@sema-agent/server 7.4.0 → 7.6.0

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

@@ -1,5 +1,5 @@
 import type { WorkflowRun, WorkflowRunStore, WorkflowRunStatus, WorkflowRunSummary } from "@sema-agent/core";
-import type { FleetEventBus } from "../fleet/fleet-bus.js";
+import { type FleetEventBus } from "../fleet/fleet-bus.js";
 /** A workflow completion notification's terminal payload — the bounded, redacted shape core's notifier seam
  *  carries, re-derivable from a durable {@link import("@sema-agent/core").WorkflowRun} on the recovery path. */
 export interface WorkflowCompletionPayload {
@@ -87,7 +87,21 @@ export declare class WorkflowNotifyGate {
          *  recovery-sweep error. */
         onError?: (stage: "record" | "deliver" | "recover", runId: string, err: unknown) => void;
     });
+    /**
+     * The runIds whose journal entry THIS process recorded — the boot-orphan judgment's authoritative anchor
+     * (round-1 review, MEDIUM). A wall-clock cutoff alone is not sound: after a BACKWARD clock step the entries
+     * this process records land BELOW the boot cutoff, and the sweep would finalize runs whose in-process
+     * executor is alive and running (a false `failed` notify for a workflow that then keeps going — worse than
+     * the absent row it was fixing). Membership here is a fact about THIS incarnation, unforgeable by any clock.
+     * Retired on ack AND the moment a sweep observes the run terminal (the anchor only ever gates the `running`
+     * arm), so a delivery/ack outage cannot pile up entries for runs that are no longer executing.
+     */
+    private readonly recordedThisIncarnation;
     private now;
