From 87fc6b8acb0199399bfa248338fce71c228a872a Mon Sep 17 00:00:00 2001 From: LogicDuke Date: Mon, 17 Aug 2026 01:29:01 +0200 Subject: [PATCH] docs(pr022): clarify hardening cleanup contract --- docs/architecture/010-commander-claude-bridge.md | 13 ++++++++----- src/adapters/process-transport.ts | 15 +++++++++------ 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/architecture/010-commander-claude-bridge.md b/docs/architecture/010-commander-claude-bridge.md index e53bd12..57beecb 100644 --- a/docs/architecture/010-commander-claude-bridge.md +++ b/docs/architecture/010-commander-claude-bridge.md @@ -165,11 +165,14 @@ cancellation, overflow, termination, and close — the function resolves exactly one frozen record. Nothing outside that handled set is promised to resolve. It rejects deliberately, rather than reporting an outcome, when mandatory post-spawn child-dispatch hardening cannot be established: the transport runs -its bounded, platform-qualified termination procedure, tears down its pipes and -listeners, and then rejects. That rejection is not `SPAWN_FAILED` and is not an -exchange outcome at all. Catches wrap only defined operational failures, so a -programmer or security-boundary defect still surfaces as a defect rather than -being laundered into a failure code. +its bounded, platform-qualified termination procedure, destroys the local +stdout and stderr ends, clears the child's listeners, re-arms the spawn-failure +absorber over the cleared handle, and then rejects. The local stdin end is left +as it is, and termination stays a request rather than a completion guarantee. +That rejection is not `SPAWN_FAILED` and is not an exchange outcome at all. +Catches wrap only defined operational failures, so a programmer or +security-boundary defect still surfaces as a defect rather than being laundered +into a failure code. ## Termination is qualified, and the limit is disclosed diff --git a/src/adapters/process-transport.ts b/src/adapters/process-transport.ts index 05d7f1e..7c4c054 100644 --- a/src/adapters/process-transport.ts +++ b/src/adapters/process-transport.ts @@ -605,12 +605,15 @@ async function terminate( * exactly one frozen {@link AgentExchange}. Nothing outside that handled set * is promised to resolve. Deliberate fail-closed rejection: when mandatory * post-spawn child-dispatch hardening cannot be established, the transport - * runs its bounded, platform-qualified termination procedure, tears down its - * pipes and listeners, and then rejects. That rejection is not `SPAWN_FAILED` - * and is not an `AgentExchange` outcome at all. Catches are placed only around - * defined operational failures — `spawn`, `kill`, a broken stdin pipe, a - * hostile `AbortSignal` getter — so a programmer or security-boundary defect - * still surfaces as a defect rather than being laundered into a failure code. + * runs its bounded, platform-qualified termination procedure, destroys the + * local stdout and stderr ends, clears the child's listeners, re-arms the + * spawn-failure absorber over the cleared handle, and then rejects. The local + * stdin end is left as it is, and termination stays a request rather than a + * completion guarantee. That rejection is not `SPAWN_FAILED` and is not an + * `AgentExchange` outcome at all. Catches are placed only around defined + * operational failures — `spawn`, `kill`, a broken stdin pipe, a hostile + * `AbortSignal` getter — so a programmer or security-boundary defect still + * surfaces as a defect rather than being laundered into a failure code. * * **Deterministic precedence.** Every detected terminal cause is compared with * `TERMINAL_CAUSE_PRECEDENCE`; callback arrival order cannot demote a stronger