@sema-agent/server 7.146.0 → 7.147.0

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

@@ -3,10 +3,10 @@ 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 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 ForkPlacement, type ForkTarget, type ForkToOutcome } from "./session-fork.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.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 孪生
@@ -692,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`(**行代号**:
@@ -714,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`(从没被记下 = 无主;格缺而存档在 = 从没被记下),比较器是删除门的那一只
@@ -723,7 +789,7 @@ export declare class LocalSessionStore implements SessionStore {
     private importMayLand;
     /**
      * ② 推送落下的那一格 —— 三个导入写口与暂存提交「内容相同、日志不动」那一支都经这**一处**(调用方持写锁、① 已判过):属主重戳为导入者;
-     * 化身与 fork 键经 {@link carriedRowCells}(三只店同一句)读那一格自己 —— 行在 ⇒ 沿用(同一行 = 同一位住客,属主重戳与否不改这一判),刚建 ⇒ 新铸、不带键;
+     * 化身与 fork 键经 {@link carriedRowCells}(SQL 两店就地改写同一行、化身与旁表行不动 —— 同一结局)读那一格自己 —— 行在 ⇒ 沿用(同一行 = 同一位住客,属主重戳与否不改这一判),刚建 ⇒ 新铸、不带键;
      * 执行位 = mirror(导入落下的是「写者在别处」;SQL 孪生的提交点同一句写)。**在 `before` 上改这三位**,别的位(建档时刻、谱系)照带;刚建的行建档时刻 = 此刻。
      * 只写这一格:四只行边档与新近不在这里。交回写之前的那一格(`undefined` = 原本没有),③ 撤回用。
      */
@@ -764,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 孪生在提交事务里读同一行,同义);
      * 提交之后按住客条件写的重放(会话行两位)只认这只面,不再重读。改属主的每一条写腿(登记 / 删除 / 导入 / 换装)都在同一把锁里,所以锁内这一读到锁放下都成立。

package/dist/plugins/local-session-store.js

@@ -1,26 +1,27 @@
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { lstat, readFile } from "node:fs/promises";
+import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { isDeepStrictEqual } from "node:util";
 import { dirname, join, resolve } from "node:path";
+import { atomicWriteFileAsync } from "./owner-only-file-mode.js";
 import { assertFirstOwnerWritable, forkOwnerOf, importerOwnerOf, placedSessionOwnerOf } from "./session-ownership.js";
 import { SessionOwnerUnreadableError, StampedSessionArchiveError, sessionUnreadableOf } from "../session-error-wire.js";
-import { FileSessionRepo, SessionError, StoredSession, admitSessionPlacement, atomicWriteFile, sessionLogMarkOf, settledForkOptions, uuidv7, validateEntriesForImport } from "@sema-agent/core";
+import { FileSessionRepo, SessionError, StoredSession, admitSessionPlacement, atomicWriteFile, ensureDir, sessionLogMarkOf, settledForkOptions, uuidv7, validateEntriesForImport } from "@sema-agent/core";
 import { placementCapabilityOf } from "./session-placement.js";
 import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
-import { StoreBootRefusalError } from "./store-contracts.js";
+import { SCHEMA_MISMATCH_ERROR_CODE, StoreBootRefusalError } from "./store-contracts.js";
 import { judgeSessionRowWrite, sessionRowTagKey, settleSessionRowWrite, } from "../session-row.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
