@sema-agent/server 7.120.0 → 7.122.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

@@ -29,7 +29,7 @@ import { reasoningDeltaBytes, reasoningSegmentEventId } from "../trace/model-seg
 import { errorText } from "../observability/err-text.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { verifyRoundsFromBody } from "./verify-rounds.js";
-import { storedBodyPermissionMode } from "../task-settings.js";
+import { planReviewDecisionExitsPlan, storedBodyPermissionMode } from "../task-settings.js";
 import { acceptedResumingReceipt, buildHostLegOutcome } from "./route-ctx.js";
 import { mintAndDriveDurableRun } from "./durable-run-leg.js";
 import { createSessionsLocal } from "./routes/sessions.js";
@@ -43,7 +43,8 @@ import { commitSessionInheritEnv } from "./session-inherit-env.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "../approval-content-kind.js";
 import { deploymentListAsks } from "../approval.js";
 import { readResumeCtx, resumeCtxCorruptAnswer } from "./resume-ctx-read.js";
-import { resumeBlockedByPolicyAnswer, storedBodyReplayAnswer, storedBodyReplayLogFields, storedBodyReplayRefusal } from "./checkpoint-ctx.js";
+import { resumeBlockedByPolicyAnswer, storedBodyReplayAnswer, storedBodyReplayLogFields, withPermissionModeRewritten } from "./checkpoint-ctx.js";
+import { storedBodyReplayRefusal } from "./stored-body-replay.js";
 import { httpErrorCode } from "./send.js";
 function isCheckpointReopenedFailure(r) {
     const code = failureCodeOf(r.terminal);
@@ -422,7 +423,7 @@ export function createResumeLegs(ctx) {
         return storedBodyReplayAnswer(refusal);
     };
     const resolveResumeSpecOrBlocked = async (ctx, req, auth) => {
-        const replay = storedBodyReplayRefusal(ctx);
+        const replay = storedBodyReplayRefusal(ctx, deps.config.autonomy);
         if (replay !== undefined)
             return { ok: false, answer: refuseStoredBodyReplay(auth.sessionId, replay) };
         try {
@@ -582,7 +583,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;
@@ -1352,7 +1353,7 @@ export function createResumeLegs(ctx) {
             return refuse(resumeCtxCorruptAnswer(ctxRead.where));
         if (ctxRead.kind === "absent")
             return refuse({ status: 409, body: { error: "resume context missing — cannot rebuild task config", errorCode: "conflict.resume_context_unavailable" } });
-        const replay = storedBodyReplayRefusal(ctxRead.ctx);
+        const replay = storedBodyReplayRefusal(ctxRead.ctx, deps.config.autonomy);
         if (replay !== undefined)
             return refuse(refuseStoredBodyReplay(sessionId, replay));
         return { ok: true, prepared: { sessionId, token, cp, ctx: ctxRead.ctx } };
@@ -1364,11 +1365,10 @@ export function createResumeLegs(ctx) {
         const auth = { sessionId: cp.sessionId, principal: decodeCheckpointScope(cp.scope), memoryScope: ctx.memoryScope };
         const effMode = storedBodyPermissionMode(ctx.body);
         if (permissionModeAfter !== undefined && effMode !== "plan") {
-            throw new Error("drivePlanReview: permissionModeAfter was passed for a task that was not submitted with permissionMode \"plan\" — the caller must refuse this before any state changes (see the plan_review route's pre-nonce gate)");
+            throw new Error("drivePlanReview: permissionModeAfter was passed for a task whose stored permission mode is not \"plan\" — the caller must refuse this before any state changes (see the plan_review route's pre-nonce gate)");
         }
-        const approvedMode = decision === "approve" && effMode === "plan" ? (permissionModeAfter ?? "default") : undefined;
-        const resumeBody = approvedMode === undefined ? ctx.body : { ...ctx.body, permissionMode: approvedMode };
-        const rebuildCtx = { ...ctx, body: resumeBody };
+        const approvedMode = planReviewDecisionExitsPlan(decision) && effMode === "plan" ? (permissionModeAfter ?? "default") : undefined;
+        const rebuildCtx = approvedMode === undefined ? ctx : withPermissionModeRewritten(ctx, { ...ctx.body, permissionMode: approvedMode });
         const resolved = await resolveResumeSpecOrBlocked(rebuildCtx, req, auth);
         if (!resolved.ok)
             return resolved.answer;

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

@@ -168,6 +168,14 @@ export interface CheckpointCtx {
      * 写点只有 `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` 顶注第三问)。
+     * 写点两个(写模式词的人盖记号,同模块):`buildCheckpointCtx`(每一次新的持久化写都写)与 `withPermissionModeRewritten`(`plan_review` 改词的写回);
+     * 不改词的续跑腿写回传原 ctx ⇒ 记号随行。
+     */
+    permissionModeReading?: import("./checkpoint-ctx.js").PermissionModeReading;
 }
 /** B4①(命名化):`driveResumeIntoRunLog` 的入参形(resume 家族共用)——原为 9 成员内联匿名对象。 */
 export interface DriveResumeArgs {
@@ -448,8 +456,8 @@ export interface RouteLegs {
     drivePlanReview(prepared: PreparedPlanReview, decision: "approve" | "edit" | "reject", editedPlan: string | undefined, reason: string | undefined, req: IncomingMessage | undefined, 
     /** [ref] 件 S-1:透传给 {@link DriveResumeArgs.acceptEarly}(200 受理语义)。HTTP `/plan_review` 腿传 `true`。 */
     acceptEarly?: boolean, 
-    /** S-433:批准之后这条会话继续用的 permission mode(闭集 `PLAN_APPROVE_PERMISSION_MODES_AFTER`;只在 `approve`
-     *  上有意义,缺席 ⇒ `"default"`)。语义与判据的唯一属主 = `resume-legs.ts` 的同名形参顶注。 */
+    /** S-433:批准之后这条会话继续用的 permission mode(闭集 `PLAN_APPROVE_PERMISSION_MODES_AFTER`;只在把计划带出 plan 的决定
+     *  —— `approve` / `edit` —— 上有意义,缺席 ⇒ `"default"`)。语义与判据的唯一属主 = `resume-legs.ts` 的同名形参顶注。 */
     permissionModeAfter?: PlanApprovePermissionModeAfter): Promise<{
         status: number;
         body: object;
@@ -569,10 +577,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` 的头注里,声明行只记结论。 */
@@ -584,7 +594,7 @@ export interface RouteDeclFacts {
      *  503 照旧罩着(它判的是「这台机能不能收写」,与方法无关,且必须在解析请求体之前)。 */
     readonly methodDispatched?: true;
 }
-/** **可分派行**多出来的两列(S-146 第三刀):身份 + 它真认的方法。纯门行两列都没有(见下)。 */
+/** **可分派行**多出来的列(S-146 第三刀):身份 + 它真认的方法(+ S-1281 的订阅类)。纯门行一列都没有(见下)。 */
 interface RouteDeclIdentity {
     /** **全表唯一**的行名(kebab 闭集词)。这是声明行的身份:域 handler 用
      *  `switch (match.decl.id)` 闭集分派(漏一口 = 编译红),所以它必须稳定、唯一、且与路径解耦
@@ -599,6 +609,14 @@ interface RouteDeclIdentity {
      *     ② 2 条「一条路径住着两只域」的跨域行按方法拆成两行各归各域(`/v1/tasks` = trace-usage 的 GET +
      *     tasks 的 POST;`/v1/memory/export` = memory-policy 的 GET + memory-bundle 的 POST)。 */
     readonly methods: readonly RouteMethod[];
+    /**
+     * 「这条 GET 开的是一条**只读订阅**」—— 一条 SSE 读面(推送队列 / 账本 tail),它看着别人干活,自己不是活(S-1281)。
+     * 在场 ⇒ 分派器不把它记进在飞(`drainState.inflight()`:排空等的、`/health` 报的、SIGHUP 空闲窗与附着租约读的那一只),只记进附着
+     * (`attachedStreams()`:壳还挂在这只引擎上);排空进入那一拍(以及硬停起点)由分派器发一帧 `draining` 终帧后关掉它
+     * (`drainState.endSubscriptions`)。闭集 = 八条 GET SSE 读面,逐行理由见各行注;**唯一**一条「在飞腿的流」`POST /v1/tasks/stream`
+     * 不带它 —— 那条流就是 sync 腿本身(关流 = 断连语义),照旧算在飞。漏标一条订阅的方向是**多算在飞**(排空多等),不是少等。
+     */
+    readonly subscription?: true;
 }
 /**
  * **可分派行**:一条真路由。匹配式二选一 —— `path`(精确;标签**就是** path 自身,所以没有 label 列,

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,11 +134,16 @@ 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 ——
  *  而收编与规则读写在排空期/roster 未落时做完全无害。 */
 export declare function isCredentialGatedRewrite(method: string, url: string): boolean;
+/** S-1281:这次请求是不是一条**只读订阅**(`RouteDeclFacts.subscription` 那一列;方法也要对上 —— 订阅行恒只认 GET)。
+ *  分派器在 admission 那一拍(第一个 await 之前)同步判它:订阅不进在飞计数,只进附着集与订阅集。 */
+export declare function isSubscriptionRequest(method: string, url: string): boolean;
 /** 见 `RouteDeclFacts.methodDispatched` 的头注(单 URL 多方法端点)。 */
 export declare function isMethodDispatchedSubmitPath(url: string): boolean;
 /** 一次分派查找的结果:命中的行与它的参数,外加**这条路径上所有行**的方法并集(405 的 `Allow`)。 */

package/dist/http/route-table.js

@@ -109,8 +109,9 @@ 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 SUBSCRIPTION_DECLS = ROUTE_DECLARATIONS.filter(isDispatchDecl).filter((d) => d.subscription === true);
 const CREDENTIAL_GATED_BY_METHOD = (() => {
     const m = new Map();
     for (const d of ROUTE_DECLARATIONS)
@@ -135,10 +136,16 @@ 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));
 }
+export function isSubscriptionRequest(method, url) {
+    return SUBSCRIPTION_DECLS.some((d) => d.methods.includes(method) && matchDecl(d, url) !== null);
+}
 export function isMethodDispatchedSubmitPath(url) {
     return METHOD_DISPATCHED_DECLS.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,24 @@
 /**
- * [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`(零状态变化)→ 没有收尾链(嵌入宿主 / 测试夹具)⇒ 501 `capability.drain_state_required`
+ *    → 身份不符 ⇒ 409 `conflict.fleet_identity`(零状态变化;拒句点名不符的字段,不回显值)→ 入口:已在排空 / 硬停已在进行 ⇒ 200 回执
+ *    (这一发的期限不会被采用);这一发会进入排空而 `deadlineAt` 离进入那一拍超过 `FLEET_LEASE_OUTAGE_MAX_MS`(`config.fleetLeaseOutageMaxMs`,
+ *    本口随入参声明的准入上界,`fleet/drain-entry.ts` 规则 2)⇒ 入口答拒、本口 400 `request.field_invalid`(零状态变化;拒句点名字段、上界的
+ *    席名与值,不回显请求带的期限)。
+ *  · 首次 ⇒ 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,19 +24,35 @@ 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 });
-            return;
+            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;
+            }
+            const answer = enter({ actionId: request.actionId, deadlineAt: request.deadlineAt, deadlineBoundMs: deps.config.fleetLeaseOutageMaxMs });
+            switch (answer.state) {
+                case "deadline_beyond_bound":
+                    sendError(res, 400, "request.field_invalid", `the drain request's deadlineAt is further from now than FLEET_LEASE_OUTAGE_MAX_MS (${answer.boundMs} ms) on this engine's clock — the longest this engine stays up without serving; send a nearer deadline — nothing was changed`);
+                    return;
+                case "draining":
+                case "already_draining":
+                    sendJson(res, 200, answer);
+                    return;
+                default: {
+                    const unhandled = answer;
+                    throw new Error(`drain entry: unknown answer ${JSON.stringify(unhandled)}`);
+                }
+            }
         }
         default:
             return assertNever(match.decl.id);

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

@@ -151,6 +151,7 @@ export declare const APPROVALS_ASSISTANT_ROUTES: readonly [{
     readonly id: "approvals-stream";
     readonly path: "/v1/approvals/stream";
     readonly methods: readonly ["GET"];
+    readonly subscription: true;
 }, {
     readonly id: "assistant-inbox";
     readonly path: "/v1/assistant/inbox";
@@ -183,17 +184,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>;