@sema-agent/core 7.55.0 → 7.57.0

package/dist/core/runner/runtask.js

@@ -7,13 +7,13 @@ import { createRapidRefillState } from "../auto-compaction.js";
 import { boundInputHashOf } from "../canonical-json.js";
 import { emitTrace } from "../trace.js";
 import { emitTaskOutcome } from "../task-outcome.js";
-import { runWithReasoningWireFacts } from "../../brain/status-sink.js";
+import { runWithCapabilityWithheld, runWithReasoningWireFacts } from "../../brain/status-sink.js";
 import { expandTiers } from "../roles.js";
 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";
@@ -62,11 +64,15 @@ import { runStopAndFinalVerify } from "./run-stop-and-final-verify.js";
 import { runRecoveryLanes } from "./run-recovery-lanes.js";
 import { runGitLane } from "./run-git-lane.js";
 import { deploymentCanRerootChild } from "./child-tree.js";
-import { thrownText } from "../thrown-value.js";
+import { rewindSessionFiles } from "./rewind-files.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();
@@ -95,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(),
                     }));
                 }
@@ -158,14 +164,14 @@ export class Runner {
         const chain = prev.then(() => mine);
         this.sessionLocks.set(sessionId, chain);
         await prev.catch(() => { });
-        return () => {
+        const releaseHold = () => {
             release();
-            void chain.then(() => {
-                if (this.sessionLocks.get(sessionId) === chain) {
-                    this.sessionLocks.delete(sessionId);
-                }
-            });
+            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,8 +239,10 @@ export class Runner {
         announceReadDenySwap(this.deps.onNotice, seats, this.deps);
     }
     sideQuery(spec) {
-        return runWithReasoningWireFacts(() => { }, () => runSideQuery(spec, { brain: this.deps.brain, models: this.deps.models, roles: this.deps.roles }));
+        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, ...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. " +
@@ -282,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;
@@ -332,6 +342,7 @@ export class Runner {
                 });
             }
             finally {
+                legWrites.close();
                 releaseLock?.();
                 publishReady(handle);
                 manualCompactRef.closed = true;
@@ -383,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 }) => {
@@ -403,7 +414,7 @@ export class Runner {
                         const { effectiveTimeoutMs, walltimeMonotonicDeadline, timeout, pushContent, ownCommittedTailRef, emitCommitted } = runClockAndContent({ spec, prepared, queue, internals, rs, ident, parentToolCallId, startedToolCallIds });
                         const toolProgress = createToolProgressLane(pushContent, ident, prepared.toolOccurrences);
                         prepared.toolProgressRef.current = toolProgress;
-                        const { withBrainSinks, withLegRequestSinks } = runBrainSinks({ queue, internals, rs, ident, observeReasoningWireFacts, notice: { onNotice: this.deps.onNotice, sessionId: prepared.sessionId, runId: prepared.runId } });
+                        const { withBrainSinks, withLegRequestSinks } = runBrainSinks({ queue, internals, rs, ident, observeReasoningWireFacts, notice: { onNotice: this.deps.onNotice, sessionId: prepared.sessionId, runId: prepared.runId }, announced: prepared });
                         const toolLabels = new Map(prepared.tools.flatMap((t) => (t.label !== undefined && t.label !== t.name ? [[t.name, t.label]] : [])));
                         for (const orphan of prepared.wakeRecovered) {
                             emitSettled(prepared.toolOccurrences, { toolCallId: orphan.toolCallId, spelledName: orphan.toolName, ...(toolLabels.has(orphan.toolName) ? { label: toolLabels.get(orphan.toolName) } : {}), args: orphan.args }, reconciledEnd(orphan), { push: (f) => queue.push({ ...f, ...ident() }), structured: prepared.structuredProjector, mediaByteCapBytes: this.deps.mediaByteCapBytes });
@@ -502,7 +513,7 @@ export class Runner {
                 token, cp, resumeSignal, recheckGovernanceWindow, store, runner: this.depsSeat,
                 locallyClaimedTokens: this.locallyClaimedTokens, parentConstraintRegistry: this.parentConstraintRegistry, suspendedEnvReaps: this.suspendedEnvReaps,
                 next: () => resumeClaim({
-                    token, cp, store, outcomeForStore,
+                    token, cp, store, outcomeForStore, holder: internals?.holder,
                     locallyClaimedTokens: this.locallyClaimedTokens, parentConstraintRegistry: this.parentConstraintRegistry,
                     next: () => this.resumeHandoff({ token, cp, store, config, internals, resumeInternals, plainPolicyOutcome, redeemedAnswer, outcomeForStore, wakeMessage, wakeHookContext, legMods, resumeSignal }),
                 }),
@@ -528,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-read-file-states.d.ts

@@ -39,7 +39,22 @@ import type { ReadFileState } from "../../tools/fs/safety.js";
  */
 export declare class SessionReadFileStates {
     private readonly seats;
+    /**
+     * The ONE handoff of "which files did a file-history restore of this session move" to the read state that
+     * must stop vouching for their old bytes — written by every restore (the run's restore seat and the
+     * out-of-run `Runner.rewindFiles`), read by the next leg's read face, which checks each path against the disk
+     * after every seeding rung and settles the batch only once its own map is adopted as the seat. A leg that
+     * throws before adopting, or skips the adoption, leaves the batch for the next one. Bounded like the seats
+     * (LRU over session ids): a dropped batch costs a refusal whose wording blames an outside edit, never an admission.
+     */
+    private readonly restored;
     private static readonly CAP;
+    /** Record the ABSOLUTE paths a restore of `sessionId`'s history wrote, deleted or failed to write. */
+    noteRestored(sessionId: string, absPaths: readonly string[]): void;
+    /** The paths still owed a read-state check on `sessionId` — a copy; nothing is cleared by reading. */
+    pendingRestored(sessionId: string): readonly string[];
+    /** Clear exactly the paths a leg checked and then adopted over; a path noted since stays owed. */
+    settleRestored(sessionId: string, checked: readonly string[]): void;
     /** The session's seat row, or undefined (cross-process / evicted / first turn) ⇒ caller replays.
      *  The caller must verify the anchor against the session's CURRENT branch before using `state`. */
     get(sessionId: string): {

package/dist/core/runner/session-read-file-states.js

@@ -1,6 +1,34 @@
 export class SessionReadFileStates {
     seats = new Map();
+    restored = new Map();
     static CAP = 1024;
+    noteRestored(sessionId, absPaths) {
+        if (absPaths.length === 0)
+            return;
+        const batch = this.restored.get(sessionId) ?? new Set();
+        for (const p of absPaths)
+            batch.add(p);
+        this.restored.delete(sessionId);
+        this.restored.set(sessionId, batch);
+        while (this.restored.size > SessionReadFileStates.CAP) {
+            const oldest = this.restored.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.restored.delete(oldest);
+        }
+    }
+    pendingRestored(sessionId) {
+        return [...(this.restored.get(sessionId) ?? [])];
+    }
+    settleRestored(sessionId, checked) {
+        const batch = this.restored.get(sessionId);
+        if (batch === undefined)
+            return;
+        for (const p of checked)
+            batch.delete(p);
+        if (batch.size === 0)
+            this.restored.delete(sessionId);
+    }
     get(sessionId) {
         const seat = this.seats.get(sessionId);
         if (seat !== undefined) {

package/dist/core/runner/session-rule-policy.js

@@ -1,5 +1,5 @@
 import { canonicalizeTarget, isWinFormPath, pathFamilyOf, writeTargetPath } from "../../tools/fs/safety.js";
-import { SESSION_RULES_GRAMMAR, compileSessionRuleBucket, continuesLineage, earlierGrammarAnnouncer, earlierGrammarRefusalClause, readSessionRulesShape, unreadableDenyEntries } from "../session-policy-store.js";
+import { SESSION_RULES_GRAMMAR, compileSessionRuleBucket, continuesLineage, earlierGrammarAnnouncer, earlierGrammarEntries, earlierGrammarRefusalClause, readSessionRulesShape, unreadableDenyEntries } from "../session-policy-store.js";
 import { compiledEntryName, judgeAllowEntries, uncoveredCommandSegment } from "../allow-entry.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { callTargetReadingOf, pathTargetBaseOf, readCallTarget } from "../effective-path-target.js";
@@ -95,7 +95,7 @@ function compileSessionRules(rules) {
     if ("fault" in shaped) {
         const { field, got } = shaped.fault;
         const what = got === "not a rule bucket" ? "a key that is no rule bucket" : field === "" ? `a value that is ${got}, not an object of rule buckets` : `${field} holding ${got}`;
-        return { deny: [], allow: undefined, earlier: { grammar: SESSION_RULES_GRAMMAR, toolAllow: [], toolDeny: [] }, allowDirs: undefined, pathRows: false, names: { deny: [], allow: [] }, unreadable: refuseEvery(what) };
+        return { deny: [], allow: undefined, earlier: { grammar: SESSION_RULES_GRAMMAR, toolAllow: [], toolDeny: [] }, announced: { toolAllow: [], toolDeny: [] }, allowDirs: undefined, pathRows: false, names: { deny: [], allow: [] }, unreadable: refuseEvery(what) };
     }
     const { toolAllow, allowDirs, grammar } = shaped.rules;
     const unreadDeny = unreadableDenyEntries(shaped.rules).length;
@@ -109,6 +109,7 @@ function compileSessionRules(rules) {
         deny,
         allow,
         earlier: { grammar, toolAllow: named(allowList, true), toolDeny: named(denyList, true) },
+        announced: { toolAllow: earlierGrammarEntries(shaped.rules, "toolAllow"), toolDeny: earlierGrammarEntries(shaped.rules, "toolDeny") },
         allowDirs: allowDirs !== undefined && allowDirs.length > 0 ? allowDirs : undefined,
         pathRows: [...deny, ...(allow ?? [])].some((r) => r.compiled.kind === "path"),
         names: { deny: [...deny.map((r) => compiledEntryName(r.compiled)), ...named(denyList, false)], allow: [...(allow ?? []).map((r) => compiledEntryName(r.compiled)), ...named(allowList, false)] },
@@ -128,7 +129,7 @@ export function createSessionRulePolicy(rules, opts) {
         if (compiled === undefined || compiledFor !== r) {
             compiled = compileSessionRules(r);
             for (const field of ["toolAllow", "toolDeny"])
-                announceEarlier(compiled.earlier[field], field, compiled.earlier.grammar);
+                announceEarlier(compiled.announced[field], field, compiled.earlier.grammar);
             compiledFor = r;
         }
         return compiled;

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/shell-env-withheld.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The run's seat for `inherit_env.names_withheld`: the person whose run drives the engine's shell tool is told which
+ * variables of the engine's environment that shell does not receive.
+ *
+ * ONE FACT, ONE MINT. Which entries a shell child loses is decided by the execution environment's one composition
+ * (`inheritedHostEnv(policy, findings)` and the adapter's explicit grants), and the environment hands the result over as
+ * the read `ExecutionEnv.withheldEnv`. This seat reads that answer and tells it; it never recomputes it (the policy and
+ * the grants are the adapter's, not the run's). The split into the scrub's half and the deployment's own credentials is
+ * the one the operator notice uses (`withheldEnvNames`).
+ *
+ * WHEN. At the start of every call to the engine's own shell tool (its mount, judged by the catalog's mount judge), on a
+ * root leg (the person reads the root; the delegation fact is the hook identity's, the leg's one derivation). The answer
+ * is read at each such call because it can grow during a run — a credential the engine takes in when it first routes a
+ * model, dials a peer or builds a seat is withheld from the next child — and a call follows at least one model request.
+ * Told once per SESSION per answer: the digest rides the session's announced record (`advisories`), and a run-time record
+ * write is parked for the leg's flush like every other run-time arm of that record.
+ *
+ * An answer of `"unknown"` is told as unknown, never as silence. A value that is neither a list of findings nor
+ * `"unknown"` (or a read that throws) is a wiring fault: it is announced to the operator under the existing
+ * capability-shape code, once per run, and the person is told nothing — no reading defaults to `"unknown"`.
+ */
+import { type EngineNotice } from "../engine-notice.js";
+import type { ExecutionEnv } from "../../internal/harness.js";
+import type { Prepared } from "./contracts.js";
+export type WithheldShellEnvSeatInput = Pick<Prepared, "sessionId" | "runId" | "hookIdentity" | "toolRosterDeltas" | "announcedListingsRef" | "frameReceipts"> & {
+    readonly harness: {
+        readonly env: Pick<ExecutionEnv, "withheldEnv">;
+    };
+};
+/** The seat, per run. `onToolStart` never throws: a diagnostic may not be what fails a call. */
+export declare function createWithheldShellEnvSeat(prepared: WithheldShellEnvSeatInput, onNotice: ((notice: EngineNotice) => void) | undefined): {
+    onToolStart(toolName: string): void;
+};

package/dist/core/runner/shell-env-withheld.js

@@ -0,0 +1,51 @@
+import { deliverEngineNotice } from "../engine-notice.js";
+import { withheldEnvUserNotice } from "../secret-env.js";
+import { isEngineShellFace } from "../tool-catalog-entries.js";
+import { toolCallFaceOf } from "../tool-roster.js";
+import { announceDigest, withAnnounceDigests } from "./announce-once-ledger.js";
+const isFinding = (f) => typeof f === "object" && f !== null && typeof Reflect.get(f, "key") === "string" && typeof Reflect.get(f, "kind") === "string";
+function readWithheldEnv(env) {
+    try {
+        const value = env.withheldEnv;
+        if (value === "unknown")
+            return "unknown";
+        if (!Array.isArray(value))
+            return { malformed: value === null ? "null" : typeof value };
+        return value.every(isFinding) ? value : { malformed: "array holding a non-finding" };
+    }
+    catch {
+        return { malformed: "unreadable" };
+    }
+}
+export function createWithheldShellEnvSeat(prepared, onNotice) {
+    let shapeFaultTold = false;
+    return {
+        onToolStart(toolName) {
+            if (prepared.hookIdentity.isDelegatedChild || !isEngineShellFace(toolCallFaceOf(prepared.toolRosterDeltas.current, toolName)))
+                return;
+            const answer = readWithheldEnv(prepared.harness.env);
+            if (typeof answer === "object" && "malformed" in answer) {
+                if (shapeFaultTold)
+                    return;
+                shapeFaultTold = true;
+                deliverEngineNotice(onNotice, {
+                    code: "config.execution_env_capability_invalid",
+                    message: `The execution environment declares withheldEnv as (${answer.malformed}), not a list of findings or "unknown". The person whose run drives its shell is told nothing about the variables that shell does not receive. Fix the adapter — this is a wiring fault, not a supported way to leave the member unanswered.`,
+                    detail: { key: "withheldEnv", valueType: answer.malformed },
+                });
+                return;
+            }
+            const notice = withheldEnvUserNotice(answer, { sessionId: prepared.sessionId, runId: prepared.runId });
+            if (notice === undefined)
+                return;
+            const d = notice.detail;
+            const digest = announceDigest(notice.code, `${d.state}\n${[...(d.names ?? [])].sort().join("\n")}\n\n${[...(d.ownCredentials ?? [])].sort().join("\n")}`);
+            const record = prepared.announcedListingsRef;
+            if (record.advisories?.includes(digest) === true)
+                return;
+            deliverEngineNotice(onNotice, notice);
+            record.advisories = withAnnounceDigests(record.advisories, [digest]);
+            prepared.frameReceipts.listingSnapshotOwed = true;
+        },
+    };
+}

package/dist/core/runner/skills-seat.js

@@ -39,7 +39,7 @@ export function readSkillsSeat(skills) {
         const at = `${SKILLS_SEAT}[${i}]`;
         if (typeof raw !== "object" || raw === null || Array.isArray(raw))
             throw skillsSeatRefusal(at, `must be an object { name, description, content } (got ${kindOf(raw)})`);
-        const { name, description, content, allowedTools, disallowedTools, files: rawFiles, baseDir, ...rest } = raw;
+        const { name, description, content, allowedTools, disallowedTools, files: rawFiles, baseDir, mods: rawMods, ...rest } = raw;
         void rest;
         for (const [member, value] of [["name", name], ["description", description], ["content", content]]) {
             if (typeof value !== "string")
@@ -47,11 +47,15 @@ export function readSkillsSeat(skills) {
         }
         const files = readSkillFiles(rawFiles, `${at}.files`);
         skillBaseDirOf(baseDir);
+        if (rawMods !== undefined && !Array.isArray(rawMods))
+            throw skillsSeatRefusal(`${at}.mods`, `must be a list of mods registrations (got ${kindOf(rawMods)})`);
         if (seen.has(name))
             continue;
         seen.add(name);
         const [allowed, denied] = [readSkillTable(allowedTools), readSkillTable(disallowedTools)];
-        out.push({ name, description, content, ...(allowed !== undefined ? { allowedTools: allowed } : {}), ...(denied !== undefined ? { disallowedTools: denied } : {}), ...(files !== undefined ? { files } : {}), ...(baseDir !== undefined ? { baseDir } : {}) });
+        const list = rawMods;
+        const mods = list === undefined ? undefined : Object.freeze(Array.from({ length: list.length }, (_, j) => list[j]));
+        out.push({ name, description, content, ...(allowed !== undefined ? { allowedTools: allowed } : {}), ...(denied !== undefined ? { disallowedTools: denied } : {}), ...(files !== undefined ? { files } : {}), ...(baseDir !== undefined ? { baseDir } : {}), ...(mods !== undefined ? { mods } : {}) });
     }
     return out;
 }