@sema-agent/server 7.85.0 → 7.87.0

package/dist/http/resume-legs.js

@@ -1,4 +1,4 @@
-import { redactErrorMessage, redactHead } from "../observability/run-terminal-log.js";
+import { redactErrorMessage, redactHead } from "../observability/run-terminal.js";
 import { createHash } from "node:crypto";
 import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, validatePendingSteer, GLOBAL_USAGE_KEY, terminalProjection, PAUSE_REGISTRY } from "@sema-agent/core";
 import { decideParkedAgent, denyWorkflowParksUnreadable, findParkOrigin, planWorkflowParkedDecide } from "../parked-decide.js";
@@ -24,6 +24,7 @@ import { reasoningDeltaBytes, reasoningSegmentEventId } from "../trace/model-seg
 import { errorText } from "../observability/err-text.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { verifyRoundsFromBody } from "./verify-rounds.js";
+import { storedBodyPermissionMode } from "../task-settings.js";
 import { acceptedResumingReceipt } from "./route-ctx.js";
 import { mintAndDriveDurableRun } from "./durable-run-leg.js";
 import { createSessionsLocal } from "./routes/sessions.js";
@@ -320,7 +321,7 @@ export function createResumeLegs(ctx) {
             hostDecision,
         };
         const verifyRounds = verifyRoundsFromBody(ctx.body);
