@sema-agent/server 1.323.0 → 2.0.1

package/dist/orchestration/workflow-agent-steer.js

@@ -1,9 +1,47 @@
 import { untrustedEgressForHuman } from "@sema-agent/core";
+/**
+ * SVC-5 (design/97 CORE-5 #6) — the SERVICE-side transport + redaction trust-gate for
+ * STEERING a still-running workflow agent (`ctx.agentStream`). Two concerns live here so the steer-in path
+ * cannot reopen the hole in scattered places:
+ *   1. A process-local REGISTRY of the live {@link WorkflowAgentHandle}s on THIS replica — the only steerable
+ *      surface (`handle.steer` is an in-memory bridge to the running `TaskStream`, replica-local like
+ *      `steerableRuns` / `preemptableRuns`). Keyed by `runId label` (a label is unique within a run —
+ *      core mints `agent-N` when the caller omits one, so the pair addresses exactly one running agent).
+ *   2. The steer-in REDACTION gate ({@link redactSteerIn}) — a human's / leader's steer content is UNTRUSTED
+ *      EVEN THOUGH it carries operator authority on the wire: it must not smuggle host internals to the worker
+ *      (a leaked baseUrl/token/path in a copy-pasted steer) nor pose as authority to it. We apply core's
+ *      `untrustedEgressForHuman` (redact host leaks + size-bound + fence) BEFORE the content reaches
+ *      `handle.steer`, which fences AGAIN inside its trusted marker framing — defense in depth, two independent
+ *      owners of the boundary.
+ *
+ * 🔴 HANDLE-VISIBILITY SEAM (the SVC-5 design blocker, reported to clay/core). Core returns a
+ * {@link WorkflowAgentHandle} ONLY from `WorkflowRunContext.agentStream`, and — by a deliberate security
+ * invariant (workflow-script-runner.d.ts) — the host `WorkflowRunContext` STRUCTURALLY
+ * never enters the script runner: the LLM-authored workflow runs against the flat, sterile
+ * `WorkflowPrimitives` record, which carries `agent` but NOT `agentStream`. The service launches workflows
+ * EXCLUSIVELY through core's `run_workflow` tool → `WorkflowScriptRunner` → `WorkflowPrimitives`, so no code in
+ * the service process ever holds a handle to register. This module is therefore the COMPLETE, REAL transport
+ * (registry + redaction + auth contract) the service WOULD register into the instant core exposes the handle to
+ * the deployment — e.g. a `RunWorkflowToolDeps.onAgentStream(handle)` lifecycle callback, or a steerable-handle
+ * sink on the run_workflow tool. Until then the HTTP route correctly returns `steering.not_running` (the
+ * registry is genuinely empty — an honest seam, never a silent drop or a fake-live). It is NOT a stopgap: the
+ * registry/redaction/auth are production-real and what the populated path uses unchanged.
+ */
+/** The composite key NUL-joining `runId` + `label` (a label is unique within a workflow run). NUL can't appear
+ *  in either part, so the join is unambiguous. */
 function handleKey(runId, label) {
     return `${runId}\u0000${label}`;
 }
