knodin 0.8.3 → 0.8.5

package/dist/bin/cli.js

@@ -16,6 +16,8 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { canUseSessionContextCache, parseClaudeHookPayload, readSessionContextCache, recordClaudeLifecycleEvent, renderSessionContext, SESSION_CONTEXT_BUDGET_LINE, sessionStartHookOutput, writeSessionContextCache, } from "../src/agent-events.js";
+import { inspectClaudeAgentHooks, installClaudeAgentHooks, uninstallClaudeAgentHooks, } from "../src/agent-hooks.js";
 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";
@@ -43,6 +45,7 @@ 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 { appendSessionEvent, clearSessionTelemetry, disableSessionTelemetry, enableSessionTelemetry, readSessionEvents, sessionTelemetryStatus, } from "../src/session-telemetry.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";
@@ -362,7 +365,7 @@ async function runRemoteCommand(args) {
  * empty result this whole feature exists to avoid.
  */
 async function indexMirror(source, deferSemantic) {
-    const engine = createEngine();
+    const engine = createEngine({ watcher: "disabled" });
     try {
         await engine.index(source, undefined, true, { skipEmbeddings: true });
         const structural = await engine.status(source, { audit: "deep" });
@@ -417,7 +420,8 @@ function formatStatusHuman(result) {
     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`;
+        `Last successful refresh: ${result.freshness.lastSuccessfulRefresh ?? "never"}.\n` +
+        `Freshness mechanism: ${result.freshnessMechanism.strategy}; watcher ${result.freshnessMechanism.watcher}${result.freshnessMechanism.diagnostic ? ` (${result.freshnessMechanism.diagnostic})` : ""}.\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")
@@ -631,7 +635,7 @@ async function main() {
         }, 50);
         interval.unref();
         process.send?.({ type: "rss", rssBytes: process.memoryUsage().rss });
-        const engine = createEngine();
+        const engine = createEngine({ watcher: "disabled" });
         try {
             const systemConfig = loadSystemConfiguration(repository);
             const summary = await initializeRepositories([repository], {
@@ -684,9 +688,13 @@ async function main() {
     };
     const repoFlag = selectorValue("--repo");
     const runtimeCommand = resolveCliRuntimeCommand(process);
-    // hook-refresh is an internal machine-to-machine command. Keep it JSON even
+    // Internal machine-to-machine commands stay JSON regardless of TTY state.
     // when an older installed hook predates the explicit --json argument.
-    const jsonOutput = invocation.options.json === true || cmd === "hook-refresh";
+    const jsonOutput = invocation.options.json === true ||
+        invocation.options.format === "json" ||
+        cmd === "hook-refresh" ||
+        cmd === "agent-event" ||
+        (cmd === "shared" && rawRest.includes("--jsonl"));
     // `--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");
@@ -753,7 +761,7 @@ async function main() {
         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 engine = createEngine({ watcher: "disabled" });
         const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
         const memoryLimitBytes = configuredRepositoryInitMemoryLimitBytes(systemConfig);
         const summary = await initializeRepositories(plan.roots, {
@@ -790,7 +798,7 @@ async function main() {
                 depth: plan.depth,
                 linkedWorktrees: plan.linkedWorktrees,
             });
-            const engine = createEngine();
+            const engine = createEngine({ watcher: "disabled" });
             const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const repositories = [];
             const discoveryRecords = plan.signals
@@ -857,7 +865,7 @@ async function main() {
                 process.exitCode = summary.exitCode;
                 return;
             }
-            const engine = createEngine();
+            const engine = createEngine({ watcher: "disabled" });
             const summary = await initializeRepositories(plan.roots, {
                 command: runtimeCommand,
                 depth: plan.depth,
@@ -895,7 +903,7 @@ async function main() {
             return;
         }
         if (plan.command === "search") {
-            const engine = createEngine();
+            const engine = createEngine({ watcher: "disabled" });
             const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const output = await searchRepositories(plan.roots, plan.query ?? "", {
                 depth: plan.depth,
@@ -924,7 +932,7 @@ async function main() {
             depth: plan.depth,
             linkedWorktrees: plan.linkedWorktrees,
         });
-        const engine = createEngine();
+        const engine = createEngine({ watcher: "disabled" });
         const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
         const repositories = [];
         for (const repository of discovery.repositories) {
@@ -1075,12 +1083,43 @@ async function main() {
             background.unref();
         }
     }
+    if (cmd === "agent-hooks") {
+        const action = invocation.commandPath[1];
+        const client = selectorValue("--client") ?? "claude";
+        if (client !== "claude")
+            throw new Error("knodin agent-hooks: only --client claude is supported");
+        if (invocation.options.dryRun === true && action !== "install")
+            throw new Error("knodin agent-hooks: --dry-run applies only to install");
+        let hookResult;
+        if (action === "install") {
+            const quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+            hookResult = installClaudeAgentHooks({
+                command: runtimeCommand.map(quote).join(" "),
+                dryRun: invocation.options.dryRun === true,
+            });
+        }
+        else if (action === "status")
+            hookResult = inspectClaudeAgentHooks();
+        else if (action === "uninstall")
+            hookResult = uninstallClaudeAgentHooks();
+        else
+            throw new Error("knodin agent-hooks requires install, status, or uninstall");
+        process.stdout.write(jsonOutput
+            ? `${JSON.stringify(hookResult)}\n`
+            : formatGenericHuman("agent-hooks", hookResult));
+        return;
+    }
     const resolved = resolveRepo(repoFlag, process.cwd());
     if (!resolved.ok) {
+        // Global agent hooks also run outside repositories and must fail open.
+        if (cmd === "agent-event")
+            return;
         process.stderr.write(`${resolved.error}\n`);
         process.exit(1);
     }
     const repo = resolved.repo;
+    if (cmd === "agent-event" && !fs.existsSync(resolveDbPath(repo)))
+        return;
     if (cmd === "doctor") {
         const gitProbe = spawnSync(gitExecutable(), ["rev-parse", "--is-inside-work-tree"], {
             cwd: repo,
@@ -1133,7 +1172,7 @@ async function main() {
         let compressionResult;
         let diagnosisUnavailable = false;
         if (action === "diagnose") {
-            const diagnosisEngine = createEngine();
+            const diagnosisEngine = createEngine({ watcher: "disabled" });
             try {
                 const health = await inspectGraphQueryHealth(repo, (target) => diagnosisEngine.status(target, { audit: "cached" }));
                 if (health.available) {
@@ -1225,12 +1264,19 @@ async function main() {
             process.stdout.write(formatGenericHuman("compress delete", compressionResult));
         return;
     }
-    const engine = createEngine();
+    const engine = createEngine({ watcher: "disabled" });
+    const opportunisticSharedRestore = async () => {
+        if (!fs.existsSync(path.join(repo, ".knodin", "shared-index.yaml")))
+            return null;
+        const { attemptOpportunisticSharedRestore } = await import("../src/shared-index/opportunistic.js");
+        return attemptOpportunisticSharedRestore(repo, engine);
+    };
     let result;
     let repairOutput;
     let repairWasPlan = false;
     let repairExitCode = 0;
     let statusWasWatched = false;
+    let agentEventOutput = false;
     const graphRead = async (run) => {
         const health = await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
         if (!health.available) {
@@ -1246,6 +1292,310 @@ async function main() {
         return decorateGraphQueryResult(value, verified.state, verified.graph.freshness);
     };
     switch (cmd) {
+        case "shared": {
+            const [cacheModule, compatibilityModule, configModule, manifestModule, provenanceModule, publisherModule, restoreModule, s3Module, selectionModule,] = await Promise.all([
+                import("../src/shared-index/cache.js"),
+                import("../src/shared-index/compatibility.js"),
+                import("../src/shared-index/config.js"),
+                import("../src/shared-index/manifest.js"),
+                import("../src/shared-index/provenance.js"),
+                import("../src/shared-index/publisher.js"),
+                import("../src/shared-index/restore.js"),
+                import("../src/shared-index/s3-client.js"),
+                import("../src/shared-index/selection.js"),
+            ]);
+            const { SharedIndexCache } = cacheModule;
+            const { currentSharedIndexCompatibility } = compatibilityModule;
+            const { loadSharedIndexConfig, publicKeyFingerprint, writeSharedIndexConfig } = configModule;
+            const { branchPointerKey } = manifestModule;
+            const { readSharedIndexProvenance, readSharedRestoreAttempt } = provenanceModule;
+            const { createSharedPublisherBundle, finalizeSharedPublisherBundle, guardPublisherPointer, prepareSharedPublisherDatabase, } = publisherModule;
+            const { restoreSharedIndex } = restoreModule;
+            const { createSharedObjectStore, SharedIndexError } = s3Module;
+            const { configuredBranchCandidates } = selectionModule;
+            const action = invocation.commandPath[1];
+            if (action === "configure") {
+                const existing = loadSharedIndexConfig(repo);
+                if (invocation.options.disable === true) {
+                    if (existing.state !== "configured")
+                        throw new Error("knodin shared configure --disable requires a valid existing configuration");
+                    writeSharedIndexConfig(repo, { ...existing.config, enabled: false });
+                    result = { state: "configured", config: { ...existing.config, enabled: false } };
+                    break;
+                }
+                const required = (name) => {
+                    const value = invocation.options[name];
+                    if (typeof value !== "string" || !value)
+                        throw new Error(`knodin shared configure requires --${name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`);
+                    return value;
+                };
+                const publicKeyPath = path.resolve(process.cwd(), required("publicKey"));
+                const publicKeyPem = fs.readFileSync(publicKeyPath, "utf8");
+                const branches = Array.isArray(invocation.options.branch)
+                    ? invocation.options.branch.filter((value) => typeof value === "string")
+                    : [];
+                if (branches.length === 0)
+                    throw new Error("knodin shared configure requires --branch");
+                const config = {
+                    schemaVersion: 1,
+                    enabled: true,
+                    registrationId: required("registrationId"),
+                    aws: { region: required("region"), bucket: required("bucket") },
+                    repository: {
+                        host: required("host"),
+                        owner: required("owner"),
+                        name: required("name"),
+                    },
+                    branches,
+                    signing: {
+                        algorithm: "RSASSA_PSS_SHA_256",
+                        keyId: required("keyId"),
+                        publicKeySha256: publicKeyFingerprint(publicKeyPem),
+                        publicKeyPem,
+                    },
+                };
+                const target = writeSharedIndexConfig(repo, config);
+                result = { state: "configured", path: target, config: loadSharedIndexConfig(repo) };
+                break;
+            }
+            if (action === "publisher-metadata") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared publisher-metadata requires valid reviewed configuration");
+                result = prepareSharedPublisherDatabase(repo);
+                break;
+            }
+            if (action === "publisher-bundle") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared publisher-bundle requires valid reviewed configuration");
+                const branch = invocation.positionals[0];
+                const output = invocation.options.output;
+                if (!branch || typeof output !== "string")
+                    throw new Error("knodin shared publisher-bundle requires <branch> --output <path>");
+                result = await createSharedPublisherBundle({
+                    repo,
+                    config: configuration.config,
+                    branch,
+                    outputDirectory: path.resolve(process.cwd(), output),
+                });
+                break;
+            }
+            if (action === "publisher-finalize") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared publisher-finalize requires valid reviewed configuration");
+                const bundlePath = invocation.positionals[0];
+                if (!bundlePath)
+                    throw new Error("knodin shared publisher-finalize requires <bundle>");
+                const bundle = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), bundlePath), "utf8"));
+                const pointer = finalizeSharedPublisherBundle({ config: configuration.config, bundle });
+                result = { bundle, pointer: JSON.parse(pointer.toString("utf8")) };
+                break;
+            }
+            if (action === "publisher-guard") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared publisher-guard requires valid reviewed configuration");
+                const [pointerPath, branch, commit] = invocation.positionals;
+                if (!pointerPath || !branch || !commit)
+                    throw new Error("knodin shared publisher-guard requires <pointer> <branch> <commit>");
+                guardPublisherPointer({
+                    repo,
+                    config: configuration.config,
+                    branch,
+                    newCommit: commit,
+                    existingPointerBytes: fs.readFileSync(path.resolve(process.cwd(), pointerPath)),
+                });
+                result = { allowed: true, branch, commit };
+                break;
+            }
+            if (action === "status") {
+                const configuration = loadSharedIndexConfig(repo);
+                const graph = await engine.status(repo, { audit: "cached" });
+                let credentialProbe = "not-requested";
+                if (invocation.options.probe === true) {
+                    if (configuration.state !== "configured" || !configuration.config.enabled) {
+                        credentialProbe = { state: "unavailable", category: "configuration" };
+                    }
+                    else {
+                        const store = createSharedObjectStore(configuration.config);
+                        try {
+                            const current = spawnSync(gitExecutable(), ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).stdout.trim();
+                            const branch = configuredBranchCandidates(configuration.config, current || undefined)[0];
+                            if (!store || !branch)
+                                throw new SharedIndexError("configuration", "shared-index probe has no configured local branch candidate");
+                            await store.head(branchPointerKey(configuration.config, branch));
+                            credentialProbe = { state: "available" };
+                        }
+                        catch (error) {
+                            credentialProbe = {
+                                state: "unavailable",
+                                category: error instanceof SharedIndexError ? error.category : "unavailable",
+                            };
+                        }
+                    }
+                }
+                result = {
+                    configuration,
+                    provenance: readSharedIndexProvenance(repo),
+                    lastRestoreAttempt: readSharedRestoreAttempt(repo),
+                    credentialProbe,
+                    freshnessMechanism: graph.freshnessMechanism,
+                };
+                break;
+            }
+            if (action === "pull") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared pull requires valid .knodin/shared-index.yaml");
+                const store = createSharedObjectStore(configuration.config);
+                if (!store)
+                    throw new Error("knodin shared pull: shared-index access is disabled");
+                const progressMode = invocation.options.jsonl === true
+                    ? "jsonl"
+                    : typeof invocation.options.progress === "string"
+                        ? invocation.options.progress
+                        : process.stderr.isTTY
+                            ? "plain"
+                            : "none";
+                if (!["plain", "jsonl", "none"].includes(progressMode))
+                    throw new Error("knodin shared pull: --progress must be plain, jsonl, or none");
+                let lastHumanPhase = "";
+                let lastHumanWrite = 0;
+                result = await restoreSharedIndex({
+                    repo,
+                    config: configuration.config,
+                    store,
+                    cache: new SharedIndexCache(),
+                    engine,
+                    clientCompatibility: currentSharedIndexCompatibility(),
+                    onProgress: (event) => {
+                        if (progressMode === "jsonl")
+                            process.stdout.write(`${JSON.stringify({ type: "progress", ...event })}\n`);
+                        else if (progressMode === "plain") {
+                            const now = Date.now();
+                            if (event.phase !== lastHumanPhase ||
+                                event.phase === "completed" ||
+                                event.phase === "failed" ||
+                                now - lastHumanWrite >= 125) {
+                                lastHumanPhase = event.phase;
+                                lastHumanWrite = now;
+                                const count = event.completed !== undefined && event.total !== undefined
+                                    ? ` ${event.completed.toLocaleString()}/${event.total.toLocaleString()}`
+                                    : "";
+                                const rate = event.ratePerSecond
+                                    ? ` · ${Math.round(event.ratePerSecond).toLocaleString()}/s`
+                                    : "";
+                                const eta = event.etaSeconds ? ` · ETA ${Math.ceil(event.etaSeconds)}s` : "";
+                                process.stderr.write(`[shared:${event.phase}]${count}${rate}${eta} ${event.message}\n`);
+                            }
+                        }
+                    },
+                });
+                if (!result.restored)
+                    repairExitCode = 1;
+                break;
+            }
+            throw new Error("knodin shared: unknown action");
+        }
+        case "agent-event": {
+            agentEventOutput = true;
+            const event = invocation.positionals[0];
+            if (!event)
+                throw new Error("knodin agent-event requires an event");
+            let payload;
+            try {
+                payload = parseClaudeHookPayload(await readBoundedStdin(65_536));
+            }
+            catch {
+                result = null;
+                break;
+            }
+            if (event !== "session-start") {
+                try {
+                    recordClaudeLifecycleEvent(repo, event, payload);
+                }
+                catch {
+                    // Optional telemetry must never interrupt the agent.
+                }
+                result = null;
+                break;
+            }
+            const startedAt = performance.now();
+            let status;
+            try {
+                status = await engine.status(repo, { audit: "cached" });
+            }
+            catch {
+                if (payload.session_id)
+                    try {
+                        appendSessionEvent(repo, {
+                            event: "session_start",
+                            sessionId: payload.session_id,
+                            context: "unavailable",
+                            freshness: "unavailable",
+                            latencyMs: Math.round((performance.now() - startedAt) * 100) / 100,
+                            cacheHit: false,
+                        });
+                    }
+                    catch {
+                        // Best-effort local recording remains fail-open.
+                    }
+                result = sessionStartHookOutput(`## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status before relying on graph evidence.`);
+                break;
+            }
+            const freshness = status.freshness?.state ?? "unknown";
+            const cacheKey = JSON.stringify({
+                schemaVersion: 1,
+                head: status.freshness?.currentHead,
+                fingerprint: status.freshness?.workingTree?.indexedFingerprint,
+                generation: status.indexGeneration,
+                budgets: [600, 8192, 12],
+            });
+            const cacheEligible = canUseSessionContextCache(status.status, freshness);
+            let text = cacheEligible ? readSessionContextCache(repo, cacheKey) : null;
+            let cacheHit = text !== null;
+            let contextState = "delivered";
+            if (!cacheEligible) {
+                contextState = "degraded";
+                text = `## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nGraph evidence is ${freshness}. Run knodin status and follow its repair or reindex guidance before relying on graph evidence.`;
+            }
+            else if (!text) {
+                cacheHit = false;
+                try {
+                    const context = await buildKnodinContext(engine, "Orient this coding session", repo, undefined, []);
+                    text = renderSessionContext(context, freshness);
+                    writeSessionContextCache(repo, cacheKey, text);
+                }
+                catch {
+                    contextState = "unavailable";
+                    text = `## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status, then call the connected knodin context operation when needed.`;
+                }
+            }
+            if (payload.session_id)
+                try {
+                    appendSessionEvent(repo, {
+                        event: "session_start",
+                        sessionId: payload.session_id,
+                        context: contextState,
+                        freshness: freshness === "fresh"
+                            ? "fresh"
+                            : status.status === "repair-needed"
+                                ? "repair-needed"
+                                : freshness === "unknown"
+                                    ? "unavailable"
+                                    : "stale",
+                        latencyMs: Math.round((performance.now() - startedAt) * 100) / 100,
+                        cacheHit,
+                    });
+                }
+                catch {
+                    // Best-effort local recording remains fail-open.
+                }
+            result = sessionStartHookOutput(text);
+            break;
+        }
         case "doctor": {
             const client = selectorValue("--client");
             if (client !== undefined &&
@@ -1340,8 +1690,11 @@ async function main() {
             else {
                 throw new Error("knodin hook-refresh: invalid lifecycle event");
             }
-            const indexed = await refreshFromGitEvent(repo, event, (target, files) => engine.index(target, files));
-            result = { indexed };
+            const shared = await opportunisticSharedRestore();
+            const indexed = shared?.restored
+                ? []
+                : await refreshFromGitEvent(repo, event, (target, files) => engine.index(target, files));
+            result = { indexed, ...(shared ? { sharedRestore: shared } : {}) };
             break;
         }
         case "init": {
@@ -1354,6 +1707,11 @@ async function main() {
             let paths;
             try {
                 try {
+                    if (!fs.existsSync(resolveDbPath(repo))) {
+                        const shared = await opportunisticSharedRestore();
+                        if (shared?.restored)
+                            process.stderr.write("[init:shared] Restored and verified shared snapshot\n");
+                    }
                     paths = await initializeRepository(repo, {
                         command: runtimeCommand,
                         index: (target, options) => engine.index(target, undefined, false, options),
@@ -1785,7 +2143,7 @@ async function main() {
                 ? ""
                 : (rest[1] ?? "");
             if (!pattern) {
-                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
+                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|file_metrics|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
                 process.exit(1);
             }
             const directionValue = selectorValue("--direction");
@@ -1794,6 +2152,16 @@ async function main() {
                 process.exit(1);
             }
             const facetsValue = selectorValue("--facets")?.split(",").filter(Boolean);
+            const testScopeValue = selectorValue("--test-scope");
+            const queryFormat = selectorValue("--format");
+            if (queryFormat && (pattern !== "file_metrics" || queryFormat !== "json")) {
+                process.stderr.write("knodin query: --format is supported only as file_metrics --format json\n");
+                process.exit(1);
+            }
+            if (testScopeValue && !["all", "test", "production"].includes(testScopeValue)) {
+                process.stderr.write("knodin query: --test-scope must be all, test, or production\n");
+                process.exit(1);
+            }
             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);
@@ -1838,7 +2206,7 @@ async function main() {
                 process.stderr.write("knodin query: --limit must be a positive integer\n");
                 process.exit(1);
             }
-            const queryHealth = pattern.startsWith("lsp_")
+            const queryHealth = pattern.startsWith("lsp_") || pattern === "file_metrics"
                 ? null
                 : await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
             if (queryHealth && !queryHealth.available) {
@@ -1864,6 +2232,10 @@ async function main() {
                 }
                 : undefined, {
                 minLines: selectorValue("--min-lines") ? Number(selectorValue("--min-lines")) : undefined,
+                base: pattern === "file_metrics" ? selectorValue("--base") : undefined,
+                testScope: pattern === "file_metrics"
+                    ? testScopeValue
+                    : undefined,
                 minComplexity: selectorValue("--min-complexity")
                     ? Number(selectorValue("--min-complexity"))
                     : undefined,
@@ -1888,6 +2260,8 @@ async function main() {
                     : selectorValue("--relations")?.split(",").filter(Boolean),
                 detailLevel,
             });
+            if (pattern === "file_metrics")
+                result = result.fileMetrics;
             if (pattern === "impact" || pattern === "dead_code") {
                 const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
                 result = incorporateSystemQueryEvidence(config, repo, pattern, target, result);
@@ -1973,16 +2347,23 @@ async function main() {
             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);
+            if (action === "enable")
+                result = enableSessionTelemetry(repo);
+            else if (action === "disable")
+                result = disableSessionTelemetry(repo);
+            else if (action === "status")
+                result = {
+                    ...telemetryStatus(repo, input, retentionDays),
+                    session: sessionTelemetryStatus(repo, retentionDays),
+                };
             else if (action === "report")
-                result = writeTelemetryReport(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"));
+                result = writeTelemetryReport(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"), readSessionEvents(repo, retentionDays));
             else if (action === "export")
-                result = exportTelemetry(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"));
+                result = exportTelemetry(repo, readTelemetryRecords(repo, input, retentionDays), selectorValue("--output"), readSessionEvents(repo, retentionDays));
             else if (action === "clear")
-                result = clearTelemetry(repo, input);
+                result = { ...clearTelemetry(repo, input), session: clearSessionTelemetry(repo) };
             else
-                throw new Error("knodin telemetry requires status, report, export, or clear");
+                throw new Error("knodin telemetry requires enable, disable, status, report, export, or clear");
             break;
         }
         case "diagnostics": {
@@ -2074,13 +2455,17 @@ async function main() {
             process.exit(1);
     }
     await engine.close();
+    if (agentEventOutput) {
+        if (result !== null && result !== undefined)
+            process.stdout.write(`${JSON.stringify(result)}\n`);
+        return;
+    }
     if (statusWasWatched)
         return;
-    const boundedResult = applyResponseBudget(result, cmd, responseBudget, {
-        bytes: 65_536,
-        tokens: 16_384,
-        items: 100,
-    });
+    const fileMetricsOutput = cmd === "query" && rest[0] === "file_metrics";
+    const boundedResult = applyResponseBudget(result, cmd, responseBudget, fileMetricsOutput
+        ? { bytes: 16_777_216, tokens: 4_194_304, items: 100_000 }
+        : { bytes: 65_536, tokens: 16_384, items: 100 });
     const finalExitCode = Math.max(Number(process.exitCode ?? 0), repairExitCode);
     if (cmd === "init" && !jsonOutput) {
         process.stdout.write(formatInitHuman(boundedResult));
@@ -2128,55 +2513,81 @@ try {
 }
 catch (err) {
     const argv = process.argv.slice(2);
-    const repoIndex = argv.indexOf("--repo");
-    const equalsRepo = argv.find((argument) => argument.startsWith("--repo="));
-    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;
-        return !(index > 0 && argv[index - 1] === "--repo") && argument !== candidate;
-    });
-    const knownCommands = new Set([
-        "init",
-        "configure",
-        "index",
-        "doctor",
-        "status",
-        "wait",
-        "repair",
-        "serve",
-        "context",
-        "explain",
-        "review",
-        "map",
-        "search",
-        "query",
-        "rename",
-        "wiki",
-        "visualize",
-        "pack",
-        "compress",
-        "prs",
-        "worktrees",
-        "telemetry",
-        "diagnostics",
-        "system",
-        "repos",
-        "remote",
-        "update",
-    ]);
-    const diagnostic = recordDiagnosticFailure(candidate, {
-        surface: "cli",
-        operation: command && knownCommands.has(command) ? command : "unknown",
-        phase: "dispatch",
-        error: err,
-    });
-    const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
-    console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
-    process.exit(1);
+    let invokedCommand;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--repo") {
+            index += 1;
+            continue;
+        }
+        if (argument?.startsWith("--repo=") || argument === "--json")
+            continue;
+        if (!argument?.startsWith("-")) {
+            invokedCommand = argument;
+            break;
+        }
+    }
+    if (invokedCommand === "agent-event") {
+        const eventIndex = argv.indexOf("agent-event");
+        if (argv[eventIndex + 1] === "session-start") {
+            process.stdout.write(`${JSON.stringify(sessionStartHookOutput(`## knodin session context\n${SESSION_CONTEXT_BUDGET_LINE}\nContext generation was unavailable. Run knodin status before relying on graph evidence.`))}\n`);
+        }
+        process.exitCode = 0;
+    }
+    else {
+        const repoIndex = argv.indexOf("--repo");
+        const equalsRepo = argv.find((argument) => argument.startsWith("--repo="));
+        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;
+            return !(index > 0 && argv[index - 1] === "--repo") && argument !== candidate;
+        });
+        const knownCommands = new Set([
+            "init",
+            "configure",
+            "agent-hooks",
+            "agent-event",
+            "index",
+            "doctor",
+            "status",
+            "wait",
+            "repair",
+            "serve",
+            "context",
+            "explain",
+            "review",
+            "map",
+            "search",
+            "query",
+            "rename",
+            "wiki",
+            "visualize",
+            "pack",
+            "compress",
+            "prs",
+            "worktrees",
+            "telemetry",
+            "diagnostics",
+            "system",
+            "repos",
+            "remote",
+            "shared",
+            "update",
+        ]);
+        const diagnostic = recordDiagnosticFailure(candidate, {
+            surface: "cli",
+            operation: command && knownCommands.has(command) ? command : "unknown",
+            phase: "dispatch",
+            error: err,
+        });
+        const correlation = diagnostic.recorded ? ` [diagnostic ${diagnostic.correlationId}]` : "";
+        console.error(`${err instanceof Error ? err.message : String(err)}${correlation}`);
+        process.exit(1);
+    }
 }