@sema-agent/server 7.148.0 → 7.150.0

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

@@ -8,7 +8,7 @@ import { IS_WIN32 } from "./host-platform.js";
 import { atomicWriteFileAsync, atomicWriteFileSync, proveDurableSync } 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 { SHELL_SENTINEL_OWNER_M48 } from "./shell-sentinel-owner-m48.js";
+import { isShellSentinelOwnerM48 } from "./shell-sentinel-owner-m48.js";
 import { FileSessionRepo, SessionError, StoredSession, admitSessionPlacement, atomicWriteFile, ensureDir, forkRowCells, sessionLogMarkOf, settledForkOptions, uuidv7, validateEntriesForImport } from "@sema-agent/core";
 import { placementCapabilityOf } from "./session-placement.js";
 import { z } from "zod";
@@ -19,8 +19,9 @@ import { judgeSessionRowWrite, sessionRowTagKey, settleSessionRowWrite, } from "
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.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 } from "./one-time-migrations.js";
+import { ExecutionLaneRenameWriteRefusedError, migrationCarried } from "./one-time-migrations.js";
 import { compareReleaseTriples, releaseText, releaseTriple } from "./release-version.js";
+import { PRE_CUTOFF_SKILL_EXEMPTION_CONSEQUENCE, SKILL_EXEMPTION_TOOL_NAME } from "./approval-exemption-skill-cutoff.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 import { createLogger, writeLogText } from "../observability/logger.js";
 import { UNMANAGED_RETENTION } from "./retention-declaration.js";
@@ -78,6 +79,15 @@ function readSessionMetaCell(cell) {
         ? { incarnation: cell, owner: undefined, execution: undefined, forkKey: undefined, createdAt: undefined, forkedFrom: undefined, forkedFromIncarnation: undefined, dropping: false, deleting: undefined, clientWrites: undefined }
         : { incarnation: cell.incarnation, owner: cell.owner, execution: cell.execution, forkKey: cell.forkKey, createdAt: cell.createdAt, forkedFrom: cell.forkedFrom, forkedFromIncarnation: cell.forkedFromIncarnation, dropping: cell.dropping === true, deleting: cell.deleting, clientWrites: cell.clientWrites };
 }
