@sema-agent/server 7.131.0 → 7.133.0

package/dist/orchestration/workflow-agent-session-index.d.ts

@@ -15,11 +15,12 @@ export interface WorkflowAgentSessionRow {
 /**
  * 索引面的两个动词。**写者只有一个**(见文件头),读者是判别式。
  *
- * `syncRun` 语义 = 「这条 run 当前的指针集**就是** rows」:多出来的旧行删,rows 里的行 upsert。幂等、可重放、与 run 的一次成功写同拍。
- * `listByAgentSession` = 点名这个子会话的**全部**指针(各 run 一行;顺序不承重)。
+ * `ensurePointers` 语义 = 「rows 里的每一枚指针此后都在」:upsert,**从不删**(唯一的删除是 run 收割的级联)。幂等、可重放;写者在记录落盘
+ * **之前**调它(文件头「指针先于记录」)。
+ * `listByAgentSession` = 点名这个子会话的**全部**指针(各 run 一行;顺序不承重)—— 点名者的超集。
  */
 export interface WorkflowAgentSessionIndex {
-    syncRun(runId: string, rows: readonly WorkflowAgentSessionRow[]): Promise<void>;
+    ensurePointers(runId: string, rows: readonly WorkflowAgentSessionRow[]): Promise<void>;
     listByAgentSession(sessionId: string): Promise<WorkflowAgentSessionRow[]>;
 }
 /**
@@ -50,8 +51,8 @@ export declare function readRunParks(run: unknown): WorkflowRunParkKey[] | undef
 export declare function heldParksOf(recordId: string, parks: readonly WorkflowRunParkKey[]): WorkflowRunParkKey[];
 /**
  * 派生的**唯一属主**:一只 `WorkflowRun` 的指针行 = 它 `parks[]` 里点名的每一个子会话(一个子会话一行)。`parks` 缺席 ⇒ 零条
- * ({@link readRunParks}:没有条目)⇒ 写者按「这条 run 的指针集就是这一份」清掉它已有的指针。
- * `parks[]` 读不出 ⇒ `undefined`(**派生不出来**,不是「零条」):写者据此不动这条 run 已有的指针(文件头「单写者」段)。
+ * ({@link readRunParks}:没有条目)⇒ 没有要写的指针。
+ * `parks[]` 读不出 ⇒ `undefined`(**派生不出来**,不是「零条」):写者据此不写指针(文件头「指针先于记录」段)。
  */
 export declare function buildParkSessionRows(runId: string, run: {
     scope: string;
@@ -99,9 +100,7 @@ export type WorkflowParkRoute = {
  * 🔴 **窗与删码**:规则 ③ 的 `older_engine` 读臂是一次性迁移 M9 的读侧半场(升级那一刻还停驻着的存量记录)。窗口与删码清单见 `plugins/one-time-migrations.ts` 登记表 M9 一行,随 M9 一起删;这里不写第二份窗。
  */
 export declare function routeWorkflowPark(sessionId: string, candidates: readonly WorkflowRun[]): WorkflowParkRoute;
-/** 两处(装饰器的变更检测、local 后端的重放)共用的行集等值判据 —— 顺序无关的集合比较,单一属主。 */
-export declare function sameAgentSessionRows(a: readonly WorkflowAgentSessionRow[], b: readonly WorkflowAgentSessionRow[]): boolean;
-/** 账本一行的**内域形**:一次 `syncRun` 的整份行集快照(`{runId, rows}`)。 */
+/** 账本一行的**内域形**:一条 run 当时的整份指针快照(`{runId, rows}`;同一条 run 后写的一行整份覆盖先写的 —— 本仓只增不删,所以后一行恒是前一行的超集)。 */
 export interface WorkflowAgentSessionLedgerLine {
     runId: string;
     rows: WorkflowAgentSessionRow[];
@@ -112,7 +111,7 @@ export interface WorkflowAgentSessionLedgerLine {
  * 姿态与 SQL 孪生逐字同源:那边 `listByAgentSession` 逐字段收窄(`String(r.session_id)` …),这边逐字段
  * 判形 —— 一张索引面、两个后端、**一种**入域姿态。
  *
- * **整行成败制**(与既有的撕裂行臂同一条规则):一行 = 一次 syncRun 的**整份**快照,任一位读不出来就说明
+ * **整行成败制**(与既有的撕裂行臂同一条规则):一行 = 一条 run 的**整份**快照,任一位读不出来就说明
  * 这份快照重建不出来 ⇒ 整行不 apply(那条 run 保留上一份已知良好的快照)。不做「丢掉坏成员、留下好成员」
  * ——那会静默铸出一份**比真相少几条 park** 的行集,而这条索引的消费面正是 park 的赎回路由。
  * 读不出来 ⇒ 调用方**响亮**记一笔([ref]:安全轴不许静默),不吞整档。
@@ -125,7 +124,7 @@ export declare function readAgentSessionLedgerLine(v: unknown): WorkflowAgentSes
  * 逐字同形:0o700 目录 + 0o600 账本、按行重放),重启后 park 仍可 join;缺席 ⇒ 纯内存
  * (`WORKFLOW_RUN_STORE=memory` 的显式易失车道,与它的 run 店同寿命)。
  *
- * 账本的一行 = **一次 `syncRun` 的整份行集**(按 runId 后写覆盖),所以重放即收敛,不需要压缩腿。
+ * 账本的一行 = **一条 run 当时的整份指针集**(按 runId 后写覆盖;指针只增不删 ⇒ 后一行恒是前一行的超集),所以重放即收敛,不需要压缩腿。
  *
  * 追加 / 重放走本仓 JSONL 店的**共用口**(S-977;此前 ctor 里自写 `truncateTornTail` + 手写 `split("\n") + JSON.parse` 重放):
  * 追加 = core `AppendLog`(惰性打开、撕尾在**打开与每次追加前**修 —— 修前只在 boot 修,运行期半写后的下一次成功写仍会被粘进残尾),
@@ -141,9 +140,10 @@ export declare class LocalWorkflowAgentSessionIndex implements WorkflowAgentSess
     private readonly bySession;
     private log;
     constructor(root?: string, fsyncEnabled?: boolean);
-    /** 内存两张表的收敛(重放与写路径共用一份逻辑):先摘这条 run 的旧指针,再挂新的。 */
+    /** 内存两张表的收敛(重放与写路径共用一份逻辑):这条 run 的指针集 = 这一行的整份快照。 */
     private apply;
-    syncRun(runId: string, rows: readonly WorkflowAgentSessionRow[]): Promise<void>;
+    /** 只增不删:这条 run 已有的指针 ∪ 这几枚,写成一行整份快照(盘上一行仍是「这条 run 的指针集」,与早年的账本行同一种读法)。 */
+    ensurePointers(runId: string, rows: readonly WorkflowAgentSessionRow[]): Promise<void>;
     listByAgentSession(sessionId: string): Promise<WorkflowAgentSessionRow[]>;
 }
 //# sourceMappingURL=workflow-agent-session-index.d.ts.map

package/dist/orchestration/workflow-agent-session-index.js

@@ -88,16 +88,6 @@ function highestHolders(sessionId, readable) {
     }
     return top;
 }
-export function sameAgentSessionRows(a, b) {
-    if (a.length !== b.length)
-        return false;
-    const key = (r) => `${r.sessionId}\u0000${r.runId}\u0000${r.agentKey}\u0000${r.scope}`;
-    const left = new Set(a.map(key));
-    for (const r of b)
-        if (!left.has(key(r)))
-            return false;
-    return true;
-}
 export function readAgentSessionLedgerLine(v) {
     if (typeof v !== "object" || v === null)
         return undefined;
@@ -173,12 +163,18 @@ export class LocalWorkflowAgentSessionIndex {
             runs.set(runId, r);
         }
     }
-    async syncRun(runId, rows) {
+    async ensurePointers(runId, rows) {
+        const held = this.byRun.get(runId) ?? [];
+        const named = new Set(held.map((r) => r.sessionId));
+        const added = rows.filter((r) => !named.has(r.sessionId));
+        if (added.length === 0)
+            return;
+        const merged = [...held, ...added];
         if (this.ledgerPath !== undefined) {
             this.log ??= new AppendLog(this.ledgerPath);
-            this.log.append({ runId, rows }, this.fsyncEnabled);
+            this.log.append({ runId, rows: merged }, this.fsyncEnabled);
         }
-        this.apply(runId, rows);
+        this.apply(runId, merged);
     }
     async listByAgentSession(sessionId) {
         return [...(this.bySession.get(sessionId)?.values() ?? [])];

package/dist/orchestration/workflow-completion-inbox.d.ts

@@ -228,26 +228,26 @@ diag?: {
     connection: string;
     log(msg: string, meta?: Record<string, unknown>): void;
 }): Promise<void>;
-/**
- * The durable half is the deployment's job: map a core `TaskNotificationPayload`
- * (background subagent / background bash completion) onto an inbox entry, for the IDLE gap — core's in-process
- * injection covers a LIVE harness; a completion that lands after the leg ended had NO durable path (idle no-show,
- * lost across restart). Bounded + redacted HERE (the store carries only egress-safe bytes; summary/result are
- * UNTRUSTED free text). `status` collapses onto the inbox's completed|failed column; the ORIGINAL status rides
- * the payload extras and overrides on drain (killed/cancelled reach the shell verbatim). Workflow-type
- * notifications are the CALLER's job to filter (they have their own durable chain — double-enqueueing here would
- * re-open the poll-served double-push).
- */
-export declare function taskNotificationInboxEntry(sessionId: string, owner: string | null, n: {
+/** 停驻收件条目的**共享字段** —— 引擎递来的完成与本服务铸的 external 通知都有的那几位。三只入参型都写成类型字面量(不是 interface):
+ *  调用方手里的是一只记录形的 payload,字面量型才与它可比(interface 没有隐式索引签名)。 */
+type ParkedNotificationFields = {
     task_id: string;
-    task_type: string;
-    toolUseId?: string;
     status: string;
     summary: string;
     result?: string;
+    seq?: number;
+    /** 通知的来源标签(external 通知的入站体键,core 载荷同名键;live 投影过 `redactSecrets`,这里同读法)。 */
+    source?: string;
+};
+/**
+ * **引擎递来的一次完成**(`onTaskNotification` 的 payload,执行腿父腿已收尾时入箱)—— 停驻收件的入参型。四处调用(bg 腿 `runs.ts`、sync 腿
+ * `routes/tasks.ts`、两条续跑腿 `resume-legs.ts`)原样交 core 的那只 payload。
+ */
+export type EngineNotificationParkInput = ParkedNotificationFields & {
+    task_type: string;
+    toolUseId?: string;
     output_file?: string;
     sessionId?: string;
-    seq?: number;
     lines?: string[];
     stoppedBy?: string;
     recentSteps?: Array<{
@@ -281,7 +281,33 @@ export declare function taskNotificationInboxEntry(sessionId: string, owner: str
     };
     resupplied?: boolean;
     attempt?: number;
-}, enqueuedAt: number, 
+    /**
+     * 引擎的**一次完成**的相关 id(fill-once,`SemaTaskHandle.completionId`)—— live 投影(`trace/project.ts`)逐字透传的同一个值,
+     * 停驻收件条目照带 ⇒ 同一次完成在 live 帧与下一次开流的补投帧上同一个 id。引擎铸的不透明标识:逐字、不脱敏、不进折叠键;本仓零自铸。
+     */
+    completionId?: string;
+};
+/**
+ * **本服务自己铸的 external 通知**(`POST /v1/sessions/:id/notify` 的 idle 半场)—— 停驻收件的入参型。类型上**不许**带 `completionId`:
+ * 那一位是引擎的一次完成的相关 id,本服务铸的通知没有它(编一个 = 凭空造一次「完成」)。
+ */
+export type ExternalNotificationParkInput = ParkedNotificationFields & {
+    task_type: "external";
+    completionId?: never;
+};
+/** external 通知 → 停驻收件条目(逐键取共享字段:运行期硬塞进来的别的键 —— 包括 `completionId` —— 一个都不过)。 */
+export declare function externalNotificationInboxEntry(sessionId: string, owner: string | null, n: ExternalNotificationParkInput, enqueuedAt: number): WorkflowCompletionInboxEntry;
+/**
+ * The durable half is the deployment's job: map a core `TaskNotificationPayload`
+ * (background subagent / background bash completion) onto an inbox entry, for the IDLE gap — core's in-process
+ * injection covers a LIVE harness; a completion that lands after the leg ended had NO durable path (idle no-show,
+ * lost across restart). Bounded + redacted HERE (the store carries only egress-safe bytes; summary/result are
+ * UNTRUSTED free text). `status` collapses onto the inbox's completed|failed column; the ORIGINAL status rides
+ * the payload extras and overrides on drain (killed/cancelled reach the shell verbatim). Workflow-type
+ * notifications are the CALLER's job to filter (they have their own durable chain — double-enqueueing here would
+ * re-open the poll-served double-push). External notifications enter through {@link externalNotificationInboxEntry}.
+ */
+export declare function taskNotificationInboxEntry(sessionId: string, owner: string | null, n: EngineNotificationParkInput, enqueuedAt: number, 
 /** lead-b (dual-ID audit): the PARENT run's durable taskId (the uuid the shell's footer rows
  *  key on) — rides the drained frame so a consumer can bind the a*-keyed child notification to its uuid-keyed
  *  parent row without a side lookup. */
@@ -341,4 +367,5 @@ export declare function resolveServedSession(p: {
 }, getRun?: (taskId: string) => Promise<{
     sessionId?: string | null;
 } | undefined | null>): Promise<string | undefined>;
+export {};
 //# sourceMappingURL=workflow-completion-inbox.d.ts.map

package/dist/orchestration/workflow-completion-inbox.js

@@ -315,6 +315,17 @@ export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPri
         }
     }
 }
+export function externalNotificationInboxEntry(sessionId, owner, n, enqueuedAt) {
+    return taskNotificationInboxEntry(sessionId, owner, {
+        task_id: n.task_id,
+        task_type: "external",
+        status: n.status,
+        summary: n.summary,
+        ...(n.result !== undefined ? { result: n.result } : {}),
+        ...(n.seq !== undefined ? { seq: n.seq } : {}),
+        ...(n.source !== undefined ? { source: n.source } : {}),
+    }, enqueuedAt);
+}
 export function taskNotificationInboxEntry(sessionId, owner, n, enqueuedAt, parentTaskId, priority) {
     const cap = (s, max) => (s.length > max ? `${s.slice(0, max)}…[+${s.length - max} chars]` : s);
     const extras = {
@@ -328,6 +339,8 @@ export function taskNotificationInboxEntry(sessionId, owner, n, enqueuedAt, pare
         ...(n.toolUseId ? { toolUseId: n.toolUseId } : {}),
         ...(n.status !== "completed" && n.status !== "failed" ? { status: n.status } : {}),
         ...(n.seq !== undefined ? { seq: n.seq } : {}),
+        ...(n.completionId !== undefined ? { completionId: n.completionId } : {}),
+        ...(n.source !== undefined ? { source: redactSecrets(n.source) } : {}),
         ...(n.lines !== undefined ? { lines: n.lines.map((l) => cap(redactSecrets(l), 1024)) } : {}),
         ...(n.stoppedBy !== undefined ? { stoppedBy: n.stoppedBy } : {}),
         ...(n.diagnostics !== undefined ? { diagnostics: cap(n.diagnostics, 4_000) } : {}),

package/dist/orchestration/workflow-notify-journal.d.ts

@@ -291,39 +291,20 @@ export declare class JournalingWorkflowRunStore implements WorkflowRunStore {
      *  的派生投影,写点必须与 fleet 行投影/notify journal 同一个(见 index 模块的文件头「单写者」段)。
      *  可选:缺席 ⇒ 一位不维护(与 fleet 半场同姿势,行为逐字不变)。 */
     agentSessionIndex?: WorkflowAgentSessionIndex | undefined);
-    /** 上一次**本进程**为某条 run 写进索引的行集 —— 变更检测,不是缓存。
+    /** 本进程**亲眼看着落进索引**的指针:run → 它点名过的子会话。只用来跳过重复的 upsert,不是缓存(指针只增不删,记着的必在索引里)。
      *
-     *  为什么需要:workflow 的进度写是每只 agent 状态变化一次,而 park 是罕见事件 ⇒ 无条件同步会给
-     *  「一条 park 都没有」的绝大多数 run 每次写多打一发删除(SQL)或多追加一行账本(file,无界增长)。
-     *  判据是**行集是否变化**,与后端无关 ⇒ 规则只有一条、两个后端同享。
-     *  跨副本安全性:一条 run 的写者按 core 契约唯一(`store` 的 owner),而同步只发生在一次**成功 CAS 之后**;
-     *  失败切换后新 owner 的表是空的 ⇒ 它的第一次写必落盘,收敛。
-     *
-     *  🔴 **空集也记**(7.69.0 合并重扫 c0):此前成功臂写作「空集 delete、非空集 set」,于是「一条 park
-     *  都没有」的那条 run —— 也就是上面这段头注**点名要短路的绝大多数形** —— memo 恒回 `undefined`、短路
-     *  判据恒假,每一次 put/update 都重跑一遍 `syncRun(id, [])`(file 车道每次多一行账本 + 一次 fsync,而
-     *  这本账本按设计没有压缩腿;SQL 车道每次多一发 `DELETE`)。代码与自己成文的判据相反。
-     *  当时那条 delete 臂承担的是**有界性**:memo 若无条件记,表会随本进程见过的每一条 run 单调增长。
-     *  现在有界性由下面那条**终态驱逐**独立承担(run 终态 ⇒ 它不会再被写 ⇒ 摘表),两件事各归各位:
-     *  记不记 = 变更检测的正确性;摘不摘 = 表的有界性。**不**加「首次空集跳过」这类依赖进程内历史的特判。 */
-    private readonly indexedRows;
-    /**
-     * 写腿的**不变式守卫**(codex r1 [medium],验真后修):`indexedRows` 只保留一次**我们亲眼看着落地**
-     * 的写。持久化抛错时这条 run 的盘上状态未知(而 core 会吞掉这次失败、这条 run 往往再也不被写),
-     * 若把 memo 留着,那一条 `{runId → rows}` 就永久留在表里 —— 终态驱逐等不到它的终态写。
-     *
-     * ⚠️ 如实登记的残余:一条**最后一次写成功、随后被放弃**的 run(进程崩前没跑到终态)仍会在本进程的
-     * memo 里留一条空集。它与 fleet 活行登记簿同一量级(都随本世进程消亡),刻意**不**为它加清扫腿:
-     * 那是给一个不产生错误答案的形加机制。
-     */
-    private forgetIndexMemoIfWriteOutcomeUnknown;
-    /** 索引的一次收敛(put/update 成功后调用)。
-     *
-     *  **自吞错**:索引是观察面的派生物,它的故障绝不能把一次已成功的 run 持久化变成失败 —— 与
-     *  `publishFleet` 的姿态同源。但自吞 ≠ 静默([ref]):留痕走**登记过的** fail-open tag
-     *  `server.workflow-park-index.sync-failed`(P-DEBT;射程、后果与欠账的唯一属主 = 那条词表项的
-     *  `note`,census 里有对应行);记录的 `parks[]` 读不出而不同步的那一臂另走 `server.workflow-park-index.parks-unreadable`(F 类,见下)。 */
-    private syncAgentSessionIndex;
+     *  为什么需要:workflow 的进度写是每只 agent 状态变化一次,而 park 是罕见事件 ⇒ 无条件 upsert 会给每一次写多打几发语句(SQL)
+     *  或多追加一行账本(file,无界增长)。判据只有一条:**这次记录点名的子会话,有没有还没亲眼看着落盘的** —— 没有就不写。
+     *  有界性:这条 run 不会再被本进程写的那一刻就摘表 —— 写到终态、CAS 输掉(owner 已不是本副本)、或这次写抛了(盘上状态未知)。 */
+    private readonly pointedSessions;
+    /** **指针先于记录**(索引模块头注的那条律):这次记录点名的子会话,指针在记录落盘之前 upsert。写不进 ⇒ 抛 —— 调用方的记录写
+     *  因此不发生,错误交给引擎 persist 的失败臂(与库写失败同一条路),不吞、不计 fail-open。
+     *  记录的 `parks[]` 读不出(在场却不是列表 / 条目形坏)⇒ 派生不出 ⇒ 不写指针,记录照写(读口据记录响亮拒);留痕走
+     *  `server.workflow-park-index.parks-unreadable`(F 类)。`parks` 缺席不在这一臂:那是没有条目(读者答 `[]`),没有要写的指针。 */
+    private ensurePointersFor;
+    /** 一次记录写的整形:先指针、再记录;记录没落(`landed` 答否 / 写抛)或写到终态 ⇒ 摘表(见 {@link pointedSessions} 的有界性)。
+     *  终态判据走 fleet 半场那张**同一张**终态闭集表,不在这里手写第二份「哪些词算终态」。 */
+    private writeWithPointers;
     /** Derive + publish the MF-Fleet workflow row from a WorkflowRun (doneCount/totalCount from agents, tokens from
      *  stats); a terminal workflow LEAVES the fleet (publish terminal then remove), a running one stays/updates. */
     private publishFleet;

package/dist/orchestration/workflow-notify-journal.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { AppendLog, ensureDir } from "@sema-agent/core";
 import { buildFleetWorkflowRow } from "../fleet/fleet-bus.js";
 import { isTerminalWorkflowRowStatus, seedTerminalWorkflowRow } from "../fleet/fleet-terminal-window.js";
-import { buildParkSessionRows, sameAgentSessionRows } from "./workflow-agent-session-index.js";
+import { buildParkSessionRows } from "./workflow-agent-session-index.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 const SUMMARY_MAX = 500;
@@ -264,41 +264,39 @@ export class JournalingWorkflowRunStore {
         this.fleetBus = fleetBus;
         this.agentSessionIndex = agentSessionIndex;
     }
-    indexedRows = new Map();
-    async forgetIndexMemoIfWriteOutcomeUnknown(id, write) {
-        try {
-            return await write();
-        }
-        catch (e) {
-            this.indexedRows.delete(id);
-            throw e;
-        }
-    }
-    async syncAgentSessionIndex(id, run) {
+    pointedSessions = new Map();
+    async ensurePointersFor(id, run) {
         const index = this.agentSessionIndex;
         if (index === undefined)
             return;
         const rows = buildParkSessionRows(id, run);
         if (rows === undefined) {
-            this.indexedRows.delete(id);
             recordFailOpen("server.workflow-park-index.parks-unreadable", `runId=${id}`);
             return;
         }
-        const prior = this.indexedRows.get(id);
-        if (prior === undefined || !sameAgentSessionRows(prior, rows)) {
-            try {
-                await index.syncRun(id, rows);
-            }
-            catch (err) {
-                this.indexedRows.delete(id);
-                recordFailOpen("server.workflow-park-index.sync-failed", `runId=${id} rows=${rows.length} err=${err instanceof Error ? err.message : String(err)}`);
-                return;
-            }
+        const known = this.pointedSessions.get(id);
+        const fresh = rows.filter((r) => known?.has(r.sessionId) !== true);
+        if (fresh.length === 0)
+            return;
+        await index.ensurePointers(id, fresh);
+        const landed = known ?? new Set();
+        for (const r of fresh)
+            landed.add(r.sessionId);
+        this.pointedSessions.set(id, landed);
+    }
+    async writeWithPointers(id, run, write, landed) {
+        await this.ensurePointersFor(id, run);
+        let result;
+        try {
+            result = await write();
         }
-        if (isTerminalWorkflowRowStatus(run.status))
-            this.indexedRows.delete(id);
-        else
-            this.indexedRows.set(id, rows);
+        catch (e) {
+            this.pointedSessions.delete(id);
+            throw e;
+        }
+        if (!landed(result) || isTerminalWorkflowRowStatus(run.status))
+            this.pointedSessions.delete(id);
+        return result;
     }
     publishFleet(id, run) {
         if (!this.fleetBus)
@@ -322,16 +320,11 @@ export class JournalingWorkflowRunStore {
             runId: id,
             scope: run.scope,
         });
-        await this.forgetIndexMemoIfWriteOutcomeUnknown(id, () => this.inner.put(id, run));
-        await this.syncAgentSessionIndex(id, run);
+        await this.writeWithPointers(id, run, () => this.inner.put(id, run), () => true);
         this.publishFleet(id, run);
     }
     async update(id, scope, run, expect) {
-        const ok = await this.forgetIndexMemoIfWriteOutcomeUnknown(id, () => this.inner.update(id, scope, run, expect));
-        if (!ok)
-            this.indexedRows.delete(id);
-        if (ok)
-            await this.syncAgentSessionIndex(id, run);
+        const ok = await this.writeWithPointers(id, run, () => this.inner.update(id, scope, run, expect), (won) => won);
         if (ok)
             this.publishFleet(id, run);
         return ok;

package/dist/orchestration/workflow-park-decision.d.ts

@@ -0,0 +1,89 @@
+import { type CheckpointToken, type ResumeOutcome } from "@sema-agent/core";
+import { type JsonColumnReader } from "../plugins/sql-json-column.js";
+import { type InProcessClaimFence } from "../plugins/store-contracts.js";
+/** 一条人对审批卡的决定(引擎 `ResumeOutcome` 的 `policy_ask` 臂 —— 子代停驻只会是这一门)。 */
+export type WorkflowParkOutcome = Extract<ResumeOutcome, {
+    gate: "policy_ask";
+}>;
+/** 决定行(内域形)。 */
+export interface WorkflowParkDecision {
+    /** 子代 checkpoint 的 token —— 键。 */
+    readonly token: CheckpointToken;
+    /** 留存锚:受理那一刻的持有者 run(收割它时同批删本行)。**不是**投递目标 —— 投递目标在读时由路由判官定。 */
+    readonly runId: string;
+    /** 带着它的会话 = 受理那一刻那条 run 的发起会话(宿主)。 */
+    readonly hostSessionId: string;
+    readonly outcome: WorkflowParkOutcome;
+    /** {@link parkDecisionFingerprint}:同一决定的判据(回执幂等用)。 */
+    readonly fingerprint: string;
+    /** 受理它的那一次投递跑(回执上的 `taskId`)。 */
+    readonly deliveredTaskId: string;
+    /** 受理时刻(受理那台副本的墙钟,记录值;不当任何条件 —— 序由认领栅栏的提交序定,见文件头律二)。 */
+    readonly acceptedAtMs: number;
+}
+/**
+ * 决定行的店契约(SQL 两方言 / local 文件 / 内存三形同律)。写者只有 `/decide` 的 workflow 车道(开跑之前那一笔);读者是起跑读者与
+ * `/decide` 自己的回执幂等判;删除只有 SQL 收割的级联。
+ */
+export interface WorkflowParkDecisionStore {
+    /** 这只店每一笔写所在的认领栅栏 = 构造时绑定的那只 run 店。起服判官要它**就是**部署的 run 店({@link parkDecisionStoreRefusal})。 */
+    readonly claims: object;
+    /**
+     * 认领栅栏的原子段里整行写(律二,文件头):投递那一跑此刻持有宿主会话的认领且在跑 ⇒ 写(没有行插入、有行整行取代)并答 `true`;
+     * 否则什么都不写、答 `false`。
+     */
+    record(decision: WorkflowParkDecision): Promise<boolean>;
+    get(token: CheckpointToken): Promise<WorkflowParkDecision | null>;
+    /** 带着这个会话的全部决定行(顺序不承重)。 */
+    listByHostSession(hostSessionId: string): Promise<WorkflowParkDecision[]>;
+}
+/** 起服判官读的那几座(`ServiceDeps` 的子集)。 */
+export interface ParkDecisionLaneSeats {
+    readonly runStore?: object | undefined;
+    readonly workflowAgentSessionIndex?: unknown;
+    readonly workflowParkDecisions?: WorkflowParkDecisionStore | undefined;
+}
+/**
+ * 🔴 **「决定店绑对了 run 店吗」的唯一判官**(`createHttpServer` 起服时调;拒 ⇒ 拒启)。判的是**递进来的对象**(按身份比),不是配置组合 ——
+ * 本服务自己那一形(SQL 后端配 `WORKFLOW_RUN_STORE=file|memory` 且开自编排)由配置不变量 `workflow-park-decision-domain` 在第 1 段、一次性迁移之前拒,走不到这里;
+ * 走到这里的不相等只来自嵌入方递错了座。
+ * 期望的绑定:workflow 子代停驻车道装了(park 索引在场)且部署有 run 店 ⇒ 决定店在场、绑的**就是**那只 run 店;否则不该有决定店。不相等的三形各一句:
+ * ①车道与 run 店都在而决定店缺席;②决定店绑的是别的 run 店(两只店各取各的:决定写进一只库、认领与读在另一只);③有决定店,而车道没装或部署没有 run 店。
+ */
+export declare function parkDecisionStoreRefusal(seats: ParkDecisionLaneSeats): string | undefined;
+/**
+ * 决定的同一性判据:判词 + 绑定两位 + 出处词(`decidedBy`)+ 载荷指纹(`updatedInput` / `answer` / `reason`,与 live 腿幂等回放的门⑦
+ * 同一只 {@link approvalPayloadFingerprint})。通道自报的 `approver` 不进 —— 它是归属标签,不改引擎铸的结算词。
+ * 载荷序列化不了 ⇒ 抛(两侧都源自 JSON,走到这里是结构异常;那只函数自己已经响亮 warn)。
+ */
+export declare function parkDecisionFingerprint(outcome: WorkflowParkOutcome): string;
+/**
+ * 存下的决定体 → 内域形的**唯一读者**(SQL 列与 local 账本行共用)。判到本仓自己读的那几格为止(门、判词、绑定两位、出处对象);
+ * 其余键的属主是引擎,它在续跑入口 pre-CAS 再判一遍(与 checkpoint 店读 `outcome` 列同一条分工,见 `checkpoint-store-sql.ts` 的形读者注)。
+ */
+export declare const readWorkflowParkOutcome: JsonColumnReader<WorkflowParkOutcome>;
+/**
+ * 单机车道的决定店(`LocalWorkflowAgentSessionIndex` 的同室孪生),绑在进程内的 run 店上({@link InProcessClaimFence}:Memory / File run 店)。
+ * `root` 在场 ⇒ 追加式 JSONL 账本(0o700 目录 + 0o600 账本,一行 = 一条决定行的整份快照,每一笔写都追加);重放按行序、**末行胜**
+ * (写序就是认领栅栏的序:每一笔都在栅栏的同步段里追加,同一宿主会话上的受理由认领串行);缺席 ⇒ 纯内存(`WORKFLOW_RUN_STORE=memory` 的易失车道)。
+ *
+ * 🔴 **坏行 fail-closed**(登记座 `workflow-park-decisions`):读不出的一行可能正是**取代**了一条旧决定的那一笔 —— 跳过它重放其余行,
+ * 会把被取代的旧决定复活成当下的决定,在下一次起跑时交给引擎。闸合上之后三个动词都响亮拒,直到有人处理那只文件;
+ * 起跑读者(`parked-decide.ts`)把这一拒读成「本店没有可供的行」(F tag `server.workflow-park-decision.store-unreadable`)—— 起跑不连带拒,写与按 token 读照旧拒。
+ * SQL 孪生同律:某一行 `outcome` 坏体 ⇒ 读口拒,起跑读者同一臂。
+ */
+export declare class LocalWorkflowParkDecisionStore implements WorkflowParkDecisionStore {
+    readonly claims: InProcessClaimFence;
+    private readonly fsyncEnabled;
+    private readonly ledgerPath;
+    private readonly gate;
+    private readonly rows;
+    private log;
+    constructor(claims: InProcessClaimFence, root?: string, fsyncEnabled?: boolean);
+    record(decision: WorkflowParkDecision): Promise<boolean>;
+    /** 整行写(同步):落盘**先于**内存翻转(调用方观察到的状态背后一定有耐久记录)。交回栅栏的落定记号(同步交回,型上不许让出)。 */
+    private landNow;
+    get(token: CheckpointToken): Promise<WorkflowParkDecision | null>;
+    listByHostSession(hostSessionId: string): Promise<WorkflowParkDecision[]>;
+}
+//# sourceMappingURL=workflow-park-decision.d.ts.map

package/dist/orchestration/workflow-park-decision.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { AppendLog, ensureDir } from "@sema-agent/core";
+import { approvalPayloadFingerprint } from "../plugins/approval-payload-fingerprint.js";
+import { createObjectColumnReader, isJsonObject } from "../plugins/sql-json-column.js";
+import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
+import { FENCE_LANDED } from "../plugins/store-contracts.js";
+function seatName(v) {
+    if (v === undefined)
+        return "none";
+    const ctor = Reflect.get(v, "constructor");
+    return typeof ctor === "function" && ctor.name !== "" ? ctor.name : "an object";
+}
+export function parkDecisionStoreRefusal(seats) {
+    const wanted = seats.workflowAgentSessionIndex !== undefined ? seats.runStore : undefined;
+    const decisions = seats.workflowParkDecisions;
+    if (decisions?.claims === wanted)
+        return undefined;
+    const pair = `run store: ${seatName(seats.runStore)}; workflow park decision store: ${decisions === undefined ? "none" : `${seatName(decisions)} bound to ${seatName(decisions.claims)}`}`;
+    if (decisions === undefined) {
+        return (`the workflow park lane is wired (park index and run store) but no workflow park decision store is bound to that run store (${pair}) — ` +
+            "a decision row is written in the same atomic step that checks the delivering run still holds the host session, so it must live where the session claims live; " +
+            "pass the store backend's workflowParkDecisions() next to its run(); refusing to start rather than answer every workflow approval decision with a 500");
+    }
+    if (wanted === undefined) {
+        return (`a workflow park decision store is wired but the workflow park lane is not (${pair}; park index: ${seats.workflowAgentSessionIndex === undefined ? "none" : "present"}) — ` +
+            "a decision store is only read and written by that lane, which needs both the park index and the run store the decisions are fenced by; " +
+            "wire the lane (park index and run store) or drop the decision store; refusing to start rather than keep a store no lane fences");
+    }
+    return (`the workflow park decision store is not bound to this server's run store (${pair}) — ` +
+        "its writes are fenced by the run store it was built on, so a different run store means decisions recorded where the session claims are not checked; " +
+        "take runStore and workflowParkDecisions from the same store backend (run() and workflowParkDecisions()); refusing to start rather than record decisions the session claim cannot fence");
+}
+export function parkDecisionFingerprint(outcome) {
+    const payload = approvalPayloadFingerprint({
+        ...(outcome.updatedInput !== undefined ? { updatedInput: outcome.updatedInput } : {}),
+        ...(outcome.answer !== undefined ? { answer: outcome.answer } : {}),
+        ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}),
+    });
+    if (payload === null)
+        throw new Error("workflow park decision: the decision payload cannot be serialized — refusing to record a decision whose identity cannot be stated");
+    const identity = JSON.stringify([outcome.decision, outcome.boundCallId, outcome.boundInputHash, outcome.hostDecision.decidedBy, payload]);
+    return createHash("sha256").update(identity).digest("hex");
+}
+const readOutcomeObject = createObjectColumnReader();
+export const readWorkflowParkOutcome = (body) => {
+    if (!isJsonObject(body))
+        return { problem: "expected a JSON object" };
+    if (body.gate !== "policy_ask")
+        return { problem: "expected a policy_ask decision" };
+    if (body.decision !== "allow" && body.decision !== "deny")
+        return { problem: "decision is neither allow nor deny" };
+    if (typeof body.boundCallId !== "string" || typeof body.boundInputHash !== "string")
+        return { problem: "the binding pair is not two strings" };
+    if (!isJsonObject(body.hostDecision))
+        return { problem: "hostDecision is not an object" };
+    return readOutcomeObject(body);
+};
+const nonEmpty = (v) => typeof v === "string" && v !== "";
+function readRow(raw) {
+    if (!isJsonObject(raw))
+        return undefined;
+    const { token, runId, hostSessionId, outcome, fingerprint, deliveredTaskId, acceptedAtMs } = raw;
+    if (!nonEmpty(token) || !nonEmpty(runId) || !nonEmpty(hostSessionId) || !nonEmpty(fingerprint) || !nonEmpty(deliveredTaskId))
+        return undefined;
+    if (typeof acceptedAtMs !== "number" || !Number.isSafeInteger(acceptedAtMs))
+        return undefined;
+    const o = readWorkflowParkOutcome(outcome);
+    if (o.problem !== undefined)
+        return undefined;
+    return { token: token, runId, hostSessionId, outcome: o.value, fingerprint, deliveredTaskId, acceptedAtMs };
+}
+const LEDGER_LINE_SHAPE = { what: "a workflow park decision row", read: readRow };
+export class LocalWorkflowParkDecisionStore {
+    claims;
+    fsyncEnabled;
+    ledgerPath;
+    gate;
+    rows = new Map();
+    log;
+    constructor(claims, root, fsyncEnabled = true) {
+        this.claims = claims;
+        this.fsyncEnabled = fsyncEnabled;
+        if (root === undefined) {
+            this.ledgerPath = undefined;
+            this.gate = undefined;
+            return;
+        }
+        const dir = join(root, "workflow-park-decisions");
+        ensureDir(dir);
+        this.ledgerPath = join(dir, "decisions.jsonl");
+        const { records, gate } = replayJsonlGuarded(this.ledgerPath, "workflow-park-decisions", LEDGER_LINE_SHAPE);
+        this.gate = gate;
+        for (const d of records)
+            this.rows.set(d.token, d);
+    }
+    async record(decision) {
+        this.gate?.assertUsable();
+        return this.claims.whileHoldingClaim(decision.hostSessionId, decision.deliveredTaskId, () => this.landNow(decision));
+    }
+    landNow(decision) {
+        if (this.ledgerPath !== undefined) {
+            this.log ??= new AppendLog(this.ledgerPath);
+            this.log.append(decision, this.fsyncEnabled);
+        }
+        this.rows.set(decision.token, decision);
+        return FENCE_LANDED;
+    }
+    async get(token) {
+        this.gate?.assertUsable();
+        return this.rows.get(token) ?? null;
+    }
+    async listByHostSession(hostSessionId) {
+        this.gate?.assertUsable();
+        return [...this.rows.values()].filter((d) => d.hostSessionId === hostSessionId);
+    }
+}
+//# sourceMappingURL=workflow-park-decision.js.map