@sema-agent/server 7.96.0 → 7.98.0

package/dist/file-history-capture.d.ts

@@ -0,0 +1,65 @@
+/**
+ * S-589 —— 文件历史的**装配单点**与能力词 `fileHistoryCapture` 的闭集(叶模块:只 type-import store-backend)。
+ *
+ * ## 病(修前)
+ * `boot/budget-tracing.ts` 只要后端有文件历史店就无条件交给 core(`RunnerDeps.fileHistoryStore`)。core 的首次触碰
+ * 捕获是**进程级**的:接了店就恒捕获,没有任何单会话 / 单 run 的杠杆;全仓相关旋钮只有保留条数
+ * `FILE_HISTORY_RETENTION_KEEP`。于是用户在客户端关掉「文件检查点」关掉的只是提示,文件字节照旧进
+ * `file_history_*` —— 隐私 / 留存轴上的用户面语义谎言。
+ *
+ * ## 一处判定,两张脸(按动词类别切分,不是特例)
+ * 「这台部署有没有文件历史店」只在 {@link assembleFileHistory} 判一次,部署旋钮 `FILE_HISTORY_CAPTURE` 在这一处合取:
+ *  · **捕获脸** `store` = 后端 ∧ 旋钮。喂 core 的首次触碰捕获(`RunnerDeps.fileHistoryStore`)、rewind 族能力位
+ *    (`rewindFiles` / `restoreFiles` / `rewindFilesTo` / `sessionSync`)与本模块的能力词、2c sync 路由族。
+ *  · **擦除脸** `erasure` = 后端在即在,类型上**只有删除类动词**。喂 E21 在线删除(`boot/session-faces.ts`)与
+ *    孤儿 blob GC(`boot/reapers.ts`)。
+ * 规则一句话:**旋钮只管写入,从不管擦除**。关掉捕获的部署照样要能删掉已经捕获的文件字节 —— 否则翻旋钮之后
+ * `DELETE /v1/sessions/:id` 会回成功却把存量文件内容留在库里,而留存车道(`plugins/retention-store-sql.ts` 的
+ * 原生 SQL 删六张 `file_history_*` 表,本来就不看店在不在)与在线删除从此不再等价(E21 两个执行体分家)。
+ * ⚠️ 关掉 ≠ 删掉:翻旋钮**不**做任何批量删除。已捕获的历史照既有的会话删除 / 留存规则清理;在旋钮关着的
+ * 部署上它也不会再被读用(rewind / restore / sync 都随捕获脸一起缺席)。
+ *
+ * ## 能力词为什么是闭集两词、没有 `on-optional`
+ * cli 要的是「`/config` 那个开关该不该出现」。present-iff 布尔在今天的**每一台**部署上都只能回答「关不掉」
+ * (core 的捕获是进程级的)⇒ 出一格三词闭集的前两词:`off`(这台部署根本不捕获,也没有 rewind)与
+ * `on-always`(捕获中,且无法按会话关闭)。第三词 `on-optional`(「本会话可以不捕获」)要等 core 收一个
+ * 单会话 / 单 run 的不捕获位,**在那之前刻意留空**:预先声明一个结构上不可达的词,等于给客户端一个永远等不到的分支。
+ */
+import type { ServiceFileHistoryStore, StoreBackend } from "./plugins/store-backend.js";
+/** 能力词闭集的单点属主(`Record` 锁步:联合加词而这里不补 ⇒ 编译红;词表数组由它派生,不手抄)。 */
+declare const FILE_HISTORY_CAPTURE_WORD_SET: {
+    readonly off: true;
+    readonly "on-always": true;
+};
+/** `GET /v1/capabilities` 的 `fileHistoryCapture` 词。 */
+export type FileHistoryCapture = keyof typeof FILE_HISTORY_CAPTURE_WORD_SET;
+/** 闭集的全部词(契约文档门 / 测试据此对表)。 */
+export declare const FILE_HISTORY_CAPTURE_WORDS: readonly FileHistoryCapture[];
+/** 擦除脸 —— 物理店上**只有删除类**的那几个动词(类型收窄 = 结构上拿它捕获不了、导出不了、还原不了)。
+ *  `reap` 是 core 契约必填(local File 店没有整 scope 的 `deleteBySession`,E21 在那条车道上退回 `reap(scope, [])`);
+ *  `deleteBySession` / `sweepOrphanBlobs` 是 SQL 双生的服务端额外动词。 */
+export type FileHistoryErasureFace = Pick<ServiceFileHistoryStore, "reap" | "deleteBySession" | "sweepOrphanBlobs">;
+/** 装配结果:两张脸。 */
+export interface FileHistoryAssembly {
+    /** 捕获脸:在场 ⟺ 后端在 ∧ `FILE_HISTORY_CAPTURE`。 */
+    readonly store: ServiceFileHistoryStore | undefined;
+    /** 擦除脸:在场 ⟺ 后端在(与旋钮无关)。 */
+    readonly erasure: FileHistoryErasureFace | undefined;
+}
+/**
+ * **唯一**的装配判定。`capture` = 部署旋钮 `FILE_HISTORY_CAPTURE`(`config.fileHistoryCapture`)。
+ *
+ * 形照 `execution-lane-caps.ts` 的穷举 switch(无 default 臂):意图词加一个(将来的 `on-optional`)而这里不加臂
+ * ⇒ 编译红 —— 加臂的那一刻就是决定「这一词下捕获脸接不接、core 那一位单会话不捕获位怎么递」的地方。
+ */
+export declare function assembleFileHistory(backend: StoreBackend | undefined, capture: boolean): FileHistoryAssembly;
+/**
+ * 能力词 = 捕获脸在不在(读**装配结果**,不照旋钮字面回声:后端本来就没有这只店的部署同样是 `off`)。
+ *
+ * 与 `rewindFiles` 读的是**同一个判定**(`deps.fileHistoryStore` 在场),今天两位同构。分叉条件(写在这里免得
+ * 将来有人把两位当成一回事):core 收了单会话不捕获位之后,本词在捕获脸在场时会变成 `on-optional`,而
+ * `rewindFiles` 仍是 true —— 它回答的是「这台部署能不能还原」,本词回答的是「捕获关不关得掉」。
+ */
+export declare function fileHistoryCaptureOf(captureFace: object | undefined): FileHistoryCapture;
+export {};
+//# sourceMappingURL=file-history-capture.d.ts.map

