@sema-agent/server 7.133.0 → 7.135.0

package/dist/http/memory-compliance-failure-reply.d.ts

@@ -1,16 +1,16 @@
 /**
- * S-930 —— 记忆合规面(抹除 / 出处)上 core **已分类拒**的**唯一** HTTP 映射。两面同调:
+ * [ref] —— 记忆合规面(抹除 / 出处)上 core **已分类拒**的**唯一** HTTP 映射。两面同调:
  *  · operator 面 `routes/memory-compliance.ts`(`POST /v1/memory/erase` · `GET /v1/memory/entries/:entryId/provenance`);
  *  · 会话所有者自助抹除面 `routes/sessions.ts`(`POST /v1/sessions/:id/memory/erase`)。
  *
- * ## 病(sdk 车 SH 黑盒实证,S-930)
+ * ## 病(sdk 车 SH 黑盒实证,[ref])
  * 修前自助面在路由里自写了一份更窄的分类:只认 `config.memory_erasure_request`(400)与 `memory.target_outside_store`(409),
  * core 的另外三只 409 与 `ControlPlaneCorruptError` 全落 500 `internal.error` —— 「同一个 requestId 拿去抹另一个会话」这种**调用方自己
  * 能改**的错被说成服务器坏了。两份分类 = 两个判官,少的那份恒是静默的一份。现在**码与状态**只在这里判一次,两面同读。
  *
  * ## 规则(三层,与 operator 面既有层序逐字同序)
  *  ① core 的**本口专属**码(闭集穷举 `switch`,见 {@link sentCoreCode})—— 码与状态两面同;文案按受众(下一节,一条规则);
- *  ② **店形拒**两码 `memory.target_outside_store`(core 7.31.1 #1094)/ `memory.scope_home_not_directory`(core 7.44.0 #1368)—— 跨面 store 状态码,409、码原样
+ *  ② **店形拒**两码 `memory.target_outside_store`(core 7.31.1 [ref])/ `memory.scope_home_not_directory`(core 7.44.0 [ref])—— 跨面 store 状态码,409、码原样
  *     (判据 `memory-store-refusal.ts` 一只;运维行 `memory_store_form_refused { code, path?, form? }` 两受众同一只铸点,路径只在那里);
  *  ③ `ControlPlaneCorruptError` —— typed 500 `internal.memory_control_plane_corrupt`(fail-closed 信号,一码两义见下);
  *  其余 ⇒ `false`(未分类,调用方发它自己那句 500 且**不回显**内部文本)。
@@ -30,7 +30,7 @@ import type { ServerResponse } from "node:http";
 import type { Logger } from "../observability/logger.js";
 /**
  * 已分类拒 → HTTP 状态的**唯一**码表 = 自铸 wire 值登记处的 `sessionMemoryEraseStatus` 集(F3:wire 变更清单从同一张表 diff,状态改一处、
- * 清单跟着列)。两面同读(S-930:码与状态只判一次)。键写错 ⇒ tsc 红(索引的是 `as const` 表的键)。
+ * 清单跟着列)。两面同读([ref]:码与状态只判一次)。键写错 ⇒ tsc 红(索引的是 `as const` 表的键)。
  */
 /** 读这张映射的受众(闭集)。会话所有者受众必须交一只 `withheld` —— 被换成固定句的 core 原句落到那里(运维材料不许丢)。 */
 export type MemoryComplianceAudience = {

package/dist/http/owner-access.d.ts

@@ -1,5 +1,5 @@
 /**
- * 🔴 **属主存取器**(S-487 RH-3 第一期)——「这个调用方读得到这一行 run / 会话吗」的行只经这里取得。
+ * 🔴 **属主存取器**([ref] RH-3 第一期)——「这个调用方读得到这一行 run / 会话吗」的行只经这里取得。
  *
  * ## 律(一条)
  * 判官只有一只:run 行 = `principal-gate.ts` 的 `runOwnerReadable`(三条放行臂,含 [ref] C8 窄互认),会话行 = `sessionOwnerReadable`
@@ -39,14 +39,12 @@ export declare function readOwnedRun(config: OwnerAccessConfig, runStore: {
     getRun(taskId: string): Promise<RunRecord | undefined>;
 }, principal: Principal | undefined, taskId: string, arm: OwnerArm): Promise<RunRecord | undefined>;
 /**
- * 会话行读口:属主一读 + 无主时 placement 一格(`sessionOwnerCellOf`,S-1770)+ 会话面判官。`undefined` = 没有这只会话(`ownerOf` 答 `undefined`)≡ 读不到。
- * 读回的那一格交给调用点(要按属主作答的口用它)。店的读失败照常抛(500,绝不当成「读不到」或「读得到」)。
+ * 会话行读口:属主一读(会话店唯一的按 id 读 `headOf(id)?.owner`)+ 无主时 placement 一格(`sessionOwnerCellOf`,[ref])+ 会话面判官。
+ * `undefined` = 没有这只会话(头读答 `undefined`)≡ 读不到。读回的那一格交给调用点(要按属主作答的口用它)。店的读失败照常抛(500,绝不当成「读不到」或「读得到」)。
  */
 export declare function readOwnedSession(w: IdentityWiring & {
     readonly config: OwnerAccessConfig;
-}, store: Pick<OwnerAwareSessionStore, "placementOf"> & {
-    ownerOf(sessionId: string): Promise<string | null | undefined>;
-}, caller: SessionCaller, sessionId: string, arm: OwnerArm): Promise<SessionOwnerCell | undefined>;
+}, store: Pick<OwnerAwareSessionStore, "placementOf"> & Required<Pick<OwnerAwareSessionStore, "headOf">>, caller: SessionCaller, sessionId: string, arm: OwnerArm): Promise<SessionOwnerCell | undefined>;
 /**
  * leader 登记表的判官形(boot 装配一次,`createLeaderEndpoint` 的必填席)—— leader 模块不再自判属主(修前它手抄 `owner == null || owner === requester`,
  * 缺 C8 窄互认臂而注称 mirrors runOwnerOk)。leader 腿的调用方身份经幂等身份结构(`IdemCaller.principal`,即 `gatedPrincipal` 的回值)转手而来,

package/dist/http/owner-access.js

@@ -30,7 +30,7 @@ export async function readOwnedRun(config, runStore, principal, taskId, arm) {
     return row !== undefined && runRowReadable(config, principal, row.owner, arm) ? row : undefined;
 }
 export async function readOwnedSession(w, store, caller, sessionId, arm) {
-    const owner = await store.ownerOf(sessionId);
+    const owner = (await store.headOf(sessionId))?.owner;
     if (owner === undefined)
         return undefined;
     const cell = await sessionOwnerCellOf(store, sessionId, owner);

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

@@ -12,6 +12,9 @@ export declare function systemFor(req: IncomingMessage, config: ServiceConfig):
 /** "presented credentials must verify":Authorization 带 Bearer/token scheme 且三路全验不过 → true。
  *  其他 scheme(Basic 等,非我方凭证空间)不管——由原有门语义处置,避免误伤未知代理注头。 */
 export declare function bearerPresentedButUnverified(req: IncomingMessage, config: ServiceConfig): boolean;
+/** 「这次请求出示了这台部署的只读 trace 凭据(`TRACE_TOKEN`)」—— 一句,三处读:凭据验不过判({@link bearerPresentedButUnverified})、门前读路谓词
+ *  (`dispatch.ts` 的 `readCredentialOk`)、fleet 读档的只读臂({@link fleetViewOf})。没配 ⇒ 恒 false。 */
+export declare function traceTokenPresented(req: IncomingMessage, config: ServiceConfig): boolean;
 /** loopback 三形(IPv4 / IPv6 / IPv4-mapped)—— 一处定义,diagnostics 门与任何「本机自用」判据同吃。缺席 ⇒ false(fail-closed)。 */
 export declare function isLoopbackAddress(addr: string | undefined): boolean;
 /**
@@ -39,7 +42,7 @@ export declare function gatedPrincipal(req: IncomingMessage, config: ServiceConf
  */
 export declare function principalTokenPresentedButUnverified(req: IncomingMessage, config: ServiceConfig): boolean;
 /**
- * 🔴 **`requirePrincipal` 部署上「这次请求没有可用身份」的唯一 401 铸点**(S-305,7.76.2)。
+ * 🔴 **`requirePrincipal` 部署上「这次请求没有可用身份」的唯一 401 铸点**([ref],7.76.2)。
  *
  * 此前 45 个路由各自手抄同一行 `sendError(res, 401, "auth.principal_required", …)`,于是直连门上
  * 「JWT 出示了但过期/签不上」与「什么头都没带」在 wire 上**同形**(黑盒实测:plan_review 带过期 JWT
@@ -53,7 +56,7 @@ 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)。
+ * 🔴 **`401 auth.unauthorized` 的唯一铸点**([ref],7.104.0;test [ref] QA 7a C15)。
  *
  * 病:十六处路由(9 个文件)各自手抄同一个 401 —— 码 `auth.unauthorized`、message 就一个词 `unauthorized`。照 sema-up 部署、壳接上
  * 引擎后,第一句就撞上它,不说要哪份凭据、放哪、去哪拿。
@@ -62,8 +65,8 @@ export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingM
  * 每面一句模块级常量(冻结门按常量解引用逐字钉)。三句都**不含任何值**(令牌 / 头名 / 路径实参一概不回显),且**不区分**
  * 「没带」与「带错」—— 同一道门上两者逐字同体,区分就是探测面。
  *  · `credential` —— 全局凭据门(`dispatch.ts`):部署配了 service token,请求没带或带的不认(registry 登录令牌验不过同属此面);
- *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):service token 开得了,指标口另认只读的
- *    `METRICS_TOKEN`(它在全局门之前判);
+ *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):不带主体头的 service token 开得了(带主体头的是那位主体,
+ *    {@link actsForDeployment}),指标口另认只读的 `METRICS_TOKEN`、`source-summary` 另认只读的 `TRACE_TOKEN`(都在全局门之前判);
  *  · `identity` —— 过了凭据门(或这台部署没配 service token)、但这一口要一个**验过的调用方身份**:属主寻址的读 / 写面、规则面、
  *    记忆面。在配了 service token 的部署上,「带 service token 却没身份」只会落在只认身份的口(规则 / 记忆 / 会话策略)上 ——
  *    这时再叫调用方「去带 service token」是假出路,所以这一面的句子只讲身份。
@@ -71,11 +74,11 @@ export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingM
  */
 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_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 without a principal header (a service-token request that names a principal acts for that principal, not for the deployment), or a read-only token this endpoint accepts (METRICS_TOKEN for the metrics endpoints, TRACE_TOKEN for the task source summary)";
 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` 的
+ * 🔴 **「这个调用方读得到这一行 run 吗」的唯一谓词**([ref] 抽取;此前只活在 `server.ts runOwnerOk` 的
  * 函数体里,而 `runOwnerOk` 把**判断**与**404 怎么发**焊在一起 —— 于是任何需要同一条判断但不想 404 的
  * 读面(如 `/mcp` 面板的 `lastLegMcp`:非属主就不投这个键、面板照常 200)只能手抄一份,而手抄那份必然
  * 漏掉下面这条窄互认臂:`explicitOperatorOk` 顶注已经为同族的病写过「SINGLE mint point,不要再造兄弟」)。
@@ -109,23 +112,46 @@ export interface IdentityWiring {
  */
 export declare function wiredIdentitySources(w: IdentityWiring): readonly IdentitySource[];
 /**
- * 🔴 **「这台部署有没有身份边界」的唯一判据**(S-1452;S-1509 改读身份来源)。dev-open = 装配**没接任何身份来源**({@link wiredIdentitySources} 为空:
+ * 🔴 **「这台部署有没有身份边界」的唯一判据**([ref];[ref] 改读身份来源)。dev-open = 装配**没接任何身份来源**({@link wiredIdentitySources} 为空:
  * 没配 service token、没装鉴权桥、没开直连门)、**也没声明**只读 trace token 或 `REQUIRE_PRINCIPAL`:请求里没有任何东西替主体头作保,头是谁都能自报的
  * **标签**(过滤 / 展示用),不是身份。装了鉴权桥的部署(SSO 单开)带登录令牌的调用方是验过的身份 ⇒ 不是 dev-open(修前只看 token / `REQUIRE_PRINCIPAL`,
  * 这一形被读成 dev-open,任何人 fleet-wide 读全部会话)。
- * 四处读它、不各写一份:会话列表的 fleet-wide 第一臂(`isFleetWide`)、会话写面的 fleet-wide 第一臂(`sessionOwnerScopeForWrite`)、
+ * 三处读它、不各写一份:fleet 调用方的第一臂({@link sessionCallerOf} —— fleet 面的 {@link fleetViewOf} 与会话行属主门都经它)、
  * 会话面的属主谓词({@link sessionOwnerReadable})、`/metrics` 族的免凭据臂(`dispatch.ts`)—— 于是「调用方是谁」在列表、单会话面与指标面上只有一只读法。
  */
 export declare function devOpenDeployment(w: IdentityWiring): boolean;
-/** 会话行属主门的调用方的唯一铸点({@link SessionCaller}):验过的主体 + 是不是 fleet 调用方 —— {@link devOpenDeployment} 上的任何调用方,
- *  或出示了这台部署的 service 凭据(`systemFor`)、不报主体的调用方(带主体头的是那位主体,不是 fleet;只读 trace token 不是 service 凭据)。 */
+/**
+ * service 凭据**代部署本身**说话:出示了这台部署的 service 凭据({@link systemFor}),且不代任何验过的主体。带主体头的 service 凭据请求是前端(BFF)
+ * 代那位主体发的 —— 它读那位主体,不读全舰队;部署姿态(单用户 / 多租)不改这一句(单用户形上的主体头同样是「这次请求为谁」)。
+ * 两处读它:fleet 调用方的凭据臂({@link sessionCallerOf})与 `/metrics` 族的 service 臂(`dispatch.ts`)。先判凭据、后取主体:`principal` 只在出示了
+ * service 凭据时才求值(调用点那一次 {@link gatedPrincipal}),没带凭据的请求不因主体头的形而改答。
+ */
+export declare function actsForDeployment(req: IncomingMessage, config: ServiceConfig, principal: () => Principal | undefined): boolean;
+/**
+ * 🔴 **「这个调用方是不是 fleet 调用方(看得到所有租户)」的唯一铸点**({@link SessionCaller}):验过的主体 + 是不是 fleet —— {@link devOpenDeployment} 上的任何
+ * 调用方,或 {@link actsForDeployment}(出示 service 凭据、不报主体)。带主体头的是那位主体,不是 fleet;只读 trace token 不是 service 凭据;operator 不在这里
+ * (运维口各自读 {@link explicitOperatorOk})。读者:会话行属主门(无主 placed 行的放行臂)与 fleet 面的 {@link fleetViewOf} —— 同一问一只读法。
+ */
 export declare function sessionCallerOf(req: IncomingMessage, w: IdentityWiring): SessionCaller;
+/** fleet 面的两档(闭集):`read` = 只读面,只读 trace 凭据在这一档也是 fleet;`write` = 写面,只认 {@link sessionCallerOf}(读凭据不能变成跨租户写权)。 */
+export type FleetFace = "read" | "write";
+/** 一次 fleet 面判定的读数:`fleetWide` = 看全舰队(不钉人);否则 `gateOwner` = 钉住的那位验过的主体,`null` = 没有可用身份(调用点答 401 identity)。 */
+export interface FleetView {
+    readonly fleetWide: boolean;
+    readonly gateOwner: Principal | null;
+}
+/**
+ * 🔴 **fleet 面「看全舰队,还是钉住一位主体」的唯一读法**。fleet 判据只有一个来源 —— {@link sessionCallerOf};本函数只把它投成 fleet 面要的两格,
+ * 并按档并上只读 trace 凭据(读档)。读者 —— 读档:舰队流、会话列表、发件链接列表、后台名册、trace 五口、用量三口、`/v1/tasks/source-summary`;
+ * 写档:删除、fork、同步族(拉取与推送同门)。
+ */
+export declare function fleetViewOf(req: IncomingMessage, w: IdentityWiring, face: FleetFace): FleetView;
 /**
  * **「这个调用方能不能动这只会话」的唯一谓词**(会话面:视图 / head / 事件流 / 记忆状态与自助抹除 / 改名置顶 / 后台任务 / MCP 重连 /
  * 面板的上一腿 MCP 投影)。没有身份边界的部署({@link devOpenDeployment})上不钉任何人(与会话列表同读,列表把这只会话列给谁,谁就读得到它);
  * 有身份边界的部署上:
  *  · **无主的行**经无主臂的唯一判据 `ownerlessRowOpen`(`security.ts`):普通会话照旧对任何调用方开放;委派子代的 placed 行只对 fleet 调用方
- *    ({@link sessionCallerOf})开放 —— 任何具名主体、没有 service 凭据的无身份调用方都与别人的行同体(调用点答 404)(S-1770)。
+ *    ({@link sessionCallerOf})开放 —— 任何具名主体、没有 service 凭据的无身份调用方都与别人的行同体(调用点答 404)([ref])。
  *    代价如实:属主还没定下的子代行连它将来的属主也暂时读不到(由一次性迁移 M23 / 那一行的下一次停驻定下);
  *  · 有主的行就是 run 面那一条谓词({@link runOwnerReadable}),一字不变。
  * run 面(poll / events / cancel …)不读本谓词 —— 那是 run 资源的门,另一只。
@@ -137,7 +163,7 @@ export declare function sessionOwnerReadable(caller: SessionCaller, cell: Sessio
  */
 export type OperatorRoster = Pick<ServiceConfig, "operatorPrincipals" | "operatorSingleUser">;
 /**
- * 🔴 **「谁是 operator」的唯一读法**(S-1050,[ref] ① 裁 A;IMAGE-API-DESIGN.md §P2.4a MUST-FIX 的那一只门)。
+ * 🔴 **「谁是 operator」的唯一读法**([ref],[ref] ① 裁 A;IMAGE-API-DESIGN.md §P2.4a MUST-FIX 的那一只门)。
  *  · 名单为空 ⇒ **没人是**(没有任何形把「空名单」读成「人人是」—— 那条读法 `isOperator` 已删);
  *  · 名单非空 ⇒ 验过的主体在名单里才是;
  *  · 单用户形显式声明 `OPERATOR_SINGLE_USER=true` ⇒ 这台部署的**每个调用方**都是(单用户形只有一位用户,能到这台部署的就是他;边界是部署自己的
@@ -149,7 +175,7 @@ export declare function explicitOperatorOk(principal: string | undefined, roster
 /** 「这台部署**有没有**运维」的唯一读法(名单非空 ∨ 单用户声明在场)—— 能力事实 `operatorLane`、整理阀门的可达性告警、起服提示同读这一只。 */
 export declare function operatorRosterPresent(roster: OperatorRoster): boolean;
 /**
- * 起服提示(S-1050):单用户形(`REQUIRE_PRINCIPAL` 未开)+ 没有运维名册 + 这台部署有审批底座 ⇒ 一行 warn。这一形在「空名单 = 人人是」那条读法退役之后
+ * 起服提示([ref]):单用户形(`REQUIRE_PRINCIPAL` 未开)+ 没有运维名册 + 这台部署有审批底座 ⇒ 一行 warn。这一形在「空名单 = 人人是」那条读法退役之后
  * 丢的东西就是审批队列的运维视图(跨 scope 列表 / `?owner=` / 无主体调用方的整个队列),补回它只要一行配置 —— 不拒启:升级那一拍打掉一台今天跑得好好的
  * 单用户机器比一条提示重。多租形不提示(它另有拒启不变量);没有审批底座的形什么都没少。
  */

package/dist/http/principal-gate.js

@@ -1,4 +1,5 @@
 import { timingSafeEqual } from "node:crypto";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { PRINCIPAL_TOKEN_HEADER, verifiedPrincipal, ssoVerifiedPrincipal, ownerlessRowOpen, mintPrincipal } from "../security.js";
 import { sendError } from "./send.js";
 export function headerStr(v) {
@@ -30,10 +31,13 @@ export function bearerPresentedButUnverified(req, config) {
         return false;
     if (systemFor(req, config) !== undefined)
         return false;
-    if (config.traceToken && authorized(req, config.traceToken))
+    if (traceTokenPresented(req, config))
         return false;
     return true;
 }
+export function traceTokenPresented(req, config) {
+    return !!config.traceToken && authorized(req, config.traceToken);
+}
 export function isLoopbackAddress(addr) {
     return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
 }
@@ -68,7 +72,7 @@ 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_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 without a principal header (a service-token request that names a principal acts for that principal, not for the deployment), or a read-only token this endpoint accepts (METRICS_TOKEN for the metrics endpoints, TRACE_TOKEN for the task source summary)";
 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) {
@@ -95,7 +99,7 @@ export function runOwnerReadable(principal, owner, config) {
         return true;
     if (principal !== undefined && sameIdentity(principal, owner))
         return true;
-    return !config.requirePrincipal && owner === "anon:shell-live" && principal === undefined;
+    return !DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(config) && owner === "anon:shell-live" && principal === undefined;
 }
 export function hasServiceAuth(config) {
     return Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
@@ -118,11 +122,31 @@ export function wiredIdentitySources(w) {
     return IDENTITY_SOURCES.filter((k) => identitySourceWired(k, w));
 }
 export function devOpenDeployment(w) {
-    return wiredIdentitySources(w).length === 0 && !w.config.traceToken && !w.config.requirePrincipal;
+    return wiredIdentitySources(w).length === 0 && !w.config.traceToken && !DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(w.config);
+}
+export function actsForDeployment(req, config, principal) {
+    return systemFor(req, config) !== undefined && principal() === undefined;
 }
 export function sessionCallerOf(req, w) {
     const principal = gatedPrincipal(req, w.config);
-    return { principal, fleet: devOpenDeployment(w) || (principal === undefined && systemFor(req, w.config) !== undefined) };
+    return { principal, fleet: devOpenDeployment(w) || actsForDeployment(req, w.config, () => principal) };
+}
+export function fleetViewOf(req, w, face) {
+    const caller = sessionCallerOf(req, w);
+    const fleetWide = caller.fleet || readOnlyFleetCredential(req, w.config, face);
+    return { fleetWide, gateOwner: fleetWide ? null : caller.principal || null };
+}
+function readOnlyFleetCredential(req, config, face) {
+    switch (face) {
+        case "read":
+            return traceTokenPresented(req, config);
+        case "write":
+            return false;
+        default: {
+            const unknownFace = face;
+            throw new Error(`fleetViewOf: unknown fleet face ${String(unknownFace)}`);
+        }
+    }
 }
 export function sessionOwnerReadable(caller, cell, w) {
     if (devOpenDeployment(w))
@@ -146,7 +170,7 @@ export function buildOperatorUndeclaredNotice(config, approvalFaceWired) {
         event: "operator_undeclared_single_user",
         fields: {
             detail: "this single-user deployment declares no operator: OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not set, so no caller is an operator — " +
-                "GET /v1/approvals, its stream, /v1/assistant/inbox and /v1/assistant/tasks show each caller only its own pending approvals (a caller that sends no principal sees none) and ignore ?owner=. " +
+                "GET /v1/approvals, its stream, /v1/assistant/inbox and /v1/assistant/tasks show each caller only its own pending approvals (a caller that sends no principal sees only the anonymous ones - the cards and tasks that were submitted without a principal - never a named principal's) and ignore ?owner=. " +
                 "To act as this deployment's operator, add one line: OPERATOR_SINGLE_USER=true",
         },
     };

package/dist/http/readiness.d.ts

@@ -1,5 +1,5 @@
 /**
- * S-739 / S-740(车OE,7.102.0):**就绪判的唯一属主** —— 一只谓词 {@link readinessOf},全部读点经它:
+ * [ref] / [ref](车OE,7.102.0):**就绪判的唯一属主** —— 一只谓词 {@link readinessOf},全部读点经它:
  *
  *  ① `GET /readyz`(`dispatch.ts`,凭据门之前,与 `/health` 同位):200 `{ready:true}` / 503 `{ready:false, reasons}` ——
  *     给**摘流**语义的探针(k8s readinessProbe / LB 健康检查);**重启**语义的探针(Docker HEALTHCHECK、k8s livenessProbe)

package/dist/http/refusal-body.d.ts

@@ -18,4 +18,16 @@ export type RefusalBody = {
 } & Record<string, unknown>;
 /** 拒体:`{ error, errorCode, ...facts }`。 */
 export declare function refusalBody(r: Refusal): RefusalBody;
+/**
+ * 引擎拒一次续跑时的**三个机读判别位** → 拒体的同名事实键(唯一读法;续跑家族的每一只拒答都读它):
+ * `detail.code` ⇒ `blockedBy`(挡住它的准入码)· `detail.field` ⇒ `field`(哪一侧 / 哪一格)· `detail.reason` ⇒ `reason`(同码多臂时哪一臂)。
+ * 一员在场 ⇔ 它是非空串;其余(缺席、非串、空串)一律不铸键 —— 引擎没说就是没说,本层不编值,也不把一个非串原样推上 wire。
+ * 载体有两种,读法同一只:同步腿的 `CheckpointError.detail`(`http/resume-legs.ts` `checkpointRefusalAnswer`),与后台停驻子代赎回回执的
+ * `details.detail`(`parked-decide.ts` 的 422 `parked_resume.startup_failed`;引擎 7.54.0 起它把认领前那只失败的同三位交到回执上)。
+ */
+export declare function resumeRefusalFacts(detail: unknown): {
+    blockedBy?: string;
+    field?: string;
+    reason?: string;
+};
 //# sourceMappingURL=refusal-body.d.ts.map

package/dist/http/refusal-body.js

@@ -1,4 +1,15 @@
 export function refusalBody(r) {
     return { error: r.message, errorCode: r.errorCode, ...r.facts };
 }
+export function resumeRefusalFacts(detail) {
+    if (typeof detail !== "object" || detail === null)
+        return {};
+    const d = detail;
+    const word = (v) => typeof v === "string" && v !== "";
+    return {
+        ...(word(d.code) ? { blockedBy: d.code } : {}),
+        ...(word(d.field) ? { field: d.field } : {}),
+        ...(word(d.reason) ? { reason: d.reason } : {}),
+    };
+}
 //# sourceMappingURL=refusal-body.js.map

package/dist/http/request-guards.d.ts

@@ -1,5 +1,5 @@
 /**
- * 请求守门族(S-147 切片:`http/server.ts` 4837–5195 + `MAX_BODY` 逐字搬家,正文一字未改)。
+ * 请求守门族([ref] 切片:`http/server.ts` 4837–5195 + `MAX_BODY` 逐字搬家,正文一字未改)。
  * 配额 / 租约 / 用量窗 / 限流 / owner-scope / 体读取 —— 每只守门的判据与它自己的头注原位随行。
  * ctx 字段 1 只(`deps`):本族对外围的耦合就这一格,它也是这一族的可测性读数。
  */
@@ -21,7 +21,7 @@ import { type SqlWallSource, type SqlWallsReading } from "../plugins/sql-driver.
  * 入参是**已判好的墙**(`sql-driver.ts` `sqlWallsOf` —— 事实缺席时的落点只在那里定义,与 blob 帽同一只判官、同一个方向);本函数不读事实、不判缺席,
  * 墙从哪来(`sources` 里**被拒的那一堵**的出处)原样带进判决(`wallSource`),拒句按它分两形:库报的墙点名库的上限与旋钮,假定的墙(事实还没建立,或事实在场但这一堵读失败、退了文档缺省)只说「库的这个上限没读到、按最保守的墙拒」。
  *
- * 🔴 **包墙腿是同一只规则的提前一跑,不是第二套规则**(S-1746 主会话裁定):包墙是物理连接的事实(会话值,连接建立时从全局拷一份、此后不变),
+ * 🔴 **包墙腿是同一只规则的提前一跑,不是第二套规则**([ref] 主会话裁定):包墙是物理连接的事实(会话值,连接建立时从全局拷一份、此后不变),
  * 终判在将要执行写入的那条连接上 —— 那是库自己(续跑输入那一笔被拒 ⇒ 店的带码拒 ⇒ 同一个 413;会话日志那一笔走它既有的失败面);SQL 快照 blob 则由
  * `blob-backend.ts` 经 `connectJudged` 在写入连接上判。受理时手里没有那条连接,判官 `sqlWallsOf` 读的 `facts` 是池里**最近一次初始化**的那条连接的读数
  * (`SqlDriver.facts`:池见过的最新读数,只在有连接初始化时才更新),同一个折算 `packetWallStatementBytes`:拒 ⇒ 413 在任何副作用之前;收 ⇒ 写入那条连接上的判决仍是终判。
@@ -44,7 +44,7 @@ export interface SubmitBodyRefusal {
 }
 export declare function refuseSubmitBody(walls: SqlWallsReading, body: unknown): SubmitBodyRefusal | null;
 /**
- * S-866 ③ —— 租约拒绝的应答形({@link leaseRefusalOf} 的产物;`{status, body}` 交回形 + 镜像头用的 `retryAfterSec`)。
+ * [ref] ③ —— 租约拒绝的应答形({@link leaseRefusalOf} 的产物;`{status, body}` 交回形 + 镜像头用的 `retryAfterSec`)。
  * 体经唯一组句器铸(键序 `error, errorCode, …机读位`;冻结门 `FROZEN_RESULT_BODY` 读 `refusalBody({ errorCode, message, … })` 这一形)。
  */
 export interface LeaseRefusal {
@@ -53,7 +53,7 @@ export interface LeaseRefusal {
     readonly retryAfterSec: number;
 }
 /**
- * S-866 ③ —— 一次被拒的租约准入 → HTTP 应答的**唯一**映射(三只门 {@link createRequestGuards} 里的 `leaseDenied` /
+ * [ref] ③ —— 一次被拒的租约准入 → HTTP 应答的**唯一**映射(三只门 {@link createRequestGuards} 里的 `leaseDenied` /
  * `ownerLeaseDenied` / `ownerFleetLeaseDenied` 同调它;12 个调用点零改)。按拒因穷举(加一臂 = 编译红):
  *  · `budget_exhausted` ⇒ **429 `quota_exhausted`**(字节同 7.105.0 的路由发送形:`retryAfterSec` + 中心 E4 结构化字段逐字透传);
  *  · `lease_unavailable` ⇒ **503 `fleet.lease_unavailable`**(只在 `FLEET_LEASE_FAIL_CLOSED` 生效时出现):体 `{reason, retryAfterSec}`,
@@ -95,15 +95,6 @@ export declare function createRequestGuards(ctx: {
     usageWindowDenied: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
     rateLimited: (req: IncomingMessage, res: ServerResponse) => boolean;
     safeDecode: (seg: string) => string | null;
-    isFleetWide: (req: IncomingMessage) => boolean;
-    sessionOwnerScope: (req: IncomingMessage) => {
-        fleetWide: boolean;
-        gateOwner: string | null;
-    };
-    sessionOwnerScopeForWrite: (req: IncomingMessage) => {
-        fleetWide: boolean;
-        gateOwner: string | null;
-    };
     runOwnerOk: (req: IncomingMessage, res: ServerResponse, owner: string | null) => boolean;
     sessionOwnerOk: (req: IncomingMessage, res: ServerResponse, cell: SessionOwnerCell) => boolean;
     runSessionAcceptOk: (req: IncomingMessage, res: ServerResponse, run: {

package/dist/http/request-guards.js

@@ -4,8 +4,9 @@ import { RUN_NOT_FOUND_MESSAGE, SESSION_NOT_FOUND_MESSAGE } from "./route-ctx.js
 import { invalidJsonError, sendError } from "./send.js";
 import { refusalBody } from "./refusal-body.js";
 import { limitFactsUnmeasured } from "../limit-refusal.js";
-import { authorized, systemFor, gatedPrincipal, explicitOperatorOk, sessionOwnerReadable, sessionCallerOf, devOpenDeployment, sendPrincipalRefusal } from "./principal-gate.js";
+import { gatedPrincipal, explicitOperatorOk, sessionOwnerReadable, sessionCallerOf, sendPrincipalRefusal } from "./principal-gate.js";
 import { runRowReadable } from "./owner-access.js";
+import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
 import { quotaWindowResetsAt } from "../observability/cost-quota.js";
 import { escapedStatementBytes, packetWallStatementBytes, rowWallPayloadBytes } from "../plugins/sql-driver.js";
 const MAX_BODY = 8 * 1024 * 1024;
@@ -184,23 +185,9 @@ export function createRequestGuards(ctx) {
             return null;
         }
     }
-    function isFleetWide(req) {
-        const tt = deps.config.traceToken;
-        return devOpenDeployment(deps) || systemFor(req, deps.config) !== undefined || (!!tt && authorized(req, tt));
-    }
-    function sessionOwnerScope(req) {
-        const fleetWide = isFleetWide(req);
-        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
-        return { fleetWide, gateOwner };
-    }
-    function sessionOwnerScopeForWrite(req) {
-        const fleetWide = devOpenDeployment(deps) || systemFor(req, deps.config) !== undefined;
-        const gateOwner = fleetWide ? null : (gatedPrincipal(req, deps.config) || null);
-        return { fleetWide, gateOwner };
-    }
     function ownerGate(req, res, readable, notFound) {
         const principal = gatedPrincipal(req, deps.config);
-        if (deps.config.requirePrincipal && !principal) {
+        if (DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(deps.config) && !principal) {
             sendPrincipalRefusal(res, req, deps.config);
             return false;
         }
@@ -265,6 +252,6 @@ export function createRequestGuards(ctx) {
         }
         return Buffer.concat(chunks);
     }
-    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, isFleetWide, sessionOwnerScope, sessionOwnerScopeForWrite, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, readJson, readRawBody };
+    return { quotaExceeded, ownerCostQuotaDenied, ownerFleetLeaseDenied, ownerLeaseDenied, ownerQuotaDenied, leaseDenied, usageWindowDenialFor, usageWindowDenied, rateLimited, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, readJson, readRawBody };
 }
 //# sourceMappingURL=request-guards.js.map

package/dist/http/resume-ctx-read.d.ts

@@ -1,8 +1,8 @@
 /**
- * **续跑上下文这一次读的结局**(S-577 第二半,7.94.0)—— 属主模块,所有消费腿共用这一只读口。
+ * **续跑上下文这一次读的结局**([ref] 第二半,7.94.0)—— 属主模块,所有消费腿共用这一只读口。
  *
  * 🔴 **为什么必须有这只铸点**:此前各消费腿各写一句 `.catch(() => null)`(还有一处把异常文案拼上 wire),
- * 于是店层在 S-577 里把坏体从「答缺席」改成「响亮拒」之后,那些 `catch` 会把那次拒**原样吞回缺席** ——
+ * 于是店层在 [ref] 里把坏体从「答缺席」改成「响亮拒」之后,那些 `catch` 会把那次拒**原样吞回缺席** ——
  * 机制上「坏体不再与缺席同答」成立,**用户面上不成立**(用户拿到的还是同一个 409)。判据要钉用户实际
  * 拿到的码,这只铸点就是让那句判据有地方落(test [ref] 的判据订正,当拍采纳)。
  *
@@ -16,13 +16,25 @@
  *    ⚠️ `not-text`(投影漂 = 我方的码病)**刻意不进这一态**,原样上抛、响亮成 500 —— 不许伪装成
  *    「数据坏了」,更不许折成缺席(那会让一次代码漂看起来像「这条会话没有上下文」)。
  *
- * 🔴 **按「店的拒绝形」分类,不按「列错误类」**(S-608,7.95.1:这一句此前反了,整整一版)。修前本口
+ * 🔴 **按「店的拒绝形」分类,不按「列错误类」**([ref],7.95.1:这一句此前反了,整整一版)。修前本口
  * 认的是属主谓词 `isJsonColumnBodyProblem`(= 一只 `SqlJsonColumnError`),而 SQL 两孪生的 `refusing()`
  * 早把列错误**折**成了一只普通 `Error` ⇒ 折后的错落进下面那条「店抖动 ⇒ 当缺席」臂,坏体与缺席在
- * 用户面上仍然同答 409 —— 正是 S-577 第二半要修的那个病,只是它当时只在 local 车道上修成了(那一侧
+ * 用户面上仍然同答 409 —— 正是 [ref] 第二半要修的那个病,只是它当时只在 local 车道上修成了(那一侧
  * 恰好没折码,把列错误漏了出来 = 巧合式正确)。两条车道现在同一份拒绝契约,本口只认它。
+ *
+ * 🔴 **第四态 `unsealable`([ref],7.134.0):读出来了,但凭据位上的封签开不开**。店交出的是**落盘形**(凭据位上是封签,`StoredCheckpointCtx`);
+ * 本口在任何消费者看到之前经**唯一**开口 `openCheckpointCtx` 开封(规则属主 = `checkpoint-ctx.ts` 末段「凭据位密封」)—— 所以 `ok` 交出的恒是开封形,
+ * 没有哪条腿拿着封签去重建 spec。开不开(没有保管店 / 钥匙不在本副本 / 密文坏或不是本行封的 / 明文 / 认不出的封签)⇒ `unsealable`(`field` + `reason`),
+ * 各续跑入口答 {@link resumeCtxUnsealableAnswer}(409 `conflict.checkpoint_ctx_unsealable`)。**不折成缺席**(出路不同:缺席 = 重提;开不开 = 看 `reason`
+ * —— `key_not_held` 多半是多副本没共享保管目录,运维修好之后同一个决定原样重发即可),**不明文回落、不丢键**。
+ * 开封要知道这一行的会话(封签绑会话)与开口(`ServiceDeps.checkpointCtxSealing`;缺席 = 本副本没有保管店):两件一起交({@link CheckpointCtxOpening})。
+ *
+ * **两种读法,一只读口**(第二个实参):① 开封形({@link CheckpointCtxOpening})—— 续跑重建 spec 的每一条腿;② {@link KEEP_SEALED}「信封原样留着」——
+ * 只读**非凭据字段**的读者(今天 = inbox 的展示位 `objective`):不开封、不判凭据位(活凭据不为展示进内存),交回落盘形 `StoredCheckpointCtx`,
+ * 结局里没有 `unsealable` 这一态(型面就没有;店边界的三态与开封形逐字同一段)。凭据位上的值在这种读法里仍是封签 —— 谁要用它们就必须走读法 ①。
  */
 import type { CheckpointCtx } from "./route-ctx.js";
+import { type CheckpointCtxOpener, type CheckpointCtxUnsealableReason, type StoredCheckpointCtx } from "./checkpoint-ctx.js";
 import { type RefusalBody } from "./refusal-body.js";
 export type ResumeCtxRead = {
     readonly kind: "ok";
@@ -32,10 +44,45 @@ export type ResumeCtxRead = {
 } | {
     readonly kind: "corrupt";
     readonly where: string;
+} | {
+    readonly kind: "unsealable";
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+};
+/** 读法 ② 的结局:店边界的三态,`ok` 交落盘形(凭据位上仍是封签)。 */
+export type SealedResumeCtxRead = {
+    readonly kind: "ok";
+    readonly ctx: StoredCheckpointCtx;
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "corrupt";
+    readonly where: string;
+};
+/** 开封的两件:这一行的会话(= 交给店 `getCtx` 的那一个)与开口(缺席 = 本副本没有保管店)。 */
+export interface CheckpointCtxOpening {
+    readonly sessionId: string;
+    readonly opener: CheckpointCtxOpener | undefined;
+}
+/** 读法 ② 的词:信封原样留着(只读非凭据字段)。 */
+export declare const KEEP_SEALED = "keep_sealed";
+export declare function readResumeCtx(load: Promise<StoredCheckpointCtx | null>, opening: CheckpointCtxOpening): Promise<ResumeCtxRead>;
+export declare function readResumeCtx(load: Promise<StoredCheckpointCtx | null>, opening: typeof KEEP_SEALED): Promise<SealedResumeCtxRead>;
+/**
+ * 开不开的对外答复([ref])—— 409 `conflict.checkpoint_ctx_unsealable`,机读 `field`(哪一个凭据位,提交体路径;键名不是秘密,值从不进来)+ `reason`
+ * (闭集 `CHECKPOINT_CTX_UNSEALABLE_REASONS`)。句子说「这条任务的续跑上下文里带的凭据本服务开不开」、五种成因与出路(按 `reason` 修好保管目录后原样重发,
+ * 或作为新任务重提、仍停驻的先取消)。拒在任何状态改动之前:卡仍待决、行字节不动、`plan_review` 的一次性 nonce 未烧。
+ * 🔴 形是给冻结门看的(与 {@link resumeCtxCorruptAnswer} 同一条):`status: <三位数>, body: refusalBody({ errorCode: "<码>", message: "<整句双引号字面>"`,中间只许有空白。
+ */
+export declare function resumeCtxUnsealableAnswer(read: {
+    readonly field: string;
+    readonly reason: CheckpointCtxUnsealableReason;
+}): {
+    status: number;
+    body: RefusalBody;
 };
-export declare function readResumeCtx(load: Promise<CheckpointCtx | null>): Promise<ResumeCtxRead>;
 /** 坏体的对外答复 —— 与会话策略面**同码**(`session-policy-wire.ts` 的 `corrupt` ⇒ 500),不铸新词。
- *  文案只说「哪一行读不出来 + 该找谁」,不把店层 detail 拼上 wire(内部机件不上 wire,S-376 同律)。 */
+ *  文案只说「哪一行读不出来 + 该找谁」,不把店层 detail 拼上 wire(内部机件不上 wire,[ref] 同律)。 */
 export declare function resumeCtxCorruptAnswer(where: string): {
     status: number;
     body: RefusalBody;

package/dist/http/resume-ctx-read.js

@@ -1,9 +1,18 @@
+import { openCheckpointCtx } from "./checkpoint-ctx.js";
 import { SqlJsonColumnError, StoreCorruptError } from "../plugins/sql-json-column.js";
 import { refusalBody } from "./refusal-body.js";
-export async function readResumeCtx(load) {
+export const KEEP_SEALED = "keep_sealed";
+export async function readResumeCtx(load, opening) {
+    const read = await readStoredCtx(load);
+    if (read.kind !== "ok" || opening === KEEP_SEALED)
+        return read;
+    const opened = openCheckpointCtx(read.ctx, opening.opener, opening.sessionId);
+    return opened.kind === "ok" ? { kind: "ok", ctx: opened.ctx } : { kind: "unsealable", field: opened.field, reason: opened.reason };
+}
+async function readStoredCtx(load) {
+    let stored;
     try {
-        const ctx = await load;
-        return ctx == null ? { kind: "absent" } : { kind: "ok", ctx };
+        stored = await load;
     }
     catch (e) {
         if (e instanceof StoreCorruptError)
@@ -12,6 +21,20 @@ export async function readResumeCtx(load) {
             throw e;
         return { kind: "absent" };
     }
+    return stored == null ? { kind: "absent" } : { kind: "ok", ctx: stored };
+}
+export function resumeCtxUnsealableAnswer(read) {
+    return {
+        status: 409,
+        body: refusalBody({
+            errorCode: "conflict.checkpoint_ctx_unsealable",
+            message: "this task's stored resume context holds credentials from its request (MCP / A2A headers or env values, settings.env, settings.webSearch.apiKey, http hook headers, or command hook plugin options) that this server cannot unseal — reason says why: no_key_store (this server has no sealed-key store), key_not_held (they were sealed with a key this server does not hold: another replica's, or a replaced sealed-key directory), unopenable (the sealed value is damaged or belongs to another session), plaintext (an older server version stored them unsealed), unrecognized_seal (a seal format this version does not know). Nothing was decided and nothing was resumed. If whoever operates this deployment restores the sealed-key directory that sealed them and restarts this server (it reads its keys only at startup), the same request can be sent again; otherwise submit the work again as a new task, and if this task is still suspended cancel it first (POST /v1/runs/:id/cancel).",
+            facts: {
+                field: read.field,
+                reason: read.reason,
+            },
+        }),
+    };
 }
 export function resumeCtxCorruptAnswer(where) {
     return {

package/dist/http/resume-legs.d.ts

@@ -1,5 +1,5 @@
 /**
- * 续跑腿家族 + 路由 ctx 的装配(S-147 切片:`http/server.ts` 2378–4804 与 1119–1128 逐字搬家,正文一字未改)。
+ * 续跑腿家族 + 路由 ctx 的装配([ref] 切片:`http/server.ts` 2378–4804 与 1119–1128 逐字搬家,正文一字未改)。
  *
  * 🔴 为什么 `routeCtxBase` 住在这个文件里而不是组合根:`startFreshHostTurn` 把**整只** ctx 交给
  * `mintAndDriveDurableRun`,而 `ctx.legs` 装的正是本文件这几条腿 —— 两者是一个结。拆开只有两条路:
@@ -8,7 +8,7 @@
  * 腿是提升的函数声明、ctx 是文件尾的 `const`,谁也不会在工厂执行期读到对方。
  *
  * ctx 字段 27 只(registry 6 + helpers 14 + deps/runnerFor/prepareSpec/finalizeTaskResult + 三只配额/租约/用量窗
- * 判据;S-947 删 `cancelledViaVerb` 旁表后 28 → 27,与 `test/split-ctx-parity.test.ts` 的读数同)—— 这是**如实披露**的耦合读数(设计稿 §9:把它变小是波 3 的事,本刀不承诺)。型一律从既有型派生
+ * 判据;[ref] 删 `cancelledViaVerb` 旁表后 28 → 27,与 `test/split-ctx-parity.test.ts` 的读数同)—— 这是**如实披露**的耦合读数(设计稿 §9:把它变小是波 3 的事,本刀不承诺)。型一律从既有型派生
  * (`RunRegistry` / `RouteHelpers` / `RouteLegs` / `ReturnType<typeof createRequestGuards>`),不手抄签名 ⇒ 不会漂。
  */
 import type { IncomingMessage } from "node:http";
@@ -29,13 +29,14 @@ import { type ResumeRefusalAnswer } from "./checkpoint-ctx.js";
  */
 export declare function resumeRefusalDisposition(e: CheckpointError): "cancelled" | "retriable" | "terminal";
 /**
- * 🔴 **引擎拒一次续跑(`CheckpointError`)的 HTTP 答复 —— 唯一组句器**(S-1690 / S-1692,core 7.52.0;五条续跑腿〔`/decide` · `/resume` · `/wake` · `plan_review` ·
+ * 🔴 **引擎拒一次续跑(`CheckpointError`)的 HTTP 答复 —— 唯一组句器**([ref] / [ref],core 7.52.0;五条续跑腿〔`/decide` · `/resume` · `/wake` · `plan_review` ·
  * workflow 决定在宿主会话上起的新一跑〕同经 `driveResumeLeg` 的 catch 臂到这里,SLA 拒扫腿与 PARKED 赎回席经 `resumeCheckpoint` 同得)。
  *
  * 规则(一条):**一次拒 = 一个答复形,与「谁发现的」无关**。引擎在认领前 / CAS 前拒的,与本服务在重放存量体之前自己拒的(`resume_blocked_by_policy`,
  * `checkpoint-ctx.ts` `resumeBlockedByPolicyAnswer`;续跑入口上卡仍 pending ⇒ 同样带 `retriable:true`)读同一组机读键;体经拒体组句器 `refusalBody` 铸,
  * `retriable` 经续跑家族的唯一写点 `resumeRefusalWithCard` 追加。
- * 一处如实例外:后台停驻子代的 parked 赎回不经本函数 —— 引擎的赎回回执只交成因词,`parked-decide.ts` 答 `422 parked_resume.startup_failed`,体只带 `cause`:
+ * 后台停驻子代的 parked 赎回不经本函数(引擎交的是赎回回执,不是 `CheckpointError`):`parked-decide.ts` 答 `422 parked_resume.startup_failed`,体带成因词 `cause`,
+ * 引擎 7.54.0 起回执的 `details.detail` 交出同三位判别位,经**同一只**读法 `resumeRefusalFacts` 落成同名三键(下面第二条)。键律:
  *  · `errorCode` —— 引擎码的原码镜像(`checkpoint.invalid_outcome` 按决断成因改铸,{@link decisionRefusalCauseOf});
  *  · 引擎 `detail` 的三个机读判别位原样过境,键名与 `resume_blocked_by_policy` 同义:`detail.code` ⇒ `blockedBy`(挡住它的准入码 = 同一份坏配置在新跑上报的 `errorCode`;
  *    今天只有 `checkpoint.config_refused` 带它)· `detail.field` ⇒ `field`(哪一侧 / 哪一格)· `detail.reason` ⇒ `reason`(同码多臂时哪一臂,闭集 `CheckpointErrorReason`)。