knodin 0.6.0 → 0.7.3

package/README.md

@@ -147,9 +147,10 @@ knodin repair
 |---|---|
 | `knodin context` | Compact repository orientation and next-operation hint |
 | `knodin explain <symbol>` | Source, identity, callers, callees, and blast radius |
-| `knodin review` | Diff-aware risks, changed symbols, affected flows, and test gaps |
+| `knodin review` | Itemized graph impact, test gaps, centrality, and bounded Git-history evidence |
 | `knodin query …` | Impact, paths, callers, callees, tests, flows, and structured graph queries |
-| `knodin search <query>` | Hybrid semantic and keyword symbol search |
+| `knodin search <query>` | Explainable structural-first search with a bounded local embedding fallback |
+| `knodin index --scip <file>` | Opt in to a bounded local SCIP snapshot while preserving native and LSIF facts |
 | `knodin map` | Subsystems, communities, hubs, bridges, and boundaries |
 | `knodin pack …` | Deterministic source context under hard budgets |
 | `knodin compress …` | Bounded diagnostic output with recoverable local detail |
@@ -158,6 +159,7 @@ knodin repair
 | `knodin visualize` | Self-contained local graph visualization |
 | `knodin status --deep` | Index freshness, health, hooks, and integration status |
 | `knodin repair` | Repair or rebuild unhealthy local graph state |
+| `knodin diagnostics …` | Retain local failure evidence and create a redacted support bundle |
 
 Run `knodin --help` or read the [CLI reference](docs/CLI.md) for complete syntax.
 
@@ -186,7 +188,8 @@ repository, and lifecycle capabilities. See the [MCP guide](docs/MCP.md).
 Each checkout stores its graph and lifecycle state in `.knodin/`. Shared model
 files live in the user cache rather than being duplicated per repository.
 Source and graph data stay local. Telemetry is metadata-only, disabled by
-default, and never sent by knodin.
+default, and never sent by knodin. Troubleshooting diagnostics are also
+explicitly enabled, local-only, bounded, and never uploaded automatically.
 
 The optional `prs` command invokes the user's authenticated `gh` CLI. Network
 access may also occur when installing packages, downloading the configured
@@ -206,9 +209,29 @@ productivity percentage or superiority over every competing product.
 - [Competitive roadmap and limitations](roadmap/competitive-roadmap.md)
 - [Systems and relationships](docs/SYSTEMS-AND-RELATIONSHIPS.md)
 - [Command-output compression](docs/COMMAND-OUTPUT-COMPRESSION.md)
+- [Local troubleshooting diagnostics](docs/DIAGNOSTICS.md)
 
 ## Develop
 
