karajan-code 2.7.2 → 2.7.3

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.7.2 released** — Skills observability: `summary.md` now shows a "Skills Used" section listing the addyosmani slugs resolved per role + OpenSkills installed/recommended, and `kj-tail` v1.37.0 highlights `[skills:*]` events with a 🎯 icon (magenta on success, yellow on graceful-degradation). Carries the full v2.7 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`. SEA platform binaries (`linux-x64`, `darwin-arm64`, `win-x64`) publish correctly again after the v2.7.1 workflow fix. 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.37.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 ──────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.7.2",
+  "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 };
+  });
 }

package/src/commands/review.js

@@ -4,12 +4,15 @@ import { computeBaseRef, generateDiff } from "../review/diff-generator.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveRole } from "../config.js";
 import { resolveReviewProfile } from "../review/profiles.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
 
 export async function reviewCommand({ task, config, logger, baseRef }) {
-  const reviewerRole = resolveRole(config, "reviewer");
-  await assertAgentsAvailable([reviewerRole.provider]);
-  logger.info(`Reviewer (${reviewerRole.provider}) starting...`);
-  const reviewer = createAgent(reviewerRole.provider, config, logger);
+  return withCliRunLog("review", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const reviewerRole = resolveRole(config, "reviewer");
+    await assertAgentsAvailable([reviewerRole.provider]);
+    logger.info(`Reviewer (${reviewerRole.provider}) starting...`);
+    runLog.logText(`[reviewer] provider=${reviewerRole.provider} baseRef=${baseRef || "(auto)"}`);
+    const reviewer = createAgent(reviewerRole.provider, config, logger);
 
   let diff;
   if (config.ci?.enabled) {
@@ -75,4 +78,7 @@ export async function reviewCommand({ task, config, logger, baseRef }) {
       logger.warn(`CI dispatch failed (non-blocking): ${err.message}`);
     }
   }
+  runLog.logText(`[reviewer] finished (exit=${result.exitCode})`);
+  return { ok: true };
+  });
 }

package/src/commands/run.js

@@ -3,6 +3,7 @@ import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
 import { printHeader } from "../utils/display/header.js";
 import { printEvent } from "../utils/display/event-handlers.js";
 import { resolveRole } from "../config.js";
@@ -57,32 +58,41 @@ export async function runCommandHandler({ task, config, logger, flags }) {
   // Quiet mode is the default; --verbose disables it
   const quietMode = config.output?.quiet !== false;
 
-  const emitter = new EventEmitter();
-  let activityLog = null;
+  return withCliRunLog("run", { projectDir: config?.projectDir, logger }, async ({ runLog, forwardProgress }) => {
+    runLog.logText(`[kj_run] task="${String(task).slice(0, 80)}..."`);
 
-  emitter.on("progress", (event) => {
-    if (!activityLog && event.sessionId) {
-      activityLog = createActivityLog(event.sessionId);
-      logger.onLog((entry) => activityLog.write(entry));
-    }
+    const emitter = new EventEmitter();
+    let activityLog = null;
 
-    if (activityLog) {
-      activityLog.writeEvent(event);
-    }
+    // Mirror every progress event into .kj/run.log so kj-tail works identically
+    // whether the command came from the MCP server or the CLI (KJC-TSK-0327 follow-up).
+    forwardProgress(emitter);
+
+    emitter.on("progress", (event) => {
+      if (!activityLog && event.sessionId) {
+        activityLog = createActivityLog(event.sessionId);
+        logger.onLog((entry) => activityLog.write(entry));
+      }
+
+      if (activityLog) {
+        activityLog.writeEvent(event);
+      }
+
+      if (!jsonMode) {
+        printEvent(event, { quiet: quietMode });
+      }
+    });
 
     if (!jsonMode) {
-      printEvent(event, { quiet: quietMode });
+      printHeader({ task: task, config });
     }
-  });
-
-  if (!jsonMode) {
-    printHeader({ task: task, config });
-  }
 
-  const askQuestion = createCliAskQuestion();
-  const result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+    const askQuestion = createCliAskQuestion();
+    const result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
 
-  if (jsonMode) {
-    console.log(JSON.stringify(result, null, 2));
-  }
+    if (jsonMode) {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    return { ok: !result?.paused && result?.approved !== false };
+  });
 }

package/src/commands/triage.js

@@ -34,30 +34,36 @@ function formatTriage(result) {
 }
 
 export async function triageCommand({ task, config, logger, json }) {
-  const triageRole = resolveRole(config, "triage");
-  await assertAgentsAvailable([triageRole.provider]);
-  logger.info(`Triage (${triageRole.provider}) starting...`);
+  const { withCliRunLog } = await import("../utils/cli-run-log.js");
+  return withCliRunLog("triage", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
+    const triageRole = resolveRole(config, "triage");
+    await assertAgentsAvailable([triageRole.provider]);
+    logger.info(`Triage (${triageRole.provider}) starting...`);
+    runLog.logText(`[triage] provider=${triageRole.provider}`);
 
-  const agent = createAgent(triageRole.provider, config, logger);
-  const prompt = buildTriagePrompt({ task });
-  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
-  const result = await agent.runTask({ prompt, onOutput, role: "triage" });
+    const agent = createAgent(triageRole.provider, config, logger);
+    const prompt = buildTriagePrompt({ task });
+    const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+    const result = await agent.runTask({ prompt, onOutput, role: "triage" });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Triage failed");
-  }
+    if (!result.ok) {
+      throw new Error(result.error || result.output || "Triage failed");
+    }
 
-  const parsed = parseMaybeJsonString(result.output);
+    const parsed = parseMaybeJsonString(result.output);
+    if (parsed?.level) runLog.logText(`[triage] level=${parsed.level} roles=${(parsed.roles || []).join(",")}`);
 
-  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?.level) {
-    console.log(formatTriage(parsed));
-  } else {
-    console.log(result.output);
-  }
-  logger.info("Triage completed.");
+    if (parsed?.level) {
+      console.log(formatTriage(parsed));
+    } else {
+      console.log(result.output);
+    }
+    logger.info("Triage completed.");
+    return { ok: true };
+  });
 }

package/src/mcp/direct-role-runner.js

@@ -53,6 +53,18 @@ export async function runDirectRole({
   await assertAgentsAvailable([role.provider]);
 
   const projectDir = await resolveProjectDir(server, args.projectDir);
+
+  // Allow taskFile as alternative to inline task — works for every direct
+  // role (discover/triage/researcher/architect/audit/impeccable/...) without
+  // per-handler wiring. The mutation is in-place on the role's runInput /
+  // initContext since they are already built with `task: a.task`.
+  if ((!runInput?.task || runInput.task === undefined) && args.taskFile) {
+    const { readTaskFile } = await import("../utils/task-file.js");
+    const loaded = await readTaskFile(args.taskFile, { projectDir });
+    if (runInput) runInput.task = loaded;
+    if (initContext) initContext.task = loaded;
+    args.task = loaded;
+  }
   const runLog = createRunLog(projectDir);
   const startMsg = logStartMsg || `[kj_${effectiveStage}] started`;
   runLog.logText(startMsg);

package/src/mcp/handlers/direct-handlers.js

@@ -56,6 +56,8 @@ export async function handlePlanDirect(a, server, extra) {
   await assertAgentsAvailable([plannerRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { ensureTaskFromFile } = await import("../shared-helpers.js");
+  await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
     ? Math.round(Number(config.session.max_agent_silence_minutes) * 60 * 1000)
@@ -210,6 +212,8 @@ export async function handleCodeDirect(a, server, extra) {
   await assertAgentsAvailable([coderRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { ensureTaskFromFile } = await import("../shared-helpers.js");
+  await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_code] started — provider=${coderRole.provider}`);
   const emitter = buildDirectEmitter(server, runLog, extra);
