@karajan-family/code 4.21.0

package/src/commands/run.js

@@ -0,0 +1,185 @@
+import { EventEmitter } from "node:events";
+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 { registerRun, unregisterRun } from "../utils/run-registry.js";
+import { printHeader } from "../utils/display/header.js";
+import { printEvent } from "../utils/display/event-handlers.js";
+import { printResumeHint } from "../utils/display/resume-hint.js";
+import { resolveRole } from "../config.js";
+import { parseCardId } from "../planning-game/adapter.js";
+import { confirmCwd } from "../utils/cwd-confirm.js";
+import { runSpecReview } from "../spec-review/run-spec-review.js";
+import { maybeAutoUpdate } from "../rag/auto-update.js";
+
+// Re-export the shared helper so existing imports (tests, MCP wrappers)
+// keep working. KJC-BUG-0081 round 2 split the body into utils/ because
+// resume.js also needs the same contract.
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
+import { buildDecider } from "../autonomy/decider.js";
+import { createAutonomyAskQuestion } from "../autonomy/stage-ask.js";
+export { createCliAskQuestion };
+
+export async function runCommandHandler({ task, config, logger, flags }) {
+  // PR-F (cwd confirmation): when launching from an interactive
+  // terminal, surface the working directory so the user can abort if
+  // they typed `kj run` from the wrong place. The user's words:
+  // "todas las que lo lancé desde terminal te garantizo que estaba
+  // en la carpeta del proyecto … aún así preguntar por si acaso".
+  //
+  // Skip the prompt when:
+  //   - --yes / -y is set (CI / scripted runs),
+  //   - --json mode is on (machine-readable output, no TTY assumed),
+  //   - stdin is not a TTY (piped, board-spawned subprocess, MCP).
+  const projectDir = config?.projectDir || process.cwd();
+  const canPrompt = process.stdin.isTTY && process.stdout.isTTY
+    && !flags?.yes && !flags?.json;
+  if (canPrompt) {
+    const ok = await confirmCwd(projectDir);
+    if (!ok) {
+      console.log("Aborted by user.");
+      return { ok: false, aborted: true };
+    }
+  }
+
+  // KJC-TSK-0455 — Pre-run drift check. Default ON; opt out with
+  // --no-rag-update (flag) or config.rag.autoUpdate.onRun=false. If the
+  // local index is behind HEAD we re-embed the delta before the agents
+  // start reading from the RAG store; on any failure we log and move on
+  // so a broken vector store never blocks a run.
+  await maybeAutoUpdate({ projectDir, config, logger, flags });
+
+  // Best-effort session cleanup before starting
+  try {
+    const { cleanupExpiredSessions } = await import("../session-cleanup.js");
+    await cleanupExpiredSessions({ logger });
+  } catch { /* non-blocking */ }
+
+  const requiredProviders = [
+    resolveRole(config, "coder").provider
+  ];
+  if (config.pipeline?.reviewer?.enabled !== false) {
+    requiredProviders.push(resolveRole(config, "reviewer").provider);
+  }
+  if (config.pipeline?.triage?.enabled) requiredProviders.push(resolveRole(config, "triage").provider);
+  if (config.pipeline?.planner?.enabled) requiredProviders.push(resolveRole(config, "planner").provider);
+  if (config.pipeline?.refactorer?.enabled) requiredProviders.push(resolveRole(config, "refactorer").provider);
+  if (config.pipeline?.researcher?.enabled) requiredProviders.push(resolveRole(config, "researcher").provider);
+  if (config.pipeline?.tester?.enabled) requiredProviders.push(resolveRole(config, "tester").provider);
+  if (config.pipeline?.security?.enabled) requiredProviders.push(resolveRole(config, "security").provider);
+  await assertAgentsAvailable(requiredProviders);
+
+  // --- Planning Game: resolve card ID ---
+  const pgCardId = flags?.pgTask || parseCardId(task);
+  const pgProject = flags?.pgProject || config.planning_game?.project_id || null;
+
+  const jsonMode = flags?.json;
+  // Quiet mode is the default; --verbose disables it
+  const quietMode = config.output?.quiet !== false;
+
+  return withCliRunLog("run", { projectDir: config?.projectDir, logger }, async ({ runLog, forwardProgress }) => {
+    runLog.logText(`[kj_run] task="${String(task).slice(0, 80)}..."`);
+
+    // KJC-TSK-0396 extensión: registrar el PID + planId + huIds en
+    // ~/.karajan/runs/<runId>.json para que el HU Board pueda mostrar
+    // el botón ⏹ Stop incluso cuando el run se lanza desde terminal
+    // externa (no solo desde el botón ▶ Run del board). Best-effort:
+    // si la escritura falla, el run sigue su curso normal. Limpieza
+    // garantizada en el finally del withCliRunLog vía registry.unregisterRun.
+    const huIdsFromFlag = typeof flags?.hu === "string"
+      ? flags.hu.split(",").map((s) => s.trim()).filter(Boolean)
+      : null;
+    const runId = registerRun({
+      pid: process.pid,
+      planId: flags?.plan || null,
+      huIds: huIdsFromFlag,
+      projectDir: config?.projectDir || process.cwd(),
+      source: "cli",
+    });
+    const cleanupRegistry = () => { if (runId) unregisterRun(runId); };
+    // Cubrir todos los caminos de salida del proceso.
+    process.once("exit", cleanupRegistry);
+    process.once("SIGTERM", () => { cleanupRegistry(); process.exit(143); });
+    process.once("SIGINT", () => { cleanupRegistry(); process.exit(130); });
+
+    const emitter = new EventEmitter();
+    let activityLog = null;
+
+    // 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) {
+      printHeader({ task: task, config });
+    }
+
+    const askQuestion = createCliAskQuestion({ flags });
+
+    // Autonomy (KJC-PCS-0062): wire the level to a resolver. In autonomous mode
+    // every gate is decided by the Arbiter instead of the human; interactive
+    // keeps the human prompts. The decider is threaded into the gates below.
+    const { autonomy, resolve: decide } = buildDecider({ config, flags, ask: askQuestion, logger });
+
+    // Spec-reviewer pre-pipeline audit (KJC-PCS-0048). Runs BEFORE
+    // anything else — surfaces ambiguity / missing scope / missing AC.
+    // In autonomous mode the Arbiter decides (never aborts); interactive
+    // lets the user bail. Bypass with --skip-spec-review.
+    const reviewResult = await runSpecReview({ spec: task, config, logger, askQuestion, flags, resolve: decide, autonomy });
+    if (!reviewResult.proceed) {
+      logger.info("Aborted by user after spec review.");
+      cleanupRegistry();
+      return { ok: false, aborted: true, reason: "spec-review-cancelled" };
+    }
+    // If the user refined the spec via [r]efine, downstream runs the
+    // REFINED text (not the original) so the pipeline acts on what the
+    // user actually approved.
+    const effectiveTask = reviewResult.refined && reviewResult.finalSpec ? reviewResult.finalSpec : task;
+
+    // AUTO-E: in autonomous mode the stages never ask a human or block on the
+    // board — they auto-continue with the least-bad choice. interactive/assisted
+    // keep the human prompts.
+    const stageAsk = createAutonomyAskQuestion({ baseAsk: askQuestion, autonomy, logger });
+
+    let result;
+    try {
+      result = await runFlow({ task: effectiveTask, config, logger, flags, emitter, askQuestion: stageAsk, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+    } finally {
+      // KJC-TSK-0396: limpia el registro pase lo que pase (éxito,
+      // throw, o paused). Los handlers de SIGINT/SIGTERM/exit son
+      // backstop para casos donde el throw no llega aquí (segfault,
+      // kill -9, etc.).
+      cleanupRegistry();
+    }
+
+    if (jsonMode) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      // Last line printed: if the run stopped (hibernated / paused /
+      // failed), tell the user the exact command to resume it.
+      printResumeHint(result);
+    }
+    // Surface per-HU results so `kj autorun` can build a real outcome report
+    // (KJC-BUG-0090: it showed "0/0 met the ask" because only { ok } came back).
+    // The plan run returns them as `huResults` (run-hu-batch finalResult).
+    const hus = Array.isArray(result?.huResults)
+      ? result.huResults.map((r) => ({ id: r.huId, met: r.approved === true }))
+      : [];
+    return { ok: !result?.paused && result?.approved !== false, hus };
+  });
+}

