@sema-agent/server 7.120.0 → 7.121.0

package/dist/http/health-self-report.js

@@ -0,0 +1,53 @@
+import { IDENTITY_SOURCES } from "./principal-gate.js";
+import { operatorLane, sessionList } from "../capability-facts.js";
+import { authBridgeIssuerOf } from "../auth-bridge.js";
+import { centerLaneConfigured } from "../config-center/center-request.js";
+import { buildDisplaySafeUrl } from "../trace/redact.js";
+export const IDENTITY_ATTACH_WORDS = ["available", "unavailable"];
+export const OPERATOR_PRESENCE_WORDS = ["present", "absent"];
+export const SESSIONS_VISIBLE_VALUES = [true, false, "unknown"];
+function carriesCallerIdentity(kind) {
+    switch (kind) {
+        case "service_token":
+            return false;
+        case "sso":
+        case "direct_door_jwt":
+            return true;
+        default: {
+            const unknownKind = kind;
+            throw new Error(`health self-report: unknown identity source ${String(unknownKind)}`);
+        }
+    }
+}
+function identitySourceWired(kind, a) {
+    switch (kind) {
+        case "service_token":
+            return a.credentialGateArmed;
+        case "sso":
+            return a.bridgeWired;
+        case "direct_door_jwt":
+            return a.directDoorActive;
+        default: {
+            const unknownKind = kind;
+            throw new Error(`health self-report: unknown identity source ${String(unknownKind)}`);
+        }
+    }
+}
+export function buildHealthSelfReport(deps, credentialGateArmed) {
+    const { config } = deps;
+    const bridgeWired = deps.registryJwtVerifier !== undefined;
+    const kinds = IDENTITY_SOURCES.filter((k) => identitySourceWired(k, { credentialGateArmed, bridgeWired, directDoorActive: config.directDoorActive }));
+    const issuer = authBridgeIssuerOf(config)?.issuer;
+    const webBaseUrl = config.configCenter?.webBaseUrl;
+    const sessionsVisible = centerLaneConfigured(config) && config.fleetAdvertiseAddress !== undefined && bridgeWired && sessionList(deps).available ? (config.requirePrincipal ? true : "unknown") : false;
+    return {
+        auth: { required: credentialGateArmed, kinds, identityAttach: kinds.some(carriesCallerIdentity) ? "available" : "unavailable" },
+        operator: operatorLane(deps).available ? "present" : "absent",
+        center: {
+            ...(issuer !== undefined ? { issuer: buildDisplaySafeUrl(issuer) } : {}),
+            ...(webBaseUrl !== undefined ? { webBaseUrl: buildDisplaySafeUrl(webBaseUrl) } : {}),
+            sessionsVisible,
+        },
+    };
+}
+//# sourceMappingURL=health-self-report.js.map

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

@@ -13,13 +13,20 @@ export declare function systemFor(req: IncomingMessage, config: ServiceConfig):
 export declare function bearerPresentedButUnverified(req: IncomingMessage, config: ServiceConfig): boolean;
 /** loopback 三形(IPv4 / IPv6 / IPv4-mapped)—— 一处定义,diagnostics 门与任何「本机自用」判据同吃。缺席 ⇒ false(fail-closed)。 */
 export declare function isLoopbackAddress(addr: string | undefined): boolean;
+/**
+ * 验过的身份来源的**闭集**(序 = `/health.auth.kinds` 的出现序)。{@link verifiedIdentitySource} 的回值就是这张表的词;
+ * `/health` 的自报位(`http/health-self-report.ts`)读同一张表,答「这台部署的装配**能**回哪几个词」—— 加一个来源 = 加一个词,
+ * 两边各自的穷举 `switch` 不接就编译红。
+ */
+export declare const IDENTITY_SOURCES: readonly ["service_token", "sso", "direct_door_jwt"];
+export type IdentitySource = (typeof IDENTITY_SOURCES)[number];
 /**
  * 这次请求的身份是不是**密码学验过**的(而不是调用方自述的 header):`sso` = registry JWT(入口预认证的签名真源)/
  * `direct_door_jwt` = direct-door principal JWT 验过 / `service_token` = 出示了单一或 per-system service token。
  * 缺席 = 只有自述头或什么都没有。一处判定(7.63.0 codex [high]+[medium]):off-box 读 operator 面的门用它——名单只在
  * 有可验身份时才是身份,零凭据下它只是谁都能写的字符串;而 JWT 身份不依赖静态 token 的在场。
  */
-export declare function verifiedIdentitySource(req: IncomingMessage, config: ServiceConfig): "sso" | "direct_door_jwt" | "service_token" | undefined;
+export declare function verifiedIdentitySource(req: IncomingMessage, config: ServiceConfig): IdentitySource | undefined;
 export declare function gatedPrincipal(req: IncomingMessage, config: ServiceConfig): string | undefined;
 /**
  * 「**出示了凭证但验不过** ≠ **没出示**」在 **direct-door principal JWT** 面上的形 —— 本仓

package/dist/http/principal-gate.js

@@ -37,6 +37,7 @@ export function bearerPresentedButUnverified(req, config) {
 export function isLoopbackAddress(addr) {
     return addr === "127.0.0.1" || addr === "::1" || addr === "::ffff:127.0.0.1";
 }
+export const IDENTITY_SOURCES = ["service_token", "sso", "direct_door_jwt"];
 export function verifiedIdentitySource(req, config) {
     if (ssoVerifiedPrincipal(req))
         return "sso";

package/dist/http/readiness.d.ts

@@ -22,6 +22,7 @@
  * 模块形:纯叶(只值 import `send.ts`)—— `fleet-client.ts` / `boot/` 都会读它,不许长出回环。
  */
 import type { ServerResponse } from "node:http";