@@ -261,6 +265,8 @@ export async function handleReviewDirect(a, server, extra) {
   await assertAgentsAvailable([reviewerRole.provider]);
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { ensureTaskFromFile } = await import("../shared-helpers.js");
+  await ensureTaskFromFile(a, projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);
   const emitter = buildDirectEmitter(server, runLog, extra);

package/src/mcp/handlers/run-handler.js

@@ -267,8 +267,14 @@ export async function handleResume(a, server, extra) {
 }
 
 export async function handleRun(a, server, extra) {
+  const { ensureTaskFromFile, resolveProjectDir: _rpd } = await import("../shared-helpers.js");
+  try {
+    await ensureTaskFromFile(a, a.projectDir || (await _rpd(server, a.projectDir).catch(() => null)));
+  } catch (err) {
+    return failPayload(`taskFile read failed: ${err.message}`);
+  }
   if (!a.task) {
-    return failPayload("Missing required field: task");
+    return failPayload("Missing required field: task (or pass taskFile with a .md path)");
   }
   if (a.taskType) {
     const validTypes = new Set(["sw", "infra", "doc", "add-tests", "refactor"]);

package/src/mcp/shared-helpers.js

@@ -21,6 +21,29 @@ export { classifyError } from "./error-classifiers.js";
  * Resolve the user's project directory.
  * Priority: 1) explicit projectDir param, 2) MCP roots, 3) error with instructions.
  */