package/src/commands/scan.js

@@ -0,0 +1,18 @@
+import { getOpenIssues, getQualityGateStatus } from "../sonar/api.js";
+import { runSonarScan } from "../sonar/scanner.js";
+import { summarizeIssues } from "../sonar/enforcer.js";
+
+export async function scanCommand({ config }) {
+  const scan = await runSonarScan(config);
+  if (!scan.ok) {
+    throw new Error(`Sonar scan failed: ${scan.stderr || scan.stdout}`);
+  }
+
+  const gate = await getQualityGateStatus(config, scan.projectKey);
+  const issues = await getOpenIssues(config, scan.projectKey);
+
+  console.log(`Project key: ${scan.projectKey}`);
+  console.log(`Quality Gate: ${gate.status}`);
+  console.log(`Open issues: ${issues.total}`);
+  console.log(`By severity: ${summarizeIssues(issues.issues) || "none"}`);
+}

package/src/commands/skills.js

@@ -0,0 +1,86 @@
+/**
+ * `kj skills` — manage the local OpenSkills cache and the addyosmani catalog.
+ *
+ * Subcommands:
+ *   - list                  : print cached OpenSkills with their age and freshness.
+ *   - clear-cache           : delete all cached metadata (forces re-install on next session).
+ *   - sync-addyosmani       : force a git pull of addyosmani/agent-skills.
+ *   - list-addyosmani       : enumerate slugs available in the cached catalog.
+ */
+
+import { listCached, clearCache, getCacheRoot, DEFAULT_TTL_MS } from "../skills/skills-cache.js";
+import { refreshIfStale, listAvailableSlugs, getCatalogRoot, loadSkillBySlug } from "../skills/addyosmani-catalog.js";
+
+function humanAge(cachedAt) {
+  const ms = Date.now() - Date.parse(cachedAt);
+  if (!Number.isFinite(ms) || ms < 0) return "unknown";
+  const days = ms / (24 * 60 * 60 * 1000);
+  if (days < 1) return `${Math.max(1, Math.round(ms / (60 * 60 * 1000)))}h ago`;
+  return `${days.toFixed(1)}d ago`;
+}
+
+export async function skillsCommand({ action = "list" } = {}) {
+  switch (action) {
+    case "list":
+      return listAction();
+    case "clear-cache":
+      return clearAction();
+    case "sync-addyosmani":
+      return syncAddyosmaniAction();
+    case "list-addyosmani":
+      return listAddyosmaniAction();
+    default:
+      console.error(`Unknown action: ${action}. Use: list | clear-cache | sync-addyosmani | list-addyosmani`);
+      return 1;
+  }
+}
+
+async function listAction() {
+  const cache = await listCached();
+  if (cache.length === 0) {
+    console.log(`No cached skills at ${getCacheRoot()}`);
+    return 0;
+  }
+  console.log(`Cached skills (TTL ${Math.round(DEFAULT_TTL_MS / 86400000)}d) at ${getCacheRoot()}:\n`);
+  for (const entry of cache) {
+    const flag = entry.fresh ? "FRESH" : "STALE";
+    console.log(`  ${flag}  ${entry.name}  (${humanAge(entry.cachedAt)})`);
+  }
+  return 0;
+}
+
+async function clearAction() {
+  const { removed } = await clearCache();
+  console.log(`Cleared ${removed} cached skill${removed === 1 ? "" : "s"} from ${getCacheRoot()}`);
+  return 0;
+}
+
+async function syncAddyosmaniAction() {
+  console.log("Syncing addyosmani/agent-skills catalog...");
+  const logger = { warn: (m) => console.warn(`  warn: ${m}`), info: (m) => console.log(`  ${m}`) };
+  const result = await refreshIfStale({ force: true, logger });
+  if (!result.ok) {
+    console.error(`Sync failed: ${result.error || result.action}`);
+    return 1;
+  }
+  const slugs = await listAvailableSlugs();
+  console.log(`${result.action === "cloned" ? "Cloned" : "Pulled"} at ${getCatalogRoot()}`);
+  console.log(`Available slugs: ${slugs.length}`);
+  return 0;
+}
+
+async function listAddyosmaniAction() {
+  const slugs = await listAvailableSlugs();
+  if (slugs.length === 0) {
+    console.log(`No addyosmani catalog found at ${getCatalogRoot()}`);
+    console.log("Run `kj skills sync-addyosmani` to bootstrap it.");
+    return 0;
+  }
+  console.log(`addyosmani/agent-skills catalog at ${getCatalogRoot()}\n${slugs.length} slug(s):\n`);
+  for (const slug of slugs) {
+    const skill = await loadSkillBySlug(slug);
+    const desc = skill?.description ? ` — ${skill.description.slice(0, 100)}${skill.description.length > 100 ? "..." : ""}` : "";
+    console.log(`  ${slug}${desc}`);
+  }
+  return 0;
+}

