knodin 0.10.4 → 0.10.6

package/dist/bin/cli.js

@@ -174,7 +174,13 @@ function formatIndexHuman(result) {
 function formatIndexVerificationError(result) {
     const firstIssue = result.verification.missing.files[0] ?? result.verification.missing.records[0];
     const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
-    return `knodin index: requested work completed, but ${result.verification.issueCount.toLocaleString()} graph issue(s) remain.${detail} Run \`knodin repair\`.\n`;
+    // Describes whichever condition actually gated. Printing the issue count
+    // unconditionally produced "0 graph issue(s) remain" as a failure reason —
+    // a sentence that reports no problem and then recommends repair (KNODIN-7).
+    const condition = result.verification.issueCount > 0
+        ? `${result.verification.issueCount.toLocaleString()} graph issue(s) remain`
+        : `graph verification reported status "${result.verification.status}"`;
+    return `knodin index: requested work completed, but ${condition}.${detail} Run \`knodin repair\`.\n`;
 }
 /**
  * The hooks/lifecycle line of `status`.
@@ -395,7 +401,13 @@ function formatStatusHuman(result) {
     const semanticNote = result.semanticReadiness && result.semanticReadiness !== "ready"
         ? ` Semantic search coverage is ${result.semanticReadiness}: \`search\` will under-return until embedding completes (\`knodin index\`).`
         : "";
-    const coverage = `${result.coverage.sourceFiles} source files, ${result.coverage.indexedFiles} indexed files, ${result.coverage.filesWithSymbols} files with symbols${formatCoverageGaps(result.coverage.skipped)}${mirrorNote}${semanticNote}`;
+    // `countsUnknown` means the graph could not be read, so these are placeholders
+    // rather than measurements. Printing "0 indexed files" makes an absent graph
+    // indistinguishable from a fully destroyed one.
+    const indexedCounts = result.coverage.countsUnknown
+        ? "indexed and symbol counts unknown; the graph could not be read"
+        : `${result.coverage.indexedFiles} indexed files, ${result.coverage.filesWithSymbols} files with symbols`;
+    const coverage = `${result.coverage.sourceFiles} source files, ${indexedCounts}${formatCoverageGaps(result.coverage.skipped)}${mirrorNote}${semanticNote}`;
     if (result.status === "indexing" && result.activity) {
         const count = result.activity.phaseTotal === undefined
             ? ""
@@ -431,8 +443,18 @@ function formatStatusHuman(result) {
         return `Graph content is intact but evidence is stale (${coverage}).${result.verification.mode === "persisted-audit"
             ? ` Cached deep-audit evidence is from ${result.verification.auditVerifiedAt ?? "an earlier run"}; freshness was probed ${result.verification.verifiedAt ?? "now"}. Run \`knodin status --deep\` for an exact current audit.`
             : ""}\n${freshnessLine}${lifecycleLine}${integrationLine}Run \`knodin wait --fresh\` or issue a graph query to reconcile bounded drift.\n`;
-    const outstanding = result.missing.files.length + result.missing.records.length;
-    const firstIssue = result.missing.files[0] ?? result.missing.records[0];
+    // When the graph could not be read, every source file lands in `missing.files`
+    // because none of them are indexed. That is ONE structural problem, not one
+    // per file: a 94-file repository with no database reported "95 issue(s)" and
+    // led with an arbitrary source filename, so an absent graph read as damage
+    // proportional to repository size. `missing.files` still carries the repair
+    // worklist — only the count and the headline shown to a human change here.
+    const outstanding = result.coverage.countsUnknown
+        ? result.missing.records.length
+        : result.missing.files.length + result.missing.records.length;
+    const firstIssue = result.coverage.countsUnknown
+        ? 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))
@@ -2256,11 +2278,39 @@ async function main() {
             result = indexResult;
             const indexedCheck = checkIndexed([...indexResult.indexed, ...indexResult.unchanged], plan.repo);
             if (!indexedCheck.ok) {
+                // Same obligation as the verification gate below: `--json` must mean
+                // parseable output on every exit path, and this one wrote zero bytes
+                // to stdout and a bare sentence to stderr (KNODIN-5).
+                if (jsonOutput)
+                    process.stdout.write(`${JSON.stringify({
+                        available: false,
+                        status: "unavailable",
+                        state: "unknown",
+                        error: indexedCheck.error,
+                    })}\n`);
                 process.stderr.write(`${indexedCheck.error}\n`);
                 await engine.close();
                 process.exit(1);
             }
-            if (indexResult.verification.status !== "healthy") {
+            // Gated on damage, not on `status !== "healthy"`. That older condition
+            // rejected `stale`, and a freshly promoted graph is routinely stale
+            // because freshness has not been probed since the index wrote — so the
+            // FIRST clean index of any repository exited 1 while its own progress
+            // output said "Promoted graph has 0 issue(s)" and its error said "0
+            // graph issue(s) remain. Run `knodin repair`", recommending repair for
+            // a graph it had just verified as undamaged (KNODIN-7).
+            //
+            // `repair-needed` and a non-zero issue count keep every real failure.
+            // Staleness is a freshness fact that `status` reports and ordinary use
+            // reconciles; it is not a verification result, and treating it as one
+            // made a new repository's first command fail for doing nothing wrong.
+            if (indexResult.verification.status === "repair-needed" ||
+                indexResult.verification.issueCount > 0) {
+                // Emitted before exiting so `--json` is not silently empty on this
+                // path: it previously wrote zero bytes to stdout and a human
+                // sentence to stderr, which is the same defect as KNODIN-5.
+                if (jsonOutput)
+                    process.stdout.write(`${JSON.stringify(indexResult)}\n`);
                 process.stderr.write(formatIndexVerificationError(indexResult));
                 await engine.close();
                 process.exit(1);
@@ -2484,14 +2534,38 @@ async function main() {
                 stripEmbeddings: !rest.includes("--keep-embeddings"),
                 includeExcluded: rest.includes("--include-excluded"),
             });
+            // `ok: false` and exit 0 are contradictory claims from one command, and
+            // the exit code is what every shell idiom reads. `knodin seal --output X
+            // && upload X` ran the upload after a refusal (KNODIN-4).
+            //
+            // seal already fails closed on content — it writes no file when it
+            // refuses — so this closes the last gap rather than papering over one.
+            if (result.ok === false)
+                process.exitCode = 1;
             break;
         }
         case "sealed": {
-            if (!rest[0])
+            // Positionals are extracted rather than read off `rest` by index.
+            // `rest[1]` took whatever token followed the artifact, so
+            // `sealed <artifact> --tokens 200` explained a symbol literally named
+            // "--tokens" — and at that budget the fabricated empty explain block
+            // evicted commit, ref and sealedAt, which are the fields an
+            // inspect-only call exists to return (KNODIN-3).
+            //
+            // `extractPositionals` already knows which flags consume the token
+            // after them, so `200` is not mistaken for a symbol either.
+            const positionals = extractPositionals(rest);
+            if (!positionals[0])
                 throw new Error("knodin sealed requires an artifact path");
-            result = await runSealedQuery(rest[0], rest[1], {
+            result = await runSealedQuery(positionals[0], positionals[1], {
                 strictCompat: rest.includes("--strict-compat"),
             });
+            // Same contradiction as `seal`, found while testing the fix for it:
+            // `sealed <missing-artifact>` reported ok: false and exited 0, so a
+            // caller checking $? saw success (KNODIN-4 R2 — audit the other
+            // commands emitting an `ok` field).
+            if (result.ok === false)
+                process.exitCode = 1;
             break;
         }
         case "pack": {
@@ -3038,7 +3112,32 @@ catch (err) {
             error: err,
         });
         const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
-        console.error(`${describeThrown(err)}${correlation}`);
+        const message = describeThrown(err);
+        // `--json` has to mean parseable output on EVERY exit path, not only the
+        // successful one. A bare string here makes a consumer's parser throw a
+        // decode error, which gets triaged as a malformed response or a version
+        // mismatch — while the string it failed to parse already named the cause
+        // (KNODIN-5, found as "attempt to write a readonly database" from
+        // `knodin --json sealed` against a read-only artifact).
+        //
+        // Shaped like the unavailability envelope the graph-backed paths already
+        // return for the same class of condition, so a caller can handle both
+        // surfaces with one branch. Written to stdout because that is where a
+        // caller reading `--json` is looking; the human path keeps stderr.
+        // The envelope is ADDITIONAL, not a replacement. stdout is the JSON
+        // channel and stderr is the human one, so writing the envelope instead of
+        // the message silently emptied stderr for every existing caller that reads
+        // diagnostics there — `configure --json` asserts its refusal on stderr, and
+        // it went blank.
+        if (argv.includes("--json"))
+            process.stdout.write(`${JSON.stringify({
+                available: false,
+                status: "unavailable",
+                state: "unknown",
+                error: message,
+                ...(diagnostic.recorded ? { diagnosticId: diagnostic.correlationId } : {}),
+            })}\n`);
+        console.error(`${message}${correlation}`);
         process.exit(1);
     }
 }

package/dist/src/diagnostics.js

@@ -528,8 +528,19 @@ function scrubText(raw, repo) {
     };
     for (const exact of [repo, os.homedir()].filter(Boolean).sort((a, b) => b.length - a.length))
         replace(new RegExp(exact.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`), "g"), "<path>");
-    replace(/\b(?:ghp|github_pat|sk|xox[baprs])-[-A-Za-z0-9_]{10,}\b/g, "<secret>");
-    replace(/\b(?:password|passwd|token|secret|api[_-]?key|authorization)\s*[=:]\s*[^\s,;]+/gi, "$1=<secret>");
+    // Either separator. GitHub issues its tokens with an UNDERSCORE after the
+    // prefix, so a hyphen-only pattern matched a shape GitHub never mints and
+    // missed every shape it does — a real token in an error message survived
+    // scrubbing and reached the bundle a user shares (KNODIN-10). Slack and
+    // OpenAI really do use a hyphen, so both separators must be accepted.
+    replace(/\b(?:ghp|github_pat|sk|xox[baprs])[-_][-A-Za-z0-9_]{10,}\b/g, "<secret>");
+    // The value pattern stops at whitespace, so `authorization: Bearer <token>`
+    // used to match only the word "Bearer" and leave the credential in place —
+    // the standard header form leaked the one thing worth redacting (KNODIN-10).
+    // An optional scheme is consumed first so the credential after it is the
+    // part that gets replaced. Only known schemes are skipped, so an ordinary
+    // `password=x next word` still redacts one value rather than eating prose.
+    replace(/\b(?:password|passwd|token|secret|api[_-]?key|authorization)\s*[=:]\s*(?:(?:bearer|basic|digest|token)\s+)?[^\s,;]+/gi, "<secret>");
     replace(/\b[A-Z]:\\(?:[^\s<>:"|?*]+\\)*[^\s<>:"|?*]*/g, "<path>");
     replace(/(?:^|[\s('"`])\/(?:[^\s)'"`]+\/)*[^\s)'"`]*/g, "<path>");
     replace(/\b(?:[A-Za-z0-9_.-]+\/)+(?:[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,12})\b/g, "<path>");

package/dist/src/engine/candidate-database.js

@@ -1,6 +1,8 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { isSealedDatabase } from "./seal.js";
+import { Database } from "./sqlite.js";
 import { resolveDbPath, resolveStateDir } from "./state-paths.js";
 const PROMOTION_SCHEMA_VERSION = 1;
 const CANDIDATES_DIRECTORY = "candidates";
@@ -166,6 +168,29 @@ export function recoverInterruptedPromotion(repo) {
     fsyncDirectory(path.dirname(marker));
     return outcome;
 }
+/**
+ * Whether the database currently at the active path carries embedded source.
+ *
+ * An active database that cannot be opened reports false ON PURPOSE. Replacing
+ * a damaged graph is exactly what promotion exists to do, and a graph too
+ * corrupt to open is the ordinary case for that — refusing here would break
+ * repair for the situation it is most needed in. The trade is deliberate: a
+ * sealed artifact that is ALSO unreadable can still be replaced, but such an
+ * artifact is already unrecoverable.
+ */
+function activeDatabaseIsSealed(activePath) {
+    let db = null;
+    try {
+        db = new Database(activePath, { readonly: true });
+        return isSealedDatabase(db);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        db?.close();
+    }
+}
 /** Same-filesystem, marker-backed promotion. Caller must close and audit both databases first. */
 export function promoteCandidateFile(repo, candidate) {
     assertCandidate(repo, candidate);
@@ -176,6 +201,18 @@ export function promoteCandidateFile(repo, candidate) {
     for (const suffix of ["-wal", "-shm"])
         if (fs.existsSync(`${candidate.databasePath}${suffix}`))
             throw new Error("candidate database has uncheckpointed sidecar files");
+    // Promotion REPLACES the active database. When that file is a sealed
+    // artifact, replacing it destroys the only copy of the source embedded in
+    // it. `repair` reaches here with a candidate built from the working tree,
+    // so an artifact sitting at the active path was emptied by a command whose
+    // entire purpose is to make a graph healthier (KNODIN-9).
+    //
+    // This is the chokepoint rather than a guard inside `repair`, because every
+    // promotion has the same consequence regardless of which caller arrives.
+    // An ordinary working graph is never sealed, so normal promotion and repair
+    // are unaffected.
+    if (fs.existsSync(activePath) && activeDatabaseIsSealed(activePath))
+        throw new Error("active database is a sealed artifact; promotion would replace it");
     fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
     fsyncFile(candidate.databasePath);
     const backupPath = path.join(stateDir, `db.sqlite.backup.${Date.now()}.${crypto.randomUUID().slice(0, 8)}`);
@@ -200,6 +237,30 @@ export function promoteCandidateFile(repo, candidate) {
         fsyncDirectory(stateDir);
         fs.rmSync(marker, { force: true });
         fsyncDirectory(stateDir);
+        // The rename above moves the database out and nothing else, and the
+        // candidate directory is NOT empty at this point: the clean-index audit
+        // writes `status-audit-v1.json` beside the candidate database. So every
+        // SUCCESSFUL promotion left a directory behind — and `listCandidates`
+        // skips directories without a database, so the only cleanup path could
+        // never see them (KNODIN-2). Twelve had accumulated in this repository
+        // since 11 Aug and thirty in a reporting checkout, where they were
+        // reasonably read as promotions that had failed.
+        //
+        // Removed after the marker, so an interruption before this point still
+        // recovers through the marker rather than losing a candidate it needed.
+        //
+        // Swallowed rather than left to the enclosing `catch`: the promotion is
+        // already committed here — the marker is gone and the new database is
+        // fsynced into place — so a failure to delete leftover residue (a locked
+        // file, EPERM on a read-only parent) must not reach the rollback below,
+        // which would move the just-promoted database back into the candidate
+        // directory and restore the old graph over a promotion that succeeded.
+        try {
+            fs.rmSync(path.dirname(candidate.databasePath), { recursive: true, force: true });
+        }
+        catch {
+            // Residue only. `sweepAbandonedCandidates` collects it on the next run.
+        }
         return fs.existsSync(backupPath) ? backupPath : null;
     }
     catch (error) {
@@ -214,6 +275,50 @@ export function promoteCandidateFile(repo, candidate) {
         throw error;
     }
 }
+/**
+ * Remove candidate directories that hold no database, and report how many.
+ *
+ * `listCandidates` deliberately answers "what could be resumed", so it skips a
+ * directory with no `db.sqlite`. Cleanup used to run only over that list, which
+ * meant the one kind of directory guaranteed to have no database — the residue a
+ * successful promotion leaves once the database is renamed out — was the one
+ * kind nothing could ever delete (KNODIN-2).
+ *
+ * Promotion now removes its own directory, so this exists for two other cases:
+ * residue already accumulated by earlier versions, and directories left by a
+ * process that died between `allocateCandidate` and writing a database.
+ *
+ * Returns the count rather than nothing so callers can say what they swept
+ * instead of tidying up silently.
+ */
+export function sweepAbandonedCandidates(repo) {
+    const resolvedRepo = path.resolve(repo);
+    const root = candidateRoot(resolvedRepo);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith("candidate-"))
+            continue;
+        const directory = path.join(root, entry.name);
+        if (fs.existsSync(path.join(directory, "db.sqlite")))
+            continue;
+        try {
+            fs.rmSync(directory, { recursive: true, force: true });
+            removed++;
+        }
+        catch {
+            // Best effort. Failing to remove residue must not stop the caller's
+            // actual work, which is what this is being cleaned up alongside.
+        }
+    }
+    return removed;
+}
 export function discardCandidateFiles(repo, candidate) {
     assertCandidate(repo, candidate);
     fs.rmSync(path.dirname(candidate.databasePath), { recursive: true, force: true });

package/dist/src/engine/index.js

@@ -28,7 +28,7 @@ import { contentFingerprint, writeStructuralSnapshot, } from "../structural-snap
 import { acquireLifecycleCoordination } from "../update-coordination.js";
 import { KNODIN_VERSION } from "../version.js";
 import * as ann from "./ann-hnsw.js";
-import { allocateCandidate, assertCandidate, discardCandidateFiles, listCandidates, promoteCandidateFile, recoverInterruptedPromotion, } from "./candidate-database.js";
+import { allocateCandidate, assertCandidate, discardCandidateFiles, listCandidates, promoteCandidateFile, recoverInterruptedPromotion, sweepAbandonedCandidates, } from "./candidate-database.js";
 import { computeSimilarity, generateEmbedding, generateEmbeddings, } from "./embeddings.js";
 import { walkRepoFiles } from "./file-walker.js";
 import { clearGitHistorySignalCache, collectGitHistorySignals, } from "./git-history.js";
@@ -41,7 +41,7 @@ import { isIndexablePath, makeWatchIgnorePredicate } from "./prune.js";
 import { reflinkCopyFile } from "./reflink-copy.js";
 import { readSarifLog, SARIF_DEFAULT_LIMITS, } from "./sarif-import.js";
 import { readScipIndex, SCIP_DEFAULT_LIMITS, } from "./scip-import.js";
-import { listSealedFiles, readSealedSource } from "./seal.js";
+import { isSealedDatabase, listSealedFiles, readSealedSource } from "./seal.js";
 import { isIndexableSourcePath } from "./source-policy.js";
 import { Database } from "./sqlite.js";
 import { lookupMirror, mayWriteToRepository, resolveDbPath, resolveStateDir, } from "./state-paths.js";
@@ -7273,6 +7273,12 @@ function sumCounts(counts) {
  */
 function findResumableCandidate(repoPath) {
     const head = gitHead(repoPath) ?? "";
+    // Swept first, because the loop below can only discard what `listCandidates`
+    // returns and that deliberately excludes database-less directories — which is
+    // exactly what a promoted candidate leaves behind (KNODIN-2). Without this,
+    // the comment above about not accumulating abandoned copies was false for the
+    // most common case.
+    sweepAbandonedCandidates(repoPath);
     let resumable = null;
     for (const candidate of listCandidates(repoPath)) {
         let usable = false;
@@ -7683,8 +7689,54 @@ function recordIndexState(db, repoPath, relPath) {
         return 0;
     }
 }
+/**
+ * Whether this database is a sealed artifact — one carrying its own source.
+ *
+ * Decided from the seal attestation, which is what `seal` writes to declare an
+ * artifact sealed, rather than from a row count in `sealed_file`: an artifact of
+ * a repository that indexed no files carries no `sealed_file` rows and is still
+ * sealed, and a count answers "does it embed source for anything" instead of
+ * "is this an artifact".
+ *
+ * Cached per database: this is asked once per file during reconciliation, and
+ * the answer cannot change for the life of a connection.
+ */
+const sealedArtifactDatabases = new WeakMap();
+function databaseIsSealedArtifact(db) {
+    const known = sealedArtifactDatabases.get(db);
+    if (known !== undefined)
+        return known;
+    // `isSealedDatabase` returns false for an ordinary working graph, including
+    // one with no `meta` table at all, so no extra guard is needed here.
+    const sealed = isSealedDatabase(db);
+    sealedArtifactDatabases.set(db, sealed);
+    return sealed;
+}
+/**
+ * Whether a file missing from disk should be purged from this graph.
+ *
+ * For a working checkout, purging is right — the file really was deleted. For an
+ * artifact whose source was materialized from `sealed_source`, a missing file
+ * means the extraction was incomplete, not that the repository changed, and
+ * purging silently rewrote the graph to match a truncated tree: 858 index_state
+ * rows fell to 627 on one query while `sealed_file` still claimed 858, leaving
+ * the artifact contradicting itself and answering confidently from the smaller
+ * graph (KNODIN-6).
+ *
+ * Keeping every file-owned row makes the discrepancy visible instead: health
+ * reports the file as indexed-but-missing, which is the truth, and a symbol
+ * query against it can be told apart from a symbol that genuinely has no
+ * callers. Guarding only the `index_state` row would be worse than not guarding
+ * at all — the symbols, references and dependencies would still be gone, and
+ * `index_state` would then claim coverage the graph no longer has.
+ */
+function shouldPurgeMissingFile(db) {
+    return !databaseIsSealedArtifact(db);
+}
 /** Drop a file's `index_state` row (used when a file is deleted). */
 function removeIndexState(db, relPath) {
+    if (!shouldPurgeMissingFile(db))
+        return;
     try {
         db.run("DELETE FROM index_state WHERE filePath = ?", [relPath]);
     }
@@ -7854,7 +7906,7 @@ async function reconcileIndex(repoPath, db, progress, skipEmbeddings = false) {
                     reindexedPaths.push(rel);
                 }
             }
-            else {
+            else if (shouldPurgeMissingFile(db)) {
                 // Deletion or source-policy retirement — purge every file-owned row.
                 db.run("BEGIN TRANSACTION;");
                 try {
@@ -8524,6 +8576,8 @@ function startFileWatcher(repoPath, db, watcherFileLimit = MAX_RECURSIVE_WATCH_F
     };
     watchQueues.set(resolvedRepoPath, queue);
     const purgeFile = (relativePath) => {
+        if (!shouldPurgeMissingFile(db))
+            return;
         db.run("BEGIN TRANSACTION;");
         try {
             deleteSymbolsForFile(db, relativePath);
@@ -8806,6 +8860,16 @@ export async function getOrInitDb(repoPath, options = {}) {
             // Runs after the CREATE TABLEs below, since the table must exist.
             const needsOrphanPurge = storedVersion < KNODIN_SCHEMA_VERSION;
             const needsEmbeddingRepresentationRefresh = storedVersion >= 22 && storedVersion < 23;
+            // An artifact sealed by an older build carries that build's schema
+            // version, so a newer knodin opening it for write lands here and drops
+            // every table below — including the embedded source, which no working
+            // tree can supply again. Today's artifacts report the current version
+            // and never reach it; one from a single release ago would.
+            //
+            // Refuse rather than skip: skipping would leave the caller holding a
+            // database it believes is writable and current, and it is neither.
+            if (storedVersion < LAST_REBUILD_SCHEMA_VERSION && isSealedDatabase(db))
+                throw new Error("refusing to rebuild the schema of a sealed artifact: it would drop the embedded source, which is the only copy");
             if (storedVersion < LAST_REBUILD_SCHEMA_VERSION) {
                 db.run("DROP TRIGGER IF EXISTS after_symbol_insert;");
                 db.run("DROP TRIGGER IF EXISTS after_symbol_delete;");
@@ -11901,7 +11965,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     await indexFile(absolute, file, resolved, db);
                     recordIndexState(db, resolved, file);
                 }
-                else {
+                else if (shouldPurgeMissingFile(db)) {
                     db.run("BEGIN TRANSACTION;");
                     try {
                         deleteSymbolsForFile(db, file);
@@ -12887,6 +12951,9 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 let indexedFiles = 0;
                 let filesWithSymbols = 0;
                 let lastSuccessfulReconciliation = null;
+                // No database, or counters that threw, means the zeros below were
+                // never measured.
+                let countsUnknown = !db;
                 if (db) {
                     try {
                         schemaVersion =
@@ -12903,7 +12970,10 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                     }
                     catch {
                         // A schema migration can briefly make counters unavailable;
-                        // the live operation remains the authoritative status.
+                        // the live operation remains the authoritative status. Whatever
+                        // was read before the throw is partial, so report the counts as
+                        // unknown rather than presenting a half-filled tally as measured.
+                        countsUnknown = true;
                     }
                     if (!activeDb)
                         db.close();
@@ -12926,6 +12996,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                             ? Math.round((Math.min(indexedFiles, sourceFiles.length) / sourceFiles.length) * 10000) / 100
                             : 100,
                         skipped,
+                        ...(countsUnknown ? { countsUnknown: true } : {}),
                     },
                     orphaned: { embeddings: 0, references: 0, dependencies: 0 },
                     missing: { files: [], records: [] },
@@ -12957,6 +13028,8 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         filesWithSymbols: 0,
                         percent: sourceFiles.length ? 0 : 100,
                         skipped: buildCoverageSkips(collected.skippedByExtension, null),
+                        // There is no database to count, so these are placeholders.
+                        countsUnknown: true,
                     },
                     orphaned: { embeddings: 0, references: 0, dependencies: 0 },
                     missing: {
@@ -13129,6 +13202,9 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         filesWithSymbols: 0,
                         percent: sourceFiles.length ? 0 : 100,
                         skipped: coverageSkips,
+                        // The schema is not one this build can read, so index_state is
+                        // not counted here even though rows may well exist.
+                        countsUnknown: true,
                     },
                     orphaned: { embeddings: 0, references: 0, dependencies: 0 },
                     missing: { files: sourceFiles, records: schemaProblems },
@@ -13477,7 +13553,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         else
                             counts.indexed++;
                     }
-                    else {
+                    else if (shouldPurgeMissingFile(db)) {
                         db.run("BEGIN TRANSACTION;");
                         try {
                             deleteSymbolsForFile(db, file);
@@ -13493,6 +13569,17 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                         }
                         counts.removed++;
                     }
+                    else {
+                        // A sealed artifact's rows ARE the artifact: it has no working
+                        // tree, so "this file is missing" is its normal condition rather
+                        // than drift to clean up (KNODIN-9).
+                        //
+                        // This was the sixth purge site and the only unguarded one.
+                        // `removeIndexState` above carries its own guard, which is why
+                        // the damage looked so strange: index_state survived while the
+                        // symbols, references and dependencies around it were deleted.
+                        counts.skipped++;
+                    }
                     committedWork = true;
                     setMeta(db, "repairPostprocessingPending", "1");
                     completedFiles = fileIndex + 1;
@@ -13866,7 +13953,7 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                                 await indexFile(absPath, relativePath, repoPath, db);
                                 recordIndexState(db, repoPath, relativePath);
                             }
-                            else {
+                            else if (shouldPurgeMissingFile(db)) {
                                 // File was deleted
                                 db.run("BEGIN TRANSACTION;");
                                 try {

package/dist/src/failure-diagnosis.js

@@ -26,7 +26,13 @@ const CODE_EXTENSIONS = [
     ".cpp",
     ".h",
     ".hpp",
-];
+    // Longest first. `referenceAt` takes the FIRST extension that matches at a
+    // cursor, so a shorter extension listed earlier wins and truncates the path:
+    // `src/main.cpp:3:4` parsed as `src/main.c` with no line, pointing diagnosis
+    // at a file that does not exist. `.tsx` only worked because it happened to
+    // precede `.ts`. Sorting makes longest-match the rule rather than an
+    // accident of list order.
+].sort((left, right) => right.length - left.length);
 const MAX_ANALYSIS_BYTES = 4 * 1024 * 1024;
 const MAX_SOURCE_FILE_BYTES = 1024 * 1024;
 const MAX_MANIFEST_BYTES = 256 * 1024;

package/dist/src/init.js

@@ -20,7 +20,14 @@ export class InitializationHealthError extends Error {
     constructor(indexResult) {
         const firstIssue = indexResult.verification.missing.files[0] ?? indexResult.verification.missing.records[0];
         const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
-        super(`knodin init: lifecycle hooks were installed, but ${indexResult.verification.issueCount.toLocaleString()} graph issue(s) remain.${detail} Run \`knodin repair\`.`);
+        // Describes whichever condition actually gated, for the same reason
+        // `formatIndexVerificationError` does: printing the issue count
+        // unconditionally produced "0 graph issue(s) remain" as a failure reason —
+        // a sentence that reports no problem and then recommends repair (KNODIN-7).
+        const condition = indexResult.verification.issueCount > 0
+            ? `${indexResult.verification.issueCount.toLocaleString()} graph issue(s) remain`
+            : `graph verification reported status "${indexResult.verification.status}"`;
+        super(`knodin init: lifecycle hooks were installed, but ${condition}.${detail} Run \`knodin repair\`.`);
         this.name = "InitializationHealthError";
         this.indexResult = indexResult;
     }
@@ -1385,9 +1392,16 @@ export async function initializeRepository(repo, options) {
             // Only a full index has verified the whole graph, so only a full index
             // may fail the run on graph health. A configuration-scoped pass saw a
             // handful of files and knows nothing about the rest.
+            // Gated on damage, not on `status !== "healthy"` — the same correction
+            // `knodin index` needed (KNODIN-7). A freshly written graph is routinely
+            // `stale` because freshness has not been probed since the index wrote,
+            // and an untracked file makes that the normal outcome, so the old
+            // condition failed `knodin init` on the very first run in a new
+            // repository while its own verification had found nothing wrong.
             if (!scopedIndexPaths &&
                 isIndexResult(indexResult) &&
-                indexResult.verification.status !== "healthy") {
+                (indexResult.verification.status === "repair-needed" ||
+                    indexResult.verification.issueCount > 0)) {
                 throw new InitializationHealthError(indexResult);
             }
         }

package/docs/releases/0.10.5.md

@@ -0,0 +1,172 @@
+# knodin 0.10.5
+
+Six fixes, all found by treating knodin's own artifacts as something another
+program has to consume. A verifier team spent a day characterizing sealed
+artifacts and the `--repo` query path; every defect below came out of measuring
+state before and after an operation rather than reading the code.
+
+The theme is the one 0.10.2 through 0.10.4 have been working on: **a result that
+looks complete while quietly being wrong**, and a command that reports success it
+has not earned.
+
+## Candidate directories no longer accumulate
+
+A checkout had thirty candidate directories under `.knodin/candidates/` going
+back weeks, none promoted, while `knodin repair` exited 0. It read as clean
+indexes silently failing to promote. This repository had twelve of its own.
+
+**They were the residue of successful promotions, not failures.** Three facts
+composed:
+
+- Promotion renames the database out and leaves the directory.
+- The directory is not empty: the clean-index audit writes
+  `status-audit-v1.json` beside the candidate database, so something always
+  remains after the database leaves.
+- `listCandidates` skips directories without a database — correctly, since it
+  answers "what can be resumed" — and it is the only input to the sole cleanup
+  path. So the one kind of directory guaranteed to have no database was the one
+  kind nothing could ever delete.
+
+Promotion now removes its own directory, and a sweep clears residue left by
+earlier versions and by processes that died before writing a database. A
+resumable candidate — one that still holds a database — is untouched, so
+0.10.3's resumable clean index is unaffected.
+
+If you have accumulated directories, the next clean index removes them.
+
+## `seal` and `sealed` exit non-zero when they refuse
+
+Both reported `ok: false` and exited **0**. The exit code carried no
+information at all:
+
+```
+$ knodin seal --output artifact.sqlite     # in a directory with no index
+seal:
+  ok: false
+  code: database-missing
+$ echo $?
+0
+```
+
+So `knodin seal --output X && upload X` ran the upload after a refusal. `sealed`
+had the same contradiction on a missing artifact.
+
+Both now exit non-zero when they report `ok: false`. Worth stating what was
+already right: `seal` fails closed on content — it writes no file when it
+refuses, so nothing broken was ever shipped by this. The failure simply arrived
+one step late and attributed to the wrong command.
+
+## `--json` produces JSON on failure, not a bare string
+
+`knodin --json sealed <artifact> <symbol>` against a read-only artifact printed:
+
+```
+attempt to write a readonly database
+```
+
+Not JSON. A consumer's parser throws a decode error, which gets triaged as a
+malformed response or a version mismatch — while the string it failed to parse
+already named the cause.
+
+Thrown failures under `--json` now emit an envelope shaped like the one the
+graph-backed paths already return for the same class of condition, so a caller
+can handle both surfaces with one branch:
+
+```json
+{"available": false, "status": "unavailable", "state": "unknown",
+ "error": "attempt to write a readonly database"}
+```
+
+Without `--json` the human message on stderr is unchanged.
+
+## `sealed` no longer mistakes a flag for a symbol
+
+`knodin sealed <artifact> --tokens 200` explained a symbol literally named
+`--tokens`, because the symbol was read positionally as "whatever followed the
+artifact". Under a tight budget the fabricated empty explain block then evicted
+`commit`, `ref` and `sealedAt` — the fields an inspect-only call exists to
+return.
+
+Arguments are now extracted with the shared parser, which already knows which
+flags consume the token after them, so neither `--tokens` nor its value `200` is
+taken as a symbol.
+
+## A sealed artifact is no longer silently rewritten to match a truncated tree
+
+The sharpest finding. A sealed artifact can be materialized — its embedded
+source extracted next to it — and queried through `--repo`. If that extraction
+is incomplete, knodin reconciled the graph to match:
+
+```
+index_state:  858 → 627     persisted to disk
+symbols:     5358 → 4791    567 symbols destroyed
+sealed_file:  858 → 858     the artifact's own file list, untouched
+```
+
+The artifact ends up **contradicting itself** and still answering confidently.
+Querying a symbol that lived only in the missing files returned exit 0, an empty
+result and a null identity — indistinguishable from a symbol that genuinely has
+no callers. A file truncated mid-content behaved identically.
+
+For a working checkout, pruning rows for deleted files is right: the files really
+were deleted. For an artifact carrying its own source, a missing file means the
+extraction was incomplete, not that the repository changed.
+
+Every file-owned row — `index_state`, symbols, references, dependencies — is now
+preserved on a database carrying a seal attestation. Health reports those files
+as indexed-but-missing, which is the truth, instead of quietly forgetting them.
+
+Preserving `index_state` alone would have been worse than preserving nothing: the
+567 symbols in the table above would still have been destroyed, and `index_state`
+would then have claimed coverage the graph no longer had.
+
+## The first clean index of a repository no longer fails
+
+Found while building a test fixture for the fix above, and it affects every new
+checkout. With any untracked file present, the **first** `knodin index --clean`
+exited 1 — after its own progress output said the work succeeded:
+
+```
+[index:verifying] Promoted graph has 0 issue(s)
+[index:completed] Clean index completed
+knodin index: requested work completed, but 0 graph issue(s) remain. Run `knodin repair`.
+```
+
+Zero issues, and a failure — recommending repair for a graph it had just
+verified as undamaged. The second run exited 0, so the first run's work had been
+fine all along.
+
+The gate read `status !== "healthy"` while the message printed an issue count.
+An untracked file makes freshness `stale-working-tree` and verification `stale`,
+so a correct index was rejected for a fact about the working tree.
+
+Failure is now gated on damage — `repair-needed`, or a non-zero issue count — and
+the message names whichever condition actually gated instead of printing a count
+that contradicts it. `--json` also emits the result on this path, which
+previously wrote zero bytes to stdout.
+
+`knodin init` carried the identical gate and the identical message, and it is the
+first command anyone runs in a new repository — so it is corrected the same way.
+
+Anything running `knodin init` or `knodin index --clean && …` on a fresh checkout
+was failing on the first run, every time.
+
+## Known, not fixed here
+
+- **Querying through `--repo` still writes to the database**, so a read-only
+  mount cannot be used. It fails loudly — `attempt to write a readonly database`
+  — rather than silently. `sealed` does not mutate the artifact at all, but still
+  requires a writable file for symbol queries.
+- **Sealing the same commit twice produces different bytes**; `sealedAt` is the
+  only differing field, so a hash identifies an upload rather than a commit.
+- **`sealAttestation` embeds the sealer's absolute local path**, git remote URL
+  and current branch, which travel with any artifact that crosses a trust
+  boundary.
+
+The last three are recorded on KNODIN-6.
+
+## Compatibility
+
+Compatible. No interface is removed or renamed. Exit codes change on paths that
+previously reported success incorrectly — a script relying on `seal` exiting 0
+after a refusal will now see the failure, which is the point.

package/docs/releases/0.10.6.md

@@ -0,0 +1,139 @@
+# knodin 0.10.6
+
+Four fixes, continuing the theme 0.10.2 through 0.10.5 have been working on: **a
+result that looks complete while quietly being wrong**. Three of the four were
+found the same way — by writing a test per case and watching which ones failed,
+rather than by reading the code and deciding it looked correct.
+
+Two of them disclose credentials, so read that section first if you have ever
+attached a diagnostics bundle to a support request.
+
+## Credentials survived redaction
+
+`knodin` scrubs secrets out of recorded failures before they can reach a
+diagnostics bundle — the artefact a user hands to someone else when asking for
+help. Two things it claimed to redact, it did not.
+
+**GitHub tokens were never redacted at all.** The pattern required a hyphen
+after the prefix:
+
+```
+\b(?:ghp|github_pat|sk|xox[baprs])-[-A-Za-z0-9_]{10,}\b
+```
+
+GitHub issues both its formats with an *underscore*. So the two GitHub
+alternatives matched a shape GitHub never mints and missed every shape it does.
+Slack and OpenAI genuinely do use a hyphen, so the separator now accepts either
+rather than being swapped.
+
+**An authorization header leaked the credential and redacted its label.** The
+value pattern stops at whitespace, so for the standard form
+
+```
+authorization: Bearer <token>
+```
+
+it matched only the word `Bearer` — replacing the part that identifies the
+header and preserving the part that authenticates. Exactly inverted. An optional
+known scheme is now consumed first, so the credential after it is what gets
+replaced.
+
+This was quiet in an unhelpful way. The journal stores only a *fingerprint* of
+the scrubbed message, never the message, so an unredacted credential is
+invisible locally and appears only in the bundle that gets shared. The tests
+assert redaction by fingerprint equivalence for that reason, and by
+value-independence — two messages differing only in the secret must fingerprint
+identically — which is how the `Bearer` case was found. An assertion written
+against expected output text would have passed, because the output *did* contain
+a redaction marker.
+
+Redaction is on by default, so this needed no unusual configuration to hit.
+
+A second redactor, in output compression, has different gaps in the opposite
+direction: it catches GitHub classic but not fine-grained, and misses Slack and
+OpenAI. Neither pattern list is a superset of the other. That one is filed
+rather than patched here, because adding three regexes to one of two diverging
+lists would only re-create the problem later.
+
+## `repair` emptied a sealed artifact
+
+Pointed at a sealed artifact, `knodin repair` deleted its symbols, references
+and dependencies. A sealed artifact's embedded source is the only copy of that
+source, so this was unrecoverable.
+
+0.10.5 audited five sites that purge rows for files missing from disk and
+guarded all five. This was a **sixth**, in repair's own removal branch, which
+never consulted the guard.
+
+It also explains a symptom that made no sense while the mechanism was unknown:
+`index_state` survived intact while everything around it was deleted.
+`removeIndexState`, called *inside* that same block, carries its own guard and
+declined correctly — so the damage was the guard working on one line and being
+absent from the four above it.
+
+Two adjacent hazards are guarded alongside it: a schema rebuild would drop every
+table of an artifact sealed by an older build, and promotion would overwrite a
+sealed artifact sitting at the active path.
+
+## `status` reported an unreadable graph as a measured zero
+
+A 94-file repository whose database was missing printed:
+
+```
+Graph or lifecycle needs repair: 95 issue(s) found
+(94 source files, 0 indexed files, 0 files with symbols)
+First issue: <an arbitrary source file>
+```
+
+`repair`, seconds later, reported 94 indexed and 53 with symbols. The two
+commands never counted differently. `status` was rendering a graph it could not
+read as a measurement of zero.
+
+The `95` was arithmetic, not a tally: the issue count is
+`missing.files + missing.records`, and the no-database branch fills
+`missing.files` with every source file. Ninety-four files plus one record. So
+the count scaled with repository size, and a graph that had simply never been
+built read as damage proportional to how much code you have.
+
+Three sites emitted zeros they had not measured, and now report the counts as
+unknown instead:
+
+```
+Graph or lifecycle needs repair: 1 issue(s) found
+(3 source files, indexed and symbol counts unknown; the graph could not be read)
+First issue: local index database is missing
+```
+
+`missing.files` is deliberately still populated. `repair` consumes it as its
+worklist and `seal` reads it as dirty paths, so emptying it — the obvious way to
+stop the count inflating — would have left repair with nothing to do.
+
+## C++ diagnostics pointed at files that do not exist
+
+Source extensions are matched first-listed rather than longest, and `.c`
+preceded `.cpp`. A C++ stack frame did not merely lose precision:
+
+```
+in    at f (src/main.cpp:3:4)
+was   { path: "src/main.c", line: null, column: null }
+now   { path: "src/main.cpp", line: 3, column: 4 }
+```
+
+A path to a file that does not exist, with the location dropped. `.tsx` worked
+only because it happened to precede `.ts`; longest-match is now the rule rather
+than an accident of list order.
+
+## Coverage measures the parse path again
+
+Not a shipped behaviour change, but worth recording because it changes what the
+project's own numbers mean.
+
+Generic source files are parsed off the main thread, and v8 coverage instruments
+only the isolate it runs in — so everything the parse path did executed inside a
+worker thread where it could not be observed, and was reported as untested. On
+an identical set of shards, with no test changed, disabling parse workers for
+the coverage run alone moved branch coverage from 74.85% to 77.16%: 414 branches
+the suite was already exercising.
+
+Sixteen functions had been sitting in the uncovered map looking like dead code.
+They were not.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.10.4",
+	"version": "0.10.6",
 	"knodin": {
 		"compatibility": "compatible"
 	},
@@ -23,32 +23,44 @@
 		"knodin": "dist/bin/launcher.js"
 	},
 	"files": [
+		"*.wasm",
+		"benchmarks/competitors/SYNTHESIS.md",
 		"dist",
-		"skills",
-		"docs/prompts/declare-multi-repository-system.md",
-		"docs/DEAD-CODE-AND-IMPACT.md",
-		"docs/DOCTOR-AND-UPDATES.md",
 		"docs/BACKUP-RETENTION.md",
-		"docs/DIAGNOSTICS.md",
 		"docs/BEHAVIORAL-CONTRACT.md",
-		"docs/DEMO.md",
+		"docs/CLI.md",
+		"docs/COMMAND-OUTPUT-COMPRESSION.md",
 		"docs/COMPARISON.md",
 		"docs/COMPETITIVE-LANDSCAPE-2026-08.md",
-		"docs/INDEXING-POLICY-AND-PROVENANCE.md",
+		"docs/CONTAINED-EXECUTION.md",
+		"docs/DEAD-CODE-AND-IMPACT.md",
+		"docs/DEMO.md",
+		"docs/DIAGNOSTICS.md",
+		"docs/DOCTOR-AND-UPDATES.md",
+		"docs/GIT-HISTORY-REVIEW.md",
 		"docs/HANDOFF.md",
+		"docs/INDEXING-POLICY-AND-PROVENANCE.md",
 		"docs/INSTALLATION.md",
 		"docs/MCP.md",
-		"docs/COMMAND-OUTPUT-COMPRESSION.md",
-		"docs/CONTAINED-EXECUTION.md",
 		"docs/PROGRESSIVE-EVIDENCE.md",
-		"docs/GIT-HISTORY-REVIEW.md",
-		"docs/SCIP-IMPORT.md",
-		"docs/CLI.md",
 		"docs/PT-ACCESS-RECOMMENDATION.md",
-		"docs/REPOSITORIES-AND-WORKTREES.md",
 		"docs/RELEASE-0.3-EVIDENCE.md",
-		"docs/SIGNED-UPDATES.md",
+		"docs/REPOSITORIES-AND-WORKTREES.md",
+		"docs/SCIP-IMPORT.md",
 		"docs/SHARED-INDEX-CONTRACT.md",
+		"docs/SIGNED-UPDATES.md",
+		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
+		"docs/TELEMETRY.md",
+		"docs/TOKEN-OPTIMIZER-SCORECARD.md",
+		"docs/assets/knodin-favicon.svg",
+		"docs/prompts/declare-multi-repository-system.md",
+		"docs/releases/0.10.0.md",
+		"docs/releases/0.10.1.md",
+		"docs/releases/0.10.2.md",
+		"docs/releases/0.10.3.md",
+		"docs/releases/0.10.4.md",
+		"docs/releases/0.10.5.md",
+		"docs/releases/0.10.6.md",
 		"docs/releases/0.3.0.md",
 		"docs/releases/0.4.0.md",
 		"docs/releases/0.4.1.md",
@@ -71,24 +83,14 @@
 		"docs/releases/0.8.6.md",
 		"docs/releases/0.8.7.md",
 		"docs/releases/0.9.0.md",
-		"docs/releases/0.10.0.md",
-		"docs/releases/0.10.1.md",
-		"docs/releases/0.10.2.md",
-		"docs/releases/0.10.3.md",
-		"docs/releases/0.10.4.md",
-		"docs/assets/knodin-favicon.svg",
-		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
-		"docs/TELEMETRY.md",
-		"docs/TOKEN-OPTIMIZER-SCORECARD.md",
-		"benchmarks/competitors/SYNTHESIS.md",
 		"roadmap/competitive-roadmap.md",
 		"schemas/release-attestation-v1.schema.json",
-		"schemas/support-bundle-v2.schema.json",
-		"schemas/shared-index-config-v1.schema.json",
 		"schemas/shared-index-branch-pointer-v1.schema.json",
+		"schemas/shared-index-config-v1.schema.json",
 		"schemas/shared-index-manifest-v1.schema.json",
 		"schemas/shared-index-provenance-v1.schema.json",
-		"*.wasm"
+		"schemas/support-bundle-v2.schema.json",
+		"skills"
 	],
 	"engines": {
 		"node": ">=24.0.0"