+/**
+ * Resolve the `task` argument for MCP handlers. If the caller passed
+ * `a.taskFile` (instead of or in addition to `a.task`), read the file and
+ * set `a.task` to its trimmed content. When both are given, the explicit
+ * `a.task` wins (symmetric with CLI `resolveTaskInput`).
+ *
+ * Mutates `a` in place so downstream handlers keep reading `a.task`
+ * without any change. Returns `a` for convenience.
+ *
+ * @param {Object} a
+ * @param {string} [projectDir]  - used to resolve relative file paths
+ * @returns {Promise<Object>}    - the same `a`, with `a.task` filled in
+ */
+export async function ensureTaskFromFile(a, projectDir) {
+  if (!a) return a;
+  const hasTask = typeof a.task === "string" && a.task.trim().length > 0;
+  const hasFile = typeof a.taskFile === "string" && a.taskFile.trim().length > 0;
+  if (hasTask || !hasFile) return a;
+  const { readTaskFile } = await import("../utils/task-file.js");
+  a.task = await readTaskFile(a.taskFile, { projectDir });
+  return a;
+}
+
 export async function resolveProjectDir(server, explicitProjectDir) {
   if (explicitProjectDir) return explicitProjectDir;
 

package/src/mcp/tools.js

@@ -54,9 +54,9 @@ export const tools = [
       "Run the full Karajan pipeline. IMPORTANT: Pass the user's task description exactly as they wrote it. Do NOT group, split, reorder, or modify tasks yourself. Karajan handles decomposition, role activation, iteration, and quality gates internally. Do NOT override pipeline parameters (enableHuReviewer, mode, methodology) unless the user explicitly requested it. If you have observations about the task, use kj_suggest instead.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042)" },
+        task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042). Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md (or any text file) whose contents become the task description. Relative paths resolve against projectDir." },
         plan: { type: "string", description: "Plan ID from kj_plan. Loads persisted plan context and skips researcher/architect/planner stages." },
         projectDir: { type: "string", description: "Absolute path to the project directory. Required when KJ MCP server runs from a different directory than the target project." },
         pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as task context and updates card status on completion." },
@@ -195,9 +195,9 @@ export const tools = [
     description: "Run coder-only mode. Pass the user's task exactly as described. Do NOT split or reinterpret the task.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string" },
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         coder: { type: "string" },
         coderModel: { type: "string" },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
@@ -210,9 +210,9 @@ export const tools = [
     description: "Run reviewer-only mode against current diff. Do NOT filter or pre-process the diff before passing it.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string" },
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         reviewer: { type: "string" },
         reviewerModel: { type: "string" },
         baseRef: { type: "string" },
@@ -236,9 +236,9 @@ export const tools = [
     description: "Generate implementation plan for a task. Pass the task as the user described it. Karajan's planner decides the approach.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string" },
+        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         planner: { type: "string" },
         plannerModel: { type: "string" },
         coder: { type: "string", description: "Legacy alias for planner" },
@@ -253,9 +253,9 @@ export const tools = [
     description: "Analyze a task for gaps, ambiguities, and missing information before execution. Returns a verdict (ready/needs_validation) with structured gap list. Can read task details from Planning Game if pgTask is provided.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description to analyze for gaps" },
