sealkeep 0.9.0 → 0.11.0

package/dist/src/resume-stub.js

@@ -0,0 +1,417 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, open, realpath, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { openForFlush } from "./flush.js";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { validateNoFollowPath } from "./reclaim-transaction.js";
+/**
+ * A stable, model-visible marker.  It deliberately lives in an ordinary Codex
+ * message rather than in a made-up rollout record type: old and new Codex
+ * builds may ignore fields they do not know, but the conversation loader has
+ * always understood user/assistant messages.
+ */
+export const CODEX_RESUME_STUB_MARKER = "sealkeep://codex-resume-stub/v1";
+const MAX_STUB_BYTES = 1024 * 1024;
+const MAX_META_BYTES = 1024 * 1024;
+const PREPARED_STUB_BASENAME = /^\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.sealkeep-resume-stub\.partial$/i;
+const POINTER_OPEN_FLAGS = fsConstants.O_RDONLY
+    | (typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0)
+    | (typeof fsConstants.O_NONBLOCK === "number" ? fsConstants.O_NONBLOCK : 0);
+function samePointerSnapshot(left, right) {
+    return right.isFile() && left.dev === right.dev && left.ino === right.ino && left.size === right.size
+        && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+/** A growing rollout must not turn a <=1 MiB stat into an unbounded readFile. */
+async function readStablePointer(handle, path, before) {
+    if (!before.isFile() || before.size < 0n || before.size > BigInt(MAX_STUB_BYTES)) {
+        throw new Error(`Codex resume pointer candidate exceeds the regular-file read bound and was retained: ${path}`);
+    }
+    // One extra byte detects growth even on filesystems with coarse timestamps.
+    // The allocation and total bytes read remain bounded regardless of appends.
+    const buffer = Buffer.alloc(Number(before.size) + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+        if (!bytesRead)
+            break;
+        offset += bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    const named = await lstat(path, { bigint: true });
+    if (offset !== Number(before.size) || !samePointerSnapshot(before, after) || !samePointerSnapshot(before, named)) {
+        throw new Error(`Codex resume pointer candidate changed while it was validated and was retained: ${path}`);
+    }
+    return buffer.subarray(0, offset);
+}
+/**
+ * Only real, non-symlinked native Codex rollout locations participate.
+ *
+ * Lexical containment is insufficient here: a symlinked `sessions` directory
+ * can make a path spell `~/.codex/sessions/...` while naming an unrelated file
+ * elsewhere. Check every user-controlled path component with lstat, then check
+ * canonical containment as a second independent condition.
+ */
+export async function isNativeCodexSessionPath(path, home = homedir()) {
+    return validateNativeCodexSessionPath(path, home, "file").then(() => true, () => false);
+}
+/** Canonical no-follow validation shared by reclaim and crash reconciliation. */
+export async function validateNativeCodexSessionPath(path, home = homedir(), leaf = "file") {
+    const lexicalHome = resolve(home);
+    const suffix = relative(lexicalHome, resolve(path));
+    if (suffix === "" || suffix.startsWith(`..${sep}`) || suffix === ".." || isAbsolute(suffix)) {
+        throw new Error(`Codex session path is outside the selected home: ${path}`);
+    }
+    const canonicalHome = await realpath(lexicalHome).catch(() => null);
+    if (!canonicalHome)
+        throw new Error(`Codex home is unavailable: ${lexicalHome}`);
+    const candidate = join(canonicalHome, suffix);
+    await validateNoFollowPath(candidate, [join(canonicalHome, ".codex", "sessions"), join(canonicalHome, ".codex", "archived_sessions")], { leaf });
+    return resolve(path);
+}
+async function firstLine(path) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const handle = await open(path, fsConstants.O_RDONLY | noFollow);
+    try {
+        const chunks = [];
+        let offset = 0;
+        while (offset <= MAX_META_BYTES) {
+            const chunk = Buffer.alloc(Math.min(64 * 1024, MAX_META_BYTES + 1 - offset));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, offset);
+            if (bytesRead === 0)
+                break;
+            const part = chunk.subarray(0, bytesRead);
+            const newline = part.indexOf(0x0a);
+            if (newline !== -1) {
+                chunks.push(part.subarray(0, newline));
+                return Buffer.concat(chunks).toString("utf8");
+            }
+            chunks.push(part);
+            offset += bytesRead;
+        }
+        if (offset > MAX_META_BYTES)
+            throw new Error(`Codex session metadata exceeds ${MAX_META_BYTES} bytes`);
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_IN_NAME = /(?:^|[^0-9a-f])([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(?=$|[^0-9a-f])/ig;
+/** The native filename, not a parent directory or a longer hex token, owns the session id. */
+export function codexSessionIdMatchesFilename(path, sessionId) {
+    // Index rows are searchable across operating systems, so recognize both
+    // separator styles even when this process did not create the path.
+    const filename = path.split(/[\\/]/).at(-1) ?? basename(path);
+    return [...filename.matchAll(UUID_IN_NAME)]
+        .some((match) => match[1]?.toLowerCase() === sessionId.toLowerCase());
+}
+function parseSessionMeta(line, path, options = {}) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        throw new Error(`Codex session ${path} has unreadable session metadata; keeping the original on disk`);
+    }
+    const payloadId = value?.payload?.id;
+    const payloadSessionId = value?.payload?.session_id;
+    const source = value?.payload?.source;
+    const subagentThreadSpawn = source && typeof source === "object" && !Array.isArray(source)
+        && source.subagent
+        && typeof source.subagent === "object"
+        && !Array.isArray(source.subagent)
+        && (source.subagent.thread_spawn)
+        && typeof (source.subagent.thread_spawn) === "object"
+        && !Array.isArray(source.subagent.thread_spawn)
+        ? source.subagent.thread_spawn
+        : null;
+    if (subagentThreadSpawn) {
+        // Direct resume is unproven for every structurally recognized child—not
+        // just today's dual-id shape. Installed Codex v0.152 rejects a real v2
+        // child until its parent is loaded, so variants with one/equal IDs must
+        // remain full transcripts until a parent-first protocol is proven.
+        const parentThreadId = subagentThreadSpawn.parent_thread_id;
+        const recognized = typeof payloadId === "string" && UUID.test(payloadId)
+            && typeof payloadSessionId === "string" && UUID.test(payloadSessionId)
+            && typeof parentThreadId === "string" && UUID.test(parentThreadId)
+            && parentThreadId.toLowerCase() === payloadSessionId.toLowerCase();
+        if (!options.allowRecognizedSubagent || !recognized) {
+            throw new Error(`Codex subagent session ${path} cannot be independently resumed by the installed Codex; keeping the original on disk`);
+        }
+    }
+    if (typeof payloadId === "string" && typeof payloadSessionId === "string"
+        && payloadId.toLowerCase() !== payloadSessionId.toLowerCase()
+        && !subagentThreadSpawn) {
+        throw new Error(`Codex session ${path} has conflicting session ids; keeping the original on disk`);
+    }
+    const id = payloadId ?? payloadSessionId;
+    const cwd = value?.payload?.cwd;
+    const rawTimestamp = value.timestamp ?? value?.payload?.timestamp;
+    if (value?.type !== "session_meta" || typeof id !== "string" || !UUID.test(id)
+        || typeof cwd !== "string" || !cwd.trim()
+        || typeof rawTimestamp !== "string" || !Number.isFinite(Date.parse(rawTimestamp))) {
+        throw new Error(`Codex session ${path} has unsupported session metadata; keeping the original on disk`);
+    }
+    // The catalog and the rollout must agree.  A pointer under the wrong UUID
+    // would make `codex resume <id>` open another session, which is worse than
+    // declining to reclaim a file.
+    if (!codexSessionIdMatchesFilename(path, id)) {
+        throw new Error(`Codex session id ${id} does not match an exact UUID token in its rollout filename; keeping the original on disk`);
+    }
+    const ordinal = typeof value.ordinal === "number" && Number.isSafeInteger(value.ordinal) && value.ordinal >= 0
+        ? value.ordinal
+        : undefined;
+    const relatedProcessSessionIds = [id];
+    if (typeof payloadSessionId === "string" && UUID.test(payloadSessionId)
+        && !relatedProcessSessionIds.some((candidate) => candidate.toLowerCase() === payloadSessionId.toLowerCase())) {
+        relatedProcessSessionIds.push(payloadSessionId);
+    }
+    return { sessionId: id, relatedProcessSessionIds, timestamp: rawTimestamp, cwd, ...(ordinal === undefined ? {} : { ordinal }) };
+}
+/** Validates that replacing this exact native rollout with a pointer is supported. */
+export async function assertCodexResumePointerSupported(path, home = homedir()) {
+    const canonical = await validateNativeCodexSessionPath(path, home, "file");
+    await assertCodexResumePointerMetadataSupported(canonical, canonical);
+}
+/**
+ * Re-validates a staged original against its logical native filename.
+ * Crash reconciliation uses this after upgrades: staging lives inside the
+ * vault, but the rollout UUID contract still belongs to the original path.
+ */
+export async function assertCodexResumePointerMetadataSupported(contentsPath, logicalNativePath) {
+    parseSessionMeta(await firstLine(resolve(contentsPath)), resolve(logicalNativePath));
+}
+/**
+ * A reclaim journal may outlive the binary that wrote it. Do not let such a
+ * journal turn an arbitrary neighbouring file into a replacement temp: only
+ * the private basename generated by prepareCodexResumeStub is eligible.
+ */
+export function assertCodexResumePointerTempPath(tempPath) {
+    if (!PREPARED_STUB_BASENAME.test(basename(resolve(tempPath)))) {
+        throw new Error(`Codex resume pointer temp has an unsupported name and was retained: ${tempPath}`);
+    }
+}
+function parseUntouchedPointerContents(raw, logicalNativePath, options = {}) {
+    const lines = raw.endsWith("\n") ? raw.slice(0, -1).split("\n") : raw.split("\n");
+    if (lines.length !== 3)
+        return null;
+    try {
+        const meta = parseSessionMeta(lines[0], resolve(logicalNativePath), options);
+        const message = JSON.parse(lines[1]);
+        const content = Array.isArray(message?.payload?.content) ? message.payload.content : [];
+        const text = content.length === 1 && content[0] && typeof content[0] === "object"
+            ? content[0].text
+            : null;
+        if (message.type !== "response_item" || message.payload?.type !== "message" || message.payload.role !== "user"
+            || typeof text !== "string" || !text.startsWith(`${CODEX_RESUME_STUB_MARKER}\n`))
+            return null;
+        const match = / as archive ([0-9a-f-]{36}), then reclaimed/.exec(text);
+        if (!match)
+            return null;
+        const final = JSON.parse(lines[2]);
+        if (final.type !== "response_item" || final.payload?.type !== "message" || final.payload.role !== "assistant")
+            return null;
+        return { version: 1, archiveId: match[1], sessionId: meta.sessionId };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Return true only when an existing pathname is the exact journaled pointer
+ * and its structured contents bind it to this native session and archive.
+ * A missing or fingerprint-mismatched pathname returns false because generic
+ * reconciliation already retains it. A matching-but-invalid pathname throws:
+ * deleting or publishing it based only on a journal-supplied hash would let a
+ * corrupt journal target an unrelated neighbouring file.
+ */
+export async function validateCodexResumePointerBinding(contentsPath, logicalNativePath, archiveId, expected) {
+    let handle;
+    try {
+        handle = await open(resolve(contentsPath), POINTER_OPEN_FLAGS);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile())
+            throw new Error(`Codex resume pointer candidate is not a regular file and was retained: ${contentsPath}`);
+        if (before.size !== BigInt(expected.bytes))
+            return false;
+        if (before.size > BigInt(MAX_STUB_BYTES)) {
+            throw new Error(`Codex resume pointer candidate exceeds ${MAX_STUB_BYTES} bytes and was retained: ${contentsPath}`);
+        }
+        const rawBuffer = await readStablePointer(handle, contentsPath, before);
+        const sha256 = createHash("sha256").update(rawBuffer).digest("hex");
+        if (sha256 !== expected.sha256)
+            return false;
+        // Binding is not an eligibility decision. An older release could have
+        // generated a structurally valid child pointer before direct child resume
+        // was disproven. Recognize only that narrow, internally consistent shape
+        // here so reconciliation may safely remove the pointer while restoring the
+        // full child rollout; normal pointer creation/reading still rejects it.
+        const pointer = parseUntouchedPointerContents(rawBuffer.toString("utf8"), logicalNativePath, {
+            allowRecognizedSubagent: true,
+        });
+        if (!pointer || pointer.archiveId.toLowerCase() !== archiveId.toLowerCase()) {
+            throw new Error(`Codex resume pointer candidate is not bound to archive ${archiveId} and was retained: ${contentsPath}`);
+        }
+        return true;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Own and validated parent IDs that may identify a live Codex process. */
+export async function codexSessionProcessIds(path) {
+    return parseSessionMeta(await firstLine(path), resolve(path)).relatedProcessSessionIds;
+}
+/** IDs plus project cwd used when a live Codex process has no UUID in argv. */
+export async function codexSessionProcessIdentity(path) {
+    const meta = parseSessionMeta(await firstLine(path), resolve(path));
+    return { ids: meta.relatedProcessSessionIds, cwd: meta.cwd };
+}
+function inputMessage(timestamp, text, ordinal) {
+    return {
+        ...(ordinal === undefined ? {} : { ordinal }),
+        timestamp,
+        type: "response_item",
+        payload: { type: "message", role: "user", content: [{ type: "input_text", text }] },
+    };
+}
+function outputMessage(timestamp, text, ordinal) {
+    return {
+        ...(ordinal === undefined ? {} : { ordinal }),
+        timestamp,
+        type: "response_item",
+        payload: { type: "message", role: "assistant", phase: "final_answer", content: [{ type: "output_text", text }] },
+    };
+}
+/**
+ * Builds the replacement beside the source, while the original is still
+ * present and fully verified. The caller transaction-stages the original first
+ * and then publishes this prepared file into its native path without
+ * overwriting a path the agent recreated in the meantime.
+ *
+ * The original session-meta line is kept byte-for-byte.  It is the format
+ * contract of the installed Codex build and carries the stable id, cwd, git
+ * project, source kind and original timestamp.  Even a large modern metadata
+ * line is tiny beside a multi-GB rollout and avoids guessing at vendor fields.
+ */
+export async function prepareCodexResumeStub(sourcePath, archiveId, options = {}) {
+    const path = resolve(sourcePath);
+    if (!(await isNativeCodexSessionPath(path, options.home)))
+        return null;
+    const sourceStat = await stat(path);
+    if (!sourceStat.isFile())
+        throw new Error(`Codex session ${path} is not a regular file; keeping it on disk`);
+    const metaLine = await firstLine(path);
+    const meta = parseSessionMeta(metaLine, path);
+    const project = options.project?.trim();
+    const scope = project ? ` for project ${JSON.stringify(project)}` : "";
+    const pointer = [
+        CODEX_RESUME_STUB_MARKER,
+        `Sealkeep preserved a searchable snapshot of Codex session ${meta.sessionId}${scope} as archive ${archiveId}, then reclaimed only the bulky local source. Other snapshots of this session may have different archive ids.`,
+        `Use the local MCP tool \`sealkeep_search\` with \`{"query":"<current question>","agent":"codex","sessionId":"${meta.sessionId}"}\` to retrieve relevant knowledge across every preserved snapshot of this Codex session.`,
+        "For a matching result, pass its context object unchanged to `sealkeep_read_context` to read the cited source passage, actual user prompt when recorded, and neighboring messages. Follow its continuation with the same source if needed; a search snippet is not the full earlier conversation.",
+        `To restore this exact archived snapshot, run \`sealkeep recover ${archiveId} --native --overwrite backup\`, then run \`codex resume ${meta.sessionId}\` again.`,
+        "Do not claim that earlier context was recovered until the search or restore returns it.",
+    ].join("\n");
+    const display = [
+        "This session's preserved history is searchable in Sealkeep.",
+        "This lightweight resume intentionally keeps archived snapshots off disk. Use Sealkeep MCP search now, or run the exact restore command above and resume the same session again when you need every byte from that snapshot.",
+    ].join(" ");
+    const contents = `${metaLine}\n${JSON.stringify(inputMessage(meta.timestamp, pointer, meta.ordinal === undefined ? undefined : meta.ordinal + 1))}\n${JSON.stringify(outputMessage(meta.timestamp, display, meta.ordinal === undefined ? undefined : meta.ordinal + 2))}\n`;
+    if (Buffer.byteLength(contents) > MAX_STUB_BYTES) {
+        throw new Error(`Codex resume pointer for ${path} exceeds ${MAX_STUB_BYTES} bytes; keeping the original on disk`);
+    }
+    const tempPath = join(dirname(path), `.${randomUUID()}.sealkeep-resume-stub.partial`);
+    try {
+        await writeFile(tempPath, contents, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        await utimes(tempPath, sourceStat.atime, sourceStat.mtime);
+        if (options.syncPreparedFile) {
+            await options.syncPreparedFile(tempPath);
+        }
+        else {
+            const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+            const { handle } = await openForFlush(tempPath, noFollow);
+            try {
+                const info = await handle.stat();
+                if (!info.isFile())
+                    throw new Error(`Codex resume pointer temp is not a regular file: ${tempPath}`);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return {
+        version: 1,
+        archiveId,
+        sessionId: meta.sessionId,
+        path,
+        bytes: Buffer.byteLength(contents),
+        sha256: createHash("sha256").update(contents).digest("hex"),
+        tempPath,
+        atime: sourceStat.atime,
+        mtime: sourceStat.mtime,
+    };
+}
+/** Installs an already-prepared pointer without clobbering a recreated path. */
+export async function installCodexResumeStub(stub) {
+    // `rename(temp, path)` overwrites on POSIX. Codex can recreate its rollout
+    // after the staging move but before this call; a hard-link publication is the
+    // same-filesystem atomic create-if-absent primitive and returns EEXIST rather
+    // than discarding those newly written bytes. The extra temp link is harmless
+    // after a crash and is removed best-effort once the native name is durable.
+    await link(stub.tempPath, stub.path);
+    await rm(stub.tempPath, { force: true }).catch(() => undefined);
+}
+export async function discardCodexResumeStub(stub) {
+    if (stub)
+        await rm(stub.tempPath, { force: true }).catch(() => undefined);
+}
+/**
+ * Recognises only the complete, untouched pointer format.  Once Codex appends
+ * a new turn there are more than the three expected lines, so the worker
+ * archives that new work normally instead of permanently excluding the file.
+ */
+export async function readUntouchedCodexResumeStub(path) {
+    let handle;
+    try {
+        // lstat before open also avoids opening a FIFO or other special file.
+        const named = await lstat(path, { bigint: true });
+        if (!named.isFile() || named.size <= 0n || named.size > BigInt(MAX_STUB_BYTES))
+            return null;
+        // Nonblocking is ignored for regular files, but prevents a FIFO swapped
+        // into the pathname after lstat from hanging the background worker.
+        handle = await open(path, POINTER_OPEN_FLAGS);
+        const before = await handle.stat({ bigint: true });
+        if (!samePointerSnapshot(named, before))
+            return null;
+        const raw = await readStablePointer(handle, path, before);
+        const pointer = parseUntouchedPointerContents(raw.toString("utf8"), path);
+        return pointer ? {
+            ...pointer,
+            path: resolve(path),
+            bytes: raw.length,
+            sha256: createHash("sha256").update(raw).digest("hex"),
+        } : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close();
+    }
+}

package/dist/src/retention.d.ts

@@ -1,6 +1,10 @@
 import { type ActivityOptions } from "./activity.js";
-import { type TrashResult } from "./trash.js";
-import { type VaultConfig } from "./types.js";
+import { recordAudit } from "./audit.js";
+import { moveToTrash, type TrashResult } from "./trash.js";
+import { type ArchiveRecord, type ArchiveRecordV2, type RemoteObject, type VaultConfig } from "./types.js";
+import { mutateArchiveRecord } from "./vault.js";
+import { installCodexResumeStub } from "./resume-stub.js";
+import { type VerifiedManagedAccountIndexPublication } from "./index-publication-verifier.js";
 export type RetentionPolicy = "local-only" | "sync-only" | "archive-and-reclaim" | "manual-approval";
 export type RetentionSettings = {
     policy: RetentionPolicy;
@@ -44,6 +48,8 @@ export type Candidate = {
     agent: string;
     path: string;
     bytes: number;
+    /** Filesystem blocks attributed to the source inode at preview time. */
+    allocatedBytes: number;
     createdAt: string;
     eligible: boolean;
     /** Every reason this source is still protected. Empty exactly when eligible. */
@@ -60,11 +66,68 @@ export type RetentionOptions = {
     now?: number;
     activity?: ActivityOptions;
     settings?: Partial<RetentionSettings>;
+    /** Set by the unattended daemon; foreground/manual actions leave it unset. */
+    backgroundCpuTarget?: number;
+    /** Aggregate daemon transfer ceiling for full remote identity proof. */
+    backgroundRemoteBytesPerSecond?: number;
+    signal?: AbortSignal;
+    /** Selected home for native Codex/Claude path and resume-format validation. */
+    home?: string;
+    /** Explicit unlock for foreground use; background work normally uses the OS keystore. */
+    phrase?: string;
+};
+/**
+ * Narrow operation seams for deterministic failure testing of the destructive
+ * boundary. Production callers leave this absent and get the real atomic
+ * filesystem, record-lock, and append-only audit operations.
+ */
+export type ReclaimOperations = {
+    moveToTrash?: typeof moveToTrash;
+    installResumeStub?: typeof installCodexResumeStub;
+    mutateRecord?: typeof mutateArchiveRecord;
+    audit?: typeof recordAudit;
+    /** Test/embedding seam; production asks the recorded provider immediately before purge. */
+    checkRemoteCopy?: (dataDir: string, archiveId: string, copyId: string) => Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    /**
+     * Stream seam that keeps the production byte-count/SHA-256 proof intact.
+     * Unlike checkRemoteCopy, returning a stream here does not assert success.
+     */
+    fetchRemoteCopy?: (dataDir: string, record: ArchiveRecordV2, copy: RemoteObject, signal?: AbortSignal) => Promise<AsyncIterable<Buffer>>;
+    /** Deterministic seam for cooperative hashing; daemon uses the 30% lane. */
+    cooperate?: () => Promise<void>;
+    /** Exact managed-index proof seam. Production always uses the real verifier. */
+    verifyIndexPublication?: (dataDir: string, chain: readonly ArchiveRecord[], requestedHead: ArchiveRecord, phrase: string, signal?: AbortSignal, 
+    /** Reclaimed snapshots belonging to the same exact native Codex session. */
+    searchableHeads?: readonly ArchiveRecord[]) => Promise<VerifiedManagedAccountIndexPublication>;
+    /** Cheap exact-head recheck seam used immediately before unlink. */
+    recheckIndexPublication?: (dataDir: string, verification: VerifiedManagedAccountIndexPublication, signal?: AbortSignal) => Promise<void>;
 };
+/**
+ * A live permission check for source deletion. Returning anything except
+ * literal `true`, or failing to read the current policy, keeps the original.
+ * The daemon supplies its machine-local gate; foreground entry points derive a
+ * command-scoped gate so crash reconciliation cannot borrow authority from an
+ * unrelated command or from a preview.
+ */
+export type ReclaimAuthorization = (archiveId: string) => Promise<boolean>;
 export declare function retentionSettings(config: VaultConfig, overrides?: Partial<RetentionSettings>): RetentionSettings;
 export declare function readApprovals(dataDir: string): Promise<string[]>;
 /** Manual-approval policy: an operator names the archives whose sources may be reclaimed. */
 export declare function approveReclamation(dataDir: string, archiveIds: string[]): Promise<string[]>;
+/**
+ * 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 declare function neverReclaimMarks(dataDir: string): Promise<string[]>;
+export declare function isPinned(path: string, marks: string[]): boolean;
 /**
  * Decides, per archive, whether its local source may be reclaimed.
  *
@@ -86,26 +149,44 @@ export type ReclaimOutcome = {
     id: string;
     path: string;
     bytes: number;
+    /** Legacy recoverable-trash destination. Empty after permanent purge. */
     movedTo: string;
-    strategy: TrashResult["strategy"];
+    strategy: TrashResult["strategy"] | "purged";
+    /** Allocated blocks released from the source inode, net of its pointer. */
+    freedBytes: number;
+    /** Present only once the durable staged original has been permanently purged. */
+    purgedAt?: string;
+    /** A tiny Codex-native pointer now occupies `path`, so `codex resume <id>` remains discoverable. */
+    resumeStub?: {
+        sessionId: string;
+        bytes: number;
+    };
 };
+/** Resolve kill -9 windows before starting another native source reclaim. */
+export declare function reconcileCodexReclaims(dataDir: string, storageRoot: string, home?: string, remoteCheck?: ReclaimOperations["checkRemoteCopy"], cooperate?: () => Promise<void>, activity?: ActivityOptions, signal?: AbortSignal, remoteBytesPerSecond?: number, remoteFetch?: ReclaimOperations["fetchRemoteCopy"], authorizeReclaim?: ReclaimAuthorization, phrase?: string, indexOperations?: Pick<ReclaimOperations, "verifyIndexPublication" | "recheckIndexPublication">): Promise<void>;
 /**
  * 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 declare function applyRetention(dataDir: string, options?: RetentionOptions & {
     confirm?: boolean;
     home?: string;
     strategy?: TrashResult["strategy"];
+    operations?: ReclaimOperations;
+    /** Set only by the installed daemon; checked repeatedly during a long pass. */
+    authorizeReclaim?: ReclaimAuthorization;
 }): Promise<{
     mode: "dry-run";
     policy: RetentionPolicy;
     wouldReclaim: number;
     wouldFreeBytes: number;
+    wouldMoveBytes: number;
     candidates: Candidate[];
     reclaimed?: undefined;
     failed?: undefined;
     freedBytes?: undefined;
+    movedBytes?: undefined;
     protected?: undefined;
 } | {
     mode: "apply";
@@ -116,9 +197,11 @@ export declare function applyRetention(dataDir: string, options?: RetentionOptio
         error: string;
     }[];
     freedBytes: number;
+    movedBytes: number;
     protected: number;
     wouldReclaim?: undefined;
     wouldFreeBytes?: undefined;
+    wouldMoveBytes?: undefined;
     candidates?: undefined;
 }>;
 /**
@@ -132,13 +215,16 @@ export declare function applyRetention(dataDir: string, options?: RetentionOptio
  *
  *  - 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 declare function reclaimOne(dataDir: string, archiveId: string, options?: {
     confirm?: boolean;
@@ -146,6 +232,9 @@ export declare function reclaimOne(dataDir: string, archiveId: string, options?:
     strategy?: TrashResult["strategy"];
     now?: number;
     activity?: ActivityOptions;
+    operations?: ReclaimOperations;
+    phrase?: string;
+    signal?: AbortSignal;
 }): Promise<ReclaimOutcome>;
 /**
  * `reclaimOne` over a selection. Each row passes or is kept with its reason —
@@ -158,6 +247,7 @@ export declare function reclaimBatch(dataDir: string, ids: readonly string[], op
     strategy?: TrashResult["strategy"];
     now?: number;
     activity?: ActivityOptions;
+    operations?: ReclaimOperations;
 }): Promise<{
     reclaimed: ReclaimOutcome[];
     kept: {
@@ -165,6 +255,7 @@ export declare function reclaimBatch(dataDir: string, ids: readonly string[], op
         reason: string;
     }[];
     freedBytes: number;
+    movedBytes: number;
 }>;
 export declare function setRetentionPolicy(dataDir: string, settings: Partial<RetentionSettings>): Promise<VaultConfig>;
 export type RedundantArchive = {