@sema-agent/core 7.8.0 → 7.9.1

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;

package/dist/core/runner/resume-checkpoint-screen.js

@@ -0,0 +1,108 @@
+import { persistedReadDenyEntryProblem } from "../../tools/fs/read-deny.js";
+import { isAskOrigin } from "../ask-origin.js";
+import { CheckpointError, checkpointVersionOf, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, realApprovalOrgFact } from "../checkpoint-store.js";
+import { constraintChainDigest, constraintChainEntryOfSuppliedLayer } from "../tool-policy.js";
+export function resumeCheckpointScreen(input) {
+    const { cp, resumeSignal, internals, runner } = input;
+    if (checkpointVersionOf(cp) > MAX_SUPPORTED_CHECKPOINT_VERSION) {
+        throw new CheckpointError("checkpoint.unsupported_version", `checkpoint version ${checkpointVersionOf(cp)} is newer than this worker supports (max ${MAX_SUPPORTED_CHECKPOINT_VERSION})`, { reason: "version_newer" });
+    }
+    const preCasGateBit = cp.gate.kind === "irreversible_ask" ? cp.gate.realApproval : undefined;
+    const preCasBitWellFormed = preCasGateBit !== undefined && typeof preCasGateBit === "object" && isAskOrigin(preCasGateBit.origin);
+    const faceSaysGoverned = (cp.state.readFace?.realApproval) === true;
+    const preCasBitViolation = checkpointVersionOf(cp) === REAL_APPROVAL_CHECKPOINT_VERSION
+        ? !preCasBitWellFormed
+        : checkpointVersionOf(cp) < REAL_APPROVAL_CHECKPOINT_VERSION
+            ? preCasGateBit !== undefined
+            : faceSaysGoverned
+                ? !preCasBitWellFormed
+                : preCasGateBit !== undefined && !preCasBitWellFormed;
+    if (preCasBitViolation) {
+        throw new CheckpointError("checkpoint.invalid_outcome", checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION
+            ? `a v${checkpointVersionOf(cp)} checkpoint's realApproval gate bit must be well-formed (origin a member of the closed ask-origin set)${checkpointVersionOf(cp) === REAL_APPROVAL_CHECKPOINT_VERSION ? " and present on an irreversible_ask gate" : ""} — this row's is not; refusing to resume a damaged real-approval row (corruption / downgrade guard), the checkpoint stays pending`
+            : `a v${checkpointVersionOf(cp)} checkpoint carries a realApproval gate bit no release of that version ever minted — refusing to honor a fabricated origin (corruption / forgery guard), the checkpoint stays pending`, { reason: checkpointVersionOf(cp) >= REAL_APPROVAL_CHECKPOINT_VERSION ? "real_approval_damaged" : "real_approval_forged" });
+    }
+    {
+        const faceSectionRaw = cp.state.readFace;
+        const faceCandidate = faceSectionRaw !== undefined && typeof faceSectionRaw === "object" && faceSectionRaw !== null
+            ? faceSectionRaw
+            : undefined;
+        const faceWellFormed = faceCandidate !== undefined &&
+            (faceCandidate.face === "open" || faceCandidate.face === "roots") &&
+            (faceCandidate.realApproval === undefined || faceCandidate.realApproval === true) &&
+            (faceCandidate.denyEntries === undefined ||
+                (Array.isArray(faceCandidate.denyEntries) &&
+                    faceCandidate.denyEntries.every((e) => persistedReadDenyEntryProblem(e) === null)));
+        if (checkpointVersionOf(cp) >= FACE_CHECKPOINT_VERSION ? !faceWellFormed : faceSectionRaw !== undefined) {
+            throw new CheckpointError("checkpoint.invalid_outcome", checkpointVersionOf(cp) >= FACE_CHECKPOINT_VERSION
+                ? `a v${checkpointVersionOf(cp)} checkpoint must carry a well-formed read-face section (state.readFace) — this row's is missing or malformed; refusing to resume a damaged read-face row (corruption / downgrade guard), the checkpoint stays pending`
+                : `a v${checkpointVersionOf(cp)} checkpoint carries a read-face section no release of that version ever minted — refusing to honor a fabricated read-face state (corruption / forgery guard), the checkpoint stays pending`, { reason: checkpointVersionOf(cp) >= FACE_CHECKPOINT_VERSION ? "read_face_damaged" : "read_face_forged" });
+        }
+    }
+    if (realApprovalOrgFact(preCasGateBit) !== undefined && runner.deps.permissionRuleStore?.partitions.org !== true) {
+        throw new CheckpointError("checkpoint.unsupported_version", `this checkpoint's approval was minted under organization governance (org ${String(realApprovalOrgFact(preCasGateBit))}, routed as ${String(preCasGateBit?.origin)}) and this worker has no org adjudication wiring (its permission-rule store carries no org partition) — a governed approval may only be redeemed where governance can be enforced; the checkpoint stays pending, resume it on an org-wired worker`, { reason: "governed_unwired" });
+    }
+    const retiredWalltimeTotal = cp.resourceLedger?.totalWalltimeSec;
+    if (retiredWalltimeTotal !== undefined) {
+        throw new CheckpointError("checkpoint.walltime_axis_retired", "this checkpoint's ledger carries a cross-slice WALL-CLOCK allocation (resourceLedger.totalWalltimeSec), an axis this engine version retired — " +
+            "resuming here would run the leg with that ceiling unenforced. Rejected pre-CAS (the checkpoint stays pending): finish it on a worker of the " +
+            "previous release, or start a fresh task bounded by resourceSuspend.totalTokens / totalBudgetUsd.");
+    }
+    if (resumeSignal?.aborted === true && cp.status === "pending") {
+        throw new CheckpointError("checkpoint.resume_aborted", "the resume was handed an ALREADY-ABORTED signal — refusing to consume the approval on a leg that cannot run it (the checkpoint stays pending and is resumable with a live signal)");
+    }
+    if (cp.state.workspaceHandle !== undefined && runner.deps.executionEnvFactory === undefined) {
+        throw new CheckpointError("checkpoint.unsupported_version", "checkpoint has a remote workspaceHandle but no RunnerDeps.executionEnvFactory is wired to rebuild the env", { reason: "env_factory_missing" });
+    }
+    if (cp.state.workspaceHandle !== undefined && internals?.requestedCwd !== undefined) {
+        throw new CheckpointError("checkpoint.cwd_conflicts_restore", `internals.requestedCwd ("${internals.requestedCwd}") cannot be combined with a checkpoint workspace restore — ` +
+            "the restored workspace's own mount path is authoritative for the task root. Drop requestedCwd on resume legs " +
+            "(the checkpoint stays pending and is resumable without it).");
+    }
+    if (cp.state.inheritedGate?.requiresParentConstraint === true) {
+        const supplied = internals?.inheritedGate?.parentConstraints?.length ?? 0;
+        if (supplied === 0) {
+            throw new CheckpointError("resume.parent_constraint_missing", "this checkpoint's task ran under inherited parent-policy constraints (state.inheritedGate.requiresParentConstraint) " +
+                "— the live policy/onAsk closures cannot be persisted, so the resume must re-supply them via " +
+                "resumeStream(token, outcome, taskConfig, internals) with internals.inheritedGate.parentConstraints; " +
+                "rejected pre-CAS (the checkpoint stays pending) rather than silently dropping the ancestors' gate");
+        }
+        const expected = cp.state.inheritedGate.parentConstraintCount;
+        if (expected !== undefined && supplied !== expected) {
+            throw new CheckpointError("resume.parent_constraint_mismatch", `re-supplied ${supplied} parent constraint(s) but the checkpoint recorded ${expected} — a partial/mismatched ` +
+                "re-supply would run the resumed leg under a different ancestor chain than it suspended with; " +
+                "rejected pre-CAS (the checkpoint stays pending) — re-resume with the full original chain");
+        }
+        if (checkpointVersionOf(cp) >= F012_CHECKPOINT_VERSION &&
+            (cp.state.inheritedGate.constraintChain === undefined || cp.state.inheritedGate.constraintDigest === undefined)) {
+            throw new CheckpointError("checkpoint.invalid_outcome", `a v${checkpointVersionOf(cp)} checkpoint that requires parent constraints must carry BOTH the frozen constraintChain and its constraintDigest (they are minted in one write with the version stamp) — this row carries neither or only one; refusing to fall back to the count-only contract on a damaged row (corruption / downgrade guard), the checkpoint stays pending`, { reason: "constraint_chain_missing" });
+        }
+        const expectedDigest = cp.state.inheritedGate.constraintDigest;
+        if (expectedDigest !== undefined) {
+            const persistedChain = cp.state.inheritedGate.constraintChain;
+            if (persistedChain === undefined || constraintChainDigest(persistedChain) !== expectedDigest) {
+                throw new CheckpointError("resume.parent_constraint_mismatch", "the checkpoint's OWN recorded constraint chain does not match its recorded digest " +
+                    "(corrupt / inconsistently-minted row) — the frozen deny data the resume would execute is not the data the " +
+                    "digest authenticates; rejected pre-CAS (the checkpoint stays pending)");
+            }
+            const suppliedDigest = constraintChainDigest((internals?.inheritedGate?.parentConstraints ?? []).map((pc, i) => constraintChainEntryOfSuppliedLayer(pc, persistedChain[i])));
+            if (suppliedDigest !== expectedDigest) {
+                throw new CheckpointError("resume.parent_constraint_mismatch", "the re-supplied parent-constraint chain's projection content does not match what the checkpoint recorded " +
+                    `(recorded ${expectedDigest}, re-supplied ${suppliedDigest}) — a same-shape chain with different frozen ` +
+                    "deny data would run the resumed leg under a different ancestor gate than it suspended with; " +
+                    "rejected pre-CAS (the checkpoint stays pending) — re-resume with the original chain's policies " +
+                    "(including, when the row recorded one, the ancestor's auto-mode arming recipe verbatim)");
+            }
+        }
+    }
+    const resumeInternals = internals?.inheritedGate?.parentConstraints !== undefined
+        ? {
+            ...internals,
+            inheritedGate: {
+                ...internals.inheritedGate,
+                parentConstraints: Object.freeze(internals.inheritedGate.parentConstraints.map((e) => ({ ...e }))),
+            },
+        }
+        : internals;
+    return { resumeInternals };
+}

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