+### Internal GHES mirror
+
+GitHub SaaS `knodin/knodin` is the authoritative review and release repository.
+The internal `github.docusignhq.com/Enterprise-Apps/knodin` repository is a
+read-only mirror for colleagues who need GHES access; work must not be opened
+or reviewed there.
+
+After a pull fast-forwards local `main`, Lefthook automatically fast-forwards
+the mirror when this maintainer-local remote exists:
+
+```bash
+git remote add ghes git@github.docusignhq.com:Enterprise-Apps/knodin.git
+```
+
+The hook silently no-ops off `main`, on CI, or without that remote. It never
+forces and never breaks the surrounding merge when GHES is unavailable. Run
+`npm run mirror:sync` for manual recovery. A divergence is reported for
+investigation instead of being overwritten.
+
 ```bash
 npm ci
 npm run build

package/dist/bin/cli.js

@@ -22,6 +22,7 @@ import { checkIndexed, extractPositionals, extractRepoFlag, parseReviewArgs, pla
 import { helpCommandPath, parseCliInvocation, renderCliHelp } from "../src/cli-model.js";
 import { buildKnodinContext } from "../src/context.js";
 import { exportContext, grepPackedArtifact, readPackedArtifact } from "../src/context-export.js";
+import { clearDiagnostics, collectDiagnostics, diagnosticsStatus, disableDiagnostics, enableDiagnostics, inspectDiagnosticsBundle, recordDiagnosticFailure, } from "../src/diagnostics.js";
 import { getDocSection, listDocTopics } from "../src/docs-sections.js";
 import { diagnoseInstallation } from "../src/doctor.js";
 import { createEngine, REPO_WIDE_QUERY_PATTERNS, } from "../src/engine/index.js";
@@ -31,13 +32,14 @@ import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../src/graph-
 import { createIndexActivityReporter } from "../src/index-activity.js";
 import { detectTrackedTeamIntegration, InitializationHealthError, initializeRepository, inspectRepositoryIntegrationStatus, readRepositoryIntegrationConfig, refreshFromGitEvent, } from "../src/init.js";
 import { createInitProgressRenderer } from "../src/init-progress.js";
-import { attachLifecycleHealth } from "../src/lifecycle-health.js";
+import { attachLifecycleHealth, attachRepairLifecycle } from "../src/lifecycle-health.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 { createRepairPlan, createRepairProgressRenderer, parseRepairCliArgs, resolveRepairProgressMode, serializeRepairJsonlRecord, } from "../src/repair-progress.js";
 import { runRepositoryInitializationProcess } from "../src/repository-init-process.js";
-import { discoverRepositories, formatRepositoryHuman, initializeRepositories, inventoryRepository, parseFleetInitArgs, parseRepositoryCommandArgs, searchRepositories, } from "../src/repository-management.js";
+import { detectRepositorySignals, discoverRepositories, formatRepositoryHuman, initializeRepositories, inventoryRepository, parseFleetInitArgs, parseRepositoryCommandArgs, repositorySignalInspectionLimit, searchRepositories, withRepositorySignals, } from "../src/repository-management.js";
 import { applyResponseBudget } from "../src/response-budget.js";
 import { enrichSystemRelationships, incorporateSystemQueryEvidence, indexModeForPath, loadSystemConfiguration, queryConfiguredSystem, systemMembershipsForPath, validateSystemHealth, } from "../src/system-config.js";
 import { applyTrustedUpdate, checkTrustedUpdate, claimScheduledUpdateCheck, detectUpdateInstallMethod, explainTrustedUpdate, releaseScheduledUpdateCheck, rollbackTrustedUpdate, trustedUpdateStatus, } from "../src/update-policy.js";
@@ -96,7 +98,8 @@ async function chooseInitScope(args, repo) {
 }
 function integrationAgents(repo) {
     const previous = readRepositoryIntegrationConfig(repo)?.agents ?? [];
-    return [...new Set([...detectSupportedAgents(), ...previous])];
+    const repositoryDetected = inspectRepositoryIntegrationStatus(repo)?.agents ?? [];
+    return [...new Set([...detectSupportedAgents(), ...previous, ...repositoryDetected])];
 }
 function formatInitHuman(result) {
     const agents = result.paths.scope === "cli-only"
@@ -117,6 +120,8 @@ function formatConfigureStatusHuman(result) {
         return "Agent integration: unconfigured.\nWarning: AI agents will not discover or invoke knodin automatically. Run `knodin configure --scope personal`.\n";
     if (result.scope === "cli-only")
         return "Agent integration: CLI-only.\nWarning: AI agents will not discover or invoke knodin automatically. Run `knodin configure --scope personal` or `--scope team` to enable them.\n";
+    if (result.scope === "repository-detected")
+        return `Agent integration: repository-detected${result.agents.length > 0 ? ` (${result.agents.join(", ")})` : ""}.\nLocal scope receipt: missing; managed repository integration is present.\n`;
     return `Agent integration: ${result.scope}${result.agents.length > 0 ? ` (${result.agents.join(", ")})` : ""}.\n`;
 }
 function formatConfigureHuman(result) {
@@ -133,7 +138,13 @@ function formatConfigureHuman(result) {
     const refresh = result.paths.lifecycleRefresh.state === "fresh"
         ? "fresh"
         : `still running (${result.paths.lifecycleRefresh.queuedEvents} queued event(s))`;
-    return `${result.message}\nAgent integration: ${result.paths.scope} — ${configured}${failures}\nGraph initialization: unchanged\nLifecycle refresh: ${refresh}\nNext: ${result.nextAction}\n`;
+    const filesystemMutationLines = result.paths.filesystemChanges
+        .map(({ path: changedPath, action }) => `\nFilesystem ${action}: ${changedPath}`)
+        .join("");
+    const externalOutcomeLines = result.paths.externalConfigurationOutcomes
+        .map(({ system, state }) => `\nExternal configuration outcome: ${system} ${state} (external mutation not locally observable)`)
+        .join("");
+    return `${result.message}\nAgent integration: ${result.paths.scope} — ${configured}${failures}${filesystemMutationLines}${externalOutcomeLines}\nGraph initialization: unchanged\nLifecycle refresh: ${refresh}\nNext: ${result.nextAction}\n`;
 }
 function formatRepairHuman(result) {
     const coverage = result.after.coverage;
@@ -141,6 +152,8 @@ function formatRepairHuman(result) {
         return `Repair paused: ${result.remaining ?? 0} file(s) remaining. Run \`knodin repair\` again to finish.\n`;
     }
     if (result.verified) {
+        if (result.lifecycle?.status === "degraded")
+            return `Repair verified: graph is healthy (${coverage.indexedFiles} indexed files, ${coverage.filesWithSymbols} files with symbols), but lifecycle routing is degraded. Run \`knodin init\`, then \`knodin status\`.\n`;
         return `Repair verified: graph is healthy (${coverage.indexedFiles} indexed files, ${coverage.filesWithSymbols} files with symbols).\n`;
     }
     return `Repair finished with remaining issues. Run \`knodin status --deep\` for details.\n`;
