knodin 0.5.0

package/dist/bin/cli.js

@@ -0,0 +1,1704 @@
+#!/usr/bin/env node
+/**
+ * `knodin` CLI — the daily driver.
+ *
+ *   knodin explain <symbol> [minimal]   edit-ready source + direct call paths + blast radius
+ *   knodin review [base]      risk-scored context with explicit git diff scopes
+ *   knodin map                subsystems + confidence-tagged edges
+ *   knodin wiki [--force]     write .reckon/wiki/ (index.md + per-community pages)
+ *   knodin serve              run the MCP server on stdio
+ *
+ * The same engine backs both the CLI and the MCP server, so any assistant and
+ * a human at a terminal see identical results.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { detectSupportedAgents, parseInitScope, } from "../src/agent-integration.js";
+import { refreshExternalGraphArtifacts, writeArtifactRefreshRecord, } from "../src/artifact-refresh.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";
+import { exportContext, grepPackedArtifact, readPackedArtifact } from "../src/context-export.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 { diagnoseFailure, } from "../src/failure-diagnosis.js";
+import { gitExecutable } from "../src/git-executable.js";
+import { decorateGraphQueryResult, inspectGraphQueryHealth } from "../src/graph-query-health.js";
+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 { 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 { 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 { 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";
+import { KNODIN_VERSION } from "../src/version.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) {
+    const index = args.indexOf("--scope");
+    if (index >= 0) {
+        const value = args[index + 1];
+        if (!value)
+            throw new Error("knodin: --scope requires a value");
+        return parseInitScope(value);
+    }
+    const equals = args.find((argument) => argument.startsWith("--scope="));
+    return equals ? parseInitScope(equals.slice("--scope=".length)) : null;
+}
+async function chooseInitScope(args, repo) {
+    const selected = explicitScope(args);
+    if (selected)
+        return selected;
+    if (detectTrackedTeamIntegration(repo)) {
+        process.stderr.write("[init:scope] Detected tracked knodin team integration; preserving team scope\n");
+        return "team";
+    }
+    if (!process.stdin.isTTY || !process.stderr.isTTY)
+        return "personal";
+    const prompt = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        const answer = await prompt.question([
+            "How should knodin integrate with coding agents?",
+            "  1. Personal (recommended) — all detected agents; Git stays clean",
+            "  2. Team — create commit-ready shared configuration",
+            "  3. CLI-only — agents will not discover or invoke knodin automatically",
+            "Select [1]: ",
+        ].join("\n"));
+        if (!answer.trim() || answer.trim() === "1")
+            return "personal";
+        if (answer.trim() === "2")
+            return "team";
+        if (answer.trim() === "3") {
+            const confirmation = await prompt.question("CLI-only requires manual knodin commands. Continue? [y/N] ");
+            if (!/^y(?:es)?$/i.test(confirmation.trim()))
+                throw new Error("knodin init: CLI-only selection cancelled");
+            return "cli-only";
+        }
+        return parseInitScope(answer.trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
+function integrationAgents(repo) {
+    const previous = readRepositoryIntegrationConfig(repo)?.agents ?? [];
+    return [...new Set([...detectSupportedAgents(), ...previous])];
+}
+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`;
+    const failures = result.paths.agentIntegration.failed
+        .map(({ agent, message }) => `\nAgent warning (${agent}): ${message}`)
+        .join("");
+    const refresh = result.paths.lifecycleRefresh.state === "fresh"
+        ? "fresh"
+        : `still running (${result.paths.lifecycleRefresh.queuedEvents} queued event(s)); run \`knodin wait --fresh\``;
+    return `${result.message}\nGraph: ${result.paths.database}\nGit refresh: ${result.paths.gitHooks.length} lifecycle hooks installed; ${refresh}\nAgent integration: ${agents}${failures}\nBackground indexer: ${result.paths.backgroundIndexer}\n`;
+}
+function formatConfigureStatusHuman(result) {
+    if (result.scope === "unconfigured")
+        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";
+    return `Agent integration: ${result.scope}${result.agents.length > 0 ? ` (${result.agents.join(", ")})` : ""}.\n`;
+}
+function formatConfigureHuman(result) {
+    let configured = "none detected";
+    if (result.paths.agentIntegration.configured.length > 0) {
+        configured = result.paths.agentIntegration.configured.join(", ");
+    }
+    else if (result.paths.scope === "cli-only") {
+        configured = "none (CLI-only)";
+    }
+    const failures = result.paths.agentIntegration.failed
+        .map(({ agent, message }) => `\nAgent warning (${agent}): ${message}`)
+        .join("");
+    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`;
+}
+function formatRepairHuman(result) {
+    const coverage = result.after.coverage;
+    if (result.cancelled) {
+        return `Repair paused: ${result.remaining ?? 0} file(s) remaining. Run \`knodin repair\` again to finish.\n`;
+    }
+    if (result.verified) {
+        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`;
+}
+function formatIndexHuman(result) {
+    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.\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.\n`;
+}
+function formatIndexVerificationError(result) {
+    const firstIssue = result.verification.missing.files[0] ?? result.verification.missing.records[0];
+    const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
+    return `knodin index: requested work completed, but ${result.verification.issueCount.toLocaleString()} graph issue(s) remain.${detail} Run \`knodin repair\`.\n`;
+}
+function formatStatusHuman(result) {
+    const coverage = `${result.coverage.sourceFiles} source files, ${result.coverage.indexedFiles} indexed files, ${result.coverage.filesWithSymbols} files with symbols`;
+    if (result.status === "indexing" && result.activity) {
+        const count = result.activity.phaseTotal === undefined
+            ? ""
+            : ` ${result.activity.phaseCompleted}/${result.activity.phaseTotal}`;
+        const elapsed = Math.max(0, Math.floor((Date.now() - Date.parse(result.activity.startedAt)) / 1_000));
+        return `Graph update in progress: ${result.activity.phase}${count} — ${result.activity.message} (${elapsed}s elapsed; ${coverage}).\n`;
+    }
+    const integration = result.integration;
+    const integrationLine = integration
+        ? `Agent integration: ${integration.scope}${integration.agents.length > 0 ? ` (${integration.agents.join(", ")})` : ""}.\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`
+        : "";
+    const head = (value) => value?.slice(0, 12) ?? "unknown";
+    const distance = result.freshness.commitDistance === null
+        ? ""
+        : ` by ${result.freshness.commitDistance.toLocaleString()} commit(s)`;
+    const freshnessLine = `Freshness: ${result.freshness.state}; indexed ${head(result.freshness.indexedHead)}, ` +
+        `current ${head(result.freshness.currentHead)} (${result.freshness.commitRelation}${distance}); ` +
+        `${result.freshness.workingTree.pendingPaths ?? "unknown"} pending path(s).\n` +
+        `Last successful refresh: ${result.freshness.lastSuccessfulRefresh ?? "never"}.\n`;
+    if (result.status === "healthy")
+        return `Graph content is healthy: ${coverage} (knodin ${result.version}; ${result.verification.mode}).\n${freshnessLine}${lifecycleLine}${integrationLine}`;
+    if (result.status === "stale")
+        return `Graph content is intact but evidence is stale (${coverage}).\n${freshnessLine}${lifecycleLine}${integrationLine}Run \`knodin wait --fresh\` or issue a graph query to reconcile bounded drift.\n`;
+    const outstanding = result.missing.files.length + result.missing.records.length;
+    const firstIssue = result.missing.files[0] ?? result.missing.records[0];
+    const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
+    const repairCommand = result.lifecycle?.status === "degraded" &&
+        result.missing.records.every((record) => result.lifecycle?.issues.includes(record))
+        ? "Run `knodin init`."
+        : "Run `knodin repair`.";
+    return `Graph or lifecycle needs repair: ${outstanding} issue(s) found (${coverage}).${detail} ${repairCommand}\n${lifecycleLine}${integrationLine}`;
+}
+function humanLabel(key) {
+    return key.replace(/([a-z])([A-Z])/g, "$1 $2");
+}
+/** 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)}`];
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return label ? [] : [`${indent}(none)`];
+        const lines = label ? [`${indent}${humanLabel(label)}:`] : [];
+        for (const item of value) {
+            if (item === null || typeof item !== "object")
+                lines.push(`${indent}  - ${String(item)}`);
+            else
+                lines.push(...formatHumanValue(item, `${indent}  - `));
+        }
+        return lines;
+    }
+    const entries = Object.entries(value).filter(([key]) => key !== "responseBudget");
+    const lines = label ? [`${indent}${humanLabel(label)}:`] : [];
+    for (const [key, child] of entries) {
+        if (child === null || typeof child !== "object") {
+            lines.push(`${indent}${label ? "  " : ""}${humanLabel(key)}: ${String(child)}`);
+        }
+        else
+            lines.push(...formatHumanValue(child, `${indent}${label ? "  " : ""}`, key));
+    }
+    return lines;
+}
+function formatGenericHuman(cmd, result) {
+    return `${[`${humanLabel(cmd)}:`, ...formatHumanValue(result, "  ")].join("\n")}\n`;
+}
+function formatCompressionHuman(result) {
+    const omitted = result.omittedRanges.reduce((total, range) => total + range.lineCount, 0);
+    let fidelity = `Compressed output; ${omitted} line(s) omitted.`;
+    if (result.status === "insufficient-budget")
+        fidelity = `INSUFFICIENT BUDGET: ${result.fidelity.unpreservedSignals.length} detected signal line(s) are available only through retained drill-down.`;
+    else if (result.complete)
+        fidelity = "Complete output; nothing omitted.";
+    const artifact = result.artifact.retained
+        ? ` Retained artifact: ${result.artifact.id} (${result.artifact.path}).`
+        : " Raw retention disabled; omitted regions cannot be retrieved.";
+    const content = result.content ? `${result.content}\n` : "";
+    return (`${content}---\n${fidelity} ` +
+        `${result.output.lines}/${result.input.lines} lines, ${result.output.bytes}/${result.input.bytes} bytes; ` +
+        `exit=${result.exit.code ?? "unknown"}, signal=${result.exit.signal ?? "none"}.${artifact}\n`);
+}
+function formatCompressionReadHuman(result) {
+    const content = result.content ? `${result.content}\n` : "";
+    const redactionStatus = result.raw
+        ? "UNREDACTED raw view"
+        : `${result.secretRedactions} secret(s) redacted`;
+    return (`${content}---\nArtifact ${result.artifactId}, lines ${result.range.startLine}-${result.range.endLine}` +
+        ` of ${result.range.totalLines}; ${result.bytes}/${result.byteBudget} bytes; ` +
+        `${redactionStatus}.\n`);
+}
+function formatFailureRelations(label, relations) {
+    if (relations.length === 0)
+        return `${label}: none`;
+    const formatted = relations.map(({ symbol, file, line }) => {
+        const location = file ? ` (${file}:${line ?? "?"})` : "";
+        return `${symbol}${location}`;
+    });
+    return `${label}: ${formatted.join(", ")}`;
+}
+function formatFailureDiagnosisHuman(result) {
+    const lines = [
+        `Failure diagnosis: ${result.status}; ${result.diagnostics.length} resolved, ${result.unresolved.length} unresolved.`,
+        `Freshness: ${result.freshness.state}; indexed=${result.freshness.indexedHead ?? "unknown"}; current=${result.freshness.currentHead ?? "unknown"}.`,
+    ];
+    for (const diagnostic of result.diagnostics) {
+        const location = `${diagnostic.file}:${diagnostic.reference.line ?? "?"}`;
+        const identity = diagnostic.owner?.identity ? ` [${diagnostic.owner.identity}]` : "";
+        const owner = `${diagnostic.owner?.symbol ?? "no owning symbol"}${identity}`;
+        const packageDescription = diagnostic.package
+            ? `${diagnostic.package.name ?? "unnamed"} (${diagnostic.package.kind}, ${diagnostic.package.manifest})`
+            : "none";
+        lines.push("", `${location} -> ${owner}`, `Package: ${packageDescription}`, formatFailureRelations("Tests", diagnostic.tests), formatFailureRelations("Upstream", diagnostic.upstream), formatFailureRelations("Downstream", diagnostic.downstream));
+        const snippet = result.contextBundle.snippets.find(({ file }) => file === diagnostic.file);
+        if (snippet)
+            lines.push(snippet.content);
+    }
+    for (const unresolved of result.unresolved) {
+        const candidates = unresolved.candidates ? ` (${unresolved.candidates.join(", ")})` : "";
+        lines.push("", `Unresolved ${unresolved.reference.path}: ${unresolved.reason}${candidates}`);
+    }
+    lines.push("", ...result.limitations.map((limitation) => `Limitation: ${limitation}`));
+    return `${lines.join("\n")}\n`;
+}
+async function readBoundedStdin(maxBytes) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        bytes += buffer.byteLength;
+        if (bytes > maxBytes)
+            throw new Error(`knodin compress: input exceeded bounded retention limit of ${maxBytes} bytes`);
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf-8");
+}
+const CLEAR_TERMINAL_LINE = "\r\x1b[2K";
+const PROGRESS_WORKER_CLOSE_TIMEOUT_MS = 2_000;
+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}`);
+    const workerArgs = extension === ".ts" && path.basename(process.execPath).startsWith("node")
+        ? [...process.execArgv, workerPath]
+        : [workerPath];
+    const worker = spawn(process.execPath, workerArgs, {
+        stdio: ["pipe", "ignore", "inherit"],
+        env: { ...process.env, RECKON_FORCE_PROGRESS_TTY: "1" },
+    });
+    let failed = false;
+    const closed = new Promise((resolve) => {
+        worker.once("close", () => resolve());
+        worker.once("error", () => resolve());
+    });
+    worker.once("error", () => {
+        failed = true;
+    });
+    worker.stdin.once("error", () => {
+        failed = true;
+    });
+    const send = (message) => {
+        if (failed || worker.stdin.destroyed)
+            return;
+        try {
+            worker.stdin.write(`${JSON.stringify(message)}\n`);
+        }
+        catch {
+            failed = true;
+        }
+    };
+    return {
+        start: () => send(startMessage),
+        onProgress: (event) => send({ type: "progress", event }),
+        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));
+            });
+            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.
+                worker.kill("SIGKILL");
+                if (!(await waitForClose(500)))
+                    worker.unref();
+            }
+            process.stderr.write(CLEAR_TERMINAL_LINE);
+        },
+    };
+}
+function createInitRenderer(operation = "init") {
+    if (process.stderr.isTTY !== true) {
+        const renderer = createInitProgressRenderer({
+            stderr: process.stderr,
+            operation,
+        });
+        return {
+            start: () => renderer.start(),
+            onProgress: (event) => renderer.onProgress(event),
+            stop: async () => renderer.stop(),
+        };
+    }
+    return createProgressWorkerRenderer("init-progress-worker", {
+        type: "start",
+        operation,
+    });
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv[0] === "__repository-init-worker") {
+        if (argv.length !== 2 || !path.isAbsolute(argv[1]))
+            throw new Error("knodin internal repository init worker requires one absolute path");
+        const repository = await fs.promises.realpath(argv[1]);
+        const interval = setInterval(() => {
+            process.send?.({ type: "rss", rssBytes: process.memoryUsage().rss });
+        }, 50);
+        interval.unref();
+        process.send?.({ type: "rss", rssBytes: process.memoryUsage().rss });
+        const engine = createEngine();
+        try {
+            const systemConfig = loadSystemConfiguration(repository);
+            const summary = await initializeRepositories([repository], {
+                // A portfolio worker owns exactly one already-discovered worktree.
+                // Do not recursively initialize nested repositories inside the same
+                // process, which would evade the per-repository memory boundary.
+                depth: 0,
+                include: [repository],
+                command: resolveCliRuntimeCommand(process),
+                index: (target) => engine.index(target),
+                status: (target) => engine.status(target),
+                agents: detectSupportedAgents(),
+                indexMode: (target) => indexModeForPath(systemConfig, target),
+            });
+            const result = summary.results.find(({ repository: target }) => target === repository);
+            if (!result)
+                throw new Error("repository init worker produced no repository result");
+            process.send?.({ type: "rss", rssBytes: process.memoryUsage().rss });
+            process.send?.({ type: "result", result });
+            if (result.status === "failed")
+                process.exitCode = 1;
+        }
+        finally {
+            clearInterval(interval);
+            await engine.close();
+        }
+        return;
+    }
+    // Keep a normalized argv for compatibility dispatch while Commander remains
+    // the authoritative grammar, option parser, validator, and help source.
+    const { rest: cleaned } = extractRepoFlag(argv);
+    const [cmd, ...rawRest] = cleaned;
+    if (!cmd || cmd === "-h" || cmd === "--help") {
+        process.stdout.write(renderCliHelp([], process.stdout.isTTY ? process.stdout.columns : undefined));
+        return;
+    }
+    if (cmd === "-v" || cmd === "--version" || cmd === "version") {
+        process.stdout.write(`${KNODIN_VERSION}\n`);
+        return;
+    }
+    if (argv.some((argument) => argument === "-h" || argument === "--help")) {
+        process.stdout.write(renderCliHelp(helpCommandPath(argv), process.stdout.isTTY ? process.stdout.columns : undefined));
+        return;
+    }
+    const invocation = parseCliInvocation(argv);
+    const optionKey = (flag) => flag.slice(2).replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+    const selectorValue = (flag) => {
+        const value = invocation.options[optionKey(flag)];
+        return typeof value === "string" || typeof value === "number" ? String(value) : undefined;
+    };
+    const repoFlag = selectorValue("--repo");
+    const runtimeCommand = resolveCliRuntimeCommand(process);
+    // hook-refresh is an internal machine-to-machine command. Keep it JSON even
+    // when an older installed hook predates the explicit --json argument.
+    const jsonOutput = invocation.options.json === true || cmd === "hook-refresh";
+    // `--json` is a shared output flag. Repair owns its richer --json/--jsonl
+    // parser; all other commands receive their original arguments minus it.
+    const rest = cmd === "repair" ? rawRest : rawRest.filter((argument) => argument !== "--json");
+    const selector = {
+        identity: selectorValue("--identity"),
+        file: selectorValue("--file"),
+        kind: selectorValue("--kind"),
+        toIdentity: selectorValue("--to-identity"),
+        toFile: selectorValue("--to-file"),
+        toKind: selectorValue("--to-kind"),
+    };
+    const responseBudget = {
+        bytes: selectorValue("--bytes") ? Number(selectorValue("--bytes")) : undefined,
+        tokens: selectorValue("--tokens") ? Number(selectorValue("--tokens")) : undefined,
+        items: selectorValue("--items") ? Number(selectorValue("--items")) : undefined,
+    };
+    for (const [flag, value, minimum] of [
+        ["--bytes", responseBudget.bytes, 256],
+        ["--tokens", responseBudget.tokens, 64],
+        ["--items", responseBudget.items, 1],
+    ]) {
+        if (value !== undefined && (!Number.isInteger(value) || value < minimum))
+            throw new Error(`knodin: ${flag} must be an integer >= ${minimum}`);
+    }
+    if (cmd === "init") {
+        explicitScope(rawRest);
+        const unsupported = rawRest.filter((argument, index) => {
+            if (argument === "--json" || argument.startsWith("--scope="))
+                return false;
+            if (argument === "--scope" || rawRest[index - 1] === "--scope")
+                return false;
+            return true;
+        });
+        if (unsupported.length > 0)
+            throw new Error(`knodin init: unknown option: ${unsupported[0]}`);
+    }
+    if (cmd === "configure") {
+        const status = rawRest.includes("--status");
+        const scope = explicitScope(rawRest);
+        const unsupported = rawRest.filter((argument, index) => {
+            if (argument === "--json" || argument === "--status" || argument.startsWith("--scope="))
+                return false;
+            if (argument === "--scope" || rawRest[index - 1] === "--scope")
+                return false;
+            return true;
+        });
+        if (unsupported.length > 0)
+            throw new Error(`knodin configure: unknown option: ${unsupported[0]}`);
+        if (status && scope)
+            throw new Error("knodin configure: --status and --scope are mutually exclusive");
+        if (!status && !scope)
+            throw new Error("knodin configure requires --scope personal|team|cli-only or --status");
+    }
+    if (cmd === "serve") {
+        const { startServer } = await import("../src/server.js");
+        await startServer();
+        return;
+    }
+    if (cmd === "fleet") {
+        if (repoFlag !== undefined) {
+            throw new Error("knodin fleet init accepts discovery roots, not --repo");
+        }
+        const plan = parseFleetInitArgs(rawRest, process.cwd());
+        if (!plan.json) {
+            process.stderr.write("warning: `knodin fleet init` is deprecated; use `knodin repos init --linked-worktrees=skip|include` (alias retained for two minor releases)\n");
+        }
+        const engine = createEngine();
+        const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
+        const summary = await initializeRepositories(plan.roots, {
+            command: runtimeCommand,
+            depth: plan.depth,
+            dryRun: plan.dryRun,
+            worktrees: plan.worktrees,
+            index: (target) => engine.index(target),
+            status: (target) => engine.status(target),
+            agents: detectSupportedAgents(),
+            indexMode: (target) => indexModeForPath(systemConfig, target),
+            isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command: runtimeCommand }),
+        });
+        await engine.close();
+        process.stdout.write(plan.json ? `${JSON.stringify(summary)}\n` : formatRepositoryHuman(summary));
+        process.exitCode = summary.exitCode;
+        return;
+    }
+    if (cmd === "repos") {
+        if (repoFlag !== undefined) {
+            throw new Error("knodin repos accepts discovery roots, not --repo");
+        }
+        const plan = parseRepositoryCommandArgs(rawRest, process.cwd());
+        if (plan.command === "discover") {
+            const discovery = await discoverRepositories(plan.roots, {
+                depth: plan.depth,
+                linkedWorktrees: plan.linkedWorktrees,
+            });
+            const engine = createEngine();
+            const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
+            const repositories = [];
+            for (const record of discovery.repositories) {
+                repositories.push(await inventoryRepository(record, {
+                    status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
+                    systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                }));
+            }
+            await engine.close();
+            const output = {
+                schemaVersion: 1,
+                command: "discover",
+                linkedWorktrees: plan.linkedWorktrees,
+                ...discovery,
+                repositories,
+            };
+            process.stdout.write(`${JSON.stringify(output, null, plan.json ? 0 : 2)}\n`);
+            process.exitCode = discovery.issues.length > 0 ? 1 : 0;
+            return;
+        }
+        if (plan.command === "init") {
+            const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
+            if (plan.dryRun) {
+                const summary = await initializeRepositories(plan.roots, {
+                    command: runtimeCommand,
+                    depth: plan.depth,
+                    dryRun: true,
+                    worktrees: plan.linkedWorktrees,
+                    manifestPath: plan.manifestPath,
+                    include: plan.include,
+                    exclude: plan.exclude,
+                    index: async () => undefined,
+                    status: async () => {
+                        throw new Error("dry-run must not inspect graph databases");
+                    },
+                    agents: detectSupportedAgents(),
+                    indexMode: (target) => indexModeForPath(systemConfig, target),
+                });
+                const planned = summary.results.reduce((counts, result) => {
+                    const key = result.plannedStatus ?? result.status;
+                    counts[key] = (counts[key] ?? 0) + 1;
+                    return counts;
+                }, {});
+                const output = {
+                    schemaVersion: 1,
+                    command: "init",
+                    dryRun: true,
+                    graphDatabasesOpened: 0,
+                    modelsLoaded: 0,
+                    selectedRepositories: summary.results.filter(({ message }) => message.startsWith("dry-run:")).length,
+                    planned,
+                    ...summary,
+                    repositories: [],
+                };
+                process.stdout.write(plan.json ? `${JSON.stringify(output)}\n` : formatRepositoryHuman(summary));
+                process.exitCode = summary.exitCode;
+                return;
+            }
+            const engine = createEngine();
+            const summary = await initializeRepositories(plan.roots, {
+                command: runtimeCommand,
+                depth: plan.depth,
+                dryRun: false,
+                worktrees: plan.linkedWorktrees,
+                manifestPath: plan.manifestPath,
+                include: plan.include,
+                exclude: plan.exclude,
+                index: (target) => engine.index(target),
+                status: (target) => engine.status(target),
+                agents: detectSupportedAgents(),
+                indexMode: (target) => indexModeForPath(systemConfig, target),
+                isolatedInitialize: (target) => runRepositoryInitializationProcess({ repository: target, command: runtimeCommand }),
+            });
+            const discovery = await discoverRepositories(plan.roots, {
+                depth: plan.depth,
+                linkedWorktrees: plan.linkedWorktrees,
+            });
+            const repositories = [];
+            const selectedPaths = new Set(summary.results.map(({ repository }) => repository));
+            for (const record of discovery.repositories.filter(({ path }) => selectedPaths.has(path))) {
+                repositories.push(await inventoryRepository(record, {
+                    status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
+                    systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                }));
+            }
+            await engine.close();
+            const output = { schemaVersion: 1, command: "init", ...summary, repositories };
+            process.stdout.write(plan.json ? `${JSON.stringify(output)}\n` : formatRepositoryHuman(summary));
+            process.exitCode = summary.exitCode;
+            return;
+        }
+        if (plan.command === "search") {
+            const engine = createEngine();
+            const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
+            const output = await searchRepositories(plan.roots, plan.query ?? "", {
+                depth: plan.depth,
+                linkedWorktrees: plan.linkedWorktrees,
+                include: plan.include,
+                exclude: plan.exclude,
+                allowPartial: plan.allowPartial,
+                itemBudget: plan.itemBudget,
+                byteBudget: plan.byteBudget,
+                tokenBudget: plan.tokenBudget,
+                cursor: plan.cursor,
+                status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
+                search: (query, target, limit, offset) => engine.search(query, target, limit, {
+                    offset,
+                    includeSource: true,
+                    federate: false,
+                }),
+                systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+            });
+            await engine.close();
+            process.stdout.write(`${JSON.stringify(output, null, plan.json ? 0 : 2)}\n`);
+            process.exitCode = output.status === "unavailable" ? 1 : 0;
+            return;
+        }
+        const discovery = await discoverRepositories(plan.roots, {
+            depth: plan.depth,
+            linkedWorktrees: plan.linkedWorktrees,
+        });
+        const engine = createEngine();
+        const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
+        const repositories = [];
+        for (const repository of discovery.repositories) {
+            try {
+                if (plan.command === "doctor") {
+                    const graph = attachLifecycleHealth(repository.path, await engine.status(repository.path, { audit: "deep" }));
+                    const inventory = await inventoryRepository(repository, {
+                        status: async () => graph,
+                        systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                    });
+                    repositories.push({
+                        ...inventory,
+                        diagnosis: await diagnoseInstallation(repository.path, {
+                            currentVersion: KNODIN_VERSION,
+                            runtimeCommand,
+                            graph,
+                        }),
+                    });
+                }
+                else {
+                    repositories.push(await inventoryRepository(repository, {
+                        status: async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })),
+                        systemMemberships: (target) => systemMembershipsForPath(systemConfig, target),
+                    }));
+                }
+            }
+            catch (error) {
+                repositories.push({
+                    path: repository.path,
+                    status: "unknown",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        await engine.close();
+        const output = {
+            schemaVersion: 1,
+            command: plan.command,
+            linkedWorktrees: plan.linkedWorktrees,
+            repositories,
+            issues: discovery.issues,
+            emptyRoots: discovery.emptyRoots,
+            staleLinkedWorktrees: discovery.staleLinkedWorktrees,
+        };
+        process.stdout.write(`${JSON.stringify(output, null, plan.json ? 0 : 2)}\n`);
+        process.exitCode =
+            discovery.issues.length > 0 ||
+                repositories.some((entry) => ("health" in entry && entry.health !== "healthy") ||
+                    ("status" in entry && entry.status === "unknown"))
+                ? 1
+                : 0;
+        return;
+    }
+    if (cmd === "docs") {
+        if (repoFlag !== undefined)
+            throw new Error("knodin docs does not accept --repo");
+        const [topic, ...unsupported] = rawRest;
+        if (unsupported.length > 0)
+            throw new Error(`knodin docs: unknown argument ${unsupported[0]}`);
+        if (!topic || topic === "list") {
+            process.stdout.write(`${listDocTopics().join("\n")}\n`);
+            return;
+        }
+        const content = getDocSection(topic);
+        if (!content)
+            throw new Error(`knodin docs: unknown topic ${topic}`);
+        process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+        return;
+    }
+    if (cmd === "update") {
+        if (repoFlag !== undefined)
+            throw new Error("knodin update does not accept --repo");
+        const [action, ...unsupported] = rest;
+        if (!action || !["status", "check", "explain", "apply", "rollback"].includes(action)) {
+            throw new Error("knodin update requires status, check, explain, apply, or rollback");
+        }
+        if (unsupported.length > 0)
+            throw new Error(`knodin update ${action}: unknown argument ${unsupported[0]}`);
+        const method = detectUpdateInstallMethod(runtimeCommand);
+        const runManager = async (argv) => {
+            const [executable, ...arguments_] = argv;
+            if (!executable)
+                return { status: 1, stdout: "", stderr: "missing manager command" };
+            const outcome = spawnSync(executable, arguments_, {
+                encoding: "utf-8",
+                timeout: 120_000,
+                maxBuffer: 4 * 1_024 * 1_024,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            return {
+                status: outcome.status,
+                stdout: outcome.stdout ?? "",
+                stderr: outcome.stderr ?? outcome.error?.message ?? "",
+            };
+        };
+        const healthCheck = async () => {
+            const [executable, ...arguments_] = runtimeCommand;
+            if (!executable)
+                return false;
+            const outcome = spawnSync(executable, [...arguments_, "--version"], {
+                encoding: "utf-8",
+                timeout: 10_000,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            return outcome.status === 0 && /^\d+\.\d+\.\d+/.test(outcome.stdout.trim());
+        };
+        const options = {
+            currentVersion: KNODIN_VERSION,
+            installMethod: method,
+            env: process.env,
+            runManager,
+            healthCheck,
+        };
+        let output;
+        if (action === "status")
+            output = trustedUpdateStatus(options);
+        else if (action === "check") {
+            try {
+                output = await checkTrustedUpdate(options);
+            }
+            finally {
+                if (process.env.RECKON_UPDATE_BACKGROUND === "1")
+                    releaseScheduledUpdateCheck();
+            }
+        }
+        else if (action === "explain")
+            output = explainTrustedUpdate(options);
+        else if (action === "apply")
+            output = await applyTrustedUpdate(options);
+        else
+            output = await rollbackTrustedUpdate(options);
+        process.stdout.write(jsonOutput ? `${JSON.stringify(output)}\n` : formatGenericHuman("update", output));
+        return;
+    }
+    if (process.stdout.isTTY &&
+        claimScheduledUpdateCheck({
+            currentVersion: KNODIN_VERSION,
+            installMethod: detectUpdateInstallMethod(runtimeCommand),
+            env: process.env,
+        })) {
+        const [executable, ...arguments_] = runtimeCommand;
+        if (executable) {
+            const background = spawn(executable, [...arguments_, "update", "check", "--json"], {
+                detached: true,
+                stdio: "ignore",
+                env: { ...process.env, RECKON_UPDATE_BACKGROUND: "1" },
+            });
+            background.unref();
+        }
+    }
+    const resolved = resolveRepo(repoFlag, process.cwd());
+    if (!resolved.ok) {
+        process.stderr.write(`${resolved.error}\n`);
+        process.exit(1);
+    }
+    const repo = resolved.repo;
+    if (cmd === "doctor") {
+        const gitProbe = spawnSync(gitExecutable(), ["rev-parse", "--is-inside-work-tree"], {
+            cwd: repo,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        if (gitProbe.status !== 0 || gitProbe.stdout.trim() !== "true") {
+            const portfolio = {
+                schemaVersion: 1,
+                status: "portfolio-root",
+                path: repo,
+                graph: "not-inspected",
+                warning: "Target is not a Git worktree; treating a portfolio parent as one repository would be misleading.",
+                remediation: [`knodin repos doctor ${JSON.stringify(repo)}`],
+            };
+            process.stdout.write(jsonOutput ? `${JSON.stringify(portfolio)}\n` : formatGenericHuman("doctor", portfolio));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    if (cmd === "compress") {
+        const valueFlags = new Set([
+            "--strategy",
+            "--adapter",
+            "--lines",
+            "--max-output-bytes",
+            "--context",
+            "--exit-code",
+            "--signal",
+            "--max-input-bytes",
+            "--start",
+            "--end",
+            "--limit",
+        ]);
+        const positionals = rest.filter((argument, index) => !argument.startsWith("--") && !valueFlags.has(rest[index - 1]));
+        const integer = (flag, fallback, minimum, maximum) => {
+            const raw = selectorValue(flag);
+            const value = raw === undefined ? fallback : Number(raw);
+            if (!Number.isInteger(value) || value < minimum || value > maximum)
+                throw new Error(`knodin compress: ${flag} must be an integer from ${minimum} to ${maximum}`);
+            return value;
+        };
+        const action = positionals[0] === "read" || positionals[0] === "diagnose" || positionals[0] === "delete"
+            ? positionals[0]
+            : "create";
+        const artifactId = action === "create" ? undefined : positionals[1];
+        if (action !== "create" && !artifactId)
+            throw new Error(`knodin compress ${action} requires an artifact id`);
+        let compressionResult;
+        let diagnosisUnavailable = false;
+        if (action === "diagnose") {
+            const diagnosisEngine = createEngine();
+            try {
+                const health = await inspectGraphQueryHealth(repo, (target) => diagnosisEngine.status(target, { audit: "cached" }));
+                if (health.available) {
+                    compressionResult = await diagnoseFailure(diagnosisEngine, repo, {
+                        artifactId: artifactId ?? "",
+                        maxDiagnostics: integer("--limit", 10, 1, 50),
+                        contextLines: integer("--context", 2, 0, 10),
+                        contextByteBudget: integer("--max-output-bytes", 16_384, 256, 128 * 1024),
+                    });
+                }
+                else {
+                    compressionResult = health;
+                    diagnosisUnavailable = true;
+                    process.exitCode = 1;
+                }
+            }
+            finally {
+                await diagnosisEngine.close();
+            }
+        }
+        else if (action === "read") {
+            compressionResult = readOutputArtifact(repo, artifactId ?? "", {
+                startLine: integer("--start", 1, 1, Number.MAX_SAFE_INTEGER),
+                endLine: selectorValue("--end")
+                    ? integer("--end", 200, 1, Number.MAX_SAFE_INTEGER)
+                    : undefined,
+                byteBudget: integer("--max-output-bytes", 16_384, 256, 4 * 1024 * 1024),
+                raw: rest.includes("--raw"),
+            });
+        }
+        else if (action === "delete") {
+            compressionResult = deleteOutputArtifact(repo, artifactId ?? "");
+        }
+        else {
+            const strategy = selectorValue("--strategy") ?? "smart";
+            if (!["smart", "head-tail", "errors-only"].includes(strategy))
+                throw new Error("knodin compress: invalid --strategy");
+            const adapter = selectorValue("--adapter") ?? "auto";
+            if (![
+                "auto",
+                "generic",
+                "vitest",
+                "jest",
+                "pytest",
+                "go-test",
+                "maven",
+                "gradle",
+                "dotnet",
+                "cargo",
+            ].includes(adapter))
+                throw new Error("knodin compress: invalid --adapter");
+            const maxInputBytes = integer("--max-input-bytes", 16 * 1024 * 1024, 1, 64 * 1024 * 1024);
+            const request = {
+                exitCode: selectorValue("--exit-code") ? integer("--exit-code", 0, 0, 255) : undefined,
+                signal: selectorValue("--signal"),
+                strategy: strategy,
+                adapter: adapter,
+                lineBudget: integer("--lines", 200, 1, 10_000),
+                byteBudget: integer("--max-output-bytes", 16_384, 256, 4 * 1024 * 1024),
+                contextLines: integer("--context", 1, 0, 10),
+                maxInputBytes,
+                retain: !rest.includes("--no-retain"),
+                redactSecrets: !rest.includes("--no-redact"),
+            };
+            const input = positionals[0] === "create" ? (positionals[1] ?? "-") : (positionals[0] ?? "-");
+            compressionResult =
+                input === "-"
+                    ? compressOutput(repo, { ...request, text: await readBoundedStdin(maxInputBytes) })
+                    : compressOutputFile(repo, input, request);
+        }
+        if (jsonOutput)
+            process.stdout.write(`${JSON.stringify(compressionResult)}\n`);
+        else if (action === "diagnose" && !diagnosisUnavailable)
+            process.stdout.write(formatFailureDiagnosisHuman(compressionResult));
+        else if (action === "diagnose")
+            process.stdout.write(formatGenericHuman("compress diagnose", compressionResult));
+        else if (action === "read")
+            process.stdout.write(formatCompressionReadHuman(compressionResult));
+        else if (action === "create")
+            process.stdout.write(formatCompressionHuman(compressionResult));
+        else
+            process.stdout.write(formatGenericHuman("compress delete", compressionResult));
+        return;
+    }
+    const engine = createEngine();
+    let result;
+    let repairOutput;
+    let repairWasPlan = false;
+    let repairExitCode = 0;
+    let statusWasWatched = false;
+    const graphRead = async (run) => {
+        const health = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
+        if (!health.available) {
+            process.exitCode = 1;
+            return health;
+        }
+        const value = await run();
+        const verified = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
+        if (!verified.available) {
+            process.exitCode = 1;
+            return verified;
+        }
+        return decorateGraphQueryResult(value, verified.state, verified.graph.freshness);
+    };
+    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");
+            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]}`);
+            const diagnosis = await diagnoseInstallation(repo, {
+                currentVersion: KNODIN_VERSION,
+                runtimeCommand: [...runtimeCommand, "serve"],
+                graph: await engine.status(repo, { audit: "deep" }),
+                client,
+            });
+            const manager = diagnosis.manager.name;
+            diagnosis.update = await checkTrustedUpdate({
+                currentVersion: KNODIN_VERSION,
+                installMethod: ["npm", "mise", "volta", "nvm", "fnm", "asdf", "homebrew"].includes(manager ?? "")
+                    ? manager
+                    : "unknown",
+                env: process.env,
+            });
+            result = diagnosis;
+            break;
+        }
+        case "system": {
+            const allowPartial = rest.includes("--allow-partial");
+            const [action, systemId, ...unsupported] = rest.filter((argument) => argument !== "--allow-partial");
+            if (!action || !["list", "show", "validate", "query"].includes(action)) {
+                throw new Error("knodin system requires list, show, validate, or query");
+            }
+            if (allowPartial && action !== "query")
+                throw new Error(`knodin system ${action}: --allow-partial applies only to query`);
+            if (unsupported.length > 0)
+                throw new Error(`knodin system ${action}: unknown argument ${unsupported[0]}`);
+            const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
+            if (action === "list") {
+                if (systemId)
+                    throw new Error("knodin system list accepts no system id");
+                result = {
+                    schemaVersion: config.schemaVersion,
+                    systems: config.systems.map(({ id, components }) => ({
+                        id,
+                        componentCount: components.length,
+                    })),
+                };
+                break;
+            }
+            if (!systemId)
+                throw new Error(`knodin system ${action} requires <system-id>`);
+            const system = config.systems.find(({ id }) => id === systemId);
+            if (!system) {
+                result = {
+                    status: "not-found",
+                    systemId,
+                    available: config.systems.map(({ id }) => id),
+                };
+                process.exitCode = 1;
+                break;
+            }
+            if (action === "show") {
+                result = { status: "ok", system, repositories: config.repositories };
+            }
+            else if (action === "validate") {
+                const validation = await validateSystemHealth(config, systemId, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })), repo);
+                result = { systemId, ...validation };
+                if (!validation.valid)
+                    process.exitCode = 1;
+            }
+            else {
+                const validation = await validateSystemHealth(config, systemId, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })), repo);
+                result = queryConfiguredSystem(config, systemId, allowPartial, validation);
+                if (result.status === "unavailable")
+                    process.exitCode = 1;
+            }
+            break;
+        }
+        case "hook-refresh": {
+            const [kind, first, second] = rest;
+            let event;
+            if (kind === "commit")
+                event = { kind };
+            else if (kind === "checkout" && first && second) {
+                event = { kind, before: first, after: second };
+            }
+            else if (kind === "merge" && first && second) {
+                event = { kind, before: first, after: second };
+            }
+            else if (kind === "rewrite" && first) {
+                event = { kind, inputPath: first };
+            }
+            else {
+                throw new Error("knodin hook-refresh: invalid lifecycle event");
+            }
+            const indexed = await refreshFromGitEvent(repo, event, (target, files) => engine.index(target, files));
+            result = { indexed };
+            break;
+        }
+        case "init": {
+            const scope = await chooseInitScope(rawRest, repo);
+            const agents = scope === "team" ? [] : integrationAgents(repo);
+            const renderer = createInitRenderer();
+            const activity = createIndexActivityReporter(repo);
+            activity.start();
+            renderer.start();
+            let paths;
+            try {
+                try {
+                    paths = await initializeRepository(repo, {
+                        command: runtimeCommand,
+                        index: (target, options) => engine.index(target, undefined, false, options),
+                        scope,
+                        agents,
+                        onProgress: (event) => {
+                            activity.update(event);
+                            renderer.onProgress(event);
+                        },
+                    });
+                }
+                finally {
+                    await renderer.stop();
+                    activity.stop();
+                }
+            }
+            catch (error) {
+                if (!(error instanceof InitializationHealthError))
+                    throw error;
+                process.stderr.write(`${error.message}\n`);
+                await engine.close();
+                process.exitCode = 1;
+                return;
+            }
+            result = {
+                status: "success",
+                message: "knodin initialized successfully. Git lifecycle hooks configured.",
+                paths,
+            };
+            break;
+        }
+        case "configure": {
+            if (rawRest.includes("--status")) {
+                result = readRepositoryIntegrationConfig(repo) ?? {
+                    scope: "unconfigured",
+                    agents: [],
+                    warning: "AI agents are not configured by knodin. Run `knodin configure --scope personal`.",
+                };
+                break;
+            }
+            const scope = explicitScope(rawRest);
+            if (!scope)
+                throw new Error("knodin configure: missing --scope");
+            if (!fs.existsSync(path.join(repo, ".reckon", "db.sqlite"))) {
+                throw new Error("knodin configure changes agent integration only; this repository is not initialized. Run `knodin init` first.");
+            }
+            const agents = scope === "team" ? [] : integrationAgents(repo);
+            const paths = await initializeRepository(repo, {
+                command: runtimeCommand,
+                index: async () => undefined,
+                scope,
+                agents,
+                allowTrackedTransition: true,
+            });
+            result = {
+                status: "success",
+                message: `knodin agent integration changed to ${scope}.`,
+                graphInitialization: "unchanged",
+                nextAction: "run `knodin status` and reload the configured client",
+                paths,
+            };
+            break;
+        }
+        case "index": {
+            // Target the repo unambiguously and never report success for a no-op:
+            // a lone directory positional means "index this repo", file positionals
+            // must resolve inside the repo, and a run touching zero files fails loud.
+            const positionals = extractPositionals(rest);
+            const plan = planIndex(repoFlag, positionals, process.cwd());
+            if (!plan.ok) {
+                process.stderr.write(`${plan.error}\n`);
+                await engine.close();
+                process.exit(1);
+            }
+            const clean = rest.includes("--clean") || rest.includes("--force");
+            const renderer = createInitRenderer("index");
+            const activity = createIndexActivityReporter(plan.repo);
+            activity.start();
+            renderer.start();
+            let indexResult;
+            try {
+                indexResult = await engine.index(plan.repo, plan.files, clean, {
+                    onProgress: (event) => {
+                        activity.update(event);
+                        renderer.onProgress(event);
+                    },
+                });
+            }
+            finally {
+                await renderer.stop();
+                activity.stop();
+            }
+            result = indexResult;
+            const indexedCheck = checkIndexed([...indexResult.indexed, ...indexResult.unchanged], plan.repo);
+            if (!indexedCheck.ok) {
+                process.stderr.write(`${indexedCheck.error}\n`);
+                await engine.close();
+                process.exit(1);
+            }
+            if (indexResult.verification.status !== "healthy") {
+                process.stderr.write(formatIndexVerificationError(indexResult));
+                await engine.close();
+                process.exit(1);
+            }
+            break;
+        }
+        case "status": {
+            const snapshot = async () => ({
+                ...attachLifecycleHealth(repo, await engine.status(repo, {
+                    audit: rest.includes("--deep") ? "deep" : "cached",
+                })),
+                integration: inspectRepositoryIntegrationStatus(repo),
+                update: trustedUpdateStatus({
+                    currentVersion: KNODIN_VERSION,
+                    installMethod: detectUpdateInstallMethod(runtimeCommand),
+                    env: process.env,
+                }),
+            });
+            if (rest.includes("--watch")) {
+                const intervalRaw = selectorValue("--interval");
+                const intervalSeconds = intervalRaw === undefined ? 1 : Number(intervalRaw);
+                if (!Number.isFinite(intervalSeconds) || intervalSeconds < 0.1 || intervalSeconds > 60)
+                    throw new Error("knodin status: --interval must be between 0.1 and 60 seconds");
+                let watching = true;
+                const stop = () => {
+                    watching = false;
+                };
+                process.once("SIGINT", stop);
+                process.once("SIGTERM", stop);
+                while (watching) {
+                    const observed = await snapshot();
+                    process.stdout.write(`${JSON.stringify({ observedAt: new Date().toISOString(), ...observed })}\n`);
+                    await new Promise((resolve) => setTimeout(resolve, intervalSeconds * 1_000));
+                }
+                process.removeListener("SIGINT", stop);
+                process.removeListener("SIGTERM", stop);
+                statusWasWatched = true;
+                result = null;
+            }
+            else
+                result = await snapshot();
+            break;
+        }
+        case "wait": {
+            if (!rest.includes("--fresh"))
+                throw new Error("knodin wait requires --fresh");
+            const timeoutRaw = selectorValue("--timeout");
+            const timeoutSeconds = timeoutRaw === undefined ? 30 : Number(timeoutRaw);
+            if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0 || timeoutSeconds > 300)
+                throw new Error("knodin wait: --timeout must be between 0 and 300 seconds");
+            result = await waitForFresh(engine, repo, Math.round(timeoutSeconds * 1_000));
+            if (result.status !== "fresh")
+                process.exitCode = 1;
+            break;
+        }
+        case "repair": {
+            const options = parseRepairCliArgs(rest);
+            if (options.plan) {
+                result = createRepairPlan(await engine.status(repo, { audit: "deep" }));
+                repairOutput = options.output;
+                repairWasPlan = true;
+                break;
+            }
+            const progressMode = resolveRepairProgressMode(options, process.env, process.stderr.isTTY);
+            const renderer = progressMode === "tty"
+                ? createProgressWorkerRenderer("repair-progress-worker", { type: "start" })
+                : (() => {
+                    const direct = createRepairProgressRenderer({
+                        mode: progressMode,
+                        intervalMs: options.progressIntervalMs,
+                        stdout: process.stdout,
+                        stderr: process.stderr,
+                    });
+                    return {
+                        start: () => direct.start(),
+                        onProgress: (event) => direct.onProgress(event),
+                        stop: async () => direct.stop(),
+                    };
+                })();
+            const controller = new AbortController();
+            const abortRepair = () => controller.abort();
+            process.once("SIGINT", abortRepair);
+            renderer.start();
+            try {
+                result = await engine.repair(repo, {
+                    signal: controller.signal,
+                    onProgress: (event) => renderer.onProgress(event),
+                });
+            }
+            finally {
+                process.removeListener("SIGINT", abortRepair);
+                await renderer.stop();
+            }
+            repairOutput = options.output;
+            if (result.cancelled)
+                repairExitCode = 130;
+            break;
+        }
+        case "refresh-artifacts": {
+            const event = rest[0] ?? "code-change";
+            if (event !== "checkout" && event !== "merge" && event !== "code-change") {
+                process.stderr.write("knodin refresh-artifacts accepts checkout, merge, or code-change\n");
+                process.exit(1);
+            }
+            const refreshResult = refreshExternalGraphArtifacts(repo, event);
+            writeArtifactRefreshRecord(repo, refreshResult);
+            result = refreshResult;
+            break;
+        }
+        case "explain": {
+            const symbol = rest[0];
+            if (!symbol) {
+                process.stderr.write("knodin explain requires a <symbol>\n");
+                process.exit(1);
+            }
+            result = await graphRead(async () => {
+                const explained = await engine.explain(symbol, repo, rest[1] === "minimal" ? "minimal" : "standard", selector);
+                return rest[1] === "source" && !explained.ambiguity
+                    ? {
+                        mode: "source",
+                        identity: explained.identity,
+                        symbol: explained.symbol,
+                        source: explained.source,
+                        staleness: explained.staleness,
+                    }
+                    : explained;
+            });
+            break;
+        }
+        case "review": {
+            const plan = parseReviewArgs(rest);
+            result = await graphRead(() => engine.review(plan.base, repo, plan.detailLevel, plan.options));
+            break;
+        }
+        case "map":
+            result = await graphRead(() => engine.map(repo, rest.includes("--standard") ? "standard" : "minimal", {
+                topN: selectorValue("--top") ? Number(selectorValue("--top")) : undefined,
+                sort: selectorValue("--sort"),
+                relationKinds: selectorValue("--relations")?.split(",").filter(Boolean),
+            }));
+            break;
+        case "wiki": {
+            const health = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
+            if (!health.available) {
+                result = health;
+                process.exitCode = 1;
+                break;
+            }
+            const force = rest.includes("--force");
+            const summary = await engine.wiki(repo, force);
+            await engine.close();
+            process.stdout.write(`wrote ${summary.written.length} pages, skipped ${summary.skipped.length}\n`);
+            process.exitCode = 0;
+            return;
+        }
+        case "visualize": {
+            const entry = rest.find((value, index) => !value.startsWith("--") && !rest[index - 1]?.startsWith("--"));
+            const outputPath = selectorValue("--output");
+            if (!entry)
+                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,
+                depth: selectorValue("--depth") ? Number(selectorValue("--depth")) : undefined,
+                byteBudget: selectorValue("--max-bytes")
+                    ? Number(selectorValue("--max-bytes"))
+                    : undefined,
+                selector: {
+                    identity: selector.identity,
+                    file: selector.file,
+                    kind: selector.kind,
+                },
+            }));
+            break;
+        }
+        case "search": {
+            const query = rest[0];
+            if (!query) {
+                process.stderr.write("knodin search requires a <query>\n");
+                process.exit(1);
+            }
+            const positionalLimit = rest[1] && !rest[1].startsWith("--") ? rest[1] : undefined;
+            const limit = Number(selectorValue("--limit") ?? positionalLimit ?? 5);
+            if (!Number.isInteger(limit) || limit < 1)
+                throw new Error("knodin search: limit must be a positive integer");
+            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",
+                includeSource: !rest.includes("--no-source"),
+                offset: selectorValue("--offset") ? Number(selectorValue("--offset")) : 0,
+            }));
+            break;
+        }
+        case "pack": {
+            const action = rest[0];
+            const diffScope = selectorValue("--diff-scope");
+            if (diffScope && !["unstaged", "staged", "all", "compare"].includes(diffScope))
+                throw new Error("knodin pack: invalid --diff-scope");
+            if (action === "read") {
+                if (!rest[1])
+                    throw new Error("knodin pack read requires an artifact path");
+                result = readPackedArtifact(repo, rest[1], Number(selectorValue("--start") ?? 1), Number(selectorValue("--end") ?? 200), Number(selectorValue("--bytes") ?? 16_384));
+            }
+            else if (action === "grep") {
+                if (!rest[1] || !rest[2])
+                    throw new Error("knodin pack grep requires an artifact path and regex");
+                result = grepPackedArtifact(repo, rest[1], rest[2], selectorValue("--flags") ?? "", Number(selectorValue("--limit") ?? 100));
+            }
+            else {
+                const policies = {};
+                for (const assignment of selectorValue("--policy")?.split(",") ?? []) {
+                    const [glob, policy] = assignment.split("=");
+                    if (!glob || !["full", "summary", "structure-only"].includes(policy))
+                        throw new Error("knodin pack: invalid --policy assignment");
+                    policies[glob] = policy;
+                }
+                result = exportContext(repo, {
+                    format: selectorValue("--format") ?? "markdown",
+                    include: selectorValue("--include")?.split(",").filter(Boolean),
+                    exclude: selectorValue("--exclude")?.split(",").filter(Boolean),
+                    policies,
+                    alreadyPresent: selectorValue("--already-present")?.split(",").filter(Boolean),
+                    chatFiles: selectorValue("--chat-files")?.split(",").filter(Boolean),
+                    lineNumbers: rest.includes("--line-numbers"),
+                    includeTree: rest.includes("--tree"),
+                    byteBudget: Number(selectorValue("--bytes") ?? 65_536),
+                    tokenBudget: Number(selectorValue("--tokens") ?? 16_384),
+                    outputPath: selectorValue("--output"),
+                    git: diffScope || selectorValue("--log")
+                        ? {
+                            diffScope: diffScope,
+                            from: selectorValue("--from"),
+                            to: selectorValue("--to"),
+                            log: selectorValue("--log") ? Number(selectorValue("--log")) : undefined,
+                        }
+                        : undefined,
+                });
+            }
+            break;
+        }
+        case "query": {
+            const pattern = rest[0];
+            const repoWide = REPO_WIDE_QUERY_PATTERNS.includes(pattern);
+            // architecture_overview's only positional is the detail level (minimal|
+            // standard), not a target — keep its target empty so it's not misreported.
+            const target = pattern === "architecture_overview" ||
+                pattern === "import_cycles" ||
+                rest[1]?.startsWith("--")
+                ? ""
+                : (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|batch_outline|project_overview|shortest_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|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.exit(1);
+            }
+            const directionValue = selectorValue("--direction");
+            if (directionValue && !["upstream", "downstream", "both"].includes(directionValue)) {
+                process.stderr.write("knodin query: --direction must be upstream, downstream, or both\n");
+                process.exit(1);
+            }
+            const facetsValue = selectorValue("--facets")?.split(",").filter(Boolean);
+            if (facetsValue?.some((facet) => !["packages", "layers", "boundaries", "hotspots", "entryPoints", "languages"].includes(facet))) {
+                process.stderr.write("knodin query: --facets contains an unknown architecture facet\n");
+                process.exit(1);
+            }
+            if (!target && !repoWide) {
+                process.stderr.write(`knodin query ${pattern} requires a <target>\n`);
+                process.exit(1);
+            }
+            // shortest_path: `knodin query shortest_path <from> <to>`
+            // rename_preview: `knodin query rename_preview <old> <new>`
+            const to = pattern === "shortest_path" || pattern === "rename_preview" ? rest[2] : undefined;
+            if (pattern === "rename_preview" && !to) {
+                process.stderr.write("knodin query rename_preview requires <old> and <new>\n");
+                process.exit(1);
+            }
+            // traverse: `knodin query traverse <symbol> [--depth n | <n>]`. Depth is
+            // clamped (1-6) in the engine, so a raw value passes straight through.
+            let depth;
+            if (pattern === "traverse" || pattern === "feature_path" || pattern === "impact") {
+                const flagIdx = rest.indexOf("--depth");
+                const raw = flagIdx >= 0 ? rest[flagIdx + 1] : rest[2];
+                if (raw !== undefined && raw !== "" && Number.isFinite(Number(raw)))
+                    depth = Number(raw);
+            }
+            // architecture_overview: `knodin query architecture_overview [minimal|standard]`.
+            // Reuses the same detail knob as explain/review; minimal is the default.
+            let detailLevel;
+            if (pattern === "architecture_overview" && rest.includes("standard")) {
+                detailLevel = "standard";
+            }
+            const queryLimitRaw = selectorValue("--limit");
+            if (queryLimitRaw !== undefined &&
+                (!Number.isInteger(Number(queryLimitRaw)) || Number(queryLimitRaw) < 1)) {
+                process.stderr.write("knodin query: --limit must be a positive integer\n");
+                process.exit(1);
+            }
+            const queryHealth = pattern.startsWith("lsp_")
+                ? null
+                : await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
+            if (queryHealth && !queryHealth.available) {
+                result = queryHealth;
+                process.exitCode = 1;
+                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",
+                    direction: ["upstream", "downstream", "both"].includes(selectorValue("--direction") ?? "")
+                        ? selectorValue("--direction")
+                        : undefined,
+                    relationKinds: selectorValue("--relations")
+                        ?.split(",")
+                        .map((kind) => kind.trim())
+                        .filter(Boolean),
+                    minConfidence: selectorValue("--min-confidence")
+                        ? Number(selectorValue("--min-confidence"))
+                        : undefined,
+                    includeTests: !rest.includes("--exclude-tests"),
+                    includeDataFlow: rest.includes("--data-flow"),
+                }
+                : undefined, {
+                minLines: selectorValue("--min-lines") ? Number(selectorValue("--min-lines")) : undefined,
+                minComplexity: selectorValue("--min-complexity")
+                    ? Number(selectorValue("--min-complexity"))
+                    : undefined,
+                kinds: selectorValue("--kinds")?.split(",").filter(Boolean),
+                path: selectorValue("--path"),
+                direction: pattern === "traverse" &&
+                    ["upstream", "downstream", "both"].includes(selectorValue("--direction") ?? "")
+                    ? selectorValue("--direction")
+                    : undefined,
+                includeDataFlow: pattern === "traverse" ? rest.includes("--data-flow") : undefined,
+                flowVariable: pattern === "flow_analysis" ? selectorValue("--variable") : undefined,
+                architectureFacets: facetsValue,
+                topN: selectorValue("--top") ? Number(selectorValue("--top")) : undefined,
+                sort: selectorValue("--sort"),
+                relationKinds: pattern === "impact"
+                    ? undefined
+                    : selectorValue("--relations")?.split(",").filter(Boolean),
+                detailLevel,
+            });
+            if (pattern === "impact" || pattern === "dead_code") {
+                const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
+                result = incorporateSystemQueryEvidence(config, repo, pattern, target, result);
+            }
+            if (queryHealth?.available) {
+                const verifiedQueryHealth = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
+                if (!verifiedQueryHealth.available) {
+                    result = verifiedQueryHealth;
+                    process.exitCode = 1;
+                    break;
+                }
+                result = decorateGraphQueryResult(result, verifiedQueryHealth.state, verifiedQueryHealth.graph.freshness);
+            }
+            break;
+        }
+        case "rename": {
+            // knodin rename <old> <new> [--apply] [--no-verify]
+            const positional = rest.filter((a) => !a.startsWith("--"));
+            const oldName = positional[0];
+            const newName = positional[1];
+            const apply = rest.includes("--apply");
+            // Post-apply typecheck is on by default; --no-verify opts out.
+            const verify = !rest.includes("--no-verify");
+            if (!oldName || !newName) {
+                process.stderr.write("knodin rename requires <old> and <new>\n");
+                process.exit(1);
+            }
+            result = await graphRead(() => engine.rename(oldName, newName, repo, apply, verify, selector));
+            break;
+        }
+        case "prs": {
+            try {
+                const args = rest[0] === "audit" ? rest.slice(1) : rest;
+                const flag = (name) => {
+                    const index = args.indexOf(name);
+                    return index >= 0 ? args[index + 1] : undefined;
+                };
+                const state = flag("--state");
+                const limitValue = flag("--limit");
+                const limit = limitValue === undefined ? 50 : Number(limitValue);
+                if (!Number.isInteger(limit) || limit < 1)
+                    throw new Error("knodin prs: --limit must be a positive integer");
+                result = await auditPullRequests(repo, engine, {
+                    state,
+                    limit,
+                    branches: flag("--branches"),
+                    range: flag("--range"),
+                    base: flag("--base"),
+                    head: flag("--head"),
+                    expectedLogin: flag("--expected-login"),
+                });
+            }
+            catch (err) {
+                await engine.close();
+                process.stderr.write(`${err.message}\n`);
+                process.exit(1);
+            }
+            break;
+        }
+        case "worktrees": {
+            const action = rest[0] ?? "status";
+            if (action === "status") {
+                result = await inspectWorktrees(repo, (worktree) => engine.status(worktree, { audit: "cached" }));
+            }
+            else if (action === "reconcile") {
+                result = reconcileWorktrees(repo);
+            }
+            else if (action === "remove") {
+                const target = rest[1];
+                if (!target)
+                    throw new Error("knodin worktrees remove requires <path>");
+                result = removeManagedWorktree(repo, target, rest.includes("--dry-run"));
+            }
+            else {
+                throw new Error(`knodin worktrees: unknown action ${action}`);
+            }
+            break;
+        }
+        case "telemetry": {
+            const action = rest[0];
+            const rawRetention = selectorValue("--retention-days");
+            const retentionDays = rawRetention === undefined ? 30 : Number(rawRetention);
+            if (!Number.isInteger(retentionDays) || retentionDays < 1 || retentionDays > 3650)
+                throw new Error("knodin telemetry: --retention-days must be an integer from 1 to 3650");
+            const input = selectorValue("--input");
+            if (action === "status")
+                result = telemetryStatus(repo, input, retentionDays);
+            else if (action === "report")
+                result = writeTelemetryReport(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"));
+            else if (action === "export")
+                result = exportTelemetry(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"));
+            else if (action === "clear")
+                result = clearTelemetry(repo, input);
+            else
+                throw new Error("knodin telemetry requires status, report, export, or clear");
+            break;
+        }
+        case "context": {
+            // knodin context "<task>" [base]
+            const task = rest[0];
+            if (!task) {
+                process.stderr.write('knodin context requires a "<task>" description\n');
+                process.exit(1);
+            }
+            result = await graphRead(() => buildKnodinContext(engine, task, repo, rest[1]));
+            break;
+        }
+        default:
+            process.stderr.write(`unknown command: ${cmd}\n\n${renderCliHelp([], process.stderr.isTTY ? process.stderr.columns : undefined)}`);
+            process.exit(1);
+    }
+    await engine.close();
+    if (statusWasWatched)
+        return;
+    const boundedResult = applyResponseBudget(result, cmd, responseBudget, {
+        bytes: 65_536,
+        tokens: 16_384,
+        items: 100,
+    });
+    const finalExitCode = Math.max(Number(process.exitCode ?? 0), repairExitCode);
+    if (cmd === "init" && !jsonOutput) {
+        process.stdout.write(formatInitHuman(boundedResult));
+        process.exitCode = finalExitCode;
+        return;
+    }
+    if (cmd === "configure" && !jsonOutput && !rawRest.includes("--status")) {
+        process.stdout.write(formatConfigureHuman(boundedResult));
+        return;
+    }
+    if (cmd === "configure" && !jsonOutput && rawRest.includes("--status")) {
+        process.stdout.write(formatConfigureStatusHuman(boundedResult));
+        return;
+    }
+    if (cmd === "repair" && repairOutput === "human" && !repairWasPlan) {
+        process.stdout.write(formatRepairHuman(boundedResult));
+        process.exitCode = finalExitCode;
+        return;
+    }
+    if (cmd === "index" && !jsonOutput) {
+        // Human counts must describe the actual operation. The response budget is
+        // a JSON transport constraint and may truncate large `indexed` arrays.
+        process.stdout.write(formatIndexHuman(result));
+        process.exitCode = finalExitCode;
+        return;
+    }
+    if (cmd === "status" && !jsonOutput) {
+        process.stdout.write(formatStatusHuman(boundedResult));
+        process.exitCode = finalExitCode;
+        return;
+    }
+    if (!jsonOutput && repairOutput !== "jsonl") {
+        process.stdout.write(formatGenericHuman(cmd, boundedResult));
+        process.exitCode = finalExitCode;
+        return;
+    }
+    // Budget accounting is over the exact compact serialization written here.
+    process.stdout.write(repairOutput === "jsonl"
+        ? serializeRepairJsonlRecord("result", boundedResult)
+        : `${JSON.stringify(boundedResult)}\n`);
+    process.exitCode = finalExitCode;
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});