+    /** Record a journal entry AND remember that this incarnation is the one that recorded it (see the field). */
+    private recordPending;
+    /** Ack an entry + drop its incarnation mark (acked ⇒ never scanned again, so the mark has no further use). */
+    private ackDelivered;
     /**
      * Journal a STARTED run as pending-notify. Call this with the synchronous `runId` from `startWorkflow` /
      * `run_workflow` — BEFORE the workflow can reach terminal — so a crash mid-run still leaves a recoverable
@@ -129,14 +143,50 @@ export declare class WorkflowNotifyGate {
      *    workflow died) + ack, instead of leaking the entry forever. This closes the exact crash topology SVC-1
      *    exists for (a replica SIGKILLed mid-run).
      *  - `running` and FRESH (within the grace window): genuinely in flight → leave pending (the owning process
-     *    delivers its terminal notify, or the next sweep catches it once it goes terminal or stale).
+     *    delivers its terminal notify, or the next sweep catches it once it goes terminal or stale). The sweep
+     *    publishes NOTHING here — see the single-writer invariant below.
      *  - MISSING (reaped / never persisted): ack-as-abandoned so the journal doesn't chase a ghost forever.
      * `orphanGraceMs` MUST exceed the max expected workflow runtime (the run store has no cross-replica liveness
      * signal, so age is the only orphan proxy). Returns a tally. A per-entry throw is isolated so one bad entry
      * can't abort the sweep.
+     *
+     * BOTH abandoned arms (boot-orphan + stale-past-grace) flip the DURABLE row to `failed` FIRST (CAS on rev),
+     * so the run store, the fleet panel and the delivered notify give ONE answer — previously the notify said
+     * `failed` while `/workflows` kept saying `running` forever ([2999]: republishing without finalizing would
+     * have turned "panel empty" into "panel shows a row that never moves"). A lost CAS means the run moved under
+     * the sweep (e.g. its real terminal landed concurrently) — skip this pass; the entry stays pending and the
+     * next sweep handles the NEW state.
+     *
+     * 🔴 SINGLE-WRITER INVARIANT for the fleet row (round-1 review, two HIGH findings): the sweep only ever
+     * publishes a **TERMINAL** fleet frame (the flip above, via `publishTerminalFleetRow` → final frame + remove).
+     * It NEVER publishes a `running` row. Two reasons, both "a row we mint here can become one nobody can retire":
+     *  1. cross-replica (SQL journal): a pending `running` entry may belong to ANOTHER replica. Its terminal
+     *     update lands on that replica's own (replica-local) fleet bus, and its ack removes the entry from the
+     *     shared journal — so this replica would never see the run again and its minted row would sit `running`
+     *     forever. (The terminal-redelivery arm deliberately doesn't publish either — it is a notify path.)
+     *  2. same-replica: `runStore.get` is a READ-TIME SNAPSHOT. If the live run commits its terminal (and the
+     *     wrapper removes the row) between that read and the publish, a `running` republish resurrects a row
+     *     that will never be removed again.
+     * A live row's ONE writer is this replica's `put`/`update` observation point ({@link JournalingWorkflowRunStore}),
+     * which by construction sees every transition including the terminal one.
      */
     recover(opts?: {
         orphanGraceMs?: number;
+        /** Replica-local (File/in-memory) journal ONLY: a pending entry recorded BEFORE this timestamp belongs to
+         *  a previous incarnation of THIS process — workflow executors are in-process, so they died with it and a
+         *  still-`running` run is a boot-orphan: finalize it NOW instead of leaving the user's "Waiting for
+         *  workflow" pointed at a run that can never finish for the whole grace window ([2995] 顺带①/[3000]§二).
+         *  NEVER pass this for a cross-replica (SQL) journal — there a pending running run may be genuinely alive
+         *  on another replica, and age (`orphanGraceMs`) is the only sound orphan proxy.
+         *  ⚠️ This wall-clock cutoff is a NECESSARY, not sufficient, condition — {@link recordedThisIncarnation}
+         *  is the authoritative one (a clock rollback after boot would otherwise stamp THIS process's own new
+         *  entries below the cutoff and finalize live runs). */
+        finalizeStartedBeforeMs?: number;
+        /** Retire a fleet row for a run this sweep just finalized ([2995]/[2999]): called ONLY with a TERMINAL run,
+         *  so the {@link JournalingWorkflowRunStore} projection publishes the final frame and then removes the row —
+         *  the store, the panel and the notify end up saying the same thing. Never called with a `running` run (see
+         *  the single-writer invariant above). Late-bound because the wrapper is constructed after this gate. */
+        publishTerminalFleetRow?: (id: string, run: WorkflowRun) => void;
     }): Promise<{
         scanned: number;
         redelivered: number;
@@ -234,6 +284,12 @@ export declare class JournalingWorkflowRunStore implements WorkflowRunStore {
     /** 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;
+    /** [2995] recovery projection seam: the same fleet projection as the put/update observation points, exposed so
+     *  the recovery sweep can RETIRE a row for a run it just finalized (terminal input ⇒ final frame, then remove).
+     *  Wire it as `recover`'s `publishTerminalFleetRow` hook — and only ever hand it a TERMINAL run: a `running`
+     *  row published from outside the wrapper's own write path has no guaranteed retirement (see the invariant on
+     *  {@link WorkflowNotifyGate.recover}). */
+    republishFleet(id: string, run: WorkflowRun): void;
     put(id: string, run: WorkflowRun): Promise<void>;
     update(id: string, scope: string, run: WorkflowRun, expect?: {
         rev: number;

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

@@ -41,8 +41,8 @@
  */
 import { mkdirSync, readFileSync, existsSync, openSync, writeSync, fsyncSync, closeSync } from "node:fs";
 import { join } from "node:path";
-import { deriveAgentDisplayStatus } from "@sema-agent/core";
-import { redactSecrets } from "../trace/redact.js";
+import { buildFleetWorkflowRow } from "../fleet/fleet-bus.js";
+import { isTerminalWorkflowRowStatus, seedTerminalWorkflowRow } from "../fleet/fleet-terminal-window.js";
 /** Build a bounded + redacted completion summary from a durable run's terminal state (the recovery path — the
  *  live path uses core's own `boundedSummary`). We never have the raw result here (the run store keeps the run,
  *  not the originator's payload), so we synthesize a conservative one: status + the run's already-bounded error.
@@ -86,9 +86,29 @@ export class WorkflowNotifyGate {
         this.deliver = deliver;
         this.opts = opts;
     }
+    /**
+     * The runIds whose journal entry THIS process recorded — the boot-orphan judgment's authoritative anchor
+     * (round-1 review, MEDIUM). A wall-clock cutoff alone is not sound: after a BACKWARD clock step the entries
+     * this process records land BELOW the boot cutoff, and the sweep would finalize runs whose in-process
+     * executor is alive and running (a false `failed` notify for a workflow that then keeps going — worse than
+     * the absent row it was fixing). Membership here is a fact about THIS incarnation, unforgeable by any clock.
+     * Retired on ack AND the moment a sweep observes the run terminal (the anchor only ever gates the `running`
+     * arm), so a delivery/ack outage cannot pile up entries for runs that are no longer executing.
+     */
+    recordedThisIncarnation = new Set();
     now() {
         return this.opts.now ? this.opts.now() : Date.now();
     }
+    /** Record a journal entry AND remember that this incarnation is the one that recorded it (see the field). */
+    async recordPending(entry) {
+        await this.journal.record(entry);
+        this.recordedThisIncarnation.add(entry.runId);
+    }
+    /** Ack an entry + drop its incarnation mark (acked ⇒ never scanned again, so the mark has no further use). */
+    async ackDelivered(runId) {
+        await this.journal.ack(runId, this.now());
+        this.recordedThisIncarnation.delete(runId);
+    }
     /**
      * Journal a STARTED run as pending-notify. Call this with the synchronous `runId` from `startWorkflow` /
      * `run_workflow` — BEFORE the workflow can reach terminal — so a crash mid-run still leaves a recoverable
@@ -97,7 +117,7 @@ export class WorkflowNotifyGate {
      */
     async onWorkflowStart(input) {
         try {
-            await this.journal.record({
+            await this.recordPending({
                 runId: input.runId,
                 scope: input.scope,
                 ...(input.sourceTaskId ? { sourceTaskId: input.sourceTaskId } : {}),
@@ -142,7 +162,7 @@ export class WorkflowNotifyGate {
         if (!existing) {
             // The start hook didn't journal it (e.g. a run started before this gate existed, or the hook was skipped).
             // Record it now so the deliver-then-ack ordering still holds and a crash mid-delivery is recoverable.
-            await this.journal.record({
+            await this.recordPending({
                 runId: p.runId,
                 scope,
                 ...(p.sourceTaskId ? { sourceTaskId: p.sourceTaskId } : {}),
@@ -158,7 +178,7 @@ export class WorkflowNotifyGate {
             this.opts.onError?.("deliver", p.runId, err);
             return;
         }
-        await this.journal.ack(p.runId, this.now());
+        await this.ackDelivered(p.runId);
     }
     /**
      * RECOVERY sweep — run at boot AND PERIODICALLY (wired into the service reaper), BEFORE/while serving traffic.
@@ -171,11 +191,32 @@ export class WorkflowNotifyGate {
      *    workflow died) + ack, instead of leaking the entry forever. This closes the exact crash topology SVC-1
      *    exists for (a replica SIGKILLed mid-run).
      *  - `running` and FRESH (within the grace window): genuinely in flight → leave pending (the owning process
-     *    delivers its terminal notify, or the next sweep catches it once it goes terminal or stale).
+     *    delivers its terminal notify, or the next sweep catches it once it goes terminal or stale). The sweep
+     *    publishes NOTHING here — see the single-writer invariant below.
      *  - MISSING (reaped / never persisted): ack-as-abandoned so the journal doesn't chase a ghost forever.
      * `orphanGraceMs` MUST exceed the max expected workflow runtime (the run store has no cross-replica liveness
      * signal, so age is the only orphan proxy). Returns a tally. A per-entry throw is isolated so one bad entry
      * can't abort the sweep.
+     *
+     * BOTH abandoned arms (boot-orphan + stale-past-grace) flip the DURABLE row to `failed` FIRST (CAS on rev),
+     * so the run store, the fleet panel and the delivered notify give ONE answer — previously the notify said
+     * `failed` while `/workflows` kept saying `running` forever ([2999]: republishing without finalizing would
+     * have turned "panel empty" into "panel shows a row that never moves"). A lost CAS means the run moved under
+     * the sweep (e.g. its real terminal landed concurrently) — skip this pass; the entry stays pending and the
+     * next sweep handles the NEW state.
+     *
+     * 🔴 SINGLE-WRITER INVARIANT for the fleet row (round-1 review, two HIGH findings): the sweep only ever
+     * publishes a **TERMINAL** fleet frame (the flip above, via `publishTerminalFleetRow` → final frame + remove).
+     * It NEVER publishes a `running` row. Two reasons, both "a row we mint here can become one nobody can retire":
+     *  1. cross-replica (SQL journal): a pending `running` entry may belong to ANOTHER replica. Its terminal
+     *     update lands on that replica's own (replica-local) fleet bus, and its ack removes the entry from the
+     *     shared journal — so this replica would never see the run again and its minted row would sit `running`
+     *     forever. (The terminal-redelivery arm deliberately doesn't publish either — it is a notify path.)
+     *  2. same-replica: `runStore.get` is a READ-TIME SNAPSHOT. If the live run commits its terminal (and the
+     *     wrapper removes the row) between that read and the publish, a `running` republish resurrects a row
+     *     that will never be removed again.
+     * A live row's ONE writer is this replica's `put`/`update` observation point ({@link JournalingWorkflowRunStore}),
+     * which by construction sees every transition including the terminal one.
      */
     async recover(opts = {}) {
         const orphanGraceMs = opts.orphanGraceMs ?? 24 * 60 * 60 * 1000; // 24h default — well beyond any normal workflow
@@ -183,12 +224,28 @@ export class WorkflowNotifyGate {
         let redelivered = 0;
         let stillRunning = 0;
         let abandoned = 0;
+        /** Was this entry recorded by a PREVIOUS incarnation of this process? Only meaningful when the caller granted
+         *  the replica-local finalize authority (a shared/SQL journal carries other replicas' entries). Both halves
+         *  are required — see `finalizeStartedBeforeMs` + {@link recordedThisIncarnation}. */
+        const isPreBootEntry = (entry) => opts.finalizeStartedBeforeMs !== undefined &&
+            !this.recordedThisIncarnation.has(entry.runId) &&
+            entry.createdAt < opts.finalizeStartedBeforeMs;
         for (const entry of pending) {
             try {
                 const run = await this.runStore.get(entry.runId);
                 if (!run) {
-                    // No durable run — reaped or never persisted. Don't keep it pending forever.
-                    await this.journal.ack(entry.runId, this.now());
+                    // No durable run — USUALLY a ghost (the row was reaped, or its `put` threw). But it is ALSO the
+                    // transient shape of a run being started RIGHT NOW: JournalingWorkflowRunStore journals BEFORE it
+                    // persists (deliberately — a persist that throws must still leave a recoverable entry), so there is a
+                    // window where the entry exists and the row does not. Acking that window is unrecoverable: the owner's
+                    // own terminal `deliverOnce` then sees `acked` and drops the completion for good — the exact loss SVC-1
+                    // exists to prevent (round-2 review, HIGH). So only ack a ghost that PROVABLY isn't that window: one
+                    // that predates this incarnation, or one older than the grace the whole sweep already trusts.
+                    if (!isPreBootEntry(entry) && this.now() - entry.createdAt <= orphanGraceMs) {
+                        stillRunning++; // "left pending this pass" — a start-in-progress is exactly that
+                        continue;
+                    }
+                    await this.ackDelivered(entry.runId);
                     abandoned++;
                     continue;
                 }
@@ -207,15 +264,43 @@ export class WorkflowNotifyGate {
                 const originatingSessionId = run.originatingSessionId;
                 if (run.status === "running") {
                     const startedAt = run.startedAt || entry.createdAt;
-                    if (this.now() - startedAt <= orphanGraceMs) {
+                    // [2995] boot-orphan judgment (replica-local journal only): the entry predates this process, so the
+                    // in-process executor that owned it died with the previous incarnation — nothing will ever flip it.
+                    // (Conditions in `isPreBootEntry`: replica-local authority + not recorded by US + predates boot.)
+                    const bootOrphan = isPreBootEntry(entry);
+                    if (!bootOrphan && this.now() - startedAt <= orphanGraceMs) {
                         stillRunning++;
-                        continue; // fresh → genuinely in flight; the owner (or a later sweep) delivers terminal
+                        // fresh → genuinely in flight; the owner (or a later sweep) delivers terminal. Publish NOTHING here:
+                        // a `running` row minted from a read-time snapshot can outlive every chance to retire it (the
+                        // single-writer invariant on the doc-comment above).
+                        continue;
                     }
-                    // Stale `running` ⇒ crash-orphan (nothing will ever flip it terminal). Finalize as abandoned/failed.
+                    // Orphaned `running` — boot-orphan (executor died with the previous process) or stale past grace
+                    // (nothing will ever flip it terminal). Finalize as abandoned/failed: flip the DURABLE row first
+                    // ([2999] honesty half — store/fleet/notify must give one answer), then deliver + ack.
+                    const abandonSummary = bootOrphan
+                        ? "workflow abandoned — the engine restarted while it was running (its in-process executor did not survive the restart)"
+                        : "workflow abandoned — still `running` past the orphan grace window (replica likely crashed mid-run)";
+                    const flipped = { ...run, status: "failed", error: abandonSummary, endedAt: this.now() };
+                    const flippedOk = await this.runStore.update(entry.runId, run.scope, flipped, run.rev !== undefined ? { rev: run.rev } : undefined);
+                    if (!flippedOk)
+                        continue; // the run moved under the sweep — leave pending; next sweep sees the NEW state
+                    this.recordedThisIncarnation.delete(entry.runId); // terminal now — the anchor only ever gates `running`
+                    // ORDER: retire the fleet row FIRST — immediately after the durable flip, before anything is awaited.
+                    // Same order as the live leg (the wrapper publishes the terminal frame, then core fires its notify), and
+                    // it is the only order where "a finalized run leaves the active fleet" survives every delivery outcome
+                    // (rounds 4+5): the delivery may throw at its ack, or never settle at all, and a `finally` cannot help
+                    // with the latter — while the NEXT sweep takes the terminal-redelivery arm, which deliberately publishes
+                    // nothing, so a row skipped here would be stranded `running` with nobody left to retire it.
+                    // The converse risk is bounded and self-healing: if the projection throws, this pass delivers nothing
+                    // and the entry stays pending — the next sweep's terminal arm delivers it. Deferred by one sweep, never
+                    // lost. (Subscriber throws are already isolated inside the fleet bus — per-callback try/catch with a
+                    // registered fail-open tag — so a projection throw here means the publish machinery itself broke.)
+                    opts.publishTerminalFleetRow?.(entry.runId, flipped); // final frame then remove
                     await this.deliverOnce({
                         runId: entry.runId,
                         status: "failed",
-                        summary: "workflow abandoned — still `running` past the orphan grace window (replica likely crashed mid-run)",
+                        summary: abandonSummary,
                         ...(sourceTaskId ? { sourceTaskId } : {}),
                         ...(principal ? { principal } : {}),
                         ...(originatingSessionId ? { originatingSessionId } : {}),
@@ -225,6 +310,10 @@ export class WorkflowNotifyGate {
                     continue;
                 }
                 // Terminal but not acked ⇒ the crash dropped its notify. Re-derive the bounded summary + re-deliver.
+                // Drop the incarnation mark FIRST (round-2 review, MEDIUM): the anchor only ever gates the `running` arm,
+                // so a terminal run has no use for it — retiring here (not only on a successful ack) keeps the registry
+                // tracking runs that are actually in flight even through a prolonged delivery outage.
+                this.recordedThisIncarnation.delete(entry.runId);
                 await this.deliverOnce({
                     runId: entry.runId,
                     status: run.status,
@@ -411,40 +500,36 @@ export class JournalingWorkflowRunStore {
     publishFleet(id, run) {
         if (!this.fleetBus)
             return;
-        const agents = run.agents ?? [];
-        // [2336] doneCount 与 failedCount **不相交**:done 只数 completed。契约以此为前提(fleet-bus.ts
-        // startedCount 注的回退式 done+failed ≤ started);把 failed 也计进 done 会让全失败 workflow 的
-        // 终帧渲成 "N done"(cli 4.1.3 实测 done=2 failed=2 started=2)。
-        const done = agents.filter((a) => a.status === "completed").length;
-        const failed = agents.filter((a) => a.status === "failed").length;
-        // cli [1726] 二①:CC 规模告警的分母是 **started**(已启动),而 `totalCount`(= agents.length)是**计划总数**
-        // (含排队中)。判别口径走 core 导出的 `deriveAgentDisplayStatus` —— 一个 agent 已在 `run.agents` 里但
-        // `startedAt` 未置就是排队中。**不自己写 `startedAt !== undefined`**:那是 core 的显示契约,两端各写一遍
-        // 必然漂移(本仓刚在 coarse 门镜像上吃过同款),用它的函数则 core 一改、两端同时跟随。
-        const started = agents.filter((a) => deriveAgentDisplayStatus(a, run.status) !== "queued").length;
-        const terminal = run.status === "completed" || run.status === "failed";
-        this.fleetBus.publishWorkflow({
-            id,
-            // [WF2-A parity] redact the workflow label surfaces for parity with the run + subagent-child names (fleet-bus.ts):
-            // a tool-launched (LLM-authored) workflow's meta.name/description is task-controlled and could carry a secret shape.
-            name: redactSecrets(run.name ?? "Dynamic workflow"),
-            ...(run.description ? { description: redactSecrets(run.description) } : {}),
-            scope: run.scope,
-            // codex-6 F2:sessionId 必须随行——streamFleet 对无 sessionId 的行按「同 principal 全会话可见」
-            // 兜底,漏发=A 会话的 workflow 名/进度/token 泄进 B 会话的 ?session= 过滤流。
-            ...(run.originatingSessionId ? { sessionId: run.originatingSessionId } : {}),
-            status: run.status,
-            doneCount: done,
-            totalCount: agents.length,
-            failedCount: failed,
-            startedCount: started,
-            tokens: (run.stats?.tokens ?? 0) + (run.stats?.nested?.tokens ?? 0),
-            // [1294]:跑动中也带时长(1.232 只在 endedAt 后带——clay 验收轮实锚面板恒显 0s)。终态用
-            // endedAt 定格,活跑用 now-startedAt(每次 put/update 观察点刷新,壳侧读帧即当前时长)。
-            elapsedMs: (run.endedAt ?? Date.now()) - run.startedAt,
-        });
+        // A-002.3(#194 病族 F1 同源性断裂):终态判据走 fleet-terminal-window 的共享谓词(其穷举表对
+        // core WorkflowRunStatus 编译期闭合)——此前手写两值比较是第二份独立定义,core 加终态词时穷举表
+        // 红、这里恒 false ⇒ 行既不 seed 进终态窗也不 removeWorkflow,面板留幽灵 running 行。
+        const terminal = isTerminalWorkflowRowStatus(run.status);
+        // 撤行**不挂在发帧成功上**(复审第 2 轮 MEDIUM):「终态行必须离场」是不变量、发终帧是尽力而为。
+        // try/finally ⇒ 发布本体抛错照样撤行(异常仍向上抛,不吞:吞了就是一条未登记的 fail-open 臂)。
+        // 订阅方抛错已在 fleet bus 的 subscribe 隔离层被吞并记 fail-open——本 finally 守的是发布机器本身
+        // 的抛错(理论缝级,fresh 复审盘点后判近死防御但保留:防未来发布本体改动回退)。两腿一处收口。
+        // 行投影本体 = {@link buildFleetWorkflowRow}(#189:快照的终态行窗与本写路径共用同一份投影,
+        // 单源不漂;本函数的发布/撤行语义逐字不变)。
+        // [3156] 轮2 修:终态行**写路径顺手 seed** 进程内终态窗缓存——重启-重连剧本里(boot recover 判死),
+        // fleetWide 连接的 durable pull 没有正确的查询键可用(caller principal ≠ 引擎铸行 scope),seed 是
+        // 唯一同源可达径。放在 publish 之前:seed 是纯内存 push,不会抛;终态行入窗与发帧同拍。
         if (terminal)
-            this.fleetBus.removeWorkflow(id); // terminal workflow leaves the active fleet (the shell saw the final frame)
+            seedTerminalWorkflowRow(buildFleetWorkflowRow(id, run));
+        try {
+            this.fleetBus.publishWorkflow(buildFleetWorkflowRow(id, run));
+        }
+        finally {
+            if (terminal)
+                this.fleetBus.removeWorkflow(id); // terminal workflow leaves the active fleet (the shell saw the final frame)
+        }
+    }
+    /** [2995] recovery projection seam: the same fleet projection as the put/update observation points, exposed so
+     *  the recovery sweep can RETIRE a row for a run it just finalized (terminal input ⇒ final frame, then remove).
+     *  Wire it as `recover`'s `publishTerminalFleetRow` hook — and only ever hand it a TERMINAL run: a `running`
+     *  row published from outside the wrapper's own write path has no guaranteed retirement (see the invariant on
+     *  {@link WorkflowNotifyGate.recover}). */
+    republishFleet(id, run) {
+        this.publishFleet(id, run);
     }
     async put(id, run) {
         // Journal FIRST (best-effort, swallowed inside onWorkflowStart) so a started run is always recoverable, THEN

package/dist/parked-decide.js

@@ -81,10 +81,15 @@ export async function decideParkedAgent(deps, req) {
         // RB-459(core 5.7.0,F1/F6 翻案后唯一剩下的 claim 前拒):问题门的 approve 必须携 answer——
         // parked 腿无 live answering face,消费 claim 后只会空跑一次 revive;claim 前拒是免损前置。带 answer 的
         // approve 与任何 deny 都放行透传,core 是语义权威(header 逐字匹配等)。
-        // 🔴 #152:本判据**不再**有 core 侧同判兜底。core 的 pre-CAS 拒条件是「`taskConfig.onQuestion ??
-        // deps.onQuestion` 为 undefined 或 QUESTION_AWAITS_RESUME」;ASK_QUESTION_ENABLED 部署上 spec 不再 stamp
-        // 哨兵、deps.onQuestion 是 coordinator,条件恒不成立 ⇒ core 放行,赎回腿会拿 coordinator 的空答当人答
-        // 并消费掉 checkpoint。这一手现在是该腿唯一的拒绝点(任务级孪生:src/http/server.ts 的 decide 路由)。
+        // 🔴 #152 当年写这条时的机制理由是:core 的 pre-CAS 拒条件(「`taskConfig.onQuestion ??
+        // deps.onQuestion` 为 undefined 或 QUESTION_AWAITS_RESUME」)在 ASK_QUESTION_ENABLED 部署上恒不成立
+        // ⇒ core 放行,而赎回腿会拿 coordinator 的**空答**当人答并消费掉 checkpoint。
+        // ⚠️ 那个理由已被后续两处证伪,别再据它推理:①#166 起 QuestionCoordinator 的每一条无人应答臂(无
+        // ALS ctx / abort / 限流 / 呈现不了 / TTL)一律返 `{kind:"unavailable"}`,类头逐字承诺「It NEVER
+        // synthesizes an empty answer set」——赎回腿无 ctx,拿到的是 unavailable 而不是空答;②core 5.16 对
+        // 赎回中的 ask 走 redeemsApproval 臂返 isError(「will not silently self-answer」)。
+        // 本判据**保留**,理由换成免损前置:放过去也只会空跑一次 revive(claim 已被消费),claim 前拒是
+        // 更便宜、错误信息也更准的那一手(任务级孪生:src/http/server.ts 的 decide 路由)。
         return { status: 400, body: { error: "pending action is AskUserQuestion — approve requires body.answer (the operator's answers[]); deny needs none", errorCode: "decide.parked_answer_required", taskId: match.handle } };
     }
     if (row.name === undefined) {

package/dist/plugins/approval-ask-store-memory.d.ts

@@ -12,11 +12,11 @@
  *  - resolveProvisional 故意不经 canAskTransition(同 SQL twin 头注：这是版本化补偿的例外通道）。
  */
 import { type AskState, type BatchState } from "../approval-ask-machine.js";
-import type { AskDecision, AskRow, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, DecideResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
+import type { AskDecision, AskRow, AskTransitionPatch, ApprovalAskStore, BatchRow, BindGateInput, BindResult, DecideAskInput, EnsureAskResult, DecideResult, ExpireResult, NewAskRow } from "./approval-ask-store-sql.js";
 export declare class InMemoryApprovalAskStore implements ApprovalAskStore {
     private readonly asks;
     private readonly batches;
-    ensureAsk(row: NewAskRow): Promise<AskRow>;
+    ensureAsk(row: NewAskRow): Promise<EnsureAskResult>;
     transitionAsk(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     decideAsk(askId: string, batchId: string, decision: DecideAskInput): Promise<DecideResult>;
     expireAsk(askId: string, batchId: string): Promise<ExpireResult>;

package/dist/plugins/approval-ask-store-memory.js

@@ -50,8 +50,9 @@ export class InMemoryApprovalAskStore {
             });
         }
         const existing = this.asks.get(row.askId);
+        // 幂等命中:行是**别人**插的 ⇒ `inserted: false`(收尾权限判别位,语义见 `EnsureAskResult` 顶注)。
         if (existing)
-            return { ...existing };
+            return { row: { ...existing }, inserted: false };
         // 🔴 车4 §12-E:`idempotency_key` 已归**回决专用**,`NewAskRow` 的同名字段随之摘除 ⇒ 铸行不再有
         // 唯一性可撞(列恒 NULL)。原先在这里镜像 UNIQUE 的那段扫描也随之下车;撞键判定搬到 `decideAsk`
         // (SQL twin 那侧是 `(task_id, idempotency_key)` 索引在库层拒 ⇒ typed `idempotency_conflict`)。
@@ -85,7 +86,7 @@ export class InMemoryApprovalAskStore {
             updatedAtMs: row.createdAtMs,
         };
         this.asks.set(row.askId, created);
-        return { ...created };
+        return { row: { ...created }, inserted: true };
     }
     async transitionAsk(askId, from, to, patch) {
         if (!canAskTransition(from, to)) {

package/dist/plugins/approval-ask-store-sql.d.ts

@@ -59,9 +59,13 @@ export interface AskRow {
      * 🔴 车5 §9 C2:铸卡时呈给人看的那份 input 的**服务端摘要**(`AskRequest.boundInputHash`,core 侧已在场)。
      * 与下面 PARKED 坐标里的 `gateBoundInputHash` 是**两件不同的东西**,别混:
      *   - `boundInputHash`(本列)= ask **铸行时**的入参摘要,一次写定永不改;对账收敛器判据 1 用它跟
-     *     checkpoint 行的同名列做**硬相等**(identity 四元组之外的第二道等式)。缺席 ⇒ 判据 1 不命中
-     *     (禁「能取到时才比」的可选谓词——同 session 内 toolCallId 会被网关重用,只靠 identity 会把旧 ask
-     *     PARK 到别人的 resume 坐标上,而 PARKED 是不可回滚的终态)。
+     *     checkpoint 行的同名列做**硬相等**——它是**身份三元组之外的第二道等式**,身份本身是
+     *     (`sourceTaskId`, `toolCallId`, 因果下界)三维(#168 件1 换轴,判据属主 = `approval-reconciler.ts`
+     *     的 `classifyGateMatch`;本注上一版写的「identity 四元组」是换轴前的旧口径,`sessionId` 从来不是
+     *     内存判据维)。任一侧缺席 ⇒ 判据 1 **不命中**;归因看走到哪一层:身份先判(候选集非空却没有同身份
+     *     的一条 ⇒ `identity_miss`),身份这层还够得着时缺席才记 `single_mint`(禁「能取到时才比」的可选谓词
+     *     ——同 session 内 toolCallId 会被网关重用,只靠身份会把旧 ask PARK 到别人的 resume 坐标上,而
+     *     PARKED 是不可回滚的终态)。
      *   - `gateBoundInputHash`(下面)= 真 **PARK 成功那一刻**从 checkpoint 抄回来的坐标之一,bindBatch 才写。
      * 本车只落店面承载(列 + 行形 + 读写),铸行调用点的供值归车2/3b。
      */
@@ -114,6 +118,23 @@ export interface NewAskRow {
     expiresAtMs: number;
     createdAtMs: number;
 }
+/**
+ * `ensureAsk` 的产出 —— 行 **+ 这一次调用到底插没插**(#168 件2)。
+ *
+ * 🔴 为什么判别位必须由**店**给:`ensureAsk` 是幂等 upsert(`askId` 是确定性派生,重试 / failover /
+ * 闭包再入天然指向同一行),所以「拿到一条 STREAM_PENDING 行」有两种成因 —— 本次插的,或幂等命中了
+ * **别人正持有**的那条活行。两者的收尾权限完全相反:前者本次可以收(放弃时把孤儿行 VOID 掉),后者
+ * 一个字都不许动(动了就是把真属主正在等的那张卡作废)。调用侧此前只能拿 `createdAtMs === 本次传入值`
+ * 去**猜**归属,而那把尺在同一毫秒的两次并发插入上会给出假阳性(旧注里如实记着的残余)。
+ * `INSERT IGNORE` / `ON CONFLICT DO NOTHING` 的 affected 行数是引擎对同一个问题的**权威**回答,
+ * 两方言都有;把它如实带出来,猜就退休了。
+ *
+ * `inserted: true` ⇒ 这条行是本次调用写下的(可收尾);`false` ⇒ 幂等命中既有行(只读,不许收尾)。
+ */
+export interface EnsureAskResult {
+    row: AskRow;
+    inserted: boolean;
+}
 /** `transitionAsk`/`resolveProvisional` 的可选补丁——只有出现的字段才落 SQL(未出现 = 该列不变),
  *  `updatedAtMs` 恒必填(调用方是未来的协调器,时间戳由它按事件时钟决定,店不偷偷用 `Date.now()`)。 */
 export interface AskTransitionPatch {
@@ -206,7 +227,8 @@ export interface BatchRow {
 }
 /** design 定稿 §4 的持久层接口。协调器接线(车2)、恢复扫描消费(车5)不在本车范围——本车只落这些方法。 */
 export interface ApprovalAskStore {
-    ensureAsk(row: NewAskRow): Promise<AskRow>;
+    /** 幂等 upsert。返回**行 + 本次是否真插入**(判别位语义见 {@link EnsureAskResult})。 */
+    ensureAsk(row: NewAskRow): Promise<EnsureAskResult>;
     transitionAsk(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     decideAsk(askId: string, batchId: string, decision: DecideAskInput): Promise<DecideResult>;
     expireAsk(askId: string, batchId: string): Promise<ExpireResult>;
@@ -275,6 +297,39 @@ export declare const APPROVAL_BATCHES_TABLE = "approval_batches";
  *
  * SCHEMA POLICY 同 `tidb-pool.ts` 头注:纯 CREATE,禁 ALTER 增量 seam,改列直接改这里 + 重建库
  * (`docs/schema/baseline-mysql.sql` 是由这些文本机器录制出的**产物**,永不手改)。
+ *
+ * ── 列宽的**测量依据**(#192 A10;U2 逐列取证在档)──────────────────────────────────────────────────
+ * 本表家族原先一律 VARCHAR(255),是"先建表后想"的产物。按"每列的值到底由谁铸、有没有入口上限"重新裁:
+ *
+ *  收窄(有硬上限背书,证据即上限本身):
+ *   · `ask_id` / `batch_id` / `bound_ask_id` → 64:`deriveAskId`/`deriveBatchId` 恒是 sha256 hex 取前
+ *     64 字符(`approval-ask-machine.ts` deterministicId),按构造不可能更长。
+ *   · `task_id` → 64:入口 `UUIDV7_RE`(`security.ts:134`)只放行 36 字符的规范 uuidv7;与兄弟列
+ *     `task_run.task_id VARCHAR(64)` 同宽(此前 255 是本家族独有的偏离,无依据)。
+ *   · `session_id` → 64:提交入口硬拒 >64(`http/server.ts` "sessionId must be at most 64 characters"),
+ *     与 `session_meta`/`task_run` 同宽。
+ *   · `owner` → 190:`assertPrincipalShape` 的 `PRINCIPAL_MAX_LENGTH = 190`(`security.ts:350`)硬拒更长者;
+ *     全仓每一根 owner/scope 轴都是 190,此前 255 同样是无依据偏离。
+ *   · `gate_token` → 120:它抄的是 checkpoint 的 token(core `mintCheckpointToken` = 16 字节 hex = 32 字符),
+ *     取与**被抄那一列** `checkpoint.token VARCHAR(120)` 同宽 —— 同一个值在两张表上宽度必须一致,
+ *     否则抄的那一步就是一道静默截断。512 是原先的 16 倍冗余。
+ *
+ *  🔑 上面四条收窄之所以**不引入任何新暴露面**,靠的不是入口断言而是一条更硬的事实:同一个 session_id /
+ *     task_id / owner **早就**同时躺在 `session_meta.session_id VARCHAR(64)` / `task_run.task_id VARCHAR(64)` /
+ *     `task_run.owner VARCHAR(190)` 里。任何长到能撑爆本表新宽度的值,在写到那几张**更中心**的表时就已经
+ *     先炸了 —— 本表此前的 255 从来不是一道额外的安全余量,只是一处与全仓不一致的偏离。
+ *     ⇒ 收窄的风险上界 = 0;真正要担心的是反过来:留着 255 会让人误以为这里可以存更长的 id。
+ *
+ *  🔴 **刻意不收窄**(测量结果不支持,记在这里免得下一个人以为是漏了):
+ *   · `source_task_id` / `tool_call_id` / `parent_tool_call_id` / `gate_bound_call_id` —— 这四列的值是
+ *     **模型/引擎铸的原始 id**,服务端在写行这一步**没有任何长度断言**(`approval-card.ts` 的
+ *     `MAX_IDENT` 只裁了给人看的那份 card 投影,不是本列)。没有入口上限就收窄 = 把"存不下"这件事
+ *     推迟到 INSERT 才炸(MySQL 更糟:静默截断),换来的只是几十字节。要收窄,先补入口断言
+ *     (照 `assertPrincipalShape`/`assertIdempotencyKeyShape` 的姿势),那是另一件事。
+ *   · `bound_input_hash` / `gate_bound_input_hash` —— 按约定是 sha256 hex(64),但 `readBoundInputHash`
+ *     只校验"非空字符串",没校长度/字形 ⇒ 同上,先有断言再谈收窄。
+ *   · `idempotency_key` —— 255 **正是**入口断言的上限本身(zod `.max(255)` + 店内 `assertIdempotencyKeyShape`
+ *     双执法),宽度与上限同源,恰好正确,动它反而制造截断面。
  */
 export declare const TIDB_APPROVAL_ASK_STATEMENTS: readonly string[];
 /** {@link TIDB_APPROVAL_ASK_STATEMENTS} 的遍历壳——生产路径走 `tidb-pool.ts` 的中央 `ensureSchema`
@@ -303,7 +358,7 @@ export declare class SqlApprovalAskStore implements ApprovalAskStore {
     private getAskOn;
     /** {@link getAskOn} 的批侧同形(同一条纪律:失败臂回读走本连接)。 */
     private getBatchOn;
-    ensureAsk(row: NewAskRow): Promise<AskRow>;
+    ensureAsk(row: NewAskRow): Promise<EnsureAskResult>;
     transitionAsk(askId: string, from: AskState, to: AskState, patch: AskTransitionPatch): Promise<boolean>;
     decideAsk(askId: string, batchId: string, decision: DecideAskInput): Promise<DecideResult>;
     expireAsk(askId: string, batchId: string): Promise<ExpireResult>;