@sema-agent/core 7.32.1 → 7.33.1

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,117 @@ 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 by default ({@link BrainTimeoutConfig.firstByteRetries}),
+ *  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 first-byte lane's retry budget: absent ⇒ {@link FIRST_BYTE_RETRY_BUDGET}; `0` / `1` are themselves; anything
+ *  else is refused (`config.stall_timeout_invalid`), never folded to the default or to `0`. */
+export declare function resolveFirstByteRetries(value: unknown): 0 | 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 ({@link firstByteRetries}), then fails naming this knob.
+     * Fires as a `stall` (this process cancelled its own request), never as a transport fault. `0` ⇒ off.
+     */
+    firstByteTimeoutMs?: number;
+    /**
+     * The first-byte lane's own retry budget: `1` (absent ⇒ {@link FIRST_BYTE_RETRY_BUDGET}) or `0` — the first
+     * window's expiry is the call's terminal, for a host whose own failover ladder should take a silent gateway after
+     * one window. Independent of `maxRetries` both ways; construction only; any other value fails the call naming this
+     * knob. The derived floors ({@link firstByteLaneKnobMs}) read the default.
+     */
+    firstByteRetries?: 0 | 1;
     /**
      * 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 +152,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 +179,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,54 @@ 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 function resolveFirstByteRetries(value) {
+    if (value === undefined)
+        return FIRST_BYTE_RETRY_BUDGET;
+    if (value === 0 || value === 1)
+        return value;
+    const shown = typeof value === "string" ? JSON.stringify(value) : typeof value === "bigint" ? `${value}n` : typeof value === "object" && value !== null ? "an object" : String(value);
+    const e = new Error(`firstByteRetries must be 0 or 1 (got ${shown}) — 1 re-sends a first-byte stall once at a widened window (the default), 0 ends the call at the first window so the caller's own failover takes it`);
+    e.code = "config.stall_timeout_invalid";
+    throw e;
+}
+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 +72,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/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/prepare-wiring-manifest.js

@@ -11,7 +11,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { mountWriteProtection } from "./write-protection-station.js";
 import { autoRunOnRecommendationEffective } from "./memory-consolidation-driver.js";
 import { GLOBAL_USAGE_KEY, usageRetryAfterMs, windowsGovernCost } from "../usage-window-store.js";
-import { LSP_CONTRACT_ID, countElicitOptIns, deriveLspSeam, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam, resolveSubagentTranscriptTier } from "../wiring-manifest.js";
+import { LSP_CONTRACT_ID, countElicitOptIns, deriveHandsSeam, deriveLspSeam, deriveWiringManifest, resolveAskSeamForm, resolveDeclaredDurability, resolveElicitSeam, resolveQuestionSeam, resolveSubagentTranscriptTier } from "../wiring-manifest.js";
 import { DEFAULT_IRREVERSIBLE_SCOPE } from "./checkpoint-scope.js";
 export function mcpManifestEntries(entries, statuses) {
     return (entries ?? []).map((entry) => {
@@ -218,6 +218,7 @@ export function prepareWiringManifest(input) {
         tools: toolRoster,
         hooks: wiredHookEntries(hooks, spec.hooks !== undefined ? "spec" : "deps", preToolUseObservational),
         ...(lspManagerWired ? { lsp: deriveLspSeam(toolRoster.entries.some((e) => e.contract.contractId === LSP_CONTRACT_ID), lspDiagnosticsLive) } : {}),
+        hands: deriveHandsSeam(handsEnabled),
         fileHistory: fileHistoryFact,
     });
     peerLaneRefs.askEffective = wiringManifest.ask.effective;

package/dist/core/secret-env.d.ts

@@ -18,6 +18,12 @@
  */
 import type { RedactionConfidence, RedactionSource } from "./arg-summary.js";
 import { type EngineNotice } from "./engine-notice.js";
+/** A name table as the exact-name arm reads it: membership of an UPPER-CASED name, given the entry's value when
+ *  the caller has one. A `Set` of exact names is one (it ignores the value); the exemption side is the union of
+ *  its two tables. */
+export interface EnvNameTable {
+    has(upperName: string, value?: string): boolean;
+}
 /** Which rule classified a key as secret-shaped — the env arm's `kind` vocabulary. */
 export type SecretEnvFindingKind = "suffix-rule" | "namespace-rule" | "exact-name";
 /** One env entry the `scrub` policy dropped: the key (the VALUE is never carried — this record is meant
@@ -30,14 +36,17 @@ export interface SecretEnvFinding {
 }
 /** What the two exact-name lists say about a name, before any shape rule is consulted. */
 export type ExactEnvNameVerdict = "credential" | "exempt" | "unknown";
