@sema-agent/core 7.8.0 → 7.9.0

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 };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * design/393 S3 — the resume ladder's deployment PREFLIGHT rung (E9), verbatim from `Runner.resumeStream`:
+ * the LAST rung before the CAS. The deployment's `resumePreflight` screens the resume off the persisted row's
+ * facts under its own validated deadline; every non-answer arm refuses retry-later (the row stays pending);
+ * only an explicit, fully readable `terminal` verdict settles the row through the single-shot expire CAS
+ * (with the reap duty that win carries), and the window verdict is re-asserted after the hook's await.
+ *
+ * Async (the seat, the expire, the loss re-read, the bounded destroy). It ends by handing off to the rung
+ * after it (`next`) in its LAST continuation — the claim opens on the tick the preflight cleared — and
+ * returns what that rung returns.
+ */
+import { type Checkpoint, type CheckpointStore, type CheckpointToken } from "../checkpoint-store.js";
+import type { InheritedGate, RunnerDepsSeat, SuspendReap } from "./contracts.js";
+export interface ResumePreflightInput<R> {
+    /** borrowed-readonly — the checkpoint token (handed to the deployment and to the settling CAS). */
+    token: CheckpointToken;
+    /** borrowed-readonly — the pending row; the deployment reads its persisted facts, never the caller's bag. */
+    cp: Checkpoint;
+    /** borrowed-readonly — the ONE signal read from admission; the seat's wait is bounded by it. */
+    resumeSignal: AbortSignal | undefined;
+    /** borrowed-readonly — the window verdict to re-assert after the seat's await (undefined when unarmed). */
+    recheckGovernanceWindow: (() => Promise<void>) | undefined;
+    /** borrowed-readonly — the store the row lives in (the terminal arm's expire and its loss re-read). */
+    store: CheckpointStore;
+    /** borrowed-readonly — the Runner's deployment deps, read LIVE through the Runner (reads `resumePreflight`, `resumePreflightTimeoutMs`, `onError` (after the seat's await too) and is the seat's owner); the one home of why it is a
+     *  seat and not a captured object is {@link RunnerDepsSeat}. */
+    runner: RunnerDepsSeat;
+    /** borrowed-mutable — the Runner's same-Runner claim marks: opened with the expire attempt, released at the duty decision. */
+    locallyClaimedTokens: Set<CheckpointToken>;
+    /** borrowed-mutable — the Runner's parked-constraint registry: the token's entry is evicted when the terminal arm wins. */
+    parentConstraintRegistry: Map<CheckpointToken, NonNullable<InheritedGate["parentConstraints"]>>;
+    /** borrowed-mutable — the Runner's suspended-env reap handles: the winning terminal arm takes and destroys this token's. */
+    suspendedEnvReaps: Map<CheckpointToken, SuspendReap>;
+    /** borrowed-readonly — the rung after the preflight, entered in this rung's last continuation. */
+    next: (screened: ResumePreflightResult) => Promise<R>;
+}
+/** The preflight's completion is its whole result: every refusal throws, so reaching `next` IS the fact. */
+export interface ResumePreflightResult {
+}
+export declare function resumePreflight<R>(input: ResumePreflightInput<R>): Promise<R>;

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

