@sema-agent/core 7.56.0 → 7.57.0

package/dist/core/runner/runtask.js

@@ -13,7 +13,7 @@ import { announceReadDenySwap, screenSwappableDeps } from "../swappable-deps.js"
 import { runSideQuery } from "../side-query.js";
 import { PushQueue } from "../push-queue.js";
 import { TtlSessionStore } from "../session-store.js";
-import { errorCodeOf } from "./terminal-account.js";
+import { compensateUnstarted, unstartedRowSentence } from "../resume-startup-cause.js";
 import { effectiveDelegationFacts, prepareTask } from "./prepare-task.js";
 import { SessionReadFileStates } from "./session-read-file-states.js";
 import { SessionModeSeats } from "./session-mode-seats.js";
@@ -24,6 +24,8 @@ import { PendingSessionNotifications } from "../task-notification.js";
 import { ToolDetachHub } from "../tool-detach.js";
 import { assertContextSettingsValue, assertContextSettingsWords, contextOverlayFor } from "../context-settings.js";
 import { createRunState } from "./initial-run-state.js";
+import { SessionWriteLedger } from "./session-write-ledger.js";
+import { teardownLegBudget } from "./teardown-bounded.js";
 import { emitSettled, reconciledEnd } from "./tool-end-body.js";
 import { answerFaceForRedeemedCall } from "./decide-continuation.js";
 import { createTurnBoundary } from "./run-turn-boundary.js";
@@ -63,11 +65,14 @@ import { runRecoveryLanes } from "./run-recovery-lanes.js";
 import { runGitLane } from "./run-git-lane.js";
 import { deploymentCanRerootChild } from "./child-tree.js";
 import { rewindSessionFiles } from "./rewind-files.js";
-import { thrownText } from "../thrown-value.js";
+import { compactIdleSession } from "./compact-session.js";
+import { egressThrownText } from "../untrusted-egress.js";
 export class Runner {
     deps;
     sessions;
     sessionLocks = new Map();
+    sessionWrites = new SessionWriteLedger();
+    verbLockSeats = { sessionBusy: (id) => this.sessionLocks.has(id) || this.sessionWrites.busy(id), takeSessionLock: (id) => this.acquireSessionLock(id) };
     sessionReadStates = new SessionReadFileStates();
     sessionModeSeats = new SessionModeSeats();
     pendingSessionNotifications = new PendingSessionNotifications();
@@ -96,7 +101,7 @@ export class Runner {
                         version: 1,
                         sessionId: context.sessionId,
                         phase: context.phase,
-                        reason: (thrownText(sinkErr)).slice(0, 256),
+                        reason: egressThrownText("same-principal", sinkErr).slice(0, 256),
                         ts: Date.now(),
                     }));
                 }