-/** The exact-name arm of the classification, taking both lists as arguments. The credential list is read
+/** The exact-name arm of the classification, taking both lists as arguments (the exemption side is the exact
+ *  names plus the named families). The credential list is read
  *  FIRST: an exemption can never take a name away from it, so a name landing on both lists resolves to the
  *  credential reading — the fail-closed direction (a wrongly-exempted name leaks; a wrongly-dropped one
  *  does not). Module-level export (not part of the package surface): the two real lists are disjoint, so
  *  only a controlled collision can tell this precedence from an inverted one. */
-export declare function classifyExactEnvName(key: string, credentialNames: ReadonlySet<string>, exemptNames: ReadonlySet<string>): ExactEnvNameVerdict;
-/** Is `key` a secret-pattern env var (one the fail-closed `scrub` policy drops before spawning a shell)? */
-export declare function isSecretEnvKey(key: string): boolean;
+export declare function classifyExactEnvName(key: string, credentialNames: EnvNameTable, exemptNames: EnvNameTable, value?: string): ExactEnvNameVerdict;
+/** Is `key` a secret-pattern env var (one the fail-closed `scrub` policy drops before spawning a shell)? Pass the
+ *  entry's `value` to get exactly the scrub's answer for that entry: a named-family exemption holds only for a value
+ *  that clears the family's screen, so without a value such a member reads as secret (the name alone cannot clear). */
+export declare function isSecretEnvKey(key: string, value?: string): boolean;
 /** Drop every secret-pattern key (see {@link isSecretEnvKey}) from an env object — the fail-closed `scrub`
  *  policy. `findings` is an OPTIONAL caller-owned collector: pass an array to learn which entries were
  *  dropped and why, read it back after the call. Omitting it leaves this function byte-for-byte what it

package/dist/core/secret-env.js

@@ -15,21 +15,30 @@ const NON_SECRET_ENV_EXACT_NAMES = new Set([
     "MAX_BATCH_PREFILL_TOKENS", "MAX_WAITING_TOKENS", "MAX_TOP_N_TOKENS", "RATE_LIMIT_TOKENS",
     "PROMPT_TOKENS", "CONTEXT_TOKENS",
 ]);
+const NON_SECRET_ENV_INDEXED_FAMILIES = [
+    { stem: "GIT_CONFIG_KEY", valueClears: (value) => !/[a-z][a-z0-9+.-]*:\/\/[^/@]+@/i.test(value) },
+];
+const indexedFamilyMember = (stem) => new RegExp(`^${stem}_(?:0|[1-9][0-9]*)$`);
+const NON_SECRET_ENV_INDEXED_FAMILY_ROWS = NON_SECRET_ENV_INDEXED_FAMILIES.map((f) => ({ member: indexedFamilyMember(f.stem), valueClears: f.valueClears }));
+const NON_SECRET_ENV_NAMES = {
+    has: (upperName, value) => NON_SECRET_ENV_EXACT_NAMES.has(upperName) ||
+        (value !== undefined && NON_SECRET_ENV_INDEXED_FAMILY_ROWS.some((row) => row.member.test(upperName) && row.valueClears(value))),
+};
 const SECRET_ENV_KIND_CONFIDENCE = {
     "exact-name": "high",
     "suffix-rule": "medium",
     "namespace-rule": "medium",
 };
-export function classifyExactEnvName(key, credentialNames, exemptNames) {
+export function classifyExactEnvName(key, credentialNames, exemptNames, value) {
     const upper = key.toUpperCase();
-    if (credentialNames.has(upper))
+    if (credentialNames.has(upper, value))
         return "credential";
-    if (exemptNames.has(upper))
+    if (exemptNames.has(upper, value))
         return "exempt";
     return "unknown";
 }
-function classifySecretEnvKey(key) {
-    const byExactName = classifyExactEnvName(key, SECRET_ENV_EXACT_NAMES, NON_SECRET_ENV_EXACT_NAMES);
+function classifySecretEnvKey(key, value) {
+    const byExactName = classifyExactEnvName(key, SECRET_ENV_EXACT_NAMES, NON_SECRET_ENV_NAMES, value);
     if (byExactName === "credential")
         return "exact-name";
     if (byExactName === "exempt")
@@ -38,13 +47,13 @@ function classifySecretEnvKey(key) {
         return "suffix-rule";
     return SEMA_NAMESPACE_SECRET_RE.test(key) ? "namespace-rule" : undefined;
 }
-export function isSecretEnvKey(key) {
-    return classifySecretEnvKey(key) !== undefined;
+export function isSecretEnvKey(key, value) {
+    return classifySecretEnvKey(key, value) !== undefined;
 }
 export function scrubSecretEnv(env, findings) {
     const out = {};
     for (const k of Object.keys(env)) {
-        const kind = classifySecretEnvKey(k);
+        const kind = classifySecretEnvKey(k, env[k]);
         if (kind === undefined) {
             out[k] = env[k];
             continue;

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.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,11 +609,6 @@ 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. Env identity is part of the
-     *  match (a shared registry never exempts another env's ids). No caller in src since the park-only parks
-     *  moved to the run-boundary dispose (which spares every running row: {@link runningShellIds}); removal
-     *  scheduled for the next minor. */
-    retainedShellIds(env: unknown): BackgroundShellId[];
     /** 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

package/dist/core/task-registry.js

@@ -606,7 +606,12 @@ export class TaskRegistry {
             }
             let outcome;
             try {
-                outcome = handle.env.killBackgroundNow !== undefined ? handle.env.killBackgroundNow(handle.shellId) : "no_pgid";
+                const seat = handle.env.killBackgroundNow;
+                if (seat === undefined)
+                    shutdownDebug("hard kill: seat absent", { id: handle.id, shellId: handle.shellId });
+                outcome = seat === undefined ? "no_pgid" : seat.call(handle.env, handle.shellId);
+                if (seat !== undefined && outcome === "no_pgid")
+                    shutdownDebug("hard kill: seat answered no_pgid", { id: handle.id, shellId: handle.shellId });
             }
             catch (err) {
                 shutdownDebug("hard kill: seat threw", { id: handle.id, shellId: handle.shellId, error: thrownText(err) });
@@ -835,15 +840,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/core/tool-policy.d.ts

@@ -341,18 +341,18 @@ export type PermissionResult = {
      *  `probe*` above; ENGINE-STAMPED and VALIDATED at the tighten, and deliberately NOT merged onto an ask
      *  another layer raised, which a grant leaves standing. */
     probeReadRootCandidate?: import("./types.js").ReadRootGrantCandidate;
