karajan-code 1.5.0 → 1.6.0

package/README.md

@@ -39,6 +39,8 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Session management** — pause/resume with fail-fast detection and automatic cleanup of expired sessions
 - **Plugin system** — extend with custom agents via `.karajan/plugins/`
 - **Smart model selection** — auto-selects optimal model per role based on triage complexity (lighter models for trivial tasks, powerful models for complex ones)
+- **Interactive checkpoints** — instead of killing long-running tasks, pauses every 5 minutes with a progress report and lets you decide: continue, stop, or adjust the time
+- **Task decomposition** — triage detects when tasks should be split and recommends subtasks; with Planning Game integration, creates linked cards with sequential blocking
 - **Retry with backoff** — automatic recovery from transient API errors (429, 5xx) with exponential backoff and jitter
 - **Planning Game integration** — optionally pair with [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) for agile project management (tasks, sprints, estimation) — like Jira, but open-source and XP-native
 
@@ -199,6 +201,7 @@ kj run "Fix the login bug" [options]
 | `--smart-models` | Enable smart model selection based on triage complexity |
 | `--no-smart-models` | Disable smart model selection |
 | `--no-sonar` | Skip SonarQube analysis |
+| `--checkpoint-interval <n>` | Minutes between interactive checkpoints (default: 5) |
 | `--pg-task <cardId>` | Planning Game card ID for task context |
 | `--pg-project <projectId>` | Planning Game project ID |
 | `--dry-run` | Show what would run without executing |
@@ -349,6 +352,7 @@ git:
 session:
   max_iteration_minutes: 15
   max_total_minutes: 120
+  checkpoint_interval_minutes: 5  # Interactive checkpoint every N minutes
   max_budget_usd: null         # null = unlimited
   fail_fast_repeats: 2
 
@@ -443,7 +447,7 @@ Use `kj roles show <role>` to inspect any template. Create a project override to
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 964+ tests with Vitest
+npm test              # Run 1025+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```

package/docs/README.es.md

@@ -38,6 +38,8 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Automatizacion Git** — auto-commit, auto-push, auto-PR tras aprobacion
 - **Gestion de sesiones** — pausa/reanudacion con deteccion fail-fast y limpieza automatica de sesiones expiradas
 - **Sistema de plugins** — extiende con agentes custom via `.karajan/plugins/`
+- **Checkpoints interactivos** — en lugar de matar tareas largas, pausa cada 5 minutos con un informe de progreso y te deja decidir: continuar, parar o ajustar el tiempo
+- **Descomposicion de tareas** — triage detecta cuando una tarea debe dividirse y recomienda subtareas; con integracion Planning Game, crea cards vinculadas con bloqueo secuencial
 - **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
 - **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
 

package/package.json

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

package/src/cli.js

@@ -24,7 +24,7 @@ async function withConfig(commandName, flags, fn) {
 }
 
 const program = new Command();
-program.name("kj").description("Karajan Code CLI").version("1.5.0");
+program.name("kj").description("Karajan Code CLI").version("1.6.0");
 
 program
   .command("init")
@@ -81,6 +81,7 @@ program
   .option("--methodology <name>")
   .option("--no-auto-rebase")
   .option("--no-sonar")
+  .option("--checkpoint-interval <n>", "Minutes between interactive checkpoints (default: 5)")
   .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
   .option("--pg-project <projectId>", "Planning Game project ID")
   .option("--smart-models", "Enable smart model selection based on triage complexity")
@@ -140,6 +141,7 @@ program
   .option("--format <type>", "Output format: text|json", "text")
   .option("--trace", "Show chronological trace of all pipeline stages")
   .option("--currency <code>", "Display costs in currency: usd|eur", "usd")
+  .option("--pg-task <cardId>", "Filter reports by Planning Game card ID")
   .action(async (flags) => {
     await reportCommand(flags);
   });

package/src/commands/report.js

