@sema-agent/server 1.323.0 → 2.0.0

package/dist/env-facts.js

@@ -1,11 +1,29 @@
+/**
+ * RFC A1 (docs/design/ENV-SELECT-AND-REGION-SOURCE.md) — the sandbox envFacts composer (service 半场).
+ * Shape ratified REV-1: `TaskSpec.envFacts?: { profile?, capabilities?[], pkgSource?, egress? }`.
+ * Core injects it into model context (escape+bound core-side); this module only COMPOSES the facts
+ * from deployment-trusted sources (image catalog entry + operator region config + exec-lane posture).
+ *
+ * Values are bounded here too (defense-in-depth, cheap): catalog data is trusted, but a hostile row must not
+ * become an unbounded prompt segment. Wire-up is flag-gated OFF until core lands the whitelist field
+ * (`SANDBOX_ENV_FACTS=true` — flipping early is inert: core ignores unknown spec fields).
+ */
 import { isAbsolute, join, resolve, sep } from "node:path";
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 const MAX_STR = 64;
 const MAX_CAPS = 16;
+/** scratchpadDir gets its own cap: TRUNCATING a path points at a non-existent dir (worse than absence), so an
+ *  over-long path DROPS the whole field instead. The threshold is aligned to core's RENDER limit (codex F4):
+ *  core's buildScratchpadSection inlines the path via `inlineUntrusted` whose default cap is 160 CODE POINTS
+ *  (untrusted-text LABEL_MAX) — a 161+ char path would be truncated with "…" in the prompt, i.e. the model would
+ *  be handed a FAKE path. So any path core cannot render verbatim is omitted entirely (honest-facts). */
 const MAX_PATH = 160;
 const bound = (s) => (s.length > MAX_STR ? s.slice(0, MAX_STR) : s);
+/** resumeFacts.note 是整句(64 截会砍在半句上);对齐 MAX_PATH 的 160 render 上限。 */
 const bound2 = (s) => (s.length > MAX_PATH ? s.slice(0, MAX_PATH) : s);
+/** Compose envFacts from what the deployment knows at spec-prep. Returns undefined when nothing is known
+ *  (no fact beats a vacuous one — an empty block would still spend prompt tokens). */
 export function buildEnvFacts(opts) {
     const caps = Object.entries(opts.capabilities ?? {})
         .filter(([, v]) => v === true)
@@ -23,6 +41,11 @@ export function buildEnvFacts(opts) {
     };
     return Object.keys(facts).length > 0 ? facts : undefined;
 }
+/** resumeFacts 按车道能力面的单真源(部署静态;undefined=整域不声明)。取值依据见
+ *  {@link SandboxEnvFacts.resumeFacts} 的逐车道注。
+ *  codex 复审 medium:k8s 必须按**有效快照能力**分叉,不能只看车道名——s3Snapshot 未配=park-only,
+ *  resume 是全新 pod 且**工作区不恢复**,「文件已从快照恢复」那句会让模型信赖不存在的文件(比缺席
+ *  更糟的谎)。 */
 export function resumeFactsForLane(provider, caps) {
     switch (provider) {
         case "e2b":
@@ -35,20 +58,39 @@ export function resumeFactsForLane(provider, caps) {
         case "adb":
             return { scratch: "preserved" };
         case "host":
-        case undefined:
+        case undefined: // provider unset = in-process host lane
             return { scratch: "preserved" };
         default:
-            return undefined;
+            return undefined; // local-docker:容器跨 leg 存续不保证——不知道的不说
     }
 }
+// ── [820]③ scratchpad directory(single source for the FACT and the future exemptDirs)──────────────
+/** Path-safe session segment: the session id can be CALLER-SUPPLIED (body.sessionId), so it must not be able to
+ *  walk the tree ("../", separators, control bytes). Allowlist [A-Za-z0-9_-] (dots excluded so ".." cannot
+ *  survive), everything else becomes "_". Empty after sanitize → "_".
+ *
+ *  INJECTIVITY (codex F3): allowlist sanitization alone is NOT injective — "team/a" and "team?a" both map to
+ *  "team_a", so two DIFFERENT sessions (possibly different principals) would collide onto ONE scratchpad dir.
+ *  The segment is therefore `<readable prefix (sanitized, ≤24)>-<sha256(FULL ORIGINAL sessionId) hex ≤16>`:
+ *  the hash is over the raw pre-sanitize id, so distinct ids always produce distinct segments (the prefix stays
+ *  purely for human readability). Max length 24+1+16=41 (uuidv7 = 36 raw). */
 export function scratchpadSessionSegment(sessionId) {
     const cleaned = sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 24);
     const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
     return `${cleaned.length > 0 ? cleaned : "_"}-${digest}`;
 }
