@sema-agent/server 7.43.0 → 7.44.0

package/dist/http/routes/trace-usage.js

@@ -4,49 +4,21 @@ import { usageSummary, usageSeries, usageBreakdown } from "../../usage-analytics
 import { sleep } from "../sse-log.js";
 import { bindSseLifecycle } from "../sse-lifecycle.js";
 import { sendJson, sendError, sseHeaders, SSE_MAX_STREAM_MS, SSE_HEARTBEAT_IDLE_MS } from "../send.js";
+import { filterFingerprint } from "../cursor-fingerprint.js";
 import { gatedPrincipal } from "../principal-gate.js";
-// [3321] tool-results 读面**共用这一段守卫**([3318] 的字面承诺):新 sub 进的是同一个 `sub` 捕获组,
-// 于是下方 fleetWide / gateOwner / per-id owner-404 三道门原样罩住它,不存在第二套门可以漂。
-// ⚠️ 「both-or-neither」结构不可破:`:id` 与 `sub` 同在一个可选组里,所以 TRACE_RE 从不匹配裸
-// `/v1/tasks/<seg>` —— 那正是 `POST /v1/tasks/stream` 不被本读面遮蔽的原因(见下方 source-summary 注)。
-// 新臂写成 `sub` 的一个 alternation 分支(而不是新开捕获组),组号与既有两个捕获保持逐字不变。
 const TRACE_RE = /^\/v1\/tasks(?:\/([^/]+)(\/turns|\/stream|\/artifacts|\/tool-results\/[^/]+))?$/;
-/** tool-results 读面的 sub 前缀(路由判别 + 段切分单源)。 */
 const TOOL_RESULTS_SUB = "/tool-results/";
-/** `limit` 的 server 权威上限(chars)。缺席 = 不传给 store,用 store 自己的默认;超上限 = 400(不静默夹取:
- *  夹取会让「我要 1M」与「我要 256K」返回同一段内容,调用方无从知道自己被截了)。 */
 const TOOL_RESULT_LIMIT_CAP = 262_144;
-/** `offset` 的上限 = **最窄后端**能表达的值(codex 复审 R1 medium,已核真)。PG 那半边发的是
- *  `SUBSTRING(content FROM $1::int …)` 且绑的是 `offset + 1`(`plugins/tool-result-store-sql.ts`),
- *  于是 `offset = 2147483647` 过得了「非负整数」这一关,却在库里变成 `2147483648::int` ⇒ 范围错 ⇒ 500。
- *  「坏输入回 400」是本面的承诺,承诺不能挑后端兑现,所以上限按 int32 - 1 收(留出 +1 的余量)。 */
 const TOOL_RESULT_OFFSET_CAP = 2_147_483_646;
 export async function handleTraceUsage(req, res, url, ctx) {
     const miss = { fell: false };
     await handleTraceUsageBody(req, res, url, ctx, miss);
     return !miss.fell;
 }