-        const driven = await driveResumeIntoRunLog({ runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, verifyRounds, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(boundGrant ? { onResumeCommitted: boundGrant } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}), ...(ownerLeaseAdmittedHere ? { ownerLeaseAdmitted: true } : {}) });
+        const driven = await driveResumeIntoRunLog({ runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, 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;
     }
@@ -353,7 +354,11 @@ export function createResumeLegs(ctx) {
     }
     async function driveResumeLeg(args, onAccepted) {
         const resumeLegStartedAt = Date.now();
-        const { runner: legRunner, token, sessionId, principal, fleetScope, taskConfig, resumeObjective, outcome, verifyRounds } = args;
+        const { runner: legRunner, token, sessionId, principal, fleetScope, taskConfig, resumeObjective, outcome, verifyRounds, resumeCtx } = args;
+        const commitResumeCtx = () => deps.checkpointStore.putCtx(resumeCtx.sessionId, resumeCtx.ctx).catch((e) => {
+            deps.metrics?.inc("resume_ctx_not_persisted_total");
+            deps.logger?.warn?.("resume_ctx_not_persisted", { sessionId: resumeCtx.sessionId, gate: outcome.gate, error: errorText(e), note: "this continuation runs with the body it was given; the durable rebuild input still holds the PREVIOUS body, so the NEXT continuation of this session rebuilds from that one (never wider than this leg's)" });
+        });
         const legKey = createHash("sha256").update(String(token)).digest("hex");
         const streamApprovalOn = resolveStreamApprovalGate({
             toolApprovalEnabled: Boolean(deps.toolApproval),
@@ -425,7 +430,8 @@ export function createResumeLegs(ctx) {
             try {
                 return (await store.get(token))?.status === "pending";
             }
-            catch {
+            catch (e) {
+                recordFailOpen("server.resume.reopen-confirm-unreadable", `task=${taskId ?? ""} err=${e instanceof Error ? e.message : String(e)}`);
                 return true;
             }
         };
@@ -539,6 +545,7 @@ export function createResumeLegs(ctx) {
                     };
                     resumeLegLive = true;
                     const vr = await resumeWithVerification(legRunner, token, outcome, { ...resumeTaskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, resumeObjective, verifyRounds, verifyInternals);
+                    await commitResumeCtx();
                     let safe = stripResumeToken(vr);
                     const vrNested = nestedPauseOf(vr.terminal);
                     const reParkStatus = nestedParkStatusOf(vr);
@@ -663,6 +670,7 @@ export function createResumeLegs(ctx) {
                             }
                             : {}),
                     });
+                    await commitResumeCtx();
                     resumeStreamRef = stream;
                     if (taskId)
                         steerableRuns.set(taskId, stream);
@@ -1026,7 +1034,7 @@ export function createResumeLegs(ctx) {
         const { spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth);
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
         const verifyRounds = verifyRoundsFromBody(ctx.body);
-        return driveResumeIntoRunLog({ runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome: { gate: "resource_limit", decision: "continue" }, verifyRounds, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
+        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) {
         const cs = deps.checkpointStore;
@@ -1139,6 +1147,7 @@ export function createResumeLegs(ctx) {
             resumeObjective,
             outcome: { gate: "wake", ...(message !== undefined ? { message: { text: message, trusted } } : {}) },
             verifyRounds: undefined,
+            resumeCtx: { sessionId, ctx },
             mintFreshRun: { source: "wake" },
             ...(engineNotices.length > 0 ? { engineNotices } : {}),
             ...(acceptEarly === true ? { acceptEarly: true } : {}),
@@ -1147,7 +1156,7 @@ export function createResumeLegs(ctx) {
             ...(ownerLeaseAdmittedFor !== undefined && auth.principal === ownerLeaseAdmittedFor ? { ownerLeaseAdmitted: true } : {}),
         });
     }
-    async function resumePlanReview(sessionId, decision, editedPlan, reason, req, log, acceptEarly, decider) {
+    async function resumePlanReview(sessionId, decision, editedPlan, reason, req, log, acceptEarly, decider, permissionModeAfter) {
         const cs = deps.checkpointStore;
         const log404 = (r) => deps.logger?.info?.("decide_404", {
             reason: r,
@@ -1208,7 +1217,13 @@ export function createResumeLegs(ctx) {
         if (!ctx)
             return { status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } };
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
-        const { spec, engineNotices } = await resolveResumeSpec(ctx.body, req, auth);
+        const 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)");
+        }
+        const approvedMode = decision === "approve" && effMode === "plan" ? (permissionModeAfter ?? "default") : undefined;
+        const resumeBody = approvedMode === undefined ? ctx.body : { ...ctx.body, permissionMode: approvedMode };
+        const { spec, engineNotices } = await resolveResumeSpec(resumeBody, req, auth);
         const { objective: resumeObjective, sessionId: _sessionId, ...taskConfig } = spec;
         const verifyRounds = verifyRoundsFromBody(ctx.body);
         const outcome = {
@@ -1217,7 +1232,8 @@ export function createResumeLegs(ctx) {
             ...(editedPlan !== undefined ? { editedPlan } : {}),
             ...(reason ? { reason } : {}),
         };
-        return driveResumeIntoRunLog({ runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, verifyRounds, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
+        const out = await driveResumeIntoRunLog({ runner: runnerFor(spec), token, sessionId: cp.sessionId, principal: auth.principal, fleetScope: resumeFleetScope(req, auth), taskConfig, resumeObjective, outcome, verifyRounds, resumeCtx: { sessionId, ctx: { ...ctx, body: resumeBody } }, ...(engineNotices.length > 0 ? { engineNotices } : {}), ...(acceptEarly === true ? { acceptEarly: true } : {}), ...(req !== undefined ? { callerInitiated: true } : {}) });
+        return out;
     }
     const routeCtxBase = {
         deps,

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

@@ -23,6 +23,7 @@ import type { IdempotencyCache } from "./idempotency.js";
 import type { ImagesLocal } from "./routes/images.js";
 import type { SessionsLocal } from "./routes/sessions.js";
 import type { SessionSyncLocal } from "./routes/session-sync.js";
+import type { PlanApprovePermissionModeAfter } from "../task-settings.js";
 import type { VerifyRoundsSpec } from "./verify-rounds.js";
 /** 跨域可变状态 = lens1 §C2 实测的那 8 条「运行期登记簿」,一个对象。 */
 export interface RunRegistry {
@@ -127,9 +128,55 @@ export interface PreparedTaskSubmission {
      *  经 `pending` 一起投(投递单点仍是那一只注册助手,不新开第二条机制)。缺席 = 本次装配没铸下任何通告。 */
     engineNotices?: readonly EngineNotice[];
 }
+/**
+ * 一条会话的**续跑重建输入**(`checkpoint_ctx` 的行体)—— 提交腿写一次,续跑腿读它重建 spec。
+ *
+ * S-433 F2 起命名化(此前是五处结构等价的内联字面 `{ body: TaskRequestBody; memoryScope?: string }`):
+ * 它同时是 {@link DriveResumeArgs.resumeCtx} 的形,而那一位是**写回**口 —— 读形与写形是同一件东西这句话
+ * 得由类型说,不能靠五处手抄碰巧一致。
+ */
+export interface CheckpointCtx {
+    body: TaskRequestBody;
+    /** 提交时这条会话绑定的记忆域(重建 `RequestAuth` 用);缺席 = 没有记忆面。 */
+    memoryScope?: string;
+}
 /** B4①(命名化):`driveResumeIntoRunLog` 的入参形(resume 家族共用)——原为 9 成员内联匿名对象。 */
 export interface DriveResumeArgs {
     token: CheckpointToken;
+    /**
+     * 🔴 **S-433 合并复审 F2 [high] —— 「本次续跑真正用的那个体」,由本腿在赢下 CAS 之后写回耐久层**
+     * (验真后修;必填 —— `driveResumeIntoRunLog` 今天恰有**四个**调用点:legacy `/decide`(`resumeCheckpoint`)、
+     * `resumePreempted`、`resumeWake`、`resumePlanReview`,四条一视同仁)。
+     *
+     * 病(修前):`resumePlanReview` 在 `driveResumeIntoRunLog` **受理(2xx)之后**才 `putCtx(sessionId,
+     * {...ctx, body})`,而 `ctx` 是请求**开头** `getCtx` 读到的那一份,两个店的 `putCtx` 又都是按
+     * `session_id` **无条件 upsert**(`checkpoint-store-sql.ts` / `local-checkpoint-store.ts`)。受理点之后
+     * 本腿已经可以跑完并 `setTerminal` 释放 `task_active` —— 别的副本随即 `createRun` + 写一份**新的** ctx,
+     * 然后这条迟到的写把它整只盖掉。那是一条**跨副本的丢写**,而被盖掉的恰恰是权限模式。
+     *
+     * 修法(单一写者,栅栏 = CAS 赢点,不引版本号/不加特判):写点移进 `driveResumeLeg`,落在
+     * `resumeStream` / `resumeWithVerification` **解析之后**(core 的 pre-CAS 守卫 + 原子 CAS 已经赢了)、
+     * 本腿驱终局之前。此时 park 行仍攥着 `task_active`,在本腿 `setTerminal` 之前**谁也建不了新 run** ⇒
+     * 写与释放天然串行;输掉 CAS 的决裁在 `resumeStream` 处就 reject,**永远到不了写点**(「先写回则输家
+     * 放宽」这个顾虑同时成立)。
+     *
+     * 不变量(规则变小,四条驱动腿一视同仁):**`ctx.body` 恒等于最近一次赢得 CAS 的续跑实际用的体**。
+     * 体没被改写的腿传**原 ctx** —— 同内容 upsert 幂等,不需要「只有 plan_review 才写」这条特判。
+     *
+     * 🔴 `sessionId` 自带一位:写回的键**恒是读进来的那一个**(各腿的 `sessionId` 形参,**不是**
+     * `cp.sessionId`)—— 读写不同键会写出一条谁也读不回来的行。
+     *
+     * 🔴 写失败**响亮但不致命**(codex r1 两条 [high] 验真后定):core 的 `resumeStream` 是 **EAGER** 的 ——
+     * 写点这一拍 run 已经在执行,裸抛会把一条活腿判成 failed + 释放 claim 而执行还在继续。⇒ 一个臂、
+     * 四条腿同守:计数 `resume_ctx_not_persisted_total` + 一行 warn,本次续跑照常。方向论证(不是 [ref] 的
+     * 静默放宽):写失败 ⇒ 耐久体保持**上一次**的值,而这四条腿里只有 `resumePlanReview` 改写这个体、
+     * 且只会**放宽** ⇒ 落盘的恒不比本次续跑更宽。旧的 `plan_approve_mode_not_persisted`(plan 专用)随本批删除,
+     * 由上面这只家族级的取代。全文见 `resume-legs.ts` 的 `commitResumeCtx` 顶注。
+     */
+    resumeCtx: {
+        sessionId: string;
+        ctx: CheckpointCtx;
+    };
     /** [ref]:续跑腿的执行 Runner。resume 会用同一条 resolveSpec 重解析场景,故与首跑选同一只 —— 否则
      *  一次续跑就把手带 band 重新 mount 回来(收窄只在首跑成立 = 没成立)。 */
     runner: Runner;
@@ -354,7 +401,10 @@ export interface RouteLegs {
     decider?: {
         principal?: string;
         explicitOperator: boolean;
-    }): Promise<{
+    }, 
+    /** S-433:批准之后这条会话继续用的 permission mode(闭集 `PLAN_APPROVE_PERMISSION_MODES_AFTER`;只在 `approve`
+     *  上有意义,缺席 ⇒ `"default"`)。语义与判据的唯一属主 = `resume-legs.ts` 的同名形参顶注。 */
+    permissionModeAfter?: PlanApprovePermissionModeAfter): Promise<{
         status: number;
         body: object;
     }>;
@@ -549,22 +599,6 @@ export declare function acceptedResumingReceipt(taskId: string, sessionId: strin
     status: number;
     body: object;
 };
-/**
- * 「**证得出**这条 run 活在别的副本上」——「他副本」那一句话的**唯一判据**(S-381 收编)。
- *
- * 成案:这个合取式此前在四处**逐字手抄**(`routes/runs.ts` 的 steer 臂与 interrupt 臂、同文件
- * `sendHandleMiss`、`routes/run-memory-capture.ts`),第五处就要随 `POST /v1/sessions/:id/mcp/reconnect`
- * 出现 —— 而它的每一个合取项都是一条**被复审逐条挣出来的**纪律,不是随手的判空:
- *  · `run.instanceId` 缺席(`null` / 建列之前的行 / 替身行的 `undefined`)= **不知道它在哪**,不是「在别处」;
- *  · `thisInstanceId` 缺席 = 本副本连自己是谁都说不上,更不能断言别人;
- *  · 两者都在场且**不等**才够格说「他副本」(`markResuming` 认领后该列语义 = **当前持有副本**)。
- * 抄第五份 = 第五个写者;收成一只谓词之后,纪律改一次就四处同改。**`status` 不进本谓词**:
- * `sendHandleMiss` 只对 `running` 行说这句话,而 steer 族在 park/终态两臂之后才走到这里 —— 各调用点
- * 的前置臂不同族,合进来会让某一处悄悄改判。
- */
-export declare function runProvenElsewhere(run: {
-    instanceId?: string | null;
-}, thisInstanceId: string | undefined): boolean;
 export declare const RUN_NOT_FOUND_MESSAGE = "run not found \u2014 the id belongs to no run in this deployment's run store (a run from another server process, or an in-memory store that did not survive a restart, is not visible here)";
 /** [ref] 前缀=域判别子既成契约:a\* 与 wa\* 形 id 给 TaskOutput/journal 指路;其余给 {@link RUN_NOT_FOUND_MESSAGE}。 */
 export declare function runNotFoundMessage(id: string): string;

package/dist/http/route-ctx.js

@@ -24,9 +24,6 @@ export const ROUTE_METHOD_ORDER = ["GET", "POST", "PUT", "DELETE"];
 export function acceptedResumingReceipt(taskId, sessionId) {
     return { status: 200, body: { taskId, sessionId, status: "resuming", bindingEnforced: true } };
 }
-export function runProvenElsewhere(run, thisInstanceId) {
-    return typeof run.instanceId === "string" && run.instanceId.length > 0 && thisInstanceId !== undefined && run.instanceId !== thisInstanceId;
-}
 export const RUN_NOT_FOUND_MESSAGE = "run not found — the id belongs to no run in this deployment's run store (a run from another server process, or an in-memory store that did not survive a restart, is not visible here)";
 export function runNotFoundMessage(id) {
     const aStar = /^(?:a|wa)[0-9a-f]{4,}$/i.test(id);

package/dist/http/routes/a2a-serve.js

@@ -1,6 +1,6 @@
 import { persistedPlaneOf } from "../../terminal.js";
 import { createHash } from "node:crypto";
-import { memoRedactedRead, redactErrorMessage } from "../../observability/run-terminal-log.js";
+import { memoRedactedRead, redactErrorMessage } from "../../observability/run-terminal.js";
 import { A2A_TASK_STATES } from "@sema-agent/core";
 import { isParkedRunStatus, isTerminalRunStatus } from "../../plugins/store-contracts.js";
 import { HttpError } from "../../security.js";

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

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { QuestionAnswer } from "@sema-agent/core";
 import type { CheckpointStoreFull } from "../../plugins/store-backend.js";
+import { type ToolApprovalCoordinator } from "../../tool-approval.js";
 import { type GovernancePosture } from "../active-run-conflict.js";
 import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
 import { type KeyClosureIssue } from "../../request-key-closure.js";
@@ -16,6 +17,17 @@ import { type KeyClosureIssue } from "../../request-key-closure.js";
  * 的两种兑现方式:**门只站在人**(或客户端)**现写的那份字节**上。
  */
 export declare function decideBodyKeyIssue(raw: unknown): KeyClosureIssue | null;
+/**
+ * FRESH 决裁面的**顶层**键闭集裁决:受理集之外的键 ⇒ 返回拒体(调用方 400 `request.body_shape`);
+ * 全部受理 ⇒ `null`。判据边界与三个孪生门(`taskBodyKeyIssue` / `taskSettingsKeyIssue` /
+ * {@link decideBodyKeyIssue})逐字同一条:**只判键名**(值形校验归各自既有的门,本门零抢话);体本身
+ * 非对象 ⇒ 本门不判(留给「body must be { decision … }」那道根形门,免得同一个体被两句话抢答)。
+ *
+ * 🔴 **重放不额外过门**,也不需要 —— 逐字同 {@link decideBodyKeyIssue} 的同名段:本腿的反重放是
+ * 一次性 nonce(S-280),它守的是**同一份现写的字节**;而续跑重建读的是盘上的体、走 `resolveSpec` 的
+ * 宽容层 ⇒ 4xx 砖不到任何存量挂起的任务。**门只站在人(或客户端)现写的那份字节上**。
+ */
+export declare function planReviewBodyKeyIssue(raw: unknown): KeyClosureIssue | null;
 /**
  * S-342 —— 「空串的理由 = 没有理由 = 这是一次**裸拒**」。这条语义只适用于**本仓自铸**的那一个域。
  *
@@ -38,35 +50,46 @@ export declare function decideBodyKeyIssue(raw: unknown): KeyClosureIssue | null
 export declare function decisionReasonOf(body: {
     reason?: unknown;
 }): string | undefined;
-/** Structural check for an operator-supplied QuestionAnswer (durable ask resume, TC-5.4). Strict on the
- *  load-bearing shape — `answers[]` non-empty, each `{header: string, selected: string[], note?: string}` —
- *  so a typo'd payload fails the request instead of resuming the task with an answer the tool can't use. */
-export declare function isQuestionAnswer(v: unknown): v is QuestionAnswer;
+/** {@link checkQuestionAnswer} 的判词。两种拒各配**一个既有的**错误码,不铸第三种。 */
+export type QuestionAnswerCheck = {
+    readonly ok: true;
+    readonly value: QuestionAnswer;
+}
+/** 形不对(不是对象 / `answers` 空 / 某一位的值形不对)⇒ 400 `request.body_shape`,文案逐字不变。 */
+ | {
+    readonly ok: false;
+    readonly kind: "shape";
+}
+/** 词表外的键 ⇒ 400 `request.field_invalid`,**点名键路径**(`answer.answers[0].selection`)。 */
+ | {
+    readonly ok: false;
+    readonly kind: "unknown_key";
+    readonly keyPaths: readonly string[];
+};
+/**
+ * Structural check for an operator-supplied QuestionAnswer (durable ask resume, TC-5.4). Strict on the
+ * load-bearing shape — `answers[]` non-empty, each `{header: string, selected: string[], note?: string}` —
+ * so a typo'd payload fails the request instead of resuming the task with an answer the tool can't use.
+ * S-452 起**同时闭键**:词表外的键(拼错 / 未来键 / `__proto__`)拒不丢。
+ */
+export declare function checkQuestionAnswer(v: unknown): QuestionAnswerCheck;
 /** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
  *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 export declare function handleApprovalsAssistant(req: IncomingMessage, res: ServerResponse, match: RouteMatch<ApprovalsAssistantRouteId>, ctx: RouteCtx): Promise<void>;
+export declare function streamApprovals(req: IncomingMessage, res: ServerResponse, cs: Pick<CheckpointStoreFull, "listPending">, 
 /**
- * GET /v1/approvals/stream ([ref] native push): SSE — pushes pending-approval deltas so the portal
- * SUBSCRIBES ONCE instead of polling GET /v1/approvals every ~10s (better UX: near-real-time + no client poll
- * loop). Polls listPending(scope) and diffs against the prior snapshot: `pending` for a new suspend, `resolved`
- * for a decided/expired/gone one. Cross-replica BY CONSTRUCTION — the poll reads the SHARED checkpoint table,
- * so a suspend on ANY replica is seen by an operator streaming on a DIFFERENT replica. A transient DB blip
- * heartbeats + retries (never kills the stream); a 15-min cap + req-close end it (parity with streamTaskTrace).
- * Poll-granularity caveat (**narrowed** by [ref]②): the delta now re-emits a `pending` frame whenever a key's
- * WIRE PROJECTION changes (upsert), not only when the key enters — so a same-key re-suspend within one interval
- * IS visible as long as anything on the row differs. What still shows no delta is the strictly degenerate case:
- * a resolve + re-suspend on the same (session,toolCallId) whose projection is BYTE-IDENTICAL — indistinguishable
- * by construction, and harmless (the card the operator sees is the card that is pending). Pins: the two halves of
- * `test/wire-pairing-approvals-stream.test.ts` S3b (changed ⇒ re-emit with the NEW payload; unchanged ⇒ silence).
+ * 🔴 S-454:**第二条 diff 源** —— `GET /v1/approvals` 的 `livePending` 那**同一只**读函数
+ * (`Pick` 而不是另立接口:同源是结构事实,不是两处各写一份的约定)。
+ *
+ * 为什么必须同源:消费方(client-core `hitl/approvalsFeed`)对 stream 上任一非 heartbeat 事件的
+ * 反应是**重取权威 `list()`** —— 推与拉读两份数据时,一条只在推面存在的行会让 feed 空转,
+ * 一条只在拉面存在的行则永远等不到催人事件。
  *
- * [ref](2026-08-09 亲验定性=设计接受,非欠账):每连接自跑 pollMs 轮询打共享 checkpoint 表,
- * 之所以不建 fan-out/单轮询器基建——①消费方=portal 运营面,并发连接数量级为个位(不是用户面);
- * ②listPending 走 (scope,status) 索引,单查成本与一次 /v1/approvals 轮询同阶,而本路正是替代客户端
- * ~10s 轮询的(净负载持平或更低);③DB blip 已 fail-soft(心跳+下拍重试),15-min cap 兜顶。连接
- * 数假设若被打破(portal 多开成常态),届时把 poll 收敛为进程内单轮询器多路复用——那是量级触发的
- * 演化,不是现在的缺陷。
+ * `undefined` = 本部署无 live 审批面(`TOOL_APPROVAL_ENABLED=false` ⇒ 协调器未装配)⇒ 本源整个
+ * 缺席,流的字节与 S-454 之前逐字相同(能力缺席 = 零变化,不是空数组)。**位置在 `pollMs` 之前**
+ * 与 `governance` 同一条理由:`pollMs` 只有测试传,而本参数是每个生产调用点都必须表态的那一个。
  */
-export declare function streamApprovals(req: IncomingMessage, res: ServerResponse, cs: Pick<CheckpointStoreFull, "listPending">, scope: string | undefined, 
+live: Pick<ToolApprovalCoordinator, "listLivePending"> | undefined, scope: string | undefined, 
 /** [ref]②:出身归因的部署侧一半(缺席 ⇒ 归不出治理出身 ⇒ 键缺席,与 best-effort 同方向)。**位置在
  *  `pollMs` 之前**是刻意的:`pollMs` 只有测试传,而本参数是每个生产调用点都必须给的那一个。 */
 governance?: GovernancePosture, pollMs?: number): Promise<void>;