@sema-agent/server 7.145.0 → 7.147.0

package/dist/http/resume-legs.d.ts

@@ -12,18 +12,40 @@
  * (`RunRegistry` / `RouteHelpers` / `RouteLegs` / `ReturnType<typeof createRequestGuards>`),不手抄签名 ⇒ 不会漂。
  */
 import type { IncomingMessage } from "node:http";
-import { CheckpointError, type QuestionAnswer, type CheckpointToken } from "@sema-agent/core";
+import { CheckpointError, type QuestionAnswer, type CheckpointToken, type PendingSteerInput } from "@sema-agent/core";
 import type { DecideBinding, DecidedAction } from "./wire-types.js";
 import type { CheckpointStoreFull } from "../plugins/store-backend.js";
 import type { HostDecision } from "../host-decision.js";
 import { type GateSighting } from "../approval-gate-currency.js";
 import { type PlanApprovePermissionModeAfter } from "../task-settings.js";
-import type { RouteCtxBase, DriveResumeArgs, PreparedPlanReview, ResumeLegOutcome, WorkflowDecisionDelivery } from "./route-ctx.js";
+import type { RouteCtxBase, DriveResumeArgs, PreparedPlanReview, RememberSessionRequest, ResumeCheckpointOutcome, ResumeLegOutcome, WorkflowDecisionDelivery } from "./route-ctx.js";
 import type { RunRegistry, RouteHelpers, RouteLegs } from "./route-ctx.js";
 import type { createRequestGuards } from "./request-guards.js";
 import type { FlatServiceDeps } from "./server.js";
 import { type ResumeRefusalAnswer } from "./checkpoint-ctx.js";
 import { type ResumeRestatement } from "./resume-restatement.js";