-/** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
- *  = 「本域已应答」;走到函数尾才是「没匹配上」。跨域的东西一律在首行解构出来。 */
 async function handleTraceUsageBody(req, res, url, ctx, miss) {
     const { deps } = ctx;
     const { isFleetWide, safeDecode } = ctx.helpers;
-    // Task Trace API (S1, read-only): GET /v1/tasks[/:id/turns|/stream]. Authorized by EITHER the full authToken
-    // OR a read-only traceToken (sema-registry pulls traces fleet-wide with one read-only token). Handled BEFORE
-    // the global gate (like /metrics) so a traceToken-only caller isn't 401'd.
-    // ⚠️ Blast radius (council DESIGN-1): fleet-wide by design — traces are NOT per-run-owner-scoped here (the
-    // trace token is a deployment-held read-only credential, like metricsToken). Per-tenant/roster scoping is the
-    // sema-registry relay's job (admin-session + roster); the kill-switch is leaving TRACE_TOKEN unset.
-    // Per-door usage rollup (center systems-UI, SERVICE-PROPOSAL-SYSTEMS-DOMAIN): COUNT by (source,status)
-    // since ?sinceSec ago (default 24h, max 30d). Own route — TRACE_RE's :id group is both-or-neither (it
-    // deliberately never matches a bare /v1/tasks/<seg>, keeping POST /v1/tasks/stream unshadowed), so this
-    // CANNOT ride that block (caught live: the in-block branch was dead code → 404).
     if (req.method === "GET" && url === "/v1/tasks/source-summary") {
-        // source-summary is a CROSS-TENANT aggregate (count-by-source/status across ALL tenants) with NO owner-scoped
-        // variant — so it is ops-only: fleet-wide callers (system/trace token) on any deployment, or dev-open on a
-        // single-user deployment. A multi-tenant deployment without a token must NOT see it (isFleetWide fail-closes —
-        // the SAME HIGH tenant-isolation fix as the trace/session gates; this endpoint had the un-migrated fail-open
-        // clause, caught by the systematic-audit review's dimension-2 sweep).
         if (!isFleetWide(req)) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -62,11 +34,8 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
     }
     const traceMatch = req.method === "GET" ? TRACE_RE.exec(url) : null;
     if (traceMatch) {
-        // FLEET-WIDE (sees ALL tenants): a system authToken or the read-only traceToken (sema-registry ops
-        // relay), or dev-open on a SINGLE-USER deployment. A multi-tenant deployment without a token is owner-gated,
-        // NEVER fleet-wide — see isFleetWide (HIGH tenant-isolation audit fix). Otherwise a principal caller is owner-gated.
         const fleetWide = isFleetWide(req);
-        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null); // direct-door safe; `|| null`: an absent principal ("" / undefined) → null
+        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
         if (!fleetWide && gateOwner === null) {
             sendError(res, 401, "auth.unauthorized", "unauthorized");
             return;
@@ -77,11 +46,7 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
         }
         const query = new URL(req.url ?? "", "http://x").searchParams;
         const taskId = traceMatch[1];
-        const sub = traceMatch[2]; // undefined (list) | "/turns" | "/stream" | "/artifacts" | "/tool-results/<ref>"
-        // per-id owner gate for the principal path (404 for a non-owner — no existence oracle, parity with runOwnerOk).
-        // 🔴 该行**只在 principal 路径**被取(fleet 路径按设计不做 per-id 归属判定)——tool-results 面还要用
-        // `run.sessionId` 算 ref 前缀,所以这里把取到的行留住(`ownedRun`),fleet 路径由该面自己补一次取行:
-        // 少了那次取行,fleet caller 就能拿任意 taskId 配任意 ref 读走**别的 session** 的产物。
+        const sub = traceMatch[2];
         let ownedRun;
         if (taskId && gateOwner !== null) {
             const run = await deps.runStore.getRun(taskId);
@@ -92,7 +57,7 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             ownedRun = run;
         }
         if (!taskId)
-            await handleTaskList(res, deps.runStore, query, gateOwner); // gateOwner (when set) forces the owner filter
+            await handleTaskList(res, deps.runStore, query, gateOwner);
         else if (sub === "/turns")
             await handleTaskTurns(res, deps.runStore, taskId, query);
         else if (sub === "/stream")
@@ -106,16 +71,6 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
             sendError(res, 404, "not_found.route", "not found");
         return;
     }
