@sema-agent/server 7.124.0 → 7.125.0

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

@@ -44,14 +44,16 @@ export interface ParseHooksConfigResult {
  * 其实没跑,硬破坏三句要求的「响亮」没有着落。7.112.0(S-924)只拒**字面**别名;同一个错误写成 `^ListPeers$` / `ListPeers.*` / `(ListPeers)` 照样 200(S-995)。
  *
  * 规则(一条;字面形是它的特例):{@link deadToolMatcherIssue} 对 core 静态目录里**每一条退役别名**问「这只 matcher 选不选它 / 选不选它的正名」:
- * matcher **命中别名 ∧ 不命中它的正名** ⇒ `400 request.field_invalid`(`admission.ts` fresh 门)。「选不选」与运行期 {@link hookMatcherMatches} 同一套读法,按**一条顺序**判(两档共用,7.114.0 修复轮):
+ * matcher **命中别名 ∧ 不命中它的正名** ⇒ `400 request.field_invalid`(`admission.ts` fresh 门)。「选不选」**只有一只读法**:契约包的 `hookMatcherSelects`
+ * (名字表 / 空 / `*` / 正则三形都由它答;正则形**不锚定**,与壳同形;运行期 {@link hookMatcherMatches} 问的也是它,本仓不留副本)。按**一条顺序**判(两档共用,7.114.0 修复轮):
  *  ① **长度上限**:超 {@link MAX_MATCHER_EVAL_CHARS} 的 matcher 两档都不读 ⇒ 未判(reason = oversize);
- *  ② 空 / `*` 命中一切 ⇒ 永不「死」;
- *  ③ **字面 / 名字表读法**({@link matcherLiteralNames},与运行期共用:`|` 与 `,` 分隔、每段 trim〔容忍两端与分隔符两侧空白〕、不折大小写、不剥词内空白)
- *    两档都先走、每只 matcher 读一次、**不占求值预算**,按名字表成员答 —— 所以两档在字面子集上答案逐位相同是构造出来的(R5f 语料再钉);
- *  ④ 只剩**正则形**:**`"regex"` 档**(hooks 会被采纳的车道,`taskHooksHonored`)问运行期正则臂的那一只函数 {@link matcherPatternMatches}(同一个函数对象,锚定正则),
- *    经 `node:vm` 的 `timeout` 带一次受理共享的预算调用({@link matcherPatternMatchesWithin});**`"literal"` 档**(多租户车道:hooks 整只被 resolveSpec 忽略)
- *    = **不适用**:该车道没有被守的对象(hooks 不装配),不判、不算未判、不登记 —— **零正则求值、零调用方正则执行**(7.112.0 的字面判保留:裸 `ListPeers` / `Read|ListPeers` 照旧 400)。
+ *  ② **形只问契约包的 `hookMatcherForm`**(与 `hookMatcherSelects` 同一只解析步,本仓不留形判),闭集三词、两档一张表:
+ *     · `literal`(缺席 / 空 / `*` / 名字表形;契约不编、不跑调用方的正则)⇒ 两档都**直接问契约函数**、**不占求值预算**;
+ *     · `regex` ⇒ **`"regex"` 档**(hooks 会被采纳的车道,`taskHooksHonored`)把**同一只契约函数**经 `node:vm` 的 `timeout` 带一次受理共享的预算调用({@link matcherSelectsWithin});
+ *       **`"literal"` 档**(多租户车道:hooks 整只被 resolveSpec 忽略)= **不适用**:该车道没有被守的对象(hooks 不装配),不判、不算未判、不登记 —— **零调用方正则执行**
+ *       (7.112.0 的字面判保留:裸 `ListPeers` / `Read|ListPeers` 照旧 400);
+ *     · `invalid`(编不过)⇒ `"regex"` 档 = 未判 `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)—— 预算只界住一次请求、界不住「每个请求再拿一份」。
  *    但也不能因此在多租户车道「不判决」(那会放宽已发行为:裸 `ListPeers` 的 400)。所以两车道同一条规则、两档深度。谓词 `taskHooksHonored` 是唯一属主(与 resolveSpec / capabilities 同调)。
@@ -66,7 +68,7 @@ export interface ParseHooksConfigResult {
  *  · **正名同在则不拒**:`正名|别名` / `List.*` 会命中正名,不是「静默不命中」,且正是 7.107.0 CHANGELOG 给的「滚动期两名都写」补偿形。
  *    只拒「别名那一路永远打不中、而它的正名不在选中集里」—— 含 `Read|ListPeers`(7.112.0 已拒;主会话裁:规则形采「按条目逐条问」,不放宽;卡面整 matcher「匹配不到任何现役名」形会把它放回 200)。
  *    多拒(相对卡面形)三例与出路:`Read|ListPeers` / `ListPeers|mcp__.*`(别名支永不命中,出路:改成正名)/ 排除式 `^(?!ListAgents).*`(出路:`^(?!ListAgents|ListPeers).*` 两名都不命中 ⇒ 放)。
- *  · **空白与大小写(S-995 / sema-test [ref] 起,运行期与 CC 2.1.280 同形)**:字面 / 名字表读法({@link matcherLiteralNames};`|` 与 `,` 分隔)容忍两端与分隔符两侧空白 ⇒ `" ListPeers"` / `"ListPeers "` / `"Read | ListPeers"` 会命中别名 ⇒ 落进本规则 400;
+ *  · **空白与大小写(S-995 / sema-test [ref] 起,运行期与 CC 同形)**:名字表读法(契约函数;`|` 与 `,` 分隔)容忍两端与分隔符两侧空白 ⇒ `" ListPeers"` / `"ListPeers "` / `"Read | ListPeers"` 会命中别名 ⇒ 落进本规则 400;
  *    **区分大小写、不剥词内空白** ⇒ `"listpeers"` / `"List Peers"` 对别名与正名都选不中,照旧受理(CC 同形)。
  *  · **不在本规则内**:两边都选不中的 matcher(大小写错 / 词内空白 / 纯错字;目录之外的 MCP / 嵌入方工具名同样「选不中目录里任何名」,受理面无从区分错字与它们)=
  *    **「选不到目录里任何名」另一类,候设计(台账另立号,主会话裁)**。
@@ -89,7 +91,7 @@ export interface ParseHooksConfigResult {
 export declare const MAX_MATCHER_EVAL_CHARS = 8192;
 /** 一次 fresh 受理里 regex 档**正则形**求值共享的墙钟预算(毫秒)。字面形不占它。良性求值 ~0.1 ms;灾难回溯的 matcher 把预算吃完就停,后面的正则形组直接「未判」。 */
 export declare const ADMISSION_MATCHER_EVAL_BUDGET_MS = 100;
-/** 受理面判据的求值深度(见上头注):`"regex"` = 字面形按名字表答、正则形问运行期同一只正则求值(带预算);`"literal"` = 7.112.0 的字面判(零正则,正则形不适用)。 */
+/** 受理面判据的求值深度(见上头注):`"regex"` = 契约字面形直接问、正则形带预算问同一只契约函数;`"literal"` = 7.112.0 的字面判(只判契约字面形,零调用方正则执行;正则形 / 编不过的形不适用)。 */
 export type MatcherEvalDepth = "regex" | "literal";
 /**
  * **仅供测试注入**的求值预算(生产调用点不传 ⇒ 预算 = {@link ADMISSION_MATCHER_EVAL_BUDGET_MS}、时钟 = `performance.now`)。
@@ -134,25 +136,11 @@ export declare function deadToolMatcherIssue(config: HooksConfig, depth: Matcher
  */
 export declare function parseHooksConfig(raw: unknown): ParseHooksConfigResult;
 /**
- * matcher 的**字面 / 名字表读法**(S-995 / sema-test [ref];与 CC 2.1.280 同形):matcher 只含名字字符(`[A-Za-z0-9_-]`)、竖线、**逗号**与**空格**时,它不是正则而是「名字列表」——
- * 按 `[|,]` 拆、**每段 trim**、丢空段;返回这张名字表。含任何别的字符(`.` / `*` / 括号 / 制表 / 换行 …)⇒ `undefined` = 不是字面读法,整体当正则(由调用方处置,**一字不动**)。
- * 大小写敏感、词内空白不剥(`"Ba sh"` 是一个词 `Ba sh`)。**对所有带 matcher 的事件同一只读法**(工具事件 / StopFailure 的 `error` 词 / PreCompact·PostCompact 的 `trigger` 词 /
- * `if` 条件的名部),不按事件分档。
- *
- * 等价性的依据(收车档 ⑥ / ⑦):
- *  · 黑盒 —— sema-test `repro/cc-r219-mcpstar-hookmatcher-20261003/`([ref],CC 2.1.280 真 TUI + 真 command 钩子):`" Bash"` / `"Bash "` / `" Bash "` / `"Read | Bash"` 命中 3/3,
- *    `"Ba sh"`(词内空白)/ `bash` / `BASH` 不命中(零告警),`^Bash$` / `Bash.*` / `(Bash)` / `Read|Bash` 照命中;PreToolUse 与 PostToolUse 同向。**逗号没有黑盒读数**,只有语料。
- *  · 语料 —— `sema-internal/blueprints/cc-decoded/cli280.js:216638` `uAe(matchValue, matcher, flag, …)` → `$mr(matcher, flag, …)`:`flag` 真时字符集门 `/^[a-zA-Z0-9_|, -]+$/` 过了才
- *    `matcher.split(/[|,]/).map(trim).filter(Boolean)` 做成员判;过不了才 `new RegExp(matcher)`(CC 的正则路径**不锚定**,本仓锚定 `^(?:…)$` —— 既有差异,不动)。
- *    本函数的字符集与拆符与 CC 逐字同(空白只认空格 0x20)。
- *  · 已知差异(如实登记,本车不做):CC 的空白 / 逗号放行**按事件分档**(`dAe` 集合:工具事件 / PreCompact / PostCompact 等放,StopFailure 不放),本函数不分事件(第二批裁:同一只读法);
- *    CC 正则路径不锚定、本仓锚定。两条登记在 CHANGELOG 7.114.0 线 · 车 UW 已知边界。
- * 零正则:单趟逐字符扫描(7.114.0 修复轮起;只为非空段分配名字,不按分隔符个数分配)。受理面两档({@link deadToolMatcherIssue})与运行期求值**共用这一只**读法,且两档都先走它、不占求值预算 ——
- * 两档在字面子集上答案逐位相同是**构造出来的**,不是对拍出来的(超过长度上限的 matcher 两档都不读、同判未判)。
+ * 运行期的 matcher 读法席位:**问契约包的 `hookMatcherSelects`,别无其它**(壳与服务端都问这一只,谁都不留副本;读法全文见它的头注,这里不重述)。
+ * 三形(名字表 / 空 `*` 缺省 / 不锚定的 JS 正则)与「编不过 ⇒ `"invalid"`」都由它答;**对所有带 matcher 的事件同一只读法**(工具事件 / StopFailure 的 `error` 词 /
+ * PreCompact·PostCompact 的 `trigger` 词 / `if` 条件的名部),不按事件分档。`"invalid"` ⇒ 该组不跑(fail-closed 到「不跑」),由调用方记账一次(`hook_matcher_invalid`);
+ * 受理面({@link deadToolMatcherIssue})问的是同一只函数。
  */
-export declare function matcherLiteralNames(matcher: string): readonly string[] | undefined;
-/** CC matcher 语义:空/`*`/缺省匹配一切;**字面 / 名字表读法**({@link matcherLiteralNames}:`|` 与 `,` 分隔、每段 trim、不剥词内空白、区分大小写)按名字表成员判;
- *  其余整体当 JS 正则({@link matcherPatternMatches};锚定全匹配;S-995 起正则路径一字不动);非法正则 → 该条不匹配(fail-closed 到"不跑",由调用方记账一次)。 */
 export declare function hookMatcherMatches(matcher: string | undefined, value: string): boolean | "invalid";
 /** `if` 条目条件(CC-exact,对照 CC 2.1.187/198 实测行为核验的真语义,两版一致):
  *  值 = permission-rule 模式(`ToolName` 或 `ToolName(arg-模式)`),【不是】表达式语言——按当前工具调用

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, } from "@sema-agent/settings-schema/hooks";
+import { HooksConfig, DEFAULT_HOOK_TIMEOUT_SECONDS, HOOK_EVENT_OWNER, HOOK_EVENT_MATCHER_FIELD, hookMatcherForm, hookMatcherSelects, } 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";
@@ -81,13 +81,13 @@ function engineToolAliases() {
     return table;
 }
 let matcherEvalBox;
-function matcherPatternMatchesWithin(matcher, name, budget) {
+function matcherSelectsWithin(matcher, name, budget) {
     const remaining = budget.deadlineMs - budget.now();
     if (remaining <= 0)
         return "over_budget";
     matcherEvalBox ??= {
-        script: new vm.Script("matcherPatternMatches(matcher, name)"),
-        context: vm.createContext({ matcherPatternMatches, matcher: "", name: "" }),
+        script: new vm.Script("hookMatcherSelects(matcher, name)"),
+        context: vm.createContext({ hookMatcherSelects, matcher: "", name: "" }),
     };
     matcherEvalBox.context.matcher = matcher;
     matcherEvalBox.context.name = name;
@@ -101,31 +101,30 @@ function matcherPatternMatchesWithin(matcher, name, budget) {
         throw err;
     }
 }
+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) {
     if (matcher.length > MAX_MATCHER_EVAL_CHARS)
         return { kind: "unjudged", reason: "oversize" };
-    if (matcher === "" || matcher === "*")
-        return undefined;
-    const names = matcherLiteralNames(matcher);
-    if (names !== undefined) {
-        for (const [alias, canonical] of engineToolAliases()) {
-            if (names.includes(alias) && !names.includes(canonical))
-                return { kind: "dead", alias, canonical };
-        }
-        return undefined;
-    }
-    switch (depth) {
-        case "literal":
+    const evaluate = MATCHER_EVALUATION[hookMatcherForm(matcher)][depth];
+    switch (evaluate) {
+        case "not_applicable":
             return undefined;
-        case "regex":
+        case "unreadable":
+            return { kind: "unjudged", reason: "invalid_regex" };
+        case "inline":
+        case "budgeted":
             break;
         default: {
-            const unreachable = depth;
+            const unreachable = evaluate;
             return unreachable;
         }
     }
     const selects = (name) => {
-        const verdict = matcherPatternMatchesWithin(matcher, name, budget);
+        const verdict = evaluate === "inline" ? hookMatcherSelects(matcher, name) : matcherSelectsWithin(matcher, name, budget);
         return verdict === "invalid" ? "invalid_regex" : verdict;
     };
     for (const [alias, canonical] of engineToolAliases()) {
@@ -214,47 +213,8 @@ export function parseHooksConfig(raw) {
     }
     return { config };
 }
-export function matcherLiteralNames(matcher) {
-    const names = [];
-    let first = -1;
-    let last = -1;
-    for (let i = 0; i <= matcher.length; i++) {
-        const c = i < matcher.length ? matcher.charCodeAt(i) : 0x7c;
-        if (c === 0x7c || c === 0x2c) {
-            if (first !== -1)
-                names.push(matcher.slice(first, last + 1));
-            first = -1;
-            last = -1;
-            continue;
-        }
-        if (c === 0x20)
-            continue;
-        const nameChar = (c >= 0x30 && c <= 0x39) || (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a) || c === 0x5f || c === 0x2d;
-        if (!nameChar)
-            return undefined;
-        if (first === -1)
-            first = i;
-        last = i;
-    }
-    return names;
-}
-function matcherPatternMatches(matcher, value) {
-    if (matcher === value)
-        return true;
-    try {
-        return new RegExp(`^(?:${matcher})$`).test(value);
-    }
-    catch {
-        return "invalid";
-    }
-}
 export function hookMatcherMatches(matcher, value) {
-    if (matcher === undefined || matcher === "" || matcher === "*")
-        return true;
-    const names = matcherLiteralNames(matcher);
-    if (names !== undefined)
-        return names.includes(value);
-    return matcherPatternMatches(matcher, value);
+    return hookMatcherSelects(matcher, value);
 }
 export function hookIfMatches(cond, payload) {
     if (cond.length > 500 || (cond.match(/\*/g)?.length ?? 0) > 16)

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

@@ -149,6 +149,9 @@ export interface ActiveRunConflictDoneResult {
     stale?: true;
     pendingGate?: PendingGateMaterial;
 }
+/** 一份提交拒绝体是不是**会话占用冲突**体(`buildActiveRunConflict` 的产物)—— 判别位 = 机器码,与 sdk 终帧联合里冲突臂的窄化同一个位。
+ *  只收那一只铸点的产物:调用方是流式腿把「拒绝」编码成终帧的投影({@link toDoneFrameResult} 的入口),别处的 409 体不过这里。 */
+export declare function isActiveRunConflictBody(body: unknown): body is ActiveRunConflictBody;
 export declare function toDoneFrameResult(body: ActiveRunConflictBody): ActiveRunConflictDoneResult;
 interface ConflictProbeDeps<TToken> {
     /** 结构形入参,但 `status` 取 run 行的**闭词表**(合并码重扫):判 park 要走词表属主

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

@@ -27,6 +27,9 @@ function safeCheckpointIdOf(raw, token) {
         return undefined;
     return raw;
 }
+export function isActiveRunConflictBody(body) {
+    return typeof body === "object" && body !== null && "activeTaskId" in body && body.errorCode === "conflict.session_active_run";
+}
 export function toDoneFrameResult(body) {
     return {
         status: "failed",

package/dist/http/admission.js

@@ -10,12 +10,12 @@ import * as facts from "../capability-facts.js";
 import { buildDeadToolMatcherRefusal, deadToolMatcherIssue, parseHooksConfig } from "../hooks/hook-runner.js";
 import { judgeRequestWebSearch } from "../plugins/web-search.js";
 import { normalizeApproachNotice, skillToolListOk, skillToolListRefusal, unknownTaskAgentModelRef, validateTaskAgents } from "../spec-fields.js";
-import { isValidCwd, MAX_ADDITIONAL_DIRS, MAX_CWD_CHARS } from "../task-cwd.js";
+import { MAX_ADDITIONAL_DIRS } from "../task-cwd.js";
 import { verifyRoundsFromBody } from "./verify-rounds.js";
 import { skillCarriesRetiredManifest } from "./retired-skill-manifest.js";
 import { resolveDevicePlacementIntent } from "./device-placement.js";
 import { sendError, httpErrorCode } from "./send.js";
-import { WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
+import { ABSOLUTE_HOST_PATH_MAX, isAbsoluteHostPath, WEB_ADMIN_ENV } from "@sema-agent/settings-schema";
 const APPROVAL_REACH_WORDS = APPROVAL_REACH.map((word) => JSON.stringify(word)).join(" / ");
 export const MAX_SKILL_CONTENT_CHARS = 1_048_576;
 export const MAX_SYSTEM_PROMPT_CHARS = 16_384;
@@ -34,8 +34,8 @@ export function validateUserSkills(skills) {
             return "skill.description must be a string";
         if (typeof s["content"] !== "string" || s["content"].length === 0 || s["content"].length > MAX_SKILL_CONTENT_CHARS)
             return `skill.content must be a non-empty string of at most ${MAX_SKILL_CONTENT_CHARS} characters (the engine rejects skills over this size outright at load time)`;
-        if (s["baseDir"] !== undefined && !isValidCwd(s["baseDir"]))
-            return `skill.baseDir must be an absolute path string of at most ${MAX_CWD_CHARS} characters with no ".." segment and no NUL byte (it is not resolved or read here — the engine only substitutes it into the skill's own text)`;
+        if (s["baseDir"] !== undefined && !isAbsoluteHostPath(s["baseDir"]))
+            return `skill.baseDir must be an absolute path string of at most ${ABSOLUTE_HOST_PATH_MAX} characters with no ".." segment and no NUL byte (it is not resolved or read here — the engine only substitutes it into the skill's own text)`;
         if (skillCarriesRetiredManifest(s))
             return SKILL_MANIFEST_RETIRED;
         for (const key of ["allowedTools", "disallowedTools"]) {
@@ -103,7 +103,7 @@ export function createAdmission(ctx) {
                 return null;
             }
         }
-        if (body.cwd !== undefined && !isValidCwd(body.cwd)) {
+        if (body.cwd !== undefined && !isAbsoluteHostPath(body.cwd)) {
             sendError(res, 400, "request.field_invalid", "cwd must be a non-empty absolute host path");
             return null;
         }
@@ -117,7 +117,7 @@ export function createAdmission(ctx) {
                 sendError(res, 400, "request.field_invalid", `additionalDirectories must have at most ${MAX_ADDITIONAL_DIRS} entries`);
                 return null;
             }
-            const bad = addDirsRaw.find((d) => !isValidCwd(d));
+            const bad = addDirsRaw.find((d) => !isAbsoluteHostPath(d));
             if (bad !== undefined) {
                 sendError(res, 400, "request.field_invalid", "each additionalDirectories entry must be a non-empty absolute host path (no '..' segments)");
                 return null;
@@ -133,7 +133,7 @@ export function createAdmission(ctx) {
                 sendError(res, 400, "request.field_invalid", `additionalReadDirectories must have at most ${MAX_ADDITIONAL_DIRS} entries`);
                 return null;
             }
-            const badRead = addReadDirsRaw.find((d) => !isValidCwd(d));
+            const badRead = addReadDirsRaw.find((d) => !isAbsoluteHostPath(d));
             if (badRead !== undefined) {
                 sendError(res, 400, "request.field_invalid", "each additionalReadDirectories entry must be a non-empty absolute host path (no '..' segments)");
                 return null;

package/dist/http/approval-sweeps.js

@@ -6,6 +6,7 @@ import { APPROVAL_GATE_KINDS } from "../tool-approval.js";
 import { createWallClockJumpGuard } from "../wall-clock-jump-guard.js";
 import { hasServiceAuth } from "./dispatch.js";
 import { gatedPrincipal } from "./principal-gate.js";
+import { costQuotaRefusalOf } from "./request-guards.js";
 import { admissionRefusalOf, readinessOf } from "./readiness.js";
 import { readResumeCtx } from "./resume-ctx-read.js";
 import { storedBodyReplayRefusal } from "./stored-body-replay.js";
@@ -116,10 +117,7 @@ export function createApprovalSweeps(ctx) {
                 const d = deps.costQuota.check(quotaPrincipal);
                 if (!d.allowed) {
                     deps.metrics?.inc("cost_quota_rejected_total");
-                    return {
-                        status: 429,
-                        body: { error: "cost quota exceeded", errorCode: "limit.cost_quota_exceeded", usedMicroUsd: d.usedMicroUsd, limitMicroUsd: d.limitMicroUsd, retryAfterSec: d.retryAfterSec },
-                    };
+                    return costQuotaRefusalOf(d);
                 }
             }
         }

package/dist/http/device-placement.js

@@ -92,6 +92,7 @@ export async function commitPlacement(ctx, runStore, taskId, intent) {
     const releaseRun = async (why) => {
         try {
             await runStore.setTerminal(taskId, "failed", null, why);
+            await runStore.releaseIdemKey(taskId);
         }
         catch (err) {
             ctx.logger?.warn("device_placement_run_release_failed", { taskId, err: err instanceof Error ? err.message : String(err) });

package/dist/http/dispatch.js

@@ -35,7 +35,7 @@ function cors(res, req, origins, principalHeader) {
     if (allow === undefined)
         return;
     res.setHeader("access-control-allow-origin", allow);
-    res.setHeader("access-control-allow-methods", "GET, POST, PUT, DELETE, OPTIONS");
+    res.setHeader("access-control-allow-methods", [...ROUTE_METHOD_ORDER, "OPTIONS"].join(", "));
     res.setHeader("access-control-allow-headers", `content-type, authorization, last-event-id, ${principalHeader}, idempotency-key, x-detach-on-disconnect, ${PRINCIPAL_TOKEN_HEADER}, ${APPROVAL_MAC_HEADER}, ${APPROVAL_MAC_KID_HEADER}, if-none-match`);
     res.setHeader("access-control-expose-headers", "x-task-id, retry-after");
 }

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

@@ -9,12 +9,13 @@
  * 当年从路由体里提取出来时,头注写的就是同一条判词)。方向:`routes/runs.ts` 与 `http/server.ts`
  * 都 import 本模块,本模块谁都不 import —— 与 `http/run-meta.ts` 同一条「两个域共用一件 ⇒ 单独成文件」。
  *
- * 边界(本腿**不**含的东西,留给各自的门):`body.taskId` 幂等重放、`Idempotency-Key` 内存去重、
+ * 边界(本腿**不**含的东西,留给各自的门):同键重放的回执(`http/submit-replay.ts`)、`Idempotency-Key` 的在飞合流、
  * lease / 治理窗 pre-admission、属主门。它们是**提交面**的判据(读请求、写响应),而本腿只吃已经备好的
  * `PreparedTaskSubmission` 并交回一份收据 —— 这正是它能被一条没有 `ServerResponse` 的内部车道复用的原因。
  */
 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 { PreparedTaskSubmission, RouteCtxBase } from "./route-ctx.js";
 /**
  * 🔴 **TRUSTED run internals** —— 由**部署方**(不是模型、不是请求体、不是工具参数)铸给这一跑的
@@ -34,6 +35,8 @@ 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;
     /** 🔒 这条 run 的 **fleet 行 scope** —— 必须与 `GET /v1/fleet/stream` 过滤用的是同一个身份,且绝不是
      *  自报的 `x-agent-principal` 头(自报头会把行打到受害者的 scope 上,或打到 `default` 而真属主的流把它
      *  过滤掉)。提交门传 `gatedPrincipal(req) ?? "default"`;`/decide` 的第三条车道传 resume 家族的
@@ -49,16 +52,27 @@ export interface DurableRunLegArgs {
     trustedInternals?: TrustedRunInternals;
 }
 /**
- * 建行 + 驱动。返回 `202` = 新行已建并在跑(体带 `taskId`/`sessionId`);`409` = 会话被别的 run 占着,
- * **没有**建行(体 = `buildActiveRunConflict` 的既有形,含 `errorCode: "conflict.session_active_run"`)。
- * 协议渲染归调用方(HTTP `sendJson` / A2A 协议对象 / `/decide` 的受理体)。
+ * 本腿的结局:一份收据,或「这次提交的一把幂等钥匙已经指向一条行」(店的原子赢或观察的**观察**臂 —— 本腿不碰
+ * 请求、不判属主,回执归提交面的唯一回执函数 `replayOfExistingRun`)。另一位在每一形上恒 `undefined`。
  */
-export declare function mintAndDriveDurableRun(ctx: RouteCtxBase, runStore: RunStore, args: DurableRunLegArgs): Promise<{
+export type DurableRunLegOutcome = {
     status: number;
     body: {
         taskId: string;
         sessionId: string;
         status: string;
     } | object;
-}>;
+    existing?: undefined;
+} | {
+    existing: RunRecord;
+    status?: undefined;
+    body?: undefined;
+};
+/**
+ * 建行 + 驱动。返回 `202` = 新行已建并在跑(体带 `taskId`/`sessionId`);`409` = 会话被别的 run 占着,
+ * **没有**建行(体 = `buildActiveRunConflict` 的既有形,含 `errorCode: "conflict.session_active_run"`);
+ * `existing` = 这次提交的钥匙(`idemKey` / `clientTaskId`)已经指向一条行,没建新行。
+ * 协议渲染归调用方(HTTP `sendJson` / A2A 协议对象 / `/decide` 的受理体)。
+ */
+export declare function mintAndDriveDurableRun(ctx: RouteCtxBase, runStore: RunStore, args: DurableRunLegArgs): Promise<DurableRunLegOutcome>;
 //# sourceMappingURL=durable-run-leg.d.ts.map

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

@@ -15,17 +15,16 @@ 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));
+    const created = await runStore.createRun(taskId, sessionId, args.prepared.auth?.principal ?? null, deps.instanceId ?? "default", { ...runMeta(args.prepared, args.source), idemKey: args.idemKey ?? null });
     if (created.ok)
         clearTurnActivity(taskId);
     if (created.ok)
         recordResourceWindow(taskId, args.prepared.spec.resourceSuspend);
     if (created.ok)
         deps.sessionTitler?.maybeTitle(sessionId, args.prepared.spec.objective, typeof args.prepared.spec.model === "string" ? args.prepared.spec.model : args.prepared.spec.model?.id);
+    if (created.existing)
+        return { existing: created.existing };
     if (!created.ok) {
-        if (args.clientTaskId && created.activeTaskId === args.clientTaskId) {
-            return { status: 202, body: { taskId: args.clientTaskId, sessionId, status: "running" } };
-        }
         return { status: 409, body: await buildActiveRunConflict({ runStore, checkpointStore: deps.checkpointStore, governance: deps.config, runStaleSec: deps.config.runStaleSec, turnActivity: readTurnActivityMs }, sessionId, created.activeTaskId) };
     }
     const placementReject = await commitPlacement(deps, runStore, taskId, args.prepared.bindingIntent);
@@ -51,6 +50,7 @@ export async function mintAndDriveDurableRun(ctx, runStore, args) {
         runId: taskId,
         scope: args.fleetScope,
         rootTaskId: taskId,
+        sessionId,
         ...fleetRunLabels(args.prepared.spec.objective),
     });
     void runInBackground(args.prepared.runner, { ...args.prepared.spec, sessionId }, runStore, taskId, deps.metrics, args.prepared.auth?.principal, args.prepared.verify, args.prepared.cascade ? cascadeConfig(deps.config.cascadeLadder, args.prepared.spec.limits?.maxCostUsd) : undefined, deps.instrumentDegenerate, deps.planCacheProbe, deps.config.traceThinking, inflightRuns, preemptableRuns, steerableRuns, deps.modelUsage, deps.elicitation, args.elicitOwner, captureTurnAnchor, fleetPub, captureUserMessageAnchor, deps.question, deps.workflowCompletionInbox, deps.subagentSteerRegistry, (m, x) => deps.logger?.info?.(m, x), deps.sendUserFile, deps.promptManifests, deps.toolApproval

package/dist/http/idempotency.d.ts

@@ -1,65 +1,110 @@
+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";
 /**
- * In-memory, TTL'd dedup cache keyed by an opaque string (an Idempotency-Key).
+ * 同进程的**在飞合流** —— 并发同键的提交共享同一个 promise(避免同一进程里双起)。它**不是**重放的真源。
  *
- * - `run(key, produce, shouldCache?)` invokes `produce` at most once per key — concurrent and retried calls
- *   with the same key await the same promise — and retains a CACHEABLE resolution for `ttlMs` so a later retry
- *   replays it. A rejection (a thrown error billed nothing) or a caller-marked un-cacheable resolution (e.g. a
- *   transient 409) is evicted so a genuine retry re-runs.
- * - `peek(key)` returns the cached (in-flight or settled) promise without producing — letting a caller
- *   short-circuit a retry BEFORE side gates (rate/quota), so the retry gets the same response, not a fresh 429.
- *   An SSE stream wraps its live run in `run()` so the in-flight promise is stored too; a retry then peeks it.
+ * 提交幂等的律:`Idempotency-Key` 的执法点 = 资源行上的 `idem_key` UNIQUE(`task_run` / `leader_run` /
+ * `image_bake`);同键再投 ⇒ 读到那一行 ⇒ 唯一回执函数作答(`http/submit-replay.ts`)。本类只管「那一行还在
+ * 半路上」的那一刻:
  *
- * Per-entry TTL is enforced on access (O(1)); abandoned keys are reclaimed by a sweep that runs only once the
- * map grows past a threshold (no O(n) scan on the hot path). Single-threaded event-loop semantics: each HTTP
- * request is its own task, so there is no get→set race within a tick.
- *
- * (Caller context: the web-admin review gateway mints/echoes the Idempotency-Key and routes a given key to
- * the same worker, so this PER-POD cache is the worker-side backstop against a retried submission re-running —
- * and re-billing. Cross-pod / cross-restart exactly-once needs store-backing; the durable async /v1/runs path
- * is the alternative for long tasks.)
+ * - `run(key, produce)` 对同一个键至多调一次 `produce`;并发的同键调用拿到**同一个** promise(两份同体回执)。
+ *   promise 一落定(成或败)条目即删 —— 之后的同键请求读行,不读这里。于是「同进程重试」与「跨副本 / 重启后
+ *   重试」读的是同一张账、拿到的是同一种回执,不存在「15 分钟内回缓存体、之后回行」的两个判官。
+ * - `peek(key)` 交出在飞的 promise(不产出)—— 让调用方在副门(rate/quota)**之前**合流,并发的那一条不吃新 429。
+ *   SSE 腿把整条活流包在 `run()` 里,在飞期间到达的同键重试 peek 到它、等它落定。
+ * - TTL 只约束**条目**:一个落不了定的 promise(挂死的腿)最多被合流 `ttlMs`,过期即不再被 peek(之后的同键请求
+ *   去读行)。被遗弃的条目在表长过阈值后才扫(热路径无 O(n))。单线程事件循环语义:同一 tick 内没有 get→set 竞态。
  */
 export declare class IdempotencyCache<T> {
     private readonly ttlMs;
     private readonly sweepThreshold;
     private readonly entries;
     constructor(ttlMs?: number, sweepThreshold?: number);
-    /** Live (un-expired) cached promise for a key, or undefined — without producing. */
+    /** 在飞(未过 TTL)的 promise,或 undefined —— 不产出。 */
     peek(key: string): Promise<T> | undefined;
-    run(key: string | undefined, produce: () => Promise<T>, shouldCache?: (value: T) => boolean): Promise<T>;
+    run(key: string | undefined, produce: () => Promise<T>): Promise<T>;
     get size(): number;
-    /** Return the cached promise if present AND within the TTL; drop it and return undefined if expired. */
+    /** Return the in-flight promise if present AND within the TTL; drop it and return undefined if expired. */
     private live;
     /** Reclaim expired entries only once the map is large — avoids an O(n) scan on every call (council). */
     private maybeSweep;
 }
 /**
- * Namespace an Idempotency-Key by the authenticated identity (BL-3). The dedup cache is one per process; keying
- * it on the RAW client header let a different tenant (or anonymous caller) replaying the same key receive the
- * FIRST caller's response and skip the rate/quota gates. Folding the credential-derived `source` + the
- * `principal` into the key scopes a replay to the SAME caller only — cross-tenant collisions become cache
- * misses (re-run, correctly attributed). `\x1f` (unit separator) can't occur in an HTTP header value, so the
- * three fields can't be confused. undefined raw key → undefined (no dedup, unchanged).
+ * `Idempotency-Key` 的**资源族**闭集 —— 键的作用域里那一位是**资源族,不是端点**。
+ *
+ *  · `run`    —— 一条 run(`POST /v1/tasks` · `/v1/tasks/stream` · `/v1/runs` · A2A `message/send` 都建同一种行;
+ *                同一条 run 换腿重试仍同键,不会重复计费)。同族的两个动词口(`/v1/runs/:id/steer` · `/interrupt`)
+ *                也按本族取键,收成引擎的 `inputId`(它们的去重属主是引擎的输入队列,不是本仓的行)。
+ *  · `leader` —— 一条 leader run(`leader_run.idem_key`)。
+ *  · `bake`   —— 一次镜像烘焙(`image_bake.idem_key`)。
+ *
+ * 跨族同一个原始键**互不命中**(它们是不同资源表上的不同行)。
+ */
+export type IdemFamily = "run" | "leader" | "bake";
+/**
+ * 一次提交的**调用方身份**(幂等的作用域就是它)—— 授权口建立的那两样:验过的 principal(`gatedPrincipal`)与凭据族
+ * (`source`:鉴权门由出示的服务凭据派生的系统名,`RouteRequestState.source` 是它唯一的赋值点)。由 {@link idemCallerOf}
+ * 从请求一处读出;键里用的那一位由 {@link idemIdentityOf} 一处定。
+ */
+export interface IdemCaller {
+    readonly principal: string | null | undefined;
+    readonly source: string | null | undefined;
+}
+/** 本次请求的 {@link IdemCaller} —— 一处读:验过的 principal + 鉴权门派生的凭据族(两样都是既有的席位,这里不另判身份)。 */
+export declare function idemCallerOf(req: IncomingMessage, ctx: {
+    readonly deps: {
+        readonly config: ServiceConfig;
+    };
+    readonly req: {
+        readonly source: string | null;
+    };
+}): IdemCaller;
+/**
+ * 幂等的**身份位** —— 一条规则:`principal ?? source`。有验过的 principal 用 principal;没有 principal 用凭据族(按系统令牌区分的
+ * 多系统部署,请求都不带 principal);两者皆无 ⇒ 空(无凭据的单租部署)。两位调用方用同一个原始键得到两把不同的键 —— 不给跨租户
+ * 预言机,也不让 B 的提交被 A 的行吞掉。同一次提交的两把钥匙(`idem_key` 与 A2A 派生的 taskId)都吃这一位,作用域相同。
+ * 编码带种类字:principal 与凭据族是两个命名空间(一个叫 `sysA` 的 principal 与凭据族 `sysA` 不共用键空间)。
+ */
+export declare function idemIdentityOf(caller: IdemCaller): string;
+/**
+ * 提交幂等键的**唯一**铸法:`sha256(身份位 ␟ family ␟ raw)` 的 hex(定宽 64)。
+ *
+ * - 身份位 = {@link idemIdentityOf}(`principal ?? source`)。
+ * - `family` = 资源族({@link IdemFamily}),不是端点。
+ * - 定宽 hash:落库列是 `VARCHAR(64)`,原始键与身份的长度上界都不进列宽;库里也不留调用方的原始键字面量。
+ *   `\x1f`(单元分隔符)不可能出现在 HTTP 头值里,三段不会互相串位。
+ */
+export declare function idemKeyOf(raw: string, caller: IdemCaller, family: IdemFamily): string;
+/**
+ * 在飞合流的键 = 提交幂等键 × 这条腿的**回执形**(`durable` / `sync`)× 这次请求自带的 taskId。
+ *
+ * 合流交出的是**首个请求那条腿的结局**,所以只有「同一条 run、同一种回执形、同一把 taskId」的请求才许合流:durable 腿
+ * 合到同步腿的在飞结局上会拿到 200 引擎结果而不是 202 收据;带另一个 taskId 的请求合进来就绕过了「key 指向别的行」
+ * 那条 409。形不同(或 taskId 不同)的请求各自走到建行,由店的原子赢或观察 + 唯一回执函数作答 —— 仍是一条 run,
+ * 各拿自己腿的回执形。同步腿与流式腿同形(流式腿把同一份体放进 `done.result`),合流照旧。
  */
-export declare function scopedIdempotencyKey(raw: string | undefined, source: string | null, principal: string | undefined): string | undefined;
+export declare function inflightKeyOf(idemKey: string, face: SubmitReplayFace, clientTaskId?: string): string;
 /**
- * 提交腿的**运行结局**(进幂等缓存的那一只)—— `status` + `body` 是它一直以来的两位;S-528 起多一位
+ * 提交腿的**运行结局**(在飞合流共享的那一只)—— `status` + `body` 是它一直以来的两位;S-528 起多一位
  * `wiringManifest`。
  *
- * 🔴 **为什么回执挂在 outcome 上、不铸进 `body`**(codex 对抗复审 [medium],红先复现后修):
- * `Idempotency-Key` 的作用域是 `(credential source, principal, raw key)`,**不含端点** —— 同一个 key 先
- * 走 `/v1/tasks/stream`、再走 `/v1/tasks`,命中的是前者缓存的那份体。回执若铸在同步腿的体里,这条
- * **确实产了帧**的 run 在非流式面上就成了「键缺席」,而 present-iff 的读法会把它读成「这台引擎不给
- * 回执」。挂在 outcome 上 = 它是**这条 run 的属性**(哪条腿跑的都一样),由各腿自己的应答构造器在
- * 送出那一刻按自己的 wire 形挂。拆缓存键也能消歧,但那会让换腿的重试**重复计费** —— 比缺一个键坏。
+ * 🔴 **为什么回执挂在 outcome 上、不铸进 `body`**(codex 对抗复审 [medium],红先复现后修):在飞合流按资源族
+ * `run` 取键(`idemKeyOf`),同一条 run 的几条提交腿同族 —— 同一个 key 先走 `/v1/tasks/stream`、在它**还在跑**时
+ * 再走 `/v1/tasks`,合流到的是前者的那份结局。回执若铸在同步腿的体里,这条**确实产了帧**的 run 在非流式面上
+ * 就成了「键缺席」,而 present-iff 的读法会把它读成「这台引擎不给回执」。挂在 outcome 上 = 它是**这条 run 的
+ * 属性**(哪条腿跑的都一样),由各腿自己的应答构造器在送出那一刻按自己的 wire 形挂。
+ * 落定之后的同键重放不走这里:它读行,体是 run 行读面 + `replay: true`(`http/submit-replay.ts`)—— 回执是起手那一帧
+ * 的活捕获、不落行,所以重放体上**不带** `wiringManifest`(`replay: true` 就是那一形的判别位)。
  *
- * 🔴 **租户面安全(别在复审里当成漏)**:缓存的那份回执是按**第一位调用方**的 `explicitOperatorOk` 投的,
- * 而键本身就按 `principal` 分区(`scopedIdempotencyKey`)⇒ 命中它的只可能是**同一个** principal,同一份
- * 部署 operator 名单下求值恒同 ⇒ operator 面不可能经重放落到租户手里。跨租户同 key 是**缓存未命中**
- * (各自重跑、各自归账),这一位从 BL-3 起就是这么设计的。
+ * 🔴 **租户面安全(别在复审里当成漏)**:合流的那份回执是按**第一位调用方**的 `explicitOperatorOk` 投的,
+ * 而键本身就按身份位分区(`idemKeyOf` 的 `principal ?? source`)⇒ 合流到它的只可能是**同一个** principal(无 principal 时
+ * 是同一个凭据族,两边的 `explicitOperatorOk` 都是假),同一份部署 operator 名单下求值恒同 ⇒ operator 面不可能经合流落到
+ * 租户手里。跨租户 / 跨系统同 key 是**不同的键**(各自重跑、各自归账),这一位从 BL-3 起就是这么设计的。
  *
  * 对照:同一条 200 体上的 `notice` 仍铸在 `body` 里,因为它说的是**本次请求**带没带 verify/cascade
- * (重放腿在 `prepareSpec` 之前就答了,结构上不知道这件事);回执说的是**那条 run**。两者的归属不同,
+ * (合流腿在 `prepareSpec` 之前就答了,结构上不知道这件事);回执说的是**那条 run**。两者的归属不同,
  * 不是可以统一的两处写法。
  */
 export interface SubmitOutcome {