+/**
+ * 🔴 **resume / 决断腿上一次 `CheckpointError` 拒的处置 —— 一张表:core 的码闭集 → 处置词**(唯一读口 {@link resumeRefusalDisposition};
+ * 7.113.0 提货车 UP ⑤ 起穷举,此前是 catch 臂里一串 `e.code === … ||` 手列)。
+ *
+ * doctrine(只写这一次):处置词说的是**这张卡与这条 run 行此刻的处境**,不是「重试会不会成」——
+ *  · `retriable` —— PRE-CAS 拒:**卡仍 pending ⇒ run 行重新 park**(`suspended` / `needs_review`),wire 体自述 `retriable:true`
+ *    (契约附录 A.1 注的定义:「卡仍 pending,不是『重试会成功』」)。出路(改那一格 / 重取坐标 / 回到写它的那一版引擎 / 换对 worker / 取消)
+ *    由码、`field`、`writerVersion` / `readerVersion` 与报文说,**不由 `retriable` 说**;
+ *  · `terminal`  —— 卡已消费 / 已不在 / 本腿读不懂 ⇒ 驱行终局,wire 体不带 `retriable`;
+ *  · `cancelled` —— 取消 ⇒ 取消终局。
+ * 行的落点与 wire 的 `retriable` 读**同一次**求值(catch 臂一处),所以同一处境只有一个答案。决断口 409 的成因({@link decisionRefusalCauseOf})只决定码名、
+ * 不另答处置:决断类三词都出自 `checkpoint.invalid_outcome`,落点读本表那一行。「停驻行的格式比本引擎新」只有 core 一个来源(`checkpoint.unsupported_version`
+ * + `version_newer` ⇒ `retriable`);续跑上下文的写者版本只让那一码的 409 体多带 `writerVersion` / `readerVersion` 两件事实,不参与判处置。
+ * 同码多铸点、可恢复性不同的码再按它自己的判别位闭集分(`"by_reason"` → {@link WORKER_SWAP_REDEEMABLE})。
+ * 表是 `Record<CheckpointError["code"], …>` ⇒ core 加一个码而本表没跟 = **tsc 红**(手列串的病:新码不在串里 ⇒ 静默落终局 —— core 7.39.0 的
+ * `checkpoint.config_refused` 提货当拍就是这样把一张 pending 卡孤儿化的,钉 `test/durable-resume-http.test.ts` [ref] 两格)。
+ *
+ * 驱终局为什么危险(原 catch 臂注,D-1 / core 1.101):PRE-CAS 拒时卡仍 pending,驱终局会释放 task_active 并孤儿化那张卡(下一次 /decide → 404);
+ * re-park 让改正后的重试能再认领。驱终局只给「卡已消费或已不在」的码,免得留一条僵尸 `running` 行让 reapStale 误标并攥着会话锁 ~runStaleSec。
+ */
+export type CheckpointErrorDispositionWord = "cancelled" | "retriable" | "terminal" | "by_reason";
+export declare const CHECKPOINT_ERROR_DISPOSITION: Readonly<Record<CheckpointError["code"], CheckpointErrorDispositionWord>>;
 /**
  * 🔴 **一次 `CheckpointError` 拒的处置 —— 唯一读口**:{@link CHECKPOINT_ERROR_DISPOSITION} 的读法(doctrine 在那张表头)。resume 腿的 catch 臂只调它一次,
  * 行的落点与 wire 的 `retriable` 都读这一个结果。纯函数,钉直接调。运行期遇到表外的码(装树 core 比本二进制多一个码的版本偏斜 —— 型面上拼不出来)
@@ -53,13 +75,10 @@ export declare function createResumeLegs(ctx: {
     runnerFor: FlatServiceDeps["runnerFor"];
 } & RunRegistry & RouteHelpers & Pick<RouteLegs, "prepareSpec" | "finalizeTaskResult"> & Pick<ReturnType<typeof createRequestGuards>, "ownerCostQuotaDenied" | "ownerFleetLeaseDenied" | "usageWindowDenialFor">): {
     routeCtxBase: RouteCtxBase;
-    resumeCheckpoint: (sessionId: string, decision: "approve" | "deny", reason: string | undefined, hostDecision: HostDecision, req: IncomingMessage | undefined, answer: QuestionAnswer | undefined, binding: DecideBinding, onResumeCommitted?: (grant: {
-        overrideSessionId?: string;
-        rememberableToolName: string | null;
-    }) => Promise<void>, acceptEarly?: boolean, decider?: {
+    resumeCheckpoint: (sessionId: string, decision: "approve" | "deny", reason: string | undefined, hostDecision: HostDecision, req: IncomingMessage | undefined, answer: QuestionAnswer | undefined, binding: DecideBinding, remember?: RememberSessionRequest, acceptEarly?: boolean, decider?: {
         principal?: string;
         explicitOperator: boolean;
-    }, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
+    }, restatement?: ResumeRestatement) => Promise<ResumeCheckpointOutcome>;
     driveResumeIntoRunLog: (args: DriveResumeArgs) => Promise<ResumeLegOutcome>;
     driveResumeLeg: (args: DriveResumeArgs, onAccepted?: (receipt: {
         status: number;
@@ -74,14 +93,14 @@ export declare function createResumeLegs(ctx: {
         explicitOperator: boolean;
     }, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
     startFreshHostTurn: (sessionId: string, objective: string, principal: string | undefined, req: IncomingMessage, workflowDecision: WorkflowDecisionDelivery, runId: string, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
-    resumeWake: (sessionId: string, message: string | undefined, caller: string | undefined, req: IncomingMessage | undefined, acceptEarly?: boolean, workflowDecision?: WorkflowDecisionDelivery, ownerLeaseAdmittedFor?: string, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
+    resumeWake: (sessionId: string, message: PendingSteerInput | undefined, caller: string | undefined, req: IncomingMessage | undefined, acceptEarly?: boolean, workflowDecision?: WorkflowDecisionDelivery, ownerLeaseAdmittedFor?: string, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
     preparePlanReview: (sessionId: string, log?: {
         taskId?: string;
         principalPresent?: boolean;
     }, decider?: {
         principal?: string;
         explicitOperator: boolean;
-    }, sighting?: GateSighting) => Promise<{
+    }, sighting?: GateSighting, restatement?: ResumeRestatement) => Promise<{
         readonly ok: false;
         readonly answer: {
             status: number;
@@ -91,7 +110,7 @@ export declare function createResumeLegs(ctx: {
         readonly ok: true;
         readonly prepared: PreparedPlanReview;
     }>;
-    drivePlanReview: (prepared: PreparedPlanReview, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, hostDecision: HostDecision, req: IncomingMessage | undefined, acceptEarly?: boolean, permissionModeAfter?: PlanApprovePermissionModeAfter, restatement?: ResumeRestatement) => Promise<ResumeLegOutcome>;
+    drivePlanReview: (prepared: PreparedPlanReview, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, hostDecision: HostDecision, req: IncomingMessage | undefined, acceptEarly?: boolean, permissionModeAfter?: PlanApprovePermissionModeAfter) => Promise<ResumeLegOutcome>;
     sessionNotifyDoor: import("../session-notify-door.js").SessionNotifyDoor;
 };
 //# sourceMappingURL=resume-legs.d.ts.map

package/dist/http/resume-legs.js

@@ -1,6 +1,6 @@
 import { redactErrorMessage, redactHead } from "../observability/run-terminal.js";
 import { createHash } from "node:crypto";
-import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, taskNotificationDedupKey, validatePendingSteer, GLOBAL_USAGE_KEY } from "@sema-agent/core";
+import { uuidv7, resumeWithVerification, CheckpointError, judgeCheckpointRow, defaultTaskRegistry, taskNotificationDedupKey, validatePendingSteer, GLOBAL_USAGE_KEY } from "@sema-agent/core";
 import { decideParkedAgent, denyWorkflowParkForked, denyWorkflowParksUnreadable, findParkOrigin, heldWorkflowParkDecisions, planWorkflowParkedDecide } from "../parked-decide.js";
 import { parkDecisionFingerprint } from "../orchestration/workflow-park-decision.js";
 import { headReadOf } from "../session-incarnation.js";
@@ -22,12 +22,12 @@ import { approverFacingArgs, createApprovalCardEmitter, declaredApprovalFrameFam
 import { buildCheckpointAnchorHash } from "../approval-ask-audit-store.js";
 import { APPROVAL_ENDING_CAUSES } from "../approval-deny-reasons.js";
 import { serviceVersion } from "../service-version.js";
-import { TERMINAL_PARK_GATE_KINDS } from "../plugins/checkpoint-store-sql.js";
+import { TERMINAL_PARK_GATE_KINDS, UnreadableCheckpointRowError } from "../plugins/checkpoint-store-face.js";
 import { withPrincipal } from "../observability/principal-context.js";
 import { withModelReachScope } from "../model-reach-scope.js";
 import { legFactsOf } from "../leg-facts.js";
 import { createInstructionSelectionLeg } from "../instruction-selection.js";
-import { modelTextEventData, appendParkRow, turnEndEventData, contextUsageEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskStartedEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, compactionStartedEventData, workspaceChangedEventData, wiringManifestEventData, toolRosterDeltaEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, appendPromptManifest, attachModelUsage } from "../trace/project.js";
+import { modelTextEventData, appendParkRow, turnEndEventData, contextUsageEventData, toolStartEventData, toolEndEventData, taskProgressEventData, taskStartedEventData, taskNotificationEventData, compactedEventData, diagnosticsEventData, brainStatusEventData, steeringInjectedEventData, compactionOutcomeEventData, compactionStartedEventData, workspaceChangedEventData, wiringManifestEventData, toolRosterDeltaEventData, toolDisclosureEventData, humanInputEventData, appendModelUsageDelta, attachModelUsage, createPromptManifestSeat } from "../trace/project.js";
 import { redactSecrets } from "../trace/redact.js";
 import { buildRunObjectivePreview } from "../user-authored-text.js";
 import { createForwardAppendFailedNote, createLedgerSink, createSerialLedgerAppend } from "../trace/ledger-sink.js";
@@ -49,13 +49,14 @@ import { createCapabilitiesLocal } from "./routes/capabilities.js";
 import { gatedPrincipal, explicitOperatorOk, runIdentityOf } from "./principal-gate.js";
 import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflict.js";
 import { commitExecutionContext, isRootSessionGoneError, resolveExecutionContext, rootSessionAbsentAnswer, stampSpecRoot } from "./execution-context.js";
+import { timeClaim } from "./claim-latency.js";
 import { commitSessionInheritEnv } from "./session-inherit-env.js";
 import { ASK_USER_QUESTION_TOOL_NAME, isApprovalGateKind, isEngineQuestionRow } from "../approval-content-kind.js";
 import { deploymentListAsks } from "../approval.js";
 import { isParkLedgerEventType } from "../trace/ledger-events.js";
 import { readResumeCtx, resumeCtxCorruptAnswer, resumeCtxUnsealableAnswer } from "./resume-ctx-read.js";
 import { objectiveWithheldIn } from "./submit-ctx.js";
-import { buildCheckpointVersionKeys, resumeBlockedByPolicyAnswer, resumeRefusalWithCard, sealCheckpointCtx, storedBodyReplayAnswer, storedBodyReplayLogFields, withPermissionModeRewritten } from "./checkpoint-ctx.js";
+import { buildCheckpointVersionKeys, resumeAssemblyRefusalAnswer, resumeRefusalWithCard, sealCheckpointCtx, storedBodyReplayAnswer, storedBodyReplayLogFields, withPermissionModeRewritten } from "./checkpoint-ctx.js";
 import { refusalBody, resumeRefusalFacts } from "./refusal-body.js";
 import { storedBodyReplayRefusal } from "./stored-body-replay.js";
 import { restateResumeCtx } from "./resume-restatement.js";
@@ -103,7 +104,7 @@ const WORKER_SWAP_REDEEMABLE = {
 function checkpointRowRedeemableElsewhere(reason) {
     return reason !== undefined && WORKER_SWAP_REDEEMABLE[reason] === true;
 }
-const CHECKPOINT_ERROR_DISPOSITION = {
+export const CHECKPOINT_ERROR_DISPOSITION = {
     "checkpoint.resume_aborted": "cancelled",
     "checkpoint.invalid_outcome": "retriable",
     "checkpoint.reopen_revote": "retriable",
@@ -184,13 +185,13 @@ const WIRE_CODE_OF_DECISION_REFUSAL = {
     [APPROVAL_ENDING_CAUSES.ANSWER_INVALID]: "resume_outcome_invalid",
     [APPROVAL_ENDING_CAUSES.OUTCOME_CELL_INVALID]: "resume_outcome_invalid",
 };
-const UNCLASSIFIED_INVALID_OUTCOME_CODE = WIRE_CODE_OF_DECISION_REFUSAL[APPROVAL_ENDING_CAUSES.BINDING_CHANGED];
 function decisionRefusalCauseOf(e, gate) {
-    if (gate !== "policy_ask")
-        return APPROVAL_ENDING_CAUSES.OUTCOME_CELL_INVALID;
+    if (e.detail?.reason !== undefined)
+        return undefined;
     const field = e.detail?.field;
-    const role = field !== undefined && Object.hasOwn(CHECKPOINT_ERROR_FIELD_ROLE, field) ? CHECKPOINT_ERROR_FIELD_ROLE[field] : undefined;
-    return role === undefined ? undefined : FIELD_ROLE_CAUSE[role];
+    if (field !== undefined)
+        return Object.hasOwn(CHECKPOINT_ERROR_FIELD_ROLE, field) ? FIELD_ROLE_CAUSE[CHECKPOINT_ERROR_FIELD_ROLE[field]] : undefined;
+    return gate === "policy_ask" ? undefined : APPROVAL_ENDING_CAUSES.OUTCOME_CELL_INVALID;
 }
 function notResumableAnswer() {
     return { status: 409, body: refusalBody({ errorCode: "conflict.not_resumable", message: "run is not in a resumable (suspended) state (already resumed, decided, or expired)" }) };
@@ -208,6 +209,13 @@ function approvalStaleAnswer(facts) {
         }),
     };
 }
+function rowRefusalAnswer(verdict, diagnostic, ctx) {
+    const refusal = new CheckpointError(verdict.code, diagnostic === undefined ? verdict.sentence : `${verdict.sentence} Diagnostic: ${diagnostic}`, verdict.reason === undefined ? undefined : { reason: verdict.reason });
+    return checkpointRefusalAnswer(refusal, { gate: "policy_ask", retriable: resumeRefusalDisposition(refusal) === "retriable", versionKeys: refusalVersionKeys(refusal, ctx) });
+}
+function refusalVersionKeys(e, ctx) {
+    return e.code === "checkpoint.unsupported_version" ? buildCheckpointVersionKeys(ctx.writerVersion, serviceVersion()) : {};
+}
 function acceptableFormFacts(detail) {
     const rewritten = detail !== null && typeof detail === "object" ? detail.editRewritten : undefined;
     if (rewritten === null || typeof rewritten !== "object" || !Object.hasOwn(rewritten, "acceptableForm"))
@@ -222,7 +230,7 @@ export function checkpointRefusalAnswer(e, at) {
         status: e.code === "checkpoint.not_found" ? 404 : 409,
         body: refusalBody({
             message: e.message,
-            errorCode: e.code === "checkpoint.invalid_outcome" ? (refusalCause !== undefined ? WIRE_CODE_OF_DECISION_REFUSAL[refusalCause] : UNCLASSIFIED_INVALID_OUTCOME_CODE) : e.code,
+            errorCode: refusalCause === undefined ? e.code : WIRE_CODE_OF_DECISION_REFUSAL[refusalCause],
             facts: {
                 ...(at.taskId !== undefined ? { taskId: at.taskId } : {}),
                 ...resumeRefusalFacts(detail),
@@ -241,11 +249,36 @@ export function decidedActionOf(binding) {
     return missingKeys.length === 0 ? { action: { boundCallId: boundCallId, boundInputHash: boundInputHash } } : { missingKeys };
 }
 export function createResumeLegs(ctx) {
-    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
+    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, admitRun, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
     const ctxOpening = (sessionId) => ({ sessionId, opener: deps.checkpointCtxSealing });
     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, restatement) {
+    function createRememberIntent(sessionId, remember) {
+        let pending;
+        return {
+            laneCannotRecord: remember.laneCannotRecord,
+            record: async (grant) => {
+                if (grant.rememberableToolName !== null)
+                    pending = { sessionId: grant.overrideSessionId ?? sessionId, toolName: grant.rememberableToolName };
+            },
+            settle: async (committed) => {
+                const store = deps.approvalExemptionStore;
+                if (!committed || pending === undefined || store === undefined)
+                    return false;
+                try {
+                    await store.grant(pending.sessionId, pending.toolName, remember.grantedBy);
+                    deps.logger?.info?.("approval_exemption_granted", { sessionId: pending.sessionId, toolName: pending.toolName, grantedBy: remember.grantedBy });
+                    return true;
+                }
+                catch (e) {
+                    deps.logger?.warn?.("approval_exemption_grant_failed", { sessionId: pending.sessionId, toolName: pending.toolName, error: String(e).slice(0, 200) });
+                    return false;
+                }
+            },
+        };
+    }
+    async function resumeCheckpoint(sessionId, decision, reason, hostDecision, req, answer, binding, remember, acceptEarly, decider, restatement) {
         const cs = deps.checkpointStore;
+        const intent = remember !== undefined ? createRememberIntent(sessionId, remember) : undefined;
         const token = await currentApprovalGateToken(cs, sessionId);
         if (binding.checkpointToken && !sightsCurrentGate({ face: "checkpointToken", value: binding.checkpointToken }, token ? { checkpointToken: token } : null)) {
             let seenUnreadable = false;
@@ -293,6 +326,7 @@ export function createResumeLegs(ctx) {
         const ctxPromise = cs.getCtx(sessionId);
         void ctxPromise.catch(() => { });
         const noApproval = { status: 404, body: refusalBody({ errorCode: "not_found.approval", message: "approval not found" }) };
+        const rowOwnRefusal = async (verdict, diagnostic) => rowRefusalAnswer(verdict, diagnostic, verdict.code === "checkpoint.unsupported_version" ? ((await ctxPromise.catch(() => null)) ?? {}) : {});
         let cp;
         try {
             cp = await cpPromise;
@@ -303,7 +337,9 @@ 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: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) };
+            if (e instanceof UnreadableCheckpointRowError && e.rowVerdict.kind !== "ok")
+                return rowOwnRefusal(e.rowVerdict, errorText(e));
+            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: errorText(e) }) };
         }
         if (!cp) {
             if (!(await mayDiscloseRowError(cs, token, decider)))
@@ -319,20 +355,20 @@ export function createResumeLegs(ctx) {
         }
         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;
+            const verdict = judgeCheckpointRow(cp);
+            if (verdict.kind !== "ok")
+                return rowOwnRefusal(verdict);
+            if (typeof decideGateKind !== "string" || decideGateKind === "") {
+                return { status: 409, body: refusalBody({ errorCode: "gate_not_tool_approval", message: "task is suspended on a gate whose kind this engine cannot read, so it cannot say which endpoint resolves it" }) };
+            }
+            const activeForPath = await deps.runStore?.getActiveTaskId(sessionId).catch(() => undefined);
+            const gnPath = activeForPath ? resumeEntryForGate(decideGateKind, { sessionId, taskId: activeForPath }) : null;
             return {
                 status: 409,
                 body: refusalBody({
                     errorCode: "gate_not_tool_approval",
-                    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 } : {}) } } : {}),
-                    },
+                    message: `task is suspended on a '${decideGateKind}' 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: { pendingGate: { kind: decideGateKind, ...(gnPath ? { decidePath: gnPath } : {}) } },
                 }),
             };
         }
@@ -370,8 +406,8 @@ export function createResumeLegs(ctx) {
             standingAnswerDurablyRecordable(parkRowStandingAnswerFacts(paForGrant, cp.gate, deps.config, deploymentListAsks(deps.config, { toolName: paForGrant.toolName })))
             ? paForGrant.toolName
             : null;
-        const boundGrant = onResumeCommitted
-            ? (overrideSessionId) => onResumeCommitted({ ...(overrideSessionId !== undefined ? { overrideSessionId } : {}), rememberableToolName: rememberableTool })
+        const boundGrant = intent
+            ? (overrideSessionId) => intent.record({ ...(overrideSessionId !== undefined ? { overrideSessionId } : {}), rememberableToolName: rememberableTool })
             : undefined;
         const lateSettleSink = deps.approvalLateSettle;
         const lateSettleAnchor = lateSettleSink !== undefined && req !== undefined && token
@@ -381,8 +417,8 @@ export function createResumeLegs(ctx) {
                 checkpointTokenHash: buildCheckpointAnchorHash(token),
             }
             : undefined;
-        const noteLateSettleIfAccepted = (out) => {
-            if (lateSettleSink === undefined || lateSettleAnchor === undefined || !decisionCommittedOf(out))
+        const noteLateSettleIfAccepted = (committed) => {
+            if (!committed || lateSettleSink === undefined || lateSettleAnchor === undefined)
                 return;
             try {
                 lateSettleSink.recordLateSettle({ ...lateSettleAnchor, outcome: decision === "approve" ? "allowed" : "denied", decidedBy: hostDecision.decidedBy, ...(hostDecision.approver !== undefined ? { approver: hostDecision.approver } : {}), settledAtMs: Date.now() });
@@ -391,6 +427,11 @@ export function createResumeLegs(ctx) {
                 recordFailOpen("server.approval-ask-audit.append-failed", `kind=late_settle err=${e instanceof Error ? e.message : String(e)}`);
             }
         };
+        const landAfterCommit = async (out) => {
+            const committed = decisionCommittedOf(out);
+            noteLateSettleIfAccepted(committed);
+            return intent === undefined ? out : { ...out, rememberApplied: await intent.settle(committed) };
+        };
         const parkedForkQuotaDenial = req !== undefined ? ownerCostQuotaDenied(decodeCheckpointScope(cp.scope)) : undefined;
         if (parkedForkQuotaDenial)
             return parkedForkQuotaDenial;
@@ -416,7 +457,7 @@ export function createResumeLegs(ctx) {
                 binding: { ...(({ checkpointToken: _staleGuardOnly, ...rest }) => rest)(binding), ...action },
                 ...(answer !== undefined ? { answer } : {}),
                 ...(restatement !== undefined ? { restatement } : {}),
-                ...(boundGrant ? { grantRemember: (rootSessionId) => boundGrant(rootSessionId) } : {}),
+                ...(boundGrant && intent ? { remember: { anchor: (rootSessionId) => boundGrant(rootSessionId), laneCannotRecord: intent.laneCannotRecord } } : {}),
             };
             if (origin?.kind === "background" && parkedAgentStore !== undefined && parkedSurface !== undefined) {
                 const parked = await withPrincipal(decodeCheckpointScope(cp.scope), () => decideParkedAgent({
@@ -437,7 +478,7 @@ export function createResumeLegs(ctx) {
                                 if (isRootSessionGoneError(e))
                                     return { ok: false, gone: true };
                                 if (e instanceof HttpError)
-                                    return { ok: false, gone: false, answer: resumeRefusalWithCard(resumeBlockedByPolicyAnswer(httpErrorRefusal(e)), true) };
+                                    return { ok: false, gone: false, answer: resumeRefusalWithCard(resumeAssemblyRefusalAnswer(e.status, httpErrorRefusal(e)), true) };
                                 throw e;
                             }
                             const occupant = ctx.occupant;
@@ -451,8 +492,7 @@ export function createResumeLegs(ctx) {
                     ...(deps.logger ? { warn: parkWarn } : {}),
                 }, { ...parkedReq, selectedGate: captureSelectedGate() }, { handle: origin.handle, row: origin.row }));
                 void ctxPromise.catch(() => { });
-                noteLateSettleIfAccepted(parked);
-                return parked;
+                return await landAfterCommit(parked);
             }
             if (origin?.kind === "workflow_parks_unreadable") {
                 void ctxPromise.catch(() => { });
@@ -503,7 +543,7 @@ export function createResumeLegs(ctx) {
                 const admittedPayer = decodeCheckpointScope(cp.scope);
                 const out = hostToken
                     ? await resumeWake(plan.hostSessionId, plan.message, decider?.principal, req, acceptEarly, delivery, admittedPayer, restatement)
-                    : await startFreshHostTurn(plan.hostSessionId, plan.message, admittedPayer, req, delivery, plan.runId, restatement);
+                    : await startFreshHostTurn(plan.hostSessionId, plan.message.text, admittedPayer, req, delivery, plan.runId, restatement);
                 if (recordFailure !== undefined)
                     throw recordFailure.err;
                 if (acceptedTaskIdOf(out) === undefined)
@@ -548,8 +588,7 @@ export function createResumeLegs(ctx) {
             };
             const verifyRounds = verifyRoundsFromBody(ctx.body);
             const driven = await driveResumeIntoRunLog({ peerLease: resolved.peerLease, execution: resolved.execution, runner: resolved.runner, legFacts: resolved.legFacts, token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, commitment: { kind: "gate_resolved", ...captureSelectedGate() }, verifyRounds, resumeCtx: { sessionId, ctx }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(boundGrant ? { onResumeCommitted: boundGrant } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}), ...(ownerLeaseAdmittedHere ? { ownerLeaseAdmitted: true } : {}) });
-            noteLateSettleIfAccepted(driven);
-            return driven;
+            return await landAfterCommit(driven);
         }
         finally {
             resolved.peerLease.release();
@@ -588,7 +627,7 @@ export function createResumeLegs(ctx) {
         catch (e) {
             lease.release();
             if (e instanceof HttpError) {
-                return { ok: false, answer: resumeRefusalWithCard(resumeBlockedByPolicyAnswer(httpErrorRefusal(e)), true) };
+                return { ok: false, answer: resumeRefusalWithCard(resumeAssemblyRefusalAnswer(e.status, httpErrorRefusal(e)), true) };
             }
             throw e;
         }
@@ -652,11 +691,11 @@ export function createResumeLegs(ctx) {
         }
         if (!taskId && args.mintFreshRun && deps.runStore) {
             const freshId = uuidv7();
-            const created = await deps.runStore.createRun(freshId, sessionId, principal ?? null, deps.instanceId ?? "default", {
+            const created = await timeClaim(deps.metrics, "run_claim", deps.runStore.createRun(freshId, sessionId, principal ?? null, deps.instanceId ?? "default", {
                 source: args.mintFreshRun.source,
                 identity: args.mintFreshRun.identity,
                 objectivePreview: heldObjective === undefined ? null : buildRunObjectivePreview(heldObjective),
-            });
+            }));
             if (created.existing) {
                 throw new Error(`wake fresh run: createRun observed an existing row for the freshly minted taskId ${freshId} (no idempotency key was sent) — refusing to treat it as a busy session`);
             }
@@ -742,12 +781,12 @@ export function createResumeLegs(ctx) {
             return { reopened: pending, leg };
         };
         let resumeHeartbeat;
-        let resumeManifestLease = 0;
+        let resumeManifestSeat;
         let resumeStreamRef;
         let resumeLegLive = false;
         const subagentHandleEvictions = [];
         let claimedRow = false;
-        const cancelCtrl = createRunAbort();
+        const cancelCtrl = createRunAbort(principal ?? null);
         let cancelLedgerAppend;
         const preemptCtrl = new AbortController();
         if (taskId && deps.runStore) {
@@ -778,7 +817,7 @@ export function createResumeLegs(ctx) {
             }, HEARTBEAT_MS);
             resumeHeartbeat.unref?.();
             deps.modelUsage?.register(taskId);
-            resumeManifestLease = deps.promptManifests?.register(taskId) ?? 0;
+            resumeManifestSeat = createPromptManifestSeat(deps.promptManifests, taskId);
         }
         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");
@@ -890,7 +929,7 @@ export function createResumeLegs(ctx) {
                         const rs2 = deps.runStore;
                         try {
                             const ap = vAppend;
-                            await appendPromptManifest(ap, deps.promptManifests, taskId);
+                            await resumeManifestSeat?.drain(ap);
                             if (reSuspended || vrReopened) {
                                 const vrParkCallId = reSuspended ? await parkToolCallId(vr, deps.checkpointStore) : undefined;
                                 await appendParkRow(ap, { modelUsage: deps.modelUsage, taskId }, reParkEvent ?? reparkStatus, { terminal: vrPaused, ...(vrParkCallId !== undefined ? { toolCallId: vrParkCallId } : {}) }, vrReopened ? (failureCodeOf(vr.terminal) ?? null) : undefined);
@@ -938,7 +977,7 @@ export function createResumeLegs(ctx) {
                     ? async (eventId) => { const leaf = (await headOf(sessionId))?.leafId; if (leaf)
                         await deps.resumeAnchorStore.put(sessionId, eventId, leaf, anchorOwner); }
                     : undefined;
-                const captureUserMessageAnchor = deps.resumeAnchorStore && taskId
+                const captureUserMessageAnchor = deps.resumeAnchorStore && taskId && freshRunClaimed
                     ? async (entryId) => { await deps.resumeAnchorStore.put(sessionId, taskId, entryId, anchorOwner); }
                     : undefined;
                 const anchor = new TurnAnchorCapture(captureTurnAnchor, "resume", captureUserMessageAnchor);
@@ -1039,7 +1078,7 @@ export function createResumeLegs(ctx) {
                         fleetPub?.onEvent(ev);
                         await deps.userInputLedger?.observeLegEvent(stream, ev);
                         await resumeWorkspace.observe(ev);
-                        await appendPromptManifest(append, deps.promptManifests, taskId);
+                        await resumeManifestSeat?.drain(append);
                         switch (ev.type) {
                             case "text_delta":
                                 block += ev.delta;
@@ -1247,7 +1286,7 @@ export function createResumeLegs(ctx) {
                         settleFleet("failed");
                     }
                 }
-                return checkpointRefusalAnswer(e, { gate: outcome.gate, retriable, ...(taskId !== undefined ? { taskId } : {}), versionKeys: e.code === "checkpoint.unsupported_version" ? buildCheckpointVersionKeys(resumeCtx.ctx.writerVersion, serviceVersion()) : {} });
+                return checkpointRefusalAnswer(e, { gate: outcome.gate, retriable, ...(taskId !== undefined ? { taskId } : {}), versionKeys: refusalVersionKeys(e, resumeCtx.ctx) });
             }
             const thrownCause = cancelCtrl.cause();
             if (thrownCause !== undefined) {
@@ -1281,7 +1320,7 @@ export function createResumeLegs(ctx) {
                 for (const evict of subagentHandleEvictions)
                     evict();
                 deps.modelUsage?.clear(taskId);
-                deps.promptManifests?.clear(taskId, resumeManifestLease);
+                resumeManifestSeat?.release();
             }
             if (resumeHeartbeat)
                 clearInterval(resumeHeartbeat);
@@ -1488,10 +1527,9 @@ export function createResumeLegs(ctx) {
         if (gateKind !== "task_done") {
             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) {
             try {
-                validatePendingSteer({ text: message, trusted });
+                validatePendingSteer(message);
             }
             catch (e) {
                 if (e instanceof CheckpointError && e.code === "steering.invalid_content") {
@@ -1526,7 +1564,7 @@ export function createResumeLegs(ctx) {
                 fleetScope: resumeFleetScope(req, auth),
                 taskConfig,
                 resumeObjective,
-                outcome: { gate: "wake", ...(message !== undefined ? { message: { text: message, trusted } } : {}) },
+                outcome: { gate: "wake", ...(message !== undefined ? { message } : {}) },
                 commitment: { kind: "delivered" },
                 verifyRounds: undefined,
                 resumeCtx: { sessionId, ctx },
@@ -1542,7 +1580,7 @@ export function createResumeLegs(ctx) {
             resolved.peerLease.release();
         }
     }
-    async function preparePlanReview(sessionId, log, decider, sighting) {
+    async function preparePlanReview(sessionId, log, decider, sighting, restatement) {
         const cs = deps.checkpointStore;
         const refuse = (answer) => ({ ok: false, answer });
         const log404 = (r) => deps.logger?.info?.("decide_404", {
@@ -1614,14 +1652,14 @@ export function createResumeLegs(ctx) {
             return refuse(resumeCtxUnsealableAnswer(ctxRead));
         if (ctxRead.kind === "absent")
             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);
+        const ctx = restateResumeCtx(ctxRead.ctx, restatement);
+        const replay = storedBodyReplayRefusal(ctx, deps.config);
         if (replay !== undefined)
             return refuse(refuseStoredBodyReplay(sessionId, replay));
-        return { ok: true, prepared: { sessionId, token, cp, ctx: ctxRead.ctx } };
+        return { ok: true, prepared: { sessionId, token, cp, ctx } };
     }
-    async function drivePlanReview(prepared, decision, editedPlan, reason, hostDecision, req, acceptEarly, permissionModeAfter, restatement) {
-        const { sessionId, token, cp } = prepared;
-        const ctx = restateResumeCtx(prepared.ctx, restatement);
+    async function drivePlanReview(prepared, decision, editedPlan, reason, hostDecision, req, acceptEarly, permissionModeAfter) {
+        const { sessionId, token, cp, ctx } = prepared;
         if ((await deps.checkpointStore.findPendingTokenBySession(sessionId, undefined, { gateKinds: ["plan_review"] })) !== token)
             return notResumableAnswer();
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
@@ -1662,7 +1700,7 @@ export function createResumeLegs(ctx) {
     const routeCtxBase = {
         deps,
         registry: { idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters },
-        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk },
+        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, admitRun, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk },
         local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal(), capabilities: createCapabilitiesLocal() },
         legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, preparePlanReview, drivePlanReview, sessionNotify: sessionNotifyDoor },
     };

package/dist/http/rewind-files-reply.d.ts

@@ -0,0 +1,34 @@
+/**
+ * run 外回退口 `POST /v1/sessions/:id/rewind-files` 的 200 体 —— 引擎 `Runner.rewindFiles` 的结果(`RewindFilesResult`)**原形**,文本叶经出口座出门。
+ *
+ * 规则一句:形照引擎(`dryRun:true` ⇒ `{ preview }`,`null` 仍是 `null`;`dryRun:false` ⇒ `{ restore }` 台账,空数组仍是空数组),每一片自由文本叶只经
+ * {@link seatText} 的一行 —— 被跟踪文件的路径(台账 `filesChanged` / `identicalSkipped` / `refused[].path` / `failed[].path`、预览 `filesChanged`;源头是模型交的
+ * 路径参数)走 `rewind-ledger-path`(不设界:截过的路径就不是那个文件了);拒因 / 故障句(`refused[].reason` / `failed[].reason` / `error.message`)走
+ * `rewind-ledger-reason`;闭集词 / 计数逐字。台账上的店故障(core `FileHistoryError`)按本仓错误体的唯一机读键律出门:引擎的 `code` 成员在 wire 上叫
+ * `errorCode`(值逐字),`message` 经座,`permanence` 逐字 —— 本仓的 wire 上没有叫 `code` 的错误键。两张叶表与故障的三键按 core 型的键穷举 ——
+ * core 给台账 / 统计 / 故障加一格而这里不表态 ⇒ tsc 红;表外的运行期键不出门(按表取键,不展开原对象)。唯一调用方 = `http/routes/sessions.ts` 的 `session-rewind-files` 臂。
+ */
+import type { FileHistoryDiffStats, FileHistoryError, FileHistoryRestoreResult, RewindFilesResult } from "@sema-agent/core";
+/** 台账上的店故障在 wire 上的形:码键 = `errorCode`(本仓错误体的唯一机读键),其余两键同引擎。 */
+export interface RewindLedgerError {
+    readonly errorCode: FileHistoryError["code"];
+    readonly message: string;
+    readonly permanence?: FileHistoryError["permanence"];
+}
+/** 台账在 wire 上的形 = 引擎台账,`error` 换成 {@link RewindLedgerError}。 */
+export type RewindLedgerReply = Omit<FileHistoryRestoreResult, "error"> & {
+    readonly error?: RewindLedgerError;
+};
+/** 200 体在 wire 上的形(引擎 `RewindFilesResult`,台账的 `error` 按 {@link RewindLedgerError})。 */
+export type RewindFilesReply = {
+    readonly dryRun: true;
+    readonly preview: FileHistoryDiffStats | null;
+} | {
+    readonly dryRun: false;
+    readonly restore: RewindLedgerReply & {
+        readonly outcome: "complete" | "partial";
+    };
+};
+/** 200 体(纯数据)。 */
+export declare function buildRewindFilesReply(result: RewindFilesResult): RewindFilesReply;
+//# sourceMappingURL=rewind-files-reply.d.ts.map