@@ -159,11 +164,14 @@ export class Runner {
         const chain = prev.then(() => mine);
         this.sessionLocks.set(sessionId, chain);
         await prev.catch(() => { });
-        return () => {
+        const releaseHold = () => {
             release();
             if (this.sessionLocks.get(sessionId) === chain)
                 this.sessionLocks.delete(sessionId);
         };
+        if (this.sessionWrites.busy(sessionId))
+            await this.sessionWrites.settleBeforeHold(sessionId, teardownLegBudget()).catch((err) => { releaseHold(); throw err; });
+        return releaseHold;
     }
     swapDeps(next) {
         const screened = screenSwappableDeps(next);
@@ -233,7 +241,8 @@ export class Runner {
     sideQuery(spec) {
         return runWithReasoningWireFacts(() => { }, () => runWithCapabilityWithheld(() => { }, () => runSideQuery(spec, { brain: this.deps.brain, models: this.deps.models, roles: this.deps.roles })));
     }
-    rewindFiles(request) { return rewindSessionFiles({ deps: this.deps, sessions: this.sessions, readStates: this.sessionReadStates, sessionBusy: (id) => this.sessionLocks.has(id), takeSessionLock: (id) => this.acquireSessionLock(id) }, request); }
+    rewindFiles(request) { return rewindSessionFiles({ deps: this.deps, sessions: this.sessions, readStates: this.sessionReadStates, ...this.verbLockSeats }, request); }
+    compactSession(request) { return compactIdleSession({ deps: this.deps, sessions: this.sessions, ...this.verbLockSeats }, request); }
     runTaskStream(spec, resume, internals) {
         if (resume !== undefined && (typeof resume !== "object" || resume.outcome === undefined)) {
             throw new TypeError("runTaskStream: `resume` must be a ResumeRun carrying `outcome` — got a value without one. " +
@@ -281,14 +290,16 @@ export class Runner {
             return held.taken;
         };
         const namedSessionId = spec.sessionId;
+        const legWrites = this.sessionWrites.openLeg((err, sessionId) => this.deps.onError?.(err, { phase: "degraded", sessionId }));
         const run = (async () => {
-            if (namedSessionId)
-                await holdSessionLock(namedSessionId);
             try {
+                if (namedSessionId)
+                    await holdSessionLock(namedSessionId);
                 await this.runLocked({
                     spec,
                     queue,
                     holdSessionLock: namedSessionId ? undefined : holdSessionLock,
+                    legWrites,
                     setResult: (r) => {
                         resultValue = r;
                         const pcs = internals?.inheritedGate?.parentConstraints;
@@ -331,6 +342,7 @@ export class Runner {
                 });
             }
             finally {
+                legWrites.close();
                 releaseLock?.();
                 publishReady(handle);
                 manualCompactRef.closed = true;
@@ -382,9 +394,9 @@ export class Runner {
         };
     }
     runLocked(input) {
-        const { spec, queue, setResult, onSuggestions, onReady, onSuspend, manualCompactRef, taskIdRef, holdSessionLock, resume, internals, notifyRef, captureOptOutRef, mcpRedialRef, entryActor, entryTracer } = input;
+        const { spec, queue, setResult, onSuggestions, onReady, onSuspend, manualCompactRef, taskIdRef, holdSessionLock, legWrites, resume, internals, notifyRef, captureOptOutRef, mcpRedialRef, entryActor, entryTracer } = input;
         return runNotificationLane({
-            spec, queue, resume, internals, taskIdRef, holdSessionLock,
+            spec, queue, resume, internals, taskIdRef, holdSessionLock, legWrites,
             runner: this.depsSeat, self: this, sessions: this.sessions, sessionReadStates: this.sessionReadStates, sessionModeSeats: this.sessionModeSeats, pendingSessionNotifications: this.pendingSessionNotifications,
             prepareTask,
             next: ({ prepared, injectTaskNotification, deliveredAtTurnOpen, peerInboundChainRef, modelCatalog, notificationLane, unsubscribeTaskNotifications }) => {
@@ -527,37 +539,19 @@ export class Runner {
             preemptSignal: config.preemptSignal?.aborted ? undefined : config.preemptSignal,
             ...(answerFace !== undefined ? { onQuestion: answerFace } : {}),
         };
-        const reopenFn = store.reopen?.bind(store);
+        const reopenUnstarted = async (reason) => ((await store.reopen(token, cp.scope, reason)) ? "reopened" : "declined");
         const recordExecutionOutcome = (gate) => store.recordExecutionOutcome(token, cp.scope, gate);
-        const onEnvRestoreFailed = reopenFn
-            ? async (reason) => {
-                const reopened = await reopenFn(token, cp.scope, reason);
-                if (!reopened) {
-                    throw new CheckpointError("checkpoint.reopen_failed", "checkpoint could not be reopened for a retry (missing, expired, or changed concurrently) — the resume failure is terminal");
-                }
-            }
-            : undefined;
         if (resumeSignal?.aborted === true && consumeFlipDone) {
             throw new CheckpointError("checkpoint.resume_aborted", "the resume was aborted after its row was already claimed — the checkpoint stays consumed and the caller's rollback settles the outcome-unknown terminal (reopening here would strand a pending approval no redemption path can reach)");
         }
         if (resumeSignal?.aborted === true) {
-            let reopenOutcome = "refused";
-            if (onEnvRestoreFailed !== undefined) {
-                try {
-                    await onEnvRestoreFailed("env_failed");
-                    reopenOutcome = "reopened";
-                }
-                catch (err) {
-                    reopenOutcome = errorCodeOf(err) === "checkpoint.reopen_failed" ? "refused" : "unknown";
-                }
-            }
-            throw reopenOutcome === "reopened"
-                ? new CheckpointError("checkpoint.resume_aborted", "the resume was aborted before the approved action could run — the checkpoint was reopened, so the same approval can be resumed with a live signal")
-                : reopenOutcome === "refused"
-                    ? new CheckpointError("checkpoint.reopen_failed", "the resume was aborted before the approved action could run AND the store refused to reopen the checkpoint — the approval is terminally consumed and the suspended work was not executed; a retry needs a fresh approval")
-                    : new CheckpointError("checkpoint.reopen_failed", "the resume was aborted before the approved action could run and the reopen attempt FAILED IN FLIGHT — the checkpoint's state is unprovable from here: it may already be pending again. Re-read it before deciding; do NOT issue a fresh approval on the assumption the old one is dead (the approved action did NOT run either way)");
+            const row = await compensateUnstarted(reopenUnstarted, "env_failed");
+            const said = `the resume was aborted before the approved action could run — ${unstartedRowSentence(row)}`;
+            if (row.kind === "reopened")
+                throw new CheckpointError("checkpoint.resume_aborted", said);
+            throw new CheckpointError("checkpoint.reopen_failed", said);
         }
-        return this.runTaskStream(spec, { cp, outcome: outcomeForStore, onEnvRestoreFailed, recordExecutionOutcome, ...(wakeMessage !== undefined ? { wakeMessage } : {}), ...(wakeHookContext !== undefined ? { wakeMessageHookContext: wakeHookContext } : {}), ...(legMods !== undefined ? { legMods } : {}) }, resumeInternals);
+        return this.runTaskStream(spec, { cp, outcome: outcomeForStore, reopenUnstarted, recordExecutionOutcome, ...(wakeMessage !== undefined ? { wakeMessage } : {}), ...(wakeHookContext !== undefined ? { wakeMessageHookContext: wakeHookContext } : {}), ...(legMods !== undefined ? { legMods } : {}) }, resumeInternals);
     }
 }
 export function runTask(spec, deps) {

package/dist/core/runner/send-message-continuation.js

@@ -9,7 +9,7 @@ function buildTier3ReviveSpawn(delegationForRevive, enrichSpecToolCtx) {
             prompt: req.prompt,
             run_in_background: true,
             ...(req.row.agentType !== undefined ? { subagent_type: req.row.agentType } : {}),
-            ...(req.row.name !== undefined ? { name: req.row.name } : {}),
+            name: req.row.name,
             ...(req.row.model !== undefined ? { model: req.row.model } : {}),
         }, enrichSpecToolCtx({ toolCallId: `rv-${randomBytes(8).toString("hex")}`, reviveClaim: { row: req.row, rev: req.rev, ...(req.peerSeed !== undefined ? { peerSeed: req.peerSeed } : {}) } }));
         const o = (typeof out === "string" ? { content: out } : out);

package/dist/core/runner/session-verb-doors.d.ts

@@ -0,0 +1,28 @@
+import type { AcquiredSession, SessionStore } from "../session.js";
+/** What the Runner lends an out-of-run verb for the session's lock. */
+export interface SessionLockSeats {
+    /** Whether a leg of this Runner holds or awaits `sessionId`'s lock, or a write one issued to it has not settled. */
+    sessionBusy(sessionId: string): boolean;
+    /** Take `sessionId`'s lock; called synchronously after `sessionBusy` answered false, so nothing slips in between. */
+    takeSessionLock(sessionId: string): Promise<() => void>;
+}
+/**
+ * The request door: the request must be a plain data object — not a Proxy (its traps are the caller's code, and could
+ * answer the caller's read of a member differently from this one), its prototype `Object.prototype` or none (so no
+ * member is inherited) — judged before any member is read; its members are then taken from ONE snapshot of its own
+ * data properties, so no code of the request itself (a trap, a getter) runs while it is read and nothing read can
+ * change what is read next (an accessor member is a bad request); own keys inside the verb's closed set. `bad`
+ * throws the verb's own refusal; the member types are the verb's to judge on the returned snapshot.
+ */
+export declare function readPlainRequest(request: unknown, keys: ReadonlySet<string>, bad: (what: string) => never): Record<string, unknown>;
+/** A value as a refusal names it: a string clipped, a primitive spelled, anything else by its type. */
+export declare function shownValue(v: unknown): string;
+/**
+ * The idle claim: refused with `busy()` when a leg of this Runner is running or queued on the session (its state is
+ * not moved under it); otherwise the session's lock is claimed in this same synchronous step and held by the verb
+ * until it releases it, so a leg that arrives meanwhile waits for the verb.
+ */
+export declare function claimIdleSession(seats: SessionLockSeats, sessionId: string, busy: () => Error): Promise<() => void>;
+/** The session must exist — the same door and code a run with `requireExistingSession` meets. `verb` prefixes the
+ *  message, `nothingDone` says what the verb did not do. */
+export declare function acquireExistingSession(sessions: SessionStore, sessionId: string, verb: string, nothingDone: string): Promise<AcquiredSession>;

package/dist/core/runner/session-verb-doors.js

@@ -0,0 +1,48 @@
+import { types } from "node:util";
+import { isPlainRecord } from "../mods/kernel/receive.js";
+import { readMember } from "../thrown-value.js";
+export function readPlainRequest(request, keys, bad) {
+    if (typeof request !== "object" || request === null)
+        return bad(`the request must be a plain object, got ${request === null ? "null" : typeof request}`);
+    if (types.isProxy(request) || !isPlainRecord(request))
+        return bad("the request must be a plain data object (not a Proxy, and with no prototype that could supply a member)");
+    let descriptors;
+    try {
+        descriptors = Object.getOwnPropertyDescriptors(request);
+    }
+    catch {
+        return bad("the request could not be read");
+    }
+    const own = Reflect.ownKeys(descriptors);
+    const unknown = own.filter((k) => typeof k !== "string" || !keys.has(k));
+    if (unknown.length > 0)
+        return bad(`unknown key ${unknown.map((k) => JSON.stringify(String(k))).join(", ")}`);
+    const read = {};
+    for (const k of own) {
+        const d = descriptors[k];
+        if (!("value" in d))
+            return bad(`member ${JSON.stringify(k)} is an accessor, not a value`);
+        read[k] = d.value;
+    }
+    return read;
+}
+export function shownValue(v) {
+    return typeof v === "string" ? JSON.stringify(v.slice(0, 40)) : v === null || typeof v === "boolean" || typeof v === "number" ? String(v) : `a ${typeof v}`;
+}
+export function claimIdleSession(seats, sessionId, busy) {
+    if (seats.sessionBusy(sessionId))
+        throw busy();
+    return seats.takeSessionLock(sessionId);
+}
+export async function acquireExistingSession(sessions, sessionId, verb, nothingDone) {
+    try {
+        return await sessions.acquire(sessionId, { requireExisting: true });
+    }
+    catch (err) {
+        if (readMember(err, "code") !== "not_found")
+            throw err;
+        const e = new Error(`${verb}: session "${sessionId}" does not exist — ${nothingDone}`);
+        e.code = "resume.session_not_found";
+        throw e;
+    }
+}

package/dist/core/runner/session-write-ledger.d.ts

@@ -0,0 +1,30 @@
+import type { SessionStorage } from "../session.js";
+import type { LegWrites } from "./contracts.js";
+export type { LegWrites };
+export declare class SessionWriteLedger {
+    #private;
+    /** A leg's view. `report` receives the incidents (a refused write, a late settlement); a throwing sink is swallowed. */
+    openLeg(report: (err: Error, sessionId: string) => void): LegWrites;
+    /**
+     * The session's next hold starts here: resolves once `sessionId` has no write in flight, and throws `SessionError("conflict")`
+     * — the leg about to start has written nothing — when one is still unsettled after `ms`.
+     */
+    settleBeforeHold(sessionId: string, ms: number): Promise<void>;
+    /**
+     * Whether `sessionId` has a write in flight — a synchronous read. The session's next holder asks it before {@link settleBeforeHold}
+     * and awaits only on `true`: a session with nothing in flight takes no suspension point at its hold. The two reads sit on one tick,
+     * and nothing joins the set between the check and the hold's return — the previous holder's view is closed before its lock is
+     * released, the lock serialises holders, and a holder that is no leg (the rewind verb) issues no write through a view.
+     */
+    busy(sessionId: string): boolean;
+    /**
+     * Resolves `true` once `sessionId` has no write in flight, `false` when `ms` elapse first. The timer is not unref'd: the
+     * caller awaits this in foreground control flow (the teardown-bounded discipline), and it is cleared on settle.
+     */
+    drained(sessionId: string, ms: number): Promise<boolean>;
+}
+/**
+ * The acquired storage as a leg writes it: the two write members go through `leg.issue` (named by the entry type, `leaf` for a
+ * leaf move), every other member is the storage's own. Per leg and non-mutating (a Proxy), like the conflict watch above it.
+ */
+export declare function writesThroughLeg(storage: SessionStorage, leg: LegWrites, sessionId: string): SessionStorage;

package/dist/core/runner/session-write-ledger.js

@@ -0,0 +1,101 @@
+import { SessionError } from "../session.js";
+import { thrownText } from "../thrown-value.js";
+export class SessionWriteLedger {
+    #inFlight = new Map();
+    #drainWaiters = new Map();
+    openLeg(report) {
+        let closedAt;
+        const tell = (sessionId, message) => {
+            try {
+                report(new Error(message), sessionId);
+            }
+            catch {
+            }
+        };
+        return {
+            issue: (sessionId, what, start) => {
+                if (closedAt !== undefined) {
+                    const message = `session "${sessionId}": a ${what} write was issued after its leg ended and was not started`;
+                    tell(sessionId, message);
+                    return Promise.reject(new SessionError("conflict", message));
+                }
+                let write;
+                try {
+                    write = Promise.resolve(start());
+                }
+                catch (err) {
+                    return Promise.reject(err);
+                }
+                this.#add(sessionId, write);
+                const settledLate = (outcome) => {
+                    this.#remove(sessionId, write);
+                    if (closedAt !== undefined)
+                        tell(sessionId, `session "${sessionId}": a ${what} write issued by a leg that has since ended settled ${Date.now() - closedAt}ms after the leg ended — ${outcome}`);
+                };
+                write.then(() => settledLate("it landed"), (err) => settledLate(`it failed: ${thrownText(err)}`));
+                return write;
+            },
+            close: () => {
+                closedAt ??= Date.now();
+            },
+        };
+    }
+    async settleBeforeHold(sessionId, ms) {
+        if (await this.drained(sessionId, ms))
+            return;
+        throw new SessionError("conflict", `session "${sessionId}": a write an earlier leg of this session issued has not settled after ${ms}ms — this leg wrote nothing; retry once it settles`);
+    }
+    busy(sessionId) {
+        return (this.#inFlight.get(sessionId)?.size ?? 0) > 0;
+    }
+    drained(sessionId, ms) {
+        if (!this.busy(sessionId))
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const waiters = this.#drainWaiters.get(sessionId) ?? new Set();
+            this.#drainWaiters.set(sessionId, waiters);
+            const done = () => {
+                clearTimeout(timer);
+                waiters.delete(done);
+                if (waiters.size === 0 && this.#drainWaiters.get(sessionId) === waiters)
+                    this.#drainWaiters.delete(sessionId);
+                resolve(true);
+            };
+            const timer = setTimeout(() => {
+                waiters.delete(done);
+                if (waiters.size === 0 && this.#drainWaiters.get(sessionId) === waiters)
+                    this.#drainWaiters.delete(sessionId);
+                resolve(false);
+            }, ms);
+            waiters.add(done);
+        });
+    }
+    #add(sessionId, write) {
+        const set = this.#inFlight.get(sessionId) ?? new Set();
+        set.add(write);
+        this.#inFlight.set(sessionId, set);
+    }
+    #remove(sessionId, write) {
+        const set = this.#inFlight.get(sessionId);
+        if (set === undefined)
+            return;
+        set.delete(write);
+        if (set.size > 0)
+            return;
+        this.#inFlight.delete(sessionId);
+        for (const wake of [...(this.#drainWaiters.get(sessionId) ?? [])])
+            wake();
+    }
+}
+export function writesThroughLeg(storage, leg, sessionId) {
+    return new Proxy(storage, {
+        get(target, prop, receiver) {
+            if (prop === "appendEntry")
+                return (...args) => leg.issue(sessionId, args[0].type, () => target.appendEntry(...args));
+            if (prop === "setLeafId")
+                return (...args) => leg.issue(sessionId, "leaf", () => target.setLeafId(...args));
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}

package/dist/core/runner/stream-settle-backstop.js

@@ -1,5 +1,5 @@
-import { errorCodeOf, thrownFailureOf } from "./terminal-account.js";
-import { reopenReasonOf, resumeStartupCauseOf } from "../resume-startup-cause.js";
+import { thrownFailureOf } from "./terminal-account.js";
+import { compensateUnstarted, reopenReasonOf, resumeStartupCauseOf, unstartedRowSentence } from "../resume-startup-cause.js";
 import { resumeDecisionWasNegative } from "./decide-continuation.js";
 import { drainForwardedFramesBeforeDone, forwardsSubagentEvents } from "./prepare-run-refs.js";
 import { hasDestroy } from "../remote-env.js";
@@ -13,23 +13,20 @@ export function streamSettleBackstop(input) {
     const onRunRejected = async (err) => {
         let { code, message, detail } = thrownFailureOf(err, thrownText(err));
         const reopenReason = reopenReasonOf(resumeStartupCauseOf(code));
-        const reopenable = resume !== undefined && resume.pendingActionStarted !== true && reopenReason !== undefined && !(resumeDecisionWasNegative(resume) && resume.decisionDelivered === true);
+        const reopenable = resume !== undefined && live.resultValue === undefined && resume.pendingActionStarted !== true && !(resumeDecisionWasNegative(resume) && resume.decisionDelivered === true);
         let reopenCommitted = false;
         let reopenStateUnknown = false;
-        if (reopenable && resume?.onEnvRestoreFailed) {
-            try {
-                await resume.onEnvRestoreFailed(reopenReason);
+        if (reopenable && resume !== undefined) {
+            const row = await compensateUnstarted(resume.reopenUnstarted, reopenReason);
+            if (row.kind === "reopened") {
                 reopenCommitted = true;
+                message = `${message} — ${unstartedRowSentence(row)}`;
             }
-            catch (reopenErr) {
+            else {
                 parentConstraintRegistry.delete(resume.cp.token);
                 const original = asThrownError(err);
-                const reopenMsg = thrownText(reopenErr);
-                const definitive = errorCodeOf(reopenErr) === "checkpoint.reopen_failed";
-                reopenStateUnknown = !definitive;
-                err = Object.assign(new Error(definitive
-                    ? `${reopenMsg} (original resume failure: ${original.message})`
-                    : `checkpoint reopen threw mid-flight — state UNKNOWN, confirm via the checkpoint store before retrying: ${reopenMsg} (original resume failure: ${original.message})`, { cause: original }), { code: "checkpoint.reopen_failed" });
+                reopenStateUnknown = row.kind === "unknown";
+                err = Object.assign(new Error(`${original.message} — ${unstartedRowSentence(row)}`, { cause: original }), { code: "checkpoint.reopen_failed" });
                 const replacement = thrownFailureOf(err, thrownText(err));
                 code = replacement.code;
                 message = replacement.message;
@@ -38,7 +35,7 @@ export function streamSettleBackstop(input) {
         }
         if (resume)
             locallyClaimedTokens.delete(resume.cp.token);
-        if (resume && !reopenCommitted) {
+        if (resume && !reopenCommitted && live.resultValue === undefined) {
             parentConstraintRegistry.delete(resume.cp.token);
             await settleTeardownLeg(() => sessions.unpin?.(resume.cp.sessionId), "sessions.unpin (resume-failure leg)", (e) => runner.deps.onError?.(e, { phase: "config", sessionId: resume.cp.sessionId }));
             if (!reopenStateUnknown) {

package/dist/core/runner/sub-agent-deny-lists.d.ts

@@ -36,7 +36,7 @@
 import type { AgentTool } from "../../internal/harness.js";
 import { valveLeaves } from "../../agents/tool-filter.js";
 import { type ProtocolId } from "../protocol-table.js";
-import type { ToolLegKind, ToolSelectorLayer } from "../tool-face.js";
+import type { ToolLegKind, ToolSelector, ToolSelectorLayer } from "../tool-face.js";
 import { type ConstraintChainEntry } from "../tool-policy.js";
 import type { TaskSpec } from "../types.js";
 import type { CheckpointErrorReason } from "../checkpoint-store.js";
@@ -87,6 +87,27 @@ export type PersistedToolFaceReason = Extract<CheckpointErrorReason, "not_a_list
  * leg's roster and a sink; the leg's own policy-name audit is what reads them.
  */
 export declare function deniedToolNamesOf(where: string, value: unknown): string[];
+/**
+ * Whose lists a run's own layer are, in the words every sentence about them uses: the delegation tool (and agent definition) that wrote
+ * them when the run records one (`RunInternals.ownToolLists`), else `undefined` — the run's own `TaskSpec` seats.
+ */
+export declare function ownListsWhereOf(ownBy: RunInternals["ownToolLists"]): string | undefined;
+/**
+ * THE build of a leg's tool selector: `layers` are the ceiling it was spawned under, then its own lists (the last is its own), and
+ * `legs` the kinds of leg it is. Every layer is read by the one layer reader ({@link readSelectorLayer}), once, whoever judged it and
+ * whatever evidence the run carries — a live ceiling and the run's own lists were judged by the engine that wrote them, which may have
+ * read what this one cannot (a list that is not one, a member that is not a string, an entry no rule syntax reads), so the leg does not
+ * start without a layer that says something. The selector is compiled from what was read, never from the layers again: a getter that
+ * answers differently the second time is not asked a second time, and the selector's layers (handed to the leg's children as their
+ * ceiling) are the frozen product. Built before anything reads it, and before the session is acquired, so a refusal needs nothing given
+ * back. `where` is whose lists the own layer is ({@link ownListsWhereOf}). (A ceiling a resumed row restored was read by the same reader
+ * before the claim — `persistedToolNamesRefusal`.)
+ */
+export declare function readToolSelector(input: {
+    readonly layers: readonly unknown[];
+    readonly where: string | undefined;
+    readonly legs: readonly ToolLegKind[];
+}): ToolSelector;
 /**
  * THE read-back of the tool names a checkpoint row carries, before the claim: the ceiling the resumed leg will run under when it is
  * the row's (`ceiling`: absent when a live seat hands one) — each layer read by {@link readSelectorLayer} as a recorded layer — and
@@ -141,8 +162,9 @@ export interface RunToolListsInput {
         readonly allow: readonly string[] | undefined;
         readonly exclude: readonly string[] | undefined;
     };
-    /** borrowed-readonly — every layer of the run's selector (the ceiling, then its own) and the kinds of leg it is. */
-    layers: readonly ToolSelectorLayer[];
+    /** borrowed-readonly — the run's selector, as {@link readToolSelector} built it: every layer of it (the ceiling, then its own) already read, and judged here as read. */
+    selector: ToolSelector;
+    /** The kinds of leg the run is (the ones the selector was built for). */
     legs: readonly ToolLegKind[];
     /** True ⇔ the spawning run's prepare judged exactly these own lists where they were mounted, against a pool it could list (as the
      *  child-facing lists of the delegation tool or definition that wrote them) — the evidence digest it handed down (live, or recorded

package/dist/core/runner/sub-agent-deny-lists.js

@@ -150,14 +150,31 @@ function readSelectorLayer(layer, layerWhere, listWhere, recorded) {
     if (!isToolSelectorLayer(layer)) {
         throw refused(`${layerWhere} are a value that is ${valueTypeLabel(layer)}, not a pair of tool-name lists (an allowed and a denied list) — the leg does not start. Fix the layer.`, "config.tool_face_control", "not_a_list");
     }
+    const lists = {};
     for (const side of ["allowed", "denied"]) {
         const where = listWhere(side);
-        const entries = readableToolNameList(where, side, side === "allowed" ? layer.allow : layer.deny, "config.tool_face_control");
+        const value = side === "allowed" ? layer.allow : layer.deny;
+        const entries = readableToolNameList(where, side, value, "config.tool_face_control");
         const written = recorded ? entries.find((read) => !isCanonicalToolName(read.entry)) : undefined;
         if (written !== undefined) {
             throw refused(`${where} declares ${renderListEntry(written.entry)} in its ${LIST_WORD[side]}: a row records each tool name in its bare spelling (\`Read\`, never \`Read()\`, \`Read(*)\` or \`Read(…)\`), and this entry was recorded by an engine that read the list otherwise — it is read here neither as that engine read it nor as this one would`, "config.tool_face_control", "unsupported_pattern");
         }
+        if (value !== undefined && value !== null)
+            lists[side] = Object.freeze(entries.map((read) => read.entry));
     }
+    return Object.freeze({ ...(lists.allowed !== undefined ? { allow: lists.allowed } : {}), deny: lists.denied ?? Object.freeze([]) });
+}
+export function ownListsWhereOf(ownBy) {
+    return ownBy !== undefined ? delegationListWhere(ownBy.toolName, ownBy.definition) : undefined;
+}
+export function readToolSelector(input) {
+    const layers = [...input.layers];
+    const ceilings = layers.length - 1;
+    const read = layers.map((layer, i) => {
+        const inherited = i === ceilings ? undefined : inheritedListsWhere(ceilings, i);
+        return readSelectorLayer(layer, inherited ?? "this run's own tool lists", (side) => inherited ?? input.where ?? (side === "allowed" ? "TaskSpec.allowTools" : "TaskSpec.excludeTools"), false);
+    });
+    return compileToolSelector(read, input.legs);
 }
 function ownToolListsFlaw(value) {
     try {
@@ -255,14 +272,9 @@ export function judgeRunToolLists(input) {
         catch {
         }
     };
-    const ownWhere = input.ownBy !== undefined ? delegationListWhere(input.ownBy.toolName, input.ownBy.definition) : undefined;
-    const ceilings = input.layers.length - 1;
-    input.layers.forEach((layer, i) => {
-        const own = i === ceilings;
-        const inherited = own ? undefined : inheritedListsWhere(ceilings, i);
-        readSelectorLayer(layer, inherited ?? "this run's own tool lists", (side) => inherited ?? ownWhere ?? (side === "allowed" ? "TaskSpec.allowTools" : "TaskSpec.excludeTools"), false);
-    });
-    const denied = deniedProtocolTools(input.layers, input.legs);
+    const ownWhere = ownListsWhereOf(input.ownBy);
+    const selector = input.selector;
+    const denied = deniedProtocolTools(selector.layers, input.legs);
     if (denied.length > 0) {
         const names = [...new Set(denied.map((h) => `"${h.name}"`))];
         const one = names.length === 1;
@@ -273,7 +285,6 @@ export function judgeRunToolLists(input) {
         const by = [...deniedBy(true, ownWhere ?? "this run's own excludeTools"), ...deniedBy(false, "an inherited list (the spawning run's excludeTools, or one it inherits)")];
         throw refused(`This kind of leg (${input.legs.join(", ")}) relies on ${names.join(", ")}, but ${by.join(" and ")} — the leg cannot work without ${one ? "it" : "them"}. Remove the entry from the list that names it.`, "config.tool_face_control", "protocol_denied");
     }
-    const selector = compileToolSelector(input.layers, input.legs);
     const pool = delegationPoolReading(spec.tools ?? [], valveLeaves(spec, selector));
     const mounted = mountedToolNames([...tools, ...(spec.tools ?? [])]);
     if (!input.judgedUpstream) {

package/dist/core/runner/teardown-bounded.d.ts

@@ -27,6 +27,7 @@
 export declare const TEARDOWN_LEG_MAX_MS = 15000;
 /** Test hook (fs-atomic TxnLockTimings precedent): shrink the budget so wedge pins need no real 15s. */
 export declare function setTeardownLegBudgetForTests(ms: number | undefined): void;
+export declare const teardownLegBudget: () => number;
 /** The typed timeout incident — `leg` names the site so a leak is attributable from the report alone. */
 export declare class TeardownLegTimeoutError extends Error {
     readonly leg: string;

package/dist/core/runner/teardown-bounded.js

@@ -4,6 +4,7 @@ let teardownLegBudgetMs = TEARDOWN_LEG_MAX_MS;
 export function setTeardownLegBudgetForTests(ms) {
     teardownLegBudgetMs = ms ?? TEARDOWN_LEG_MAX_MS;
 }
+export const teardownLegBudget = () => teardownLegBudgetMs;
 export class TeardownLegTimeoutError extends Error {
     leg;
     constructor(leg, budgetMs) {

package/dist/core/runner-deps.d.ts

@@ -968,8 +968,8 @@ export interface RunnerDeps {
      * organization's delivery gate appends cross-principal letters; the mailbox contract's fourth chain).
      * Absent = no consumer, no lane (byte for byte as before); a deployment that mounts a gate DECLARES
      * `{ assistant: "<agent handle>" }` (the scope's assistant is the only consumer; no terminal leg touches the
-     * box). `"terminals"` (each terminal drains the box as a second lane) is refused until held decisions are
-     * shared across terminals (`detail.reason: "terminals_unsupported"`). Letters are judged on the principal's
+     * box) or `"terminals"` (each terminal drains the box as a second lane; a held letter's decision is the
+     * letter's own field in the box, so every terminal reads the same one). Letters are judged on the principal's
      * `crossSessionInbound` layers (managed, user), held when unset. ANY other value fails the prepare of a leg
      * that drains a session box with `config.principal_inbox_consumer_invalid` (`detail.reason: "malformed"`).
      */

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

@@ -61,6 +61,10 @@ export interface WithheldEnvDeclaration {
      *  a flag or placeholder word, one character repeated, or fewer than eight characters. */
     readonly values: readonly string[];
 }
+/** {@link notACredentialReason}'s answer as a yes: the same guess for the second place that pays for withholding a string — every
+ *  occurrence of a request's key taken out of a remote's words (`remoteWords`): a key that names no secret (`EMPTY`, a local gateway's
+ *  one-letter key) is left in the words, as it is left to every child. */
+export declare function namesASecret(value: string): boolean;
 /**
  * Declare this deployment's OWN credentials in this process's environment — the engine's or its host's: an approval
  * bearer, a service token — by name and by value. From then on no child spawned on this host inherits one, whatever the

package/dist/core/secret-env.js

@@ -209,6 +209,9 @@ function notACredentialReason(value) {
         return "one character repeated, which names no secret";
     return undefined;
 }
+export function namesASecret(value) {
+    return notACredentialReason(value) === undefined;
+}
 function credentialValueProblem(v) {
     if (typeof v !== "string")
         return kindOf(v);

package/dist/core/session-policy-store.d.ts

@@ -76,7 +76,12 @@ export type SessionRuleEntryField = {
  *    name starting with `*` as no rule; in `toolAllow` it grants nothing by itself and the entries beside it keep their reading,
  *    where grammars 1–4 voided a list holding it. An engine of grammar 4 given a row written in grammar 5 refuses it rather than
  *    read a `*` deny as nothing. In the same revision a host pattern with an empty label (`WebFetch(domain:.evil.test)`) or a `*`
- *    the URL parser folds (`＊.`) is no rule, where grammar 4 read the exact host it spelled; an earlier row's such entry reads as no rule.
+ *    the URL parser folds (`＊.`) is no rule, where grammar 4 read the exact host it spelled; an earlier row's such entry reads as no rule;
+ *  - 6, a persisted rule with no content (`SendUserFile`, `Bash`, `Bash(*)`) is the WHOLE-TOOL rule (`match: "tool"`), where grammar 5's
+ *    persisted grammar read every bare name as no rule. A session's entries mean what they meant (the entry reader already read a bare
+ *    name as the whole tool), so no earlier entry reads differently; the stamp moves for the persisted store's buckets and the sync
+ *    wire's states, so an engine of grammar 5 given a bucket written in grammar 6 refuses it whole rather than drop a whole-tool deny
+ *    as damage. No persisted row of an earlier stamp can hold a bare name (every entrance refused one), so none is read anew.
  * A row an earlier grammar wrote keeps the meaning that grammar gave its entries, and an entry that grammar could not read takes
  * this one's ({@link earlierGrammarReads}, over the revisions above as one table); an entry this grammar reads as no rule reads as
  * `earlier_grammar` ({@link compileSessionRuleBucket}).
@@ -89,7 +94,7 @@ export type SessionRuleEntryField = {
  * what an existing persisted rule text means owes that store a reading of its earlier stamps, as {@link earlierGrammarReads}
  * is for entries. Every stamp is judged by {@link readRuleGrammarStamp}.
  */
-export declare const SESSION_RULES_GRAMMAR = 5;
+export declare const SESSION_RULES_GRAMMAR = 6;
 /** {@link SessionPermissionRules} plus the monotonic `rev` the store stamps (the OCC key). */
 export interface StoredSessionRules extends SessionPermissionRules {
     rev: number;

package/dist/core/session-policy-store.js

@@ -12,7 +12,7 @@ const BUCKETS = Object.keys(SESSION_RULE_BUCKETS);
 const ENTRY_FIELDS = BUCKETS.filter((f) => SESSION_RULE_BUCKETS[f] !== "dirs");
 const STORE_STAMPS = new Set(["rev", "gen", "grammar"]);
 const OPERATOR_PART = "operatorRules";
-export const SESSION_RULES_GRAMMAR = 5;
+export const SESSION_RULES_GRAMMAR = 6;
 export class SessionPolicyError extends Error {
     code;
     detail;

package/dist/core/shell-wrapper-projection.d.ts

@@ -1,6 +1,6 @@
 import type { ShellWrapperRow } from "./shell-wrapper-table.js";
 /**
- * The PROJECTION {@link import("./shell-wrapper-table.js").SHELL_WRAPPER_TABLE} is: the second lexer's view of the program read model's rows (`program-read-model.ts`
+ * The PROJECTION {@link import("./shell-wrapper-table.js").SHELL_WRAPPER_TABLE} is: the tightening reader's peel view of the program read model's rows (`program-read-model.ts`
  * — one table of program facts, read through the binary gate). A launcher row's options by arity (a value word, a
  * switch or an attached-only value, a command string), its required operand (a duration, or the spelling it must have),
  * its bare-dash switch and its `NAME=value` operands; a row that runs its operands, or a code body, as shell input