karajan-code 1.2.3 → 1.4.0

package/README.md

@@ -36,7 +36,9 @@ Instead of running one AI agent and manually reviewing its output, `kj` chains a
 - **Review profiles** — standard, strict, relaxed, paranoid
 - **Budget tracking** — per-session token and cost monitoring with `--trace`
 - **Git automation** — auto-commit, auto-push, auto-PR after approval
-- **Session management** — pause/resume with fail-fast detection
+- **Session management** — pause/resume with fail-fast detection and automatic cleanup of expired sessions
+- **Plugin system** — extend with custom agents via `.karajan/plugins/`
+- **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
 
 > **Best with MCP** — Karajan Code is designed to be used as an MCP server inside your AI agent (Claude, Codex, etc.). The agent sends tasks to `kj_run`, gets real-time progress notifications, and receives structured results — no copy-pasting needed.
@@ -428,7 +430,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 761+ tests with Vitest
+npm test              # Run 899+ tests with Vitest
 npm run test:watch    # Watch mode
 npm run validate      # Lint + test
 ```
@@ -439,6 +441,7 @@ npm run validate      # Lint + test
 
 ## Links
 
+- [Website](https://karajancode.com) (also [kj-code.com](https://kj-code.com))
 - [Changelog](CHANGELOG.md)
 - [Security Policy](SECURITY.md)
 - [License (AGPL-3.0)](LICENSE)

package/docs/README.es.md

@@ -36,7 +36,9 @@ En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encad
 - **Perfiles de revision** — standard, strict, relaxed, paranoid
 - **Tracking de presupuesto** — monitorizacion de tokens y costes por sesion con `--trace`
 - **Automatizacion Git** — auto-commit, auto-push, auto-PR tras aprobacion
-- **Gestion de sesiones** — pausa/reanudacion con deteccion fail-fast
+- **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/`
+- **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
 
 > **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
