@sema-agent/core 7.48.0 → 7.49.1

package/dist/core/permission-rules.js

@@ -1,11 +1,10 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
-import { splitNamespacedName } from "./tool-name-aliases.js";
 import { catalogRuleFaceOf, isShellFaceToolName, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
 import { COMMAND_RULE_TOOL, NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, laneToolNamesOf, nameRuleAdmits, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleBasesNeeded, ruleToolGrammarOf } from "./permission-rule-model.js";
 import { pathFamilyOf } from "../tools/fs/safety.js";
 import { callTargetReadingOf, callTargetViewsOf } from "./effective-path-target.js";
-import { bindPathRules, pathRowsReach, policyAnchors, rowsWhereTheyLead } from "./path-rule-binding.js";
+import { bindPathRules, judgeRuleRows, policyAnchors, rowsWhereTheyLead } from "./path-rule-binding.js";
 import { ruleDenialSentence } from "./rule-denial-sentence.js";
 import { heldValues } from "./tool-name-readings.js";
 export { parsePermissionRule };
@@ -31,57 +30,8 @@ const DEFAULT_CAPS = {
     maxStars: 16,
     maxScalarValueChars: 16_384,
 };
-export function wildcardMatch(pattern, value) {
-    let p = 0;
-    let v = 0;
-    let star = -1;
-    let mark = 0;
-    while (v < value.length) {
-        if (p < pattern.length && pattern[p] === value[v] && pattern[p] !== "*") {
-            p++;
-            v++;
-        }
-        else if (p < pattern.length && pattern[p] === "*") {
-            star = p++;
-            mark = v;
-        }
-        else if (star >= 0) {
-            p = star + 1;
-            v = ++mark;
-        }
-        else {
-            return false;
-        }
-    }
-    while (p < pattern.length && pattern[p] === "*")
-        p++;
-    return p === pattern.length;
-}
-function parseNamespacedRuleName(name) {
-    const split = splitNamespacedName(name);
-    if (split === undefined || split.peer === "")
-        return undefined;
-    return split.tool !== undefined ? { protocol: split.ns.id, peer: split.peer, tool: split.tool } : { protocol: split.ns.id, peer: split.peer };
-}
-export function namespacedRuleNameCovers(ruleName, toolName) {
-    const rule = parseNamespacedRuleName(ruleName);
-    if (rule === undefined)
-        return false;
-    const target = parseNamespacedRuleName(toolName);
-    if (target === undefined)
-        return false;
-    if (rule.protocol !== target.protocol)
-        return false;
-    if (rule.peer !== target.peer)
-        return false;
-    if (rule.tool === undefined || rule.tool === "*")
-        return true;
-    return target.tool !== undefined && rule.tool.includes("*") && wildcardMatch(rule.tool, target.tool);
-}
-export function isNamespacedCoveringRuleName(name) {
-    const parsed = parseNamespacedRuleName(name);
-    return parsed !== undefined && (parsed.tool === undefined || parsed.tool.includes("*"));
-}
+import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, wildcardMatch } from "./namespaced-rule-name.js";
+export { isNamespacedCoveringRuleName, namespacedRuleNameCovers, wildcardMatch };
 export function catalogRuleFaceView(toolName) {
     const face = catalogRuleFaceOf(toolName);
     if (face === undefined)
@@ -395,7 +345,7 @@ export function createPermissionRulePolicy(rules, opts) {
             if (views !== undefined) {
                 const { of } = boundAt(policyAnchors(pathBases, req.pathRuleAnchors));
                 const rows = rowsWhereTheyLead(pathLane.map((r) => of.get(r)), callTargetReadingOf(req)?.leads ?? NO_LEADS);
-                const hit = pathRowsReach(rows, views, "tighten");
+                const hit = judgeRuleRows(rows, views, "tighten");
                 const rule = hit === undefined ? undefined : pathLane.find((r) => of.get(r).spec === hit.row.spec);
                 if (hit !== undefined && hit.unreadable === undefined)
                     return { rule: rule };

package/dist/core/read-root-candidate.d.ts

@@ -1,6 +1,4 @@
-/** The display bound on a grant candidate's directory: generous next to a real `PATH_MAX`, tight enough
- *  that the seat cannot become an unbounded prose channel onto an approval card. */
-export declare const READ_ROOT_CANDIDATE_DIR_MAX = 1024;
+export { READ_ROOT_CANDIDATE_DIR_MAX } from "./effective-path-target.js";
 /**
  * The validator for a probe's {@link import("./tool-spec.js").ReversibilityVerdict.readRootCandidate}: the
  * errand `normalizeProbeCause` does for the cause, fail-closed on the disclosure alone — a malformed value

package/dist/core/read-root-candidate.js

@@ -1,24 +1,13 @@
 import { isPlainRecord, safeDataValue } from "./checkpoint-store.js";
-import { hasWin32AliasedComponent, isAbsolutePathForm, normalizeAbsPathLexically, pathFamilyOf, win32NamespaceScreen } from "../tools/fs/safety.js";
-export const READ_ROOT_CANDIDATE_DIR_MAX = 1024;
+import { validatePath } from "./effective-path-target.js";
+export { READ_ROOT_CANDIDATE_DIR_MAX } from "./effective-path-target.js";
 export function normalizeReadRootCandidate(value) {
     if (!isPlainRecord(value))
         return undefined;
     if (safeDataValue(value, "clearsThisAsk") !== true)
         return undefined;
-    const dir = safeDataValue(value, "dir");
-    if (typeof dir !== "string" || dir.length === 0 || dir.length > READ_ROOT_CANDIDATE_DIR_MAX)
-        return undefined;
-    if (/[\u0000-\u001f\u007f\u2028\u2029]/.test(dir))
-        return undefined;
-    if (!isAbsolutePathForm(dir))
-        return undefined;
-    const folded = normalizeAbsPathLexically(dir);
-    if (folded !== dir || normalizeAbsPathLexically(`${dir}/..`) === dir)
-        return undefined;
-    if (hasWin32AliasedComponent(dir))
-        return undefined;
-    if (!win32NamespaceScreen(dir, pathFamilyOf({ root: dir })).ok)
+    const dir = validatePath(safeDataValue(value, "dir"), { intent: "validate-grant" });
+    if (dir === undefined)
         return undefined;
     let covers;
     try {

package/dist/core/real-approval.d.ts

@@ -8,14 +8,15 @@
 import type { Checkpoint } from "./checkpoint-store.js";
 import type { HostDecider } from "./gate-outcome.js";
 import type { OrgGateVerdict } from "./hooks.js";
-import type { AskRequest, PermissionResult, ResolvedAsk } from "./tool-policy.js";
+import type { AskRequest, PermissionResult, ResolverArmResult } from "./tool-policy.js";
 /** The synchronous seat's refusal of a configuration's allow: one settlement word for both forms
  *  (`blanket_allow_refused`, nobody's — no person decided), a sentence that says which configuration it was. */
-export declare function unjudgedAllowRefused(req: AskRequest, by: "blanket" | "policy"): Extract<ResolvedAsk, {
+export declare function unjudgedAllowRefused(req: AskRequest, by: "blanket" | "policy"): Extract<ResolverArmResult, {
     action: "deny";
 }>;
 /** A durable row demands a person when its gate carries the real-approval bit (the gate's own, which every resume
- *  check reads; the pending action's `requiresRealApproval` is its display twin). */
+ *  check reads; the pending action's `requiresRealApproval` is its display twin). A plan-pause gate carries no bit, so
+ *  the same predicate lets the deployment's policy decide a plan pause — and would refuse it the day a gate stamps one. */
 export declare function rowDemandsAPerson(cp: Checkpoint): boolean;
 /** A question a decide is held against, in each form a station holds one: the parked row, a policy's re-check of an
  *  approver's edit, the organization's CURRENT verdict about the call, and the request an approver was handed (the card a

package/dist/core/retired-keys.d.ts

@@ -25,3 +25,16 @@ export declare function assertNoRetiredKeys(bag: object, table: Readonly<Record<
  *  (`config.spec_retired_key`), never read as absence: a mode a caller believes it declared must not silently run
  *  as another. */
 export declare const RETIRED_TASK_SPEC_KEYS: Readonly<Record<string, string>>;
+/** The RETIRED `ToolPolicy` members — a policy still carrying one is refused by name (`config.deps_retired_key`) wherever
+ *  the engine reads a policy's members: the intake of the caller's policy (prepare, and a resume before its claim), the
+ *  by-name member reader the wrap and the path-rule installation share, and `combinePolicies`. A member the policy no
+ *  longer declares is dropped by every one of them, so a guard stated in it would read as stated while guarding nothing. */
+export declare const RETIRED_TOOL_POLICY_KEYS: Readonly<Record<string, string>>;
+/** The RETIRED `ShellReadBoundary` members — a boundary a consumer hands to `judgeShellRead` that still carries one is
+ *  refused by name (`config.deps_retired_key`); the station reads one write seat, so a retired one would leave every write
+ *  target unjudged by its rows. (The engine's own station builds its boundaries itself.) */
+export declare const RETIRED_SHELL_READ_BOUNDARY_KEYS: Readonly<Record<string, string>>;
+/** The `ToolPolicy` door ({@link RETIRED_TOOL_POLICY_KEYS}); `undefined` is no policy. */
+export declare function assertNoRetiredToolPolicyKeys(policy: object | undefined): void;
+/** The `ShellReadBoundary` door ({@link RETIRED_SHELL_READ_BOUNDARY_KEYS}). */
+export declare function assertNoRetiredShellReadBoundaryKeys(boundary: object): void;

package/dist/core/retired-keys.js

@@ -30,3 +30,17 @@ export const RETIRED_TASK_SPEC_KEYS = Object.freeze({
     "attachments.planModeReminder": "the read-only planning posture is stated whenever the leg's mode is `plan` (first turn, every 5 turns, and an exit frame when it ends) — drop the key",
     "skills[].manifest": "a skill's tools are its `allowedTools` / `disallowedTools` now — an allow-rule and a deny-rule source for the run the skill is activated in, never a fence; move `manifest.allowTools` to `allowedTools`. To fence tools write deny rules (or a delegated agent definition's `allowTools`); to fence write paths use session `allowDirs`",
 });
+export const RETIRED_TOOL_POLICY_KEYS = Object.freeze({
+    writeTargetGuard: "the guarded write targets are stated as rows now — `ToolPolicy.writeGuardRows`, an async provider of the one path table's `PathGuardRow`s the leg's ONE write judgment reads for every writer the policy cannot see as a call (the shell's file commands). A wrapper carries it through `wrapToolPolicy`, which reads every member a policy declares",
+});
+export const RETIRED_SHELL_READ_BOUNDARY_KEYS = Object.freeze({
+    writeProtectionJudge: 'the station asks ONE write judgment, `ShellReadBoundary.writeTargetJudge`, over the write-protection table and the deployment\'s guarded write rows together — it answers `"protected"`, `"guarded"` or `undefined`, not a boolean',
+    writeTargetGuard: 'the deployment\'s guarded write rows join the same one judgment, `ShellReadBoundary.writeTargetJudge` (`"guarded"` for a target a `ToolPolicy.writeGuardRows` row covers) — the boundary has no second write seat',
+});
+export function assertNoRetiredToolPolicyKeys(policy) {
+    if (policy !== undefined)
+        assertNoRetiredKeys(policy, RETIRED_TOOL_POLICY_KEYS, "ToolPolicy");
+}
+export function assertNoRetiredShellReadBoundaryKeys(boundary) {
+    assertNoRetiredKeys(boundary, RETIRED_SHELL_READ_BOUNDARY_KEYS, "ShellReadBoundary");
+}

package/dist/core/roles.d.ts

@@ -1,6 +1,6 @@
 import type { ThinkingLevel } from "../internal/harness-types.js";
 import type { Model } from "../internal/llm.js";
-import type { ModelRef, ModelRole, ModelRoles, RoleSpec } from "./types.js";
+import { type ModelRef, type ModelRole, type ModelRoles, type RoleSpec } from "./types.js";
 export type { ModelRole, RoleSpec, ModelRoles } from "./types.js";
 export { MODEL_ROLES } from "./types.js";
 /** Resolve a string ModelRef against the catalog (a Model object passes through). */
@@ -85,10 +85,9 @@ export declare function parseModelMention(text: string, allowedNames: Iterable<s
  * 各 role 未显式配置时自动落到语义档位——用户/壳只感知档位,roles 降级为内部路由层:
  * - `default` → `pro`(主力档兜底;用户/部署 roles.default / TaskSpec.model 恒可覆盖);
  * - `summarize` → `flash`(压缩本该便宜;flash 未绑沿降档链到 lite);
- * - `advisor` → 第一档(`ultra` 起,未绑降档到 max/pro——teacher 用最强的);
  * - `verifier` → `pro`;
  * - `classifier` → `flash`(design/143 批2b:auto-mode 权限分类腿是便宜档;flash 未绑沿降档链到 lite);
- * - `subagent`/`team`/`synthesize` 无档位默认 = 走 FALLBACK 继承主模型(LLM 可经 model 参数自选档);
+ * - `subagent` 无档位默认 = 走 FALLBACK 继承主模型(LLM 可经 model 参数自选档);
  * - `consolidate` 同样无档位默认,但它的 FALLBACK 刻意只有 `summarize` 一站(design/376,见
  *   {@link FALLBACK} 的注):未配即响亮拒,不静默骑主模型。
  * 未配 tiers 的部署:catalog 无 TIERS_ACTIVE 标记 → 表整体 INERT,行为与从前逐字节一致

package/dist/core/roles.js

@@ -1,4 +1,5 @@
 import { selectModel } from "./select-model.js";
+import { MODEL_ROLES } from "./types.js";
 export { MODEL_ROLES } from "./types.js";
 export function resolveModel(ref, models) {
     if (typeof ref !== "string") {
@@ -113,7 +114,6 @@ export function parseModelMention(text, allowedNames) {
 export const ROLE_TIER_DEFAULTS = {
     default: "pro",
     summarize: "flash",
-    advisor: DEFAULT_TIER_ORDER[0],
     verifier: "pro",
     classifier: "flash",
 };
@@ -127,9 +127,6 @@ const FALLBACK = {
     default: [],
     summarize: ["default"],
     subagent: ["default"],
-    team: ["default"],
-    synthesize: ["team", "default"],
-    advisor: ["default"],
     verifier: ["default"],
     classifier: ["summarize", "default"],
     consolidate: ["summarize"],
@@ -175,7 +172,19 @@ function mergeRoleSpec(base, over) {
         systemPrompt: o.systemPrompt ?? b.systemPrompt,
     };
 }
+function assertKnownRole(word, seat) {
+    if (typeof word === "string" && MODEL_ROLES.includes(word))
+        return;
+    const shown = typeof word === "string" ? JSON.stringify(word).slice(0, 80) : `<${word === null ? "null" : typeof word}>`;
+    const e = new Error(`${seat} names the model role ${shown}, which is not one of ${MODEL_ROLES.join(" / ")} — a word outside the vocabulary binds nothing and resolves nothing; bind the model on one of these roles, or name it on TaskSpec.model`);
+    e.code = "config.unknown_role";
+    throw e;
+}
 function mergeRoles(base, over) {
+    for (const key of Object.keys(base ?? {}))
+        assertKnownRole(key, "RunnerDeps.roles key");
+    for (const key of Object.keys(over ?? {}))
+        assertKnownRole(key, "TaskSpec.roles key");
     const out = { ...base };
     for (const role of Object.keys(over ?? {})) {
         out[role] = mergeRoleSpec(base?.[role], over?.[role]);
@@ -192,8 +201,9 @@ function partsModel(parts, models) {
     return undefined;
 }
 export function resolveTaskModel(spec, deps) {
+    const start = spec.modelRole ?? "default";
+    assertKnownRole(start, "modelRole");
     if (spec.model) {
-        const start = spec.modelRole ?? "default";
         const startParts = specParts(mergeRoles(deps.roles, spec.roles)[start]);
         return {
             model: resolveModel(spec.model, deps.models),
@@ -202,7 +212,6 @@ export function resolveTaskModel(spec, deps) {
             systemPrompt: startParts.systemPrompt,
         };
     }
-    const start = spec.modelRole ?? "default";
     const merged = mergeRoles(deps.roles, spec.roles);
     const startSystemPrompt = specParts(merged[start]).systemPrompt;
     for (const role of [start, ...FALLBACK[start]]) {

package/dist/core/runner/assemble-result.d.ts

@@ -214,13 +214,6 @@ export interface ResultFlags {
      *  somehow set — are gone with the commit-side routing that fed them. */
     paused?: PausedCause;
 }
-/**
- * Extract a machine-readable code from a thrown error (e.g. `SessionError.code`, a Node error code).
- * Walks the `cause` chain because the harness wraps lower-level errors (e.g. a `SessionError("conflict")`
- * append failure surfaces as an `AgentHarnessError("unknown")` whose cause is the real one) — so we
- * prefer the first specific code over a generic `"unknown"` wrapper.
- */
-export declare function errorCodeOf(err: unknown): string | undefined;
 /**
  * WHY the run ended — the ONE terminal arbitration ({@link TerminalCause}). First match wins, in the
  * slot order documented on {@link assembleResult} (a public contract: do not reorder). Every plane

package/dist/core/runner/assemble-result.js

@@ -1,5 +1,6 @@
 import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
 import { extractErrorCode, isProviderEchoShape, refusedTheRequest, stripErrorCodePrefix } from "../../brain/errors.js";
+import { completedTerminalOf, modelOutputInvalidOfMessage, providerVerdictOf, requestRouteOfMessage, thrownFailureOf } from "./terminal-account.js";
 import { terminalProjection } from "./terminal-projection.js";
 import { haltConsumed } from "./halt-attribution.js";
 import { providerReportedModel } from "../message-utils.js";
@@ -22,21 +23,6 @@ function thrownMessage(threw) {
     }
     return describeRejectedValue(threw);
 }
-export function errorCodeOf(err) {
-    let cur = err;
-    let fallback;
-    for (let depth = 0; cur !== null && cur !== undefined && typeof cur === "object" && depth < 8; depth++) {
-        const code = readMember(cur, "code");
-        if (typeof code === "string" && code) {
-            if (code !== "unknown") {
-                return code;
-            }
-            fallback ??= code;
-        }
-        cur = readMember(cur, "cause");
-    }
-    return fallback;
-}
 function stripThinkTags(text) {
     let t = text.replace(/<think>[\s\S]*?<\/think>/gi, "");
     const lower = t.toLowerCase();
@@ -95,15 +81,11 @@ export function terminalCauseOf(final, stats, flags) {
         terminal = { kind: "failed", code: "suspend.loop", message };
     }
     else if (flags.threw) {
-        const message = thrownMessage(flags.threw);
-        const code = flags.abortedForTimeout
-            ? "limits.max_walltime_exceeded"
-            : flags.abortedForTurns
-                ? "limits.max_turns_exceeded"
-                : flags.conflict
-                    ? "conflict"
-                    : errorCodeOf(flags.threw);
-        terminal = { kind: "failed", ...(code !== undefined ? { code } : {}), message };
+        const thrown = thrownFailureOf(flags.threw, thrownMessage(flags.threw));
+        const axisCode = flags.abortedForTimeout ? "limits.max_walltime_exceeded" : flags.abortedForTurns ? "limits.max_turns_exceeded" : flags.conflict ? "conflict" : undefined;
+        const code = axisCode ?? thrown.code;
+        const detail = axisCode === undefined ? thrown.detail : undefined;
+        terminal = { kind: "failed", ...(code !== undefined ? { code } : {}), message: thrown.message, ...(detail !== undefined ? { detail } : {}) };
     }
     else if (flags.blockedReason) {
         terminal = { kind: "blocked", reason: flags.blockedReason, ...(flags.blockedDetail !== undefined ? { detail: flags.blockedDetail } : {}) };
@@ -134,7 +116,7 @@ export function terminalCauseOf(final, stats, flags) {
                 ...(typeof apiRequestId === "string" && isProviderEchoShape(apiRequestId) ? { requestId: apiRequestId } : {}),
             };
         }
-        let providerNamed = true;
+        let messageNamed = true;
         const lifted = extractErrorCode(message);
         if (lifted) {
             code = lifted;
@@ -142,22 +124,28 @@ export function terminalCauseOf(final, stats, flags) {
         }
         else if (flags.gitCoreOverBudget) {
             code = "irreducible_core_over_budget";
-            providerNamed = false;
+            messageNamed = false;
         }
         else if (flags.conflict) {
             code = "conflict";
-            providerNamed = false;
+            messageNamed = false;
         }
         else {
             code = "provider.error";
         }
-        const detail = apiError && providerNamed && typeof apiStatus === "number" && refusedTheRequest(apiStatus)
-            ? { kind: "provider_rejected", status: apiStatus, ...(typeof apiCode === "string" && isProviderEchoShape(apiCode) ? { code: apiCode } : {}) }
-            : undefined;
+        const outputInvalid = apiError ? undefined : modelOutputInvalidOfMessage(final);
+        let detail;
+        if (messageNamed && apiError && typeof apiStatus === "number" && refusedTheRequest(apiStatus)) {
+            const route = requestRouteOfMessage(final);
+            detail = { kind: "provider_rejected", status: apiStatus, ...(typeof apiCode === "string" && isProviderEchoShape(apiCode) ? { code: apiCode } : {}), ...providerVerdictOf(final), ...(route !== undefined ? { route } : {}) };
+        }
+        else if (messageNamed && outputInvalid !== undefined) {
+            detail = { kind: "model_output_invalid", ...outputInvalid };
+        }
         terminal = { kind: "failed", code, message, ...(detail !== undefined ? { detail } : {}) };
     }
     else {
-        terminal = { kind: "completed" };
+        terminal = completedTerminalOf(final);
     }
     return { terminal, apiFailure };
 }

package/dist/core/runner/caller-roster.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The caller roster's ONE snapshot (#1167). A run's tool roster is the caller's `spec.tools` as it stands when prepare
+ * starts reading the request — before its first await — and nothing later, down to each entry's members: the driver
+ * rebinds onto a private copy of the spec whose `tools` is an own, fixed data property — a frozen array of frozen entry
+ * FACES, each member read once (an omitted roster stays omitted, a value that is no array stays as read), never the
+ * caller's accessor or an inherited one. The safety scan, the mount, the listings and every other phase read those faces,
+ * so no phase can read the caller's objects a second time after a caller microtask had the chance to change them —
+ * not the array (a push, a reassignment of `spec.tools`) and not an entry (a name, an effect or egress mark, a schema,
+ * the `execute` function swapped in place, a getter or a Proxy answering differently on a later read).
+ *
+ * The snapshot holds no live entry. Every object entry (a function included) becomes a face: its own enumerable members
+ * (string and symbol keys — what the mount's spread carries) plus every ToolSpec member name read through an ordinary
+ * property read (how the phases read a declaration — non-enumerable, inherited or Proxy-answered included), each read once;
+ * every declaration value is deep-copied and frozen by the one copier. A primitive is immutable and stays as read. A
+ * read that throws refuses the run at the snapshot. Whether the ToolSpec arm can build the entry ({@link specArmCanConstruct})
+ * is asked of the entry once, there, and recorded on its face ({@link specArmCanBuild}); the mount refuses an entry it
+ * cannot build from that record, so an `execute` that grows on the caller's object later is never read. The mount calls a
+ * spec face's `execute` with the caller's own object as `this` ({@link callerEntryOrigin}). A `defineTool` product's face is
+ * what every phase reads in its place, and the mount keeps the one authenticated rebind of the product object itself
+ * ({@link rebindProductEntry}; the factory's seal refuses a product whose `execute` was replaced or which is not the object
+ * it stamped): the factory rebuilds the product from its own members at the mount, and the run is refused when the rebuilt
+ * product no longer answers as its face did. The tool a product mounts as is built from that face around the rebound
+ * `execute`, never the rebuilt object itself (it shares list members and accessors with the caller's product): the
+ * brand is asked once, here at the snapshot, and no object the caller can reach is ever a mounted tool.
+ *
+ * An array the caller changes after that instant is refused instead of run without the change:
+ * {@link refuseLateRosterChanges}, called once at the end of prepare, re-reads the caller's `spec.tools` and refuses
+ * the run with the declaration door's code (`config.tool_mount_denied`) naming every entry that is not, in order, the
+ * object the snapshot read (a getter that hands back a fresh array of the same objects is not a change). A change to an
+ * entry's members is not compared — the run never reads them again. A change after prepare returned is read by nothing.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { TaskSpec } from "../types.js";
+import type { ToolSpec } from "../tool-spec.js";
+import { type ToolCtxEnricher } from "../tools.js";
+declare const ROSTER_FACE: unique symbol;
+/** A roster entry as the snapshot minted it. The brand is private to this module and {@link rosterFaceOf} is the only
+ *  function that returns one, so a phase that takes `RosterFace`s cannot be handed a live caller object: code that tries
+ *  to put one into the roster does not compile. */
+export type RosterFace = ToolSpec & {
+    readonly [ROSTER_FACE]: true;
+};
+/** A task spec whose tool roster is faces — what the driver and every phase that reads the roster hold after the snapshot. */
+export type RosterSpec = Omit<TaskSpec, "tools"> & {
+    tools?: RosterFace[];
+};
+/** What the refusal compares: the caller's own spec (re-read, never mutated here) and the objects the snapshot read
+ *  (`undefined` when the roster was not an array — an omitted roster snapshots as no entries, a non-array value is the
+ *  doors' to judge and is not compared). */
+export interface CallerRosterSnapshot {
+    readonly caller: TaskSpec;
+    readonly handed: readonly unknown[] | undefined;
+}
+/** The object a snapshot face was read from (the entry itself when it was held as handed). */
+export declare function callerEntryOrigin(entry: object): object;
+/** Can the mount's ToolSpec arm build this roster entry? Only the verdict recorded at the snapshot answers: an object that
+ *  is no face of this snapshot, a primitive, a product's face, is not built from. */
+export declare function specArmCanBuild(entry: RosterFace): boolean;
+/** One entry of the roster, and the ONLY place a {@link RosterFace} is minted. Every object entry (a function included) becomes a frozen face, so no entry the snapshot holds is a
+ *  live object: a primitive is immutable and stays as read; a `defineTool` product's face names the product for its sealed
+ *  rebind; an entry the ToolSpec arm cannot build gets a face too, and the mount refuses it from the verdict recorded here —
+ *  an `execute` or a mark that grows on the caller's object afterwards is never read. A read that throws refuses the run. */
+export declare function rosterFaceOf(t: unknown, index: number): RosterFace;
+/** The mount's arm for a roster entry that is the face of a `defineTool` product: the exact product object is rebound to
+ *  the run's ctx through the factory's sealed seat, compared with its face ({@link refuseProductDrift}), and the tool the
+ *  run mounts is built from the face around the rebound `execute` ({@link mountedProduct}). `undefined` when the entry is
+ *  not a product's face (the mount's ToolSpec arm takes it). */
+export declare function rebindProductEntry(entry: object, enrich: ToolCtxEnricher): AgentTool | undefined;
+/** Take the snapshot and rebind onto a private spec copy carrying it. The copy keeps the caller's prototype and every own
+ *  property descriptor (an inherited or non-enumerable request field reads exactly as it did on the caller's spec); only
+ *  `tools` becomes the copy's own frozen array of faces when the request carried one. */
+export declare function snapshotCallerRoster(spec: TaskSpec): {
+    spec: RosterSpec;
+    roster: CallerRosterSnapshot;
+};
+/** Refuse the run when the caller's `spec.tools` no longer holds exactly the objects the snapshot read, in order. */
+export declare function refuseLateRosterChanges(roster: CallerRosterSnapshot): void;
+export {};