@sema-agent/server 1.323.0 → 2.0.0

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

@@ -1,24 +1,123 @@
+/**
+ * P1 ①② — the async-workflow COMPLETION INBOX (the deployment half of "route a finished
+ * background workflow back to the session that started it").
+ *
+ * ## Why this exists
+ * A self-orchestration / background workflow (started via core's `RunWorkflow`) runs to terminal OUTSIDE the
+ * originating session's request loop — often minutes later, possibly after that turn's SSE stream already
+ * closed. core's notifier seam + the SVC-1 {@link WorkflowNotifyGate} deliver its terminal payload to the
+ * deployment's `deliverWorkflowCompletion` AT-LEAST-ONCE, but that was a log-only shell: the model that
+ * launched the workflow never learned it finished (it had only the deterministic `WorkflowStatus` poll floor).
+ *
+ * This inbox is the PUSH half. `deliverWorkflowCompletion` resolves the originating **session + owner** (from
+ * the payload's `sourceTaskId`) and `enqueue`s the completion here; when that session next OPENS a stream (a
+ * new `POST /v1/runs` turn), the HTTP layer `drain`s the inbox and — for entries whose `owner` matches the
+ * draining caller's VERIFIED principal — emits a `workflow_complete` out-of-band SSE frame (mirroring the
+ * question/elicit frame pattern) that the shell turns into a `<task-notification>` (the shell's
+ * `enqueuePendingNotification`, deduped by runId). Delivery is thus decoupled from whether a stream was open
+ * at completion time — a disconnected-then-reconnected shell still gets it — WITHOUT a cross-loop append into
+ * the originating run's own event log (its `seq` counter is owned by that run's loop; appending from outside
+ * would race it — so completions live in this SEPARATE store).
+ *
+ * ## Tenancy
+ * Each entry carries the originating run's `owner`. The drain-side owner check (in the HTTP layer) is a
+ * defence-in-depth SECOND gate on top of the authorizer's sessionId→owner binding: a session that is deleted
+ * then re-claimed by a different tenant rotates that binding, so the stamped `owner` is what actually gates
+ * whether a completion is EMITTED. `purge(sessionId)` is called on session delete so orphaned completions
+ * don't linger. (`owner: null` = the single-user turnkey posture, no tenancy boundary.)
+ *
+ * ## Durability / delivery model
+ * - **At-least-once, shell-deduped**: the shell dedups by `runId` (`markTaskNotified`), so a completion frame
+ *   re-delivered across a crash is harmless. `drain` therefore removes on read; the small window where a crash
+ *   after `drain` but before the frame is flushed loses a push is covered by the deterministic `WorkflowStatus`
+ *   poll floor (core 1.197) — never a silent hang.
+ * - **Crash-safe File ledger** (default): an append-only `(op) → record` journal, replayed into an in-memory
+ *   `sessionId → (runId → entry)` map. A torn trailing line (crash mid-append) is dropped on replay
+ *   (uncommitted). **Compacted** — rewritten from the live in-memory state on boot AND once the ledger grows
+ *   past {@link COMPACT_EVERY} appends — so tombstones/evicted/drained lines don't accumulate without bound.
+ *   Owner-only perms (identity data).
+ * - **Bounded**: at most {@link MAX_PENDING_PER_SESSION} newest completions are retained per session; the
+ *   oldest is dropped (with a warn on LIVE enqueue — suppressed during replay to avoid log noise).
+ */
 import { mkdirSync, readFileSync, existsSync, openSync, writeSync, fsyncSync, closeSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { redactSecrets } from "../trace/redact.js";
+/** Cap on retained pending completions per session (drop-oldest beyond it). A session with more than this many
+ *  undelivered workflow completions is pathological; the poll floor still covers the dropped ones. */
 export const MAX_PENDING_PER_SESSION = 100;
+/** Compact the File ledger (rewrite from live state) once this many records have been appended since the last
+ *  compaction — bounds on-disk size + boot replay cost for a long-lived process with high workflow churn. */
 export const COMPACT_EVERY = 512;
+/** How long after a `purge` an `enqueue` for the same session is refused (the purge-vs-enqueue fence): a
+ *  workflow completion landing AFTER its session was deleted must not resurrect as a live entry the next
+ *  claimant of that sessionId would see. In-memory only (a restart forgets the fence — the cross-restart race
+ *  window is negligible and the drain-side owner gate still stands as the real tenancy boundary). */
 export const PURGE_FENCE_MS = 10 * 60 * 1000;
+/** How long after {@link WorkflowCompletionInbox.markTerminalServed} an `enqueue` for the SAME (session,
+ *  runId) is refused — covers the notify path lagging the model's poll (the notify gate is async +
+ *  at-least-once, so the completion can land in the inbox AFTER the poll already told the model). Long enough
+ *  to swallow any realistic notify lag incl. a boot-recovery re-fire racing a fresh poll; per-runId scoped, so
+ *  it can never starve a DIFFERENT workflow's push. In-memory only (see {@link PURGE_FENCE_MS} rationale). */
 export const SERVED_FENCE_MS = 30 * 60 * 1000;
+/** design/144 §4 server 折叠键:`JSON([域, taskId, RAW status])[#seq]`。域=external 帧独立 lane(task_id 是
+ *  调用方自由串,不分域可预占内部帧键把真实子代 settle 帧吞掉)/其余内部帧统一 "task" 域。
+ *
+ *  三路复审修1(MED):status 保留 RAW,不再归一 completed/failed —— 归一让同 id 无 seq 的两条 external
+ *  通知(先 `event` 后 `cancelled`)折叠成同一把 `…:failed` 键,inbox map 里第二条 REPLACE 第一条,drain
+ *  只吐一条(entry 的存储 status 列仍归一,那是账本的双终态列,不动;RAW status 本就随 payload extras
+ *  透传)。这与 {@link taskNotificationStreamKey} 的 RAW 语义对齐(stream 侧早已保 RAW)。
+ *
+ *  编码=防碰撞元组:域/taskId/status 走 JSON 数组(调用方自由串伪造不了分隔符);`#seq` 尾折在 JSON 之外
+ *  ——JSON 段恒以 `"]` 结尾,`#digits` 尾无歧义,于是 {@link foldKeyFamily} 的剥尾语义 AND SQL 双生子
+ *  (tidb/pg-workflow-run-store 的 `regexp_replace(run_id, '#[0-9]+$', '')` 家族比对)原样成立——把 seq 折进
+ *  JSON 元组会让 SQL 侧家族 ack/fence 永 miss(那是另一批的真库改动面,本修有意不碰)。
+ *  seq 折入=逐停机周期各自成键(1.283 起 background_agent 四腿 notify 铸 cycleSeq);无 seq=单周期旧键
+ *  (bash/monitor terminal/retain 降级,诚实语义)。serve-fence 侧必须用同一函数(或其家族前缀)构造,
+ *  否则键形漂移=fence 永 miss(server.ts fleet 腿的 `taskNotificationFoldKey({task_id, status})` 无 seq 形
+ *  即家族前缀,两侧同为 RAW status,依旧咬合)。 */
 export function taskNotificationFoldKey(n) {
     const domain = n.task_type === "external" ? "external" : "task";
     return `${JSON.stringify([domain, n.task_id, n.status])}${n.seq !== undefined ? `#${n.seq}` : ""}`;
 }
+/** design/144 stream 侧去重键(core [784]④a + codex 1.189 前双审 F2)= `域:taskId:status[#seq]`。
+ *  与 {@link taskNotificationFoldKey} 同族,域二分也一致(codex F2 HIGH:external 通知的 task_id 是
+ *  POST /v1/sessions/:id/notify 调用方自由串——同一条腿上,drain 出的 external 帧可与内部任务帧同形
+ *  `task_id:status:seq` 撞键互吞,per-leg 键集并不豁免这个面,旧注释「没有跨调用方预占面」判错);
+ *  仍与 fold key 有意不同的一点:status 保留 RAW(killed/cancelled/event 不归一 failed)——归一会让同
+ *  task 的 Monitor event 批与 failed 终态在一条腿上互吞;wire 去重要的是逐帧身份,不是 inbox 的双终态列。
+ *  `seq` 折入 = 停→唤→停的第二周期同 status 帧各自成键(core 1.283 起 background_agent 四腿 notify 铸
+ *  cycleSeq;缺 seq 时旧键曾把二周期 completed 帧在 observer 臂反向吞掉——core [784]④a);无 seq 的帧
+ *  (bash/monitor terminal/retain 降级)保持单周期旧键=同键第二帧吞,诚实语义。task_type 缺席(旧 core
+ *  内部帧)归 "task" 域——external 帧的 task_type 三来源齐备(notify 端点 core 铸 / inbox entry extras 存
+ *  / drain 帧 spread 复原),不会漏域。observer 臂 / stream 臂 / turn-open drain 登记三处必须用本函数
+ *  构键且都传 task_type,键形漂移=去重永 miss。 */
 export function taskNotificationStreamKey(n) {
     const domain = n.task_type === "external" ? "external" : "task";
     return `${domain}:${n.task_id}:${n.status}${n.seq !== undefined ? `#${n.seq}` : ""}`;
 }
+/** Per-leg notified-key ledger cap (codex 1.189 前双审 F3):一条超长腿(海量互异 bg 通知)不许把键集
+ *  撑到无界——超出删最老插入(Map 迭代序=插入序)。远高于任何真实 per-leg 通知量;被逐键的老通知
+ *  最坏情形=同键晚到帧多写一次(at-least-once,shell 按键 dedup 兜底),绝不吞新帧。 */
 export const NOTIFIED_KEYS_MAX = 4096;
+/**
+ * Per-leg delivered-notification ledger(codex 1.189 前双审 F1 HIGH 的修位)。
+ * 键 = {@link taskNotificationStreamKey};值 = 「认领这把键的那次写是否真落盘」的 promise(true=成功)。
+ * 为什么是 Map<string, Promise<boolean>> 而不是 Set:bg/resume 腿的 observer 臂是 fire-and-forget append
+ * (`void append(...)`)——旧 Set 下 append 失败(SQL blip)时键已被占而盘上无帧,core pend-drain 把同
+ * payload 重放到 stream 臂时被键吞 = 通知永丢。现在 stream 臂对已见键 `await` 认领方的真实结果,false 则
+ * 照写并把键值升为 true。sync 腿的写是同步 res.write(无异步失败窗口)、drain 臂的写被
+ * emitPendingWorkflowCompletions await(失败→不 ack→下腿重投)——两者登记 resolved(true) 即可;三腿统一
+ * 用本 Map 形状,让三对臂保持逐行孪生。
+ */
 export class NotifiedKeys {
     byKey = new Map();
+    /** The pending/settled outcome of the write that claimed `key`, or undefined when unclaimed. */
     get(key) {
         return this.byKey.get(key);
     }
+    /** Claim (or update) `key` with the outcome of its write. Bounded: past {@link NOTIFIED_KEYS_MAX} the
+     *  oldest-inserted key is dropped (F3; an update keeps the original insertion slot — good enough for a
+     *  pathology cap). */
     set(key, written) {
         this.byKey.set(key, written);
         while (this.byKey.size > NOTIFIED_KEYS_MAX) {
@@ -27,15 +126,27 @@ export class NotifiedKeys {
         }
     }
 }
+/** 家族前缀 = 折叠键只剥 `#seq` 分量(仅当尾是纯数字才剥)。新元组键的 JSON 段恒以 `"]` 结尾、taskId/
+ *  status 里天然的 # 被 JSON 引号包住,`#digits` 尾无歧义=必是 seq;旧格式遗留行(`域:task:status#seq`)
+ *  与 workflow_complete 的裸 runId 键同一语义原样兼容。 */
 export function foldKeyFamily(runId) {
     const i = runId.lastIndexOf("#");
     return i > 0 && /^\d+$/.test(runId.slice(i + 1)) ? runId.slice(0, i) : runId;
 }
+/** Collision-safe (session, runId) fence key — ids are caller-influenced strings, so a plain separator could
+ *  be forged into a cross-pair collision; JSON tuple encoding cannot. */
 const servedKey = (sessionId, runId) => JSON.stringify([sessionId, runId]);
+/** In-memory inbox — the parity oracle + the ephemeral opt-out (WORKFLOW_RUN_STORE=memory). No persistence:
+ *  a restart forgets undelivered completions (the poll floor covers them). */
 export class InMemoryWorkflowCompletionInbox {
     onWarn;
     bySession = new Map();
+    /** sessionId → {at, owner}: purge stamps; enqueues within {@link PURGE_FENCE_MS} for the SAME owner are
+     *  refused. Swept on BOTH enqueue and purge (a purge-heavy, enqueue-quiet process must not accumulate
+     *  stamps unboundedly — review). */
     purgedAt = new Map();
+    /** servedKey(sessionId, runId) → stamp: terminal-poll-served fences; an enqueue for the pair within
+     *  {@link SERVED_FENCE_MS} is refused (the poll already told the model). Swept alongside the purge fence. */
     servedAt = new Map();
     constructor(onWarn) {
         this.onWarn = onWarn;
@@ -48,9 +159,16 @@ export class InMemoryWorkflowCompletionInbox {
             if (now - at > SERVED_FENCE_MS)
                 this.servedAt.delete(key);
     }
+    /** True (and warns) when `entry`'s session was purged within the fence window AND the fence applies to its
+     *  owner: same owner as the purged session (a late completion of the DELETED session) — or an owner-less
+     *  fence (caller couldn't say), conservative. A DIFFERENT owner = a new legitimate claimant of a reused
+     *  sessionId → not fenced (their push must not be starved; the drain-side owner gate stays the real
+     *  tenancy boundary either way). */
     purgeFenced(entry) {
         const now = Date.now();
         this.sweepFence(now);
+        // Served fence FIRST (per-runId, so it can't shadow the purge fence's owner semantics): this exact
+        // completion already reached the model through its own poll — enqueueing it would be the double delivery.
         if (this.servedAt.has(servedKey(entry.sessionId, entry.runId)) || this.servedAt.has(servedKey(entry.sessionId, foldKeyFamily(entry.runId)))) {
             this.onWarn?.("workflow_completion_enqueue_after_poll_served", { sessionId: entry.sessionId, runId: entry.runId });
             return true;
@@ -59,14 +177,20 @@ export class InMemoryWorkflowCompletionInbox {
         if (st === undefined)
             return false;
         if (st.owner !== undefined && entry.owner !== st.owner)
-            return false;
+            return false; // new claimant, different owner → pass
         this.onWarn?.("workflow_completion_enqueue_after_purge", { sessionId: entry.sessionId, runId: entry.runId });
         return true;
     }
+    /** Fence FIRST (an enqueue racing the poll is refused even mid-call), then drop any already-pending
+     *  entry via `ack` — the durable subclass inherits this and gets a durable ack for free. */
     async markTerminalServed(sessionId, runId) {
         this.sweepFence(Date.now());
         this.servedAt.set(servedKey(sessionId, runId), Date.now());
         await this.ack(sessionId, runId);
+        // 家族 ack(design/144 消费批):fleet 常开流帧不带 seq,而 1.283 起终态 park 是 seq 键——精确 ack
+        // 必 miss ⇒ 下次开流 drain 二次注入模型。传入 runId 视作家族前缀,清掉同 (域,taskId,status) 的全部
+        // seq 键成员。取舍如实记:同家族的更早 Monitor 批可能被连带清(终态已送达后丢进度行,低害),
+        // 换取每个 bg 终态必然双投的消除;workflow_complete 键无 # 尾,家族=自身,行为不变。
         const q = this.bySession.get(sessionId);
         if (q) {
             for (const key of [...q.keys()]) {
@@ -76,14 +200,16 @@ export class InMemoryWorkflowCompletionInbox {
         }
     }
     stampPurge(sessionId, owner) {
-        this.sweepFence(Date.now());
+        this.sweepFence(Date.now()); // bound the map on the purge side too (enqueue-quiet processes)
         this.purgedAt.set(sessionId, { at: Date.now(), owner });
     }
+    /** Fold one entry into the map. `warn` is false during ledger replay (a historical overflow must not re-log
+     *  on every boot) and true on a live enqueue. */
     applyEnqueue(entry, warn) {
         let q = this.bySession.get(entry.sessionId);
         if (!q)
             this.bySession.set(entry.sessionId, (q = new Map()));
-        q.delete(entry.runId);
+        q.delete(entry.runId); // idempotent + re-insert at the tail (Map preserves insertion order → oldest-first)
         q.set(entry.runId, entry);
         while (q.size > MAX_PENDING_PER_SESSION) {
             const oldest = q.keys().next().value;
@@ -94,13 +220,16 @@ export class InMemoryWorkflowCompletionInbox {
     }
     async enqueue(entry) {
         if (this.purgeFenced(entry))
-            return;
+            return; // late completion of a DELETED session → drop (poll floor covers)
         this.applyEnqueue(entry, true);
     }
     async pending(sessionId) {
         const q = this.bySession.get(sessionId);
         if (!q || q.size === 0)
             return [];
+        // The served fence is armed SYNCHRONOUSLY in markTerminalServed (before its async ack
+        // lands), so filtering here closes the same-process race where a stream-open drain reads a still-pending
+        // entry while the ack write is in flight — the drain must never re-deliver what the fence says was served.
         return [...q.values()].filter((e) => !this.servedAt.has(servedKey(e.sessionId, e.runId)) && !this.servedAt.has(servedKey(e.sessionId, foldKeyFamily(e.runId))));
     }
     async ack(sessionId, runId) {
@@ -116,6 +245,8 @@ export class InMemoryWorkflowCompletionInbox {
         this.stampPurge(sessionId, purgedOwner);
     }
 }
+/** File-backed crash-safe inbox (the durable default — a background workflow's completion survives a replica
+ *  restart, the prerequisite for pushing it to a session that reconnects after the crash). */
 export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox {
     fsyncEnabled;
     dir;
@@ -126,10 +257,12 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
         super(onWarn);
         this.fsyncEnabled = fsyncEnabled;
         this.dir = join(root, "workflow-completion-inbox");
+        // 0o700 dir + 0o600 ledger: entries carry the completion summary (may reference tenant work) + sessionId +
+        // owner — owner-only, parity with the notify-journal's identity-data posture.
         mkdirSync(this.dir, { recursive: true, mode: 0o700 });
         this.ledgerPath = join(this.dir, "inbox.jsonl");
         this.replay();
-        this.compact();
+        this.compact(); // rewrite the ledger to just the live pending set → tombstones/evicted lines don't survive restarts
     }
     replay() {
         if (!existsSync(this.ledgerPath))
@@ -143,7 +276,7 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
                 rec = JSON.parse(line);
             }
             catch {
-                continue;
+                continue; // torn/partial trailing line (crash mid-append) — uncommitted, skip
             }
             if (rec.op === "enqueue" && rec.entry?.sessionId && rec.entry.runId)
                 this.applyEnqueue(rec.entry, false);
@@ -151,29 +284,40 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
                 const q = this.bySession.get(rec.sessionId);
                 q?.delete(rec.runId);
                 if (q && q.size === 0)
-                    this.bySession.delete(rec.sessionId);
+                    this.bySession.delete(rec.sessionId); // mirror the live ack — replay is a strict fold
             }
             else if (rec.op === "drain" && rec.sessionId)
-                this.bySession.delete(rec.sessionId);
+                this.bySession.delete(rec.sessionId); // purge today; pre-1.80 drain lines too
         }
     }
     commit(rec) {
         if (this.fd === undefined)
-            this.fd = openSync(this.ledgerPath, "a", 0o600);
+            this.fd = openSync(this.ledgerPath, "a", 0o600); // owner-only (identity/work data)
         writeSync(this.fd, `${JSON.stringify(rec)}\n`);
         if (this.fsyncEnabled)
-            fsyncSync(this.fd);
+            fsyncSync(this.fd); // durable BEFORE the in-memory state the caller observes
         this.appendsSinceCompact++;
     }
+    /** Compact iff we've appended enough since the last one. MUST be called AFTER the in-memory mutation the
+     *  triggering commit records — compact() rewrites from `bySession`, so a compact fired BEFORE the caller
+     *  applied its enqueue/delete would rewrite a stale snapshot and lose that record. */
     maybeCompact() {
         if (this.appendsSinceCompact >= COMPACT_EVERY)
             this.compact();
     }
+    /** Rewrite the ledger from the authoritative in-memory state — one `enqueue` record per LIVE pending entry —
+     *  dropping every accumulated drain-tombstone + evicted/drained line. Atomic (temp + rename) so a crash
+     *  mid-compact leaves the old ledger intact. */
     compact() {
         if (this.fd !== undefined) {
             closeSync(this.fd);
             this.fd = undefined;
         }
+        // tmp 名带 pid(2026-07-28 核查修):两个进程共用同一数据根时(例:两个 memory 形引擎共用一个
+        // HOME——multi-instance 共享目录本不受支持,但 memory 形用户合理预期「无盘无锁」,却默默共享
+        // `~/.ai-agent`),固定 `.tmp` 名会互相 rename 走对方的 staging ⇒ 对方 renameSync ENOENT,而 compact
+        // 在 constructor 里同步跑 = **boot fatal**(真机复现:两只引擎并发 boot 恢复期)。带 pid 后各进程
+        // staging 独立,rename 原子替换回落到 last-writer-wins(账本内容级共享仍不支持,但不再拒启)。
         const tmp = `${this.ledgerPath}.tmp.${process.pid}`;
         const lines = [];
         for (const q of this.bySession.values())
@@ -189,7 +333,9 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
         finally {
             closeSync(tfd);
         }
-        renameSync(tmp, this.ledgerPath);
+        renameSync(tmp, this.ledgerPath); // atomic replace of the ledger
+        // fsync the DIRECTORY so the rename (a namespace change) is itself crash-durable on POSIX/macOS, not just
+        // the file contents. Best-effort: a dir that can't be opened for fsync (rare) is skipped.
         if (this.fsyncEnabled) {
             try {
                 const dfd = openSync(this.dir, "r");
@@ -201,35 +347,40 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
                 }
             }
             catch {
+                /* dir fsync unsupported/failed — the rename is still namespace-atomic; skip */
             }
         }
         this.appendsSinceCompact = 0;
     }
     async enqueue(entry) {
         if (this.purgeFenced(entry))
-            return;
+            return; // late completion of a DELETED session → never re-committed to the ledger
         this.commit({ op: "enqueue", entry });
         this.applyEnqueue(entry, true);
-        this.maybeCompact();
+        this.maybeCompact(); // AFTER applyEnqueue → compact's rewrite includes this entry
     }
+    // `pending` is the inherited non-destructive read — deliberately NO ledger write (phase 1 of two-phase
+    // delivery leaves the durable state untouched; only the per-entry `ack` mutates it, so a crash/failed
+    // frame-write between the two re-delivers on the next leg instead of silently eating the completion).
     async ack(sessionId, runId) {
         const q = this.bySession.get(sessionId);
         if (!q?.has(runId))
-            return;
-        this.commit({ op: "ack", sessionId, runId });
+            return; // idempotent — a raced double-ack (two legs) writes ONE tombstone
+        this.commit({ op: "ack", sessionId, runId }); // durable BEFORE the in-memory delete (deliver-then-ack)
         q.delete(runId);
         if (q.size === 0)
             this.bySession.delete(sessionId);
-        this.maybeCompact();
+        this.maybeCompact(); // AFTER delete → compact's rewrite reflects the ack (no resurrection)
     }
     async purge(sessionId, purgedOwner) {
-        this.stampPurge(sessionId, purgedOwner);
+        this.stampPurge(sessionId, purgedOwner); // fence FIRST — an enqueue racing the purge is refused even mid-purge
         if (!this.bySession.has(sessionId))
             return;
-        this.commit({ op: "drain", sessionId });
+        this.commit({ op: "drain", sessionId }); // a purge clears the whole session (session-level tombstone)
         this.bySession.delete(sessionId);
-        this.maybeCompact();
+        this.maybeCompact(); // AFTER delete → compact's rewrite reflects the purge
     }
+    /** Close the ledger fd (shutdown). */
     close() {
         if (this.fd !== undefined) {
             closeSync(this.fd);
@@ -237,14 +388,41 @@ export class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox
         }
     }
 }
-export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPrincipal, emit, diag) {
+/**
+ * P1 ①② delivery half, TWO-PHASE since 1.80: read the session's pending completions, emit
+ * one `workflow_complete` out-of-band frame per entry, and `ack` (remove) each entry only AFTER its emit
+ * SUCCEEDED — a failed frame write (dead socket / durable-append error) leaves the entry pending, so the next
+ * leg re-delivers instead of silently eating it (the 1.77-review "drained-but-append-failed" window, closed).
+ * Called at STREAM-OPEN of EVERY run leg (the sync `POST /v1/runs` SSE leg emits a live frame; the bg + resume
+ * legs append a durable `workflow_complete` event their tailing client replays). Best-effort throughout (the
+ * deterministic `WorkflowStatus` poll is the floor); at-least-once — the shell dedups by runId (two legs racing
+ * the same session may double-emit; same contract).
+ *
+ * 🔒 Tenancy (defence-in-depth over the authorizer's sessionId→owner gate): only entries whose stamped
+ * `owner` matches `callerPrincipal` are EMITTED — a session deleted-then-reclaimed by a different tenant
+ * (which rotates the sessionId→owner binding) can't surface the prior owner's completions. `owner: null`
+ * (single-user turnkey) has no tenancy boundary → always emitted. A non-matching entry is a DELIBERATE drop —
+ * acked (the session is gone/reclaimed for its original owner; the poll floor is their fallback), so it never
+ * wedges the queue.
+ */
+export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPrincipal, emit, 
+/** Emit-TARGET diagnostics — WHICH leg drained (route) onto WHAT kind of connection
+ *  (live SSE write vs durable event-log append), plus the enqueue→emit lag, so a "workflow completed but the
+ *  shell only saw it on the next manual turn" report can be pinned to the leg that finally carried the frame
+ *  (the push is stream-open-driven by design — a session with NO open leg has no push path until its next
+ *  leg; the lag makes that visible instead of a mystery). Info-level, one line per delivered frame. */
+diag) {
     if (!inbox || !sessionId)
         return;
+    // Diagnostics must never influence delivery (1.108 review): a throwing log sink inside the try would
+    // misroute an already-delivered-and-acked frame into the emit_failed line — a lie in the very diagnostics
+    // this sink exists to provide. Swallow here; the drain semantics stay byte-identical with diag absent.
     const dlog = (msg, meta) => {
         try {
             diag?.log(msg, meta);
         }
         catch {
+            /* never let diagnostics fault the drain */
         }
     };
     let entries;
@@ -252,28 +430,34 @@ export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPri
         entries = await inbox.pending(sessionId);
     }
     catch {
-        return;
+        return; // best-effort push — the model can always fall back to the WorkflowStatus poll
     }
     for (const e of entries) {
         try {
             if (e.owner !== null && e.owner !== callerPrincipal) {
-                await inbox.ack(sessionId, e.runId);
+                await inbox.ack(sessionId, e.runId); // 🔒 not this caller's completion → deliberate drop (ack, never emit)
                 dlog("workflow_complete_dropped_owner_mismatch", { route: diag?.route, sessionId, runId: e.runId });
                 continue;
             }
             if (e.kind === "task_notification") {
+                // A background subagent/bash completion parked while the session was idle — drain it as the
+                // SAME frame family the live legs emit (`task_notification`, task_id keyed), so the shell's existing
+                // renderer + dedup consume it unchanged. Extras (task_type/result/…) were bounded+redacted at enqueue.
                 let extras = {};
                 try {
                     extras = e.payload ? JSON.parse(e.payload) : {};
                 }
                 catch {
+                    /* a torn payload degrades to the summary-only frame */
                 }
+                // `injected: false` AFTER the extras spread:恒量判别位([1818]§四 (b)案,与 project.ts live 投影
+                // 同义)——parked 通知更如实:park 发生恰因 leg 已死、core 的注入无处可去。
                 await emit({ type: "task_notification", task_id: e.runId, status: e.status, summary: e.summary, ...extras, injected: false });
             }
             else {
                 await emit({ type: "workflow_complete", runId: e.runId, status: e.status, summary: e.summary });
             }
-            await inbox.ack(sessionId, e.runId);
+            await inbox.ack(sessionId, e.runId); // phase 2: the frame durably landed → remove
             dlog("workflow_complete_emitted", {
                 route: diag?.route,
                 connection: diag?.connection,
@@ -284,22 +468,51 @@ export async function emitPendingWorkflowCompletions(inbox, sessionId, callerPri
             });
         }
         catch (err) {
+            // emit failed → NOT acked → re-delivered on the next leg (at-least-once; a dead socket / failed append
+            // must not fault the turn). An ack failure after a successful emit re-delivers too — same contract.
             dlog("workflow_complete_emit_failed", { route: diag?.route, connection: diag?.connection, sessionId, runId: e.runId, err: err instanceof Error ? err.message : String(err) });
         }
     }
 }
-export function taskNotificationInboxEntry(sessionId, owner, n, enqueuedAt, parentTaskId) {
+/**
+ * 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 function taskNotificationInboxEntry(sessionId, owner, n, enqueuedAt, 
+/** 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. */
+parentTaskId) {
     const cap = (s, max) => (s.length > max ? `${s.slice(0, max)}…[+${s.length - max} chars]` : s);
     const extras = {
         task_type: n.task_type,
         ...(parentTaskId ? { parentTaskId } : {}),
+        // core 1.238: the payload's own sessionId — the stable a*↔local-uuid cross-system anchor
+        // (same handle TaskResult.sessionId/fleet rows carry). Optional (bash lane has none).
         ...(n.sessionId ? { sessionId: n.sessionId } : {}),
         ...(n.toolUseId ? { toolUseId: n.toolUseId } : {}),
-        ...(n.status !== "completed" && n.status !== "failed" ? { status: n.status } : {}),
+        ...(n.status !== "completed" && n.status !== "failed" ? { status: n.status } : {}), // original rides through
+        // core drain 案: the Monitor/stoppedBy fields must survive the PARK too, or a drained event batch
+        // arrives with no dedup discriminator (`seq` — core's taskNotificationDedupKey folds it in), no line text,
+        // and no stop attribution. Same trust posture as the live projection (project.ts): seq/stoppedBy verbatim
+        // (core counter / open enum), lines = watched-process stdout → redact + cap each line.
         ...(n.seq !== undefined ? { seq: n.seq } : {}),
+        // 对抗评审 2026-07-11:redact BEFORE cap — capping first could bisect a secret so its residue no longer
+        // matches any redact pattern (a half-token is still a usable prefix). Order: redact, then bound.
         ...(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) } : {}),
+        ...(n.diagnostics !== undefined ? { diagnostics: cap(n.diagnostics, 4_000) } : {}), // [1412] 诊断槽(bounded;引擎值单源,park 原样过)
+        // (core 1.262.0 残局字段的 PARK 半场——live 腿 1.154.0 已放行,但「用户杀 bg 子代」的
+        // 主动线恰是 between-turns,通知落这里):与 project.ts 同一 trust posture——recentSteps.tool verbatim,
+        // target/outcome UNTRUSTED(命令行/工具输出首行可为 secret 形)→ redact+cap;editedFiles.path → redact+cap
+        // (attachedFiles 姿势),edits 数字 verbatim;resumable boolean verbatim。字段挑取绝不 spread;数组防御
+        // 截断(core 上游本就 bound ≤10 步——slice 是入库前的双保险)。
         ...(n.recentSteps !== undefined
             ? { recentSteps: n.recentSteps.slice(0, 10).map((s) => ({ tool: s.tool, target: cap(redactSecrets(s.target), 512), outcome: cap(redactSecrets(s.outcome), 512) })) }
             : {}),
@@ -313,14 +526,43 @@ export function taskNotificationInboxEntry(sessionId, owner, n, enqueuedAt, pare
     return {
         sessionId,
         owner,
+        // 对抗评审 2026-07-11(MED):the inbox key is REPLACE-on-runId (the workflow_complete contract) — keying a
+        // task_notification by the bare task_id COLLAPSES multiple between-turns notifications of the same bg task
+        // (a Monitor event batch, then the killed terminal: the terminal REPLACED the batch, drain emitted 1 of 2).
+        // Fold `seq` into the key (core's own taskNotificationDedupKey folds seq for exactly this reason); the frame's
+        // task_id comes from the extras override below, so the wire shape is unchanged. Same-key retries still dedup.
+        // design/144 §4 键升级:(域,taskId,status,seq?)——status 进键且保 RAW(修1:归一曾让同 id 的
+        // event/cancelled 两条 external 通知互吞),external 分域([769]①),seq 折入(逐周期)。
+        // wire 形状不变(task_id 从 extras override 恢复);存储 status 列(下一行)仍归一双终态,不受键影响。
         runId: taskNotificationFoldKey(n),
         status: n.status === "completed" ? "completed" : "failed",
         summary: cap(redactSecrets(n.summary ?? ""), 4000),
         enqueuedAt,
         kind: "task_notification",
-        payload: JSON.stringify({ ...extras, task_id: n.task_id }),
+        payload: JSON.stringify({ ...extras, task_id: n.task_id }), // task_id rides extras → drain's spread restores it over the keyed runId
     };
 }
+/**
+ * Resolve WHERE a workflow completion routes (core 1.208): the SESSION comes straight off
+ * `originatingSessionId` (the Runner closes over it at RunWorkflow mount — lookup-free). The OWNER comes from,
+ * in order:
+ *  1. the originating RUN ROW's owner (`getRun(sourceTaskId)`, 1.75) — immutable, stamped at submit. Only the
+ *     BG leg has a run-row `sourceTaskId` though: the sync + resume legs deliberately leave `spec.taskId` unset
+ *     (subagent nesting), so core derives `sourceTaskId = sessionId` and this lookup MISSES for them (review
+ *     review, 1.78) — which under the old rule silently killed the multi-tenant push for every sync-leg workflow;
+ *  2. the payload's `principal` — core threads `spec.principal`, which in THIS service is ALWAYS the VERIFIED
+ *     identity (the 1.55 F-fix invariant, main.ts: gated door = BFF-verified header, direct door = JWT `sub`,
+ *     never the spoofable header; core 1.187 hardened the `TaskSpec.principal` contract to exactly this).
+ *     Captured at SPAWN time → immutable, no delete-then-reclaim window. This is also the same value core's own
+ *     workflow scope guard (`canAccessWorkflowRun`) keys off;
+ *  3. neither → single-user stamps `owner: null` (no tenancy boundary); multi-tenant (`requirePrincipal`)
+ *     returns undefined = DROP fail-closed (an unverifiable owner must not ride the reclaim gate; the
+ *     `WorkflowStatus` poll floor covers). Returns undefined when there is no route at all.
+ * The `getRun` lookup also carries the session FALLBACK for a crash-RECOVERY notify payload that lacks
+ * `originatingSessionId` — since core 1.210 the durable `WorkflowRun` records it and the recovery
+ * re-derivation threads it through (workflow-notify-journal), so this fallback covers only pre-1.210 rows
+ * (or a writer that omitted it), not the recovery path wholesale.
+ */
 export async function resolveCompletionRoute(p, getRun, requirePrincipal) {
     let sessionId = p.originatingSessionId;
     let owner;
@@ -329,23 +571,31 @@ export async function resolveCompletionRoute(p, getRun, requirePrincipal) {
             const originating = await getRun(p.sourceTaskId);
             if (originating) {
                 sessionId ??= originating.sessionId ?? undefined;
-                owner = originating.owner ?? null;
+                owner = originating.owner ?? null; // the run row's owner — stamped at submit, immutable
             }
         }
         catch {
+            // lookup outage: fall through — the session may still route via the payload; owner resolves below
         }
     }
     if (!sessionId)
-        return undefined;
+        return undefined; // no route → poll floor
     if (owner === undefined && p.principal !== undefined)
-        owner = p.principal;
+        owner = p.principal; // VERIFIED spec.principal (see doc #2)
     if (owner === undefined) {
         if (requirePrincipal)
-            return undefined;
-        owner = null;
+            return undefined; // multi-tenant + no verifiable owner → fail-closed (poll floor)
+        owner = null; // single-user turnkey: no tenancy boundary
     }
     return { sessionId, owner };
 }
+/**
+ * core 1.232 — resolve WHICH session's inbox entry a poll-served ack targets: the payload's
+ * `originatingSessionId` directly (core threads it on `ackServed`), else the originating run row via
+ * `sourceTaskId` (mirrors {@link resolveCompletionRoute}'s session half — same fallback, same reason:
+ * older runs may predate the lookup-free field). Returns undefined when there is no attribution — the
+ * entry stays pending (at-least-once; the shell's own dedup covers a rare duplicate).
+ */
 export async function resolveServedSession(p, getRun) {
     if (p.originatingSessionId)
         return p.originatingSessionId;
@@ -354,6 +604,7 @@ export async function resolveServedSession(p, getRun) {
             return (await getRun(p.sourceTaskId))?.sessionId ?? undefined;
         }
         catch {
+            /* lookup outage → no attribution; the poll floor + shell dedup cover */
         }
     }
     return undefined;