@sema-agent/server 7.52.0 → 7.53.0

package/dist/http/active-run-conflict.d.ts

@@ -1,5 +1,5 @@
 /**
- * [2252]/[2255]①/[2257] 追加件:409 `conflict.session_active_run` 的**真出路材料**装配(单源)。
+ * [ref]/[ref]①/[ref] 追加件:409 `conflict.session_active_run` 的**真出路材料**装配(单源)。
  *
  * 事故形:park(suspended/needs_review)占着 session claim,客户端每条新提交吃 409,而旧文案只教
  * cancel(毁灭当前 run)。对 parked 会话,「继续」的唯一合法动作是去**对的** resume 入口决议——但四条
@@ -15,7 +15,8 @@
  */
 import { type Autonomy } from "../runtime-governance.js";
 import { type RunRecord } from "../plugins/store-contracts.js";
-/** #220 归因的部署侧入参(两个治理旋钮;判据属主见 `governanceMandatesShellGateAlways`)。 */
+import { type PendingRowBinding } from "../plugins/checkpoint-store-sql.js";
+/** [ref] 归因的部署侧入参(两个治理旋钮;判据属主见 `governanceMandatesShellGateAlways`)。 */
 export interface GovernancePosture {
     autonomy?: Autonomy;
     manualModeShellGate?: "always" | "classify";
@@ -25,15 +26,15 @@ export declare const ACTIVE_RUN_CONFLICT_BASE_TEXT = "session already has an act
 /**
  * 409 体(与 SSE done 帧 result 共用)里的**待批门材料**。
  *
- * `kind`/`decidePath` = 出路(去哪决议);#220 追加的 `governanceForced` = **出身**(这道门是谁下的)——
- * [3513] T3「park 后待批通道事件」的读者此前只知道「有一道 X 型门」,不知道它是运维治理层强制的还是
+ * `kind`/`decidePath` = 出路(去哪决议);[ref] 追加的 `governanceForced` = **出身**(这道门是谁下的)——
+ * [ref] T3「park 后待批通道事件」的读者此前只知道「有一道 X 型门」,不知道它是运维治理层强制的还是
  * 别的来源,于是「我都开了 bypassPermissions 为什么还在问」这个 UX 缺口在 park 腿上原样复现
- * ([3031]#1/[3038] 在活卡腿上的实证)。
+ * ([ref]#1/[ref] 在活卡腿上的实证)。
  *
  * 🔴 **additive + 只在为真时在场**:与活卡帧 `ToolApprovalFrame.governanceForced` **同一条纪律**——
  * 缺席 ≠「这不是治理门」,而是「没有治理来源的证据」(判据够不着的形也落在缺席里,见装配处的注)。
  *
- * #285 追加的 `checkpointId` = **相关性**(这道门在别的面上叫什么名字),是出路/出身之外的第三个问题。
+ * [ref] 追加的 `checkpointId` = **相关性**(这道门在别的面上叫什么名字),是出路/出身之外的第三个问题。
  * 上文那条「askId 为什么不在这里」的记账(见 {@link governanceOriginOf} 顶注末段)说的是**同一个缺口的
  * 另一半**:park 门此前在 wire 上**没有任何稳定身份**——唯一单射的键是 `token`,而 token 是秘密能力、
  * 永不上 wire,于是消费端只能拿 `(sessionId, kind)` 这种非单射组合去猜「这次的门」和「上次的门」是不是
@@ -64,7 +65,7 @@ export interface PendingGateMaterial {
     decidePath: string;
     /** 见 {@link PendingGateMaterial} 顶注:`true` 才在场,恒不写 `false`。 */
     governanceForced?: true;
-    /** #285(core 5.42.0):这道 park 门的**非秘密稳定身份**(`Checkpoint.checkpointId`)。逐字过境,
+    /** [ref](core 5.42.0):这道 park 门的**非秘密稳定身份**(`Checkpoint.checkpointId`)。逐字过境,
      *  server 绝不自铸、绝不派生(信任边界校验见 `safeCheckpointIdOf`)。
      *  🔴 **缺席是三成因合流的一个形**(R3-[low] 验真后改真 —— 此前这里只写了第一条,那是失真):
      *    ① **legacy 行**:该键诞生前 park 的(core 明写「absent ⇒ legacy row, read compatibly, no backfill」);
@@ -73,16 +74,13 @@ export interface PendingGateMaterial {
      *    ③ **材料读取失败**:整只 `pendingGate` 都不在(那时本键连位置都没有)。
      *  ⇒ 读作「不知道这道门叫什么」,**不是**「这道门没有身份」,更**不是**「这一定是条老行」。
      *
-     *  🔴 **它命名的是「本次 409 实际读到的那一行」,不是「activeTaskId 这条 run 的门」**(codex 交叉复审
-     *  R1-[high] 验真后如实登记):同 session 可以并存两条 pending checkpoint(表上**没有** per-session
-     *  pending 唯一约束),而 `findPendingTokenBySession` 是**无序 `LIMIT 1`** —— 这个条件是本仓自己成文的
-     *  已知事实(见 `src/http/server.ts` mintFreshRun 腿 409 那段的逐字论证:「两条 pending 并存时旧
-     *  task_done park 完全可能被选中」)。⇒ 本材料的**每一格**(kind / decidePath / governanceForced /
-     *  checkpointId)共享同一条归属不确定性;本键是**继承**它,不是引入它。
-     *  **对消费端的直接后果**:这一位**不是**跨调用的稳定去重键 —— 同一情形连续两次 409 可能报出不同的
-     *  id(选中了另一行),也可能 id 不变而 activeTaskId 已换。可安全用于:落日志/排障关联,以及「id 变了
-     *  ⇒ 我看到的门确实不是刚才那一道」这个**单向**判断。根治要一条能按 run 绑定选行的 store 读口
-     *  (SQL 面 = 双库门),已作为提货批未决项上报,不在本批。 */
+     *  🔴 **归属不确定性(codex 交叉复审 R1-[high] 曾如实登记)—— [ref]([ref])已收口**:同 session 可以
+     *  并存两条 pending checkpoint(表上**没有** per-session pending 唯一约束;并存形 = 终局后的 `task_done`
+     *  纯 park + 下一条 run 的门 park),而 `findPendingTokenBySession` 曾是**无序 `LIMIT 1`**,本材料的
+     *  每一格因此曾共享「读到的是哪一行」的不确定性。现形:本模块按 **run 绑定**选行(`LIVE_RUN_GATE_KINDS`
+     *  —— activeTaskId 持有 claim ⇒ 它的门绝非 task_done),且店读口自此有序(最新优先,token 兜平局;
+     *  谓词/序属主 `checkpoint-store-sql.ts` `pendingRowQuery`,LOCAL twin 同判)⇒ 同一情形连续两次 409
+     *  报的是同一行。残余如实记:这一位仍不是**跨 run** 的去重键 —— activeTaskId 换了,门自然也换。 */
     checkpointId?: string;
 }
 export interface ActiveRunConflictBody {
@@ -90,13 +88,13 @@ export interface ActiveRunConflictBody {
     errorCode: "conflict.session_active_run";
     activeTaskId: string | null;
     activeTaskStatus?: string;
-    /** #245 S1([3777]):running 形专属的**活性证据**——本副本 ledger sink 最后一次 durable append 距今
+    /** [ref] S1([ref]):running 形专属的**活性证据**——本副本 ledger sink 最后一次 durable append 距今
      *  的毫秒数(「turn 真在推进」的判别材料;与行 updatedAt 的进程心跳语义刻意分离)。**同副本
      *  best-effort**:缺席 = 无法证明(跨副本/重启后),不是「不活」——诚实缺席,绝不铸 0。消费端
-     *  (cli running 臂,[3779] C3)凭它区分「真忙的后台 run」与「久无进展的疑似僵局」,替代猜测文案。 */
+     *  (cli running 臂,[ref] C3)凭它区分「真忙的后台 run」与「久无进展的疑似僵局」,替代猜测文案。 */
     msSinceLastActivity?: number;
     /**
-     * #316(c)([4664]② 成文的洞 (c) 的修):**两面口径的对齐位**。
+     * [ref](c)([ref]② 成文的洞 (c) 的修):**两面口径的对齐位**。
      *
      * 病:poll 面(`GET /v1/runs/:id`)对「`running` 且 `now - updatedAt > runStaleSec`」的行**折叠**成
      * `status:"failed"`(+「run stalled (instance lost?)」),而本体把 run 行 `status` **原样**报 `running`。
@@ -110,10 +108,10 @@ export interface ActiveRunConflictBody {
      * `msSinceLastActivity` **并存**,壳凭它把两面对上(「poll 那边会说 failed = 这条大概率是死行」)。
      *
      * 🔴 **只在为真时在场**(与 `PendingGateMaterial.governanceForced` 同一条纪律):缺席 = 「没有陈旧的
-     * 证据」,**不是**「证明它活着」——判据只有 `updated_at` 一维,慢而活的 run 有误杀窗([4664]② 洞 (b)
+     * 证据」,**不是**「证明它活着」——判据只有 `updated_at` 一维,慢而活的 run 有误杀窗([ref]② 洞 (b)
      * 原样有效)。⇒ 这一位是**分诊材料**,不是终态断言。
      *
-     * 🔴 **只对 `running` 铸**:park 两态(suspended/needs_review)根本不在 `reapStale` 射程内([4664]②
+     * 🔴 **只对 `running` 铸**:park 两态(suspended/needs_review)根本不在 `reapStale` 射程内([ref]②
      * 洞 (a)),给它们标 stale 就是假材料。
      */
     stale?: true;
@@ -137,20 +135,20 @@ export declare function governanceOriginOf(gate: {
  */
 export interface ActiveRunConflictDoneResult {
     status: "failed";
-    /** [2373]C-1:与 409 体同一机器码——流腿客户端凭它认拒绝,禁按 byte-frozen 文案匹配。 */
+    /** [ref]C-1:与 409 体同一机器码——流腿客户端凭它认拒绝,禁按 byte-frozen 文案匹配。 */
     errorCode: "conflict.session_active_run";
     errorMessage: string;
     activeTaskId: string | null;
     activeTaskStatus?: string;
-    /** #245 S1:与 409 body 同键同语义(见 {@link ActiveRunConflictBody.msSinceLastActivity})。 */
+    /** [ref] S1:与 409 body 同键同语义(见 {@link ActiveRunConflictBody.msSinceLastActivity})。 */
     msSinceLastActivity?: number;
     /**
-     * #316(c):与 409 body 同键同语义(见 {@link ActiveRunConflictBody.stale})。
+     * [ref](c):与 409 body 同键同语义(见 {@link ActiveRunConflictBody.stale})。
      *
      * 🔴 **跨仓欠账,如实登记**(codex 交叉复审 R1-[medium] 验真后的真形):sema-sdk 的
      * `spec/openapi.yaml` 里 `ActiveRunConflictDoneResult` 是 `additionalProperties: false` 的**封闭**
      * schema,今天只声明 `status/errorCode/errorMessage/activeTaskId/activeTaskStatus/pendingGate` 六键。
-     * ⚠️ 亲验后的关键修正:这**不是本键引入的新问题** —— `msSinceLastActivity`(#245 S1)早就在这条
+     * ⚠️ 亲验后的关键修正:这**不是本键引入的新问题** —— `msSinceLastActivity`([ref] S1)早就在这条
      * done 帧上,同样没进那张封闭表,即**同族违例已存在**且没有任何门看得见它(producer-contract 只校
      * 409 体那条 op,不校这条 SSE 帧)。本批**刻意不**为了绕开它而让 done 帧与 409 体分家(「同材料禁
      * 分家」是本文件自己的纪律,分家换来的是两面口径再次相左 —— 正是本件在修的病)。
@@ -165,7 +163,7 @@ interface ConflictProbeDeps<TToken> {
     /** 结构形入参,但 `status` 取 run 行的**闭词表**(合并码重扫):判 park 要走词表属主
      *  `isParkedRunStatus`,而它的入参是穷举联合 —— 这一格写成开放 `string` 就只能在调用点裸 cast,
      *  绕开那道编译期执法(core 加一个 park 类成员时本文件不会红)。 */
-    /** `updatedAt`(#316(c)):stale 折叠的唯一判据维([4664]② 洞 (b):慢而活的 run 有误杀窗)。可选 —— 缺席
+    /** `updatedAt`([ref](c)):stale 折叠的唯一判据维([ref]② 洞 (b):慢而活的 run 有误杀窗)。可选 —— 缺席
      *  或不可解析 ⇒ `stale` 键诚实缺席(与本模块「材料是 best-effort 增强」同方向)。 */
     runStore?: {
         getRun?: (id: string) => Promise<{
@@ -174,11 +172,11 @@ interface ConflictProbeDeps<TToken> {
         } | null | undefined>;
     } | undefined;
     checkpointStore?: {
-        peekPendingScope?: (sessionId: string) => Promise<string | null | undefined>;
-        findPendingTokenBySession?: (sessionId: string, scope?: string) => Promise<TToken | null | undefined>;
+        peekPendingScope?: (sessionId: string, binding?: PendingRowBinding) => Promise<string | null | undefined>;
+        findPendingTokenBySession?: (sessionId: string, scope?: string, binding?: PendingRowBinding) => Promise<TToken | null | undefined>;
         /** 结构形(不 import core 的 `Checkpoint`):只声明本模块**真读**的几格。`riskDescriptor` 是
          *  core 在 mint 时挂到升级门上的判读元数据(display/triage only),`shellGateDoctrine` 是 2026-08-05
-         *  裁定加的取证格 —— 见下方 `governanceOriginOf` 的推导论证。`checkpointId`(#285,core 5.42.0)
+         *  裁定加的取证格 —— 见下方 `governanceOriginOf` 的推导论证。`checkpointId`([ref],core 5.42.0)
          *  是行的非秘密稳定身份,可选 —— legacy 行没有它(见 `PendingGateMaterial.checkpointId`)。 */
         get?: (token: TToken) => Promise<{
             checkpointId?: string;
@@ -190,13 +188,13 @@ interface ConflictProbeDeps<TToken> {
             };
         } | null | undefined>;
     } | undefined;
-    /** #220:出身归因的部署侧一半(缺席 ⇒ 归不出治理出身 ⇒ 键缺席 —— 与 best-effort 同方向)。 */
+    /** [ref]:出身归因的部署侧一半(缺席 ⇒ 归不出治理出身 ⇒ 键缺席 —— 与 best-effort 同方向)。 */
     governance?: GovernancePosture | undefined;
-    /** #316(c):stale 折叠的阈值(秒),生产装配 = `config.runStaleSec` —— 与 poll 面
+    /** [ref](c):stale 折叠的阈值(秒),生产装配 = `config.runStaleSec` —— 与 poll 面
      *  (`routes/runs.ts` 的 `deps.config.runStaleSec * 1000`)**同一个旋钮**,两面口径因此同源。
      *  缺席/非正数 ⇒ 不折叠(键缺席),等价于「本部署没有配这条判据」。 */
     runStaleSec?: number | undefined;
-    /** #245 S1:turn 活性读口(生产装配 = `readTurnActivityMs`,turn-activity.ts)。返回最后活性时刻
+    /** [ref] S1:turn 活性读口(生产装配 = `readTurnActivityMs`,turn-activity.ts)。返回最后活性时刻
      *  (epoch ms)或 undefined。可选:未装配/读不到 ⇒ `msSinceLastActivity` 键缺席,best-effort 同方向。 */
     turnActivity?: ((taskId: string) => number | undefined) | undefined;
 }

package/dist/http/active-run-conflict.js

@@ -1,5 +1,6 @@
 import { governanceMandatesShellGateAlways } from "../runtime-governance.js";
 import { isParkedRunStatus } from "../plugins/store-contracts.js";
+import { LIVE_RUN_GATE_KINDS } from "../plugins/checkpoint-store-sql.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 export const ACTIVE_RUN_CONFLICT_BASE_TEXT = "session already has an active run — POST /v1/runs/{activeTaskId}/cancel stops it (same-instance interactive runs abort immediately)";
 export function resumeEntryForGate(kind, ids) {
@@ -72,8 +73,9 @@ export async function buildActiveRunConflict(deps, sessionId, activeTaskId) {
         const cs = deps.checkpointStore;
         let pendingGate;
         if (cs?.findPendingTokenBySession) {
-            const scope = (await cs.peekPendingScope?.(sessionId)) ?? undefined;
-            const token = scope === null ? null : await cs.findPendingTokenBySession(sessionId, scope);
+            const runBinding = { gateKinds: LIVE_RUN_GATE_KINDS };
+            const scope = (await cs.peekPendingScope?.(sessionId, runBinding)) ?? undefined;
+            const token = scope === null ? null : await cs.findPendingTokenBySession(sessionId, scope, runBinding);
             const row = token ? await cs.get?.(token) : undefined;
             const gate = row?.gate;
             const kind = gate?.kind;

package/dist/http/route-ctx.d.ts

@@ -1,5 +1,5 @@
 /**
- * design/158 A9 — 路由域装配缝(`handle()` 按路由域拆多文件 + 装配器)。
+ * [ref] A9 — 路由域装配缝(`handle()` 按路由域拆多文件 + 装配器)。
  *
  * `createHttpServer` 建**一次** `RouteCtxBase`(deps/registry/helpers/local 四格),`handle()` 每请求把它
  * 加上一格 `req`(每请求局部量)交给按序尝试的域表。域模块只从这里取自己那份窄切片,**在函数首行解构**
@@ -47,11 +47,13 @@ export interface RouteHelpers {
     rateLimited(req: IncomingMessage, res: ServerResponse): boolean;
     quotaExceeded(req: IncomingMessage, res: ServerResponse): boolean;
     leaseDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
-    /** design/166-T1:治理窗 pre-admission(异步 202 车道的唯一 429 出路;key 公式与 core 单源)。 */
+    /** [ref]-T1:治理窗 pre-admission(异步 202 车道的唯一 429 出路;key 公式与 core 单源)。 */
     usageWindowDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
     safeDecode(seg: string): string | null;
     isFleetWide(req: IncomingMessage): boolean;
-    runOwnerOk(req: IncomingMessage, res: ServerResponse, owner: string | null): boolean;
+    /** 属主门。`notFoundForm` 选 not-yours 臂的 404 拼法:缺省 `"run"`(not_found.run 长文,[ref]);session
+     *  资源面传 `"session"`(not_found.session + "session not found")与其 unknown 臂同码同串(G52 [ref])。 */
+    runOwnerOk(req: IncomingMessage, res: ServerResponse, owner: string | null, notFoundForm?: "run" | "session"): boolean;
     sessionOwnerScope(req: IncomingMessage): {
         fleetWide: boolean;
         gateOwner: string | null;
@@ -82,7 +84,7 @@ export interface RouteRequestState {
  *  命名后好处不只是过 B4 门:两个消费域现在都能对同一个符号做 `import type` 标注,而不是各自重推断结构。 */
 export interface PreparedTaskSubmission {
     spec: TaskSpec;
-    /** #196:本次提交的执行 Runner —— 场景 hands=none 时是无手孪生(不挂 executionEnvFactory)。
+    /** [ref]:本次提交的执行 Runner —— 场景 hands=none 时是无手孪生(不挂 executionEnvFactory)。
      *  两个消费域一律用它,不再直接摸 `deps.runner`(那正是「场景表态了、执行点没听」的缝)。 */
     runner: Runner;
     auth?: RequestAuth;
@@ -94,7 +96,7 @@ export interface PreparedTaskSubmission {
 /** B4①(命名化):`driveResumeIntoRunLog` 的入参形(resume 家族共用)——原为 9 成员内联匿名对象。 */
 export interface DriveResumeArgs {
     token: CheckpointToken;
-    /** #196:续跑腿的执行 Runner。resume 会用同一条 resolveSpec 重解析场景,故与首跑选同一只 —— 否则
+    /** [ref]:续跑腿的执行 Runner。resume 会用同一条 resolveSpec 重解析场景,故与首跑选同一只 —— 否则
      *  一次续跑就把手带 band 重新 mount 回来(收窄只在首跑成立 = 没成立)。 */
     runner: Runner;
     sessionId: string;
@@ -109,7 +111,7 @@ export interface DriveResumeArgs {
      *  ask sees them — the decide leg's exemption grant). Contract: must not throw (callers swallow internally);
      *  awaited so the ordering guarantee is real, and a store write here is ms-scale vs the model leg. */
     onResumeCommitted?: () => Promise<void>;
-    /** [3829]/[3830]:调用方声明「本腿的 park 是终局后纯 park,session claim 已随终局 finalize 删除」——
+    /** [ref]/[ref]:调用方声明「本腿的 park 是终局后纯 park,session claim 已随终局 finalize 删除」——
      *  getActiveTaskId 缺席时**铸新 canonical taskId + createRun 全生命周期行**(wake 续跑=同 session 新一轮
      *  turn),而不是无行裸跑(不可取消/无计费归因/无 durable append/fleet 不可见,且 core `spec.taskId ??
      *  sessionId` fallback 会把 lastRunId 铸成 sessionId)。`source` 进 run 行元数据(runMeta 同列)。
@@ -118,7 +120,7 @@ export interface DriveResumeArgs {
     mintFreshRun?: {
         source: string;
     };
-    /** #316([4660] Inkglow 案 → [4664]① 定谳):**200 受理语义**——调用方声明「我的消费方按 poll/SSE 跟
+    /** [ref]([ref] Inkglow 案 → [ref]① 定谳):**200 受理语义**——调用方声明「我的消费方按 poll/SSE 跟
      *  终态,别让 HTTP 等模型往返」。在场为 `true` 时本腿在**受理点**(`resumeStream` 解析之后)立刻把
      *  `200 {taskId, status:"resuming", bindingEnforced:true}` 交回调用方,模型腿(流迭代 + 行驱动)继续
      *  在同一条 promise 链上跑完 —— 不是新写口,逐字还是那条 `createSerialLedgerAppend` 单写串行链。
@@ -133,7 +135,7 @@ export interface DriveResumeArgs {
      *  await,没有「CAS 已过、模型还没跑」这个缝可停 —— 在那条臂上提前受理就等于把绑定判别也异步化了
      *  (那是决策证明的一部分,不能丢)。故它维持同步长调用形,如实登记在 CHANGELOG/契约文档。
      *
-     *  **今天传 `true` 的调用方**([3833] 件 S-1 之后 = 全部有人在等响应的 HTTP 腿):legacy 任务级
+     *  **今天传 `true` 的调用方**([ref] 件 S-1 之后 = 全部有人在等响应的 HTTP 腿):legacy 任务级
      *  `/v1/approvals/:sessionId/decide`、`/v1/assistant/tasks/:id/resume`、`…/plan_review`、
      *  `/v1/sessions/:id/wake`、以及 live 回决腿的 parked 赎回席(`redeemParkedAsk`)。
      *  **唯一不设此位的**是内部 D-D SLA deny-sweep:它没有在等响应的人,提前受理对它零收益,而且那条
@@ -158,7 +160,7 @@ export interface RouteLegs {
      *  `sendError` 连 `extra` 一起回显。DESIGN-269 车2 的 A2A 腿必须传它 —— 那些 `extra`(尤其
      *  `scenario_unknown` 的**全部场景名**)对壳是指路材料,对一个外部 peer 是内部词表外泄。 */
     prepareSpec(req: IncomingMessage, res: ServerResponse, body?: TaskRequestBody, onTypedFailure?: (err: import("../security.js").HttpError) => void, 
-    /** S-46 件C:**腿身份**(不是能力表态)。`liveStream: true` 只由 `POST /v1/tasks/stream` 的装配点按
+    /** [ref] 件C:**腿身份**(不是能力表态)。`liveStream: true` 只由 `POST /v1/tasks/stream` 的装配点按
      *  URL 传 —— 那是全树唯一挂 HITL 活流投递面的腿,逐腿 `interactionPosture` 判据的第一条合取项。
      *  缺席 ⇒ 无人腿(bg / A2A / resume),行为字节不变。 */
     legFacts?: {
@@ -171,7 +173,7 @@ export interface RouteLegs {
      *  `/decide` = 人;内部 D-D SLA deny-sweep = 窗到期),而函数内部分辨不出谁在叫它 —— 必填参数把
      *  「漏报出处」变成编译错,不是一条下游把「没人答」渲染成「有人拒」的静默假出处。 */
     resumeCheckpoint(sessionId: string, decision: "approve" | "deny", reason: string | undefined, settledBy: ApprovalSettledBy, req?: IncomingMessage, answer?: QuestionAnswer, binding?: DecideBinding, 
-    /** S-02 codex R4(验真后修):remember 豁免的 grant 挂点。**工具名不再由路由自己读**(那是与本函数
+    /** [ref] codex R4(验真后修):remember 豁免的 grant 挂点。**工具名不再由路由自己读**(那是与本函数
      *  载入行分歧的第三次 scope-less 读,三读分歧下会给他人工具落豁免=提权)——由本函数把**已属主校验的
      *  载入 cp** 的工具名(`validatedToolName`,非 tool_approval / AskUserQuestion / legacy null ⇒ `null`
      *  = 无可记)一并回传,路由只对这个逐字落店。`overrideSessionId` = parked 腿的 root/host 会话 grant 锚。 */
@@ -179,10 +181,10 @@ export interface RouteLegs {
         overrideSessionId?: string;
         validatedToolName: string | null;
     }) => Promise<void>, 
-    /** #316:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/decide` 腿传 `true`;
+    /** [ref]:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/decide` 腿传 `true`;
      *  内部 D-D SLA deny-sweep 不传 —— 它没有在等响应的人,提前受理对它零收益而少一条同步失败面。 */
     acceptEarly?: boolean, 
-    /** S-02:调用方已验身份的裁定 —— stale 臂铸 `currentPending` 指路键前在被读回的行上重跑 decide 门
+    /** [ref]:调用方已验身份的裁定 —— stale 臂铸 `currentPending` 指路键前在被读回的行上重跑 decide 门
      *  同一属主判(缺席 ⇒ 恒不造键;判据属主=server.ts 铸键点注)。 */
     decider?: {
         principal?: string;
@@ -198,14 +200,14 @@ export interface RouteLegs {
     }>;
     /** assistant 抢占腿的复位(gate-kind 守卫 + 驱动)。 */
     resumePreempted(sessionId: string, req: IncomingMessage | undefined, 
-    /** [3833] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/resume` 腿传 `true`。 */
+    /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/resume` 腿传 `true`。 */
     acceptEarly?: boolean): Promise<{
         status: number;
         body: object;
     }>;
     /** notify-wake 域:唤醒一条 parked checkpoint。 */
     resumeWake(sessionId: string, message: string | undefined, caller: string | undefined, req: IncomingMessage | undefined, 
-    /** [3833] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/wake` 腿传 `true`
+    /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/wake` 腿传 `true`
      *  —— 本腿走 `mintFreshRun`,受理体里的 `taskId` 因此是**新铸的**那个(壳的 poll 锚)。 */
     acceptEarly?: boolean): Promise<{
         status: number;
@@ -213,19 +215,19 @@ export interface RouteLegs {
     }>;
     /** assistant plan_review 三态腿。 */
     resumePlanReview(sessionId: string, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, req: IncomingMessage | undefined, 
-    /** [4277]/[4288] 件5:`decide_404` 判别日志的附加位(只进日志,不上 wire;身份只记有无不记值)。 */
+    /** [ref]/[ref] 件5:`decide_404` 判别日志的附加位(只进日志,不上 wire;身份只记有无不记值)。 */
     log?: {
         taskId?: string;
         principalPresent?: boolean;
     }, 
-    /** [3833] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/plan_review` 腿传 `true`。 */
+    /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/plan_review` 腿传 `true`。 */
     acceptEarly?: boolean): Promise<{
         status: number;
         body: object;
     }>;
 }
 /**
- * [3833] 件 S-2 —— resume 族**受理点的断连留痕**(裁定:维持 detach,补观察面)。
+ * [ref] 件 S-2 —— resume 族**受理点的断连留痕**(裁定:维持 detach,补观察面)。
  *
  * ## 裁定(fable,与 S-1 同批;这里是它的唯一属主)
  *
@@ -258,7 +260,7 @@ export declare function noteResumeClientGone(res: ServerResponse, out: {
     info?: (msg: string, fields?: Record<string, unknown>) => void;
 } | undefined): void;
 /**
- * #359②(A-075.6)—— resume 族四腿(`/decide` / `/assistant/tasks/:id/resume` / `/plan_review` /
+ * [ref]②([ref])—— resume 族四腿(`/decide` / `/assistant/tasks/:id/resume` / `/plan_review` /
  * `/wake`)的**唯一**回执发送口。
  *
  * 为什么是一个函数而不是「在四处各加一行 `res.setHeader`」:这四条腿此前已经各自记得调
@@ -297,14 +299,14 @@ export interface RouteMiss {
     fell: boolean;
 }
 /**
- * #262(A-041 存在性 oracle 封口)——`not_found.run` 的**唯一**文案源,unknown 与 not-yours 两臂共用。
+ * [ref]([ref] 存在性 oracle 封口)——`not_found.run` 的**唯一**文案源,unknown 与 not-yours 两臂共用。
  * 修前:unknown 臂发这条长指路文案、not-yours 臂发短文「run not found」,同 code 下按**文案长度**即可
  * 枚举他人 run id 的存在性(822 行「no existence oracle」注释的意图被长短差打穿)。not-yours 臂只可能
  * 拿到非 a\* id(store 查到行才有 owner 比对;a\* 与 wa\* 形 id 永不在 run store)⇒ 非 a\* 长文串足以让
- * 两臂逐字节同形,指路价值不丢。钉=audit-fixes-http「#262」格(两臂全文比对);文案变更走
+ * 两臂逐字节同形,指路价值不丢。钉=audit-fixes-http「[ref]」格(两臂全文比对);文案变更走
  * api-error-text-freeze 基线流程。
  */
 export declare const RUN_NOT_FOUND_MESSAGE = "run not found \u2014 the id belongs to no run in this deployment's run store (a run from another server process, or an in-memory store that did not survive a restart, is not visible here)";
-/** [1434] 前缀=域判别子既成契约:a\* 与 wa\* 形 id 给 TaskOutput/journal 指路;其余给 {@link RUN_NOT_FOUND_MESSAGE}。 */
+/** [ref] 前缀=域判别子既成契约:a\* 与 wa\* 形 id 给 TaskOutput/journal 指路;其余给 {@link RUN_NOT_FOUND_MESSAGE}。 */
 export declare function runNotFoundMessage(id: string): string;
 //# sourceMappingURL=route-ctx.d.ts.map

package/dist/http/routes/a2a-serve.d.ts

@@ -36,12 +36,12 @@ export declare function buildAgentCard(serve: A2aServeConfig): A2aAgentCard;
  */
 export declare function handleA2aServe(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
 /**
- * 🔴 **反枚举不变式(A-041)在本模块的执行点**:`tasks/get` 的「这条 task 不存在」与「这条 task 不是
+ * 🔴 **反枚举不变式([ref])在本模块的执行点**:`tasks/get` 的「这条 task 不存在」与「这条 task 不是
  * 你的」必须**逐字节**同形 —— 同一个 code、同一条 message、同一个(缺席的)data。两臂共用**这一个**
  * 常量就是那条不变式的机制支撑:任何一臂想说得更具体,都得先改这里,而改这里会被
  * `a2a-serve-rpc.test.ts` 的逐字节比对当场钉住。
  *
- * (同族先例:`route-ctx.ts` 的 `RUN_NOT_FOUND_MESSAGE` —— #262 抓到的正是两臂**文案长度**不同就足以
+ * (同族先例:`route-ctx.ts` 的 `RUN_NOT_FOUND_MESSAGE` —— [ref] 抓到的正是两臂**文案长度**不同就足以
  * 枚举他人 run id 的存在性。JSON-RPC 侧一模一样,只是载体从 HTTP body 换成了 error 对象。)
  */
 export declare const A2A_TASK_NOT_FOUND_MESSAGE = "task not found";

package/dist/http/routes/admin-config-refresh.d.ts

@@ -1,5 +1,5 @@
 /**
- * #322 批1 追加件(clay 当场裁定,design/322 批1 行):`POST /v1/admin/config/refresh` —— operator 改完
+ * [ref] 批1 追加件(clay 当场裁定,[ref] 批1 行):`POST /v1/admin/config/refresh` —— operator 改完
  * 配置**不等 60s tick**,手动触发一次立即拉取。
  *
  * 族属 = `POST /v1/admin/drain` 逐字同族(operator lane:同一条 `explicitOperatorOk` 门、billable=false、

package/dist/http/routes/admin-drain.d.ts

@@ -1,5 +1,5 @@
 /**
- * #291(C17,[4470]/[4472] 认领,黑板 [4472] 原文即本口的契约):`POST /v1/admin/drain {reason}` ——
+ * [ref](C17,[ref]/[ref] 认领,黑板 [ref] 原文即本口的契约):`POST /v1/admin/drain {reason}` ——
  * 编排壳在发停机信号(SIGTERM)**之前**先调本口显式声明停机因由;server 记入 `drainState.reason`,
  * draining 期间由 `/health`(`drainReason`)与 503 draining 体(`reason`)透出。未声明 = 两面键缺席
  * (additive,不编数)——升级/缩容/驱逐在消费端因此可判别,而不是一律读成「实例没了」。
@@ -11,9 +11,9 @@
  * operator 门(空表恒拒,fail-closed)已是正确强度。
  *
  * reason 校验:非空 trim 后 string ≤ {@link MAX_DRAIN_REASON_CHARS} —— 它会进 /health 与 503 体
- * (消费面是监控/壳),超长或怪型响亮拒([3425] 坏值立律),拒绝不留痕(不写半个值)。
+ * (消费面是监控/壳),超长或怪型响亮拒([ref] 坏值立律),拒绝不留痕(不写半个值)。
  *
- * 🔴 **写侧特权、读侧公开 —— 这条不对称是刻意的,但必须被写的人知道**(A-054.11,2026-08-19 合并重扫
+ * 🔴 **写侧特权、读侧公开 —— 这条不对称是刻意的,但必须被写的人知道**([ref],2026-08-19 合并重扫
  * partial,存活断言):本口是 operator-only + fail-closed(空 `OPERATOR_PRINCIPALS` 恒拒),而透出面里
  * `/health` 在 `server.ts` 的鉴权门**之前**、无鉴权、缺省全网卡监听,USAGE 三处白纸黑字把它定为「无需
  * 鉴权」—— 任何能连到这个端口的人都读得到这段**运维手打的自由文本**。
@@ -22,7 +22,7 @@
  * operator 自选,且窗口只在 draining 期;③ 同一免鉴权体上早已有 `dataRoot` 绝对路径 / `pid` / `port` /
  * `instanceId` / `configHash` / `storeProbe`,单独收紧本键不改变那面的暴露量级。
  * (那条另立的兄弟件 —— `storeProbe.error` 把**原始异常 message 未截断**塞出去、DSN 片段可随之外泄 ——
- * 已在 #305 修掉:免鉴权面上它改成闭集词,原文只走日志轴。两件的判据不同故不合并:本键的值由 operator
+ * 已在 [ref] 修掉:免鉴权面上它改成闭集词,原文只走日志轴。两件的判据不同故不合并:本键的值由 operator
  * 自选且窗口只在 draining 期,`storeProbe.error` 的值则来自不受控的驱动异常。)
  * ⇒ 真正的缺口是**告诫缺席**:此前路由头注、400 文案、CHANGELOG、wire 契约四处都只说「透出」,没有一处
  * 说「其中一面免鉴权」,操作员要拼出「我写的字是公开的」得自己合并两处文档去推理。本批把它写进**写口

package/dist/http/routes/admin-memory-optout.d.ts

@@ -1,19 +1,19 @@
 /**
- * design/383 §3.1 / S-50 §1.3(S-49 S-2)—— per-principal **memory-capture opt-out 授权表**的 operator 四口:
+ * [ref] §3.1 / [ref] §1.3([ref] S-2)—— per-principal **memory-capture opt-out 授权表**的 operator 四口:
  *
  *   · `GET    /v1/admin/memory-optout`             → `{ deploymentDefault: Row|null, overrides: Row[] }`
  *   · `PUT    /v1/admin/memory-optout`             body `{allow, note?}` → 部署缺省行 upsert(哨兵 `principal=''`)
  *   · `PUT    /v1/admin/memory-optout/:principal`  body `{allow, note?}` → per-principal 覆盖行 upsert
  *   · `DELETE /v1/admin/memory-optout/:principal`  → 撤覆盖(回落部署缺省);`{ deleted: boolean }` 诚实答
  *
- * Row = `{ principal, allow, updatedAtMs, updatedBy, note? }`(审计行内,S-50 §1.3;`updatedBy` = 调用方 operator
+ * Row = `{ principal, allow, updatedAtMs, updatedBy, note? }`(审计行内,[ref] §1.3;`updatedBy` = 调用方 operator
  * principal,server 铸,body 不收)。
  *
  * ── 稿偏离两条(如实记)────────────────────────────────────────────────────────────────────────────
- * ① S-50 §1.1/§1.3 写的是 `orgDefault` + `(org_id, principal)`。亲读本仓(2026-08-30 侦察):server **没有 org 身份维**
+ * ① [ref] §1.1/§1.3 写的是 `orgDefault` + `(org_id, principal)`。亲读本仓(2026-08-30 侦察):server **没有 org 身份维**
  *    (租户维 = 单 principal;`org` 只是记忆 scope 目录里的词),给表/wire 铸一根没人能填的 `org_id` 是编数据。一台
  *    worker = 一个租户面 ⇒ 「org 级缺省」落成**部署级缺省**,wire 键名随实体改叫 `deploymentDefault`。折叠律不变。
- * ② S-50 §1.3 把部署缺省写成 `PUT …/memory-optout/default`。codex R1-[medium] 验真:`default` 是一个**合法 principal
+ * ② [ref] §1.3 把部署缺省写成 `PUT …/memory-optout/default`。codex R1-[medium] 验真:`default` 是一个**合法 principal
  *    拼写**,字面路径 `/default` 与 `%64efault`(解码后同为 `default`)在第一版里分派到**两个不同的行**(哨兵行 vs
  *    一条名叫 default 的覆盖行)—— 命名空间碰撞,而且 DELETE 侧还不对称。修法不是「解码后再保留一个词」(那只是把
  *    碰撞改成一条不可寻址的 principal),而是**让缺省行住在集合根**:`PUT /v1/admin/memory-optout`(集合本身的
@@ -35,7 +35,7 @@
  * 本仓 501 `capability.*` 族的定义(`capability.memory_engine_required` / `capability.outcome_ledger_required`
  * 同族)。能力位 `memoryOptOutGrant`(`GET /v1/capabilities`)读同一个事实 + operator 名单非空。
  *
- * ── 撤销窗(S-50 §1.4)──────────────────────────────────────────────────────────────────────────
+ * ── 撤销窗([ref] §1.4)──────────────────────────────────────────────────────────────────────────
  * 写后**零缓存**:resolver 腿(`RuntimeCaps.allowMemoryOptOut`)每次 prepare 直读同一张表 ⇒ 下一次带声明的
  * prepare 即读到新 verdict(撤权后新声明具名拒;已声明会话 record wins,core 判,server 零码)。
  */

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

@@ -1,5 +1,5 @@
 /**
- * design/183 §4.3 —— **收编面**(operator lane):`POST /v1/adoption` 发起、`GET /v1/adoption/:id` 读状态。
+ * [ref] §4.3 —— **收编面**(operator lane):`POST /v1/adoption` 发起、`GET /v1/adoption/:id` 读状态。
  *
  * 形态:一次性的**部署级动作**,不是常驻业务面 —— 所以它 billable=false(零模型工作)、operator-only、
  * 且在没有 SQL 后端的部署上诚实 501(收编重绑的是多租身份轴,local 后端根本没有那个轴)。

package/dist/http/routes/agents-roster.d.ts

@@ -1,5 +1,5 @@
 /**
- * #A1([4147] 窗三件批 件3;C-R13 链的 server 前置)—— 后台 agent **名册读面**
+ * #A1([ref] 窗三件批 件3;[ref] 链的 server 前置)—— 后台 agent **名册读面**
  * `GET /v1/agents/roster`。
  *
  * ## 读的是哪个店(两个「名册」概念的定界)

package/dist/http/routes/approvals-assistant.d.ts

@@ -1,10 +1,10 @@
 /**
- * design/158 A9 域模块 —— 人在环审批面(durable F4 + legacy)与 assistant-scheduler 三动词。
+ * [ref] A9 域模块 —— 人在环审批面(durable F4 + legacy)与 assistant-scheduler 三动词。
  *
  * 路由(前缀 `/v1/approvals` 与 `/v1/assistant`):
  *   · durable 腿(接了 checkpointStore 时优先):list / stream(SSE 原生推送)/ decide|answer / preempt /
  *     resume / plan_review;
- *   · legacy 腿(approvalStore 轮询车道)已于 5.0.0 整体退役([2354]/[2356] A-5)——无 checkpointStore 时
+ *   · legacy 腿(approvalStore 轮询车道)已于 5.0.0 整体退役([ref]/[ref] A-5)——无 checkpointStore 时
  *     `/v1/approvals` 落 404(诚实缺席),不再有 trusted-header 决裁面。
  *
  * 所有会**烧模型**的续跑都经 `ctx.legs.*`(resumeCheckpoint / resumePreempted / resumePlanReview)走 resume
@@ -25,20 +25,20 @@ export declare const ASSISTANT_PLAN_REVIEW_RE: RegExp;
 export declare function isQuestionAnswer(v: unknown): v is QuestionAnswer;
 export declare function handleApprovalsAssistant(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
 /**
- * GET /v1/approvals/stream (design/80 native push): SSE — pushes pending-approval deltas so the portal
+ * GET /v1/approvals/stream ([ref] native push): SSE — pushes pending-approval deltas so the portal
  * SUBSCRIBES ONCE instead of polling GET /v1/approvals every ~10s (better UX: near-real-time + no client poll
  * loop). Polls listPending(scope) and diffs against the prior snapshot: `pending` for a new suspend, `resolved`
  * for a decided/expired/gone one. Cross-replica BY CONSTRUCTION — the poll reads the SHARED checkpoint table,
  * so a suspend on ANY replica is seen by an operator streaming on a DIFFERENT replica. A transient DB blip
  * heartbeats + retries (never kills the stream); a 15-min cap + req-close end it (parity with streamTaskTrace).
- * Poll-granularity caveat (**narrowed** by [3684]②): the delta now re-emits a `pending` frame whenever a key's
+ * Poll-granularity caveat (**narrowed** by [ref]②): the delta now re-emits a `pending` frame whenever a key's
  * WIRE PROJECTION changes (upsert), not only when the key enters — so a same-key re-suspend within one interval
  * IS visible as long as anything on the row differs. What still shows no delta is the strictly degenerate case:
  * a resolve + re-suspend on the same (session,toolCallId) whose projection is BYTE-IDENTICAL — indistinguishable
  * by construction, and harmless (the card the operator sees is the card that is pending). Pins: the two halves of
  * `test/wire-pairing-approvals-stream.test.ts` S3b (changed ⇒ re-emit with the NEW payload; unchanged ⇒ silence).
  *
- * A-002.19(2026-08-09 亲验定性=设计接受,非欠账):每连接自跑 pollMs 轮询打共享 checkpoint 表,
+ * [ref](2026-08-09 亲验定性=设计接受,非欠账):每连接自跑 pollMs 轮询打共享 checkpoint 表,
  * 之所以不建 fan-out/单轮询器基建——①消费方=portal 运营面,并发连接数量级为个位(不是用户面);
  * ②listPending 走 (scope,status) 索引,单查成本与一次 /v1/approvals 轮询同阶,而本路正是替代客户端
  * ~10s 轮询的(净负载持平或更低);③DB blip 已 fail-soft(心跳+下拍重试),15-min cap 兜顶。连接
@@ -46,7 +46,7 @@ export declare function handleApprovalsAssistant(req: IncomingMessage, res: Serv
  * 演化,不是现在的缺陷。
  */
 export declare function streamApprovals(req: IncomingMessage, res: ServerResponse, cs: Pick<CheckpointStoreFull, "listPending">, scope: string | undefined, 
-/** [3684]②:出身归因的部署侧一半(缺席 ⇒ 归不出治理出身 ⇒ 键缺席,与 best-effort 同方向)。**位置在
+/** [ref]②:出身归因的部署侧一半(缺席 ⇒ 归不出治理出身 ⇒ 键缺席,与 best-effort 同方向)。**位置在
  *  `pollMs` 之前**是刻意的:`pollMs` 只有测试传,而本参数是每个生产调用点都必须给的那一个。 */
 governance?: GovernancePosture, pollMs?: number): Promise<void>;
 //# sourceMappingURL=approvals-assistant.d.ts.map

package/dist/http/routes/approvals-assistant.js

@@ -1,4 +1,5 @@
 import { DECIDED_REPLAY_SCAN_CAP, approvalPayloadFingerprint } from "../../plugins/checkpoint-store-sql.js";
+import { APPROVAL_GATE_KINDS } from "../../tool-approval.js";
 import { isParkedRunStatus } from "../../plugins/store-contracts.js";
 import { principalFrom, decodeCheckpointScope, PRINCIPAL_TOKEN_HEADER, APPROVAL_MAC_HEADER, APPROVAL_MAC_KID_HEADER } from "../../security.js";
 import { verifyDirectDoorProof } from "../../principal-jwt.js";
@@ -457,7 +458,9 @@ async function handleApprovalsAssistantBody(req, res, url, ctx, miss) {
             const operators = deps.config.operatorPrincipals;
             const explicitOperator = explicitOperatorOk(deciderPrincipal, operators);
             if (!explicitOperator) {
-                const cpScope = await cs.peekPendingScope(sessionId);
+                const cpScope = await cs
+                    .peekPendingScope(sessionId, { gateKinds: APPROVAL_GATE_KINDS })
+                    .then((s) => (s === undefined ? cs.peekPendingScope(sessionId) : s));
                 const decodedCpScope = cpScope != null ? decodeCheckpointScope(cpScope) : undefined;
                 const ownsIt = cpScope == null || decodedCpScope === undefined || decodedCpScope === deciderPrincipal;
                 if (!ownsIt) {

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

@@ -1,5 +1,5 @@
 /**
- * design/158 A9 域模块 —— 能力/场景/模型目录只读面。
+ * [ref] A9 域模块 —— 能力/场景/模型目录只读面。
  *
  * 路由:`GET /v1/capabilities/scenarios/:name`、`GET /v1/capabilities`、`GET /v1/models`。
  * 三条都在全局 service-credential 门**之后**(config 面非密只读),装配表里的位置必须保住这一点。

package/dist/http/routes/capabilities.js

@@ -156,6 +156,7 @@ async function handleCapabilitiesBody(req, res, url, ctx, miss) {
                 return allow.filter((n) => Object.hasOwn(live, n));
             })(),
             manualCompact: Boolean(deps.runStore),
+            configCatalog: deps.config.configCatalogEnabled === true && deps.config.operatorPrincipals.length > 0,
         });
         return;
     }

package/dist/http/routes/config-catalog.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DESIGN-278 §5 S2([ref])—— `GET /v1/config/catalog`:配置目录自描述端点(operator lane)。
+ *
+ * TOB 运维在 web 上要一个**不撒谎**的配置目录:哪个键、什么腿(env/center)、改了何时生效
+ * (hot/restart-片名/deploy/inert)、本机实际值 —— 今天这些事实散在 config.ts 数千行与三份文档里,
+ * 人肉汇编必然漂移。目录本体(逐键登记 + 实算)在 `src/config-catalog.ts`(D1 双向对账门钉住完备性),
+ * 本文件只做门与投影。
+ *
+ * 门序 = `POST /v1/admin/config/refresh` 逐字同族(operator lane):身份 → 授权 → 应答;billable=false,
+ * 刻意不吃 drain / roster-pending 两道 503(排障读面在停机窗里恰恰要打得通)。
+ *
+ * 🔴 鉴权 = `explicitOperatorOk`(空名单=谁都不是)——设计稿 §0.5 点名**禁** `isOperator` 那个
+ * 「空名单=人人都是」的 fail-open 谓词:本面是部署事实外泄口(env 在场性/后端形态/限额值),
+ * 单用户形也不放宽。
+ *
+ * 🔴 旋钮 `CONFIG_CATALOG_ENABLED=false` ⇒ **本域不认领**(装配器尾部 404 `not_found.route`)——
+ * 与 memory-consolidation 阀门同判:旋钮没开是一句运维表态(合规部署不想让部署事实上 wire),
+ * 不是部署能力缺失,404 的动作是「去把旋钮打开」,501 会指去一条修不好的路。能力位 `configCatalog`
+ * 与本判据同源(capabilities.ts,两项合取)。
+ *
+ * 🔴 secret 纪律:值的裁剪在 catalog 构建层(secret=在场位、opaque=在场位+长度、url=剥 userinfo),
+ * 本文件不再碰值 —— 一处裁剪,机器钉 = test/config-catalog.test.ts 的响应体 canary 扫描格。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteCtx } from "../route-ctx.js";
+export declare const CONFIG_CATALOG_PATH = "/v1/config/catalog";
+export declare function handleConfigCatalog(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=config-catalog.d.ts.map

package/dist/http/routes/config-catalog.js

@@ -0,0 +1,42 @@
+import { DOMAINS } from "@sema-agent/settings-schema";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+import { configKnobTable } from "../../config.js";
+import { buildConfigCatalog } from "../../config-catalog.js";
+export const CONFIG_CATALOG_PATH = "/v1/config/catalog";
+const OPERATOR_ONLY_MESSAGE = "the config catalog is operator-only: the caller principal is not in OPERATOR_PRINCIPALS (an empty list means NO one is an operator — configure it to enable this endpoint)";
+export async function handleConfigCatalog(req, res, url, ctx) {
+    const miss = { fell: false };
+    handleConfigCatalogBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+function handleConfigCatalogBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    const path = url.split("?")[0] ?? url;
+    if (req.method !== "GET" || path !== CONFIG_CATALOG_PATH) {
+        miss.fell = true;
+        return;
+    }
+    if (deps.config.configCatalogEnabled !== true) {
+        miss.fell = true;
+        return;
+    }
+    const principal = gatedPrincipal(req, deps.config);
+    if (deps.config.requirePrincipal && !principal) {
+        sendError(res, 401, "auth.principal_required", `missing principal header '${deps.config.principalHeader}'`);
+        return;
+    }
+    if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+        sendError(res, 403, "auth.operator_only", OPERATOR_ONLY_MESSAGE);
+        return;
+    }
+    res.setHeader("Cache-Control", "no-store");
+    sendJson(res, 200, buildConfigCatalog({
+        config: deps.config,
+        env: process.env,
+        knobs: configKnobTable(),
+        centerDomains: DOMAINS,
+        centerManagedKeys: deps.configCenterManagedKeys?.(),
+    }));
+}
+//# sourceMappingURL=config-catalog.js.map