knodin 0.10.3 → 0.10.4

package/dist/bin/cli.js

@@ -77,8 +77,17 @@ function integrationAgents(repo) {
     const repositoryDetected = inspectRepositoryIntegrationStatus(repo)?.agents ?? [];
     return [...new Set([...detectSupportedAgents(), ...previous, ...repositoryDetected])];
 }
-function formatInitHuman(result) {
-    let agents = `${result.paths.scope} — no supported coding agents detected`;
+export function formatInitHuman(result) {
+    // `configured` is what THIS run wrote, not what exists on the machine. The
+    // old wording called an empty list "no supported coding agents detected",
+    // asserting a detection result init never computed — and it read as a flat
+    // contradiction of the `status` line seconds later, which lists the agents
+    // that genuinely are configured (EASFDC-8499).
+    //
+    // Deliberately not calling the detector here: a formatter that reads the
+    // machine cannot be tested deterministically, and the honest fix is to stop
+    // claiming more than this value supports rather than to go find more.
+    let agents = `${result.paths.scope} — no agents configured by this run`;
     if (result.paths.scope === "cli-only")
         agents = "CLI-only — AI agents are not configured to discover knodin";
     else if (result.paths.agentIntegration.configured.length > 0)

package/dist/src/engine/index.js

@@ -46,6 +46,7 @@ import { isIndexableSourcePath } from "./source-policy.js";
 import { Database } from "./sqlite.js";
 import { lookupMirror, mayWriteToRepository, resolveDbPath, resolveStateDir, } from "./state-paths.js";
 import { deleteAllSymbols, deleteSymbolsForFile, deleteSymbolsMatchingPath, ORPHANED_EMBEDDING_PREDICATE, purgeOrphanEmbeddings, } from "./symbol-delete.js";
+import { searchRepoText } from "./text-matches.js";
 // ES Module resolution
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -11555,6 +11556,13 @@ function withStaleness(engine, claimRepository, openDb, openPolicy) {
                 row.staleness = staleness;
             return page;
         },
+        searchText(term, repoPath, options) {
+            claimRepository(repoPath);
+            // No staleness annotation: this reads the working tree directly rather
+            // than the graph, so its answers are current by construction and
+            // stamping them with the index's freshness would misreport them.
+            return engine.searchText(term, repoPath, options);
+        },
         async query(pattern, target, repoPath, to, limit, depth, detailLevel, selector, impactOptions, options) {
             claimRepository(repoPath);
             const result = await engine.query(pattern, target, repoPath, to, limit, depth, detailLevel, selector, impactOptions, options);
@@ -14073,6 +14081,15 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 indexCoordination.release();
             }
         },
+        async searchText(term, repoPath, options = {}) {
+            if (term.length === 0)
+                throw new Error("knodin searchText: term must not be empty");
+            // Reads the working tree, not the graph, so it needs no open database
+            // and no freshness check. `getLanguageForFile` is the same grammar
+            // loader indexing uses, which is what makes the classification
+            // evidence rather than a heuristic over file extensions.
+            return searchRepoText(path.resolve(repoPath), term, getLanguageForFile, () => new Parser(), options);
+        },
         async search(query, repoPath, limit, options = {}) {
             const resolvedRepoPath = path.resolve(repoPath);
             const offset = options.offset ?? 0;

package/dist/src/engine/text-matches.js

@@ -0,0 +1,309 @@
+/**
+ * Exact-text search with per-match classification (EASFDC-8496).
+ *
+ * The point of this module is the one thing `rg` cannot do: say *what a match
+ * is*. A product-name rename spans UI strings, prose and identifiers, and the
+ * reported case that motivated this had visible `NOVA` labels needing change
+ * while `NOVA-CANARY-…` was a deliberate security token that must not. A flat
+ * text search returns both and leaves a human to separate them by eye across
+ * however many hits a large repository yields.
+ *
+ * knodin can do better only because it already parses these files. For a file
+ * with a grammar, a match resolves to the smallest syntax node containing it,
+ * and the parser's own node type is the evidence. For a file without one, the
+ * strongest honest claim is about the file, not the match.
+ *
+ * That gap is not hidden. Every match carries the `basis` it was classified on,
+ * so a reviewer can see which answers came from a parse tree and which are an
+ * inference from a file extension. Classification will sometimes be wrong; it
+ * is offered as evidence a human is reviewing, never as a decision already
+ * taken on their behalf.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { walkRepoFiles } from "./file-walker.js";
+const WORD_CHARACTER = /[\p{L}\p{N}_]/u;
+/** Upper bound on `TextMatch.enclosingText`, so one row cannot flood a preview. */
+const ENCLOSING_TEXT_LIMIT = 120;
+function isWordCharacter(value) {
+    return value !== undefined && WORD_CHARACTER.test(value);
+}
+/**
+ * Map a grammar's node type onto a coarse class.
+ *
+ * Deliberately substring-based rather than an exhaustive per-language table.
+ * Across the grammars this project loads, the same concept appears as `string`,
+ * `string_literal`, `template_string`, `interpreted_string_literal`, `comment`,
+ * `line_comment`, `identifier`, `property_identifier` and more, and any fixed
+ * list would silently degrade to "unclassified" the first time a grammar is
+ * updated or added. An unrecognised type keeps `unclassified` while the real
+ * node type still travels on the match, so nothing is lost by guessing less.
+ */
+export function classifyNodeType(nodeType) {
+    const normalized = nodeType.toLowerCase();
+    if (normalized.includes("comment"))
+        return "comment";
+    if (normalized.includes("string") || normalized.includes("char_literal"))
+        return "string-literal";
+    if (normalized.includes("identifier") || normalized === "word")
+        return "identifier";
+    return "unclassified";
+}
+/**
+ * Extensions whose contents are prose rather than code.
+ *
+ * A file-type claim, and labelled as one: `basis: "file-type"`. Prose is the
+ * common case for the renames this feature exists to serve, so saying nothing
+ * at all about a markdown file would leave most matches unclassified.
+ */
+const PROSE_EXTENSIONS = new Set([".md", ".mdx", ".markdown", ".txt", ".rst", ".adoc", ".org"]);
+function extensionOf(file) {
+    const base = file.slice(file.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+export function classifyByFileType(file) {
+    return PROSE_EXTENSIONS.has(extensionOf(file)) ? "prose" : "unclassified";
+}
+/** Every occurrence of `term`, non-overlapping, left to right. */
+function findOccurrences(content, term, caseSensitive) {
+    if (term.length === 0)
+        return [];
+    const haystack = caseSensitive ? content : content.toLowerCase();
+    const needle = caseSensitive ? term : term.toLowerCase();
+    const found = [];
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1)
+            break;
+        found.push({
+            startIndex: at,
+            endIndex: at + term.length,
+            // Sliced from the ORIGINAL content, so the reported text carries the
+            // case actually on disk rather than the case that was searched for.
+            matchedText: content.slice(at, at + term.length),
+        });
+        from = at + term.length;
+    }
+    return found;
+}
+/** Byte-free line/column lookup, built once per file rather than per match. */
+function lineStarts(content) {
+    const starts = [0];
+    for (let i = 0; i < content.length; i++)
+        if (content[i] === "\n")
+            starts.push(i + 1);
+    return starts;
+}
+function lineIndexFor(starts, index) {
+    let low = 0;
+    let high = starts.length - 1;
+    while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (starts[mid] <= index)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low;
+}
+/**
+ * A tree-sitter abort is permanent and process-wide, not a per-file failure.
+ *
+ * Mirrors the engine's own guard (EASFDC-8445): swallowing one of these turns a
+ * dead WASM module into "this file has no matches" for every remaining file,
+ * which is precisely the silent-undercount this feature must not produce.
+ */
+function isWasmAbort(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.name === "ExitStatus");
+}
+/**
+ * Classify each match in one file against its parse tree.
+ *
+ * Parses once for the whole file, not once per match. Returns null when the
+ * file has no grammar, leaving the caller to fall back to a file-type claim.
+ */
+function classifyAgainstTree(parser, content, raw) {
+    const tree = parser.parse(content);
+    if (!tree)
+        return null;
+    try {
+        return raw.map((match) => {
+            // `endIndex - 1` because the range is inclusive: passing the exclusive
+            // end can select the following sibling for a match ending at a
+            // boundary, which mislabels exactly the tokens that sit flush against
+            // punctuation — quotes, most of all.
+            const node = tree.rootNode.descendantForIndex(match.startIndex, Math.max(match.startIndex, match.endIndex - 1));
+            const nodeType = node?.type ?? "";
+            const text = node?.text ?? "";
+            return {
+                classification: classifyNodeType(nodeType),
+                nodeType,
+                // Bounded: a match inside a large node (a whole template literal,
+                // a long comment) must not turn one row of a preview into a page.
+                enclosingText: text.length > ENCLOSING_TEXT_LIMIT ? `${text.slice(0, ENCLOSING_TEXT_LIMIT)}…` : text,
+            };
+        });
+    }
+    finally {
+        tree.delete();
+    }
+}
+/**
+ * Search already-read files for an exact term and classify every hit.
+ *
+ * `loadLanguage` is injected rather than imported so this module can be tested
+ * without standing up the engine's grammar loader, and so a caller that already
+ * knows a file has no grammar can skip the lookup.
+ *
+ * The parser is created lazily and freed in a `finally`: this walks the same
+ * ground as the leak that left 174,205 files silently unparsed, and a search
+ * over a large repository touches enough files to reproduce it exactly.
+ */
+export async function searchFiles(files, term, loadLanguage, newParser, options = {}) {
+    const caseSensitive = options.caseSensitive ?? true;
+    const matches = [];
+    const uncovered = [];
+    let filesSearched = 0;
+    for (const { file, content } of files) {
+        const raw = findOccurrences(content, term, caseSensitive);
+        filesSearched++;
+        if (raw.length === 0)
+            continue;
+        let classified = null;
+        let language = null;
+        try {
+            language = await loadLanguage(file);
+        }
+        catch {
+            // A grammar that will not load costs classification, not the match.
+            language = null;
+        }
+        if (language) {
+            const parser = newParser();
+            try {
+                parser.setLanguage(language);
+                classified = classifyAgainstTree(parser, content, raw);
+            }
+            catch (error) {
+                if (isWasmAbort(error))
+                    throw error;
+                // Parsing failed on this file only. The matches are still real and
+                // still reported — just without node evidence.
+                classified = null;
+                uncovered.push({
+                    file,
+                    reason: `matched but could not be parsed for classification: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+            finally {
+                try {
+                    parser.delete();
+                }
+                catch {
+                    /* a dead module has nothing to reclaim */
+                }
+            }
+        }
+        const starts = lineStarts(content);
+        raw.forEach((match, position) => {
+            const lineIndex = lineIndexFor(starts, match.startIndex);
+            const lineStart = starts[lineIndex];
+            const nextStart = starts[lineIndex + 1] ?? content.length + 1;
+            const node = classified?.[position] ?? null;
+            matches.push({
+                file,
+                line: lineIndex + 1,
+                column: match.startIndex - lineStart + 1,
+                startIndex: match.startIndex,
+                endIndex: match.endIndex,
+                lineText: content.slice(lineStart, Math.max(lineStart, nextStart - 1)).replace(/\r$/, ""),
+                matchedText: match.matchedText,
+                caseMatchesQuery: match.matchedText === term,
+                withinLargerWord: isWordCharacter(content[match.startIndex - 1]) ||
+                    isWordCharacter(content[match.endIndex]),
+                classification: node ? node.classification : classifyByFileType(file),
+                basis: node ? "parse-node" : language ? "none" : "file-type",
+                nodeType: node ? node.nodeType : null,
+                enclosingText: node ? node.enclosingText : null,
+            });
+        });
+    }
+    return { matches, uncovered, filesSearched, searched: true };
+}
+/**
+ * Read a file for searching, or say why it could not be.
+ *
+ * Binary detection is a NUL-byte sniff over the head of the file rather than an
+ * extension list: the extensions that matter here are open-ended, and a
+ * misjudged binary read produces garbage matches rather than an honest skip.
+ */
+function readSearchable(absolute) {
+    let buffer;
+    try {
+        buffer = fs.readFileSync(absolute);
+    }
+    catch (error) {
+        return { reason: `unreadable: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (buffer.subarray(0, 8192).includes(0))
+        return { reason: "binary" };
+    return { content: buffer.toString("utf8") };
+}
+/**
+ * Exact-text search across a whole repository (R1).
+ *
+ * Enumerates with the indexer's prune rules but NOT its source-extension
+ * filter. That difference is the requirement: a product-name rename lives in
+ * markdown, UI strings and changelogs, so restricting the search to files that
+ * yield symbols would answer a different question than the one being asked.
+ *
+ * Every file that could not be searched is returned in `uncovered` (R5). A
+ * rename that silently skipped files would leave a half-renamed repository
+ * looking finished, which is the worst available outcome for this operation.
+ */
+export async function searchRepoText(repoPath, term, loadLanguage, newParser, options = {}) {
+    let candidates;
+    try {
+        // Checked explicitly because `walkRepoFiles` swallows a missing directory
+        // and returns an empty list. Without this, searching a path that does not
+        // exist reports a completed search over zero files — "the term appears
+        // nowhere", which is the precise failure AC5 exists to make impossible.
+        const stats = fs.statSync(repoPath);
+        if (!stats.isDirectory())
+            throw new Error("not a directory");
+        candidates = walkRepoFiles(repoPath);
+    }
+    catch (error) {
+        // Enumeration failed, so nothing was searched. Reported as `searched:
+        // false` rather than as an empty match list, which would read as "the
+        // term appears nowhere" (AC5).
+        return {
+            matches: [],
+            uncovered: [
+                {
+                    file: repoPath,
+                    reason: `could not enumerate: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            filesSearched: 0,
+            searched: false,
+        };
+    }
+    const readable = [];
+    const uncovered = [];
+    for (const file of candidates) {
+        const outcome = readSearchable(path.join(repoPath, file));
+        if ("reason" in outcome)
+            uncovered.push({ file, reason: outcome.reason });
+        else
+            readable.push({ file, content: outcome.content });
+    }
+    const result = await searchFiles(readable, term, loadLanguage, newParser, options);
+    // Files skipped at read time and files that failed classification are both
+    // gaps in the same claim, so they are reported through one list.
+    return { ...result, uncovered: [...uncovered, ...result.uncovered] };
+}

package/dist/src/init.js

@@ -7,6 +7,7 @@ import { compareBytes } from "./compare.js";
 import { isIndexableSourcePath } from "./engine/source-policy.js";
 import { lookupMirror } from "./engine/state-paths.js";
 import { inspectLefthookIntegration, installHookManagerIntegration, isActiveLefthookHook, } from "./hook-manager-integration.js";
+import { stableInterpreterPath } from "./node-runtime.js";
 import { acquireRepairLease, LIFECYCLE_LEASE_TOKEN_ENV } from "./repair-lease.js";
 import { installKnodinSkills, removeKnodinSkills } from "./skill-management.js";
 import { registerInitializedWorktree } from "./worktree-lifecycle.js";
@@ -426,7 +427,13 @@ function backgroundScript(command) {
     // silently switch which runtime executes, which is its own bug.
     const [interpreter, ...rest] = command;
     const invocation = ['"$KNODIN_NODE"', ...rest.map(shellQuote)].join(" ");
-    const preferred = shellQuote(interpreter ?? process.execPath);
+    // Recorded through `stableInterpreterPath` so a Homebrew interpreter is
+    // written as its version-stable `opt` path rather than the versioned Cellar
+    // path Node reports. Without it the preferred path is guaranteed to break on
+    // the next `brew upgrade` and every hook leans on the fallback below to stay
+    // alive — which works, but means the recorded path is wrong from the moment
+    // it is written (EASFDC-8497).
+    const preferred = shellQuote(stableInterpreterPath(interpreter ?? process.execPath));
     return String.raw `#!/bin/sh
 # knodin packaged background refresh. Generated by knodin init.
 set -u

package/dist/src/lifecycle-health.js

@@ -136,6 +136,39 @@ function inspectManagedHooks(repo, hooksDirectory) {
         routing: hookRouting(wrappers, managerNative),
     };
 }
+/**
+ * The interpreter a generated hook records, when that interpreter is gone.
+ *
+ * Existence and the executable bit say the script is runnable; they say nothing
+ * about whether the runtime on its first line still exists. A hook written
+ * against a Homebrew Cellar path stops working at the next `brew upgrade` and
+ * fails with exit 127 in the background, where the only trace is a log file
+ * (EASFDC-8497). Health then reported "degraded" without ever naming the cause,
+ * and `repair` could not help because the fault is in the hook's contents, not
+ * in graph state.
+ *
+ * Returns null when the hook is fine, unreadable, or shaped differently than
+ * expected — an unparseable hook is not evidence of a missing interpreter, and
+ * guessing here would invent a failure rather than report one.
+ */
+function recordedInterpreterIfMissing(backgroundScriptPath) {
+    let contents;
+    try {
+        contents = fs.readFileSync(backgroundScriptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const recorded = /^KNODIN_NODE='([^']+)'/m.exec(contents)?.[1];
+    if (!recorded)
+        return null;
+    if (fs.existsSync(recorded))
+        return null;
+    // A working `node` on PATH means the hook's own fallback will carry it, so
+    // this is not currently breaking anything — but the recorded path is still
+    // wrong and the next environment without that fallback breaks silently.
+    return recorded;
+}
 function readRefreshFailure(repo) {
     const failurePath = path.join(repo, ".knodin", "hooks", HOOK_FAILURE_FILE);
     if (!fs.existsSync(failurePath))
@@ -218,6 +251,9 @@ export function inspectLifecycleHealth(repoPath) {
     const issues = missingHooks.map((hook) => `${hook} no longer routes through knodin's active Git hook path`);
     if (!backgroundReady)
         issues.push("background indexer is missing or not executable");
+    const staleInterpreter = backgroundReady ? recordedInterpreterIfMissing(background) : null;
+    if (staleInterpreter)
+        issues.push(`background indexer records a Node interpreter that no longer exists (${staleInterpreter}); run \`knodin init\` to rewrite the hook`);
     const lastError = readRefreshFailure(repo);
     if (lastError)
         issues.push(`${lastError} See .knodin/indexer.log for details`);

package/dist/src/node-runtime.js

@@ -155,3 +155,36 @@ export function handoffCurrentProcessToSupportedNodeRuntime() {
         listDirectories,
     });
 }
+/**
+ * Rewrite a Homebrew Cellar path to the version-stable `opt` path it came from.
+ *
+ * `process.execPath` is symlink-resolved by Node, so invoking a stable entry
+ * point does not preserve it:
+ *
+ *   $ /opt/homebrew/opt/node/bin/node -p "process.execPath"
+ *   /opt/homebrew/Cellar/node/26.7.0/bin/node
+ *
+ * Both stable Homebrew entry points report the versioned path, which means the
+ * caller cannot avoid this by launching differently — by the time knodin can
+ * read its own interpreter, the durable path is already gone. Anything that
+ * records `execPath` for later therefore records a path Homebrew deletes on the
+ * next `brew upgrade`, and a managed hook written against it dies with exit 127
+ * (EASFDC-8497, and the 174k-file class of failure before it: a background
+ * process failing where nobody is looking).
+ *
+ * `<prefix>/opt/<formula>` is the symlink Homebrew repoints on upgrade, so the
+ * path survives by construction rather than by a runtime fallback. Derived from
+ * the matched prefix rather than hardcoding `/opt/homebrew`, so Intel
+ * (`/usr/local`) and Linuxbrew layouts work unchanged.
+ *
+ * Returns the input untouched when it is not a Cellar path, or when the `opt`
+ * path does not exist — a rewrite is only safe if the destination is real.
+ */
+export function stableInterpreterPath(executable, exists = (candidate) => fs.existsSync(candidate)) {
+    const match = /^(.*)\/Cellar\/([^/]+)\/[^/]+\/(.+)$/.exec(executable);
+    if (!match)
+        return executable;
+    const [, prefix, formula, remainder] = match;
+    const candidate = `${prefix}/opt/${formula}/${remainder}`;
+    return exists(candidate) ? candidate : executable;
+}

package/dist/src/tools/knodin-tools.js

@@ -183,6 +183,7 @@ function buildDocumentedKnodinTools() {
                             "review",
                             "map",
                             "search",
+                            "textSearch",
                             "query",
                             "prs",
                             "context",
@@ -204,7 +205,7 @@ function buildDocumentedKnodinTools() {
                             "diagnostics",
                             "sealed",
                         ],
-                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. execute: run one immutable repository-defined profile only when independently enabled globally and locally; no executable or argv is accepted from the caller, unsupported containment fails closed, and output is compressed then diagnosed. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.knodin/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP. remote: list read-only mirrors of repositories that are reachable but not checked out locally, so you can run explain/query/map/search against one by passing its `path` as `repoPath`. Each mirror is a snapshot pinned at a commit; the remote is not watched. Acquiring, refreshing, and removing mirrors is CLI-only (`knodin remote add|refresh|remove`) because it clones another repository's source onto this machine and consumes disk nothing reclaims automatically — the user's decision to make, not an agent's. sealed: query a sealed artifact (`artifactPath`) with NO checkout — source is embedded in it. Returns attested identity, commit, ref, age, coverage, and a `degraded` list of what it cannot do; pass `symbol` to explain. Describes the attested commit and no later one, so staleness is `unknown`, never `fresh`. Creating one is CLI-only (`knodin seal`).",
+                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. textSearch: use when what you are renaming is NOT a code symbol — a product name, a UI label, a literal — so `explain` does not apply. Read-only exact-text match repo-wide, including files yielding no symbols (markdown, config); each hit is classified string/comment/identifier/prose with `basis` stating whether that came from the file's parse tree or only its extension. Names files it could not read, and separates no-matches from could-not-search. `caseSensitive: false` also matches other casings, each labelled. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. execute: run one immutable repository-defined profile only when independently enabled globally and locally; no executable or argv is accepted from the caller, unsupported containment fails closed, and output is compressed then diagnosed. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.knodin/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP. remote: list read-only mirrors of repositories that are reachable but not checked out locally, so you can run explain/query/map/search against one by passing its `path` as `repoPath`. Each mirror is a snapshot pinned at a commit; the remote is not watched. Acquiring, refreshing, and removing mirrors is CLI-only (`knodin remote add|refresh|remove`) because it clones another repository's source onto this machine and consumes disk nothing reclaims automatically — the user's decision to make, not an agent's. sealed: query a sealed artifact (`artifactPath`) with NO checkout — source is embedded in it. Returns attested identity, commit, ref, age, coverage, and a `degraded` list of what it cannot do; pass `symbol` to explain. Describes the attested commit and no later one, so staleness is `unknown`, never `fresh`. Creating one is CLI-only (`knodin seal`).",
                     },
                     profile: {
                         type: "string",
@@ -221,7 +222,7 @@ function buildDocumentedKnodinTools() {
                     },
                     file: {
                         type: "string",
-                        description: "Repo-relative definition file selector.",
+                        description: "Repo-relative file. Disambiguates which definition is meant when a symbol resolves in several files; with query impact and impactMode=file it names the target file instead.",
                     },
                     evidenceLevel: {
                         type: "string",
@@ -272,7 +273,7 @@ function buildDocumentedKnodinTools() {
                     impactMode: {
                         type: "string",
                         enum: ["symbol", "file"],
-                        description: "query impact only: stable symbol reach (default) or explicitly labeled changed-file blast radius.",
+                        description: "query impact only: stable symbol reach (default) or explicitly labeled changed-file blast radius. With `file`, name the target in the `file` parameter, or pass comma-separated paths in `symbol` for a multi-file change set.",
                     },
                     direction: {
                         type: "string",
@@ -399,6 +400,10 @@ function buildDocumentedKnodinTools() {
                         enum: ["all", "test", "production"],
                         description: "search/file_metrics: include all, test-only, or production-only files.",
                     },
+                    caseSensitive: {
+                        type: "boolean",
+                        description: "textSearch only; default true. False also matches other casings; each hit reports the case on disk and whether it matched exactly, so a case-sensitive token is not folded into the same decision as a label.",
+                    },
                     offset: {
                         type: "number",
                         minimum: 0,
@@ -1398,7 +1403,7 @@ async function handleDiagnosticsOperation(repo, args, bounded) {
 async function dispatchKnodinTool(args) {
     const startedAt = performance.now();
     const parsedArgs = (args ?? {});
-    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, queries, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
+    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, queries, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, caseSensitive, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
     const repo = repoPath ?? process.cwd();
     const selector = {
         identity: expandCompactIdentity(identity),
@@ -1744,6 +1749,15 @@ async function dispatchKnodinTool(args) {
                 includeSource,
                 offset,
             }));
+        case "textSearch": {
+            if (!query)
+                throw new Error("knodin textSearch requires `query` (the exact text to find)");
+            const found = await engine.searchText(query, repo, { caseSensitive });
+            // Not routed through `graphRead`: this reads the working tree rather
+            // than the graph, so it is answerable — and correct — on a repository
+            // whose index is stale, absent, or still building.
+            return bounded(found, "textSearch");
+        }
         case "prs": {
             return bounded(await handlePullRequestsOperation({
                 repo,
@@ -1799,8 +1813,23 @@ async function dispatchKnodinTool(args) {
             if (limit !== undefined && (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1))
                 throw new Error("knodin query: limit must be a positive integer");
             const repoWide = REPO_WIDE_QUERY_PATTERNS.includes(pattern);
-            if (!symbol && !repoWide)
-                throw new Error(`knodin query ${pattern} requires \`symbol\``);
+            // File-mode impact takes its target as comma-separated paths in
+            // `symbol`. That is not the call anyone forms from this schema: a `file`
+            // parameter is published right beside `impactMode`, and the obvious
+            // reading — impactMode "file" plus file: <path> — was rejected with
+            // "requires `symbol`", naming a field the caller had deliberately not
+            // used. A user reported the capability as unavailable because of it.
+            //
+            // `file` is now accepted as the target here, and only here: in symbol
+            // mode it keeps its existing meaning as a definition disambiguator.
+            const fileModeImpact = pattern === "impact" && impactMode === "file";
+            if (fileModeImpact && symbol && file && symbol !== file)
+                throw new Error(`knodin query impact with impactMode=file received different targets in \`symbol\` (${symbol}) and \`file\` (${file}); pass one`);
+            const target = fileModeImpact ? (symbol ?? file) : symbol;
+            if (!target && !repoWide)
+                throw new Error(fileModeImpact
+                    ? "knodin query impact with impactMode=file requires a target path in `file`, or comma-separated paths in `symbol`"
+                    : `knodin query ${pattern} requires \`symbol\``);
             if ((pattern === "shortest_path" || pattern === "cross_substrate_path") && !to)
                 throw new Error(`knodin query ${pattern} requires \`to\``);
             if (pattern === "rename_preview" && !to)
@@ -1817,7 +1846,7 @@ async function dispatchKnodinTool(args) {
                     .rename(symbol ?? "", to ?? "", repo, apply === true, true, selector)
                     .then((result) => bounded(decorateGraphQueryResult(result, queryHealth?.available ? queryHealth.state : "healthy", queryHealth?.available ? queryHealth.graph.freshness : undefined), "query:rename_preview"));
             }
-            const queryResult = await engine.query(pattern, symbol ?? "", repo, to, Math.min(limit ?? itemBudget ?? 100, itemBudget ?? 1000), depth, detailLevel === "source" ? undefined : detailLevel, selector, pattern === "impact"
+            const queryResult = await engine.query(pattern, target ?? "", repo, to, Math.min(limit ?? itemBudget ?? 100, itemBudget ?? 1000), depth, detailLevel === "source" ? undefined : detailLevel, selector, pattern === "impact"
                 ? {
                     mode: impactMode ?? "symbol",
                     direction,

package/dist/src/wait-for-fresh.js

@@ -62,6 +62,30 @@ function completedStatus(graph) {
         return "unknown";
     return null;
 }
+/**
+ * Waiting here can only end at the timeout (EASFDC-8498).
+ *
+ * `queued` freshness means progress depends on the queued-event drainer, and
+ * `reconcileOrdinaryDrift` deliberately declines that state, so the in-process
+ * path cannot advance it either. If the drainer also cannot run, every
+ * remaining poll is spent relaunching a processor that will not start.
+ *
+ * This is the exact shape reported on 0.10.2: a hook exiting 127 on every
+ * invocation, freshness stuck at `queued`, and `status` recommending
+ * `wait --fresh` — which held the reason for its own futility on every poll and
+ * reported none of it.
+ *
+ * Deliberately narrow. A degraded lifecycle with freshness that is NOT queued
+ * can still be reconciled in process, and failing fast there would refuse work
+ * the command can actually do.
+ */
+function blockedOnDeadDrainer(graph) {
+    return graph.freshness?.state === "queued" && !graph.lifecycle.refreshCapable;
+}
+function describeDeadDrainer(graph) {
+    const detail = graph.lifecycle.lastError ?? graph.lifecycle.issues[0] ?? "cause not recorded";
+    return `background refresh cannot run, so queued work will not drain: ${detail}`;
+}
 async function reconcileOrdinaryDrift(engine, repo, graph) {
     const shouldReconcile = (graph.status === "stale" || graph.status === "repair-needed") &&
         graph.freshness.state !== "queued";
@@ -90,9 +114,27 @@ export async function waitForFresh(engine, repo, timeoutMs = 30_000, processQueu
         status = completedStatus(graph);
         if (status)
             return completedResult(status, startedAt, polls, graph);
+        // Checked after the completion checks, never before: a repository that is
+        // already fresh must still report `fresh`, even with a broken hook.
+        if (blockedOnDeadDrainer(graph))
+            return {
+                status: "lifecycle-degraded",
+                waitedMs: Date.now() - startedAt,
+                polls,
+                graph,
+                reason: describeDeadDrainer(graph),
+            };
         const elapsed = Date.now() - startedAt;
         if (elapsed >= timeoutMs)
-            return { status: "timeout", waitedMs: elapsed, polls, graph };
+            return {
+                status: "timeout",
+                waitedMs: elapsed,
+                polls,
+                graph,
+                // A timeout that names nothing is what sent the reporter looking in
+                // the wrong place. Say what was still outstanding.
+                reason: `still waiting on ${graph.lifecycle.queuedEvents} queued event(s)${graph.lifecycle.lastError ? `; last refresh error: ${graph.lifecycle.lastError}` : ""}`,
+            };
         await delay(Math.min(100, timeoutMs - elapsed));
     }
 }

package/docs/releases/0.10.4.md

@@ -0,0 +1,161 @@
+# knodin 0.10.4
+
+Five changes from two pieces of field feedback. The first came from a
+product-name rename in the Nova repository; the second from a checkout whose
+background refresh had been failing silently since a Homebrew upgrade.
+
+The theme is the same one 0.10.2 and 0.10.3 were about: a tool that reports
+things it has not verified, and a failure that leaves no trace anywhere a person
+looks.
+
+## `textSearch`: exact text, with every match classified
+
+The reported blocker: the refactor workflow assumes a rename targets a code
+symbol. This one was a product-name literal spanning UI strings and documents,
+where `explain` and symbol resolution do not apply. The reporter fell back to
+`rg` and hand-applied patches for the whole task.
+
+Searching is the easy half. The half worth building is classification, and their
+case shows why: visible `NOVA` labels had to change, while `NOVA-CANARY-…` was a
+deliberate case-sensitive security token that had to survive. A flat text search
+returns both and leaves a human to separate them by eye across however many hits
+a large repository produces — exactly the position knodin exists to remove
+people from.
+
+knodin can classify only because it already parses these files. A match in a
+file with a grammar resolves to its smallest containing syntax node, and the
+parser's own node type is the evidence. A file without a grammar supports a
+claim about the file, not about the match.
+
+That difference is reported rather than smoothed over. Every match carries the
+`basis` its classification rests on — `parse-node`, `file-type`, or `none` — and
+the grammar's raw node type travels alongside the coarse label so a bad mapping
+is catchable. Classification will sometimes be wrong; it is offered as evidence
+a human is reviewing, never as a decision already taken.
+
+Three details that matter in practice:
+
+- **Documents are searched.** Enumeration uses the indexer's prune rules but not
+  its source-extension filter, because markdown and config are the point.
+- **Files that could not be read are named**, not omitted. A rename that
+  silently skipped files would leave a half-renamed repository looking finished.
+- **"No matches" is distinguishable from "could not search."** An empty list
+  that reads as reassurance is the defect this whole operation exists to avoid.
+
+`textSearch` reads the working tree rather than the graph, so it stays
+answerable when the index is stale, absent, or still building — often exactly
+when a rename is underway.
+
+It previews only. Applying edits is deliberately not in this release.
+
+## `impact` accepts the file you gave it
+
+Reported verbatim against 0.10.2:
+
+```
+operation: query, pattern: impact, impactMode: file,
+file: documents/nova-architecture-deck.js
+-> knodin query impact requires `symbol`
+```
+
+File-mode impact was never missing. It read its target from `symbol`, documented
+in one clause buried inside that parameter's prose, while a `file` parameter sat
+published right beside `impactMode` meaning something else entirely. The schema
+offered both, and the combination anyone would form from them was the one that
+failed.
+
+That is worse than a missing feature: the reporter concluded the capability was
+broken and moved on. A working feature was recorded as unavailable because of
+parameter naming.
+
+`file` is now accepted as the target under file mode, and keeps its original
+meaning in symbol mode. Conflicting `symbol` and `file` values are refused with
+both named rather than resolved by preference — silently picking one would
+answer a question nobody asked. The error now states the supported call.
+
+## Managed hooks survive a Node upgrade
+
+A checkout's background refresh had exited 127 seventeen consecutive times:
+
+```
+background-index.sh: /opt/homebrew/Cellar/node/26.5.0_1/bin/node:
+No such file or directory
+```
+
+`brew upgrade node` deletes the versioned Cellar directory. The hook had
+recorded the interpreter's absolute path at generation time, and that path
+contains the version, so it was guaranteed to stop existing.
+
+The caller cannot avoid this: Node symlink-resolves `process.execPath`, so
+invoking `/opt/homebrew/opt/node/bin/node` still reports the Cellar path. By the
+time knodin can read its own interpreter, the durable path is gone.
+
+The recorded path is now mapped back to `<prefix>/opt/<formula>/…`, the symlink
+Homebrew repoints on upgrade, so it survives by construction rather than by
+falling back at run time. The prefix is derived from the match, so Intel
+`/usr/local` and Linuxbrew work through the same path. A non-Homebrew
+interpreter is left untouched.
+
+**Existing repositories need one `knodin init`** to pick up a corrected hook.
+`repair` cannot do it: the fault lives in the hook's contents, not in graph
+state — which is why a `repair` run in that checkout returned "healthy" while
+the lifecycle stayed broken.
+
+Lifecycle health now notices this class of failure. It previously checked that
+the background script existed and was executable, neither of which says anything
+about the runtime on its first line, so the repository reported a degraded
+lifecycle while naming no cause. The reported issue now names the missing
+interpreter and the command that rewrites the hook.
+
+## `wait --fresh` stops instead of waiting for something that cannot happen
+
+`wait --fresh` has always had a bounded timeout, and it was reached honestly.
+But when the background refresh is failing, waiting cannot succeed, and the
+command already knew that: it recomputes lifecycle health on every poll, so it
+was holding the exit-127 error the entire time it spun, then reported the single
+word `timeout`.
+
+It now returns immediately when freshness is queued and lifecycle refresh cannot
+run — the pairing that is genuinely futile — and names the recorded failure.
+Timeouts carry a reason as well: what remained queued, and the last refresh
+error.
+
+The guard is narrow on purpose. A degraded lifecycle whose freshness is not
+queued can still be reconciled in process, and a repository that is already
+fresh still reports `fresh` even with a broken hook.
+
+## `init` no longer denies agents that are configured
+
+Six seconds apart, with nothing installed in between:
+
+```
+$ knodin init
+Agent integration: personal - no supported coding agents detected
+$ knodin status
+Agent integration: personal (claude, codex, gemini, antigravity)
+```
+
+Both commands were computing something correct — `init` reports what that run
+configured, `status` reports what is configured — but `init` described its empty
+set as a *detection* result it had never run, which reads as a denial of the
+four agents the next command lists. It now says what the value supports: no
+agents configured by this run.
+
+## Known gaps
+
+Two items from the same report are deliberately not fixed here rather than
+guessed at:
+
+- `status` and `repair` can disagree about indexed-file and symbol counts. In
+  the reported session `status` showed 0 indexed files and 95 issues while
+  `repair`, seconds later, reported 94 indexed files and 53 with symbols and
+  called itself "verified". Whether `repair` inspected or silently rebuilt
+  changes what the fix is, and the evidence does not settle it.
+- `init --scope personal` leaves `.agents/`, `.codex/` and `.gemini/` untracked
+  and unexcluded, and migrates a tracked `.gitignore` entry without saying so.
+
+## Compatibility
+
+Compatible. Nothing is removed or renamed; `textSearch` is a new operation
+alongside the existing ones, and `file` gains a meaning under `impactMode: file`
+while keeping its previous one everywhere else.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.10.3",
+	"version": "0.10.4",
 	"knodin": {
 		"compatibility": "compatible"
 	},
@@ -75,6 +75,7 @@
 		"docs/releases/0.10.1.md",
 		"docs/releases/0.10.2.md",
 		"docs/releases/0.10.3.md",
+		"docs/releases/0.10.4.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",