@sema-agent/server 7.144.0 → 7.146.0

package/dist/deploy-facts.js

@@ -0,0 +1,94 @@
+import { TENANT_SEPARATION_WORDS } from "@sema-agent/settings-schema/execution-lanes";
+import { CHECKPOINT_CTX_KEY_SUBDIR, SEALED_KEY_DIR_MODE, SEALED_KEY_FILE_MODE } from "./sealed-key-layout.js";
+export const DEPLOY_FACTS_DIR = "deploy/facts";
+export const DEPLOY_FACTS_MEMBERS = ["lanes", "sandbox-rbac", "sealed-key"];
+export const DEPLOY_FACTS_CHANGES_FILE = "CHANGES.json";
+export const FACTS_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+export const FACTS_SCHEMA_KEYWORDS = {
+    string: ["type", "enum", "const", "description"],
+    integer: ["type", "const", "description"],
+    boolean: ["type", "description"],
+    object: ["type", "properties", "required", "additionalProperties", "description"],
+    array: ["type", "items", "minItems", "uniqueItems", "x-uniqueKey", "description"],
+};
+export const FACTS_SCHEMA_CHANGE_KINDS = ["introduced", "additive", "breaking"];
+export const FACTS_SCHEMA_CHANGES = [
+    { version: "7.146.0", file: "lanes", kind: "introduced", pointer: "", why: "首发:每条执行车道的租户档、隔离位与必需键,行集 = 所依 settings-schema 的全部车道词" },
+    { version: "7.146.0", file: "sandbox-rbac", kind: "introduced", pointer: "", why: "首发:k8s 沙箱服务账号的 RBAC 规则表(每条规则何时授、引擎真调还是兼容保留)" },
+    { version: "7.146.0", file: "sealed-key", kind: "introduced", pointer: "", why: "首发:钥匙保管目录的安装契约(显式绝对 SEALED_KEY_DIR、整个目录跨重启持久且各副本共享、目录与文件的权限位)" },
+];
+export function factsSchemaVersion(member, changes = FACTS_SCHEMA_CHANGES) {
+    const own = changes.filter((c) => c.file === member);
+    const intro = own.filter((c) => c.kind === "introduced");
+    const [first] = intro;
+    if (intro.length !== 1 || first === undefined)
+        throw new Error(`deploy-facts: member "${member}" needs exactly one "introduced" entry in FACTS_SCHEMA_CHANGES (found ${intro.length}) — its schemaVersion cannot be derived`);
+    return 1 + new Set(own.filter((c) => c.kind === "breaking" && c.version !== first.version).map((c) => c.version)).size;
+}
+export const LANE_ISOLATION_WORDS = ["supported", "unsupported"];
+const envNames = (description) => ({ type: "array", uniqueItems: true, items: { type: "string" }, description });
+export const LANE_FACTS_SCHEMA = {
+    $schema: FACTS_SCHEMA_DIALECT,
+    description: "引擎的执行车道事实:每条车道分不分租户、手跑在不在 OS 级隔离边界里、选它时引擎起服必须读到的键。行集 = 本包所依 settings-schema 车道表的全部车道词(含没有安装器接线的车道)。",
+    type: "object",
+    additionalProperties: false,
+    required: ["schemaVersion", "lanes"],
+    properties: {
+        schemaVersion: { type: "integer", const: factsSchemaVersion("lanes"), description: "本份数据的形版本;读方不认识的版本整份拒读。" },
+        lanes: {
+            type: "array",
+            minItems: 1,
+            "x-uniqueKey": ["lane"],
+            description: "每条车道一行,行序 = 车道表次序。",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["lane", "tenantSeparation", "isolation", "requiredEnv", "requiredSecretEnv"],
+                properties: {
+                    lane: { type: "string", description: "车道词,即 REMOTE_EXEC 的取值。" },
+                    tenantSeparation: { type: "string", enum: TENANT_SEPARATION_WORDS, description: "supported = 可在多租户部署(REQUIRE_PRINCIPAL=true)上用;single-user-only = 只给单用户部署,多租户部署选它起服即拒。" },
+                    isolation: { type: "string", enum: LANE_ISOLATION_WORDS, description: "supported = 手跑在 OS 级隔离边界里(独立沙箱);unsupported = 手跑在没有 OS 级隔离的地方(服务容器本身、远端主机、设备)。" },
+                    requiredEnv: envNames("选这条车道时引擎起服必须读到的非密键(缺任一 ⇒ 起服拒)。"),
+                    requiredSecretEnv: envNames("选这条车道时引擎起服必须读到的密钥键(缺任一 ⇒ 起服拒;值由运维自备)。"),
+                },
+            },
+        },
+    },
+};
+export const SEALED_KEY_REQUIREMENTS = ["persist-across-restart", "shared-by-all-replicas", "writable", "whole-directory"];
+export const SEALED_KEY_DIR_PATH_FORMS = ["absolute"];
+const octal = (mode) => mode.toString(8).padStart(4, "0");
+const SEALED_KEY_DIR_ENV = "SEALED_KEY_DIR";
+export const SEALED_KEY_FACTS = {
+    schemaVersion: factsSchemaVersion("sealed-key"),
+    dirEnv: SEALED_KEY_DIR_ENV,
+    dirPath: SEALED_KEY_DIR_PATH_FORMS[0],
+    subdirs: [CHECKPOINT_CTX_KEY_SUBDIR],
+    dirMode: octal(SEALED_KEY_DIR_MODE),
+    fileMode: octal(SEALED_KEY_FILE_MODE),
+    requirements: SEALED_KEY_REQUIREMENTS,
+};
+export const SEALED_KEY_FACTS_SCHEMA = {
+    $schema: FACTS_SCHEMA_DIALECT,
+    description: "引擎钥匙保管目录的安装契约:sealed 形模型钥匙的 X25519 钥匙对与停驻行凭据封签的钥匙都在这个目录里,私钥只存在这里。",
+    type: "object",
+    additionalProperties: false,
+    required: ["schemaVersion", "dirEnv", "dirPath", "subdirs", "dirMode", "fileMode", "requirements"],
+    properties: {
+        schemaVersion: { type: "integer", const: SEALED_KEY_FACTS.schemaVersion, description: "本份数据的形版本;读方不认识的版本整份拒读。" },
+        dirEnv: { type: "string", const: SEALED_KEY_FACTS.dirEnv, description: "安装器必须给引擎设的环境变量:值 = 保管目录的挂载位。" },
+        dirPath: { type: "string", enum: SEALED_KEY_DIR_PATH_FORMS, description: "absolute = 值必须是绝对路径(相对路径起服即拒;设了而目录建不了保管店也起服拒)。" },
+        subdirs: { type: "array", uniqueItems: true, items: { type: "string" }, description: "引擎在保管目录之下自建的子目录(随目录一起持久、一起共享)。" },
+        dirMode: { type: "string", const: SEALED_KEY_FACTS.dirMode, description: "引擎每次起服把保管目录设成的权限位(四位八进制);目录必须允许引擎进程改它的权限。" },
+        fileMode: { type: "string", const: SEALED_KEY_FACTS.fileMode, description: "引擎写钥匙文件时设的权限位(四位八进制)。" },
+        requirements: {
+            type: "array",
+            minItems: 1,
+            uniqueItems: true,
+            items: { type: "string", enum: SEALED_KEY_REQUIREMENTS },
+            description: "persist-across-restart = 目录跨进程重启保留(不然重启后封给旧钥匙的密文与停驻行凭据开不开);shared-by-all-replicas = 同一部署的每个副本挂同一份目录(多副本要支持多处读写的存储;不然 A 副本封的东西 B 副本开不开);" +
+                "writable = 引擎对目录可写(空目录起服时生成一把钥匙;只读挂载 ⇒ 建不了保管店);whole-directory = 持久与共享的单位是整个目录,含 subdirs 列出的子目录。",
+        },
+    },
+};
+//# sourceMappingURL=deploy-facts.js.map

