@sema-agent/server 7.145.0 → 7.147.0

package/dist/execution-lane-caps.js

@@ -1,13 +1,13 @@
 import { homedir } from "node:os";
 import { StubExecutionEnv } from "@sema-agent/core";
-import { EXECUTION_LANE_WORDS as DECLARABLE_LANE_WORDS, EXECUTION_LANES, isBlankCoordinate, retiredLaneWordRefusal } from "@sema-agent/settings-schema/execution-lanes";
+import { EXECUTION_LANE_WORDS as DECLARABLE_LANE_WORDS, EXECUTION_LANES, LANE_SET_RULE, isBlankCoordinate, laneSetFlaws, retiredLaneWordRefusal } from "@sema-agent/settings-schema/execution-lanes";
 import { DECLARE_HOME_REMEDY, LANE_HOME_UNDECLARED_EVENT, LANE_HOME_UNMEASURED_EVENT, buildHomeAbsentNote, buildHomeUnmeasuredNote } from "./lane-home-probe.js";
 const NO = "unsupported";
 const YES = "supported";
 const SU = "single-user-only";
 export function executionLaneCaps(lane) {
     switch (lane) {
-        case "in-process":
+        case "none":
             return {
                 callerCwd: NO,
                 backgroundShell: NO,
@@ -16,7 +16,7 @@ export function executionLaneCaps(lane) {
                 sandboxSendUserFile: NO,
                 remoteScratchpad: NO,
                 worktreeIsolation: NO,
-                tenantSeparation: YES,
+                tenantSeparation: executionLaneRow(lane).tenantSeparation,
             };
         case "host":
             return {
@@ -119,7 +119,7 @@ export function sandboxReadFloorState(lane, knob) {
             return readFloorStateOf(k, false);
     }
 }
-const IN_PROCESS_BLOCK = new StubExecutionEnv().capabilities;
+const NONE_BLOCK = new StubExecutionEnv().capabilities;
 const HOST_BLOCK = Object.freeze({ isolation: false, suspendable: false, sharesProcessTable: true, canonicalPathAuthoritative: true, hostLocalPaths: true, externalContentTarget: false, io: true, keepsReadFloor: false });
 const E2B_SHAPE = Object.freeze({ isolation: true, suspendable: true, sharesProcessTable: false, canonicalPathAuthoritative: true, hostLocalPaths: false, externalContentTarget: false, io: true });
 const K8S_SHAPE = Object.freeze({ isolation: true, suspendable: false, sharesProcessTable: false, canonicalPathAuthoritative: true, hostLocalPaths: false, externalContentTarget: false, io: true });
@@ -144,8 +144,8 @@ const DEVICE_BLOCK = Object.freeze({ isolation: false, suspendable: false, share
 const NO_SUB_KNOBS = Object.freeze({ snapshotStore: false, sandboxReadFloor: undefined });
 function laneBlock(lane, sub) {
     switch (lane) {
-        case "in-process":
-            return IN_PROCESS_BLOCK;
+        case "none":
+            return NONE_BLOCK;
         case "host":
             return HOST_BLOCK;
         case "e2b":
@@ -161,13 +161,13 @@ function laneBlock(lane, sub) {
     }
 }
 export function capabilitiesFor(deployment) {
-    const lane = executionLaneOf(deployment.remoteExec?.provider);
+    const lane = executionLaneOf(deployment.remoteExec.provider);
     if (lane === undefined)
         return undefined;
-    return laneBlock(lane, { snapshotStore: lane === "k8s" && Boolean(deployment.remoteExec?.s3Snapshot), sandboxReadFloor: deployment.sandboxReadFloor });
+    return laneBlock(lane, { snapshotStore: lane === "k8s" && Boolean(deployment.remoteExec.s3Snapshot), sandboxReadFloor: deployment.sandboxReadFloor });
 }
 export function laneSandboxReadFloorState(deployment) {
-    const lane = executionLaneOf(deployment.remoteExec?.provider);
+    const lane = executionLaneOf(deployment.remoteExec.provider);
     if (lane === undefined)
         return undefined;
     switch (lane) {
@@ -175,7 +175,7 @@ export function laneSandboxReadFloorState(deployment) {
         case "k8s":
         case "local-docker":
             return sandboxReadFloorState(lane, deployment.sandboxReadFloor);
-        case "in-process":
+        case "none":
         case "host":
         case "ssh":
         case "adb":
@@ -183,12 +183,11 @@ export function laneSandboxReadFloorState(deployment) {
             return undefined;
     }
 }
-export const ALL_EXECUTION_LANES = Object.freeze(["in-process", ...DECLARABLE_LANE_WORDS]);
+export const ALL_EXECUTION_LANES = Object.freeze([...DECLARABLE_LANE_WORDS]);
 const EXECUTION_LANE_SET = new Set(ALL_EXECUTION_LANES);
 export function isExecutionLane(word) {
     return EXECUTION_LANE_SET.has(word);
 }
-export const REMOTE_EXEC_PROVIDER_WORDS = Object.freeze([...DECLARABLE_LANE_WORDS]);
 const LANE_ROWS = (() => {
     const rows = new Map();
     for (const row of EXECUTION_LANES) {
@@ -217,53 +216,48 @@ export function isBlankRequiredEnvValue(value) {
 export function laneMissingEnv(lane, env) {
     return laneRequiredEnv(lane).filter((name) => isBlankRequiredEnvValue(env[name]));
 }
+const LANE_ROW_OF_WORD = LANE_ROWS;
+function laneSetFlawPhrase(flaw) {
+    switch (flaw.kind) {
+        case "empty_set":
+            return "it has no entries";
+        case "blank_entry":
+            return `entry ${flaw.at + 1} is empty or whitespace-only`;
+        case "unknown":
+            return `"${String(flaw.word)}" (entry ${flaw.at + 1}) is not an execution lane`;
+        case "retired":
+            return retiredLaneWordRefusal(flaw.word) ?? `"${flaw.word}" (entry ${flaw.at + 1}) is a retired execution lane`;
+        case "duplicate":
+            return `"${flaw.lane}" is listed twice (again at entry ${flaw.at + 1})`;
+        case "not_alone":
+            return `"${flaw.lane}" (no execution environment for the agent's tools) must be the only entry`;
+    }
+}
 export function readDeclaredLaneTable(raw) {
     const segments = raw.split(",");
-    const lanes = [];
-    for (const [i, segment] of segments.entries()) {
-        if (segment === "") {
-            return { refusal: `REMOTE_EXEC="${raw}" has an empty entry at position ${i + 1} — it is an ordered, comma-separated list of execution lanes (the first is the default) with no blank entries; valid lanes: ${REMOTE_EXEC_PROVIDER_WORDS.join(" | ")}.` };
-        }
-        const lane = REMOTE_EXEC_PROVIDER_WORDS.find((w) => w === segment);
-        const retired = lane === undefined ? retiredLaneWordRefusal(segment) : undefined;
-        if (retired !== undefined)
-            return { refusal: `REMOTE_EXEC="${raw}": ${retired}.` };
-        if (lane === undefined) {
-            return {
-                refusal: `REMOTE_EXEC="${raw}"${segments.length > 1 ? ` lists "${segment}", which` : ""} is not an execution lane — valid: ${REMOTE_EXEC_PROVIDER_WORDS.join(" | ")}. ` +
-                    `An unrecognized value used to fall through to the host/in-process lane silently; refusing to start instead (#157).`,
-            };
-        }
-        if (lanes.includes(lane))
-            return { refusal: `REMOTE_EXEC="${raw}" lists "${lane}" twice — each execution lane appears once (the first one is the default).` };
-        lanes.push(lane);
+    const flaws = laneSetFlaws(segments);
+    if (flaws.length > 0) {
+        return {
+            refusal: `REMOTE_EXEC="${raw}" is not a valid execution lane set: ${flaws.map(laneSetFlawPhrase).join("; ")}. ` +
+                `REMOTE_EXEC (the lane set, comma-separated) ${LANE_SET_RULE}. Refusing to start rather than guessing a lane (#157).`,
+        };
     }
+    const lanes = segments.map((segment) => {
+        const row = LANE_ROW_OF_WORD.get(segment);
+        if (row === undefined)
+            throw new Error(`readDeclaredLaneTable: the lane-set judge accepted "${segment}" but the lane table has no row for it`);
+        return row.lane;
+    });
     const [first, ...rest] = lanes;
     if (first === undefined)
         throw new Error(`readDeclaredLaneTable: "${raw}" split into no segments`);
     return { lanes: [first, ...rest] };
 }
-export function executionLaneRequiredRefusal(deployment) {
-    if (!deployment.requireExecutionLane || executionLaneOf(deployment.remoteExec?.provider) !== "in-process")
-        return undefined;
-    return (`REQUIRE_EXECUTION_LANE=true but NO execution lane is named on this deployment — refusing to start. ` +
-        `With no lane the engine falls back to its in-process stub environment: the hands band (the roster entries whose ` +
-        `wiring_manifest mountedBy is "hands", Bash among them) is not mounted, while the rest of the roster still executes, ` +
-        `and every task still returns status=completed — for any request that needs a hand, indistinguishable from "the model ` +
-        `chose not to use its tools". (How much of the roster is mounted is a per-run fact: read the wiring_manifest event and ` +
-        `count entries whose mountedBy is "hands" — never judge by tool names.) ` +
-        `Cause: REMOTE_EXEC is unset/empty AND CONFIG_PROVIDER is not "local". ` +
-        `Fix: set REMOTE_EXEC to one of ${REMOTE_EXEC_PROVIDER_WORDS.join(" | ")} (and that lane's required env), ` +
-        `or set CONFIG_PROVIDER=local to take the single-machine \`host\` default, ` +
-        `or unset REQUIRE_EXECUTION_LANE to keep running without hands on purpose.`);
-}
 export function executionLaneOf(provider) {
-    if (provider === undefined)
-        return "in-process";
     return isExecutionLane(provider) ? provider : undefined;
 }
 export function deployedExecutionLanes(config) {
-    return [executionLaneOf(config.remoteExec?.provider)];
+    return [config.remoteExec.provider];
 }
 export function handsOnWorkerFilePlane(lane) {
     const block = laneBlock(lane, NO_SUB_KNOBS);
@@ -273,7 +267,7 @@ export function laneBindsReads(lane) {
     switch (lane) {
         case "host":
             return true;
-        case "in-process":
+        case "none":
         case "e2b":
         case "k8s":
         case "ssh":
@@ -293,7 +287,7 @@ export function laneMeasuresHome(lane) {
         case "host":
             return true;
         case "device":
-        case "in-process":
+        case "none":
             return false;
     }
 }
@@ -304,7 +298,7 @@ export function laneReadFaceDefault(lane) {
         case "local-docker":
             return "open";
         case "host":
-        case "in-process":
+        case "none":
         case "ssh":
         case "adb":
         case "device":
@@ -324,11 +318,8 @@ export function executionLaneHomeDir(deployment) {
     const declared = deployment.remoteExecHomeDir;
     if (declared !== undefined)
         return declared;
-    const lane = executionLaneOf(deployment.remoteExec?.provider);
-    if (lane === undefined)
-        return undefined;
-    switch (lane) {
-        case "in-process":
+    switch (deployment.remoteExec.provider) {
+        case "none":
         case "host":
             return homedir();
         case "e2b":
@@ -348,23 +339,22 @@ export function buildLaneHomeClaim(deployment) {
     return { homeDir: home, homeDirSource: deployment.remoteExecHomeDir !== undefined ? "declared" : "lane" };
 }
 export function buildLaneHomeBootNote(deployment) {
-    const lane = executionLaneOf(deployment.remoteExec?.provider);
-    if (lane === undefined || !laneWiresExecutionEnv(lane))
+    const homeLane = deployment.remoteExec.provider;
+    if (!laneWiresExecutionEnv(homeLane))
         return undefined;
-    if (laneMeasuresHome(lane))
+    if (laneMeasuresHome(homeLane))
         return undefined;
     const home = executionLaneHomeDir(deployment);
     if (home === undefined)
-        return { event: LANE_HOME_UNDECLARED_EVENT, note: buildHomeAbsentNote(lane, "REMOTE_EXEC_HOME_DIR is unset, and this lane cannot read its execution environment's home", DECLARE_HOME_REMEDY) };
-    return { event: LANE_HOME_UNMEASURED_EVENT, note: buildHomeUnmeasuredNote(lane, home) };
+        return { event: LANE_HOME_UNDECLARED_EVENT, note: buildHomeAbsentNote(homeLane, "REMOTE_EXEC_HOME_DIR is unset, and this lane cannot read its execution environment's home", DECLARE_HOME_REMEDY) };
+    return { event: LANE_HOME_UNMEASURED_EVENT, note: buildHomeUnmeasuredNote(homeLane, home) };
 }
 export function buildReadDenyFloorUnkeptNote(deployment) {
     if (!deployment.readDenyFloorRequired)
         return undefined;
     if (capabilitiesFor(deployment)?.keepsReadFloor === true)
         return undefined;
-    const lane = executionLaneOf(deployment.remoteExec?.provider) ?? String(deployment.remoteExec?.provider);
-    return (`READ_DENY_FLOOR_REQUIRED=true, but the "${lane}" execution lane does not keep the read-deny byte floor (a program its commands run can open a path ` +
+    return (`READ_DENY_FLOOR_REQUIRED=true, but the "${deployment.remoteExec.provider}" execution lane does not keep the read-deny byte floor (a program its commands run can open a path ` +
         `the read-deny table refuses). Every run whose read-deny table has rows — the shipped default tiers put rows there unless READ_DENY_BUILTIN_TIERS=none — ` +
         `is refused before any command starts (config.read_deny_floor_unkept; a synchronous submit answers 409). ` +
         `Either run on a lane that keeps the floor, or unset READ_DENY_FLOOR_REQUIRED to run with one operator notice per run instead.`);

package/dist/execution-placement.d.ts

@@ -162,8 +162,9 @@ export declare class SessionForkInProgressError extends Error {
     constructor(sessionId: string);
 }
 /**
- * 写事务内的认领读命中(读写序律,`plugins/execution-placement-sql.ts` 的 `lockRootAndReadClaim`):改根住客 / 放置的写者在自己的事务里先锁根
- * `session_meta` 行、再锁定读 `task_active(root)`,读到认领 ⇒ 回滚、一个字节不写、抛它。只 SQL 后端(local 不立此律:没有 device 工厂)。
+ * 写口在写事务 / 写锁内的认领读命中:SQL = 读写序律(`plugins/execution-placement-sql.ts` 的 `lockRootAndReadClaim`:改根住客 / 放置的写者在自己的事务里先锁根
+ * `session_meta` 行、再锁定读 `task_active(root)`,读到认领 ⇒ 回滚、一个字节不写、抛它);local = 这只会话的写锁内读 run 店的认领(`markMirror` 返回 `active` 臂;
+ * 三个导入写口经 {@link judgeImportWrite} 抛它)—— 删除终刀与 device 首绑在写事务内的认领读仍只在 SQL 后端(local 没有 device 工厂)。
  * 具名类型、**不带 wire 码**:各门按自己的既有码答(导入 409 `session_active`、删除 409 `conflict.session_active_run`),体带 `activeTaskId`。
  */
 export declare class SessionActiveRunError extends Error {
@@ -181,6 +182,21 @@ export declare const WRITABLE: "writable";
 export declare function settledPlaceOutcome(root: string, reading: ExecutionPlacementReading | undefined, occupant: SessionFace, wanted: ExecutionWriterCell): PlaceOutcome | typeof WRITABLE;
 /** markMirror 的唯一判官(认领那一半在本判官之后,SQL 与 local 各在自己的写事务 / 写锁内判):行不在 / 住客不同 ⇒ `gone`;writer ⇒ `writer`;mirror ⇒ `mirrored`(幂等,零写);absent ⇒ {@link WRITABLE};forking ⇒ 抛。 */
 export declare function settledMirrorOutcome(root: string, reading: ExecutionPlacementReading | undefined, occupant: SessionFace): MarkMirrorOutcome | typeof WRITABLE;
+/** {@link judgeImportWrite} 的判:放行,或拒(拒的载荷是写口抛的那只 typed 错;SQL 的事务内钩原样交给店,local 直接抛)。 */
+export type ImportWriteVerdict = "proceed" | {
+    readonly refuse: SessionActiveRunError | SessionWriterPresentError | SessionForkInProgressError;
+};
+/**
+ * 三个导入写口(整段 `importEntries` / `replaceEntries` / 暂存提交)落定这一行**之前**的唯一判官,**连序**在内(SQL 的事务内钩 `import` 臂与 local 的写锁内同调,两店不各抄一份):
+ * 先读认领 —— 在 ⇒ {@link SessionActiveRunError};再读这一格 —— `writer` ⇒ {@link SessionWriterPresentError}(带车道)、`forking` ⇒ {@link SessionForkInProgressError};
+ * `absent` / `mirror` ⇒ 放行(落 mirror 由调用方写)。读口由调用方给、**按需读**:认领在 ⇒ 不读格(SQL:不发格那一句锁定读;local:不探存档)。
+ * 读与判必须在写者独占的同一刻里:SQL = 锁根行之后、同一连接;local = 这只会话的写锁内、写格之前(取锁 → 读认领 → 判 → 写)。
+ * 返回判、不抛:拒之后一个字节不写由调用方保证(SQL 回滚,local 判在第一笔写之前)。
+ */
+export declare function judgeImportWrite(root: string, read: {
+    readonly claim: () => Promise<string | null | undefined>;
+    readonly cell: () => Promise<ExecutionPlacementCell>;
+}): Promise<ImportWriteVerdict>;
 /** device 车道首绑(absent → writer(device, D) 或 writer(device, ∅) → writer(device, D))的结果(设备店的事务 / 内存参照实现同调)。 */
 export type DeviceBindOutcome = {
     readonly outcome: "bound";

package/dist/execution-placement.js

@@ -94,6 +94,25 @@ export function settledMirrorOutcome(root, reading, occupant) {
         }
     }
 }
+export async function judgeImportWrite(root, read) {
+    const claim = await read.claim();
+    if (claim !== null && claim !== undefined)
+        return { refuse: new SessionActiveRunError(root, claim) };
+    const cell = await read.cell();
+    switch (cell.role) {
+        case "writer":
+            return { refuse: new SessionWriterPresentError(root, cell.lane) };
+        case "forking":
+            return { refuse: new SessionForkInProgressError(root) };
+        case "absent":
+        case "mirror":
+            return "proceed";
+        default: {
+            const unknownRole = cell;
+            throw new Error(`judgeImportWrite: no arm for ${JSON.stringify(unknownRole)}`);
+        }
+    }
+}
 export function settledDeviceBindOutcome(root, reading, occupant, deviceId) {
     if (reading === undefined || !sameOccupant(reading.occupant, occupant))
         return { outcome: "gone" };

package/dist/file-history-disclosure.d.ts

@@ -2,9 +2,9 @@
  * [ref]④ —— SQL file-history 店的 **typed 永久失败**披露座:散文一个铸点 + 机器面一只 sink。
  *
  * ## 病(基线 v7.79.0 逐行亲核 + 亲跑)
- * `plugins/blob-backend.ts:55` 的 `BlobTooLargeError` 带 typed 判别码 `blob_too_large_for_sql`,头注
+ * `stores-sql/blob-index-sql.ts` 的 `BlobTooLargeError` 带 typed 判别码 `blob_too_large_for_sql`,头注
  * 原话「绝不能与 transient 写失败混在一类(那类是可重试的 502;这类重试永远不会成功)」。可它一旦被
- * `plugins/file-history-store-sql.ts` 的任何一条 `catch` 折进 `FileHistoryResult.error.message`,判别码
+ * `stores-sql/file-history-store-sql.ts` 的任何一条 `catch` 折进 `FileHistoryResult.error.message`,判别码
  * 就只剩散文,**机器一位都读不到**。两条腿各自的后果:
  *
  * · **snapshot(边界捕获)腿**:引擎把失败包成一句散文交给 `RunnerDeps.onError({phase:"rewind"})`

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,36 @@ export interface DrainDeadlineRefusal {
 }
 /** 入口的答:契约回执(进入 / 已在排空),或期限越界的拒(只在调用方声明了上界时出现)。按 `state` 穷举。 */
 export type DrainEntryAnswer = DrainReceipt | DrainDeadlineRefusal;
+/**
+ * 在飞数的**分项**(`GET /health` 的 `inflightBreakdown`)—— 同一份分项派生**两个事实**,不是两份计数(计法表全文 = 契约 `docs/ASSISTANT-WIRE-CONTRACT.md` 的 `/health` 节):
+ *  · **总数**(可观测事实,{@link inflightTotal} = `/health.inflight`):这台引擎此刻托管着多少活 = `http + leader + backgroundAgents + sessionResident`;
+ *  · **阻断集**(判据,{@link blockingInflightOf} = `drainState.blockingInflight`):还有没有**必须等完**的活 = `http + leader + backgroundAgents`。
+ *    排空等的、孤儿窗 / 附着租约自退 / SIGHUP 空闲窗判「可以停了吗」读它。`sessionResident` 不在其内。
+ * 四项:
+ *  · `http` —— 本副本的 HTTP 腿:在飞 run 集(`inflightRuns ∪ steerableRuns`)+ 没有登记身份的同步计费腿(`/v1/tasks` 的同步腿)+ admission 期的非探针请求;
+ *  · `leader` —— leader 口的后台 run(`leaderEndpoint.inflight()`);
+ *  · `backgroundAgents` —— 活过起它的那一条腿、仍在跑的后台子代理(core `backgroundScope:"session"`;`session-resident-background.ts` 的读法:停驻的不计)。
+ *    它进阻断集:它是一条在干活的模型腿,干完自己收尾(在审批 / 问答卡上等人时行仍是 `running`、照计;窗满转成耐久停驻后不再计);不等 = 受控退把还在干活的子代理中断。
+ *    上界 = 停滞收割窗 `BG_AGENT_STALL_MS`:读口每读一次先让引擎收掉静默满窗的子代理(挂死的,或收尾时 core 等的那次账本写挂住的)再数 —— 判停窗不再被一只僵尸无界地撑着;
+ *    SIGTERM 排空另以期限为界;
+ *  · `sessionResident` —— 会话驻留的后台 shell / monitor(同一读法:不含 retain 行)。
+ *    它只进总数、不进阻断集:一只不退出的驻留 shell(`while true`)若阻断,崩溃孤儿引擎就永生、排空每次等满窗;窗到 / 排空完成即由退出边界的后台收割收掉
+ *    (retain 行按 retain 既有语义,活过受控退)。
+ * 不进任何一项的(计法表成文的行):停驻待赎回的 run 与停驻的后台子代理(耐久,不占执行座)· 活过起它的腿的 workflow(任务表分不出它在干活还是在等人,见
+ * `session-resident-background.ts` 头注)· retain 的后台 shell · 只读订阅流(只进 `attachedStreams`)。
+ * 四项在同一次读里求出(`http/server.ts` 的 `inflightBreakdown` 是唯一的分项函数,两个和都读它),`/health` 的 `inflight` 与 `inflightBreakdown` 因此永远自洽,
+ * 判停与 `/health` 也不会各有一份算法。只有这两个函数各写一次这两个和,没有第三张计法表。
+ */
+export interface InflightBreakdown {
+    readonly http: number;
+    readonly leader: number;
+    readonly backgroundAgents: number;
+    readonly sessionResident: number;
+}
+/** 阻断集 = 必须等完的活 = `drainState.blockingInflight()`(`sessionResident` 不在内)。 */
+export declare function blockingInflightOf(b: InflightBreakdown): number;
+/** 总数 = 引擎此刻托管的全部活 = `/health.inflight`(= 阻断集 + 会话驻留的 shell / monitor 项)。 */
+export declare function inflightTotal(b: InflightBreakdown): number;
 /**
  * 引擎与 HTTP 面共享的排空盒子(装配层建一只,`createHttpServer` 与收尾链各自往上装读口 / 入口)。
  *  · `draining` / `since` / `actionId` / `deadlineAt` —— **只由** {@link enter} 整组写入(排空事实 = 契约 `EngineDraining`);
@@ -75,8 +105,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 +116,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 + backgroundAgents`。排空等的(`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 + b.backgroundAgents;
+}
+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/fleet/serving-lease.js

@@ -1,5 +1,6 @@
-import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { atomicWriteFileSync } from "../plugins/owner-only-file-mode.js";
 import { SERVING_LEASE_TTL_DEFAULT_MS, readServingLeaseResponse } from "@sema-agent/settings-schema/fleet";
 import { centerFetch } from "../web-admin-client/center-request.js";
 import { recordFailOpen } from "../observability/fail-open.js";
@@ -66,10 +67,8 @@ export function createServingLeaseClient(o) {
             return false;
         }
         const record = { worker: o.center.worker, generation: o.generation, reason, at: epoch() };
-        const tmp = `${stickyPath}.tmp-${process.pid}`;
         try {
-            writeFileSync(tmp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
-            renameSync(tmp, stickyPath);
+            atomicWriteFileSync(stickyPath, `${JSON.stringify(record)}\n`, { durability: "best-effort" });
             return true;
         }
         catch (err) {

package/dist/history-anchor.d.ts

@@ -0,0 +1,22 @@
+import type { ResumeAnchorStore } from "./plugins/store-backend.js";
+/** 两族:码与句尾(出路)。键 = 族名;加一族 = 加一行(两只调用方按族名取,不手写码)。 */
+declare const HISTORY_ANCHOR_FAMILIES: {
+    /** 分叉式回卷(会话在那条消息处分叉)。 */
+    readonly resumeAt: {
+        readonly code: "resume_at.unknown_event";
+        readonly wayOut: "give an explicit resumeAt";
+    };
+    /** 只恢复代码(提交体 `rewindFilesTo` 与 run 外口的 `to` 同族同码)。 */
+    readonly rewindFilesTo: {
+        readonly code: "rewind_files_to.unknown_event";
+        readonly wayOut: "name another prompt";
+    };
+};
+export type HistoryAnchorFamily = keyof typeof HISTORY_ANCHOR_FAMILIES;
+/**
+ * 手柄 → entry id;未知 ⇒ 抛 404(族码 + 共用半句)。`owner` = 锚行的属主键(锚店的 null-safe 属主守卫):提交面传提交者,run 外口传会话属主
+ * (门已证调用方读得到这只会话;锚由这只会话的提交落下,属主键就是会话属主 —— 运维代人回退读的是同一把键)。`field` = 句首点名的请求字段。
+ */
+export declare function resolveHistoryAnchor(family: HistoryAnchorFamily, store: Pick<ResumeAnchorStore, "resolve">, sessionId: string, handle: string, owner: string | null, field: string): Promise<string>;
+export {};
+//# sourceMappingURL=history-anchor.d.ts.map

package/dist/history-anchor.js

@@ -0,0 +1,14 @@
+import { HttpError } from "./security.js";
+const NO_ANCHOR_HINT = "no rewind anchor is recorded under that handle (a prompt that carried attachments records none when its attachment frames were interrupted or their count did not match)";
+const HISTORY_ANCHOR_FAMILIES = {
+    resumeAt: { code: "resume_at.unknown_event", wayOut: "give an explicit resumeAt" },
+    rewindFilesTo: { code: "rewind_files_to.unknown_event", wayOut: "name another prompt" },
+};
+export async function resolveHistoryAnchor(family, store, sessionId, handle, owner, field) {
+    const entryId = await store.resolve(sessionId, handle, owner);
+    if (entryId !== undefined)
+        return entryId;
+    const { code, wayOut } = HISTORY_ANCHOR_FAMILIES[family];
+    throw new HttpError(404, `${field}: no such message in this session (${code}) — ${NO_ANCHOR_HINT}; ${wayOut}`, { code });
+}
+//# sourceMappingURL=history-anchor.js.map

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/command-spawn.d.ts

@@ -6,13 +6,10 @@ export interface HookPluginContext {
     readonly dataDir?: string;
     readonly options?: Readonly<Record<string, string>>;
 }
-/** 本仓会跑的 command 条目:契约形 + 本仓读的两只 wire 键。 */
+/** 本仓会跑的 command 条目:契约形(含 `args` / `onFailure`)+ 本仓先于契约读的 wire 键 `plugin`(契约包不承运它;收口票 [ref])。 */
 export type RunnableCommandHookEntry = CommandHookEntry & {
-    readonly args?: readonly string[];
     readonly plugin?: HookPluginContext;
 };
-/** 受理面:`args` 合形(串数组、元素无 NUL)⇒ 拷贝;否则 `undefined`。 */
-export declare function readHookArgs(raw: unknown): string[] | undefined;
 /** 受理面:`plugin` 合形 ⇒ 拷贝;否则 `undefined`。路径与 `skills[i].baseDir` 同一只判(契约包 `isAbsoluteHostPath`:绝对、无 `..` 段、无 NUL、有长度上限);不做存在性检查(那是执行面的事)。 */
 export declare function readHookPlugin(raw: unknown): HookPluginContext | undefined;
 /** 插件上下文的总字符数(服务侧上限 `plugin` 帽的量):名 + 根 + 数据目录 + 各选项的键与值。 */