knodin 0.12.2 → 0.13.1

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";
@@ -27,23 +31,29 @@ import { exportContext, grepPackedArtifact, readPackedArtifact } from "../src/co
 import { clearDiagnostics, collectDiagnostics, diagnosticsStatus, disableDiagnostics, enableDiagnostics, inspectDiagnosticsBundle, persistDiagnosticsPreview, recordDiagnosticFailure, } from "../src/diagnostics.js";
 import { getDocSection, listDocTopics } from "../src/docs-sections.js";
 import { diagnoseInstallation } from "../src/doctor.js";
+import { sweepAbandonedCandidates } from "../src/engine/candidate-database.js";
 import { createEngine, describeThrown, KNODIN_SCHEMA_VERSION, REPO_WIDE_QUERY_PATTERNS, } from "../src/engine/index.js";
 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";
@@ -51,6 +61,8 @@ import { detectRepositorySignals, discoverRepositories, formatRepositoryHuman, i
 import { applyResponseBudget } from "../src/response-budget.js";
 import { appendSessionEvent, clearSessionTelemetry, disableSessionTelemetry, enableSessionTelemetry, readSessionEvents, sessionTelemetryStatus, } from "../src/session-telemetry.js";
 import { inspectKnodinSkills, installKnodinSkills, KNODIN_SKILLS, removeKnodinSkills, } from "../src/skill-management.js";
+import { inventoryStorage } from "../src/storage-inventory.js";
+import { configureStoragePolicy, postOperationStorageMaintenance, resolveStoragePolicy, } from "../src/storage-management.js";
 import { configuredRepositoryInitMemoryLimitBytes, enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../src/system-config.js";
 import { applySystemPlan, planSystemImport, planSystemLink, planSystemRelate, planSystemUnlink, planSystemUnrelate, } from "../src/system-management.js";
 import { coordinationStatus } from "../src/update-coordination.js";
@@ -161,15 +173,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];
@@ -414,7 +432,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
             ? ""
@@ -1274,6 +1292,8 @@ async function main() {
         const depth = invocation.options.depth;
         const retentionDays = invocation.options.retentionDays;
         const keepNewest = invocation.options.keepNewest;
+        const maxCount = invocation.options.maxCount;
+        const maxAllocatedBytes = invocation.options.maxBytes;
         let output;
         if (action === "list")
             output = listBackups(defaultRoots(), { depth });
@@ -1282,16 +1302,70 @@ async function main() {
                 depth,
                 retentionDays,
                 keepNewest,
+                maxCount,
+                maxAllocatedBytes,
                 apply: invocation.options.apply === true,
             });
         }
+        else if (action === "policy") {
+            output = defaultRoots().map((repository) => {
+                if (retentionAction === "status")
+                    return {
+                        repository,
+                        policy: resolveStoragePolicy(repository),
+                        inventory: inventoryStorage(repository),
+                    };
+                if (retentionAction !== "preview" && retentionAction !== "apply")
+                    throw new Error("knodin backups policy requires preview, apply, or status");
+                const changes = {
+                    apply: retentionAction === "apply",
+                };
+                if (maxCount !== undefined)
+                    changes.maxCount = maxCount;
+                if (maxAllocatedBytes !== undefined)
+                    changes.maxAllocatedBytes = maxAllocatedBytes;
+                if (invocation.options.reserveBytes !== undefined)
+                    changes.minFreeBytes = invocation.options.reserveBytes;
+                const mode = invocation.options.mode;
+                if (mode !== undefined) {
+                    changes.enabled = mode !== "disabled";
+                    changes.dryRun = mode === "preview";
+                }
+                const configured = configureStoragePolicy(repository, changes);
+                const maintenance = retentionAction === "apply" ? postOperationStorageMaintenance(repository) : null;
+                const candidateWarnings = [];
+                const candidatesRemoved = maintenance?.policy?.enabled && !maintenance.policy.dryRun
+                    ? sweepAbandonedCandidates(repository, {
+                        onDiagnostic: (warning) => {
+                            if (candidateWarnings.length < 8)
+                                candidateWarnings.push(warning.reason.slice(0, 512));
+                        },
+                    })
+                    : 0;
+                return {
+                    repository,
+                    ...configured,
+                    inventory: inventoryStorage(repository),
+                    cleanup: retentionAction === "apply"
+                        ? { ...maintenance, candidatesRemoved, candidateWarnings }
+                        : pruneBackups([repository], {
+                            ...configured.policy,
+                            depth: 0,
+                            includeRegistry: false,
+                            apply: false,
+                        }),
+                };
+            });
+        }
         else if (action === "retention" && retentionAction === "install") {
             output = installBackupRetention(roots, {
                 depth,
                 retentionDays,
                 keepNewest,
+                maxCount,
+                maxAllocatedBytes,
                 schedule: invocation.options.schedule,
-                dryRun: invocation.options.dryRun === true,
+                dryRun: invocation.options.dryRun,
                 launcher: runtimeCommand,
             });
         }
@@ -1374,10 +1448,19 @@ async function main() {
     const repo = resolved.repo;
     if (cmd !== "doctor") {
         try {
-            maybeRunOpportunisticRetention(repo);
+            const maintenance = maybeRunOpportunisticRetention(repo);
+            const issues = "issues" in maintenance
+                ? maintenance.issues
+                : "result" in maintenance && maintenance.result
+                    ? maintenance.result.skipped.map((entry) => entry.reason)
+                    : [];
+            if (issues?.length)
+                process.stderr.write(`knodin storage: ${issues.slice(0, 8).join("; ").slice(0, 4096)}\n`);
         }
-        catch {
-            // Best-effort cleanup must never make an ordinary command fail.
+        catch (error) {
+            // Cleanup remains nonfatal, but failures are not hidden or reported as
+            // reclaimed storage. Keep stdout/JSON framing untouched.
+            process.stderr.write(`knodin storage: ${String(error).slice(0, 512)}\n`);
         }
     }
     if (cmd === "agent-event" && !fs.existsSync(resolveDbPath(repo)))
@@ -1537,6 +1620,8 @@ async function main() {
         return attemptOpportunisticSharedRestore(repo, engine);
     };
     let result;
+    let finalizedClassConsumer = false;
+    let classConsumerErrorContract;
     let repairOutput;
     let repairWasPlan = false;
     let repairWasLifecycle = false;
@@ -1555,7 +1640,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": {
@@ -1830,10 +1915,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);
@@ -1848,7 +1934,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 {
@@ -2687,6 +2777,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({
@@ -2717,7 +2825,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");
@@ -2788,6 +2896,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",
@@ -2847,12 +3031,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;
@@ -3034,7 +3218,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:
@@ -3042,6 +3245,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`);
@@ -3050,9 +3255,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();
+}