grepmax 0.26.27 → 0.26.28

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

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Daemon-side handlers for the `vector.*` read verbs — the two commands whose
+ * store work is a vector scan rather than a row select.
+ *
+ * Both ship the *analysed* answer, never the vectors:
+ *
+ * - `vector.similar` runs the source-chunk lookup, `configureAnnVectorQuery`,
+ *   `table.vectorSearch`, and the self/threshold filter, and returns the ranked
+ *   chunks. The 384-float source vector never crosses the socket.
+ * - `vector.surprises` runs `analyzeSurprisingConnections` and returns the
+ *   summary plus the findings the caller will actually print. The raw `pairs`
+ *   array is dropped: nothing renders it, and it is the largest field by far.
+ *
+ * As in rows-handler.ts, each `run*` function is the single implementation both
+ * the verb and the command's in-process fallback call, so the two paths cannot
+ * produce different output.
+ */
+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.runSimilar = runSimilar;
+exports.handleVectorSimilar = handleVectorSimilar;
+exports.runSurprises = runSurprises;
+exports.handleVectorSurprises = handleVectorSurprises;
+exports.registerVectorVerbs = registerVectorVerbs;
+const surprising_connections_1 = require("../analysis/surprising-connections");
+const ann_config_1 = require("../store/ann-config");
+const arrow_1 = require("../utils/arrow");
+const filter_builder_1 = require("../utils/filter-builder");
+const path_containment_1 = require("../utils/path-containment");
+const scope_filter_1 = require("../utils/scope-filter");
+const read_verbs_1 = require("./read-verbs");
+const rows_handler_1 = require("./rows-handler");
+function runSimilar(deps, req) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (!deps.vectorDb)
+            throw new rows_handler_1.ReadVerbError("daemon not ready");
+        (_a = deps.touchActivity) === null || _a === void 0 ? void 0 : _a.call(deps);
+        const table = yield deps.vectorDb.ensureTable();
+        const sourceSelect = ["vector", "path", "defined_symbols", "start_line"];
+        const sourceRows = yield table
+            .query()
+            .select(sourceSelect)
+            .where(req.absPath !== undefined
+            ? `path = '${(0, filter_builder_1.escapeSqlString)(req.absPath)}'`
+            : `array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)((_b = req.symbol) !== null && _b !== void 0 ? _b : "")}') AND ${(0, filter_builder_1.pathStartsWith)(`${req.projectRoot}/`)}`)
+            .limit(1)
+            .toArray();
+        if (sourceRows.length === 0)
+            return { status: "not-found" };
+        const source = sourceRows[0];
+        const sourceVector = source.vector;
+        const sourcePath = String(source.path || "");
+        if (!sourceVector || sourceVector.length === 0)
+            return { status: "no-vector" };
+        const pathScope = (0, scope_filter_1.buildScopeWhere)(req.scope);
+        const results = yield (0, ann_config_1.configureAnnVectorQuery)(table.vectorSearch(sourceVector))
+            .select([
+            "path",
+            "start_line",
+            "end_line",
+            "defined_symbols",
+            "role",
+            "content",
+            "_distance",
+        ])
+            .where(pathScope)
+            .limit(req.limit + 5) // fetch extra to account for self-filtering
+            .toArray();
+        // Filter out self and apply threshold
+        const filtered = results.filter((raw) => {
+            const r = raw;
+            if (r.path === sourcePath && r.start_line === source.start_line)
+                return false;
+            if (req.threshold > 0) {
+                // LanceDB returns L2 distance; convert to similarity
+                const sim = 1 / (1 + (Number(r._distance) || 0));
+                if (sim < req.threshold)
+                    return false;
+            }
+            return true;
+        });
+        // `content` is selected (keeping the query identical) but never rendered, so
+        // it is dropped here rather than shipped.
+        return {
+            status: "ok",
+            results: filtered.map((raw) => {
+                var _a, _b, _c, _d, _e;
+                const r = raw;
+                return {
+                    path: String((_a = r.path) !== null && _a !== void 0 ? _a : ""),
+                    start_line: Number((_b = r.start_line) !== null && _b !== void 0 ? _b : 0),
+                    end_line: Number((_c = r.end_line) !== null && _c !== void 0 ? _c : 0),
+                    defined_symbols: (0, arrow_1.toArr)(r.defined_symbols),
+                    role: String((_d = r.role) !== null && _d !== void 0 ? _d : ""),
+                    _distance: Number((_e = r._distance) !== null && _e !== void 0 ? _e : 0),
+                };
+            }),
+        };
+    });
+}
+function handleVectorSimilar(deps, payload) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return (0, rows_handler_1.asReadVerbResponse)(() => __awaiter(this, void 0, void 0, function* () {
+            const projectRoot = (0, rows_handler_1.assertReadableProject)(payload.projectRoot);
+            const scope = (0, rows_handler_1.resolveWireScope)(projectRoot, payload.scope);
+            const absPath = typeof payload.absPath === "string" && payload.absPath
+                ? (0, path_containment_1.resolveContainedPath)(projectRoot, payload.absPath)
+                : undefined;
+            const symbol = typeof payload.symbol === "string" && payload.symbol
+                ? payload.symbol
+                : undefined;
+            if (!absPath && !symbol)
+                throw new rows_handler_1.ReadVerbError("missing target");
+            const result = yield runSimilar(deps, {
+                projectRoot,
+                absPath,
+                symbol,
+                scope,
+                limit: (0, rows_handler_1.clampInt)(payload.limit, 5, 1, 25),
+                threshold: typeof payload.threshold === "number" &&
+                    Number.isFinite(payload.threshold)
+                    ? payload.threshold
+                    : 0,
+            });
+            return Object.assign({ ok: true }, result);
+        }));
+    });
+}
+function runSurprises(deps, req) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        if (!deps.vectorDb)
+            throw new rows_handler_1.ReadVerbError("daemon not ready");
+        (_a = deps.touchActivity) === null || _a === void 0 ? void 0 : _a.call(deps);
+        const table = yield deps.vectorDb.ensureTable();
+        const result = yield (0, surprising_connections_1.analyzeSurprisingConnections)(table, req.projectRoot, req.options);
+        // Both formatters use only `summary` and `findings.slice(0, top)`, plus
+        // `findings.length === 0`. Trimming to `top` here preserves both and keeps
+        // `pairs` (the bulk of the object) off the wire entirely.
+        return {
+            summary: result.summary,
+            findings: result.findings.slice(0, req.top),
+        };
+    });
+}
+function handleVectorSurprises(deps, payload) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return (0, rows_handler_1.asReadVerbResponse)(() => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const projectRoot = (0, rows_handler_1.assertReadableProject)(payload.projectRoot);
+            const raw = ((_a = payload.options) !== null && _a !== void 0 ? _a : {});
+            const toPrefixList = (value) => {
+                if (!Array.isArray(value) || value.length === 0)
+                    return undefined;
+                // Validated here rather than trusted: these reach resolveScope, which
+                // builds the WHERE clause the scan runs under.
+                return value.map((v) => (0, path_containment_1.resolveContainedPath)(projectRoot, String(v)));
+            };
+            const result = yield runSurprises(deps, {
+                projectRoot,
+                options: {
+                    sample: (0, rows_handler_1.clampInt)(raw.sample, surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.sample, 1, 10000),
+                    neighbors: (0, rows_handler_1.clampInt)(raw.neighbors, surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.neighbors, 1, 200),
+                    dirDepth: (0, rows_handler_1.clampInt)(raw.dirDepth, surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.dirDepth, 1, 20),
+                    minSimilarity: typeof raw.minSimilarity === "number" &&
+                        Number.isFinite(raw.minSimilarity) &&
+                        raw.minSimilarity >= 0
+                        ? raw.minSimilarity
+                        : surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.minSimilarity,
+                    maxRows: (0, rows_handler_1.clampInt)(raw.maxRows, surprising_connections_1.DEFAULT_SURPRISE_OPTIONS.maxRows, 1, surprising_connections_1.MAX_SURPRISE_ROWS),
+                    includeTests: Boolean(raw.includeTests),
+                    includeEval: Boolean(raw.includeEval),
+                    in: toPrefixList(raw.in),
+                    exclude: toPrefixList(raw.exclude),
+                },
+                top: (0, rows_handler_1.clampInt)(payload.top, 20, 1, 100),
+            });
+            return Object.assign({ ok: true }, result);
+        }));
+    });
+}
+// --- Registration -----------------------------------------------------------
+/** Called from `Daemon.start()`; see registerRowsVerbs for why not at import. */
+function registerVectorVerbs() {
+    (0, read_verbs_1.registerReadVerbs)({
+        "vector.similar": (payload, ctx) => handleVectorSimilar(ctx.daemon.storeReadDeps(), payload),
+        "vector.surprises": (payload, ctx) => handleVectorSurprises(ctx.daemon.storeReadDeps(), payload),
+    });
+}

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

