knodin 0.11.0 → 0.12.0

package/dist/bin/cli.js

@@ -35,7 +35,7 @@ import { diagnoseFailure, } from "../src/failure-diagnosis.js";
 import { gitExecutable } from "../src/git-executable.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../src/graph-query-health.js";
 import { createIndexActivityReporter } from "../src/index-activity.js";
-import { InitializationHealthError, initializeRepository, inspectRepositoryIntegrationStatus, readRepositoryIntegrationConfig, refreshFromGitEvent, } from "../src/init.js";
+import { InitializationHealthError, initializeRepository, inspectRepositoryIntegrationStatus, readRepositoryIntegrationConfig, refreshFromGitEvent, repairLifecycleRouting, } from "../src/init.js";
 import { createInitProgressRenderer } from "../src/init-progress.js";
 import { attachLifecycleHealth, attachRepairLifecycle } from "../src/lifecycle-health.js";
 import { acknowledgeUpdateFailure, queryOwnerAvailability, readManagerUpdateState, readUpdateJournal, resolveManagerOwnership, setManualPin, unpinUpdate, updateAttention, writeManagerUpdateState, } from "../src/manager-update.js";
@@ -60,7 +60,7 @@ import { KNODIN_VERSION } from "../src/version.js";
 import { writeVisualization, } from "../src/visualization.js";
 import { waitForFresh } from "../src/wait-for-fresh.js";
 import { inspectWorktrees, reconcileWorktrees, removeManagedWorktree, } from "../src/worktree-lifecycle.js";