@@ -227,7 +229,7 @@ Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar 761+ tests con Vitest
+npm test              # Ejecutar 899+ tests con Vitest
 npm run test:watch    # Modo watch
 npm run validate      # Lint + test
 ```
@@ -238,6 +240,7 @@ npm run validate      # Lint + test
 
 ## Enlaces
 
+- [Web](https://karajancode.com) (tambien [kj-code.com](https://kj-code.com))
 - [Changelog](../CHANGELOG.md)
 - [Politica de seguridad](../SECURITY.md)
 - [Licencia (AGPL-3.0)](../LICENSE)

package/package.json

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

package/src/cli.js

@@ -71,6 +71,7 @@ program
   .option("--max-total-minutes <n>")
   .option("--base-branch <name>")
   .option("--base-ref <ref>")
+  .option("--coder-fallback <name>")
   .option("--reviewer-fallback <name>")
   .option("--reviewer-retries <n>")
   .option("--auto-commit")

package/src/config.js

@@ -33,7 +33,7 @@ const DEFAULTS = {
   review_rules: "./review-rules.md",
   coder_rules: "./coder-rules.md",
   base_branch: "main",
-  coder_options: { model: null, auto_approve: true },
+  coder_options: { model: null, auto_approve: true, fallback_coder: null },
   reviewer_options: {
     output_format: "json",
     require_schema: true,
@@ -114,10 +114,18 @@ const DEFAULTS = {
     max_sonar_retries: 3,
     max_reviewer_retries: 3,
     max_tester_retries: 1,
-    max_security_retries: 1
+    max_security_retries: 1,
+    expiry_days: 30
   },
   failFast: {
     repeatThreshold: 2
+  },
+  retry: {
+    max_attempts: 3,
+    initial_backoff_ms: 1000,
+    max_backoff_ms: 30000,
+    backoff_multiplier: 2,
+    jitter_factor: 0.1
   }
 };
 
@@ -232,6 +240,7 @@ export function applyRunOverrides(config, flags) {
   if (flags.maxIterationMinutes) out.session.max_iteration_minutes = Number(flags.maxIterationMinutes);
   if (flags.maxTotalMinutes) out.session.max_total_minutes = Number(flags.maxTotalMinutes);
   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;
   if (flags.reviewerRetries !== undefined) out.reviewer_options.retries = Number(flags.reviewerRetries);
   if (flags.autoCommit !== undefined) out.git.auto_commit = Boolean(flags.autoCommit);

package/src/orchestrator/agent-fallback.js

@@ -0,0 +1,83 @@
+import { createAgent } from "../agents/index.js";
+import { addCheckpoint } from "../session-store.js";
+import { detectRateLimit } from "../utils/rate-limit-detector.js";
+
+/**
+ * Run a coder-like role with fallback on rate limit.
+ * Tries the primary agent first. If it fails with a rate limit,
+ * switches to the fallback agent (if configured).
+ * Non-rate-limit failures stop immediately (no fallback).
+ *
+ * Returns { execResult, attempts, allRateLimited }
+ */
+export async function runCoderWithFallback({
+  coderName,
+  fallbackCoder,
+  config,
+  logger,
+  emitter,
+  RoleClass,
+  roleInput,
+  session,
+  iteration,
+  onAttemptResult
+}) {
+  const candidates = [coderName];
+  if (fallbackCoder && fallbackCoder !== coderName) {
+    candidates.push(fallbackCoder);
+  }
+
+  const attempts = [];
+  let allRateLimited = true;
+
+  for (const name of candidates) {
+    const agentConfig = {
+      ...config,
+      roles: { ...config.roles, coder: { ...config.roles?.coder, provider: name } }
+    };
+
+    const role = new RoleClass({ config: agentConfig, logger, emitter, createAgentFn: createAgent });
+    await role.init();
+
+    const execResult = await role.execute(roleInput);
+
+    if (onAttemptResult) {
+      await onAttemptResult({ coder: name, result: execResult.result });
+    }
+
+    const rateLimited = !execResult.ok && detectRateLimit({
+      stderr: execResult.result?.error || "",
+      stdout: execResult.result?.output || ""
+    }).isRateLimit;
+
+    attempts.push({
+      coder: name,
+      ok: execResult.ok,
+      rateLimited,
+      result: execResult.result,
+      execResult
+    });
+
+    await addCheckpoint(session, {
+      stage: "coder-attempt",
+      iteration,
+      coder: name,
+      ok: execResult.ok,
+      rateLimited
+    });
+
+    if (execResult.ok) {
+      return { execResult, attempts, allRateLimited: false };
+    }
+
+    // Only fallback on rate limit errors
+    if (!rateLimited) {
+      allRateLimited = false;
+      return { execResult: null, attempts, allRateLimited: false };
+    }
+
+    logger.warn(`Agent ${name} hit rate limit, trying fallback...`);
+  }
+
+  return { execResult: null, attempts, allRateLimited };
+}

package/src/orchestrator/iteration-stages.js

@@ -1,4 +1,5 @@
 import { createAgent } from "../agents/index.js";
+import { CoderRole } from "../roles/coder-role.js";
 import { RefactorerRole } from "../roles/refactorer-role.js";
 import { SonarRole } from "../roles/sonar-role.js";
 import { addCheckpoint, markSessionStatus, saveSession, pauseSession } from "../session-store.js";
@@ -7,7 +8,9 @@ import { evaluateTddPolicy } from "../review/tdd-policy.js";
 import { validateReviewResult } from "../review/schema.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { runReviewerWithFallback } from "./reviewer-fallback.js";
+import { runCoderWithFallback } from "./agent-fallback.js";
 import { invokeSolomon } from "./solomon-escalation.js";
+import { detectRateLimit } from "../utils/rate-limit-detector.js";
 
 export async function runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration }) {
   logger.setContext({ iteration, stage: "coder" });
@@ -35,8 +38,70 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
   trackBudget({ role: "coder", provider: coderRole.provider, model: coderRole.model, result: coderExecResult.result, duration_ms: Date.now() - coderStart });
 
   if (!coderExecResult.ok) {
-    await markSessionStatus(session, "failed");
     const details = coderExecResult.result?.error || coderExecResult.summary || "unknown error";
+    const rateLimitCheck = detectRateLimit({
+      stderr: coderExecResult.result?.error || "",
+      stdout: coderExecResult.result?.output || ""
+    });
+
+    if (rateLimitCheck.isRateLimit) {
+      // Try fallback agent if configured
+      const fallbackCoder = config.coder_options?.fallback_coder;
+      if (fallbackCoder && fallbackCoder !== coderRole.provider) {
+        logger.warn(`Coder ${coderRole.provider} hit rate limit, falling back to ${fallbackCoder}`);
+        emitProgress(
+          emitter,
+          makeEvent("coder:fallback", { ...eventBase, stage: "coder" }, {
+            message: `Coder ${coderRole.provider} rate-limited, switching to ${fallbackCoder}`,
+            detail: { primary: coderRole.provider, fallback: fallbackCoder }
+          })
+        );
+
+        const fallbackResult = await runCoderWithFallback({
+          coderName: fallbackCoder,
+          fallbackCoder: null,
+          config,
+          logger,
+          emitter,
+          RoleClass: CoderRole,
+          roleInput: { task: plannedTask, reviewerFeedback: session.last_reviewer_feedback, sonarSummary: session.last_sonar_summary, onOutput: coderOnOutput },
+          session,
+          iteration,
+          onAttemptResult: ({ coder, result }) => {
+            trackBudget({ role: "coder", provider: coder, model: coderRole.model, result, duration_ms: Date.now() - coderStart });
+          }
+        });
+
+        if (fallbackResult.execResult?.ok) {
+          await addCheckpoint(session, { stage: "coder", iteration, note: `Coder completed via fallback (${fallbackCoder})` });
+          emitProgress(
+            emitter,
+            makeEvent("coder:end", { ...eventBase, stage: "coder" }, {
+              message: `Coder completed (fallback: ${fallbackCoder})`
+            })
+          );
+          return;
+        }
+      }
+
+      // 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" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("coder:end", { ...eventBase, stage: "coder" }, {
@@ -71,8 +136,30 @@ export async function runRefactorerStage({ refactorerRole, config, logger, emitt
   const refResult = await refRole.execute(plannedTask);
   trackBudget({ role: "refactorer", provider: refactorerRole.provider, model: refactorerRole.model, result: refResult.result, duration_ms: Date.now() - refactorerStart });
   if (!refResult.ok) {
-    await markSessionStatus(session, "failed");
     const details = refResult.result?.error || refResult.summary || "unknown error";
+    const rateLimitCheck = detectRateLimit({
+      stderr: refResult.result?.error || "",
+      stdout: refResult.result?.output || ""
+    });
+
+    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" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("refactorer:end", { ...eventBase, stage: "refactorer" }, {
@@ -318,12 +405,35 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
   });
 
   if (!reviewerExec.execResult || !reviewerExec.execResult.ok) {
-    await markSessionStatus(session, "failed");
     const lastAttempt = reviewerExec.attempts.at(-1);
     const details =
       lastAttempt?.result?.error ||
       lastAttempt?.execResult?.summary ||
       `reviewer=${lastAttempt?.reviewer || "unknown"}`;
+
+    const rateLimitCheck = detectRateLimit({
+      stderr: lastAttempt?.result?.error || "",
+      stdout: lastAttempt?.result?.output || ""
+    });
+
+    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" } };
+    }
+
+    await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("reviewer:end", { ...eventBase, stage: "reviewer" }, {

package/src/orchestrator.js

@@ -255,11 +255,17 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     logger.info(`Iteration ${i}/${config.max_iterations}`);
 
     // --- Coder ---
-    await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+    const coderResult = await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+    if (coderResult?.action === "pause") {
+      return coderResult.result;
+    }
 
     // --- Refactorer ---
     if (refactorerEnabled) {
-      await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+      const refResult = await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+      if (refResult?.action === "pause") {
+        return refResult.result;
+      }
     }
 
     // --- TDD Policy ---
@@ -302,6 +308,9 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         reviewerRole, config, logger, emitter, eventBase, session, trackBudget,
         iteration: i, reviewRules, task, repeatDetector, budgetSummary
       });
+      if (reviewerResult.action === "pause") {
+        return reviewerResult.result;
+      }
       review = reviewerResult.review;
       if (reviewerResult.stalled) {
         return reviewerResult.stalledResult;

package/src/planning-game/client.js

@@ -9,6 +9,8 @@
  * Requires planning_game.api_url in config or PG_API_URL env var.
  */
 
+import { withRetry, isTransientError } from "../utils/retry.js";
+
 const DEFAULT_API_URL = "http://localhost:3000/api";
 const DEFAULT_TIMEOUT_MS = 10000;
 
@@ -20,10 +22,20 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_M
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    return await fetch(url, { ...options, signal: controller.signal });
+    const response = await fetch(url, { ...options, signal: controller.signal });
+    if (!response.ok) {
+      const err = new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
+      err.httpStatus = response.status;
+      err.retryAfter = response.headers?.get?.("retry-after") || null;
+      throw err;
+    }
+    return response;
   } catch (error) {
+    if (error?.httpStatus) throw error;
     if (error?.name === "AbortError") {
-      throw new Error(`Planning Game API timeout after ${timeoutMs}ms`);
+      const err = new Error(`Planning Game API timeout after ${timeoutMs}ms`);
+      err.httpStatus = 408;
+      throw err;
     }
     throw new Error(`Planning Game network error: ${error?.message || "unknown error"}`);
   } finally {
@@ -31,6 +43,13 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_M
   }
 }
 
+async function fetchWithRetry(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS, retryOpts = {}) {
+  return withRetry(
+    () => fetchWithTimeout(url, options, timeoutMs),
+    { maxAttempts: 3, initialBackoffMs: 1000, ...retryOpts }
+  );
+}
+
 async function parseJsonResponse(response) {
   try {
     return await response.json();
@@ -41,10 +60,7 @@ async function parseJsonResponse(response) {
 
 export async function fetchCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
   const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(cardId)}`;
