knodin 0.10.6 → 0.10.8

package/dist/bin/cli.js

@@ -456,10 +456,17 @@ function formatStatusHuman(result) {
         ? result.missing.records[0]
         : (result.missing.files[0] ?? result.missing.records[0]);
     const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
-    const repairCommand = result.lifecycle?.status === "degraded" &&
-        result.missing.records.every((record) => result.lifecycle?.issues.includes(record))
-        ? "Run `knodin init`."
-        : "Run `knodin repair`.";
+    // A linked worktree with no database is the one case where `repair` is both
+    // the wrong first step and the expensive one: `init` seeds from an indexed
+    // sibling and reconciles only what differs, while `repair` builds from
+    // scratch. The engine has already worked out that this is that case, so
+    // defer to the step it wrote rather than recomputing the judgement here.
+    const worktreeStep = result.repairSteps?.find((step) => step.includes("per-worktree"));
+    const repairCommand = worktreeStep ??
+        (result.lifecycle?.status === "degraded" &&
+            result.missing.records.every((record) => result.lifecycle?.issues.includes(record))
+            ? "Run `knodin init`."
+            : "Run `knodin repair`.");
     return `Graph or lifecycle needs repair: ${outstanding} issue(s) found (${coverage}).${detail} ${repairCommand}\n${lifecycleLine}${integrationLine}`;
 }
 function humanLabel(key) {

package/dist/src/credential-patterns.js

@@ -0,0 +1,90 @@
+/**
+ * One credential-pattern set, shared by every redactor.
+ *
+ * knodin previously carried two independent lists — one in `diagnostics.ts` for
+ * recorded failures, one in `output-compression.ts` for captured command output
+ * — and they drifted apart in OPPOSITE directions. Diagnostics knew Slack and
+ * OpenAI but not AWS or JWTs; output compression knew AWS and JWTs but missed
+ * Slack, OpenAI and GitHub's fine-grained tokens. Neither list was a superset of
+ * the other, so a credential redacted on one path was disclosed on the other,
+ * and patching either one alone would only let them drift again (KNODIN-11).
+ *
+ * Callers keep their own replacement text: diagnostics collapses a match to a
+ * single marker, output compression names the provider. `preservedGroups` is
+ * what makes that possible — the leading captures a caller may echo back
+ * verbatim, so `password=` survives while its value does not.
+ *
+ * Fresh `RegExp` objects are built per call. A shared global regex carries
+ * `lastIndex` between uses, which turns a redactor into something that depends
+ * on what it scrubbed previously.
+ */
+export function credentialPatterns() {
+    return [
+        {
+            // `name=value` in any of its spellings. An optional auth scheme is
+            // consumed BEFORE the value, because `authorization: Bearer <token>`
+            // otherwise matches only the word "Bearer" — redacting the label and
+            // preserving the credential, exactly inverted (KNODIN-10).
+            label: "credential",
+            pattern: /\b(authorization|password|passwd|secret|token|api[_-]?key)(\s*[:=]\s*)(?:(?:bearer|basic|digest|token)\s+)?[^\s,;]+/gi,
+            preservedGroups: 2,
+        },
+        {
+            // GitHub issues every format with an UNDERSCORE. A hyphen-only pattern
+            // matched a shape GitHub never mints and missed every shape it does, so
+            // both separators are accepted. `github_pat` is listed explicitly: it
+            // does not fit the gh[pousr] shape.
+            label: "github-token",
+            pattern: /\b(?:gh[pousr]|github_pat)[-_]\w{20,}\b/g,
+            preservedGroups: 0,
+        },
+        {
+            label: "slack-token",
+            pattern: /\bxox[baprse]-[A-Za-z0-9-]{10,}\b/g,
+            preservedGroups: 0,
+        },
+        {
+            label: "openai-key",
+            pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+            preservedGroups: 0,
+        },
+        {
+            label: "aws-access-key",
+            pattern: /\bAKIA[A-Z0-9]{16}\b/g,
+            preservedGroups: 0,
+        },
+        {
+            label: "jwt",
+            pattern: /\beyJ[\w-]{8,}\.[\w-]{8,}\.[\w-]{8,}\b/g,
+            preservedGroups: 0,
+        },
+        {
+            // Bearer outside an `authorization:` assignment — a bare header line, or
+            // a curl command echoed into a log.
+            label: "bearer-token",
+            pattern: /\b(Bearer\s+)[-\w.~+/]{12,}=*/gi,
+            preservedGroups: 1,
+        },
+    ];
+}
+/**
+ * Apply every shared pattern, letting the caller render the replacement.
+ *
+ * `marker` receives the provider label; preserved groups are prepended to
+ * whatever it returns.
+ */
+export function redactCredentials(text, marker) {
+    let result = text;
+    let count = 0;
+    for (const { label, pattern, preservedGroups } of credentialPatterns()) {
+        result = result.replace(pattern, (...values) => {
+            count++;
+            const kept = values
+                .slice(1, 1 + preservedGroups)
+                .map((value) => (typeof value === "string" ? value : ""))
+                .join("");
+            return `${kept}${marker(label)}`;
+        });
+    }
+    return { text: result, count };
+}

package/dist/src/diagnostics.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import zlib from "node:zlib";
 import { compareBytes } from "./compare.js";
+import { redactCredentials } from "./credential-patterns.js";
 const CONFIG_PATH = ".knodin/diagnostics/config.json";
 const JOURNAL_PATH = ".knodin/diagnostics/events.jsonl";
 const JOURNAL_LOCK_PATH = ".knodin/diagnostics/events.lock";
@@ -528,19 +529,17 @@ function scrubText(raw, repo) {
     };
     for (const exact of [repo, os.homedir()].filter(Boolean).sort((a, b) => b.length - a.length))
         replace(new RegExp(exact.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`), "g"), "<path>");
-    // Either separator. GitHub issues its tokens with an UNDERSCORE after the
-    // prefix, so a hyphen-only pattern matched a shape GitHub never mints and
-    // missed every shape it does — a real token in an error message survived
-    // scrubbing and reached the bundle a user shares (KNODIN-10). Slack and
-    // OpenAI really do use a hyphen, so both separators must be accepted.
-    replace(/\b(?:ghp|github_pat|sk|xox[baprs])[-_][-A-Za-z0-9_]{10,}\b/g, "<secret>");
-    // The value pattern stops at whitespace, so `authorization: Bearer <token>`
-    // used to match only the word "Bearer" and leave the credential in place —
-    // the standard header form leaked the one thing worth redacting (KNODIN-10).
-    // An optional scheme is consumed first so the credential after it is the
-    // part that gets replaced. Only known schemes are skipped, so an ordinary
-    // `password=x next word` still redacts one value rather than eating prose.
-    replace(/\b(?:password|passwd|token|secret|api[_-]?key|authorization)\s*[=:]\s*(?:(?:bearer|basic|digest|token)\s+)?[^\s,;]+/gi, "<secret>");
+    // Provider credentials, from the set shared with output-compression (see
+    // credential-patterns.ts). These used to be maintained here separately, and
+    // the two lists drifted: this one knew Slack and OpenAI but not AWS keys or
+    // JWTs, while output compression knew those and missed these. A credential
+    // safe on one path was disclosed on the other (KNODIN-11).
+    //
+    // `redactCredentials` counts its own replacements, so they are added to the
+    // running total rather than counted by the local `replace` helper.
+    const credentials = redactCredentials(value, () => "<secret>");
+    value = credentials.text;
+    redactions += credentials.count;
     replace(/\b[A-Z]:\\(?:[^\s<>:"|?*]+\\)*[^\s<>:"|?*]*/g, "<path>");
     replace(/(?:^|[\s('"`])\/(?:[^\s)'"`]+\/)*[^\s)'"`]*/g, "<path>");
     replace(/\b(?:[A-Za-z0-9_.-]+\/)+(?:[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,12})\b/g, "<path>");

package/dist/src/engine/git-layout.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Git checkout-layout questions, kept out of the engine on purpose.
+ *
+ * `engine/index.ts` carries a pinned budget on direct `fs` reads
+ * (`sealed-reader-inventory.spec.ts`) because a sealed artifact answers with no
+ * working tree: a reader that touches the filesystem there gets ENOENT, which
+ * the nearest guard turns into `""` or `null`, and that 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, and these functions are never on a source-content path — so
+ * routing them through the sealed resolver would add a branch that can never
+ * execute. Keeping them here says that in the layout rather than by spending
+ * budget the engine reserves for source reads, and it makes them directly
+ * unit-testable, which they are not as engine-private helpers.
+ */
+/**
+ * True only for a `git worktree add` checkout.
+ *
+ * A linked worktree's `.git` is a FILE pointing at an administrative directory
+ * under the main checkout, and that directory contains `commondir` naming the
+ * shared repository.
+ *
+ * The `.git` file alone is NOT sufficient and treating it as sufficient is a
+ * live bug: submodules and `--separate-git-dir` clones use one too, and neither
+ * has a main checkout whose graph could cover it, so per-worktree guidance would
+ * be actively wrong for them. `commondir` is the marker that actually
+ * distinguishes the case.
+ */
+export function isLinkedWorktree(repo) {
+    const marker = path.join(repo, ".git");
+    try {
+        // An ordinary checkout keeps a `.git` directory; `statSync` throws when
+        // there is no `.git` at all, which is an ordinary case — knodin indexes
+        // plain directories too.
+        if (!fs.statSync(marker).isFile())
+            return false;
+        const pointer = fs.readFileSync(marker, "utf8").trim();
+        const gitDir = /^gitdir:\s*(.+)$/m.exec(pointer)?.[1]?.trim();
+        if (!gitDir)
+            return false;
+        return fs.existsSync(path.join(path.resolve(repo, gitDir), "commondir"));
+    }
+    catch {
+        // Every read is inside the guard on purpose. This is best-effort detection
+        // reached from the missing-database remediation path, and that path has to
+        // answer: an unreadable `.git`, or one that disappears between the stat and
+        // the read, must degrade to "not a worktree" rather than crash `status`.
+        return false;
+    }
+}

package/dist/src/engine/index.js

@@ -32,6 +32,7 @@ import { allocateCandidate, assertCandidate, discardCandidateFiles, listCandidat
 import { computeSimilarity, generateEmbedding, generateEmbeddings, } from "./embeddings.js";
 import { walkRepoFiles } from "./file-walker.js";
 import { clearGitHistorySignalCache, collectGitHistorySignals, } from "./git-history.js";
+import { isLinkedWorktree } from "./git-layout.js";
 // Runtime import, but not a cycle: parse-pool imports only TYPES from here,
 // which erase at compile time. parse-worker's runtime import of this module
 // resolves inside the worker thread, never in this one.
@@ -8779,26 +8780,28 @@ export async function getOrInitDb(repoPath, options = {}) {
             else {
                 const stateDir = resolveStateDir(normalizedPath);
                 await fs.promises.mkdir(stateDir, { recursive: true });
-                // Ensure .knodin is in .gitignore. Skipped for mirrors: their state
-                // lives outside the clone, and the clone must stay byte-identical to
-                // the remote so a refetch has nothing of ours to discard.
+                // Ensure .knodin is ignored, through `.git/info/exclude` rather than
+                // `.gitignore`.
+                //
+                // `.gitignore` is a SHARED file: it is tracked by convention, so
+                // writing it put a change into someone's working tree that they did
+                // not ask for and would carry into their next commit. That is the
+                // one thing `knodin init --scope personal` promises not to do, and
+                // this ran regardless of scope — a bare `knodin index` did it too
+                // (KNODIN-1).
+                //
+                // `.git/info/exclude` has the same effect and is repo-local: git
+                // never commits it, so nothing reaches a diff or a teammate.
+                //
+                // Skipped for mirrors: their state lives outside the clone, and the
+                // clone must stay byte-identical to the remote so a refetch has
+                // nothing of ours to discard.
                 if (mayWriteToRepository(normalizedPath)) {
                     try {
-                        const gitignorePath = path.join(normalizedPath, ".gitignore");
-                        let gitignoreContent = "";
-                        if (fs.existsSync(gitignorePath)) {
-                            gitignoreContent = await fs.promises.readFile(gitignorePath, "utf-8");
-                        }
-                        const lines = gitignoreContent.split("\n").map((l) => l.trim());
-                        if (!lines.includes(".knodin") &&
-                            !lines.includes(".knodin/") &&
-                            !lines.includes("/.knodin")) {
-                            const prefix = gitignoreContent.length > 0 && !gitignoreContent.endsWith("\n") ? "\n" : "";
-                            await fs.promises.appendFile(gitignorePath, `${prefix}\n# knodin\n.knodin\n`);
-                        }
+                        await excludeStateDirectoryLocally(normalizedPath);
                     }
                     catch (e) {
-                        console.error("Failed to update .gitignore", e);
+                        console.error("Failed to exclude .knodin from git", e);
                     }
                 }
                 dbPath = path.join(stateDir, "db.sqlite");
@@ -10092,6 +10095,45 @@ function parseUnifiedDiff(stdout) {
     }
     return modifiedFiles;
 }
+/**
+ * Ignore `.knodin/` through `.git/info/exclude`, which git never commits.
+ *
+ * Resolved with `git rev-parse --git-path` rather than assembled by hand:
+ * inside a linked worktree `.git` is a FILE pointing elsewhere, so
+ * `<repo>/.git/info/exclude` is not a path that exists. Idempotent — a second
+ * call over an already-excluded repository writes nothing.
+ */
+async function excludeStateDirectoryLocally(repoPath) {
+    // A directory that is not a git repository has nothing to exclude, and git
+    // exits non-zero there. That is an ordinary state — knodin indexes plain
+    // directories — so it must not surface as an error. The previous
+    // `.gitignore` write never had to ask git anything, which is why this case
+    // only appears now.
+    let raw;
+    try {
+        raw = runGit(repoPath, ["rev-parse", "--git-path", "info/exclude"]).trim();
+    }
+    catch {
+        return;
+    }
+    if (!raw)
+        return;
+    const excludePath = path.isAbsolute(raw) ? raw : path.resolve(repoPath, raw);
+    let existing = "";
+    try {
+        existing = await fs.promises.readFile(excludePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const entries = new Set(existing.split(/\r?\n/).map((line) => line.trim()));
+    if (entries.has(".knodin") || entries.has(".knodin/") || entries.has("/.knodin"))
+        return;
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await fs.promises.mkdir(path.dirname(excludePath), { recursive: true });
+    await fs.promises.appendFile(excludePath, `${prefix}.knodin/\n`, "utf-8");
+}
 function runGit(repoPath, args) {
     return child_process.execFileSync("git", args, {
         cwd: repoPath,
@@ -13042,6 +13084,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     verification: { mode: "deep-audit", verifiedAt },
                     freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                     repairSteps: [
+                        ...(isLinkedWorktree(resolved)
+                            ? [
+                                "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.",
+                            ]
+                            : []),
                         "Run `knodin repair` to create the local index.",
                         "Run `knodin status` again to verify health.",
                     ],

package/dist/src/output-compression.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { redactCredentials } from "./credential-patterns.js";
 import { resolveStateDir } from "./engine/state-paths.js";
 const DEFAULT_LINE_BUDGET = 200;
 const DEFAULT_BYTE_BUDGET = 16_384;
@@ -90,20 +91,20 @@ function splitEvent(event) {
         lines.push({ raw: "", sourceBytes: 0 });
     return lines;
 }
+/**
+ * Redact credentials from captured output.
+ *
+ * The pattern set is shared with `diagnostics.ts` (see credential-patterns.ts).
+ * It used to be maintained here separately, and the two lists drifted: this one
+ * knew AWS keys and JWTs but missed Slack, OpenAI and GitHub's fine-grained
+ * tokens, while diagnostics missed AWS and JWTs. A credential safe on one path
+ * was disclosed on the other (KNODIN-11).
+ *
+ * The provider-named markers are kept, because a reader of compressed output
+ * benefits from knowing WHAT was removed.
+ */
 function redact(text) {
-    let count = 0;
-    const replace = (pattern, replacement) => {
-        text = text.replace(pattern, (...values) => {
-            count++;
-            return typeof replacement === "string" ? replacement : replacement(...values);
-        });
-    };
-    replace(/\b(authorization|password|passwd|secret|token|api[_-]?key)\s*([:=])\s*([^\s,;]+)/gi, (_match, name, separator) => `${name}${separator}[REDACTED:credential]`);
-    replace(/\bAKIA[A-Z0-9]{16}\b/g, "[REDACTED:aws-access-key]");
-    replace(/\bgh[pousr]_\w{20,}\b/g, "[REDACTED:github-token]");
-    replace(/\bBearer\s+[-\w.~+/]{12,}=*\b/gi, "Bearer [REDACTED:bearer-token]");
-    replace(/\beyJ[\w-]{8,}\.[\w-]{8,}\.[\w-]{8,}\b/g, "[REDACTED:jwt]");
-    return { text, count };
+    return redactCredentials(text, (label) => `[REDACTED:${label}]`);
 }
 function csiSequenceEnd(text, escapeIndex) {
     for (let index = escapeIndex + 2; index < text.length; index++) {

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.7.md

@@ -0,0 +1,79 @@
+# knodin 0.10.7
+
+Two fixes, both about knodin doing something to your repository or your
+credentials that you did not ask for.
+
+## knodin no longer writes to your .gitignore
+
+Indexing appended `.knodin` to `.gitignore`. That file is **shared**: tracked by
+convention, so the edit landed in your working tree and would ride into your next
+commit — and on a narrowly-scoped branch, `git add -A` swept it in.
+
+It ran regardless of scope, so a bare `knodin index` did it too. That matters
+because `knodin init --scope personal` exists precisely to promise that nothing
+reaches git.
+
+The same protection now goes to `.git/info/exclude`, which git never commits.
+The rule is resolved through `git rev-parse --git-path` rather than assembled by
+hand, because inside a linked worktree `.git` is a file and
+`<repo>/.git/info/exclude` is not a path that exists. A directory that is not a
+git repository has nothing to exclude and is left alone silently — knodin indexes
+plain directories too.
+
+### What this changed about freshness reporting
+
+Worth knowing if you have ever read the `staleness` field.
+
+Because every repository knodin touched carried that untracked `.gitignore`, its
+working tree was permanently dirty, and a dirty tree forces the reconcile path.
+So a branch switch reported `reconciled`. With a genuinely clean tree the same
+switch reports `fresh`.
+
+Nothing about the answer changed — measured directly, the query returns the
+symbols of the branch you are on, with no trace of the one you left. `fresh` is
+accurate: the graph does match the tree. Only the label is different, and it is
+different because the tree is finally clean.
+
+Three internal assertions had been reading that side effect rather than the
+behaviour they named, and now measure the returned symbols instead.
+
+## One credential-pattern set, not two
+
+knodin had **two independent secret redactors** — one for diagnostics bundles,
+one for compressed command output — each with its own list. They had drifted in
+opposite directions:
+
+| | diagnostics | output compression |
+|---|---|---|
+| GitHub classic | yes | yes |
+| GitHub fine-grained | yes | **no** |
+| Slack | yes | **no** |
+| OpenAI | yes | **no** |
+| AWS access key | **no** | yes |
+| JWT | **no** | yes |
+
+Neither list was a superset of the other, so the same log line was scrubbed on
+one path and disclosed on the other. Redaction is on by default, so nothing
+unusual had to be configured to hit this.
+
+Both now use one shared set covering every row. Each caller keeps its own
+replacement text: compressed output still names the provider, because a reader
+benefits from knowing what was removed, while diagnostics collapses to a single
+marker. Both preserve the key name and drop only the value, so `password=`
+survives and its secret does not.
+
+Tests assert every provider on **both** paths — a property no single-module test
+could hold. What redaction must leave alone is pinned too: a 40-character hex
+git SHA passes through untouched, because redacting commit SHAs would make diffs
+and review output unreadable.
+
+## Coverage
+
+Measured across all sixteen shards: 78.22% branches, 87.77% statements, 91.20%
+functions, 90.33% lines.
+
+The 77.16% recorded in 0.10.6 came from fifteen shards, the sixteenth having
+failed to write its report. That number was described at the time as a floor. It
+was not — a missing shard shrinks the denominator faster than the numerator, so
+it flattered the result. A partial-shard measurement is unusable rather than
+conservative.

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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.10.6",
+	"version": "0.10.8",
 	"knodin": {
 		"compatibility": "compatible"
 	},
@@ -61,6 +61,8 @@
 		"docs/releases/0.10.4.md",
 		"docs/releases/0.10.5.md",
 		"docs/releases/0.10.6.md",
+		"docs/releases/0.10.7.md",
+		"docs/releases/0.10.8.md",
 		"docs/releases/0.3.0.md",
 		"docs/releases/0.4.0.md",
 		"docs/releases/0.4.1.md",