@sema-agent/server 7.145.0 → 7.146.0

package/dist/http/memory-compliance-failure-reply.js

@@ -1,5 +1,5 @@
-import { ControlPlaneCorruptError } from "@sema-agent/core";
 import { logStoreFormRefusal, storeFormRefusalOf } from "../memory-store-refusal.js";
+import { sentControlPlaneCorrupt } from "./memory-control-plane-corrupt-reply.js";
 import { sentMemoryStoreRefusal } from "./memory-store-refusal-reply.js";
 import { sendError } from "./send.js";
 import { assertNever } from "./route-ctx.js";
@@ -70,19 +70,6 @@ export function sentMemoryComplianceFailure(res, err, audience, logger) {
                 return assertNever(audience);
         }
     }
-    if (err instanceof ControlPlaneCorruptError) {
-        switch (audience.kind) {
-            case "operator":
-                sendError(res, 500, "internal.memory_control_plane_corrupt", err.message);
-                return true;
-            case "session_owner":
-                audience.withheld(err.message);
-                sendError(res, 500, "internal.memory_control_plane_corrupt", "session memory erasure could not be completed — this deployment's memory control plane could not be read cleanly (depending on where it stopped, either nothing was changed or the deletions were already committed and a replay finishes them); ask the operator to repair it, then resend with the same requestId");
-                return true;
-            default:
-                return assertNever(audience);
-        }
-    }
-    return false;
+    return sentControlPlaneCorrupt(res, err, audience);
 }
 //# sourceMappingURL=memory-compliance-failure-reply.js.map

package/dist/http/memory-control-plane-corrupt-reply.d.ts

@@ -0,0 +1,25 @@
+/**
+ * core 的 `ControlPlaneCorruptError` ⇒ typed 500 `internal.memory_control_plane_corrupt` 的 **HTTP 映射** —— 唯一一处码字面量、唯一一处 `instanceof` 判别。
+ *
+ * ## 为什么是一只
+ * 这是 core 的 fail-closed 信号:记忆引擎的控制面(账本 / 事务日志 / 清标账 / 治理账)说不清,它宁可不答,也不在一个说不清的账上拼一个答案。
+ * 凡是会碰控制面的 operator 记忆口,对它的答法必须是同一句话:消费端按 `errorCode` 分支,运维有具体动作(修 / 重建账本后重试)。
+ * 此前这条映射写在四个地方(导出 / 导入口、外源标记口、整理口、合规口),码字面量与判别各一份 = 第五个口加错码或漏一支的口子。
+ * 同族的店形拒早已是一只(`sentMemoryStoreRefusal`,在 `memory-store-refusal-reply.ts`);本文件是第二只。挂在每一个**已分类收尾**上:
+ * `routes/memory-bundle.ts`(导出 / 导入)· `routes/memory-origin.ts`(外源列表 / 清标 / 清标账列表 —— 清标账列表是纯控制面读,店形拒不挂在它上面,它的损坏信号走这一只)·
+ * `routes/memory-consolidation.ts`(整理)· `memory-compliance-failure-reply.ts`(出处 / 抹除,两受众)。
+ *
+ * ## 文案按受众分(码与状态不分;与 `memory-compliance-failure-reply.ts` 同一条规则)
+ *  · operator ⇒ 引擎原句上 wire(点名**哪一张**控制面账本坏了,运维下一步动作取决于它;原句带宿主路径,过了 operator 门的受众拿它不是泄露);
+ *  · 会话所有者(自助抹除口,只有这一个口有这个受众)⇒ 一句固定指路,引擎原句整句交 `withheld` 落运维行 —— 不逐句判断哪句安全。
+ *    固定句**一码两义都真**:操作前账本读不出 ⇒ 什么都没发生;落定后残留枚举失败 ⇒ 抹除已提交、重放收敛(core 原话)。两句都不许诺零删除,
+ *    都指路「运维修好后用同一个 requestId 重发」。本层**不**嗅 core 文案去分辨哪一义(拿上游自由文本当判别式是第二真源)。
+ *
+ * 两处 `sendError` 的码都写**字面量**:错误码目录门(`test/error-code-catalog-live.test.ts`)与文案冻结门(`test/api-error-text-freeze.test.ts`,
+ * 固定句是它冻的那一句)扫的是源码字面量,变量态的码 / 句对它们隐形。
+ */
+import type { ServerResponse } from "node:http";
+import type { MemoryComplianceAudience } from "./memory-compliance-failure-reply.js";
+/** `err` 是 core 的控制面损坏 ⇒ 500 `internal.memory_control_plane_corrupt`(文案按受众),返回 true(已应答);否则 false,一个字节都不写。 */
+export declare function sentControlPlaneCorrupt(res: ServerResponse, err: unknown, audience: MemoryComplianceAudience): boolean;
+//# sourceMappingURL=memory-control-plane-corrupt-reply.d.ts.map

package/dist/http/memory-control-plane-corrupt-reply.js

