@sema-agent/server 7.103.2 → 7.104.0

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/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();

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

@@ -55,10 +55,12 @@ export declare class MemoryRunStore {
     /** [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>;
@@ -124,7 +126,7 @@ export declare class MemoryRunStore {
     /** Fail stale `running` rows (crashed-run backstop) + release task_active for any now-terminal row. */
     reapStale(olderThanMs: number): Promise<number>;
     /** [ref] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired'), the
-     *  in-memory twin of the SQL UPDATE (`error`/`error_code` set directly — no result blob to derive from). */
+     *  in-memory twin of the SQL UPDATE (`error`/`error_code` set directly — no result blob to derive from; S-173: the park-time `result` is cleared, same as the SQL `result = NULL`). */
     private failExpiredPark;
     /** Release the claim for TERMINAL rows only — suspended/needs_review keep it (the `DELETE ta … WHERE tr.status
      *  NOT IN ('running','suspended','needs_review')` twin, shared by reapStale + the [ref] suspended reapers). */

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

@@ -1,4 +1,4 @@
-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 { notifyRunTerminal } from "../observability/run-terminal.js";
@@ -105,7 +105,7 @@ export class MemoryRunStore {
             .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) {
@@ -140,17 +140,21 @@ export class MemoryRunStore {
         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();
         }
     }
-    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();
         }
     }
@@ -159,6 +163,7 @@ export class MemoryRunStore {
         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;
@@ -292,6 +297,7 @@ export class MemoryRunStore {
         for (const r of this.runs.values()) {
             if (r.status === "running" && r.updatedAt.getTime() < cutoff) {
                 r.status = "failed";
+                r.result = null;
                 r.error = "run stalled (instance lost?)";
                 r.updatedAt = new Date();
                 reaped += 1;
@@ -302,6 +308,7 @@ export class MemoryRunStore {
     }
     failExpiredPark(r) {
         r.status = "failed";
+        r.result = null;
         r.error = "approval expired before decision";
         r.errorCode = "approval.expired";
         r.updatedAt = new Date();

package/dist/plugins/one-time-migrations.d.ts

@@ -16,8 +16,45 @@ export interface OneTimeMigrationReport {
     /** M4:`device_audit.detail` 里 JSON 文本 `null` 被改成列 NULL 的行数(表不在 ⇒ 恒 0)。
      *  非零 = 这次迁移真改写了存量字节,必须让运维看见(与 M1 的 `retiredSnapshotRows` 同一条纪律)。 */
     readonly auditDetailJsonNullRows: number;
+    /** M5:`session_meta.incarnation` 列 —— `added` = 本次 `ADD COLUMN`;`present` = 早已在(新库 / 第二跑);
+     *  `no-table` = 这只库上没有 `session_meta`(中央 DDL 之后不可达,只为不编一个读数);`lazy-on-read` = local 文件车道
+     *  (没有这张表,存量会话首读补铸)。 */
+    readonly sessionIncarnationColumn: "added" | "present" | "no-table" | "lazy-on-read";
+    /** M5:本次给空化身铸了令牌的行数。非零 = 这次迁移真写了存量行,必须让运维看见(与 M4 同一条纪律)。 */
+    readonly sessionIncarnationsBackfilled: number;
 }
-/** 三条迁移都不适用的载体(local 车道没有 SQL 表)。 */
+/**
+ * S-590 —— 一条一次性迁移的窗(登记表的一行;纯数据)。字段注写着每个值的取证方式,改一行之前照着重核。
+ * 规则(窗长 30 天、窗关后的第一个 minor 删码、门怎么判)在本文件头注「窗」一节,只写那一次。
+ */
+export interface OneTimeMigrationWindow {
+    /** 本文件里的条目名(头注「四条迁移」的 M1…M4)。 */
+    readonly id: string;
+    /** 引入这条迁移的版本 = 第一只含其代码的发布 tag(取证:`git log -S '<该条的常量名>' -- src/plugins/one-time-migrations.ts`
+     *  找引入提交 → `git tag --contains <提交> --sort=creatordate` 取最早)。 */
+    readonly introducedIn: string;
+    /** 该版本在 npm 上的发布日,UTC 日历日 YYYY-MM-DD(取证:`npm view @sema-agent/server time`)。`null` = **未发布形**:引入它的
+     *  那一版还没发布,由抬 `package.json` 到那一版的发布准备提交回填(规则见文件头「窗」一节;键必须显式写,缺席 ⇒ 到期门红)。 */
+    readonly releasedOn: string | null;
+    /** = `releasedOn` + 30 天(UTC 日历日;到期门逐条核这条等式)。今天晚于它 ⇒ 到期门红,删码排进其后第一个 minor。
+     *  与 `releasedOn` 同为 `null`(未发布形,不计到期)或同为日期。 */
+    readonly removableAfter: string | null;
+    /** 删码时删什么(到期门的红句逐字引用)。 */
+    readonly removal: string;
+    /** 删码之后,存量库若还带着迁移前的形,由哪一条**既有**响亮臂接住;没有就如实写没有(不为它新造兼容读)。 */
+    readonly afterRemoval: string;
+    /** 本条在 {@link OneTimeMigrationReport} 里的读数键 —— 报告的每个键恰属一条(到期门核:新迁移不登记 ⇒ 红)。 */
+    readonly reportKeys: readonly (keyof OneTimeMigrationReport)[];
+}
+/**
+ * 🔴 S-590 —— 一次性迁移登记表,本文件各条的窗的**唯一属主**。别处(接口 JSDoc、调用点、DDL 注、部署文档)只写「窗口见
+ * `plugins/one-time-migrations.ts` 登记表」;起动日志行 `one_time_migrations_applied` 的 `removableAfter` 读数由本表派生。
+ *
+ * M1–M3 同一次删:M3 的「本版在这只库上跑过了」标记就是 M1 / M2 的退役 schema 在不在(头注「幂等」一节),先删 M1 / M2
+ * 而留着 M3 会让 M3 永远判「跑过了」。三条同版引入、同一天到期,本来就同一次删。
+ */
+export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
+/** local 车道上 SQL 独有的四条(M1 / M2 / M4 / M5)的读数:那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
 export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "askOriginRowsMigrated">;
 /** 启动期的日志口(logger 的子集)。两级各有其用,见 {@link logOneTimeMigrations}。 */
 export interface MigrationLogSink {