@sema-agent/core 7.19.0 → 7.20.0

package/dist/brain/anthropic.js

@@ -365,6 +365,7 @@ export function createAnthropicBrain(config = {}) {
                 const blocks = new Map();
                 const usageRaw = {};
                 let stopReason = null;
+                const terminalFrameSeen = () => stopReason != null;
                 let stopDetails;
                 let nextContentIndex = 0;
                 let malformedFrames = 0;
@@ -532,6 +533,7 @@ export function createAnthropicBrain(config = {}) {
                             hasSubstantiveText,
                             hasCompletedToolCall,
                             hasOnlyThinking: hasThinking && !hasSubstantiveText && !hasCompletedToolCall,
+                            terminalFrameSeen: terminalFrameSeen(),
                         };
                     },
                     sealForRetry() {
@@ -666,7 +668,7 @@ export function createAnthropicBrain(config = {}) {
                             emptyNoFinish ||
                             (toolError !== undefined && noUsableContent) ||
                             (truncatedEmpty && !dynamicCut && !staticReasoningCut);
-                        const tornWithContent = !errored && opts?.truncated !== true && stopReason == null && !noUsableContent && !degenerate;
+                        const tornWithContent = !errored && opts?.truncated !== true && !terminalFrameSeen() && !noUsableContent && !degenerate;
                         const errorMessageOut = tornWithContent ? (errorMessage ? `${errorMessage}\n${STREAM_TORN_WARNING}` : STREAM_TORN_WARNING) : errorMessage;
                         const errorKind = degenerate
                             ? "degenerate"

package/dist/brain/open-responses.js

@@ -303,6 +303,7 @@ export function createOpenResponsesBrain(config = {}) {
                 let usageRaw;
                 let responseId;
                 let terminalStatus;
+                const terminalFrameSeen = () => terminalStatus !== undefined;
                 let incompleteReason;
                 let accumRefusal = "";
                 const capabilityNotes = [];
@@ -573,6 +574,7 @@ export function createOpenResponsesBrain(config = {}) {
                             hasSubstantiveText,
                             hasCompletedToolCall,
                             hasOnlyThinking: hasReasoning && !hasSubstantiveText && !hasCompletedToolCall,
+                            terminalFrameSeen: terminalFrameSeen(),
                         };
                     },
                     sealForRetry() {
@@ -690,7 +692,7 @@ export function createOpenResponsesBrain(config = {}) {
                         const safetyCut = incompleteReason === INCOMPLETE_CONTENT_FILTER;
                         const refused = accumRefusal.trim().length > 0;
                         const incompleteUnmapped = terminalStatus === "incomplete" && incompleteReason !== INCOMPLETE_MAX_OUTPUT_TOKENS && incompleteReason !== INCOMPLETE_CONTENT_FILTER;
-                        const emptyNoFinish = noUsableContent && (terminalStatus === undefined || incompleteUnmapped) && !degenerate;
+                        const emptyNoFinish = noUsableContent && (!terminalFrameSeen() || incompleteUnmapped) && !degenerate;
                         const maxTokensNote = sentMaxTokens !== undefined
                             ? `effective max_output_tokens=${sentMaxTokens} (from ${sentMaxTokensLane === "options"
                                 ? "options.maxTokens"
@@ -718,7 +720,7 @@ export function createOpenResponsesBrain(config = {}) {
                             emptyNoFinish ||
                             (toolError !== undefined && noUsableContent) ||
                             (truncatedEmpty && !dynamicCut && !staticReasoningCut);
-                        const tornWithContent = !errored && opts?.truncated !== true && (terminalStatus === undefined || incompleteUnmapped) && !noUsableContent && !degenerate;
+                        const tornWithContent = !errored && opts?.truncated !== true && (!terminalFrameSeen() || incompleteUnmapped) && !noUsableContent && !degenerate;
                         const partialWarning = terminalStatus === undefined ? STREAM_TORN_WARNING : RESPONSE_INCOMPLETE_WARNING;
                         const errorMessageOut = tornWithContent ? (errorMessage ? `${errorMessage}\n${partialWarning}` : partialWarning) : errorMessage;
                         const errorKind = degenerate

package/dist/brain/openai.js

@@ -373,6 +373,7 @@ export function createOpenAIBrain(config = {}) {
                 let textIndex = 0;
                 const toolAccum = new Map();
                 let finishReason = null;
+                const terminalFrameSeen = () => finishReason != null;
                 let usageRaw;
                 let malformedFrames = 0;
                 let malformedSample;
@@ -438,6 +439,7 @@ export function createOpenAIBrain(config = {}) {
                             hasSubstantiveText,
                             hasCompletedToolCall,
                             hasOnlyThinking: accumReasoning.length > 0 && !hasSubstantiveText && !hasCompletedToolCall,
+                            terminalFrameSeen: terminalFrameSeen(),
                         };
                     },
                     sealForRetry() {
@@ -619,7 +621,7 @@ export function createOpenAIBrain(config = {}) {
                             emptyNoFinish ||
                             (toolError !== undefined && noUsableContent) ||
                             (truncatedEmpty && !dynamicCut);
-                        const tornWithContent = !errored && opts?.truncated !== true && finishReason == null && !noUsableContent && !degenerate;
+                        const tornWithContent = !errored && opts?.truncated !== true && !terminalFrameSeen() && !noUsableContent && !degenerate;
                         const errorMessageOut = tornWithContent ? (errorMessage ? `${errorMessage}\n${STREAM_TORN_WARNING}` : STREAM_TORN_WARNING) : errorMessage;
                         const errorKind = degenerate
                             ? "degenerate"

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

@@ -194,11 +194,15 @@ export interface StreamParser {
      * - `hasOnlyThinking` — thinking streamed but nothing substantive (no non-blank text, no completed
      *   tool call) → tier B (seal + whole-turn retry). A dangling tool-call accumulation alongside the
      *   thinking does not veto this (nothing was admitted; the retry's snapshot replacement drops it).
+     * - `terminalFrameSeen` — the provider TERMINATED this stream (openai `finish_reason`, anthropic
+     *   `message_delta.stop_reason`, responses `response.completed`/`response.incomplete`). A FACT, not a tier:
+     *   the parser reports it off the same state its own finalize reads, and the tiering owns what it means.
      */
     snapshot(): {
         hasSubstantiveText: boolean;
         hasCompletedToolCall: boolean;
         hasOnlyThinking: boolean;
+        terminalFrameSeen: boolean;
     };
     /**
      * design/124 §0.5-2 tier B: seal the UI stream before a whole-turn retry — emit `thinking_end` for

package/dist/brain/stream-engine.js

@@ -647,6 +647,10 @@ export function runStreamingBrain(args) {
                 return;
             }
             const snap = parser.snapshot();
+            if (snap.terminalFrameSeen) {
+                parser.finalize();
+                return;
+            }
             if (snap.hasSubstantiveText || snap.hasCompletedToolCall) {
                 midstreamWarning =
                     failure.kind === "stalled"

package/dist/core/auto-mode.d.ts

@@ -13,10 +13,12 @@ export declare function isAutoModeUnavailableCause(v: unknown): v is AutoModeUna
 /**
  * HOW a reply failed to carry a verdict — the closed set behind `parse_error.form`. `missing` = the reader found
  * NO answer (empty text, prose, an answer only inside a thinking block); `conflict` = it found TWO distinct
- * `<block>` answers (raw or thinking-stripped). The split exists for the classify leg's re-ask: a missing
- * answer is asked for again (CC 2.1.259 `Vrr` re-asks an unparseable reply), a conflict is not — it carries a
- * `yes`, and a second attempt that answered `no` would erase it. Not on any wire face; the trace frame and the
- * gate record keep the one word `parse_error`.
+ * `<block>` answers (raw or thinking-stripped). The split decides who gets a SECOND ATTEMPT at the same
+ * question, on both seats that offer one: a missing answer is asked for again (CC 2.1.259 `Vrr` re-asks an
+ * unparseable reply) and handed on to the next candidate ({@link rungDidNotRule}); a conflict gets neither —
+ * it carries a `yes`, and any second attempt that answered `no` would erase it. One rule, two seats: whatever
+ * a re-ask may not overwrite, a later rung may not overwrite either. Not on any wire face; the trace frame and
+ * the gate record keep the one word `parse_error`.
  */
 export declare const AUTO_MODE_PARSE_FAILURES: readonly ["missing", "conflict"];
 export type AutoModeParseFailure = (typeof AUTO_MODE_PARSE_FAILURES)[number];
@@ -26,8 +28,9 @@ export declare function isAutoModeParseFailure(v: unknown): v is AutoModeParseFa
  * WHY a classification moved DOWN the candidate ladder — the closed set behind
  * {@link AutoModeClassifierRound}'s `fallback.cause`, i.e. the ways a candidate produces NO RULING
  * ({@link rungDidNotRule}). Two words are the unavailable causes verbatim (the leg threw / rejected; the
- * round-trip cap elapsed); `parse_error` is the candidate that ANSWERED without a verdict. A ruling is not a
- * member: the ladder stops at a verdict either way.
+ * round-trip cap elapsed); `parse_error` is the candidate that ANSWERED with no answer in it at all (the
+ * `missing` form). A ruling is not a member, and neither is a CONTRADICTORY reply (`conflict`): the ladder
+ * stops at a rung that settled the classification, whichever way it settled it.
  */
 export declare const AUTO_MODE_FALLBACK_CAUSES: readonly ["error", "timeout", "parse_error"];
 export type AutoModeFallbackCause = (typeof AUTO_MODE_FALLBACK_CAUSES)[number];
@@ -65,8 +68,9 @@ export type AutoModeVerdict = ({
 } & AutoModeRoundAttributed)
 /** The model responded but not in the `<block>…` contract shape. Handled as a BLOCK with the CC
  *  parse-failure sentence ({@link classifierParseFailureDenyMessage}), counted by the denial limit. `form`
- *  says WHICH way the reply failed ({@link AutoModeParseFailure}): the classify leg re-asks a `missing`
- *  reply once and never a `conflict`. */
+ *  says WHICH way the reply failed ({@link AutoModeParseFailure}) and decides who may try the question a
+ *  second time: the classify leg re-asks a `missing` reply once and the ladder hands it to the next rung;
+ *  a `conflict` gets neither ({@link rungDidNotRule}). */
  | ({
     kind: "parse_error";
     raw: string;
@@ -100,20 +104,18 @@ export interface AutoModeClassifierRound {
  * the QUESTION (the transcript window every rung shares), not in a rung's answer.
  *
  * WHY IT EXISTS. The ladder advances on "the rung produced no ruling", and a hook that rejects looks exactly
- * like that. But a classification whose prompt could not be built fails IDENTICALLY on every rung (the build is one
- * shared promise, by contract — "the same prompt, re-asked" is literal), so the walk recorded a fallback
- * `{from: seat, to: main, cause: "error"}` and a deny sentence naming two models, for a classification in which NO
- * MODEL WAS EVER DISPATCHED: a transcript-store outage read, on every face a person can see, as a broken
- * classifier seat. The verdict is unchanged (fail-closed `unavailable`); what changes is that the record
- * stops attributing it to models that were never asked.
+ * like that. But a classification whose prompt could not be built fails IDENTICALLY on every rung (the build is
+ * one shared promise, by contract — "the same prompt, re-asked" is literal), so without this word the walk
+ * records a fallback and a deny sentence naming two models for a classification in which NO MODEL WAS EVER
+ * DISPATCHED. The verdict is unchanged (fail-closed `unavailable`); what this changes is that the record stops
+ * attributing it to models that were never asked.
  *
  * Carried as a `code` on the thrown error rather than a class so any classify hook — including one this
  * package never constructed — can raise it without importing a constructor.
  *
  * WHAT IT DOES NOT COVER, stated: a build that OUTRUNS a rung's cap is still recorded as that rung's
  * `timeout`. The cap bounds the whole classify call, assembly included, so at that point nothing distinguishes
- * a slow transcript store from a slow model. Moving the per-classification build outside the rung cap is a
- * seam change, filed for a later version.
+ * a slow transcript store from a slow model.
  */
 export declare const AUTO_MODE_ROUND_NOT_ASKED_CODE = "auto_mode.round_not_asked";
 /** Mint the marker above around whatever failed, keeping the original as `cause` for the host's own logs.
@@ -124,8 +126,25 @@ export declare const AUTO_MODE_ROUND_NOT_ASKED_CODE = "auto_mode.round_not_asked
 export declare function autoModeRoundNotAsked(reason: unknown): Error & {
     code: string;
 };
-/** Why a rung did not settle the classification, or `undefined` when it RULED and the ladder stops — the ONE
- *  predicate behind the advance (there is no `if (fallback)` arm anywhere). */
+/**
+ * Why a rung did not settle the classification, or `undefined` when it SETTLED it and the ladder stops — the
+ * ONE predicate behind the advance (there is no `if (fallback)` arm anywhere).
+ *
+ * A rung settles the classification two ways: it RULES (`allow` / `block`), or it answers with a
+ * CONTRADICTION (`parse_error` of form `conflict` — two distinct `<block>` answers in one reply). The second
+ * is not a ruling and stays the fail-closed deny it is; what it is NOT is an unanswered question. It holds a
+ * `yes`, so asking the SAME question again — of the same model as a re-ask, or of the next rung as a fallback
+ * — can only overwrite that `yes` with a `no` and allow a call the classifier already objected to. One rule
+ * for both second attempts: {@link AUTO_MODE_PARSE_FAILURES} names the form, the leg reads it for the re-ask
+ * and this predicate reads it for the walk. Only a reply with NO answer in it (`missing`) moves the ladder.
+ *
+ * @contract auto_mode.ladder.advances_on_no_evidence — the candidate ladder advances on exactly one
+ * condition, and it is the ABSENCE of evidence: the rung's leg threw or rejected, its round-trip cap elapsed,
+ * or its reply carried no answer at all. A rung that RULED and a rung whose reply CONTRADICTED itself both
+ * settle the classification where they stand — the contradiction as the fail-closed `parse_error` deny it
+ * already is, attributed to that rung and disclosing no fallback — so no later candidate is ever asked a
+ * question an earlier one has already answered `yes` to.
+ */
 export declare function rungDidNotRule(v: AutoModeVerdict): AutoModeFallbackCause | undefined;
 /**
  * The model-facing deny text for an `unavailable` verdict — CC 2.1.250 `x1t`, with the parenthetical `EIt`

package/dist/core/auto-mode.js

@@ -56,7 +56,7 @@ export function rungDidNotRule(v) {
     if (v.kind === "unavailable")
         return v.cause;
     if (v.kind === "parse_error")
-        return "parse_error";
+        return v.form === "conflict" ? undefined : "parse_error";
     return undefined;
 }
 export function classifierUnavailableDenyMessage(toolName, cause, attribution) {

package/dist/core/child-clamp-seats.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The TIGHTEN-ONLY CLAMP SEATS an engine-built child spec carries from the run that builds it — and the
+ * ONE carrier every such constructor passes them through.
+ *
+ * Why a carrier and not a convention. The engine builds child specs in several places (the delegation
+ * lane, the observer sidecar, the wake/revival fold, the teacher's internal legs, the verify gate's two
+ * legs, the workflow lane), and each re-deriving per seat WHICH value is the tightening one lands a new
+ * seat one constructor at a time — the ones it does not reach staying invisible, since a `grep readFace`
+ * census cannot see a station that carries the face through a persisted seed or a synthesized fold.
+ *
+ * Two mechanical halves replace the census:
+ *  · the COMPILER — {@link ChildClampSource} requires every seat as a PRESENT key (an `undefined` value
+ *    is fine; a missing key is not), so adding a member to {@link CHILD_CLAMP_SEATS} reds `tsc` at every
+ *    construction site until each one says what it carries there;
+ *  · the SCAN — `scripts/verify-child-clamp-seats.mjs` reads {@link ENGINE_CHILD_SPEC_CONSTRUCTORS} and
+ *    requires each registered constructor to go through this carrier, requires the carrier's own source
+ *    to cover every seat, and requires every tighten-only seat `tightenTaskSpec` governs to be either
+ *    carried here or listed in {@link CHILD_CLAMP_SEATS_NOT_CARRIED} with a reason.
+ *
+ * What "tighten-only" means for this seat list: the value that travels is the RESTRICTING one and only
+ * that one, so a parent that clamped nothing changes nothing about its children, and nothing a child can
+ * author lifts a clamp its parent ran under. That is why the carrier omits a key rather than writing a
+ * loosening value — a constructor may state its own stricter default and spread this after it.
+ */
+import type { ReadDenyEntry } from "../tools/fs/read-deny.js";
+import type { TaskSpec } from "./types.js";
+/**
+ * The clamp seats, as string literals (the closed set the scan and the wire-manifest reader both parse —
+ * a spread or an identifier here reads as an empty set).
+ */
+export declare const CHILD_CLAMP_SEATS: readonly ["handsReadOnly", "interactiveTools", "readFace", "writeFace", "readDenyPatterns"];
+/** One clamp seat's name. */
+export type ChildClampSeat = (typeof CHILD_CLAMP_SEATS)[number];
+/**
+ * The seats `tightenTaskSpec` governs that this carrier deliberately does NOT carry, each with the reason
+ * — the "forgot" / "decided" distinction, kept where a new reader will trip over it. The scan requires
+ * every seat named in `tightenTaskSpec` to be in this table or in {@link CHILD_CLAMP_SEATS}.
+ */
+export declare const CHILD_CLAMP_SEATS_NOT_CARRIED: Readonly<Record<string, string>>;
+/**
+ * The engine-built child-spec constructors, as `<repo-relative file>#<name>` — the closed registry the
+ * scan enumerates. A constructor that builds a spec for a child RUN belongs here; the scan requires each
+ * row to resolve to exactly one declaration IN ITS OWN FILE that calls {@link childClampSeats}.
+ *
+ * Why the file is half the key, and why a shape the scan cannot read is a RED rather than an absence: a
+ * registry keyed on a bare NAME asks a syntactic scan to enumerate every shape that binds a callable, and
+ * that list has no end — every shape it misses leaves the real constructor invisible while a namesake
+ * answers for it.
+ */
+export declare const ENGINE_CHILD_SPEC_CONSTRUCTORS: readonly ["src/agents/subagent.ts#buildChildSpec", "src/agents/subagent.ts#observerSpec", "src/agents/subagent.ts#resumeSpec", "src/agents/teacher.ts#inheritedDeploymentConfig", "src/agents/verify.ts#verifierSpec", "src/agents/verify.ts#fixLegSpec", "src/orchestration/workflow-primitives.ts#workflowChildClamps"];
+/**
+ * The clamp source a construction site hands the carrier: EVERY seat as a present key. A site whose lane
+ * has no value for a seat writes `undefined` explicitly — which is the point, since that is a sentence
+ * a reader (and a diff) can see, unlike an absent key.
+ */
+export interface ChildClampSource {
+    /** The write-hands clamp: only `true` travels. */
+    handsReadOnly: boolean | undefined;
+    /** The hard-headless clamp: only `false` travels. */
+    interactiveTools: boolean | undefined;
+    /** The read containment face: only `"roots"` travels. */
+    readFace: TaskSpec["readFace"] | undefined;
+    /** The write containment face: only `"roots"` travels. */
+    writeFace: TaskSpec["writeFace"] | undefined;
+    /** The deny-set additions: an add-only axis, so a non-empty list travels as a spawn-time copy. */
+    readDenyPatterns: readonly ReadDenyEntry[] | undefined;
+}
+/**
+ * Project a parent's clamps onto a child spec — the ONE place that decides, per seat, which value is the
+ * tightening one and how it is copied. Spread the result onto the child spec; a seat with nothing to
+ * clamp contributes NO KEY, so a constructor may state its own stricter value above the spread and keep
+ * it (a `false` from the parent can never lift it).
+ *
+ * @contract child_spec.clamps_travel_whole — every child spec the ENGINE builds carries the whole of its
+ * parent's tighten-only clamp seats (`CHILD_CLAMP_SEATS`) through this one carrier: only the restricting
+ * value of each seat travels, arrays are copied at spawn, and a seat the parent did not clamp adds no key
+ * — so a clamp can never end one level deep, and a new seat cannot reach some constructors and not others.
+ */
+export declare function childClampSeats(source: ChildClampSource): Partial<TaskSpec>;

package/dist/core/child-clamp-seats.js

@@ -0,0 +1,29 @@
+export const CHILD_CLAMP_SEATS = ["handsReadOnly", "interactiveTools", "readFace", "writeFace", "readDenyPatterns"];
+export const CHILD_CLAMP_SEATS_NOT_CARRIED = Object.freeze({
+    toolPolicy: "not a clamp a child spec copies: a parent's denies reach its children through the ancestor-constraint chain the child's own prepare folds, not by putting the parent's policy object on the child seat",
+    shellGate: "travels on the inherited-gate lane (`InheritedGate.shellGate`, a trusted internals seat), not on the child spec — a spec-level copy would be a second source for the same clamp",
+    onAsk: "per-lane by construction: the delegation lane wraps the parent's approver with spawn provenance before it becomes the child's seat, and a lane with no approver must hand down none",
+    hooks: "a deployment seat, not an inherited clamp — `tightenTaskSpec` refuses to merge two hook sets rather than composing them, so there is no tightening value to carry",
+    excludeTools: "roster control rather than containment: the lanes that copy a parent's roster do so beside these seats, and the workflow lane authors its child roster from the governance baseline instead of the host's",
+    deferTools: "roster control, same reading as `excludeTools` above",
+});
+export const ENGINE_CHILD_SPEC_CONSTRUCTORS = [
+    "src/agents/subagent.ts#buildChildSpec",
+    "src/agents/subagent.ts#observerSpec",
+    "src/agents/subagent.ts#resumeSpec",
+    "src/agents/teacher.ts#inheritedDeploymentConfig",
+    "src/agents/verify.ts#verifierSpec",
+    "src/agents/verify.ts#fixLegSpec",
+    "src/orchestration/workflow-primitives.ts#workflowChildClamps",
+];
+export function childClampSeats(source) {
+    return {
+        ...(source.handsReadOnly === true ? { handsReadOnly: true } : {}),
+        ...(source.interactiveTools === false ? { interactiveTools: false } : {}),
+        ...(source.readFace === "roots" ? { readFace: "roots" } : {}),
+        ...(source.writeFace === "roots" ? { writeFace: "roots" } : {}),
+        ...(source.readDenyPatterns !== undefined && source.readDenyPatterns.length > 0
+            ? { readDenyPatterns: [...source.readDenyPatterns] }
+            : {}),
+    };
+}

package/dist/core/engine-notice.d.ts

@@ -10,31 +10,41 @@ export interface EngineNotice {
      *    `autoCompactTokens` ABOVE its physical window; the trigger-side geometry was clamped to the
      *    physical window (an autocompact window only ever lowers the trigger) and the bad value is
      *    announced once per prepared task; `detail: { modelId, declaredAutoCompactTokens,
-     *    physicalWindow, sessionId, runId }` — `runId` (#499) is what makes the "once per prepared
-     *    task" claim checkable: the session id beside it is shared by every run of the session, so two
-     *    runs clamping the same model used to mint byte-identical lines.
+     *    physicalWindow, sessionId, runId }` — `runId` is what makes the "once per prepared task" claim
+     *    checkable, the session id beside it being shared by every run of the session.
      *  - `"config.env_timeout_discarded"` — a Bash timeout knob (option or env) held a value that is not
      *    the value in force; `detail: { knob, raw, usedMs }`.
      *  - `"config.materialize_env_discarded"` — `SEMA_TOOL_MATERIALIZE_STRATEGY` held a value outside the
      *    closed set in a seat where it is not in force; `detail: { raw, specStrategy? }`.
+     *  - `"config.task_root_not_canonical"` (#759) — the task root this run was handed is not its own
+     *    canonical path (a symlinked directory; `/var` → `/private/var` on macOS). Containment is judged
+     *    on the CANONICAL spelling, so the deployment and the engine reason about two different
+     *    directories: a target the host considers inside the root can be judged outside it. The run is
+     *    unchanged — announce, never narrow, never repair — and the fix is to hand the canonical path in.
+     *    Audience `operator` (a deployment wiring fact). `detail: { given, canonical, sessionId, runId }`
+     *    — both spellings, so a consumer can diff them without guessing which one it holds. Once per
+     *    prepared leg, and never for a root that already is its own canonical form (its absence is the
+     *    claim that the two agree).
      *  - `"config.tool_card_undeclared"` (design/388 L4) — a tool minted a `details.type` card its definition
      *    (or its caller declaration's `renderHints.resultCards`) never declared; the card was dropped from
      *    `tool_end.structured`; once per leg per type; `detail: { type, sessionId, runId }`.
      *  - `"config.tool_face_undeclared"` / `"config.tool_face_invalid"` (design/388 §2.7) — an MCP server's
      *    `toolFaces` overlay names a tool the listing does not carry / does not fit the tool's materialized
      *    schema (the tool mounts bare); once per leg per tool; `detail: { server, tool, problem?, sessionId, runId }`.
+     *  - `"agents.listing_truncated"` — the agent-type roster frame did not fit the same listing budget:
+     *    at least one type is listed name-only (`nameOnly`) or not at all (`dropped`). Audience `operator`.
+     *    `detail: { budgetBytes, total, kept, nameOnly: [name], dropped: [name], sessionId }`; the same
+     *    firing rule as its skills sibling below (once per delivered frame, on the carrying message's receipt).
      *  - `"skills.listing_truncated"` — the `<skills>` disclosure block did not fit its byte budget, so
      *    at least one skill is listed without its description (`nameOnly`) or, in the pathological case,
      *    not listed at all (`dropped`); the `Skill` tool still serves every one of them. Audience
      *    `operator` — raising `TaskSpec.skillListingBudgetFraction`, lowering `skillListingMaxDescChars`
-     *    or declaring fewer skills are all deployment acts. `detail: { budgetBytes,
-     *    requestedBudgetBytes, descMaxChars, total, kept, nameOnly: [name], dropped: [name], sessionId }`
-     *    — `requestedBudgetBytes` is what the declared fraction asked for BEFORE the delivery lane's
-     *    structural clamp, and differs from `budgetBytes` only when that clamp bound, so a listing
-     *    shortened by the lane is distinguishable from one shortened by the deployment's own fraction.
-     *    Announced by the lane that DELIVERS a listing frame — the leg's first-frame producer, or the
-     *    turn boundary that a drift (or a resume leg's initial listing) rides — once per delivered frame
-     *    the budget actually degraded, and never for one that fit. Every count is read off that frame, so
+     *    or declaring fewer skills are all deployment acts. `detail: { budgetBytes, descMaxChars, total,
+     *    kept, nameOnly: [name], dropped: [name], sessionId }` — `budgetBytes` IS the budget in force;
+     *    no ceiling stands above the declared fraction, so no second number rides beside it.
+     *    Announced on the RECEIPT of the message that carried the frame — the leg's first user message, or
+     *    the boundary steer that a drift (or a resume leg's initial listing) rides — once per delivered
+     *    frame the budget actually degraded, and never for one that fit. Every count is read off that frame, so
      *    `total` is the whole roster on an initial listing and the newly announced set on a drift frame.
      *    A run whose deployment turned the listing off (`attachments.skillsListing: false`) emits nothing,
      *    since nothing is rendered. There is NO dedup key: each notice is one delivered frame`s cost, and
@@ -43,21 +53,19 @@ export interface EngineNotice {
      *    failed; THIS attempt stored nothing (the failure arm reports, it never re-inserts under the
      *    ref) — an earlier attempt of the same idempotent re-put may already have stored the row, so
      *    the notice claims a failed write, not an empty ref;
-     *    `detail: { ref, sessionId, cause, occurrenceId }`.
-     *    Per-occurrence, not per-process-deduplicated: each failed write is a distinct fact — and
-     *    `occurrenceId` (#495, uuidv7 minted at the failure) is what lets a consumer act on that:
-     *    `ref` names the ROW, and the same ref is attempted again on every later re-clear, so two
-     *    genuine losses of one ref were byte-identical notices. Dedup key: (code, occurrenceId).
+     *    `detail: { ref, sessionId, cause, occurrenceId }`. Per-occurrence, not
+     *    per-process-deduplicated: each failed write is a distinct fact, and `ref` names the ROW rather
+     *    than the attempt, so the uuidv7 `occurrenceId` minted at the failure is what tells two genuine
+     *    losses of one ref apart. Dedup key: (code, occurrenceId).
      *  - `"workflow.governance_key_stripped"` (#235) — the fields of an LLM-authored workflow `agent(spec)`
      *    that did NOT cross the governed default-deny whitelist: an unrecognized/control-plane field, or a
      *    `readFace` value that is not the containment-tightening one. The spawn PROCEEDS on the deployment
      *    baseline (the strip is not a refusal in this window), which is why the drop is announced;
      *    `detail: { total, stripped: [{ key, reason }], omitted?, occurrenceId }`, the rendered key list
      *    bounded in count and length because the names come from the untrusted script. One aggregated
-     *    notice per governed child build, not de-duplicated across builds: each spec is a distinct fact —
-     *    `occurrenceId` (#495, uuidv7 minted at the announcement) carries that claim to the consumer,
-     *    which otherwise saw two builds of the same spec as one repeated notice. Dedup key:
-     *    (code, occurrenceId).
+     *    notice per governed child build, not de-duplicated across builds: each spec is a distinct fact,
+     *    and the uuidv7 `occurrenceId` minted at the announcement is what carries that claim to a consumer
+     *    that would otherwise read two builds of one spec as one repeated notice. Dedup key: (code, occurrenceId).
      *  - `"workflow.agent_option_ignored"` (#505 ①) — the OPTIONS-object twin of the row above: keys of
      *    `agent(spec, opts)`'s SECOND argument that were not applied (unrecognized, or a known option
      *    whose value its type check rejected — `label: 42`). The spawn PROCEEDS without them, which is
@@ -67,6 +75,21 @@ export interface EngineNotice {
      *    key: (code, occurrenceId). NOT the whole family: a SPEC field written on the options object
      *    (`model`, `modelName`, `thinking`, …) is REFUSED at the membrane instead — a silently ignored
      *    `model` runs a different agent than the author asked for.
+     *  - `"config.forward_sink_failed"` — the deployment's opt-in subagent display sink
+     *    (`RunInternals.onForwardEvent`) failed and the frame it was handed was dropped: it threw, or —
+     *    since an `async` function satisfies that `=> void` seat — it returned a promise that rejected.
+     *    The run is untouched (forwarding is a render channel, and delivery is never awaited, so a sink
+     *    that never settles is not a failure and announces nothing). `detail: { site, cause }` — `site` is
+     *    the engine-owned site name the failures are counted under, `cause` the thrown value's message.
+     *    Audience `operator`: the sink is deployment wiring and nobody else can repair it. Dedup unit:
+     *    once per RUN (the counters ride `RunInternals.forwardScope`, which every copy of a run's
+     *    internals carries), later failures of the same run counted only — a sink that fails on every
+     *    frame therefore costs ONE line, not one per frame.
+     *  - `"memory.restore_withheld"` — a memory containment DID NOT write a committed baseline back: another
+     *    writer held the path when the restore reached it, and those newer bytes were left standing.
+     *    Containment is unaffected and the committed copy is still in the store, so reconciling the two is
+     *    the host's act (audience `operator`). `detail: { paths: [{ path, entryId?, rev? }], sessionId? }`,
+     *    `rev` = the declined generation. Dedup unit: once per containment PASS, never per path.
      *  - `"mcp.revocation_probe_failed"` (design/338) — the deployment's `mcpRevocations.isRevoked`
      *    probe threw; MCP dispatch FAILS OPEN (revocation is a tightening face) and this announces
      *    once per materialization (a resume re-materializes and may announce again).
@@ -90,10 +113,9 @@ export interface EngineNotice {
      *    { models, tiers, occurrenceId }` — key COUNTS only, never the catalog itself. In-flight tasks
      *    finish on the models they resolved at prepare (natural snapshot); every later prepare resolves
      *    against the new generation. A failed swap (illegal tier binding, a refused candidate) throws
-     *    atomically and mints nothing.
-     *    `occurrenceId` (#495, uuidv7 minted at the announcement): the verb carries no run and no
-     *    session, and the payload is a pair of counts, so two swaps of the same shape were byte-
-     *    identical lines. Dedup key: (code, occurrenceId).
+     *    atomically and mints nothing. The verb carries no run and no session and the payload is a pair
+     *    of counts, so the uuidv7 `occurrenceId` minted at the announcement is what tells two swaps of the
+     *    same shape apart. Dedup key: (code, occurrenceId).
      *  - `"config.read_face_swapped"` — `Runner.swapDeps` replaced the deployment's read-face
      *    declaration (`RunnerDeps.readFace`, the `readFace` seat of the swappable set) without a
      *    restart. `detail: { from, to, occurrenceId }` — the seat's previous and new value, each
@@ -102,8 +124,7 @@ export interface EngineNotice {
      *    read-only mount) still runs per prepare. In-flight legs keep the face they prepared under;
      *    every later prepare resolves against the new declaration. A candidate outside the value gate
      *    (`assertContainmentFaceValue`) throws atomically and mints nothing. Own `occurrenceId` for the same
-     *    reason as the catalog line (no run, no session, a two-word payload). Dedup key:
-     *    (code, occurrenceId).
+     *    reason as the catalog line (no run, no session, a two-word payload). Dedup key: (code, occurrenceId).
      *  - `"config.write_face_swapped"` — the same line for the WRITE seat (`RunnerDeps.writeFace`),
      *    same payload, same laws. A SEPARATE code rather than a face field on the line above: the audience
      *    table and every consumer table are keyed by code.
@@ -114,10 +135,9 @@ export interface EngineNotice {
      *    `detail: { seat, from, to, cause, fixHint, sessionId?, runId? }` — `cause` is the refusal code
      *    (`route.credential_mismatch` / `route.credential_missing`); `sessionId` (#433, additive)
      *    rides when the adjudicating seat knows its session, and `runId` (#499, additive) names the
-     *    INVOCATION whose seats were being resolved — both correlation keys only, the audience
-     *    stays `"operator"` (see the registry's entitlement-not-routability note). Two runs of one
-     *    session falling back on the same seat used to mint byte-identical lines; `runId` is what
-     *    tells one task falling back twice apart from two tasks falling back once each.
+     *    INVOCATION whose seats were being resolved — both correlation keys only, the audience stays
+     *    `"operator"` (see the registry's entitlement-not-routability note), and `runId` is what tells one
+     *    task falling back twice apart from two tasks falling back once each.
      *    Explicitly-named models never mint this: they refuse at the brain's request gate instead.
      *  - `"route.classifier_unroutable"` (same pre-flight, the other POSTURE) — the derived classifier seat
      *    failed the same pairing pre-flight while the deployment had declared NO fallback
@@ -155,10 +175,9 @@ export interface EngineNotice {
      *    refusal; per-model-hook credentials are invisible to the catalog swap, so the notice is
      *    deliberately conservative (it may fire when a hook-side credential DID change in lockstep).
      *    One aggregated notice per swap; `detail: { entries: [{ modelId, from, to }], total,
-     *    occurrenceId }` (rendered list bounded, total always exact). `occurrenceId` (#495, uuidv7
-     *    minted at the announcement, independent of the `config.models_swapped` line's own): the
-     *    bounded render makes two swaps moving the same first entries byte-identical.
-     *    Dedup key: (code, occurrenceId).
+     *    occurrenceId }` (rendered list bounded, total always exact); the `occurrenceId` is minted at this
+     *    announcement, independently of the `config.models_swapped` line's own, because the bounded render
+     *    makes two swaps moving the same first entries identical. Dedup key: (code, occurrenceId).
      *  - `"config.read_face_deployment_clamped"` (#237) — a deployment-wide `readFace: "open"` is not
      *    in force beside a read-only (verifier) mount: it clamps to "roots" without throwing
      *    (stricter-wins; the clamp verdict stands, only its occurrence was undisclosed). Announced
@@ -194,14 +213,17 @@ export interface EngineNotice {
      *    threw: the `Artifact` tool is not mounted for the task and this is the loud half (an absent seat
      *    is silent; a broken one must not look the same). Once per prepared leg;
      *    `detail: { problem, sessionId, runId }`.
+     *  - `"config.execution_env_capability_invalid"` — a remote env DECLARES a boolean capability key
+     *    (`isolation`, `suspendable`, `canonicalPathAuthoritative`) with a non-boolean value; ABSENCE is a
+     *    supported reading of each and stays silent. Once per key per run; `detail: { key, valueType }`.
      *  - `"config.durable_gate_unavailable"` — a durable-approval MANDATE is in force on a leg with NO
      *    checkpoint store: the per-principal `forceDurableGate` entitlement, or the task's own
      *    `durableApproval` opt-in with no live approver seat (`durableMandateSourceOf`, the predicate the
      *    leg's children inherit). A mandate with no park facility cannot be honored: no ask of the leg can suspend, so each one resolves on the LIVE
      *    chain — a live approver / question face answers in-stream, and with none the ask is denied
      *    fail-closed — and NO durable approval record is written. The ask routing itself is not
-     *    changed by the notice (a store-less leg never could park); the notice is the loud half of a
-     *    posture that used to degrade silently, disclosed before the first ask of the leg. Audience
+     *    changed by the notice (a store-less leg never could park); the notice is its loud half,
+     *    disclosed before the first ask of the leg. Audience
      *    `"user"` (the person whose asks will not be recorded is entitled to that; the operator hears
      *    it through the sink as always). Once per prepared task leg — a resume or a delegated child
      *    is its own leg and says so again; `detail: { sessionId, runId, principal?, cause, source,
@@ -224,12 +246,10 @@ export interface EngineNotice {
      *    (`sessionId` = #433's routing half for these two `"user"`-audience rows; `runId` = #499's
      *    per-run identity, the key this account is actually about — see
      *    {@link undrainedUserInputNotices}; all omitted when the caller has none, never fabricated).
-     *    Per-run, at most once per family (the terminal sweep is a single site) — which is exactly why
-     *    `taskId`/`sessionId` cannot key it: both answer the same value for two runs of one session,
-     *    so two runs each stranding one steer folded into one indistinguishable row.
-     *    **#389 (two corrections).** ① The family now fires on the INTERRUPT path too: `abort()` used
-     *    to empty both queues before agent_end could count them, so the one loss path an operator most
-     *    needs to hear about was the one path that stayed silent. ② On a DURABLE PARK the verdict is
+     *    Per-run, at most once per family (the terminal sweep is a single site) — which is why
+     *    `taskId`/`sessionId` cannot key it: both answer the same value for two runs of one session.
+     *    ① The family fires on the INTERRUPT path too, `abort()` being barred from emptying either queue
+     *    before agent_end can count it. ② On a DURABLE PARK the verdict is
      *    settled at the run tail instead of at agent_end, because the tail first carries the still-
      *    undelivered input onto the committed checkpoint's parked-steer queue (the resume delivers it)
      *    — what is announced is the remainder that could NOT be carried, so a fully-migrated park says
@@ -260,10 +280,9 @@ export interface EngineNotice {
      *        the other question (was the halt CONSUMED), see that seat.
      *    In both lanes: one notice per REAL cut (a `now` that found nothing in flight or whose frame
      *    already rode the imminent boundary, and a halt with nothing in flight, announce nothing — no
-     *    false interrupt claims); `runId` (#499) is the INVOCATION that was cut (the other two ids are
-     *    shared by every run of the session); every cut turn counts toward `maxTurns`, so an interrupt
-     *    storm's cost is bounded and each of its cuts is on the record. Audience `"user"`: the person
-     *    who forced the boundary is the one entitled to see that it landed.
+     *    false interrupt claims); `runId` is the INVOCATION that was cut; every cut turn counts toward
+     *    `maxTurns`, so an interrupt storm's cost is bounded and each of its cuts is on the record.
+     *    Audience `"user"`: the person who forced the boundary is the one entitled to see that it landed.
      *    RETIRED here (BREAKING, named): `"task.injection_priority_unimplemented"` — the ladder is
      *    implemented, so the unhonored-knob disclosure it carried has no referent; consumers must
      *    judge ladder support by VERSION, never by that code's absence.
@@ -350,9 +369,8 @@ export interface EngineNotice {
      *    the inputId, so "accepted at park, screened at redelivery" is auditable end to end. Audience
      *    `"user"` (the person whose instruction was withheld is the one entitled to re-issue it);
      *    `detail: { inputId?, sessionId, runId, taskId? }` — `inputId` is the parked entry's stored
-     *    correlation key (OPTIONAL: a row parked without one exists), and `runId` (#499) names the
-     *    resume leg that withheld it, so a session resumed twice does not report two withholdings as
-     *    one.
+     *    correlation key (OPTIONAL: a row parked without one exists), and `runId` names the resume leg
+     *    that withheld it, so a session resumed twice does not report two withholdings as one.
      *
      *  - `"memory.session_polluted"` (design/178 §3, #324a; message mode-aware since design/336) —
      *    this session's memory crossed into the one-way externally-exposed state (a tool classified

package/dist/core/fs-write-gate-policy.d.ts

@@ -20,7 +20,12 @@ export interface FsWriteGatePolicyOptions {
     acceptDirs?: readonly string[];
     /** Writes whose canonical target lands inside one of these dirs are ALLOWED and never asked
      *  (auto-approved working areas: the scratchpad dir, plan files). Checked before `acceptDirs`
-     *  (same verdict — the split is intent/observability, exemptions are structural not session-won). */
+     *  (same verdict — the split is intent/observability, exemptions are structural not session-won).
+     *  An entry that RESOLVES onto `rootPath` — or above it — grants nothing: a domain that holds the
+     *  root is not a working area but the whole workspace, and a symlinked scratchpad is all it takes.
+     *  Same rule, same predicate as the prompt's advertised writable directories; say "every write here
+     *  is pre-approved" with `defaultWrite: "allow"` instead. `acceptDirs` is NOT judged by it (a person
+     *  may grant the whole root for a session — see the module header). */
     exemptDirs?: readonly string[];
     /** Verdict for a covered write OUTSIDE every domain: `"ask"` (the manual-mode default) routes it
      *  to the ask-resolution chain (live onAsk / durable park / headless deny); `"allow"` is the
@@ -55,17 +60,20 @@ export interface FsWriteGatePolicyOptions {
      * deployment's gate options, not in core-global state: core stays lane-agnostic (no device concept
      * here); the deployment that runs guarded-capable envs arms it.
      *
-     * WHAT ARMED DOES AND DOES NOT CLOSE (honesty boundary, codex r1-1): armed guarantees every covered
-     * write lands through an ATOMIC precondition-verified backend step — the tool's own
-     * canonicalize→write window is closed. It does NOT yet bind THIS GATE's adjudicated canonical key
-     * across an approval wait: the tool re-canonicalizes at execute time, so a symlink swapped between
-     * this gate's verdict and the tool's execution is re-resolved (and then atomically verified against
-     * the NEW resolution). Closing that remaining window needs the adjudicated key carried through a
-     * trusted approval receipt into tool execution — a separate seat, deliberately not smuggled into
-     * this knob.
+     * WHAT ARMED DOES AND DOES NOT CLOSE (honesty boundary): armed guarantees every covered write lands
+     * through an ATOMIC precondition-verified backend step, closing the tool's own canonicalize→write
+     * window. It does NOT bind THIS GATE's adjudicated canonical key across an approval wait: the tool
+     * re-canonicalizes at execute time, so a symlink swapped between this gate's verdict and the tool's
+     * execution is re-resolved (then atomically verified against the NEW resolution). Closing that
+     * remaining window needs the adjudicated key carried through a trusted approval receipt into tool
+     * execution — a separate seat, deliberately not smuggled into this knob.
      */
     requireGuardedWrite?: boolean;
 }
+/** The coded refusal a gate wired with a root-covering exempt domain throws at CONSTRUCTION — the
+ *  `config.*` prepare-refusal family (one exported spelling per member, thrown so the task never
+ *  starts), so a deployment can compare against this constant instead of matching message text. */
+export declare const WRITE_EXEMPT_DIR_COVERS_ROOT_CODE = "config.write_exempt_dir_covers_root";
 /**
  * Build the file-write approval gate policy. Mount via `combinePolicies` alongside the deployment's
  * other layers (sensitive-path deny, session rules, caller policy) — see the module header for the