@sema-agent/server 1.323.0 → 2.0.0

package/dist/http/routes/attachments.js

@@ -1,3 +1,9 @@
+/**
+ * design/158 A9 域模块 —— D-1 通用文件附件面(`/v1/attachments`:上传/取回/删除三动词)。
+ *
+ * owner 门无 oracle(未知与他人同答 404,与 notify 门同姿);上限=server 权威(reject-not-OOM);
+ * mime 白名单是部署策略旋钮不是安全开关。本域零可变状态。
+ */
 import { createHash } from "node:crypto";
 import { uuidv7, sanitizePathComponent } from "@sema-agent/core";
 import { HttpError } from "../../security.js";
@@ -8,11 +14,19 @@ export async function handleAttachments(req, res, url, ctx) {
     await handleAttachmentsBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。
+ *  跨域的东西(deps / 助手 / 单域状态 / 每请求量)一律在首行解构出来,于是下面每一行都逐字不变。 */
 async function handleAttachmentsBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { rateLimited, quotaExceeded, safeDecode, readRawBody } = ctx.helpers;
+    // D-1 通用文件上传(clay 拍 2026-07-27:独立附件 store)——上传/取回/删除三动词。
+    // 语义:上传先行拿句柄 → TaskRequest.attachments 引用绑定(main.ts resolveSpec 半场)→ env 建立
+    // 时物化到执行环境(远程 lane factory 包装 / host lane 提交时直写)。owner 门无 oracle(未知与
+    // 他人同答 404,notify 门同姿);上限=server 权威(reject-not-OOM,sync-blob 同姿);
+    // mime 白名单是部署策略旋钮非安全开关(声明 mime 不可验证;真防线=尺寸上限+沙箱内消费)。
     {
-        const am = /^\/v1\/attachments(?:\/([^/?]+))?$/.exec(url);
+        const am = /^\/v1\/attachments(?:\/([^/?]+))?$/.exec(url); // NB: `url` 已剥 query(:1017),参数读 req.url
         if (am) {
             if (rateLimited(req, res) || quotaExceeded(req, res))
                 return;
@@ -29,14 +43,17 @@ async function handleAttachmentsBody(req, res, url, ctx, miss) {
             const owner = principal ?? "default";
             const attId = am[1] !== undefined ? safeDecode(am[1]) : undefined;
             if (attId === undefined && req.method === "POST") {
-                const q = new URL(req.url ?? "", "http://x").searchParams;
+                // ── 上传:POST /v1/attachments?name=<urlencoded>,raw body,content-type=声明 mime ──
+                const q = new URL(req.url ?? "", "http://x").searchParams; // `url` 已剥 query
                 const rawName = q.get("name");
+                // 消毒:剥路径段(两种分隔符)取 basename,截长,再过 core 的组件验证器(throw 形——不合法
+                // 即拒;此处先自检同一规则把「用户给了个烂名」按 400 答而不是 500)。
                 const base = ((rawName ?? "").split(/[/\\]/).filter(Boolean).pop() ?? "").slice(0, 128);
                 if (!rawName || base === "" || base === "." || base === ".." || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(base)) {
                     sendError(res, 400, "request.query_invalid", "query param `name` is required and must reduce to a safe basename ([A-Za-z0-9._-], not starting with a dot)");
                     return;
                 }
-                const name = sanitizePathComponent(base);
+                const name = sanitizePathComponent(base); // 双保险:与 core 文件店同一验证器(不合法=上面已 400,这里恒过)
                 const mime = String(req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
                 if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mime) || mime.length > 128) {
                     sendError(res, 400, "request.query_invalid", "content-type must be a well-formed mime type (type/subtype)");
@@ -50,7 +67,7 @@ async function handleAttachmentsBody(req, res, url, ctx, miss) {
                 const max = deps.config.attachmentMaxBytes ?? 32 * 1024 * 1024;
                 let body;
                 try {
-                    body = await readRawBody(req, max);
+                    body = await readRawBody(req, max); // 413s mid-stream(reject-not-OOM)
                 }
                 catch (err) {
                     if (err instanceof HttpError && err.status === 413) {
@@ -83,6 +100,7 @@ async function handleAttachmentsBody(req, res, url, ctx, miss) {
                 res.writeHead(200, {
                     "content-type": meta.mime,
                     "content-length": String(bytes.byteLength),
+                    // RFC 5987 编码名(name 已消毒为安全 basename,URL 编码后恒 header-safe)
                     "content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(meta.name)}`,
                 });
                 res.end(Buffer.from(bytes));

package/dist/http/routes/capabilities.d.ts

@@ -1,3 +1,10 @@
+/**
+ * design/158 A9 域模块 —— 能力/场景/模型目录只读面。
+ *
+ * 路由:`GET /v1/capabilities/scenarios/:name`、`GET /v1/capabilities`、`GET /v1/models`。
+ * 三条都在全局 service-credential 门**之后**(config 面非密只读),装配表里的位置必须保住这一点。
+ * 本域零可变状态;deps 面宽(能力布尔逐条对应各路由的 501 门,单源不许漂移)但全是存在性只读。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleCapabilities(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;

package/dist/http/routes/capabilities.js

@@ -7,29 +7,56 @@ export async function handleCapabilities(req, res, url, ctx) {
     await handleCapabilitiesBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。
+ *  跨域的东西(deps / 助手 / 单域状态 / 每请求量)一律在首行解构出来,于是下面每一行都逐字不变。 */
 async function handleCapabilitiesBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
+    // E5 定稿:场景详情只读端点——web 专家模式渲染工具面选项+提示词概览。source 语义=selectScenario
+    // 实际取用的定义(main.ts 组装时 center 条目与 overlay 同判定源盖同名,约定①)。鉴权=与 /v1/capabilities
+    // 同门(全局 service-credential 门后,config 面非密);未知名 404 typed code(人话归壳/web)。
     if (req.method === "GET" && url.startsWith("/v1/capabilities/scenarios/")) {
         const name = url.slice("/v1/capabilities/scenarios/".length).split("?")[0];
         const detail = deps.scenarioDetails?.[name];
         if (!detail) {
+            // [939] 信封统一:本路曾是全站唯一对象形 error(`{error:{code}}`)——SDK toApiError 对它特判过一轮
+            // TypeError 加固。统一为「字符串 error + 顶层 errorCode」邻位形(cancel/decide 同款),机器判据保留。
             sendError(res, 404, "scenario_not_found", "scenario not found");
             return;
         }
         sendJson(res, 200, detail);
         return;
     }
+    // Capability discovery: one call tells a consumer which surfaces this worker has,
+    // instead of probing each verb for a 501. Open set — unknown keys must be ignored by consumers.
+    // Auth'd like /v1/models (config surface, non-secret). Booleans derive from the SAME deps that gate
+    // the routes, so this can never drift from actual 501 behavior.
     if (req.method === "GET" && url === "/v1/capabilities") {
+        // Deployment bag first, derived booleans LAST: the bag extends the set but can never shadow the
+        // route-gating truths (a config typo must not make capabilities lie about what 501s).
         sendJson(res, 200, {
             ...deps.capabilities,
             asyncRuns: Boolean(deps.runStore),
             artifacts: Boolean(deps.runStore),
+            // TRUE when durable HITL can FIRE = checkpointStore present (DURABLE_APPROVAL=true): it mounts
+            // AskUserQuestion-suspend + the approval center + resumable checkpoints, independent of whether any
+            // TOOL is gated (APPROVAL_REQUIRE = the additive F4 layer). Legacy poll-gate approvalStore does NOT
+            // count: alone it can't suspend (the P2-preflight lie).
             approvals: Boolean(deps.checkpointStore),
             sessions: Boolean(deps.sessionAudit),
+            // [1196] session 级 SSE 订阅面:与 /v1/sessions/:id/events 的 501 谓词同源(sessionWatch 只在
+            // sessionStorage 具备 getLeafId/ownerOf 时由 main.ts 构建)——web 据此换轨,false=回落 /head 轮询。
             sessionEvents: Boolean(deps.sessionWatch && deps.sessionStorage?.getLeafId && deps.sessionStorage?.ownerOf),
+            // #13([1871] web asks,clay 排批 2026-07-27):fleet 面能力族——一个诚实对象或 false(无 fleetBus=
+            // 无 /v1/fleet/stream,路由 501 同谓词)。`resume:"snapshot"` 是刻意的语义广告而非搪塞:总线是
+            // latest-state 不是事件日志,**每次连接开头就是全量 snapshot 帧** ⇒ 重连=重快照,行状态不存在
+            // 「丢帧」;通知帧(bg_notification)另有 durable inbox 兜底重投。做 last-event-id 重放缓冲=与
+            // snapshot 机制重复建设,收益为零(SDK streamFleet 的「NOT RESUMABLE」旧自述按此口径改写)。
+            // `steerPriority:"advisory"` 诚实:steer body.priority 收下+枚举校验但 no-op(E15,候 core 队列 seam)。
             fleet: deps.fleetBus
                 ? { stream: true, sessionScope: true, observe: true, resume: "snapshot", bgNotifyFailClosed: true, steerPriority: "advisory" }
                 : false,
+            // #3 workspace 浏览面([1894]④:与 fleet 同姿势——对象=面在场,false=501 同谓词)。
             workspace: (() => {
                 const wfs = deps.fileSnapshotStore;
                 return wfs && typeof wfs.listKeys === "function" && typeof wfs.exportManifest === "function" && typeof wfs.getBlob === "function" && Boolean(deps.sessionStorage?.ownerOf)
@@ -37,57 +64,216 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
                     : false;
             })(),
             leader: Boolean(deps.leaderEndpoint),
+            // design/138 S1 (clay 2026-07-08): the legacy MemoryStore surface (GET/DELETE /v1/memory + the MF-30
+            // session write verbs) was DEPRECATED with the store itself — the new memory engine is model file skills
+            // over the injected memory dir, with NO service HTTP verbs. Hard-coded false so a shell that still knows
+            // the old caps honestly hides the affordances (the adaptation was pre-announced).
             memory: false,
             memoryWrite: false,
+            // CLI surfaces: /v1/policy is always served (config surface); /v1/usage returns real
+            // cumulative spend only when a per-principal quota is configured (else enabled:false).
             policy: true,
             usage: Boolean(deps.costQuota),
+            // E5 (shell-host contract): permission-mode WRITE is not a cloud-worker capability. Autonomy is
+            // compile-time tighten-only + worker-global config (a cloud supervisor shell CANNOT change server-side
+            // gating, ~L2075; "autonomy is CONFIG, not steer", core checkpoint-store.ts:513). The READ side is served
+            // honestly via GET /v1/policy (PolicyInfo.autonomy). A runtime per-session mutation verb + mode_changed push
+            // need a core seam (SERVICE-GAP-DOSSIER §2 row 5) — advertise false so the shell keeps a read-only mode
+            // banner instead of a 501-able write affordance ("says yes but 501s" must be impossible).
             permissionModeWrite: false,
+            // E7 (shell-host contract): model selection (body.model) + reasoning-effort selection
+            // (body.reasoningEffort→TaskSpec.thinking) are accepted on every task request → both true.
+            // 🔴 CORRECTION (2026-07-25, blackboard [1664]→[1668]): this used to say "the RESOLVED effectiveModel ECHO
+            // is a separate, still-core-blocked cap (SERVICE-GAP-DOSSIER §2 row 7)". THAT WAS WRONG, and it was wrong in
+            // an instructive way — the capability exists, it just isn't SPELLED `effectiveModel`. core's `TaskResult.model`
+            // (core `src/core/types.ts:1871`, design/99 MF-25) is documented verbatim as "the EFFECTIVE model id that
+            // served this task — the RESOLVED `Model.id`, not the requested `TaskSpec.model` ref … Lets a UI echo
+            // 'served by X'". A grep for the identifier `effectiveModel` returns zero hits in core and that was mistaken
+            // for "core doesn't have it" (search by SEMANTICS, not by identifier name). It already reaches the wire:
+            // `POST /v1/tasks` returns the TaskResult verbatim (~L1852), the SDK declares `TaskResult.model`, and this
+            // server already consumes it internally for cache-family accounting (~L1843). Pinned by
+            // `test/effective-model-echo-wire.test.ts` (real HTTP: resolved id echoed, absent key stays absent) so a
+            // future projection/whitelist on this leg can't silently drop it — the `toolEndEventData`-label bug class.
+            // Nothing is advertised as a capability BIT here because an additive result field needs no gate
+            // (gate-don't-trial-by-501 governs endpoints/verbs, not additive response fields).
             modelSelection: true,
             effortSelection: true,
+            // E1 (shell-host contract): tool_end now carries the model-facing `output` (core 1.121.0) — wired onto the durable +
+            // live + replay streams (redacted at every boundary). E2: content events carry `eventId` (+ `parentToolCallId`
+            // for sub-agent tasks). Both true now that the pinned core emits them and the service threads them through.
             toolOutput: true,
             messageIdentity: true,
+            // C1/C2 (core 1.219): `forwardSubagentEvents` = body flag accepted (a delegated child's live
+            // content events ride the run stream, parentToolCallId-attributed); `subagentSteer` = the
+            // POST /v1/runs/:id/subagents/:target/steer verb routes (requires the run store the route 501s without —
+            // same derive-from-deps discipline as the rest of this block; the registry itself is always constructed).
             forwardSubagentEvents: true,
+            // G3([820]③):TaskRequest.scratchpadDir 壳供半场已接(env-facts.acceptShellScratchpadDir 验收门;
+            // 单用户 + host lane 生效,拒收形回落自算)。TRUE=键会被消费(而非静默丢),不是「必然生效」。
             scratchpadDir: true,
             subagentSteer: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
+            // design/122 (core 1.225): body.retainSubagentSessions accepted + POST /v1/runs/:id/subagents/:target/resume
+            // routes (same gate as steer — the verbs share the registry + run store; retain-off runs 409 resume.retain_off).
             subagentResume: Boolean(deps.subagentSteerRegistry) && Boolean(deps.runStore),
+            // TaskRequest.settings (client per-request SemaSettings stamp) → projected into the engine TIGHTEN-ONLY
+            // (deny-wins, after the deployment + operator baseline). v1 wires permissions + permissionMode (default/
+            // acceptEdits/plan — `bypassPermissions` is NEVER honored from settings) + model + outputStyle. `env` is
+            // DEFERRED (TaskSpec deliberately has no per-task env injection) — advertised here so the client never
+            // silently loses a setting (it can warn the user / withhold those fields).
+            // `hooks`(hook-runner 阶段一):TRUE 当本部署会真跑 hook 命令 = 单用户闸(hook 命令跑在
+            // worker host,class ② 能力授予;resolveSpec 的 taskHooks 装配同一谓词)。多租户 = false(收到警告忽略)。
             taskSettings: { permissions: true, permissionMode: true, model: true, outputStyle: true, env: false, hooks: deps.config.requirePrincipal !== true },
+            // [1476] R1 / [1478] R2: TaskRequest.appendSystemPrompt is accepted top-level → TaskSpec.appendSystemPrompt
+            // (first-class lane for the shell's product-knowledge block). A shell probes THIS flag: false/absent ⇒ fall
+            // back to the settings.outputStyle ride-along (older servers fold that into the same spec field).
             appendSystemPrompt: true,
+            // [1479]① TaskRequest.compactionModel → TaskSpec.compactionModel (design/145 cheap compaction gear;
+            // catalog-gated like body.model). Probe this before offering the picker — older servers drop the field.
             compactionModel: true,
+            // [1488]③(b): GET /v1/runs/:id/subagents/:handle/output — a BACKGROUND child's (a… agent handle) final
+            // report body + status via the core TaskRegistry (the TaskOutput-tool face over HTTP; bg children are
+            // never in the run store and bg_notification only carries a summary). background_agent ONLY (codex R1
+            // type gate — wa… workflow rows read via the workflow journal). Replica-local like steer.
             subagentOutput: Boolean(deps.subagentTaskOutput) && Boolean(deps.runStore),
+            // S2([1520]{core},server 1.251): GET /v1/runs/:id/subagents/:handle/stream — per-agent live tail
+            // (SSE;core 1.370 bgAgentId 路由键)。「replay+tail」的 tail 半场(replay=subagentOutput 面);
+            // live 帧 replica-local(帧只在宿主 run 所在副本产生),meta 帧如实声明。同门同寻址同 404 形。
             subagentStream: Boolean(deps.subagentTaskOutput) && Boolean(deps.runStore),
+            // [1499] CC TaskOutput/TaskStop 人侧对位: GET/POST /v1/runs/:id/tasks/:handle/{output,stop} — the
+            // GENERIC background task-handle verbs (b* bash stdout consuming the cursor, m* monitor batches, a*
+            // agent final report; workflow handles refused — journal face owns them). SESSION-enforced from birth
+            // (?session= required on a session-bound run). Replica-local like subagentOutput.
             taskHandles: Boolean(deps.taskHandleOutput) && Boolean(deps.taskHandleStop) && Boolean(deps.runStore),
+            // [876] per-task subagents (core 1.295 body.agents → TaskSpec.agents): honored on SINGLE-USER deployments
+            // only — multi-tenant has no per-tenant caps face yet, so it's fail-closed there (resolveSpec warns +
+            // ignores; same predicate as mcpInjection/hooks so the shell never pretends its agent bundle took effect).
+            // ⚠️ Semantics = "the HTTP face accepts + forwards the field", NOT "every scenario honors it": scenarios
+            // without a delegation tool (scan/oa/…) fail-loud in core prepare (`config.agents.no_delegation_tool`) —
+            // a per-scenario projection needs the capability face to know the requested scenario (it doesn't; next batch).
             taskAgents: deps.config.requirePrincipal !== true,
+            // [854]② body.retainBackgroundProcesses → TaskSpec.retainBackgroundProcesses: a resource-residency grant
+            // (task-end keeps session bg processes alive), single-user gate like backgroundShell/hooks — multi-tenant
+            // warns + ignores, advertised false here so the shell greys the affordance.
+            // ⚠️ Best-effort per env lifecycle: on an isolated env destroyed at task end (e2b/k8s/local-docker/ephemeral
+            // host) core skips retention (`ownedEnvDying`, dist-read) — the grant only means anything where the env outlives the task.
             retainBackgroundProcesses: deps.config.requirePrincipal !== true,
+            // [922]①/[915]② core 1.296 interactiveTools 三态旋钮经 body 透传(per-run 工具面选择,无租户门)——
+            // 壳 capability 探测门用(旧 server 剥字段,壳 fail-soft 白发;此旗=真转发)。
             interactiveTools: true,
+            // [#40 / TOC cwd seam] TRUE when this deployment HONORS a caller-supplied `cwd` (the agent's host workspace =
+            // the TOC launch dir) — only the single-user `host` lane (task-cwd.ts cwdHonored). FALSE on cloud/container
+            // lanes + multi-tenant (cwd ignored there) so the shell never pretends `sema` operates on the project dir.
+            // Also gates `body.additionalDirectories` (CC --add-dir, design/119) — SAME host-lane trust boundary (extra
+            // host paths the file tools may read), so one flag covers both project-context host seams (no fragmentation).
             projectContext: cwdHonored(deps.config),
+            // [R3 / TOC MCP seam] TRUE when this deployment HONORS a caller-supplied `mcpServers` (the TOC local
+            // `.mcp.json`) — any SINGLE-USER deployment (task-mcp.ts mcpInjectionHonored = `requirePrincipal!==true`), on
+            // ANY execution lane. FALSE on multi-tenant (per-request MCP ignored) so the shell never pretends its `.mcp.json` took effect.
             mcpInjection: mcpInjectionHonored(deps.config),
+            // E8 (shell-host contract): per-model usage echo on TaskStats.modelUsage — sourced from durable model_usage events,
+            // so it requires BOTH the durable run store AND the tracker that feeds them (a store-without-
+            // tracker deploy would otherwise lie). Absent either → the shell shows aggregate cost only.
             modelUsage: Boolean(deps.runStore && deps.modelUsage),
+            // E11 (shell-host contract): GET /v1/sessions/:id/init startup bundle. Pure config assembly (model+mode), always
+            // served (no 501 path) — safe unconditionally, like policy:true.
             sessionInit: true,
+            // E9 (shell-host contract): GET /v1/sessions/:id/mcp materializes MCP server status on demand. The route is always
+            // served (returns an empty panel when no MCP is configured), so the query capability is unconditional.
             mcp: true,
+            // E23 (shell-host contract): inbound MCP elicitation HITL — true ONLY when the onElicit producing path is wired
+            // (MCP_ELICITATION_ENABLED), so "says yes but no-ops" is impossible. Per-server opt-in (McpServerSpec.
+            // elicitation, default OFF) is the second, orthogonal gate; this flag advertises the deployment capability.
+            // SCOPE: elicitation fires only on the streaming + durable run legs (POST /v1/tasks/stream, POST /v1/runs,
+            // and a durable resume) — a synchronous POST /v1/tasks, a verify/cascade attempt, and leader sub-tasks have
+            // no live stream to surface a prompt on, so an elicitation there fail-closed DECLINES (honest, not a hang).
             mcpElicitation: Boolean(deps.elicitation),
+            // §4④: AskUserQuestion LIVE HITL — true ONLY when the onQuestion producing path is wired
+            // (ASK_QUESTION_ENABLED). Same SCOPE as mcpElicitation (streaming + durable legs; a synchronous /v1/tasks or a
+            // sub-task with no live stream headless-defaults — honest, not a hang). The durable-disconnected-human leg is
+            // always available (createDurableQuestionPolicy on the durable path), independent of this live capability.
             askUserQuestion: Boolean(deps.question),
+            // [816]/[820]②: live tool-approval HITL — true ONLY when the onAsk producing path is wired
+            // (TOOL_APPROVAL_ENABLED). LIVE sync-stream leg only; since [879] G1 (OnAsk 三值化) every other leg
+            // (no ALS context / undeliverable card) returns "unavailable" → core durable-parks where a checkpoint
+            // exists, and only fail-closed denies without one ([819]⑤). The durable-approval leg (checkpoint park +
+            // /decide) is independent of this.
             toolApproval: Boolean(deps.toolApproval),
+            // [1469] POST /v1/side-query(core 1.361 Runner.sideQuery 包装):一次性 brain 路由问答,无 session
+            // 副作用。恒可用(runner 自带)——探测位供壳判「引擎腿在」而非 trial-by-404。
             sideQuery: true,
+            // E16/E17/E21 (§0.5 session-ownership): list/fork/delete are homed on the durable SESSION abstraction.
+            // Each flag is true ONLY when its PRODUCING path exists (never a bare const) — list needs an enumerator
+            // (session store OR legacy run-store aggregate), fork needs sessionStorage.fork, delete needs the
+            // purgeSession coordinator. Absent backend (in-memory dev) ⇒ false, so "says yes but 501s" can't happen.
             sessionList: Boolean(deps.sessionStorage?.listSessions ?? deps.runStore?.listSessions),
-            sessionSearch: Boolean(deps.sessionStorage?.listSessions ?? deps.runStore?.listSessions),
+            sessionSearch: Boolean(deps.sessionStorage?.listSessions ?? deps.runStore?.listSessions), // GET /v1/sessions?q= (all lister backends carry it)
             sessionFork: Boolean(deps.sessionStorage?.fork),
             sessionDelete: Boolean(deps.purgeSession),
+            // E18 (shell-host contract): resume-at (rewind to a prior message). True ONLY when BOTH the eventId→entryId anchor map
+            // (resumeAnchorStore) AND the leaf-read path (sessionStorage.getLeafId, the §0.5 durable session abstraction)
+            // exist — so a `resumeAt` submit can be resolved + captured. "Says yes but 4xx/no-ops" is impossible. Works
+            // local + cloud (the anchor store is present on all backends); false only on the env-only/no-backend worker.
             resumeAt: Boolean(deps.resumeAnchorStore && deps.sessionStorage?.getLeafId),
+            // E12 (shell-host contract): opt-in post-completion prompt suggestions (body.suggestNextPrompts → a `suggestions` event
+            // on the run's events tail). A core 1.128 runner feature, no store dependency → always available on a worker.
             promptSuggestions: true,
+            // E6 (shell-host contract): operator-tightened per-session tool rules (PUT/GET /v1/sessions/:id/policy + core reads them
+            // at prepare-time, subtract-only). True when the durable/local SessionPolicyStore is wired.
             sessionPolicy: Boolean(deps.sessionPolicyStore),
+            // E19 (shell-host contract): rewind-files (body.rewindFiles → snapshot per turn + restore on a resumeAt branch). core's
+            // gate-split (1.134.0) snapshots for ANY ExecutionEnv when fileSnapshotStore is wired (host/local-mode +
+            // e2b/k8s/ssh/adb/local-docker all active) → advertise whenever the store is wired.
             rewindFiles: Boolean(deps.fileSnapshotStore),
+            // R8 code-only rewind (CC "Restore code", core 1.166 body.rewindFilesTo → restore files to a prior user message
+            // WITHOUT forking). Needs BOTH the snapshot store (to restore) AND the anchor map (to resolve the target handle),
+            // so it's the conjunction of `rewindFiles` and `resumeAt` — "says yes ⟺ the code-only submit resolves + restores".
             rewindFilesTo: Boolean(deps.fileSnapshotStore && deps.resumeAnchorStore && deps.sessionStorage?.getLeafId),
+            // R7 自唤醒 (CC parity): the self-wake scheduler is LIVE — the host env exposes core's SchedulerCapability
+            // (CronCreate/CronDelete/CronList mount——L8 订正旧名) and the TOC shell daemon should run to fire due intents. True
+            // only on the single-user host lane with SCHEDULER_ENABLED (multi-tenant routes scheduling to center).
             scheduler: Boolean(deps.config.schedulerEnabled && deps.config.requirePrincipal !== true && deps.config.remoteExec?.provider === "host"),
+            // 2c session-sync (P1d): the /v1/sessions/:id/sync/* peer routes (manifest/blobs/import/plan). True only when
+            // the whole backend + the entry export seam + a snapshot store are all wired (so export/import + blob transfer
+            // all resolve) — absent backend ⇒ false (the routes 501); "says yes ⟺ route works".
             sessionSync: Boolean(deps.backend && deps.sessionStorage?.exportEntries && deps.fileSnapshotStore),
+            // SendUserFile(S3 双轨公网直链,契约 settled 2026-07-14):flag=READY 语义(F7 codex 审)——
+            // emitter 存在(=工具真挂载,lane/租户/签发面三门在 main.ts 已判)∧ 公网端点在场(publicEndpoint
+            // 缺席时 issue()/prepareDirectUpload() 一律 fail-loud,工具挂着也必失败)。"says yes ⟺ 调用真能
+            // 成功":只看 config.sendUserFile(签发面已配)会在工具缺席的形态(adb/local-docker lane、多租户
+            // host/ssh)假 yes(配置自查 agent 抓获 2026-07-14);只看 emitter 会在无公网端点时假 yes。
+            // s3PublicEndpoint=web 渲染/拼接要的公网 base(bootstrap 单一真源判决——server 透出,web 不猜、
+            // 不走 registry env 双源;工具挂不挂载它都照透——纯感知面,web 可提前接线)。
             sendUserFile: Boolean(deps.sendUserFile && deps.config.sendUserFile?.publicEndpoint),
             s3PublicEndpoint: deps.config.sendUserFile?.publicEndpoint ?? null,
+            // SendUserFile 账本(多租户治理面):true ⇔ 签发面已配 + store backend 在(记账写点活 + GET
+            // /v1/sendfile-links 可列)。false = env-only worker(不记账,读面 501)——诚实缺席。
             sendUserFileLedger: Boolean(deps.sendFileLedger),
+            // K-2 (shell §K) — core ruling = SPLIT into two ORTHOGONAL axes so the shell gates each honestly:
+            //  • `workflows` = ENGINE-CAN (can the engine self-orchestrate / run ultracode) = core's single-source
+            //    `workflowsCapability(deps)` (hardened script runner ∧ governance), boot-computed in main.ts. Falls back
+            //    to the `Boolean(workflowRunStore)` proxy when the boot flag isn't wired (older callers / tests).
+            //  • `workflowsList` = can durably LIST workflow runs = `Boolean(workflowRunStore)` (GET /v1/workflows* 501s
+            //    without it — list AND detail/stream, see the store gate ~L731).
+            // ⚠️ In the CURRENT service wiring these two COINCIDE: `workflowRunStore` is built IFF self-orchestration is on
+            // (InMemoryWorkflowRunStore when WORKFLOW_RUN_STORE=memory, else File — main.ts ~L527), the SAME gate that
+            // wires the safe script runner `workflowsCapability` checks → `Boolean(workflowRunStore)` ≡ `workflowsCapability`
+            // always today. So this split is core's FORWARD-LOOKING orthogonal-axes CONTRACT, NOT a fix for a live
+            // divergence (the earlier "memory backend → no store → divergence" framing was WRONG — InMemory IS a store;
+            // double-review caught it). It becomes load-bearing only if a future wiring decouples them (e.g. a run store
+            // present without a safe runner → engine-not-capable but listable). Both values are correct today.
             workflows: deps.workflowsCapable ?? Boolean(deps.workflowRunStore),
             workflowsList: Boolean(deps.workflowRunStore),
+            // K-1c (shell §K): manual /compact verb (POST /v1/runs/:id/compact → core 1.156 TaskStream.compact()). Needs
+            // the runs ledger (live-run lookup); advertise on runStore presence so the shell un-greys /compact only where
+            // the endpoint exists (it 409s for a non-live run, 501s without the store). core ≥1.156 guaranteed by the pin.
             manualCompact: Boolean(deps.runStore),
         });
         return;
     }
+    // Model catalog for consumers (e.g. OA's @-model autocomplete). NON-secret: names/capabilities
+    // only — never baseUrl/apiKey. `name` is the `@handle`; any of these may be @-mentioned. Source
+    // today = env-derived config.models; later the sema registry (sema-registry). The internal
+    // `default` alias is hidden (it's a fallback ref, not a user-pickable model).
     if (req.method === "GET" && url === "/v1/models") {
         const models = Object.entries(deps.config.models)
             .filter(([name]) => name !== "default")
@@ -97,10 +283,25 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
             provider: m.provider,
             reasoning: m.reasoning,
             vision: Array.isArray(m.input) ? m.input.includes("image") : false,
+            // E4 (shell-host contract): the context-window DENOMINATOR for the "% context used / N tokens until
+            // compact / low-context warning" gauge. Pure passthrough of the Model the service already holds
+            // (config.ts:603-604). Soft-degrade — omit when unknown (0) so the shell renders a raw token count
+            // without a %. The NUMERATOR (turn_end.usage.contextTokens) is core-blocked (SERVICE-GAP-DOSSIER §2 row 4);
+            // the denominator ships now with zero core dependency.
             ...(m.contextWindow ? { contextWindow: m.contextWindow } : {}),
             ...(m.maxTokens ? { maxOutputTokens: m.maxTokens } : {}),
+            // E7 (shell-host contract): the `/effort` picker's options. core's authoritative default tier set
+            // (DEFAULT_EFFORT_LEVELS = minimal/low/medium/high) for a reasoning model; omitted for a non-reasoning
+            // model (effort doesn't apply). The accept-set on a request is broader (any core ThinkingLevel) — this is
+            // the advertised picker default, not a hard allow-list.
             ...(m.reasoning ? { supportedEffortLevels: [...DEFAULT_EFFORT_LEVELS] } : {}),
         }));
+        // [865]③ id/name 撕裂消解:`default` 历史上是 **id 形**(壳面板行 value 却是 name 形,壳侧只能打补丁
+        // 拼回)。additive 双给:`default` 保持 id 形字节不动(既有消费者),新 `defaultModel = { id, name }`
+        // 一次给全。name = 目录里与 config.model 同一实例的键("default" 别名除外;registry 未生效的 env 单模型
+        // 目录也可能无命中 → 退 id 匹配,再退 undefined 时省略 name)。
+        // 双程匹配(codex M1):先引用相等(applyEffective 后 config.model 与目录真身同实例——重复 id 目录下
+        // 唯一无歧义的判据),仅 env 单模型 lane 等无引用命中时才退 id 匹配(目录序第一,确定性)。
         const nonAlias = Object.entries(deps.config.models).filter(([n]) => n !== "default");
         const defaultName = (nonAlias.find(([, m]) => m === deps.config.model) ?? nonAlias.find(([, m]) => m.id === deps.config.model.id))?.[0];
         sendJson(res, 200, { models, default: deps.config.model.id, defaultModel: { id: deps.config.model.id, ...(defaultName ? { name: defaultName } : {}) } });

package/dist/http/routes/fleet.d.ts

@@ -1,3 +1,9 @@
+/**
+ * design/158 A9 域模块 —— MF-Fleet 实时舰队流。
+ *
+ * 路由:`GET /v1/fleet/stream`(SSE PUSH:连上先快照,之后每条 per-row delta)。跑在服务凭据门**之前**
+ * (按 principal 自门,与 workflow 只读路由同列)。本域零可变状态。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleFleet(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;

package/dist/http/routes/fleet.js

@@ -6,38 +6,79 @@ export async function handleFleet(req, res, url, ctx) {
     await handleFleetBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
+/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
+ *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleFleetBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { sessionOwnerScope } = ctx.helpers;
-    void url;
+    void url; // 本域按 `req.url` 的完整 pathname 判路(带 query),`url` 只为域入口签名一致
+    // MF-Fleet (shell-host data contract): GET /v1/fleet/stream — the LIVE multi-row task/workflow fleet view as
+    // an SSE PUSH stream (status/elapsed/tokens/doneCount transitions over time). Owner-gated by scope (the
+    // caller's own active runs) UNLESS fleet-wide (a deployment trace/auth token sees every tenant's rows, like
+    // the trace API). Before the service-credential gate (self-gates by principal), parity with the workflow routes.
     if (req.method === "GET" && new URL(req.url ?? "", "http://x").pathname === "/v1/fleet/stream") {
         if (!deps.fleetBus) {
             sendError(res, 501, "capability.self_orchestration_required", "fleet stream requires self-orchestration / fleet wiring");
             return;
         }
-        const { fleetWide } = sessionOwnerScope(req);
-        const principal = gatedPrincipal(req, deps.config);
+        const { fleetWide } = sessionOwnerScope(req); // trace-token / system authToken ⇒ fleet-wide (all tenants)
+        const principal = gatedPrincipal(req, deps.config); // direct-door-safe identity (NOT the spoofable header)
         if (deps.config.requirePrincipal && !principal && !fleetWide) {
             sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
             return;
         }
+        // #3 fleet per-session scope (clay 2026-06-30): the shell sends its current sessionId as `?session=` to see ONLY
+        // this session's rows (not other sessions of the same principal — the "他会话 token" leak). Absent ⇒
+        // unscoped (all of the principal's rows — back-compat).
+        // 🔴 cli[1524] HIGH-1(V5c 回归锁首跑抓获):此前 fleetWide 把 callerSession 也强制 null——无 auth
+        // 部署(isFleetWide 第一臂:无 token/无 traceToken/无 requirePrincipal=恒 fleetWide,TOC loopback
+        // 默认形全中)下会话过滤/通知 fail-closed 门整体旁路成全量广播,而 meta 的 bgNotifyFailClosed 照报
+        // true=标说谎;1.245 的注入 fail-closed 与 1.247 的代际标在默认部署从未真正生效(一直是壳侧台账
+        // 在兜)。修:fleetWide 是**能力上限**(可看全量=豁免 scope 授权轴),不是「强制 unscoped」——
+        // 显式带 `?session=` 的请求无论 fleetWide 与否都按会话过滤(观察者要全量=不带 session;要跟单
+        // 会话且不烧 durable 副本=带 session+observe=1,既有防烧口)。meta 的 sessionScoped 由此自动如实,
+        // bgNotifyFailClosed 对 session-bound 连接从此真实。
         const fleetParams = new URL(req.url ?? "", "http://x").searchParams;
         const callerSession = fleetParams.get("session");
+        // `?observe=1` = a session-bound lane that must NOT serve-fence the durable copy
+        // (a non-shell observer following one session). Default (absent) keeps the frame-即-投递 semantics —
+        // today's only session-bound consumer IS the model-injecting shell.
         const observeOnly = fleetParams.get("observe") === "1";
         await streamFleet(req, res, deps.fleetBus, fleetWide ? null : (principal ?? "default"), callerSession || null, observeOnly ? undefined : deps.workflowCompletionInbox);
         return;
     }
     miss.fell = true;
 }
+/** MF-Fleet: SSE the live fleet (active task + workflow rows) — a SNAPSHOT on connect, then every per-row delta
+ *  the {@link FleetEventBus} fans out. `callerScope === null` ⇒ fleet-wide (a trace/auth token sees all tenants);
+ *  else owner-scoped (only rows whose `scope` matches). The tenant-internal `scope` field is STRIPPED from every
+ *  emitted row (it's a gate input, never rendered). A removal is forwarded ONLY for a row this connection actually
+ *  saw (no id-existence oracle for an unseen tenant's run). Heartbeat + dual-close cleanup unsubscribe the bus. */
 function streamFleet(req, res, bus, callerScope, callerSession = null, completionInbox) {
     return new Promise((resolve) => {
         sseHeaders(res);
+        // [1508] 1.247 `bgNotifyFailClosed` — the GENERATION marker cli asked for ([1500]📌/[1502] F2): declares
+        // this server's bg_notification injection path fails CLOSED for scoped subscribers (1.245+ [1493] fix), so
+        // a new-generation shell can drop its frame-level own/foreign checks entirely (incl. the cross-shell
+        // restart edge) while keeping them against older servers whose meta lacks the field. Additive (version
+        // stays 1): older shells ignore unknown fields.
         res.write(`event: meta\ndata: ${JSON.stringify({ version: 1, scoped: callerScope !== null, sessionScoped: callerSession !== null, bgNotifyFailClosed: true })}\n\n`);
         const seenTasks = new Set();
         const seenWf = new Set();
+        // #3 fleet per-session scope (clay 2026-06-30): a row is visible iff it matches the caller's principal scope AND
+        // — when the caller sent `?session=` — its `sessionId`. A row WITHOUT a sessionId stays visible (back-compat for
+        // unscoped rows); the leak this closes is a row whose sessionId is ANOTHER session of the same principal.
         const sessionOk = (rowSession) => callerSession === null || rowSession === undefined || rowSession === callerSession;
         const visT = (r) => (callerScope === null || r.scope === callerScope) && sessionOk(r.sessionId);
         const visW = (r) => (callerScope === null || r.scope === callerScope) && sessionOk(r.sessionId);
+        // [1493] fable5 R1 (display plane): an UNATTRIBUTED row (no sessionId — restart lazy-mint / core version
+        // skew edges; post-Part-A every normal spawn is tagged) stays fail-open VISIBLE to a scoped subscriber
+        // (liveness back-compat: your own row after a restart still shows as running), but its content fields are
+        // conversation-derived text — `name` is the objective preview, `description`/`agentType`/`agentName` label
+        // the ask, `currentAction` is a live tool line. None of that may cross the session boundary, so a SCOPED
+        // subscriber gets a content-scrubbed projection (ids/status/progress/timing kept); a fleet-wide observer
+        // (trace/dashboard, callerSession === null) keeps the full row. Rows tagged with the caller's own session
+        // pass sessionOk and are never scrubbed (r.sessionId present ⇒ it equals callerSession here).
         const stripT = (r) => {
             const { scope: _s, sessionId: _sid, ...rest } = r;
             if (callerSession !== null && r.sessionId === undefined) {
@@ -56,6 +97,7 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
         };
         const send = (event, data) => { if (!res.writableEnded)
             res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); };
+        // connect-time snapshot (filtered + scope-stripped) — the visible rows become this connection's "seen" set.
         const snap = bus.snapshot();
         const tasks = snap.tasks.filter(visT);
         const workflows = snap.workflows.filter(visW);
@@ -85,35 +127,81 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                         send("workflow_remove", { id: frame.id, ts: frame.ts });
                     break;
                 case "hook_notice": {
+                    // cli [1786]:一次 hook 判定**未能完成**的观测帧。可见性与 bg_notification **同为 fail-CLOSED** ——
+                    // 一条关于**别人会话**的「这轮没看住」落到这个壳上,会让用户以为是自己这轮出了问题
+                    // (而且 `/goal enforced` 面板会据此说一句不属于这个会话的话)。
+                    // ⇒ scoped 订阅方只收能证明是自己的:`ownerSessionId === callerSession`;`undefined` ⇒ **丢弃**。
+                    //   fleet-wide 观察者(callerSession === null:trace/dashboard)照收。
                     const hn = frame.notice;
                     const hScopeOk = callerScope === null || hn.ownerScope === callerScope;
                     const hSessionOk = callerSession === null || hn.ownerSessionId === callerSession;
                     if (hScopeOk && hSessionOk) {
                         const { ownerScope: _hs, ownerSessionId: _hsid, ...wire } = hn;
+                        // 与 bg_notification 同一帧契约:`type` 也放进 payload(壳的帧桥按 data.type 分派)。
                         send("hook_notice", { type: "hook_notice", ...wire, ts: frame.ts });
                     }
                     break;
                 }
                 case "bg_notification": {
+                    // design/129-B 缺口②(帧契约): a bg child's completion pushed on THIS always-open lane — the
+                    // idle shell renders the receipt immediately (no more one-input-cycle durable-drain lag). Visibility:
+                    // tenant filter on ownerScope (same rule as rows; a notification without one is operator/fleet-wide
+                    // visible only — fail-closed for scoped callers) + `?session=` on ownerSessionId (the HOST session;
+                    // the payload sessionId is the CHILD's uuid — the contract's stable anchor — and never matches the caller's).
                     const n = frame.notification;
                     const scopeOk = callerScope === null || n.ownerScope === callerScope;
+                    // [1493] fail-CLOSED on the MODEL-INJECTION path. bg_notification is auto-injected into the idle
+                    // shell's model (the receipt drives the LLM's next turn). Unlike the display rows — whose absent-
+                    // session `sessionOk` stays fail-OPEN for back-compat (an untagged row is at worst visible, never
+                    // actionable) — an untagged completion delivered to a SCOPED subscriber would inject a DIFFERENT
+                    // session's result into this shell's model (clay's dual-shell repro: two shells sharing one engine +
+                    // principal). So a scoped caller (callerSession !== null) receives a completion ONLY when it is
+                    // provably its own: ownerSessionId === callerSession. undefined ⇒ NOT proven ⇒ dropped. A fleet-wide
+                    // observer (callerSession === null: trace/dashboard) still sees everything. Part A (fleet-bus) is what
+                    // populates ownerSessionId for the legit owner so this gate delivers to it and drops only strangers.
                     const sessionInjectOk = callerSession === null || n.ownerSessionId === callerSession;
                     if (scopeOk && sessionInjectOk) {
                         const { ownerScope: _os, ownerSessionId: _osid, ...wire } = n;
+                        // The frame contract puts `type:'bg_notification'` INSIDE the object (the shell's frame
+                        // bridge dispatches on data.type, not only the SSE event name) — carry it in the payload too.
                         send("bg_notification", { type: "bg_notification", ...wire, ts: frame.ts });
+                        // The frame IS the delivery when it reaches the OWNING shell's session-bound lane —
+                        // serve-fence the durable park (both orders hold: an already-parked entry is acked; a park landing
+                        // AFTER this is refused by the serve fence) so the next stream-open drain can't re-inject the same
+                        // completion into the model (the engine-side steer-inject double the shell cannot dedup — the
+                        // 129-bg variant of that double-injection class, proven from real session logs). ONLY a `?session=`-bound subscriber counts: a fleet-wide
+                        // dashboard consuming the frame must NOT burn the owning shell's durable copy — the park keeps its
+                        // offline/no-active-lane semantics. Keys line up by contract: frame taskId = BackgroundChildEvent
+                        // .taskId = the a*-domain registry handle (stable across kinds) = the parked entry's
+                        // runId (leg onTaskNotification's n.task_id, same domain); ownerSessionId = HOST session = entry key.
+                        // design/144 键升级:park 键=域:taskId:status[#seq],fleet 帧不带 seq → 传家族前缀
+                        // (taskNotificationFoldKey 无 seq 形),markTerminalServed 家族 ack 清同族 seq 键成员。
+                        // PAIR-REVIEW F-2:mark 延至 **write flush 回调** + socket 存活双检——「res.write 已调用」≠投递
+                        // (对端已断本端未感知的窗口里,帧写进死 socket 而 durable 副本被烧=通知永丢,1.334 教训)。
+                        // flush 回调=数据出到内核缓冲(尽力而为的最强本端信号;真端到端 ack 需协议位,另议),回调时
+                        // 再验 socket.destroyed——断连时 Node 会先触发 destroy,此时不 ack,park 副本留给下次开流 drain。
+                        // fence 的防双注入语义不变(已 ack 的重复帧仍被拒),只推迟 ack 时点。
                         if (completionInbox && n.ownerSessionId && callerSession !== null && callerSession === n.ownerSessionId && !res.writableEnded) {
                             const ownerSid = n.ownerSessionId;
+                            // codex R1-H1(修车批):帧带 seq(1.239/core 1.352)→ **精确键** ack(servedAt 只 fence 该
+                            // 周期;revive 周期 N+1 的 park/enqueue 不被连坐)。legacy 无 seq 帧保持家族键 ack(原语义)。
                             const family = taskNotificationFoldKey({ task_id: n.taskId, status: n.status, ...(n.seq !== undefined ? { seq: n.seq } : {}) });
+                            // codex R2-H1(server belt):revive 周期的 park 键在 **uuid 域**(core ≤1.353 的 revive 通知
+                            // task_id=childSessionId,subagent.js:598/655——identity 对齐转 core 在单),帧键在 a\* 域——
+                            // 单键 ack 必 miss=开流二次注入。帧带 sessionId(uuid 别名)时**双域各 ack 一次**,两种 core
+                            // 版本的 park 键都被 fence 住;core 修齐后 uuid 臂自然空转(无同键 park,无害)。
                             const familyUuid = n.sessionId !== undefined && n.sessionId !== n.taskId
                                 ? taskNotificationFoldKey({ task_id: n.sessionId, status: n.status, ...(n.seq !== undefined ? { seq: n.seq } : {}) })
                                 : undefined;
                             const ackIfAlive = () => {
                                 if (res.writableEnded || res.socket?.destroyed)
-                                    return;
+                                    return; // 死连接:不烧 durable 副本
                                 void completionInbox.markTerminalServed(ownerSid, family).catch(() => undefined);
                                 if (familyUuid !== undefined)
                                     void completionInbox.markTerminalServed(ownerSid, familyUuid).catch(() => undefined);
                             };
+                            // res.write 的 flush 回调在上面 send() 内不可达(send 不透传 cb)——补一个零字节注释帧承载回调:
+                            // SSE 注释行(`: ack\n\n`)对消费者不可见(SDK 吞注释),flush 语义等同。
                             res.write(`: ack
 
 `, ackIfAlive);
@@ -122,9 +210,10 @@ function streamFleet(req, res, bus, callerScope, callerSession = null, completio
                     break;
                 }
                 default:
-                    break;
+                    break; // snapshot frames are connect-time only, never fanned out
             }
         });
+        // Real frame (not an SSE comment) — a per-frame-parsing BFF drops comments (zero-frame window downstream)
         const hb = setInterval(() => { if (!res.writableEnded)
             res.write(`event: heartbeat\ndata: {}\n\n`); }, 15_000);
         if (typeof hb.unref === "function")