@@ -0,0 +1,122 @@
+import { CheckpointError } from "../checkpoint-store.js";
+import { MAX_HOOK_TIMEOUT_MS, runHookSeat } from "../hooks.js";
+import { hasDestroy } from "../remote-env.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+import { describeSuppliedValue } from "./decide-continuation.js";
+import { settleTeardownLeg } from "./teardown-bounded.js";
+const RESUME_PREFLIGHT_DEFAULT_TIMEOUT_MS = 10_000;
+export async function resumePreflight(input) {
+    const { token, cp, resumeSignal, recheckGovernanceWindow, store, runner, locallyClaimedTokens, parentConstraintRegistry, suspendedEnvReaps } = input;
+    if (runner.deps.resumePreflight !== undefined) {
+        const preflight = runner.deps.resumePreflight;
+        const rawDeadline = runner.deps.resumePreflightTimeoutMs;
+        let preflightTimeoutMs = RESUME_PREFLIGHT_DEFAULT_TIMEOUT_MS;
+        if (rawDeadline !== undefined) {
+            if (typeof rawDeadline === "number" && Number.isFinite(rawDeadline) && rawDeadline > 0 && rawDeadline <= MAX_HOOK_TIMEOUT_MS) {
+                preflightTimeoutMs = rawDeadline;
+            }
+            else {
+                try {
+                    runner.deps.onError?.(new Error(`RunnerDeps.resumePreflightTimeoutMs is not a positive finite number within the seat ceiling of ${MAX_HOOK_TIMEOUT_MS}ms (got ${describeSuppliedValue(rawDeadline)}) — the resume preflight falls back to its own ${RESUME_PREFLIGHT_DEFAULT_TIMEOUT_MS}ms default`), { phase: "config", sessionId: cp.sessionId });
+                }
+                catch {
+                }
+            }
+        }
+        const info = {
+            token,
+            sessionId: cp.sessionId,
+            ...(cp.state.placementRootSessionId !== undefined ? { placementRootSessionId: cp.state.placementRootSessionId } : {}),
+            ...(cp.principal ? { principal: cp.principal } : {}),
+            ...(cp.state.workspaceHandle !== undefined ? { workspaceHandle: structuredClone(cp.state.workspaceHandle) } : {}),
+            gateKind: cp.gate.kind,
+        };
+        const refusalTail = "; the checkpoint stays pending and the same token is redeemable once the obstacle clears";
+        let verdict;
+        try {
+            const seat = await runHookSeat("resumePreflight", {
+                timeoutMs: preflightTimeoutMs,
+                ...(resumeSignal !== undefined ? { signal: resumeSignal } : {}),
+                abortEnds: true,
+                onBadTimeout: (badErr) => {
+                    try {
+                        runner.deps.onError?.(badErr instanceof Error ? badErr : new Error(String(badErr)), { phase: "hook", sessionId: cp.sessionId });
+                    }
+                    catch {
+                    }
+                },
+                owner: runner.deps,
+            }, (sig) => preflight(info, sig));
+            if (seat.expired) {
+                throw new CheckpointError("resume.preflight_rejected", seat.cause === "timeout"
+                    ? `the deployment's resumePreflight did not answer within its ${preflightTimeoutMs}ms deadline while screening this resume — refused fail-closed (retry-later arm)${refusalTail}`
+                    : `the resume was cancelled while the deployment's resumePreflight was still screening it — refused (retry-later arm)${refusalTail}`);
+            }
+            verdict = seat.value;
+        }
+        catch (preflightErr) {
+            if (preflightErr instanceof CheckpointError)
+                throw preflightErr;
+            const err = preflightErr instanceof Error ? preflightErr : new Error(String(preflightErr));
+            try {
+                runner.deps.onError?.(err, { phase: "hook", sessionId: cp.sessionId });
+            }
+            catch {
+            }
+            throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight crashed while screening this resume (${inlineUntrusted(err.message)}) — refused fail-closed (retry-later arm)${refusalTail}`);
+        }
+        const verdictOk = verdict !== null && typeof verdict === "object" ? verdict.ok : undefined;
+        if (verdictOk !== true) {
+            const bag = verdict !== null && typeof verdict === "object" ? verdict : undefined;
+            const disposition = bag?.disposition;
+            const suppliedMessage = bag?.message;
+            const retryAfterMs = bag?.retryAfterMs;
+            const readableMessage = typeof suppliedMessage === "string" && suppliedMessage !== "" ? suppliedMessage : undefined;
+            const said = readableMessage !== undefined ? `: ${inlineUntrusted(readableMessage)}` : " (no readable verdict — fail-closed)";
+            if (disposition === "terminal" && readableMessage !== undefined) {
+                locallyClaimedTokens.add(token);
+                let settled;
+                try {
+                    settled = await store.expire(token, cp.scope);
+                }
+                catch (expireErr) {
+                    locallyClaimedTokens.delete(token);
+                    throw expireErr;
+                }
+                if (!settled) {
+                    locallyClaimedTokens.delete(token);
+                    const live = await store.get(token);
+                    if (live?.status === "pending") {
+                        throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight ruled this resume PERMANENTLY blocked${said}, but the row moved under this refusal (a concurrent resolve/reopen cycle) — nothing was settled here; the row is pending again, re-resume against the current state (the preflight screens every attempt)`);
+                    }
+                    throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight ruled this resume PERMANENTLY blocked${said} — a concurrent actor had already settled the row (${describeSuppliedValue(live?.status ?? "consumed")}); nothing was settled by this refusal`);
+                }
+                parentConstraintRegistry.delete(token);
+                const terminalReap = suspendedEnvReaps.get(token);
+                suspendedEnvReaps.delete(token);
+                locallyClaimedTokens.delete(token);
+                if (terminalReap?.env !== undefined && hasDestroy(terminalReap.env)) {
+                    const terminalEnv = terminalReap.env;
+                    await settleTeardownLeg(() => terminalEnv.destroy(), "terminal-preflight env destroy", (envErr) => {
+                        try {
+                            runner.deps.onError?.(envErr, { phase: "config", sessionId: terminalReap.sessionId });
+                        }
+                        catch {
+                        }
+                    });
+                }
+                try {
+                    runner.deps.onError?.(new Error(`resumePreflight ruled this row PERMANENTLY blocked${said} — the row was settled terminally (expired) by this refusal's single-shot CAS (token no longer redeemable)`), { phase: "hook", sessionId: cp.sessionId });
+                }
+                catch {
+                }
+                throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight ruled this resume PERMANENTLY blocked${said} — the row was settled terminally (expired by this refusal's single-shot CAS); the token is not redeemable`);
+            }
+            const waitHint = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0 ? retryAfterMs : undefined;
+            throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight refused this resume${said}${refusalTail}${waitHint !== undefined ? ` (deployment wait hint: ${String(waitHint)}ms)` : ""}`, waitHint !== undefined ? { retryAfterMs: waitHint } : undefined);
+        }
+        if (recheckGovernanceWindow !== undefined)
+            await recheckGovernanceWindow();
+    }
+    return await input.next({});
+}

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

@@ -0,0 +1,30 @@
+/**
+ * design/393 S3 — the resume ladder's gate-match rung and the review / park TWINS (E3), verbatim from
+ * `Runner.resumeStream`: the outcome arm must match the persisted gate kind; a review-gate outcome
+ * (plan_review / dry_run_review) is captured into a plain twin with its domain and text-payload checks, the
+ * break-out-tag hygiene and the env_failed replay guard; the two tool-less park lanes (wake / resource_limit)
+ * get their twins too, so no lane hands the caller's object downstream. Synchronous; every refusal throws
+ * pre-CAS.
+ */
+import { type Checkpoint, type PendingSteerEntry, type ResumeOutcome } from "../checkpoint-store.js";
+export interface ResumeReviewOutcomeInput {
+    /** borrowed-readonly — the pending row (the lane is keyed on the STORED gate kind). */
+    cp: Checkpoint;
+    /** borrowed-readonly — the caller's outcome; each review field is read exactly once, into the twin. */
+    outcome: ResumeOutcome;
+    /** borrowed-readonly — the ONE read of the outcome discriminant, taken at admission. */
+    outcomeGate: ResumeOutcome["gate"];
+    /** borrowed-readonly — the validated wake message, carried into the wake twin. */
+    wakeMessage: Omit<PendingSteerEntry, "seq"> | undefined;
+}
+export interface ResumeReviewOutcomeResult {
+    /** The review lane's plain twin (a plan_review / needs_review row), else undefined. */
+    plainReviewOutcome: Extract<ResumeOutcome, {
+        gate: "plan_review" | "dry_run_review";
+    }> | undefined;
+    /** The tool-less park lanes' plain twin (a wake or a resource_limit continue), else undefined. */
+    plainParkOutcome: Extract<ResumeOutcome, {
+        gate: "wake" | "resource_limit";
+    }> | undefined;
+}
+export declare function resumeReviewOutcome(input: ResumeReviewOutcomeInput): ResumeReviewOutcomeResult;