karajan-code 4.70.4 → 5.0.1

package/src/cli/register-pipeline.js

@@ -1,8 +1,9 @@
 import { initCommand } from "../commands/init.js";
 import { ollamaStartCommand, ollamaStopCommand, ollamaStatusCommand, ollamaPullCommand } from "../commands/ollama.js";
 import { configCommand } from "../commands/config.js";
+import { checkSecretsCommand } from "../config/secrets.js";
 import { codeCommand } from "../commands/code.js";
-import { reviewCommand } from "../commands/review.js";
+import { retire } from "./retired-commands.js";
 import { tournamentCommand } from "../commands/tournament.js";
 import { resolveTaskInput } from "../utils/task-file.js";
 import { reviewGateCommand, solomonCommand } from "../commands/review-gate.js";
@@ -10,9 +11,6 @@ import { scanCommand } from "../commands/scan.js";
 import { installToolsCommand } from "../commands/install-tools.js";
 import { doctorCommand } from "../commands/doctor.js";
 import { reportCommand } from "../commands/report.js";
-import { runCommandHandler } from "../commands/run.js";
-import { statusCommand } from "../commands/status.js";
-import { loadPlan } from "../plan/plan-store.js";
 import { withConfig } from "./_shared.js";
 import { publishPrReview } from "../review/publish-pr.js";
 import { verifyPrReview } from "../review/verify-pr.js";