-  const response = await fetchWithTimeout(url, {}, timeoutMs);
-  if (!response.ok) {
-    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
-  }
+  const response = await fetchWithRetry(url, {}, timeoutMs);
   const data = await parseJsonResponse(response);
   return data?.card || data;
 }
@@ -55,27 +71,21 @@ export async function getCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_M
 
 export async function listCards({ projectId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
   const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards`;
-  const response = await fetchWithTimeout(url, {}, timeoutMs);
-  if (!response.ok) {
-    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
-  }
+  const response = await fetchWithRetry(url, {}, timeoutMs);
   const data = await parseJsonResponse(response);
   return data?.cards || data;
 }
 
 export async function updateCard({ projectId, cardId, firebaseId, updates, timeoutMs = DEFAULT_TIMEOUT_MS }) {
   const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(firebaseId)}`;
-  const response = await fetchWithTimeout(
+  const response = await fetchWithRetry(
     url,
     {
-    method: "PATCH",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ updates })
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ updates })
     },
     timeoutMs
   );
-  if (!response.ok) {
-    throw new Error(`Planning Game API error: ${response.status} ${response.statusText}`);
-  }
   return parseJsonResponse(response);
 }

package/src/plugins/loader.js

@@ -0,0 +1,67 @@
+/**
+ * Plugin loader: discovers and loads plugins from .karajan/plugins/ directories.
+ *
+ * Plugins are JS files that export a `register(api)` function.
+ * The `api` object provides: registerAgent, registerModel.
+ *
+ * Discovery order (all are loaded, not first-wins):
+ *   1. <project>/.karajan/plugins/*.js
+ *   2. ~/.karajan/plugins/*.js
+ */
+
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getKarajanHome } from "../utils/paths.js";
+import { registerAgent } from "../agents/index.js";
+
+async function listPluginFiles(dir) {
+  try {
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith(".js"))
+      .map((e) => path.join(dir, e.name));
+  } catch {
+    return [];
+  }
+}
+
+async function loadPlugin(filePath, api, logger) {
+  try {
+    const mod = await import(pathToFileURL(filePath).href);
+    const registerFn = mod.register || mod.default?.register;
+    if (typeof registerFn !== "function") {
+      logger?.warn?.(`Plugin ${filePath}: no register() export found, skipping`);
+      return null;
+    }
+    const meta = registerFn(api);
+    const name = meta?.name || path.basename(filePath, ".js");
+    logger?.debug?.(`Plugin loaded: ${name} (${filePath})`);
+    return { name, path: filePath, meta };
+  } catch (error) {
+    logger?.warn?.(`Plugin ${filePath} failed to load: ${error.message}`);
+    return null;
+  }
+}
+
+export async function loadPlugins({ projectDir, logger } = {}) {
+  const dirs = [];
+
+  if (projectDir) {
+    dirs.push(path.join(projectDir, ".karajan", "plugins"));
+  }
+  dirs.push(path.join(getKarajanHome(), "plugins"));
+
+  const api = { registerAgent };
+
+  const loaded = [];
+  for (const dir of dirs) {
+    const files = await listPluginFiles(dir);
+    for (const file of files) {
+      const result = await loadPlugin(file, api, logger);
+      if (result) loaded.push(result);
+    }
+  }
+
+  return loaded;
+}

