knodin 0.10.7 → 0.11.0

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

@@ -25,6 +25,24 @@ import { walkRepoFiles } from "./file-walker.js";
 const WORD_CHARACTER = /[\p{L}\p{N}_]/u;
 /** Upper bound on `TextMatch.enclosingText`, so one row cannot flood a preview. */
 const ENCLOSING_TEXT_LIMIT = 120;
+/**
+ * Largest file this search will read, in bytes.
+ *
+ * R1 deliberately drops the source-extension filter, so the walk reaches
+ * lockfiles, NDJSON dumps, fixtures and generated JSON as well as prose. Four
+ * mebibytes clears every hand-written source or document file by a wide margin
+ * while excluding the generated artefacts that would otherwise decide the
+ * process's peak memory. Oversized files are reported in `uncovered`, never
+ * dropped.
+ */
+export const MAX_SEARCHABLE_FILE_BYTES = 4 * 1024 * 1024;
+/**
+ * Largest number of matches this search will accumulate.
+ *
+ * Past this the result is no longer reviewable and the match objects alone
+ * dominate memory; the honest answer is a bounded list plus `truncated: true`.
+ */
+export const MAX_TEXT_MATCHES = 5_000;
 function isWordCharacter(value) {
     return value !== undefined && WORD_CHARACTER.test(value);
 }
