@sema-agent/server 7.103.2 → 7.105.0

package/dist/plugins/file-resume-anchor-store.js

@@ -1,13 +1,25 @@
 import { join } from "node:path";
 import { existsSync, readdirSync, rmSync } from "node:fs";
-import { AppendLog, ensureDir, readJsonlRecords, sanitizePathComponent } from "@sema-agent/core";
+import { AppendLog, ensureDir, sanitizePathComponent } from "@sema-agent/core";
+import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
+const ANCHOR_RECORD_SHAPE = {
+    what: "resume-anchor record without a string eventId / entryId",
+    read(record) {
+        const { eventId, entryId, owner } = record;
+        if (typeof eventId !== "string" || typeof entryId !== "string")
+            return undefined;
+        return { eventId, entryId, owner: typeof owner === "string" ? owner : null, ownerReadable: owner === undefined || owner === null || typeof owner === "string" };
+    },
+};
 export class FileResumeAnchorStore {
     dir;
     bySession = new Map();
     logs = new Map();
-    constructor(root) {
+    warn;
+    constructor(root, opts) {
         this.dir = join(root, "resume-anchors");
+        this.warn = opts?.warn;
         ensureDir(this.dir);
         this.hydrate();
     }
@@ -26,14 +38,16 @@ export class FileResumeAnchorStore {
             if (!name.endsWith(".jsonl"))
                 continue;
             const key = name.slice(0, -".jsonl".length);
-            const records = readJsonlRecords(join(this.dir, name));
+            const { records } = replayJsonlSkipping(join(this.dir, name), "resume-anchor", ANCHOR_RECORD_SHAPE, this.warn);
             if (!records.length)
                 continue;
             const m = this.bySession.get(key) ?? new Map();
             for (const r of records) {
-                if (!r || typeof r.eventId !== "string" || typeof r.entryId !== "string")
+                if (!r.ownerReadable) {
+                    m.delete(r.eventId);
                     continue;
-                m.set(r.eventId, { entryId: r.entryId, owner: r.owner ?? null });
+                }
+                m.set(r.eventId, { entryId: r.entryId, owner: r.owner });
             }
             this.bySession.set(key, m);
         }

package/dist/plugins/file-run-store.d.ts

@@ -1,5 +1,6 @@
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskStatus } from "@sema-agent/core";
+import type { Logger } from "../observability/logger.js";
 import { StoreBootRefusalError, type RunRecord, type SessionSummary, type RunEvent, type PersistedTaskResult, type LatestRunRef } from "./store-contracts.js";
 import type { RunStoreCheckpointProbe } from "./memory-run-store.js";
 import type { LedgerEventType } from "../trace/ledger-events.js";
@@ -45,9 +46,12 @@ export declare class FileRunStore {
     /** [ref] 件B(census 第 29 行终局):`RUN_STORE_STRICT_HYDRATE` 的**部署级**表态。
      *  `true` ⇒ hydrate 的 readdir 失败拒启;缺席/`false` ⇒ 件6 的记债腿,行为字节不变。 */
     private readonly strictHydrate;
+    /** S-582:三个盘面坏行的腐读披露座(`LocalBackend` 接 `discloseWarn`;缺席 ⇒ 重放属主退回 `console.warn`)。 */
+    private readonly corruptReadWarn;
     constructor(root: string, opts?: {
         error?(msg: string, fields?: Record<string, unknown>): void;
         strictHydrate?: boolean;
+        warn?: Logger["warn"];
     });
     private runDir;
     private runJsonPath;
@@ -58,8 +62,9 @@ export declare class FileRunStore {
     private toRecord;
     /** Replay the on-disk registry/claims/event-logs into the in-memory index on boot. Each plane is torn-tail-/
      *  partial-write-safe (run.json via atomicWriteFile can never be half-written; the active file via writeThenLink is
-     *  all-or-nothing; events.jsonl via readJsonlRecords drops a crash tail). A corrupt run.json (failed parse) is
-     *  skipped — that run is lost, not a poison that fails the boot. */
+     *  all-or-nothing; events.jsonl via the JSONL replay drops a crash tail). A corrupt run.json (failed parse) is
+     *  skipped — that run is lost, not a poison that fails the boot — and since S-582 the skip is disclosed and counted
+     *  (`server.run-store.corrupt-record-skipped`), never silent. */
     /**
      * hydrate 期**逐文件**读盘的统一口([ref] 件B / codex 对抗复审 R4-[high])。
      *
@@ -73,6 +78,12 @@ export declare class FileRunStore {
      * 吞、也不改形),既有的「坏行跳过、不毒 boot」宽容契约与既有的抛法一起原封保留。
      */
     private replay;
+    /**
+     * S-582 —— 本店**唯一**的盘上记录读口(hydrate 经 {@link replay} 包一层 strict 档,运行期读点直调它):
+     * 交形判据给重放属主,坏行按登记名 `run-store` 跳过 + 披露 + 计数。strict 档的射程是「文件读不出」,
+     * 不含「文件里有坏行」—— 后者在两档下都走这里的 F 臂(普查表第 96 行)。
+     */
+    private readRecords;
     /**
      * strict 档下的**存在性判别**(codex R4-[high] 的前半):`existsSync` 对 ENOENT 与 EACCES 同答 false,
      * 而这两句话在本门下必须分开 —— 前者是常态(`runs/` 下的非目录杂物、还没落盘的目录),后者是「我读
@@ -110,10 +121,12 @@ export declare class FileRunStore {
     /** [ref] FIRST terminal writer wins(SQL 孪生同款正向 CAS on running/suspended/needs_review,
      *  [1.207 codex M1] 负向形漏 blocked/timeout);claim 释放保持无条件(幂等)。 */
     setTerminal(taskId: string, status: TaskStatus, result: PersistedTaskResult | null, error: string | null): Promise<void>;
-    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard). */
-    setSuspended(taskId: string): Promise<void>;
-    /** [ref] D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
-    setNeedsReview(taskId: string): Promise<void>;
+    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard).
+     *  S-173:同时落 `result` —— 封口脱敏后的投影(`sealRunRowResult`,凭据不落;`null` = 没观察到 park 结果),SQL 孪生同注。 */
+    setSuspended(taskId: string, result: PersistedTaskResult | null): Promise<void>;
+    /** [ref] D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review.
+     *  S-173:同 {@link setSuspended} 落封口脱敏后的 `result`。 */
+    setNeedsReview(taskId: string, result: PersistedTaskResult | null): Promise<void>;
     /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags.
      *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改。 */
     markResuming(taskId: string, instanceId: string): Promise<boolean>;
@@ -192,7 +205,7 @@ export declare class FileRunStore {
     /** [ref] wire the checkpoint probe (LocalBackend.checkpoint(), where checkpoint + run store share one root). */
     setCheckpointProbe(probe: RunStoreCheckpointProbe): void;
     /** [ref] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired') and
-     *  PERSIST it — the file twin of the SQL UPDATE (`error`/`error_code` set directly, no result blob). */
+     *  PERSIST it — the file twin of the SQL UPDATE (`error`/`error_code` set directly, no result blob; S-173: the park-time `result` is cleared, same as the SQL `result = NULL`). */
     private failExpiredPark;
     /**
      * [ref] Durable F4 expiry — the file twin of TiDBRunStore.reapSuspended, driven by the injected checkpoint
@@ -294,7 +307,7 @@ export declare class FileRunStore {
     /** Drop a run entirely (registry + event log + open fd + on-disk dir) — used by deleteBySession. */
     private dropRun;
     /**
-     * 🔴 **一次性迁移(随 7.75.0 连同 `one-time-migrations.ts` 整删)** —— 退役词旧拼法的账本改写,
+     * 🔴 **一次性迁移 M3 的 local 腿(窗口见 `one-time-migrations.ts` 登记表,随 M3 一起删)** —— 退役词旧拼法的账本改写,
      * SQL 两孪生那条整表 UPDATE 的 local 形。逐条走**同一只**纯改写函数,所以三条车道改出来的字节一致。
      *
      * 为什么是 store 上的一只动词、而不是外面一个文件走查:本店的账本有**两份**在场 —— 盘上的 jsonl

package/dist/plugins/file-run-store.js

@@ -1,21 +1,45 @@
-import { redactErrorMessage, redactLedgerEventData, redactTerminalResult } from "../observability/run-terminal.js";
+import { redactErrorMessage, redactLedgerEventData, sealRunRowResult } from "../observability/run-terminal.js";
 import { outwardPlane } from "../terminal.js";
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprint, readJsonlRecords, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
+import { AppendLog, atomicWriteFile, ensureDir, isProcessLive, processFingerprint, sanitizePathComponent, writeThenLink } from "@sema-agent/core";
 import { recordFailOpen } from "../observability/fail-open.js";
+import { replayJsonlSkipping } from "../observability/corrupt-read-seat.js";
 import { StoreBootRefusalError } from "./store-contracts.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
 import { migrateRetiredAskOrigin } from "./one-time-migrations.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
+const isParseableDate = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
+const RUN_ROW_SHAPE = {
+    what: "run.json record without a string taskId and parseable createdAt / updatedAt",
+    read(record) {
+        const r = record;
+        return typeof r.taskId === "string" && isParseableDate(r.createdAt) && isParseableDate(r.updatedAt) ? record : undefined;
+    },
+};
+const EVENT_RECORD_SHAPE = {
+    what: "run event record without a numeric seq",
+    read(record) {
+        return typeof record.seq === "number" ? record : undefined;
+    },
+};
+const CLAIM_RECORD_SHAPE = {
+    what: "active-run claim record without a string sessionId / taskId",
+    read(record) {
+        const r = record;
+        return typeof r.sessionId === "string" && typeof r.taskId === "string" ? record : undefined;
+    },
+};
 const CLAIM_TAKEOVER_ATTEMPTS = 3;
 const SAFE_PATH_COMPONENT = /^[A-Za-z0-9_.-]+$/;
 const isSafePathComponent = (s) => s !== "" && s !== "." && s !== ".." && SAFE_PATH_COMPONENT.test(s);
-function readClaimRecord(recs, sessionId) {
-    const c = recs[recs.length - 1];
-    if (!c || typeof c.sessionId !== "string" || typeof c.taskId !== "string" || c.sessionId !== sessionId)
+function singleRecordOf(read) {
+    return read.skipped > 0 ? undefined : read.records[read.records.length - 1];
+}
+function readClaimRecord(c, sessionId) {
+    if (!c || c.sessionId !== sessionId)
         return undefined;
     if (!isSafePathComponent(c.taskId))
         return undefined;
@@ -38,9 +62,11 @@ export class FileRunStore {
     claimLocks = new Map();
     logger;
     strictHydrate;
+    corruptReadWarn;
     constructor(root, opts) {
         this.logger = opts;
         this.strictHydrate = opts?.strictHydrate === true;
+        this.corruptReadWarn = opts?.warn;
         this.runsDir = join(root, "runs");
         this.activeDir = join(root, "runs", "active");
         this.tmpDir = join(root, "tmp");
@@ -96,9 +122,9 @@ export class FileRunStore {
             updatedAt: r.updatedAt.toISOString(),
         };
     }
-    replay(path) {
+    replay(path, shape) {
         try {
-            return readJsonlRecords(path);
+            return this.readRecords(path, shape);
         }
         catch (err) {
             if (!this.strictHydrate)
@@ -110,6 +136,9 @@ export class FileRunStore {
                 "Fix the permissions/mount on that path, point LOCAL_DATA_ROOT at a readable dir, or unset RUN_STORE_STRICT_HYDRATE to boot anyway (the pre-existing behavior).");
         }
     }
+    readRecords(path, shape) {
+        return replayJsonlSkipping(path, "run-store", shape, this.corruptReadWarn);
+    }
     refuseIfUnreadable(jsonPath, dir) {
         try {
             statSync(jsonPath);
@@ -159,21 +188,17 @@ export class FileRunStore {
                     this.refuseIfUnreadable(jsonPath, dir);
                 continue;
             }
-            const rows = this.replay(jsonPath);
-            const disk = rows[rows.length - 1];
-            if (!disk || typeof disk.taskId !== "string")
-                continue;
-            if (typeof disk.createdAt !== "string" || Number.isNaN(Date.parse(disk.createdAt)) ||
-                typeof disk.updatedAt !== "string" || Number.isNaN(Date.parse(disk.updatedAt)))
+            const disk = singleRecordOf(this.replay(jsonPath, RUN_ROW_SHAPE));
+            if (!disk)
                 continue;
             this.runs.set(disk.taskId, this.toRow(disk));
             const eventsPath = join(dir, "events.jsonl");
-            const recs = this.replay(eventsPath);
+            const recs = this.replay(eventsPath, EVENT_RECORD_SHAPE).records;
             if (recs.length) {
                 const list = [];
                 const seen = new Set();
                 for (const e of recs) {
-                    if (!e || typeof e.seq !== "number" || seen.has(e.seq))
+                    if (seen.has(e.seq))
                         continue;
                     seen.add(e.seq);
                     list.push({ seq: e.seq, type: String(e.type), data: e.data ?? null, ts: String(e.ts) });
@@ -215,9 +240,8 @@ export class FileRunStore {
         }
         for (const sanitized of claims) {
             const path = join(this.activeDir, sanitized);
-            const recs = this.replay(path);
-            const claim = recs[recs.length - 1];
-            if (claim && typeof claim.sessionId === "string" && typeof claim.taskId === "string" && isSafePathComponent(claim.taskId)) {
+            const claim = singleRecordOf(this.replay(path, CLAIM_RECORD_SHAPE));
+            if (claim && isSafePathComponent(claim.taskId)) {
                 this.active.set(claim.sessionId, claim.taskId);
                 continue;
             }
@@ -355,7 +379,7 @@ export class FileRunStore {
             .map((e) => ({ ...e, data: e.data == null ? null : structuredClone(e.data) }));
     }
     async setTerminal(taskId, status, result, error) {
-        result = redactTerminalResult(result);
+        result = sealRunRowResult(result);
         error = error === null ? null : (redactErrorMessage(error) ?? null);
         const r = this.runs.get(taskId);
         if (!r) {
@@ -391,18 +415,22 @@ export class FileRunStore {
         if (pending)
             notifyRunTerminal(pending);
     }
-    async setSuspended(taskId) {
+    async setSuspended(taskId, result) {
+        const sealed = sealRunRowResult(result);
         const r = this.runs.get(taskId);
         if (r && (r.status === "running" || r.status === "suspended")) {
             r.status = "suspended";
+            r.result = sealed;
             r.updatedAt = new Date();
             this.persist(r);
         }
     }
-    async setNeedsReview(taskId) {
+    async setNeedsReview(taskId, result) {
+        const sealed = sealRunRowResult(result);
         const r = this.runs.get(taskId);
         if (r && (r.status === "running" || r.status === "needs_review")) {
             r.status = "needs_review";
+            r.result = sealed;
             r.updatedAt = new Date();
             this.persist(r);
         }
@@ -412,6 +440,7 @@ export class FileRunStore {
         if (!r || (r.status !== "suspended" && r.status !== "needs_review"))
             return false;
         r.status = "running";
+        r.result = null;
         r.instanceId = instanceId;
         r.cancelRequested = false;
         r.preemptRequested = false;
@@ -551,6 +580,7 @@ export class FileRunStore {
         for (const r of this.runs.values()) {
             if (r.status === "running" && pred(r)) {
                 r.status = "failed";
+                r.result = null;
                 r.error = reason;
                 r.updatedAt = new Date();
                 this.persist(r);
@@ -572,6 +602,7 @@ export class FileRunStore {
         }
         for (const r of orphans) {
             r.status = "failed";
+            r.result = null;
             r.error = "run orphaned by engine restart";
             r.updatedAt = new Date();
             this.persist(r);
@@ -584,6 +615,7 @@ export class FileRunStore {
     }
     failExpiredPark(r) {
         r.status = "failed";
+        r.result = null;
         r.error = "approval expired before decision";
         r.errorCode = "approval.expired";
         r.updatedAt = new Date();
@@ -642,14 +674,8 @@ export class FileRunStore {
         const path = this.runJsonPath(taskId);
         if (!existsSync(path))
             return undefined;
-        const rows = readJsonlRecords(path);
-        const disk = rows[rows.length - 1];
-        if (!disk || typeof disk.taskId !== "string")
-            return undefined;
-        if (typeof disk.createdAt !== "string" || Number.isNaN(Date.parse(disk.createdAt)) ||
-            typeof disk.updatedAt !== "string" || Number.isNaN(Date.parse(disk.updatedAt)))
-            return undefined;
-        return this.toRow(disk);
+        const disk = singleRecordOf(this.readRecords(path, RUN_ROW_SHAPE));
+        return disk === undefined ? undefined : this.toRow(disk);
     }
     newestNonTerminalRowOnDisk(sessionId) {
         const names = readdirSync(this.runsDir);
@@ -660,12 +686,8 @@ export class FileRunStore {
             const path = join(this.runsDir, name, "run.json");
             if (!existsSync(path))
                 continue;
-            const rows = readJsonlRecords(path);
-            const disk = rows[rows.length - 1];
-            if (!disk || typeof disk.taskId !== "string" || disk.sessionId !== sessionId)
-                continue;
-            if (typeof disk.createdAt !== "string" || Number.isNaN(Date.parse(disk.createdAt)) ||
-                typeof disk.updatedAt !== "string" || Number.isNaN(Date.parse(disk.updatedAt)))
+            const disk = singleRecordOf(this.readRecords(path, RUN_ROW_SHAPE));
+            if (!disk || disk.sessionId !== sessionId)
                 continue;
             if (disk.status !== "running" && disk.status !== "suspended" && disk.status !== "needs_review")
                 continue;
@@ -705,7 +727,7 @@ export class FileRunStore {
             catch (e) {
                 if (e.code !== "EEXIST")
                     throw e;
-                const claim = readClaimRecord(readJsonlRecords(this.activePath(sessionId)), sessionId);
+                const claim = readClaimRecord(singleRecordOf(this.readRecords(this.activePath(sessionId), CLAIM_RECORD_SHAPE)), sessionId);
                 const holder = claim?.taskId ?? this.active.get(sessionId) ?? "";
                 const verdict = await this.judgeClaim(sessionId, claim, holder);
                 if (verdict.kind === "live")
@@ -721,7 +743,7 @@ export class FileRunStore {
             if (e.code !== "EEXIST")
                 throw e;
         }
-        const finalClaim = readClaimRecord(readJsonlRecords(this.activePath(sessionId)), sessionId);
+        const finalClaim = readClaimRecord(singleRecordOf(this.readRecords(this.activePath(sessionId), CLAIM_RECORD_SHAPE)), sessionId);
         return { ok: false, activeTaskId: finalClaim?.taskId ?? this.active.get(sessionId) ?? "" };
     }
     async judgeClaim(sessionId, claim, holderTaskId) {
@@ -789,7 +811,7 @@ export class FileRunStore {
         return { kind: "stale", reason: `run orphaned by engine restart (claim held by ${who}, which is gone)`, snapshot };
     }
     takeOverClaim(sessionId, reason, snapshot) {
-        const nowClaim = readClaimRecord(readJsonlRecords(this.activePath(sessionId)), sessionId);
+        const nowClaim = readClaimRecord(singleRecordOf(this.readRecords(this.activePath(sessionId), CLAIM_RECORD_SHAPE)), sessionId);
         if (snapshot.torn) {
             if (nowClaim !== undefined)
                 return false;

package/dist/plugins/image-bake-store-sql.d.ts

@@ -122,8 +122,6 @@ export declare class SqlImageBake {
     private lineOrdExists;
     /** Highest event seq for a bake (0 if none) — the ++seq allocator + the resume cursor head. */
     maxSeq(bakeId: string): Promise<number>;
-    /** Earliest retained event seq (0 if none) → the SSE 416 boundary (a resume below this was evicted, P2.9). */
-    retainedFrom(bakeId: string): Promise<number>;
     /** Events with seq strictly greater than `afterSeq` (0 for the whole stream), ascending. */
     getEvents(bakeId: string, afterSeq: number): Promise<BakeEvent[]>;
     /**

package/dist/plugins/image-bake-store-sql.js

@@ -379,11 +379,6 @@ export class SqlImageBake {
         const m = rows[0]?.m;
         return m == null ? 0 : Number(m);
     }
-    async retainedFrom(bakeId) {
-        const { rows } = await this.db.query(this.q("SELECT MIN(seq) AS m FROM image_bake_event WHERE bake_id = ?", "SELECT MIN(seq) AS m FROM image_bake_event WHERE bake_id = $1"), [bakeId]);
-        const m = rows[0]?.m;
-        return m == null ? 0 : Number(m);
-    }
     async getEvents(bakeId, afterSeq) {
         const { rows } = await this.db.query(this.q(`SELECT seq, line_ord, kind, level, ${jsonColumnText("tidb", "data")}, ts FROM image_bake_event WHERE bake_id = ? AND seq > ? ORDER BY seq ASC`, `SELECT seq, line_ord, kind, level, ${jsonColumnText("pg", "data")}, ts FROM image_bake_event WHERE bake_id = $1 AND seq > $2 ORDER BY seq ASC`), [bakeId, afterSeq]);
         return rows.map((r) => ({

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

@@ -1,5 +1,6 @@
 import { type AcquiredSession, type SessionStore, type SessionRepo, type SessionTreeEntry } from "@sema-agent/core";
 import type { SessionSummary } from "./store-contracts.js";
+import { type SessionFace } from "../session-incarnation.js";
 import { type InstructionSourceBaseline } from "../instruction-source-notice.js";
 import { type StagingHandle } from "../session-sync-kernel.js";
 export declare class LocalSessionStore implements SessionStore {
@@ -59,11 +60,30 @@ export declare class LocalSessionStore implements SessionStore {
      *  run selected, encoded like the SQL twins' `session_meta.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;
+    /** S-790 / S-506([ref] §2):会话化身(`session-incarnations.json`,`{ [sessionId]: token }`)。SQL 孪生的
+     *  `session_meta.incarnation` 列在本店的对位。🔴 **必须落盘**(不能像 `owners` 那样只活在内存):化身的口径是「一位住客一生
+     *  稳定」,而记忆引擎按它绑定会话级记录(opt-out / 污染标记)—— 重启后换一只值 = 同一位住客的 opt-out 不再绑它 = 静默恢复采集。
+     *  设计稿原说「存进属主边车」,但本店**没有**落盘的属主边车(`owners` 是纯内存 Map,S3 裁定),所以落在同一族的第四只边档
+     *  (同一只 `SidecarStringMap`:同写链、失败回滚)。铸点只在新建会话;盘上旧会话没有这一格 ⇒ 第一次读补铸并落盘。 */
+    private readonly incarnations;
     /** @param repo     the core SessionRepo this store projects into the §0.5 SessionStore shape.
      *  @param dataDir  the SAME data dir the file-backed repo persists under (LocalBackend passes `fileBackend.root`).
      *                  When given, lastActivity is persisted to `<dataDir>/session-last-activity.json` so it survives a
      *                  restart (the file-backed deployment); omit it for the in-memory deployment (nothing survives). */
     constructor(repo: SessionRepo, dataDir?: string);
+    /**
+     * S-790:把 `sessionId` 的化身写成 `next(before)` 的结果并**落盘**(写链里判、写、失败回滚 —— 与 instruction-source 同一只
+     * `commit`)。`next` 返回 `undefined` = 不改。落不了盘 ⇒ 抛(化身是正确性事实,不做「内存里先记着」的降级:一只没落盘的化身
+     * 重启后会被换掉,那就是另一位住客)。
+     */
+    private writeIncarnation;
+    /** S-790:新建会话 ⇒ 铸一只新的(覆盖同 id 上任何残留 —— 新建行就是新住客)。 */
+    private mintIncarnation;
+    /** S-790:已存在的会话缺一只化身(盘上 7.104.0 之前的会话)⇒ 补铸;已有的一个字节不动。 */
+    private ensureIncarnation;
+    /** S-790:属主 + 化身一次读(SQL 孪生同义;`undefined` = 无此会话)。盘上有会话而边档里没有它的化身 ⇒ 补铸并落盘后再答;
+     *  读的过程中会话被删 / 换了主 ⇒ `undefined`(与 {@link getHead} 同一条「读间被删」判据)。 */
+    sessionFaceOf(sessionId: string): Promise<SessionFace | undefined>;
     /** Cheap pre-LLM probe (local twin). The map write needs no session_meta row, so there is
      *  no "none" (register-lag) dimension here — two states only. */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
@@ -222,6 +242,8 @@ export declare class LocalSessionStore implements SessionStore {
      *  importing principal (re-stamped into the service-side owner map; core's local repo has no owner column, §9).
      *  `owner=null` (single-user local) is passed as `undefined` to the core seam (its owner param is `string | undefined`). */
     importEntries(sessionId: string, owner: string | null, entries: SessionTreeEntry[]): Promise<void>;
+    /** importEntries / replaceEntries 的共用写半场:导日志 + 盖属主 + 落化身(新建铸的那只,或换装沿用的那只)。 */
+    private importEntriesAs;
     /** 2c session-sync (§7/§8) — IDEMPOTENT REPLACE. The local twin's replace is DELETE-then-IMPORT: core's
      *  InMemorySessionRepo / FileSessionRepo expose no single replace primitive, but the local backend is single-writer
      *  with NO compaction floor / cross-instance race (a process-local in-memory map / a single-process file repo), so

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

@@ -3,9 +3,11 @@ import { join, resolve } from "node:path";
 import { SessionError, validateEntriesForImport } from "@sema-agent/core";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
-import { decodeJsonColumn, readStringRecordColumn } from "./sql-json-column.js";
+import { decodeJsonColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
+import { carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
+import { openSessionForItself } from "../session-records-skipped-notice.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
@@ -28,19 +30,21 @@ function userText(entry) {
     }
     return null;
 }
-const SIDECAR_DEGRADES = { lastActivity: "recency", title: "auto-title", "instruction-source": "instruction-source baseline" };
+const SIDECAR_DEGRADES = { lastActivity: "recency", title: "auto-title", "instruction-source": "instruction-source baseline", incarnation: "session-incarnation (the write that needed it failed loudly)" };
 const SIDECAR_MAP_STATE_BY_PATH = new Map();
 class SidecarStringMap {
     path;
     label;
     onUnreadable;
     onWriteFailed;
+    strict;
     own = { entries: new Map(), writeChain: Promise.resolve() };
-    constructor(path, label, onUnreadable, onWriteFailed) {
+    constructor(path, label, onUnreadable, onWriteFailed, strict = false) {
         this.path = path;
         this.label = label;
         this.onUnreadable = onUnreadable;
         this.onWriteFailed = onWriteFailed;
+        this.strict = strict;
         if (path && !SIDECAR_MAP_STATE_BY_PATH.has(path))
             SIDECAR_MAP_STATE_BY_PATH.set(path, { entries: new Map(), writeChain: Promise.resolve() });
     }
@@ -62,8 +66,16 @@ class SidecarStringMap {
                     }
                 }
                 catch (e) {
-                    if (e?.code !== "ENOENT")
+                    if (e?.code === "ENOENT")
+                        return;
+                    if (!this.strict) {
                         this.onUnreadable(path, e);
+                        return;
+                    }
+                    const kind = e instanceof SqlJsonColumnError ? e.problem : (e?.code ?? "unreadable");
+                    throw new Error(`${this.label} is unreadable (${kind}) — refusing to read or mint session incarnations until it is repaired: a replacement ` +
+                        `token for an existing session would make it a different occupant (its memory opt-out would stop binding it), and a write ` +
+                        `would overwrite the unreadable bytes. The file is left in place at ${path}.`);
                 }
             })();
         }
@@ -112,12 +124,48 @@ export class LocalSessionStore {
     sidecarPath;
     titles;
     instructionSources;
+    incarnations;
     constructor(repo, dataDir) {
         this.repo = repo;
         this.sidecarPath = dataDir ? join(dataDir, "session-last-activity.json") : undefined;
-        const sidecar = (file, which) => new SidecarStringMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which));
+        const sidecar = (file, which, strict = false) => new SidecarStringMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which), strict);
         this.titles = sidecar("session-titles.json", "title");
         this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source");
+        this.incarnations = sidecar("session-incarnations.json", "incarnation", true);
+    }
+    async writeIncarnation(sessionId, next) {
+        await this.incarnations.ensureLoaded();
+        const committed = await this.incarnations.commit((entries) => {
+            const before = entries.get(sessionId);
+            const value = next(before);
+            if (value === undefined || value === before)
+                return undefined;
+            entries.set(sessionId, value);
+            return () => {
+                if (before === undefined)
+                    entries.delete(sessionId);
+                else
+                    entries.set(sessionId, before);
+            };
+        });
+        if (!committed)
+            throw new SessionError("storage", `LocalSessionStore: session-incarnation sidecar write failed for session ${sessionId} — nothing was recorded`);
+    }
+    mintIncarnation(sessionId) {
+        return this.writeIncarnation(sessionId, () => mintSessionIncarnation());
+    }
+    ensureIncarnation(sessionId) {
+        return this.writeIncarnation(sessionId, (before) => (before === undefined ? mintSessionIncarnation() : undefined));
+    }
+    async sessionFaceOf(sessionId) {
+        const owner = await this.ownerOf(sessionId);
+        if (owner === undefined)
+            return undefined;
+        await this.ensureIncarnation(sessionId);
+        const incarnation = this.incarnations.state.entries.get(sessionId);
+        if (!this.owners.has(sessionId) || (this.owners.get(sessionId) ?? null) !== owner)
+            return undefined;
+        return sessionFaceFromRow(sessionId, owner, incarnation);
     }
     async probeTitle(sessionId) {
         await this.titles.ensureLoaded();
@@ -223,9 +271,11 @@ export class LocalSessionStore {
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
+            await this.incarnations.ensureLoaded();
             const session = await this.repo.create({});
             const id = (await session.getMetadata()).id;
             this.owners.set(id, null);
+            await this.mintIncarnation(id);
             return { session: session, sessionId: id };
         }
         if (opts?.requireExisting)
@@ -239,7 +289,7 @@ export class LocalSessionStore {
     }
     async load(sessionId, requireExisting = false) {
         try {
-            const session = await this.repo.open({ id: sessionId, createdAt: "" });
+            const session = await openSessionForItself(sessionId, () => this.repo.open({ id: sessionId, createdAt: "" }));
             if (!this.owners.has(sessionId))
                 this.owners.set(sessionId, null);
             return { session: session, sessionId };
@@ -249,7 +299,9 @@ export class LocalSessionStore {
                 throw e;
             if (requireExisting)
                 throw e;
+            await this.incarnations.ensureLoaded();
             const session = await this.repo.create({ id: sessionId });
+            await this.mintIncarnation(sessionId);
             if (!this.owners.has(sessionId))
                 this.owners.set(sessionId, null);
             return { session: session, sessionId };
@@ -258,15 +310,17 @@ export class LocalSessionStore {
     async register(sessionId, owner) {
         if (this.owners.has(sessionId))
             return;
+        await this.incarnations.ensureLoaded();
         this.owners.set(sessionId, owner);
         try {
             await this.repo.open({ id: sessionId, createdAt: "" });
+            await this.ensureIncarnation(sessionId);
         }
         catch (e) {
-            if (isNotFound(e))
-                await this.repo.create({ id: sessionId });
-            else
+            if (!isNotFound(e))
                 throw e;
+            await this.repo.create({ id: sessionId });
+            await this.mintIncarnation(sessionId);
         }
     }
     async ownerOf(sessionId) {
@@ -369,10 +423,12 @@ export class LocalSessionStore {
         }
     }
     async fork(sourceId, owner) {
+        await this.incarnations.ensureLoaded();
         try {
             const session = await this.repo.fork({ id: sourceId, createdAt: "" }, {});
             const id = (await session.getMetadata()).id;
             this.owners.set(id, owner);
+            await this.mintIncarnation(id);
             return id;
         }
         catch (e) {
@@ -410,10 +466,15 @@ export class LocalSessionStore {
         return gen();
     }
     async importEntries(sessionId, owner, entries) {
+        await this.importEntriesAs(sessionId, owner, entries, mintSessionIncarnation());
+    }
+    async importEntriesAs(sessionId, owner, entries, incarnation) {
         if (!this.repo.importEntries)
             throw new SessionError("storage", "session import is not supported by this local backend");
+        await this.incarnations.ensureLoaded();
         await this.repo.importEntries(sessionId, owner ?? undefined, entries);
         this.owners.set(sessionId, owner);
+        await this.writeIncarnation(sessionId, () => incarnation);
     }
     async replaceEntries(sessionId, owner, entries) {
         if (!this.repo.importEntries)
@@ -421,8 +482,10 @@ export class LocalSessionStore {
         if (!this.repo.delete)
             throw new SessionError("storage", "session replace is not supported by this local backend (no delete seam)");
         validateEntriesForImport(entries);
+        await this.incarnations.ensureLoaded();
+        const prior = this.owners.has(sessionId) ? { owner: this.owners.get(sessionId) ?? null, incarnation: this.incarnations.state.entries.get(sessionId) } : undefined;
         await this.deleteSession(sessionId, owner);
-        await this.importEntries(sessionId, owner, entries);
+        await this.importEntriesAs(sessionId, owner, entries, carriedIncarnation(prior, owner));
     }
     beginImportStaging(realSessionId, token) {
         const h = new LocalStagingHandle(this, realSessionId, stagingIdFor(realSessionId, token));
@@ -449,7 +512,7 @@ export class LocalSessionStore {
         this.owners.delete(sessionId);
         this.lastActivity.delete(sessionId);
         this.lastTaskRun.delete(sessionId);
-        for (const map of [this.titles, this.instructionSources]) {
+        for (const map of [this.titles, this.instructionSources, this.incarnations]) {
             await map.ensureLoaded();
             if (map.state.entries.delete(sessionId))
                 await map.persist();