karajan-code 1.10.0 → 1.11.0

package/src/orchestrator/iteration-stages.js

@@ -93,21 +93,16 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
         }
       }
 
-      // No fallback or fallback also failed — pause
-      const question = `Agent ${coderRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
-      await pauseSession(session, {
-        question,
-        context: { iteration, stage: "coder", reason: "rate_limit", agent: coderRole.provider, detail: rateLimitCheck.message }
-      });
-      emitProgress(
-        emitter,
-        makeEvent("coder:rate_limit", { ...eventBase, stage: "coder" }, {
-          status: "paused",
-          message: question,
-          detail: { agent: coderRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
-        })
-      );
-      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+      // No fallback or fallback also failed — enter standby
+      return {
+        action: "standby",
+        standbyInfo: {
+          agent: coderRole.provider,
+          cooldownMs: rateLimitCheck.cooldownMs,
+          cooldownUntil: rateLimitCheck.cooldownUntil,
+          message: rateLimitCheck.message
+        }
+      };
     }
 
     await markSessionStatus(session, "failed");
@@ -167,20 +162,16 @@ export async function runRefactorerStage({ refactorerRole, config, logger, emitt
     });
 
     if (rateLimitCheck.isRateLimit) {
-      const question = `Agent ${refactorerRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
-      await pauseSession(session, {
-        question,
-        context: { iteration, stage: "refactorer", reason: "rate_limit", agent: refactorerRole.provider, detail: rateLimitCheck.message }
-      });
-      emitProgress(
-        emitter,
-        makeEvent("refactorer:rate_limit", { ...eventBase, stage: "refactorer" }, {
-          status: "paused",
-          message: question,
-          detail: { agent: refactorerRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
-        })
-      );
-      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+      // Enter standby instead of pausing
+      return {
+        action: "standby",
+        standbyInfo: {
+          agent: refactorerRole.provider,
+          cooldownMs: rateLimitCheck.cooldownMs,
+          cooldownUntil: rateLimitCheck.cooldownUntil,
+          message: rateLimitCheck.message
+        }
+      };
     }
 
     await markSessionStatus(session, "failed");
@@ -451,20 +442,16 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
     });
 
     if (rateLimitCheck.isRateLimit) {
-      const question = `Reviewer ${reviewerRole.provider} hit a rate limit: ${rateLimitCheck.message}. Session paused until the token window resets.`;
-      await pauseSession(session, {
-        question,
-        context: { iteration, stage: "reviewer", reason: "rate_limit", agent: reviewerRole.provider, detail: rateLimitCheck.message }
-      });
-      emitProgress(
-        emitter,
-        makeEvent("reviewer:rate_limit", { ...eventBase, stage: "reviewer" }, {
-          status: "paused",
-          message: question,
-          detail: { agent: reviewerRole.provider, rateLimitMessage: rateLimitCheck.message, sessionId: session.id }
-        })
-      );
-      return { action: "pause", result: { paused: true, sessionId: session.id, question, context: "rate_limit" } };
+      // Enter standby instead of pausing
+      return {
+        action: "standby",
+        standbyInfo: {
+          agent: reviewerRole.provider,
+          cooldownMs: rateLimitCheck.cooldownMs,
+          cooldownUntil: rateLimitCheck.cooldownUntil,
+          message: rateLimitCheck.message
+        }
+      };
     }
 
     await markSessionStatus(session, "failed");

package/src/orchestrator/solomon-rules.js

