@sema-agent/core 7.5.0 → 7.5.2

package/dist/core/runner/prepare-ask-lane.d.ts

@@ -0,0 +1,110 @@
+/**
+ * design/390 §1.2 M19 (ask lane) — prepareTask's IN-STREAM ASK LANE, verbatim from the driver's gate-machinery block:
+ * the per-call signal composition bound to this task's run signal, the abort-bound `adjudicate` wrapper (the budget
+ * snapshot and the live tracked cwd stamped onto every request), the approval-preview projection over the live roster,
+ * the `resolveAskBound` mint (the inherited-unavailable intercept, the duplicate-frame grant reuse, the human-review
+ * ledger, the bare-human-rejection record), the pre-wrapped deny observer and the hook-crash notifier. The three
+ * module-scope helpers only this segment called moved with it (the deny-observer factory, the preview sanitizer and
+ * resolver). The interface is the dependency list the segment had implicitly (design/238 R-1) — the closures below
+ * used to capture every seat here off the driver's scope.
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (every await lives inside the closures
+ * it builds, which run per tool call), so the phase adds no yield between the wiring-manifest station before it and
+ * the suspend saga after it (design/390 §1.5: a stretch with no await is extracted as a sync function). Read-stability
+ * of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * The lane exists exactly when the wiring-manifest phase's `gateMachineryActive` holds — the driver's `if` around the
+ * whole block became this phase's one early return (the block's other four phases key off the lane's presence), so
+ * the orchestrator grows no branch.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { AutoModeDenialTracker } from "../auto-mode.js";
+import { type Hooks } from "../hooks.js";
+import { type OnAsk, type ToolCallRequest, type ToolPolicy } from "../tool-policy.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import type { AskLane, Prepared } from "./contracts.js";
+import { consumeInheritedAskGrant } from "./inherited-ask-grants.js";
+import type { createRuleOffersOf } from "./permission-rule-lanes.js";
+export interface PrepareAskLaneInput {
+    /** borrowed-readonly — the wiring-manifest phase's ONE activation predicate; false ⇒ this phase builds nothing and
+     *  returns an absent lane. */
+    gateMachineryActive: boolean;
+    /** borrowed-readonly — prepare's abort seat; only `.signal` is read (composed into every per-call signal and bound
+     *  onto the deny observer). Never aborted here. */
+    abortController: {
+        readonly signal: AbortSignal;
+    };
+    /** borrowed-readonly — the policy chain's effective policy, or undefined (then no `adjudicate` wrapper is built and
+     *  the gate reads a missing policy as allow). Called at RUN time, per tool call, through the abort-bound wrapper. */
+    effectivePolicy: ToolPolicy | undefined;
+    /** borrowed-readonly — the per-leg-immutable durable budget snapshot stamped onto EVERY adjudicated request. Same
+     *  object every call; the policy cannot write it back. */
+    budgetSnapshot: NonNullable<ToolCallRequest["budget"]>;
+    /** borrowed-readonly — the hand's live tracked cwd, or undefined (hands-less). Read per call at RUN time (`current`),
+     *  never captured: the fs hand tools resolve their relative paths against this very ref. Not written here. */
+    handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the shared mount roster; read at RUN time by the approval-preview projection (alias-aware
+     *  lookup over whatever the roster holds when the ask is minted). Never mutated here. */
+    tools: AgentTool[];
+    /** borrowed-mutable — the inherited-unavailable marker set. Writer here: `resolveAskBound` consumes (`delete`) a
+     *  marked call at its fail-closed intercept; the policy-chain phase records, the gate station sweeps. */
+    inheritedUnavailableAsks: Set<string>;
+    /** borrowed-mutable — the duplicate-frame ask-grant record. Writer here: the grant-reuse consume half
+     *  (`consumeInheritedAskGrant`); the policy-chain phase records, the gate station sweeps. */
+    inheritedAskGrants: Parameters<typeof consumeInheritedAskGrant>[0];
+    /** borrowed-readonly — the run's own approver seat (spec over deps), or undefined: the resolve target, the
+     *  live-approver test the carry mint reads, and the grant-reuse identity law's approver. */
+    onAsk: OnAsk | undefined;
+    /** borrowed-mutable — the per-task human-review accumulator (`Prepared.humanReviewRef`). Writers here: every
+     *  synchronous resolve that a person actually judged (count / totalWaitMs / gates push); runtask adds the durable
+     *  resume latency. */
+    humanReviewRef: Prepared["humanReviewRef"];
+    /** borrowed-mutable — the bare-human-rejection sideband. Writer here: a `settledBy:"human"` deny with no note
+     *  (`add`); the gate station judges and sweeps it. */
+    humanBareRejections: Set<string>;
+    /** borrowed-readonly — the injectable wall clock every human-time observable reads (`Prepared.now`). */
+    now: () => number;
+    /** borrowed-readonly — the policy-chain phase's rule-offer factory (the suggestion members the ask mint threads). */
+    ruleOffersOf: ReturnType<typeof createRuleOffersOf>;
+    /** borrowed-readonly — the policy-chain phase's Runner-filled source identity (one factory, every ask mint site). */
+    askSourceIdentity: () => {
+        principal?: string;
+        sourceTaskId?: string;
+        fromSubagent?: true;
+        sourceAgentName?: string;
+        isDelegatedChild?: true;
+    };
+    /** borrowed-readonly — the policy-chain phase's per-tool risk-axes projection (`riskAxes` on the ask). */
+    riskAxesOf: (toolName: string) => {
+        riskAxes?: {
+            irreversible?: boolean;
+            egress?: boolean;
+        };
+    };
+    /** borrowed-mutable — the auto-mode denial tracker, or undefined. Writer here: the carry mint arms the auto-deny
+     *  window on it iff the seat about to be called is live (the tracker's one writer). */
+    autoModeDenialTracking: AutoModeDenialTracker | undefined;
+    /** borrowed-readonly — the REBOUND spec; only `taskId` is read (the late-settlement observer's tag). */
+    spec: Pick<TaskSpec, "taskId">;
+    /** borrowed-readonly — the deployment seats this lane reports on, as a Pick over the SAME `deps` object (receiver
+     *  preserved for `deps.onError?.()`): the late-settlement observer's notice/error sinks and the hook-crash notifier. */
+    deps: Pick<RunnerDeps, "onNotice" | "onError">;
+    /** borrowed-readonly — the acquired session id (the observer's tag, the hook-phase error tag). */
+    sessionId: string;
+    /** borrowed-readonly — the run's invocation id (the observer's tag). */
+    runId: string;
+    /** borrowed-readonly — the resolved hook record; only `permissionDenied` is read (the deny observer's seat). */
+    hooks: Hooks | undefined;
+    /** borrowed-readonly — the validated per-prepare hook seat bound (the deny observer's timeout). */
+    hookTimeoutMs: number;
+    /** borrowed-readonly — the own hook-crash reporter (the deny observer's swallow-guarded report sink). */
+    notifyOwnHookCrash: (err: unknown) => void;
+}
+export interface PrepareAskLaneResult {
+    /** owned — the lane, or undefined exactly when `gateMachineryActive` is false (then the suspend saga, the boundary
+     *  parks, the park closure and the gate station are not built either — they key off this seat). */
+    askLane: AskLane | undefined;
+}
+/** The M19 ask-lane phase body — prepareTask's in-stream ask stretch, verbatim (see the module header). */
+export declare function prepareAskLane(input: PrepareAskLaneInput): PrepareAskLaneResult;

