From ff76c8149cd1d43dd910aa30a8f928675f112220 Mon Sep 17 00:00:00 2001 From: LogicDuke Date: Sun, 16 Aug 2026 18:33:22 +0200 Subject: [PATCH 1/3] docs(pr010): clarify process transport contract --- .../architecture/010-commander-claude-bridge.md | 10 +++++++--- src/adapters/process-transport.ts | 17 +++++++++++------ 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/architecture/010-commander-claude-bridge.md b/docs/architecture/010-commander-claude-bridge.md index 9de1cf5..f3c0837 100644 --- a/docs/architecture/010-commander-claude-bridge.md +++ b/docs/architecture/010-commander-claude-bridge.md @@ -161,9 +161,13 @@ forced settlement also destroys the local stdout and stderr pipe ends, and stdout or stderr read errors are contained until the child close path reports the provider-neutral outcome. The function resolves exactly one frozen record on every validation, spawn, I/O, timeout, cancellation, overflow, termination, -and close path. It never rejects. Catches wrap only defined operational -failures, so a programmer defect still surfaces as a defect rather than being -laundered into a failure code. +and close path. 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. ## Termination is qualified, and the limit is disclosed diff --git a/src/adapters/process-transport.ts b/src/adapters/process-transport.ts index 40b7919..f7516cf 100644 --- a/src/adapters/process-transport.ts +++ b/src/adapters/process-transport.ts @@ -599,12 +599,17 @@ async function terminate( /** * Run one process exchange. * - * **Total.** Resolves to exactly one frozen {@link AgentExchange} on every - * validation, spawn, I/O, timeout, cancellation, overflow, termination, and - * close path. It never rejects and never throws by design. Catches are placed - * only around defined operational failures — `spawn`, `kill`, a broken stdin - * pipe, a hostile `AbortSignal` getter — so a programmer defect still surfaces - * as a defect rather than being laundered into a failure code. + * **Defined operational results.** Resolves to exactly one frozen + * {@link AgentExchange} on every validation, spawn, I/O, timeout, + * cancellation, overflow, termination, and close path. 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. * * **Deterministic precedence.** Every detected terminal cause is compared with * `TERMINAL_CAUSE_PRECEDENCE`; callback arrival order cannot demote a stronger From 7378f8e2fcc977bc88d133f5326fbd85a4938426 Mon Sep 17 00:00:00 2001 From: LogicDuke Date: Sun, 16 Aug 2026 20:57:56 +0200 Subject: [PATCH 2/3] docs(pr022): qualify process transport exchange outcomes --- .../010-commander-claude-bridge.md | 20 ++++++++-------- src/adapters/process-transport.ts | 23 ++++++++++--------- 2 files changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/architecture/010-commander-claude-bridge.md b/docs/architecture/010-commander-claude-bridge.md index f3c0837..e53bd12 100644 --- a/docs/architecture/010-commander-claude-bridge.md +++ b/docs/architecture/010-commander-claude-bridge.md @@ -159,15 +159,17 @@ to `unknown`. Every listener, timer, and abort handler is removed on every settle path. A forced settlement also destroys the local stdout and stderr pipe ends, and stdout or stderr read errors are contained until the child close path reports -the provider-neutral outcome. The function resolves exactly one frozen record -on every validation, spawn, I/O, timeout, cancellation, overflow, termination, -and close path. 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. +the provider-neutral outcome. For the defined operational results the transport +represents as exchange outcomes — validation, spawn, I/O, timeout, +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. ## Termination is qualified, and the limit is disclosed diff --git a/src/adapters/process-transport.ts b/src/adapters/process-transport.ts index f7516cf..05d7f1e 100644 --- a/src/adapters/process-transport.ts +++ b/src/adapters/process-transport.ts @@ -599,17 +599,18 @@ async function terminate( /** * Run one process exchange. * - * **Defined operational results.** Resolves to exactly one frozen - * {@link AgentExchange} on every validation, spawn, I/O, timeout, - * cancellation, overflow, termination, and close path. 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. + * **Defined operational results.** For the defined operational results this + * transport represents as exchange outcomes — validation, spawn, I/O, + * timeout, cancellation, overflow, termination, and close — resolves to + * 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. * * **Deterministic precedence.** Every detected terminal cause is compared with * `TERMINAL_CAUSE_PRECEDENCE`; callback arrival order cannot demote a stronger From 87fc6b8acb0199399bfa248338fce71c228a872a Mon Sep 17 00:00:00 2001 From: LogicDuke Date: Mon, 17 Aug 2026 01:29:01 +0200 Subject: [PATCH 3/3] 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