@sema-agent/core 7.32.0 → 7.33.0

package/dist/brain/timeout.d.ts

@@ -1,14 +1,20 @@
 import type { StreamFn } from "../internal/llm.js";
 /**
- * Tiered timeouts (1.38.1, design/17 §5B). The task-level `timeoutSec` only bounds the *whole* run;
- * it can't tell apart a gateway that never accepts the connection from one that accepts it, opens the
- * SSE stream, then hangs forever without emitting a token (the most common gateway-stall symptom).
- * Two finer levels close that gap, each retryable as a transient `network` failure:
+ * Tiered timeouts (design/17 §5B; re-cut along the segments of a call in 7.33.0). The task-level
+ * `timeoutSec` only bounds the *whole* run; it cannot tell apart a gateway that never completes the
+ * handshake, one that accepts the request and then holds the response headers while it works, one
+ * that opens the stream and never emits a token, and one that goes quiet mid-answer. Four clocks,
+ * one per segment, each named for the segment it bounds:
  *
- * - **connect**: `fetch` hasn't returned response headers in time.
- * - **first-token**: the SSE stream is open but no content delta has arrived (see brain read loops).
+ * - **connect**: TCP + TLS establishment inside `fetch` — the transport's own clock (undici's 10s by
+ *   default), tuned on the process dispatcher the host installs; not a knob here (`transport.ts`).
+ * - **first-byte**: the `fetch()` call → response headers. A stall here is this process cancelling
+ *   its own request at a deadline it chose, and is announced as such.
+ * - **first-token**: headers → the first content delta (a thinking delta counts).
+ * - **idle**: silence between deltas once output has started.
  *
- * Both default to `undefined` (disabled) so existing behavior is unchanged.
+ * Every field resolves through the same chain: construction config (an explicit `0` is OFF) >
+ * per-call advisory (`StreamOptions.stallTimeouts`) > the engine default constant below.
  */
 /**
  * The largest delay a host timer can actually wait for. Past this `setTimeout` does not schedule far in
@@ -28,55 +34,107 @@ export declare const MAX_TIMER_DELAY_MS = 2147483647;
  */
 export declare function resolveStallTimeoutMs(value: number | undefined, knob: string): number | undefined;
 /**
- * The engine's ADVISORY per-call stall watchdog values (`StreamOptions.stallTimeouts`), supplied on
- * every provider call. They are a GUARDRAIL, not part of any budget lane: `BrainTimeoutConfig` defaults
- * every watchdog to OFF, so without these an in-flight call that goes silent is bounded by nothing
- * finer than the hour-scale {@link BRAIN_CALL_GUARDRAIL_DEFAULT_MS} (a measured production frame sat
- * 680s with ZERO deltas). A silent stream is never worth more than these bounds, whether or not the
- * task declared a time limit. All three surface as the brain's existing retryable `network` stall
- * class (design/124 tier C retries a zero-content cut, so a transient gateway hang still recovers). 量纲:
- *   - connect 30s: bounds the fetch→response-HEADERS wait — the one segment every post-headers
- *     watchdog is blind to. On a streaming API the model's time is spent AFTER headers, so 30s with
- *     none at all is a hung gateway, not a slow model.
+ * The engine's DEFAULT watchdog values, one per segment of a model call — the third and last level of
+ * the chain every brain reads (`BrainTimeoutConfig` field > per-call advisory `StreamOptions.stallTimeouts`
+ * > these). The Runner supplies these same numbers as the advisory on every call, so a Brain supplied by
+ * the deployment (BYOM) is told what the engine would arm; a first-party brain arms them itself when
+ * neither a config field nor an advisory names the segment. A silent call is therefore always bounded by
+ * something finer than the hour-scale {@link BRAIN_CALL_GUARDRAIL_DEFAULT_MS} (a measured production
+ * frame once sat 680s with ZERO deltas) unless a deployment switched the watchdog for that segment off
+ * by name — an explicit `0` is the only spelling of OFF. The TCP + TLS connect has no row here: it is
+ * the transport's own clock (`transport.ts`), not a segment the engine can observe. 量纲:
+ *   - first-byte 300s: the `fetch()` call → response headers. A self-hosted gateway that runs its
+ *     prefill BEFORE writing headers is silent here for minutes and healthy; the 30s "connect" clock
+ *     this replaces cut that prefill and re-sent the same body ten times. 300s is the reference
+ *     implementation's window for a non-first-party route; the window grows with the request body
+ *     ({@link firstByteWindow}) and the one retry is widened ({@link FIRST_BYTE_RETRY_WINDOW_FACTOR}).
  *   - first-token 600s: bounds the headers→first-delta wait, NOT the model's thought (the first
- *     THINKING delta already counts as the first token, design/17 O5 — see
- *     {@link BrainTimeoutConfig.firstTokenTimeoutMs}), so a slow reasoner is safe. A minutes-scale
- *     bound would be FALSE for a real class of backend: a self-hosted server working through a long
- *     prefill emits nothing at all for 2–3 minutes, and cancelling it burns the prefill and re-sends
- *     a request that burns it again — a guardrail whose reason is false for healthy traffic is not a
- *     guardrail. 600s is the same order of magnitude as the reference implementation's own request
- *     timeout, and the shapes this bound exists for (a gateway that accepted the request and then
- *     died) are still caught, just later; the task's own hard abort remains the outer bound.
- *     HONEST CEILING (measured): this watchdog is not the only clock over a
- *     byte-silent stream, so 600s is the bound this engine ASKS FOR, not the silence a deployment is
- *     necessarily granted. On Node's own `fetch` — the default transport for both adapters, and the
- *     one a deployment gets by supplying no `fetchImpl` — undici destroys a body that has produced no
- *     bytes for 300s (`bodyTimeout`, default `300e3`), so byte-silence past 300s ends the attempt
- *     there and arrives as a read rejection reported `transport`. That report is CORRECT (the
- *     transport really did cut it) and the seat to change it exists: `fetchImpl` on both brain configs
- *     takes any `fetch`, so a deployment needing the full 600s passes one built on an undici
- *     `Agent`/`Dispatcher` with its own `bodyTimeout`. Named here so the next reader who measures ~300s
- *     of tolerance does not conclude this number is a lie.
- *     {@link import("../orchestration/workflow.js").WORKFLOW_AGENT_STALL_MS} is DERIVED from
- *     {@link STALL_CONNECT_MS} + this value, so the coarse agent-restart cannot sit UNDER a single
- *     silent provider call. Move this number and that one follows. It is a floor, not
- *     a guarantee of ordering — see that constant's own comment for the cases that still invert.
- *   - idle 90s: mid-stream silence after output started — a healthy stream emits steadily
- *     (comfortably above any provider keep-alive cadence).
+ *     THINKING delta already counts as the first token, design/17 O5), so a slow reasoner is safe. A
+ *     minutes-scale bound is FALSE for a self-hosted server working through a long prefill AFTER
+ *     headers: it emits nothing for 2–3 minutes while healthy, and cancelling it burns the prefill and
+ *     re-sends a request that burns it again. The default transport keeps NO clock over this segment
+ *     (the request carries `bodyTimeout: 0`), so this number is the bound actually granted.
+ *     {@link import("../orchestration/workflow.js").WORKFLOW_AGENT_STALL_MS} is DERIVED from the
+ *     first-byte lane at {@link STALL_FIRST_BYTE_MS} ({@link firstByteLaneKnobMs}) + this value, so the coarse agent-restart cannot sit UNDER a single
+ *     silent provider call (a floor, not a guarantee of ordering — see that constant's comment).
+ *   - idle 300s: mid-stream silence after output started — the reference implementation's idle floor
+ *     (a self-hosted server can stall for minutes between deltas while a server-side tool runs; a provider
+ *     keep-alive comment is not a delta and does not count).
  * ADVISORY: a brain whose construction-time {@link BrainTimeoutConfig} sets the corresponding field
  * keeps it (deployment sovereignty; see the `StreamOptions.stallTimeouts` priority chain).
  */