-    /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules`
-     *  shape); carries the matched rule's text. Present ⇔ a rule someone WROTE says "ask about this",
-     *  never for a `defaultAction:"ask"` fallback (an unmatched call is default-closed posture, not a
-     *  per-call instruction — CC draws the same line: only a matched ask rule diverts the auto-mode
-     *  lane, a mode-default ask stays classifier-eligible). Consumer: the gate's auto-mode classifier
-     *  step refuses to resolve an ask carrying it — a person's standing "ask me each time" is not
-     *  classifier hesitation, so a classifier verdict must not be the thing that clears it. A policy
-     *  self-declaring the member only ever OPTS ITS OWN ask OUT of classifier auto-resolution
-     *  (tightening — the false-claim direction is safe, unlike the engine-stamped `"hook"` word whose
-     *  risk was laundering provenance AWAY). {@link combinePolicies} carries it onto the surviving ask
-     *  when ANY folded-away concurrent ask bore it (monotone, tighten-only); it is consumed inside the
-     *  gate and deliberately NOT copied onto the park/approval-card request. */
+    /** An EXPLICIT `ask` permission rule matched this call (design/127 DSL — the CC `alwaysAskRules` shape); carries the
+     *  matched rule's text. Present ⇔ a rule someone WROTE says "ask about this", never for a `defaultAction:"ask"` fallback
+     *  (an unmatched call is default-closed posture, not a per-call instruction — CC draws the same line: only a matched ask
+     *  rule diverts the auto-mode lane, a mode-default ask stays classifier-eligible). Consumer: the gate's auto-mode
+     *  classifier step refuses to resolve an ask carrying it — a person's standing "ask me each time" is not classifier
+     *  hesitation, so a classifier verdict must not be the thing that clears it. A policy self-declaring the member only
+     *  ever OPTS ITS OWN ask OUT of classifier auto-resolution (tightening — the false-claim direction is safe, unlike the
+     *  engine-stamped `"hook"` word whose risk was laundering provenance AWAY). {@link combinePolicies} carries it onto the
+     *  surviving ask when ANY folded-away concurrent ask bore it (monotone, tighten-only); it is consumed inside the gate
+     *  and NOT copied onto the park/approval-card request — but it is the ONE input of the `ask_rule` origin word they DO
+     *  carry ({@link origin}): a minter raising an ask for a written rule (a person's settings rule, an operator's must-ask
+     *  list) that leaves it unset gets `policy` there, indistinguishable from hesitation. */
     matchedAskRule?: string;
     /** design/252 G-2 (additive): the RULE-PROVENANCE evidence behind this ask — see
      *  {@link AskRuleEvidence}. ENGINE-STAMPED inside the gate, once, after the org layer and the