-    // ── 用量统计查询面(web P4,registry AnalyticsSource "service-usage" 数据源)────────────────
-    // GET /v1/usage/{summary|series|breakdown}?from&to&…(ISO 或 epoch-ms)。鉴权双支持(回帖契约):
-    //  - fleet 凭证(authToken/traceToken)= 全量视角,可用 principal 参数过滤任意主体;
-    //  - registry JWT(1.141 鉴权桥,verifiedPrincipal)= 强制 owner=本人(参数里的 principal 被忽略);
-    //  - 都没有 → 401。scope 参数 v1 不实装(principal 即租户键;registry 侧按需把 scope→principal 集合映射)。
-    // 聚合=usage-analytics 纯函数;store 扫窗触顶 → truncated:true 诚实上抛(绝不静默截断)。
-    // 🔴 位置(1.148 修):必须在全局 service-credential 门【之前】(与 trace 门/metrics 同款待遇)——
-    // 门函数 isFleetWide 认只读 traceToken,但配了 authToken 的部署里全局门只认 service token/SSO-JWT,
-    // usage 挂门后时 traceToken-only 调用(registry 用量中继的姿势)在全局门就 401=门内 traceToken 支持成死代码
-    // (a2 实机抓获)。本块所有命中路径自带 401/501 fail-closed 再 return,未命中 sub 落回后续路由(含全局门)。
     if (url.startsWith("/v1/usage/") && req.method === "GET") {
         const sub = url.slice("/v1/usage/".length).split("?")[0];
         if (sub === "summary" || sub === "series" || sub === "breakdown") {
@@ -124,12 +79,12 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
                 return;
             }
             const fleetWide = isFleetWide(req);
-            const jwtOwner = fleetWide ? undefined : gatedPrincipal(req, deps.config); // 经 gatedPrincipal:未验 Bearer 不回退头
+            const jwtOwner = fleetWide ? undefined : gatedPrincipal(req, deps.config);
             if (!fleetWide && !jwtOwner) {
                 sendError(res, 401, "auth.unauthorized", "unauthorized");
                 return;
             }
-            const q = new URL(req.url ?? "", "http://x").searchParams; // NB: `url` 已剥 query,参数必须读 req.url
+            const q = new URL(req.url ?? "", "http://x").searchParams;
             const parseT = (v, dflt) => {
                 if (!v)
                     return dflt;
@@ -137,13 +92,12 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
                 return Number.isFinite(n) ? n : NaN;
             };
             const now = Date.now();
-            const from = parseT(q.get("from"), now - 7 * 86_400_000); // 默认近 7 天
+            const from = parseT(q.get("from"), now - 7 * 86_400_000);
             const to = parseT(q.get("to"), now);
             if (Number.isNaN(from) || Number.isNaN(to) || from >= to) {
                 sendError(res, 400, "request.query_invalid", "invalid from/to (ISO-8601 or epoch-ms; from < to)");
                 return;
             }
-            // owner 过滤:JWT 主体强制=本人;fleet 凭证可选 principal 参数。
             const owner = jwtOwner ?? (q.get("principal") ?? undefined);
             try {
                 const scan = await deps.runStore.usageScan(from, to, owner !== undefined ? { owner } : undefined);
@@ -166,7 +120,6 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
                         sendError(res, 400, "request.query_invalid", "dimension=principal|model");
                         return;
                     }
-                    // JWT 主体查 dimension=principal 只会看到自己一桶(owner 已强制)——语义自然成立,无泄漏面。
                     sendJson(res, 200, { ...base, dimension, breakdown: usageBreakdown(scan.rows, dimension) });
                 }
             }
@@ -179,44 +132,42 @@ async function handleTraceUsageBody(req, res, url, ctx, miss) {
     }
     miss.fell = true;
 }
