@sema-agent/server 7.103.2 → 7.104.0

package/dist/file-history-capture.d.ts

@@ -1,35 +1,41 @@
 /**
- * S-589 —— 文件历史的**装配单点**与能力词 `fileHistoryCapture` 的闭集(叶模块:只 type-import store-backend)。
+ * S-589 → S-724 —— 文件历史的**装配单点**与能力词 `fileHistoryCapture` 的闭集(叶模块:只 type-import store-backend 与 core 型)。
  *
- * ## 病(修前)
- * `boot/budget-tracing.ts` 只要后端有文件历史店就无条件交给 core(`RunnerDeps.fileHistoryStore`)。core 的首次触碰
- * 捕获是**进程级**的:接了店就恒捕获,没有任何单会话 / 单 run 的杠杆;全仓相关旋钮只有保留条数
- * `FILE_HISTORY_RETENTION_KEEP`。于是用户在客户端关掉「文件检查点」关掉的只是提示,文件字节照旧进
- * `file_history_*` —— 隐私 / 留存轴上的用户面语义谎言。
+ * ## 病史
+ * S-589(7.97.0):`boot/budget-tracing.ts` 只要后端有文件历史店就无条件交给 core(`RunnerDeps.fileHistoryStore`)。core 的首次
+ * 触碰捕获当时是**进程级**的:接了店就恒捕获,没有任何单会话 / 单 run 的杠杆。于是用户在客户端关掉「文件检查点」关掉的只是
+ * 提示,文件字节照旧进 `file_history_*`。S-589 给了部署旋钮 `FILE_HISTORY_CAPTURE`,而 core 那时只有一种写法表达「不捕获」——
+ * **不接店** ⇒ 旋钮关 = 摘店,代价是已存历史也一起读不了(restore / rewind / 2c sync 一并关)。
+ * S-724(7.104.0):core 7.31.0 收了两件 —— 部署的**捕获位** `RunnerDeps.fileHistoryCapture: "off"`(店照接,只停新捕获,
+ * 已存历史照常服务 `restoreFiles` / `rewindFilesTo`)与请求级关断词 `TaskSpec.fileHistory: "disabled"`。旋钮改落 core 的同名座:
+ * **名字说的是「捕获」,就只关捕获** —— 一条旋钮一个意思。
  *
- * ## 一处判定,两张脸(按动词类别切分,不是特例)
- * 「这台部署有没有文件历史店」只在 {@link assembleFileHistory} 判一次,部署旋钮 `FILE_HISTORY_CAPTURE` 在这一处合取:
- *  · **捕获脸** `store` = 后端 ∧ 旋钮。喂 core 的首次触碰捕获(`RunnerDeps.fileHistoryStore`)、rewind 族能力位
- *    (`rewindFiles` / `restoreFiles` / `rewindFilesTo` / `sessionSync`)与本模块的能力词、2c sync 路由族。
- *  · **擦除脸** `erasure` = 后端在即在,类型上**只有删除类动词**。喂 E21 在线删除(`boot/session-faces.ts`)与
- *    孤儿 blob GC(`boot/reapers.ts`)。
- * 规则一句话:**旋钮只管写入,从不管擦除**。关掉捕获的部署照样要能删掉已经捕获的文件字节 —— 否则翻旋钮之后
- * `DELETE /v1/sessions/:id` 会回成功却把存量文件内容留在库里,而留存车道(`plugins/retention-store-sql.ts` 的
- * 原生 SQL 删六张 `file_history_*` 表,本来就不看店在不在)与在线删除从此不再等价(E21 两个执行体分家)。
- * ⚠️ 关掉 ≠ 删掉:翻旋钮**不**做任何批量删除。已捕获的历史照既有的会话删除 / 留存规则清理;在旋钮关着的
- * 部署上它也不会再被读用(rewind / restore / sync 都随捕获脸一起缺席)。
+ * ## 两件事,两个单点
+ *  · 「这台部署有没有文件历史店」只在 {@link assembleFileHistory} 判一次(后端在即在,**与旋钮无关**),产出两张脸:
+ *    **店** `store` 喂 core 的 `RunnerDeps.fileHistoryStore`(还原族)、rewind 族能力位(`rewindFiles` / `restoreFiles` /
+ *    `rewindFilesTo` / `sessionSync`)与 2c sync 路由族;**擦除脸** `erasure` = 店的**只有删除类动词**的收窄视图,喂 E21 在线删除
+ *    (`boot/session-faces.ts`)与孤儿 blob GC(`boot/reapers.ts`)。旋钮从不管擦除:关掉捕获的部署照样要能删掉已捕获的文件字节。
+ *  · 「捕不捕」只在 {@link fileHistoryCaptureOf} 判一次(纯函数,输入 = 店在不在 + 旋钮)。两个消费点喂它同一组输入:
+ *    core 的部署捕获位({@link coreFileHistoryCaptureSeat},`boot/runner-deps.ts`)与能力词(`http/routes/capabilities.ts`)——
+ *    core 收到的与能力面说的不可能各说各话。捕获位 `"off"` ⟺ 店在 ∧ 旋钮关;**没有店的部署形不下发**该位:core 对
+ *    「off 但没店」拒 prepare(`config.invalid_file_history_capture`,「nothing to switch off」),而旋钮的意思「不捕获」在没店的
+ *    部署上本来就成立 —— 旋钮照样无条件生效,只是那一形无事可关(选这一臂而不是拒启的理由见 CHANGELOG 7.104.0 S-724 条:
+ *    拒启会把「形合法、意思成立」的配置判成错,且会与 auto 后端的降级臂耦合)。
+ * ⚠️ 关掉 ≠ 删掉:翻旋钮**不**做任何批量删除;已捕获的历史照旧被 restore / rewind / sync 读用,按既有的会话删除 /
+ * 留存规则清理。要让已存历史也不可用,部署今天的出路只有逐会话 `DELETE /v1/sessions/:id` 与留存清扫(见 USAGE)。
  *
- * ## 能力词为什么是闭集两词、没有 `on-optional`
- * cli 要的是「`/config` 那个开关该不该出现」。present-iff 布尔在今天的**每一台**部署上都只能回答「关不掉」
- * (core 的捕获是进程级的)⇒ 出一格三词闭集的前两词:`off`(这台部署根本不捕获,也没有 rewind)与
- * `on-always`(捕获中,且无法按会话关闭)。第三词 `on-optional`(「本会话可以不捕获」)要等 core 收一个
- * 单会话 / 单 run 的不捕获位,**在那之前刻意留空**:预先声明一个结构上不可达的词,等于给客户端一个永远等不到的分支。
+ * ## 能力词为什么是 `off` / `on-optional` 两词
+ * cli 要的是「`/config` 那个开关该不该出现」。三词闭集的设计(S-589)是 `off` / `on-always` / `on-optional`;S-589 时第三词
+ * 结构上不可达(没有单 run 不捕获位)。S-724 起请求词 `fileHistory: "disabled"` 受理 ⇒ 捕获中的部署恒可按 run 关掉 ⇒
+ * `on-optional` 成真,而 `on-always`(「捕获中且关不掉」)**结构上不可达** —— 预先声明一个到不了的词等于给客户端一个
+ * 永远等不到的分支,所以删词不留(7.97.0–7.103.x 的 worker 仍会发它,消费端读法在契约附录 B)。
  */
