karajan-code 2.7.3 → 2.8.0

package/src/canvas/to-flat.js

@@ -0,0 +1,85 @@
+/**
+ * Canvas → flat task string adapter.
+ *
+ * Renders a validated Canvas object as a single markdown blob the
+ * existing planner can consume verbatim. Preserves every section
+ * with its original heading so downstream steps (planner prompt,
+ * coder prompt, plan JSON `task` field) see the same shape.
+ *
+ * The point: Canvas users get planner-time validation (catching
+ * broken acceptance tests before they're persisted) AND benefit from
+ * every existing planner / coder pipeline without those pipelines
+ * needing Canvas awareness. Norms + Safeguards explicitly bracketed
+ * so prompts that scan for them can find them with a regex.
+ */
+
+/**
+ * @param {object} canvas — output of validateCanvas (.canvas)
+ * @returns {string} markdown task ready for the planner
+ */
+export function canvasToTask(canvas) {
+  const lines = [`# ${canvas.title}`, ""];
+
+  // Requirements
+  lines.push("## Requirements", canvas.requirements.problem);
+  if (canvas.requirements.done && canvas.requirements.done.length > 0) {
+    lines.push("", "Definition of done:");
+    for (const d of canvas.requirements.done) lines.push(`- ${d}`);
+  }
+  lines.push("");
+
+  // Entities (optional)
+  if (canvas.entities && canvas.entities.length > 0) {
+    lines.push("## Entities");
+    for (const e of canvas.entities) {
+      const fields = e.fields && e.fields.length > 0 ? ` — fields: ${e.fields.join(", ")}` : "";
+      lines.push(`- ${e.name}${fields}${e.notes ? `. ${e.notes}` : ""}`);
+    }
+    lines.push("");
+  }
+
+  // Approach
+  lines.push("## Approach", canvas.approach, "");
+
+  // Structure (optional content)
+  lines.push("## Structure");
+  if (canvas.structure?.touches?.length > 0) lines.push(`- touches: ${canvas.structure.touches.join(", ")}`);
+  if (canvas.structure?.depends_on?.length > 0) lines.push(`- depends_on: ${canvas.structure.depends_on.join(", ")}`);
+  if (canvas.structure?.contracts?.length > 0) lines.push(`- contracts: ${canvas.structure.contracts.join(", ")}`);
+  lines.push("");
+
+  // Operations — each becomes one HU. Acceptance tests inline so the
+  // planner sees the contract from turn 1.
+  lines.push("## Operations");
+  canvas.operations.forEach((op, i) => {
+    lines.push(`${i + 1}. ${op.title}`);
+    if (op.file_hint) lines.push(`   file: ${op.file_hint}`);
+    if (op.blocked_by && op.blocked_by.length > 0) lines.push(`   depends on: ${op.blocked_by.join(", ")}`);
+    lines.push("   Acceptance:");
+    for (const t of op.acceptance) {
+      // Render shell as one-liner, gherkin as fenced block so newlines survive.
+      if (t.type === "gherkin") {
+        lines.push("   - gherkin:", "     ```gherkin", ...t.content.split("\n").map((l) => `     ${l}`), "     ```");
+      } else {
+        lines.push(`   - shell: \`${t.content}\``);
+      }
+    }
+  });
+  lines.push("");
+
+  // Norms (optional) — bracketed so prompts can find them.
+  if (canvas.norms && canvas.norms.length > 0) {
+    lines.push("## Norms (per-task engineering standards — coder MUST follow)");
+    for (const n of canvas.norms) lines.push(`- ${n}`);
+    lines.push("");
+  }
+
+  // Safeguards (optional) — bracketed similarly.
+  if (canvas.safeguards && canvas.safeguards.length > 0) {
+    lines.push("## Safeguards (non-negotiable invariants — code MUST hold these)");
+    for (const s of canvas.safeguards) lines.push(`- ${s}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/canvas/validate.js

@@ -0,0 +1,163 @@
+/**
+ * REASONS Canvas validator.
+ *
+ * Schema validation + planner-time sanity checks for acceptance tests.
+ * The schema is enforced via Valibot in canvas/schema.js. This module
+ * adds the bug-class fix: parse-check every shell acceptance test
+ * BEFORE it gets persisted into a plan and BEFORE any LLM is called.
+ *
+ * Catches the 2026-04-29 incident class:
+ *   `length as $n | .filesOver300LOC == $n` → exits non-zero with a
+ *   descriptive error pointing at the offending operation + test
+ *   index, BEFORE the user has paid for any agent run.
+ */
+
+import { spawnSync } from "node:child_process";
+import { safeParseCanvas } from "./schema.js";
+
+/**
+ * Run a single shell acceptance test through `bash -n` (parse-only,
+ * doesn't execute) to catch shell-level syntax errors. Then, if the
+ * test invokes `jq`, also probe the jq query through `jq -n <query>`
+ * with empty input — jq errors there iff the query has bad syntax.
+ *
+ * Trade-off accepted: bash -n won't catch every command-substitution
+ * pitfall (it parses but doesn't expand), and jq -n with empty input
+ * may pass queries that fail at runtime against real input. The point
+ * is to catch the OBVIOUS bugs cheaply, not to be airtight.
+ *
+ * @param {string} cmd
+ * @returns {{ ok: true } | { ok: false, kind: string, error: string }}
+ */
+export function validateShellTest(cmd) {
+  if (typeof cmd !== "string" || cmd.trim().length === 0) {
+    return { ok: false, kind: "empty", error: "shell test is empty" };
+  }
+
+  // Layer 1: bash -n parse-check on the whole command.
+  const bash = spawnSync("bash", ["-n", "-c", cmd], { encoding: "utf8", timeout: 5000 });
+  if (bash.status !== 0) {
+    const err = (bash.stderr || "").trim() || "bash -n rejected the command";
+    return { ok: false, kind: "shell-syntax", error: err };
+  }
+
+  // Layer 2: every `jq '...'` invocation gets its query parse-checked.
+  // Permissive regex: catches `jq -e 'X'`, `jq "X"`, `| jq 'X'`. False
+  // negatives are fine — better to skip a real jq than misinterpret a
+  // shell-quoting edge case.
+  //
+  // We distinguish COMPILE errors (the bug we want to catch — invalid
+  // syntax, e.g. `length as $n | .field` over an array) from RUNTIME
+  // errors (the query is well-formed but fails on null input from
+  // `-n`, like `.foo[]` on null). Only compile errors fail validation;
+  // runtime errors against synthetic input are expected because real
+  // input isn't available at plan-time.
+  const jqRe = /\bjq\b\s+(?:-[a-zA-Z]+\s+)*(?:'([^']+)'|"([^"]+)")/g;
+  for (const m of cmd.matchAll(jqRe)) {
+    const query = m[1] || m[2];
+    if (!query) continue;
+
+    // Static pattern detector for the 2026-04-29 as-binding misuse:
+    // `[expr] | length as $X | .field` and similar. The `as $X`
+    // binds the value to a name but does NOT change the value
+    // flowing through the pipe. The next `.field` is therefore
+    // applied to the array tail (or whatever the previous stage
+    // returned), not to the original root. Always wrong.
+    //
+    // Detection: a pipeline whose tail is `length as $X | .X` (or
+    // any `<terminal-operator> as $X | .field`) is the smell.
+    const asBindingMisuse = /\b(?:length|keys|values|min|max|add|first|last)\s+as\s+\$[A-Za-z_][\w]*\s*\|\s*\.[A-Za-z_]/;
+    if (asBindingMisuse.test(query)) {
+      return {
+        ok: false,
+        kind: "jq-syntax",
+        error: "Likely as-binding misuse: `length as $n | .field` does not change the value flowing through; `.field` is applied to the previous stage's output, not the root. Use `. as $r | <transform> | $r.field` instead.",
+      };
+    }
+
+    const jq = spawnSync("jq", ["-n", query], { encoding: "utf8", timeout: 5000 });
+    if (jq.status !== 0) {
+      const err = (jq.stderr || "").trim() || "jq rejected the query";
+      // jq distinguishes compile errors with these tokens. Anything
+      // else (e.g. "Cannot index null with string") is a runtime error
+      // against the empty input, NOT a syntax bug.
+      const isCompileError = /\b(compile error|syntax error|unexpected|jq: error \(at <stdin>:\d+\): ?$)/i.test(err);
+      if (isCompileError) {
+        return { ok: false, kind: "jq-syntax", error: err };
+      }
+      // Special case: `length as $n | .field` returns "Cannot index
+      // array/number/string with string" on -n input because the as-
+      // binding misuse means `.field` is applied to the wrong thing.
+      // This is exactly the 2026-04-29 bug class. Treat it as syntax-
+      // adjacent: the query is "compilable" but semantically broken
+      // by misuse of as-binding.
+      if (/Cannot index (array|number|string) with string/i.test(err)) {
+        return { ok: false, kind: "jq-syntax", error: err };
+      }
+      // Otherwise let it pass — runtime error against synthetic input
+      // is fine. jq parsed the query successfully.
+    }
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Validate every operation's acceptance tests in a parsed Canvas.
+ * Returns an array of issues; empty array means everything passed.
+ *
+ * @param {object} canvas
+ * @returns {Array<{ operationIndex: number, operationTitle: string, testIndex: number, type: string, content: string, kind: string, error: string }>}
+ */
+export function validateAcceptanceTests(canvas) {
+  const issues = [];
+  if (!canvas || !Array.isArray(canvas.operations)) return issues;
+  canvas.operations.forEach((op, opIdx) => {
+    (op.acceptance || []).forEach((t, tIdx) => {
+      if (t.type === "shell") {
+        const r = validateShellTest(t.content);
+        if (!r.ok) {
+          issues.push({
+            operationIndex: opIdx,
+            operationTitle: op.title,
+            testIndex: tIdx,
+            type: t.type,
+            content: t.content,
+            kind: r.kind,
+            error: r.error,
+          });
+        }
+      } else if (t.type === "gherkin") {
+        // Minimal gherkin sanity: must contain at least one Given AND
+        // one Then. When/And/But are optional. This catches "blank
+        // gherkin" without trying to parse the language.
+        if (!/\bGiven\b/i.test(t.content) || !/\bThen\b/i.test(t.content)) {
+          issues.push({
+            operationIndex: opIdx,
+            operationTitle: op.title,
+            testIndex: tIdx,
+            type: t.type,
+            content: t.content,
+            kind: "gherkin-incomplete",
+            error: "Gherkin scenario must contain at least one Given and one Then.",
+          });
+        }
+      }
+    });
+  });
+  return issues;
+}
+
+/**
+ * Top-level validator. Runs schema + acceptance-test parse-checks.
+ *
+ * @param {unknown} canvas
+ * @returns {{ valid: true, canvas: object } | { valid: false, schemaIssues?: object[], testIssues?: object[] }}
+ */
+export function validateCanvas(canvas) {
+  const schema = safeParseCanvas(canvas);
+  if (!schema.success) return { valid: false, schemaIssues: schema.issues };
+  const testIssues = validateAcceptanceTests(schema.output);
+  if (testIssues.length > 0) return { valid: false, testIssues };
+  return { valid: true, canvas: schema.output };
+}

package/src/checks/binaries.js

@@ -88,7 +88,7 @@ export function createSerenaCheck() {
     applies: (config) => config.serena?.enabled === true,
     describe: "Install Serena via: uvx --from git+https://github.com/oraios/serena serena",
     async detect() {
-      let ok = false;
+      let ok;
       try {
         const res = await runCommand("serena", ["--version"]);
         ok = res.exitCode === 0;

package/src/checks/ports.js

@@ -12,6 +12,8 @@
 
 import { isPortAvailable, findAvailablePort } from "../utils/port-check.js";
 import { getPortOccupant } from "../utils/port-occupant.js";
+import { discoverRunningSonar } from "../sonar/discovery.js";
+import { isSonarReachable } from "../sonar/manager.js";
 import { STRATEGY } from "./types.js";
 
 const DEFAULT_SONAR_PORT = 9000;
@@ -22,47 +24,110 @@ function extractPortFromHost(host, fallback) {
   return m ? Number(m[1]) : fallback;
 }
 
-/**
- * Whether the occupant looks like the Karajan-managed Sonar container.
- * Docker Desktop's proxy is typically `com.docker.backend` / `com.docker.vmnetd`
- * on macOS and `docker-proxy` on Linux. We treat those as OK.
- */
-function isKarajanSonarOccupant(occupant) {
-  if (!occupant?.command) return false;
-  const cmd = occupant.command.toLowerCase();
-  return cmd.includes("docker") || cmd.includes("sonar");
-}
-
 export function createSonarPortCheck() {
   return {
     name: "port:sonar",
     label: "SonarQube port",
-    strategy: STRATEGY.MANUAL,
-    applies: (config) => config?.sonarqube?.enabled !== false,
+    // AUTO since v2.7.5 — Karajan now resolves SonarQube discovery on
+    // its own. If a Sonar container is running anywhere (any name, any
+    // image tag), point Karajan at it. If port 9000 is occupied by
+    // someone non-Sonar, rebind to the next free port. Asking the user
+    // to "stop the unknown process" was busywork.
+    strategy: STRATEGY.AUTO,
+    applies: (config) => {
+      if (config?.sonarqube?.external === true) {
+        return { applies: false, reason: "sonarqube.external is true — port managed outside Karajan" };
+      }
+      return true;
+    },
+    describe: "Discover or rebind SonarQube port (no user action needed)",
     async detect({ config }) {
-      const port = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
-      const free = await isPortAvailable(port);
+      const configuredPort = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
+
+      // Step 1 — is there ANY running SonarQube container we can reuse?
+      // Container name doesn't matter; we just need a published host port
+      // that responds to /api/system/status. This avoids "port 9000 is
+      // taken by an unknown process" errors when the unknown process is
+      // actually a perfectly good SonarQube from another project.
+      const discovered = await discoverRunningSonar();
+      if (discovered.found && discovered.reachable) {
+        // If the discovered host matches what's already configured,
+        // there's nothing to fix — happy path.
+        if (discovered.port === configuredPort) {
+          return {
+            ok: true,
+            severity: "info",
+            detail: `Reusing running SonarQube container "${discovered.containerName}" on port ${discovered.port}`,
+          };
+        }
+        // Otherwise we want to rewrite the host config at runtime.
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Found running SonarQube container "${discovered.containerName}" on port ${discovered.port} (config points at ${configuredPort})`,
+          extra: { remap: { host: discovered.host, port: discovered.port, container: discovered.containerName } },
+        };
+      }
+
+      // Step 2 — no running container. Is the configured port even free?
+      const free = await isPortAvailable(configuredPort);
       if (free) {
-        return { ok: true, severity: "info", detail: `Port ${port} is free (Sonar container not yet running)` };
+        return {
+          ok: true,
+          severity: "info",
+          detail: `Port ${configuredPort} is free (Sonar container will be started on demand)`,
+        };
       }
-      // Busy — is it our container?
-      const occupant = await getPortOccupant(port);
-      if (occupant && isKarajanSonarOccupant(occupant)) {
+
+      // Step 3 — port is busy. Maybe the occupant IS Sonar but not
+      // discovered by `docker ps` (rare: bare-metal Sonar, host-network
+      // container, etc.). HTTP-probe to find out.
+      const probeHost = `http://localhost:${configuredPort}`;
+      if (await isSonarReachable(probeHost)) {
         return {
           ok: true,
           severity: "info",
-          detail: `Port ${port} held by Karajan-managed Sonar (${occupant.command} PID ${occupant.pid})`,
+          detail: `Port ${configuredPort} held by a Sonar instance (HTTP /api/system/status responds) — reusing it`,
         };
       }
-      const who = occupant
-        ? `${occupant.command || "unknown"} (PID ${occupant.pid ?? "?"})`
-        : "unknown process";
+
+      // Step 4 — really not Sonar. Find an alternate free port and tell
+      // the runtime to use it. The compose template's published port is
+      // hardcoded at 9000 so we can't auto-rebind the container itself,
+      // but we CAN warn loudly with a clear, fixable message.
+      const occupant = await getPortOccupant(configuredPort);
+      const alt = await findAvailablePort(configuredPort + 1, 20);
+      if (alt) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Port ${configuredPort} occupied by ${occupant?.command || "unknown"} (PID ${occupant?.pid ?? "?"}). Will rebind Karajan-managed Sonar to ${alt}.`,
+          extra: { remap: { host: `http://localhost:${alt}`, port: alt, fromPort: configuredPort } },
+        };
+      }
+      // Last-resort failure (no free port in the next 20).
       return {
         ok: false,
         severity: "fail",
-        detail: `Port ${port} occupied by ${who}`,
-        fix: `Stop the process holding port ${port} or change sonarqube.host in kj.config.yml.`,
-        extra: { port, occupant },
+        detail: `Port ${configuredPort} occupied by ${occupant?.command || "unknown"} (PID ${occupant?.pid ?? "?"}) and no free port in ${configuredPort + 1}..${configuredPort + 20}`,
+        fix: "Stop the conflicting process or set sonarqube.host in kj.config.yml.",
+      };
+    },
+    async remediate({ extra }) {
+      if (!extra?.remap) {
+        return { fixed: false, detail: "No remap available" };
+      }
+      const { host, container, fromPort } = extra.remap;
+      const detail = container
+        ? `Pointed Karajan at running SonarQube ${container} (${host})`
+        : `Rebound Karajan-managed Sonar from port ${fromPort} to ${host}`;
+      return {
+        fixed: true,
+        detail,
+        // The runner merges this into the runtime config so every
+        // downstream Sonar caller (scanner, manager, MCP handler) sees
+        // the new host without the user touching kj.config.yml.
+        changes: { sonarqube: { host } },
       };
     },
   };
