From 4f2f34c6fd04f3787a5e74712f3fcbb6c97461b0 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Tue, 7 Jul 2026 10:25:29 +0800 Subject: [PATCH] docs: BashRunResult timedOut/aborted are first-cause, not independent (codex round 3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The timeout convergence on this branch made timedOut/aborted mutually exclusive — one fused deadline reports the single cause that first cut the command short — as the timeout-library RFC documents deliberately. The seam type's JSDoc still described the old independent latches, so a consumer could code the wrong contract. State first-cause classification on both fields and cross-link the RFC. Docs-only; the code already matches. --- packages/bash/bash/src/types.ts | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/packages/bash/bash/src/types.ts b/packages/bash/bash/src/types.ts index 9acd5c7cb7..457ca87d9e 100644 --- a/packages/bash/bash/src/types.ts +++ b/packages/bash/bash/src/types.ts @@ -131,9 +131,19 @@ export interface BashRunResult { exitCode: number | null /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */ signal: NodeJS.Signals | null - /** True when the executor's own timeout killed the command. */ + /** + * True when the executor's own timeout was the FIRST cause to cut the command + * short. Mutually exclusive with {@link aborted}: one fused deadline drives + * both the timeout and the caller's cancellation, so a timeout and an abort + * racing before process close report the single first-abort cause, not both + * (see the [timeout-library RFC](../../../../docs/rfc/implemented/architecture/2026-07-06-timeout-deadline-library.md)). + */ timedOut: boolean - /** True when the caller's AbortSignal killed the command. */ + /** + * True when the caller's `AbortSignal` was the FIRST cause to kill the command + * (and it was not the executor's own timeout). Mutually exclusive with + * {@link timedOut} — see there for the first-cause classification. + */ aborted: boolean /** The effective timeout applied to this run (after defaulting/capping). */ timeoutMs: number