sealkeep 0.8.1 → 0.11.0

package/dist/src/retention.js

@@ -1,11 +1,25 @@
-import { readFile, rm, stat, writeFile } from "node:fs/promises";
+import { readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { join } from "node:path";
-import { isSourceActive } from "./activity.js";
-import { fail, isVaultlineError } from "./errors.js";
+import { isSourceActive, probeLiveNativeSession } from "./activity.js";
+import { fail } from "./errors.js";
 import { recordAudit } from "./audit.js";
-import { moveToTrash } from "./trash.js";
+import { defaultStrategy, moveToTrash } from "./trash.js";
 import { isV2 } from "./types.js";
-import { listArchives, readConfig, writeConfig, writeRecord } from "./vault.js";
+import { deltaOf, listArchives, mutateArchiveRecord, readConfig, resolveDeltaChain, teamSpaceOf, updateConfigFields } from "./vault.js";
+import { archiveCopies, hasCompleteVerifiedCopyChain, hasVerifiedCopy, verifiedCopyDestinationKey } from "./archive-copies.js";
+import { equalHex } from "./crypto.js";
+import { hashFileRange } from "../packages/sealkeep-crypto/src/index.js";
+import { discardCodexResumeStub, assertCodexResumePointerMetadataSupported, assertCodexResumePointerSupported, assertCodexResumePointerTempPath, codexSessionIdMatchesFilename, installCodexResumeStub, isNativeCodexSessionPath, prepareCodexResumeStub, readUntouchedCodexResumeStub, validateNativeCodexSessionPath, validateCodexResumePointerBinding, } from "./resume-stub.js";
+import { acquireReclaimSourceLock, beginReclaimTransaction, finalizeReclaimTransaction, installReclaimReplacement, markReclaimMetadataCommitted, markReclaimPurgeAuthorized, moveReclaimSource, reconcileReclaimTransactions, reclaimJournalPath, rollbackReclaimTransaction, validateNoFollowPath, } from "./reclaim-transaction.js";
+import { NATIVE_ROOTS } from "./restore.js";
+import { createBackgroundCpuYield } from "./background-cpu.js";
+import { paceBackgroundByteStream } from "./background-bandwidth.js";
+import { listIndexPublicationRequirements } from "./index-publication-state.js";
+import { recheckManagedAccountIndexPublicationBeforeUnlink, verifyManagedAccountIndexPublication, } from "./index-publication-verifier.js";
+import { resolveRecoveryPhrase } from "./secrets.js";
+import { INDEX_EXTRACTION_POLICY } from "./search.js";
 /** For blocker text a person reads. Whole numbers below 10 units, one decimal above. */
 function humanBytes(value) {
     const units = ["B", "KB", "MB", "GB", "TB"];
@@ -17,10 +31,237 @@ function humanBytes(value) {
     return `${unit === 0 ? size : size < 10 ? size.toFixed(1) : Math.round(size)} ${units[unit]}`;
 }
 export const DEFAULT_RETENTION = {
-    policy: "local-only", olderThanDays: 30, graceDays: 7, deleteAfterDays: null,
+    // 30 days here meant a fresh install returned nothing for a month, which
+    // reads as "the product does not work" rather than "the product is careful".
+    // 7 matches the grace period, and the guards that actually prevent data loss
+    // — a verified remote copy, search coverage, an idle source unchanged since
+    // sealing, and the crash-safe purge transaction — are untouched by this number.
+    policy: "local-only", olderThanDays: 7, graceDays: 7, deleteAfterDays: null,
     sourceIdleDays: null, minSourceBytes: null
 };
 export const POLICIES = ["local-only", "sync-only", "archive-and-reclaim", "manual-approval"];
+const denyReclaimAuthorization = async () => false;
+/** Current persisted policy, re-read at every irreversible boundary. */
+function confirmedRetentionAuthorization(dataDir, delegated) {
+    return async (archiveId) => {
+        const policy = retentionSettings(await readConfig(dataDir)).policy;
+        const policyAllows = policy === "archive-and-reclaim"
+            || (policy === "manual-approval" && (await readApprovals(dataDir)).includes(archiveId));
+        if (!policyAllows)
+            return false;
+        return delegated ? await delegated(archiveId) === true : true;
+    };
+}
+async function assertReclaimAuthorized(authorize, archiveId) {
+    if (!authorize)
+        return;
+    if (await authorize(archiveId) !== true) {
+        fail("invalid_argument", "Automatic reclaim was disabled or its policy changed while reclaim was running, so the original was kept.", { archiveId });
+    }
+}
+/** A delta session is durable only when its complete chain shares one target. */
+function completeRemoteChain(archives, record) {
+    try {
+        const chain = resolveDeltaChain(archives, record);
+        return {
+            chain,
+            complete: chain.every(isV2) && hasCompleteVerifiedCopyChain(chain),
+        };
+    }
+    catch {
+        return { chain: [], complete: false };
+    }
+}
+/**
+ * Read every object needed for this session from one complete recorded
+ * destination and require its current bytes to match the archive SHA-256. This
+ * fresh cryptographic proof closes lifecycle deletion, same-size replacement,
+ * and stale managed-metadata windows immediately before local purge.
+ *
+ * Extra stale copies do not block a healthy one. For a delta chain, however,
+ * every link must answer from the same physical destination; independently
+ * healthy links split across providers cannot restore the session.
+ */
+async function verifyRemoteChainImmediatelyBeforePurge(dataDir, chain, operation, options = {}) {
+    if (chain.length === 0 || !chain.every(isV2)) {
+        fail("invalid_argument", "The complete verified archive chain could not be loaded, so the local original was kept.");
+    }
+    const records = chain;
+    const verified = records.map((record) => archiveCopies(record).filter((copy) => Number.isFinite(Date.parse(copy.verifiedAt))));
+    const groups = [];
+    if (records.length === 1) {
+        for (const copy of verified[0] ?? [])
+            groups.push([copy]);
+    }
+    else {
+        let common = new Set((verified[0] ?? []).map(verifiedCopyDestinationKey).filter((key) => Boolean(key)));
+        for (const copies of verified.slice(1)) {
+            const keys = new Set(copies.map(verifiedCopyDestinationKey).filter((key) => Boolean(key)));
+            common = new Set([...common].filter((key) => keys.has(key)));
+        }
+        for (const key of [...common].sort()) {
+            const group = verified.map((copies) => copies.find((copy) => verifiedCopyDestinationKey(copy) === key));
+            if (group.every((copy) => Boolean(copy)))
+                groups.push(group);
+        }
+    }
+    if (groups.length === 0) {
+        fail("invalid_argument", "No one verified storage destination contains this session's complete archive chain, so the local original was kept.");
+    }
+    const check = operation ?? (async (root, archiveId, copyId) => {
+        const current = records.find((record) => record.id === archiveId);
+        const copy = archiveCopies(current).find((candidate) => candidate.copyId === copyId);
+        if (!copy)
+            return { ok: false, detail: "the selected physical copy disappeared from archive metadata" };
+        const remote = options.fetchRemoteCopy
+            ? await options.fetchRemoteCopy(root, current, copy, options.signal)
+            : await import("./offload.js").then(({ fetchCiphertextStream }) => (fetchCiphertextStream(root, current, undefined, copy, {}, options.signal)));
+        const stream = options.bytesPerSecond
+            ? paceBackgroundByteStream(root, remote, options.bytesPerSecond, { signal: options.signal })
+            : remote;
+        const hash = createHash("sha256");
+        let bytes = 0;
+        let sinceYield = 0;
+        for await (const chunk of stream) {
+            options.signal?.throwIfAborted();
+            hash.update(chunk);
+            bytes += chunk.length;
+            sinceYield += chunk.length;
+            if (sinceYield >= 16 * 1024 * 1024) {
+                sinceYield = 0;
+                await options.cooperate?.();
+            }
+        }
+        const digest = hash.digest("hex");
+        const expected = isV2(current) ? current.cipher : null;
+        const ok = Boolean(expected && bytes === expected.storedBytes && equalHex(digest, expected.ciphertextSha256));
+        return {
+            ok,
+            detail: ok
+                ? "the complete stored bytes were fetched and matched the archive SHA-256"
+                : `the fetched object was ${bytes} bytes with SHA-256 ${digest}; it did not match this archive`,
+        };
+    });
+    const problems = [];
+    for (const group of groups) {
+        let complete = true;
+        for (let index = 0; index < records.length; index += 1) {
+            const copy = group[index];
+            try {
+                const proof = await check(dataDir, records[index].id, copy.copyId);
+                if (!proof.ok) {
+                    complete = false;
+                    problems.push(proof.detail);
+                    break;
+                }
+            }
+            catch (error) {
+                complete = false;
+                problems.push(error instanceof Error ? error.message : "the provider check failed");
+                break;
+            }
+        }
+        if (complete)
+            return;
+    }
+    fail("invalid_argument", `Storage could not confirm a complete exact copy immediately before reclaim, so the local original was restored. ${problems[0] ?? "Try the copy check again."}`);
+}
+/**
+ * Proves that the pathname still contains exactly the bytes the archive sealed.
+ *
+ * Size is a cheap preview gate, but it is not an integrity proof: an editor can
+ * rewrite a transcript in place without changing its length. Every destructive
+ * path calls this immediately before staging the source for reclaim, after all
+ * slower policy, remote-copy, indexing, and activity checks have finished.
+ */
+async function verifySourceImmediatelyBeforeReclaim(record, cooperate) {
+    const measured = await hashFileRange(record.source.path, 0, undefined, undefined, undefined, cooperate).catch(() => null);
+    if (!measured) {
+        fail("source_unreadable", "The source file could not be read at the final safety check, so nothing was moved.", { path: record.source.path });
+    }
+    if (measured.bytes !== record.source.bytes || !equalHex(measured.sha256, record.source.sha256)) {
+        fail("invalid_argument", `The session contents changed since this archive was sealed (${record.source.bytes} bytes archived, ${measured.bytes} now) — re-archive it first; nothing was moved.`, { archiveId: record.id });
+    }
+}
+async function verifyIndexChainImmediatelyBeforePurge(dataDir, chain, requestedHead, searchableHeads, phrase, signal, bytesPerSecond, operation) {
+    const config = await readConfig(dataDir);
+    try {
+        return await (operation ?? (async (root, links, head, unlock, currentSignal, logicalHeads = [head]) => verifyManagedAccountIndexPublication({
+            dataDir: root,
+            vaultId: config.vaultId,
+            phrase: unlock,
+            extractionPolicy: INDEX_EXTRACTION_POLICY,
+            chain: links.map((record) => ({ archiveId: record.id, archiveRef: record.id })),
+            requestedHead: { archiveId: head.id, archiveRef: head.id },
+            searchableHeads: logicalHeads.map((record) => ({ archiveId: record.id, archiveRef: record.id })),
+            signal: currentSignal,
+            maxBytesPerSecond: bytesPerSecond,
+        })))(dataDir, chain, requestedHead, phrase, signal, searchableHeads);
+    }
+    catch (error) {
+        fail("invalid_argument", `Sealkeep could not prove this exact searchable memory is in the current immutable cloud index, so the local original was kept. ${error instanceof Error ? error.message : "Index verification failed."}`, { archiveId: requestedHead.id });
+    }
+}
+const CODEX_SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * A resumed Codex rollout can be reclaimed repeatedly. Each cycle creates a
+ * new archive head while every cycle keeps the same native session UUID. The
+ * next pointer searches by that UUID, so deletion is safe only if the current
+ * immutable account index still carries every previously reclaimed head.
+ */
+function searchableCodexContinuationHeads(records, requestedHead) {
+    if (!isV2(requestedHead) || requestedHead.source.agent !== "codex")
+        return [requestedHead];
+    const sessionId = requestedHead.reclaimed?.resumeStub?.sessionId;
+    if (!sessionId)
+        return [requestedHead];
+    if (!CODEX_SESSION_UUID.test(sessionId)
+        || !codexSessionIdMatchesFilename(requestedHead.source.path, sessionId)) {
+        fail("invalid_argument", "The current Codex continuation is not bound to its exact native session id, so the local original was kept.", { archiveId: requestedHead.id });
+    }
+    const heads = records.filter((candidate) => isV2(candidate)
+        && candidate.reclaimed?.resumeStub?.sessionId?.toLowerCase() === sessionId.toLowerCase());
+    for (const candidate of heads) {
+        if (candidate.source.agent !== "codex"
+            || !codexSessionIdMatchesFilename(candidate.source.path, sessionId)) {
+            fail("invalid_argument", `A prior reclaimed continuation (${candidate.id}) is not bound to the same exact Codex session id, so the local original was kept.`, { archiveId: requestedHead.id, priorArchiveId: candidate.id });
+        }
+    }
+    if (!heads.some((candidate) => candidate.id === requestedHead.id)) {
+        fail("invalid_argument", "The current Codex continuation reclaim record changed before index verification, so the local original was kept.", { archiveId: requestedHead.id });
+    }
+    return heads.sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
+}
+async function verifyCurrentDurabilityImmediatelyBeforePurge(dataDir, archiveId, sourcePath, remoteCheck, activity = {}, options = {}) {
+    const records = await listArchives(dataDir);
+    const record = records.find((candidate) => candidate.id === archiveId);
+    if (!record)
+        throw new Error("Reclaim archive disappeared before final durability verification");
+    const remoteChain = completeRemoteChain(records, record);
+    if (!remoteChain.complete)
+        throw new Error("The complete verified archive chain changed before purge");
+    // The byte-for-byte provider read is deliberately first: it is the slowest
+    // gate. Mutable local decisions (search coverage, a newly added pin, and a
+    // waiting agent process) are sampled after it, adjacent to authorization.
+    await verifyRemoteChainImmediatelyBeforePurge(dataDir, remoteChain.chain, remoteCheck, options);
+    const config = await readConfig(dataDir);
+    const phrase = await resolveRecoveryPhrase(dataDir, config.vaultId, options.phrase).catch(() => null);
+    if (!phrase) {
+        fail("invalid_argument", "Sealkeep cannot verify searchable cloud memory while this machine is locked. Unlock it and try again; the local original was kept.");
+    }
+    const publication = await verifyIndexChainImmediatelyBeforePurge(dataDir, remoteChain.chain, record, searchableCodexContinuationHeads(records, record), phrase, options.signal, options.bytesPerSecond, options.verifyIndexPublication);
+    if (isPinned(sourcePath, await neverReclaimMarks(dataDir))) {
+        fail("invalid_argument", "This session was pinned while reclaim was running, so the original was restored.", { archiveId });
+    }
+    const live = await (activity.liveNativeSession ?? probeLiveNativeSession)(sourcePath);
+    if (live === null) {
+        fail("invalid_argument", "Sealkeep could not confirm that the native agent process is stopped, so the original was restored.", { archiveId });
+    }
+    if (live) {
+        fail("invalid_argument", "This session belongs to a running native agent process, so the original was restored.", { archiveId });
+    }
+    return publication;
+}
 export function retentionSettings(config, overrides = {}) {
     return { ...DEFAULT_RETENTION, ...config.retention, ...overrides };
 }
@@ -44,6 +285,73 @@ export async function approveReclamation(dataDir, archiveIds) {
     await recordAudit(dataDir, "retention.approve", "allowed", { approved: archiveIds.length, total: merged.length });
     return merged;
 }
+/**
+ * The standing "never take this one" list, honoured by EVERY reclaimer.
+ *
+ * `<dataDir>/never-reclaim` (one id or path fragment per line, `#` comments)
+ * was read by exactly one of the four deleters — the squeeze command — so a
+ * pinned session survived a squeeze and was then reclaimed by the daemon's
+ * ordinary retention tick, with no user in the loop. A pin only one deleter
+ * honours is a hole; it lives here now so every caller inherits it.
+ */
+export async function neverReclaimMarks(dataDir) {
+    const { readFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    return readFile(join(dataDir, "never-reclaim"), "utf8")
+        .then((text) => text.split("\n").map((line) => line.split("#")[0].trim().toLowerCase()).filter(Boolean))
+        .catch(() => []);
+}
+export function isPinned(path, marks) {
+    const lower = path.toLowerCase();
+    return marks.some((mark) => lower.includes(mark));
+}
+/**
+ * Which local archive ids the encrypted content index can currently answer.
+ *
+ * A verified remote object proves recoverability, but preservation also means
+ * an agent can find the work after the bulky source leaves this machine.  The
+ * coverage sidecar contains ids only (never transcript text), so this gate is
+ * cheap and does not need the recovery phrase.  `null` is deliberately fail
+ * closed: if coverage cannot be read, no source becomes disposable merely
+ * because an advisory file is damaged.
+ */
+async function indexedArchiveIds(dataDir, records) {
+    try {
+        const { indexCoverage } = await import("./search.js");
+        const coverage = await indexCoverage(dataDir);
+        const missing = new Set(coverage.missing.map((item) => item.id));
+        return new Set(records.map((record) => record.id).filter((id) => !missing.has(id)));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cheap, local preview of the durable publication ledger.  Local index
+ * coverage says an agent on THIS machine can search; a positive receipt says
+ * an immutable managed generation carrying that exact entry was committed and
+ * read back.  Destructive paths repeat the network and cryptographic checks at
+ * the final boundary; this merely prevents the UI/daemon from presenting an
+ * obviously unreceipted source as reclaimable.
+ */
+async function publicationReceiptStatuses(dataDir, config) {
+    try {
+        return await listIndexPublicationRequirements(dataDir, { vaultId: config.vaultId });
+    }
+    catch {
+        return null;
+    }
+}
+function hasPublicationReceipt(statuses, archiveId, scope) {
+    if (!statuses)
+        return false;
+    return statuses.some((status) => status.requirement.archiveId === archiveId
+        && status.receipt !== null
+        && status.requirement.scope.kind === scope.kind
+        && (scope.kind === "account"
+            ? status.requirement.scope.kind === "account" && status.requirement.scope.vaultId === scope.vaultId
+            : status.requirement.scope.kind === "team" && status.requirement.scope.spaceKey === scope.spaceKey));
+}
 /**
  * Decides, per archive, whether its local source may be reclaimed.
  *
@@ -51,6 +359,7 @@ export async function approveReclamation(dataDir, archiveIds) {
  * complete reason a file is protected rather than the first one that matched.
  */
 export async function evaluateRetention(dataDir, options = {}) {
+    const pins = await neverReclaimMarks(dataDir);
     const config = await readConfig(dataDir);
     const settings = retentionSettings(config, { ...options.settings, ...(options.olderThanDays === undefined ? {} : { olderThanDays: options.olderThanDays }) });
     if (!Number.isFinite(settings.olderThanDays) || settings.olderThanDays < 0)
@@ -67,7 +376,9 @@ export async function evaluateRetention(dataDir, options = {}) {
     // managed storage proves it, and a fresh vault with none reads as unmanaged,
     // which only changes wording.
     const allRecords = await listArchives(dataDir);
-    const managed = allRecords.some((item) => isV2(item) && item.remote?.provider === "vaultline");
+    const indexed = await indexedArchiveIds(dataDir, allRecords);
+    const publicationStatuses = await publicationReceiptStatuses(dataDir, config);
+    const managed = allRecords.some((item) => isV2(item) && archiveCopies(item).some((copy) => copy.provider === "vaultline" && copy.verifiedAt));
     for (const record of allRecords) {
         const current = await stat(record.source.path).catch(() => null);
         if (!current)
@@ -75,6 +386,8 @@ export async function evaluateRetention(dataDir, options = {}) {
         if (isV2(record) && record.reclaimed)
             continue;
         const blockers = [];
+        if (isPinned(record.source.path, pins))
+            blockers.push("listed in never-reclaim — this session is pinned; edit <dataDir>/never-reclaim to release it");
         // The archive covers the bytes that existed when it was written. A session
         // that kept being appended to has content in no archive at all, and
         // reclaiming it would delete exactly that content — so refuse, and say so
@@ -82,6 +395,8 @@ export async function evaluateRetention(dataDir, options = {}) {
         // agent transcripts grow by appending and this runs over every record.
         if (current.size !== record.source.bytes)
             blockers.push(`source changed since it was archived (${record.source.bytes} bytes archived, ${current.size} now); re-archive it first`);
+        if (current.nlink !== 1)
+            blockers.push(`source has ${current.nlink} hard links, so removing this name would not free its allocated blocks`);
         // These render straight into a dashboard table cell, so they are sentences
         // a customer reads, not slugs a maintainer greps. The retention page already
         // names the four policies in plain words; the same words are used here.
@@ -90,28 +405,44 @@ export async function evaluateRetention(dataDir, options = {}) {
         // shows in a narrow column. The one a person can act on leads — "no
         // storage is set up" is a thing to go and change, while "set to keep
         // everything" is quite possibly what they meant.
-        const remote = isV2(record) ? record.remote : undefined;
+        const remote = isV2(record) ? archiveCopies(record).find((copy) => copy.verifiedAt) : undefined;
+        const remoteChain = isV2(record) ? completeRemoteChain(allRecords, record) : { chain: [], complete: false };
         // A managed-tier vault has no `remoteStorage` of its own — the bucket is
         // ours — so "no remote target configured" was told to paying customers about
         // storage they were paying for. The honest state is the same either way:
         // this archive has not been uploaded and verified yet.
         if (!remote?.verifiedAt)
             blockers.push(config.remoteStorage || managed ? "not yet uploaded and verified" : "no storage is set up, so there is no second copy to reclaim against");
+        else if (!remoteChain.complete && !deltaOf(record))
+            blockers.push("the archive chain is not fully verified at one storage destination yet");
+        // Durability and discoverability are separate promises. Upload may run in
+        // parallel with a historical index migration, but the original transcript
+        // stays until this exact archive is searchable. That keeps the fast lane
+        // fast without ever turning a successful backup into forgotten work.
+        if (!indexed?.has(record.id))
+            blockers.push(indexed ? "not yet searchable; indexing is still in progress" : "search index could not be checked; keeping the source");
+        const accountReceipted = remoteChain.chain.length > 0
+            && remoteChain.chain.every((link) => hasPublicationReceipt(publicationStatuses, link.id, { kind: "account", vaultId: config.vaultId }));
+        if (!accountReceipted)
+            blockers.push(publicationStatuses
+                ? "search memory is not yet committed to a verified Sealkeep Cloud index generation"
+                : "search publication proof could not be checked; keeping the source");
+        const teamBinding = teamSpaceOf(config, isV2(record) ? record.source.project : undefined, isV2(record) ? record.source.projectKey : undefined);
+        if (teamBinding && !remoteChain.chain.every((link) => hasPublicationReceipt(publicationStatuses, link.id, { kind: "team", spaceKey: teamBinding.spaceKey }))) {
+            blockers.push("shared project memory has not reached its current verified team index yet");
+        }
         // A delta archive restores through its whole chain, so "there is a second
         // copy" must be true of every link, not just this head. One unverified
         // base and reclaiming the source deletes bytes only this disk holds.
-        if (remote?.verifiedAt) {
-            const { deltaOf, resolveDeltaChain } = await import("./vault.js");
-            if (deltaOf(record)) {
-                try {
-                    const chain = resolveDeltaChain(allRecords, record);
-                    const unverified = chain.filter((link) => !(isV2(link) && link.remote?.verifiedAt)).length;
-                    if (unverified > 0)
-                        blockers.push(`this snapshot builds on ${chain.length - 1} earlier ${chain.length === 2 ? "archive" : "archives"}, and ${unverified} of the chain ${unverified === 1 ? "is" : "are"} not uploaded and verified yet`);
-                }
-                catch {
-                    blockers.push("this snapshot builds on an earlier archive that is missing, so the transcript cannot be restored from the cloud alone");
-                }
+        if (remote?.verifiedAt && deltaOf(record) && !remoteChain.complete) {
+            if (remoteChain.chain.length > 0) {
+                const unverified = remoteChain.chain.filter((link) => !(isV2(link) && hasVerifiedCopy(link))).length;
+                blockers.push(unverified > 0
+                    ? `this snapshot builds on ${remoteChain.chain.length - 1} earlier ${remoteChain.chain.length === 2 ? "archive" : "archives"}, and ${unverified} of the chain ${unverified === 1 ? "is" : "are"} not uploaded and verified at one destination yet`
+                    : "this snapshot's verified copies are split across storage destinations, so no one destination can restore the cloud session");
+            }
+            else {
+                blockers.push("this snapshot builds on an earlier archive that is missing, so the cloud cannot reproduce the file. Keep the source.");
             }
         }
         if (settings.policy === "local-only")
@@ -142,6 +473,15 @@ export async function evaluateRetention(dataDir, options = {}) {
                 blockers.push(hours < 48 ? `grace period ends in ${hours}h` : `grace period ends in ${Math.ceil(hours / 24)} days`);
             }
         }
+        // A multi-agent Codex child currently cannot resume independently through
+        // its own native id. Detect that before presenting it as reclaimable; the
+        // apply path repeats this parser while building the pointer and therefore
+        // still fails closed if the file changes after preview.
+        if (blockers.length === 0 && record.source.agent === "codex"
+            && await isNativeCodexSessionPath(record.source.path, options.home ?? homedir())) {
+            await assertCodexResumePointerSupported(record.source.path, options.home ?? homedir())
+                .catch((error) => blockers.push(error instanceof Error ? error.message : "Codex resume metadata could not be verified; keeping the original on disk"));
+        }
         // The activity probe shells out to lsof, so it is the one expensive gate —
         // and it only changes the outcome when every other gate already passed.
         // Probing unconditionally put ~90ms × every archive inside each evaluation,
@@ -159,12 +499,14 @@ export async function evaluateRetention(dataDir, options = {}) {
         // reason.
         const distinct = [...new Set(blockers)];
         candidates.push({
-            id: record.id, agent: record.source.agent, path: record.source.path, bytes: record.source.bytes, createdAt: record.createdAt,
+            id: record.id, agent: record.source.agent, path: record.source.path, bytes: record.source.bytes,
+            allocatedBytes: current.blocks * 512, createdAt: record.createdAt,
             eligible: distinct.length === 0, blockers: distinct, reason: distinct[0] ?? "eligible for reclamation",
             remote: remote?.verifiedAt ? { provider: remote.provider, verifiedAt: remote.verifiedAt } : null
         });
     }
-    const reclaimableBytes = candidates.filter((candidate) => candidate.eligible).reduce((total, candidate) => total + candidate.bytes, 0);
+    const reclaimableBytes = candidates.filter((candidate) => candidate.eligible)
+        .reduce((total, candidate) => total + candidate.allocatedBytes, 0);
     return {
         mode: "preview", policy: settings.policy, olderThanDays: settings.olderThanDays, graceDays: settings.graceDays,
         sourceIdleDays: settings.sourceIdleDays, minSourceBytes: settings.minSourceBytes,
@@ -175,37 +517,632 @@ export async function evaluateRetention(dataDir, options = {}) {
         reclaimableBytes, candidates
     };
 }
+/**
+ * Stages a source and, for a real native Codex rollout, replaces it with the
+ * already-prepared resume pointer. Preparation happens while the verified
+ * original still exists. Any failure before the durable purge decision rolls
+ * the move back rather than leaving resume broken.
+ */
+async function moveReclaimableSource(dataDir, record, options) {
+    const stub = await prepareCodexResumeStub(record.source.path, record.id, {
+        home: options.home,
+        project: isV2(record) ? record.source.project ?? null : null,
+    });
+    const selectedHome = options.home ?? homedir();
+    const nativeClaudeSource = record.source.agent === "claude"
+        && await validateNoFollowPath(record.source.path, NATIVE_ROOTS.claude(selectedHome), { leaf: "file" })
+            .then(() => true, () => false);
+    const durablePurge = Boolean(stub) || nativeClaudeSource;
+    // Every production "Free up disk" operation is one journaled transaction.
+    // Codex gets a tiny same-id replacement; other agents leave the native path
+    // absent. Test seams for the legacy trash/install boundary stay narrow and
+    // never run in production.
+    if (durablePurge && !options.operations?.moveToTrash && !options.operations?.installResumeStub) {
+        if (!options.lock)
+            throw new Error("Source reclaim requires its source lock");
+        if (stub) {
+            await validateNativeCodexSessionPath(record.source.path, options.home, "file");
+            await validateNativeCodexSessionPath(stub.tempPath, options.home, "file");
+        }
+        let transaction;
+        try {
+            transaction = await beginReclaimTransaction(dataDir, options.lock, {
+                sourcePath: record.source.path,
+                original: { bytes: record.source.bytes, sha256: record.source.sha256 },
+                replacement: stub ? { tempPath: stub.tempPath, bytes: stub.bytes, sha256: stub.sha256 } : null,
+                transactionId: record.id,
+            }, { onYield: options.cooperate });
+        }
+        catch (error) {
+            // `begin` publishes the durable journal last. If a directory fsync
+            // reports failure after that publication, its exact replacement temp is
+            // now recovery state and must survive for the next reconciliation. In
+            // every other begin failure this process still owns the unreferenced
+            // prepared temp and can remove it.
+            const raw = await readFile(reclaimJournalPath(dataDir, record.id), "utf8").catch(() => null);
+            let journalOwnsTemp = false;
+            if (raw && stub) {
+                try {
+                    const parsed = JSON.parse(raw);
+                    journalOwnsTemp = parsed.replacement?.tempPath === stub.tempPath
+                        && parsed.replacement.bytes === stub.bytes
+                        && parsed.replacement.sha256 === stub.sha256;
+                }
+                catch { /* malformed journals stay visible as reconciliation conflicts */ }
+            }
+            if (!journalOwnsTemp)
+                await discardCodexResumeStub(stub);
+            throw error;
+        }
+        try {
+            await assertReclaimAuthorized(options.authorizeReclaim, record.id);
+            await options.assertStillAllowed?.();
+            await moveReclaimSource(transaction, options.lock, { onYield: options.cooperate });
+            if (stub)
+                await installReclaimReplacement(transaction, options.lock, { onYield: options.cooperate });
+            // Re-check the parked inode after its public native name has gone. An
+            // agent that already held the old file descriptor can otherwise keep
+            // writing to it after our first lsof probe. At this point new agent opens
+            // reach either the Codex pointer or an absent Claude path; any handle on
+            // the staged inode is therefore an old live writer and forces rollback.
+            const stagedActivity = await isSourceActive(transaction.trashPath, {
+                ...options.activity,
+                now: options.now ?? Date.now(),
+            });
+            if (stagedActivity.active) {
+                fail("invalid_argument", `The session became active while Sealkeep prepared to reclaim it: ${stagedActivity.reason}. The original was restored and nothing was freed.`, { archiveId: record.id });
+            }
+            return {
+                trash: { movedTo: transaction.trashPath, strategy: "sealkeep-trash" },
+                stub,
+                transaction,
+                lock: options.lock,
+                verifyPurgeStillSafe: async () => {
+                    const publication = await verifyCurrentDurabilityImmediatelyBeforePurge(dataDir, record.id, record.source.path, options.operations?.checkRemoteCopy, options.activity, {
+                        signal: options.signal,
+                        cooperate: options.cooperate,
+                        bytesPerSecond: options.remoteBytesPerSecond,
+                        fetchRemoteCopy: options.operations?.fetchRemoteCopy,
+                        phrase: options.phrase,
+                        verifyIndexPublication: options.operations?.verifyIndexPublication,
+                    });
+                    const finalStagedActivity = await isSourceActive(transaction.trashPath, {
+                        ...options.activity,
+                        now: Date.now(),
+                    });
+                    if (finalStagedActivity.active) {
+                        fail("invalid_argument", `The staged session is still open: ${finalStagedActivity.reason}. The original was restored.`, { archiveId: record.id });
+                    }
+                    // The full provider read above can take minutes. Sample the daemon's
+                    // current permission last, adjacent to the irreversible unlink.
+                    await assertReclaimAuthorized(options.authorizeReclaim, record.id);
+                    await (options.operations?.recheckIndexPublication
+                        ? options.operations.recheckIndexPublication(dataDir, publication, options.signal)
+                        : recheckManagedAccountIndexPublicationBeforeUnlink({
+                            dataDir,
+                            verification: publication,
+                            signal: options.signal,
+                        }));
+                },
+            };
+        }
+        catch (error) {
+            const rollbackErrors = [];
+            await rollbackReclaimTransaction(transaction, options.lock, { io: { onYield: options.cooperate } })
+                .catch((rollback) => rollbackErrors.push(rollback));
+            await discardCodexResumeStub(stub);
+            if (rollbackErrors.length > 0)
+                throw new AggregateError([error, ...rollbackErrors], "Codex reclamation failed and its journal was retained for reconciliation");
+            throw error;
+        }
+    }
+    // The public action is named "Free up disk". Moving an unsupported source
+    // to another directory on the same filesystem frees no blocks, so production
+    // must not silently fall back to Trash and report a successful reclaim.
+    // The injected boundary remains only for the older isolated trash-contract
+    // tests; real native Codex and Claude paths always use the journaled purge.
+    if (!options.operations?.moveToTrash && !options.operations?.installResumeStub) {
+        fail("invalid_argument", "Sealkeep cannot safely free this source yet. Only supported native Codex and Claude session files can be permanently reclaimed; the original was kept.", { archiveId: record.id, agent: record.source.agent });
+    }
+    let trash = null;
+    try {
+        // Windows' native Recycle Bin API does not return the moved pathname, so
+        // it cannot roll the original back if pointer installation fails. A Codex
+        // pointer therefore uses Sealkeep's own recoverable Trash on Windows.
+        const requestedStrategy = options.strategy ?? defaultStrategy();
+        const strategy = stub && requestedStrategy === "windows-recycle-bin" ? "sealkeep-trash" : requestedStrategy;
+        await assertReclaimAuthorized(options.authorizeReclaim, record.id);
+        trash = await (options.operations?.moveToTrash ?? moveToTrash)(record.source.path, { dataDir, home: options.home, strategy });
+        if (stub)
+            await (options.operations?.installResumeStub ?? installCodexResumeStub)(stub);
+        return { trash, stub };
+    }
+    catch (error) {
+        await discardCodexResumeStub(stub);
+        // macOS, XDG and Sealkeep-owned Trash all return a real path. Codex never
+        // reaches this branch with the pathless Windows Recycle Bin strategy.
+        if (trash && trash.strategy !== "windows-recycle-bin") {
+            const sourceMissing = !(await stat(record.source.path).catch(() => null));
+            const trashed = await stat(trash.movedTo).catch(() => null);
+            if (sourceMissing && trashed?.isFile())
+                await rename(trash.movedTo, record.source.path).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+function resumeStubRecord(stub) {
+    return stub ? { resumeStub: { version: 1, sessionId: stub.sessionId, bytes: stub.bytes, sha256: stub.sha256 } } : {};
+}
+function transactionAllocatedBytesFreed(transaction) {
+    return Math.max(0, transaction.original.allocatedBytes - (transaction.replacement?.allocatedBytes ?? 0));
+}
+function hasPlausibleFinalFreedBytes(reclaimed, transaction) {
+    return reclaimed.stagingPath === undefined
+        && typeof reclaimed.purgedAt === "string"
+        && Number.isSafeInteger(reclaimed.freedBytes)
+        && (reclaimed.freedBytes ?? -1) >= 0
+        && (reclaimed.freedBytes ?? Number.MAX_SAFE_INTEGER) <= transactionAllocatedBytesFreed(transaction);
+}
+/** Put the exact original back without ever overwriting content written after the move. */
+async function rollbackReclaimMove(record, moved) {
+    if (moved.trash.strategy === "windows-recycle-bin") {
+        throw new Error("The source entered the Windows Recycle Bin and cannot be rolled back automatically");
+    }
+    const trashed = await stat(moved.trash.movedTo).catch(() => null);
+    if (!trashed?.isFile())
+        throw new Error(`The reclaimed original is not available at ${moved.trash.movedTo}`);
+    if (!moved.stub) {
+        if (await stat(record.source.path).catch(() => null))
+            throw new Error(`Refusing to overwrite new content at ${record.source.path}`);
+        await rename(moved.trash.movedTo, record.source.path);
+        return;
+    }
+    const pointer = await readUntouchedCodexResumeStub(record.source.path);
+    if (!pointer
+        || pointer.archiveId !== record.id
+        || pointer.sessionId !== moved.stub.sessionId
+        || pointer.bytes !== moved.stub.bytes
+        || pointer.sha256 !== moved.stub.sha256) {
+        throw new Error(`The Codex resume pointer changed before rollback; refusing to overwrite ${record.source.path}`);
+    }
+    // Park the pointer with rename and restore the original. Retain the tiny
+    // parked pointer even after success: Codex may have opened its old inode
+    // before the rename and can append a resumed turn through that fd. Unlinking
+    // it here would silently discard that turn. If restoration fails, atomically
+    // put the pointer back so Codex's catalog is never left with a missing path.
+    const parked = `${moved.stub.tempPath}.rollback`;
+    await rename(record.source.path, parked);
+    try {
+        await rename(moved.trash.movedTo, record.source.path);
+    }
+    catch (error) {
+        await rename(parked, record.source.path).catch(() => undefined);
+        throw error;
+    }
+}
+async function commitReclaim(dataDir, storageRoot, record, moved, reclaimedAt, detail, operations = {}) {
+    const transaction = moved.transaction;
+    const reclaimed = transaction ? {
+        at: reclaimedAt,
+        strategy: "purged",
+        transactionId: transaction.id,
+        stagingPath: transaction.trashPath,
+        originalBytes: transaction.original.bytes,
+        ...resumeStubRecord(moved.stub),
+    } : {
+        // Injectable legacy seams deliberately retain their recoverable Trash
+        // behavior. Real Free-up-disk calls always use the durable purge path.
+        at: reclaimedAt,
+        trashPath: moved.trash.movedTo,
+        strategy: moved.trash.strategy,
+        ...resumeStubRecord(moved.stub),
+    };
+    const mutate = operations.mutateRecord ?? mutateArchiveRecord;
+    const audit = operations.audit ?? recordAudit;
+    const matchesReclaimed = (current) => current !== undefined
+        && isV2(current)
+        && current.reclaimed?.at === reclaimed.at
+        && current.reclaimed.strategy === reclaimed.strategy
+        && current.reclaimed.transactionId === reclaimed.transactionId
+        && current.reclaimed.originalBytes === reclaimed.originalBytes
+        && (transaction
+            ? current.reclaimed.stagingPath === transaction.trashPath || (hasPlausibleFinalFreedBytes(current.reclaimed, transaction))
+            : current.reclaimed.trashPath === reclaimed.trashPath)
+        && current.reclaimed.resumeStub?.sessionId === reclaimed.resumeStub?.sessionId
+        && current.reclaimed.resumeStub?.bytes === reclaimed.resumeStub?.bytes
+        && current.reclaimed.resumeStub?.sha256 === reclaimed.resumeStub?.sha256;
+    const readCurrent = async () => {
+        try {
+            return JSON.parse(await readFile(join(storageRoot, `${record.id}.json`), "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    };
+    try {
+        await mutate(storageRoot, record.id, (current) => isV2(current) ? { ...current, reclaimed } : current);
+        if (!transaction || !moved.lock) {
+            await audit(dataDir, "source.reclaim", "allowed", detail);
+            return { freedBytes: 0 };
+        }
+        await markReclaimMetadataCommitted(transaction, moved.lock);
+        const expectedFreedBytes = transactionAllocatedBytesFreed(transaction);
+        const auditDetail = {
+            ...detail,
+            transactionId: transaction.id,
+            purgeAuthorized: true,
+            expectedFreedBytes,
+        };
+        // Audit first. The journal's purge-authorized stage is the durable proof
+        // that both record metadata and this decision reached storage.
+        await audit(dataDir, "source.reclaim", "allowed", auditDetail);
+        await markReclaimPurgeAuthorized(transaction, moved.lock);
+        if (!moved.verifyPurgeStillSafe) {
+            throw new Error("Reclaim cannot purge without a fresh provider proof at the irreversible boundary");
+        }
+        let purgedAt;
+        const finalized = await finalizeReclaimTransaction(transaction, moved.lock, {
+            onPurged: async (_currentTransaction, freedBytes) => {
+                purgedAt = new Date().toISOString();
+                await mutate(storageRoot, record.id, (current) => {
+                    if (!matchesReclaimed(current))
+                        throw new Error("Archive reclaim metadata changed before purge finalization");
+                    if (current.reclaimed?.purgedAt && hasPlausibleFinalFreedBytes(current.reclaimed, transaction)) {
+                        purgedAt = current.reclaimed.purgedAt;
+                        return current;
+                    }
+                    const { stagingPath: _stagingPath, ...committed } = current.reclaimed;
+                    return { ...current, reclaimed: { ...committed, purgedAt, freedBytes } };
+                });
+            },
+            verifyPurgeStillSafe: moved.verifyPurgeStillSafe,
+            io: { onYield: operations.cooperate },
+        });
+        return { freedBytes: finalized.freedBytes, ...(purgedAt ? { purgedAt } : {}) };
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        // Once the authorized staging name is gone, the irreversible unlink has
+        // happened. Do not infer that from a generic stat failure: only ENOENT is
+        // proof of absence. Any other inspection error keeps the journal and all
+        // remaining names untouched for reconciliation.
+        if (transaction?.stage === "purge-authorized") {
+            try {
+                await stat(transaction.trashPath);
+            }
+            catch (stagingError) {
+                if (stagingError.code === "ENOENT") {
+                    throw new AggregateError([error], "Source bytes were purged safely; final metadata will be completed from the durable journal");
+                }
+                rollbackErrors.push(stagingError);
+            }
+        }
+        // Clear this exact metadata commit before putting the original back. If
+        // the clear cannot commit, leave the journaled pointer/staging pair intact;
+        // the next run will complete it instead of creating an unauthenticated
+        // pointer or overwriting user bytes.
+        // A mutation can become durable and then throw (for example its parent
+        // directory fsync reports an error after rename). Re-read the exact record
+        // after *every* failure; an in-memory boolean cannot distinguish that
+        // window from a mutation that never landed.
+        let current;
+        try {
+            current = await readCurrent();
+        }
+        catch (readError) {
+            rollbackErrors.push(readError);
+        }
+        if (current && isV2(current) && current.reclaimed && !matchesReclaimed(current)) {
+            rollbackErrors.push(new Error("Archive reclaim metadata changed before rollback"));
+        }
+        else if (matchesReclaimed(current)) {
+            let clearError;
+            await mutate(storageRoot, record.id, (latest) => {
+                if (!matchesReclaimed(latest))
+                    throw new Error("Archive reclaim metadata changed before rollback");
+                const { reclaimed: _removed, ...restored } = latest;
+                return restored;
+            }).catch((error) => { clearError = error; });
+            // The clear has the same rename-then-fsync ambiguity as the initial
+            // write. Inspect its durable result before deciding whether the byte
+            // rollback is safe.
+            try {
+                const afterClear = await readCurrent();
+                if (afterClear && isV2(afterClear) && afterClear.reclaimed) {
+                    rollbackErrors.push(clearError ?? new Error("Archive reclaim metadata could not be cleared before rollback"));
+                }
+            }
+            catch (readError) {
+                rollbackErrors.push(clearError
+                    ? new AggregateError([clearError, readError], "Could not verify reclaim metadata rollback")
+                    : readError);
+            }
+        }
+        if (rollbackErrors.length === 0) {
+            if (transaction && moved.lock) {
+                await rollbackReclaimTransaction(transaction, moved.lock, { io: { onYield: operations.cooperate } })
+                    .catch((rollback) => rollbackErrors.push(rollback));
+            }
+            else {
+                await rollbackReclaimMove(record, moved).catch((rollback) => rollbackErrors.push(rollback));
+            }
+        }
+        if (rollbackErrors.length > 0) {
+            throw new AggregateError([error, ...rollbackErrors], "Reclamation failed and could not be rolled back completely");
+        }
+        throw error;
+    }
+}
+function transactionMatchesReclaim(record, transaction) {
+    if (!record || !isV2(record))
+        return false;
+    const pointer = record.reclaimed?.resumeStub;
+    return record.id === transaction.id
+        && record.source.path === transaction.sourcePath
+        && record.source.bytes === transaction.original.bytes
+        && record.source.sha256 === transaction.original.sha256
+        && record.reclaimed?.transactionId === transaction.id
+        && record.reclaimed?.strategy === "purged"
+        && record.reclaimed.originalBytes === transaction.original.bytes
+        && (record.reclaimed.stagingPath === transaction.trashPath
+            || hasPlausibleFinalFreedBytes(record.reclaimed, transaction))
+        && (transaction.replacement ? (pointer?.version === 1
+            && codexSessionIdMatchesFilename(transaction.sourcePath, pointer.sessionId)
+            && pointer.bytes === transaction.replacement.bytes
+            && pointer.sha256 === transaction.replacement.sha256) : pointer === undefined);
+}
+/** Resolve kill -9 windows before starting another native source reclaim. */
+export async function reconcileCodexReclaims(dataDir, storageRoot, home, remoteCheck, cooperate, activity = {}, signal, remoteBytesPerSecond, remoteFetch, authorizeReclaim, phrase, indexOperations = {}) {
+    const canonicalHome = home;
+    await reconcileReclaimTransactions(dataDir, {
+        validateTransaction: async (transaction) => {
+            const records = await listArchives(dataDir);
+            const record = records.find((candidate) => candidate.id === transaction.id);
+            if (!record
+                || record.source.path !== transaction.sourcePath
+                || record.source.bytes !== transaction.original.bytes
+                || record.source.sha256 !== transaction.original.sha256) {
+                throw new Error("Reclaim journal does not match its immutable archive source");
+            }
+            if (transaction.replacement) {
+                await validateNativeCodexSessionPath(transaction.sourcePath, canonicalHome, "missing-or-file");
+                await validateNativeCodexSessionPath(transaction.replacement.tempPath, canonicalHome, "missing-or-file");
+                assertCodexResumePointerTempPath(transaction.replacement.tempPath);
+                // A journal is not authority to publish or unlink whichever file its
+                // tempPath names. Bind every surviving exact replacement candidate to
+                // this archive and logical native session before reconciliation can
+                // touch it. Mismatched candidates are retained by generic inode/hash
+                // checks; matching-but-malformed candidates fail closed here.
+                await validateCodexResumePointerBinding(transaction.replacement.tempPath, transaction.sourcePath, transaction.id, transaction.replacement);
+                await validateCodexResumePointerBinding(transaction.sourcePath, transaction.sourcePath, transaction.id, transaction.replacement);
+            }
+            else {
+                const resolvedHome = canonicalHome ?? homedir();
+                const roots = record.source.agent === "claude"
+                    ? NATIVE_ROOTS.claude(resolvedHome)
+                    : record.source.agent === "codex"
+                        ? NATIVE_ROOTS.codex(resolvedHome)
+                        : [];
+                if (roots.length === 0)
+                    throw new Error(`No safe native reclaim root for agent ${record.source.agent}`);
+                await validateNoFollowPath(transaction.sourcePath, roots, { leaf: "missing-or-file" });
+            }
+        },
+        validatePurgeCandidate: async (transaction) => {
+            const staged = await stat(transaction.trashPath).catch((error) => {
+                if (error.code === "ENOENT")
+                    return null;
+                throw error;
+            });
+            // A daemon restart is not authority to finish an earlier deletion after
+            // the person has since turned reclaim off or selected a safe policy. The
+            // sole exception is a purge-authorized journal whose staged inode is
+            // already absent: the irreversible unlink happened before the crash, so
+            // reconciliation is only finishing truthful metadata and journal cleanup.
+            if (staged || transaction.stage !== "purge-authorized") {
+                await assertReclaimAuthorized(authorizeReclaim, transaction.id);
+            }
+            if (!transaction.replacement)
+                return;
+            // An old binary may have staged a multi-agent child before this release
+            // learned that installed Codex cannot resume it independently. Re-parse
+            // whichever exact original name still survives, against the logical
+            // rollout filename, before allowing reconciliation to advance. If an
+            // authorized purge already completed there are no bytes left to restore;
+            // final metadata can only be completed conservatively.
+            const contentsPath = staged?.isFile()
+                ? transaction.trashPath
+                : transaction.stage === "prepared"
+                    ? transaction.sourcePath
+                    : null;
+            if (contentsPath) {
+                await assertCodexResumePointerMetadataSupported(contentsPath, transaction.sourcePath);
+            }
+        },
+        isMetadataCommitted: async (transaction) => {
+            const records = await listArchives(dataDir);
+            return transactionMatchesReclaim(records.find((record) => record.id === transaction.id), transaction);
+        },
+        clearMetadataCommit: async (transaction) => {
+            await mutateArchiveRecord(storageRoot, transaction.id, (current) => {
+                if (!transactionMatchesReclaim(current, transaction))
+                    throw new Error("Archive reclaim metadata changed before crash rollback");
+                const { reclaimed: _removed, ...restored } = current;
+                return restored;
+            });
+        },
+        verifyPurgeStillSafe: async (transaction) => {
+            // A crash may be reconciled minutes or days later, including after the
+            // purge-authorization record landed. Authorization is not a lease on an
+            // external object, so repeat the provider proof whenever staged bytes
+            // still exist immediately before their unlink.
+            const publication = await verifyCurrentDurabilityImmediatelyBeforePurge(dataDir, transaction.id, transaction.sourcePath, remoteCheck, activity, {
+                signal,
+                cooperate,
+                bytesPerSecond: remoteBytesPerSecond,
+                fetchRemoteCopy: remoteFetch,
+                phrase,
+                verifyIndexPublication: indexOperations.verifyIndexPublication,
+            });
+            const finalStagedActivity = await isSourceActive(transaction.trashPath, {
+                ...activity,
+                now: Date.now(),
+            });
+            if (finalStagedActivity.active) {
+                throw new Error(`The staged session is still open: ${finalStagedActivity.reason}`);
+            }
+            await assertReclaimAuthorized(authorizeReclaim, transaction.id);
+            await (indexOperations.recheckIndexPublication
+                ? indexOperations.recheckIndexPublication(dataDir, publication, signal)
+                : recheckManagedAccountIndexPublicationBeforeUnlink({ dataDir, verification: publication, signal }));
+        },
+        ensureAuditCommitted: async (transaction) => {
+            await recordAudit(dataDir, "source.reclaim", "allowed", {
+                archiveId: transaction.id,
+                path: transaction.sourcePath,
+                transactionId: transaction.id,
+                strategy: "purged",
+                purgeAuthorized: true,
+                expectedFreedBytes: transactionAllocatedBytesFreed(transaction),
+                resumeStub: Boolean(transaction.replacement),
+                reconciled: true,
+            });
+        },
+        onPurged: async (transaction, freedBytes) => {
+            await mutateArchiveRecord(storageRoot, transaction.id, (current) => {
+                if (!transactionMatchesReclaim(current, transaction)) {
+                    throw new Error("Archive reclaim metadata changed before crash finalization");
+                }
+                if (current.reclaimed?.purgedAt && hasPlausibleFinalFreedBytes(current.reclaimed, transaction))
+                    return current;
+                const { stagingPath: _stagingPath, ...committed } = current.reclaimed;
+                return {
+                    ...current,
+                    reclaimed: { ...committed, purgedAt: new Date().toISOString(), freedBytes },
+                };
+            });
+        },
+        io: { onYield: cooperate },
+    });
+}
 /**
  * Reclaims eligible sources. Dry-run is the default: without `confirm`, nothing on
- * disk changes. Reclaimed files go to the OS trash, never to `unlink`.
+ * disk changes. Confirmed, verified sources are transaction-staged and then
+ * permanently purged; Codex receives a tiny same-id resume pointer.
  */
 export async function applyRetention(dataDir, options = {}) {
     const config = await readConfig(dataDir);
+    const cooperate = options.operations?.cooperate ?? (options.backgroundCpuTarget === undefined
+        ? undefined
+        : createBackgroundCpuYield({ target: options.backgroundCpuTarget, signal: options.signal }));
+    // Reconciliation runs before candidate evaluation because it must repair a
+    // previous kill -9 window first. That ordering must not turn a preview into
+    // deletion authority. A confirmed foreground pass is bounded by the current
+    // persisted policy (and current per-id approval); a daemon pass must satisfy
+    // that policy AND its machine-local live gate.
+    const authorizeReclaim = options.confirm === true
+        ? confirmedRetentionAuthorization(dataDir, options.authorizeReclaim)
+        : denyReclaimAuthorization;
+    await reconcileCodexReclaims(dataDir, config.storage.root, options.home, options.operations?.checkRemoteCopy, cooperate, options.activity, options.signal, options.backgroundRemoteBytesPerSecond, options.operations?.fetchRemoteCopy, authorizeReclaim, options.phrase, options.operations);
     const evaluation = await evaluateRetention(dataDir, options);
     const eligible = evaluation.candidates.filter((candidate) => candidate.eligible);
     if (!options.confirm) {
-        return { mode: "dry-run", policy: evaluation.policy, wouldReclaim: eligible.length, wouldFreeBytes: evaluation.reclaimableBytes, candidates: evaluation.candidates };
+        return {
+            mode: "dry-run", policy: evaluation.policy, wouldReclaim: eligible.length,
+            wouldFreeBytes: evaluation.reclaimableBytes,
+            wouldMoveBytes: eligible.reduce((total, candidate) => total + candidate.bytes, 0),
+            candidates: evaluation.candidates
+        };
     }
     const records = new Map((await listArchives(dataDir)).map((record) => [record.id, record]));
     const reclaimed = [];
     const failed = [];
     for (const candidate of eligible) {
+        // Stop the batch on a revoked/unreadable live authorization. Continuing to
+        // inspect hundreds of candidates cannot become safer within this pass.
         try {
-            const result = await moveToTrash(candidate.path, { dataDir, home: options.home, strategy: options.strategy });
+            await assertReclaimAuthorized(authorizeReclaim, candidate.id);
+        }
+        catch (error) {
+            failed.push({ id: candidate.id, error: error instanceof Error ? error.message : "automatic reclaim is no longer allowed" });
+            break;
+        }
+        try {
+            // The evaluation ran one lsof per candidate before this loop — a wide
+            // window on a long batch. What is moved must still be what was verified.
             const record = records.get(candidate.id);
-            if (isV2(record)) {
-                const next = { ...record, reclaimed: { at: new Date(options.now ?? Date.now()).toISOString(), trashPath: result.movedTo, strategy: result.strategy } };
-                await writeRecord(config.storage.root, next);
+            const remoteChain = completeRemoteChain([...records.values()], record);
+            if (!remoteChain.complete)
+                throw new Error("The complete remote archive chain changed before reclaim; the local original was kept");
+            const lock = await acquireReclaimSourceLock(dataDir, record.source.path);
+            try {
+                await verifySourceImmediatelyBeforeReclaim(record, cooperate);
+                const moved = await moveReclaimableSource(dataDir, record, {
+                    home: options.home,
+                    strategy: options.strategy,
+                    operations: options.operations,
+                    lock,
+                    activity: options.activity,
+                    now: options.now,
+                    remoteChain: remoteChain.chain,
+                    cooperate,
+                    signal: options.signal,
+                    remoteBytesPerSecond: options.backgroundRemoteBytesPerSecond,
+                    phrase: options.phrase,
+                    authorizeReclaim,
+                    assertStillAllowed: async () => {
+                        if (isPinned(record.source.path, await neverReclaimMarks(dataDir))) {
+                            fail("invalid_argument", "This session was pinned while reclaim was running, so the original was kept.", { archiveId: record.id });
+                        }
+                        const stillActive = await isSourceActive(record.source.path, {
+                            ...options.activity,
+                            now: options.now ?? Date.now(),
+                        });
+                        if (stillActive.active) {
+                            fail("invalid_argument", `The session became active while reclaim was running: ${stillActive.reason}. The original was kept.`, { archiveId: record.id });
+                        }
+                    },
+                });
+                const result = moved.trash;
+                if (isV2(record)) {
+                    const reclaimedAt = new Date(options.now ?? Date.now()).toISOString();
+                    const committed = await commitReclaim(dataDir, config.storage.root, record, moved, reclaimedAt, {
+                        archiveId: candidate.id,
+                        path: candidate.path,
+                        bytes: candidate.bytes,
+                        stagingPath: result.movedTo,
+                        strategy: moved.transaction ? "purged" : result.strategy,
+                        ...(moved.stub ? { resumeStub: true, sessionId: moved.stub.sessionId, resumeStubBytes: moved.stub.bytes } : {}),
+                    }, options.operations);
+                    reclaimed.push({
+                        id: candidate.id,
+                        path: candidate.path,
+                        bytes: candidate.bytes,
+                        movedTo: committed.purgedAt ? "" : result.movedTo,
+                        strategy: committed.purgedAt ? "purged" : result.strategy,
+                        freedBytes: committed.freedBytes,
+                        ...(committed.purgedAt ? { purgedAt: committed.purgedAt } : {}),
+                        ...(moved.stub ? { resumeStub: { sessionId: moved.stub.sessionId, bytes: moved.stub.bytes } } : {}),
+                    });
+                }
+            }
+            finally {
+                await lock.release();
             }
-            await recordAudit(dataDir, "source.reclaim", "allowed", { archiveId: candidate.id, path: candidate.path, bytes: candidate.bytes, movedTo: result.movedTo, strategy: result.strategy });
-            reclaimed.push({ id: candidate.id, path: candidate.path, bytes: candidate.bytes, movedTo: result.movedTo, strategy: result.strategy });
         }
         catch (error) {
-            await recordAudit(dataDir, "source.reclaim", "denied", { archiveId: candidate.id, path: candidate.path });
+            await (options.operations?.audit ?? recordAudit)(dataDir, "source.reclaim", "denied", { archiveId: candidate.id, path: candidate.path }).catch(() => undefined);
             failed.push({ id: candidate.id, error: error instanceof Error ? error.message : "reclamation failed" });
         }
     }
-    return { mode: "apply", policy: evaluation.policy, reclaimed, failed, freedBytes: reclaimed.reduce((total, item) => total + item.bytes, 0), protected: evaluation.candidates.length - eligible.length };
+    const movedBytes = reclaimed.reduce((total, item) => total + item.bytes, 0);
+    const freedBytes = reclaimed.reduce((total, item) => total + item.freedBytes, 0);
+    return {
+        mode: "apply", policy: evaluation.policy, reclaimed, failed,
+        freedBytes, movedBytes, protected: evaluation.candidates.length - eligible.length
+    };
 }
 /**
  * Reclaims ONE source, because a person pointed at it.
@@ -218,16 +1155,25 @@ export async function applyRetention(dataDir, options = {}) {
  *
  *  - the archive must have a verified remote copy (and a delta head's whole
  *    chain must be verified — one unverified base and the cloud cannot
- *    reproduce the file this is about to trash);
+ *    reproduce the file this is about to reclaim);
+ *  - this exact archive must be covered by the search index, so durable memory
+ *    is also memory a fresh agent can actually find;
  *  - the source must be byte-for-byte the file that was archived — a session
  *    that grew since has content in no archive at all;
  *  - nothing may have the file open right now.
  *
- * Policy, age and grace are deliberately not consulted. Trash, never unlink,
- * same as everywhere.
+ * Policy, age and grace are deliberately not consulted. The explicit click is
+ * the irreversible-delete approval; all durability/search/activity gates still
+ * run immediately before the transaction commits.
  */
 export async function reclaimOne(dataDir, archiveId, options = {}) {
     const config = await readConfig(dataDir);
+    const cooperate = options.operations?.cooperate;
+    // A direct confirmed click is authority for exactly the selected archive,
+    // never for another crash journal found beside it. An unconfirmed request is
+    // a preview/refusal and may only drive conservative rollback.
+    const authorizeReconciliation = async (pendingArchiveId) => options.confirm === true && pendingArchiveId === archiveId;
+    await reconcileCodexReclaims(dataDir, config.storage.root, options.home, options.operations?.checkRemoteCopy, cooperate, options.activity, undefined, undefined, options.operations?.fetchRemoteCopy, authorizeReconciliation, options.phrase, options.operations);
     const archives = await listArchives(dataDir);
     const record = archives.find((item) => item.id === archiveId);
     if (!record)
@@ -235,40 +1181,94 @@ export async function reclaimOne(dataDir, archiveId, options = {}) {
     if (!isV2(record))
         fail("invalid_argument", `Archive ${archiveId} uses format v1. Run: sealkeep migrate`, { archiveId });
     if (record.reclaimed)
-        fail("invalid_argument", "This source was already reclaimed — it is in your trash, not on this list.");
+        fail("invalid_argument", "This source was already reclaimed from this machine.");
     const current = await stat(record.source.path).catch(() => null);
     if (!current)
         fail("source_unreadable", "The source file is no longer at its recorded path, so there is nothing to reclaim.", { path: record.source.path });
     if (current.size !== record.source.bytes) {
         fail("invalid_argument", `The session changed since it was archived (${record.source.bytes} bytes archived, ${current.size} now) — re-archive it first, or reclaiming would delete exactly the part no archive holds.`, { archiveId });
     }
-    if (!record.remote?.verifiedAt) {
-        fail("invalid_argument", "No verified cloud copy exists for this archive, so this disk holds the only bytes. Upload it first.", { archiveId });
+    const remoteChain = completeRemoteChain(archives, record);
+    if (!remoteChain.complete) {
+        const unverified = remoteChain.chain.filter((link) => !(isV2(link) && hasVerifiedCopy(link))).length;
+        fail("invalid_argument", remoteChain.chain.length === 0
+            ? "This snapshot builds on an earlier archive that is missing, so the cloud cannot reproduce the file. Keep the source."
+            : unverified > 0
+                ? "No verified cloud copy exists for every archive in this snapshot's chain, so this disk may hold the only bytes. Upload the complete chain first."
+                : "This snapshot's verified copies are split across storage destinations, so no one destination can reproduce the file. Upload the complete chain to one destination first.", { archiveId });
     }
-    const { deltaOf, resolveDeltaChain } = await import("./vault.js");
-    if (deltaOf(record)) {
-        try {
-            const chain = resolveDeltaChain(archives, record);
-            const unverified = chain.filter((link) => !(isV2(link) && link.remote?.verifiedAt)).length;
-            if (unverified > 0)
-                fail("invalid_argument", `This snapshot builds on earlier archives and ${unverified} of the chain ${unverified === 1 ? "is" : "are"} not verified in the cloud yet — the cloud cannot reproduce this file without them.`, { archiveId });
-        }
-        catch (error) {
-            if (isVaultlineError(error))
-                throw error;
-            fail("invalid_argument", "This snapshot builds on an earlier archive that is missing, so the cloud cannot reproduce the file. Keep the source.", { archiveId });
-        }
+    const indexed = await indexedArchiveIds(dataDir, archives);
+    if (!indexed?.has(record.id)) {
+        fail("invalid_argument", indexed
+            ? "This archive is safely stored but not searchable yet. Sealkeep is still indexing it, so the original stays on this disk for now."
+            : "Sealkeep could not confirm this archive is in the search index, so the original stays on this disk.", { archiveId });
     }
     const activity = await isSourceActive(record.source.path, { ...options.activity, now: options.now ?? Date.now() });
     if (activity.active)
         fail("invalid_argument", `The file looks in use right now: ${activity.reason}. Close it and try again.`, { archiveId });
     if (!options.confirm)
-        fail("invalid_argument", "Pass confirm to move this source to the trash.");
-    const result = await moveToTrash(record.source.path, { dataDir, home: options.home, strategy: options.strategy });
-    const next = { ...record, reclaimed: { at: new Date(options.now ?? Date.now()).toISOString(), trashPath: result.movedTo, strategy: result.strategy } };
-    await writeRecord(config.storage.root, next);
-    await recordAudit(dataDir, "source.reclaim", "allowed", { archiveId, path: record.source.path, bytes: record.source.bytes, movedTo: result.movedTo, strategy: result.strategy, manual: true });
-    return { id: archiveId, path: record.source.path, bytes: record.source.bytes, movedTo: result.movedTo, strategy: result.strategy };
+        fail("invalid_argument", "Pass confirm to permanently free this source's local disk space.");
+    if (isPinned(record.source.path, await neverReclaimMarks(dataDir))) {
+        fail("invalid_argument", "This session is listed in never-reclaim — pinned on purpose. Edit <dataDir>/never-reclaim to release it.", { archiveId });
+    }
+    /**
+     * Re-checked at the last instant. The size gate above ran BEFORE the
+     * activity probe (which shells out to lsof — real wall-clock); an agent
+     * appending in that window could otherwise have its never-archived tail swept
+     * away with the verified part. What is purged must be what was verified.
+     */
+    const lock = await acquireReclaimSourceLock(dataDir, record.source.path);
+    try {
+        await verifySourceImmediatelyBeforeReclaim(record, cooperate);
+        const moved = await moveReclaimableSource(dataDir, record, {
+            home: options.home,
+            strategy: options.strategy,
+            operations: options.operations,
+            lock,
+            activity: options.activity,
+            now: options.now,
+            remoteChain: remoteChain.chain,
+            cooperate,
+            signal: options.signal,
+            phrase: options.phrase,
+            assertStillAllowed: async () => {
+                if (isPinned(record.source.path, await neverReclaimMarks(dataDir))) {
+                    fail("invalid_argument", "This session was pinned while reclaim was running, so the original was kept.", { archiveId });
+                }
+                const stillActive = await isSourceActive(record.source.path, {
+                    ...options.activity,
+                    now: options.now ?? Date.now(),
+                });
+                if (stillActive.active) {
+                    fail("invalid_argument", `The session became active while reclaim was running: ${stillActive.reason}. The original was kept.`, { archiveId });
+                }
+            },
+        });
+        const result = moved.trash;
+        const reclaimedAt = new Date(options.now ?? Date.now()).toISOString();
+        const committed = await commitReclaim(dataDir, config.storage.root, record, moved, reclaimedAt, {
+            archiveId,
+            path: record.source.path,
+            bytes: record.source.bytes,
+            stagingPath: result.movedTo,
+            strategy: moved.transaction ? "purged" : result.strategy,
+            manual: true,
+            ...(moved.stub ? { resumeStub: true, sessionId: moved.stub.sessionId, resumeStubBytes: moved.stub.bytes } : {}),
+        }, options.operations);
+        return {
+            id: archiveId,
+            path: record.source.path,
+            bytes: record.source.bytes,
+            movedTo: committed.purgedAt ? "" : result.movedTo,
+            strategy: committed.purgedAt ? "purged" : result.strategy,
+            freedBytes: committed.freedBytes,
+            ...(committed.purgedAt ? { purgedAt: committed.purgedAt } : {}),
+            ...(moved.stub ? { resumeStub: { sessionId: moved.stub.sessionId, bytes: moved.stub.bytes } } : {}),
+        };
+    }
+    finally {
+        await lock.release();
+    }
 }
 /**
  * `reclaimOne` over a selection. Each row passes or is kept with its reason —
@@ -286,7 +1286,13 @@ export async function reclaimBatch(dataDir, ids, options = {}) {
             kept.push({ id, reason: error instanceof Error ? error.message : "could not reclaim" });
         }
     }
-    return { reclaimed, kept, freedBytes: reclaimed.reduce((total, item) => total + item.bytes, 0) };
+    const movedBytes = reclaimed.reduce((total, item) => total + item.bytes, 0);
+    return {
+        reclaimed,
+        kept,
+        freedBytes: reclaimed.reduce((total, item) => total + item.freedBytes, 0),
+        movedBytes,
+    };
 }
 export async function setRetentionPolicy(dataDir, settings) {
     if (settings.policy && !POLICIES.includes(settings.policy))
@@ -304,9 +1310,7 @@ export async function setRetentionPolicy(dataDir, settings) {
             fail("invalid_argument", `${key} must be a non-negative number, or null to ignore it`);
     }
     const config = await readConfig(dataDir);
-    const next = { ...config, retention: retentionSettings(config, settings) };
-    await writeConfig(dataDir, next);
-    return next;
+    return updateConfigFields(dataDir, { retention: retentionSettings(config, settings) });
 }
 /**
  * Snapshots whose every byte is already inside a newer archive of the same file.
@@ -369,7 +1373,7 @@ export async function redundantArchives(dataDir) {
         const heirObject = await stat(heir.objectPath).catch(() => null);
         if (!heirObject)
             continue;
-        if (config.remoteStorage && !(isV2(heir) && heir.remote?.verifiedAt))
+        if (config.remoteStorage && !(isV2(heir) && hasVerifiedCopy(heir)))
             continue;
         const own = await stat(record.objectPath).catch(() => null);
         if (!own)