knodin 0.10.8 → 0.12.0

package/dist/src/init.js

@@ -478,8 +478,15 @@ if ! mkdir "$LOCK_DIR" 2>/dev/null; then
   if [ -f "$LOCK_DIR/pid" ]; then
     LOCK_PID="$(cat "$LOCK_DIR/pid" 2>/dev/null || true)"
     if [ -n "$LOCK_PID" ] && ! kill -0 "$LOCK_PID" 2>/dev/null; then
-      rm -rf "$LOCK_DIR"
-      mkdir "$LOCK_DIR" 2>/dev/null || exit 0
+      # Claim the stale lock by RENAMING it: "rm -rf then mkdir" leaves a window
+      # in which two processes that both saw the same dead pid can each succeed.
+      # Only one rename can win, because the loser's source no longer exists.
+      if mv "$LOCK_DIR" "$LOCK_DIR.stale.$$" 2>/dev/null; then
+        rm -rf "$LOCK_DIR.stale.$$"
+        mkdir "$LOCK_DIR" 2>/dev/null || exit 0
+      else
+        exit 0
+      fi
     else
       exit 0
     fi
@@ -488,7 +495,25 @@ if ! mkdir "$LOCK_DIR" 2>/dev/null; then
   fi
 fi
 printf '%s\n' "$$" > "$LOCK_DIR/pid"
-trap 'rm -rf "$LOCK_DIR"; rm -f "$FAILURE_TMP"' EXIT HUP INT TERM
+# Release only a lock this process still owns. The previous handler removed
+# $LOCK_DIR unconditionally, so a script that had already lost the lock deleted
+# its SUCCESSOR's — and init sends SIGTERM here on every drain that outruns its
+# 30s spawnSync timeout, which made that the common case rather than the rare
+# one (KNODIN-23).
+knodin_release_lock() {
+  if [ "$(cat "$LOCK_DIR/pid" 2>/dev/null || true)" = "$$" ]; then
+    rm -rf "$LOCK_DIR"
+  fi
+  rm -f "$FAILURE_TMP"
+}
+trap 'knodin_release_lock' EXIT
+# Each signal exits explicitly. POSIX sh defers a trap until the foreground
+# command finishes and then RESUMES where it left off, so a handler that only
+# cleaned up dropped the lock and kept draining — two processors at once, and
+# Ctrl-C failed to cancel a foreground run at all.
+trap 'knodin_release_lock; trap - EXIT; exit 129' HUP
+trap 'knodin_release_lock; trap - EXIT; exit 130' INT
+trap 'knodin_release_lock; trap - EXIT; exit 143' TERM
 LOG_PATH="$REPO_ROOT/.knodin/indexer.log"
 if [ -f "$LOG_PATH" ]; then
   LOG_BYTES="$(wc -c < "$LOG_PATH" 2>/dev/null | tr -d '[:space:]')"
@@ -1433,6 +1458,87 @@ export async function initializeRepository(repo, options) {
         lifecycleLease.release();
     }
 }
