@sema-agent/server 7.43.0 → 7.44.0

package/dist/http/routes/sessions.js

@@ -10,29 +10,14 @@ import { sendJson, sendError, sseHeaders } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
 const MCP_STATUS_TTL_MS = 5_000;
 const MCP_MATERIALIZE_TIMEOUT_MS = 10_000;
-// DESIGN-269 件4:A2A 读面的两枚同族时限。**刻意与 MCP 分开命名而不复用同一个常量**:两条腿的物化
-// 成本不同族(MCP 可能 spawn 子进程/开长连;A2A 只是几个 HTTPS 卡请求),将来任一侧要调窗时不该被
-// 另一侧的名字绑架。数值今天相同,语义各自独立。
 const A2A_STATUS_TTL_MS = 5_000;
 const A2A_MATERIALIZE_TIMEOUT_MS = 10_000;
-/** 面板上每个 peer 最多回多少条工具名(codex finding 5)。超出只截**表**,`toolCount` 仍是真数、
- *  `toolNamesTruncated:true` 显式说明 —— 消费端读得出「还有更多」,而不是拿到一份看着完整的假名单。 */
 const A2A_PANEL_MAX_TOOL_NAMES = 200;
 export function createSessionsLocal() {
     return {
-        // [1196] session-events SSE 活跃连接计数(连接帽谓词;帽=deps.sessionEventsMaxConnections ?? 256)。
         sseConnections: 0,
-        // 六轮复审:初始 owner 查探的**存储侧**并发许可——连接坑在 race 超时即还,但底层查询可能仍悬着
-        // (驱动级取消不可得);重连风暴下未决查询必须独立有界(64),超限=零存储触碰直接 503。
         sseOwnerLookups: 0,
-        // E9 (shell-host contract) — short-TTL single-flight cache for GET /v1/sessions/:id/mcp. materializeMcpTools connects to (or
-        // spawns) MCP servers; without this a burst of /mcp polls would re-connect every time (adversarial-review MEDIUM:
-        // resource-exhaustion on an unbounded panel-poll path). Keyed by (scenario, principal) so per-user RBAC stays
-        // correct; stores the in-flight PROMISE so concurrent first-polls collapse to ONE materialize. Bounded by TTL +
-        // a hard size cap (cleared on overflow). The cached value is the PROJECTED panel (no live connections held).
         mcpStatusCache: new Map(),
-        // DESIGN-269 件4 —— 同上那套(TTL + single-flight + 硬条数帽 + 按 (scenario, principal) 分键,因为
-        // `principalHeader` 注入让不同调用方看到的 peer 授权面可能不同),A2A 半场。
         a2aStatusCache: new Map(),
     };
 }