@@ -0,0 +1,32 @@
+/**
+ * design/393 S3 — the resume ladder's CLAIM rung (E10), verbatim from `Runner.resumeStream`: the atomic
+ * CAS (`claimTerminal` when the store provides it — one round trip carrying the loser's truth — else the
+ * two-step `resolve` + diagnostic read), the same-Runner claim mark around it, and the loss classification
+ * (`reopened_concurrently` for a live row whose rev moved, `already_resolved` for a consumed one, with the
+ * dead parked-constraint entry evicted). Winning is the SOLE trigger to execute the pending action.
+ *
+ * Async (the CAS). It ends by handing off to the driver's post-claim rung (`next`) in its LAST continuation
+ * — the post-consume hook fires on the tick the win was read — and returns what that rung returns.
+ */
+import { type Checkpoint, type CheckpointStore, type CheckpointToken } from "../checkpoint-store.js";
+import type { InheritedGate, ResumeRun } from "./contracts.js";
+export interface ResumeClaimInput<R> {
+    /** borrowed-readonly — the checkpoint token being claimed. */
+    token: CheckpointToken;
+    /** borrowed-readonly — the pending row (scope and the rev the ladder validated against). */
+    cp: Checkpoint;
+    /** borrowed-readonly — the store the CAS runs against. */
+    store: CheckpointStore;
+    /** borrowed-readonly — the twin the store persists as the resolved outcome. */
+    outcomeForStore: ResumeRun["outcome"];
+    /** borrowed-mutable — the Runner's same-Runner claim marks: opened with the resolve attempt, released on a loss. */
+    locallyClaimedTokens: Set<CheckpointToken>;
+    /** borrowed-mutable — the Runner's parked-constraint registry: a terminally consumed token's entry is evicted. */
+    parentConstraintRegistry: Map<CheckpointToken, NonNullable<InheritedGate["parentConstraints"]>>;
+    /** borrowed-readonly — the driver's post-claim rung, entered in this rung's last continuation. */
+    next: (claimed: ResumeClaimResult) => Promise<R>;
+}
+/** The claim's completion is its whole result: a lost CAS throws, so reaching `next` IS the win. */
+export interface ResumeClaimResult {
+}
+export declare function resumeClaim<R>(input: ResumeClaimInput<R>): Promise<R>;

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

