Track 1.2: Standalone gateway build

KNOWN-LIMITATIONS.md

@@ -91,17 +91,29 @@ There is no `fs.flock`, no `fcntl`, no `O_EXLOCK`, and no `LOCK_*` constant on a
 
 **Update (2026-08-26) — the zombie branch is now verified, not just reachable.** `pidAlive`'s `/proc`-based zombie check (a dead-but-unreaped owner reads as state `Z`) had been exercised by CI on Linux but never actually asserted against a real zombie — every prior test only ran it against live, non-zombie processes. `tests/state-store/pidalive-zombie/` closes that specific gap with a fixture that forges a genuine, self-verified Linux zombie (a `python3 os.fork()` child held unreaped) and asserts `pidAlive` returns `false` against it; see `.plans/v0.5.0/PIDALIVE-ZOMBIE-TEST-TRD-2026-08-24.md` for the design. This closes evidence for that one branch of `pidAlive` — it does not change the pid-reuse-across-namespaces or mtime-vs-wall-clock approximations described above, which remain.
 
-## 9. The MCP shim seals a session it is handed — it does not capture live traffic
+## 9. Three of the shim's four capture modes remain unbuilt — the local-proxy mode now exists
 
-`scripts/gsa-mcp-shim.js` (`sealBoundaryBundle`) takes an already-assembled `session` object — `initialize`, the granted `tools[]`, and the `calls[]` already made — and maps it into a signed boundary-tier (profile A) attestation bundle. That is the whole of what exists: hashing, tracing, and sealing data that is passed in. **Nothing produces that `session` object from a live MCP connection.**
+`scripts/gsa-mcp-shim.js` (`sealBoundaryBundle`) takes an already-assembled `session` object — `initialize`, the granted `tools[]`, and the `calls[]` already made — and maps it into a signed boundary-tier (profile A) attestation bundle. That contract is unchanged and still narrow: the shim itself never observes an MCP connection directly, only the `session` shape it is handed.
 
-The design doc ([`.plans/v0.3.0/graphsmith-v0.3.0-mcp-attestation-shim-design.md`](.plans/v0.3.0/graphsmith-v0.3.0-mcp-attestation-shim-design.md), §4) describes four deployment modes for capturing real traffic: a local proxy sitting between an MCP client and its servers, a client-side plugin hooking an agent's MCP middleware, server-side middleware wrapping a tool server, and a gateway integration for enterprise MCP gateways. **None of the four exist in code.** There is no JSON-RPC interceptor, no stdio wrapper, no HTTP reverse proxy, and no gateway-attachment point anywhere in the tree — confirmed by grepping the current source for `gateway`/`proxy`/`interceptor`: the only hits are an unrelated word-count comment and a JS `Proxy`-trap comment, neither part of MCP capture.
+**Update (2026-09-04) — deployment mode 1 (local proxy) is now built.** The design doc (`.plans/v0.3.0/graphsmith-v0.3.0-mcp-attestation-shim-design.md`, §4 -- **not present in this reviewed tree**; referenced here for historical continuity with mode 1's own design lineage, not as a resolvable link) describes four ways to produce that `session` object from a live MCP connection: a local proxy sitting between an MCP client and its servers, a client-side plugin hooking an agent's own MCP middleware, server-side middleware wrapping a tool server, and an integration point inside an enterprise MCP gateway. `scripts/gateway/` (`gateway.js`, `proxy.js`, `downstream.js`, `agent-transport.js`, `session.js`) is deployment mode 1: it sits between an agent and one or more real downstream MCP servers, speaks both legs of the protocol itself, builds the `session` object from the live traffic it proxies, and calls `chain.appendSession` (which calls `sealBoundaryBundle`) when each agent connection closes. See the Standalone Gateway TRD (`.plans/v0.5.0/STANDALONE-GATEWAY-TRD-2026-08-22.md` -- **not present in this reviewed tree**, same caveat as above) for its design and section 10 below for that gateway's own residual scope limit.
 
-**What this costs, precisely.** A caller who wants a real boundary attestation for a live MCP session must build the capture themselves — record `initialize`, `tools/list`, and every `tools/call` into the `session` shape the shim expects — before `sealBoundaryBundle` can do anything. The shim's own selftest (`--selftest` in the same file) demonstrates this: it hand-constructs a `session` literal in the test rather than deriving one from a running MCP exchange, because there is no code path that would derive one.
+**What still doesn't exist.** Modes 2–4 — a client-side plugin hooking an agent's own MCP middleware, server-side middleware wrapping a tool server, and an attachment point inside a THIRD-PARTY enterprise MCP gateway (distinct from this repo's own standalone one) — remain unbuilt. A caller who cannot or does not want to run this repo's own gateway process in front of their MCP traffic still has no capture path and must assemble the `session` object themselves, exactly as before this update.
 
-*Control:* the shim's contract is narrow and honestly scoped — it never claims to observe anything beyond the `session` object it is given (the file's own header comment states the boundary-only, profile-A-never-full-profiles limit), and the produced bundle's `decision_record.md` states plainly that the agent's plan was not observed. There is no false "captured live" claim anywhere in the emitted bundle.
+*Control:* the shim's contract is narrow and honestly scoped — it never claims to observe anything beyond the `session` object it is given (the file's own header comment states the boundary-only, profile-A-never-full-profiles limit), and the produced bundle's `decision_record.md` states plainly that the agent's plan was not observed. There is no false "captured live" claim anywhere in the emitted bundle, and this document no longer claims zero capture paths exist now that one does.
 