@@ -41,22 +26,15 @@ export async function handleSessions(req, res, url, ctx) {
     await handleSessionsBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
-/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(去缩进两格;sessions 另有一处见文件头说明)。
- *  裸 `return;` 的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。 */
 async function handleSessionsBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { readJson, safeDecode, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite } = ctx.helpers;
     const sse = ctx.local.sessions;
     const { mcpStatusCache, a2aStatusCache } = ctx.local.sessions;
-    // E11 (shell-host contract): GET /v1/sessions/:id/init — the one-call startup bundle, so the shell renders its
-    // banner from ONE request instead of fanning out to /v1/models + /v1/policy + /v1/capabilities. Worker-global
-    // config surface (same posture as /v1/policy): principal OPTIONAL, enforced only under REQUIRE_PRINCIPAL.
-    // ADDITIVE — `model` + `mode` are the load-bearing banner fields; `tools`/`agents`/`commands`/`cwd` are omitted
-    // today (tolerate-absent — the shell falls back to its mock-fill). `cwd` is live-only (E13) and never durable here.
     {
         const im = /^\/v1\/sessions\/([^/]+)\/init$/.exec(url);
         if (im && req.method === "GET") {
-            const principal = gatedPrincipal(req, deps.config); // F-fix: VERIFIED presence gate (direct-door JWT, not the spoofable header)
+            const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
@@ -69,15 +47,10 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    // E24 (shell-host contract): GET /v1/sessions/:id/settings — the effective merged settings view (CC /config read
-    // side). Worker-global config surface (principal optional unless REQUIRE_PRINCIPAL), same posture as /v1/policy +
-    // the E11 init bundle. `effective` = the resolved worker config the run obeys; `applied` echoes the resolved
-    // model. The PATCH half (runtime settings write) + per-source layering need a core seam (SERVICE-GAP-DOSSIER E24)
-    // — omitted today, so no `settings` write capability is advertised (honest: read route only).
     {
         const stm = /^\/v1\/sessions\/([^/]+)\/settings$/.exec(url);
         if (stm && req.method === "GET") {
-            const principal = gatedPrincipal(req, deps.config); // F-fix: VERIFIED presence gate (direct-door JWT, not the spoofable header)
+            const principal = gatedPrincipal(req, deps.config);
             if (deps.config.requirePrincipal && !principal) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
@@ -95,38 +68,25 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    // E9 (shell-host contract, core 1.124.0): GET /v1/sessions/:id/mcp — per-server MCP status for the `/mcp` panel.
-    // 🔴 core does NOT persist MCP connections (task-scoped), so there is no stored session MCP health. This
-    // MATERIALIZES the worker's configured MCP servers ON-DEMAND (a fresh connect → list → dispose, fail-open) and
-    // returns the projected statuses with `asOf` = THIS materialization moment. It is materialization-time status,
-    // NOT live session health (core §E9) — the shell renders "as of <asOf>". Worker-global config surface
-    // (principal-optional like /policy); the caller's gatedPrincipal is threaded for per-user MCP RBAC
-    // (principalHeader injection). Uses the DEFAULT scenario's MCP set (per-session scenario tracking is a follow-up).
     {
         const mm = /^\/v1\/sessions\/([^/]+)\/mcp$/.exec(url);
         if (mm && req.method === "GET") {
-            // F-fix: VERIFIED presence gate (direct-door JWT, not the spoofable header); per-user MCP RBAC already uses gatedPrincipal.
             if (deps.config.requirePrincipal && !gatedPrincipal(req, deps.config)) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
             }
             const specs = mcpForScenario(deps.config.mcpServers, deps.config.defaultScenario);
             if (!specs || specs.length === 0) {
-                sendJson(res, 200, { servers: [], asOf: new Date().toISOString() }); // no MCP configured → honest empty panel
+                sendJson(res, 200, { servers: [], asOf: new Date().toISOString() });
                 return;
             }
-            const principal = gatedPrincipal(req, deps.config); // threaded for per-user MCP RBAC (principalHeader injection)
+            const principal = gatedPrincipal(req, deps.config);
             const cacheKey = `${deps.config.defaultScenario}::${principal ?? ""}`;
             const cached = mcpStatusCache.get(cacheKey);
             if (!cached || Date.now() - cached.at > MCP_STATUS_TTL_MS) {
                 if (mcpStatusCache.size > 1024)
-                    mcpStatusCache.clear(); // hard size cap (per-principal keys) — crude but bounded
-                // Single-flight: store the in-flight promise so a burst of polls collapses to ONE materialize.
+                    mcpStatusCache.clear();
                 const panel = (async () => {
-                    // Bound the connect/list so a hanging MCP server can't pin the request; dispose the late resolver if it
-                    // eventually completes after the timeout (no connection leak). materializeMcpTools is fail-open per server.
-                    // #324:第 6 参接撤销台账 —— 展示面与引擎执行面同一权威(被撤服务器不再进面板;core 契约:
-                    // probe 抛错 fail-open + onProbeFailure 回调,这里缺席=沿 core 的 once-per-materialization notice)。
                     const matP = materializeMcpTools(specs, principal, undefined, undefined, undefined, deps.mcpRevocations);
                     let timer;
                     const mat = await Promise.race([matP.catch(() => null), new Promise((r) => { timer = setTimeout(() => r(null), MCP_MATERIALIZE_TIMEOUT_MS); })]);
@@ -134,7 +94,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                         clearTimeout(timer);
                     if (!mat) {
                         void matP.then((m) => m?.dispose().catch(() => undefined)).catch(() => undefined);
-                        return { servers: [], asOf: new Date().toISOString(), degraded: true }; // timed out / failed to materialize
+                        return { servers: [], asOf: new Date().toISOString(), degraded: true };
                     }
                     try {
                         return {
@@ -144,8 +104,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                                 status: s.status,
                                 ...(s.serverInfo ? { serverInfo: s.serverInfo } : {}),
                                 ...(s.toolNames ? { toolNames: s.toolNames } : {}),
-                                // E9 (review LOW): redact secret-shaped strings + bound length — raw MCP connect errors may carry
-                                // internal paths/config the shell needn't see (same redaction posture as tool output).
                                 ...(s.error ? { error: redactSecrets(String(s.error)).slice(0, 200) } : {}),
                             })),
                         };
@@ -160,17 +118,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    // [DESIGN-269 车1 件4] GET /v1/sessions/:id/a2a — per-peer A2A status for the shell's agent panel.
-    // 逐点对称上面的 /mcp 面(按需物化 → 投影 → TTL single-flight 缓存 → 超时竞速 + 迟到 dispose),
-    // 差别只在**投影形状**,而那是被裁定过的(设计稿 v1.2 §2.5,cli [4107] 采纳级意见):
-    //
-    // 🔴 **不发裸 `status`**。core 的 `A2aPeerStatus.status:"ready"` 的真语义是「本次探测时,卡取到了、
-    // skills 铸出来了」——A2A **不持连接**(每次调用都是独立 HTTPS 请求),所以它永远不是「peer 现在活着」。
-    // 一个叫 `status:"ready"` 的键发给三个消费端,必有一端渲成「在线」,而那句话我们证不了。所以投影的
-    // 键名自己承重语义:`cardFetched: boolean`(卡取到没有)+ `probedAt: number`(**本次**探测时刻)+
-    // 可选 `error`。「在线/离线」这个词在本读面结构性不存在,不是靠文档约束不许渲。
-    // `asOf` 与 `probedAt` 并存不是冗余:前者是**面板**的物化时刻(ISO,与 /mcp 同形,壳渲 "as of …"),
-    // 后者是**每个 peer** 的探测时刻戳(机器可读,消费端算新鲜度用)。
     {
         const am = /^\/v1\/sessions\/([^/]+)\/a2a$/.exec(url);
         if (am && req.method === "GET") {
@@ -180,19 +127,16 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             }
             const specs = a2aForScenario(deps.config.a2aPeers, deps.config.defaultScenario);
             if (!specs || specs.length === 0) {
-                sendJson(res, 200, { peers: [], asOf: new Date().toISOString() }); // no peers configured → honest empty panel
+                sendJson(res, 200, { peers: [], asOf: new Date().toISOString() });
                 return;
             }
-            const principal = gatedPrincipal(req, deps.config); // threaded for per-user peer authz (principalHeader injection)
+            const principal = gatedPrincipal(req, deps.config);
             const cacheKey = `${deps.config.defaultScenario}::${principal ?? ""}`;
             const cached = a2aStatusCache.get(cacheKey);
             if (!cached || Date.now() - cached.at > A2A_STATUS_TTL_MS) {
                 if (a2aStatusCache.size > 1024)
-                    a2aStatusCache.clear(); // hard size cap (per-principal keys)
+                    a2aStatusCache.clear();
                 const panel = (async () => {
-                    // Bound the card fetches so a hanging peer can't pin the request; dispose the late resolver if it
-                    // completes after the timeout (materializeA2aTools holds no socket, but its dispose IS the lifetime
-                    // statement — a tool that outlives this probe must fail loudly instead of calling a remote agent).
                     const matP = materializeA2aTools(specs, principal);
                     let timer;
                     const mat = await Promise.race([matP.catch(() => null), new Promise((r) => { timer = setTimeout(() => r(null), A2A_MATERIALIZE_TIMEOUT_MS); })]);
@@ -201,28 +145,18 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     const probedAt = Date.now();
                     if (!mat) {
                         void matP.then((m) => m?.dispose().catch(() => undefined)).catch(() => undefined);
-                        return { peers: [], asOf: new Date(probedAt).toISOString(), degraded: true }; // timed out / failed to materialize
+                        return { peers: [], asOf: new Date(probedAt).toISOString(), degraded: true };
                     }
                     try {
                         return {
                             asOf: new Date(probedAt).toISOString(),
                             peers: mat.statuses.map((s) => ({
                                 name: s.name,
-                                // 🔴 翻译点(唯一):core 的闭集 status → 承重键名。`"ready"` = 卡取到了 + skills 铸出来了。
                                 cardFetched: s.status === "ready",
                                 probedAt,
-                                // 卡自述的两串是 UNTRUSTED(core 已中性化+限长);端点是协商结果,诊断用。
                                 ...(s.agentName ? { agentName: s.agentName } : {}),
                                 ...(s.agentDescription ? { agentDescription: s.agentDescription } : {}),
-                                // 🔒 自审第三镜(泄密面):`endpoint` 是**卡自述**的协商结果 —— 远端可控文本,而且 URL 形
-                                // 天然能带 userinfo(`https://user:pass@host/rpc`,core 的 `new URL()` 原样保留)。core 对
-                                // name/description 有中性化+限长,对 endpoint 只验协议(http/https),所以脱敏与限长是**本
-                                // 读面自己的活**(投影是它的输出,不是 core 的)。2048 = 通用 URL 上限量级,越界的是病态值。
                                 ...(s.endpoint ? { endpoint: redactSecrets(String(s.endpoint)).slice(0, 2048) } : {}),
-                                // 🔴 codex 对抗复审 finding 5(medium,验真后采纳):技能**条数**是远端可控且无界的
-                                // (core 限单个名字的长度,不限卡里的条数;卡体上限 8MiB),而这条只读 GET 按
-                                // (scenario, principal) 分键缓存 ⇒ 多身份可放大。发**有界表 + 真计数 + 显式旗**,
-                                // 而不是静默截断:一个会撒谎的读面比一个大的读面更贵。
                                 ...(s.toolNames
                                     ? {
                                         toolCount: s.toolNames.length,
@@ -230,8 +164,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                                         ...(s.toolNames.length > A2A_PANEL_MAX_TOOL_NAMES ? { toolNamesTruncated: true } : {}),
                                     }
                                     : {}),
-                                // 与 /mcp 同规:原始错误可能带内部路径/凭据形 —— 脱敏 + 截断。
-                                // 🔒 `headers`/`principalHeader` 在本投影里**根本没有出口**(白名单式铸键,不是删黑名单)。
                                 ...(s.error ? { error: redactSecrets(String(s.error)).slice(0, 200) } : {}),
                             })),
                         };
@@ -246,16 +178,9 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    // [1075]② 会话追随轻探针:GET /v1/sessions/:id/head → { leafId }(+ ETag/304)。leafId=会话树叶
-    // 指针,任何 append 都变=天然版本号——web 空闲期低成本轮询(If-None-Match 命中=304 零 body),
-    // 变了才拉 tail 增量。刻意不做 session 级 SSE(真订阅需跨副本通知面,写可发生在任意副本而流挂在
-    // 某一副本——设计件另立;探针轮询 1-2s 一次的 304 成本≈零,先解「必须刷新」的主诉)。
-    // 顶层路由(只依赖 sessionStorage,不依赖 sessionAudit——audit 缺席的部署探针照常)。
     {
         const hm = req.method === "GET" ? /^\/v1\/sessions\/([^/]+)\/head$/.exec(url) : null;
         if (hm) {
-            // 二轮复审([1196] S1 邻案连修):方法必须 bind 宿主——SESSION_CACHE_TTL_SEC=0 时 sessionStorage
-            // 是裸 PG/TiDB 类实例,getLeafId 内用 this.pool,裸引用调用=TypeError 500。
             const getLeafId = deps.sessionStorage?.getLeafId?.bind(deps.sessionStorage);
             const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
             if (!getLeafId || !ownerOf) {
@@ -263,8 +188,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             const headSession = decodeURIComponent(hm[1]);
-            // 七轮复审:store 有 getHead 时用单行原子快照(owner 鉴权与 leafId 同拍——两独立读在
-            // delete/reclaim 缝里可鉴旧主发新叶);无 getHead 的旧 store 保持两读旧形(退化面照旧)。
             const getHead = deps.sessionStorage?.getHead?.bind(deps.sessionStorage);
             let owner;
             let leafId;
@@ -299,16 +222,9 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    // [1196] session 级 SSE 真订阅:GET /v1/sessions/:id/events —— `event: head` 推送(latest-wins),
-    // `?lastLeafId=` 为游标(等价 If-None-Match:相同则无初始帧),25s 心跳注释行。鉴权/存储门与 /head
-    // 完全同门;连接帽超限=503+Retry-After(消费方回落 /head 轮询,capabilities.sessionEvents 广告)。
     {
         const em = req.method === "GET" ? /^\/v1\/sessions\/([^/]+)\/events$/.exec(url) : null;
         if (em) {
-            // 二轮复审单源化:本路由**不再自读基线**——所有帧(含首帧)由 registry 按 rev 单调序 fan-out
-            // (replay-on-subscribe 给已知条目即时首帧;新条目首帧=首拍探针 ≤hotMs)。双源(自读基线 vs
-            // registry 缓冲)必然产生不可判序的回退帧,单源后该类竞序结构性不存在。getLeafId 由 registry
-            // 内部使用(main.ts 注入时已绑定宿主);路由只需 ownerOf 门。
             const ownerOf = deps.sessionStorage?.ownerOf?.bind(deps.sessionStorage);
             const watch = deps.sessionWatch;
             if (!deps.sessionStorage?.getLeafId || !ownerOf || !watch) {
@@ -316,17 +232,12 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             const evSession = decodeURIComponent(em[1]);
-            // codex 一轮生命周期状态机:①连接坑与 close 守卫在任何 await 之前同步建立(读存储期间断连不再
-            // 漏清/漏还坑);②每个 await 之后查 closed;③所有拒绝/异常路径经同一 release。
             if (sse.sseConnections >= (deps.sessionEventsMaxConnections ?? 256)) {
-                // 🔴 机器码而非裸 writeHead(2026-07-31 缝合审):这条 503 与 drain 的 503 走同一条流,
-                // 而 drain 的带 `errorCode:"draining"`(冻结契约)。没有码,消费端只能靠自由文本字面区分
-                // 「连接帽 ⇒ 回落 /head 轮询(自愈,保持连接策略)」与「该重连替换实例」—— 正是本仓要根除的姿势。
                 res.setHeader("retry-after", "5");
                 sendError(res, 503, "state.sse_connection_cap", "session-events connection cap reached — fall back to /head polling");
                 return;
             }
-            sse.sseConnections++; // 同步占坑(查+占同拍,慢读并发不再超卖);此后一切路径必经 cleanup 还坑
+            sse.sseConnections++;
             let hb;
             let unsubscribe;
             let closed = false;
@@ -342,10 +253,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             res.on("close", cleanup);
             req.on("close", cleanup);
             try {
-                // 五轮复审:初始 ownerOf 也受 stall 界(存储悬死时不许无限占坑——256 坑被悬死请求耗尽=合法
-                // 客户端全 503);超时=可重试失败(503+Retry-After),坑经 cleanup 归还。六轮复审:查询本体的
-                // 并发另行有界(sseOwnerLookups,许可在底层 settle 时才还)——race 只还连接坑不还查询许可,
-                // 重连风暴不得无界堆积未决存储查询。
                 const stallBound = deps.sessionEventsStallMs ?? 60_000;
                 if (sse.sseOwnerLookups >= 64) {
                     cleanup();
@@ -355,8 +262,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 }
                 sse.sseOwnerLookups++;
                 const ownerP = ownerOf(evSession);
-                void ownerP.catch(() => undefined).then(() => { sse.sseOwnerLookups--; }); // 许可随底层 settle 归还
-                // 七轮复审:race 计时器 settle 即清——高频开合不得每次拖 60s 计时器+闭包(unref 只保进程退出面)。
+                void ownerP.catch(() => undefined).then(() => { sse.sseOwnerLookups--; });
                 let stallTimer;
                 let owner;
                 try {
@@ -370,7 +276,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                         clearTimeout(stallTimer);
                 }
                 if (closed)
-                    return; // 读期断连:close 守卫已还坑,别再写已死响应
+                    return;
                 if (owner === "__stall__") {
                     cleanup();
                     res.setHeader("retry-after", "5");
@@ -387,20 +293,14 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const q = new URL(req.url ?? url, "http://x").searchParams;
-                const lastLeafId = q.get("lastLeafId"); // null=未带 ⇒ 恒发首帧;带了且首帧值相等 ⇒ 抑制(304 同义)
-                // 单源发射:全部帧来自 registry(rev 单调序),连接级 lastSent 去重;首帧抑制=首值命中
-                // lastLeafId 时只记不发(后续同值仍去重,更新值照发)。
+                const lastLeafId = q.get("lastLeafId");
                 let first = true;
-                let lastAccepted; // 去重基准(单源 rev 序,最新接受值)
+                let lastAccepted;
                 let lastWritten;
-                // 三轮复审背压:res.write 返回 false 即停写,只保「最新一格」待冲(latest-wins 恰是本契约),
-                // drain 冲洗;阻塞超时(缺省 60s)=消费者死/僵——断流(client 重连自愈),绝不无界积压。
                 let writeBlocked = false;
                 let blockedAt = 0;
                 let pendingHead;
                 const stallMs = deps.sessionEventsStallMs ?? 60_000;
-                // 四轮复审:**全部**写(connected/心跳注释/head 帧)走同一背压感知写手——任何一次 false 都
-                // 进 blocked 态(心跳先塞住的流同样受 stall 断流约束,不再有旁路缓冲增长)。
                 const writeRaw = (chunk) => {
                     if (closed)
                         return;
@@ -418,7 +318,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                             });
                         }
                     }
-                    catch { /* torn socket: close 守卫清理 */ }
+                    catch { }
                 };
                 const doWrite = (leafId) => {
                     lastWritten = leafId;
@@ -433,22 +333,20 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     if (suppress) {
                         lastWritten = leafId;
                         return;
-                    } // 视作已发:重复抑制,真变更仍会推
+                    }
                     if (writeBlocked) {
-                        pendingHead = { v: leafId }; // latest-wins 单格
+                        pendingHead = { v: leafId };
                         if (Date.now() - blockedAt > stallMs) {
                             cleanup();
                             try {
                                 res.end();
                             }
-                            catch { /* noop */ }
+                            catch { }
                         }
                         return;
                     }
                     doWrite(leafId);
                 };
-                // 订阅先于 SSE headers(帽拒绝要保住干净 503)——headers 前到达的 replay/live 帧存一格
-                // pre 缓冲(latest-wins 覆写,单源序不破),headers 后冲洗。
                 let started = false;
                 let preVal;
                 const onHead = (leafId) => {
@@ -457,13 +355,11 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     else
                         emit(leafId);
                 };
-                // dropSession(session 删除,三轮复审租户轮转围栏)→ 即刻断流:旧 owner 的订阅绝不跨越
-                // delete/reclaim 边界;跨副本删除由下方心跳期 owner 复核兜底(≤心跳一拍)。
                 const onEnd = () => { cleanup(); try {
                     res.end();
                 }
-                catch { /* noop */ } };
-                unsubscribe = watch.subscribe(evSession, owner ?? null, onHead, onEnd); // owner 铸入条目(四轮跨副本围栏);已知条目=同步 replay 首帧;新条目=首拍探针 ≤hotMs
+                catch { } };
+                unsubscribe = watch.subscribe(evSession, owner ?? null, onHead, onEnd);
                 if (!unsubscribe) {
                     cleanup();
                     res.setHeader("retry-after", "5");
@@ -476,8 +372,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 if (preVal !== undefined)
                     emit(preVal.v);
                 const hbMs = deps.sessionEventsHeartbeatMs ?? 25_000;
-                // 四轮复审:owner 复核 single-flight——上拍未归不再起新查(存储卡顿时 256 连接不得堆积
-                // 未决查询);未决超过 stallMs=复核面失效,fail-closed 断流(长活流不许在盲区里续命)。
                 let ownerCheckPending = false;
                 let ownerCheckStartedAt = 0;
                 hb = setInterval(() => {
@@ -486,22 +380,21 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     if (writeBlocked && Date.now() - blockedAt > stallMs) {
                         onEnd();
                         return;
-                    } // 僵消费者:无新帧也到点断
+                    }
                     if (!writeBlocked)
                         writeRaw(": hb\n\n");
                     if (ownerCheckPending) {
                         if (Date.now() - ownerCheckStartedAt > stallMs)
-                            onEnd(); // 复核悬死=盲区,fail-closed
+                            onEnd();
                         return;
                     }
-                    // 三轮复审跨副本围栏:心跳拍复核 owner——session 被删(undefined)或换主(≠连接时 owner)即断流。
                     ownerCheckPending = true;
                     ownerCheckStartedAt = Date.now();
                     void ownerOf(evSession).then((o) => {
                         ownerCheckPending = false;
                         if (!closed && o !== owner)
                             onEnd();
-                    }).catch(() => { ownerCheckPending = false; /* 瞬时读障不断流,下一拍再核 */ });
+                    }).catch(() => { ownerCheckPending = false; });
                 }, hbMs);
                 hb.unref?.();
             }
@@ -513,7 +406,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     try {
                         res.end();
                     }
-                    catch { /* noop */ }
+                    catch { }
             }
             return;
         }
@@ -528,13 +421,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             }
             if (!runOwnerOk(req, res, audit.owner))
                 return;
-            // web 会话区性能(additive — parameterless requests stay BYTE-IDENTICAL):
-            //   ?tail=N              → messages = last N (+ window {offset,total})
-            //   ?before=<off>&limit=N → the page above a prior window (offsets stable within one floorEntryId
-            //                           generation — a compaction changes floorEntryId, the web refetches)
-            //   ?blobCap=<bytes>     → oversized string bodies truncated to a preview + message-level truncated:true
-            //                           (expand = refetch that ONE message via ?message=<index>, full size)
-            //   ?message=<index>     → SINGLE full message {message, index, floorEntryId} (the expand face)
             const q = new URL(req.url ?? url, "http://x").searchParams;
             const qi = (k) => {
                 const v = q.get(k);
@@ -557,7 +443,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             const before = qi("before");
             const blobCap = qi("blobCap");
             if (tail === undefined && before === undefined && blobCap === undefined) {
-                sendJson(res, 200, audit); // additive contract: no params = the exact legacy payload
+                sendJson(res, 200, audit);
                 return;
             }
             let messages = audit.messages;
@@ -573,8 +459,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    // E17 (§0.5) — POST /v1/sessions/:id/fork → {sessionId}. Branch a NEW session off the source's WHOLE history
-    // via the SessionRepo seam the service owns (sessionStorage.fork), owner-scoped exactly like GET /v1/sessions.
     {
         const fm = req.method === "POST" ? /^\/v1\/sessions\/([^/]+)\/fork$/.exec(url) : null;
         if (fm) {
@@ -590,9 +474,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             const sourceId = safeDecode(fm[1]);
-            // §0.5 — shape-validate the session id (uuidv7) so a crafted id can't reach the store ops as anything but
-            // a well-formed key (a second layer behind the tool-result LIKE-escape). Malformed (bad %-seq or non-uuidv7)
-            // ⇒ 400, never a store hit.
             if (sourceId === null || !isUuidV7(sourceId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a uuidv7)");
                 return;
@@ -602,38 +483,20 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 sendError(res, 404, "not_found.session", "session not found");
                 return;
             }
-            // Owner gate (no existence oracle for non-owners — 404, parity with runOwnerOk): a principal caller may
-            // only fork its OWN session; a fleet-wide (system/trace) caller may fork any (ops).
-            // [4198] 窄互认第二臂:单机形下 default 主对**存量无主行**放行(三条件齐,见 legacyUnownedSessionOk)。
             if (!scope.fleetWide && owner !== scope.gateOwner && !legacyUnownedSessionOk(deps.config.requirePrincipal, scope.gateOwner, owner)) {
                 sendError(res, 404, "not_found.session", "session not found");
                 return;
             }
-            // New-session ownership — DELIBERATE (no security issue either way; documented per adversarial-review):
-            //  • principal caller → the NEW session is owned by the CALLER (scope.gateOwner): you fork your own session,
-            //    you own the copy.
-            //  • [4198] 窄臂放行的 default 主 → 走 principal 支 ⇒ 副本铸给 `default`(具名行)。刻意如此:副本
-            //    离开无主池,本臂**不被 fork 传播延寿**,墓碑注(存量随生命周期消亡后可整删)仍然成立。
-            //  • fleet-wide (ops, fork-on-behalf) → the NEW session INHERITS the SOURCE owner (`owner ?? null`) so the
-            //    fork is TENANT-owned (an ops/system fork-on-behalf hands the copy to the same tenant as the source,
-            //    NOT to the ownerless/system pool) — a later attach is then governed by the normal authorizer for that
-            //    tenant. (Chosen over null/system-owned: an ops fork is "give this tenant a branched copy", so tenant
-            //    attribution is the intent; a system-submitted *run* forks ownerless, but a *session* fork-on-behalf
-            //    is explicitly on the source tenant's behalf.)
             const newOwner = scope.fleetWide ? (owner ?? null) : scope.gateOwner;
             const newId = await fork(sourceId, newOwner);
             if (newId === null) {
                 sendError(res, 404, "not_found.session", "session not found");
                 return;
-            } // raced delete between ownerOf and fork
+            }
             sendJson(res, 200, { sessionId: newId });
             return;
         }
     }
-    // E21 (§0.5) — DELETE /v1/sessions/:id → {deleted}. Purge the session's conversation history (session_meta/
-    // session_event) AND the service-owned run-ledger/checkpoint/tool-result rows for it. Auth-FIRST (the scope is
-    // computed before any store touch, mirroring GET to avoid a 501-before-auth existence oracle). Owner-scoped,
-    // idempotent ({deleted:false} when nothing existed). active-run guard → 409 (don't orphan the session lock).
     {
         const dm = req.method === "DELETE" ? /^\/v1\/sessions\/([^/]+)$/.exec(url) : null;
         if (dm) {
@@ -649,8 +512,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             const sessionId = safeDecode(dm[1]);
-            // §0.5 — shape-validate the session id (uuidv7) so a crafted id can't reach the purge ops (a second layer
-            // behind the tool-result LIKE-escape). Malformed (bad %-seq or non-uuidv7) ⇒ 400, never a store hit.
             if (sessionId === null || !isUuidV7(sessionId)) {
                 sendError(res, 400, "request.id_invalid", "invalid session id (must be a uuidv7)");
                 return;
@@ -659,21 +520,11 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             if (owner === undefined) {
                 sendJson(res, 200, { deleted: false });
                 return;
-            } // idempotent: already gone
-            // Foreign-owner ⇒ the SAME response as missing (a 404 here vs 200 above was an existence
-            // oracle — a prober could distinguish "absent" from "another tenant's"). deleted:false is also honest
-            // (nothing was deleted) and keeps the route idempotent-shaped for both cases.
-            // [4198] 窄互认第二臂:不放行时,存量无主会话对 default 主是**静默假成功**(用户永远删不掉自己的历史)。
-            // 放行后 purge 的 owner 守卫仍传**行的真 owner**(下面的 `owner`,即 null)——SQL 侧 null-safe 属主门不被放宽。
+            }
             if (!scope.fleetWide && owner !== scope.gateOwner && !legacyUnownedSessionOk(deps.config.requirePrincipal, scope.gateOwner, owner)) {
                 sendJson(res, 200, { deleted: false });
                 return;
             }
-            // Don't orphan the single-active-run lock: refuse while a run is live on this session (409 over a
-            // half-purge that strands a task_active claim). A terminal/suspended/parked session deletes cleanly. This
-            // is a cheap PRE-check; the AUTHORITATIVE no-active-run gate is re-asserted transactionally inside the
-            // runs-ledger purge (FOR UPDATE on task_active), which closes the check→purge TOCTOU and also returns
-            // `{ active }` to 409 if a createRun raced in between.
             const activeTaskId = await deps.runStore?.getActiveTaskId(sessionId);
             if (activeTaskId) {
                 sendError(res, 409, "conflict.session_active_run", "session has an active run; cancel it before deleting", { activeTaskId });
@@ -688,12 +539,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    // E6 — GET/PUT /v1/sessions/:id/policy: read / write operator-tightened per-session tool-permission rules (core
-    // reads them at prepare-time, SUBTRACT-only). Owner-gated + the operator flag FROZEN from the verified principal
-    // (explicitOperatorOk(gatedPrincipal), NEVER the spoofable header — the steer.trusted privilege-escalation rule):
-    // a non-operator may only TIGHTEN its OWN session (a loosen → loosen_forbidden); an operator may loosen + act
-    // cross-tenant. The target key = the session OWNER (the principal core reads rules under). SessionPolicyError →
-    // conflict:409 (stale expectedRev) / loosen_forbidden:403. 404 (not 403) on a non-owner — no existence oracle.
     {
         const pm = req.method === "GET" || req.method === "PUT" ? /^\/v1\/sessions\/([^/]+)\/policy$/.exec(url) : null;
         if (pm) {
@@ -717,11 +562,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             if (owner === undefined) {
                 sendError(res, 404, "not_found.session", "session not found");
                 return;
-            } // idempotent / no oracle
-            // E6 (review): rules MUST be keyed by the principal core reads at run time (getRules(sessionId, spec.principal)).
-            // For an OWNED session that is the owner (a task on it runs as the owner). An OWNERLESS session (owner=null,
-            // REQUIRE_PRINCIPAL=false) has no stable run-principal — a task attaching any principal would read a DIFFERENT
-            // key, silently bypassing the rule (fail-OPEN). Refuse rather than store a rule that won't apply.
+            }
             if (owner === null) {
                 sendError(res, 409, "conflict.session_ownerless", "session policy requires an owned session (set REQUIRE_PRINCIPAL / attach a principal); this session is ownerless");
                 return;
@@ -730,16 +571,12 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             if (!operator && owner !== (principal ?? null)) {
                 sendError(res, 404, "not_found.session", "session not found");
                 return;
-            } // non-owner → 404, no existence oracle
-            const target = owner; // the key core reads rules under = the session's owner (= spec.principal for its tasks)
+            }
+            const target = owner;
             if (req.method === "GET") {
-                // BC-3 (shell §I): the 200 is ALWAYS a non-null StoredSessionRules with a load-bearing `rev` (the PUT CAS
-                // baseline). An owned session with NO policy yet → getRules null → return the empty-at-rev-0 record (the
-                // store reads a missing row as rev 0 = expectedRev:0 create-once), never `{rules:null}`.
                 sendJson(res, 200, { rules: (await store.getRules(sessionId, target)) ?? { rev: 0 } });
                 return;
             }
-            // PUT — validate + pick the 5 known string[] rule fields (reject malformed fail-loud); CAS + tighten gate in the store.
             let body;
             try {
                 body = (await readJson(req));
@@ -781,11 +618,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             return;
         }
     }
-    // ── workspace 浏览面(#3,docs/DESIGN-workspace-browse.md;[1882] 征询 → [1894] cli 表态四点细化)────────
-    // E19 快照店的只读投影:list/tree/file/archive 四端点,零新 store。owner 门=sync 面 PULL 同款
-    // (session 必须存在且属调用方,404 无 oracle);501 谓词=快照店三读面(listKeys/exportManifest/
-    // getBlob)+ ownerOf 齐(capabilities.workspace 同源)。`:key=latest` 别名=最新快照(键=entryId,
-    // uuidv7 时间序 ⇒ 字典序最大即最新)。
     {
         const wm = req.method === "GET" ? /^\/v1\/sessions\/([^/]+)\/workspace(?:\/([^/]+)(?:\/(tree|file|archive))?)?$/.exec(url) : null;
         if (wm) {
@@ -806,16 +638,13 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             const wsOwner = await ownerOf(wsSession);
-            // PULL 门:必须存在且属己,无 oracle。[4198] 窄互认第二臂同样覆盖本读面(存量会话的工作区浏览)。
             if (wsOwner === undefined || (!scope.fleetWide && wsOwner !== scope.gateOwner && !legacyUnownedSessionOk(deps.config.requirePrincipal, scope.gateOwner, wsOwner))) {
                 sendError(res, 404, "not_found.session", "session not found");
                 return;
             }
             const q = new URL(req.url ?? "", "http://x").searchParams;
-            const keys = (await fs.listKeys(wsSession)).sort().reverse(); // uuidv7 entryId:字典序 desc = 时间序 新→旧
+            const keys = (await fs.listKeys(wsSession)).sort().reverse();
             const sub = wm[3];
-            // GET …/workspace — 列快照(新→旧;?limit 1..100 默认 20)。files=manifest 行数;bytes 仅在
-            // blobSizes 面在场时给(local 店缺席=诚实省略,[1894]② additive 口径)。
             if (wm[2] === undefined) {
                 const limRaw = q.get("limit");
                 if (limRaw !== null && !(/^[0-9]+$/.test(limRaw) && Number(limRaw) >= 1 && Number(limRaw) <= 100)) {
@@ -823,12 +652,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const lim = limRaw === null ? 20 : Number(limRaw);
-                // [2400] CAPS-OPS-6(clay 裁 2026-08-03,最优设计不留旧语义):
-                //   · `?before=<key>`(exclusive)游标——keys 是 uuidv7 字典序 desc(新→旧),before 取更旧段;
-                //   · `total` = listKeys 口径的**快照总数**(与 tree 腿的 total 同名同义;此前=页内行数,同名反义
-                //     且超过 limit 的快照永远取不到)。竞态窗口内正被 reap 的 ghost 键会短暂多计 1,下一拍自愈;
-                //   · `nextBefore` 仅在还有更旧的 key 时给(=本页最后一个 key);
-                //   · 复审 A-MED 的保护不变:latest 与**展示行**同源(ghost 不当 latest)、页行掉 ghost 不空报。
                 const beforeRaw = q.get("before");
                 const scoped = beforeRaw !== null ? keys.filter((k) => k < beforeRaw) : keys;
                 const page = scoped.slice(0, lim);
@@ -836,7 +659,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 for (const k of page) {
                     const m = await fs.exportManifest(wsSession, k);
                     if (m === null)
-                        continue; // listKeys 与 manifest 读之间被 reap 的键:掉行不空报
+                        continue;
                     let bytes;
                     if (typeof fs.blobSizes === "function") {
                         const sizes = await fs.blobSizes([...new Set(m.values())]);
@@ -857,7 +680,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 });
                 return;
             }
-            // :key 解析(latest 别名);快照必须真存在(manifest 非 null)。
             const keyRaw = safeDecode(wm[2]);
             if (keyRaw === null) {
                 sendError(res, 400, "request.path_malformed", "malformed snapshot key");
@@ -870,7 +692,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             if (sub === "tree") {
-                // [1894]②:entries 带 {path, size?, hash};?limit 默认 500 cap 2000、?offset 分页;path 序稳定。
                 const limRaw = q.get("limit");
                 if (limRaw !== null && !(/^[0-9]+$/.test(limRaw) && Number(limRaw) >= 1 && Number(limRaw) <= 2000)) {
                     sendError(res, 400, "request.query_invalid", "limit must be a decimal integer in 1..2000");
@@ -907,8 +728,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const cap = deps.config.workspaceFileMaxBytes ?? 8 * 1024 * 1024;
-                // [1894]①:超限=413 结构化信封(web 渲「文件过大,下载查看」卡)。size 可先知(SQL 索引)时
-                // 先拒后拉——绝不为判超限吸整块字节。
                 if (typeof fs.blobSizes === "function") {
                     const known = (await fs.blobSizes([hash])).get(hash);
                     if (known !== undefined && known > cap) {
@@ -925,8 +744,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     sendError(res, 413, "workspace_file_too_large", "file exceeds the single-file read limit — download it via the archive endpoint", { sizeBytes: bytes.byteLength, limit: cap });
                     return;
                 }
-                // [1894]③:content-type 按扩展名(保守表,未知=octet-stream)+ 二进制判别头(首 8KiB NUL/控制
-                // 字节嗅探)。nosniff 恒带(内容是 agent 产物=不可信,绝不让浏览器自嗅成可执行类型)。
                 const ct = workspaceContentType(pathParam);
                 const bin = looksBinary(bytes);
                 res.writeHead(200, {
@@ -939,10 +756,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 return;
             }
             if (sub === "archive") {
-                // 流式 tar(ustar,src/http/tar.ts 零依赖)。开流前三道预检(头没发,还能诚实报错):
-                // ① 路径全部可表示(>255B/不可拆 ⇒ 422 点名);② blob 全在(hasBlobs 单查;缺 ⇒ 502 可重试);
-                // ③ 之后逐文件 getBlob 流式写+背压。中途 blob 消失(reap 竞态)⇒ 已在流中,destroy 连接
-                // (诚实截断——tar 尾块缺失,消费端可判损)。
                 const entries = [...manifest.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
                 const bad = entries.filter(([p]) => splitTarPath(p) === null).map(([p]) => p);
                 if (bad.length > 0) {
@@ -965,10 +778,6 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 const write = async (buf) => {
                     if (res.writableEnded || res.destroyed)
                         throw new Error("client gone");
-                    // 🔴 复审 F5:drain 必须与 close/error **竞速**——socket 被销毁后 `drain` 永不再来,只等
-                    // 它会让本协程永久 pending(入口的 destroyed 守卫挡不住「已经卡在 await 里」这一态)。
-                    // 今天的缓和事实是引用图随连接一起变垃圾、admittedInflight 由 res.on("close") 独立释放;
-                    // 但任何将来加在这条腿上的 finally 清理都会静默不执行 —— 一行竞速根除这个类别。
                     if (!res.write(buf)) {
                         await new Promise((resolve, reject) => {
                             const onDrain = () => { cleanup(); resolve(); };
@@ -993,11 +802,10 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     res.end();
                 }
                 catch {
-                    res.destroy(); // 头已发:诚实截断(缺 tar 尾块,消费端可判损),绝不补一个假完整尾
+                    res.destroy();
                 }
                 return;
             }
-            // 裸 :key 无动词 ⇒ 404 指路(不猜语义)。
             sendError(res, 404, "request.route_unsupported", "unknown workspace verb — use /tree, /file?path=, or /archive");
             return;
         }