@@ -0,0 +1,27 @@
+import { CheckpointError } from "../checkpoint-store.js";
+export async function resumeClaim(input) {
+    const { token, cp, store, outcomeForStore, locallyClaimedTokens, parentConstraintRegistry } = input;
+    locallyClaimedTokens.add(token);
+    let won;
+    let claimLossStatus;
+    if (store.claimTerminal !== undefined) {
+        const claim = await store.claimTerminal(token, cp.scope, { kind: "resolve", outcome: outcomeForStore, expect: { rev: cp.rev ?? 0 } });
+        won = claim.claimed;
+        if (!claim.claimed)
+            claimLossStatus = claim.current.status;
+    }
+    else {
+        won = await store.resolve(token, cp.scope, outcomeForStore, { rev: cp.rev ?? 0 });
+    }
+    if (!won)
+        locallyClaimedTokens.delete(token);
+    if (!won) {
+        const stillPending = claimLossStatus !== undefined ? claimLossStatus === "pending" : (await store.get(token))?.status === "pending";
+        if (stillPending) {
+            throw new CheckpointError("checkpoint.reopened_concurrently", "checkpoint changed concurrently (its revision advanced via a resolve/reopen cycle since this resume validated) — not executed; re-resume against the current state");
+        }
+        parentConstraintRegistry.delete(token);
+        throw new CheckpointError("checkpoint.already_resolved", "checkpoint already resolved or expired — not re-executed (idempotent)");
+    }
+    return await input.next({});
+}

