knodin 0.10.3 → 0.10.5

package/dist/bin/cli.js

@@ -77,8 +77,17 @@ function integrationAgents(repo) {
     const repositoryDetected = inspectRepositoryIntegrationStatus(repo)?.agents ?? [];
     return [...new Set([...detectSupportedAgents(), ...previous, ...repositoryDetected])];
 }
-function formatInitHuman(result) {
-    let agents = `${result.paths.scope} — no supported coding agents detected`;
+export function formatInitHuman(result) {
+    // `configured` is what THIS run wrote, not what exists on the machine. The
+    // old wording called an empty list "no supported coding agents detected",
+    // asserting a detection result init never computed — and it read as a flat
+    // contradiction of the `status` line seconds later, which lists the agents
+    // that genuinely are configured (EASFDC-8499).
+    //
+    // Deliberately not calling the detector here: a formatter that reads the
+    // machine cannot be tested deterministically, and the honest fix is to stop
+    // claiming more than this value supports rather than to go find more.
+    let agents = `${result.paths.scope} — no agents configured by this run`;
     if (result.paths.scope === "cli-only")
         agents = "CLI-only — AI agents are not configured to discover knodin";
     else if (result.paths.agentIntegration.configured.length > 0)
@@ -165,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`.
@@ -2247,11 +2262,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);
@@ -2475,14 +2518,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": {
@@ -3029,7 +3096,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/engine/candidate-database.js

@@ -200,6 +200,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 +238,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,11 +41,12 @@ 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";
 import { deleteAllSymbols, deleteSymbolsForFile, deleteSymbolsMatchingPath, ORPHANED_EMBEDDING_PREDICATE, purgeOrphanEmbeddings, } from "./symbol-delete.js";
+import { searchRepoText } from "./text-matches.js";
 // ES Module resolution
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -7272,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;
@@ -7682,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]);
     }
@@ -7853,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 {
@@ -8523,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);
@@ -11555,6 +11610,13 @@ function withStaleness(engine, claimRepository, openDb, openPolicy) {
                 row.staleness = staleness;
             return page;
         },
+        searchText(term, repoPath, options) {
+            claimRepository(repoPath);
+            // No staleness annotation: this reads the working tree directly rather
+            // than the graph, so its answers are current by construction and
+            // stamping them with the index's freshness would misreport them.
+            return engine.searchText(term, repoPath, options);
+        },
         async query(pattern, target, repoPath, to, limit, depth, detailLevel, selector, impactOptions, options) {
             claimRepository(repoPath);
             const result = await engine.query(pattern, target, repoPath, to, limit, depth, detailLevel, selector, impactOptions, options);
@@ -11893,7 +11955,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);
@@ -13858,7 +13920,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 {
@@ -14073,6 +14135,15 @@ export function createEngine(openPolicy = DEFAULT_ENGINE_OPEN_POLICY) {
                 indexCoordination.release();
             }
         },
+        async searchText(term, repoPath, options = {}) {
+            if (term.length === 0)
+                throw new Error("knodin searchText: term must not be empty");
+            // Reads the working tree, not the graph, so it needs no open database
+            // and no freshness check. `getLanguageForFile` is the same grammar
+            // loader indexing uses, which is what makes the classification
+            // evidence rather than a heuristic over file extensions.
+            return searchRepoText(path.resolve(repoPath), term, getLanguageForFile, () => new Parser(), options);
+        },
         async search(query, repoPath, limit, options = {}) {
             const resolvedRepoPath = path.resolve(repoPath);
             const offset = options.offset ?? 0;