-import { createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
-import { SCHEMA_MISMATCH_ERROR_CODE } from "./schema-consistency.js";
-import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./one-time-migrations.js";
+import { createZodColumnReader, decodeJsonColumn, isJsonColumnBodyProblem, isJsonObject, readJsonObjectColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
+import { RENAMED_EXECUTION_LANE_M40, RETIRED_EXECUTION_LANE_WORD_M40 } from "./execution-lane-rename-m40.js";
+import { ExecutionLaneRenameWriteRefusedError, ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./one-time-migrations.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { createLogger } from "../observability/logger.js";
-import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
+import { UNMANAGED_RETENTION } from "./retention-declaration.js";
 import { UnreadableLeaf, carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { isExecutionLane } from "../execution-lane-caps.js";
-import { SessionForkInProgressError, SessionWriterPresentError, WRITABLE, assertPlaceableLane, isUnusableArchive, settledMirrorOutcome, settledPlaceOutcome, } from "../execution-placement.js";
+import { SessionForkInProgressError, WRITABLE, assertPlaceableLane, isUnusableArchive, judgeImportWrite, settledMirrorOutcome, settledPlaceOutcome, } from "../execution-placement.js";
 import { classifyForkTarget, forkByFreshId } from "./session-fork.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
 import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
@@ -126,9 +127,13 @@ function rowMetadataOf(sessionId, meta) {
     return { id: sessionId, createdAt: rowCreatedAtOf(sessionId, meta), owner: face.owner, incarnation: face.incarnation, ...(meta.forkedFrom !== undefined ? { forkedFrom: meta.forkedFrom } : {}) };
 }
 const isForkCreatedCell = (meta) => meta !== undefined && meta.forkKey !== undefined && meta.execution === undefined;
+function placementCellOf(meta, forking) {
+    return forking ? { role: "forking" } : (meta?.execution ?? { role: "absent" });
+}
 function readingOfCell(sessionId, meta, forking) {
-    return { occupant: sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation), cell: forking ? { role: "forking" } : (meta.execution ?? { role: "absent" }) };
+    return { occupant: sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation), cell: placementCellOf(meta, forking) };
 }
+const SESSION_META_SIDECAR_FILE = "session-incarnations.json";
 const LOCAL_EXECUTION_CELL = z.discriminatedUnion("role", [
     z.object({ role: z.literal("writer"), lane: z.custom((v) => typeof v === "string" && isExecutionLane(v), { message: "not an execution lane" }) }).strict(),
     z.object({ role: z.literal("mirror") }).strict(),
@@ -154,18 +159,23 @@ function ownerClaimWindowOpen() {
 const SIDECAR_MAP_STATE_BY_PATH = new Map();
 const SESSION_WRITE_LOCKS_BY_ROOT = new Map();
 const quotedFieldNames = (names) => `${names.slice(0, 8).map((name) => JSON.stringify(name.slice(0, 64))).join(", ")}${names.length > 8 ? `, … (${names.length} in all)` : ""}`;
+function describeDataRootFinding(f) {
+    if (f.problem === "newer-engine") {
+        return `  ${f.label} at ${f.path}: engine high-water ${f.engineHighWater.highWater} — the data root has been opened by server ${f.engineHighWater.highWater}, NEWER than this build (${f.engineHighWater.engine}).`;
+    }
+    return f.unknownFields.length > 0
+        ? `  ${f.label} at ${f.path}: UNKNOWN field(s) ${quotedFieldNames(f.unknownFields)} — the data root is NEWER than this build (a newer server engine wrote it).`
+        : `  ${f.label} at ${f.path}: unreadable (${f.problem}) — this build cannot read it, and an unreadable file is treated as a mismatch, not as empty.`;
+}
 function describeLocalDataRootMismatch(findings, when) {
     const lines = [
         when === "boot"
             ? `${SCHEMA_MISMATCH_ERROR_CODE}: the local data root does not match this build's shape — refusing to start.`
             : `${SCHEMA_MISMATCH_ERROR_CODE}: the local data root does not match this build's shape — refusing to read or write the file(s) named below until this process is restarted.`,
     ];
-    for (const f of findings) {
-        lines.push(f.unknownFields.length > 0
-            ? `  ${f.label} at ${f.path}: UNKNOWN field(s) ${quotedFieldNames(f.unknownFields)} — the data root is NEWER than this build (a newer server engine wrote it).`
-            : `  ${f.label} at ${f.path}: unreadable (${f.problem}) — this build cannot read it, and an unreadable file is treated as a mismatch, not as empty.`);
-    }
-    lines.push("This build never reads such a file as empty and never writes over it: either would silently change what the file records.", "", "  Ways out (these three and no others):", "    (1) the data root is NEWER than this build (unknown fields): deploy the build that wrote it;", "    (2) roll back: restore the data-root backup taken before the upgrade, then start this build — also the way out when the file's bytes are damaged (not-json / malformed);", "    (3) the file could not be read at all (an I/O error such as EACCES): repair access to it (permissions, mount, disk) and restart — nothing in the file needs changing.", "The check behind this refusal only reads: the file was left in place and nothing in the data root was changed.");
+    for (const f of findings)
+        lines.push(describeDataRootFinding(f));
+    lines.push("This build never reads such a file as empty and never writes over it: either would silently change what the file records.", "", "  Ways out (these three and no others):", "    (1) the data root is NEWER than this build (unknown fields, or an engine high-water above this build): deploy the build that wrote it (for a high-water: server at or above it) — to run an older build on this machine, give it its own data root (LOCAL_DATA_ROOT);", "    (2) roll back: restore the data-root backup taken before the upgrade, then start this build — also the way out when the file's bytes are damaged (not-json / malformed);", "    (3) the file could not be read at all (an I/O error such as EACCES): repair access to it (permissions, mount, disk) and restart — nothing in the file needs changing.", "The check behind this refusal only reads: the file(s) named above were left in place, unchanged.");
     return lines.join("\n");
 }
 export class LocalDataRootSchemaMismatchError extends StoreBootRefusalError {
@@ -179,6 +189,56 @@ export class LocalDataRootSchemaMismatchError extends StoreBootRefusalError {
         this.name = "LocalDataRootSchemaMismatchError";
     }
 }
+export async function readDataRootFileText(path) {
+    try {
+        return { state: "text", text: await readFile(path, "utf8") };
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            return { state: "unreadable", fault: e };
+        return judgedAfterEnoent(e, await lstat(path).then(() => ENTRY_PRESENT, (fault) => ({ fault })));
+    }
+}
+export function readDataRootFileTextSync(path) {
+    try {
+        return { state: "text", text: readFileSync(path, "utf8") };
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            return { state: "unreadable", fault: e };
+        let probe = ENTRY_PRESENT;
+        try {
+            lstatSync(path);
+        }
+        catch (fault) {
+            probe = { fault };
+        }
+        return judgedAfterEnoent(e, probe);
+    }
+}
+const ENTRY_PRESENT = { present: true };
+function judgedAfterEnoent(readFault, probe) {
+    if ("present" in probe)
+        return { state: "unreadable", fault: readFault };
+    return probe.fault?.code === "ENOENT" ? { state: "absent" } : { state: "unreadable", fault: probe.fault };
+}
+export function dataRootMismatchOf(path, label, fault) {
+    if (fault instanceof SqlJsonColumnError)
+        return { path, label, problem: fault.problem, unknownFields: fault.unknownKeys };
+    const code = fault?.code;
+    return { path, label, problem: typeof code === "string" && /^E[A-Z0-9_]+$/.test(code) ? code : "unreadable", unknownFields: [] };
+}
+async function readSessionMetaForM40(path) {
+    const raw = await readDataRootFileText(path);
+    if (raw.state !== "text")
+        return raw;
+    try {
+        return { state: "read", entries: decodeJsonColumn(raw.text, readJsonObjectColumn, `${SESSION_META_SIDECAR_FILE} (one-time migration M40)`) };
+    }
+    catch (e) {
+        return { state: "unreadable", fault: e };
+    }
+}
 class SidecarMap {
     path;
     label;
@@ -244,15 +304,11 @@ class SidecarMap {
             throw this.refuse(path, disk);
     }
     async readDisk(path) {
-        let text;
-        try {
-            text = await readFile(path, "utf8");
-        }
-        catch (e) {
-            return e?.code === "ENOENT" ? { state: "absent" } : { state: "unreadable", fault: e };
-        }
+        const raw = await readDataRootFileText(path);
+        if (raw.state !== "text")
+            return raw;
         try {
-            return { state: "read", entries: decodeJsonColumn(text, this.read, this.label) };
+            return { state: "read", entries: decodeJsonColumn(raw.text, this.read, this.label) };
         }
         catch (e) {
             return { state: "unreadable", fault: e };
@@ -260,9 +316,7 @@ class SidecarMap {
     }
     refuse(path, disk) {
         const shape = isJsonColumnBodyProblem(disk.fault);
-        const problem = disk.fault instanceof SqlJsonColumnError ? disk.fault.problem : (disk.fault?.code ?? "unreadable");
-        const unknownFields = disk.fault instanceof SqlJsonColumnError ? disk.fault.unknownKeys : [];
-        const refusal = new LocalDataRootSchemaMismatchError([{ path, label: this.label, problem, unknownFields }], "serving");
+        const refusal = new LocalDataRootSchemaMismatchError([dataRootMismatchOf(path, this.label, disk.fault)], "serving");
         if (shape)
             this.state.refused = refusal;
         return refusal;
@@ -300,9 +354,7 @@ class SidecarMap {
                     }
                 }
                 try {
-                    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-                    await writeFile(tmp, JSON.stringify(Object.fromEntries(draft)), "utf8");
-                    await rename(tmp, path);
+                    await atomicWriteFileAsync(path, JSON.stringify(Object.fromEntries(draft)), { durability: "best-effort" });
                 }
                 catch (e) {
                     this.onWriteFailed(e);
@@ -435,7 +487,6 @@ export class LocalSessionStore {
     flushTimer;
     writeChain = Promise.resolve();
     dirty = false;
-    writeSeq = 0;
     lastWarnAt = 0;
     sidecarPath;
     titles;
@@ -493,7 +544,7 @@ export class LocalSessionStore {
         this.pinned = sidecar("session-pinned.json", "pinned", readPinnedSidecar);
         this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source", readStringRecordColumn);
         this.workspaces = sidecar("session-workspaces.json", "workspace", readStringRecordColumn);
-        this.meta = sidecar("session-incarnations.json", "session-meta", readSessionMetaSidecar, true);
+        this.meta = sidecar(SESSION_META_SIDECAR_FILE, "session-meta", readSessionMetaSidecar, true);
         const root = dataDir ? resolve(dataDir) : undefined;
         this.dataRoot = root;
         if (root !== undefined && !SESSION_WRITE_LOCKS_BY_ROOT.has(root))
@@ -509,6 +560,33 @@ export class LocalSessionStore {
             place: (sessionId, occupant, cell) => this.placeExecution(sessionId, occupant, cell),
         };
     }
+    async renameRetiredExecutionLaneWordM40() {
+        if (this.dataRoot === undefined)
+            return 0;
+        const path = join(this.dataRoot, SESSION_META_SIDECAR_FILE);
+        const disk = await readSessionMetaForM40(path);
+        if (disk.state !== "read")
+            return 0;
+        let renamed = 0;
+        for (const cell of Object.values(disk.entries)) {
+            if (!isJsonObject(cell))
+                continue;
+            const execution = cell["execution"];
+            if (!isJsonObject(execution) || execution["role"] !== "writer" || execution["lane"] !== RETIRED_EXECUTION_LANE_WORD_M40)
+                continue;
+            execution["lane"] = RENAMED_EXECUTION_LANE_M40;
+            renamed += 1;
+        }
+        if (renamed === 0)
+            return 0;
+        try {
+            await atomicWriteFileAsync(path, JSON.stringify(disk.entries), { durability: "best-effort" });
+        }
+        catch (e) {
+            throw new ExecutionLaneRenameWriteRefusedError(path, e);
+        }
+        return renamed;
+    }
     async assertStrictSidecarsReadable() {
         const loads = await Promise.allSettled(this.strictSidecars.map((map) => map.reconcile()));
         const findings = [];
@@ -943,10 +1021,8 @@ export class LocalSessionStore {
         this.dirty = false;
         const snapshot = Object.fromEntries(this.lastActivity);
         try {
-            await mkdir(join(path, ".."), { recursive: true });
-            const tmp = `${path}.${process.pid}.${++this.writeSeq}.tmp`;
-            await writeFile(tmp, JSON.stringify(snapshot), "utf8");
-            await rename(tmp, path);
+            ensureDir(dirname(path));
+            await atomicWriteFileAsync(path, JSON.stringify(snapshot), { durability: "best-effort" });
         }
         catch (e) {
             this.warnSidecar("write", e);
@@ -1306,10 +1382,8 @@ export class LocalSessionStore {
             await this.assertNotPlacedHeld(sessionId);
         validateEntriesForImport(entries);
         const current = this.metaCellOf(sessionId);
-        if (current?.execution?.role === "writer")
-            throw new SessionWriterPresentError(sessionId, current.execution.lane);
-        if (await this.forkingOf(sessionId, current))
-            throw new SessionForkInProgressError(sessionId);
+        if (landing !== "judged")
+            await this.admitImportHeld(sessionId, current);
         if (!(await this.importMayLand(sessionId, current, owner, landing)))
             throw importRowRefused(sessionId, landing);
         const prior = await this.landImportCell(sessionId, owner);
@@ -1348,6 +1422,14 @@ export class LocalSessionStore {
             throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placed.kind} placement partition (a delegated agent's transcript) — a session import cannot replace its log`);
         }
     }
+    async admitImportHeld(sessionId, current) {
+        const verdict = await judgeImportWrite(sessionId, {
+            claim: () => this.runs.getActiveTaskId(sessionId),
+            cell: async () => placementCellOf(current, await this.forkingOf(sessionId, current)),
+        });
+        if (verdict !== "proceed")
+            throw verdict.refuse;
+    }
     async importMayLand(sessionId, current, owner, landing) {
         switch (landing) {
             case "create":
@@ -1404,8 +1486,6 @@ export class LocalSessionStore {
             const current = await this.metaOf(sessionId);
             if (!ownerCellIs(opts.expectedOwner, current === undefined ? undefined : (current.owner ?? null)))
                 throw new StagedCommitOwnerChangedError(sessionId);
-            if (await this.forkingOf(sessionId, current))
-                throw new SessionForkInProgressError(sessionId);
             await this.assertNotPlacedHeld(sessionId);
             const dstEntries = await this.exportEntries(sessionId);
             const rel = classifySyncRelationshipByIds(staged.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
@@ -1421,8 +1501,7 @@ export class LocalSessionStore {
                 if (diverged)
                     throw new SyncConflictError(sessionId, contentForkRelation(diverged, rel.newEntryIds));
             }
-            if (current?.execution?.role === "writer")
-                throw new SessionWriterPresentError(sessionId, current.execution.lane);
+            await this.admitImportHeld(sessionId, current);
             if (rel.relation !== "identical" || !contentEqual) {
                 await this.importHeld(sessionId, importer, staged, "judged");
             }
@@ -1589,7 +1668,7 @@ export class LocalSessionStore {
         this.meta.syncToDisk();
         let anonymized = 0;
         if (listed.some((row) => (row.owner ?? null) !== null)) {
-            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            ensureDir(dir);
             fsyncPaths(dir, dirname(dir));
         }
         const keptStamped = [];

package/dist/plugins/local-task-attachment-store.d.ts

@@ -1,4 +1,6 @@
 import { type AttachmentStoreBindOutcome, type TaskAttachmentStore, type TaskAttachmentRecord } from "./task-attachment-store.js";
+/** 附件店在数据根下的目录(构造器与一次性迁移 M39 的名册同读这一只)。 */
+export declare function attachmentStoreDirFor(rootDir: string): string;
 export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
     private readonly dir;
     private metas;