test(gateway): RC3 executor-residue gates + tool-submit context-mismatch warning net

[Kyzcreig]

Follow-up to #271, driven by fresh live evidence (foreign session identity in subprocess env with the #271 entry warning silent).

What this proves: deterministic RC3 tests poison a reused size-1 worker thread with a foreign binding and assert on the real subprocess-env surface from inside the worker — both wrapped seams (gateway _run_in_executor_with_context, tool propagate_context_to_thread) correctly override residue. Ruled out.

What this adds: a log-only mismatch warning at the tool-batch submit seam (agent._gateway_session_key vs bound key) — the exact point tonight's leak was visible. Next live occurrence self-identifies with both keys.

Honest status: the live mechanism remains unexplained; diagnosis doc names the remaining suspects (shared LocalEnvironment snapshot, unwrapped submit). This PR ships the gates + the net, not a claimed fix.

[greptile-apps]

Greptile Summary

Adds two deterministic RC3 tests that poison a size-1 pool thread with a foreign ContextVar binding and assert the gateway and tool-thread ctx.run wrappers correctly override that residue, ruling out both wrapped seams as the live leak mechanism. A log-only _warn_on_tool_submit_session_mismatch diagnostic is inserted at the tool-batch submit point in execute_tool_calls_concurrent, comparing the bound HERMES_SESSION_KEY against agent._gateway_session_key so the next live occurrence self-identifies.

• agent/tool_executor.py gains _warn_on_tool_submit_session_mismatch: ImportError is silently skipped, unexpected exceptions now emit a debug-level trace (addressing prior review concern) rather than vanishing silently, and a warning fires only when the keys genuinely differ.
• tests/gateway/test_session_context_inheritance.py adds three tests covering the gateway executor bidirectional residue override, the tool-thread wrapper bidirectional residue override, and the new warning function's mismatch branch.
• Three docs/sync/ files are committed for traceability of the diagnosis, evidence pack, and change log.

Confidence Score: 5/5

Safe to merge. The production change is a log-only diagnostic that cannot affect tool dispatch correctness, and the new tests are hermetic.

The only production-code change is _warn_on_tool_submit_session_mismatch, which returns early or emits log output and never affects control flow. The new tests are isolated with the existing _isolate_session_context autouse fixture. No data path, session binding, or executor lifecycle is modified.

No files require special attention. The test file is the natural place to extend coverage but the gap does not affect production behavior.

Important Files Changed

Filename	Overview
agent/tool_executor.py	Adds _warn_on_tool_submit_session_mismatch diagnostic and wires it into execute_tool_calls_concurrent; exception handling is now visible (debug log) rather than silent, and the call site is correctly placed before the executor is created.
tests/gateway/test_session_context_inheritance.py	Three new tests: two bidirectional residue-override probes (gateway executor and tool-thread wrapper), one warning-net unit. The mismatch warning test only exercises the mismatch branch; the matched-key complement is absent (flagged in previous review thread).
docs/sync/2026-07-10-ctx-residue-DIAGNOSIS.md	Diagnosis document recording root-cause investigation, re-grounded line anchors, and mechanism description; no code changes.
docs/sync/2026-07-10-ctx-residue-CHANGES.md	Changes summary listing code modifications, test results, and outstanding work; no code changes.
docs/sync/CTX-RESIDUE-BRIEF.md	Evidence pack and build brief committed for traceability; no code changes.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant AT as Async Task
    participant GW as GatewayRunner._run_in_executor_with_context
    participant WT as Worker Thread
    participant TE as execute_tool_calls_concurrent
    participant WF as _warn_on_tool_submit_session_mismatch
    participant TW as Tool Worker Thread

    AT->>GW: copy_context() + ctx.run
    GW->>WT: ctx.run overrides residue
    WT->>TE: runnable_calls assembled
    TE->>WF: check bound key vs agent._gateway_session_key
    alt "bound != expected"
        WF-->>TE: logger.warning mismatch
    else "bound == expected"
        WF-->>TE: silent
    end
    TE->>TW: propagate_context_to_thread
    TW->>TW: subprocess env injected

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant AT as Async Task
    participant GW as GatewayRunner._run_in_executor_with_context
    participant WT as Worker Thread
    participant TE as execute_tool_calls_concurrent
    participant WF as _warn_on_tool_submit_session_mismatch
    participant TW as Tool Worker Thread

    AT->>GW: copy_context() + ctx.run
    GW->>WT: ctx.run overrides residue
    WT->>TE: runnable_calls assembled
    TE->>WF: check bound key vs agent._gateway_session_key
    alt "bound != expected"
        WF-->>TE: logger.warning mismatch
    else "bound == expected"
        WF-->>TE: silent
    end
    TE->>TW: propagate_context_to_thread
    TW->>TW: subprocess env injected

Loading

_{Reviews (3): Last reviewed commit: "fix(tool-executor): don't let the mismat..." | Re-trigger Greptile}