+/** THE scratchpad path convention: `<localDataRoot>/scratchpad/<sessionSegment>`. Session-scoped (core's
+ *  prompt says "session-specific" — every task on the session shares one dir, which is the useful semantics:
+ *  intermediate artifacts survive across turns/resume legs). Exported as the single source both the envFacts
+ *  composer (below) and the future createFsWriteGatePolicy `exemptDirs` wiring ([820]①, 1.290) must use. */
 export function scratchpadDirFor(localDataRoot, sessionId) {
     return join(localDataRoot, "scratchpad", scratchpadSessionSegment(sessionId));
 }
+/** Resolve + CREATE the session scratchpad dir (mkdir -p, idempotent). Returns the path, or undefined when
+ *  creation fails (honest-facts posture: never advertise a directory that does not exist — same class as
+ *  egress/pkgSource "don't declare what you don't know"). Lifecycle: the reaper primitives live below —
+ *  {@link purgeScratchpadDir}(session delete)+ {@link sweepStaleScratchpads}(mtime 周期扫),keyed by the
+ *  same scratchpadDirFor convention;接线(E21 DELETE purge + 周期 sweep)在 main.ts 侧(D 组)。 */
 export async function ensureScratchpadDir(localDataRoot, sessionId) {
     const dir = scratchpadDirFor(localDataRoot, sessionId);
     try {
@@ -59,9 +101,22 @@ export async function ensureScratchpadDir(localDataRoot, sessionId) {
         return undefined;
     }
 }
+/** G3([816] 壳侧承诺③/[820]③,[1840]§四接单):**壳供** scratchpad 路径的验收门。
+ *
+ *  壳(cli)vendored getScratchpadDir 算出 per-session scratchpad 路径随 `TaskRequest.scratchpadDir` 发来;
+ *  接受后它**优先于** server 自算(ensureScratchpadDir),喂 main.ts 的同一单点(envFacts 事实 +
+ *  fs-write gate exemptDirs + additionalDirectories 根围栏)。「没到货引擎忽略 = 无害 additive」。
+ *
+ *  信任边界:这是 exemptDirs **放宽**输入,验收 fail-closed(任何拒收形回落自算,不 fault 任务):
+ *   - 多租户(requirePrincipal)一律拒——共享 worker 盘上租户自选豁免目录=越权面;
+ *   - 仅 host-semantics lane——远程沙箱 lane 的 worker 本机路径对 hands 是谎言(honest-facts 同轴);
+ *   - 绝对路径 + ≤{@link MAX_PATH}(core 渲染上限同源,超限=core 只能给模型假路径)+ canonical
+ *     深度 ≥3(裸 /、/tmp、/home 一整块系统目录不能当豁免域;穿越形按 resolve 归一后判);
+ *   - mkdir -p 确保存在(gate 的 canonicalize 与 core 根围栏都要真目录)。
+ *  敏感路径的最后一道在 core gate 折叠里(sensitivePatterns deny 恒赢,exemptDirs 越不过)。 */
 export async function acceptShellScratchpadDir(raw, opts) {
     if (typeof raw !== "string" || raw.length === 0)
-        return undefined;
+        return undefined; // additive 常态:键缺席/异形,零告警
     if (opts.requirePrincipal) {
         opts.warn("shell_scratchpad_ignored", { reason: "multi_tenant", note: "tenant-supplied exempt dir on a shared worker disk — server-computed scratchpad used instead" });
         return undefined;
@@ -79,6 +134,7 @@ export async function acceptShellScratchpadDir(raw, opts) {
         return undefined;
     }
     const canonical = resolve(raw);
+    // 深度 = 根后的非空路径段数;<3 即一整块系统级目录(/、/tmp、/home/x 之类),不能当写门豁免域。
     const depth = canonical.split(sep).filter((s) => s.length > 0).length;
     if (depth < 3) {
         opts.warn("shell_scratchpad_ignored", { reason: "too_shallow", canonical });
@@ -93,15 +149,23 @@ export async function acceptShellScratchpadDir(raw, opts) {
         return undefined;
     }
 }
+// ── 三路复审修4:scratchpad 清理原语(此前 deferred 注释=无 reap 无界增长;这里只出原语,
+// D 组把它们接到 E21 DELETE purge 与周期 sweep——签名即 seam,勿改名/改形)──────────────────────
+/** 删除一个 session 的 scratchpad 目录(rm -rf,幂等:目录不存在=no-op)。失败吞 warn 不抛——
+ *  清理绝不 fault 调用它的 session-delete 路径;下一轮 {@link sweepStaleScratchpads} 仍会兜到它。 */
 export async function purgeScratchpadDir(localDataRoot, sessionId) {
     const dir = scratchpadDirFor(localDataRoot, sessionId);
     try {
-        await rm(dir, { recursive: true, force: true });
+        await rm(dir, { recursive: true, force: true }); // force: ENOENT 静默=幂等
     }
     catch (err) {
         console.warn(`scratchpad_purge_failed dir=${dir}: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
+/** 周期 sweep:扫 `<localDataRoot>/scratchpad/` 下 mtime 早于 `olderThanMs` 且不属于 `activeSessionIds`
+ *  (先经 {@link scratchpadSessionSegment} 映射到目录名域)的目录并删除,返回删除数。逐目录失败跳过
+ *  (下一轮再兜);scratchpad 根不存在=0。mtime 取目录自身(子文件写入会碰父目录 mtime 的语义因平台而异
+ *  ——诚实边界:一个只被读的活跃 session 目录可能被判过期,activeSessionIds 排除面才是活会话的真保险)。 */
 export async function sweepStaleScratchpads(localDataRoot, opts) {
     const root = join(localDataRoot, "scratchpad");
     let names;
@@ -109,7 +173,7 @@ export async function sweepStaleScratchpads(localDataRoot, opts) {
         names = await readdir(root);
     }
     catch {
-        return 0;
+        return 0; // 根未建(还没任何 session 用过 scratchpad)= 无事可扫
     }
     const activeSegments = new Set([...(opts.activeSessionIds ?? [])].map((id) => scratchpadSessionSegment(id)));
     const cutoff = Date.now() - opts.olderThanMs;
@@ -126,17 +190,19 @@ export async function sweepStaleScratchpads(localDataRoot, opts) {
             removed++;
         }
         catch {
+            /* 单目录 stat/rm 失败(并发删除/权限)→ 跳过,本轮不计数 */
         }
     }
     return removed;
 }
+/** Map the exec-lane posture to the egress fact (the model must know when downloads can't work). */
 export function egressForRemoteExec(remoteExec) {
     if (!remoteExec?.provider)
         return undefined;
     if (remoteExec.provider === "e2b")
         return remoteExec.allowInternetAccess === false ? "none" : "full";
     if (remoteExec.provider === "k8s")
-        return "full";
-    return undefined;
+        return "full"; // kata pods egress via the cluster CNI (no allowlist face yet)
+    return undefined; // host/ssh/adb: the deployment hasn't declared a posture — say nothing rather than guess
 }
 //# sourceMappingURL=env-facts.js.map

package/dist/fleet/fleet-bus.d.ts

@@ -1,28 +1,94 @@
+/** The fleet vocabulary the shell renders (MF-Fleet `FleetTask.status`). The service maps its run/workflow status
+ *  onto this neutral set; `awaiting approval` = a needs-review/plan-approval park, `waiting` = a durable suspend.
+ *
+ *  §K-7 (shell ASK 2026-06-28) asked for a `report_blocked` / `nesting` status extension to hide blocked internal-
+ *  nesting agents from the picker. DELIBERATELY NOT EXTENDED — the need is already met without breaking the
+ *  SDK byte-alignment (`@sema-agent/sdk` 0.0.39 keeps this exact 9-value set, and the SDK explicitly declined to add
+ *  one unilaterally, awaiting a service decision): (1) `report_blocked` = a TERMINAL outcome (the agent gave up) →
+ *  `runStatusToFleet("blocked")→"failed"` → the row is REMOVED (onTerminal), so a blocked agent never lingers in
+ *  the picker (the leaked-stale-blocked-row bug that triggered the ask was fixed in 1.11.0); (2) "internal nesting"
+ *  is already expressible — every subagent CHILD row carries `parentId`, so the picker filters its flat view to
+ *  top-level rows (`parentId` absent) and shows the rest only in the tree. Adding a redundant status/flag that
+ *  carries no non-derivable information would only create wire surface the SDK must mirror. The real picker fix is
+ *  the additive `agentType` carrier above (a short type label instead of the objective). */
 export type FleetTaskStatus = "queued" | "running" | "waiting" | "stopping" | "awaiting approval" | "idle" | "completed" | "failed" | "killed";
+/** One active task row (wire subset of the contract `FleetTask` — `depth`/`viewed`/tree-`selection` are
+ *  shell-local render state the renderer composes; the wire carries the data that TRANSITIONS). */
 export interface FleetTaskRow {
     id: string;
     name: string;
     description?: string;
+    /** §K-7 (shell ASK 2026-06-28; byte-aligned to `@sema-agent/sdk` 0.0.39 `FleetTaskRow.agentType`/`agentName`) — a
+     *  SHORT agent-TYPE label so the picker renders like CC 187 (`Explore`/`general-purpose`/`code-review`) instead of
+     *  the full objective. `agentType` = the "what kind of agent" (a subagent's type / a delegated `taskName`);
+     *  `agentName` = an in-process teammate's INSTANCE name. ADDITIVE / tolerate-absent: a TOP-LEVEL run carries NO
+     *  native agentType (sema design — top-level runs have no agent-type; the analog is the SCENARIO, whose surfacing
+     *  is the still-open "fleet-row name source" decision for clay/shell) → ABSENT, and the consumer FALLS BACK to
+     *  `name` (the objective-preview). Populated TODAY on SUBAGENT CHILD rows, where `task_progress.name` IS the type
+     *  (BC-2). SECRET-SAFE: redacted before emit, same discipline as `name`. */
     agentType?: string;
     agentName?: string;
+    /** Owning principal (= the run's scope). The `/v1/fleet/stream` route filters to the caller's scope (owner-gated)
+     *  unless the caller is fleet-wide (operator / trace-token). NOT rendered — a tenant-isolation field. */
     scope?: string;
+    /** Fleet per-session scope: the run's rootTaskId (= sessionId). The
+     *  `/v1/fleet/stream` route ALSO filters to the caller's `?session=` when present, so a TUI footer shows only the
+     *  CURRENT session's rows, not OTHER sessions of the same principal (the "他会话 token" leak). NOT rendered — a
+     *  scoping field like `scope`. Absent ⇒ the row is visible to any same-principal caller (back-compat, unscoped). */
     sessionId?: string;
     parentId?: string;
+    /** [1832] P1-2(core 1.432 BackgroundChildEvent.parentToolCallId,「出生就在场」语义):发起本子代的
+     *  父 tool_use id **原值**(E2 域,core-mint 不含用户内容)——与 `parentId`(解析后的行链接)是两个域:
+     *  本键给按 tool_use id 建卡树的消费端(cli 卡片树)直接绑定,无需 FIFO 猜/形状嗅探。
+     *  ADDITIVE / tolerate-absent(旧 core 不发)。 */
     parentToolCallId?: string;
+    /** [1440] design/149:wa\* 行的 workflow 归属附注位(w\* runId)——面板按此分组;footer 树不按此嵌套
+     *  ([1433] CC 锚:wa\* 不进 footer,壳按 taskId 前缀过滤)。ADDITIVE / tolerate-absent。 */
     workflowRunId?: string;
     status: FleetTaskStatus;
+    /** core 1.367 δ([1514]/[1515]④):launch 时刻 epoch ms(revive 行=本 revive 周期 wake 时刻)——
+     *  cli 的 elapsed 锚直出(比 server 端 elapsedMs 快照更稳,消费方自算不漂)。ADDITIVE / tolerate-absent
+     *  (a* 车道 spawn 即带;旧 core 帧无 startedAt 时回落 server 收帧时刻)。 */
     startedAt?: number;
     elapsedMs?: number;
     tokens?: number;
     queuedCount?: number;
     awaitingPlanApproval?: boolean;
+    /** core 1.262.0: the child's most recent tool intent as one
+     *  human line ("Bash npm test") — from the bg sink tick's `currentAction` (core's only attachment point
+     *  today). UNTRUSTED (tool argument head) → redacted before publish, same discipline as `name`.
+     *  ADDITIVE / tolerate-absent. */
     currentAction?: string;
+    /** cli [1827]②(core 1.429 `currentTool`):`currentAction` 的**结构化**同源体 —— CC220 详情页
+     *  Progress 段消费 `{toolName, target}` 结构(toolName 查工具注册表,自由文本塞不进去)。
+     *  `toolName` = core 工具名 verbatim;`target` = UNTRUSTED 自由文本(命令行/路径可能秘密形)→
+     *  redactSecrets + bound,与 `currentAction` 同信任边界。与 currentAction 同生命周期(未跑过工具前
+     *  缺席);ADDITIVE / tolerate-absent(旧 core 不发 ⇒ 键缺席,消费方回落 currentAction 文本)。 */
     currentTool?: {
         toolName: string;
         target?: string;
     };
+    /** cli [1748]①:该子代**累计**的工具调用次数(bg sink tick 的 `usage.toolUses`)——面板行与详情页的
+     *  tool 计数。⚠️ **累计值,直接上行不累加**(与 `turn_end` 的每轮增量相反);⚠️ **缺席 ≠ 0** ——
+     *  老 core 不发这个数时本位缺席,消费方不得当 0 渲染(那会把「不知道」伪装成「跑了 0 个工具」)。
+     *  ADDITIVE / tolerate-absent。 */
     toolUses?: number;
+    /** cli [1748]②:该子代的转录 id —— 壳侧据此去转录里取**委派 prompt**(详情页 `Prompt` 段)。
+     *  ⚠️ 为什么给的是映射而不是 prompt 本身:`BackgroundChildEvent` 上**没有 prompt**(core `types.d.ts`),
+     *  server 收不到的东西不能凭空造 —— 要 prompt 直出需要 core 先发。(旧注还说「也无 parentToolCallId」,
+     *  core 1.432 已补该键,见 FleetTaskRow.parentToolCallId——本键的理由只剩 prompt 一半。)
+     *  ADDITIVE / tolerate-absent。 */
     transcriptId?: string;
+    /** [1839]①/(a) 案:**终态行帧的残局键**——cli 实测裸 durable-run 完成时终态 task 帧键集只有
+     *  [id,name,status,tokens,elapsedMs,description],idle 观察者(web 首屏形)从行卡拿不到终局。
+     *  (b) 案(为顶层 run 造 bg_notification)被否:那族语义=观察者眼里的**子代**,伪造事件族比丰富行帧
+     *  更伤([1840]§二)。四键全部 ADDITIVE / tolerate-absent、**只在终态帧出现**:
+     *  - `stoppedBy`:core open enum verbatim(与 BgNotification 同姿势);顶层 run 仅 cancel 路径有源
+     *    (= "user",与 markStopSource 同源值),其余终态诚实缺席。
+     *  - `usage`:与 {@link BgNotification.usage} **同形**(消费端一个形状)——bg 子代=terminal 事件的
+     *    usage 逐键挑;顶层 run=TaskResult.stats 映射(tokens→totalTokens、toolCalls→toolUses)。
+     *  - `resumable`/`editedFiles`:**仅 bg 子代有源**(BackgroundChildEvent.terminal);顶层 TaskResult
+     *    上没有这两位 ⇒ 顶层行帧永缺席,不造([1840]§二「没有就诚实缺席」)。 */
     stoppedBy?: string;
     usage?: {
         totalTokens?: number;
@@ -38,20 +104,31 @@ export interface FleetTaskRow {
         edits: number;
     }>;
 }
+/** One workflow row (wire subset of contract `FleetWorkflow`). */
 export interface FleetWorkflowRow {
     id: string;
     name: string;
     description?: string;
+    /** Owning principal (= the workflow run's scope). Same owner-gate as FleetTaskRow. NOT rendered. */
     scope?: string;
+    /** #3 fleet per-session scope (rootTaskId = sessionId): the `/v1/fleet/stream` `?session=` filter. NOT rendered. */
     sessionId?: string;
     status: string;
     doneCount?: number;
+    /** 计划总数(= `run.agents.length`,**含排队中**)—— 注意它**不是**"已启动数",见 {@link FleetWorkflowRow.startedCount}。 */
     totalCount?: number;
     failedCount?: number;
+    /** MF-Fleet additive(cli [1726] 二①):**已启动**(非排队中)的 agent 数 —— CC 2.1.220 `⚠ Large workflow`
+     *  规模告警的分母。判别用 core 导出的 `deriveAgentDisplayStatus`(`startedAt` 未置 ⇒ 显示态 `queued`),
+     *  **不自己重写谓词**:两端各写一遍必然漂移(本仓刚在治理面镜像上吃过同款)。
+     *  ADDITIVE / tolerate-absent:缺席时消费方可退回 `doneCount + failedCount` 这个**诚实下界**(告警偏早)。 */
     startedCount?: number;
     elapsedMs?: number;
     tokens?: number;
 }
+/** A push frame on the fleet stream. `snapshot` = the full current state on connect; `task`/`workflow` = a single
+ *  row upsert (the row transitioned); `task_remove`/`workflow_remove` = the row left the active set (terminal +
+ *  swept). Stable identity (`id`) lets the UI update/remove the right row in place. */
 export type FleetFrame = {
     type: "snapshot";
     tasks: FleetTaskRow[];
@@ -82,20 +159,56 @@ export type FleetFrame = {
     notice: HookNotice;
     ts: number;
 };
+/**
+ * **一次 hook 判定「未能完成」**的观测帧(cli 黑板 [1786] 点名的需求;字段名由本仓定)。
+ *
+ * ── 它解决什么 ────────────────────────────────────────────────────────────────────────────────
+ * 用户设了 `/goal enforced`,产品对模型承诺「没达成不许停」。某一轮评估者没能给出判词
+ * (无内容 / 读不懂 / 被跳过)⇒ 按裁定**放行**。此刻的问题不是放行本身,是:
+ * **用户不知道这一轮的守卫没生效**,而模型拿到的是一个与「已达成」**无法区分**的放行。
+ * ⇒ **产品声称了一件它这一轮没做到的事。** 方向可以 fail-open,但不能连「我这轮没看住」都不说。
+ *
+ * ── 四条设计约束(逐条对应需求)──────────────────────────────────────────────────────────────
+ *  1. 语义是「**未能评估**」,**不是**「未通过」—— 两者必须可区分,否则壳侧只能说一句更模糊的话;
+ *  2. `reason` 机器可判(`no_content` / `unparsed` / `skipped`),与 server 侧那三行结构化日志同源;
+ *  3. **不只服务 `/goal`**:按「hook 判定未能完成」定义,带 `event` 位;`/goal` 只是第一个消费者;
+ *  4. 🔴 **纯 observe,不改变运行** —— 它走 fleet 流(常开推送道),**不是** `additionalContext`
+ *     (那个通道本身会让这一轮不结束,见 hook-runner 折叠处那段旁注)。
+ *
+ * ⚠️ 可见性**与 `bg_notification` 同为 fail-CLOSED**:带 `ownerSessionId` 的帧只投给能证明是自己的
+ * 订阅方(`undefined` ⇒ 对 scoped 订阅方**丢弃**)。理由同源:一条关于别人会话的通知落到这个壳上,
+ * 会让用户以为是自己这轮出了问题。
+ */
 export interface HookNotice {
+    /** 目前只有一种;留成枚举位是为了下一类观测帧不必再开一个 frame 臂。 */
     kind: "hook_decision_unavailable";
+    /** 哪个 hook 事件(`Stop` / `PreToolUse` / …)。 */
     event: string;
+    /** 机器可判的原因(与 server 日志的三行同源)。 */
     reason: "no_content" | "unparsed" | "skipped";
+    /** 补充说明(已脱敏)。例如 `skipped` 的具体原因。 */
     detail?: string;
+    /** 租户可见性(发布前带,上 wire 前剥)。 */
     ownerScope?: string;
+    /** 宿主会话(发布前带,上 wire 前剥)——scoped 订阅方的 fail-closed 判据。 */
     ownerSessionId?: string;
 }
+/** design/129-B 缺口② (帧契约): a background child's COMPLETION notification pushed on the
+ *  ALWAYS-OPEN fleet stream — the only server-push lane an idle shell keeps subscribed, so a session-scoped bg
+ *  child finishing while the host sits idle notifies IMMEDIATELY (no more "late by one input cycle" durable-drain).
+ *  EVENT semantics, not state: never in the snapshot, no dedup key held here (the shell's task_notification
+ *  injection queue dedups by (taskId,status) — the outer belt). Row visibility stays on `task` frames
+ *  (行是状态、通知是事件,别合并). */
 export interface BgNotification {
+    /** Registry handle (`a*` domain — the TaskOutput/TaskStop key). */
     taskId: string;
+    /** The child RUN's session id (uuid domain — the a*↔uuid dual anchor), when known. */
     sessionId?: string;
+    /** Stop-cycle counter(core 1.352 terminal 帧补位;revive 周期判别键素材)——tolerate-absent。 */
     seq?: number;
     status: "completed" | "failed" | "killed";
     summary?: string;
+    /** Background lifetime scope (design/129), NOT the tenant scope. */
     scope: "task" | "session";
     parentTaskId?: string;
     stoppedBy?: string;
@@ -109,6 +222,8 @@ export interface BgNotification {
         path: string;
         edits: number;
     }>;
+    /** [1543]§二 LOW 补:完成通知的花费/转录锚(core BackgroundChildEvent.terminal 携带,此前被剥——
+     *  完成卡无花费显示、转录跳转无锚)。数值/id verbatim。 */
     usage?: {
         totalTokens?: number;
         toolUses?: number;
@@ -118,37 +233,67 @@ export interface BgNotification {
         costMicroUsd?: number;
     };
     transcriptId?: string;
+    /** P1-3(core 1.452,[1925] 一轮批):子代完成的**幂等锚**——同一完成的多路通知(bg_notification/
+     *  task_notification/inbox 重放)带同一 id,消费端按它去重。verbatim;ADDITIVE/tolerate-absent。 */
     completionId?: string;
+    /** core 1.367 δ([1514]/[1515]④):委托树 root 宿主会话(固定点语义,嵌套孙代恒锚 root shell)——
+     *  cli 跨壳重启按宿主会话归组([1500]② 台账判别 F2 残余闭环)。ADDITIVE / tolerate-absent。 */
     rootSessionId?: string;
+    /** Tenant/principal isolation key (same filter as FleetTaskRow.scope). STRIPPED before send. */
     ownerScope?: string;
+    /** The HOST session id (session-scoped children: registry owner) — the `?session=` filter key (the payload
+     *  `sessionId` above is the CHILD's uuid and would never match the caller's session). STRIPPED before send. */
     ownerSessionId?: string;
 }
+/**
+ * The process-local fleet aggregation bus. Holds the current active set + fans out deltas to SSE subscribers.
+ * Upserts MERGE (a partial delta patches the existing row), so a publisher can emit just the field that changed
+ * (e.g. only `tokens`) and the row stays whole. Removal drops the row (terminal). Subscribers get a snapshot of
+ * the current set immediately, then every subsequent delta.
+ */
 export declare class FleetEventBus {
     private readonly now;
     private readonly emitter;
     private readonly tasks;
     private readonly workflows;
     constructor(now?: () => number);
+    /** Upsert a task row (MERGE onto any existing row by `id`) + fan out the merged row. Publishers may send a
+     *  partial `{ id, tokens }` etc.; the row keeps its other fields. */
     publishTask(delta: Partial<FleetTaskRow> & {
         id: string;
     }): void;
+    /** 推一帧 hook 判定未完成的观测通知(事件语义,不进 snapshot —— 与 `bg_notification` 同族)。 */
     publishHookNotice(notice: HookNotice): void;
+    /** Drop a task row (terminal + swept) + fan out the removal. Idempotent (a no-op if already gone). */
     removeTask(id: string): void;
+    /** Upsert a workflow row (MERGE by `id`) + fan out. */
     publishWorkflow(delta: Partial<FleetWorkflowRow> & {
         id: string;
     }): void;
+    /** Drop a workflow row + fan out the removal. Idempotent. */
     removeWorkflow(id: string): void;
+    /** design/129-B 缺口②: fan out a background-child completion notification (EVENT — not stored, never in the
+     *  snapshot; a subscriber that connects later reads the durable inbox instead). */
     publishBgNotification(notification: BgNotification): void;
+    /** The current full state (the connect-time snapshot frame). */
     snapshot(): Extract<FleetFrame, {
         type: "snapshot";
     }>;
+    /** Subscribe to deltas. Returns an unsubscribe thunk. The caller typically sends `snapshot()` first, then every
+     *  delta this delivers — the snapshot+delta sequence is the live fleet view. */
     subscribe(cb: (frame: FleetFrame) => void): () => void;
+    /** Live counts (test/observability). */
     get size(): {
         tasks: number;
         workflows: number;
     };
     private emit;
 }
+/** A run-scoped lifecycle publisher — wire it into a run's TaskEvent loop so the fleet row TRANSITIONS with the
+ *  run. `onStart()` adds the top-level row (running); `onEvent(ev)` accrues tokens (turn_end usage) + adds/updates
+ *  subagent CHILD rows (core `task_progress`, keyed by its `taskId`, nested under the run via `parentId`);
+ *  `onTerminal(status)` flips the row terminal + removes it (and its children) from the active set. No-op when no
+ *  bus is wired. The token accrual is CUMULATIVE across the run's turns (turn_end carries a per-turn delta). */
 export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
     runId: string;
     scope: string;
@@ -175,14 +320,30 @@ export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
         parentToolCallId?: string;
         status?: string;
     }) => void;
+    /** Flip + remove one subagent CHILD row when its background completion notification arrives
+     *  (task_progress never emits a terminal tick — without this a bg child sat "running" until parent settle).
+     *  FLIP-THROUGH: publishes the terminal frame even when the row no longer exists — the parent leg's
+     *  settle removes ALL child rows (it cannot tell a settled sync child from a still-running bg child), so a bg
+     *  child that completes after parent settle otherwise had NO row to flip and the shell (auto-exit's fourth
+     *  release condition watches the viewed cid's terminal) never saw a terminal transition. Returns whether the
+     *  row EXISTED (hadRow — the observer logs it; false = the frame was synthesized flip-through). */
     onChildTerminal: (taskId: string, status: string, altId?: string, toolUseId?: string) => boolean;
+    /** [1839]①/(a) 案:`residuals` = 顶层 run 的终局残局键(有源才传,见 FleetTaskRow 上的键注)。
+     *  只有**真终态**(completed/failed/killed)帧带残局——parked(suspended/needs_review)的行还活着,
+     *  没有「终局」可言,误传也不上帧。 */
     onTerminal: (status: string, residuals?: {
         usage?: FleetTaskRow["usage"];
         stoppedBy?: string;
         transcriptId?: string;
     }) => void;
 };
+/** The run-scoped publisher handle (returned by `fleetRunPublisher`). Threaded into `runInBackground` so a
+ *  background run TRANSITIONS its fleet row exactly like the sync POST /v1/runs leg does. */
 export type FleetRunPublisher = ReturnType<typeof fleetRunPublisher>;
+/** [1839]①/(a) 案:TaskResult → 终态行帧残局键映射(sync/background/resume 三条腿各自 settle,共用一处
+ *  映射——键名映射写三遍必漂移)。usage 与 {@link BgNotification.usage} 同形:stats.tokens→totalTokens、
+ *  stats.toolCalls→toolUses(名对齐,消费端一个形状)。errorCode "cancelled" ⇒ stoppedBy:"user"(与
+ *  markStopSource 的归因值同源);transcriptId 顶层 = run 的 sessionId([1840]§二拍)。缺源的键不铸。 */
 export declare function fleetRunResiduals(result: {
     sessionId?: string;
     errorCode?: string;
@@ -197,10 +358,34 @@ export declare function fleetRunResiduals(result: {
     stoppedBy?: string;
     transcriptId?: string;
 };
+/**
+ * design/129-B (core 1.240.0) — the PROCESS-LEVEL background-child fleet publisher, wired once
+ * onto `RunnerDeps.onBackgroundChildEvent`. Unlike {@link fleetRunPublisher} (per-leg: dies at leg settle —
+ * the root cause: a session-scoped bg child outliving its turn had NO forward path, fleet showed zero
+ * child frames), this observer lives as long as the process and covers the child's WHOLE lifecycle:
+ *   spawn    → row appears the moment the child registers (launch→turn-tail 零帧 fixed: no more waiting for a
+ *              first tick that a slow child never emits inside the turn);
+ *   tick     → token rollup onto the row; ALSO best-effort removes the per-leg uuid-keyed TWIN row the leg's
+ *              onForwardEvent built for the same child (`${parentTaskId} ${progressTaskId}` composite — the
+ *              per-leg childId shape), so the child shows ONCE, keyed by its stable a* handle;
+ *   terminal → terminal frame under the a* row id, row leaves the fleet, and the contract
+ *              `bg_notification` frame rides the always-open stream (缺口②'s immediate idle delivery).
+ * Rows are tagged `scope` (tenant filter) from the registry scope and `sessionId` (the `?session=` filter)
+ * from the registry owner when session-scoped (owner IS the host sessionId; task-scoped children have no
+ * session attribution → unscoped, back-compat visible). Names ride the same redactSecrets discipline.
+ */
 export declare function fleetBackgroundChildPublisher(bus?: FleetEventBus, log?: (msg: string, fields: Record<string, unknown>) => void): (e: import("@sema-agent/core").BackgroundChildEvent) => void;
+/** BC-1 (clay-decided 2026-06-27): a top-level run's fleet-row `name` = a SHORT, single-line **objective preview**
+ *  (the readable "what is this task" label) — NOT the full objective dumped in, and NOT duplicated into `description`.
+ *  `description` is left to the publisher's LIVE-ACTIVITY update (`onEvent` tool_start → the current tool), so the row
+ *  shows `name`=objective + `description`=current activity (two DISTINCT things, killing the earlier "objective shown
+ *  twice" dup). Whitespace-collapsed + capped ≤48. (A subagent CHILD row's name = its agent-type — BC-2.)
+ *  SECRET-SAFE: redact secret shapes (redactSecrets) BEFORE truncating — a secret in the objective must not leak in
+ *  the row name. The durable objective is already redacted; the name preview was asymmetric (raw) until this. */
 export declare function fleetRunLabels(objective: string | undefined): {
     name: string;
 };
+/** Map a service run status onto the neutral fleet vocabulary the shell renders. */
 export declare function runStatusToFleet(status: string, opts?: {
     awaitingPlanApproval?: boolean;
 }): FleetTaskStatus;