package/dist/device-ws-hub.d.ts

@@ -38,6 +38,7 @@
 import http from "node:http";
 import { type DeviceOwner, type DeviceStore } from "./device-store.js";
 import type { DeviceEnrollment, DeviceRejection } from "./device-enrollment.js";
+import { type CidrSet } from "./net-address.js";
 import { type DeviceChunkKind, type DeviceInstructionArgsByKind, type DeviceInstructionKind, type DeviceInstructionOutcome } from "./device-ws-protocol.js";
 /** 交给调用方的一片上行流(`data` 已从 base64 解回字节)。 */
 export interface DeviceChunkDelivery {
@@ -159,10 +160,14 @@ export interface DeviceWsHubOptions {
     chunkBufferMaxBytes?: number;
     /** codex R1-F3:本副本**未鉴权**连接的并发帽(超额在 upgrade 阶段就 503 拒)。 */
     maxPreAuthConnections?: number;
-    /** codex R1-F3:单来源地址的未鉴权连接并发帽。[ref]([ref]):字面 `off` = 显式停用该层——
-     *  帽键是裸 remoteAddress,XFF 反代 / 公司 NAT 部署形把全员折叠成单键,这层从公平层退化成
-     *  「全员共享一份预算」;停层后全局帽(`maxPreAuthConnections`)照常兜底。 */
+    /** codex R1-F3:单来源地址的未鉴权连接并发帽。[ref]([ref]):字面 `off` = 显式停用该层;停层后全局帽
+     *  (`maxPreAuthConnections`)照常兜底。帽键 = 真实对端的规范形({@link readPreAuthRemoteKey}):名单
+     *  {@link trustedProxyCidrs} 空时就是 socket 对端 —— 反代 / 公司 NAT 后全员同一 socket 对端,这层是「全员共享一份预算」;
+     *  把自己的反代写进名单,这层就按反代转来的真实来源计。 */
     maxPreAuthConnectionsPerRemote?: number | "off";
+    /** [ref]:可信代理名单(CIDR 闭集;env `DEVICE_TRUSTED_PROXY_CIDRS`,配置层逐项校验)。缺省空 = 不读任何代理头(帽键 =
+     *  socket 对端,今日行为)。socket 对端落在名单内才读 `X-Forwarded-For`。坏项构造时抛(装配缝,与 helloAck 界同姿势)。 */
+    trustedProxyCidrs?: readonly string[];
 }
 export interface DeviceWsHub {
     /** 把 `GET /v1/device/ws` 的 upgrade 处理器挂到裸 `http.Server` 上。 */
@@ -204,5 +209,45 @@ export interface DeviceWsHub {
     declaredSupports(deviceId: string): ReadonlySet<DeviceInstructionKind> | undefined;
     close(): Promise<void>;
 }
+/** per-remote 帽键的来源(闭集;指标 `device_preauth_key_total{source}` 与 cap-hit 行 `keySource` 同一张表)。 */
+export declare const DEVICE_PREAUTH_KEY_SOURCES: readonly ["socket", "xff", "fallback"];
+export type DevicePreAuthKeySource = (typeof DEVICE_PREAUTH_KEY_SOURCES)[number];
+/** 对端是可信代理而转发头展不开的缘由(闭集;warn `device_preauth_forwarded_unusable{reason}`)。 */
+export declare const DEVICE_FORWARDED_UNUSABLE_REASONS: readonly ["absent", "malformed", "all_trusted", "too_many_headers"];
+export type DeviceForwardedUnusableReason = (typeof DEVICE_FORWARDED_UNUSABLE_REASONS)[number];
+export type DevicePreAuthKey = {
+    readonly key: string;
+    readonly source: "socket" | "xff";
+} | {
+    readonly key: string;
+    readonly source: "fallback";
+    readonly reason: DeviceForwardedUnusableReason;
+};
+/**
+ * 可信对端的升级请求最多带几行头,汇聚端还认它的 `X-Forwarded-For`。node 对头行数超过它的上限(`server.maxHeadersCount`,缺省约 1000 行)
+ * 的请求要么**静默**丢掉多余的头、要么直接答 431(版本行为)。丢头那一形里,反代追加在末尾的那一行 XFF 正在尾部,丢了它,剩下的就只有
+ * 客户端自己垫在前面的那一行 —— 所以行数到这个数(或运维给 server 设的更低上限)⇒ 不采 XFF(回落 `too_many_headers`);答 431 那一形里
+ * 请求到不了这里。两形下垫在前面的 XFF 都不会成为帽键。一次设备握手连同反代自己加的头远不到 100 行;这个数刻意远低于 node 的缺省上限,
+ * 不随 node 版本漂。
+ */
+export declare const DEVICE_PREAUTH_FORWARDED_HEADER_LINES_MAX = 100;
+/** 转发头的一次读数(只在对端可信时取):`header` = node 合并后的 `X-Forwarded-For`;`complete` = 请求头行数低于可信读数上限。 */
+export interface ForwardedForReading {
+    readonly header: string | readonly string[] | undefined;
+    readonly complete: boolean;
+}
+/**
+ * [ref]:per-remote 帽键 = **本连接真实对端的规范形**(`canonicalAddress`;IPv4-mapped 折成点分 IPv4 —— 同一台主机直连与经代理
+ * 是同一个键,不是两份名额)。
+ *
+ * 真实对端只有一个来源 = socket 对端;唯一的展开:socket 对端落在可信代理名单内 ⇒ 读 `X-Forwarded-For`(node 把重复头按到达序
+ * 以 `, ` 合并 = 同一张列表),**自右向左**逐项:名单内 = 又一层自己的代理,继续左移;第一个名单外的地址 = 键。选中项**以左**是
+ * 客户端自己写的段,不解析 —— 往那里塞什么都改不了键,也逼不出回落。
+ *
+ * 展不开(头行数到顶 / 头缺席 / 某项不是地址 / 全在名单内)⇒ 键 = socket 对端,`source=fallback`。🔴 这不是 fail-open,**不走 `recordFailOpen`**:
+ * 回落键把整只代理折成一个键,比展开更严(收紧方向),与名单空的今日行为同键;调用方另打一行带 reason 的 warn 指路。
+ * 名单外的对端:转发头读口一次都不调用(惰性 `readForwardedFor`;伪造 XFF 零效果)。不读 `Forwarded` / `X-Real-IP` / PROXY protocol —— 对端只有这一种展开。
+ */
+export declare function readPreAuthRemoteKey(peer: string | undefined, readForwardedFor: () => ForwardedForReading, trusted: CidrSet): DevicePreAuthKey;
 export declare function createDeviceWsHub(options: DeviceWsHubOptions): DeviceWsHub;
 //# sourceMappingURL=device-ws-hub.d.ts.map

package/dist/device-ws-hub.js

@@ -1,8 +1,10 @@
 import http from "node:http";
 import { createHash } from "node:crypto";
+import { isIP } from "node:net";
 import { WebSocketServer } from "ws";
 import { DEVICE_DRAINING_CODE, DEVICE_ERROR_CODES, DEVICE_ERROR_STATUS, assertDeviceIdShape, } from "./device-store.js";
 import { MAX_TIMER_DELAY_MS } from "./config-types.js";
+import { canonicalAddress, createTrustedProxySet } from "./net-address.js";
 import { DEVICE_HELLO_ACK_BOUNDS, DEVICE_MIN_PROTOCOL_VERSION, DEVICE_WS_LIMITS, DEVICE_WS_PATH, DEVICE_PROTOCOL_VERSION, asInstructionKind, buildHelloSignaturePayload, deviceHelloAckNumberFlaw, formatGeneration, mintChallengeNonce, mintInstructionId, parseDeviceFrameText, verifyHelloSignature, } from "./device-ws-protocol.js";
 const OUTCOME_UNKNOWN_SENTENCE = "outcome unknown — the command may have already executed on the device; verify its effect before re-running";
 const SETTLED_MEMO_MAX = 512;
@@ -63,6 +65,41 @@ function assertHelloAckNumbersInBounds(values) {
         }
     }
 }
