knodin 0.12.1 → 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

@@ -8227,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
@@ -8298,6 +8298,7 @@ export function resetFreshnessStats() {
     freshnessStats.probes = 0;
     freshnessStats.reconciles = 0;
     freshnessStats.cacheHits = 0;
+    freshnessStats.probeOverflows = 0;
     freshnessProbes.clear();
 }
 /**
@@ -8316,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();

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/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,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.12.1",
+	"version": "0.12.2",
 	"knodin": {
 		"compatibility": "compatible"
 	},
@@ -66,6 +66,7 @@
 		"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",