grepmax 0.26.49 → 0.26.51

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

package/README.md

@@ -119,9 +119,11 @@ gmax plugin remove claude      # Remove specific plugin
 
 After upgrading with `npm install -g grepmax@latest`, run `gmax plugin update` (or `gmax plugin update <client>`) to refresh integrations. Package installation does not modify your agent configuration; its postinstall script only prints this reminder.
 
+Starting with v0.26.51, the installer refreshes an existing Claude marketplace from its configured source and updates each existing user/project/local installation in its original scope. It does not remove the marketplace, reset disabled preferences, or reinstall after a refresh failure. New installations use the local npm package. An existing source is retained; moving to another source is a separate migration. Codex instructions follow `CODEX_HOME` (default `~/.codex`), and a matching STDIO registration retains its existing options. A different existing launch configuration is reported for review instead of overwritten. Refresh the plugins after upgrading to activate the hook and installer repairs.
+
 ### How it works per client
 
-- **Claude Code:** Plugin with hooks (SessionStart, SessionEnd, CwdChanged, SubagentStart, PreToolUse). Model uses CLI via `Bash(gmax ... --agent)`.
+- **Claude Code:** Plugin with session/directory hooks, guidance hooks and activity renewal on UserPromptSubmit/PostToolUse for Bash. Model uses CLI via `Bash(gmax ... --agent)`; the plugin does not register an MCP server. Source hooks honor the autostart kill switch, start only after a definite absent socket and never fall back to a separate watcher beside a live daemon.
 - **OpenCode:** Tool shim with dynamic SKILL + session plugin for daemon startup. Model calls gmax tool directly.
 - **Codex:** MCP server registration + AGENTS.md skill instructions.
 - **Factory Droid:** Skills + SessionStart/SessionEnd hooks for daemon lifecycle.
@@ -205,6 +207,8 @@ gmax "query" [options]
 | `--exclude-projects <list>` | With `--all-projects`, skip these projects. | — |
 | `--min-score <n>` | Minimum score relative to this query’s top match, not an absolute confidence threshold. | `0` |
 
+v0.26.50 carries an explicit `--per-file` value into retrieval as well as formatting. Values must be positive safe integers. Omitted requests retain the searcher's configured `GMAX_MAX_PER_FILE` cap or three; larger explicit values still respect `-m` and the existing candidate/rerank bounds. Explicit overrides require a daemon advertising `capabilities.perFileSearch: 1`; older live daemons are refused with an update/restart hint, without opening a fallback reader. An incompatible optional local HTTP fast path is skipped. v0.26.49 and older releases do not support this retrieval override.
+
 ## Experimental Orientation
 
 `gmax surprises --experimental` finds file pairs that are semantically similar but not already connected by the indexed static graph. Use it for architecture orientation, duplicate-logic sweeps, and cross-package drift checks, not as proof that two files are unrelated.
@@ -399,7 +403,7 @@ embedding paths, with and without ColBERT rerank:
 | `small` / 384d | **0.72** | **0.51** |
 | `standard` / 768d | 0.62 | 0.44 |
 