@@ -0,0 +1,138 @@
+/**
+ * Solomon rules engine — detects anomalies during session execution.
+ * Each rule returns { triggered: boolean, severity: "warn"|"critical", message, detail }
+ */
+
+const DEFAULT_RULES = {
+  max_files_per_iteration: 10,
+  max_stale_iterations: 3,
+  no_new_dependencies_without_task: true,
+  scope_guard: true
+};
+
+export function evaluateRules(context, rulesConfig = {}) {
+  const rules = { ...DEFAULT_RULES, ...rulesConfig };
+  const alerts = [];
+
+  // Rule 1: Too many files modified
+  if (rules.max_files_per_iteration && context.filesChanged > rules.max_files_per_iteration) {
+    alerts.push({
+      rule: "max_files_per_iteration",
+      severity: "critical",
+      message: `Coder modified ${context.filesChanged} files (limit: ${rules.max_files_per_iteration}). Possible scope drift.`,
+      detail: { filesChanged: context.filesChanged, limit: rules.max_files_per_iteration }
+    });
+  }
+
+  // Rule 2: Stale iterations (no progress)
+  if (rules.max_stale_iterations && context.staleIterations >= rules.max_stale_iterations) {
+    alerts.push({
+      rule: "max_stale_iterations",
+      severity: "critical",
+      message: `${context.staleIterations} iterations without progress. Same errors repeating.`,
+      detail: { staleIterations: context.staleIterations, limit: rules.max_stale_iterations }
+    });
+  }
+
+  // Rule 3: New dependencies not in task
+  if (rules.no_new_dependencies_without_task && context.newDependencies?.length > 0) {
+    const depsNotInTask = context.newDependencies.filter(
+      dep => !context.task?.toLowerCase().includes(dep.toLowerCase())
+    );
+    if (depsNotInTask.length > 0) {
+      alerts.push({
+        rule: "no_new_dependencies_without_task",
+        severity: "warn",
+        message: `New dependencies added not mentioned in task: ${depsNotInTask.join(", ")}`,
+        detail: { dependencies: depsNotInTask }
+      });
+    }
+  }
+
+  // Rule 4: Scope guard — files outside expected scope
+  if (rules.scope_guard && context.outOfScopeFiles?.length > 0) {
+    alerts.push({
+      rule: "scope_guard",
+      severity: "warn",
+      message: `Files modified outside expected scope: ${context.outOfScopeFiles.join(", ")}`,
+      detail: { files: context.outOfScopeFiles }
+    });
+  }
+
+  return {
+    alerts,
+    hasCritical: alerts.some(a => a.severity === "critical"),
+    hasWarnings: alerts.some(a => a.severity === "warn")
+  };
+}
+
+/**
+ * Build context for rules evaluation from git diff and session state.
+ */
+export async function buildRulesContext({ session, task, iteration }) {
+  const context = {
+    task,
+    iteration,
+    filesChanged: 0,
+    staleIterations: 0,
+    newDependencies: [],
+    outOfScopeFiles: []
+  };
+
+  // Count files changed via git
+  try {
+    const { execaCommand } = await import("execa");
+    const baseRef = session.session_start_sha || "HEAD~1";
+
+    // Files changed
+    const diffResult = await execaCommand(`git diff --name-only ${baseRef}`, { reject: false });
+    if (diffResult.stdout) {
+      const files = diffResult.stdout.split("\n").filter(Boolean);
+      context.filesChanged = files.length;
+
+      // Detect scope: config files, CI/CD, etc. that are often out of scope
+      const scopePatterns = [".github/", ".gitlab-ci", "docker-compose", ".env", "firebase.json", "firestore.rules"];
+      context.outOfScopeFiles = files.filter(f =>
+        scopePatterns.some(pattern => f.includes(pattern))
+      );
+
+      // Detect new dependencies
+      if (files.includes("package.json")) {
+        try {
+          const pkgDiff = await execaCommand(`git diff ${baseRef} -- package.json`, { reject: false });
+          const addedDeps = (pkgDiff.stdout || "").split("\n")
+            .filter(line => line.startsWith("+") && line.includes('"') && !line.startsWith("+++"))
+            .map(line => {
+              const match = line.match(/"([^"]+)":\s*"/);
+              return match ? match[1] : null;
+            })
+            .filter(Boolean)
+            .filter(name => !["name", "version", "description", "main", "scripts", "type", "license", "author"].includes(name));
+          context.newDependencies = addedDeps;
+        } catch { /* ignore */ }
+      }
+    }
+  } catch { /* git not available */ }
+
+  // Count stale iterations from session checkpoints
+  const checkpoints = session.checkpoints || [];
+  const recentCoderCheckpoints = checkpoints
+    .filter(cp => cp.stage === "coder" || cp.stage === "reviewer")
+    .slice(-6); // Last 3 iterations (coder+reviewer each)
+
+  // Simple heuristic: if last N reviewer checkpoints all have the same note/feedback, it's stale
+  if (recentCoderCheckpoints.length >= 4) {
+    const lastFeedbacks = checkpoints
+      .filter(cp => cp.stage === "reviewer")
+      .slice(-3)
+      .map(cp => cp.note || "");
+    const uniqueFeedbacks = new Set(lastFeedbacks);
+    if (uniqueFeedbacks.size === 1 && lastFeedbacks.length >= 2) {
+      context.staleIterations = lastFeedbacks.length;
+    }
+  }
+
+  return context;
+}
+
+export { DEFAULT_RULES };