package/src/commands/sonar.js

@@ -0,0 +1,53 @@
+import os from "node:os";
+import { sonarDown, sonarLogs, sonarStatus, sonarUp, isSonarReachable } from "../sonar/manager.js";
+import { resolveSonarProjectKey } from "../sonar/project-key.js";
+import { runCommand } from "../utils/process.js";
+
+function openBrowserCmd() {
+  const platform = os.platform();
+  if (platform === "darwin") return "open";
+  if (platform === "win32") return "start";
+  return "xdg-open";
+}
+
+export async function sonarOpenCommand({ config }) {
+  const host = config?.sonarqube?.host || "http://localhost:9000";
+
+  if (!(await isSonarReachable(host))) {
+    return { ok: false, error: `SonarQube is not reachable at ${host}. Run 'kj sonar start' first.` };
+  }
+
+  let projectKey;
+  try {
+    projectKey = await resolveSonarProjectKey(config);
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+
+  const url = `${host}/dashboard?id=${projectKey}`;
+  await runCommand(openBrowserCmd(), [url]);
+  return { ok: true, url };
+}
+
+export async function sonarCommand({ action }) {
+  if (action === "start") {
+    const res = await sonarUp();
+    console.log(res.stdout || res.stderr);
+    return;
+  }
+
+  if (action === "stop") {
+    const res = await sonarDown();
+    console.log(res.stdout || res.stderr);
+    return;
+  }
+
+  if (action === "logs") {
+    const res = await sonarLogs();
+    console.log(res.stdout || res.stderr);
+    return;
+  }
+
+  const res = await sonarStatus();
+  console.log(res.stdout || "stopped");
+}

package/src/commands/standby.js

@@ -0,0 +1,117 @@
+// KJC-TSK-0414 PR2: comandos kj standby list / kj resume.
+//
+// `kj resume <sessionId>` valida cooldownUntil y, si llegó la hora, re-spawn
+// el comando original capturado en argv. Si cooldown todavía está en el
+// futuro, muestra countdown y aborta. `kj standby list` solo enumera.
+//
+// Estrategia de resume: cada sessionState persiste su argv original (los
+// argumentos con los que se lanzó el `kj` que hibernó). El resume re-spawn
+// EXACTAMENTE ese mismo comando con env preservado. El run reanuda como si
+// fuera un retry — el state interno (HU pendiente, snapshot_sha, etc.) está
+// en el JSON persistido en disco por TSK-0408 + TSK-0414 PR1.
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadStandby, listPendingStandby, markStandbyDone, acquireStandbyLock } from "../brain/standby-store.js";
+
+const REPO_KJ_CLI = (() => {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(here, "..", "cli.js");
+  } catch {
+    return null;
+  }
+})();
+
+function formatCountdown(ms) {
+  if (ms <= 0) return "ahora";
+  const s = Math.round(ms / 1000);
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(sec).padStart(2, "0")}`;
+}
+
+export async function standbyListCommand({ json } = {}) {
+  const sessions = listPendingStandby();
+  if (json) {
+    console.log(JSON.stringify(sessions, null, 2));
+    return;
+  }
+  if (sessions.length === 0) {
+    console.log("No hay sesiones hibernadas.");
+    return;
+  }
+  console.log(`Sesiones hibernadas (${sessions.length}):`);
+  const now = Date.now();
+  for (const s of sessions) {
+    const ms = new Date(s.cooldownUntil).getTime() - now;
+    const status = ms <= 0 ? "✓ lista para resume" : `⏳ resume en ${formatCountdown(ms)}`;
+    console.log(`  ${s.sessionId}  · ${s.reason || "?"}  · ${status}`);
+    if (s.planId) {
+      const huSuffix = s.huId ? `, HU: ${s.huId}` : "";
+      console.log(`    plan: ${s.planId}${huSuffix}`);
+    }
+  }
+}
+
+/**
+ * Re-spawn el comando original capturado en sessionState.argv.
+ * Si cooldownUntil > now y force=false → aborta con mensaje.
+ */
+export async function resumeCommand({ sessionId, force } = {}) {
+  if (!sessionId) {
+    console.error("kj resume requiere <sessionId>. Usa `kj standby list` para ver pendientes.");
+    process.exitCode = 1;
+    return;
+  }
+  const state = loadStandby(sessionId);
+  if (!state) {
+    console.error(`Sesión no encontrada: ${sessionId}`);
+    process.exitCode = 1;
+    return;
+  }
+  const cooldownMs = new Date(state.cooldownUntil).getTime() - Date.now();
+  if (cooldownMs > 0 && !force) {
+    console.log(`Sesión ${sessionId} todavía en cooldown ${formatCountdown(cooldownMs)} (hasta ${state.cooldownUntil}).`);
+    console.log("Espera o usa `kj resume <sessionId> --force` (no recomendado — la API seguramente seguirá rechazando).");
+    process.exitCode = 0;
+    return;
+  }
+
+  const lock = acquireStandbyLock(sessionId);
+  if (!lock.acquired) {
+    console.log(`Sesión ${sessionId} ya está siendo reanudada por otro proceso.`);
+    process.exitCode = 0;
+    return;
+  }
+
+  try {
+    if (!Array.isArray(state.argv) || state.argv.length === 0) {
+      console.error(`Sesión ${sessionId} sin argv — no se puede re-spawn. Borra manual y relanza.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!REPO_KJ_CLI) {
+      console.error("No se pudo localizar cli.js. ¿Karajan instalado correctamente?");
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`Reanudando ${sessionId}: kj ${state.argv.join(" ")}`);
+    const child = spawn(process.execPath, [REPO_KJ_CLI, ...state.argv], {
+      cwd: state.cwd || process.cwd(),
+      env: { ...process.env, ...(state.env || {}), KJ_RESUME_FROM: sessionId },
+      stdio: "inherit",
+    });
+    await new Promise((resolve) => {
+      child.on("exit", (code) => {
+        if (code === 0) markStandbyDone(sessionId);
+        process.exitCode = code ?? 0;
+        resolve();
+      });
+    });
+  } finally {
+    lock.release?.();
+  }
+}

