knodin 0.10.7 → 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/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.
@@ -13083,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/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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.10.7",
+	"version": "0.10.8",
 	"knodin": {
 		"compatibility": "compatible"
 	},
@@ -62,6 +62,7 @@
 		"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",