karajan-code 2.7.1 → 2.7.3

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.7.1 released** — Patch that restores SEA binary publishing (broken since v2.4.1). GitHub Releases now ship `linux-x64`, `darwin-arm64` and `win-x64` binaries plus SHA256 checksums again. Carries the full v2.7.0 feature set: [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) as Karajan's first-source process catalog (20+ lifecycle workflows — TDD, code-review-and-quality, security-and-hardening, performance-optimization, git-workflow-and-versioning, CI/CD, debugging-and-error-recovery, spec-driven-development, planning-and-task-breakdown…) injected per role **before** OpenSkills stack skills, shallow-cloned into `~/.karajan/agent-skills/` and refreshed weekly via `git pull`. Role → slug map: `tester → test-driven-development`, `reviewer → code-review-and-quality`, `security → security-and-hardening`, `architect → spec-driven-development + api-and-interface-design`, `coder → incremental-implementation + debugging-and-error-recovery`... New CLI: `kj skills sync-addyosmani`, `kj skills list-addyosmani`. New config: `skills.sources`, `skills.addyosmani.{enabled,refreshDays,repoUrl}`. See [CHANGELOG.md](./CHANGELOG.md) for full history and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
+> **v2.7.3 released** — Three dogfooding fixes: (1) task can now come from a `.md` file — `kj run --task-file spec.md` or MCP `kj_run({ taskFile: "spec.md" })`, same for `kj plan/audit/code/review/discover/triage/researcher/architect`; (2) CLI commands finally write `.kj/run.log` like MCP does, so `kj-tail` works whether Claude Code launches `kj` via Bash or the MCP tool; (3) Node 18 LTS is really supported now (preflight no longer refuses 18 with a bogus "needs Node 20" message), and `kj-tail` v1.38.0 waits for the log file to appear instead of exiting. Carries the full v2.7 skills story: [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) as Karajan's first-source process catalog (20+ lifecycle workflows) injected per role **before** OpenSkills stack skills, `summary.md` now surfaces which slugs shaped each role's prompt. See [CHANGELOG.md](./CHANGELOG.md) for full history and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 

package/bin/kj-tail

@@ -4,7 +4,7 @@
 
 set -euo pipefail
 
-VERSION="1.36.0"
+VERSION="1.38.0"
 
 # ── Colors ──────────────────────────────────────────────
 RED='\033[0;31m'
@@ -94,15 +94,42 @@ PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
 LOG_FILE="${PROJECT_DIR}/.kj/run.log"
 
 # ── Locate log ──────────────────────────────────────────
+# When the log does not exist yet, kj-tail stays open and polls until any
+# `kj` / `kj_*` invocation creates it. Exit with Ctrl-C. This used to be a
+# hard exit, which forced the user to time `kj-tail` start vs. the command;
+# too easy to miss early lines. Follow-mode and snapshot mode both get this.
 if [[ ! -f "$LOG_FILE" ]]; then
-  echo -e "${RED}No run log found at ${LOG_FILE}${RESET}"
-  echo ""
-  echo "The run log is created when Karajan starts a pipeline."
-  echo "Make sure you're in the project directory, or pass it as argument:"
+  if [[ "$FOLLOW" == "false" ]]; then
+    # Snapshot mode (-s): nothing to print, say so and exit cleanly.
+    echo -e "${YELLOW}No run log at ${LOG_FILE} yet.${RESET}"
+    echo ""
+    echo "The log is created when Karajan starts a pipeline — run any of:"
+    echo "  kj run \"...\"    kj audit    kj code    kj review    kj plan"
+    echo "  mcp__karajan-mcp__kj_run / kj_audit / kj_code / kj_review / kj_plan ..."
+    echo ""
+    exit 0
+  fi
+
+  echo -e "${YELLOW}Waiting for run log to appear at ${LOG_FILE}${RESET}"
+  echo -e "${DIM}(It is created the moment you run any kj command that invokes the orchestrator or a role.${RESET}"
+  echo -e "${DIM} Ctrl-C to stop waiting. Triggers: kj run/audit/code/review/plan/discover/triage/researcher/architect, or the same via MCP.)${RESET}"
   echo ""