@@ -164,86 +182,101 @@ function classifyAgainstTree(parser, content, raw) {
  * over a large repository touches enough files to reproduce it exactly.
  */
 export async function searchFiles(files, term, loadLanguage, newParser, options = {}) {
-    const caseSensitive = options.caseSensitive ?? true;
-    const matches = [];
-    const uncovered = [];
-    let filesSearched = 0;
+    const state = newSearchState();
     for (const { file, content } of files) {
-        const raw = findOccurrences(content, term, caseSensitive);
-        filesSearched++;
-        if (raw.length === 0)
-            continue;
-        let classified = null;
-        let language = null;
+        await searchOneFile(state, file, content, term, loadLanguage, newParser, options);
+        if (state.truncated)
+            break;
+    }
+    return { ...state, searched: true };
+}
+function newSearchState() {
+    return { matches: [], uncovered: [], filesSearched: 0, truncated: false };
+}
+/**
+ * Search and classify one file, appending to `state`.
+ *
+ * Takes a single file's content rather than a list so that a repository-wide
+ * search never has to hold more than one file in memory at once (KNODIN-24).
+ * Sets `state.truncated` when the match cap is reached; the caller is
+ * responsible for stopping there.
+ */
+async function searchOneFile(state, file, content, term, loadLanguage, newParser, options) {
+    const caseSensitive = options.caseSensitive ?? true;
+    const raw = findOccurrences(content, term, caseSensitive);
+    state.filesSearched++;
+    if (raw.length === 0)
+        return;
+    let classified = null;
+    let language = null;
+    try {
+        language = await loadLanguage(file);
+    }
+    catch {
+        // A grammar that will not load costs classification, not the match.
+        language = null;
+    }
+    if (language) {
+        const parser = newParser();
         try {
-            language = await loadLanguage(file);
+            parser.setLanguage(language);
+            classified = classifyAgainstTree(parser, content, raw);
         }
-        catch {
-            // A grammar that will not load costs classification, not the match.
-            language = null;
+        catch (error) {
+            if (isWasmAbort(error))
+                throw error;
+            // Parsing failed on this file only. The matches are still real and
+            // still reported — just without node evidence.
+            classified = null;
+            state.uncovered.push({
+                file,
+                reason: `matched but could not be parsed for classification: ${error instanceof Error ? error.message : String(error)}`,
+            });
         }
-        if (language) {
-            const parser = newParser();
+        finally {
             try {
-                parser.setLanguage(language);
-                classified = classifyAgainstTree(parser, content, raw);
+                parser.delete();
             }
-            catch (error) {
-                if (isWasmAbort(error))
-                    throw error;
-                // Parsing failed on this file only. The matches are still real and
-                // still reported — just without node evidence.
-                classified = null;
-                uncovered.push({
-                    file,
-                    reason: `matched but could not be parsed for classification: ${error instanceof Error ? error.message : String(error)}`,
-                });
-            }
-            finally {
-                try {
-                    parser.delete();
-                }
-                catch {
-                    /* a dead module has nothing to reclaim */
-                }
+            catch {
+                /* a dead module has nothing to reclaim */
             }
         }
-        const starts = lineStarts(content);
-        raw.forEach((match, position) => {
-            const lineIndex = lineIndexFor(starts, match.startIndex);
-            const lineStart = starts[lineIndex];
-            const nextStart = starts[lineIndex + 1] ?? content.length + 1;
-            const node = classified?.[position] ?? null;
-            matches.push({
-                file,
-                line: lineIndex + 1,
-                column: match.startIndex - lineStart + 1,
-                startIndex: match.startIndex,
-                endIndex: match.endIndex,
-                lineText: content.slice(lineStart, Math.max(lineStart, nextStart - 1)).replace(/\r$/, ""),
-                matchedText: match.matchedText,
-                caseMatchesQuery: match.matchedText === term,
-                withinLargerWord: isWordCharacter(content[match.startIndex - 1]) ||
-                    isWordCharacter(content[match.endIndex]),
-                classification: node ? node.classification : classifyByFileType(file),
-                basis: node ? "parse-node" : language ? "none" : "file-type",
-                nodeType: node ? node.nodeType : null,
-                enclosingText: node ? node.enclosingText : null,
-            });
+    }
+    const starts = lineStarts(content);
+    for (const [position, match] of raw.entries()) {
+        if (state.matches.length >= MAX_TEXT_MATCHES) {
+            state.truncated = true;
+            return;
+        }
+        const lineIndex = lineIndexFor(starts, match.startIndex);
+        const lineStart = starts[lineIndex];
+        const nextStart = starts[lineIndex + 1] ?? content.length + 1;
+        const node = classified?.[position] ?? null;
+        state.matches.push({
+            file,
+            line: lineIndex + 1,
+            column: match.startIndex - lineStart + 1,
+            startIndex: match.startIndex,
+            endIndex: match.endIndex,
+            lineText: content.slice(lineStart, Math.max(lineStart, nextStart - 1)).replace(/\r$/, ""),
+            matchedText: match.matchedText,
+            caseMatchesQuery: match.matchedText === term,
+            withinLargerWord: isWordCharacter(content[match.startIndex - 1]) || isWordCharacter(content[match.endIndex]),
+            classification: node ? node.classification : classifyByFileType(file),
+            basis: node ? "parse-node" : language ? "none" : "file-type",
+            nodeType: node ? node.nodeType : null,
+            enclosingText: node ? node.enclosingText : null,
         });
     }
-    return { matches, uncovered, filesSearched, searched: true };
 }
-/**
- * Read a file for searching, or say why it could not be.
- *
- * Binary detection is a NUL-byte sniff over the head of the file rather than an
- * extension list: the extensions that matter here are open-ended, and a
- * misjudged binary read produces garbage matches rather than an honest skip.
- */
-function readSearchable(absolute) {
+export function readSearchable(absolute) {
     let buffer;
     try {
+        const stats = fs.statSync(absolute);
+        if (stats.size > MAX_SEARCHABLE_FILE_BYTES)
+            return {
+                reason: `too large to search: ${stats.size} bytes exceeds the ${MAX_SEARCHABLE_FILE_BYTES}-byte limit`,
+            };
         buffer = fs.readFileSync(absolute);
     }
     catch (error) {
@@ -264,8 +297,15 @@ function readSearchable(absolute) {
  * Every file that could not be searched is returned in `uncovered` (R5). A
  * rename that silently skipped files would leave a half-renamed repository
  * looking finished, which is the worst available outcome for this operation.
+ *
+ * Files are read and searched one at a time. Reading them all up front held the
+ * entire non-pruned working tree in memory at once, which on a tree carrying
+ * generated dumps or vendored data is gigabytes for a single call (KNODIN-24).
+ *
+ * `readFile` is injected only so a test can observe that reads interleave with
+ * searching rather than preceding it.
  */
-export async function searchRepoText(repoPath, term, loadLanguage, newParser, options = {}) {
+export async function searchRepoText(repoPath, term, loadLanguage, newParser, options = {}, readFile = readSearchable) {
     let candidates;
     try {
         // Checked explicitly because `walkRepoFiles` swallows a missing directory
@@ -291,19 +331,21 @@ export async function searchRepoText(repoPath, term, loadLanguage, newParser, op
             ],
             filesSearched: 0,
             searched: false,
+            truncated: false,
         };
     }
-    const readable = [];
-    const uncovered = [];
-    for (const file of candidates) {
-        const outcome = readSearchable(path.join(repoPath, file));
-        if ("reason" in outcome)
-            uncovered.push({ file, reason: outcome.reason });
-        else
-            readable.push({ file, content: outcome.content });
-    }
-    const result = await searchFiles(readable, term, loadLanguage, newParser, options);
+    const state = newSearchState();
     // Files skipped at read time and files that failed classification are both
     // gaps in the same claim, so they are reported through one list.
-    return { ...result, uncovered: [...uncovered, ...result.uncovered] };
+    for (const file of candidates) {
+        const outcome = readFile(path.join(repoPath, file));
+        if ("reason" in outcome) {
+            state.uncovered.push({ file, reason: outcome.reason });
+            continue;
+        }
+        await searchOneFile(state, file, outcome.content, term, loadLanguage, newParser, options);
+        if (state.truncated)
+            break;
+    }
+    return { ...state, searched: true };
 }

package/dist/src/init.js

@@ -478,8 +478,15 @@ if ! mkdir "$LOCK_DIR" 2>/dev/null; then
   if [ -f "$LOCK_DIR/pid" ]; then
     LOCK_PID="$(cat "$LOCK_DIR/pid" 2>/dev/null || true)"
     if [ -n "$LOCK_PID" ] && ! kill -0 "$LOCK_PID" 2>/dev/null; then
-      rm -rf "$LOCK_DIR"
-      mkdir "$LOCK_DIR" 2>/dev/null || exit 0
+      # Claim the stale lock by RENAMING it: "rm -rf then mkdir" leaves a window
+      # in which two processes that both saw the same dead pid can each succeed.
+      # Only one rename can win, because the loser's source no longer exists.
+      if mv "$LOCK_DIR" "$LOCK_DIR.stale.$$" 2>/dev/null; then
+        rm -rf "$LOCK_DIR.stale.$$"
+        mkdir "$LOCK_DIR" 2>/dev/null || exit 0
+      else
+        exit 0
+      fi
     else
       exit 0
     fi
@@ -488,7 +495,25 @@ if ! mkdir "$LOCK_DIR" 2>/dev/null; then
   fi
 fi
 printf '%s\n' "$$" > "$LOCK_DIR/pid"
-trap 'rm -rf "$LOCK_DIR"; rm -f "$FAILURE_TMP"' EXIT HUP INT TERM
+# Release only a lock this process still owns. The previous handler removed
+# $LOCK_DIR unconditionally, so a script that had already lost the lock deleted
+# its SUCCESSOR's — and init sends SIGTERM here on every drain that outruns its
+# 30s spawnSync timeout, which made that the common case rather than the rare
+# one (KNODIN-23).
+knodin_release_lock() {
+  if [ "$(cat "$LOCK_DIR/pid" 2>/dev/null || true)" = "$$" ]; then
+    rm -rf "$LOCK_DIR"
+  fi
+  rm -f "$FAILURE_TMP"
+}
+trap 'knodin_release_lock' EXIT
+# Each signal exits explicitly. POSIX sh defers a trap until the foreground
+# command finishes and then RESUMES where it left off, so a handler that only
+# cleaned up dropped the lock and kept draining — two processors at once, and
+# Ctrl-C failed to cancel a foreground run at all.
+trap 'knodin_release_lock; trap - EXIT; exit 129' HUP
+trap 'knodin_release_lock; trap - EXIT; exit 130' INT
+trap 'knodin_release_lock; trap - EXIT; exit 143' TERM
 LOG_PATH="$REPO_ROOT/.knodin/indexer.log"
 if [ -f "$LOG_PATH" ]; then
   LOG_BYTES="$(wc -c < "$LOG_PATH" 2>/dev/null | tr -d '[:space:]')"

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

@@ -214,9 +214,17 @@ export class RepositoryWorker extends EventEmitter {
             if (signal.aborted)
                 throw codedError("KNODIN_CLIENT_DISCONNECTED", "MCP client disconnected before worker dispatch");
             if (!this.child) {
+                // Prune HERE as well as in `exited`. Once this gate throws, no child is
+                // spawned, so no exit event ever fires to prune the array — filtering
+                // only on exit turned the 60s rate window into a permanent per-repository
+                // latch that outlived whatever caused the crashes, and the cached
+                // RepositoryWorker is never evicted, so only a gateway restart cleared
+                // it (KNODIN-17).
+                const startedAt = Date.now();
+                this.restartTimes = this.restartTimes.filter((at) => startedAt - at < RESTART_WINDOW_MS);
                 if (this.restartTimes.length >= MAX_RESTARTS)
-                    throw codedError("KNODIN_RESTART_LIMIT", "graph worker restart limit reached");
-                this.restartTimes.push(Date.now());
+                    throw codedError("KNODIN_RESTART_LIMIT", `graph worker restarted ${MAX_RESTARTS} times within ${RESTART_WINDOW_MS / 1000}s; it will be retried once that window elapses`);
+                this.restartTimes.push(startedAt);
             }
             const startup = this.start();
             const remainingForStartup = Math.max(1, deadlineAt - Date.now());

package/dist/src/structural-fast-path.js

@@ -169,6 +169,55 @@ function directFile(repo, filePath) {
         symbols: directSymbols(filePath, content),
     };
 }
+function directoryOf(filePath) {
+    const slash = filePath.lastIndexOf("/");
+    return slash === -1 ? "." : filePath.slice(0, slash);
+}
+function extensionOf(name) {
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? name.slice(dot) : null;
+}
+/**
+ * True when every directory the aggregate covers holds only files the snapshot
+ * already knows about.
+ *
+ * The indexable extensions are taken from the snapshot's own file list rather
+ * than hardcoded, so this stays calibrated to whatever the walker actually
+ * indexed. Membership is tested against the WHOLE snapshot, not the filtered
+ * subset, so a sibling that is indexed but outside the caller's target does not
+ * read as an omission.
+ */
+function snapshotCoversDirectories(repo, snapshot, covered) {
+    const indexed = new Set((snapshot?.files ?? []).map((file) => file.path));
+    if (indexed.size === 0)
+        return false;
+    const extensions = new Set();
+    for (const known of indexed) {
+        const extension = extensionOf(known.slice(known.lastIndexOf("/") + 1));
+        if (extension)
+            extensions.add(extension);
+    }
+    for (const directory of new Set(covered.map((file) => directoryOf(file.path)))) {
+        let entries;
+        try {
+            entries = fs.readdirSync(path.resolve(repo, directory), { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const extension = extensionOf(entry.name);
+            if (!extension || !extensions.has(extension))
+                continue;
+            const relative = directory === "." ? entry.name : `${directory}/${entry.name}`;
+            if (!indexed.has(relative))
+                return false;
+        }
+    }
+    return true;
+}
 export function runStructuralFastPath(repo, pattern, target, limit = 100) {
     const snapshot = readStructuralSnapshot(repo);
     if (!snapshot && pattern !== "file_summary")
@@ -195,7 +244,7 @@ export function runStructuralFastPath(repo, pattern, target, limit = 100) {
     let fingerprint;
     let fresh = false;
     if (pattern === "project_overview") {
-        fresh = matching.every((file) => {
+        const unchanged = matching.every((file) => {
             try {
                 const stat = fs.statSync(path.resolve(repo, file.path));
                 return stat.size === file.sizeBytes && stat.mtimeMs === file.mtimeMs;
@@ -204,6 +253,20 @@ export function runStructuralFastPath(repo, pattern, target, limit = 100) {
                 return false;
             }
         });
+        // A size+mtime sweep can only ever prove that the files the snapshot
+        // ALREADY knows about are unchanged. A file added since the snapshot is not
+        // in that set, so it was never checked, never counted, and never mentioned
+        // — while the overview still reported itself "fresh" (KNODIN-25). So also
+        // read back the directories being aggregated and look for an indexable
+        // sibling the snapshot has never seen.
+        //
+        // Known bound: this sees additions to directories the snapshot already
+        // covers, which is where source files are overwhelmingly added. A brand new
+        // top-level directory is still missed, because recognising one would mean
+        // re-deriving the walker's prune rules here and re-walking the tree, which
+        // is the cost this fast path exists to avoid. `upgrade` already points at
+        // the full `architecture_overview` query for callers that need certainty.
+        fresh = unchanged && snapshotCoversDirectories(repo, snapshot, matching);
         const directories = new Map();
         for (const file of matching) {
             const directory = file.path.includes("/") ? file.path.split("/", 1)[0] : ".";

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

@@ -70,10 +70,8 @@ export async function closeKnodinToolEngine() {
     if (initializedEngine)
         await initializedEngine.close();
     initializedEngine = null;
-    compactReadyRepos.clear();
 }
 const localTelemetry = [];
-const compactReadyRepos = new Set();
 let cachedSchemaTokens;
 function gatewaySchemaTokens() {
     cachedSchemaTokens ??= countOutputTokens(JSON.stringify(buildDocumentedKnodinTools()[0]?.inputSchema ?? {}));
@@ -82,15 +80,24 @@ function gatewaySchemaTokens() {
 function inspectGatewayGraphHealth(repo) {
     return inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
 }
+/**
+ * Probe on EVERY compact call, exactly as the non-compact path does.
+ *
+ * This used to latch a repository as ready after one successful probe and never
+ * look again for the life of the process. Nothing invalidated that latch —
+ * `closeKnodinToolEngine` clears it but has no production caller — so once
+ * `.knodin/` was deleted or re-inited from another terminal, a long-lived MCP
+ * server kept answering compact queries against a database the open path had
+ * silently recreated as an empty schema (`CREATE TABLE IF NOT EXISTS`). The
+ * result was "no matches": indistinguishable from a true negative, and the exact
+ * confident-but-wrong answer this product exists to avoid (KNODIN-18).
+ *
+ * The probe is cheap — `engine.status(..., { audit: "cached" })` — so the latch
+ * was buying very little in exchange for that failure mode.
+ */
 async function compactGraphUnavailable(repo) {
-    const key = nodePath.resolve(repo);
-    if (compactReadyRepos.has(key))
-        return null;
     const health = await inspectGatewayGraphHealth(repo);
-    if (!health.available)
-        return health;
-    compactReadyRepos.add(key);
-    return null;
+    return health.available ? null : health;
 }
 /** Runs `fn`, converting any thrown error into a structured `{ error }` result
  * instead of letting it escape into the stdio transport. Extracted from the

package/docs/REPOSITORIES-AND-WORKTREES.md

@@ -24,6 +24,36 @@ Results distinguish:
 - stale linked-worktree metadata;
 - an unrelated repository under the same discovery root.
 
+### Graphs are per-worktree
+
+A linked worktree carries its own `.knodin` with its own graph, `indexedHead`,
+and freshness. A healthy main checkout does not cover it, so a worktree created
+by `git worktree add` has **no graph until `knodin init` runs inside it**.
+
+`git worktree add` creates no `.knodin` of its own — the directory is knodin's,
+written by `init` and by the managed lifecycle hooks. Where those hooks are
+already installed in the repository, a new worktree can therefore appear to have
+a `.knodin` while holding no graph at all, which is the more confusing shape of
+this: the directory exists, and it is empty of anything that can answer.
+
+That does not mean a new worktree pays for a full index. `init` selects the
+already-indexed sibling worktree closest in commit distance, reflink-copies its
+baseline where the filesystem supports it, reconciles only the paths that differ
+between that sibling's `indexedHead` and this HEAD, deep-audits the result, and
+promotes it only if it is healthy — falling back to a full index when no
+schema- and build-compatible sibling exists. `KNODIN_DISABLE_WORKTREE_SEED=1`
+forces the full path.
+
+Seeding is on the `init` path only, which is why an uninitialized worktree is
+steered to `init` rather than `repair`: both produce a correct index, but
+`repair` rebuilds from scratch.
+
+Nothing silently answers from the wrong graph in that state: structural queries
+refuse with `available: false`, `state: not-initialized`, and exit code 1 rather
+than returning an empty result, and status leads its remediation with the
+per-worktree model and `knodin init`. Read a refusal as "this checkout was never
+indexed", never as "there is nothing here to find".
+
 ### Opt-in repository signals
 
 `repos discover --json --signals` adds a deterministic `signals` object to

package/docs/releases/0.10.8.md

@@ -0,0 +1,165 @@
+# knodin 0.10.8
+
+One change, prompted by a field report from an agent session that built a
+duplicate implementation of a hook that already existed. Most of that report
+described behaviour knodin already has; the part it got right is fixed here.
+
+## A linked worktree with no graph now says so in its remediation
+
+`git worktree add` gives you a checkout with no graph in it. Graphs are
+**per-worktree**, so a perfectly healthy main checkout tells you nothing about
+the worktree you are standing in — and that makes the missing graph *more*
+surprising, not less.
+
+Git creates no `.knodin`; that directory is knodin's, written by `init` and by
+the managed lifecycle hooks. Where those hooks are already installed, a fresh
+worktree can present a `.knodin` that holds no graph — which is the more
+confusing shape of this, and the one the original report hit.
+
+Until now, status in that state produced generic remediation:
+
+```
+remediation:
+  - Run `knodin repair` to create the local index.
+  - Run `knodin status` again to verify health.
+```
+
+That guidance works — `repair` does build the index from cold, and then tells
+you to run `init` for lifecycle routing. What it does not do is explain *why*
+there was no index in a repository whose main checkout is fine. A reader who
+does not already know the per-worktree model has no way to tell "this checkout
+was never indexed" from "there is nothing here to find", and the second reading
+is the one that quietly confirms whatever hypothesis sent them looking.
+
+A linked worktree now leads with the model and the fix, on both the
+machine-readable `remediation` and the human `status` line:
+
+```
+Run `knodin init` here: graphs are per-worktree and this one has none of its
+own, so the main checkout's graph does not cover it. `init` seeds from an
+indexed sibling worktree where one exists rather than rebuilding from scratch.
+```
+
+Ordinary checkouts are unchanged. Detection reads the `.git` file's `gitdir:`
+pointer and requires a `commondir` beside it — no subprocess, no registry read,
+and it works on a repository too damaged to answer anything else.
+
+A `.git` **file** alone is not enough, and treating it as enough was wrong in
+the first cut of this fix: submodules and `--separate-git-dir` clones use one
+too, and neither has a main checkout whose graph could cover it, so they would
+have been handed an explanation that does not apply to them. `commondir` is
+what actually distinguishes a linked worktree.
+
+The check lives in a new `src/engine/git-layout.ts` rather than in the engine,
+for a reason worth stating. `engine/index.ts` carries a pinned budget on direct
+`fs` reads, because a sealed artifact answers with no working tree and a reader
+that touches the filesystem there gets ENOENT — which the nearest guard turns
+into `""` or `null`, and which reads downstream as "this symbol has no body"
+rather than "this was not covered". Git *metadata* is categorically outside
+that concern: a sealed artifact has no `.git` at all, so routing these reads
+through the sealed resolver would add a branch that can never execute. Saying
+so in the layout is more honest than spending budget the engine reserves for
+source reads — and it makes the check directly unit-testable, which it was not
+as an engine-private helper.
+
+Its spec covers every branch (100% of statements and branches): a plain
+directory, an ordinary checkout, a real linked worktree, a real submodule, a
+real `--separate-git-dir` clone, a malformed `.git` file naming no gitdir, and a
+dangling pointer whose administrative directory was pruned.
+
+### Why `init` and not `repair` here
+
+`repair` does build the index from cold, and for an ordinary checkout it stays
+the right advice. In a linked worktree it is the *expensive* answer: seeding
+lives on the `init` path only (`indexOrSeed`), so `repair` rebuilds from scratch
+while `init` reflink-copies an indexed sibling's baseline, reconciles only the
+paths that differ between that sibling's `indexedHead` and this HEAD,
+deep-audits the candidate, and promotes it only if it passes — falling back to a
+full index when no compatible sibling exists.
+
+The human `status` renderer had been computing its own one-line advice and
+ignoring `repairSteps` entirely, so the first fix reached the JSON surface and
+not the line a person actually reads. It now defers to the step the engine
+already wrote. Measured on a 20-file fixture, `init` in a fresh worktree with an
+indexed sibling completes in about three seconds.
+
+Worth stating plainly, because the surprise runs the other way from the cost:
+the per-worktree model does **not** mean a new worktree pays for a full index.
+
+## What the same report claimed that measurement did not support
+
+Recorded because acting on any of these would have been a regression, and
+because each was reported in good faith from accumulated notes rather than from
+a run against this release.
+
+**"Structural queries return empty rather than erroring on an uninitialized
+graph."** They do not, and have not for some time. Against a committed
+repository with no index, `knodin query callers_of <symbol>` returns
+`available: false`, `status: unavailable`, `state: not-initialized`, the full
+status envelope, and **exit code 1**. The same holds for `impact`, `dead_code`,
+`tests_for`, and `file_summary`, on both the CLI and the MCP gateway — both
+route through the same `inspectGraphQueryHealth` gate before and after the
+operation runs. There was no empty result set to fix.
+
+This one matters most, because an empty structural result that agrees with your
+hypothesis is the worst failure this tool could have. It is worth restating that
+the gate is there, and that it fails loudly on both surfaces.
+
+**"`knodin init --scope personal` exits 0 having done nothing."** It exits **1**.
+The refusal is thrown, and every non-`agent-event` throw reaches the top-level
+handler, which prints to stderr and exits 1. Reproduced against a repository with
+tracked team integration active.
+
+**"A backgrounded `knodin repair` produces no progress output."** Repair emits
+ordered per-phase progress on stderr — audit, planning, file reconciliation,
+symbol identities, embeddings, orphan cleanup, verification — and finishes with a
+verified summary naming indexed file and symbol counts.
+
+Both of these turned out to have the same cause, since confirmed by the
+reporter: the commands were run through `| tail`. A pipeline's exit status is the
+last command's, so `init`'s 1 was recorded as `tail`'s 0; and `tail` flushes
+nothing until the stream closes, so a capture file read mid-run looked empty
+while repair was in fact reporting every phase. Neither surface changed. Worth
+naming because one habit produced two bug reports against the wrong component.
+
+## Not changed here: semantic search ranking
+
+A follow-up from the same session measured something real and unaddressed: on a
+healthy graph, `"hands-free voice conversation mode hook with barge-in"` ranked a
+constant list (`BARGE_IN_PHRASES`, 0.588) and the caller's own minutes-old
+duplicate (0.552) above the canonical 513-line implementation, which did not
+appear in the top hits at all. Mechanism-shaped phrasing
+(`"voice pipeline auto restart mic after TTS"`) put the canonical hook at #2,
+0.517.
+
+So feature-shaped phrasing — the phrasing a developer uses when asking "does this
+already exist?" — ranked worst for exactly that question, and surfaced the new
+duplicate as apparent confirmation. Centrality data the fix would need
+(in-degree, community membership) is already in the graph and already in the
+output; it is not weighted into ranking.
+
+That is a ranking change with its own evaluation burden and it is not bundled
+into a remediation-string fix. It is recorded here so it is not rediscovered from
+scratch.
+
+## The pre-push test gate was not gating
+
+Found because this release's own broken commit sailed through it.
+
+`lefthook.yml`'s `quality-gates` block ran `bun run test:coverage` and then
+`sh scripts/run-sonar-scan.sh` as two lines of one shell block with no
+`set -e`. A shell block's exit status is its **last** command's, so a failing
+suite followed by a passing Sonar scan reported success, and the push was
+allowed. The suite printed `1 failed | 2058 passed` and
+`script "test:coverage" exited with code 1`, and the push completed anyway.
+
+`set -e` now leads the block. Coverage thresholds and Sonar were unaffected;
+what was broken is that a red suite could not stop a push.
+
+## Verification
+
+`npm test`, `npm run lint`, and `npm run typecheck` pass. The new behaviour is
+pinned by a test in `src/__tests__/unit/index-health.spec.ts` that builds a real
+linked worktree with `git worktree add`, asserts the per-worktree line leads its
+remediation, and asserts the ordinary checkout keeps repair-first guidance with
+no per-worktree line.