package/dist/http/rewind-files-reply.js

@@ -0,0 +1,36 @@
+import { seatText } from "../trace/exit-seat.js";
+function applyLeafTable(obj, table) {
+    const out = {};
+    for (const key of Object.keys(table)) {
+        const v = obj[key];
+        if (v !== undefined && v !== null)
+            out[key] = table[key](v);
+    }
+    return out;
+}
+const pathLeaf = (p) => seatText("rewind-ledger-path", p);
+const reasonLeaf = (t) => seatText("rewind-ledger-reason", t);
+function ledgerErrorOf(e) {
+    return { errorCode: e.code, message: reasonLeaf(e.message), ...(e.permanence !== undefined ? { permanence: e.permanence } : {}) };
+}
+const RESTORE_LEDGER_LEAVES = {
+    outcome: (v) => v,
+    filesChanged: (v) => v.map(pathLeaf),
+    identicalSkipped: (v) => v.map(pathLeaf),
+    refused: (v) => v.map((f) => ({ path: pathLeaf(f.path), reason: reasonLeaf(f.reason), class: f.class })),
+    failed: (v) => v.map((f) => ({ path: pathLeaf(f.path), reason: reasonLeaf(f.reason) })),
+    modeNotPreserved: (v) => v,
+};
+const DIFF_STATS_LEAVES = {
+    filesChanged: (v) => v.map(pathLeaf),
+    insertions: (v) => v,
+    deletions: (v) => v,
+};
+export function buildRewindFilesReply(result) {
+    if (result.dryRun)
+        return { dryRun: true, preview: result.preview === null ? null : applyLeafTable(result.preview, DIFF_STATS_LEAVES) };
+    const { error, ...ledger } = result.restore;
+    const projected = applyLeafTable(ledger, RESTORE_LEDGER_LEAVES);
+    return { dryRun: false, restore: { ...projected, outcome: result.restore.outcome, ...(error !== undefined ? { error: ledgerErrorOf(error) } : {}) } };
+}
+//# sourceMappingURL=rewind-files-reply.js.map