@sema-agent/core 7.32.1 → 7.33.1

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 7.33.1 — 2026-09-26
+
+### The first-byte lane's retry is a construction-time seat — `BrainTimeoutConfig.firstByteRetries?: 0 | 1` (#1128; additive; +1 optional type key; +0 exports, +0 codes) (@server)
+
+- **Before.** The lane's budget was a module constant (`FIRST_BYTE_RETRY_BUDGET` = 1) with no seat, and `maxRetries: 0` does not reach it (the lane's budget is its own, by design). A host that keeps a failover ladder of its own — a second gateway it tries when a call fails — waited the first-byte window and then a retry at twice the knob before the failure reached that ladder: 300 s + 600 s at the default, 30 s + 60 s even at an explicit 30 s knob.
+- **Now.** `firstByteRetries: 0 | 1` on every first-party brain's config (absent ⇒ 1, the reference implementation's one retry — unchanged). `0` ⇒ the first window's expiry is the call's terminal: one request, no retry frame, the existing one-window sentence (`[network] first-byte timeout: no response headers within <w1>ms (firstByteTimeoutMs) — …`). Independent of `maxRetries` in both directions, construction only (no per-call advisory twin). A value other than `0` / `1` fails the call before anything is sent, naming the knob (the watchdog knobs' own refusal, `config.stall_timeout_invalid`, at the same resolution point — like theirs, the code stays inside the brain and the caller reads the message) — never folded to the default or to `0`. The derived floors (`firstByteLaneKnobMs`, `WORKFLOW_AGENT_STALL_MS`) read the default and do not move.
+- **Who is hurt.** Nobody: absent is byte-for-byte 7.33.0. **Compensation** n/a.
+- Pins: `test/backlog1128-first-byte-retries.test.ts` (real transport, a local gateway that never writes headers: `0` ⇒ one request and the one-window terminal on all three brains, also under `maxRetries: 10`; explicit `1` and absent ⇒ two requests and one retry frame with `maxRetries: 1` under `maxRetries: 0`; twelve bad values refused by the resolver and through a brain with nothing sent; the derived floors). Docs: `docs/TIMEOUTS.md` (a retry-knob column; "a host with a failover ladder sets `0`"), `docs/sdk/03-brains-and-models.md`. Wire sheet: `docs/wire-consumption/unreleased-1128.md`.
+
+### Fix — git's environment config group survives the secret-env scrub whole: `GIT_CONFIG_KEY_<i>` is no longer taken for a credential unless its value carries one (#1129; behavior; +0 exports; `isSecretEnvKey` gains an optional `value` argument; +0 wire keys) (@server)
+
+- **Before.** The shape rule reads a bare `KEY` word with a numbered suffix as a credential, so `GIT_CONFIG_KEY_<i>` — git's env config, where the member holds a config entry's NAME (`user.name`, `safe.directory`, `http.extraHeader`) and `GIT_CONFIG_VALUE_<i>` its value — was dropped while `GIT_CONFIG_COUNT` and the value stayed. Every git child of a scrubbed env then refused to start: `error: missing config key GIT_CONFIG_KEY_0` / `fatal: unable to parse command-line config`, exit 128 (measured through the default exec env on a host carrying the group).
+- **Now.** The exemption side of the exact-name arm reads a second table beside the exact names, under the same three admission criteria: NAMED FAMILIES, `<STEM>_<i>` with `i` a canonical decimal — the spelling the reading tool builds itself. One member: `GIT_CONFIG_KEY`. Its row states criterion 2 ("the value is not a credential") as a screen on the VALUE rather than a standing claim, because a config key's subsection can be a URL and git authenticates with a URL's userinfo (`url.https://x-access-token:<token>@github.com/.insteadOf`): a member whose value carries `<scheme>://<userinfo>@` (any character but `/` counts as userinfo, whitespace included) is not exempt and drops by the shape rule exactly as before (finding `suffix-rule`). The screen is the row's own admission condition, read by the one classification (`classifySecretEnvKey(name, value?)`); `scrubSecretEnv` passes each entry's value, and `isSecretEnvKey(name)` without a value reads as in 7.33.0 (a family member is `true` — the name alone cannot clear); `isSecretEnvKey(name, value)` gives the scrub's answer for that entry. Unchanged: the bare `GIT_CONFIG_KEY`, a decorated (`X_GIT_CONFIG_KEY_0`), padded (`GIT_CONFIG_KEY_01`) or suffixed (`GIT_CONFIG_KEY_ID`, `GIT_CONFIG_KEY_0_TOKEN`) name, and every credential name (`GIT_API_TOKEN`, `GIT_PASSWORD`, `GH_TOKEN`) still drop and are still reported through `config.secret_env_scrubbed` / `onSecretEnvScrub`; the credential list still wins a collision.
+- **Who needs it.** Any deployment whose host process configures git through the environment (the `GIT_CONFIG_COUNT` protocol — a `safe.directory`, an `http.extraHeader` name, a mirror rewrite set without touching a config file): the two children the engine spawns from a scrubbed copy of its own environment — the default exec env's shell (`inheritEnv: "scrub"`) and an LSP server started without an explicit `env`.
+- **Who is hurt / compensation.** A group whose key carries URL userinfo — a token-bearing `url.<base>.insteadOf`, and also a username-only one such as `url.ssh://git@github.com/.insteadOf` — is still dropped at that key, so git in the child still exits 128 there (fail-closed: the credential does not reach the child; KL-1129b); the compensation is to hand the group explicitly (`inheritEnv` allowlist / `shellEnv`) or move the rewrite into a git config file. `GIT_CONFIG_VALUE_<i>` can carry a credential (an `http.extraHeader: Authorization: …` value) and was already inherited: the shape rule never matched its name, and this change does not touch it either way (KL-1129a).
+- Pins: `test/backlog1129-git-config-key-family.test.ts` (① `user.name` / `safe.directory` / a userinfo-free `insteadOf` through `scrubSecretEnv` and a real git child reading all three, and the default exec env's git child reading the entry while the withheld set names a planted credential and not the member; ② a token-bearing `insteadOf` key dropped with one finding, the token nowhere in the scrubbed env, git refusing with exit 128; the screen across schemes, a username-only userinfo, a userinfo with whitespace in it (git reads the credential out of it all the same) and an `@` in a path; ③ `isSecretEnvKey` without a value unchanged, with a clearing value `false`; an undefined entry drops; ④ the stem, decorated, padded, suffixed and credential names dropped by the shape rule even with a clearing value; the value member unmatched; the credential side winning a collision). Mutation-checked: a screen that always clears reds ②, a screen consulted without a value reds ③.
+
+### The wiring manifest says whether a leg has hands — `WiringManifest.hands?: { mounted, reason? }` (#1039; additive; +1 optional member on `WiringManifest` / `WiringFacts`; +1 wire word `no_execution_env`; +0 exports; `configFingerprint` value moves once) (@server)
+
+- **Before.** A leg whose deployment supplied no execution environment (no factory, no static `executionEnv`) mounts no hand band at all, and the wire said so only indirectly: an empty `mountedBy: "hands"` slice of `tools[]`, or `writeProtection.targetView: "spelling-only"` — which is absent altogether when the protection table is `[]`, where "no hands" and "protection off" read the same and the two assemblies hashed to the same `configFingerprint`.
+- **Now.** Every engine-minted effective manifest carries `hands`, beside `lsp` and in the same shape: `{ mounted: true }` when the band mounted (a factory-minted env, or a static `executionEnv` seat that is not `undefined` — a supplied `StubExecutionEnv` included, the band mounting over it with file tools and no shell, and a JS caller's `null` likewise over the no-I/O placeholder), `{ mounted: false, reason: "no_execution_env" }` otherwise. The value is the one the hand band's mount dispatches on, relayed, not re-derived. `reason` is one literal, not a registered closed set, because the hands decision has one false branch (a second branch promotes it). Unlike `lsp`, the member is IN `configFingerprint` (an assembly fact, the class of `writeProtection`), so a with-hands and a hands-less assembly now hash apart. No `EngineNotice`, no `TaskResult` change; whether a full shell is reachable stays a `tools[]` reading.
+- **Who is hurt.** A consumer that persisted `configFingerprint` values across engine versions sees every effective fingerprint change once (a new member in the hashed body); legs of one assembly still agree. An external `deriveWiringManifest` caller that passes an inconsistent `hands` fact is refused (the `autoMode` / `fileHistory` screen posture). **Compensation** n/a — the member is additive and its absence (older engines, the static half) is not a state.
+- Pins: `test/backlog1039-wiring-manifest-hands.test.ts` (through the Runner: a static env, no env, a supplied `StubExecutionEnv`, a JS caller's `null`, the factory lane — each read against the same leg's `tools[]`; the fingerprint telling the two assemblies apart with no protection judge on either; the value screen's six refusals, `null` included; the static half; no aliasing). Docs: `docs/INTEGRATION-CORE.md` (`wiring_manifest` row). Wire sheet: `docs/wire-consumption/unreleased-1039.md`.
+
+### Pins and wording — an explicit ask rule's ask and a hook's ask carry their own origin word on the card and on the park row (#1117; zero behavior face; +0 exports, +0 wire keys) (@server @cli)
+
+- **What was unpinned.** The origin ladder already mints `ask_rule` from a decision's `matchedAskRule` and `hook` from the hook fold, and gate-level pins read the word the resolver receives — but no pin read the WIRE faces a surface renders from: `AskRequest.origin` on a live approver and `PendingAction.tool_approval.origin` / `CheckpointSummary.origin` on a park, through the real Runner. A host policy that raises an operator's must-ask as an `ask` WITH `matchedAskRule` (composed through `combinePolicies`, beside a base policy's plain ask) reaches both faces as `ask_rule` today; without the member it reads `policy`.
+- **Now pinned**, and said where the words are listed: `docs/INTEGRATION-CORE.md` §4.6b (the enumerated set brought to its eleven words) states that `ask_rule` has one input — a minter raising an ask for a rule someone wrote must set `matchedAskRule`, or a plain policy ask reads `policy` on the card and the row — and what setting it means (the classifier does not answer it, a persisted allow rule does not clear it, an answer for this call does); the `PermissionResult.matchedAskRule` doc says the same. Two internal comments on the inherited-lane mint stations and the 7.26.0 `AskRequest.mandated` entry used "standing posture" for what a mandate refuses; the contract's word is a STANDING ANSWER (a release remembered from an earlier call) — an answer given for this call still clears a mandated ask. Wording only.
+- Pins: `test/backlog1117-ask-origin-rule-and-hook.test.ts` (live card and park row for the operator ask folded beside a base ask and alone, with the no-`matchedAskRule` negative control reading `policy`; live card — over an allowing policy and folded over a policy ask — and park row for a hook ask). Mutation-checked: removing the ladder's `ask_rule` arm reds three, its `hook` arm two, the fold's `matchedAskRule` carry two.
+
+### Forensics — the exit hard face says which of three causes a `no_pgid` receipt had (+2 trace lines; zero behavior face; +0 exports, +0 wire keys) (@server)
+
+- `killAllBackgroundShellsNow` folds three facts into one `no_pgid` receipt: the env has no synchronous kill seat, the seat answered `no_pgid` itself, or the seat threw. Only the third left a trace line. Two more, same form, same opt-in (`SEMA_DEBUG_SHUTDOWN=1`, stderr): `hard kill: seat absent` and `hard kill: seat answered no_pgid`, each with `{ id, shellId }`. The seat is now read once, inside the guard, so a READ that throws (a revoked membrane) is traced as `seat threw` and costs only its row — before this, the presence check sat inside the guard too. Receipts, row states and the per-row `hard kill: row` line are unchanged; an answer outside the closed set is still folded to `no_pgid` with the per-row line only. Contract text: `docs/background-process-lifetime.md` (Receipts). Pins: `test/backlog1107-hard-kill-forensics.test.ts` (the trace sink mocked: three arms, one line each, receipts `no_pgid`, rows `running`; a throwing READ of the seat costs its row only and the next row is killed; the seat called with its env as `this`; a seat that killed or found the shell gone leaves no seat line).
+
+### Test hygiene — `test/mcp-pagination.test.ts` no longer reads the host's `MCP_TOOL_TIMEOUT` (zero behavior face; +0 exports)
+
+- The page-walk pins measure the DEFAULT budget; with the variable set in the host env two of them went red on any branch. The file now clears it for its own run and restores it after (red-before / green-after verified at the fix).
+- `test/backlog994-s1-gaps-real-shells.test.ts`: the `echo x |& cat` pin compared the two pipeline stages' xtrace lines in a fixed order; the stages are concurrent processes, so the order is a race (one red in 23 546 on the stage run). The pin now compares membership; the other assertions of that pin are unchanged.
+
+## 7.33.0 — 2026-09-26
+
+### Model-call timeouts re-cut by segment: the header wait gets its own `firstByteTimeoutMs`, and every request carries the engine's dispatcher with the transport's header/body clocks off (#1121 #1122; behaviour: a pre-headers stall is a `stall` with its own one-retry lane, not a `transport` failure re-sent ten times; every watchdog defaults ON; +1 optional key `BrainTimeoutConfig.firstByteTimeoutMs`; **`BrainTimeoutConfig.connectTimeoutMs` REMOVED**; `StallTimeouts.connectMs` → `firstByteMs` (type-face breaking, see below); `WORKFLOW_AGENT_STALL_MS` 630 s → 1 500 s (derived); +1 dependency `undici@7.30.0`; `engines.node` `>=20.18.1`) (@server @cli @client-core)
+
+- **Before.** Two shapes, both reported against a self-hosted gateway. (1) The knob named `connectTimeoutMs` (advisory 30 s) actually bounded the `fetch()` call → response headers. A gateway that runs its prefill BEFORE writing headers was cut at 30 s, the cut was announced as `errClass: "transport"` / "connection lost, reconnecting" (nothing about the link was observed — this process cancelled its own request), and the identical body was re-sent through the transient ladder up to `maxRetries` (10) times: ~8.5 minutes of burned prefill ending in "connect timeout after 30000ms". (2) `config.fetchImpl ?? fetch` handed the request to Node's global `fetch`, whose undici transport keeps a 300 s headers clock and a 300 s body-silence clock that nothing here set or named; they sat UNDER `firstTokenTimeoutMs` (600 s) and `idleTimeoutMs`, so a value above 300 s was never granted, the cut arrived as a read rejection reported `transport`, and raising the knob changed nothing, silently.
+- **Three engine clocks, one per segment the engine can see, one definition (`src/brain/timeout.ts`).** The TCP + TLS connect is the transport's own clock (undici's 10 s by default, tuned on the process dispatcher the host installs); it is not a knob here.
+
+  | segment | key (`BrainTimeoutConfig`, all optional) | default | enforced by | on expiry |
+  |---|---|---|---|---|
+  | `fetch()` call → response headers | `firstByteTimeoutMs` — **new** | `STALL_FIRST_BYTE_MS` 300 s, plus 1 s per 32 KiB of request body (rounded up); the one retry runs at 2× the knob | the engine (per-attempt abort controller) | `stall`: retry frame `first-byte watchdog fired after <window>ms (firstByteTimeoutMs[ <knob> + <n> upload allowance]), retrying`, `maxRetries: 1`; terminal `[network] first-byte timeout: no response headers within <w1>ms, then <w2>ms on the retry (firstByteTimeoutMs) — if a proxy or gateway holds responses until they complete, raise firstByteTimeoutMs to wait longer` |
+  | headers → first content delta | `firstTokenTimeoutMs` | `STALL_FIRST_TOKEN_MS` 600 s | the engine | unchanged (`first-token watchdog fired …`) |
+  | delta → delta | `idleTimeoutMs` | `STALL_IDLE_MS` **300 s** (was 90 s; the reference implementation's idle floor — ruled to follow) | the engine | unchanged (`stream idle watchdog fired …`) |
+
+- **One resolution chain for every knob** (`resolveWatchdogMs`): construction config (an explicit `0` is OFF) > per-call advisory `StreamOptions.stallTimeouts` (the Runner sends the same defaults on every call; a BYOM brain reads them as its hint) > the engine default constant. The old third level "both absent ⇒ off" is retired: a brain built with no timeout config and used outside the Runner used to have NO engine watchdog at all and rode on the transport's accidental 300 s. **Who is hurt.** A deployment that constructed a first-party brain with no timeout fields and relied on it having none: it now arms 300 / 600 / 300 s (first byte / first token / idle). The idle default is the reference implementation's 300 s floor (ruled to follow), so a call that carried no advisory keeps the same 300 s of tolerated mid-stream silence the transport's body clock used to give it — now as the engine's own watchdog with a `stall` announcement instead of a transport failure; an Anthropic `ping` is still not a content delta, so a server-side tool that keeps the stream silent past 300 s is cut and, with text already streamed, committed by tier A (unchanged bound, new announcer). The number is not changed here; it is in #1125's candidate material. **Compensation.** `0` on the field it wants off (deployment sovereignty, unchanged), or a larger `idleTimeoutMs`.
+- **The first-byte lane** has its OWN budget (`FIRST_BYTE_RETRY_BUDGET` = 1, independent of `maxRetries`, like the thinking-only tier's), widens the knob ×2 on the retry (`FIRST_BYTE_RETRY_WINDOW_FACTOR`), re-sends the same body exactly once, and never claims the link dropped. The retry frame and the operator telemetry read one mapping (`retryAnnouncement`), the same one the post-headers watchdogs already used — a phase has no dialect of its own. The **wait disclosure** (`waiting_first_token`, first frame at 30 s then every 30 s) now runs during the header wait too, reporting the first-byte window as `timeoutMs`; before, a 5-minute header hold showed nothing until the wrong "reconnecting".
+- **The transport seat** (`src/brain/transport.ts`, one `resolveFetch` for all three brains): every request goes to the caller's `fetchImpl` (else Node's global `fetch`) with ONE addition to its init — `ENGINE_DISPATCHER`, a transparent stand-in for the PROCESS's dispatcher that differs from it in one place: each request it dispatches carries `headersTimeout: 0, bodyTimeout: 0`. The sending members undici's Dispatcher base builds on `dispatch` (`request`, `compose`, …, read off the base class, not listed) stay the engine's, so a `fetchImpl` that composes interceptors over `init.dispatcher` still sends with the clocks off, keeps every interceptor and reaches its own fetch's slot; every other member (`isMockActive`, `close`, events, …) is read off the host's dispatcher when accessed — nothing is listed, so a host `MockAgent` sees the request body and intercepts as it does for the host's own requests. Which host dispatcher: the one the CALLING fetch would resolve on its own — undici keeps one process slot per Dispatcher-API version (`undici.globalDispatcher.1` for every undici ≤ 7 including Node's built-in fetch, `.2` for undici 8), and the handler the fetch passes says which (undici's own test: `onRequestStart` ⇒ v2); resolved per request. Proxies, CA trust, mTLS, mocks and the connect clock stay whatever the host installed with `setGlobalDispatcher`. Consequence: `firstTokenTimeoutMs` / `idleTimeoutMs` above 300 s are now actually granted, on Node's fetch and on any `fetchImpl` that forwards `init` to a fetch. On an undici 8 host a v1 caller (Node's built-in fetch) goes through undici 8's slot-1 translation, which forces HTTP/1.1 and leaves a `MockAgent`'s interceptors — for the host's own plain requests too; a `fetchImpl` that is undici 8's `fetch` reaches the real dispatcher (KL-1121h). **The slot is the API**: slot 1 (`…globalDispatcher.1`) is always handed a v1 handler and slot 2 a v2 one, through undici's own converters (`lib/handler/unwrap-handler.js` / `wrap-handler.js`), so a composed chain whose interceptor rewraps the handler to v2 (undici 7's `interceptors.retry()`) still reaches an undici 6 host in slot 1 (before this rule: `UND_ERR_INVALID_ARG invalid onError method` and a retry loop).
+- **`fetchImpl` contract.** It receives `init.dispatcher = ENGINE_DISPATCHER` beside the method / headers / body / signal it always received. A wrapper that forwards `init` to Node's `fetch` gets the seat for free; a fetch that ignores `init.dispatcher` (another HTTP stack, a fetch that rebuilds its init) keeps its own transport's clocks under the engine's — the engine cannot see or lift them (KL-1121a): with undici's defaults its 300 s header clock fires before the engine's first-byte window (≥ 301 s: 300 s + at least 1 s of upload allowance), so the one-retry first-byte lane is never reached — the cut is reported `transport`, re-sent through the shared ladder, and a dead gateway reaches the terminal after about 11 × 300 s. The engine's three watchdogs arm regardless; a first-byte cut still requires the fetch to honour `init.signal`.
+- **`connectTimeoutMs` removed — who is hurt / compensation.** The knob bounded the header wait, which is now `firstByteTimeoutMs`; the TCP + TLS connect it was named for is the transport's own clock, tuned on the process dispatcher (`setGlobalDispatcher(new Agent({ connect: { timeout } }))`) — the engine has no honest home for a connect number, so the key is gone rather than kept with a changed meaning or a silent no-op. A host passing it fails loudly at upgrade — a literal does not compile, and a spread (`{ ...timeouts }`) or a JS caller, which the compiler cannot see, is refused by the brain factory (`config.stall_timeout_retired`, naming `firstByteTimeoutMs`) rather than ignored — and moves the number to `firstByteTimeoutMs` (a host that wants the old 30 s header cut spells it `firstByteTimeoutMs: 30_000`). **@server** `MODEL_CONNECT_TIMEOUT_MS` fed this key through a spread (`src/brain.ts` `timeouts`) — that shape compiles, and `createBrain` throws at construction until the key is dropped; it maps to `firstByteTimeoutMs` now (the env's own doc, "连接超时 … 0=关", described the header wait), and `0` there still means off. **@cli / @client-core** the retry frame for a pre-headers cut now carries `errClass: "stall"` with a detail that names `firstByteTimeoutMs`; a renderer that special-cased "connection lost" for that case sees a stall.
+- **Hard breaking (type face).** ① `BrainTimeoutConfig.connectTimeoutMs` is removed: a literal passing it fails to compile; a spread or a JS caller passing it is refused at run time by all three brain factories (`config.stall_timeout_retired`, the message names `firstByteTimeoutMs`) — the key's presence is refused even with an `undefined` value; the header wait it bounded is `firstByteTimeoutMs`. ② `StallTimeouts.connectMs` is removed and `firstByteMs` added: a literal with `connectMs` fails to compile; a spread or a JS caller that still sends it gets the CALL refused (stop reason `error`, the message names `firstByteMs`, nothing sent); a reader sees `firstByteMs`. ③ `WORKFLOW_AGENT_STALL_MS` is now `firstByteLaneKnobMs(STALL_FIRST_BYTE_MS) + STALL_FIRST_TOKEN_MS` = 1 500 000 (was 630 000): the floor is what one call may legitimately spend producing nothing — the first-byte probe and every widened retry the lane's budget allows (`FIRST_BYTE_RETRY_BUDGET`, `FIRST_BYTE_RETRY_WINDOW_FACTOR`), then the first-token wait — so a workflow's per-agent progress watchdog waits longer before restarting a silent agent (the derivation's whole point: an outer, coarser clock must not fire before the engine's own; the body-dependent upload allowance and the backoff between attempts are not counted, so it is a lower bound). ④ `engines.node` rises from `>=20.3.0` to `>=20.18.1`, the floor `undici@7.30.0` states; Node 20.18.1 is on the same LTS line.
+- **Dependency decision — `undici@7.30.0` (exact) enters `dependencies`.** Node exposes neither its dispatcher classes nor `getGlobalDispatcher`; the npm package does, and it shares the process-wide dispatcher slot with Node's own `fetch` (the documented `setGlobalDispatcher` contract), which is what lets the engine forward to whatever the host installed. undici 6 would have kept `>=18.17` but is the previous major. Stated side effect of the import (KL-1121c): if slot 1 is still empty, undici writes its default `Agent` (the same defaults as Node's own) into both process slots — measured on Node 20.18.1 at import of the package entry (the host's plain `fetch` then uses it too); on Node 24 it depends on load order. Anchored on the reference implementation's shape: an independent first-byte window with its own knob and a one-retry cap, a request-body upload allowance, a widened retry, and the gateway hint — its default for a non-first-party route (300 s) is the default here.
+- **Unchanged here, stated.** A model call whose watchdog is `0` has no bound on that segment at all now (the transport's clocks are 0 too); under the Runner the hour-scale guardrail remains, and the calls outside it (compaction, side-query, memory consolidation, the classifier, prompt suggestions) are listed with their own bounds in `docs/TIMEOUTS.md`. The memory distiller's model call is not on the seat yet (#1127).
+- Pins: `test/backlog1121-model-timeouts.test.ts` (window arithmetic; the chain; the engine dispatcher forwarding to the process dispatcher with the clocks off — pure and on the real transport with a spied host `Agent`; the slot chosen by the handler's Dispatcher-API version — Node's built-in fetch and npm undici 7's fetch reach slot 1 past a v2-only dispatcher in slot 2, a v2 handler reaches slot 2; every other member read off the host while `compose` / `request` keep the clocks off; a host `MockAgent` with a string body matcher in either slot, net connect disabled and enabled, and end to end through a brain — matched, 0 real requests; `isMockActive` true against a real dispatcher delivers the body intact; the retired keys refused by all three factories and per call; a deadline between the transport's headers and `doFetch` returning taken as a stall; the `fetchImpl` init carrying the seat; three fake-gateway arms against a local HTTP server — headers held, headers never, first data held — plus a contrast arm with an undici body clock; the first-byte and idle defaults pinned at the call site; the header-wait disclosure and the truthful closing frame under fake timers). Re-pinned: `test/walltime-stall-watchdog.test.ts`, `test/resilience.test.ts`, `test/backlog682-stall-retry-announcement.test.ts`, `test/stream-options-forwarding.test.ts`, `test/brain-resilience-coverage.test.ts`. Wire sheet: `docs/wire-consumption/unreleased-1121.md`. The timeout table: `docs/TIMEOUTS.md`.
+
+### Type surface — `TaskRegistry.retainedShellIds` removed (#1120 follow-up; +0 wire keys)
+
+- **Removed (type surface).** `TaskRegistry.retainedShellIds(env)` is gone. Since 7.32.1 nothing in `src` calls it (the park-only parks share the run-boundary dispose, whose keep-list is `runningShellIds(env)`). No caller was found in the server / cli / client-core trees. Read `runningShellIds(env)` with `list(access)` rows' `retained` instead.
+
 ## 7.32.1 — 2026-09-25
 
 ### Fix — a park that does not pause the env no longer stops the session's background shells (#1120; behavior; +0 exports, +0 wire keys) (@cli @server)
@@ -1062,7 +1128,7 @@ with the next package release.
 - **Who is hurt.** A caller that relied on the file backend folding an unnamed kind into a delete — none in-tree, and the behaviour was unreachable through a typed call. Exports +2 (`permissionRuleWriteContract`, `PermissionRuleWriteContractHooks`), removals 0.
 - Reach: **@server** — the store twin's acceptance floor gains one suite to run (the sync kit is unchanged); **@cli** / **@client-core** — zero. Headless: a malformed delta from a foreign backend caller now throws where the file backend previously wrote a tombstone. `test/backlog996-write-delta-kinds.test.ts`.
 ### A mandate is a fact about the ask, not about a lane — `AskRequest.mandated` (#997; P2; approval face; additive, no export change)
-- **Before.** The only way an approval surface could learn that a card was MANDATED — that no persisted allow rule and no standing posture could retire it — was `AskRequest.ruleOffersAbsence === "mandated"`, a seat that reports what the RULE-OFFER LANE has to give. That lane speaks for one tool, only where a rule store is wired, and only on a task that can hold a rule; its own contract says absence is not a claim. Measured on the base of this entry, real Runner, `cat <path outside the session roots>`, both `shellGate` doctrines: `Bash` with a store and a principal carried `"mandated"`; the SAME command on `Monitor`, on `Bash` with no store, and on an anonymous task carried nothing. One approval card in every row; the mandate — the read station's own structural demotion — present in every row.
+- **Before.** The only way an approval surface could learn that a card was MANDATED — that no persisted allow rule and no standing answer (a release remembered from an earlier call) could retire it, while an answer given for that call still could — was `AskRequest.ruleOffersAbsence === "mandated"`, a seat that reports what the RULE-OFFER LANE has to give. That lane speaks for one tool, only where a rule store is wired, and only on a task that can hold a rule; its own contract says absence is not a claim. Measured on the base of this entry, real Runner, `cat <path outside the session roots>`, both `shellGate` doctrines: `Bash` with a store and a principal carried `"mandated"`; the SAME command on `Monitor`, on `Bash` with no store, and on an anonymous task carried nothing. One approval card in every row; the mandate — the read station's own structural demotion — present in every row.
 - **After.** `AskRequest.mandated?: true` (and the `PermissionResult` ask-arm member it is copied from) states it on the ask. Minted ONCE, at the gate's single origin stamp, from the one derivation the card's rule-offer word is also read from (`ruleClearanceOf`): the door SET decides the bit, the incumbent display ladder decides the word. Which door a card shows is a display choice; whether the ask is mandated is not — so a card worded `shadowed` over a probe mandate is mandated all the same, which the two-enumeration shape got wrong.
 - **The doors,** in one place: the tool seat's `egress` / `irreversibility` marks, an operator `shellGate: "always"`, the shell read station's structural demotion or a probe that timed out or threw, a write the protection judge matched or could not resolve, `requiresRealApproval`, a hook-raised ask, and an ask decided at an ANCESTOR's frozen approver. **Not** a door: a person's own explicit `ask` permission rule — the lane words that `shadowed`, because a rule they wrote is already speaking.
 - **What the bit says, and what it does not.** It says a persisted allow RULE may not clear the card. It does NOT say an approver may not answer it: a person, a hook and a deployment's blanket `onAsk: "allow"` seat all resolve a mandated ask exactly as before, and `requiresRealApproval` remains the separate, stronger "a person, not a configuration" demand. A shell whose POSTURE seat declines to auto-answer mandated cards reads this member to know which they are — @cli L-459, @client-core CC-110 (frame mirror), @server in transit. Absent on an older engine is not the opposite claim; tell the two apart by engine version, not by this seat.

package/dist/brain/anthropic.d.ts

@@ -9,7 +9,7 @@ export interface AnthropicBrainConfig extends StreamEngineConfig {
     version?: string;
     /** Extra headers merged into every request (e.g. `anthropic-beta`). */
     headers?: Record<string, string>;
-    /** Custom fetch (tests / proxies). Defaults to global fetch. */
+    /** Custom fetch (tests / proxies); absent ⇒ the engine's default transport — see `resolveFetch`. */
     fetchImpl?: typeof fetch;
     /** `max_tokens` when the call/model doesn't specify one (Anthropic requires it). Default 4096. */
     defaultMaxTokens?: number;

package/dist/brain/anthropic.js

@@ -10,6 +10,8 @@ import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap
 import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
+import { refuseRetiredTimeoutKnobs } from "./timeout.js";
+import { resolveFetch } from "./transport.js";
 function thinkingBudget(maxTokens, share, fixed, hardCap = false) {
     const max = hardCap ? maxTokens : Math.max(maxTokens, MIN_THINKING_TOKENS * 2);
     const want = fixed ?? Math.floor(max * share);
@@ -225,7 +227,8 @@ function closeToolUseBlock(acc) {
 }
 export function createAnthropicBrain(config = {}) {
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
-    const doFetch = config.fetchImpl ?? fetch;
+    refuseRetiredTimeoutKnobs(config, "construction", "createAnthropicBrain config");
+    const doFetch = resolveFetch(config);
     const cacheBreakpoints = config.cacheBreakpoints !== false;
     const stream = (model, context, options) => {
         let thinkingRequested = false;

package/dist/brain/open-responses.d.ts

@@ -7,7 +7,8 @@ export interface OpenResponsesBrainConfig extends StreamEngineConfig {
     apiKey?: string;
     /** Extra headers merged into every request (auth + content-type are hard-locked after the merge). */
     headers?: Record<string, string>;
-    /** Inject a custom fetch (tests / proxies). Defaults to global fetch. */
+    /** Inject a custom fetch (tests / proxies); the default transport and the `fetchImpl` seat are
+     *  `resolveFetch` (transport.ts). */
     fetchImpl?: typeof fetch;
     /**
      * Replay prior assistant reasoning items back to the endpoint on the turns that carry tool calls

package/dist/brain/open-responses.js

@@ -9,6 +9,8 @@ import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap
 import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
+import { refuseRetiredTimeoutKnobs } from "./timeout.js";
+import { resolveFetch } from "./transport.js";
 const DEGENERATE_POLL_CHARS = 64;
 const MALFORMED_SAMPLE_CHARS = 160;
 const MALFORMED_ARGS_CHARS = 200;
@@ -218,7 +220,8 @@ function mapTerminalStopReason(incompleteReason, hadToolCalls) {
 }
 export function createOpenResponsesBrain(config = {}) {
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
-    const doFetch = config.fetchImpl ?? fetch;
+    refuseRetiredTimeoutKnobs(config, "construction", "createOpenResponsesBrain config");
+    const doFetch = resolveFetch(config);
     const stream = (model, context, options) => {
         let sentMaxTokens;
         let sentMaxTokensLane = "unset";

package/dist/brain/openai.d.ts

@@ -7,7 +7,8 @@ export interface OpenAIBrainConfig extends StreamEngineConfig {
     apiKey?: string;
     /** Extra headers merged into every request. */
     headers?: Record<string, string>;
-    /** Inject a custom fetch (tests / proxies). Defaults to global fetch. */
+    /** Inject a custom fetch (tests / proxies). Absent ⇒ the engine's default transport; the contract for
+     *  both cases is `resolveFetch` (transport.ts). */
     fetchImpl?: typeof fetch;
     /**
      * For weaker models that emit tool calls as TEXT (`<tool_call>{...}</tool_call>` / fenced json)

package/dist/brain/openai.js

@@ -10,6 +10,8 @@ import { BrainError } from "./errors.js";
 import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
+import { refuseRetiredTimeoutKnobs } from "./timeout.js";
+import { resolveFetch } from "./transport.js";
 function closeToolCallAccum(acc) {
     if (acc.closedTc)
         return acc.closedTc;
@@ -282,7 +284,8 @@ export function inferMaxTokensField(modelId) {
 }
 export function createOpenAIBrain(config = {}) {
     assertServableRequestRoot(config.baseUrl, "config.baseUrl");
-    const doFetch = config.fetchImpl ?? fetch;
+    refuseRetiredTimeoutKnobs(config, "construction", "createOpenAIBrain config");
+    const doFetch = resolveFetch(config);
     const stream = (model, context, options) => {
         let sentMaxTokens;
         let sentMaxTokensLane = "unset";

package/dist/brain/stream-engine.d.ts

@@ -4,7 +4,7 @@ import { type BrainTimeoutConfig } from "./timeout.js";
  * Shared streaming engine for the OpenAI- and Anthropic-shaped brains (design/32, consolidation).
  *
  * It owns the **bug-prone machinery that was duplicated verbatim** across `openai.ts` and
- * `anthropic.ts` — the connect-timeout + retry loop, the three-tier timer logic (first-token + idle
+ * `anthropic.ts` — the first-byte window + retry loop, the three-tier timer logic (first-token + idle
  * watchdog) with their flag resets, the SSE read loop + line framing, the one-shot cleanup, and the
  * `.catch/.finally` error wrapping. Centralizing the timer logic is the point: the same first-token /
  * idle reset bug was fixed twice (1.38.2 / 1.40.2) precisely because this lived in two copies.
@@ -231,14 +231,15 @@ export declare function runStreamingBrain(args: {
     makeParser: (ctrl: StreamControls) => StreamParser;
     /**
      * 1.296 件A — per-call ADVISORY stall watchdogs (`StreamOptions.stallTimeouts`). Priority chain:
-     * brain construction-time config (`BrainTimeoutConfig.connectTimeoutMs`/`firstTokenTimeoutMs`/
-     * `idleTimeoutMs`) wins whenever PRESENT — including an explicit 0/negative, which means
-     * "deliberately disabled" — and only an ABSENT (undefined) field adopts the advisory value; both
-     * absent ⇒ off. `connectMs` bounds the fetch→response-headers wait: the engine's post-headers
-     * timers can't see a gateway that never returns headers.
+     * brain construction-time config (`BrainTimeoutConfig.firstByteTimeoutMs`/`firstTokenTimeoutMs`/
+     * `idleTimeoutMs`) wins whenever PRESENT — including an explicit 0, which means "deliberately
+     * disabled" — and only an ABSENT (undefined) field adopts the advisory value; both absent ⇒ the
+     * engine default constant for that segment (`timeout.ts`). `firstByteMs` bounds the
+     * fetch→response-headers wait: the engine's post-headers timers can't see a gateway that never
+     * returns headers. The connect clock is not per-call: it is the process dispatcher's (`transport.ts`).
      */
     stallTimeouts?: {
-        connectMs?: number;
+        firstByteMs?: number;
         firstTokenMs?: number;
         idleMs?: number;
     };

package/dist/brain/stream-engine.js

@@ -6,7 +6,7 @@ import { stripUrlCredentials } from "./route-adjudicator.js";
 import { classifyInputTooLong } from "./input-too-long.js";
 import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.js";
 import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
-import { createConnectController, resolveStallTimeoutMs } from "./timeout.js";
+import { createAttemptController, firstByteWindow, refuseRetiredTimeoutKnobs, resolveFirstByteRetries, resolveWatchdogMs, STALL_FIRST_BYTE_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, } from "./timeout.js";
 import { readMember, thrownText } from "../core/thrown-value.js";
 import { redactSecrets } from "../core/untrusted-egress.js";
 const DEFAULT_MAX_RETRIES = 10;
@@ -250,10 +250,18 @@ async function sleepAnnouncingRetry(totalMs, signal, frame) {
             return;
     }
 }
-function midstreamRetryAnnouncement(failure) {
-    return failure.kind === "stalled"
-        ? { errClass: "stall", detail: `${failure.watchdog} watchdog fired after ${failure.timeoutMs}ms (${failure.knob}), retrying` }
-        : { errClass: "transport", detail: "connection lost, reconnecting" };
+function retryAnnouncement(failure) {
+    if (failure.kind !== "stalled")
+        return { errClass: "transport", detail: "connection lost, reconnecting" };
+    const knob = failure.allowanceMs !== undefined && failure.allowanceMs > 0
+        ? `${failure.knob} ${failure.timeoutMs - failure.allowanceMs} + ${failure.allowanceMs} upload allowance`
+        : failure.knob;
+    return { errClass: "stall", detail: `${failure.watchdog} watchdog fired after ${failure.timeoutMs}ms (${knob}), retrying` };
+}
+function firstByteTimeoutMessage(windowsMs) {
+    const [first, ...retries] = windowsMs;
+    const waited = retries.length === 0 ? `within ${first ?? 0}ms` : `within ${first ?? 0}ms, then ${retries.map((w) => `${w}ms`).join(", then ")} on the retry`;
+    return `first-byte timeout: no response headers ${waited} (firstByteTimeoutMs) — if a proxy or gateway holds responses until they complete, raise firstByteTimeoutMs to wait longer`;
 }
 export function runStreamingBrain(args) {
     const { model, doFetch, signal, config, httpLabel, buildRequest, makeParser, stallTimeouts } = args;
@@ -262,6 +270,7 @@ export function runStreamingBrain(args) {
     let announcedRetry = false;
     let announcedWait = false;
     let terminalWaitDetail = "first token arrived";
+    let firstTokenArrived = false;
     let terminalRetryPhase = "recovered";
     let terminalRetryDetail = "recovered after retrying";
     let requestIdSeen;
@@ -271,7 +280,13 @@ export function runStreamingBrain(args) {
         const aborted = signal?.aborted === true || isAbortError(err);
         terminalRetryPhase = "gave_up";
         terminalRetryDetail = aborted ? "cancelled while retrying" : "retries exhausted";
-        terminalWaitDetail = aborted ? "cancelled while waiting for the first token" : "the first-token wait ended in failure";
+        terminalWaitDetail = firstTokenArrived
+            ? aborted
+                ? "cancelled after the first token arrived"
+                : "the call failed after the first token arrived"
+            : aborted
+                ? "cancelled while waiting for the first token"
+                : "the first-token wait ended in failure";
         const errorMsg = emptyAssistant(model);
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = thrownText(err);
@@ -315,33 +330,84 @@ export function runStreamingBrain(args) {
         const baseDelay = config.retryDelayMs ?? 500;
         const deterministicConnectBudget = Math.min(resolveDeterministicConnectRetries(config.deterministicConnectRetries), maxRetries);
         const deterministicLaneActive = deterministicConnectBudget < maxRetries;
-        const firstTokenTimeoutMs = resolveStallTimeoutMs(config.firstTokenTimeoutMs ?? stallTimeouts?.firstTokenMs, "firstTokenTimeoutMs");
-        const idleTimeoutMs = resolveStallTimeoutMs(config.idleTimeoutMs ?? stallTimeouts?.idleMs, "idleTimeoutMs");
-        const connectTimeoutMs = resolveStallTimeoutMs(config.connectTimeoutMs ?? stallTimeouts?.connectMs, "connectTimeoutMs");
+        refuseRetiredTimeoutKnobs(stallTimeouts, "advisory", "StreamOptions.stallTimeouts");
+        const firstByteTimeoutMs = resolveWatchdogMs(config.firstByteTimeoutMs, stallTimeouts?.firstByteMs, STALL_FIRST_BYTE_MS, "firstByteTimeoutMs");
+        const firstTokenTimeoutMs = resolveWatchdogMs(config.firstTokenTimeoutMs, stallTimeouts?.firstTokenMs, STALL_FIRST_TOKEN_MS, "firstTokenTimeoutMs");
+        const idleTimeoutMs = resolveWatchdogMs(config.idleTimeoutMs, stallTimeouts?.idleMs, STALL_IDLE_MS, "idleTimeoutMs");
+        const firstByteRetryBudget = resolveFirstByteRetries(config.firstByteRetries);
+        const armWaitDisclosure = (ceilingMs) => {
+            if (!(ceilingMs > WAITING_FIRST_TOKEN_AFTER_MS))
+                return { stop: () => undefined };
+            const startedAt = Date.now();
+            const emitWaitFrame = bindBrainStatusEmitter();
+            let timer;
+            let stopped = false;
+            const schedule = (delayMs) => {
+                timer = setTimeout(() => {
+                    timer = undefined;
+                    if (stopped || Date.now() - startedAt >= ceilingMs)
+                        return;
+                    announcedWait = true;
+                    emitWaitFrame({ phase: "waiting_first_token", detail: "waiting for the first token", elapsedMs: Date.now() - startedAt, timeoutMs: ceilingMs });
+                    schedule(WAITING_FIRST_TOKEN_EVERY_MS);
+                }, delayMs);
+            };
+            schedule(WAITING_FIRST_TOKEN_AFTER_MS);
+            return {
+                stop: () => {
+                    stopped = true;
+                    if (timer)
+                        clearTimeout(timer);
+                    timer = undefined;
+                },
+            };
+        };
         let attempt = 0;
         let thinkingRetries = 0;
+        let firstByteStalls = 0;
+        const firstByteWindowsWaited = [];
         let startEmitted = false;
         for (;;) {
             let res;
             let connect;
-            for (;; attempt++) {
+            for (;;) {
                 if (signal?.aborted) {
                     const e = new Error("aborted");
                     e.name = "AbortError";
                     throw e;
                 }
-                const cc = createConnectController(connectTimeoutMs, signal);
+                const window = firstByteWindow(firstByteTimeoutMs, Buffer.byteLength(req.body), firstByteStalls);
+                const cc = createAttemptController(window.windowMs, signal);
                 let r;
                 let netErr;
+                let firstByteStall;
                 requestIdSeen = undefined;
                 attemptPartial = undefined;
+                const headerWait = armWaitDisclosure(window.windowMs);
+                const stalledAtFirstByte = () => {
+                    firstByteWindowsWaited.push(window.windowMs);
+                    return {
+                        kind: "stalled",
+                        watchdog: "first-byte",
+                        knob: "firstByteTimeoutMs",
+                        timeoutMs: window.windowMs,
+                        allowanceMs: window.allowanceMs,
+                        err: new BrainError("network", firstByteTimeoutMessage(firstByteWindowsWaited), undefined, { apiError: true }),
+                    };
+                };
                 try {
                     r = await doFetch(req.url, { method: "POST", headers: req.headers, body: req.body, signal: cc.signal });
                     requestIdSeen = readProviderRequestId(r);
+                    if (cc.timedOut()) {
+                        discardResponseBody(r);
+                        r = undefined;
+                        requestIdSeen = undefined;
+                        firstByteStall = stalledAtFirstByte();
+                    }
                 }
                 catch (e) {
                     if (cc.timedOut()) {
-                        netErr = new Error(`connect timeout after ${connectTimeoutMs}ms`);
+                        firstByteStall = stalledAtFirstByte();
                     }
                     else if (isAbortError(e) || signal?.aborted) {
                         cc.dispose();
@@ -355,6 +421,9 @@ export function runStreamingBrain(args) {
                         netErr = e;
                     }
                 }
+                finally {
+                    headerWait.stop();
+                }
                 if (r && r.ok && r.body) {
                     cc.clearTimer();
                     connect = cc;
@@ -364,6 +433,27 @@ export function runStreamingBrain(args) {
                 }
                 cc.clearTimer();
                 try {
+                    if (firstByteStall !== undefined) {
+                        if (firstByteStalls >= firstByteRetryBudget)
+                            throw firstByteStall.err;
+                        firstByteStalls++;
+                        const announcement = retryAnnouncement(firstByteStall);
+                        const delayMs = retryBackoffMs(baseDelay, firstByteStalls - 1);
+                        emitBrainTelemetry({ kind: "retry", attempt: firstByteStalls, phase: "connect", errClass: announcement.errClass, nextDelayMs: delayMs });
+                        announcedRetry = true;
+                        cc.abort();
+                        cc.dispose();
+                        await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
+                            phase: "reconnecting",
+                            detail: announcement.detail,
+                            retryInSec: Math.ceil(remainingMs / 1000),
+                            retryInMs: remainingMs,
+                            attempt: firstByteStalls,
+                            maxRetries: firstByteRetryBudget,
+                            errClass: announcement.errClass,
+                        }));
+                        continue;
+                    }
                     let overflowBody;
                     let overflowDeclineNote = "";
                     if (r !== undefined && r.status === 400) {
@@ -402,6 +492,7 @@ export function runStreamingBrain(args) {
                                         errClass: "output_cap",
                                         ...(namesTheFailure(r?.status) ? { errorStatus: r.status } : {}),
                                     });
+                                    attempt++;
                                     continue;
                                 }
                                 overflowDeclineNote =
@@ -468,6 +559,7 @@ export function runStreamingBrain(args) {
                             errClass,
                             ...(retryStatus !== undefined ? { errorStatus: retryStatus } : {}),
                         }));
+                        attempt++;
                         continue;
                     }
                     if (netErr)
@@ -494,39 +586,14 @@ export function runStreamingBrain(args) {
             let firstTokenSeen = false;
             let firedFirstTokenDeadlineMs;
             let ftTimer;
-            let waitTimer;
-            const clearWaitTimer = () => {
-                if (waitTimer) {
-                    clearTimeout(waitTimer);
-                    waitTimer = undefined;
-                }
-            };
+            let firstTokenWait = { stop: () => undefined };
             if (firstTokenTimeoutMs && firstTokenTimeoutMs > 0) {
                 ftTimer = setTimeout(() => {
                     firedFirstTokenDeadlineMs = firstTokenTimeoutMs;
-                    clearWaitTimer();
+                    firstTokenWait.stop();
                     void reader.cancel().catch(() => undefined);
                 }, firstTokenTimeoutMs);
-                if (firstTokenTimeoutMs > WAITING_FIRST_TOKEN_AFTER_MS) {
-                    const waitStartedAt = Date.now();
-                    const emitWaitFrame = bindBrainStatusEmitter();
-                    const scheduleWaitFrame = (delayMs) => {
-                        waitTimer = setTimeout(() => {
-                            waitTimer = undefined;
-                            if (firstTokenSeen || firedFirstTokenDeadlineMs !== undefined || Date.now() - waitStartedAt >= firstTokenTimeoutMs)
-                                return;
-                            announcedWait = true;
-                            emitWaitFrame({
-                                phase: "waiting_first_token",
-                                detail: "waiting for the first token",
-                                elapsedMs: Date.now() - waitStartedAt,
-                                timeoutMs: firstTokenTimeoutMs,
-                            });
-                            scheduleWaitFrame(WAITING_FIRST_TOKEN_EVERY_MS);
-                        }, delayMs);
-                    };
-                    scheduleWaitFrame(WAITING_FIRST_TOKEN_AFTER_MS);
-                }
+                firstTokenWait = armWaitDisclosure(firstTokenTimeoutMs);
             }
             let firedIdleDeadlineMs;
             let idleTimer;
@@ -546,19 +613,20 @@ export function runStreamingBrain(args) {
                 if (firstTokenSeen)
                     return;
                 firstTokenSeen = true;
+                firstTokenArrived = true;
                 firedFirstTokenDeadlineMs = undefined;
                 if (ftTimer) {
                     clearTimeout(ftTimer);
                     ftTimer = undefined;
                 }
-                clearWaitTimer();
+                firstTokenWait.stop();
             };
             cleanup = () => {
                 if (ftTimer) {
                     clearTimeout(ftTimer);
                     ftTimer = undefined;
                 }
-                clearWaitTimer();
+                firstTokenWait.stop();
                 if (idleTimer) {
                     clearTimeout(idleTimer);
                     idleTimer = undefined;
@@ -631,7 +699,7 @@ export function runStreamingBrain(args) {
                 clearTimeout(ftTimer);
                 ftTimer = undefined;
             }
-            clearWaitTimer();
+            firstTokenWait.stop();
             if (idleTimer) {
                 clearTimeout(idleTimer);
                 idleTimer = undefined;
@@ -678,7 +746,7 @@ export function runStreamingBrain(args) {
                 throw failure.err;
             cleanup?.();
             cleanup = undefined;
-            const announcement = midstreamRetryAnnouncement(failure);
+            const announcement = retryAnnouncement(failure);
             if (snap.hasOnlyThinking) {
                 if (thinkingRetries >= THINKING_RETRY_BUDGET)
                     throw failure.err;