-**What would be needed to do it properly:** implement one of the four deployment modes in §4 of the design doc — most naturally the local proxy, since it needs no changes to the agent or to any MCP server. That is unbuilt work, not a documentation gap.
+**What would be needed to do it properly:** implement one of the remaining three deployment modes in §4 of the design doc, for callers who need capture without running this repo's own gateway process. That is unbuilt work, not a documentation gap.
+
+## 10. The standalone gateway's HTTP agent sessions are keyed by an explicit session ID, with a bounded idle-timeout lifecycle (updated 2026-09-08)
+
+**Superseded.** Until 2026-09-08 this section documented that `scripts/gateway/agent-transport.js`'s agent-facing HTTP listener identified a session by the underlying TCP socket (`req.socket`), and recorded a 2026-09-04 board decision to deliberately NOT build anything past that. Paul asked, informally, whether the HTTP transport should carry an explicit session identifier instead -- citing the MCP streamable-HTTP spec's own `Mcp-Session-Id` convention -- and said yes. Before building, this project sought a second opinion from an external panel of five non-Anthropic frontier models (openai/gpt-6-astra, x-ai/grok-4.5, google/gemini-3.1-pro-preview, deepseek/deepseek-v3.2, qwen/qwen3-max) on what scope was actually correct, since "yes" was compatible with a small labeling change or a much larger reconnect/resume rewrite. 4 of 5 recommended a socket-scoped ID that only fixes the naming/observability problem; x-ai/grok-4.5 dissented, arguing that leaves the actual pooling-proxy defect (below) unfixed and that a *coherent* minimal HTTP session model is not much more code. Paul chose grok-4.5's design. Full brief and all five raw responses: this project's decision log, entry "2026-09-08 -- external panel: HTTP agent session identity."
+
+**What's implemented now.** Sessions are keyed by an explicit, server-minted `Mcp-Session-Id` (128 random bits), minted on a header-less `initialize` and returned on the response header. Every later request on that session must echo the header; an unrecognized/expired ID gets 404. A session ends on an explicit `DELETE` (204), after 30 minutes of inactivity (fixed for now -- not yet a config field, see `scripts/gateway/agent-transport.js`'s own header comment on why), or when the gateway process shuts down (`gateway.js#stop` already force-closes every session still open in `proxy.sessions`, unconditionally). The TCP socket that happened to carry a given request is no longer part of session identity at all -- this is still `session_boundary: "connection"` (the schema's only implemented value; `"time_window"` is still rejected at startup), just with "connection" now meaning "this MCP session," not "this TCP socket."
+
+**What this fixes.** A connection-pooling reverse proxy multiplexing several distinct agents over one shared backend socket can no longer corrupt session identity (identity no longer comes from the socket at all), and one well-behaved agent whose HTTP client rotates connections mid-session (a recycled keep-alive socket, a client-side reconnect) no longer loses its already-`initialize`d session for a reason outside its control.
+
+**What this deliberately still does NOT do -- disclosed, not hidden.** This is not full HTTP session resumption. There is no cross-process session store (a session dies with the gateway process, same as before), no session replay/recovery after a crash, and no configurable idle-timeout window yet. An agent that vanishes uncleanly (crash, network partition, no `DELETE`) now leaves its session open -- and counted in `active_sessions`, and un-sealed in the audit chain -- for up to the 30-minute idle window, instead of the near-instant cleanup the old socket-close handler gave for free; that is the deliberate trade for no longer conflating "this TCP connection ended" with "this agent is done." Building the fuller reconnect/replay/multi-node session store that a real `time_window` boundary would eventually need remains out of scope until a concrete deployment defines that lifecycle for real -- the same discipline the original 2026-09-04 decision applied, now to a narrower remaining gap.
+
+*Control:* documented here, in `scripts/gateway/agent-transport.js`'s own header comment, and in the project's decision log (external panel brief + all five responses).
 
 ---
 *This document is publication-hygiene clean. See also the worked offline-verifier transcript in [`docs/examples/offline-verify.md`](docs/examples/offline-verify.md).*