@sema-agent/server 7.79.0 → 7.79.1

package/dist/http/resume-legs.js

@@ -0,0 +1,1230 @@
+import { redactErrorMessage, redactHead } from "../observability/run-terminal-log.js";
+import { createHash } from "node:crypto";
+import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, validatePendingSteer, GLOBAL_USAGE_KEY, terminalProjection, PAUSE_REGISTRY } from "@sema-agent/core";
+import { decideParkedAgent, denyWorkflowParksUnreadable, findParkOrigin, planWorkflowParkedDecide } from "../parked-decide.js";
+import { HttpError, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE } from "../security.js";
+import { evictIfConflict, parkToolCallId, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
+import { failureCodeOf, nestedPauseOf, stripResumeToken } from "../terminal.js";
+import { mintCancelledResult } from "../run-cancel-context.js";
+import {} from "../host-decision.js";
+import { readTurnActivityMs, recordTurnActivity } from "../turn-activity.js";
+import { recordResumeResourceWindow } from "../resource-window.js";
+import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKey, NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
+import { fleetRunPublisher, fleetRunLabels, fleetRunResiduals, isFleetAgentTerminalNotification } from "../fleet/fleet-bus.js";
+import { defaultSubagentTailBus } from "../fleet/subagent-tail-bus.js";
+import { APPROVAL_GATE_KINDS, createApprovalCardEmitter, isApprovalGateKind, resolveApprovalLeg, resolveStreamApprovalGate } from "../tool-approval.js";
+import { buildCheckpointAnchorHash } from "../approval-ask-audit-store.js";
+import { TERMINAL_PARK_GATE_KINDS } from "../plugins/checkpoint-store-sql.js";
+import { withPrincipal } from "../observability/principal-context.js";
+import { modelTextEventData, turnEndEventData, contextUsageEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, workspaceChangedEventData, wiringManifestEventData, toolRosterDeltaEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "../trace/project.js";
+import { redactSecrets } from "../trace/redact.js";
+import { createLedgerSink, createSerialLedgerAppend } from "../trace/ledger-sink.js";
+import { registerEngineNoticeLeg } from "../trace/engine-notice-wire.js";
+import { reasoningDeltaBytes, reasoningSegmentEventId } from "../trace/model-segment.js";
+import { errorText } from "../observability/err-text.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { verifyRoundsFromBody } from "./verify-rounds.js";
+import { acceptedResumingReceipt } from "./route-ctx.js";
+import { mintAndDriveDurableRun } from "./durable-run-leg.js";
+import { createSessionsLocal } from "./routes/sessions.js";
+import { createSessionSyncLocal } from "./routes/session-sync.js";
+import { createImagesLocal } from "./routes/images.js";
+import { gatedPrincipal, explicitOperatorOk } from "./principal-gate.js";
+import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflict.js";
+import { ASK_USER_QUESTION_TOOL_NAME } from "../approval-content-kind.js";
+function isCheckpointReopenedFailure(r) {
+    const code = failureCodeOf(r.terminal);
+    return code === "resume.env_failed" || code === "resume.tool_unavailable" || code === "resume.tool_contract_mismatch";
+}
+function nestedParkStatusOf(r) {
+    const paused = nestedPauseOf(r.terminal);
+    if (paused === undefined)
+        return undefined;
+    return PAUSE_REGISTRY[paused.gate.kind].taskStatus;
+}
+const WORKER_SWAP_REDEEMABLE = {
+    version_newer: true,
+    env_factory_missing: true,
+    governed_unwired: true,
+    origin_missing: true,
+    seat_retired: true,
+    ledger_event_unknown: true,
+    real_approval_damaged: false,
+    real_approval_forged: false,
+    read_face_damaged: false,
+    read_face_forged: false,
+    write_face_damaged: false,
+    constraint_chain_missing: false,
+};
+function checkpointRowRedeemableElsewhere(reason) {
+    return reason !== undefined && WORKER_SWAP_REDEEMABLE[reason] === true;
+}
+export function createResumeLegs(ctx) {
+    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
+    const resumeFleetScope = (req, auth) => req ? (gatedPrincipal(req, deps.config) ?? "default") : (auth.principal ?? "default");
+    async function resumeCheckpoint(sessionId, decision, reason, hostDecision, req, answer, binding, onResumeCommitted, acceptEarly, decider) {
+        const cs = deps.checkpointStore;
+        const token = (await cs.findPendingTokenBySession(sessionId, undefined, { gateKinds: APPROVAL_GATE_KINDS })) ?? (await cs.findPendingTokenBySession(sessionId));
+        if (binding?.checkpointToken && binding.checkpointToken !== token) {
+            let seenUnreadable = false;
+            const seen = await cs.get(binding.checkpointToken).catch((e) => {
+                seenUnreadable = true;
+                recordFailOpen("server.approvals.stale-echoed-token-unreadable", `session=${sessionId} err=${e instanceof Error ? e.message : String(e)}`);
+                return null;
+            });
+            const attributable = seen !== null && seen.sessionId === sessionId;
+            if (!attributable && seen !== null) {
+                deps.logger?.warn?.("approval_stale_token_foreign", { sessionId, tokenSession: seen.sessionId ?? null });
+            }
+            if (!token && !attributable && !seenUnreadable) {
+                deps.logger?.info?.("approval_decide_no_pending", { sessionId, staleTokenEchoed: true });
+                return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            }
+            let currentPending;
+            if (token && decider !== undefined) {
+                const cur = await cs.get(token).catch((e) => {
+                    recordFailOpen("server.approvals.stale-current-pending-unreadable", `session=${sessionId} err=${e instanceof Error ? e.message : String(e)}`);
+                    return null;
+                });
+                const curPa = cur?.pendingAction;
+                const curOwner = cur ? decodeCheckpointScope(cur.scope) : undefined;
+                const scopeOk = cur !== null && (decider.explicitOperator || curOwner === undefined || curOwner === decider.principal);
+                if (cur && cur.sessionId === sessionId && !scopeOk) {
+                    deps.logger?.info?.("approval_decide_no_pending", { sessionId, staleTokenEchoed: true, foreignCurrentSuppressed: true });
+                    return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+                }
+                if (cur && cur.status === "pending" && cur.sessionId === sessionId && scopeOk && curPa?.kind === "tool_approval" && curPa.toolCallId) {
+                    currentPending = {
+                        toolName: curPa.toolName,
+                        boundCallId: curPa.toolCallId,
+                        ...(curPa.boundInputHash ? { boundInputHash: curPa.boundInputHash } : {}),
+                    };
+                }
+            }
+            return {
+                status: 409,
+                body: {
+                    error: "the approval you are deciding is no longer current (already resolved or superseded since you viewed it)",
+                    errorCode: "approval_stale",
+                    ...(attributable ? { terminal: "resolved" } : {}),
+                    ...(currentPending ? { currentPending } : {}),
+                },
+            };
+        }
+        if (!token) {
+            deps.logger?.info?.("approval_decide_no_pending", { sessionId });
+            return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+        }
+        const cpPromise = cs.get(token);
+        const ctxPromise = cs.getCtx(sessionId);
+        void ctxPromise.catch(() => { });
+        const noApproval = { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+        let cp;
+        try {
+            cp = await cpPromise;
+        }
+        catch (e) {
+            void ctxPromise.catch(() => { });
+            if (!(await mayDiscloseRowError(cs, token, decider))) {
+                deps.logger?.warn?.("approval_decide_unreadable_row_withheld", { sessionId, note: "row unreadable and the caller's ownership of THAT token is unproven — folded into the uniform 404" });
+                return noApproval;
+            }
+            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+        }
+        if (!cp) {
+            if (!(await mayDiscloseRowError(cs, token, decider)))
+                return noApproval;
+            return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+        }
+        if (decider !== undefined && !decider.explicitOperator) {
+            const cpOwner = decodeCheckpointScope(cp.scope);
+            if (cpOwner !== undefined && cpOwner !== decider.principal) {
+                deps.logger?.warn?.("approval_decide_row_scope_mismatch", { sessionId, note: "loaded pending row is foreign to the verified caller — TOCTOU fold" });
+                return { status: 404, body: { error: "approval not found", errorCode: "not_found.approval" } };
+            }
+        }
+        const decideGateKind = cp.gate?.kind;
+        if (!isApprovalGateKind(decideGateKind)) {
+            const activeForPath = decideGateKind
+                ? await deps.runStore?.getActiveTaskId(sessionId).catch(() => undefined)
+                : undefined;
+            const gnPath = decideGateKind && activeForPath
+                ? resumeEntryForGate(decideGateKind, { sessionId, taskId: activeForPath })
+                : null;
+            return {
+                status: 409,
+                body: {
+                    error: `task is suspended on a '${decideGateKind ?? "unknown"}' gate, not a tool approval — a plan_review gate is resolved via POST /v1/assistant/tasks/:id/plan_review, a resource_limit suspension via POST /v1/assistant/tasks/:id/resume`,
+                    errorCode: "gate_not_tool_approval",
+                    ...(decideGateKind ? { pendingGate: { kind: decideGateKind, ...(gnPath ? { decidePath: gnPath } : {}) } } : {}),
+                },
+            };
+        }
+        if (req !== undefined && !binding?.checkpointToken && !binding?.boundCallId) {
+            return {
+                status: 400,
+                body: {
+                    error: "decide requires the decision-action binding — echo checkpointToken and/or boundCallId from the pending approval (GET /v1/approvals)",
+                    errorCode: "decide_requires_binding",
+                    bindingEnforced: true,
+                },
+            };
+        }
+        const s57RowCallId = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.toolCallId : undefined;
+        if (binding?.boundCallId !== undefined && s57RowCallId && binding.boundCallId !== s57RowCallId) {
+            let s57CurrentPending;
+            if (decider !== undefined && cp.status === "pending" && cp.sessionId === sessionId && cp.pendingAction.kind === "tool_approval") {
+                s57CurrentPending = {
+                    toolName: cp.pendingAction.toolName,
+                    boundCallId: s57RowCallId,
+                    ...(cp.pendingAction.boundInputHash ? { boundInputHash: cp.pendingAction.boundInputHash } : {}),
+                };
+            }
+            return {
+                status: 409,
+                body: {
+                    error: "the approval you are deciding is no longer current (already resolved or superseded since you viewed it)",
+                    errorCode: "approval_stale",
+                    ...(s57CurrentPending ? { currentPending: s57CurrentPending } : {}),
+                },
+            };
+        }
+        const paForGrant = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction : undefined;
+        const loadedGrantTool = paForGrant !== undefined && paForGrant.toolName && paForGrant.toolName !== ASK_USER_QUESTION_TOOL_NAME
+            ? paForGrant.toolName
+            : null;
+        const boundGrant = onResumeCommitted
+            ? (overrideSessionId) => onResumeCommitted({ ...(overrideSessionId !== undefined ? { overrideSessionId } : {}), validatedToolName: loadedGrantTool })
+            : undefined;
+        const lateSettleSink = deps.approvalLateSettle;
+        const lateSettleAnchor = lateSettleSink !== undefined && req !== undefined && token
+            ? {
+                sessionId: cp.sessionId,
+                ...(paForGrant?.toolCallId !== undefined ? { toolCallId: paForGrant.toolCallId } : {}),
+                checkpointTokenHash: buildCheckpointAnchorHash(token),
+            }
+            : undefined;
+        const noteLateSettleIfAccepted = (out) => {
+            if (lateSettleSink === undefined || lateSettleAnchor === undefined || out.status !== 200)
+                return;
+            if (out.body?.errorCode === "cancelled")
+                return;
+            try {
+                lateSettleSink.recordLateSettle({ ...lateSettleAnchor, outcome: decision === "approve" ? "allowed" : "denied", decidedBy: hostDecision.decidedBy, ...(hostDecision.approver !== undefined ? { approver: hostDecision.approver } : {}), settledAtMs: Date.now() });
+            }
+            catch (e) {
+                recordFailOpen("server.approval-ask-audit.append-failed", `kind=late_settle err=${e instanceof Error ? e.message : String(e)}`);
+            }
+        };
+        const parkedForkQuotaDenial = req !== undefined ? ownerCostQuotaDenied(decodeCheckpointScope(cp.scope)) : undefined;
+        if (parkedForkQuotaDenial)
+            return parkedForkQuotaDenial;
+        const parkedForkLeaseDenial = req !== undefined ? await ownerFleetLeaseDenied(decodeCheckpointScope(cp.scope)) : undefined;
+        if (parkedForkLeaseDenial)
+            return parkedForkLeaseDenial;
+        const ownerLeaseAdmittedHere = req !== undefined;
+        if (req !== undefined) {
+            const parkedAgentStore = deps.backgroundAgentStore;
+            const parkedTool = deps.parkedReviveTool;
+            const parkWarn = (event, fields) => deps.logger?.warn?.(event, fields);
+            const origin = await findParkOrigin({
+                ...(parkedAgentStore !== undefined && parkedTool !== undefined ? { agentStore: parkedAgentStore } : {}),
+                ...(deps.workflowAgentSessionIndex !== undefined && deps.workflowRunStore !== undefined
+                    ? { workflowIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore }
+                    : {}),
+                ...(deps.logger ? { warn: parkWarn } : {}),
+            }, { token, scope: cp.scope, sessionId: cp.sessionId });
+            const parkedReq = {
+                token, scope: cp.scope, sessionId: cp.sessionId, pendingAction: cp.pendingAction,
+                decision, hostDecision, ...(reason !== undefined ? { reason } : {}),
+                ...(binding !== undefined ? { binding: { ...(binding.boundCallId !== undefined ? { boundCallId: binding.boundCallId } : {}), ...(binding.boundInputHash !== undefined ? { boundInputHash: binding.boundInputHash } : {}), ...(binding.updatedInput !== undefined ? { updatedInput: binding.updatedInput } : {}) } } : {}),
+                ...(answer !== undefined ? { answer } : {}),
+                ...(boundGrant ? { grantRemember: (rootSessionId) => boundGrant(rootSessionId) } : {}),
+            };
+            if (origin?.kind === "background" && parkedAgentStore !== undefined && parkedTool !== undefined) {
+                const parked = await withPrincipal(decodeCheckpointScope(cp.scope), () => decideParkedAgent({
+                    agentStore: parkedAgentStore,
+                    checkpointStore: cs,
+                    registry: defaultTaskRegistry,
+                    reviveTool: parkedTool,
+                    ...(deps.parkedKnownAgentTypes ? { knownAgentTypes: deps.parkedKnownAgentTypes } : {}),
+                    ...(deps.parkedReviveInheritedGate ? { rebuildInheritedGate: deps.parkedReviveInheritedGate } : {}),
+                    ...(deps.logger ? { warn: parkWarn } : {}),
+                }, parkedReq, { handle: origin.handle, row: origin.row }));
+                void ctxPromise.catch(() => { });
+                noteLateSettleIfAccepted(parked);
+                return parked;
+            }
+            if (origin?.kind === "workflow_parks_unreadable") {
+                void ctxPromise.catch(() => { });
+                return denyWorkflowParksUnreadable(origin);
+            }
+            if (origin?.kind === "workflow") {
+                void ctxPromise.catch(() => { });
+                const plan = planWorkflowParkedDecide(origin, parkedReq);
+                if (!plan.ok)
+                    return plan.deny;
+                const parkedResume = { workflowParkedResume: [{ runId: plan.runId, token, outcome: plan.outcome }] };
+                const hostToken = await cs
+                    .findPendingTokenBySession(plan.hostSessionId, undefined, { gateKinds: TERMINAL_PARK_GATE_KINDS, pick: "oldest" })
+                    .catch(() => undefined);
+                const admittedPayer = decodeCheckpointScope(cp.scope);
+                return hostToken
+                    ? await resumeWake(plan.hostSessionId, plan.message, decider?.principal, req, acceptEarly, parkedResume.workflowParkedResume, admittedPayer)
+                    : await startFreshHostTurn(plan.hostSessionId, plan.message, admittedPayer, req, parkedResume, plan.runId);
+            }
+        }
+        let ctx;
+        try {
+            ctx = await ctxPromise;
+        }
+        catch (e) {
+            return { status: 409, body: { error: `resume context load failed: ${e instanceof Error ? e.message : String(e)}`, errorCode: "conflict.resume_context_unavailable" } };
+        }
+        if (!ctx)
+            return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
+        let spec;
+        let engineNotices = [];
+        try {
+            ({ spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth));
+        }
+        catch (e) {
+            if (e instanceof HttpError) {
+                return {
+                    status: 409,
+                    body: { error: `resume blocked by an admission policy change: ${e.message}`, errorCode: "resume_blocked_by_policy", ...(e.code ? { blockedBy: e.code } : {}), ...(e.extra ?? {}) },
+                };
+            }
+            throw e;
+        }
+        const pendingTool = cp.pendingAction.toolName;
+        if (decision === "approve" && pendingTool === ASK_USER_QUESTION_TOOL_NAME && !answer) {
+            return { status: 400, body: { error: "pending action is AskUserQuestion — approve must carry body.answer ({ answers: [{ header, selected: string[], note? }] })", errorCode: "request.field_conflict" } };
+        }
+        if (answer && (decision !== "approve" || pendingTool !== ASK_USER_QUESTION_TOOL_NAME)) {
+            return { status: 400, body: { error: `body.answer is only valid when approving a pending AskUserQuestion (decision: "${decision}", pending: "${pendingTool ?? "unknown"}")`, errorCode: "request.field_conflict" } };
+        }
+        const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
+        const pa = cp.pendingAction;
+        const persistedCallId = pa.kind === "tool_approval" ? pa.toolCallId : "";
+        const persistedHash = pa.kind === "tool_approval" ? (pa.boundInputHash ?? "") : "";
+        const outcome = {
+            gate: "policy_ask",
+            boundCallId: binding?.boundCallId ?? persistedCallId,
+            boundInputHash: binding?.boundInputHash ?? persistedHash,
+            decision: decision === "approve" ? "allow" : "deny",
+            ...(decision === "approve" && binding?.updatedInput !== undefined ? { updatedInput: binding.updatedInput } : {}),
+            ...(reason ? { reason } : {}),
+            ...(answer !== undefined ? { answer } : {}),
+            hostDecision,
+        };
+        const verifyRounds = verifyRoundsFromBody(ctx.body);
+        const driven = await driveResumeIntoRunLog({ runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, verifyRounds, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(boundGrant ? { onResumeCommitted: boundGrant } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}), ...(ownerLeaseAdmittedHere ? { ownerLeaseAdmitted: true } : {}) });
+        noteLateSettleIfAccepted(driven);
+        return driven;
+    }
+    const ONE_SHOT_HISTORY_KEYS = ["resumeAt", "restoreFiles", "acceptPartialRestore", "rewindFilesTo", "rewindFiles"];
+    const ONE_SHOT_HISTORY_STRIP = Object.fromEntries(ONE_SHOT_HISTORY_KEYS.map((k) => [k, undefined]));
+    const resolveResumeSpec = async (body, req, auth) => {
+        const engineNotices = [];
+        const spec = await deps.resolveSpec({ ...body, ...ONE_SHOT_HISTORY_STRIP }, req, auth, { leg: "resume", onNotice: (n) => engineNotices.push(n) });
+        return { spec, engineNotices };
+    };
+    async function driveResumeIntoRunLog(args) {
+        if (args.acceptEarly !== true)
+            return await driveResumeLeg(args);
+        let settleAccepted;
+        let wasAccepted = false;
+        const accepted = new Promise((resolve) => { settleAccepted = resolve; });
+        const leg = driveResumeLeg(args, (receipt) => { wasAccepted = true; settleAccepted?.(receipt); });
+        void leg.then((out) => {
+            if (wasAccepted && out.status >= 400) {
+                deps.logger?.warn?.("resume_leg_failed_after_accept", { sessionId: args.sessionId, status: out.status, body: out.body });
+                deps.metrics?.inc("resume_post_accept_failed_total");
+            }
+        }, (err) => {
+            if (!wasAccepted)
+                return;
+            deps.logger?.error?.("resume_leg_threw_after_accept", { sessionId: args.sessionId, err: redactHead(err instanceof Error ? err.message : String(err), 2000) });
+            deps.metrics?.inc("resume_post_accept_failed_total");
+        });
+        return await Promise.race([accepted, leg]);
+    }
+    async function driveResumeLeg(args, onAccepted) {
+        const resumeLegStartedAt = Date.now();
+        const { runner: legRunner, token, sessionId, principal, fleetScope, taskConfig, resumeObjective, outcome, verifyRounds } = args;
+        const legKey = createHash("sha256").update(String(token)).digest("hex");
+        const streamApprovalOn = resolveStreamApprovalGate({
+            toolApprovalEnabled: Boolean(deps.toolApproval),
+            streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
+            backend: deps.backend,
+            parkFacility: deps.checkpointStore !== undefined,
+        }).active;
+        const approvalLeg = resolveApprovalLeg({
+            streamApprovalOn,
+            windowMs: deps.config.streamApproval?.windowMs,
+            windowMarginMs: deps.config.streamAskWindowMarginMs,
+            ...(typeof taskConfig.limits?.maxWalltimeMs === "number" ? { legWalltimeMs: taskConfig.limits.maxWalltimeMs } : {}),
+            nowMonotonicMs: performance.now(),
+        });
+        const legDeadlineMonotonic = approvalLeg.legDeadlineMonotonic;
+        const ownerQuotaDenial = args.callerInitiated === true ? ownerCostQuotaDenied(principal) : undefined;
+        if (ownerQuotaDenial)
+            return ownerQuotaDenial;
+        const ownerLeaseDenial = args.callerInitiated === true && args.ownerLeaseAdmitted !== true ? await ownerFleetLeaseDenied(principal) : undefined;
+        if (ownerLeaseDenial)
+            return ownerLeaseDenial;
+        let taskId = await deps.runStore?.getActiveTaskId(sessionId);
+        let freshRunClaimed = false;
+        if (args.mintFreshRun && taskId && deps.runStore) {
+            return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, sessionId, taskId) };
+        }
+        if (!taskId && args.mintFreshRun && deps.runStore) {
+            const freshId = uuidv7();
+            const created = await deps.runStore.createRun(freshId, sessionId, principal ?? null, deps.instanceId ?? "default", {
+                source: args.mintFreshRun.source,
+                objectivePreview: resumeObjective ? redactSecrets(resumeObjective).slice(0, 120) : null,
+            });
+            if (!created.ok) {
+                return { status: 409, body: await buildActiveRunConflict({ runStore: deps.runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, sessionId, created.activeTaskId) };
+            }
+            taskId = freshId;
+            freshRunClaimed = true;
+        }
+        const fleetPub = taskId && deps.fleetBus
+            ? fleetRunPublisher(deps.fleetBus, { runId: taskId, scope: fleetScope, rootTaskId: taskId, ...fleetRunLabels(resumeObjective) })
+            : undefined;
+        const resumeTaskConfig = taskId ? { ...taskConfig, taskId } : taskConfig;
+        if (deps.toolApproval && taskId) {
+            const toolApproval = deps.toolApproval;
+            resumeTaskConfig.onAsk = approvalLeg.windowZero
+                ? (askReq) => Promise.resolve(toolApproval.unattendedAskOutcome({ taskId, owner: principal ?? null, toolName: askReq.toolName }))
+                : toolApproval.boundAsk({
+                    owner: principal ?? null,
+                    taskId,
+                    sessionId,
+                    ...(approvalLeg.active ? { legKey, ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}) } : {}),
+                });
+        }
+        if (taskId && resumeTaskConfig.resourceSuspend)
+            recordResumeResourceWindow(taskId, resumeTaskConfig.resourceSuspend);
+        let fleetSettled = false;
+        const settleFleet = (status, residuals) => {
+            if (fleetSettled)
+                return;
+            fleetSettled = true;
+            fleetPub?.onTerminal(status, residuals);
+        };
+        let result;
+        let reopenConfirmedPark = false;
+        const confirmCheckpointReopened = async () => {
+            const store = deps.checkpointStore;
+            if (!store)
+                return true;
+            try {
+                return (await store.get(token))?.status === "pending";
+            }
+            catch {
+                return true;
+            }
+        };
+        let resumeHeartbeat;
+        let resumeManifestLease = 0;
+        let resumeStreamRef;
+        let resumeLegLive = false;
+        const subagentHandleEvictions = [];
+        let claimedRow = false;
+        const cancelCtrl = new AbortController();
+        const preemptCtrl = new AbortController();
+        if (taskId && deps.runStore) {
+            claimedRow = freshRunClaimed ? true : await deps.runStore.markResuming(taskId, deps.instanceId ?? "default");
+            if (!claimedRow)
+                return { status: 409, body: { error: "run is not in a resumable (suspended) state (already resumed, decided, or expired)", errorCode: "conflict.not_resumable" } };
+            markChildrenStoppedByUserOnAbort(cancelCtrl.signal, taskId, principal);
+            fleetPub?.onStart();
+            const rs = deps.runStore;
+            const owner = principal ?? null;
+            inflightRuns.set(taskId, cancelCtrl);
+            preemptableRuns.set(taskId, preemptCtrl);
+            resumeHeartbeat = setInterval(() => {
+                void rs.heartbeat(taskId, owner).catch(() => undefined);
+                if (!cancelCtrl.signal.aborted) {
+                    void rs.isCancelRequested(taskId, owner).then((c) => { if (c)
+                        cancelCtrl.abort(); }).catch(() => undefined);
+                }
+                if (!preemptCtrl.signal.aborted) {
+                    void rs.isPreemptRequested(taskId, owner).then((p) => { if (p)
+                        preemptCtrl.abort(); }).catch(() => undefined);
+                }
+            }, HEARTBEAT_MS);
+            resumeHeartbeat.unref?.();
+            deps.modelUsage?.register(taskId);
+            resumeManifestLease = deps.promptManifests?.register(taskId) ?? 0;
+        }
+        if (args.onResumeCommitted)
+            await args.onResumeCommitted();
+        let unregisterEngineNotice;
+        try {
+            result = await withPrincipal(principal, async () => {
+                const resumeNotifiedKeys = new NotifiedKeys();
+                if (deps.runStore && taskId) {
+                    const rs0 = deps.runStore;
+                    let drainSeq = (await rs0.maxSeq(taskId)) + 1;
+                    await emitPendingWorkflowCompletions(deps.workflowCompletionInbox, sessionId, principal ?? null, (frame) => {
+                        const { type, ...rest } = frame;
+                        const f = frame;
+                        const write = rs0.appendEvent(taskId, drainSeq++, type, rest);
+                        if (f.type === "task_notification" && f.task_id)
+                            resumeNotifiedKeys.set(taskNotificationStreamKey({ task_type: f.task_type, task_id: f.task_id, status: String(f.status), seq: f.seq }), write.then(() => true, () => false));
+                        return write;
+                    }, { route: "resume-open", connection: "durable-append", log: (m, x) => deps.logger?.info?.(m, x) });
+                }
+                if (verifyRounds !== undefined) {
+                    const rsV = deps.runStore;
+                    const vSeqBase = rsV && taskId ? await rsV.maxSeq(taskId) : 0;
+                    const verifySink = createLedgerSink({
+                        appendEvent: (seq, type, data) => (rsV && taskId ? rsV.appendEvent(taskId, vSeqBase + seq, type, data) : Promise.resolve()),
+                        persistThinking: deps.config.traceThinking,
+                        notifiedKeys: resumeNotifiedKeys,
+                        ...(taskId ? { onActivity: () => recordTurnActivity(taskId) } : {}),
+                    });
+                    const vAppend = (type, data) => verifySink.append(type, data);
+                    const verifyTailContentMode = resumeTaskConfig.forwardSubagentEvents === true ? "on" : "progress_only";
+                    const verifyInternals = {
+                        ...(taskId ? { onActivity: () => recordTurnActivity(taskId) } : {}),
+                        onForwardEvent: (e) => {
+                            fleetPub?.onForwardEvent(e);
+                            {
+                                const bg = e.bgAgentId;
+                                if (bg !== undefined)
+                                    defaultSubagentTailBus.onForwardFrame(bg, verifyTailContentMode, e);
+                            }
+                            if (rsV && taskId)
+                                verifySink.onForwardEvent(e);
+                        },
+                        onStatusEvent: (e) => {
+                            deps.metrics?.inc("brain_retry_total", { phase: String(e.phase) });
+                            if (rsV && taskId) {
+                                void verifySink.appendStatus(e).catch((err) => deps.logger?.warn?.("status_event_append_failed", { route: "resume-verify", taskId, err: err instanceof Error ? err.message : String(err) }));
+                            }
+                        },
+                        onTaskNotification: (n, opts) => {
+                            if (n.task_type === "workflow")
+                                return;
+                            defaultSubagentTailBus.forgetHandle(n.task_id);
+                            if (defaultSubagentTailBus.hasSubscribers(n.task_id)) {
+                                defaultSubagentTailBus.publish(n.task_id, { type: "task_settled", taskId: n.task_id, status: n.status, ...(typeof n.seq === "number" ? { seq: n.seq } : {}), ...(n.summary ? { summary: redactSecrets(n.summary) } : {}) });
+                            }
+                            const hadRow = isFleetAgentTerminalNotification(n) ? (fleetPub?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false) : false;
+                            const parked = !resumeLegLive && Boolean(deps.workflowCompletionInbox && sessionId);
+                            deps.logger?.info?.("task_notification_observed", { route: "resume-verify", taskId: n.task_id, taskType: n.task_type, status: n.status, hadFleetRow: hadRow, legLive: resumeLegLive, parkedDurable: parked });
+                            if (parked) {
+                                void deps.workflowCompletionInbox.enqueue(taskNotificationInboxEntry(sessionId, principal ?? null, n, Date.now(), taskId, opts?.priority)).catch((err) => deps.logger?.warn?.("park_enqueue_failed", { route: "resume-verify", taskId: n.task_id, err: err instanceof Error ? err.message : String(err) }));
+                            }
+                            else if (resumeLegLive) {
+                                const key = taskNotificationStreamKey(n);
+                                if (resumeNotifiedKeys.get(key) === undefined) {
+                                    resumeNotifiedKeys.set(key, vAppend("task_notification", taskNotificationEventData({ notification: n, ...(opts?.priority !== undefined ? { priority: opts.priority } : {}) })).then(() => true, () => false));
+                                }
+                            }
+                        },
+                        ...(deps.subagentSteerRegistry && taskId
+                            ? {
+                                onSubagentSpawn: (handle) => {
+                                    subagentHandleEvictions.push(deps.subagentSteerRegistry.register(taskId, handle));
+                                },
+                            }
+                            : {}),
+                    };
+                    resumeLegLive = true;
+                    const vr = await resumeWithVerification(legRunner, token, outcome, { ...resumeTaskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, resumeObjective, verifyRounds, verifyInternals);
+                    let safe = stripResumeToken(vr);
+                    const vrNested = nestedPauseOf(vr.terminal);
+                    const reParkStatus = nestedParkStatusOf(vr);
+                    const reSuspended = vrNested !== undefined;
+                    const vrReopened = isCheckpointReopenedFailure(vr) && (await confirmCheckpointReopened());
+                    if (vrReopened)
+                        reopenConfirmedPark = true;
+                    if (taskId && deps.runStore) {
+                        const rs2 = deps.runStore;
+                        try {
+                            const ap = vAppend;
+                            await appendPromptManifest(ap, deps.promptManifests, taskId);
+                            if (reSuspended || vrReopened) {
+                                await appendModelUsageDelta(ap, deps.modelUsage, taskId);
+                                const vrParkCallId = vrNested !== undefined ? await parkToolCallId({ terminal: vrNested }, deps.checkpointStore) : undefined;
+                                await ap(reParkStatus ?? "suspended", { gate: vrNested?.gate ?? null, ...(vrParkCallId !== undefined ? { toolCallId: vrParkCallId } : {}), ...(vrReopened ? { reopened: failureCodeOf(vr.terminal) ?? null } : {}) });
+                            }
+                            else {
+                                safe = await attachModelUsage(safe, { append: ap, getEvents: (id, a) => rs2.getEvents(id, a), modelUsage: deps.modelUsage, taskId });
+                                await ap("done", { result: safe });
+                            }
+                        }
+                        catch (e) {
+                            if (!vrReopened)
+                                throw e;
+                        }
+                    }
+                    if (vrNested !== undefined)
+                        return { ...safe, terminal: vrNested };
+                    if (vr.verification?.verdict)
+                        deps.metrics?.inc("verifications_total", { verdict: vr.verification.verdict });
+                    return safe;
+                }
+                const rs = deps.runStore;
+                const startSeq = rs && taskId ? await rs.maxSeq(taskId) : 0;
+                let text = "";
+                let reasoning = "";
+                let reasoningEventId;
+                const persistThinking = deps.config.traceThinking;
+                const serialAppend = createSerialLedgerAppend((s, type, data) => rs.appendEvent(taskId, s, type, data), startSeq);
+                const append = (type, data) => (rs && taskId ? serialAppend(type, data) : Promise.resolve());
+                unregisterEngineNotice = registerEngineNoticeLeg({
+                    sessionId,
+                    ...(args.engineNotices !== undefined && args.engineNotices.length > 0 ? { pending: [...args.engineNotices] } : {}),
+                    durable: (row) => void append("engine_notice", row).catch((err) => {
+                        recordFailOpen("server.engine-notice.durable-append-failed", `leg=resume code=${row.code} task=${taskId ?? ""}`);
+                        deps.logger?.warn?.("engine_notice_append_failed", { taskId, noticeCode: row.code, sessionId: row.sessionId, err: err instanceof Error ? err.message : String(err) });
+                    }),
+                });
+                const anchorOwner = principal ?? null;
+                const getLeafId = deps.sessionStorage?.getLeafId?.bind(deps.sessionStorage);
+                const captureTurnAnchor = deps.resumeAnchorStore && getLeafId
+                    ? async (eventId) => { const leaf = await getLeafId(sessionId); if (leaf)
+                        await deps.resumeAnchorStore.put(sessionId, eventId, leaf, anchorOwner); }
+                    : undefined;
+                const captureUserMessageAnchor = deps.resumeAnchorStore && taskId
+                    ? async (entryId) => { await deps.resumeAnchorStore.put(sessionId, taskId, entryId, anchorOwner); }
+                    : undefined;
+                const anchor = new TurnAnchorCapture(captureTurnAnchor, () => deps.metrics?.inc("resume_anchor_capture_failed"), captureUserMessageAnchor);
+                const flush = async () => {
+                    if (reasoning) {
+                        await append("reasoning", modelTextEventData({ text: reasoning, eventId: reasoningEventId }));
+                        reasoning = "";
+                        reasoningEventId = undefined;
+                    }
+                    if (text) {
+                        await append("text", modelTextEventData({ text, eventId: anchor.firstTextEventId }));
+                        text = "";
+                    }
+                };
+                const driveResume = async () => {
+                    resumeLegLive = true;
+                    const tailContentMode = resumeTaskConfig.forwardSubagentEvents === true ? "on" : "progress_only";
+                    const stream = await legRunner.resumeStream(token, outcome, { ...resumeTaskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, {
+                        ...(args.workflowParkedResume !== undefined ? { workflowParkedResume: args.workflowParkedResume } : {}),
+                        onForwardEvent: (e) => {
+                            fleetPub?.onForwardEvent(e);
+                            {
+                                const bg = e.bgAgentId;
+                                if (bg !== undefined)
+                                    defaultSubagentTailBus.onForwardFrame(bg, tailContentMode, e);
+                            }
+                            if (!rs || !taskId)
+                                return;
+                            const t = e.type;
+                            const warnAppend = (kind) => (err) => deps.logger?.warn?.("forward_event_append_failed", { type: kind, taskId, err: err instanceof Error ? err.message : String(err) });
+                            if (t === "task_progress") {
+                                void append("task_progress", taskProgressEventData(e)).catch(warnAppend(t));
+                            }
+                            else if (t === "tool_start") {
+                                void append("tool_start", toolStartEventData(e)).catch(warnAppend(t));
+                            }
+                            else if (t === "tool_end") {
+                                void append("tool_end", toolEndEventData(e)).catch(warnAppend(t));
+                            }
+                        },
+                        onTaskNotification: (n, opts) => {
+                            if (n.task_type === "workflow")
+                                return;
+                            defaultSubagentTailBus.forgetHandle(n.task_id);
+                            if (defaultSubagentTailBus.hasSubscribers(n.task_id)) {
+                                defaultSubagentTailBus.publish(n.task_id, { type: "task_settled", taskId: n.task_id, status: n.status, ...(typeof n.seq === "number" ? { seq: n.seq } : {}), ...(n.summary ? { summary: redactSecrets(n.summary) } : {}) });
+                            }
+                            const hadRow = isFleetAgentTerminalNotification(n) ? (fleetPub?.onChildTerminal(n.sessionId ?? n.task_id, n.status, n.task_id, n.toolUseId) ?? false) : false;
+                            const parked = !resumeLegLive && Boolean(deps.workflowCompletionInbox && sessionId);
+                            deps.logger?.info?.("task_notification_observed", { route: "resume", taskId: n.task_id, taskType: n.task_type, status: n.status, hadFleetRow: hadRow, legLive: resumeLegLive, parkedDurable: parked });
+                            if (parked) {
+                                void deps.workflowCompletionInbox.enqueue(taskNotificationInboxEntry(sessionId, principal ?? null, n, Date.now(), taskId, opts?.priority)).catch((err) => deps.logger?.warn?.("park_enqueue_failed", { route: "resume", taskId: n.task_id, err: err instanceof Error ? err.message : String(err) }));
+                            }
+                            else if (resumeLegLive) {
+                                const key = taskNotificationStreamKey(n);
+                                if (resumeNotifiedKeys.get(key) === undefined) {
+                                    resumeNotifiedKeys.set(key, append("task_notification", taskNotificationEventData({ notification: n, ...(opts?.priority !== undefined ? { priority: opts.priority } : {}) })).then(() => true, () => false));
+                                }
+                            }
+                        },
+                        ...(deps.subagentSteerRegistry && taskId
+                            ? {
+                                onSubagentSpawn: (handle) => {
+                                    subagentHandleEvictions.push(deps.subagentSteerRegistry.register(taskId, handle));
+                                },
+                            }
+                            : {}),
+                    });
+                    resumeStreamRef = stream;
+                    if (taskId)
+                        steerableRuns.set(taskId, stream);
+                    if (!taskId || !rs)
+                        return await stream.result();
+                    onAccepted?.(acceptedResumingReceipt(taskId, sessionId));
+                    for await (const ev of stream) {
+                        recordTurnActivity(taskId);
+                        fleetPub?.onEvent(ev);
+                        await appendPromptManifest(append, deps.promptManifests, taskId);
+                        switch (ev.type) {
+                            case "text_delta":
+                                text += ev.delta;
+                                anchor.onText(ev.eventId);
+                                break;
+                            case "reasoning_delta": {
+                                const rb = reasoningDeltaBytes(ev);
+                                if (persistThinking && rb !== undefined) {
+                                    reasoning += rb;
+                                    reasoningEventId ??= reasoningSegmentEventId(ev.eventId);
+                                }
+                                break;
+                            }
+                            case "tool_start":
+                                anchor.onTool();
+                                await flush();
+                                await append("tool_start", toolStartEventData(ev));
+                                break;
+                            case "tool_end":
+                                await flush();
+                                await append("tool_end", toolEndEventData(ev));
+                                break;
+                            case "status": {
+                                const st = ev;
+                                deps.metrics?.inc("brain_retry_total", { phase: String(st.phase) });
+                                await flush();
+                                await append("status", brainStatusEventData(st));
+                                break;
+                            }
+                            case "context_usage":
+                                await flush();
+                                await append("context_usage", contextUsageEventData(ev));
+                                break;
+                            case "compacted":
+                                await flush();
+                                await append("compacted", compactedEventData(ev));
+                                break;
+                            case "diagnostics":
+                                await flush();
+                                await append("diagnostics", diagnosticsEventData(ev));
+                                break;
+                            case "steering_injected":
+                                await flush();
+                                await append("steering_injected", steeringInjectedEventData(ev));
+                                break;
+                            case "compaction_outcome":
+                                await flush();
+                                await append("compaction_outcome", compactionOutcomeEventData(ev));
+                                break;
+                            case "workspace_changed":
+                                await flush();
+                                await append("workspace_changed", workspaceChangedEventData(ev));
+                                break;
+                            case "wiring_manifest":
+                                await flush();
+                                await append("wiring_manifest", wiringManifestEventData(ev));
+                                break;
+                            case "tool_roster_delta": {
+                                await flush();
+                                const rosterDelta = toolRosterDeltaEventData(ev);
+                                if (rosterDelta !== undefined)
+                                    await append("tool_roster_delta", rosterDelta);
+                                break;
+                            }
+                            case "tool_disclosure": {
+                                await flush();
+                                const disclosure = toolDisclosureEventData(ev);
+                                if (disclosure !== undefined)
+                                    await append("tool_disclosure", disclosure);
+                                break;
+                            }
+                            case "human_input":
+                                await flush();
+                                await append("human_input", humanInputEventData(ev));
+                                break;
+                            case "message_committed":
+                                await anchor.onMessageCommitted(ev.role, ev.entryId);
+                                break;
+                            case "task_progress":
+                                await append("task_progress", taskProgressEventData(ev));
+                                break;
+                            case "task_notification": {
+                                await flush();
+                                const tnr = ev.notification;
+                                const tnrKey = tnr?.task_id ? taskNotificationStreamKey({ task_type: tnr.task_type, task_id: tnr.task_id, status: String(tnr.status), seq: tnr.seq }) : undefined;
+                                const tnrPrior = tnrKey !== undefined ? resumeNotifiedKeys.get(tnrKey) : undefined;
+                                if (tnrPrior === undefined || !(await tnrPrior)) {
+                                    const write = append("task_notification", taskNotificationEventData(ev));
+                                    if (tnrKey !== undefined)
+                                        resumeNotifiedKeys.set(tnrKey, write.then(() => true, () => false));
+                                    await write;
+                                }
+                                break;
+                            }
+                            case "turn_end": {
+                                await flush();
+                                await append("turn_end", turnEndEventData(ev));
+                                await appendModelUsageDelta(append, deps.modelUsage, taskId);
+                                await anchor.onTurnEnd();
+                                break;
+                            }
+                        }
+                    }
+                    await flush();
+                    const r = await stream.result();
+                    const rPark = r.terminal.kind === "paused" ? terminalProjection(r.terminal).status : undefined;
+                    if (rPark === "suspended") {
+                        const parkCallId = await parkToolCallId(r, deps.checkpointStore);
+                        await append("suspended", { gate: r.terminal.kind === "paused" ? r.terminal.gate : null, ...(parkCallId !== undefined ? { toolCallId: parkCallId } : {}) });
+                        await appendModelUsageDelta(append, deps.modelUsage, taskId);
+                        return r;
+                    }
+                    if (rPark === "needs_review") {
+                        await append("needs_review", { gate: r.terminal.kind === "paused" ? r.terminal.gate : null });
+                        await appendModelUsageDelta(append, deps.modelUsage, taskId);
+                        return r;
+                    }
+                    if (isCheckpointReopenedFailure(r) && (await confirmCheckpointReopened())) {
+                        reopenConfirmedPark = true;
+                        try {
+                            await append("suspended", { gate: null, reopened: failureCodeOf(r.terminal) ?? null });
+                            await appendModelUsageDelta(append, deps.modelUsage, taskId);
+                        }
+                        catch {
+                        }
+                        return r;
+                    }
+                    const safe = await attachModelUsage(stripResumeToken(r), { append, getEvents: (id, a) => rs.getEvents(id, a), modelUsage: deps.modelUsage, taskId });
+                    await append("done", { result: safe });
+                    if (taskConfig.suggestNextPrompts && safe.terminal.kind === "completed") {
+                        const suggestions = await stream.suggestions().catch(() => []);
+                        if (suggestions.length)
+                            await append("suggestions", { suggestions: suggestions.map((s) => redactSecrets(s)) });
+                    }
+                    return safe;
+                };
+                const approvalEmit = (frame) => {
+                    const { type, ...rest } = frame;
+                    return append(type, rest);
+                };
+                const withApproval = () => deps.toolApproval && taskId && approvalLeg.active && !approvalLeg.windowZero
+                    ? deps.toolApproval.runWithContext({
+                        taskId,
+                        owner: principal ?? null,
+                        emit: approvalEmit,
+                        abortSignal: cancelCtrl.signal,
+                        sessionId,
+                        emitCard: createApprovalCardEmitter({ appendDurable: (f) => approvalEmit(f) }),
+                        emitRevoke: (f) => approvalEmit(f),
+                        legKey,
+                        ...(legDeadlineMonotonic !== undefined ? { legDeadlineMonotonic } : {}),
+                    }, driveResume)
+                    : driveResume();
+                const withElicitation = () => deps.elicitation && taskId
+                    ? deps.elicitation.runWithContext({ taskId, owner: principal ?? null, emit: (frame) => { const { type, ...rest } = frame; return append(type, rest); }, abortSignal: cancelCtrl.signal }, withApproval)
+                    : withApproval();
+                return await (deps.sendUserFile && taskId
+                    ? deps.sendUserFile.runWithContext({ taskId, emit: async (frame) => { const { type, ...rest } = frame; await append(type, rest); } }, withElicitation)
+                    : withElicitation());
+            });
+        }
+        catch (e) {
+            if (e instanceof CheckpointError) {
+                if (e.code === "checkpoint.resume_aborted") {
+                    const cs2 = deps.checkpointStore;
+                    if (cs2) {
+                        try {
+                            const live = await cs2.get(token);
+                            if (live?.status === "pending" && !(await cs2.expire(token, live.scope))) {
+                                deps.logger?.warn?.("resume_cancel_checkpoint_settle_lost", { taskId, sessionId });
+                            }
+                        }
+                        catch (cancelSettleErr) {
+                            deps.logger?.warn?.("resume_cancel_checkpoint_settle_failed", {
+                                taskId, sessionId, err: cancelSettleErr instanceof Error ? cancelSettleErr.message : String(cancelSettleErr),
+                            });
+                        }
+                    }
+                    if (claimedRow && taskId && deps.runStore) {
+                        const c = mintCancelledResult({ taskId, sessionId, startedAtMs: resumeLegStartedAt, message: e.message });
+                        await deps.runStore.setTerminal(taskId, "failed", c, e.message).catch(() => undefined);
+                    }
+                    settleFleet("failed");
+                    return { status: 200, body: { taskId, sessionId, status: "failed", errorCode: "cancelled" } };
+                }
+                const retriable = e.code === "checkpoint.invalid_outcome" ||
+                    e.code === "checkpoint.reopen_revote" ||
+                    e.code === "checkpoint.reopened_concurrently" ||
+                    e.code === "resume.parent_constraint_missing" ||
+                    e.code === "resume.parent_constraint_mismatch" ||
+                    e.code === "resume.constraint_rejected" ||
+                    e.code === "resume.constraint_unprojectable" ||
+                    e.code === "resume.usage_window_exhausted" ||
+                    e.code === "resume.principal_mismatch" ||
+                    e.code === "resume.placement_mismatch" ||
+                    e.code === "resume.preflight_rejected" ||
+                    e.code.startsWith("wake.") ||
+                    (e.code === "checkpoint.unsupported_version" && checkpointRowRedeemableElsewhere(e.detail?.reason));
+                if (claimedRow && taskId && deps.runStore) {
+                    if (retriable && freshRunClaimed) {
+                        const c = { taskId, sessionId, terminal: { kind: "failed", code: e.code, message: e.message }, stats: { turns: 0, tokens: 0, usageMissing: true } };
+                        await deps.runStore.setTerminal(taskId, "failed", c, e.message).catch((err) => {
+                            deps.logger?.warn?.("wake_synthetic_run_release_failed", { taskId, sessionId, errorCode: e.code, error: err instanceof Error ? err.message : String(err), note: "the synthetic run row for this refused fresh-run resume could not be settled — its task_active claim is still held and the next attempt on this session will 409 conflict.session_active_run until reapStale collects it (runStaleSec)" });
+                        });
+                        settleFleet("failed");
+                    }
+                    else if (retriable) {
+                        await (outcome.gate === "plan_review" ? deps.runStore.setNeedsReview(taskId) : deps.runStore.setSuspended(taskId)).catch(() => undefined);
+                        settleFleet(outcome.gate === "plan_review" ? "needs_review" : "suspended");
+                    }
+                    else {
+                        await deps.runStore.setTerminal(taskId, "failed", null, e.message).catch(() => undefined);
+                        settleFleet("failed");
+                    }
+                }
+                const status = e.code === "checkpoint.not_found" ? 404 : 409;
+                return {
+                    status,
+                    body: {
+                        ...(taskId !== undefined ? { taskId } : {}),
+                        error: e.message,
+                        errorCode: e.code === "checkpoint.invalid_outcome"
+                            ? (outcome.gate === "policy_ask" ? "approval_binding_mismatch" : "resume_outcome_invalid")
+                            : e.code,
+                        ...(e.detail?.field ? { field: e.detail.field } : {}),
+                        ...((e.code === "resume.usage_window_exhausted" || e.code === "resume.preflight_rejected") && typeof e.detail?.retryAfterMs === "number" && Number.isFinite(e.detail.retryAfterMs) && e.detail.retryAfterMs > 0
+                            ? { retryAfterSec: Math.max(1, Math.ceil(e.detail.retryAfterMs / 1000)) }
+                            : {}),
+                        ...(retriable ? { retriable: true } : {}),
+                    },
+                };
+            }
+            if (cancelCtrl.signal.aborted) {
+                if (taskId && deps.runStore) {
+                    const c = mintCancelledResult({ taskId, sessionId, startedAtMs: resumeLegStartedAt, message: "cancelled by user" });
+                    await deps.runStore.setTerminal(taskId, "failed", c, "cancelled by user").catch(() => undefined);
+                }
+                settleFleet("failed");
+                return { status: 200, body: { taskId, sessionId, status: "failed", errorCode: "cancelled" } };
+            }
+            if (claimedRow && taskId && deps.runStore) {
+                await deps.runStore.setTerminal(taskId, "failed", null, errorText(e)).catch(() => undefined);
+            }
+            settleFleet("failed");
+            throw e;
+        }
+        finally {
+            unregisterEngineNotice?.();
+            if (taskId) {
+                if (inflightRuns.get(taskId) === cancelCtrl)
+                    inflightRuns.delete(taskId);
+                if (preemptableRuns.get(taskId) === preemptCtrl)
+                    preemptableRuns.delete(taskId);
+                if (resumeStreamRef !== undefined && steerableRuns.get(taskId) === resumeStreamRef)
+                    steerableRuns.delete(taskId);
+                for (const evict of subagentHandleEvictions)
+                    evict();
+                deps.modelUsage?.clear(taskId);
+                deps.promptManifests?.clear(taskId, resumeManifestLease);
+            }
+            if (resumeHeartbeat)
+                clearInterval(resumeHeartbeat);
+            resumeLegLive = false;
+        }
+        evictIfConflict(deps.runner, sessionId, result);
+        const checkpointReopened = reopenConfirmedPark;
+        const resumePlane = terminalProjection(result.terminal);
+        if (taskId && deps.runStore) {
+            if (resumePlane.status === "suspended" || checkpointReopened)
+                await deps.runStore.setSuspended(taskId);
+            else if (resumePlane.status === "needs_review")
+                await deps.runStore.setNeedsReview(taskId);
+            else
+                await deps.runStore.setTerminal(taskId, resumePlane.status, stripResumeToken(result), resumePlane.errorMessage ?? null);
+        }
+        settleFleet(checkpointReopened ? "suspended" : resumePlane.status, fleetRunResiduals(result));
+        return {
+            status: 200,
+            body: {
+                taskId, sessionId, status: resumePlane.status,
+                bindingEnforced: true,
+                ...(resumePlane.errorCode ? { errorCode: resumePlane.errorCode } : {}),
+                ...(resumePlane.errorMessage ? { errorMessage: redactErrorMessage(resumePlane.errorMessage) ?? "" } : {}),
+                ...(checkpointReopened ? { retriable: true } : {}),
+            },
+        };
+    }
+    async function mayDiscloseRowError(cs, token, decider) {
+        if (decider === undefined || decider.explicitOperator)
+            return true;
+        let scope;
+        try {
+            scope = await cs.peekScopeByToken(token);
+        }
+        catch (e) {
+            deps.logger?.warn?.("checkpoint_owner_probe_unreadable", { note: "peekScopeByToken failed — row-error disclosure withheld (fail-closed)", err: e instanceof Error ? e.message : String(e) });
+            return false;
+        }
+        if (scope === undefined)
+            return false;
+        const owner = decodeCheckpointScope(scope ?? CHECKPOINT_PUBLIC_SCOPE);
+        return owner === undefined || owner === decider.principal;
+    }
+    async function resumePreempted(sessionId, req, acceptEarly, decider) {
+        const cs = deps.checkpointStore;
+        const RESUMABLE_GATE_KIND = "resource_limit";
+        const preemptBinding = { gateKinds: [RESUMABLE_GATE_KIND] };
+        const token = (await cs.findPendingTokenBySession(sessionId, undefined, preemptBinding)) ?? (await cs.findPendingTokenBySession(sessionId));
+        const noSuspension = { status: 404, body: { error: "no resumable suspension for this task (already running, resumed, or expired)", errorCode: "not_found.suspension" } };
+        if (!token)
+            return noSuspension;
+        if (decider !== undefined && !decider.explicitOperator) {
+            const peeked = await cs
+                .peekPendingScope(sessionId, preemptBinding)
+                .then((sc) => (sc === undefined ? cs.peekPendingScope(sessionId) : sc))
+                .catch(() => undefined);
+            const peekedOwner = peeked != null ? decodeCheckpointScope(peeked) : undefined;
+            if (peekedOwner !== undefined && peekedOwner !== decider.principal) {
+                deps.logger?.warn?.("assistant_resume_row_scope_mismatch", { sessionId, note: "pending row is foreign to the verified caller — owner gate ahead of the row load" });
+                return noSuspension;
+            }
+        }
+        let cp;
+        try {
+            cp = await cs.get(token);
+        }
+        catch (e) {
+            if (!(await mayDiscloseRowError(cs, token, decider))) {
+                deps.logger?.warn?.("assistant_resume_unreadable_row_withheld", { sessionId, note: "row unreadable and the caller's ownership of THAT token is unproven — folded into the uniform 404" });
+                return noSuspension;
+            }
+            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+        }
+        if (!cp) {
+            if (!(await mayDiscloseRowError(cs, token, decider)))
+                return noSuspension;
+            return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+        }
+        if (decider !== undefined && !decider.explicitOperator && cp.scope !== CHECKPOINT_PUBLIC_SCOPE && cp.scope !== decider.principal) {
+            deps.logger?.warn?.("assistant_resume_row_scope_mismatch", { sessionId, note: "loaded pending row is foreign to the verified caller — TOCTOU fold" });
+            return noSuspension;
+        }
+        const gateKind = cp.gate?.kind;
+        if (gateKind !== RESUMABLE_GATE_KIND) {
+            return { status: 409, body: { error: `task is suspended on a '${gateKind ?? "unknown"}' gate, not a resumable resource/preempt suspension — an approval gate must be decided via POST /v1/approvals/:id/decide`, errorCode: "gate_not_resumable" } };
+        }
+        const ctx = await cs.getCtx(sessionId).catch(() => null);
+        if (!ctx)
+            return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
+        const { spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth);
+        const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
+        const verifyRounds = verifyRoundsFromBody(ctx.body);
+        return driveResumeIntoRunLog({ runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome: { gate: "resource_limit", decision: "continue" }, verifyRounds, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
+    }
+    async function startFreshHostTurn(sessionId, objective, principal, req, trustedInternals, runId) {
+        const cs = deps.checkpointStore;
+        if (!deps.runStore) {
+            return { status: 501, body: { error: "delivering a workflow decision on the host's next turn requires a durable run store (DB_BACKEND=mysql|pg|local)", errorCode: "capability.run_store_required" } };
+        }
+        const ctx = await cs.getCtx(sessionId).catch(() => null);
+        if (!ctx) {
+            return {
+                status: 409,
+                body: {
+                    error: "the workflow's originating session no longer has the rebuild inputs for a new turn: a session's resume context is garbage-collected once it is stale AND that session itself has no pending checkpoint and no active run (REAP_RUN_STALE_SEC, default 120s) — a workflow CHILD's park does not hold the HOST session's row open. Raise REAP_RUN_STALE_SEC to cover how long approvals may sit before someone decides them, or resume the workflow run yourself with the runId below",
+                    errorCode: "conflict.resume_context_unavailable",
+                    runId,
+                },
+            };
+        }
+        const windowDenial = await usageWindowDenialFor(principal || GLOBAL_USAGE_KEY);
+        if (windowDenial)
+            return { status: windowDenial.status, body: windowDenial.body };
+        const auth = { sessionId, principal, memoryScope: ctx.memoryScope };
+        let spec;
+        let engineNotices = [];
+        try {
+            ({ spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth));
+        }
+        catch (e) {
+            if (e instanceof HttpError) {
+                return { status: 409, body: { error: `resume blocked by an admission policy change: ${e.message}`, errorCode: "resume_blocked_by_policy", ...(e.code ? { blockedBy: e.code } : {}), ...(e.extra ?? {}) } };
+            }
+            throw e;
+        }
+        const hostSpec = { ...spec, objective, sessionId };
+        const out = await mintAndDriveDurableRun(routeCtxBase, deps.runStore, {
+            prepared: { spec: hostSpec, runner: runnerFor(hostSpec), auth, body: ctx.body, ...(engineNotices.length > 0 ? { engineNotices } : {}) },
+            fleetScope: resumeFleetScope(req, auth),
+            elicitOwner: principal ?? null,
+            source: "workflow_parked_decide",
+            trustedInternals,
+        });
+        if (out.status !== 202)
+            return { status: out.status, body: out.body };
+        const minted = out.body;
+        return acceptedResumingReceipt(minted.taskId, minted.sessionId);
+    }
+    async function resumeWake(sessionId, message, caller, req, acceptEarly, workflowParkedResume, ownerLeaseAdmittedFor) {
+        const cs = deps.checkpointStore;
+        const wakeBinding = { gateKinds: TERMINAL_PARK_GATE_KINDS, pick: "oldest" };
+        const token = (await cs.findPendingTokenBySession(sessionId, undefined, wakeBinding)) ?? (await cs.findPendingTokenBySession(sessionId));
+        if (!token)
+            return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
+        const operator = explicitOperatorOk(caller, deps.config.operatorPrincipals);
+        if (!operator) {
+            const scope = await cs.peekPendingScope(sessionId, wakeBinding).then((s) => (s === undefined ? cs.peekPendingScope(sessionId) : s)).catch(() => undefined);
+            const decodedScope = scope != null ? decodeCheckpointScope(scope) : undefined;
+            if (decodedScope !== undefined && decodedScope !== caller) {
+                return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
+            }
+        }
+        let cp;
+        try {
+            cp = await cs.get(token);
+        }
+        catch (e) {
+            if (!(await mayDiscloseRowError(cs, token, { principal: caller, explicitOperator: operator }))) {
+                deps.logger?.warn?.("wake_unreadable_row_withheld", { sessionId, note: "row unreadable and the caller's ownership of THAT token is unproven — folded into the uniform 404" });
+                return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
+            }
+            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+        }
+        if (!cp) {
+            if (!(await mayDiscloseRowError(cs, token, { principal: caller, explicitOperator: operator }))) {
+                return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
+            }
+            return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+        }
+        if (!operator && cp.scope !== CHECKPOINT_PUBLIC_SCOPE && cp.scope !== caller) {
+            return { status: 404, body: { error: "no parked checkpoint for this session (nothing to wake)", errorCode: "not_found.parked_checkpoint" } };
+        }
+        const gateKind = cp.gate?.kind;
+        if (gateKind !== "task_done") {
+            return { status: 409, body: { error: `cannot wake: this checkpoint awaits a pending gate decision (gate "${gateKind ?? "unknown"}") — resolve it through its own decide entry`, errorCode: "wake.gate_pending" } };
+        }
+        const trusted = operator;
+        if (message !== undefined) {
+            try {
+                validatePendingSteer({ text: message, trusted });
+            }
+            catch (e) {
+                if (e instanceof CheckpointError && e.code === "steering.invalid_content") {
+                    return { status: 422, body: { errorCode: "steering.invalid_content", error: e.message } };
+                }
+                throw e;
+            }
+        }
+        const ctx = await cs.getCtx(sessionId).catch(() => null);
+        if (!ctx)
+            return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
+        const { spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth);
+        const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
+        return driveResumeIntoRunLog({
+            runner: runnerFor(spec),
+            token,
+            sessionId: cp.sessionId,
+            principal: auth.principal,
+            fleetScope: resumeFleetScope(req, auth),
+            taskConfig,
+            resumeObjective,
+            outcome: { gate: "wake", ...(message !== undefined ? { message: { text: message, trusted } } : {}) },
+            verifyRounds: undefined,
+            mintFreshRun: { source: "wake" },
+            ...(engineNotices.length > 0 ? { engineNotices } : {}),
+            ...(acceptEarly === true ? { acceptEarly: true } : {}),
+            ...(req !== undefined ? { callerInitiated: true } : {}),
+            ...(workflowParkedResume !== undefined ? { workflowParkedResume } : {}),
+            ...(ownerLeaseAdmittedFor !== undefined && auth.principal === ownerLeaseAdmittedFor ? { ownerLeaseAdmitted: true } : {}),
+        });
+    }
+    async function resumePlanReview(sessionId, decision, editedPlan, reason, req, log, acceptEarly, decider) {
+        const cs = deps.checkpointStore;
+        const log404 = (r) => deps.logger?.info?.("decide_404", {
+            reason: r,
+            ...(log?.taskId !== undefined ? { taskId: log.taskId } : { sessionId }),
+            ...(log?.principalPresent !== undefined ? { principalPresent: log.principalPresent } : {}),
+        });
+        const PLAN_REVIEW_GATE_KIND = "plan_review";
+        const planReviewBinding = { gateKinds: [PLAN_REVIEW_GATE_KIND] };
+        const token = (await cs.findPendingTokenBySession(sessionId, undefined, planReviewBinding)) ?? (await cs.findPendingTokenBySession(sessionId));
+        const noPending = { status: 404, body: { error: "no pending plan_review for this session (already decided or expired)", errorCode: "not_found.plan_review" } };
+        if (!token) {
+            log404("no-pending-checkpoint");
+            return noPending;
+        }
+        if (decider !== undefined && !decider.explicitOperator) {
+            const peeked = await cs
+                .peekPendingScope(sessionId, planReviewBinding)
+                .then((sc) => (sc === undefined ? cs.peekPendingScope(sessionId) : sc))
+                .catch(() => undefined);
+            const peekedOwner = peeked != null ? decodeCheckpointScope(peeked) : undefined;
+            if (peekedOwner !== undefined && peekedOwner !== decider.principal) {
+                deps.logger?.warn?.("plan_review_row_scope_mismatch", { sessionId, note: "pending row is foreign to the verified caller — owner gate ahead of the row load" });
+                return noPending;
+            }
+        }
+        let cp;
+        try {
+            cp = await cs.get(token);
+        }
+        catch (e) {
+            if (!(await mayDiscloseRowError(cs, token, decider))) {
+                deps.logger?.warn?.("plan_review_unreadable_row_withheld", { sessionId, note: "row unreadable and the caller's ownership of THAT token is unproven — folded into the uniform 404" });
+                return noPending;
+            }
+            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+        }
+        if (!cp) {
+            log404("checkpoint-missing");
+            if (!(await mayDiscloseRowError(cs, token, decider)))
+                return noPending;
+            return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+        }
+        if (decider !== undefined && !decider.explicitOperator && cp.scope !== CHECKPOINT_PUBLIC_SCOPE && cp.scope !== decider.principal) {
+            deps.logger?.warn?.("plan_review_row_scope_mismatch", { sessionId, note: "loaded pending row is foreign to the verified caller — TOCTOU fold" });
+            return noPending;
+        }
+        const gateKind = cp.gate?.kind;
+        if (gateKind !== PLAN_REVIEW_GATE_KIND) {
+            return {
+                status: 409,
+                body: {
+                    error: `task is suspended on a '${gateKind ?? "unknown"}' gate, not a plan_review — a tool approval must be decided via POST /v1/approvals/:id/decide`,
+                    errorCode: "gate_not_plan_review",
+                },
+            };
+        }
+        const ctx = await cs.getCtx(sessionId).catch(() => null);
+        if (!ctx)
+            return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+        const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
+        const { spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth);
+        const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
+        const verifyRounds = verifyRoundsFromBody(ctx.body);
+        const outcome = {
+            gate: "plan_review",
+            decision,
+            ...(editedPlan !== undefined ? { editedPlan } : {}),
+            ...(reason ? { reason } : {}),
+        };
+        return driveResumeIntoRunLog({ runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, verifyRounds, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
+    }
+    const routeCtxBase = {
+        deps,
+        registry: { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters },
+        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk },
+        local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal() },
+        legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, resumePlanReview },
+    };
+    return { routeCtxBase, resumeCheckpoint, driveResumeIntoRunLog, driveResumeLeg, mayDiscloseRowError, resumePreempted, startFreshHostTurn, resumeWake, resumePlanReview };
+}
+//# sourceMappingURL=resume-legs.js.map