+import type { RunnerDeps } from "@sema-agent/core";
 import type { ServiceFileHistoryStore, StoreBackend } from "./plugins/store-backend.js";
 /** 能力词闭集的单点属主(`Record` 锁步:联合加词而这里不补 ⇒ 编译红;词表数组由它派生,不手抄)。 */
 declare const FILE_HISTORY_CAPTURE_WORD_SET: {
     readonly off: true;
-    readonly "on-always": true;
+    readonly "on-optional": true;
 };
 /** `GET /v1/capabilities` 的 `fileHistoryCapture` 词。 */
 export type FileHistoryCapture = keyof typeof FILE_HISTORY_CAPTURE_WORD_SET;
@@ -41,25 +47,26 @@ export declare const FILE_HISTORY_CAPTURE_WORDS: readonly FileHistoryCapture[];
 export type FileHistoryErasureFace = Pick<ServiceFileHistoryStore, "reap" | "deleteBySession" | "sweepOrphanBlobs">;
 /** 装配结果:两张脸。 */
 export interface FileHistoryAssembly {
-    /** 捕获脸:在场 ⟺ 后端在 ∧ `FILE_HISTORY_CAPTURE`。 */
+    /** 店:在场 ⟺ 后端在(与旋钮无关)。 */
     readonly store: ServiceFileHistoryStore | undefined;
-    /** 擦除脸:在场 ⟺ 后端在(与旋钮无关)。 */
+    /** 擦除脸:在场 ⟺ 后端在(与旋钮无关;是 {@link store} 的删除类动词视图)。 */
     readonly erasure: FileHistoryErasureFace | undefined;
 }
+/** 装配:「这台部署有没有文件历史店」的唯一判定。旋钮不在这里 —— 它只关捕获,不摘店(S-724)。 */
+export declare function assembleFileHistory(backend: StoreBackend | undefined): FileHistoryAssembly;
 /**
- * **唯一**的装配判定。`capture` = 部署旋钮 `FILE_HISTORY_CAPTURE`(`config.fileHistoryCapture`)。
+ * 「捕不捕」的**唯一**判定(纯函数):能力词。`store` = 装配出来的店(在不在),`knob` = 部署旋钮 `FILE_HISTORY_CAPTURE`
+ * (`config.fileHistoryCapture`)。从**装配结果**派生,不照旋钮字面回声:后端本来就没有这只店的部署同样是 `off`。
  *
- * 形照 `execution-lane-caps.ts` 的穷举 switch(无 default 臂):意图词加一个(将来的 `on-optional`)而这里不加臂
- * ⇒ 编译红 —— 加臂的那一刻就是决定「这一词下捕获脸接不接、core 那一位单会话不捕获位怎么递」的地方。
+ * 与 `rewindFiles` 分叉(S-589 当时写下的分叉条件,自本版成真):本词答「这台部署捕不捕、能不能按 run 关掉」,
+ * `rewindFiles` 答「这台部署能不能还原」—— 旋钮关的部署本词 `off` 而 `rewindFiles` 仍为真。
  */
