@sema-agent/core 7.8.0 → 7.9.0

package/dist/core/runner/permission-rule-lanes.js

@@ -1,8 +1,8 @@
 import { persistedRuleMandateOf } from "../hooks.js";
-import { directoryRuleAdmits, eligiblePersisted, findAdmittingRule, lexicalNormalAbsolutePathOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { adjudicatePersistedPathRules, adjudicatePersistedRules, lexicalNormalAbsolutePathOf, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { declaredPathTargetOf, pathTargetValue, protectivePathTargetOf } from "../tool-registry.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 export const PERSISTED_RULE_TOOL = "Bash";
-export const DIRECTORY_RULE_TOOL = "Read";
 const HANDOFF_BOUND = 256;
 export function inheritedAskRuleEvidence(provider) {
     const org = provider?.partitions.org === true ? "not_adjudicated" : "not_wired";
@@ -19,21 +19,26 @@ export function orgRevisionEvidenceOf(resolution, onDefect) {
         `the adjudication stands, but the ask carries no revision evidence for this call`);
     return {};
 }
-export function persistedRuleHitOf(admitting) {
-    return admitting === undefined
+export function persistedRuleHitOf(verdict) {
+    return verdict === undefined
         ? undefined
-        : { rules: admitting.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
+        : { behavior: verdict.behavior, rules: verdict.rules.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
 }
-export function directoryRuleLaneAnswer(table, args, ctx) {
-    const filePath = args?.file_path;
-    if (typeof filePath !== "string" || filePath === "")
-        return undefined;
-    const spelled = filePath.startsWith("/") ? filePath : `${(ctx.liveCwd ?? ctx.root ?? "").replace(/\/+$/, "")}/${filePath}`;
-    const target = lexicalNormalAbsolutePathOf(spelled);
-    if (target === undefined)
+export function pathRuleLaneAnswer(table, req, ctx) {
+    const base = (ctx.liveCwd ?? ctx.root ?? "").replace(/\/+$/, "");
+    const resolve = (pt) => {
+        if (pt === undefined)
+            return undefined;
+        const spelled = pathTargetValue(req.args, pt);
+        if (spelled === undefined)
+            return undefined;
+        return lexicalNormalAbsolutePathOf(spelled.startsWith("/") ? spelled : `${base}/${spelled}`);
+    };
+    const tighten = resolve(protectivePathTargetOf(req));
+    const allow = resolve(declaredPathTargetOf(req));
+    if (tighten === undefined && allow === undefined)
         return undefined;
-    const hit = table.find((r) => eligiblePersisted(r, { tool: DIRECTORY_RULE_TOOL, cwd: ctx.root, sessionId: ctx.sessionId }) && directoryRuleAdmits(r, target));
-    return hit !== undefined ? persistedRuleHitOf([hit]) : undefined;
+    return persistedRuleHitOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}) }));
 }
 export function createPermissionRuleLanes(cfg) {
     const provider = cfg.provider;
@@ -103,10 +108,11 @@ export function createPermissionRuleLanes(cfg) {
         : undefined;
     const personal = provider.partitions.durable
         ? {
-            admits: async (req) => {
+            adjudicate: async (req) => {
                 if (anonymous && !cfg.localOwnerDeclared)
                     return undefined;
-                if (req.toolName !== PERSISTED_RULE_TOOL && req.toolName !== DIRECTORY_RULE_TOOL)
+                const grammar = ruleToolGrammarOf(req.toolName);
+                if (grammar === undefined)
                     return undefined;
                 let view;
                 try {
@@ -122,16 +128,16 @@ export function createPermissionRuleLanes(cfg) {
                 }
                 const table = view.rules;
                 const liveCwd = cfg.liveCwd();
-                if (req.toolName === DIRECTORY_RULE_TOOL) {
-                    return directoryRuleLaneAnswer(table, req.args, { root: cfg.root, sessionId: cfg.sessionId, liveCwd });
+                if (grammar === "path") {
+                    return pathRuleLaneAnswer(table, req, { root: cfg.root, sessionId: cfg.sessionId, liveCwd });
                 }
                 const command = req.args?.command;
                 if (typeof command !== "string")
                     return undefined;
                 const execCwd = liveCwd !== undefined ? { execCwd: liveCwd } : {};
-                const admitting = findAdmittingRule(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
-                if (admitting !== undefined)
-                    return persistedRuleHitOf(admitting);
+                const verdict = adjudicatePersistedRules(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
+                if (verdict !== undefined)
+                    return persistedRuleHitOf(verdict);
                 const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
                 return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
             },

package/dist/core/runner/prepare-gate-stations.js

@@ -123,7 +123,7 @@ export function prepareGateStations(input) {
                         ...(permissionRuleLane
                             ? {
                                 persistedRules: {
-                                    admits: permissionRuleLane.admits,
+                                    adjudicate: permissionRuleLane.adjudicate,
                                     onResolved: (info) => emitTrace(deps.tracer, () => ({
                                         kind: "permission.persisted_rule_allowed",
                                         version: 2,

package/dist/core/runner/prepare-safety-scan.js

@@ -1,7 +1,7 @@
 import { NAMESPACED_NAME_SHAPES } from "../protocol-table.js";
-import { handBandEffects } from "../tool-registry.js";
+import { engineCardTypes, handBandEffects } from "../tool-registry.js";
 import { TOOL_CONTRACT_MAX_CHARS, TOOL_WIRE_NAME_MAX_CHARS } from "../tool-face.js";
-import { schemaKeyBoundProblem } from "../tool-roster.js";
+import { callerCardIdOf, offendingResultCard, schemaKeyBoundProblem } from "../tool-roster.js";
 import { toolFaceProblem } from "./tool-face-overlay.js";
 import { OFFLOAD_TOOL_NAME } from "../tool-result-store.js";
 import { PRESENT_PLAN_TOOL_NAME, ENTER_PLAN_MODE_TOOL_NAME } from "../present-plan-tool.js";
@@ -52,6 +52,12 @@ export function prepareSafetyScan(input) {
                 e.code = "config.tool_face_invalid";
                 throw e;
             }
+            const foreignCard = offendingResultCard(t.renderHints, callerCardIdOf(t), engineCardTypes());
+            if (foreignCard !== undefined) {
+                const e = new Error(`Tool "${t.name}" declares a result card outside its own namespace: ${JSON.stringify(foreignCard)} (a caller card is "${callerCardIdOf(t)}/<card>"; engine cards and other contracts' namespaces are reserved).`);
+                e.code = "config.tool_face_invalid";
+                throw e;
+            }
         }
         if (t.name.includes("__")) {
             const e = new Error(`Tool name "${t.name}" is invalid: "__" is reserved for the engine's protocol tool namespaces (${NAMESPACED_NAME_SHAPES}) and must not appear in a caller tool name.`);

package/dist/core/runner/prepare-task.js

@@ -686,7 +686,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const preparedHolder = {};
         const { cacheBreakDetector, cacheFingerprint, promptOverheadTokens, readTaskFile, normalizeAttachmentPath, isDedupStubResult, recentlyReadFiles, onCompactionApplied, detectExternalChanges, listBackgroundTasks, centerCompactionCandidate, effectiveReadFaceObserved, effectiveReadDenyObserved } = prepareTurnWiring({ deps, systemPromptSeat, harnessTools, fpRef, model, epochArtifactDigestForSnapshot, promptProfile, fableMitigations, systemBlocks, thinking, spec, sessionId, turnSnapshotRef, promptManifest, charsPerToken, handsEnabled, executionEnv, attachmentRootCanonical, additionalRootsCanonical, additionalReadRootsCanonical, readDenyMatcher, resolvedReadFace, handsCwdRef, readFileStateForCheckpoint, denyNarrowingPolicy, abortController, hostTaskId, taskScope, buildAssembleInputs, centerAdoptionRef, harnessRef, epochDeclaredSections, carrierReadFace, readDenyAdditionsNormalized, preparedHolder });
         await onceLedger.settle(session, announcedListingsRef);
-        const buildPrepared = () => ({ harness, session, sessionId, runId, reminderMark, reminderDisclosureCounts, editedFilesSnapshot, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp, ...(a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, gateOutcomes, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(fileHistoryBoundary !== undefined ? { fileHistoryBoundary } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), ...(sealReadStateSeat !== undefined ? { sealReadStateSeat } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, pausedRef, suspendProgressRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, gateStopRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolRoster, toolRosterDeltas: rosterSeat, structuredProjector, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, microCompact, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, stopRequestedRef, announcedSnapshotRecovered: onceLedger.recovered, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(projectInstructionContent !== undefined ? { projectInstructionContent } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, runId, reminderMark, reminderDisclosureCounts, editedFilesSnapshot, taskRootPath: taskRootFinal, model, thinking, compModel: effectiveCompModel, mcp, ...(a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, gateOutcomes, batchHaltRef, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), ...(fileHistoryBoundary !== undefined ? { fileHistoryBoundary } : {}), ...(effectiveReadFaceObserved !== undefined ? { effectiveReadFace: effectiveReadFaceObserved } : {}), ...(effectiveReadDenyObserved !== undefined ? { effectiveReadDenyPatterns: effectiveReadDenyObserved } : {}), effectiveMemoryScopes: memoryEffectiveScopes, cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), ...(sealReadStateSeat !== undefined ? { sealReadStateSeat } : {}), denyNarrowingPolicy, ...(permissionRuleLane !== undefined ? { persistedRuleLane: permissionRuleLane } : {}), ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), ...(permissionRuleOrgLane !== undefined ? { permissionRuleOrg: permissionRuleOrgLane } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, deferDirectCall, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, pausedRef, suspendProgressRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, gateStopRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolRoster, toolRosterDeltas: rosterSeat, structuredProjector, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, microCompact, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, stopRequestedRef, announcedSnapshotRecovered: onceLedger.recovered, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(projectInstructionContent !== undefined ? { projectInstructionContent } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, gitStatusRef, listBackgroundTasks, hookIdentity, hookTimeoutMs, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         rollback.commit();
         const prepared = buildPrepared();
         preparedHolder.current = prepared;

package/dist/core/runner/resume-admission.d.ts

@@ -0,0 +1,53 @@
+/**
+ * design/393 S3 — the resume ladder's ADMISSION rung (E1) and the wake's shaping (E2), verbatim from
+ * `Runner.resumeStream`: the outcome container's domain, the one-read snapshots of the caller's config and
+ * the trusted internals bag, the store resolution, the row read and its terminal-status confirm, the
+ * same-process parent-constraint re-supply, then the wake pre-ladder (gate purity, pendingAction purity,
+ * the message's persist-time validation) and the one read of the outcome discriminant and the signal slot.
+ *
+ * Async (two store reads); every refusal throws a typed `CheckpointError` pre-CAS. It ends by handing what it
+ * admitted to the rung after it (`next`) in its LAST continuation — no suspension point between the
+ * registry read and the wake pre-ladder's first read of the row — and returns what that rung returns.
+ * The same seat shape the tool gate's fold uses to enter its lanes (gate-fold.ts `afterFold`).
+ */
+import { type Checkpoint, type CheckpointStore, type CheckpointToken, type PendingSteerEntry, type ResumeOutcome } from "../checkpoint-store.js";
+import type { InheritedGate, ResumeTaskConfig, RunInternals, RunnerDepsSeat } from "./contracts.js";
+/** What the admission rung was called with. */
+export interface ResumeAdmissionInput<R> {
+    /** borrowed-readonly — the checkpoint token the caller is redeeming. */
+    token: CheckpointToken;
+    /** borrowed-readonly — the caller's outcome object, read exactly where the driver read it (the container test,
+     *  the discriminant once, the wake message once); never stored, never handed on as itself. */
+    outcome: ResumeOutcome;
+    /** borrowed-readonly — the caller's config bag; snapshotted ONCE here (own enumerable fields), the snapshot is what
+     *  every later rung and the resumed leg read. */
+    taskConfig: ResumeTaskConfig;
+    /** borrowed-readonly — the trusted run-internals bag as the caller supplied it; shallow-snapshotted here, the
+     *  snapshot (with the parked chain re-supplied when the registry holds it) is what the ladder reads. */
+    internals: RunInternals | undefined;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE through the Runner (the store resolution reads `checkpointStore`); the one home of why it is a
+     *  seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the Runner's same-process parked-constraint registry; read for this token (never written here). */
+    parentConstraintRegistry: ReadonlyMap<CheckpointToken, NonNullable<InheritedGate["parentConstraints"]>>;
+    /** borrowed-readonly — the rung after admission, entered in this rung's last continuation with what it admitted. */
+    next: (admitted: ResumeAdmissionResult) => Promise<R>;
+}
+/** What admission established — the constants every later rung reads. */
+export interface ResumeAdmissionResult {
+    /** The caller's config, snapshotted once (own enumerable fields). */
+    config: ResumeTaskConfig;
+    /** The trusted internals snapshot, with the parked parent chain re-supplied when this Runner spawned the leg. */
+    internals: RunInternals | undefined;
+    /** The checkpoint store the row lives in. */
+    store: CheckpointStore;
+    /** The pending row, read once; a non-pending snapshot was refused before this result existed. */
+    cp: Checkpoint;
+    /** The ONE read of the outcome's discriminant. */
+    outcomeGate: ResumeOutcome["gate"];
+    /** The ONE read of the config's signal slot (`.aborted` stays a live read on this object). */
+    resumeSignal: AbortSignal | undefined;
+    /** The validated wake message (wake outcomes that carried one), never the caller's object. */
+    wakeMessage: Omit<PendingSteerEntry, "seq"> | undefined;
+}
+export declare function resumeAdmission<R>(input: ResumeAdmissionInput<R>): Promise<R>;

package/dist/core/runner/resume-admission.js

@@ -0,0 +1,83 @@
+import { CheckpointError, readPendingSteerQueue, resolveCheckpointStore, validatePendingSteer } from "../checkpoint-store.js";
+import { describeSuppliedValue } from "./decide-continuation.js";
+export async function resumeAdmission(input) {
+    const { token, outcome, taskConfig, runner, parentConstraintRegistry } = input;
+    let internals = input.internals;
+    if (outcome === null || typeof outcome !== "object") {
+        throw new CheckpointError("checkpoint.invalid_outcome", `resume outcome must be an object naming its gate (got ${outcome === null ? "null" : typeof outcome})`);
+    }
+    const config = typeof taskConfig === "object" && taskConfig !== null ? { ...taskConfig } : taskConfig;
+    internals = internals !== undefined ? { ...internals } : undefined;
+    const store = resolveCheckpointStore(config, runner.deps);
+    if (!store) {
+        throw new CheckpointError("checkpoint.not_found", "no CheckpointStore wired — cannot resume (set RunnerDeps.checkpointStore or taskConfig.checkpointStore)");
+    }
+    let cp = await store.get(token);
+    if (!cp) {
+        throw new CheckpointError("checkpoint.not_found", "no checkpoint found for the supplied token");
+    }
+    if (cp.status !== "pending") {
+        const live = await store.get(token);
+        if (live?.status === "pending") {
+            throw new CheckpointError("checkpoint.reopened_concurrently", "checkpoint changed concurrently (a resolve/reopen cycle landed between this resume's read of the row and its state check) — nothing was validated or executed; re-resume against the current state");
+        }
+        throw new CheckpointError("checkpoint.already_resolved", `checkpoint is ${describeSuppliedValue(live?.status ?? cp.status)} — the token is consumed, so this resume was neither validated nor executed (idempotent); a different outcome cannot redeem it`);
+    }
+    if ((internals?.inheritedGate?.parentConstraints?.length ?? 0) === 0) {
+        const parked = parentConstraintRegistry.get(token);
+        if (parked !== undefined) {
+            internals = {
+                ...(internals ?? {}),
+                inheritedGate: { ...(internals?.inheritedGate ?? {}), parentConstraints: parked },
+            };
+        }
+    }
+    let wakeMessage;
+    const outcomeGate = outcome.gate;
+    const resumeSignal = config.signal;
+    let suppliedMessage;
+    if (outcomeGate === "wake") {
+        suppliedMessage = outcome.message;
+        const gk = cp.gate.kind;
+        const decideEntry = gk === "human" || gk === "irreversible_ask"
+            ? 'a `policy_ask` outcome (decision allow/deny bound to the pending tool call)'
+            : gk === "needs_review"
+                ? 'a `dry_run_review` outcome (decision approve/reject)'
+                : gk === "plan_review"
+                    ? 'a `plan_review` outcome (decision approve/edit/reject)'
+                    : gk === "resource_limit"
+                        ? 'a `resource_limit` outcome (decision "continue")'
+                        : undefined;
+        if (gk !== "task_done") {
+            throw new CheckpointError("wake.gate_pending", `cannot wake: this checkpoint awaits a pending gate decision (gate "${gk}") — wake is not a decision ` +
+                `channel; resume it with ${decideEntry ?? "its own gate outcome"} instead`);
+        }
+        const pa = cp.pendingAction;
+        switch (pa.kind) {
+            case "task_done":
+                break;
+            case "tool_approval":
+            case "resource_limit":
+            case "review":
+            case "plan_review": {
+                throw new CheckpointError("wake.gate_pending", `cannot wake: this checkpoint still carries a pending gate-typed action (pendingAction "${pa.kind}" ` +
+                    `on a "${gk}" gate — inconsistent row) — wake is not a decision channel; resolve it through its ` +
+                    `own decide entry instead`);
+            }
+            default: {
+                const _exhaustive = pa;
+                void _exhaustive;
+                throw new CheckpointError("wake.gate_pending", `cannot wake: this checkpoint carries an unrecognized pendingAction kind "${pa.kind}" ` +
+                    `(newer-version row?) — fail-closed: wake only serves a pure park (pendingAction "task_done")`);
+            }
+        }
+        if (suppliedMessage !== undefined) {
+            wakeMessage = validatePendingSteer(suppliedMessage);
+        }
+        else if (readPendingSteerQueue(cp.state).length === 0) {
+            throw new CheckpointError("wake.nothing_to_deliver", "cannot wake: no message was supplied and the checkpoint holds no parked pendingSteer — an empty " +
+                "wake would burn the checkpoint on a blank continuation; supply `message` or park a steer first");
+        }
+    }
+    return await input.next({ config, internals, store, cp, outcomeGate, resumeSignal, wakeMessage });
+}

package/dist/core/runner/resume-apply.d.ts

@@ -0,0 +1,50 @@
+import { type Checkpoint, type PendingSteerEntry, type ResumeOutcome } from "../checkpoint-store.js";
+import type { ResumeRun, ResumeTaskConfig, RunInternals, RunnerDepsSeat } from "./contracts.js";
+export interface ResumeApplyInput<R> {
+    /** borrowed-readonly — the pending row (session id, pending call, inherited chain, ledger, hands cwd). */
+    cp: Checkpoint;
+    /** borrowed-readonly — the config snapshot (`hooks`, `taskId`, `signal`, the policy seats). */
+    config: ResumeTaskConfig;
+    /** borrowed-readonly — the internals snapshot (delegation identity facts for the screen's envelope). */
+    internals: RunInternals | undefined;
+    /** borrowed-readonly — the ONE read of the outcome discriminant. */
+    outcomeGate: ResumeOutcome["gate"];
+    /** borrowed-readonly — the validated wake message the screen judges. */
+    wakeMessage: Omit<PendingSteerEntry, "seq"> | undefined;
+    /** borrowed-readonly — the ONE signal read from admission; the screen and the edit legs are bounded by it. */
+    resumeSignal: AbortSignal | undefined;
+    /** borrowed-readonly — the window verdict to re-assert after the screen's await (undefined when unarmed). */
+    recheckGovernanceWindow: (() => Promise<void>) | undefined;
+    /** borrowed-readonly — the approval lane's twin (its edit is what the rechecks judge; the settlement is minted onto a copy). */
+    plainPolicyOutcome: Extract<ResumeOutcome, {
+        gate: "policy_ask";
+    }> | undefined;
+    /** borrowed-readonly — the review lane's twin. */
+    plainReviewOutcome: Extract<ResumeOutcome, {
+        gate: "plan_review" | "dry_run_review";
+    }> | undefined;
+    /** borrowed-readonly — the tool-less park lanes' twin. */
+    plainParkOutcome: Extract<ResumeOutcome, {
+        gate: "wake" | "resource_limit";
+    }> | undefined;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE through the Runner (reads `hooks`, `onError`, `lockedConfig`, `basePolicyForResumeEdit`, `toolPolicy` — the last three AFTER this rung's awaits); the one home of why it is a
+     *  seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-readonly — the orchestrator's delegation-facts fold (a lane may not name the orchestrator; the driver hands it in). */
+    effectiveDelegationFacts: (internals: Pick<RunInternals, "isDelegatedChild" | "insideFork"> | undefined, seedIsDelegatedChild: boolean | undefined) => {
+        isDelegatedChild: boolean;
+    };
+    /** borrowed-readonly — the rung after apply, entered in this rung's last continuation. */
+    next: (applied: ResumeApplyResult) => Promise<R>;
+}
+export interface ResumeApplyResult {
+    /** The screen's `additionalContext` for the wake message, when a screen ran and supplied one. */
+    wakeHookContext: string | undefined;
+    /** The approval lane's twin WITH its minted settlement record (undefined on every other lane). */
+    plainPolicyOutcome: Extract<ResumeOutcome, {
+        gate: "policy_ask";
+    }> | undefined;
+    /** The twin the store persists and the resumed leg reads — exactly one lane captured it. */
+    outcomeForStore: ResumeRun["outcome"];
+}
+export declare function resumeApply<R>(input: ResumeApplyInput<R>): Promise<R>;

package/dist/core/runner/resume-apply.js

@@ -0,0 +1,184 @@
+import { snapshotActorAssertion } from "../../internal/llm.js";
+import { isAskOrigin } from "../ask-origin.js";
+import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
+import { CheckpointError, remainingBudgetMicroUsd } from "../checkpoint-store.js";
+import { cloneObserverInput, mintHookInvocationIdentity, resolveHookTimeoutMs, runHookSeat } from "../hooks.js";
+import { checkToolPolicyProjection, refuseOutOfContractDecision } from "../tool-policy.js";
+import { callFaceSeat, parkedCallFaceOf } from "../tool-roster.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+import { deepJsonEqual, describeSuppliedValue } from "./decide-continuation.js";
+import { mintGateOutcome } from "./gate-exit.js";
+export async function resumeApply(input) {
+    const { cp, config, internals, outcomeGate, wakeMessage, resumeSignal, recheckGovernanceWindow, plainReviewOutcome, plainParkOutcome, runner, effectiveDelegationFacts } = input;
+    let plainPolicyOutcome = input.plainPolicyOutcome;
+    let wakeHookContext;
+    if (outcomeGate === "wake" && wakeMessage !== undefined) {
+        const resumeScreenHooks = config.hooks ?? runner.deps.hooks;
+        const screen = resumeScreenHooks?.userPromptSubmit;
+        if (screen !== undefined && resumeSignal?.aborted !== true) {
+            const screenedMessage = wakeMessage;
+            const identity = mintHookInvocationIdentity({
+                sessionId: cp.sessionId,
+                taskId: config.taskId ?? cp.sessionId,
+                legKind: "resume",
+                isDelegatedChild: effectiveDelegationFacts(internals, cp.state.isDelegatedChild).isDelegatedChild,
+                ...(internals?.insideFork === true ? { insideFork: true } : {}),
+                ...(internals?.agentName !== undefined ? { agentName: internals.agentName } : {}),
+                ...(internals?.parentToolCallId !== undefined ? { parentToolCallId: internals.parentToolCallId } : {}),
+            });
+            const screenTimeoutMs = resolveHookTimeoutMs(resumeScreenHooks?.timeoutMs, (badErr) => {
+                try {
+                    runner.deps.onError?.(badErr instanceof Error ? badErr : new Error(String(badErr)), { phase: "hook", sessionId: cp.sessionId });
+                }
+                catch {
+                }
+            }, resumeScreenHooks);
+            let decision;
+            try {
+                const seat = await runHookSeat("userPromptSubmit", { timeoutMs: screenTimeoutMs, ...(resumeSignal !== undefined ? { signal: resumeSignal } : {}), abortEnds: true }, (sig) => screen(screenedMessage.text, {
+                    identity,
+                    signal: sig,
+                    source: "resume_message",
+                    ...(screenedMessage.inputId !== undefined ? { inputId: screenedMessage.inputId } : {}),
+                    ...(screenedMessage.actor !== undefined ? { actor: snapshotActorAssertion(screenedMessage.actor) } : {}),
+                }));
+                if (seat.expired) {
+                    throw new CheckpointError("steering.blocked_by_hook", seat.cause === "timeout"
+                        ? `the deployment's userPromptSubmit hook did not answer within its ${screenTimeoutMs}ms bound while screening this wake message; the resume was refused (fail-closed) and the checkpoint stays pending`
+                        : `the resume was cancelled while the deployment's userPromptSubmit hook was still screening this wake message; the checkpoint stays pending`);
+                }
+                decision = seat.value;
+            }
+            catch (hookErr) {
+                if (hookErr instanceof CheckpointError)
+                    throw hookErr;
+                const err = hookErr instanceof Error ? hookErr : new Error(String(hookErr));
+                try {
+                    runner.deps.onError?.(err, { phase: "hook", sessionId: cp.sessionId });
+                }
+                catch {
+                }
+                throw new CheckpointError("steering.blocked_by_hook", `the deployment's userPromptSubmit hook crashed while screening this wake message (${inlineUntrusted(err.message)}); the resume was refused (fail-closed) and the checkpoint stays pending`);
+            }
+            if (decision?.block !== undefined && decision.block !== "") {
+                throw new CheckpointError("steering.blocked_by_hook", `the deployment's userPromptSubmit hook blocked this wake message: ${inlineUntrusted(decision.block)}`);
+            }
+            if (decision?.additionalContext !== undefined && decision.additionalContext !== "") {
+                wakeHookContext = decision.additionalContext;
+            }
+            if (recheckGovernanceWindow !== undefined)
+                await recheckGovernanceWindow();
+        }
+    }
+    if (plainPolicyOutcome !== undefined &&
+        plainPolicyOutcome.decision === "allow" &&
+        plainPolicyOutcome.updatedInput !== undefined &&
+        cp.pendingAction.kind === "tool_approval" &&
+        cp.pendingAction.toolName !== ASK_USER_QUESTION_TOOL_NAME) {
+        const editedArgs = plainPolicyOutcome.updatedInput;
+        const editBudget = {
+            resourceRemainingMicroUsd: remainingBudgetMicroUsd(cp.resourceLedger),
+            resourceSpentMicroUsd: cp.resourceLedger?.spentMicroUsd ?? 0,
+            suspendCount: cp.suspendCount ?? 0,
+        };
+        const editedReq = {
+            toolName: cp.pendingAction.toolName,
+            args: editedArgs,
+            toolCallId: cp.pendingAction.toolCallId,
+            budget: editBudget,
+            ...callFaceSeat(parkedCallFaceOf(cp.pendingAction)),
+            ...(cp.state.handsCwd !== undefined ? { cwd: cp.state.handsCwd } : {}),
+        };
+        const editSignal = config.signal;
+        const raceEditAbort = async (p) => {
+            if (editSignal === undefined)
+                return p;
+            if (editSignal.aborted) {
+                throw new CheckpointError("checkpoint.resume_aborted", "the resume was aborted while re-adjudicating the approver's edit — the checkpoint stays pending and is resumable with a live signal");
+            }
+            return new Promise((resolve, reject) => {
+                const onAbort = () => reject(new CheckpointError("checkpoint.resume_aborted", "the resume was aborted while re-adjudicating the approver's edit — the checkpoint stays pending and is resumable with a live signal"));
+                editSignal.addEventListener("abort", onAbort, { once: true });
+                p.then((v) => { editSignal.removeEventListener("abort", onAbort); resolve(v); }, (e) => { editSignal.removeEventListener("abort", onAbort); reject(e); });
+            });
+        };
+        const ig = cp.state.inheritedGate;
+        if (ig?.requiresParentConstraint === true) {
+            const chain = ig.constraintChain;
+            const unprojectable = chain === undefined
+                ? "the checkpoint predates the frozen projection chain (no constraintChain recorded)"
+                : chain.some((e) => "opaque" in e)
+                    ? "the inherited chain carries an OPAQUE layer (no projection exported)"
+                    : chain.some((e) => !("opaque" in e) && e.requiresLiveRemainder)
+                        ? "an inherited chain layer declares a live remainder beyond its projection"
+                        : undefined;
+            if (unprojectable !== undefined) {
+                throw new CheckpointError("resume.constraint_unprojectable", `the approver EDITED this call's input, but the inherited ancestor chain cannot re-adjudicate the edit statically: ${unprojectable}. ` +
+                    "Refusing the edited resume pre-CAS (the checkpoint stays pending and remains decidable) — approve the shown input as-is, deny it, " +
+                    "or re-issue the edited action as a fresh call so the full live chain adjudicates it");
+            }
+            for (const entry of chain) {
+                const denied = checkToolPolicyProjection(entry, editedReq);
+                if (denied !== undefined) {
+                    throw new CheckpointError("resume.constraint_rejected", `the approver EDITED this call's input and a FROZEN inherited ancestor constraint denies the edited args${denied.message ? `: ${denied.message}` : ""}. ` +
+                        "Refused pre-CAS (fresh-redecision semantics: the checkpoint stays pending and the same token remains decidable — approve as shown, deny, or edit differently)");
+                }
+            }
+        }
+        const toolPolicyLocked = runner.deps.lockedConfig?.keys?.includes("toolPolicy") === true;
+        const editBasePolicy = toolPolicyLocked
+            ? (runner.deps.basePolicyForResumeEdit ?? runner.deps.toolPolicy)
+            : (config.basePolicyForResumeEdit ?? runner.deps.basePolicyForResumeEdit ?? config.toolPolicy ?? runner.deps.toolPolicy);
+        if (editBasePolicy !== undefined) {
+            let rechecked;
+            try {
+                rechecked = refuseOutOfContractDecision(await raceEditAbort(Promise.resolve(editBasePolicy.check(editedReq, editSignal))));
+            }
+            catch (err) {
+                if (err instanceof CheckpointError)
+                    throw err;
+                rechecked = { action: "deny", message: `the resume-edit policy re-check errored: ${err instanceof Error ? err.message : String(err)}` };
+            }
+            if (rechecked.action === "deny") {
+                throw new CheckpointError("resume.constraint_rejected", `the approver EDITED this call's input and the deployment's resume-edit policy denies the edited args${rechecked.message ? `: ${rechecked.message}` : ""}. ` +
+                    "Refused pre-CAS (the checkpoint stays pending and remains decidable)");
+            }
+            if (rechecked.updatedInput !== undefined && !deepJsonEqual(rechecked.updatedInput, editedArgs)) {
+                throw new CheckpointError("resume.constraint_rejected", `the deployment's resume-edit policy REWROTE the approver's edited args to a different value than was approved — the durable resume cannot execute either the un-adjudicated edit or an unapproved rewrite; ` +
+                    `refused pre-CAS (the checkpoint stays pending); re-submit the edited action so the rewrite is adjudicated and approved synchronously`);
+            }
+        }
+        const resumeHooks = config.hooks ?? runner.deps.hooks;
+        if (resumeHooks?.preToolUse !== undefined && resumeHooks.preToolUseObservational === true) {
+            try {
+                await raceEditAbort(Promise.resolve(resumeHooks.preToolUse(cp.pendingAction.toolName, cloneObserverInput(editedArgs), {
+                    toolCallId: cp.pendingAction.toolCallId,
+                    toolName: cp.pendingAction.toolName,
+                })));
+            }
+            catch (err) {
+                if (err instanceof CheckpointError)
+                    throw err;
+                throw new CheckpointError("resume.constraint_rejected", `the declared-observational PreToolUse face threw while observing the approver's edited args (${err instanceof Error ? err.message : String(err)}) — ` +
+                    "refused fail-closed pre-CAS (the checkpoint stays pending and remains decidable)");
+            }
+        }
+    }
+    if (plainPolicyOutcome !== undefined) {
+        const parkedOrigin = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.origin : undefined;
+        if (!isAskOrigin(parkedOrigin)) {
+            throw new CheckpointError("checkpoint.unsupported_version", "this checkpoint's pending approval carries no origin word (a row minted before the ask's origin was persisted on the park) — its settlement cannot be recorded; the checkpoint stays pending", { reason: "origin_missing" });
+        }
+        const facts = plainPolicyOutcome.hostDecision;
+        const approverCell = facts.approver !== undefined ? { approver: facts.approver } : {};
+        const settlement = facts.decidedBy === "sla_timeout"
+            ? { kind: "park_sla_expired", who: { party: "host", ...approverCell }, when: Date.now() }
+            : { kind: plainPolicyOutcome.decision === "allow" ? "human_allowed" : "human_refused", who: { party: "person", ...approverCell }, when: Date.now(), ...(plainPolicyOutcome.decision === "deny" && plainPolicyOutcome.reason !== undefined ? { note: plainPolicyOutcome.reason } : {}) };
+        plainPolicyOutcome = { ...plainPolicyOutcome, gateOutcome: mintGateOutcome({ ...(plainPolicyOutcome.decision === "deny" ? { deniedBy: "ask_resolution" } : {}), settled: { settlement, origin: parkedOrigin } }) };
+    }
+    const outcomeForStore = plainPolicyOutcome ?? plainReviewOutcome ?? plainParkOutcome;
+    if (outcomeForStore === undefined) {
+        throw new CheckpointError("checkpoint.invalid_outcome", `resume outcome (gate "${describeSuppliedValue(outcomeGate)}") matched the checkpoint gate but no lane captured it — refusing pre-CAS rather than passing the caller's live object to the store and the resumed run`);
+    }
+    return await input.next({ wakeHookContext, plainPolicyOutcome, outcomeForStore });
+}

package/dist/core/runner/resume-checkpoint-screen.d.ts

@@ -0,0 +1,18 @@
+import { type Checkpoint } from "../checkpoint-store.js";
+import type { RunInternals, RunnerDepsSeat } from "./contracts.js";
+export interface ResumeCheckpointScreenInput {
+    /** borrowed-readonly — the pending row; every invariant is judged on its persisted fields. */
+    cp: Checkpoint;
+    /** borrowed-readonly — the ONE signal read from admission; `.aborted` is read live here. */
+    resumeSignal: AbortSignal | undefined;
+    /** borrowed-readonly — the internals snapshot (the re-supplied chain, the requested cwd). */
+    internals: RunInternals | undefined;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE through the Runner (reads `permissionRuleStore` and `executionEnvFactory`); the one home of why it is a
+     *  seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+}
+export interface ResumeCheckpointScreenResult {
+    /** The internals the resumed leg is handed: the validated chain frozen at the array level (entries by reference). */
+    resumeInternals: RunInternals | undefined;
+}
+export declare function resumeCheckpointScreen(input: ResumeCheckpointScreenInput): ResumeCheckpointScreenResult;