-import { indexOrSeed } from "../src/worktree-seed.js";
+import { indexOrSeed, seedWorktreeIndex } from "../src/worktree-seed.js";
 function explicitScope(args) {
     const index = args.indexOf("--scope");
     if (index >= 0) {
@@ -138,7 +138,7 @@ function formatRepairHuman(result) {
     }
     if (result.verified) {
         if (result.lifecycle?.status === "degraded")
-            return `Repair verified: graph is healthy (${coverage.indexedFiles} indexed files, ${coverage.filesWithSymbols} files with symbols), but lifecycle routing is degraded. Run \`knodin init\`, then \`knodin status\`.\n`;
+            return `Repair verified: graph is healthy (${coverage.indexedFiles} indexed files, ${coverage.filesWithSymbols} files with symbols), but lifecycle routing is degraded. Run \`knodin repair --lifecycle\`, then \`knodin status\`.\n`;
         return `Repair verified: graph is healthy (${coverage.indexedFiles} indexed files, ${coverage.filesWithSymbols} files with symbols).\n`;
     }
     const outstanding = result.outstandingIssues?.total ??
@@ -198,7 +198,7 @@ function formatLifecycleLine(lifecycle, isMirror) {
     if (lifecycle.status === "healthy")
         return "Hooks: installed and executable.\n";
     const issue = lifecycle.issues[0] ?? "refresh capability is not verified";
-    return `Lifecycle refresh: ${lifecycle.status}; ${issue}. Run \`knodin init\`.\n`;
+    return `Lifecycle refresh: ${lifecycle.status}; ${issue}. Run \`knodin repair --lifecycle\`.\n`;
 }
 /** Renders the top extensions of a tally as `.md 180, .yml 74, +3 more`. */
 function formatTally(counts, limit = 4) {
@@ -1522,6 +1522,7 @@ async function main() {
     let result;
     let repairOutput;
     let repairWasPlan = false;
+    let repairWasLifecycle = false;
     let repairExitCode = 0;
     let statusWasWatched = false;
     let agentEventOutput = false;
@@ -2381,6 +2382,27 @@ async function main() {
                 repairWasPlan = true;
                 break;
             }
+            if (options.lifecycle) {
+                result = await repairLifecycleRouting(repo, { command: runtimeCommand });
+                repairOutput = options.output;
+                repairWasLifecycle = true;
+                break;
+            }
+            // Cold start only. With no database at all there is nothing to rebuild
+            // *from*, so repair would index the whole corpus while a sibling
+            // worktree already holds a reusable baseline — reflink-copying it and
+            // reconciling the differing paths is seconds against minutes
+            // (KNODIN-14). Repair's contract is untouched: it still rebuilds from
+            // this working tree, it just starts from a baseline instead of zero.
+            //
+            // A database that exists but is damaged is deliberately excluded. That
+            // is the case repair exists for, and seeding it would replace a
+            // verifiable local rebuild with another checkout's state.
+            if (!fs.existsSync(resolveDbPath(repo))) {
+                const seed = await seedWorktreeIndex(repo, engine, KNODIN_SCHEMA_VERSION);
+                if (seed.seeded)
+                    process.stderr.write("[repair:seed] Seeded baseline from an indexed sibling worktree\n");
+            }
             const progressMode = resolveRepairProgressMode(options, process.env, process.stderr.isTTY);
             const renderer = progressMode === "tty"
                 ? createProgressWorkerRenderer("repair-progress-worker", {
@@ -2787,6 +2809,12 @@ async function main() {
                 }
                 result = decorateGraphQueryResult(result, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness);
             }
+            // A target that does not exist is operator error, not a negative
+            // answer, so it exits non-zero like an unavailable graph rather than
+            // like real dead code (KNODIN-28). `resolved` with zero rows keeps
+            // exit 0: the symbol exists and genuinely has no callers.
+            if (result?.targetResolution === "not-found")
+                process.exitCode = 1;
             break;
         }
         case "rename": {
@@ -2999,6 +3027,15 @@ async function main() {
         process.stdout.write(formatConfigureStatusHuman(boundedResult));
         return;
     }
+    if (cmd === "repair" && repairOutput === "human" && repairWasLifecycle) {
+        // A lifecycle repair carries no graph coverage, so it cannot go through
+        // the graph-repair renderer, and saying nothing about what it left alone
+        // would omit the only reason to reach for it (KNODIN-31).
+        const lifecycle = boundedResult;
+        process.stdout.write(`Lifecycle routing rewritten: ${lifecycle.gitHooks.length} managed Git hook(s) and the background indexer, in ${lifecycle.hooksDirectory}. Agent configuration untouched. Run \`knodin status\` to confirm.\n`);
+        process.exitCode = finalExitCode;
+        return;
+    }
     if (cmd === "repair" && repairOutput === "human" && !repairWasPlan) {
         process.stdout.write(formatRepairHuman(boundedResult));
         process.exitCode = finalExitCode;

package/dist/src/cli-model.js

@@ -309,6 +309,7 @@ function createCliProgram(capture = () => { }) {
         .addOption(option("--timeout <seconds>", "deadline", "number"));
     leaf(program, "repair", "audit and reconcile graph state", capture)
         .option("--plan", "report the repair plan without mutation")
+        .option("--lifecycle", "rewrite lifecycle hooks only, leaving agent configuration untouched")
         .option("--jsonl", "stream JSONL progress")
         .option("--progress <mode>", "tty, jsonl, plain, or none")
         .option("--progress-interval <duration>", "progress interval such as 750ms, 30s, or 2m");

package/dist/src/engine/index.js

@@ -826,6 +826,97 @@ function freshnessMechanismFor(repoPath, policy) {
 // Bumped whenever any repo is (re)indexed, so cached community-detection results
 // below can be invalidated cheaply instead of recomputed on every call.
 export const KNODIN_SCHEMA_VERSION = 24;
+/**
+ * Reciprocal Rank Fusion's smoothing constant. Was written as a bare `60` at
+ * each use site; named so the ranking formula can be read and changed in one
+ * place. Adjacent ranks differ by roughly 0.00026 at this k, which is the unit
+ * every other ranking weight has to be reasoned about in.
+ */
+const RRF_K = 60;
+/**
+ * How hard graph centrality pulls on ranking, as a fraction of one full RRF
+ * component.
+ *
+ * Semantic similarity alone ranks a minutes-old duplicate above the
+ * implementation it duplicates: the duplicate is short and made almost entirely
+ * of the query's own words, while the canonical version is diluted by a real
+ * body. The searcher then reads their own new leaf as evidence that nothing
+ * existed (KNODIN-15). Community and degree data was already in the graph and
+ * already in the output; it simply was not weighted into ranking.
+ *
+ * 0.05 caps the boost at `0.05 / (RRF_K + 1)` ≈ 0.00082, about three rank
+ * positions. That is deliberately modest, because the opposite failure is
+ * equally real and lands on the same symbols: a *seam* is by definition a
+ * well-documented symbol with no callers, and those are already the hardest
+ * things to retrieve (KNODIN-28, KNODIN-30). A large centrality weight would
+ * bury them to fix this, trading one silent miss for another. So a connected
+ * implementation climbs past neighbours it is scoring near, and does not
+ * override a decisively stronger semantic match.
+ *
+ * Zero-in-degree symbols are excluded from the centrality ranking rather than
+ * ranked last, so an uncalled symbol is never *penalised* — it only forgoes a
+ * boost it has no evidence for.
+ */
+const CENTRALITY_RRF_WEIGHT = 0.05;
+/**
+ * The live ranking weights, exported so a benchmark can record which values
+ * produced its numbers.
+ *
+ * Comparing two ranking runs whose constants differed is not a measurement, and
+ * the difference is invisible unless the run writes them down. Reading them here
+ * rather than copying them into the benchmark keeps that record from going stale
+ * the first time someone tunes a weight.
+ */
+/**
+ * How hard a partial (OR) lexical match pulls, as a fraction of one full RRF
+ * component, and how many of them are considered.
+ *
+ * The weight buys a statable property: at 0.75 a top-ranked partial match
+ * contributes `0.75 / (RRF_K + 1)` ≈ 0.0123, which is enough to lift a symbol
+ * sitting around semantic rank 90 above an unsupported semantic rank 1. So
+ * lexical evidence can rescue a symbol the embedder under-ranked, and cannot
+ * resurrect one the embedder judged irrelevant. At 1.0 the loose channel becomes
+ * a full peer of semantic similarity and wins from arbitrarily deep, which is
+ * over-correction.
+ *
+ * The limit is a separate lever and conflating the two is how this gets
+ * mistuned. RRF has a floor — the hundredth partial match still scores
+ * `w / (RRF_K + 100)` — so an unbounded channel gives a meaningful shove to a
+ * hundred symbols at once on any query full of common words. Truncating raises
+ * the per-item floor slightly while applying it to under a third as many rows,
+ * which is the trade that actually reduces noise.
+ *
+ * Both are starting points measured against `benchmarks/evaluations/c103-prose-retrieval`,
+ * not settled constants. Re-run it before changing either.
+ */
+const LOOSE_LEXICAL_RRF_WEIGHT = 0.75;
+/**
+ * How many query words the quorum check will probe, one bounded FTS query each.
+ *
+ * The check exists because a single incidental token match is not evidence, and
+ * this index cannot tell the difference on its own: FTS5 here has no stemming
+ * and does not split identifiers, so "validations" misses "validation" and
+ * `SessionAuthenticator` is one opaque token. The cap keeps a pathologically
+ * long query from turning into a pathological number of probes; beyond it the
+ * leading words decide, which is where the discriminating terms usually are.
+ */
+const LEXICAL_QUORUM_TOKEN_CAP = 8;
+const LOOSE_LEXICAL_LIMIT = 30;
+/**
+ * The live ranking weights, exported so a benchmark can record which values
+ * produced its numbers.
+ *
+ * Comparing two ranking runs whose constants differed is not a measurement, and
+ * the difference is invisible unless the run writes them down. Reading them here
+ * rather than copying them into the benchmark keeps that record from going stale
+ * the first time someone tunes a weight.
+ */
+export const RANKING_CONSTANTS = {
+    rrfK: RRF_K,
+    centralityWeight: CENTRALITY_RRF_WEIGHT,
+    looseLexicalWeight: LOOSE_LEXICAL_RRF_WEIGHT,
+    looseLexicalLimit: LOOSE_LEXICAL_LIMIT,
+};
 const LAST_REBUILD_SCHEMA_VERSION = 24;
 let indexGeneration = 0;
 const resourceReachabilityCache = new Map();
@@ -1631,12 +1722,48 @@ function createLanguageMemo() {
         return name;
     };
 }
+/**
+ * Node types a `//` line can carry across the grammars this indexes. They
+ * disagree on the name, so matching one of them is not enough on its own — see
+ * `isLineComment` below, which also requires the `//` prefix.
+ */
+const LINE_COMMENT_NODE_TYPES = new Set(["comment", "line_comment", "hash_comment"]);
 /** Clean up and format comment/docstring blocks in JavaScript/TypeScript. */
 function getPrecedingComment(node) {
     let target = node;
     while (target.parent && target.parent.startPosition.row === target.startPosition.row) {
         target = target.parent;
     }
+    // Only decorators and modifiers may sit between a doc comment and the thing
+    // it documents. The walk used to step over ANY five siblings looking for a
+    // comment, so a symbol with no doc comment of its own adopted whichever
+    // comment preceded a nearby earlier symbol — attaching prose to a symbol it
+    // was never written about, in both the embedding input and the FTS `summary`
+    // column.
+    //
+    // That is not a corner case. Measured on this repository before the fix, 857
+    // of 1,329 documented symbols under `src/` — 64% — shared summary text with
+    // another symbol, and spot checks showed plain misattribution rather than
+    // genuine repetition: an interface carrying a neighbouring function's
+    // docstring, two unrelated types sharing a third symbol's sentence. Prose
+    // retrieval matching that text then returns the wrong symbol confidently,
+    // which is the same class of failure as the truncation above and strictly
+    // worse: absent prose loses a hit, misattributed prose manufactures one.
+    //
+    // Stopping at the first non-skippable node is the whole fix. A row-adjacency
+    // check was tried alongside it and removed: decorators are children of the
+    // declaration in some grammars and siblings in others, so "directly above"
+    // is not portable, and it silently dropped the doc comment of every
+    // decorated class. The walk already refuses to cross a declaration, which is
+    // what the misattribution needed.
+    const SKIPPABLE_BEFORE_DOC = new Set([
+        "decorator",
+        "export",
+        "default",
+        "async",
+        "abstract",
+        "declare",
+    ]);
     let prev = target.previousSibling;
     let count = 0;
     while (prev && count < 5) {
@@ -1646,6 +1773,8 @@ function getPrecedingComment(node) {
             prev.type === "line_comment") {
             break;
         }
+        if (!SKIPPABLE_BEFORE_DOC.has(prev.type))
+            return null;
         prev = prev.previousSibling;
         count++;
     }
@@ -1654,6 +1783,48 @@ function getPrecedingComment(node) {
             prev.type === "hash_comment" ||
             prev.type === "block_comment" ||
             prev.type === "line_comment")) {
+        // Walk back over a run of consecutive `//` lines and rejoin them.
+        //
+        // tree-sitter gives every `//` line its OWN comment node, so `prev` is the
+        // LAST line of a block, and the `split("\n")` below could never fire for
+        // this style. Every multi-line `//` doc comment in every indexed
+        // repository was therefore truncated to its final line before it reached
+        // the embedding or the FTS index — silently, since a one-line summary
+        // looks perfectly well-formed.
+        //
+        // That is a retrieval defect, not a cosmetic one: the first line of a doc
+        // comment is usually the sentence that says what the thing is for, which
+        // is exactly what a capability question matches on. `/* */` blocks are a
+        // single node and were never affected, so the damage was invisible in any
+        // codebase that preferred them.
+        //
+        // Adjacency is required: a blank line or any code between two comment
+        // nodes ends the block, so a stray earlier comment is not absorbed.
+        // Keyed on the `//` PREFIX rather than on one node type. The surrounding
+        // checks accept `comment`, `line_comment`, `hash_comment` and
+        // `block_comment` because grammars disagree about the name, and an
+        // earlier version of this rejoin tested `type === "comment"` alone — so
+        // in any grammar that calls a `//` line `line_comment`, multi-line
+        // comments went on being truncated to their last line while appearing
+        // fixed everywhere else. The prefix is the thing that actually decides
+        // whether a node is one line of a multi-line run.
+        const isLineComment = (node) => LINE_COMMENT_NODE_TYPES.has(node.type) && node.text.trim().startsWith("//");
+        if (isLineComment(prev)) {
+            const lines = [];
+            let line = prev;
+            while (line &&
+                isLineComment(line) &&
+                // Consecutive source lines, and nothing but whitespace between them.
+                (lines.length === 0 || line.endPosition.row + 1 === prev.startPosition.row)) {
+                lines.unshift(line.text.trim());
+                prev = line;
+                line = line.previousSibling;
+            }
+            return lines
+                .map((entry) => entry.replace(/^\/\/+\s*/, ""))
+                .join("\n")
+                .trim();
+        }
         let text = prev.text.trim();
         if (text.startsWith("/*")) {
             text = text
@@ -6988,6 +7159,34 @@ function repairPathsAffectTypeScriptDi(db, repoPath, repairPaths) {
 // measurements.
 const DEFAULT_EMBEDDING_BATCH_SIZE = 1;
 const MAX_EMBEDDING_BATCH_SIZE = 32;
+/**
+ * Total characters embedded per symbol.
+ *
+ * A `EMBEDDING_SOURCE_BUDGET` capping the source body inside this was tried and
+ * reverted. It looked like a win — the diluted implementation's similarity rose
+ * 0.163 to 0.212 against its own fresh duplicate — but that was measured on the
+ * suite's bag-of-words test embedder, and re-measuring on the real MiniLM model
+ * across two body shapes, three query phrasings and both budgets showed the cap
+ * never changes the winner in any of the twelve configurations. Its apparent
+ * benefit came from the fixture: `fillerBody` emitted forty copies of one line,
+ * and truncating identical lines removes a redundancy bag-of-words punishes and
+ * a transformer largely ignores. On realistic varied code the cap is neutral to
+ * slightly negative.
+ *
+ * The general lesson, which cost a forced re-embed to learn: a short document
+ * made almost entirely of query tokens beats a long one under cosine
+ * similarity, and no reweighting of a single vector's inputs changes that.
+ * KNODIN-15's remedy is a non-similarity signal — graph degree, in the rank
+ * fusion — not the representation.
+ */
+const EMBEDDING_INPUT_BUDGET = 1000;
+/**
+ * The text embedded for one symbol: what it is called, what kind of thing it
+ * is, what its docstring says it does, and then its body.
+ */
+function embeddingInputFor(symbol, source) {
+    return `Name: ${symbol.name}\nKind: ${symbol.kind}\nSummary: ${symbol.summary || ""}\nSource:\n${source}`.slice(0, EMBEDDING_INPUT_BUDGET);
+}
 // A full embedding pass can touch many symbols per source file. Keep only a
 // bounded LRU of split lines so large repositories avoid re-reading a file for
 // every symbol without turning source preparation into an unbounded memory sink.
@@ -7182,10 +7381,7 @@ async function indexEmbeddings(db, repoPath, progress, signal) {
                 throwIfAborted(signal);
                 const prepared = missing.slice(offset, offset + batchSize).map((sym) => {
                     const source = sourceForEmbedding(sym.filePath, sym.startLine, sym.endLine);
-                    return {
-                        symbol: sym,
-                        text: `Name: ${sym.name}\nKind: ${sym.kind}\nSummary: ${sym.summary || ""}\nSource:\n${source}`.slice(0, 1000),
-                    };
+                    return { symbol: sym, text: embeddingInputFor(sym, source) };
                 });
                 const generated = await embedPreparedBatch(prepared, onModelProgress);
                 throwIfAborted(signal);
@@ -8004,50 +8200,6 @@ const freshnessChecks = new Map();
  * deterministic, rather than in wall-clock milliseconds, which is flaky.
  */
 const freshnessStats = { probes: 0, reconciles: 0, cacheHits: 0 };
-/** Read HEAD without spawning Git. `null` means this is not a Git checkout;
- * `undefined` means Git metadata exists but could not be resolved safely. */
-function readGitHeadFast(repoPath) {
-    const marker = path.join(repoPath, ".git");
-    if (!fs.existsSync(marker))
-        return null;
-    try {
-        const markerStat = fs.statSync(marker);
-        const gitDir = markerStat.isDirectory()
-            ? marker
-            : path.resolve(repoPath, fs
-                .readFileSync(marker, "utf8")
-                .trim()
-                .replace(/^gitdir:\s*/, ""));
-        const head = fs.readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
-        if (/^[a-f0-9]{40}$/i.test(head))
-            return head.toLowerCase();
-        const refPrefix = "ref: ";
-        const ref = head.startsWith(refPrefix) ? head.slice(refPrefix.length).trim() : "";
-        if (!ref)
-            return undefined;
-        let commonDir = gitDir;
-        const commonMarker = path.join(gitDir, "commondir");
-        if (fs.existsSync(commonMarker))
-            commonDir = path.resolve(gitDir, fs.readFileSync(commonMarker, "utf8").trim());
-        for (const base of [gitDir, commonDir]) {
-            const loose = path.join(base, ref);
-            if (fs.existsSync(loose))
-                return fs.readFileSync(loose, "utf8").trim().toLowerCase();
-        }
-        const packed = path.join(commonDir, "packed-refs");
-        if (!fs.existsSync(packed))
-            return undefined;
-        return fs
-            .readFileSync(packed, "utf8")
-            .split("\n")
-            .find((line) => line.endsWith(` ${ref}`))
-            ?.split(" ", 1)[0]
-            ?.toLowerCase();
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Paths the live watcher for `repoPath` currently has registered, flattened to
  * repo-relative form. Empty when no watcher is running (test mode, or after
@@ -8272,15 +8424,20 @@ async function ensureIndexFresh(repoPath, db) {
     // already reached its event queue. Git worktrees therefore take the bounded
     // porcelain proof on every answer. The long watcher lease remains safe for
     // non-Git directories, where the watcher is the only new-file signal.
+    //
+    // The lease used to be paired with a spawn-free HEAD read, so a leased
+    // answer could still be invalidated by a commit. Once git-backed repos took
+    // `lease = 0` that read became unreachable — it was called only when `.git`
+    // was absent, which was its own first bail-out — and the term it fed was
+    // inert. Both are gone (KNODIN-16); a lease is now reached only where there
+    // is no HEAD to check.
     const gitBacked = fs.existsSync(path.join(key, ".git"));
     const lease = gitBacked
         ? 0
         : watchQueues.get(key)?.ready
             ? WATCHED_FRESHNESS_LEASE_MS
             : FRESHNESS_PROBE_TTL_MS;
-    const head = lease === WATCHED_FRESHNESS_LEASE_MS ? readGitHeadFast(key) : null;
-    const headUnchanged = head === null || (head !== undefined && head === getMeta(db, "lastIndexedHead"));
-    if (cached && Date.now() - cached.at < lease && headUnchanged) {
+    if (cached && Date.now() - cached.at < lease) {
         freshnessStats.cacheHits++;
         return cached.staleness;
     }
@@ -14447,9 +14604,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         .split(/\s+/)
                         .filter((word) => word.length >= 4)
                         .map((word) => `"${word}"`);
-                    const runFts = (separator) => {
-                        if (tokens.length === 0)
-                            return [];
+                    const runFtsMatch = (match) => {
                         try {
                             const statement = repo.db.query(`
 								SELECT symbolId FROM symbols_fts
@@ -14458,7 +14613,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
 								LIMIT 100
 							`);
                             const ids = statement
-                                .all(tokens.join(separator))
+                                .all(match)
                                 .map(({ symbolId }) => symbolId)
                                 .filter((id) => allowedIds.has(id));
                             statement.finalize();
@@ -14469,8 +14624,43 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             return [];
                         }
                     };
+                    const runFts = (separator) => tokens.length === 0 ? [] : runFtsMatch(tokens.join(separator));
+                    const runFtsTokens = (subset) => subset.length === 0 ? [] : runFtsMatch(subset.join(" OR "));
                     const and = measurePerfPhaseSync("fts", () => runFts(" "));
-                    const or = tokens.length > 1 ? measurePerfPhaseSync("fts", () => runFts(" OR ")) : and;
+                    // The OR set, restricted to candidates matching at least two of the
+                    // query's words.
+                    //
+                    // A single incidental token match is not evidence. FTS5 here has no
+                    // stemming and does not split identifiers, so for "session
+                    // authentication and token validations" the class that actually does
+                    // the work matches NOTHING — its docstring says "sessions" and
+                    // "validation" — while a handler whose docstring happens to contain
+                    // "session" matches once and collects the full partial-match credit.
+                    // Fusing that put the caller above the implementation it calls.
+                    //
+                    // Requiring a quorum keeps the signal that matters (a symbol echoing
+                    // several of the query's words) and drops the one that misleads. It
+                    // costs one bounded FTS query per token, which is why it is capped.
+                    const or = measurePerfPhaseSync("fts", () => {
+                        if (tokens.length < 2)
+                            return and;
+                        const loose = runFts(" OR ");
+                        if (loose.length === 0)
+                            return loose;
+                        const hits = new Map();
+                        for (const token of tokens.slice(0, LEXICAL_QUORUM_TOKEN_CAP)) {
+                            for (const id of runFtsTokens([token])) {
+                                hits.set(id, (hits.get(id) ?? 0) + 1);
+                            }
+                        }
+                        // No fallback when nothing clears the bar. An earlier version
+                        // returned the unfiltered set in that case, which reinstated the
+                        // exact failure the quorum exists to prevent — and did so
+                        // precisely in the small-corpus situation where one weak match is
+                        // most likely to be the only one. A lexical channel with nothing
+                        // trustworthy to say should say nothing.
+                        return loose.filter((id) => (hits.get(id) ?? 0) >= 2);
+                    });
                     const lexicalSeeds = or
                         .map((id) => snapshot.rowById.get(id))
                         .filter((row) => row !== undefined)
@@ -14526,6 +14716,15 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
             // 1. Generate query embedding once
             const queryVec = await generateMeasuredEmbedding(query, true);
             const rankedCandidates = [];
+            // Inbound reference counts for the centrality term. Computed once for the
+            // federation rather than per repo, and only on the route that actually
+            // fuses ranks — the structural and exact-match routes above return before
+            // here and must keep their deterministic ordering.
+            //
+            // Not wrapped in a perf phase: the phase keys are a closed set that the
+            // instrumentation contract asserts on, and adding one to measure a fix
+            // would change what that contract describes.
+            const referenceDegree = computeResolvedReferenceDegree(allRepos, formatPath);
             let totalMatches = 0;
             for (const repo of allRepos) {
                 const db = repo.db;
@@ -14574,12 +14773,35 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 }
                 // Sort by semantic score descending
                 const sortedSemantics = semanticMatches.sort((a, b) => b.score - a.score);
-                const semanticScoresAreTied = sortedSemantics.length > 1 &&
-                    sortedSemantics.every((item) => item.score === sortedSemantics[0]?.score);
                 // 3. Reuse the lexical and bounded-graph ranks computed before query inference.
+                //
+                // Both operators are fused, as separate channels. The selection used to
+                // be `semanticScoresAreTied ? or : and`, and semantic scores are never
+                // all bit-identical under a real embedding model — so the OR set was
+                // computed on every query and then discarded on every query.
+                //
+                // That made the AND clause the entire lexical channel, and for a query
+                // phrased as prose the AND clause is empty: it demands one symbol
+                // containing every surviving query word, function words included.
+                // Nothing matches, so `ftsPart` was zero for every candidate and
+                // "hybrid search" was pure vector search with a centrality nudge. The
+                // docstring's BM25 evidence existed the whole time, in the OR set that
+                // was thrown away (KNODIN-30).
+                //
+                // Fusing both rather than falling back from one to the other avoids a
+                // discontinuity triggered by corpus contents rather than query intent:
+                // with a fallback, one incidental symbol matching every word would flip
+                // the channel from a broad candidate set to a single row, silently.
+                //
+                // `and ⊆ or` by construction — same tokens, narrower operator — so an
+                // AND match collects BOTH terms while an OR-only match collects one.
+                // The precision bonus falls out of that containment exactly, with no
+                // extra machinery to express or tune.
                 const lexical = lexicalRanks.get(repo.path);
-                const baseLexical = semanticScoresAreTied ? lexical?.or : lexical?.and;
-                const ftsMatches = [...new Set(baseLexical ?? [])].filter((id) => allowedIds.has(id));
+                const strictMatches = [...new Set(lexical?.and ?? [])].filter((id) => allowedIds.has(id));
+                const looseMatches = [...new Set(lexical?.or ?? [])]
+                    .filter((id) => allowedIds.has(id))
+                    .slice(0, LOOSE_LEXICAL_LIMIT);
                 // Rank mappings for Reciprocal Rank Fusion (RRF)
                 const semanticRankMap = new Map();
                 const semanticById = new Map();
@@ -14587,19 +14809,57 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     semanticRankMap.set(item.id, idx + 1);
                     semanticById.set(item.id, item);
                 });
-                const ftsRankMap = new Map();
-                ftsMatches.forEach((id, idx) => {
-                    ftsRankMap.set(id, idx + 1);
+                const strictRankMap = new Map();
+                strictMatches.forEach((id, idx) => {
+                    strictRankMap.set(id, idx + 1);
                 });
+                const looseRankMap = new Map();
+                looseMatches.forEach((id, idx) => {
+                    looseRankMap.set(id, idx + 1);
+                });
+                // Rank the matched candidates that anything actually depends on, most
+                // depended-upon first. Symbols with no inbound references are left out
+                // entirely rather than ranked last — see CENTRALITY_RRF_WEIGHT.
+                const centralityRankMap = new Map();
+                {
+                    const connected = [];
+                    for (const id of new Set([
+                        ...semanticRankMap.keys(),
+                        ...strictRankMap.keys(),
+                        ...looseRankMap.keys(),
+                    ])) {
+                        const row = semanticById.get(id)?.row ?? snapshot.rowById.get(id);
+                        if (!row)
+                            continue;
+                        const inDegree = referenceDegree.get(`${formatPath(repo.path, row.filePath)}::${row.name}`)
+                            ?.inDegree ?? 0;
+                        if (inDegree > 0)
+                            connected.push({ id, inDegree });
+                    }
+                    connected.sort((a, b) => b.inDegree - a.inDegree || a.id - b.id);
+                    connected.forEach((item, idx) => {
+                        centralityRankMap.set(item.id, idx + 1);
+                    });
+                }
                 // Perform Reciprocal Rank Fusion (RRF)
                 const topRrf = measurePerfPhaseSync("fusion", () => {
-                    const allMatchedIds = new Set([...semanticRankMap.keys(), ...ftsRankMap.keys()]);
+                    const allMatchedIds = new Set([
+                        ...semanticRankMap.keys(),
+                        ...strictRankMap.keys(),
+                        ...looseRankMap.keys(),
+                    ]);
                     const rrfResults = Array.from(allMatchedIds).map((id) => {
                         const semRank = semanticRankMap.get(id);
-                        const ftsRank = ftsRankMap.get(id);
-                        const semPart = semRank !== undefined ? 1 / (60 + semRank) : 0;
-                        const ftsPart = ftsRank !== undefined ? 1 / (60 + ftsRank) : 0;
-                        return { id, rrfScore: semPart + ftsPart };
+                        const strictRank = strictRankMap.get(id);
+                        const looseRank = looseRankMap.get(id);
+                        const centralityRank = centralityRankMap.get(id);
+                        const semPart = semRank !== undefined ? 1 / (RRF_K + semRank) : 0;
+                        const strictPart = strictRank !== undefined ? 1 / (RRF_K + strictRank) : 0;
+                        const loosePart = looseRank !== undefined ? LOOSE_LEXICAL_RRF_WEIGHT * (1 / (RRF_K + looseRank)) : 0;
+                        const centralityPart = centralityRank !== undefined
+                            ? CENTRALITY_RRF_WEIGHT * (1 / (RRF_K + centralityRank))
+                            : 0;
+                        return { id, rrfScore: semPart + strictPart + loosePart + centralityPart };
                     });
                     // Sort by RRF score descending and take top N
                     return rrfResults.sort((a, b) => b.rrfScore - a.rrfScore).slice(0, candidateLimit);
@@ -14775,6 +15035,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 ...(impactOptions.mode !== "file" ? ["impact"] : []),
             ]);
             let selectedTarget;
+            let targetResolution;
             if (target && symbolPatterns.has(pattern)) {
                 const resolved = resolveSymbolRows(db, primary.path, target, selector);
                 if (resolved.ambiguity)
@@ -14804,6 +15065,26 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         ambiguity: resolved.ambiguity,
                     };
                 selectedTarget = resolved.selected;
+                // Graph health and target resolution are separate axes. A healthy,
+                // fresh graph answering `count: 0` for a misspelled symbol was
+                // byte-identical to one answering for real dead code, and the
+                // freshness stamp made the typo read as an authoritative negative
+                // (KNODIN-28). Say which of the two happened.
+                //
+                // `resolveSymbolRows` only sees the primary database, so a symbol
+                // defined in a federated repo must be checked before it is called
+                // missing — otherwise cross-repo queries would report every target
+                // as a typo.
+                targetResolution = resolved.selected
+                    ? "resolved"
+                    : allRepos.some((r) => {
+                        const stmt = r.db.query("SELECT filePath FROM symbols WHERE name = ? LIMIT 1");
+                        const row = stmt.get(target);
+                        stmt.finalize();
+                        return row != null;
+                    })
+                        ? "resolved"
+                        : "not-found";
             }
             const finish = (rows, extra = {}) => {
                 for (const row of rows) {
@@ -14822,6 +15103,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     count: rows.length,
                     results: rows.slice(0, cap),
                     ...(rows.length > cap ? { hasMore: true } : {}),
+                    ...(targetResolution ? { targetResolution } : {}),
                     ...extra,
                 };
             };
@@ -15004,26 +15286,41 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     const refs = pattern === "callers_of"
                         ? findCallersFederated(allRepos, defRepo, targetName, 1, new Set(), defFile, selectedTarget?.identity ?? null)
                         : findCalleesFederated(allRepos, defRepo, targetName, 1, new Set(), defFile, selectedTarget?.identity ?? null);
-                    const seen = new Set();
+                    // One row per caller symbol, but carrying every call site it has.
+                    // Collapsing to the first line lost the rest and made `count`
+                    // read as a call-site count (KNODIN-29).
+                    const byCaller = new Map();
                     const rows = [];
+                    let callSiteCount = 0;
                     for (const r of refs) {
                         const file = formatPath(r.repoPath || defRepo, r.filePath);
                         const key = `${r.symbol}|${file}`;
-                        if (seen.has(key))
+                        callSiteCount++;
+                        const existing = byCaller.get(key);
+                        if (existing) {
+                            if (r.lineNumber !== undefined && !existing.callSiteLines?.includes(r.lineNumber))
+                                existing.callSiteLines?.push(r.lineNumber);
                             continue;
-                        seen.add(key);
+                        }
                         const rr = (r.repoPath ? allRepos.find((x) => x.path === r.repoPath) : primary)?.db
                             .query("SELECT * FROM symbols WHERE name = ? AND filePath = ? LIMIT 1")
                             .get(r.symbol, r.filePath);
-                        rows.push({
+                        const row = {
                             symbol: r.symbol,
                             file,
                             line: r.lineNumber,
                             kind: r.kind ?? "call",
+                            callSiteLines: r.lineNumber !== undefined ? [r.lineNumber] : [],
                             ...(rr ? { identity: symbolIdentity(r.repoPath || defRepo, rr) } : {}),
-                        });
+                        };
+                        byCaller.set(key, row);
+                        rows.push(row);
                     }
-                    return finish(rows);
+                    for (const row of rows) {
+                        row.callSiteLines?.sort((a, b) => a - b);
+                        row.line = row.callSiteLines?.[0] ?? row.line;
+                    }
+                    return finish(rows, { callSiteCount });
                 }
                 case "imports_of": {
                     const stmt = db.query("SELECT DISTINCT toFile, kind FROM dependencies WHERE fromFile = ?");

package/dist/src/graph-query-health.js

@@ -101,15 +101,21 @@ export function decorateGraphQueryResult(value, graphState = "healthy", freshnes
         };
     }
     const root = value;
-    const noMatch = hasNoMatches(root) && root.ambiguity === undefined;
+    // An unresolved target is not a no-match: nothing was searched for. Calling
+    // it `no-match` is what let a misspelled symbol read as proof that nothing
+    // calls it (KNODIN-28). Ambiguity is exempted for the same reason.
+    const notFound = root.targetResolution === "not-found";
+    const noMatch = hasNoMatches(root) && root.ambiguity === undefined && !notFound;
+    const state = notFound ? "target-not-found" : noMatch ? "no-match" : graphState;
     return {
         ...root,
         ...(freshness ? { freshness } : {}),
+        ...(notFound && root.status === undefined ? { status: "target-not-found" } : {}),
         ...(noMatch && root.status === undefined ? { status: "no-match" } : {}),
         availability: {
-            state: noMatch ? "no-match" : graphState,
+            state,
             graphState,
-            outcome: noMatch ? "no-match" : "matches",
+            outcome: notFound ? "target-not-found" : noMatch ? "no-match" : "matches",
         },
     };
 }

package/dist/src/init.js

@@ -1458,6 +1458,87 @@ export async function initializeRepository(repo, options) {
         lifecycleLease.release();
     }
 }
+/**
+ * Rewrite lifecycle routing — the managed Git hooks and the background refresh
+ * script — without reading or writing a single line of agent configuration.
+ *
+ * This exists because a team-integrated repository whose hooks had died had no
+ * safe exit (KNODIN-31). `repair` fixes graph rows and leaves the dead indexer
+ * dead, so the schema drifts again; `init` rewrites tracked `AGENTS.md` /
+ * `GEMINI.md` / `.mcp.json`, which is churn every teammate diffs on a branch
+ * that has nothing to do with it; and `configure --scope personal` strips the
+ * shared block for everyone else on that branch. The one clean option,
+ * `init --scope personal`, is precisely the one refused in that state.
+ *
+ * So fault and remedy are matched in scope: the fault is in the hooks'
+ * contents, and this rewrites the hooks' contents. It deliberately does not
+ * index, does not touch graph rows, and never enters the `configureIntegration`
+ * block — a broken hook should not be able to change a scope preference. Run
+ * plain `knodin repair` alongside it when graph content is also damaged.
+ */
+export async function repairLifecycleRouting(repoPath, options) {
+    const resolvedRepo = path.resolve(repoPath);
+    if (runGit(resolvedRepo, ["rev-parse", "--is-inside-work-tree"]).trim() !== "true") {
+        throw new Error(`knodin repair --lifecycle: not a Git worktree: ${resolvedRepo}`);
+    }
+    const mirror = lookupMirror(resolvedRepo);
+    if (mirror) {
+        throw new Error(`knodin repair --lifecycle: ${resolvedRepo} is a read-only mirror of ${mirror.url}. Mirrors carry no lifecycle hooks by design, so there is no routing here to repair.`);
+    }
+    if (!path.isAbsolute(options.command[0])) {
+        throw new Error("knodin repair --lifecycle: packaged runtime command must be an absolute path");
+    }
+    const lifecycleLease = acquireRepairLease(resolvedRepo, "init");
+    try {
+        const knodinHooksDir = path.join(resolvedRepo, ".knodin", "hooks");
+        const hookInstallation = await prepareHookInstallation(resolvedRepo);
+        const hooksDir = hookInstallation.hooksDir;
+        await Promise.all([
+            fs.promises.mkdir(knodinHooksDir, { recursive: true }),
+            fs.promises.mkdir(hooksDir, { recursive: true }),
+        ]);
+        const backgroundPath = path.join(knodinHooksDir, "background-index.sh");
+        await fs.promises.writeFile(backgroundPath, backgroundScript(options.command), {
+            encoding: "utf-8",
+            mode: 0o755,
+        });
+        await fs.promises.chmod(backgroundPath, 0o755);
+        const hookManagerIntegration = installHookManagerIntegration(resolvedRepo);
+        for (const hookName of HOOK_NAMES) {
+            let preservedOriginal;
+            if (hookInstallation.trackedHooksDir) {
+                const relativeHook = `${hookInstallation.trackedHooksDir}/${hookName}`;
+                const sourceHook = path.join(resolvedRepo, relativeHook);
+                try {
+                    const stat = await fs.promises.stat(sourceHook);
+                    preservedOriginal =
+                        stat.isFile() && (stat.mode & 0o111) !== 0 ? `repo:${relativeHook}` : null;
+                }
+                catch {
+                    preservedOriginal = null;
+                }
+            }
+            await installManagedHook(hooksDir, hookName, preservedOriginal);
+        }
+        for (const entry of await fs.promises.readdir(hooksDir, { withFileTypes: true })) {
+            if (entry.isFile())
+                await preventLefthookAutoInstall(path.join(hooksDir, entry.name));
+        }
+        const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath, lifecycleLease.token);
+        await fs.promises.rm(path.join(knodinHooksDir, HOOK_FAILURE_FILE), { force: true });
+        return {
+            backgroundIndexer: ".knodin/hooks/background-index.sh",
+            hooksDirectory: path.relative(resolvedRepo, hooksDir) || ".",
+            gitHooks: [...HOOK_NAMES],
+            hookManagerIntegration,
+            lifecycleRefresh,
+            configurationChanges: [],
+        };
+    }
+    finally {
+        lifecycleLease.release();
+    }
+}
 async function matchesManagedFile(filePath, expected, executable) {
     try {
         const [content, stat] = await Promise.all([

package/dist/src/lifecycle-health.js

@@ -169,6 +169,41 @@ function recordedInterpreterIfMissing(backgroundScriptPath) {
     // wrong and the next environment without that fallback breaks silently.
     return recorded;
 }
+/**
+ * The interpreter a pre-fallback generated script pins, when it pins one.
+ *
+ * Scripts written before the `KNODIN_NODE` fallback (EASFDC-8497) invoke an
+ * absolute interpreter path with nothing to fall back to. Homebrew deletes its
+ * Cellar directory on upgrade, so `.../Cellar/node/<version>/bin/node`
+ * evaporates and every background refresh afterwards dies with exit 127 — in
+ * the background, where the only trace is a log file nobody reads. The graph
+ * then drifts until someone happens to run `status`. Observed across three
+ * repositories on one machine from a single `brew upgrade` (KNODIN-32), so the
+ * blast radius is every checkout initialized before the fix, not one.
+ *
+ * `recordedInterpreterIfMissing` cannot see this: it keys off a `KNODIN_NODE=`
+ * line, and these scripts have none, so the most dangerous shape reads as
+ * healthy. Detection is the absence of that line in a script that is otherwise
+ * recognisably ours.
+ *
+ * Returns null when the script is current, unreadable, or shaped unfamiliarly.
+ * A script we cannot parse is not evidence of a pinned interpreter, and
+ * guessing would invent a failure rather than report one.
+ */
+function pinnedInterpreterWithoutFallback(backgroundScriptPath) {
+    let contents;
+    try {
+        contents = fs.readFileSync(backgroundScriptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (/^KNODIN_NODE=/m.test(contents))
+        return null;
+    if (!contents.includes("hook-refresh"))
+        return null;
+    return /'(\/[^']*\/bin\/node)'/.exec(contents)?.[1] ?? null;
+}
 function readRefreshFailure(repo) {
     const failurePath = path.join(repo, ".knodin", "hooks", HOOK_FAILURE_FILE);
     if (!fs.existsSync(failurePath))
@@ -253,7 +288,15 @@ export function inspectLifecycleHealth(repoPath) {
         issues.push("background indexer is missing or not executable");
     const staleInterpreter = backgroundReady ? recordedInterpreterIfMissing(background) : null;
     if (staleInterpreter)
-        issues.push(`background indexer records a Node interpreter that no longer exists (${staleInterpreter}); run \`knodin init\` to rewrite the hook`);
+        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
+    // by construction — the script works right up until the next `brew upgrade`
+    // deletes the path out from under it, and then fails silently in the
+    // background. Waiting for the breakage would mean reporting it only after
+    // the graph had already drifted (KNODIN-32).
+    const pinnedInterpreter = backgroundReady && !staleInterpreter ? pinnedInterpreterWithoutFallback(background) : null;
+    if (pinnedInterpreter)
+        issues.push(`background indexer predates the interpreter fallback and pins ${pinnedInterpreter} with no alternative; a Node upgrade will break refresh silently — run \`knodin repair --lifecycle\` to rewrite the hook`);
     const lastError = readRefreshFailure(repo);
     if (lastError)
         issues.push(`${lastError} See .knodin/indexer.log for details`);
@@ -299,7 +342,7 @@ export function attachLifecycleHealth(repo, graph) {
         },
         repairSteps: [
             ...graph.repairSteps,
-            "Run `knodin init` to restore managed lifecycle hooks.",
+            "Run `knodin repair --lifecycle` to restore managed lifecycle hooks without touching agent configuration.",
             "Run `knodin status` again to verify graph and refresh-path health.",
         ],
         lifecycle,
@@ -312,7 +355,7 @@ export function attachRepairLifecycle(repo, result) {
         ...result,
         lifecycle,
         nextSteps: lifecycle.status === "degraded"
-            ? ["Run `knodin init` to restore lifecycle routing, then `knodin status`."]
+            ? ["Run `knodin repair --lifecycle` to restore lifecycle routing, then `knodin status`."]
             : [],
     };
 }

package/dist/src/repair-progress.js

@@ -23,6 +23,7 @@ export function parseRepairCliArgs(args) {
     let json = false;
     let jsonl = false;
     let plan = false;
+    let lifecycle = false;
     const seen = new Set();
     const markSeen = (flag) => {
         if (seen.has(flag))
@@ -42,6 +43,11 @@ export function parseRepairCliArgs(args) {
             plan = true;
             continue;
         }
+        if (argument === "--lifecycle") {
+            markSeen(argument);
+            lifecycle = true;
+            continue;
+        }
         if (argument === "--json" || argument === "--jsonl") {
             markSeen(argument);
             if (argument === "--json")
@@ -86,12 +92,18 @@ export function parseRepairCliArgs(args) {
     }
     if (json && jsonl)
         throw new Error("knodin repair: --json and --jsonl are mutually exclusive");
+    // `--plan` explains what a graph repair would do; a lifecycle repair does not
+    // touch the graph, so there is nothing for it to explain. Refusing beats
+    // printing a graph plan for a run that would not carry it out.
+    if (plan && lifecycle)
+        throw new Error("knodin repair: --plan and --lifecycle are mutually exclusive");
     return {
         progress,
         progressExplicit,
         progressIntervalMs,
         output: jsonl ? "jsonl" : json ? "json" : "human",
         plan,
+        lifecycle,
     };
 }
 export function createRepairPlan(health) {

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

@@ -1052,6 +1052,22 @@ function validateKnodinArgs(args) {
     if (args.client !== undefined &&
         !["claude", "codex", "gemini", "copilot", "antigravity"].includes(args.client))
         throw new Error("knodin: invalid client");
+    // `auditRange`/`auditBase`/`auditHead` select a range of pull requests for
+    // `prs`, and nothing else consumes them. `review` used to accept them and
+    // silently review HEAD~1..HEAD instead, returning `base: "HEAD~1"` under a
+    // full `staleness: fresh` envelope — so it did not merely fail to answer the
+    // question asked, it confidently answered a different one, and a caller who
+    // did not inspect `base` would read the result as authoritative for their
+    // range (KNODIN-27). An unused-parameter error is always better than that.
+    //
+    // The review equivalent is `diffScope: "compare"` with `from`/`toRevision`,
+    // which is what the CLI's `--scope compare --from X --to Y` maps to.
+    const auditOnly = ["auditRange", "auditBase", "auditHead"].filter((name) => args[name] !== undefined);
+    if (auditOnly.length > 0 && args.operation !== "prs")
+        throw new Error(`knodin ${args.operation}: ${auditOnly.join(", ")} ${auditOnly.length === 1 ? "is" : "are"} accepted only by \`prs\`` +
+            (args.operation === "review"
+                ? '; to review a revision range pass diffScope: "compare" with `from` and `toRevision`'
+                : ""));
 }
 function compactExplainSource(result) {
     const source = result.source

package/docs/releases/0.12.0.md

@@ -0,0 +1,281 @@
+# knodin 0.12.0
+
+Ten open defects worked as one batch, plus three more found while investigating
+them. Nearly all are the same failure in different clothing: a result that is
+*complete* and a result that is *empty* arriving in the same shape, so the reader
+cannot tell which one they got. One is worse than that, and it goes first.
+
+No schema change and no re-index. An earlier draft of this release carried both,
+for an embedding change that measured well on the test embedder and turned out to
+do nothing on the real model. That story is told below, because the way it was
+nearly shipped is more instructive than the fix — and because the same mistake,
+caught a second time, is what led to the retrieval benchmark this release adds.
+
+## `review` answered a different question and said nothing about it
+
+The MCP gateway accepted `auditRange`, `auditBase` and `auditHead` on `review`,
+discarded them, and reviewed `HEAD~1..HEAD` instead. The response reported
+`base: HEAD~1` truthfully — but carried `staleness: fresh`, `availability:
+healthy` and a full freshness envelope, so unless the caller happened to inspect
+`base`, it read as authoritative for the range they had asked about.
+
+Measured against a real branch, the difference was one changed file versus
+twenty. That is not a near-miss; it is a review of the wrong thing, presented
+with the same confidence as a review of the right thing. It was found while
+running a product validation, where the conclusion would otherwise have been
+"review does not catch this defect" — a false negative manufactured entirely out
+of discarded input, and reported as a finding.
+
+Those three parameters belong to `prs`, and only to `prs`; the schema had always
+said so and nothing enforced it. They are now refused on every other operation,
+and the refusal on `review` names the parameter that would have worked
+(`diffScope: "compare"` with `from`/`toRevision`). An unused-parameter error is
+always better than a confident answer to an unasked question.
+
+## `count: 0` could not tell a typo from dead code
+
+On a healthy, fresh graph, `knodin query callers_of someMisspelling` returned
+`count: 0`, `staleness: fresh`, exit 0 — byte-identical to the answer for a real
+symbol that genuinely has no callers.
+
+The uninitialized-graph case was fixed earlier and now fails loudly, which made
+this one worse rather than better: before that fix an empty result at least felt
+untrustworthy, and afterwards it arrived with a certificate. The freshness stamp
+certifies the **graph**; it says nothing about whether the **target** resolved.
+Those are separate axes and are now reported separately. A query for a symbol
+that exists in no open repository answers `targetResolution: "not-found"`,
+renders as `target-not-found` rather than `no-match`, and exits non-zero, since
+a misspelling is operator error rather than a negative result. A real symbol
+with no callers still answers `resolved` and exits 0 — that is the honest
+negative, and it is now distinguishable from the typo.
+
+This matters most for the symbol it is easiest to lose: a seam is *by
+definition* a well-documented symbol with no callers yet, so `count: 0` was
+destroying exactly the signal that would have said "use this one". One session
+nearly hand-rolled a duplicate of a blessed seam for that reason.
+
+## `callers_of` counted callers and read as call sites
+
+`callers_of` answers "which symbols call X", and its output — `count: N` above
+one line per row — reads as "N call sites, here they are". When a function calls
+the target twice, only the first line appeared and the count was lower than the
+number of call sites. Ground truth of four calls reported as three.
+
+Anyone sizing an edit from that count under-sizes it. Worse, the reporting
+session initially scored a correct answer as a bug, because cross-checking with
+grep found a call the tool had "missed" — it had not missed it, it had merged
+it. Each row now carries `callSiteLines` with every line for that caller, and
+the result carries `callSiteCount` alongside `count`, which is documented as
+counting rows. Renaming the field alone would not have been enough: it would
+have left the reader doing arithmetic they had no data for.
+
+## A team repo with dead hooks had no safe way out
+
+Every exit mutated something. Plain `repair` fixed graph rows and left the
+background indexer dead, so the schema drifted again. `init` rewrote tracked
+`AGENTS.md`, `GEMINI.md` and `.mcp.json` — churn every teammate diffs, on a
+branch that has nothing to do with it. `configure --scope personal` stripped the
+shared block for everyone else. The one clean option, `init --scope personal`,
+is precisely the one refused while tracked team integration is active.
+
+`knodin repair --lifecycle` rewrites the managed Git hooks and the background
+refresh script and touches nothing else — no indexing, no graph rows, and it
+never enters the agent-configuration path at any scope. Fault and remedy now
+match in scope: the fault is in the hooks' contents, so the hooks' contents are
+what changes. Every remediation message that used to say "run `knodin init`" for
+a lifecycle fault now points here instead.
+
+This does not settle the separate question of whether a per-developer scope
+preference should mutate team-shared tracked files. It removes the trap.
+
+## Hooks that predate the interpreter fallback are now named before they break
+
+Scripts generated before the `KNODIN_NODE` fallback pin an absolute Homebrew
+Cellar interpreter with nothing to fall back to. Homebrew deletes that directory
+on upgrade, so every background refresh afterwards dies with exit 127 — in the
+background, where the only trace is a log file — and the graph drifts until
+someone happens to run `status`. One `brew upgrade` did this to three
+repositories on one machine in a day.
+
+The existing check could not see these at all: it keys off a `KNODIN_NODE=`
+line, and these scripts have none, so the most dangerous shape read as healthy.
+Health now reports a script that predates the fallback **while its interpreter
+still exists**, because the whole point is that it is a time bomb rather than an
+already-detonated one. A script it cannot recognise is still left alone; an
+unparseable hook is not evidence of a pinned interpreter, and guessing would
+invent a failure rather than report one.
+
+## Search ranks a depended-upon implementation above its own fresh duplicate
+
+Semantic similarity alone ranked a minutes-old duplicate above the
+implementation it duplicated. The duplicate is short and made almost entirely of
+the query's own words; the canonical version is diluted by an actual body. The
+searcher read their own new leaf as evidence that nothing existed.
+
+Degree is now weighted into rank fusion, capped at about three rank positions.
+It is deliberately a small weight, because the opposite failure is equally real
+and lands on the *same symbols*: a seam is a documented symbol with no callers,
+and a large centrality weight would bury seams to fix duplicates — trading one
+silent miss for another. A connected implementation climbs past neighbours it
+was scoring near; it does not win from anywhere. Symbols with no inbound
+references are excluded from the centrality ranking rather than ranked last, so
+an uncalled symbol is never penalised, it only forgoes a boost it has no
+evidence for.
+
+An accompanying change — bounding the source body inside the embedding budget —
+was written, measured, justified in a comment, given a schema bump, and then
+**reverted before release**. On the deterministic bag-of-words embedder the suite
+runs, it raised the diluted implementation's similarity from 0.163 to 0.212. On
+the real MiniLM model it does nothing: across two body shapes, three query
+phrasings and both budgets, the duplicate wins all twelve times, and the cap
+never moves the winner. Its apparent benefit came from the test fixture, which
+emitted forty copies of one line — truncating identical lines removes a
+redundancy bag-of-words punishes and a transformer largely ignores.
+
+The general lesson is worth more than the change would have been: a short
+document made almost entirely of query tokens beats a long one under cosine
+similarity, and no reweighting of a single vector's inputs changes that. Graph
+degree is the right remedy here precisely because it is not a similarity signal.
+
+## Prose queries got no lexical signal at all, and now do
+
+A query phrased as prose did not surface the symbol whose docstring restates it;
+symbols sharing a word or two in their *identifier* won instead. The ticket
+framed this as docstring prose being under-weighted against code in the
+embedding. That premise turned out to be false — for the reported symbol the
+embedded text is already about 95% docstring, and it still lost.
+
+The actual cause was in rank fusion. The lexical channel selected the AND-matched
+set unless every semantic score was bit-identical, which never happens under a
+real model, so the OR set was computed on every query and discarded on every
+query. And for a query phrased as prose the AND clause is empty by construction:
+it demands one symbol containing every surviving query word, function words
+included. Nothing matches, so the lexical contribution was zero for every
+candidate and "hybrid search" was pure vector search. The docstring's BM25
+evidence existed the whole time, in the set being thrown away.
+
+Both operators are now fused as separate channels, the partial one at 0.75 weight
+and truncated to its top 30. Because the AND set is a subset of the OR set by
+construction, an exact match collects both terms and a partial match collects
+one — so the precision bonus falls out of that containment rather than needing
+machinery of its own. The weight buys a property worth stating: lexical evidence
+can rescue a symbol the embedder under-ranked, and cannot resurrect one the
+embedder judged irrelevant.
+
+A partial match must also clear a quorum: it has to echo at least two of the
+query's words. A single incidental token is not evidence, and this index cannot
+tell the difference unaided — FTS5 here has no stemming and does not split
+identifiers, so for "session authentication and token validations" the class
+that does the work matches *nothing* (its docstring says "sessions" and
+"validation") while a handler containing "session" matches once. Without the
+quorum that handler outranked the authenticator, and no weight fixed it: every
+value from 0.75 down to 0.15 flipped the same way, because the problem was which
+symbol earned credit rather than how much.
+
+Measured on the new benchmark below: **MRR 0.5178 → 0.754, recall@10 0.80 →
+0.925**, with 19 of 40 queries improving, 4 regressing and 17 unchanged — a
+two-sided exact sign test at p = 0.0026. Dev and test halves moved together,
+which is what you want when nothing was tuned against the labels. The largest
+gains were symbols that had been effectively unreachable: rank 24 → 1, 28 → 3,
+14 → 2.
+
+## Doc comments were being lost, and misattributed
+
+Two defects in how a doc comment is matched to the thing it documents. Both fed
+the embedding input and the FTS `summary` column, so both corrupted retrieval
+directly — and they point in opposite directions, which is why neither showed up
+as an obvious symptom.
+
+**Multi-line `//` comments kept only their last line.** tree-sitter gives each
+`//` line its own node and the extractor read a single previous sibling, so the
+loop meant to rejoin lines could never fire for this style. The first line of a
+doc comment is usually the sentence saying what the thing is for — exactly what a
+capability question matches on — so this silently removed the most useful text
+and left a grammatical fragment that still looked like a well-formed summary.
+Block comments are one node and were never affected, which is why the damage
+stayed invisible in codebases that prefer them.
+
+**And a symbol with no doc comment adopted its neighbour's.** The sibling walk
+stepped over as many as five non-comment nodes hunting for a comment, so prose
+written about one symbol was embedded against another. Measured on this
+repository before the fix: **857 of 1,329 documented symbols under `src/` — 64% —
+shared their summary text with another symbol**, and spot checks showed plain
+misattribution rather than genuine repetition, including an interface carrying a
+neighbouring function's docstring. After the fix, 718 symbols are documented and
+**none** share text.
+
+That second one is the worse of the pair. Absent prose merely loses a hit;
+misattributed prose manufactures a confident wrong one.
+
+A related gap is recorded but not fixed: a decorated declaration still never
+receives its doc comment, because the decorator is a sibling of the declaration
+but a child of the exporting statement. It was verified to predate both fixes and
+is pinned by a characterization test.
+
+## A benchmark for retrieval quality, and why it could not be a test
+
+`npm run bench:c103` measures whether a capability question phrased as prose
+finds the symbol implementing it, through the real ranker and the real embedding
+model, over knodin's own source at a pinned commit. Forty hand-written queries,
+15 dev / 25 test, MRR primary.
+
+It exists as an opt-in benchmark rather than a spec because the fast suite
+installs a deterministic bag-of-words embedder, and that embedder produces the
+**opposite** answer on exactly this case: an identifier match beats a docstring
+match on it, while the docstring wins by 2.75x on the real model. Two ranking
+assertions written for this release were deleted for pinning that inversion. A
+test that asserts the reverse of production is worse than no test — it fails
+changes that help users and passes changes that hurt them.
+
+So the fast suite now asserts only ranking properties no choice of embedder can
+change, which in practice means rank arithmetic over graph structure, and
+retrieval quality is measured where it can be measured honestly. The existing
+`c86` evaluation could not host this: it ranks raw text by exact cosine, never
+touching fusion or the ranking weights, and is saturated at recall@5 = 1.0.
+
+## What is not fixed
+
+**Mean-pooling dilution inside long docstrings.** Only one sentence of a
+multi-sentence docstring may be on topic, and averaged over the whole comment it
+becomes a minority of the vector while a short, entirely-on-topic competitor does
+not. Splitting docstrings into sentence chunks and max-pooling was prototyped
+against the real model and moves the reported symbol from rank 4 of 5 to rank 2 —
+but it needs roughly 1.5x the vectors, a composite primary key, and a re-embed
+migration.
+
+It is deliberately **not** in this release. The lexical fix above addressed the
+same failure for no migration at all, and the benchmark now says prose retrieval
+sits at MRR 0.754 with recall@10 of 0.95. Chunking should be re-measured against
+that new baseline before anyone pays for it — which is the whole reason the
+benchmark was built first.
+
+Worth stating plainly: the benchmark corpus is knodin's own source, and the
+defect was reported against a different codebase. The improvement is real and
+significant here; it has not been demonstrated there.
+
+## Smaller things
+
+`repair` now seeds from an indexed sibling worktree when there is **no** database
+at all, reflink-copying a baseline and reconciling only the differing paths
+instead of rebuilding the corpus from scratch. A database that exists but is
+damaged is deliberately excluded — that is the case `repair` exists for, and
+seeding it would replace a verifiable local rebuild with another checkout's
+state.
+
+`readGitHeadFast` is deleted. Its caller invoked it only when `.git` was absent,
+which was its own first bail-out, so the two conditions were exactly
+anti-correlated and the function could only ever return `null` — making the
+`&& headUnchanged` term it fed inert. Coverage confirmed zero hits across the
+whole suite. Git history settled which side was the bug: the fast HEAD read
+landed first, and the later `lease = 0` for git-backed repositories superseded
+it.
+
+Two timing-sensitive specs no longer produce false pre-push failures. Both had
+been widened only for instrumented coverage runs, on the theory that
+instrumentation caused the contention. It does not — the failures reproduce on
+ordinary uninstrumented runs under host load — and the uninstrumented run is
+exactly the one developers gate on. The budgets are now unconditional, matching
+the correction already recorded in `SUBPROCESS_BUDGET_MS`. A timeout that fires
+on a loaded machine reports a failure that did not happen, and a gate whose
+failures have to be re-run in isolation before they can be believed is not
+doing its job.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.11.0",
+	"version": "0.12.0",
 	"knodin": {
 		"compatibility": "breaking"
 	},
@@ -64,6 +64,7 @@
 		"docs/releases/0.10.7.md",
 		"docs/releases/0.10.8.md",
 		"docs/releases/0.11.0.md",
+		"docs/releases/0.12.0.md",
 		"docs/releases/0.3.0.md",
 		"docs/releases/0.4.0.md",
 		"docs/releases/0.4.1.md",
@@ -122,6 +123,7 @@
 		"check:hygiene": "node scripts/check-repository-hygiene.mjs",
 		"check:roadmap": "tsx scripts/check-roadmap.ts",
 		"verify:c79": "tsx scripts/verify-c79.ts",
+		"bench:c103": "tsx benchmarks/evaluations/c103-prose-retrieval/runner.ts",
 		"bench:c80": "tsx benchmarks/evaluations/c80-structural-routing/runner.ts",
 		"verify:c80": "tsx scripts/verify-c80.ts",
 		"bench:c81": "tsx benchmarks/evaluations/c81-powered-benchmark/runner.ts",