karajan-code 1.34.2 → 1.34.4

package/README.md

@@ -116,7 +116,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 | **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
 | **Codex** | `codex` | `npm install -g @openai/codex` |
 | **Gemini** | `gemini` | See [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
-| **Aider** | `aider` | `pip install aider-chat` |
+| **Aider** | `aider` | `pipx install aider-chat` (or `pip3 install aider-chat`) |
 | **OpenCode** | `opencode` | See [OpenCode docs](https://github.com/nicepkg/opencode) |
 
 Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects installed agents during `kj init`.

package/docs/README.es.md

@@ -124,7 +124,7 @@ Guias completas: [`docs/multi-instance.md`](multi-instance.md) | [`docs/install-
 | **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
 | **Codex** | `codex` | `npm install -g @openai/codex` |
 | **Gemini** | `gemini` | Ver [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
-| **Aider** | `aider` | `pip install aider-chat` |
+| **Aider** | `aider` | `pipx install aider-chat` (o `pip3 install aider-chat`) |
 
 `kj init` auto-detecta los agentes instalados. Si solo hay uno disponible, se asigna a todos los roles automaticamente.
 

package/package.json

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

package/src/commands/doctor.js

@@ -8,6 +8,7 @@ import { isSonarReachable } from "../sonar/manager.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { ensureGitRepo } from "../utils/git.js";
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
+import { getInstallCommand } from "../utils/os-detect.js";
 
 function getPackageVersion() {
   const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
@@ -162,23 +163,23 @@ async function checkBecariaSecrets() {
     const { detectRepo } = await import("../becaria/repo.js");
     const repo = await detectRepo();
     if (!repo) return null;
+
     const secretsRes = await runCommand("gh", ["api", `repos/${repo}/actions/secrets`, "--jq", ".secrets[].name"]);
     if (secretsRes.exitCode !== 0) return null;
+
     const names = new Set(secretsRes.stdout.split("\n").map((s) => s.trim()));
     const hasAppId = names.has("BECARIA_APP_ID");
     const hasKey = names.has("BECARIA_APP_PRIVATE_KEY");
     const secretsOk = hasAppId && hasKey;
+    const missing = [!hasAppId && "BECARIA_APP_ID", !hasKey && "BECARIA_APP_PRIVATE_KEY"].filter(Boolean).join(" ");
     return {
       name: "becaria:secrets",
       label: "BecarIA: GitHub secrets",
       ok: secretsOk,
-      detail: secretsOk
-        ? "BECARIA_APP_ID + BECARIA_APP_PRIVATE_KEY found"
-        : `Missing: ${[!hasAppId && "BECARIA_APP_ID", !hasKey && "BECARIA_APP_PRIVATE_KEY"].filter(Boolean).join(" ")}`,
+      detail: secretsOk ? "BECARIA_APP_ID + BECARIA_APP_PRIVATE_KEY found" : `Missing: ${missing}`,
       fix: secretsOk ? null : "Add BECARIA_APP_ID and BECARIA_APP_PRIVATE_KEY as GitHub repository secrets"
     };
   } catch {
-    // Skip secrets check if we can't access the API
     return null;
   }
 }
@@ -205,33 +206,15 @@ async function checkBecariaInfra(config) {
 }
 
 async function checkRtk() {
+  const NOT_FOUND_DETAIL = `Not found — install for 60-90% token savings: ${getInstallCommand("rtk")}`;
+  let detail = NOT_FOUND_DETAIL;
   try {
     const res = await runCommand("rtk", ["--version"]);
     if (res.exitCode === 0) {
-      return {
-        name: "rtk",
-        label: "RTK (Rust Token Killer)",
-        ok: true,
-        detail: `${res.stdout.trim()} — token savings active`,
-        fix: null
-      };
+      detail = `${res.stdout.trim()} — token savings active`;
     }
-    return {
-      name: "rtk",
-      label: "RTK (Rust Token Killer)",
-      ok: true,
-      detail: "Not found — install for 60-90% token savings: brew install rtk",
-      fix: null
-    };
-  } catch {
-    return {
-      name: "rtk",
-      label: "RTK (Rust Token Killer)",
-      ok: true,
-      detail: "Not found — install for 60-90% token savings: brew install rtk",
-      fix: null
-    };
-  }
+  } catch { /* not installed */ }
+  return { name: "rtk", label: "RTK (Rust Token Killer)", ok: true, detail, fix: null };
 }
 
 async function checkRuleFiles(config) {

package/src/commands/init.js

@@ -8,6 +8,7 @@ import { getKarajanHome } from "../utils/paths.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
 import { createWizard, isTTY } from "../utils/wizard.js";
 import { runCommand } from "../utils/process.js";
+import { getInstallCommand } from "../utils/os-detect.js";
 
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
@@ -292,7 +293,7 @@ export async function initCommand({ logger, flags = {} }) {
   if (!hasRtk) {
     logger.info("");
     logger.info("RTK (Rust Token Killer) can reduce token usage by 60-90%.");
-    logger.info("  Install: brew install rtk && rtk init --global");
+    logger.info(`  Install: ${getInstallCommand("rtk")}`);
   }
 
   await setupSonarQube(config, logger);

package/src/commands/report.js

@@ -155,50 +155,49 @@ async function buildReport(dir, sessionId) {
   return report;
 }
 
-function printTextReport(report) {
-  let budgetText = "N/A";
-  if (typeof report.budget_consumed?.consumed_usd === "number") {
-    const limitSuffix = typeof report.budget_consumed?.limit_usd === "number"
-      ? ` / $${report.budget_consumed.limit_usd.toFixed(2)}`
-      : "";
-    budgetText = `$${report.budget_consumed.consumed_usd.toFixed(2)}${limitSuffix}`;
-  }
+function formatBudgetText(budget) {
+  if (typeof budget?.consumed_usd !== "number") return "N/A";
+  const limitSuffix = typeof budget.limit_usd === "number" ? ` / $${budget.limit_usd.toFixed(2)}` : "";
+  return `$${budget.consumed_usd.toFixed(2)}${limitSuffix}`;
+}
 
-  const planText = report.plan_executed.length > 0 ? report.plan_executed.join(" -> ") : "N/A";
-  const iterationText =
-    report.iterations.length > 0
-      ? report.iterations
-          .map(
-            (item) =>
-              `#${item.iteration} coder=${item.coder_runs} reviewer_attempts=${item.reviewer_attempts} approved=${item.reviewer_approved}`
-          )
-          .join("\n")
-      : "N/A";
-  const commitsText =
-    report.commits_generated.ids.length > 0
-      ? `${report.commits_generated.count} (${report.commits_generated.ids.join(", ")})`
-      : String(report.commits_generated.count);
+function formatIterationsText(iterations) {
+  if (iterations.length === 0) return "N/A";
+  return iterations
+    .map((item) => `#${item.iteration} coder=${item.coder_runs} reviewer_attempts=${item.reviewer_attempts} approved=${item.reviewer_approved}`)
+    .join("\n");
+}
+
+function formatCommitsText(commits) {
+  return commits.ids.length > 0
+    ? `${commits.count} (${commits.ids.join(", ")})`
+    : String(commits.count);
+}
+
+function printPgCardLine(report) {
+  if (!report.pg_task_id) return;
+  const projectLabel = report.pg_project_id ? ` (${report.pg_project_id})` : "";
+  console.log(`Planning Game Card: ${report.pg_task_id}${projectLabel}`);
+}
+
+function printTextReport(report) {
+  const sonar = report.sonar_issues_resolved;
 
   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}`);
-  }
+  printPgCardLine(report);
   console.log(`Status: ${report.status}`);
   console.log("Task Description:");
   console.log(report.task_description || "N/A");
   console.log("Plan Executed:");
-  console.log(planText);
+  console.log(report.plan_executed.length > 0 ? report.plan_executed.join(" -> ") : "N/A");
   console.log("Iterations (Coder/Reviewer):");
-  console.log(iterationText);
+  console.log(formatIterationsText(report.iterations));
   console.log("Sonar Issues Resolved:");
-  console.log(
-    `initial=${report.sonar_issues_resolved.initial_open_issues ?? "N/A"} final=${report.sonar_issues_resolved.final_open_issues ?? "N/A"} resolved=${report.sonar_issues_resolved.resolved}`
-  );
+  console.log(`initial=${sonar.initial_open_issues ?? "N/A"} final=${sonar.final_open_issues ?? "N/A"} resolved=${sonar.resolved}`);
   console.log("Budget Consumed:");
-  console.log(budgetText);
+  console.log(formatBudgetText(report.budget_consumed));
   console.log("Commits Generated:");
-  console.log(commitsText);
+  console.log(formatCommitsText(report.commits_generated));
 }
 
 function formatDuration(ms) {
@@ -329,10 +328,7 @@ async function resolveTraceOptions(currency) {
 
 function printTraceReport(report, currency, exchangeRate) {
   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}`);
-  }
+  printPgCardLine(report);
   console.log(`Status: ${report.status}`);
   console.log(`Task: ${report.task_description || "N/A"}`);
   console.log("");