-export declare function assembleFileHistory(backend: StoreBackend | undefined, capture: boolean): FileHistoryAssembly;
+export declare function fileHistoryCaptureOf(store: object | undefined, knob: boolean): FileHistoryCapture;
 /**
- * 能力词 = 捕获脸在不在(读**装配结果**,不照旋钮字面回声:后端本来就没有这只店的部署同样是 `off`)。
- *
- * 与 `rewindFiles` 读的是**同一个判定**(`deps.fileHistoryStore` 在场),今天两位同构。分叉条件(写在这里免得
- * 将来有人把两位当成一回事):core 收了单会话不捕获位之后,本词在捕获脸在场时会变成 `on-optional`,而
- * `rewindFiles` 仍是 true —— 它回答的是「这台部署能不能还原」,本词回答的是「捕获关不关得掉」。
+ * core 的部署捕获位 `RunnerDeps.fileHistoryCapture`,由 {@link fileHistoryCaptureOf} 派生(同一组输入、同一只判定)。
+ * 形照 `execution-lane-caps.ts` 的穷举 switch(无 default 臂):能力词加一个而这里不加臂 ⇒ 编译红 —— 加臂的那一刻就是
+ * 决定「这一词下 core 的捕获位怎么递」的地方。没有店 ⇒ 恒 `undefined`(core 对「off 但没店」拒 prepare)。
  */
-export declare function fileHistoryCaptureOf(captureFace: object | undefined): FileHistoryCapture;
+export declare function coreFileHistoryCaptureSeat(store: object | undefined, knob: boolean): RunnerDeps["fileHistoryCapture"];
 export {};
 //# sourceMappingURL=file-history-capture.d.ts.map

package/dist/file-history-capture.js

@@ -1,21 +1,26 @@
 const FILE_HISTORY_CAPTURE_WORD_SET = {
     off: true,
-    "on-always": true,
+    "on-optional": true,
 };
 export const FILE_HISTORY_CAPTURE_WORDS = Object.keys(FILE_HISTORY_CAPTURE_WORD_SET);