+export const DEVICE_PREAUTH_KEY_SOURCES = ["socket", "xff", "fallback"];
+export const DEVICE_FORWARDED_UNUSABLE_REASONS = ["absent", "malformed", "all_trusted", "too_many_headers"];
+export const DEVICE_PREAUTH_FORWARDED_HEADER_LINES_MAX = 100;
+export function readPreAuthRemoteKey(peer, readForwardedFor, trusted) {
+    const raw = peer ?? "unknown";
+    const socketKey = canonicalAddress(raw) ?? raw;
+    if (!trusted.has(socketKey))
+        return { key: socketKey, source: "socket" };
+    const reading = readForwardedFor();
+    if (!reading.complete)
+        return { key: socketKey, source: "fallback", reason: "too_many_headers" };
+    const header = typeof reading.header === "string" ? reading.header : reading.header?.join(",");
+    if (header === undefined || header.replace(/[ \t]/g, "") === "")
+        return { key: socketKey, source: "fallback", reason: "absent" };
+    const hops = header.split(",");
+    for (let i = hops.length - 1; i >= 0; i--) {
+        const hop = forwardedHopAddress(hops[i]);
+        if (hop === undefined)
+            return { key: socketKey, source: "fallback", reason: "malformed" };
+        if (!trusted.has(hop))
+            return { key: hop, source: "xff" };
+    }
+    return { key: socketKey, source: "fallback", reason: "all_trusted" };
+}
+function forwardedHopAddress(hop) {
+    const t = hop.replace(/^[ \t]+|[ \t]+$/g, "");
+    if (t.startsWith("[")) {
+        const m = /^\[([^\]]*)\](?::\d{1,5})?$/.exec(t);
+        return m === null || isIP(m[1]) !== 6 ? undefined : canonicalAddress(m[1]);
+    }
+    const withPort = /^([^:]+):\d{1,5}$/.exec(t);
+    if (withPort !== null)
+        return isIP(withPort[1]) === 4 ? withPort[1] : undefined;
+    return canonicalAddress(t);
+}
 export function createDeviceWsHub(options) {
     const { store, enrollment, replicaId, logger, metrics } = options;
     const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15_000;
@@ -81,6 +118,7 @@ export function createDeviceWsHub(options) {
     const chunkBufferMaxBytes = options.chunkBufferMaxBytes ?? 2 * 1024 * 1024;
     const maxPreAuthConnections = options.maxPreAuthConnections ?? 64;
     const maxPreAuthConnectionsPerRemote = options.maxPreAuthConnectionsPerRemote ?? 8;
+    const trustedProxies = createTrustedProxySet(options.trustedProxyCidrs ?? []);
     const wss = new WebSocketServer({ noServer: true, maxPayload: DEVICE_WS_LIMITS.maxFrameBytes });
     const conns = new Map();
     const allConns = new Set();
@@ -757,6 +795,10 @@ export function createDeviceWsHub(options) {
         }, DEVICE_WS_LIMITS.handshakeDeadlineMs);
         sendServerFrame(conn, { t: "challenge", nonce: conn.nonce, protocolVersion: DEVICE_PROTOCOL_VERSION });
     }