+/** A process-local registry of the steerable workflow-agent handles live on THIS replica. Mirrors the
+ *  `steerableRuns` / `preemptableRuns` pattern (a live in-memory handle is replica-local — a cross-replica steer
+ *  is a structured 409, never a silent drop). Stores a LIST per (runId,label): core does not enforce label
+ *  uniqueness, so a duplicate-label collision must NOT silently last-writer-wins (that would steer the WRONG
+ *  agent + strand the sibling) — {@link resolve} reports the count so the route can 409-on-ambiguous instead. */
 export class WorkflowAgentRegistry {
     handles = new Map();
+    /** Register a handle when its `agentStream` starts on this replica. Returns an unregister thunk to call when
+     *  the agent settles (keeps the map from leaking). APPENDS (does not overwrite) so a duplicate-label sibling is
+     *  also tracked → {@link resolve} sees count>1 and the route refuses rather than steering an arbitrary one. */
     register(handle) {
         const key = handleKey(handle.runId, handle.label);
         const list = this.handles.get(key);
@@ -15,18 +53,22 @@ export class WorkflowAgentRegistry {
             const cur = this.handles.get(key);
             if (!cur)
                 return;
-            const i = cur.indexOf(handle);
+            const i = cur.indexOf(handle); // remove THIS handle only — a sibling's unregister must not evict it
             if (i >= 0)
                 cur.splice(i, 1);
             if (cur.length === 0)
                 this.handles.delete(key);
         };
     }
+    /** Resolve `runId`+`label` to its UNIQUE live handle on this replica. count=0 → not here (terminal /
+     *  cross-replica); count=1 → `handle` set; count>1 → ambiguous (`handle` undefined → the route 409s rather
+     *  than steering an arbitrary one of the colliding same-label agents). */
     resolve(runId, label) {
         const list = this.handles.get(handleKey(runId, label));
         const count = list ? list.length : 0;
         return count === 1 ? { handle: list[0], count } : { count };
     }
+    /** Total live handles (test/observability). */
     get size() {
         let n = 0;
         for (const list of this.handles.values())
@@ -34,8 +76,45 @@ export class WorkflowAgentRegistry {
         return n;
     }
 }
+/** Max steer-in length fed to a worker (chars). A steer is a short redirection, not a payload; core's
+ *  `untrustedEgressForHuman` bounds + truncates beyond this.
+ *
+ *  ⚠️ 纠正(2026-07-26,core 1.414 + 亲测):这里原本写的是「truncates with an **honest marker**」,现在只有
+ *  一半成立 —— 实测(`test/svc5-steer-live.test.ts` 里已钉):
+ *   · **「被截断过」仍有信号**:超界时正文段尾出现 `…`(未超界时不出现)⇒ 消费方能判断"这不是全文";
+ *   · **「截了多少」不再披露**:`[+N chars]` 在**所有**档位都没有了(实测 +1 / +10 / +100 / +5000 / +50000
+ *     全部无披露,输出长度恒 4103)。所以一个超出 5 万字符的输入与只超 1 个字符的输入,**外观完全相同**。
+ *  ⚠️ core [1707]⑤ 的措辞是「**刚过界**的输入现在是裸 `…` 结尾」,而实测是**全档位**都没有披露 —— 范围比
+ *  它描述的宽。已带实测数据上黑板问 core 这是否是有意的(可能只是描述省略,也可能是它没注意到)。
+ *  在得到答复前**不改行为**:core 的截断器是它那侧的安全件,server 不该自己在外面补一层"+N chars"去顶
+ *  ——那会变成两处各说一套。 */
 export const STEER_IN_MAX_CHARS = 4_000;
+/**
+ * **入参**上限(与 {@link STEER_IN_MAX_CHARS} 是两件事:那个限的是**输出**,这个限的是**请求带进来的**)。
+ *
+ * ── 为什么需要它 ───────────────────────────────────────────────────────────────────────────────
+ * 脱敏门是**同步**函数,烧的是**事件循环** ⇒ 一次大 steer 卡住的是**整个副本**,不只是那个请求。
+ * 此前这里没有上限:`body.content` 只校验类型与非空,而 JSON 请求体上限是 8 MiB。
+ *
+ * ── 数是怎么定的(实测,不是拍的)────────────────────────────────────────────────────────────────
+ * core 1.421.0 起该函数对输入是**线性**的(此前对「最长不间断词字符段」二次,已修)。
+ * 本机实测最坏形状(纯词字符段):64 KiB ≈ 17ms ⇒ **256 KiB ≈ 68ms**、8 MiB ≈ 2.2s。
+ * ⇒ 取 **256 KiB**:最坏一拍 ~70ms(可接受的事件循环占用),而它是输出上限的 **64 倍** ——
+ *   任何正当的粘贴都装得下,而超出部分**本来就会被丢弃**(只保留 4000 字符 + 一个"丢了多少"的披露)。
+ *
+ * ── 为什么是**拒**而不是**服务端先截** ──────────────────────────────────────────────────────────
+ * 先截会让 core 的 `[+N chars]` 披露**低报**(N 会变成相对截断后输入的),
+ * 而"诚实标记不得低报"是本仓另一条钉守着的性质。**为一个已经不紧迫的成本去改一条正确性性质,不划算。**
+ * ⇒ 拒 + 在错误里说清上限,调用方自己决定发什么。
+ */
 export const STEER_IN_MAX_REQUEST_CHARS = 256 * 1024;
+/**
+ * The steer-in REDACTION gate (SVC-5 信任门). Treat the human/leader steer content as UNTRUSTED before it
+ * reaches the worker: redact host-internal leaks (URLs / tokens / named secrets / absolute paths), size-bound,
+ * and FENCE it so it can't pose as authority / forge a `</system-reminder>`. `label` tags the fenced block for
+ * the worker's reader. This is the service's half of the depth — `handle.steer` fences again inside its trusted
+ * marker framing.
+ */
 export function redactSteerIn(content, label) {
     return untrustedEgressForHuman(content, { label, max: STEER_IN_MAX_CHARS });
 }

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

@@ -1,59 +1,173 @@
+/** One pending completion, scoped to the session that must be told about it. `summary` is ALREADY
+ *  redacted + length-bounded by core's notifier seam (see {@link WorkflowCompletionPayload}). */
 export interface WorkflowCompletionInboxEntry {
     sessionId: string;
+    /** The originating run's owner (verified principal), or null in the single-user turnkey posture. Gates
+     *  emission at drain time (defence-in-depth over the sessionId→owner binding a delete/reclaim can rotate). */
     owner: string | null;
     runId: string;
     status: "completed" | "failed";
     summary: string;
     enqueuedAt: number;
+    /** The frame family this entry drains as. Absent (every pre-1.109 row) = the original
+     *  `workflow_complete`. `task_notification` = a background subagent/bash completion observed while the
+     *  originating leg was IDLE (core's in-process injection had no harness to steer — the durable half
+     *  is the deployment's job). `runId` then holds the core task_id (disjoint id spaces). */
     kind?: "workflow_complete" | "task_notification";
+    /** The task_notification extras (JSON: {task_type, toolUseId?, result?, output_file?}) — bounded +
+     *  redacted AT ENQUEUE (the store carries only egress-safe bytes). Absent on workflow_complete entries. */
     payload?: string;
 }
+/** Session-keyed queue of finished-workflow completions awaiting a push to the originating session.
+ *  Two-phase delivery (1.80, closes the 1.77-review "drained-but-append-failed" at-most-once window): `pending`
+ *  READS without removing; the consumer removes each entry via `ack` only AFTER its frame durably landed (or it
+ *  decided a deliberate drop, e.g. an owner mismatch). A crash/failed write between pending and ack re-delivers
+ *  on the next leg (at-least-once; the shell dedups by runId). Two legs racing the same session may double-emit —
+ *  same at-least-once contract, same dedup. */
 export interface WorkflowCompletionInbox {
+    /** Record a completion for `entry.sessionId`. Idempotent on `runId` within a session (a re-delivered
+     *  at-least-once notify replaces, never duplicates). Dropped (with a warn) when the session was PURGED within
+     *  the fence window — a late completion racing a session delete must not resurrect as a live ledger entry
+     *  (1.78-review purge-vs-enqueue hygiene). */
     enqueue(entry: WorkflowCompletionInboxEntry): Promise<void>;
+    /** READ every pending completion for `sessionId` (oldest-first) WITHOUT removing — phase 1 of delivery. */
     pending(sessionId: string): Promise<WorkflowCompletionInboxEntry[]>;
+    /** Remove ONE delivered (or deliberately dropped) completion — phase 2. Idempotent on an unknown runId. */
     ack(sessionId: string, runId: string): Promise<void>;
+    /** Drop every pending completion for `sessionId` without emitting (called on session delete) + arm the
+     *  enqueue fence for {@link PURGE_FENCE_MS}. `purgedOwner` (the deleted session's owner) scopes the fence:
+     *  a completion enqueued for a DIFFERENT owner — a new tenant who legitimately re-claimed the sessionId
+     *  within the window (sessionIds are caller-chosen; reuse is a supported flow) — is NOT fenced (review:
+     *  the ownerless fence silently starved the new claimant's push). Omitted `purgedOwner` = conservative
+     *  fence-all (an ownerless caller can't distinguish). */
     purge(sessionId: string, purgedOwner?: string | null): Promise<void>;
+    /** The originating session OBSERVED this run's terminal state through a model-facing poll
+     *  (core 1.232 `WorkflowCompletionNotifier.ackServed` fires this), so the push would be
+     *  a pure duplicate ("poll-then-also-notify" double delivery: the model burns turns dismissing a completion
+     *  it already summarized). Drops the pending entry (a deliberate ack) AND arms a {@link SERVED_FENCE_MS}
+     *  enqueue fence for this (session, runId) so a LATE-arriving notify (the notifier races the poll) is
+     *  dropped too. Fence is in-memory only — a crash between poll and notify re-delivers (at-least-once; the
+     *  shell's own runId dedup + the model tolerate it), mirroring the purge fence's restart posture. */
     markTerminalServed(sessionId: string, runId: string): Promise<void>;
 }
+/** 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 declare 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 declare 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 declare const PURGE_FENCE_MS: number;
+/** 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 declare const SERVED_FENCE_MS: number;
+/** 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 declare function taskNotificationFoldKey(n: {
     task_type?: string;
     task_id: string;
     status: string;
     seq?: number;
 }): string;
+/** 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 declare function taskNotificationStreamKey(n: {
     task_type?: string;
     task_id: string;
     status: string;
     seq?: number;
 }): string;
+/** Per-leg notified-key ledger cap (codex 1.189 前双审 F3):一条超长腿(海量互异 bg 通知)不许把键集
+ *  撑到无界——超出删最老插入(Map 迭代序=插入序)。远高于任何真实 per-leg 通知量;被逐键的老通知
+ *  最坏情形=同键晚到帧多写一次(at-least-once,shell 按键 dedup 兜底),绝不吞新帧。 */
 export declare 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 declare class NotifiedKeys {
     private readonly byKey;
+    /** The pending/settled outcome of the write that claimed `key`, or undefined when unclaimed. */
     get(key: string): Promise<boolean> | undefined;
+    /** 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: string, written: Promise<boolean>): void;
 }
+/** 家族前缀 = 折叠键只剥 `#seq` 分量(仅当尾是纯数字才剥)。新元组键的 JSON 段恒以 `"]` 结尾、taskId/
+ *  status 里天然的 # 被 JSON 引号包住,`#digits` 尾无歧义=必是 seq;旧格式遗留行(`域:task:status#seq`)
+ *  与 workflow_complete 的裸 runId 键同一语义原样兼容。 */
 export declare function foldKeyFamily(runId: string): string;
+/** 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 declare class InMemoryWorkflowCompletionInbox implements WorkflowCompletionInbox {
     protected readonly onWarn?: ((msg: string, meta: Record<string, unknown>) => void) | undefined;
     protected readonly bySession: Map<string, Map<string, WorkflowCompletionInboxEntry>>;
+    /** 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). */
     private readonly purgedAt;
+    /** 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. */
     private readonly servedAt;
     constructor(onWarn?: ((msg: string, meta: Record<string, unknown>) => void) | undefined);
     private sweepFence;
+    /** 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). */
     protected purgeFenced(entry: WorkflowCompletionInboxEntry): boolean;
+    /** 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. */
     markTerminalServed(sessionId: string, runId: string): Promise<void>;
     protected stampPurge(sessionId: string, owner: string | null | undefined): void;
+    /** 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. */
     protected applyEnqueue(entry: WorkflowCompletionInboxEntry, warn: boolean): void;
     enqueue(entry: WorkflowCompletionInboxEntry): Promise<void>;
     pending(sessionId: string): Promise<WorkflowCompletionInboxEntry[]>;
     ack(sessionId: string, runId: string): Promise<void>;
     purge(sessionId: string, purgedOwner?: string | null): Promise<void>;
 }
+/** 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 declare class FileWorkflowCompletionInbox extends InMemoryWorkflowCompletionInbox {
     private readonly fsyncEnabled;
     private readonly dir;
@@ -63,20 +177,60 @@ export declare class FileWorkflowCompletionInbox extends InMemoryWorkflowComplet
     constructor(root: string, onWarn?: (msg: string, meta: Record<string, unknown>) => void, fsyncEnabled?: boolean);
     private replay;
     private commit;
+    /** 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. */
     private maybeCompact;
+    /** 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. */
     private compact;
     enqueue(entry: WorkflowCompletionInboxEntry): Promise<void>;
     ack(sessionId: string, runId: string): Promise<void>;
     purge(sessionId: string, purgedOwner?: string | null): Promise<void>;
+    /** Close the ledger fd (shutdown). */
     close(): void;
 }
