grepmax 0.26.64 → 0.26.66

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "grepmax",
       "source": "./plugins/grepmax",
       "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
-      "version": "0.26.64",
+      "version": "0.26.66",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/README.md

@@ -485,7 +485,17 @@ When heavy work is paused, the daemon keeps metadata, bounded symbol/file lookup
 
 To serve bounded reads under an existing startup quarantine, run `gmax watch --daemon --read-only -b`. This preserves the safety markers. `status --json` reports `daemon.service.mode` and its reason; `doctor` reports paused availability and skips native corpus diagnostics. Pausing is sticky for that daemon process. Full service requires a deliberate restart after host recovery and quarantine review. Known critical OS or kernel pressure still stops even the read-only service.
 
-Full-table compaction and new FTS/ANN index builds are disabled in the containment release, including forced maintenance and doctor repair. Existing indexes remain readable; missing lexical indexes fall back to available retrieval. Retained copies are not recovered by this release. A separate exclusive prune-only path requires validation before deployment. Do not repeatedly force repair, use future cutoffs or manually remove index fragments.
+Full-table compaction and new FTS/ANN index builds are disabled in the containment release, including forced maintenance and doctor repair. Existing indexes remain readable; missing lexical indexes fall back to available retrieval. Do not repeatedly force repair, use future cutoffs or manually remove index fragments.
+
+The package includes a separate prune-only helper with pinned Lance 12 dependencies, plus an exclusively leased Node wrapper. Runtime preparation uses `uv >=0.12.18`, an existing Python interpreter and locked wheels; it does not download Python, build from source, load an embedding model or run during installation. The helper currently supports macOS and Linux. No timer, CLI repair or startup path calls it automatically. Explicit recovery has separate production admission; packaging does not authorize live cleanup.
+
+`gmax recover --table /path/to/lancedb/chunks.lance --json` reads the durable recovery receipt without starting a daemon or preparing Python. `--check` samples admission without pruning. `--prune --version <current-version> --cutoff <absolute-ISO-timestamp>` explicitly requests one offline prune. A prior uncertain attempt requires `--acknowledge-uncertain <attempt-id>` after inspection. Recovery never creates/clears quarantine, stops other owners, retries automatically or enables rewriting.
+
+Production recovery currently requires macOS, a persistent `autostart-disabled` file in the selected store home, and closed store owners. Recovery alone uses known healthy memory/kernel pressure, measured physical headroom and the shared aggregate resource budget; normal development retains its configured guard policy. The helper reserves 512 MiB of admission capacity; this is not an OS-enforced footprint cap. Recovery samples have an eight-second total ceiling, including the established five-second kernel probe allowance, with fresh sampling at deletion admission and five-second heartbeat scheduling. Unknown, stale, warning or critical measurements refuse/interrupt recovery. Pruning needs at least 1 MiB of measured metadata disk headroom, not full-table rewrite space. Initial wheel setup requires 512 MiB; an existing environment is checked against the lock offline without that download-space requirement.
+
+The child waits for launch and deletion admission tokens, with verified helper PID/start identity recorded as the primary exclusive owner. Existing readers retain exclusion if the parent dies while the helper is alive. Current/tagged/post-cutoff metadata is verified after pruning; recovery refuses more than 256 protected versions before deletion to bound verification. Interrupted attempts require verification and explicit acknowledgement before retry. Linux/APFS fixtures exercise native retention and interruption; supported production host admission is tested separately and still runs freshly for each operation.
+
+Explicit helper calls persist a private `.gmax-prune-state.json` receipt outside the table before deletion. Cancellation, invalid results, lost ownership and abandoned running receipts remain uncertain; a verified explicit retry records the prior uncertain attempt. Successful receipts include before/after file lengths, allocated bytes and filesystem free space. These measurements do not imply zero retained copies or a macOS physical-footprint cap. Current, tagged and post-cutoff versions are protected; unverified files are retained. Full-table rewriting remains disabled regardless of receipt state.
 
 `~/.gmax/logs/daemon.log` records containment skips and retained historical compaction outcomes, including duration, logical size, disk size before/after, free space, and bytes reclaimed. `gmax status --json` exposes the last outcome under `daemon.compaction`; its `at` timestamp identifies when it was recorded. Five-minute resource snapshots track footprint, RSS, heap, external/ArrayBuffer memory, Lance cache, workers and pending work for memory investigations. Reading status uses retained snapshots and does not scan the index directory. Logs rotate to `daemon.log.prev`.
 