-// ─────────── Task Trace API handlers (S1) ───────────
-function encodeCursor(c) {
-    return Buffer.from(JSON.stringify(c)).toString("base64url");
+function encodeCursor(c, f) {
+    return Buffer.from(JSON.stringify({ ...c, f })).toString("base64url");
 }
-function decodeCursor(s) {
+function decodeCursor(s, expectF) {
     if (!s)
         return undefined;
     try {
         const o = JSON.parse(Buffer.from(s, "base64url").toString());
-        // Same date-validity guard as decodeSessionCursor: a tampered non-date createdAt would reach `new Date()` in the
-        // store keyset predicate and 500 (same latent issue as the sibling cursor).
+        if (o.f !== undefined && (typeof o.f !== "string" || o.f !== expectF))
+            return "mismatch";
         return o.createdAt && o.taskId && !Number.isNaN(Date.parse(o.createdAt)) ? { createdAt: o.createdAt, taskId: o.taskId } : undefined;
     }
     catch {
         return undefined;
     }
 }
-/** GET /v1/tasks — cheap list summary (contract 2.1), keyset-paginated newest-first. */
 async function handleTaskList(res, runStore, query, forceOwner) {
     const status = query.get("status") ?? undefined;
-    const jobId = query.get("jobId") ?? undefined; // work-view group filter — all runs of one logical task
-    const source = query.get("source") ?? undefined; // credential-derived door filter (oa/cc-mcp/portal)
-    // forceOwner (set on the principal path) PINS the listing to the caller's own runs — it overrides any ?owner
-    // so a principal can't list another tenant. null/undefined (fleet-wide path) → honor the ?owner query (ops view).
+    const jobId = query.get("jobId") ?? undefined;
+    const source = query.get("source") ?? undefined;
     const owner = forceOwner != null ? forceOwner : (query.get("owner") ?? undefined);
     const limit = Math.min(100, Math.max(1, Number(query.get("limit") ?? 50) || 50));
-    const cursor = decodeCursor(query.get("cursor"));
+    const f = filterFingerprint([status, jobId, source, owner]);
+    const cursor = decodeCursor(query.get("cursor"), f);
+    if (cursor === "mismatch") {
+        sendError(res, 400, "request.cursor_filter_mismatch", "cursor was issued under a different filter (status/jobId/source/owner) — restart from the first page without a cursor");
+        return;
+    }
     const rows = await runStore.listRuns({ ...(status ? { status } : {}), ...(jobId ? { jobId } : {}), ...(source ? { source } : {}), ...(owner ? { owner } : {}), ...(cursor ? { cursor } : {}), limit: limit + 1 });
     const hasMore = rows.length > limit;
     const page = hasMore ? rows.slice(0, limit) : rows;
-    const tasks = page.map((r) => taskSummary(r)); // lastStep from status; latest-event lastStep = a later refinement
+    const tasks = page.map((r) => taskSummary(r));
     const last = page[page.length - 1];
-    const nextCursor = hasMore && last ? encodeCursor({ createdAt: last.createdAt, taskId: last.taskId }) : undefined;
+    const nextCursor = hasMore && last ? encodeCursor({ createdAt: last.createdAt, taskId: last.taskId }, f) : undefined;
     sendJson(res, 200, { tasks, ...(nextCursor ? { nextCursor } : {}) });
 }
-/** GET /v1/tasks/:id/turns — lazy history (contract 2.2), backward-paginated by turn seq. */
-/** GET /v1/tasks/:id/artifacts — what the agent produced (M2). A pure projection of the
- *  durable log (no new write path), so it works for every historical run. */
 async function handleTaskArtifacts(res, runStore, taskId) {
     const run = await runStore.getRun(taskId);
     if (!run) {
@@ -226,85 +177,11 @@ async function handleTaskArtifacts(res, runStore, taskId) {
     const events = await runStore.getEvents(taskId, 0);
     sendJson(res, 200, { artifacts: projectArtifacts(events, { taskId, jobId: run.jobId }) });
 }
-/**
- * GET /v1/tasks/:id/tool-results/:ref?offset&limit —— core `ToolResultStore.get` 的 wire 镜像([3321])。
- *
- * 三件事,顺序本身就是契约:
- *
- * ① **query 先判**。坏 offset/limit ⇒ 400,且这一判**先于**任何 ref/归属/store 在场性判定 —— 否则
- *    「坏 query + 已知 ref = 400」而「坏 query + 未知 ref = 404」,状态码之差立刻成了存在性 oracle。
- *    query 的合法性只取决于 query 自身,与调用方看不看得见这个 ref 无关,所以先判是安全的。
- *
- * ② **归属绑定 = 店里记的出处(`ownerOf`)与本 run 的 session/task 精确相等**(实现见 ②-a),不解析 ref、
- *    不复制段转义规则,**且没有第二条腿**。
- *
- *    下面这一大段是这条判据的**病历**(前缀形 → 本 task 日志作证形 → 出处形),留着是因为「为什么不
- *    照 ref 的字面去判」每隔一阵就被重新问一次;当前生效的判据只有 🟡 段之后的那一条。
- *
- *    先说为什么**不是**前缀判定([3321]② 的字面形、[3322] 的指定形):core 的 ref 形是
- *    `tr_<seg(session)>_<seg(toolCallId)>`,而 `_` 在两段里都合法 ⇒ session `team` 的前缀 `tr_team_`
- *    同样命中 session `team_blue` 的 ref(`tr_team_blue_toolu_x`)。本仓的 sessionId 是**调用方自选的
- *    任意 ≤64 字符串**(`http/server.ts` 的 submit 面只查长度,刻意宽松),所以租户 A 可以把自己的
- *    sessionId 取成租户 B 的前缀,拿自己的 taskId 配 B 的 ref 读走 B 的产物(codex 复审 R1 high,已核真)。
- *    这在字符串层面**无解**:把余段当 toolCallId 重铸一遍会逐字相等(拼接本身有歧义),而按「更长的
- *    session 是否存在」去探,既堵不住折成 base+sha 的 sessionId(候选串 ≠ 真 id),又反手造出一个新的
- *    跨租户**拒绝**面(别人注册一个 `<你的 session>_toolu` 就能让你自己的 ref 永远 404)——R2 复审两条
- *    中标,已撤回该启发式。
- *
- *    当年的改判据(**已被 ②-a 取代,见下**):ref **必须由本 task 自己的耐久事件日志作证**。日志里每条 tool_start/tool_end 都带
- *    `toolCallId`(`trace/project.ts` 的 toolStartEventData / toolEndEventData 是唯一铸造点),用 core
- *    的**同一个** `buildToolResultRef` 把它们铸成 ref 集合,再要求 `ref` 是其中一员 —— 精确相等,
- *    零解析、零转义规则复制,歧义面结构上不存在(A 的 taskId 只作证 A 自己的 toolCallId)。
- *    辖域(诚实写明,也正是本路由的语义):本面服务的是**这条 task 的 trace 里看得见的那些产物** ——
- *    trace 的 tool-result 块与本判据读的是同一份日志,所以「trace 上看得见 ⇒ 这里读得到」成立;
- *    同 session 里**别的 task** 的 ref(或日志已过保留窗被逐出的)按 404 同形拒,请到那条 task 上读。
- *
- *    🟡 **两条残余的现状(7.14.0 合并窗复扫改口,下面原文保留作病历)**。core 按当年这里写的方向动了刀:
- *    `put` 带出处落库 + `ownerOf` 读回,读面改用出处判定(实现见 ②-a)。逐条对账:
- *      · (b) 拼接非单射的越权面**已彻底消失** —— ref 铸法换成 `~` 多段,`~` 不在段的合法字符集里。
- *      · (a) 合成 id 铸的 ref **只销了一半**:offload / budget / compaction 三个写点的出处只声明
- *        session ⇒ 现在读得到;而 `task-registry-monitor` 的 spill(`<stream>_seg<n>`)与
- *        `task-registry-agent` 的 spill(`c<cycle>`)在出处里**点名了 taskId,填的是 core TaskRegistry
- *        的 handle id**(`b/w/a/m` 前缀 + 16 hex,见 core `task-registry.js`),与本路由段里的 server
- *        run id(uuidv7)是两个命名空间,恒不相等 ⇒ 这两族 ref 在本面**恒 404**(改前也 404,不是回归)。
- *        而它们恰恰是 core 在成品文本里明写「call ReadToolResult with ref …」露给调用方的那批。
- *        真解仍在 core 侧(出处该声明的是**调用方认得的** task 坐标,或干脆只声明 session);本仓不自行
- *        放宽 taskId 那条腿 —— 那是单方面改判定语义,归属判据会与上游各漂一份。
- *    日志重铸那条腿**已删**(见 ②-b:它对任何真实行都不可达,且每次未命中还要付一次全量日志读)。
- *
- *    ⚠️ 两处**已知残余**,都要 core 侧动刀才能消,写在明处而不是让下一个人自己撞(codex 复审 R3):
- *
- *    (a) **覆盖面**:core 除了「按工具调用 id 卸载」这条主路,还从**合成 id** 铸 ref ——
- *        `task-registry-monitor` 的 `<handle>_<stream>_seg<n>`、`task-registry-agent` 的 `<handle>_c<n>`、
- *        `runner/compaction-call-options` 的 `<toolCallId>_s<sha>`、budget 的 `idx<k>`。这些 id **不进**
- *        耐久事件日志(日志记的是外层调用 id),所以那几类 ref 在本面一律 404 同形拒。
- *        方向明确:**不**在本仓照抄那几条命名规则去反推(复制上游规则 = 两处各自漂,宪法禁),
- *        真解是 core 在写入时带上 (session/task) 出处、或给出 core 属主的精确成员判定。
- *
- *    (b) **注入性**:`buildToolResultRef` 对 `(session, toolCallId)` **不是单射**(`_` 两段都合法):
- *        `("team","blue_toolu_1")` 与 `("team_blue","toolu_1")` 铸出同一枚 ref。所以「本 task 日志作证过
- *        一个恰好长成 `<受害 session 尾巴>_<受害 toolCallId>` 的 toolCallId」时,判据仍会放行。
- *        与被撤掉的前缀形的差别是**门槛**:前缀形只要知道 ref 就能读,本形还要求攻击者能让**模型网关**
- *        铸出那一枚精确的 toolCallId(provider 铸,本服务不控也不产)。同样只有 core 换成单射编码才真消。
- *        这里**不留特征化测试**去钉这条通路 —— 把缺陷钉成契约是另一种病。
- *
- * ③ **同形 404**(unknown ref / 出处判不过(含无属主行)/ 本部署没有 durable store)。任何可区分的响应都是
- *    缺陷:前两者之差会告诉调用方「这枚 ref 存在,只是不是你的」;第三者若回 501 则会把部署形告诉一个
- *    连自己的 ref 都读不到的 caller。文案恒定且**不回显 ref**(回显=把输入原样反射进错误面)。
- *    残余面(诚实写明):响应字节同形,**时序**并不同形 —— 三条臂到达的后端调用数不同。要抹平时序得让
- *    每条臂都跑满全部后端调用,那是另一档代价/收益裁定,不在本批;本批的判据是响应本身不给 oracle。
- */
-async function handleToolResult(res, store, runStore, taskId, ownedRun, 
-/** 已过 `safeDecode` 的 ref;`null` = %-序列坏(客户端错,但同形 404 —— 它同样不该成为一条可区分的信道)。
- *  解码用调用点传下来的 helper 而不是本地 try/catch:那条规则(坏序列 ⇒ null,绝不 500)在本仓只有
- *  `safeDecode` 一个属主,复制一份等于把它变成两个。 */
-ref, query) {
-    // ① query 校验(先于一切存在性判定 —— 见头注)。非负十进制整数,`Number()` 的宽松形(空串/前后空白/
-    //    "1e3"/"0x10"/"1.5")一律不认:宽松解析会让两个不同的请求串静默映射到同一段内容。
+async function handleToolResult(res, store, runStore, taskId, ownedRun, ref, query) {
     const intParam = (name, cap) => {
         const raw = query.get(name);
         if (raw === null)
-            return undefined; // 缺席 = 用 store 默认
+            return undefined;
         if (!/^\d+$/.test(raw))
             return "bad";
         const n = Number(raw);
@@ -324,46 +201,18 @@ ref, query) {
         sendError(res, 400, "request.query_invalid", "limit must be a non-negative integer of at most 262144");
         return;
     }
-    // ③ 同形 404 的**唯一**下发点:每条臂都必须走这里,不许任何一条自己写一句(文案分家=oracle 复活)。
     const notFound = () => sendError(res, 404, "not_found.tool_result", "tool result not found");
     if (ref === null)
-        return notFound(); // 坏 %-序列(见参数注)
-    // fleet 路径没做 per-id 取行(见调用点注),这里补齐 —— 归属绑定要 run.sessionId,没有行就没有绑定面。
+        return notFound();
     const run = ownedRun ?? (await runStore.getRun(taskId));
     if (!run)
         return notFound();
-    // ②-a 出处判定(#119,core 5.26.0 —— 上面 (a)/(b) 两条残余的**正解到货**)。
-    // 店里现在自己记着「这枚 ref 属于谁」(`put` 的第三参落库,`ownerOf` 读回),读面拿**自己已知的字段**
-    // 比对即可:零解析、零段转义规则复制,拼接歧义那条残余彻底消失,合成 id 那条**消了一半**
-    // (monitor/agent spill 两族的出处点名的 taskId 是 core handle id,与本函数收到的 server run id 不同
-    //  命名空间 ⇒ 恒判假;详见头注 🟡 段)。
-    //
-    // 🔴 为什么必须改而不是"锦上添花":5.26.0 起 offload ref 是多段单射形(内容坐标进 ref),服务端手里
-    // 没有内容 ⇒ 原来那条重铸判据**重铸不出来** ⇒ 每一枚真 offload ref 都会 404。读面整死。
-    //
-    // ⚠️ 辖域(有意的口径变化,写在明处):出处的粒度由 core 定 —— offload/budget/projection 三个写点只声明
-    // session,把 taskId 钉在那里会把「一个 session 的两条 task 共用一枚 ref」这个**设计内**的共享形变成拒绝
-    // (core d.ts 逐字裁过)。所以有出处时的判据是「同 session,且出处**若点名了** task 则必须是本 task」——
-    // 相对旧的「本 task 日志作证过」是**放宽到同 session**。放宽的边界仍在 owner 之内(run 归属门在本函数
-    // 之前已过,session 的属主就是这个 caller),换来的是这条读面在 5.26.0 上还活着。
     const owner = store?.ownerOf ? await store.ownerOf(ref) : undefined;
     const ownedByThisCaller = owner !== undefined && owner.sessionId === run.sessionId && (owner.taskId === undefined || owner.taskId === taskId);
-    // ②-b **没有**第二条腿:出处判不过就是 404(unowned 行也在内 —— core 的口径就是「读面对 unowned
-    // fail-closed」)。这里曾有一条「用本 task 耐久日志作证过的 toolCallId 经 `buildToolResultRef` 重铸再
-    // 精确相等」的兜底,7.14.0 合并窗复扫判定为**结构性死支**并整条删除,证据链写在明处:
-    //   · 重铸只喂得起两个参数(服务端手里没有内容)⇒ 铸出的是**两段**形 `tr_<sid>~<callId>`;
-    //   · core 5.27.0 的**每一个**落库写点铸的都是 ≥3 段(offload/budget/compaction 三段带内容摘要、
-    //     detail 卸载四段、monitor/agent spill 三段带 `<stream>_seg<n>`/`c<cycle>`),而 `~` 不在段的合法
-    //     字符集里 ⇒ **段数不同的 ref 恒不相等** ⇒ 该判据对库里任何真实行都不可能成立;
-    //   · 旧引擎(≤5.25.0)的 `tr_<sid>_<call>` 同样重铸不出来(分隔符换了),而按旧规则手写一个 legacy
-    //     编码器 = 复制上游规则(本文件头注自己禁掉的那件事);存量行的真处置是**删表重建**(见 CHANGELOG)。
-    // 删的另一半理由是**代价**:走到这条腿的前提是「出处缺席」,而任意乱写的未知 ref 恰好也落在这里,
-    // 于是每个必然 404 的请求都要付一次整份耐久事件日志读(已鉴权调用方可用随机 ref 放大后端读),
-    // 换不到任何放行。行为面只收窄不放宽:能放行的集合原本就是空集。
     if (!ownedByThisCaller)
         return notFound();
     if (!store)
-        return notFound(); // durable store 缺席:404 同形,不 501(不泄露部署形)
+        return notFound();
     const slice = await store.get(ref, { ...(offset !== undefined ? { offset } : {}), ...(limit !== undefined ? { limit } : {}) });
     if (!slice)
         return notFound();
@@ -376,20 +225,15 @@ async function handleTaskTurns(res, runStore, taskId, query) {
         return;
     }
     const limit = Math.min(100, Math.max(1, Number(query.get("limit") ?? 20) || 20));
-    const cursorSeq = Number(query.get("cursor") ?? 0) || 0; // turns with seq < cursor (older); 0 = newest page
+    const cursorSeq = Number(query.get("cursor") ?? 0) || 0;
     const [events, retainedFrom] = await Promise.all([runStore.getEvents(taskId, 0), runStore.retainedFrom(taskId)]);
-    const all = projectEvents(events); // the objective (user turn) isn't on the run row → omitted for MVP (refinement)
+    const all = projectEvents(events);
     const eligible = cursorSeq > 0 ? all.filter((t) => t.seq < cursorSeq) : all;
-    const turns = eligible.slice(Math.max(0, eligible.length - limit)); // backward = the newest of the eligible
+    const turns = eligible.slice(Math.max(0, eligible.length - limit));
     const oldest = turns[0];
-    // The turns cursor is a plain turn-seq (turns are seq-ordered); it is opaque to the client per the contract
-    // (2.2), so it needn't match the list endpoint's base64url(createdAt,taskId) keyset cursor (council).
     const nextCursor = eligible.length > limit && oldest ? String(oldest.seq) : undefined;
     sendJson(res, 200, { turns, ...(nextCursor ? { nextCursor } : {}), retainedFrom });
 }
-/** GET /v1/tasks/:id/stream — resumable SSE (contract 2.3). Maps the durable event log to the contract event
- *  names, declares mode in the first event, 416s a resume point evicted past retention, heartbeats, and emits an
- *  explicit `error` on stall so the client never hangs. */
 async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
     const run0 = await runStore.getRun(taskId);
     if (!run0) {
@@ -397,22 +241,17 @@ async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
         return;
     }
     const lastId = Number(req.headers["last-event-id"] ?? new URL(req.url ?? "", "http://x").searchParams.get("from") ?? 0);
-    let from = Number.isFinite(lastId) ? lastId : 0; // unified with streamRunEvents (council DESIGN-4); a <0 from just replays all
+    let from = Number.isFinite(lastId) ? lastId : 0;
     if (from > 0) {
         const retainedFrom = await runStore.retainedFrom(taskId);
         if (retainedFrom > from + 1) {
-            // The events the client wants to resume past were evicted → it must re-sync via GET /turns (contract 2.3).
             sendError(res, 416, "limit.retention_evicted", "resume point evicted past retention", { retainedFrom });
             return;
         }
     }
     sseHeaders(res);
-    // First event declares the stream contract: mode + a version (council — lets the relay detect a worker whose
-    // SSE shape changed, e.g. when P1 adds token-delta granularity). resumeFrom echoes the honored Last-Event-ID.
-    res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", version: 1, mode: "delta", resumeFrom: from })}\n\n`); // [2373]C-12:data.type 双发与内容帧一致
+    res.write(`event: meta\ndata: ${JSON.stringify({ type: "meta", version: 1, mode: "delta", resumeFrom: from })}\n\n`);
     let closed = false;
-    // design/245 件1:断连清理走共享助手(req+res 双挂 + 一次性闸)。只挂 `req` 时,请求流被读干的
-    // 形下这条旗永远翻不过来,泵会对着死 socket 一路轮询到 15 分钟帽 —— 理由全文在 `sse-lifecycle.ts` 顶注。
     bindSseLifecycle(req, res, () => {
         closed = true;
     });
@@ -432,7 +271,7 @@ async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
         if (!run)
             break;
         if (run.status !== "running") {
-            write(await runStore.getEvents(taskId, from)); // the terminal event can land in the gap above
+            write(await runStore.getEvents(taskId, from));
             break;
         }
         const stale = Date.now() - new Date(run.updatedAt).getTime() > staleMs;
@@ -441,8 +280,6 @@ async function streamTaskTrace(req, res, runStore, taskId, staleMs) {
             break;
         }
         if (Date.now() - start > SSE_MAX_STREAM_MS) {
-            // BL-16: the stream hit its 15-min cap but the RUN is still going — emit a terminal event so the client
-            // can tell "reconnect to continue" from "task completed" (a silent close looked like completion).
             res.write(`event: error\ndata: ${JSON.stringify({ type: "error", errorCode: "STREAM_MAX_DURATION", message: "trace stream reached its 15-minute cap — reconnect with Last-Event-ID to continue (the run is still active)" })}\n\n`);
             break;
         }