+/**
+ * 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 declare function emitPendingWorkflowCompletions(inbox: WorkflowCompletionInbox | undefined, sessionId: string | undefined, callerPrincipal: string | null, emit: (frame: {
     type: string;
-}) => void | Promise<void>, diag?: {
+}) => void | Promise<void>, 
+/** 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?: {
     route: string;
     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: {
     task_id: string;
     task_type: string;
@@ -99,8 +253,34 @@ export declare function taskNotificationInboxEntry(sessionId: string, owner: str
         edits: number;
     }>;
     resumable?: boolean;
+    /** core 1.353([1412]):诊断槽(journal 坐标+教句,引擎值单源)——park 透传,drain 帧原样带。 */
     diagnostics?: string;
-}, enqueuedAt: number, parentTaskId?: string): WorkflowCompletionInboxEntry;
+}, 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. */
+parentTaskId?: string): WorkflowCompletionInboxEntry;
+/**
+ * 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 declare function resolveCompletionRoute(p: {
     originatingSessionId?: string;
     sourceTaskId?: string;
@@ -112,6 +292,13 @@ export declare function resolveCompletionRoute(p: {
     sessionId: string;
     owner: string | null;
 } | undefined>;
+/**
+ * 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 declare function resolveServedSession(p: {
     originatingSessionId?: string;
     sourceTaskId?: string;