package/dist/file-history-capture.js

@@ -0,0 +1,21 @@
+const FILE_HISTORY_CAPTURE_WORD_SET = {
+    off: true,
+    "on-always": true,
+};
+export const FILE_HISTORY_CAPTURE_WORDS = Object.keys(FILE_HISTORY_CAPTURE_WORD_SET);
+export function assembleFileHistory(backend, capture) {
+    if (backend === undefined)
+        return { store: undefined, erasure: undefined };
+    const physical = backend.fileHistory();
+    const intent = capture ? "on-always" : "off";
+    switch (intent) {
+        case "off":
+            return { store: undefined, erasure: physical };
+        case "on-always":
+            return { store: physical, erasure: physical };
+    }
+}
+export function fileHistoryCaptureOf(captureFace) {
+    return captureFace === undefined ? "off" : "on-always";
+}
+//# sourceMappingURL=file-history-capture.js.map

package/dist/hooks/hook-llm.d.ts

@@ -9,7 +9,7 @@ import type { HookLlmCall } from "./hook-runner.js";
  *  - `openai-completions` ⇒ POST {base}/chat/completions(现状,字节不变);
  *  - `anthropic-messages` ⇒ POST {base}/v1/messages(x-api-key / Authorization: Bearer + anthropic-version
  *    头,messages 数组,回包取 content[].text)。此前 hookLlm 只会说 openai 形且缺省 baseUrl 恒落
