knodin 0.10.2 → 0.10.4

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

@@ -183,6 +183,7 @@ function buildDocumentedKnodinTools() {
                             "review",
                             "map",
                             "search",
+                            "textSearch",
                             "query",
                             "prs",
                             "context",
@@ -204,7 +205,7 @@ function buildDocumentedKnodinTools() {
                             "diagnostics",
                             "sealed",
                         ],
-                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. execute: run one immutable repository-defined profile only when independently enabled globally and locally; no executable or argv is accepted from the caller, unsupported containment fails closed, and output is compressed then diagnosed. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.knodin/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP. remote: list read-only mirrors of repositories that are reachable but not checked out locally, so you can run explain/query/map/search against one by passing its `path` as `repoPath`. Each mirror is a snapshot pinned at a commit; the remote is not watched. Acquiring, refreshing, and removing mirrors is CLI-only (`knodin remote add|refresh|remove`) because it clones another repository's source onto this machine and consumes disk nothing reclaims automatically — the user's decision to make, not an agent's. sealed: query a sealed artifact (`artifactPath`) with NO checkout — source is embedded in it. Returns attested identity, commit, ref, age, coverage, and a `degraded` list of what it cannot do; pass `symbol` to explain. Describes the attested commit and no later one, so staleness is `unknown`, never `fresh`. Creating one is CLI-only (`knodin seal`).",
+                        description: "Which knodin capability to run. context: call this FIRST when starting any investigation and unsure which operation to reach for — one ultra-compact orientation (repo stats + top subsystems/hubs/flows + a risk score if there's a diff + a heuristic next-operation suggestion); the suggestion is only a hint and never blocks calling any operation directly. explain: use when orienting on a symbol/file or before editing it — returns edit-ready source + call paths + blast radius. review: use before writing a PR description or approving a diff — risk-scored context (changed symbols, affected flows, test gaps). map: use before a cross-cutting refactor or to understand subsystem boundaries — communities + hub/bridge nodes + confidence-tagged edges. search: use when you don't know the exact symbol name — hybrid semantic + keyword lookup over code symbols. textSearch: use when what you are renaming is NOT a code symbol — a product name, a UI label, a literal — so `explain` does not apply. Read-only exact-text match repo-wide, including files yielding no symbols (markdown, config); each hit is classified string/comment/identifier/prose with `basis` stating whether that came from the file's parse tree or only its extension. Names files it could not read, and separates no-matches from could-not-search. `caseSensitive: false` also matches other casings, each labelled. query: use for a structured question about a known symbol — callers_of, tests_for, shortest_path, dead_code, rename_preview, flows, and more (see `pattern`). pack: create deterministic Markdown/JSON/XML source context under hard budgets, or bounded-read/exact-regex-grep a saved artifact. compress: reduce already-produced diagnostic text under exact line/content-byte budgets, preserve exit metadata and detected signals, retain private local drill-down data by default, and never label insufficient-fidelity output complete. execute: run one immutable repository-defined profile only when independently enabled globally and locally; no executable or argv is accepted from the caller, unsupported containment fails closed, and output is compressed then diagnosed. prs: use to triage open GitHub PRs (via your local authenticated `gh`) — per-PR status, CI, and blast radius sorted ready-small-impact first; pass `prNumber` for one PR's impacted files + community names. wiki: write a static markdown documentation site for the repository's logical subsystems to `.knodin/wiki/`. Generates an index plus one page per mapped community. Reuses the `map` output. Idempotent: unchanged pages are untouched on disk unless `force` is true. docs: call this to retrieve curated, focused markdown usage guidance directly over MCP. remote: list read-only mirrors of repositories that are reachable but not checked out locally, so you can run explain/query/map/search against one by passing its `path` as `repoPath`. Each mirror is a snapshot pinned at a commit; the remote is not watched. Acquiring, refreshing, and removing mirrors is CLI-only (`knodin remote add|refresh|remove`) because it clones another repository's source onto this machine and consumes disk nothing reclaims automatically — the user's decision to make, not an agent's. sealed: query a sealed artifact (`artifactPath`) with NO checkout — source is embedded in it. Returns attested identity, commit, ref, age, coverage, and a `degraded` list of what it cannot do; pass `symbol` to explain. Describes the attested commit and no later one, so staleness is `unknown`, never `fresh`. Creating one is CLI-only (`knodin seal`).",
                     },
                     profile: {
                         type: "string",
@@ -221,7 +222,7 @@ function buildDocumentedKnodinTools() {
                     },
                     file: {
                         type: "string",
-                        description: "Repo-relative definition file selector.",
+                        description: "Repo-relative file. Disambiguates which definition is meant when a symbol resolves in several files; with query impact and impactMode=file it names the target file instead.",
                     },
                     evidenceLevel: {
                         type: "string",
@@ -272,7 +273,7 @@ function buildDocumentedKnodinTools() {
                     impactMode: {
                         type: "string",
                         enum: ["symbol", "file"],
-                        description: "query impact only: stable symbol reach (default) or explicitly labeled changed-file blast radius.",
+                        description: "query impact only: stable symbol reach (default) or explicitly labeled changed-file blast radius. With `file`, name the target in the `file` parameter, or pass comma-separated paths in `symbol` for a multi-file change set.",
                     },
                     direction: {
                         type: "string",
@@ -399,6 +400,10 @@ function buildDocumentedKnodinTools() {
                         enum: ["all", "test", "production"],
                         description: "search/file_metrics: include all, test-only, or production-only files.",
                     },
+                    caseSensitive: {
+                        type: "boolean",
+                        description: "textSearch only; default true. False also matches other casings; each hit reports the case on disk and whether it matched exactly, so a case-sensitive token is not folded into the same decision as a label.",
+                    },
                     offset: {
                         type: "number",
                         minimum: 0,
@@ -1398,7 +1403,7 @@ async function handleDiagnosticsOperation(repo, args, bounded) {
 async function dispatchKnodinTool(args) {
     const startedAt = performance.now();
     const parsedArgs = (args ?? {});
-    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, queries, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
+    const { operation, symbol, base, diffScope, from, toRevision, reviewFiles, query, pattern, queries, to, limit, depth, impactMode, direction, relationKinds, minConfidence, includeTests, includeDataFlow, flowVariable, apply, force, detailLevel, prNumber, prState, branches, auditRange, auditBase, auditHead, expectedLogin, worktreeAction, worktreePath, telemetryAction, telemetryRetentionDays, task, changedFiles, repoPath, section, systemAction, repositories, scope, distributed, repositoryIds, components, evidence, relationshipType, requireComplete, repositoryAction, roots, linkedWorktrees, cursor, allowPartial, dryRun, manifestPath, planDigest, identity, file, kind, toIdentity, toFile, toKind, byteBudget, tokenBudget, itemBudget, includeSource, languages, extensions, kinds, path, architectureFacets, testScope, caseSensitive, offset, minLines, minComplexity, topN, sort, packAction, format, include, exclude, filePolicies, alreadyPresent, chatFiles, lineNumbers, includeTree, outputPath, artifactPath, startLine, endLine, regex, regexFlags, gitDiffScope, gitLog, statusAudit, timeoutMs, client, repairPlan, persistTelemetry, } = parsedArgs;
     const repo = repoPath ?? process.cwd();
     const selector = {
         identity: expandCompactIdentity(identity),
@@ -1744,6 +1749,15 @@ async function dispatchKnodinTool(args) {
                 includeSource,
                 offset,
             }));
+        case "textSearch": {
+            if (!query)
+                throw new Error("knodin textSearch requires `query` (the exact text to find)");
+            const found = await engine.searchText(query, repo, { caseSensitive });
+            // Not routed through `graphRead`: this reads the working tree rather
+            // than the graph, so it is answerable — and correct — on a repository
+            // whose index is stale, absent, or still building.
+            return bounded(found, "textSearch");
+        }
         case "prs": {
             return bounded(await handlePullRequestsOperation({
                 repo,
@@ -1799,8 +1813,23 @@ async function dispatchKnodinTool(args) {
             if (limit !== undefined && (!Number.isFinite(limit) || !Number.isInteger(limit) || limit < 1))
                 throw new Error("knodin query: limit must be a positive integer");
             const repoWide = REPO_WIDE_QUERY_PATTERNS.includes(pattern);
-            if (!symbol && !repoWide)
-                throw new Error(`knodin query ${pattern} requires \`symbol\``);
+            // File-mode impact takes its target as comma-separated paths in
+            // `symbol`. That is not the call anyone forms from this schema: a `file`
+            // parameter is published right beside `impactMode`, and the obvious
+            // reading — impactMode "file" plus file: <path> — was rejected with
+            // "requires `symbol`", naming a field the caller had deliberately not
+            // used. A user reported the capability as unavailable because of it.
+            //
+            // `file` is now accepted as the target here, and only here: in symbol
+            // mode it keeps its existing meaning as a definition disambiguator.
+            const fileModeImpact = pattern === "impact" && impactMode === "file";
+            if (fileModeImpact && symbol && file && symbol !== file)
+                throw new Error(`knodin query impact with impactMode=file received different targets in \`symbol\` (${symbol}) and \`file\` (${file}); pass one`);
+            const target = fileModeImpact ? (symbol ?? file) : symbol;
+            if (!target && !repoWide)
+                throw new Error(fileModeImpact
+                    ? "knodin query impact with impactMode=file requires a target path in `file`, or comma-separated paths in `symbol`"
+                    : `knodin query ${pattern} requires \`symbol\``);
             if ((pattern === "shortest_path" || pattern === "cross_substrate_path") && !to)
                 throw new Error(`knodin query ${pattern} requires \`to\``);
             if (pattern === "rename_preview" && !to)
@@ -1817,7 +1846,7 @@ async function dispatchKnodinTool(args) {
                     .rename(symbol ?? "", to ?? "", repo, apply === true, true, selector)
                     .then((result) => bounded(decorateGraphQueryResult(result, queryHealth?.available ? queryHealth.state : "healthy", queryHealth?.available ? queryHealth.graph.freshness : undefined), "query:rename_preview"));
             }
-            const queryResult = await engine.query(pattern, symbol ?? "", repo, to, Math.min(limit ?? itemBudget ?? 100, itemBudget ?? 1000), depth, detailLevel === "source" ? undefined : detailLevel, selector, pattern === "impact"
+            const queryResult = await engine.query(pattern, target ?? "", repo, to, Math.min(limit ?? itemBudget ?? 100, itemBudget ?? 1000), depth, detailLevel === "source" ? undefined : detailLevel, selector, pattern === "impact"
                 ? {
                     mode: impactMode ?? "symbol",
                     direction,

package/dist/src/update-policy.js

@@ -234,7 +234,12 @@ function baseResult(options, status) {
         networkUsed: false,
     };
 }
-function parseVersion(version) {
+/**
+ * Exported so release classification can reuse this parser rather than adding a
+ * third hand-rolled copy (`src/manager-update.ts:424` is the second, and a
+ * de-duplication candidate). Strict SemVer: leading zeros are rejected.
+ */
+export function parseVersion(version) {
     const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
     if (!match)
         return null;

package/dist/src/wait-for-fresh.js

@@ -62,6 +62,30 @@ function completedStatus(graph) {
         return "unknown";
     return null;
 }
+/**
+ * Waiting here can only end at the timeout (EASFDC-8498).
+ *
+ * `queued` freshness means progress depends on the queued-event drainer, and
+ * `reconcileOrdinaryDrift` deliberately declines that state, so the in-process
+ * path cannot advance it either. If the drainer also cannot run, every
+ * remaining poll is spent relaunching a processor that will not start.
+ *
+ * This is the exact shape reported on 0.10.2: a hook exiting 127 on every
+ * invocation, freshness stuck at `queued`, and `status` recommending
+ * `wait --fresh` — which held the reason for its own futility on every poll and
+ * reported none of it.
+ *
+ * Deliberately narrow. A degraded lifecycle with freshness that is NOT queued
+ * can still be reconciled in process, and failing fast there would refuse work
+ * the command can actually do.
+ */
+function blockedOnDeadDrainer(graph) {
+    return graph.freshness?.state === "queued" && !graph.lifecycle.refreshCapable;
+}
+function describeDeadDrainer(graph) {
+    const detail = graph.lifecycle.lastError ?? graph.lifecycle.issues[0] ?? "cause not recorded";
+    return `background refresh cannot run, so queued work will not drain: ${detail}`;
+}
 async function reconcileOrdinaryDrift(engine, repo, graph) {
     const shouldReconcile = (graph.status === "stale" || graph.status === "repair-needed") &&
         graph.freshness.state !== "queued";
@@ -90,9 +114,27 @@ export async function waitForFresh(engine, repo, timeoutMs = 30_000, processQueu
         status = completedStatus(graph);
         if (status)
             return completedResult(status, startedAt, polls, graph);
+        // Checked after the completion checks, never before: a repository that is
+        // already fresh must still report `fresh`, even with a broken hook.
+        if (blockedOnDeadDrainer(graph))
+            return {
+                status: "lifecycle-degraded",
+                waitedMs: Date.now() - startedAt,
+                polls,
+                graph,
+                reason: describeDeadDrainer(graph),
+            };
         const elapsed = Date.now() - startedAt;
         if (elapsed >= timeoutMs)
-            return { status: "timeout", waitedMs: elapsed, polls, graph };
+            return {
+                status: "timeout",
+                waitedMs: elapsed,
+                polls,
+                graph,
+                // A timeout that names nothing is what sent the reporter looking in
+                // the wrong place. Say what was still outstanding.
+                reason: `still waiting on ${graph.lifecycle.queuedEvents} queued event(s)${graph.lifecycle.lastError ? `; last refresh error: ${graph.lifecycle.lastError}` : ""}`,
+            };
         await delay(Math.min(100, timeoutMs - elapsed));
     }
 }

package/docs/releases/0.10.3.md

@@ -0,0 +1,93 @@
+# knodin 0.10.3
+
+Four changes, all from one observation: after 0.10.2 fixed a parser leak that had
+left 174,205 files silently unparsed on a large repository, the recovery advice
+turned out to be unusable. A full reindex of that checkout has no knowable cost,
+no way to ask for less work, and no way to survive an interruption.
+
+## Indexing reports how much work is left, not just how many files
+
+A full index of a 902,960-file Salesforce checkout appeared to hang for twenty
+minutes at 71%. It had not hung — it had reached the profiles.
+
+Progress was counted in files while the cost lives in bytes, and on that
+repository the two disagree violently: **435 files over 1 MB hold 78% of all
+source bytes.** So the counter raced through the cheap files and appeared to
+stall exactly when the expensive ones began, which is the moment an operator is
+most likely to conclude the process is wedged and kill it. The only way to tell
+grinding from hung was to read the process's accumulated CPU time.
+
+Both counters are now reported, and the estimate is derived from the byte rate.
+Files answer "how far through the list"; bytes answer "how much work is left".
+
+The estimate is labelled an estimate. During that one run, three separate
+completion figures were derived from observed rates — 38 hours, 4 hours, and 15
+minutes — and every one was wrong, because the rate ranged from 6.5 to 361 files
+per second before collapsing to 0.065. Rates are now measured from the start of
+the phase rather than process start, so the cold-start window no longer drags the
+estimate; extrapolating from it is what produced the 38-hour figure.
+
+## Rebuild one subtree with `--under`
+
+`knodin index --under <dir>` rebuilds only that directory. Previously the
+intuitive attempt was also the worst one: a lone directory argument means "index
+this whole repository".
+
+The file set is resolved inside the engine rather than by expanding paths
+yourself, so a scoped rebuild indexes exactly the files a full index would. A
+scope that matches nothing fails rather than reporting a successful rebuild of
+nothing.
+
+Coverage is reported as a lower bound afterwards, because a whole-repository
+tally no longer describes a partially rebuilt graph. Trading a graph you were
+told to distrust for one that is silently partial would be worse than doing
+nothing.
+
+## Defer embeddings with `--skip-embeddings`
+
+The embedding phase dominates indexing cost, and the engine has always supported
+deferring it — only mirrors could ask. `knodin index --skip-embeddings` now
+builds structure alone, leaving `explain`, `query` and impact answerable while
+semantic search waits.
+
+The gap is stated rather than left to be discovered. An index that defers
+embeddings says so, and `knodin search` now announces that it will under-return
+until they are built. A short result list is otherwise indistinguishable from a
+thorough search that found little.
+
+Running `knodin index` again completes the deferred pass, and only the symbols
+still lacking embeddings are processed.
+
+## An interrupted `--clean` resumes
+
+A clean index builds into a candidate database and promotes it atomically. That
+is deliberate — it is why a failed rebuild cannot leave a half-built graph in
+place of a working one, and it is unchanged.
+
+But a killed process runs no discard, so the candidate survived on disk and the
+next run ignored it and started over. On a repository where the rebuild takes
+hours, an interruption cost all of it.
+
+The next `knodin index --clean` now continues that build, skipping files already
+recorded whose contents still match disk, and says how many it kept. Resumption
+is refused when the tree has moved on since — continuing there would promote a
+graph that never described any single state of the repository — and refused for
+a candidate that was never marked as an interrupted build. Both cases fall back
+to a full rebuild rather than guessing.
+
+## Release compatibility is derived, not declared
+
+`knodin.compatibility` had been the literal string `"breaking"` since it was
+introduced, across four releases. Two of those genuinely were breaking and two
+were bugfix patches, so it was accidentally correct half the time — which is
+worse than being consistently wrong, because the correct entries make the field
+look maintained.
+
+It is now derived from the version change, with the pre-1.0 rule stated
+explicitly: below 1.0 the minor is the breaking axis, so `0.10.x` to `0.11.0`
+breaks and `0.10.2` to `0.10.3` does not. Nothing inside this repository reads
+the field — the Homebrew tap reads it from the published package — so two guards
+now check it, because otherwise nothing would.
+
+Releases already published keep the label they shipped with. Published metadata
+is immutable by design.

package/docs/releases/0.10.4.md

@@ -0,0 +1,161 @@
+# knodin 0.10.4
+
+Five changes from two pieces of field feedback. The first came from a
+product-name rename in the Nova repository; the second from a checkout whose
+background refresh had been failing silently since a Homebrew upgrade.
+
+The theme is the same one 0.10.2 and 0.10.3 were about: a tool that reports
+things it has not verified, and a failure that leaves no trace anywhere a person
+looks.
+
+## `textSearch`: exact text, with every match classified
+
+The reported blocker: the refactor workflow assumes a rename targets a code
+symbol. This one was a product-name literal spanning UI strings and documents,
+where `explain` and symbol resolution do not apply. The reporter fell back to
+`rg` and hand-applied patches for the whole task.
+
+Searching is the easy half. The half worth building is classification, and their
+case shows why: visible `NOVA` labels had to change, while `NOVA-CANARY-…` was a
+deliberate case-sensitive security token that had to survive. A flat text search
+returns both and leaves a human to separate them by eye across however many hits
+a large repository produces — exactly the position knodin exists to remove
+people from.
+
+knodin can classify only because it already parses these files. A match in a
+file with a grammar resolves to its smallest containing syntax node, and the
+parser's own node type is the evidence. A file without a grammar supports a
+claim about the file, not about the match.
+
+That difference is reported rather than smoothed over. Every match carries the
+`basis` its classification rests on — `parse-node`, `file-type`, or `none` — and
+the grammar's raw node type travels alongside the coarse label so a bad mapping
+is catchable. Classification will sometimes be wrong; it is offered as evidence
+a human is reviewing, never as a decision already taken.
+
+Three details that matter in practice:
+
+- **Documents are searched.** Enumeration uses the indexer's prune rules but not
+  its source-extension filter, because markdown and config are the point.
+- **Files that could not be read are named**, not omitted. A rename that
+  silently skipped files would leave a half-renamed repository looking finished.
+- **"No matches" is distinguishable from "could not search."** An empty list
+  that reads as reassurance is the defect this whole operation exists to avoid.
+
+`textSearch` reads the working tree rather than the graph, so it stays
+answerable when the index is stale, absent, or still building — often exactly
+when a rename is underway.
+
+It previews only. Applying edits is deliberately not in this release.
+
+## `impact` accepts the file you gave it
+
+Reported verbatim against 0.10.2:
+
+```
+operation: query, pattern: impact, impactMode: file,
+file: documents/nova-architecture-deck.js
+-> knodin query impact requires `symbol`
+```
+
+File-mode impact was never missing. It read its target from `symbol`, documented
+in one clause buried inside that parameter's prose, while a `file` parameter sat
+published right beside `impactMode` meaning something else entirely. The schema
+offered both, and the combination anyone would form from them was the one that
+failed.
+
+That is worse than a missing feature: the reporter concluded the capability was
+broken and moved on. A working feature was recorded as unavailable because of
+parameter naming.
+
+`file` is now accepted as the target under file mode, and keeps its original
+meaning in symbol mode. Conflicting `symbol` and `file` values are refused with
+both named rather than resolved by preference — silently picking one would
+answer a question nobody asked. The error now states the supported call.
+
+## Managed hooks survive a Node upgrade
+
+A checkout's background refresh had exited 127 seventeen consecutive times:
+
+```
+background-index.sh: /opt/homebrew/Cellar/node/26.5.0_1/bin/node:
+No such file or directory
+```
+
+`brew upgrade node` deletes the versioned Cellar directory. The hook had
+recorded the interpreter's absolute path at generation time, and that path
+contains the version, so it was guaranteed to stop existing.
+
+The caller cannot avoid this: Node symlink-resolves `process.execPath`, so
+invoking `/opt/homebrew/opt/node/bin/node` still reports the Cellar path. By the
+time knodin can read its own interpreter, the durable path is gone.
+
+The recorded path is now mapped back to `<prefix>/opt/<formula>/…`, the symlink
+Homebrew repoints on upgrade, so it survives by construction rather than by
+falling back at run time. The prefix is derived from the match, so Intel
+`/usr/local` and Linuxbrew work through the same path. A non-Homebrew
+interpreter is left untouched.
+
+**Existing repositories need one `knodin init`** to pick up a corrected hook.
+`repair` cannot do it: the fault lives in the hook's contents, not in graph
+state — which is why a `repair` run in that checkout returned "healthy" while
+the lifecycle stayed broken.
+
+Lifecycle health now notices this class of failure. It previously checked that
+the background script existed and was executable, neither of which says anything
+about the runtime on its first line, so the repository reported a degraded
+lifecycle while naming no cause. The reported issue now names the missing
+interpreter and the command that rewrites the hook.
+
+## `wait --fresh` stops instead of waiting for something that cannot happen
+
+`wait --fresh` has always had a bounded timeout, and it was reached honestly.
+But when the background refresh is failing, waiting cannot succeed, and the
+command already knew that: it recomputes lifecycle health on every poll, so it
+was holding the exit-127 error the entire time it spun, then reported the single
+word `timeout`.
+
+It now returns immediately when freshness is queued and lifecycle refresh cannot
+run — the pairing that is genuinely futile — and names the recorded failure.
+Timeouts carry a reason as well: what remained queued, and the last refresh
+error.
+
+The guard is narrow on purpose. A degraded lifecycle whose freshness is not
+queued can still be reconciled in process, and a repository that is already
+fresh still reports `fresh` even with a broken hook.
+
+## `init` no longer denies agents that are configured
+
+Six seconds apart, with nothing installed in between:
+
+```
+$ knodin init
+Agent integration: personal - no supported coding agents detected
+$ knodin status
+Agent integration: personal (claude, codex, gemini, antigravity)
+```
+
+Both commands were computing something correct — `init` reports what that run
+configured, `status` reports what is configured — but `init` described its empty
+set as a *detection* result it had never run, which reads as a denial of the
+four agents the next command lists. It now says what the value supports: no
+agents configured by this run.
+
+## Known gaps
+
+Two items from the same report are deliberately not fixed here rather than
+guessed at:
+
+- `status` and `repair` can disagree about indexed-file and symbol counts. In
+  the reported session `status` showed 0 indexed files and 95 issues while
+  `repair`, seconds later, reported 94 indexed files and 53 with symbols and
+  called itself "verified". Whether `repair` inspected or silently rebuilt
+  changes what the fix is, and the evidence does not settle it.
+- `init --scope personal` leaves `.agents/`, `.codex/` and `.gemini/` untracked
+  and unexcluded, and migrates a tracked `.gitignore` entry without saying so.
+
+## Compatibility
+
+Compatible. Nothing is removed or renamed; `textSearch` is a new operation
+alongside the existing ones, and `file` gains a meaning under `impactMode: file`
+while keeping its previous one everywhere else.

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "knodin",
-	"version": "0.10.2",
+	"version": "0.10.4",
 	"knodin": {
-		"compatibility": "breaking"
+		"compatibility": "compatible"
 	},
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
@@ -74,6 +74,8 @@
 		"docs/releases/0.10.0.md",
 		"docs/releases/0.10.1.md",
 		"docs/releases/0.10.2.md",
+		"docs/releases/0.10.3.md",
+		"docs/releases/0.10.4.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",