@@ -135,7 +135,7 @@ async function buildReport(dir, sessionId) {
 
   const budgetTrace = Array.isArray(session.budget?.trace) ? session.budget.trace : [];
 
-  return {
+  const report = {
     session_id: session.id,
     task_description: session.task || "",
     plan_executed: summarizePlan(checkpoints),
@@ -150,6 +150,9 @@ async function buildReport(dir, sessionId) {
     commits_generated: commits,
     status: session.status || "unknown"
   };
+  if (session.pg_task_id) report.pg_task_id = session.pg_task_id;
+  if (session.pg_project_id) report.pg_project_id = session.pg_project_id;
+  return report;
 }
 
 function printTextReport(report) {
@@ -178,6 +181,10 @@ function printTextReport(report) {
       : String(report.commits_generated.count);
 
   console.log(`Session: ${report.session_id}`);
+  if (report.pg_task_id) {
+    const projectLabel = report.pg_project_id ? ` (${report.pg_project_id})` : "";
+    console.log(`Planning Game Card: ${report.pg_task_id}${projectLabel}`);
+  }
   console.log(`Status: ${report.status}`);
   console.log("Task Description:");
   console.log(report.task_description || "N/A");
@@ -233,13 +240,14 @@ function printTraceTable(trace, { currency = "usd", exchangeRate = 0.92 } = {})
 
   const currencyLabel = currency.toUpperCase();
 
-  const headers = ["#", "Stage", "Provider", "Duration", "Tokens In", "Tokens Out", `Cost ${currencyLabel}`];
+  const headers = ["#", "Stage", "Provider", "Model", "Duration", "Tokens In", "Tokens Out", `Cost ${currencyLabel}`];
   const rows = trace.map((entry) => {
     const cost = convertCost(entry.cost_usd, currency, exchangeRate);
     return [
       String(entry.index ?? "-"),
       entry.role,
       entry.provider || "-",
+      entry.model || "-",
       formatDuration(entry.duration_ms),
       String(entry.tokens_in),
       String(entry.tokens_out),
@@ -262,6 +270,7 @@ function printTraceTable(trace, { currency = "usd", exchangeRate = 0.92 } = {})
     "",
     "TOTAL",
     "",
+    "",
     formatDuration(totals.duration),
     String(totals.tokens_in),
     String(totals.tokens_out),
@@ -273,7 +282,7 @@ function printTraceTable(trace, { currency = "usd", exchangeRate = 0.92 } = {})
     Math.max(...allRows.map((row) => String(row[colIdx]).length))
   );
 
-  const rightAligned = new Set([0, 3, 4, 5, 6]);
+  const rightAligned = new Set([0, 4, 5, 6, 7]);
   function formatRow(row) {
     return row
       .map((cell, idx) =>
@@ -293,7 +302,26 @@ function printTraceTable(trace, { currency = "usd", exchangeRate = 0.92 } = {})
   console.log(formatRow(totalRow));
 }
 
-export async function reportCommand({ list = false, sessionId = null, format = "text", trace = false, currency = "usd" }) {
+async function findSessionsByPgTask(dir, pgTask) {
+  const entries = await fs.readdir(dir);
+  const matches = [];
+  for (const entry of entries) {
+    const sessionFile = path.join(dir, entry, "session.json");
+    if (!(await exists(sessionFile))) continue;
+    try {
+      const raw = await fs.readFile(sessionFile, "utf8");
+      const session = JSON.parse(raw);
+      if (session.pg_task_id === pgTask) {
+        matches.push(entry);
+      }
+    } catch {
+      // skip malformed sessions
+    }
+  }
+  return matches.sort();
+}
+
+export async function reportCommand({ list = false, sessionId = null, format = "text", trace = false, currency = "usd", pgTask = null }) {
   const dir = getSessionRoot();
   if (!(await exists(dir))) {
     console.log("No reports yet");
@@ -301,6 +329,45 @@ export async function reportCommand({ list = false, sessionId = null, format = "
   }
 
   const entries = await fs.readdir(dir);
+
+  if (pgTask) {
+    const matches = await findSessionsByPgTask(dir, pgTask);
+    if (matches.length === 0) {
+      console.log(`No sessions found for card: ${pgTask}`);
+      return;
+    }
+    if (list) {
+      for (const item of matches) console.log(item);
+      return;
+    }
+    // Show all reports for this card, or the latest if no list flag
+    const targetId = sessionId || matches.at(-1);
+    const report = await buildReport(dir, targetId);
+    if (format === "json") {
+      console.log(JSON.stringify({ card: pgTask, sessions: matches, report }, null, 2));
+      return;
+    }
+    console.log(`Card ${pgTask}: ${matches.length} session${matches.length === 1 ? "" : "s"}`);
+    for (const m of matches) {
+      const marker = m === targetId ? " <--" : "";
+      console.log(`  ${m}${marker}`);
+    }
+    console.log("");
+    if (trace) {
+      const { config } = await loadConfig();
+      const cur = currency?.toLowerCase() || config?.budget?.currency || "usd";
+      const rate = config?.budget?.exchange_rate_eur ?? 0.92;
+      console.log(`Session: ${report.session_id}`);
+      console.log(`Status: ${report.status}`);
+      console.log(`Task: ${report.task_description || "N/A"}`);
+      console.log("");
+      printTraceTable(report.budget_trace, { currency: cur, exchangeRate: rate });
+    } else {
+      printTextReport(report);
+    }
+    return;
+  }
+
   if (list) {
     for (const item of entries) console.log(item);
     return;
@@ -327,6 +394,10 @@ export async function reportCommand({ list = false, sessionId = null, format = "
     const cur = currency?.toLowerCase() || config?.budget?.currency || "usd";
     const rate = config?.budget?.exchange_rate_eur ?? 0.92;
     console.log(`Session: ${report.session_id}`);
+    if (report.pg_task_id) {
+      const projectLabel = report.pg_project_id ? ` (${report.pg_project_id})` : "";
+      console.log(`Planning Game Card: ${report.pg_task_id}${projectLabel}`);
+    }
     console.log(`Status: ${report.status}`);
     console.log(`Task: ${report.task_description || "N/A"}`);
     console.log("");
@@ -337,4 +408,4 @@ export async function reportCommand({ list = false, sessionId = null, format = "
   printTextReport(report);
 }
 
-export { formatDuration, convertCost, formatCost, printTraceTable, buildReport };
+export { formatDuration, convertCost, formatCost, printTraceTable, buildReport, findSessionsByPgTask };

package/src/commands/run.js

@@ -66,7 +66,7 @@ export async function runCommandHandler({ task, config, logger, flags }) {
   }
 
   const startDate = new Date().toISOString();
-  const result = await runFlow({ task: enrichedTask, config, logger, flags, emitter });
+  const result = await runFlow({ task: enrichedTask, config, logger, flags, emitter, pgTaskId: pgCardId || null, pgProject: pgProject || null });
 
   // --- Planning Game: update card on completion ---
   if (pgCard && pgProject && result?.approved) {

package/src/config.js

@@ -112,8 +112,9 @@ const DEFAULTS = {
     role_overrides: {}
   },
   session: {
-    max_iteration_minutes: 15,
+    max_iteration_minutes: 30,
     max_total_minutes: 120,
+    checkpoint_interval_minutes: 5,
     fail_fast_repeats: 2,
     repeat_detection_threshold: 2,
     max_sonar_retries: 3,
@@ -244,6 +245,7 @@ export function applyRunOverrides(config, flags) {
   if (flags.maxIterations) out.max_iterations = Number(flags.maxIterations);
   if (flags.maxIterationMinutes) out.session.max_iteration_minutes = Number(flags.maxIterationMinutes);
   if (flags.maxTotalMinutes) out.session.max_total_minutes = Number(flags.maxTotalMinutes);
+  if (flags.checkpointInterval) out.session.checkpoint_interval_minutes = Number(flags.checkpointInterval);
   if (flags.baseBranch) out.base_branch = flags.baseBranch;
   if (flags.coderFallback) out.coder_options.fallback_coder = flags.coderFallback;
   if (flags.reviewerFallback) out.reviewer_options.fallback_reviewer = flags.reviewerFallback;

package/src/git/automation.js

@@ -52,7 +52,37 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
   return { enabled: true, branch, baseBranch, autoRebase };
 }
 
-export async function finalizeGitAutomation({ config, gitCtx, task, logger, session }) {
+export function buildPrBody({ task, stageResults }) {
+  const sections = ["Created by Karajan Code."];
+
+  const approach = stageResults?.planner?.approach;
+  if (approach) {
+    sections.push("", "## Approach", approach);
+  }
+
+  const steps = stageResults?.planner?.steps;
+  if (steps?.length) {
+    sections.push("", "## Steps");
+    for (let i = 0; i < steps.length; i++) {
+      sections.push(`${i + 1}. ${steps[i]}`);
+    }
+  }
+
+  const triageSubtasks = stageResults?.triage?.subtasks;
+  const shouldDecompose = stageResults?.triage?.shouldDecompose;
+  const pendingSubtasks = shouldDecompose && triageSubtasks?.length > 1 ? triageSubtasks.slice(1) : [];
+  if (pendingSubtasks.length > 0) {
+    sections.push("", "## Pending subtasks");
+    sections.push("This PR addresses part of a larger task. The following subtasks were identified but not included:");
+    for (const subtask of pendingSubtasks) {
+      sections.push(`- [ ] ${subtask}`);
+    }
+  }
+
+  return sections.join("\n");
+}
+
+export async function finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults = null }) {
   if (!gitCtx?.enabled) return { git: "disabled", commits: [] };
 
   const commitMsg = config.git.commit_message || commitMessageFromTask(task);
@@ -86,11 +116,12 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
 
   let prUrl = null;
   if (config.git.auto_pr) {
+    const body = buildPrBody({ task, stageResults });
     prUrl = await createPullRequest({
       baseBranch: gitCtx.baseBranch,
       branch: gitCtx.branch,
       title: commitMessageFromTask(task),
-      body: "Created by Karajan Code."
+      body
     });
     await addCheckpoint(session, { stage: "git-pr", branch: gitCtx.branch, pr: prUrl });
     logger.info("Pull request created");

package/src/mcp/run-kj.js

@@ -51,6 +51,7 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
   normalizeBoolFlag(options.noSonar, "--no-sonar", args);
   if (options.smartModels === true) args.push("--smart-models");
   if (options.smartModels === false) args.push("--no-smart-models");
+  addOptionalValue(args, "--checkpoint-interval", options.checkpointInterval);
   addOptionalValue(args, "--pg-task", options.pgTask);
   addOptionalValue(args, "--pg-project", options.pgProject);
 
@@ -67,10 +68,12 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
     runEnv.KJ_SONAR_TOKEN = options.sonarToken;
   }
 
+  const timeout = options.timeoutMs ? Number(options.timeoutMs) : undefined;
+
   const result = await execa("node", args, {
     env: runEnv,
     reject: false,
-    timeout: options.timeoutMs ? Number(options.timeoutMs) : undefined
+    timeout
   });
 
   const ok = result.exitCode === 0;
@@ -81,7 +84,18 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
     stderr: result.stderr
   };
 
-  if (!ok && result.stderr) {
+  if (result.timedOut) {
+    payload.ok = false;
+    payload.timedOut = true;
+    payload.stderr = `Process timed out after ${Math.round((timeout || 0) / 1000)}s (explicit timeout). Consider using kj_run for interactive checkpoint support instead of subprocess commands.`;
+  }
+
+  if (result.killed && !payload.timedOut) {
+    payload.ok = false;
+    payload.stderr = `Process was killed by signal ${result.signal || "unknown"}. ${result.stderr || ""}`.trim();
+  }
+
+  if (!ok && result.stderr && !payload.timedOut) {
     payload.errorSummary = result.stderr.split("\n").filter(Boolean).slice(-3).join(" | ");
   }
 

package/src/mcp/server-handlers.js

@@ -66,7 +66,7 @@ export function classifyError(error) {
   if (lower.includes("timed out") || lower.includes("timeout")) {
     return {
       category: "timeout",
-      suggestion: "The operation timed out. Try increasing timeoutMs or maxIterationMinutes. If a scan timed out, check SonarQube health."
+      suggestion: "The agent did not complete in time. Try: (1) increase --max-iteration-minutes (default: 5), (2) split the task into smaller pieces, (3) use kj_code for single-agent tasks. If a SonarQube scan timed out, check Docker health."
     };
   }
 
@@ -145,7 +145,9 @@ export async function handleRunDirect(a, server, extra) {
   if (progressNotifier) emitter.on("progress", progressNotifier);
 
   const askQuestion = buildAskQuestion(server);
-  const result = await runFlow({ task: a.task, config, logger, flags: a, emitter, askQuestion });
+  const pgTaskId = a.pgTask || null;
+  const pgProject = a.pgProject || config.planning_game?.project_id || null;
+  const result = await runFlow({ task: a.task, config, logger, flags: a, emitter, askQuestion, pgTaskId, pgProject });
   return { ok: !result.paused && (result.approved !== false), ...result };
 }
 
@@ -212,6 +214,7 @@ export async function handleToolCall(name, args, server, extra) {
     if (a.format) commandArgs.push("--format", String(a.format));
     if (a.trace) commandArgs.push("--trace");
     if (a.currency) commandArgs.push("--currency", String(a.currency));
+    if (a.pgTask) commandArgs.push("--pg-task", String(a.pgTask));
     return runKjCommand({
       command: "report",
       commandArgs,

package/src/mcp/tools.js

@@ -86,6 +86,7 @@ export const tools = [
         autoRebase: { type: "boolean" },
         branchPrefix: { type: "string" },
         smartModels: { type: "boolean", description: "Enable/disable smart model selection based on triage complexity" },
+        checkpointInterval: { type: "number", description: "Minutes between interactive checkpoints (default: 5). Set 0 to disable." },
         noSonar: { type: "boolean" },
         kjHome: { type: "string" },
         sonarToken: { type: "string" },
@@ -118,6 +119,7 @@ export const tools = [
         format: { type: "string", enum: ["text", "json"] },
         trace: { type: "boolean", description: "Show chronological trace of all pipeline stages" },
         currency: { type: "string", enum: ["usd", "eur"], description: "Display costs in this currency" },
+        pgTask: { type: "string", description: "Filter reports by Planning Game card ID (e.g., KJC-TSK-0042)" },
         kjHome: { type: "string" }
       }
     }

package/src/orchestrator/iteration-stages.js

@@ -73,7 +73,7 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
         });
 
         if (fallbackResult.execResult?.ok) {
-          await addCheckpoint(session, { stage: "coder", iteration, note: `Coder completed via fallback (${fallbackCoder})` });
+          await addCheckpoint(session, { stage: "coder", iteration, note: `Coder completed via fallback (${fallbackCoder})`, provider: fallbackCoder, model: null });
           emitProgress(
             emitter,
             makeEvent("coder:end", { ...eventBase, stage: "coder" }, {
@@ -112,7 +112,7 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
     throw new Error(`Coder failed: ${details}`);
   }
 
-  await addCheckpoint(session, { stage: "coder", iteration, note: "Coder applied changes" });
+  await addCheckpoint(session, { stage: "coder", iteration, note: "Coder applied changes", provider: coderRole.provider, model: coderRole.model || null });
   emitProgress(
     emitter,
     makeEvent("coder:end", { ...eventBase, stage: "coder" }, {
@@ -169,7 +169,7 @@ export async function runRefactorerStage({ refactorerRole, config, logger, emitt
     );
     throw new Error(`Refactorer failed: ${details}`);
   }
-  await addCheckpoint(session, { stage: "refactorer", iteration, note: "Refactorer applied cleanups" });
+  await addCheckpoint(session, { stage: "refactorer", iteration, note: "Refactorer applied cleanups", provider: refactorerRole.provider, model: refactorerRole.model || null });
   emitProgress(
     emitter,
     makeEvent("refactorer:end", { ...eventBase, stage: "refactorer" }, {
@@ -285,7 +285,9 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
     iteration,
     project_key: sonarResult.projectKey,
     quality_gate: sonarResult.gateStatus,
-    open_issues: sonarResult.openIssuesTotal
+    open_issues: sonarResult.openIssuesTotal,
+    provider: "sonar",
+    model: null
   });
 
   emitProgress(
@@ -472,7 +474,9 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
     stage: "reviewer",
     iteration,
     approved: review.approved,
-    blocking_issues: review.blocking_issues.length
+    blocking_issues: review.blocking_issues.length,
+    provider: reviewerRole.provider,
+    model: reviewerRole.model || null
   });
 
   emitProgress(

package/src/orchestrator/post-loop-stages.js

@@ -25,7 +25,13 @@ export async function runTesterStage({ config, logger, emitter, eventBase, sessi
     duration_ms: Date.now() - testerStart
   });
 
-  await addCheckpoint(session, { stage: "tester", iteration, ok: testerOutput.ok });
+  await addCheckpoint(session, {
+    stage: "tester",
+    iteration,
+    ok: testerOutput.ok,
+    provider: config?.roles?.tester?.provider || coderRole.provider,
+    model: config?.roles?.tester?.model || coderRole.model || null
+  });
 
   emitProgress(
     emitter,
@@ -93,7 +99,13 @@ export async function runSecurityStage({ config, logger, emitter, eventBase, ses
     duration_ms: Date.now() - securityStart
   });
 
-  await addCheckpoint(session, { stage: "security", iteration, ok: securityOutput.ok });
+  await addCheckpoint(session, {
+    stage: "security",
+    iteration,
+    ok: securityOutput.ok,
+    provider: config?.roles?.security?.provider || coderRole.provider,
+    model: config?.roles?.security?.model || coderRole.model || null
+  });
 
   emitProgress(
     emitter,

package/src/orchestrator/pre-loop-stages.js

@@ -28,7 +28,13 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     duration_ms: Date.now() - triageStart
   });
 
-  await addCheckpoint(session, { stage: "triage", iteration: 0, ok: triageOutput.ok });
+  await addCheckpoint(session, {
+    stage: "triage",
+    iteration: 0,
+    ok: triageOutput.ok,
+    provider: config?.roles?.triage?.provider || coderRole.provider,
+    model: config?.roles?.triage?.model || coderRole.model || null
+  });
 
   const recommendedRoles = new Set(triageOutput.result?.roles || []);
   const roleOverrides = {};
@@ -41,11 +47,16 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     roleOverrides.securityEnabled = recommendedRoles.has("security");
   }
 
+  const shouldDecompose = triageOutput.result?.shouldDecompose || false;
+  const subtasks = triageOutput.result?.subtasks || [];
+
   const stageResult = {
     ok: triageOutput.ok,
     level: triageOutput.result?.level || null,
     roles: Array.from(recommendedRoles),
-    reasoning: triageOutput.result?.reasoning || null
+    reasoning: triageOutput.result?.reasoning || null,
+    shouldDecompose,
+    subtasks
   };
 
   let modelSelection = null;
@@ -73,6 +84,16 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     stageResult.modelSelection = modelSelection;
   }
 
+  if (shouldDecompose && subtasks.length > 0) {
+    emitProgress(
+      emitter,
+      makeEvent("triage:decompose", { ...eventBase, stage: "triage" }, {
+        message: `Task decomposition recommended: ${subtasks.length} subtask${subtasks.length === 1 ? "" : "s"}`,
+        detail: { shouldDecompose, subtasks }
+      })
+    );
+  }
+
   emitProgress(
     emitter,
     makeEvent("triage:end", { ...eventBase, stage: "triage" }, {
@@ -106,7 +127,13 @@ export async function runResearcherStage({ config, logger, emitter, eventBase, s
     duration_ms: Date.now() - researchStart
   });
 
-  await addCheckpoint(session, { stage: "researcher", iteration: 0, ok: researchOutput.ok });
+  await addCheckpoint(session, {
+    stage: "researcher",
+    iteration: 0,
+    ok: researchOutput.ok,
+    provider: config?.roles?.researcher?.provider || coderRole.provider,
+    model: config?.roles?.researcher?.model || coderRole.model || null
+  });
 
   emitProgress(
     emitter,
@@ -122,7 +149,7 @@ export async function runResearcherStage({ config, logger, emitter, eventBase, s
   return { researchContext, stageResult };
 }
 
-export async function runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, trackBudget }) {
+export async function runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, triageDecomposition = null, trackBudget }) {
   const task = session.task;
   logger.setContext({ iteration: 0, stage: "planner" });
   emitProgress(
@@ -134,11 +161,18 @@ export async function runPlannerStage({ config, logger, emitter, eventBase, sess
   );
 
   const planRole = new PlannerRole({ config, logger, emitter, createAgentFn: createAgent });
-  planRole.context = { task, research: researchContext };
+  planRole.context = { task, research: researchContext, triageDecomposition };
   await planRole.init();
   const plannerStart = Date.now();
   const planResult = await planRole.execute(task);
   trackBudget({ role: "planner", provider: plannerRole.provider, model: plannerRole.model, result: planResult.result, duration_ms: Date.now() - plannerStart });
+  await addCheckpoint(session, {
+    stage: "planner",
+    iteration: 0,
+    ok: planResult.ok,
+    provider: plannerRole.provider,
+    model: plannerRole.model || null
+  });
 
   if (!planResult.ok) {
     await markSessionStatus(session, "failed");

package/src/orchestrator.js

@@ -4,7 +4,8 @@ import {
   loadSession,
   markSessionStatus,
   resumeSessionWithAnswer,
-  saveSession
+  saveSession,
+  addCheckpoint
 } from "./session-store.js";
 import { computeBaseRef, generateDiff } from "./review/diff-generator.js";
 import { buildCoderPrompt } from "./prompts/coder.js";
@@ -27,7 +28,7 @@ import { runTesterStage, runSecurityStage } from "./orchestrator/post-loop-stage
 
 
 
-export async function runFlow({ task, config, logger, flags = {}, emitter = null, askQuestion = null }) {
+export async function runFlow({ task, config, logger, flags = {}, emitter = null, askQuestion = null, pgTaskId = null, pgProject = null }) {
   const plannerRole = resolveRole(config, "planner");
   const coderRole = resolveRole(config, "coder");
   const reviewerRole = resolveRole(config, "reviewer");
@@ -136,7 +137,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   }
 
   const baseRef = await computeBaseRef({ baseBranch: config.base_branch, baseRef: flags.baseRef || null });
-  const session = await createSession({
+  const sessionInit = {
     task,
     config_snapshot: config,
     base_ref: baseRef,
@@ -149,7 +150,10 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     sonar_repeat_count: 0,
     last_reviewer_issue_signature: null,
     reviewer_repeat_count: 0
-  });
+  };
+  if (pgTaskId) sessionInit.pg_task_id = pgTaskId;
+  if (pgProject) sessionInit.pg_project_id = pgProject;
+  const session = await createSession(sessionInit);
 
   eventBase.sessionId = session.id;
 
@@ -179,6 +183,57 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     if (triageResult.roleOverrides.testerEnabled !== undefined) testerEnabled = triageResult.roleOverrides.testerEnabled;
     if (triageResult.roleOverrides.securityEnabled !== undefined) securityEnabled = triageResult.roleOverrides.securityEnabled;
     stageResults.triage = triageResult.stageResult;
+
+    // --- PG decomposition: offer to create subtasks in Planning Game ---
+    const pgDecompose = triageResult.stageResult?.shouldDecompose
+      && triageResult.stageResult.subtasks?.length > 1
+      && pgTaskId
+      && pgProject
+      && config.planning_game?.enabled !== false
+      && askQuestion;
+
+    if (pgDecompose) {
+      try {
+        const { buildDecompositionQuestion, createDecompositionSubtasks } = await import("./planning-game/decomposition.js");
+        const { createCard, relateCards, fetchCard } = await import("./planning-game/client.js");
+
+        const question = buildDecompositionQuestion(triageResult.stageResult.subtasks, pgTaskId);
+        const answer = await askQuestion(question);
+
+        if (answer && (answer.trim().toLowerCase() === "yes" || answer.trim().toLowerCase() === "sí" || answer.trim().toLowerCase() === "si")) {
+          const parentCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId }).catch(() => null);
+          const createdSubtasks = await createDecompositionSubtasks({
+            client: { createCard, relateCards },
+            projectId: pgProject,
+            parentCardId: pgTaskId,
+            parentFirebaseId: parentCard?.firebaseId || null,
+            subtasks: triageResult.stageResult.subtasks,
+            epic: parentCard?.epic || null,
+            sprint: parentCard?.sprint || null,
+            codeveloper: config.planning_game?.codeveloper || null
+          });
+
+          stageResults.triage.pgSubtasks = createdSubtasks;
+          logger.info(`Planning Game: created ${createdSubtasks.length} subtasks from decomposition`);
+
+          emitProgress(
+            emitter,
+            makeEvent("pg:decompose", { ...eventBase, stage: "triage" }, {
+              message: `Created ${createdSubtasks.length} subtasks in Planning Game`,
+              detail: { subtasks: createdSubtasks.map((s) => ({ cardId: s.cardId, title: s.title })) }
+            })
+          );
+
+          await addCheckpoint(session, {
+            stage: "pg-decompose",
+            subtasksCreated: createdSubtasks.length,
+            cardIds: createdSubtasks.map((s) => s.cardId)
+          });
+        }
+      } catch (err) {
+        logger.warn(`Planning Game decomposition failed: ${err.message}`);
+      }
+    }
   }
 
   if (flags.enablePlanner !== undefined) plannerEnabled = Boolean(flags.enablePlanner);
@@ -198,8 +253,9 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
 
   // --- Planner ---
   let plannedTask = task;
+  const triageDecomposition = stageResults.triage?.shouldDecompose ? stageResults.triage.subtasks : null;
   if (plannerEnabled) {
-    const plannerResult = await runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, trackBudget });
+    const plannerResult = await runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, triageDecomposition, trackBudget });
     plannedTask = plannerResult.plannedTask;
     stageResults.planner = plannerResult.stageResult;
   }
@@ -210,9 +266,65 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   const { rules: reviewRules } = await resolveReviewProfile({ mode: config.review_mode, projectDir });
   await coderRoleInstance.init();
 
+  const checkpointIntervalMs = (config.session.checkpoint_interval_minutes ?? 5) * 60 * 1000;
+  let lastCheckpointAt = Date.now();
+  let checkpointDisabled = false;
+
   for (let i = 1; i <= config.max_iterations; i += 1) {
     const elapsedMinutes = (Date.now() - startedAt) / 60000;
-    if (elapsedMinutes > config.session.max_total_minutes) {
+
+    // --- Interactive checkpoint: pause and ask every N minutes ---
+    if (!checkpointDisabled && askQuestion && (Date.now() - lastCheckpointAt) >= checkpointIntervalMs) {
+      const elapsedStr = elapsedMinutes.toFixed(1);
+      const iterInfo = `${i - 1}/${config.max_iterations} iterations completed`;
+      const budgetInfo = budgetTracker.total().cost_usd > 0 ? ` | Budget: $${budgetTracker.total().cost_usd.toFixed(2)}` : "";
+      const stagesCompleted = Object.keys(stageResults).join(", ") || "none";
+      const checkpointMsg = `Checkpoint — ${elapsedStr} min elapsed | ${iterInfo}${budgetInfo} | Stages completed: ${stagesCompleted}. What would you like to do?`;
+
+      emitProgress(
+        emitter,
+        makeEvent("session:checkpoint", { ...eventBase, iteration: i, stage: "checkpoint" }, {
+          message: `Interactive checkpoint at ${elapsedStr} min`,
+          detail: { elapsed_minutes: Number(elapsedStr), iterations_done: i - 1, stages: stagesCompleted }
+        })
+      );
+
+      const answer = await askQuestion(
+        `${checkpointMsg}\n\nOptions:\n1. Continue 5 more minutes\n2. Continue until done (no more checkpoints)\n3. Continue for N minutes (reply with the number)\n4. Stop now`
+      );
+
+      await addCheckpoint(session, { stage: "interactive-checkpoint", elapsed_minutes: Number(elapsedStr), answer });
+
+      if (!answer || answer.trim() === "4" || answer.trim().toLowerCase().startsWith("stop")) {
+        await markSessionStatus(session, "stopped");
+        emitProgress(
+          emitter,
+          makeEvent("session:end", { ...eventBase, iteration: i, stage: "user-stop" }, {
+            status: "stopped",
+            message: "Session stopped by user at checkpoint",
+            detail: { approved: false, reason: "user_stopped", elapsed_minutes: Number(elapsedStr), budget: budgetSummary() }
+          })
+        );
+        return { approved: false, sessionId: session.id, reason: "user_stopped", elapsed_minutes: Number(elapsedStr) };
+      }
+
+      if (answer.trim() === "2" || answer.trim().toLowerCase().startsWith("continue until")) {
+        checkpointDisabled = true;
+      } else if (answer.trim() === "1" || answer.trim().toLowerCase().includes("5 m")) {
+        lastCheckpointAt = Date.now();
+      } else {
+        const customMinutes = parseInt(answer.trim().replace(/\D/g, ""), 10);
+        if (customMinutes > 0) {
+          lastCheckpointAt = Date.now();
+          config.session.checkpoint_interval_minutes = customMinutes;
+        } else {
+          lastCheckpointAt = Date.now();
+        }
+      }
+    }
+
+    // --- Hard timeout: only when no askQuestion available ---
+    if (!askQuestion && elapsedMinutes > config.session.max_total_minutes) {
       await markSessionStatus(session, "failed");
       emitProgress(
         emitter,
@@ -366,7 +478,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
       }
 
       // --- All post-loop checks passed → finalize ---
-      const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session });
+      const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults });
       if (stageResults.planner?.ok) {
         stageResults.planner.completedSteps = [...(stageResults.planner.steps || [])];
       }

package/src/planning-game/client.js

@@ -89,3 +89,31 @@ export async function updateCard({ projectId, cardId, firebaseId, updates, timeo
   );
   return parseJsonResponse(response);
 }
+
+export async function createCard({ projectId, card, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards`;
+  const response = await fetchWithRetry(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(card)
+    },
+    timeoutMs
+  );
+  return parseJsonResponse(response);
+}
+
+export async function relateCards({ projectId, sourceCardId, targetCardId, relationType, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/relate`;
+  const response = await fetchWithRetry(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ sourceCardId, targetCardId, relationType })
+    },
+    timeoutMs
+  );
+  return parseJsonResponse(response);
+}

package/src/planning-game/decomposition.js

@@ -0,0 +1,83 @@
+/**
+ * Planning Game decomposition.
+ * Creates subtask cards in PG with blocks/blockedBy chain when triage
+ * recommends decomposition and user accepts.
+ */
+
+export async function createDecompositionSubtasks({
+  client,
+  projectId,
+  parentCardId,
+  parentFirebaseId,
+  subtasks,
+  epic,
+  sprint,
+  codeveloper
+}) {
+  if (!subtasks?.length || subtasks.length < 2) return [];
+
+  const created = [];
+
+  for (let i = 0; i < subtasks.length; i++) {
+    const card = {
+      type: "task",
+      title: subtasks[i],
+      descriptionStructured: [{
+        role: "developer",
+        goal: subtasks[i],
+        benefit: `Part ${i + 1}/${subtasks.length} of decomposed task ${parentCardId}`
+      }],
+      acceptanceCriteria: `Subtask ${i + 1} of ${parentCardId}: ${subtasks[i]}`
+    };
+
+    if (epic) card.epic = epic;
+    if (sprint) card.sprint = sprint;
+    if (codeveloper) card.codeveloper = codeveloper;
+
+    const result = await client.createCard({ projectId, card });
+    created.push({
+      cardId: result.cardId,
+      firebaseId: result.firebaseId,
+      title: subtasks[i],
+      index: i
+    });
+  }
+
+  // Chain blocks/blockedBy relationships: card[0] blocks card[1], card[1] blocks card[2], etc.
+  for (let i = 0; i < created.length - 1; i++) {
+    await client.relateCards({
+      projectId,
+      sourceCardId: created[i].cardId,
+      targetCardId: created[i + 1].cardId,
+      relationType: "blocks"
+    });
+  }
+
+  // Relate all subtasks to parent
+  for (const sub of created) {
+    await client.relateCards({
+      projectId,
+      sourceCardId: parentCardId,
+      targetCardId: sub.cardId,
+      relationType: "related"
+    });
+  }
+
+  return created;
+}
+
+export function buildDecompositionQuestion(subtasks, parentCardId) {
+  const lines = [
+    `Triage recommends decomposing this task into ${subtasks.length} subtasks:`,
+    ""
+  ];
+  for (let i = 0; i < subtasks.length; i++) {
+    lines.push(`${i + 1}. ${subtasks[i]}`);
+  }
+  lines.push("");
+  lines.push(`Create these as linked cards in Planning Game (parent: ${parentCardId})?`);
+  lines.push("Each subtask will block the next one (sequential chain).");
+  lines.push("");
+  lines.push("Reply: yes / no");
+  return lines.join("\n");
+}

package/src/roles/planner-role.js

@@ -9,7 +9,7 @@ function resolveProvider(config) {
   );
 }
 
-function buildPrompt({ task, instructions, research }) {
+function buildPrompt({ task, instructions, research, triageDecomposition }) {
   const sections = [];
 
   if (instructions) {
@@ -21,6 +21,17 @@ function buildPrompt({ task, instructions, research }) {
   sections.push("Return concise numbered steps focused on execution order and risk.");
   sections.push("");
 
+  if (triageDecomposition?.length) {
+    sections.push("## Triage decomposition recommendation");
+    sections.push("The triage stage determined this task should be decomposed. Suggested subtasks:");
+    for (let i = 0; i < triageDecomposition.length; i++) {
+      sections.push(`${i + 1}. ${triageDecomposition[i]}`);
+    }
+    sections.push("");
+    sections.push("Focus your plan on the FIRST subtask only. List the remaining subtasks as 'pending_subtasks' in your output for documentation.");
+    sections.push("");
+  }
+
   if (research) {
     sections.push("## Research findings");
     if (research.affected_files?.length) {
@@ -56,10 +67,11 @@ export class PlannerRole extends BaseRole {
   async execute(input) {
     const task = input || this.context?.task || "";
     const research = this.context?.research || null;
+    const triageDecomposition = this.context?.triageDecomposition || null;
     const provider = resolveProvider(this.config);
 
     const agent = this._createAgent(provider, this.config, this.logger);
-    const prompt = buildPrompt({ task, instructions: this.instructions, research });
+    const prompt = buildPrompt({ task, instructions: this.instructions, research, triageDecomposition });
 
     const result = await agent.runTask({ prompt, role: "planner" });
 

package/src/roles/triage-role.js

@@ -26,10 +26,10 @@ function buildPrompt({ task, instructions }) {
   }
 
   sections.push(
-    "Classify the task complexity and recommend only the necessary pipeline roles.",
+    "Classify the task complexity, recommend only the necessary pipeline roles, and assess whether the task should be decomposed into smaller subtasks.",
     "Keep the reasoning short and practical.",
     "Return a single valid JSON object and nothing else.",
-    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security"],"reasoning":string}'
+    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security"],"reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}'
   );
 
   sections.push(`## Task\n${task}`);
@@ -49,6 +49,14 @@ function normalizeRoles(roles) {
   return Array.from(new Set(roles.filter((role) => VALID_ROLES.has(role))));
 }
 
+function normalizeSubtasks(subtasks) {
+  if (!Array.isArray(subtasks)) return [];
+  return subtasks
+    .map((s) => (typeof s === "string" ? s.trim() : ""))
+    .filter(Boolean)
+    .slice(0, 5);
+}
+
 export class TriageRole extends BaseRole {
   constructor({ config, logger, emitter = null, createAgentFn = null }) {
     super({ name: "triage", config, logger, emitter });
@@ -98,16 +106,28 @@ export class TriageRole extends BaseRole {
       const level = VALID_LEVELS.has(parsed.level) ? parsed.level : "medium";
       const roles = normalizeRoles(parsed.roles);
       const reasoning = String(parsed.reasoning || "").trim() || "No reasoning provided.";
+      const shouldDecompose = Boolean(parsed.shouldDecompose);
+      const subtasks = normalizeSubtasks(parsed.subtasks);
+
+      const triageResult = {
+        level,
+        roles,
+        reasoning,
+        provider
+      };
+
+      if (shouldDecompose && subtasks.length > 0) {
+        triageResult.shouldDecompose = true;
+        triageResult.subtasks = subtasks;
+      } else {
+        triageResult.shouldDecompose = false;
+      }
 
+      const decomposeNote = shouldDecompose ? " — decomposition recommended" : "";
       return {
         ok: true,
-        result: {
-          level,
-          roles,
-          reasoning,
-          provider
-        },
-        summary: `Triage: ${level} (${roles.length} role${roles.length === 1 ? "" : "s"})`,
+        result: triageResult,
+        summary: `Triage: ${level} (${roles.length} role${roles.length === 1 ? "" : "s"})${decomposeNote}`,
         usage: result.usage
       };
     } catch {

package/src/utils/process.js

@@ -7,6 +7,20 @@ export async function runCommand(command, args = [], options = {}) {
     ...rest
   });
 
+  let stdoutAccum = "";
+  let stderrAccum = "";
+
+  if (subprocess.stdout) {
+    subprocess.stdout.on("data", (chunk) => {
+      stdoutAccum += chunk.toString();
+    });
+  }
+  if (subprocess.stderr) {
+    subprocess.stderr.on("data", (chunk) => {
+      stderrAccum += chunk.toString();
+    });
+  }
+
   if (onOutput) {
     const handler = (stream) => {
       let partial = "";
@@ -25,7 +39,8 @@ export async function runCommand(command, args = [], options = {}) {
 
   try {
     if (!timeout) {
-      return await subprocess;
+      const result = await subprocess;
+      return enrichResult(result, stdoutAccum, stderrAccum);
     }
 
     let timer = null;
@@ -38,15 +53,17 @@ export async function runCommand(command, args = [], options = {}) {
         }
         resolve({
           exitCode: 143,
-          stdout: "",
-          stderr: `Command timed out after ${timeout}ms`
+          stdout: stdoutAccum,
+          stderr: `Command timed out after ${timeout}ms`,
+          timedOut: true,
+          signal: "SIGKILL"
         });
       }, timeout);
     });
 
     const result = await Promise.race([subprocess, timeoutResult]);
     if (timer) clearTimeout(timer);
-    return result;
+    return enrichResult(result, stdoutAccum, stderrAccum);
   } catch (error) {
     const details = [
       error?.shortMessage,
@@ -60,8 +77,29 @@ export async function runCommand(command, args = [], options = {}) {
 
     return {
       exitCode: 1,
-      stdout: error?.stdout || "",
-      stderr: details || String(error)
+      stdout: error?.stdout || stdoutAccum,
+      stderr: details || String(error),
+      signal: error?.signal || null
+    };
+  }
+}
+
+function enrichResult(result, stdoutAccum, stderrAccum) {
+  if (result.timedOut) return result;
+
+  const killed = result.killed || !!result.signal;
+  const signal = result.signal || null;
+
+  if (killed && !result.stderr) {
+    return {
+      ...result,
+      stdout: result.stdout || stdoutAccum,
+      stderr: signal
+        ? `Process killed by signal ${signal}`
+        : "Process was killed externally",
+      signal
     };
   }
+
+  return result;
 }

package/templates/roles/triage.md

@@ -1,6 +1,6 @@
 You are the **Triage** role in a multi-role AI pipeline.
 
-Your job is to quickly classify task complexity and activate only the necessary roles.
+Your job is to quickly classify task complexity, activate only the necessary roles, and assess whether the task should be decomposed into smaller subtasks before execution.
 
 ## Output format
 Return a single valid JSON object and nothing else:
@@ -9,7 +9,9 @@ Return a single valid JSON object and nothing else:
 {
   "level": "trivial|simple|medium|complex",
   "roles": ["planner", "researcher", "refactorer", "reviewer", "tester", "security"],
-  "reasoning": "brief practical justification"
+  "reasoning": "brief practical justification",
+  "shouldDecompose": false,
+  "subtasks": []
 }
 ```
 
@@ -19,7 +21,20 @@ Return a single valid JSON object and nothing else:
 - `medium`: moderate scope/risk. Reviewer required; optional planner/researcher.
 - `complex`: high scope/risk, architecture or security/testing impact. Full pipeline.
 
+## Decomposition guidance
+Analyze whether the task is too large for a single agent iteration. Set `shouldDecompose: true` when ANY of these apply:
+- The task touches more than 3 unrelated areas of the codebase.
+- It requires both architectural changes AND feature implementation.
+- It combines multiple independent features or fixes in one request.
+- It would likely require more than ~200 lines of changes across many files.
+- It mixes refactoring with new functionality.
+
+When `shouldDecompose` is true, provide `subtasks`: an array of 2-5 short strings, each describing one focused, independently deliverable piece of work. Order them by dependency (do first → do last).
+
+When `shouldDecompose` is false, `subtasks` must be an empty array.
+
 ## Rules
 - Keep `reasoning` short.
 - Recommend only roles that add clear value.
 - Do not include `coder` or `sonar` in `roles` (they are always active).
+- Subtask descriptions should be actionable and specific, not vague.