@sema-agent/server 7.145.0 → 7.146.0

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

@@ -396,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)被滤掉没跑;

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

package/dist/hooks/classic-stations.js

@@ -14,16 +14,42 @@ export const CLASSIC_STATION_ROLE = {
     "classic.SessionStart": "observe",
     "classic.SessionEnd": "observe",
 };
+async function withHalt(next, body) {
+    const { signal } = next;
+    const readCause = () => next.budget.remainingMs === 0;
+    let spent = signal.aborted ? readCause() : undefined;
+    const latch = () => {
+        spent = readCause();
+    };
+    if (spent === undefined)
+        signal.addEventListener("abort", latch, { once: true });
+    try {
+        return await body({ signal, budgetSpent: () => spent === true });
+    }
+    finally {
+        signal.removeEventListener("abort", latch);
+    }
+}
 export function hangClassic(on, station, answer) {
     if (CLASSIC_STATION_ROLE[station] === "observe") {
-        observeClassic(on, station, async (e, signal) => void (await answer(e, signal)));
+        observeClassic(on, station, async (e, halt) => void (await answer(e, halt, undefined)));
+        return;
+    }
+    on(station, async (_$, e, next) => (await withHalt(next, (halt) => answer(e, halt, undefined))) ?? next(e));
+}
+export function wrapClassic(on, station, answer) {
+    if (CLASSIC_STATION_ROLE[station] === "observe") {
+        hangClassic(on, station, answer);
         return;
     }
-    on(station, async (_$, e, next) => (await answer(e, next.signal)) ?? next(e));
+    on(station, async (_$, e, next) => {
+        const below = await next(e);
+        return (await withHalt(next, (halt) => answer(e, halt, below))) ?? below;
+    });
 }
 export function observeClassic(on, station, watch) {
     on(station, async (_$, e, next) => {
-        await watch(e, next.signal);
+        await withHalt(next, async (halt) => watch(e, halt));
         return undefined;
     }, { observe: true });
 }

package/dist/hooks/hook-runner.d.ts

@@ -57,20 +57,27 @@ export declare const SETTINGS_HOOK_STATIONS: {
     readonly PreCompact: readonly ["classic.PreCompact"];
     readonly PostCompact: readonly ["classic.PostCompact"];
 };
-/** 这张注册的名字 —— wire 可见(`wiring_manifest.mods[].name`、`allowRuleShadowed[].entries`),也是 handler 失败时引擎拒句点名的扩展名。 */
-export declare const SETTINGS_HOOKS_REGISTRATION = "settings.hooks";
 /**
- * 律四 · `HOOKS_TIMEOUT_MS` 未设时本注册每个 handler 的预算(ms)。
+ * **一条车道一张注册**:每张的名字 —— wire 可见(`wiring_manifest.mods[].name`、`allowRuleShadowed[].entries`、问因项 `askReasons[].registration`),
+ * 也是 handler 失败时引擎拒句点名的扩展名。没有托管组的请求只铸非托管那一张(名字与托管车道之前逐字同)。
+ */
+export declare const SETTINGS_HOOKS_REGISTRATIONS: {
+    readonly managed: "settings.hooks.managed";
+    readonly unmanaged: "settings.hooks";
+};
+/**
+ * 律四 · `HOOKS_TIMEOUT_MS` 未设时**每张车道注册**每个 handler 的预算(ms;两张注册各一份同值,不另铸数)。
  *
  * **这只数是引擎的钟,不是本服务跑钩子子进程的墙钟。** 引擎对 `budgetMs` 的定义(core `ModRegistration.budgetMs` 的注释,逐字)是
  * "Each handler's own time" —— 每个 handler 自己的时间:一只在 handler 等 `next` / `$` 调用时暂停的钟(core 的 `SelfBudget`),
- * 到点 ⇒ 这个 handler 失败(PreToolUse / UserPromptSubmit 上 fail-closed 拒,其余站跳过)。命令钩子子进程自己的墙钟另有两只,都在本文件:
- * 单条命令的 `timeout`(上限 {@link MAX_HOOK_TIMEOUT_SECONDS})与一个事件里同步条目的总墙钟({@link MAX_HOOK_EVENT_TOTAL_SECONDS},到点不再起下一条)。
+ * 到点 ⇒ 这个 handler 失败(PreToolUse / UserPromptSubmit 上 fail-closed 拒,其余站跳过)。托管车道是外层、先等 `next`:它的表在非托管车道跑的那段停着 ——
+ * 非托管条目吃光的只是非托管那张的预算,托管车道照跑;托管车道自己的预算用尽 ⇒ 撞上的托管条目记未跑成(`budget_exhausted`)。命令钩子子进程自己的墙钟另有两只,都在本文件:
+ * 单条命令的 `timeout`(上限 {@link MAX_HOOK_TIMEOUT_SECONDS})与一个事件里一条车道同步条目的总墙钟({@link MAX_HOOK_EVENT_TOTAL_SECONDS},到点不再起下一条)。
  *
  * 缺省取单条命令超时的上限 {@link MAX_HOOK_TIMEOUT_SECONDS} × 1000(两只钟起点不同:引擎的钟在 handler 起跑时就开始走,命令的 `timeout` 钟要等 shell 解析和 spawn 之后,
  * 同一 handler 里串行的几条还共用这一只钟 —— 配到 600 s 的命令跑满时预算会先到)。不是抄引擎缺省(10 s):一条跑 11 s 的 PreToolUse 钩子会因此被 fail-closed 拒。
  *
- * 两只钟的交汇:预算到,与任务被取消一样,引擎对这个 handler 的信号({@link ClassicAnswer} 的 `signal`)触发 ——
+ * 两只钟的交汇:预算到,与任务被取消一样,引擎对这个 handler 的信号({@link HandlerHalt} 的 `signal`)触发 ——
  * 在跑的命令钩子的进程组被叫停(SIGTERM → {@link HOOK_KILL_GRACE_MS} → 组长还在则组 SIGKILL),这个 handler 里还没起的条目不再起。
  */
 export declare const DEFAULT_SETTINGS_HOOKS_BUDGET_MS: number;