package/dist/core/runner/prepare-ask-lane.js

@@ -0,0 +1,133 @@
+import { primaryActivityArg } from "../arg-summary.js";
+import { hookSeatExpiredError, runHookSeat } from "../hooks.js";
+import { isLiveApproverSeat, resolveAsk } from "../tool-policy.js";
+import { composeCallSignal, raceAbort } from "./abort-race.js";
+import { gateAskCarry, lateAskSettlementObserver } from "./denial-limit-arms.js";
+import { consumeInheritedAskGrant } from "./inherited-ask-grants.js";
+function createDenyObserverNotifier(hooks, hookTimeoutMs, signal, report) {
+    if (hooks?.permissionDenied === undefined)
+        return undefined;
+    return async (payload) => {
+        try {
+            const seat = await runHookSeat("permissionDenied", { timeoutMs: hookTimeoutMs, signal }, (sig) => hooks.permissionDenied({ ...payload, signal: sig }));
+            if (seat.expired)
+                report(hookSeatExpiredError("permissionDenied", hookTimeoutMs, seat.cause, "the deny observation was abandoned; the deny itself is unchanged"));
+        }
+        catch (err) {
+            report(err);
+        }
+    };
+}
+const sanitizePreview = (node, depth = 0) => {
+    if (depth > 6)
+        return undefined;
+    if (typeof node === "string") {
+        return node.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "\u2400");
+    }
+    if (node === null || typeof node !== "object")
+        return node;
+    if (Array.isArray(node))
+        return node.map((v) => sanitizePreview(v, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        out[sanitizePreview(k, depth + 1)] = sanitizePreview(v, depth + 1);
+    }
+    return out;
+};
+function resolveApprovalPreview(tools, toolName, args) {
+    const t = tools.find((x) => x.name === toolName || (x.aliases?.includes(toolName) ?? false));
+    if (t?.approvalPreview === undefined)
+        return {};
+    try {
+        const raw = t.approvalPreview(args);
+        if (raw === undefined)
+            return {};
+        const bytes = JSON.stringify(raw);
+        if (bytes === undefined)
+            return { withheld: "unavailable" };
+        if (bytes.length > 16_384) {
+            return { preview: { truncated: true, note: `approval preview exceeded 16KiB (${bytes.length} chars serialized)` }, withheld: "oversize" };
+        }
+        return { preview: sanitizePreview(raw) };
+    }
+    catch {
+        return { withheld: "unavailable" };
+    }
+}
+export function prepareAskLane(input) {
+    const { gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, humanBareRejections, now, ruleOffersOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash } = input;
+    if (!gateMachineryActive)
+        return { askLane: undefined };
+    const composedCallSignal = (callSignal) => composeCallSignal(abortController.signal, callSignal);
+    const adjudicate = effectivePolicy
+        ? (req, callSignal) => {
+            const signal = composedCallSignal(callSignal);
+            return raceAbort(Promise.resolve(effectivePolicy.check({ ...req, budget: budgetSnapshot, ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}) }, signal)), signal, () => ({
+                action: "deny",
+                message: "policy check aborted (task timed out or cancelled)",
+            }));
+        }
+        : undefined;
+    const approvalPreviewOf = (toolName, args) => resolveApprovalPreview(tools, toolName, args);
+    const resolveAskBound = async (decision, req, callSignal) => {
+        if (inheritedUnavailableAsks.delete(req.toolCallId)) {
+            return {
+                action: "deny",
+                message: `approval for "${req.toolName}" requires an ancestor task's approval that cannot be resolved here ` +
+                    `(no live approver reachable, or a durable-park mandate applies), and no durable approval park is ` +
+                    `available — denied fail-closed (the inherited constraint stands).`,
+                decisionReason: "mode",
+                approverUnavailable: true,
+            };
+        }
+        const grantReuse = consumeInheritedAskGrant(inheritedAskGrants, onAsk, humanReviewRef, decision, req);
+        if (grantReuse !== undefined)
+            return grantReuse;
+        const t0 = now();
+        const resolved = await resolveAsk({
+            toolName: req.toolName,
+            toolCallId: req.toolCallId,
+            args: req.args,
+            ...(() => {
+                const p = approvalPreviewOf(req.toolName, req.args);
+                return { ...(p.preview !== undefined ? { preview: p.preview } : {}), ...(p.withheld !== undefined ? { previewWithheld: p.withheld } : {}) };
+            })(),
+            ...ruleOffersOf(req.toolName, req.args, decision.action === "ask" ? decision : undefined),
+            message: decision.message ?? `approval required for "${req.toolName}"`,
+            ...askSourceIdentity(),
+            ...riskAxesOf(req.toolName),
+            ...(decision.action === "ask" && decision.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+            ...(decision.action === "ask" && decision.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: decision.persistedRuleShadowed } : {}),
+            ...(decision.action === "ask" ? gateAskCarry(decision, isLiveApproverSeat(onAsk), autoModeDenialTracking) : {}),
+            ...(decision.action === "ask" && decision.probeReason !== undefined ? { probeReason: decision.probeReason } : {}),
+            ...(decision.action === "ask" && decision.probeCause !== undefined ? { probeCause: decision.probeCause } : {}),
+            ...(decision.action === "ask" && decision.ruleEvidence !== undefined ? { ruleEvidence: decision.ruleEvidence } : {}),
+        }, onAsk, composedCallSignal(callSignal), lateAskSettlementObserver({ toolName: req.toolName, toolCallId: req.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
+        const waitMs = Math.max(0, now() - t0);
+        if (resolved.approverUnavailable !== true && resolved.resolution !== "task_aborted") {
+            humanReviewRef.count += 1;
+            humanReviewRef.totalWaitMs += waitMs;
+            const toolArg = primaryActivityArg(req.args);
+            humanReviewRef.gates.push({
+                kind: "human",
+                waitMs,
+                decision: resolved.action === "allow" ? "allow" : "deny",
+                toolName: req.toolName,
+                ...(toolArg !== undefined ? { toolArg } : {}),
+            });
+        }
+        if (resolved.action === "deny" && resolved.settledBy === "human" && resolved.humanRefusalNote !== true) {
+            humanBareRejections.add(req.toolCallId);
+        }
+        return resolved;
+    };
+    const notifyPermissionDenied = createDenyObserverNotifier(hooks, hookTimeoutMs, abortController.signal, notifyOwnHookCrash);
+    const notifyHookError = (err) => {
+        try {
+            deps.onError?.(err instanceof Error ? err : new Error(String(err)), { phase: "hook", sessionId });
+        }
+        catch {
+        }
+    };
+    return { askLane: { composedCallSignal, adjudicate, approvalPreviewOf, resolveAskBound, notifyPermissionDenied, notifyHookError } };
+}

package/dist/core/runner/prepare-boundary-parks.d.ts

@@ -0,0 +1,105 @@
+/**
+ * design/390 §1.2 M19 (boundary parks) — prepareTask's three BOUNDARY-FAMILY park lanes, verbatim from the driver's
+ * gate-machinery block: the ONE resource mint (`mintResourceSuspend`) behind the task-axis `suspendForResource` (exposed
+ * under the caller's `resourceSuspend` opt-in) and the infrastructure `suspendForPlatformLimit` (exposed on durable infra
+ * alone), and the `plan_review` mint behind `suspendForReview` (exposed with a checkpoint store). Every mint reuses the
+ * suspend saga's serializer, commit saga, loop cap and env split — this phase adds no second copy of any of them. The
+ * interface is the dependency list the segment had implicitly (design/238 R-1); the three lanes used to be forward-declared
+ * `let`s at task scope, assigned inside the block, so the driver's Prepared could expose them — they are this phase's
+ * Result now, and the driver binds them as consts.
+ *
+ * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the mints run at a turn boundary), so the
+ * phase adds no yield between the suspend saga before it and the park closure after it (design/390 §1.5). Read-stability
+ * of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
+ *
+ * The lanes exist exactly when the saga does (the ask lane's presence law) — an absent saga answers three absent lanes,
+ * so the orchestrator grows no branch.
+ */
+import type { AgentHarness } from "../../internal/harness.js";
+import { type CheckpointStore } from "../checkpoint-store.js";
+import type { SessionStore } from "../session.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+import type { Prepared, SuspendSaga } from "./contracts.js";
+export interface PrepareBoundaryParksInput {
+    /** borrowed-readonly — the suspend saga's eight seats (the serializer, the commit saga, the loop cap, the env split, the
+     *  park-only handle, the in-flight spend), or undefined when the gate machinery is inactive (then all three lanes are
+     *  absent). Called at park time; never rebuilt here. */
+    saga: SuspendSaga | undefined;
+    /** borrowed-readonly — the REBOUND spec. Read: `resourceSuspend` (the slice scope/ttl/maxSlices), `retainBackgroundProcesses`
+     *  (the park-only sweep gate), `durableApproval` (the review pause's ttl), `principal` (the rows' identity record and
+     *  the review scope). Never mutated. */
+    spec: Pick<TaskSpec, "resourceSuspend" | "retainBackgroundProcesses" | "durableApproval" | "principal">;
+    /** borrowed-readonly — the leg's checkpoint store, or undefined (then the review lane is absent and the resource mint
+     *  answers false). */
+    checkpointStore: CheckpointStore | undefined;
+    /** borrowed-mutable — prepare's abort seat. `.signal` is read (a cancelling run mints nothing); `abort()` is called on
+     *  the review lane's commit (the review pause stops the run the human gate's way). */
+    abortController: {
+        readonly signal: AbortSignal;
+        abort(): void;
+    };
+    /** borrowed-mutable — the built harness. Writers here: `requestStopAfterTurn()` (the resource lanes' clean stop) and
+     *  `abort()` (the review lane's stop). */
+    harness: Pick<AgentHarness, "abort" | "requestStopAfterTurn">;
+    /** borrowed-readonly — the acquired session; only `getLeafId` is read (no committed leaf ⇒ no consistent resume point). */
+    session: Pick<Prepared["session"], "getLeafId">;
+    /** borrowed-readonly — the session store; only the optional `pin` is called (best-effort, after commit). */
+    sessions: Pick<SessionStore, "pin">;
+    /** borrowed-readonly — the acquired session id (the rows' session, the source attribution, every disclosure's tag). */
+    sessionId: string;
+    /** borrowed-readonly — the deployment's error face, as a Pick over the SAME `deps` object (receiver preserved for
+     *  `deps.onError?.()`): the suspendVM refusals, the skipped-review lines, the pin failures. */
+    deps: Pick<RunnerDeps, "onError">;
+    /** borrowed-readonly — the cross-slice ledger carried on the resumed checkpoint, or undefined on the first slice. */
+    priorLedger: Prepared["resourceLedger"];
+    /** borrowed-readonly — the resource-slice cap, or undefined (no slice ceiling). */
+    maxSlices: number | undefined;
+    /** borrowed-readonly — the restart-loop cap the review lane is bounded by. */
+    maxSuspends: number;
+    /** borrowed-readonly — the human total the first slice seeds the ledger from, or undefined. */
+    resourceTotal: {
+        totalBudgetMicroUsd?: number;
+        totalTokens?: number;
+    } | undefined;
+    /** borrowed-readonly — how many times this task already suspended (carried on the resumed checkpoint); a slice carries
+     *  it UNCHANGED. */
+    priorSuspendCount: number;
+    /** borrowed-readonly — the restart-loop chain base (resets after an approved execution); the review lane's count. */
+    suspendChainBase: () => number;
+    /** borrowed-readonly — the per-task human-review accumulator; snapshotted onto every row (never written here). */
+    humanReviewRef: Prepared["humanReviewRef"];
+    /** borrowed-readonly — the loop's live spend seat; `.get` is read at mint time for the review ledger. */
+    liveSpendRef: Prepared["liveSpendRef"];
+    /** borrowed-readonly — the injectable wall clock (the review pause's `suspendedAt`). */
+    now: () => number;
+    /** borrowed-readonly — the inherited-gate phase's three version-stamp predicates (face / F-012 / org admission). */
+    faceCheckpointState: () => boolean;
+    /** borrowed-readonly — see `faceCheckpointState`. */
+    f012CheckpointState: () => boolean;
+    /** borrowed-readonly — see `faceCheckpointState`. */
+    orgAdmissionCheckpointState: () => boolean;
+    /** borrowed-mutable — the durable-suspend holder (`Prepared.suspendRef`). Writer here: the commit-side publication of a
+     *  committed resource row. */
+    suspendRef: Prepared["suspendRef"];
+    /** borrowed-mutable — the review holder (`Prepared.reviewRef`). Writer here: the commit-side publication of a committed
+     *  plan_review row. */
+    reviewRef: Prepared["reviewRef"];
+    /** borrowed-mutable — the run-scoped remote-lifecycle failure log. Writer here: a refused `suspendVM` (`push`). */
+    remoteEnvFailures: Prepared["remoteEnvFailures"];
+    /** borrowed-readonly — the wiring-manifest phase's task-axis predicate (opt-in ∧ durable infra): exposes `suspendForResource`. */
+    resourceSuspendEligible: boolean;
+    /** borrowed-readonly — the wiring-manifest phase's durable-infra predicate: exposes `suspendForPlatformLimit`. */
+    durableSuspendInfraReady: boolean;
+    /** borrowed-readonly — the restore-incomplete adapter's missing members, or undefined (the review lane refuses loudly). */
+    incompleteSuspendAdapter: readonly ("resumeVM" | "postResumeInit")[] | undefined;
+}
+export interface PrepareBoundaryParksResult {
+    /** owned — the task-axis resource lane (`Prepared.suspendForResource`), or undefined (no opt-in / no infra / inactive). */
+    suspendForResource: Prepared["suspendForResource"];
+    /** owned — the platform lane (`Prepared.suspendForPlatformLimit`), or undefined (no durable infra / inactive). */
+    suspendForPlatformLimit: Prepared["suspendForPlatformLimit"];
+    /** owned — the plan-review lane (`Prepared.suspendForReview`), or undefined (no store / inactive). */
+    suspendForReview: Prepared["suspendForReview"];
+}
+/** The M19 boundary-parks phase body — prepareTask's three boundary lanes, verbatim (see the module header). */
+export declare function prepareBoundaryParks(input: PrepareBoundaryParksInput): PrepareBoundaryParksResult;

package/dist/core/runner/prepare-boundary-parks.js

@@ -0,0 +1,169 @@
+import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
+import { BINDING_CHECKPOINT_VERSION, debitLedger, F012_CHECKPOINT_VERSION, FACE_CHECKPOINT_VERSION, mintCheckpointId, mintCheckpointToken, ORG_ADMISSION_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, } from "../checkpoint-store.js";
+import { defaultTaskRegistry } from "../task-registry.js";
+import { checkpointScopeOf } from "./checkpoint-scope.js";
+import { DEFAULT_RESOURCE_TTL_MS, publishCommittedSuspend, sanitizedTtlMs, USAGE_WINDOW_REAP_MARGIN_MS } from "./park-commit.js";
+import { remoteEnvFailureNote } from "./remote-env-retry.js";
+export function prepareBoundaryParks(input) {
+    const { saga, spec, checkpointStore, abortController, harness, session, sessions, sessionId, deps, priorLedger, maxSlices, maxSuspends, resourceTotal, priorSuspendCount, suspendChainBase, humanReviewRef, liveSpendRef, now, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, suspendRef, reviewRef, remoteEnvFailures, resourceSuspendEligible, durableSuspendInfraReady, incompleteSuspendAdapter } = input;
+    if (saga === undefined)
+        return { suspendForResource: undefined, suspendForPlatformLimit: undefined, suspendForReview: undefined };
+    const { inFlightSpendMicroUsd, serializeCheckpointState, commitSuspendSaga, suspendLoopCapHit, suspendableEnv, parkOnlyRemoteEnv, parkOnlyHandle } = saga;
+    const mintResourceSuspend = async (reason, sliceSpend, hint) => {
+        const rs = spec.resourceSuspend;
+        if (!checkpointStore)
+            return false;
+        const scope = rs?.scope ?? checkpointScopeOf(spec);
+        if (abortController.signal.aborted)
+            return false;
+        if (suspendLoopCapHit(priorLedger?.sliceCount ?? 0, maxSlices, " (resource slice limit)"))
+            return false;
+        const leafId = await session.getLeafId();
+        if (!leafId)
+            return false;
+        if (abortController.signal.aborted)
+            return false;
+        let remoteHandle;
+        if (suspendableEnv !== undefined) {
+            if (hasBackgroundShell(suspendableEnv))
+                await sweepBackgroundShells(suspendableEnv, defaultTaskRegistry);
+            const snap = await suspendableEnv.suspendVM({ abortSignal: abortController.signal });
+            if (!snap.ok) {
+                remoteEnvFailures.push(remoteEnvFailureNote("suspendVM", snap.error, 1));
+                deps.onError?.(new Error(`resource suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error }), { phase: "config", sessionId });
+                return false;
+            }
+            remoteHandle = { ...suspendableEnv.workspaceHandle(), snapshotId: snap.value };
+        }
+        else if (parkOnlyRemoteEnv !== undefined) {
+            if (hasBackgroundShell(parkOnlyRemoteEnv) && spec.retainBackgroundProcesses !== true)
+                await sweepBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry);
+            remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+        }
+        const token = mintCheckpointToken();
+        const gate = { kind: "resource_limit", reason, ...(hint !== undefined ? { resumeAfterMs: hint.resumeAfterMs } : {}) };
+        const resourceLedgerOut = debitLedger(priorLedger, sliceSpend, resourceTotal);
+        const mintedAt = Date.now();
+        const cp = {
+            token,
+            checkpointId: mintCheckpointId(),
+            version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : resourceLedgerOut.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : RESOURCE_CHECKPOINT_VERSION,
+            scope,
+            sessionId,
+            leafId,
+            gate,
+            pendingAction: { kind: "resource_limit", reason },
+            state: serializeCheckpointState(remoteHandle),
+            status: "pending",
+            createdAt: mintedAt,
+            deadline: mintedAt + Math.max(sanitizedTtlMs(rs?.ttlMs) ?? DEFAULT_RESOURCE_TTL_MS, hint !== undefined ? hint.resumeAfterMs + USAGE_WINDOW_REAP_MARGIN_MS : 0),
+            suspendCount: priorSuspendCount,
+            humanReview: humanReviewRef.count > 0
+                ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                : undefined,
+            resourceLedger: resourceLedgerOut,
+            ...(spec.durableApproval !== undefined ? { durableApproval: { ...spec.durableApproval } } : {}),
+            ...(spec.principal ? { principal: spec.principal } : {}),
+        };
+        if ((await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).tag !== "committed")
+            return false;
+        publishCommittedSuspend({ suspendRef, reviewRef }, token, gate, scope, remoteHandle, cp.checkpointId, cp.pendingAction);
+        try {
+            await sessions.pin?.(sessionId);
+        }
+        catch (pinErr) {
+            deps.onError?.(pinErr, { phase: "config", sessionId });
+        }
+        harness.requestStopAfterTurn();
+        return true;
+    };
+    const suspendForResource = resourceSuspendEligible ? mintResourceSuspend : undefined;
+    const suspendForPlatformLimit = durableSuspendInfraReady ? mintResourceSuspend : undefined;
+    const suspendForReview = checkpointStore
+        ? async (reason) => {
+            if (!checkpointStore)
+                return false;
+            if (abortController.signal.aborted)
+                return false;
+            if (incompleteSuspendAdapter !== undefined) {
+                try {
+                    deps.onError?.(new Error(`plan_review park skipped: the per-task execution env declares capabilities.suspendable but its adapter does not implement ${incompleteSuspendAdapter.join(" or ")}, so its workspace could not be restored on resume (the plan-review request was dropped; the run continues without pausing)`), { phase: "config", sessionId });
+                }
+                catch {
+                }
+                return false;
+            }
+            if (suspendLoopCapHit(suspendChainBase(), maxSuspends, " for a plan_review (likely a resume/restart loop)."))
+                return false;
+            const leafId = await session.getLeafId();
+            if (!leafId) {
+                try {
+                    deps.onError?.(new Error("plan_review park skipped: no committed session leaf (the plan-review request was dropped; the run continues without pausing)"), { phase: "config", sessionId });
+                }
+                catch {
+                }
+                return false;
+            }
+            if (abortController.signal.aborted)
+                return false;
+            let remoteHandle;
+            if (suspendableEnv !== undefined) {
+                if (hasBackgroundShell(suspendableEnv))
+                    await sweepBackgroundShells(suspendableEnv, defaultTaskRegistry);
+                const snap = await suspendableEnv.suspendVM({ abortSignal: abortController.signal });
+                if (!snap.ok) {
+                    remoteEnvFailures.push(remoteEnvFailureNote("suspendVM", snap.error, 1));
+                    deps.onError?.(new Error(`plan_review suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error }), { phase: "config", sessionId });
+                    return false;
+                }
+                remoteHandle = { ...suspendableEnv.workspaceHandle(), snapshotId: snap.value };
+            }
+            else if (parkOnlyRemoteEnv !== undefined) {
+                if (hasBackgroundShell(parkOnlyRemoteEnv) && spec.retainBackgroundProcesses !== true)
+                    await sweepBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry);
+                remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+            }
+            const token = mintCheckpointToken();
+            const scope = checkpointScopeOf(spec);
+            const gate = { kind: "plan_review", reason: reason ?? `plan review requested` };
+            const reviewLedger = debitLedger(priorLedger, liveSpendRef.get?.() ?? { costMicroUsd: 0, tokens: 0, turns: 0, walltimeMs: 0 }, resourceTotal, { countSlice: false });
+            const mintedAt = Date.now();
+            const cp = {
+                token,
+                checkpointId: mintCheckpointId(),
+                version: faceCheckpointState() ? FACE_CHECKPOINT_VERSION : f012CheckpointState() ? F012_CHECKPOINT_VERSION : orgAdmissionCheckpointState() ? ORG_ADMISSION_CHECKPOINT_VERSION : reviewLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
+                scope,
+                sessionId,
+                leafId,
+                gate,
+                pendingAction: { kind: "plan_review" },
+                state: serializeCheckpointState(remoteHandle, inFlightSpendMicroUsd()),
+                status: "pending",
+                createdAt: mintedAt,
+                suspendedAt: now(),
+                deadline: mintedAt + (sanitizedTtlMs(spec.durableApproval?.ttlMs) ?? DEFAULT_RESOURCE_TTL_MS),
+                suspendCount: suspendChainBase() + 1,
+                humanReview: humanReviewRef.count > 0
+                    ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                    : undefined,
+                resourceLedger: reviewLedger,
+                sourceTaskId: sessionId,
+                ...(spec.principal ? { principal: spec.principal } : {}),
+                ...(spec.durableApproval !== undefined ? { durableApproval: { ...spec.durableApproval } } : {}),
+            };
+            if ((await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).tag !== "committed")
+                return false;
+            publishCommittedSuspend({ suspendRef, reviewRef }, token, gate, scope, remoteHandle, cp.checkpointId, cp.pendingAction);
+            try {
+                await sessions.pin?.(sessionId);
+            }
+            catch (pinErr) {
+                deps.onError?.(pinErr, { phase: "config", sessionId });
+            }
+            abortController.abort();
+            void harness.abort();
+            return true;
+        }
+        : undefined;
+    return { suspendForResource, suspendForPlatformLimit, suspendForReview };
+}