package/src/commands/start.js

@@ -0,0 +1,121 @@
+// KJC-TSK-0570 (Onboard C) — `kj start`: the single entry point to the Brain.
+// Wires the read-only sweep (0568) → deterministic assessment (0569) → haiku
+// decider (0569), reports the recommended next step, and — interactively only —
+// confirms and dispatches the chosen intent to its saved command
+// (harden/rag/run/plan). --json / --yes / no-TTY stay read-only: emit the
+// assessment + intent and apply nothing. Collaborators are injected for testing.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+import { runReadOnlySweep } from "../start/sweep.js";
+import { buildAssessment } from "../start/assessment.js";
+import { StartDecidorRole } from "../start/start-decider-role.js";
+import { createWizard, isTTY } from "../utils/wizard.js";
+
+// The recommended next step shown for each intent.
+const NEXT_STEP = {
+  ASSESS_ONLY: "Everything looks healthy — nothing to do.",
+  RECOMMEND_HARDEN: "Suggested: `kj harden --interactive`",
+  RECOMMEND_INDEX: "Suggested: `kj rag index`",
+  START_TASK: 'Suggested: `kj run "<task>"`',
+  PROPOSE_PLAN: 'Suggested: `kj plan "<goal>"`',
+};
+
+// Each writing intent maps to the saved command + args `kj start` dispatches.
+const DISPATCH = {
+  RECOMMEND_HARDEN: () => ["harden", "--interactive"],
+  RECOMMEND_INDEX: () => ["rag", "index"],
+  START_TASK: (task) => ["run", task],
+  PROPOSE_PLAN: (task) => ["plan", task],
+};
+
+const ASK_FALLBACK = "What would you like to do with this project?";
+const CLI_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "cli.js");
+
+// Run a saved `kj` subcommand as a child, inheriting stdio so its own prompts
+// (e.g. `harden --interactive`) drive the real terminal. Never throws here.
+async function spawnKj(args, { cwd }) {
+  await execa("node", [CLI_PATH, ...args.filter(Boolean)], { cwd, stdio: "inherit", reject: false });
+}
+
+// The decider has its own quota/parse recovery; a spawn-level failure (CLI not
+// installed) still throws, so we degrade here too — `kj start` never crashes.
+async function decide({ task, text, config, logger, makeDecider }) {
+  const decider = makeDecider({ config, logger });
+  try {
+    const decision = await decider.execute({ userMessage: task, assessment: text });
+    return decision.result || {};
+  } catch (err) {
+    logger?.warn?.(`[start] decider unavailable (${err?.message || err}) — asking the user.`);
+    return { intent: "ASK_USER", rationale: "Decider unavailable.", questionToAsk: ASK_FALLBACK, degraded: true };
+  }
+}
+
+// Ask one yes/no, always closing the readline interface afterwards.
+async function confirmApply(makeWizard) {
+  const wizard = makeWizard();
+  try {
+    return await wizard.confirm("Apply this?", true);
+  } finally {
+    wizard.close();
+  }
+}
+
+// Print the rationale + recommended step, or the open question for ASK_USER.
+function render(result) {
+  if (result.intent === "ASK_USER") {
+    console.log(`❓ ${result.questionToAsk || ASK_FALLBACK}`);
+    return;
+  }
+  if (result.rationale) console.log(`→ ${result.rationale}`);
+  const step = NEXT_STEP[result.intent];
+  if (step) console.log(`  ${step}`);
+}
+
+export async function startCommand({ task = "", config, logger, flags = {}, deps = {} }) {
+  const sweep = deps.runReadOnlySweep || runReadOnlySweep;
+  const assess = deps.buildAssessment || buildAssessment;
+  const makeDecider = deps.makeDecider || ((opts) => new StartDecidorRole(opts));
+  const tty = deps.isTTY || isTTY;
+  const spawn = deps.spawnKj || spawnKj;
+  const makeWizard = deps.makeWizard || (() => createWizard());
+
+  // KJC-BUG-0145 (campo, #1471): loadConfig never sets projectDir — passing
+  // config.projectDir straight through handed `undefined` to the sweep, every
+  // collector failed silently and the project read as "new, no source code".
+  const projectDir = config.projectDir || process.cwd();
+  const bundle = await sweep(projectDir, { declared: flags.maturity || null });
+  const { text, summary } = assess(bundle);
+  let result = await decide({ task, text, config, logger, makeDecider });
+
+  if (flags.json) {
+    console.log(JSON.stringify({ maturity: summary.maturity, assessment: text, ...result }, null, 2));
+    return { ok: true, intent: result.intent };
+  }
+
+  console.log(`${text}\n`);
+  const interactive = tty() && !flags.yes;
+  let goal = task;
+
+  // ASK_USER: one interactive re-route — the open answer becomes the goal.
+  if (result.intent === "ASK_USER" && interactive) {
+    const wizard = makeWizard();
+    try {
+      const answer = await wizard.input(`❓ ${result.questionToAsk || ASK_FALLBACK}`);
+      if (answer) {
+        goal = answer;
+        result = await decide({ task: answer, text, config, logger, makeDecider });
+      }
+    } finally {
+      wizard.close();
+    }
+  }
+  render(result);
+
+  // Dispatch the chosen intent to its saved command, confirming first (it writes).
+  const toArgs = DISPATCH[result.intent];
+  if (interactive && toArgs && (await confirmApply(makeWizard))) {
+    await spawn(toArgs(goal), { cwd: projectDir });
+  }
+  return { ok: true, intent: result.intent };
+}

package/src/commands/status.js

@@ -0,0 +1,36 @@
+/**
+ * CLI status command — shows a terminal dashboard of the current pipeline state.
+ */
+
+import { readRunLog } from "../utils/run-log.js";
+import { loadMostRecentSession } from "../session/store.js";
+import { buildDashboard } from "../utils/status-dashboard.js";
+
+
+/**
+ * Run the `kj status` command: print a human-readable dashboard to stdout.
+ * @param {object} options
+ * @param {number} [options.lines=50] - Max log lines to read.
+ * @param {string} [options.projectDir] - Project directory override.
+ */
+export async function statusCommand({ lines = 50, projectDir } = {}) {
+  const dir = projectDir || process.cwd();
+  const logResult = readRunLog(dir, lines);
+
+  let session = null;
+  try {
+    session = await loadMostRecentSession();
+  } catch { /* no session available */ }
+
+  let stories = [];
+  if (session) {
+    try {
+      const { loadHuBatch } = await import("../hu/store.js");
+      const batch = await loadHuBatch(session.id);
+      if (batch?.stories) stories = batch.stories;
+    } catch { /* no HU batch */ }
+  }
+
+  const dashboard = buildDashboard(session, logResult.lines || [], { stories });
+  console.log(dashboard);
+}