+function shellSentinelCellIdsM48(cells) {
+    const ids = [];
+    for (const [sessionId, cell] of cells) {
+        if (typeof cell === "string" || !isShellSentinelOwnerM48(cell.owner) || readSessionMetaCell(cell).dropping)
+            continue;
+        ids.push(sessionId);
+    }
+    return ids;
+}
 const ownerRecorded = (cell) => cell !== undefined && readSessionMetaCell(cell).owner !== undefined;
 const cellObjectOf = (cell) => (typeof cell === "string" ? { incarnation: cell } : cell);
 function cellWith(before, bits) {
@@ -162,6 +172,27 @@ export const SESSION_META_CELL_OBJECT = z
     .strict();
 const SESSION_META_SIDECAR = z.record(z.string(), z.union([z.string(), SESSION_META_CELL_OBJECT]));
 const readSessionMetaSidecar = createZodColumnReader(SESSION_META_SIDECAR);
+function renameRetiredExecutionLaneWordsInCellsM40(entries) {
+    if (!isJsonObject(entries))
+        return 0;
+    let renamed = 0;
+    for (const cell of Object.values(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;
+    }
+    return renamed;
+}
+const STRICT_SIDECARS = [{ file: SESSION_META_SIDECAR_FILE, which: "session-meta" }];
+const readSessionMetaSidecarInWindow = (body) => {
+    renameRetiredExecutionLaneWordsInCellsM40(body);
+    return readSessionMetaSidecar(body);
+};
+const STRICT_SIDECAR_FILES = new Set(STRICT_SIDECARS.map((s) => s.file));
 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)` : ""}`;
@@ -174,24 +205,40 @@ 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}).`;
     }
-    if (f.problem === "skipped-required-migration") {
-        const { highWater, requiredSince, sessions } = f.skippedMigration;
-        const consequence = "This build no longer carries that migration: opening the root would give those sessions a new occupant token, and memory records kept under the old one (capture opt-outs, pollution marks) would stop applying to them.";
-        if (highWater !== null && releaseAtOrAbove(highWater, requiredSince)) {
-            return (`  ${f.label} at ${f.path}: ${sessions} session archive(s) have no session-meta cell, and the data root was last opened by server ${highWater}, which carries the one-time migration ` +
-                `(introduced in ${requiredSince}) that gives such an archive its row cell under the occupant token the archive already carries — but that start did not finish it ` +
-                `(${ARCHIVE_TOKEN_ADOPTION_PENDING_FILE} is still in the data root). ${consequence} ` +
-                `Start the root once with a release at or above ${highWater} that still carries that migration (server or run-local) and let that start finish, then start this build.`);
-        }
-        const lastOpened = highWater === null ? "no engine that records a high-water (run-local before 7.148.0, or a server before 7.144.0)" : `server ${highWater}`;
-        return (`  ${f.label} at ${f.path}: ${sessions} session archive(s) have no session-meta cell, and the data root was last opened by ${lastOpened} — older than ${requiredSince}, ` +
-            `whose one-time migration gives such an archive its row cell under the occupant token the archive already carries. ${consequence} ` +
-            `Start the root once with a release at or above ${requiredSince} that still carries that migration (server or run-local) and let that start finish, then start this build.`);
-    }
+    if (f.problem === "skipped-required-migration")
+        return describeSkippedMigration(f);
     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 describeSkippedMigration(f) {
+    const m = f.skippedMigration;
+    switch (m.residue) {
+        case "archives-without-cell":
+            return describeArchivesWithoutCell(f, m);
+        case "pre-cutoff-skill-exemptions": {
+            const atLeast = m.highWater !== null && releaseAtOrAbove(m.highWater, m.requiredSince) ? m.highWater : m.requiredSince;
+            const cutoff = m.cutoff === null ? "no cutoff is recorded in the data root (no release that records it has fully started on this root)" : `the data root's cutoff is ${m.cutoff}`;
+            return (`  ${f.label} at ${f.path}: ${m.sessions} session(s) hold a \`${SKILL_EXEMPTION_TOOL_NAME}\` session approval exemption first granted before the Skill exemption cutoff (${cutoff}). ` +
+                `${PRE_CUTOFF_SKILL_EXEMPTION_CONSEQUENCE} This build no longer carries the one-time migration (introduced in ${m.requiredSince}) that removes such rows. ` +
+                `Start the root once with a release at or above ${atLeast} that still carries that migration (server or run-local) and let that start finish, then start this build.`);
+        }
+    }
+}
+function describeArchivesWithoutCell(f, m) {
+    const { highWater, requiredSince, sessions } = m;
+    const consequence = "This build no longer carries that migration: opening the root would give those sessions a new occupant token, and memory records kept under the old one (capture opt-outs, pollution marks) would stop applying to them.";
+    if (highWater !== null && releaseAtOrAbove(highWater, requiredSince)) {
+        return (`  ${f.label} at ${f.path}: ${sessions} session archive(s) have no session-meta cell, and the data root was last opened by server ${highWater}, which carries the one-time migration ` +
+            `(introduced in ${requiredSince}) that gives such an archive its row cell under the occupant token the archive already carries — but that start did not finish it ` +
+            `(${ARCHIVE_TOKEN_ADOPTION_PENDING_FILE} is still in the data root). ${consequence} ` +
+            `Start the root once with a release at or above ${highWater} that still carries that migration (server or run-local) and let that start finish, then start this build.`);
+    }
+    const lastOpened = highWater === null ? "no engine that records a high-water (run-local before 7.148.0, or a server before 7.144.0)" : `server ${highWater}`;
+    return (`  ${f.label} at ${f.path}: ${sessions} session archive(s) have no session-meta cell, and the data root was last opened by ${lastOpened} — older than ${requiredSince}, ` +
+        `whose one-time migration gives such an archive its row cell under the occupant token the archive already carries. ${consequence} ` +
+        `Start the root once with a release at or above ${requiredSince} that still carries that migration (server or run-local) and let that start finish, then start this build.`);
+}
 function describeLocalDataRootMismatch(findings, when) {
     const lines = [
         when === "boot"
@@ -200,7 +247,9 @@ function describeLocalDataRootMismatch(findings, when) {
     ];
     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 four 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;", "    (4) the data root skipped a required one-time migration, or a release carrying it opened the root and did not finish it (the finding names the release to start with): start the root once with a release at or above that one that still carries the migration (server or run-local), let that start finish, then start this build.", "The check behind this refusal only reads: the file(s) named above were left in place, unchanged.");
+    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 four 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;", "    (4) the data root skipped a required one-time migration, or a release carrying it opened the root and did not finish it (the finding names the release to start with): start the root once with a release at or above that one that still carries the migration (server or run-local), let that start finish, then start this build.", when === "boot"
+        ? "This refusal comes from the data-root admission, which only reads and runs before this start writes anything to the data root: the data root is exactly as it was — no file, directory, key or lock was created, changed or removed."
+        : "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 {
@@ -215,14 +264,11 @@ export class LocalDataRootSchemaMismatchError extends StoreBootRefusalError {
     }
 }
 export const ARCHIVE_TOKEN_ADOPTION_SINCE = "7.148.0";
-export function archiveTokenAdoptionCarried() {
-    return ONE_TIME_MIGRATIONS.some((w) => w.id === "M47");
-}
 const ARCHIVE_DIR = "sessions";
 const ARCHIVE_SUFFIX = ".jsonl";
 const ARCHIVE_TOKEN_ADOPTION_PENDING_FILE = "archive-token-adoption.pending";
 const archiveTokenAdoptionPendingPath = (root) => resolve(join(root, ARCHIVE_TOKEN_ADOPTION_PENDING_FILE));
-function archiveTokenAdoptionPendingPresent(root) {
+export function archiveTokenAdoptionPendingPresent(root) {
     try {
         lstatSync(archiveTokenAdoptionPendingPath(root));
         return true;
@@ -258,7 +304,7 @@ function dischargeArchiveTokenAdoptionPending(root) {
     if (!IS_WIN32)
         fsyncPaths(dirname(path));
 }
-function archiveIdsInSync(root) {
+export function archiveIdsInSync(root) {
     let names;
     try {
         names = readdirSync(join(root, ARCHIVE_DIR));
@@ -270,54 +316,78 @@ function archiveIdsInSync(root) {
     }
     return names.filter((name) => name.endsWith(ARCHIVE_SUFFIX)).map((name) => name.slice(0, -ARCHIVE_SUFFIX.length));
 }
-export function archiveIdsWithoutCellSync(root) {
-    const sidecarPath = resolve(join(root, SESSION_META_SIDECAR_FILE));
-    const label = `${SESSION_META_SIDECAR_FILE} (the local session-meta sidecar)`;
-    const raw = readDataRootFileTextSync(sidecarPath);
+function strictSidecarSite(root, entry) {
+    return { path: resolve(join(root, entry.file)), label: `${entry.file} (the local ${entry.which} sidecar)` };
+}
+export function readStrictSidecarTextsSync(root) {
+    return STRICT_SIDECARS.map((entry) => readDataRootFileTextSync(strictSidecarSite(root, entry).path));
+}
+function decodeStrictSidecar(root, entry, raw) {
+    const { path, label } = strictSidecarSite(root, entry);
+    if (raw.state === "absent")
+        return raw;
     if (raw.state === "unreadable")
-        throw new LocalDataRootSchemaMismatchError([dataRootMismatchOf(sidecarPath, label, raw.fault)], "boot");
-    let cells = {};
-    if (raw.state === "text") {
-        try {
-            cells = decodeJsonColumn(raw.text, readSessionMetaSidecar, label);
-        }
-        catch (e) {
-            throw new LocalDataRootSchemaMismatchError([dataRootMismatchOf(sidecarPath, label, e)], "boot");
-        }
+        return { state: "unreadable", finding: dataRootMismatchOf(path, label, raw.fault) };
+    try {
+        return { state: "read", entries: decodeJsonColumn(raw.text, readSessionMetaSidecarInWindow, label) };
     }
-    return archiveIdsInSync(root)
-        .filter((id) => !Object.hasOwn(cells, id))
-        .sort();
+    catch (e) {
+        return { state: "unreadable", finding: dataRootMismatchOf(path, label, e) };
+    }
+}
+export function readSessionMetaCellsSync(root) {
+    return decodeStrictSidecar(root, STRICT_SIDECARS[0], readDataRootFileTextSync(strictSidecarSite(root, STRICT_SIDECARS[0]).path));
 }
-export function holdArchiveTokenAdoptionDuty(root, priorHighWater, adoptionCarried) {
+export function judgeStrictSidecars(root, texts) {
+    const findings = [];
+    let sessionMeta = {};
+    STRICT_SIDECARS.forEach((entry, i) => {
+        const reading = decodeStrictSidecar(root, entry, texts[i] ?? { state: "absent" });
+        if (reading.state === "unreadable")
+            findings.push(reading.finding);
+        else if (reading.state === "read")
+            sessionMeta = reading.entries;
+    });
+    if (findings.length > 0)
+        throw new LocalDataRootSchemaMismatchError(findings, "boot");
+    return sessionMeta;
+}
+function cellLessArchiveIds(archiveIds, cells) {
+    return archiveIds.filter((id) => !Object.hasOwn(cells, id)).sort();
+}
+export function judgeArchiveTokenAdoptionDuty(root, priorHighWater, adoptionCarried, observed) {
     const since = releaseTriple(ARCHIVE_TOKEN_ADOPTION_SINCE);
     const neverOpenedByAdoptingRelease = priorHighWater === undefined || compareReleaseTriples(priorHighWater, since) < 0;
-    if (adoptionCarried) {
-        if (neverOpenedByAdoptingRelease && archiveIdsInSync(root).length > 0)
-            recordArchiveTokenAdoptionPending(root, priorHighWater);
-        return;
-    }
-    const owed = archiveTokenAdoptionPendingPresent(root);
+    if (adoptionCarried)
+        return neverOpenedByAdoptingRelease && observed.archiveIds.length > 0 ? "record" : "none";
+    const owed = observed.adoptionPending;
     if (!neverOpenedByAdoptingRelease && !owed)
-        return;
-    const cellLess = archiveIdsWithoutCellSync(root);
-    if (cellLess.length === 0) {
-        if (owed)
-            dischargeArchiveTokenAdoptionPending(root);
-        return;
-    }
+        return "none";
+    const cellLess = cellLessArchiveIds(observed.archiveIds, observed.cells);
+    if (cellLess.length === 0)
+        return owed ? "discharge" : "none";
     throw new LocalDataRootSchemaMismatchError([
         {
             path: resolve(join(root, ARCHIVE_DIR)),
             label: `${ARCHIVE_DIR} (the local session archives)`,
             problem: "skipped-required-migration",
             unknownFields: [],
-            skippedMigration: { highWater: priorHighWater === undefined ? null : releaseText(priorHighWater), requiredSince: ARCHIVE_TOKEN_ADOPTION_SINCE, sessions: cellLess.length },
+            skippedMigration: { residue: "archives-without-cell", highWater: priorHighWater === undefined ? null : releaseText(priorHighWater), requiredSince: ARCHIVE_TOKEN_ADOPTION_SINCE, sessions: cellLess.length },
         },
     ], "boot");
 }
+export function settleArchiveTokenAdoptionDuty(physicalRoot, priorHighWater, action) {
+    switch (action) {
+        case "none":
+            return;
+        case "record":
+            return recordArchiveTokenAdoptionPending(physicalRoot, priorHighWater);
+        case "discharge":
+            return dischargeArchiveTokenAdoptionPending(physicalRoot);
+    }
+}
 function firstCellIncarnationOf(sessionId, archiveToken) {
-    const token = archiveTokenAdoptionCarried() ? incarnationFromCell(sessionId, archiveToken, "absent") : undefined;
+    const token = migrationCarried("M47") ? incarnationFromCell(sessionId, archiveToken, "absent") : undefined;
     return token !== undefined ? { incarnation: token, adopted: true } : { incarnation: mintSessionIncarnation(), adopted: false };
 }
 function cellChangedUnderLock(sessionId) {
@@ -423,20 +493,6 @@ class SidecarMap {
         }
         return st.loaded;
     }
-    async reconcile() {
-        const path = this.path;
-        if (!path)
-            return;
-        const st = this.state;
-        if (st.refused !== undefined)
-            throw st.refused;
-        if (!st.loaded)
-            return this.ensureLoaded();
-        await st.loaded;
-        const disk = await this.readDisk(path);
-        if (disk.state === "unreadable")
-            throw this.refuse(path, disk);
-    }
     async landed(path, changed, draft) {
         const disk = await this.readDisk(path);
         switch (disk.state) {
@@ -656,7 +712,6 @@ export class LocalSessionStore {
     instructionSources;
     workspaces;
     meta;
-    strictSidecars = [];
     log;
     sessionWriteLocks;
     executionPlacement;
@@ -698,17 +753,15 @@ export class LocalSessionStore {
             }
             this.durability = opts.durability;
         }
-        const sidecar = (file, which, read, strict = false) => {
-            const map = new SidecarMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, read, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which), strict);
-            if (strict)
-                this.strictSidecars.push(map);
-            return map;
+        const sidecar = (file, which, read) => {
+            const strict = STRICT_SIDECAR_FILES.has(file);
+            return new SidecarMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, read, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which), strict);
         };
         this.titles = sidecar("session-titles.json", "title", readStringRecordColumn);
         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_META_SIDECAR_FILE, "session-meta", readSessionMetaSidecar, true);
+        this.meta = sidecar(SESSION_META_SIDECAR_FILE, "session-meta", readSessionMetaSidecar);
         const root = dataDir ? resolve(dataDir) : undefined;
         this.dataRoot = root;
         if (root !== undefined && !SESSION_WRITE_LOCKS_BY_ROOT.has(root))
@@ -738,16 +791,7 @@ export class LocalSessionStore {
         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;
-        }
+        const renamed = renameRetiredExecutionLaneWordsInCellsM40(disk.entries);
         if (renamed === 0)
             return 0;
         try {
@@ -758,19 +802,6 @@ export class LocalSessionStore {
         }
         return renamed;
     }
-    async assertStrictSidecarsReadable() {
-        const loads = await Promise.allSettled(this.strictSidecars.map((map) => map.reconcile()));
-        const findings = [];
-        for (const load of loads) {
-            if (load.status === "fulfilled")
-                continue;
-            if (!(load.reason instanceof LocalDataRootSchemaMismatchError))
-                throw load.reason;
-            findings.push(...load.reason.findings);
-        }
-        if (findings.length > 0)
-            throw new LocalDataRootSchemaMismatchError(findings, "boot");
-    }
     async forkingOf(sessionId, meta) {
         if (!isForkCreatedCell(meta))
             return false;
@@ -1027,7 +1058,7 @@ export class LocalSessionStore {
         return meta;
     }
     async firstCellIncarnationHeld(sessionId) {
-        const head = archiveTokenAdoptionCarried() ? await this.archiveHeadOf(sessionId) : undefined;
+        const head = migrationCarried("M47") ? await this.archiveHeadOf(sessionId) : undefined;
         return firstCellIncarnationOf(sessionId, head?.incarnation).incarnation;
     }
     async headOf(sessionId) {
@@ -2040,20 +2071,25 @@ export class LocalSessionStore {
         await this.meta.ensureLoaded();
         let cleared = 0;
         const committed = await this.meta.commit((draft) => {
-            cleared = 0;
-            for (const sessionId of [...draft.keys()]) {
-                const cell = draft.get(sessionId);
-                if (cell === undefined || typeof cell === "string" || cell.owner !== SHELL_SENTINEL_OWNER_M48 || readSessionMetaCell(cell).dropping)
-                    continue;
-                draft.set(sessionId, { ...cell, owner: null });
-                cleared += 1;
-            }
+            const hits = shellSentinelCellIdsM48(draft);
+            for (const sessionId of hits)
+                draft.set(sessionId, { ...cellObjectOf(draft.get(sessionId)), owner: null });
+            cleared = hits.length;
             return cleared > 0;
         }, "best-effort");
         if (!committed)
             throw new SessionError("storage", "LocalSessionStore: the one-time migration M48 could not write the session-meta cells it cleared of the shell sentinel owner durably — nothing was changed");
         return cleared;
     }
+    async countShellSentinelOwnersM48() {
+        await this.meta.ensureLoaded();
+        let count = 0;
+        await this.meta.commit((draft) => {
+            count = shellSentinelCellIdsM48(draft).length;
+            return false;
+        }, "best-effort");
+        return count;
+    }
     async adoptArchiveTokensM47() {
         const root = this.dataRoot;
         if (root === undefined)
@@ -2087,8 +2123,13 @@ export class LocalSessionStore {
         return { adopted, minted };
     }
     async assertArchiveTokensAdoptedM47(root) {
+        const reading = readSessionMetaCellsSync(root);
+        if (reading.state === "unreadable") {
+            throw new SessionError("storage", `LocalSessionStore: the one-time migration M47 cannot re-read ${reading.finding.label} to prove the adoption finished (${reading.finding.problem}) — refusing to start. ` +
+                `${ARCHIVE_TOKEN_ADOPTION_PENDING_FILE} stays in the data root; the next start of a release carrying this migration tries again.`);
+        }
         let left = 0;
-        for (const sessionId of archiveIdsWithoutCellSync(root))
+        for (const sessionId of cellLessArchiveIds(archiveIdsInSync(root), reading.state === "read" ? reading.entries : {}))
             if ((await this.adoptionScopeOf(sessionId)) === "in")
                 left += 1;
         if (left > 0) {

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

@@ -66,11 +66,15 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     withdrawRunsOf(sessionId: string, ownTaskId: string | undefined): "proceed" | {
         readonly keep: "runs";
     };
+    /** 撤回本请求铸的这一条 run(SQL / 文件孪生同判,律见 SQL 孪生头注):行上的持有腿不是 `legId` ⇒ 不是本腿的行,一个字节不动;是 ⇒ 行仍在跑 ⇒ 删事件、幂等键、行,放本行持有的认领;已终局 ⇒ 行零删、只放它上面的提交幂等键;停驻 ⇒ 一个字节不动。交回删没删。 */
+    withdrawMintedRun(taskId: string, legId: string): Promise<boolean>;
     /** Undo THIS submission's binding (key + body fingerprint → null) — called only where the submit surface refuses the submission
      *  before any work and terminalizes the row it just claimed (the sync leg's zero-work refusal, an execution-placement reject):
      *  the error answer invites a retry, and a retry with the same key must run, not replay the refusal. The row stays (it
      *  is the refusal's record); only the binding is freed. */
     releaseIdemKey(taskId: string): Promise<void>;
+    /** 放一条行上的提交幂等键绑定(`releaseIdemKey` 与 `withdrawMintedRun` 的非在跑臂同读)。 */
+    private dropIdemBinding;
     /** The body fingerprint this row's binding of `idem.key` holds — binding `idem.bodyFingerprint` first when it holds none (first
      *  arrival binds, everyone after reads; the twin of the SQL conditional UPDATE). `null` = no such row, or the row is not bound to
      *  this key (never written). */
@@ -95,15 +99,16 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     /** The terminal write's one synchronous section (SQL twin: one transaction): the k8s space's pending commit row (when
      *  offered) → the terminal row → the active-run slot release. Returns whether the pending row is now this run's. */
     private writeTerminal;
-    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard).
-     *  [ref]:同时落 `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.
-     *  [ref]:同 {@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>;
+    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS = 行仍归 `legId` ∧ running / suspended ∧ 没挂取消请求(三件的理由见 SQL 孪生)。
+     *  [ref]:同时落 `result` —— 封口脱敏后的投影(`sealRunRowResult`,凭据不落;`null` = 没观察到 park 结果),SQL 孪生同注。
+     *  交回 CAS 的答:`true` ⇔ 这一写之后行停在这个词上;`false` ⇔ 三件有一件不成立(或行不在)—— 写不动它。判与写同一个同步段。 */
+    setSuspended(taskId: string, result: PersistedTaskResult | null, legId: string): Promise<boolean>;
+    /** [ref] D-B: park NON-terminal `needs_review`, KEEP the claim. CAS = {@link setSuspended} 的三件(词换成 needs_review)。
+     *  [ref]:同 {@link setSuspended} 落封口脱敏后的 `result`;CAS 的答同 {@link setSuspended}。 */
+    setNeedsReview(taskId: string, result: PersistedTaskResult | null, legId: string): Promise<boolean>;
+    /** Durable F4 resume: flip suspended/needs_review → running (CAS);认领 = 换持有腿(铸新的 `legId` 交回)+ 两面请求旗随旧腿清零(SQL 孪生同注)。
+     *  [ref](codex R1 [medium]):认领 = 接管 `instanceId`(= 当前持有副本;SQL 孪生同注)。CAS 输不改、交回 `undefined`。 */
+    markResuming(taskId: string, instanceId: string): Promise<string | undefined>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     /** 认领当写栅栏用(契约 = `store-contracts.ts` 的 `InProcessClaimFence`):判、刷新活性与 `write` 是同一个同步段。 */
     whileHoldingClaim(sessionId: string, taskId: string, write: (run: FencedRun) => FenceLanded): boolean;

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

@@ -1,7 +1,7 @@
 import { redactErrorMessage, redactLedgerEventData, runRowErrorCodeOf, sealRunRowResult } from "../observability/run-terminal.js";
 import { outwardPlane } from "../terminal.js";
 import { projectUsageStats, USAGE_SCAN_LIMIT } from "../usage-analytics.js";
-import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, RUN_STALL_DEFAULT_WIRING, isTerminalRunStatus, runLivenessOf, settledLegObservationOf } from "./store-contracts.js";
+import { RUN_HOLDER_DEATH_CODES, RUN_STALLED_ERROR, RUN_STALL_DEFAULT_WIRING, isTerminalRunStatus, mintRunLegId, runLivenessOf, settledLegObservationOf } from "./store-contracts.js";
 import { buildSessionRunRollups } from "./session-run-rollup.js";
 import { notifyRunTerminal } from "../observability/run-terminal.js";
 import { createInProcessSpaceCommitTable, fenceSpaceCommitAtTerminal } from "../workspace-space-commit.js";
@@ -52,6 +52,7 @@ export class MemoryRunStore {
             source: r.source,
             identity: r.identity,
             instanceId: r.instanceId,
+            legId: r.legId,
             cancelRequested: r.cancelRequested,
             objectivePreview: r.objectivePreview,
             createdAt: r.createdAt.toISOString(),
@@ -74,6 +75,7 @@ export class MemoryRunStore {
         if (claimed !== undefined && !this.settleDueHolder(claimed))
             return { ok: false, activeTaskId: claimed };
         const now = new Date();
+        const legId = mintRunLegId();
         this.active.set(sessionId, taskId);
         this.runs.set(taskId, {
             taskId,
@@ -86,6 +88,7 @@ export class MemoryRunStore {
             jobId: meta.jobId ?? null,
             source: meta.source ?? null,
             instanceId,
+            legId,
             objectivePreview: meta.objectivePreview ?? null,
             idemKey,
             idemBodyFingerprint: meta.idem?.bodyFingerprint ?? null,
@@ -97,7 +100,7 @@ export class MemoryRunStore {
         });
         if (idemKey !== null)
             this.byIdem.set(idemKey, taskId);
-        return { ok: true };
+        return { ok: true, legId };
     }
     withdrawRunsOf(sessionId, ownTaskId) {
         for (const r of this.runs.values())
@@ -114,14 +117,33 @@ export class MemoryRunStore {
         this.runs.delete(own.taskId);
         return "proceed";
     }
+    async withdrawMintedRun(taskId, legId) {
+        const r = this.runs.get(taskId);
+        if (r === undefined || r.legId !== legId)
+            return false;
+        if (r.status !== "running") {
+            if (isTerminalRunStatus(r.status))
+                this.dropIdemBinding(r);
+            return false;
+        }
+        this.events.delete(taskId);
+        if (r.idemKey !== null && this.byIdem.get(r.idemKey) === taskId)
+            this.byIdem.delete(r.idemKey);
+        this.runs.delete(taskId);
+        if (this.active.get(r.sessionId) === taskId)
+            this.active.delete(r.sessionId);
+        return true;
+    }
     async releaseIdemKey(taskId) {
         const r = this.runs.get(taskId);
-        if (!r)
-            return;
+        if (r)
+            this.dropIdemBinding(r);
+    }
+    dropIdemBinding(r) {
         r.idemBodyFingerprint = null;
         if (r.idemKey === null)
             return;
-        if (this.byIdem.get(r.idemKey) === taskId)
+        if (this.byIdem.get(r.idemKey) === r.taskId)
             this.byIdem.delete(r.idemKey);
         r.idemKey = null;
     }
@@ -235,38 +257,42 @@ export class MemoryRunStore {
             notifyRunTerminal(pending);
         return fenced;
     }
-    async setSuspended(taskId, result) {
+    async setSuspended(taskId, result, legId) {
         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.errorCode = runRowErrorCodeOf(sealed);
-            r.updatedAt = new Date();
-        }
+        if (!r || r.legId !== legId || (r.status !== "running" && r.status !== "suspended") || r.cancelRequested)
+            return false;
+        r.status = "suspended";
+        r.result = sealed;
+        r.errorCode = runRowErrorCodeOf(sealed);
+        r.updatedAt = new Date();
+        return true;
     }
-    async setNeedsReview(taskId, result) {
+    async setNeedsReview(taskId, result, legId) {
         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.errorCode = runRowErrorCodeOf(sealed);
-            r.updatedAt = new Date();
-        }
+        if (!r || r.legId !== legId || (r.status !== "running" && r.status !== "needs_review") || r.cancelRequested)
+            return false;
+        r.status = "needs_review";
+        r.result = sealed;
+        r.errorCode = runRowErrorCodeOf(sealed);
+        r.updatedAt = new Date();
+        return true;
     }
     async markResuming(taskId, instanceId) {
         const r = this.runs.get(taskId);
         if (!r || (r.status !== "suspended" && r.status !== "needs_review"))
-            return false;
+            return undefined;
+        const legId = mintRunLegId();
         r.status = "running";
         r.result = null;
         r.errorCode = null;
         r.instanceId = instanceId;
+        r.legId = legId;
         r.cancelRequested = false;
         r.preemptRequested = false;
         r.updatedAt = new Date();
-        return true;
+        return legId;
     }
     async getActiveTaskId(sessionId) {
         return this.active.get(sessionId);
@@ -276,7 +302,7 @@ export class MemoryRunStore {
         if (this.active.get(sessionId) !== taskId || r === undefined || r.status !== "running")
             return false;
         r.updatedAt = new Date();
-        write({ instanceId: r.instanceId });
+        write({ instanceId: r.instanceId, legId: r.legId });
         return true;
     }
     async getRun(taskId) {

package/dist/plugins/one-time-migration-marker.d.ts

@@ -1,10 +1,26 @@
 /**
- * **一次性迁移的标记表**(SQL 两方言)—— 需要「这一库上这一条已经判过 / 落过」这一事实的迁移各在这里记一行(键 = 登记表里的那一条名,`plugins/one-time-migrations.ts`)。
- * 表由用到它的那一步自己建(不进中央建表语句:它随最后一条读它的迁移删码,库里留下的空表无人读,起服列册对账只核本树声明的表)。最后一条读它的迁移删码时,本文件一起删。
+ * **标记表**(SQL 两方言)—— 一库一行一事实,键 = 落它的那一条一次性迁移的名(`plugins/one-time-migrations.ts` 登记表)。两类行:
+ *  · **一次性的标记**:需要「这一库上这一条已经判过 / 落过」的迁移各记一行(M42 / M43 / M51),随那一条删码后无人再读(行留着无害);
+ *  · **常设的一行 —— `Skill` 豁免截点**({@link SKILL_EXEMPTION_CUTOFF_ID}):T0 = 一只按今天的意思读会话豁免行的构建第一次接管这只库的时刻。
+ *    首次放行早于它的引擎家 `Skill` 豁免行是更早的意思写下的(批准 = 激活某技能),读者 = 跳版拒启臂 `approval-exemption-skill-cutoff.ts`(无窗)与一次性迁移 M46(窗内删那些行)。
+ * 表是常设的:中央建表语句建它(`tidb-pool.ts` / `pg-pool.ts`),`ensureSchema()` 在建表之后落截点那一行(只在缺席时落 —— 「此刻这只库由知道今天读法的构建接管」)。
  */
 import type { SqlDialect } from "./sql-driver.js";
 /** 标记表名。 */
 export declare const MIGRATION_MARKER_TABLE = "one_time_migration_marker";
-/** 标记表的建表句(两方言;幂等)。 */
+/**
+ * 常设的那一行的键:`Skill` 豁免截点 T0(`marked_at_ms` = T0 的 epoch 毫秒)。键沿用第一个落它的一次性迁移 M46 的名 —— 7.148.0 起的库里已经是这一行,
+ * 改名就要再迁一次;M46 删码之后这一行照旧是截点的家。
+ */
+export declare const SKILL_EXEMPTION_CUTOFF_ID = "M46";
+/**
+ * 标记表的建表句(两方言;幂等)。中央建表语句与一次性迁移的步骤读同一只。键列与中央各表同形钉二进制排序(MySQL 协议表级 `COLLATE utf8mb4_bin`、PG 列级 `"C"`),
+ * 不继承库的缺省排序;7.148.0 由迁移建下的那一张(MySQL 协议上没钉表级排序)`IF NOT EXISTS` 不动它 —— 键是固定的 ASCII 迁移名,列册对账不看排序规则。
+ */
 export declare function migrationMarkerDdl(dialect: SqlDialect): string;
+/**
+ * 落一行标记、只在缺席时落(两方言;参数 `[键, 毫秒]`;已在 ⇒ 零改动,先落的那一只赢 —— 并发起服收敛到同一个值)。本表唯一的写句:
+ * `ensureSchema()` 的截点种子行与一次性迁移的各步同读这一只。
+ */
+export declare function markIfAbsentSql(dialect: SqlDialect): string;
 //# sourceMappingURL=one-time-migration-marker.d.ts.map