@sema-agent/server 7.132.0 → 7.133.0

package/dist/http/resume-legs.js

@@ -1,7 +1,9 @@
 import { redactErrorMessage, redactHead } from "../observability/run-terminal.js";
 import { createHash } from "node:crypto";
 import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, taskNotificationDedupKey, validatePendingSteer, GLOBAL_USAGE_KEY, PAUSE_REGISTRY } from "@sema-agent/core";
-import { decideParkedAgent, denyWorkflowParkForked, denyWorkflowParksUnreadable, findParkOrigin, planWorkflowParkedDecide } from "../parked-decide.js";
+import { decideParkedAgent, denyWorkflowParkForked, denyWorkflowParksUnreadable, findParkOrigin, heldWorkflowParkDecisions, planWorkflowParkedDecide } from "../parked-decide.js";
+import { parkDecisionFingerprint } from "../orchestration/workflow-park-decision.js";
+const DELIVERY_NOT_RECORDED = "workflow park decide: this delivery no longer holds the host session (its claim was released) — the decision was not recorded and this delivery was not started";
 const sessionFaceUnavailable = async (sessionId) => {
     throw new Error(`parked decide cannot verify which occupant session ${sessionId} belongs to: this deployment's session store has no sessionFaceOf read (every built-in store has one) — refusing rather than resuming unverified`);
 };
