@sema-agent/server 1.323.0 → 2.0.0

package/dist/http/routes/sessions.js

@@ -12,8 +12,16 @@ const MCP_STATUS_TTL_MS = 5_000;
 const MCP_MATERIALIZE_TIMEOUT_MS = 10_000;
 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(),
     };
 }
@@ -22,15 +30,22 @@ 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 } = 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);
+            const principal = gatedPrincipal(req, deps.config); // F-fix: VERIFIED presence gate (direct-door JWT, not the spoofable header)
             if (deps.config.requirePrincipal && !principal) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
@@ -43,10 +58,15 @@ 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);
+            const principal = gatedPrincipal(req, deps.config); // F-fix: VERIFIED presence gate (direct-door JWT, not the spoofable header)
             if (deps.config.requirePrincipal && !principal) {
                 sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
                 return;
@@ -64,25 +84,36 @@ 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() });
+                sendJson(res, 200, { servers: [], asOf: new Date().toISOString() }); // no MCP configured → honest empty panel
                 return;
             }
-            const principal = gatedPrincipal(req, deps.config);
+            const principal = gatedPrincipal(req, deps.config); // threaded for per-user MCP RBAC (principalHeader injection)
             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();
+                    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.
                 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.
                     const matP = materializeMcpTools(specs, principal);
                     let timer;
                     const mat = await Promise.race([matP.catch(() => null), new Promise((r) => { timer = setTimeout(() => r(null), MCP_MATERIALIZE_TIMEOUT_MS); })]);
@@ -90,7 +121,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 };
+                        return { servers: [], asOf: new Date().toISOString(), degraded: true }; // timed out / failed to materialize
                     }
                     try {
                         return {
@@ -100,6 +131,8 @@ 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) } : {}),
                             })),
                         };
@@ -114,9 +147,16 @@ 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) {
@@ -124,6 +164,8 @@ 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;
@@ -158,9 +200,16 @@ 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) {
@@ -168,12 +217,14 @@ 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)) {
                 res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
                 res.end(JSON.stringify({ error: "session-events connection cap reached — fall back to /head polling" }));
                 return;
             }
-            sse.sseConnections++;
+            sse.sseConnections++; // 同步占坑(查+占同拍,慢读并发不再超卖);此后一切路径必经 cleanup 还坑
             let hb;
             let unsubscribe;
             let closed = false;
@@ -189,6 +240,10 @@ 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();
@@ -198,7 +253,8 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                 }
                 sse.sseOwnerLookups++;
                 const ownerP = ownerOf(evSession);
-                void ownerP.catch(() => undefined).then(() => { sse.sseOwnerLookups--; });
+                void ownerP.catch(() => undefined).then(() => { sse.sseOwnerLookups--; }); // 许可随底层 settle 归还
+                // 七轮复审:race 计时器 settle 即清——高频开合不得每次拖 60s 计时器+闭包(unref 只保进程退出面)。
                 let stallTimer;
                 let owner;
                 try {
@@ -212,7 +268,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                         clearTimeout(stallTimer);
                 }
                 if (closed)
-                    return;
+                    return; // 读期断连:close 守卫已还坑,别再写已死响应
                 if (owner === "__stall__") {
                     cleanup();
                     res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
@@ -229,14 +285,20 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     return;
                 }
                 const q = new URL(req.url ?? url, "http://x").searchParams;
-                const lastLeafId = q.get("lastLeafId");
+                const lastLeafId = q.get("lastLeafId"); // null=未带 ⇒ 恒发首帧;带了且首帧值相等 ⇒ 抑制(304 同义)
+                // 单源发射:全部帧来自 registry(rev 单调序),连接级 lastSent 去重;首帧抑制=首值命中
+                // lastLeafId 时只记不发(后续同值仍去重,更新值照发)。
                 let first = true;
-                let lastAccepted;
+                let lastAccepted; // 去重基准(单源 rev 序,最新接受值)
                 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;
@@ -254,7 +316,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                             });
                         }
                     }
-                    catch { }
+                    catch { /* torn socket: close 守卫清理 */ }
                 };
                 const doWrite = (leafId) => {
                     lastWritten = leafId;
@@ -269,20 +331,22 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     if (suppress) {
                         lastWritten = leafId;
                         return;
-                    }
+                    } // 视作已发:重复抑制,真变更仍会推
                     if (writeBlocked) {
-                        pendingHead = { v: leafId };
+                        pendingHead = { v: leafId }; // latest-wins 单格
                         if (Date.now() - blockedAt > stallMs) {
                             cleanup();
                             try {
                                 res.end();
                             }
-                            catch { }
+                            catch { /* noop */ }
                         }
                         return;
                     }
                     doWrite(leafId);
                 };
+                // 订阅先于 SSE headers(帽拒绝要保住干净 503)——headers 前到达的 replay/live 帧存一格
+                // pre 缓冲(latest-wins 覆写,单源序不破),headers 后冲洗。
                 let started = false;
                 let preVal;
                 const onHead = (leafId) => {
@@ -291,11 +355,13 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     else
                         emit(leafId);
                 };
