karajan-code 1.31.0 → 1.32.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/karajan-code-logo-small.png" alt="Karajan Code" width="200">
+  <img src="docs/karajan-code-logo.svg" alt="Karajan Code" width="180">
 </p>
 
 <h1 align="center">Karajan Code</h1>
@@ -46,6 +46,7 @@ Use Karajan when you want:
 - **Zero-config operation** — auto-detects test frameworks, starts SonarQube, simplifies pipeline for trivial tasks
 - **Composable role architecture** — define agent behaviors as plain markdown files that travel with your project
 - **Local-first** — your code, your keys, your machine, no data leaves unless you say so
+- **Zero API costs** — Karajan uses AI agent CLIs (Claude Code, Codex, Gemini CLI), not APIs. You pay your existing subscription (Claude Pro, ChatGPT Plus), not per-token API fees. No surprise bills.
 
 If Claude Code is a smart pair programmer, Karajan is the CI/CD pipeline for AI-assisted development. They work great together — Karajan is designed to be used as an MCP server inside Claude Code.
 
@@ -64,6 +65,8 @@ That's it. No Docker required (SonarQube uses Docker, but Karajan auto-manages i
 kj run "Create a utility function that validates Spanish DNI numbers, with tests"
 ```
 
+[**▶ Watch the full pipeline demo**](https://karajancode.com#demo) — HU certification, triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.
+
 Karajan will:
 1. Triage the task complexity and activate the right roles
 2. Write tests first (TDD)

package/package.json

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

package/src/agents/resolve-bin.js

@@ -10,6 +10,7 @@ const SEARCH_DIRS = [
   path.join(os.homedir(), ".npm-global", "bin"),
   "/usr/local/bin",
   path.join(os.homedir(), ".local", "bin"),
+  path.join(os.homedir(), ".opencode", "bin"),
 ];
 
 function getNvmDirs() {

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

@@ -1,6 +1,7 @@
 import { TesterRole } from "../roles/tester-role.js";
 import { SecurityRole } from "../roles/security-role.js";
 import { ImpeccableRole } from "../roles/impeccable-role.js";
+import { AuditRole } from "../roles/audit-role.js";
 import { addCheckpoint, saveSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { invokeSolomon } from "./solomon-escalation.js";
@@ -134,36 +135,18 @@ export async function runTesterStage({ config, logger, emitter, eventBase, sessi
   );
 
   if (!testerOutput.ok) {
-    const maxTesterRetries = config.session?.max_tester_retries ?? 1;
-    session.tester_retry_count = (session.tester_retry_count || 0) + 1;
-    await saveSession(session);
-
-    if (session.tester_retry_count >= maxTesterRetries) {
-      const solomonResult = await invokeSolomon({
-        config, logger, emitter, eventBase, stage: "tester", askQuestion, session, iteration,
-        conflict: {
-          stage: "tester",
-          task,
-          diff,
-          iterationCount: session.tester_retry_count,
-          maxIterations: maxTesterRetries,
-          history: [{ agent: "tester", feedback: testerOutput.summary }]
-        }
-      });
-
-      if (solomonResult.action === "pause") {
-        return { action: "pause", result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "tester_fail_fast" } };
-      }
-      if (solomonResult.action === "subtask") {
-        return { action: "pause", result: { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "tester_subtask" } };
-      }
-      // Solomon approved — proceed to next stage
-      return { action: "ok" };
-    }
-
-    session.last_reviewer_feedback = `Tester feedback: ${testerOutput.summary}`;
-    await saveSession(session);
-    return { action: "continue" };
+    // Tester findings are advisory when reviewer already approved.
+    // Auto-continue with a warning — no human escalation needed.
+    logger.warn(`Tester failed (advisory): ${testerOutput.summary}`);
+    emitProgress(
+      emitter,
+      makeEvent("tester:auto-continue", { ...eventBase, stage: "tester" }, {
+        status: "warn",
+        message: `Tester issues are advisory (reviewer approved), continuing: ${testerOutput.summary}`,
+        detail: { summary: testerOutput.summary, auto_continued: true }
+      })
+    );
+    return { action: "ok", stageResult: { ok: false, summary: testerOutput.summary || "Tester issues (advisory)", auto_continued: true } };
   }
 
   session.tester_retry_count = 0;
@@ -212,36 +195,46 @@ export async function runSecurityStage({ config, logger, emitter, eventBase, ses
   );
 
   if (!securityOutput.ok) {
-    const maxSecurityRetries = config.session?.max_security_retries ?? 1;
-    session.security_retry_count = (session.security_retry_count || 0) + 1;
-    await saveSession(session);
-
-    if (session.security_retry_count >= maxSecurityRetries) {
+    // Check if the security finding is critical (SQL injection, RCE, auth bypass, etc.)
+    const summary = (securityOutput.summary || "").toLowerCase();
+    const criticalPatterns = ["injection", "rce", "remote code", "auth bypass", "authentication bypass", "privilege escalation", "credentials exposed", "secret", "critical vulnerability"];
+    const isCritical = criticalPatterns.some((p) => summary.includes(p));
+
+    if (isCritical) {
+      // Critical security issue — escalate to Solomon/human
+      logger.warn(`Critical security finding — escalating: ${securityOutput.summary}`);
       const solomonResult = await invokeSolomon({
         config, logger, emitter, eventBase, stage: "security", askQuestion, session, iteration,
         conflict: {
           stage: "security",
           task,
           diff,
-          iterationCount: session.security_retry_count,
-          maxIterations: maxSecurityRetries,
+          iterationCount: 1,
+          maxIterations: 1,
           history: [{ agent: "security", feedback: securityOutput.summary }]
         }
       });
 
       if (solomonResult.action === "pause") {
-        return { action: "pause", result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "security_fail_fast" } };
+        return { action: "pause", result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "security_critical" } };
       }
       if (solomonResult.action === "subtask") {
         return { action: "pause", result: { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "security_subtask" } };
       }
-      // Solomon approved — proceed
       return { action: "ok" };
     }
 
-    session.last_reviewer_feedback = `Security feedback: ${securityOutput.summary}`;
-    await saveSession(session);
-    return { action: "continue" };
+    // Non-critical security findings are advisory when reviewer already approved.
+    logger.warn(`Security failed (advisory): ${securityOutput.summary}`);
+    emitProgress(
+      emitter,
+      makeEvent("security:auto-continue", { ...eventBase, stage: "security" }, {
+        status: "warn",
+        message: `Security issues are advisory (reviewer approved), continuing: ${securityOutput.summary}`,
+        detail: { summary: securityOutput.summary, auto_continued: true }
+      })
+    );
+    return { action: "ok", stageResult: { ok: false, summary: securityOutput.summary || "Security issues (advisory)", auto_continued: true } };
   }
 
   session.security_retry_count = 0;
@@ -298,5 +291,113 @@ export async function runImpeccableStage({ config, logger, emitter, eventBase, s
   return { action: "ok", stageResult: { ok: impeccableOutput.ok, verdict, summary: impeccableOutput.summary || "No frontend design issues found" } };
 }
 
+export async function runFinalAuditStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff }) {
+  logger.setContext({ iteration, stage: "audit" });
+  emitProgress(
+    emitter,
+    makeEvent("audit:start", { ...eventBase, stage: "audit" }, {
+      message: "Final audit — verifying code quality"
+    })
+  );
+
+  const auditStart = Date.now();
+  const { output: auditOutput, provider, attempts } = await runRoleWithFallback(
+    AuditRole,
+    { roleName: "audit", config, logger, emitter, eventBase, task, iteration, diff }
+  );
+  const totalDuration = Date.now() - auditStart;
+
+  trackBudget({
+    role: "audit",
+    provider: provider || coderRole.provider,
+    model: config?.roles?.audit?.model || coderRole.model,
+    result: auditOutput,
+    duration_ms: totalDuration
+  });
+
+  await addCheckpoint(session, {
+    stage: "audit",
+    iteration,
+    ok: auditOutput.ok,
+    provider: provider || coderRole.provider,
+    model: config?.roles?.audit?.model || coderRole.model || null,
+    attempts: attempts.length > 1 ? attempts : undefined
+  });
+
+  if (!auditOutput.ok) {
+    // Audit agent failed to run — treat as advisory, don't block pipeline
+    logger.warn(`Audit agent error (advisory): ${auditOutput.summary}`);
+    emitProgress(
+      emitter,
+      makeEvent("audit:end", { ...eventBase, stage: "audit" }, {
+        status: "warn",
+        message: `Audit: agent error (advisory), continuing — ${auditOutput.summary}`
+      })
+    );
+    return { action: "ok", stageResult: { ok: false, summary: auditOutput.summary || "Audit agent error (advisory)", auto_continued: true } };
+  }
+
+  // Parse findings from audit result
+  const result = auditOutput.result || {};
+  const summary = result.summary || {};
+  const overallHealth = summary.overallHealth || "fair";
+  const criticalCount = summary.critical || 0;
+  const highCount = summary.high || 0;
+
+  // Collect critical and high findings for feedback
+  const actionableFindings = [];
+  if (result.dimensions) {
+    for (const [dimName, dim] of Object.entries(result.dimensions)) {
+      for (const finding of (dim.findings || [])) {
+        if (finding.severity === "critical" || finding.severity === "high") {
+          actionableFindings.push({
+            dimension: dimName,
+            ...finding
+          });
+        }
+      }
+    }
+  }
+
+  const hasActionableIssues = (overallHealth === "poor" || overallHealth === "critical") && (criticalCount > 0 || highCount > 0);
+
+  if (hasActionableIssues) {
+    // Build feedback string for the coder
+    const feedbackLines = actionableFindings.map(f => {
+      const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+      return `[${f.severity.toUpperCase()}] ${loc} ${f.description}${f.recommendation ? ` — Fix: ${f.recommendation}` : ""}`;
+    });
+    const feedback = `Audit found ${criticalCount + highCount} critical/high issue(s) that must be fixed:\n${feedbackLines.join("\n")}`;
+
+    logger.warn(`Audit: ${criticalCount + highCount} actionable issues found, sending back to coder`);
+    emitProgress(
+      emitter,
+      makeEvent("audit:end", { ...eventBase, stage: "audit" }, {
+        status: "fail",
+        message: `Audit: ${criticalCount + highCount} issue(s) found, sending back to coder`
+      })
+    );
+
+    return { action: "retry", feedback, stageResult: { ok: false, summary: auditOutput.summary || `${criticalCount + highCount} actionable issues` } };
+  }
+
+  // Audit passed (good/fair or no critical/high findings)
+  const hasAdvisory = (summary.medium || 0) + (summary.low || 0) > 0;
+  const certifiedMsg = hasAdvisory
+    ? `Audit: CERTIFIED (with ${(summary.medium || 0) + (summary.low || 0)} advisory warning(s))`
+    : "Audit: CERTIFIED";
+
+  logger.info(certifiedMsg);
+  emitProgress(
+    emitter,
+    makeEvent("audit:end", { ...eventBase, stage: "audit" }, {
+      status: "ok",
+      message: certifiedMsg
+    })
+  );
+
+  return { action: "ok", stageResult: { ok: true, summary: certifiedMsg } };
+}
+
 // Exported for testing
 export { buildFallbackChain, isAgentFailure, runRoleWithFallback };

package/src/orchestrator.js

@@ -32,7 +32,7 @@ import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
 import { PipelineContext } from "./orchestrator/pipeline-context.js";
 import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage, runHuReviewerStage } from "./orchestrator/pre-loop-stages.js";
 import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runSonarCloudStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
-import { runTesterStage, runSecurityStage, runImpeccableStage } from "./orchestrator/post-loop-stages.js";
+import { runTesterStage, runSecurityStage, runImpeccableStage, runFinalAuditStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 import { detectTestFramework } from "./utils/project-detect.js";
 import { runPreflightChecks } from "./orchestrator/preflight-checks.js";
@@ -313,22 +313,60 @@ async function tryBecariaComment({ config, session, logger, agent, body }) {
   } catch { /* non-blocking */ }
 }
 
-async function handleCheckpoint({ checkpointDisabled, askQuestion, lastCheckpointAt, checkpointIntervalMs, elapsedMinutes, i, config, budgetTracker, stageResults, emitter, eventBase, session, budgetSummary }) {
+function detectCheckpointProgress(session, lastCheckpointSnapshot) {
+  if (!lastCheckpointSnapshot) return true; // First checkpoint — assume progress
+  const currentIteration = session.reviewer_retry_count ?? 0;
+  const currentStages = Object.keys(session.resolved_policies || {}).length;
+  const currentCheckpoints = (session.checkpoints || []).length;
+
+  const iterationAdvanced = currentIteration !== lastCheckpointSnapshot.iteration;
+  const stagesChanged = currentStages !== lastCheckpointSnapshot.stagesCount;
+  const checkpointsChanged = currentCheckpoints !== lastCheckpointSnapshot.checkpointsCount;
+
+  return iterationAdvanced || stagesChanged || checkpointsChanged;
+}
+
+function takeCheckpointSnapshot(session) {
+  return {
+    iteration: session.reviewer_retry_count ?? 0,
+    stagesCount: Object.keys(session.resolved_policies || {}).length,
+    checkpointsCount: (session.checkpoints || []).length
+  };
+}
+
+async function handleCheckpoint({ checkpointDisabled, askQuestion, lastCheckpointAt, checkpointIntervalMs, elapsedMinutes, i, config, budgetTracker, stageResults, emitter, eventBase, session, budgetSummary, lastCheckpointSnapshot }) {
   if (checkpointDisabled || !askQuestion || (Date.now() - lastCheckpointAt) < checkpointIntervalMs) {
-    return { action: "continue_loop", checkpointDisabled, lastCheckpointAt };
+    return { action: "continue_loop", checkpointDisabled, lastCheckpointAt, lastCheckpointSnapshot };
   }
 
   const elapsedStr = elapsedMinutes.toFixed(1);
+  const stagesCompleted = Object.keys(stageResults).join(", ") || "none";
+
+  // Auto-continue if progress detected since last checkpoint
+  const hasProgress = detectCheckpointProgress(session, lastCheckpointSnapshot);
+  const newSnapshot = takeCheckpointSnapshot(session);
+
+  if (hasProgress) {
+    emitProgress(
+      emitter,
+      makeEvent("session:checkpoint", { ...eventBase, iteration: i, stage: "checkpoint" }, {
+        message: `Checkpoint: progress detected, continuing (${elapsedStr} min elapsed)`,
+        detail: { elapsed_minutes: Number(elapsedStr), iterations_done: i - 1, stages: stagesCompleted, auto_continued: true }
+      })
+    );
+    return { action: "continue_loop", checkpointDisabled, lastCheckpointAt: Date.now(), lastCheckpointSnapshot: newSnapshot };
+  }
+
+  // No progress — ask human
   const iterInfo = `${i - 1}/${config.max_iterations} iterations completed`;
   const budgetInfo = budgetTracker.total().cost_usd > 0 ? ` | Budget: $${budgetTracker.total().cost_usd.toFixed(2)}` : "";
-  const stagesCompleted = Object.keys(stageResults).join(", ") || "none";
-  const checkpointMsg = `Checkpoint — ${elapsedStr} min elapsed | ${iterInfo}${budgetInfo} | Stages completed: ${stagesCompleted}. What would you like to do?`;
+  const checkpointMsg = `Checkpoint — ${elapsedStr} min elapsed | ${iterInfo}${budgetInfo} | Stages completed: ${stagesCompleted}. No progress since last checkpoint. What would you like to do?`;
 
   emitProgress(
     emitter,
     makeEvent("session:checkpoint", { ...eventBase, iteration: i, stage: "checkpoint" }, {
-      message: `Interactive checkpoint at ${elapsedStr} min`,
-      detail: { elapsed_minutes: Number(elapsedStr), iterations_done: i - 1, stages: stagesCompleted }
+      message: `Interactive checkpoint at ${elapsedStr} min (stalled)`,
+      detail: { elapsed_minutes: Number(elapsedStr), iterations_done: i - 1, stages: stagesCompleted, auto_continued: false }
     })
   );
 
@@ -354,7 +392,9 @@ async function handleCheckpoint({ checkpointDisabled, askQuestion, lastCheckpoin
     return { action: "stop", result: { approved: false, sessionId: session.id, reason: "user_stopped", elapsed_minutes: Number(elapsedStr) } };
   }
 
-  return parseCheckpointAnswer({ trimmedAnswer, checkpointDisabled, config });
+  const parsed = parseCheckpointAnswer({ trimmedAnswer, checkpointDisabled, config });
+  parsed.lastCheckpointSnapshot = newSnapshot;
+  return parsed;
 }
 
 function parseCheckpointAnswer({ trimmedAnswer, checkpointDisabled, config }) {
@@ -629,6 +669,22 @@ async function handlePostLoopStages({ config, session, emitter, eventBase, coder
     }
   }
 
+  // Final audit — last quality gate before declaring success
+  const auditResult = await runFinalAuditStage({
+    config, logger, emitter, eventBase, session, coderRole, trackBudget,
+    iteration: i, task, diff: postLoopDiff
+  });
+  if (auditResult.stageResult) {
+    stageResults.audit = auditResult.stageResult;
+    await tryBecariaComment({ config, session, logger, agent: "Audit", body: `Final audit: ${auditResult.stageResult.summary || "completed"}` });
+  }
+  if (auditResult.action === "retry") {
+    // Audit found actionable issues — loop back to coder
+    session.last_reviewer_feedback = auditResult.feedback;
+    await saveSession(session);
+    return { action: "continue" };
+  }
+
   return { action: "proceed" };
 }
 
@@ -1159,6 +1215,7 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   const checkpointIntervalMs = (ctx.config.session.checkpoint_interval_minutes ?? 5) * 60 * 1000;
   let lastCheckpointAt = Date.now();
   let checkpointDisabled = false;
+  let lastCheckpointSnapshot = takeCheckpointSnapshot(ctx.session);
 
   let i = 0;
   while (i < ctx.config.max_iterations) {
@@ -1167,11 +1224,12 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
 
     const cpResult = await handleCheckpoint({
       checkpointDisabled, askQuestion, lastCheckpointAt, checkpointIntervalMs, elapsedMinutes,
-      i, config: ctx.config, budgetTracker: ctx.budgetTracker, stageResults: ctx.stageResults, emitter, eventBase: ctx.eventBase, session: ctx.session, budgetSummary: ctx.budgetSummary
+      i, config: ctx.config, budgetTracker: ctx.budgetTracker, stageResults: ctx.stageResults, emitter, eventBase: ctx.eventBase, session: ctx.session, budgetSummary: ctx.budgetSummary, lastCheckpointSnapshot
     });
     if (cpResult.action === "stop") return cpResult.result;
     checkpointDisabled = cpResult.checkpointDisabled;
     lastCheckpointAt = cpResult.lastCheckpointAt;
+    if (cpResult.lastCheckpointSnapshot !== undefined) lastCheckpointSnapshot = cpResult.lastCheckpointSnapshot;
 
     await checkSessionTimeout({ askQuestion, elapsedMinutes, config: ctx.config, session: ctx.session, emitter, eventBase: ctx.eventBase, i, budgetSummary: ctx.budgetSummary });
     await checkBudgetExceeded({ budgetTracker: ctx.budgetTracker, config: ctx.config, session: ctx.session, emitter, eventBase: ctx.eventBase, i, budgetLimit: ctx.budgetLimit, budgetSummary: ctx.budgetSummary });

package/src/utils/agent-detect.js

@@ -4,7 +4,7 @@ import { resolveBin } from "../agents/resolve-bin.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 @anthropic-ai/gemini-code (or check Gemini CLI docs)" },
+  { 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)" }
 ];

package/src/utils/budget.js

@@ -121,6 +121,10 @@ export class BudgetTracker {
     return this.total().cost_usd > n;
   }
 
+  hasUsageData() {
+    return this.entries.length > 0 && (this.total().tokens_in > 0 || this.total().tokens_out > 0 || this.total().cost_usd > 0);
+  }
+
   summary() {
     const totals = this.total();
     const byRole = {};
@@ -133,7 +137,8 @@ export class BudgetTracker {
       total_tokens: totals.tokens_in + totals.tokens_out,
       total_cost_usd: totals.cost_usd,
       breakdown_by_role: byRole,
-      entries: [...this.entries]
+      entries: [...this.entries],
+      usage_available: this.hasUsageData()
     };
   }
 

package/src/utils/display.js

@@ -221,6 +221,10 @@ function printSessionGit(git) {
 
 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)) {
+    console.log(`  ${ANSI.dim}\ud83d\udcb0 Budget: N/A (provider does not report usage)${ANSI.reset}`);
+    return;
+  }
   console.log(`  ${ANSI.dim}\ud83d\udcb0 Total tokens: ${budget.total_tokens ?? 0}${ANSI.reset}`);
   console.log(`  ${ANSI.dim}\ud83d\udcb0 Total cost: $${Number(budget.total_cost_usd || 0).toFixed(2)}${ANSI.reset}`);
   for (const [role, metrics] of Object.entries(budget.breakdown_by_role || {})) {
@@ -376,9 +380,15 @@ 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;
+    if (hasEntries && totalTokens === 0 && total === 0) {
+      console.log(`  \u251c\u2500 ${icon} Budget: ${ANSI.dim}N/A (provider does not report usage)${ANSI.reset}`);
+      return;
+    }
     const color = budgetColor(max, pct, warn);
     if (Number.isFinite(max) && max >= 0) {
       console.log(`  \u251c\u2500 ${icon} Budget: ${color}$${total.toFixed(2)} / $${max.toFixed(2)} (${pct.toFixed(1)}%)${ANSI.reset}`);

package/src/utils/wizard.js

@@ -1,7 +1,7 @@
 import readline from "node:readline";
 
 export function createWizard(input = process.stdin, output = process.stdout) {
-  const rl = readline.createInterface({ input, output });
+  const rl = readline.createInterface({ input, output, terminal: false });
 
   function ask(question) {
     return new Promise((resolve) => {