package/dist/core/runner/resume-internals-and-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * design/393 S3 — the resume ladder's INTERNALS-AND-CONFIG rung (E7), verbatim from `Runner.resumeStream`:
+ * the locked-policy guard on the resume-edit seat, the principal and placement identity-continuity rungs,
+ * and the governance-window ENTRANCE check for a row that still owes a delivery.
+ *
+ * Synchronous by construction, with the ladder's ONE await at this rung handed back instead of taken: the
+ * window read is STARTED here (the same expression, on the same tick) and returned as `windowEntrance` for the
+ * driver to await exactly where the ladder always awaited it — an `async` wrapper would add a suspension point
+ * the ladder never had, on the path where no window is armed most of all. Same reason the forwarding drain is a
+ * synchronous predicate plus a Promise factory (prepare-run-refs.ts).
+ */
+import { type Checkpoint, type ResumeOutcome } from "../checkpoint-store.js";
+import type { ResumeTaskConfig, RunInternals, RunnerDepsSeat } from "./contracts.js";
+export interface ResumeInternalsAndConfigInput {
+    /** borrowed-readonly — the pending row (recorded principal, placement root, parked steers, background tasks). */
+    cp: Checkpoint;
+    /** borrowed-readonly — the config snapshot (`basePolicyForResumeEdit`, `principal`). */
+    config: ResumeTaskConfig;
+    /** borrowed-readonly — the internals snapshot (`placementRoot`). */
+    internals: RunInternals | undefined;
+    /** borrowed-readonly — the ONE read of the outcome discriminant (a bare resource_limit continue owes nothing). */
+    outcomeGate: ResumeOutcome["gate"];
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE through the Runner (reads `lockedConfig`, `usageWindowStore`, `usageWindows`); the one home of why it is a
+     *  seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+}
+export interface ResumeInternalsAndConfigResult {
+    /** The window verdict as a re-assertable closure (armed only when governance is active), for the rungs whose awaits sit inside the read→CAS window. */
+    recheckGovernanceWindow: (() => Promise<void>) | undefined;
+    /** The entrance check already in flight (started on this tick) — the driver awaits it where the ladder did; absent when governance is unarmed. */
+    windowEntrance: Promise<void> | undefined;
+}
+export declare function resumeInternalsAndConfig(input: ResumeInternalsAndConfigInput): ResumeInternalsAndConfigResult;

