From 7378f8e2fcc977bc88d133f5326fbd85a4938426 Mon Sep 17 00:00:00 2001 From: LogicDuke Date: Sun, 16 Aug 2026 20:57:56 +0200 Subject: [PATCH] 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