@sema-agent/core 7.48.0 → 7.49.1

package/dist/core/shell-lexer.js

@@ -1,10 +1,11 @@
+import { shellWordsOf } from "../shell/shell-words.js";
 import { evaluatesOperand, SHELL_WRAPPER_TABLE } from "./shell-wrapper-table.js";
 import { arithmeticHidesRun, carriesSubstitution, freshWord, matchOp, readDoubleQuoted, readExpansion, skipBalanced, skipHeredocBodies } from "./shell-scan.js";
 export { SHELL_WRAPPER_TABLE } from "./shell-wrapper-table.js";
 const WRAPPERS = new Map(Object.entries(SHELL_WRAPPER_TABLE));
-const PREFIX_KEYWORDS = new Set(["if", "then", "else", "elif", "while", "until", "do", "!"]);
-const CLOSING_KEYWORDS = new Set(["fi", "done", "esac", "}", "{", "]]"]);
-const OPAQUE_KEYWORDS = new Set(["for", "select", "case", "function", "coproc", "in"]);
+const PREFIX_KEYWORDS = shellWordsOf("stripped_prefix");
+const CLOSING_KEYWORDS = shellWordsOf("stripped_standalone");
+const OPAQUE_KEYWORDS = shellWordsOf("opaque");
 const ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*\])?\+?=/;
 const DURATION_RE = /^\d+(?:\.\d+)?[smhd]?$/;
 const REDIRECT_OPS = ["<<<", "<<-", "<<", "<>", "<&", "<", ">>", ">|", ">&", "&>>", "&>", ">"];
@@ -222,7 +223,7 @@ export function readShellCommand(source) {
             i = end;
             continue;
         }