package/dist/core/runner/resume-internals-and-config.js

@@ -0,0 +1,50 @@
+import { CheckpointError, readPendingSteerQueue } from "../checkpoint-store.js";
+import { GLOBAL_USAGE_KEY, resolveUsageWindows, usageRetryAfterMs } from "../usage-window-store.js";
+import { placementValueOrAbsent } from "./checkpoint-scope.js";
+export function resumeInternalsAndConfig(input) {
+    const { cp, config, internals, outcomeGate, runner } = input;
+    let windowEntrance;
+    if (runner.deps.lockedConfig?.keys?.includes("toolPolicy") === true && config.basePolicyForResumeEdit !== undefined) {
+        throw new CheckpointError("checkpoint.invalid_outcome", "TaskSpec.basePolicyForResumeEdit is administratively locked by this deployment (locked key \"toolPolicy\") — a task-supplied " +
+            "resume-edit policy is refused pre-CAS (the checkpoint stays pending); remove the field or change the deployment's lock configuration");
+    }
+    let recheckGovernanceWindow;
+    {
+        const rowPrincipal = cp.principal || undefined;
+        const suppliedPrincipal = config.principal || undefined;
+        if (rowPrincipal !== undefined && suppliedPrincipal !== undefined && suppliedPrincipal !== rowPrincipal) {
+            throw new CheckpointError("resume.principal_mismatch", `the resume config carries principal ${JSON.stringify(suppliedPrincipal)} but this checkpoint was suspended under principal ${JSON.stringify(rowPrincipal)} — ` +
+                "running the resumed leg under a different identity would move its usage-ledger bucket, scope derivation and attribution; " +
+                "refused pre-CAS (the checkpoint stays pending): re-resume with the original principal, or omit the field to inherit the recorded one");
+        }
+        {
+            const recordedPlacementRoot = placementValueOrAbsent(cp.state.placementRootSessionId);
+            const suppliedPlacementRoot = placementValueOrAbsent(internals?.placementRoot);
+            if (recordedPlacementRoot !== undefined && suppliedPlacementRoot !== undefined && suppliedPlacementRoot !== recordedPlacementRoot) {
+                throw new CheckpointError("resume.placement_mismatch", `the resume supplied explicit placement root ${JSON.stringify(suppliedPlacementRoot)} but this checkpoint recorded placement root ${JSON.stringify(recordedPlacementRoot)} at suspend — ` +
+                    "resuming under a different placement fixed point would re-place the leg (and its descendants) on another target; " +
+                    "refused pre-CAS (the checkpoint stays pending): re-resume with the recorded root, or omit internals.placementRoot to inherit it");
+            }
+        }
+        const owesDelivery = outcomeGate !== "resource_limit" ||
+            readPendingSteerQueue(cp.state).length > 0 ||
+            (cp.state.runningBackgroundTasks?.length ?? 0) > 0;
+        const usageWindowStore = runner.deps.usageWindowStore;
+        if (owesDelivery && usageWindowStore !== undefined) {
+            const preCasWindows = resolveUsageWindows(runner.deps.usageWindows);
+            if (preCasWindows !== undefined && preCasWindows.length > 0) {
+                const ledgerKey = (suppliedPrincipal ?? rowPrincipal) || GLOBAL_USAGE_KEY;
+                const assertWindowOpen = async () => {
+                    const wait = usageRetryAfterMs(await usageWindowStore.read(ledgerKey, preCasWindows, Date.now()), preCasWindows);
+                    if (wait !== undefined) {
+                        throw new CheckpointError("resume.usage_window_exhausted", `a deployment usage window for ledger key ${JSON.stringify(ledgerKey)} is exhausted, and this checkpoint still owes a delivery a re-mint cannot carry — ` +
+                            `refused pre-CAS (nothing consumed, nothing unpinned): the same token and the same decision are redeemable once the window frees, in ${String(wait)}ms`, { retryAfterMs: wait });
+                    }
+                };
+                recheckGovernanceWindow = assertWindowOpen;
+                windowEntrance = assertWindowOpen();
+            }
+        }
+    }
+    return { recheckGovernanceWindow, windowEntrance };
+}

