@sema-agent/core 7.56.0 → 7.57.0

package/dist/core/store-contracts/background-agent-store-contract.js

@@ -9,6 +9,7 @@ function record(over = {}) {
         owner: "task-1",
         sessionScoped: false,
         parentSessionId: "sess-1",
+        name: "contract-agent",
         writerId: "writer-1",
         spawnedAt: 1_000,
         updatedAt: 1_000,

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

@@ -308,7 +308,7 @@ export async function checkpointStoreContract(make, runAssertion, options = {})
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
-    run("the approval object's members: a row's identity + face group and its targets (capabilityId/contractId/shapeDigest/implementationRevision + family/pathTarget/hostTarget/names + targets + engineMounted) survive the round-trip verbatim; an absent group stays absent", async () => {
+    run("the approval object's members: a row's identity + face group and its targets (capabilityId/contractId/shapeDigest/implementationRevision + family/pathTarget/hostTarget/names + targets + targetReads + engineMounted) survive the round-trip verbatim; an absent group stays absent", async () => {
         const store = make();
         const carried = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-carried" });
         const group = {
@@ -320,6 +320,7 @@ export async function checkpointStoreContract(make, runAssertion, options = {})
             pathTarget: { param: "destination", aliases: ["path"], access: "create", skillScopeEligible: true },
             names: ["AcmeWrite", "acme_write"],
             targets: { protective: "/srv/work/out.txt", declared: "/srv/work/out.txt" },
+            targetReads: { ["0123456789abcdef".repeat(4)]: "fedcba9876543210".repeat(4) },
             engineMounted: true,
         };
         Object.assign(carried.pendingAction, group);

package/dist/core/store-contracts/file-history-store-contract.js

@@ -473,9 +473,18 @@ export async function fileHistoryStoreContract(make, runAssertion) {
                 throw Object.assign(new Error("source blob unreadable"), { code: "EACCES" });
             });
             assert.equal(thrown.ok, false);
+            if (!thrown.ok)
+                assert.equal(thrown.error.code, "adopt_failed", "a source whose read throws cannot supply a referenced blob");
             if (!thrown.ok)
                 assertPermanenceWord(thrown.error, "importHistory whose source fetch threw");
             assert.equal(await store.canRestore("sc", "b2"), false);
+            const wrongBytes = await store.importHistory("sc", missingBlob, async () => new TextEncoder().encode("bytes that are not the content this address names"));
+            assert.equal(wrongBytes.ok, false);
+            if (!wrongBytes.ok)
+                assert.equal(wrongBytes.error.code, "adopt_failed", "a source whose bytes fail their content address cannot supply a referenced blob");
+            if (!wrongBytes.ok)
+                assertPermanenceWord(wrongBytes.error, "importHistory whose source served the wrong bytes");
+            assert.equal(await store.canRestore("sc", "b2"), false);
             const duplicated = wireEnvelope({
                 formatVersion: "file-history/1",
                 tracked: [

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

@@ -1,5 +1,5 @@
 import { strict as assert } from "node:assert";
-import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
+import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_INVALID_DECISION_MOVE_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
 import { beginContract } from "./contract-harness.js";
 import { PRINCIPAL_INBOX_HANDLE } from "../../agents/cross-session-ref.js";
 import { mintCrossPrincipalRecord } from "../../agents/org-delivery-gate.js";
@@ -183,6 +183,54 @@ export async function mailboxStoreContract(mk, runAssertion) {
         const again = await s.claimLease(S, "a1", "w2", 1_000, 20_000);
         assert.deepEqual(again.messages[0].peerMeta, { fromMode: "bypass", fromSession: "sess_1" }, "重投的记录必须是原样");
     });
+    run("#972b hold decision:CAS 一胜一负、负者拿到真值;不受租约围栏;每个租约快照都带它", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        await s.append(S, "a1", msg("m2"));
+        const held = await s.claimLease(S, "a1", "holder", 60_000, 10_000);
+        assert.equal(held.messages[0].decision, undefined, "从未 held 的记录没有 decision");
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, undefined, "held"), { ok: true });
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, undefined, "held"), { ok: false, current: "held" }, "同一步再走一次:负者拿到当前值");
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, "held", "denied"), { ok: true }, "不持租约的一方也能落人的决定");
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, "held", "approved"), { ok: false, current: "denied" }, "后到的答复输给先到的决定");
+        assert.deepEqual(await s.moveDecision(S, "a1", 2, "held", "approved"), { ok: false, current: "unset" }, "未 held 的记录答 unset");
+        const snap = await s.claimLease(S, "a1", "holder", 60_000, 11_000);
+        assert.deepEqual(snap.messages.map((m) => [m.seq, m.decision]), [[1, "denied"], [2, undefined]], "租约快照带每条记录的 decision");
+        await s.ack(S, "a1", "holder", 1);
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, "denied", "denied").catch((e) => e.code), MAILBOX_INVALID_DECISION_MOVE_CODE, "终局不再移动(先于存在性判)");
+        assert.deepEqual(await s.moveDecision(S, "a1", 1, "held", "approved"), { ok: false, current: "gone" }, "ack 掉的记录答 gone");
+    });
+    run("#972b decision 律:只向前走,终局不动;坏词 / 坏 seq / 非法边先于任何副作用被拒(带码)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("m1"));
+        const codeOf = async (p) => {
+            try {
+                await p;
+                return undefined;
+            }
+            catch (e) {
+                return e.code;
+            }
+        };
+        for (const [label, seq, expect, next] of [
+            ["unset → approved", 1, undefined, "approved"],
+            ["unset → delivered", 1, undefined, "delivered"],
+            ["held → held", 1, "held", "held"],
+            ["held → dropped", 1, "held", "dropped"],
+            ["delivered → denied", 1, "delivered", "denied"],
+            ["denied → approved", 1, "denied", "approved"],
+            ["unknown word", 1, undefined, "consumed"],
+            ["seq 0", 0, undefined, "held"],
+            ["seq 1.5", 1.5, undefined, "held"],
+        ]) {
+            assert.equal(await codeOf(s.moveDecision(S, "a1", seq, expect, next)), MAILBOX_INVALID_DECISION_MOVE_CODE, label);
+        }
+        const snap = await s.claimLease(S, "a1", "w", 60_000, 10_000);
+        assert.equal(snap.messages[0].decision, undefined, "被拒的调用零副作用");
+        for (const [from, to] of [[undefined, "held"], ["held", "approved"], ["approved", "delivered"], ["delivered", "dropped"]]) {
+            assert.deepEqual(await s.moveDecision(S, "a1", 1, from, to), { ok: true }, `${String(from)} → ${to}`);
+        }
+    });
     await settle();
 }
 export async function mailboxAckOwnershipContract(mk, runAssertion) {

package/dist/core/task-registry-agent.d.ts

@@ -443,19 +443,23 @@ export declare function deliverToRunningAgentLane(core: DurableAgentCore, id: st
  *  counterpart rows here). This variant is the SENDMESSAGE footer's source and lists EVERY running
  *  agent, named or not: SendMessage addresses by name AND by id, so dropping named rows here (the way
  *  {@link runningAgentFooterLane} does for the task faces, per CC `rxo`'s `!n.has(i.id)`) would hide the
- *  very rows a retry needs. The task faces' split lives in `runningAgentFooterLane` (RB-332). */
+ *  very rows a retry needs. The label is the name someone chose, else the description: the name an agent
+ *  carries only because it must carry one ({@link chosenAgentName}) says nothing about what it does.
+ *  The task faces' split lives in `runningAgentFooterLane` (RB-332). */
 export declare function runningBackgroundAgentLabelsLane(core: DurableAgentCore, access: TaskAccess): string[];
 /**
  * The not-found FOOTER's two rows, split the way the reference assembles them:
  *  - `named`  = CC `uG_` (220:467941-467953): the agentNameRegistry's KEYS whose task is a running local
  *               agent, listed as BARE NAMES — the string a retry should pass verbatim. sema's counterpart
- *               of "has a registry entry" is the handle carrying an explicit `name` (spawn-time label),
- *               the same field TaskStop's name leg and SendMessage address by.
+ *               of "has a registry entry" is the handle carrying a CHOSEN name (the spawn-time label; the
+ *               name an agent carries only because every agent has one is not a registry entry —
+ *               {@link chosenAgentName}).
  *  - `background` = CC `rxo` (220:467937-467951): the remaining running background agents as `id (label)`
  *               rows. CC filters `!n.has(i.id)` — a NAMED agent is deliberately NOT repeated here, because
  *               its addressable form is the name, not the id. The pre-RB-332 sema code merged both legs
  *               into one list and justified it with "named has no counterpart", a claim [c209-D] retired
- *               when the explicit `name` field landed.
+ *               when the explicit `name` field landed. The id stays in these rows because TaskOutput
+ *               resolves exact ids only: an agent nobody named is the one a retry can reach by its id alone.
  * CC's `YEd` "Running teammates:" leg has no sema counterpart (no teammate registry on this face) and is
  * honestly absent rather than faked.
  */

package/dist/core/task-registry-agent.js

@@ -5,7 +5,7 @@ import { canAccessAgentRecord, BackgroundAgentStoreError, clearRevivedRowTermina
 import { shutdownDebug } from "./shutdown-debug.js";
 import { delimitUntrusted } from "./untrusted-text.js";
 import { boundedRedactedSummary } from "./untrusted-egress.js";
-import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
+import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, engineAgentName, chosenAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
 import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
 import { thrownLabel } from "./thrown-value.js";
 import { agentStateSourceOfHandle, agentStateSummary, readAgentState } from "./agent-state.js";
@@ -367,6 +367,10 @@ export function registerBackgroundAgentLane(core, input) {
     if (core.handles.has(id))
         throw new Error(`TaskRegistry: task id already registered: ${id}`);
     const now = input.now ?? Date.now();
+    if (input.name !== undefined && (typeof input.name !== "string" || input.name === "")) {
+        throw new Error(`TaskRegistry: background-agent name must be a non-empty string (got ${JSON.stringify(input.name)}); omit it to take the derived one`);
+    }
+    const name = input.name ?? engineAgentName(id);
     core.handles.set(id, {
         id,
         type: "background_agent",
@@ -375,7 +379,7 @@ export function registerBackgroundAgentLane(core, input) {
         ...(input.resolveParkedStop !== undefined ? { resolveParkedStop: input.resolveParkedStop } : {}),
         ...(input.sessionScoped ? { sessionScoped: true } : {}),
         ...(input.description !== undefined ? { description: input.description } : {}),
-        ...(input.name !== undefined ? { name: input.name } : {}),
+        name,
         ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
         ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
         ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
@@ -396,6 +400,7 @@ export function registerBackgroundAgentLane(core, input) {
         if (input.durableSeed !== undefined) {
             const seeded = structuredClone(input.durableSeed.record);
             seeded.rev = input.durableSeed.rev;
+            seeded.name = name;
             handle.durable = {
                 store: input.store,
                 record: seeded,
@@ -417,7 +422,7 @@ export function registerBackgroundAgentLane(core, input) {
                 ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
                 ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
                 ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
-                ...(input.name !== undefined ? { name: input.name } : {}),
+                name,
                 ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
                 ...(input.description !== undefined ? { description: input.description } : {}),
                 ...(input.model !== undefined ? { model: input.model } : {}),
@@ -892,7 +897,7 @@ export function resolveBackgroundAgentByNameLane(core, name, access, opts) {
     };
     const named = [];
     for (const h of core.handles.values()) {
-        if (h.type !== "background_agent" || h.name === undefined || !canAccess(h, access))
+        if (h.type !== "background_agent" || !canAccess(h, access))
             continue;
         if (h.name === name || normalizeAgentName(h.name) === key)
             named.push(h);
@@ -902,7 +907,7 @@ export function resolveBackgroundAgentByNameLane(core, name, access, opts) {
         if (namedRunning.length > 1) {
             return {
                 status: "ambiguous",
-                message: `Multiple RUNNING background agents match "${name}": ${namedRunning.map((h) => `${h.id} (${h.name ?? h.description ?? "unnamed"})`).join(", ")}. Use the task ID.`,
+                message: `Multiple RUNNING background agents match "${name}": ${namedRunning.map((h) => `${h.id} (${h.name})`).join(", ")}. Use the task ID.`,
             };
         }
         if (namedRunning.length === 1)
@@ -1256,7 +1261,7 @@ export function runningBackgroundAgentLabelsLane(core, access) {
     for (const h of core.handles.values()) {
         if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
             continue;
-        const label = h.name ?? h.description;
+        const label = chosenAgentName(h.id, h.name) ?? h.description;
         out.push(label ? `${h.id} (${label})` : h.id);
     }
     return out;
@@ -1267,8 +1272,9 @@ export function runningAgentFooterLane(core, access) {
     for (const h of core.handles.values()) {
         if (h.type !== "background_agent" || h.status !== "running" || !canAccess(h, access))
             continue;
-        if (h.name !== undefined && h.name !== "") {
-            named.push(h.name);
+        const chosen = chosenAgentName(h.id, h.name);
+        if (chosen !== undefined) {
+            named.push(chosen);
             continue;
         }
         background.push(h.description ? `${h.id} (${h.description})` : h.id);

package/dist/core/task-registry-shared.d.ts

@@ -321,11 +321,12 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
             reason: "not_found" | "not_running" | "no_channel";
         }) => void) | undefined)?
     ]>;
-    /** [c209-D] the EXPLICIT addressing name (CC Agent.name parity, validated at spawn: charset regex +
-     *  "main" reserved). Distinct from `description` (the display/legacy-matching label): the name layer
-     *  resolves latest-wins ("a newer agent took the name"), the description layers keep their
-     *  running-preferred + ambiguous posture. Absent on pre-[c209] rows and unnamed spawns. */
-    name?: string;
+    /** The addressing name: the spawner's explicit one (CC Agent.name parity, validated at spawn: charset
+     *  regex + reserved set), or — when the spawn named none — the one {@link engineAgentName} derives from
+     *  the handle, written by the registration itself, so every background agent has exactly one. Distinct
+     *  from `description` (the display/legacy-matching label): the name layer resolves latest-wins ("a newer
+     *  agent took the name"), the description layers keep their running-preferred + ambiguous posture. */
+    name: string;
     /** design/129: this child OUTLIVES its parent turn — owner is the SESSION id; the parent-teardown reap
      *  skips it; `reapSessionBackground` is its terminal anchor. Explicit flag, never inferred from key values
      *  (hostTaskId===sessionId deployments would otherwise be ambiguous). */
@@ -836,6 +837,32 @@ export declare const DURABLE_AGENT_HEARTBEAT_MS = 60000;
  *  durable arm (a bare exact-key miss lets padded/legacy/name-shaped ids leak into live branches —
  *  the server 1.250 HIGH) — one shared regex kills the drift, roster-normalize precedent. */
 export declare const DURABLE_AGENT_HANDLE_RE: RegExp;
+/**
+ * The name a background agent carries when its spawner named none: `agent-` + the first twelve hex
+ * digits of its handle (`a3fa9c2d1b7e04a15` → `agent-3fa9c2d1b7e0`; a handle with fewer digits keeps
+ * them all). A pure function of the handle, so the same agent id reads the same name in every process
+ * and every store — a host that finds a row from an earlier version without a name derives it here, it
+ * does not invent one.
+ *
+ * Shorter than the id's sixteen digits on purpose: a name of the SHAPE of an agent id (`a`, an optional
+ * `<label>-`, sixteen hex) already addresses an agent directly and is refused as a name everywhere
+ * (`reservedPeerNameReason`), so a minted name is an ordinary admissible name — nothing in the name
+ * grammar singles it out. Twelve digits (48 bits) because the name layer resolves a name to the NEWEST
+ * agent that holds it: two agents of one caller would have to share twelve digits of their ids to collide.
+ *
+ * The registry's registration is the one place this is called (see `registerBackgroundAgentLane`); every
+ * reader that needs to know whether SOMEONE chose a name goes through {@link chosenAgentName}.
+ */
+export declare function engineAgentName(handle: string): string;
+/**
+ * The name SOMEONE chose for an agent — `undefined` when the agent's name is the one {@link engineAgentName}
+ * derives from its handle (or there is none). Every agent has a name to be addressed by; only a chosen one is
+ * also a spawn identity (the teammate key, `spawnName` on frames, a roster entry, the unnamed-child tool pool),
+ * and a reader that hands a row's name back into a place that reads it as an identity — a revival's `name`
+ * argument, a retained resume's row name — goes through here, so an agent nobody named stays unnamed in every
+ * later cycle. A reader that only needs to ADDRESS the agent reads `name` as it is.
+ */
+export declare function chosenAgentName(handle: string, name: string | undefined): string | undefined;
 /** Synthetic settle error the subagent reap path passes after a stop/parent teardown. It is NOT a
  *  real child error — settleBackgroundAgent never stores it (status "killed" + stoppedBy already say
  *  it); exported so the subagent call sites and the registry agree on the exact sentinel. */
@@ -937,7 +964,9 @@ export interface RegisterBackgroundAgentInput extends TaskAccess {
     description?: string;
     /** [c209-D] explicit addressing name (CC Agent.name parity) — the CALLER validates it (charset +
      *  reserved "main") before registration; the registry stores it verbatim. Duplicate names are legal
-     *  (latest-wins at resolution; older rows stay task_id-addressable). */
+     *  (latest-wins at resolution; older rows stay task_id-addressable). ABSENT = the spawner named none:
+     *  the registration gives the agent the name {@link engineAgentName} derives from its handle (this is
+     *  the only place a name is minted), on the live handle and the durable row alike. */
     name?: string;
     /** the RESOLVED subagent type ("general-purpose"/"fork"/a roster name), persisted
      *  so a REVIVE cycle's observer frames can reproduce the row's TYPE column (never the description). */

package/dist/core/task-registry-shared.js

@@ -279,6 +279,17 @@ export function formatWorkflowRun(run) {
 }
 export const DURABLE_AGENT_HEARTBEAT_MS = 60_000;
 export const DURABLE_AGENT_HANDLE_RE = /^a[0-9a-f]{6,32}$/;
+export function engineAgentName(handle) {
+    if (!DURABLE_AGENT_HANDLE_RE.test(handle)) {
+        throw new TypeError(`engineAgentName: ${JSON.stringify(handle)} is not an agent handle (expected "a" followed by 6-32 hex digits)`);
+    }
+    return `agent-${handle.slice(1, 13)}`;
+}
+export function chosenAgentName(handle, name) {
+    if (name === undefined)
+        return undefined;
+    return DURABLE_AGENT_HANDLE_RE.test(handle) && name === engineAgentName(handle) ? undefined : name;
+}
 export const BG_AGENT_REAP_STOP_ERROR = "stopped (parent task ended or TaskStop)";
 export function normalizeAgentName(s) {
     return s

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

@@ -7,7 +7,7 @@ import { type BackgroundAgentStore } from "./background-agent-store.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
 import type { ToolResultStore } from "./tool-result-store.js";
 import { type SemaTaskType, type StopSource, type SemaTaskStatus, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type SemaTaskHandle, type TaskAccess, type BackgroundAgentTaskHandle, type MonitorTimers, type RegisterMonitorInput, type RegisterWorkflowInput, canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE } from "./task-registry-shared.js";
-export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
+export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, engineAgentName, chosenAgentName } from "./task-registry-shared.js";
 export type { ParkedClaimTicket, RegisterBackgroundAgentInput } from "./task-registry-shared.js";
 import type { RegisterBackgroundAgentInput, ParkedClaimTicket } from "./task-registry-shared.js";
 import { type AgentStateSource } from "./agent-state.js";

package/dist/core/task-registry.js

@@ -9,7 +9,7 @@ import { stripCwdSentinel } from "../tools/fs/fs-shared.js";
 import { registerMonitorLane, pollMonitorLane, stopMonitorLane } from "./task-registry-monitor.js";
 import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task-registry-workflow.js";
 import { mintCompletionId, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, stdoutHeadingOf, REPLAY_FACE, SPOOL_REPLAY, INCREMENT_REPLAY, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
-export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
+export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, engineAgentName, chosenAgentName } from "./task-registry-shared.js";
 import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESSAGE, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, resolveTaskIdArg, REGISTRY_TASK_TOOL_CAPS, composeTaskOutputDescription, composeTaskOutputParams, composeTaskStopDescription, } from "./task-tool-shape.js";
 import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
 import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";

package/dist/core/tool-catalog-entries.d.ts

@@ -71,6 +71,12 @@ export declare const isEngineShellFace: (face: {
     readonly engineMounted?: true;
     readonly contractId: string;
 } | undefined) => boolean;
+/** Is this call's face one of the content-routing tools the engine mounts (question, answer, blocked report)? They route content,
+ *  act on nothing, and no stored rule governs them: the persisted-rule lane does not judge them and their card offers no rule. */
+export declare const routesContent: (face: {
+    readonly engineMounted?: true;
+    readonly contractId: string;
+} | undefined) => boolean;
 /**
  * The rule face a definition whose schema is BUILT PER MOUNT puts on its instance: its row's primaries only (none ⇒ no rule
  * face). The row's `params` is the static view's vocabulary, the fullest mount's; a mount's own is read off the schema it

package/dist/core/tool-catalog-entries.js

@@ -207,6 +207,7 @@ export function engineMountedAs(ids) {
     return (face) => face?.engineMounted === true && contracts.has(face.contractId);
 }
 export const isEngineShellFace = engineMountedAs(["bash", "bash-readonly"]);
+export const routesContent = engineMountedAs(["ask-user-question", "structured-output", "report-blocked"]);
 export function mountRuleFace(id) {
     const primaryParams = toolFace(id).ruleFace?.primaryParams;
     return primaryParams === undefined ? undefined : { primaryParams: [...primaryParams] };

package/dist/core/tool-name-aliases.d.ts

@@ -16,8 +16,8 @@ import type { RuleBehavior } from "./permission-rule-model.js";
  *    with the successor, where any other unknown name stays the generic roster miss.
  *
  * What REMAINS is validation data: {@link RETIRED_TOOL_NAMES} maps every name the engine ever
- * retired to a one-line guidance string, and {@link judgeRuleToolName} is the ONE reading of it a rule's
- * tool name gets. They exist because deleting the mapping flips stale POLICY entries from "silently
+ * retired to a one-line guidance string, and {@link judgeRuleToolName} is the ONE judgment of it a rule's
+ * tool name gets ({@link toolNameFaultOf} adds the near-miss step: the one reading). They exist because deleting the mapping flips stale POLICY entries from "silently
  * matched" to "silently matches nothing" — and for a deny/requireApproval entry that direction WIDENS
  * the surface. `validatePermissionRules` (permission-rules.ts) does NOT classify retired names itself:
  * which names a deployment mounts its OWN tool under is a roster fact, and the judgment takes the roster.
@@ -100,6 +100,36 @@ export declare function grantWildcardRefusalOf(name: string): string | undefined
  *  as a glob ({@link readsNameGlob}) — such a name outside every namespace, or with a glob in its peer segment, is a pattern and
  *  `current`; with `allow` or none a wildcard peer names no peer and is `unmintable_segment`. */
 export declare function judgeRuleToolName(name: string, roster: ReadonlySet<string>, behavior?: RuleBehavior): RuleToolNameVerdict;
+/**
+ * THE near-miss reading of a tool name the judgment calls current: the spelling the roster carries when it carries no tool of this
+ * exact name but one that differs from it only by case (`BASH` beside `Bash`), else `undefined`. Two kinds of name are never a near
+ * miss, because the roster they would be read against is not the final one: an engine tool's (the engine mounts some of its tools
+ * after a list is read) and a protocol tool's (a refresh mounts and unmounts them while the run goes on) — in both the exact
+ * spelling can be the right one by the time it matters. Every station that asks "is this name a case twin of a carried tool" reads
+ * this answer: an entry list and the persisted grammar's whole-tool rule through {@link toolNameFaultOf}, and a tool policy's name
+ * lists (the prepare-time policy-name audit, which reads two rosters and skips an inherited layer) directly.
+ */
+export declare function nearMissSpellingOf(name: string, roster: ReadonlySet<string>): string | undefined;
+/** What {@link toolNameFaultOf} finds wrong with a rule's tool name: the judgment's stale words (`tool_name`, with the verdict and
+ *  its facts), or another spelling of a carried tool (`near_miss`, the spelling to write). */
+export type ToolNameFault = {
+    readonly reason: "tool_name";
+    readonly verdict: Exclude<RuleToolNameVerdict["kind"], "current">;
+    readonly guidance?: string;
+    readonly currentName?: string;
+} | {
+    readonly reason: "near_miss";
+    readonly currentName: string;
+};
+/**
+ * THE ONE reading of a rule's tool name against a roster — the name judgment's stale words, then, for a name the judgment calls
+ * current but the roster does not carry exactly, whether the roster carries it under another case ({@link nearMissSpellingOf}).
+ * `undefined` = no fault: the name is carried, or nothing carried is another spelling of it. A name the roster simply does not
+ * carry is silent: a tool of that name may be mounted later, and a list shared across runs is not wrong because one run lacks a
+ * tool. A list entry (`readRuleEntry`) and a stored whole-tool rule (`parseRuleText`) read a name through this and nothing else;
+ * the policy-name audit composes the same two steps itself over two rosters (a candidate to fold in).
+ */
+export declare function toolNameFaultOf(name: string, roster: ReadonlySet<string>, behavior: RuleBehavior | undefined): ToolNameFault | undefined;
 /** The two kinds of tool-name miss — a closed set. `unknown`: the name is none the engine ever mounted (a typo, a
  *  guess). `expected-absent`: the name is one the engine RETIRED ({@link RETIRED_TOOL_NAMES}), so its absence is no
  *  surprise and the table says what replaced it (the reference spells the same two words for its render-time miss). */

package/dist/core/tool-name-aliases.js

@@ -1,5 +1,6 @@
 import { carriesNamespaceSeparator, protocolOf } from "./protocol-table.js";
 import { mintNamespacePrefix } from "./protocol-naming.js";
+import { catalogToolNames } from "./tool-registry.js";
 export const RETIRED_TOOL_NAMES = new Map([
     ["read_file", 'renamed "Read"'],
     ["edit_file", 'renamed "Edit"'],
@@ -98,6 +99,28 @@ export function judgeRuleToolName(name, roster, behavior) {
         return carriesNamespaceSeparator(name) && !(readsNameGlob(behavior) && name.includes("*")) ? UNPREFIXED : CURRENT;
     return unmintableSegmentOf(split, behavior) ?? CURRENT;
 }
+function mountedSpellingOf(name, roster) {
+    const folded = name.toLowerCase();
+    for (const mounted of roster)
+        if (mounted.toLowerCase() === folded)
+            return mounted;
+    return undefined;
+}
+export function nearMissSpellingOf(name, roster) {
+    if (roster.has(name) || catalogToolNames().has(name) || splitNamespacedName(name) !== undefined)
+        return undefined;
+    return mountedSpellingOf(name, roster);
+}
+export function toolNameFaultOf(name, roster, behavior) {
+    const verdict = judgeRuleToolName(name, roster, behavior);
+    if (verdict.kind === "unprefixed_namespace")
+        return { reason: "tool_name", verdict: verdict.kind };
+    if (verdict.kind !== "current") {
+        return { reason: "tool_name", verdict: verdict.kind, guidance: verdict.guidance, ...(verdict.currentName !== undefined ? { currentName: verdict.currentName } : {}) };
+    }
+    const mounted = nearMissSpellingOf(name, roster);
+    return mounted === undefined ? undefined : { reason: "near_miss", currentName: mounted };
+}
 export const TOOL_MISS_KINDS = Object.freeze(["unknown", "expected-absent"]);
 const [UNKNOWN_MISS, ABSENT_MISS] = TOOL_MISS_KINDS;
 export function judgeToolNameMiss(name, roster) {

package/dist/core/tool-name-readings.d.ts

@@ -127,6 +127,10 @@ export declare const NAME_READINGS: {
         readonly kind: "any";
         readonly file: string;
     };
+    readonly "policy.persistedToolRule": {
+        readonly kind: "any";
+        readonly file: string;
+    };
     readonly "policy.sensitivePathGuardedByName": {
         readonly kind: "any";
         readonly file: string;

package/dist/core/tool-name-readings.js

@@ -33,6 +33,7 @@ export const NAME_READINGS = {
     "gate.skillActivationSeat": wire(GATE),
     "policy.permissionRules": any("src/core/permission-rules.ts"),
     "policy.persistedGrammar": any("src/core/permission-rule-model.ts"),
+    "policy.persistedToolRule": any("src/core/permission-rule-model.ts"),
     "policy.sensitivePathGuardedByName": any("src/core/sensitive-path-policy.ts"),
     "floor.protectivePathTarget": seat("member", "src/core/tool-registry.ts"),
     "floor.protectiveHostTarget": seat("member", "src/core/host-target.ts"),

package/dist/core/tool-policy.d.ts

@@ -1125,7 +1125,8 @@ export declare function createUnverifiableDeletePolicy(opts?: {
 export declare function createTranscriptIntegrityPolicy(opts?: {
     /** Transcript directories to protect. Default: `($AGENT_DATA_DIR ?? ~/.ai-agent)/sessions`. */
     sessionsDirs?: readonly string[];
-    /** argv[0] allowlist for read-only access to the transcript dir (default {@link BASH_READONLY_DEFAULT_ALLOW}). */
+    /** The programs a read-only command over the transcript dir may run (default {@link BASH_READONLY_DEFAULT_ALLOW}); it only
+     *  narrows the read-only reader — a listed program whose call writes still asks. */
     readAllow?: readonly string[];
     /** Override the shell tool names this gate parses (default {@link COARSE_SHELL_TOOLS}, the shell face). */
     tools?: string[];
@@ -1328,13 +1329,16 @@ export interface AskRequest {
      *    command whose exact form the validator refuses offers nothing rather than promoting a lone
      *    prefix to index 0 — see `suggestRulesForCommand`). The seat says "this card has no rule to
      *    offer you", which is true of both; it does not claim the grammar is empty, and a surface must
-     *    not word it as though no rule could ever be written for the command.
+     *    not word it as though no rule could ever be written for the command. It is also the word of a
+     *    card whose tool's form mints no offer: a path tool's, a shell-face sibling's, and a tool that
+     *    answers to one of those under an alias.
      *
      * ABSENT is not a claim, exactly as {@link previewWithheld}'s absence is not: it also covers the
-     * ordinary "there are offers" case and the three STRUCTURAL doors that answer with silence on
-     * purpose (no rule lane wired, a tool the lane does not speak for, a task that cannot hold a rule at
-     * all) — a reason line on every ask of a deployment that never had the feature would be noise about
-     * a lane that does not exist. Read presence, never absence.
+     * ordinary "there are offers" case and the STRUCTURAL door that answers with silence on purpose — no
+     * rule speaks for this call: no rule lane wired, a task that cannot hold a rule at all, or a call the
+     * lane does not judge (a content-routing tool the engine mounts) — a reason line on every ask of a
+     * deployment that never had the feature would be noise about a lane that does not exist. Read
+     * presence, never absence.
      *
      * ADVISORY disclosure metadata, never adjudication input: it changes nothing about what is allowed,
      * and a surface that ignores it renders exactly the card it rendered before. The durable park row

package/dist/core/tool-policy.js

@@ -12,6 +12,7 @@ export { policyCannotAnswer, rowDemandsAPerson } from "./real-approval.js";
 import { sanitizeAutoModeArmingRecipe } from "./auto-mode-arming.js";
 import { join, normalize as normalizePath, sep } from "node:path";
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
+import { readOnlyShellVerdict } from "./read-only-shell.js";
 import { protectivePathTargetOf, shellFaceToolNames } from "./tool-registry.js";
 import { heldBy } from "./tool-name-readings.js";
 import { bindableValueOf, boundInputHashOf, describeBindingFault, exactBoundInputHashOf } from "./canonical-json.js";
@@ -830,14 +831,10 @@ export function createTranscriptIntegrityPolicy(opts) {
                 const cwdInsideProtected = req.cwd !== undefined && inProtectedDir(req.cwd);
                 if (!referencesProtectedDir(cmd) && !cwdInsideProtected)
                     return ALLOW;
-                const parsed = parseLeadingCommandName(command);
-                if ("name" in parsed && readAllow.has(parsed.name))
+                const verdict = readOnlyShellVerdict(command, { cwd: req.cwd, readers: readAllow });
+                if (verdict.readOnly)
                     return ALLOW;
-                return askReason(req, "name" in parsed
-                    ? `\`${parsed.name}\` is not a read-only command${cwdInsideProtected ? " and the shell's working directory is inside the transcript directory" : ""}`
-                    : cwdInsideProtected
-                        ? "the shell's working directory is inside the transcript directory and this is not a single read-only command (fail-closed)"
-                        : "the command references the transcript directory and is not a single read-only command (fail-closed)");
+                return askReason(req, `${cwdInsideProtected ? "the shell's working directory is inside the transcript directory" : "the command references the transcript directory"} and is not read-only: ${verdict.reason}`);
             }
             const writeTarget = protectivePathTargetOf(req);
             if (writeTarget !== undefined && writeTarget.access !== "read") {

package/dist/core/trace.d.ts

@@ -984,5 +984,8 @@ export type TraceEvent = {
  * await it; the default (absent) hook is a no-op the JIT can elide. Must not throw or do sync I/O.
  */
 export type TracerHook = (e: TraceEvent) => void;
-/** Invoke a tracer without ever letting it break the task (absent → no-op; throws swallowed). */
+/** Invoke a tracer without ever letting it break the task (absent → no-op; throws swallowed). A frame is the engine's own account: it
+ *  leaves minted HERE, the one throat — every string leaf through the same-principal tier's text pass, member names as written
+ *  (`egressAccount`) — so a frame that carries a host's, a store's or a remote's words (a thrown text, a failure reason) needs no
+ *  remembering at its mint site. */
 export declare function emitTrace(tracer: TracerHook | undefined, build: () => TraceEvent): void;

package/dist/core/trace.js

@@ -1,8 +1,9 @@
+import { egressAccount } from "./untrusted-egress.js";
 export function emitTrace(tracer, build) {
     if (!tracer)
         return;
     try {
-        tracer(build());
+        tracer(egressAccount("same-principal", build()));
     }
     catch {
     }

package/dist/core/untrusted-egress.d.ts

@@ -60,6 +60,26 @@ export declare function redactHostLeaks(s: string, report?: RedactionReport): Eg
  *  - cycles and shared members stay shared on the snapshot.
  */
 export declare function egressValue<T extends EgressTier, V>(tier: T, value: V): V;
+/**
+ * Tier `tier`'s pass over an engine ACCOUNT value — a notice's detail, a trace frame: data the engine shaped, carrying words that may have
+ * come from a host, a store or a remote. Returned as a new value, never the one handed in. The rules, one each:
+ *  - a string, at any depth, goes through {@link egressText};
+ *  - a member NAME of plain data is the engine's own closed word and is kept as written (a detail's `key` or `tokenCount` is not a
+ *    credential name, and reading it as one would blank the engine's own facts);
+ *  - plain data is an array or an object whose prototype is `Object.prototype` or `null`, and is not a proxy (whose traps answer what
+ *    they choose, a fresh value at every read included); its own enumerable members are read once, a function member is code and is
+ *    not carried;
+ *  - any other object (an error, a class instance, a `Map`, a `Date`, a proxy) came from elsewhere and leaves as
+ *    {@link egressValue} reads it — there, and only there, a credential-named member's string is the marker whole, and there, and
+ *    only there, a member bound applies (one per such value);
+ *  - no member bound applies to plain data: the account is the engine's own, and its size is the engine's to answer for;
+ *  - one walk: an object reached twice — through the data and through a value from elsewhere included — is read once and answers one
+ *    snapshot (cycles and shared members stay shared); past {@link VALUE_DEPTH_MAX} the marker stands in.
+ * Every pass it runs is a fixed point, so an account value minted twice reads the same.
+ */
+export declare function egressAccount<T extends EgressTier, V>(tier: T, value: V): V;
+/** Where the markers sit in `s`, as [start, end) spans, leftmost first. */
+export declare function redactionMarkerSpans(s: string): Array<[number, number]>;
 /** The `same-principal` tier's pass + size-bound (NO injection fence): workflow outputs/results/errors riding back to
  *  the launching model/script, run rows behind scope-gated observe. Paths/URLs survive (the assertion pattern depends on
  *  them); secrets never do. */