-export declare const STALL_CONNECT_MS = 30000;
+export declare const STALL_FIRST_BYTE_MS = 300000;
 export declare const STALL_FIRST_TOKEN_MS = 600000;
-export declare const STALL_IDLE_MS = 90000;
+export declare const STALL_IDLE_MS = 300000;
+/**
+ * The retired names of the header-wait bound, each with the name that replaced it: the construction key and
+ * the per-call advisory key. The type face no longer has them, but a type only refuses a LITERAL — a
+ * spread object (`{ ...timeouts }`) or a JS caller still delivers the key, and a knob that arrives and is
+ * then ignored is a deployment setting silently doing nothing. So their arrival is refused, naming the
+ * replacement: a tripwire, not a second spelling (nothing reads the value).
+ */
+export declare const RETIRED_TIMEOUT_KNOBS: {
+    readonly construction: {
+        readonly connectTimeoutMs: "firstByteTimeoutMs";
+    };
+    readonly advisory: {
+        readonly connectMs: "firstByteMs";
+    };
+};
+/** Refuse a retired timeout key present on `holder` (see {@link RETIRED_TIMEOUT_KNOBS}); `where` names the
+ *  object in the message (`"createOpenAIBrain config"`, `"StreamOptions.stallTimeouts"`). */
+export declare function refuseRetiredTimeoutKnobs(holder: object | undefined, level: keyof typeof RETIRED_TIMEOUT_KNOBS, where: string): void;
+/** The first-byte window grows with the request body: one second per this many bytes, rounded up (the
+ *  reference implementation's allowance) — a large context on a slow uplink is still UPLOADING when a
+ *  fixed window would call the gateway silent. */
+export declare const FIRST_BYTE_UPLOAD_BYTES_PER_SECOND = 32768;
+/** A first-byte stall is re-sent at most this many times, out of its OWN budget rather than
+ *  `maxRetries` (the reference implementation: "normally one retry, not the session budget"); the shared
+ *  ladder counts transport failures, and this is not one. */
+export declare const FIRST_BYTE_RETRY_BUDGET = 1;
+/** The retry's knob is the first times this — the reference implementation widens its retry to a second
+ *  knob's default (599s against a 300s first window); one knob here keeps that ratio instead. */
+export declare const FIRST_BYTE_RETRY_WINDOW_FACTOR = 2;
+/** The ONE resolution every watchdog knob reads: construction config (an explicit `0` is OFF) > per-call
+ *  advisory > the engine default. A bad number at either level is refused ({@link resolveStallTimeoutMs});
+ *  only an ABSENT value falls through. */
+export declare function resolveWatchdogMs(configured: number | undefined, advisory: number | undefined, engineDefault: number, knob: string): number;
+/** One armed first-byte window, with the two numbers its announcement quotes. */
+export interface FirstByteWindow {
+    /** The knob's value for THIS attempt (the configured value, widened on the retry). */
+    knobMs: number;
+    /** The upload allowance added for the request body, ms (0 for an empty body). */
+    allowanceMs: number;
+    /** What is actually armed: `knobMs + allowanceMs`, capped at {@link MAX_TIMER_DELAY_MS}. `0` = off. */
+    windowMs: number;
+}
+/** The first-byte window for one attempt; `retryIndex` = first-byte stalls already suffered (0 first),
+ *  each widening the knob by {@link FIRST_BYTE_RETRY_WINDOW_FACTOR}. A knob of `0` (OFF) stays off. */
+export declare function firstByteWindow(knobMs: number | undefined, bodyBytes: number, retryIndex: number): FirstByteWindow;
+/**
+ * The most a first-byte lane armed at `knobMs` waits on the gateway in total before it gives up: the probe
+ * window and every widened retry its budget allows ({@link FIRST_BYTE_RETRY_BUDGET},
+ * {@link FIRST_BYTE_RETRY_WINDOW_FACTOR}) — read off {@link firstByteWindow}, the same function that arms
+ * each attempt, so the sum cannot drift from what is armed. The knob part only: the upload allowance
+ * depends on the request body and the backoff between attempts is not a wait on the gateway, so the lane's
+ * real wall time is this plus both — a LOWER bound.
+ */
+export declare function firstByteLaneKnobMs(knobMs: number): number;
 export interface BrainTimeoutConfig {
-    /** Abort the request if `fetch` doesn't return response headers within this many ms. Retryable. */
-    connectTimeoutMs?: number;
+    /**
+     * `fetch()` call → response headers, ms: the window a gateway has to START answering (until 7.33.0 a
+     * knob named `connectTimeoutMs` bounded this wait; it is gone — the connect clock is the transport's). Absent ⇒
+     * {@link STALL_FIRST_BYTE_MS}; the armed window grows with the request body ({@link firstByteWindow});
+     * a stall earns ONE retry at a widened window out of its own budget, then fails naming this knob.
+     * Fires as a `stall` (this process cancelled its own request), never as a transport fault. `0` ⇒ off.
+     */
+    firstByteTimeoutMs?: number;
     /**
      * After the stream opens, cancel it if no content delta (text / thinking / tool input) arrives
      * within this many ms → `BrainError("network", "first-token timeout")`. For reasoning models the
      * **first thinking delta also counts** as the first token, so a long-thinking model isn't killed
-     * for being slow to its first *visible* word (design/17 O5).
+     * for being slow to its first *visible* word (design/17 O5). Absent ⇒ {@link STALL_FIRST_TOKEN_MS};
+     * `0` ⇒ off.
      */
     firstTokenTimeoutMs?: number;
     /**
@@ -84,18 +142,19 @@ export interface BrainTimeoutConfig {
      * After the first delta, re-armed on every delta; if the stream then goes silent for this many ms
      * (a gateway that hung mid-output) → `reader.cancel()` + `BrainError("network", "stream idle timeout")`.
      * Complements `firstTokenTimeoutMs`: that one tolerates a long *first* token (reasoning), this one
-     * catches a stall *after* output has started, where a healthy stream emits steadily. Default off.
+     * catches a stall *after* output has started, where a healthy stream emits steadily. Absent ⇒
+     * {@link STALL_IDLE_MS}; `0` ⇒ off.
      */
     idleTimeoutMs?: number;
 }
 /**
- * A per-fetch-attempt abort controller that fires on a connect timeout while still forwarding an
+ * A per-attempt abort controller that fires at the first-byte deadline while still forwarding an
  * outer (task) abort. The returned `signal` governs the **whole** request including the streamed body
- * — so once headers arrive, call `clearTimer()` (NOT `dispose()`) to stop the connect timer while
- * keeping the outer-abort link alive for the body read; call `dispose()` only when the request is
- * fully done or being discarded.
+ * — so once headers arrive, call `clearTimer()` (NOT `dispose()`) to stop the deadline while keeping
+ * the outer-abort link alive for the body read; call `dispose()` only when the request is fully done
+ * or being discarded.
  */