-export function assembleFileHistory(backend, capture) {
+export function assembleFileHistory(backend) {
     if (backend === undefined)
         return { store: undefined, erasure: undefined };
     const physical = backend.fileHistory();
-    const intent = capture ? "on-always" : "off";
-    switch (intent) {
+    return { store: physical, erasure: physical };
+}
+export function fileHistoryCaptureOf(store, knob) {
+    return store !== undefined && knob ? "on-optional" : "off";
+}
+export function coreFileHistoryCaptureSeat(store, knob) {
+    if (store === undefined)
+        return undefined;
+    const word = fileHistoryCaptureOf(store, knob);
+    switch (word) {
         case "off":
-            return { store: undefined, erasure: physical };
-        case "on-always":
-            return { store: physical, erasure: physical };
+            return "off";
+        case "on-optional":
+            return undefined;
     }
 }
-export function fileHistoryCaptureOf(captureFace) {
-    return captureFace === undefined ? "off" : "on-always";
-}
 //# sourceMappingURL=file-history-capture.js.map

package/dist/http/admission.d.ts

@@ -29,11 +29,18 @@ export declare const MAX_OUTPUT_SCHEMA_CHARS = 32768;
  *  · `skill.description must be a string of at most 1024 characters`(描述长度帽);
  *  · `skill.name must be a non-empty string of at most 64 characters` 里的 **长度**那一半。
  *
- * 退役的判据是**上游两侧都没有同形门**:CC 2.1.259 的技能清单渲染(`cli259.js:23195` 的预算算法)
- * 在超预算时把**描述裁短**、再不够就退成 name-only,**从不**因为条数多或描述长而拒掉一条技能;
- * 它的 `Ir()` 名字校验也只判非空 / 无配对代理 / 无首尾空白 / 无括号逗号控制字符,没有长度帽。
+ * 退役的判据是**上游两侧都没有同形门**:CC 的技能清单渲染**从不**因为条数多或描述长而拒掉一条技能 —— 超预算时每一条
+ * 只有两种结局:全文,或退成 name-only(`- name`);bundled 技能恒为全文,其余按优先级在剩余预算内贪心升回全文
+ * (cli280.js:217940-217942 `JBt`;预算 = `max(1, floor((窗口 ?? 200000) × bytesPerToken(缺省 4)× fraction))`,
+ * env `SLASH_COMMAND_TOOL_CHAR_BUDGET` 优先,cli280.js:215920 `nUe`)。单条描述超过 `skillListingMaxDescChars`(默认 1536)
+ * 截成前 1535 字符加「…」,这一截与预算无关、恒生效(cli280.js:217940 `NFr`)。旧引的 `cli259.js:23195` 是 `skillListingBudgetFraction` 的 settings describe 文案,
+ * 不是算法本体。CC 的技能名校验(2.1.259 `Ir()` / 2.1.280 `Rs()`,cli280.js:236381;校验的是 Agent SDK `skills` 选项里的
+ * 技能名)判非空、无未配对代理、无首尾空白、无括号逗号控制字符、不是 `'*'`、无通配后缀、不以 `/` 开头、无连续反斜杠、
+ * 不以反斜杠结尾 —— **没有长度这一条**;CC 的名字长度界在别的面上且都不是 64:forked skill 作用域持久化 256
+ * (cli280.js:214671 `BV`)、transcript 载入(resume)时 `skill_listing.names` 每条 ≤ 512 / 至多 4096 条,不合格整条附件丢弃
+ * (cli280.js:217865)。
  * 引擎侧同理:唯一整拒的是 1 MiB 的单技能加载门。于是那三条帽是「装了 11 个技能就 400」这种
- * 纯本仓面的伤——收益是零(预算由渲染侧按字节兜),代价是用户装不进自己的技能库。
+ * 纯本仓面的伤——收益是零(预算由渲染侧兜),代价是用户装不进自己的技能库。
  *
  * **补偿**(三问的第三问):`settings.skillListingBudgetFraction` / `settings.skillListingMaxDescChars`
  * 两个旋钮直达引擎的渲染预算(per-turn 成本的真属主)。

package/dist/http/admission.js

@@ -4,7 +4,7 @@ import { modelUnavailableMessage } from "../model-entry-refusal.js";
 import { HttpError } from "../security.js";
 import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, MAX_SETTINGS_PERMISSION_RULES, MAX_SETTINGS_ENV_VARS, MAX_SETTINGS_ENV_KEY_CHARS, MAX_SETTINGS_ENV_VALUE_CHARS, SETTINGS_PERMISSION_MODE_WORDS, isSettingsPermissionMode, parseTaskSettings, skillListingBudgetFractionOk, skillListingMaxDescOk, taskSettingsKeyIssue } from "../task-settings.js";
 import { taskBodyKeyIssue } from "../request-key-closure.js";
-import { singleMemberOffFieldIssue } from "../request-value-closure.js";
+import { FILE_HISTORY_DISABLED_NO_RESTORE, fileHistoryRestoreConflict, singleMemberOffFieldIssue } from "../request-value-closure.js";
 import { selfOrchestrationDenial } from "../task-workflow.js";
 import { centerEntitlementSourceWired } from "../runtime-caps-resolver.js";
 import { parseHooksConfig } from "../hooks/hook-runner.js";
@@ -333,6 +333,10 @@ export function createAdmission(ctx) {
                 return null;
             }
         }
