knodin 0.10.8 → 0.11.0

package/dist/src/compact-structural.js

@@ -12,12 +12,17 @@ export function compactIdentity(identity) {
 export function expandCompactIdentity(identity) {
     return identity?.startsWith("~") ? `${IDENTITY_PREFIX}${identity.slice(1)}*` : identity;
 }
+// Missing evidence is "unknown", never "fresh" — the same default the engine's
+// own `stalenessFor()` uses. Search stamps staleness per row and `SearchPage`
+// carries no page-level field, so a zero-row page has no row to read it from:
+// defaulting to "fresh" rendered an empty result on a stale or unprobed graph as
+// `fresh 0/0`, an authoritative-looking negative (KNODIN-22).
 function freshness(value) {
     if (value === "reconciled")
         return "reconciled";
-    if (value === "unknown")
-        return "unknown";
-    return "fresh";
+    if (value === "fresh")
+        return "fresh";
+    return "unknown";
 }
 function terseSignature(row) {
     const signature = row.signature?.replace(/\s+/g, " ").trim() ?? "";

package/dist/src/credential-patterns.js

@@ -25,8 +25,21 @@ export function credentialPatterns() {
             // consumed BEFORE the value, because `authorization: Bearer <token>`
             // otherwise matches only the word "Bearer" — redacting the label and
             // preserving the credential, exactly inverted (KNODIN-10).
+            //
+            // The keyword is surrounded by `[\w-]*` rather than anchored with `\b`,
+            // because `\b` does not exist between `_` and a letter: a leading `\b`
+            // could never match inside `AWS_SECRET_ACCESS_KEY`, and a trailing one
+            // stopped the name short of the `=`. That excluded the dominant spelling
+            // of every real secret — `AWS_SECRET_ACCESS_KEY=`, `DB_PASSWORD=`,
+            // `NPM_TOKEN=`, any `*_SECRET=` — while `password=` alone was redacted
+            // (KNODIN-19).
+            //
+            // The trailing half is `[_-]`-led rather than a bare `[\w-]*` so the
+            // keyword has to be a whole segment of the name. knodin echoes source
+            // into diagnostics and compressed output, and an unanchored tail
+            // redacted the value of a plain `const tokenCount = 5`.
             label: "credential",
-            pattern: /\b(authorization|password|passwd|secret|token|api[_-]?key)(\s*[:=]\s*)(?:(?:bearer|basic|digest|token)\s+)?[^\s,;]+/gi,
+            pattern: /(?<![\w-])([\w-]*(?:authorization|password|passwd|secret|token|api[_-]?key)(?:[_-][\w-]*)?)(\s*[:=]\s*)(?:(?:bearer|basic|digest|token)\s+)?[^\s,;]+/gi,
             preservedGroups: 2,
         },
         {

package/dist/src/engine/parse-pool.js

@@ -147,10 +147,27 @@ class PoolRun {
         return this.buckets.get(bestKey)?.pop() ?? null;
     }
     attach(slot) {
-        slot.handle.onMessage((response) => this.onResponse(slot, response));
-        slot.handle.onError((error) => this.onSlotFailure(slot, error.message));
-        slot.handle.onExit((code) => {
-            if (slot.inFlight)
+        // Bind these listeners to the handle they were registered on, not just to
+        // the slot. `PoolWorkerHandle` offers no listener removal, so a replaced
+        // worker's listeners stay live and still close over the slot — whose
+        // `.handle` is by then the replacement. A crashed worker's inevitable late
+        // `exit` therefore re-entered `onSlotFailure` and terminated its OWN
+        // replacement, cancelling the one documented retry and leaving the lane
+        // dead; on a one-worker pool that dropped the whole run to inline parsing
+        // (KNODIN-20). Mirrors the `pending.child !== child` guard the MCP
+        // supervisor already carries.
+        const handle = slot.handle;
+        const current = () => slot.handle === handle;
+        handle.onMessage((response) => {
+            if (current())
+                this.onResponse(slot, response);
+        });
+        handle.onError((error) => {
+            if (current())
+                this.onSlotFailure(slot, error.message);
+        });
+        handle.onExit((code) => {
+            if (current() && slot.inFlight)
                 this.onSlotFailure(slot, `worker exited with code ${code}`);
         });
     }

package/dist/src/engine/seal.js

@@ -22,16 +22,114 @@ const SEAL_SCHEMA = [
 function countLines(buf) {
     return buf.toString("utf8").split("\n").length;
 }
+/**
+ * A database claims to be an artifact but carries an attestation the reader
+ * cannot trust.
+ *
+ * Distinct from "no attestation at all", which is an ordinary index and a
+ * routine answer. Every field here is consumed as a decision downstream — the
+ * schema gate, the version gate, and the repository path the artifact is
+ * allowed to serve source for — so a half-populated object must stop at the
+ * reader rather than reach them.
+ */
+export class SealAttestationError extends Error {
+    code = "malformed-attestation";
+    constructor(reason) {
+        super(reason);
+        this.name = "SealAttestationError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validates the WHOLE shape, not just the fields the immediate caller reads.
+ * A sealed artifact is transported between machines, so it is untrusted input
+ * rather than something this process wrote (KNODIN-21), and an unchecked cast
+ * would let `undefined` stand where a version or a path belongs.
+ */
+function validateAttestation(value) {
+    const bad = (reason) => {
+        throw new SealAttestationError(`seal attestation is malformed: ${reason}`);
+    };
+    if (!isRecord(value))
+        return bad("not an object");
+    const str = (key, on) => typeof on[key] === "string" ? on[key] : bad(`${key} is not a string`);
+    const num = (key, on) => typeof on[key] === "number" && Number.isFinite(on[key])
+        ? on[key]
+        : bad(`${key} is not a finite number`);
+    const nullableStr = (key, on) => on[key] === null || typeof on[key] === "string"
+        ? on[key]
+        : bad(`${key} is not a string or null`);
+    const obj = (key) => isRecord(value[key]) ? value[key] : bad(`${key} is not an object`);
+    if (value.sealVersion !== 1)
+        bad(`unsupported sealVersion ${String(value.sealVersion)}`);
+    const repository = obj("repository");
+    const health = obj("health");
+    const source = obj("source");
+    const embeddings = obj("embeddings");
+    const policy = source.policy;
+    if (policy !== "all-indexed" && policy !== "excluded")
+        bad(`unsupported source policy ${String(policy)}`);
+    const stripped = embeddings.stripped;
+    if (typeof stripped !== "boolean")
+        bad("embeddings.stripped is not a boolean");
+    return {
+        sealVersion: 1,
+        knodinVersion: str("knodinVersion", value),
+        schemaVersion: num("schemaVersion", value),
+        repository: {
+            identity: str("identity", repository),
+            path: str("path", repository),
+            remoteUrl: nullableStr("remoteUrl", repository),
+        },
+        sealedCommit: str("sealedCommit", value),
+        sealedRef: nullableStr("sealedRef", value),
+        sealedAt: str("sealedAt", value),
+        health: {
+            status: str("status", health),
+            pendingPaths: num("pendingPaths", health),
+            freshness: str("freshness", health),
+        },
+        source: {
+            policy: policy,
+            files: num("files", source),
+            uniqueBlobs: num("uniqueBlobs", source),
+            rawBytes: num("rawBytes", source),
+            storedBytes: num("storedBytes", source),
+        },
+        embeddings: { stripped: stripped, removed: num("removed", embeddings) },
+    };
+}
+/**
+ * `null` when the database carries no attestation; THROWS
+ * `SealAttestationError` when it carries one that does not validate. The split
+ * has teeth: "ordinary index" is something a caller falls back from, while a
+ * database misrepresenting itself must not be quietly downgraded to the same
+ * answer.
+ */
 export function readSealAttestation(db) {
+    let raw;
     try {
         const row = db
             .query("SELECT value FROM meta WHERE key = 'sealAttestation'")
             .get();
-        return row ? JSON.parse(row.value) : null;
+        if (!row)
+            return null;
+        raw = row.value;
     }
     catch {
+        // No `meta` table, or an unreadable one: not a sealed artifact.
         return null;
     }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new SealAttestationError(`seal attestation is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return validateAttestation(parsed);
 }
 /**
  * Reads embedded source out of a sealed artifact.
@@ -64,9 +162,30 @@ export function listSealedFiles(db) {
         .all()
         .map((row) => row.filePath);
 }
-/** True when this database carries embedded source, i.e. can answer with no checkout. */
+/**
+ * Content hash of every embedded file, as recorded at seal time.
+ *
+ * The hash is over the RAW bytes, so a caller can compare against a file on
+ * disk without decompressing the blob.
+ */
+export function listSealedFileHashes(db) {
+    return db
+        .query("SELECT filePath, sha256 FROM sealed_file ORDER BY filePath")
+        .all();
+}
+/**
+ * True when this database carries embedded source, i.e. can answer with no
+ * checkout. A malformed attestation answers false: it is not an artifact any
+ * reader here can serve from, and this predicate's callers route on it rather
+ * than handle it.
+ */
 export function isSealedDatabase(db) {
-    return readSealAttestation(db) !== null;
+    try {
+        return readSealAttestation(db) !== null;
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Produce a sealed artifact, or refuse with a machine-readable code.

package/dist/src/engine/sealed-open.js

@@ -1,9 +1,10 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { KNODIN_VERSION as RUNTIME_VERSION } from "../version.js";
 import { KNODIN_SCHEMA_VERSION, registerSealedRepository, unregisterSealedRepository, } from "./index.js";
-import { readSealAttestation } from "./seal.js";
+import { listSealedFileHashes, readSealAttestation, SealAttestationError, } from "./seal.js";
 import { Database } from "./sqlite.js";
 export function openSealedArtifact(artifactPath, options = {}) {
     const resolved = path.resolve(artifactPath);
@@ -20,7 +21,18 @@ export function openSealedArtifact(artifactPath, options = {}) {
             reason: error instanceof Error ? error.message : String(error),
         };
     }
-    const attestation = readSealAttestation(db);
+    let attestation;
+    try {
+        attestation = readSealAttestation(db);
+    }
+    catch (error) {
+        db.close();
+        return {
+            ok: false,
+            code: error instanceof SealAttestationError ? "malformed-attestation" : "unreadable",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
     if (!attestation) {
         db.close();
         return {
@@ -84,10 +96,31 @@ export function openSealedArtifact(artifactPath, options = {}) {
     // only the mount would leave those internal reads falling through to a
     // filesystem that does not have the source, which fails as "" rather than
     // loudly.
-    registerSealedRepository(mountDir, db);
     const attestedPath = attestation.repository.path;
-    if (attestedPath && path.resolve(attestedPath) !== path.resolve(mountDir))
-        registerSealedRepository(attestedPath, db);
+    const registerAttested = attestedPath && path.resolve(attestedPath) !== path.resolve(mountDir);
+    // The attested path is chosen by the artifact, and the registry it lands in
+    // takes precedence over the filesystem for every source read in the
+    // process. An artifact naming a path that exists here would therefore serve
+    // its own bytes to live queries against that checkout (KNODIN-21). Sealing
+    // and opening on ONE machine is a real flow, so this refuses on
+    // DISAGREEMENT rather than on existence: where the embedded blobs match the
+    // files on disk the artifact describes that tree and shadowing it changes
+    // nothing, and where they do not, whichever side is wrong, no read of that
+    // path can be trusted.
+    if (registerAttested) {
+        const conflict = firstSourceDisagreement(db, path.resolve(attestedPath));
+        if (conflict) {
+            db.close();
+            return {
+                ok: false,
+                code: "path-conflict",
+                reason: `artifact attests ${path.resolve(attestedPath)}, which exists here with different source (${conflict}); re-seal from this checkout, or open the artifact where that path is absent`,
+            };
+        }
+    }
+    acquireSealedRepository(mountDir, db);
+    if (registerAttested)
+        acquireSealedRepository(attestedPath, db);
     const sealedAt = Date.parse(attestation.sealedAt);
     const ageDays = Number.isNaN(sealedAt)
         ? 0
@@ -100,13 +133,97 @@ export function openSealedArtifact(artifactPath, options = {}) {
         degraded,
         ageDays,
         close() {
-            unregisterSealedRepository(mountDir);
-            if (attestedPath)
-                unregisterSealedRepository(attestedPath);
+            releaseSealedRepository(mountDir, db);
+            if (registerAttested)
+                releaseSealedRepository(attestedPath, db);
             db.close();
         },
     };
 }
+/**
+ * Open handles per registered path, most recent last.
+ *
+ * The engine's registry is a bare path→database map, so two artifacts
+ * attesting the same repository would have the first `close()` unregister the
+ * other's source and leave it reading `""` (KNODIN-21). Held here rather than
+ * widened there because the map is the engine's chokepoint for a single
+ * answer to "where do bytes for this path come from"; ownership of the
+ * handles that claim it belongs to whoever opened them.
+ */
+const sealedRegistrations = new Map();
+function acquireSealedRepository(repoPath, db) {
+    const key = path.resolve(repoPath);
+    const held = sealedRegistrations.get(key) ?? [];
+    held.push(db);
+    sealedRegistrations.set(key, held);
+    registerSealedRepository(key, db);
+}
+function releaseSealedRepository(repoPath, db) {
+    const key = path.resolve(repoPath);
+    const held = sealedRegistrations.get(key);
+    if (!held)
+        return;
+    const last = held.lastIndexOf(db);
+    if (last === -1)
+        return;
+    held.splice(last, 1);
+    // Re-point at a surviving handle rather than leaving the closed one
+    // registered: an unregister here would fall through to a filesystem that
+    // has no source, and a closed database would throw on the next read.
+    const survivor = held.at(-1);
+    if (survivor)
+        registerSealedRepository(key, survivor);
+    else {
+        sealedRegistrations.delete(key);
+        unregisterSealedRepository(key);
+    }
+}
+/**
+ * First embedded file whose bytes differ from the file at the same relative
+ * path under `dir`, or `null` when every one that exists there agrees.
+ *
+ * Files absent from `dir` are not disagreement — a partially or wholly removed
+ * checkout is precisely what an artifact is for. Compared by hash against the
+ * one recorded at seal time, which is over raw bytes, so nothing is
+ * decompressed to answer this.
+ *
+ * `filePath` comes out of the artifact and is therefore attacker-controlled, so
+ * every candidate is resolved and required to stay under `dir` before it is
+ * opened. A `..` segment would otherwise have this check read and hash files
+ * outside the attested checkout — reachable during `openSealedArtifact`, and
+ * pure attack surface, since a repository-relative path never needs to escape.
+ * An entry that does is reported as disagreement rather than skipped: it is not
+ * a path this artifact can honestly claim, and failing closed keeps a traversal
+ * from being a way to hide an entry from this comparison.
+ */
+function firstSourceDisagreement(db, dir) {
+    let stat;
+    try {
+        stat = fs.statSync(dir);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isDirectory())
+        return null;
+    const root = path.resolve(dir);
+    for (const entry of listSealedFileHashes(db)) {
+        const candidate = path.resolve(root, entry.filePath);
+        if (candidate !== root && !candidate.startsWith(root + path.sep))
+            return entry.filePath;
+        let onDisk;
+        try {
+            onDisk = fs.readFileSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        const hash = crypto.createHash("sha256").update(onDisk).digest("hex");
+        if (hash !== entry.sha256)
+            return entry.filePath;
+    }
+    return null;
+}
 /**
  * Read at call time rather than imported as a constant so that a test can
  * exercise the soft gate without rebuilding the package version.

package/dist/src/engine/text-matches.js

@@ -25,6 +25,24 @@ import { walkRepoFiles } from "./file-walker.js";
 const WORD_CHARACTER = /[\p{L}\p{N}_]/u;
 /** Upper bound on `TextMatch.enclosingText`, so one row cannot flood a preview. */
 const ENCLOSING_TEXT_LIMIT = 120;
+/**
+ * Largest file this search will read, in bytes.
+ *
+ * R1 deliberately drops the source-extension filter, so the walk reaches
+ * lockfiles, NDJSON dumps, fixtures and generated JSON as well as prose. Four
+ * mebibytes clears every hand-written source or document file by a wide margin
+ * while excluding the generated artefacts that would otherwise decide the
+ * process's peak memory. Oversized files are reported in `uncovered`, never
+ * dropped.
+ */
+export const MAX_SEARCHABLE_FILE_BYTES = 4 * 1024 * 1024;
+/**
+ * Largest number of matches this search will accumulate.
+ *
+ * Past this the result is no longer reviewable and the match objects alone
+ * dominate memory; the honest answer is a bounded list plus `truncated: true`.
+ */
+export const MAX_TEXT_MATCHES = 5_000;
 function isWordCharacter(value) {
     return value !== undefined && WORD_CHARACTER.test(value);
 }
@@ -164,86 +182,101 @@ function classifyAgainstTree(parser, content, raw) {
  * over a large repository touches enough files to reproduce it exactly.
  */
 export async function searchFiles(files, term, loadLanguage, newParser, options = {}) {
-    const caseSensitive = options.caseSensitive ?? true;
-    const matches = [];
-    const uncovered = [];
-    let filesSearched = 0;
+    const state = newSearchState();
     for (const { file, content } of files) {
-        const raw = findOccurrences(content, term, caseSensitive);
-        filesSearched++;
-        if (raw.length === 0)
-            continue;
-        let classified = null;
-        let language = null;
+        await searchOneFile(state, file, content, term, loadLanguage, newParser, options);
+        if (state.truncated)
+            break;
+    }
+    return { ...state, searched: true };
+}
+function newSearchState() {
+    return { matches: [], uncovered: [], filesSearched: 0, truncated: false };
+}
+/**
+ * Search and classify one file, appending to `state`.
+ *
+ * Takes a single file's content rather than a list so that a repository-wide
+ * search never has to hold more than one file in memory at once (KNODIN-24).
+ * Sets `state.truncated` when the match cap is reached; the caller is
+ * responsible for stopping there.
+ */
+async function searchOneFile(state, file, content, term, loadLanguage, newParser, options) {
+    const caseSensitive = options.caseSensitive ?? true;
+    const raw = findOccurrences(content, term, caseSensitive);
+    state.filesSearched++;
+    if (raw.length === 0)
+        return;
+    let classified = null;
+    let language = null;
+    try {
+        language = await loadLanguage(file);
+    }
+    catch {
+        // A grammar that will not load costs classification, not the match.
+        language = null;
+    }
+    if (language) {
+        const parser = newParser();
         try {
-            language = await loadLanguage(file);
+            parser.setLanguage(language);
+            classified = classifyAgainstTree(parser, content, raw);
         }
-        catch {
-            // A grammar that will not load costs classification, not the match.
-            language = null;
+        catch (error) {
+            if (isWasmAbort(error))
+                throw error;
+            // Parsing failed on this file only. The matches are still real and
+            // still reported — just without node evidence.
+            classified = null;
+            state.uncovered.push({
+                file,
+                reason: `matched but could not be parsed for classification: ${error instanceof Error ? error.message : String(error)}`,
+            });
         }
-        if (language) {
-            const parser = newParser();
+        finally {
             try {
-                parser.setLanguage(language);
-                classified = classifyAgainstTree(parser, content, raw);
+                parser.delete();
             }
-            catch (error) {
-                if (isWasmAbort(error))
-                    throw error;
-                // Parsing failed on this file only. The matches are still real and
-                // still reported — just without node evidence.
-                classified = null;
-                uncovered.push({
-                    file,
-                    reason: `matched but could not be parsed for classification: ${error instanceof Error ? error.message : String(error)}`,
-                });
-            }
-            finally {
-                try {
-                    parser.delete();
-                }
-                catch {
-                    /* a dead module has nothing to reclaim */
-                }
+            catch {
+                /* a dead module has nothing to reclaim */
             }
         }
-        const starts = lineStarts(content);
-        raw.forEach((match, position) => {
-            const lineIndex = lineIndexFor(starts, match.startIndex);
-            const lineStart = starts[lineIndex];
-            const nextStart = starts[lineIndex + 1] ?? content.length + 1;
-            const node = classified?.[position] ?? null;
-            matches.push({
-                file,
-                line: lineIndex + 1,
-                column: match.startIndex - lineStart + 1,
-                startIndex: match.startIndex,
-                endIndex: match.endIndex,
-                lineText: content.slice(lineStart, Math.max(lineStart, nextStart - 1)).replace(/\r$/, ""),
-                matchedText: match.matchedText,
-                caseMatchesQuery: match.matchedText === term,
-                withinLargerWord: isWordCharacter(content[match.startIndex - 1]) ||
-                    isWordCharacter(content[match.endIndex]),
-                classification: node ? node.classification : classifyByFileType(file),
-                basis: node ? "parse-node" : language ? "none" : "file-type",
-                nodeType: node ? node.nodeType : null,
-                enclosingText: node ? node.enclosingText : null,
-            });
+    }
+    const starts = lineStarts(content);
+    for (const [position, match] of raw.entries()) {
+        if (state.matches.length >= MAX_TEXT_MATCHES) {
+            state.truncated = true;
+            return;
+        }
+        const lineIndex = lineIndexFor(starts, match.startIndex);
+        const lineStart = starts[lineIndex];
+        const nextStart = starts[lineIndex + 1] ?? content.length + 1;
+        const node = classified?.[position] ?? null;
+        state.matches.push({
+            file,
+            line: lineIndex + 1,
+            column: match.startIndex - lineStart + 1,
+            startIndex: match.startIndex,
+            endIndex: match.endIndex,
+            lineText: content.slice(lineStart, Math.max(lineStart, nextStart - 1)).replace(/\r$/, ""),
+            matchedText: match.matchedText,
+            caseMatchesQuery: match.matchedText === term,
+            withinLargerWord: isWordCharacter(content[match.startIndex - 1]) || isWordCharacter(content[match.endIndex]),
+            classification: node ? node.classification : classifyByFileType(file),
+            basis: node ? "parse-node" : language ? "none" : "file-type",
+            nodeType: node ? node.nodeType : null,
+            enclosingText: node ? node.enclosingText : null,
         });
     }
-    return { matches, uncovered, filesSearched, searched: true };
 }
-/**
- * Read a file for searching, or say why it could not be.
- *
- * Binary detection is a NUL-byte sniff over the head of the file rather than an
- * extension list: the extensions that matter here are open-ended, and a
- * misjudged binary read produces garbage matches rather than an honest skip.
- */
-function readSearchable(absolute) {
+export function readSearchable(absolute) {
     let buffer;
     try {
+        const stats = fs.statSync(absolute);
+        if (stats.size > MAX_SEARCHABLE_FILE_BYTES)
+            return {
+                reason: `too large to search: ${stats.size} bytes exceeds the ${MAX_SEARCHABLE_FILE_BYTES}-byte limit`,
+            };
         buffer = fs.readFileSync(absolute);
     }
     catch (error) {
@@ -264,8 +297,15 @@ function readSearchable(absolute) {
  * Every file that could not be searched is returned in `uncovered` (R5). A
  * rename that silently skipped files would leave a half-renamed repository
  * looking finished, which is the worst available outcome for this operation.
+ *
+ * Files are read and searched one at a time. Reading them all up front held the
+ * entire non-pruned working tree in memory at once, which on a tree carrying
+ * generated dumps or vendored data is gigabytes for a single call (KNODIN-24).
+ *
+ * `readFile` is injected only so a test can observe that reads interleave with
+ * searching rather than preceding it.
  */
-export async function searchRepoText(repoPath, term, loadLanguage, newParser, options = {}) {
+export async function searchRepoText(repoPath, term, loadLanguage, newParser, options = {}, readFile = readSearchable) {
     let candidates;
     try {
         // Checked explicitly because `walkRepoFiles` swallows a missing directory
@@ -291,19 +331,21 @@ export async function searchRepoText(repoPath, term, loadLanguage, newParser, op
             ],
             filesSearched: 0,
             searched: false,
+            truncated: false,
         };
     }
-    const readable = [];
-    const uncovered = [];
-    for (const file of candidates) {
-        const outcome = readSearchable(path.join(repoPath, file));
-        if ("reason" in outcome)
-            uncovered.push({ file, reason: outcome.reason });
-        else
-            readable.push({ file, content: outcome.content });
-    }
-    const result = await searchFiles(readable, term, loadLanguage, newParser, options);
+    const state = newSearchState();
     // Files skipped at read time and files that failed classification are both
     // gaps in the same claim, so they are reported through one list.
-    return { ...result, uncovered: [...uncovered, ...result.uncovered] };
+    for (const file of candidates) {
+        const outcome = readFile(path.join(repoPath, file));
+        if ("reason" in outcome) {
+            state.uncovered.push({ file, reason: outcome.reason });
+            continue;
+        }
+        await searchOneFile(state, file, outcome.content, term, loadLanguage, newParser, options);
+        if (state.truncated)
+            break;
+    }
+    return { ...state, searched: true };
 }

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:]')"

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/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

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.

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "knodin",
-	"version": "0.10.8",
+	"version": "0.11.0",
 	"knodin": {
-		"compatibility": "compatible"
+		"compatibility": "breaking"
 	},
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
@@ -63,6 +63,7 @@
 		"docs/releases/0.10.6.md",
 		"docs/releases/0.10.7.md",
 		"docs/releases/0.10.8.md",
+		"docs/releases/0.11.0.md",
 		"docs/releases/0.3.0.md",
 		"docs/releases/0.4.0.md",
 		"docs/releases/0.4.1.md",