- *    `config.gatewayBaseUrl`(缺省 http://127.0.0.1:8000/v1)——anthropic 单路由部署(主模型
+ *    `config.gatewayBaseUrl`(当年它有一个本机 8000 端口的出厂缺省,S-623 已删)——anthropic 单路由部署(主模型
  *    provider=anthropic 走 ANTHROPIC_BASE_URL,没配 MODEL_GATEWAY_BASEURL)下 titler 每会话打死
  *    localhost:8000 ⇒ `session_title_failed: TypeError: fetch failed`;即使端点活着,anthropic-messages
  *    模型也不能用 /chat/completions 形调。

package/dist/hooks/hook-llm.js

@@ -1,5 +1,6 @@
 import { adjudicateModelRoute, joinRequestUrl, resolveRouteCredential, routeKeyOf, routeRefusalText } from "@sema-agent/core";
 import { matchCatalogModel } from "../model-select.js";
+import { resolveOpenaiRouteEndpoint } from "../model-route-endpoint.js";
 import { buildDisplaySafeRefusal, redactSecrets } from "../trace/redact.js";
 export function buildHookFailureText(raw) {
     if (raw === "")
@@ -26,7 +27,8 @@ export function createHookLlm(deps) {
             }
             return { ok: true, catalogRef, providerModelId, baseUrl, api };
         }
-        return { ok: true, catalogRef, providerModelId, baseUrl: m?.baseUrl || config.gatewayBaseUrl, api };
+        const endpoint = resolveOpenaiRouteEndpoint(catalogRef, m?.baseUrl, config.gatewayBaseUrl);
+        return endpoint.ok ? { ok: true, catalogRef, providerModelId, baseUrl: endpoint.baseUrl, api } : { ok: false, error: endpoint.refusal };
     };
     const hookModelFor = (requested) => {
         const shape = (ref) => shapeFrom(ref, config.models[ref], config.models[ref]?.id ?? ref);

package/dist/hosted-posture.d.ts

@@ -151,7 +151,7 @@ export type TaskHostPostureScope = HostedPostureInput & Readonly<Pick<ServiceCon
  *
  * 🔴 **为什么这一条不拒**(初版给了 422,当批撤回):这个键**零授权** —— 引擎只把它渲给模型,没有任何
  * 裁决腿读它(`http/wire-types.ts` 的字段注逐字,来源是 core 的 `ApproverPosture` 头注)。而续跑腿
- * **逐字重放盘上的体**,调用方**删不掉**它 ⇒ 一条 park 会被永久砖死;`resumePlanReview` 上更贵:
+ * **逐字重放盘上的体**,调用方**删不掉**它 ⇒ 一条 park 会被永久砖死;plan_review 驱动段(`drivePlanReview`)上更贵:
  * nonce 先烧、拒在其后才抛,运维重签再撞同一个拒 = 无限循环。本仓对这一类的成文结论逐字是
  * 「**砖死 resume 比降级糟**」(`boot/resolve-spec.ts` 顶部那段列了三处先例)。
  * ⇒ 把本批最硬的处置给族里**危害最小**的成员,方向是错的。

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

@@ -17,7 +17,7 @@ import type { DecideBinding } from "./wire-types.js";
 import type { CheckpointStoreFull } from "../plugins/store-backend.js";
 import { type HostDecision } from "../host-decision.js";
 import { type PlanApprovePermissionModeAfter } from "../task-settings.js";
-import type { RouteCtxBase, DriveResumeArgs } from "./route-ctx.js";
+import type { RouteCtxBase, DriveResumeArgs, PreparedPlanReview } from "./route-ctx.js";
 import { type TrustedRunInternals } from "./durable-run-leg.js";
 import type { RunRegistry, RouteHelpers, RouteLegs } from "./route-ctx.js";
 import type { createRequestGuards } from "./request-guards.js";
@@ -67,13 +67,23 @@ export declare function createResumeLegs(ctx: {
         status: number;
         body: object;
     }>;
-    resumePlanReview: (sessionId: string, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, req: IncomingMessage | undefined, log?: {
+    preparePlanReview: (sessionId: string, log?: {
         taskId?: string;
         principalPresent?: boolean;
-    }, acceptEarly?: boolean, decider?: {
+    }, decider?: {
         principal?: string;
         explicitOperator: boolean;
-    }, permissionModeAfter?: PlanApprovePermissionModeAfter) => Promise<{
+    }) => Promise<{
+        readonly ok: false;
+        readonly answer: {
+            status: number;
+            body: object;
+        };
+    } | {
+        readonly ok: true;
+        readonly prepared: PreparedPlanReview;
+    }>;
+    drivePlanReview: (prepared: PreparedPlanReview, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, req: IncomingMessage | undefined, acceptEarly?: boolean, permissionModeAfter?: PlanApprovePermissionModeAfter) => Promise<{
         status: number;
         body: object;
     }>;

package/dist/http/resume-legs.js

@@ -64,6 +64,9 @@ function checkpointRowRedeemableElsewhere(reason) {
     return reason !== undefined && WORKER_SWAP_REDEEMABLE[reason] === true;
 }
 const NON_BINDING_INVALID_OUTCOME_FIELDS = new Set(["hostDecision", "approver"]);
+function notResumableAnswer() {
+    return { status: 409, body: { error: "run is not in a resumable (suspended) state (already resumed, decided, or expired)", errorCode: "conflict.not_resumable" } };
+}
 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");
@@ -458,7 +461,7 @@ export function createResumeLegs(ctx) {
         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" } };
+                return notResumableAnswer();
             markChildrenStoppedByUserOnAbort(cancelCtrl.signal, taskId, principal);
             fleetPub?.onStart();
             const rs = deps.runStore;
@@ -1179,8 +1182,9 @@ export function createResumeLegs(ctx) {
             ...(ownerLeaseAdmittedFor !== undefined && auth.principal === ownerLeaseAdmittedFor ? { ownerLeaseAdmitted: true } : {}),
         });
     }
-    async function resumePlanReview(sessionId, decision, editedPlan, reason, req, log, acceptEarly, decider, permissionModeAfter) {
+    async function preparePlanReview(sessionId, log, decider) {
         const cs = deps.checkpointStore;
+        const refuse = (answer) => ({ ok: false, answer });
         const log404 = (r) => deps.logger?.info?.("decide_404", {
             reason: r,
             ...(log?.taskId !== undefined ? { taskId: log.taskId } : { sessionId }),
@@ -1192,7 +1196,7 @@ export function createResumeLegs(ctx) {
         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;
+            return refuse(noPending);
         }
         if (decider !== undefined && !decider.explicitOperator) {
             const peeked = await cs
@@ -1202,7 +1206,7 @@ export function createResumeLegs(ctx) {
             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;
+                return refuse(noPending);
             }
         }
         let cp;
@@ -1212,40 +1216,45 @@ export function createResumeLegs(ctx) {
         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 refuse(noPending);
             }
-            return { status: 409, body: { error: e instanceof Error ? e.message : String(e), errorCode: "conflict.checkpoint_unreadable" } };
+            return refuse({ 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" } };
+                return refuse(noPending);
+            return refuse({ 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;
+            return refuse(noPending);
         }
         const gateKind = cp.gate?.kind;
         if (gateKind !== PLAN_REVIEW_GATE_KIND) {
-            return {
+            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`,
                     errorCode: "gate_not_plan_review",
                 },
-            };
+            });
         }
         const ctxRead = await readResumeCtx(cs.getCtx(sessionId));
         if (ctxRead.kind === "corrupt")
-            return resumeCtxCorruptAnswer(ctxRead.where);
+            return refuse(resumeCtxCorruptAnswer(ctxRead.where));
         if (ctxRead.kind === "absent")
-            return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
-        const ctx = ctxRead.ctx;
+            return refuse({ status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } });
+        return { ok: true, prepared: { sessionId, token, cp, ctx: ctxRead.ctx } };
+    }
+    async function drivePlanReview(prepared, decision, editedPlan, reason, 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 };
         const effMode = storedBodyPermissionMode(ctx.body);
         if (permissionModeAfter !== undefined && effMode !== "plan") {
-            throw new Error("resumePlanReview: permissionModeAfter was passed for a task that was not submitted with permissionMode \"plan\" — the caller must refuse this before any state changes (see the plan_review route's pre-nonce gate)");
+            throw new Error("drivePlanReview: permissionModeAfter was passed for a task that was not submitted with permissionMode \"plan\" — the caller must refuse this before any state changes (see the plan_review route's pre-nonce gate)");
         }
         const approvedMode = decision === "approve" && effMode === "plan" ? (permissionModeAfter ?? "default") : undefined;
         const resumeBody = approvedMode === undefined ? ctx.body : { ...ctx.body, permissionMode: approvedMode };
@@ -1269,8 +1278,8 @@ export function createResumeLegs(ctx) {
         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(), capabilities: createCapabilitiesLocal() },
-        legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, resumePlanReview },
+        legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, preparePlanReview, drivePlanReview },
     };
-    return { routeCtxBase, resumeCheckpoint, driveResumeIntoRunLog, driveResumeLeg, mayDiscloseRowError, resumePreempted, startFreshHostTurn, resumeWake, resumePlanReview };
+    return { routeCtxBase, resumeCheckpoint, driveResumeIntoRunLog, driveResumeLeg, mayDiscloseRowError, resumePreempted, startFreshHostTurn, resumeWake, preparePlanReview, drivePlanReview };
 }
 //# sourceMappingURL=resume-legs.js.map

package/dist/http/route-ctx.d.ts

@@ -16,7 +16,7 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { HostDecision } from "../host-decision.js";
-import type { TaskStream, TaskSpec, TaskResult, QuestionAnswer, CheckpointToken, ResumeOutcome, RunInternals, Runner, EngineNotice } from "@sema-agent/core";
+import type { TaskStream, TaskSpec, TaskResult, QuestionAnswer, Checkpoint, CheckpointToken, ResumeOutcome, RunInternals, Runner, EngineNotice } from "@sema-agent/core";
 import type { FlatServiceDeps, RequestAuth } from "./server.js";
 import type { TaskRequestBody, DecideBinding } from "./wire-types.js";
 import type { IdempotencyCache, SubmitOutcome } from "./idempotency.js";
@@ -154,7 +154,7 @@ export interface DriveResumeArgs {
     /**
      * 🔴 **S-433 合并复审 F2 [high] —— 「本次续跑真正用的那个体」,由本腿在赢下 CAS 之后写回耐久层**
      * (验真后修;必填 —— `driveResumeIntoRunLog` 今天恰有**四个**调用点:legacy `/decide`(`resumeCheckpoint`)、
-     * `resumePreempted`、`resumeWake`、`resumePlanReview`,四条一视同仁)。
+     * `resumePreempted`、`resumeWake`、`drivePlanReview`(S-609 前名 `resumePlanReview`),四条一视同仁)。
      *
      * 病(修前):`resumePlanReview` 在 `driveResumeIntoRunLog` **受理(2xx)之后**才 `putCtx(sessionId,
      * {...ctx, body})`,而 `ctx` 是请求**开头** `getCtx` 读到的那一份,两个店的 `putCtx` 又都是按
@@ -177,7 +177,7 @@ export interface DriveResumeArgs {
      * 🔴 写失败**响亮但不致命**(codex r1 两条 [high] 验真后定):core 的 `resumeStream` 是 **EAGER** 的 ——
      * 写点这一拍 run 已经在执行,裸抛会把一条活腿判成 failed + 释放 claim 而执行还在继续。⇒ 一个臂、
      * 四条腿同守:计数 `resume_ctx_not_persisted_total` + 一行 warn,本次续跑照常。方向论证(不是 [ref] 的
-     * 静默放宽):写失败 ⇒ 耐久体保持**上一次**的值,而这四条腿里只有 `resumePlanReview` 改写这个体、
+     * 静默放宽):写失败 ⇒ 耐久体保持**上一次**的值,而这四条腿里只有 `drivePlanReview` 改写这个体、
      * 且只会**放宽** ⇒ 落盘的恒不比本次续跑更宽。旧的 `plan_approve_mode_not_persisted`(plan 专用)随本批删除,
      * 由上面这只家族级的取代。全文见 `resume-legs.ts` 的 `commitResumeCtx` 顶注。
      */
@@ -311,6 +311,17 @@ export interface DriveResumeArgs {
      */
     ownerLeaseAdmitted?: boolean;
 }
+/**
+ * S-609(7.97.0):plan_review 纯读段全部过关后交给驱动段的那一份 —— **选中的那张卡**(token + 载入的行)与**它那一刻**
+ * 的续跑上下文。三者一起走:驱动段只认这张卡,ctx 读绑在它上面(读在选卡之后;之后任何 ctx 写都得先赢这张卡的
+ * CAS,于是一份过期的读只会让驱动段在 CAS 上败,不会被配给别的卡)。
+ */
+export interface PreparedPlanReview {
+    readonly sessionId: string;
+    readonly token: CheckpointToken;
+    readonly cp: Checkpoint;
+    readonly ctx: CheckpointCtx;
+}
 /** 提交/续跑「腿」= 跨域共享的**有状态**长流程(不像 {@link RouteHelpers} 那样只依赖 deps/config:它们要写
  *  run log、发 fleet 帧、走 markResuming CAS、驱动模型)。A9 上批的停点就在这里——tasks/runs 两域共用
  *  `prepareSpec`,approvals/assistant/notify-wake 三域共用 resume 家族,把它们跟着任一域搬都会造出
@@ -395,21 +406,36 @@ export interface RouteLegs {
         status: number;
         body: object;
     }>;
-    /** assistant plan_review 三态腿。 */
-    resumePlanReview(sessionId: string, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, req: IncomingMessage | undefined, 
+    /**
+     * assistant plan_review 三态腿的**纯读段**(S-609,7.97.0):选卡 → 属主轻读 → 载入 → 行级 scope → 门类 → 这条决断
+     * 唯一的一次 ctx 读。任何一步拒 ⇒ `{ok:false, answer}`(不改任何状态;端点在消费一次性 nonce **之前**把它答出去);
+     * 全部过关 ⇒ `{ok:true, prepared}`,交给 {@link RouteLegs.drivePlanReview}。语义属主 = `resume-legs.ts` 同名函数顶注。
+     */
+    preparePlanReview(sessionId: string, 
     /** [ref]/[ref] 件5:`decide_404` 判别日志的附加位(只进日志,不上 wire;身份只记有无不记值)。 */
     log?: {
         taskId?: string;
         principalPresent?: boolean;
     }, 
-    /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/plan_review` 腿传 `true`。 */
-    acceptEarly?: boolean, 
-    /** [ref]②([ref]):调用方已验身份的裁定(直连门 = HMAC 验出的 principal)—— 腿内行级属主复核
+    /** [ref]②([ref]):调用方已验身份的裁定(直连门 = HMAC 验出的 principal)—— 属主轻读与行级属主复核
      *  ([ref] R3 同形;缺席 = 匿名 dev 部署,不咬)。 */
     decider?: {
         principal?: string;
         explicitOperator: boolean;
-    }, 
+    }): Promise<{
+        readonly ok: false;
+        readonly answer: {
+            status: number;
+            body: object;
+        };
+    } | {
+        readonly ok: true;
+        readonly prepared: PreparedPlanReview;
+    }>;
+    /** plan_review 三态腿的**驱动段**(S-609):只吃 prepare 的结果,用它选定的 token,不再选卡、不再读 ctx。 */
+    drivePlanReview(prepared: PreparedPlanReview, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, req: IncomingMessage | undefined, 
+    /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/plan_review` 腿传 `true`。 */
+    acceptEarly?: boolean, 
     /** S-433:批准之后这条会话继续用的 permission mode(闭集 `PLAN_APPROVE_PERMISSION_MODES_AFTER`;只在 `approve`
      *  上有意义,缺席 ⇒ `"default"`)。语义与判据的唯一属主 = `resume-legs.ts` 的同名形参顶注。 */
     permissionModeAfter?: PlanApprovePermissionModeAfter): Promise<{

package/dist/http/routes/approvals-assistant.d.ts

@@ -36,7 +36,7 @@ export declare function planReviewBodyKeyIssue(raw: unknown): KeyClosureIssue |
  *  · **签名域**(直连门的 HMAC 信封第五位)—— 属主是**跨仓字节契约**(§6.2 / `approvalHmacMessage`,
  *    签名器在 cli / SDK)。那份契约明写空串与 `null` 是两个不同的被签值。⇒ **逐字线值,永不折叠**;
  *    在这里折一刀,一份合法签发的空理由证明就永远 401(合并复审 R1 [high] 真复现过)。
- *  · **上送域**(`resumePlanReview` / `resumeCheckpoint` 的 `reason` 尾参)—— 属主是**引擎的单铸点**
+ *  · **上送域**(`drivePlanReview` / `resumeCheckpoint` 的 `reason` 尾参)—— 属主是**引擎的单铸点**
  *    (7.19.0 / [ref] 把「人的结算」收进一个铸点,空文本在那里折成缺席,live 与 durable decide 两条路径同形)。
  *    ⇒ **原样透传**;跨仓宪法「源头修复禁下游旁路」:在下游再折一次就是同一语义的第二个写者,
  *    今天两者答案相同,上游哪天改法就变成一条谁都查不出来的分歧。

package/dist/http/routes/approvals-assistant.js

@@ -19,6 +19,8 @@ import { gatedPrincipal, explicitOperatorOk, isOperator, sendPrincipalRefusal }
 import { governanceOriginOf } from "../active-run-conflict.js";
 import { sendResumeOutcome } from "../route-ctx.js";
 import { assertNever } from "../route-ctx.js";
+import { readResumeCtx, resumeCtxCorruptAnswer } from "../resume-ctx-read.js";
+import { recordFailOpen } from "../../observability/fail-open.js";
 import { MAX_KEY_ECHO, keyClosureClause, scanKeyClosure } from "../../request-key-closure.js";
 const DECIDE_BODY_DECLARED_KEYS = [
     "answer", "boundCallId", "boundInputHash", "checkpointToken", "decision", "reason", "remember", "settledBy", "updatedInput",
@@ -199,7 +201,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
     const { deps } = ctx;
     const { preemptableRuns } = ctx.registry;
     const { readJson, rateLimited, quotaExceeded, safeDecode } = ctx.helpers;
-    const { resumeCheckpoint, resumePreempted, resumePlanReview } = ctx.legs;
+    const { resumeCheckpoint, resumePreempted, preparePlanReview, drivePlanReview } = ctx.legs;
     {
         const cs = deps.checkpointStore;
         const principal = gatedPrincipal(req, deps.config);
@@ -271,7 +273,10 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
             const scope = operator && ownerParam ? ownerParam : (principal ?? "__none__");
             const summaries = await cs.listByScope(scope);
             const inbox = (await Promise.all(summaries.map(async (s) => {
-                const ctx = await cs.getCtx(s.sessionId).catch(() => null);
+                const ctxRead = await readResumeCtx(cs.getCtx(s.sessionId));
+                if (ctxRead.kind === "corrupt")
+                    recordFailOpen("server.assistant-inbox.objective-ctx-corrupt", ctxRead.where);
+                const objective = ctxRead.kind === "ok" ? (ctxRead.ctx.body?.objective ?? null) : null;
                 const input = s.toolInput != null ? redactedPreview(s.toolInput) : null;
                 return {
                     sessionId: s.sessionId,
@@ -286,7 +291,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     ...(s.denialLimitFallback !== undefined ? { denialLimitFallback: s.denialLimitFallback } : {}),
                     ...(s.origin !== undefined ? { origin: s.origin } : {}),
                     ...(s.ruleStoreUnreadable !== undefined ? { ruleStoreUnreadable: s.ruleStoreUnreadable } : {}),
-                    objective: ctx?.body?.objective ?? null,
+                    objective,
                     input,
                 };
             }))).sort((a, b) => (b.severity ?? 0) - (a.severity ?? 0) || (a.createdAt ?? 0) - (b.createdAt ?? 0));
@@ -520,9 +525,14 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                 sendError(res, 404, "not_found.run", "task not found");
                 return;
             }
+            const plan = await preparePlanReview(run.sessionId, { taskId, principalPresent: principal !== undefined }, { principal: deciderPrincipal, explicitOperator });
+            if (!plan.ok) {
+                sendResumeOutcome(res, plan.answer, deps.logger);
+                return;
+            }
             if (body.permissionModeAfter !== undefined) {
-                const storedCtx = await deps.checkpointStore?.getCtx(run.sessionId).catch(() => null);
-                if (storedCtx?.body !== undefined && storedBodyPermissionMode(storedCtx.body) !== "plan") {
+                const storedCtx = plan.prepared.ctx;
+                if (storedCtx.body !== undefined && storedBodyPermissionMode(storedCtx.body) !== "plan") {
                     sendError(res, 400, "request.field_conflict", "permissionModeAfter does not apply to this task: it was not submitted with permissionMode \"plan\", so approving the plan lifts no read-only restriction");
                     return;
                 }
@@ -539,7 +549,7 @@ export async function handleApprovalsAssistant(req, res, match, ctx) {
                     return;
                 }
             }
-            const out = await resumePlanReview(run.sessionId, decision, decision === "edit" ? body.editedPlan : undefined, typeof body.reason === "string" ? body.reason : undefined, req, { taskId, principalPresent: principal !== undefined }, true, { principal: deciderPrincipal, explicitOperator }, isPlanApprovePermissionModeAfter(body.permissionModeAfter) ? body.permissionModeAfter : undefined);
+            const out = await drivePlanReview(plan.prepared, decision, decision === "edit" ? body.editedPlan : undefined, typeof body.reason === "string" ? body.reason : undefined, req, true, isPlanApprovePermissionModeAfter(body.permissionModeAfter) ? body.permissionModeAfter : undefined);
             sendResumeOutcome(res, out, deps.logger);
             return;
         }

package/dist/http/routes/capabilities.js

@@ -12,6 +12,7 @@ import { buildEmptyMcpProbeFace, buildMcpInjectionRefusal, buildMcpProbeCacheKey
 import { mcpForScenario } from "../../config-center/facade.js";
 import { sendJson, sendError } from "../send.js";
 import { assertNever } from "../route-ctx.js";
+import { fileHistoryCaptureOf } from "../../file-history-capture.js";
 import { resolveStreamApprovalGate } from "../../tool-approval.js";
 import { projectMemoryEngineCapability } from "../../memory-posture.js";
 import { projectWriteProtectionCapability } from "../../write-protection.js";
@@ -173,6 +174,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 rewindFiles: Boolean(deps.fileHistoryStore),
                 restoreFiles: Boolean(deps.fileHistoryStore),
                 rewindFilesTo: Boolean(deps.fileHistoryStore && deps.resumeAnchorStore && deps.sessionStorage?.getLeafId),
+                fileHistoryCapture: fileHistoryCaptureOf(deps.fileHistoryStore),
                 scheduler: Boolean(deps.config.schedulerEnabled && deps.config.requirePrincipal !== true && deps.config.remoteExec?.provider === "host"),
                 sessionSync: Boolean(deps.backend && deps.sessionStorage?.exportEntries && deps.sessionStorage?.beginImportStaging && deps.fileHistoryStore),
                 sendUserFile: Boolean(deps.sendUserFile && deps.config.sendUserFile?.publicEndpoint),

package/dist/http/routes/runs.js

@@ -589,7 +589,7 @@ export async function handleRuns(req, res, match, ctx) {
                 const leafId = await Promise.resolve(deps.sessionStorage.getLeafId(run.sessionId)).catch(() => undefined);
                 if (leafId === undefined || leafId === null)
                     return;
-                const resumeRead = await readResumeCtx(Promise.resolve(cs.getCtx(run.sessionId)));
+                const resumeRead = await readResumeCtx(cs.getCtx(run.sessionId));
                 if (resumeRead.kind === "corrupt") {
                     mintResult.corruptCtxWhere = resumeRead.where;
                     return;
@@ -612,7 +612,7 @@ export async function handleRuns(req, res, match, ctx) {
                     createdAt: Date.now(),
                     sourceTaskId: taskId,
                 });
-                const stillRead = await readResumeCtx(Promise.resolve(cs.getCtx(run.sessionId)));
+                const stillRead = await readResumeCtx(cs.getCtx(run.sessionId));
                 if (stillRead.kind === "corrupt") {
                     await cs.expire(wakeToken, cpScope).catch(() => undefined);
                     mintResult.corruptCtxWhere = stillRead.where;

package/dist/http/routes/session-sync.js

@@ -41,6 +41,11 @@ export async function handleSessionSync(req, res, match, ctx) {
                 sendError(res, 501, "capability.session_store_required", "session sync requires a durable session store");
                 return;
             }
+            const historyStore = deps.fileHistoryStore;
+            if (historyStore === undefined) {
+                sendError(res, 501, "capability.snapshot_store_required", "session sync is not available on this deployment: file-history capture is turned off (FILE_HISTORY_CAPTURE=false), so there is no file history to export or import");
+                return;
+            }
             const scope = sessionOwnerScopeForWrite(req);
             if (!scope.fleetWide && scope.gateOwner === null) {
                 sendError(res, 401, "auth.unauthorized", "unauthorized");
@@ -76,7 +81,7 @@ export async function handleSessionSync(req, res, match, ctx) {
                     return;
                 let out;
                 try {
-                    out = await exportSessionManifest(sessionId, deps.backend);
+                    out = await exportSessionManifest(sessionId, deps.backend, historyStore);
                 }
                 catch (e) {
                     if (sendSessionPolicyError(res, e))

package/dist/http/server.d.ts

@@ -146,7 +146,10 @@ export interface ServiceStoreDeps {
     toolResultStore?: ToolResultStoreFull;
     /** [ref] per-edited-file rewind history store. Present ⇒ the rewind capabilities are advertised; core uses it
      *  via RunnerDeps.fileHistoryStore (first-touch tracking + per-turn boundaries + tracked-set restore, ANY
-     *  env). Also the 2c history-transfer store (exportHistory/importHistory + blob negotiation faces). */
+     *  env). Also the 2c history-transfer store (exportHistory/importHistory + blob negotiation faces).
+     *  🔴 S-589:这是装配单点 `assembleFileHistory` 的**捕获脸**(后端 ∧ `FILE_HISTORY_CAPTURE`),不是「后端有没有这只店」
+     *  —— 旋钮关着时它缺席,rewind 族四位、能力词 `fileHistoryCapture` 与 2c sync 路由族一起按「店不在」走。
+     *  擦除(E21 / 孤儿 blob GC)不读本键,读 boot 侧的擦除脸。 */
     fileHistoryStore?: ServiceFileHistoryStore;
     /** D-1 通用文件上传(clay 拍 2026-07-27:独立附件 store,不骑 snapshot blob 面):enables
      *  POST/GET/DELETE /v1/attachments*。缺席 ⇒ 501(与其他可选 store 面同姿)。绑定/物化半场在

package/dist/http/server.js

@@ -94,7 +94,7 @@ export function createHttpServer(rawDeps) {
     }
     const { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, isFleetWide, sessionOwnerScope, sessionOwnerScopeForWrite, runOwnerOk, runSessionAcceptOk, readJson, readRawBody } = createRequestGuards({ deps });
     const { prepareSpec } = createAdmission({ deps, readJson, runnerFor });
-    const { routeCtxBase, resumeCheckpoint, driveResumeIntoRunLog, driveResumeLeg, mayDiscloseRowError, resumePreempted, startFreshHostTurn, resumeWake, resumePlanReview } = createResumeLegs({ 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 });
+    const { routeCtxBase, resumeCheckpoint, driveResumeIntoRunLog, driveResumeLeg, mayDiscloseRowError, resumePreempted, startFreshHostTurn, resumeWake } = createResumeLegs({ 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 });
     const { denyExpiredApprovals, redeemParkedAsk } = createApprovalSweeps({ deps, resumeCheckpoint, mayDiscloseRowError });
     const { handle } = createDispatch({ deps, noteActivity, routeCtxBase, counters });
     const server = http.createServer((req, res) => {

package/dist/http/verify-rounds.d.ts

@@ -19,6 +19,6 @@ export declare function clampVerifyRounds(v: unknown): number;
 /** `undefined` when `body.verify` is not `true` (the caller didn't opt into the gate); otherwise the clamped
  *  rounds + (if `maxCostUsd` is a positive number) the same USD→micro-USD cost ceiling the cascade lane uses.
  *  Same expression that lived inline at all four verify/resume call sites in http/server.ts (fresh-submit,
- *  resumeCheckpoint, resumePreempted, resumePlanReview) — collected here VERBATIM ([ref] R9). */
+ *  resumeCheckpoint, resumePreempted, drivePlanReview — named resumePlanReview before S-609) — collected here VERBATIM ([ref] R9). */
 export declare function verifyRoundsFromBody(body: Pick<TaskRequestBody, "verify" | "verifyRounds" | "maxCostUsd">): VerifyRoundsSpec | undefined;
 //# sourceMappingURL=verify-rounds.d.ts.map