+                // dropSession(session 删除,三轮复审租户轮转围栏)→ 即刻断流:旧 owner 的订阅绝不跨越
+                // delete/reclaim 边界;跨副本删除由下方心跳期 owner 复核兜底(≤心跳一拍)。
                 const onEnd = () => { cleanup(); try {
                     res.end();
                 }
-                catch { } };
-                unsubscribe = watch.subscribe(evSession, owner ?? null, onHead, onEnd);
+                catch { /* noop */ } };
+                unsubscribe = watch.subscribe(evSession, owner ?? null, onHead, onEnd); // owner 铸入条目(四轮跨副本围栏);已知条目=同步 replay 首帧;新条目=首拍探针 ≤hotMs
                 if (!unsubscribe) {
                     cleanup();
                     res.writeHead(503, { "retry-after": "5", "content-type": "application/json" });
@@ -308,6 +374,8 @@ 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(() => {
@@ -316,21 +384,22 @@ 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();
+                            onEnd(); // 复核悬死=盲区,fail-closed
                         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?.();
             }
@@ -342,7 +411,7 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     try {
                         res.end();
                     }
-                    catch { }
+                    catch { /* noop */ }
             }
             return;
         }
@@ -357,6 +426,13 @@ 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);
@@ -379,7 +455,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);
+                sendJson(res, 200, audit); // additive contract: no params = the exact legacy payload
                 return;
             }
             let messages = audit.messages;
@@ -395,6 +471,8 @@ 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) {
@@ -410,6 +488,9 @@ 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;
@@ -419,20 +500,35 @@ 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).
             if (!scope.fleetWide && owner !== scope.gateOwner) {
                 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.
+            //  • 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) {
@@ -448,6 +544,8 @@ 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;
@@ -456,11 +554,19 @@ 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.
             if (!scope.fleetWide && owner !== scope.gateOwner) {
                 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 });
@@ -475,6 +581,12 @@ 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) {
@@ -498,7 +610,11 @@ 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;
@@ -507,12 +623,16 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             if (!operator && owner !== (principal ?? null)) {
                 sendError(res, 404, "not_found.session", "session not found");
                 return;
-            }
-            const target = owner;
+            } // non-owner → 404, no existence oracle
+            const target = owner; // the key core reads rules under = the session's owner (= spec.principal for its tasks)
             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));
@@ -554,6 +674,11 @@ 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) {
@@ -577,10 +702,12 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
             if (wsOwner === undefined || (!scope.fleetWide && wsOwner !== scope.gateOwner)) {
                 sendError(res, 404, "not_found.session", "session not found");
                 return;
-            }
+            } // PULL 门:必须存在且属己,无 oracle
             const q = new URL(req.url ?? "", "http://x").searchParams;
-            const keys = (await fs.listKeys(wsSession)).sort().reverse();
+            const keys = (await fs.listKeys(wsSession)).sort().reverse(); // uuidv7 entryId:字典序 desc = 时间序 新→旧
             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)) {
@@ -593,7 +720,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;
+                        continue; // listKeys 与 manifest 读之间被 reap 的键:掉行不空报
                     let bytes;
                     if (typeof fs.blobSizes === "function") {
                         const sizes = await fs.blobSizes([...new Set(m.values())]);
@@ -603,6 +730,9 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     }
                     snapshots.push({ key: k, files: m.size, ...(bytes !== undefined ? { bytes } : {}) });
                 }
+                // 🔴 复审 A-MED:`latest` 与 `total` 必须与**展示行**同源——listKeys 与 exportManifest 之间
+                // 被 reap 的键(ghost)若恰是字典序最大者,原写法会让 latest 指向已消失的快照(latest 别名的
+                // tree/file/archive 全 404,尽管有有效的次新快照),且 total 计入 ghost 与 snapshots[] 不一致。
                 sendJson(res, 200, {
                     sessionId: wsSession,
                     snapshots,
@@ -611,6 +741,7 @@ 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");
@@ -623,6 +754,7 @@ 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");
@@ -659,6 +791,8 @@ 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) {
@@ -675,6 +809,8 @@ 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", { code: "workspace_file_too_large", 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, {
@@ -687,6 +823,10 @@ 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) {
@@ -709,6 +849,10 @@ 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(); };
@@ -733,10 +877,11 @@ async function handleSessionsBody(req, res, url, ctx, miss) {
                     res.end();
                 }
                 catch {
-                    res.destroy();
+                    res.destroy(); // 头已发:诚实截断(缺 tar 尾块,消费端可判损),绝不补一个假完整尾
                 }
                 return;
             }
+            // 裸 :key 无动词 ⇒ 404 指路(不猜语义)。
             sendError(res, 404, "request.route_unsupported", "unknown workspace verb — use /tree, /file?path=, or /archive");
             return;
         }

package/dist/http/routes/side-query.d.ts

@@ -1,3 +1,11 @@
+/**
+ * design/158 A9 域模块 —— sideQuery 一次性问答面([1469],core 1.361)。
+ *
+ * 路由:`POST /v1/side-query` —— 无 session / 无工具执行 / 无 policy gate / 无引擎侧记账 / 无流式的
+ * 一次性 brain 路由问答(v1 刻意面 = core 规格 side-query.d.ts)。cli 壳侧十几个 utility(标题/摘要/
+ * 权限解释…)的传输层正解。位置在全局 service-credential 门**之后**、任务提交面之前;`isBillableSubmitPath`
+ * 已含本路径,故 no-token 503 / draining / model-ready 三闸在进本域前就已生效。本域零可变状态。
+ */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";
 export declare function handleSideQuery(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;