package/dist/core/runner/resume-policy-outcome.d.ts

@@ -0,0 +1,31 @@
+/**
+ * design/393 S3 — the resume ladder's APPROVAL-LANE capture and binding rung (E4), verbatim from
+ * `Runner.resumeStream`: on a human / irreversible_ask row every deployment-supplied field of the
+ * `policy_ask` decide is read exactly once into a plain twin (answer canonicalized, updatedInput cloned to the
+ * JSON domain, the decision word, the refused keys, the host's decision facts and attribution, the deny note),
+ * then the decision-action binding (boundCallId, boundInputHash by version), the env_failed replay guard and
+ * the content-ask answer binding. Synchronous; every refusal throws pre-CAS.
+ */
+import { type QuestionAnswer } from "../ask-question.js";
+import { type Checkpoint, type ResumeOutcome } from "../checkpoint-store.js";
+import type { ResumeTaskConfig, RunnerDepsSeat } from "./contracts.js";
+export interface ResumePolicyOutcomeInput {
+    /** borrowed-readonly — the pending row (the lane is keyed on the STORED gate kind; the binding reads its pending call). */
+    cp: Checkpoint;
+    /** borrowed-readonly — the caller's outcome; each policy field is read exactly once, into the twin. */
+    outcome: ResumeOutcome;
+    /** borrowed-readonly — the config snapshot; the answer binding reads its `onQuestion` face. */
+    config: ResumeTaskConfig;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE through the Runner (the answer binding falls back to `onQuestion`); the one home of why it is a
+     *  seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+}
+export interface ResumePolicyOutcomeResult {
+    /** The approval lane's plain twin (a human / irreversible_ask row), else undefined. */
+    plainPolicyOutcome: Extract<ResumeOutcome, {
+        gate: "policy_ask";
+    }> | undefined;
+    /** The decide's content-ask answer in canonical form (present only when one was carried). */
+    redeemedAnswer: QuestionAnswer | undefined;
+}
+export declare function resumePolicyOutcome(input: ResumePolicyOutcomeInput): ResumePolicyOutcomeResult;

package/dist/core/runner/resume-policy-outcome.js

