grepmax 0.26.80 → 0.26.81

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.80",
+      "version": "0.26.81",
       "author": {
         "name": "Robert Owens",
         "email": "robowens@me.com"

package/README.md

@@ -524,13 +524,13 @@ To serve bounded reads under an existing startup quarantine, run `gmax watch --d
 
 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.
+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. The daemon runs independent prune-only retention: at most 128 old versions per pass, keeping current, tagged and two-minute recent versions. It retries backlog every minute and checks settled history every five minutes; status polling and watched edits do not prevent cleanup. Runtime setup happens before writer suspension. Older readers and external store owners are drained under an exclusive lease; new read-only queries may use the protected current version while history is deleted. Writers resume and watchers reconcile edits after the pass. Full-table compaction admission never gates this reclamation. Normal configured host policy applies; explicit offline recovery retains its separate admission.
 
 `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 uses the shared aggregate resource budget and requires measured OS pressure and healthy kernel pressure. The configured `critical-only` policy permits a known OS memory warning while retaining aggregate accounting; the default `strict` policy pauses on warnings. Immediately free RAM is measured for diagnostics but has no fixed minimum: macOS can reclaim cached memory, so a low free-page count alone must not prevent cleanup. 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 a five-second kernel probe allowance, three-second command allowance and three-second footprint allowance, with fresh sampling at deletion admission and five-second heartbeat scheduling. Unknown, stale, critical, kernel-warning or over-budget measurements refuse/interrupt recovery. A prune has a ten-minute wall-time ceiling so rate-limited deletion of thousands of manifests can finish; the 90-second CPU limit and guarded heartbeat remain. 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.
+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. Explicit recovery requires verification and acknowledgement of interrupted attempts. Automatic retention may make a fresh exclusively owned prune-only pass after interruption; it re-verifies retained state and links the prior uncertain attempt without claiming that attempt succeeded. Linux/APFS fixtures exercise native retention and interruption; supported production host admission is tested separately and still runs freshly for each operation.
 
 If a short-lived client child exits during memory sampling, confirmed dead processes can leave the sample while all surviving processes retain measured footprints. An uncertain exit, new process or changed identity requires a complete fresh measurement; a recovery sample may do that once within the original deadline while retaining any observed OS warning for the final policy check. Normal service requires normal pressure for this retry. It never accepts an unmeasured live process. Continued changes, unavailable measurements and critical pressure still refuse admission; warning admission follows the recovery policy above.
 
@@ -544,9 +544,9 @@ For an operator-coordinated recovery window:
 
 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`.
+`~/.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 historical compaction under `daemon.compaction` and independent retention under `daemon.versionCleanup`; their `at` timestamps identify when each was recorded. Retention reports versions removed, eligible backlog, allocated bytes before/after and signed net reclamation, with `rewritten: false`. 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`.
 
-`gmax doctor --fix` refuses work under quarantine and otherwise reports optimization skipped by containment. It exits nonzero when a requested optimization did not complete or an older daemon could not verify its outcome. A busy or failed daemon is never retried as a second writer in the CLI process.
+`gmax doctor --fix` refuses work under quarantine. With a current daemon it requests prune-only version cleanup; it does not enable full-table rewriting. Without a daemon, the historical full-table optimizer remains disabled. It exits nonzero when a requested optimization did not complete or an older daemon could not verify its outcome. A busy or failed daemon is never retried as a second writer in the CLI process.
 
 ### Known issues
 

package/dist/lib/daemon/daemon.js

@@ -62,6 +62,7 @@ const maintenance_policy_1 = require("../store/maintenance-policy");
 const meta_cache_1 = require("../store/meta-cache");
 const store_lease_1 = require("../store/store-lease");
 const vector_db_1 = require("../store/vector-db");
+const version_cleanup_1 = require("../store/version-cleanup");
 const async_semaphore_1 = require("../utils/async-semaphore");
 const autostart_1 = require("../utils/autostart");
 const blocked_roots_1 = require("../utils/blocked-roots");
@@ -159,6 +160,9 @@ class Daemon {
         this.startTime = Date.now();
         this.heartbeatInterval = null;
         this.idleInterval = null;
+        this.cleanupInterval = null;
+        this.cleanupPromise = null;
+        this.lastCleanupAttempt = 0;
         this.heartbeatTick = 0;
         this.shuttingDown = false;
         this.recycling = false;
@@ -450,6 +454,7 @@ class Daemon {
                 this.assertStartupActive();
                 // Resources are open — only now may resource-dependent IPC commands run.
                 this.ready = true;
+                this.startVersionCleanupLoop();
             }
             catch (err) {
                 console.error("[daemon] Failed to open shared resources:", err);
@@ -830,7 +835,7 @@ class Daemon {
             const db = this.vectorDb;
             if (!db)
                 throw new Error("daemon resources not ready");
-            const compaction = yield this.runSharedOperation("store-maintenance", undefined, () => db.runMaintenance({ force: true }));
+            const compaction = yield this.runVersionCleanup();
             if (!compaction)
                 return { ok: false, error: "maintenance produced no compaction outcome" };
             return Object.assign({ ok: compaction.status === "completed", compaction }, (compaction.status === "completed"
@@ -838,6 +843,95 @@ class Daemon {
                 : { error: (_a = compaction.reason) !== null && _a !== void 0 ? _a : compaction.status }));
         });
     }
+    versionCleanupStatus() {
+        var _a;
+        var _b;
+        return (_b = (_a = this.vectorDb) === null || _a === void 0 ? void 0 : _a.versionCleanupStatus()) !== null && _b !== void 0 ? _b : null;
+    }
+    /** Status polling and watched edits cannot starve independent reclamation. */
+    startVersionCleanupLoop() {
+        if (this.cleanupInterval)
+            return;
+        this.cleanupInterval = setInterval(() => {
+            var _a;
+            const interval = ((_a = this.versionCleanupStatus()) === null || _a === void 0 ? void 0 : _a.eligibleVersionsRemaining) === 0
+                ? 5 * 60000
+                : 60000;
+            if (!this.ready ||
+                this.shuttingDown ||
+                this.recycling ||
+                this.pausedReason !== null ||
+                this.cleanupPromise ||
+                this.operations.status !== "open" ||
+                Date.now() - this.lastCleanupAttempt < interval)
+                return;
+            void this.runVersionCleanup().catch((error) => {
+                (0, logger_1.log)("daemon", `Version cleanup deferred: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }, 60000);
+        this.cleanupInterval.unref();
+    }
+    runVersionCleanup() {
+        if (this.cleanupPromise)
+            return this.cleanupPromise;
+        this.lastCleanupAttempt = Date.now();
+        const run = this.performVersionCleanup();
+        const tracked = run.finally(() => {
+            if (this.cleanupPromise === tracked)
+                this.cleanupPromise = null;
+        });
+        this.cleanupPromise = tracked;
+        return tracked;
+    }
+    performVersionCleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.vectorDb ||
+                !this.ready ||
+                this.shuttingDown ||
+                this.recycling ||
+                this.pausedReason !== null)
+                throw new Error("daemon resources not ready for version cleanup");
+            this.assertHeavyOperationAdmission("version-cleanup");
+            const deadline = AbortSignal.timeout(60000);
+            const runtime = yield (0, version_cleanup_1.prepareVersionCleanup)(config_1.PATHS.lancedbDir, deadline);
+            let roots = [];
+            try {
+                return yield this.operations.runExclusive("version-cleanup", () => __awaiter(this, void 0, void 0, function* () {
+                    deadline.throwIfAborted();
+                    this.assertHeavyOperationAdmission("version-cleanup");
+                    roots = [
+                        ...new Set([
+                            ...this.processors.keys(),
+                            ...this.subscriptions.keys(),
+                        ]),
+                    ];
+                    yield this.watcherManager.quiesceAll();
+                }), (signal) => __awaiter(this, void 0, void 0, function* () {
+                    this.assertHeavyOperationAdmission("version-cleanup");
+                    const result = yield this.vectorDb.cleanupVersions(runtime, AbortSignal.any([signal, deadline]), () => this.operations.openVersionCleanupReadWindow((name) => (0, read_verbs_1.getReadVerb)(name) !== undefined ||
+                        [
+                            "search",
+                            "keyword-search",
+                            "documents",
+                            "project-stats",
+                        ].includes(name)));
+                    if (!result)
+                        return (0, compaction_result_1.skippedCompaction)("no indexed table");
+                    (0, logger_1.log)("daemon", `Version cleanup completed: ${JSON.stringify(result)}`);
+                    return result;
+                }), { queueShared: true });
+            }
+            finally {
+                if (!this.shuttingDown &&
+                    this.ready &&
+                    this.pausedReason === null &&
+                    roots.length) {
+                    yield this.watcherManager.resumeAll(roots, { catchup: false });
+                    yield this.watcherManager.catchupAll(roots);
+                }
+            }
+        });
+    }
     operationStatus() {
         return this.operations.status;
     }
