@danielblomma/cortex-mcp 2.2.5 → 2.4.1

package/scaffold/mcp/package.json

@@ -14,23 +14,32 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^4.1.0",
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@types/js-yaml": "^4.0.9",
-    "js-yaml": "^4.1.1",
-    "minimatch": "^10.2.5",
+    "js-yaml": "^4.3.0",
+    "minimatch": "^10.2.6",
     "ryugraph": "^25.9.1",
     "zod": "^3.24.1"
   },
   "overrides": {
+    "@hono/node-server": "^2.0.12",
+    "adm-zip": "^0.6.0",
+    "body-parser": "^2.3.0",
+    "brace-expansion": "^5.0.8",
     "cmake-js": "^8.0.0",
     "express-rate-limit": "^8.5.1",
-    "hono": "^4.12.23",
-    "@hono/node-server": "^1.19.13",
-    "tar": "^7.5.11"
+    "fast-uri": "^3.1.4",
+    "hono": "^4.12.32",
+    "protobufjs": "^7.6.5",
+    "sharp": "^0.35.3",
+    "tar": "^7.5.22"
   },
   "devDependencies": {
     "@types/node": "^22.10.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20.9.0"
   }
 }

package/scaffold/mcp/src/cli/enterprise-setup.ts

@@ -1,11 +1,28 @@
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { verifyLicense } from "../core/license.js";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import {
+  enterpriseCredentialId,
+  isAllowedLicenseEndpoint,
+  verifyLicense,
+} from "../core/license.js";
+import {
+  claimEnterpriseHostIdentity,
+  inspectEnterpriseHostIdentity,
+} from "../core/enterprise-host-identity.js";
+import { prepareEnterpriseCredentialRotation } from "../core/enterprise-rotation.js";
 
 /**
  * One-liner enterprise onboarding.
  *
- *   $ cortex enterprise <api-key> [--endpoint <url>]
+ *   $ printenv CORTEX_API_KEY | cortex enterprise install --api-key-stdin
  *
  * Replaces the manual `.context/enterprise.yml` editing flow that's been
  * the friction point for new users. Validates the key against the
@@ -33,7 +50,7 @@ const API_KEY_RE = /^(?:ctx|ent)_[A-Za-z0-9._-]{8,}$/;
 
 function buildEnterpriseYaml(baseUrl: string, apiKey: string): string {
   const lines = [
-    "# Cortex enterprise configuration. Generated by `cortex enterprise <key>`.",
+    "# Cortex enterprise configuration. Generated by `cortex enterprise install --api-key-stdin`.",
     "# Single api_key is used for telemetry, policy, audit and govern services.",
     "enterprise:",
     `  api_key: ${apiKey}`,
@@ -75,10 +92,11 @@ export async function runEnterpriseSetup(
     };
   }
 
-  if (!/^https?:\/\//.test(endpoint)) {
+  if (!isAllowedLicenseEndpoint(endpoint)) {
     return {
       ok: false,
-      message: `Endpoint must be http(s) URL: ${endpoint}`,
+      message:
+        "Endpoint must use HTTPS. Plain HTTP is allowed only for localhost loopback development.",
     };
   }
 
@@ -101,13 +119,33 @@ export async function runEnterpriseSetup(
       message: `License rejected: ${license.reason} (source=${license.source}). Verify the API key and endpoint are correct.`,
     };
   }
-
   // Write enterprise.yml.
   const configPath = join(contextDir, "enterprise.yml");
+  const temporaryConfigPath = join(
+    contextDir,
+    `.enterprise.yml.${process.pid}.${randomUUID()}.tmp`,
+  );
   try {
     mkdirSync(contextDir, { recursive: true });
-    writeFileSync(configPath, buildEnterpriseYaml(endpoint, apiKey), "utf8");
+    writeFileSync(
+      temporaryConfigPath,
+      buildEnterpriseYaml(endpoint, apiKey),
+      {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+      },
+    );
+    chmodSync(temporaryConfigPath, 0o600);
+    renameSync(temporaryConfigPath, configPath);
+    // Preserve restrictive permissions even when replacing an existing file.
+    chmodSync(configPath, 0o600);
   } catch (err) {
+    try {
+      unlinkSync(temporaryConfigPath);
+    } catch {
+      // The rename may already have completed, or the temp file was not made.
+    }
     return {
       ok: false,
       message: `Failed to write ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
@@ -122,3 +160,39 @@ export async function runEnterpriseSetup(
     expiresAt: license.expires_at,
   };
 }
+
+export function bindEnterpriseIdentity(options: {
+  apiKey: string;
+  endpoint?: string;
+  homeDir?: string;
+  owner?: { uid: number; gid: number };
+}): boolean {
+  const endpoint = (options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/$/, "");
+  const apiKey = options.apiKey.trim();
+  if (!API_KEY_RE.test(apiKey) || !isAllowedLicenseEndpoint(endpoint)) {
+    return false;
+  }
+  const credentialId = enterpriseCredentialId(endpoint, apiKey);
+  const identityStatus = inspectEnterpriseHostIdentity(
+    credentialId,
+    endpoint,
+    { homeDir: options.homeDir, owner: options.owner },
+  );
+  if (identityStatus === "conflict" || identityStatus === "invalid") {
+    return false;
+  }
+  if (
+    identityStatus === "rotation" &&
+    !prepareEnterpriseCredentialRotation(options.homeDir)
+  ) {
+    return false;
+  }
+  return claimEnterpriseHostIdentity(
+    credentialId,
+    endpoint,
+    {
+      homeDir: options.homeDir,
+      owner: options.owner,
+    },
+  );
+}

package/scaffold/mcp/src/cli/govern.ts

@@ -14,7 +14,15 @@ import { join, dirname } from "node:path";
 import { platform, hostname } from "node:os";
 import { randomUUID } from "node:crypto";
 import { loadEnterpriseConfig, type ComplianceFramework } from "../core/config.js";
-import { installCopilotShim, uninstallCopilotShim } from "./run.js";
+import { isAllowedEnterpriseEndpoint } from "../core/secure-endpoint.js";
+import { getGovernManagedPath } from "../core/govern-paths.js";
+import { matchesEnterpriseHostIdentity } from "../core/enterprise-host-identity.js";
+import { enterpriseCredentialId } from "../core/license.js";
+import {
+  getDefaultCopilotShimPath,
+  installCopilotShim,
+  uninstallCopilotShim,
+} from "./run.js";
 import {
   readTamperLock,
   removeTamperLock,
@@ -28,21 +36,14 @@ const TIER1_CLIS: GovernCli[] = ["claude", "codex"];
 
 export type ManagedSettingsPaths = Partial<Record<GovernCli, Partial<Record<NodeJS.Platform, string>>>>;
 
-const DEFAULT_PATHS: ManagedSettingsPaths = {
-  claude: {
-    darwin: "/Library/Application Support/ClaudeCode/managed-settings.json",
-    linux: "/etc/claude-code/managed-settings.json",
-  },
-  codex: {
-    darwin: "/Library/Application Support/Codex/requirements.toml",
-    linux: "/etc/codex/requirements.toml",
-  },
-};
-
 export type GovernState = {
   installs: Partial<Record<GovernCli, GovernInstallRecord>>;
 };
 
+export type ProjectOperationRunner = <T>(
+  operation: () => T | Promise<T>,
+) => T | Promise<T>;
+
 export type GovernInstallRecord = {
   path: string;
   version: string;
@@ -84,11 +85,10 @@ const SUPPORTED_CODEX_HOOK_EVENTS = new Set([
 ]);
 
 export function getManagedSettingsPath(cli: GovernCli, os: NodeJS.Platform): string {
-  const path = DEFAULT_PATHS[cli]?.[os];
-  if (!path) {
+  if (cli === "copilot") {
     throw new Error(`govern install for ${cli} not yet supported on ${os}`);
   }
-  return path;
+  return getGovernManagedPath(cli, os);
 }
 
 export function requireRoot(): void {
@@ -346,8 +346,33 @@ function loadState(cwd: string): GovernState {
 
 function saveState(cwd: string, state: GovernState): void {
   const path = getStatePath(cwd);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(state, null, 2), "utf8");
+  writeAtomic(path, JSON.stringify(state, null, 2) + "\n", 0o600);
+}
+
+async function runProjectOperation<T>(
+  runner: ProjectOperationRunner | undefined,
+  operation: () => T | Promise<T>,
+): Promise<T> {
+  return runner ? await runner(operation) : await operation();
+}
+
+function managedPathForCli(
+  cli: GovernCli,
+  options: {
+    skipRoot?: boolean;
+    pathOverride?: Partial<Record<GovernCli, string>>;
+  },
+): string {
+  const override = options.pathOverride?.[cli];
+  if (override) {
+    if (!options.skipRoot) {
+      throw new Error("Managed path overrides are allowed only in non-root tests.");
+    }
+    return override;
+  }
+  return cli === "copilot"
+    ? getDefaultCopilotShimPath(platform())
+    : getManagedSettingsPath(cli, platform());
 }
 
 async function fetchGovernConfig(
@@ -356,6 +381,9 @@ async function fetchGovernConfig(
   cli: GovernCli,
   frameworks: string[],
 ): Promise<{ config: FetchedConfig; etag: string | null }> {
+  if (!isAllowedEnterpriseEndpoint(baseUrl)) {
+    throw new Error("insecure or invalid enterprise endpoint");
+  }
   const url = new URL(`${baseUrl.replace(/\/$/, "")}/api/v1/govern/config`);
   url.searchParams.set("cli", cli);
   url.searchParams.set("frameworks", frameworks.join(","));
@@ -383,6 +411,9 @@ async function postApplied(
     instance_id?: string;
   },
 ): Promise<void> {
+  if (!isAllowedEnterpriseEndpoint(baseUrl)) {
+    throw new Error("insecure or invalid enterprise endpoint");
+  }
   const res = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v1/govern/applied`, {
     method: "POST",
     headers: {
@@ -406,6 +437,7 @@ export type GovernInstallOptions = {
   skipRoot?: boolean;
   apiKey?: string;
   baseUrl?: string;
+  projectOperation?: ProjectOperationRunner;
 };
 
 export type GovernInstallResult = {
@@ -432,7 +464,10 @@ export async function runGovernInstall(
   let frameworks = options.frameworks ?? [];
 
   if (!apiKey || !baseUrl || frameworks.length === 0) {
-    const config = loadEnterpriseConfig(contextDir);
+    const config = await runProjectOperation(
+      options.projectOperation,
+      () => loadEnterpriseConfig(contextDir),
+    );
     if (!apiKey) apiKey = config.enterprise.api_key.trim();
     if (!baseUrl) baseUrl = (config.enterprise.base_url || config.enterprise.endpoint).trim();
     if (frameworks.length === 0) {
@@ -468,16 +503,17 @@ export async function runGovernInstall(
   }
 
   const mode = options.mode ?? "advisory";
-  const state = loadState(cwd);
+  const state = await runProjectOperation(
+    options.projectOperation,
+    () => loadState(cwd),
+  );
   const installed: GovernCli[] = [];
 
   for (const cli of targets) {
     if (cli === "copilot") {
       if (!options.skipRoot) requireRoot();
-      const shimPath = options.pathOverride?.copilot;
-      const shimResult = installCopilotShim(
-        shimPath ? { shimPath } : {},
-      );
+      const shimPath = managedPathForCli(cli, options);
+      const shimResult = installCopilotShim({ shimPath });
       if (!shimResult.ok) {
         console.log(`! ${cli}: ${shimResult.message}`);
         continue;
@@ -495,7 +531,7 @@ export async function runGovernInstall(
     }
     if (!options.skipRoot) requireRoot();
 
-    const path = options.pathOverride?.[cli] ?? getManagedSettingsPath(cli, platform());
+    const path = managedPathForCli(cli, options);
 
     let merged: FetchedConfig;
     let version: string;
@@ -564,7 +600,10 @@ export async function runGovernInstall(
     console.log(`✓ ${cli}: managed-settings written to ${path} (version ${shortVersion}, mode=${mode})`);
   }
 
-  saveState(cwd, state);
+  await runProjectOperation(
+    options.projectOperation,
+    () => saveState(cwd, state),
+  );
   return {
     ok: true,
     message: `Installed govern for ${installed.join(", ") || "(none)"}.`,
@@ -578,13 +617,18 @@ export type GovernUninstallOptions = {
   reason?: string;
   cwd?: string;
   skipRoot?: boolean;
+  pathOverride?: Partial<Record<GovernCli, string>>;
+  projectOperation?: ProjectOperationRunner;
 };
 
 export async function runGovernUninstall(
   options: GovernUninstallOptions,
 ): Promise<{ ok: boolean; message: string; uninstalled: GovernCli[] }> {
   const cwd = options.cwd ?? process.cwd();
-  const state = loadState(cwd);
+  const state = await runProjectOperation(
+    options.projectOperation,
+    () => loadState(cwd),
+  );
 
   // Filter out unknown CLI keys defensively — govern.local.json is a
   // user-writable file and a corrupted/forward-compatible entry must not
@@ -620,8 +664,9 @@ export async function runGovernUninstall(
     const inst = state.installs[cli];
     if (!inst) continue;
     if (!options.skipRoot) requireRoot();
+    const managedPath = managedPathForCli(cli, options);
     if (cli === "copilot") {
-      const shimResult = uninstallCopilotShim(inst.path);
+      const shimResult = uninstallCopilotShim(managedPath);
       if (!shimResult.ok) {
         console.log(`! ${cli}: ${shimResult.message}`);
         continue;
@@ -635,19 +680,22 @@ export async function runGovernUninstall(
       continue;
     }
     try {
-      unlinkSync(inst.path);
+      unlinkSync(managedPath);
     } catch {
       // file already gone — proceed
     }
     delete state.installs[cli];
     uninstalled.push(cli);
     console.log(
-      `✓ ${cli}: managed-settings removed from ${inst.path}` +
+      `✓ ${cli}: managed-settings removed from ${managedPath}` +
         (options.breakGlass ? ` (break-glass: ${options.reason})` : ""),
     );
   }
 
-  saveState(cwd, state);
+  await runProjectOperation(
+    options.projectOperation,
+    () => saveState(cwd, state),
+  );
   return {
     ok: true,
     message: `Uninstalled govern for ${uninstalled.join(", ") || "(none)"}.`,
@@ -685,6 +733,7 @@ export type GovernStatusReport = {
   generated_at: string;
   enterprise: {
     api_key_set: boolean;
+    host_identity_bound: boolean;
     base_url: string;
     frameworks_configured: ComplianceFramework[];
     govern_mode_config: GovernConfigModeFromConfig;
@@ -933,14 +982,23 @@ export function buildGovernStatus(options: { cwd?: string; now?: Date } = {}): G
   }
 
   const { counts, sample } = readRecentEvents(cwd, 24 * 60 * 60 * 1000, now);
+  const enterpriseBaseUrl =
+    config.enterprise.base_url || config.enterprise.endpoint;
+  const enterpriseApiKey = config.enterprise.api_key.trim();
 
   return {
     cwd,
     host_id: hostname(),
     generated_at: now.toISOString(),
     enterprise: {
-      api_key_set: config.enterprise.api_key.trim() !== "",
-      base_url: config.enterprise.base_url || config.enterprise.endpoint,
+      api_key_set: enterpriseApiKey !== "",
+      host_identity_bound:
+        enterpriseApiKey !== "" &&
+        enterpriseBaseUrl !== "" &&
+        matchesEnterpriseHostIdentity(
+          enterpriseCredentialId(enterpriseBaseUrl, enterpriseApiKey),
+        ),
+      base_url: enterpriseBaseUrl,
       frameworks_configured: config.compliance.frameworks,
       govern_mode_config: config.govern.mode,
     },
@@ -964,7 +1022,10 @@ function formatCompact(report: GovernStatusReport): string {
   );
   lines.push(`Endpoint:      ${report.enterprise.base_url || "(not set)"}`);
   lines.push(
-    `API key:       ${report.enterprise.api_key_set ? "configured" : "NOT SET (run 'sudo cortex enterprise <key>')"}`,
+    `API key:       ${report.enterprise.api_key_set ? "configured" : "NOT SET (run 'sudo cortex enterprise install --api-key-stdin')"}`,
+  );
+  lines.push(
+    `Host identity: ${report.enterprise.host_identity_bound ? "verified" : "NOT ENROLLED (re-run stdin install)"}`,
   );
   lines.push("");
   if (report.tamper_lock) {
@@ -986,7 +1047,7 @@ function formatCompact(report: GovernStatusReport): string {
   }
   if (report.installs.length === 0) {
     lines.push("No CLIs governed on this host.");
-    lines.push("Run: sudo cortex enterprise <api-key>");
+    lines.push("Run: sudo cortex enterprise install --api-key-stdin");
     return lines.join("\n");
   }
   lines.push("AI CLIs on this host:");
@@ -1065,6 +1126,8 @@ export type GovernRepairOptions = {
   cwd?: string;
   skipRoot?: boolean;
   reason?: string;
+  pathOverride?: Partial<Record<GovernCli, string>>;
+  projectOperation?: ProjectOperationRunner;
 };
 
 export type GovernRepairResult = {
@@ -1087,7 +1150,10 @@ export async function runGovernRepair(
   options: GovernRepairOptions = {},
 ): Promise<GovernRepairResult> {
   const cwd = options.cwd ?? process.cwd();
-  const state = loadState(cwd);
+  const state = await runProjectOperation(
+    options.projectOperation,
+    () => loadState(cwd),
+  );
   // Filter to known CLIs so a corrupt or forward-compatible install
   // record doesn't crash the repair walk.
   const installed: Array<[GovernCli, GovernInstallRecord]> = Object.entries(
@@ -1100,7 +1166,7 @@ export async function runGovernRepair(
     return {
       ok: false,
       message:
-        "No CLIs governed on this host — nothing to repair. Run 'cortex enterprise <key>' first.",
+        "No CLIs governed on this host — nothing to repair. Run 'cortex enterprise install --api-key-stdin' first.",
       reverified: [],
     };
   }
@@ -1109,21 +1175,22 @@ export async function runGovernRepair(
 
   const verified: GovernCli[] = [];
   const missing: string[] = [];
-  for (const [cli, record] of installed) {
-    if (!existsSync(record.path)) {
-      missing.push(`${cli}: ${record.path} is missing`);
+  for (const [cli] of installed) {
+    const managedPath = managedPathForCli(cli, options);
+    if (!existsSync(managedPath)) {
+      missing.push(`${cli}: ${managedPath} is missing`);
       continue;
     }
     if (cli === "copilot") {
       // Verify the file is still our shim (not replaced by a real binary).
       try {
-        const raw = readFileSync(record.path, "utf8");
+        const raw = readFileSync(managedPath, "utf8");
         if (!raw.includes("# cortex-shim-v1")) {
-          missing.push(`${cli}: ${record.path} is no longer a cortex shim`);
+          missing.push(`${cli}: ${managedPath} is no longer a cortex shim`);
           continue;
         }
       } catch {
-        missing.push(`${cli}: ${record.path} could not be read`);
+        missing.push(`${cli}: ${managedPath} could not be read`);
         continue;
       }
     }
@@ -1141,7 +1208,10 @@ export async function runGovernRepair(
     };
   }
 
-  const lock = readTamperLock(cwd);
+  const lock = await runProjectOperation(
+    options.projectOperation,
+    () => readTamperLock(cwd),
+  );
   if (!lock) {
     return {
       ok: true,
@@ -1152,14 +1222,20 @@ export async function runGovernRepair(
     };
   }
 
-  const removed = removeTamperLock(cwd);
+  const removed = await runProjectOperation(
+    options.projectOperation,
+    () => removeTamperLock(cwd),
+  );
   if (removed) {
-    await emitTamperAudit(cwd, {
-      ...lock,
-      detected_at: new Date().toISOString(),
-      hook_name: "tamper_repaired",
-      missing_seconds: 0,
-    }).catch(() => undefined);
+    await runProjectOperation(
+      options.projectOperation,
+      () => emitTamperAudit(cwd, {
+        ...lock,
+        detected_at: new Date().toISOString(),
+        hook_name: "tamper_repaired",
+        missing_seconds: 0,
+      }).catch(() => undefined),
+    );
   }
 
   return {
@@ -1172,9 +1248,17 @@ export async function runGovernRepair(
   };
 }
 
-export async function runGovernSync(options: { cwd?: string } = {}): Promise<void> {
+export async function runGovernSync(
+  options: {
+    cwd?: string;
+    projectOperation?: ProjectOperationRunner;
+  } = {},
+): Promise<void> {
   const cwd = options.cwd ?? process.cwd();
-  const state = loadState(cwd);
+  const state = await runProjectOperation(
+    options.projectOperation,
+    () => loadState(cwd),
+  );
   // Drop unknown CLI keys: runGovernInstall would throw on an unsupported
   // cli, but silently skipping is the right behaviour when sync runs in
   // the daemon — it's not a user typo to surface, just stale/forward
@@ -1192,6 +1276,7 @@ export async function runGovernSync(options: { cwd?: string } = {}): Promise<voi
       cli,
       cwd,
       mode: previous?.mode,
+      projectOperation: options.projectOperation,
     });
     if (!result.ok) {
       console.log(`! sync ${cli} failed: ${result.message}`);

package/scaffold/mcp/src/cli/query.ts

@@ -1,7 +1,9 @@
 import { runContextRules } from "../rules.js";
+import { runPatternEvidence } from "../patternEvidence.js";
 import { runContextImpact, runContextRelated, runContextSearch } from "../search.js";
 import type {
   ImpactParams,
+  PatternEvidenceParams,
   RelatedParams,
   RelationType,
   RulesParams,
@@ -29,7 +31,7 @@ type JsonEnvelope = {
   };
 };
 
-const QUERY_COMMANDS = new Set(["search", "related", "impact", "rules", "explain"]);
+const QUERY_COMMANDS = new Set(["search", "related", "impact", "rules", "explain", "pattern-evidence"]);
 
 const ENTITY_ID_PREFIXES = [
   "file:",
@@ -66,6 +68,8 @@ export async function runQueryCommand(args: string[]): Promise<void> {
         return await runRules(rest);
       case "explain":
         return await runExplain(rest);
+      case "pattern-evidence":
+        return await runPatternEvidenceCommand(rest);
       default:
         throw new Error(`Unknown query command: ${command}`);
     }
@@ -93,6 +97,7 @@ function printHelp(): void {
     "  cortex impact <query-or-entity-id> [--entity-id <id>] [--query <q>] [--depth <n>] [--top-k <n>] [--json]",
     "  cortex rules [--scope <scope>] [--include-inactive] [--json]",
     "  cortex explain <query-or-entity-id> [--top-k <n>] [--json]",
+    "  cortex pattern-evidence <file-path|entity-id> [--query <text>] [--top-k <n>] [--json]",
     "",
     "These commands read the local Cortex graph and emit MCP-equivalent data with --json.",
   ];
@@ -157,7 +162,11 @@ function parsePositiveIntFlag(
   if (typeof raw !== "string" || raw.trim().length === 0) {
     throw new Error(`--${name} requires a numeric value`);
   }
-  const parsed = Number.parseInt(raw, 10);
+  const normalized = raw.trim();
+  if (!/^[1-9]\d*$/.test(normalized)) {
+    throw new Error(`--${name} must be an integer from 1 to ${max}`);
+  }
+  const parsed = Number(normalized);
   if (!Number.isInteger(parsed) || parsed <= 0 || parsed > max) {
     throw new Error(`--${name} must be an integer from 1 to ${max}`);
   }
@@ -453,3 +462,28 @@ async function runExplain(args: string[]): Promise<void> {
   }
   printSummary("explain", data);
 }
+
+async function runPatternEvidenceCommand(args: string[]): Promise<void> {
+  const { flags, rest } = parseArgs(args);
+  const target = optionalString(flags, "target") ?? positionalText(rest, "file-path-or-entity-id");
+  const input: PatternEvidenceParams = {
+    target,
+    query: optionalString(flags, "query"),
+    top_k: parsePositiveIntFlag(flags, "top-k", 3, 10),
+    include_deprecated: isFlagEnabled(flags, "include-deprecated"),
+  };
+  const data = await runPatternEvidence(input);
+  if (isFlagEnabled(flags, "json")) {
+    emitEnvelope("pattern-evidence", input, data);
+    return;
+  }
+
+  const tiers = Array.isArray(data.tiers) ? data.tiers : [];
+  process.stdout.write(`pattern-evidence: local_pattern_found=${String(data.local_pattern_found)}\n`);
+  for (const value of tiers) {
+    if (!value || typeof value !== "object") continue;
+    const tier = value as Record<string, unknown>;
+    const evidence = Array.isArray(tier.evidence) ? tier.evidence : [];
+    process.stdout.write(`- ${String(tier.name ?? "")}: ${evidence.length}\n`);
+  }
+}