karajan-code 2.14.3 → 2.15.0

package/src/commands/init.js

@@ -127,6 +127,52 @@ async function askPerRoleProviders(wizard, available, config, { coder, reviewer
   }
 }
 
+/**
+ * KJC-TSK-0415: Plan B — fallback chain. Cuando el provider primario se
+ * queda sin créditos (QUOTA_EXHAUSTED_DAILY/MONTHLY) y el cooldown excede
+ * max_wait_hours, Brain switchea al fallback en vez de hibernar.
+ *
+ * Solo pregunta si hay >= 2 providers disponibles (sin alternativas reales
+ * no tiene sentido el fallback).
+ */
+async function askFallbackChain(wizard, available, config, { coder, reviewer }, logger) {
+  if (available.length < 2) return;
+
+  logger.info("");
+  logger.info("Plan B — fallback automático cuando un provider se queda sin créditos:");
+  const enable = await wizard.confirm(
+    "  ¿Configurar fallback? (default: 12h; si el cooldown supera ese tiempo, switch al provider alternativo)",
+    true
+  );
+  if (!enable) return;
+
+  const maxHoursRaw = await wizard.input("  Máximo tiempo de espera antes de fallback (horas):", "12");
+  const maxHours = Number.parseFloat(maxHoursRaw) || 12;
+
+  config.roles = config.roles || {};
+  const KEY_ROLES = [
+    { key: "coder", label: "coder", primary: coder },
+    { key: "reviewer", label: "reviewer", primary: reviewer },
+    { key: "planner", label: "planner", primary: coder },
+  ];
+  for (const role of KEY_ROLES) {
+    config.roles[role.key] = config.roles[role.key] || {};
+    const opts = [{ label: "Sin fallback (hibernar)", value: "__none__", available: true }];
+    for (const a of available) {
+      if (a.name === role.primary) continue;
+      opts.push({ label: a.name, value: a.name, available: true });
+    }
+    const choice = await wizard.select(`  Fallback de ${role.label} cuando ${role.primary} se quede sin créditos:`, opts);
+    if (choice === "__none__") {
+      delete config.roles[role.key].fallback;
+      logger.info(`    -> ${role.key}: sin fallback (hibernará)`);
+    } else {
+      config.roles[role.key].fallback = { provider: choice, max_wait_hours: maxHours };
+      logger.info(`    -> ${role.key}: ${role.primary} → ${choice} (tras ${maxHours}h)`);
+    }
+  }
+}
+
 async function askMethodology(wizard, config, logger) {
   const methodology = await wizard.select("Development methodology:", [
     { label: "TDD (test-driven development)", value: "tdd", available: true },
@@ -256,6 +302,7 @@ async function runWizard(config, logger) {
     logger.info(`  -> HU Board: ${enableHuBoard ? "enabled (auto-start on kj run)" : "disabled"}`);
 
     await askPerRoleProviders(wizard, available, config, { coder, reviewer }, logger);
+    await askFallbackChain(wizard, available, config, { coder, reviewer }, logger);
     await askMethodology(wizard, config, logger);
     await askLanguages(wizard, config, logger);
 

package/src/commands/plan/_shared.js

@@ -25,16 +25,31 @@ export function formatPlan(plan) {
   return lines.join("\n");
 }
 
+/**
+ * Convierte el id largo de una dep `hu_<planId>_<NNN>` al short_id de
+ * la HU correspondiente cuando lo conoce. Mantiene el id largo si la
+ * dep no tiene short_id (HU legacy pre-humanización).
+ */
+function displayDep(depId, hus) {
+  const hu = hus.find((h) => h.id === depId);
+  if (hu?.short_id) return hu.short_id;
+  return depId;
+}
+
 export function formatHuTable(hus) {
   if (!hus?.length) return "  (no HUs)";
+  // Humanización IDs: si la HU tiene short_id ("INFRA-001"), úsalo
+  // como columna ID; si no, fallback al id largo (HU legacy).
+  const idOf = (h) => h.short_id || h.id;
   const lines = [];
+  const maxId = Math.min(20, Math.max(...hus.map((h) => idOf(h).length || 0)));
   const maxTitle = Math.min(50, Math.max(...hus.map(h => h.title?.length || 0)));
-  lines.push(`  ${"ID".padEnd(30)} ${"Title".padEnd(maxTitle)} ${"Type".padEnd(10)} ${"Status".padEnd(10)} Deps`);
-  lines.push(`  ${"─".repeat(30)} ${"─".repeat(maxTitle)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(15)}`);
+  lines.push(`  ${"ID".padEnd(maxId)} ${"Title".padEnd(maxTitle)} ${"Type".padEnd(10)} ${"Status".padEnd(10)} Deps`);
+  lines.push(`  ${"─".repeat(maxId)} ${"─".repeat(maxTitle)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(15)}`);
   for (const hu of hus) {
     const title = (hu.title || "").slice(0, maxTitle).padEnd(maxTitle);
-    const deps = (hu.blocked_by || []).join(", ") || "—";
-    lines.push(`  ${hu.id.padEnd(30)} ${title} ${(hu.task_type || "sw").padEnd(10)} ${(hu.status || "?").padEnd(10)} ${deps}`);
+    const deps = (hu.blocked_by || []).map((d) => displayDep(d, hus)).join(", ") || "—";
+    lines.push(`  ${idOf(hu).padEnd(maxId)} ${title} ${(hu.task_type || "sw").padEnd(10)} ${(hu.status || "?").padEnd(10)} ${deps}`);
   }
   return lines.join("\n");
 }

package/src/commands/plan/fix.js

@@ -0,0 +1,99 @@
+// KJC-TSK-0402: relanzar el self-fix loop sobre un plan ya generado,
+// opcionalmente con feedback humano que guía al reviewer hacia los
+// puntos débiles que la primera pasada no detectó. NO regenera desde
+// cero — preserva el trabajo previo.
+
+import { createAgent } from "../../agents/index.js";
+import { assertAgentsAvailable } from "../../agents/availability.js";
+import { resolveRole } from "../../config.js";
+import { createCliProgressReporter } from "../../utils/cli-progress.js";
+import { reviewPlan, findingsCount, findingsCountByType } from "../../plan/plan-reviewer.js";
+import { applyReviewerFeedback, applyFixerPatch } from "../../plan/plan-fixer.js";
+import { runStructuralPass } from "../../plan/plan-structural-pass.js";
+import { loadPlan, savePlan } from "../../plan/plan-store.js";
+
+export async function planFixCommand({ config, planId, prompt, logger, json }) {
+  const projectDir = config.projectDir || process.cwd();
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) throw new Error(`Plan no encontrado: ${planId}`);
+  if (!Array.isArray(plan.hus) || plan.hus.length === 0) {
+    throw new Error(`Plan ${planId} no tiene HUs.`);
+  }
+
+  const before = { hus: plan.hus.length, deps: plan.hus.reduce((a, h) => a + (h.blocked_by?.length || 0), 0) };
+
+  const plannerRole = resolveRole(config, "planner");
+  await assertAgentsAvailable([plannerRole.provider]);
+  const planner = createAgent(plannerRole.provider, config, logger);
+  const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
+    ? Math.round(Number(config.session.max_agent_silence_minutes) * 60 * 1000) : undefined;
+  const timeoutMs = Number(config?.session?.max_planner_minutes) > 0
+    ? Math.round(Number(config.session.max_planner_minutes) * 60 * 1000) : undefined;
+
+  // Reviewer con prompt opcional del usuario inyectado como contexto extra.
+  // El prompt se prepende al task original para que el reviewer LLM lo lea
+  // antes de la HU list.
+  const enrichedTask = prompt
+    ? `${plan.task || ""}\n\n## USER FEEDBACK (priorizar estos puntos)\n${prompt}\n`
+    : plan.task || "";
+
+  const reviewProgress = createCliProgressReporter({ role: "plan-fix:reviewer", quiet: Boolean(json) });
+  const review = await reviewPlan({
+    agent: planner, task: enrichedTask, hus: plan.hus,
+    onOutput: reviewProgress.onOutput, silenceTimeoutMs, timeoutMs,
+  });
+  reviewProgress.finish(review.ok ? "done" : "failed");
+  if (!review.ok) throw new Error(`Reviewer falló: ${review.error}`);
+  plan.review = review.findings;
+  let count = findingsCount(review.findings);
+  if (!json) process.stderr.write(`Reviewer encontró ${count} item(s).\n`);
+
+  // Self-fix loop con smart convergence guard (mismo que generate.js).
+  const maxIter = 4;
+  for (let i = 1; i <= maxIter && count > 0; i++) {
+    const husSnapshot = JSON.parse(JSON.stringify(plan.hus));
+    const reviewSnapshot = JSON.parse(JSON.stringify(plan.review));
+    const fixProgress = createCliProgressReporter({ role: `plan-fix:iter ${i}`, quiet: Boolean(json) });
+    const fix = await applyReviewerFeedback({
+      agent: planner, task: enrichedTask, hus: plan.hus, findings: plan.review,
+      onOutput: fixProgress.onOutput, silenceTimeoutMs, timeoutMs,
+    });
+    if (!fix.ok) { fixProgress.finish("failed"); break; }
+    const ops = applyFixerPatch(plan, fix.patch);
+    if (ops.added + ops.depsAdded + ops.deleted === 0) { fixProgress.finish("done"); break; }
+    const review2 = await reviewPlan({
+      agent: planner, task: enrichedTask, hus: plan.hus,
+      onOutput: fixProgress.onOutput, silenceTimeoutMs, timeoutMs,
+    });
+    if (!review2.ok) { plan.hus = husSnapshot; plan.review = reviewSnapshot; fixProgress.finish("failed"); break; }
+    const b = findingsCountByType(reviewSnapshot);
+    const a = findingsCountByType(review2.findings);
+    const accept = a.priority < b.priority || (a.priority === b.priority && a.total <= b.total);
+    if (!accept) { plan.hus = husSnapshot; plan.review = reviewSnapshot; fixProgress.finish("reverted"); break; }
+    plan.review = review2.findings;
+    count = a.total;
+    fixProgress.finish("done");
+  }
+
+  // Structural integrity pass determinístico al final.
+  const { fixes: structuralFixes } = runStructuralPass(plan);
+  if (structuralFixes.length > 0) {
+    if (!plan.review) plan.review = {};
+    plan.review.structural_fixes = structuralFixes;
+  }
+
+  await savePlan(projectDir, plan);
+  const after = { hus: plan.hus.length, deps: plan.hus.reduce((a, h) => a + (h.blocked_by?.length || 0), 0) };
+
+  if (json) {
+    console.log(JSON.stringify({ planId, before, after, structuralFixes }, null, 2));
+    return;
+  }
+  const diffHus = after.hus - before.hus;
+  const diffDeps = after.deps - before.deps;
+  const structuralSummary = structuralFixes.length > 0
+    ? `, ${structuralFixes.length} structural fix(es)` : "";
+  console.log(
+    `kj plan fix ${planId}: ${diffHus >= 0 ? "+" : ""}${diffHus} HUs, ${diffDeps >= 0 ? "+" : ""}${diffDeps} deps${structuralSummary}. Findings: ${count} restantes.`
+  );
+}

package/src/commands/plan/generate.js

@@ -8,6 +8,9 @@ import { runAutoGC, summarizeGC } from "../../utils/garbage-collector.js";
 import { promptProjectName } from "../../utils/prompt-project-name.js";
 import { deriveProjectNameFromCwd } from "../../utils/derive-project-name-from-cwd.js";
 import { applyReviewerFeedback, applyFixerPatch } from "../../plan/plan-fixer.js";
+import { runStructuralPass } from "../../plan/plan-structural-pass.js";
+import { recommendModelsForHu, complexityFromTaskType } from "../../hu/model-router.js";
+import { withBrainRecovery } from "../../brain/with-brain-recovery.js";
 import { formatPlan, formatHuTable } from "./_shared.js";
 
 /**
@@ -51,14 +54,23 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
   // Live progress to stderr so the user sees what the planner is doing
   // instead of staring at a silent shell for 30 s – 3 min. `--json` mode
   // stays quiet so stdout remains a pure JSON document.
-  const progress = createCliProgressReporter({ role: "planner", quiet: Boolean(json) });
+  // Sub-progress por fase (KJC outputs limpios): cada llamada al
+  // agente arranca su propio "[planner:fase] starting → done" para
+  // que el usuario no piense que "[planner] done" significa "el
+  // comando entero terminó" — sigue habiendo tests-synth, reviewer,
+  // self-fix iter N por delante.
+  const progress = createCliProgressReporter({ role: "planner:initial", quiet: Boolean(json) });
   let result;
   try {
-    result = await planner.runTask({
-      prompt, role: "planner", silenceTimeoutMs, timeoutMs,
-      onOutput: progress.onOutput,
+    // KJC-TSK-0413: planner inicial pasa por Brain Recovery — clasifica
+    // 401/429/5xx/SILENCED/etc y decide retry/standby/hibernate/abort.
+    result = await withBrainRecovery({
+      agent: planner,
+      taskArgs: { prompt, role: "planner", silenceTimeoutMs, timeoutMs, onOutput: progress.onOutput },
+      role: "planner",
+      logger,
     });
-    progress.finish(result.ok ? "done" : "failed");
+    progress.finish(result.ok ? "done" : (result.action || "failed"));
   } catch (err) {
     progress.finish("failed");
     throw err;
@@ -124,19 +136,38 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     const rawTests = typeof step === "object" ? step.acceptance_tests : null;
     const tests = normaliseAcceptanceTests(rawTests);
     if (tests.length === 0) stepsMissingTests += 1;
+    // Humanización IDs: preservar el id simbólico del planner ("INFRA-001",
+    // "AUTH-SIGNUP", etc.) como short_id del HU. La clave canónica
+    // sigue siendo el `hu.id` largo (`hu_<planId>_<NNN>`); el short_id
+    // solo da una etiqueta amigable que la CLI muestra y acepta como
+    // referencia en `kj run --hu INFRA-001`.
+    const symbolicId = typeof step === "object" && typeof step.id === "string" && step.id.trim()
+      ? step.id.trim() : null;
+    const taskType = classifyTaskType(desc);
+    // KJC-TSK-0405 step 2: asigna coder_model + reviewer_model
+    // automáticamente según complexity inferido del task_type. El
+    // planner puede emitir `step.complexity` (trivial/simple/medium/complex
+    // o score 1-5) para override más fino. Cross-provider reviewer
+    // (claude↔codex) por defecto.
+    const coderProvider = config?.roles?.coder?.provider || config?.coder || "claude";
+    const complexity = (typeof step === "object" && step.complexity)
+      ? step.complexity
+      : complexityFromTaskType(taskType);
+    const models = recommendModelsForHu({ complexity, coderProvider, config });
     const hu = addHu(plan, {
       title: desc.slice(0, 80),
-      task_type: classifyTaskType(desc),
+      task_type: taskType,
       scope: desc,
       blocked_by: [],
       acceptance_tests: tests,
-      // Spec mapping (PR C): preserve the planner's section citation
-      // so the coder/reviewer / board can show "implements §5.3".
+      short_id: symbolicId,
       spec_section: typeof step === "object" && typeof step.spec_section === "string" ? step.spec_section.trim() || null : null,
+      coder_model: models.coder_model,
+      coder_provider: models.coder_provider,
+      reviewer_model: models.reviewer_model,
+      reviewer_provider: models.reviewer_provider,
     });
-    if (typeof step === "object" && typeof step.id === "string" && step.id.trim()) {
-      symbolicToHuId.set(step.id.trim(), hu.id);
-    }
+    if (symbolicId) symbolicToHuId.set(symbolicId, hu.id);
     const deps = typeof step === "object" && Array.isArray(step.dependencies) ? step.dependencies : [];
     stepDeps.push(deps);
     const reuse = typeof step === "object" && Array.isArray(step.reuse) ? step.reuse : [];
@@ -169,7 +200,10 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     runLog.logText(
       `[planner] ${stepsMissingTests}/${steps.length} HUs missing acceptance_tests — running tests-synthesizer pass`
     );
-    progress.onOutput?.({ line: `${stepsMissingTests} HU(s) missing tests — running synthesizer pass`, kind: "text" });
+    // Sub-progress reporter por fase: el usuario ve cada fase como su
+    // propio "[planner:X] starting → done" en vez de un solo
+    // "[planner] done" que oculta que aún hay trabajo en cola.
+    const synthProgress = createCliProgressReporter({ role: "planner:tests-synth", quiet: Boolean(json) });
     const { synthesizeMissingTests } = await import("../../plan/tests-synthesizer.js");
     const husNeedingTests = plan.hus
       .filter((h) => !Array.isArray(h.acceptance_tests) || h.acceptance_tests.length === 0)
@@ -178,10 +212,11 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       agent: planner,
       task,
       husNeedingTests,
-      onOutput: progress.onOutput,
+      onOutput: synthProgress.onOutput,
       silenceTimeoutMs,
       timeoutMs,
     });
+    synthProgress.finish(synthResult.ok ? "done" : "failed");
     if (synthResult.ok) {
       let patched = 0;
       for (const hu of plan.hus) {
@@ -216,16 +251,17 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
   const skipReview = Boolean(flags?.noPlanReview || flags?.quick);
   if (plan.hus.length > 0 && !skipReview) {
     runLog.logText("[planner] running plan reviewer pass");
-    progress.onOutput?.({ line: "Reviewing the plan for gaps / overlaps / order issues", kind: "text" });
-    const { reviewPlan, findingsCount } = await import("../../plan/plan-reviewer.js");
+    const reviewProgress = createCliProgressReporter({ role: "planner:reviewer", quiet: Boolean(json) });
+    const { reviewPlan, findingsCount, findingsCountByType } = await import("../../plan/plan-reviewer.js");
     const review = await reviewPlan({
       agent: planner,
       task,
       hus: plan.hus,
-      onOutput: progress.onOutput,
+      onOutput: reviewProgress.onOutput,
       silenceTimeoutMs,
       timeoutMs,
     });
+    reviewProgress.finish(review.ok ? "done" : "failed");
     if (review.ok) {
       plan.review = review.findings;
       const count = findingsCount(review.findings);
@@ -239,13 +275,18 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       // PATCH the plan, apply in-process, and re-review. Loop until 0
       // findings or maxIterations. Skippable with --no-plan-fixer/--quick.
       const skipFixer = Boolean(flags?.noPlanFixer || flags?.quick);
-      const maxFixerIterations = 2;
+      // KJC-BUG-0054: bumped 2 → 4 — el guard antiguo cortaba el loop
+      // demasiado pronto cuando había muchos hallazgos. Con el guard
+      // inteligente (priority vs secondary) podemos permitir más
+      // iteraciones sin riesgo de divergir indefinidamente, porque
+      // cada iter que NO reduce priority ni total se revierte.
+      const maxFixerIterations = 4;
       if (count > 0 && !skipFixer) {
         for (let i = 1; i <= maxFixerIterations; i++) {
           const currentCount = findingsCount(plan.review);
           if (currentCount === 0) break;
           runLog.logText(`[planner] self-fix iter ${i}/${maxFixerIterations} — patching ${currentCount} issue(s)`);
-          progress.onOutput?.({ line: `Self-fix iter ${i}: patching ${currentCount} issue(s)`, kind: "text" });
+          const fixProgress = createCliProgressReporter({ role: `planner:self-fix iter ${i}`, quiet: Boolean(json) });
           // KJC-BUG-0046 / P5: snapshot plan + review BEFORE applying the patch
           // so we can revert if the iteration regresses (newCount > currentCount).
           // Dogfooding 2026-05-12: GRETA Plan 2 iter 2 went 10 → 17 findings
@@ -256,38 +297,66 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
           const reviewSnapshot = JSON.parse(JSON.stringify(plan.review));
           const fix = await applyReviewerFeedback({
             agent: planner, task, hus: plan.hus, findings: plan.review,
-            onOutput: progress.onOutput, silenceTimeoutMs, timeoutMs,
+            onOutput: fixProgress.onOutput, silenceTimeoutMs, timeoutMs,
           });
           if (!fix.ok) {
+            fixProgress.finish("failed");
             runLog.logText(`[planner] self-fix iter ${i} failed (non-blocking): ${fix.error}`);
             break;
           }
           const ops = applyFixerPatch(plan, fix.patch);
           runLog.logText(`[planner] self-fix iter ${i} applied: +${ops.added} HU, +${ops.depsAdded} dep, -${ops.deleted} HU`);
           if (ops.added + ops.depsAdded + ops.deleted === 0) {
+            fixProgress.finish("done");
             runLog.logText(`[planner] self-fix iter ${i} empty patch — stopping`);
             break;
           }
           const review2 = await reviewPlan({
             agent: planner, task, hus: plan.hus,
-            onOutput: progress.onOutput, silenceTimeoutMs, timeoutMs,
+            onOutput: fixProgress.onOutput, silenceTimeoutMs, timeoutMs,
           });
           if (!review2.ok) {
+            fixProgress.finish("failed");
             runLog.logText(`[planner] re-review after iter ${i} failed: ${review2.error}`);
             plan.hus = husSnapshot;
             plan.review = reviewSnapshot;
             break;
           }
-          const newCount = findingsCount(review2.findings);
-          if (newCount > currentCount) {
-            // P5 convergence guard: iter made things worse — revert + stop.
+          // KJC-BUG-0054: smart convergence guard. El guard antiguo
+          // (newCount > currentCount → revert) tiraba iteraciones
+          // VÁLIDAS que arreglaban un ciclo o una HU faltante pero
+          // a cambio creaban deps menores. Ahora distinguimos:
+          //   - priority = cycles + missing_hus (CRÍTICO, no ignorable)
+          //   - secondary = missing_deps + overlaps + order non-circular
+          //
+          // Reglas (en orden):
+          //   1. priority bajó → ACEPTAR (aunque secondary suba — el plan es ejecutable)
+          //   2. priority igual + total bajó → ACEPTAR
+          //   3. priority igual + total igual → ACEPTAR (lateral move, da chance)
+          //   4. priority subió → REVERT
+          //   5. priority igual + total subió → REVERT (regresión genuina)
+          const before = findingsCountByType(reviewSnapshot);
+          const after = findingsCountByType(review2.findings);
+          const newCount = after.total;
+          const accept =
+            after.priority < before.priority
+            || (after.priority === before.priority && after.total <= before.total);
+          if (!accept) {
+            const reason = after.priority > before.priority
+              ? `priority ${before.priority}→${after.priority}`
+              : `total ${before.total}→${after.total} (priority unchanged at ${after.priority})`;
             plan.hus = husSnapshot;
             plan.review = reviewSnapshot;
-            runLog.logText(`[planner] self-fix iter ${i} regressed (${currentCount} → ${newCount}) — reverted, stopping`);
+            fixProgress.finish("reverted");
+            runLog.logText(`[planner] self-fix iter ${i} regressed (${reason}) — reverted, stopping`);
             break;
           }
           plan.review = review2.findings;
-          runLog.logText(`[planner] after self-fix iter ${i}: ${newCount} issue(s) remaining`);
+          fixProgress.finish("done");
+          const deltaSummary = after.priority < before.priority
+            ? `priority ${before.priority}→${after.priority}, total ${before.total}→${after.total}`
+            : `total ${before.total}→${after.total}`;
+          runLog.logText(`[planner] after self-fix iter ${i}: ${newCount} issue(s) (${deltaSummary})`);
         }
       }
     } else {
@@ -295,6 +364,19 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     }
   }
 
+  // KJC-TSK-0399: deterministic structural integrity pass — cycles,
+  // orphan refs, missing short_id. Runs after self-fix loop because
+  // the LLM is bad at graph problems. Always runs (cheap, no network).
+  if (plan.hus.length > 0) {
+    const { fixes } = runStructuralPass(plan);
+    if (fixes.length > 0) {
+      if (!plan.review) plan.review = {};
+      plan.review.structural_fixes = fixes;
+      const byKind = fixes.reduce((a, f) => ({ ...a, [f.kind]: (a[f.kind] || 0) + 1 }), {});
+      runLog.logText(`[planner] structural pass: ${fixes.length} fix(es) — ${JSON.stringify(byKind)}`);
+    }
+  }
+
   const planId = await savePlan(projectDir, plan);
   const { plansDir } = await import("../../plan/plan-store.js");
   const path = await import("node:path");
@@ -341,9 +423,12 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       console.log(`Reviewer flagged: ${counts.join(", ")} — see \`kj plan show ${planId}\``);
     }
   }
+  // Humanización IDs: si el plan tiene alias, lo preferimos como
+  // referencia visible (más legible). Fallback al planId.
+  const ref = plan.alias || planId;
   console.log("");
-  console.log(`Inspect: kj plan show ${planId}`);
-  console.log(`Run:     kj run --plan ${planId} "${task.slice(0, 40)}..."`);
+  console.log(`Inspect: kj plan show ${ref}`);
+  console.log(`Run:     kj run --plan ${ref}`);
   console.log(`         (or click ▶ Run plan on the board, if running)`);
 
   // UX boost for HU-bearing plans: auto-start the HU Board (same pattern as

package/src/commands/plan/index.js

@@ -9,6 +9,8 @@ export { planValidateCommand } from "./validate.js";
 export { planDeleteCommand } from "./delete.js";
 export { planAddHuCommand } from "./add-hu.js";
 export { planRemoveHuCommand } from "./remove-hu.js";
+export { planMigrateResultCommand } from "./migrate-result.js";
+export { planFixCommand } from "./fix.js";
 
 // Keep backward compat — old callers import planCommand
 export const planCommand = planGenerateCommand;

package/src/commands/plan/migrate-result.js

@@ -0,0 +1,41 @@
+/**
+ * kj plan migrate-result [--dry-run] — KJC-TSK-0394 step 4.
+ * Siembra `result` en las HUs de los plan files existentes,
+ * deducido del status legacy. Idempotente.
+ */
+import { listPlans, loadPlan, savePlan } from "../../plan/plan-store.js";
+import { migratePlanResult } from "../../plan/plan-migrate-result.js";
+
+export async function planMigrateResultCommand({ config, flags = {} }) {
+  const projectDir = config.projectDir || process.cwd();
+  const dryRun = !!flags.dryRun;
+
+  const plans = await listPlans(projectDir);
+  if (plans.length === 0) {
+    console.log("No hay plans que migrar en este proyecto.");
+    return;
+  }
+
+  let totalPlans = 0;
+  let totalHus = 0;
+  for (const meta of plans) {
+    const plan = await loadPlan(projectDir, meta.planId);
+    if (!plan) continue;
+    const { plan: migrated, changes } = migratePlanResult(plan);
+    if (changes.length === 0) continue;
+    totalPlans += 1;
+    totalHus += changes.length;
+    const summary = changes
+      .map((c) => `${c.huId}→${c.result ?? "null"}`)
+      .join(", ");
+    console.log(`${dryRun ? "[dry-run] " : ""}${meta.planId}: ${changes.length} HU(s) — ${summary}`);
+    if (!dryRun) await savePlan(projectDir, migrated);
+  }
+
+  if (totalPlans === 0) {
+    console.log("Todos los plans ya tienen `result` sembrado. Nada que hacer.");
+  } else {
+    const prefix = dryRun ? "[dry-run] " : "";
+    console.log(`${prefix}Migrados ${totalHus} HU(s) en ${totalPlans} plan(s).`);
+  }
+}

package/src/commands/plan.js

@@ -10,5 +10,7 @@ export {
   planDeleteCommand,
   planAddHuCommand,
   planRemoveHuCommand,
+  planMigrateResultCommand,
+  planFixCommand,
   planCommand,
 } from "./plan/index.js";

package/src/commands/researcher.js

@@ -2,6 +2,7 @@ import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -33,8 +34,11 @@ export async function researcherCommand({ task, config, logger }) {
     const progress = createCliProgressReporter({ role: "researcher" });
     let result;
     try {
-      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "researcher" });
-      progress.finish(result.ok ? "done" : "failed");
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "researcher" },
+        role: "researcher", provider: researcherRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
     } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {

package/src/commands/run.js

@@ -4,6 +4,7 @@ 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 { resolveRole } from "../config.js";
@@ -112,6 +113,28 @@ export async function runCommandHandler({ task, config, logger, flags }) {
   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;
 
@@ -139,7 +162,16 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     }
 
     const askQuestion = createCliAskQuestion();
-    const result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+    let result;
+    try {
+      result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, 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));