@@ -547,11 +560,15 @@ async function main() {
             const engine = createEngine();
             const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const repositories = [];
-            for (const record of discovery.repositories) {
-                repositories.push(await inventoryRepository(record, {
+            const discoveryRecords = plan.signals
+                ? discovery.repositories.slice(0, repositorySignalInspectionLimit(plan))
+                : discovery.repositories;
+            for (const record of discoveryRecords) {
+                const inventory = await inventoryRepository(record, {
                     status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
                     systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
-                }));
+                });
+                repositories.push(withRepositorySignals(inventory, plan.signals, plan.signals ? await detectRepositorySignals(record.path) : {}));
             }
             await engine.close();
             const output = {
@@ -561,7 +578,10 @@ async function main() {
                 ...discovery,
                 repositories,
             };
-            process.stdout.write(`${JSON.stringify(output, null, plan.json ? 0 : 2)}\n`);
+            const boundedOutput = plan.signals
+                ? applyResponseBudget(output, "repositories:discover", { bytes: plan.byteBudget, tokens: plan.tokenBudget, items: plan.itemBudget }, { bytes: 65_536, tokens: 16_384, items: 100 })
+                : output;
+            process.stdout.write(`${JSON.stringify(boundedOutput, null, plan.json ? 0 : 2)}\n`);
             process.exitCode = discovery.issues.length > 0 ? 1 : 0;
             return;
         }
@@ -856,6 +876,7 @@ async function main() {
             "--start",
             "--end",
             "--limit",
+            "--offset",
         ]);
         const positionals = rest.filter((argument, index) => !argument.startsWith("--") && !valueFlags.has(rest[index - 1]));
         const integer = (flag, fallback, minimum, maximum) => {
@@ -881,6 +902,7 @@ async function main() {
                     compressionResult = await diagnoseFailure(diagnosisEngine, repo, {
                         artifactId: artifactId ?? "",
                         maxDiagnostics: integer("--limit", 10, 1, 50),
+                        diagnosticOffset: integer("--offset", 0, 0, 1_000_000),
                         contextLines: integer("--context", 2, 0, 10),
                         contextByteBudget: integer("--max-output-bytes", 16_384, 256, 128 * 1024),
                     });
@@ -945,6 +967,12 @@ async function main() {
                     ? compressOutput(repo, { ...request, text: await readBoundedStdin(maxInputBytes) })
                     : compressOutputFile(repo, input, request);
         }
+        if (action === "diagnose" &&
+            (responseBudget.bytes !== undefined ||
+                responseBudget.tokens !== undefined ||
+                responseBudget.items !== undefined)) {
+            compressionResult = applyResponseBudget(compressionResult, "compress:diagnose", responseBudget, { bytes: 65_536, tokens: 16_384, items: 50 });
+        }
         if (jsonOutput)
             process.stdout.write(`${JSON.stringify(compressionResult)}\n`);
         else if (action === "diagnose" && !diagnosisUnavailable)
@@ -1120,7 +1148,7 @@ async function main() {
         }
         case "configure": {
             if (rawRest.includes("--status")) {
-                result = readRepositoryIntegrationConfig(repo) ?? {
+                result = inspectRepositoryIntegrationStatus(repo) ?? {
                     scope: "unconfigured",
                     agents: [],
                     warning: "AI agents are not configured by knodin. Run `knodin configure --scope personal`.",
@@ -1140,6 +1168,7 @@ async function main() {
                 scope,
                 agents,
                 allowTrackedTransition: true,
+                auditConfigurationChanges: true,
             });
             result = {
                 status: "success",
@@ -1162,6 +1191,7 @@ async function main() {
                 process.exit(1);
             }
             const clean = rest.includes("--clean") || rest.includes("--force");
+            const scipPath = selectorValue("--scip");
             const renderer = createInitRenderer("index");
             const activity = createIndexActivityReporter(plan.repo);
             activity.start();
@@ -1169,6 +1199,7 @@ async function main() {
             let indexResult;
             try {
                 indexResult = await engine.index(plan.repo, plan.files, clean, {
+                    scip: scipPath ? { path: scipPath } : undefined,
                     onProgress: (event) => {
                         activity.update(event);
                         renderer.onProgress(event);
@@ -1271,10 +1302,10 @@ async function main() {
             process.once("SIGINT", abortRepair);
             renderer.start();
             try {
-                result = await engine.repair(repo, {
+                result = attachRepairLifecycle(repo, await engine.repair(repo, {
                     signal: controller.signal,
                     onProgress: (event) => renderer.onProgress(event),
-                });
+                }));
             }
             finally {
                 process.removeListener("SIGINT", abortRepair);
@@ -1436,6 +1467,28 @@ async function main() {
             }
             break;
         }
+        case "evidence": {
+            const level = rest[0];
+            const file = rest[1];
+            if (!file || !["locate", "outline", "evidence", "expand"].includes(level))
+                throw new Error("knodin evidence requires locate|outline|evidence|expand <file>");
+            result = deliverProgressiveEvidence({
+                repo,
+                file,
+                level,
+                continuation: selectorValue("--continuation"),
+                baselineHash: selectorValue("--baseline-hash"),
+                baselineBytes: selectorValue("--baseline-bytes")
+                    ? Number(selectorValue("--baseline-bytes"))
+                    : undefined,
+                startLine: selectorValue("--start") ? Number(selectorValue("--start")) : undefined,
+                endLine: selectorValue("--end") ? Number(selectorValue("--end")) : undefined,
+                byteLimit: responseBudget.bytes,
+                tokenLimit: responseBudget.tokens,
+                itemLimit: responseBudget.items,
+            });
+            break;
+        }
         case "query": {
             const pattern = rest[0];
             const repoWide = REPO_WIDE_QUERY_PATTERNS.includes(pattern);
@@ -1634,6 +1687,61 @@ async function main() {
                 throw new Error("knodin telemetry requires status, report, export, or clear");
             break;
         }
+        case "diagnostics": {
+            const [action, bundlePath] = invocation.positionals;
+            const rawRetention = selectorValue("--retention-days");
+            const sinceOption = selectorValue("--since");
+            const outputOption = selectorValue("--output");
+            const retentionDays = rawRetention === undefined ? 14 : Number(rawRetention);
+            if (!Number.isInteger(retentionDays) || retentionDays < 1 || retentionDays > 365)
+                throw new Error("knodin diagnostics: --retention-days must be an integer from 1 to 365");
+            if (bundlePath && action !== "inspect")
+                throw new Error(`knodin diagnostics ${action}: unexpected bundle argument`);
+            if (rawRetention !== undefined && action !== "enable")
+                throw new Error(`knodin diagnostics ${action}: --retention-days applies only to enable`);
+            if (sinceOption !== undefined && action !== "collect")
+                throw new Error(`knodin diagnostics ${action}: --since applies only to collect`);
+            if (outputOption !== undefined && action !== "collect")
+                throw new Error(`knodin diagnostics ${action}: --output applies only to collect`);
+            if (action === "enable")
+                result = enableDiagnostics(repo, retentionDays);
+            else if (action === "status")
+                result = diagnosticsStatus(repo);
+            else if (action === "disable")
+                result = disableDiagnostics(repo);
+            else if (action === "clear")
+                result = clearDiagnostics(repo);
+            else if (action === "inspect") {
+                if (!bundlePath)
+                    throw new Error("knodin diagnostics inspect requires <bundle>");
+                result = inspectDiagnosticsBundle(repo, bundlePath);
+            }
+            else if (action === "collect") {
+                const since = sinceOption ?? "24h";
+                const match = /^(\d+)(h|d)$/.exec(since);
+                if (!match)
+                    throw new Error("knodin diagnostics collect: --since must be hours or days, such as 24h or 7d");
+                const sinceHours = Number(match[1]) * (match[2] === "d" ? 24 : 1);
+                const graph = attachLifecycleHealth(repo, await engine.status(repo, { audit: "deep" }));
+                const doctor = await diagnoseInstallation(repo, {
+                    currentVersion: KNODIN_VERSION,
+                    runtimeCommand: [...runtimeCommand, "serve"],
+                    graph,
+                });
+                result = collectDiagnostics(repo, {
+                    sinceHours,
+                    outputPath: outputOption,
+                    doctor,
+                    graph,
+                    telemetry: readTelemetryRecords(repo, undefined, Math.max(1, Math.ceil(sinceHours / 24))),
+                    knodinVersion: KNODIN_VERSION,
+                });
+            }
+            else {
+                throw new Error("knodin diagnostics requires enable, status, collect, inspect, clear, or disable");
+            }
+            break;
+        }
         case "context": {
             // knodin context "<task>" [base]
             const task = rest[0];
@@ -1699,6 +1807,54 @@ async function main() {
     process.exitCode = finalExitCode;
 }
 main().catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
+    const argv = process.argv.slice(2);
+    const repoIndex = argv.indexOf("--repo");
+    const equalsRepo = argv.find((argument) => argument.startsWith("--repo="));
+    const candidate = repoIndex >= 0 && argv[repoIndex + 1]
+        ? argv[repoIndex + 1]
+        : equalsRepo
+            ? equalsRepo.slice("--repo=".length)
+            : process.cwd();
+    const command = argv.find((argument, index) => {
+        if (argument.startsWith("-"))
+            return false;
+        return !(index > 0 && argv[index - 1] === "--repo") && argument !== candidate;
+    });
+    const knownCommands = new Set([
+        "init",
+        "configure",
+        "index",
+        "doctor",
+        "status",
+        "wait",
+        "repair",
+        "serve",
+        "context",
+        "explain",
+        "review",
+        "map",
+        "search",
+        "query",
+        "rename",
+        "wiki",
+        "visualize",
+        "pack",
+        "compress",
+        "prs",
+        "worktrees",
+        "telemetry",
+        "diagnostics",
+        "system",
+        "repos",
+        "update",
+    ]);
+    const diagnostic = recordDiagnosticFailure(candidate, {
+        surface: "cli",
+        operation: command && knownCommands.has(command) ? command : "unknown",
+        phase: "dispatch",
+        error: err,
+    });
+    const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
+    console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
     process.exit(1);
 });

package/dist/bin/launcher.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { tryStructuralFastPath } from "../src/structural-fast-path.js";
+const argv = process.argv.slice(2);
+const fast = tryStructuralFastPath(argv);
+if (!fast) {
+    const { tryPureCompressionFastPath } = await import("../src/pure-compression-cli.js");
+    if (!(await tryPureCompressionFastPath(argv)))
+        await import("./cli.js");
+}
+if (process.env.KNODIN_BENCH_PROCESS_UPTIME === "1")
+    process.stderr.write(`KNODIN_PROCESS_UPTIME_MS=${(process.uptime() * 1000).toFixed(3)}\n`);

package/dist/src/agent-integration.js

@@ -81,7 +81,9 @@ export function configurePersonalAgents(options) {
             (options.remove ? removed : configured).push(agent);
         }
         catch (error) {
-            // Removing a missing registration is already the desired state.
+            // Claude reports a missing local registration as a remove failure. Keep
+            // this backward-compatible result conservative at the presentation layer:
+            // it means removal was attempted, not that absence was verified.
             if (options.remove)
                 removed.push(agent);
             else

package/dist/src/cli-args.js

@@ -240,7 +240,14 @@ export function parseReviewArgs(args) {
     if (rawScope && !scopes.includes(rawScope)) {
         throw new Error(`invalid review scope: ${rawScope}`);
     }
-    const optionValues = new Set([...GLOBAL_VALUE_FLAGS, "--scope", "--from", "--to", "--files"]);
+    const optionValues = new Set([
+        ...GLOBAL_VALUE_FLAGS,
+        "--scope",
+        "--from",
+        "--to",
+        "--files",
+        "--scip",
+    ]);
     const positionals = args.filter((arg, index) => {
         if (arg.startsWith("--"))
             return false;

package/dist/src/cli-model.js

@@ -66,6 +66,14 @@ function addRepositoryCommands(program, capture) {
                 .option("--manifest <path>", "write or resume a portfolio manifest")
                 .option("--dry-run", "report actions without changing repositories");
         }
+        if (action === "discover") {
+            command
+                .option("--signals", "include bounded repository applicability signals")
+                .addOption(option("--items <count>", "bound returned repositories and signal arrays", "integer"))
+                .addOption(option("--bytes <count>", "bound serialized response bytes", "integer"))
+                .addOption(option("--tokens <count>", "bound estimated response tokens", "integer"))
+                .addHelpText("after", "\n--signals returns hookManager, markerFiles, sanitized remotes, ciProviders, agentConfigs, and aidevTrackReferenced when known; every returned repository has signals, including {}. Inspection uses fixed documented marker/hook allowlists, reads only bounded hook configuration, and performs no network, credential, or marker-content reads. Linked worktrees inspect their own checkout when --linked-worktrees include is selected. See docs/REPOSITORIES-AND-WORKTREES.md for omissions and limits.\n");
+        }
     }
     leaf(repos, "search <query>", "search selected repositories sequentially", capture)
         .addOption(option("--root <path>", "portfolio root", "collect"))
@@ -129,6 +137,12 @@ function addGraphCommands(program, capture) {
         .option("--no-verify", "skip post-apply typecheck");
 }
 function addArtifactCommands(program, capture) {
+    leaf(program, "evidence <level> <file>", "deliver progressive source evidence", capture)
+        .option("--continuation <handle>", "resume an exact prior response")
+        .option("--baseline-hash <sha256>", "complete baseline SHA-256")
+        .addOption(option("--baseline-bytes <count>", "complete baseline UTF-8 bytes", "integer"))
+        .addOption(option("--start <line>", "first source line", "integer"))
+        .addOption(option("--end <line>", "last source line", "integer"));
     const pack = program.command("pack").description("export bounded portable context");
     pack
         .argument("[input]")
@@ -173,6 +187,7 @@ function addArtifactCommands(program, capture) {
             .addOption(option("--max-output-bytes <count>", "hard output byte budget", "integer"))
             .addOption(option("--context <count>", "diagnostic context lines", "integer"))
             .addOption(option("--limit <count>", "diagnostic result limit", "integer"))
+            .addOption(option("--offset <count>", "resume retained diagnostics at offset", "integer"))
             .option("--raw", "return unredacted retained bytes");
     }
     leaf(compress, "delete <artifact>", "delete a retained output artifact", capture);
@@ -196,7 +211,8 @@ function createCliProgram(capture = () => { }) {
         .option("--status", "inspect configuration without changing it");
     leaf(program, "index [files...]", "index a repository or selected files", capture)
         .option("--clean", "rebuild selected index state")
-        .option("--force", "force clean indexing");
+        .option("--force", "force clean indexing")
+        .option("--scip <file>", "opt in to a bounded local SCIP protobuf import");
     leaf(program, "doctor", "diagnose installation, clients, hooks, graph, and updates", capture).option("--client <client>", "claude, codex, gemini, or antigravity");
     leaf(program, "status", "report graph, lifecycle, integration, and update state", capture)
         .option("--deep", "run a full graph audit")
@@ -250,6 +266,24 @@ function createCliProgram(capture = () => { }) {
         .option("--output <path>", "dashboard or evidence-bundle output path")
         .addOption(option("--retention-days <count>", "retention window in days", "integer"))
         .action((...values) => capture(values.at(-1)));
+    const diagnostics = program
+        .command("diagnostics")
+        .description("manage local troubleshooting diagnostics and support bundles")
+        .allowExcessArguments(false)
+        .addArgument(new Argument("<action>").choices([
+        "enable",
+        "status",
+        "collect",
+        "inspect",
+        "clear",
+        "disable",
+    ]))
+        .addArgument(new Argument("[bundle]"));
+    diagnostics
+        .addOption(option("--retention-days <count>", "local event retention in days", "integer"))
+        .option("--since <duration>", "collection window, such as 24h or 7d")
+        .option("--output <path>", "repository-contained .json.gz bundle path")
+        .action((...values) => capture(values.at(-1)));
     return program;
 }
 function flattenPositionals(values) {

package/dist/src/codeflow-replay.js

@@ -0,0 +1,80 @@
+export const EXPECTED_RELATIONSHIPS = [
+    "packages/api/route.ts->packages/auth/service.ts",
+    "packages/api/route.ts->packages/audit/store.ts",
+    "packages/auth/service.ts->packages/data/users.ts",
+];
+export function normalizeCodeFlowRelationships(connections) {
+    return connections.map((value) => {
+        const edge = value;
+        return {
+            // CodeFlow exports callee/definition as source and caller as target.
+            from: String(edge.target ?? ""),
+            to: String(edge.source ?? ""),
+            kind: typeof edge.kind === "string" ? edge.kind : null,
+            extractor: typeof edge.extractor === "string" ? edge.extractor : null,
+            confidence: edge.confidence === "exact" || edge.confidence === "heuristic" ? edge.confidence : null,
+            sourceFile: typeof edge.sourceFile === "string" ? edge.sourceFile : null,
+            sourceLine: typeof edge.sourceLine === "number" ? edge.sourceLine : null,
+            evidence: typeof edge.evidence === "string" ? edge.evidence : null,
+            raw: value,
+        };
+    });
+}
+export function scoreRelationships(relationships) {
+    const actual = new Set(relationships.map((edge) => `${edge.from}->${edge.to}`));
+    const expected = new Set(EXPECTED_RELATIONSHIPS);
+    const truePositives = [...expected].filter((edge) => actual.has(edge));
+    const falseNegatives = [...expected].filter((edge) => !actual.has(edge));
+    const falsePositives = [...actual].filter((edge) => !expected.has(edge));
+    const malformed = relationships.filter((edge) => !edge.from || !edge.to);
+    return {
+        truePositives,
+        falsePositives,
+        falseNegatives,
+        precision: actual.size === 0 ? 0 : truePositives.length / actual.size,
+        recall: truePositives.length / expected.size,
+        unsupportedEdgeRate: falseNegatives.length / expected.size,
+        malformedRelationships: malformed.length,
+    };
+}
+export function blastRadiusCompleteness(relationships) {
+    const origin = "packages/data/users.ts";
+    const expected = new Set(["packages/auth/service.ts", "packages/api/route.ts"]);
+    const adjacency = new Map();
+    for (const edge of relationships) {
+        if (!adjacency.has(edge.to))
+            adjacency.set(edge.to, new Set());
+        adjacency.get(edge.to)?.add(edge.from);
+    }
+    const found = new Set();
+    const queue = [origin];
+    while (queue.length) {
+        const current = queue.shift();
+        for (const dependent of adjacency.get(current) ?? []) {
+            if (dependent === origin || found.has(dependent))
+                continue;
+            found.add(dependent);
+            queue.push(dependent);
+        }
+    }
+    return {
+        origin,
+        expected: [...expected],
+        found: [...found].sort(),
+        missing: [...expected].filter((file) => !found.has(file)),
+        completeness: [...expected].filter((file) => found.has(file)).length / expected.size,
+    };
+}
+export function provenanceCoverage(relationships) {
+    const count = relationships.length;
+    const rate = (predicate) => count === 0 ? 0 : relationships.filter(predicate).length / count;
+    return {
+        relationships: count,
+        relationKind: rate((edge) => edge.kind !== null),
+        extractorIdentity: rate((edge) => edge.extractor !== null),
+        exactOrHeuristicConfidence: rate((edge) => edge.confidence !== null),
+        sourceFile: rate((edge) => edge.sourceFile !== null),
+        sourceLine: rate((edge) => edge.sourceLine !== null),
+        boundedSourceEvidence: rate((edge) => edge.evidence !== null),
+    };
+}

package/dist/src/competitive-cold-mcp.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { sampleOperation } from "./competitive-measurement.js";
+function textOf(value) {
+    return (value.content ?? [])
+        .filter((item) => item.type === "text")
+        .map((item) => item.text ?? "")
+        .join("\n");
+}
+/** Measure five cold calls, rebuilding the MCP process before every recorded call. */
+export async function measureColdMcp(command, args, cwd, side, clientName) {
+    let last;
+    let error;
+    const { measurement } = await sampleOperation(async () => {
+        const transport = new StdioClientTransport({ command, args, cwd, stderr: "pipe" });
+        const client = new Client({ name: clientName, version: "1" }, { capabilities: {} });
+        try {
+            await client.connect(transport);
+            last = await client.callTool({ name: side.tool, arguments: side.args });
+            error = undefined;
+        }
+        catch (cause) {
+            error = cause instanceof Error ? cause.message : String(cause);
+        }
+        finally {
+            await transport.close().catch(() => undefined);
+        }
+        return last;
+    }, { mode: "cold" });
+    const response = last ? textOf(last) : "";
+    return {
+        ok: !error && !last?.isError,
+        error,
+        ...measurement,
+        responseBytes: Buffer.byteLength(response),
+        responseSha256: createHash("sha256").update(response).digest("hex"),
+        response,
+    };
+}