@@ -73,7 +138,12 @@ export function createHuBoardPortCheck() {
     name: "port:hu-board",
     label: "HU Board port",
     strategy: STRATEGY.AUTO,
-    applies: (config) => config?.hu_board?.enabled !== false,
+    applies: (config) => {
+      if (config?.hu_board?.enabled === false) {
+        return { applies: false, reason: "hu_board.enabled is false in kj.config.yml — HU Board dashboard skipped" };
+      }
+      return true;
+    },
     describe: "Rebind HU Board to the next free port",
     async detect({ config }) {
       const port = config?.hu_board?.port || DEFAULT_HU_BOARD_PORT;

package/src/checks/runner.js

@@ -55,19 +55,35 @@ export async function runChecks(checks, ctx, options = {}) {
   const overrides = {};
 
   // Build applicable entries (skipped checks noted up front).
+  // A check.applies(config) may return:
+  //   - true / false — boolean form (back-compat).
+  //   - an object { applies: boolean, reason?: string } — when false, `reason`
+  //     is shown verbatim so users see WHY (e.g. "sonarqube.enabled is false
+  //     in kj.config.yml") instead of the opaque "Not applicable" message
+  //     that confused users debugging their config.
   for (const check of checks) {
-    if (typeof check.applies === "function" && !check.applies(config)) {
-      entries.push({
-        check,
-        status: STATUS.SKIPPED,
-        detail: "Not applicable for current configuration",
-        runMs: 0,
-        detectResult: null,
-        remediated: false,
-      });
-    } else {
+    if (typeof check.applies !== "function") {
+      entries.push({ check, status: null, detail: null, runMs: 0, detectResult: null, remediated: false });
+      continue;
+    }
+    const verdict = check.applies(config);
+    const isObj = verdict && typeof verdict === "object" && "applies" in verdict;
+    const applies = isObj ? Boolean(verdict.applies) : Boolean(verdict);
+    if (applies) {
       entries.push({ check, status: null, detail: null, runMs: 0, detectResult: null, remediated: false });
+      continue;
     }
+    const reason = (isObj && typeof verdict.reason === "string" && verdict.reason.trim())
+      ? verdict.reason.trim()
+      : "Not applicable for current configuration";
+    entries.push({
+      check,
+      status: STATUS.SKIPPED,
+      detail: reason,
+      runMs: 0,
+      detectResult: null,
+      remediated: false,
+    });
   }
 
   // Phase 1: detect in parallel with timeout.

package/src/checks/sonar.js

@@ -36,7 +36,7 @@ export function createSonarStatusCheck() {
       if (!sonarEnabled(config)) {
         return { ok: true, severity: "info", detail: "Disabled in config" };
       }
-      let reachable = false;
+      let reachable;
       try {
         reachable = await isSonarReachable(host);
       } catch {

package/src/checks/system.js

@@ -32,7 +32,7 @@ export function createGitRepoCheck() {
     label: "Git repository",
     strategy: STRATEGY.MANUAL,
     async detect() {
-      let gitOk = false;
+      let gitOk;
       try {
         gitOk = await ensureGitRepo();
       } catch {

package/src/checks/tokens.js

@@ -1,41 +1,83 @@
 /**
- * API token availability checks.
+ * Provider CLI availability checks (preflight).
  *
- * Provider tokens (ANTHROPIC_API_KEY / OPENAI_API_KEY / ...) are LAZY:
- * we only check them for providers that are actually used by at least one
- * active role in the current config.
+ * IMPORTANT — Karajan does NOT call provider APIs directly. There is no
+ * `@anthropic-ai/sdk`, no `openai`, no `@google/generative-ai` in
+ * package.json. Every active role spawns its agent CLI as a subprocess
+ * (`claude`, `codex`, `gemini`, `opencode`, `aider`). The CLI handles its
+ * own auth, typically via OAuth + on-disk token (Claude Code, Codex CLI,
+ * Gemini CLI). The user does NOT need to set ANTHROPIC_API_KEY etc. for
+ * Karajan to work.
  *
- * Strategy:
- *   - Required providers with no key → FAIL, strategy manual (we can't
- *     fetch an API key for the user). Fix hint includes the how-to URL.
- *   - Optional providers (opencode, aider) without key → WARN.
- *   - GH_TOKEN is checked when git.auto_pr=true, strategy prompt (we can
- *     launch `gh auth login` with user approval).
+ * Pre-v2.7.4 this module checked for ANTHROPIC_API_KEY / OPENAI_API_KEY /
+ * GEMINI_API_KEY env vars and FAILed preflight when missing — a false
+ * positive that blocked every user running Karajan as an MCP child of
+ * Claude Code (where `apiKeySource: "none"` is the norm). Replaced with a
+ * CLI-availability check that mirrors what the orchestrator actually does.
+ *
+ * GH_TOKEN is still checked when `git.auto_pr=true`, because that flow uses
+ * `git push` directly with the env var.
  */
 
 import { checkBinary } from "../utils/agent-detect.js";
-import { getRequiredProviderEnvs, hasEnvVar } from "../utils/provider-env.js";
+import { getRequiredProviderEnvs, normalizeProvider } from "../utils/provider-env.js";
 import { STRATEGY } from "./types.js";
 
 /**
- * A single provider env check. One is created per active provider.
+ * Map canonical provider name → the CLI binary Karajan actually spawns.
+ * Keep in sync with src/agents/index.js.
  */
-function createProviderTokenCheck(entry) {
+const PROVIDER_TO_CLI = Object.freeze({
+  anthropic: "claude",
+  openai: "codex",
+  google: "gemini",
+  opencode: "opencode",
+  aider: "aider",
+});
+
+/**
+ * Build a CLI-availability check for one provider.
+ *
+ * The check runs `<cli> --version`. If the binary is on PATH and exits 0,
+ * preflight passes — Karajan can spawn it. If the CLI is missing, preflight
+ * fails with the install URL we already track in PROVIDER_ENV.
+ *
+ * Note: we do NOT verify that the CLI is *authenticated*. Doing so would
+ * require provider-specific introspection (`claude doctor`, `codex login
+ * status`, ...), each with its own quirks and exit codes. If the CLI is
+ * present but not logged in, the agent will fail at the first request with
+ * a clear error — and the orchestrator surfaces that error already.
+ */
+function createProviderCliCheck(entry) {
+  const cli = PROVIDER_TO_CLI[entry.provider];
   return {
-    name: `token:${entry.provider}`,
-    label: `API token: ${entry.provider}`,
+    name: `cli:${entry.provider}`,
+    label: `${entry.provider} CLI (${cli})`,
     strategy: STRATEGY.MANUAL,
     async detect() {
-      const ok = hasEnvVar(entry);
-      if (ok) {
-        return { ok: true, severity: "info", detail: `${entry.envVars[0]} is set` };
+      if (!cli) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Unknown CLI for provider ${entry.provider}`,
+          extra: { provider: entry.provider },
+        };
+      }
+      const result = await checkBinary(cli);
+      if (result.ok) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: `${cli} on PATH (${result.version || "version unknown"})`,
+          extra: { provider: entry.provider, cli, version: result.version, path: result.path },
+        };
       }
       return {
         ok: false,
         severity: entry.optional ? "warn" : "fail",
-        detail: `${entry.envVars.join(" / ")} not set`,
-        fix: `Get an API key at ${entry.howToGetUrl} and export ${entry.envVars[0]}=...`,
-        extra: { provider: entry.provider, envVars: entry.envVars, howToGetUrl: entry.howToGetUrl },
+        detail: `${cli} not found on PATH`,
+        fix: `Install the ${cli} CLI: see ${entry.howToGetUrl}`,
+        extra: { provider: entry.provider, cli, howToGetUrl: entry.howToGetUrl },
       };
     },
   };
@@ -43,6 +85,8 @@ function createProviderTokenCheck(entry) {
 
 /**
  * GH token check + auto-remediation via `gh auth login` when it's installed.
+ * Kept from the previous version: this one IS legitimate because Karajan
+ * uses `gh` (or raw `git push`) directly when auto_pr is on.
  */
 function createGhTokenCheck() {
   return {
@@ -82,15 +126,24 @@ function createGhTokenCheck() {
 }
 
 /**
- * Build the list of token checks for the active config. Each active provider
- * gets one, plus conditional GH token when auto_pr is on.
+ * Build the list of CLI/token checks for the active config.
+ * - One CLI availability check per active provider (claude / codex / gemini / ...).
+ * - One GH token check, conditional on git.auto_pr.
+ *
+ * Function name kept as `getTokenChecks` for backward compat with
+ * preflight-checks.js, even though the bulk of the checks no longer touch
+ * tokens at all. Tracked: rename to `getProviderChecks` in a follow-up
+ * once consumers are updated.
  *
  * @param {Object} config
  * @returns {import("./types.js").Check[]}
  */
 export function getTokenChecks(config) {
   const required = getRequiredProviderEnvs(config);
-  const checks = required.map(createProviderTokenCheck);
+  const checks = required.map(createProviderCliCheck);
   checks.push(createGhTokenCheck());
   return checks;
 }
+
+// Re-export for tests that need to introspect the mapping.
+export { PROVIDER_TO_CLI, normalizeProvider };

package/src/cli/_shared.js

@@ -0,0 +1,30 @@
+import { applyRunOverrides, loadConfig, validateConfig } from "../config.js";
+import { createLogger } from "../utils/logger.js";
+
+/**
+ * Wraps a CLI action so it loads + validates config, builds the logger,
+ * and fires the anonymous cli_command telemetry event before invoking
+ * the real command body. Shared across every register-*.js module so
+ * each one doesn't need to re-import the config plumbing.
+ *
+ * @param {string} pkgVersion       Current kj version (used for telemetry).
+ * @param {string} commandName      The CLI command name being executed.
+ * @param {object} flags            Flags parsed by Commander.
+ * @param {(ctx: { config: object, logger: object, flags: object }) => Promise<any>} fn
+ *                                  Body of the command — receives the merged config + logger.
+ */
+export async function withConfig(pkgVersion, commandName, flags, fn) {
+  const { config } = await loadConfig();
+  const merged = applyRunOverrides(config, flags || {});
+  validateConfig(merged, commandName);
+  const logger = createLogger(merged.output.log_level);
+
+  // Telemetry: anonymous cli_command event (non-blocking).
+  import("../utils/telemetry.js")
+    .then(({ sendTelemetryEvent }) =>
+      sendTelemetryEvent("cli_command", { command: commandName, version: pkgVersion }, merged)
+    )
+    .catch(() => {});
+
+  return fn({ config: merged, logger, flags });
+}