@sema-agent/core 7.8.0 → 7.9.1

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;

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

@@ -0,0 +1,88 @@
+import { CheckpointError } from "../checkpoint-store.js";
+import { isGateKind, PAUSE_REGISTRY, resumeGateMatches } from "../pause-registry.js";
+import { sanitizeUntrustedText } from "../untrusted-text.js";
+import { assertOutcomeText, describeSuppliedValue } from "./decide-continuation.js";
+export function resumeReviewOutcome(input) {
+    const { cp, outcome, outcomeGate, wakeMessage } = input;
+    const gateMatch = isGateKind(cp.gate.kind) && resumeGateMatches(cp.gate.kind, outcomeGate);
+    if (!gateMatch) {
+        throw new CheckpointError("checkpoint.gate_mismatch", `resume outcome (gate "${describeSuppliedValue(outcomeGate)}") does not match checkpoint gate "${cp.gate.kind}" — resume serves ${Object.entries(PAUSE_REGISTRY)
+            .filter(([, row]) => !row.terminal)
+            .map(([k, row]) => `${k}/${row.resume}`)
+            .join(", ")}`);
+    }
+    let plainReviewOutcome;
+    if (cp.gate.kind === "plan_review") {
+        const decide = outcome;
+        const decision = decide.decision;
+        const editedPlan = decide.editedPlan;
+        const reason = decide.reason;
+        if (decision !== "approve" && decision !== "edit" && decision !== "reject") {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume decision "${describeSuppliedValue(decision)}" is outside the plan_review domain — a plan review is exactly "approve", "edit" or "reject"; refusing pre-CAS, the checkpoint stays pending`);
+        }
+        assertOutcomeText(editedPlan, "editedPlan");
+        assertOutcomeText(reason, "reason");
+        plainReviewOutcome = {
+            gate: "plan_review",
+            decision,
+            ...(editedPlan !== undefined ? { editedPlan } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+        };
+    }
+    else if (cp.gate.kind === "needs_review") {
+        const decide = outcome;
+        const decision = decide.decision;
+        const reason = decide.reason;
+        if (decision !== "approve" && decision !== "reject") {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume decision "${describeSuppliedValue(decision)}" is outside the dry_run_review domain — a dry-run review is exactly "approve" or "reject"; refusing pre-CAS, the checkpoint stays pending`);
+        }
+        assertOutcomeText(reason, "reason");
+        plainReviewOutcome = {
+            gate: "dry_run_review",
+            decision,
+            ...(reason !== undefined ? { reason } : {}),
+        };
+    }
+    if (plainReviewOutcome !== undefined) {
+        const reason = plainReviewOutcome.reason;
+        if (plainReviewOutcome.decision === "reject" && reason && sanitizeUntrustedText(reason) !== reason) {
+            throw new CheckpointError("checkpoint.invalid_outcome", "resume deny/reject reason must not contain a </system-reminder> tag");
+        }
+        const capturedPlan = plainReviewOutcome.gate === "plan_review" ? plainReviewOutcome.editedPlan : undefined;
+        if (plainReviewOutcome.decision === "edit" &&
+            capturedPlan &&
+            sanitizeUntrustedText(capturedPlan) !== capturedPlan) {
+            throw new CheckpointError("checkpoint.invalid_outcome", "resume editedPlan must not contain a </system-reminder> tag");
+        }
+        if (cp.reopenReason === "env_failed") {
+            const winner = cp.resolvedOutcome;
+            if (winner === undefined) {
+                throw new CheckpointError("checkpoint.reopen_revote", "review checkpoint was reopened after an env-restore failure (env_failed) but carries no persisted winner to replay — refusing to resume (inconsistent row, fail-closed)");
+            }
+            if (winner.decision !== plainReviewOutcome.decision) {
+                throw new CheckpointError("checkpoint.reopen_revote", `an env_failed reopen replays the ALREADY-RECORDED review decision ("${winner.decision}") — refusing a re-vote with a different decision ("${plainReviewOutcome.decision}")`);
+            }
+            if (winner.updatedInput !== capturedPlan) {
+                throw new CheckpointError("checkpoint.reopen_revote", "an env_failed reopen replays the ALREADY-RECORDED review decision — refusing a re-vote whose edited plan differs from the recorded one");
+            }
+            if (winner.reason !== undefined && winner.reason !== plainReviewOutcome.reason) {
+                throw new CheckpointError("checkpoint.reopen_revote", "an env_failed reopen replays the ALREADY-RECORDED review decision — refusing a re-vote whose reviewer note differs from the recorded one");
+            }
+        }
+    }
+    let plainParkOutcome;
+    if (outcomeGate === "wake") {
+        plainParkOutcome = {
+            gate: "wake",
+            ...(wakeMessage !== undefined ? { message: wakeMessage } : {}),
+        };
+    }
+    else if (outcomeGate === "resource_limit") {
+        const decision = outcome.decision;
+        if (decision !== "continue") {
+            throw new CheckpointError("checkpoint.invalid_outcome", `resume decision "${describeSuppliedValue(decision)}" is outside the resource_limit domain — a slice resume is exactly "continue"; refusing pre-CAS, the checkpoint stays pending`);
+        }
+        plainParkOutcome = { gate: "resource_limit", decision };
+    }
+    return { plainReviewOutcome, plainParkOutcome };
+}

