karajan-code 3.15.2 → 3.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "3.15.2",
+  "version": "3.15.3",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -85,7 +85,8 @@
     "mcp": "node src/mcp/server.js",
     "audit:test-diet": "node scripts/audit-test-diet.mjs",
     "verify-pack": "node scripts/verify-pack.mjs",
-    "prepublishOnly": "node scripts/verify-pack.mjs"
+    "prepublishOnly": "node scripts/verify-pack.mjs",
+    "verify-quickstart": "node scripts/quickstart-gate.mjs"
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"

package/scripts/quickstart-gate.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Quickstart gate (KJC-TSK-0635) — the landing's Quick Start, end to end,
+ * against the PACKED tarball, with a REAL coder run.
+ *
+ * Run manually before a release (`npm run verify-quickstart`). Opt-in
+ * because the coder run spends real subscription quota (~$0.5-1.5, 5-8
+ * minutes). What it catches that unit tests and verify-pack cannot:
+ * the exact first-contact sequence a new user follows — install → init →
+ * `kj run` on a no-remote repo → playable artifact (2026-07-19: that
+ * sequence surfaced KJC-BUG-0111/0112/0113 in one afternoon).
+ *
+ * Asserts: run exits 0 · report says approved · index.html exists with
+ * game markers · "skipping push/PR" logged · ZERO Solomon escalations.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+const TASK = "Create a tic-tac-toe game in a single self-contained index.html — vanilla HTML, CSS and JavaScript, no server and no build step. The human plays X, the bot plays O and blocks or takes a winning move when it can. Detect wins and draws, and add a New Game button. Opening index.html in a browser must be enough to play.";
+
+function fail(msg, detail) {
+  console.error(`\n✗ quickstart-gate: ${msg}`);
+  if (detail) console.error(String(detail).slice(-1200));
+  process.exitCode = 1;
+  throw new Error(msg);
+}
+
+let work = null;
+try {
+  console.log("quickstart-gate: packing…");
+  const packOut = execFileSync("npm", ["pack", "--json", "--silent"], { cwd: repoRoot, encoding: "utf8" });
+  const tgz = path.join(repoRoot, JSON.parse(packOut)[0].filename);
+
+  work = fs.mkdtempSync(path.join(os.tmpdir(), "kj-qs-gate-"));
+  const prefix = path.join(work, "npm");
+  const project = path.join(work, "project");
+  fs.mkdirSync(project, { recursive: true });
+
+  console.log("quickstart-gate: installing the tarball (isolated prefix)…");
+  execFileSync("npm", ["install", "-g", tgz, "--no-audit", "--no-fund", "--silent", "--prefix", prefix], { encoding: "utf8" });
+  const kj = path.join(prefix, "bin", "kj");
+  fs.rmSync(tgz, { force: true });
+
+  // Isolated KARAJAN_HOME: faithful to a brand-new user (no global
+  // config) and never touches the maintainer's real ~/.karajan.
+  const env = { ...process.env, KARAJAN_HOME: path.join(work, "karajan-home") };
+  delete env.CLAUDECODE;
+  // If the maintainer's machine has a SonarQube server running, preflight
+  // (correctly) demands a token the isolated home doesn't have. Forward the
+  // maintainer's token so the gate exercises the sonar stage instead of
+  // dying in preflight. A machine with no sonar server is unaffected.
+  if (!env.KJ_SONAR_TOKEN) {
+    try {
+      const cfg = fs.readFileSync(path.join(os.homedir(), ".karajan", "kj.config.yml"), "utf8");
+      const m = cfg.match(/^\s*token:\s*(sqa_[A-Za-z0-9]+|squ_[A-Za-z0-9]+)\s*$/m);
+      if (m) env.KJ_SONAR_TOKEN = m[1];
+    } catch { /* no global config — brand-new machine, nothing to forward */ }
+  }
+
+  console.log("quickstart-gate: git init + kj init (unattended)…");
+  execFileSync("git", ["init", "-q", "-b", "main"], { cwd: project });
+  const init = spawnSync(kj, ["init", "--no-interactive", "--no-ollama", "--no-rtk", "--no-squeezr", "--no-qmd"], {
+    cwd: project, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 300000,
+  });
+  if (init.status !== 0) fail("kj init failed", init.stderr || init.stdout);
+
+  console.log("quickstart-gate: kj run (REAL coder — this spends quota, ~5-8 min)…");
+  const runRes = spawnSync(kj, ["run", "-y", TASK], {
+    cwd: project, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 20 * 60 * 1000,
+  });
+  const runOut = `${runRes.stdout || ""}${runRes.stderr || ""}`;
+  fs.writeFileSync(path.join(work, "run.log"), runOut);
+
+  if (runRes.status !== 0) fail(`kj run exited ${runRes.status} (log: ${work}/run.log)`, runOut);
+  if (/escalating to Solomon/i.test(runOut)) fail(`Solomon escalation detected — the happy path must not consult Solomon (log: ${work}/run.log)`);
+  // KJC-BUG-0112 regression: a remote-less repo must never attempt (and
+  // fail) push/fetch automation. With init's defaults (auto_push: false)
+  // the "skipping push/PR" line is legitimately absent, so assert the
+  // absence of failure symptoms rather than the presence of the skip line.
+  if (/failed to push|fatal: .*origin|couldn't find remote/i.test(runOut)) fail(`push/fetch against a missing remote detected (log: ${work}/run.log)`);
+
+  const html = path.join(project, "index.html");
+  if (!fs.existsSync(html)) fail("index.html was not created");
+  const htmlText = fs.readFileSync(html, "utf8");
+  if (!/new game/i.test(htmlText)) fail("index.html has no New Game control — not the requested game");
+
+  const report = spawnSync(kj, ["report"], { cwd: project, env, encoding: "utf8", timeout: 60000 });
+  if (!/approved/i.test(`${report.stdout || ""}`)) fail("kj report does not say approved", report.stdout);
+
+  console.log("\n✓ quickstart-gate: install → init → run → playable index.html → approved. Ship it.");
+} finally {
+  if (work && process.exitCode !== 1 && fs.existsSync(work)) fs.rmSync(work, { recursive: true, force: true });
+  if (work && process.exitCode === 1) console.error(`quickstart-gate: workdir kept for inspection: ${work}`);
+}

package/scripts/verify-pack.mjs

@@ -52,6 +52,7 @@ let tgzPath = null;
 let tmpDir = null;
 let gTmp = null;
 let pnpmTmp = null;
+let qsTmp = null;
 try {
   console.log(`verify-pack: packing karajan-code@${expectedVersion}…`);
   // --json gives us the exact filename without parsing human output.
@@ -146,6 +147,42 @@ try {
   }
   console.log(`verify-pack: global install + kj --version → ${gVersion} ✓`);
 
+  // 5.5 Quickstart smoke (KJC-TSK-0635) — the landing's Getting Started
+  // sequence against the INSTALLED tarball, no LLM involved. Born from
+  // 2026-07-19: following the docs to the letter caught 3 field bugs
+  // (silent 2.34.0 install, Solomon loop on no-remote repos, retired
+  // gemini CLI) that 6000 unit tests never saw. Aux bootstraps (ollama,
+  // rtk, squeezr, qmd, harden) are skipped — this validates kj's own
+  // init + config on the canonical no-remote scenario, not the network.
+  qsTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-qs-"));
+  console.log(`verify-pack: quickstart smoke (init on a no-remote repo) in ${qsTmp}…`);
+  run("git", ["init", "-q", "-b", "main"], { cwd: qsTmp });
+  // KARAJAN_HOME points at an isolated dir: faithful to a brand-new user
+  // (no pre-existing global config — `--local` without one is rejected by
+  // design, which is exactly what this smoke caught on its first CI run)
+  // AND hermetic (never touches the real ~/.karajan).
+  const qsEnv = { ...childEnv, KARAJAN_HOME: path.join(qsTmp, "karajan-home") };
+  delete qsEnv.CLAUDECODE;
+  const initRes = spawnSync(gBin, ["init", "--no-interactive", "--no-ollama", "--no-rtk", "--no-squeezr", "--no-qmd", "--no-harden"], {
+    encoding: "utf8", cwd: qsTmp, env: qsEnv, timeout: 180000,
+  });
+  if (initRes.status !== 0) {
+    fail("`kj init --no-interactive` failed on a fresh no-remote repo", (initRes.stderr || initRes.stdout || "").slice(-800));
+  }
+  const qsCfgLocal = path.join(qsTmp, ".karajan", "kj.config.yml");
+  const qsCfgGlobal = path.join(qsTmp, "karajan-home", "kj.config.yml");
+  const qsCfg = fs.existsSync(qsCfgLocal) ? qsCfgLocal : qsCfgGlobal;
+  if (!fs.existsSync(qsCfg)) fail(`kj init did not write ${qsCfg}`);
+  if (!/coder:\s*\S+/.test(fs.readFileSync(qsCfg, "utf8"))) {
+    fail("generated kj.config.yml has no coder assignment");
+  }
+  const reportRes = spawnSync(gBin, ["report"], { encoding: "utf8", cwd: qsTmp, env: qsEnv, timeout: 60000 });
+  const reportOut = `${reportRes.stdout || ""}${reportRes.stderr || ""}`;
+  if (reportRes.status !== 0 && !/no session|sin sesi|not found/i.test(reportOut)) {
+    fail("`kj report` crashed on a project with no sessions", reportOut.slice(-400));
+  }
+  console.log("verify-pack: quickstart smoke (init + report, no-remote repo) ✓");
+
   // 6. pnpm install smoke (KJC-TSK-0580). pnpm's layout differs from npm's
   // (a symlinked virtual store), so it can break resolution of the bundled
   // karajan-core the way npm packaging breakage did before (KJC-BUG-0082/0086).
@@ -195,4 +232,5 @@ try {
   if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
   if (gTmp && fs.existsSync(gTmp)) fs.rmSync(gTmp, { recursive: true, force: true });
   if (pnpmTmp && fs.existsSync(pnpmTmp)) fs.rmSync(pnpmTmp, { recursive: true, force: true });
+  if (qsTmp && fs.existsSync(qsTmp)) fs.rmSync(qsTmp, { recursive: true, force: true });
 }

package/src/commands/report.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { exists } from "../utils/fs.js";
 import { getSessionRoot } from "../utils/paths.js";
 import { loadConfig } from "../config.js";
+import { DEFAULTS } from "../config/defaults.js";
 
 function parseBudgetFromActivityLog(logText) {
   if (!logText) {
@@ -131,6 +132,14 @@ async function buildReport(dir, sessionId) {
 
   const sonar = summarizeSonar(checkpoints);
   const budget = parseBudgetFromActivityLog(activityLog);
+  // KJC-BUG-0114: activity logs written when max_budget_usd was null carry
+  // a phantom "$0.00" ceiling (Number(null) === 0). Resolve the effective
+  // ceiling from the session's config snapshot, falling back to the
+  // shipped default; an explicit 0 means "no ceiling" and drops the suffix.
+  if (budget.limit_usd === 0) {
+    const snapBudget = session.config_snapshot?.max_budget_usd;
+    budget.limit_usd = snapBudget == null ? DEFAULTS.max_budget_usd : (Number(snapBudget) || null);
+  }
   const commits = summarizeCommits(session, checkpoints);
 
   const budgetTrace = Array.isArray(session.budget?.trace) ? session.budget.trace : [];

package/src/orchestrator/config-init.js

@@ -12,6 +12,7 @@ import { resolveRole } from "../config.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { getTemplatesRoot } from "../utils/templates-root.js";
 import { BudgetTracker, extractUsageMetrics } from "../utils/budget.js";
+import { DEFAULTS } from "../config/defaults.js";
 import { computeKjComparison } from "../budget/comparison.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { projectSlug } from "../plan/plan-store.js";
@@ -303,8 +304,13 @@ export async function handleDryRun({ task, config, flags, emitter, pipelineFlags
 
 export function createBudgetManager({ config, emitter, eventBase, getCompressionStats = null }) {
   const budgetTracker = new BudgetTracker({ pricing: config?.budget?.pricing });
-  const budgetLimit = Number(config?.max_budget_usd);
-  const hasBudgetLimit = Number.isFinite(budgetLimit) && budgetLimit >= 0;
+  // KJC-BUG-0114: Number(null) === 0, so a config that reached us with
+  // max_budget_usd: null produced a phantom "$X / $0.00" ceiling (and a
+  // permanent warn state). null/undefined fall back to the shipped
+  // default ceiling; an explicit 0 means "no ceiling".
+  const rawBudget = config?.max_budget_usd;
+  const budgetLimit = rawBudget == null ? DEFAULTS.max_budget_usd : Number(rawBudget);
+  const hasBudgetLimit = Number.isFinite(budgetLimit) && budgetLimit > 0;
   const warnThresholdPct = Number(config?.budget?.warn_threshold_pct ?? 80);
   let stageCounter = 0;
 

package/src/orchestrator/drivers/init-context.js

@@ -21,9 +21,8 @@ import { prepareGitAutomation } from "../../git/automation.js";
 import { CoderRole } from "../../roles/coder-role.js";
 import { PipelineContext } from "../pipeline-context.js";
 import { detectRtk } from "../../utils/rtk-detect.js";
-import { createRtkRunner, RtkSavingsTracker } from "../../utils/rtk-wrapper.js";
-import { setRunner as setDiffRunner, setProjectDir as setDiffProjectDir } from "../../review/diff-generator.js";
-import { setRunner as setGitRunner } from "../../utils/git.js";
+import { RtkSavingsTracker } from "../../utils/rtk-wrapper.js";
+import { setProjectDir as setDiffProjectDir } from "../../review/diff-generator.js";
 import {
   loadProductContext, resolvePipelineFlags, createBudgetManager,
   initializeSession, autoInit,
@@ -116,19 +115,19 @@ export async function initFlowContext({ task, config, logger, emitter, askQuesti
   const rtkResult = await detectRtk();
   if (rtkResult.available) {
     config = { ...config, rtk: { available: true, version: rtkResult.version } };
-    const rtkTracker = new RtkSavingsTracker();
-    const rtkRunner = createRtkRunner(true, rtkTracker);
-    // TSK-0338: install rtkRunner into the per-run context; module-level
-    // setters are the back-compat path for runs outside a withRunContext scope.
-    if (runCtx) runCtx.runner = rtkRunner;
-    else {
-      setDiffRunner(rtkRunner);
-      setGitRunner(rtkRunner);
-    }
-    ctx.rtkTracker = rtkTracker;
-    logger.info(`RTK detected (${rtkResult.version}) — wrapping internal git/diff commands with rtk`);
+    // KJC-BUG-0115: rtk MUST NOT wrap the pipeline's internal git/diff
+    // commands. `rtk git diff` emits a compressed summary without
+    // `diff --git` headers, so every consumer that parses the output
+    // (tdd-policy extractChangedFiles, reviewer diffs, status checks)
+    // sees an empty change set — in the field this made the TDD gate
+    // fail forever with "(2 src, 0 test)" while real tests existed.
+    // RTK still saves tokens where it belongs: inside the coder agent's
+    // own shell, via its Claude Code hook. Detection is kept so the
+    // config advertises availability to agents.
+    ctx.rtkTracker = new RtkSavingsTracker();
+    logger.info(`RTK detected (${rtkResult.version}) — available to agents (internal git/diff stay unwrapped)`);
     emitProgress(emitter, makeEvent("rtk:detected", ctx.eventBase, {
-      message: "RTK detected — internal commands wrapped for token optimization",
+      message: "RTK detected — available to agents",
       detail: { version: rtkResult.version, executorType: "local" }
     }));
   }

package/src/orchestrator/drivers/iteration-loop.js

@@ -253,6 +253,7 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
     }
     if (iterResult.action === "retry") { i -= 1; }
     else {
+      await ensureIterationRecorded(ctx, i, logger);
       // Iteration gate (KJC-TSK-0628): opt-in pause with a report before the
       // next iteration; free-text answers become directives for the coder.
       const gate = await handleIterationGate({
@@ -306,6 +307,7 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
       if (iterResult.action === "return") return iterResult.result;
       if (iterResult.action === "retry") { i -= 1; }
       else {
+        await ensureIterationRecorded(ctx, i, logger);
         // Same iteration gate on Solomon-extended iterations (KJC-TSK-0628).
         const gate = await handleIterationGate({
           enabled: ctx.config.session?.iteration_gate === true,
@@ -323,9 +325,56 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
 
     // Extended iterations also exhausted — final Solomon call
     const finalResult = await handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config: ctx.config, stageResults: ctx.stageResults, logger, askQuestion, task: loopTask, rtkTracker: ctx.rtkTracker, brainCtx: ctx.brainCtx });
-    return finalResult;
+    return finalizeMaxIterationsApproval(ctx, finalResult, { task: loopTask, askQuestion, emitter, logger, i });
   }
 
-  return maxIterResult;
+  return finalizeMaxIterationsApproval(ctx, maxIterResult, { task: loopTask, askQuestion, emitter, logger, i });
+}
+
+// KJC-BUG-0117: iterations that end before the reviewer (TDD/sonar
+// "continue", guard retries) never reached the recordIteration call at
+// the end of runSingleIteration, so session._journalIterations stayed
+// empty and the journal read "Iterations: 0" after a 5-iteration run.
+export async function ensureIterationRecorded(ctx, i, logger) {
+  if (!ctx.journalIterations) return;
+  if ((ctx.session._journalIterations?.length || 0) >= i) return;
+  try {
+    const { recordIteration, extractIterationData } = await import("../../session/journal/iteration-logger.js");
+    recordIteration(ctx.session, extractIterationData({
+      iteration: i, durationMs: 0, stageResults: ctx.stageResults, session: ctx.session,
+    }));
+  } catch (err) {
+    logger.warn(`Iteration journal record failed (non-blocking): ${err.message}`);
+  }
+}
+
+// KJC-BUG-0116: an "approved" verdict at max_iterations (brain_approved,
+// brain_solomon_approved, solomon_approved) used to be returned as-is,
+// skipping the entire post-loop (tester/security/audit) AND git
+// automation (push/PR) that every reviewer-approved session gets — the
+// session read "approved" with zero verification and zero push. Route it
+// through the same handleApprovedReview path instead.
+export async function finalizeMaxIterationsApproval(ctx, maxIterResult, { task, askQuestion, emitter, logger, i }) {
+  if (maxIterResult?.approved !== true) return maxIterResult;
+
+  const review = {
+    approved: true,
+    raw_summary: `Finalized at max_iterations (${maxIterResult.reason || "approved"})`,
+    blocking_issues: []
+  };
+  const fin = await handleApprovedReview({
+    config: ctx.config, session: ctx.session, emitter, eventBase: ctx.eventBase,
+    coderRole: ctx.coderRole, trackBudget: ctx.trackBudget, i, task,
+    stageResults: ctx.stageResults, pipelineFlags: ctx.pipelineFlags, askQuestion, logger,
+    gitCtx: ctx.gitCtx, budgetSummary: ctx.budgetSummary, pgCard: ctx.pgCard, pgProject: ctx.pgProject,
+    review, rtkTracker: ctx.rtkTracker, brainCtx: ctx.brainCtx
+  });
+  if (fin.action === "return") return fin.result;
+
+  // Post-loop demanded another coder pass but iterations are exhausted —
+  // report honestly instead of a false green.
+  logger.warn("Post-loop stages rejected the work at max_iterations — session NOT approved");
+  await markSessionStatus(ctx.session, "failed");
+  return { approved: false, sessionId: ctx.session.id, reason: "post_loop_rejected_at_max_iterations" };
 }
 

package/src/orchestrator/stages/coder-stage.js

@@ -389,16 +389,19 @@ async function handleTddFailure({ tddEval, config, logger, emitter, eventBase, s
     return { action: "continue" };
   }
 
-  // Brain: when enabled, skip Solomon — Brain handles via max_iterations
+  // Brain: at the sub-loop limit the TDD gate must stop eating iterations.
+  // KJC-BUG-0115: returning "continue" here short-circuited runSingleIteration
+  // before the reviewer gate — 5/5 iterations ended without any review. The
+  // failure is already queued as feedback; "proceed" lets the reviewer run.
   if (brainCtx?.enabled) {
-    logger.info("Brain: TDD sub-loop limit reached — Brain will handle via max_iterations (Solomon bypassed)");
+    logger.info("Brain: TDD sub-loop limit reached — proceeding to reviewer with TDD failure as pending feedback");
     emitProgress(emitter, makeEvent("brain:tdd-retry-limit", { ...eventBase, stage: "tdd" }, {
-      message: `TDD sub-loop limit reached (${session.repeated_issue_count}/${config.session.fail_fast_repeats}) — Brain handling`,
+      message: `TDD sub-loop limit reached (${session.repeated_issue_count}/${config.session.fail_fast_repeats}) — proceeding to reviewer`,
       detail: { subloop: "tdd", retryCount: session.repeated_issue_count, reason: tddEval.reason }
     }));
     resetRetryCount(session, "repeated_issue");
     await saveSession(session);
-    return { action: "continue" };
+    return { action: "proceed" };
   }
 
   emitProgress(

package/src/utils/role-assigner.js

@@ -15,7 +15,13 @@ const CAPABILITY_TIERS = {
 // Role requirements: what capability level is ideal for each role
 const ROLE_PREFERENCES = {
   brain: { minTier: 4, prefer: "claude", description: "Karajan Brain (orchestrator)" },
-  solomon: { minTier: 3, prefer: "gemini", description: "Solomon (judge/arbiter)" },
+  // KJC-BUG-0113: Solomon preferred gemini, but Google retired the Gemini
+  // Code Assist CLI for individuals — a binary that answers --version yet
+  // dies with IneligibleTierError on every real call. Any machine with the
+  // stale CLI on PATH got a judge that could never rule. Claude matches
+  // the brain default; diversifyReviewer still picks a different agent
+  // when more than one healthy option exists.
+  solomon: { minTier: 3, prefer: "claude", description: "Solomon (judge/arbiter)" },
   coder: { minTier: 2, prefer: "claude", description: "Coder" },
   reviewer: { minTier: 3, prefer: "codex", description: "Reviewer" },
   planner: { minTier: 4, prefer: "claude", description: "Planner" },