@@ -9,6 +11,7 @@ import { HttpError, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE } from "../se
 import { parkToolCallId, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
 import { failureCodeOf, nestedPauseOf, sealResultForExit, outwardPlane } from "../terminal.js";
 import { buildCancelledLedgerRow, createRunAbort, mintCancelledResult } from "../run-cancel-context.js";
+import { isTerminalRunStatus } from "../plugins/store-contracts.js";
 import { readTurnActivityMs, recordTurnActivity } from "../turn-activity.js";
 import { recordResumeResourceWindow } from "../resource-window.js";
 import { emitPendingWorkflowCompletions, taskNotificationInboxEntry, taskNotificationStreamKeyOf, NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
@@ -32,7 +35,7 @@ import { errorText } from "../observability/err-text.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { verifyRoundsFromBody } from "./verify-rounds.js";
 import { planReviewDecisionExitsPlan, storedBodyPermissionMode } from "../task-settings.js";
-import { acceptedResumingReceipt, buildHostLegOutcome } from "./route-ctx.js";
+import { acceptedResumingReceipt, acceptedTaskIdOf, buildHostLegOutcome } from "./route-ctx.js";
 import { mintAndDriveDurableRun } from "./durable-run-leg.js";
 import { createSessionsLocal } from "./routes/sessions.js";
 import { createSessionSyncLocal } from "./routes/session-sync.js";
@@ -50,6 +53,7 @@ import { refusalBody } from "./refusal-body.js";
 import { storedBodyReplayRefusal } from "./stored-body-replay.js";
 import { httpErrorRefusal } from "./send.js";
 import { createRunAcceptance } from "../run-acceptance.js";
+import { fieldConflictFacts } from "../field-conflict.js";
 function legMayHaveReopenedCheckpoint(r) {
     return r.terminal.kind === "failed" && nestedPauseOf(r.terminal) === undefined;
 }
@@ -170,7 +174,7 @@ function decisionRefusalCauseOf(e, gate) {
     return role === undefined ? undefined : FIELD_ROLE_CAUSE[role];
 }
 function notResumableAnswer() {
-    return { status: 409, body: { error: "run is not in a resumable (suspended) state (already resumed, decided, or expired)", errorCode: "conflict.not_resumable" } };
+    return { status: 409, body: refusalBody({ errorCode: "conflict.not_resumable", message: "run is not in a resumable (suspended) state (already resumed, decided, or expired)" }) };
 }
 export function checkpointRefusalAnswer(e, at) {
     const refusalCause = e.code === "checkpoint.invalid_outcome" ? decisionRefusalCauseOf(e, at.gate) : undefined;
@@ -212,7 +216,7 @@ export function createResumeLegs(ctx) {
             }
             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" } };
+                return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
             }
             let currentPending;
             if (token && decider !== undefined) {
@@ -225,7 +229,7 @@ export function createResumeLegs(ctx) {
                 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" } };
+                    return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
                 }
                 if (cur && cur.status === "pending" && cur.sessionId === sessionId && scopeOk && curPa?.kind === "tool_approval" && curPa.toolCallId) {
                     currentPending = {
@@ -237,22 +241,24 @@ export function createResumeLegs(ctx) {
             }
             return {
                 status: 409,
-                body: {
-                    error: "the approval you are deciding is no longer current (already resolved or superseded since you viewed it)",
+                body: refusalBody({
                     errorCode: "approval_stale",
-                    ...(attributable ? { terminal: "resolved" } : {}),
-                    ...(currentPending ? { currentPending } : {}),
-                },
+                    message: "the approval you are deciding is no longer current (already resolved or superseded since you viewed it)",
+                    facts: {
+                        ...(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" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         }
         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" } };
+        const noApproval = { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
         let cp;
         try {
             cp = await cpPromise;
@@ -263,18 +269,18 @@ export function createResumeLegs(ctx) {
                 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" } };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) };
         }
         if (!cp) {
             if (!(await mayDiscloseRowError(cs, token, decider)))
                 return noApproval;
-            return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.checkpoint", message: "checkpoint not found" }) };
         }
         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" } };
+                return { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
             }
         }
         const decideGateKind = cp.gate?.kind;
@@ -287,21 +293,25 @@ export function createResumeLegs(ctx) {
                 : 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`,
+                body: refusalBody({
                     errorCode: "gate_not_tool_approval",
-                    ...(decideGateKind ? { pendingGate: { kind: decideGateKind, ...(gnPath ? { decidePath: gnPath } : {}) } } : {}),
-                },
+                    message: `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`,
+                    facts: {
+                        ...(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)",
+                body: refusalBody({
                     errorCode: "decide_requires_binding",
-                    bindingEnforced: true,
-                },
+                    message: "decide requires the decision-action binding — echo checkpointToken and/or boundCallId from the pending approval (GET /v1/approvals)",
+                    facts: {
+                        bindingEnforced: true,
+                    },
+                }),
             };
         }
         const s57RowCallId = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction.toolCallId : undefined;
@@ -316,11 +326,13 @@ export function createResumeLegs(ctx) {
             }
             return {
                 status: 409,
-                body: {
-                    error: "the approval you are deciding is no longer current (already resolved or superseded since you viewed it)",
+                body: refusalBody({
                     errorCode: "approval_stale",
-                    ...(s57CurrentPending ? { currentPending: s57CurrentPending } : {}),
-                },
+                    message: "the approval you are deciding is no longer current (already resolved or superseded since you viewed it)",
+                    facts: {
+                        ...(s57CurrentPending ? { currentPending: s57CurrentPending } : {}),
+                    },
+                }),
             };
         }
         const paForGrant = cp.pendingAction.kind === "tool_approval" ? cp.pendingAction : undefined;
@@ -407,14 +419,48 @@ export function createResumeLegs(ctx) {
                 const plan = planWorkflowParkedDecide(origin, parkedReq);
                 if (!plan.ok)
                     return plan.deny;
-                const parkedResume = { workflowParkedResume: [{ runId: plan.runId, token, outcome: plan.outcome }] };
+                const decisions = deps.workflowParkDecisions;
+                const runStore = deps.runStore;
+                if (decisions === undefined || runStore === undefined) {
+                    return { status: 501, body: refusalBody({ errorCode: "capability.run_store_required", message: "delivering this decision requires a durable run store (DB_BACKEND=mysql|pg|local)" }) };
+                }
+                const fingerprint = parkDecisionFingerprint(plan.outcome);
+                const liveReceiptOf = async (held) => {
+                    if (held === null || held.fingerprint !== fingerprint)
+                        return undefined;
+                    const run = await runStore.getRun(held.deliveredTaskId);
+                    return run != null && !isTerminalRunStatus(run.status) ? acceptedResumingReceipt(held.deliveredTaskId, held.hostSessionId) : undefined;
+                };
+                const replay = await liveReceiptOf(await decisions.get(token));
+                if (replay !== undefined)
+                    return replay;
+                let recordFailure;
+                const delivery = {
+                    carried: [{ runId: plan.runId, token, outcome: plan.outcome }],
+                    commitBeforeLaunch: async (deliveredTaskId) => {
+                        try {
+                            const recorded = await decisions.record({ token, runId: plan.runId, hostSessionId: plan.hostSessionId, outcome: plan.outcome, fingerprint, deliveredTaskId, acceptedAtMs: Date.now() });
+                            if (!recorded)
+                                throw new Error(DELIVERY_NOT_RECORDED);
+                        }
+                        catch (err) {
+                            recordFailure = { err };
+                            throw err;
+                        }
+                    },
+                };
                 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);
+                const out = hostToken
+                    ? await resumeWake(plan.hostSessionId, plan.message, decider?.principal, req, acceptEarly, delivery, admittedPayer)
+                    : await startFreshHostTurn(plan.hostSessionId, plan.message, admittedPayer, req, delivery, plan.runId);
+                if (recordFailure !== undefined)
+                    throw recordFailure.err;
+                if (acceptedTaskIdOf(out) === undefined)
+                    return (await liveReceiptOf(await decisions.get(token))) ?? out;
+                return out;
             }
         }
         const ctxRead0 = await readResumeCtx(ctxPromise);
@@ -422,7 +468,7 @@ export function createResumeLegs(ctx) {
             return resumeCtxCorruptAnswer(ctxRead0.where);
         const ctx = ctxRead0.kind === "ok" ? ctxRead0.ctx : null;
         if (!ctx)
-            return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.resume_context_unavailable", message: "resume context missing — cannot rebuild task config" }) };
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         const resolved = await resolveResumeSpecOrBlocked(ctx, req, auth);
         if (!resolved.ok)
@@ -430,10 +476,10 @@ export function createResumeLegs(ctx) {
         const { spec, engineNotices } = resolved;
         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" } };
+            return { status: 400, body: refusalBody({ errorCode: "request.field_conflict", message: "pending action is AskUserQuestion — approve must carry body.answer ({ answers: [{ header, selected: string[], note? }] })", facts: { ...fieldConflictFacts("ask_answer", ["decision", "answer"]) } }) };
         }
         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" } };
+            return { status: 400, body: refusalBody({ errorCode: "request.field_conflict", message: `body.answer is only valid when approving a pending AskUserQuestion (decision: "${decision}", pending: "${pendingTool ?? "unknown"}")`, facts: { ...fieldConflictFacts("ask_answer", ["answer", "decision"]) } }) };
         }
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
         const pa = cp.pendingAction;
@@ -533,6 +579,7 @@ export function createResumeLegs(ctx) {
         const ownerLeaseDenial = args.callerInitiated === true && args.ownerLeaseAdmitted !== true ? await ownerFleetLeaseDenied(principal) : undefined;
         if (ownerLeaseDenial)
             return ownerLeaseDenial;
+        const heldDecisions = await heldWorkflowParkDecisions(deps, sessionId, args.workflowDecision?.carried);
         let taskId = await deps.runStore?.getActiveTaskId(sessionId);
         let freshRunClaimed = false;
         if (args.mintFreshRun && taskId && deps.runStore) {
@@ -654,6 +701,14 @@ export function createResumeLegs(ctx) {
             deps.modelUsage?.register(taskId);
             resumeManifestLease = deps.promptManifests?.register(taskId) ?? 0;
         }
+        if (args.workflowDecision !== undefined && taskId === undefined) {
+            throw new Error("workflow decision delivery: no run row was claimed for the delivering leg — refusing to start a delivery whose decision could not be recorded against it");
+        }
+        const workflowDecision = args.workflowDecision;
+        const launchInternals = {
+            ...heldDecisions,
+            ...(workflowDecision !== undefined && taskId !== undefined ? { afterCheckpointResolve: () => workflowDecision.commitBeforeLaunch(taskId) } : {}),
+        };
         commitSessionInheritEnv(deps, sessionId, resumeCtx.ctx.body);
         if (args.onResumeCommitted)
             await args.onResumeCommitted();
@@ -689,6 +744,7 @@ export function createResumeLegs(ctx) {
                     cancelLedgerAppend = vAppend;
                     const verifyTailContentMode = resumeTaskConfig.forwardSubagentEvents === true ? "on" : "progress_only";
                     const verifyInternals = {
+                        ...launchInternals,
                         ...(taskId ? { onActivity: () => recordTurnActivity(taskId) } : {}),
                         onForwardEvent: (e) => {
                             fleetPub?.onForwardEvent(e);
@@ -817,7 +873,7 @@ export function createResumeLegs(ctx) {
                     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 } : {}),
+                        ...launchInternals,
                         onForwardEvent: (e) => {
                             fleetPub?.onForwardEvent(e);
                             {
@@ -1045,7 +1101,6 @@ export function createResumeLegs(ctx) {
                     ? deps.toolApproval.runWithContext({
                         taskId,
                         owner: principal ?? null,
-                        emit: approvalEmit,
                         abortSignal: cancelCtrl.signal,
                         sessionId,
                         emitCard: createApprovalCardEmitter({ appendDurable: (f) => approvalEmit(f) }),
@@ -1181,7 +1236,7 @@ export function createResumeLegs(ctx) {
         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" } };
+        const noSuspension = { status: 404, body: refusalBody({ errorCode: "not_found.suspension", message: "no resumable suspension for this task (already running, resumed, or expired)" }) };
         if (!token)
             return noSuspension;
         if (decider !== undefined && !decider.explicitOperator) {
@@ -1204,12 +1259,12 @@ export function createResumeLegs(ctx) {
                 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" } };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) };
         }
         if (!cp) {
             if (!(await mayDiscloseRowError(cs, token, decider)))
                 return noSuspension;
-            return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.checkpoint", message: "checkpoint not found" }) };
         }
         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" });
@@ -1217,13 +1272,13 @@ export function createResumeLegs(ctx) {
         }
         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" } };
+            return { status: 409, body: refusalBody({ errorCode: "gate_not_resumable", message: `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` }) };
         }
         const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
         if (ctxRead.kind === "corrupt")
             return resumeCtxCorruptAnswer(ctxRead.where);
         if (ctxRead.kind === "absent")
-            return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.resume_context_unavailable", message: "resume context missing — cannot rebuild task config" }) };
         const ctx = ctxRead.ctx;
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         const resolved = await resolveResumeSpecOrBlocked(ctx, req, auth);
@@ -1234,10 +1289,10 @@ export function createResumeLegs(ctx) {
         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, resumeCtx: { sessionId, ctx }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
     }
-    async function startFreshHostTurn(sessionId, objective, principal, req, trustedInternals, runId) {
+    async function startFreshHostTurn(sessionId, objective, principal, req, workflowDecision, runId) {
         const cs = deps.checkpointStore;
         if (!deps.runStore) {
-            return { status: 501, body: { error: "delivering this decision requires a durable run store (DB_BACKEND=mysql|pg|local)", errorCode: "capability.run_store_required" } };
+            return { status: 501, body: refusalBody({ errorCode: "capability.run_store_required", message: "delivering this decision requires a durable run store (DB_BACKEND=mysql|pg|local)" }) };
         }
         const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
         if (ctxRead.kind === "corrupt")
@@ -1246,12 +1301,14 @@ export function createResumeLegs(ctx) {
         if (!ctx) {
             return {
                 status: 409,
-                body: {
-                    error: "this approval waited too long to be delivered: the session this run was started from no longer keeps what a new turn would need, because that state is dropped once the session has been idle past this deployment's retention window (REAP_RUN_STALE_SEC — its current value is staleAfterSec below). Nothing was decided and the approval is still pending: resume the run yourself with the runId below, or ask whoever operates this deployment to raise REAP_RUN_STALE_SEC so approvals can sit longer before someone decides them",
+                body: refusalBody({
                     errorCode: "conflict.resume_context_unavailable",
-                    runId,
-                    staleAfterSec: deps.config.runStaleSec,
-                },
+                    message: "this approval waited too long to be delivered: the session this run was started from no longer keeps what a new turn would need, because that state is dropped once the session has been idle past this deployment's retention window (REAP_RUN_STALE_SEC — its current value is staleAfterSec below). Nothing was decided and the approval is still pending: resume the run yourself with the runId below, or ask whoever operates this deployment to raise REAP_RUN_STALE_SEC so approvals can sit longer before someone decides them",
+                    facts: {
+                        runId,
+                        staleAfterSec: deps.config.runStaleSec,
+                    },
+                }),
             };
         }
         const windowDenial = await usageWindowDenialFor(principal || GLOBAL_USAGE_KEY);
@@ -1268,7 +1325,7 @@ export function createResumeLegs(ctx) {
             fleetScope: resumeFleetScope(req, auth),
             elicitOwner: principal ?? null,
             source: "workflow_parked_decide",
-            trustedInternals,
+            workflowDecision,
         });
         if (out.existing) {
             throw new Error(`decide host turn: createRun observed an existing row ${out.existing.taskId} for a freshly minted taskId (no idempotency key was sent)`);
@@ -1278,18 +1335,18 @@ export function createResumeLegs(ctx) {
         const minted = out.body;
         return acceptedResumingReceipt(minted.taskId, minted.sessionId);
     }
-    async function resumeWake(sessionId, message, caller, req, acceptEarly, workflowParkedResume, ownerLeaseAdmittedFor) {
+    async function resumeWake(sessionId, message, caller, req, acceptEarly, workflowDecision, 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);
+            return { status: 404, body: refusalBody({ errorCode: "not_found.parked_checkpoint", message: "no parked checkpoint for this session (nothing to wake)" }) };
+        const operator = explicitOperatorOk(caller, deps.config);
         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" } };
+                return { status: 404, body: refusalBody({ errorCode: "not_found.parked_checkpoint", message: "no parked checkpoint for this session (nothing to wake)" }) };
             }
         }
         let cp;
@@ -1299,22 +1356,22 @@ export function createResumeLegs(ctx) {
         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: 404, body: refusalBody({ errorCode: "not_found.parked_checkpoint", message: "no parked checkpoint for this session (nothing to wake)" }) };
             }
-            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) };
         }
         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: refusalBody({ errorCode: "not_found.parked_checkpoint", message: "no parked checkpoint for this session (nothing to wake)" }) };
             }
-            return { status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.checkpoint", message: "checkpoint not found" }) };
         }
         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" } };
+            return { status: 404, body: refusalBody({ errorCode: "not_found.parked_checkpoint", message: "no parked checkpoint for this session (nothing to wake)" }) };
         }
         const gateKind = cp.gate?.kind;
         if (gateKind !== "task_done") {
-            return { status: 409, body: { error: `cannot wake: this session is waiting on a pending gate decision (gate "${gateKind ?? "unknown"}") — resolve it through its own decide entry`, errorCode: "wake.gate_pending" } };
+            return { status: 409, body: refusalBody({ errorCode: "wake.gate_pending", message: `cannot wake: this session is waiting on a pending gate decision (gate "${gateKind ?? "unknown"}") — resolve it through its own decide entry` }) };
         }
         const trusted = operator;
         if (message !== undefined) {
@@ -1323,7 +1380,7 @@ export function createResumeLegs(ctx) {
             }
             catch (e) {
                 if (e instanceof CheckpointError && e.code === "steering.invalid_content") {
-                    return { status: 422, body: { errorCode: "steering.invalid_content", error: e.message } };
+                    return { status: 422, body: refusalBody({ errorCode: "steering.invalid_content", message: e.message }) };
                 }
                 throw e;
             }
@@ -1332,7 +1389,7 @@ export function createResumeLegs(ctx) {
         if (ctxRead.kind === "corrupt")
             return resumeCtxCorruptAnswer(ctxRead.where);
         if (ctxRead.kind === "absent")
-            return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.resume_context_unavailable", message: "resume context missing — cannot rebuild task config" }) };
         const ctx = ctxRead.ctx;
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         const resolved = await resolveResumeSpecOrBlocked(ctx, req, auth);
@@ -1352,10 +1409,10 @@ export function createResumeLegs(ctx) {
             verifyRounds: undefined,
             resumeCtx: { sessionId, ctx },
             mintFreshRun: { source: "wake" },
+            ...(workflowDecision !== undefined ? { workflowDecision } : {}),
             ...(engineNotices.length > 0 ? { engineNotices } : {}),
             ...(acceptEarly === true ? { acceptEarly: true } : {}),
             ...(req !== undefined ? { callerInitiated: true } : {}),
-            ...(workflowParkedResume !== undefined ? { workflowParkedResume } : {}),
             ...(ownerLeaseAdmittedFor !== undefined && auth.principal === ownerLeaseAdmittedFor ? { ownerLeaseAdmitted: true } : {}),
         }));
     }
@@ -1370,7 +1427,7 @@ export function createResumeLegs(ctx) {
         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" } };
+        const noPending = { status: 404, body: refusalBody({ errorCode: "not_found.plan_review", message: "no pending plan_review for this session (already decided or expired)" }) };
         if (!token) {
             log404("no-pending-checkpoint");
             return refuse(noPending);
@@ -1395,13 +1452,13 @@ export function createResumeLegs(ctx) {
                 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 refuse(noPending);
             }
-            return refuse({ status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } });
+            return refuse({ status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) });
         }
         if (!cp) {
             log404("checkpoint-missing");
             if (!(await mayDiscloseRowError(cs, token, decider)))
                 return refuse(noPending);
-            return refuse({ status: 404, body: { error: "checkpoint not found", errorCode: "not_found.checkpoint" } });
+            return refuse({ status: 404, body: refusalBody({ errorCode: "not_found.checkpoint", message: "checkpoint not found" }) });
         }
         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" });
@@ -1411,17 +1468,17 @@ export function createResumeLegs(ctx) {
         if (gateKind !== PLAN_REVIEW_GATE_KIND) {
             return refuse({
                 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`,
+                body: refusalBody({
                     errorCode: "gate_not_plan_review",
-                },
+                    message: `task is suspended on a '${gateKind ?? "unknown"}' gate, not a plan_review — a tool approval must be decided via POST /v1/approvals/:id/decide`,
+                }),
             });
         }
         const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
         if (ctxRead.kind === "corrupt")
             return refuse(resumeCtxCorruptAnswer(ctxRead.where));
         if (ctxRead.kind === "absent")
-            return refuse({ status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } });
+            return refuse({ status: 409, body: refusalBody({ errorCode: "conflict.resume_context_unavailable", message: "resume context missing — cannot rebuild task config" }) });
         const replay = storedBodyReplayRefusal(ctxRead.ctx, deps.config);
         if (replay !== undefined)
             return refuse(refuseStoredBodyReplay(sessionId, replay));

package/dist/http/retired-service-deps.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 已退役的 `ServiceDeps` 座 —— 「嵌入方照传旧键」的**唯一判据**(闭集表 + 一只判官)。
+ *
+ * 病:一个座退役后,类型上它不在了(TypeScript 嵌入方 tsc 红即通告),但类型之外的嵌入方(JS / `as` 硬转)照传旧键 ⇒ 值被装配无声丢掉,
+ * 「传了没用」是无声失效 —— 而旧键背后的那道门(受理口的墙、blob 的帽)仍在别处判着,调用方以为自己的值在生效。
+ *
+ * 律:退役的座在 `createHttpServer` 装配期**响亮拒**,不静默忽略。座的名字只登记在 {@link RETIRED_SERVICE_DEPS} 这一张表里(键 = 旧座名,
+ * 值 = 退役版本 + 出路),判官 {@link retiredServiceDepsRefusal} 扫一次摊平后的装配入参(`flattenServiceDeps` 之后:顶层键与各组成员同在,
+ * 旧座曾住在 `knobs` 组里,分组形与平铺形同判),命中 ⇒ 交回一句拒话,点名「键 · 退役版本 · 出路」,一次把所有命中的键说全。
+ *
+ * 「传了」= 自有键在场且值不是 `undefined`(条件装配写 `k: cond ? v : undefined` 的嵌入方什么都没传,不拒)。
+ * 一个座新退役时,在表里加一行(同一提交里 CHANGELOG / MIGRATION 的升级条点名它);窗口过后的删表行是单独的一步,不在这里留别名。
+ */
+/** 一个退役座的登记:哪一版退的、嵌入方现在该怎么做。 */
+export interface RetiredServiceDep {
+    /** 退役所在的版本(拒句里原样说出)。 */
+    readonly retiredIn: string;
+    /** 出路,接在「was retired in <版本> — 」之后的半句(英文,与起服拒的其余句子同口径)。 */
+    readonly wayOut: string;
+}
+/** 闭集:`ServiceDeps` 上已退役的座名。 */
+export declare const RETIRED_SERVICE_DEPS: {
+    readonly sqlEngineFacts: {
+        readonly retiredIn: "7.132.0";
+        readonly wayOut: "replaced by sqlEngine — pass the SQL pool's engine reading as sqlEngine: `{ dialect: \"tidb\" | \"pg\", facts }` where `facts` is read live (a getter) and is null while the pool's connection setup has not succeeded, or leave both unset when there is no SQL store";
+    };
+    readonly snapshotBlobSqlCapBytes: {
+        readonly retiredIn: "7.132.0";
+        readonly wayOut: "the HTTP surface no longer holds a blob cap of its own — the SQL snapshot store judges the cap on the connection that executes the write; set SNAPSHOT_BLOB_SQL_MAX_BYTES for a fixed cap, and a self-built file-history store answers an oversized putBlob with `{ ok: false, error: { code \"blob_too_large_for_sql\", message, wallSource } }`";
+    };
+    readonly snapshotBlobSqlCap: {
+        readonly retiredIn: "7.133.0";
+        readonly wayOut: "the HTTP surface no longer holds a blob cap of its own — the SQL snapshot store judges the cap on the connection that executes the write; set SNAPSHOT_BLOB_SQL_MAX_BYTES for a fixed cap, and a self-built file-history store answers an oversized putBlob with `{ ok: false, error: { code \"blob_too_large_for_sql\", message, wallSource } }`";
+    };
+};
+/** 退役座名的闭集。 */
+export type RetiredServiceDepName = keyof typeof RETIRED_SERVICE_DEPS;
+/**
+ * 装配入参(已摊平)里有没有传已退役的座。没有 ⇒ `undefined`;有 ⇒ 一句拒话(按表序把所有命中的键说全:键、退役版本、出路)。
+ * 调用方原样抛出 —— 判官只判不抛,抛的位置(装配期)在 `createHttpServer`。
+ */
+export declare function retiredServiceDepsRefusal(flatDeps: object): string | undefined;
+//# sourceMappingURL=retired-service-deps.d.ts.map

package/dist/http/retired-service-deps.js

@@ -0,0 +1,18 @@
+const BLOB_CAP_WAY_OUT = "the HTTP surface no longer holds a blob cap of its own — the SQL snapshot store judges the cap on the connection that executes the write; set SNAPSHOT_BLOB_SQL_MAX_BYTES for a fixed cap, and a self-built file-history store answers an oversized putBlob with `{ ok: false, error: { code \"blob_too_large_for_sql\", message, wallSource } }`";
+export const RETIRED_SERVICE_DEPS = {
+    sqlEngineFacts: {
+        retiredIn: "7.132.0",
+        wayOut: "replaced by sqlEngine — pass the SQL pool's engine reading as sqlEngine: `{ dialect: \"tidb\" | \"pg\", facts }` where `facts` is read live (a getter) and is null while the pool's connection setup has not succeeded, or leave both unset when there is no SQL store",
+    },
+    snapshotBlobSqlCapBytes: { retiredIn: "7.132.0", wayOut: BLOB_CAP_WAY_OUT },
+    snapshotBlobSqlCap: { retiredIn: "7.133.0", wayOut: BLOB_CAP_WAY_OUT },
+};
+const RETIRED_NAMES = Object.keys(RETIRED_SERVICE_DEPS);
+export function retiredServiceDepsRefusal(flatDeps) {
+    const hits = RETIRED_NAMES.filter((name) => Object.hasOwn(flatDeps, name) && flatDeps[name] !== undefined);
+    if (hits.length === 0)
+        return undefined;
+    const said = hits.map((name) => `${name} was retired in ${RETIRED_SERVICE_DEPS[name].retiredIn} — ${RETIRED_SERVICE_DEPS[name].wayOut}`).join("; ");
+    return `createHttpServer: ${said}; refusing to start rather than silently ignore a retired ServiceDeps seat (the value would no longer do anything)`;
+}
+//# sourceMappingURL=retired-service-deps.js.map