package/dist/core/runner/run-harness-handlers.js

@@ -261,7 +261,7 @@ export function createHarnessHandlers(input) {
             toolName: event.toolName,
             ...(toolLabels.get(event.toolName) !== undefined ? { label: toolLabels.get(event.toolName) } : {}),
             isError: event.isError,
-            ...toolEndBodyFrom(event.result, event.isError, gate, prepared.abortController.signal.aborted ? gatedCallIdOf(prepared) : undefined),
+            ...toolEndBodyFrom(event.result, event.isError, prepared.structuredProjector, gate, prepared.abortController.signal.aborted ? gatedCallIdOf(prepared) : undefined),
             ...ident(),
         });
         announceWorkspaceMove();

package/dist/core/runner/runtask.d.ts

@@ -56,6 +56,9 @@ export declare class Runner implements RunnerSelfSeat {
      *  never a wrong destroy. */
     private readonly locallyClaimedTokens;
     private static readonly PARENT_CONSTRAINT_REGISTRY_CAP;
+    /** The lanes' LIVE view of `deps` ({@link RunnerDepsSeat}): a getter, never a captured object, because
+     *  `swapModels` replaces the object and a rung reading after its own await must see the replacement. */
+    private readonly depsSeat;
     constructor(deps: RunnerDeps);
     /** design/73 §1 v1 — fire `RunnerDeps.onTaskOutcome` through the single swallow-guarded chokepoint
      *  ({@link emitTaskOutcome}: mechanical-tier only, throwing sink never breaks the caller). Public so
@@ -227,6 +230,23 @@ export declare class Runner implements RunnerSelfSeat {
      *  authority, so constraint substitution here is outside the enforced threat model (the count check
      *  catches shape MISTAKES, not a untrusted trusted caller). */
     internals?: RunInternals): Promise<TaskStream>;
+    /**
+     * design/393 S3 — the resume decision ladder after admission (E3–E10), driving the eight `resume-*` lanes in
+     * the order the one-function ladder had: the review / park twins, the approval twin and its bindings, the
+     * checkpoint screen, the internals-and-config rungs (whose one window await is taken HERE, where the ladder
+     * took it), then the three async rungs after it — apply, preflight, claim — each entering the next in its own last
+     * continuation, and the post-claim hand-off to the resumed leg. Every rung throws its typed refusal pre-CAS;
+     * the first `return` is the leg's stream.
+     */
+    private resumeLadder;
+    /**
+     * design/393 S3 — the ladder's POST-CLAIM rung (E11), the driver's own: the post-consume hook, the answering
+     * face minted from the decide's answer, the resumed leg's spec (identity continuity, the existing-session
+     * requirement, the stripped pre-aborted preempt signal), the reopen compensation and the execution-record
+     * verb bound to the row, the two post-CAS abort re-checks, and the hand-off to `runTaskStream` with the plain
+     * twin. Entered in the claim rung's last continuation, so its first statement runs on the tick the win was read.
+     */
+    private resumeHandoff;
     /**
      * design/45 resume step: with the harness idle and the branch rewound to the suspension leaf, resolve
      * the gated tool call and close the rest of the suspended batch, all by appending `toolResult`s to the