@sema-agent/server 7.3.0 → 7.5.0

package/dist/hooks/hook-runner.js

@@ -65,6 +65,24 @@ export const MAX_HOOK_HTTP_HEADERS = 32;
 export const MAX_HOOK_OUTPUT_BYTES = 1024 * 1024;
 /** 喂给模型的 deny 原因/additionalContext 的单条长度上限(字符)。 */
 const MAX_HOOK_FEEDBACK_CHARS = 4_096;
+/**
+ * 一次事件里所有 hook 上下文片段**聚合后**喂给模型的总量上限(字符)。
+ *
+ * 为什么单条帽不够:一次事件最多 {@link MAX_HOOK_ENTRIES_PER_EVENT} 条(parseHooksConfig 的广度闸),
+ * 每条最多推两段(`decision:"block"` 的 reason + `hookSpecificOutput.additionalContext`),
+ * {@link composeHooks} 再把部署槽与 task 槽的**成品**拼一次 —— 单条 4096 相乘后一次注入可达 ~256KB,
+ * 而这些字符是**逐次工具调用**进模型可见文本的(core `hooks.js` 的 preToolContext / `prepare-task.js`
+ * 的 tool_result 追加 / `runtask.js` 的 Stop follow-up),不是日志。
+ *
+ * 帽值取 10_000 的依据:模型可见文本在本栈的既有预算量纲就是 10k —— core `truncateError`
+ * (`src/core/tool-errors.ts`)的 10k 中截,逐字锚 CC 序列化器 `A7e` 的 `1e4`;#181 战役里 core 还要给
+ * `beforeToolCall` block reason 补一道同值兜底闸。取同一量级 = 「一次 hook 注入 ≤ 一份错误文本预算」,
+ * 且 4096 的单条帽保证**前两条**钩子的话仍整段进得去(截断是配置广度的代价,不是常态)。
+ */
+export const MAX_HOOK_CONTEXT_TOTAL_CHARS = 10_000;
+/** 帽满时仍值得保留的最短残段(字符)。比这更短的尾巴不是信息:模型会把半句话读成完整指令,
+ *  宁可整条落进"省略"计数。 */
+const MIN_HOOK_CONTEXT_PARTIAL_CHARS = 256;
 /** PostToolUse payload 里 tool_response 文本投影的上限(字符)——工具结果可能是 MB 级。 */
 const MAX_TOOL_RESPONSE_CHARS = 32_768;
 /** stdin payload 里 tool_input JSON 投影的上限(字符;巨大 tool_input 经 JSON.stringify 造成
@@ -233,6 +251,104 @@ const DEFAULT_AGENT_HOOK_TIMEOUT_SECONDS = 120;
 function clip(s, n) {
     return s.length > n ? `${s.slice(0, n)}…(${s.length})` : s;
 }
+/**
+ * hook 上下文片段 → 喂给模型的单串。**所有** `additionalContext` 聚合点的唯一属主(此前是同一个
+ * `contexts.join("\n")` 表达式抄在二十余处,总量帽无处可挂 —— 那正是漂移成因)。
+ *
+ * 三条语义,都是承重的:
+ *  1. **顺序保留、只截尾**:先来的钩子先说话;一旦装不下就停,后面的条目一律不再挤进来(哪怕更短)。
+ *     按长度重排会让"第 3 条钩子的话"随别人的长度忽隐忽现,排障时无从复现。
+ *  2. **截断可见**:尾巴挂一行标记说明省了几条、丢了多少字符。静默丢弃会让 hook 作者以为自己的
+ *     context 生效了,而模型那头根本没见过 —— 这类"以为配好了"的缺席比长文本本身更贵。
+ *  3. **标记不计预算**:与 core `truncateError` / CC `A7e` 同姿势(marker 不占那 10k),否则帽值的
+ *     含义会随标记文案长度漂。
+ */
+export function buildHookContext(parts) {
+    const present = parts.filter((p) => p.length > 0).map(readHookContextPart);
+    if (present.length === 0)
+        return undefined;
+    const kept = [];
+    let used = 0;
+    let truncating = false;
+    let messages = 0;
+    let omitted = 0;
+    let droppedChars = 0;
+    for (const part of present) {
+        // 内层的账先并进来(标记读回,见 {@link readHookContextPart}),再谈这一轮自己丢了什么。
+        messages += part.messages;
+        omitted += part.omitted;
+        droppedChars += part.dropped;
+        if (!truncating) {
+            const sep = kept.length > 0 ? 1 : 0; // join 的 "\n" 也占预算
+            const room = MAX_HOOK_CONTEXT_TOTAL_CHARS - used - sep;
+            if (room >= part.body.length) {
+                if (part.body.length > 0) {
+                    kept.push(part.body);
+                    used += sep + part.body.length;
+                }
+                continue;
+            }
+            truncating = true;
+            // 只有**单条**发言可以切尾:切了它仍是"部分在场",账目诚实(dropped 记尾巴,omitted 不变)。
+            // 已聚合的成品代表内层多条、正文里却没有条目边界 —— 切一刀会把第 2..N 条整个抹掉却记 0 条省略,
+            // 标记恰好在最常走的两层合流路上说谎(codex 复审 R4,亲核属实)。⇒ 它要么整段留,要么整条丢。
+            if (part.messages === 1 && room >= MIN_HOOK_CONTEXT_PARTIAL_CHARS) {
+                kept.push(part.body.slice(0, room));
+                used += sep + room;
+                droppedChars += part.body.length - room;
+                continue;
+            }
+        }
+        // 整条不见 = 它代表的**全部**条目都不见。内层已经报过的那几条上面加过了,这里只补差额
+        // ——否则一个"3 of 5"的成品被整条丢掉会记成 8 条,报出"省掉的比总数还多"这种自相矛盾的账。
+        omitted += part.messages - part.omitted;
+        droppedChars += part.body.length;
+    }
+    const body = kept.join("\n");
+    if (droppedChars === 0)
+        return body;
+    const marker = `[hook context truncated at ${MAX_HOOK_CONTEXT_TOTAL_CHARS} chars: ${omitted} of ${messages} hook messages omitted, ${droppedChars} characters dropped]`;
+    return kept.length > 0 ? `${body}\n${marker}` : marker;
+}
+/** 截断标记的尾锚形。帽值**逐字写进模式**(不是 `\d+`):只认"我们自己这一版才会写出的那一份",
+ *  别处飘来的同类文字连模式都不匹配。 */
+const HOOK_CONTEXT_MARKER_RE = new RegExp(`\\n\\[hook context truncated at ${MAX_HOOK_CONTEXT_TOTAL_CHARS} chars: (\\d+) of (\\d+) hook messages omitted, (\\d+) characters dropped\\]$`);
+/** 读回标记时接受的数字上界(2^42)。比任何真值大若干数量级,又小到几十条相加也绝不越过安全整数
+ *  —— 伪造的巨数因此根本进不来,合并加法也不必每一步复验溢出。 */
+const MAX_HOOK_CONTEXT_PARSED_COUNT = 2 ** 42;
+/**
+ * 片段 → 内容 + 它自带的截断账。
+ *
+ * 为什么必须能**读回**自己写的标记:`composeHooks` 会把 {@link buildHookContext} 的成品当片段再喂一次
+ * (部署槽在场即走这条路 —— 是常态不是边角)。标记按内容处理会犯两桩:①切在标记中间 ⇒ 模型读到半截
+ * 标记;②外层重新记账 ⇒ 内层丢掉的那一万多字符凭空消失,标记数字变成谎。标记既然不计预算,读回时也
+ * 不能算内容;把它携带的账并进外层,函数对自己的输出就是幂等的。
+ *
+ * 🔴 这把尺子对着的是**不可信文本**(钩子想吐什么就吐什么),所以只认"我们自己才写得出的那一份":
+ * 帽值逐字相等(在模式里)、`dropped ≥ 1`(我们从不在零丢弃时写标记)、`omitted ≤ messages`、
+ * `messages ≥ 1`、数字都在 {@link MAX_HOOK_CONTEXT_PARSED_COUNT} 内。任一条不合 ⇒ **整段当普通内容**。
+ * 认下之后也不会有"内容静默少一行":认下 ⇒ `dropped > 0` ⇒ 输出必然带标记 —— 摘掉的那一行总是被
+ * **重写**回去(数字可能被合并),从不是被删掉。伪造得刚好合规只会让记账口径偏,不改任何裁决;
+ * 而且钩子配置在单用户闸内,伪造者就是这份账的读者本人。
+ */
+function readHookContextPart(part) {
+    const m = HOOK_CONTEXT_MARKER_RE.exec(part);
+    if (!m)
+        return { body: part, messages: 1, omitted: 0, dropped: 0 };
+    const omitted = Number(m[1]);
+    const messages = Number(m[2]);
+    const dropped = Number(m[3]);
+    const sane = (n) => Number.isSafeInteger(n) && n <= MAX_HOOK_CONTEXT_PARSED_COUNT;
+    if (!sane(omitted) || !sane(messages) || !sane(dropped) || messages < 1 || omitted > messages || dropped < 1) {
+        return { body: part, messages: 1, omitted: 0, dropped: 0 };
+    }
+    return { body: part.slice(0, part.length - m[0].length), messages, omitted, dropped };
+}
+/** {@link buildHookContext} 的字段形(聚合点全是 `...spread` 进结果对象):空 → 不产字段。 */
+function buildHookContextField(parts) {
+    const text = buildHookContext(parts);
+    return text === undefined ? {} : { additionalContext: text };
+}
 /** 跑一条 command hook:sh -c,stdin=payload JSON(CC-verbatim),超时 SIGKILL,输出各限 1MiB。 */
 function runCommandHook(entry, payload, ctx) {
     return new Promise((resolve) => {
@@ -706,6 +822,10 @@ export function createTaskHooks(config, ctx) {
             let currentInput = input;
             let rewritten = false;
             let asked;
+            // #157 fail-open 治理(P 类,tag `server.hooks.pretooluse-unknown-permission-word`):本轮见过
+            // 词表外的 `permissionDecision`。安全域闭集词表的 miss 不是"没意见"——钩子作者**表过态**,只是
+            // 用了我们不认识的词;把它折成放行等于替他改判。置位后禁止本轮铸 `action:"allow"`(见末尾折叠)。
+            let unknownDecision = false;
             const contexts = [];
             const deadlineAt = Date.now() + MAX_HOOK_EVENT_TOTAL_SECONDS * 1000; // 跨全部组的事件级预算
             // 逐条串行(deny 立即短路;updatedInput 串进后续条目 payload——确定性优先,CC 的并行聚合语义
@@ -732,7 +852,7 @@ export function createTaskHooks(config, ctx) {
                     if (run.code === 2) {
                         // CC:exit 2 = 阻断,stderr 喂给模型
                         const reason = clip(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS) || "blocked by a PreToolUse hook";
-                        return { action: "deny", message: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+                        return { action: "deny", message: reason, ...buildHookContextField(contexts) };
                     }
                     if (run.code !== 0) {
                         ctx.logger.warn("hook_command_failed", { event: "PreToolUse", code: run.code, stderr: clip(run.stderr, 300) });
@@ -746,11 +866,11 @@ export function createTaskHooks(config, ctx) {
                     if (out.continue === false) {
                         const reason = clip(typeof out.stopReason === "string" ? out.stopReason : "hook requested stop", MAX_HOOK_FEEDBACK_CHARS);
                         // core 的 preToolUse seam 无"终止整个 run"能力(阶段一诚实近似:deny 本次调用)。
-                        return { action: "deny", message: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+                        return { action: "deny", message: reason, ...buildHookContextField(contexts) };
                     }
                     if (out.decision === "block") {
                         const reason = clip(typeof out.reason === "string" ? out.reason : "blocked by a PreToolUse hook", MAX_HOOK_FEEDBACK_CHARS);
-                        return { action: "deny", message: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+                        return { action: "deny", message: reason, ...buildHookContextField(contexts) };
                     }
                     const hso = out.hookSpecificOutput;
                     if (hso !== null && typeof hso === "object" && hso.hookEventName === "PreToolUse") {
@@ -760,7 +880,7 @@ export function createTaskHooks(config, ctx) {
                         const decision = h.permissionDecision;
                         if (decision === "deny") {
                             const reason = clip(typeof h.permissionDecisionReason === "string" ? h.permissionDecisionReason : "denied by a PreToolUse hook", MAX_HOOK_FEEDBACK_CHARS);
-                            return { action: "deny", message: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+                            return { action: "deny", message: reason, ...buildHookContextField(contexts) };
                         }
                         if (decision === "ask") {
                             asked = clip(typeof h.permissionDecisionReason === "string" ? h.permissionDecisionReason : "a PreToolUse hook requires approval", MAX_HOOK_FEEDBACK_CHARS);
@@ -771,6 +891,18 @@ export function createTaskHooks(config, ctx) {
                                 rewritten = true;
                             }
                         }
+                        else if (decision !== "deny" && decision !== "ask") {
+                            // 闭集 miss(拼错大小写的 deny / 自造词 / 非字符串 / null)。该条目的裁决**整条不采信**:
+                            // 它的 updatedInput 也不进串(上面的 if 已排除),并置位禁 allow。CC 的 `allow`/`deny`/
+                            // `ask` 三词是唯一词表;新词入表须同时进这里,否则它在本仓的语义就是"不采信"。
+                            unknownDecision = true;
+                            ctx.logger.warn("hook_permission_decision_unknown", {
+                                event: "PreToolUse",
+                                decision: clip(typeof decision === "string" ? decision : typeof decision, 200),
+                                tool: toolName,
+                                effect: "hook ruling not honored (closed word set is allow|deny|ask); this call falls back to the engine gate",
+                            });
+                        }
                     }
                 }
             }
@@ -782,14 +914,30 @@ export function createTaskHooks(config, ctx) {
                     action: "ask",
                     message: asked,
                     ...(rewritten ? { updatedInput: currentInput } : {}),
-                    ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}),
+                    ...buildHookContextField(contexts),
+                };
+            }
+            if (unknownDecision) {
+                // #157:本轮有一条**不采信**的裁决 ⇒ 一律折 `ask`(人在环)。两条都不行,各有其害:
+                //  · `allow` —— 显式放行短路,引擎门不再裁决,等于替钩子作者把 DENY 改判成放行;
+                //  · `undefined`(无裁决)—— 看着中立,其实**不是** fail-closed(codex 复审 HIGH,2026-08-07):
+                //    引擎拿到无裁决就走普通门,而 bypassPermissions / acceptEdits 档下普通门就是放行,
+                //    钩子作者写的 DENY 照样跑。词表 miss 的语义是「保护型判词坏了」而不是「钩子没表态」。
+                // 已有改写则随 `ask` 投递:改写通常正是 redact/clamp,丢了它 approve 后执行的是【原始】args
+                // —— `ask` 是唯一既 fail-closed 又能带 updatedInput 的裁决形。不采信的那条自己的改写不在其中
+                // (上面的 if 已把它挡在串外),否则一个坏判词就是一条免审的 args 改写通道。
+                return {
+                    action: "ask",
+                    message: "a PreToolUse hook returned an unrecognized permissionDecision — approval required",
+                    ...(rewritten ? { updatedInput: currentInput } : {}),
+                    ...buildHookContextField(contexts),
                 };
             }
             if (rewritten || contexts.length > 0) {
                 return {
                     action: "allow",
                     ...(rewritten ? { updatedInput: currentInput } : {}),
-                    ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}),
+                    ...buildHookContextField(contexts),
                 };
             }
             return undefined; // 无意见(≠ allow 短路;core 门照常裁决)
@@ -847,7 +995,8 @@ export function createTaskHooks(config, ctx) {
                     }
                 }
             }
-            return contexts.length > 0 ? { additionalContext: contexts.join("\n") } : undefined;
+            const additionalContext = buildHookContext(contexts);
+            return additionalContext === undefined ? undefined : { additionalContext };
         };
         hooks.postToolUse = postToolUseHook;
     }
@@ -895,7 +1044,8 @@ export function createTaskHooks(config, ctx) {
                         contexts.push(clip(h.additionalContext, MAX_HOOK_FEEDBACK_CHARS));
                 }
             }
