knodin 0.12.0 → 0.12.2

package/dist/bin/cli.js

@@ -195,8 +195,15 @@ function formatLifecycleLine(lifecycle, isMirror) {
         return "";
     if (isMirror)
         return "Hooks: not applicable; a mirror is refreshed explicitly, not by Git events.\n";
-    if (lifecycle.status === "healthy")
-        return "Hooks: installed and executable.\n";
+    if (lifecycle.status === "healthy") {
+        // A silent self-heal would leave the user unable to explain why the hook's
+        // interpreter changed; a degraded report for a fixed condition would cry
+        // wolf. Say what happened, once, on the healthy line.
+        const heal = lifecycle.interpreterSelfHeal;
+        return heal
+            ? `Hooks: installed and executable; background indexer interpreter self-healed (${heal.from} -> ${heal.to}).\n`
+            : "Hooks: installed and executable.\n";
+    }
     const issue = lifecycle.issues[0] ?? "refresh capability is not verified";
     return `Lifecycle refresh: ${lifecycle.status}; ${issue}. Run \`knodin repair --lifecycle\`.\n`;
 }
@@ -449,24 +456,34 @@ function formatStatusHuman(result) {
     // led with an arbitrary source filename, so an absent graph read as damage
     // proportional to repository size. `missing.files` still carries the repair
     // worklist — only the count and the headline shown to a human change here.
-    const outstanding = result.coverage.countsUnknown
-        ? result.missing.records.length
-        : result.missing.files.length + result.missing.records.length;
-    const firstIssue = result.coverage.countsUnknown
-        ? result.missing.records[0]
-        : (result.missing.files[0] ?? result.missing.records[0]);
-    const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
+    const issueItems = result.coverage.countsUnknown
+        ? result.missing.records
+        : [...result.missing.files, ...result.missing.records];
+    const outstanding = issueItems.length;
+    // One issue keeps the established single-line shape; more are listed bounded
+    // rather than hidden behind "First issue" — a report that names one problem
+    // out of several sends the user to fix it and then surprises them with the
+    // rest, one status invocation at a time (KNODIN-38).
+    const shownIssues = issueItems.slice(0, 5);
+    const hiddenIssues = outstanding - shownIssues.length;
+    const detail = shownIssues.length === 0
+        ? ""
+        : shownIssues.length === 1
+            ? ` First issue: ${shownIssues[0]}.`
+            : ` Issues: ${shownIssues.join("; ")}${hiddenIssues > 0 ? `; +${hiddenIssues} more (see --json)` : ""}.`;
     // A linked worktree with no database is the one case where `repair` is both
     // the wrong first step and the expensive one: `init` seeds from an indexed
     // sibling and reconciles only what differs, while `repair` builds from
     // scratch. The engine has already worked out that this is that case, so
     // defer to the step it wrote rather than recomputing the judgement here.
     const worktreeStep = result.repairSteps?.find((step) => step.includes("per-worktree"));
-    const repairCommand = worktreeStep ??
-        (result.lifecycle?.status === "degraded" &&
-            result.missing.records.every((record) => result.lifecycle?.issues.includes(record))
-            ? "Run `knodin init`."
-            : "Run `knodin repair`.");
+    // Lifecycle-only damage takes `repair --lifecycle`, not `init`: the graph is
+    // healthy, and the engine's own repairSteps already say so — prescribing
+    // `init` here contradicted the lifecycle line printed directly beneath it.
+    const lifecycleOnly = result.lifecycle?.status === "degraded" &&
+        (result.coverage.countsUnknown || result.missing.files.length === 0) &&
+        result.missing.records.every((record) => result.lifecycle?.issues.includes(record));
+    const repairCommand = worktreeStep ?? (lifecycleOnly ? "Run `knodin repair --lifecycle`." : "Run `knodin repair`.");
     return `Graph or lifecycle needs repair: ${outstanding} issue(s) found (${coverage}).${detail} ${repairCommand}\n${lifecycleLine}${integrationLine}`;
 }
 function humanLabel(key) {
@@ -1867,13 +1884,20 @@ async function main() {
             if (client !== undefined &&
                 !["claude", "codex", "gemini", "copilot", "antigravity"].includes(client))
                 throw new Error("knodin doctor: --client must be claude, codex, gemini, copilot, or antigravity");
-            const unsupported = rest.filter((argument, index) => argument !== "--client" && rest[index - 1] !== "--client");
+            const unsupported = rest.filter((argument, index) => argument !== "--client" && argument !== "--deep" && rest[index - 1] !== "--client");
             if (unsupported.length > 0)
                 throw new Error(`knodin doctor: unknown option ${unsupported[0]}`);
             const diagnosis = await diagnoseInstallation(repo, {
                 currentVersion: KNODIN_VERSION,
                 runtimeCommand: [...runtimeCommand, "serve"],
-                graph: await engine.status(repo, { audit: "deep" }),
+                // Adaptive, like `status`: the persisted-audit path runs the same
+                // drift probe, so a stale graph still reports stale, while a forced
+                // deep audit on a very large repository cost doctor two full stat
+                // sweeps every run (KNODIN-39). `--deep` keeps the exact audit
+                // available on demand.
+                graph: await engine.status(repo, {
+                    audit: rest.includes("--deep") ? "deep" : "adaptive",
+                }),
                 client,
             });
             const manager = diagnosis.manager.name;
@@ -1884,7 +1908,23 @@ async function main() {
                     : "unknown",
                 env: process.env,
             });
-            result = diagnosis;
+            // One MCP probe backs every client row; the human listing printed the
+            // identical initialize/toolsList block five times, reading as five
+            // independent server checks (KNODIN-40). JSON keeps the per-client
+            // shape for compatibility.
+            const agents = diagnosis.agents;
+            result = jsonOutput
+                ? diagnosis
+                : {
+                    ...diagnosis,
+                    agents: {
+                        ...agents,
+                        clients: agents.clients?.map((clientRow) => ({
+                            ...clientRow,
+                            server: "shared MCP probe; see the mcp section",
+                        })),
+                    },
+                };
             break;
         }
         case "system": {

package/dist/src/backup-retention.js

@@ -355,12 +355,19 @@ function parseRetentionReceipt(value) {
 }
 function readInstalledRetention(options) {
     const locations = homes(options);
+    const receiptPath = path.join(locations.stateRoot, "receipt.json");
     const policy = parseRetentionPolicy(readJson(locations.policy));
-    const receipt = parseRetentionReceipt(readJson(path.join(locations.stateRoot, "receipt.json")));
+    const receipt = parseRetentionReceipt(readJson(receiptPath));
+    // A machine where NEITHER file exists never had retention installed; that is
+    // a clean state, not a broken one, and reporting "missing-or-invalid" for it
+    // taught every fresh doctor run to cry attention-required (KNODIN-40). Any
+    // on-disk trace — even an unparseable file — is installation evidence and
+    // keeps the strict issue reporting.
+    const installEvidence = fs.existsSync(locations.policy) || fs.existsSync(receiptPath);
     const issues = [];
-    if (!policy)
+    if (installEvidence && !policy)
         issues.push("policy-missing-or-invalid");
-    if (!receipt)
+    if (installEvidence && !receipt)
         issues.push("receipt-missing-or-invalid");
     if (policy && receipt && digest(`${JSON.stringify(policy, null, 2)}\n`) !== receipt.policyDigest)
         issues.push("policy-receipt-mismatch");
@@ -373,7 +380,7 @@ function readInstalledRetention(options) {
             issues.push(`scheduler-missing: ${artifact.path}`);
         }
     }
-    return { policy, receipt, issues };
+    return { policy, receipt, issues, installEvidence };
 }
 function commandRunner(command, args) {
     const result = childProcess.spawnSync(command, args, { encoding: "utf8" });
@@ -571,11 +578,18 @@ export function installBackupRetention(roots, options = {}) {
 }
 export function retentionStatus(options = {}) {
     const locations = homes(options);
-    const { policy, receipt, issues } = readInstalledRetention(options);
+    const { policy, receipt, issues, installEvidence } = readInstalledRetention(options);
     const lastRun = readJson(path.join(locations.stateRoot, "last-run.json"));
     return {
         schemaVersion: 1,
-        status: issues.length === 0 ? "healthy" : policy || receipt ? "attention-required" : "not-installed",
+        // Keyed on on-disk evidence rather than parse success: a never-installed
+        // machine is "not-installed" with no issues, while an installed-but-broken
+        // state (either file present, parseable or not) keeps attention-required.
+        status: !installEvidence && issues.length === 0
+            ? "not-installed"
+            : issues.length === 0
+                ? "healthy"
+                : "attention-required",
         installed: Boolean(policy && receipt),
         policy,
         receipt,

package/dist/src/doctor.js

@@ -171,15 +171,68 @@ function managedConfigurationRemediation(repo, run) {
                 paths.push(relative);
         }
     }
+    // One `ls-files` and one `diff` for every managed path together: the previous
+    // per-path pair spawned ~2 git processes per entry, and each `git diff` must
+    // load and refresh the repository index — seconds apiece on a 900k-file
+    // checkout, for identical answers (KNODIN-39).
+    const trackedResult = run("git", ["-C", repo, "ls-files", "-z", "--", ...paths]);
+    const trackedFiles = trackedResult.status === 0 ? trackedResult.stdout.split("\0").filter(Boolean) : [];
+    // A managed DIRECTORY (a receipted skill dir) never appears in ls-files
+    // output itself — only files under it do — so membership alone would read
+    // every tracked skill dir as untracked, matching neither the old
+    // `--error-unmatch` semantics nor reality (review on KNODIN-39). The output
+    // is already limited to the managed pathspecs, so the prefix scan is tiny.
+    const isTrackedManaged = (relative) => trackedFiles.includes(relative) || trackedFiles.some((file) => file.startsWith(`${relative}/`));
+    const trackedManaged = paths.filter(isTrackedManaged);
+    // Ignored paths need no "add to .git/info/exclude" advice: the instruction
+    // previously fired for every present, untracked, knodin-looking file whether
+    // or not the exclude entry already existed (KNODIN-40). One batched
+    // check-ignore answers for all of them; a non-zero status just means none
+    // are ignored.
+    const ignoredPaths = new Set();
+    const untrackedPresent = paths.filter((relative) => !isTrackedManaged(relative) && fs.existsSync(path.join(repo, relative)));
+    if (untrackedPresent.length > 0) {
+        const checkIgnore = run("git", ["-C", repo, "check-ignore", "-z", "--stdin"], {
+            input: `${untrackedPresent.join("\0")}\0`,
+        });
+        for (const relative of checkIgnore.stdout.split("\0").filter(Boolean))
+            ignoredPaths.add(relative);
+    }
+    // Guarding on trackedManaged (not the raw ls-files output) matters: with no
+    // tracked managed paths, `git diff --` with an empty pathspec list would
+    // diff the entire repository (review on KNODIN-39).
+    const diffSections = [];
+    if (trackedManaged.length > 0) {
+        const batchedDiff = run("git", [
+            "-C",
+            repo,
+            "diff",
+            "--no-ext-diff",
+            "--unified=3",
+            "--",
+            ...trackedManaged,
+        ]);
+        if (batchedDiff.status === 0 && batchedDiff.stdout) {
+            for (const section of batchedDiff.stdout.split(/^(?=diff --git )/m)) {
+                const header = /^diff --git a\/(.+) b\//.exec(section);
+                if (header?.[1])
+                    diffSections.push({ file: header[1], section });
+            }
+        }
+    }
+    // A managed directory owns every section for files beneath it; a managed
+    // file owns only its own. This mirrors what the old per-path `git diff -- p`
+    // returned for each shape.
+    const diffFor = (relative) => diffSections
+        .filter(({ file }) => file === relative || file.startsWith(`${relative}/`))
+        .map(({ section }) => section)
+        .join("");
     return paths
         .map((relative) => {
         const absolute = path.join(repo, relative);
         const present = fs.existsSync(absolute);
-        const trackedResult = run("git", ["-C", repo, "ls-files", "--error-unmatch", "--", relative]);
-        const tracked = trackedResult.status === 0;
-        const diffResult = tracked
-            ? run("git", ["-C", repo, "diff", "--no-ext-diff", "--unified=3", "--", relative])
-            : { status: 0, stdout: "", stderr: "" };
+        const tracked = isTrackedManaged(relative);
+        const diffResult = { status: 0, stdout: diffFor(relative), stderr: "" };
         const receipted = fs.existsSync(path.join(absolute, ".knodin-managed.json"));
         let entryOwned = false;
         if (present && !receipted) {
@@ -195,7 +248,7 @@ function managedConfigurationRemediation(repo, run) {
             instructions.push(`Review the diff, then restore manually with: git restore --source=HEAD -- ${relative}`);
         if (!tracked && receipted)
             instructions.push(`Review the Knodin receipt, then remove manually if unwanted: ${relative}`);
-        if (!tracked && present && (receipted || entryOwned))
+        if (!tracked && present && (receipted || entryOwned) && !ignoredPaths.has(relative))
             instructions.push(`To retain it locally without committing, add ${relative} to .git/info/exclude manually.`);
         return {
             path: relative,

package/dist/src/engine/index.js

@@ -1728,6 +1728,34 @@ function createLanguageMemo() {
  * `isLineComment` below, which also requires the `//` prefix.
  */
 const LINE_COMMENT_NODE_TYPES = new Set(["comment", "line_comment", "hash_comment"]);
+/**
+ * Repo-relative files that reference `symbol` and are test files, read from raw
+ * reference rows rather than from resolved callers.
+ *
+ * Resolved callers cannot answer this. A call inside an anonymous callback --
+ * `it("...", () => { target() })`, which is how essentially all test code is
+ * written -- has no enclosing NAMED symbol, so it is stored with a null
+ * `callerSymbol` and every caller-resolution path drops it. Measured on this
+ * repository: 29,158 of 31,467 references from test files (92.7%) have a null
+ * caller, against 390 of 18,399 (2.1%) from production files. So a coverage
+ * question answered from callers is roughly 93% blind in exactly the files it is
+ * asking about, and reported `untested: true` for 642 symbols that have tests
+ * (KNODIN-36).
+ *
+ * The reference row itself carries `callerFile`, which is all this question
+ * needs. Attributing the call to the file instead would be the other repair, and
+ * `call-graph.spec.ts` deliberately forbids it: a file path must never appear as
+ * a caller. So the fix belongs here, at the question, not in the graph.
+ *
+ * Shared by `explain`'s `untested`, `tests_for`, and `detectKnowledgeGaps` so the
+ * definition of "covered by a test" cannot drift between them.
+ */
+function testCallerFilesFor(db, symbol, relativeFile) {
+    const statement = db.query('SELECT DISTINCT callerFile FROM "references" WHERE calleeSymbol = ? AND (calleeFile = ? OR calleeFile IS NULL)');
+    const rows = statement.all(symbol, relativeFile);
+    statement.finalize();
+    return rows.map((row) => row.callerFile).filter((file) => isTestFilePath(file));
+}
 /** Clean up and format comment/docstring blocks in JavaScript/TypeScript. */
 function getPrecedingComment(node) {
     let target = node;
@@ -8199,7 +8227,7 @@ const freshnessChecks = new Map();
  * Work counters for the guard. Tests assert its cost in *invocations*, which is
  * deterministic, rather than in wall-clock milliseconds, which is flaky.
  */
-const freshnessStats = { probes: 0, reconciles: 0, cacheHits: 0 };
+const freshnessStats = { probes: 0, reconciles: 0, cacheHits: 0, probeOverflows: 0 };
 /**
  * Paths the live watcher for `repoPath` currently has registered, flattened to
  * repo-relative form. Empty when no watcher is running (test mode, or after
@@ -8270,6 +8298,7 @@ export function resetFreshnessStats() {
     freshnessStats.probes = 0;
     freshnessStats.reconciles = 0;
     freshnessStats.cacheHits = 0;
+    freshnessStats.probeOverflows = 0;
     freshnessProbes.clear();
 }
 /**
@@ -8288,10 +8317,19 @@ function gitWorkTreeProbe(repoPath) {
             cwd: repoPath,
             encoding: "utf-8",
             stdio: ["pipe", "pipe", "ignore"],
+            // Node's default 1 MB maxBuffer holds only a few thousand dirty
+            // porcelain lines; a large dirty tree then threw here and silently
+            // demoted the probe to the bounded mtime fallback (KNODIN-39).
+            maxBuffer: 64 * 1024 * 1024,
         })
             .split("\n");
     }
-    catch {
+    catch (error) {
+        // An overflow is a degradation worth attributing — the fallback path is
+        // bounded and can only answer "unknown" — so it is counted where the perf
+        // harness and tests can see it, unlike a plain not-a-git-repo failure.
+        if (error.code === "ENOBUFS")
+            freshnessStats.probeOverflows += 1;
         return null;
     }
     const head = lines[0]?.trim();
@@ -12449,7 +12487,20 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 })
                 : [];
             const allBlastFiles = Array.from(new Set(allCallers.map((c) => c.filePath)));
-            const untested = !allCallers.some((c) => isTestFilePath(c.filePath));
+            // Asked of raw reference rows, not of resolved callers: a test that calls
+            // this symbol from inside an anonymous `it(...)` callback has no caller
+            // symbol and is invisible to `allCallers` (KNODIN-36). `untested: true`
+            // is a positive assertion with no zero-count to invite doubt, so it has
+            // to be answered from the evidence that actually exists.
+            // Three values, not two. Without the defining repository's database this
+            // question cannot be answered, and the previous fallback -- guessing from
+            // resolved callers -- is precisely the collapse that made this field
+            // wrong in the first place: it turned "cannot tell" into a confident
+            // `true`. `untested` is now simply absent when the evidence is absent,
+            // so a caller reading it gets a fact or nothing, never a guess.
+            const untested = targetDb
+                ? testCallerFilesFor(targetDb, primaryDef.name, primaryDef.filePath).length === 0
+                : undefined;
             const minimal = detailLevel === "minimal";
             const cap = minimal ? 25 : 200;
             const truncated = allCallers.length > cap ||
@@ -15459,6 +15510,60 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         seen.add(key);
                         rows.push({ symbol: r.symbol, file, line: r.lineNumber });
                     }
+                    // Resolved callers miss almost every real test. A call inside an
+                    // anonymous `it(...)` callback has no enclosing named symbol, so it
+                    // carries a null `callerSymbol` and `findCallersFederated` drops it
+                    // (92.7% of this repository's test-file references, against 2.1% of
+                    // production ones). Reading the raw rows recovers them (KNODIN-36).
+                    //
+                    // These rows carry no caller name because there genuinely is none,
+                    // and inventing one -- the file path, or the enclosing `describe`
+                    // title -- would put a non-symbol in a `symbol` field that
+                    // `call-graph.spec.ts` explicitly forbids. `symbol` is therefore
+                    // omitted and the file and line carry the answer, which is what the
+                    // question asked for anyway: which test covers this.
+                    for (const repo of allRepos) {
+                        if (defFile && repo.path !== defRepo)
+                            continue;
+                        // MIN(line) grouped by file, not DISTINCT(file, line). The rows are
+                        // deduped by file below, so a plain DISTINCT would leave SQLite free
+                        // to hand back whichever line its query plan reached first when a
+                        // test file references the symbol more than once -- a value that can
+                        // change between runs and plans, which is a flaky test waiting to be
+                        // written. The first reference is both stable and the more useful
+                        // one to report.
+                        // With no defining file the file filter is dropped rather than bound
+                        // to "", which would degrade the clause to `calleeFile IS NULL` and
+                        // silently discard every reference that does carry a file -- turning
+                        // "I do not know where this is defined" into "it is defined nowhere",
+                        // and under-reporting coverage for exactly the symbols we know least
+                        // about (ADR 008). findCallersFederated omits the filter in the same
+                        // situation; these two must not disagree.
+                        const anonymous = defFile
+                            ? (() => {
+                                const stmt = repo.db.query('SELECT callerFile, MIN(line) AS line FROM "references" WHERE calleeSymbol = ? AND (calleeFile = ? OR calleeFile IS NULL) AND callerSymbol IS NULL GROUP BY callerFile ORDER BY callerFile');
+                                const out = stmt.all(target, defFile);
+                                stmt.finalize();
+                                return out;
+                            })()
+                            : (() => {
+                                const stmt = repo.db.query('SELECT callerFile, MIN(line) AS line FROM "references" WHERE calleeSymbol = ? AND callerSymbol IS NULL GROUP BY callerFile ORDER BY callerFile');
+                                const out = stmt.all(target);
+                                stmt.finalize();
+                                return out;
+                            })();
+                        for (const row of anonymous) {
+                            const file = formatPath(repo.path, row.callerFile);
+                            if (!isTestFilePath(file))
+                                continue;
+                            const key = `|${file}`;
+                            if (seen.has(key))
+                                continue;
+                            seen.add(key);
+                            rows.push({ file, line: row.line });
+                        }
+                    }
+                    rows.sort((a, b) => (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0));
                     return finish(rows);
                 }
                 case "rename_preview": {

package/dist/src/init.js

@@ -7,7 +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 { stableInterpreterCandidates } 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";
@@ -434,18 +434,33 @@ 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(" ");
-    // Recorded through `stableInterpreterPath` so a Homebrew interpreter is
+    // Recorded through `stableInterpreterCandidates` 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));
+    // path Node reports (EASFDC-8497), and so the script carries an ordered list
+    // of stable runtimes (version-manager shims, Homebrew opt paths) that engage
+    // only once the recorded path is dead. Version-manager installs (mise, nvm,
+    // fnm, asdf, volta) delete their versioned directories on upgrade exactly
+    // like Homebrew's Cellar, and no eager rewrite exists for them — the shim
+    // resolves per-directory configuration, so promoting it while the recorded
+    // path still works could silently switch runtimes (KNODIN-38).
+    const resolution = stableInterpreterCandidates(interpreter ?? process.execPath);
+    const preferred = shellQuote(resolution.preferred);
+    const fallbackBlock = resolution.fallbacks.length > 0
+        ? String.raw `if [ ! -x "$KNODIN_NODE" ]; then
+  for KNODIN_NODE_CANDIDATE in ${resolution.fallbacks.map(shellQuote).join(" ")}; do
+    if [ -x "$KNODIN_NODE_CANDIDATE" ]; then
+      KNODIN_NODE="$KNODIN_NODE_CANDIDATE"
+      break
+    fi
+  done
+fi
+`
+        : "";
     return String.raw `#!/bin/sh
 # knodin packaged background refresh. Generated by knodin init.
 set -u
 KNODIN_NODE=${preferred}
-if [ ! -x "$KNODIN_NODE" ]; then
+${fallbackBlock}if [ ! -x "$KNODIN_NODE" ]; then
   KNODIN_NODE="$(command -v node 2>/dev/null || true)"
   # No interpreter at all: fall through to the recorded path so the failure is
   # the existing loud "not found", not a silent no-op.
@@ -954,12 +969,34 @@ function withoutManagedExcludeBlock(content) {
         after += 1;
     return `${content.slice(0, start > 0 ? start - 1 : 0)}\n${content.slice(after)}`;
 }
-async function excludeUntrackedPaths(repo, candidates) {
-    const safe = [...new Set(candidates)]
-        .filter((candidate) => !isTracked(repo, candidate))
-        .sort(compareBytes);
-    if (safe.length === 0)
+/** The entries currently inside the knodin-owned exclude block, verbatim. */
+function managedExcludeBlockEntries(content) {
+    let start = content.indexOf(EXCLUDE_BLOCK_START);
+    while (start > 0 && content[start - 1] !== "\n")
+        start = content.indexOf(EXCLUDE_BLOCK_START, start + 1);
+    if (start < 0)
         return [];
+    const end = content.indexOf(EXCLUDE_BLOCK_END, start + EXCLUDE_BLOCK_START.length);
+    if (end < 0)
+        return [];
+    return content
+        .slice(start + EXCLUDE_BLOCK_START.length, end)
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+/**
+ * MERGES into the managed block rather than rewriting it from `candidates`
+ * alone. Rewriting was the SalesforceCI regression (KNODIN-40): init calls this
+ * up to twice per run with different candidate lists, so the hook-manager pass
+ * erased the agent-config entries written moments earlier, and a later bare
+ * `knodin init` shrank the block to `.knodin/` — leaving knodin-owned files as
+ * untracked dirt in `git status`. Entries already in the block survive as long
+ * as they remain untracked; only a tracked path (or an explicit
+ * `removeManagedExcludes`, which team and cli-only transitions call first) can
+ * remove one.
+ */
+async function excludeUntrackedPaths(repo, candidates) {
     const rawExcludePath = runGit(repo, ["rev-parse", "--git-path", "info/exclude"]).trim();
     const excludePath = path.isAbsolute(rawExcludePath)
         ? rawExcludePath
@@ -972,6 +1009,11 @@ async function excludeUntrackedPaths(repo, candidates) {
         if (error.code !== "ENOENT")
             throw error;
     }
+    const safe = [...new Set([...managedExcludeBlockEntries(existing), ...candidates])]
+        .filter((candidate) => !isTracked(repo, candidate))
+        .sort(compareBytes);
+    if (safe.length === 0)
+        return [];
     const startMarker = "# knodin:start";
     const endMarker = "# knodin:end";
     const outside = withoutManagedExcludeBlock(existing);
@@ -983,6 +1025,40 @@ async function excludeUntrackedPaths(repo, candidates) {
     await fs.promises.writeFile(excludePath, `${prefix}${block}`, "utf-8");
     return owned;
 }
+/**
+ * Personal-scope files whose exclude entry is worth restoring during repair.
+ * `.mcp.json` is absent deliberately: personal scope removes it rather than
+ * writing it, and `.vscode/mcp.json` only exists when copilot was configured.
+ */
+const PERSONAL_AGENT_CONFIG_PATHS = [
+    ".codex/config.toml",
+    ".gemini/settings.json",
+    ".agents/mcp_config.json",
+    ".vscode/mcp.json",
+];
+/**
+ * Restore managed exclude entries a whole-block rewrite erased (KNODIN-40).
+ * Candidates are limited to files that exist, mention knodin, and belong to a
+ * personal-scope integration — repair must never start excluding files it
+ * cannot show it owns. The merge inside `excludeUntrackedPaths` keeps whatever
+ * else the block already carries (a hook manager's local config, for one).
+ */
+async function reconcileManagedExcludes(repo) {
+    if (readRepositoryIntegrationConfig(repo)?.scope !== "personal")
+        return [];
+    const candidates = [
+        ...(isTracked(repo, ".knodin") ? [] : [".knodin/"]),
+        ...PERSONAL_AGENT_CONFIG_PATHS.filter((relative) => {
+            try {
+                return fs.readFileSync(path.join(repo, relative), "utf-8").includes("knodin");
+            }
+            catch {
+                return false;
+            }
+        }),
+    ];
+    return candidates.length > 0 ? excludeUntrackedPaths(repo, candidates) : [];
+}
 async function removeManagedExcludes(repo) {
     const rawExcludePath = runGit(repo, ["rev-parse", "--git-path", "info/exclude"]).trim();
     const excludePath = path.isAbsolute(rawExcludePath)
@@ -1526,12 +1602,14 @@ export async function repairLifecycleRouting(repoPath, options) {
         }
         const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath, lifecycleLease.token);
         await fs.promises.rm(path.join(knodinHooksDir, HOOK_FAILURE_FILE), { force: true });
+        const excluded = await reconcileManagedExcludes(resolvedRepo);
         return {
             backgroundIndexer: ".knodin/hooks/background-index.sh",
             hooksDirectory: path.relative(resolvedRepo, hooksDir) || ".",
             gitHooks: [...HOOK_NAMES],
             hookManagerIntegration,
             lifecycleRefresh,
+            excluded,
             configurationChanges: [],
         };
     }

package/dist/src/lifecycle-health.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { compareBytes } from "./compare.js";
 import { isMirror, resolveDbPath } from "./engine/state-paths.js";
 import { inspectLefthookIntegration, isActiveLefthookHook } from "./hook-manager-integration.js";
+import { resolveHealthyInterpreter } from "./node-runtime.js";
 const MANAGED_MARKER = "KNODIN MANAGED HOOK";
 const HOOK_NAMES = ["post-commit", "post-checkout", "post-merge", "post-rewrite"];
 const HOOK_FAILURE_FILE = "last-refresh-failure";
@@ -204,6 +205,44 @@ function pinnedInterpreterWithoutFallback(backgroundScriptPath) {
         return null;
     return /'(\/[^']*\/bin\/node)'/.exec(contents)?.[1] ?? null;
 }
+/**
+ * Rewrite a dead recorded interpreter to a proven-healthy stable one, in place.
+ *
+ * Detection without repair made this a recurring chore: every `brew upgrade
+ * node` (or mise/nvm upgrade) killed the recorded path, health reported
+ * degraded, and the user ran `repair --lifecycle` by hand — which re-recorded
+ * the repairing process's own versioned path and planted the next failure
+ * (KNODIN-38). The fix is narrow by design: only the quoted interpreter path
+ * changes, the replacement must exist AND report a supported Node version
+ * (`resolveHealthyInterpreter` executes it), and the write is atomic
+ * (tmp+rename, mode preserved) so a hook running concurrently keeps the copy
+ * it already read.
+ *
+ * Returns null — leaving the degraded report exactly as it was — when no
+ * replacement can be proven healthy, when the script cannot be written, or
+ * when the replacement contains a single quote the recorded format cannot
+ * carry. Degraded-but-honest beats healed-but-guessed.
+ */
+export function selfHealRecordedInterpreter(backgroundScriptPath, recorded, resolve = resolveHealthyInterpreter) {
+    const replacement = resolve(recorded);
+    if (!replacement || replacement.includes("'"))
+        return null;
+    const temporary = `${backgroundScriptPath}.self-heal.${process.pid}`;
+    try {
+        const contents = fs.readFileSync(backgroundScriptPath, "utf8");
+        const updated = contents.split(`'${recorded}'`).join(`'${replacement}'`);
+        if (updated === contents)
+            return null;
+        const mode = fs.statSync(backgroundScriptPath).mode & 0o777;
+        fs.writeFileSync(temporary, updated, { mode });
+        fs.renameSync(temporary, backgroundScriptPath);
+        return { from: recorded, to: replacement };
+    }
+    catch {
+        fs.rmSync(temporary, { force: true });
+        return null;
+    }
+}
 function readRefreshFailure(repo) {
     const failurePath = path.join(repo, ".knodin", "hooks", HOOK_FAILURE_FILE);
     if (!fs.existsSync(failurePath))
@@ -216,7 +255,15 @@ function readRefreshFailure(repo) {
         return "last background refresh failed";
     }
 }
-/** Read-only proof that committed Git activity can still reach knodin's indexer. */
+/**
+ * Proof that committed Git activity can still reach knodin's indexer.
+ *
+ * Read-only, with one deliberate exception: a recorded interpreter that no
+ * longer exists is rewritten in place when a proven-healthy replacement
+ * resolves (`selfHealRecordedInterpreter`), because reporting that condition
+ * without fixing it made every Node upgrade a manual `repair --lifecycle`
+ * chore (KNODIN-38).
+ */
 export function inspectLifecycleHealth(repoPath) {
     const repo = path.resolve(repoPath);
     // A mirror deliberately has no lifecycle hooks: its working tree is replaced
@@ -240,6 +287,7 @@ export function inspectLifecycleHealth(repoPath) {
             lastError: null,
             hookManager: null,
             routing: "unavailable",
+            interpreterSelfHeal: null,
         };
     }
     if (!fs.existsSync(resolveDbPath(repo))) {
@@ -257,6 +305,7 @@ export function inspectLifecycleHealth(repoPath) {
             lastError: null,
             hookManager: null,
             routing: "unavailable",
+            interpreterSelfHeal: null,
         };
     }
     let hooksDirectory;
@@ -278,6 +327,7 @@ export function inspectLifecycleHealth(repoPath) {
             lastError: null,
             hookManager: null,
             routing: "unavailable",
+            interpreterSelfHeal: null,
         };
     }
     const { activeHooks, missingHooks, hookManager, routing } = inspectManagedHooks(repo, hooksDirectory);
@@ -286,7 +336,16 @@ 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;
+    // A dead recorded interpreter is repaired here, not just reported: the
+    // replacement must prove itself healthy, and when nothing does the original
+    // degraded report stands untouched (KNODIN-38).
+    let staleInterpreter = backgroundReady ? recordedInterpreterIfMissing(background) : null;
+    let interpreterSelfHeal = null;
+    if (staleInterpreter) {
+        interpreterSelfHeal = selfHealRecordedInterpreter(background, staleInterpreter);
+        if (interpreterSelfHeal)
+            staleInterpreter = null;
+    }
     if (staleInterpreter)
         issues.push(`background indexer records a Node interpreter that no longer exists (${staleInterpreter}); run \`knodin repair --lifecycle\` to rewrite the hook`);
     // Reported even while that interpreter still exists. The failure is latent
@@ -315,6 +374,7 @@ export function inspectLifecycleHealth(repoPath) {
         lastError,
         hookManager,
         routing,
+        interpreterSelfHeal,
     };
 }
 /** Merge graph and refresh-path health without reporting absent evidence as healthy. */

package/dist/src/node-runtime.js

@@ -188,3 +188,99 @@ export function stableInterpreterPath(executable, exists = (candidate) => fs.exi
     const candidate = `${prefix}/opt/${formula}/${remainder}`;
     return exists(candidate) ? candidate : executable;
 }
+/**
+ * The version manager's stable shim for a versioned install path, when the
+ * manager has one. mise, asdf, and volta shims survive `<manager> upgrade`
+ * because the manager repoints them; the versioned install directory the
+ * recorded `execPath` names does not. nvm has no on-disk shim (it is a shell
+ * function), so an nvm path yields nothing here.
+ */
+function versionManagerShim(executable) {
+    const mise = /^(.*)\/installs\/node\/[^/]+\/bin\/node$/.exec(executable);
+    if (mise)
+        return `${mise[1]}/shims/node`;
+    const asdf = /^(.*)\/installs\/nodejs\/[^/]+\/bin\/node$/.exec(executable);
+    if (asdf)
+        return `${asdf[1]}/shims/node`;
+    const volta = /^(.*)\/tools\/image\/node\/[^/]+\/bin\/node$/.exec(executable);
+    if (volta)
+        return `${volta[1]}/bin/node`;
+    const fnm = /^(.*)\/node-versions\/[^/]+\/installation\/bin\/node$/.exec(executable);
+    if (fnm)
+        return `${fnm[1]}/aliases/default/bin/node`;
+    return null;
+}
+/**
+ * A version-stable interpreter plus an ordered fallback list for anything that
+ * records an interpreter path for later (the background refresh hook).
+ *
+ * The preferred path stays EXACT except for the Homebrew Cellar→opt rewrite,
+ * which is the same binary by construction. A version-manager shim is
+ * deliberately NOT promoted to preferred while the recorded path still exists:
+ * shims resolve per-directory configuration, so an eager rewrite could
+ * silently switch which runtime executes. Shims belong in the fallback list,
+ * where they only engage once the recorded path is dead — at which point any
+ * working stable runtime beats a vanished one.
+ */
+export function stableInterpreterCandidates(executable, options = {}) {
+    const exists = options.exists ?? ((candidate) => fs.existsSync(candidate));
+    const env = options.env ?? process.env;
+    const home = options.homeDirectory ?? os.homedir();
+    const preferred = stableInterpreterPath(executable, exists);
+    const absolute = (value) => value && path.isAbsolute(value) ? value : undefined;
+    const miseRoot = absolute(env.MISE_DATA_DIR) ?? path.join(home, ".local", "share", "mise");
+    const asdfRoot = absolute(env.ASDF_DATA_DIR) ?? path.join(home, ".asdf");
+    const voltaRoot = absolute(env.VOLTA_HOME) ?? path.join(home, ".volta");
+    const fnmRoot = absolute(env.FNM_DIR);
+    // KNODIN_NODE_RUNTIME leads: it is the user's explicit override, and
+    // `runtimeCandidates` above treats it as highest priority — the derived shim
+    // must not outrank it once the recorded path is dead. A non-absolute value
+    // is skipped rather than thrown here (the launcher already throws for it at
+    // startup): this derivation runs inside status/doctor health checks, where
+    // a bad environment variable must degrade a fallback list, not the command.
+    const ordered = [
+        absolute(env.KNODIN_NODE_RUNTIME),
+        versionManagerShim(executable),
+        "/opt/homebrew/opt/node@24/bin/node",
+        "/opt/homebrew/opt/node/bin/node",
+        "/usr/local/opt/node@24/bin/node",
+        "/usr/local/opt/node/bin/node",
+        path.join(miseRoot, "shims", "node"),
+        path.join(home, ".mise", "shims", "node"),
+        path.join(asdfRoot, "shims", "node"),
+        path.join(voltaRoot, "bin", "node"),
+        fnmRoot ? path.join(fnmRoot, "aliases", "default", "bin", "node") : null,
+    ];
+    const fallbacks = [];
+    const seen = new Set([preferred, executable]);
+    for (const candidate of ordered) {
+        if (!candidate || seen.has(candidate) || !exists(candidate))
+            continue;
+        seen.add(candidate);
+        fallbacks.push(candidate);
+        if (fallbacks.length >= 4)
+            break;
+    }
+    return { preferred, fallbacks };
+}
+/**
+ * A working replacement for a recorded interpreter that no longer exists, or
+ * null when none can be proven healthy. Candidates are the stable derivation
+ * of the dead path plus the stable fallback list; each is executed to confirm
+ * it actually reports a supported Node version — a shim can resolve to an
+ * unsupported runtime through per-directory configuration, and recording an
+ * unverified path would trade one dead interpreter for another.
+ */
+export function resolveHealthyInterpreter(deadExecutable, options = {}) {
+    const exists = options.exists ?? ((candidate) => fs.existsSync(candidate));
+    const probe = options.probe ?? probeNodeVersion;
+    const { preferred, fallbacks } = stableInterpreterCandidates(deadExecutable, options);
+    const candidates = preferred === deadExecutable ? fallbacks : [preferred, ...fallbacks];
+    for (const candidate of candidates) {
+        if (!exists(candidate))
+            continue;
+        if (isSupported(probe(candidate)))
+            return candidate;
+    }
+    return null;
+}

package/dist/src/output-telemetry.js

@@ -7,6 +7,17 @@ import { resolveDbPath } from "./engine/state-paths.js";
 import { summarizeAdoption } from "./session-telemetry.js";
 export const TELEMETRY_TOKENIZER = "gpt-tokenizer@3.4.0:o200k_base";
 export const countOutputTokens = (value) => encode(value).length;
+/** Retrieval stages the engine can report; anything else is dropped. */
+const RETRIEVAL_ROUTE_STEPS = new Set([
+    "stable-identity",
+    "exact-name",
+    "exact-path",
+    "lexical",
+    "bounded-graph",
+    "embeddings",
+]);
+/** Embedding-coverage states the engine can report; anything else is dropped. */
+const SEMANTIC_READINESS_STATES = new Set(["ready", "partial", "absent"]);
 export const DEFAULT_TELEMETRY_RETENTION_DAYS = 30;
 const DEFAULT_INPUT = ".knodin-telemetry.jsonl";
 function lineCount(value) {
@@ -105,6 +116,28 @@ export function measureOutput(options) {
     const status = typeof options.output.status === "string" ? options.output.status : undefined;
     const availability = options.output.availability;
     const freshness = options.output.freshness;
+    // Retrieval-quality fields, lifted so a repository where knodin underperforms
+    // is diagnosable from a shared bundle instead of from a hand-written field
+    // report (KNODIN-37). All four already travel in the response and all four are
+    // source-free metadata, so this persists nothing the privacy contract forbids.
+    //
+    // `semanticReadiness` is the most diagnostic of them: a partially embedded
+    // index returns confident SHORT answers, which is indistinguishable from the
+    // query being wrong unless the readiness is recorded beside the result.
+    const retrieval = options.output.retrieval;
+    const retrievalRoute = Array.isArray(retrieval?.route)
+        ? retrieval.route.filter((step) => typeof step === "string")
+        : undefined;
+    const embeddingsUsed = typeof retrieval?.embeddingsUsed === "boolean" ? retrieval.embeddingsUsed : undefined;
+    const semanticReadiness = typeof options.output.semanticReadiness === "string"
+        ? options.output.semanticReadiness
+        : undefined;
+    const results = options.output.results;
+    const resultCount = Array.isArray(results)
+        ? results.length
+        : typeof options.output.count === "number"
+            ? options.output.count
+            : undefined;
     const fidelity = options.output.fidelity;
     const database = resolveDbPath(fs.realpathSync(options.repo));
     const latencyMs = Math.round((performance.now() - options.startedAt) * 100) / 100;
@@ -137,6 +170,15 @@ export function measureOutput(options) {
         compressionFidelity,
         confidence: baseline ? "measured" : "unavailable",
         truncated: options.truncated,
+        // Non-empty or absent, never `[]`. An empty route asserts that no retrieval
+        // stage ran, which is a claim about the query; a route that is unknown or
+        // wholly unreadable is the absence of one. The sanitizer downstream makes
+        // the same distinction, and a record that collapsed it here would hand the
+        // sanitizer a falsehood to faithfully preserve (ADR 008).
+        ...(retrievalRoute && retrievalRoute.length > 0 ? { retrievalRoute } : {}),
+        ...(embeddingsUsed !== undefined ? { embeddingsUsed } : {}),
+        ...(semanticReadiness ? { semanticReadiness } : {}),
+        ...(resultCount !== undefined ? { resultCount } : {}),
         detailMode: options.detailMode,
         tokenizer: TELEMETRY_TOKENIZER,
         schemaTokens: options.schemaTokens,
@@ -232,7 +274,12 @@ export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/te
         sessionEvents: sessionEvents.length,
     };
 }
-function sanitizeTelemetryRecord(record) {
+/**
+ * Exported for the retrieval-quality spec: the allowlist is the guarantee that
+ * an unexpected field never reaches a shareable file, and that guarantee is
+ * only worth anything if it is tested directly rather than through a caller.
+ */
+export function sanitizeTelemetryRecord(record) {
     return {
         schemaVersion: record.schemaVersion,
         at: record.at,
@@ -252,6 +299,38 @@ function sanitizeTelemetryRecord(record) {
         compressionFidelity: record.compressionFidelity,
         confidence: record.confidence,
         truncated: record.truncated,
+        // Retrieval-quality fields (KNODIN-37). Validated rather than copied: the
+        // allowlist is the reason an unexpected field can never reach the file, and
+        // a new entry that trusts its input would quietly defeat that. Route steps
+        // are constrained to a known vocabulary and the array is bounded, so a
+        // malformed response cannot smuggle arbitrary strings into a shareable
+        // record.
+        // Omitted when nothing survives the allowlist, not emitted as `[]`. An
+        // empty array reads as "no retrieval stage ran", which is a fact; a route
+        // whose every step was unrecognised is the absence of a readable fact, and
+        // the two must not share a representation (ADR 008). Caught in review of
+        // this very change, which is the telemetry meant to diagnose exactly this
+        // class of confusion.
+        ...(() => {
+            if (!Array.isArray(record.retrievalRoute))
+                return {};
+            const route = record.retrievalRoute
+                .filter((step) => RETRIEVAL_ROUTE_STEPS.has(step))
+                .slice(0, 8);
+            return route.length > 0 ? { retrievalRoute: route } : {};
+        })(),
+        ...(typeof record.embeddingsUsed === "boolean"
+            ? { embeddingsUsed: record.embeddingsUsed }
+            : {}),
+        ...(typeof record.semanticReadiness === "string" &&
+            SEMANTIC_READINESS_STATES.has(record.semanticReadiness)
+            ? { semanticReadiness: record.semanticReadiness }
+            : {}),
+        ...(typeof record.resultCount === "number" &&
+            Number.isInteger(record.resultCount) &&
+            record.resultCount >= 0
+            ? { resultCount: record.resultCount }
+            : {}),
         detailMode: record.detailMode,
         tokenizer: record.tokenizer,
         schemaTokens: record.schemaTokens,

package/docs/releases/0.12.1.md

@@ -0,0 +1,98 @@
+# knodin 0.12.1
+
+A P1 correctness fix, a field made honest, and telemetry that lets a badly
+performing repository explain itself. No schema change and no re-index.
+
+## `explain` said "untested" about symbols that have tests
+
+`explain` reported `untested: true`, and `tests_for` returned `count: 0`, for
+symbols with dedicated unit tests — on a healthy, fresh graph.
+
+Test code lives almost entirely inside anonymous callbacks passed to `it(...)`
+and `describe(...)`. Such a call has no enclosing *named* symbol, so it is
+recorded with a null caller and every caller-resolution path drops it. Measured
+on this repository: **29,158 of 31,467 references from test files (92.7%) had no
+caller symbol, against 390 of 18,399 (2.1%) from production files.** A coverage
+question answered from callers was therefore about 93% blind in exactly the files
+it was asking about, and 642 symbols with real tests reported as untested.
+
+This is the worst shape a wrong answer can take. An empty result invites a second
+look; a confident positive does not. The field was written into a security
+proposal as a precondition blocking a change and reached a pull request before a
+reviewer caught it.
+
+Both questions now read the raw reference rows, which carry the calling file.
+
+Two alternatives were rejected on evidence rather than taste. Attributing the
+call to the *file* would put a non-symbol into a `symbol` field, which a
+checked-in contract forbids outright. Indexing `describe`/`it` titles as symbols
+would add roughly ten thousand rows and perturb statistics, dead-code detection,
+communities, embeddings, and the centrality term added in 0.12.0. Reading the
+rows changes no caller, so search ranking is bit-identical — verified rather than
+assumed.
+
+Rows for anonymous callers carry a file and a line and no symbol, because there
+genuinely is none.
+
+## `untested` is now three-valued
+
+The first version of that fix still collapsed "cannot tell" into a guess: without
+the defining repository's database it inferred from resolved callers, which is
+the same blindness that made the field wrong. `untested` is now simply **absent**
+when the evidence is absent. A caller gets a fact or nothing, never a guess.
+
+The control matters as much as the fix: a genuinely uncovered symbol still
+reports `untested: true`. A field that is never true would be as broken as one
+that is always true, and only that second test tells them apart.
+
+## Telemetry can now explain a repository where knodin underperforms
+
+knodin has been reported as performing poorly in other people's repositories,
+and there was no way to find out why without someone writing a field report by
+hand. The signals that explain it already travelled in every response and were
+being discarded.
+
+Four are now persisted with the existing opt-in local telemetry:
+`retrievalRoute`, `embeddingsUsed`, `semanticReadiness`, and `resultCount`.
+
+`semanticReadiness` is the most diagnostic of them. A partially embedded index
+returns confident *short* answers, which is indistinguishable from a poorly
+phrased query unless the readiness is recorded beside the result.
+
+All four are source-free metadata, so the privacy contract is unchanged: no
+source, no query text, no paths, no identities, still opt-in, still local-only,
+still no transport. Query *shape* — the remaining diagnostic gap — is
+deliberately excluded, because persisting query text would falsify the
+no-source-egress property the product is built on.
+
+The sanitizer's allowlist gained these fields with validation rather than
+pass-through. That allowlist is the only reason an unexpected field cannot reach
+a shareable file, and an entry that trusted its input would quietly defeat it.
+
+## A design principle, written down
+
+ADR 008 records what eleven defects across 0.12.0 and this release turned out to
+have in common:
+
+> A check that collapses "no" and "don't know" into a single answer will
+> eventually return the wrong one, and it will do so confidently.
+
+`untested: true`, `count: 0` for a misspelling, a review answering a different
+range, staleness defaulting to `fresh` when it was missing. Two instances in the
+ADR are deliberately not knodin bugs — another product's CI gate reporting a
+network timeout as a security advisory, and an agent truncating its own terminal
+output and concluding a remote did not exist. The shape belongs to any predicate
+whose failure path and negative path are the same path.
+
+## Measured and not shipped
+
+Three attempts at the lexical retrieval channel were implemented, measured, and
+reverted: asymmetric token floors, Porter stemming, and grading a partial match
+by how many query words it echoed. On a 44-query real-model benchmark they
+scored 0.7112, 0.7389, and "no measurable difference" against a 0.7635 baseline,
+and **none bought a single point of recall** — including on four queries added
+specifically to favour morphological matching.
+
+The reproductions behind them were sound. The inference was not: a demonstrated
+defect does not imply that removing it is an improvement. The vector channel was
+already carrying what the lexical channel could not see.

package/docs/releases/0.12.2.md

@@ -0,0 +1,88 @@
+# knodin 0.12.2
+
+Three field reports from one very large Salesforce repository (903k files):
+a lifecycle fault that came back after every Node upgrade, a doctor that took
+48 seconds to say so, and a handful of reports that were wrong in ways that
+taught people to ignore them. No schema change and no re-index.
+
+## The interpreter that died on every `brew upgrade node` now heals itself
+
+The background refresh hook records the absolute path of the Node interpreter
+that wrote it. Node reports `process.execPath` as a fully resolved path, so a
+stable `/opt/homebrew/bin/node` was recorded as a versioned Cellar path — and
+mise, nvm, fnm, asdf, and volta versioned installs were recorded verbatim.
+Every Node upgrade deleted that path, health reported "a Node interpreter that
+no longer exists," and the prescribed `repair --lifecycle` re-recorded the
+repairing process's own versioned path: the fix planted the next failure. This
+loop had no exit, only a chore per upgrade per repository.
+
+Three changes close it:
+
+- **Recording is version-stable where that is safe.** The Homebrew Cellar path
+  is still rewritten to its durable `opt` form (the same binary by
+  construction). A version-manager path stays exact — a shim resolves
+  per-directory configuration, so promoting it while the recorded path still
+  works could silently switch which runtime executes.
+- **The generated script carries an ordered fallback list** — the explicit
+  `KNODIN_NODE_RUNTIME` override first, then the recording manager's shim,
+  then known stable runtimes — so a single dead path never stops refresh.
+- **Health repairs what it detects.** When the recorded interpreter is gone
+  and a replacement both exists and *proves itself* (it is executed and must
+  report a supported Node version), `status` and `doctor` rewrite the one
+  recorded line atomically and say so:
+  `background indexer interpreter self-healed (<old> -> <new>)`. When nothing
+  can be proven healthy, the degraded report stands untouched — degraded but
+  honest beats healed but guessed.
+
+## `doctor` on a 903k-file repository: 48 seconds of redundant evidence
+
+Doctor forced a full deep audit — two complete stat sweeps — on every run,
+ignoring the persisted audit that `status` already trusts, and then spawned
+two git processes per managed configuration path, each `git diff` reloading
+the 903k-entry index. Doctor now audits adaptively exactly as `status` does
+(the persisted-audit path runs the same drift probe, so a stale graph still
+reports stale — accuracy was the constraint, and it is regression-tested),
+with `doctor --deep` keeping the exact audit one flag away. The managed-path
+inspection is one `git ls-files` and one `git diff` for everything, aware
+that a managed *directory* is tracked through the files beneath it and never
+runs a diff with an empty pathspec.
+
+One silent accuracy hazard was found on the way: the working-tree probe used
+Node's default 1 MB buffer for `git status --porcelain`, so a few thousand
+dirty paths overflowed it and quietly demoted freshness checking to the
+bounded mtime fallback. The buffer is now 64 MB and an overflow is counted
+where tests and the perf harness can see it.
+
+## Reports that cried wolf, and one that hid the pack
+
+- **`.git/info/exclude` entries no longer vanish.** The managed exclude block
+  was rewritten from each caller's candidate list alone, so on a lefthook
+  repository the hook-manager pass erased the agent-config entries written
+  moments earlier, and a later bare `knodin init` shrank the block to
+  `.knodin/` — leaving knodin-owned files as permanent untracked dirt in
+  `git status`. The block now merges, and `repair --lifecycle` restores lost
+  entries for personal-scope repositories (only files that exist, mention
+  knodin, and match the receipt scope — repair never excludes what it cannot
+  show it owns).
+- **A machine that never installed backup retention is `not-installed`, not
+  broken.** Doctor reported `attention-required` with
+  `policy-missing-or-invalid` and `receipt-missing-or-invalid` on machines
+  with neither file and zero backups. Absence of both files is a clean state;
+  any on-disk trace — even an unparseable file — still counts as installation
+  evidence and keeps the strict reporting.
+- **Status names every issue, and the right remedy.** A lifecycle-only fault
+  used to print "Run `knodin init`." directly above a line that correctly said
+  `repair --lifecycle` — advice that contradicts itself teaches people to
+  read neither. The remediation now matches the fault, and status lists up to
+  five issues (`+N more`, full list under `--json`) instead of only the first.
+- **Doctor prints its MCP probe once.** One probe backs every client row; the
+  human listing rendered it five times as if five servers had been tested.
+  JSON keeps the per-client shape for compatibility.
+- **Doctor stops telling you to add exclude entries you already have.** The
+  "add to `.git/info/exclude` manually" instruction now consults
+  `git check-ignore` first.
+
+Field verification for the recurring interpreter loop: run
+`knodin repair --lifecycle` once with this version installed; the next Node
+upgrade should self-heal on the first `status` instead of demanding another
+repair.

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "knodin",
-	"version": "0.12.0",
+	"version": "0.12.2",
 	"knodin": {
-		"compatibility": "breaking"
+		"compatibility": "compatible"
 	},
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
@@ -65,6 +65,8 @@
 		"docs/releases/0.10.8.md",
 		"docs/releases/0.11.0.md",
 		"docs/releases/0.12.0.md",
+		"docs/releases/0.12.1.md",
+		"docs/releases/0.12.2.md",
 		"docs/releases/0.3.0.md",
 		"docs/releases/0.4.0.md",
 		"docs/releases/0.4.1.md",