+import type { ServingLeaseView } from "../fleet/engine-signal.js";
 /**
  * 就绪原因闭集,**数组序 = 优先序**:`/health.readyReason` 取首条的句、计费门取首条的拒绝码。
  * draining 在前 —— 一台正在下线的副本「去找替补」(Retry-After 15)比「稍后重试本机」(5)更对。
@@ -61,6 +62,26 @@ export declare function healthReadinessKeys(v: ReadinessVerdict): Record<string,
 /** `/readyz` 两形:200 `{ready:true}` / 503 `{ready:false, reasons}` + `Retry-After: 5`。体只这两键(不带身份字段:
  *  就绪探针给 k8s readinessProbe / Traefik / LB 摘流用,不是 `/health` 的替身;`drainReason` 等运维自由文本也不上这一面)。 */
 export declare function sendReadyz(res: ServerResponse, v: ReadinessVerdict): void;
+/**
+ * 编排器片 2 件 2 —— 计费面请求的**种类**(闭集;路由声明表 `billable` 列的取值,`http/route-ctx.ts`):
+ *  · `submit`      —— 起一轮**新**工作(新任务 / 新 run / leader / side-query / wake / 记忆整理 / A2A `message/send`);
+ *  · `hitl-answer` —— 对一张已经在等人的卡作答(耐久 `/decide`、计划审阅、PARKED 停驻卡的赎回);
+ *  · `resume`      —— 续跑一条已经存在的 run(助手 resume、子代 resume)。
+ */
+export declare const BILLABLE_KINDS: readonly ["submit", "hitl-answer", "resume"];
+export type BillableKind = (typeof BILLABLE_KINDS)[number];
+/**
+ * 计费面的拒因(**数组序 = 优先序**):就绪原因({@link READINESS_REASONS})∪ `lease_expired`(服务租约过期且中心不可达满 `T_max`)。
+ * `lease_expired` 刻意不是就绪原因:它不翻 `/readyz`(中心不可达不是本实例的病,摘它出路由只会把取消 / HITL / 读面一起摘掉)。
+ */
+export declare const ADMISSION_REFUSALS: readonly ["draining", "model_roster_pending", "lease_expired"];
+export type AdmissionRefusal = (typeof ADMISSION_REFUSALS)[number];
+/**
+ * 计费面请求的**唯一**准入判(dispatch 的计费门、a2a `message/send`、PARKED 赎回席同调):按 {@link ADMISSION_REFUSALS} 序找第一条
+ * 成立且按 {@link ADMISSION_TABLE} 拒这一种的拒因;没有 ⇒ `undefined`(放行)。入参是**判决**而不是 deps:就绪判由调用点经唯一谓词
+ * {@link readinessOf} 现读(模块边界上那一只 —— 谓词单源钉注入它,任何读点自己读 `drainState` 都会当场红),租约读数取 `deps.servingLease`。
+ */
+export declare function admissionRefusalOf(verdict: ReadinessVerdict, lease: ServingLeaseView | undefined, kind: BillableKind): BillableRefusal | undefined;
 /** 计费提交门的拒绝(首条 reason 定码)。`retryAfterSec` 由发送形(`sendBillableRefusal`)镜像成头;交回
  *  `{status, body}` 的赎回席只取体(它的路由刻意不带头,见 `approval-sweeps.ts` 该臂注)。 */
 export interface BillableRefusal {
@@ -69,17 +90,16 @@ export interface BillableRefusal {
         readonly error: string;
         readonly errorCode: string;
         readonly message: string;
-        readonly reason?: string;
     };
-    readonly retryAfterSec: 15 | 5;
+    readonly retryAfterSec: 15 | 5 | 60;
 }
 /**
  * 计费提交门的拒绝体 —— **唯一铸点**(`error` 字面 `"draining"` / `"model_roster_pending"` 与 `message` 是冻结的
  * wire 契约:SDK / 壳的 pre-stream 重试按它们判型;冻结在 `test/api-error-text-freeze.test.ts` 的
- * `FROZEN_RESULT_BODY` 与 `test/api-notice-text-freeze.test.ts` §2)。`drainReason` = `POST /v1/admin/drain`
- * 声明的停机因由([ref],additive 键 `reason`;未声明 = 键缺席)。
+ * `FROZEN_RESULT_BODY` 与 `test/api-notice-text-freeze.test.ts` §2)。编排器片 2:排空体的 `reason` 键随
+ * 停机因由声明口一起退役(排空口的体改成契约 `DrainRequest`,没有因由字段);`lease_expired` 一臂新增。
  */
-export declare function billableRefusalOf(v: NotReadyVerdict, drainReason: string | undefined): BillableRefusal;
+export declare function billableRefusalOf(reason: AdmissionRefusal): BillableRefusal;
 /** 发送形:`Retry-After` + 体(`dispatch.ts` 的 billable 门与 a2a `message/send` 同调)。走 `sendError` —— errorCode
  *  是它的必填位置参(对抗复审 #3:修前这里是 `sendJson(res, r.status, r.body)`,与 leader 口的豁免行逐字同文,
  *  在 error-code-key-gate 上借了别人的豁免过门);体键序与修前逐字同(`error, errorCode, message, reason?`)。 */

package/dist/http/readiness.js

