karajan-code 2.14.2 → 2.15.0

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));

package/src/commands/standby.js

@@ -0,0 +1,114 @@
+// 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) console.log(`    plan: ${s.planId}${s.huId ? `, HU: ${s.huId}` : ""}`);
+  }
+}
+
+/**
+ * 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/triage.js

@@ -4,6 +4,7 @@ import { resolveRole } from "../config.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { buildTriagePrompt } from "../prompts/triage.js";
 import { parseMaybeJsonString } from "../review/parser.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 function formatTriage(result) {
   const lines = [];
@@ -47,8 +48,11 @@ export async function triageCommand({ task, config, logger, json }) {
     const progress = createCliProgressReporter({ role: "triage" });
     let result;
     try {
-      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "triage" });
-      progress.finish(result.ok ? "done" : "failed");
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "triage" },
+        role: "triage", provider: triageRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
     } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {