knodin 0.9.0 → 0.10.1

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

@@ -16,8 +16,9 @@ import { exportContext, grepPackedArtifact, readPackedArtifact } from "../contex
 import { collectDiagnostics, persistDiagnosticsPreview } from "../diagnostics.js";
 import { getDocSection, listDocTopics } from "../docs-sections.js";
 import { diagnoseInstallation } from "../doctor.js";
-import { createEngine, REPO_WIDE_QUERY_PATTERNS, } from "../engine/index.js";
+import { createEngine, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PATTERNS, } from "../engine/index.js";
 import { measurePerfPhaseSync } from "../engine/perf.js";
+import { runSealedQuery } from "../engine/sealed-query.js";
 import { resolveDbPath } from "../engine/state-paths.js";
 import { runExecutionProfile } from "../execution-profile.js";
 import { diagnoseFailure, } from "../failure-diagnosis.js";
@@ -41,6 +42,7 @@ import { applySystemPlan, planSystemImport, planSystemLink, planSystemRelate, pl
 import { trustedUpdateStatus } from "../update-policy.js";
 import { waitForFresh } from "../wait-for-fresh.js";
 import { inspectWorktrees, reconcileWorktrees, removeManagedWorktree, } from "../worktree-lifecycle.js";
+import { indexOrSeed } from "../worktree-seed.js";
 let initializedEngine = null;
 function gatewayEngine() {
     initializedEngine ??= createEngine();
@@ -200,8 +202,9 @@ function buildDocumentedKnodinTools() {
                             "system",
                             "telemetry",
                             "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.",
+                        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`).",
                     },
                     profile: {
                         type: "string",
@@ -821,7 +824,7 @@ async function handleRepositoriesOperation(options) {
         const memoryLimitBytes = configuredRepositoryInitMemoryLimitBytes(systemConfig);
         const summary = await initializeRepositories(discoveryRoots, {
             command,
-            index: (target) => engine.index(target),
+            index: indexOrSeed(engine, KNODIN_SCHEMA_VERSION),
             status: (target) => engine.status(target),
             depth,
             worktrees: linkedWorktrees,
@@ -1054,6 +1057,7 @@ function compactExplainSource(result) {
         identity: result.identity,
         symbol: result.symbol,
         source,
+        sourceAvailability: result.sourceAvailability,
         staleness: result.staleness,
     };
 }
@@ -1595,6 +1599,15 @@ async function dispatchKnodinTool(args) {
                 note: "Each mirror is a snapshot pinned at `snapshot`; the remote is not watched, so results describe that commit and no later one.",
             }, "remote:list");
         }
+        case "sealed": {
+            // Read-only, and safe over MCP for the same reason `remote:list` is:
+            // it acquires nothing and writes nothing. It opens an artifact the
+            // caller already has and answers from bytes embedded inside it.
+            if (!artifactPath)
+                throw new Error("knodin sealed requires `artifactPath`");
+            const sealedResult = await runSealedQuery(artifactPath, symbol);
+            return bounded(sealedResult, "sealed:query");
+        }
         case "repositories": {
             if (!repositoryAction)
                 throw new Error("knodin repositories requires `repositoryAction`");

package/dist/src/update-executor.js

@@ -203,19 +203,28 @@ export async function executeManagerUpdate(options) {
         lock.release();
     }
 }
-function installedRuntimeVersion(command, env) {
+/** How long the `--version` probe may take. Overridable so tests are not bound to wall clock. */
+export const DEFAULT_VERSION_PROBE_TIMEOUT_MS = 10_000;
+function installedRuntimeVersion(command, env, timeoutMs = DEFAULT_VERSION_PROBE_TIMEOUT_MS) {
     const [executable, ...prefix] = command;
     if (!executable)
-        return null;
+        return { kind: "unreadable", reason: "no runtime command" };
     const result = spawnSync(executable, [...prefix, "--version"], {
         encoding: "utf8",
         env,
         stdio: ["ignore", "pipe", "pipe"],
-        timeout: 10_000,
+        timeout: timeoutMs,
     });
-    return result.status === 0 && /^\d+\.\d+\.\d+/.test(result.stdout.trim())
-        ? result.stdout.trim()
-        : null;
+    if (result.error)
+        return { kind: "unreadable", reason: String(result.error) };
+    if (result.signal)
+        return { kind: "unreadable", reason: `killed by ${result.signal}` };
+    if (result.status !== 0)
+        return { kind: "unreadable", reason: `exited with status ${result.status}` };
+    const output = result.stdout?.trim() ?? "";
+    return /^\d+\.\d+\.\d+/.test(output)
+        ? { kind: "version", version: output }
+        : { kind: "unrecognized", output };
 }
 /** Resume an interrupted installation from its fsynced journal before ordinary dispatch. */
 export async function recoverInterruptedUpdate(options) {
@@ -248,16 +257,26 @@ export async function recoverInterruptedUpdate(options) {
         }));
     try {
         if (journal.state === "manager-applying") {
-            const active = installedRuntimeVersion(options.runtimeCommand, options.env);
+            const probe = installedRuntimeVersion(options.runtimeCommand, options.env, options.versionProbeTimeoutMs);
+            const active = probe.kind === "version" ? probe.version : null;
+            // Say which of the three actually happened. "active version unknown"
+            // implied a value was read; a probe that timed out or could not be
+            // executed never got that far, and an operator reading this journal
+            // needs to know whether the install is wrong or merely unreadable.
+            const describe = () => {
+                if (probe.kind === "unreadable")
+                    return `installed version could not be read: ${probe.reason}`;
+                if (probe.kind === "unrecognized")
+                    return `installed runtime reported an unrecognized version ${JSON.stringify(probe.output)}`;
+                return `manager application was interrupted with active version ${probe.version}`;
+            };
             journal = transitionUpdateJournal(journal, active === journal.targetVersion
                 ? "candidate-installed-unverified"
                 : active === journal.previousVersion
                     ? "rollback-installed-unverified"
                     : "rollback-required", active && [journal.targetVersion, journal.previousVersion].includes(active)
                 ? {}
-                : {
-                    error: `manager application was interrupted with active version ${active ?? "unknown"}`,
-                }, options.stateHome);
+                : { error: describe() }, options.stateHome);
         }
         if (["candidate-installed-unverified", "candidate-verifying"].includes(journal.state)) {
             journal = transitionUpdateJournal(journal, "candidate-verifying", {}, options.stateHome);

package/dist/src/worktree-seed.js

@@ -0,0 +1,172 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { Database } from "./engine/sqlite.js";
+import { resolveDbPath } from "./engine/state-paths.js";
+import { deriveSharedOverlay } from "./shared-index/overlay.js";
+import { commitRelation } from "./shared-index/selection.js";
+import { KNODIN_VERSION } from "./version.js";
+import { inspectWorktrees } from "./worktree-lifecycle.js";
+const OPT_OUT_ENV = "KNODIN_DISABLE_WORKTREE_SEED";
+function readHead(repoPath) {
+    try {
+        return childProcess
+            .execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: repoPath,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Opens `dbPath` read-only and confirms schema + build compatibility with this process. */
+function siblingIsCompatible(dbPath, schemaVersion) {
+    let db = null;
+    try {
+        db = new Database(dbPath, { readonly: true });
+        const version = db.query("PRAGMA user_version").get()?.user_version ?? 0;
+        if (version !== schemaVersion)
+            return null;
+        const versionRow = db
+            .query("SELECT value FROM meta WHERE key = ?")
+            .get("knodinVersion");
+        if (!versionRow || versionRow.value !== KNODIN_VERSION)
+            return null;
+        const headRow = db
+            .query("SELECT value FROM meta WHERE key = ?")
+            .get("lastIndexedHead");
+        return headRow?.value || null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        db?.close();
+    }
+}
+/**
+ * Finds the cheapest-to-reconcile already-indexed sibling worktree of `repoPath`,
+ * or `null` when no eligible sibling exists (single-worktree repo, no healthy
+ * siblings, or none pass the schema/build compatibility gate).
+ */
+export async function selectSeedSibling(repoPath, schemaVersion, status) {
+    const resolved = path.resolve(repoPath);
+    const head = readHead(resolved);
+    if (!head)
+        return null;
+    let worktrees;
+    try {
+        worktrees = (await inspectWorktrees(resolved, status)).worktrees;
+    }
+    catch {
+        return null;
+    }
+    if (worktrees.length < 2)
+        return null;
+    const eligible = worktrees.filter((worktree) => path.resolve(worktree.path) !== resolved &&
+        worktree.graphInitialized &&
+        worktree.freshness !== "removed");
+    const ranked = eligible
+        .map((worktree) => {
+        const dbPath = resolveDbPath(worktree.path);
+        const indexedHead = siblingIsCompatible(dbPath, schemaVersion);
+        if (!indexedHead)
+            return null;
+        const relation = commitRelation(resolved, head, indexedHead);
+        const distance = relation ? relation.distance : Number.MAX_SAFE_INTEGER;
+        return { worktree, dbPath, indexedHead, distance };
+    })
+        .filter((entry) => entry !== null)
+        .sort((left, right) => left.distance - right.distance);
+    const best = ranked[0];
+    if (!best)
+        return null;
+    return {
+        siblingPath: best.worktree.path,
+        siblingDbPath: best.dbPath,
+        siblingIndexedHead: best.indexedHead,
+    };
+}
+/**
+ * Seeds a brand-new worktree's graph database from an already-indexed sibling's
+ * clean baseline (OS-level copy-on-write clone where supported) and reconciles it
+ * to this worktree's actual HEAD/working tree, instead of building from scratch.
+ */
+export async function seedWorktreeIndex(repoPath, engine, schemaVersion) {
+    const resolved = path.resolve(repoPath);
+    const sibling = await selectSeedSibling(resolved, schemaVersion, (p) => engine.status(p));
+    if (!sibling)
+        return { seeded: false, reason: "no eligible sibling worktree" };
+    let candidate;
+    try {
+        candidate = await engine.createCandidate(resolved, {
+            sourceDatabasePath: sibling.siblingDbPath,
+            sourceLabel: sibling.siblingPath,
+        });
+        const overlay = deriveSharedOverlay(resolved, sibling.siblingIndexedHead);
+        const reconciliation = await engine.reconcileCandidate(candidate, resolved, overlay.changedPaths);
+        const audit = await engine.auditCandidate(candidate, { mode: "deep" });
+        if (!audit.healthy) {
+            return { seeded: false, reason: audit.issues.join(",") || "candidate audit failed" };
+        }
+        await engine.promoteCandidate(candidate);
+        const promoted = candidate;
+        candidate = undefined;
+        const health = await engine.status(resolved, { audit: "deep", ignoreActiveOperation: true });
+        return {
+            seeded: true,
+            reflinked: promoted.reflinked ?? false,
+            seededFrom: sibling.siblingPath,
+            reconciledPaths: reconciliation.reconciled,
+            status: health,
+        };
+    }
+    catch (error) {
+        return { seeded: false, reason: error instanceof Error ? error.message : "seed failed" };
+    }
+    finally {
+        if (candidate) {
+            try {
+                await engine.discardCandidate(candidate);
+            }
+            catch {
+                // Best-effort cleanup; a fresh candidate directory is harmless to leave for the next attempt.
+            }
+        }
+    }
+}
+function toIndexResult(status, reconciledPaths) {
+    return {
+        indexed: reconciledPaths,
+        unchanged: [],
+        verification: {
+            status: status.status,
+            issueCount: status.missing.files.length + status.missing.records.length,
+            missing: status.missing,
+            verifiedAt: status.verification.verifiedAt,
+        },
+    };
+}
+/**
+ * Drop-in replacement for `(repo, options) => engine.index(repo, undefined, false, options)`
+ * used by every `knodin init`-family command: for a brand-new worktree, tries to
+ * seed-and-reconcile from a sibling before falling back to a full from-scratch
+ * index. For a worktree that already has a database (repair/update path),
+ * behaves exactly like the wrapped full index call.
+ */
+export function indexOrSeed(engine, schemaVersion) {
+    const fullIndex = (target, options) => engine.index(target, undefined, false, options);
+    return async (target, options) => {
+        if (fs.existsSync(resolveDbPath(target)))
+            return fullIndex(target, options);
+        if (process.env[OPT_OUT_ENV] === "1")
+            return fullIndex(target, options);
+        const seed = await seedWorktreeIndex(target, engine, schemaVersion);
+        if (seed.seeded)
+            return toIndexResult(seed.status, seed.reconciledPaths);
+        return fullIndex(target, options);
+    };
+}

package/docs/SHARED-INDEX-CONTRACT.md

@@ -114,6 +114,15 @@ the signed output size and digest, rejects trailing compressed data, validates
 the SQLite header and internal commit/schema/fingerprint, reconciles final Git
 and filesystem truth, deep-audits, and only then promotes.
 
+A brand-new worktree's distinct database may itself be populated by cloning an
+already-indexed sibling worktree's baseline (an OS-level copy-on-write file
+clone where the filesystem supports it, falling back to a plain copy
+otherwise) instead of a from-scratch build — see `knodin init`'s seed-and-
+reconcile path in `src/worktree-seed.ts`. That clone is reconciled to the new
+worktree's actual state through this same overlay-diff machinery before
+promotion, so the "distinct, writable" guarantee above is unchanged; only how
+the initial bytes are produced differs.
+
 ## Operator surfaces
 
 - `knodin shared status` is network-free. `--probe` is the explicit S3/auth

package/docs/releases/0.10.0.md

@@ -0,0 +1,127 @@
+# knodin 0.10.0
+
+This release makes a full index roughly 2.8x faster, turns parallel parsing on
+by default, adds sealed artifacts so a repository can be queried with no
+checkout at all, and makes unreadable source distinguishable from source that
+does not exist. It also makes `knodin init` fast on a brand-new git worktree by
+seeding its graph from an already-indexed sibling.
+
+## Sealed artifacts: query a repository with no checkout
+
+An ordinary `.knodin/db.sqlite` stores `filePath` plus line ranges and reads the
+bytes off a live working tree, so it cannot answer anything on a machine that
+has no clone. `knodin seal` embeds those bytes and stamps an attestation
+describing exactly which tree they came from.
+
+- `knodin seal --output <path.sqlite>` produces a portable artifact. Sealing is
+  a post-index transform, never index-time work: an ordinary user with a
+  checkout should not pay for source already on disk, so opting in is
+  structural rather than a matter of flag discipline. The live database is
+  copied, never mutated.
+- `knodin sealed <artifact> [symbol]` inspects or queries an artifact, and the
+  same capability is available as a `sealed` operation on the MCP gateway. Both
+  are read-only; creating an artifact stays CLI-only because it writes to disk.
+- The attestation carries schema version, knodin version, canonical
+  `owner/name` repository identity, the exact commit, **and which ref** was
+  sealed — a citation cannot be checked without knowing whether it came from
+  `main` or from whatever production is running.
+- Refusals are machine-readable codes rather than prose, because a caller
+  branches on them: `database-missing`, `index-unhealthy`, `working-tree-dirty`,
+  `commit-divergent`, `no-commit`, `source-drift`.
+- `source-drift` refuses the whole seal when a file changed between indexing
+  and sealing. Embedded bytes that disagree with recorded line ranges make
+  `explain` return the wrong function's body with full confidence and no
+  omission — a false positive that looks correct, which is worse than any
+  absence. Two checks run: `mtimeMs`/`size` against `index_state`, and a bounds
+  check that recorded line ranges fit the embedded bytes, which holds without
+  consulting a clock at all.
+- **Known residual, stated rather than implied:** a same-size edit that also
+  preserves line count and lands inside the mtime comparison window is still
+  invisible. Closing it needs a content hash in `index_state`, which forces a
+  full reindex and is tracked separately.
+- Uncovered content reads as absent, never as an empty string. An empty string
+  is indistinguishable from an empty file and downstream reads as "this symbol
+  has no body" rather than "this was not covered".
+- Size: profiles are excluded by default under the named rule
+  `profiles-excluded` (58% of one Salesforce payload in 187 files, already
+  captured as graph edges); blobs are zstd-compressed **inside** the database,
+  since SQLite does not transparently compress and a consumer holds the
+  decompressed file resident; storage is content-addressed so duplicate files
+  cost one blob; and embeddings are stripped unless `--keep-embeddings` is
+  passed, with semantic search then reporting itself unavailable rather than
+  returning zero results.
+- Measured on this repository: 832 files, 6.05 MB of source compressing to
+  2.05 MB (2.95x), a 17 MB artifact, `integrity_check: ok`.
+- Opening an artifact requires `mode: "sealed"`. Without it the engine
+  reconciles the graph against an empty mount, prunes every symbol, and answers
+  "not found" for content the artifact is carrying.
+
+## A full index is about 2.8x faster
+
+- Scoping an FTS trigger to the columns it actually mirrors, and removing a
+  whole-body string build from symbol identity, took a full index of this
+  repository from 60.5s to 21.3s.
+- Salesforce metadata is now symbolized by kind rather than as one
+  undifferentiated `salesforce-metadata` symbol carrying identical boilerplate,
+  so FTS and embeddings over it mean something for the first time.
+
+## Parallel parsing is on by default
+
+- The parse pool now runs unless `KNODIN_DISABLE_PARSE_WORKERS=1` is set. Pool
+  size is derived from total memory and core count, and an unsuitable host
+  silently keeps the previous sequential behaviour rather than discovering the
+  problem partway through an index.
+- Files that need a main-thread indexer are kept off the pool. `.page`,
+  `.component`, `.clp`, `.ws`, `.xml`, `.sql`, `.pkb`, `.pks` and `.prisma`
+  classify as generic but hand off to indexers that write to the database
+  themselves, and routing them to a worker made a Visualforce controller edge
+  resolve on some runs and not others.
+
+## Unreadable source is distinguishable from missing source
+
+- Source reads report an availability state instead of collapsing every failure
+  into `""`. A file that is gone, a file that could not be read this time, and a
+  symbol that does not exist are now three different answers.
+- `dead_code` no longer reports a symbol as dead because its file could not be
+  read, and a missing file no longer aborts an entire `map` or `explain`.
+
+## Faster `knodin init` on a new worktree
+
+- A brand-new worktree's graph database is seeded from the cheapest-to-
+  reconcile already-indexed sibling worktree of the same repository, cloned
+  via an OS-level copy-on-write file clone where the filesystem supports it
+  (plain-copy fallback otherwise), then reconciled to the new worktree's
+  actual committed/staged/working/untracked state through the existing
+  candidate allocate/reconcile/audit/promote pipeline before atomic
+  promotion.
+- Seeding is opportunistic: no eligible sibling, a schema/build-compatibility
+  mismatch, or any candidate-audit failure falls straight back to a full
+  from-scratch index, with no error surfaced to the caller. Every git
+  lifecycle operation (pull, reset, merge, rebase, checkout, stash, clean)
+  on a seeded worktree is handled by the same incremental reconciliation and
+  hook machinery as any other worktree.
+- Measured on this repository (810 files, 5,086 symbols): `knodin init` on a
+  new worktree with an eligible sibling completed in roughly 5 seconds versus
+  30-40 seconds for a from-scratch build.
+- Fixes a latent bug in the candidate reconciliation path: a candidate
+  populated from a foreign source (a downloaded shared-index artifact, or now
+  another worktree's database) kept `index_state` mtimes from wherever that
+  source was built, so every file outside the explicit changed-path set could
+  trip the deep audit's drift check once source and target were genuinely
+  different checkouts. `reconcileCandidate` now refreshes that bookkeeping
+  (a stat, not a re-index) for known files outside the changed-path set,
+  which also benefits the existing shared-index restore path.
+- Set `KNODIN_DISABLE_WORKTREE_SEED=1` to always force a full from-scratch
+  index.
+
+No existing worktree's database is touched by that change; it only affects the
+code path for a worktree whose `.knodin/db.sqlite` does not yet exist.
+
+## Also in this release
+
+- Five benchmark runners no longer call `.replace("Z", "Z")`, a no-op that
+  CodeQL correctly flagged as `js/identity-replacement`. Output filenames are
+  byte-identical.
+- Fixed an `update-executor` test that failed roughly one run in three: a
+  version probe raced a 10-second timeout, and the probe timeout is now
+  injectable so the suite does not depend on process-spawn latency.

package/docs/releases/0.10.1.md

@@ -0,0 +1,83 @@
+# knodin 0.10.1
+
+Three defects, none of which a test suite would have found on its own. Two were
+found by upgrading knodin on a real machine: one only appears after Homebrew
+moves the Node binary, the other only when a lifecycle event is already queued.
+The third is a scheduling race that reported the same cause under two different
+codes, and it surfaced as an unrelated pre-push failure after six clean runs.
+
+## Background refresh survives a moved Node binary
+
+`knodin init` wrote the generated hook with a fully-resolved path to whichever
+Node was running at the time. `process.execPath` is symlink-resolved, so a
+stable `/opt/homebrew/bin/node` became a version-pinned
+`/opt/homebrew/Cellar/node/<version>/bin/node`.
+
+Homebrew deletes that directory on upgrade, so every hook written beforehand
+died with exit 127 — silently, because refresh runs in the background. The
+graph simply stopped keeping up, and only a `knodin status` run revealed it.
+It affected every repository initialized before the upgrade, not one.
+
+The hook now resolves its interpreter when it runs. The recorded path stays
+preferred, so nothing changes while it exists; `PATH` is consulted only once it
+does not. Falling back first would silently change which runtime executes,
+which is its own bug.
+
+Hooks generated before this release still carry the old absolute path. They
+keep failing until regenerated with `knodin init`; the fix prevents recurrence
+after the next Node upgrade rather than repairing them retroactively.
+
+## `knodin init` can drain its own lifecycle queue
+
+`init` takes the lifecycle lease, then drains queued events by spawning the
+background hook. The hook re-entered knodin, met the same lease, saw a live
+pid — its own parent — and refused. `init` reported "queued lifecycle refresh
+could not be drained (exit 1)" on every run, and `knodin status` then advised
+running `init`, which reproduced the failure exactly.
+
+Worse, the failed drain wrote a failure marker that `status` kept reporting, so
+a transient condition looked permanent while the graph was in fact intact — in
+the observed case 5,883 of 5,883 files indexed and 5,059 carrying symbols.
+
+A lease holder now passes its nonce to processes it spawns, and a child whose
+token matches the lease on disk is admitted re-entrantly. Re-entry returns a
+no-op release, because releasing there would drop the lock while the parent
+still believes it holds it.
+
+The lease is not weakened. A missing token, or one that does not match the
+lease on disk, still hits the existing contention check, so a genuinely
+concurrent mutation from another process is refused exactly as before.
+
+## One abort cause, one code
+
+Worker startup and queue admission are each a race between "ready" and
+"aborted". Each arm had an abort listener rejecting with
+`KNODIN_CLIENT_DISCONNECTED` and a follow-up `signal.aborted` re-check
+rejecting with `KNODIN_REQUEST_CANCELLED`, so the same client disconnect
+surfaced as either code depending on which arm settled first.
+
+That is worse than a consistently wrong code. It was stable on an idle machine
+and unstable under load, so it looked trustworthy everywhere anyone would have
+checked it — it surfaced as a pre-push gate failure on an unrelated change
+after six clean runs.
+
+It also fed the reliability journal, where the two codes map to distinct kinds.
+One disconnect was recorded under two kinds, quietly skewing any rate computed
+from them. **That contamination is retroactive and cannot be repaired:** journal
+entries written before this release cannot be reattributed, so a
+cancellation-versus-disconnect rate spanning the 0.10.1 boundary should be read
+as suspect rather than corrected.
+
+The taxonomy is unchanged. `superviseMcpRequest` can still tell an explicit
+cancellation from a disconnect; the supervisor cannot, so it now names only the
+cause it actually knows.
+
+## Homebrew formula retention
+
+The `Retain versioned Homebrew formula` job ran on a GitHub-hosted runner whose
+ephemeral IP is not on the organization's allow list, so it failed at checkout
+with a 403 on every release since it was added — and it cloned
+`knodin/knodin`, a stale source mirror, rather than `knodin/homebrew-tap`.
+
+Both are corrected. Every formula through 0.10.0 was retained by hand; this is
+the first release where that job can do it.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.9.0",
+	"version": "0.10.1",
 	"knodin": {
 		"compatibility": "breaking"
 	},
@@ -71,6 +71,8 @@
 		"docs/releases/0.8.6.md",
 		"docs/releases/0.8.7.md",
 		"docs/releases/0.9.0.md",
+		"docs/releases/0.10.0.md",
+		"docs/releases/0.10.1.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",