-<sub>Historical gmax-repo comparison: 97 cases, MLX GPU, rerank off. CPU/q4 and rerank-on comparisons showed a similar gap. These figures are not a v0.26.48 benchmark; see the evaluation caveats below.</sub>
+<sub>Historical gmax-repo comparison: 97 cases, MLX GPU, rerank off. CPU/q4 and rerank-on comparisons showed a similar gap. These figures are not a current-release benchmark; see the evaluation caveats below.</sub>
 
 The larger tier performed worse on that fixture and doubles dense-vector width; compute and memory costs depend on the backend.
 Unless you have a measured reason to switch (e.g. a recall complaint on a very
@@ -484,7 +488,7 @@ whether you need to act.
 | `disabling auto-rebuild until an optimize succeeds` | Transient, not a wedge. The next successful optimize clears it. Search stays available. |
 | `ANN: vector index not built` | Normal — exact search is the default. |
 | `cannot reach the daemon socket from this sandbox` (exit 2) | The shell is sandboxed. Add the two keys in [Running under the Claude Code sandbox](#running-under-the-claude-code-sandbox); `gmax doctor` warns about the same gap. |
-| `npm audit` reports advisories on install | v0.26.48 passed production and fresh packed-consumer audits. Audit findings can change: record the installed version and dependency path and report new findings; do not assume historical advisories still apply. |
+| `npm audit` reports advisories on install | v0.26.50 passed production and fresh packed-consumer audits. Audit findings can change: record the installed version and dependency path and report new findings; do not assume historical advisories still apply. |
 
 ## Contributing
 
@@ -504,7 +508,7 @@ GMAX_EVAL_RERANK=1 pnpm bench:oss   # toggle ColBERT rerank
 
 The OSS harness expects indexed express, lodash and platform fixtures at the paths defined in [src/eval-oss.ts](src/eval-oss.ts). The historical comparison in [known limitations](docs/known-limitations.md#colbert-rerank-is-opt-in-shape-sensitive-helps-monolithic-files-hurts-modular-repos) combines these with the internal fixture: four datasets / 131 cases. It is not a current release acceptance run.
 
-Both retrieval harnesses request 20 results for diagnostics, but `mrrAt10` and Recall@10 credit only ranks 1–10. Later matches retain their actual ranks and count as found/hits, with zero reciprocal-rank credit. This cutoff was corrected in source after v0.26.48; historical MRR figures recorded before the correction may include ranks 11–20 and require a new run or rescoring before comparison. Also set `GMAX_CONCENTRATION_THRESHOLD=2` for a true rerank-off comparison: `GMAX_EVAL_RERANK=0` alone does not disable automatic concentration gating. Freeze fixtures and record source, embedding/index identity and ranking configuration before drawing conclusions.
+Both retrieval harnesses request 20 results for diagnostics, but `mrrAt10` and Recall@10 credit only ranks 1–10. Later matches retain their actual ranks and count as found/hits, with zero reciprocal-rank credit. This cutoff correction shipped in v0.26.49; historical MRR figures recorded before the correction may include ranks 11–20 and require a new run or rescoring before comparison. Also set `GMAX_CONCENTRATION_THRESHOLD=2` for a true rerank-off comparison: `GMAX_EVAL_RERANK=0` alone does not disable automatic concentration gating. Freeze fixtures and record source, embedding/index identity and ranking configuration before drawing conclusions.
 
 `pnpm bench:recall` also drives the model-tier comparison behind the 384d default — see [Model Tier](#model-tier) for why the larger 768d model is *not* the default.
 
@@ -521,13 +525,13 @@ pnpm bench:relevance --fixture docs/measurements/relevance/fixture-v1.json \
 
 The fixture schema is in [relevance-baseline.ts](src/lib/eval/relevance-baseline.ts). Its JSON contains `schemaVersion: 1`, `createdAt`, `purpose`, `corpora` and `cases`. Each corpus has an `id`, `root` (absolute or relative to the fixture) and `language`. Each case declares an `id`, `corpus`, `split` (`dev` or `heldout`), `origin` (`curated-source` or `observed-session`), `intent`, `query` and one or more `expected` targets. Targets require an exact relative `file`, definition `symbol`, one-based `startLine`/`endLine` and the SHA-256 of the source file.
 
-A hit requires the exact file and either the definition symbol or overlap with the declared line range. Choose answer-bearing ranges and reviewed alternatives: a declaration-only target can miss a useful function-body chunk. The October 4 baseline intentionally preserves its frozen declaration targets, so its 57.5% Recall@10 / 0.3275 MRR@10 describes target retrieval, not general answer quality. It covers 40 curated cases across TypeScript, JavaScript, Python and Swift; both repetitions produced identical ranks. These are not observed user-session misses or a ranking acceptance gate.
+A hit requires the exact file and either the definition symbol or overlap with the declared line range. The source runner also accepts target `match: "range"` to require range overlap without a symbol shortcut; omitted or `"symbol-or-range"` preserves legacy matching. Range overlap measures useful context discovery, not complete answer coverage. Choose answer-bearing ranges and reviewed alternatives: a declaration-only target can miss a useful function-body chunk. The October 4 baseline intentionally preserves its frozen declaration targets, so its 57.5% Recall@10 / 0.3275 MRR@10 describes target retrieval, not general answer quality. It covers 40 curated cases across TypeScript, JavaScript, Python and Swift; both repetitions produced identical ranks. These are not observed user-session misses or a ranking acceptance gate. Previously inspected cases must be treated as exposed development cases in successor measurements.
 
 The report records source/index hashes, registry embedding identity, daemon snapshots, exclusions, per-case ranks, aggregate metrics and ordinary-session latency. A sibling `.samples.jsonl` checkpoints each completed request; the final JSON applies run-wide exclusions and is authoritative. Changed source/cache hashes, missing targets, unsettled indexes, search warnings and daemon replacement invalidate samples. The runner refuses to overwrite artifacts and exits 2 when any samples are excluded.
 
 Requests use `rerank: false`, but the daemon's concentration gate can still enable reranking. Client environment settings cannot change an existing daemon's settings, and `scoreBreakdown.rerank` also holds the fallback base score when reranking is off.
 
-Source now supports `--diagnostics`. This requires a ready daemon advertising `capabilities.searchDiagnostics: 1`; v0.26.48's installed release does not advertise it. The evaluator refuses incompatible daemons before measuring and excludes responses missing requested diagnostics. Each sample records FTS availability/failure, effective settings and allowlisted daemon ranking environment, concentration-gate evaluation/activation and whether reranking was actually invoked.
+v0.26.49 supports `--diagnostics`. This requires a ready daemon advertising `capabilities.searchDiagnostics: 1`; older daemons without that capability require an update. The evaluator refuses incompatible daemons before measuring and excludes responses missing requested diagnostics. Each sample records FTS availability/failure, effective settings and allowlisted daemon ranking environment, concentration-gate evaluation/activation and whether reranking was actually invoked.
 
 The candidate trace contains pointers and stage ranks for at most the first 200 post-seed fusion candidates, plus full stage counts and an explicit truncation flag. Ranks cover vector/FTS, RRF, seeded fusion, stage-one selection, pooled filtering, selected rerank batch, final scoring, overlap deduplication and final display. Rerank-batch membership does not imply execution; use `gate.rerankInvoked`. Zero at a later stage means a traced candidate was removed; a target missing from a truncated trace may lie outside the reported head. Diagnostics add no database reads and preserve ranking/results. The frozen October 4 artifacts retain their original unknowns. Review ground truth and collect new diagnostic artifacts before tuning.
 

package/dist/commands/claude-code.js

@@ -46,32 +46,36 @@ exports.installClaudeCode = void 0;
 const node_child_process_1 = require("node:child_process");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const node_util_1 = require("node:util");
 const commander_1 = require("commander");
-function runClaudeCommand(args) {
-    return new Promise((resolve, reject) => {
-        const child = (0, node_child_process_1.spawn)("claude", ["plugin", ...args], {
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function runClaudeCommand(args_1) {
+    return __awaiter(this, arguments, void 0, function* (args, options = {}) {
+        const { stdout, stderr } = yield execFileAsync("claude", ["plugin", ...args], {
             env: process.env,
-            stdio: "inherit",
-        });
-        const timeout = setTimeout(() => {
-            child.kill("SIGTERM");
-            reject(new Error("claude command timed out after 60s"));
-        }, 60000);
-        child.on("error", (error) => {
-            clearTimeout(timeout);
-            reject(error);
-        });
-        child.on("exit", (code) => {
-            clearTimeout(timeout);
-            if (code === 0) {
-                resolve();
-            }
-            else {
-                reject(new Error(`claude exited with code ${code !== null && code !== void 0 ? code : "unknown"}`));
-            }
+            encoding: "utf8",
+            timeout: 60000,
+            maxBuffer: 2 * 1024 * 1024,
+            cwd: options.cwd,
         });
+        if (!options.quiet) {
+            process.stdout.write(stdout);
+            process.stderr.write(stderr);
+        }
+        return stdout;
     });
 }
+function parseList(raw, label) {
+    const parsed = JSON.parse(raw);
+    const key = label === "marketplace list" ? "name" : "id";
+    if (!Array.isArray(parsed) ||
+        parsed.some((entry) => !entry ||
+            typeof entry !== "object" ||
+            typeof entry[key] !== "string" ||
+            !entry[key]))
+        throw new Error(`Unexpected Claude ${label} response; configuration preserved`);
+    return parsed;
+}
 /**
  * Resolve the gmax package root directory.
  * Works for both npm global installs (symlinked binary) and dev mode.
@@ -94,19 +98,47 @@ function installPlugin() {
                 return;
             }
             console.log(`Installing plugin from ${marketplacePath}`);
-            // Remove old GitHub-based marketplace if present (ignore errors)
-            try {
-                yield runClaudeCommand(["marketplace", "remove", "grepmax"]);
+            // Query the CLI so account selection and CLAUDE_CONFIG_DIR match the client.
+            // A failed/invalid inventory must never trigger a destructive reinstall.
+            const marketplaces = parseList(yield runClaudeCommand(["marketplace", "list", "--json"], {
+                quiet: true,
+            }), "marketplace list");
+            const installed = parseList(yield runClaudeCommand(["list", "--json"], { quiet: true }), "plugin list").filter((entry) => entry.id === "grepmax@grepmax");
+            const updates = installed.filter((entry) => entry.scope !== "managed");
+            // Validate every target before even refreshing the source.
+            for (const entry of updates) {
+                if (!["user", "project", "local"].includes(String(entry.scope)))
+                    throw new Error("Unknown gmax installation scope; configuration preserved");
+                if (entry.scope !== "user" &&
+                    (typeof entry.projectPath !== "string" ||
+                        !fs.existsSync(entry.projectPath)))
+                    throw new Error("Missing gmax installation project; configuration preserved");
             }
-            catch (_a) {
-                // May not exist — fine
+            if (installed.length > 0 && updates.length === 0) {
+                console.log("gmax is managed by your administrator; installation preserved.");
+                return;
+            }
+            if (marketplaces.some((entry) => entry.name === "grepmax")) {
+                // Retain the user's chosen source, including GitHub or another npm prefix.
+                // Retargeting by removing a marketplace also deletes plugin-owned state.
+                yield runClaudeCommand(["marketplace", "update", "grepmax"]);
+                console.log("✔ Marketplace refreshed (existing source preserved)");
+            }
+            else {
+                yield runClaudeCommand(["marketplace", "add", marketplacePath]);
+                console.log("✔ Marketplace registered (local)");
+            }
+            if (updates.length === 0) {
+                yield runClaudeCommand(["install", "grepmax@grepmax", "--scope", "user"]);
+            }
+            else {
+                for (const entry of updates) {
+                    yield runClaudeCommand(["update", "grepmax@grepmax", "--scope", String(entry.scope)], {
+                        cwd: entry.scope === "user" ? undefined : String(entry.projectPath),
+                    });
+                }
             }
-            // Add local package directory as marketplace source
-            yield runClaudeCommand(["marketplace", "add", marketplacePath]);
-            console.log("✔ Marketplace registered (local)");
-            // Install the plugin from the local marketplace
-            yield runClaudeCommand(["install", "grepmax"]);
-            console.log("✅ Successfully installed the gmax plugin for Claude Code");
+            console.log("✅ Successfully refreshed the gmax plugin for Claude Code");
             console.log("\nNext steps:");
             console.log("1. Restart Claude Code if it's running");
             console.log("2. Run `gmax add` in your project to index it");

package/dist/commands/codex.js

@@ -15,13 +15,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.uninstallCodex = exports.installCodex = void 0;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
-const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_util_1 = require("node:util");
 const commander_1 = require("commander");
+const codex_home_1 = require("../lib/utils/codex-home");
 const shell = process.env.SHELL || (process.platform === "win32" ? "cmd.exe" : "/bin/sh");
 const execAsync = (0, node_util_1.promisify)(node_child_process_1.exec);
-const AGENTS_PATH = node_path_1.default.join(node_os_1.default.homedir(), ".codex", "AGENTS.md");
 const SKILL_START = "<!-- gmax:start -->";
 const SKILL_END = "<!-- gmax:end -->";
 function ownedSkillBlocks() {
@@ -48,6 +47,7 @@ function loadSkill() {
     }
 }
 function writeSkillToAgents(skill) {
+    const AGENTS_PATH = (0, codex_home_1.codexAgentsPath)();
     node_fs_1.default.mkdirSync(node_path_1.default.dirname(AGENTS_PATH), { recursive: true });
     const block = `${SKILL_START}\n${skill.trim()}\n${SKILL_END}`;
     if (!node_fs_1.default.existsSync(AGENTS_PATH)) {
@@ -74,20 +74,37 @@ function writeSkillToAgents(skill) {
 }
 function installPlugin() {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a;
         try {
+            const inventory = yield execAsync("codex mcp list --json", {
+                shell,
+                env: process.env,
+            });
+            const servers = JSON.parse(inventory.stdout);
+            if (!Array.isArray(servers) ||
+                servers.some((server) => !server || typeof server.name !== "string"))
+                throw new Error("Unexpected Codex MCP inventory; configuration preserved");
+            const existing = servers.find((server) => (server === null || server === void 0 ? void 0 : server.name) === "gmax");
+            if (existing &&
+                (((_a = existing.transport) === null || _a === void 0 ? void 0 : _a.type) !== "stdio" ||
+                    node_path_1.default.basename(String(existing.transport.command)) !== "gmax" ||
+                    JSON.stringify(existing.transport.args) !== JSON.stringify(["mcp"])))
+                throw new Error("Existing gmax MCP launch differs; review it before replacing");
             // 1. Register MCP tool. Codex requires the stdio command after `--`:
             //   codex mcp add [OPTIONS] <NAME> -- <COMMAND>...
             // Without the separator the launch command is misparsed. AGENTS.md is only
             // written after this resolves, so a failed registration leaves it untouched.
-            yield execAsync("codex mcp add gmax -- gmax mcp", {
-                shell,
-                env: process.env,
-            });
-            console.log("✅ gmax MCP tool registered with Codex");
+            if (!existing) {
+                yield execAsync("codex mcp add gmax -- gmax mcp", {
+                    shell,
+                    env: process.env,
+                });
+            }
+            console.log("✅ gmax MCP registration ready (existing options preserved)");
             // 2. Write SKILL to AGENTS.md (idempotent)
             const skill = loadSkill();
             writeSkillToAgents(skill);
-            console.log("✅ gmax skill instructions written to", AGENTS_PATH);
+            console.log("✅ gmax skill instructions written to", (0, codex_home_1.codexAgentsPath)());
         }
         catch (error) {
             console.error(`❌ Error installing Codex plugin: ${error}`);
@@ -97,6 +114,7 @@ function installPlugin() {
 }
 function uninstallPlugin() {
     return __awaiter(this, void 0, void 0, function* () {
+        const AGENTS_PATH = (0, codex_home_1.codexAgentsPath)();
         try {
             yield execAsync("codex mcp remove gmax", { shell, env: process.env });
             console.log("✅ gmax MCP tool removed");

package/dist/commands/plugin.js

@@ -49,6 +49,7 @@ const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
+const codex_home_1 = require("../lib/utils/codex-home");
 const exit_1 = require("../lib/utils/exit");
 function commandExists(cmd) {
     try {
@@ -106,7 +107,7 @@ function getClients() {
             id: "codex",
             detect: () => commandExists("codex"),
             isInstalled: () => {
-                const p = path.join(os.homedir(), ".codex", "AGENTS.md");
+                const p = (0, codex_home_1.codexAgentsPath)();
                 try {
                     return (fs.existsSync(p) && fs.readFileSync(p, "utf-8").includes("gmax"));
                 }

package/dist/commands/search-output.js

@@ -48,6 +48,7 @@ const path = __importStar(require("node:path"));
 const agent_search_formatter_1 = require("../lib/output/agent-search-formatter");
 const compact_results_1 = require("../lib/output/compact-results");
 const index_state_footer_1 = require("../lib/output/index-state-footer");
+const per_file_1 = require("../lib/search/per-file");
 const cross_project_1 = require("../lib/utils/cross-project");
 const formatter_1 = require("../lib/utils/formatter");
 const import_extractor_1 = require("../lib/utils/import-extractor");
@@ -69,14 +70,26 @@ const search_skeletons_1 = require("./search-skeletons");
  */
 function executeServerSearch(params) {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b;
         const { server, pattern, exec_path, projectRootForServer, options, minScore, } = params;
+        const maxPerFile = (0, per_file_1.parseCliPerFile)(options.perFile);
         try {
+            if (maxPerFile !== undefined) {
+                const health = yield fetch(`http://127.0.0.1:${server.port}/health`);
+                if (!health.ok)
+                    return false;
+                const info = (yield health.json());
+                if (((_a = info.capabilities) === null || _a === void 0 ? void 0 : _a.perFileSearch) !== 1)
+                    return false;
+            }
             const response = yield fetch(`http://127.0.0.1:${server.port}/search`, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({
                     query: pattern,
                     limit: parseInt(options.m, 10),
+                    maxPerFile,
                     path: exec_path
                         ? path.relative(projectRootForServer, path.resolve(exec_path))
                         : undefined,
@@ -161,7 +174,7 @@ function executeServerSearch(params) {
                         isPlain: true,
                         compact: options.compact,
                         content: options.content,
-                        perFile: parseInt(options.perFile, 10),
+                        perFile: parseInt((_b = options.perFile) !== null && _b !== void 0 ? _b : "3", 10),
                         showScores: options.scores,
                     });
                     console.log(output);
@@ -195,7 +208,7 @@ function executeServerSearch(params) {
 function renderSearchOutput(params) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c;
-        var _d, _e, _f, _g;
+        var _d, _e, _f, _g, _h, _j;
         const { searchResult, options, minScore, crossProject, pattern, effectiveRoot, projectRoot, vectorDb, precomputedSkeletons, precomputedGraph, indexState, } = params;
         if (!options.agent && ((_a = searchResult.warnings) === null || _a === void 0 ? void 0 : _a.length)) {
             for (const w of searchResult.warnings) {
@@ -220,7 +233,7 @@ function renderSearchOutput(params) {
                     return defs.some((d) => regex.test(d));
                 });
             }
-            catch (_h) {
+            catch (_k) {
                 // Invalid regex — skip
             }
         }
@@ -293,7 +306,7 @@ function renderSearchOutput(params) {
                         isPlain: true,
                         compact: options.compact,
                         content: options.content,
-                        perFile: parseInt(options.perFile, 10),
+                        perFile: parseInt((_d = options.perFile) !== null && _d !== void 0 ? _d : "3", 10),
                         showScores: options.scores,
                     });
                 }
@@ -355,7 +368,7 @@ function renderSearchOutput(params) {
                         }
                     }
                 }
-                catch (_j) { }
+                catch (_l) { }
             }
             // Partial-index footer last, so it's the final line the agent reads —
             // and emitted even on "(none)", where an empty result may just mean the
@@ -453,7 +466,7 @@ function renderSearchOutput(params) {
         if (options.imports) {
             const seenFiles = new Set();
             for (const r of filteredData) {
-                const absP = (_e = (_d = r.path) !== null && _d !== void 0 ? _d : (_b = r.metadata) === null || _b === void 0 ? void 0 : _b.path) !== null && _e !== void 0 ? _e : "";
+                const absP = (_f = (_e = r.path) !== null && _e !== void 0 ? _e : (_b = r.metadata) === null || _b === void 0 ? void 0 : _b.path) !== null && _f !== void 0 ? _f : "";
                 if (absP && !seenFiles.has(absP)) {
                     seenFiles.add(absP);
                     const imports = getImportsForFile(absP);
@@ -472,7 +485,7 @@ function renderSearchOutput(params) {
                 isPlain: true,
                 compact: options.compact,
                 content: options.content,
-                perFile: parseInt(options.perFile, 10),
+                perFile: parseInt((_g = options.perFile) !== null && _g !== void 0 ? _g : "3", 10),
                 showScores: options.scores,
             });
             console.log(output);
@@ -480,7 +493,7 @@ function renderSearchOutput(params) {
                 for (const r of filteredData) {
                     const b = r.scoreBreakdown;
                     if (b) {
-                        const absP = (_g = (_f = r.path) !== null && _f !== void 0 ? _f : (_c = r.metadata) === null || _c === void 0 ? void 0 : _c.path) !== null && _g !== void 0 ? _g : "";
+                        const absP = (_j = (_h = r.path) !== null && _h !== void 0 ? _h : (_c = r.metadata) === null || _c === void 0 ? void 0 : _c.path) !== null && _j !== void 0 ? _j : "";
                         const relPath = absP.startsWith(projectRoot)
                             ? absP.slice(projectRoot.length + 1)
                             : absP;
@@ -542,7 +555,7 @@ function renderSearchOutput(params) {
                     console.log(lines.join("\n"));
                 }
             }
-            catch (_k) {
+            catch (_m) {
                 // Trace failed — skip silently
             }
         }

package/dist/commands/search-run.js

@@ -51,6 +51,7 @@ const grammar_loader_1 = require("../lib/index/grammar-loader");
 const index_config_1 = require("../lib/index/index-config");
 const sync_helpers_1 = require("../lib/index/sync-helpers");
 const syncer_1 = require("../lib/index/syncer");
+const per_file_1 = require("../lib/search/per-file");
 const searcher_1 = require("../lib/search/searcher");
 const vector_db_1 = require("../lib/store/vector-db");
 const lock_1 = require("../lib/utils/lock");
@@ -76,6 +77,7 @@ function runSearch(params) {
         var _a, _b;
         var _c;
         const { pattern, options, projectRoot, effectiveRoot, paths, projectStatus, searchFilters, pathFilter, seeds, } = params;
+        const maxPerFile = (0, per_file_1.parseCliPerFile)(options.perFile);
         // Tracks a DB opened by the in-process path so it can be (a) returned to the
         // caller for closing after render, or (b) closed here if indexing throws.
         let openedDb = null;
@@ -96,13 +98,14 @@ function runSearch(params) {
             let indexState;
             if (!options.sync && !options.dryRun) {
                 try {
-                    const { sendDaemonCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
+                    const { sendSearchCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-search")));
                     const crossProject = Array.isArray(searchFilters.projectRoots);
-                    const resp = yield sendDaemonCommand({
+                    const resp = yield sendSearchCommand({
                         cmd: crossProject ? "search-v2" : "search",
                         projectRoot: effectiveRoot,
                         query: pattern,
                         limit: parseInt(options.m, 10),
+                        maxPerFile,
                         filters: Object.keys(searchFilters).length > 0 ? searchFilters : undefined,
                         pathPrefix: pathFilter,
                         rerank: process.env.GMAX_RERANK === "1",
@@ -253,6 +256,7 @@ function runSearch(params) {
                 const searcher = new searcher_1.Searcher(vectorDb);
                 searchResult = yield searcher.search(pattern, parseInt(options.m, 10), {
                     rerank: process.env.GMAX_RERANK === "1",
+                    maxPerFile,
                     explain: options.explain,
                     seeds,
                 }, Object.keys(searchFilters).length > 0

package/dist/commands/search.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.search = void 0;
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
+const per_file_1 = require("../lib/search/per-file");
 const setup_helpers_1 = require("../lib/setup/setup-helpers");
 const cross_project_1 = require("../lib/utils/cross-project");
 const exit_1 = require("../lib/utils/exit");
@@ -61,7 +62,7 @@ exports.search = new commander_1.Command("search")
     .description("Search code by meaning (default command)")
     .option("-m <max_count>, --max-count <max_count>", "The maximum number of results to return (total)", "5")
     .option("-c, --content", "Show full chunk content instead of snippets", false)
-    .option("--per-file <n>", "Number of matches to show per file", "3")
+    .option("--per-file <n>", "Maximum retrieved matches per file (default: configured cap or 3)")
     .option("--scores", "Show relevance scores", false)
     .option("--explain", "Show scoring breakdown per result", false)
     .option("--context-for-llm", "Return full function body + imports per result", false)
@@ -105,6 +106,14 @@ Examples:
     var _a, _b, _c;
     var _d, _e, _f, _g;
     const options = cmd.optsWithGlobals();
+    try {
+        (0, per_file_1.parseCliPerFile)(options.perFile);
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+        return;
+    }
     const root = process.cwd();
     const minScore = Number.isFinite(Number.parseFloat(options.minScore))
         ? Number.parseFloat(options.minScore)

package/dist/commands/serve.js

@@ -64,8 +64,10 @@ const http = __importStar(require("node:http"));
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const per_file_1 = require("../lib/search/per-file");
 const blocked_roots_1 = require("../lib/utils/blocked-roots");
 const daemon_client_1 = require("../lib/utils/daemon-client");
+const daemon_search_1 = require("../lib/utils/daemon-search");
 const exit_1 = require("../lib/utils/exit");
 const log_rotate_1 = require("../lib/utils/log-rotate");
 const path_containment_1 = require("../lib/utils/path-containment");
@@ -194,7 +196,7 @@ function createServeHttpServer(projectRoot, deps) {
         var _b, _c, _d;
         (_a = deps.onActivity) === null || _a === void 0 ? void 0 : _a.call(deps);
         if (req.method === "GET" && req.url === "/health") {
-            writeJson(res, 200, { status: "ok" });
+            writeJson(res, 200, { status: "ok", capabilities: { perFileSearch: 1 } });
             return;
         }
         const ac = new AbortController();
@@ -223,6 +225,13 @@ function createServeHttpServer(projectRoot, deps) {
                 const query = typeof body.query === "string" ? body.query.trim() : "";
                 if (!query)
                     throw new HttpRequestError(400, "invalid_query");
+                let maxPerFile;
+                try {
+                    maxPerFile = (0, per_file_1.validateMaxPerFile)(body.maxPerFile);
+                }
+                catch (_e) {
+                    throw new HttpRequestError(400, "invalid_maxPerFile");
+                }
                 const limit = body.limit === undefined ? 10 : body.limit;
                 if (typeof limit !== "number" ||
                     !Number.isInteger(limit) ||
@@ -262,12 +271,8 @@ function createServeHttpServer(projectRoot, deps) {
                 if (scope.excludePrefixes.length > 0) {
                     filters.excludePrefixes = scope.excludePrefixes;
                 }
-                const response = yield deps.search({
-                    query,
-                    limit,
-                    pathPrefix: scope.pathPrefix,
-                    filters: Object.keys(filters).length ? filters : undefined,
-                }, ac.signal);
+                const response = yield deps.search(Object.assign(Object.assign({ query,
+                    limit }, (maxPerFile === undefined ? {} : { maxPerFile })), { pathPrefix: scope.pathPrefix, filters: Object.keys(filters).length ? filters : undefined }), ac.signal);
                 if (!response.ok) {
                     writeJson(res, daemonErrorStatus(response.error), {
                         error: (_c = response.error) !== null && _c !== void 0 ? _c : "search_failed",
@@ -453,11 +458,12 @@ exports.serve = new commander_1.Command("serve")
             onActivity: () => {
                 lastActivity = Date.now();
             },
-            search: (input, signal) => (0, daemon_client_1.sendDaemonCommand)({
+            search: (input, signal) => (0, daemon_search_1.sendSearchCommand)({
                 cmd: "search",
                 projectRoot,
                 query: input.query,
                 limit: input.limit,
+                maxPerFile: input.maxPerFile,
                 pathPrefix: input.pathPrefix,
                 filters: input.filters,
                 rerank: true,

package/dist/commands/watch.js

@@ -53,6 +53,7 @@ const watcher_1 = require("../lib/index/watcher");
 const index_state_footer_1 = require("../lib/output/index-state-footer");
 const meta_cache_1 = require("../lib/store/meta-cache");
 const vector_db_1 = require("../lib/store/vector-db");
+const autostart_1 = require("../lib/utils/autostart");
 const daemon_restart_1 = require("../lib/utils/daemon-restart");
 const exit_1 = require("../lib/utils/exit");
 const filter_builder_1 = require("../lib/utils/filter-builder");
@@ -92,11 +93,18 @@ exports.watch = new commander_1.Command("watch")
             return;
         }
         if (options.background) {
+            const startOnly = process.env.GMAX_DAEMON_START_ONLY === "1";
+            // Plugin hooks are implicit starts. Recheck quarantine in this child
+            // and never use their launch as a version-upgrade restart.
+            if (startOnly && (0, autostart_1.isAutostartDisabled)())
+                return;
             // Skip spawn if daemon already running at the same version.
             // If version mismatches (e.g. after npm install -g), shut down the old
             // daemon so we can start a fresh one with the new code.
             const { isDaemonRunning, isDaemonHeartbeatFresh, sendDaemonCommand, readDaemonPid, waitForProcessExit, } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
             if (yield isDaemonRunning()) {
+                if (startOnly)
+                    return;
                 const cliVersion = JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), "utf-8")).version;
                 const resp = yield sendDaemonCommand({ cmd: "ping" });
                 if (resp.version && resp.version === cliVersion) {

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

@@ -50,6 +50,7 @@ exports.handleCommand = handleCommand;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const config_1 = require("../../config");
+const per_file_1 = require("../search/per-file");
 const logger_1 = require("../utils/logger");
 const operation_coordinator_1 = require("../utils/operation-coordinator");
 const path_containment_1 = require("../utils/path-containment");
@@ -153,6 +154,7 @@ function handleCommand(daemon, cmd, conn) {
                             exclusiveGenerationRebuild: exports.EXCLUSIVE_GENERATION_REBUILD_PROTOCOL,
                             readVerbs: read_verbs_1.READ_VERBS_PROTOCOL,
                             searchDiagnostics: 1,
+                            perFileSearch: 1,
                             // `watch`/`unwatch` accept holder/pid/ttlMs. A daemon without this
                             // treats `unwatch` as unwatch-for-everyone, so clients releasing a
                             // single lease must check it first.
@@ -232,6 +234,13 @@ function handleCommand(daemon, cmd, conn) {
                     conn.on("close", onClose);
                     try {
                         const limitRaw = typeof cmd.limit === "number" ? cmd.limit : 10;
+                        let maxPerFile;
+                        try {
+                            maxPerFile = (0, per_file_1.validateMaxPerFile)(cmd.maxPerFile);
+                        }
+                        catch (_m) {
+                            return { ok: false, error: "invalid maxPerFile" };
+                        }
                         if (!Number.isInteger(limitRaw) || limitRaw < 1 || limitRaw > 1000) {
                             return { ok: false, error: "invalid limit" };
                         }
@@ -296,6 +305,7 @@ function handleCommand(daemon, cmd, conn) {
                             projectRoot,
                             query,
                             limit: limitRaw,
+                            maxPerFile,
                             filters,
                             pathPrefix,
                             rerank: cmd.rerank === true,

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

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleDaemonSearch = handleDaemonSearch;
 const embedding_generation_1 = require("../index/embedding-generation");
 const index_state_footer_1 = require("../output/index-state-footer");
+const per_file_1 = require("../search/per-file");
 const searcher_1 = require("../search/searcher");
 const retriever_1 = require("../skeleton/retriever");
 const project_registry_1 = require("../utils/project-registry");
@@ -57,6 +58,13 @@ function handleDaemonSearch(deps, payload, signal) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a, _b, _c, _d;
         var _e, _f, _g;
+        let maxPerFile;
+        try {
+            maxPerFile = (0, per_file_1.validateMaxPerFile)(payload.maxPerFile);
+        }
+        catch (_h) {
+            return { ok: false, error: "invalid maxPerFile" };
+        }
         const { vectorDb, workerPool } = deps;
         if (!vectorDb || !workerPool) {
             return { ok: false, error: "daemon not ready" };
@@ -104,6 +112,7 @@ function handleDaemonSearch(deps, payload, signal) {
                 rerank: payload.rerank === true,
                 explain: payload.explain === true,
                 diagnostics: payload.diagnostics === true,
+                maxPerFile,
                 seeds: payload.seeds,
             }, payload.filters, payload.pathPrefix, undefined, signal);
         }
@@ -155,7 +164,7 @@ function handleDaemonSearch(deps, payload, signal) {
                     if (sk)
                         skeletons[p] = sk;
                 }
-                catch (_h) {
+                catch (_j) {
                     // best-effort — drop the entry, keep the search result
                 }
             }
@@ -170,7 +179,7 @@ function handleDaemonSearch(deps, payload, signal) {
                 const builder = new GraphBuilder(vectorDb, root);
                 response.graph = yield builder.buildGraphMultiHop(payload.query, 1);
             }
-            catch (_j) {
+            catch (_k) {
                 // best-effort — drop graph, keep results
             }
         }

package/dist/lib/eval/relevance-baseline.js

@@ -48,6 +48,7 @@ const targetSchema = zod_1.z
     .object({
     file: zod_1.z.string().min(1),
     symbol: zod_1.z.string().min(1),
+    match: zod_1.z.enum(["symbol-or-range", "range"]).optional(),
     startLine: zod_1.z.number().int().positive(),
     endLine: zod_1.z.number().int().positive(),
     sourceSha256: digest,
@@ -117,14 +118,15 @@ function parseFrozenFixture(bytes, expectedSha256) {
     }
     return exports.relevanceFixtureSchema.parse(JSON.parse(bytes.toString("utf8")));
 }
-/** Exact file plus definition symbol OR overlap with a source-grounded line range. */
+/** Exact file plus the frozen matching rule; legacy fixtures allow symbol or range. */
 function matchesTarget(chunk, root, target) {
     var _a, _b, _c, _d;
     if (typeof ((_a = chunk.metadata) === null || _a === void 0 ? void 0 : _a.path) !== "string")
         return false;
     if (path.resolve(chunk.metadata.path) !== path.resolve(root, target.file))
         return false;
-    if ((_b = chunk.defined_symbols) === null || _b === void 0 ? void 0 : _b.includes(target.symbol))
+    if (target.match !== "range" &&
+        ((_b = chunk.defined_symbols) === null || _b === void 0 ? void 0 : _b.includes(target.symbol)))
         return true;
     const start = (_c = chunk.generated_metadata) === null || _c === void 0 ? void 0 : _c.start_line;
     const count = (_d = chunk.generated_metadata) === null || _d === void 0 ? void 0 : _d.num_lines;

package/dist/lib/search/per-file.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMaxPerFile = validateMaxPerFile;
+exports.parseCliPerFile = parseCliPerFile;
+/** Omitted requests retain the daemon's configured default. */
+function validateMaxPerFile(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+        throw new Error("maxPerFile must be a positive safe integer");
+    return value;
+}
+function parseCliPerFile(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value))
+        throw new Error("--per-file must be a positive safe integer");
+    try {
+        return validateMaxPerFile(Number(value));
+    }
+    catch (_a) {
+        throw new Error("--per-file must be a positive safe integer");
+    }
+}

package/dist/lib/search/searcher.js

@@ -21,6 +21,7 @@ const pool_1 = require("../workers/pool");
 const diagnostics_1 = require("./diagnostics");
 const intent_1 = require("./intent");
 const pagerank_1 = require("./pagerank");
+const per_file_1 = require("./per-file");
 const seed_weight_1 = require("./seed-weight");
 // Reads a defined_symbols / referenced_symbols column that may arrive as a plain
 // array or a LanceDB Arrow proxy (.toArray()).
@@ -397,6 +398,7 @@ class Searcher {
     search(query, top_k, _search_options, _filters, pathPrefix, intent, signal) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
+            const requestedMaxPerFile = (0, per_file_1.validateMaxPerFile)(_search_options === null || _search_options === void 0 ? void 0 : _search_options.maxPerFile);
             const finalLimit = top_k !== null && top_k !== void 0 ? top_k : 10;
             // ColBERT rerank is opt-in as of v0.17.1. On the 97-case eval it
             // regresses MRR@10 by ~3% and doubles query latency; sweep across
@@ -742,7 +744,7 @@ class Searcher {
                     : {}));
             }
             const envMaxPerFile = Number.parseInt((_m = process.env.GMAX_MAX_PER_FILE) !== null && _m !== void 0 ? _m : "", 10);
-            const MAX_PER_FILE = Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3;
+            const MAX_PER_FILE = requestedMaxPerFile !== null && requestedMaxPerFile !== void 0 ? requestedMaxPerFile : (Number.isFinite(envMaxPerFile) && envMaxPerFile > 0 ? envMaxPerFile : 3);
             // Rank the entire bounded candidate pool before trimming the result count.
             // A limit-dependent cut here discarded contenders before structure boosts
             // and dedup, so requesting three results could hide the top match returned

package/dist/lib/utils/autostart.js

@@ -49,7 +49,7 @@ const config_1 = require("../../config");
  * Explicit `gmax watch --daemon` is never gated: typing it is the user asking
  * for a daemon in that moment.
  *
- * plugins/grepmax/hooks/start.js carries a plain-JS copy of these semantics
+ * plugins/grepmax/hooks/watch-lease.js carries a plain-JS copy of these semantics
  * (env var checked first, then the file) because a SessionStart hook cannot
  * import from dist. Keep the two in sync.
  */

package/dist/lib/utils/codex-home.js

@@ -0,0 +1,44 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexAgentsPath = codexAgentsPath;
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+function codexAgentsPath() {
+    const home = process.env.CODEX_HOME
+        ? path.resolve(process.env.CODEX_HOME)
+        : path.join(os.homedir(), ".codex");
+    return path.join(home, "AGENTS.md");
+}

package/dist/lib/utils/daemon-search.js

@@ -0,0 +1,34 @@
+"use strict";
+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.sendSearchCommand = sendSearchCommand;
+const per_file_1 = require("../search/per-file");
+const daemon_client_1 = require("./daemon-client");
+/** An old live daemon must not silently ignore a request-scoped override. */
+function sendSearchCommand(command, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const maxPerFile = (0, per_file_1.validateMaxPerFile)(command.maxPerFile);
+        if (maxPerFile !== undefined) {
+            const ping = yield (0, daemon_client_1.sendDaemonCommand)({ cmd: "ping" }, options);
+            if (!ping.ok)
+                return ping;
+            if (((_a = ping.capabilities) === null || _a === void 0 ? void 0 : _a.perFileSearch) !== 1) {
+                return {
+                    ok: false,
+                    error: "unsupported per-file retrieval control",
+                    hint: "run gmax watch restart with the updated CLI",
+                };
+            }
+        }
+        return (0, daemon_client_1.sendDaemonCommand)(command, options);
+    });
+}

package/package.json

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

package/plugins/grepmax/hooks/activity.js

@@ -0,0 +1,12 @@
+const { ensureSessionLease, readHookInput } = require("./watch-lease");
+
+// Bounded renewal on turns and Bash activity keeps long CLI sessions watched.
+// No detached timer, global watcher or additional MCP process is needed.
+async function main() {
+  const input = await readHookInput();
+  await ensureSessionLease(input, input.cwd || process.cwd(), {
+    allowStart: true,
+  });
+}
+
+main();

package/plugins/grepmax/hooks/cwd-changed.js

@@ -1,6 +1,5 @@
-const { execFileSync } = require("node:child_process");
 const {
-  acquireSessionLease,
+  ensureSessionLease,
   readHookInput,
   registeredRootFor,
   releaseSessionLeases,
@@ -20,19 +19,7 @@ async function main() {
     }
   }
 
-  if (!registeredRootFor(newCwd)) return;
-
-  try {
-    execFileSync("gmax", ["watch", "--daemon", "-b"], {
-      timeout: 5000,
-      stdio: "ignore",
-    });
-  } catch {
-    try {
-      execFileSync("gmax", ["watch", "-b"], { timeout: 5000, stdio: "ignore" });
-    } catch {}
-  }
-  await acquireSessionLease(input, newCwd);
+  await ensureSessionLease(input, newCwd, { allowStart: true });
 }
 
 main();

package/plugins/grepmax/hooks/start.js

@@ -2,7 +2,7 @@ const fs = require("node:fs");
 const _path = require("node:path");
 const { execFileSync } = require("node:child_process");
 const {
-  acquireSessionLease,
+  ensureSessionLease,
   readHookInput,
   registeredRootFor,
 } = require("./watch-lease");
@@ -70,43 +70,10 @@ function isProjectRegistered(dir) {
   return registeredRootFor(dir) !== null;
 }
 
-// A kill switch for the auto-start. Create ~/.gmax/autostart-disabled (or export
-// GMAX_NO_AUTOSTART=1) to keep sessions from reviving the daemon — needed when the
-// host is quarantined after a kernel-zone incident and the daemon's write volume is
-// the thing under investigation. Delete the file to restore normal behavior.
-//
-// The CLI honors the same switch via src/lib/utils/autostart.ts (PATHS.autostartDisabledFile).
-// This copy exists because a hook cannot import from dist — keep the two in sync.
-function isAutostartDisabled() {
-  if (process.env.GMAX_NO_AUTOSTART === "1") return true;
-  try {
-    return require("node:fs").existsSync(
-      _path.join(require("node:os").homedir(), ".gmax", "autostart-disabled"),
-    );
-  } catch {
-    return false;
-  }
-}
-
 async function startWatcher(input) {
-  if (isAutostartDisabled()) return;
   const dir = input.cwd || process.cwd();
   if (!isProjectRegistered(dir)) return;
-  try {
-    execFileSync("gmax", ["watch", "--daemon", "-b"], {
-      timeout: 5000,
-      stdio: "ignore",
-    });
-  } catch {
-    // Fallback to per-project mode (older gmax without --daemon)
-    try {
-      execFileSync("gmax", ["watch", "-b"], { timeout: 5000, stdio: "ignore" });
-    } catch {
-      // Watcher may already be running or gmax not in PATH — ignore
-    }
-  }
-  // The daemon only watches projects a session holds a lease on.
-  await acquireSessionLease(input, dir);
+  await ensureSessionLease(input, dir, { allowStart: true });
 }
 
 async function main() {

package/plugins/grepmax/hooks/watch-lease.js

@@ -1,10 +1,9 @@
 // Session watch leases for the hooks.
 //
-// The daemon only watches projects that some session holds a lease on (see
-// src/lib/daemon/watch-leases.ts). The MCP server holds the long-lived one; the
-// hooks take a session lease so a project is watched from the first moment of a
-// session, and drop it at SessionEnd. A hook cannot import from dist, so this
-// speaks the daemon's one-line JSON protocol directly.
+// Claude's CLI integration takes a lease at startup, renews it during activity,
+// and releases it at SessionEnd. Other MCP clients own separate leases. A hook
+// cannot import from dist, so this speaks the one-line Unix socket protocol.
+const { spawn } = require("node:child_process");
 const fs = require("node:fs");
 const net = require("node:net");
 const os = require("node:os");
@@ -13,10 +12,18 @@ const path = require("node:path");
 const GMAX_DIR = path.join(os.homedir(), ".gmax");
 const SOCKET = path.join(GMAX_DIR, "daemon.sock");
 
-// Long enough to cover a session without an MCP server; SessionEnd releases it
-// early, and the daemon caps any lease at 12h.
+// Activity refreshes this TTL; idle sessions do not watch forever.
 const SESSION_LEASE_TTL_MS = 4 * 60 * 60 * 1000;
 
+function isAutostartDisabled() {
+  if (process.env.GMAX_NO_AUTOSTART === "1") return true;
+  try {
+    return fs.existsSync(path.join(GMAX_DIR, "autostart-disabled"));
+  } catch {
+    return false;
+  }
+}
+
 function readHookInput(timeoutMs = 1000) {
   return new Promise((resolve) => {
     let data = "";
@@ -102,6 +109,7 @@ function sendOnce(cmd, timeoutMs) {
     socket.on("error", (err) =>
       finish({
         ok: false,
+        absent: err.code === "ENOENT" || err.code === "ECONNREFUSED",
         retry: err.code === "ENOENT" || err.code === "ECONNREFUSED",
       }),
     );
@@ -143,6 +151,42 @@ async function acquireSessionLease(input, dir) {
   return resp !== null;
 }
 
+/** Reuse a lease-capable daemon; start one only after a definite absent socket. */
+async function ensureSessionLease(input, dir, { allowStart = false } = {}) {
+  if (isAutostartDisabled() || !sessionHolder(input) || !registeredRootFor(dir))
+    return false;
+  const ping = await sendOnce({ cmd: "ping" }, 500);
+  if (ping.ok) {
+    if (!ping.resp.capabilities?.watchLeases) return false;
+    return acquireSessionLease(input, dir);
+  }
+  // Busy, initializing, denied and timed-out sockets belong to an existing
+  // daemon. Never start a per-project writer or replace that process here.
+  if (!allowStart || !ping.absent) return false;
+  try {
+    const child = spawn("gmax", ["watch", "--daemon", "-b"], {
+      detached: true,
+      stdio: "ignore",
+      cwd: dir,
+      // Another session can win the race after the absent-socket probe. The
+      // launcher must reuse that peer, even if its package version differs.
+      env: { ...process.env, GMAX_DAEMON_START_ONLY: "1" },
+    });
+    await new Promise((resolve, reject) => {
+      child.once("spawn", resolve);
+      child.once("error", reject);
+    });
+    child.unref();
+  } catch {
+    return false;
+  }
+  // A cold daemon may take longer than a hook's budget to become ready. Later
+  // activity retries ownership instead of opening another watcher.
+  const ready = await sendDaemonLine({ cmd: "ping" }, 1500);
+  if (!ready?.capabilities?.watchLeases) return false;
+  return acquireSessionLease(input, dir);
+}
+
 async function releaseSessionLeases(input, dir) {
   const holder = sessionHolder(input);
   const root = registeredRootFor(dir);
@@ -157,6 +201,8 @@ async function releaseSessionLeases(input, dir) {
 
 module.exports = {
   acquireSessionLease,
+  ensureSessionLease,
+  isAutostartDisabled,
   readHookInput,
   registeredRootFor,
   releaseSessionLeases,

package/plugins/grepmax/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/start.js",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/start.js\"",
             "timeout": 10
           }
         ]
@@ -16,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/stop.js",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/stop.js\"",
             "timeout": 10
           }
         ]
@@ -27,8 +27,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/cwd-changed.js",
-            "timeout": 5
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/cwd-changed.js\"",
+            "timeout": 10
           }
         ]
       }
@@ -38,7 +38,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.js",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.js\"",
             "timeout": 3
           }
         ]
@@ -50,11 +50,34 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pre-grep.js",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-grep.js\"",
             "timeout": 2
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/activity.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/activity.js\"",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }