knodin 0.10.0 → 0.10.2

package/dist/bin/cli.js

@@ -27,7 +27,7 @@ import { exportContext, grepPackedArtifact, readPackedArtifact } from "../src/co
 import { clearDiagnostics, collectDiagnostics, diagnosticsStatus, disableDiagnostics, enableDiagnostics, inspectDiagnosticsBundle, persistDiagnosticsPreview, recordDiagnosticFailure, } from "../src/diagnostics.js";
 import { getDocSection, listDocTopics } from "../src/docs-sections.js";
 import { diagnoseInstallation } from "../src/doctor.js";
-import { createEngine, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PATTERNS, } from "../src/engine/index.js";
+import { createEngine, describeThrown, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PATTERNS, } from "../src/engine/index.js";
 import { runSeal } from "../src/engine/seal-command.js";
 import { runSealedQuery } from "../src/engine/sealed-query.js";
 import { resolveDbPath } from "../src/engine/state-paths.js";
@@ -199,10 +199,16 @@ function formatCoverageGaps(skipped) {
     if (byExtension)
         clauses.push(`not indexed: ${byExtension}`);
     const unparsed = formatTally(skipped.unparsedByExtension);
+    // "not parsed", not "parsed but empty". Nothing in this tally was parsed:
+    // it collects files with no tree-sitter grammar, minified sources, and files
+    // whose indexing threw. Calling that "parsed but empty" asserts the parser
+    // looked and found nothing, which is the one thing it did not do — and it
+    // made a real outage unreadable, since a dead wasm module dumped thousands
+    // of never-parsed files into this bucket under a label saying they were fine.
     if (unparsed)
-        clauses.push(`parsed but empty: ${unparsed}`);
+        clauses.push(`not parsed: ${unparsed}`);
     if (skipped.unparsedUnknown)
-        clauses.push("parsed-but-empty tally unavailable — run a full index; this is a lower bound");
+        clauses.push("not-parsed tally unavailable — run a full index; this is a lower bound");
     const count = skipped.unparsedUnknown ? `${skipped.total}+` : `${skipped.total}`;
     return `. Not in graph: ${count} files (${clauses.join("; ")})`;
 }
@@ -2124,17 +2130,27 @@ async function main() {
             const agents = scope === "team" ? [] : integrationAgents(repo);
             const paths = await initializeRepository(repo, {
                 command: runtimeCommand,
-                index: indexOrSeed(engine, KNODIN_SCHEMA_VERSION),
+                // Not `indexOrSeed`: seeding exists for a worktree with no database,
+                // and this command has already refused to run without one. Indexing
+                // the written files directly is the whole point of the narrow scope.
+                index: (target, indexOptions, files) => engine.index(target, files, false, indexOptions),
+                indexScope: "configuration",
                 scope,
                 agents,
                 allowTrackedTransition: true,
                 auditConfigurationChanges: true,
                 configureIntegration: true,
             });
+            const indexed = paths.scopedIndexPaths ?? [];
             result = {
                 status: "success",
                 message: `knodin agent integration changed to ${scope}.`,
-                graphInitialization: "refreshed",
+                // Say what happened. Claiming "refreshed" after touching a few
+                // configuration files misdescribes the graph's state, and did so most
+                // misleadingly on a repository whose graph was in fact empty.
+                graphInitialization: indexed.length === 0
+                    ? "unchanged — no configuration files needed indexing"
+                    : `configuration files indexed (${indexed.length})`,
                 nextAction: "run `knodin status` and reload the configured client",
                 paths,
             };
@@ -2985,7 +3001,7 @@ catch (err) {
             error: err,
         });
         const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
-        console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
+        console.error(`${describeThrown(err)}${correlation}`);
         process.exit(1);
     }
 }

package/dist/src/engine/index.js

@@ -4938,13 +4938,22 @@ async function indexRazorFile(content, relativePath, _repoPath, db) {
     const parser = new Parser();
     parser.setLanguage(language);
     const tree = parser.parse(projected);
-    if (!tree)
+    if (!tree) {
+        parser.delete();
         return;
+    }
     // `filePath` drives the extractor's language-specific branches, so it must
     // look like C#; the rows are persisted against the real Razor path below.
-    const extracted = extractSymbolsAndReferences(tree.rootNode, false, false, "razor-projection.cs");
-    tree.delete();
-    parser.delete();
+    // The `finally` matters: a throw out of the extractor previously leaked both
+    // objects, on exactly the malformed inputs most likely to throw.
+    let extracted;
+    try {
+        extracted = extractSymbolsAndReferences(tree.rootNode, false, false, "razor-projection.cs");
+    }
+    finally {
+        freeQuietly(tree);
+        freeQuietly(parser);
+    }
     // The synthetic wrapper class exists only to make members parseable.
     const definitions = extracted.definitions.filter((def) => def.name !== "__RazorCode");
     db.run("BEGIN TRANSACTION;");
@@ -6178,6 +6187,58 @@ const INDEX_WRITE_BATCH_SIZE = (() => {
     const raw = Number(process.env.KNODIN_INDEX_WRITE_BATCH_SIZE);
     return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 200;
 })();
+/**
+ * True for an Emscripten abort: the wasm module itself calling `exit()`.
+ *
+ * This is categorically different from "this file did not parse" and must never
+ * be handled by a per-file recovery path. The module does not come back — every
+ * subsequent parse, even on a freshly constructed `Parser`, fails with the same
+ * error. Treating it per-file turns one real failure into thousands of
+ * misattributed ones against innocent files, and still reports the run as
+ * successful, so the graph ends up quietly missing everything after the abort.
+ */
+export function isWasmAbort(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.name === "ExitStatus");
+}
+/**
+ * Render any throwable as a message, including one that is not an `Error`.
+ *
+ * `error instanceof Error ? error.message : String(error)` is the reflex, and it
+ * is wrong for exactly the failure this release exists to surface: Emscripten's
+ * `ExitStatus` is a plain object carrying `name`/`message`/`status`, so the
+ * ternary falls through to `String(error)` and prints `[object Object]` —
+ * destroying the diagnosis at the last step, in the CLI's top-level handler and
+ * in the parse worker's hand-serialization alike.
+ */
+export function describeThrown(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "object" && error !== null) {
+        const { name, message } = error;
+        if (typeof message === "string" && message.length > 0)
+            return typeof name === "string" && name.length > 0 ? `${name}: ${message}` : message;
+    }
+    return String(error);
+}
+/**
+ * Free a wasm object without letting the free itself throw.
+ *
+ * Used only where the free sits in a `finally`. If the module has aborted, its
+ * heap is already gone and `delete()` throws too — from a `finally` that
+ * replaces the in-flight error with a second, less informative one, losing the
+ * cause at exactly the moment it matters. There is nothing to reclaim from a
+ * dead module anyway, so dropping that failure loses nothing real.
+ */
+function freeQuietly(target) {
+    try {
+        target.delete();
+    }
+    catch {
+        // Intentionally ignored; see above.
+    }
+}
 /**
  * Read, parse, and extract one file through the generic tree-sitter path.
  *
@@ -6212,40 +6273,78 @@ export async function extractGenericFileForIndex(absolutePath, relativePath, rep
         tree = measurePerfPhaseSync("parse_extract", () => parser.parse(parseContent));
     }
     catch (e) {
+        // Rethrow BEFORE attempting to free: once the module has aborted its heap
+        // is gone, there is nothing left to reclaim, and calling delete() would
+        // throw a second ExitStatus that replaces the real cause.
+        if (isWasmAbort(e))
+            throw e;
+        // Otherwise free before returning. Skipping one file must not also cost a
+        // parser, or a repository full of pathological inputs would leak its way
+        // to an abort through the recovery path itself.
+        freeQuietly(parser);
         console.warn(`knodin: skipped ${relativePath} (parser error: ${e.message})`);
         return { kind: "skipped", reason: e.message };
     }
-    if (!tree)
+    if (!tree) {
+        freeQuietly(parser);
         return { kind: "skipped", reason: "parser returned no tree" };
-    const mcpRegistrations = /\.[cm]?[jt]sx?$/.test(absolutePath) && /@modelcontextprotocol\/sdk/.test(content)
-        ? extractMcpToolRegistrations(content, relativePath, tree.rootNode)
-        : [];
-    const isPython = absolutePath.endsWith(".py");
-    const isApex = absolutePath.endsWith(".cls") || absolutePath.endsWith(".trigger");
-    const isVisualforce = absolutePath.endsWith(".page") || absolutePath.endsWith(".component");
-    const isPrisma = absolutePath.endsWith(".prisma");
-    const isWorkday = absolutePath.endsWith(".clp") ||
-        absolutePath.endsWith(".ws") ||
-        (absolutePath.endsWith(".xml") && isWorkdayStudioFile(content, absolutePath));
-    const special = (route) => ({
-        kind: "special",
-        route,
-        content,
-        parseContent,
-        tree: tree,
-    });
-    if (isWorkday)
-        return special("workday");
-    if (isVisualforce)
-        return special("visualforce");
-    if (isSql)
-        return special("sql");
-    if (isPrisma)
-        return special("prisma");
-    return {
-        kind: "result",
-        result: buildFileIndexResult(tree, content, isPython, isApex, absolutePath, relativePath, repoPath, mcpRegistrations),
-    };
+    }
+    // Everything from here on can throw — `extractMcpToolRegistrations` and the
+    // symbol extractor both walk attacker-shaped input — and this runs once per
+    // file, so a leak on the throwing path scales with repository size exactly
+    // like the leak this whole change removes. The `finally` is the guarantee;
+    // `handedOff` is the one case where the tree deliberately escapes.
+    let handedOff = false;
+    try {
+        const mcpRegistrations = /\.[cm]?[jt]sx?$/.test(absolutePath) && /@modelcontextprotocol\/sdk/.test(content)
+            ? extractMcpToolRegistrations(content, relativePath, tree.rootNode)
+            : [];
+        const isPython = absolutePath.endsWith(".py");
+        const isApex = absolutePath.endsWith(".cls") || absolutePath.endsWith(".trigger");
+        const isVisualforce = absolutePath.endsWith(".page") || absolutePath.endsWith(".component");
+        const isPrisma = absolutePath.endsWith(".prisma");
+        const isWorkday = absolutePath.endsWith(".clp") ||
+            absolutePath.endsWith(".ws") ||
+            (absolutePath.endsWith(".xml") && isWorkdayStudioFile(content, absolutePath));
+        const special = (route) => {
+            handedOff = true;
+            freeQuietly(parser);
+            return {
+                kind: "special",
+                route,
+                content,
+                parseContent,
+                tree: tree,
+            };
+        };
+        // The parser has done its job by here and nothing downstream needs it: a
+        // `Tree` owns its own wasm memory and stays readable after its parser is
+        // freed (pinned by parser-lifetime.spec.ts, because a use-after-free here
+        // would surface as corrupt nodes rather than a crash). Freeing it at the
+        // point of return is what makes the escaping-tree routes below safe to
+        // hand out — the caller then owns exactly one object, the tree.
+        if (isWorkday)
+            return special("workday");
+        if (isVisualforce)
+            return special("visualforce");
+        if (isSql)
+            return special("sql");
+        if (isPrisma)
+            return special("prisma");
+        // `FileIndexResult` is plain data — it must be, since it is structured-cloned
+        // out of a parse worker — so both objects are dead the moment it is built,
+        // and the `finally` below frees them.
+        return {
+            kind: "result",
+            result: buildFileIndexResult(tree, content, isPython, isApex, absolutePath, relativePath, repoPath, mcpRegistrations),
+        };
+    }
+    finally {
+        if (!handedOff) {
+            freeQuietly(tree);
+            freeQuietly(parser);
+        }
+    }
 }
 /**
  * The single source of truth for indexer routing.
@@ -6405,20 +6504,35 @@ async function indexFile(absolutePath, relativePath, repoPath, db, unparsed, col
             return;
         if (extraction.kind === "special") {
             const { content, parseContent, tree } = extraction;
-            switch (extraction.route) {
-                case "workday":
-                    await indexWorkdayFile(content, tree, relativePath, repoPath, db);
-                    return;
-                case "visualforce":
-                    await indexVisualforceFile(content, tree, relativePath, repoPath, db);
-                    return;
-                case "sql":
-                    await indexSqlFile(parseContent, tree, relativePath, repoPath, db);
-                    return;
-                case "prisma":
-                    await indexPrismaFile(content, tree, relativePath, repoPath, db);
-                    return;
+            // The tree outlived the function that parsed it, so this is the only
+            // place that can free it. `finally` rather than a delete per branch,
+            // because a throw inside an indexer would otherwise leak silently on
+            // exactly the inputs most likely to throw.
+            //
+            // The cases `break` rather than `return` so the single exit below is
+            // reachable. Returning from inside the `try` left that trailing
+            // statement unreachable — dead code the compiler flagged and coverage
+            // could never account for.
+            try {
+                switch (extraction.route) {
+                    case "workday":
+                        await indexWorkdayFile(content, tree, relativePath, repoPath, db);
+                        break;
+                    case "visualforce":
+                        await indexVisualforceFile(content, tree, relativePath, repoPath, db);
+                        break;
+                    case "sql":
+                        await indexSqlFile(parseContent, tree, relativePath, repoPath, db);
+                        break;
+                    case "prisma":
+                        await indexPrismaFile(content, tree, relativePath, repoPath, db);
+                        break;
+                }
             }
+            finally {
+                freeQuietly(tree);
+            }
+            return;
         }
         if (collectResult) {
             collectResult(extraction.result);
@@ -6428,6 +6542,13 @@ async function indexFile(absolutePath, relativePath, repoPath, db, unparsed, col
         }
     }
     catch (error) {
+        // A dead wasm module is not this file's fault and is not survivable.
+        // Swallowing it here is what made one abort look like thousands of
+        // broken files followed by a successful run: every file after the abort
+        // failed identically, got tallied as a coverage gap, and the missing
+        // symbols became indistinguishable from files that genuinely have none.
+        if (isWasmAbort(error))
+            throw error;
         console.error(`Error indexing file ${relativePath}:`, error);
         if (unparsed)
             tallyOne(unparsed, extensionBucket(relativePath));
@@ -7790,11 +7911,16 @@ export function getWatcherQueueStats(repoPath) {
             generationAdvances: 0,
         };
 }
-/** Inject one queue failure for the R45 recovery regression test. */
-export function failNextWatcherFlush(repoPath) {
+/**
+ * Inject one queue failure for the R45 recovery regression test.
+ *
+ * `kind: "wasm-abort"` injects an Emscripten-shaped abort instead of an
+ * ordinary error, which the flush must treat as terminal rather than retryable.
+ */
+export function failNextWatcherFlush(repoPath, kind = "error") {
     const queue = watchQueues.get(path.resolve(repoPath));
     if (queue)
-        queue.failNextFlush = true;
+        queue.failNextFlush = kind;
 }
 /** Hold one queue flush at a deterministic boundary for R45 backpressure tests. */
 export function gateNextWatcherFlushForTests(repoPath, gate) {
@@ -8210,7 +8336,18 @@ function startFileWatcher(repoPath, db, watcherFileLimit = MAX_RECURSIVE_WATCH_F
                     if (testGate)
                         await testGate;
                     if (queue.failNextFlush) {
+                        const injected = queue.failNextFlush;
                         queue.failNextFlush = false;
+                        if (injected === "wasm-abort") {
+                            // Deliberately NOT an Error: the real ExitStatus is a plain object,
+                            // and an Error-shaped stand-in would let a naive `instanceof Error`
+                            // check pass and hide the very bug this pins.
+                            throw Object.assign(Object.create(null), {
+                                name: "ExitStatus",
+                                message: "Program terminated with exit(1)",
+                                status: 1,
+                            });
+                        }
                         throw new Error("injected watcher flush failure");
                     }
                     for (const relativePath of paths) {
@@ -8238,6 +8375,16 @@ function startFileWatcher(repoPath, db, watcherFileLimit = MAX_RECURSIVE_WATCH_F
                 catch (error) {
                     queue.errors++;
                     console.error(`Error flushing watcher updates for ${resolvedRepoPath}:`, error);
+                    if (isWasmAbort(error)) {
+                        // Unrecoverable and process-wide: re-queueing would retry the same
+                        // files every debounce interval, forever, each pass failing at the
+                        // first parse and logging again. Stop the watcher instead — the
+                        // graph is stale from here and only a fresh process can fix it.
+                        queue.closed = true;
+                        queue.pending.clear();
+                        watcherStates.set(resolvedRepoPath, { watcher: "disabled" });
+                        break;
+                    }
                     for (const relativePath of paths)
                         queue.pending.add(relativePath);
                     if (!queue.closed) {
@@ -8732,23 +8879,34 @@ export async function getOrInitDb(repoPath, options = {}) {
                                 tree = parser.parse(source);
                             }
                             catch {
+                                parser.delete();
                                 backfillComplete = false;
                                 continue;
                             }
-                            if (!tree)
+                            if (!tree) {
+                                parser.delete();
                                 continue;
-                            db.run("DELETE FROM mcp_tools WHERE filePath = ?", [filePath]);
-                            for (const registration of extractMcpToolRegistrations(source, filePath, tree.rootNode)) {
-                                db.run("INSERT INTO mcp_tools(name, description, schemaSymbol, handlerSymbol, filePath, line, confidence, associationKey) VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [
-                                    registration.name,
-                                    registration.description ?? null,
-                                    registration.schemaSymbol ?? null,
-                                    registration.handlerSymbol ?? null,
-                                    filePath,
-                                    registration.line,
-                                    registration.confidence,
-                                    registration.associationKey ?? null,
-                                ]);
+                            }
+                            // This loop runs once per indexed file, so anything it fails to
+                            // free scales with repository size.
+                            try {
+                                db.run("DELETE FROM mcp_tools WHERE filePath = ?", [filePath]);
+                                for (const registration of extractMcpToolRegistrations(source, filePath, tree.rootNode)) {
+                                    db.run("INSERT INTO mcp_tools(name, description, schemaSymbol, handlerSymbol, filePath, line, confidence, associationKey) VALUES (?, ?, ?, ?, ?, ?, ?, ?)", [
+                                        registration.name,
+                                        registration.description ?? null,
+                                        registration.schemaSymbol ?? null,
+                                        registration.handlerSymbol ?? null,
+                                        filePath,
+                                        registration.line,
+                                        registration.confidence,
+                                        registration.associationKey ?? null,
+                                    ]);
+                                }
+                            }
+                            finally {
+                                freeQuietly(tree);
+                                freeQuietly(parser);
                             }
                         }
                         catch {
@@ -11874,7 +12032,15 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             if (lang) {
                                 const parser = new Parser();
                                 parser.setLanguage(lang);
-                                tree = parser.parse(source.text);
+                                // The binding dies with this block, so nothing else could ever
+                                // free it — including when `parse` itself throws, which the
+                                // outer `catch` only logs. The tree stays valid without it.
+                                try {
+                                    tree = parser.parse(source.text);
+                                }
+                                finally {
+                                    freeQuietly(parser);
+                                }
                             }
                         }
                     }
@@ -11940,6 +12106,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             symbolRisks.push(risk);
                         }
                     }
+                    // Last use of this file's tree; the next iteration reassigns the
+                    // binding, so not freeing here loses it for the rest of the review.
+                    if (tree)
+                        freeQuietly(tree);
+                    tree = null;
                 }
             }
             finally {
@@ -15483,7 +15654,18 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                                     return undefined;
                                 const parser = new Parser();
                                 parser.setLanguage(language);
-                                const tree = parser.parse(content);
+                                // This runs once per traversal edge, not once per file, so the
+                                // same file can be reparsed many times within a single query.
+                                // Both objects are freed on every exit from this closure — the
+                                // parser here even when `parse` throws, which the outer `catch`
+                                // would otherwise swallow along with the allocation.
+                                let tree;
+                                try {
+                                    tree = parser.parse(content);
+                                }
+                                finally {
+                                    freeQuietly(parser);
+                                }
                                 let matched;
                                 const visit = (node) => {
                                     if (matched ||
@@ -15502,17 +15684,26 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                                     for (const child of node.namedChildren)
                                         visit(child);
                                 };
-                                visit(tree.rootNode);
-                                const argumentsNode = matched?.childForFieldName("arguments");
-                                if (!matched || !argumentsNode)
+                                if (!tree)
                                     return undefined;
-                                return {
-                                    kind: "call-arguments",
-                                    arguments: argumentsNode.namedChildren.map((node) => node.text),
-                                    evidence: matched.text.slice(0, 240),
-                                    grounding: "tree-sitter",
-                                    heuristic: true,
-                                };
+                                try {
+                                    visit(tree.rootNode);
+                                    const argumentsNode = matched?.childForFieldName("arguments");
+                                    if (!matched || !argumentsNode)
+                                        return undefined;
+                                    return {
+                                        kind: "call-arguments",
+                                        // `.text` copies into JS strings, so the returned evidence
+                                        // holds no reference into the tree being freed.
+                                        arguments: argumentsNode.namedChildren.map((node) => node.text),
+                                        evidence: matched.text.slice(0, 240),
+                                        grounding: "tree-sitter",
+                                        heuristic: true,
+                                    };
+                                }
+                                finally {
+                                    freeQuietly(tree);
+                                }
                             }
                             catch {
                                 return undefined;

package/dist/src/engine/parse-worker.js

@@ -1,5 +1,5 @@
 import { parentPort } from "node:worker_threads";
-import { extractGenericFileForIndex } from "./index.js";
+import { describeThrown, extractGenericFileForIndex, isWasmAbort } from "./index.js";
 /**
  * Parse-pool worker entry.
  *
@@ -32,6 +32,10 @@ port.on("message", (task) => {
                     break;
                 default:
                     // `special` carries a live tree; hand the file back instead.
+                    // Free it first — this branch is the tree's only owner, and the
+                    // main thread reparses the file from scratch, so leaving it
+                    // alive leaks wasm memory per file until the module aborts.
+                    extraction.tree.delete();
                     response = { id: task.id, kind: "special" };
                     break;
             }
@@ -40,11 +44,20 @@ port.on("message", (task) => {
             // Serialize by hand. A thrown Error clones without its message on some
             // paths, and losing the message turns a diagnosable failure into a
             // mystery at exactly the moment the pool decides whether to retry.
-            response = {
-                id: task.id,
-                kind: "error",
-                message: error instanceof Error ? error.message : String(error),
-            };
+            //
+            // `instanceof Error` is not enough on its own: Emscripten's `ExitStatus`
+            // is a plain object with `name`/`message`, so the naive ternary reports
+            // the wasm abort as "[object Object]". Shared with the CLI's top-level
+            // handler, which had the identical bug — one rule, one place.
+            response = { id: task.id, kind: "error", message: describeThrown(error) };
+            // The module is dead and does not come back: every later task in THIS
+            // worker would fail identically and fall back to the main thread, so the
+            // pool would quietly lose a lane for the rest of the run without any
+            // signal that it had. Report this file, then exit so the pool replaces
+            // the worker (the exit is deferred so the message actually flushes; if
+            // it does not, the pool's exit handler retries the file anyway).
+            if (isWasmAbort(error))
+                setImmediate(() => process.exit(1));
         }
         port.postMessage(response);
     })();

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 { acquireRepairLease } from "./repair-lease.js";
+import { acquireRepairLease, LIFECYCLE_LEASE_TOKEN_ENV } from "./repair-lease.js";
 import { installKnodinSkills, removeKnodinSkills } from "./skill-management.js";
 import { registerInitializedWorktree } from "./worktree-lifecycle.js";
 const MANAGED_MARKER = "KNODIN MANAGED HOOK";
@@ -230,6 +230,63 @@ function fileSignature(filePath, allowOversized = false) {
         throw error;
     }
 }
+/**
+ * The configuration files a `configure` run actually changed, as repo-relative
+ * paths that indexing can accept.
+ *
+ * `configure` used to hand the indexer no file list at all, which means "the
+ * whole repository" — a whole-tree walk to account for a change to three
+ * dotfiles, and minutes of work on a large checkout. Narrowing it here keeps
+ * the cost a function of the configuration, not of the repository.
+ *
+ * Directories and anything outside the worktree are dropped: they are audited
+ * for change reporting but are not indexable files.
+ *
+ * So is anything the prune policy excludes. `.git/` and `.knodin/` are INSIDE
+ * the worktree in an ordinary checkout, so the `..` check below does not
+ * exclude them — it only happens to, in a linked worktree, where the git common
+ * dir lives elsewhere. Without this filter `configure` hands the indexer
+ * `.git/hooks/post-commit`, `.git/info/exclude` and `.knodin/integration.json`,
+ * which the explicit-file index path does not re-filter, so it records
+ * `index_state` rows for paths a full index would never visit and the next
+ * reconciliation then has to purge.
+ */
+function changedConfigurationFiles(repo, targets, before) {
+    const after = mutationSnapshot(targets, true);
+    const changed = [];
+    for (const target of targets) {
+        if (before.get(target.label) === after.get(target.label))
+            continue;
+        const relative = path.relative(repo, target.absolute);
+        if (relative.startsWith("..") || path.isAbsolute(relative))
+            continue;
+        // The SAME predicate a full index uses, not merely the prune check.
+        // `isIndexableSourcePath` is the canonical candidate policy shared by
+        // full-repository collection, the watcher, repair selection and hook
+        // refresh, so filtering through it makes this list a strict subset of what
+        // `init` would have indexed.
+        //
+        // Anything looser indexes files no other path in the system ever selects:
+        // `.mcp.json` and `.codex/config.toml` are configuration, not source, and
+        // including them writes `index_state` rows that the next reconciliation
+        // purges again — churn that looks like drift.
+        if (!isIndexableSourcePath(relative))
+            continue;
+        let stat;
+        try {
+            stat = fs.statSync(target.absolute);
+        }
+        catch {
+            // Removed by this run. There is nothing to index, and pruning the
+            // deleted rows is the lifecycle refresh's job, not this list's.
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        changed.push(relative);
+    }
+    return changed.sort(compareBytes);
+}
 function mutationSnapshot(targets, allowOversized = false) {
     const snapshot = new Map();
     for (const target of targets) {
@@ -357,10 +414,29 @@ export async function refreshFromGitEvent(repo, event, index) {
     }
 }
 function backgroundScript(command) {
-    const invocation = command.map(shellQuote).join(" ");
+    // The interpreter is resolved at RUN time, not baked in. `process.execPath`
+    // is symlink-resolved by Node, so a stable `/opt/homebrew/bin/node` becomes
+    // a version-pinned `/opt/homebrew/Cellar/node/<version>/bin/node`. Homebrew
+    // deletes that directory on upgrade, and every hook generated beforehand
+    // then dies with exit 127 — silently, because refresh runs in the
+    // background, so the graph just stops keeping up.
+    //
+    // The generated path stays PREFERRED, so nothing changes while it exists;
+    // the fallback only engages once it does not. Falling back first would
+    // silently switch which runtime executes, which is its own bug.
+    const [interpreter, ...rest] = command;
+    const invocation = ['"$KNODIN_NODE"', ...rest.map(shellQuote)].join(" ");
+    const preferred = shellQuote(interpreter ?? process.execPath);
     return String.raw `#!/bin/sh
 # knodin packaged background refresh. Generated by knodin init.
 set -u
+KNODIN_NODE=${preferred}
+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.
+  [ -n "$KNODIN_NODE" ] || KNODIN_NODE=${preferred}
+fi
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 [ -n "$REPO_ROOT" ] || exit 0
 cd "$REPO_ROOT" || exit 0
@@ -460,7 +536,7 @@ function refreshProcessorIsRunning(repo) {
         return false;
     }
 }
-function drainQueuedLifecycleEvents(repo, backgroundPath) {
+function drainQueuedLifecycleEvents(repo, backgroundPath, leaseToken) {
     const before = queuedLifecycleEvents(repo);
     if (before.length === 0)
         return { state: "fresh", queuedEvents: 0 };
@@ -469,6 +545,13 @@ function drainQueuedLifecycleEvents(repo, backgroundPath) {
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "pipe"],
         timeout: 30_000,
+        // The caller holds the lifecycle lease while this runs. Without handing
+        // the token down, the child re-enters knodin, meets its own parent's
+        // lease, and refuses — so the drain could never succeed and init
+        // reported failure on every run.
+        env: leaseToken
+            ? { ...process.env, [LIFECYCLE_LEASE_TOKEN_ENV]: leaseToken }
+            : { ...process.env },
     });
     if (result.status !== 0) {
         const detail = result.error?.message || result.stderr.trim() || `exit ${result.status ?? "unknown"}`;
@@ -1283,13 +1366,25 @@ export async function initializeRepository(repo, options) {
         // Configuration is graph-visible, so explicit configuration must complete
         // before the final index and health verification. Plain init reaches this
         // point without touching agent instructions, MCP files, skills, or receipts.
-        const indexResult = await options.index(resolvedRepo, {
-            onProgress: options.onProgress,
-        });
-        if (isIndexResult(indexResult) && indexResult.verification.status !== "healthy") {
-            throw new InitializationHealthError(indexResult);
+        //
+        // "Graph-visible" justifies indexing the files configuration wrote. It does
+        // not justify walking the whole repository to find them, which is what an
+        // undefined file list means.
+        const scopedIndexPaths = options.indexScope === "configuration"
+            ? changedConfigurationFiles(resolvedRepo, mutationTargets, beforeMutation)
+            : undefined;
+        if (!scopedIndexPaths || scopedIndexPaths.length > 0) {
+            const indexResult = await options.index(resolvedRepo, { onProgress: options.onProgress }, scopedIndexPaths);
+            // Only a full index has verified the whole graph, so only a full index
+            // may fail the run on graph health. A configuration-scoped pass saw a
+            // handful of files and knows nothing about the rest.
+            if (!scopedIndexPaths &&
+                isIndexResult(indexResult) &&
+                indexResult.verification.status !== "healthy") {
+                throw new InitializationHealthError(indexResult);
+            }
         }
-        const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath);
+        const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath, lifecycleLease.token);
         await fs.promises.rm(path.join(knodinHooksDir, HOOK_FAILURE_FILE), {
             force: true,
         });
@@ -1310,6 +1405,7 @@ export async function initializeRepository(repo, options) {
             excluded,
             lifecycleRefresh,
             hookManagerIntegration,
+            scopedIndexPaths,
         };
     }
     finally {

package/dist/src/mcp-worker-supervisor.js

@@ -200,8 +200,19 @@ export class RepositoryWorker extends EventEmitter {
         }
         const { requestId, operation } = context;
         try {
+            // Same race as the startup one below, one phase earlier: the queueAbort
+            // arm above reports CLIENT_DISCONNECTED, and this re-check reported
+            // CANCELLED for the identical event whenever the queue wait resolved in
+            // the same instant the abort landed.
+            //
+            // The supervisor observes only "the signal aborted" and cannot tell a
+            // disconnect from an explicit cancel; every abort-listener arm here
+            // already calls that a disconnect, so the re-checks now agree with them.
+            // The distinction belongs to the layer that knows why the signal fired —
+            // superviseMcpRequest, which raises REQUEST_CANCELLED for a client
+            // cancellation it can actually identify.
             if (signal.aborted)
-                throw codedError("KNODIN_REQUEST_CANCELLED", "request cancelled before worker dispatch");
+                throw codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected before worker dispatch");
             if (!this.child) {
                 if (this.restartTimes.length >= MAX_RESTARTS)
                     throw codedError("KNODIN_RESTART_LIMIT", "graph worker restart limit reached");
@@ -233,8 +244,20 @@ export class RepositoryWorker extends EventEmitter {
                 if (startupAbort)
                     signal.removeEventListener("abort", startupAbort);
             });
+            // Same event as the startupAbort arm above, same code. Both describe an
+            // abort arriving during worker startup; which one reports it is decided
+            // by whether the startup race settles as ready or as aborted in the same
+            // instant. Reporting different codes made the SAME client disconnect
+            // surface as CLIENT_DISCONNECTED or REQUEST_CANCELLED depending on
+            // scheduling — stable on an idle machine, unstable under load, which is
+            // worse than a consistently wrong value because it invites trust.
+            //
+            // These codes name a CAUSE, not a phase. classifyMcpFailure maps them to
+            // distinct kinds in the reliability journal, so the race was also
+            // recording one disconnect under two kinds and silently contaminating
+            // any disconnect-versus-cancellation rate computed from it.
             if (signal.aborted)
-                throw codedError("KNODIN_REQUEST_CANCELLED", "request cancelled during worker startup");
+                throw codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected during worker startup");
             const predecessorTraceId = this.lastFailureTraceId;
             if (predecessorTraceId)
                 recordMcpLifecycle(context, "restart", { predecessorTraceId });

package/dist/src/repair-lease.js

@@ -92,10 +92,34 @@ function removeStaleLeaseOrThrow(target, operation) {
             throw error;
     }
 }
+/**
+ * Environment channel by which a lease holder tells a process it spawns that
+ * the lease it is about to meet is its OWN.
+ *
+ * `knodin init` holds the lease and then drains the queued lifecycle refresh by
+ * spawning the background hook, which re-enters knodin and tries to take the
+ * same lease. Without this the child sees a live pid — its own parent — and
+ * refuses, so init can never drain its own queue and reports failure on every
+ * run while telling the user to run init again.
+ */
+export const LIFECYCLE_LEASE_TOKEN_ENV = "KNODIN_LIFECYCLE_LEASE_TOKEN";
 /** Atomically serialize repair post-processing across independent CLI/MCP processes. */
 export function acquireRepairLease(repo, operation = "repair") {
     const target = leasePath(repo);
     fs.mkdirSync(path.dirname(target), { recursive: true });
+    // Re-entrant ONLY for a token that matches the lease actually on disk. A
+    // stale or forged token falls through to the normal contention check, so a
+    // genuinely concurrent mutation from another process is still refused —
+    // this makes the lease stop blocking its own holder, it does not disable it.
+    const inheritedToken = process.env[LIFECYCLE_LEASE_TOKEN_ENV];
+    if (inheritedToken) {
+        const held = readLease(target);
+        if (held?.nonce === inheritedToken) {
+            // The holder releases it. Releasing here would drop the lock while the
+            // parent still believes it holds it.
+            return { release() { } };
+        }
+    }
     const lifecycleCommand = [
         "repair",
         "init",
@@ -124,6 +148,7 @@ export function acquireRepairLease(repo, operation = "repair") {
             writeLease(target, record);
             writeActivity(repo, record);
             return {
+                token: record.nonce,
                 release() {
                     try {
                         const current = readLease(target);

package/docs/releases/0.10.1.md

@@ -0,0 +1,83 @@
+# knodin 0.10.1
+
+Three defects, none of which a test suite would have found on its own. Two were
+found by upgrading knodin on a real machine: one only appears after Homebrew
+moves the Node binary, the other only when a lifecycle event is already queued.
+The third is a scheduling race that reported the same cause under two different
+codes, and it surfaced as an unrelated pre-push failure after six clean runs.
+
+## Background refresh survives a moved Node binary
+
+`knodin init` wrote the generated hook with a fully-resolved path to whichever
+Node was running at the time. `process.execPath` is symlink-resolved, so a
+stable `/opt/homebrew/bin/node` became a version-pinned
+`/opt/homebrew/Cellar/node/<version>/bin/node`.
+
+Homebrew deletes that directory on upgrade, so every hook written beforehand
+died with exit 127 — silently, because refresh runs in the background. The
+graph simply stopped keeping up, and only a `knodin status` run revealed it.
+It affected every repository initialized before the upgrade, not one.
+
+The hook now resolves its interpreter when it runs. The recorded path stays
+preferred, so nothing changes while it exists; `PATH` is consulted only once it
+does not. Falling back first would silently change which runtime executes,
+which is its own bug.
+
+Hooks generated before this release still carry the old absolute path. They
+keep failing until regenerated with `knodin init`; the fix prevents recurrence
+after the next Node upgrade rather than repairing them retroactively.
+
+## `knodin init` can drain its own lifecycle queue
+
+`init` takes the lifecycle lease, then drains queued events by spawning the
+background hook. The hook re-entered knodin, met the same lease, saw a live
+pid — its own parent — and refused. `init` reported "queued lifecycle refresh
+could not be drained (exit 1)" on every run, and `knodin status` then advised
+running `init`, which reproduced the failure exactly.
+
+Worse, the failed drain wrote a failure marker that `status` kept reporting, so
+a transient condition looked permanent while the graph was in fact intact — in
+the observed case 5,883 of 5,883 files indexed and 5,059 carrying symbols.
+
+A lease holder now passes its nonce to processes it spawns, and a child whose
+token matches the lease on disk is admitted re-entrantly. Re-entry returns a
+no-op release, because releasing there would drop the lock while the parent
+still believes it holds it.
+
+The lease is not weakened. A missing token, or one that does not match the
+lease on disk, still hits the existing contention check, so a genuinely
+concurrent mutation from another process is refused exactly as before.
+
+## One abort cause, one code
+
+Worker startup and queue admission are each a race between "ready" and
+"aborted". Each arm had an abort listener rejecting with
+`KNODIN_CLIENT_DISCONNECTED` and a follow-up `signal.aborted` re-check
+rejecting with `KNODIN_REQUEST_CANCELLED`, so the same client disconnect
+surfaced as either code depending on which arm settled first.
+
+That is worse than a consistently wrong code. It was stable on an idle machine
+and unstable under load, so it looked trustworthy everywhere anyone would have
+checked it — it surfaced as a pre-push gate failure on an unrelated change
+after six clean runs.
+
+It also fed the reliability journal, where the two codes map to distinct kinds.
+One disconnect was recorded under two kinds, quietly skewing any rate computed
+from them. **That contamination is retroactive and cannot be repaired:** journal
+entries written before this release cannot be reattributed, so a
+cancellation-versus-disconnect rate spanning the 0.10.1 boundary should be read
+as suspect rather than corrected.
+
+The taxonomy is unchanged. `superviseMcpRequest` can still tell an explicit
+cancellation from a disconnect; the supervisor cannot, so it now names only the
+cause it actually knows.
+
+## Homebrew formula retention
+
+The `Retain versioned Homebrew formula` job ran on a GitHub-hosted runner whose
+ephemeral IP is not on the organization's allow list, so it failed at checkout
+with a 403 on every release since it was added — and it cloned
+`knodin/knodin`, a stale source mirror, rather than `knodin/homebrew-tap`.
+
+Both are corrected. Every formula through 0.10.0 was retained by hand; this is
+the first release where that job can do it.

package/docs/releases/0.10.2.md

@@ -0,0 +1,76 @@
+# knodin 0.10.2
+
+Two defects found by running 0.10.1 against a 902,960-file Salesforce checkout.
+One of them means graphs built by earlier releases on large repositories are
+incomplete in a way that nothing reported.
+
+## Parsers were never freed, and the run reported success anyway
+
+Indexing built a tree-sitter `Parser` for every file and freed neither it nor
+the resulting syntax tree. web-tree-sitter objects live in the Emscripten heap
+and are reclaimed only by an explicit `delete()`; of the five parse sites in the
+engine, exactly one had it.
+
+The heap therefore grew with every file until allocation failed and the wasm
+module called `abort()`. Measured on a 219-byte XML file: leaking died at the
+87,305th parse with `ExitStatus: Program terminated with exit(1)`, while freeing
+survived 200,000 with no failure.
+
+Three things went wrong from there, and the last is the reason this is a
+correctness fix rather than a performance one.
+
+The module never comes back. After the first abort, every later parse failed
+identically — verified on freshly constructed parsers.
+
+The error then named the wrong file. Every file processed after the abort was
+reported as failing regardless of its contents, which is why the observed
+failure list was a contiguous alphabetical run of Salesforce package manifests.
+Those files are fine; all 144 of them parse cleanly on a shared parser.
+
+And the failure was swallowed. The per-file handler logged, counted the file as
+a coverage gap, and continued, so the run finished successfully. Files that were
+never parsed became indistinguishable from files that genuinely contain no
+symbols, and every later query answered confidently from a graph that was
+quietly missing everything after the abort.
+
+All five sites now free both objects on every path, including early returns and
+error paths. A wasm abort is no longer treated as a per-file problem: it fails
+the run, because it is not survivable and pretending otherwise is what turned
+one real failure into thousands of misattributed ones.
+
+**Reindex to trust an existing graph.** If a large repository was indexed with
+an earlier release, symbol coverage may be short by an unknown amount and
+nothing in `knodin status` would have said so. Smaller repositories that never
+approached the threshold are unaffected.
+
+The coverage line also stops claiming more than it knows. Files with no
+tree-sitter grammar, minified sources, and files whose indexing failed were all
+reported as `parsed but empty`, which asserts the parser looked and found
+nothing — the one thing it did not do. They are now reported as `not parsed`.
+
+## `knodin configure` no longer indexes the entire repository
+
+`configure` refuses to run against an uninitialized repository on the grounds
+that it "changes agent integration only", and then passed the indexer no file
+list, which means every file in the tree. On a large checkout that is minutes of
+work to account for a change to three dotfiles, with nothing in the output
+saying an index was happening at all.
+
+It now indexes only the files it actually wrote that a full index would also
+have selected, and reports what it did instead of claiming the graph was
+refreshed. That claim was most misleading precisely where it mattered: on a
+repository whose graph was empty, `configure` silently rebuilt it from scratch,
+which is `init`'s job and is what made a routine scope change look inexplicably
+slow.
+
+In practice `knodin configure --scope personal` now indexes nothing at all.
+Personal scope writes only `.agents/`, `.codex/` and `.gemini/`, none of which
+is source, so there is nothing for the indexer to do and it is not invoked.
+Team scope still indexes the agent instructions it writes.
+
+The filter is the same predicate a full index uses, rather than a looser one
+written for this path. Anything looser records `index_state` rows for files no
+other part of the system ever selects, which the next reconciliation then
+purges — churn that reads as drift.
+
+`knodin init` is unchanged and still indexes everything and verifies health.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.10.0",
+	"version": "0.10.2",
 	"knodin": {
 		"compatibility": "breaking"
 	},
@@ -72,6 +72,8 @@
 		"docs/releases/0.8.7.md",
 		"docs/releases/0.9.0.md",
 		"docs/releases/0.10.0.md",
+		"docs/releases/0.10.1.md",
+		"docs/releases/0.10.2.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",