@sema-agent/server 7.146.0 → 7.148.0

package/dist/execution-lane-caps.js

@@ -1,29 +1,27 @@
 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,
                 scheduler: NO,
-                lsp: NO,
                 sandboxSendUserFile: NO,
                 remoteScratchpad: NO,
                 worktreeIsolation: NO,
-                tenantSeparation: YES,
+                tenantSeparation: executionLaneRow(lane).tenantSeparation,
             };
         case "host":
             return {
                 callerCwd: SU,
                 backgroundShell: SU,
                 scheduler: SU,
-                lsp: SU,
                 sandboxSendUserFile: NO,
                 remoteScratchpad: NO,
                 worktreeIsolation: YES,
@@ -34,7 +32,6 @@ export function executionLaneCaps(lane) {
                 callerCwd: NO,
                 backgroundShell: YES,
                 scheduler: NO,
-                lsp: NO,
                 sandboxSendUserFile: YES,
                 remoteScratchpad: YES,
                 worktreeIsolation: NO,
@@ -45,7 +42,6 @@ export function executionLaneCaps(lane) {
                 callerCwd: NO,
                 backgroundShell: YES,
                 scheduler: NO,
-                lsp: NO,
                 sandboxSendUserFile: YES,
                 remoteScratchpad: YES,
                 worktreeIsolation: NO,
@@ -56,7 +52,6 @@ export function executionLaneCaps(lane) {
                 callerCwd: NO,
                 backgroundShell: NO,
                 scheduler: NO,
-                lsp: NO,
                 sandboxSendUserFile: SU,
                 remoteScratchpad: YES,
                 worktreeIsolation: NO,
@@ -67,7 +62,6 @@ export function executionLaneCaps(lane) {
                 callerCwd: NO,
                 backgroundShell: NO,
                 scheduler: NO,
-                lsp: NO,
                 sandboxSendUserFile: NO,
                 remoteScratchpad: NO,
                 worktreeIsolation: NO,
@@ -78,7 +72,6 @@ export function executionLaneCaps(lane) {
                 callerCwd: NO,
                 backgroundShell: NO,
                 scheduler: NO,
-                lsp: NO,
                 sandboxSendUserFile: NO,
                 remoteScratchpad: YES,
                 worktreeIsolation: NO,
@@ -89,7 +82,6 @@ export function executionLaneCaps(lane) {
                 callerCwd: YES,
                 backgroundShell: NO,
                 scheduler: NO,
-                lsp: NO,
                 sandboxSendUserFile: NO,
                 remoteScratchpad: YES,
                 worktreeIsolation: NO,
@@ -119,7 +111,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 +136,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 +153,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 +167,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 +175,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,72 +208,53 @@ 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);
     return block.io && block.hostLocalPaths;
 }
-export function laneBindsReads(lane) {
-    switch (lane) {
-        case "host":
-            return true;
-        case "in-process":
-        case "e2b":
-        case "k8s":
-        case "ssh":
-        case "adb":
-        case "device":
-        case "local-docker":
-            return false;
-    }
-}
 export function laneMeasuresHome(lane) {
     switch (lane) {
         case "k8s":
@@ -293,7 +265,7 @@ export function laneMeasuresHome(lane) {
         case "host":
             return true;
         case "device":
-        case "in-process":
+        case "none":
             return false;
     }
 }
@@ -304,7 +276,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 +296,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 +317,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

@@ -9,7 +9,7 @@
  *    委派分区行读作「不在」。
  *  · **读只有一只**:会话店的执行席 {@link ExecutionPlacementSeat.read}(一次行读:住客 + 格;行不在 / 委派分区行 ⇒ `undefined`;读故障抛,不吞成 `absent`)。
  *    跨行的聚合也只有一只:设备店的绑定数 `countDeviceBindings`(writer(device, D) 的格数 = {@link boundDeviceOf} 的聚合;只交数,不交根 id)。
- *  · **写只按住客谓词** `(root, incarnation, owner) ∧ placement_kind IS NULL`:住客换了(删后重建,哪怕同一属主;local M10 窗内的认领)= 这一格不在 ⇒ 落空;
+ *  · **写只按住客谓词** `(root, incarnation, owner) ∧ placement_kind IS NULL`:住客换了(删后重建,哪怕同一属主)= 这一格不在 ⇒ 落空;
  *    0 行一律按住客复读分类({@link settledPlaceOutcome} / {@link settledMirrorOutcome} / {@link settledDeviceBindOutcome}),**永不对现住客重试**。
  *  · **没有的转换**:writer ↔ mirror、writer(L) → writer(L')(device 车道的换绑 writer(device, D) → writer(device, D') 除外,它有自己的语句与门)。
  *  · **放置存在 ⇒ 住客存在**:放置是行的列 / 格,删会话即删放置;建行恒 absent(SQL 建行 INSERT 列名显式;local 新格整格新铸),导入新建的行同锁落 mirror。
@@ -22,6 +22,7 @@ import { type SessionHead } from "@sema-agent/core";
 import type { DeviceOwner } from "./device-store.js";
 import type { ExecutionLane } from "./execution-lane-caps.js";
 import type { SessionFace } from "./session-incarnation.js";
+import type { SessionWrite } from "./plugins/store-backend.js";
 /** writer(device, D) 的 D:设备、绑定属主(= 设备属主)、换绑序号、放下时刻(ISO)。 */
 export interface ExecutionDeviceCell {
     readonly id: string;
@@ -108,13 +109,22 @@ export interface UnusableArchive {
     readonly fault: unknown;
 }
 export declare function isUnusableArchive(x: object | undefined): x is UnusableArchive;
+/** {@link LocalPlacementBackfillSeat.backfill} 的结局(随 M32):写成了 writer · 这一格此刻不归回填(行不在 / placed / 已有执行位 / forking)· 车道表不是一项而这一格要回填(不写)· 存档读不出(点名跳过)。 */
+export type LocalPlacementBackfillOutcome = {
+    readonly outcome: "placed";
+} | {
+    readonly outcome: "skipped";
+} | {
+    readonly outcome: "ambiguous";
+} | UnusableArchive;
 /**
- * 一次性迁移 M32 **local 腿**的席(随 M32 · 窗口见 `plugins/one-time-migrations.ts` 登记表;只 local 有:SQL 的行就是会话,没有「会话元数据格缺 ∧ 存档读不出」这一形)。`read` 与 {@link ExecutionPlacementSeat.read} 是
- * **同一读**(同一只实现的本体),只差一点:这只会话的存档读不出(格缺而探针读不出,或 fork 创建的格而探针读不出)⇒ **答 {@link UnusableArchive} 而不抛** —— 开机回填不动存档、
- * 只补一格放置,读不出的会话由它点名跳过(该会话的请求照旧答存档的故障);席的 `read` 对同一形照旧抛。`place` 就是席的 `place`。
+ * 一次性迁移 M32 **local 腿**的席(随 M32 · 窗口见 `plugins/one-time-migrations.ts` 登记表;只 local 有:SQL 的行就是会话,没有「会话元数据格缺 ∧ 存档读不出」这一形)。
+ * 唯一成员 `backfill(root, lanes)`:在这只会话的写锁里**观察一次**(与执行席的读同一只观察),absent 的那一格 ∧ 车道表只有一项 ⇒ **一笔**写成 writer(格缺就在同一笔里铸化身);
+ * 车道表不是一项 ⇒ `ambiguous`、不写;观察抛(这只会话的存档读不出)⇒ 答 {@link UnusableArchive} 而不抛 —— 开机回填不动存档、只补一格放置,读不出的会话由它点名跳过
+ * (该会话的请求照旧答存档的故障)。观察与写在同一节锁里:读与写之间没有别的写者。
  */
-export interface LocalPlacementBackfillSeat extends Pick<ExecutionPlacementSeat, "place"> {
-    read(root: string): Promise<ExecutionPlacementReading | UnusableArchive | undefined>;
+export interface LocalPlacementBackfillSeat {
+    backfill(root: string, lanes: readonly ExecutionLane[]): Promise<LocalPlacementBackfillOutcome>;
 }
 /** wire 投影(新读面 + 受理回声共用)。 */
 export type ExecutionPlacementView = {
@@ -135,7 +145,7 @@ export type ExecutionPlacementView = {
 export declare function executionPlacementView(cell: ExecutionPlacementCell): ExecutionPlacementView;
 /**
  * 住客谓词的 JS 读法(SQL `incarnation = ? AND owner <=> ?` 的对位)= core 的行期望判官 `sessionRowMatches`(会话行格写原语锁内判的也是它,
- * `session-row.ts` 的 `judgeSessionRowWrite`):属主与化身两样都没变才是判过的那一位 —— 同一化身的属主会变(local M10 认领、identical 重戳、
+ * `session-row.ts` 的 `judgeSessionRowWrite`):属主与化身两样都没变才是判过的那一位 —— 同一化身的属主会变(identical 重戳、
  * SQL 导入提交点改属主)。两侧收「属主 + 化身」那一读:活住客(`SessionFace`)与店的头(`SessionHead`,门判过的那一读)。三处调用方:
  *  · 执行格的写口判官(本模块)与执行上下文解析器步 ① 的 `judged` 复核(`http/execution-context.ts`)—— 一侧恒是执行席的读数(住客经 `sessionFaceFromRow` 解码,令牌非空);
  *  · 会话通知门投递前的住客复核(`session-notify-door.ts` 的 `recheck`)—— 两侧都是会话店的头读:不铸化身的店上**两侧都没有令牌**。
@@ -162,8 +172,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` 臂;
+ * 三个导入写口、删除与 placed 行的终结经 {@link judgeSessionWrite} 抛它)—— device 首绑在写事务内的认领读只在 SQL 后端(local 没有 device 工厂)。
  * 具名类型、**不带 wire 码**:各门按自己的既有码答(导入 409 `session_active`、删除 409 `conflict.session_active_run`),体带 `activeTaskId`。
  */
 export declare class SessionActiveRunError extends Error {
@@ -181,6 +192,51 @@ 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;
+/**
+ * 删净在删会话的执行体(写词 `erase`;`session-erase.ts`)在根行锁里读到:这一行此刻**不是**这一次删除的在删态 —— 另一次删除接管了它(换了令牌)、它已经删完(行不在 / 同 id 的新住客)。
+ * 一个字节不删。具名类型、不带 wire 码:协调器把它读作「这次尝试被接管」(路由 409 `conflict.session_deleting`)。
+ */
+export declare class SessionDeletionSupersededError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}
+/**
+ * 改动会话树根的写(导入三写口 / 撤回 / placed 行的终结 / 留存删除)在根行锁里读到这一行**在删**(会话三态,`src/session-deletion.ts`):一次删除独占着它,一个字节不写。
+ * 带 wire 码 `conflict.session_deleting`(全局兜底映射 409;导入路由的属主门读头 —— 在删读作不在 ⇒ 404 —— 只有门判过之后才落围栏的那一拍走到这里)。
+ * 留存删除读作「本轮跳过这棵树」(在删的行由删除协调器删完,留存不当第二个收尾者);撤回读作留(`claim`:一次删除持有这一行)。
+ */
+export declare class SessionDeletingError extends Error {
+    readonly sessionId: string;
+    readonly code = "conflict.session_deleting";
+    constructor(sessionId: string);
+}
+/** {@link judgeSessionWrite} 的判:放行,或拒(拒的载荷是写口抛的那只 typed 错;SQL 的事务内钩原样交给店,local 直接抛)。 */
+export type SessionWriteJudgement = "proceed" | {
+    readonly refuse: SessionActiveRunError | SessionWriterPresentError | SessionForkInProgressError | SessionDeletionSupersededError | SessionDeletingError;
+};
+/**
+ * 一个写词碰不碰这一行的执行格(写词闭集的**唯一**分派,穷尽 —— 加一个词在这里编译红):`import` ⇒ 碰(判写者 / fork 中间态,放行后调用方落 mirror);
+ * `delete` / `retention-delete` ⇒ 不碰(删除不问执行格:格随这一行一起走)。判官 {@link judgeSessionWrite} 与 SQL 事务内钩的写派(放行后落不落 mirror)都读它。
+ */
+export declare function sessionWriteTouchesCell(op: SessionWrite["op"]): boolean;
+/**
+ * 改动会话树根的写(闭集 = `SessionWrite.op`:`import` 导入三写口落定这一行 / `delete` 提交出口的条件撤回与 placed 行的终结 / `retention-delete` 留存删一棵树的根 /
+ * `erase` 删净在删会话的执行体)落定**之前**的唯一判官,**连序**在内(SQL 的事务内钩与 local 的写锁内同调,两店不各抄一份):
+ * 先读这一行的在删令牌:
+ *  · `erase` —— 令牌等于 `write.token` ⇒ 放行,否则 {@link SessionDeletionSupersededError}(认领在围栏那一刻判过,在删期间认领落不下;不读认领、不读格);
+ *  · 其余三个词 —— 在删 ⇒ {@link SessionDeletingError}(一次删除独占着这一行;任何别的写者 / 删除者都不碰它);
+ * 不在删 ⇒ 其余三个词再读认领 —— 在 ⇒ {@link SessionActiveRunError}(活 run 挂着的根不换内容、不删);认领不在 ⇒ 按词:
+ *  · `import` 再读这一格 —— `writer` ⇒ {@link SessionWriterPresentError}(带车道)、`forking` ⇒ {@link SessionForkInProgressError};`absent` / `mirror` ⇒ 放行(落 mirror 由调用方写);
+ *  · `delete` / `retention-delete` ⇒ 放行(删除不问执行格:格随这一行一起走)。
+ * 读口由调用方给、**按需读**:在删令牌每个词都读;认领在 ⇒ 不读格;删除三词从不读格(SQL:不发格那一句锁定读;local:不探存档)。
+ * 读与判必须在写者独占的同一刻里:SQL = 锁根行之后、同一连接;local = 这只会话的写锁(= 根行锁)内、第一笔写之前(取锁 → 读认领 → 判 → 写)。
+ * 返回判、不抛:拒之后一个字节不写由调用方保证(SQL 回滚,local 判在第一笔写之前)。
+ */
+export declare function judgeSessionWrite(write: SessionWrite, read: {
+    readonly claim: () => Promise<string | null | undefined>;
+    readonly cell: () => Promise<ExecutionPlacementCell>;
+    readonly deleting: () => Promise<string | null>;
+}): Promise<SessionWriteJudgement>;
 /** device 车道首绑(absent → writer(device, D) 或 writer(device, ∅) → writer(device, D))的结果(设备店的事务 / 内存参照实现同调)。 */
 export type DeviceBindOutcome = {
     readonly outcome: "bound";

package/dist/execution-placement.js

@@ -94,6 +94,64 @@ export function settledMirrorOutcome(root, reading, occupant) {
         }
     }
 }
+export class SessionDeletionSupersededError extends Error {
+    sessionId;
+    constructor(sessionId) {
+        super(`session ${sessionId} is no longer held by this deletion attempt (another deletion took it over, or it is already gone) — nothing was deleted by this attempt`);
+        this.sessionId = sessionId;
+        this.name = "SessionDeletionSupersededError";
+    }
+}
+export class SessionDeletingError extends Error {
+    sessionId;
+    code = "conflict.session_deleting";
+    constructor(sessionId) {
+        super(`session ${sessionId} is being deleted — this write was refused inside its transaction; nothing was written`);
+        this.sessionId = sessionId;
+        this.name = "SessionDeletingError";
+    }
+}
+export function sessionWriteTouchesCell(op) {
+    switch (op) {
+        case "import":
+            return true;
+        case "delete":
+        case "retention-delete":
+        case "erase":
+            return false;
+        default: {
+            const unknownOp = op;
+            throw new Error(`sessionWriteTouchesCell: no write ${JSON.stringify(unknownOp)}`);
+        }
+    }
+}
+export async function judgeSessionWrite(write, read) {
+    const root = write.rootSessionId;
+    const deleting = await read.deleting();
+    if (write.op === "erase")
+        return deleting === write.token ? "proceed" : { refuse: new SessionDeletionSupersededError(root) };
+    if (deleting !== null)
+        return { refuse: new SessionDeletingError(root) };
+    const claim = await read.claim();
+    if (claim !== null && claim !== undefined)
+        return { refuse: new SessionActiveRunError(root, claim) };
+    if (!sessionWriteTouchesCell(write.op))
+        return "proceed";
+    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(`judgeSessionWrite: 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/field-conflict.d.ts

@@ -1,7 +1,7 @@
-/** 冲突的类(闭集)。同一个约束的几个拒点同一个词;新增一类见文件头。 */
-export declare const FIELD_CONFLICT_KINDS: readonly ["cascade_verify", "image_profile", "resume_anchor", "system_prompt_fold", "file_history_restore", "skills_disabled", "existing_session", "fork_target", "scratchpad_root", "ask_answer", "policy_person_ask", "plan_edit", "plan_mode_after", "bound_call_door", "remember_decision", "approval_feedback"];
+/** 冲突的类(闭集;拒体根上的 `reason`)。同一个约束的几个拒点同一个词;新增一类见文件头。 */
+export declare const FIELD_CONFLICT_REASONS: readonly ["cascade_verify", "image_profile", "resume_anchor", "system_prompt_fold", "file_history_restore", "skills_disabled", "existing_session", "fork_target", "scratchpad_root", "ask_answer", "policy_person_ask", "plan_edit", "plan_mode_after", "bound_call_door", "remember_decision", "approval_feedback"];
 /** 冲突的类(闭集词)。 */
-export type FieldConflictKind = (typeof FIELD_CONFLICT_KINDS)[number];
+export type FieldConflictReason = (typeof FIELD_CONFLICT_REASONS)[number];
 /**
  * 每一类允许点名的请求体坐标(铸点的 `fields` 按所属类的行检查)。键序无意义;值是该类可出现的坐标的联合。
  * 动态下标的坐标用模板字面量型(`agents[1].skills`)。
@@ -29,17 +29,13 @@ export interface FieldConflictMeasure {
     readonly count: number;
     readonly cap: number;
 }
-/** 拒体上的 `detail`。 */
-export type FieldConflictDetail<K extends FieldConflictKind = FieldConflictKind> = {
-    readonly kind: K;
+/** 一处冲突的机读位(原样摊在拒体根上:`sendError` 的 extra / `HttpError.extra` / `refusalBody` 的 facts;型别名而不是接口 —— 要能直接当 `Record<string, unknown>` 用)。 */
+export type FieldConflictFacts<K extends FieldConflictReason = FieldConflictReason> = {
+    readonly reason: K;
     readonly fields: readonly FieldConflictCoordinates[K][];
 } & Partial<FieldConflictMeasure>;
-/** 一处冲突的机读位(原样进拒体:`sendError` 的 extra / `HttpError.extra` / 手拼体的展开;型别名而不是接口 —— 要能直接当 `Record<string, unknown>` 用)。 */
-export type FieldConflictFacts<K extends FieldConflictKind = FieldConflictKind> = {
-    readonly detail: FieldConflictDetail<K>;
-};
 /**
  * 铸一处冲突的机读位。`fields` 至少一个坐标、主语在前;`measure` 只有折叠上限那一类给。
  */
-export declare function fieldConflictFacts<K extends FieldConflictKind>(kind: K, fields: readonly [FieldConflictCoordinates[K], ...FieldConflictCoordinates[K][]], measure?: FieldConflictMeasure): FieldConflictFacts<K>;
+export declare function fieldConflictFacts<K extends FieldConflictReason>(reason: K, fields: readonly [FieldConflictCoordinates[K], ...FieldConflictCoordinates[K][]], measure?: FieldConflictMeasure): FieldConflictFacts<K>;
 //# sourceMappingURL=field-conflict.d.ts.map

package/dist/field-conflict.js

@@ -1,4 +1,4 @@
-export const FIELD_CONFLICT_KINDS = [
+export const FIELD_CONFLICT_REASONS = [
     "cascade_verify",
     "image_profile",
     "resume_anchor",
@@ -16,7 +16,7 @@ export const FIELD_CONFLICT_KINDS = [
     "remember_decision",
     "approval_feedback",
 ];
-export function fieldConflictFacts(kind, fields, measure) {
-    return { detail: { kind, fields: [...fields], ...(measure === undefined ? {} : { count: measure.count, cap: measure.cap }) } };
+export function fieldConflictFacts(reason, fields, measure) {
+    return { reason, fields: [...fields], ...(measure === undefined ? {} : { count: measure.count, cap: measure.cap }) };
 }
 //# sourceMappingURL=field-conflict.js.map

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

@@ -12,7 +12,7 @@
  *
  * ## 两件事,两个单点
  *  · 「这台部署有没有文件历史店」只在 {@link assembleFileHistory} 判一次(后端在即在,**与旋钮无关**),产出两张脸:
- *    **店** `store` 喂 core 的 `RunnerDeps.fileHistoryStore`(还原族)、rewind 族能力位(`rewindFiles` / `restoreFiles` /
+ *    **店** `store` 喂 core 的 `RunnerDeps.fileHistoryStore`(还原族)、rewind 族能力位(`restoreFiles` /
  *    `rewindFilesTo` / `sessionSync`)与 2c sync 路由族;**擦除脸** `erasure` = 店的**只有删除类动词**的收窄视图,喂 E21 在线删除
  *    (`boot/session-faces.ts`)与孤儿 blob GC(`boot/reapers.ts`)。旋钮从不管擦除:关掉捕获的部署照样要能删掉已捕获的文件字节。
  *  · 「捕不捕」只在 {@link fileHistoryCaptureOf} 判一次(纯函数,输入 = 店在不在 + 旋钮)。两个消费点喂它同一组输入:
@@ -58,8 +58,8 @@ export declare function assembleFileHistory(backend: StoreBackend | undefined):
  * 「捕不捕」的**唯一**判定(纯函数):能力词。`store` = 装配出来的店(在不在),`knob` = 部署旋钮 `FILE_HISTORY_CAPTURE`
  * (`config.fileHistoryCapture`)。从**装配结果**派生,不照旋钮字面回声:后端本来就没有这只店的部署同样是 `off`。
  *
- * 与 `rewindFiles` 分叉([ref] 当时写下的分叉条件,自本版成真):本词答「这台部署捕不捕、能不能按 run 关掉」,
- * `rewindFiles` 答「这台部署能不能还原」—— 旋钮关的部署本词 `off` 而 `rewindFiles` 仍为真。
+ * 与 `restoreFiles` 分叉([ref] 当时写下的分叉条件,自 [ref] 成真):本词答「这台部署捕不捕、能不能按 run 关掉」,
+ * `restoreFiles` 答「这台部署能不能还原」—— 旋钮关的部署本词 `off` 而 `restoreFiles` 仍为真。
  */
 export declare function fileHistoryCaptureOf(store: object | undefined, knob: boolean): FileHistoryCapture;
 /**

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/file-history-disclosure.js

@@ -49,6 +49,7 @@ function faultOfClass(cls) {
         case "deployment":
             return { permanence: "terminal" };
         case "corrupt":
+        case "defect":
         case "unclassified":
             return {};
         default: {

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

@@ -69,27 +69,34 @@ 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`。
+ * 在飞数的**分项**(`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()`);
- *  · `sessionResident` —— 会话驻留的后台 shell / monitor(活过起它的那一条腿;`session-resident-background.ts` 的读法:不含 retain 行)。
+ *  · `backgroundAgents` —— 活过起它的那一条腿、仍在跑的后台子代理(core `backgroundScope:"session"`;`session-resident-background.ts` 的读法:停驻的不计)。
+ *    它进阻断集:它是一条在干活的模型腿,干完自己收尾(在审批 / 问答卡上等人时行仍是 `running`、照计;窗满转成耐久停驻后不再计);不等 = 受控退把还在干活的子代理中断。
+ *    上界 = 停滞收割窗 `BG_AGENT_STALL_MS`:读口每读一次先让引擎收掉静默满窗的子代理(挂死的,或收尾时 core 等的那次账本写挂住的)再数 —— 判停窗不再被一只僵尸无界地撑着;
+ *    SIGTERM 排空另以期限为界;
+ *  · `sessionResident` —— 会话驻留的后台 shell / monitor(同一读法:不含 retain 行)。
  *    它只进总数、不进阻断集:一只不退出的驻留 shell(`while true`)若阻断,崩溃孤儿引擎就永生、排空每次等满窗;窗到 / 排空完成即由退出边界的后台收割收掉
  *    (retain 行按 retain 既有语义,活过受控退)。
- * 三项在同一次读里求出,`/health` 的 `inflight` 与 `inflightBreakdown` 因此永远自洽。只有这两个函数各写一次这两个和,没有第三张计法表。
- * 阻断集只需要前两项:判停路径(排空 1 s 拍 / 租约拍 / SIGHUP 拍)**不求值** `sessionResident`(那是对进程级注册表的一次逐会话走查,只在 `/health` 与崩溃遗言里付)。
+ * 不进任何一项的(计法表成文的行):停驻待赎回的 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: Pick<InflightBreakdown, "http" | "leader">): number;
-/** 总数 = 引擎此刻托管的全部活 = `/health.inflight`(= 阻断集 + 会话驻留项)。 */
+export declare function blockingInflightOf(b: InflightBreakdown): number;
+/** 总数 = 引擎此刻托管的全部活 = `/health.inflight`(= 阻断集 + 会话驻留的 shell / monitor 项)。 */
 export declare function inflightTotal(b: InflightBreakdown): number;
 /**
  * 引擎与 HTTP 面共享的排空盒子(装配层建一只,`createHttpServer` 与收尾链各自往上装读口 / 入口)。
@@ -114,7 +121,7 @@ export interface DrainState {
     inflight?: () => number;
     /** 分项读口(`createHttpServer` 装,与 `inflight` / `blockingInflight` 同一次装、同一份求值)。`/health` 读它一次,同时出 `inflight` 与 `inflightBreakdown` 两键。 */
     inflightBreakdown?: () => InflightBreakdown;
-    /** **阻断集**读口(`createHttpServer` 装):还有没有必须等完的活 = `blockingInflightOf(inflightBreakdown())` = `http + leader`。排空等的(`boot/shutdown.ts` 的排空驱动表)、
+    /** **阻断集**读口(`createHttpServer` 装):还有没有必须等完的活 = `blockingInflightOf(inflightBreakdown())` = `http + leader + backgroundAgents`。排空等的(`boot/shutdown.ts` 的排空驱动表)、
      *  孤儿窗 / 附着租约自退(`boot/engine-lease.ts`)、SIGHUP 空闲窗(`sighup-idle.ts`)的「可以停了吗」都读它;会话驻留的后台 shell / monitor 不在内。 */
     blockingInflight?: () => number;
     lastActivityAt?: () => number;