package/src/orchestrator/standby.js

@@ -0,0 +1,70 @@
+import { emitProgress, makeEvent } from "../utils/events.js";
+
+const DEFAULT_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
+const MAX_COOLDOWN_MS = 30 * 60 * 1000; // 30 minutes
+const MAX_STANDBY_RETRIES = 5;
+const HEARTBEAT_INTERVAL_MS = 30 * 1000; // 30 seconds
+
+/**
+ * Wait for a rate limit cooldown, emitting heartbeat events.
+ * Returns when the cooldown expires.
+ *
+ * @param {object} options
+ * @param {number|null} options.cooldownMs - Milliseconds to wait (null = use default)
+ * @param {string|null} options.cooldownUntil - ISO timestamp when cooldown expires
+ * @param {string} options.agent - Agent that was rate-limited
+ * @param {number} options.retryCount - Current retry attempt (for backoff)
+ * @param {object} options.emitter - Event emitter
+ * @param {object} options.eventBase - Base event fields
+ * @param {object} options.logger
+ * @param {object} options.session
+ */
+export async function waitForCooldown({ cooldownMs, cooldownUntil, agent, retryCount, emitter, eventBase, logger, session }) {
+  // Calculate wait time with exponential backoff for retries without known cooldown
+  let waitMs = cooldownMs || DEFAULT_COOLDOWN_MS;
+  if (!cooldownMs && retryCount > 0) {
+    waitMs = Math.min(DEFAULT_COOLDOWN_MS * Math.pow(2, retryCount), MAX_COOLDOWN_MS);
+  }
+
+  const resumeAt = cooldownUntil || new Date(Date.now() + waitMs).toISOString();
+
+  logger.info(`Standby: waiting ${Math.round(waitMs / 1000)}s for ${agent} rate limit (retry ${retryCount + 1}/${MAX_STANDBY_RETRIES})`);
+
+  // Emit standby start event
+  emitProgress(emitter, makeEvent("coder:standby", { ...eventBase, stage: "standby" }, {
+    message: `Rate limited — standby until ${resumeAt} (attempt ${retryCount + 1}/${MAX_STANDBY_RETRIES})`,
+    detail: { agent, cooldownUntil: resumeAt, cooldownMs: waitMs, retryCount: retryCount + 1, maxRetries: MAX_STANDBY_RETRIES }
+  }));
+
+  // Update session status
+  session.status = "standby";
+
+  // Wait with periodic heartbeats
+  const startTime = Date.now();
+  const endTime = startTime + waitMs;
+
+  while (Date.now() < endTime) {
+    const remaining = endTime - Date.now();
+    const sleepTime = Math.min(HEARTBEAT_INTERVAL_MS, remaining);
+
+    await new Promise(resolve => setTimeout(resolve, sleepTime));
+
+    if (Date.now() < endTime) {
+      const remainingSec = Math.round((endTime - Date.now()) / 1000);
+      emitProgress(emitter, makeEvent("coder:standby_heartbeat", { ...eventBase, stage: "standby" }, {
+        message: `Standby: ${remainingSec}s remaining`,
+        detail: { agent, remainingMs: endTime - Date.now(), retryCount: retryCount + 1 }
+      }));
+    }
+  }
+
+  // Emit resume event
+  emitProgress(emitter, makeEvent("coder:standby_resume", { ...eventBase, stage: "standby" }, {
+    message: `Cooldown expired — resuming with ${agent}`,
+    detail: { agent, retryCount: retryCount + 1 }
+  }));
+
+  session.status = "running";
+}
+
+export { DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS, MAX_STANDBY_RETRIES, HEARTBEAT_INTERVAL_MS };

