@sema-agent/core 5.21.1 → 5.23.0

package/CHANGELOG.md

@@ -1,5 +1,108 @@
 # Changelog
 
+## 5.23.0 — 2026-08-10
+
+No BREAKING changes.
+
+### Added
+
+- **design/183 adoption protocol, core file half.** Root adoption marker + six-phase
+  `adoptLocalDataRoot` state machine + `readAdoptionStatus` standing introspection + config account
+  (witness/ack) + quarantine listing; 23 new exports. The I6 boot gate is a new refusal surface: every
+  file-store constructor under a root whose `adoption.json` marker is IN FLIGHT throws
+  `AdoptionError("adoption_in_flight")` (corrupt marker: `adoption_marker_corrupt`, fail-closed).
+  Roots without a marker are untouched. The terminal report carries `notMigratedByDesign` — the
+  machine-readable closed set of assets ruled to stay local, sharded per migration form.
+- **design/182 org layer wired into the decision chain** (org-governed deployments only): org deny
+  blocks on both the main gate and the durable-resume leg; an unavailable org snapshot past
+  `ORG_ADJUDICATION_TIMEOUT_MS` (15s, mandatory at both call sites) downgrades every terminal allow
+  to a human ask, fail-closed. Closed-set additions consumers should re-pin: `DecisionReason`
+  +`org_rule`/`org_unavailable`; `PermissionDeniedSource` +`org`; `TraceEvent`
+  +`rule_sync_resurrected`/`rule_sync_dropped`/`org_snapshot_unavailable`.
+- `AskOutcome` terminal arms accept an optional `settledBy` (host self-report; `allow` × `"timeout"`
+  is loudly refused); `GoalResult.budgetCause` names which ceiling ended a budget run;
+  `NON_GOVERNANCE_MEMORY_CODES` +3 members (`memory.challenge_ledger_oversize`,
+  `memory.control_plane_rebuilt`, `memory.control_plane_not_corrupt`);
+  `MemoryEngine.rebuildCorruptControlPlaneLedger` (host-only, refuses a healthy ledger, quarantines
+  corrupt bytes) and `CHALLENGE_LEDGER_MAX_EVENTS` disclosure threshold.
+
+### Fixed / narrowed
+
+- **#109**: separated option values (`head -c 5`, `cut -f 1`, `grep -A 3 pat`, …) are no longer
+  counted as file operands by the read-only shell classifier — fileless forms of these commands now
+  ask instead of auto-passing.
+- **#110**: a checkpoint `put` that errors but whose row is durably present (read-back claims it)
+  suspends instead of running on; `put`+`get` both failing aborts the run fail-closed.
+- **#114**: `settledBy:"timeout"` documented promise narrowed to the two core-managed wait windows.
+- **#115**: the offload truncation notice states where the remainder IS instead of implying any
+  caller can fetch it.
+- Consent-record ids and the in-memory CRDT actor default now take real entropy (`randomBytes`);
+  format is opaque, do not parse.
+
+### Tooling
+
+- New `gate:error-surface` (four invariants over model-visible error minting: no `.stack`,
+  >400-char templates ledgered, uncapped-arm ratchet, verbatim-guidance dedup) wired into CI.
+- The environment-knob surface (25 names) is under an exhaustive AST-driven liveness registry;
+  `docs/CONFIG-CATALOG-GUIDE.md` gained the environment-knobs chapter (two comment-only pseudo-knobs
+  called out: `MAX_TOOL_CONCURRENCY`, `APPROVAL_TTL_MS` — setting them has no effect).
+
+## 5.22.0 — 2026-08-09
+
+### BREAKING
+
+- **Checkpoint version 6 → 7.** A checkpoint row that carries the new inheritance-chain constraint
+  snapshot or delegation-provenance state is stamped v7; a pre-5.22 worker refuses it up front
+  (`checkpoint.unsupported_version`) instead of resuming with the ancestors' gate silently dropped.
+  Rows without the new faces keep their old stamp and resume everywhere.
+- **Durable re-supply contract: content digest replaces the count check.** Resuming a suspended task
+  under inherited constraints now verifies a `cpv1:` sha256 digest of the persisted constraint
+  projection (topology + decision-chain metadata: autoMode armed, durable/content mandates) — a
+  same-length substitute chain, or one that dropped the ancestor's classifier, is refused
+  (`resume.parent_constraint_mismatch`). Old checkpoints without a digest fall back to the count check.
+- **Approver-edited args re-adjudicate BEFORE the resolve CAS, and a refusal keeps the park pending.**
+  Previously the edit recheck ran after the checkpoint was consumed; a refusal now surfaces as
+  `resume.constraint_rejected` / `resume.constraint_unprojectable` with the checkpoint still
+  `pending` and re-decidable (new reopen reason `constraint_rejected`). Deployments that pinned the
+  old "resume completes, denial injected" shape must re-pin.
+- **`basePolicyForResumeEdit` absent no longer skips the edit recheck.** The knob becomes an
+  override; absence falls back to the deployment's locked preflight policy, so an approver edit is
+  never executed with zero re-adjudication. Configured deployments are unchanged.
+
+### Added
+
+- **Inheritance-chain decision-chain integrity (F-012).** Ancestor deny verdicts freeze into the
+  chain as a canonical projection; the ancestor's auto-mode classifier now travels with the chain
+  (both wrapper arms and the approved-edit recheck) — a delegated child no longer executes a call the
+  ancestor's own gate would have classified into a block. The budget ledger is documented as
+  task-scoped (it does not follow the chain), and the edit-recheck path now sees a real budget
+  snapshot instead of an absent one.
+- **Sandbox admission (opt-in, narrow form).** Under an execution environment that declares
+  `capabilities.isolation`, surviving engine-minted local asks on engine hand tools admit
+  automatically with a durable `permission.sandbox_admitted` disclosure (`decisionReason:"sandbox"`)
+  instead of parking. Caller-registered in-process tools never auto-admit — the isolation capability
+  only vouches for what runs inside that environment. Enabling the mode requires durable parking and
+  a checkpoint store that declares re-decision capability; otherwise preparation refuses loudly.
+- **Deterministic connect refusals take a short retry lane (#107).** ECONNREFUSED/ENOTFOUND-class
+  failures retry 2× with a 1s backoff cap instead of consuming the full transient budget
+  (measured 186s → 1.8s); `BrainStatus` and `brain.retry` telemetry carry a closed `errClass` and
+  the in-force lane budget. Consumers pinning the `reconnecting` detail text or reading
+  `maxRetries` as the engine-wide budget are affected.
+- **Delegation attestation persists across processes (design/180 R-4 half).** The three-value
+  delegation-provenance aggregate rides the durable checkpoint; a resumed leg missing the state
+  reads as `unknown` (static floor), never as `clean`.
+- **`buildToolResultRef` exported from the package root** — a host wiring an HTTP tool-result read
+  face binds an incoming ref to its owning task by prefix recomputation.
+- **Content mandate split from the approval mandate (#94).** A delegated child's question routes on
+  the QUESTION seat, not the approver seat. Behavior widening, called out explicitly: under
+  `durableApproval` with a live `onQuestion`, an absent or string approver seat used to leave child
+  questions undeliverable — they now reach the live question face. The permission leg is unchanged.
+- **Background-agent revival honesty (#84).** `resumable` answers the real revival ladder;
+  the revive lane distinguishes a transient `recycling` window (`resume.row_recycling`, retry) from
+  `row_gone` (terminal), checks access before disclosing row lifecycle, and
+  `TaskRegistry.reviveBackgroundAgent`'s refusal union gains the `recycling` member — exhaustive
+  consumers add one arm.
+
 ## 5.21.1 — 2026-08-09
 
 - **Fix: every `hands: none` deployment failed at the door on 5.21.0** (P0). `HAND_TOOL_EFFECTS`

package/dist/agents/send-message-tool.js

@@ -709,9 +709,12 @@ export function createSendMessageTool(opts) {
                                     : code === "steering.still_running"
                                         ?
                                             `${who} (or a prior follow-up to it) is still running — wait for its completion notification. ${DEDUP_RETRY_NOTE}`
-                                        : code === "resume.row_gone"
-                                            ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
-                                            : `${e instanceof Error ? e.message : String(e)} ${DEDUP_RETRY_NOTE}`;
+                                        : code === "resume.row_recycling"
+                                            ?
+                                                `${who}'s registry row is being adjudicated right now (a revival claim or a reap sweep holds it) — send again in a moment. ${DEDUP_RETRY_NOTE}`
+                                            : code === "resume.row_gone"
+                                                ? `${who}'s registry row no longer exists (terminal GC) — relaunch a new agent instead.`
+                                                : `${e instanceof Error ? e.message : String(e)} ${DEDUP_RETRY_NOTE}`;
                     return { content: `Message not sent: ${text}`, details: { error: code ?? "resume_failed", to }, isError: true };
                 }
             });

package/dist/agents/subagent.d.ts

@@ -293,6 +293,12 @@ export declare function completedAgentCard(child: {
      *  flagged (or no review was armed), so a consumer must not read presence as a verdict source for
      *  anything else. */
     handbackWarning?: string;
+    /** design/180 half A — the child's delegation runtime-provenance attestation, reduced from its
+     *  recorder aggregate at delivery. Present only when the parent chain armed the recorder; the
+     *  parent-side judgment (the content-origin wrap) reads it off this card — `clean` retires the
+     *  static face verdict for this call, `external` marks with the observed-event reason, `unknown`
+     *  (or absence) keeps the static floor. Deliberate whitelist admission (see the boundary note). */
+    attestation?: import("../core/memory-engine/delegation-provenance.js").DelegationAttestation;
 }): Record<string, unknown>;
 /**
  * ruled 2026-08-04 — the DELEGATION-REPORT vocabulary for a child that durably paused at an approval

package/dist/agents/subagent.js

@@ -1,6 +1,8 @@
 import { Type } from "typebox";
 import { isAbsolute } from "node:path";
 import { withDelegationProvenance } from "../core/tool-policy.js";
+import { isHighSurrogate, isLowSurrogate } from "../core/surrogate-safe-slice.js";
+import { newDelegationProvenanceAggregate, reduceDelegationAttestation } from "../core/memory-engine/delegation-provenance.js";
 import { resolveModel, resolveModelDisplayLabel } from "../core/roles.js";
 import { OUTPUT_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { TOOL_SEARCH_NAME } from "../core/runner/tool-disclosure.js";
@@ -64,8 +66,8 @@ function defuseGapMarkers(slice) {
     return slice.replace(/\[…/g, `${REVIEW_MARKER_SCAR}…`);
 }
 function surrogateSafeSlice(text, from, width, anchorEnd = false) {
-    const isLow = (i) => text.charCodeAt(i) >= 0xdc00 && text.charCodeAt(i) <= 0xdfff;
-    const isHigh = (i) => text.charCodeAt(i) >= 0xd800 && text.charCodeAt(i) <= 0xdbff;
+    const isLow = (i) => isLowSurrogate(text.charCodeAt(i));
+    const isHigh = (i) => isHighSurrogate(text.charCodeAt(i));
     let start = from;
     if (start > 0 && start < text.length && isLow(start) && isHigh(start - 1))
         start--;
@@ -311,6 +313,13 @@ const ccElapsedTag = (ms) => {
     return sec >= 60 ? ` \u00b7 ${Math.floor(sec / 60)}m${sec % 60}s` : ` \u00b7 ${sec}s`;
 };
 const ccCompletionText = (desc, settled, rawStatus, elapsedMs) => `Agent "${desc}" ${settled === "killed" ? "stopped" : settled === "completed" ? "finished" : rawStatus}${ccElapsedTag(elapsedMs)}`;
+function resumabilityClaim(f) {
+    if (f.status === "killed" && f.stoppedBy === "user")
+        return false;
+    if (f.liveRetainPresent)
+        return f.liveRetainHasBudget;
+    return f.durableRow && f.named;
+}
 const BG_AGENT_COLLATERAL_REAP_REASON = "its parent run ended";
 const RESERVED_AGENT_NAMES = new Set([OUTPUT_TOOL_NAME, TOOL_SEARCH_NAME, OFFLOAD_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME, DEFAULT_SUBAGENT_TOOL_NAME]);
 export const REPORT_FIELD_MAX = 300;
@@ -341,6 +350,7 @@ export function classifySubagentError(child) {
 export function completedAgentCard(child, extras) {
     return {
         type: "agent",
+        ...(extras.attestation !== undefined ? { attestation: extras.attestation } : {}),
         ...(extras.subagentType !== undefined ? { subagent_type: extras.subagentType } : {}),
         status: child.status,
         taskId: child.taskId,
@@ -522,7 +532,9 @@ export function createSubagentResume(deps) {
                     throw configError(revived.reason === "still_running"
                         ?
                             "resume unavailable: the agent's registry row is not available for a resume right now (it is running, or another revival claimed it) — wait for its completion notification and send again."
-                        : "resume unavailable: the agent's registry row no longer exists (terminal GC) — relaunch a new agent instead.", revived.reason === "still_running" ? "steering.still_running" : "resume.row_gone");
+                        : revived.reason === "recycling"
+                            ? "resume unavailable: the agent's registry row is being adjudicated right now (a revival claim or a reap sweep holds it) — this clears on its own; send again in a moment."
+                            : "resume unavailable: the agent's registry row no longer exists (terminal GC) — relaunch a new agent instead.", revived.reason === "still_running" ? "steering.still_running" : revived.reason === "recycling" ? "resume.row_recycling" : "resume.row_gone");
                 }
                 reviveCycle = revived.cycle;
                 if (deps.bgSink !== undefined) {
@@ -682,6 +694,16 @@ export function createSubagentResume(deps) {
                 const reviveTerminalSummary = failReasonRevive !== undefined
                     ? `Agent "${reviveName}" (resumed) failed: ${failReasonRevive}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + errorKindClause(errClassRevive)
                     : `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(Date.now() - reviveStartedAt)}`;
+                const reviveDurableProbe = deps.registry !== undefined && deps.taskId !== undefined ? deps.registry.durableAgentRowProbe(deps.taskId) : undefined;
+                const reviveDurableRow = reviveDurableProbe !== undefined ? await reviveDurableProbe().catch(() => false) : false;
+                const resumableRevive = resumabilityClaim({
+                    status,
+                    ...(stoppedByRevive !== undefined ? { stoppedBy: stoppedByRevive } : {}),
+                    liveRetainPresent: ledger.get(deps.parentToolCallId) === entry,
+                    liveRetainHasBudget: entry.resumeCount < SUBAGENT_RESUME_CAP,
+                    durableRow: reviveDurableRow,
+                    named: deps.rowName !== undefined,
+                });
                 const ownsTerminalFacesRevive = deps.registry !== undefined && deps.taskId !== undefined ? deps.registry.claimAgentTerminalNotify(deps.taskId) : true;
                 if (ownsTerminalFacesRevive)
                     reviveEmit?.({
@@ -696,7 +718,7 @@ export function createSubagentResume(deps) {
                         ...(stoppedByRevive !== undefined ? { stoppedBy: stoppedByRevive } : {}),
                         summary: reviveTerminalSummary,
                         ...resumeResidual(),
-                        resumable: status !== "killed",
+                        resumable: resumableRevive,
                         usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats) },
                         ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
                     });
@@ -714,7 +736,7 @@ export function createSubagentResume(deps) {
                     ...(resumeHandbackResult ? { result: notifyResultField(resumeHandbackResult) } : {}),
                     ...(status === "killed" && child.result ? { partial: true } : {}),
                     ...resumeResidual(),
-                    resumable: status !== "killed",
+                    resumable: resumableRevive,
                     usage: { tokens: child.stats.tokens, turns: child.stats.turns, ...delegatedCostField(child.stats) },
                     ...(completionIdRevive !== undefined ? { completionId: completionIdRevive } : {}),
                 };
@@ -1589,8 +1611,12 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 return { ...(recentSteps ? { recentSteps } : {}), ...(editedFiles ? { editedFiles } : {}) };
             };
             const treeScope = reviveClaim?.row.scope ?? ctx.principal ?? opts.background?.scope;
+            const provenanceRequest = ctx.delegationProvenanceForChildren?.();
+            const childProvenanceRef = provenanceRequest !== undefined ? { current: newDelegationProvenanceAggregate() } : undefined;
+            const childAttestation = (status) => childProvenanceRef !== undefined ? reduceDelegationAttestation(childProvenanceRef.current, { completed: status === "completed" }) : undefined;
             const childInternals = {
                 ...(inheritedManifestScope ? { inheritedManifestScope } : {}),
+                ...(childProvenanceRef !== undefined && provenanceRequest !== undefined ? { delegationProvenance: { ref: childProvenanceRef, contentSafety: provenanceRequest } } : {}),
                 ...(treeScope !== undefined ? { registryScope: treeScope } : {}),
                 ...(ctx.inheritedGateForChildren ? { inheritedGate: ctx.inheritedGateForChildren() } : {}),
                 ownOrgAdmissionRef: { current: reviveClaim !== undefined ? readDurableOrgAdmission(reviveClaim.row) : undefined },
@@ -2274,6 +2300,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     details: completedAgentCard(forkChild, {
                         subagentType: FORK_SUBAGENT_TYPE,
                         error: forkErr,
+                        ...(() => {
+                            const a = childAttestation(forkChild.status);
+                            return a !== undefined ? { attestation: a } : {};
+                        })(),
                         ...(forkHandbackWarning !== undefined ? { handbackWarning: forkHandbackWarning } : {}),
                         ...(worktreeKeptPath !== undefined ? { worktreePath: worktreeKeptPath } : {}),
                         ...(() => {
@@ -2795,7 +2825,15 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const completionIdBg = bg.registry.getCompletionId(taskId);
                     const observerNote = observerNoteFor(await startBoundedObserverDrain());
                     const residual = residualFields();
-                    const resumableBg = bgRetain !== undefined && settled !== "killed";
+                    const bgDurableRow = await bgRowConfirmed();
+                    const resumableBg = resumabilityClaim({
+                        status: settled,
+                        ...(stoppedBy !== undefined ? { stoppedBy } : {}),
+                        liveRetainPresent: settled !== "killed" && bgRetain !== undefined && bgRetainLedger?.get(ctx.toolCallId) === bgRetain,
+                        liveRetainHasBudget: bgRetain !== undefined && bgRetain.resumeCount < SUBAGENT_RESUME_CAP,
+                        durableRow: bgDurableRow,
+                        named: agentName !== undefined,
+                    });
                     const failReasonBg = settled === "failed" ? unparkedPauseReason ?? child.errorMessage : undefined;
                     const bgTerminalSummary = failReasonBg !== undefined
                         ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + errorKindClause(errClassBg)
@@ -3106,6 +3144,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 details: completedAgentCard(child, {
                     ...(def !== undefined ? { subagentType: def.name } : {}),
                     error: errClass,
+                    ...(() => {
+                        const a = childAttestation(child.status);
+                        return a !== undefined ? { attestation: a } : {};
+                    })(),
                     ...(handbackWarning !== undefined ? { handbackWarning } : {}),
                     ...(modelFallback !== undefined ? { modelFallback } : {}),
                     ...(worktreeKeptPath !== undefined ? { worktreePath: worktreeKeptPath } : {}),

package/dist/brain/errors.d.ts

@@ -45,6 +45,26 @@ export declare function extractErrorCode(errorMessage: string | undefined): Brai
  *  human text. Pairs with {@link extractErrorCode} so a caller can lift the code and clean the message
  *  without re-hardcoding the code list (the Runner does both when assembling `TaskResult`). */
 export declare function stripErrorCodePrefix(errorMessage: string): string;
+/**
+ * Whether a transport-level connect failure is DETERMINISTIC (see {@link DETERMINISTIC_CONNECT_CODES})
+ * or gives no such verdict. Classification is by `code` along the error graph — never by message text,
+ * which providers and runtimes reword freely.
+ *
+ * The graph, not just the chain: undici nests the actionable error under `cause`, and a dual-stack
+ * connect nests one `AggregateError` whose `errors[]` hold the per-family results. A code outside the
+ * set ANYWHERE in the graph returns `"indeterminate"`, and every AGGREGATE LEG must reach a
+ * deterministic verdict of its own — so a hostname whose IPv4 leg is refused while its IPv6 leg timed
+ * out, or whose second leg says nothing this classifier can read, keeps the full ladder. Position
+ * decides how silence is read: a WRAPPER with no code (the `TypeError("fetch failed")` shell, an
+ * `AbortSignal.timeout` DOMException whose `code` is a number) is structural and defers to what it
+ * wraps, while a LEG with nothing readable is an outcome nobody accounted for and blocks the verdict.
+ *
+ * Fail-safe by construction — every uncertain outcome (empty aggregate, an unreadable leg, a graph
+ * larger than the node budget, no deterministic code found at all) answers `"indeterminate"`, i.e. the
+ * pre-existing behavior.
+ */
+export type ConnectFailureClass = "deterministic" | "indeterminate";
+export declare function classifyConnectFailure(e: unknown): ConnectFailureClass;
 /** RB-386③ ([2090]) — render a transport-level error WITHOUT folding away its cause chain. undici's
  *  `fetch` rejects with `TypeError("fetch failed", { cause })` where the CAUSE carries the actually
  *  actionable fact (`connect ECONNREFUSED …` / `getaddrinfo ENOTFOUND …` / `SocketError: other side

package/dist/brain/errors.js

@@ -61,6 +61,46 @@ function hasStaleConnectionCode(e) {
     }
     return false;
 }
+const DETERMINISTIC_CONNECT_CODES = new Set(["ECONNREFUSED", "ENOTFOUND"]);
+const CONNECT_GRAPH_NODE_BUDGET = 16;
+function walkConnectFailure(node, budget) {
+    if (budget.left <= 0)
+        return "indeterminate";
+    budget.left--;
+    if (node === undefined || node === null)
+        return "silent";
+    let verdict = "silent";
+    const code = node.code;
+    if (typeof code === "string") {
+        if (!DETERMINISTIC_CONNECT_CODES.has(code))
+            return "indeterminate";
+        verdict = "deterministic";
+    }
+    if (!(node instanceof Error))
+        return verdict;
+    const members = node.errors;
+    if (Array.isArray(members)) {
+        if (members.length === 0)
+            return "indeterminate";
+        for (const member of members) {
+            if (walkConnectFailure(member, budget) !== "deterministic")
+                return "indeterminate";
+        }
+        verdict = "deterministic";
+    }
+    const cause = node.cause;
+    if (cause !== undefined && cause !== null) {
+        const below = walkConnectFailure(cause, budget);
+        if (below === "indeterminate")
+            return "indeterminate";
+        if (below === "deterministic")
+            verdict = "deterministic";
+    }
+    return verdict;
+}
+export function classifyConnectFailure(e) {
+    return walkConnectFailure(e, { left: CONNECT_GRAPH_NODE_BUDGET }) === "deterministic" ? "deterministic" : "indeterminate";
+}
 export function describeNetworkError(e) {
     const top = e instanceof Error ? e.message : String(e);
     const parts = [];

package/dist/brain/retry.d.ts

@@ -46,9 +46,23 @@ export interface ProviderWaitHint {
  *  ask as if nothing had been truncated at all, even though the pair's honored wait is identical either
  *  way. */
 export declare function providerWaitHint(res: Response | undefined): ProviderWaitHint | undefined;
+/**
+ * Ceiling on the exponential term for the SHORT lane that serves deterministic connect failures
+ * (`ECONNREFUSED` / a name with no address — see `errors.ts` `classifyConnectFailure`).
+ *
+ * That lane exists because waiting does not change the answer: the only thing that can is the peer
+ * itself coming up. So its ladder is sized to cover a service that is already mid-restart, not to
+ * out-wait an overloaded provider — which is what the 32s ceiling above is for. The two are separate
+ * constants rather than one parameter because they answer different questions, and collapsing them
+ * would make either lane's number look arbitrary.
+ */
+export declare const FAST_MAX_BACKOFF_MS = 1000;
 /**
  * Backoff (ms) for retry `attempt` (0-based) of a transient failure: an increasing capped exponential
  * plus ≤25% additive jitter, floored by the response's provider wait hints (see the module note).
- * `rand` is injectable for deterministic tests.
+ * `rand` is injectable for deterministic tests. `maxBackoffMs` overrides the exponential ceiling for a
+ * caller running a deliberately shorter lane; it bounds only the COMPUTED term — a provider wait hint
+ * still floors the result, because a lane choosing to be short is not a licence to ignore a server that
+ * said when to come back (and such a lane's failures carry no response to read a hint off anyway).
  */
-export declare function retryBackoffMs(baseDelayMs: number, attempt: number, res?: Response, rand?: () => number): number;
+export declare function retryBackoffMs(baseDelayMs: number, attempt: number, res?: Response, rand?: () => number, maxBackoffMs?: number): number;

package/dist/brain/retry.js

@@ -48,8 +48,9 @@ export function providerWaitHint(res) {
 function providerWaitHintMs(res) {
     return providerWaitHint(res)?.ms;
 }
-export function retryBackoffMs(baseDelayMs, attempt, res, rand = Math.random) {
-    const exp = Math.min(MAX_BACKOFF_MS, baseDelayMs * 2 ** attempt);
+export const FAST_MAX_BACKOFF_MS = 1_000;
+export function retryBackoffMs(baseDelayMs, attempt, res, rand = Math.random, maxBackoffMs = MAX_BACKOFF_MS) {
+    const exp = Math.min(maxBackoffMs, baseDelayMs * 2 ** attempt);
     const computed = Math.round(exp + rand() * JITTER_FRACTION * exp);
     const hint = providerWaitHintMs(res);
     return hint === undefined ? computed : Math.max(hint, computed);

package/dist/brain/status-sink.d.ts

@@ -1,4 +1,4 @@
-import type { BrainStatus } from "../core/types.js";
+import type { BrainRetryErrClass, BrainStatus } from "../core/types.js";
 /** Run `fn` with a per-task brain-status sink in scope. ALS propagates it through the async brain calls
  *  inside `fn` (the harness's prompt → brain.stream → connect/retry loop), so {@link emitBrainStatus}
  *  reaches THIS task's sink and nothing else. */
@@ -34,10 +34,17 @@ export type BrainTelemetry = {
     key: string;
     phase: "open" | "half-open" | "closed";
     failures: number;
-} | {
+}
+/** A retried provider call. `errClass` is the same closed bucket the user-facing status frame carries
+ *  (so an operator reading traces and a user reading a progress line agree on why); `nextDelayMs` is
+ *  the backoff actually about to be slept — 0 for the immediate re-sends that take no backoff. Both
+ *  optional so a caller that has no verdict to report is not forced to invent one. */
+ | {
     kind: "retry";
     attempt: number;
     phase: "connect" | "midstream";
+    errClass?: BrainRetryErrClass;
+    nextDelayMs?: number;
 } | {
     kind: "vision_placeholder";
     count: number;

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

@@ -25,6 +25,21 @@ export interface StreamEngineConfig extends BrainTimeoutConfig {
     maxRetries?: number;
     /** First-retry backoff ms; each further attempt doubles it (capped, +≤25% jitter). Default 500. */
     retryDelayMs?: number;
+    /**
+     * Retries allowed for a DETERMINISTIC connect failure — one whose error codes say the target itself
+     * is not there (`ECONNREFUSED`, or a name with no address; see `errors.ts` `classifyConnectFailure`).
+     * Absent ⇒ {@link DEFAULT_DETERMINISTIC_CONNECT_RETRIES}.
+     *
+     * These retries exist for one case only: a peer that is mid-restart and about to accept. Waiting
+     * longer cannot change any other outcome — re-sending at an address where nothing listens gets the
+     * same refusal in milliseconds — so spending the full transient budget on it buys nothing and costs
+     * an unattended caller minutes of silence.
+     *
+     * The value is capped by {@link maxRetries} (this lane can only ever be the SHORTER of the two).
+     * Setting it AT or ABOVE `maxRetries` turns the lane off entirely: budget and backoff both revert to
+     * the shared transient ladder, which is the opt-out for a deployment that wants the old behavior.
+     */
+    deterministicConnectRetries?: number;
 }
 /**
  * Resolve the transient-failure retry budget — explicit config > `SEMA_MAX_RETRIES` env > default 10
@@ -32,6 +47,13 @@ export interface StreamEngineConfig extends BrainTimeoutConfig {
  * value is ignored rather than silently meaning "zero retries"; an oversized one is clamped.
  */
 export declare function resolveMaxRetries(configured: number | undefined): number;
+/**
+ * Resolve the deterministic-connect retry budget. Same posture as {@link resolveMaxRetries}: a chosen
+ * NUMBER is honored, a non-finite or negative one falls back to the default rather than silently
+ * meaning something (a NaN here would compare false against every budget gate and disable the lane by
+ * accident, which is the sentinel-inversion shape CLS-A-8 pinned for the shared budget).
+ */
+export declare function resolveDeterministicConnectRetries(configured: number | undefined): number;
 /**
  * Is `rebuilt` still THE SAME REQUEST as `original`, differing only in the output cap and the values
  * that follow from it (ruled 2026-08-05)?

package/dist/brain/stream-engine.js

@@ -1,7 +1,7 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } from "./context-overflow.js";
-import { BrainError, classifyHttp, describeNetworkError } from "./errors.js";
-import { providerWaitHint, retryBackoffMs } from "./retry.js";
+import { BrainError, classifyConnectFailure, classifyHttp, describeNetworkError } from "./errors.js";
+import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { createConnectController, resolveStallTimeoutMs } from "./timeout.js";
 const DEFAULT_MAX_RETRIES = 10;
@@ -18,6 +18,12 @@ export function resolveMaxRetries(configured) {
     }
     return DEFAULT_MAX_RETRIES;
 }
+const DEFAULT_DETERMINISTIC_CONNECT_RETRIES = 2;
+export function resolveDeterministicConnectRetries(configured) {
+    if (configured !== undefined && Number.isFinite(configured) && configured >= 0)
+        return Math.floor(configured);
+    return DEFAULT_DETERMINISTIC_CONNECT_RETRIES;
+}
 const SHOULD_RETRY_HEADER = "x-should-retry";
 function sameHeaders(a, b) {
     const aKeys = Object.keys(a);
@@ -272,6 +278,8 @@ export function runStreamingBrain(args) {
         let maxOutputTokensOverride;
         const maxRetries = resolveMaxRetries(config.maxRetries);
         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");
@@ -342,13 +350,14 @@ export function runStreamingBrain(args) {
                                     maxOutputTokensOverride = plan.maxOutputTokens;
                                     req = rebuilt;
                                     req.onCommitted?.();
-                                    emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect" });
+                                    emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect", errClass: "output_cap", nextDelayMs: 0 });
                                     announcedRetry = true;
                                     emitBrainStatus({
                                         phase: "retrying",
                                         detail: `output limit lowered from ${previousCap} to ${plan.maxOutputTokens} tokens, retrying`,
                                         attempt: attempt + 1,
                                         maxRetries,
+                                        errClass: "output_cap",
                                     });
                                     continue;
                                 }
@@ -370,14 +379,33 @@ export function runStreamingBrain(args) {
                     const retryableByStatus = netErr !== undefined ||
                         (r !== undefined && (r.status >= 500 || r.status === 429 || r.status === 408 || r.status === 409));
                     const retryable = shouldRetryHeaderVerdict(r) ?? retryableByStatus;
-                    if (retryable && attempt < maxRetries) {
-                        const delayMs = retryBackoffMs(baseDelay, attempt, r);
+                    const deterministicConnect = netErr !== undefined && classifyConnectFailure(netErr) === "deterministic";
+                    const fastLane = deterministicConnect && deterministicLaneActive;
+                    const laneMaxRetries = fastLane ? deterministicConnectBudget : maxRetries;
+                    const errClass = netErr !== undefined
+                        ? deterministicConnect
+                            ? "connect_refused"
+                            : "transport"
+                        : r?.status === 429
+                            ? "rate_limit"
+                            : r !== undefined && (r.status >= 500 || r.status === 408 || r.status === 409)
+                                ? "server"
+                                : "http";
+                    if (retryable && attempt < laneMaxRetries) {
+                        const delayMs = fastLane
+                            ? retryBackoffMs(baseDelay, attempt, r, Math.random, FAST_MAX_BACKOFF_MS)
+                            : retryBackoffMs(baseDelay, attempt, r);
                         const waitHint = providerWaitHint(r);
                         const truncationNote = waitHint?.rawMs !== undefined
                             ? ` (the requested wait was longer than the cap; honoring ${Math.ceil(waitHint.ms / 1000)}s instead of ${Math.ceil(waitHint.rawMs / 1000)}s)`
                             : "";
                         const statusPhase = r?.status === 429 ? "rate_limited" : netErr !== undefined ? "reconnecting" : "retrying";
-                        emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect" });
+                        const reconnectDetail = errClass !== "connect_refused"
+                            ? "connection lost, reconnecting"
+                            : fastLane
+                                ? "no endpoint answering, retrying briefly"
+                                : "no endpoint answering, retrying";
+                        emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect", errClass, nextDelayMs: delayMs });
                         announcedRetry = true;
                         discardResponseBody(r);
                         cc.abort();
@@ -387,12 +415,13 @@ export function runStreamingBrain(args) {
                             detail: statusPhase === "rate_limited"
                                 ? `rate limited, backing off${truncationNote}`
                                 : statusPhase === "reconnecting"
-                                    ? "connection lost, reconnecting"
+                                    ? reconnectDetail
                                     : `transient error, retrying${truncationNote}`,
                             retryInSec: Math.ceil(remainingMs / 1000),
                             retryInMs: remainingMs,
                             attempt: attempt + 1,
-                            maxRetries,
+                            maxRetries: laneMaxRetries,
+                            errClass,
                         }));
                         continue;
                     }
@@ -561,7 +590,7 @@ export function runStreamingBrain(args) {
                 thinkingRetries++;
                 parser.sealForRetry();
                 const delayMs = 100 * thinkingRetries;
-                emitBrainTelemetry({ kind: "retry", attempt: thinkingRetries, phase: "midstream" });
+                emitBrainTelemetry({ kind: "retry", attempt: thinkingRetries, phase: "midstream", errClass: "transport", nextDelayMs: delayMs });
                 announcedRetry = true;
                 await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
                     phase: "reconnecting",
@@ -570,6 +599,7 @@ export function runStreamingBrain(args) {
                     retryInMs: remainingMs,
                     attempt: thinkingRetries,
                     maxRetries: THINKING_RETRY_BUDGET,
+                    errClass: "transport",
                 }));
                 continue;
             }
@@ -577,7 +607,7 @@ export function runStreamingBrain(args) {
                 throw failure.err;
             const delayMs = retryBackoffMs(baseDelay, attempt);
             attempt++;
-            emitBrainTelemetry({ kind: "retry", attempt, phase: "midstream" });
+            emitBrainTelemetry({ kind: "retry", attempt, phase: "midstream", errClass: "transport", nextDelayMs: delayMs });
             announcedRetry = true;
             await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
                 phase: "reconnecting",
@@ -586,6 +616,7 @@ export function runStreamingBrain(args) {
                 retryInMs: remainingMs,
                 attempt,
                 maxRetries,
+                errClass: "transport",
             }));
         }
     }