package/src/config.js

@@ -453,27 +453,39 @@ export function isModelCompatible(agent, model) {
   return true;
 }
 
+// Roles that inherit provider/model from the coder when not explicitly configured
+const CODER_INHERITED_ROLES = new Set([
+  "planner", "refactorer", "solomon", "researcher", "tester", "security",
+  "impeccable", "triage", "discover", "architect", "audit", "hu_reviewer", "hu-reviewer"
+]);
+
+function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {
+  if (roleConfig.provider) return roleConfig.provider;
+  if (role === "coder") return legacyCoder;
+  if (role === "reviewer") return legacyReviewer;
+  if (CODER_INHERITED_ROLES.has(role)) return roles.coder?.provider || legacyCoder;
+  return null;
+}
+
+function resolveModel(roleConfig, role, config) {
+  if (roleConfig.model) return { model: roleConfig.model, inherited: false };
+  if (role === "coder") return { model: config?.coder_options?.model ?? null, inherited: false };
+  if (role === "reviewer") return { model: config?.reviewer_options?.model ?? null, inherited: false };
+  if (CODER_INHERITED_ROLES.has(role)) {
+    const model = config?.coder_options?.model ?? null;
+    return { model, inherited: !!model };
+  }
+  return { model: null, inherited: false };
+}
+
 export function resolveRole(config, role) {
   const roles = config?.roles || {};
   const roleConfig = roles[role] || {};
   const legacyCoder = config?.coder || null;
   const legacyReviewer = config?.reviewer || null;
 
-  let provider = roleConfig.provider ?? null;
-  if (!provider && role === "coder") provider = legacyCoder;
-  if (!provider && role === "reviewer") provider = legacyReviewer;
-  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect" || role === "audit" || role === "hu_reviewer" || role === "hu-reviewer")) {
-    provider = roles.coder?.provider || legacyCoder;
-  }
-
-  let model = roleConfig.model ?? null;
-  let modelIsInherited = false;
-  if (!model && role === "coder") model = config?.coder_options?.model ?? null;
-  if (!model && role === "reviewer") model = config?.reviewer_options?.model ?? null;
-  if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect" || role === "hu_reviewer" || role === "hu-reviewer")) {
-    model = config?.coder_options?.model ?? null;
-    modelIsInherited = !!model;
-  }
+  const provider = resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer);
+  let { model, inherited: modelIsInherited } = resolveModel(roleConfig, role, config);
 
   // Drop inherited model if incompatible with the resolved provider
   if (modelIsInherited && provider && model && !isModelCompatible(provider, model)) {

package/src/mcp/server-handlers.js

@@ -252,6 +252,31 @@ async function attemptAutoResume({ err, config, logger, emitter, askQuestion, ru
   }
 }
 
+const PIPELINE_PROVIDER_ROLES = [
+  ["triage", true],
+  ["planner", true],
+  ["refactorer", true],
+  ["researcher", true],
+  ["tester", true],
+  ["security", true]
+];
+
+function collectRequiredProviders(config) {
+  const providers = [
+    resolveRole(config, "coder").provider,
+    config.reviewer_options?.fallback_reviewer
+  ];
+  if (config.pipeline?.reviewer?.enabled !== false) {
+    providers.push(resolveRole(config, "reviewer").provider);
+  }
+  for (const [role, requireEnabled] of PIPELINE_PROVIDER_ROLES) {
+    if (requireEnabled && config.pipeline?.[role]?.enabled) {
+      providers.push(resolveRole(config, role).provider);
+    }
+  }
+  return providers;
+}
+
 export async function handleRunDirect(a, server, extra) {
   const config = await buildConfig(a);
   await assertNotOnBaseBranch(config);
@@ -263,20 +288,7 @@ export async function handleRunDirect(a, server, extra) {
     await cleanupExpiredSessions({ logger });
   } catch { /* non-blocking */ }
 
-  const requiredProviders = [
-    resolveRole(config, "coder").provider,
-    config.reviewer_options?.fallback_reviewer
-  ];
-  if (config.pipeline?.reviewer?.enabled !== false) {
-    requiredProviders.push(resolveRole(config, "reviewer").provider);
-  }
-  if (config.pipeline?.triage?.enabled) requiredProviders.push(resolveRole(config, "triage").provider);
-  if (config.pipeline?.planner?.enabled) requiredProviders.push(resolveRole(config, "planner").provider);
-  if (config.pipeline?.refactorer?.enabled) requiredProviders.push(resolveRole(config, "refactorer").provider);
-  if (config.pipeline?.researcher?.enabled) requiredProviders.push(resolveRole(config, "researcher").provider);
-  if (config.pipeline?.tester?.enabled) requiredProviders.push(resolveRole(config, "tester").provider);
-  if (config.pipeline?.security?.enabled) requiredProviders.push(resolveRole(config, "security").provider);
-  await assertAgentsAvailable(requiredProviders);
+  await assertAgentsAvailable(collectRequiredProviders(config));
 
   const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
@@ -343,13 +355,16 @@ export async function handleResumeDirect(a, server, extra) {
   }
 }
 
+const EVENT_LOG_LEVELS = {
+  "agent:stall": "warning",
+  "agent:heartbeat": "info"
+};
+
 function buildDirectEmitter(server, runLog, extra) {
   const emitter = new EventEmitter();
   emitter.on("progress", (event) => {
     try {
-      let level = "debug";
-      if (event.type === "agent:stall") level = "warning";
-      else if (event.type === "agent:heartbeat") level = "info";
+      const level = EVENT_LOG_LEVELS[event.type] || "debug";
       server.sendLoggingMessage({ level, logger: "karajan", data: event });
     } catch { /* best-effort */ }
     if (runLog) runLog.logEvent(event);

package/src/orchestrator.js

@@ -476,7 +476,7 @@ async function checkBudgetExceeded({ budgetTracker, config, session, emitter, ev
 }
 
 async function handleStandbyResult({ stageResult, session, emitter, eventBase, i, stage, logger }) {
-  if (!stageResult?.action || stageResult.action !== "standby") {
+  if (stageResult?.action !== "standby") {
     return { handled: false };
   }
 
@@ -511,6 +511,47 @@ async function handleStandbyResult({ stageResult, session, emitter, eventBase, i
   return { handled: true, action: "retry" };
 }
 
+function formatCommitList(commits) {
+  return commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
+}
+
+async function becariaIncrementalPush({ config, session, gitCtx, task, logger, repo, dispatchComment }) {
+  const pushResult = await incrementalPush({ gitCtx, task, logger, session });
+  if (!pushResult) return;
+
+  session.becaria_commits = [...(session.becaria_commits ?? []), ...pushResult.commits];
+  await saveSession(session);
+
+  if (!repo) return;
+  const feedback = session.last_reviewer_feedback || "N/A";
+  await dispatchComment({
+    repo, prNumber: session.becaria_pr_number, agent: "Coder",
+    body: `Issues corregidos:\n${feedback}\n\nCommits:\n${formatCommitList(pushResult.commits)}`,
+    becariaConfig: config.becaria
+  });
+}
+
+async function becariaCreateEarlyPr({ config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i, repo, dispatchComment }) {
+  const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
+  if (!earlyPr) return;
+
+  session.becaria_pr_number = earlyPr.prNumber;
+  session.becaria_pr_url = earlyPr.prUrl;
+  session.becaria_commits = earlyPr.commits;
+  await saveSession(session);
+  emitProgress(emitter, makeEvent("becaria:pr-created", { ...eventBase, stage: "becaria" }, {
+    message: `Early PR created: #${earlyPr.prNumber}`,
+    detail: { prNumber: earlyPr.prNumber, prUrl: earlyPr.prUrl }
+  }));
+
+  if (!repo) return;
+  await dispatchComment({
+    repo, prNumber: earlyPr.prNumber, agent: "Coder",
+    body: `Iteración ${i} completada.\n\nCommits:\n${formatCommitList(earlyPr.commits)}`,
+    becariaConfig: config.becaria
+  });
+}
+
 async function handleBecariaEarlyPrOrPush({ becariaEnabled, config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i }) {
   if (!becariaEnabled) return;
 
@@ -520,48 +561,26 @@ async function handleBecariaEarlyPrOrPush({ becariaEnabled, config, session, emi
     const repo = await detectRepo();
 
     if (session.becaria_pr_number) {
-      const pushResult = await incrementalPush({ gitCtx, task, logger, session });
-      if (pushResult) {
-        session.becaria_commits = [...(session.becaria_commits ?? []), ...pushResult.commits];
-        await saveSession(session);
-
-        if (repo) {
-          const feedback = session.last_reviewer_feedback || "N/A";
-          const commitList = pushResult.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
-          await dispatchComment({
-            repo, prNumber: session.becaria_pr_number, agent: "Coder",
-            body: `Issues corregidos:\n${feedback}\n\nCommits:\n${commitList}`,
-            becariaConfig: config.becaria
-          });
-        }
-      }
+      await becariaIncrementalPush({ config, session, gitCtx, task, logger, repo, dispatchComment });
     } else {
-      const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
-      if (earlyPr) {
-        session.becaria_pr_number = earlyPr.prNumber;
-        session.becaria_pr_url = earlyPr.prUrl;
-        session.becaria_commits = earlyPr.commits;
-        await saveSession(session);
-        emitProgress(emitter, makeEvent("becaria:pr-created", { ...eventBase, stage: "becaria" }, {
-          message: `Early PR created: #${earlyPr.prNumber}`,
-          detail: { prNumber: earlyPr.prNumber, prUrl: earlyPr.prUrl }
-        }));
-
-        if (repo) {
-          const commitList = earlyPr.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
-          await dispatchComment({
-            repo, prNumber: earlyPr.prNumber, agent: "Coder",
-            body: `Iteración ${i} completada.\n\nCommits:\n${commitList}`,
-            becariaConfig: config.becaria
-          });
-        }
-      }
+      await becariaCreateEarlyPr({ config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i, repo, dispatchComment });
     }
   } catch (err) {
     logger.warn(`BecarIA early PR/push failed (non-blocking): ${err.message}`);
   }
 }
 
+function emitSolomonAlerts(alerts, emitter, eventBase, logger) {
+  for (const alert of alerts) {
+    emitProgress(emitter, makeEvent("solomon:alert", { ...eventBase, stage: "solomon" }, {
+      status: alert.severity === "critical" ? "fail" : "warn",
+      message: alert.message,
+      detail: alert.detail
+    }));
+    logger.warn(`Solomon alert [${alert.rule}]: ${alert.message}`);
+  }
+}
+
 async function handleSolomonCheck({ config, session, emitter, eventBase, logger, task, i, askQuestion, becariaEnabled, blockingIssues }) {
   if (config.pipeline?.solomon?.enabled === false) return { action: "continue" };
 
@@ -571,15 +590,7 @@ async function handleSolomonCheck({ config, session, emitter, eventBase, logger,
     const rulesResult = evaluateRules(rulesContext, config.solomon?.rules);
 
     if (rulesResult.alerts.length > 0) {
-      for (const alert of rulesResult.alerts) {
-        emitProgress(emitter, makeEvent("solomon:alert", { ...eventBase, stage: "solomon" }, {
-          status: alert.severity === "critical" ? "fail" : "warn",
-          message: alert.message,
-          detail: alert.detail
-        }));
-        logger.warn(`Solomon alert [${alert.rule}]: ${alert.message}`);
-      }
-
+      emitSolomonAlerts(rulesResult.alerts, emitter, eventBase, logger);
       const pauseResult = await checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i });
       if (pauseResult) return pauseResult;
     }
@@ -623,6 +634,27 @@ async function checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i
   return null;
 }
 
+function formatBlockingIssues(issues) {
+  return issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
+}
+
+function formatSuggestions(suggestions) {
+  return suggestions?.map((s) => {
+    const detail = typeof s === "string" ? s : `${s.id || ""} ${s.description || s}`;
+    return `- ${detail}`;
+  }).join("\n") || "";
+}
+
+function buildReviewCommentBody(review, i) {
+  const status = review.approved ? "APPROVED" : "REQUEST_CHANGES";
+  const blocking = formatBlockingIssues(review.blocking_issues);
+  const suggestions = formatSuggestions(review.non_blocking_suggestions);
+  let body = `Review iteración ${i}: ${status}`;
+  if (blocking) body += `\n\n**Blocking:**\n${blocking}`;
+  if (suggestions) body += `\n\n**Suggestions:**\n${suggestions}`;
+  return body;
+}
+
 async function handleBecariaReviewDispatch({ becariaEnabled, config, session, review, i, logger }) {
   if (!becariaEnabled || !session.becaria_pr_number) return;
 
@@ -633,33 +665,19 @@ async function handleBecariaReviewDispatch({ becariaEnabled, config, session, re
     if (!repo) return;
 
     const bc = config.becaria;
-    if (review.approved) {
-      await dispatchReview({
-        repo, prNumber: session.becaria_pr_number,
-        event: "APPROVE", body: review.summary || "Approved", agent: "Reviewer", becariaConfig: bc
-      });
-    } else {
-      const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
-      await dispatchReview({
-        repo, prNumber: session.becaria_pr_number,
-        event: "REQUEST_CHANGES",
-        body: blocking || review.summary || "Changes requested",
-        agent: "Reviewer", becariaConfig: bc
-      });
-    }
+    const reviewEvent = review.approved ? "APPROVE" : "REQUEST_CHANGES";
+    const reviewBody = review.approved
+      ? (review.summary || "Approved")
+      : (formatBlockingIssues(review.blocking_issues) || review.summary || "Changes requested");
+
+    await dispatchReview({
+      repo, prNumber: session.becaria_pr_number,
+      event: reviewEvent, body: reviewBody, agent: "Reviewer", becariaConfig: bc
+    });
 
-    const status = review.approved ? "APPROVED" : "REQUEST_CHANGES";
-    const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
-    const suggestions = review.non_blocking_suggestions?.map((s) => {
-      const detail = typeof s === "string" ? s : `${s.id || ""} ${s.description || s}`;
-      return `- ${detail}`;
-    }).join("\n") || "";
-    let reviewBody = `Review iteración ${i}: ${status}`;
-    if (blocking) reviewBody += `\n\n**Blocking:**\n${blocking}`;
-    if (suggestions) reviewBody += `\n\n**Suggestions:**\n${suggestions}`;
     await dispatchComment({
       repo, prNumber: session.becaria_pr_number, agent: "Reviewer",
-      body: reviewBody, becariaConfig: bc
+      body: buildReviewCommentBody(review, i), becariaConfig: bc
     });
 
     logger.info(`BecarIA: dispatched review for PR #${session.becaria_pr_number}`);
@@ -1095,6 +1113,24 @@ async function handleMaxIterationsReached({ session, budgetSummary, emitter, eve
   return { approved: false, sessionId: session.id, reason: "max_iterations" };
 }
 
+async function tryAutoStartBoard(config, logger, emitter, eventBase) {
+  if (!config.hu_board?.enabled || !config.hu_board?.auto_start) return;
+
+  try {
+    const { startBoard } = await import("./commands/board.js");
+    const boardPort = config.hu_board.port || 4000;
+    const boardResult = await startBoard(boardPort);
+    const status = boardResult.alreadyRunning ? "already running" : "started";
+    logger.info(`HU Board ${status} at ${boardResult.url}`);
+    emitProgress(emitter, makeEvent("board:started", eventBase, {
+      message: `HU Board running at ${boardResult.url}`,
+      detail: { pid: boardResult.pid, port: boardPort }
+    }));
+  } catch (err) {
+    logger.warn(`HU Board auto-start failed (non-blocking): ${err.message}`);
+  }
+}
+
 async function initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags }) {
   const ctx = new PipelineContext({ config, session: null, logger, emitter, task, flags });
   ctx.askQuestion = askQuestion;
@@ -1127,24 +1163,7 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
   }
 
   // --- HU Board auto-start ---
-  if (config.hu_board?.enabled && config.hu_board?.auto_start) {
-    try {
-      const { startBoard } = await import("./commands/board.js");
-      const boardPort = config.hu_board.port || 4000;
-      const boardResult = await startBoard(boardPort);
-      if (boardResult.alreadyRunning) {
-        logger.info(`HU Board already running at ${boardResult.url}`);
-      } else {
-        logger.info(`HU Board started at ${boardResult.url}`);
-      }
-      emitProgress(emitter, makeEvent("board:started", ctx.eventBase, {
-        message: `HU Board running at ${boardResult.url}`,
-        detail: { pid: boardResult.pid, port: boardPort }
-      }));
-    } catch (err) {
-      logger.warn(`HU Board auto-start failed (non-blocking): ${err.message}`);
-    }
-  }
+  await tryAutoStartBoard(config, logger, emitter, ctx.eventBase);
 
   // --- Product Context ---
   const ctxProjectDir = config.projectDir || process.cwd();

package/src/utils/agent-detect.js

@@ -1,12 +1,13 @@
 import { runCommand } from "./process.js";
 import { resolveBin } from "../agents/resolve-bin.js";
+import { getInstallCommand } from "./os-detect.js";
 
 const KNOWN_AGENTS = [
-  { name: "claude", install: "npm install -g @anthropic-ai/claude-code" },
-  { name: "codex", install: "npm install -g @openai/codex" },
-  { name: "gemini", install: "npm install -g @google/gemini-cli (or check https://geminicli.com/docs/get-started/installation/)" },
-  { name: "aider", install: "pip install aider-chat" },
-  { name: "opencode", install: "curl -fsSL https://opencode.ai/install | bash (or see https://opencode.ai)" }
+  { name: "claude", install: getInstallCommand("claude") },
+  { name: "codex", install: getInstallCommand("codex") },
+  { name: "gemini", install: getInstallCommand("gemini") },
+  { name: "aider", install: getInstallCommand("aider") },
+  { name: "opencode", install: getInstallCommand("opencode") }
 ];
 
 export async function checkBinary(name, versionArg = "--version") {

package/src/utils/display.js

@@ -219,9 +219,14 @@ function printSessionGit(git) {
   }
 }
 
+function isBudgetUnavailable(budget) {
+  return budget.usage_available === false ||
+    (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0);
+}
+
 function printSessionBudget(budget) {
   if (!budget) return;
-  if (budget.usage_available === false || (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0)) {
+  if (isBudgetUnavailable(budget)) {
     console.log(`  ${ANSI.dim}\ud83d\udcb0 Budget: N/A (provider does not report usage)${ANSI.reset}`);
     return;
   }
@@ -381,12 +386,13 @@ const EVENT_HANDLERS = {
   },
 
   "budget:update": (event, icon) => {
-    const total = Number(event.detail?.total_cost_usd || 0);
-    const totalTokens = Number(event.detail?.total_tokens || 0);
-    const max = Number(event.detail?.max_budget_usd);
-    const pct = Number(event.detail?.pct_used ?? 0);
-    const warn = Number(event.detail?.warn_threshold_pct ?? 80);
-    const hasEntries = (event.detail?.entries?.length ?? 0) > 0 || Object.keys(event.detail?.breakdown_by_role || {}).length > 0;
+    const d = event.detail || {};
+    const total = Number(d.total_cost_usd || 0);
+    const totalTokens = Number(d.total_tokens || 0);
+    const max = Number(d.max_budget_usd);
+    const pct = Number(d.pct_used ?? 0);
+    const warn = Number(d.warn_threshold_pct ?? 80);
+    const hasEntries = (d.entries?.length ?? 0) > 0 || Object.keys(d.breakdown_by_role || {}).length > 0;
     if (hasEntries && totalTokens === 0 && total === 0) {
       console.log(`  \u251c\u2500 ${icon} Budget: ${ANSI.dim}N/A (provider does not report usage)${ANSI.reset}`);
       return;

package/src/utils/os-detect.js

@@ -0,0 +1,45 @@
+import os from "node:os";
+
+/**
+ * Detect platform and return OS-appropriate install commands.
+ */
+export function getPlatform() {
+  const platform = os.platform();
+  return platform === "darwin" ? "macos" : "linux";
+}
+
+const INSTALL_COMMANDS = {
+  rtk: {
+    macos: "brew install rtk && rtk init --global",
+    linux: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh && rtk init --global"
+  },
+  claude: {
+    macos: "npm install -g @anthropic-ai/claude-code",
+    linux: "npm install -g @anthropic-ai/claude-code"
+  },
+  codex: {
+    macos: "npm install -g @openai/codex",
+    linux: "npm install -g @openai/codex"
+  },
+  gemini: {
+    macos: "npm install -g @google/gemini-cli",
+    linux: "npm install -g @google/gemini-cli"
+  },
+  aider: {
+    macos: "pipx install aider-chat",
+    linux: "pipx install aider-chat || pip3 install aider-chat"
+  },
+  opencode: {
+    macos: "curl -fsSL https://opencode.ai/install | bash",
+    linux: "curl -fsSL https://opencode.ai/install | bash"
+  },
+  docker: {
+    macos: "brew install --cask docker",
+    linux: "sudo apt install docker.io docker-compose-v2 (or see https://docs.docker.com/engine/install/)"
+  }
+};
+
+export function getInstallCommand(tool) {
+  const platform = getPlatform();
+  return INSTALL_COMMANDS[tool]?.[platform] || INSTALL_COMMANDS[tool]?.linux || `Install ${tool} manually`;
+}