@@ -0,0 +1,127 @@
+import { canonicalizeCapturedPlainData, classifyQuestionOutcome, isLiveQuestionFace } from "../ask-question.js";
+import { BINDING_CHECKPOINT_VERSION, CheckpointError, checkpointVersionOf, winnerFromOutcome } from "../checkpoint-store.js";
+import { screenApproverAttribution } from "../tool-policy.js";
+import { sanitizeUntrustedText } from "../untrusted-text.js";
+import { assertOutcomeText, describeSuppliedValue, pendingContentAskCallId, sameWinner } from "./decide-continuation.js";
+const REFUSED_DECIDE_KEYS = [
+    ["gateOutcome", "the settlement record is minted by core from the host's decision facts and the row's origin, never supplied"],
+    ["settledBy", 'a retired key — the host supplies decision FACTS as hostDecision{decidedBy: "person" | "sla_timeout", approver?} and core mints the settlement word from them'],
+    ["approver", "a retired key — the attribution rides the facts it belongs to, as hostDecision.approver"],
+];
+export function resumePolicyOutcome(input) {
+    const { cp, outcome, config, runner } = input;
+    let suppliedAnswer;
+    let redeemedAnswer;
+    let plainPolicyOutcome;
+    if (cp.gate.kind === "human" || cp.gate.kind === "irreversible_ask") {
+        const decide = outcome;
+        suppliedAnswer = decide.answer;
+        if (suppliedAnswer !== undefined) {
+            const reading = classifyQuestionOutcome(suppliedAnswer);
+            if (reading.shape !== "answered") {
+                throw new CheckpointError("checkpoint.invalid_outcome", "resume carried a content-ask `answer` that does not read as an answer (malformed, sparse, or not capturable as plain data) — " +
+                    "refusing pre-CAS rather than fabricating an empty human response; the checkpoint stays pending", { field: "answer" });
+            }
+            redeemedAnswer = reading.answer;
+        }
+        const updatedInputRaw = decide.updatedInput;
+        let updatedInput;
+        try {
+            updatedInput = updatedInputRaw === undefined ? undefined : structuredClone(updatedInputRaw);
+        }
+        catch {
+            throw new CheckpointError("checkpoint.invalid_outcome", "resume carried an `updatedInput` that could not be captured as plain data — refusing pre-CAS; the checkpoint stays pending");
+        }
+        if (Object.is(updatedInput, -0))
+            updatedInput = 0;
+        if (updatedInput !== undefined && !canonicalizeCapturedPlainData(updatedInput)) {
+            throw new CheckpointError("checkpoint.invalid_outcome", "resume carried an `updatedInput` outside the plain-JSON value domain (a Map/Set/Date/buffer, a sparse or expando-carrying array, a non-finite number, or a cycle) — " +
+                "such a value reads differently on the two sides of the durable store; refusing pre-CAS, the checkpoint stays pending");
+        }
+        const decision = decide.decision;
+        if (decision !== "allow" && decision !== "deny") {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume decision "${describeSuppliedValue(decision)}" is outside the policy_ask domain — a decide is exactly "allow" or "deny"; refusing pre-CAS, the checkpoint stays pending`);
+        }
+        for (const [key, why] of REFUSED_DECIDE_KEYS) {
+            if (Reflect.get(decide, key) !== undefined) {
+                throw new CheckpointError("checkpoint.invalid_outcome", `resume carries \`${key}\` — ${why}; refusing pre-CAS, the checkpoint stays pending`, { field: "hostDecision" });
+            }
+        }
+        const hostDecisionRaw = decide.hostDecision;
+        if (typeof hostDecisionRaw !== "object" || hostDecisionRaw === null) {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume carries no hostDecision — a policy_ask decide names who decided it ({ decidedBy: "person" | "sla_timeout", approver? }); refusing pre-CAS, the checkpoint stays pending`, { field: "hostDecision" });
+        }
+        const decidedBy = hostDecisionRaw.decidedBy;
+        if (decidedBy !== "person" && decidedBy !== "sla_timeout") {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume hostDecision.decidedBy "${describeSuppliedValue(decidedBy)}" is outside the closed set — it is exactly "person" or "sla_timeout"; refusing pre-CAS, the checkpoint stays pending`, { field: "hostDecision" });
+        }
+        if (decidedBy === "sla_timeout" && decision === "allow") {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume carries decision "allow" decided by "sla_timeout" — an elapsed SLA window cannot be what approved an action that EXECUTES; refusing pre-CAS, the checkpoint stays pending`, { field: "hostDecision" });
+        }
+        const attribution = screenApproverAttribution(hostDecisionRaw.approver);
+        if (attribution.defect !== undefined) {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume carries an approver attribution this engine refuses: ${attribution.defect}; refusing pre-CAS, the checkpoint stays pending`, { field: "approver" });
+        }
+        const reason = decide.reason;
+        assertOutcomeText(reason, "reason");
+        const approverCell = attribution.approver !== undefined ? { approver: attribution.approver } : {};
+        plainPolicyOutcome = {
+            gate: "policy_ask",
+            boundCallId: decide.boundCallId,
+            boundInputHash: decide.boundInputHash,
+            decision,
+            ...(updatedInput !== undefined ? { updatedInput } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+            ...(redeemedAnswer !== undefined ? { answer: redeemedAnswer } : {}),
+            hostDecision: { decidedBy, ...approverCell },
+        };
+        if (plainPolicyOutcome.decision === "deny" && plainPolicyOutcome.reason && sanitizeUntrustedText(plainPolicyOutcome.reason) !== plainPolicyOutcome.reason) {
+            throw new CheckpointError("checkpoint.invalid_outcome", "resume deny/reject reason must not contain a </system-reminder> tag");
+        }
+    }
+    if (plainPolicyOutcome !== undefined) {
+        const boundTo = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.toolCallId : undefined;
+        if (plainPolicyOutcome.boundCallId !== boundTo) {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume boundCallId "${plainPolicyOutcome.boundCallId}" does not match the checkpoint's pending tool call "${boundTo ?? "(none)"}" — the decision-action binding (design/80 D-1) failed; refusing to apply a decision bound to a different action`, { field: "boundCallId" });
+        }
+        const boundHash = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.boundInputHash : undefined;
+        if (boundHash !== undefined) {
+            if (plainPolicyOutcome.boundInputHash !== boundHash) {
+                throw new CheckpointError("checkpoint.invalid_outcome", "resume boundInputHash does not match the checkpoint's pending tool call input — the decision-action input binding (design/80 D-1 §2) failed; refusing to apply an approval bound to a different input (TOCTOU re-mint guard)", { field: "boundInputHash" });
+            }
+        }
+        else if (checkpointVersionOf(cp) >= BINDING_CHECKPOINT_VERSION) {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume of a binding-version (v${checkpointVersionOf(cp)}) checkpoint whose pending tool call has no persisted boundInputHash — refusing to resume an unbound binding-version checkpoint (corruption / downgrade guard)`);
+        }
+        if (cp.reopenReason === "env_failed") {
+            if (cp.resolvedOutcome === undefined) {
+                throw new CheckpointError("checkpoint.reopen_revote", "checkpoint was reopened after an env-restore failure (env_failed) but carries no persisted winner to replay — refusing to resume (inconsistent row, fail-closed)");
+            }
+            const incoming = winnerFromOutcome(plainPolicyOutcome);
+            const persistedWinner = (() => {
+                const w = cp.resolvedOutcome;
+                if (w?.answer === undefined)
+                    return w;
+                const reading = classifyQuestionOutcome(w.answer);
+                return reading.shape === "answered" ? { ...w, answer: reading.answer } : w;
+            })();
+            if (incoming === undefined || !sameWinner(incoming, persistedWinner)) {
+                throw new CheckpointError("checkpoint.reopen_revote", `this checkpoint was reopened after an env-restore failure (env_failed) — a re-resume is a system retry of the already-approved action, not a re-vote; the supplied decision must replay the persisted winner (boundCallId "${cp.resolvedOutcome.boundCallId}", decision "${cp.resolvedOutcome.decision}"), refusing a different decision`);
+            }
+        }
+        const contentAskCallId = pendingContentAskCallId(cp);
+        if (suppliedAnswer !== undefined && (contentAskCallId === undefined || plainPolicyOutcome.decision !== "allow")) {
+            throw new CheckpointError("checkpoint.invalid_outcome", contentAskCallId === undefined
+                ? "resume carried a content-ask `answer` but the checkpoint's pending call is not the reserved question tool — an answer has no consumer on a side-effecting tool's approval; refusing rather than dropping it silently"
+                : "resume carried a content-ask `answer` on a `deny` — a denial injects a refusal, never an answer; refusing rather than dropping it silently", { field: "answer" });
+        }
+        if (contentAskCallId !== undefined && plainPolicyOutcome.decision === "allow" && suppliedAnswer === undefined) {
+            if (!isLiveQuestionFace(config.onQuestion ?? runner.deps.onQuestion)) {
+                throw new CheckpointError("checkpoint.invalid_outcome", "resume approved a content-ask (the reserved question tool) without an `answer`, and this resume has no live answering face — " +
+                    'executing the question against nothing would hand the model a fabricated "no human is available" default while consuming the approval; ' +
+                    "re-resume with the operator's answer on the outcome (or deny it), the checkpoint stays pending", { field: "answer" });
+            }
+        }
+    }
+    return { plainPolicyOutcome, redeemedAnswer };
+}