docs: BashRunResult timedOut/aborted are first-cause, not independent (codex round 3)

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.
This commit is contained in:
Dudu-0223
2026-07-07 10:25:29 +08:00
parent f4acb1cf05
commit 4f2f34c6fd

View File

@@ -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