@@ -33,16 +33,41 @@ export function sendReadyz(res, v) {
     res.setHeader("retry-after", "5");
     sendJson(res, 503, { ready: false, reasons: [...v.reasons] });
 }
-export function billableRefusalOf(v, drainReason) {
-    const primary = v.reasons[0];
-    switch (primary) {
+export const BILLABLE_KINDS = ["submit", "hitl-answer", "resume"];
+export const ADMISSION_REFUSALS = [...READINESS_REASONS, "lease_expired"];
+const ADMISSION_TABLE = {
+    draining: { submit: true, "hitl-answer": false, resume: false },
+    model_roster_pending: { submit: true, "hitl-answer": true, resume: true },
+    lease_expired: { submit: true, "hitl-answer": false, resume: false },
+};
+export function admissionRefusalOf(verdict, lease, kind) {
+    const holdsNow = (r) => {
+        switch (r) {
+            case "draining":
+            case "model_roster_pending":
+                return !verdict.ready && verdict.reasons.includes(r);
+            case "lease_expired":
+                return lease?.state === "expired" && lease.pastOutageMax;
+            default: {
+                const unhandled = r;
+                throw new Error(`admission refusal without a predicate arm: ${String(unhandled)}`);
+            }
+        }
+    };
+    const refusal = ADMISSION_REFUSALS.find((r) => holdsNow(r) && ADMISSION_TABLE[r][kind]);
+    return refusal === undefined ? undefined : billableRefusalOf(refusal);
+}
+export function billableRefusalOf(reason) {
+    switch (reason) {
         case "draining":
-            return { status: 503, body: { error: "draining", errorCode: "draining", message: "this instance is draining for shutdown/upgrade — retry against the replacement instance", ...(drainReason ? { reason: drainReason } : {}) }, retryAfterSec: 15 };
+            return { status: 503, body: { error: "draining", errorCode: "draining", message: "this instance is draining for shutdown/upgrade — retry against the replacement instance" }, retryAfterSec: 15 };
         case "model_roster_pending":
             return { status: 503, body: { error: "model_roster_pending", errorCode: "state.model_roster_pending", message: "this worker has no model yet (waiting for the first effective-config pull to land the roster) — retry shortly" }, retryAfterSec: 5 };
+        case "lease_expired":
+            return { status: 503, body: { error: "lease_expired", errorCode: "state.lease_expired", message: "this instance has not renewed its serving lease with the fleet center for longer than its outage limit — it takes no new work; cancel, approvals, resume and reads stay open here — retry new work against another instance" }, retryAfterSec: 60 };
         default: {
-            const unhandled = primary;
-            throw new Error(`readiness reason without a billable refusal: ${String(unhandled)}`);
+            const unhandled = reason;
+            throw new Error(`admission refusal without a billable refusal: ${String(unhandled)}`);
         }
     }
 }

package/dist/http/resume-legs.js

@@ -582,7 +582,7 @@ export function createResumeLegs(ctx) {
         let unregisterEngineNotice;
         try {
             const instructionLeg = createInstructionSelectionLeg();
-            result = await instructionLeg.run(sessionId, () => withModelReachScope(sessionId, () => withPrincipal(principal, async () => {
+            result = await instructionLeg.run(sessionId, () => withModelReachScope({ sessionId, taskId }, () => withPrincipal(principal, async () => {
                 const resumeNotifiedKeys = new NotifiedKeys();
                 if (deps.runStore && taskId) {
                     const rs0 = deps.runStore;

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

@@ -569,10 +569,12 @@ export type RouteMethod = "GET" | "POST" | "PUT" | "DELETE";
  *  `satisfies` 让它与 {@link RouteMethod} 双向闭合:漏一个动词 / 多一个都是编译红。 */
 export declare const ROUTE_METHOD_ORDER: readonly ["GET", "POST", "PUT", "DELETE"];
 export interface RouteDeclFacts {
-    /** 「这条 url **烧模型**」—— drain / model-roster-pending / 无 service-token 三道 503 的共同判别。
-     *  没有这一列 = 不烧模型(零默认值:要它为真必须显式写出来,漏写的方向是**少收一笔账单**而不是
-     *  少一道门 —— 反了才是灾难,所以三道门读的是 true 这一侧)。 */
-    readonly billable?: true;
+    /** 「这条 url **烧模型**」—— drain / model-roster-pending / 租约过期 / 无 service-token 四道 503 的共同判别。
+     *  没有这一列 = 不烧模型(零默认值:要它在场必须显式写出来,漏写的方向是**少收一笔账单**而不是
+     *  少一道门 —— 反了才是灾难,所以门读的是在场这一侧)。
+     *  编排器片 2 件 2:值 = 这一种计费请求的**种类**(`submit` 新工作 / `hitl-answer` 对等人的卡作答 / `resume` 续跑;闭集属主
+     *  `http/readiness.ts` 的 `BILLABLE_KINDS`)—— 排空与租约过期只拒 `submit`(放行闭集表 `ADMISSION_TABLE`),无凭证门不看种类。 */
+    readonly billable?: import("./readiness.js").BillableKind;
     /** 「本条 url 在**没有任何 service credential** 的部署形下,这几个方法必须 fail-closed」。
      *  判据(两个合取项)= 「授权的唯一输入是 principal 头」∧「持久改写,或爆炸半径跨租户的治理读」;
      *  逐口论证在各 `routes/*.ts` 的头注里,声明行只记结论。 */

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

@@ -54,6 +54,7 @@
 import type { FlatServiceDeps } from "./server.js";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteDecl, RouteDispatchDecl, RouteMatch, RouteCtx, RouteMethod } from "./route-ctx.js";
+import type { BillableKind } from "./readiness.js";
 /** 一只域 handler 相对**全局服务凭据门**的位置。门前 = 未鉴权可达(每一只都要单独论证),门后 = 先过凭据。 */
 /**
  * 一行路由在全局服务凭据门的哪一侧、吃哪道门(闭集,三员;S-672 起由两员拆成三员):
@@ -133,6 +134,8 @@ export declare function matchDecl(d: RouteDispatchDecl, url: string): Readonly<R
 export declare function routeLabel(_method: string, url: string): string;
 /** POST endpoints that trigger BILLABLE work — the fail-closed auth guard must cover ALL of them. */
 export declare function isBillableSubmitPath(url: string): boolean;
+/** 编排器片 2 件 2:这条 url 是哪一**种**计费请求(`undefined` = 不在计费面)。声明序第一条命中的行定种类(今天每条 url 至多命中一行)。 */
+export declare function billableKindOf(url: string): BillableKind | undefined;
 /** [ref]([ref] 件5)—— **改写门**:不烧模型、但在没有任何 service credential 的部署形下必须
  *  与 billable / bake 两族一样 fail-closed 的写门。与 `isBillableSubmitPath` **刻意分开**:这几扇门
  *  `billable=false`(零模型工作),塞进那张名单会让它们连带吃 drain 与 roster-pending 两道 503 ——

package/dist/http/route-table.js

@@ -109,7 +109,7 @@ export function matchDecl(d, url) {
 const NO_PARAMS = Object.freeze({});
 const LABEL_BY_PATH = new Map(ROUTE_DECLARATIONS.flatMap((d) => ("path" in d ? [[d.path, d.path]] : [])));
 const SHAPED_LABEL_DECLS = ROUTE_DECLARATIONS.filter((d) => !("path" in d) && typeof d.label === "string");
-const BILLABLE_DECLS = ROUTE_DECLARATIONS.filter((d) => d.billable === true);
+const BILLABLE_DECLS = ROUTE_DECLARATIONS.filter((d) => d.billable !== undefined);
 const METHOD_DISPATCHED_DECLS = ROUTE_DECLARATIONS.filter((d) => d.methodDispatched === true);
 const CREDENTIAL_GATED_BY_METHOD = (() => {
     const m = new Map();
@@ -135,6 +135,9 @@ export function routeLabel(_method, url) {
 export function isBillableSubmitPath(url) {
     return BILLABLE_DECLS.some((d) => declMatches(d, url));
 }
+export function billableKindOf(url) {
+    return BILLABLE_DECLS.find((d) => declMatches(d, url))?.billable;
+}
 export function isCredentialGatedRewrite(method, url) {
     const rows = CREDENTIAL_GATED_BY_METHOD.get(method.toUpperCase());
     return rows !== undefined && rows.some((d) => declMatches(d, url));

package/dist/http/routes/a2a-serve.d.ts

@@ -79,7 +79,7 @@ export type A2aServeRouteId = RouteIdsOf<typeof A2A_SERVE_ROUTES>;
 export declare const A2A_RPC_ROUTES: readonly [{
     readonly id: "a2a-rpc";
     readonly path: "/v1/a2a";
-    readonly billable: true;
+    readonly billable: "submit";
     readonly methodDispatched: true;
     readonly methods: readonly ["POST"];
 }];

package/dist/http/routes/a2a-serve.js

@@ -5,7 +5,7 @@ import { isParkedRunStatus, isTerminalRunStatus } from "../../plugins/store-cont
 import { HttpError } from "../../security.js";
 import { scopedIdempotencyKey } from "../idempotency.js";
 import { sendJson, sendError } from "../send.js";
-import { readinessOf, billableRefusalOf, sendBillableRefusal } from "../readiness.js";
+import { admissionRefusalOf, readinessOf, sendBillableRefusal } from "../readiness.js";
 import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
@@ -168,10 +168,10 @@ function rpcErrorFromTypedFailure(err, skillId) {
 }
 function submitUnavailable(res, ctx) {
     const { deps } = ctx;
-    const verdict = readinessOf(deps);
-    if (verdict.ready)
+    const refusal = admissionRefusalOf(readinessOf(deps), deps.servingLease?.(), "submit");
+    if (refusal === undefined)
         return false;
-    sendBillableRefusal(res, billableRefusalOf(verdict, deps.drainState?.reason));
+    sendBillableRefusal(res, refusal);
     return true;
 }
 function readBlocking(params) {
@@ -392,6 +392,6 @@ export const A2A_SERVE_ROUTES = [
     { id: "a2a-agent-card", path: "/.well-known/agent-card.json", methods: ["GET"] },
 ];
 export const A2A_RPC_ROUTES = [
-    { id: "a2a-rpc", path: "/v1/a2a", billable: true, methodDispatched: true, methods: ["POST"] },
+    { id: "a2a-rpc", path: "/v1/a2a", billable: "submit", methodDispatched: true, methods: ["POST"] },
 ];
 //# sourceMappingURL=a2a-serve.js.map

package/dist/http/routes/admin-drain.d.ts

@@ -1,40 +1,21 @@
 /**
- * [ref](C17,[ref]/[ref] 认领,黑板 [ref] 原文即本口的契约):`POST /v1/admin/drain {reason}` ——
- * 编排壳在发停机信号(SIGTERM)**之前**先调本口显式声明停机因由;server 记入 `drainState.reason`,
- * draining 期间由 `/health`(`drainReason`)与 503 draining 体(`reason`)透出。未声明 = 两面键缺席
- * (additive,不编数)——升级/缩容/驱逐在消费端因此可判别,而不是一律读成「实例没了」。
+ * `POST /v1/admin/drain` —— 排空口(编排器长远稿片 2 件 2;契约体 = settings-schema 8.1.0 `DrainRequest`,回执 = `DrainReceipt`)。
  *
- * 族属 = adoption / retention-ops 的 operator lane(同一条 `explicitOperatorOk` 门、billable=false、
- * **刻意不吃 drain 503**——它正是 drain 开始前要调的口,吃了就自锁)。门序照 retention-ops 逐字:
- * 身份 → 授权 → 验型。刻意**不进** `isCredentialGatedRewrite` 名单:那族的判据是「授权唯一输入是
- * service token ∧ 爆炸半径跨租户持久改写」,本口只写一个进程内观测字段(重启即逝、零持久面),
- * operator 门(空表恒拒,fail-closed)已是正确强度。
- *
- * reason 校验:非空 trim 后 string ≤ {@link MAX_DRAIN_REASON_CHARS} —— 它会进 /health 与 503 体
- * (消费面是监控/壳),超长或怪型响亮拒([ref] 坏值立律),拒绝不留痕(不写半个值)。
- *
- * 🔴 **写侧特权、读侧公开 —— 这条不对称是刻意的,但必须被写的人知道**([ref],2026-08-19 合并重扫
- * partial,存活断言):本口是 operator-only + fail-closed(空 `OPERATOR_PRINCIPALS` 恒拒),而透出面里
- * `/health` 在 `server.ts` 的鉴权门**之前**、无鉴权、缺省全网卡监听,USAGE 三处白纸黑字把它定为「无需
- * 鉴权」—— 任何能连到这个端口的人都读得到这段**运维手打的自由文本**。
- * **裁定:行为不改。** 判据三条:① `/health` 免鉴权是既成契约,而它正是这条信息的设计消费者(k8s
- * probe / LB / 编排器带不了 token,`drainReason` 放这儿的全部理由就是给它们看);② 值的内容完全由
- * operator 自选,且窗口只在 draining 期;③ 同一免鉴权体上早已有 `dataRoot` 绝对路径 / `pid` / `port` /
- * `instanceId` / `configHash` / `storeProbe`,单独收紧本键不改变那面的暴露量级。
- * (那条另立的兄弟件 —— `storeProbe.error` 把**原始异常 message 未截断**塞出去、DSN 片段可随之外泄 ——
- * 已在 [ref] 修掉:免鉴权面上它改成闭集词,原文只走日志轴。两件的判据不同故不合并:本键的值由 operator
- * 自选且窗口只在 draining 期,`storeProbe.error` 的值则来自不受控的驱动异常。)
- * ⇒ 真正的缺口是**告诫缺席**:此前路由头注、400 文案、CHANGELOG、wire 契约四处都只说「透出」,没有一处
- * 说「其中一面免鉴权」,操作员要拼出「我写的字是公开的」得自己合并两处文档去推理。本批把它写进**写口
- * 现场**(400 文案 + 本注 + USAGE 端点条目),因为那是操作员唯一会读到的地方。
- * 词表化(把自由文本换成受限枚举)= 行为变更,**不在本批**:它会让「rolling upgrade to 7.36.0」这类真正
- * 有用的因由说不出来,取舍要属主拍。
+ * 一只入口的 HTTP 车道(Docker 车道 / 中心直调 / 人手形):体经契约读器 `readDrainRequest`(一处判形),身份四元经
+ * `fleet/drain-entry.ts` 的 `drainIdentityMismatches`(一处判身份;本引擎的 scope = `config.fleetScope`,env `FLEET_SCOPE` 的唯一读数),
+ * 进入排空经 `drainState.enter`(收尾链装的唯一入口)。
+ *  · 门序 = operator 面的既有口径(`routes/retention-ops.ts` 逐字):身份 → 授权 → 验型;billable=false,**刻意不吃排空 503**
+ *    (排空中的重放必须能拿到 `already_draining` 回执,吃了就自锁)。
+ *  · 体坏 ⇒ 400 `request.field_invalid`(零状态变化);身份不符 ⇒ 409 `conflict.fleet_identity`(零状态变化;拒句点名不符的字段,不回显值);
+ *    没有收尾链(嵌入宿主 / 测试夹具)⇒ 501 `capability.drain_state_required`。
+ *  · 首次 ⇒ 200 回执 `state:"draining"`;同一 `actionId`(或别的动作)再来 ⇒ 200 `already_draining`,回显第一次的 `since` / `deadlineAt`,不重置。
+ *  · 人手形:`actionId` 自取(推荐 `manual:<uuid>`),身份照样四元比对 —— 非 fleet 成员不带 `expectedGeneration`(缺席对缺席);
+ *    `instanceId` 在场才比(从本机 `/health` 读);不带 `scope` = 点名缺省 scope(多租引擎要带它自己的 `FLEET_SCOPE`)。
+ * 修前形(7.35.0 起的 `{reason}` 停机因由声明:只记一句话、不进排空)随契约体退役 —— 零别名;那一形的请求体读不成 `DrainRequest` ⇒ 400。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 export declare const ADMIN_DRAIN_PATH = "/v1/admin/drain";
-/** 上限与 approvals 的 reason 族同量级(消费面同为人读短句;非同一常量——两面语义无关,独立演化)。 */
-export declare const MAX_DRAIN_REASON_CHARS = 256;
 export declare function handleAdminDrain(req: IncomingMessage, res: ServerResponse, match: RouteMatch<AdminDrainRouteId>, ctx: RouteCtx): Promise<void>;
 export declare const ADMIN_DRAIN_ROUTES: readonly [{
     readonly id: "admin-drain";

package/dist/http/routes/admin-drain.js

@@ -1,9 +1,11 @@
+import { readDrainRequest } from "@sema-agent/settings-schema/fleet";
 import { sendJson, sendError } from "../send.js";
 import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sendPrincipalRefusal } from "../principal-gate.js";
 import * as facts from "../../capability-facts.js";
+import { fleetScopeOf } from "../../config-types.js";
+import { drainIdentityMismatches } from "../../fleet/drain-entry.js";
 import { assertNever } from "../route-ctx.js";
 export const ADMIN_DRAIN_PATH = "/v1/admin/drain";
-export const MAX_DRAIN_REASON_CHARS = 256;
 const OPERATOR_ONLY_MESSAGE = "drain declaration is operator-only: the caller principal is not in OPERATOR_PRINCIPALS";
 export async function handleAdminDrain(req, res, match, ctx) {
     const { deps } = ctx;
@@ -22,18 +24,22 @@ export async function handleAdminDrain(req, res, match, ctx) {
                 sendError(res, 403, "auth.operator_only", OPERATOR_ONLY_MESSAGE);
                 return;
             }
-            const body = (await ctx.helpers.readJson(req));
-            const reason = body?.reason;
-            if (typeof reason !== "string" || reason.trim().length === 0 || reason.length > MAX_DRAIN_REASON_CHARS) {
-                sendError(res, 400, "request.field_invalid", `the drain reason is surfaced verbatim on the UNAUTHENTICATED /health endpoint (and in 503 draining bodies), so anyone who can reach this port can read it — do not put ticket ids, hostnames, or internal identifiers in it. body must be { reason: string }: a non-empty string of at most ${MAX_DRAIN_REASON_CHARS} characters`);
+            const request = readDrainRequest(await ctx.helpers.readJson(req));
+            if (request === undefined) {
+                sendError(res, 400, "request.field_invalid", "the drain request must be { actionId, worker, deadlineAt, scope?, expectedGeneration?, instanceId?, term? }: actionId a non-empty idempotency key, worker this engine's worker name, deadlineAt epoch milliseconds, expectedGeneration a canonical decimal string (\"7\") — nothing was changed");
                 return;
             }
-            if (!deps.drainState) {
-                sendError(res, 501, "capability.drain_state_required", "this deployment has no drain state wired (embedded in another process?) — the declared reason would have nowhere to surface");
+            const enter = deps.drainState?.enter;
+            if (enter === undefined) {
+                sendError(res, 501, "capability.drain_state_required", "this deployment has no drain entry wired (embedded in another process?) — there is no drain for this request to enter");
                 return;
             }
-            deps.drainState.reason = reason.trim();
-            sendJson(res, 200, { ok: true });
+            const mismatched = drainIdentityMismatches(request, { scope: deps.config.fleetScope, worker: deps.config.configCenter?.worker, generation: deps.config.fleetGeneration, instanceId: deps.instanceId });
+            if (mismatched.length > 0) {
+                sendError(res, 409, "conflict.fleet_identity", `the drain request names a different instance than this engine (mismatched: ${mismatched.join(", ")}) — nothing was changed; compare with this engine's GET /health (worker comes from SEMA_REGISTRY_WORKER, generation from FLEET_GENERATION, scope from FLEET_SCOPE — unset, and a request without scope, mean "${fleetScopeOf(undefined)}")`);
+                return;
+            }
+            sendJson(res, 200, enter({ actionId: request.actionId, deadlineAt: request.deadlineAt }));
             return;
         }
         default:

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

@@ -183,17 +183,17 @@ export declare const APPROVALS_ASSISTANT_ROUTES: readonly [{
     readonly id: "assistant-task-resume";
     readonly pattern: RegExp;
     readonly label: "/v1/assistant/tasks/:id/resume";
-    readonly billable: true;
+    readonly billable: "resume";
     readonly methods: readonly ["POST"];
 }, {
     readonly id: "assistant-task-plan-review";
     readonly pattern: RegExp;
     readonly label: "/v1/assistant/tasks/:id/plan_review";
-    readonly billable: true;
+    readonly billable: "hitl-answer";
     readonly methods: readonly ["POST"];
 }, {
     readonly prefix: "/v1/approvals";
-    readonly billable: true;
+    readonly billable: "hitl-answer";
 }];
 /** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
 export type ApprovalsAssistantRouteId = RouteIdsOf<typeof APPROVALS_ASSISTANT_ROUTES>;

package/dist/http/routes/approvals-assistant.js

@@ -917,9 +917,9 @@ export const APPROVALS_ASSISTANT_ROUTES = [
     { id: "approval-exemptions-list", pattern: /^\/v1\/approvals\/(?<sessionId>[^/]+)\/exemptions(?:\/(?<tool>[^/]+))?$/, label: "/v1/approvals/:id/exemptions", methods: ["GET"] },
     { id: "approval-exemption-delete", pattern: /^\/v1\/approvals\/(?<sessionId>[^/]+)\/exemptions(?:\/(?<tool>[^/]+))?$/, label: "/v1/approvals/:id/exemptions", methods: ["DELETE"] },
     { id: "assistant-task-preempt", pattern: /^\/v1\/assistant\/tasks\/(?<taskId>[^/]+)\/preempt$/, label: "/v1/assistant/tasks/:id/preempt", methods: ["POST"] },
-    { id: "assistant-task-resume", pattern: /^\/v1\/assistant\/tasks\/(?<taskId>[^/]+)\/resume$/, label: "/v1/assistant/tasks/:id/resume", billable: true, methods: ["POST"] },
-    { id: "assistant-task-plan-review", pattern: /^\/v1\/assistant\/tasks\/(?<taskId>[^/]+)\/plan_review$/, label: "/v1/assistant/tasks/:id/plan_review", billable: true, methods: ["POST"] },
-    { prefix: "/v1/approvals", billable: true },
+    { id: "assistant-task-resume", pattern: /^\/v1\/assistant\/tasks\/(?<taskId>[^/]+)\/resume$/, label: "/v1/assistant/tasks/:id/resume", billable: "resume", methods: ["POST"] },
+    { id: "assistant-task-plan-review", pattern: /^\/v1\/assistant\/tasks\/(?<taskId>[^/]+)\/plan_review$/, label: "/v1/assistant/tasks/:id/plan_review", billable: "hitl-answer", methods: ["POST"] },
+    { prefix: "/v1/approvals", billable: "hitl-answer" },
 ];
 const DECISION_DOOR_KEY_TABLE = deriveDecisionDoorKeyTable(DECISION_DOOR_FAMILY, APPROVALS_ASSISTANT_ROUTES);
 //# sourceMappingURL=approvals-assistant.js.map

package/dist/http/routes/capabilities.js

@@ -79,7 +79,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                     : false,
                 sessionEvents: facts.sessionEventStream(deps).available,
                 fleet: facts.fleetStream(deps).available
-                    ? { stream: true, sessionScope: true, observe: true, resume: "snapshot", bgNotifyFailClosed: true, steerPriority: "engine", hookFailureNotice: true }
+                    ? { stream: true, sessionScope: true, observe: true, resume: "snapshot", bgNotifyFailClosed: true, steerPriority: "engine", hookFailureNotice: true, leaseClient: true, generationEcho: true }
                     : false,
                 workspace: facts.workspaceBrowse().available,
                 leader: facts.leaderLane(deps).available,
@@ -130,6 +130,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 readFace: deps.config.readFace ?? null,
                 writeProtection: projectWriteProtectionCapability(deps.writeProtection),
                 appendSystemPrompt: true,
+                outputStyle: true,
                 compactionModel: true,
                 subagentOutput: facts.subagentOutput(deps).available,
                 subagentStream: facts.subagentOutput(deps).available,

package/dist/http/routes/devices.js

@@ -8,6 +8,7 @@ import { deviceOwnerDomainOf } from "../device-placement.js";
 import { echoKeyName } from "../../request-key-closure.js";
 const DEVICE_NOT_FOUND_MESSAGE = "device not found";
 const NO_DEVICE_DOMAIN_MESSAGE = "device management needs a caller domain: this credential carries no verified tenant scope claim (registry auth-bridge JWT `scope`) and is not an explicit operator — connect through the registry auth bridge, or configure OPERATOR_PRINCIPALS";
+const NO_ENROLL_DOMAIN_MESSAGE = "device enrollment needs a registry login that carries a tenant scope: this credential carries no verified tenant scope claim (registry auth-bridge JWT `scope`), and an operator principal carries no scope, so it cannot enroll a device or issue an enroll token — connect through the registry auth bridge with a tenant-scoped login";
 const DEVICE_LANE_REQUIRED_MESSAGE = "device management requires the device execution lane (REMOTE_EXEC=device with a SQL store backend) — this deployment has no device lane wired";
 const _deviceRouteCodesPinned = ["not_found.device", "device.rebind_rev_conflict", "device.rebind_active_run"];
 void _deviceRouteCodesPinned;
@@ -164,7 +165,7 @@ export async function handleDevices(req, res, match, ctx) {
     }
     if (match.decl.id === "device-enroll-tokens") {
         if (domain === undefined) {
-            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
+            sendError(res, 403, "auth.forbidden", NO_ENROLL_DOMAIN_MESSAGE);
             return;
         }
         if ((await readClosedBody(req, res, readJson, [])) === null)
@@ -180,7 +181,7 @@ export async function handleDevices(req, res, match, ctx) {
     }
     if (match.decl.id === "device-enroll") {
         if (domain === undefined) {
-            sendError(res, 403, "auth.forbidden", NO_DEVICE_DOMAIN_MESSAGE);
+            sendError(res, 403, "auth.forbidden", NO_ENROLL_DOMAIN_MESSAGE);
             return;
         }
         const raw = await readClosedBody(req, res, readJson, ENROLL_BODY_KEYS);

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

@@ -16,7 +16,7 @@ export declare function handleLeader(req: IncomingMessage, res: ServerResponse,
 export declare const LEADER_ROUTES: readonly [{
     readonly id: "leader-submit";
     readonly path: "/v1/leader";
-    readonly billable: true;
+    readonly billable: "submit";
     readonly methods: readonly ["POST"];
 }, {
     readonly id: "leader-detail";

package/dist/http/routes/leader.js

@@ -51,7 +51,7 @@ export async function handleLeader(req, res, match, ctx) {
     throw new Error(`leader endpoint did not claim its own declared route: ${match.decl.id}`);
 }
 export const LEADER_ROUTES = [
-    { id: "leader-submit", path: LEADER_SUBMIT_PATH, billable: true, methods: ["POST"] },
+    { id: "leader-submit", path: LEADER_SUBMIT_PATH, billable: "submit", methods: ["POST"] },
     { id: "leader-detail", pattern: /^\/v1\/leader\/(?<id>[^/]+)$/, label: "/v1/leader/:id", methods: ["GET"] },
 ];
 //# sourceMappingURL=leader.js.map

package/dist/http/routes/memory-consolidation.d.ts

@@ -58,7 +58,7 @@ export declare function handleMemoryConsolidation(req: IncomingMessage, res: Ser
 export declare const MEMORY_CONSOLIDATION_ROUTES: readonly [{
     readonly id: "memory-consolidation-run";
     readonly path: "/v1/admin/memory/consolidation/run";
-    readonly billable: true;
+    readonly billable: "submit";
     readonly methods: readonly ["POST"];
 }, {
     readonly id: "memory-consolidation-status";

package/dist/http/routes/memory-consolidation.js

@@ -163,7 +163,7 @@ export async function handleMemoryConsolidation(req, res, match, ctx) {
     }
 }
 export const MEMORY_CONSOLIDATION_ROUTES = [
-    { id: "memory-consolidation-run", path: MEMORY_CONSOLIDATION_RUN_PATH, billable: true, methods: ["POST"] },
+    { id: "memory-consolidation-run", path: MEMORY_CONSOLIDATION_RUN_PATH, billable: "submit", methods: ["POST"] },
     { id: "memory-consolidation-status", path: MEMORY_CONSOLIDATION_STATUS_PATH, methods: ["GET"] },
 ];
 //# sourceMappingURL=memory-consolidation.js.map

package/dist/http/routes/notify-wake.d.ts

@@ -22,7 +22,7 @@ export declare const NOTIFY_WAKE_ROUTES: readonly [{
     readonly id: "session-wake";
     readonly pattern: RegExp;
     readonly label: "/v1/sessions/:id/$verb";
-    readonly billable: true;
+    readonly billable: "submit";
     readonly methods: readonly ["POST"];
 }, {
     readonly id: "session-notify";

package/dist/http/routes/notify-wake.js

@@ -143,7 +143,7 @@ export async function handleNotifyWake(req, res, match, ctx) {
     }
 }
 export const NOTIFY_WAKE_ROUTES = [
-    { id: "session-wake", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/wake$/, label: "/v1/sessions/:id/$verb", billable: true, methods: ["POST"] },
+    { id: "session-wake", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/wake$/, label: "/v1/sessions/:id/$verb", billable: "submit", methods: ["POST"] },
     { id: "session-notify", pattern: /^\/v1\/sessions\/(?<sessionId>[^/]+)\/notify$/, label: "/v1/sessions/:id/$verb", methods: ["POST"] },
 ];
 //# sourceMappingURL=notify-wake.js.map

package/dist/http/routes/rules.js

@@ -4,7 +4,7 @@ import { gatedPrincipal, explicitOperatorOk, sendOperatorPrincipalsRequired, sen
 import { assertNever } from "../route-ctx.js";
 import * as facts from "../../capability-facts.js";
 import { createLogger } from "../../observability/logger.js";
-import { RULE_IMPORT_RETRY_AFTER_SEC, RULE_SCOPE_REFUSAL_SENTENCE, MAX_RULE_SCOPE_CHARS, parseRuleScope, serializeRuleScope } from "../../rules-consent.js";
+import { RULE_IMPORT_RETRY_AFTER_SEC, RULE_SCOPE_REFUSAL_SENTENCE, MAX_RULE_SCOPE_CHARS, buildCcImportLayerRootRefusal, parseRuleScope, serializeRuleScope } from "../../rules-consent.js";
 import { CONTROL_AND_BIDI_CHARS } from "../../text-bidi.js";
 import { HttpError } from "../../security.js";
 import { MAX_RULE_TEXT_CHARS, RULE_BEHAVIORS, isValidDurableScope } from "@sema-agent/core";
@@ -173,8 +173,9 @@ export async function handleRules(req, res, match, ctx) {
             sendError(res, 400, "request.body_shape", "body must be {layers:[{layer,path,root,content}]}");
             return;
         }
-        if (parsed.data.layers.some(ccImportRootRefused)) {
-            sendError(res, 400, "request.body_shape", RULE_SCOPE_REFUSAL_SENTENCE);
+        const refusedLayer = parsed.data.layers.findIndex(ccImportRootRefused);
+        if (refusedLayer >= 0) {
+            sendError(res, 400, "request.body_shape", buildCcImportLayerRootRefusal(refusedLayer));
             return;
         }
         const prepared = await lane.prepareImport(principal, parsed.data.layers);

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

@@ -40,7 +40,7 @@ idemKey: string | undefined): Promise<{
 export declare const RUNS_ROUTES: readonly [{
     readonly id: "runs-submit";
     readonly path: "/v1/runs";
-    readonly billable: true;
+    readonly billable: "submit";
     readonly methods: readonly ["POST"];
 }, {
     readonly id: "run-steer";
@@ -99,7 +99,7 @@ export declare const RUN_VERBS_ROUTES: readonly [{
     readonly id: "run-subagent-resume";
     readonly pattern: RegExp;
     readonly label: "/v1/runs/:id/subagents/:sub/*";
-    readonly billable: true;
+    readonly billable: "resume";
     readonly methods: readonly ["POST"];
 }, {
     readonly id: "run-task-output";