+        task: { type: "string", description: "Task description to analyze for gaps. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         mode: { type: "string", enum: ["gaps", "momtest", "wendel", "classify", "jtbd"], description: "Discovery mode: gaps (default), momtest (Mom Test questions), wendel (behavior change checklist), classify (START/STOP/DIFFERENT), or jtbd (Jobs-to-be-Done)" },
         context: { type: "string", description: "Additional context for the analysis (e.g., research output)" },
         pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as additional context." },
@@ -270,9 +270,9 @@ export const tools = [
     description: "Classify task complexity and recommend which pipeline roles to activate. Returns level (trivial/simple/medium/complex), taskType, recommended roles, and optional decomposition.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description to classify" },
+        task: { type: "string", description: "Task description to classify. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
@@ -283,9 +283,9 @@ export const tools = [
     description: "Research the codebase for a task. Identifies affected files, patterns, constraints, prior decisions, risks, and test coverage.",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description to research" },
+        task: { type: "string", description: "Task description to research. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
@@ -296,9 +296,9 @@ export const tools = [
     description: "Design solution architecture for a task. Returns layers, patterns, data model, API contracts, tradeoffs, and a verdict (ready/needs_clarification).",
     inputSchema: {
       type: "object",
-      required: ["task"],
       properties: {
-        task: { type: "string", description: "Task description to architect" },
+        task: { type: "string", description: "Task description to architect. Either `task` or `taskFile` is required." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
         context: { type: "string", description: "Additional context (e.g., researcher output)" },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
@@ -311,6 +311,8 @@ export const tools = [
     inputSchema: {
       type: "object",
       properties: {
+        task: { type: "string", description: "Optional focus for the audit. If absent (and no taskFile), defaults to a full-codebase analysis." },
+        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file with the audit focus." },
         projectDir: { type: "string", description: "Absolute path to the project to audit" },
         dimensions: { type: "string", description: "Comma-separated dimensions to analyze: security,codeQuality,performance,architecture,testing (default: all)" },
         kjHome: { type: "string" }

package/src/utils/cli-run-log.js

@@ -0,0 +1,83 @@
+/**
+ * Shared run.log wrapper for CLI commands.
+ *
+ * Every MCP handler (`kj_run`, `kj_audit`, `kj_code`, `kj_review`, ...) writes
+ * progress + lifecycle events to `<projectDir>/.kj/run.log` via
+ * `createRunLog()`. `kj-tail` reads that file in real time to show pipeline
+ * activity. Until this module, the CLI (`kj run`, `kj audit`, ...) did NOT
+ * write that log at all, so running the same command as a shell (vs MCP)
+ * produced silence in `kj-tail`. This helper closes that asymmetry: CLI
+ * commands that opt in get the same run.log behavior as MCP.
+ *
+ * Usage pattern:
+ *
+ *   import { withCliRunLog } from "../utils/cli-run-log.js";
+ *
+ *   export async function fooCommand({ task, config, logger }) {
+ *     return withCliRunLog("foo", { projectDir: config.projectDir }, async ({ runLog, forwardProgress }) => {
+ *       runLog.logText(`[kj_foo] args — task="${task.slice(0, 80)}"`);
+ *
+ *       const emitter = new EventEmitter();
+ *       forwardProgress(emitter);   // every emitter.emit("progress", event) also lands in run.log
+ *
+ *       // ... run the work ...
+ *       return { ok: true };
+ *     });
+ *   }
+ *
+ * The wrapper guarantees:
+ *   - `.kj/run.log` is created/truncated at the start.
+ *   - A `[kj_<cmd>] started` line is written immediately so kj-tail shows the
+ *     command began (even if no emitter events follow — e.g. `kj audit` which
+ *     streams agent output directly).
+ *   - A `[kj_<cmd>] finished` (or `failed — <error>`) line is written at the
+ *     end, even if the inner function throws.
+ *   - The file descriptor is always closed.
+ *   - `forwardProgress(emitter)` is a no-op when the command doesn't use an
+ *     EventEmitter (e.g. one-shot agent calls). Commands that do emit
+ *     progress events (like `kj run`) get the same per-event coverage as MCP.
+ */
+
+import { createRunLog } from "./run-log.js";
+
+/**
+ * Wrap a CLI command body with run.log lifecycle management.
+ *
+ * @template T
+ * @param {string} commandName         - short slug, e.g. "run", "audit", "code"
+ * @param {Object}  opts
+ * @param {string} [opts.projectDir]   - project root; defaults to `process.cwd()`
+ * @param {Object} [opts.logger]       - optional logger for close-time warnings
+ * @param {(ctx: {
+ *   runLog: ReturnType<typeof createRunLog>,
+ *   forwardProgress: (emitter: import("node:events").EventEmitter) => void,
+ * }) => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export async function withCliRunLog(commandName, opts, fn) {
+  const projectDir = opts?.projectDir || process.cwd();
+  const runLog = createRunLog(projectDir);
+
+  runLog.logText(`[kj_${commandName}] started (cli)`);
+
+  const forwardProgress = (emitter) => {
+    if (!emitter || typeof emitter.on !== "function") return;
+    emitter.on("progress", (event) => {
+      try {
+        runLog.logEvent(event);
+      } catch { /* best-effort */ }
+    });
+  };
+
+  try {
+    const result = await fn({ runLog, forwardProgress });
+    const ok = result && result.ok !== false;
+    runLog.logText(`[kj_${commandName}] finished — ok=${ok}`);
+    return result;
+  } catch (err) {
+    runLog.logText(`[kj_${commandName}] failed — ${err?.message || String(err)}`);
+    throw err;
+  } finally {
+    runLog.close();
+  }
+}

package/src/utils/task-file.js

@@ -0,0 +1,109 @@
+/**
+ * Load a task description from a file (.md / .txt / .markdown / any plain text).
+ *
+ * Motivation: for anything beyond a one-line task, writing a `kj run "long
+ * multi-paragraph prompt ..."` becomes painful — escaping quotes, losing
+ * markdown formatting, no history. `kj run --task-file my-task.md` reads the
+ * file's contents and uses them as the task description. Same for `kj plan`,
+ * `kj audit`, `kj code`, and their MCP counterparts (via the `taskFile`
+ * argument).
+ *
+ * Behaviour:
+ *   - `taskFile` may be relative (resolved against `process.cwd()` by default,
+ *     or against `projectDir` if supplied) or absolute.
+ *   - Accepts any text file; markdown is the expected common case but we do
+ *     not require a specific extension.
+ *   - Trimmed of leading/trailing whitespace so agents don't get empty lines
+ *     around the task.
+ *   - `maxBytes` (default 256 KiB) guards against accidentally passing a huge
+ *     file (log dumps, PDFs). Agents choke on very long prompts anyway.
+ *   - Precedence with the positional `task` arg is decided by the caller:
+ *     this helper only loads, never merges. Convention used across commands:
+ *     when BOTH are provided, the positional task wins and the file is a
+ *     fallback — with a log warning so the user notices.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_TASK_FILE_MAX_BYTES = 256 * 1024;
+
+/**
+ * @param {string} filePath                - relative or absolute
+ * @param {Object} [opts]
+ * @param {string} [opts.projectDir]       - base dir for relative paths; defaults to process.cwd()
+ * @param {number} [opts.maxBytes]         - size cap; default 256 KiB
+ * @returns {Promise<string>}              - the trimmed file contents (task text)
+ * @throws                                 - Error with a user-readable message when the file is
+ *                                           missing, unreadable, empty, or over the size cap.
+ */
+export async function readTaskFile(filePath, opts = {}) {
+  if (!filePath || typeof filePath !== "string") {
+    throw new Error("readTaskFile: path must be a non-empty string");
+  }
+  const { projectDir, maxBytes = DEFAULT_TASK_FILE_MAX_BYTES } = opts;
+  const base = projectDir || process.cwd();
+  const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(base, filePath);
+
+  let stat;
+  try {
+    stat = await fs.stat(resolved);
+  } catch (err) {
+    throw new Error(`Task file not found: ${resolved} (${err.code || err.message})`);
+  }
+  if (!stat.isFile()) {
+    throw new Error(`Task file is not a regular file: ${resolved}`);
+  }
+  if (stat.size > maxBytes) {
+    const kb = Math.round(stat.size / 1024);
+    const capKb = Math.round(maxBytes / 1024);
+    throw new Error(
+      `Task file is too large: ${resolved} (${kb} KiB > ${capKb} KiB cap). ` +
+      `Summarise the task or raise the limit with the caller's maxBytes option.`
+    );
+  }
+
+  const raw = await fs.readFile(resolved, "utf8");
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error(`Task file is empty (or whitespace-only): ${resolved}`);
+  }
+  return trimmed;
+}
+
+/**
+ * Resolve the task text a command should use, given both positional `task`
+ * and an optional `taskFile`. Single source of truth for precedence across
+ * CLI and MCP entry points.
+ *
+ * Rules:
+ *   - Neither provided → throw (caller decides the UX; typically propagates).
+ *   - Only `task` → returns it, untouched.
+ *   - Only `taskFile` → reads and returns it.
+ *   - Both → `task` wins; emits a warning through `logger.warn` (if given).
+ *
+ * @param {Object} args
+ * @param {string|undefined} args.task
+ * @param {string|undefined} args.taskFile
+ * @param {string} [args.projectDir]
+ * @param {Object} [args.logger]             - optional; uses `logger.warn(msg)` only
+ * @returns {Promise<string>}
+ */
+export async function resolveTaskInput({ task, taskFile, projectDir, logger } = {}) {
+  const hasTask = typeof task === "string" && task.trim().length > 0;
+  const hasFile = typeof taskFile === "string" && taskFile.trim().length > 0;
+
+  if (!hasTask && !hasFile) {
+    throw new Error("No task provided. Pass a task argument or --task-file <path>.");
+  }
+  if (hasTask && hasFile) {
+    logger?.warn?.(
+      `Both task and --task-file given; using the positional task and ignoring file: ${taskFile}`
+    );
+    return task.trim();
+  }
+  if (hasFile) {
+    return readTaskFile(taskFile, { projectDir });
+  }
+  return task.trim();
+}