knodin 0.7.5 → 0.8.2

package/dist/bin/cli.js

@@ -22,10 +22,11 @@ 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 { 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 { createEngine, REPO_WIDE_QUERY_PATTERNS, } from "../src/engine/index.js";
+import { resolveDbPath } from "../src/engine/state-paths.js";
 import { diagnoseFailure, } from "../src/failure-diagnosis.js";
 import { gitExecutable } from "../src/git-executable.js";
 import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../src/graph-query-health.js";
@@ -33,6 +34,7 @@ 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, attachRepairLifecycle } from "../src/lifecycle-health.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";
@@ -41,10 +43,10 @@ import { createRepairPlan, createRepairProgressRenderer, parseRepairCliArgs, res
 import { runRepositoryInitializationProcess } from "../src/repository-init-process.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 { configuredRepositoryInitMemoryLimitBytes, 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";
 import { KNODIN_VERSION } from "../src/version.js";
-import { writeVisualization } from "../src/visualization.js";
+import { writeVisualization, } from "../src/visualization.js";
 import { waitForFresh } from "../src/wait-for-fresh.js";
 import { inspectWorktrees, reconcileWorktrees, removeManagedWorktree, } from "../src/worktree-lifecycle.js";
 function explicitScope(args) {
@@ -102,11 +104,11 @@ function integrationAgents(repo) {
     return [...new Set([...detectSupportedAgents(), ...previous, ...repositoryDetected])];
 }
 function formatInitHuman(result) {
-    const agents = result.paths.scope === "cli-only"
-        ? "CLI-only — AI agents are not configured to discover knodin"
-        : result.paths.agentIntegration.configured.length > 0
-            ? `${result.paths.scope} — ${result.paths.agentIntegration.configured.join(", ")}`
-            : `${result.paths.scope} — no supported coding agents detected`;
+    let agents = `${result.paths.scope} — no supported coding agents detected`;
+    if (result.paths.scope === "cli-only")
+        agents = "CLI-only — AI agents are not configured to discover knodin";
+    else if (result.paths.agentIntegration.configured.length > 0)
+        agents = `${result.paths.scope} — ${result.paths.agentIntegration.configured.join(", ")}`;
     const failures = result.paths.agentIntegration.failed
         .map(({ agent, message }) => `\nAgent warning (${agent}): ${message}`)
         .join("");
@@ -174,8 +176,220 @@ function formatIndexVerificationError(result) {
     const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
     return `knodin index: requested work completed, but ${result.verification.issueCount.toLocaleString()} graph issue(s) remain.${detail} Run \`knodin repair\`.\n`;
 }
+/**
+ * The hooks/lifecycle line of `status`.
+ *
+ * A mirror has no hooks by design, so neither "installed" nor "degraded" is true
+ * of it: claiming they are "installed and executable" would describe a directory
+ * containing none, and reporting "degraded" would demand a `knodin init` that
+ * must never run there.
+ */
+function formatLifecycleLine(lifecycle, isMirror) {
+    if (!lifecycle)
+        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";
+    const issue = lifecycle.issues[0] ?? "refresh capability is not verified";
+    return `Lifecycle refresh: ${lifecycle.status}; ${issue}. Run \`knodin init\`.\n`;
+}
+/** Renders the top extensions of a tally as `.md 180, .yml 74, +3 more`. */
+function formatTally(counts, limit = 4) {
+    const entries = Object.entries(counts).sort((left, right) => right[1] - left[1]);
+    const shown = entries.slice(0, limit).map(([ext, count]) => `${ext} ${count}`);
+    const remaining = entries.length - shown.length;
+    if (remaining > 0)
+        shown.push(`+${remaining} more`);
+    return shown.join(", ");
+}
+/**
+ * One clause naming what the graph does not cover. Silence here would let a
+ * language gap read as an absence of facts, so this is appended to the coverage
+ * line whenever anything was skipped.
+ */
+function formatCoverageGaps(skipped) {
+    if (!skipped)
+        return "";
+    // A zero total is only reportable as "no gaps" when the tally was actually
+    // read. If it wasn't, staying silent would state full coverage on the
+    // strength of a measurement that never happened.
+    if (skipped.total === 0 && !skipped.unparsedUnknown)
+        return "";
+    const clauses = [];
+    const byExtension = formatTally(skipped.byExtension);
+    if (byExtension)
+        clauses.push(`not indexed: ${byExtension}`);
+    const unparsed = formatTally(skipped.unparsedByExtension);
+    if (unparsed)
+        clauses.push(`parsed but empty: ${unparsed}`);
+    if (skipped.unparsedUnknown)
+        clauses.push("parsed-but-empty tally unavailable — run a full index; this is a lower bound");
+    const count = skipped.unparsedUnknown ? `${skipped.total}+` : `${skipped.total}`;
+    return `. Not in graph: ${count} files (${clauses.join("; ")})`;
+}
+/**
+ * Recursive on-disk size of a directory.
+ *
+ * Reports unreadable entries rather than treating them as zero. The listing
+ * exists so acquired disk is auditable; a mirror that cannot be measured showing
+ * a confident `0 B` invites exactly the wrong conclusion — that it is empty and
+ * safe to remove — which is the same absence-as-fact error this whole feature
+ * is built to avoid.
+ */
+function directorySizeBytes(target) {
+    let bytes = 0;
+    let partial = false;
+    let entries;
+    try {
+        entries = fs.readdirSync(target, { withFileTypes: true });
+    }
+    catch {
+        return { bytes: 0, partial: true };
+    }
+    for (const entry of entries) {
+        const child = path.join(target, entry.name);
+        if (entry.isDirectory()) {
+            const nested = directorySizeBytes(child);
+            bytes += nested.bytes;
+            partial = partial || nested.partial;
+        }
+        else if (entry.isFile()) {
+            try {
+                bytes += fs.statSync(child).size;
+            }
+            catch {
+                partial = true;
+            }
+        }
+    }
+    return { bytes, partial };
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ["KiB", "MiB", "GiB"];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+}
+/**
+ * `knodin remote <add|list|remove|refresh>`.
+ *
+ * Mirrors are reported as snapshots, never as `fresh`: the clone is pinned to
+ * the commit it was fetched at, and nothing watches the remote for changes. Size
+ * and fetch time are shown for every mirror so acquired disk is auditable rather
+ * than silently accumulating.
+ */
+function writeMirrorListing() {
+    const mirrors = listMirrors();
+    if (mirrors.length === 0) {
+        process.stdout.write("No mirrors acquired. Add one with `knodin remote add <url>`.\n");
+        return;
+    }
+    let total = 0;
+    let anyPartial = false;
+    for (const mirror of mirrors) {
+        const size = directorySizeBytes(path.dirname(mirror.path));
+        total += size.bytes;
+        anyPartial = anyPartial || size.partial;
+        // "at least" rather than a bare figure when something was unreadable: a
+        // mirror reported as 0 B reads as empty, and the obvious next action on an
+        // empty mirror is to delete it.
+        const shown = size.partial ? `at least ${formatBytes(size.bytes)}` : formatBytes(size.bytes);
+        process.stdout.write(`${mirror.identity}  ${mirror.url}\n  snapshot ${mirror.sha.slice(0, 12)}, fetched ${mirror.fetchedAt}, ${shown}\n  ${mirror.path}\n`);
+    }
+    const totalShown = anyPartial ? `at least ${formatBytes(total)}` : formatBytes(total);
+    process.stdout.write(`${mirrors.length} mirror(s), ${totalShown} on disk. Remove one with \`knodin remote remove <identity>\`.\n`);
+}
+async function remoteAdd(url, options) {
+    const { record, alreadyPresent } = addMirror(url);
+    process.stdout.write(alreadyPresent
+        ? `Mirror already present: ${record.identity} (snapshot ${record.sha.slice(0, 12)}). Use \`knodin remote refresh ${record.identity}\` to update it.\n`
+        : `Acquired ${record.identity} at snapshot ${record.sha.slice(0, 12)} into ${record.path}\n`);
+    if (options.skipIndex || alreadyPresent)
+        return;
+    await indexMirror(record.path, options.deferSemantic);
+}
+async function remoteRefresh(identity, options) {
+    const record = refreshMirror(identity);
+    process.stdout.write(`Refreshed ${record.identity} to snapshot ${record.sha.slice(0, 12)} (${record.fetchedAt})\n`);
+    if (options.skipIndex)
+        return;
+    await indexMirror(record.path, options.deferSemantic);
+}
+async function runRemoteCommand(args) {
+    const [action, target] = args;
+    const options = {
+        skipIndex: args.includes("--no-index"),
+        deferSemantic: args.includes("--defer-semantic"),
+    };
+    if (action === "list")
+        return writeMirrorListing();
+    if (action === "remove") {
+        if (!target)
+            throw new Error("knodin remote remove requires an <identity>");
+        process.stdout.write(removeMirror(target) ? `Removed ${target}\n` : `No mirror named ${target}\n`);
+        return;
+    }
+    if (action === "add") {
+        if (!target)
+            throw new Error("knodin remote add requires a <url>");
+        return remoteAdd(target, options);
+    }
+    if (action === "refresh") {
+        if (!target)
+            throw new Error("knodin remote refresh requires an <identity>");
+        return remoteRefresh(target, options);
+    }
+    throw new Error("knodin remote <add|list|remove|refresh>");
+}
+/**
+ * Builds a mirror's graph structure-first, then fills embeddings.
+ *
+ * The embedding pass dominates indexing cost, so structural answers (`explain`,
+ * `callers_of`, blast radius) become available in a fraction of the total. The
+ * gap is reported rather than hidden: until embeddings land, `search` silently
+ * under-returns, so saying nothing here would hand back exactly the confident
+ * empty result this whole feature exists to avoid.
+ */
+async function indexMirror(source, deferSemantic) {
+    const engine = createEngine();
+    try {
+        await engine.index(source, undefined, true, { skipEmbeddings: true });
+        const structural = await engine.status(source, { audit: "deep" });
+        process.stdout.write(`Indexed ${structural.coverage.indexedFiles} file(s), ${structural.coverage.filesWithSymbols} with symbols${formatCoverageGaps(structural.coverage.skipped)}\n`);
+        process.stdout.write("Structural queries (explain, query, map) are ready now; semantic search is not.\n");
+        if (deferSemantic) {
+            process.stdout.write("Semantic coverage deferred. Run `knodin index --repo <mirror>` to build it; until then `search` will under-return.\n");
+            return;
+        }
+        process.stdout.write("Building semantic index...\n");
+        await engine.index(source, undefined, false);
+        const full = await engine.status(source, { audit: "deep" });
+        process.stdout.write(`Semantic coverage: ${full.semanticReadiness ?? "unknown"}\n`);
+    }
+    finally {
+        await engine.close();
+    }
+}
 function formatStatusHuman(result) {
-    const coverage = `${result.coverage.sourceFiles} source files, ${result.coverage.indexedFiles} indexed files, ${result.coverage.filesWithSymbols} files with symbols`;
+    // A mirror's `freshness` describes the graph against its local clone and can
+    // legitimately read `fresh`. Saying so without also saying the clone is a
+    // snapshot would imply knodin is tracking the remote, which it is not.
+    const mirrorNote = result.mirror
+        ? ` Mirror of ${result.mirror.url}: snapshot ${result.mirror.sha.slice(0, 12)}, fetched ${result.mirror.fetchedAt}; the remote is not watched.`
+        : "";
+    // Semantic search drops symbols that have no embedding, so an incomplete pass
+    // silently shortens results. Say so rather than let it read as "no matches".
+    const semanticNote = result.semanticReadiness && result.semanticReadiness !== "ready"
+        ? ` Semantic search coverage is ${result.semanticReadiness}: \`search\` will under-return until embedding completes (\`knodin index\`).`
+        : "";
+    const coverage = `${result.coverage.sourceFiles} source files, ${result.coverage.indexedFiles} indexed files, ${result.coverage.filesWithSymbols} files with symbols${formatCoverageGaps(result.coverage.skipped)}${mirrorNote}${semanticNote}`;
     if (result.status === "indexing" && result.activity) {
         const count = result.activity.phaseTotal === undefined
             ? ""
@@ -184,14 +398,14 @@ function formatStatusHuman(result) {
         return `Graph update in progress: ${result.activity.phase}${count} — ${result.activity.message} (${elapsed}s elapsed; ${coverage}).\n`;
     }
     const integration = result.integration;
+    const integrationAgents = integration && integration.agents.length > 0 ? ` (${integration.agents.join(", ")})` : "";
     const integrationLine = integration
-        ? `Agent integration: ${integration.scope}${integration.agents.length > 0 ? ` (${integration.agents.join(", ")})` : ""}.\n`
+        ? `Agent integration: ${integration.scope}${integrationAgents}.\n`
         : "Agent integration: unconfigured. AI agents will not discover knodin automatically; run `knodin configure --scope personal`.\n";
-    const lifecycleLine = result.lifecycle
-        ? result.lifecycle.status === "healthy"
-            ? "Hooks: installed and executable.\n"
-            : `Lifecycle refresh: ${result.lifecycle.status}; ${result.lifecycle.issues[0] ?? "refresh capability is not verified"}. Run \`knodin init\`.\n`
-        : "";
+    // Replaces main's inline form: a mirror installs no hooks by design, so the
+    // inline version reported "needs repair — run knodin init" on every mirror
+    // status call, an instruction that must never be followed there.
+    const lifecycleLine = formatLifecycleLine(result.lifecycle, result.mirror !== undefined);
     const head = (value) => value?.slice(0, 12) ?? "unknown";
     const distance = result.freshness.commitDistance === null
         ? ""
@@ -219,7 +433,8 @@ function humanLabel(key) {
 /** Render bounded CLI data for a terminal without turning it back into JSON. */
 function formatHumanValue(value, indent = "", label) {
     if (value === null || typeof value !== "object") {
-        return [`${indent}${label ? `${humanLabel(label)}: ` : ""}${String(value)}`];
+        const labelPrefix = label ? `${humanLabel(label)}: ` : "";
+        return [`${indent}${labelPrefix}${String(value)}`];
     }
     if (Array.isArray(value)) {
         if (value.length === 0)
@@ -245,7 +460,8 @@ function formatHumanValue(value, indent = "", label) {
     return lines;
 }
 function formatGenericHuman(cmd, result) {
-    return `${[`${humanLabel(cmd)}:`, ...formatHumanValue(result, "  ")].join("\n")}\n`;
+    const lines = [`${humanLabel(cmd)}:`, ...formatHumanValue(result, "  ")];
+    return `${lines.join("\n")}\n`;
 }
 function formatCompressionHuman(result) {
     const omitted = result.omittedRanges.reduce((total, range) => total + range.lineCount, 0);
@@ -318,6 +534,22 @@ async function readBoundedStdin(maxBytes) {
 }
 const CLEAR_TERMINAL_LINE = "\r\x1b[2K";
 const PROGRESS_WORKER_CLOSE_TIMEOUT_MS = 2_000;
+/** Resolve true when `closed` settles first, false when the deadline wins. */
+function raceWorkerClose(closed, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (closedCleanly) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(closedCleanly);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        timer.unref();
+        void closed.then(() => finish(true));
+    });
+}
 function createProgressWorkerRenderer(workerName, startMessage) {
     const extension = fileURLToPath(import.meta.url).endsWith(".ts") ? ".ts" : ".js";
     const workerPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), `../src/${workerName}${extension}`);
@@ -355,19 +587,7 @@ function createProgressWorkerRenderer(workerName, startMessage) {
         stop: async () => {
             send({ type: "stop" });
             worker.stdin.end();
-            const waitForClose = (timeoutMs) => new Promise((resolve) => {
-                let settled = false;
-                const finish = (closedCleanly) => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    clearTimeout(timer);
-                    resolve(closedCleanly);
-                };
-                const timer = setTimeout(() => finish(false), timeoutMs);
-                timer.unref();
-                void closed.then(() => finish(true));
-            });
+            const waitForClose = (timeoutMs) => raceWorkerClose(closed, timeoutMs);
             if (!(await waitForClose(PROGRESS_WORKER_CLOSE_TIMEOUT_MS))) {
                 // Rendering is observational. A wedged terminal renderer must never
                 // hold graph work or its completion summary hostage.
@@ -531,6 +751,7 @@ async function main() {
         }
         const engine = createEngine();
         const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
+        const memoryLimitBytes = configuredRepositoryInitMemoryLimitBytes(systemConfig);
         const summary = await initializeRepositories(plan.roots, {
             command: runtimeCommand,
             depth: plan.depth,
@@ -540,13 +761,21 @@ async function main() {
             status: (target) => engine.status(target),
             agents: detectSupportedAgents(),
             indexMode: (target) => indexModeForPath(systemConfig, target),
-            isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command: runtimeCommand }),
+            isolatedInitialize: (target) => runRepositoryInitializationProcess({
+                repository: target,
+                command: runtimeCommand,
+                memoryLimitBytes,
+            }),
         });
         await engine.close();
         process.stdout.write(plan.json ? `${JSON.stringify(summary)}\n` : formatRepositoryHuman(summary));
         process.exitCode = summary.exitCode;
         return;
     }
+    if (cmd === "remote") {
+        await runRemoteCommand(rawRest);
+        return;
+    }
     if (cmd === "repos") {
         if (repoFlag !== undefined) {
             throw new Error("knodin repos accepts discovery roots, not --repo");
@@ -587,6 +816,7 @@ async function main() {
         }
         if (plan.command === "init") {
             const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
+            const memoryLimitBytes = plan.memoryLimitBytes ?? configuredRepositoryInitMemoryLimitBytes(systemConfig);
             if (plan.dryRun) {
                 const summary = await initializeRepositories(plan.roots, {
                     command: runtimeCommand,
@@ -636,7 +866,11 @@ async function main() {
                 status: (target) => engine.status(target),
                 agents: detectSupportedAgents(),
                 indexMode: (target) => indexModeForPath(systemConfig, target),
-                isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command: runtimeCommand }),
+                isolatedInitialize: (target) => runRepositoryInitializationProcess({
+                    repository: target,
+                    command: runtimeCommand,
+                    memoryLimitBytes,
+                }),
             });
             const discovery = await discoverRepositories(plan.roots, {
                 depth: plan.depth,
@@ -1010,8 +1244,9 @@ async function main() {
     switch (cmd) {
         case "doctor": {
             const client = selectorValue("--client");
-            if (client !== undefined && !["claude", "codex", "gemini", "antigravity"].includes(client))
-                throw new Error("knodin doctor: --client must be claude, codex, gemini, or antigravity");
+            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");
             if (unsupported.length > 0)
                 throw new Error(`knodin doctor: unknown option ${unsupported[0]}`);
@@ -1158,7 +1393,7 @@ async function main() {
             const scope = explicitScope(rawRest);
             if (!scope)
                 throw new Error("knodin configure: missing --scope");
-            if (!fs.existsSync(path.join(repo, ".knodin", "db.sqlite"))) {
+            if (!fs.existsSync(resolveDbPath(repo))) {
                 throw new Error("knodin configure changes agent integration only; this repository is not initialized. Run `knodin init` first.");
             }
             const agents = scope === "team" ? [] : integrationAgents(repo);
@@ -1192,6 +1427,28 @@ async function main() {
             }
             const clean = rest.includes("--clean") || rest.includes("--force");
             const scipPath = selectorValue("--scip");
+            const sarifPath = selectorValue("--sarif");
+            // A bound the operator cannot move is just a failure, so every import
+            // ceiling is overridable. Reject junk here rather than letting NaN
+            // silently disable a limit downstream.
+            const importLimit = (flag) => {
+                const raw = selectorValue(flag);
+                if (raw === undefined)
+                    return undefined;
+                const parsed = Number(raw);
+                if (!Number.isInteger(parsed) || parsed <= 0) {
+                    process.stderr.write(`knodin index: ${flag} must be a positive integer\n`);
+                    process.exit(1);
+                }
+                return parsed;
+            };
+            const sarifMaxBytes = importLimit("--sarif-max-bytes");
+            const sarifMaxFindings = importLimit("--sarif-max-findings");
+            const sarifTimeoutMs = importLimit("--sarif-timeout-ms");
+            const scipMaxBytes = importLimit("--scip-max-bytes");
+            const scipMaxFiles = importLimit("--scip-max-files");
+            const scipMaxFacts = importLimit("--scip-max-facts");
+            const scipTimeoutMs = importLimit("--scip-timeout-ms");
             const renderer = createInitRenderer("index");
             const activity = createIndexActivityReporter(plan.repo);
             activity.start();
@@ -1199,7 +1456,25 @@ async function main() {
             let indexResult;
             try {
                 indexResult = await engine.index(plan.repo, plan.files, clean, {
-                    scip: scipPath ? { path: scipPath } : undefined,
+                    scip: scipPath
+                        ? {
+                            path: scipPath,
+                            // Only override a default when the operator actually asked.
+                            ...(scipMaxBytes !== undefined ? { maxBytes: scipMaxBytes } : {}),
+                            ...(scipMaxFiles !== undefined ? { maxFiles: scipMaxFiles } : {}),
+                            ...(scipMaxFacts !== undefined ? { maxFacts: scipMaxFacts } : {}),
+                            ...(scipTimeoutMs !== undefined ? { timeoutMs: scipTimeoutMs } : {}),
+                        }
+                        : undefined,
+                    sarif: sarifPath
+                        ? {
+                            path: sarifPath,
+                            // Only override a default when the operator actually asked.
+                            ...(sarifMaxBytes !== undefined ? { maxBytes: sarifMaxBytes } : {}),
+                            ...(sarifMaxFindings !== undefined ? { maxFindings: sarifMaxFindings } : {}),
+                            ...(sarifTimeoutMs !== undefined ? { timeoutMs: sarifTimeoutMs } : {}),
+                        }
+                        : undefined,
                     onProgress: (event) => {
                         activity.update(event);
                         renderer.onProgress(event);
@@ -1376,13 +1651,18 @@ async function main() {
         case "visualize": {
             const entry = rest.find((value, index) => !value.startsWith("--") && !rest[index - 1]?.startsWith("--"));
             const outputPath = selectorValue("--output");
-            if (!entry)
+            const scope = selectorValue("--scope");
+            const granularity = selectorValue("--granularity");
+            // Repo scope draws the whole graph, so it takes no entry selector.
+            if (!entry && scope !== "repo")
                 throw new Error("knodin visualize requires an <entry> selector");
             if (!outputPath)
                 throw new Error("knodin visualize requires --output <path.html>");
             result = await graphRead(() => writeVisualization(engine, repo, {
                 entry,
                 outputPath,
+                scope,
+                granularity,
                 depth: selectorValue("--depth") ? Number(selectorValue("--depth")) : undefined,
                 byteBudget: selectorValue("--max-bytes")
                     ? Number(selectorValue("--max-bytes"))
@@ -1405,16 +1685,17 @@ async function main() {
             const limit = Number(selectorValue("--limit") ?? positionalLimit ?? 5);
             if (!Number.isInteger(limit) || limit < 1)
                 throw new Error("knodin search: limit must be a positive integer");
+            let testScope = "all";
+            if (rest.includes("--tests-only"))
+                testScope = "test";
+            else if (rest.includes("--production-only"))
+                testScope = "production";
             result = await graphRead(() => engine.search(query, repo, limit, {
                 languages: selectorValue("--languages")?.split(",").filter(Boolean),
                 extensions: selectorValue("--extensions")?.split(",").filter(Boolean),
                 kinds: selectorValue("--kinds")?.split(",").filter(Boolean),
                 path: selectorValue("--path"),
-                testScope: rest.includes("--tests-only")
-                    ? "test"
-                    : rest.includes("--production-only")
-                        ? "production"
-                        : "all",
+                testScope,
                 includeSource: !rest.includes("--no-source"),
                 offset: selectorValue("--offset") ? Number(selectorValue("--offset")) : 0,
             }));
@@ -1692,6 +1973,7 @@ async function main() {
             const rawRetention = selectorValue("--retention-days");
             const sinceOption = selectorValue("--since");
             const outputOption = selectorValue("--output");
+            const previewId = selectorValue("--preview-id");
             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");
@@ -1699,10 +1981,12 @@ async function main() {
                 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 (sinceOption !== undefined && !["preview", "archive", "collect"].includes(action ?? ""))
+                throw new Error(`knodin diagnostics ${action}: --since applies only to preview or archive`);
+            if (outputOption !== undefined && !["archive", "collect"].includes(action ?? ""))
+                throw new Error(`knodin diagnostics ${action}: --output applies only to archive`);
+            if (previewId !== undefined && !["archive", "collect"].includes(action ?? ""))
+                throw new Error(`knodin diagnostics ${action}: --preview-id applies only to archive`);
             if (action === "enable")
                 result = enableDiagnostics(repo, retentionDays);
             else if (action === "status")
@@ -1716,29 +2000,45 @@ async function main() {
                     throw new Error("knodin diagnostics inspect requires <bundle>");
                 result = inspectDiagnosticsBundle(repo, bundlePath);
             }
-            else if (action === "collect") {
+            else if (["preview", "archive", "collect"].includes(action ?? "")) {
                 const since = sinceOption ?? "24h";
-                const match = /^(\d+)(h|d)$/.exec(since);
+                const match = /^(\d+)([hd])$/.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, {
+                let graph;
+                let doctor;
+                try {
+                    graph = attachLifecycleHealth(repo, await engine.status(repo, { audit: "deep" }));
+                }
+                catch {
+                    // Support evidence remains available with an explicit unavailable graph section.
+                }
+                if (graph) {
+                    try {
+                        doctor = await diagnoseInstallation(repo, {
+                            currentVersion: KNODIN_VERSION,
+                            runtimeCommand: [...runtimeCommand, "serve"],
+                            graph,
+                        });
+                    }
+                    catch {
+                        // Installation diagnosis is represented as unavailable in the manifest.
+                    }
+                }
+                const options = {
                     sinceHours,
-                    outputPath: outputOption,
                     doctor,
                     graph,
-                    telemetry: readTelemetryRecords(repo, undefined, Math.max(1, Math.ceil(sinceHours / 24))),
                     knodinVersion: KNODIN_VERSION,
-                });
+                };
+                result =
+                    action === "preview"
+                        ? persistDiagnosticsPreview(repo, options)
+                        : collectDiagnostics(repo, { ...options, outputPath: outputOption, previewId });
             }
             else {
-                throw new Error("knodin diagnostics requires enable, status, collect, inspect, clear, or disable");
+                throw new Error("knodin diagnostics requires enable, status, preview, archive, inspect, clear, or disable");
             }
             break;
         }
@@ -1806,15 +2106,19 @@ async function main() {
         : `${JSON.stringify(boundedResult)}\n`);
     process.exitCode = finalExitCode;
 }
-main().catch((err) => {
+try {
+    await main();
+}
+catch (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 explicitRepo = repoIndex >= 0 ? argv[repoIndex + 1] : undefined;
+    let candidate = process.cwd();
+    if (explicitRepo)
+        candidate = explicitRepo;
+    else if (equalsRepo)
+        candidate = equalsRepo.slice("--repo=".length);
     const command = argv.find((argument, index) => {
         if (argument.startsWith("-"))
             return false;
@@ -1846,6 +2150,7 @@ main().catch((err) => {
         "diagnostics",
         "system",
         "repos",
+        "remote",
         "update",
     ]);
     const diagnostic = recordDiagnosticFailure(candidate, {
@@ -1857,4 +2162,4 @@ main().catch((err) => {
     const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
     console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
     process.exit(1);
-});
+}