-        if (ch === "(" && source[i + 1] === "(" && (!word.started || word.raw === "!") && pendingRedirect === undefined && seg.words.every((w) => w.expands === false && (PREFIX_KEYWORDS.has(w.text) || CLOSING_KEYWORDS.has(w.text) || w.text === "time" || w.text === "-p"))) {
+        if (ch === "(" && source[i + 1] === "(" && (!word.started || word.raw === "!") && pendingRedirect === undefined && seg.words.every((w) => w.expands === false && (shellWordsOf("control_prefix").has(w.text) || CLOSING_KEYWORDS.has(w.text) || w.text === "-p"))) {
             endWord();
             const end = skipBalanced(source, i, "(", ")");
             if (end === undefined) {

package/dist/core/shell-wrapper-projection.js

@@ -38,7 +38,7 @@ function projectRow(row) {
         return executes.length > 0 ? { valueFlags: [], flags: [], commandString: [], executes } : undefined;
     }
     const commandString = sorted(all.filter((o) => o.spec.value?.kind === "shell-text").map((o) => o.spelling));
-    const values = all.filter((o) => o.spec.value?.kind !== "shell-text");
+    const values = all.filter((o) => o.spec.value?.kind !== "shell-text" && o.spec.mode !== "queries");
     const attached = sorted(values.filter((o) => o.arity === "attached" && !o.spelling.startsWith("--")).map((o) => o.spelling));
     const required = row.launcher.requiredOperands ?? 0;
     const duration = required > 0 && row.launcher.requiredOperandSpelling === DURATION_SPELLING;

package/dist/core/skill-grant.js

@@ -3,7 +3,7 @@ import { parsePermissionRule } from "./permission-rules.js";
 import { mountedToolPermissionSeat } from "./mode-policy.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { boundInputHashOf } from "./canonical-json.js";
-import { readToolNameList } from "../agents/tool-filter.js";
+import { readToolNameList } from "./tool-name-list.js";
 import { allowingRows, autoStripped, compileAllowEntry, compileAllowList, inertEntryPhrase, judgeAllowEntries, nonListValueLabel, nonStringMemberLabel, renderListEntry } from "./allow-entry.js";
 export const SKILL_GRANT_ORIGINS = Object.freeze(["model", "user", "inherited"]);
 const FROZEN_SKILL_GRANT_ORIGINS = new Set(["model", "inherited"]);

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -405,6 +405,19 @@ export async function checkpointStoreContract(make, runAssertion) {
         assert.equal("askClass" in bare, false, "an absent askClass must stay OMITTED on the row");
         assert.equal("classes" in bare, false, "an absent classes must stay OMITTED on the row");
     });
+    run("#1320 requirement list: a v10 row's `requires` survives the round-trip verbatim (the whole array, in its order) beside its version; a row without one stays without", async () => {
+        const store = make();
+        const listed = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "rq-list", version: 10, requires: ["binding", "hands_coordinates", "requirements_digest"], requirementsDigest: "a".repeat(64) });
+        const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "rq-none" });
+        for (const cp of [listed, bare])
+            await store.put(cp.token, cp);
+        const back = (await store.get(listed.token));
+        assert.equal(back.version, 10, "the frozen stamp must survive the round-trip");
+        assert.deepEqual(back.requires, ["binding", "hands_coordinates", "requirements_digest"], "the requirement list must survive the round-trip as the same array, in the same order");
+        assert.equal(back.requirementsDigest, "a".repeat(64), "the row digest must survive the round-trip verbatim");
+        const bareBack = (await store.get(bare.token));
+        assert.equal("requires" in bareBack || "requirementsDigest" in bareBack, false, "a row without a list or digest must stay without (never [] / null / \"\")");
+    });
     run("decider pair: a policy-decided allow resolves like a person's — its `policy_allowed` record (party `policy`, the attribution) round-trips verbatim on the resolved winner and as the execution record; the same record is already_recorded, a person's record for that row conflicts", async () => {
         const store = make();
         const cp = createCheckpointFixture();

package/dist/core/store-contracts/mailbox-store-contract.d.ts

@@ -6,22 +6,16 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
  * `contract-harness.ts` for the runner seam and `contract-kit-version.ts` for version lockstep).
  *
  * 为什么这个家族有契约(结构性复发机制,两次实证):契约 harness 此前只喂 InMemory + File 两个
- * 后端,于是没进 harness 的那个后端反复独立漂移 ——
- *   - RB-86:`stores/cc/mailbox-store.ts` 注释自陈 "the contract both bundled backends already
- *     honor, missing only here"(空箱 claimLease 不返回 null,还装上幽灵租约);
- *   - MB1:CC 后端的 `ack` 根本不查 lease 表,注释自陈 "worse than the other two
- *     backends' pre-fix bug"。
- * 两次漏的都是同一个后端。修法不是再补一次点,而是把契约本身变成全后端共跑的资产 —— design/159
- * 再进一步:第三方后端也拿得到同一份资产。
+ * 后端,于是没进 harness 的第三个后端(已退役的 CC inbox 适配器)反复独立漂移 —— RB-86 空箱
+ * claimLease 不返回 null 还装上幽灵租约;MB1 `ack` 根本不查 lease 表。修法不是再补一次点,而是
+ * 把契约本身变成全后端共跑的资产 —— design/159 再进一步:第三方后端也拿得到同一份资产。
  *
  * 分层(与 test/mailbox-contract.ts 的挂载对应):
  * - T1 核心不变量层 = {@link mailboxStoreContract} + {@link mailboxAckOwnershipContract}:每个后端
  *   都必须过。任何后端在这一层变红 = 该后端违约,**不许通过放宽契约让它变绿**。核心层一律用
- *   `scope: "default"`({@link MAILBOX_CONTRACT_SCOPE}),这样租户轴受限的后端(CC inbox 文件)
- *   也跑同一段代码。
+ *   `scope: "default"`({@link MAILBOX_CONTRACT_SCOPE}),这样租户轴受限的第三方后端也跑同一段代码。
  * - T2 可选能力层 = {@link mailboxBundledOnlyContract}:多租户隔离 + 键注入性,只挂具备租户轴/
- *   自有键空间的后端(core 的两个捆绑后端;CC 按 D-3 边界豁免,豁免明细在
- *   `src/stores/cc/mailbox-store.ts` 模块头)。
+ *   自有键空间的后端(core 的两个捆绑后端)。
  *
  * `make()` must return a FRESH, empty store each call. Stores a contract case creates are closed
  * (`close?.()`) when the case ends — the file backend's append fd is refcounted, so a harness that
@@ -41,9 +35,8 @@ export declare function mailboxStoreContract(mk: () => MailboxStore, runAssertio
  */
 export declare function mailboxAckOwnershipContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
 /**
- * T2 可选能力层 —— 只挂具备租户轴 + 自有键空间的后端(core 的两个捆绑后端)。CC 后端按其形态
- * 明文豁免(豁免明细在 `src/stores/cc/mailbox-store.ts` 模块头,D-3 裁定),不是「没做到所以
- * 放宽」:核心层没有一条为了任何后端而弱化。第三方后端若有租户轴,应当也挂这一层。
+ * T2 可选能力层 —— 只挂具备租户轴 + 自有键空间的后端(core 的两个捆绑后端)。核心层没有一条
+ * 为了任何后端而弱化。第三方后端若有租户轴,应当也挂这一层。
  */
 export declare function mailboxBundledOnlyContract(mk: () => MailboxStore, runAssertion?: ContractAssertionRunner): Promise<void>;
 export interface MailboxCrossProcessContractHooks {

package/dist/core/store-contracts/session-store-incarnation-contract.d.ts

@@ -0,0 +1,27 @@
+import { type SessionStore } from "../session.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+/**
+ * The cross-backend contract for the SESSION INCARNATION face ({@link SessionStore.incarnationOf}):
+ * the token naming WHICH occupant holds a session id. vitest-free (see `contract-harness.ts`); mount it
+ * on every store that implements `incarnationOf` — the face is optional on the interface, so this kit
+ * is a separate opt-in kit rather than a skipped case inside another one (a skipped case is how an
+ * unimplemented face reads green). A store WITHOUT the face fails every case loudly.
+ *
+ * The law the cases pin: the token is a cell of the session ROW, minted once when the row comes into
+ * existence and answered unchanged by every later read of that row — a cache forgetting the session or
+ * a second store over the same rows does not change it, deleting the row and handing the id out again
+ * does, a fork is a new occupant. A `SessionRepo` author runs it through the bundled cache layer
+ * (`make: () => new TtlSessionStore({ repo })`, `reopen: () => new TtlSessionStore({ repo })`).
+ *
+ * `make()` must return a FRESH, empty store each call; each case disposes the store it built.
+ */
+export interface SessionStoreIncarnationContractHooks {
+    /** Delete `sessionId`'s session ROW through the backend's own deletion path (history and all), so
+     *  that a later `acquire(sessionId)` creates a new session under the same id. */
+    deleteSession: (store: SessionStore, sessionId: string) => Promise<void>;
+    /** A SECOND, independent store instance over the same rows as `store` — what a restarted process or
+     *  another replica constructs. The kit disposes it. */
+    reopen: (store: SessionStore) => SessionStore;
+    runAssertion?: ContractAssertionRunner;
+}
+export declare function sessionStoreIncarnationContract(make: () => SessionStore, hooks: SessionStoreIncarnationContractHooks): Promise<void>;

package/dist/core/store-contracts/session-store-incarnation-contract.js

@@ -0,0 +1,92 @@
+import { strict as assert } from "node:assert";
+import { hasSessionFork } from "../session.js";
+import { beginContract } from "./contract-harness.js";
+const ID_A = "0198fa00-0000-7000-8000-0000000014a1";
+const ID_B = "0198fa00-0000-7000-8000-0000000014b2";
+const ID_NONE = "0198fa00-0000-7000-8000-0000000014ff";
+async function tokenOf(store, sessionId) {
+    assert.equal(typeof store.incarnationOf, "function", "this kit is for stores that implement SessionStore.incarnationOf");
+    return store.incarnationOf(sessionId);
+}
+function assertToken(token, what) {
+    assert.equal(typeof token, "string", `${what}: a session row created through this store must carry an incarnation`);
+    assert.notEqual(token, "", `${what}: an empty token names nobody`);
+}
+export async function sessionStoreIncarnationContract(make, hooks) {
+    const { run: runRaw, settle } = beginContract(hooks.runAssertion);
+    const run = (name, fn) => runRaw(name, async () => {
+        const store = make();
+        try {
+            await fn(store);
+        }
+        finally {
+            await store.dispose();
+        }
+    });
+    run("a session created through acquire carries a token, and every later read of the row answers the same one", async (store) => {
+        await store.acquire(ID_A);
+        const first = await tokenOf(store, ID_A);
+        assertToken(first, "after acquire");
+        await store.acquire(ID_A);
+        assert.equal(await tokenOf(store, ID_A), first, "a re-acquire reopens the same occupant");
+        await store.forget?.(ID_A);
+        assert.equal(await tokenOf(store, ID_A), first, "the token is the row's, not the cache's: forgetting the cached view must not change it");
+        await store.acquire(ID_A, { requireExisting: true });
+        assert.equal(await tokenOf(store, ID_A), first, "a require-existing reopen after the cache forgot it is still the same occupant");
+    });
+    run("the session acquire hands back carries the token incarnationOf answers — a run's memory seat reads the former", async (store) => {
+        const acquired = await store.acquire(ID_A);
+        const byId = await tokenOf(store, ID_A);
+        assertToken(byId, "by-id read");
+        assert.equal((await acquired.session.getMetadata()).incarnation, byId, "two faces of one row cell must agree, or the seat and the by-id read name two occupants");
+    });
+    run("a second store over the same rows (a restart, a replica) answers the same token — the token lives in the row, not in an instance", async (store) => {
+        await store.acquire(ID_A);
+        const first = await tokenOf(store, ID_A);
+        assertToken(first, "first instance");
+        const second = hooks.reopen(store);
+        try {
+            assert.equal(await tokenOf(second, ID_A), first, "an instance-local token would name a different occupant after every restart");
+            await second.acquire(ID_A, { requireExisting: true });
+            assert.equal(await tokenOf(second, ID_A), first, "reopening the session on the second instance is still the same occupant");
+        }
+        finally {
+            await second.dispose();
+        }
+    });
+    run("two sessions never share a token, and an id with no session answers undefined (unknown — not an error, not a token)", async (store) => {
+        await store.acquire(ID_A);
+        const generated = await store.acquire();
+        const a = await tokenOf(store, ID_A);
+        const g = await tokenOf(store, generated.sessionId);
+        assertToken(a, "explicit id");
+        assertToken(g, "generated id");
+        assert.notEqual(a, g, "two sessions are two occupants");
+        assert.equal(await tokenOf(store, ID_NONE), undefined, "no row ⇒ unknown");
+    });
+    run("a deleted id handed out again is a NEW occupant: a fresh token, never the previous occupant's", async (store) => {
+        await store.acquire(ID_A);
+        const before = await tokenOf(store, ID_A);
+        assertToken(before, "first occupant");
+        await hooks.deleteSession(store, ID_A);
+        assert.equal(await tokenOf(store, ID_A), undefined, "a deleted row has no occupant");
+        await store.acquire(ID_A);
+        const after = await tokenOf(store, ID_A);
+        assertToken(after, "second occupant");
+        assert.notEqual(after, before, "the id was recycled — the previous occupant's records must not bind this one");
+    });
+    run("a fork is a new occupant: a fresh token, and the source keeps its own", async (store) => {
+        if (!hasSessionFork(store))
+            return;
+        await store.acquire(ID_B);
+        const source = await tokenOf(store, ID_B);
+        assertToken(source, "fork source");
+        const forkedId = await store.fork(ID_B);
+        assert.ok(forkedId !== null, "forking an existing session returns the fork's id");
+        const forked = await tokenOf(store, forkedId);
+        assertToken(forked, "fork");
+        assert.notEqual(forked, source, "a fork copies the history, never the occupant");
+        assert.equal(await tokenOf(store, ID_B), source, "forking does not touch the source's occupant");
+    });
+    await settle();
+}

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

@@ -12,6 +12,8 @@ export declare class StubExecutionEnv implements ExecutionEnv {
      *  member off a `ExecutionEnv | StubExecutionEnv` union; the no-I/O stub produces no target
      *  content, so it never declares (always `undefined` — the trusted-side default). */
     readonly externalContentTarget?: boolean;
+    /** `ExecutionEnv.cdPath`: the stub runs no shell, so no shell receives a `CDPATH`. */
+    readonly cdPath: readonly string[];
     constructor(cwd?: string);
     private fsErr;
     absolutePath(path: string): Promise<Result<string, FileError>>;

package/dist/core/stub-env.js

@@ -2,6 +2,7 @@ import { ExecutionError, FileError, err, } from "../internal/harness.js";
 export class StubExecutionEnv {
     cwd;
     externalContentTarget;
+    cdPath = [];
     constructor(cwd = "/") {
         this.cwd = cwd;
     }

package/dist/core/synthetic-read-verdict.js

@@ -1,4 +1,4 @@
-import { describeThrown, engineSettlementOf, refuseOutOfContractDecision } from "./tool-policy.js";
+import { attestationOf, describeThrown, refuseOutOfContractDecision } from "./tool-policy.js";
 import { skillRowRefusal } from "./skill-grant.js";
 import { applyPersistedTightening } from "./persisted-rule-arms.js";
 import { readOrgRuleLane, readPersistedRuleLane } from "./rule-lane-reads.js";
@@ -62,7 +62,7 @@ export function createSyntheticReadJudge(layers) {
             }
             if (read.action !== "deny")
                 return undefined;
-            if (engineSettlementOf(d, req) !== undefined) {
+            if (attestationOf(read, req)?.settlement !== undefined) {
                 cannot(layer, "approval_seat", "the policy would ask an approver, who is never consulted for a visibility probe");
                 return undefined;
             }

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

@@ -9,6 +9,7 @@
 import type { ActorAssertion } from "../internal/llm.js";
 import type { TaskResult } from "./task-result.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
+import type { ProviderCondition, ProviderConditionSource } from "../brain/provider-dialect.js";
 /**
  * Identity fields carried by every CONTENT event of a task stream (design/99 §E2 — lightweight message
  * identity). Both are OPTIONAL and ADDITIVE; a consumer that ignores them is unchanged.
@@ -198,6 +199,25 @@ export interface BrainStatus {
      * `control_request_progress` frame, where CC itself makes the key optional.
      */
     errorStatus?: number;
+    /**
+     * What the provider said about the account or its capacity on the response being retried — one word of
+     * `PROVIDER_CONDITIONS`, judged off the provider dialect table keyed by where the request went
+     * (`brain/provider-dialect.ts`). Fills the gap {@link errorStatus} states: {@link errClass} `rate_limit`
+     * buckets a 429 that clears on its own with one the provider pinned on the account. Only the RETRYABLE words
+     * ride a retry frame (`throttled` / `overloaded` / `unknown`): a response judged `quota_exhausted` or
+     * `stop_other` is not retried — its word rides the terminal (`terminal.detail.providerCondition`) — unless
+     * the provider's own `x-should-retry: true` sent it back into the ladder, in which case the frame states the
+     * word the response was judged by.
+     *
+     * PRESENCE — exactly the connect-ladder backoff frames that carry {@link errorStatus}: a response named the
+     * failure. ABSENT on a transport failure, a stall, a mid-stream tear, the output-cap re-send (a re-shaped
+     * request, not a provider condition), `circuit_open`, and the terminal `recovered` / `gave_up` frames. A
+     * consumer reads absence as "not judged" — the same reading as `unknown`: back off, do not claim a quota.
+     */
+    providerCondition?: ProviderCondition;
+    /** Which evidence {@link providerCondition} rests on (`unified_header` / `provider_code` / `status`). Present
+     *  exactly when it is. */
+    providerConditionSource?: ProviderConditionSource;
 }
 /**
  * design/97 CORE-8 (③): one lightweight TOOL-ACTIVITY beat surfaced from a running task, for a per-agent live
@@ -282,9 +302,19 @@ export type TaskEvent = ({
 } & TaskEventIdentity) | ({
     type: "tool_start";
     toolCallId: string;
-    toolName: string; /** {@link ToolSpec.label} when distinct from `toolName` (design/71 liveness); omitted otherwise. */
+    toolName: string;
+    /** {@link ToolSpec.label} when distinct from `toolName`; omitted otherwise. */
     label?: string;
     args: unknown;
+    /**
+     * @contract tool_start.recovered — `true` on a start frame the engine minted at the moment it CLOSED a call
+     * whose start never went out on this stream: an interrupted run's reconcile closing a call the loop never
+     * reached, or a resumed process closing a call a dead process had announced. Every `tool_end` is preceded by
+     * a `tool_start` with the same id on the same stream — this frame is how that holds for those closes. `args`
+     * is the call's input as the transcript recorded it. It asserts NOTHING about execution (whether the call
+     * ran is the paired `tool_end.notExecuted`); absent on every start the loop announced itself.
+     */
+    recovered?: true;
 } & TaskEventIdentity) | ({
     /**
      * A LIVENESS TICK for a tool call that is still running. Emitted on the run's own queue between this
@@ -477,17 +507,41 @@ export type TaskEvent = ({
      * denied by which LAYER), `settlement` (how the ask this pass consumed ENDED — a person's yes or
      * no with the channel's attribution and, on a bare "no", no note; a window that elapsed and whose;
      * nobody reachable; the wait aborted…) and `origin` (who ASKED). It is the SAME object the
-     * `permissionDenied` observer received and the engine's per-call sideband recorded — one mint, three
+     * `permissionDenied` observer received and the call's occurrence record holds — one mint, three
      * faces — so a renderer never branches on prose to tell "a person refused" from "the window closed".
      *
      * WHERE IT COMES FROM — never inferred here: the gate mints it at its exit, the decide lane mints it
      * from the host's decision facts joined with the row's persisted origin.
      *
-     * ABSENT on every frame of a call the gate never saw (a tool call on an unarmed gate, a deferred
-     * re-issue, a reconcile-recovered orphan). A gated call's frame ALWAYS carries it — an absence is
-     * not a fact about the call, and a consumer must not read one out of it.
+     * THE LATEST RECORD: a station that refuses the call AFTER its gate exit (the shell read admission that
+     * re-establishes what the gate judged and finds it moved, a resumed leg's re-checks) adds one more
+     * record, minted as a veto — the refusing layer is the disposition, an approval already given stays on
+     * the settlement — and this member is that record. A call refused after its gate allowed it therefore
+     * reads `denied`, never `allowed` beside an error, and {@link isError} is `true` whatever the tool's own
+     * result said.
+     *
+     * ABSENT on every frame of a call no gate exit on this stream saw (a tool call on an unarmed gate, a
+     * deferred re-issue, a call a reconcile closed that never reached a gate here). A gated call's frame
+     * ALWAYS carries it — an absence is not a fact about the call, and a consumer must not read one out of it.
      */
     gate?: import("./gate-outcome.js").GateOutcome;
+    /**
+     * @contract tool_end.wireName — on a REFUSED call's frame only (`gate.disposition.kind === "denied"`): the name of
+     * the tool the call dispatched to on the live roster — the name the gate judged and the deny observer's `toolName`
+     * — where {@link toolName} is the model's spelling (an alias, a retired name the roster still answers to). A
+     * refusals list keyed on the tool reads this member; absent on every other frame, and on a refused frame whose
+     * station did not know the roster name.
+     */
+    wireName?: string;
+    /**
+     * @contract tool_end.notExecuted — `true` when the engine has POSITIVE evidence this call never executed:
+     * the loop closed it without running it (a sibling settled by a halted batch, a call a turn interrupt
+     * reached before it started) or an interrupted run's reconcile closed a call this run never started.
+     * ABSENT means only that no such evidence exists — never "it ran": a call closed with its outcome unknown
+     * (a reconcile at the next process start, a call interrupted mid-execution) carries no mark, because
+     * telling a consumer it did not run could invite a replay of a write that already took effect.
+     */
+    notExecuted?: true;
     /**
      * design/99 §E1 — `true` when {@link output} was SIZE-bounded by core (the full body exceeded the cap and
      * was degraded to a truncated string). Lets a consumer detect truncation programmatically instead of

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

@@ -11,7 +11,7 @@ import type { NestedUsage } from "./tool-spec.js";
  * `"suspended"` (design/45) is a **non-terminal** outcome: the task hit a durable tool-policy gate
  * (`ask` with a `CheckpointStore` wired) and persisted a checkpoint instead of finishing — resume it
  * with `runner.resume(checkpointToken, outcome)`. v1 contract: it is only safe at the **top-level
- * `runTask` boundary**; the orchestrators (cascade/teacher/verify/team) map an unexpected `suspended`
+ * `runTask` boundary**; the orchestrators (cascade/verify/repair-loop) map an unexpected `suspended`
  * to `failed` + `errorCode:"unexpected.suspended"` and pass the token up (§11 Q6, hard boundary).
  *
  * `"needs_review"` (design/76 §2.5, dry-run / shadow; design/80 D-B, plan-gate) is also a **non-terminal,

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

@@ -426,15 +426,34 @@ export interface TaskSpec {
      */
     tools?: ToolSpec[];
     /**
-     * per-scenario tool ROSTER (true unmount, NOT a permission gate): wire names listed here
-     * are removed from the mounted tool set AFTER assembly — their schemas never reach `tools[]`
-     * (unlike a policy deny, which gates calls but still ships the schema bytes every request —
-     * measured at zero token savings). Exact wire-name match (aliases resolve to their
-     * canonical wire name at mount, so list the canonical name). Unknown names are ignored (a
-     * center-distributed roster may cover tools this deployment doesn't mount). The injected
-     * ToolSearch cannot be excluded (it mounts after this filter, only when deferred tools exist).
-     * ⚠️ Excluding structural tools (submit_output / ReportBlocked) can strand the task — the caller
-     * owns that risk, same trust level as assembling `spec.tools` itself.
+     * The run's tool ALLOWLIST — the availability selector (true unmount, NOT a permission gate): when set, the run may use only the
+     * tools it names, out of everything the engine would otherwise mount for it (the caller's tools, the hands, the engine's own
+     * tools, MCP and A2A tools, scenario and leg tools); the rest never reach `tools[]`. Omitted ⇒ the default set (a delegated
+     * child: whatever its parent could use). `[]` ⇒ no tools. An entry `"*"` ⇒ no allowlist on this layer (still bounded by the
+     * ceiling a spawning run handed down — a child's `"*"` never widens its parent).
+     *
+     * Entries are read like {@link excludeTools}: a wire name or an alias it declares, `mcp__srv` / `mcp__srv__*` for every tool
+     * of a server (including tools it lists later), a glob over the tool segment. The engine resolves the list against its OWN
+     * roster at prepare — a host passes the names it was given and never computes a complement. A name no tool answers to, a
+     * protocol-wide `mcp__*`, or an entry that is not a string is REFUSED at prepare (`config.tool_face_control`). The same
+     * compiled selector is applied on every later roster change (an MCP refresh or re-dial, the deferred-search lane): an exact name
+     * admits no new tool. Deferral is reached through ToolSearch, so a list that leaves it out defers nothing.
+     *
+     * A tool a leg relies on (a delegated child's ReportBlocked, a teammate's SendMessage, a goal iteration's DeclareDone, an
+     * observer's report tool — the catalog's protocol column) is not an allowlist's to name; a denylist that reaches one on such a
+     * leg is refused at prepare.
+     */
+    allowTools?: string[];
+    /**
+     * per-scenario tool ROSTER removal (true unmount, NOT a permission gate): the tools this list names are removed from the
+     * mounted tool set AFTER assembly — their schemas never reach `tools[]` (unlike a policy deny, which gates calls but still
+     * ships the schema bytes every request — measured at zero token savings). The DENY half of the run's tool selector, read
+     * exactly as a sub-agent's denied tools are: a wire name or an alias it declares; `Tool(content)` names the whole `Tool`;
+     * `mcp__srv` / `mcp__srv__*` / a glob over the tool segment for a server's tools, `mcp__*` for every MCP tool (including tools
+     * a server lists later). A name no tool answers to, `"*"`, or an entry that is not a string is REFUSED at prepare
+     * (`config.tool_face_control`) — a misspelt exclusion guards nothing. A deny wins over {@link allowTools}.
+     * ⚠️ A list that reaches a tool this kind of leg relies on (see {@link allowTools}) is refused; excluding a host-requested
+     * structural tool (the structured-output tool) can still strand the task — the caller owns that risk.
      */
     excludeTools?: string[];
     /**
@@ -854,6 +873,20 @@ export interface TaskSpec {
      * (#123). The write faces are untouched.
      */
     readDenyPatterns?: readonly import("../tools/fs/read-deny.js").ReadDenyEntry[];
+    /**
+     * TASK-layer rows ADDED to the write-protection table ({@link readDenyPatterns}' law): the run's table is the deployment's
+     * ({@link RunnerDeps.writeProtectedPaths}) UNION these; `[]` ≡ absent; no task-layer value removes a deployment row. A
+     * covered write is the judge's mandated ask (`write_protection`), as for a deployment row. Bad shapes refuse at prepare
+     * (`config.invalid_argument`); rides every engine-built child spec add-only.
+     */
+    writeProtectedAdditions?: readonly import("./write-protect.js").WriteProtectedEntry[];
+    /**
+     * TASK-layer denies ADDED to the compliance posture ({@link readDenyPatterns}' law): the run's deny set is the deployment's
+     * ({@link RunnerDeps.compliancePostureResolver}) UNION these; `[]` ≡ absent; nothing here removes a deployment deny. A hit
+     * is refused exactly as a deployment deny is. Members outside the closed capability set refuse at prepare
+     * (`config.invalid_argument`) — never a silently dropped deny; rides every engine-built child spec add-only.
+     */
+    complianceAdditionalDenies?: readonly import("./compliance.js").ComplianceCapability[];
     /**
      * design/199 件A — the TASK layer's read-face containment declaration
      * ({@link import("../tools/fs/containment-face.js").ContainmentFace}). "roots" pins this task (and, via the

package/dist/core/terminal-cause.d.ts

@@ -9,6 +9,9 @@
  * `runner/terminal-projection.ts` — the one cause→plane derivation.
  */
 import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { ProviderCondition, ProviderConditionSource } from "../brain/provider-dialect.js";
+import type { RequestRoute } from "../brain/request-route.js";
+import type { ModelOutputInvalidCause, OutputLimit } from "../internal/llm.js";
 /**
  * WHY a run ended — ONE tagged cause, and the ONLY terminal record a {@link TaskResult} carries. The run
  * loop's terminal arbitration used to decide a `status` word plus seven optional plane fields one by one
@@ -32,6 +35,14 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
  */
 export type TerminalCause = {
     kind: "completed";
+    /**
+     * A machine-readable account beside a completion, for the one shape that completes yet may be short:
+     * `finish_reason_unknown` — the final turn's provider ended it with a stream-end word the brain does not read
+     * (`AssistantMessage.finishReasonUnknown`); the turn was kept as the model left it, and the run announced the
+     * word (`route.finish_reason_unknown`). PRESENCE: only when the final assistant message carried that seat and the
+     * run completed on it; every other completion leaves it absent.
+     */
+    detail?: TerminalCompletedDetail;
 } | {
     kind: "failed";
     /**
@@ -69,14 +80,16 @@ export type TerminalCause = {
     /** Human-readable failure text. */
     message?: string;
     /**
-     * A machine-readable account of the failure beside `code`, for the one shape a consumer offers its own way out
-     * of: `provider_rejected` — the provider REFUSED the request as sent (a 4xx answer) and that refusal named this
-     * result. `status` is the refusal's HTTP status (`TaskResult.apiFailure.status`, the same value);
-     * `code` the provider's own word for it from its error envelope (`AssistantMessage.apiErrorCode`), when it
-     * stated one. PRESENCE: only on that terminal — a run whose higher-ranked cause named the result, a 5xx, a
-     * connect / stream failure, an in-band error inside a 200 and every non-provider failure leave it absent.
-     * A 401 / 403 (credentials) and a 429 (rate limit) are refusals too: branch on `status` (or on `code` above)
-     * to tell a request a consumer may change and resend from one it may not.
+     * A machine-readable account of the failure beside `code` — the fact the failure's mint point stated, projected
+     * once ({@link TerminalFailureDetail}; branch on `detail.kind`, never on `message`):
+     *  - `provider_rejected` — the provider REFUSED the request as sent (a 4xx answer) and that refusal named this
+     *    result. `status` is the refusal's HTTP status (`TaskResult.apiFailure.status`, the same value); `code` the
+     *    provider's own word (`AssistantMessage.apiErrorCode`); `route` the request's route. A run whose
+     *    higher-ranked cause named the result, a 5xx, a connect / stream failure and an in-band error inside a 200
+     *    carry none. A 401 / 403 (credentials) and a 429 (rate limit) are refusals too: branch on `status`.
+     *  - `coded` — the run threw a coded error (this `code`) whose throw site stated a structured `detail`.
+     *  - `model_output_invalid` — the model's final turn failed because its tool calls could not be executed.
+     * PRESENCE: only when the arm that named this result has such a fact to project; absent otherwise.
      */
     detail?: TerminalFailureDetail;
     /**
@@ -144,14 +157,84 @@ export type TerminalCause = {
      */
     restoreMode?: "snapshot" | "park_only";
 };
-/** The machine-readable account a `failed` cause may carry ({@link TerminalCause}). `kind` is closed; one member. */
-export interface TerminalFailureDetail {
+/** The machine-readable account a `completed` cause may carry ({@link TerminalCause}). `kind` is closed; one member. */
+export interface TerminalCompletedDetail {
+    kind: "finish_reason_unknown";
+    /** The provider's stream-end word, in the provider echo shape (`?` when it had bytes outside it). */
+    finishReasonUnknown: string;
+}
+/**
+ * The machine-readable account a `failed` cause may carry ({@link TerminalCause}) — the ONE projection of a fact the
+ * failure's mint point already stated, carried as it was stated (a missing fact stays missing; nothing is re-derived
+ * from the message). `kind` is closed:
+ *  - `provider_rejected` — the provider REFUSED the request as sent (a 4xx answer) and that refusal named the result:
+ *    the terminal message's refusal account (`apiErrorStatus` / `apiErrorCode` / the provider-condition verdict / the
+ *    request's `apiErrorRoute`).
+ *  - `coded` — a failure THROWN with a machine code whose throw site stated a structured `detail` beside it (e.g. a
+ *    `CheckpointError`'s `{ reason }` on `resume.parent_constraint_mismatch`): that detail, as a JSON-plain snapshot.
+ *    `terminal.code` is the same error's code.
+ *  - `model_output_invalid` — the model's turn failed because its tool calls could not be executed: the terminal
+ *    message's `modelOutputInvalid` account.
+ * New members join with a minor; a consumer that branches on `kind` keeps a default arm.
+ */
+export type TerminalFailureDetail = {
     kind: "provider_rejected";
     /** The refusal's HTTP status, 400–499. */
     status: number;
     /** The provider's own word for the refusal (its error envelope's `error.code`, else `error.type`), when stated. */
     code?: string;
-}
+    /**
+     * What the refusal says about the account — the engine's closed word for it (`PROVIDER_CONDITIONS`), judged off
+     * the provider dialect table by where the request went: `quota_exhausted` (stop; someone must act or a window
+     * must reset), `throttled` / `overloaded` / `unknown` (a retryable condition the retry budget ran out on, or the
+     * provider's own `x-should-retry: false` stopped), `stop_other` (credentials, model access, the request itself).
+     * The terminal's reading of the same verdict the call's retry frames carried. Present whenever the terminal
+     * message states one (`AssistantMessage.providerCondition`); a host-minted message that did not judge leaves it
+     * absent.
+     */
+    providerCondition?: ProviderCondition;
+    /** Which evidence {@link providerCondition} rests on. Present exactly when it is. */
+    providerConditionSource?: ProviderConditionSource;
+    /** The terminal message's `providerResetAtMs`, carried beside a `quota_exhausted` condition. */
+    providerResetAtMs?: number;
+    /**
+     * The route the refused request took (`AssistantMessage.apiErrorRoute`): where its credential came from, how it
+     * rode, which knob named its root — the knob words of `ROUTE_CREDENTIAL_PAIRING`, never a key value or a URL.
+     * Present whenever the terminal message states one (the first-party brains always do); a host-minted message that
+     * states none leaves it absent.
+     */
+    route?: RequestRoute;
+} | {
+    kind: "coded";
+    /**
+     * The thrown error's own `detail`, as its throw site stated it — a snapshot of its JSON-plain members (strings,
+     * finite numbers, booleans, null, and arrays / plain objects of those, bounded; a member of any other kind is left
+     * out; bytes — an `ArrayBuffer` view, an index-keyed object — are never a record). A member under a credential
+     * name (the env-credential judge's names: `password`, `apiKey`, `token` …) stands as `"[redacted]"`, unread; every
+     * other string leaf passes the secret-tier redaction (credential shapes masked; a path is kept — it rides this
+     * structured seat, never `message`); a member whose key is not JSON-safe (visible ASCII 1–128, nothing the
+     * redaction would mask) is left out. Read off the same link of the error's `cause` chain whose `code` became
+     * `terminal.code`. PRESENCE: only when that link carried a plain-object `detail` with at least one such member — a
+     * code thrown without one (or a higher-ranked terminal that named the result) leaves the whole account absent.
+     */
+    detail: CodedFailureDetail;
+} | {
+    kind: "model_output_invalid";
+    /** Which drop cause failed the turn (`MODEL_OUTPUT_INVALID_CAUSES`: `truncated` — arguments cut before they
+     *  parsed; `unnamed` — a call with no tool name). The same words `task.tool_turn_incomplete` announces. */
+    cause: ModelOutputInvalidCause;
+    /** With `truncated`: the output-cap facts the stream reported (the cap stop, the counted output, the request's
+     *  cap) — what the brain's sentence words as its cap clause. */
+    outputLimit?: OutputLimit;
+};
+/** A JSON-plain value as a `coded` account carries it. */
+export type CodedFailureDetailValue = string | number | boolean | null | readonly CodedFailureDetailValue[] | {
+    readonly [key: string]: CodedFailureDetailValue;
+};
+/** The `coded` account's body: the thrown error's `detail` members ({@link TerminalFailureDetail}). */
+export type CodedFailureDetail = {
+    readonly [key: string]: CodedFailureDetailValue;
+};
 /**
  * The endings of a `userPromptSubmit` hook that keep a prompt from being submitted — the closed set of
  * {@link TerminalBlockedDetail.cause} words:

package/dist/core/tighten-task-spec.d.ts

@@ -11,10 +11,11 @@ export declare class TaskSpecTightenError extends Error {
  *  - **`toolPolicy`** — both set ⇒ `combinePolicies(base, override)` (deny-wins; the base's denials survive,
  *    the override can only ADD denials/asks). Either alone ⇒ that one. This is the central fix: a blind spread
  *    would drop the base policy entirely.
- *  - **`handsReadOnly`** — `true` is stricter. `base:true` + `override:false` ⇒ **throw** (loosening). Otherwise
- *    the stricter (`true` if either is true) wins.
- *  - **`approvalReach`** — `"none"` (nobody can be asked) is the only word; a base declaration survives an override that
- *    omits it or writes `undefined`.
+ *  - **every row of the clamp table** (`CLAMP_SET`: `handsReadOnly`, `interactiveTools`, `approvalReach`, the two
+ *    containment faces, `readDenyPatterns`, `oneShot`, `memoryPersistenceCapable`, `fileHistory`) — a base carrying the
+ *    row's restricting value meeting an override that states a different one ⇒ **throw** (loosening); otherwise the
+ *    restricting value wins if either side carries it, an add-only list unions, and an override writing `undefined`
+ *    erases nothing.
  *  - **`shellGate`** — one value (`"always"`, the operator floor). Either side set ⇒ the floor stands; it cannot
  *    be loosened because absence is the only other state and an override cannot unset a base value.
  *  - **`onAsk`** — no safe automatic merge (the approver and the policy must be coordinated). Both set to