package/dist/bin.js

@@ -77,7 +77,7 @@ function selectHome() {
     const argv = process.argv.slice(2);
     // These enumerate/route stores per request rather than pinning the process
     // to its launch cwd's store. In particular an MCP session can serve both.
-    if (argv[0] === "mcp" || argv[0] === "status")
+    if (argv[0] === "mcp" || argv[0] === "status" || argv[0] === "recover")
         return;
     const match = (0, stores_1.matchStore)(commandTarget(argv, process.cwd()));
     if (match.kind === "primary")

package/dist/commands/recover.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recover = void 0;
+exports.parseRecoveryCutoff = parseRecoveryCutoff;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const commander_1 = require("commander");
+const prune_state_1 = require("../lib/store/prune-state");
+const recovery_1 = require("../lib/store/recovery");
+function parseRecoveryCutoff(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.exec(value);
+    if (!match)
+        throw new Error("--cutoff requires an absolute ISO timestamp with timezone");
+    const calendar = new Date(`${value.slice(0, 19)}Z`);
+    const parts = [
+        calendar.getUTCFullYear(),
+        calendar.getUTCMonth() + 1,
+        calendar.getUTCDate(),
+        calendar.getUTCHours(),
+        calendar.getUTCMinutes(),
+        calendar.getUTCSeconds(),
+    ];
+    const result = new Date(value);
+    if (parts.some((part, i) => part !== Number(match[i + 1])) ||
+        !Number.isFinite(result.getTime()))
+        throw new Error("--cutoff is not a valid calendar timestamp");
+    return result;
+}
+exports.recover = new commander_1.Command("recover")
+    .description("Inspect or explicitly prune an offline Lance store without rewriting it")
+    .requiredOption("--table <path>", "Existing .lance table directory")
+    .option("--check", "Check recovery admission without preparing or pruning")
+    .option("--prune", "Explicitly perform exclusively leased prune-only recovery")
+    .option("--version <number>", "Expected current table version", Number)
+    .option("--cutoff <timestamp>", "Real absolute ISO retention cutoff")
+    .option("--acknowledge-uncertain <attempt>", "Acknowledge an inspected uncertain attempt before explicit retry")
+    .option("--json", "Structured outcome and durable receipt")
+    .addHelpText("after", "\nStatus is metadata-only. Pruning requires a persistent autostart-disabled file in the store home, closed store owners, known healthy macOS resources, --version and --cutoff. Recovery does not stop services or clear containment. --check can refuse under unknown pressure without pausing normal service.")
+    .action((opts) => __awaiter(void 0, void 0, void 0, function* () {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once("SIGINT", abort);
+    process.once("SIGTERM", abort);
+    try {
+        const report = yield (0, recovery_1.recoverStore)({
+            table: opts.table,
+            check: opts.check,
+            prune: opts.prune,
+            version: opts.version,
+            cutoff: opts.cutoff ? parseRecoveryCutoff(opts.cutoff) : undefined,
+            acknowledgeUncertain: opts.acknowledgeUncertain,
+            signal: controller.signal,
+        });
+        console.log(JSON.stringify(report, null, opts.json ? undefined : 2));
+    }
+    catch (error) {
+        let state = "unverified";
+        try {
+            state = (0, prune_state_1.readPruneState)(path.dirname(fs.realpathSync(opts.table)));
+        }
+        catch (_a) { }
+        console.error(JSON.stringify({
+            outcome: state === "unverified" || (state === null || state === void 0 ? void 0 : state.outcome) === "uncertain"
+                ? "uncertain"
+                : "refused",
+            error: error instanceof Error ? error.message : "Recovery failed",
+            state,
+        }));
+        process.exitCode = 1;
+    }
+    finally {
+        process.removeListener("SIGINT", abort);
+        process.removeListener("SIGTERM", abort);
+    }
+}));

package/dist/index.js

@@ -62,6 +62,7 @@ const peek_1 = require("./commands/peek");
 const plugin_1 = require("./commands/plugin");
 const project_1 = require("./commands/project");
 const recent_1 = require("./commands/recent");
+const recover_1 = require("./commands/recover");
 const related_1 = require("./commands/related");
 const remove_1 = require("./commands/remove");
 const repair_1 = require("./commands/repair");
@@ -146,6 +147,7 @@ commander_1.program.addCommand(setup_1.setup);
 commander_1.program.addCommand(config_1.config);
 commander_1.program.addCommand(doctor_1.doctor);
 commander_1.program.addCommand(repair_1.repair);
+commander_1.program.addCommand(recover_1.recover);
 // Plugins
 commander_1.program.addCommand(plugin_1.plugin);
 // Legacy plugin installers (hidden — use `gmax plugin` instead)
@@ -161,4 +163,8 @@ opencode_1.installOpencode._hidden = true;
 commander_1.program.addCommand(opencode_1.installOpencode);
 opencode_1.uninstallOpencode._hidden = true;
 commander_1.program.addCommand(opencode_1.uninstallOpencode);
+// Recovery owns --version as a required table-version value. Keep the root
+// package-version flag from consuming it; other commands retain global options.
+if (process.argv[2] === "recover")
+    commander_1.program.enablePositionalOptions();
 commander_1.program.parse();

package/dist/lib/store/lance-cleanup.js

@@ -0,0 +1,425 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCleanupProcess = runCleanupProcess;
+exports.prepareCleanupRuntime = prepareCleanupRuntime;
+exports.pruneVersions = pruneVersions;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("../../config");
+const prune_state_1 = require("./prune-state");
+const recovery_admission_1 = require("./recovery-admission");
+const store_lease_1 = require("./store-lease");
+const project = path.resolve(__dirname, "../../../lance-maintenance");
+const MAX_OUTPUT_BYTES = 128 * 1024;
+const MAX_HELPER_MS = 120000;
+/** No shell, inherited service credentials, Python path hooks or source builds.
+ * Thread settings apply before Arrow/Lance imports in the child. */
+function helperEnvironment() {
+    const env = {};
+    for (const name of [
+        "PATH",
+        "HOME",
+        "TMPDIR",
+        "TEMP",
+        "SystemRoot",
+        "LOCALAPPDATA",
+        "SSL_CERT_FILE",
+        "SSL_CERT_DIR",
+    ]) {
+        if (process.env[name] !== undefined)
+            env[name] = process.env[name];
+    }
+    return Object.assign(Object.assign({}, env), { RAYON_NUM_THREADS: "1", TOKIO_WORKER_THREADS: "1", OMP_NUM_THREADS: "1", OPENBLAS_NUM_THREADS: "1", MKL_NUM_THREADS: "1", NUMEXPR_NUM_THREADS: "1", UV_CONCURRENT_DOWNLOADS: "1", UV_CONCURRENT_INSTALLS: "1", UV_CONCURRENT_BUILDS: "1", UV_PYTHON_DOWNLOADS: "never" });
+}
+/** Settle only after close, including abort/timeout. Releasing an exclusive lease
+ * on AbortError before the child exits would let writers race native deletion. */
+function runCleanupProcess(executable, args, options = {}) {
+    var _a;
+    if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted)
+        return Promise.reject(new Error("Cleanup cancelled before launch"));
+    return new Promise((resolve, reject) => {
+        var _a, _b, _c;
+        var _d;
+        const child = (0, node_child_process_1.spawn)(executable, args, {
+            env: Object.assign(Object.assign({}, helperEnvironment()), options.env),
+            stdio: [options.admission ? "pipe" : "ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let output = "";
+        let diagnostics = "";
+        let bytes = 0;
+        let failure;
+        let approved = false;
+        let launched = false;
+        let readyBuffer = "";
+        let monitor;
+        let forceKill;
+        const stop = (reason) => {
+            failure !== null && failure !== void 0 ? failure : (failure = new Error(`${reason}; cleanup completion is uncertain`));
+            child.kill("SIGTERM");
+            forceKill !== null && forceKill !== void 0 ? forceKill : (forceKill = setTimeout(() => child.kill("SIGKILL"), 1000));
+        };
+        const abort = () => stop("Cleanup cancelled");
+        const timeout = setTimeout(() => stop("Cleanup timed out"), Math.min((_d = options.timeoutMs) !== null && _d !== void 0 ? _d : MAX_HELPER_MS, MAX_HELPER_MS));
+        (_a = options.signal) === null || _a === void 0 ? void 0 : _a.addEventListener("abort", abort, { once: true });
+        // stderr is deliberately not returned: child diagnostics may contain paths,
+        // tokens or registry URLs. Retain a concrete bounded exit/signal/error code.
+        for (const stream of [child.stdout, child.stderr]) {
+            stream.on("data", (chunk) => {
+                bytes += chunk.length;
+                if (bytes > MAX_OUTPUT_BYTES)
+                    stop("Cleanup output exceeded limit");
+                else if (stream === child.stdout) {
+                    if (options.admission && !approved) {
+                        readyBuffer += chunk.toString("utf8");
+                        let end = readyBuffer.indexOf("\n");
+                        while (end >= 0 && !approved && !failure) {
+                            try {
+                                const phase = JSON.parse(readyBuffer.slice(0, end)).admission;
+                                readyBuffer = readyBuffer.slice(end + 1);
+                                if (phase === "launch" && !launched) {
+                                    if (!child.stdin)
+                                        throw Error();
+                                    child.stdin.write(`${options.admission.nonce}\n`);
+                                    launched = true;
+                                }
+                                else if (phase === "ready" && launched) {
+                                    options.admission.approve();
+                                    child.stdin.end(`${options.admission.nonce}\n`);
+                                    approved = true;
+                                    output += readyBuffer;
+                                    readyBuffer = "";
+                                }
+                                else
+                                    throw Error();
+                            }
+                            catch (_a) {
+                                stop("Prune deletion admission refused");
+                            }
+                            end = readyBuffer.indexOf("\n");
+                        }
+                    }
+                    else
+                        output += chunk.toString("utf8");
+                }
+                else
+                    diagnostics += chunk.toString("utf8");
+            });
+        }
+        child.on("error", (error) => {
+            var _a;
+            failure !== null && failure !== void 0 ? failure : (failure = new Error(`Cleanup process could not start (${(_a = error.code) !== null && _a !== void 0 ? _a : "unknown"})`));
+        });
+        child.once("close", (code, signal) => {
+            var _a, _b;
+            var _c;
+            clearTimeout(timeout);
+            if (forceKill)
+                clearTimeout(forceKill);
+            if (monitor)
+                clearInterval(monitor);
+            try {
+                (_a = options.admission) === null || _a === void 0 ? void 0 : _a.close();
+            }
+            catch (_d) {
+                failure !== null && failure !== void 0 ? failure : (failure = new Error("Prune ownership/resource close failed; completion is uncertain"));
+            }
+            if (options.admission && !approved)
+                failure !== null && failure !== void 0 ? failure : (failure = new Error("Prune deletion was not admitted; completion is uncertain"));
+            (_b = options.signal) === null || _b === void 0 ? void 0 : _b.removeEventListener("abort", abort);
+            if (failure)
+                reject(failure);
+            else if (code !== 0) {
+                // Whitelist categories, never repeat registry credentials, file paths,
+                // full traceback text or arbitrary diagnostics from a subprocess.
+                const detail = /lockfile.*(?:needs|updated|out.of.date)|locked.*(?:changed|update)/i.test(diagnostics)
+                    ? "locked project/runtime mismatch"
+                    : /no space left|ENOSPC/i.test(diagnostics)
+                        ? "disk full"
+                        : /no (?:python|interpreter)|python.*(?:not found|unavailable)/i.test(diagnostics)
+                            ? "compatible Python unavailable"
+                            : /failed to (?:download|fetch)|connection refused|network|cache missing/i.test(diagnostics)
+                                ? "download, network or cache unavailable"
+                                : /exclusive (?:lease|ownership)|shared store owners/i.test(diagnostics)
+                                    ? "exclusive ownership verification failed"
+                                    : /protected state|table changed|state.*changed/i.test(diagnostics)
+                                        ? "current/protected state verification failed"
+                                        : "unclassified child failure";
+                reject(new Error(`Cleanup process exited (${(_c = signal !== null && signal !== void 0 ? signal : code) !== null && _c !== void 0 ? _c : "unknown"}): ${detail}; cleanup completion is uncertain`));
+            }
+            else
+                resolve(output);
+        });
+        (_b = child.stdin) === null || _b === void 0 ? void 0 : _b.on("error", () => stop("Prune admission pipe failed"));
+        if (options.admission) {
+            try {
+                if (!child.pid)
+                    throw Error();
+                options.admission.start(child.pid);
+                monitor = setInterval(() => {
+                    try {
+                        options.admission.check();
+                    }
+                    catch (_a) {
+                        stop("Prune host/resource admission changed");
+                    }
+                }, 5000);
+            }
+            catch (_e) {
+                stop("Prune helper launch admission refused");
+            }
+        }
+        if ((_c = options.signal) === null || _c === void 0 ? void 0 : _c.aborted)
+            abort();
+    });
+}
+let preparation;
+/** Explicit recovery only. Containment has no automatic caller of this setup. */
+function prepareCleanupRuntime(signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+            throw new Error("Cleanup setup cancelled");
+        if (process.platform !== "darwin" && process.platform !== "linux")
+            throw new Error("Prune-only runtime currently supports macOS and Linux");
+        if (!preparation) {
+            preparation = (() => __awaiter(this, void 0, void 0, function* () {
+                const stdout = yield runCleanupProcess("uv", ["--version"], {
+                    signal,
+                    timeoutMs: 10000,
+                });
+                const match = /^uv (\d+)\.(\d+)\.(\d+)/.exec(stdout);
+                if (!match ||
+                    (Number(match[1]) === 0 &&
+                        (Number(match[2]) < 12 ||
+                            (Number(match[2]) === 12 && Number(match[3]) < 18)))) {
+                    throw new Error("Prune-only runtime requires uv >=0.12.18");
+                }
+                const hash = (0, node_crypto_1.createHash)("sha256")
+                    .update(fs.readFileSync(path.join(project, "pyproject.toml")))
+                    .update(fs.readFileSync(path.join(project, "uv.lock")))
+                    .digest("hex")
+                    .slice(0, 16);
+                const root = path.join(config_1.PATHS.sharedRoot, "runtimes");
+                fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+                if (fs.lstatSync(root).isSymbolicLink())
+                    throw new Error("Unverified cleanup runtime directory");
+                fs.chmodSync(root, 0o700);
+                const environment = path.join(root, `lance-cleanup-${hash}`);
+                const python = path.join(environment, process.platform === "win32" ? "Scripts/python.exe" : "bin/python");
+                if (fs.existsSync(environment)) {
+                    if (!fs.lstatSync(environment).isDirectory() ||
+                        fs.lstatSync(environment).isSymbolicLink())
+                        throw new Error("Unverified cleanup environment");
+                    yield runCleanupProcess("uv", [
+                        "sync",
+                        "--check",
+                        "--locked",
+                        "--offline",
+                        "--project",
+                        project,
+                        "--no-dev",
+                        "--no-python-downloads",
+                        "--no-build",
+                    ], {
+                        signal,
+                        timeoutMs: 10000,
+                        env: { UV_PROJECT_ENVIRONMENT: environment },
+                    });
+                    return { python, script: path.join(project, "prune.py") };
+                }
+                const available = fs.statfsSync(root);
+                const freeBytes = available.bavail * available.bsize;
+                if (!Number.isFinite(freeBytes) || freeBytes < 512 * Math.pow(1024, 2)) {
+                    throw new Error("Cleanup runtime setup refused: less than 512MiB free");
+                }
+                yield runCleanupProcess("uv", [
+                    "sync",
+                    "--locked",
+                    "--project",
+                    project,
+                    "--no-dev",
+                    "--no-python-downloads",
+                    "--no-build",
+                ], {
+                    signal,
+                    env: { UV_PROJECT_ENVIRONMENT: environment },
+                });
+                fs.chmodSync(environment, 0o700);
+                return {
+                    python,
+                    script: path.join(project, "prune.py"),
+                };
+            }))().catch((error) => {
+                preparation = undefined;
+                throw error;
+            });
+        }
+        return preparation;
+    });
+}
+/** Explicit recovery only. Caller must have drained local work/readers before
+ * acquiring the exclusive lease. The lease cannot be released during this call. */
+function pruneVersions(runtime, store, version, cutoff, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        if (!((options === null || options === void 0 ? void 0 : options.lease) instanceof store_lease_1.StoreLease))
+            throw new Error("Pruning requires a verified StoreLease token");
+        if (!Number.isSafeInteger(version) ||
+            version < 1 ||
+            !Number.isSafeInteger(cutoff.getTime()) ||
+            cutoff.getTime() > Date.now()) {
+            throw new Error("Invalid prune version or future cutoff");
+        }
+        const table = fs.realpathSync(store);
+        if (!table.endsWith(".lance") || !fs.statSync(table).isDirectory())
+            throw new Error("Pruning requires a local Lance table");
+        const storeDir = path.dirname(table);
+        if ((_a = options.signal) === null || _a === void 0 ? void 0 : _a.aborted)
+            throw new Error("Cleanup cancelled before launch");
+        let attempt;
+        let admission;
+        try {
+            const result = yield options.lease.withExclusiveUse(storeDir, () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const previous = (0, prune_state_1.readPruneState)(storeDir);
+                if ((previous === null || previous === void 0 ? void 0 : previous.outcome) === "uncertain" &&
+                    options.acknowledgeUncertain !== previous.attemptId)
+                    throw new Error(`Previous prune completion is uncertain; explicit acknowledgement required for attempt ${previous.attemptId}`);
+                admission = (_a = options.admission) !== null && _a !== void 0 ? _a : (0, recovery_admission_1.admitPrune)(storeDir);
+                attempt = {
+                    schemaVersion: 1,
+                    storeIdentity: fs.realpathSync(storeDir),
+                    attemptId: (0, node_crypto_1.randomUUID)(),
+                    version,
+                    cutoffMs: cutoff.getTime(),
+                    startedAt: Date.now(),
+                    outcome: "running",
+                    previousUncertainAttemptId: (previous === null || previous === void 0 ? void 0 : previous.outcome) === "uncertain"
+                        ? previous.attemptId
+                        : previous === null || previous === void 0 ? void 0 : previous.previousUncertainAttemptId,
+                };
+                (0, prune_state_1.writePruneState)(attempt);
+                let unpin;
+                const stdout = yield runCleanupProcess(runtime.python, [
+                    "-I",
+                    runtime.script,
+                    "--store",
+                    table,
+                    "--version",
+                    String(version),
+                    "--cutoff-ms",
+                    String(cutoff.getTime()),
+                    "--lease-owner",
+                    (0, store_lease_1.storeLeasePaths)(storeDir).intentOwnerFile,
+                    "--lease-nonce",
+                    options.lease.owner.nonce,
+                    "--require-admission",
+                ], {
+                    signal: options.signal,
+                    admission: {
+                        nonce: options.lease.owner.nonce,
+                        start: (pid) => {
+                            unpin = options.lease.pinExclusiveHelper(pid);
+                            admission.start(pid);
+                        },
+                        approve: () => admission.approve(),
+                        check: () => admission.check(),
+                        close: () => {
+                            try {
+                                unpin === null || unpin === void 0 ? void 0 : unpin();
+                            }
+                            finally {
+                                admission.close();
+                                admission = undefined;
+                            }
+                        },
+                    },
+                });
+                const result = JSON.parse(stdout);
+                if (result.engine !== "12.0.0" ||
+                    result.version !== version ||
+                    result.rewritten !== false ||
+                    ![
+                        "fragments",
+                        "bytesRemoved",
+                        "versionsRemoved",
+                        "fileBytesBefore",
+                        "fileBytesAfter",
+                        "allocatedBytesBefore",
+                        "allocatedBytesAfter",
+                        "freeBytesBefore",
+                        "freeBytesAfter",
+                    ].every((key) => {
+                        const value = result[key];
+                        return (typeof value === "number" &&
+                            Number.isSafeInteger(value) &&
+                            value >= 0);
+                    }))
+                    throw new Error("Invalid prune-only cleanup result; cleanup completion is uncertain");
+                return result;
+            }));
+            // withExclusiveUse verifies ownership again before this synchronous write.
+            // The caller still holds the lease; it cannot release it during the helper.
+            (0, prune_state_1.writePruneState)(Object.assign(Object.assign({}, attempt), { outcome: "completed", finishedAt: Date.now(), result }));
+            return result;
+        }
+        catch (error) {
+            if (attempt) {
+                try {
+                    (0, prune_state_1.writePruneState)(Object.assign(Object.assign({}, attempt), { outcome: "uncertain", finishedAt: Date.now() }));
+                }
+                catch (_b) {
+                    throw new Error("Prune completion is uncertain; durable outcome could not be recorded");
+                }
+            }
+            throw error;
+        }
+        finally {
+            admission === null || admission === void 0 ? void 0 : admission.close();
+        }
+    });
+}