-  echo "  kj-tail /path/to/project"
+  # Ensure parent dir exists so we can poll even on a fresh project
+  mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+  # Poll every 500ms until the file shows up (low CPU, visible responsiveness).
+  # Cap at 4h (28800 ticks) to avoid infinite stuck monitors; after the cap we
+  # exit 0 so tmux/screen panes don't linger as errors.
+  tick=0
+  while [[ ! -f "$LOG_FILE" ]]; do
+    sleep 0.5
+    tick=$((tick + 1))
+    if (( tick >= 28800 )); then
+      echo -e "${YELLOW}Still no run log after 4h — exiting. Re-run kj-tail when ready.${RESET}"
+      exit 0
+    fi
+  done
+  echo -e "${GREEN}Log appeared — streaming...${RESET}"
   echo ""
-  exit 1
 fi
 
 # ── Filter & colorize ──────────────────────────────────
@@ -248,6 +275,17 @@ filter_line() {
     return
   fi
 
+  # Skills (addyosmani catalog + OpenSkills marketplace)
+  if [[ "$clean" == *"[skills:"* ]] || [[ "$clean" == *"[skills]"* ]]; then
+    # Highlight failures/unavailability in yellow, successes in magenta
+    if [[ "$clean" == *"unavailable"* ]] || [[ "$clean" == *"would have used"* ]]; then
+      echo -e "${prefix}${YELLOW}  ├─ 🎯 ${clean}${RESET}"
+    else
+      echo -e "${prefix}${MAGENTA}  ├─ 🎯 ${clean}${RESET}"
+    fi
+    return
+  fi
+
   # TDD
   if [[ "$clean" == *"TDD"* ]] || [[ "$clean" == *"tdd"* ]]; then
     echo -e "${prefix}${GREEN}  ├─ 📋 ${clean}${RESET}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.7.1",
+  "version": "2.7.3",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/checks/node.js

@@ -1,12 +1,18 @@
 /**
- * Node.js runtime version check. Requires Node >= 20 (minimum version that
- * ships structuredClone, Array.prototype.findLast, AbortSignal.timeout, and
- * stable fetch). Strategy: manual — we cannot auto-upgrade the runtime.
+ * Node.js runtime version check. Requires Node >= 18 — the LTS baseline that
+ * ships every runtime feature Karajan needs: ESM support, `fetch` (built-in),
+ * `structuredClone` (17+), `AbortSignal.timeout` (17.3+), and
+ * `Array.prototype.findLast` / `findLastIndex` (18+). Nothing in the runtime
+ * code path uses Node 20+ APIs (no `Promise.withResolvers`, no
+ * `Object.groupBy`, no `Set.prototype.union/intersection`, no
+ * `Array.prototype.toSorted`). Strategy: manual — we cannot auto-upgrade the
+ * runtime. Users on older Node get a clear upgrade instruction with nvm + brew
+ * hints instead of a silent runtime crash.
  */
 
 import { STRATEGY } from "./types.js";
 
-export const MIN_NODE_MAJOR = 20;
+export const MIN_NODE_MAJOR = 18;
 
 /**
  * Accepts a version string in the form "v20.12.1" or "20.12.1" and returns

package/src/cli.js

@@ -76,7 +76,8 @@ program
 program
   .command("run")
   .description("Run coder+sonar+reviewer loop")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file to read from a .md file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md). Alternative to the positional task argument.")
   .option("--planner <name>")
   .option("--coder <name>")
   .option("--reviewer <name>")
@@ -138,32 +139,40 @@ program
   .option("-v, --verbose", "Show full agent output (stream-json, raw lines)")
   .action(async (task, flags) => {
     await withConfig("run", flags, async ({ config, logger }) => {
-      await runCommandHandler({ task, config, logger, flags });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await runCommandHandler({ task: resolvedTask, config, logger, flags });
     });
   });
 
 program
   .command("code")
   .description("Run only coder")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--coder <name>")
   .option("--coder-model <name>")
   .action(async (task, flags) => {
     await withConfig("code", flags, async ({ config, logger }) => {
-      await codeCommand({ task, config, logger });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await codeCommand({ task: resolvedTask, config, logger });
     });
   });
 
 program
   .command("review")
   .description("Run only reviewer")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--reviewer <name>")
   .option("--reviewer-model <name>")
   .option("--base-ref <ref>")
   .action(async (task, flags) => {
     await withConfig("review", flags, async ({ config, logger }) => {
-      await reviewCommand({ task, config, logger, baseRef: flags.baseRef });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await reviewCommand({ task: resolvedTask, config, logger, baseRef: flags.baseRef });
     });
   });
 
@@ -248,15 +257,18 @@ const plan = program.command("plan").description("Plan management (generate, rev
 plan
   .command("generate", { isDefault: true })
   .description("Generate implementation plan with HUs")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --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")
   .action(async (task, flags) => {
     await withConfig("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 });
       const { planGenerateCommand } = await import("./commands/plan.js");
-      await planGenerateCommand({ task, config, logger, json: flags.json, context: flags.context });
+      await planGenerateCommand({ task: resolvedTask, config, logger, json: flags.json, context: flags.context });
     });
   });
 
@@ -317,65 +329,83 @@ plan.command("remove-hu").description("Remove HU from plan").argument("<planId>"
 program
   .command("discover")
   .description("Analyze task for gaps, ambiguities and missing info")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--mode <name>", "Discovery mode: gaps|momtest|wendel|classify|jtbd", "gaps")
   .option("--discover <name>", "Override discover agent")
   .option("--discover-model <name>", "Override discover model")
   .option("--json", "Output raw JSON")
   .action(async (task, flags) => {
     await withConfig("discover", flags, async ({ config, logger }) => {
-      await discoverCommand({ task, config, logger, mode: flags.mode, json: flags.json });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await discoverCommand({ task: resolvedTask, config, logger, mode: flags.mode, json: flags.json });
     });
   });
 
 program
   .command("triage")
   .description("Classify task complexity and recommend pipeline roles")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--triage <name>", "Override triage agent")
   .option("--triage-model <name>", "Override triage model")
   .option("--json", "Output raw JSON")
   .action(async (task, flags) => {
     await withConfig("triage", flags, async ({ config, logger }) => {
-      await triageCommand({ task, config, logger, json: flags.json });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await triageCommand({ task: resolvedTask, config, logger, json: flags.json });
     });
   });
 
 program
   .command("researcher")
   .description("Research codebase for a task (files, patterns, constraints)")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--researcher <name>", "Override researcher agent")
   .option("--researcher-model <name>", "Override researcher model")
   .action(async (task, flags) => {
     await withConfig("researcher", flags, async ({ config, logger }) => {
-      await researcherCommand({ task, config, logger });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await researcherCommand({ task: resolvedTask, config, logger });
     });
   });
 
 program
   .command("architect")
   .description("Design solution architecture (layers, patterns, contracts)")
-  .argument("<task>")
+  .argument("[task]", "Task description (or use --task-file)")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--architect <name>", "Override architect agent")
   .option("--architect-model <name>", "Override architect model")
   .option("--context <text>", "Additional context (e.g. researcher output)")
   .option("--json", "Output raw JSON")
   .action(async (task, flags) => {
     await withConfig("architect", flags, async ({ config, logger }) => {
-      await architectCommand({ task, config, logger, context: flags.context, json: flags.json });
+      const { resolveTaskInput } = await import("./utils/task-file.js");
+      const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+      await architectCommand({ task: resolvedTask, config, logger, context: flags.context, json: flags.json });
     });
   });
 
 program
   .command("audit")
   .description("Analyze codebase health (read-only)")
-  .argument("[task]")
+  .argument("[task]", "Task description. If absent, defaults to a full-codebase analysis. Use --task-file to point at a .md.")
+  .option("--task-file <path>", "Read the task from a file (e.g. .md)")
   .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing", "all")
   .option("--json", "Output raw JSON")
   .action(async (task, flags) => {
     await withConfig("audit", flags, async ({ config, logger }) => {
-      await auditCommand({ task: task || "Analyze the full codebase", config, logger, dimensions: flags.dimensions, json: flags.json });
+      let resolvedTask = task;
+      if (flags.taskFile) {
+        const { readTaskFile } = await import("./utils/task-file.js");
+        resolvedTask = await readTaskFile(flags.taskFile, { projectDir: config.projectDir });
+      }
+      await auditCommand({ task: resolvedTask || "Analyze the full codebase", config, logger, dimensions: flags.dimensions, json: flags.json });
     });
   });
 

package/src/commands/architect.js

@@ -58,30 +58,35 @@ function formatArchitect(result) {
 }
 
 export async function architectCommand({ task, config, logger, context, json }) {
-  const architectRole = resolveRole(config, "architect");
-  await assertAgentsAvailable([architectRole.provider]);
-  logger.info(`Architect (${architectRole.provider}) starting...`);
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("architect", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const architectRole = resolveRole(config, "architect");
+    await assertAgentsAvailable([architectRole.provider]);
+    logger.info(`Architect (${architectRole.provider}) starting...`);
+    runLog.logText(`[architect] provider=${architectRole.provider}`);
 
-  const agent = createAgent(architectRole.provider, config, logger);
-  const prompt = await buildArchitectPrompt({ task, researchContext: context });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "architect" });
+    const agent = createAgent(architectRole.provider, config, logger);
+    const prompt = await buildArchitectPrompt({ task, researchContext: context });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "architect" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Architect failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Architect failed");
+    }
 
-  const parsed = parseArchitectOutput(result.output);
+    const parsed = parseArchitectOutput(result.output);
 
-  if (json) {
-    console.log(JSON.stringify(parsed || result.output, null, 2));
-    return;
-  }
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
 
-  if (parsed?.verdict) {
-    console.log(formatArchitect(parsed));
-  } else {
-    console.log(result.output);
-  }
-  logger.info("Architect completed.");
+    if (parsed?.verdict) {
+      console.log(formatArchitect(parsed));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Architect completed.");
+    return { ok: true };
+  });
 }

package/src/commands/audit.js

@@ -2,6 +2,7 @@ import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
 
 function formatFindings(findings) {
   const lines = [];
@@ -66,34 +67,41 @@ function formatAudit(parsed) {
 }
 
 export async function auditCommand({ task, config, logger, dimensions, json }) {
-  const auditRole = resolveRole(config, "audit");
-  await assertAgentsAvailable([auditRole.provider]);
-  logger.info(`Audit (${auditRole.provider}) starting...`);
+  return withCliRunLog("audit", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const auditRole = resolveRole(config, "audit");
+    await assertAgentsAvailable([auditRole.provider]);
+    logger.info(`Audit (${auditRole.provider}) starting...`);
+    runLog.logText(`[audit] provider=${auditRole.provider} dimensions=${dimensions || "all"}`);
 
-  const agent = createAgent(auditRole.provider, config, logger);
-  const dimList = dimensions && dimensions !== "all"
-    ? dimensions.split(",").map(d => d.trim().toLowerCase()).map(d => d === "quality" ? "codeQuality" : d).filter(d => AUDIT_DIMENSIONS.includes(d))
-    : null;
+    const agent = createAgent(auditRole.provider, config, logger);
+    const dimList = dimensions && dimensions !== "all"
+      ? dimensions.split(",").map(d => d.trim().toLowerCase()).map(d => d === "quality" ? "codeQuality" : d).filter(d => AUDIT_DIMENSIONS.includes(d))
+      : null;
 
-  const prompt = buildAuditPrompt({ task: task || "Analyze the full codebase", dimensions: dimList });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "audit" });
+    const prompt = buildAuditPrompt({ task: task || "Analyze the full codebase", dimensions: dimList });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "audit" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Audit failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Audit failed");
+    }
 
-  const parsed = parseAuditOutput(result.output);
+    const parsed = parseAuditOutput(result.output);
+    if (parsed?.summary) {
+      runLog.logText(`[audit] findings=${parsed.summary.totalFindings} (critical=${parsed.summary.critical}, high=${parsed.summary.high})`);
+    }
 
-  if (json) {
-    console.log(JSON.stringify(parsed || result.output, null, 2));
-    return;
-  }
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
 
-  if (parsed?.summary) {
-    console.log(formatAudit(parsed));
-  } else {
-    console.log(result.output);
-  }
-  logger.info("Audit completed.");
+    if (parsed?.summary) {
+      console.log(formatAudit(parsed));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Audit completed.");
+    return { ok: true };
+  });
 }

package/src/commands/code.js

@@ -3,32 +3,38 @@ import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { resolveRole } from "../config.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
 
 export async function codeCommand({ task, config, logger }) {
-  const coderRole = resolveRole(config, "coder");
-  await assertAgentsAvailable([coderRole.provider]);
-  logger.info(`Coder (${coderRole.provider}) starting...`);
-  const coder = createAgent(coderRole.provider, config, logger);
-  let coderRules = null;
-  if (config.coder_rules) {
-    try {
-      coderRules = await fs.readFile(config.coder_rules, "utf8");
-    } catch { /* configured coder_rules path not found — try fallback */
-      try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+  return withCliRunLog("code", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const coderRole = resolveRole(config, "coder");
+    await assertAgentsAvailable([coderRole.provider]);
+    logger.info(`Coder (${coderRole.provider}) starting...`);
+    runLog.logText(`[coder] provider=${coderRole.provider}`);
+    const coder = createAgent(coderRole.provider, config, logger);
+    let coderRules = null;
+    if (config.coder_rules) {
+      try {
+        coderRules = await fs.readFile(config.coder_rules, "utf8");
+      } catch { /* configured coder_rules path not found — try fallback */
+        try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+      }
     }
-  }
-  const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await coder.runTask({ prompt, onOutput, role: "coder" });
-  if (!result.ok) {
-    if (result.error) logger.error(result.error);
-    throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
-  }
-  if (result.output) {
-    console.log(result.output);
-  }
-  if (result.error) {
-    logger.warn(result.error);
-  }
-  logger.info(`Coder completed (exit ${result.exitCode})`);
+    const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await coder.runTask({ prompt, onOutput, role: "coder" });
+    if (!result.ok) {
+      if (result.error) logger.error(result.error);
+      throw new Error(result.error || result.output || `Coder failed (exit ${result.exitCode})`);
+    }
+    if (result.output) {
+      console.log(result.output);
+    }
+    if (result.error) {
+      logger.warn(result.error);
+    }
+    logger.info(`Coder completed (exit ${result.exitCode})`);
+    runLog.logText(`[coder] finished (exit=${result.exitCode})`);
+    return { ok: true };
+  });
 }