+    function forwardedHeaderLineCeiling(server) {
+        const cap = server.maxHeadersCount;
+        return typeof cap === "number" && cap > 0 ? Math.min(DEVICE_PREAUTH_FORWARDED_HEADER_LINES_MAX, cap) : DEVICE_PREAUTH_FORWARDED_HEADER_LINES_MAX;
+    }
     function attach(server) {
         server.on("upgrade", (req, socket, head) => {
             const path = (req.url ?? "/").split("?")[0];
@@ -764,7 +806,11 @@ export function createDeviceWsHub(options) {
                 return refuseUpgrade(socket, 404);
             if (draining || closed)
                 return refuseUpgrade(socket, 503);
-            const remoteKey = req.socket.remoteAddress ?? "unknown";
+            const keyed = readPreAuthRemoteKey(req.socket.remoteAddress, () => ({ header: req.headers["x-forwarded-for"], complete: req.rawHeaders.length / 2 < forwardedHeaderLineCeiling(server) }), trustedProxies);
+            const remoteKey = keyed.key;
+            metrics?.inc("device_preauth_key_total", { source: keyed.source });
+            if (keyed.source === "fallback")
+                logger?.warn("device_preauth_forwarded_unusable", { reason: keyed.reason });
             const perRemoteCount = preAuthByRemote.get(remoteKey) ?? 0;
             const globalHit = preAuthCount >= maxPreAuthConnections;
             const perRemoteHit = maxPreAuthConnectionsPerRemote !== "off" && perRemoteCount >= maxPreAuthConnectionsPerRemote;
@@ -772,7 +818,7 @@ export function createDeviceWsHub(options) {
                 const arm = globalHit ? (perRemoteHit ? "both" : "global") : "per_remote";
                 metrics?.inc("device_preauth_refused_total", { arm });
                 logger?.warn("device_preauth_cap_hit", {
-                    remoteKey, arm, preAuthCount, cap: maxPreAuthConnections, perRemoteCount, perRemoteCap: maxPreAuthConnectionsPerRemote,
+                    remoteKey, keySource: keyed.source, arm, preAuthCount, cap: maxPreAuthConnections, perRemoteCount, perRemoteCap: maxPreAuthConnectionsPerRemote,
                 });
                 return refuseUpgrade(socket, 503);
             }

package/dist/error-code-family.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 错误码目录的**码族**列(契约附录 A.1g;目录每一行的第二格)的闭集与读法 —— 纯数据 + 穷举 switch,无 import。
+ *
+ * ## 它是什么
+ * 目录(附录 A.1 / A.1b / A.1h)的每个码恰属一族 —— 族写在目录行的**第二格**(紧跟在码后面)。族回答的是消费端要做的那一个决定:**同一个请求原样再发一次,有没有意义**,以及出路在哪一侧。
+ * 它与码名前缀的「前缀族」(`auth.` / `request.` / … ,粗分支面,按**码的出身**分)是两根轴:前缀说这个码从哪来,码族说拿到它之后重发有没有用。
+ *
+ *  · `transient`         —— 原样重发(不改请求、不改部署、不改数据,谁也不必动一手)等一等**可能成功**:限流 / 配额窗 / 排空 / 店暂时不可用 / 竞态窗 / 在飞的活干完了自会放行(会话上的活跃 run、在跑的 bake)/ 未判为确定性的服务端故障。
+ *  · `deterministic`     —— 原样重发**改不了判**:要变的是请求本身、凭据与权限、部署声明与旋钮、存储里坏掉的字节,或一个已被别人结清的状态。
+ *  · `store_judged`      —— 重试类**逐次由店判**:体键 `permanence`(`transient` / `terminal`)在场 ⇔ 店判了;缺席 = 店没判(按 `transient` 读)。
+ *  · `pending_decision`  —— 恢复面 / 决断面的拒,拒在认领之前:体 `retriable: true` 在场 ⇒ 一张待批卡仍 pending(行重新 park);键缺席不推出「卡已不在」(服务端自铸的拒如 `wake.gate_pending` 不带该键)。
+ *                            它说「卡还在」,**不说**「原样重发会成功」。
+ *  · `retention_expired` —— 被寻址的留存物曾在、已被保留策略收走(TTL / 容量 / 淘汰),不会回来;出路是新开,不是重试。
+ *
+ * ## 单一真源
+ * 码 → 族的归属**只住在契约文档的目录行上**(消费端读的就是那份文档与它的 wire 变更清单);本文件只定**词表**与每个词的**状态律**,
+ * 词表与文档 A.1g 的词表行由 `test/error-code-family.test.ts` 双向钉(多一个词 / 少一个词 / 写错一个词都红),目录每个码有族、族与状态对得上、`pending_decision` 与
+ * 服务端真能盖 `retriable:true` 的码集对得上也在那里钉。没有第二张「码 → 族」的表。
+ */
+/** 码族闭集(词表顺序 = 契约 A.1g 的行序)。 */
+export declare const ERROR_CODE_FAMILIES: readonly ["transient", "deterministic", "store_judged", "pending_decision", "retention_expired"];
+export type ErrorCodeFamily = (typeof ERROR_CODE_FAMILIES)[number];
+/** 一个串是不是码族词(`includes` 判,不吃原型链上的名字)。 */
+export declare function isErrorCodeFamily(word: string): word is ErrorCodeFamily;
+/**
+ * 一个状态码落在这一族是否说得通 —— 每个词一条状态律(穷举 switch:加词而没来这里定它的状态律 ⇒ tsc 红)。
+ *
+ *  · `transient`         —— 等待 / 可用性类状态:408 · 425 · 429,服务端侧 500 · 502 · 503 · 504,以及「等一个明说的窗再发」的 409(忙 / 竞态);501 不是(换部署形态不是等);
+ *  · `deterministic`     —— 除了等待类三态(408 · 425 · 429:这三个状态本身就在说「等一等再来」)之外的任何状态;
+ *  · `store_judged`      —— 店答的状态:422(店的重放失败)与服务端侧 500 · 502 · 503 · 504;
+ *  · `pending_decision`  —— 只在 4xx(拒在认领之前,调用方可以带着更新后的坐标再决),且不是等待类三态;
+ *  · `retention_expired` —— 只在 4xx(被寻址的东西不在了),且不是等待类三态。
+ */
+export declare function familyAdmitsStatus(family: ErrorCodeFamily, status: number): boolean;
+//# sourceMappingURL=error-code-family.d.ts.map

package/dist/error-code-family.js

@@ -0,0 +1,26 @@
+export const ERROR_CODE_FAMILIES = ["transient", "deterministic", "store_judged", "pending_decision", "retention_expired"];
+export function isErrorCodeFamily(word) {
+    return ERROR_CODE_FAMILIES.includes(word);
+}
+export function familyAdmitsStatus(family, status) {
+    const waiting = status === 408 || status === 425 || status === 429;
+    const clientSide = status >= 400 && status < 500 && !waiting;
+    const serverSide = status === 500 || status === 502 || status === 503 || status === 504;
+    switch (family) {
+        case "transient":
+            return waiting || serverSide || status === 409;
+        case "deterministic":
+            return status >= 400 && status < 600 && !waiting;
+        case "store_judged":
+            return serverSide || status === 422;
+        case "pending_decision":
+            return clientSide;
+        case "retention_expired":
+            return clientSide;
+        default: {
+            const unhandled = family;
+            throw new Error(`unhandled error-code family: ${String(unhandled)}`);
+        }
+    }
+}
+//# sourceMappingURL=error-code-family.js.map

package/dist/fleet/drain-entry.d.ts

@@ -30,7 +30,7 @@
  * 纯类型 + 纯函数叶(值 import 只有 scope 读法叶与 run 行判词叶)。
  */
 import type { DrainReceipt, DrainRequest, EngineDraining } from "@sema-agent/settings-schema/fleet";
-import type { EngineLeaseFacts } from "../boot/engine-lease.js";
+import type { EngineHandoverDoor, EngineLeaseFacts } from "../boot/engine-lease.js";
 /**
  * 引擎自铸的动作号 —— **一张表**(排空事实与回执里不来自请求体的全部拼法;请求体的 `actionId` 由调用方自取):
  *  · {@link ENGINE_DRAIN_CAUSES}:没有请求承载的排空成因(停止信号 / SIGHUP 升级 / 附着租约自退);
@@ -68,6 +68,29 @@ export interface DrainDeadlineRefusal {
 }
 /** 入口的答:契约回执(进入 / 已在排空),或期限越界的拒(只在调用方声明了上界时出现)。按 `state` 穷举。 */
 export type DrainEntryAnswer = DrainReceipt | DrainDeadlineRefusal;
+/**
+ * 在飞数的**分项**(`GET /health` 的 `inflightBreakdown`)—— 同一份分项派生**两个事实**,不是两份计数:
+ *  · **总数**(可观测事实,{@link inflightTotal} = `/health.inflight`):这台引擎此刻托管着多少活 = `http + leader + sessionResident`;
+ *  · **阻断集**(判据,{@link blockingInflightOf} = `drainState.blockingInflight`):还有没有**必须等完**的活 = `http + leader`。
+ *    排空等的、孤儿窗 / 附着租约自退 / SIGHUP 空闲窗判「可以停了吗」读它。`sessionResident` 不在其内。
+ * 三项:
+ *  · `http` —— 本副本的 HTTP 腿:在飞 run 集(`inflightRuns ∪ steerableRuns`)+ 没有登记身份的同步计费腿(`/v1/tasks` 的同步腿)+ admission 期的非探针请求;
+ *  · `leader` —— leader 口的后台 run(`leaderEndpoint.inflight()`);
+ *  · `sessionResident` —— 会话驻留的后台 shell / monitor(活过起它的那一条腿;`session-resident-background.ts` 的读法:不含 retain 行)。
+ *    它只进总数、不进阻断集:一只不退出的驻留 shell(`while true`)若阻断,崩溃孤儿引擎就永生、排空每次等满窗;窗到 / 排空完成即由退出边界的后台收割收掉
+ *    (retain 行按 retain 既有语义,活过受控退)。
+ * 三项在同一次读里求出,`/health` 的 `inflight` 与 `inflightBreakdown` 因此永远自洽。只有这两个函数各写一次这两个和,没有第三张计法表。
+ * 阻断集只需要前两项:判停路径(排空 1 s 拍 / 租约拍 / SIGHUP 拍)**不求值** `sessionResident`(那是对进程级注册表的一次逐会话走查,只在 `/health` 与崩溃遗言里付)。
+ */
+export interface InflightBreakdown {
+    readonly http: number;
+    readonly leader: number;
+    readonly sessionResident: number;
+}
+/** 阻断集 = 必须等完的活 = `drainState.blockingInflight()`(`sessionResident` 不在内)。 */
+export declare function blockingInflightOf(b: Pick<InflightBreakdown, "http" | "leader">): number;
+/** 总数 = 引擎此刻托管的全部活 = `/health.inflight`(= 阻断集 + 会话驻留项)。 */
+export declare function inflightTotal(b: InflightBreakdown): number;
 /**
  * 引擎与 HTTP 面共享的排空盒子(装配层建一只,`createHttpServer` 与收尾链各自往上装读口 / 入口)。
  *  · `draining` / `since` / `actionId` / `deadlineAt` —— **只由** {@link enter} 整组写入(排空事实 = 契约 `EngineDraining`);
@@ -75,8 +98,8 @@ export type DrainEntryAnswer = DrainReceipt | DrainDeadlineRefusal;
  *  · `yieldInflight` —— 让出本副本在飞的可抢占腿(`createHttpServer` 装);
  *  · `endSubscriptions` —— 关掉本副本打开着的只读订阅流(发一帧 `draining` 终帧再关;`createHttpServer` 装,[ref])。订阅流不是在飞的工作
  *    (不进 `inflight`),排空不等它;收尾链在排空进入那一拍与硬停起点各调一次(排空期间新开的订阅在硬停那一拍收);
- *  · 其余四只是既有的读口(在飞数 / 活性时钟 / 附着流),语义见 `http/server.ts`。`inflight` 只数**工作**(run 腿 / 计费提交 / HITL 应答 /
- *    admission 期的普通请求),只读订阅只进 `attachedStreams`([ref])。
+ *  · 其余五只是既有的读口(在飞数 / 活性时钟两只〔最近一次 / 首次〕/ 附着流两只),语义见 `http/server.ts`。在飞数只数**工作**(run 腿 / 计费提交 / HITL 应答 /
+ *    admission 期的普通请求),只读订阅只进 `attachedStreams`([ref]);在飞数分两个读口 —— 总数 `inflight`(事实)与阻断集 `blockingInflight`(判据),见 {@link InflightBreakdown}。
  */
 export interface DrainState {
     draining: boolean;
@@ -86,12 +109,25 @@ export interface DrainState {
     enter?: (entry: DrainEntry) => DrainEntryAnswer;
     yieldInflight?: () => void;
     endSubscriptions?: () => void;
+    /** **总数**读口(`createHttpServer` 装):引擎此刻托管的全部活 = `inflightTotal(inflightBreakdown())`。可观测事实 —— 只有 `/health` 与崩溃遗言读它;
+     *  **没有任何「停不停」的判据读它**(判据读 {@link DrainState.blockingInflight})。 */
     inflight?: () => number;
+    /** 分项读口(`createHttpServer` 装,与 `inflight` / `blockingInflight` 同一次装、同一份求值)。`/health` 读它一次,同时出 `inflight` 与 `inflightBreakdown` 两键。 */
+    inflightBreakdown?: () => InflightBreakdown;
+    /** **阻断集**读口(`createHttpServer` 装):还有没有必须等完的活 = `blockingInflightOf(inflightBreakdown())` = `http + leader`。排空等的(`boot/shutdown.ts` 的排空驱动表)、
+     *  孤儿窗 / 附着租约自退(`boot/engine-lease.ts`)、SIGHUP 空闲窗(`sighup-idle.ts`)的「可以停了吗」都读它;会话驻留的后台 shell / monitor 不在内。 */
+    blockingInflight?: () => number;
     lastActivityAt?: () => number;
+    /** [ref]:首个**非探针**请求的单调时刻(`null` = 还没有过)。与 `lastActivityAt` 同一个写者(`http/server.ts` 的活性打点)、写一次就定;
+     *  读者 = 租约腿的候首触态(`boot/engine-lease.ts`)与 `/health.engineLease.firstAttach.attachedAt`。 */
+    firstActivityAt?: () => number | null;
     attachedStreams?: () => number;
     lastAttachEndedAt?: () => number;
     /** [ref]:附着租约窗的读口(`/health.engineLease`)。收尾链在**装了租约腿**时才装它,读口现读租约腿的把手 —— 腿还在观察才有读数,未装配的盒子里根本没有这只口。 */
     engineLease?: () => EngineLeaseFacts | undefined;
+    /** [ref]:附着租约的交接门(`POST /v1/engine/handover` · `POST /v1/engine/attach` 与能力位 `engine.handover` 读它)。收尾链在**装了交接车道**时才装
+     *  (租约腿已装配 ∧ 非多租户);`observing` = 腿还在观察。 */
+    engineHandover?: EngineHandoverDoor;
 }
 /** 排空盒子里的排空事实(三键齐才是;入口整组写,所以「缺一」只出现在手搭的夹具上)。 */
 export declare function drainingFactOf(s: Pick<DrainState, "draining" | "since" | "actionId" | "deadlineAt">): EngineDraining | undefined;

package/dist/fleet/drain-entry.js

@@ -10,6 +10,12 @@ export const DRAIN_CAUSE_COUNTS_AS_FIRST_STOP_SIGNAL = {
     "signal:SIGHUP": true,
     "self-exit:attachment": false,
 };
+export function blockingInflightOf(b) {
+    return b.http + b.leader;
+}
+export function inflightTotal(b) {
+    return blockingInflightOf(b) + b.sessionResident;
+}
 export function drainingFactOf(s) {
     return s.draining && s.actionId !== undefined && s.since !== undefined && s.deadlineAt !== undefined ? { actionId: s.actionId, since: s.since, deadlineAt: s.deadlineAt } : undefined;
 }

package/dist/fleet/fleet-bus.d.ts

@@ -1,5 +1,6 @@
 import type { TerminalCause, WorkflowRun } from "@sema-agent/core";
 import type { RunRecord } from "../plugins/store-contracts.js";
+import type { RunAcceptance } from "../run-acceptance.js";
 /** The fleet vocabulary the shell renders (MF-Fleet `FleetTask.status`). The service maps its run/workflow status
  *  onto this neutral set; `awaiting approval` = a needs-review/plan-approval park, `waiting` = a durable suspend.
  *
@@ -395,7 +396,8 @@ export interface HookManagedUnrun {
      *  · `llm_carrier_unavailable` / `llm_cap` —— prompt / agent 条目没有模型载体 / 超出每事件的 LLM 条目数;
      *  · `powershell_unsupported` —— `shell:"powershell"` 条目(本服务不跑);
      *  · `if_unevaluable` —— 条目的 `if` 条件评不出;
-     *  · `budget_exhausted` —— 托管车道的事件墙钟耗尽:撞上的那一条记一帧,同一次执行里其后的条目不再起、不逐条记(PreToolUse 逐组执行 ⇒ 至多每组一帧);
+     *  · `budget_exhausted` —— 托管车道的预算耗尽:本服务的事件墙钟到点(不再起下一条),或托管车道那张注册的**引擎 handler 预算**(`HOOKS_TIMEOUT_MS`)用尽、被引擎叫停(`detail` 点名这一种);
+     *    撞上的那一条记一帧,同一次执行里其后的条目不再起、不逐条记(墙钟:每一相、PreToolUse 每一组至多一帧;引擎预算:每个事件恰一帧);任务取消叫停不记;
      *  · `spawn_failed` / `timeout` —— 起不来 / 超时被收;
      *  · `exit_nonzero` —— 退出码非 0 非 2;`bad_json` —— 看着是 JSON 却读不成(含 http 条目 2xx 回了非 JSON 体、Stop × prompt 的判词读不出);`decision_out_of_set` —— `permissionDecision` 不在 allow / deny / ask 里;
      *  · `evidence_unavailable` —— Stop × prompt 条目因会话证据面不足(或运维关了 transcript)被滤掉没跑;
@@ -642,7 +644,8 @@ export declare class FleetEventBus {
 export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
     runId: string;
     scope: string;
-    name: string;
+    /** 行名 = 本服务持有的交付文本的预览({@link fleetRunLabels});缺席 = 腿上装着 prompt 屏、提交时还没有交付的文本 ⇒ 建行不带名,交付之后经 `onNamed` 补。 */
+    name?: string;
     description?: string;
     /** 嵌子代树的根:这条腿的 canonical core taskId(`spec.taskId ?? sessionId`)。转发子代的 `parentTaskId` 与它相等
      *  ⇒ 挂在 run 行下,否则挂在那个子代的行下。**只管嵌套**,不是行的会话键。 */
@@ -679,6 +682,9 @@ export declare function fleetRunPublisher(bus: FleetEventBus | undefined, run: {
      *  只有**真终态**(completed/failed/killed)帧带残局——parked(suspended/needs_review)的行还活着,
      *  没有「终局」可言,误传也不上帧。 */
     onTerminal: (status: RunStatusForFleet, residuals?: FleetRunResiduals) => void;
+    /** 建行时没有名(腿上有屏)的行,引擎交付之后补上名(受理座的补写口调)。只改**还在 bus 上**的那一行:收场之后、或行已被别的路径收走(对账腿退场)⇒ 不发 ——
+     *  名不是活着的信号,一帧只带名的 delta 不许铸行(铸出来的行没有 scope / 会话键)。 */
+    onNamed: (name: string) => void;
 };
 /** The run-scoped publisher handle (returned by `fleetRunPublisher`). Threaded into `runInBackground` so a
  *  background run TRANSITIONS its fleet row exactly like the sync POST /v1/runs leg does. */
@@ -738,10 +744,15 @@ export declare function buildRunName(preview: string): string;
  *  shows `name`=objective + `description`=current activity (two DISTINCT things, killing the earlier "objective shown
  *  twice" dup). (A subagent CHILD row's name = its agent-type — BC-2.)
  *  一只折法({@link buildRunName}),输入 = 与 run 行同一只预览(用户写的那段 → 脱敏 → 截):`GET /v1/assistant/tasks`
- *  读 run 行上存的预览、过同一只折法 ⇒ 同一个 run 两面同名。剥完没有用户正文 ⇒ `(notification turn)`;闭集外的 XML 头当普通正文标。 */
+ *  读 run 行上存的预览、过同一只折法 ⇒ 同一个 run 两面同名。剥完没有用户正文 ⇒ `(notification turn)`;闭集外的 XML 头当普通正文标。
+ *  入参 = 本服务持有的交付文本(受理座的 `objectiveAtSubmit` / 交付之后的那一份;律的属主 = `run-acceptance.ts`),缺席(腿上有屏、还没有可写的那一份)⇒ 不带名 ——
+ *  与运维任务视图对 NULL 预览的处置同(展示位缺席即缺席,客户端渲占位)。 */
 export declare function fleetRunLabels(objective: string | undefined): {
-    name: string;
+    name?: string;
 };
+/** 腿上有屏时 fleet 行名的补写口(开 fleet 行之后、起跑之前登记;律的属主 = `run-acceptance.ts`):交付的那一份 → {@link fleetRunLabels} 同一只折法 → `onNamed`。
+ *  腿上没有屏 ⇒ 受理座永不调它(行名在开行时已按提交时的交付文本写好)。 */
+export declare function nameFleetRowOnDelivery(acceptance: Pick<RunAcceptance, "onDelivered">, publisher: Pick<FleetRunPublisher, "onNamed">): void;
 /**
  * `runStatusToFleet` 的入参**闭集**([ref] P1-④)。两段:
  *  · `RunRecord["status"]` = `"running" | core.TaskStatus` —— run **行**状态词表,属主

package/dist/fleet/fleet-bus.js

@@ -230,7 +230,7 @@ export class FleetEventBus {
 }
 export function fleetRunPublisher(bus, run) {
     if (!bus)
-        return { onStart: () => undefined, onEvent: () => undefined, onForwardEvent: () => undefined, onTerminal: () => undefined };
+        return { onStart: () => undefined, onEvent: () => undefined, onForwardEvent: () => undefined, onTerminal: () => undefined, onNamed: () => undefined };
     let tokens = 0;
     const startedAt = Date.now();
     const sessionField = run.sessionId ? { sessionId: run.sessionId } : {};
@@ -282,7 +282,14 @@ export function fleetRunPublisher(bus, run) {
     };
     return {
         onStart() {
-            bus.publishTask({ id: run.runId, name: run.name, ...(run.description ? { description: run.description } : {}), scope: run.scope, ...sessionField, status: "running", tokens: 0, elapsedMs: 0 });
+            bus.publishTask({ id: run.runId, ...(run.name !== undefined ? { name: run.name } : {}), ...(run.description ? { description: run.description } : {}), scope: run.scope, ...sessionField, status: "running", tokens: 0, elapsedMs: 0 });
+        },
+        onNamed(name) {
+            if (settledLeg)
+                return;
+            if (bus.taskRow(run.runId) === undefined)
+                return;
+            bus.publishTask({ id: run.runId, name });
         },
         onEvent(ev) {
             if (settledLeg)
@@ -595,7 +602,14 @@ export function buildRunName(preview) {
     return oneLine.length > RUN_NAME_CHARS ? `${oneLine.slice(0, RUN_NAME_CHARS - 1)}…` : oneLine;
 }
 export function fleetRunLabels(objective) {
-    return { name: buildRunName(buildRunObjectivePreview(objective ?? "")) };
+    return objective === undefined ? {} : { name: buildRunName(buildRunObjectivePreview(objective)) };
+}
+export function nameFleetRowOnDelivery(acceptance, publisher) {
+    acceptance.onDelivered("fleet-name", async (objective) => {
+        const { name } = fleetRunLabels(objective);
+        if (name !== undefined)
+            publisher.onNamed(name);
+    });
 }
 export function isTerminalFleetStatus(status) {
     switch (status) {

package/dist/hooks/branch-transcript.d.ts

@@ -19,7 +19,7 @@ export declare const RENDERED_ENTRY_TYPES: readonly ["message", "compaction", "c
  * custom —— data-only(session.js 折 messages 只认 message/custom_message 两型),模型看不见它的
  * data;把它渲出来反而是把模型没见过的东西冒充成证据,与 [ref] 是同一判据的反方向。
  */
-export declare const SKIPPED_ENTRY_TYPES: readonly ["thinking_level_change", "model_change", "label", "session_info", "leaf", "prompt_epoch", "announced_listing", "workspace_state", "git_announcement", "reminder_mark", "custom"];
+export declare const SKIPPED_ENTRY_TYPES: readonly ["thinking_level_change", "model_change", "label", "session_info", "leaf", "prompt_epoch", "announced_listing", "workspace_state", "git_announcement", "reminder_mark", "session_checkout", "custom"];
 /** 渲染结果。**判别式**:证据不足时调用方拿不到 `text`,想用也用不了(见顶注)。 */
 export type BranchTranscript = {
     sufficient: true;

package/dist/hooks/branch-transcript.js

@@ -11,6 +11,7 @@ export const SKIPPED_ENTRY_TYPES = [
     "workspace_state",
     "git_announcement",
     "reminder_mark",
+    "session_checkout",
     "custom",
 ];
 export const BRANCH_TRANSCRIPT_MAX_CHARS = 60_000;

package/dist/hooks/classic-stations.d.ts

@@ -7,8 +7,11 @@
  *  ② **handler 怎么挂**:链成员「无意见 ⇒ `next(e)`」(链 handler 返回 `undefined` 是站点违约,refuse 站上即 fail-closed 拒),
  *     观察者「恒返回 `undefined`」(观察者的判词不采纳、被引擎报告)。两条都在 {@link hangClassic} / {@link observeClassic} 里成形,
  *     调用方只写「这一站我答什么」或「这一站我看什么」,不再各自记得这两条。
- *  ③ **信号**:引擎交给每只 handler 的 `next.signal` 是「这只 handler 的预算 ∪ 这次派发被取消」的合成(core 的派发器自合成,本仓不另合成第二份)。
- *     它是 handler 体的第二个入参 —— 触发之后 handler 不再起新事、在飞的子进程要叫停(`hooks/hook-runner.ts` 的命令钩子腿)。
+ *  ③ **停表**:引擎交给每只 handler 的 `next.signal` 是「这只 handler 的预算 ∪ 这次派发结束 / 被取消」的合成(core 的派发器自合成,本仓不另合成第二份);
+ *     成因只读引擎的读数 `next.budget.remainingMs`(用尽 = 0),不解析信号的文案。两样一起是 handler 体的第二个入参 {@link HandlerHalt} ——
+ *     触发之后 handler 不再起新事、在飞的子进程要叫停(`hooks/hook-runner.ts` 的命令钩子腿);是自己的预算用尽,托管车道把撞上的条目记成未跑成。
+ *  ④ **两种链上挂法**:内层「先答,无意见再 `next(e)`」({@link hangClassic});外层「先 `next(e)`,在答回来的答案上再答」({@link wrapClassic})——
+ *     外层 handler 等 `next` 的那段引擎停它的表(core `SelfBudget` 的暂停),所以外层的预算只算它自己的时间。
  *
  * 站的集合 = 引擎事件表里有站的 `classic.*` 名(一条钉从 `MOD_EVENT_TABLE` 派生对拍,不手抄第二份)。
  * 观察站(`StopFailure` / `PostCompact` / `PermissionDenied` / `SessionStart` / `SessionEnd`)只许观察者:答案形是「无」,core 的迁移配方要求挂 `{ observe: true }`。
@@ -36,16 +39,30 @@ export declare const CLASSIC_STATION_ROLE: {
 /** 本仓 handler 体对一站作的答:观察站不作答(`void`);链站 = core 的答案形,去掉本仓从不作的 `null` / `false`(PreToolUse 的两个「不表态」词)。 */
 type StationAnswer<K extends ClassicStation> = (typeof CLASSIC_STATION_ROLE)[K] extends "observe" ? void : Exclude<ClassicEventMap[K]["answer"], null | false>;
 /**
- * 一站的 handler 体:读 `e`,答这一站的答案;`undefined` = 无意见(链成员由 {@link hangClassic} 交给 `next(e)`)。
- * `signal` = 引擎交给这只 handler 的 `next.signal`(预算到 ∪ 派发被取消;见头注 ③)。
+ * 引擎交给一只 handler 的停表(头注 ③):`signal` 触发 = 引擎不再等它;`budgetSpent()` = 触发的是不是它**自己的预算**用尽(派发结束 / 任务取消 ⇒ `false`;
+ * 信号还没触发 ⇒ `false`)。
  */
-export type ClassicAnswer<K extends ClassicStation> = (e: ClassicEventMap[K]["e"], signal: AbortSignal) => Promise<StationAnswer<K> | undefined>;
+export interface HandlerHalt {
+    readonly signal: AbortSignal;
+    budgetSpent(): boolean;
+}
 /**
- * 按站的角色挂一只 handler:链站 ⇒ 链成员 `(await answer(e)) ?? next(e)`;观察站 ⇒ 观察者(体照跑、恒返回 `undefined`)。
+ * 一站的 handler 体:读 `e`,答这一站的答案;`undefined` = 无意见。`halt` 见 {@link HandlerHalt}。
+ * `below` = 外层挂法下(见 {@link wrapClassic})链下方答回来的那份答案(接收后冻结的数据;下方都无意见时是引擎核心的空答案)—— 内层挂法与观察站恒 `undefined`。
+ * 外层体答 `undefined` = 下方的答案原样作数;要换掉它就交一份新答案(把下方的成员并进去是体自己的事)。
+ */
+export type ClassicAnswer<K extends ClassicStation> = (e: ClassicEventMap[K]["e"], halt: HandlerHalt, below: unknown) => Promise<StationAnswer<K> | undefined>;
+/**
+ * 内层挂法:链站 ⇒ 链成员 `(await answer(e)) ?? next(e)`;观察站 ⇒ 观察者(体照跑、恒返回 `undefined`)。
  * `e` 的型由 core 的 `ClassicEventMap` 给(引擎交来的是本站的 `e`;见头注 ①)。
  */
 export declare function hangClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, answer: ClassicAnswer<K>): void;
-/** 挂一只观察者(任何站都可):拿分离副本、不进链、恒返回 `undefined`;`signal` 同 {@link ClassicAnswer}。 */
-export declare function observeClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, watch: (e: ClassicEventMap[K]["e"], signal: AbortSignal) => void | Promise<void>): void;
+/**
+ * 外层挂法:链站 ⇒ 先 `next(e)`(下方的链成员与引擎核心先跑完,这一只的表在等的那段停着),再拿答回来的答案作答 —— 体答 `undefined` ⇒ 下方的答案原样作数;
+ * 下方在拒站上失败 ⇒ 派发已 fail-closed 终局,`next` 抛,体不跑。观察站 ⇒ 与 {@link hangClassic} 同(观察者不进链,没有「下方」)。
+ */
+export declare function wrapClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, answer: ClassicAnswer<K>): void;
+/** 挂一只观察者(任何站都可):拿分离副本、不进链、恒返回 `undefined`;`halt` 同 {@link ClassicAnswer}。 */
+export declare function observeClassic<K extends ClassicStation>(on: On<EngineDollar>, station: K, watch: (e: ClassicEventMap[K]["e"], halt: HandlerHalt) => void | Promise<void>): void;
 export {};
 //# sourceMappingURL=classic-stations.d.ts.map