+        if (fileHistoryRestoreConflict(body)) {
+            sendError(res, 400, "request.field_conflict", FILE_HISTORY_DISABLED_NO_RESTORE);
+            return null;
+        }
         if (body.requireExistingSession !== undefined && typeof body.requireExistingSession !== "boolean") {
             sendError(res, 400, "request.field_invalid", "requireExistingSession must be a boolean");
             return null;

package/dist/http/dispatch.js

@@ -6,7 +6,7 @@ import { ROUTE_METHOD_ORDER } from "./route-ctx.js";
 import { PRE_CREDENTIAL_ROUTES, POST_CREDENTIAL_ROUTES, routeLabel, isBillableSubmitPath, isCredentialGatedRewrite, isMethodDispatchedSubmitPath, lookupRoute, isProbePath } from "./route-table.js";
 import { sendJson, sendError, isSseResponse } from "./send.js";
 import { readinessOf, healthReadinessKeys, sendReadyz, billableRefusalOf, sendBillableRefusal } from "./readiness.js";
-import { authorized, systemFor, gatedPrincipal, sendPrincipalRefusal } from "./principal-gate.js";
+import { authorized, systemFor, gatedPrincipal, sendPrincipalRefusal, sendUnauthorized } from "./principal-gate.js";
 const PROCESS_STARTED_AT_MS = Date.now() - Math.round(process.uptime() * 1000);
 export function hasServiceAuth(config) {
     return Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
@@ -175,7 +175,7 @@ export function createDispatch(ctx) {
             const devOpen = !anyT && !mt && !deps.config.requirePrincipal;
             const ok = devOpen || (anyT && systemFor(req, deps.config) !== undefined) || (!!mt && authorized(req, mt));
             if (!ok) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "operator");
                 return;
             }
             if (url === "/metrics/summary") {
@@ -215,7 +215,7 @@ export function createDispatch(ctx) {
                     source = "sso";
                 }
                 else {
-                    sendError(res, 401, "auth.unauthorized", "unauthorized");
+                    sendUnauthorized(res, "credential");
                     return;
                 }
             }

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

@@ -44,6 +44,28 @@ export declare function principalTokenPresentedButUnverified(req: IncomingMessag
  * 调用链上的**证明三件套**,与本门(身份面)是两道门。
  */
 export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingMessage, config: ServiceConfig): void;
+/**
+ * 🔴 **`401 auth.unauthorized` 的唯一铸点**(S-850,7.104.0;test [ref] QA 7a C15)。
+ *
+ * 病:十六处路由(9 个文件)各自手抄同一个 401 —— 码 `auth.unauthorized`、message 就一个词 `unauthorized`。照 sema-up 部署、壳接上
+ * 引擎后,第一句就撞上它,不说要哪份凭据、放哪、去哪拿。
+ *
+ * 规则:码不变;message 按**这道门收什么**分三面(闭集 {@link UnauthorizedFace},穷举 switch —— 加一面不接句子 = 编译红),
+ * 每面一句模块级常量(冻结门按常量解引用逐字钉)。三句都**不含任何值**(令牌 / 头名 / 路径实参一概不回显),且**不区分**
+ * 「没带」与「带错」—— 同一道门上两者逐字同体,区分就是探测面。
+ *  · `credential` —— 全局凭据门(`dispatch.ts`):部署配了 service token,请求没带或带的不认(registry 登录令牌验不过同属此面);
+ *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):service token 开得了,指标口另认只读的
+ *    `METRICS_TOKEN`(它在全局门之前判);
+ *  · `identity` —— 过了凭据门(或这台部署没配 service token)、但这一口要一个**验过的调用方身份**:属主寻址的读 / 写面、规则面、
+ *    记忆面。在配了 service token 的部署上,「带 service token 却没身份」只会落在只认身份的口(规则 / 记忆 / 会话策略)上 ——
+ *    这时再叫调用方「去带 service token」是假出路,所以这一面的句子只讲身份。
+ * `auth.principal_required` / `principal_unverified`(上面 {@link sendPrincipalRefusal})是另一只码、另一只铸点,不在此列。
+ */
+export type UnauthorizedFace = "credential" | "operator" | "identity";
+export declare const UNAUTHORIZED_CREDENTIAL = "unauthorized \u2014 the request carries no credential this deployment accepts: send the deployment's service token as a Bearer token in the Authorization header (its operator set it as SERVICE_AUTH_TOKEN or SERVICE_AUTH_TOKENS; a sema-up deployment keeps SERVICE_AUTH_TOKEN in ~/.sema-up/<project>/.env on the machine that ran sema-up)";
+export declare const UNAUTHORIZED_OPERATOR = "unauthorized \u2014 this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header (the metrics endpoints also accept the read-only METRICS_TOKEN)";
+export declare const UNAUTHORIZED_IDENTITY = "unauthorized \u2014 this endpoint acts for a named caller and the request carries no caller identity this deployment verifies: identify the caller the way this deployment does (a registry sign-in token as the Bearer token, a signed principal token on a direct-door deployment, or the principal header set by a trusted front end)";
+export declare function sendUnauthorized(res: ServerResponse, face: UnauthorizedFace): void;
 /**
  * 🔴 **「这个调用方读得到这一行 run 吗」的唯一谓词**(S-297 抽取;此前只活在 `server.ts runOwnerOk` 的
  * 函数体里,而 `runOwnerOk` 把**判断**与**404 怎么发**焊在一起 —— 于是任何需要同一条判断但不想 404 的

package/dist/http/principal-gate.js

@@ -65,6 +65,26 @@ export function sendPrincipalRefusal(res, req, config) {
     }
     sendError(res, 401, "auth.principal_required", `missing principal header '${config.principalHeader}'`);
 }
+export const UNAUTHORIZED_CREDENTIAL = "unauthorized — the request carries no credential this deployment accepts: send the deployment's service token as a Bearer token in the Authorization header (its operator set it as SERVICE_AUTH_TOKEN or SERVICE_AUTH_TOKENS; a sema-up deployment keeps SERVICE_AUTH_TOKEN in ~/.sema-up/<project>/.env on the machine that ran sema-up)";
+export const UNAUTHORIZED_OPERATOR = "unauthorized — this endpoint is for the deployment's operators and the request carries no operator credential: send the deployment's service token as a Bearer token in the Authorization header (the metrics endpoints also accept the read-only METRICS_TOKEN)";
+export const UNAUTHORIZED_IDENTITY = "unauthorized — this endpoint acts for a named caller and the request carries no caller identity this deployment verifies: identify the caller the way this deployment does (a registry sign-in token as the Bearer token, a signed principal token on a direct-door deployment, or the principal header set by a trusted front end)";
+export function sendUnauthorized(res, face) {
+    switch (face) {
+        case "credential":
+            sendError(res, 401, "auth.unauthorized", UNAUTHORIZED_CREDENTIAL);
+            return;
+        case "operator":
+            sendError(res, 401, "auth.unauthorized", UNAUTHORIZED_OPERATOR);
+            return;
+        case "identity":
+            sendError(res, 401, "auth.unauthorized", UNAUTHORIZED_IDENTITY);
+            return;
+        default: {
+            const unknownFace = face;
+            throw new Error(`sendUnauthorized: unknown face ${String(unknownFace)}`);
+        }
+    }
+}
 export function runOwnerReadable(principal, owner, config) {
     if (owner === null)
         return true;

package/dist/http/resume-legs.js

@@ -2,6 +2,9 @@ import { redactErrorMessage, redactHead } from "../observability/run-terminal.js
 import { createHash } from "node:crypto";
 import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, taskNotificationDedupKey, validatePendingSteer, GLOBAL_USAGE_KEY, PAUSE_REGISTRY } from "@sema-agent/core";
 import { decideParkedAgent, denyWorkflowParksUnreadable, findParkOrigin, planWorkflowParkedDecide } from "../parked-decide.js";
+const sessionFaceUnavailable = async (sessionId) => {
+    throw new Error(`parked decide cannot verify which occupant session ${sessionId} belongs to: this deployment's session store has no sessionFaceOf read (every built-in store has one) — refusing rather than resuming unverified`);
+};
 import { HttpError, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE } from "../security.js";
 import { evictIfConflict, parkToolCallId, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
 import { failureCodeOf, nestedPauseOf, sealResultForExit, outwardPlane } from "../terminal.js";
@@ -36,6 +39,7 @@ import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflic
 import { commitPlacement, devicePlacementErrorBody } from "./device-placement.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "../approval-content-kind.js";
 import { readResumeCtx, resumeCtxCorruptAnswer } from "./resume-ctx-read.js";
+import { httpErrorCode } from "./send.js";
 function isCheckpointReopenedFailure(r) {
     const code = failureCodeOf(r.terminal);
     return code === "resume.env_failed" || code === "resume.tool_unavailable" || code === "resume.tool_contract_mismatch";
@@ -258,7 +262,7 @@ export function createResumeLegs(ctx) {
                     checkpointStore: cs,
                     registry: defaultTaskRegistry,
                     reviveSurface: parkedSurface,
-                    ...(deps.sessionStorage?.ownerOf ? { sessionOwnerOf: deps.sessionStorage.ownerOf.bind(deps.sessionStorage) } : {}),
+                    sessionFaceOf: deps.sessionStorage?.sessionFaceOf ? deps.sessionStorage.sessionFaceOf.bind(deps.sessionStorage) : sessionFaceUnavailable,
                     ...(deps.parkedKnownAgentTypes ? { knownAgentTypes: deps.parkedKnownAgentTypes } : {}),
                     ...(deps.parkedReviveInheritedGate ? { rebuildInheritedGate: deps.parkedReviveInheritedGate } : {}),
                     ...(deps.logger ? { warn: parkWarn } : {}),
@@ -341,7 +345,7 @@ export function createResumeLegs(ctx) {
                     ok: false,
                     answer: {
                         status: 409,
-                        body: { error: `resume blocked by an admission policy change: ${e.message}`, errorCode: "resume_blocked_by_policy", ...(e.code ? { blockedBy: e.code } : {}), ...(e.extra ?? {}) },
+                        body: { error: `resume blocked by an admission policy change: ${e.message}`, errorCode: "resume_blocked_by_policy", blockedBy: httpErrorCode(e.status, e.code), ...(e.extra ?? {}) },
                     },
                 };
             }
@@ -908,7 +912,7 @@ export function createResumeLegs(ctx) {
                         settleFleet("failed");
                     }
                     else if (retriable) {
-                        await (outcome.gate === "plan_review" ? deps.runStore.setNeedsReview(taskId) : deps.runStore.setSuspended(taskId)).catch(() => undefined);
+                        await (outcome.gate === "plan_review" ? deps.runStore.setNeedsReview(taskId, null) : deps.runStore.setSuspended(taskId, null)).catch(() => undefined);
                         settleFleet(outcome.gate === "plan_review" ? "needs_review" : "suspended");
                     }
                     else {
@@ -973,9 +977,9 @@ export function createResumeLegs(ctx) {
         const resumePlane = outwardPlane(sealed.terminal);
         if (taskId && deps.runStore) {
             if (resumePlane.status === "suspended" || checkpointReopened)
-                await deps.runStore.setSuspended(taskId);
+                await deps.runStore.setSuspended(taskId, sealed.terminal.kind === "paused" ? sealed : null);
             else if (resumePlane.status === "needs_review")
-                await deps.runStore.setNeedsReview(taskId);
+                await deps.runStore.setNeedsReview(taskId, sealed);
             else
                 await deps.runStore.setTerminal(taskId, resumePlane.status, sealed, resumePlane.errorMessage ?? null);
         }

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

@@ -25,10 +25,17 @@
  *  · **能力位同源**:`capabilities.agentRoster` 与这里的 501 谓词是同一个 `deps.backgroundAgentStore`。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+import type { BackgroundAgentRowSummary } from "@sema-agent/core";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 /** 名册窗的扫描上限(与 fleet 的终态窗同姿势:读面要有界)。窗满时回体带 `truncated:true`,
  *  `total` 于是诚实地是「窗内行数」而不是租户全量 —— 一个悄悄封顶的 total 比没有 total 更坏。 */
 export declare const ROSTER_SCAN_LIMIT = 500;
+/**
+ * 后台子代在 wire 上的 **id 投影**(唯一一只):名册行的 `handle` 与 `DELETE /v1/sessions/:id` 的 409
+ * `conflict.session_children_alive` 体里 `remaining[]` 的每一项都经它出门(S-790,裁定 2026-09-28)—— 两个面上
+ * 「同一只子代」必须是同一个串,消费方拿删除答复里的 id 才对得上名册里的行、才能去它运行的地方停它。
+ */
+export declare function rosterAgentId(row: Pick<BackgroundAgentRowSummary, "handle">): string;
 export declare function handleAgentRoster(req: IncomingMessage, res: ServerResponse, match: RouteMatch<AgentRosterRouteId>, ctx: RouteCtx): Promise<void>;
 export declare const AGENT_ROSTER_ROUTES: readonly [{
     readonly id: "agents-roster";

package/dist/http/routes/agents-roster.js

@@ -1,4 +1,5 @@
 import { sendJson, sendError } from "../send.js";
+import { sendUnauthorized } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 export const ROSTER_SCAN_LIMIT = 500;
 const ROSTER_STATUSES = ["running", "parked", "completed", "failed", "killed"];
@@ -18,9 +19,12 @@ const ROSTER_KEY_DISPOSITION = {
     usage: "strip",
 };
 void ROSTER_KEY_DISPOSITION;
+export function rosterAgentId(row) {
+    return row.handle;
+}
 function projectRow(r) {
     return {
-        handle: r.handle,
+        handle: rosterAgentId(r),
         ...(r.name !== undefined ? { name: r.name } : {}),
         ...(r.agentType !== undefined ? { agentType: r.agentType } : {}),
         status: r.status,
@@ -56,7 +60,7 @@ export async function handleAgentRoster(req, res, match, ctx) {
         case "agents-roster": {
             const { fleetWide, gateOwner } = sessionOwnerScope(req);
             if (!fleetWide && gateOwner === null) {
-                sendError(res, 401, "auth.unauthorized", "unauthorized");
+                sendUnauthorized(res, "identity");
                 return;
             }
             const store = deps.backgroundAgentStore;

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

@@ -3,31 +3,59 @@ import type { QuestionAnswer } from "@sema-agent/core";
 import type { CheckpointStoreFull } from "../../plugins/store-backend.js";
 import { type ToolApprovalCoordinator } from "../../tool-approval.js";
 import { type GovernancePosture } from "../../runtime-governance.js";
-import { type RouteCtx, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
+import { type RouteCtx, type RouteDecl, type RouteMatch, type RouteIdsOf } from "../route-ctx.js";
 import { type KeyClosureIssue } from "../../request-key-closure.js";
+/** 族的成员 = 路由表行 id(改名 / 删行 ⇒ 下表的键当场编译红)。 */
+export type DecisionDoorId = Extract<ApprovalsAssistantRouteId, "approval-decide" | "assistant-task-plan-review">;
+/** 一道门的静态描述 —— 只写**这道门自己**的东西;路径、路径段、别门的键一概不在这里写(从来源读)。 */
+export interface DecisionDoor {
+    /** 体的受理集 = 本门的 `*_BODY_DECLARED_KEYS`(那张表的双向编译期门照旧咬着它的类型)。 */
+    readonly accepted: readonly string[];
+    /** `unknown` 桶标签里的门名(「not a <这里> key — check the spelling」)。 */
+    readonly requestNoun: string;
+    /** 拒体引子里「这道门上拼错一个键最贵的后果」那半句(人读;每门一句)。 */
+    readonly costliestTypo: string;
+}
+export type DecisionDoorFamily = {
+    readonly [K in DecisionDoorId]: DecisionDoor;
+};
+/** 「名字是真的、只是不在这个体上」的三族(闭集;加第四族 = 下面 `switch` 编译红)。 */
+type NeighborFamily = "sibling_field" | "path_segment" | "submit_body";
+/** 一个邻键:它属哪一族 + 它在哪儿是真的(wire 路径,可多条)。 */
+interface NeighborKey {
+    readonly family: NeighborFamily;
+    readonly where: readonly string[];
+}
+/** 派生结果里一道门的全部判据(受理集 + 邻键表 + 两句人读)。 */
+export interface DerivedDecisionDoor {
+    readonly accepted: ReadonlySet<string>;
+    readonly neighbors: ReadonlyMap<string, NeighborKey>;
+    readonly requestNoun: string;
+    readonly costliestTypo: string;
+}
+export type DecisionDoorKeyTable = {
+    readonly [K in DecisionDoorId]: DerivedDecisionDoor;
+};
 /**
- * FRESH 决裁面的**顶层**键闭集裁决:受理集之外的键 ⇒ 返回拒体(调用方 400 `request.body_shape`);
- * 全部受理 ⇒ `null`。判据边界与孪生门(`taskBodyKeyIssue` / `taskSettingsKeyIssue`)逐字同一条:
- * **只判键名**(值形校验归各自既有的门,本门零抢话);体本身非对象 ⇒ 本门不判(留给「body must be
- * { decision … }」那道根形门,免得同一个体被两句话抢答)。
- *
- * 🔴 **重放不额外过门**,也不需要:本腿的幂等回放(`decideIdempotentReplay`)重放的是**同一次请求的同一份
- * 体**,它与首决走同一条路由、同一道门;而 checkpoint 的 resume 重建腿根本不读这个体(它读盘上的 body,
- * 走 `resolveSpec` 的宽容层)⇒ 4xx 砖不到任何存量 parked 任务。这与 tasks 面「RESUME 重放不过门」是同一条律
- * 的两种兑现方式:**门只站在人**(或客户端)**现写的那份字节**上。
+ * 回决门族的键闭集判据表 —— **唯一**的派生口(纯函数:同一份族描述 + 同一张路由表 ⇒ 同一张表)。
+ * 生产只在本模块尾调一次(路由表声明在文件尾,见 {@link DECISION_DOOR_KEY_TABLE});测试可以喂一份构造的族
+ * (「给兄弟门受理集加一个假键 ⇒ 本门的 unsupported 集自动多这一键」就是这么钉的)。
+ * 🔴 族两两不交是**前提**不是愿望:同一个键若既是某门的体字段又是某条 URL 的路径段,它的去处就有两个答案
+ * ⇒ 抛(模块加载期 = 启动即炸,不是请求期 500)。
  */
-export declare function decideBodyKeyIssue(raw: unknown): KeyClosureIssue | null;
+export declare function deriveDecisionDoorKeyTable(family: DecisionDoorFamily, routes: readonly RouteDecl[]): DecisionDoorKeyTable;
 /**
- * FRESH 决裁面的**顶层**键闭集裁决:受理集之外的键 ⇒ 返回拒体(调用方 400 `request.body_shape`);
- * 全部受理 ⇒ `null`。判据边界与三个孪生门(`taskBodyKeyIssue` / `taskSettingsKeyIssue` /
- * {@link decideBodyKeyIssue})逐字同一条:**只判键名**(值形校验归各自既有的门,本门零抢话);体本身
- * 非对象 ⇒ 本门不判(留给「body must be { decision … }」那道根形门,免得同一个体被两句话抢答)。
+ * 回决门族**一道门**的顶层键闭集裁决:受理集之外的键 ⇒ 拒体(调用方 400 `request.body_shape`);全部受理 ⇒ `null`。
+ * 判据边界与两个孪生门(`taskBodyKeyIssue` / `taskSettingsKeyIssue`)逐字同一条:**只判键名**(值形校验归各自
+ * 既有的门,本门零抢话);体本身非对象 ⇒ 本门不判(留给「body must be { decision … }」那道根形门,免得同一个体
+ * 被两句话抢答)。
  *
- * 🔴 **重放不额外过门**,也不需要 —— 逐字同 {@link decideBodyKeyIssue} 的同名段:本腿的反重放是
- * 一次性 nonce(S-280),它守的是**同一份现写的字节**;而续跑重建读的是盘上的体、走 `resolveSpec` 的
- * 宽容层 ⇒ 4xx 砖不到任何存量挂起的任务。**门只站在人(或客户端)现写的那份字节上**。
+ * 🔴 **重放不额外过门**,也不需要:`/decide` 的幂等回放(`decideIdempotentReplay`)重放的是**同一次请求的同一份
+ * 体**、走同一条路由同一道门;plan_review 的反重放是一次性 nonce(S-280),守的也是同一份现写的字节;而续跑重建
+ * 读的是盘上的体、走 `resolveSpec` 的宽容层 ⇒ 4xx 砖不到任何存量挂起的任务。**门只站在人(或客户端)现写的
+ * 那份字节上**(与 tasks 面「RESUME 重放不过门」同一条律)。
  */
-export declare function planReviewBodyKeyIssue(raw: unknown): KeyClosureIssue | null;
+export declare function decisionBodyKeyIssue(door: DecisionDoorId, raw: unknown, table?: DecisionDoorKeyTable): KeyClosureIssue | null;
 /**
  * S-342 —— 「空串的理由 = 没有理由 = 这是一次**裸拒**」。这条语义只适用于**本仓自铸**的那一个域。
  *
@@ -147,4 +175,5 @@ export declare const APPROVALS_ASSISTANT_ROUTES: readonly [{
 }];
 /** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
 export type ApprovalsAssistantRouteId = RouteIdsOf<typeof APPROVALS_ASSISTANT_ROUTES>;
+export {};
 //# sourceMappingURL=approvals-assistant.d.ts.map