+/**
+ * Rewrite lifecycle routing — the managed Git hooks and the background refresh
+ * script — without reading or writing a single line of agent configuration.
+ *
+ * This exists because a team-integrated repository whose hooks had died had no
+ * safe exit (KNODIN-31). `repair` fixes graph rows and leaves the dead indexer
+ * dead, so the schema drifts again; `init` rewrites tracked `AGENTS.md` /
+ * `GEMINI.md` / `.mcp.json`, which is churn every teammate diffs on a branch
+ * that has nothing to do with it; and `configure --scope personal` strips the
+ * shared block for everyone else on that branch. The one clean option,
+ * `init --scope personal`, is precisely the one refused in that state.
+ *
+ * So fault and remedy are matched in scope: the fault is in the hooks'
+ * contents, and this rewrites the hooks' contents. It deliberately does not
+ * index, does not touch graph rows, and never enters the `configureIntegration`
+ * block — a broken hook should not be able to change a scope preference. Run
+ * plain `knodin repair` alongside it when graph content is also damaged.
+ */
+export async function repairLifecycleRouting(repoPath, options) {
+    const resolvedRepo = path.resolve(repoPath);
+    if (runGit(resolvedRepo, ["rev-parse", "--is-inside-work-tree"]).trim() !== "true") {
+        throw new Error(`knodin repair --lifecycle: not a Git worktree: ${resolvedRepo}`);
+    }
+    const mirror = lookupMirror(resolvedRepo);
+    if (mirror) {
+        throw new Error(`knodin repair --lifecycle: ${resolvedRepo} is a read-only mirror of ${mirror.url}. Mirrors carry no lifecycle hooks by design, so there is no routing here to repair.`);
+    }
+    if (!path.isAbsolute(options.command[0])) {
+        throw new Error("knodin repair --lifecycle: packaged runtime command must be an absolute path");
+    }
+    const lifecycleLease = acquireRepairLease(resolvedRepo, "init");
+    try {
+        const knodinHooksDir = path.join(resolvedRepo, ".knodin", "hooks");
+        const hookInstallation = await prepareHookInstallation(resolvedRepo);
+        const hooksDir = hookInstallation.hooksDir;
+        await Promise.all([
+            fs.promises.mkdir(knodinHooksDir, { recursive: true }),
+            fs.promises.mkdir(hooksDir, { recursive: true }),
+        ]);
+        const backgroundPath = path.join(knodinHooksDir, "background-index.sh");
+        await fs.promises.writeFile(backgroundPath, backgroundScript(options.command), {
+            encoding: "utf-8",
+            mode: 0o755,
+        });
+        await fs.promises.chmod(backgroundPath, 0o755);
+        const hookManagerIntegration = installHookManagerIntegration(resolvedRepo);
+        for (const hookName of HOOK_NAMES) {
+            let preservedOriginal;
+            if (hookInstallation.trackedHooksDir) {
+                const relativeHook = `${hookInstallation.trackedHooksDir}/${hookName}`;
+                const sourceHook = path.join(resolvedRepo, relativeHook);
+                try {
+                    const stat = await fs.promises.stat(sourceHook);
+                    preservedOriginal =
+                        stat.isFile() && (stat.mode & 0o111) !== 0 ? `repo:${relativeHook}` : null;
+                }
+                catch {
+                    preservedOriginal = null;
+                }
+            }
+            await installManagedHook(hooksDir, hookName, preservedOriginal);
+        }
+        for (const entry of await fs.promises.readdir(hooksDir, { withFileTypes: true })) {
+            if (entry.isFile())
+                await preventLefthookAutoInstall(path.join(hooksDir, entry.name));
+        }
+        const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath, lifecycleLease.token);
+        await fs.promises.rm(path.join(knodinHooksDir, HOOK_FAILURE_FILE), { force: true });
+        return {
+            backgroundIndexer: ".knodin/hooks/background-index.sh",
+            hooksDirectory: path.relative(resolvedRepo, hooksDir) || ".",
+            gitHooks: [...HOOK_NAMES],
+            hookManagerIntegration,
+            lifecycleRefresh,
+            configurationChanges: [],
+        };
+    }
+    finally {
+        lifecycleLease.release();
+    }
+}
 async function matchesManagedFile(filePath, expected, executable) {
     try {
         const [content, stat] = await Promise.all([

package/dist/src/lifecycle-health.js

@@ -169,6 +169,41 @@ function recordedInterpreterIfMissing(backgroundScriptPath) {
     // wrong and the next environment without that fallback breaks silently.
     return recorded;
 }
+/**
+ * The interpreter a pre-fallback generated script pins, when it pins one.
+ *
+ * Scripts written before the `KNODIN_NODE` fallback (EASFDC-8497) invoke an
+ * absolute interpreter path with nothing to fall back to. Homebrew deletes its
+ * Cellar directory on upgrade, so `.../Cellar/node/<version>/bin/node`
+ * evaporates and every background refresh afterwards dies with exit 127 — in
+ * the background, where the only trace is a log file nobody reads. The graph
+ * then drifts until someone happens to run `status`. Observed across three
+ * repositories on one machine from a single `brew upgrade` (KNODIN-32), so the
+ * blast radius is every checkout initialized before the fix, not one.
+ *
+ * `recordedInterpreterIfMissing` cannot see this: it keys off a `KNODIN_NODE=`
+ * line, and these scripts have none, so the most dangerous shape reads as
+ * healthy. Detection is the absence of that line in a script that is otherwise
+ * recognisably ours.
+ *
+ * Returns null when the script is current, unreadable, or shaped unfamiliarly.
+ * A script we cannot parse is not evidence of a pinned interpreter, and
+ * guessing would invent a failure rather than report one.
+ */
+function pinnedInterpreterWithoutFallback(backgroundScriptPath) {
+    let contents;
+    try {
+        contents = fs.readFileSync(backgroundScriptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    if (/^KNODIN_NODE=/m.test(contents))
+        return null;
+    if (!contents.includes("hook-refresh"))
+        return null;
+    return /'(\/[^']*\/bin\/node)'/.exec(contents)?.[1] ?? null;
+}
 function readRefreshFailure(repo) {
     const failurePath = path.join(repo, ".knodin", "hooks", HOOK_FAILURE_FILE);
     if (!fs.existsSync(failurePath))
@@ -253,7 +288,15 @@ export function inspectLifecycleHealth(repoPath) {
         issues.push("background indexer is missing or not executable");
     const staleInterpreter = backgroundReady ? recordedInterpreterIfMissing(background) : null;
     if (staleInterpreter)
-        issues.push(`background indexer records a Node interpreter that no longer exists (${staleInterpreter}); run \`knodin init\` to rewrite the hook`);
+        issues.push(`background indexer records a Node interpreter that no longer exists (${staleInterpreter}); run \`knodin repair --lifecycle\` to rewrite the hook`);
+    // Reported even while that interpreter still exists. The failure is latent
+    // by construction — the script works right up until the next `brew upgrade`
+    // deletes the path out from under it, and then fails silently in the
+    // background. Waiting for the breakage would mean reporting it only after
+    // the graph had already drifted (KNODIN-32).
+    const pinnedInterpreter = backgroundReady && !staleInterpreter ? pinnedInterpreterWithoutFallback(background) : null;
+    if (pinnedInterpreter)
+        issues.push(`background indexer predates the interpreter fallback and pins ${pinnedInterpreter} with no alternative; a Node upgrade will break refresh silently — run \`knodin repair --lifecycle\` to rewrite the hook`);
     const lastError = readRefreshFailure(repo);
     if (lastError)
         issues.push(`${lastError} See .knodin/indexer.log for details`);
@@ -299,7 +342,7 @@ export function attachLifecycleHealth(repo, graph) {
         },
         repairSteps: [
             ...graph.repairSteps,
-            "Run `knodin init` to restore managed lifecycle hooks.",
+            "Run `knodin repair --lifecycle` to restore managed lifecycle hooks without touching agent configuration.",
             "Run `knodin status` again to verify graph and refresh-path health.",
         ],
         lifecycle,
@@ -312,7 +355,7 @@ export function attachRepairLifecycle(repo, result) {
         ...result,
         lifecycle,
         nextSteps: lifecycle.status === "degraded"
-            ? ["Run `knodin init` to restore lifecycle routing, then `knodin status`."]
+            ? ["Run `knodin repair --lifecycle` to restore lifecycle routing, then `knodin status`."]
             : [],
     };
 }

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

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

package/dist/src/repair-progress.js

@@ -23,6 +23,7 @@ export function parseRepairCliArgs(args) {
     let json = false;
     let jsonl = false;
     let plan = false;
+    let lifecycle = false;
     const seen = new Set();
     const markSeen = (flag) => {
         if (seen.has(flag))
@@ -42,6 +43,11 @@ export function parseRepairCliArgs(args) {
             plan = true;
             continue;
         }
+        if (argument === "--lifecycle") {
+            markSeen(argument);
+            lifecycle = true;
+            continue;
+        }
         if (argument === "--json" || argument === "--jsonl") {
             markSeen(argument);
             if (argument === "--json")
@@ -86,12 +92,18 @@ export function parseRepairCliArgs(args) {
     }
     if (json && jsonl)
         throw new Error("knodin repair: --json and --jsonl are mutually exclusive");
+    // `--plan` explains what a graph repair would do; a lifecycle repair does not
+    // touch the graph, so there is nothing for it to explain. Refusing beats
+    // printing a graph plan for a run that would not carry it out.
+    if (plan && lifecycle)
+        throw new Error("knodin repair: --plan and --lifecycle are mutually exclusive");
     return {
         progress,
         progressExplicit,
         progressIntervalMs,
         output: jsonl ? "jsonl" : json ? "json" : "human",
         plan,
+        lifecycle,
     };
 }
 export function createRepairPlan(health) {

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

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

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

@@ -70,10 +70,8 @@ export async function closeKnodinToolEngine() {
     if (initializedEngine)
         await initializedEngine.close();
     initializedEngine = null;
-    compactReadyRepos.clear();
 }
 const localTelemetry = [];
-const compactReadyRepos = new Set();
 let cachedSchemaTokens;
 function gatewaySchemaTokens() {
     cachedSchemaTokens ??= countOutputTokens(JSON.stringify(buildDocumentedKnodinTools()[0]?.inputSchema ?? {}));
@@ -82,15 +80,24 @@ function gatewaySchemaTokens() {
 function inspectGatewayGraphHealth(repo) {
     return inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
 }
+/**
+ * Probe on EVERY compact call, exactly as the non-compact path does.
+ *
+ * This used to latch a repository as ready after one successful probe and never
+ * look again for the life of the process. Nothing invalidated that latch —
+ * `closeKnodinToolEngine` clears it but has no production caller — so once
+ * `.knodin/` was deleted or re-inited from another terminal, a long-lived MCP
+ * server kept answering compact queries against a database the open path had
+ * silently recreated as an empty schema (`CREATE TABLE IF NOT EXISTS`). The
+ * result was "no matches": indistinguishable from a true negative, and the exact
+ * confident-but-wrong answer this product exists to avoid (KNODIN-18).
+ *
+ * The probe is cheap — `engine.status(..., { audit: "cached" })` — so the latch
+ * was buying very little in exchange for that failure mode.
+ */
 async function compactGraphUnavailable(repo) {
-    const key = nodePath.resolve(repo);
-    if (compactReadyRepos.has(key))
-        return null;
     const health = await inspectGatewayGraphHealth(repo);
-    if (!health.available)
-        return health;
-    compactReadyRepos.add(key);
-    return null;
+    return health.available ? null : health;
 }
 /** Runs `fn`, converting any thrown error into a structured `{ error }` result
  * instead of letting it escape into the stdio transport. Extracted from the
@@ -1045,6 +1052,22 @@ function validateKnodinArgs(args) {
     if (args.client !== undefined &&
         !["claude", "codex", "gemini", "copilot", "antigravity"].includes(args.client))
         throw new Error("knodin: invalid client");
+    // `auditRange`/`auditBase`/`auditHead` select a range of pull requests for
+    // `prs`, and nothing else consumes them. `review` used to accept them and
+    // silently review HEAD~1..HEAD instead, returning `base: "HEAD~1"` under a
+    // full `staleness: fresh` envelope — so it did not merely fail to answer the
+    // question asked, it confidently answered a different one, and a caller who
+    // did not inspect `base` would read the result as authoritative for their
+    // range (KNODIN-27). An unused-parameter error is always better than that.
+    //
+    // The review equivalent is `diffScope: "compare"` with `from`/`toRevision`,
+    // which is what the CLI's `--scope compare --from X --to Y` maps to.
+    const auditOnly = ["auditRange", "auditBase", "auditHead"].filter((name) => args[name] !== undefined);
+    if (auditOnly.length > 0 && args.operation !== "prs")
+        throw new Error(`knodin ${args.operation}: ${auditOnly.join(", ")} ${auditOnly.length === 1 ? "is" : "are"} accepted only by \`prs\`` +
+            (args.operation === "review"
+                ? '; to review a revision range pass diffScope: "compare" with `from` and `toRevision`'
+                : ""));
 }
 function compactExplainSource(result) {
     const source = result.source

package/docs/releases/0.11.0.md

@@ -0,0 +1,227 @@
+# knodin 0.11.0
+
+Nine defects from one adversarial review of `main`, plus the two things that
+review's own fixes exposed. The theme running through most of them is the
+failure this tool exists to prevent: an answer that is wrong and looks fine.
+
+## A compact answer could report "no matches" from a graph that was gone
+
+`compactGraphUnavailable` cached a repository as ready after one successful
+probe and never looked again for the life of the process. Nothing invalidated
+that latch — `closeKnodinToolEngine` clears it but has no production caller — so
+in a long-lived MCP server, deleting or re-initialising `.knodin` from another
+terminal left compact operations answering from a database the open path had
+silently recreated as an empty schema. `CREATE TABLE IF NOT EXISTS` does not
+error; it just produces a graph with nothing in it.
+
+The result was "no matches", which is indistinguishable from a true negative.
+The non-compact path had it right all along: it re-probes before **and** after
+every query. Compact now does the same. The probe is
+`engine.status(..., { audit: "cached" })`, so the latch was buying very little
+in exchange for that failure mode.
+
+Two other things pointed the same direction and are fixed with it. The compact
+renderer defaulted a **missing** staleness to `fresh`, the opposite of the
+engine's own `stalenessFor()` default of `unknown` — and because search stamps
+staleness per row while `SearchPage` carries no page-level field, a zero-row
+page had nothing to read it from. An empty compact search on a stale or
+unprobed graph therefore rendered as `fresh 0/0`: an authoritative-looking
+negative assembled entirely from absent evidence. Missing evidence is now
+`unknown`.
+
+And the CLI's `project_overview` fast path reported `fresh` on the strength of a
+size-and-mtime sweep over the files the snapshot **already knew about**. A file
+added since the snapshot is not in that set, so it was never checked, never
+counted, and never mentioned — while the overview still called itself fresh. It
+now also reads back the directories it aggregates and looks for an indexable
+sibling the snapshot has never seen, with the indexable extensions derived from
+the snapshot's own file list rather than hardcoded.
+
+That last check has a bound worth stating: it sees additions to directories the
+snapshot already covers, which is where source files are overwhelmingly added,
+but a brand-new top-level directory is still missed. Recognising one would mean
+re-deriving the walker's prune rules and re-walking the tree, which is the cost
+this fast path exists to avoid. The result's `upgrade` pointer already routes a
+caller who needs certainty to the full `architecture_overview` query.
+
+## The MCP worker restart limit was a permanent latch
+
+`MAX_RESTARTS` is meant to be a rate — three crashes inside a sixty-second
+window. It was not. `restartTimes` was pruned only in the child-exit handler,
+and once the gate threw `KNODIN_RESTART_LIMIT` no child was ever spawned, so no
+exit event could ever fire to prune it. The window never elapsed.
+
+Three transient crashes — an OOM under load, a full disk, a corrupt database
+later repaired — therefore killed that repository for the life of the gateway
+process. The `RepositoryWorker` is cached per repository and never evicted, so
+nothing short of restarting the whole server cleared it, and the error message
+never said so. The gate now prunes on the way in, and names the window.
+
+## One crash killed a parse-pool lane for the whole run
+
+`PoolWorkerHandle` has no listener removal, so a replaced worker's listeners
+stay live — and they closed over the *slot*, whose `.handle` is by then the
+replacement. A crashed worker's inevitable late `exit` re-entered
+`onSlotFailure` and terminated its own replacement, cancelling the one
+documented retry and leaving the lane dead. On a single-worker pool the whole
+run degraded to sequential inline parsing; if the replacement's response landed
+first, the late exit instead killed an unrelated in-flight file.
+
+Listeners are now bound to the handle they were registered on, mirroring the
+`pending.child !== child` guard the MCP supervisor already carried.
+
+Worth recording how this survived review: `FakeWorker` in `parse-pool.spec.ts`
+never emitted `exit` — not after an error, not on `terminate()`. The pool never
+saw the second event, so the bug had no way to appear. With realistic process
+semantics restored, removing the new guard fails the new test **and** the
+pre-existing "retries a crashed task once" test. That retry path was dead code
+against real workers, and had been asserted as working.
+
+## Secrets spelled the way secrets are actually spelled
+
+The shared redaction pattern began with `\b`, which cannot match between `_` and
+a letter. So it caught a bare `password=` and let through
+`AWS_SECRET_ACCESS_KEY=`, `DB_PASSWORD=`, `NPM_TOKEN=`, and every `*_SECRET=` —
+the dominant real-world spelling, and the one that appears in a `.env` line
+quoted into an error message or a CI log dump. Both disclosure paths, the
+diagnostics bundle and the compressed output artifact, drew on that one pattern,
+so both leaked.
+
+The keyword now takes a `[\w-]*` prefix and a `[_-]`-led suffix, so the whole
+identifier matches and the name is preserved while the value is not. The suffix
+is `[_-]`-led rather than a bare `[\w-]*` deliberately: knodin echoes source
+into both artifacts, and an unanchored tail redacted the value of a plain
+`const tokenCount = 5`.
+
+Not added, deliberately: a standalone value-shape pattern for AWS secret keys.
+Those are `[A-Za-z0-9/+]{40}`, which also matches every 40-character git SHA and
+any similar-length base64 blob. A context-free pattern would redact commit
+hashes throughout diagnostics, and every realistic carrier of that value — an
+environment variable, a credentials file — is name-prefixed and now covered.
+
+## A sealed artifact could serve source for a checkout it does not describe
+
+Sealed artifacts are designed to be shared across machines, which makes an
+artifact untrusted input. Its attestation was read with a bare
+`JSON.parse(...) as SealAttestation` — an unchecked cast — and the
+self-declared `repository.path` was registered into a process-global map that
+every engine source read consults **before** the filesystem. A crafted artifact
+naming a victim's real checkout path could therefore serve its own bytes to a
+concurrent live query on that repository.
+
+The attestation is now validated as a whole shape, and a database that
+misrepresents itself raises a typed error rather than being quietly downgraded
+to "not a sealed artifact". The attested path is refused on **content
+disagreement** rather than on mere existence: sealing and then querying on the
+same checkout is a real flow that an existence check would break, so instead
+every embedded file that also exists under the attested directory is compared
+against the hash recorded at seal time. Files absent there are not disagreement
+— a removed checkout is exactly what an artifact is for.
+
+Identity and `sealedCommit` are deliberately **not** used for this. Both are
+attacker-supplied strings, and an attacker targeting a specific victim already
+knows their `owner/name`. Content hashes are the only fingerprint in the
+attestation an attacker cannot satisfy while still doing harm: to poison a live
+checkout the embedded bytes must differ from the real files, which is precisely
+what trips the gate.
+
+Registrations are also refcounted now. Two artifacts attesting the same path
+used to have the first `close()` unregister the other's source, leaving it
+reading `""`.
+
+## A repo-wide text search held the whole working tree in memory
+
+`searchRepoText` read every readable file's full content into one array before
+searching any of it, with no size cap, and the binary NUL-sniff happened *after*
+the read rather than before. The walk deliberately skips the source-extension
+filter, so lockfiles, NDJSON dumps, fixtures and generated JSON all came in
+whole. On a tree carrying gigabytes of non-pruned text, one call drove RSS to
+the total text size. The response budget could not help: it applies to a result
+object that by then already exists.
+
+Files are now stat-checked and skipped above 4 MiB — reported through the same
+`uncovered` list, never dropped — and searched one at a time, so at most one
+file's content is live. Matches are capped at 5,000 with a new `truncated` flag,
+documented as meaning the remaining files were **not** searched, so an absent
+file proves nothing.
+
+## The background refresh script deleted locks it did not own
+
+The generated `background-index.sh` trapped `HUP`/`INT`/`TERM` with a handler
+that removed the lock directory and did not exit. POSIX `sh` defers a trap until
+the foreground command finishes and then resumes where it left off — so when
+`init` sent `SIGTERM` at its thirty-second drain timeout, the script freed the
+lock and **kept draining**. The next commit's instance acquired the now-free
+lock, and the first script's eventual `EXIT` trap deleted its successor's lock
+unconditionally, because that `rm -rf` had no ownership check. Stale-lock
+takeover was also `rm -rf` followed by `mkdir`, which two processes observing
+the same dead pid could both complete.
+
+Release is now guarded on the recorded pid, each signal exits explicitly, and
+takeover claims the stale lock by renaming it, which only one racer can win. The
+inner repair lease kept this away from database corruption; what it produced was
+spurious failure markers, retained events, and `Ctrl-C` failing to cancel a
+foreground run.
+
+## Each commit is now keyed to its own Jira
+
+`scripts/jira-work-guard.sh` required every non-merge commit to carry the branch
+name's **first** Jira key, which made a branch equivalent to exactly one issue.
+Work spanning several tickets then had two options and both lose something: land
+it as one commit labelled with a ticket covering a fraction of it, or split it
+into one branch per ticket and multiply CI runs for a single coherent change.
+This release hit exactly that — nine fixes from one review.
+
+A branch is a container for work. It still has to be Jira-backed, but the
+per-issue claim now belongs to each commit, which is the more durable record
+anyway: branch names are deleted after merge and commit subjects are not.
+`pre-push` also names the offending commit's short SHA now, because a push
+carries many commits and "commit message has no JIRA key" left the author
+bisecting their own branch.
+
+The trade-off is real and worth naming: this drops the check that caught a
+commit keyed to an unrelated project — a typo, or a message copied from another
+branch. Restoring it would mean validating keys against Jira, which this guard
+deliberately does not do. It is a local hook with no network.
+
+## Timing budgets in the test suite were measuring the scheduler
+
+Found because this release's own two new spec files made the suite fail, twice,
+on two different tests that had nothing to do with the changes.
+
+Eleven specs independently hard-coded a fifteen-second budget for a spawned
+child process. Shard 12 also holds `behavior-contract.spec.ts`, which runs
+CPU-bound for about 380 seconds — 85% of that shard's wall time. A child spawned
+beside it is starved, not slow: a CLI spawn costs about 0.4s idle and a progress
+worker about 1.7s, so fifteen seconds looks like a 40x margin right up until
+contention eats it whole.
+
+Which spec pays is decided by where vitest queues its file, and that moves
+whenever any spec file is added anywhere in the repository. Measured on an
+uninstrumented `npm test`, same host, identical shard membership: the progress
+worker started in 1.7s queued at t=28s, and blew the whole fifteen seconds
+queued at t=408s. The shard's total wall time was unchanged (454s against 448s
+before the change) and `behavior-contract` was in fact 8s faster, so this was
+never added load — separately confirmed by measuring CLI spawn cost directly at
+367–468ms against 374–571ms before.
+
+`SUBPROCESS_BUDGET_MS` now lives once, in the support helper those specs already
+import, carrying that measurement. It is unconditional: two specs had already
+been widened only under `KNODIN_COVERAGE_SHARD`, on the theory that
+instrumentation causes the contention. It does not — the sixteen concurrent
+shards do, in uninstrumented runs too — and gating on that is why this kept
+being rediscovered one file at a time. The budget is an upper bound, not a
+sleep, so it costs nothing in the passing case and no assertion is weakened.
+
+One thing this does not fix, recorded so it is not rediscovered: a single spec
+at ~380 seconds sets the critical path for the entire gate and is what starves
+everything scheduled beside it. Widening budgets treats the symptom.
+
+## Verification
+
+`npm test` (sixteen shards, 2,088 tests), `npm run lint`, `npm run typecheck`,
+`npm run check:hygiene`, and `npm run test:pack-install` pass. Every fix above
+is pinned by a test, including two new specs —
+`background-refresh-lock.spec.ts` and `compact-graph-availability.spec.ts` — and
+new cases in the credential-parity, supervisor, parse-pool, structural-fast-path,
+sealed-open, text-matches and jira-work-guard specs.