package/src/session-cleanup.js

@@ -0,0 +1,63 @@
+/**
+ * Automatic cleanup of expired sessions.
+ * Removes session directories older than session.expiry_days (default: 30).
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSessionRoot } from "./utils/paths.js";
+
+const DEFAULT_EXPIRY_DAYS = 30;
+
+export async function cleanupExpiredSessions({ config, logger } = {}) {
+  const expiryDays = config?.session?.expiry_days ?? DEFAULT_EXPIRY_DAYS;
+  if (expiryDays <= 0) return { removed: 0, errors: [] };
+
+  const sessionRoot = getSessionRoot();
+  const cutoff = Date.now() - expiryDays * 24 * 60 * 60 * 1000;
+
+  let entries;
+  try {
+    entries = await fs.readdir(sessionRoot, { withFileTypes: true });
+  } catch {
+    return { removed: 0, errors: [] };
+  }
+
+  const dirs = entries.filter((e) => e.isDirectory() && e.name.startsWith("s_"));
+  const removed = [];
+  const errors = [];
+
+  for (const dir of dirs) {
+    const sessionDir = path.join(sessionRoot, dir.name);
+    const sessionFile = path.join(sessionDir, "session.json");
+
+    try {
+      const raw = await fs.readFile(sessionFile, "utf8");
+      const session = JSON.parse(raw);
+      const updatedAt = new Date(session.updated_at || session.created_at).getTime();
+
+      if (updatedAt < cutoff) {
+        await fs.rm(sessionDir, { recursive: true, force: true });
+        removed.push(dir.name);
+        logger?.debug?.(`Session expired and removed: ${dir.name}`);
+      }
+    } catch (error) {
+      const stat = await fs.stat(sessionDir).catch(() => null);
+      if (stat && stat.mtimeMs < cutoff) {
+        try {
+          await fs.rm(sessionDir, { recursive: true, force: true });
+          removed.push(dir.name);
+          logger?.debug?.(`Orphan session dir removed: ${dir.name}`);
+        } catch (rmErr) {
+          errors.push({ session: dir.name, error: rmErr.message });
+        }
+      }
+    }
+  }
+
+  if (removed.length > 0) {
+    logger?.info?.(`Cleaned up ${removed.length} expired session(s)`);
+  }
+
+  return { removed: removed.length, errors };
+}

package/src/sonar/api.js

@@ -1,4 +1,5 @@
 import { runCommand } from "../utils/process.js";
+import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 
 export class SonarApiError extends Error {
@@ -22,16 +23,18 @@ function parseHttpResponse(stdout) {
   return { httpCode, body };
 }
 
-async function sonarFetch(config, urlPath) {
+async function sonarFetchOnce(config, urlPath) {
   const token = tokenFromConfig(config);
   const url = `${config.sonarqube.host}${urlPath}`;
   const res = await runCommand("curl", ["-s", "-w", "\n%{http_code}", "-u", `${token}:`, url]);
 
   if (res.exitCode !== 0) {
-    throw new SonarApiError(
+    const err = new SonarApiError(
       `SonarQube is not reachable at ${config.sonarqube.host}. Check that SonarQube is running ('kj sonar start').`,
       { url, hint: "Run 'kj sonar start' or verify Docker is running." }
     );
+    err.httpStatus = 503;
+    throw err;
   }
 
   const { httpCode, body } = parseHttpResponse(res.stdout);
@@ -44,15 +47,25 @@ async function sonarFetch(config, urlPath) {
   }
 
   if (httpCode >= 400) {
-    throw new SonarApiError(
+    const err = new SonarApiError(
       `SonarQube API returned HTTP ${httpCode} for ${url}.`,
       { url, httpStatus: httpCode }
     );
+    err.httpStatus = httpCode;
+    throw err;
   }
 
   return body;
 }
 
+async function sonarFetch(config, urlPath) {
+  const maxAttempts = config.sonarqube?.max_scan_retries ?? 3;
+  return withRetry(
+    () => sonarFetchOnce(config, urlPath),
+    { maxAttempts, initialBackoffMs: 2000, maxBackoffMs: 15000 }
+  );
+}
+
 export async function getQualityGateStatus(config, projectKey = null) {
   const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
   const body = await sonarFetch(config, `/api/qualitygates/project_status?projectKey=${effectiveProjectKey}`);

package/src/utils/rate-limit-detector.js

@@ -0,0 +1,43 @@
+/**
+ * Detects rate limit / usage cap messages from CLI agent output.
+ * Returns { isRateLimit, agent, message } where agent is the best guess
+ * of which CLI triggered it (or "unknown").
+ */
+
+const RATE_LIMIT_PATTERNS = [
+  // Claude CLI
+  { pattern: /usage limit/i, agent: "claude" },
+  { pattern: /plan's usage limit/i, agent: "claude" },
+  { pattern: /Claude Pro usage limit/i, agent: "claude" },
+
+  // OpenAI / Codex CLI
+  { pattern: /exceeded your current quota/i, agent: "codex" },
+
+  // Gemini CLI
+  { pattern: /resource exhausted/i, agent: "gemini" },
+  { pattern: /quota exceeded/i, agent: "gemini" },
+
+  // Generic (match any agent)
+  { pattern: /rate limit/i, agent: "unknown" },
+  { pattern: /token limit reached/i, agent: "unknown" },
+  { pattern: /\b429\b/, agent: "unknown" },
+  { pattern: /too many requests/i, agent: "unknown" },
+  { pattern: /throttl/i, agent: "unknown" },
+];
+
+export function detectRateLimit({ stderr = "", stdout = "" }) {
+  const combined = `${stderr}\n${stdout}`;
+
+  for (const { pattern, agent } of RATE_LIMIT_PATTERNS) {
+    if (pattern.test(combined)) {
+      const matchedLine = combined.split("\n").find((l) => pattern.test(l)) || combined.trim();
+      return {
+        isRateLimit: true,
+        agent,
+        message: matchedLine.trim()
+      };
+    }
+  }
+
+  return { isRateLimit: false, agent: "", message: "" };
+}

package/src/utils/retry.js

@@ -0,0 +1,88 @@
+/**
+ * Generic retry utility with exponential backoff and jitter.
+ * Handles transient errors (429, 502, 503, timeouts) automatically.
+ */
+
+const TRANSIENT_HTTP_CODES = new Set([408, 429, 500, 502, 503, 504]);
+
+const TRANSIENT_ERROR_PATTERNS = [
+  "ETIMEDOUT", "ECONNREFUSED", "ECONNRESET", "EPIPE",
+  "ENETUNREACH", "EAI_AGAIN", "EHOSTUNREACH",
+  "socket hang up", "network error", "fetch failed"
+];
+
+const DEFAULT_OPTIONS = {
+  maxAttempts: 3,
+  initialBackoffMs: 1000,
+  maxBackoffMs: 30000,
+  backoffMultiplier: 2,
+  jitterFactor: 0.1,
+  onRetry: null
+};
+
+export function isTransientError(error) {
+  if (!error) return false;
+
+  if (error.httpStatus && TRANSIENT_HTTP_CODES.has(error.httpStatus)) return true;
+  if (error.status && TRANSIENT_HTTP_CODES.has(error.status)) return true;
+
+  const msg = (error.message || String(error)).toLowerCase();
+  return TRANSIENT_ERROR_PATTERNS.some((p) => msg.includes(p.toLowerCase()));
+}
+
+export function parseRetryAfter(headerValue) {
+  if (!headerValue) return null;
+  const seconds = Number(headerValue);
+  if (!Number.isNaN(seconds) && seconds > 0) return seconds * 1000;
+
+  const date = Date.parse(headerValue);
+  if (!Number.isNaN(date)) {
+    const delayMs = date - Date.now();
+    return delayMs > 0 ? delayMs : null;
+  }
+  return null;
+}
+
+export function calculateBackoff(attempt, options = {}) {
+  const { initialBackoffMs = 1000, maxBackoffMs = 30000, backoffMultiplier = 2, jitterFactor = 0.1 } = options;
+
+  const base = initialBackoffMs * Math.pow(backoffMultiplier, attempt);
+  const capped = Math.min(base, maxBackoffMs);
+  const jitter = capped * jitterFactor * (Math.random() * 2 - 1);
+  return Math.max(0, Math.round(capped + jitter));
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function withRetry(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError;
+
+  for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (error) {
+      lastError = error;
+
+      if (attempt >= opts.maxAttempts - 1) break;
+      if (!isTransientError(error)) break;
+
+      let delayMs = calculateBackoff(attempt, opts);
+
+      const retryAfterMs = parseRetryAfter(error.retryAfter || error.headers?.get?.("retry-after"));
+      if (retryAfterMs) {
+        delayMs = Math.min(retryAfterMs, opts.maxBackoffMs);
+      }
+
+      if (opts.onRetry) {
+        opts.onRetry({ attempt, error, delayMs, maxAttempts: opts.maxAttempts });
+      }
+
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError;
+}