knodin 0.13.0 → 0.13.1

package/dist/src/engine/candidate-database.js

@@ -1,12 +1,65 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { acquireRepairLease } from "../repair-lease.js";
+import { assertStorageCapacity } from "../storage-budget.js";
+import { assertManagedStorageAllocation, resolveStoragePolicy } from "../storage-management.js";
+import { assertStoragePolicyWritable } from "../storage-policy-contract.js";
 import { isSealedDatabase } from "./seal.js";
 import { Database } from "./sqlite.js";
 import { resolveDbPath, resolveStateDir } from "./state-paths.js";
 const PROMOTION_SCHEMA_VERSION = 1;
 const CANDIDATES_DIRECTORY = "candidates";
 const PROMOTION_MARKER = "promotion.json";
+const CANDIDATE_OWNER = "candidate-owner.json";
+function readCandidateOwner(directory, directoryStat) {
+    const target = path.join(directory, CANDIDATE_OWNER);
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > 4096)
+        throw new Error("candidate owner marker is missing, unsafe or oversized");
+    const descriptor = fs.openSync(target, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const opened = fs.fstatSync(descriptor);
+        if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size)
+            throw new Error("candidate owner changed during read");
+        const buffer = Buffer.alloc(stat.size + 1);
+        const bytes = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+        const final = fs.fstatSync(descriptor);
+        if (bytes !== stat.size || final.size !== stat.size || final.mtimeMs !== stat.mtimeMs)
+            throw new Error("candidate owner changed during read");
+        const owner = JSON.parse(buffer.subarray(0, bytes).toString("utf8"));
+        if (!owner ||
+            typeof owner !== "object" ||
+            Array.isArray(owner) ||
+            Object.keys(owner).length !== 6 ||
+            owner.schemaVersion !== 1 ||
+            !Number.isSafeInteger(owner.pid) ||
+            owner.pid <= 0 ||
+            typeof owner.nonce !== "string" ||
+            !/^[0-9a-f-]{36}$/.test(owner.nonce) ||
+            !Number.isSafeInteger(owner.directoryDevice) ||
+            !Number.isSafeInteger(owner.directoryInode) ||
+            owner.directoryDevice !== directoryStat.dev ||
+            owner.directoryInode !== directoryStat.ino ||
+            typeof owner.createdAt !== "string" ||
+            !Number.isFinite(Date.parse(owner.createdAt)))
+            throw new Error("candidate owner marker is invalid or belongs to a different directory");
+        return owner;
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+/** Only ESRCH proves absence. EPERM, reused/live PIDs and every uncertainty preserve. */
+function candidateOwnerIsDead(owner) {
+    try {
+        process.kill(owner.pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
 function inside(parent, child) {
     const relative = path.relative(path.resolve(parent), path.resolve(child));
     return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
@@ -24,7 +77,7 @@ function assertPromotionRecord(repo, value) {
         !inside(stateDir, record.candidatePath) ||
         !inside(stateDir, record.backupPath) ||
         !record.phase ||
-        !["prepared", "backed-up", "promoted"].includes(record.phase)) {
+        !["prepared", "backed-up", "promoted", "repair-needed"].includes(record.phase)) {
         throw new Error("invalid promotion recovery record");
     }
     return record;
@@ -84,35 +137,65 @@ export function listCandidates(repo) {
     const root = candidateRoot(resolvedRepo);
     let entries;
     try {
-        entries = fs.readdirSync(root, { withFileTypes: true });
+        const state = resolveStateDir(resolvedRepo);
+        for (const target of [state, root]) {
+            const stat = fs.lstatSync(target);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                return [];
+        }
+        if (path.dirname(fs.realpathSync(root)) !== fs.realpathSync(state))
+            return [];
+        entries = fs.opendirSync(root);
     }
     catch {
         return [];
     }
     const found = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory() || !entry.name.startsWith("candidate-"))
-            continue;
-        const databasePath = path.join(root, entry.name, "db.sqlite");
-        let modifiedMs;
-        try {
-            modifiedMs = fs.statSync(databasePath).mtimeMs;
-        }
-        catch {
-            // A directory with no database is a half-created candidate, not a
-            // resumable one.
-            continue;
+    try {
+        for (let inspected = 0; inspected < 256; inspected++) {
+            const entry = entries.readSync();
+            if (!entry)
+                break;
+            if (!entry.isDirectory() || !entry.name.startsWith("candidate-"))
+                continue;
+            const databasePath = path.join(root, entry.name, "db.sqlite");
+            let modifiedMs;
+            try {
+                const candidate = {
+                    schemaVersion: 1,
+                    id: entry.name,
+                    repo: resolvedRepo,
+                    databasePath,
+                    createdAt: new Date().toISOString(),
+                };
+                const bound = bindCandidateDatabase(resolvedRepo, candidate);
+                try {
+                    bound.verify();
+                    modifiedMs = fs.lstatSync(databasePath).mtimeMs;
+                }
+                finally {
+                    bound.close();
+                }
+            }
+            catch {
+                // A directory with no database is a half-created candidate, not a
+                // resumable one.
+                continue;
+            }
+            found.push({
+                candidate: {
+                    schemaVersion: 1,
+                    id: entry.name,
+                    repo: resolvedRepo,
+                    databasePath,
+                    createdAt: new Date(modifiedMs).toISOString(),
+                },
+                modifiedMs,
+            });
         }
-        found.push({
-            candidate: {
-                schemaVersion: 1,
-                id: entry.name,
-                repo: resolvedRepo,
-                databasePath,
-                createdAt: new Date(modifiedMs).toISOString(),
-            },
-            modifiedMs,
-        });
+    }
+    finally {
+        entries.closeSync();
     }
     // Sorted as its own statement rather than mid-chain: an in-place `sort`
     // inside an expression mutates the array being read, which is harmless for
@@ -121,12 +204,62 @@ export function listCandidates(repo) {
     found.sort((a, b) => b.modifiedMs - a.modifiedMs);
     return found.map((item) => item.candidate);
 }
-export function allocateCandidate(repo) {
+export function allocateCandidate(repo, capacityDependencies) {
     const resolvedRepo = path.resolve(repo);
     const root = candidateRoot(resolvedRepo);
+    const storagePolicy = assertManagedStorageAllocation(resolvedRepo);
+    assertStorageCapacity({
+        stateDirectory: resolveStateDir(resolvedRepo),
+        databasePath: resolveDbPath(resolvedRepo),
+        operation: "candidate",
+        reserveBytes: storagePolicy?.minFreeBytes,
+    }, capacityDependencies);
+    try {
+        const stat = fs.lstatSync(root);
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            path.dirname(fs.realpathSync(root)) !== fs.realpathSync(resolveStateDir(resolvedRepo)))
+            throw new Error("candidate root must be a contained regular nonsymlink directory");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
     fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const rootIdentity = fs.lstatSync(root);
+    const canonicalState = fs.realpathSync(resolveStateDir(resolvedRepo));
+    const verifyRoot = () => {
+        const current = fs.lstatSync(root);
+        if (!current.isDirectory() ||
+            current.isSymbolicLink() ||
+            current.dev !== rootIdentity.dev ||
+            current.ino !== rootIdentity.ino ||
+            path.dirname(fs.realpathSync(root)) !== canonicalState)
+            throw new Error("candidate root changed during allocation");
+    };
+    verifyRoot();
     const directory = fs.mkdtempSync(path.join(root, "candidate-"));
     fs.chmodSync(directory, 0o700);
+    const directoryStat = fs.lstatSync(directory);
+    verifyRoot();
+    if (!directoryStat.isDirectory() ||
+        directoryStat.isSymbolicLink() ||
+        path.dirname(fs.realpathSync(directory)) !== fs.realpathSync(root))
+        throw new Error("candidate directory escaped during allocation");
+    const owner = {
+        schemaVersion: 1,
+        pid: process.pid,
+        nonce: crypto.randomUUID(),
+        directoryDevice: directoryStat.dev,
+        directoryInode: directoryStat.ino,
+        createdAt: new Date().toISOString(),
+    };
+    verifyRoot();
+    fs.writeFileSync(path.join(directory, CANDIDATE_OWNER), `${JSON.stringify(owner)}\n`, {
+        flag: "wx",
+        mode: 0o600,
+    });
+    verifyRoot();
     return {
         schemaVersion: 1,
         id: path.basename(directory),
@@ -139,10 +272,110 @@ export function assertCandidate(repo, candidate) {
     const resolvedRepo = path.resolve(repo);
     if (candidate.schemaVersion !== 1 ||
         candidate.repo !== resolvedRepo ||
+        !/^candidate-[A-Za-z0-9_-]+$/.test(candidate.id) ||
+        path.dirname(candidate.databasePath) !== path.join(candidateRoot(resolvedRepo), candidate.id) ||
         !inside(candidateRoot(resolvedRepo), candidate.databasePath) ||
         path.basename(candidate.databasePath) !== "db.sqlite") {
         throw new Error("candidate does not belong to this repository");
     }
+    const directories = [
+        resolveStateDir(resolvedRepo),
+        candidateRoot(resolvedRepo),
+        path.dirname(candidate.databasePath),
+    ];
+    for (let index = 0; index < directories.length; index++) {
+        const directory = directories[index];
+        try {
+            const stat = fs.lstatSync(directory);
+            if (!stat.isDirectory() ||
+                stat.isSymbolicLink() ||
+                (index > 0 &&
+                    path.dirname(fs.realpathSync(directory)) !== fs.realpathSync(directories[index - 1])))
+                throw new Error("unsafe candidate directory containment");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}
+/** Resume never assumes unknown or other live process ownership is abandoned. */
+export function assertCandidateResumeOwner(candidate) {
+    assertCandidate(candidate.repo, candidate);
+    const directory = path.dirname(candidate.databasePath);
+    const owner = readCandidateOwner(directory, fs.lstatSync(directory));
+    if (owner.pid !== process.pid && !candidateOwnerIsDead(owner))
+        throw new Error("candidate owner is live or unknown");
+}
+/** Hold a no-follow descriptor and detect pathname substitution at SQLite boundaries.
+ * SQLite still opens by pathname; this is bounded race detection, not openat isolation.
+ */
+export function bindCandidateDatabase(repo, candidate) {
+    assertCandidate(repo, candidate);
+    const directories = [
+        resolveStateDir(repo),
+        candidateRoot(repo),
+        path.dirname(candidate.databasePath),
+    ];
+    const identities = directories.map((directory) => fs.lstatSync(directory));
+    let stat;
+    try {
+        stat = fs.lstatSync(candidate.databasePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error("candidate database is missing", { cause: error });
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error("unsafe candidate database");
+    const descriptor = fs.openSync(candidate.databasePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const verify = (target = candidate.databasePath) => {
+            if (target !== candidate.databasePath && target !== resolveDbPath(repo))
+                throw new Error("invalid candidate verification target");
+            assertCandidate(repo, candidate);
+            for (let index = 0; index < directories.length; index++) {
+                const current = fs.lstatSync(directories[index]);
+                if (current.dev !== identities[index].dev || current.ino !== identities[index].ino)
+                    throw new Error("candidate directory changed during access");
+            }
+            const opened = fs.fstatSync(descriptor);
+            const current = fs.lstatSync(target);
+            if (!current.isFile() ||
+                current.isSymbolicLink() ||
+                opened.dev !== stat.dev ||
+                opened.ino !== stat.ino ||
+                current.dev !== stat.dev ||
+                current.ino !== stat.ino)
+                throw new Error("candidate database changed during access");
+            for (const suffix of ["-wal", "-shm"]) {
+                try {
+                    const sidecar = fs.lstatSync(`${target}${suffix}`);
+                    if (!sidecar.isFile() || sidecar.isSymbolicLink())
+                        throw new Error("unsafe candidate sidecar");
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+            }
+        };
+        verify();
+        const header = Buffer.alloc(16);
+        const bytes = fs.readSync(descriptor, header, 0, 16, 0);
+        verify();
+        return {
+            descriptor,
+            header: header.subarray(0, bytes),
+            verify,
+            close: () => fs.closeSync(descriptor),
+        };
+    }
+    catch (error) {
+        fs.closeSync(descriptor);
+        throw error;
+    }
 }
 /** Restore the previous active graph after a process stopped between promotion renames. */
 export function recoverInterruptedPromotion(repo) {
@@ -150,6 +383,8 @@ export function recoverInterruptedPromotion(repo) {
     if (!fs.existsSync(marker))
         return "none";
     const record = assertPromotionRecord(repo, JSON.parse(fs.readFileSync(marker, "utf8")));
+    if (record.phase === "repair-needed")
+        throw new Error("promotion identity changed; preserve active, backup and candidate files and inspect promotion.json before repair");
     const activeExists = fs.existsSync(record.activePath);
     const backupExists = fs.existsSync(record.backupPath);
     let outcome;
@@ -193,6 +428,15 @@ function activeDatabaseIsSealed(activePath) {
 }
 /** Same-filesystem, marker-backed promotion. Caller must close and audit both databases first. */
 export function promoteCandidateFile(repo, candidate) {
+    const bound = bindCandidateDatabase(repo, candidate);
+    try {
+        return promoteBoundCandidateFile(repo, candidate, bound);
+    }
+    finally {
+        bound.close();
+    }
+}
+function promoteBoundCandidateFile(repo, candidate, bound) {
     assertCandidate(repo, candidate);
     const activePath = resolveDbPath(repo);
     const stateDir = resolveStateDir(repo);
@@ -225,12 +469,23 @@ export function promoteCandidateFile(repo, candidate) {
         backupPath,
     };
     atomicRecord(marker, record);
+    let candidateRenamed = false;
+    let activeBackedUp = false;
+    let previousActive;
     try {
-        if (fs.existsSync(activePath))
+        if (fs.existsSync(activePath)) {
+            previousActive = fs.lstatSync(activePath);
+            if (!previousActive.isFile() || previousActive.isSymbolicLink())
+                throw new Error("unsafe active database preserved");
             fs.renameSync(activePath, backupPath);
+            activeBackedUp = true;
+        }
         record = { ...record, phase: "backed-up" };
         atomicRecord(marker, record);
+        bound.verify();
         fs.renameSync(candidate.databasePath, activePath);
+        candidateRenamed = true;
+        bound.verify(activePath);
         record = { ...record, phase: "promoted" };
         atomicRecord(marker, record);
         fsyncFile(activePath);
@@ -256,7 +511,40 @@ export function promoteCandidateFile(repo, candidate) {
         // which would move the just-promoted database back into the candidate
         // directory and restore the old graph over a promotion that succeeded.
         try {
-            fs.rmSync(path.dirname(candidate.databasePath), { recursive: true, force: true });
+            bound.verify(activePath);
+            const directory = path.dirname(candidate.databasePath);
+            const owner = readCandidateOwner(directory, fs.lstatSync(directory));
+            if (owner.pid !== process.pid && !candidateOwnerIsDead(owner))
+                throw new Error("promoted residue owner live or unknown");
+            const contents = fs.opendirSync(directory);
+            const names = [];
+            try {
+                for (let count = 0; count < 3; count++) {
+                    const entry = contents.readSync();
+                    if (!entry)
+                        break;
+                    if (![CANDIDATE_OWNER, "status-audit-v1.json"].includes(entry.name))
+                        throw new Error("unexpected promoted candidate residue preserved");
+                    const stat = fs.lstatSync(path.join(directory, entry.name));
+                    if (!stat.isFile() ||
+                        stat.isSymbolicLink() ||
+                        stat.size > (entry.name === CANDIDATE_OWNER ? 4096 : 1_048_576))
+                        throw new Error("unsafe promoted residue preserved");
+                    names.push(entry.name);
+                }
+            }
+            finally {
+                contents.closeSync();
+            }
+            for (const name of [
+                ...names.filter((name) => name !== CANDIDATE_OWNER),
+                ...names.filter((name) => name === CANDIDATE_OWNER),
+            ]) {
+                bound.verify(activePath);
+                fs.unlinkSync(path.join(directory, name));
+            }
+            bound.verify(activePath);
+            fs.rmdirSync(directory);
         }
         catch {
             // Residue only. `sweepAbandonedCandidates` collects it on the next run.
@@ -264,60 +552,330 @@ export function promoteCandidateFile(repo, candidate) {
         return fs.existsSync(backupPath) ? backupPath : null;
     }
     catch (error) {
-        if (fs.existsSync(activePath) && fs.existsSync(backupPath)) {
-            fs.mkdirSync(path.dirname(candidate.databasePath), { recursive: true, mode: 0o700 });
-            fs.renameSync(activePath, candidate.databasePath);
+        try {
+            // A failed identity check is not authority to move an unknown inode.
+            // Preserve all evidence and block automatic recovery in that case.
+            bound.verify(candidateRenamed ? activePath : candidate.databasePath);
+            if (candidateRenamed) {
+                try {
+                    fs.lstatSync(candidate.databasePath);
+                    throw new Error("candidate rollback destination is occupied");
+                }
+                catch (failure) {
+                    if (failure.code !== "ENOENT")
+                        throw failure;
+                }
+                fs.renameSync(activePath, candidate.databasePath);
+            }
+            if (activeBackedUp && previousActive) {
+                const backup = fs.lstatSync(backupPath);
+                if (!backup.isFile() ||
+                    backup.isSymbolicLink() ||
+                    backup.dev !== previousActive.dev ||
+                    backup.ino !== previousActive.ino)
+                    throw new Error("backup identity changed during rollback");
+                try {
+                    fs.lstatSync(activePath);
+                    throw new Error("active rollback destination is occupied");
+                }
+                catch (failure) {
+                    if (failure.code !== "ENOENT")
+                        throw failure;
+                }
+                fs.renameSync(backupPath, activePath);
+            }
+            fs.rmSync(marker, { force: true });
+            fsyncDirectory(stateDir);
+        }
+        catch (rollbackError) {
+            atomicRecord(marker, { ...record, phase: "repair-needed" });
+            throw new Error("promotion rollback could not verify file identity; files preserved, inspect promotion.json before repair", { cause: rollbackError });
         }
-        if (!fs.existsSync(activePath) && fs.existsSync(backupPath))
-            fs.renameSync(backupPath, activePath);
-        fs.rmSync(marker, { force: true });
-        fsyncDirectory(stateDir);
         throw error;
     }
 }
-/**
- * Remove candidate directories that hold no database, and report how many.
- *
- * `listCandidates` deliberately answers "what could be resumed", so it skips a
- * directory with no `db.sqlite`. Cleanup used to run only over that list, which
- * meant the one kind of directory guaranteed to have no database — the residue a
- * successful promotion leaves once the database is renamed out — was the one
- * kind nothing could ever delete (KNODIN-2).
- *
- * Promotion now removes its own directory, so this exists for two other cases:
- * residue already accumulated by earlier versions, and directories left by a
- * process that died between `allocateCandidate` and writing a database.
- *
- * Returns the count rather than nothing so callers can say what they swept
- * instead of tidying up silently.
- */
-export function sweepAbandonedCandidates(repo) {
+export function sweepAbandonedCandidates(repo, options = {}) {
     const resolvedRepo = path.resolve(repo);
     const root = candidateRoot(resolvedRepo);
-    let entries;
+    const marker = promotionMarkerPath(resolvedRepo);
+    let reported = 0;
+    const report = (reason, target) => {
+        if (reported++ >= 256)
+            return;
+        try {
+            options.onDiagnostic?.({ path: target, reason });
+        }
+        catch {
+            /* Observers cannot authorize cleanup. */
+        }
+    };
+    const exists = (target) => {
+        try {
+            fs.lstatSync(target);
+            return true;
+        }
+        catch (error) {
+            return error.code !== "ENOENT";
+        }
+    };
+    let lease;
     try {
-        entries = fs.readdirSync(root, { withFileTypes: true });
+        assertStoragePolicyWritable(resolvedRepo);
+        const policy = resolveStoragePolicy(resolvedRepo);
+        if (!policy?.enabled || policy.dryRun) {
+            report("policy-unmanaged-disabled-or-dry-run");
+            return 0;
+        }
+        const state = resolveStateDir(resolvedRepo);
+        for (const directory of [state, root]) {
+            let stat;
+            try {
+                stat = fs.lstatSync(directory);
+            }
+            catch (error) {
+                if (directory === root && error.code === "ENOENT")
+                    return 0;
+                throw error;
+            }
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                return 0;
+        }
+        const canonicalState = fs.realpathSync(state);
+        const canonicalRoot = fs.realpathSync(root);
+        const stateIdentity = fs.lstatSync(state);
+        const rootIdentity = fs.lstatSync(root);
+        const sameDirectory = (target, expected, canonical) => {
+            const current = fs.lstatSync(target);
+            return (current.isDirectory() &&
+                !current.isSymbolicLink() &&
+                current.dev === expected.dev &&
+                current.ino === expected.ino &&
+                fs.realpathSync(target) === canonical);
+        };
+        if (path.dirname(canonicalRoot) !== canonicalState || exists(marker))
+            return 0;
+        // Never borrow a same-process outer lease without its explicit owner token.
+        // Busy or uncertain coordination is a safe skip, not permission to delete.
+        if (exists(path.join(state, "repair.lock")))
+            return 0;
+        lease = acquireRepairLease(resolvedRepo);
+        if (exists(marker))
+            return 0;
+        let removed = 0;
+        const entries = fs.opendirSync(root);
+        try {
+            for (let inspected = 0; inspected < 256; inspected++) {
+                const entry = entries.readSync();
+                if (!entry)
+                    break;
+                if (entry.isDirectory() && /^\.gc-private-[A-Za-z0-9_-]+$/.test(entry.name)) {
+                    const quarantine = path.join(root, entry.name);
+                    try {
+                        const identity = fs.lstatSync(quarantine);
+                        const canonical = path.join(canonicalRoot, entry.name);
+                        if (!sameDirectory(quarantine, identity, canonical))
+                            throw new Error("unsafe quarantine preserved");
+                        const children = fs.opendirSync(quarantine);
+                        let child;
+                        try {
+                            child = children.readSync();
+                            if (children.readSync())
+                                throw new Error("unexpected quarantine contents preserved");
+                        }
+                        finally {
+                            children.closeSync();
+                        }
+                        const moved = child ? path.join(quarantine, child.name) : null;
+                        let movedIdentity;
+                        const names = [];
+                        if (child && moved) {
+                            if (!child.isDirectory() || !/^candidate-[A-Za-z0-9_-]+$/.test(child.name))
+                                throw new Error("unexpected quarantined candidate preserved");
+                            movedIdentity = fs.lstatSync(moved);
+                            if (!sameDirectory(moved, movedIdentity, path.join(canonical, child.name)))
+                                throw new Error("unsafe quarantined candidate preserved");
+                            const contents = fs.opendirSync(moved);
+                            try {
+                                for (let count = 0; count < 3; count++) {
+                                    const file = contents.readSync();
+                                    if (!file)
+                                        break;
+                                    if (![CANDIDATE_OWNER, "status-audit-v1.json"].includes(file.name))
+                                        throw new Error("DB-bearing quarantine preserved");
+                                    const target = path.join(moved, file.name);
+                                    const stat = fs.lstatSync(target);
+                                    if (!stat.isFile() ||
+                                        stat.isSymbolicLink() ||
+                                        stat.size > (file.name === CANDIDATE_OWNER ? 4096 : 1_048_576) ||
+                                        path.dirname(fs.realpathSync(target)) !== fs.realpathSync(moved))
+                                        throw new Error("unsafe quarantine metadata preserved");
+                                    names.push(file.name);
+                                }
+                            }
+                            finally {
+                                contents.closeSync();
+                            }
+                            if (names.length && !candidateOwnerIsDead(readCandidateOwner(moved, movedIdentity)))
+                                throw new Error("quarantine owner live or unknown");
+                        }
+                        const verify = (includeMoved = true) => {
+                            assertStoragePolicyWritable(resolvedRepo);
+                            const policy = resolveStoragePolicy(resolvedRepo);
+                            if (!policy?.enabled ||
+                                policy.dryRun ||
+                                exists(marker) ||
+                                !sameDirectory(state, stateIdentity, canonicalState) ||
+                                !sameDirectory(root, rootIdentity, canonicalRoot) ||
+                                !sameDirectory(quarantine, identity, canonical) ||
+                                (includeMoved &&
+                                    moved &&
+                                    movedIdentity &&
+                                    !sameDirectory(moved, movedIdentity, path.join(canonical, path.basename(moved)))))
+                                throw new Error("quarantine consent or identity changed");
+                        };
+                        if (moved) {
+                            for (const name of [
+                                ...names.filter((name) => name !== CANDIDATE_OWNER),
+                                ...names.filter((name) => name === CANDIDATE_OWNER),
+                            ]) {
+                                verify();
+                                fs.unlinkSync(path.join(moved, name));
+                            }
+                            verify();
+                            fs.rmdirSync(moved);
+                        }
+                        verify(false);
+                        fs.rmdirSync(quarantine);
+                        removed++;
+                    }
+                    catch (error) {
+                        report(`quarantine-preserved: ${String(error)}`, quarantine);
+                    }
+                    continue;
+                }
+                if (!entry.isDirectory() || !/^candidate-[A-Za-z0-9_-]+$/.test(entry.name))
+                    continue;
+                const directory = path.join(root, entry.name);
+                let quarantine;
+                let moved;
+                try {
+                    const stat = fs.lstatSync(directory);
+                    if (!stat.isDirectory() ||
+                        stat.isSymbolicLink() ||
+                        fs.realpathSync(directory) !== path.join(canonicalRoot, entry.name))
+                        continue;
+                    // Age is an extra fence, never the proof that an owner is absent.
+                    if (Date.now() - stat.mtimeMs < 60_000)
+                        continue;
+                    const owner = readCandidateOwner(directory, stat);
+                    if (!candidateOwnerIsDead(owner)) {
+                        report("candidate-owner-live-or-unknown", directory);
+                        continue;
+                    }
+                    const residueFiles = (target, canonical) => {
+                        const contents = fs.opendirSync(target);
+                        const names = [];
+                        try {
+                            for (let count = 0; count < 3; count++) {
+                                const child = contents.readSync();
+                                if (!child)
+                                    break;
+                                if (![CANDIDATE_OWNER, "status-audit-v1.json"].includes(child.name))
+                                    throw new Error("DB-bearing or unexpected candidate contents preserved");
+                                const file = path.join(target, child.name);
+                                const metadata = fs.lstatSync(file);
+                                if (!metadata.isFile() ||
+                                    metadata.isSymbolicLink() ||
+                                    metadata.size > (child.name === CANDIDATE_OWNER ? 4096 : 1_048_576) ||
+                                    path.dirname(fs.realpathSync(file)) !== canonical)
+                                    throw new Error("unsafe candidate residue file preserved");
+                                names.push(child.name);
+                            }
+                        }
+                        finally {
+                            contents.closeSync();
+                        }
+                        if (!names.includes(CANDIDATE_OWNER))
+                            throw new Error("candidate owner marker disappeared");
+                        return names;
+                    };
+                    residueFiles(directory, path.join(canonicalRoot, entry.name));
+                    if (exists(marker))
+                        break;
+                    const currentPolicy = resolveStoragePolicy(resolvedRepo);
+                    if (!currentPolicy?.enabled || currentPolicy.dryRun)
+                        throw new Error("storage policy changed; candidate preserved");
+                    if (!sameDirectory(state, stateIdentity, canonicalState) ||
+                        !sameDirectory(root, rootIdentity, canonicalRoot) ||
+                        !sameDirectory(directory, stat, path.join(canonicalRoot, entry.name)))
+                        throw new Error("candidate/root changed before quarantine");
+                    quarantine = fs.mkdtempSync(path.join(root, ".gc-private-"));
+                    fs.chmodSync(quarantine, 0o700);
+                    const quarantineIdentity = fs.lstatSync(quarantine);
+                    const canonicalQuarantine = path.join(canonicalRoot, path.basename(quarantine));
+                    if (!sameDirectory(root, rootIdentity, canonicalRoot) ||
+                        !sameDirectory(quarantine, quarantineIdentity, canonicalQuarantine))
+                        throw new Error("quarantine root changed");
+                    moved = path.join(quarantine, entry.name);
+                    fs.renameSync(directory, moved);
+                    const canonicalMoved = path.join(canonicalQuarantine, entry.name);
+                    if (!sameDirectory(state, stateIdentity, canonicalState) ||
+                        !sameDirectory(root, rootIdentity, canonicalRoot) ||
+                        !sameDirectory(quarantine, quarantineIdentity, canonicalQuarantine) ||
+                        !sameDirectory(moved, stat, canonicalMoved) ||
+                        exists(marker))
+                        throw new Error("candidate/root identity changed during quarantine");
+                    const movedOwner = readCandidateOwner(moved, stat);
+                    if (movedOwner.nonce !== owner.nonce || !candidateOwnerIsDead(movedOwner))
+                        throw new Error("candidate ownership changed during quarantine");
+                    const names = residueFiles(moved, canonicalMoved);
+                    const finalPolicy = resolveStoragePolicy(resolvedRepo);
+                    if (!finalPolicy?.enabled || finalPolicy.dryRun)
+                        throw new Error("storage policy changed; quarantined candidate preserved");
+                    // Named nonrecursive unlink only after all moved identities/contents validate.
+                    for (const name of names.filter((name) => name !== CANDIDATE_OWNER))
+                        fs.unlinkSync(path.join(moved, name));
+                    fs.unlinkSync(path.join(moved, CANDIDATE_OWNER));
+                    fs.rmdirSync(moved);
+                    moved = undefined;
+                    removed++;
+                    fs.rmdirSync(quarantine);
+                    quarantine = undefined;
+                }
+                catch (error) {
+                    report(String(error), moved ?? directory);
+                    // Preserve uncertainty in quarantine. A check-then-rename restore could
+                    // overwrite a newly allocated directory occupying the original slot.
+                    if (moved)
+                        report("quarantine-preserved; inspect explicitly before retrying cleanup", moved);
+                    if (quarantine && !moved) {
+                        try {
+                            fs.rmdirSync(quarantine);
+                        }
+                        catch {
+                            report("quarantine residue preserved", quarantine);
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            entries.closeSync();
+        }
+        return removed;
     }
-    catch {
+    catch (error) {
+        report(String(error));
         return 0;
     }
-    let removed = 0;
-    for (const entry of entries) {
-        if (!entry.isDirectory() || !entry.name.startsWith("candidate-"))
-            continue;
-        const directory = path.join(root, entry.name);
-        if (fs.existsSync(path.join(directory, "db.sqlite")))
-            continue;
+    finally {
         try {
-            fs.rmSync(directory, { recursive: true, force: true });
-            removed++;
+            lease?.release();
         }
         catch {
-            // Best effort. Failing to remove residue must not stop the caller's
-            // actual work, which is what this is being cleaned up alongside.
+            /* Cleanup cannot mask the caller's work. */
         }
     }
-    return removed;
 }
 export function discardCandidateFiles(repo, candidate) {
     assertCandidate(repo, candidate);