grepmax 0.17.4 → 0.17.5

package/README.md

@@ -66,6 +66,7 @@ gmax impact handleAuth                   # Dependents + affected tests
 gmax similar handleAuth                  # Find similar code patterns
 gmax dead handleAuth                     # Unused-symbol check via call graph (DEAD / PUBLIC EXPORT / LIVE)
 gmax context "auth system" --budget 4000 # Token-budgeted topic summary
+gmax context src/lib/auth.ts --budget 4000 # Deterministic file/path context
 ```
 
 ### Project Commands
@@ -117,7 +118,7 @@ Plugins auto-update when you run `npm install -g grepmax@latest` — no need to
 
 | Tool | Description |
 | --- | --- |
-| `semantic_search` | Search by meaning. 16+ params: query, limit, role, language, scope (project/all), project filtering, etc. |
+| `semantic_search` | Search by meaning. Pointer mode matches CLI `--agent` output; `detail=code/full` returns snippets. |
 | `code_skeleton` | File structure with bodies collapsed (~4x fewer tokens). |
 | `trace_calls` | Call graph: importers, callers (multi-hop), callees with file:line. |
 | `extract_symbol` | Complete function/class body by symbol name. |

package/dist/lib/daemon/daemon.js

@@ -76,6 +76,7 @@ const daemon_client_1 = require("../utils/daemon-client");
 const index_config_1 = require("../index/index-config");
 const log_rotate_1 = require("../utils/log-rotate");
 const pool_1 = require("../workers/pool");
+const daemon_launcher_1 = require("../utils/daemon-launcher");
 const node_child_process_1 = require("node:child_process");
 const http = __importStar(require("node:http"));
 // 30 min was too aggressive — every shutdown is a chance for races, FSEvents
@@ -93,6 +94,23 @@ const IDLE_TIMEOUT_MS = (() => {
     return parsed; // <= 0 disables the idle check below
 })();
 const HEARTBEAT_INTERVAL_MS = 60 * 1000;
+// Self-recycle. Under continuous load (a busy monorepo) the idle timeout never
+// fires, so a long-lived daemon never gets a fresh start. The 24h age trigger
+// is the primary hygiene mechanism. The RSS trigger is a backstop for a genuine
+// runaway only: the daemon's memory is dominated by LanceDB working set, which
+// legitimately spikes to ~1.7 GB during compaction (then frees) on a ~250k-chunk
+// store, so the ceiling sits well above that to avoid recycling on normal
+// spikes. The maintenance-active guard in maybeRecycle() also defers during
+// compaction. Either ceiling <= 0 disables that trigger.
+const envNum = (name, fallback) => {
+    const raw = process.env[name];
+    if (raw == null)
+        return fallback;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+const MAX_LIFETIME_MS = envNum("GMAX_DAEMON_MAX_LIFETIME_MS", 24 * 60 * 60 * 1000);
+const RSS_WATERMARK_MB = envNum("GMAX_DAEMON_RSS_WATERMARK_MB", 2560);
 // Watcher health windows used for FSEvents auto-recovery.
 const FSEVENTS_RECOVERY_INTERVAL_MS = 60 * 60 * 1000; // try recovery hourly
 const FSEVENTS_HEALTH_WINDOW_MS = 5 * 60 * 1000; // 5 min of quiet = "healthy"
@@ -112,6 +130,11 @@ class Daemon {
         this.heartbeatTick = 0;
         this.mlxRecoveryInFlight = false;
         this.shuttingDown = false;
+        this.recycling = false;
+        // PIDs flagged as orphan workers on the previous sweep. A worker must look
+        // orphaned twice in a row before we kill it, so a worker the pool forked
+        // between our process snapshot and its array update is never killed by a race.
+        this.suspectedOrphanWorkers = new Set();
         this.pendingOps = new Set();
         this.watcherFailCount = new Map();
         this.pollIntervals = new Map();
@@ -298,6 +321,8 @@ class Daemon {
                 this.heartbeatTick++;
                 if (this.heartbeatTick % 5 === 0) {
                     void this.checkMlxHealth();
+                    this.sweepOrphanWorkers();
+                    this.maybeRecycle();
                 }
             }, HEARTBEAT_INTERVAL_MS);
             // 10. Idle timeout (skip when disabled via env)
@@ -1303,6 +1328,77 @@ class Daemon {
      * the PID file, which becomes stale when a daemon is orphaned through
      * the lock-compromise path.
      */
+    /**
+     * Gracefully hand off to a fresh daemon when this one has grown too old or
+     * too large. Only fires when quiet — no active compaction and no in-flight
+     * project operations — so a recycle never interrupts indexing work. The
+     * successor re-runs catchup on startup, so nothing is lost.
+     */
+    maybeRecycle() {
+        var _a;
+        if (this.shuttingDown || this.recycling)
+            return;
+        const ageMs = process.uptime() * 1000;
+        const rssMb = process.memoryUsage().rss / (1024 * 1024);
+        const ageExceeded = MAX_LIFETIME_MS > 0 && ageMs > MAX_LIFETIME_MS;
+        const rssExceeded = RSS_WATERMARK_MB > 0 && rssMb > RSS_WATERMARK_MB;
+        if (!ageExceeded && !rssExceeded)
+            return;
+        // Defer while busy; we'll re-check next tick.
+        if ((_a = this.vectorDb) === null || _a === void 0 ? void 0 : _a.isMaintenanceActive())
+            return;
+        if (this.projectLocks.size > 0)
+            return;
+        const reason = ageExceeded
+            ? `age ${(ageMs / 3600000).toFixed(1)}h > ${(MAX_LIFETIME_MS / 3600000).toFixed(1)}h`
+            : `rss ${Math.round(rssMb)}MB > ${RSS_WATERMARK_MB}MB`;
+        console.log(`[daemon] Recycling (${reason}) — handing off to a fresh daemon`);
+        this.recycling = true;
+        void this.shutdown({ relaunch: true }).finally(() => process.exit(0));
+    }
+    /**
+     * Kill gmax-worker processes that are children of THIS daemon but the worker
+     * pool no longer tracks — strays left behind if a kill ever failed silently.
+     * Filters by parent PID so a per-project `gmax watch`'s own workers are never
+     * touched. Requires a worker to look orphaned on two consecutive sweeps so a
+     * just-forked worker can't be killed by a snapshot race.
+     */
+    sweepOrphanWorkers() {
+        if (this.shuttingDown || !(0, pool_1.isWorkerPoolInitialized)())
+            return;
+        const tracked = new Set((0, pool_1.getWorkerPool)().getWorkerPids());
+        const workerPids = new Set(this.findProcessesByTitle("gmax-worker"));
+        const ourChildren = this.findChildPids();
+        const orphans = ourChildren.filter((pid) => workerPids.has(pid) && !tracked.has(pid));
+        const confirmed = orphans.filter((pid) => this.suspectedOrphanWorkers.has(pid));
+        this.suspectedOrphanWorkers = new Set(orphans);
+        for (const pid of confirmed) {
+            console.log(`[daemon] Killing orphan worker PID:${pid} (untracked by pool)`);
+            try {
+                process.kill(pid, "SIGKILL");
+            }
+            catch (_a) { }
+            this.suspectedOrphanWorkers.delete(pid);
+        }
+    }
+    /** Child PIDs of this process (workers, MLX, llama-server). */
+    findChildPids() {
+        try {
+            const out = (0, node_child_process_1.execSync)(`pgrep -P ${process.pid}`, {
+                timeout: 5000,
+                encoding: "utf-8",
+            }).trim();
+            if (!out)
+                return [];
+            return out
+                .split("\n")
+                .map((s) => parseInt(s.trim(), 10))
+                .filter((n) => Number.isFinite(n) && n > 0);
+        }
+        catch (_a) {
+            return [];
+        }
+    }
     killStaleProcesses() {
         return __awaiter(this, void 0, void 0, function* () {
             // 1. Check for other daemon processes
@@ -1359,7 +1455,7 @@ class Daemon {
         }
     }
     shutdown() {
-        return __awaiter(this, void 0, void 0, function* () {
+        return __awaiter(this, arguments, void 0, function* (opts = {}) {
             var _a, _b, _c, _d;
             if (this.shuttingDown)
                 return;
@@ -1449,6 +1545,14 @@ class Daemon {
                 yield ((_d = this.vectorDb) === null || _d === void 0 ? void 0 : _d.close());
             }
             catch (_l) { }
+            // Hand off to a successor only after every resource is released and the
+            // liveness markers (socket/pid/lock) are already gone — so the fresh
+            // daemon's singleton check sees a clean slate and opens LanceDB/LMDB
+            // without contending with this exiting process.
+            if (opts.relaunch) {
+                const pid = (0, daemon_launcher_1.spawnDaemon)();
+                console.log(`[daemon] Spawned successor daemon${pid ? ` (PID: ${pid})` : " (spawn failed)"}`);
+            }
             console.log("[daemon] Shutdown complete");
         });
     }

package/dist/lib/workers/embeddings/colbert.js

@@ -78,6 +78,11 @@ class ColbertModel {
                 intraOpNumThreads: ONNX_THREADS,
                 interOpNumThreads: 1,
                 graphOptimizationLevel: "all",
+                // ColBERT runs locally on every batch (MLX only covers dense), so its
+                // arena is the worker's main memory hog. Variable-length inputs mean the
+                // arena/mem-pattern never amortize — disable both to keep RSS bounded.
+                enableCpuMemArena: false,
+                enableMemPattern: false,
             };
             log(`Worker: Loading ColBERT ONNX session from ${modelPath}`);
             this.session = yield ort.InferenceSession.create(modelPath, sessionOptions);

package/dist/lib/workers/embeddings/granite.js

@@ -86,6 +86,13 @@ class GraniteModel {
                 intraOpNumThreads: ONNX_THREADS,
                 interOpNumThreads: 1,
                 graphOptimizationLevel: "all",
+                // Embedding inputs are variable-length, so the CPU memory arena and
+                // memory-pattern optimizer don't get reused across batches — they just
+                // retain the largest tensor a worker ever saw (a long/minified file can
+                // pin ~2 GB for the worker's lifetime). Disabling both bounds native
+                // memory at the cost of a small per-inference allocation.
+                enableCpuMemArena: false,
+                enableMemPattern: false,
             };
             this.session = yield ort.InferenceSession.create(modelPath, sessionOptions);
         });
@@ -137,6 +144,10 @@ class GraniteModel {
     runBatch(texts) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
+            // Lazy-load: in the normal path MLX/GPU handles dense embedding and this
+            // ONNX model is never used, so we avoid paying its resident cost in every
+            // worker. load() is idempotent and only runs on the first fallback batch.
+            yield this.load();
             if (!this.session || !this.tokenizer)
                 return [];
             const encoded = yield this.tokenizer(texts, {

package/dist/lib/workers/orchestrator.js

@@ -125,7 +125,10 @@ class WorkerOrchestrator {
     }
     ensureReady() {
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.granite.isReady() && this.colbert.isReady()) {
+            // Granite (dense ONNX) is loaded lazily on first fallback use inside
+            // granite.runBatch — in the normal MLX/GPU path it's never loaded, so we
+            // don't gate readiness on it or pay its resident cost per worker.
+            if (this.colbert.isReady()) {
                 return;
             }
             if (this.initPromise)
@@ -136,7 +139,6 @@ class WorkerOrchestrator {
                 yield Promise.all([
                     this.chunker.init(),
                     this.skeletonizer.init(),
-                    this.granite.load(),
                     this.colbert.load(),
                 ]);
                 stopTimer();

package/dist/lib/workers/pool.js

@@ -82,6 +82,26 @@ const TASK_TIMEOUT_MS = (() => {
         return fromEnv;
     return 120000;
 })();
+// Absolute per-task ceiling. Unlike TASK_TIMEOUT_MS (a no-progress timeout that
+// every heartbeat resets), this is wall-clock from dispatch and is NEVER reset
+// by heartbeats. It bounds a task that keeps emitting progress but never
+// finishes — e.g. a worker wedged on a hung MLX request that still services its
+// heartbeat timer. A single processFile (one file → batches of 16 chunks) is
+// seconds even for huge files, so 5 min is generous headroom, never a real cap.
+const HARD_DEADLINE_MS = (() => {
+    var _a;
+    const fromEnv = Number.parseInt((_a = process.env.GMAX_WORKER_HARD_DEADLINE_MS) !== null && _a !== void 0 ? _a : "", 10);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return fromEnv;
+    return 300000;
+})();
+// Backstop for the leak that motivated all of the above: a worker left
+// busy=true with no live timer to rescue it (a dropped IPC result, or a
+// timeout-kill whose SIGKILL threw and left the process alive but de-listed).
+// The reaper skips busy workers, so without this such a worker is immortal —
+// we saw six survive 4-5 days. Set above HARD_DEADLINE so the per-task timer
+// normally wins and this only fires for the no-timer case.
+const STUCK_BUSY_MS = HARD_DEADLINE_MS + 60000;
 const FORCE_KILL_GRACE_MS = 200;
 // Longer grace for idle reaps: the worker isn't urgently in the way, and a
 // graceful SIGTERM lets ONNX free ~1GB of model memory. But if SIGTERM is
@@ -97,6 +117,11 @@ class ProcessWorker {
         this.busy = false;
         this.pendingTaskId = null;
         this.lastBusyTime = Date.now();
+        // Wall-clock at which this worker became busy with its current task; null
+        // when idle. Used by the reaper to detect workers wedged in busy=true.
+        this.busySince = null;
+        // Most recent RSS (bytes) the worker reported, for memory-based recycling.
+        this.lastRssBytes = 0;
         // Set when the pool has cleaned up after this worker (via exit or error
         // event). Guards against handleWorkerExit running twice when both events
         // fire for the same crash.
@@ -122,6 +147,23 @@ function resolveProcessWorker() {
     throw new Error("Process worker file not found");
 }
 const IDLE_WORKER_TIMEOUT_MS = 60000; // reap idle workers after 60s
+// Idle-worker floor. Kept at 1 (not 2) to favour low resident memory over
+// search warmth: an idle worker holds ~300 MB-1 GB, and on this deployment
+// searches are infrequent, so paying a one-off cold start (~10-15s to boot +
+// load models) on the rare search is preferable to keeping a second worker
+// warm. The pool still scales up to maxWorkers on demand for indexing bursts.
+const MIN_KEEP_WORKERS = 1;
+// Recycle an idle worker whose RSS has grown past this. ONNX native memory
+// (model arenas) lives outside V8, so --max-old-space-size can't bound it — a
+// worker that processed one big file can stay pinned at ~2 GB. Replacing it
+// with a fresh worker reclaims that. 0 (or negative) disables the check.
+const WORKER_RSS_RECYCLE_MB = (() => {
+    var _a;
+    const fromEnv = Number.parseInt((_a = process.env.GMAX_WORKER_RSS_RECYCLE_MB) !== null && _a !== void 0 ? _a : "", 10);
+    if (Number.isFinite(fromEnv))
+        return fromEnv;
+    return 800;
+})();
 // Methods that must skip the indexing backlog. encodeQuery is the search hot
 // path: a single query is ~17ms but waits behind every queued processFile.
 // rerank is similarly small and latency-sensitive.
@@ -147,17 +189,33 @@ class WorkerPool {
         this.maxWorkers = Math.max(1, config_1.CONFIG.WORKER_THREADS);
         // Lazy spawn: start with 1 worker, scale up on demand
         this.spawnWorker();
-        // Periodically reap idle workers back down to 1
-        this.idleReapInterval = setInterval(() => this.reapIdleWorkers(), IDLE_WORKER_TIMEOUT_MS);
+        // Periodically reap idle workers back to MIN_KEEP, and force-kill any
+        // worker wedged in busy=true (the leak backstop — see STUCK_BUSY_MS).
+        this.idleReapInterval = setInterval(() => {
+            this.reapStuckWorkers();
+            this.reapBloatedWorkers();
+            this.reapIdleWorkers();
+        }, IDLE_WORKER_TIMEOUT_MS);
     }
     isHealthy() {
         return !this.destroyed && this.workers.length > 0;
     }
+    /** PIDs of workers the pool currently tracks. Used by the daemon's orphan
+     * sweep to distinguish live, accounted-for workers from de-listed strays. */
+    getWorkerPids() {
+        return this.workers
+            .map((w) => w.child.pid)
+            .filter((pid) => pid !== undefined);
+    }
     clearTaskTimeout(task) {
         if (task.timeout) {
             clearTimeout(task.timeout);
             task.timeout = undefined;
         }
+        if (task.hardTimeout) {
+            clearTimeout(task.hardTimeout);
+            task.hardTimeout = undefined;
+        }
     }
     removeFromQueue(taskId) {
         const pi = this.priorityQueue.indexOf(taskId);
@@ -174,6 +232,7 @@ class WorkerPool {
         if (worker) {
             worker.busy = false;
             worker.pendingTaskId = null;
+            worker.busySince = null;
             worker.lastBusyTime = Date.now();
         }
     }
@@ -222,12 +281,15 @@ class WorkerPool {
         (0, logger_1.log)("pool", `spawn PID:${worker.child.pid} (${this.workers.length + 1}/${Math.max(1, config_1.CONFIG.WORKER_THREADS)})`);
         const onMessage = (msg) => {
             var _a, _b, _c, _d, _e, _f, _g, _h;
+            if (typeof msg.rss === "number")
+                worker.lastRssBytes = msg.rss;
             // Fast cleanup for tasks that were aborted while running
             if (this.abortedTasks.has(msg.id)) {
                 this.abortedTasks.delete(msg.id);
                 const task = this.tasks.get(msg.id);
                 if (task) {
                     this.completeTask(task, worker);
+                    this.recycleIfBloated(worker);
                     this.dispatch();
                 }
                 return;
@@ -236,10 +298,15 @@ class WorkerPool {
             if (!task)
                 return;
             if ("heartbeat" in msg) {
-                // Reset timeout
-                this.clearTaskTimeout(task);
+                // Reset only the no-progress timeout. The hard deadline is left
+                // untouched on purpose — heartbeats must not be able to extend a task
+                // past its absolute ceiling.
+                if (task.timeout) {
+                    clearTimeout(task.timeout);
+                    task.timeout = undefined;
+                }
                 if (task.worker) {
-                    task.timeout = setTimeout(() => this.handleTaskTimeout(task, task.worker), TASK_TIMEOUT_MS);
+                    task.timeout = setTimeout(() => this.handleTaskTimeout(task, task.worker, "no progress"), TASK_TIMEOUT_MS);
                 }
                 return;
             }
@@ -260,6 +327,7 @@ class WorkerPool {
             }
             this.completeTask(task, worker);
             this.consecutiveRespawns = 0;
+            this.recycleIfBloated(worker);
             this.dispatch();
         };
         const onExit = (code, signal) => this.handleWorkerExit(worker, code, signal, "exit");
@@ -341,15 +409,16 @@ class WorkerPool {
             this.dispatch();
         });
     }
-    handleTaskTimeout(task, worker) {
+    handleTaskTimeout(task, worker, reason = "no progress") {
         var _a, _b, _c, _d;
         if (this.destroyed || !this.tasks.has(task.id))
             return;
         this.clearTaskTimeout(task);
+        const limitMs = reason === "hard deadline" ? HARD_DEADLINE_MS : TASK_TIMEOUT_MS;
         const filePath = (_d = (_b = (_a = task.payload) === null || _a === void 0 ? void 0 : _a.path) !== null && _b !== void 0 ? _b : (_c = task.payload) === null || _c === void 0 ? void 0 : _c.absolutePath) !== null && _d !== void 0 ? _d : "unknown";
-        (0, logger_1.log)("pool", `timeout task=${task.id} method=${task.method} file=${filePath} after ${TASK_TIMEOUT_MS}ms — killing worker PID:${worker.child.pid}`);
+        (0, logger_1.log)("pool", `timeout task=${task.id} method=${task.method} file=${filePath} (${reason}, ${limitMs}ms) — killing worker PID:${worker.child.pid}`);
         this.completeTask(task, null);
-        task.reject(new Error(`Worker task ${task.method} timed out after ${TASK_TIMEOUT_MS}ms on ${filePath}`));
+        task.reject(new Error(`Worker task ${task.method} exceeded ${reason} limit (${limitMs}ms) on ${filePath}`));
         worker.cleanedUp = true;
         worker.child.removeAllListeners("message");
         worker.child.removeAllListeners("exit");
@@ -393,9 +462,13 @@ class WorkerPool {
         }
         idle.busy = true;
         idle.pendingTaskId = task.id;
+        idle.busySince = Date.now();
         task.worker = idle;
         task.startTime = Date.now();
-        task.timeout = setTimeout(() => this.handleTaskTimeout(task, idle), TASK_TIMEOUT_MS);
+        task.timeout = setTimeout(() => this.handleTaskTimeout(task, idle, "no progress"), TASK_TIMEOUT_MS);
+        // Absolute deadline: never cleared/re-armed by heartbeats, so a task that
+        // keeps emitting progress but never completes is still bounded.
+        task.hardTimeout = setTimeout(() => this.handleTaskTimeout(task, idle, "hard deadline"), HARD_DEADLINE_MS);
         const filePath = (_e = (_c = (_b = task.payload) === null || _b === void 0 ? void 0 : _b.path) !== null && _c !== void 0 ? _c : (_d = task.payload) === null || _d === void 0 ? void 0 : _d.absolutePath) !== null && _e !== void 0 ? _e : "";
         const busyCount = this.workers.filter((w) => w.busy).length;
         (0, logger_1.debug)("pool", `dispatch task=${task.id} method=${task.method}${filePath ? ` file=${filePath}` : ""} → PID:${idle.child.pid} (busy=${busyCount}/${this.workers.length} queue=${this.taskQueue.length}+${this.priorityQueue.length}p)`);
@@ -425,14 +498,113 @@ class WorkerPool {
         return this.enqueue("rerank", input, signal);
     }
     /**
-     * Reap idle workers back down to MIN_KEEP. Keeps the most recently active.
-     * Called on a timer — never removes busy workers. Min=2 so a search task
-     * always has spare capacity even when one worker is busy with a long
-     * indexing batch (a fresh worker takes 10–15s to boot + load models, which
-     * dwarfs a ~13ms encodeQuery).
+     * Force-kill workers wedged in busy=true past STUCK_BUSY_MS. The per-task
+     * hard deadline normally rescues these first; this catches the case where no
+     * live timer exists — a dropped IPC result, or a prior SIGKILL that threw and
+     * left the process alive but de-listed. Unlike the idle reaper this ignores
+     * MIN_KEEP (a stuck worker is dead weight even at the floor) and goes straight
+     * to SIGKILL, letting the natural 'exit' handler fail the task and respawn.
+     */
+    reapStuckWorkers() {
+        if (this.destroyed)
+            return;
+        const now = Date.now();
+        const stuck = this.workers.filter((w) => w.busy && w.busySince !== null && now - w.busySince > STUCK_BUSY_MS);
+        for (const w of stuck) {
+            const busyMs = w.busySince !== null ? now - w.busySince : 0;
+            (0, logger_1.log)("pool", `stuck worker PID:${w.child.pid} busy ${Math.round(busyMs / 1000)}s (>${STUCK_BUSY_MS}ms) — SIGKILL`);
+            // Leave listeners attached so handleWorkerExit runs on the resulting
+            // 'exit' event: it fails any task still bound to this worker and respawns
+            // if work is pending. Do not pre-set cleanedUp for the same reason.
+            try {
+                w.child.kill("SIGKILL");
+            }
+            catch (_a) { }
+        }
+    }
+    /**
+     * Recycle idle workers whose RSS has grown past WORKER_RSS_RECYCLE_MB. Unlike
+     * the idle reaper this ignores MIN_KEEP — a bloated worker is replaced rather
+     * than merely trimmed: we SIGTERM it (graceful, lets ONNX free its arenas)
+     * and respawn a fresh one if that drops us below MIN_KEEP. Only idle workers
+     * are touched, so an in-flight task is never interrupted.
+     */
+    reapBloatedWorkers() {
+        if (this.destroyed || WORKER_RSS_RECYCLE_MB <= 0)
+            return;
+        const limitBytes = WORKER_RSS_RECYCLE_MB * 1024 * 1024;
+        const bloated = this.workers.filter((w) => !w.busy && w.lastRssBytes > limitBytes);
+        for (const w of bloated)
+            this.recycleWorker(w, "idle");
+    }
+    /**
+     * Recycle a worker whose RSS exceeds the threshold the instant it goes free
+     * between tasks. The idle reaper alone can't catch this: under continuous
+     * churn (a busy monorepo trickling one small file at a time) a worker is
+     * dispatched again within the 60s idle window, so a worker that peaked at
+     * ~1.4 GB on one large file never looks "idle" and stays pinned. Checking at
+     * task completion — when busy was just cleared and before the next dispatch —
+     * bounds RSS regardless of how steady the churn is. No-op while busy, so an
+     * in-flight task is never interrupted.
+     */
+    recycleIfBloated(worker) {
+        if (this.destroyed ||
+            WORKER_RSS_RECYCLE_MB <= 0 ||
+            worker.busy ||
+            worker.cleanedUp) {
+            return;
+        }
+        if (worker.lastRssBytes > WORKER_RSS_RECYCLE_MB * 1024 * 1024) {
+            this.recycleWorker(worker, "post-task");
+        }
+    }
+    /**
+     * SIGTERM a worker (graceful, lets ONNX free its arenas), drop it from the
+     * pool, escalate to SIGKILL if it ignores the signal, and refill back to the
+     * floor with a fresh, lean worker. Shared by the idle and post-task RSS paths.
+     */
+    recycleWorker(w, reason) {
+        if (w.cleanedUp)
+            return;
+        (0, logger_1.log)("pool", `recycle bloated worker PID:${w.child.pid} (${reason}, rss ${Math.round(w.lastRssBytes / 1048576)}MB > ${WORKER_RSS_RECYCLE_MB}MB)`);
+        w.cleanedUp = true;
+        w.child.removeAllListeners("message");
+        w.child.removeAllListeners("exit");
+        w.child.removeAllListeners("error");
+        const pid = w.child.pid;
+        try {
+            w.child.kill("SIGTERM");
+        }
+        catch (_a) { }
+        this.workers = this.workers.filter((x) => x !== w);
+        // Escalate to SIGKILL if SIGTERM is ignored (a worker mid native-call
+        // won't service signals).
+        if (pid !== undefined) {
+            setTimeout(() => {
+                try {
+                    process.kill(pid, 0);
+                    try {
+                        process.kill(pid, "SIGKILL");
+                    }
+                    catch (_a) { }
+                }
+                catch (_b) {
+                    // ESRCH — already gone.
+                }
+            }, REAP_FORCE_KILL_GRACE_MS);
+        }
+        // Replace anything we dropped below the floor with fresh, lean workers.
+        while (!this.destroyed && this.workers.length < MIN_KEEP_WORKERS) {
+            this.spawnWorker();
+        }
+    }
+    /**
+     * Reap idle workers back down to MIN_KEEP_WORKERS. Keeps the most recently
+     * active. Called on a timer — never removes busy workers. See
+     * MIN_KEEP_WORKERS for the memory-vs-warmth tradeoff behind the floor.
      */
     reapIdleWorkers() {
-        const MIN_KEEP = 2;
+        const MIN_KEEP = MIN_KEEP_WORKERS;
         if (this.destroyed || this.workers.length <= MIN_KEEP)
             return;
         const now = Date.now();

package/dist/lib/workers/process-child.js

@@ -49,9 +49,12 @@ const node_process_1 = __importDefault(require("node:process"));
 node_process_1.default.title = "gmax-worker";
 const worker_1 = __importStar(require("./worker"));
 const logger_1 = require("../utils/logger");
+// Every outgoing message also carries `rss` (see send()).
 const send = (msg) => {
     if (node_process_1.default.send) {
-        node_process_1.default.send(msg);
+        // Attach current RSS so the pool can recycle workers whose native (ONNX)
+        // memory has ballooned — the V8 --max-old-space-size cap can't see it.
+        node_process_1.default.send(Object.assign(Object.assign({}, msg), { rss: node_process_1.default.memoryUsage().rss }));
     }
 };
 node_process_1.default.on("message", (msg) => __awaiter(void 0, void 0, void 0, function* () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grepmax",
-  "version": "0.17.4",
+  "version": "0.17.5",
   "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.17.4",
+  "version": "0.17.5",
   "description": "Semantic code search for Claude Code. Automatically indexes your project and provides intelligent search capabilities.",
   "author": {
     "name": "Robert Owens",

package/plugins/grepmax/hooks/start.js

@@ -192,7 +192,7 @@ Understand:
 Survey:
   gmax project                       codebase overview (langs, structure, key symbols)
   gmax skeleton <file>               file structure (file path, NOT a directory)
-  gmax context "topic" --budget 4000 multi-file topic summary
+  gmax context "topic-or-path" --budget 4000 topic summary or deterministic file/dir context
   gmax log <path-or-symbol>          git commits (replaces recent/diff)
   gmax status                        indexed projects
 

package/plugins/grepmax/skills/grepmax/SKILL.md

@@ -186,12 +186,14 @@ gmax dead handleAuth --in src/         # restrict to a sub-path
 ```
 Status is `DEAD` (no callers, not exported), `PUBLIC EXPORT` (no internal callers but the defining chunk is exported — check external usage), or `LIVE` (with caller count + top-3 file:line). The call graph reflects what tree-sitter chunked: dynamic dispatch, reflection, eval, and string-built call sites won't show up — `DEAD` is a hypothesis, not a proof.
 
