knodin 0.10.7 → 0.11.0

package/dist/bin/cli.js

@@ -456,10 +456,17 @@ function formatStatusHuman(result) {
         ? result.missing.records[0]
         : (result.missing.files[0] ?? result.missing.records[0]);
     const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
-    const repairCommand = result.lifecycle?.status === "degraded" &&
-        result.missing.records.every((record) => result.lifecycle?.issues.includes(record))
-        ? "Run `knodin init`."
-        : "Run `knodin repair`.";
+    // A linked worktree with no database is the one case where `repair` is both
+    // the wrong first step and the expensive one: `init` seeds from an indexed
+    // sibling and reconciles only what differs, while `repair` builds from
+    // scratch. The engine has already worked out that this is that case, so
+    // defer to the step it wrote rather than recomputing the judgement here.
+    const worktreeStep = result.repairSteps?.find((step) => step.includes("per-worktree"));
+    const repairCommand = worktreeStep ??
+        (result.lifecycle?.status === "degraded" &&
+            result.missing.records.every((record) => result.lifecycle?.issues.includes(record))
+            ? "Run `knodin init`."
+            : "Run `knodin repair`.");
     return `Graph or lifecycle needs repair: ${outstanding} issue(s) found (${coverage}).${detail} ${repairCommand}\n${lifecycleLine}${integrationLine}`;
 }
 function humanLabel(key) {

package/dist/src/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/git-layout.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Git checkout-layout questions, kept out of the engine on purpose.
+ *
+ * `engine/index.ts` carries a pinned budget on direct `fs` reads
+ * (`sealed-reader-inventory.spec.ts`) because a sealed artifact answers with no
+ * working tree: a reader that touches the filesystem there gets ENOENT, which
+ * the nearest guard turns into `""` or `null`, and that reads downstream as
+ * "this symbol has no body" rather than "this was not covered".
+ *
+ * Git *metadata* is categorically outside that concern — a sealed artifact has
+ * no `.git` at all, and these functions are never on a source-content path — so
+ * routing them through the sealed resolver would add a branch that can never
+ * execute. Keeping them here says that in the layout rather than by spending
+ * budget the engine reserves for source reads, and it makes them directly
+ * unit-testable, which they are not as engine-private helpers.
+ */
+/**
+ * True only for a `git worktree add` checkout.
+ *
+ * A linked worktree's `.git` is a FILE pointing at an administrative directory
+ * under the main checkout, and that directory contains `commondir` naming the
+ * shared repository.
+ *
+ * The `.git` file alone is NOT sufficient and treating it as sufficient is a
+ * live bug: submodules and `--separate-git-dir` clones use one too, and neither
+ * has a main checkout whose graph could cover it, so per-worktree guidance would
+ * be actively wrong for them. `commondir` is the marker that actually
+ * distinguishes the case.
+ */
+export function isLinkedWorktree(repo) {
+    const marker = path.join(repo, ".git");
+    try {
+        // An ordinary checkout keeps a `.git` directory; `statSync` throws when
+        // there is no `.git` at all, which is an ordinary case — knodin indexes
+        // plain directories too.
+        if (!fs.statSync(marker).isFile())
+            return false;
+        const pointer = fs.readFileSync(marker, "utf8").trim();
+        const gitDir = /^gitdir:\s*(.+)$/m.exec(pointer)?.[1]?.trim();
+        if (!gitDir)
+            return false;
+        return fs.existsSync(path.join(path.resolve(repo, gitDir), "commondir"));
+    }
+    catch {
+        // Every read is inside the guard on purpose. This is best-effort detection
+        // reached from the missing-database remediation path, and that path has to
+        // answer: an unreadable `.git`, or one that disappears between the stat and
+        // the read, must degrade to "not a worktree" rather than crash `status`.
+        return false;
+    }
+}

package/dist/src/engine/index.js

@@ -32,6 +32,7 @@ import { allocateCandidate, assertCandidate, discardCandidateFiles, listCandidat
 import { computeSimilarity, generateEmbedding, generateEmbeddings, } from "./embeddings.js";
 import { walkRepoFiles } from "./file-walker.js";
 import { clearGitHistorySignalCache, collectGitHistorySignals, } from "./git-history.js";
+import { isLinkedWorktree } from "./git-layout.js";
 // Runtime import, but not a cycle: parse-pool imports only TYPES from here,
 // which erase at compile time. parse-worker's runtime import of this module
 // resolves inside the worker thread, never in this one.
@@ -13083,6 +13084,11 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     verification: { mode: "deep-audit", verifiedAt },
                     freshnessMechanism: freshnessMechanismFor(resolved, openPolicy),
                     repairSteps: [
+                        ...(isLinkedWorktree(resolved)
+                            ? [
+                                "Run `knodin init` here: graphs are per-worktree and this one has none of its own, so the main checkout's graph does not cover it. `init` seeds from an indexed sibling worktree where one exists rather than rebuilding from scratch.",
+                            ]
+                            : []),
                         "Run `knodin repair` to create the local index.",
                         "Run `knodin status` again to verify health.",
                     ],

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