@sema-agent/server 7.125.1 → 7.126.0

package/dist/hooks/hook-runner.d.ts

@@ -43,16 +43,17 @@ export interface ParseHooksConfigResult {
  * ⇒ **永不命中、一句话都没有**(post 两事件自 7.107.0 / core 7.36.0 起如此,PreToolUse 一直如此)。静默不命中 = 写的人以为在生效的 hook
  * 其实没跑,硬破坏三句要求的「响亮」没有着落。7.112.0(S-924)只拒**字面**别名;同一个错误写成 `^ListPeers$` / `ListPeers.*` / `(ListPeers)` 照样 200(S-995)。
  *
- * 规则(一条;字面形是它的特例):{@link deadToolMatcherIssue} 对 core 静态目录里**每一条退役别名**问「这只 matcher 选不选它 / 选不选它的正名」:
+ * 规则(一条;字面形是它的特例):{@link toolMatcherIssue} 对 core 静态目录里**每一条退役别名**问「这只 matcher 选不选它 / 选不选它的正名」:
  * matcher **命中别名 ∧ 不命中它的正名** ⇒ `400 request.field_invalid`(`admission.ts` fresh 门)。「选不选」**只有一只读法**:契约包的 `hookMatcherSelects`
  * (名字表 / 空 / `*` / 正则三形都由它答;正则形**不锚定**,与壳同形;运行期 {@link hookMatcherMatches} 问的也是它,本仓不留副本)。按**一条顺序**判(两档共用,7.114.0 修复轮):
  *  ① **长度上限**:超 {@link MAX_MATCHER_EVAL_CHARS} 的 matcher 两档都不读 ⇒ 未判(reason = oversize);
  *  ② **形只问契约包的 `hookMatcherForm`**(与 `hookMatcherSelects` 同一只解析步,本仓不留形判),闭集三词、两档一张表:
  *     · `literal`(缺席 / 空 / `*` / 名字表形;契约不编、不跑调用方的正则)⇒ 两档都**直接问契约函数**、**不占求值预算**;
- *     · `regex` ⇒ **`"regex"` 档**(hooks 会被采纳的车道,`taskHooksHonored`)把**同一只契约函数**经 `node:vm` 的 `timeout` 带一次受理共享的预算调用({@link matcherSelectsWithin});
+ *     · `regex` ⇒ **`"regex"` 档**(hooks 会被采纳的车道,`taskHooksHonored`)把**同一只契约函数**经 `node:vm` 的 `timeout` 带**每次求值各一份固定预算**调用({@link matcherSelectsWithin};
+ *       预算**不共享**、不随同一受理里别的 matcher 耗尽、不读钟 —— S-1455);**超时 ⇒ 这只 matcher 是灾难回溯 ⇒ `400 request.field_invalid` 拒**(见下「预算与结局」);
  *       **`"literal"` 档**(多租户车道:hooks 整只被 resolveSpec 忽略)= **不适用**:该车道没有被守的对象(hooks 不装配),不判、不算未判、不登记 —— **零调用方正则执行**
  *       (7.112.0 的字面判保留:裸 `ListPeers` / `Read|ListPeers` 照旧 400);
- *     · `invalid`(编不过)⇒ `"regex"` 档 = 未判 `invalid_regex`(不进预算求值 —— 形判已答「读不了」);`"literal"` 档 = 不适用(同上)。
+ *     · `invalid`(编不过)⇒ `"regex"` 档 = **`400 request.field_invalid` 拒**(判决 `invalid_regex`,见下「预算与结局」;不进求值 —— 形判已答「读不了」);`"literal"` 档 = 不适用(同上)。
  *    形判在 `literal` 档也跑:契约的解析步对非名字表形**构造**(只解析、不执行)一次调用方的 pattern 以分出 regex / invalid —— 长度已被 ① 界住;执行恒为零。
  *  · **为什么两档**(codex r1 [high] + 主会话裁):受理面是**所有**车道,而运行期只有单用户车道跑 hooks。在受理线程上跑调用方的正则 = 给多租户加一个事件循环 DoS 面
  *    (实测:`(.*)*` ×10 + `X` 对 9 字符名字首次执行 1.7 s,18 字符嵌套形 15 s,24 字符 157 s;8 MiB 交替串编译 + 求值 9 s)—— 预算只界住一次请求、界不住「每个请求再拿一份」。
@@ -73,63 +74,116 @@ export interface ParseHooksConfigResult {
  *  · **不在本规则内**:两边都选不中的 matcher(大小写错 / 词内空白 / 纯错字;目录之外的 MCP / 嵌入方工具名同样「选不中目录里任何名」,受理面无从区分错字与它们)=
  *    **「选不到目录里任何名」另一类,候设计(台账另立号,主会话裁)**。
  *
+ * 🔴 **预算与结局(S-1455;受理结局只取决于配置,不取决于机器忙闲)**:regex 档每一次求值(一只正则形 matcher 对一个名字的一次问)各拿**一份固定的墙钟预算**
+ * {@link ADMISSION_MATCHER_EVAL_BUDGET_MS}(vm `timeout`,从这次求值开始计)—— **不共享**(此前一次受理共用 100 ms,忙机上会被吃光 ⇒
+ * 同一份设置忙机偶尔被收下、闲机恒 400),不随同一受理里 matcher 的个数耗尽,判据里**没有时钟**(没有「截止线」可被调度停顿越过)。预算只防**灾难回溯**:
+ * 良性求值 ~0.1 ms,灾难形(指数级)吃满预算也跑不完 —— 两者相差数个数量级,取值给足余量(1 000 ms),让忙机上的调度停顿也跨不过这条线。
+ * **超时 ⇒ 确定拒绝**:`400 request.field_invalid`({@link OverBudgetMatcherIssue}),句子点名**哪一只 matcher**(事件 + 组下标,不回显原字节)与**预算**;**按配置顺序遇到的第一只超时 / 命中别名的 matcher 定结局**。
+ * 为什么是拒绝而不是放行:运行期 {@link hookMatcherMatches} 在**每次工具调用**里直接问同一只契约函数、**没有任何预算** —— 一只在受理面都跑不完的 matcher 放进去,
+ * 每次调用都会把事件循环卡住;放行 = 把一个确定的坏配置推迟成运行期的随机卡死。这条拒不是「越界即拒」的新检测面:被拒的恰是**无法被求值**的 matcher,与 `hook_matcher_invalid`(编不过 ⇒ 该组不跑)同属「这只 matcher 不可用」,
+ * 只是编不过的运行期自己安全地不跑它,跑不完的不行。
+ * 总用时的上界:首个超时即拒、不再往下求值;未超时的求值各自 < 预算。regex 档只在单用户车道(`taskHooksHonored`,hooks 会装配的那条;调用方就是进程属主,本来就能配任意 `command` 钩子)运行,
+ * 多租户车道走 literal 档、零调用方正则执行 —— 受理面的 DoS 面不因此重开。
+ *
+ * 🔴 **编不过的正则 = 确定的拒绝**(S-1455 收尾;与超预算同类 —— 确定性的坏配置,结局只取决于配置):`"regex"` 档遇契约 `hookMatcherForm` 答 `invalid`(或求值时契约函数答 `"invalid"`)⇒
+ * `400 request.field_invalid`({@link InvalidRegexMatcherIssue}),句子点名**哪一只 matcher**(事件 + 组下标 + 原文〔超 {@link MATCHER_ECHO_CHARS} 字符截断〕)与引擎的编译错误句;机读位 `detail` 只有闭集三键。
+ * 受理面与运行期问**同一只判**:契约把"编不过"答成 `invalid`,运行期 {@link hookMatcherMatches} 因此不跑那一组(并记 `hook_matcher_invalid`),受理面因此拒 —— 本仓不加第二个判官
+ * (编译错误句只是诊断文字,见 {@link matcherCompileSentence};拒不拒由契约函数一个人说了算)。为什么是拒绝而不是放行:放行 = 用户以为在生效的钩子(含会真拦的 PreToolUse deny 钩子)
+ * 在每次工具调用里都**悄悄不跑**,硬破坏三句要求的「响亮」没有着落;`"literal"` 档(多租户车道,hooks 不装配)= 不适用,与正则形同一行表。resume 重放不判(照旧采纳、该组不跑)。
+ * 🔴 **边界(如实披露)**:判据只守三个工具事件(`matcherReadsWireToolName`)—— 写在别的带 matcher 的事件(`StopFailure` 的 `error` 词 / `PreCompact`·`PostCompact` 的 `trigger` 词)上的坏 matcher 仍受理、运行期该组不跑并记 `hook_matcher_invalid`。
+ *
  * 🔴 **「未判」臂过 `recordFailOpen`**(F 类 tag `MATCHER_UNJUDGED_TAG`;主会话裁,CLAUDE.md「合法 F 类回退走登记 tag」):一只 matcher 没能被判 ⇒ 照旧受理 + 登记一笔,
- * detail = `event=… reason=… matcherChars=…`(**不带 matcher 原字节**,S-716 姿势)。三种 reason 同一个 tag:
- *   `oversize` —— 两档:matcher 超 {@link MAX_MATCHER_EVAL_CHARS} 字符不读(多租户车道上 hooks 不装配,这一笔只为让超长输入显形);
- *   `over_budget` ——「regex」档正则形:一次受理共享一份 {@link ADMISSION_MATCHER_EVAL_BUDGET_MS} 墙钟预算,用尽 ⇒ 这一只与其后各只正则形未判(`vm` 的 `timeout` 打断回溯,含 tier-up 之后的原生码);
- *   `invalid_regex` ——「regex」档正则形编不过(运行期另有每次调用的 `hook_matcher_invalid`;这是确定性的坏配置,不是负载 —— 拒它是新检测臂,不在本规则)。
- * 放行最坏后果 = 那一只 matcher 没被这条判据守住、照旧永不命中,**不是安全闸**(受理面有效性判);反方向「越界即拒」会把负载抖动 / 病态但合法的 matcher 变成对合法请求的 400。
+ * detail = `event=… reason=… matcherChars=…`(**不带 matcher 原字节**,S-716 姿势)。现在只剩一种 reason:
+ *   `oversize` —— 两档:matcher 超 {@link MAX_MATCHER_EVAL_CHARS} 字符不读(多租户车道上 hooks 不装配,这一笔只为让超长输入显形)。
+ * (`over_budget` 臂自 S-1455 起退役:它是「预算用尽 ⇒ 照旧受理」的随负载翻转的结局,现在是上面的确定拒绝;`invalid_regex` 臂自 S-1455 收尾起退役,同理。)
+ * 放行最坏后果 = 那一只 matcher 没被这条判据守住、照旧永不命中,**不是安全闸**(受理面有效性判)。
  * 拒放集合相对 7.113.0 的一处放宽(披露在 CHANGELOG / MIGRATION):超过上限的字面别名 matcher 7.113.0 拒(当时字面判不设上限),自 7.114.0 两档都判未判、受理。
  *
- * 错误句只回显**目录里的**别名与正名(闭集字符串),不回显调用方的原字节(S-716 姿势)。
+ * 错误句:死别名与超预算两形只回显**目录里的**别名与正名 / 位置(闭集字符串与数字),不回显调用方的原字节(S-716 姿势);编不过一形**点名那只 matcher 的原文**(截断到 {@link MATCHER_ECHO_CHARS} 字符)与引擎的编译错误句 ——
+ * 调用方要改的就是这一串,且它本来就是调用方自己送来的;机读位 `detail` 仍不带这两段。
  *
- * 🔴 **判决是数据,句子与体的机读位同出一只铸点**(S-1025;client-core 请托,additive):{@link deadToolMatcherIssue} 回 {@link DeadToolMatcherIssue}(event / alias / canonical)
- * 而不是句子;{@link buildDeadToolMatcherRefusal} 是**唯一**把它铸成拒句 + `field` + `detail` 的函数,受理门只取它的返回、**不解析句子**。体上多出的两键让三端不必解析英文就能把这只拒
- * 与普通提交失败分流、提示用户改 matcher;句子逐字同 7.114.0、零新码。
+ * 🔴 **判决是数据,句子与体的机读位同出一只铸点**(S-1025;client-core 请托,additive):{@link toolMatcherIssue} 回 {@link ToolMatcherIssue}(闭集三形:{@link DeadToolMatcherIssue} 的 event / alias / canonical,
+ * {@link OverBudgetMatcherIssue} 的 event / groupIndex / budgetMs,{@link InvalidRegexMatcherIssue} 的 event / groupIndex〔+ 句子用的 matcher / compileError〕,以 `reason` 区分)而不是句子;{@link buildToolMatcherRefusal} 是**唯一**把它铸成拒句 + `field` + `detail` 的函数,
+ * 受理门只取它的返回、**不解析句子**。体上多出的两键让三端不必解析英文就能把这只拒与普通提交失败分流、提示用户改 matcher;死别名那一句逐字同 7.114.0、零新码。
  */
 /** 超此长度的 matcher 不在受理面读(两档同一个上限;未判,reason = oversize)。与 {@link MAX_HOOK_COMMAND_CHARS} 同量纲的服务侧防线:真实 matcher(精确名 / 交替 / `mcp__.*`)远在其内;目录全部工具名交替 ~0.5 KiB。 */
 export declare const MAX_MATCHER_EVAL_CHARS = 8192;
-/** 一次 fresh 受理里 regex 档**正则形**求值共享的墙钟预算(毫秒)。字面形不占它。良性求值 ~0.1 ms;灾难回溯的 matcher 把预算吃完就停,后面的正则形组直接「未判」。 */
-export declare const ADMISSION_MATCHER_EVAL_BUDGET_MS = 100;
+/**
+ * regex 档**每一次正则形求值各一份**的墙钟预算(毫秒;S-1455)。**不共享、不随受理里 matcher 的个数耗尽、判据里不读钟**;字面形不占它。
+ * 良性求值 ~0.1 ms;灾难回溯(指数级)吃满它也跑不完 ⇒ 这只 matcher 被 400 拒。取值是「良性求值之上数个数量级」的余量 —— 小了,忙机上的调度停顿会把良性 matcher 读成灾难(受理结局随负载翻转,正是 S-1455 要根除的形)。
+ */
+export declare const ADMISSION_MATCHER_EVAL_BUDGET_MS = 1000;
+/** 拒句里回显的 matcher 原文 / 引擎编译错误句各自的字符上限(截断记号 `…(总长)` 由 `clip` 铸;S-1455 收尾)。真实 matcher 远在其内;上限只防一只 8 KiB 的坏 matcher 把拒句撑成一屏。 */
+export declare const MATCHER_ECHO_CHARS = 200;
 /** 受理面判据的求值深度(见上头注):`"regex"` = 契约字面形直接问、正则形带预算问同一只契约函数;`"literal"` = 7.112.0 的字面判(只判契约字面形,零调用方正则执行;正则形 / 编不过的形不适用)。 */
 export type MatcherEvalDepth = "regex" | "literal";
 /**
- * **仅供测试注入**的求值预算(生产调用点不传 ⇒ 预算 = {@link ADMISSION_MATCHER_EVAL_BUDGET_MS}、时钟 = `performance.now`)。
- * 让「预算是一次受理共享的」「耗尽之后的组」这类格子按求值次序断言,不按机器速度断言(`test/hooks-alias-matcher-s995.test.ts` R4)。
+ * **仅供测试注入**的求值预算(生产调用点不传 ⇒ 每次求值的预算 = {@link ADMISSION_MATCHER_EVAL_BUDGET_MS})。让「灾难形被拒」这类格子能用小额度(毫秒级)跑,不必等满生产预算。
+ * 只有预算额度、**没有时钟**:判据本身不读钟(S-1455),测试也就没有「在第几次读钟时预算已尽」可造 —— 求值次序、调度停顿都不改变结局。
  */
 export interface MatcherEvalBudget {
     readonly budgetMs?: number;
-    readonly now?: () => number;
 }
-/** 一条受理面判决(纯数据):`event` 事件下的某只 matcher 选中了退役别名 `alias`、却选不中它的正名 `canonical`。`alias` / `canonical` 恒取自 core 静态目录(闭集字符串,不含调用方原字节)。 */
+/** 一条受理面判决(纯数据)· 死别名:`event` 事件下的某只 matcher 选中了退役别名 `alias`、却选不中它的正名 `canonical`。`alias` / `canonical` 恒取自 core 静态目录(闭集字符串,不含调用方原字节)。 */
 export interface DeadToolMatcherIssue {
+    readonly reason: "dead_alias";
     readonly event: HookEventName;
     readonly alias: string;
     readonly canonical: string;
 }
-/** {@link buildDeadToolMatcherRefusal} 的返回(纯数据):拒句 + 400 体上的两个机读位。`field` 恒为字面 `"settings.hooks"`;`detail` 与 {@link DeadToolMatcherIssue} 同三键(逐个挑出,不 spread)。 */
-export interface DeadToolMatcherRefusal {
+/** 一条受理面判决(纯数据)· 求值超预算(S-1455):`event` 事件下第 `groupIndex` 组(从 0 起)的 matcher 单次求值没在 `budgetMs` 内结束(灾难回溯)。三键都是闭集 / 数字,不含调用方原字节。 */
+export interface OverBudgetMatcherIssue {
+    readonly reason: "over_budget";
+    readonly event: HookEventName;
+    readonly groupIndex: number;
+    readonly budgetMs: number;
+}
+/**
+ * 一条受理面判决(纯数据)· 正则编不过(S-1455 收尾):`event` 事件下第 `groupIndex` 组(从 0 起)的 matcher 在契约包的读法下答 `invalid`。
+ * `matcher` = 那只 matcher 的原文、`compileError` = 引擎的编译错误句(各自截到 {@link MATCHER_ECHO_CHARS} 字符):**只供铸拒句用**,机读位 `detail` 不带它们。
+ */
+export interface InvalidRegexMatcherIssue {
+    readonly reason: "invalid_regex";
+    readonly event: HookEventName;
+    readonly groupIndex: number;
+    readonly matcher: string;
+    readonly compileError: string;
+}
+/** 受理面判据的判决(闭集三形,`reason` 区分;每一形都是 400 拒):死别名 · 求值超预算 · 正则编不过。 */
+export type ToolMatcherIssue = DeadToolMatcherIssue | OverBudgetMatcherIssue | InvalidRegexMatcherIssue;
+/** {@link buildToolMatcherRefusal} 的返回(纯数据):拒句 + 400 体上的两个机读位。`field` 恒为字面 `"settings.hooks"`;`detail` 与 {@link ToolMatcherIssue} 同键(按 `reason` 分形,逐个挑出,不 spread)。 */
+export interface ToolMatcherRefusal {
     readonly message: string;
     readonly field: "settings.hooks";
     readonly detail: {
+        readonly reason: "dead_alias";
         readonly event: HookEventName;
         readonly alias: string;
         readonly canonical: string;
+    } | {
+        readonly reason: "over_budget";
+        readonly event: HookEventName;
+        readonly groupIndex: number;
+        readonly budgetMs: number;
+    } | {
+        readonly reason: "invalid_regex";
+        readonly event: HookEventName;
+        readonly groupIndex: number;
     };
 }
 /**
- * 判决 → 拒句 + 机读位。**拒句的唯一铸点**:句子逐字 = 7.114.0 的那一句(`test/hooks-alias-matcher-s995.test.ts` R7 冻结);受理门 `admission.ts` 用返回值填 400 体,
- * 不从句子里反解字段。
+ * 判决 → 拒句 + 机读位。**拒句的唯一铸点**:死别名的句子逐字 = 7.114.0 的那一句(`test/hooks-alias-matcher-s995.test.ts` R7 冻结);受理门 `admission.ts` 用返回值填 400 体,
+ * 不从句子里反解字段。超预算的句子点名**哪一只**(事件 + 组下标 + `matcher`)与**预算**,不回显 matcher 原字节(S-716 姿势);`reason` 闭集穷举(多一形 = 这里编译红)。
  */
-export declare function buildDeadToolMatcherRefusal(issue: DeadToolMatcherIssue): DeadToolMatcherRefusal;
+export declare function buildToolMatcherRefusal(issue: ToolMatcherIssue): ToolMatcherRefusal;
 /**
- * fresh 提交面专用判据(S-924 / S-995):配置里第一条「永远打不中」的工具事件 matcher 的判决数据({@link DeadToolMatcherIssue});没有 ⇒ undefined。
- * 拒句与 400 体的机读位由 {@link buildDeadToolMatcherRefusal} 从这份数据铸(S-1025)。
+ * fresh 提交面专用判据(S-924 / S-995 / S-1455):配置里第一条「该拒」的工具事件 matcher 的判决数据({@link ToolMatcherIssue}):「永远打不中」(死别名)或「求值超预算」(灾难回溯);没有 ⇒ undefined。
+ * 拒句与 400 体的机读位由 {@link buildToolMatcherRefusal} 从这份数据铸(S-1025)。**按配置顺序(事件 → 组)遇到的第一条定结局**;结局只取决于配置,不取决于求值次序之外的任何东西(无共享预算、无时钟)。
  * 入参是 {@link parseHooksConfig} 已校验过的配置;`depth` 由调用点按车道定(见头注:`taskHooksHonored(config) ? "regex" : "literal"`)。
  * `budget` **仅供测试注入**({@link MatcherEvalBudget});生产调用点只传前两个实参。
- * **只有 `admission.ts` 的 fresh 提交门调它** —— resume 重放不调(理由见上面的头注)。未判的 matcher 过 `recordFailOpen`(tag `MATCHER_UNJUDGED_TAG`)。
+ * **只有 `admission.ts` 的 fresh 提交门调它** —— resume 重放不调(理由见上面的头注)。未判的 matcher 过 `recordFailOpen`(tag `MATCHER_UNJUDGED_TAG`);超预算的不是未判,是拒。
  */
-export declare function deadToolMatcherIssue(config: HooksConfig, depth: MatcherEvalDepth, budget?: MatcherEvalBudget): DeadToolMatcherIssue | undefined;
+export declare function toolMatcherIssue(config: HooksConfig, depth: MatcherEvalDepth, budget?: MatcherEvalBudget): ToolMatcherIssue | undefined;
 /**
  * 把 wire 上的 untrusted `settings.hooks` 校验成契约 {@link HooksConfig} + 服务侧上限。
  * 错误返回 error 字符串而不 throw——submit 路径 400 fail-loud、resume 防御路径 warn-drop,由调用方选。
@@ -139,7 +193,7 @@ export declare function parseHooksConfig(raw: unknown): ParseHooksConfigResult;
  * 运行期的 matcher 读法席位:**问契约包的 `hookMatcherSelects`,别无其它**(壳与服务端都问这一只,谁都不留副本;读法全文见它的头注,这里不重述)。
  * 三形(名字表 / 空 `*` 缺省 / 不锚定的 JS 正则)与「编不过 ⇒ `"invalid"`」都由它答;**对所有带 matcher 的事件同一只读法**(工具事件 / StopFailure 的 `error` 词 /
  * PreCompact·PostCompact 的 `trigger` 词 / `if` 条件的名部),不按事件分档。`"invalid"` ⇒ 该组不跑(fail-closed 到「不跑」),由调用方记账一次(`hook_matcher_invalid`);
- * 受理面({@link deadToolMatcherIssue})问的是同一只函数。
+ * 受理面({@link toolMatcherIssue})问的是同一只函数。
  */
 export declare function hookMatcherMatches(matcher: string | undefined, value: string): boolean | "invalid";
 /** `if` 条目条件(CC-exact,对照 CC 2.1.187/198 实测行为核验的真语义,两版一致):
@@ -230,8 +284,8 @@ export type HookLlmFailureCode = "no_content" | "hard_timeout";
  */
 export declare function buildHookContext(parts: readonly string[]): string | undefined;
 /**
- * 阶段三a:`http` 条目——契约语义 = POST hook 输入 JSON 到 `url`;headers 里的 `$NAME` 仅当 NAME 列在
- * `allowedEnvVars` 才从 worker 进程 env 插值(配置本身绝不携带密钥值,契约同边界)。
+ * 阶段三a:`http` 条目——契约语义 = POST hook 输入 JSON 到 `url`;headers 里的 `$NAME` / `${NAME}` 仅当 NAME 列在
+ * `allowedEnvVars` 才从 {@link hookEnv} 插值(配置本身绝不携带密钥值,契约同边界);读法只有契约包的 `interpolateHookEnvVars` 一只(见函数体)。
  *
  * 结果折算成伪 {@link CommandRunResult},让 9 事件的既有折叠逻辑零改动复用:
  *  - 2xx + JSON body → 同 exit-0-stdout-JSON(SyncHookOutput 决策面)。⚠️ 这是对 CC 行为的合理近似

package/dist/hooks/hook-runner.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import vm from "node:vm";
 import { hostShell, resolveHostShell, adoptHostForegroundChild } from "../plugins/host-platform.js";
-import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, HOOK_EVENT_MATCHER_FIELD, hookMatcherForm, hookMatcherSelects, } from "@sema-agent/settings-schema/hooks";
+import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, HOOK_EVENT_MATCHER_FIELD, hookMatcherForm, hookMatcherSelects, interpolateHookEnvVars, } from "@sema-agent/settings-schema/hooks";
 import { describeToolCatalog, isEngineRefusal, receiveHookResult } from "@sema-agent/core";
 import { boundedNoticeText } from "../fleet/fleet-bus.js";
 import { recordFailOpen } from "../observability/fail-open.js";
@@ -59,7 +59,8 @@ function toAssistantTurnError(errorKind) {
     return Object.prototype.hasOwnProperty.call(BRAIN_TO_TURN_ERROR, errorKind) ? (BRAIN_TO_TURN_ERROR[errorKind] ?? "unknown") : "unknown";
 }
 export const MAX_MATCHER_EVAL_CHARS = MAX_HOOK_COMMAND_CHARS;
-export const ADMISSION_MATCHER_EVAL_BUDGET_MS = 100;
+export const ADMISSION_MATCHER_EVAL_BUDGET_MS = 1_000;
+export const MATCHER_ECHO_CHARS = 200;
 const MATCHER_UNJUDGED_TAG = "server.hooks.matcher-unjudged";
 function matcherReadsWireToolName(event) {
     return HOOK_EVENT_OWNER[event] === "engine" && HOOK_EVENT_MATCHER_FIELD[event] === "tool_name";
@@ -81,10 +82,7 @@ function engineToolAliases() {
     return table;
 }
 let matcherEvalBox;
-function matcherSelectsWithin(matcher, name, budget) {
-    const remaining = budget.deadlineMs - budget.now();
-    if (remaining <= 0)
-        return "over_budget";
+function matcherSelectsWithin(matcher, name, budgetMs) {
     matcherEvalBox ??= {
         script: new vm.Script("hookMatcherSelects(matcher, name)"),
         context: vm.createContext({ hookMatcherSelects, matcher: "", name: "" }),
@@ -92,7 +90,7 @@ function matcherSelectsWithin(matcher, name, budget) {
     matcherEvalBox.context.matcher = matcher;
     matcherEvalBox.context.name = name;
     try {
-        const verdict = matcherEvalBox.script.runInContext(matcherEvalBox.context, { timeout: Math.max(1, Math.ceil(remaining)) });
+        const verdict = matcherEvalBox.script.runInContext(matcherEvalBox.context, { timeout: Math.max(1, Math.ceil(budgetMs)) });
         return verdict === true ? true : verdict === false ? false : "invalid";
     }
     catch (err) {
@@ -101,12 +99,21 @@ function matcherSelectsWithin(matcher, name, budget) {
         throw err;
     }
 }
+function matcherCompileSentence(matcher) {
+    try {
+        new RegExp(matcher);
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    return "the pattern does not compile as a regular expression";
+}
 const MATCHER_EVALUATION = {
     literal: { regex: "inline", literal: "inline" },
     regex: { regex: "budgeted", literal: "not_applicable" },
     invalid: { regex: "unreadable", literal: "not_applicable" },
 };
-function deadAliasInMatcher(matcher, depth, budget) {
+function judgeMatcher(matcher, depth, budgetMs) {
     if (matcher.length > MAX_MATCHER_EVAL_CHARS)
         return { kind: "unjudged", reason: "oversize" };
     const evaluate = MATCHER_EVALUATION[hookMatcherForm(matcher)][depth];
@@ -114,7 +121,7 @@ function deadAliasInMatcher(matcher, depth, budget) {
         case "not_applicable":
             return undefined;
         case "unreadable":
-            return { kind: "unjudged", reason: "invalid_regex" };
+            return { kind: "invalid_regex" };
         case "inline":
         case "budgeted":
             break;
@@ -123,48 +130,74 @@ function deadAliasInMatcher(matcher, depth, budget) {
             return unreachable;
         }
     }
-    const selects = (name) => {
-        const verdict = evaluate === "inline" ? hookMatcherSelects(matcher, name) : matcherSelectsWithin(matcher, name, budget);
-        return verdict === "invalid" ? "invalid_regex" : verdict;
-    };
+    const selects = (name) => (evaluate === "inline" ? hookMatcherSelects(matcher, name) : matcherSelectsWithin(matcher, name, budgetMs));
+    const unanswered = (verdict) => (verdict === "over_budget" ? { kind: "over_budget" } : { kind: "invalid_regex" });
     for (const [alias, canonical] of engineToolAliases()) {
         const selectsAlias = selects(alias);
         if (typeof selectsAlias === "string")
-            return { kind: "unjudged", reason: selectsAlias };
+            return unanswered(selectsAlias);
         if (!selectsAlias)
             continue;
         const selectsCanonical = selects(canonical);
         if (typeof selectsCanonical === "string")
-            return { kind: "unjudged", reason: selectsCanonical };
+            return unanswered(selectsCanonical);
         if (!selectsCanonical)
             return { kind: "dead", alias, canonical };
     }
     return undefined;
 }
-export function buildDeadToolMatcherRefusal(issue) {
-    return {
-        message: `settings.hooks.${issue.event}: matcher "${issue.alias}" is an alias; tool-event matchers match the tool's wire name (PostToolUse / PostToolUseFailure since 7.107.0) — use "${issue.canonical}"`,
-        field: "settings.hooks",
-        detail: { event: issue.event, alias: issue.alias, canonical: issue.canonical },
-    };
+export function buildToolMatcherRefusal(issue) {
+    switch (issue.reason) {
+        case "dead_alias":
+            return {
+                message: `settings.hooks.${issue.event}: matcher "${issue.alias}" is an alias; tool-event matchers match the tool's wire name (PostToolUse / PostToolUseFailure since 7.107.0) — use "${issue.canonical}"`,
+                field: "settings.hooks",
+                detail: { reason: issue.reason, event: issue.event, alias: issue.alias, canonical: issue.canonical },
+            };
+        case "over_budget":
+            return {
+                message: `settings.hooks.${issue.event}[${issue.groupIndex}].matcher: evaluating the pattern did not finish within ${issue.budgetMs} ms (catastrophic regex backtracking) — rewrite it as a tool-name list or a pattern without nested repetition`,
+                field: "settings.hooks",
+                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex, budgetMs: issue.budgetMs },
+            };
+        case "invalid_regex":
+            return {
+                message: `settings.hooks.${issue.event}[${issue.groupIndex}].matcher: ${JSON.stringify(issue.matcher)} is not a valid regular expression (${issue.compileError}) — fix the pattern, or write the tool names as a list such as "Read|Edit"`,
+                field: "settings.hooks",
+                detail: { reason: issue.reason, event: issue.event, groupIndex: issue.groupIndex },
+            };
+        default: {
+            const unreachable = issue;
+            return unreachable;
+        }
+    }
 }
-export function deadToolMatcherIssue(config, depth, budget = {}) {
-    const now = budget.now ?? (() => performance.now());
-    const deadline = { deadlineMs: now() + (budget.budgetMs ?? ADMISSION_MATCHER_EVAL_BUDGET_MS), now };
+export function toolMatcherIssue(config, depth, budget = {}) {
+    const budgetMs = budget.budgetMs ?? ADMISSION_MATCHER_EVAL_BUDGET_MS;
     for (const [event, groups] of Object.entries(config)) {
         if (!matcherReadsWireToolName(event))
             continue;
-        for (const group of groups ?? []) {
+        for (const [groupIndex, group] of (groups ?? []).entries()) {
             if (group.matcher === undefined)
                 continue;
-            const verdict = deadAliasInMatcher(group.matcher, depth, deadline);
+            const verdict = judgeMatcher(group.matcher, depth, budgetMs);
             if (verdict === undefined)
                 continue;
-            if (verdict.kind === "unjudged") {
-                recordFailOpen(MATCHER_UNJUDGED_TAG, `event=${event} reason=${verdict.reason} matcherChars=${group.matcher.length}`);
-                continue;
+            switch (verdict.kind) {
+                case "dead":
+                    return { reason: "dead_alias", event, alias: verdict.alias, canonical: verdict.canonical };
+                case "over_budget":
+                    return { reason: "over_budget", event, groupIndex, budgetMs };
+                case "invalid_regex":
+                    return { reason: "invalid_regex", event, groupIndex, matcher: clip(group.matcher, MATCHER_ECHO_CHARS), compileError: clip(matcherCompileSentence(group.matcher), MATCHER_ECHO_CHARS) };
+                case "unjudged":
+                    recordFailOpen(MATCHER_UNJUDGED_TAG, `event=${event} reason=${verdict.reason} matcherChars=${group.matcher.length}`);
+                    break;
+                default: {
+                    const unreachable = verdict;
+                    return unreachable;
+                }
             }
-            return { event, alias: verdict.alias, canonical: verdict.canonical };
         }
     }
     return undefined;
@@ -558,19 +591,19 @@ async function runLlmHook(entry, payload, ctx, extra) {
             clearTimeout(hardTopTimer);
     }
 }
-async function runHttpHook(entry, payload, ctx) {
+const MAX_BLANKED_REFERENCES_LOGGED = 16;
+async function runHttpHook(entry, payload, ctx, event) {
     const timeoutMs = Math.min(entry.timeout ?? DEFAULT_HOOK_TIMEOUT_SECONDS, MAX_HOOK_TIMEOUT_SECONDS) * 1000;
-    const allowed = new Set(entry.allowedEnvVars ?? []);
-    const envSource = hookEnv(ctx);
-    const headers = { "content-type": "application/json" };
-    for (const [k, v] of Object.entries(entry.headers ?? {})) {
-        headers[k] = v.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (whole, name) => {
-            if (!allowed.has(name))
-                return whole;
-            const ev = envSource[name];
-            return typeof ev === "string" ? ev : whole;
+    const interpolated = interpolateHookEnvVars(entry.headers ?? {}, entry.allowedEnvVars ?? [], hookEnv(ctx));
+    if (interpolated.blanked.length > 0) {
+        ctx.logger.warn("hook_http_header_env_blanked", {
+            event,
+            url: buildDisplaySafeUrl(entry.url),
+            blankedCount: interpolated.blanked.length,
+            blanked: interpolated.blanked.slice(0, MAX_BLANKED_REFERENCES_LOGGED).map(({ header, name, reason }) => ({ header, name, reason })),
         });
     }
+    const headers = { "content-type": "application/json", ...interpolated.headers };
     const ac = new AbortController();
     const timer = setTimeout(() => ac.abort(), timeoutMs);
     try {
@@ -732,7 +765,7 @@ async function runMatchingEntries(event, groups, matchValue, payload, ctx, onceF
                 onceFired.add(onceKey);
             if (entry.type === "prompt" || entry.type === "agent")
                 llmEntries++;
-            const run = entry.type === "http" ? await runHttpHook(entry, payload, ctx)
+            const run = entry.type === "http" ? await runHttpHook(entry, payload, ctx, event)
                 : entry.type === "prompt" || entry.type === "agent" ? await runLlmHook(entry, payload, ctx, entry.type === "prompt" ? llmExtra : { system: ccAgentHookSystemFor(event), event })
                     : await runCommandHook(entry, payload, ctx);
             if (run.spawnError) {

package/dist/http/admission.js

@@ -1,13 +1,13 @@
 import { APPROVAL_REACH, MCP_IMAGE_MAX_BASE64, isApprovalReach, isPermissionMode, isThinkingLevel, expandTiers } from "@sema-agent/core";
 import { isAtMentionable, matchCatalogModel, refusedCatalogEntry, selectableCatalog } from "../model-select.js";
 import { modelUnavailableMessage } from "../model-entry-refusal.js";
-import { HttpError } from "../security.js";
+import { HttpError, sessionIdShapeIssue } from "../security.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS, PERMISSION_MODE_WORDS, parseTaskSettings, settingsPermissionBucketIssue, skillListingBudgetFractionOk, skillListingMaxDescOk, stampEntryPermissionMode, taskHooksHonored, taskSettingsKeyIssue } from "../task-settings.js";
 import { autonomyModeFloor } from "../runtime-governance.js";
 import { taskBodyKeyIssue } from "../request-key-closure.js";
 import { FILE_HISTORY_DISABLED_NO_RESTORE, fileHistoryRestoreConflict, inheritEnvFieldIssue, singleMemberOffFieldIssue } from "../request-value-closure.js";
 import * as facts from "../capability-facts.js";
-import { buildDeadToolMatcherRefusal, deadToolMatcherIssue, parseHooksConfig } from "../hooks/hook-runner.js";
+import { buildToolMatcherRefusal, parseHooksConfig, toolMatcherIssue } from "../hooks/hook-runner.js";
 import { judgeRequestWebSearch } from "../plugins/web-search.js";
 import { normalizeApproachNotice, skillToolListOk, skillToolListRefusal, unknownTaskAgentModelRef, validateTaskAgents } from "../spec-fields.js";
 import { MAX_ADDITIONAL_DIRS } from "../task-cwd.js";
@@ -85,9 +85,12 @@ export function createAdmission(ctx) {
             sendError(res, 400, "request.field_invalid", "jobId must be a non-empty string of at most 64 characters");
             return null;
         }
-        if (typeof body.sessionId === "string" && body.sessionId.length > 64) {
-            sendError(res, 400, "request.field_invalid", "sessionId must be at most 64 characters");
-            return null;
+        {
+            const sessionIdIssue = sessionIdShapeIssue(body.sessionId);
+            if (sessionIdIssue) {
+                sendError(res, 400, "request.id_invalid", sessionIdIssue);
+                return null;
+            }
         }
         if (typeof body.systemPrompt === "string" && body.systemPrompt.length > MAX_SYSTEM_PROMPT_CHARS) {
             sendError(res, 400, "request.field_invalid", `systemPrompt must be at most ${MAX_SYSTEM_PROMPT_CHARS} characters`);
@@ -212,9 +215,9 @@ export function createAdmission(ctx) {
                     sendError(res, 400, "request.field_invalid", hooksParsed.error ?? "settings.hooks: invalid shape");
                     return null;
                 }
-                const deadMatcher = deadToolMatcherIssue(hooksParsed.config, taskHooksHonored(deps.config) ? "regex" : "literal");
-                if (deadMatcher !== undefined) {
-                    const refusal = buildDeadToolMatcherRefusal(deadMatcher);
+                const toolMatcher = toolMatcherIssue(hooksParsed.config, taskHooksHonored(deps.config) ? "regex" : "literal");
+                if (toolMatcher !== undefined) {
+                    const refusal = buildToolMatcherRefusal(toolMatcher);
                     sendError(res, 400, "request.field_invalid", refusal.message, { field: refusal.field, detail: refusal.detail });
                     return null;
                 }
@@ -502,7 +505,7 @@ export function createAdmission(ctx) {
                 return null;
             }
         }
-        for (const key of ["excludeTools", "deferTools"]) {
+        for (const key of ["allowTools", "excludeTools", "deferTools"]) {
             const v = body[key];
             if (v !== undefined && (!Array.isArray(v) || v.some((n) => typeof n !== "string" || n.length === 0))) {
                 sendError(res, 400, "request.field_invalid", `${key} must be an array of non-empty tool-name strings`);

package/dist/http/durable-run-leg.d.ts

@@ -15,7 +15,7 @@
  */
 import { type RunInternals } from "@sema-agent/core";
 import type { RunStore } from "../plugins/store-backend.js";
-import type { RunRecord } from "../plugins/store-contracts.js";
+import type { RunIdemBinding, RunRecord } from "../plugins/store-contracts.js";
 import type { PreparedTaskSubmission, RouteCtxBase } from "./route-ctx.js";
 /**
  * 🔴 **TRUSTED run internals** —— 由**部署方**(不是模型、不是请求体、不是工具参数)铸给这一跑的
@@ -35,8 +35,9 @@ export interface DurableRunLegArgs {
     prepared: PreparedTaskSubmission;
     /** 调用方自带的 taskId(`POST /v1/runs` 的 `body.taskId` 幂等键);缺席 ⇒ 本腿铸 uuidv7。 */
     clientTaskId?: string;
-    /** 这次提交的幂等键(`idemKeyOf(raw, caller, "run")`)—— 落 `task_run.idem_key`;缺席 = 调用方没带 `Idempotency-Key`。 */
-    idemKey?: string;
+    /** 这次提交的账本绑定(键 `idemKeyOf(raw, caller, "run")` + 请求体指纹)—— 落 `task_run.idem_key` / `idem_body_fingerprint`;
+     *  缺席 = 调用方没带 `Idempotency-Key`。 */
+    idem?: RunIdemBinding;
     /** 🔒 这条 run 的 **fleet 行 scope** —— 必须与 `GET /v1/fleet/stream` 过滤用的是同一个身份,且绝不是
      *  自报的 `x-agent-principal` 头(自报头会把行打到受害者的 scope 上,或打到 `default` 而真属主的流把它
      *  过滤掉)。提交门传 `gatedPrincipal(req) ?? "default"`;`/decide` 的第三条车道传 resume 家族的
@@ -71,7 +72,7 @@ export type DurableRunLegOutcome = {
 /**
  * 建行 + 驱动。返回 `202` = 新行已建并在跑(体带 `taskId`/`sessionId`);`409` = 会话被别的 run 占着,
  * **没有**建行(体 = `buildActiveRunConflict` 的既有形,含 `errorCode: "conflict.session_active_run"`);
- * `existing` = 这次提交的钥匙(`idemKey` / `clientTaskId`)已经指向一条行,没建新行。
+ * `existing` = 这次提交的钥匙(`idem.key` / `clientTaskId`)已经指向一条行,没建新行。
  * 协议渲染归调用方(HTTP `sendJson` / A2A 协议对象 / `/decide` 的受理体)。
  */
 export declare function mintAndDriveDurableRun(ctx: RouteCtxBase, runStore: RunStore, args: DurableRunLegArgs): Promise<DurableRunLegOutcome>;

package/dist/http/durable-run-leg.js

@@ -15,7 +15,7 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
     const { inflightRuns, preemptableRuns, steerableRuns } = ctx.registry;
     const sessionId = args.prepared.spec.sessionId ?? uuidv7();
     const taskId = args.clientTaskId ?? uuidv7();
-    const created = await runStore.createRun(taskId, sessionId, args.prepared.auth?.principal ?? null, deps.instanceId ?? "default", { ...runMeta(args.prepared, args.source), idemKey: args.idemKey ?? null });
+    const created = await runStore.createRun(taskId, sessionId, args.prepared.auth?.principal ?? null, deps.instanceId ?? "default", { ...runMeta(args.prepared, args.source), idem: args.idem ?? null });
     if (created.ok)
         clearTurnActivity(taskId);
     if (created.ok)

package/dist/http/idempotency.d.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage } from "node:http";
 import type { ServiceConfig } from "../config-types.js";
 import type { WiringManifestReceipt } from "./wire-types.js";
 import type { SubmitReplayFace } from "./submit-replay.js";
+import type { RunIdemBinding } from "../plugins/store-contracts.js";
 /**
  * 同进程的**在飞合流** —— 并发同键的提交共享同一个 promise(避免同一进程里双起)。它**不是**重放的真源。
  *
@@ -78,14 +79,35 @@ export declare function idemIdentityOf(caller: IdemCaller): string;
  */
 export declare function idemKeyOf(raw: string, caller: IdemCaller, family: IdemFamily): string;
 /**
- * 在飞合流的键 = 提交幂等键 × 这条腿的**回执形**(`durable` / `sync`)× 这次请求自带的 taskId。
+ * 一次提交的**请求体指纹** —— HTTP 三条提交腿(`POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs`)同一只规范化函数:
+ * `sha256(canonicalJson(体 − taskId))` 的 hex(定宽 64)。
  *
- * 合流交出的是**首个请求那条腿的结局**,所以只有「同一条 run、同一种回执形、同一把 taskId」的请求才许合流:durable 腿
- * 合到同步腿的在飞结局上会拿到 200 引擎结果而不是 202 收据;带另一个 taskId 的请求合进来就绕过了「key 指向别的行」
- * 那条 409。形不同(或 taskId 不同)的请求各自走到建行,由店的原子赢或观察 + 唯一回执函数作答 —— 仍是一条 run,
- * 各拿自己腿的回执形。同步腿与流式腿同形(流式腿把同一份体放进 `done.result`),合流照旧。
+ * 幂等 = 同一调用方、同一键、**同一请求**:账本行记下绑定 `Idempotency-Key` 的那次请求的指纹(`task_run.idem_body_fingerprint`),
+ * 同键再投而指纹不同 ⇒ 唯一回执函数答 409(`http/submit-replay.ts`)。规范化只有两步:
+ *  · JSON 按键递归排序(唯一序列化器 `canonicalJson`;值为 `undefined` 的键与缺席同义)—— 键序不同的同一份体是同一请求;
+ *  · 去掉 `taskId` —— 它是同一条律的**另一把钥匙**(调用方自铸的主键),由回执函数的「钥匙指向别的行 ⇒ `conflict.run_exists`」判,
+ *    不是请求内容(换腿重投:流式腿不带 → durable 腿带回 `x-task-id`,仍是同一请求)。
+ * 头一概不进:身份已在键里(`idemKeyOf` 的身份位),其余头(`Idempotency-Key` 本身、`x-detach-on-disconnect` 一类连接语义)不是提交内容。
+ * 入参是**线上收到的那份体**(`readJson` 的产物),不是 `prepareSpec` 之后服务端盖过章的体 —— 指纹只由调用方看得见的字节构成,
+ * 否则两台配置不同的副本对同一次重试算出两只指纹。
  */
-export declare function inflightKeyOf(idemKey: string, face: SubmitReplayFace, clientTaskId?: string): string;
+export declare function submissionFingerprintOf(body: unknown): string;
+/**
+ * HTTP 提交腿(`POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs`)的**账本绑定**唯一铸法:键 = `idemKeyOf(raw, caller, "run")`,
+ * 指纹 = {@link submissionFingerprintOf}(线上收到的那份体)。三条腿在读到 `Idempotency-Key` 的同一处调它 —— 键与指纹同铸,不各拼一份。
+ * (A2A 的绑定不经这里:它的原始键就是消息内容指纹,绑定 = `{ key: idemKeyOf(指纹, …), bodyFingerprint: 指纹 }`,见 `routes/a2a-serve.ts`。)
+ */
+export declare function submissionIdemOf(raw: string, caller: IdemCaller, body: unknown): RunIdemBinding;
+/**
+ * 在飞合流的键 = 这次提交的**账本绑定**(幂等键 × 请求体指纹)× 这条腿的**回执形**(`durable` / `sync`)× 这次请求自带的 taskId。
+ *
+ * 合流交出的是**首个请求那条腿的结局**,所以只有「同一请求、同一条 run、同一种回执形、同一把 taskId」的请求才许合流:同键异体的
+ * 请求合进来就是静默拿到别的请求的结局(正是 409 `conflict.idempotency_payload_mismatch` 要拦的那件事);durable 腿合到同步腿的在飞
+ * 结局上会拿到 200 引擎结果而不是 202 收据;带另一个 taskId 的请求合进来就绕过了「key 指向别的行」那条 409。不许合流的请求各自走到
+ * 读行 / 建行,由店的原子赢或观察 + 唯一回执函数作答 —— 同体的仍是一条 run、各拿自己腿的回执形,异体的拿 409。同步腿与流式腿同形
+ * (流式腿把同一份体放进 `done.result`),合流照旧。
+ */
+export declare function inflightKeyOf(idem: RunIdemBinding, face: SubmitReplayFace, clientTaskId?: string): string;
 /**
  * 提交腿的**运行结局**(在飞合流共享的那一只)—— `status` + `body` 是它一直以来的两位;S-528 起多一位
  * `wiringManifest`。

package/dist/http/idempotency.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { canonicalJson } from "../canonical-json.js";
 import { gatedPrincipal } from "./principal-gate.js";
 export class IdempotencyCache {
     ttlMs;
@@ -77,7 +78,14 @@ export function idemIdentityOf(caller) {
 export function idemKeyOf(raw, caller, family) {
     return createHash("sha256").update(`${idemIdentityOf(caller)}\x1f${idemFamilyTag(family)}\x1f${raw}`).digest("hex");
 }
-export function inflightKeyOf(idemKey, face, clientTaskId) {
-    return `${idemKey}\x1f${face}\x1f${clientTaskId ?? ""}`;
+export function submissionFingerprintOf(body) {
+    const content = body !== null && typeof body === "object" && !Array.isArray(body) ? { ...body, taskId: undefined } : body;
+    return createHash("sha256").update(canonicalJson(content)).digest("hex");
+}
+export function submissionIdemOf(raw, caller, body) {
+    return { key: idemKeyOf(raw, caller, "run"), bodyFingerprint: submissionFingerprintOf(body) };
+}
+export function inflightKeyOf(idem, face, clientTaskId) {
+    return `${idem.key}\x1f${idem.bodyFingerprint}\x1f${face}\x1f${clientTaskId ?? ""}`;
 }
 //# sourceMappingURL=idempotency.js.map

package/dist/http/principal-gate.d.ts

@@ -92,6 +92,20 @@ export declare function sendUnauthorized(res: ServerResponse, face: Unauthorized
  * 那样「谁多给了 operator 一条路」在代码上看得见,而不是被偷偷塞进共享谓词里。
  */
 export declare function runOwnerReadable(principal: string | undefined, owner: string | null, config: ServiceConfig): boolean;
+/**
+ * 🔴 **「这台部署有没有身份边界」的唯一判据**(S-1452)。dev-open = 没配 service token(单一或 per-system)、没配只读 trace token、
+ * 也没开 `REQUIRE_PRINCIPAL`:请求里没有任何东西替主体头作保,头是谁都能自报的**标签**(过滤 / 展示用),不是身份。
+ * 三处读它、不各写一份:会话列表的 fleet-wide 第一臂(`isFleetWide`)、会话写面的 fleet-wide 第一臂(`sessionOwnerScopeForWrite`)、
+ * 会话面的属主谓词({@link sessionOwnerReadable})—— 于是「调用方是谁」在列表与单会话面上只有一只读法。
+ */
+export declare function devOpenDeployment(config: ServiceConfig): boolean;
+/**
+ * **「这个调用方能不能动这只会话」的唯一谓词**(会话面:视图 / head / 事件流 / 记忆状态与自助抹除 / 改名置顶 / 后台任务 / MCP 重连 /
+ * 面板的上一腿 MCP 投影)。= {@link devOpenDeployment} ∨ {@link runOwnerReadable}:没有身份边界的部署上不钉任何人(与会话列表同读,
+ * 列表把这只会话列给谁,谁就读得到它);有身份边界的部署上就是 run 面那一条谓词,一字不变。
+ * run 面(poll / events / cancel …)不读本谓词 —— 那是 run 资源的门,另一只。
+ */
+export declare function sessionOwnerReadable(principal: string | undefined, owner: string | null, config: ServiceConfig): boolean;
 /** The EXPLICIT operator gate (IMAGE-API-DESIGN.md §P2.4a MUST-FIX) — NOT the bare `isOperator` (whose empty-list
  *  "true-for-all" is an unrestricted-write exec door the instant OPERATOR_PRINCIPALS is empty). Requires a non-empty
  *  operator set AND a present principal IN it. The same form the preempt/resume endpoints already use.

package/dist/http/principal-gate.js

@@ -93,6 +93,13 @@ export function runOwnerReadable(principal, owner, config) {
         return true;
     return !config.requirePrincipal && owner === "anon:shell-live" && principal === undefined;
 }
+export function devOpenDeployment(config) {
+    const anyServiceToken = Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
+    return !anyServiceToken && !config.traceToken && !config.requirePrincipal;
+}
+export function sessionOwnerReadable(principal, owner, config) {
+    return devOpenDeployment(config) || runOwnerReadable(principal, owner, config);
+}
 export function explicitOperatorOk(principal, operatorPrincipals) {
     return operatorPrincipals.length > 0 && principal !== undefined && operatorPrincipals.includes(principal);
 }