@sema-agent/server 7.43.0 → 7.44.0

package/dist/boot/session-faces.js

@@ -1,15 +1,3 @@
-/**
- * design/158 A10:composition root 分段 —— session 只读/删除面(审计、watch 注册表、E21 purge 协调器、
- * degenerate 仪表、plan-cache 探针)。
- *
- * 纯搬运:函数体逐字来自 `main.ts`(原 2967-3092 行),缩进不变;新增的只有 import 与包壳。
- *
- * ⚠️ **位置即契约**:
- *  1. `sessionWatchRegistry` 必须在 `purgeSession` **之前**构造 —— purge 尾部的 `dropSession` 是
- *     同副本租户轮转围栏(delete 即终结旧 owner 的 SSE 订阅),两者是一对。
- *  2. `setLeafAdvanceListener(...)` 是**进程级单点**装载(leaf-bus 只有一个监听位),必须与
- *     registry 的构造同段发生,晚于它、早于任何会 append 的路由。
- */
 import { buildSessionAudit, buildSessionAuditLocal, buildSessionAuditPg } from "../audit.js";
 import { makeDegenerateInstrument } from "../degenerate-instrument.js";
 import { PlanCacheProbe } from "../plan-cache-probe.js";
@@ -19,11 +7,9 @@ import { SessionWatchRegistry, posIntEnv } from "../session-watch.js";
 import { defaultTaskRegistry } from "@sema-agent/core";
 export function createSessionFaces(ctx) {
     const { config, logger, metrics, localRoot, backend, sessionStore, runStore, checkpointStore, toolResultStore, resumeAnchorStore, approvalExemptionStore, sessionPolicyStore, taskAttachmentStore, fileSnapshotStore, workflowCompletionInbox, taskListLane, } = ctx;
-    // Audit回溯 + degenerate-output instrument are TiDB-specific raw-SQL consumers (outside the store
-    // abstraction); they run only on the TiDB backend (the mysql2 pool), and are a no-op on PG until ported.
     const mysqlPool = backend?.mysqlPool();
-    const auditPgPool = backend?.pgPool(); // the audit face now has a PG twin — web session area lights up on DB_BACKEND=pg
-    const auditLocalRoot = backend?.kind === "local" ? (config.localDataRoot ?? localRoot) : undefined; // the File leg
+    const auditPgPool = backend?.pgPool();
+    const auditLocalRoot = backend?.kind === "local" ? (config.localDataRoot ?? localRoot) : undefined;
     const ownerAware = sessionStore;
     const sessionAudit = mysqlPool || auditPgPool || auditLocalRoot
         ? async (sessionId) => {
@@ -37,24 +23,6 @@ export function createSessionFaces(ctx) {
             return { ...audit, owner: (await ownerAware.ownerOf?.(sessionId)) ?? null };
         }
         : undefined;
-    // §0.5 E21 — DELETE /v1/sessions/:id purge coordinator. Deletes the session abstraction's CONVERSATION HISTORY
-    // (sessionStorage.deleteSession → session_meta/session_event) PLUS the service-owned operational rows for that
-    // session: the runs ledger (runStore.deleteBySession → task_run/task_active/task_event, session_id-scoped), the
-    // durable checkpoints + resume-ctx (checkpointStore.deleteBySession, present only under DURABLE_APPROVAL), and
-    // offloaded tool results (toolResultStore.deleteBySession). Wired only when the session store can actually
-    // delete (a DB backend).
-    //
-    // 🔴 ORDERING (adversarial-review HIGH — privacy/right-to-delete + silent-success): the session HISTORY delete
-    // (session_meta) is the `ownerOf` gate the DELETE route consults to decide idempotency. It MUST be the LAST
-    // committed leg. If a privacy-relevant child leg (runs/checkpoint/tool-result) is deleted AFTER the meta row is
-    // gone and then FAILS, the idempotent retry sees `ownerOf===undefined` (history already gone) → the route
-    // short-circuits to 200 {deleted:false} and NEVER re-purges → those child rows are stranded while the API
-    // reports success. So we purge the child legs FIRST and PROPAGATE any error (do NOT swallow): on a child
-    // failure the history delete is SKIPPED, `session_meta` survives, the DELETE returns 500, and the idempotent
-    // retry's `ownerOf` still resolves → it re-runs the FULL purge to convergence. `deleted` is computed from the
-    // FINAL committed result (history-deleted || runsRemoved>0 — the privacy-relevant data that actually existed).
-    // [1196] session-watch registry(SSE 订阅共享探针面)。谓词与 /head 探针同门(getLeafId+ownerOf);
-    // env 旋钮经 posIntEnv 有界校验;getLeafId 箭头包一层=天然绑定宿主(SESSION_CACHE_TTL_SEC=0 裸类实例)。
     const sessionWatchRegistry = ownerAware.getHead && ownerAware.ownerOf
         ? new SessionWatchRegistry(async (sid) => (await ownerAware.getHead(sid)) ?? { owner: undefined, leafId: null }, {
             hotMs: posIntEnv(process.env.SESSION_EVENTS_HOT_MS, 200),
@@ -62,73 +30,21 @@ export function createSessionFaces(ctx) {
             maxWatchedSessions: posIntEnv(process.env.SESSION_EVENTS_MAX_PROBES, 512, 100_000),
         })
         : undefined;
-    // S2 fast path([1208]③ 兑现):同副本 append 落点(tidb/pg persist post-commit)经 leaf-bus 直推
-    // notifyLocal——单副本部署零延迟;owner 随 bus 传(commit-time row owner,session-leaf-bus 头注契约:
-    // "Owner IS carried"),notifyLocal 据此做 generation 围栏(旧 A 世代不会假匹配新租户的叶子)。
-    // local lane 无写钩,探针道照旧。
     setLeafAdvanceListener(sessionWatchRegistry ? (sid, leaf, owner, seq) => sessionWatchRegistry.notifyLocal(sid, leaf, owner, seq) : undefined);
     const purgeSession = ownerAware.deleteSession
         ? async (sessionId, owner) => {
-            // Runs-ledger FIRST: it transactionally re-asserts the no-active-run invariant (FOR UPDATE on task_active,
-            // serializing against a concurrent createRun). If a run claimed the session in the route's check→purge
-            // window it returns `{ active }` and deletes nothing → we bubble it up so the route 409s, BEFORE touching
-            // any other table (no partial purge of a live session). Each leg propagates its error so a child failure
-            // aborts the purge BEFORE the history-delete gate is removed (keeping the idempotent retry convergent).
-            // 🔴 run 账本按 session_id 单键删,**没有**行级属主门(F-A 修,2026-08-17 合并码扫描):`task_run.owner`
-            // 是每次提交的 principal,与会话的 canonical owner 会分叉(无主存量会话被带 principal 的壳续聊 ⇒ 新行
-            // owner="default",而这里递的是会话行的 owner=null)。行级门于是只删一半、把具名行连同 task_event 留成
-            // 孤儿(session_meta 已删 ⇒ 留存腿的 sessionCandidates 永远枚举不到它们),路由却回 {deleted:true} ——
-            // 与下面 anchors 腿注里那句 "a right-to-delete violation reported as success" 是同一个病,理由也同一条:
-            // 会话所有权已在路由的 DELETE 门证过。
-            // 🔴 **化身围栏**(codex R1-[high] 验真后加):属主门下来了,「路由验过权」这句话就必须还**成立到此刻**。
-            // 会话 id 由调用方自选、删除后可被别人 `register` 重新登记 ⇒ 两只并发 purge 交错时(A 与 A' 同时过门,
-            // A' 跑完整条 purge、租户 B 用同一 uuid 重登记并跑完一次 run),慢的那只会按 session_id 把 **B 的**行删掉。
-            // 复读一次 canonical owner,不齐即整条中止(一行不删、回 {deleted:false} —— 属于调用方的那个化身已经不在)。
-            // 这一读是**所有后端**都有的那道围栏;SQL 双生在 store 事务里还有一道 `session_meta … FOR UPDATE` 的
-            // 原子复核(那才是真正消灭竞态的一道),local 车道靠它 + 数据根独占 BootLock。
-            // 「行不在」(undefined)与「换了主」一律中止(codex R2 采纳):meta 不在 = 调用方验过权的那个化身
-            // 已经没了,再按 session_id 往下删,删到的只可能是**别人**重新登记后写的行。E21 的次序契约保证
-            // meta 是**最后**删的(子腿失败就不删 meta,让幂等重试收敛)⇒ 「meta 不在却还有本会话的孤儿子行」
-            // 在协调器这条路上构造不出来,中止不会丢掉任何该删的东西。
-            // ⚠️ `ownerOf` **方法缺席**的后端(可选 seam)与「行不在」必须分开判:合起来会让那些后端的删除
-            // 整条恒中止(fail-closed 到把功能关掉),那是另一种缺陷。
             if (ownerAware.ownerOf) {
                 const stillOwner = await ownerAware.ownerOf(sessionId);
                 if (stillOwner !== owner)
                     return { deleted: false };
             }
-            // 📌 **残余,如实登记**(codex R2 判真但**射程外**,不在本批修):本围栏钉住的是「purge 开始那一刻
-            // 化身是对的」+ run 腿的事务内原子复核。其余按 session_id 单键删的腿(anchors / exemption / policy /
-            // attachment / snapshot / task_list(#318 新入册,codex R2-[high] 同判)/ tool_result 的 provenance 形)
-            // 在**本批之前就是**这个 scoping(理由逐字见下方
-            // anchors 腿注,可追到公开快照那一版),它们各自开始的时刻理论上仍可能落在一次化身漂移之后。
-            // 要真正消灭它得让**整条**级联化身原子(SQL 单事务横跨十余张表 + 对象存储,即留存腿那个形),而在线
-            // 删除面刻意不是那个形:它要跨事务崩溃收敛(meta 最后删 ⇒ 幂等重试),还要动 MinIO 字节。那是设计级
-            // 改动(属主裁决 + 三问),不是复审批能顺手做的事;已作后续件登记,别把这条注读成「已解」。
             const runs = runStore ? await runStore.deleteBySession(sessionId, owner) : { removed: 0 };
             if ("active" in runs)
                 return { active: runs.active };
-            // checkpoint rows carry no owner column → owner-guarded via a session_meta.owner sub-select, so they MUST
-            // run while session_meta still exists (before the history delete below); tool_result selects by its
-            // RECORDED PROVENANCE column (`owner_session_id`) and stays route-guarded too (see its deleteBySession doc).
             if (checkpointStore)
                 await checkpointStore.deleteBySession(sessionId, owner);
-            // optional extra(R3 复扫更正:不再是「SQL twins only」——core 5.28 起 FileToolResultStore **实现了**
-            // deleteBySession,local 车道这条腿**真的会跑**。File 孪生的形:同步遍历目录、无 .owner.json 边车的
-            // 存量文件计入 unattributable 不删——所以 local 部署上这条 warn 在有 5.28 前存量时会以大数出现,
-            // 这是诚实读数不是事故。⚠️ R4 复扫再纠:**local 无 TTL 腿**(File 孪生没有 reapOlderThan,
-            // reapers 的可选链在 local 恒 no-op)⇒ 这些无主存量今天在 local 上**没有任何清理路径**
-            // (会话删除按契约不动它、TTL 也够不着)——只占磁盘不泄权,单用户 CC 姿态下按已知缺口登记,
-            // 清理腿(File 孪生补 reapOlderThan 或一次性迁移铸边车)是独立后续件,别把本注读成已有补偿。)
             if (toolResultStore) {
                 const report = await toolResultStore.deleteBySession?.(sessionId);
-                // 🔴 **回执不许丢**(codex 复审 R1-[high],验真后修):core 把 `unattributable` 写成「the caller
-                // learns the deletion was **incomplete** rather than being told a clean "done"」——无出处的行按
-                // 契约永不删除,协调器把报告丢掉就等于把这句话吞了,而删除面吞掉的是**删除权**的真相。
-                // 这一格是**全库**无出处行数(core InMemory 孪生口径),读法 = 「本店存在没人认领的字节,任何
-                // 会话删除都不可能完整」,不是「本会话残留了 N 行」;实体清理归 TTL(`reapOlderThan`)。
-                // ⚠️ 登记后续件:把它也带上 DELETE 的 HTTP 回执是**加 wire 键**,归属主裁决,不在本批自作主张;
-                // 本批先保证它不再无声消失(结构化 warn = 运维查得到、审计追得上)。
                 if (report !== undefined && report.unattributable > 0) {
                     logger.warn("tool_result_unattributable_rows_survive_session_delete", {
                         sessionId,
@@ -137,60 +53,21 @@ export function createSessionFaces(ctx) {
                     });
                 }
             }
-            // E18 resume-at anchors are per-session privacy-relevant metadata → purge ALL of them with the session, scoped
-            // by session_id ALONE (the route already proved session ownership at the DELETE gate). A per-ROW owner guard
-            // here would LEAK: an anchor's owner is the per-run submitting principal, which diverges from the canonical
-            // session owner when an anonymous session is later attached by a principal (REQUIRE_PRINCIPAL=false) — those
-            // mixed-owner rows would survive the delete (a right-to-delete violation reported as success).
             if (resumeAnchorStore)
                 await resumeAnchorStore.deleteBySession(sessionId);
-            // Approval exemptions are per-session operator decisions → purge with the session (same
-            // session_id-alone scoping rationale as the anchors above).
             if (approvalExemptionStore)
                 await approvalExemptionStore.deleteBySession(sessionId);
-            // E6 session-policy rows are per-session operator rules → purge them too, scoped by session_id (the route
-            // owner-gated the session). Since core 1.423 the seam is on the INTERFACE (optional) and core's File/InMemory
-            // stores carry it too — so this fires on EVERY backend now. (The old note here claimed local rules were
-            // "process-ephemeral anyway" — false for the file-backed local store, whose policy rows survive restarts;
-            // that right-to-delete hole is what [1796]§三 → core 1.423 closed.)
             if (sessionPolicyStore?.deleteBySession)
                 await sessionPolicyStore.deleteBySession(sessionId);
-            // D-1 附件随会话删(E21 级联;session_id 单键 scoping,与 anchors 同理由——路由已证会话所有权)。
             if (taskAttachmentStore)
                 await taskAttachmentStore.deleteBySession(sessionId);
-            // #318 任务清单(TaskCreate/TaskList 家族)是 per-session 的用户内容(任务标题/描述/元数据)
-            // → 随会话删,scoping 与 anchors 同理由(路由已在 DELETE 门证过会话所有权)。
-            // 🔴 **不是可选的卫生腿**:会话 id 由调用方自选、删除后可被别人 `register` 重新登记,而车道的
-            // listKey 是 sessionId 的确定性派生 ⇒ 不删的话新化身第一次 TaskList 就读到上一位主人的任务,
-            // TaskCreate 还从上一位的高水位续号(codex R1-[high] 验真后接)。错误如实上抛 = 与同族腿一致
-            // (子腿失败 ⇒ 不删 meta ⇒ 幂等重试收敛)。
             if (taskListLane)
                 await taskListLane.deleteBySession(sessionId);
-            // E19 rewind-files snapshots are per-session working-tree state → purge them too (scoped by sessionId; the
-            // durable twins carry deleteBySession, local InMemory omits it → optional no-op on local).
             if (fileSnapshotStore?.deleteBySession)
                 await fileSnapshotStore.deleteBySession(sessionId);
-            // P1 ①②: drop any pending async-workflow completions for this session (else they orphan when a later
-            // tenant reclaims the sessionId). Best-effort + non-fatal — a leftover entry is ALSO gated by the
-            // drain-time owner check, so a purge failure never leaks; it must not abort the session delete.
-            // `owner` scopes the purge fence (1.80): only the DELETED session's own late completions are fenced —
-            // a new tenant legitimately re-claiming this sessionId within the window keeps its push (review MED).
             if (workflowCompletionInbox)
                 await workflowCompletionInbox.purge(sessionId, owner ?? null).catch((err) => logger.warn("workflow_completion_inbox_purge_failed", { sessionId, err: String(err) }));
-            // 修8(三路复审 absorb-2,接线 (a)):the session's scratchpad dir ([820]③, ensureScratchpadDir) rides
-            // the session lifecycle — purge it with the session. purgeScratchpadDir SELF-SWALLOWS (env-facts.ts
-            // contract: cleanup never faults the delete path; the periodic sweep below is the convergence backstop),
-            // so it cannot strand the E21 ordering invariant. Same root the ensure used (config.localDataRoot ?? localRoot).
             await purgeScratchpadDir(config.localDataRoot ?? localRoot, sessionId);
-            // design/129 (core 1.239): reap this session's SESSION-scoped background children — they
-            // deliberately outlive turns (backgroundScope:"session"), so the session's DELETE is their lifecycle
-            // end (core's parent-teardown reap skips them by design; without this they run to their forced timeout).
-            // Sync + replica-local (the registry is in-process); best-effort — a reap of 0 on the wrong replica is
-            // covered by core's forced child-timeout cap.
-            // [1892]{core} 跨仓待办:scope 轴必传——core canAccess 对缺省 scope fail-closed(拒绝非通配,
-            // 1.441 复审①正过极性),不传 = 四类后台任务在会话删除时恒 0 回收(潜伏至今,core 复审顺手
-            // 核出)。铸值同源 runs.ts:25 契约:core 按 `spec.principal ?? "default"` 注册 ⇒ 此处
-            // owner(会话主)?? "default" 对齐;错 scope 不越租户由 canAccess 保证(session-reap-scope 钉)。
             try {
                 const reaped = defaultTaskRegistry.reapSessionBackground(sessionId, owner ?? "default");
                 if (reaped > 0)
@@ -199,20 +76,12 @@ export function createSessionFaces(ctx) {
             catch (err) {
                 logger.warn("session_background_reap_failed", { sessionId, err: String(err) });
             }
-            // History/meta LAST: once committed, the `ownerOf` gate is gone and the delete is durably complete. The
-            // owner is threaded into the SQL guard (session_meta.owner) for data-layer defense-in-depth.
             const historyDeleted = await ownerAware.deleteSession(sessionId, owner);
-            // [1196] 三轮复审(租户轮转围栏,同副本半场):session 删除即终结其 SSE 订阅者+watch 条目——
-            // 旧 owner 的活流不得跨越 delete/reclaim 边界收新租户的 head;跨副本半场=路由心跳期 owner 复核。
             sessionWatchRegistry?.dropSession(sessionId);
             return { deleted: historyDeleted || runs.removed > 0 };
         }
         : undefined;
-    // Degenerate-output a/b instrument: needs the durable session log to inspect turn history (design/39
-    // ② gating data). Only on the TiDB backend (mysql2 pool); env-only / PG deploys get no-op.
     const instrumentDegenerate = mysqlPool ? makeDegenerateInstrument(mysqlPool, metrics, logger) : undefined;
-    // Plan-cache recurrence probe (core design/42, INSTRUMENT-FIRST): pure in-memory, no backend needed —
-    // counts per-scope task-objective recurrence so core can decide whether to build plan caching.
     const planCacheProbe = new PlanCacheProbe(metrics, logger);
     return { ownerAware, sessionAudit, sessionWatchRegistry, purgeSession, instrumentDegenerate, planCacheProbe };
 }

package/dist/boot/shutdown.js

@@ -1,32 +1,9 @@
-/**
- * design/158 A10:composition root 分段 —— 进程收尾(hardShutdown / drain / 三个信号处理器)。
- *
- * 纯搬运:函数体逐字来自 `main.ts`(原 4385-4488 行),缩进不变;新增的只有 import 与
- * `installShutdownHandlers(ctx)` 包壳。
- *
- * ⚠️ **位置即契约**(搬运不得改次序):
- *  1. 本段必须在 `server.listen()` **之后**调用 —— `process.on("SIGTERM"|"SIGINT"|"SIGHUP")` 的注册
- *     时点即"从此刻起信号可被优雅处理";提前注册会让一个尚未 listen 的进程走 drain 分支。
- *  2. 三个 `process.on` 的**相对次序**保持 SIGTERM → SIGINT → SIGHUP(与原文件逐字一致);
- *     它们互不覆盖,但 handler 之间共享 `closing`/`draining` 两个 latch,次序变化会改变
- *     "第二个信号"的语义读数。
- *  3. `clearInterval(reaper)` 必须是 hardShutdown 的第一件事(在 `server.close()` 之前),否则
- *     收尾期还会有 reaper tick 打向正在关闭的池。
- */
 import { Runner, defaultTaskRegistry } from "@sema-agent/core";
 import { writeCrashLast, clearCrashLast, readCrashLast } from "./crash-last.js";
 import { createSighupIdleHandler } from "../sighup-idle.js";
 import { createParentWatch } from "../parent-watch.js";
-/** 注册 SIGTERM/SIGINT/SIGHUP 收尾链。**必须在 listen 之后调用**(见文件头「位置即契约」)。 */
 export function installShutdownHandlers(ctx) {
     const { config, logger, server, reaper, fleetReconcile, retentionLane, releaseRetentionLease, otelExporter, breakerState, costQuota, rateLimiter, runner, subRunner, lspManager, workflowNotifyJournal, fleetClient, backend, drainState, storeLiveProbe, configCenter, version, } = ctx;
-    // #320①([4728] 五点令)—— 崩溃遗言面。契约:`crash-last.json` 在场 ⇔ 上一次退出=崩溃。
-    //  · boot 提示:上次崩溃留了遗言 ⇒ 一行 warn(读回即证据,不清——清的责任归受控退);
-    //  · uncaught 双钩:写遗言(version/pid/uptime/inflight/err 首行消毒)后仍按崩溃语义 exit(1),不吞崩溃;
-    //  · 受控退:hardShutdown 一进来即 clearCrashLast(这次是有意的退)——若后续收尾半途真崩,
-    //    uncaught 钩会重写遗言,判别不失真。
-    // dataRoot 类型上可选(config 解析恒回退 ~/.ai-agent ⇒ 实际恒真,/health dataRoot 同注);类型面
-    // 诚实处理:真缺席=遗言面整体不装(uncaught 钩仍装——崩溃语义不能因遗言面缺席而变)。
     const dataRoot = config.localDataRoot;
     if (dataRoot) {
         const prior = readCrashLast(dataRoot);
@@ -39,7 +16,6 @@ export function installShutdownHandlers(ctx) {
     };
     process.on("uncaughtException", (err) => {
         writeLastWords(err);
-        // 与 Node 缺省崩溃姿势对齐:stack 打 stderr(遗言只留首行),随后按崩溃码退。
         console.error(err);
         process.exit(1);
     });
@@ -49,25 +25,15 @@ export function installShutdownHandlers(ctx) {
         process.exit(1);
     });
     let closing = false;
-    /** #219:parent 监视腿(装配在本函数尾,`config.parentPid` 在场才建)。声明提前只为让 hardShutdown
-     *  能把它一并停掉 —— 文件头契约 3 同族(收尾期不再有后台 tick)。 */
     let parentWatch;
     const hardShutdown = () => {
         if (closing)
             return;
         closing = true;
         if (dataRoot)
-            clearCrashLast(dataRoot); // #320①:受控退不留遗言(两形可判别;半途真崩会被 uncaught 钩重写)
+            clearCrashLast(dataRoot);
         clearInterval(reaper);
-        clearInterval(fleetReconcile.timer); // #261:契约 3 同族——收尾期不再有对账 tick 打向正在关闭的池
-        // #270 车2:契约 3 同族,且这一条最要紧——留存 tick 起飞的是跨十余张表的**破坏性**事务。
-        // 🔴 **四步的次序都是承重的**(codex 对抗复审 R1/R2 两轮各修一半,均验真后改):
-        //    停表 → 等在飞那一轮落地 → 让租 → `backend.close()`。
-        //  · `clearInterval` 只挡新 tick,不等当前这一轮;停表之后紧跟着就让租 ⇒ 新副本立刻接租,而本副本
-        //    还在删同一个域的数据 —— 一个由**正常** SIGTERM/SIGINT 稳定触发的双执行者窗口(R1);
-        //  · 而让租之后若不等就关池,这一轮会被从底下抽掉连接、半途而废(R2 —— 见下方 server.close 回调)。
-        //  · 进程若在整条链跑完之前就退了,租约不会被让出 ⇒ 下一位等满 TTL —— 那是**安全**的那一侧。
-        // 三步的产物是一条**可等的** promise —— 下面 `server.close()` 的回调必须等它落地才 `backend.close()`。
+        clearInterval(fleetReconcile.timer);
         const retentionTeardown = retentionLane === undefined
             ? Promise.resolve()
             : retentionLane
@@ -75,27 +41,20 @@ export function installShutdownHandlers(ctx) {
                 .then(() => releaseRetentionLease?.())
                 .then(() => undefined)
                 .catch(() => undefined);
-        fleetReconcile.reconciler.stop(); // 摘总线订阅(观察者已停,扇出不该再喂它)
-        parentWatch?.stop(); // #219:契约 3 同族——收尾期不再探父进程
-        storeLiveProbe?.stop(); // #131-2:契约 3 同族——收尾期不再有探针 tick 打向正在关闭的池
-        configCenter?.stopRefreshLoop(); // #131-2:停机中途不再热应用配置
+        fleetReconcile.reconciler.stop();
+        parentWatch?.stop();
+        storeLiveProbe?.stop();
+        configCenter?.stopRefreshLoop();
         otelExporter?.stop();
         breakerState?.stop();
         if (costQuota && "stop" in costQuota)
-            costQuota.stop(); // the DB-backed quota/limiter (TiDB|PG) have a refresh loop to stop; the in-memory ones don't
+            costQuota.stop();
         if (rateLimiter && "stop" in rateLimiter)
             rateLimiter.stop();
         runner.sessions.dispose();
         subRunner.sessions.dispose();
-        // TOC local LSP: NodeLspManager holds LOCAL child-process language servers — kill them on shutdown so a
-        // restart doesn't orphan a fleet of stdio servers. dispose() isn't on the LspServerManager interface (only the
-        // concrete managers have it), so probe it; the e2b/k8s bridge manager is a harmless no-op if it lacks one.
         void lspManager?.dispose?.();
-        // SVC-1: release the File journal's append handle; the SQL twins hold no fd (probe — close isn't on the seam).
         void workflowNotifyJournal?.close?.();
-        // core 1.270.1:hardShutdown 终点(drain 已完,in-flight 不再被破坏)全量收割 session 驻留
-        // bg bash(detached 进程组,引擎死后 reparent PID 1 残留=实测;retain-declared 例外在原语内)。
-        // TOB 容器形态同样调=无害且显式;SIGKILL 路径无钩=已知不可救记档。
         try {
             const reaped = defaultTaskRegistry.reapAllSessionBackground();
             if (reaped > 0)
@@ -104,34 +63,16 @@ export function installShutdownHandlers(ctx) {
         catch (err) {
             logger.warn("shutdown_background_reap_failed", { err: String(err) });
         }
-        void fleetClient?.stop(); // stop heartbeat + flush final usage window + best-effort DELETE deregistration
+        void fleetClient?.stop();
         server.close(() => {
-            // 🔴 `backend.close()` 必须排在留存收尾**之后**(codex 对抗复审 R2-[high],验真后修):
-            // 那一轮打的是跨十余张表的破坏性事务,把连接池从它底下抽掉 = 这一轮自己半途而废
-            // (比"让租早了"更重:让租早了只是**可能**双执行者,池被抽掉是必然的半成品)。
-            // 兜底仍在:下面那条 15s `finalExit` 无条件退出,一轮卡死的 sweep 拖不住停机。
             void retentionTeardown.then(() => (backend ? backend.close() : Promise.resolve())).finally(() => process.exit(0));
         });
-        // 对抗复查 B-4(HIGH):the exit above only fires after backend.close() SETTLES — a wedged pool teardown
-        // (dead DB, hung socket) kept the "force-terminated" process alive indefinitely (the 10s closeAllConnections
-        // below unblocks server.close(), but nothing bounded backend.close). FINAL deadline: whatever is still
-        // holding after 15s, exit anyway (durable state is already flushed by then — checkpoint/terminal writes
-        // happen before hardShutdown; the pool teardown is best-effort cleanup, not correctness).
         const finalExit = setTimeout(() => { logger.warn("hard_shutdown_final_deadline", { afterMs: 15_000 }); process.exit(0); }, 15_000);
         finalExit.unref?.();
-        // `server.close()` waits for every connection to end — an open SSE stream (/v1/tasks/stream, /events) would
-        // otherwise block it forever, so pool.end()/exit never run and the process hangs until SIGKILL. Drop idle
-        // keep-alives now, then force-terminate any lingering connections after a grace period so `close()` can
-        // resolve and shutdown completes. The timer is unref'd but still fires while the server holds connections.
         server.closeIdleConnections?.();
         const forceClose = setTimeout(() => server.closeAllConnections?.(), 10_000);
         forceClose.unref?.();
     };
-    // SIGTERM = graceful DRAIN — flip `draining` (new billable submits 503+Retry-After, /health carries
-    // draining:true for readiness摘流), then wait for this instance's in-flight legs (live streams + bg/resume) to
-    // finish before the hard shutdown. Bounded by DRAIN_GRACE_MS (default 10min — an interactive turn is minutes;
-    // the previous behavior was a 10s hard-cut that killed long turns). A SECOND SIGTERM or SIGINT (dev Ctrl-C)
-    // skips the wait — k8s sends SIGKILL after terminationGracePeriodSeconds regardless, so the escape hatch is free.
     let draining = false;
     const drainThenShutdown = () => {
         if (closing)
@@ -144,17 +85,14 @@ export function installShutdownHandlers(ctx) {
         draining = true;
         drainState.draining = true;
         drainState.since = Date.now();
-        void fleetClient?.announceNow(); // draining 翻转即刻再 announce — 第一时间自摘流,比任何观测都快
+        void fleetClient?.announceNow();
         const inflight = drainState.inflight?.() ?? 0;
         logger.info("draining_started", { inflight, graceMs: config.drainGraceMs });
         if (inflight === 0) {
             hardShutdown();
             return;
         }
-        // 修3(三路复审 B3-2 时钟):drain elapsed/截止计算走 performance.now() 单调域(挂钟跳变不得吞掉/拉长
-        // drainGraceMs 窗);对外报告的 drainState.since(/health drainingSince)保留 epoch(Date.now)。
         const t0 = performance.now();
-        // NOT unref'd on purpose — this timer IS the shutdown driver (the open connections keep the loop alive anyway).
         const tick = setInterval(() => {
             const n = drainState.inflight?.() ?? 0;
             const elapsed = Math.round(performance.now() - t0);
@@ -167,16 +105,8 @@ export function installShutdownHandlers(ctx) {
     };
     process.on("SIGTERM", drainThenShutdown);
     process.on("SIGINT", hardShutdown);
-    // SIGHUP(壳窗口关闭把信号打到整个进程组)≠「没人在用这只引擎」:共享引擎形态(同 config 多壳会话,
-    // 引擎按 T11 防孤儿拍骑在首壳进程组里)下 peer 会话还活着——无条件 drain 会把 peer mid-turn 斩掉(499)
-    // 且窗内新提交 503(B3,壳侧 [771]② 取证)。改 hup-pending 空闲窗:不翻 draining(peer 零感知),
-    // inflight()(bg/resume legs + live streams)连续 sighupIdleGraceMs 为 0 才 hardShutdown,任何在飞 leg
-    // 重置窗口。真孤儿(最后一窗关掉)有界自灭=T11 保留;第二个 SIGHUP 升级走既有 drain 路径(硬梯子)。
-    // session 驻留 bash 的全量收割仍挂 hardShutdown 终点(reapAllSessionBackground)。
     process.on("SIGHUP", createSighupIdleHandler({
         inflight: () => drainState.inflight?.() ?? 0,
-        // ⚠️ 时基契约(三路复审修3):lastActivityAt 由 server.ts 以 performance.now() 单调域打点,与
-        // sighup-idle.ts 内部的 `now` seam(缺省 performance.now)同域——不得混入 Date.now 值。
         lastActivityAt: () => drainState.lastActivityAt?.() ?? 0,
         isStopped: () => closing || draining,
         escalate: drainThenShutdown,
@@ -184,10 +114,6 @@ export function installShutdownHandlers(ctx) {
         idleGraceMs: config.sighupIdleGraceMs,
         log: (event, fields) => logger.info(event, fields),
     }));
-    // #219(黑板 [3617]):壳被 SIGKILL 后引擎被 reparent 到 init 而继续活着(孤儿引擎持端口/持库连接,
-    // 且再没有人会给它发 SIGTERM)。`SEMA_PARENT_PID` 设了才装配 —— 连续两拍 ESRCH 判死,出口**就是**
-    // 上面 SIGTERM 用的这条 `drainThenShutdown`(结算/park 语义与人工停机逐字一致,不是裸 exit)。
-    // 位置:与三个 process.on 同段、在它们之后 —— 它和信号腿共享 closing/draining 两个 latch。
     if (config.parentPid !== undefined) {
         parentWatch = createParentWatch({
             pid: config.parentPid,

package/dist/boot/side-query-lane.js

@@ -1,119 +1,17 @@
-/**
- * #303([4610] test 报「/model 中途切换校验探针经 POST /v1/side-query 对有效 key 返回上游 401」)——
- * side-query 面的 **per-model key plane** 装配。
- *
- * ## 病灶(#303 立案时亲验 core 5.43.0 dist 实现行)
- *
- * core 的 side-query verb 当时**结构性没有 key 座位**:
- *   · `core/side-query.d.ts` 的 `SideQuerySpec` 无 `apiKey` / `getApiKeyAndHeaders` 字段;
- *   · `SideQueryDeps` = `{ brain, models?, roles? }`;
- *   · `core/side-query.js` 铸 brain `options` 时只放 `signal/maxTokens/reasoning`,**不含 apiKey**。
- * 而 openai brain 的 `buildRequest`(`brain/openai.js`)是这两行:
- *   `const apiKey = options?.apiKey ?? config.apiKey;`   ← 缺席即回落 **brain 构造时的网关 key**
- *   `const root = (model.baseUrl || config.baseUrl || "")` ← 却**按模型**选路
- * ⇒ 对带 per-model `baseUrl` + `apiKeyEnv`/`sealedApiKey` 的模型,side-query 把**主网关 key 发到
- * 外部模型 URL**:用户看到上游 401,同时这是一次凭据外泄(安全轴)。
- * 当时的窄修 = 一只 **key 注入 brain wrapper**(`createPerModelKeyBrain`),并在顶注写明「core 一旦
- * 给 `SideQuerySpec` 补上 key 座位,本 wrapper 即可撤」,撤除信号挂机器钉。
- *
- * ## #341 换装(core 5.46.0 提货,[4615] 座位到货 —— 撤除条件已满足)
- *
- * core 5.46.0 的 `SideQuerySpec` 有了 `getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"]`,
- * `runSideQuery` 每次调用按**解析后的** `Model` 调它,并把 `{apiKey, headers}` 铸进 brain options
- * (`dist/core/side-query.js`:`const auth = await spec.getApiKeyAndHeaders?.(resolved.model);`)——
- * 与主推理链逐字同一只座位形。于是 side-query 席**撤掉 brain wrapper**,key 供给改走 spec 座位:
- *  · 本席不再在 side-query 路上包 `ctx.brain`,`RunnerDeps.brain` 的零扰动从「wrapper 只包一只引用」
- *    降级成**结构性事实**(这条路上根本没有 wrapper);
- *  · `headers` 半边从此有出路(wrapper 形只注得进 `apiKey`,core 的座位 `{apiKey, headers?}` 两半都收);
- *  · 判据(`gatewayBaseUrl`)与 resolver 一样**按调用现取** —— 见下面 `createSideQueryLane` 的注。
- * `createPerModelKeyBrain` **不删**:它仍是 WebFetch 摘要面(`boot/webfetch-summarize-lane.ts`)的
- * key plane —— core 的 `WebFetchSummarizerOptions` 至今只有 `maxContentChars`,那一面没有座位可换
- * (亲验 core 5.46.0 `dist/tools/web.d.ts`)。
- *
- * 🔴 **poison(sealed key 不可解)上抛,绝不静默回落网关 key** —— `resolveModelApiKey` 抛
- * `SealedKeyPoisonedError` 是「这个模型配了托管密钥但解不开」的响亮态;吞成 undefined 等于用共享
- * 网关账号去打这只模型的上游,正是毒丸机制存在的理由(CLAUDE.md #157 安全轴 fail-closed)。换装后
- * 这条语义由 core 承载得更彻底:座位抛 ⇒ `runSideQuery` 的 `await` 直接上抛,brain 一个字节都没发。
- *
- * ## 具名残余:**无 per-model key 的 off-route 模型仍收网关 key**(codex R1-F1,逐条评估后如实留)
- *
- * 判据本身没变(座位到货也没改它):`undefined` ⇒ 座位不给凭据 ⇒ core 用网关 key,即使这只模型的
- * `baseUrl` 指向别家。为什么**不**在本批把它改成 fail-closed(逐条,而不是"先不管"):
- *  ① **与主推理链同语义**才是当前的正确性基准 —— 任务面(core 每次调 `getApiKeyAndHeaders`,返回
- *     `undefined` 即网关 key)在**同一个** catalog、**同一批**模型上就是这个姿势。只把 side-query 收严,
- *     等于让同一只模型「跑任务能用、问一句就 401」,而任务面才是量大的那一面 —— 半边收严的覆盖比
- *     统一的宽松更难排障。
- *  ② **谁被伤到**:`baseUrl` 是**运维**在 config-center 里自己写的(不是用户输入,用户只能在
- *     `atModelAllowlist` 里点名单内的模型)。"同一账号多网关主机/多区域"是既有且正当的部署形,
- *     它今天靠网关 key 工作;无版本协商地收严 = 这类部署当场 401,而且没有旋钮可回退。
- *  ③ hook 面(`hooks/hook-llm.ts`)确实是 fail-closed 的,但它的辖域是 **hook roster**(运维给钩子挑的
- *     模型),不是用户可点的整本目录;两者的收严代价不同量级。
- * ⇒ 本批**不改行为**,把它作为**跨面语义问题**上报(要收严就三面一起收严、带旋钮、走表态制),
- *   而不是在这一面偷偷收严。真要收严时的正解:按 `normUrl` 比对 `gatewayBaseUrl`(+fallback 列表)
- *   与 anthropic 路由,off-route ∧ 无 per-model key ⇒ 拒发,并同批改任务面。
- */
 import { expandTiers, runSideQuery } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
-/**
- * 「这只模型的 baseUrl 打的是**别家**主机吗」—— core 的选路规则是 `model.baseUrl || config.baseUrl`,
- * 所以只有 `model.baseUrl` 非空时才可能离开本部署网关。比较按 URL 归一(`new URL` 小写 host、丢默认端口、
- * 去尾斜杠),裸字符串比会在 host 大小写/默认端口写法上假阴。
- *
- * 参照系缺席(`gatewayBaseUrl` 未给)⇒ 回 `false`:判不了就不判,别猜。
- *
- * ⚠️ `hooks/hook-llm.ts` 有一只逐字同形的内联归一器(它用同一判据做 **fail-closed 拒发**,本函数只
- * 做**计数**)。两处合一属跨面收严件 #309 的射程(那时三面同批换判据),本批刻意不动 hook 面的 fail-closed
- * 门 —— 在只改可观测性的批里重写另一条安全轴的门,风险与收益不对等。
- */
 export function isOffRouteBaseUrl(modelBaseUrl, gatewayBaseUrl) {
     if (!modelBaseUrl || !gatewayBaseUrl)
         return false;
-    // 解析不了(配歪的 baseUrl)⇒ 退到去尾斜杠的裸串比。用 `URL.canParse` 而不是 try/catch:静默降级
-    // 棘轮门(`test/silent-degradation-scan.test.ts` SHAPE C)对「catch 只 return 默认值」是零容忍的,
-    // 而这条降级恰好有一个不吞异常的写法(Node ≥20 / ES2023 均在射程)。方向:比不出同一家 ⇒ 算 off-route
-    // ⇒ 记债(宁可多记一条待查,不可把一次真外泄判成自家网关)。
     const norm = (u) => URL.canParse(u) ? ((x) => `${x.protocol}//${x.host}${x.pathname.replace(/\/+$/, "")}`)(new URL(u)) : u.replace(/\/+$/, "");
     return norm(modelBaseUrl) !== norm(gatewayBaseUrl);
 }
-/**
- * per-model auth 座(#341,core 5.46.0 `SideQuerySpec.getApiKeyAndHeaders` 的 server 侧填充物)。
- *
- * 语义(逐条对齐主推理链 `getApiKeyAndHeaders`,也逐条对齐它取代的 wrapper 那三条臂):
- *  · `upstream`(spec 自带的座位)**解出凭据** ⇒ 原样透传,含 `headers`(上游/装饰器已经定了凭据,
- *    本层不抢 —— wrapper 时代的「`options.apiKey` 已在场」臂);判别按**每次调用**的返回值,不是
- *    「座位在场就整只让位」:上游对这只模型没意见时,本席照常按模型解 key;
- *  · resolver 缺席(部署根本没配 per-model key)⇒ 回 `undefined` ⇒ core 用网关 key(今日行为逐字不变);
- *  · resolver 返回 undefined(这只模型没有自己的 key)⇒ 回 `undefined` ⇒ 网关 key(additive 契约);
- *  · resolver 抛(sealed key 中毒)⇒ **上抛**,`runSideQuery` 的 `await` 直接把它扔给调用方,
- *    本次调用整体失败,一个字节都不发。
- *
- * 🔴 A-057.59 [PARTIAL high](2026-08-19;#341 换装后**处置不变**)—— 「无 per-model key 的 off-route
- * 模型仍收网关 key」这条具名残余**行为不变**(逐条理由见模块顶注「具名残余」段;core 的座位是
- * 「absent ⇒ construction-time credentials apply」,与主推理链
- * `dist/engine/harness/agent-harness.js` 的 `auth?.apiKey !== undefined` 臂逐字同语义,座位到货并没有
- * 改变这条残余,所以 `P-DEBT` 计数**不可销**),但**每次调用零留痕**这一半是要清偿的存量欠账:
- * config-apply 期那条 `sema_registry_model_key_env_missing` warn 只覆盖「声明了 env 名却没设」,覆盖不到
- * 「压根没配 per-model key 的 off-route 模型」,而后者才是真发生外泄的那一形。按 CLAUDE.md #157
- * 「一时改不动的 P 类记 `P-DEBT`」补计数:命中条件 = **解不出 per-model key ∧ 该模型的 baseUrl 不是本
- * 部署网关** ⇒ 这一次调用真把网关凭据发给了别家主机。`gatewayBaseUrl` 缺席(调用方没给参照系)⇒ 不计
- * (不猜),与「宁可漏计不可错计」同向。
- */
 export function createPerModelAuthSeat(getKeyResolver, opts = {}) {
     return async (model) => {
-        // 🔴 **同代配对**(codex R1-[high],验真后采纳):resolver 引用必须在**第一个 await 之前**取。
-        // core 在同一个同步段里解析出 `model`(含它那一代的 `baseUrl`)后立刻调本席,所以本函数体的**第一条
-        // 同步语句**与模型解析同代。`await opts.upstream?.(model)` 是一道真 await 边界(`opts.upstream`
-        // 缺席时 `await undefined` 照样让出一个微任务),config-center 的 apply 提交段(#303 codex R1-F2 修成
-        // 「目录与密钥表零 await 窗成对换代」)可以整段落在那个缝里 ⇒ 缝之后再取 resolver 就会拿到**下一代**
-        // 的密钥表,配上**上一代**的模型/端点:新家的 key 发到旧家的 URL —— 正是本席存在要消灭的那个形。
-        // 取引用是纯读、无副作用,即使上游随后胜出也不多花什么。
         const resolve = getKeyResolver();
         const given = await opts.upstream?.(model);
         if (given?.apiKey !== undefined)
-            return given; // 已有凭据:不抢
-        // 🔴 不 try/catch:poison 必须上抛(静默回落 = 拿共享网关账号打这只模型的上游)。
-        // resolver 缺席(部署根本没配 per-model key 平面)与解析回 undefined(这只模型没有自己的 key)
-        // 两形都落到同一条缺席语义:回 undefined ⇒ core 用网关 key(additive 契约)。
+            return given;
         const resolved = resolve ? await resolve({ name: model.name }) : undefined;
         if (resolved === undefined && isOffRouteBaseUrl(model.baseUrl, opts.gatewayBaseUrl)) {
             recordFailOpen("server.model-key.off-route-model-uses-gateway-key", model.name);
@@ -121,34 +19,17 @@ export function createPerModelAuthSeat(getKeyResolver, opts = {}) {
         return resolved;
     };
 }
-/**
- * per-model key 注入 brain wrapper —— **#341 后只服务 WebFetch 摘要面**
- * (`boot/webfetch-summarize-lane.ts`)。side-query 面已换到 core 的 spec 座位(见顶注「#341 换装」);
- * core 的 `WebFetchSummarizerOptions` 至今只有 `maxContentChars`(亲验 5.46.0 `dist/tools/web.d.ts`),
- * 那一面**没有座位可换**,只能继续在 brain 层补凭据。
- *
- * 语义(与 `createPerModelAuthSeat` 同一张表,只是注入位在 `options.apiKey`):
- *  · `options.apiKey` **已在场** ⇒ 原样透传(上游/装饰器已经定了凭据,本层不抢);
- *  · resolver 缺席 / 返回 undefined ⇒ 不注入 ⇒ 网关 key(additive 契约);
- *  · resolver 抛(sealed key 中毒)⇒ **上抛**,本次调用整体失败,一个字节都不发。
- *
- * `complete` 在场时同样包一层:core 的 `Brain.complete` 是 compaction/摘要腿的直调口(WebFetch 摘要器
- * 正是**优先**走它),漏包等于给同一个病留第二条路。
- */
 export function createPerModelKeyBrain(brain, getKeyResolver, opts = {}) {
     const seat = createPerModelAuthSeat(getKeyResolver, opts);
     const keyFor = async (model, given) => {
         if (given !== undefined)
-            return given; // 已有凭据:不抢
+            return given;
         return (await seat(model))?.apiKey;
     };
     const stream = async (model, context, options) => {
         const apiKey = await keyFor(model, options?.apiKey);
         return brain.stream(model, context, apiKey === undefined ? options : { ...options, apiKey });
     };
-    // 🔴 A-057.2:`.bind(brain)` **保留接收者** —— 裸摘引用(`const complete = brain.complete`)在 ESM
-    // 严格模式下让 `this` = undefined,任何读 `this` 的 Brain 实现经本 wrapper 后当场 TypeError,
-    // 而两行之上的 `stream` 臂是带接收者的 `brain.stream(…)`,同一只 wrapper 两条臂不该有两种调用形。
     const complete = brain.complete?.bind(brain);
     return {
         stream,
@@ -162,22 +43,6 @@ export function createPerModelKeyBrain(brain, getKeyResolver, opts = {}) {
             : {}),
     };
 }
-/**
- * 装配 side-query 执行席 = 真 `runSideQuery` + core 的 per-model auth 座,models/roles 与 Runner 同源。
- *
- * **按调用**取三件活值(`models` / `getKeyResolver` / `gatewayBaseUrl`),因为它们是**同一次** center
- * 下发里成对换代的(#303 codex R1-F2:目录与密钥表零 await 窗成对换代):
- *  · `models` = `expandTiers(config.models, config.tiers)` —— 档位词 / CC 别名(`flash`/`opus`/…)在
- *    side-query 上照常可选路(core 的 `Runner` 构造时做同一件事),且 `Runner` 那次展开是**构造时快照**,
- *    而本路由的模型白名单门(`routes/side-query.ts` 的 `isModelAllowlisted`)按请求现算同一张增广目录 ——
- *    两边取同一份才不会出现「名单放行、选路说不认识」的分歧;
- *  · `getKeyResolver()` —— 热应用整个换 resolver 引用,活取才跟得上(装配时快照 = 旧 key 用到重启);
- *  · `config.gatewayBaseUrl` —— off-route 判据的参照系。装配时快照会让「换网关那一刻起,这次调用把网关
- *    凭据发给了别家」在遥测里永久失明(钉:`test/side-query-key-plane.test.ts` 的活取钉)。
- *
- * `spec` 自带的 `getApiKeyAndHeaders`(嵌入方/装饰器)**不被覆盖** —— 它作为 `upstream` 折进本席,
- * 每次调用先问它,它没意见时才由本席按模型解(见 `createPerModelAuthSeat` 顶注第一条臂)。
- */
 export function createSideQueryLane(ctx) {
     return (spec) => runSideQuery({
         ...spec,