-            return contexts.length > 0 ? { additionalContext: contexts.join("\n") } : undefined;
+            const additionalContext = buildHookContext(contexts);
+            return additionalContext === undefined ? undefined : { additionalContext };
         };
         hooks.postToolUseFailure = postToolUseFailureHook;
     }
@@ -941,7 +1091,8 @@ export function createTaskHooks(config, ctx) {
                 if (out.hookSpecificOutput !== undefined)
                     ctx.logger.warn("hook_result_unsupported", { event: "PostToolBatch" });
             }
-            return contexts.length > 0 ? { additionalContext: contexts.join("\n") } : undefined;
+            const additionalContext = buildHookContext(contexts);
+            return additionalContext === undefined ? undefined : { additionalContext };
         };
         hooks.postToolBatch = postToolBatchHook;
     }
@@ -957,7 +1108,7 @@ export function createTaskHooks(config, ctx) {
             for (const { run } of singles) {
                 if (run.code === 2) {
                     const reason = clip(run.stderr.trim(), MAX_HOOK_FEEDBACK_CHARS) || "blocked by a UserPromptSubmit hook";
-                    return { block: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+                    return { block: reason, ...buildHookContextField(contexts) };
                 }
                 if (run.code !== 0) {
                     ctx.logger.warn("hook_command_failed", { event: "UserPromptSubmit", code: run.code, stderr: clip(run.stderr, 300) });
@@ -971,11 +1122,11 @@ export function createTaskHooks(config, ctx) {
                 if (out.continue === false) {
                     // continue:false=终止整个 run;userPromptSubmit 的 block 语义正是"任务带理由收场"——同义直映射。
                     const reason = clip(typeof out.stopReason === "string" ? out.stopReason : "hook requested stop", MAX_HOOK_FEEDBACK_CHARS);
-                    return { block: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+                    return { block: reason, ...buildHookContextField(contexts) };
                 }
                 if (out.decision === "block") {
                     const reason = clip(typeof out.reason === "string" ? out.reason : "blocked by a UserPromptSubmit hook", MAX_HOOK_FEEDBACK_CHARS);
-                    return { block: reason, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+                    return { block: reason, ...buildHookContextField(contexts) };
                 }
                 const hso = out.hookSpecificOutput;
                 if (hso !== null && typeof hso === "object" && hso.hookEventName === "UserPromptSubmit") {
@@ -984,7 +1135,8 @@ export function createTaskHooks(config, ctx) {
                         contexts.push(clip(h.additionalContext, MAX_HOOK_FEEDBACK_CHARS));
                 }
             }
-            return contexts.length > 0 ? { additionalContext: contexts.join("\n") } : undefined;
+            const additionalContext = buildHookContext(contexts);
+            return additionalContext === undefined ? undefined : { additionalContext };
         };
         hooks.userPromptSubmit = userPromptSubmitHook;
     }
@@ -1148,7 +1300,7 @@ export function createTaskHooks(config, ctx) {
                 return undefined;
             return {
                 ...(block !== undefined ? { block } : {}),
-                ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}),
+                ...buildHookContextField(contexts),
             };
         };
         hooks.stop = stopHook;
@@ -1256,7 +1408,7 @@ export function composeHooks(deployment, task) {
                 if (r.additionalContext)
                     contexts.push(r.additionalContext);
                 if (r.action === "deny")
-                    return { ...r, ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+                    return { ...r, ...buildHookContextField(contexts) };
                 if (r.action === "ask")
                     asked = r;
                 if (r.action === "allow" && r.updatedInput !== undefined) {
@@ -1269,14 +1421,14 @@ export function composeHooks(deployment, task) {
                 return {
                     ...asked,
                     ...(askedUpdated === undefined && current !== input ? { updatedInput: current } : {}),
-                    ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}),
+                    ...buildHookContextField(contexts),
                 };
             }
             if (current !== input || contexts.length > 0) {
                 return {
                     action: "allow",
                     ...(current !== input ? { updatedInput: current } : {}),
-                    ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}),
+                    ...buildHookContextField(contexts),
                 };
             }
             return undefined;
@@ -1292,7 +1444,7 @@ export function composeHooks(deployment, task) {
             const updatedOutput = rt?.updatedOutput ?? rd?.updatedOutput;
             return {
                 ...(updatedOutput ? { updatedOutput } : {}),
-                ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}),
+                ...buildHookContextField(contexts),
             };
         };
     }