-export declare function createConnectController(connectTimeoutMs: number | undefined, outerSignal: AbortSignal | undefined): {
+export declare function createAttemptController(firstByteWindowMs: number | undefined, outerSignal: AbortSignal | undefined): {
     signal: AbortSignal;
     timedOut: () => boolean;
     clearTimer: () => void;
@@ -110,7 +169,7 @@ export declare function createConnectController(connectTimeoutMs: number | undef
  * Default ceiling on how long the ENGINE waits for a single brain call (ruled 2026-08-03: one hour).
  * Deliberately far above any legitimate call: this is a wedged-run backstop, not a latency policy —
  * a deployment that wants a tight per-call bound sets the fine tier above ({@link BrainTimeoutConfig},
- * or the advisory {@link STALL_CONNECT_MS} family the engine supplies by default). All of these clocks
+ * or the advisory {@link STALL_FIRST_BYTE_MS} family the engine supplies by default). All of these clocks
  * run in parallel with the task's own `limits.timeoutSec`; whichever expires first owns the run.
  */
 export declare const BRAIN_CALL_GUARDRAIL_DEFAULT_MS = 3600000;

package/dist/brain/timeout.js

@@ -14,10 +14,44 @@ export function resolveStallTimeoutMs(value, knob) {
     }
     return value;
 }
-export const STALL_CONNECT_MS = 30_000;
+export const STALL_FIRST_BYTE_MS = 300_000;
 export const STALL_FIRST_TOKEN_MS = 600_000;
-export const STALL_IDLE_MS = 90_000;
-export function createConnectController(connectTimeoutMs, outerSignal) {
+export const STALL_IDLE_MS = 300_000;
+export const RETIRED_TIMEOUT_KNOBS = {
+    construction: { connectTimeoutMs: "firstByteTimeoutMs" },
+    advisory: { connectMs: "firstByteMs" },
+};
+export function refuseRetiredTimeoutKnobs(holder, level, where) {
+    if (holder === undefined || holder === null)
+        return;
+    for (const [retired, replacement] of Object.entries(RETIRED_TIMEOUT_KNOBS[level])) {
+        if (!(retired in holder))
+            continue;
+        const e = new Error(`${where}: \`${retired}\` was removed in 7.33.0 and is refused rather than ignored — the fetch()→response-headers wait it bounded is \`${replacement}\` (0 = off); the TCP + TLS connect is the transport's own clock, tuned on the process dispatcher (setGlobalDispatcher(new Agent({ connect: { timeout } })))`);
+        e.code = "config.stall_timeout_retired";
+        throw e;
+    }
+}
+export const FIRST_BYTE_UPLOAD_BYTES_PER_SECOND = 32_768;
+export const FIRST_BYTE_RETRY_BUDGET = 1;
+export const FIRST_BYTE_RETRY_WINDOW_FACTOR = 2;
+export function resolveWatchdogMs(configured, advisory, engineDefault, knob) {
+    return resolveStallTimeoutMs(configured ?? advisory, knob) ?? engineDefault;
+}
+export function firstByteWindow(knobMs, bodyBytes, retryIndex) {
+    if (knobMs === undefined || knobMs <= 0)
+        return { knobMs: 0, allowanceMs: 0, windowMs: 0 };
+    const widened = knobMs * FIRST_BYTE_RETRY_WINDOW_FACTOR ** Math.max(0, retryIndex);
+    const allowanceMs = Math.ceil(Math.max(0, bodyBytes) / FIRST_BYTE_UPLOAD_BYTES_PER_SECOND) * 1000;
+    return { knobMs: widened, allowanceMs, windowMs: Math.min(widened + allowanceMs, MAX_TIMER_DELAY_MS) };
+}
+export function firstByteLaneKnobMs(knobMs) {
+    let total = 0;
+    for (let retryIndex = 0; retryIndex <= FIRST_BYTE_RETRY_BUDGET; retryIndex++)
+        total += firstByteWindow(knobMs, 0, retryIndex).knobMs;
+    return total;
+}
+export function createAttemptController(firstByteWindowMs, outerSignal) {
     const ac = new AbortController();
     let timedOut = false;
     const onAbort = () => ac.abort(outerSignal?.reason);
@@ -28,11 +62,11 @@ export function createConnectController(connectTimeoutMs, outerSignal) {
             outerSignal.addEventListener("abort", onAbort, { once: true });
     }
     let timer;
-    if (connectTimeoutMs && connectTimeoutMs > 0) {
+    if (firstByteWindowMs && firstByteWindowMs > 0) {
         timer = setTimeout(() => {
             timedOut = true;
             ac.abort();
-        }, connectTimeoutMs);
+        }, firstByteWindowMs);
     }
     const clearTimer = () => {
         if (timer)

package/dist/brain/transport.d.ts

@@ -0,0 +1,13 @@
+import { Dispatcher } from "undici";
+/**
+ * The one dispatcher every first-party brain hands its fetch: the sending members are the engine's
+ * ({@link SENDING_MEMBERS}); every other member — state, lifecycle, events — is the host's, read when
+ * accessed ({@link hostMember}), so nothing a fetch starts reading has to be added to a list here.
+ * Stateless; owns no sockets.
+ */
+export declare const ENGINE_DISPATCHER: Dispatcher;
+/** The `fetch` a brain sends its requests through: the caller's `fetchImpl` (else Node's `fetch`), each
+ *  request carrying {@link ENGINE_DISPATCHER} in its init. */
+export declare function resolveFetch(config: {
+    fetchImpl?: typeof fetch;
+}): typeof fetch;

package/dist/brain/transport.js

@@ -0,0 +1,62 @@
+import { Dispatcher, getGlobalDispatcher } from "undici";
+import UnwrapHandler from "undici/lib/handler/unwrap-handler.js";
+import WrapHandler from "undici/lib/handler/wrap-handler.js";
+function handlerApi(handler) {
+    return typeof handler.onRequestStart === "function" ? 2 : 1;
+}
+function inSlotApi(api, handler) {
+    return api === 1 ? UnwrapHandler.unwrap(handler) : WrapHandler.wrap(handler);
+}
+function slot(version) {
+    const held = Reflect.get(globalThis, Symbol.for(`undici.globalDispatcher.${String(version)}`));
+    return isDispatcher(held) ? held : undefined;
+}
+function isDispatcher(value) {
+    return typeof value === "object" && value !== null && typeof Reflect.get(value, "dispatch") === "function";
+}
+function hostDispatcher(callerApi) {
+    const own = callerApi === 2 ? slot(2) : undefined;
+    return own !== undefined ? { dispatcher: own, api: 2 } : { dispatcher: slot(1) ?? getGlobalDispatcher(), api: 1 };
+}
+function hostDispatchers() {
+    const out = [];
+    for (const d of [slot(2), slot(1), getGlobalDispatcher()])
+        if (d !== undefined && !out.includes(d))
+            out.push(d);
+    return out;
+}
+function hostMember(key) {
+    const hosts = hostDispatchers();
+    for (const host of hosts) {
+        const value = Reflect.get(host, key, host);
+        if (value)
+            return typeof value === "function" ? value.bind(host) : value;
+    }
+    const newest = hosts[0];
+    return newest === undefined ? undefined : Reflect.get(newest, key, newest);
+}
+const CALLER_API = Symbol("engine.callerDispatcherApi");
+class EngineDispatcher extends Dispatcher {
+    dispatch(options, handler) {
+        const { [CALLER_API]: callerApi, ...rest } = options;
+        const host = hostDispatcher(callerApi ?? handlerApi(handler));
+        return host.dispatcher.dispatch({ ...rest, headersTimeout: 0, bodyTimeout: 0 }, inSlotApi(host.api, handler));
+    }
+    compose(...interceptors) {
+        const composed = super.compose(...interceptors);
+        const chain = composed.dispatch;
+        const enter = (options, handler) => {
+            const stamped = { ...options, [CALLER_API]: options[CALLER_API] ?? handlerApi(handler) };
+            return chain(stamped, handler);
+        };
+        return new Proxy(composed, { get: (target, key, receiver) => (key === "dispatch" ? enter : Reflect.get(target, key, receiver)) });
+    }
+}
+const SENDING_MEMBERS = new Set(Reflect.ownKeys(Dispatcher.prototype).filter((key) => key !== "constructor" && key !== "close" && key !== "destroy"));
+export const ENGINE_DISPATCHER = new Proxy(new EngineDispatcher(), {
+    get: (engine, key, standIn) => (SENDING_MEMBERS.has(key) ? Reflect.get(engine, key, standIn) : hostMember(key)),
+});
+export function resolveFetch(config) {
+    const inner = config.fetchImpl ?? fetch;
+    return (input, init) => inner(input, { ...init, dispatcher: ENGINE_DISPATCHER });
+}

package/dist/core/background-shell.d.ts

@@ -153,9 +153,10 @@ export interface BackgroundRetainLanes {
 }
 /**
  * THE retain predicate — "is this background process kept alive past the automatic reaps?" Every face that
- * answers it calls this function (Bash description + receipts, Monitor receipt, the row stamp, teardown settle
- * and dispose, park-only sweeps, session reap, the exit hard face, the listing). Any declared lane retains,
- * unless the owning isolated env is being destroyed. Contract: docs/background-process-lifetime.md.
+ * answers it calls this function (Bash description + receipts, Monitor receipt, the row stamp, teardown settle,
+ * the run-boundary dispose at teardown and park-only parks, session reap, the exit hard face, the listing).
+ * Any declared lane retains, unless the owning isolated env is being destroyed.
+ * Contract: docs/background-process-lifetime.md.
  */
 export declare function retainsBackgroundProcesses(lanes: BackgroundRetainLanes): boolean;
 /** The env lane of {@link BackgroundRetainLanes}, read off an env (false for an env without the capability). */
@@ -192,12 +193,27 @@ export declare function sweepBackgroundShells(env: ExecutionEnv & BackgroundShel
     except?: readonly string[];
 }): Promise<void>;
 /**
- * The park-only sweep (a durable park that does not pause the env), one entry point for every park lane:
- * nothing is swept when this run's task or the env declares retain; otherwise every row already retained on
- * this env (an earlier run's delivered service) is spared.
+ * THE env-wide dispose at a run boundary: the run's teardown (every exit path) and the park-only park (a
+ * durable park that does not pause the env — its workspace, and the processes on it, persist on the target).
+ * One rule for "which background shells does this boundary take":
+ *
+ * - nothing, when THE retain predicate holds for the lanes the boundary sees (the env's declaration, the
+ *   run's `TaskSpec` lane; `envDying` overrides both);
+ * - otherwise every registered shell row still running on the env is spared (`runningShellIds`, any owner):
+ *   what the run's own settle kept (session-resident rows, in-window Monitors, retained rows) and every other
+ *   run's or session's rows sharing the env. Unregistered env shells are disposed;
+ * - `envDying` (an isolated owned env destroyed with this run) spares nothing: its processes die with it.
+ *
+ * A park and a teardown ask the same question because a park-only park IS the run ending for now: the run's
+ * teardown follows every park, its settle collects the run's own rows that end with it, and its dispose
+ * spares the rest — a park that took more would take what the run's end keeps (a session's loop, killed
+ * while its approval card is on screen). The sweep before a snapshot pause is a different question (the VM
+ * pause must not capture detached jobs; resume would revive untracked zombies), which is why those sites
+ * call {@link sweepBackgroundShells} with no keep-list.
  */
-export declare function sweepParkOnlyBackgroundShells(env: ExecutionEnv & BackgroundShellCapability, registry: EnvSweepAttribution & {
-    retainedShellIds(env: unknown): readonly string[];
+export declare function sweepRunBoundaryBackgroundShells(env: ExecutionEnv & BackgroundShellCapability, registry: EnvSweepAttribution & {
+    runningShellIds(env: unknown): readonly string[];
 }, lanes: {
     task: boolean;
+    envDying?: boolean;
 }): Promise<void>;

package/dist/core/background-shell.js

@@ -33,9 +33,10 @@ export async function sweepBackgroundShells(env, attribution, opts) {
     }
     await env.disposeBackgroundShells(opts?.except !== undefined ? { except: opts.except } : undefined);
 }
-export async function sweepParkOnlyBackgroundShells(env, registry, lanes) {
-    if (retainsBackgroundProcesses({ env: envDeclaresRetain(env), task: lanes.task }))
+export async function sweepRunBoundaryBackgroundShells(env, registry, lanes) {
+    const envDying = lanes.envDying === true;
+    if (retainsBackgroundProcesses({ env: envDeclaresRetain(env), task: lanes.task, envDying }))
         return;
-    const except = registry.retainedShellIds(env);
+    const except = envDying ? [] : registry.runningShellIds(env);
     await sweepBackgroundShells(env, registry, except.length > 0 ? { except } : undefined);
 }

package/dist/core/runner/prepare-boundary-parks.js

@@ -1,4 +1,4 @@
-import { hasBackgroundShell, sweepBackgroundShells, sweepParkOnlyBackgroundShells } from "../background-shell.js";
+import { hasBackgroundShell, sweepBackgroundShells, sweepRunBoundaryBackgroundShells } from "../background-shell.js";
 import { checkpointVersionFor, debitLedger, mintCheckpointId, mintCheckpointToken, } from "../checkpoint-store.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { checkpointScopeOf } from "./checkpoint-scope.js";
@@ -37,7 +37,7 @@ export function prepareBoundaryParks(input) {
         }
         else if (parkOnlyRemoteEnv !== undefined) {
             if (hasBackgroundShell(parkOnlyRemoteEnv))
-                await sweepParkOnlyBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
+                await sweepRunBoundaryBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
             remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
         }
         const token = mintCheckpointToken();
@@ -120,7 +120,7 @@ export function prepareBoundaryParks(input) {
             }
             else if (parkOnlyRemoteEnv !== undefined) {
                 if (hasBackgroundShell(parkOnlyRemoteEnv))
-                    await sweepParkOnlyBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
+                    await sweepRunBoundaryBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
                 remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
             }
             const token = mintCheckpointToken();

package/dist/core/runner/prepare-park-ask.js

@@ -1,7 +1,7 @@
 import { uuidv7 } from "../../engine/session/uuid.js";
 import { Value } from "typebox/value";
 import { ASK_USER_QUESTION_TOOL_NAME, classifyQuestionOutcome, validateAskQuestions } from "../ask-question.js";
-import { hasBackgroundShell, sweepBackgroundShells, sweepParkOnlyBackgroundShells } from "../background-shell.js";
+import { hasBackgroundShell, sweepBackgroundShells, sweepRunBoundaryBackgroundShells } from "../background-shell.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { buildRiskDescriptor, checkpointVersionFor, debitLedger, encodeAtFidelity, mintCheckpointId, mintCheckpointToken, resolveDeclaredFidelity, samePlainValue, } from "../checkpoint-store.js";
 import { pauseOf } from "../pause-registry.js";
@@ -230,7 +230,7 @@ export function prepareParkAsk(input) {
                 }
                 else if (parkOnlyRemoteEnv !== undefined) {
                     if (hasBackgroundShell(parkOnlyRemoteEnv))
-                        await sweepParkOnlyBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
+                        await sweepRunBoundaryBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true });
                     remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
                 }
                 token = mintCheckpointToken();

package/dist/core/runner/prepare-task.js

@@ -13,7 +13,7 @@ import { isValidReminderMark, mintReminderMark } from "../reminder-mint.js";
 import { refuseInvalidApproverPosture } from "../auto-mode-directive.js";
 import { emitTrace } from "../trace.js";
 import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
-import { STALL_CONNECT_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, withBrainCallGuardrail } from "../../brain/timeout.js";
+import { STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, withBrainCallGuardrail } from "../../brain/timeout.js";
 import { OFFLOAD_TOOL_NAME } from "../tool-result-store.js";
 import { OUTPUT_TOOL_NAME, createOutputTool } from "./synthetic-tools.js";
 import { compileOutputSchema } from "./strict-output-schema.js";
@@ -649,7 +649,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 : {}),
             stallTimeoutsPerCall: () => {
                 callIssuedAtRef.current = Date.now();
-                return { connectMs: STALL_CONNECT_MS, firstTokenMs: STALL_FIRST_TOKEN_MS, idleMs: STALL_IDLE_MS };
+                return { firstByteMs: STALL_FIRST_BYTE_MS, firstTokenMs: STALL_FIRST_TOKEN_MS, idleMs: STALL_IDLE_MS };
             },
             ...(spec.resilience !== undefined ? { resilience: spec.resilience } : {}),
             loopTrace: (step) => {

package/dist/core/runner/run-settle-and-teardown.js

@@ -2,7 +2,7 @@ import { MAX_CONSECUTIVE_COMPACTION_FAILURES } from "./compaction-knobs.js";
 import { isSyntheticApiErrorMessage } from "../../internal/harness.js";
 import { adjudicateDerivedRoute, fallbackToPrimaryNotice, sameRouteIdentity } from "../../brain/route-adjudicator.js";
 import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
-import { hasBackgroundShell, retainsBackgroundProcesses, sweepBackgroundShells } from "../background-shell.js";
+import { hasBackgroundShell, sweepRunBoundaryBackgroundShells } from "../background-shell.js";
 import { resolveCheckpointStore } from "../checkpoint-store.js";
 import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
 import { modelCostToPricing } from "../pricing.js";
@@ -315,11 +315,9 @@ export async function runSettleAndTeardown(input) {
             retainProcesses: spec.retainBackgroundProcesses === true,
         }), "taskRegistry.settleKilledForOwner", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
         const bgEnv = prepared.ownedEnv ?? runner.deps.executionEnv;
-        const retainBgBySpec = retainsBackgroundProcesses({ task: spec.retainBackgroundProcesses === true, envDying: ownedEnvDying });
-        if (bgEnv && hasBackgroundShell(bgEnv) && !retainBgBySpec) {
+        if (bgEnv && hasBackgroundShell(bgEnv)) {
             try {
-                const keepAlive = ownedEnvDying && bgEnv === prepared.ownedEnv ? [] : defaultTaskRegistry.runningShellIds(bgEnv);
-                await settleTeardownLeg(() => sweepBackgroundShells(bgEnv, defaultTaskRegistry, keepAlive.length > 0 ? { except: keepAlive } : undefined), "sweepBackgroundShells", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
+                await settleTeardownLeg(() => sweepRunBoundaryBackgroundShells(bgEnv, defaultTaskRegistry, { task: spec.retainBackgroundProcesses === true, envDying: ownedEnvDying }), "sweepBackgroundShells", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId }));
             }
             catch (e) {
                 runner.deps.onError?.(e, { phase: "config", sessionId: prepared.sessionId });

package/dist/core/task-event.d.ts

@@ -141,12 +141,14 @@ export interface BrainStatus {
      * approximate across a clock adjustment — {@link retryInMs} stays the authoritative RELATIVE quantity.
      */
     retryAtMs?: number;
-    /** On a `waiting_first_token` frame: how long the first token has been awaited, ms, at the
-     *  moment the frame is emitted (the emitting process's clock; approximate across a hop). Absent on
-     *  every other phase. */
+    /** On a `waiting_first_token` frame: how long the current wait has lasted, ms, at the moment the
+     *  frame is emitted (the emitting process's clock; approximate across a hop). The wait is one
+     *  segment's: the response-header wait before headers arrive, the first-token wait after — each
+     *  starts its own count. Absent on every other phase. */
     elapsedMs?: number;
-    /** On a `waiting_first_token` frame: the armed first-token watchdog, ms — the wait's ceiling,
-     *  so a consumer can render "45s of 120s". Absent on every other phase. */
+    /** On a `waiting_first_token` frame: the ceiling of the segment being waited on, ms — the armed
+     *  first-byte window before headers, the armed first-token watchdog after — so a consumer can render
+     *  "45s of 300s". Absent on every other phase. */
     timeoutMs?: number;
     /** 1-based index of the attempt that just failed (the wait precedes attempt `attempt + 1`);
      *  same numbering as the `brain.retry` telemetry frame. Absent on frames that are not a retry wait. */

package/dist/core/task-registry-shared.d.ts

@@ -140,7 +140,7 @@ export interface BackgroundBashTaskHandle extends SemaTaskHandle {
      *  field reads as not marked. The row is the delivered daemon's ONLY management surface — while the process runs it survives the
      *  per-run evict (TaskOutput/TaskStop resolve through this map; the watcher must stay live to mint
      *  the natural-exit receipt) and rides every later run's dispose except-list on the same env
-     *  ({@link TaskRegistry.retainedShellIds}). A terminal row evicts normally. Terminals: explicit
+     *  ({@link TaskRegistry.runningShellIds}). A terminal row evicts normally. Terminals: explicit
      *  TaskStop, the process's own exit (watcher settle), or env destruction (watcher env-death settle)
      *  — deliberately NO timed reaper (the deliverable is the living process). A retained SESSION-resident
      *  row is likewise exempt from the session-release reap ({@link TaskRegistry.reapSessionBackground}):

package/dist/core/task-registry.d.ts

@@ -386,8 +386,7 @@ export declare class TaskRegistry {
     /** Background output-file read exemption: true iff `canonicalPath` is EXACTLY the registered output
      *  file of a background bash row that (a) the caller can access (same owner/scope/session visibility as
      *  a TaskOutput poll — {@link canAccess}) and (b) was registered on the caller's OWN execution env —
-     *  `env` identity is part of the match, same discipline as {@link retainedShellIds} /
-     *  {@link runningShellIds}. A canonical path only names a file within ONE env's filesystem
+     *  `env` identity is part of the match, same discipline as {@link runningShellIds}. A canonical path only names a file within ONE env's filesystem
      *  namespace: on a shared registry, a row minted on env A must never exempt a same-named outside-root
      *  file in env B's namespace (same session or not), so instance equality — never a string proxy — is
      *  required. The output file is minted by the ENGINE itself (createTempFile
@@ -610,10 +609,8 @@ export declare class TaskRegistry {
      *  completion notification at the terminal state. `unref()`d — a watcher never keeps the process alive.
      *  Stops itself on terminal, on a vanished shell (env disposed), or when the handle is evicted. */
     private startBashWatcher;
-    /** RETAINED shells (THE retain predicate) still running on THIS env, any owner — the park-only sweep's
-     *  spare list. Env identity is part of the match (a shared registry never exempts another env's ids). */
-    retainedShellIds(env: unknown): BackgroundShellId[];
-    /** Every shell-lane row still RUNNING on this env, any owner — the run teardown's dispose except-list.
+    /** Every shell-lane row still RUNNING on this env, any owner — the run-boundary dispose's except-list (the
+     *  run teardown and the park-only parks: `sweepRunBoundaryBackgroundShells`).
      *  A run's teardown disposes only shells it can attribute to itself: its settle sweep has already killed
      *  and settled the rows of this run that end with it, so whatever registered row is still running here is
      *  either something that settle kept (session-resident, an in-window Monitor, retained) or belongs to

package/dist/core/task-registry.js

@@ -835,15 +835,6 @@ export class TaskRegistry {
         handle.watcher = setInterval(() => void tick(), 1_000);
         handle.watcher.unref?.();
     }
-    retainedShellIds(env) {
-        const out = [];
-        for (const handle of this.handles.values()) {
-            if ((handle.type === "background_bash" || handle.type === "monitor") && handle.status === "running" && shellRowRetained(handle) && handle.env === env) {
-                out.push(handle.shellId);
-            }
-        }
-        return out;
-    }
     runningShellIds(env) {
         const out = [];
         for (const handle of this.handles.values()) {

package/dist/engine/llm/types.d.ts

@@ -39,12 +39,12 @@ export interface ResilienceOptions {
      *  exists to protect the provider; circumvention only where true failure shape matters (benchmarks). */
     bypassBreaker?: boolean;
 }
-/** 1.296 件A — per-call advisory stall-watchdog values (see {@link StreamOptions.stallTimeouts}). */
+/** 1.296 件A — per-call advisory stall-watchdog values (see {@link StreamOptions.stallTimeouts}); the
+ *  connect clock is the transport's, fixed at brain construction, so it is not among them. */
 export interface StallTimeouts {
-    /** Advisory connect watchdog (ms) — bounds the fetch→response-headers wait (件1a: a gateway that
-     *  never returns headers is invisible to every post-headers watchdog, including the absolute
-     *  deadline timer). Fires as the brain's existing retryable `network` connect timeout. */
-    connectMs?: number;
+    /** Advisory first-byte watchdog (ms) — bounds the fetch→response-headers wait; fires as a retryable
+     *  `stall` out of its own small budget. */
+    firstByteMs?: number;
     /** Advisory first-token watchdog (ms) — first thinking delta counts as the first token. */
     firstTokenMs?: number;
     /** Advisory mid-stream idle watchdog (ms) — re-armed on every delta after the first. */