package/src/orchestrator.js

@@ -3,6 +3,7 @@ import {
   createSession,
   loadSession,
   markSessionStatus,
+  pauseSession,
   resumeSessionWithAnswer,
   saveSession,
   addCheckpoint
@@ -25,6 +26,7 @@ import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
 import { runTriageStage, runResearcherStage, runPlannerStage } from "./orchestrator/pre-loop-stages.js";
 import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
 import { runTesterStage, runSecurityStage } from "./orchestrator/post-loop-stages.js";
+import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 
 
 
@@ -146,6 +148,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     repeated_issue_count: 0,
     sonar_retry_count: 0,
     reviewer_retry_count: 0,
+    standby_retry_count: 0,
     last_sonar_issue_signature: null,
     sonar_repeat_count: 0,
     last_reviewer_issue_signature: null,
@@ -157,6 +160,32 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
 
   eventBase.sessionId = session.id;
 
+  // --- Planning Game: mark card as In Progress ---
+  let pgCard = null;
+  if (pgTaskId && pgProject && config.planning_game?.enabled !== false) {
+    try {
+      const { fetchCard, updateCard } = await import("./planning-game/client.js");
+      pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
+      if (pgCard && pgCard.status !== "In Progress") {
+        await updateCard({
+          projectId: pgProject,
+          cardId: pgTaskId,
+          firebaseId: pgCard.firebaseId,
+          updates: {
+            status: "In Progress",
+            startDate: new Date().toISOString(),
+            developer: "dev_016",
+            codeveloper: config.planning_game?.codeveloper || null
+          }
+        });
+        logger.info(`Planning Game: ${pgTaskId} → In Progress`);
+      }
+    } catch (err) {
+      logger.warn(`Planning Game: could not update ${pgTaskId}: ${err.message}`);
+    }
+  }
+  session.pg_card = pgCard || null;
+
   emitProgress(
     emitter,
     makeEvent("session:start", eventBase, {
@@ -380,6 +409,26 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     if (coderResult?.action === "pause") {
       return coderResult.result;
     }
+    if (coderResult?.action === "standby") {
+      const standbyRetries = session.standby_retry_count || 0;
+      if (standbyRetries >= MAX_STANDBY_RETRIES) {
+        await pauseSession(session, {
+          question: `Rate limit standby exhausted after ${standbyRetries} retries. Agent: ${coderResult.standbyInfo.agent}`,
+          context: { iteration: i, stage: "coder", reason: "standby_exhausted" }
+        });
+        emitProgress(emitter, makeEvent("coder:rate_limit", { ...eventBase, stage: "coder" }, {
+          status: "paused",
+          message: `Standby exhausted after ${standbyRetries} retries`,
+          detail: { agent: coderResult.standbyInfo.agent, sessionId: session.id }
+        }));
+        return { paused: true, sessionId: session.id, question: `Rate limit standby exhausted after ${standbyRetries} retries`, context: "standby_exhausted" };
+      }
+      session.standby_retry_count = standbyRetries + 1;
+      await saveSession(session);
+      await waitForCooldown({ ...coderResult.standbyInfo, retryCount: standbyRetries, emitter, eventBase, logger, session });
+      i -= 1; // Retry the same iteration
+      continue;
+    }
 
     // --- Refactorer ---
     if (refactorerEnabled) {
@@ -387,6 +436,26 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
       if (refResult?.action === "pause") {
         return refResult.result;
       }
+      if (refResult?.action === "standby") {
+        const standbyRetries = session.standby_retry_count || 0;
+        if (standbyRetries >= MAX_STANDBY_RETRIES) {
+          await pauseSession(session, {
+            question: `Rate limit standby exhausted after ${standbyRetries} retries. Agent: ${refResult.standbyInfo.agent}`,
+            context: { iteration: i, stage: "refactorer", reason: "standby_exhausted" }
+          });
+          emitProgress(emitter, makeEvent("refactorer:rate_limit", { ...eventBase, stage: "refactorer" }, {
+            status: "paused",
+            message: `Standby exhausted after ${standbyRetries} retries`,
+            detail: { agent: refResult.standbyInfo.agent, sessionId: session.id }
+          }));
+          return { paused: true, sessionId: session.id, question: `Rate limit standby exhausted after ${standbyRetries} retries`, context: "standby_exhausted" };
+        }
+        session.standby_retry_count = standbyRetries + 1;
+        await saveSession(session);
+        await waitForCooldown({ ...refResult.standbyInfo, retryCount: standbyRetries, emitter, eventBase, logger, session });
+        i -= 1; // Retry the same iteration
+        continue;
+      }
     }
 
     // --- TDD Policy ---
@@ -432,6 +501,26 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
       if (reviewerResult.action === "pause") {
         return reviewerResult.result;
       }
+      if (reviewerResult.action === "standby") {
+        const standbyRetries = session.standby_retry_count || 0;
+        if (standbyRetries >= MAX_STANDBY_RETRIES) {
+          await pauseSession(session, {
+            question: `Rate limit standby exhausted after ${standbyRetries} retries. Agent: ${reviewerResult.standbyInfo.agent}`,
+            context: { iteration: i, stage: "reviewer", reason: "standby_exhausted" }
+          });
+          emitProgress(emitter, makeEvent("reviewer:rate_limit", { ...eventBase, stage: "reviewer" }, {
+            status: "paused",
+            message: `Standby exhausted after ${standbyRetries} retries`,
+            detail: { agent: reviewerResult.standbyInfo.agent, sessionId: session.id }
+          }));
+          return { paused: true, sessionId: session.id, question: `Rate limit standby exhausted after ${standbyRetries} retries`, context: "standby_exhausted" };
+        }
+        session.standby_retry_count = standbyRetries + 1;
+        await saveSession(session);
+        await waitForCooldown({ ...reviewerResult.standbyInfo, retryCount: standbyRetries, emitter, eventBase, logger, session });
+        i -= 1; // Retry the same iteration
+        continue;
+      }
       review = reviewerResult.review;
       if (reviewerResult.stalled) {
         return reviewerResult.stalledResult;
@@ -448,6 +537,49 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
       })
     );
 
+    // Reset standby counter after successful iteration
+    session.standby_retry_count = 0;
+
+    // --- Solomon supervisor: anomaly detection after each iteration ---
+    if (config.pipeline?.solomon?.enabled !== false) {
+      try {
+        const { evaluateRules, buildRulesContext } = await import("./orchestrator/solomon-rules.js");
+        const rulesContext = await buildRulesContext({ session, task, iteration: i });
+        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}`);
+          }
+
+          if (rulesResult.hasCritical && askQuestion) {
+            const alertSummary = rulesResult.alerts
+              .filter(a => a.severity === "critical")
+              .map(a => a.message)
+              .join("\n");
+            const answer = await askQuestion(
+              `Solomon detected critical issues:\n${alertSummary}\n\nShould I continue, pause, or revert?`,
+              { iteration: i, stage: "solomon" }
+            );
+            if (!answer || answer.toLowerCase().includes("pause") || answer.toLowerCase().includes("stop")) {
+              await pauseSession(session, {
+                question: `Solomon supervisor paused: ${alertSummary}`,
+                context: { iteration: i, stage: "solomon", alerts: rulesResult.alerts }
+              });
+              return { paused: true, sessionId: session.id, reason: "solomon_alert" };
+            }
+          }
+        }
+      } catch (err) {
+        logger.warn(`Solomon rules evaluation failed: ${err.message}`);
+      }
+    }
+
     if (review.approved) {
       session.reviewer_retry_count = 0;
 
@@ -493,6 +625,30 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
       }
       session.budget = budgetSummary();
       await markSessionStatus(session, "approved");
+
+      // --- Planning Game: mark card as To Validate ---
+      if (pgCard && pgProject) {
+        try {
+          const { updateCard } = await import("./planning-game/client.js");
+          const { buildCompletionUpdates } = await import("./planning-game/adapter.js");
+          const pgUpdates = buildCompletionUpdates({
+            approved: true,
+            commits: gitResult?.commits || [],
+            startDate: session.pg_card?.startDate || session.created_at,
+            codeveloper: config.planning_game?.codeveloper || null
+          });
+          await updateCard({
+            projectId: pgProject,
+            cardId: session.pg_task_id,
+            firebaseId: pgCard.firebaseId,
+            updates: pgUpdates
+          });
+          logger.info(`Planning Game: ${session.pg_task_id} → To Validate`);
+        } catch (err) {
+          logger.warn(`Planning Game: could not update ${session.pg_task_id} on completion: ${err.message}`);
+        }
+      }
+
       emitProgress(
         emitter,
         makeEvent("session:end", { ...eventBase, stage: "done" }, {
@@ -600,6 +756,7 @@ export async function resumeFlow({ sessionId, answer, config, logger, flags = {}
   session.repeated_issue_count = 0;
   session.sonar_retry_count = 0;
   session.reviewer_retry_count = 0;
+  session.standby_retry_count = 0;
   session.tester_retry_count = 0;
   session.security_retry_count = 0;
   session.last_sonar_issue_signature = null;

package/src/prompts/triage.js

@@ -0,0 +1,61 @@
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on task complexity triage."
+].join(" ");
+
+const ROLE_DESCRIPTIONS = [
+  { role: "planner", description: "Generates an implementation plan before coding. Useful for complex multi-file tasks." },
+  { role: "researcher", description: "Investigates the codebase for context before coding. Useful when understanding existing code is needed." },
+  { role: "tester", description: "Runs dedicated testing pass after coding. Ensures tests exist and pass." },
+  { role: "security", description: "Audits code for security vulnerabilities. Checks auth, input validation, injection risks." },
+  { role: "refactorer", description: "Cleans up and refactors code after the main implementation." },
+  { role: "reviewer", description: "Reviews the code diff for quality issues. Standard quality gate." }
+];
+
+export function buildTriagePrompt({ task, instructions, availableRoles }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  const roles = availableRoles || ROLE_DESCRIPTIONS;
+
+  sections.push(
+    "You are a task triage agent for Karajan Code, a multi-agent coding orchestrator.",
+    "Analyze the following task and determine which pipeline roles should be activated."
+  );
+
+  sections.push(
+    "## Available Roles",
+    roles.map((r) => `- **${r.role}**: ${r.description}`).join("\n")
+  );
+
+  sections.push(
+    "## Decision Guidelines",
+    [
+      "- **planner**: Enable for complex tasks (multi-file, architectural changes, data model changes). Disable for simple fixes.",
+      "- **researcher**: Enable when the task needs codebase context, API understanding, or investigation. Disable for standalone new files.",
+      "- **tester**: Enable for any task with logic, APIs, components, services. Disable ONLY for pure documentation, comments, or CSS-only changes.",
+      "- **security**: Enable for authentication, APIs, user input handling, data access, external integrations. Disable for UI-only or doc changes.",
+      "- **refactorer**: Enable only when explicitly requested or when the task is a refactoring task.",
+      "- **reviewer**: Enable for most tasks as a quality gate. Disable only for trivial, single-line changes.",
+      "",
+      "Note: coder is ALWAYS active — you don't need to decide on it."
+    ].join("\n")
+  );
+
+  sections.push(
+    "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,"shouldDecompose":boolean,"subtasks":string[]}'
+  );
+
+  sections.push(`## Task\n${task}`);
+
+  return sections.join("\n\n");
+}
+
+export { ROLE_DESCRIPTIONS };

package/src/roles/triage-role.js

@@ -1,11 +1,6 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
-
-const SUBAGENT_PREAMBLE = [
-  "IMPORTANT: You are running as a Karajan sub-agent.",
-  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
-  "Do NOT use any MCP tools. Focus only on task complexity triage."
-].join(" ");
+import { buildTriagePrompt } from "../prompts/triage.js";
 
 const VALID_LEVELS = new Set(["trivial", "simple", "medium", "complex"]);
 const VALID_ROLES = new Set(["planner", "researcher", "refactorer", "reviewer", "tester", "security"]);
@@ -18,25 +13,6 @@ function resolveProvider(config) {
   );
 }
 
-function buildPrompt({ task, instructions }) {
-  const sections = [SUBAGENT_PREAMBLE];
-
-  if (instructions) {
-    sections.push(instructions);
-  }
-
-  sections.push(
-    "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,"shouldDecompose":boolean,"subtasks":string[]}'
-  );
-
-  sections.push(`## Task\n${task}`);
-
-  return sections.join("\n\n");
-}
-
 function parseTriageOutput(raw) {
   const text = raw?.trim() || "";
   const jsonMatch = text.match(/\{[\s\S]*\}/);
@@ -72,7 +48,7 @@ export class TriageRole extends BaseRole {
     const provider = resolveProvider(this.config);
     const agent = this._createAgent(provider, this.config, this.logger);
 
-    const prompt = buildPrompt({ task, instructions: this.instructions });
+    const prompt = buildTriagePrompt({ task, instructions: this.instructions });
     const runArgs = { prompt, role: "triage" };
     if (onOutput) runArgs.onOutput = onOutput;
     const result = await agent.runTask(runArgs);

package/src/utils/display.js

@@ -41,6 +41,9 @@ const ICONS = {
   "solomon:start": "\u2696\ufe0f",
   "solomon:end": "\u2696\ufe0f",
   "solomon:escalate": "\u26a0\ufe0f",
+  "coder:standby": "\u23f3",
+  "coder:standby_heartbeat": "\u23f3",
+  "coder:standby_resume": "\u25b6\ufe0f",
   "budget:update": "\ud83d\udcb8",
   "iteration:end": "\u23f1\ufe0f",
   "session:end": "\ud83c\udfc1",
@@ -245,6 +248,24 @@ export function printEvent(event) {
       break;
     }
 
+    case "coder:standby": {
+      const until = event.detail?.cooldownUntil || "?";
+      const attempt = event.detail?.retryCount || "?";
+      const maxRetries = event.detail?.maxRetries || "?";
+      console.log(`  \u251c\u2500 ${ANSI.yellow}${icon} Rate limited \u2014 standby until ${until} (attempt ${attempt}/${maxRetries})${ANSI.reset}`);
+      break;
+    }
+
+    case "coder:standby_heartbeat": {
+      const remaining = event.detail?.remainingMs !== undefined ? Math.round(event.detail.remainingMs / 1000) : "?";
+      console.log(`  \u251c\u2500 ${ANSI.yellow}${icon} Standby: ${remaining}s remaining${ANSI.reset}`);
+      break;
+    }
+
+    case "coder:standby_resume":
+      console.log(`  \u251c\u2500 ${ANSI.green}${icon} Cooldown expired \u2014 resuming with ${event.detail?.coder || event.detail?.provider || "?"}${ANSI.reset}`);
+      break;
+
     case "iteration:end":
       console.log(`  \u2514\u2500 ${icon} Duration: ${formatElapsed(event.detail?.duration)}  ${elapsed}`);
       break;