@@ -2468,6 +2562,8 @@ class Daemon {
                 clearInterval(this.heartbeatInterval);
             if (this.idleInterval)
                 clearInterval(this.idleInterval);
+            if (this.cleanupInterval)
+                clearInterval(this.cleanupInterval);
             for (const timer of this.pendingIndexRetryTimers.values()) {
                 clearTimeout(timer);
             }

package/dist/lib/daemon/ipc-handler.js

@@ -125,8 +125,8 @@ function startHeartbeat(conn, intervalMs = HEARTBEAT_INTERVAL_MS) {
  */
 function handleCommand(daemon, cmd, conn) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d;
-        var _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+        var _a, _b, _c, _d, _e;
+        var _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
         try {
             (0, logger_1.debug)("daemon", `ipc cmd=${cmd.cmd}${cmd.root ? ` root=${cmd.root}` : ""}`);
             if (cmd.cmd !== "ping" &&
@@ -197,13 +197,14 @@ function handleCommand(daemon, cmd, conn) {
                         diskPressure: daemon.getDiskPressure(),
                         mlx: daemon.getMlxStatus(),
                         workers: daemon.workerCount(),
-                        resources: (_e = (_b = daemon.resourceSnapshot) === null || _b === void 0 ? void 0 : _b.call(daemon)) !== null && _e !== void 0 ? _e : null,
-                        compaction: (_f = (_c = daemon.compactionStatus) === null || _c === void 0 ? void 0 : _c.call(daemon)) !== null && _f !== void 0 ? _f : null,
+                        resources: (_f = (_b = daemon.resourceSnapshot) === null || _b === void 0 ? void 0 : _b.call(daemon)) !== null && _f !== void 0 ? _f : null,
+                        compaction: (_g = (_c = daemon.compactionStatus) === null || _c === void 0 ? void 0 : _c.call(daemon)) !== null && _g !== void 0 ? _g : null,
+                        versionCleanup: (_h = (_d = daemon.versionCleanupStatus) === null || _d === void 0 ? void 0 : _d.call(daemon)) !== null && _h !== void 0 ? _h : null,
                         workerThreads: config_1.WORKER_THREADS_SETTING,
-                        service: (_d = daemon.serviceStatus) === null || _d === void 0 ? void 0 : _d.call(daemon),
+                        service: (_e = daemon.serviceStatus) === null || _e === void 0 ? void 0 : _e.call(daemon),
                     };
                 case "pause":
-                    daemon.pauseWork(String((_g = cmd.reason) !== null && _g !== void 0 ? _g : "read-only service requested"));
+                    daemon.pauseWork(String((_j = cmd.reason) !== null && _j !== void 0 ? _j : "read-only service requested"));
                     return { ok: true, service: daemon.serviceStatus() };
                 case "optimize":
                     // Keeps compaction single-writer: see Daemon.runOptimize.
@@ -218,14 +219,14 @@ function handleCommand(daemon, cmd, conn) {
                     return Object.assign({ ok: true }, (yield daemon.projectStats(root)));
                 }
                 case "shutdown": {
-                    const reason = String((_h = cmd.reason) !== null && _h !== void 0 ? _h : "unknown");
-                    const fromPid = (_j = cmd.from_pid) !== null && _j !== void 0 ? _j : "?";
-                    const fromPpid = (_k = cmd.from_ppid) !== null && _k !== void 0 ? _k : "?";
-                    const fromVer = (_l = cmd.from_version) !== null && _l !== void 0 ? _l : "?";
+                    const reason = String((_k = cmd.reason) !== null && _k !== void 0 ? _k : "unknown");
+                    const fromPid = (_l = cmd.from_pid) !== null && _l !== void 0 ? _l : "?";
+                    const fromPpid = (_m = cmd.from_ppid) !== null && _m !== void 0 ? _m : "?";
+                    const fromVer = (_o = cmd.from_version) !== null && _o !== void 0 ? _o : "?";
                     const fromArgv = Array.isArray(cmd.from_argv)
                         ? cmd.from_argv.join(" ")
                         : "?";
-                    const fromParentCmd = (_m = cmd.from_parent_cmd) !== null && _m !== void 0 ? _m : "?";
+                    const fromParentCmd = (_p = cmd.from_parent_cmd) !== null && _p !== void 0 ? _p : "?";
                     console.log(`[daemon] shutdown command received via IPC: reason=${reason} from_pid=${fromPid} from_ppid=${fromPpid} from_version=${fromVer} from_argv=[${fromArgv}] from_parent_cmd=[${fromParentCmd}]`);
                     setImmediate(() => daemon.shutdown());
                     return { ok: true };
@@ -272,7 +273,7 @@ function handleCommand(daemon, cmd, conn) {
                         try {
                             maxPerFile = (0, per_file_1.validateMaxPerFile)(cmd.maxPerFile);
                         }
-                        catch (_q) {
+                        catch (_s) {
                             return { ok: false, error: "invalid maxPerFile" };
                         }
                         if (!Number.isInteger(limitRaw) || limitRaw < 1 || limitRaw > 1000) {
@@ -319,8 +320,8 @@ function handleCommand(daemon, cmd, conn) {
                                 return { ok: false, error: "invalid project_roots" };
                             }
                             for (const prefix of [
-                                ...((_o = filters === null || filters === void 0 ? void 0 : filters.inPrefixes) !== null && _o !== void 0 ? _o : []),
-                                ...((_p = filters === null || filters === void 0 ? void 0 : filters.excludePrefixes) !== null && _p !== void 0 ? _p : []),
+                                ...((_q = filters === null || filters === void 0 ? void 0 : filters.inPrefixes) !== null && _q !== void 0 ? _q : []),
+                                ...((_r = filters === null || filters === void 0 ? void 0 : filters.excludePrefixes) !== null && _r !== void 0 ? _r : []),
                             ]) {
                                 (0, path_containment_1.resolveContainedPath)(projectRoot, prefix);
                             }

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

@@ -157,6 +157,13 @@ function runCleanupProcess(executable, args, options = {}) {
             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("exit", () => {
+            // An exited helper no longer consumes host resources. Do not turn a
+            // verified result into an uncertain receipt while stdout is draining.
+            clearTimeout(timeout);
+            if (monitor)
+                clearInterval(monitor);
+        });
         child.once("close", (code, signal) => {
             var _a, _b;
             var _c;
@@ -221,7 +228,7 @@ function runCleanupProcess(executable, args, options = {}) {
     });
 }
 let preparation;
-/** Explicit recovery only. Containment has no automatic caller of this setup. */
+/** Pinned runtime shared by explicit recovery and prune-only maintenance. */
 function prepareCleanupRuntime(signal) {
     return __awaiter(this, void 0, void 0, function* () {
         if (signal === null || signal === void 0 ? void 0 : signal.aborted)
@@ -304,7 +311,7 @@ function prepareCleanupRuntime(signal) {
         return preparation;
     });
 }
-/** Explicit recovery only. Caller must have drained local work/readers before
+/** 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* () {
@@ -317,6 +324,11 @@ function pruneVersions(runtime, store, version, cutoff, options) {
             cutoff.getTime() > Date.now()) {
             throw new Error("Invalid prune version or future cutoff");
         }
+        if (options.maxVersions !== undefined &&
+            (!Number.isSafeInteger(options.maxVersions) ||
+                options.maxVersions < 1 ||
+                options.maxVersions > 128))
+            throw new Error("Invalid bounded prune version count");
         const table = fs.realpathSync(store);
         if (!table.endsWith(".lance") || !fs.statSync(table).isDirectory())
             throw new Error("Pruning requires a local Lance table");
@@ -330,7 +342,8 @@ function pruneVersions(runtime, store, version, cutoff, options) {
                 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)
+                    options.acknowledgeUncertain !== previous.attemptId &&
+                    !options.retryUncertain)
                     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 = {
@@ -361,6 +374,9 @@ function pruneVersions(runtime, store, version, cutoff, options) {
                     "--lease-nonce",
                     options.lease.owner.nonce,
                     "--require-admission",
+                    ...(options.maxVersions === undefined
+                        ? []
+                        : ["--max-versions", String(options.maxVersions)]),
                 ], {
                     signal: options.signal,
                     timeoutMs: MAX_PRUNE_MS,
@@ -387,6 +403,10 @@ function pruneVersions(runtime, store, version, cutoff, options) {
                 if (result.engine !== "12.0.0" ||
                     result.version !== version ||
                     result.rewritten !== false ||
+                    (options.maxVersions !== undefined &&
+                        (!Number.isSafeInteger(result.eligibleVersionsRemaining) ||
+                            result.eligibleVersionsRemaining < 0 ||
+                            result.versionsRemoved > options.maxVersions)) ||
                     ![
                         "fragments",
                         "bytesRemoved",

package/dist/lib/store/maintenance-policy.js

@@ -41,13 +41,14 @@ exports.storeMutationDeniedReason = storeMutationDeniedReason;
 exports.assertStoreMutationAllowed = assertStoreMutationAllowed;
 exports.maintenancePolicyPath = maintenancePolicyPath;
 exports.recordMaintenanceContainment = recordMaintenanceContainment;
+exports.recordVersionCleanupCompleted = recordVersionCleanupCompleted;
 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 autostart_1 = require("../utils/autostart");
 const safety_latch_1 = require("../utils/safety-latch");
-exports.FULL_TABLE_MAINTENANCE_DISABLED_REASON = "full-table maintenance disabled by host-safety containment; disk recovery is pending";
+exports.FULL_TABLE_MAINTENANCE_DISABLED_REASON = "full-table maintenance disabled by host-safety containment; version cleanup runs independently";
 /** This release has no production override: force, configuration and persisted
  * state cannot enable rewriting. Tests may mock this module to cover the old
  * native algorithm without turning it into a supported production entry point. */
@@ -122,7 +123,8 @@ function recordMaintenanceContainment(storeDir) {
                 previous.storeIdentity === storeIdentity &&
                 previous.mode === "disabled" &&
                 previous.rewriteBudgetBytes === 0 &&
-                previous.cleanupPending === true) {
+                typeof previous.cleanupPending === "boolean" &&
+                previous.reason === exports.FULL_TABLE_MAINTENANCE_DISABLED_REASON) {
                 fs.chmodSync(target, 0o600);
                 return exports.FULL_TABLE_MAINTENANCE_DISABLED_REASON;
             }
@@ -170,3 +172,41 @@ function recordMaintenanceContainment(storeDir) {
         }
     }
 }
+/** A completed prune changes retention state, never enables table rewrites. */
+function recordVersionCleanupCompleted(storeDir, at) {
+    recordMaintenanceContainment(storeDir);
+    const identity = fs.realpathSync(storeDir);
+    const target = maintenancePolicyPath(identity);
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.size > 16 * 1024)
+        throw new Error("maintenance receipt is unverified");
+    const policy = JSON.parse(fs.readFileSync(target, "utf8"));
+    if (policy.storeIdentity !== identity ||
+        policy.mode !== "disabled" ||
+        policy.rewriteBudgetBytes !== 0 ||
+        !Number.isSafeInteger(at))
+        throw new Error("maintenance receipt is invalid");
+    const temporary = path.join(identity, `.gmax-maintenance-${(0, node_crypto_1.randomUUID)()}.tmp`);
+    try {
+        const descriptor = fs.openSync(temporary, "wx", 0o600);
+        try {
+            fs.writeFileSync(descriptor, `${JSON.stringify(Object.assign(Object.assign({}, policy), { cleanupPending: false, lastVersionCleanupAt: at }))}\n`);
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        fs.renameSync(temporary, target);
+        const directory = fs.openSync(identity, "r");
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}

package/dist/lib/store/vector-db.js

@@ -69,6 +69,7 @@ const compaction_result_1 = require("./compaction-result");
 const lancedb = __importStar(require("./lance-sdk"));
 const maintenance_policy_1 = require("./maintenance-policy");
 const store_lease_1 = require("./store-lease");
+const version_cleanup_1 = require("./version-cleanup");
 /**
  * Find abandoned Lance scratch files under `<lancedbDir>/ *.lance/data`.
  *
@@ -239,6 +240,9 @@ class VectorDB {
         this.indexOwner = false;
         this.lastOptimizeDidWork = false;
         this.lastCompactionResult = null;
+        this.lastVersionCleanupResult = null;
+        this.versionCleanupActive = false;
+        this.versionCleanupPromise = null;
         /** Compaction rate limiter — see COMPACTION_MIN_INTERVAL_MS. */
         this.lastCompactionMs = 0;
         this.compactionIntervalMs = COMPACTION_MIN_INTERVAL_MS;
@@ -354,7 +358,7 @@ class VectorDB {
         }
     }
     isMaintenanceActive() {
-        return this.maintenancePromise !== null;
+        return this.maintenancePromise !== null || this.versionCleanupActive;
     }
     maintenanceDue() {
         return (this.writeEpoch !== this.maintainedEpoch ||
@@ -375,6 +379,65 @@ class VectorDB {
     resumeMaintenanceLoop() {
         this.startMaintenanceLoop();
     }
+    /** The daemon has drained operations and quiesced watchers before calling.
+     * Close native handles before the helper owns the store; keep this instance
+     * and worker/searcher references available after shared ownership resumes. */
+    versionCleanupStatus() {
+        return this.lastVersionCleanupResult
+            ? Object.assign({}, this.lastVersionCleanupResult) : null;
+    }
+    cleanupVersions(runtime, signal, allowCurrentReads) {
+        if (this.versionCleanupPromise)
+            return this.versionCleanupPromise;
+        const run = this.performVersionCleanup(runtime, signal, allowCurrentReads);
+        const tracked = run.finally(() => {
+            if (this.versionCleanupPromise === tracked)
+                this.versionCleanupPromise = null;
+        });
+        this.versionCleanupPromise = tracked;
+        return tracked;
+    }
+    performVersionCleanup(runtime, signal, allowCurrentReads) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            this.assertMutationAllowed();
+            this.versionCleanupActive = true;
+            try {
+                const lease = yield this.upgradeStoreLease(signal, 750);
+                yield Promise.all([this.drainWrites(), this.drainCompactions()]);
+                const table = yield this.openExistingTableUnsafe();
+                if (!table)
+                    return null;
+                let version;
+                try {
+                    version = yield table.version();
+                }
+                finally {
+                    table.close();
+                }
+                (_a = this.db) === null || _a === void 0 ? void 0 : _a.close();
+                this.db = null;
+                this.session = null;
+                (_b = this.resourceReservation) === null || _b === void 0 ? void 0 : _b.release();
+                this.resourceReservation = null;
+                // All older readers are drained. New queries can only open the protected
+                // latest version while writers stay excluded for this prune-only pass.
+                allowCurrentReads === null || allowCurrentReads === void 0 ? void 0 : allowCurrentReads();
+                const result = yield (0, version_cleanup_1.runVersionCleanup)(this.lancedbDir, lease, version, runtime, signal);
+                this.lastVersionCleanupResult = result;
+                return result;
+            }
+            finally {
+                try {
+                    if (!this.closed)
+                        yield this.downgradeStoreLease();
+                }
+                finally {
+                    this.versionCleanupActive = false;
+                }
+            }
+        });
+    }
     getDb() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -461,7 +524,7 @@ class VectorDB {
         });
     }
     /** Upgrade and retain this instance's current lease for transfer to a new DB. */
-    upgradeStoreLease(signal) {
+    upgradeStoreLease(signal, timeoutMs) {
         return __awaiter(this, void 0, void 0, function* () {
             this.assertMutationAllowed();
             if (this.closed)
@@ -472,7 +535,7 @@ class VectorDB {
                 const current = yield this.getLease();
                 if (current.mode === "exclusive")
                     return current;
-                const upgrade = current.upgrade({ signal });
+                const upgrade = current.upgrade({ signal, timeoutMs });
                 this.leasePromise = upgrade;
                 try {
                     const upgraded = yield upgrade;
@@ -560,6 +623,8 @@ class VectorDB {
      */
     withWriteGate(fn) {
         return __awaiter(this, void 0, void 0, function* () {
+            if (this.versionCleanupActive)
+                throw new Error("writes paused for version cleanup");
             this.assertMutationAllowed();
             this.ensureDiskOk();
             while (this.exclusiveMutationPromise || this.compactingPromise) {
@@ -807,7 +872,8 @@ class VectorDB {
     }
     ensureTable() {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.options.readOnly ||
+            if (this.versionCleanupActive ||
+                this.options.readOnly ||
                 (0, maintenance_policy_1.storeMutationDeniedReason)() !== null ||
                 this.checkDiskPressure(true) === "critical") {
                 const existing = yield this.openExistingTableUnsafe();
@@ -1913,8 +1979,9 @@ class VectorDB {
     }
     finishClose() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c;
-            yield (_a = this.connecting) === null || _a === void 0 ? void 0 : _a.catch(() => { });
+            var _a, _b, _c, _d;
+            yield (_a = this.versionCleanupPromise) === null || _a === void 0 ? void 0 : _a.catch(() => { });
+            yield (_b = this.connecting) === null || _b === void 0 ? void 0 : _b.catch(() => { });
             if (this.maintenanceTimer) {
                 clearInterval(this.maintenanceTimer);
                 this.maintenanceTimer = null;
@@ -1933,11 +2000,11 @@ class VectorDB {
                 ]);
                 this.maintenancePromise = null;
             }
-            (_b = this.unregisterCleanup) === null || _b === void 0 ? void 0 : _b.call(this);
+            (_c = this.unregisterCleanup) === null || _c === void 0 ? void 0 : _c.call(this);
             this.unregisterCleanup = undefined;
             let closeError;
             let nativeClosed = !this.db;
-            if ((_c = this.db) === null || _c === void 0 ? void 0 : _c.close) {
+            if ((_d = this.db) === null || _d === void 0 ? void 0 : _d.close) {
                 try {
                     const closing = this.db.close();
                     void Promise.resolve(closing).then(() => {
@@ -1978,7 +2045,7 @@ class VectorDB {
                 try {
                     lease = yield this.leasePromise;
                 }
-                catch (_d) {
+                catch (_e) {
                     this.leasePromise = null;
                 }
                 if (lease) {

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

@@ -0,0 +1,120 @@
+"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.MAX_CLEANUP_VERSIONS = exports.VERSION_RETENTION_MS = void 0;
+exports.prepareVersionCleanup = prepareVersionCleanup;
+exports.runVersionCleanup = runVersionCleanup;
+const path = __importStar(require("node:path"));
+const resource_budget_1 = require("../utils/resource-budget");
+const lance_cleanup_1 = require("./lance-cleanup");
+const maintenance_policy_1 = require("./maintenance-policy");
+exports.VERSION_RETENTION_MS = 2 * 60000;
+exports.MAX_CLEANUP_VERSIONS = 128;
+function check(storeDir, signal) {
+    signal === null || signal === void 0 ? void 0 : signal.throwIfAborted();
+    (0, maintenance_policy_1.assertStoreMutationAllowed)();
+    const free = (0, maintenance_policy_1.availableStoreDiskBytes)(storeDir);
+    // Reclamation needs metadata space, never room for a second copy of the table.
+    if (!Number.isFinite(free) || free < Math.pow(1024, 2))
+        throw new Error("version cleanup metadata disk headroom unavailable");
+    resource_budget_1.resourceBudget.check();
+}
+/** Prepare before pausing service. Runtime downloads never hold store ownership. */
+function prepareVersionCleanup(storeDir, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        check(storeDir, signal);
+        const reservation = resource_budget_1.resourceBudget.reserve(512, "cleanup-runtime");
+        try {
+            return yield (0, lance_cleanup_1.prepareCleanupRuntime)(signal);
+        }
+        finally {
+            reservation.release();
+        }
+    });
+}
+/** Independent retention: no optimizer, compaction plan or rewrite admission. */
+function runVersionCleanup(storeDir, lease, version, runtime, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const started = Date.now();
+        check(storeDir, signal);
+        const reservation = resource_budget_1.resourceBudget.reserve(512, "version-cleanup");
+        try {
+            const result = yield (0, lance_cleanup_1.pruneVersions)(runtime, path.join(storeDir, "chunks.lance"), version, new Date(Date.now() - exports.VERSION_RETENTION_MS), {
+                lease,
+                signal,
+                maxVersions: exports.MAX_CLEANUP_VERSIONS,
+                retryUncertain: true,
+                admission: {
+                    start: (pid) => reservation.attach(pid),
+                    approve: () => check(storeDir, signal),
+                    check: () => check(storeDir, signal),
+                    close: () => reservation.release(),
+                },
+            });
+            const outcome = {
+                status: "completed",
+                reason: "old versions reclaimed without rewriting data",
+                at: Date.now(),
+                attempts: 1,
+                elapsedMs: Date.now() - started,
+                rewritten: false,
+                versionsRemoved: result.versionsRemoved,
+                eligibleVersionsRemaining: (_a = result.eligibleVersionsRemaining) !== null && _a !== void 0 ? _a : 0,
+                diskBytesBefore: result.allocatedBytesBefore,
+                diskBytesAfter: result.allocatedBytesAfter,
+                freeBytesBefore: result.freeBytesBefore,
+                freeBytesAfter: result.freeBytesAfter,
+                bytesReclaimed: result.bytesRemoved,
+                netBytesReclaimed: result.allocatedBytesBefore - result.allocatedBytesAfter,
+                cleanupPasses: 1,
+            };
+            (0, maintenance_policy_1.recordVersionCleanupCompleted)(storeDir, outcome.at);
+            return outcome;
+        }
+        finally {
+            reservation.release();
+        }
+    });
+}

package/dist/lib/utils/operation-coordinator.js

@@ -41,6 +41,8 @@ class OperationCoordinator {
         this.sharedTasks = new Set();
         this.taskNames = new Map();
         this.closePromise = null;
+        this.queueShared = false;
+        this.waiters = new Set();
     }
     get status() {
         return this.state.kind;
@@ -53,8 +55,40 @@ class OperationCoordinator {
         return [...this.activeTasks].map((task) => { var _a; return (_a = this.taskNames.get(task)) !== null && _a !== void 0 ? _a : "?"; });
     }
     runShared(name, signal, fn) {
+        var _a;
+        if (this.queueShared &&
+            (this.state.kind === "exclusive" ||
+                this.state.kind === "exclusive-pending") &&
+            !((_a = this.readWindow) === null || _a === void 0 ? void 0 : _a.call(this, name)) &&
+            !name.startsWith("watch") &&
+            name !== "store-maintenance") {
+            if (this.waiters.size >= 64)
+                return Promise.reject(new OperationBusyError(this.state.name));
+            if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                return Promise.reject(abortError(signal.reason));
+            return new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    this.waiters.delete(waiter);
+                    signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", abort);
+                };
+                const waiter = {
+                    name,
+                    resume: () => {
+                        cleanup();
+                        resolve(this.runShared(name, signal, fn));
+                    },
+                    reject: (error) => {
+                        cleanup();
+                        reject(error);
+                    },
+                };
+                const abort = () => waiter.reject(abortError(signal === null || signal === void 0 ? void 0 : signal.reason));
+                this.waiters.add(waiter);
+                signal === null || signal === void 0 ? void 0 : signal.addEventListener("abort", abort, { once: true });
+            });
+        }
         try {
-            this.assertSharedAdmission();
+            this.assertSharedAdmission(name);
         }
         catch (error) {
             return Promise.reject(error);
@@ -81,7 +115,8 @@ class OperationCoordinator {
         void task.then(cleanup, cleanup);
         return task;
     }
-    runExclusive(name, quiesce, fn) {
+    runExclusive(name, quiesce, fn, options = {}) {
+        var _a;
         if (this.state.kind === "closing" || this.state.kind === "closed") {
             return Promise.reject(new OperationClosedError());
         }
@@ -90,6 +125,7 @@ class OperationCoordinator {
             return Promise.reject(new OperationBusyError(current));
         }
         this.state = { kind: "exclusive-pending", name };
+        this.queueShared = (_a = options.queueShared) !== null && _a !== void 0 ? _a : false;
         const controller = new AbortController();
         this.controllers.add(controller);
         const task = (() => __awaiter(this, void 0, void 0, function* () {
@@ -111,6 +147,10 @@ class OperationCoordinator {
                     this.state.kind === "exclusive-pending") {
                     this.state = { kind: "open" };
                 }
+                this.queueShared = false;
+                this.readWindow = undefined;
+                for (const waiter of [...this.waiters])
+                    waiter.resume();
             }
         }))();
         this.activeTasks.add(task);
@@ -122,6 +162,18 @@ class OperationCoordinator {
         void task.then(cleanup, cleanup);
         return task;
     }
+    /** Only prune-only retention may reopen current-version reads after draining
+     * old readers and closing their native handles. Writers remain excluded. */
+    openVersionCleanupReadWindow(allowed) {
+        if (this.state.kind !== "exclusive" ||
+            this.state.name !== "version-cleanup" ||
+            !this.queueShared)
+            throw new Error("current-version reads require exclusive prune-only cleanup");
+        this.readWindow = allowed;
+        for (const waiter of [...this.waiters])
+            if (allowed(waiter.name))
+                waiter.resume();
+    }
     /** Cancel existing work without closing admission for subsequent bounded reads. */
     abortAndDrain(reason) {
         for (const controller of this.controllers)
@@ -132,6 +184,8 @@ class OperationCoordinator {
         if (this.closePromise)
             return this.closePromise;
         this.state = { kind: "closing" };
+        for (const waiter of [...this.waiters])
+            waiter.reject(reason);
         for (const controller of this.controllers)
             controller.abort(reason);
         const tasks = [...this.activeTasks];
@@ -140,12 +194,15 @@ class OperationCoordinator {
         });
         return this.closePromise;
     }
-    assertSharedAdmission() {
+    assertSharedAdmission(name) {
+        var _a;
         if (this.state.kind === "closing" || this.state.kind === "closed") {
             throw new OperationClosedError();
         }
         if (this.state.kind === "exclusive" ||
             this.state.kind === "exclusive-pending") {
+            if (this.state.kind === "exclusive" && ((_a = this.readWindow) === null || _a === void 0 ? void 0 : _a.call(this, name)))
+                return;
             throw new OperationBusyError(this.state.name);
         }
     }

package/lance-maintenance/prune.py

@@ -1,8 +1,8 @@
-"""Explicit, exclusively leased Lance 12 prune-only recovery candidate.
+"""Exclusively leased Lance 12 prune-only cleanup.
 
 Never compacts, writes rows, builds indexes or starts a server. This helper is
-not an automatic maintenance path. Native production resource validation is
-required before enabling it on a pressured host.
+used by recovery and bounded automatic retention. Native host admission and
+exclusive ownership are required before deleting files.
 """
 
 import argparse
@@ -107,7 +107,7 @@ def open_version(lance, root, version):
                          metadata_cache_size_bytes=CACHE_BYTES)
 
 
-def prune(store, expected_version, cutoff_ms, owner_file, nonce, admission=None):
+def prune(store, expected_version, cutoff_ms, owner_file, nonce, admission=None, max_versions=None):
     root = Path(store).resolve(strict=True)
     if not root.is_dir() or root.suffix != ".lance":
         raise ValueError("Cleanup requires a local Lance table directory")
@@ -116,6 +116,8 @@ def prune(store, expected_version, cutoff_ms, owner_file, nonce, admission=None)
         raise ValueError("Cleanup requires a positive current version")
     if cutoff_ms > time.time_ns() // 1_000_000:
         raise ValueError("Cleanup cutoff must not be in the future")
+    if max_versions is not None and (type(max_versions) is not int or not 1 <= max_versions <= 128):
+        raise ValueError("Invalid bounded prune version count")
     if importlib.metadata.version("pylance") != "12.0.0":
         raise ValueError("Cleanup requires pylance 12.0.0")
     before_bytes, before_allocated, before_free = measure(root)
@@ -134,6 +136,10 @@ def prune(store, expected_version, cutoff_ms, owner_file, nonce, admission=None)
             protected.add(version["version"])
         if version["version"] not in protected and version["timestamp"].timestamp() * 1000 < cutoff_ms:
             versions.append(version["version"])
+    eligible_count = len(versions)
+    if max_versions is not None:
+        versions = sorted(versions)[:max_versions]
+    retained = {version["version"] for version in all_versions} - set(versions)
     if dataset.latest_version != expected_version or verify_lease(root, owner_file, nonce) != owner:
         raise ValueError("Table or exclusive ownership changed during cleanup admission")
     if len(protected) > MAX_PROTECTED_VERSIONS:
@@ -152,7 +158,7 @@ def prune(store, expected_version, cutoff_ms, owner_file, nonce, admission=None)
     fresh = open_dataset(lance, root)
     remaining = {version["version"] for version in fresh.versions()}
     if (fresh.version != expected_version or fresh.latest_version != expected_version
-            or snapshot(fresh) != current or not protected.issubset(remaining)
+            or snapshot(fresh) != current or remaining != retained
             or set(versions).intersection(remaining)
             or verify_lease(root, owner_file, nonce) != owner):
         raise ValueError("Current/protected state or exclusive ownership changed; no retry")
@@ -166,6 +172,7 @@ def prune(store, expected_version, cutoff_ms, owner_file, nonce, admission=None)
         "bytesRemoved": stats.bytes_removed if stats else 0,
         "versionsRemoved": stats.old_versions if stats else 0,
         "rewritten": False,
+        "eligibleVersionsRemaining": eligible_count - len(versions),
         "fileBytesBefore": before_bytes, "fileBytesAfter": after_bytes,
         "allocatedBytesBefore": before_allocated, "allocatedBytesAfter": after_allocated,
         "freeBytesBefore": before_free, "freeBytesAfter": after_free,
@@ -180,6 +187,7 @@ def main():
     parser.add_argument("--lease-owner", required=True)
     parser.add_argument("--lease-nonce", required=True)
     parser.add_argument("--require-admission", action="store_true")
+    parser.add_argument("--max-versions", type=int)
     args = parser.parse_args()
     if not args.require_admission:
         parser.error("Prune helper requires guarded gmax recovery admission")
@@ -193,7 +201,8 @@ def main():
         if sys.stdin.readline(256).strip() != args.lease_nonce:
             raise ValueError("Deletion admission unavailable; no cleanup")
     print(json.dumps(prune(args.store, args.version, args.cutoff_ms, args.lease_owner,
-                          args.lease_nonce, admission if args.require_admission else None)))
+                          args.lease_nonce, admission if args.require_admission else None,
+                          args.max_versions)))
 
 
 if __name__ == "__main__":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.80",
+  "version": "0.26.81",
   "author": "Robert Owens <78518764+reowens@users.noreply.github.com>",
   "homepage": "https://github.com/reowens/grepmax",
   "bugs": {

package/plugins/grepmax/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.26.80",
+  "version": "0.26.81",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",