package/src/commands/discover.js

@@ -62,30 +62,35 @@ function formatDiscover(result, mode) {
 }
 
 export async function discoverCommand({ task, config, logger, mode, json }) {
-  const discoverRole = resolveRole(config, "discover");
-  await assertAgentsAvailable([discoverRole.provider]);
-  logger.info(`Discover (${discoverRole.provider}) starting — mode: ${mode || "gaps"}...`);
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("discover", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const discoverRole = resolveRole(config, "discover");
+    await assertAgentsAvailable([discoverRole.provider]);
+    logger.info(`Discover (${discoverRole.provider}) starting — mode: ${mode || "gaps"}...`);
+    runLog.logText(`[discover] provider=${discoverRole.provider} mode=${mode || "gaps"}`);
 
-  const agent = createAgent(discoverRole.provider, config, logger);
-  const prompt = buildDiscoverPrompt({ task, mode: mode || "gaps" });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "discover" });
+    const agent = createAgent(discoverRole.provider, config, logger);
+    const prompt = buildDiscoverPrompt({ task, mode: mode || "gaps" });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "discover" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Discover failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Discover failed");
+    }
 
-  const parsed = parseDiscoverOutput(result.output);
+    const parsed = parseDiscoverOutput(result.output);
 
-  if (json) {
-    console.log(JSON.stringify(parsed || result.output, null, 2));
-    return;
-  }
+    if (json) {
+      console.log(JSON.stringify(parsed || result.output, null, 2));
+      return { ok: true };
+    }
 
