knodin 0.12.1 → 0.13.0

package/README.md

@@ -150,7 +150,7 @@ Start broad, inspect the likely change surface, then review the actual diff:
 
 ```bash
 # Orient on an unfamiliar checkout
-knodin context
+knodin context "understand this checkout"
 
 # Explain a symbol with source and relationships
 knodin explain createServer
@@ -170,6 +170,21 @@ knodin map
 knodin pack createServer --max-tokens 4000
 ```
 
+For a task that needs an implementation and its dependencies:
+
+```bash
+knodin context "find code that persists an order" --implementations --json
+knodin context "rename persist" --symbol persist --file src/storage.ts --json
+knodin evidence expand --files src/storage.ts --items 100 --json
+```
+
+Discovery returns candidates for you to select; investigation collects source,
+callers, importers, tests, and impact for the selected identity. Evidence bundles
+page exact source and issue reusable per-file receipts after complete delivery.
+Ambiguity, incomplete coverage, and budget limits stay visible. See the
+[CLI guide](docs/CLI.md#task-discovery-and-investigation) and
+[evidence protocol](docs/PROGRESSIVE-EVIDENCE.md#graph-backed-file-bundles).
+
 If freshness or lifecycle checks fail:
 
 ```bash

package/dist/bin/cli.js

@@ -20,6 +20,10 @@ import { inspectClaudeAgentHooks, installClaudeAgentHooks, uninstallClaudeAgentH
 import { detectSupportedAgents, parseInitScope, } from "../src/agent-integration.js";
 import { refreshExternalGraphArtifacts, writeArtifactRefreshRecord, } from "../src/artifact-refresh.js";
 import { formatBackupHuman, installBackupRetention, listBackups, maybeRunOpportunisticRetention, pruneBackups, removeBackupRetention, retentionDoctor, retentionStatus, runInstalledRetention, } from "../src/backup-retention.js";
+import { ClassConsumerQueryError, } from "../src/class-consumer-contract.js";
+import { readClassConsumerCursor } from "../src/class-consumer-cursor.js";
+import { validateClassConsumerDelivery } from "../src/class-consumer-delivery.js";
+import { finalizeClassConsumerPage } from "../src/class-consumer-page.js";
 import { checkIndexed, extractPositionals, extractRepoFlag, parseReviewArgs, planIndex, resolveCliRuntimeCommand, resolveRepo, } from "../src/cli-args.js";
 import { helpCommandPath, parseCliInvocation, renderCliHelp } from "../src/cli-model.js";
 import { buildKnodinContext } from "../src/context.js";
@@ -31,19 +35,24 @@ import { createEngine, describeThrown, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PA
 import { runSeal } from "../src/engine/seal-command.js";
 import { runSealedQuery } from "../src/engine/sealed-query.js";
 import { resolveDbPath } from "../src/engine/state-paths.js";
+import { deliverEvidenceBundle } from "../src/evidence-bundle.js";
+import { createEvidenceGraphAdapter } from "../src/evidence-graph.js";
 import { diagnoseFailure, } from "../src/failure-diagnosis.js";
 import { gitExecutable } from "../src/git-executable.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../src/graph-query-health.js";
+import { findImplementationCandidates } from "../src/implementation-search.js";
 import { createIndexActivityReporter } from "../src/index-activity.js";
+import { indexCoverageCore, indexCoverageNotice, indexCoverageSnapshot, } from "../src/index-coverage-read.js";
 import { InitializationHealthError, initializeRepository, inspectRepositoryIntegrationStatus, readRepositoryIntegrationConfig, refreshFromGitEvent, repairLifecycleRouting, } from "../src/init.js";
 import { createInitProgressRenderer } from "../src/init-progress.js";
+import { buildTaskInvestigation } from "../src/investigation.js";
 import { attachLifecycleHealth, attachRepairLifecycle } from "../src/lifecycle-health.js";
 import { acknowledgeUpdateFailure, queryOwnerAvailability, readManagerUpdateState, readUpdateJournal, resolveManagerOwnership, setManualPin, unpinUpdate, updateAttention, writeManagerUpdateState, } from "../src/manager-update.js";
 import { addMirror, listMirrors, refreshMirror, removeMirror } from "../src/mirror.js";
 import { compressOutput, compressOutputFile, deleteOutputArtifact, readOutputArtifact, } from "../src/output-compression.js";
 import { clearTelemetry, exportTelemetry, readTelemetryRecords, telemetryStatus, writeTelemetryReport, } from "../src/output-telemetry.js";
 import { auditPullRequests } from "../src/pr-triage.js";
-import { deliverProgressiveEvidence, } from "../src/progressive-evidence.js";
+import { deliverProgressiveEvidence, evidenceHandleSecret, } from "../src/progressive-evidence.js";
 import { acquireRepairLease } from "../src/repair-lease.js";
 import { createRepairPlan, createRepairProgressRenderer, parseRepairCliArgs, resolveRepairProgressMode, serializeRepairJsonlRecord, } from "../src/repair-progress.js";
 import { runRepositoryInitializationProcess } from "../src/repository-init-process.js";
@@ -161,15 +170,21 @@ function formatSemanticGap(readiness) {
 }
 function formatIndexHuman(result) {
     const semantic = formatSemanticGap(result.semanticReadiness);
+    const scope = formatIndexCoverageHuman(result.indexCoverage);
     if (result.indexed.length === 0 && result.unchanged.length > 0) {
         const noun = result.unchanged.length === 1 ? "file" : "files";
-        return `Graph already current: ${result.unchanged.length.toLocaleString()} requested ${noun} needed no work; health verified.${semantic}\n`;
+        return `Graph already current: ${result.unchanged.length.toLocaleString()} requested ${noun} needed no work; health verified.${semantic}\n${scope}\n`;
     }
     const unchanged = result.unchanged.length > 0
         ? `; ${result.unchanged.length.toLocaleString()} already current`
         : "";
     const noun = result.indexed.length === 1 ? "file" : "files";
-    return `Index complete: ${result.indexed.length.toLocaleString()} ${noun} indexed${unchanged}; graph health verified.${semantic}\n`;
+    return `Index complete: ${result.indexed.length.toLocaleString()} ${noun} indexed${unchanged}; graph health verified.${semantic}\n${scope}\n`;
+}
+function formatIndexCoverageHuman(coverage) {
+    if (!coverage)
+        return "Local graph index coverage is unknown; a negative graph answer does not establish absence.";
+    return `Local graph index coverage: ${coverage.mode}; intent ${coverage.intentState}; repository inventory complete: ${coverage.repositoryComplete}. ${indexCoverageNotice(coverage) ?? "Inventory extent does not establish complete static relationships or runtime use."}`;
 }
 function formatIndexVerificationError(result) {
     const firstIssue = result.verification.missing.files[0] ?? result.verification.missing.records[0];
@@ -195,8 +210,15 @@ function formatLifecycleLine(lifecycle, isMirror) {
         return "";
     if (isMirror)
         return "Hooks: not applicable; a mirror is refreshed explicitly, not by Git events.\n";
-    if (lifecycle.status === "healthy")
-        return "Hooks: installed and executable.\n";
+    if (lifecycle.status === "healthy") {
+        // A silent self-heal would leave the user unable to explain why the hook's
+        // interpreter changed; a degraded report for a fixed condition would cry
+        // wolf. Say what happened, once, on the healthy line.
+        const heal = lifecycle.interpreterSelfHeal;
+        return heal
+            ? `Hooks: installed and executable; background indexer interpreter self-healed (${heal.from} -> ${heal.to}).\n`
+            : "Hooks: installed and executable.\n";
+    }
     const issue = lifecycle.issues[0] ?? "refresh capability is not verified";
     return `Lifecycle refresh: ${lifecycle.status}; ${issue}. Run \`knodin repair --lifecycle\`.\n`;
 }
@@ -407,7 +429,7 @@ function formatStatusHuman(result) {
     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}`;
+    const coverage = `${result.coverage.sourceFiles} source files, ${indexedCounts}${formatCoverageGaps(result.coverage.skipped)}${mirrorNote}${semanticNote}. ${formatIndexCoverageHuman(result.indexCoverage)}`;
     if (result.status === "indexing" && result.activity) {
         const count = result.activity.phaseTotal === undefined
             ? ""
@@ -449,24 +471,34 @@ function formatStatusHuman(result) {
     // 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 issueItems = result.coverage.countsUnknown
+        ? result.missing.records
+        : [...result.missing.files, ...result.missing.records];
+    const outstanding = issueItems.length;
+    // One issue keeps the established single-line shape; more are listed bounded
+    // rather than hidden behind "First issue" — a report that names one problem
+    // out of several sends the user to fix it and then surprises them with the
+    // rest, one status invocation at a time (KNODIN-38).
+    const shownIssues = issueItems.slice(0, 5);
+    const hiddenIssues = outstanding - shownIssues.length;
+    const detail = shownIssues.length === 0
+        ? ""
+        : shownIssues.length === 1
+            ? ` First issue: ${shownIssues[0]}.`
+            : ` Issues: ${shownIssues.join("; ")}${hiddenIssues > 0 ? `; +${hiddenIssues} more (see --json)` : ""}.`;
     // 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`.");
+    // Lifecycle-only damage takes `repair --lifecycle`, not `init`: the graph is
+    // healthy, and the engine's own repairSteps already say so — prescribing
+    // `init` here contradicted the lifecycle line printed directly beneath it.
+    const lifecycleOnly = result.lifecycle?.status === "degraded" &&
+        (result.coverage.countsUnknown || result.missing.files.length === 0) &&
+        result.missing.records.every((record) => result.lifecycle?.issues.includes(record));
+    const repairCommand = worktreeStep ?? (lifecycleOnly ? "Run `knodin repair --lifecycle`." : "Run `knodin repair`.");
     return `Graph or lifecycle needs repair: ${outstanding} issue(s) found (${coverage}).${detail} ${repairCommand}\n${lifecycleLine}${integrationLine}`;
 }
 function humanLabel(key) {
@@ -1520,6 +1552,8 @@ async function main() {
         return attemptOpportunisticSharedRestore(repo, engine);
     };
     let result;
+    let finalizedClassConsumer = false;
+    let classConsumerErrorContract;
     let repairOutput;
     let repairWasPlan = false;
     let repairWasLifecycle = false;
@@ -1538,7 +1572,7 @@ async function main() {
             process.exitCode = 1;
             return verified;
         }
-        return decorateGraphQueryResult(value, verified.state, verified.graph.freshness);
+        return decorateGraphQueryResult(value, verified.state, verified.graph.freshness, verified.graph.indexCoverage, health.graph.indexCoverage);
     };
     switch (cmd) {
         case "shared": {
@@ -1813,10 +1847,11 @@ async function main() {
             }
             const freshness = status.freshness?.state ?? "unknown";
             const cacheKey = JSON.stringify({
-                schemaVersion: 1,
+                schemaVersion: 2,
                 head: status.freshness?.currentHead,
                 fingerprint: status.freshness?.workingTree?.indexedFingerprint,
                 generation: status.indexGeneration,
+                indexCoverage: indexCoverageCore(status.indexCoverage),
                 budgets: [600, 8192, 12],
             });
             const cacheEligible = canUseSessionContextCache(status.status, freshness);
@@ -1831,7 +1866,11 @@ async function main() {
                 cacheHit = false;
                 try {
                     const context = await buildKnodinContext(engine, "Orient this coding session", repo, undefined, []);
-                    text = renderSessionContext(context, freshness);
+                    const verified = await engine.status(repo, { audit: "cached" });
+                    if (indexCoverageSnapshot(status.indexCoverage) !==
+                        indexCoverageSnapshot(verified.indexCoverage))
+                        throw new Error("Index coverage changed during session context generation");
+                    text = renderSessionContext(context, freshness, verified.indexCoverage);
                     writeSessionContextCache(repo, cacheKey, text);
                 }
                 catch {
@@ -1867,13 +1906,20 @@ async function main() {
             if (client !== undefined &&
                 !["claude", "codex", "gemini", "copilot", "antigravity"].includes(client))
                 throw new Error("knodin doctor: --client must be claude, codex, gemini, copilot, or antigravity");
-            const unsupported = rest.filter((argument, index) => argument !== "--client" && rest[index - 1] !== "--client");
+            const unsupported = rest.filter((argument, index) => argument !== "--client" && argument !== "--deep" && rest[index - 1] !== "--client");
             if (unsupported.length > 0)
                 throw new Error(`knodin doctor: unknown option ${unsupported[0]}`);
             const diagnosis = await diagnoseInstallation(repo, {
                 currentVersion: KNODIN_VERSION,
                 runtimeCommand: [...runtimeCommand, "serve"],
-                graph: await engine.status(repo, { audit: "deep" }),
+                // Adaptive, like `status`: the persisted-audit path runs the same
+                // drift probe, so a stale graph still reports stale, while a forced
+                // deep audit on a very large repository cost doctor two full stat
+                // sweeps every run (KNODIN-39). `--deep` keeps the exact audit
+                // available on demand.
+                graph: await engine.status(repo, {
+                    audit: rest.includes("--deep") ? "deep" : "adaptive",
+                }),
                 client,
             });
             const manager = diagnosis.manager.name;
@@ -1884,7 +1930,23 @@ async function main() {
                     : "unknown",
                 env: process.env,
             });
-            result = diagnosis;
+            // One MCP probe backs every client row; the human listing printed the
+            // identical initialize/toolsList block five times, reading as five
+            // independent server checks (KNODIN-40). JSON keeps the per-client
+            // shape for compatibility.
+            const agents = diagnosis.agents;
+            result = jsonOutput
+                ? diagnosis
+                : {
+                    ...diagnosis,
+                    agents: {
+                        ...agents,
+                        clients: agents.clients?.map((clientRow) => ({
+                            ...clientRow,
+                            server: "shared MCP probe; see the mcp section",
+                        })),
+                    },
+                };
             break;
         }
         case "system": {
@@ -2647,6 +2709,24 @@ async function main() {
         case "evidence": {
             const level = rest[0];
             const file = rest[1];
+            const files = selectorValue("--files")?.split(",");
+            if (files) {
+                if (level !== "evidence" && level !== "expand")
+                    throw new Error("Evidence bundles require evidence or expand level");
+                if (file && !file.startsWith("--"))
+                    throw new Error("Choose a file or --files, not both");
+                result = await deliverEvidenceBundle({
+                    repo,
+                    files,
+                    level,
+                    continuation: selectorValue("--continuation"),
+                    alreadyPresent: selectorValue("--already-present")?.split(","),
+                    byteLimit: responseBudget.bytes,
+                    tokenLimit: responseBudget.tokens,
+                    itemLimit: responseBudget.items,
+                }, createEvidenceGraphAdapter(engine));
+                break;
+            }
             if (!file || !["locate", "outline", "evidence", "expand"].includes(level))
                 throw new Error("knodin evidence requires locate|outline|evidence|expand <file>");
             result = deliverProgressiveEvidence({
@@ -2677,7 +2757,7 @@ async function main() {
                 ? ""
                 : (rest[1] ?? "");
             if (!pattern) {
-                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|file_metrics|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
+                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|file_metrics|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|class_consumers|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
                 process.exit(1);
             }
             const directionValue = selectorValue("--direction");
@@ -2748,6 +2828,82 @@ async function main() {
                 process.exitCode = 1;
                 break;
             }
+            if (pattern === "class_consumers") {
+                if (queryLimitRaw && Number(queryLimitRaw) > 1000)
+                    throw new Error("class_consumers --limit must not exceed 1000 sites");
+                if (["--offset", "--kinds", "--relations", "--direction", "--depth", "--exclude-tests"].some((flag) => rest.includes(flag)))
+                    throw new Error("class_consumers supports --test-scope/--path and --continuation, not offset/kinds/relations/direction/depth/exclude-tests");
+                const secret = evidenceHandleSecret(repo).secret;
+                const token = selectorValue("--continuation");
+                const cursor = token ? readClassConsumerCursor(token, secret) : undefined;
+                const request = {
+                    symbol: target,
+                    selector,
+                    testScope: (testScopeValue ?? "all"),
+                    path: selectorValue("--path"),
+                    limit: queryLimitRaw ? Number(queryLimitRaw) : 100,
+                    ...(cursor
+                        ? {
+                            after: cursor.after,
+                            expectedQueryDigest: cursor.queryDigest,
+                            expectedSnapshotDigest: cursor.snapshotDigest,
+                        }
+                        : {}),
+                };
+                try {
+                    const page = await engine.queryClassConsumers(repo, request);
+                    // Defer maintenance, not the audit, until a later eligible status or close.
+                    const verified = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached", checkpoint: "defer" })));
+                    if (!verified.available) {
+                        result = verified;
+                        process.exitCode = 1;
+                        break;
+                    }
+                    await validateClassConsumerDelivery(page, request, (next) => engine.queryClassConsumers(repo, next));
+                    result = finalizeClassConsumerPage(page, {
+                        secret,
+                        budget: responseBudget,
+                        decorate: (candidate) => decorateGraphQueryResult(candidate, verified.state, undefined, verified.graph.indexCoverage, queryHealth?.available ? queryHealth.graph.indexCoverage : undefined),
+                    });
+                    finalizedClassConsumer = true;
+                }
+                catch (error) {
+                    if (error instanceof ClassConsumerQueryError &&
+                        [
+                            "CLASS_CONSUMER_TARGET_NOT_FOUND",
+                            "CLASS_CONSUMER_TARGET_AMBIGUOUS",
+                            "CLASS_CONSUMER_TARGET_CAPABILITY_MISSING",
+                        ].includes(error.code)) {
+                        result = {
+                            available: false,
+                            status: "unavailable",
+                            pattern,
+                            targetResolution: error.code === "CLASS_CONSUMER_TARGET_CAPABILITY_MISSING"
+                                ? "capability-missing"
+                                : error.code === "CLASS_CONSUMER_TARGET_NOT_FOUND"
+                                    ? "not-found"
+                                    : "ambiguous",
+                            code: error.code,
+                            error: error.message,
+                            candidates: error.candidates,
+                            ...(queryHealth?.available
+                                ? {
+                                    indexCoverage: queryHealth.graph.indexCoverage,
+                                    freshness: queryHealth.graph.freshness,
+                                }
+                                : {}),
+                        };
+                        classConsumerErrorContract = {
+                            code: error.code,
+                            targetResolution: result.targetResolution,
+                        };
+                        process.exitCode = 1;
+                    }
+                    else
+                        throw error;
+                }
+                break;
+            }
             result = await engine.query(pattern, target, repo, to, queryLimitRaw ? Number(queryLimitRaw) : undefined, depth, detailLevel, selector, pattern === "impact"
                 ? {
                     mode: selectorValue("--impact-mode") === "file" ? "file" : "symbol",
@@ -2807,12 +2963,12 @@ async function main() {
                     process.exitCode = 1;
                     break;
                 }
-                result = decorateGraphQueryResult(result, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness);
+                result = decorateGraphQueryResult(result, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness, verifiedQueryHealth.graph.indexCoverage, queryHealth.graph.indexCoverage);
             }
             // A target that does not exist is operator error, not a negative
             // answer, so it exits non-zero like an unavailable graph rather than
             // like real dead code (KNODIN-28). `resolved` with zero rows keeps
-            // exit 0: the symbol exists and genuinely has no callers.
+            // exit 0: no callers were found within the reported index coverage.
             if (result?.targetResolution === "not-found")
                 process.exitCode = 1;
             break;
@@ -2994,7 +3150,26 @@ async function main() {
                 process.stderr.write('knodin context requires a "<task>" description\n');
                 process.exit(1);
             }
-            result = await graphRead(() => buildKnodinContext(engine, task, repo, rest[1]));
+            const symbol = selectorValue("--symbol");
+            if (rest.includes("--implementations")) {
+                if (symbol)
+                    throw new Error("Choose --implementations or --symbol, not both");
+                result = await graphRead(() => findImplementationCandidates(engine, repo, {
+                    task,
+                    limit: selectorValue("--limit") ? Number(selectorValue("--limit")) : undefined,
+                    offset: selectorValue("--offset") ? Number(selectorValue("--offset")) : undefined,
+                }));
+                break;
+            }
+            result = await graphRead(() => symbol
+                ? buildTaskInvestigation(engine, repo, {
+                    task,
+                    symbol,
+                    ...selector,
+                    limit: selectorValue("--limit") ? Number(selectorValue("--limit")) : undefined,
+                    depth: selectorValue("--depth") ? Number(selectorValue("--depth")) : undefined,
+                })
+                : buildKnodinContext(engine, task, repo, rest[1]));
             break;
         }
         default:
@@ -3002,6 +3177,8 @@ async function main() {
             process.exit(1);
     }
     await engine.close();
+    if (result?.available === false)
+        process.exitCode = 1;
     if (agentEventOutput) {
         if (result !== null && result !== undefined)
             process.stdout.write(`${JSON.stringify(result)}\n`);
@@ -3010,9 +3187,31 @@ async function main() {
     if (statusWasWatched)
         return;
     const fileMetricsOutput = cmd === "query" && rest[0] === "file_metrics";
-    const boundedResult = applyResponseBudget(result, cmd, responseBudget, fileMetricsOutput
-        ? { bytes: 16_777_216, tokens: 4_194_304, items: 100_000 }
-        : { bytes: 65_536, tokens: 16_384, items: 100 });
+    // The bundle protocol budgets its signed manifest, source and continuation together.
+    // Generic post-truncation would invalidate that recoverable envelope.
+    const evidenceBundle = cmd === "evidence" && selectorValue("--files") !== undefined;
+    const boundedResult = evidenceBundle || finalizedClassConsumer
+        ? result
+        : applyResponseBudget(result, cmd === "query" && rest[0] === "flow_analysis" ? "query:flow_analysis" : cmd, responseBudget, fileMetricsOutput
+            ? { bytes: 16_777_216, tokens: 4_194_304, items: 100_000 }
+            : { bytes: 65_536, tokens: 16_384, items: 100 });
+    if (classConsumerErrorContract) {
+        const delivered = boundedResult;
+        if (delivered.code !== classConsumerErrorContract.code ||
+            delivered.targetResolution !== classConsumerErrorContract.targetResolution ||
+            delivered.available !== false ||
+            delivered.status !== "unavailable")
+            throw new Error("Response budget cannot preserve the class-consumer error contract; increase the budget.");
+    }
+    if (cmd === "query" && rest[0] === "inheritors_of") {
+        const qualification = result
+            ?.inheritanceQuery;
+        const delivered = boundedResult
+            ?.inheritanceQuery;
+        if (qualification &&
+            ["version", "mode", "partial", "truncated", "apex"].some((key) => delivered?.[key] !== qualification[key]))
+            throw new Error("Response budget cannot preserve the inheritance qualification; increase the budget.");
+    }
     const finalExitCode = Math.max(Number(process.exitCode ?? 0), repairExitCode);
     if (cmd === "init" && !jsonOutput) {
         process.stdout.write(formatInitHuman(boundedResult));

package/dist/src/agent-events.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { indexCoverageCore, indexCoverageNotice } from "./index-coverage-read.js";
 import { countOutputTokens } from "./output-telemetry.js";
 import { appendSessionEvent, } from "./session-telemetry.js";
 export const SESSION_CONTEXT_BUDGET_LINE = "Budget: at most 600 tokens, 8 KiB, 12 items.";
@@ -81,23 +82,40 @@ export function writeSessionContextCache(repo, key, text) {
 export function canUseSessionContextCache(status, freshness) {
     return status === "healthy" && freshness === "fresh";
 }
-export function renderSessionContext(context, freshness) {
+export function renderSessionContext(context, freshness, coverage) {
     const list = (values, render) => (values ?? []).slice(0, 3).map(render).join(", ") || "none reported";
-    let text = [
+    const header = [
         "## knodin session context",
         `Graph evidence: ${freshness}. Treat stale or unavailable evidence as incomplete.`,
         SESSION_CONTEXT_BUDGET_LINE,
-        `Repository: ${context.stats?.files ?? "?"} files, ${context.stats?.symbols ?? "?"} symbols.`,
+        `Index coverage: ${JSON.stringify(indexCoverageCore(coverage) ?? { mode: "unknown", repositoryComplete: false, negativeScope: "unknown" })}`,
+        indexCoverageNotice(coverage) ??
+            (coverage
+                ? "Inventory extent does not prove complete relationships or runtime use."
+                : "Index coverage is unknown; negatives do not establish repository-wide absence."),
+    ];
+    const details = [
+        `Indexed scope: ${context.stats?.files ?? "?"} files, ${context.stats?.symbols ?? "?"} symbols.`,
         `Subsystems: ${list(context.communities, (value) => `${value.name} (${value.size})`)}`,
         `Hubs: ${list(context.hubs, (value) => `${value.symbol} (${value.degree})`)}`,
         `Flows: ${list(context.flows, (value) => value.symbol ?? "unnamed")}`,
         `Suggested next operation: ${context.suggestedOperation ?? "context"} (heuristic only).`,
         "Use exact source evidence and preserve ambiguity, freshness, omissions, and response budgets.",
-    ].join("\n");
-    while ((countOutputTokens(text) > 600 || Buffer.byteLength(text) > 8192) && text.includes("\n")) {
-        text = `${text.slice(0, text.lastIndexOf("\n"))}\nContext truncated to the configured session budget.`;
+    ];
+    let truncated = false;
+    for (;;) {
+        const text = [
+            ...header,
+            ...details,
+            ...(truncated ? ["Context truncated to the configured session budget."] : []),
+        ].join("\n");
+        if (countOutputTokens(text) <= 600 && Buffer.byteLength(text) <= 8192)
+            return text;
+        if (details.length === 0)
+            throw new RangeError("Session context budget cannot preserve index coverage");
+        details.pop();
+        truncated = true;
     }
-    return text;
 }
 export function recordClaudeLifecycleEvent(repo, event, payload) {
     const sessionId = payload.session_id;

package/dist/src/authenticated-cursor.js

@@ -0,0 +1,81 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const MAX_CURSOR_PAYLOAD_BYTES = 4096;
+export const MAX_AUTHENTICATED_CURSOR_LENGTH = 6144;
+const DOMAIN = "knodin:authenticated-cursor:v1\0";
+function checkParameters(secret, prefix) {
+    if (!Buffer.isBuffer(secret) || secret.length !== 32)
+        throw new TypeError("cursor signing key must be 32 bytes");
+    if (!/^[a-z][a-z0-9]{1,15}$/.test(prefix))
+        throw new TypeError("invalid cursor prefix");
+}
+function signature(secret, prefix, body) {
+    return createHmac("sha256", secret)
+        .update(DOMAIN)
+        .update(prefix)
+        .update("\0")
+        .update(body)
+        .digest();
+}
+function isRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Authentication only, not encryption, schema validation or a freshness lease.
+ * Callers supply the existing per-repository evidence secret and a distinct
+ * protocol prefix; they must validate payload shape and current query/snapshot.
+ * Sign only the boundary of rows actually delivered after response budgeting.
+ */
+export function signAuthenticatedCursor(value, secret, prefix) {
+    checkParameters(secret, prefix);
+    let serialized;
+    try {
+        if (!isRecord(value))
+            throw new Error("cursor payload is not a record");
+        serialized = JSON.stringify(value);
+        if (typeof serialized !== "string" || !isRecord(JSON.parse(serialized)))
+            throw new Error("serialized cursor payload is not a record");
+    }
+    catch {
+        throw new TypeError("cursor payload must be a serializable JSON object");
+    }
+    if (Buffer.byteLength(serialized) > MAX_CURSOR_PAYLOAD_BYTES)
+        throw new RangeError("cursor payload exceeds its byte limit");
+    const body = Buffer.from(serialized).toString("base64url");
+    return `${prefix}.${body}.${signature(secret, prefix, body).toString("base64url")}`;
+}
+export function verifyAuthenticatedCursor(value, secret, prefix) {
+    checkParameters(secret, prefix);
+    const invalid = () => new Error("invalid authenticated cursor");
+    if (typeof value !== "string" || value.length > MAX_AUTHENTICATED_CURSOR_LENGTH)
+        throw invalid();
+    const parts = value.split(".");
+    if (parts.length !== 3 || parts[0] !== prefix)
+        throw invalid();
+    const [, body, encodedSignature] = parts;
+    if (!/^[A-Za-z0-9_-]+$/.test(body) || !/^[A-Za-z0-9_-]+$/.test(encodedSignature))
+        throw invalid();
+    const actual = Buffer.from(encodedSignature, "base64url");
+    const expected = signature(secret, prefix, body);
+    if (actual.length !== expected.length ||
+        actual.toString("base64url") !== encodedSignature ||
+        !timingSafeEqual(actual, expected))
+        throw invalid();
+    const bytes = Buffer.from(body, "base64url");
+    if (bytes.length > MAX_CURSOR_PAYLOAD_BYTES || bytes.toString("base64url") !== body)
+        throw invalid();
+    const text = bytes.toString("utf8");
+    if (!Buffer.from(text).equals(bytes))
+        throw invalid();
+    try {
+        const payload = JSON.parse(text);
+        if (isRecord(payload))
+            return payload;
+    }
+    catch {
+        // Never echo untrusted cursor contents or decoder error details.
+    }
+    throw invalid();
+}

package/dist/src/backup-retention.js

@@ -355,12 +355,19 @@ function parseRetentionReceipt(value) {
 }
 function readInstalledRetention(options) {
     const locations = homes(options);
+    const receiptPath = path.join(locations.stateRoot, "receipt.json");
     const policy = parseRetentionPolicy(readJson(locations.policy));
-    const receipt = parseRetentionReceipt(readJson(path.join(locations.stateRoot, "receipt.json")));
+    const receipt = parseRetentionReceipt(readJson(receiptPath));
+    // A machine where NEITHER file exists never had retention installed; that is
+    // a clean state, not a broken one, and reporting "missing-or-invalid" for it
+    // taught every fresh doctor run to cry attention-required (KNODIN-40). Any
+    // on-disk trace — even an unparseable file — is installation evidence and
+    // keeps the strict issue reporting.
+    const installEvidence = fs.existsSync(locations.policy) || fs.existsSync(receiptPath);
     const issues = [];
-    if (!policy)
+    if (installEvidence && !policy)
         issues.push("policy-missing-or-invalid");
-    if (!receipt)
+    if (installEvidence && !receipt)
         issues.push("receipt-missing-or-invalid");
     if (policy && receipt && digest(`${JSON.stringify(policy, null, 2)}\n`) !== receipt.policyDigest)
         issues.push("policy-receipt-mismatch");
@@ -373,7 +380,7 @@ function readInstalledRetention(options) {
             issues.push(`scheduler-missing: ${artifact.path}`);
         }
     }
-    return { policy, receipt, issues };
+    return { policy, receipt, issues, installEvidence };
 }
 function commandRunner(command, args) {
     const result = childProcess.spawnSync(command, args, { encoding: "utf8" });
@@ -571,11 +578,18 @@ export function installBackupRetention(roots, options = {}) {
 }
 export function retentionStatus(options = {}) {
     const locations = homes(options);
-    const { policy, receipt, issues } = readInstalledRetention(options);
+    const { policy, receipt, issues, installEvidence } = readInstalledRetention(options);
     const lastRun = readJson(path.join(locations.stateRoot, "last-run.json"));
     return {
         schemaVersion: 1,
-        status: issues.length === 0 ? "healthy" : policy || receipt ? "attention-required" : "not-installed",
+        // Keyed on on-disk evidence rather than parse success: a never-installed
+        // machine is "not-installed" with no issues, while an installed-but-broken
+        // state (either file present, parseable or not) keeps attention-required.
+        status: !installEvidence && issues.length === 0
+            ? "not-installed"
+            : issues.length === 0
+                ? "healthy"
+                : "attention-required",
         installed: Boolean(policy && receipt),
         policy,
         receipt,