@@ -273,6 +273,11 @@ function isDaemonDraining(pid) {
  * This is the implicit spawn path, so it honors the autostart kill switch: with
  * it on, an already-running daemon is still used, but a dead one is not
  * revived and callers fall back to in-process work.
+ *
+ * It also refuses to spawn from a sandboxed shell. A daemon inherits its
+ * parent's sandbox for its whole life, so one spawned where `~/.gmax` is
+ * read-only fails its own lock mkdir, dies, and leaves a confusing crash in
+ * daemon.log while this function burns the full readiness timeout.
  */
 function ensureDaemonRunning() {
     return __awaiter(this, void 0, void 0, function* () {
@@ -282,6 +287,12 @@ function ensureDaemonRunning() {
             const { isAutostartDisabled } = yield Promise.resolve().then(() => __importStar(require("./autostart")));
             if (isAutostartDisabled())
                 return false;
+            const { storeWriteDeniedNotice, warnStoreWriteDeniedOnce } = yield Promise.resolve().then(() => __importStar(require("./store-access")));
+            const denied = storeWriteDeniedNotice();
+            if (denied) {
+                warnStoreWriteDeniedOnce(denied);
+                return false;
+            }
             const { spawnDaemon } = yield Promise.resolve().then(() => __importStar(require("./daemon-launcher")));
             const pid = yield spawnDaemon();
             if (!pid)

package/dist/lib/utils/store-access.js

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * Client-side access policy for store reads.
+ *
+ * Every read-only gmax command has three ways to get an answer, and exactly one
+ * of them is correct in any given situation:
+ *
+ *   1. Ask the daemon over `~/.gmax/daemon.sock`. Preferred whenever a daemon
+ *      is up: the daemon is the only process that should hold the store open.
+ *   2. Open the store in-process. Legitimate only when *no daemon exists*
+ *      (autostart disabled, tests, CI). Opening the store takes a `StoreLease`,
+ *      which mkdirs under `~/.gmax` — so a "read" is a writer as far as the
+ *      filesystem is concerned.
+ *   3. Refuse. When the process is sandboxed, both of the above fail with an
+ *      errno that says nothing useful. One actionable line beats a stack trace.
+ *
+ * `withStoreRead` encodes that decision. The fallback set is deliberately tiny:
+ * `ENOENT`/`ECONNREFUSED` mean there is no daemon listening, and nothing else
+ * does. A *live* daemon error (DAEMON_BUSY, timeout, a scope rejection, a store
+ * failure) must never send the caller into the store concurrently.
+ *
+ * Sandbox handling: Claude Code's Bash sandbox denies writes under `~/.gmax`
+ * and blocks Unix sockets. The socket connect then fails `EPERM`, and the lease
+ * mkdir fails `EPERM`/`EACCES`. Both are turned into a refusal carrying the one
+ * settings key that fixes it, exit code 2, and no stack.
+ *
+ * Env switches:
+ *   GMAX_NO_DAEMON=1  Skip the daemon attempt entirely and run the in-process
+ *                     path. Intended for byte-identical output comparisons
+ *                     between the two paths; it does not relax the sandbox
+ *                     refusal, so a sandboxed shell still gets the lease hint.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StoreAccessRefused = exports.LEASE_DENIED_MESSAGE = exports.SOCKET_DENIED_MESSAGE = void 0;
+exports.socketDeniedMessage = socketDeniedMessage;
+exports.leaseDeniedMessage = leaseDeniedMessage;
+exports.isStoreAccessRefused = isStoreAccessRefused;
+exports.refuseStoreAccess = refuseStoreAccess;
+exports.reportStoreAccessRefusal = reportStoreAccessRefusal;
+exports.classifyDaemonError = classifyDaemonError;
+exports.shouldFallbackFromDaemonError = shouldFallbackFromDaemonError;
+exports.isUnknownCommandError = isUnknownCommandError;
+exports.isOversizeError = isOversizeError;
+exports.classifyLeaseError = classifyLeaseError;
+exports.asStoreAccessError = asStoreAccessError;
+exports.isDaemonBypassed = isDaemonBypassed;
+exports.withStoreRead = withStoreRead;
+exports.probeStoreWritable = probeStoreWritable;
+exports.storeWriteDeniedNotice = storeWriteDeniedNotice;
+exports.warnStoreWriteDeniedOnce = warnStoreWriteDeniedOnce;
+exports.resetStoreWriteDeniedNotice = resetStoreWriteDeniedNotice;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("../../config");
+/**
+ * Socket-level errors that prove no daemon is listening. These — and only these
+ * — permit the in-process path.
+ */
+const NO_DAEMON_ERRORS = new Set(["ENOENT", "ECONNREFUSED"]);
+/** Errnos that mean the sandbox denied the operation, not that it failed. */
+const SANDBOX_ERRNOS = new Set(["EPERM", "EACCES", "EROFS"]);
+exports.SOCKET_DENIED_MESSAGE = 'gmax: cannot reach the daemon socket from this sandbox. Add to Claude Code settings: "sandbox": {"network": {"allowUnixSockets": ["~/.gmax/daemon.sock"]}}';
+exports.LEASE_DENIED_MESSAGE = 'gmax: cannot open the store from this sandbox. Add to Claude Code settings: "sandbox": {"filesystem": {"allowWrite": ["~/.gmax"]}}';
+/** The one line to print when the daemon socket is unreachable from a sandbox. */
+function socketDeniedMessage() {
+    return exports.SOCKET_DENIED_MESSAGE;
+}
+/** The one line to print when the store lease cannot be taken from a sandbox. */
+function leaseDeniedMessage() {
+    return exports.LEASE_DENIED_MESSAGE;
+}
+/**
+ * Refusal to reach the store at all. Carries the actionable line as its
+ * message; commands print it verbatim (one line, no stack) and exit 2.
+ */
+class StoreAccessRefused extends Error {
+    constructor(kind) {
+        super(kind === "socket" ? exports.SOCKET_DENIED_MESSAGE : exports.LEASE_DENIED_MESSAGE);
+        this.exitCode = 2;
+        this.name = "StoreAccessRefused";
+        this.kind = kind;
+    }
+}
+exports.StoreAccessRefused = StoreAccessRefused;
+function isStoreAccessRefused(err) {
+    return err instanceof StoreAccessRefused;
+}
+/**
+ * Build the refusal and mark the process failed. Exit code 2 distinguishes
+ * "refused, configure your sandbox" from an ordinary command failure (1).
+ */
+function refuseStoreAccess(kind) {
+    process.exitCode = 2;
+    return new StoreAccessRefused(kind);
+}
+/**
+ * Print a refusal as a single line and set the exit code. Returns false when
+ * `err` is something else, so callers can chain it into an existing catch:
+ *
+ *   catch (err) { if (reportStoreAccessRefusal(err)) return; ...existing... }
+ */
+function reportStoreAccessRefusal(err) {
+    if (!isStoreAccessRefused(err))
+        return false;
+    console.error(err.message);
+    process.exitCode = 2;
+    return true;
+}
+/** Pull an errno-ish string out of whatever the socket layer handed back. */
+function errorCode(error) {
+    if (typeof error === "string")
+        return error;
+    if (error && typeof error === "object") {
+        const code = error.code;
+        if (typeof code === "string")
+            return code;
+        const message = error.message;
+        if (typeof message === "string")
+            return message;
+    }
+    return undefined;
+}
+/**
+ * Classify a daemon-side failure. `error` is either the `error` field of a
+ * DaemonResponse (sendDaemonCommand reports `err.code ?? err.message`) or a
+ * thrown ErrnoException.
+ *
+ * - "ok"           no error present
+ * - "no-daemon"    nothing is listening; the in-process path is allowed
+ * - "sandboxed"    the sandbox blocked the socket; refuse with the socket hint
+ * - "daemon-error" a live daemon said no; report it, never fall back
+ */
+function classifyDaemonError(error) {
+    if (error === undefined || error === null || error === "")
+        return "ok";
+    const code = errorCode(error);
+    if (!code)
+        return "daemon-error";
+    if (NO_DAEMON_ERRORS.has(code))
+        return "no-daemon";
+    if (SANDBOX_ERRNOS.has(code))
+        return "sandboxed";
+    return "daemon-error";
+}
+/**
+ * True only for the two socket errors that prove no daemon exists.
+ *
+ * Kept as a named predicate because it is the exact rule `search-run.ts` has
+ * always applied (and re-exports); `unknown command` is deliberately NOT in the
+ * set — see `isUnknownCommandError` for the version-skew allowance.
+ */
+function shouldFallbackFromDaemonError(error) {
+    return classifyDaemonError(error) === "no-daemon";
+}
+/**
+ * A daemon older than this CLI does not know a newly added verb. Treat that as
+ * "no daemon" for one release so an unrestarted daemon does not break the
+ * command, then remove the allowance. Mirrors the `search-v2` transition rule.
+ */
+function isUnknownCommandError(error) {
+    return typeof error === "string" && error.startsWith("unknown command");
+}
+/**
+ * The daemon caps a single response line at 2 MB and answers `oversize` rather
+ * than writing a frame no client can parse. It is a *protocol* limit, not a
+ * store failure — the daemon is healthy and the store is fine.
+ *
+ * That is why it is opt-in (`fallbackOnOversize`) and off by default:
+ *
+ *   - **MCP opts in.** An MCP tool has no user at a terminal to re-run a
+ *     narrower query, and its whole session is one long-lived process; degrading
+ *     to its own store read returns an answer instead of an error string.
+ *   - **A CLI refuses.** The caller is a short-lived process at a prompt who can
+ *     narrow the query, and falling back would put a *second opener* on the
+ *     store while the daemon is busy enough to have produced a 2 MB answer —
+ *     exactly the concurrency this routing exists to prevent. One clear error
+ *     beats a second lease.
+ *
+ * No graph verb ships a capped response today (the largest measured is 963 KiB,
+ * `trace VectorDB -d 3`), so nothing trips this yet; the option exists so MCP's
+ * long-standing search behaviour survives the switch-over unchanged.
+ */
+function isOversizeError(error) {
+    return typeof error === "string" && error.toLowerCase().includes("oversize");
+}
+/**
+ * Classify a failure from opening the store in-process (the `StoreLease` mkdir,
+ * an LMDB `env.open`, a LanceDB write). Sandbox denials become a refusal that
+ * names the filesystem settings key; everything else is a real error.
+ */
+function classifyLeaseError(err) {
+    const code = err === null || err === void 0 ? void 0 : err.code;
+    if (typeof code === "string" && SANDBOX_ERRNOS.has(code))
+        return "sandboxed";
+    const message = err instanceof Error ? err.message : "";
+    // Node fs errors stringify as "EPERM: operation not permitted, mkdir '...'".
+    // LMDB reports the same denial as "Operation not permitted: ...".
+    if (/^(EPERM|EACCES|EROFS):/.test(message))
+        return "sandboxed";
+    if (/^Operation not permitted\b/.test(message))
+        return "sandboxed";
+    return "other";
+}
+/**
+ * Convert a lease/store-open failure into a refusal when the sandbox caused it,
+ * otherwise hand the original error back unchanged.
+ */
+function asStoreAccessError(err) {
+    if (isStoreAccessRefused(err))
+        return err;
+    return classifyLeaseError(err) === "sandboxed"
+        ? refuseStoreAccess("lease")
+        : err;
+}
+function defaultDaemonErrorMessage(name, resp) {
+    const detail = typeof resp.hint === "string"
+        ? `: ${resp.hint}`
+        : typeof resp.error === "string"
+            ? `: ${resp.error}`
+            : "";
+    return `Daemon ${name} failed${detail}`;
+}
+/** True when the caller asked for the in-process path explicitly. */
+function isDaemonBypassed() {
+    return process.env.GMAX_NO_DAEMON === "1";
+}
+/**
+ * Run one store read through the access policy. See the file header for the
+ * decision table; `name` names the operation in daemon-error messages.
+ */
+function withStoreRead(name, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const runInProcess = () => __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield opts.inProcess();
+            }
+            catch (err) {
+                throw asStoreAccessError(err);
+            }
+        });
+        if (opts.skipDaemon || isDaemonBypassed())
+            return runInProcess();
+        let resp;
+        try {
+            resp = yield opts.daemon();
+        }
+        catch (err) {
+            if (isStoreAccessRefused(err))
+                throw err;
+            const cls = classifyDaemonError(err === null || err === void 0 ? void 0 : err.code);
+            if (cls === "sandboxed")
+                throw refuseStoreAccess("socket");
+            if (cls !== "no-daemon")
+                throw err;
+            return runInProcess();
+        }
+        if (resp.ok) {
+            return opts.render ? yield opts.render(resp) : resp;
+        }
+        const cls = classifyDaemonError(resp.error);
+        if (cls === "sandboxed")
+            throw refuseStoreAccess("socket");
+        if (cls === "no-daemon" ||
+            (opts.fallbackOnUnknownVerb && isUnknownCommandError(resp.error)) ||
+            (opts.fallbackOnOversize && isOversizeError(resp.error)) ||
+            ((_a = opts.extraFallback) === null || _a === void 0 ? void 0 : _a.call(opts, resp.error)) === true) {
+            if (process.env.GMAX_DEBUG === "1") {
+                console.error(`[${name}] daemon path unavailable: ${resp.error}`);
+            }
+            return runInProcess();
+        }
+        throw new Error(((_b = opts.daemonErrorMessage) !== null && _b !== void 0 ? _b : ((r) => defaultDaemonErrorMessage(name, r)))(resp));
+    });
+}
+// --- Spawn guard -----------------------------------------------------------
+/**
+ * Probe whether this process could write under `~/.gmax` at all.
+ *
+ * A daemon spawned from a sandboxed shell inherits the sandbox for its whole
+ * life: it fails its own lock mkdir, dies, and leaves a confusing crash in
+ * daemon.log while the caller waits out the 30s readiness poll. Cheaper to ask
+ * first. mkdir+rmdir of a PID-named probe dir is the smallest operation that
+ * exercises the same permission the lease needs.
+ *
+ * "unknown" (e.g. ENOSPC, a weird EIO) is deliberately not "sandboxed": only a
+ * denial should suppress a spawn.
+ */
+function probeStoreWritable(dir = config_1.PATHS.globalRoot) {
+    // Only a denial may suppress a spawn, so an unusable path (a test harness
+    // with a partial PATHS, say) reports "unknown" rather than guessing.
+    if (typeof dir !== "string" || dir === "")
+        return "unknown";
+    const probe = path.join(dir, `.spawn-probe-${process.pid}`);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        try {
+            fs.mkdirSync(probe);
+        }
+        catch (err) {
+            // A same-PID leftover from a crashed probe still proves writability.
+            if ((err === null || err === void 0 ? void 0 : err.code) !== "EEXIST")
+                throw err;
+        }
+        try {
+            fs.rmdirSync(probe);
+        }
+        catch (_a) { }
+        return "writable";
+    }
+    catch (err) {
+        return classifyLeaseError(err) === "sandboxed" ? "sandboxed" : "unknown";
+    }
+}
+/**
+ * One-line notice for a spawn suppressed because the sandbox denies writes to
+ * `~/.gmax`, or null when a spawn is fine. Same shape as
+ * `autostartDisabledNotice()` in autostart.ts: the caller decides whether to
+ * print, and the text names the exact fix.
+ */
+function storeWriteDeniedNotice(dir) {
+    return probeStoreWritable(dir) === "sandboxed" ? exports.LEASE_DENIED_MESSAGE : null;
+}
+let sandboxNoticePrinted = false;
+/**
+ * Print the lease-denied hint at most once per process. The spawn guard sits on
+ * paths that run per command (`ensureDaemonRunning`, `launchWatcher`), and a
+ * repeated hint is noise.
+ */
+function warnStoreWriteDeniedOnce(message = exports.LEASE_DENIED_MESSAGE) {
+    if (sandboxNoticePrinted)
+        return;
+    sandboxNoticePrinted = true;
+    console.error(message);
+}
+/** Test hook: forget that the notice was printed. */
+function resetStoreWriteDeniedNotice() {
+    sandboxNoticePrinted = false;
+}