@@ -0,0 +1,19 @@
+import { ControlPlaneCorruptError } from "@sema-agent/core";
+import { assertNever } from "./route-ctx.js";
+import { sendError } from "./send.js";
+export function sentControlPlaneCorrupt(res, err, audience) {
+    if (!(err instanceof ControlPlaneCorruptError))
+        return false;
+    switch (audience.kind) {
+        case "operator":
+            sendError(res, 500, "internal.memory_control_plane_corrupt", err.message);
+            return true;
+        case "session_owner":
+            audience.withheld(err.message);
+            sendError(res, 500, "internal.memory_control_plane_corrupt", "session memory erasure could not be completed — this deployment's memory control plane could not be read cleanly (depending on where it stopped, either nothing was changed or the deletions were already committed and a replay finishes them); ask the operator to repair it, then resend with the same requestId");
+            return true;
+        default:
+            return assertNever(audience);
+    }
+}
+//# sourceMappingURL=memory-control-plane-corrupt-reply.js.map

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

@@ -72,8 +72,10 @@ export declare function sendPrincipalRefusal(res: ServerResponse, req: IncomingM
  * 每面一句模块级常量(冻结门按常量解引用逐字钉)。三句都**不含任何值**(令牌 / 头名 / 路径实参一概不回显),且**不区分**
  * 「没带」与「带错」—— 同一道门上两者逐字同体,区分就是探测面。
  *  · `credential` —— 全局凭据门(`dispatch.ts`):部署配了 service token,请求没带或带的不认(registry 登录令牌验不过同属此面);
- *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):不带主体头的 service token 开得了(带主体头的是那位主体,
- *    {@link actsForDeployment}),指标口另认只读的 `METRICS_TOKEN`、`source-summary` 另认只读的 `TRACE_TOKEN`(都在全局门之前判);
+ *  · `operator` —— 只给运维凭据开的口(`/metrics*` 与 `GET /v1/tasks/source-summary`):不带主体头的 service token 开得了 —— 在部署让它代自己说话时
+ *    ({@link actsForDeployment};带主体头的是那位主体;声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` 的部署上它不代任何人),指标口另认只读的 `METRICS_TOKEN`、
+ *    `source-summary` 另认只读的 `TRACE_TOKEN`(都在全局门之前判)。句子只有一句、两形都真:service token 那条出路带条件「在这台部署让它代自己说话时」,
+ *    并指 `/health` 的自报位 `auth.serviceTokenActsForDeployment` 去读这台部署的答案 —— 铸点不读配置、签名不变(一面一只常量);
  *  · `identity` —— 过了凭据门(或这台部署没配 service token)、但这一口要一个**验过的调用方身份**:属主寻址的读 / 写面、规则面、
  *    记忆面。在配了 service token 的部署上,「带 service token 却没身份」只会落在只认身份的口(规则 / 记忆 / 会话策略)上 ——
  *    这时再叫调用方「去带 service token」是假出路,所以这一面的句子只讲身份。
@@ -81,7 +83,7 @@ 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 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_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 where this deployment lets its service token act for the deployment itself (GET /health reports it as auth.serviceTokenActsForDeployment; 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;
 /**
@@ -128,15 +130,24 @@ export declare function wiredIdentitySources(w: IdentityWiring): readonly Identi
  */
 export declare function devOpenDeployment(w: IdentityWiring): boolean;
 /**
- * service 凭据**代部署本身**说话:出示了这台部署的 service 凭据({@link systemFor}),且不代任何验过的主体。带主体头的 service 凭据请求是前端(BFF)
- * 代那位主体发的 —— 它读那位主体,不读全舰队;部署姿态(单用户 / 多租)不改这一句(单用户形上的主体头同样是「这次请求为谁」)。
- * 两处读它:fleet 调用方的凭据臂({@link sessionCallerOf})与 `/metrics` 族的 service 臂(`dispatch.ts`)。先判凭据、后取主体:`principal` 只在出示了
- * service 凭据时才求值(调用点那一次 {@link gatedPrincipal}),没带凭据的请求不因主体头的形而改答。
+ * 🔴 **律(一句,一个参数)**:出示这台部署的 service 凭据且不报主体的调用方代部署本人说话(fleet),**除非部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false`**
+ * —— 此时它是无身份调用方,按各面既有的「过了凭据门、没有主体」那一臂答。带主体头的 service 凭据请求是前端(BFF)代那位主体发的 —— 它读那位主体,
+ * 不读全舰队(两形同读);部署姿态(单用户 / 多租)不改这一句(单用户形上的主体头同样是「这次请求为谁」)。
+ * 本函数是这条律的**唯一实施点**:声明位({@link ServiceConfig.serviceTokenActsForDeployment},env 一处)是这里的一个合取项,两个读者一次继承 ——
+ * fleet 调用方的凭据臂({@link sessionCallerOf})与 `/metrics` 族的 service 臂(`dispatch.ts`);不加拒码、不加闸点。自报位 `/health.auth.serviceTokenActsForDeployment`
+ * 投的是同一只读法({@link serviceTokenDeclaredActsForDeployment})与同一只武装谓词(`http/health-self-report.ts`)。先判声明与凭据、后取主体:`principal` 只在两者都成立时才求值(调用点那一次 {@link gatedPrincipal}),
+ * 没带凭据的请求不因主体头的形而改答。
  */
 export declare function actsForDeployment(req: IncomingMessage, config: ServiceConfig, principal: () => Principal | undefined): boolean;
+/**
+ * 声明位 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT` 的**唯一读法**:门({@link actsForDeployment})、自报位(`http/health-self-report.ts`)、起服行
+ * ({@link buildServiceTokenPostureNotice})三处都经它,不各写一份真值判断。只有字面 `true` 是「代部署本人」:`loadConfig` 恒写这一格(缺省 `true`),
+ * 绕过类型手搓的配置缺这一格 ⇒ 读作不代(fail-closed:安全轴上的缺席不静默放宽),三处同读 —— 不会出现「门收窄、自报位说缺席、起服行沉默」。
+ */
+export declare function serviceTokenDeclaredActsForDeployment(config: Pick<ServiceConfig, "serviceTokenActsForDeployment">): boolean;
 /**
  * 🔴 **「这个调用方是不是 fleet 调用方(看得到所有租户)」的唯一铸点**({@link SessionCaller}):验过的主体 + 是不是 fleet —— {@link devOpenDeployment} 上的任何
- * 调用方,或 {@link actsForDeployment}(出示 service 凭据、不报主体)。带主体头的是那位主体,不是 fleet;只读 trace token 不是 service 凭据;operator 不在这里
+ * 调用方,或 {@link actsForDeployment}(出示 service 凭据、不报主体,除非部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false`)。带主体头的是那位主体,不是 fleet;只读 trace token 不是 service 凭据;operator 不在这里
  * (运维口各自读 {@link explicitOperatorOk})。读者:会话行属主门(无主 placed 行的放行臂)与 fleet 面的 {@link fleetViewOf} —— 同一问一只读法。
  */
 export declare function sessionCallerOf(req: IncomingMessage, w: IdentityWiring): SessionCaller;
@@ -182,16 +193,28 @@ export declare function explicitOperatorOk(principal: string | undefined, roster
 /** 「这台部署**有没有**运维」的唯一读法(名单非空 ∨ 单用户声明在场)—— 能力事实 `operatorLane`、整理阀门的可达性告警、起服提示同读这一只。 */
 export declare function operatorRosterPresent(roster: OperatorRoster): boolean;
 /**
- * 起服提示([ref]):单用户形(`REQUIRE_PRINCIPAL` 未开)+ 没有运维名册 + 这台部署有审批底座 ⇒ 一行 warn。这一形在「空名单 = 人人是」那条读法退役之后
- * 丢的东西就是审批队列的运维视图(跨 scope 列表 / `?owner=` / 无主体调用方的整个队列),补回它只要一行配置 —— 不拒启:升级那一拍打掉一台今天跑得好好的
- * 单用户机器比一条提示重。多租形不提示(它另有拒启不变量);没有审批底座的形什么都没少。
+ * 起服提示([ref]):单用户形(`REQUIRE_PRINCIPAL` 未开)+ 没有运维名册 ⇒ 一行 warn。「空名单 = 人人是」那条读法退役之后这一形没有运维:
+ * 运维口(诊断 `GET /v1/diagnostics/wiring` —— 每台 main.ts 装起来的部署都挂着它 —— 、`GET /v1/outcomes`、管理与记忆治理口)对谁都答 501,
+ * 审批队列(挂着时)只给每个调用方看自己的;补回它们只要一行配置 —— 不拒启:升级那一拍打掉一台今天跑得好好的单用户机器比一条提示重。
+ * 多租形不提示(它另有拒启不变量)。
  */
-export declare function buildOperatorUndeclaredNotice(config: OperatorRoster & Pick<ServiceConfig, "requirePrincipal">, approvalFaceWired: boolean): {
+export declare function buildOperatorUndeclaredNotice(config: OperatorRoster & Pick<ServiceConfig, "requirePrincipal">): {
     event: "operator_undeclared_single_user";
     fields: {
         detail: string;
     };
 } | undefined;
+/**
+ * 起服一行:部署声明 `SERVICE_TOKEN_ACTS_FOR_DEPLOYMENT=false` ⇒ `service_token_posture { actsForDeployment: false }`(info);缺省不打。
+ * 声明形让运维面板开位当天成片 401,而「位关了」与「token 错了」在 wire 上同体(反探测律),这一行是起服时唯一一处说清这台部署选了哪一读法的地方。
+ * 不加逐请求事件(请求日志有 route / status,无凭据来源)。判据与字段单源在这里,装配处(`boot/stage-07-capability-layer.ts`)只调一次、原样打。
+ */
+export declare function buildServiceTokenPostureNotice(config: Pick<ServiceConfig, "serviceTokenActsForDeployment">): {
+    event: "service_token_posture";
+    fields: {
+        actsForDeployment: false;
+    };
+} | undefined;
 /** operator 面族在「名单为空」这一形上的**唯一**拒发口:事实 `operatorLane`(`capability-facts.ts`)为假 ⇒ 这一面对任何
  *  身份都打不通 = 这台部署上不可用 ⇒ 501,不是鉴权拒(403 只留给「名单非空而你不在名单上」)。能力位读的是同一只事实。 */
 export declare function sendOperatorPrincipalsRequired(res: ServerResponse): void;

package/dist/http/principal-gate.js

@@ -1,6 +1,6 @@
 import { timingSafeEqual } from "node:crypto";
 import { DEPLOYMENT_SHAPE_PREDICATES } from "../deployment-shape.js";
-import { PRINCIPAL_TOKEN_HEADER, verifiedPrincipal, ssoVerifiedPrincipal, ssoVerifiedPrincipalInc, ssoVerifiedScope, ownerlessRowOpen, mintPrincipal } from "../security.js";
+import { PRINCIPAL_TOKEN_HEADER, sameSessionOwner, verifiedPrincipal, ssoVerifiedPrincipal, ssoVerifiedPrincipalInc, ssoVerifiedScope, ownerlessRowOpen, mintPrincipal } from "../security.js";
 import { IDENTITY_SOURCES, runIdentityClaimOverflow } from "../identity-source.js";
 import { sendError } from "./send.js";
 export function headerStr(v) {
@@ -120,7 +120,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 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_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 where this deployment lets its service token act for the deployment itself (GET /health reports it as auth.serviceTokenActsForDeployment; 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) {
@@ -139,15 +139,10 @@ export function sendUnauthorized(res, face) {
         }
     }
 }
-function sameIdentity(principal, owner) {
-    return principal === owner;
-}
 export function runOwnerReadable(principal, owner, config) {
     if (owner === null)
         return true;
-    if (principal !== undefined && sameIdentity(principal, owner))
-        return true;
-    return !DEPLOYMENT_SHAPE_PREDICATES.principalRequired.holds(config) && owner === "anon:shell-live" && principal === undefined;
+    return sameSessionOwner(config, owner, principal ?? null);
 }
 export function hasServiceAuth(config) {
     return Boolean(config.authToken) || Object.keys(config.authTokens ?? {}).length > 0;
@@ -173,7 +168,10 @@ export function devOpenDeployment(w) {
     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;
+    return serviceTokenDeclaredActsForDeployment(config) && systemFor(req, config) !== undefined && principal() === undefined;
+}
+export function serviceTokenDeclaredActsForDeployment(config) {
+    return config.serviceTokenActsForDeployment === true;
 }
 export function sessionCallerOf(req, w) {
     const principal = gatedPrincipal(req, w.config);
@@ -211,18 +209,24 @@ export function explicitOperatorOk(principal, roster) {
 export function operatorRosterPresent(roster) {
     return roster.operatorSingleUser === true || roster.operatorPrincipals.length > 0;
 }
-export function buildOperatorUndeclaredNotice(config, approvalFaceWired) {
-    if (config.requirePrincipal === true || operatorRosterPresent(config) || !approvalFaceWired)
+export function buildOperatorUndeclaredNotice(config) {
+    if (config.requirePrincipal === true || operatorRosterPresent(config))
         return undefined;
     return {
         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 only the anonymous ones - the cards and tasks that were submitted without a principal - never a named principal's) and ignore ?owner=. " +
+                "operator-only endpoints such as GET /v1/diagnostics/wiring, GET /v1/outcomes and the admin and memory-governance endpoints answer 501 capability.operator_principals_required to every caller, and " +
+                "the approval queues (GET /v1/approvals, its stream, /v1/assistant/inbox and /v1/assistant/tasks, where mounted) 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",
         },
     };
 }
+export function buildServiceTokenPostureNotice(config) {
+    if (serviceTokenDeclaredActsForDeployment(config))
+        return undefined;
+    return { event: "service_token_posture", fields: { actsForDeployment: false } };
+}
 export function sendOperatorPrincipalsRequired(res) {
     sendError(res, 501, "capability.operator_principals_required", `this endpoint is operator-only and this deployment has no operator roster (OPERATOR_PRINCIPALS is empty and OPERATOR_SINGLE_USER is not declared), so no caller can be an operator; ${buildOperatorRosterWayOut()}`);
 }

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

@@ -1,5 +1,5 @@
 /**
- * 请求守门族([ref] 切片:`http/server.ts` 4837–5195 + `MAX_BODY` 逐字搬家,正文一字未改)。
+ * 请求守门族([ref] 切片:`http/server.ts` 4837–5195 逐字搬家,正文一字未改;JSON 体上限的数住叶子 `json-body-limit.ts`)。
  * 配额 / 租约 / 用量窗 / 限流 / owner-scope / 体读取 —— 每只守门的判据与它自己的头注原位随行。
  * ctx 字段 1 只(`deps`):本族对外围的耦合就这一格,它也是这一族的可测性读数。
  */

package/dist/http/request-guards.js

@@ -9,14 +9,14 @@ 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;
+import { MAX_JSON_BODY_BYTES } from "../json-body-limit.js";
 export function refuseSubmitBody(walls, body) {
     const rowWall = walls.maxRowBytes;
     const packetWall = walls.maxPacketBytes;
     const row = rowWall === null ? null : { wallBytes: rowWall, limitBytes: rowWallPayloadBytes(rowWall, "json") };
     const packet = packetWall === null ? null : { wallBytes: packetWall, limitBytes: packetWallStatementBytes(packetWall) };
-    const liveRow = row !== null && row.limitBytes < MAX_BODY ? row : null;
-    const livePacket = packet !== null && packet.limitBytes < 2 * MAX_BODY ? packet : null;
+    const liveRow = row !== null && row.limitBytes < MAX_JSON_BODY_BYTES ? row : null;
+    const livePacket = packet !== null && packet.limitBytes < 2 * MAX_JSON_BODY_BYTES ? packet : null;
     if (liveRow === null && livePacket === null)
         return null;
     const json = JSON.stringify(body);
@@ -228,8 +228,8 @@ export function createRequestGuards(ctx) {
         let size = 0;
         for await (const c of req) {
             size += c.length;
-            if (size > MAX_BODY)
-                throw bodyTooLargeError("request body too large", MAX_BODY);
+            if (size > MAX_JSON_BODY_BYTES)
+                throw bodyTooLargeError("request body too large", MAX_JSON_BODY_BYTES);
             chunks.push(c);
         }
         if (chunks.length === 0)

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

@@ -24,6 +24,28 @@ import type { createRequestGuards } from "./request-guards.js";
 import type { FlatServiceDeps } from "./server.js";
 import { type ResumeRefusalAnswer } from "./checkpoint-ctx.js";
 import { type ResumeRestatement } from "./resume-restatement.js";
+/**
+ * 🔴 **resume / 决断腿上一次 `CheckpointError` 拒的处置 —— 一张表:core 的码闭集 → 处置词**(唯一读口 {@link resumeRefusalDisposition};
+ * 7.113.0 提货车 UP ⑤ 起穷举,此前是 catch 臂里一串 `e.code === … ||` 手列)。
+ *
+ * doctrine(只写这一次):处置词说的是**这张卡与这条 run 行此刻的处境**,不是「重试会不会成」——
+ *  · `retriable` —— PRE-CAS 拒:**卡仍 pending ⇒ run 行重新 park**(`suspended` / `needs_review`),wire 体自述 `retriable:true`
+ *    (契约附录 A.1 注的定义:「卡仍 pending,不是『重试会成功』」)。出路(改那一格 / 重取坐标 / 回到写它的那一版引擎 / 换对 worker / 取消)
+ *    由码、`field`、`writerVersion` / `readerVersion` 与报文说,**不由 `retriable` 说**;
+ *  · `terminal`  —— 卡已消费 / 已不在 / 本腿读不懂 ⇒ 驱行终局,wire 体不带 `retriable`;
+ *  · `cancelled` —— 取消 ⇒ 取消终局。
+ * 行的落点与 wire 的 `retriable` 读**同一次**求值(catch 臂一处),所以同一处境只有一个答案。决断口 409 的成因({@link decisionRefusalCauseOf})只决定码名、
+ * 不另答处置:决断类三词都出自 `checkpoint.invalid_outcome`,落点读本表那一行。「停驻行的格式比本引擎新」只有 core 一个来源(`checkpoint.unsupported_version`
+ * + `version_newer` ⇒ `retriable`);续跑上下文的写者版本只让那一码的 409 体多带 `writerVersion` / `readerVersion` 两件事实,不参与判处置。
+ * 同码多铸点、可恢复性不同的码再按它自己的判别位闭集分(`"by_reason"` → {@link WORKER_SWAP_REDEEMABLE})。
+ * 表是 `Record<CheckpointError["code"], …>` ⇒ core 加一个码而本表没跟 = **tsc 红**(手列串的病:新码不在串里 ⇒ 静默落终局 —— core 7.39.0 的
+ * `checkpoint.config_refused` 提货当拍就是这样把一张 pending 卡孤儿化的,钉 `test/durable-resume-http.test.ts` [ref] 两格)。
+ *
+ * 驱终局为什么危险(原 catch 臂注,D-1 / core 1.101):PRE-CAS 拒时卡仍 pending,驱终局会释放 task_active 并孤儿化那张卡(下一次 /decide → 404);
+ * re-park 让改正后的重试能再认领。驱终局只给「卡已消费或已不在」的码,免得留一条僵尸 `running` 行让 reapStale 误标并攥着会话锁 ~runStaleSec。
+ */
+export type CheckpointErrorDispositionWord = "cancelled" | "retriable" | "terminal" | "by_reason";
+export declare const CHECKPOINT_ERROR_DISPOSITION: Readonly<Record<CheckpointError["code"], CheckpointErrorDispositionWord>>;
 /**
  * 🔴 **一次 `CheckpointError` 拒的处置 —— 唯一读口**:{@link CHECKPOINT_ERROR_DISPOSITION} 的读法(doctrine 在那张表头)。resume 腿的 catch 臂只调它一次,
  * 行的落点与 wire 的 `retriable` 都读这一个结果。纯函数,钉直接调。运行期遇到表外的码(装树 core 比本二进制多一个码的版本偏斜 —— 型面上拼不出来)

package/dist/http/resume-legs.js

@@ -1,6 +1,6 @@
 import { redactErrorMessage, redactHead } from "../observability/run-terminal.js";
 import { createHash } from "node:crypto";
-import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, taskNotificationDedupKey, validatePendingSteer, GLOBAL_USAGE_KEY } from "@sema-agent/core";
+import { uuidv7, resumeWithVerification, CheckpointError, judgeCheckpointRow, defaultTaskRegistry, taskNotificationDedupKey, validatePendingSteer, GLOBAL_USAGE_KEY } from "@sema-agent/core";
 import { decideParkedAgent, denyWorkflowParkForked, denyWorkflowParksUnreadable, findParkOrigin, heldWorkflowParkDecisions, planWorkflowParkedDecide } from "../parked-decide.js";
 import { parkDecisionFingerprint } from "../orchestration/workflow-park-decision.js";
 import { headReadOf } from "../session-incarnation.js";
@@ -22,7 +22,7 @@ import { approverFacingArgs, createApprovalCardEmitter, declaredApprovalFrameFam
 import { buildCheckpointAnchorHash } from "../approval-ask-audit-store.js";
 import { APPROVAL_ENDING_CAUSES } from "../approval-deny-reasons.js";
 import { serviceVersion } from "../service-version.js";
-import { TERMINAL_PARK_GATE_KINDS } from "../plugins/checkpoint-store-sql.js";
+import { TERMINAL_PARK_GATE_KINDS, UnreadableCheckpointRowError } from "../plugins/checkpoint-store-face.js";
 import { withPrincipal } from "../observability/principal-context.js";
 import { withModelReachScope } from "../model-reach-scope.js";
 import { legFactsOf } from "../leg-facts.js";
@@ -103,7 +103,7 @@ const WORKER_SWAP_REDEEMABLE = {
 function checkpointRowRedeemableElsewhere(reason) {
     return reason !== undefined && WORKER_SWAP_REDEEMABLE[reason] === true;
 }
-const CHECKPOINT_ERROR_DISPOSITION = {
+export const CHECKPOINT_ERROR_DISPOSITION = {
     "checkpoint.resume_aborted": "cancelled",
     "checkpoint.invalid_outcome": "retriable",
     "checkpoint.reopen_revote": "retriable",
@@ -208,6 +208,15 @@ function approvalStaleAnswer(facts) {
         }),
     };
 }
+function rowRefusalMessageOf(verdict, diagnostic) {
+    if (verdict.kind === "ok")
+        return undefined;
+    return diagnostic === undefined ? verdict.sentence : `${verdict.sentence} Diagnostic: ${diagnostic}`;
+}
+function unreadableRowMessageOf(e) {
+    const text = e instanceof Error ? e.message : String(e);
+    return (e instanceof UnreadableCheckpointRowError ? rowRefusalMessageOf(e.rowVerdict, text) : undefined) ?? text;
+}
 function acceptableFormFacts(detail) {
     const rewritten = detail !== null && typeof detail === "object" ? detail.editRewritten : undefined;
     if (rewritten === null || typeof rewritten !== "object" || !Object.hasOwn(rewritten, "acceptableForm"))
@@ -241,7 +250,7 @@ export function decidedActionOf(binding) {
     return missingKeys.length === 0 ? { action: { boundCallId: boundCallId, boundInputHash: boundInputHash } } : { missingKeys };
 }
 export function createResumeLegs(ctx) {
-    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
+    const { deps, runnerFor, idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters, readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, admitRun, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk, prepareSpec, finalizeTaskResult, ownerCostQuotaDenied, ownerFleetLeaseDenied, usageWindowDenialFor } = ctx;
     const ctxOpening = (sessionId) => ({ sessionId, opener: deps.checkpointCtxSealing });
     const resumeFleetScope = (req, auth) => req ? (gatedPrincipal(req, deps.config) ?? "default") : (auth.principal ?? "default");
     async function resumeCheckpoint(sessionId, decision, reason, hostDecision, req, answer, binding, onResumeCommitted, acceptEarly, decider, restatement) {
@@ -303,7 +312,7 @@ export function createResumeLegs(ctx) {
                 deps.logger?.warn?.("approval_decide_unreadable_row_withheld", { sessionId, note: "row unreadable and the caller's ownership of THAT token is unproven — folded into the uniform 404" });
                 return noApproval;
             }
-            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: e instanceof Error ? e.message : String(e) }) };
+            return { status: 409, body: refusalBody({ errorCode: "conflict.checkpoint_unreadable", message: unreadableRowMessageOf(e) }) };
         }
         if (!cp) {
             if (!(await mayDiscloseRowError(cs, token, decider)))
@@ -319,20 +328,20 @@ export function createResumeLegs(ctx) {
         }
         const decideGateKind = cp.gate?.kind;
         if (!isApprovalGateKind(decideGateKind)) {
-            const activeForPath = decideGateKind
-                ? await deps.runStore?.getActiveTaskId(sessionId).catch(() => undefined)
-                : undefined;
-            const gnPath = decideGateKind && activeForPath
-                ? resumeEntryForGate(decideGateKind, { sessionId, taskId: activeForPath })
-                : null;
+            if (typeof decideGateKind !== "string" || decideGateKind === "") {
+                const rowSentence = rowRefusalMessageOf(judgeCheckpointRow(cp));
+                if (rowSentence !== undefined)
+                    return { status: 409, body: refusalBody({ errorCode: "gate_not_tool_approval", message: rowSentence }) };
+                return { status: 409, body: refusalBody({ errorCode: "gate_not_tool_approval", message: "task is suspended on a gate whose kind this engine cannot read, so it cannot say which endpoint resolves it" }) };
+            }
+            const activeForPath = await deps.runStore?.getActiveTaskId(sessionId).catch(() => undefined);
+            const gnPath = activeForPath ? resumeEntryForGate(decideGateKind, { sessionId, taskId: activeForPath }) : null;
             return {
                 status: 409,
                 body: refusalBody({
                     errorCode: "gate_not_tool_approval",
-                    message: `task is suspended on a '${decideGateKind ?? "unknown"}' gate, not a tool approval — a plan_review gate is resolved via POST /v1/assistant/tasks/:id/plan_review, a resource_limit suspension via POST /v1/assistant/tasks/:id/resume`,
-                    facts: {
-                        ...(decideGateKind ? { pendingGate: { kind: decideGateKind, ...(gnPath ? { decidePath: gnPath } : {}) } } : {}),
-                    },
+                    message: `task is suspended on a '${decideGateKind}' gate, not a tool approval — a plan_review gate is resolved via POST /v1/assistant/tasks/:id/plan_review, a resource_limit suspension via POST /v1/assistant/tasks/:id/resume`,
+                    facts: { pendingGate: { kind: decideGateKind, ...(gnPath ? { decidePath: gnPath } : {}) } },
                 }),
             };
         }
@@ -747,7 +756,7 @@ export function createResumeLegs(ctx) {
         let resumeLegLive = false;
         const subagentHandleEvictions = [];
         let claimedRow = false;
-        const cancelCtrl = createRunAbort();
+        const cancelCtrl = createRunAbort(principal ?? null);
         let cancelLedgerAppend;
         const preemptCtrl = new AbortController();
         if (taskId && deps.runStore) {
@@ -1662,7 +1671,7 @@ export function createResumeLegs(ctx) {
     const routeCtxBase = {
         deps,
         registry: { idemCache, inflightRuns, preemptableRuns, steerableRuns, wakeParkMints, counters },
-        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk },
+        helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, admitRun, safeDecode, runOwnerOk, sessionOwnerOk, runSessionAcceptOk },
         local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal(), capabilities: createCapabilitiesLocal() },
         legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, preparePlanReview, drivePlanReview, sessionNotify: sessionNotifyDoor },
     };

package/dist/http/route-ctx.d.ts

@@ -79,6 +79,12 @@ export interface RouteHelpers {
     ownerLeaseDenied(res: ServerResponse, owner: string | undefined): Promise<boolean>;
     /** [ref]-T1:治理窗 pre-admission(异步 202 车道的唯一 429 出路;key 公式与 core 单源)。 */
     usageWindowDenied(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+    /**
+     * 在飞 run 并发帽的提交门准入(`RUN_MAX_CONCURRENT*`,缺省关;判据、席位与拒的形全文在 `http/run-concurrency-cap.ts`):放行 ⇒ 席位(登记那一拍与 `finally` 放);
+     * 超帽 ⇒ 已应答 429 + `Retry-After`、回 `undefined`。只挂**新提交**门(`createDurableRun` / `POST /v1/tasks` / `POST /v1/tasks/stream`),
+     * 排在幂等重放与 `usageWindowDenied` 之后、任何建行 / 认领 / SSE 头之前。
+     */
+    admitRun(req: IncomingMessage, res: ServerResponse): import("./run-concurrency-cap.js").RunSlot | undefined;
     safeDecode(seg: string): string | null;
     /** run 面的属主门(谓词 `runOwnerReadable`;非属主 ⇒ 404 `not_found.run` + 长文,与 run 读口的 unknown 臂同码同串,[ref])。 */
     runOwnerOk(req: IncomingMessage, res: ServerResponse, owner: string | null): boolean;
@@ -191,17 +197,10 @@ export interface CheckpointCtx {
      * 传原 ctx / 其展开 ⇒ 标随行。缺席 = 不是无人值守腿(HTTP 提交腿;7.106.0 前落盘的行 —— 那时这些腿不铸模式,checkpoint 里也没有)。
      */
     unattendedLeg?: true;
-    /**
-     * 体里 `settings.permissions.allow` 的**读法记号**(闭集只有当前读法一词 `"allow_layer"`):在场 = 这一行是当前读法下写下的、体里带非空 `allow`,
-     * 它按「交给引擎的 allow 层」写、也按它读。**服务端写、不来自请求体**(与 {@link unattendedLeg} 同为 `body` 的兄弟键)。
-     * 缺席(≤7.114.0,名单时代)或旧词 `"statement"`(7.115.0–7.116.x,表态时代)而体里带非空 `allow` ⇒ 续跑腿响亮拒、行字节不动(规则与删除条件的属主 = `http/checkpoint-ctx.ts` 顶注)。
-     * 写点只有 `buildCheckpointCtx`(同模块;新的持久化写);续跑腿的写回传原 ctx / 其展开 ⇒ 记号随行。体里没有 `allow` 的行不写它。
-     */
-    permissionsAllowReading?: import("./checkpoint-ctx.js").PermissionsAllowReading;
     /**
      * 体里**模式词的读法记号**(闭集只有当前一词 `"entry_word"`):在场 = 这一行体的顶层 `permissionMode` 是这条 run 模式词唯一的源(提交入口盖过运维
      * `AUTONOMY=plan` 的地板;`plan_review` 写回改它),续跑照它读。**服务端写、不来自请求体**。缺席(7.121.x 及以前写下的行 —— 那时运维的 plan 由治理层每段重钳)
-     * 而本部署此刻有入口地板、体的词被地板钳会变 ⇒ 续跑腿响亮拒、行字节不动(规则与删除条件的属主 = `http/checkpoint-ctx.ts` 顶注第三问)。
+     * 而本部署此刻有入口地板、体的词被地板钳会变 ⇒ 续跑腿响亮拒、行字节不动(规则与删除条件的属主 = `http/checkpoint-ctx.ts` 顶注「模式词问」)。
      * 写点两个(写模式词的人盖记号,同模块):`buildCheckpointCtx`(每一次新的持久化写都写)与 `withPermissionModeRewritten`(`plan_review` 改词的写回);
      * 不改词的续跑腿写回传原 ctx ⇒ 记号随行。
      */
@@ -210,8 +209,10 @@ export interface CheckpointCtx {
      * 🔴 [ref] —— **写这份上下文的服务版本**(`package.json` 的 `version`),**服务端写、不来自请求体**(与 {@link unattendedLeg} 同为 `body` 的兄弟键)。
      * 写点两个:`buildCheckpointCtx`(每一次新的持久化写)与续跑腿的写回({@link DriveResumeArgs.resumeCtx} 的唯一写点,CAS 赢点盖本进程的版本 —— 接下来写下一张停车行的就是它)。
      * 读者:`checkpoint.unsupported_version` 的 409 体 —— 原样带出 `writerVersion`,与本引擎的 `readerVersion` 并列(运维据此知道该回哪一版去决);
-     * 两键唯一铸法 `checkpoint-ctx.ts` `buildCheckpointVersionKeys`,本码每个铸点同调。它是**上下文**,不是拒因:成因与码都不读它。
-     * 缺席 = 本版之前写下的行(不回填):那一码的体不带两键,如实不猜。不是一次性迁移 —— 这一格是常设的事实位,没有删除条件。
+     * 两键唯一铸法 `checkpoint-ctx.ts` `buildCheckpointVersionKeys`,本码每个铸点同调。
+     * 另一个读者(唯一的拒因读者):存体重放判据的 allow 读法问(`checkpoint-ctx.ts` 顶注)—— 体里带非空 `settings.permissions.allow` 而本格证不出 ≥ 7.117.0 ⇒ 拒。
+     * 所以写点守一条律:盖本格的写只在本进程按当前读法读过这份体之后(新提交;或已过存体重放判据的续跑写回),在判据之前盖 = 把旧行洗成新行。
+     * 缺席 = 7.124.0 之前写下的行(不回填):那一码的体不带两键,如实不猜;allow 读法问把它读作「证不出」。不是一次性迁移 —— 这一格是常设的事实位,没有删除条件。
      */
     writerVersion?: string;
     /**

package/dist/http/route-table.js

@@ -4,6 +4,7 @@ import { handleDiagnostics, DIAGNOSTICS_ROUTES } from "./routes/diagnostics.js";
 import { handleAdoption, ADOPTION_ROUTES } from "./routes/adoption.js";
 import { handleRetention, RETENTION_ROUTES } from "./routes/retention-ops.js";
 import { handleAdminDrain, ADMIN_DRAIN_ROUTES } from "./routes/admin-drain.js";
+import { handleEngine, ENGINE_ROUTES } from "./routes/engine.js";
 import { handleDevices, DEVICES_ROUTES } from "./routes/devices.js";
 import { handleAdminConfigRefresh, ADMIN_CONFIG_REFRESH_ROUTES } from "./routes/admin-config-refresh.js";
 import { handleConfigCatalog, CONFIG_CATALOG_ROUTES } from "./routes/config-catalog.js";
@@ -65,6 +66,7 @@ export const ROUTES = [
     row({ handler: handleAdoption, decls: ADOPTION_ROUTES, position: "post-credential", label: "adoption" }),
     row({ handler: handleRetention, decls: RETENTION_ROUTES, position: "post-credential", label: "retention" }),
     row({ handler: handleAdminDrain, decls: ADMIN_DRAIN_ROUTES, position: "post-credential", label: "admin-drain" }),
+    row({ handler: handleEngine, decls: ENGINE_ROUTES, position: "post-credential", label: "engine" }),
     row({ handler: handleDevices, decls: DEVICES_ROUTES, position: "post-credential", label: "devices" }),
     row({ handler: handleAdminConfigRefresh, decls: ADMIN_CONFIG_REFRESH_ROUTES, position: "post-credential", label: "admin-config-refresh" }),
     row({ handler: handleConfigCatalog, decls: CONFIG_CATALOG_ROUTES, position: "post-credential", label: "config-catalog" }),

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

@@ -18,6 +18,11 @@
  * 一次落库,此后原样回放)。并发同参 POST 由 `adoption_log.from_principal` 的 UNIQUE 仲裁:恰一行落库,
  * 两条连接拿到同一个 adoptionId、同一份回执。
  *
+ * ── 第二条车道:源主体的批量导入 `POST /v1/adoption/:id/sessions` ─────────────────────────────────────────────
+ * 不是 operator 面:调用者是那条收编行的**源主体本人**(逐字;operator 不能代),把本地会话导进目的主体名下。门序 = 身份(401)→ 设施(501)→
+ * 行(404 `not_found.adoption`)→ 源主体(403 `auth.adoption_source_only`,不降级成 404:无行与不匹配同形是一种查不出根因的二义)→ 收编态
+ * (409 `adoption.not_adopted`)→ 体形(400)→ 条数帽(400)→ 逐元素(200 + 结局数组)。判断全在 `adoption/import.ts`,本模块只下发。
+ *
  * 分层:本模块不值 import `server.ts`(那条边闭合运行时装载环),只 `import type`。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
@@ -33,6 +38,12 @@ export declare const ADOPTION_ROUTES: readonly [{
     readonly pattern: RegExp;
     readonly label: "/v1/adoption/:id";
     readonly methods: readonly ["GET"];
+}, {
+    readonly id: "adoption-sessions-import";
+    readonly pattern: RegExp;
+    readonly label: "/v1/adoption/:id/sessions";
+    readonly credentialGated: readonly ["POST"];
+    readonly methods: readonly ["POST"];
 }];
 /** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
 export type AdoptionRouteId = RouteIdsOf<typeof ADOPTION_ROUTES>;