@@ -52,139 +50,15 @@ export function registerPipeline(program, { pkgVersion }) {
     .description("Show current config")
     .option("--json", "Show as JSON")
     .option("--edit", "Open config in $EDITOR for editing")
+    .option("--check-secrets <file>", "Exit 1 when a project kj.config.yml (or - for stdin) holds a secret (ADR 0032)")
     .action(async (flags) => {
+      if (flags.checkSecrets) return checkSecretsCommand(flags.checkSecrets);
       await configCommand(flags);
     });
 
-  program
-    .command("run")
-    .description("Run coder+sonar+reviewer loop")
-    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
-    .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
-    .option("-y, --yes", "Skip the cwd confirmation prompt (CI / scripted runs).")
-    .option("--non-interactive", "Agents/CI: auto-answer prompts with their safe defaults (warn → continue) and stop with exit code 1 when there is none (fail). Also enabled by KJ_NON_INTERACTIVE=1.")
-    .option("--planner <name>")
-    .option("--coder <name>")
-    .option("--reviewer <name>")
-    .option("--refactorer <name>")
-    .option("--planner-model <name>")
-    .option("--coder-model <name>")
-    .option("--reviewer-model <name>")
-    .option("--refactorer-model <name>")
-    .option("--profile <name>", "Model profile for every role without an explicit model: frugal | standard | deep (the reviewer never goes below standard)")
-    .option("--enable-planner")
-    .option("--enable-reviewer")
-    .option("--enable-refactorer")
-    .option("--enable-researcher")
-    .option("--enable-tester")
-    .option("--enable-security")
-    .option("--enable-impeccable")
-    .option("--enable-perf")
-    .option("--enable-triage")
-    .option("--enable-discover")
-    .option("--enable-architect")
-    .option("--plan <planId>", "Plan ID from kj plan. Loads persisted plan context and skips researcher/architect/planner.")
-    // PR4: launch a single HU (or comma-separated list) instead of the
-    // entire plan. The board uses this for the per-HU ▶ button so the
-    // user can re-run only a failed HU without restarting the whole
-    // plan. Requires --plan to also be set.
-    .option("--hu <huIds>", "Comma-separated HU IDs to run. When set, the plan's other HUs are skipped. Requires --plan.")
-    .option("--enable-hu-reviewer")
-    .option("--hu-file <path>", "YAML file with HU stories to certify before coding")
-    .option("--enable-serena")
-    .option("--mode <name>")
-    .option("--max-iterations <n>")
-    .option("--max-iteration-minutes <n>")
-    .option("--max-total-minutes <n>")
-    .option("--base-branch <name>")
-    .option("--base-ref <ref>")
-    .option("--coder-fallback <name>")
-    .option("--reviewer-fallback <name>")
-    .option("--reviewer-retries <n>")
-    .option("--auto-commit")
-    .option("--auto-push")
-    .option("--auto-pr")
-    .option("--enable-ci", "Enable Karajan CI (early PR + dispatch comments/reviews)")
-    .option("--branch-prefix <prefix>")
-    .option("--task-type <type>", "Explicit task type: sw, infra, doc, add-tests, refactor")
-    .option("--methodology <name>")
-    .option("--no-auto-rebase")
-    .option("--no-sonar")
-    .option("--enable-sonarcloud", "Enable SonarCloud scan (complementary to SonarQube)")
-    .option("--no-sonarcloud")
-    .option("--checkpoint-interval <n>", "Minutes between interactive checkpoints (default: 5)")
-    .option("--step", "Pause after each iteration with a report and ask before continuing")
-    .option("--parallel <n>", "Concurrent HU lanes for plan runs (default: 1, sequential)")
-    .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
-    .option("--pg-project <projectId>", "Planning Game project ID")
-    .option("--auto-simplify", "Auto-simplify pipeline for simple tasks (disable reviewer/tester)")
-    .option("--no-auto-simplify", "Force full pipeline regardless of triage level")
-    .option("--smart-models", "Enable smart model selection based on triage complexity")
-    .option("--no-smart-models", "Disable smart model selection")
-    .option("--design", "Activate design refactoring mode (impeccable role applies design changes)")
-    .option("--domain <text-or-path>", "Domain knowledge: inline text or path to .md file")
-    .option("--skills-mode <mode>", "Skill detection mode: auto|regex|semantic|none (default: auto)")
-    .option("--brain <mode>", "Brain decisor: on|off (default: on). When off, only legacy flags drive routing.")
-    .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
-    .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
-    .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
-    .option("--autonomy <level>", "Autonomy level: interactive | assisted | autonomous (default: interactive)")
-    .option("--autonomous", "Shortcut for --autonomy autonomous: the Arbiter resolves every gate, no human prompts")
-    .option("--no-rag-update", "Skip the pre-run RAG drift check (KJC-TSK-0455). Same as config.rag.autoUpdate.onRun=false.")
-    .option("--dry-run", "Show what would be executed without running anything")
-    .option("--json", "Output JSON only (no styled display)")
-    .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")
-    .option("-v, --verbose", "Show full agent output (stream-json, raw lines)")
-    .action(async (task, flags) => {
-      // KJC-BUG-0448: run's --profile is the model profile; harden and check use
-      // --profile for the harness, so the config loader reads modelProfile.
-      if (flags.profile) flags.modelProfile = flags.profile;
-      await withConfig(pkgVersion, "run", flags, async ({ config, logger }) => {
-        // If `--plan <id>` was passed and the user didn't provide a task
-        // argument or --task-file, fall back to the task embedded in the
-        // plan JSON. The whole point of `kj plan generate` is that the
-        // task is captured once and re-used; forcing the user to repeat
-        // --task-file on every run is friction with no upside.
-        let effectiveTask = task;
-        if (!task && !flags.taskFile && flags.plan) {
-          // config.projectDir is only populated post-init; before runFlow
-          // it can still be undefined. Plans are stored under cwd, so
-          // that's the correct fallback for the lookup.
-          const projectDir = config.projectDir || process.cwd();
-          const plan = await loadPlan(projectDir, flags.plan);
-          if (plan?.task && String(plan.task).trim()) {
-            effectiveTask = plan.task;
-          }
-        }
-        const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
-        const res = await runCommandHandler({ task: resolvedTask, config, logger, flags });
-        // KJC-TSK-0674 (issue #1289): an aborted run (spec-review cancel,
-        // unanswerable non-interactive gate) must be observable by CI.
-        if (res?.aborted) process.exitCode = 1;
-      });
-    });
-
-  program
-    .command("autorun")
-    .description("Unattended delivery: spec → plan → run all HUs → outcome (defaults to --autonomous)")
-    .argument("[task]", "Spec/task description (or use --task-file)")
-    .option("--task-file <path>", "Read the spec from a file (e.g. spec.md)")
-    .option("--autonomy <level>", "interactive | assisted | autonomous (default: autonomous)")
-    .option("--autonomous", "Shortcut for --autonomy autonomous")
-    .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
-    .action(async (task, flags) => {
-      const code = await withConfig(pkgVersion, "autorun", flags, async ({ config, logger }) => {
-        const { autorunCommand } = await import("../commands/autorun.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
-        const res = await autorunCommand({ task: resolvedTask, config, logger, flags });
-        return res?.ok ? 0 : 1;
-      });
-      if (Number.isInteger(code)) process.exit(code);
-    });
-
   program
     .command("code")
-    .description("Run only coder")
+    .description("Have the coder declared in your panel write (--agent, --card)")
     .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--coder <name>")
@@ -245,8 +119,8 @@ export function registerPipeline(program, { pkgVersion }) {
 
   program
     .command("review")
-    .description("Run only reviewer (--staged/--check: v4 cross-AI gate with recorded verdict)")
-    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
+    .description("Cross-AI review gate: --staged/--check/--range record a verdict tied to the exact diff")
+    .argument("[task]", "What the change does, for the reviewer (optional; or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--reviewer <name>")
     .option("--reviewer-model <name>")
@@ -310,8 +184,7 @@ export function registerPipeline(program, { pkgVersion }) {
           await reviewGateCommand({ config, logger, flags: { ...flags, task: gateTask } });
           return;
         }
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
-        await reviewCommand({ task: resolvedTask, config, logger, baseRef: flags.baseRef });
+        retire("review");
       });
     });
 