@@ -115,7 +122,7 @@ export interface RunnableMatcherGroup {
     source?: HookGroupSource;
     hooks: RunnableHookEntry[];
 }
-/** 受理面通过后的 hooks 配置:每个事件下的条目都是本仓会跑的型 —— 执行侧({@link createSettingsHooksRegistration})只收这一型,「不认识的类型」到不了它手里。 */
+/** 受理面通过后的 hooks 配置:每个事件下的条目都是本仓会跑的型 —— 执行侧({@link createSettingsHooksRegistrations})只收这一型,「不认识的类型」到不了它手里。 */
 export type RunnableHooksConfig = Partial<Record<HookEventName, RunnableMatcherGroup[]>>;
 /** 分类器点名的一块(被剔的块或整份被拒的理由):码 + 坐标 + 坏字段。 */
 export type HooksRefusalPiece = HooksDroppedPiece | HooksRejection;
@@ -485,7 +492,7 @@ export declare function hookMatcherMatches(matcher: string | undefined, value: s
  *  「交替/正则」是 matcher 字段的文法——本实现名部走 hookMatcherMatches 属**超集**(alternation 也认),
  *  如实登记不收窄;②250 的 `if` 已扩到 prompt/agent/http/mcp_tool 条目(本 runner 只翻 command,不涉)。 */
 export declare function hookIfMatches(cond: string, payload: unknown): true | "not_matched" | "unevaluable" | "over_budget";
-/** createSettingsHooksRegistration 的装配上下文(payload 的 CC-verbatim 字段来源)。 */
+/** createSettingsHooksRegistrations 的装配上下文(payload 的 CC-verbatim 字段来源)。 */
 export interface HookRunnerContext {
     logger: Logger;
     sessionId: string;
@@ -520,6 +527,11 @@ export interface HookRunnerContext {
      * `[]` = 没有层写名单(不限,与引擎外的参照实现「名单未设 ⇒ 不限」同读)。今天唯一的层来源是请求的 `settings`(`task-settings.ts` 的 `httpHookAllowlist`,源 `flagSettings`)。
      */
     httpHookAllowlistLayers: readonly HttpHookAllowlistLayer[];
+    /**
+     * 部署座在**任务座之下**挂了链成员的站点式样(引擎的准入记录读出,`boot/deployment-mods.ts` 的 `belowTaskChainPatternsOf`)。必填:每个装配点都要说 ——
+     * `[]` = 任务座之下没有部署座的链成员(部署注册只在任务座之上、只有观察者,或没有部署注册)。读者 = {@link managedTightenOnlyOn}(托管车道在这些站上只许收紧)。
+     */
+    belowTaskChainPatterns: readonly string[];
 }
 /** 阶段三b 模型调用载体契约(prompt=直连一次 completion;agent=runTask 收敛后的 final text)。
  *  返回 ok/text 或 ok:false/error——载体自己兜超时(timeoutMs 是硬顶,载体可更严),绝不 throw。 */
@@ -655,20 +667,25 @@ export interface LlmHookExtra {
     transcript?: string;
 }
 /**
- * 律一 · 把校验过的 {@link RunnableHooksConfig} 铸成**一张** mods 注册 `settings.hooks`(任务座;档缺席 = `user`)。
- * 没有可挂的条目 → undefined(`TaskSpec.mods` 不铸)。`budgetMs` = {@link settingsHooksBudgetMs} 的读数(调用方交)。
+ * 律一 · 把校验过的 {@link RunnableHooksConfig} 铸成任务座上的 mods 注册 —— **一条车道一张**(车道 = `hook-source.ts` 的 {@link hookLaneOf}):
+ * 托管车道 `settings.hooks.managed`(托管插件相 + 托管策略相)在前、非托管车道 `settings.hooks` 在后({@link LANE_CHAIN_ORDER});没有组的车道不铸,两道都空 ⇒ `[]`(`TaskSpec.mods` 不铸)。
+ * 没有托管组的请求只得到非托管那一张,与分道之前逐字同(名字、挂站、预算、`once` 键)。`budgetMs` = {@link settingsHooksBudgetMs} 的读数(调用方交),两张各带一份同值。
+ *
+ * 一条规则:**车道是引擎的注册,不是一只 handler 里的分支** —— 每张注册自带引擎的 handler 预算、本服务的事件墙钟、LLM 条数、`once` 账与未跑成账本,两道之间不共用任何一只钟。
+ * 托管车道外层挂(`wrapClassic`):先把事件交下去(非托管车道、更下方的注册与引擎核心先答完,托管的表在这段停着),再在答回来的那份上跑自己的两相并折叠 ——
+ * 托管判的因此恒是要执行的那一份,非托管吃光自己的预算也挤不掉它(拒站上非托管失败 = 派发 fail-closed 终局;其余站引擎跳过非托管,托管照跑)。
  *
  * 构造约束(每一条都有引擎侧的硬理由):
  *  · `register` 同步、只读本注册自己的配置、不按腿分支 —— 返回 thenable 即 `config.mods_invalid`;委派子代把父的任务座当自己的派发,
  *    两条腿挂的是同一套 handler,父链才塌进子代的 phase 1(否则多一次约束判定);
- *  · `once` 去重集({@link runMatchingEntries} 的 `onceFired`)在铸注册这一层、每请求一份,不放进 `register`(那是每腿一次);
+ *  · `once` 去重集({@link runMatchingEntries} 的 `onceFired`)在铸注册这一层、每请求每车道一份,不放进 `register`(那是每腿一次);
  *  · 答案全部由本仓从 CC JSON 铸,引擎在 handler 边界屏(唯一判官),本仓不预屏;
- *  · 无意见 ⇒ `next(e)`(链 handler 返回 `undefined` 是站点违约,PreToolUse / UserPromptSubmit 的失败列是 refuse ⇒ 每次都会被拒);
- *    观察站的 handler 恒返回 `undefined` —— 两条都在 {@link hangClassic} 成形;
- *  · `uses.calls: []`(必填;本仓的 handler 不调 `$`),`uses.events` 从 {@link SETTINGS_HOOK_STATIONS} 派生;
- *  · 每只翻译的第二个入参是引擎的 `next.signal`(这只 handler 的预算 ∪ 这次派发被取消;见 {@link DEFAULT_SETTINGS_HOOKS_BUDGET_MS}):
+ *  · 内层无意见 ⇒ `next(e)`;外层无可添 ⇒ 下方的答案原样作数(链 handler 返回 `undefined` 是站点违约,PreToolUse / UserPromptSubmit 的失败列是 refuse ⇒ 每次都会被拒);
+ *    观察站的 handler 恒返回 `undefined` —— 三条都在 `classic-stations.ts` 的两种挂法里成形;
+ *  · `uses.calls: []`(必填;本仓的 handler 不调 `$`),`uses.events` 从 {@link SETTINGS_HOOK_STATIONS} 派生(只挂本车道有组的事件);
+ *  · 每只翻译的第二个入参是引擎的停表({@link HandlerHalt}:`next.signal` = 这只 handler 的预算 ∪ 这次派发结束 / 被取消,成因读 `next.budget`;见 {@link DEFAULT_SETTINGS_HOOKS_BUDGET_MS}):
  *    一路贯穿到命令腿的 spawn({@link runCommandHook}),本仓不自合成第二只、不另设钟。
  */
-export declare function createSettingsHooksRegistration(config: RunnableHooksConfig, ctx: HookRunnerContext, budgetMs: number): ModRegistration<EngineDollar> | undefined;
+export declare function createSettingsHooksRegistrations(config: RunnableHooksConfig, ctx: HookRunnerContext, budgetMs: number): readonly ModRegistration<EngineDollar>[];
 export {};
 //# sourceMappingURL=hook-runner.d.ts.map