-### Context — `gmax context <topic> --budget <tokens>`
+### Context — `gmax context <topic-or-path> --budget <tokens>`
 ```
 gmax context "authentication system" --budget 4000
 gmax context "payment flow" --budget 8000
+gmax context src/lib/auth.ts --budget 3000
 gmax context src/lib/auth/ --budget 3000
 ```
+Use the path form when you already know the file or directory; it skips semantic search and gives deterministic structure/excerpt context.
 
 ### Investigate — `gmax investigate "question"` (requires LLM)
 ```
@@ -229,7 +231,7 @@ gmax llm on/off/start/stop/status          # manage local LLM server
 11. **Impact** — `Bash(gmax impact <symbol>)` for blast radius before significant changes
 12. **Similar** — `Bash(gmax similar <symbol>)` to find similar patterns for DRY analysis
 13. **Dead** — `Bash(gmax dead <symbol>)` to check if a symbol has zero inbound callers (hypothesis, not proof)
-14. **Context** — `Bash(gmax context "topic" --budget 4000)` for a token-budgeted topic summary
+14. **Context** — `Bash(gmax context "topic-or-path" --budget 4000)` for token-budgeted topic or path context
 15. **Related** — `Bash(gmax related <file>)` to see what else to look at
 16. **Status** — `Bash(gmax status)` to check index state across all projects