@@ -364,14 +237,6 @@ export function registerPipeline(program, { pkgVersion }) {
       }
     });
 
-  program
-    .command("status")
-    .description("Show pipeline dashboard with HU progress")
-    .option("-n, --lines <n>", "Max log lines to read", "50")
-    .action(async (flags) => {
-      await statusCommand({ lines: Number(flags.lines) });
-    });
-
   program
     .command("report")
     .description("Show latest session report")

package/src/cli/register-plan.js

@@ -1,5 +1,4 @@
 import {
-  planGenerateCommand,
   planListCommand,
   planShowCommand,
   planReadyCommand,
@@ -13,113 +12,23 @@ import {
   planUnshareCommand,
 } from "../commands/plan.js";
 import { planLicenseCommand } from "../commands/plan/license.js";
-import { parseCanvasMarkdown } from "../canvas/parse-md.js";
-import { validateCanvas } from "../canvas/validate.js";
-import { canvasToTask } from "../canvas/to-flat.js";
 import { withConfig } from "./_shared.js";
+import { retire } from "./retired-commands.js";
 
 /**
  * Register the `plan` parent command and every sub-command that lives
- * under it (generate / list / show / ready / validate / delete /
- * add-hu / remove-hu). Centralising plan management here keeps the
- * REASONS Canvas auto-detection logic in one file alongside the
- * planner entrypoint.
+ * under it (list / show / ready / validate / delete / add-hu / remove-hu...).
  */
 export function registerPlan(program, { pkgVersion }) {
-  const plan = program.command("plan").description("Plan management (generate, review, approve, execute)");
+  const plan = program.command("plan").description("Plan management (list, show, validate, approve)");
 
+  // KJC-TSK-1317: retired in 5.0; it answers to say what replaced it.
   plan
-    .command("generate", { isDefault: true })
-    .description("Generate implementation plan with HUs")
-    .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
-    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
-    .option("--planner <name>")
-    .option("--planner-model <name>")
-    .option("--context <text>", "Additional context for the planner")
-    .option("--json", "Output raw JSON plan")
-    // Tests-first quality knobs (v2.7.5). Default is "thorough":
-    // when the planner skips acceptance_tests on some HUs, run a
-    // focused synthesizer pass to fill them in. Disable with these
-    // flags only if you explicitly want a fast / sketch plan.
-    .option("--no-tests-synth", "Skip the tests-synthesizer pass that fills in missing acceptance_tests")
-    .option("--no-plan-review", "Skip the high-level plan reviewer pass (gaps / deps / overlap / order)")
-    .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
-    .option("--quick", "Sketch mode — skip every quality pass after the initial planner call")
-    .option("--no-preflight-hu", "Skip auto-injection of [PREFLIGHT-000] HU at the top of the generated plan")
-    .option("--use-onboarding", "Inject the cached Architecture Brief (~/.karajan/onboarding/<slug>.md) into the planner context")
-    .option("-y, --yes", "Skip the project-name prompt (use the auto-derived default).")
-    .option("--no-interactive", "Force non-interactive mode (no prompts, use defaults).")
-    .action(async (task, flags) => {
-      await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
-        const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
-
-        // REASONS Canvas auto-detection: a SPEC that contains
-        // `## REASONS:Section` headings is treated as a structured
-        // Canvas — parsed + validated BEFORE the planner runs. This
-        // catches broken acceptance tests (jq syntax, bash parse,
-        // gherkin missing Given/Then, the 2026-04-29 as-binding
-        // misuse class) at plan-time, without spending LLM dollars.
-        //
-        // Detection by file CONTENTS, not by CLI flag — the Canvas
-        // format is the signal. Flat SPECs without REASONS sections
-        // continue through the legacy path unchanged (back-compat).
-        if (typeof resolvedTask === "string" && /^##\s+REASONS:/m.test(resolvedTask)) {
-          let parsed;
-          try {
-            parsed = parseCanvasMarkdown(resolvedTask);
-          } catch (err) {
-            throw new Error(`Canvas parse error: ${err.message}`, { cause: err });
-          }
-          const validation = validateCanvas(parsed);
-          if (!validation.valid) {
-            const lines = ["Canvas validation failed."];
-            if (validation.schemaIssues) {
-              lines.push("Schema issues:");
-              for (const issue of validation.schemaIssues) {
-                lines.push(`  - ${issue.path?.map((p) => p.key).join(".") || "(root)"}: ${issue.message}`);
-              }
-            }
-            if (validation.testIssues) {
-              lines.push("Acceptance test issues:");
-              for (const issue of validation.testIssues) {
-                lines.push(`  - Operation #${issue.operationIndex + 1} "${issue.operationTitle}", test #${issue.testIndex + 1} (${issue.type}, ${issue.kind}):`);
-                lines.push(`      ${issue.content}`);
-                lines.push(`      → ${issue.error}`);
-              }
-            }
-            throw new Error(lines.join("\n"));
-          }
-          // Pass the Canvas-derived flat task to the existing planner.
-          // Norms + Safeguards ride along under explicit headings the
-          // coder prompt can grep for.
-          const taskFromCanvas = canvasToTask(validation.canvas);
-          // KJC-TSK-0348: remember WHERE the Canvas lived on disk so
-          // `kj sync --apply` later knows which file to patch.
-          let sourceCanvasPath = null;
-          if (typeof flags?.taskFile === "string" && flags.taskFile.length > 0) {
-            const path = await import("node:path");
-            sourceCanvasPath = path.isAbsolute(flags.taskFile)
-              ? flags.taskFile
-              : path.resolve(config.projectDir || process.cwd(), flags.taskFile);
-          }
-          await planGenerateCommand({ task: taskFromCanvas, config, logger, flags, sourceCanvasPath });
-          return;
-        }
-        await planGenerateCommand({
-          task: resolvedTask, config, logger, json: flags.json, context: flags.context,
-          flags: {
-            noTestsSynth: flags.testsSynth === false,
-            noPlanReview: flags.planReview === false,
-            quick: Boolean(flags.quick),
-            yes: Boolean(flags.yes),
-            interactive: flags.interactive,
-            preflightHu: flags.preflightHu !== false, // KJC-TSK-0397
-            useOnboarding: Boolean(flags.useOnboarding), // KJC-TSK-0384 PR 3
-          },
-        });
-      });
-    });
+    .command("generate", { hidden: true })
+    .argument("[args...]")
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(() => retire("plan generate"));
 
   plan.command("list").description("List all plans").action(async (flags) => {
     await withConfig(pkgVersion, "plan", flags, async ({ config }) => {

package/src/cli/register-roles-skills.js

@@ -10,7 +10,7 @@ import { withConfig } from "./_shared.js";
 export function registerRolesSkills(program, { pkgVersion }) {
   program
     .command("skills [action] [args...]")
-    .description("Manage the skill cache (list | clear-cache | sync-addyosmani | list-addyosmani) and, through atril, the .karajan store (search | route | scan | install | remove | graph | enrich | config)")
+    .description("Manage the skill cache (list | clear-cache | sync-addyosmani | list-addyosmani) and, through atril, the .karajan store (search, which translates a non-English query first | route | scan | install | remove | graph | enrich | config)")
     // KJC-TSK-1193: atril's options (--json, --kind, --role, --root) travel to atril untouched.
     .allowUnknownOption()
     .action(async (action, args) => {

package/src/cli/retired-commands.js

@@ -0,0 +1,49 @@
+// KJC-TSK-1317: the pipeline commands retired in 5.0. In v4 the host agent does
+// the work and kj governs it, so kj no longer drives a coder of its own. Each
+// retired command still answers, hidden from the help, to say what replaced it.
+
+const GUIDE = "https://github.com/manufosela/karajan-code/blob/main/MIGRATION-v5.md";
+const BY_THE_AGENT = "Your agent (Claude Code, OpenCode...) does the work now and kj governs it: split the task with kj brief planner + kj hu add, one lane per card with kj worktree start, and kj review --staged before every commit.";
+const brief = (role) => `Use kj brief ${role}: your agent applies the role itself.`;
+
+/** Retired command → [how it is named, what replaces it]. */
+export const RETIRED = {
+  run: ["kj run", BY_THE_AGENT],
+  autorun: ["kj autorun", BY_THE_AGENT],
+  resume: ["kj resume", BY_THE_AGENT],
+  standby: ["kj standby", BY_THE_AGENT],
+  "plan generate": ["kj plan generate", "Your agent plans with kj brief planner and puts each piece on the board with kj hu add."],
+  status: ["kj status", "The HU board shows the work in progress: kj board start."],
+  undo: ["kj undo", "Every reviewed step is its own commit: undo it with git."],
+  triage: ["kj triage", brief("triage")],
+  researcher: ["kj researcher", brief("researcher")],
+  architect: ["kj architect", brief("architect")],
+  review: ["kj review with a task", "Use kj review --staged: it reviews the exact diff you are about to commit."],
+};
+
+/** The notice a retired command (or MCP tool) answers with. */
+export const retiredMessage = (name) => {
+  const [label, instead] = RETIRED[name];
+  return `${label} was retired in 5.0. ${instead}\nMigration guide: ${GUIDE}`;
+};
+
+/** Print the notice and fail, without starting anything. */
+export const retire = (name) => {
+  process.stderr.write(`${retiredMessage(name)}\n`);
+  process.exitCode = 1;
+};
+
+const TOP_LEVEL = ["run", "autorun", "resume", "standby", "status", "undo", "triage", "researcher", "architect"];
+
+/** Register the retired top-level commands, hidden, taking any argument. */
+export function registerRetired(program) {
+  for (const name of TOP_LEVEL) {
+    program
+      .command(name, { hidden: true })
+      .description("Retired in 5.0")
+      .argument("[args...]")
+      .allowUnknownOption()
+      .allowExcessArguments()
+      .action(() => retire(name));
+  }
+}

package/src/cli.js

@@ -10,11 +10,12 @@ import { registerPlan } from "./cli/register-plan.js";
 import { registerRolesSkills } from "./cli/register-roles-skills.js";
 import { registerMeta } from "./cli/register-meta.js";
 import { registerSonar } from "./cli/register-sonar.js";
-import { registerStandby } from "./cli/register-standby.js";
+import { registerRetired } from "./cli/retired-commands.js";
 import { printUpdateNotice } from "./utils/update-check.js";
 import { printWelcomeScreen } from "./utils/welcome.js";
 import { migrateKjToKarajan } from "./utils/home-migration.js";
 import { pinGitDiffFormat } from "./utils/git-diff-format.js";
+import { pinGhAccount } from "./utils/gh-account.js";
 
 // KJC-BUG-0408: every git kj runs prints a/ and b/, whatever the user's gitconfig says.
 pinGitDiffFormat();
@@ -65,8 +66,8 @@ program.addHelpText(
   `
 Getting started (the basics — start here):
   kj init             Set up Karajan in this project (run once)
-  kj run "<task>"     Build or fix something end-to-end (coder + review)
-  kj plan "<task>"    Break a task into user stories first, then run them
+  kj hu add "<title>" Put a piece of work on the board before it starts
+  kj review --staged  Have another AI review the diff you are about to commit
   kj doctor           Check your environment is ready
   kj harden           Add quality git hooks + CI to any repo
 
@@ -78,7 +79,7 @@ registerPlan(program, { pkgVersion: PKG_VERSION });
 registerRolesSkills(program, { pkgVersion: PKG_VERSION });
 registerMeta(program, { pkgVersion: PKG_VERSION });
 registerSonar(program);
-registerStandby(program);
+registerRetired(program);
 
 /**
  * Find subcommands whose name is "close enough" to a typo. Used by the
@@ -124,7 +125,7 @@ function levenshtein(a, b) {
 program.action(async (_opts, command) => {
   if (command.args.length > 0) {
     const bad = command.args[0];
-    const known = program.commands.map((c) => c.name()).sort();
+    const known = program.commands.filter((c) => !c._hidden).map((c) => c.name()).sort();
     process.stderr.write(`error: '${bad}' no es un comando válido de kj\n`);
     const suggestions = suggestSimilarCommands(bad, known);
     if (suggestions.length > 0) {
@@ -140,6 +141,18 @@ program.action(async (_opts, command) => {
   printWelcomeScreen({ version: PKG_VERSION, config });
 });
 
+// KJC-BUG-0458 (ADR 0040): every gh kj runs uses the repo's account, not whichever another
+// session left active. A broken config is each command's to report; here it only means the
+// account comes from the remote. Kept in a top-level try: the SEA build wraps from here on.
+try {
+  const { config } = await loadConfig().catch(() => ({ config: null }));
+  const githubAccount = config?.review?.github_account ?? null;
+  const ghPin = pinGhAccount({ account: githubAccount });
+  if (githubAccount && ghPin.reason) console.warn(`\x1b[33m[warn]\x1b[0m review.github_account: ${ghPin.reason}`);
+} catch (err) {
+  console.warn(`\x1b[33m[warn]\x1b[0m gh account not pinned: ${err.message}`);
+}
+
 // One-shot ~/.kj/ → ~/.karajan/ consolidation. Idempotent via marker
 // file; failures non-blocking. See src/utils/home-migration.js.
 // Static import — the migrator runs on every kj invocation, no

package/src/commands/agent-run.js

@@ -8,10 +8,8 @@
 import { createAgent, getAvailableAgents } from "../agents/index.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
 
-export async function agentRunCommand({ agent, task, config = {}, logger = null, flags = {} }) {
-  if (!task || !task.trim()) {
-    throw new Error("kj agent run requires a task: kj agent run <agent> \"<task>\"");
-  }
+// The agent must be one kj supports AND installed here; both errors name what is available.
+async function assertAgentAvailable(agent) {
   const known = getAvailableAgents().map((a) => a.name);
   const detected = await detectAvailableAgents();
   const up = detected.filter((a) => a.available).map((a) => a.name).join(", ") || "none";
@@ -22,15 +20,44 @@ export async function agentRunCommand({ agent, task, config = {}, logger = null,
   if (!entry?.available) {
     throw new Error(`agent "${agent}" is not available on this machine (available: ${up}) — install its CLI or pick another`);
   }
+}
 
-  let timeoutMs;
-  if (flags.timeoutMinutes !== undefined) {
-    const minutes = Number(flags.timeoutMinutes);
-    if (!Number.isFinite(minutes) || minutes <= 0) {
-      throw new Error(`--timeout-minutes must be a positive number, got "${flags.timeoutMinutes}"`);
-    }
-    timeoutMs = minutes * 60000;
+function timeoutMsOf(flags) {
+  if (flags.timeoutMinutes === undefined) return undefined;
+  const minutes = Number(flags.timeoutMinutes);
+  if (!Number.isFinite(minutes) || minutes <= 0) {
+    throw new Error(`--timeout-minutes must be a positive number, got "${flags.timeoutMinutes}"`);
   }
+  return minutes * 60000;
+}
+
+function delegationResult(agent, result) {
+  return {
+    ok: Boolean(result?.ok),
+    agent,
+    output: result?.output || "",
+    error: result?.error || null,
+    usage: result?.tokens_out != null
+      ? { tokens_in: result.tokens_in ?? null, tokens_out: result.tokens_out, cached_tokens: result.cached_tokens ?? null }
+      : null,
+  };
+}
+
+function printResult(res, json) {
+  if (json) {
+    console.log(JSON.stringify(res));
+    return;
+  }
+  if (res.output) console.log(res.output);
+  if (!res.ok && res.error) console.error(res.error);
+}
+
+export async function agentRunCommand({ agent, task, config = {}, logger = null, flags = {} }) {
+  if (!task || !task.trim()) {
+    throw new Error("kj agent run requires a task: kj agent run <agent> \"<task>\"");
+  }
+  await assertAgentAvailable(agent);
+  const timeoutMs = timeoutMsOf(flags);
 
   // --json must emit ONLY the serialized result — no informational lines,
   // and a crash of the delegated subprocess still yields one JSON payload.
@@ -43,21 +70,8 @@ export async function agentRunCommand({ agent, task, config = {}, logger = null,
     result = { ok: false, output: "", error: err.message };
   }
 
-  const res = {
-    ok: Boolean(result?.ok),
-    agent,
-    output: result?.output || "",
-    error: result?.error || null,
-    usage: result?.tokens_out != null
-      ? { tokens_in: result.tokens_in ?? null, tokens_out: result.tokens_out, cached_tokens: result.cached_tokens ?? null }
-      : null,
-  };
-  if (flags.json) {
-    console.log(JSON.stringify(res));
-  } else {
-    if (res.output) console.log(res.output);
-    if (!res.ok && res.error) console.error(res.error);
-  }
+  const res = delegationResult(agent, result);
+  printResult(res, flags.json);
   process.exitCode = res.ok ? 0 : 1;
   return res;
 }