@sema-agent/server 7.140.0 → 7.142.0

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

@@ -1,13 +1,21 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isDeepStrictEqual } from "node:util";
+import { dirname, join, resolve } from "node:path";
 import { assertFirstOwnerWritable, forkOwnerOf, importerOwnerOf } from "./session-ownership.js";
-import { FileSessionRepo, SessionError, StoredSession, sessionLogMarkOf, settledForkOptions, validateEntriesForImport } from "@sema-agent/core";
+import { StampedSessionArchiveError, sessionUnreadableOf } from "../session-error-wire.js";
+import { FileSessionRepo, SessionError, StoredSession, admitSessionPlacement, atomicWriteFile, sessionLogMarkOf, settledForkOptions, uuidv7, validateEntriesForImport } from "@sema-agent/core";
+import { createPlacedSessionRow, sourceFacesVia } from "../delegated-session-owner.js";
+import { placementCapabilityOf } from "./session-placement.js";
 import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
+import { StoreBootRefusalError } from "./store-contracts.js";
 import { judgeSessionRowWrite, sessionRowTagKey, settleSessionRowWrite, } from "../session-row.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
 import { createZodColumnReader, decodeJsonColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
 import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./one-time-migrations.js";
+import { recordFailOpen } from "../observability/fail-open.js";
 import { createLogger } from "../observability/logger.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { UnreadableLeaf, carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
@@ -73,12 +81,44 @@ const SIDECAR_DEGRADES = { lastActivity: "recency", title: "title", pinned: "pin
 const readPinnedSidecar = createZodColumnReader(z.record(z.string(), z.literal(true)));
 const MIRROR_CELL = { role: "mirror" };
 function readSessionMetaCell(cell) {
-    return typeof cell === "string" ? { incarnation: cell, owner: undefined, execution: undefined, forkKey: undefined } : { incarnation: cell.incarnation, owner: cell.owner, execution: cell.execution, forkKey: cell.forkKey };
+    return typeof cell === "string"
+        ? { incarnation: cell, owner: undefined, execution: undefined, forkKey: undefined, createdAt: undefined, forkedFrom: undefined }
+        : { incarnation: cell.incarnation, owner: cell.owner, execution: cell.execution, forkKey: cell.forkKey, createdAt: cell.createdAt, forkedFrom: cell.forkedFrom };
 }
 const ownerRecorded = (cell) => cell !== undefined && readSessionMetaCell(cell).owner !== undefined;
+const cellObjectOf = (cell) => (typeof cell === "string" ? { incarnation: cell } : cell);
 function cellWith(before, bits) {
-    const base = typeof before === "string" ? { incarnation: before } : before;
-    return { ...base, ...("owner" in bits ? { owner: bits.owner } : {}), ...(bits.execution !== undefined ? { execution: bits.execution } : {}) };
+    return { ...cellObjectOf(before), ...("owner" in bits ? { owner: bits.owner } : {}), ...(bits.execution !== undefined ? { execution: bits.execution } : {}) };
+}
+const rowBornNow = () => new Date().toISOString();
+function archivedRowFactsOf(head) {
+    const createdAt = head.createdAt;
+    const forkedFrom = head.forkedFrom;
+    return {
+        createdAt: typeof createdAt === "string" && createdAt !== "" ? createdAt : ROW_CREATED_AT_ABSENT,
+        ...(typeof forkedFrom === "string" && forkedFrom !== "" ? { forkedFrom } : {}),
+    };
+}
+function rowFactsFilled(before, facts) {
+    if (before === undefined)
+        return { incarnation: mintSessionIncarnation(), createdAt: facts.createdAt, ...(facts.forkedFrom !== undefined ? { forkedFrom: facts.forkedFrom } : {}) };
+    const held = cellObjectOf(before);
+    const add = {
+        ...(held.createdAt === undefined ? { createdAt: facts.createdAt } : {}),
+        ...(held.forkedFrom === undefined && facts.forkedFrom !== undefined ? { forkedFrom: facts.forkedFrom } : {}),
+    };
+    return Object.keys(add).length === 0 ? undefined : { ...held, ...add };
+}
+const ROW_CREATED_AT_ABSENT = new Date(0).toISOString();
+function rowCreatedAtOf(sessionId, meta) {
+    if (meta?.createdAt !== undefined)
+        return meta.createdAt;
+    recordFailOpen("server.local-session-row.created-at-absent", `session=${sessionId}`);
+    return ROW_CREATED_AT_ABSENT;
+}
+function rowMetadataOf(sessionId, meta) {
+    const face = sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation);
+    return { id: sessionId, createdAt: rowCreatedAtOf(sessionId, meta), owner: face.owner, incarnation: face.incarnation, ...(meta.forkedFrom !== undefined ? { forkedFrom: meta.forkedFrom } : {}) };
 }
 const isForkCreatedCell = (meta) => meta !== undefined && meta.forkKey !== undefined && meta.execution === undefined;
 function readingOfCell(sessionId, meta, forking) {
@@ -88,7 +128,17 @@ const LOCAL_EXECUTION_CELL = z.discriminatedUnion("role", [
     z.object({ role: z.literal("writer"), lane: z.custom((v) => typeof v === "string" && isExecutionLane(v), { message: "not an execution lane" }) }).strict(),
     z.object({ role: z.literal("mirror") }).strict(),
 ]);
-const SESSION_META_SIDECAR = z.record(z.string(), z.union([z.string(), z.object({ incarnation: z.string(), owner: z.string().nullable().optional(), execution: LOCAL_EXECUTION_CELL.optional(), forkKey: z.string().optional() }).strict()]));
+export const SESSION_META_CELL_OBJECT = z
+    .object({
+    incarnation: z.string(),
+    owner: z.string().nullable().optional(),
+    execution: LOCAL_EXECUTION_CELL.optional(),
+    forkKey: z.string().optional(),
+    createdAt: z.string().optional(),
+    forkedFrom: z.string().optional(),
+})
+    .strict();
+const SESSION_META_SIDECAR = z.record(z.string(), z.union([z.string(), SESSION_META_CELL_OBJECT]));
 const readSessionMetaSidecar = createZodColumnReader(SESSION_META_SIDECAR);
 function ownerClaimWindowOpen() {
     const window = ONE_TIME_MIGRATIONS.find((w) => w.id === "M10");
@@ -153,6 +203,12 @@ class SidecarMap {
     persist() {
         return this.commit(() => true);
     }
+    syncToDisk() {
+        const path = this.path;
+        if (!path || !existsSync(path))
+            return;
+        fsyncPaths(path, dirname(path));
+    }
     deleteKey(key) {
         return this.commit((draft) => draft.delete(key));
     }
@@ -189,32 +245,116 @@ class SidecarMap {
         return link;
     }
 }
+const archiveRewriteReadScope = new AsyncLocalStorage();
+function noteReplayInArchiveRewriteRead(info) {
+    if (info.kind !== "replay")
+        return;
+    const scope = archiveRewriteReadScope.getStore();
+    if (scope !== undefined)
+        scope.dropped += info.dropped;
+}
 export function createLocalSessionRepo(root) {
     return new FileSessionRepo(root, {
-        onCorruptRead: createCorruptReadFailOpenSeat("server.session-repo.corrupt-record-skipped", noteReplayInSessionOpenScope),
+        onCorruptRead: createCorruptReadFailOpenSeat("server.session-repo.corrupt-record-skipped", (info) => {
+            noteReplayInSessionOpenScope(info);
+            noteReplayInArchiveRewriteRead(info);
+        }),
     });
 }
-function occupiedBy(session, incarnation) {
+function occupiedBy(session, row) {
     const storage = session.getStorage();
     const view = new Proxy(storage, {
         get(target, prop) {
             if (prop === "getMetadata")
-                return async () => occupantMetadata(await target.getMetadata(), incarnation);
+                return async () => ({ ...archiveKeysBesideRowFacts(await target.getMetadata()), ...row });
             const value = Reflect.get(target, prop, target);
             return typeof value === "function" ? value.bind(target) : value;
         },
     });
     return new StoredSession(view);
 }
-function occupantMetadata(meta, incarnation) {
-    const { forkedFromIncarnation: _notThisStoresToken, ...rest } = meta;
-    return { ...rest, incarnation };
+function archiveKeysBesideRowFacts(meta) {
+    const { id: _id, createdAt: _createdAt, owner: _owner, incarnation: _incarnation, forkedFrom: _forkedFrom, forkedFromIncarnation: _notThisStoresToken, ...rest } = meta;
+    return rest;
+}
+export const LOCAL_ARCHIVE_SNAPSHOT_DIR = "session-archive-m33";
+export class LocalArchiveSnapshotsPresentError extends StoreBootRefusalError {
+    dir;
+    names;
+    code = "config.local_archive_snapshot_present";
+    constructor(dir, names, detail) {
+        super(`config.local_archive_snapshot_present: ${names.length > 0 ? `the local data root holds ${names.length} session archive snapshot file(s) in ${dir} (${names.slice(0, 8).join(", ")}${names.length > 8 ? ", …" : ""})` : `the local data root's session archive snapshot directory ${dir} could not be read`}` +
+            `${detail !== undefined ? ` — ${detail}` : ""} — refusing to start. Each snapshot is a copy of one session's conversation that an interrupted one-time migration (M33) wrote ` +
+            "before rewriting that session's stored archive: the archive may have been lost in that interruption and its content may be only in the snapshot, and nothing else reads or " +
+            "deletes these copies (deleting the session would leave them behind). Ways out: start a server version that carries the one-time migration M33 once — it restores or discards " +
+            "each snapshot on boot and names any it cannot; or, after checking that every session named here has its archive under the data root's sessions/ directory " +
+            "(restore it from the snapshot's entries otherwise), delete the snapshot directory.");
+        this.dir = dir;
+        this.names = names;
+        this.name = "LocalArchiveSnapshotsPresentError";
+    }
+}
+function fsyncPaths(...paths) {
+    for (const target of paths) {
+        const fd = openSync(target, "r");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+}
+function namesIn(dir) {
+    try {
+        return readdirSync(dir).sort();
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return [];
+        throw e;
+    }
+}
+const errnoOf = (e) => {
+    const code = e?.code;
+    return typeof code === "string" ? code : undefined;
+};
+const unreadableDirDetail = (e) => `reading the directory failed (${e?.code ?? (e instanceof Error ? e.message : String(e))})`;
+export function assertNoArchiveSnapshots(dir) {
+    let names;
+    try {
+        names = namesIn(dir);
+    }
+    catch (e) {
+        throw new LocalArchiveSnapshotsPresentError(dir, [], unreadableDirDetail(e));
+    }
+    if (names.length > 0)
+        throw new LocalArchiveSnapshotsPresentError(dir, names);
+}
+const ARCHIVE_SNAPSHOT_RECORD = z
+    .object({
+    id: z.string(),
+    archiveIncarnation: z.string().nullable(),
+    rowFacts: z.object({ createdAt: z.string(), forkedFrom: z.string().optional() }).strict(),
+    entries: z.array(z.custom((v) => typeof v === "object" && v !== null && !Array.isArray(v), { message: "not an entry object" })),
+})
+    .strict();
+const readArchiveSnapshotRecord = createZodColumnReader(ARCHIVE_SNAPSHOT_RECORD);
+function sameLog(a, b) {
+    return isDeepStrictEqual(a, b);
 }
 export class LocalSessionStore {
     repo;
     runs;
     retention = UNMANAGED_RETENTION;
+    durability;
+    placements;
+    placementOf;
+    listPlaced;
+    claimOwnerless;
+    recordedPlacementOf;
     pending = new Map();
+    rowsDropped = new Set();
     lastActivity = new Map();
     stagings = new Map();
     loaded;
@@ -233,11 +373,42 @@ export class LocalSessionStore {
     sessionWriteLocks;
     executionPlacement;
     executionPlacementBackfill;
+    dataRoot;
+    archiveSnapshotsSettled = 0;
     constructor(repo, runs, dataDir, opts) {
         this.repo = repo;
         this.runs = runs;
         this.sidecarPath = dataDir ? join(dataDir, "session-last-activity.json") : undefined;
         this.log = opts?.log ?? createLogger();
+        const repoPlacementOf = repo.placementOf;
+        const repoListPlaced = repo.listPlaced;
+        if ((typeof repoPlacementOf === "function") !== (typeof repoListPlaced === "function")) {
+            throw new Error("LocalSessionStore: the session repo answers only one of placementOf / listPlaced — a repo that records placements answers both");
+        }
+        if (typeof repoPlacementOf === "function" && typeof repoListPlaced === "function") {
+            this.recordedPlacementOf = (sessionId) => repoPlacementOf.call(repo, sessionId);
+            this.placementOf = this.recordedPlacementOf;
+            this.listPlaced = (kind, o) => repoListPlaced.call(repo, kind, o);
+            this.claimOwnerless = (sessionId, incarnation, owner) => this.claimOwnerlessPlaced(sessionId, incarnation, owner);
+        }
+        else {
+            this.recordedPlacementOf = async () => undefined;
+        }
+        if (opts?.placements !== undefined) {
+            if (this.placementOf === undefined) {
+                throw new Error("LocalSessionStore: declares a subagent placement partition over a session repo that cannot record placements (no placementOf / listPlaced) — the declaration would be a promise this store cannot keep");
+            }
+            if (opts.placements.subagent?.durability === "durable" && dataDir === undefined) {
+                throw new Error("LocalSessionStore: declares durable placed transcripts without a data dir — their owner and incarnation cells would not survive a restart");
+            }
+            this.placements = opts.placements;
+        }
+        if (opts?.durability !== undefined) {
+            if (opts.durability === "durable" && dataDir === undefined) {
+                throw new Error("LocalSessionStore: declares durable sessions without a data dir — the owner and incarnation cells would not survive a restart");
+            }
+            this.durability = opts.durability;
+        }
         const sidecar = (file, which, read, strict = false) => 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);
@@ -245,6 +416,7 @@ export class LocalSessionStore {
         this.workspaces = sidecar("session-workspaces.json", "workspace", readStringRecordColumn);
         this.meta = sidecar("session-incarnations.json", "session-meta", readSessionMetaSidecar, true);
         const root = dataDir ? resolve(dataDir) : undefined;
+        this.dataRoot = root;
         if (root !== undefined && !SESSION_WRITE_LOCKS_BY_ROOT.has(root))
             SESSION_WRITE_LOCKS_BY_ROOT.set(root, new Map());
         this.sessionWriteLocks = root !== undefined ? SESSION_WRITE_LOCKS_BY_ROOT.get(root) : new Map();
@@ -278,6 +450,11 @@ export class LocalSessionStore {
             return read;
         if (read.state === "absent")
             return undefined;
+        const partition = await this.placementProbe(sessionId);
+        if (partition.state === "placed")
+            return undefined;
+        if (partition.state === "unusable" && partition.word === "storage")
+            return partition;
         const forking = await this.forkingRead(sessionId, read.meta);
         return typeof forking === "boolean" ? readingOfCell(sessionId, read.meta, forking) : forking;
     }
@@ -308,12 +485,13 @@ export class LocalSessionStore {
     }
     async settleExecutionHeld(sessionId, judge) {
         await this.meta.ensureLoaded();
-        const forking = await this.forkingOf(sessionId, this.metaCellOf(sessionId));
+        const placed = await this.isPlacedRow(sessionId);
+        const forking = !placed && (await this.forkingOf(sessionId, this.metaCellOf(sessionId)));
         let settled;
         let fault;
         await this.writeMeta(sessionId, (before) => {
             try {
-                settled = judge(before === undefined ? undefined : readingOfCell(sessionId, readSessionMetaCell(before), forking));
+                settled = judge(before === undefined || placed ? undefined : readingOfCell(sessionId, readSessionMetaCell(before), forking));
             }
             catch (e) {
                 fault = e;
@@ -372,6 +550,34 @@ export class LocalSessionStore {
             return word === "absent" ? { state: "absent" } : unusableArchiveOf(word, e);
         }
     }
+    async placementProbe(sessionId) {
+        try {
+            const record = await this.recordedPlacementOf(sessionId);
+            return record === undefined ? { state: "ordinary" } : { state: "placed", record };
+        }
+        catch (e) {
+            const word = e instanceof SessionError ? archiveFaultWord(e.code) : "storage";
+            return word === "absent" ? { state: "ordinary" } : unusableArchiveOf(word, e);
+        }
+    }
+    async placedRecordOf(sessionId) {
+        const probe = await this.placementProbe(sessionId);
+        if (probe.state === "unusable") {
+            if (probe.word === "storage")
+                throw probe.fault;
+            return undefined;
+        }
+        return probe.state === "placed" ? probe.record : undefined;
+    }
+    async isPlacedRow(sessionId) {
+        return (await this.placedRecordOf(sessionId)) !== undefined;
+    }
+    async placedRecordOrThrow(sessionId) {
+        const probe = await this.placementProbe(sessionId);
+        if (probe.state === "unusable")
+            throw probe.fault;
+        return probe.state === "placed" ? probe.record : undefined;
+    }
     async existsInRepo(sessionId) {
         const probe = await this.probeArchive(sessionId);
         if (probe.state === "unusable")
@@ -399,7 +605,7 @@ export class LocalSessionStore {
     }
     async cellOfPresent(sessionId) {
         if (!this.meta.state.entries.has(sessionId))
-            await this.writeMeta(sessionId, (before) => (before === undefined ? { incarnation: mintSessionIncarnation() } : undefined));
+            await this.writeMeta(sessionId, (before) => (before === undefined && !this.rowsDropped.has(sessionId) ? { incarnation: mintSessionIncarnation() } : undefined));
         const cell = this.meta.state.entries.get(sessionId);
         return cell === undefined ? undefined : readSessionMetaCell(cell);
     }
@@ -407,18 +613,25 @@ export class LocalSessionStore {
         const before = await this.metaOf(sessionId);
         if (before === undefined)
             return undefined;
-        const leaf = await this.repo.headOf(sessionId).then((archive) => archive?.leafId ?? null, (fault) => new UnreadableLeaf(fault));
+        const leaf = await this.archiveHeadOf(sessionId).then((archive) => archive?.leafId ?? null, (fault) => new UnreadableLeaf(fault));
         const cell = this.meta.state.entries.get(sessionId);
         const after = cell === undefined ? undefined : readSessionMetaCell(cell);
         if (after === undefined || after.incarnation !== before.incarnation || (after.owner ?? null) !== (before.owner ?? null))
             return undefined;
         return headFromRow(sessionId, before.owner ?? null, before.incarnation, leaf);
     }
+    archiveHeadOf(sessionId) {
+        return this.repo.headOf(sessionId);
+    }
     async handOut(sessionId, session) {
         const meta = await this.cellOfPresent(sessionId);
         if (meta === undefined)
             throw new SessionError("storage", `LocalSessionStore: session ${sessionId} lost its session-meta cell while it was being handed out`);
-        return { session: occupiedBy(session, sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation).incarnation), sessionId };
+        return { session: occupiedBy(session, rowMetadataOf(sessionId, meta)), sessionId };
+    }
+    async sessionMetadataOf(sessionId) {
+        const meta = await this.metaOf(sessionId);
+        return meta === undefined ? undefined : rowMetadataOf(sessionId, meta);
     }
     async probeTitle(sessionId) {
         await this.titles.ensureLoaded();
@@ -464,7 +677,7 @@ export class LocalSessionStore {
     }
     async lockedRowOf(sessionId) {
         const meta = this.metaCellOf(sessionId);
-        if (meta === undefined || (await this.listedMeta(sessionId)) === undefined)
+        if (meta === undefined || (await this.rowHeaderOf(sessionId)) === undefined)
             return undefined;
         return { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent"), placed: false, mirror: meta.execution?.role === "mirror", cells: this.rowCellsOf(sessionId) };
     }
@@ -500,19 +713,62 @@ export class LocalSessionStore {
     }
     async listRowOf(sessionId) {
         await this.loadRowSidecars();
-        const listed = await this.listedMeta(sessionId);
+        const header = await this.rowHeaderOf(sessionId);
         const meta = this.metaCellOf(sessionId);
-        if (listed === undefined || meta === undefined)
+        if (header === undefined || meta === undefined)
             return undefined;
-        return { row: await this.summaryOf(listed, await this.runRollups()), occupant: { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent") } };
+        return { row: await this.summaryOf(await this.listedRowOf(header), await this.runRollups()), occupant: { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent") } };
     }
     async sessionSummaryOf(sessionId) {
         await this.loadRowSidecars();
-        const meta = await this.listedMeta(sessionId);
-        return meta === undefined ? undefined : this.summaryOf(meta, await this.runRollups());
+        const header = await this.rowHeaderOf(sessionId);
+        return header === undefined ? undefined : this.summaryOf(await this.listedRowOf(header), await this.runRollups());
+    }
+    async rowHeaders() {
+        await this.meta.ensureLoaded();
+        const listed = await this.repo.list();
+        const listedIds = new Set(listed.map((row) => row.id));
+        const placed = this.createPlacedIdsReader();
+        const rows = listed.map((header) => ({ sessionId: header.id, header }));
+        for (const id of [...this.meta.state.entries.keys()].sort()) {
+            if (listedIds.has(id))
+                continue;
+            const row = await this.headerUnreadableRowOf(id, placed);
+            if (row !== undefined)
+                rows.push(row);
+        }
+        return rows;
+    }
+    async rowHeaderOf(sessionId) {
+        await this.meta.ensureLoaded();
+        const header = (await this.repo.list()).find((m) => m.id === sessionId);
+        if (header !== undefined)
+            return { sessionId, header };
+        return this.meta.state.entries.has(sessionId) ? this.headerUnreadableRowOf(sessionId, this.createPlacedIdsReader()) : undefined;
+    }
+    async headerUnreadableRowOf(sessionId, placed) {
+        try {
+            await this.archiveHeadOf(sessionId);
+            return undefined;
+        }
+        catch (fault) {
+            return (await placed()).has(sessionId) ? undefined : { sessionId, headerFault: fault };
+        }
+    }
+    createPlacedIdsReader() {
+        let ids;
+        return () => (ids ??= (async () => new Set((await this.listPlaced?.("subagent"))?.map((row) => row.sessionId) ?? []))());
     }
-    async listedMeta(sessionId) {
-        return (await this.repo.list()).find((m) => m.id === sessionId);
+    async listedRowOf(row) {
+        if ("headerFault" in row)
+            return { sessionId: row.sessionId, unreadable: row.headerFault };
+        try {
+            await this.archiveHeadOf(row.sessionId);
+            return { sessionId: row.sessionId, readable: row.header };
+        }
+        catch (fault) {
+            return { sessionId: row.sessionId, unreadable: fault };
+        }
     }
     async readInstructionSource(sessionId) {
         await this.instructionSources.ensureLoaded();
@@ -618,26 +874,34 @@ export class LocalSessionStore {
         console.warn(`LocalSessionStore: ${which} sidecar ${op} failed (${SIDECAR_DEGRADES[which]} persistence degraded): ${e instanceof Error ? e.message : String(e)}`);
     }
     async acquire(sessionId, opts) {
+        if (!sessionId && this.declaredPlacement(opts) !== undefined)
+            return this.load(uuidv7(), false, opts);
         if (!sessionId) {
             await this.meta.ensureLoaded();
             const session = await this.repo.create({});
             const id = (await session.getMetadata()).id;
-            await this.writeMeta(id, () => ({ incarnation: mintSessionIncarnation(), owner: null }));
+            await this.writeMeta(id, () => ({ incarnation: mintSessionIncarnation(), owner: null, createdAt: rowBornNow() }));
             return this.handOut(id, session);
         }
         if (opts?.requireExisting)
-            return this.load(sessionId, true);
+            return this.load(sessionId, true, opts);
         const inflight = this.pending.get(sessionId);
-        if (inflight)
-            return inflight;
-        const p = this.load(sessionId).finally(() => this.pending.delete(sessionId));
+        if (inflight) {
+            const acquired = await inflight;
+            admitSessionPlacement(sessionId, await this.recordedPlacementOf(sessionId), opts ?? {}, placementCapabilityOf(this));
+            return acquired;
+        }
+        const p = this.load(sessionId, false, opts).finally(() => this.pending.delete(sessionId));
         this.pending.set(sessionId, p);
         return p;
     }
-    async load(sessionId, requireExisting = false) {
+    declaredPlacement(opts) {
+        return this.placements !== undefined && opts?.requireExisting !== true ? opts?.placement : undefined;
+    }
+    async load(sessionId, requireExisting = false, opts) {
         return this.withSessionWriteLock(sessionId, async () => {
             try {
-                return await this.openForItselfHeld(sessionId);
+                return await this.openForItselfHeld(sessionId, opts);
             }
             catch (e) {
                 if (!isNotFound(e))
@@ -648,14 +912,34 @@ export class LocalSessionStore {
             await this.meta.ensureLoaded();
             if (isForkCreatedCell(this.metaCellOf(sessionId)))
                 throw new SessionForkInProgressError(sessionId);
+            const placement = this.declaredPlacement(opts);
+            if (placement !== undefined)
+                return this.createPlacedHeld(sessionId, placement, opts ?? {});
             const session = await this.repo.create({ id: sessionId });
-            await this.writeMeta(sessionId, (before) => ({ incarnation: mintSessionIncarnation(), owner: before !== undefined && ownerRecorded(before) ? (readSessionMetaCell(before).owner ?? null) : null }));
+            await this.writeMeta(sessionId, (before) => ({ incarnation: mintSessionIncarnation(), owner: before !== undefined && ownerRecorded(before) ? (readSessionMetaCell(before).owner ?? null) : null, createdAt: rowBornNow() }));
             return this.handOut(sessionId, session);
         });
     }
-    async openForItselfHeld(sessionId) {
+    async openForItselfHeld(sessionId, opts) {
         await this.meta.ensureLoaded();
         const session = await openSessionForItself(sessionId, () => this.repo.open({ id: sessionId, createdAt: "" }));
+        admitSessionPlacement(sessionId, (await session.getMetadata()).placement, opts ?? {}, placementCapabilityOf(this));
+        return this.handOut(sessionId, session);
+    }
+    async createPlacedHeld(sessionId, placement, opts) {
+        if (this.metaCellOf(sessionId) !== undefined) {
+            throw new SessionError("placement_refused", `session ${sessionId} is already registered as an ordinary session — refusing to create a subagent transcript on its id`);
+        }
+        let session;
+        await createPlacedSessionRow(sessionId, placement, {
+            readFaces: sourceFacesVia((id) => this.headOf(id)),
+            insert: async (owner) => {
+                session = await this.repo.create({ id: sessionId, placement });
+                await this.writeMeta(sessionId, (before) => (before === undefined ? { incarnation: mintSessionIncarnation(), owner, createdAt: rowBornNow() } : undefined));
+            },
+            readOwner: async () => (await this.headOf(sessionId))?.owner,
+        }, this.log);
+        admitSessionPlacement(sessionId, (await session.getMetadata()).placement, opts, placementCapabilityOf(this));
         return this.handOut(sessionId, session);
     }
     async register(sessionId, owner) {
@@ -667,14 +951,14 @@ export class LocalSessionStore {
             const existed = await this.existsInRepo(sessionId);
             if (!existed && isForkCreatedCell(this.metaCellOf(sessionId)))
                 throw new SessionForkInProgressError(sessionId);
-            const claim = existed && owner !== null && ownerClaimWindowOpen();
+            const claim = existed && owner !== null && ownerClaimWindowOpen() && !(await this.isPlacedRow(sessionId));
             const wrote = await this.writeMeta(sessionId, (before) => {
                 if (ownerRecorded(before))
                     return undefined;
                 if (claim)
                     return before === undefined ? { incarnation: mintSessionIncarnation(), owner } : cellWith(before, { owner });
                 if (!existed)
-                    return { incarnation: mintSessionIncarnation(), owner };
+                    return { incarnation: mintSessionIncarnation(), owner, createdAt: rowBornNow() };
                 return before === undefined ? { incarnation: mintSessionIncarnation() } : undefined;
             });
             if (!existed && wrote)
@@ -689,17 +973,39 @@ export class LocalSessionStore {
     }
     async release(sessionId) {
         this.pending.delete(sessionId);
+        await this.withSessionWriteLock(sessionId, async () => {
+            if ((await this.placedRecordOrThrow(sessionId)) === undefined)
+                return;
+            await this.dropRowHeld(sessionId);
+            await this.repo.delete({ id: sessionId, createdAt: "" });
+        });
+    }
+    async claimOwnerlessPlaced(sessionId, incarnation, owner) {
+        return this.withSessionWriteLock(sessionId, async () => {
+            if ((await this.placedRecordOrThrow(sessionId)) === undefined)
+                return false;
+            return this.writeMeta(sessionId, (before) => {
+                if (before === undefined)
+                    return undefined;
+                const cell = readSessionMetaCell(before);
+                if (cell.incarnation !== incarnation || (cell.owner ?? null) !== null)
+                    return undefined;
+                return cellWith(before, { owner });
+            });
+        });
     }
     async listSessions(opts) {
         await this.loadRowSidecars();
-        const metas = await this.repo.list();
+        const rows = [];
+        for (const header of await this.rowHeaders())
+            rows.push(await this.listedRowOf(header));
         const rollups = await this.runRollups();
         const all = [];
-        for (const meta of metas) {
-            const owner = this.ownerCellOf(meta.id);
+        for (const row of rows) {
+            const owner = this.ownerCellOf(row.sessionId);
             if (opts.owner !== undefined && owner !== opts.owner && !(opts.includeUnowned === true && owner === null))
                 continue;
-            all.push(await this.summaryOf(meta, rollups));
+            all.push(await this.summaryOf(row, rollups));
         }
         const qlc = opts.q?.toLowerCase();
         const filtered = qlc ? all.filter((r) => r.objectivePreview?.toLowerCase().includes(qlc)) : all;
@@ -722,23 +1028,25 @@ export class LocalSessionStore {
         const cell = this.meta.state.entries.get(sessionId);
         return cell === undefined ? null : (readSessionMetaCell(cell).owner ?? null);
     }
-    async summaryOf(meta, rollups) {
-        const firstActivityAt = meta.createdAt || new Date(0).toISOString();
-        const owner = this.ownerCellOf(meta.id);
-        const cells = this.rowCellsOf(meta.id);
-        const rowTag = this.rowTagKeyOf(meta.id, owner, cells);
-        const lastActivityAt = this.lastActivity.get(meta.id) ?? firstActivityAt;
-        const objectivePreview = await this.previewOf(meta);
+    async summaryOf(listed, rollups) {
+        const { sessionId } = listed;
+        const firstActivityAt = rowCreatedAtOf(sessionId, this.metaCellOf(sessionId));
+        const owner = this.ownerCellOf(sessionId);
+        const cells = this.rowCellsOf(sessionId);
+        const rowTag = this.rowTagKeyOf(sessionId, owner, cells);
+        const lastActivityAt = this.lastActivity.get(sessionId) ?? firstActivityAt;
+        const objectivePreview = "readable" in listed ? await this.previewOf(listed.readable) : null;
         return {
-            sessionId: meta.id,
+            sessionId,
             owner,
             lastActivityAt,
             firstActivityAt,
             objectivePreview,
-            ...this.runProjectionOf(meta.id, rollups),
+            ...this.runProjectionOf(sessionId, rollups),
             title: cells.title,
             pinned: cells.pinned,
             ...rowTag,
+            ...("unreadable" in listed ? { unreadable: sessionUnreadableOf(listed.unreadable) } : {}),
         };
     }
     rowTagKeyOf(sessionId, owner, cells) {
@@ -782,21 +1090,26 @@ export class LocalSessionStore {
     }
     async forkToHeld(sourceId, owner, target) {
         const sourceMeta = { id: sourceId, createdAt: "" };
-        let forkOptions;
+        let source;
         try {
-            forkOptions = await settledForkOptions(await this.repo.open(sourceMeta));
+            source = await this.repo.open(sourceMeta);
         }
         catch (e) {
             if (isNotFound(e))
                 return null;
             throw e;
         }
+        if (((await source.getMetadata()).owner ?? null) !== null)
+            throw new StampedSessionArchiveError(sourceId);
+        const forkOptions = await settledForkOptions(source);
         const forkOwner = forkOwnerOf(owner, this.metaCellOf(sourceId)?.owner);
         const existing = this.metaCellOf(target.id);
         const targetArchived = await this.existsInRepo(target.id);
         const copy = () => this.repo.fork(sourceMeta, { ...forkOptions, id: target.id });
         if (existing === undefined && !targetArchived) {
-            const created = await this.writeMeta(target.id, (before) => before !== undefined ? undefined : { incarnation: mintSessionIncarnation(), ...(forkOwner !== undefined ? { owner: forkOwner } : {}), ...(target.key !== undefined ? { forkKey: target.key } : {}) });
+            const created = await this.writeMeta(target.id, (before) => before !== undefined
+                ? undefined
+                : { incarnation: mintSessionIncarnation(), ...(forkOwner !== undefined ? { owner: forkOwner } : {}), ...(target.key !== undefined ? { forkKey: target.key } : {}), createdAt: rowBornNow(), forkedFrom: sourceId });
             if (!created)
                 throw new SessionError("storage", `LocalSessionStore: fork target ${target.id} gained a session-meta cell under its own write lock — refusing to guess`);
             try {
@@ -860,6 +1173,8 @@ export class LocalSessionStore {
         if (!this.repo.importEntries)
             throw new SessionError("storage", "session import is not supported by this local backend");
         await this.meta.ensureLoaded();
+        if (landing === "replace")
+            await this.assertNotPlacedHeld(sessionId);
         validateEntriesForImport(entries);
         const current = this.metaCellOf(sessionId);
         if (current?.execution?.role === "writer")
@@ -873,8 +1188,10 @@ export class LocalSessionStore {
             case "create":
             case "judged":
                 try {
-                    const archive = (await this.repo.headOf(sessionId)) ?? null;
-                    await this.repo.importEntries(sessionId, archive?.owner ?? undefined, entries, { expect: { row: archive } });
+                    const archive = (await this.archiveHeadOf(sessionId)) ?? null;
+                    if ((archive?.owner ?? null) !== null)
+                        throw new StampedSessionArchiveError(sessionId);
+                    await this.repo.importEntries(sessionId, undefined, entries, { expect: { row: archive } });
                 }
                 catch (err) {
                     await this.withdrawImportCell(sessionId, prior, err);
@@ -898,6 +1215,12 @@ export class LocalSessionStore {
         }
         await this.touch(sessionId);
     }
+    async assertNotPlacedHeld(sessionId) {
+        const placed = await this.placedRecordOf(sessionId);
+        if (placed !== undefined) {
+            throw new SessionError("placement_refused", `session ${sessionId} belongs to the ${placed.kind} placement partition (a delegated agent's transcript) — a session import cannot replace its log`);
+        }
+    }
     async importMayLand(sessionId, current, owner, landing) {
         switch (landing) {
             case "create":
@@ -917,7 +1240,9 @@ export class LocalSessionStore {
         await this.writeMeta(sessionId, (before) => {
             prior = before;
             const cells = carriedRowCells(sessionId, before === undefined ? undefined : readSessionMetaCell(before));
-            return { incarnation: cells.incarnation, owner, execution: MIRROR_CELL, ...(cells.forkKey !== null ? { forkKey: cells.forkKey } : {}) };
+            const base = before === undefined ? { createdAt: rowBornNow() } : cellObjectOf(before);
+            const { forkKey: _carriedByTheRule, ...kept } = base;
+            return { ...kept, incarnation: cells.incarnation, owner, execution: MIRROR_CELL, ...(cells.forkKey !== null ? { forkKey: cells.forkKey } : {}) };
         });
         return prior;
     }
@@ -950,6 +1275,7 @@ export class LocalSessionStore {
                 throw new StagedCommitOwnerChangedError(sessionId);
             if (await this.forkingOf(sessionId, current))
                 throw new SessionForkInProgressError(sessionId);
+            await this.assertNotPlacedHeld(sessionId);
             const dstEntries = await this.exportEntries(sessionId);
             const rel = classifySyncRelationshipByIds(staged.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
             if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
@@ -992,15 +1318,214 @@ export class LocalSessionStore {
             if (!isNotFound(e))
                 throw e;
         }
+        await this.dropRowHeld(sessionId);
+        return true;
+    }
+    async dropRowHeld(sessionId) {
+        this.rowsDropped.add(sessionId);
         for (const [map, which] of [[this.titles, "title"], [this.pinned, "pinned"], [this.instructionSources, "instruction-source"], [this.workspaces, "workspace"]]) {
             await map.ensureLoaded();
             if (!(await map.deleteKey(sessionId)))
                 throw new SessionError("storage", `LocalSessionStore: ${which} sidecar write failed while deleting session ${sessionId} — its ${which} is still on disk; retry the delete`);
         }
-        await this.dropMeta(sessionId);
+        await this.ensureLoaded();
         this.lastActivity.delete(sessionId);
         this.scheduleFlush();
-        return true;
+        await this.dropMeta(sessionId);
+    }
+    syncArchiveDirectory() {
+        if (this.dataRoot === undefined)
+            return;
+        fsyncPaths(join(this.dataRoot, "sessions"));
+    }
+    archiveSnapshotDir() {
+        return this.dataRoot === undefined ? undefined : join(this.dataRoot, LOCAL_ARCHIVE_SNAPSHOT_DIR);
+    }
+    async settleArchiveSnapshots() {
+        const dir = this.archiveSnapshotDir();
+        if (dir === undefined)
+            return 0;
+        let settled = 0;
+        let names;
+        try {
+            names = namesIn(dir);
+        }
+        catch (e) {
+            throw new LocalArchiveSnapshotsPresentError(dir, [], unreadableDirDetail(e));
+        }
+        for (const name of names) {
+            try {
+                if (name.endsWith(".tmp")) {
+                    unlinkSync(join(dir, name));
+                    continue;
+                }
+                if (!name.endsWith(".json"))
+                    continue;
+                await this.settleArchiveSnapshot(dir, name);
+                settled += 1;
+            }
+            catch (e) {
+                if (e instanceof LocalArchiveSnapshotsPresentError)
+                    throw e;
+                throw new LocalArchiveSnapshotsPresentError(dir, names, `settling ${name} failed (${e instanceof Error ? e.message : String(e)})`);
+            }
+        }
+        this.archiveSnapshotsSettled += settled;
+        assertNoArchiveSnapshots(dir);
+        return settled;
+    }
+    async settleArchiveSnapshot(dir, name) {
+        const path = join(dir, name);
+        const id = name.slice(0, -".json".length);
+        const refuse = (why, cause) => new LocalArchiveSnapshotsPresentError(dir, namesIn(dir), `${name} (session ${id}) cannot be settled: ${why}${cause === undefined ? "" : ` (${cause instanceof Error ? cause.message : String(cause)})`}`);
+        let record;
+        try {
+            record = decodeJsonColumn(readFileSync(path, "utf8"), readArchiveSnapshotRecord, `${name} (a local archive snapshot)`);
+        }
+        catch (e) {
+            throw refuse("the record is unreadable", e instanceof SqlJsonColumnError ? e.problem : e);
+        }
+        if (record.id !== id)
+            throw refuse(`the record names session ${record.id}`);
+        if (!this.repo.importEntries)
+            throw refuse("this local backend's session repo cannot import a log");
+        await this.withSessionWriteLock(id, async () => {
+            let head;
+            try {
+                head = await this.archiveHeadOf(id);
+            }
+            catch (e) {
+                throw refuse("the session's stored archive is unreadable", e);
+            }
+            if (head === undefined) {
+                try {
+                    await this.repo.importEntries(id, undefined, record.entries, { expect: { row: null }, preserveActorAssertions: true });
+                    this.syncArchiveDirectory();
+                }
+                catch (e) {
+                    throw refuse("restoring the archive from the snapshot failed", e);
+                }
+                await this.fillRowFacts(id, record.rowFacts);
+            }
+            else if (head.owner === null) {
+                await this.fillRowFacts(id, record.rowFacts);
+            }
+            else if (head.incarnation !== (record.archiveIncarnation ?? undefined)) {
+                throw refuse("the session's archive is a different generation from the one the snapshot was taken of");
+            }
+            unlinkSync(path);
+            fsyncPaths(dir);
+        });
+    }
+    async fillRowFacts(sessionId, facts) {
+        await this.writeMeta(sessionId, (before) => rowFactsFilled(before, facts));
+    }
+    async migrateLocalArchives() {
+        const dir = this.archiveSnapshotDir();
+        if (dir === undefined)
+            return { rowFactsBackfilled: 0, anonymized: 0, keptStamped: [], unreadable: [], snapshotsRecovered: 0 };
+        await this.settleArchiveSnapshots();
+        if (!this.repo.readRow || !this.repo.importEntries)
+            throw new SessionError("storage", "LocalSessionStore: the one-time migration M33 needs a session repo that reads a whole row and imports a log (readRow / importEntries)");
+        await this.meta.ensureLoaded();
+        const rowHeaders = await this.rowHeaders();
+        const listed = [];
+        const unreadable = [];
+        for (const row of rowHeaders) {
+            if ("header" in row) {
+                listed.push(row.header);
+                continue;
+            }
+            const errno = errnoOf(row.headerFault);
+            unreadable.push({ sessionId: row.sessionId, ...(errno !== undefined ? { errno } : {}) });
+        }
+        let rowFactsBackfilled = 0;
+        const committed = await this.meta.commit((draft) => {
+            rowFactsBackfilled = 0;
+            for (const row of listed) {
+                const next = rowFactsFilled(draft.get(row.id), archivedRowFactsOf(row));
+                if (next === undefined)
+                    continue;
+                draft.set(row.id, next);
+                rowFactsBackfilled += 1;
+            }
+            return rowFactsBackfilled > 0;
+        });
+        if (!committed)
+            throw new SessionError("storage", "LocalSessionStore: the one-time migration M33 could not write the row facts it backfilled into the session-meta sidecar — no archive was touched");
+        this.meta.syncToDisk();
+        let anonymized = 0;
+        if (listed.some((row) => (row.owner ?? null) !== null)) {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            fsyncPaths(dir, dirname(dir));
+        }
+        const keptStamped = [];
+        for (const row of [...listed].sort((a, b) => (a.id < b.id ? -1 : 1))) {
+            if ((row.owner ?? null) === null)
+                continue;
+            const step = await this.withSessionWriteLock(row.id, () => this.anonymizeArchiveHeld(row.id, dir));
+            switch (step.outcome) {
+                case "anonymized":
+                    anonymized += 1;
+                    break;
+                case "skipped":
+                    break;
+                case "kept":
+                    keptStamped.push({ sessionId: row.id, reason: step.reason, ...(step.detail !== undefined ? { detail: step.detail } : {}) });
+                    break;
+                case "unreadable":
+                    unreadable.push({ sessionId: row.id, ...(step.errno !== undefined ? { errno: step.errno } : {}) });
+                    break;
+                default: {
+                    const unknownOutcome = step;
+                    throw new Error(`LocalSessionStore: no M33 outcome ${JSON.stringify(unknownOutcome)}`);
+                }
+            }
+        }
+        const snapshotsRecovered = this.archiveSnapshotsSettled;
+        this.archiveSnapshotsSettled = 0;
+        return { rowFactsBackfilled, anonymized, keptStamped, unreadable, snapshotsRecovered };
+    }
+    async anonymizeArchiveHeld(sessionId, dir) {
+        const scope = { dropped: 0 };
+        let row;
+        try {
+            row = await archiveRewriteReadScope.run(scope, () => this.repo.readRow(sessionId));
+        }
+        catch (e) {
+            return { outcome: "unreadable", errno: errnoOf(e) };
+        }
+        if (row === undefined || (row.head.owner ?? null) === null)
+            return { outcome: "skipped" };
+        if (scope.dropped > 0)
+            return { outcome: "kept", reason: "records_skipped" };
+        let validated;
+        try {
+            validated = validateEntriesForImport(row.entries, { preserveActorAssertions: true });
+        }
+        catch (e) {
+            return { outcome: "kept", reason: "invalid", detail: e instanceof Error ? e.message : String(e) };
+        }
+        if (!sameLog(validated, row.entries))
+            return { outcome: "kept", reason: "normalizes" };
+        const cell = this.metaCellOf(sessionId);
+        if (cell?.createdAt === undefined)
+            throw new Error(`LocalSessionStore: the one-time migration M33 reached session ${sessionId}'s archive before its row facts were backfilled — refusing to rewrite it`);
+        const record = {
+            id: sessionId,
+            archiveIncarnation: row.head.incarnation ?? null,
+            rowFacts: { createdAt: cell.createdAt, ...(cell.forkedFrom !== undefined ? { forkedFrom: cell.forkedFrom } : {}) },
+            entries: row.entries,
+        };
+        const path = join(dir, `${sessionId}.json`);
+        atomicWriteFile(dir, path, JSON.stringify(record));
+        fsyncPaths(dir);
+        await this.repo.delete({ id: sessionId, createdAt: "" }, { row: { owner: row.head.owner, incarnation: row.head.incarnation } });
+        await this.repo.importEntries(sessionId, undefined, row.entries, { expect: { row: null }, preserveActorAssertions: true });
+        this.syncArchiveDirectory();
+        unlinkSync(path);
+        fsyncPaths(dir);
+        return { outcome: "anonymized" };
     }
     get size() {
         return this.pending.size;