-  if (parsed?.verdict) {
-    console.log(formatDiscover(parsed, mode || "gaps"));
-  } else {
-    console.log(result.output);
-  }
-  logger.info("Discover completed.");
+    if (parsed?.verdict) {
+      console.log(formatDiscover(parsed, mode || "gaps"));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Discover completed.");
+    return { ok: true };
+  });
 }

package/src/commands/plan.js

@@ -51,8 +51,16 @@ function formatHuTable(hus) {
  * kj plan "task" — generate plan + HUs
  */
 export async function planGenerateCommand({ task, config, logger, json, context }) {
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("plan", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    return planGenerateImpl({ task, config, logger, json, context, runLog });
+  });
+}
+
+async function planGenerateImpl({ task, config, logger, json, context, runLog }) {
   const plannerRole = resolveRole(config, "planner");
   await assertAgentsAvailable([plannerRole.provider]);
+  runLog.logText(`[planner] provider=${plannerRole.provider}`);
 
   const planner = createAgent(plannerRole.provider, config, logger);
   const prompt = buildPlannerPrompt({ task, context });
@@ -100,9 +108,11 @@ export async function planGenerateCommand({ task, config, logger, json, context
 
   const planId = await savePlan(projectDir, plan);
 
+  runLog.logText(`[planner] finished — hus=${plan.hus.length} plan=${planId}`);
+
   if (json) {
     console.log(JSON.stringify(plan, null, 2));
-    return;
+    return { ok: true };
   }
 
   if (parsed?.approach) {
@@ -116,6 +126,7 @@ export async function planGenerateCommand({ task, config, logger, json, context
   console.log(`Review:  kj plan show ${planId}`);
   console.log(`Approve: kj plan ready ${planId}`);
   console.log(`Execute: kj run --plan ${planId} "${task.slice(0, 40)}..."`);
+  return { ok: true };
 }
 
 /**

package/src/commands/researcher.js

@@ -20,21 +20,26 @@ function buildResearchPrompt(task) {
 }
 
 export async function researcherCommand({ task, config, logger }) {
-  const researcherRole = resolveRole(config, "researcher");
-  await assertAgentsAvailable([researcherRole.provider]);
-  logger.info(`Researcher (${researcherRole.provider}) starting...`);
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("researcher", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const researcherRole = resolveRole(config, "researcher");
+    await assertAgentsAvailable([researcherRole.provider]);
+    logger.info(`Researcher (${researcherRole.provider}) starting...`);
+    runLog.logText(`[researcher] provider=${researcherRole.provider}`);
 
-  const agent = createAgent(researcherRole.provider, config, logger);
-  const prompt = buildResearchPrompt(task);
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "researcher" });
+    const agent = createAgent(researcherRole.provider, config, logger);
+    const prompt = buildResearchPrompt(task);
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "researcher" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Researcher failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Researcher failed");
+    }
 
-  if (result.output) {
-    console.log(result.output);
-  }
-  logger.info("Researcher completed.");
+    if (result.output) {
+      console.log(result.output);
+    }
+    logger.info("Researcher completed.");
+    return { ok: true };
+  });
 }