package/dist/lib/utils/tests-footer.js

@@ -9,14 +9,31 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOOTER_TIMEOUT_MS = void 0;
+exports.withFooterTimeout = withFooterTimeout;
 exports.fetchTestsForFooter = fetchTestsForFooter;
 exports.renderTestsFooterAgent = renderTestsFooterAgent;
 exports.renderTestsFooterHuman = renderTestsFooterHuman;
 const impact_1 = require("../graph/impact");
-const FOOTER_TIMEOUT_MS = 1500;
+/**
+ * The footer is a courtesy line under a body the user asked for; it must never
+ * make the command feel slow. Past this budget the lookup is abandoned and the
+ * footer is simply omitted (`null`, not an empty list — "did not finish" is not
+ * "no tests").
+ */
+exports.FOOTER_TIMEOUT_MS = 1500;
 const MAX_SHOWN = 5;
 const useColors = process.stdout.isTTY && !process.env.NO_COLOR;
 const dim = (s) => (useColors ? `\x1b[2m${s}\x1b[22m` : s);
+/**
+ * Race a footer lookup against `FOOTER_TIMEOUT_MS`. Exported because `extract`
+ * now fetches its footer over `graph.tests` rather than calling
+ * `fetchTestsForFooter` directly, and the budget has to cover the round trip
+ * the same way it covered the local query.
+ */
+function withFooterTimeout(p) {
+    return withTimeout(p, exports.FOOTER_TIMEOUT_MS);
+}
 function withTimeout(p, ms) {
     return __awaiter(this, void 0, void 0, function* () {
         let timer;
@@ -34,7 +51,7 @@ function withTimeout(p, ms) {
 }
 function fetchTestsForFooter(symbol, vectorDb, pathPrefix, excludePrefixes) {
     return __awaiter(this, void 0, void 0, function* () {
-        return withTimeout((0, impact_1.findTests)([symbol], vectorDb, pathPrefix, 1, excludePrefixes), FOOTER_TIMEOUT_MS);
+        return withTimeout((0, impact_1.findTests)([symbol], vectorDb, pathPrefix, 1, excludePrefixes), exports.FOOTER_TIMEOUT_MS);
     });
 }
 function relPath(p, projectRoot) {

package/dist/lib/utils/watcher-launcher.js

@@ -20,6 +20,7 @@ const autostart_1 = require("./autostart");
 const daemon_client_1 = require("./daemon-client");
 const daemon_launcher_1 = require("./daemon-launcher");
 const project_registry_1 = require("./project-registry");
+const store_access_1 = require("./store-access");
 const watcher_store_1 = require("./watcher-store");
 function launchWatcher(projectRoot) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -56,6 +57,15 @@ function launchWatcher(projectRoot) {
         if (notice) {
             return { ok: false, reason: "autostart-disabled", message: notice };
         }
+        // A spawned daemon (or per-project watcher) inherits this process's sandbox
+        // for its whole life. If ~/.gmax is read-only here it will be read-only
+        // there, and the child dies on its own lock mkdir — so probe once and say so
+        // instead of leaving a crash in daemon.log.
+        const sandboxed = (0, store_access_1.storeWriteDeniedNotice)();
+        if (sandboxed) {
+            (0, store_access_1.warnStoreWriteDeniedOnce)(sandboxed);
+            return { ok: false, reason: "sandboxed", message: sandboxed };
+        }
         const error = resp.error;
         if (error === "ENOENT" || error === "ECONNREFUSED") {
             const daemonPid = yield (0, daemon_launcher_1.spawnDaemon)();

package/package.json

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