@sema-agent/core 7.5.0 → 7.5.2

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 7.5.2 — 2026-09-06
+
+Maintenance release: design/390 slices S3–S4 complete the `prepareTask` decomposition (4 756 → 1 666 driver lines, 34 phase modules), one settlement-path narrowing (#587), and the wire-manifest tooling that the 7.5.1 review asked for (#588 / #589). **No BREAKING change**: the export surface is byte-identical to 7.5.1; the only behaviour delta is that a reserved-tool-name collision now disposes an acquired protocol handle once instead of twice (below).
+
+### Changed — design/390 S3–S4: the rest of `prepareTask` becomes phases
+- Extracted verbatim, each with one Input (every seat classified) and one Result: memory-engine session, prompt assembly (two live accessor cells `systemPromptSeat` / `centerAdoptionRef`), policy chain (1 351 lines; the ask-origin mint sites move, the words and the closed set do not), context lane, turn wiring, the park lane as four phases (`prepare-ask-lane` / `prepare-suspend-saga` / `prepare-boundary-parks` / `prepare-park-ask`), and the two tool-gate stations (`prepare-gate-stations`). The driver holds five direct phase calls where it held nested closures and an `if` block; the block-activation predicate is minted once (`gateMachineryActive`).
+- Layer 1 machinery (reached down for by phases, never a phase): `permission-rule-lanes.ts` (formerly `prepare-permission-rules.ts`), `inherited-ask-grants.ts`, `prompt-hash-salt.ts`, `abort-race.ts`, `remote-env-retry.ts`, `park-commit.ts`, `content-ask-bindings.ts`, `announce-once-ledger.ts` (formerly `prepare-announce-once.ts`), `compaction-call-options.ts`; `docs/LAYERING.json` `uncovered` list is empty.
+- Contract seats: `AskLane` / `SuspendSaga` / `ParkAsk` are one fact each (a lane exists or it does not) rather than several independently-optional closures; `PromptFeatureFlags` / `SuspendSagaOutcome` and the park-lane seat types live in `contracts.ts`.
+- Unchanged and pinned: the suspendAsk 13-parameter `AskCarry`, `ASK_ORIGINS` and its fence, the 23 gate stations (words, order, deny sources), the durable park row, `tool_end` settlement words, the tool roster order (owner table on `Prepared.tools`).
+
+### Changed (narrowing, named) — #587 one releaser on the reserved-name path
+- A caller tool whose name collides with a protocol tool's reserved name still makes prepare throw `config.reserved_tool_name`; the acquired MCP / A2A handle is now released exactly once by the RollbackStack unwind (A2A before MCP). 7.5.1 disposed it inline and again on unwind. Pinned as "exactly once" at the transcript and unit level.
+
+### Gates / tooling
+- `test/runner-layer-order.test.ts`: the five-layer order (vocabulary < machinery < phases < orchestrator < runner) is asserted over the REAL import graph of `src/core/runner/*.ts`; the three upward exemptions are enumerated and the table cannot grow silently.
+- `test/prepare-prompt-assembly-zero-write-window.test.ts` (design/238 T16): prompt assembly performs no session write between its start and the prompt-epoch pin; unknown storage methods count as writes (fail-closed).
+- `scripts/wire-changes.mjs`: `declarationMoves[]` (#589) lists every module-exported name whose declaring file changed while the name stayed exported (`onSurface` marks barrel names) — informational, never counted as breaking; the CLI says on stderr when `to` resolves to HEAD (#588: amending that commit orphans the manifest; the release order is tag first, then generate against the tag). `wire-changes/core@7.5.1.json` was regenerated against its tag with 16 informational move rows.
+- `scripts/ship-post-lint.mjs`: a checksum label followed by one markdown backtick still labels the digest (the 7.5.1 post had hand-segmented its shasum to get past this leg).
+- G5 phase-contract floor `KNOWN_INPUT_FIELDS` 371 → 667; unannotated-Input exceptions 4 → 1; receiving-side pins added for the context lane's `charsPerToken` wiring.
+
+## 7.5.1 — 2026-09-06
+
+Maintenance release: the design/390 runner decomposition (slices S0–S2), the post-7.5.0 gate repairs, and one summary hardening (#566). **No BREAKING change**: the export surface is byte-identical to 7.5.0 (export snapshot unchanged); the only observable delta is the label text of a wedged dispose on the prepare-throw path (below).
+
+### Changed — design/390 S0–S2: `prepareTask` decomposed into phase modules (14 229 → 7 723 lines), one contract each
+- 24 phase modules under `src/core/runner/prepare-*.ts`, each `prepareX(input: Input): Result` with every Input seat classified (owned / borrowed-readonly / borrowed-mutable + writer table / ownership-ref) and the driver reduced to one destructuring call per phase. Extracted verbatim: offload wrappers, execution-env (`OwnedEnvSeat`), file-history, run-refs, protocol-tools (MCP/A2A), question-face, LSP, project-context, prompt-inputs, defer-classify, listings, inherited-gate, caps-and-workflow, delegation-surface, tool-disclosure-mount, wiring-manifest; helpers `contracts.ts`, `workspace-path.ts`, `derived-route-fallback.ts`, `checkpoint-scope.ts`, `denial-limit-arms.ts`.
+- **RollbackStack** (`rollback-stack.ts`): every resource acquired during prepare registers its disposer the moment it is acquired (env, MCP clients, A2A peers); a prepare throw unwinds them in reverse order, each bounded and reported, replacing the driver's explicit `if (handle) dispose` catch legs. The A2A registration keys on the acquisition decision read ONCE (a caller replacing `spec.a2a` during materialization can no longer unregister an acquired handle).
+- **Disclosed delta**: a dispose that hangs past its budget on the prepare-throw path now reports leg `"<disposer> (rollback leg N of M, prepare-throw)"` (e.g. `mcpDispose (rollback leg 2 of 3, prepare-throw)`) instead of `"mcp.dispose (prepare-throw leg)"` / `"a2a.dispose (prepare-throw leg)"` / `"ownedEnv.destroy (prepare-throw leg)"`. Error class and budget unchanged; no test or consumer referenced the old text.
+- Contract sentence `@contract prepare.deps-read-stable`: the host keeps `deps` / `internals` / `executionEnv` read-stable for the duration of `prepareTask`; an async phase returning a microtask later than the inlined code is within contract.
+- Roster mutation owner table: which phase pushes/splices which tool under which condition is written once on `Prepared.tools` (contracts.ts), not scattered in prose.
+- `isLiveApproverSeat` consumers (3) now read the one predicate in `tool-policy.ts`.
+
+### Fixed
+- #566 `CheckpointSummary.denialLimitFallback` is produced by `readDenialLimitFallback` (the same reader the park row and `AskRequest` use): exactly the four typed members when the row's value is well-formed, no key otherwise — a hand-edited or partial value is dropped, never echoed.
+- Wire-change generator: inherited keys are keys the type HAS — `readTreeModel` folds an interface's `extends` / intersection bases, so moving members onto a base interface no longer reports a false "lost keys" BREAKING item (the two false items in `wire-changes/core@7.5.0.json` are left as published and noted there).
+- `gate:message-branching` (the mcp.ts `transport.kind` fold's five sites are the ONE reader, exemption count corrected) and `gate:domain-lexicon` (UNC anchor test written with `isUncPath`) — two CI-only gates that had been red since the A-089 merge without the local chain running them.
+- Two load-sensitive pins (#583) measure by best-of-three / a generous spawn timeout instead of a single wall-clock reading.
+
+### Tooling / gates
+- `node scripts/gate-all.mjs [--with-dist] [--rc]` runs the whole `gate:*` roster in one command; a `gate:*` script without a roster seat fails `test/gate-all-roster.test.ts` (the release chain's L3 line now points here).
+- New gates: **G1** module line-count ratchet (`test/module-size-ratchet.test.ts`, banked per extraction), **G2** dependency-direction gate (`scripts/verify-layering.mjs` + `docs/LAYERING.json`, four layers: contracts ← prepare-path machinery ← phases ← orchestrator ← runtask; exemptions 13 → 3), **G5** phase-contract gate (`scripts/verify-phase-api.mjs`: every `prepare-*.ts` exports one Input/Result pair, every Input field classified; `KNOWN_INPUT_FIELDS` anti-blindness floor 371), `gate:agent-returns` (every archived car receipt's unresolved line carries a ticket / DEBTS id / DV / slice home).
+- Release criteria: `retiredIn` annotation lets a historic criteria file name a face that a later version removed without rewriting history (`criteria-lint` accepts an absent face carrying the annotation).
+- 16 runtime exports added in 7.5.0 registered in the consumer smoke probe; `test/prepare-lsp-ignore-filter.test.ts` pins the LSP tool's git-ignore wiring (a receiving-side mutation had left every LSP test green).
+
 ## 7.5.0 — 2026-09-05
 
 **BREAKING release** (the 7.4.1 bug batch merged into it — one publish, one pickup). 13 exports removed, 5 public types lose keys, one store contract replaced whole; every item is named below with its replacement. Nothing here is a wire FRAME change: `TaskEvent`, `PendingAction`, `CheckpointSummary`, `WiringManifest` only GAIN keys.

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

@@ -169,6 +169,15 @@ export interface DenialLimitFallback extends DenialLimitCounts {
  *  which is a break with nothing behind it (the routing invariant constrains where a window is WRITTEN,
  *  never who may read one). */
 export type DenialLimitFallbackFace = UnarmedDenialLimitFallback | DenialLimitFallback;
+/**
+ * A stored or foreign value read back AS a fallback member, or `undefined` when it is not one: exactly
+ * the four members, each of the right kind (finite non-negative counts, the closed `limit` word, a
+ * finite non-negative window), nothing else carried. A deployment-written row (a checkpoint store is a
+ * host's) can hold any shape; the faces that echo it (the inbox summary) read through here, so a bad
+ * shape reads as ABSENT rather than reaching a consumer as a malformed card. Not a parser of intent —
+ * `"3"` is not 3.
+ */
+export declare function readDenialLimitFallback(v: unknown): DenialLimitFallback | undefined;
 /** The window-less route's member, spelled in ONE place: every station that hands a fallback somewhere
  *  nothing can count down (a durable park row, a headless deny, a string `onAsk` seat, a member this
  *  run's tracker did not mint) passes through here rather than writing a `0` of its own. */

package/dist/core/auto-mode.js

@@ -99,6 +99,17 @@ class AutoModeTimeout extends Error {
         super("auto-mode classify timeout");
     }
 }
+export function readDenialLimitFallback(v) {
+    if (typeof v !== "object" || v === null)
+        return undefined;
+    const o = v;
+    const count = (x) => typeof x === "number" && Number.isFinite(x) && x >= 0;
+    if (!count(o["consecutive"]) || !count(o["total"]) || !count(o["autoDenyAfterMs"]))
+        return undefined;
+    if (o["limit"] !== "consecutive" && o["limit"] !== "total")
+        return undefined;
+    return { consecutive: o["consecutive"], total: o["total"], limit: o["limit"], autoDenyAfterMs: o["autoDenyAfterMs"] };
+}
 export function unarmedWindow(fallback) {
     return { ...countsOf(fallback), autoDenyAfterMs: 0 };
 }

package/dist/core/checkpoint-store.js

@@ -2,6 +2,7 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { uuidv7 } from "../internal/harness.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { carriesBidiControls } from "./tool-policy.js";
+import { readDenialLimitFallback } from "./auto-mode.js";
 import { isAskOrigin } from "./ask-origin.js";
 import { renderUntrustedCommandText, stripFormatCharacters } from "./permission-rule-model.js";
 import { redactSecrets } from "./untrusted-egress.js";
@@ -264,7 +265,10 @@ export function summarizeCheckpoint(cp) {
         ...(tool?.preview !== undefined ? { preview: tool.preview } : {}),
         ...(tool?.previewWithheld === "oversize" || tool?.previewWithheld === "unavailable" ? { previewWithheld: tool.previewWithheld } : {}),
         ...(tool?.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
-        ...(tool?.denialLimitFallback !== undefined ? { denialLimitFallback: { ...tool.denialLimitFallback } } : {}),
+        ...(() => {
+            const fb = readDenialLimitFallback(tool?.denialLimitFallback);
+            return fb !== undefined ? { denialLimitFallback: fb } : {};
+        })(),
         ...(tool !== undefined && isAskOrigin(tool.origin) ? { origin: tool.origin } : {}),
         ...(hasBidi ? { hasBidiControls: true } : {}),
     };

package/dist/core/protocol-table.d.ts

@@ -75,6 +75,11 @@ export declare const A2A_NAMESPACE: ProtocolNamespace<typeof A2A_PREFIX_NAME>;
 /** Every protocol namespace the engine knows. APPEND-ONLY: adding a protocol must not change how any
  *  existing name resolves — prefixes must stay pairwise non-overlapping (pinned in the table test). */
 export declare const PROTOCOL_TABLE: readonly ProtocolNamespace[];
+/** The namespaced-name shapes the protocol table currently owns, rendered for the two messages that have
+ *  to name them (the caller-name reservation and the policy audit's unprefixed-name arm). Read from the
+ *  table rather than written out: a message that hard-codes ONE protocol becomes wrong — while staying
+ *  green — the moment a second one is appended, and both messages tell a deployment what to write. */
+export declare const NAMESPACED_NAME_SHAPES: string;
 /** The namespace owning `name`, or `undefined` for a caller/first-party tool. */
 export declare function protocolOf(name: string): ProtocolNamespace | undefined;
 export {};

package/dist/core/protocol-table.js

@@ -37,6 +37,7 @@ const A2A_PREFIX_NAME = `a2a${NAME_SEP}`;
 export const MCP_NAMESPACE = makeProtocolNamespace("mcp", MCP_PREFIX_NAME);
 export const A2A_NAMESPACE = makeProtocolNamespace("a2a", A2A_PREFIX_NAME);
 export const PROTOCOL_TABLE = [MCP_NAMESPACE, A2A_NAMESPACE];
+export const NAMESPACED_NAME_SHAPES = PROTOCOL_TABLE.map((ns) => `${ns.prefix}<peer>__<tool>`).join(", ");
 export function protocolOf(name) {
     return PROTOCOL_TABLE.find((ns) => name.startsWith(ns.prefix));
 }

package/dist/core/runner/abort-race.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The abort-signal RACING vocabulary the park lane's synchronous-wait seats stand on — the per-call signal
+ * composition, the value-mapping race and the tagged three-state race — moved whole out of the orchestrator so
+ * the ask-lane phase (adjudicate / resolveAsk), the suspend-saga phase (the paused-VM compensation) and the
+ * park-ask phase (the content-ask delivery race, the projection re-adjudication, the fence) reach DOWN for the
+ * same three helpers instead of each carrying a copy. Pure: no engine state, no clock.
+ */
+/**
+ * design/384 slice 1 — the per-call signal composition all three synchronous-wait seats share
+ * (adjudicate / resolveAsk / resolveContentAsk): `AbortSignal.any([run, call])` when the gate
+ * threaded a per-call signal, the bare run signal otherwise (host-driven gates and unthreaded emits
+ * keep the historical binding byte for byte). The run signal is ALSO composed into the loop's turn
+ * controller, so the double source is a belt, not a dependency — this layer must not assume the
+ * loop's internal wiring. The composed product lives exactly as long as the one wait it bounds
+ * (both sources outlive it), so nothing here retains across calls.
+ */
+export declare function composeCallSignal(runSignal: AbortSignal, callSignal: AbortSignal | undefined): AbortSignal;
+/** design/384 slice 2 — how a raced await ended. The generalized sibling of the ask-side
+ *  `raceAskWaitAgainstSignal` (tool-policy.ts): same three-state form over any value domain.
+ *  `aborted` means the SIGNAL settled the race — the promise may still be pending and stays the
+ *  caller's to detach. `threw` reports the rejection AS a rejection, never folded into the abort
+ *  arm: the value-mapping `raceAbort` below resolves `onAbort()` for a rejection too, which at a
+ *  DECISION seat would disguise a real failure as a concession (and feed the concession value into
+ *  whatever door consumes the raced result) — a decision seat must race with THIS form. */
+export type RacedSettlement<T> = {
+    tag: "value";
+    value: T;
+} | {
+    tag: "threw";
+    error: unknown;
+} | {
+    tag: "aborted";
+};
+/** design/384 slice 2 — settle a raced await the moment `signal` aborts, WITHOUT waiting for the
+ *  promise to notice. Pre-aborted entry answers at once; the listener is removed on settle
+ *  whichever side wins (the `raceAbort` hygiene: `{once}` alone leaks a closure on the signal when
+ *  the promise settles first). The mapped promise attaches BOTH handlers up front, so an abort-arm
+ *  return never leaves an unhandled rejection behind. */
+export declare function raceSettlementAgainstSignal<T>(p: Promise<T>, signal: AbortSignal): Promise<RacedSettlement<T>>;
+/** Race a promise against an abort signal; on abort, resolve with `onAbort()`. Cleans up its listener. */
+export declare function raceAbort<T>(p: Promise<T>, signal: AbortSignal, onAbort: () => T): Promise<T>;

package/dist/core/runner/abort-race.js

@@ -0,0 +1,38 @@
+export function composeCallSignal(runSignal, callSignal) {
+    return callSignal !== undefined ? AbortSignal.any([runSignal, callSignal]) : runSignal;
+}
+export function raceSettlementAgainstSignal(p, signal) {
+    const settled = p.then((value) => ({ tag: "value", value }), (error) => ({ tag: "threw", error }));
+    if (signal.aborted)
+        return Promise.resolve({ tag: "aborted" });
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            signal.removeEventListener("abort", onAbortEvent);
+            resolve(r);
+        };
+        const onAbortEvent = () => finish({ tag: "aborted" });
+        signal.addEventListener("abort", onAbortEvent, { once: true });
+        void settled.then(finish);
+    });
+}
+export function raceAbort(p, signal, onAbort) {
+    if (signal.aborted)
+        return Promise.resolve(onAbort());
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbortEvent);
+            resolve(v);
+        };
+        const onAbortEvent = () => finish(onAbort());
+        signal.addEventListener("abort", onAbortEvent, { once: true });
+        p.then(finish, () => finish(onAbort()));
+    });
+}

package/dist/core/runner/checkpoint-scope.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The durable-suspend checkpoint ROW-IDENTITY vocabulary — the default isolation scope, the ONE derivation of a row's
+ * scope, and the ONE reading of the placement fields' empty string — moved whole out of the orchestrator so the
+ * wiring-manifest phase (the synthesized durableApproval), the park-lane phases (the mint sites and the suspend stamp),
+ * the driver (the restore fold) and runtask (the resume rung) reach DOWN for the same names. Pure: a constant and two
+ * string functions.
+ */
+/** design/77 §4.4: the multi-tenant scope used when a durable suspend fires for an IRREVERSIBLE tool in an
+ *  unattended deployment that did NOT opt into `durableApproval` (so there is no caller-supplied scope). The
+ *  checkpoint carries this scope; resume reads it back from the checkpoint (`cp.scope`), so it is
+ *  self-consistent without needing the original `TaskSpec`. Kept distinct from any tenant key to make an
+ *  unattended irreversible suspend auditable as such. */
+export declare const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
+/**
+ * design/153 §7.1 — the SINGLE derivation of a durable-suspend checkpoint's scope (both gate mint
+ * sites + the bg-watcher park lane's expire compensation/arbitration consume THIS; a re-derived copy
+ * that drifted was the exact bug the park tests caught — expire against the wrong scope silently
+ * no-ops). `|| DEFAULT` (not `??`): an EMPTY-string principal must not become a shared scope bucket.
+ *
+ * RB-75 (2026-07-25, red probe): that rule is stated twice in this file and was enforced on ONE of the two
+ * inputs — the principal half used `||`, the `durableApproval.scope` half used `??`, so an empty string
+ * arriving through the scope field (a config-centre / env lookup that came back blank is the realistic
+ * source) sailed through as the literal scope `""`. Two different tenants both landed in that one bucket,
+ * where `listByScope("")` reads BOTH their pending approvals — including each summary's `toolInput`
+ * preview of the raw arguments — and `reap("")` / `resolve(token, "")` act across both. `durableApproval.
+ * scope` is documented as "Multi-tenant isolation key … Required"; a blank string is the absence of an
+ * isolation key wearing its clothes, so both halves now fall through to the default isolation scope.
+ */
+export declare function checkpointScopeOf(spec: {
+    durableApproval?: {
+        scope?: string;
+    };
+    principal?: string;
+}): string;
+/**
+ * rescan C5 — the ONE spelling of the placement fields' empty-string discipline: `""` is absence
+ * wearing clothes (the resume entry's principal-rung posture), and every placement read that must
+ * treat it so — the resume rung's two sides (runtask), the restore fold's seed and the suspend
+ * stamp — goes through THIS helper, so three sites cannot drift into three readings. Deliberately
+ * NOT applied to the live `internals.placementRoot`/`rootSessionId` reads of the RESOLUTION fold:
+ * an empty supplied claim there is an assembly error the execution-env phase's `mintPlacementRootSessionId` refuses
+ * loudly on the factory path, and normalizing it away would silently repair what should be loud.
+ */
+export declare function placementValueOrAbsent(value: string | undefined): string | undefined;

package/dist/core/runner/checkpoint-scope.js

@@ -0,0 +1,7 @@
+export const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
+export function checkpointScopeOf(spec) {
+    return spec.durableApproval?.scope || spec.principal || DEFAULT_IRREVERSIBLE_SCOPE;
+}
+export function placementValueOrAbsent(value) {
+    return value || undefined;
+}

package/dist/core/runner/compaction-call-options.d.ts

@@ -3,7 +3,7 @@ import type { MaybeCompactOptions } from "../auto-compaction.js";
 import type { StaleToolResultOffloadOptions, TaskSpec } from "../types.js";
 import type { Context } from "../../internal/llm.js";
 import { type ToolResultStore } from "../tool-result-store.js";
-import type { Prepared } from "./prepare-task.js";
+import type { Prepared } from "./contracts.js";
 /**
  * REF-A2 (car R11) — the maybeCompact call arguments that MUST be assembled identically on all three
  * of runtask's compaction lanes (turn boundary / prompt-too-long recovery / end-of-task).

package/dist/core/runner/content-ask-bindings.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The content-ask BINDING vocabulary: the leak bound the routing lane checks against and the one entry shape the
+ * binding table holds. It lived in the question-face phase (which mints the table) while the routing lane was still
+ * orchestrator code; the lane is a phase now, and a phase reaching SIDEWAYS into a sibling for a constant and a type
+ * is the wrong reading — both phases reach DOWN for them here.
+ */
+import type { QuestionAnswer } from "../ask-question.js";
+export declare const CONTENT_ASK_BINDING_CAP = 32;
+/** One gate-routed content-ask outcome, keyed by the call id it was produced for (see the table's own note). */
+export type ContentAskBinding = ({
+    kind: "answered";
+    answer: QuestionAnswer;
+} | {
+    kind: "failed";
+    error: unknown;
+}) & {
+    /** Digest of the exact question batch this outcome belongs to. The call id alone is not enough
+     *  to redeem a binding: it comes from the model/provider and can repeat, so an entry that
+     *  outlived its call (its call was allowed but never executed) could otherwise be handed to a
+     *  LATER call that happens to reuse the id. Matching on the batch as well means an outcome can
+     *  only ever be delivered for the question it was produced for. */
+    questionsHash: string;
+    /** The engine-minted per-delivery identity (see AskQuestionRequest.deliveryId) — carried so a
+     *  stranded-answer disclosure names DELIVERIES, not call ids: call ids can repeat, and a
+     *  disclosure keyed on them would collapse two lost answers into one. */
+    deliveryId: string;
+};

package/dist/core/runner/content-ask-bindings.js

@@ -0,0 +1 @@
+export const CONTENT_ASK_BINDING_CAP = 32;