@sema-agent/server 7.145.0 → 7.147.0

package/dist/plugins/local-data-dir-modes-m39.js

@@ -0,0 +1,182 @@
+import { closeSync, constants as FS, fchmodSync, fstatSync, lstatSync, openSync, readdirSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { physicalPathOf } from "@sema-agent/core";
+import { IS_WIN32 } from "./host-platform.js";
+import { fileRunStoreDirsFor } from "./file-run-store.js";
+import { localCheckpointStoreDirsFor } from "./local-checkpoint-store.js";
+import { attachmentStoreDirFor } from "./local-task-attachment-store.js";
+import { scratchpadRootFor } from "../env-facts.js";
+import { pluginCacheRootFor } from "../capabilities/center-plugins.js";
+import { memorySyncCursorDirFor } from "../memory-sync-client.js";
+const DIR_MODE = 0o700;
+const GROUP_OTHER_BITS = 0o077;
+const TIGHTENED_EXAMPLES = 5;
+const REFUSED_LISTED = 10;
+export const SYMLINK_IN_PATH = "SYMLINK_IN_PATH";
+export function buildDataDirLayout(a) {
+    const rel = relative(resolve(a.configuredRoot), resolve(a.memoryEngineRoot));
+    const underConfigured = rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+    return { dataRoot: a.physicalRoot, memoryEngineRoot: underConfigured ? join(a.physicalRoot, rel) : a.memoryEngineRoot };
+}
+function rosterFor(layout) {
+    const run = fileRunStoreDirsFor(layout.dataRoot);
+    const checkpoint = localCheckpointStoreDirsFor(layout.dataRoot);
+    return [
+        { abs: run.runs, children: 1 },
+        { abs: run.tmp, children: 0 },
+        { abs: run.spaceCommits, children: 0 },
+        { abs: checkpoint.ctx, children: 0 },
+        { abs: checkpoint.tmp, children: 0 },
+        { abs: attachmentStoreDirFor(layout.dataRoot), children: 0 },
+        { abs: scratchpadRootFor(layout.dataRoot), children: 1 },
+        { abs: pluginCacheRootFor(layout.dataRoot), children: 2 },
+        { abs: memorySyncCursorDirFor(layout.memoryEngineRoot), children: 0 },
+    ];
+}
+function segmentsUnder(root, abs) {
+    const rel = relative(resolve(root), resolve(abs));
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return undefined;
+    return rel.split(sep);
+}
+const codeOf = (e) => (typeof e === "object" && e !== null && "code" in e && typeof e.code === "string" ? e.code : "UNKNOWN");
+const emit = (sink, msg, meta) => {
+    try {
+        sink(msg, meta);
+    }
+    catch {
+        console.warn(msg, meta);
+    }
+};
+const sameObject = (a, b) => a.dev === b.dev && a.ino === b.ino;
+function inRootBreak(root, segs, fd) {
+    try {
+        const held = fstatSync(fd, { bigint: true });
+        const physical = physicalPathOf(join(root, ...segs));
+        if (segmentsUnder(root, physical) === undefined)
+            return SYMLINK_IN_PATH;
+        if (!sameObject(lstatSync(physical, { bigint: true }), held))
+            return "ESTALE";
+        for (let i = 0; i <= segs.length; i += 1) {
+            const st = lstatSync(join(root, ...segs.slice(0, i)), { bigint: true });
+            if (st.isSymbolicLink())
+                return SYMLINK_IN_PATH;
+            if (!st.isDirectory())
+                return "ESTALE";
+        }
+        return undefined;
+    }
+    catch (e) {
+        return codeOf(e);
+    }
+}
+export function tightenLocalDataDirModes(layout, sinks, seats = {}) {
+    if (seats.win32 ?? IS_WIN32)
+        return { tightened: [], refused: [] };
+    const fchmod = seats.fchmod ?? ((fd, mode) => fchmodSync(fd, mode));
+    const root = layout.dataRoot;
+    const tightened = [];
+    const refused = [];
+    const refuse = (rel, code) => {
+        if (code !== "ENOENT")
+            refused.push({ path: rel, code });
+    };
+    const tighten = (segs, rel) => {
+        let fd;
+        try {
+            fd = openSync(join(root, ...segs), FS.O_RDONLY | FS.O_DIRECTORY | FS.O_NOFOLLOW);
+        }
+        catch (e) {
+            refuse(rel, codeOf(e));
+            return;
+        }
+        try {
+            const broken = inRootBreak(root, segs, fd);
+            if (broken !== undefined) {
+                refuse(rel, broken);
+                return;
+            }
+            fchmod(fd, DIR_MODE, rel);
+            tightened.push(rel);
+        }
+        catch (e) {
+            refuse(rel, codeOf(e));
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    const step = (parent, name, more, depth) => {
+        const segs = [...parent, name];
+        const rel = join(...segs);
+        let mode;
+        try {
+            const st = lstatSync(join(root, ...segs));
+            if (st.isSymbolicLink()) {
+                refused.push({ path: rel, code: SYMLINK_IN_PATH });
+                return;
+            }
+            if (!st.isDirectory())
+                return;
+            mode = st.mode;
+        }
+        catch (e) {
+            refuse(rel, codeOf(e));
+            return;
+        }
+        const [next, ...rest] = more;
+        if (next !== undefined) {
+            step(segs, next, rest, depth);
+            return;
+        }
+        if ((mode & GROUP_OTHER_BITS) !== 0)
+            tighten(segs, rel);
+        if (depth === 0)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(join(root, ...segs), { withFileTypes: true });
+        }
+        catch (e) {
+            refuse(rel, codeOf(e));
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory() || entry.isSymbolicLink())
+                step(segs, entry.name, [], depth - 1);
+        }
+    };
+    let rootIntact = false;
+    try {
+        if (lstatSync(root).isSymbolicLink())
+            refused.push({ path: ".", code: SYMLINK_IN_PATH });
+        else
+            rootIntact = true;
+    }
+    catch (e) {
+        refuse(".", codeOf(e));
+    }
+    for (const { abs, children } of rootIntact ? rosterFor(layout) : []) {
+        const [first, ...rest] = segmentsUnder(root, abs) ?? [];
+        if (first !== undefined)
+            step([], first, rest, children);
+    }
+    if (refused.length > 0) {
+        emit(sinks.refused, "local_data_dir_mode_refused", {
+            count: refused.length,
+            mode: "0700",
+            entries: refused.slice(0, REFUSED_LISTED),
+            remedy: "these directories (relative to the data root) could not be tightened or read, or are reached through a symbolic link (SYMLINK_IN_PATH: links are never followed, the data root itself included) — as the owner of the real directory run `chmod 700` on it (or chown it to the server's user) and restart; the server keeps serving meanwhile",
+        });
+    }
+    if (tightened.length > 0) {
+        emit(sinks.tightened, "local_data_dir_modes_tightened", {
+            count: tightened.length,
+            mode: "0700",
+            examples: tightened.slice(0, TIGHTENED_EXAMPLES),
+            note: "store directories created by earlier versions with the default mode were tightened to 0700 once; later boots find them tight",
+        });
+    }
+    return { tightened, refused };
+}
+//# sourceMappingURL=local-data-dir-modes-m39.js.map

package/dist/plugins/local-engine-high-water.d.ts

@@ -0,0 +1,11 @@
+/** marker 的文件名(数据根顶层;公开契约)。 */
+export declare const ENGINE_HIGH_WATER_FILE = "engine-high-water.json";
+/**
+ * **判与抬**(唯一的座;唯一调用点 `openLocalBackend`,数据根锁在手、本仓任何一只店建起之前):
+ *  ① 本构建版本 `engine` 按发布线读不出({@link buildReleaseTriple})⇒ 抛 {@link StoreBootRefusalError}(marker 不读、不写);
+ *  ② 读 `<root>/engine-high-water.json`:读不出 / 高水位高于本构建 ⇒ 抛 {@link LocalDataRootSchemaMismatchError}(`boot` 形;文件原地不动,不抬);
+ *  ③ 缺席或低于本构建 ⇒ 原子写 `{"highWater": <本构建的纯三段>}`(`required`);相等 ⇒ 不写,只过持久化屏障(读到的可能是上一次没证完的那份)。写不进 / 证不了 ⇒ 抛(点名路径与原因)。
+ * 同步:它在后端打开的同步段里跑(建店之前),拒在这里就不会有一只店被建起。
+ */
+export declare function holdEngineHighWater(root: string, engine: string): void;
+//# sourceMappingURL=local-engine-high-water.d.ts.map

package/dist/plugins/local-engine-high-water.js

@@ -0,0 +1,59 @@
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { atomicWriteFileSync, proveDurableSync } from "./owner-only-file-mode.js";
+import { createZodColumnReader, decodeJsonColumn } from "./sql-json-column.js";
+import { LocalDataRootSchemaMismatchError, dataRootMismatchOf, readDataRootFileTextSync } from "./local-session-store.js";
+import { buildReleaseTriple, compareReleaseTriples, releaseText, releaseTriple } from "./release-version.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
+export const ENGINE_HIGH_WATER_FILE = "engine-high-water.json";
+const ENGINE_HIGH_WATER_LABEL = `${ENGINE_HIGH_WATER_FILE} (the local engine high-water marker)`;
+const ENGINE_HIGH_WATER_SHAPE = z
+    .object({ highWater: z.string() })
+    .strict()
+    .transform((v, ctx) => {
+    const triple = releaseTriple(v.highWater);
+    if (triple === undefined) {
+        ctx.addIssue({ code: "custom", message: "highWater is not a plain x.y.z release version" });
+        return z.NEVER;
+    }
+    return { highWater: v.highWater, triple };
+});
+const readEngineHighWater = createZodColumnReader(ENGINE_HIGH_WATER_SHAPE);
+export function holdEngineHighWater(root, engine) {
+    const own = buildReleaseTriple(engine);
+    if (own === undefined) {
+        throw new StoreBootRefusalError(`DB_BACKEND=local: this build's own version (package.json "version": ${JSON.stringify(engine.slice(0, 64))}) is not a release version (x.y.z, optionally with a prerelease or build suffix) — refusing to open the data root ${root}: ` +
+            "the engine high-water fence needs this build's release line to show it is not older than the engines that opened this data root, and to record its own. " +
+            "Run a build whose package.json carries a release version.");
+    }
+    const path = resolve(join(root, ENGINE_HIGH_WATER_FILE));
+    const raw = readDataRootFileTextSync(path);
+    let equal = false;
+    if (raw.state === "unreadable")
+        throw new LocalDataRootSchemaMismatchError([dataRootMismatchOf(path, ENGINE_HIGH_WATER_LABEL, raw.fault)], "boot");
+    if (raw.state === "text") {
+        let marker;
+        try {
+            marker = decodeJsonColumn(raw.text, readEngineHighWater, ENGINE_HIGH_WATER_LABEL);
+        }
+        catch (e) {
+            throw new LocalDataRootSchemaMismatchError([dataRootMismatchOf(path, ENGINE_HIGH_WATER_LABEL, e)], "boot");
+        }
+        const order = compareReleaseTriples(marker.triple, own);
+        if (order > 0) {
+            throw new LocalDataRootSchemaMismatchError([{ path, label: ENGINE_HIGH_WATER_LABEL, problem: "newer-engine", unknownFields: [], engineHighWater: { highWater: marker.highWater, engine } }], "boot");
+        }
+        equal = order === 0;
+    }
+    try {
+        if (equal)
+            proveDurableSync(path);
+        else
+            atomicWriteFileSync(path, `${JSON.stringify({ highWater: releaseText(own) })}\n`, { durability: "required" });
+    }
+    catch (e) {
+        throw new Error(`DB_BACKEND=local cannot record the engine high-water ${path} durably: ${e instanceof Error ? e.message : String(e)} — refusing to open the data root: ` +
+            "writing to it without a durable high-water would let an older engine open it later unrefused. Repair write access to the data root and restart.", { cause: e });
+    }
+}
+//# sourceMappingURL=local-engine-high-water.js.map

package/dist/plugins/local-session-store.d.ts

@@ -2,13 +2,13 @@ import { FileSessionRepo, type AcquiredSession, type PlacedSessionRow, type Sess
 import { type PlacementAcquireOpts } from "./session-placement.js";
 import { z } from "zod";
 import { StoreBootRefusalError, type SessionRunClaimSource, type SessionRunRollupSource, type SessionSummary } from "./store-contracts.js";
-import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
+import { type ClientSessionRowWrite, type ReplaySessionRowWrite, type ReplaySessionRowWriteOutcome, type SessionRowAnswer, type SessionRowPatch, type SessionRowWriteOutcome } from "../session-row.js";
+import { type SqlJsonColumnProblem } from "./sql-json-column.js";
 import { type LocalArchiveKeptStamped, type LocalArchiveUnreadable } from "./one-time-migrations.js";
 import { type Logger } from "../observability/logger.js";
 import { type SessionFace } from "../session-incarnation.js";
-import { type ExecutionLane } from "../execution-lane-caps.js";
 import { type ExecutionPlacementSeat, type LocalPlacementBackfillSeat } from "../execution-placement.js";
-import { type ForkTarget, type ForkToOutcome } from "./session-fork.js";
+import { type ForkPlacement, type ForkTarget, type ForkToOutcome } from "./session-fork.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import type { SessionWorkspace } from "../session-workspace.js";
 import { type StagedCommitOptions, type StagingHandle, type SyncRelation } from "../session-sync-kernel.js";
@@ -21,7 +21,7 @@ export declare const SESSION_META_CELL_OBJECT: z.ZodObject<{
     owner: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     execution: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         role: z.ZodLiteral<"writer">;
-        lane: z.ZodCustom<ExecutionLane, ExecutionLane>;
+        lane: z.ZodCustom<"host" | "e2b" | "k8s" | "ssh" | "adb" | "local-docker" | "device" | "none", "host" | "e2b" | "k8s" | "ssh" | "adb" | "local-docker" | "device" | "none">;
     }, z.core.$strict>, z.ZodObject<{
         role: z.ZodLiteral<"mirror">;
     }, z.core.$strict>], "role">>;
@@ -29,33 +29,84 @@ export declare const SESSION_META_CELL_OBJECT: z.ZodObject<{
     createdAt: z.ZodOptional<z.ZodString>;
     forkedFrom: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-/** 严格边档清册里一只边档的对账读数(拒句的逐文件一段;{@link LocalDataRootSchemaMismatchError.findings})。 */
-export interface LocalSidecarMismatch {
+/**
+ * 数据根对账里一只文件的读数(拒句的逐文件一段;{@link LocalDataRootSchemaMismatchError.findings}):严格边档清册里的一只边档,或引擎版本高水位 marker
+ * (`local-engine-high-water.ts`)。**判别联合**,判别位 `problem`:`"newer-engine"` ⇒ {@link LocalDataRootNewerEngine}(必带 `engineHighWater`);
+ * 别的每一个词 ⇒ {@link LocalDataRootUnreadable}(没有 `engineHighWater`)—— 载荷跟着判别位走,由类型保证,不靠运行时约定。
+ */
+export type LocalDataRootMismatch = LocalDataRootUnreadable | LocalDataRootNewerEngine;
+/**
+ * 读不出的种别:形 —— `not-json` / `malformed` / `not-text`(形读者的判词),或 I/O 的 errno(`EACCES` / `EISDIR` / 悬空符号链接的 `ENOENT` …,恒以 `E` 起头);
+ * 说不出 errno ⇒ `unreadable`。`newer-engine` 不在其中(那是另一支)。
+ */
+export type LocalDataRootReadProblem = SqlJsonColumnProblem | `E${string}` | "unreadable";
+/** 一只文件本构建读不出(形或 I/O);形读者不认得的键非空 ⇒ 这只文件是更新的引擎写下的(数据根比本构建新)。 */
+export interface LocalDataRootUnreadable {
     /** 文件的绝对路径。 */
     readonly path: string;
-    /** 角色(`<文件名> (the local <角色> sidecar)`)。 */
+    /** 角色(`<文件名> (the local <角色> sidecar)` / `<文件名> (the local engine high-water marker)`)。 */
     readonly label: string;
-    /** 读不出的种别:`not-json` / `malformed`(形),或 I/O 的 errno(`EACCES` …;没有 errno ⇒ `unreadable`)。 */
-    readonly problem: string;
-    /** 格里本构建不认得的键(非空 ⇒ 这只边档是更新的引擎写下的:数据根比本构建新)。 */
+    readonly problem: LocalDataRootReadProblem;
+    /** 本构建不认得的键(非空 ⇒ 这只文件是更新的引擎写下的:数据根比本构建新)。 */
     readonly unknownFields: readonly string[];
 }
+/** 引擎版本高水位 marker 读得出,而它记的高水位高于本构建:数据根被更新的引擎服务过。 */
+export interface LocalDataRootNewerEngine {
+    /** marker 的绝对路径。 */
+    readonly path: string;
+    /** 角色(`engine-high-water.json (the local engine high-water marker)`)。 */
+    readonly label: string;
+    readonly problem: "newer-engine";
+    readonly unknownFields: readonly [];
+    /** marker 记的高水位(纯 `x.y.z`)与本构建的版本串(原样:发布线读得出的 `x.y.z`,可带预发布 / 构建后缀;读不出的构建在判之前就拒了)。 */
+    readonly engineHighWater: {
+        readonly highWater: string;
+        readonly engine: string;
+    };
+}
 /**
  * **local 数据根的「本构建读不出」拒**(起服对账一族的 local 腿;机读码与 SQL 列册对账同一个 `config.schema_mismatch`,拒句同形)。
  * 一只严格边档用它那一只严格读者读不出 ⇒ 这一只拒,文件原地不动、一个字节不改。两处触发、一只类:
- *  · `boot` —— 起服对账({@link LocalSessionStore.assertStrictSidecarsReadable},唯一调用点 `LocalBackend.ensureSchema()`)把清册里每一只读不出的合成一只:拒启;
+ *  · `boot` —— 两处拒启:local 后端**打开数据根的那一刻**(锁在手之后、本仓任何一只店建起之前;`store-backend.ts` 的 `openLocalBackend`)引擎版本高水位 marker 读不出 / 高于本构建
+ *    (`local-engine-high-water.ts`,读数种别 `newer-engine` 或读不出的那几种;同一判词「数据根比代码新」的第二种证据 —— 这一拒由公开序列的 `ensureSchema()` 交出);
+ *    起服对账(`LocalBackend.ensureSchema()`)里严格边档清册读不出的每一只合成一只({@link LocalSessionStore.assertStrictSidecarsReadable});
  *  · `serving` —— 起服之后这只边档第一次被碰时才读不出(嵌入方跳过了 `ensureSchema()`;或起服后别的写者把它写成本构建读不出的形,在替换之前那一读里看见):
  *    读不出的是**形**(`not-json` / `malformed`,确定的判词)⇒ 这只边档在本进程里从此每一读每一写都交这一只(重启才重判);碰它的请求失败(把它交给 HTTP 全局兜底的路由:
  *    500 `internal.error` + 一行 error 级 `request_error` 带本码;自己接住故障的路由按各自的 500 臂答)。I/O 故障(非确定)不粘。
  * 属 {@link StoreBootRefusalError} 族:起服降级臂不吞它(缺省推导的 local 不会被吃成内存后端)。拒句零原文:只点名文件、种别与不认得的键名,不带任何值。
  */
 export declare class LocalDataRootSchemaMismatchError extends StoreBootRefusalError {
-    readonly findings: readonly LocalSidecarMismatch[];
+    readonly findings: readonly LocalDataRootMismatch[];
     readonly when: "boot" | "serving";
     /** 机读码(与 SQL 列册对账 / 退役 schema 的拒启同一个)。 */
     readonly code = "config.schema_mismatch";
-    constructor(findings: readonly LocalSidecarMismatch[], when: "boot" | "serving");
+    constructor(findings: readonly LocalDataRootMismatch[], when: "boot" | "serving");
 }
+/** 数据根对账文件的一读的读数(两个出口同形)。 */
+export type DataRootFileText = {
+    readonly state: "absent";
+} | {
+    readonly state: "unreadable";
+    readonly fault: unknown;
+} | {
+    readonly state: "text";
+    readonly text: string;
+};
+/**
+ * 数据根对账文件的**字节一读**(唯一的判;异步 {@link readDataRootFileText} 与同步 {@link readDataRootFileTextSync} 两个出口只差 I/O 的同步性,`ENOENT` 之后的判都经 {@link judgedAfterEnoent}):
+ * 严格边档的三个触点({@link SidecarMap.readDisk})、一次性迁移 M40 的会话腿走异步出口,引擎版本高水位 marker(`local-engine-high-water.ts`,在后端打开的同步段里判)走同步出口,
+ * 所以「缺文件 / 读不出(I/O)/ 读到字节」在各处是同一个判决。形判据不在这里:每个调用点用自己的具名形读者解码([ref] 门③:读者不经参数传递,哪一套键判了这只文件在调用点上看得见)。
+ * **缺席 = 目录里没有这一项**(不是读不出):`ENOENT` 而这一项还在(悬空符号链接 —— 链接在、目标不在)⇒ 读不出,不当缺席(与配置根的悬空链接同一条律);
+ * 读完 `ENOENT` 到 `lstat` 之间这一项被删 ⇒ 缺席;`lstat` 自己判不了(非 `ENOENT`)⇒ 读不出。
+ */
+export declare function readDataRootFileText(path: string): Promise<DataRootFileText>;
+/** {@link readDataRootFileText} 的同步出口(同一判)。 */
+export declare function readDataRootFileTextSync(path: string): DataRootFileText;
+/**
+ * 读不出的故障 → 一段读数(唯一一处;严格边档的拒与引擎版本高水位 marker 同经它):形的故障({@link SqlJsonColumnError})带它的种别与形读者不认得的键,
+ * I/O 故障带 errno(没有 ⇒ `unreadable`)。
+ */
+export declare function dataRootMismatchOf(path: string, label: string, fault: unknown): LocalDataRootUnreadable;
 /**
  * local 车道会话存档的**唯一 repo 出口**:本仓里每一只读 `<root>/sessions/*.jsonl` 的 `FileSessionRepo` 都从这里取(`LocalSessionStore` 的底座;会话视图窗不再自开 repo,
  * 它的元数据与日志都由店交出 —— `local-session-window.ts`),所以坏记录的披露座只有这一份接线。座 = F 类 `server.session-repo.corrupt-record-skipped`(会话存档里读不出的记录丢的是可用性:
@@ -158,27 +209,24 @@ export declare class LocalSessionStore implements SessionStore {
     /** Set by touch/delete when the map mutated; cleared by a write that captured the change. A write that ran while this
      *  is set re-runs (a touch that landed during an active write isn't dropped). Drives the chain's re-run guard (bug B). */
     private dirty;
-    /** Monotonic per-write counter — feeds a UNIQUE tmp filename per write so overlapping writes can't share one tmp path
-     *  and tear each other's bytes (bug B). */
-    private writeSeq;
     /** Last time a sidecar-write error was warned (bug D): throttle the best-effort warn so a persistently-failing disk
      *  doesn't spam the log on every debounced flush. 0 ⇒ never warned. */
     private lastWarnAt;
     /** Absolute path to the lastActivity JSON sidecar, or undefined when not persisting (in-memory-only deployment). */
     private readonly sidecarPath?;
-    /** Title map (`session-titles.json`) — the local twin of the SQL `session_meta.title` column: one cell, two writers
+    /** Title map (`session-titles.json`) — the local twin of the SQL `session_ext.title` column: one cell, two writers
      *  (the user's {@link writeSessionRowCells}; the auto-titler's {@link setTitleIfNull}, fills an absent cell
      *  only — writer order: `src/session-row.ts`; both under the session write lock). Separate file from the lastActivity sidecar ON PURPOSE (that format is a
      *  #10 clobber area); ultra-low-rate. Cross-instance sharing: see {@link SidecarMap}. */
     private readonly titles;
-    /** Pin map (`session-pinned.json`, {@link readPinnedSidecar}) — the local twin of `session_meta.pinned`. Its own file for
+    /** Pin map (`session-pinned.json`, {@link readPinnedSidecar}) — the local twin of `session_ext.pinned`. Its own file for
      *  the same reason titles have theirs (one small map per concern, no format coupling); absent key = not pinned. */
     private readonly pinned;
     /** [ref] — instruction-source baselines (`session-instruction-sources.json`): the chain member the session's previous
-     *  run selected, encoded like the SQL twins' `session_meta.instruction_source` column ('' = none; missing key = never
+     *  run selected, encoded like the SQL twins' `session_ext.instruction_source` column ('' = none; missing key = never
      *  recorded). Its own file for the same reason titles have theirs: one small map per concern, no format coupling. */
     private readonly instructionSources;
-    /** 会话行的位置与项目那一格(`session-workspaces.json`)—— SQL 孪生 `session_meta.workspace` 的 local 对位:`{ [sessionId]: 那一格的文本 }`,
+    /** 会话行的位置与项目那一格(`session-workspaces.json`)—— SQL 孪生 `session_ext.workspace` 的 local 对位:`{ [sessionId]: 那一格的文本 }`,
      *  文本与 SQL 列同一只编解码(`session-workspace-cell.ts`,一格读不出 ⇒ 读作没有记录并计一次)。缺键 = 没有记录。一事一档,理由同 titles。 */
     private readonly workspaces;
     /**
@@ -212,7 +260,7 @@ export declare class LocalSessionStore implements SessionStore {
      * 执行席(规则在 `src/execution-placement.ts`):读 = 那一格的 `execution` 位(fork 创建的格而存档不在 ⇒ `forking`);place / markMirror 在这只会话的写锁里判住客
      * (化身 + 头读投影的属主 `owner ?? null`)再只改 `execution` 那一位 —— 住客换了(删后重建、M10 窗内认领)⇒ `gone`,不写。
      * 认领(run 店的单活槽,{@link SessionRunClaimSource}):`markMirror` 在同一把写锁里读它、只拦「absent → mirror」这一笔(判序与 SQL 孪生同,见 {@link markMirrorExecution});`place` 是认领持有者自己的初始放置写,不读认领。
-     * local 的导入三写口不读认领 —— 它们的认领判在路由(第一阶段写前判 + 提交前复判),没有 SQL 孪生那样的写事务内读。
+     * 导入三写口(整段 `importEntries` / `replaceEntries` / 暂存提交)同在写锁里读它、交 SQL 事务内钩 `import` 臂的那一只判官 {@link judgeImportWrite}(见 {@link admitImportHeld});路由的认领判(第一阶段写前判 + 提交前复判)是更早的一道,不是唯一一道。
      */
     readonly executionPlacement: ExecutionPlacementSeat;
     /**
@@ -237,6 +285,15 @@ export declare class LocalSessionStore implements SessionStore {
     constructor(repo: HeadReadingSessionRepo & Partial<PlacementRecordingRepo>, runs: SessionRunRollupSource & SessionRunClaimSource, dataDir?: string, opts?: {
         log?: Pick<Logger, "info" | "warn">;
     } & LocalSessionStoreDeclaration);
+    /**
+     * 🔴 一次性迁移 **M40 的 local 会话腿**(窗口见 `plugins/one-time-migrations.ts` 登记表 M40 行;唯一调用点 `LocalBackend.ensureSchema()` 的**第一步**,
+     * 排在 {@link assertStrictSidecarsReadable} 之前 —— 严格读的执行位只认本版车道词,旧词先到那里就整只拒启):会话元数据边档里 `execution` 位记成退役词的
+     * writer 格改记新名,整只原子重写一次。只改那一个词,别的字节按 JSON 原样写回。字节经边档的唯一一读({@link readDataRootFileText})。
+     * 缺文件 / 读不出(I/O 故障如 EACCES / EISDIR、坏 JSON、不是对象)⇒ 不抛、不改,交给其后的严格对账判 —— 它读同一只文件、以 `config.schema_mismatch`
+     * 拒(那是这只拒码在本店的唯一铸点);这里抛了,拒码与具名拒都会丢。读得出而写不进 ⇒ {@link ExecutionLaneRenameWriteRefusedError}(拒启,降级臂不吞)。
+     * 内存部署 / 没有旧词 ⇒ 零写。返回改了的格数。词的属主 = `execution-lane-rename-m40.ts`。
+     */
+    renameRetiredExecutionLaneWordM40(): Promise<number>;
     /**
      * [ref] —— **起服对账的 local 腿**(SQL 列册对账的对位;唯一调用点 `LocalBackend.ensureSchema()`,排在 M33 快照消化之前 —— 消化会写会话元数据格):
      * 严格边档清册里的每一只读一次盘(`SidecarMap.reconcile`:冷 ⇒ 载入那一读;已载入 ⇒ 重读只判);读不出的合成**一只** {@link LocalDataRootSchemaMismatchError}
@@ -428,7 +485,7 @@ export declare class LocalSessionStore implements SessionStore {
      * 抛 ⇒ 读不出(尾部 I/O 故障之类:行头好、头读照样抛);否则读得出。所以行上的 `unreadable` 与头读、读口对同一只会话的答复同读。
      */
     private listedRowOf;
-    /** [ref] —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_meta.instruction_source` 同一只编解码)。 */
+    /** [ref] —— 换源通告的基线读(local 孪生;三态读法与 SQL 两孪生的 `session_ext.instruction_source` 同一只编解码)。 */
     readInstructionSource(sessionId: string): Promise<InstructionSourceBaseline>;
     /**
      * [ref] —— CAS 覆写基线(契约见 `InstructionSourceStore`:期望值不符 ⇒ 不写;**没落盘 ⇒ 内存不动、抛**,与 SQL 孪生
@@ -584,6 +641,17 @@ export declare class LocalSessionStore implements SessionStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** {@link listSessions} 带每行的住客(属主 + 化身那一格,与行同一刻读)—— `OwnerAwareSessionStore.listSessionRows`;化身不进行本身。 */
+    listSessionRows(opts: {
+        owner?: string;
+        includeUnowned?: boolean;
+        cursor?: {
+            lastActivityAt: string;
+            sessionId: string;
+        };
+        limit: number;
+        q?: string;
+    }): Promise<Array<SessionRowAnswer<SessionSummary>>>;
     /** 列表行要读的边档一次装齐(lastActivity / 标题 / 置顶 / 会话元数据);各自记忆化,只有第一次真读盘。 */
     private loadRowSidecars;
     /** 列表行上的属主:那一格的属主(没有格 / 属主从没被记下 ⇒ null —— 与 `headOf(id)?.owner` 同答;列表不补铸缺的格,`headOf` 在第一次读时补)。 */
@@ -611,8 +679,11 @@ export declare class LocalSessionStore implements SessionStore {
      *  修前把参数原样写进新格:`fork(owned, null)` 铸出一份匿名的有主历史。
      *  拷**已提交**的叶(契约):在飞的 assistant 轮不进孩子 —— 分叉点只有引擎那一只判官(core 7.55.0 起包根导出的 `settledForkOptions`),本店把唤醒出来的源会话交给它、
      *  把它的答案原样交给引擎自己的 `repo.fork`(与 core 内存店 `TtlSessionStore.fork` 同一条调用链);两只 SQL 孪生同读它(`session-fork.ts`)。钉:
-     *  core 店契约盒的 `[fork]` 格(`test/session-store-contract-kit.test.ts`)。 */
-    fork(sourceId: string, owner?: string | null): Promise<string | null>;
+     *  core 店契约盒的 `[fork]` 格(`test/session-store-contract-kit.test.ts`)。
+     *  `opts.placement`(后台 fork 子代的转录)= fork 进委派分区:见 {@link forkToHeld} 的建行点。 */
+    fork(sourceId: string, owner?: string | null, opts?: {
+        placement?: ForkPlacement;
+    }): Promise<string | null>;
     /**
      * **fork 续写的店契约**(local 一形;规则与结果闭集在 `session-fork.ts`,SQL 孪生同义):
      *  · **两把写锁**:按 id 字典序依次取源与目标的写锁(锁不可重入;同 id 只取一把)—— 同 id 的每个写者(删除 / 登记 / 导入 / 按 id 首建 / 别的 fork)都在目标那把锁里,
@@ -622,11 +693,20 @@ export declare class LocalSessionStore implements SessionStore {
      *    (不交属主 —— 引擎仓匿名;子存档的属主格抄自源存档,源匿名 ⇒ 子匿名)。
      *    崩在两步之间 = fork 创建的格而存档不在 = `forking`:普通取用一律 {@link SessionForkInProgressError};同键重试在两把锁内补拷存档、答 `replayed`。
      *    拷贝抛错(不是崩溃)⇒ 撤掉刚写的目标格再上抛(撤不掉 ⇒ 留下的就是 `forking`,与崩在中间同形);
-     *  · **撞已在** ⇒ 按目标格的属主与 fork 键分类({@link classifyForkTarget})。
+     *  · **fork 进委派分区**(`target.placement`,只在声明了分区的店落;没声明 ⇒ 忽略、照常 fork):元组随引擎 `repo.fork` 落进子存档行头 —— 与带 placement 的建行
+     *    ({@link createPlacedHeld})同一处、同一形(存档行头,first-write 不可变,`placedAt` 由 repo 铸);行的属主仍是上面那一读(元组不带属主)。建后读回准入同
+     *    `createPlacedHeld`(镜像方向:repo 交回的行没带这一组元组 ⇒ `placement_refused`):拒了就删掉刚拷的存档、再撤目标格(**存档先删、格后撤** —— 崩在中间留下的是
+     *    「格在而存档不在」的惰性残格;反过来会留下一份没有属主格的有主历史拷贝),删不掉 ⇒ 两只故障同句点名、出路随句;
+     *  · **撞已在** ⇒ 按目标格的属主与 fork 键分类({@link classifyForkTarget});placed 目标永不带键(型面互斥)⇒ 永不 `replayed`。
      */
     forkTo(sourceId: string, owner: string | null, target: ForkTarget): Promise<ForkToOutcome | null>;
     /** {@link forkTo} 的锁内一形(调用方持源与目标两把写锁)。 */
     private forkToHeld;
+    /**
+     * fork 进委派分区的建后读回准入(锁内,调用方持目标的写锁、刚拷完存档):判据 = 引擎那一只 `admitSessionPlacement`(镜像方向,读 repo 交回的那一份行头元组,零额外读),
+     * 与 {@link createPlacedHeld} 的读回同一判。拒 ⇒ 存档先删、目标格后撤(见 {@link forkToHeld} 注),再原样上抛那只 `placement_refused`;删不掉 ⇒ 同码、两只故障同句点名。
+     */
+    private admitForkedPlacement;
     /** 2c session-sync — EXPORT a session's full durable entry log (core `SessionRepo.exportEntries`; the
      *  in-memory/file repo holds the whole log so there is no floor to bypass). null if the source is unknown / the
      *  underlying repo lacks the optional seam. The owner is NOT exported — import re-stamps it. */
@@ -669,9 +749,10 @@ export declare class LocalSessionStore implements SessionStore {
     private withImportLock;
     /**
      * 三个导入写口(`importEntries` / `replaceEntries` / 暂存提交的换装臂)的共用写序(调用方持这只会话的写锁,属主的形已在入口判过):
-     *  ① 只读、零写:引擎闸 `validateEntriesForImport`(坏包 ⇒ `invalid_session`)· 本处写者 ⇒ {@link SessionWriterPresentError} · `forking` ⇒
-     *    {@link SessionForkInProgressError} · 不是这个写口的门判过的行 ⇒ {@link importRowRefused}(判据 {@link importMayLand},按写口带来的 {@link ImportLanding};
-     *    这条路径上唯一一次判属主);
+     *  ① 只读、零写:引擎闸 `validateEntriesForImport`(坏包 ⇒ `invalid_session`)· 准入 {@link admitImportHeld}(读 run 认领、交判官 {@link judgeImportWrite}:活 run 认领 ⇒
+     *    `SessionActiveRunError` · 本处写者 ⇒ `SessionWriterPresentError` · `forking` ⇒ {@link SessionForkInProgressError};SQL 孪生的事务内钩 `import` 臂同一只判官、同序、同拒;
+     *    `judged` 在 {@link commitStagedImport} 里准入过,不再来一遍)· 不是这个写口的门判过的行 ⇒ {@link importRowRefused}(判据 {@link importMayLand},按写口带来的
+     *    {@link ImportLanding};这条路径上唯一一次判属主);
      *  ② 行先:{@link landImportCell}(属主重戳为导入者、化身与 fork 键沿用或新铸、执行位 mirror;建档时刻与谱系照带,新行写此刻);
      *  ③ 内容,按写口的动词(唯一读法在下面这一只 switch;这里不读那一格、不判属主,只换**内容**;交给引擎仓的属主恒缺席 —— 规则一):
      *    · `create` / `judged`(导入):原地换锁里读到的那一份存档的日志(没有存档 ⇒ 导入新建一只,匿名),以锁里读到的存档头为 `expect.row`(**行代号**:
@@ -691,6 +772,14 @@ export declare class LocalSessionStore implements SessionStore {
      * 读法 = {@link isPlacedRow}(行头读不出 ⇒ 按普通行答,坏档照样换得掉;说不出 ⇒ 抛)。
      */
     private assertNotPlacedHeld;
+    /**
+     * 三个导入写口落 mirror 之前的**准入**(调用方持这只会话的写锁;{@link importHeld} ① 与暂存提交「内容相同、日志不动」那一支都经这一处):**取锁 → 读认领 → 判 → 写**,
+     * 与 {@link markMirrorExecution} 同序。判官就是 SQL 孪生事务内钩 `import` 臂的那一只 {@link judgeImportWrite}(词、拒码、先认领后写者都在判官里,本店不另写一份):
+     * 认领读 run 店的单活槽({@link SessionRunClaimSource})、格读 {@link placementCellOf}(`forking` 按 {@link forkingOf} 判好)—— 读口按需:认领在 ⇒ 不探存档。
+     * 拒 ⇒ 抛那只 typed 错,此时导入的任何一笔写(格 / 存档 / 新近)都还没发生(读侧的补铸除外:盘上有会话而格缺时,读它的读口先补铸那一格 —— 与别的读口同,幂等)。
+     * 路由的认领判(第一阶段写前判 + 提交前复判)仍在、更早一道,不再是唯一防线。
+     */
+    private admitImportHeld;
     /**
      * ① 的属主 / 住客条件:这一行此刻是不是这个写口的门判过的行({@link ImportLanding};一次读、零写 —— 格缺时「行在不在」只问存档的唯一探针
      * {@link existsInRepo},不补铸那一格)。属主比的是头读的读法 `owner ?? null`(从没被记下 = 无主;格缺而存档在 = 从没被记下),比较器是删除门的那一只
@@ -700,7 +789,7 @@ export declare class LocalSessionStore implements SessionStore {
     private importMayLand;
     /**
      * ② 推送落下的那一格 —— 三个导入写口与暂存提交「内容相同、日志不动」那一支都经这**一处**(调用方持写锁、① 已判过):属主重戳为导入者;
-     * 化身与 fork 键经 {@link carriedRowCells}(三只店同一句)读那一格自己 —— 行在 ⇒ 沿用(同一行 = 同一位住客,属主重戳与否不改这一判),刚建 ⇒ 新铸、不带键;
+     * 化身与 fork 键经 {@link carriedRowCells}(SQL 两店就地改写同一行、化身与旁表行不动 —— 同一结局)读那一格自己 —— 行在 ⇒ 沿用(同一行 = 同一位住客,属主重戳与否不改这一判),刚建 ⇒ 新铸、不带键;
      * 执行位 = mirror(导入落下的是「写者在别处」;SQL 孪生的提交点同一句写)。**在 `before` 上改这三位**,别的位(建档时刻、谱系)照带;刚建的行建档时刻 = 此刻。
      * 只写这一格:四只行边档与新近不在这里。交回写之前的那一格(`undefined` = 原本没有),③ 撤回用。
      */
@@ -741,7 +830,7 @@ export declare class LocalSessionStore implements SessionStore {
      * {@link LocalStagingHandle.commit} 的整段 —— **一次持锁**(这只会话的写锁,{@link withSessionWriteLock}):属主 CAS(此刻的属主格 = 这次导入的门判过的那一格,
      * 否则抛 {@link StagedCommitOwnerChangedError},一个字节不写;在判目的端日志之前判,SQL 孪生同序)→ 分区判 → 提交时重新分类(目的端此刻的日志 vs staged)→
      * 这一提交要换日志(不是「id 与内容都相同」那一支)⇒ 带戳存档判({@link assertArchiveAnonymous};只有 local 店有带戳存档,SQL 孪生没有这一步)→
-     * 拒未经同意的 fork / stale / 载荷分叉(带戳判在它们之前:带戳存档上日志换不了,同步冲突与载荷分叉的出路 —— 带同意重来 —— 无从谈起)→ 本处写者拒 → 换装(导入写序 ①②③,落点 `judged` = 上面这一判;化身与 fork 键按换装律沿用)或 identical 且内容相同时日志不动、
+     * 拒未经同意的 fork / stale / 载荷分叉(带戳判在它们之前:带戳存档上日志换不了,同步冲突与载荷分叉的出路 —— 带同意重来 —— 无从谈起)→ 准入({@link admitImportHeld}:读认领 → 本处写者 / fork 中间态 → 拒;fork 中间态的拒也在这一处,不再在提交入口另判一遍)→ 换装(导入写序 ①②③,落点 `judged` = 上面这一判;化身与 fork 键按换装律沿用)或 identical 且内容相同时日志不动、
      * 行照样落(② 那一格:重戳属主 + mirror)→ 两支同记新近(推送即活动)→ **在同一次持锁里**
      * 读出落定的会话面交回。锁放下之前谁也换不掉这一位住客,所以交回的面就是这次提交落下的那一位(SQL 孪生在提交事务里读同一行,同义);
      * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。改属主的每一条写腿(登记 / 删除 / 导入 / 换装)都在同一把锁里,所以锁内这一读到锁放下都成立。