@@ -1301,7 +1453,8 @@ export function composeHooks(deployment, task) {
             const rd = d.postToolUseFailure ? await d.postToolUseFailure(toolName, input, failure, ctx) : undefined;
             const rt = t.postToolUseFailure ? await t.postToolUseFailure(toolName, input, failure, ctx) : undefined;
             const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            return contexts.length ? { additionalContext: contexts.join("\n") } : undefined;
+            const additionalContext = buildHookContext(contexts);
+            return additionalContext === undefined ? undefined : { additionalContext };
         };
     }
     if (d.postToolBatch || t.postToolBatch) {
@@ -1309,19 +1462,22 @@ export function composeHooks(deployment, task) {
             const rd = d.postToolBatch ? await d.postToolBatch(calls) : undefined;
             const rt = t.postToolBatch ? await t.postToolBatch(calls) : undefined;
             const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            return contexts.length ? { additionalContext: contexts.join("\n") } : undefined;
+            const additionalContext = buildHookContext(contexts);
+            return additionalContext === undefined ? undefined : { additionalContext };
         };
     }
     if (d.userPromptSubmit || t.userPromptSubmit) {
         out.userPromptSubmit = async (prompt) => {
             const rd = d.userPromptSubmit ? await d.userPromptSubmit(prompt) : undefined;
+            // 短路的是**槽序**(部署拦下就不再跑 task 槽),不是预算:`additionalContext` 与 `block` 在 core
+            // 是解耦两字段(见下方 stop 注),原样外送就是一条绕过总帽的道。
             if (rd?.block)
-                return rd;
+                return { ...rd, ...buildHookContextField(rd.additionalContext ? [rd.additionalContext] : []) };
             const rt = t.userPromptSubmit ? await t.userPromptSubmit(prompt) : undefined;
             if (!rd && !rt)
                 return undefined;
             const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            return { ...(rt?.block ? { block: rt.block } : {}), ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+            return { ...(rt?.block ? { block: rt.block } : {}), ...buildHookContextField(contexts) };
         };
     }
     if (d.stop || t.stop) {
@@ -1330,12 +1486,12 @@ export function composeHooks(deployment, task) {
         out.stop = async (sctx) => {
             const rd = d.stop ? await d.stop(sctx) : undefined;
             if (rd?.block)
-                return rd;
+                return { ...rd, ...buildHookContextField(rd.additionalContext ? [rd.additionalContext] : []) };
             const rt = t.stop ? await t.stop(sctx) : undefined;
             if (!rd && !rt)
                 return undefined;
             const contexts = [rd?.additionalContext, rt?.additionalContext].filter((c) => typeof c === "string" && c.length > 0);
-            return { ...(rt?.block ? { block: rt.block } : {}), ...(contexts.length ? { additionalContext: contexts.join("\n") } : {}) };
+            return { ...(rt?.block ? { block: rt.block } : {}), ...buildHookContextField(contexts) };
         };
     }
     if (d.preCompact || t.preCompact) {

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

@@ -0,0 +1,84 @@
+/**
+ * #154 件二+件三 —— **装配自证**域:启动期静态自检(拒启判据)与 operator 诊断读面
+ * (`GET /v1/diagnostics/wiring`)。
+ *
+ * 🔴 两件为什么同住一个模块:它们回答的是同一个问题(「这台 worker 到底接了什么线」),只是一个在 boot
+ * 用它拒绝启动、一个在运行期把它读给 operator。分成两处 = 拒启用的判据与诊断报的读数会各自演化,而
+ * 「拒启说没矛盾、诊断页显示矛盾」正是本设计要消灭的那类装配谎言。故 boot 半场是本文件导出的**纯函数**
+ * (可单测、无 I/O),路由半场只是它的读口。
+ *
+ * 分层:本模块不值 import `server.ts`(那条边会闭合运行时装载环),对它只有 `import type`。
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { WiringManifest } from "@sema-agent/core";
+import { type StreamApprovalGate, type StreamApprovalGateInput } from "../../tool-approval.js";
+import type { RouteCtx } from "../route-ctx.js";
+/** 流内审批门的读数形:上场即 `"active"`,否则是那五个合取项里**第一个**不满足的原因词
+ *  (与 `resolveStreamApprovalGate` 同一闭集,新增 reason 在此处编译红)。 */
+export type StreamApprovalGateReading = "active" | Extract<StreamApprovalGate, {
+    active: false;
+}>["reason"];
+/** server 自己的装配谓词读数(core 的静态半场之外的那一半:本仓在这台 worker 上做出的判断)。 */
+export interface ServerWiringGates {
+    streamApproval: StreamApprovalGateReading;
+    durableApproval: boolean;
+    checkpointStore: boolean;
+}
+/** `buildServerWiringGates` 的入参 = 三个谓词各自的**真输入**(不接受已算好的布尔:那样这里读到的就
+ *  不再是装配现场的事实,而是别处算完可能已漂的复述)。 */
+export interface ServerWiringGateInput {
+    toolApprovalEnabled: boolean;
+    streamApprovalEnabled: boolean;
+    /** 谓词自己的入参类型(结构形,不 import store 依赖树)—— 取型而非重述,两处不可能漂。 */
+    backend: StreamApprovalGateInput["backend"];
+    /** 在场性即事实;本面不取实例,故 `unknown` 足够(取窄型会把整棵 store 类型树拖进诊断域)。 */
+    checkpointStore: unknown;
+    durableApproval: boolean;
+}
+/** 纯数据产物(`build*`):三个门的当前读数。`streamApproval` 走**单一谓词**
+ *  `resolveStreamApprovalGate` —— 与 `/v1/capabilities` 的 `streamApproval` 位、与回决口的 501 门同一个
+ *  符号,所以诊断页读到的与消费端撞到的行为不可能不同。 */
+export declare function buildServerWiringGates(input: ServerWiringGateInput): ServerWiringGates;
+/** 启动自检的判决:`refusals` 非空 ⇒ 拒启(装配谎言);`warnings` ⇒ 留痕但放行。 */
+export interface StaticWiringAudit {
+    refusals: readonly string[];
+    warnings: readonly string[];
+}
+/** 自检输入 = core 的静态半场 + 我方装配现场的两件事实。 */
+export interface StaticWiringFacts {
+    /** core `describeStaticWiring(deps, specTemplate)` 的产物。 */
+    manifest: WiringManifest;
+    /** 我方喂给 `resolveStreamApprovalGate` 的 `parkFacility` 实参(= checkpoint 店在场 ∧ DURABLE_APPROVAL)。 */
+    parkFacility: boolean;
+    /** store backend 的种类;`undefined` = env-only worker(无 backend)。 */
+    backendKind: "mysql" | "pg" | "local" | undefined;
+}
+/**
+ * 三项对表(设计稿件二)。判据全是**两个独立谓词对同一件事的答案**,矛盾即装配谎言 —— 装配谎言不是
+ * 「配置不理想」,是「服务端对自己接了什么线的两套说法互斥」,继续启动只会把矛盾带进运行期的每一条腿。
+ *
+ *  ① park 设施:core 从 `spec.checkpointStore ?? deps.checkpointStore` 判 `parkLane.capable`,我方从
+ *     `backend.checkpoint ∧ DURABLE_APPROVAL` 判 `parkFacility` 并据此决定流内审批协议上不上场。两者
+ *     不等 ⇒ 协议按「窗到期能 park」上场而引擎侧根本不 park(结局是 core fail-closed deny),或反之
+ *     白白关掉一个可用的协议。`capable` 真而 `effective` 不真同样致命:能力在、这条部署形上却不会真的
+ *     park,窗到期依旧无降级目的地。
+ *  ② 会话店持久性:manifest 声明 `declared_durable` 而后端是 local / 根本没有后端 ⇒ 「重启存活」的声明
+ *     没有介质兑现。这条与 memory+durable 两条既有拒启同族(声明与介质必须对得上)。
+ *  ③ interaction posture 声明 `interactive` 却没有任何 question 投递面 ⇒ 只 **warn**:core 在 prepare 时
+ *     会按腿拒,boot 先一步把话说成人话。不拒启,因为部署形本身可能只是暂时没接活体面,而 core 侧已有
+ *     兜底门 —— 拒启会把一个可运行的部署挡在门外。
+ *  ④ park 车道的持久性读数不可信时 ⇒ **warn**(理由与这条判据为什么不是拒启,见其行内注)。
+ *
+ * 判决分两级是有判据的:**拒启**留给「两个谓词对同一件事互斥」(其中一个必错,继续跑就是带着谎言服务);
+ * **警告**留给「读数不可信/声明不完整」(信号本身还不足以断定谁错,据此拒启会挡住正常部署)。
+ */
+export declare function buildStaticWiringAudit(facts: StaticWiringFacts): StaticWiringAudit;
+/**
+ * boot 消费口:`refusals` 非空即抛(拒启,与 memory+durable 两条既有拒启同族的 fail-loud 形),
+ * `warnings` 逐条 warn。返回判决本体,调用方可以继续把读数打进启动 info 行。
+ */
+export declare function assertStaticWiringConsistent(facts: StaticWiringFacts, logger: {
+    warn: (msg: string, meta?: Record<string, unknown>) => void;
+} | undefined): StaticWiringAudit;
+export declare function handleDiagnostics(req: IncomingMessage, res: ServerResponse, url: string, ctx: RouteCtx): Promise<boolean>;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/http/routes/diagnostics.js

@@ -0,0 +1,145 @@
+import { resolveStreamApprovalGate } from "../../tool-approval.js";
+import { sendJson, sendError } from "../send.js";
+import { gatedPrincipal, explicitOperatorOk } from "../principal-gate.js";
+/** 纯数据产物(`build*`):三个门的当前读数。`streamApproval` 走**单一谓词**
+ *  `resolveStreamApprovalGate` —— 与 `/v1/capabilities` 的 `streamApproval` 位、与回决口的 501 门同一个
+ *  符号,所以诊断页读到的与消费端撞到的行为不可能不同。 */
+export function buildServerWiringGates(input) {
+    const gate = resolveStreamApprovalGate({
+        toolApprovalEnabled: input.toolApprovalEnabled,
+        streamApprovalEnabled: input.streamApprovalEnabled,
+        backend: input.backend,
+        parkFacility: input.checkpointStore !== undefined,
+    });
+    return {
+        streamApproval: gate.active ? "active" : gate.reason,
+        durableApproval: input.durableApproval,
+        checkpointStore: input.checkpointStore !== undefined,
+    };
+}
+/**
+ * 三项对表(设计稿件二)。判据全是**两个独立谓词对同一件事的答案**,矛盾即装配谎言 —— 装配谎言不是
+ * 「配置不理想」,是「服务端对自己接了什么线的两套说法互斥」,继续启动只会把矛盾带进运行期的每一条腿。
+ *
+ *  ① park 设施:core 从 `spec.checkpointStore ?? deps.checkpointStore` 判 `parkLane.capable`,我方从
+ *     `backend.checkpoint ∧ DURABLE_APPROVAL` 判 `parkFacility` 并据此决定流内审批协议上不上场。两者
+ *     不等 ⇒ 协议按「窗到期能 park」上场而引擎侧根本不 park(结局是 core fail-closed deny),或反之
+ *     白白关掉一个可用的协议。`capable` 真而 `effective` 不真同样致命:能力在、这条部署形上却不会真的
+ *     park,窗到期依旧无降级目的地。
+ *  ② 会话店持久性:manifest 声明 `declared_durable` 而后端是 local / 根本没有后端 ⇒ 「重启存活」的声明
+ *     没有介质兑现。这条与 memory+durable 两条既有拒启同族(声明与介质必须对得上)。
+ *  ③ interaction posture 声明 `interactive` 却没有任何 question 投递面 ⇒ 只 **warn**:core 在 prepare 时
+ *     会按腿拒,boot 先一步把话说成人话。不拒启,因为部署形本身可能只是暂时没接活体面,而 core 侧已有
+ *     兜底门 —— 拒启会把一个可运行的部署挡在门外。
+ *  ④ park 车道的持久性读数不可信时 ⇒ **warn**(理由与这条判据为什么不是拒启,见其行内注)。
+ *
+ * 判决分两级是有判据的:**拒启**留给「两个谓词对同一件事互斥」(其中一个必错,继续跑就是带着谎言服务);
+ * **警告**留给「读数不可信/声明不完整」(信号本身还不足以断定谁错,据此拒启会挡住正常部署)。
+ */
+export function buildStaticWiringAudit(facts) {
+    const refusals = [];
+    const warnings = [];
+    const park = facts.manifest.parkLane;
+    if (park.capable !== facts.parkFacility) {
+        refusals.push(`park facility contradiction: the engine's static wiring says parkLane.capable=${park.capable} while this server assembled its approval gates with parkFacility=${facts.parkFacility}. ` +
+            `One of the two is wrong about the same checkpoint store — refusing to start rather than serving a worker whose approval lane can silently fail closed. ` +
+            `Check DURABLE_APPROVAL and the backend's checkpoint face (they are what both predicates read).`);
+    }
+    else if (facts.parkFacility && park.effective !== true) {
+        refusals.push(`park facility contradiction: this server assembled its approval gates with parkFacility=true, but the engine's static wiring resolves parkLane.effective=${JSON.stringify(park.effective)} (reasons: ${park.reasons.join(", ") || "none"}). ` +
+            `A window expiry would then have no degradation target and adjudicate as a fail-closed deny — refusing to start.`);
+    }
+    // 判据写成「不在持久集合里」而不是「是 local」是有方向的:将来多一种 backend kind 时,它会**拒启**
+    // 直到有人显式把它判进持久集,而不是静默通过 —— 声明与介质的对表,失败方向必须朝拒绝那边。
+    if (facts.manifest.session.store === "declared_durable" && facts.backendKind !== "mysql" && facts.backendKind !== "pg") {
+        refusals.push(`session store durability contradiction: the engine's static wiring reports session.store="declared_durable" while the store backend is ${facts.backendKind === undefined ? "absent (env-only worker)" : `"${facts.backendKind}"`}. ` +
+            `A durable declaration with no durable medium is a claim nothing can honor — refusing to start. Wire DB_BACKEND=mysql|pg, or fix the store's durability declaration.`);
+    }
+    // park 车道的**持久性读数**(codex 交叉复审 2026-08-07 R2-F2,验真后部分采纳)。`capable` 说的是
+    // 「有没有 checkpoint 店」、`effective` 说的是「这条部署形会不会真 park」—— 两者都为真时仍可能是一个
+    // 重启即丢的店,那样窗到期后被 park 的审批在重启后无法赎回,而流内审批协议正是拿 park 当降级目的地。
+    // ✅ **读数已转可信**(#168 件5,2026-08-07):树上三条 checkpoint 店(SQL 双生 + local 文件形)现在都
+    // 如实声明了 `durability`,所以这条读数不再对真持久部署恒假 —— 它现在说的就是字面意思。
+    //
+    // 🔴 仍然是 **warn 而不是拒启**,判据与 session 那条**刻意不同**,理由写在这里免得下一个人以为是漏改:
+    // session 那条对表的是「声明 durable × 介质不 durable」——两个已知量互相矛盾,拒启是查出了谎。这一条
+    // 对表的是「有没有人声明」,而 core 把**缺席**折成 `process-local`;一个合法的第三方/新增 checkpoint
+    // 店没表态时,拒启会挡住一个本来跑得好好的部署,而**没有任何旋钮**能让它继续启动(补偿为零 ⇒ 不升格)。
+    // 升格的前置件 = core 把「未声明」与「声明为进程内」分成两个可区分读数,或本仓给出一个显式承认旋钮。
+    if (facts.parkFacility && facts.manifest.parkLane.checkpointDurability !== "declared_durable") {
+        warnings.push(`park facility is enabled but the checkpoint store does not declare durable storage ` +
+            `(parkLane.checkpointDurability=${JSON.stringify(facts.manifest.parkLane.checkpointDurability ?? null)}). ` +
+            `A parked approval survives a restart only on a durable store, and this reading folds "declared process-local" together with "declared nothing" — every in-tree adapter declares "durable", so a non-durable reading here means a store this build does not own. ` +
+            `Treat park-lane recovery as unproven until that adapter declares its durability.`);
+    }
+    if (facts.manifest.interaction.posture === "interactive" && facts.manifest.question.wired !== "wired") {
+        warnings.push(`interactionPosture declares "interactive" but no question delivery face is wired (question.wired=${JSON.stringify(facts.manifest.question.wired)}) — ` +
+            `every leg that asks a question will be refused by the engine at prepare time. Wire the live question seam (ASK_QUESTION_ENABLED), or declare the headless posture.`);
+    }
+    return { refusals, warnings };
+}
+/**
+ * boot 消费口:`refusals` 非空即抛(拒启,与 memory+durable 两条既有拒启同族的 fail-loud 形),
+ * `warnings` 逐条 warn。返回判决本体,调用方可以继续把读数打进启动 info 行。
+ */
+export function assertStaticWiringConsistent(facts, logger) {
+    const audit = buildStaticWiringAudit(facts);
+    for (const w of audit.warnings)
+        logger?.warn("wiring_static_warning", { detail: w });
+    if (audit.refusals.length > 0) {
+        throw new Error(`static wiring self-check failed — refusing to start:\n${audit.refusals.map((r) => `  · ${r}`).join("\n")}`);
+    }
+    return audit;
+}
+export async function handleDiagnostics(req, res, url, ctx) {
+    const miss = { fell: false };
+    await handleDiagnosticsBody(req, res, url, ctx, miss);
+    return !miss.fell;
+}
+async function handleDiagnosticsBody(req, res, url, ctx, miss) {
+    const { deps } = ctx;
+    // 件三:「这台 worker 到底接了什么线」一屏看清 = core 的静态半场(含 `governance` 段 —— 本面**就是**
+    // 那个段的 operator 受众)+ server 自己三个装配谓词的读数。
+    //
+    // 门 = `explicitOperatorOk`(**不是** `isOperator`)。执法条件是**名单在场 ∨ 多租户**,不是只看
+    // `REQUIRE_PRINCIPAL`:本件的 SSE 腿对同一段 governance 恒判 `explicitOperatorOk`,若这里只在
+    // REQUIRE_PRINCIPAL 时判,「列了 operator 名单却没开 REQUIRE_PRINCIPAL」的部署上就成了流里关着、
+    // 端点上开着 —— 一个秘密两套门,严的那道白严(codex 交叉复审 2026-08-07 R2-F1,验真后采纳)。
+    // 名单为空 ∧ 非多租户 = 单租户 turnkey:该部署没有 operator 这个概念,唯一的用户就是 operator,
+    // 边界由全局 service-credential 门把守(与 `GET /v1/outcomes` 同裁)。
+    // 401 由更上游的全局门给出,本域只判 operator 与否。
+    //
+    // ⚠️ 与 SSE 腿的**残余不对称**(显式裁定,不是疏忽):turnkey 形上流里仍然谁都拿不到治理段,而本端点
+    // 给。理由=流是多订阅面且身份来自连接、端点是一次显式的 operator 请求;失败方向因此在流那侧更严。
+    //
+    // **不含** per-leg effective 历史:治理段只存在于 live 帧的 operator 投影里,durable 账本恒存剥后形
+    // (账本写时不知道未来读者是谁)。历史考古是另一件事,不在本面伪装成有。
+    if (req.method === "GET" && url === "/v1/diagnostics/wiring") {
+        if (deps.config.operatorPrincipals.length > 0 || deps.config.requirePrincipal) {
+            const principal = gatedPrincipal(req, deps.config);
+            if (!explicitOperatorOk(principal, deps.config.operatorPrincipals)) {
+                sendError(res, 403, "auth.operator_only", "wiring diagnostics are operator-only on a multi-tenant worker");
+                return;
+            }
+        }
+        // 静态半场是 **composition root 在 boot 算的**(与拒启自检同一份产物,不可能与它不同)。缺席 ⇒ 这个
+        // 进程不是由 main.ts 装起来的(测试夹具形),此面诚实地不存在 —— 落到全局 404,而不是回一个空壳 200。
+        if (!deps.staticWiring) {
+            miss.fell = true;
+            return;
+        }
+        sendJson(res, 200, {
+            static: deps.staticWiring,
+            serverGates: buildServerWiringGates({
+                toolApprovalEnabled: deps.toolApproval !== undefined,
+                streamApprovalEnabled: deps.config.streamApproval?.enabled === true,
+                backend: deps.backend,
+                checkpointStore: deps.checkpointStore,
+                durableApproval: deps.config.durableApproval === true,
+            }),
+        });
+        return;
+    }
+    miss.fell = true;
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/http/routes/memory-policy.d.ts

@@ -2,7 +2,8 @@
  * design/158 A9 域模块 —— memory 导出/同步 + 只读策略面。
  *
  * 路由:`GET /v1/memory/export`、`POST /v1/memory/sync/:scope`、`GET /v1/policy`。
- * owner 门 = 「本人 user scope 或显式 operator」,越界一律 404(零存在性 oracle)。本域零可变状态。
+ * owner 门 = 「本人 user scope / 显式 operator / `org:` 键的目录成员」(见 {@link gateMemoryScope}),
+ * 越界一律 404(零存在性 oracle)。本域零可变状态。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx } from "../route-ctx.js";