karajan-code 4.51.1 → 4.52.0

package/package.json

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

package/src/checks/release-check.js

@@ -227,11 +227,27 @@ export async function dualPublishCheck(projectDir, pkg, run = runCommand) {
   }
 }
 
+/**
+ * QS-A3 (KJC-TSK-1028): a project that carries a scenario battery
+ * (`test:scenarios`) ships only with it green. Gate clashes and holes in the
+ * plan path only show end to end, and the unit suite never runs them.
+ */
+export async function scenarioBatteryCheck(projectDir, pkg, run = runCommand) {
+  if (!pkg?.scripts?.["test:scenarios"]) return null;
+  try {
+    const res = await run("npm", ["run", "test:scenarios"], { cwd: projectDir });
+    return { name: "scenarios", ok: res.exitCode === 0, detail: res.exitCode === 0 ? "scenario battery green" : `npm run test:scenarios exited ${res.exitCode}` };
+  } catch (err) {
+    return { name: "scenarios", ok: false, detail: `npm run test:scenarios failed to run: ${err.message}` };
+  }
+}
+
 export async function runReleaseCheck({ projectDir = process.cwd(), config = {}, forCommand = null } = {}) {
   const { checks, version, pkg } = await genericChecks(projectDir);
   const pack = await packPrivacyCheck(projectDir, pkg);
   const dual = await dualPublishCheck(projectDir, pkg);
-  checks.push(...(pack ? [pack] : []), ...(dual ? [dual] : []), await policyRangeCheck(projectDir), ...await declaredItems(projectDir, config, version));
+  const scenarios = await scenarioBatteryCheck(projectDir, pkg);
+  checks.push(...[pack, dual, scenarios].filter(Boolean), await policyRangeCheck(projectDir), ...await declaredItems(projectDir, config, version));
   if (forCommand === null) return { ok: checks.every((c) => c.ok), version, checks };
   // A lifted check stays RED in the report: the fact is not falsified, it just
   // stops blocking the command that exists to repair it. The mark travels ON

package/src/cli/register-meta.js

@@ -306,6 +306,14 @@ export function registerMeta(program, { pkgVersion }) {
         await worktreeCommand({ config, action: "done", args: [slug], flags });
       });
     });
+  wt.command("prune")
+    .option("--dry-run", "List what would be retired and why, touching nothing")
+    .description("Retire kj lanes that are provably abandoned (clean, no own commits, no live process); the rest are listed with their reason")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "worktree", flags, async ({ config }) => {
+        await worktreeCommand({ config, action: "prune", flags });
+      });
+    });
 
   const hu = program.command("hu").description("Track work in the HU Board from any host agent (card first)");
   hu.command("add <title>")

package/src/commands/review-gate.js

@@ -29,6 +29,7 @@ import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
 import { loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
 import { policyFileHash, recordGateDecision } from "../policy/decisions.js";
 import { evaluatePolicyGate } from "../review/policy-gate.js";
+import { correctionNote, reviewCorrectionRounds } from "../review/correction-rounds.js";
 
 // KJC-TSK-0686 (MG-A): card-first is a gate, not a habit. Runs on --staged
 // (before spending sonar/reviewer effort) AND on --check — the pre-commit
@@ -111,11 +112,12 @@ export const formatExempted = (e) => (e.standing
   ? `⚠ policy standing [${e.rule_id}] — excepción permanente${e.standing.origin === "global" ? " GLOBAL" : ""} viva hasta ${e.standing.expiresAt} (${e.standing.justification || "sin justificación"})`
   : `⚠ policy exempt [${e.rule_id}] — excepción registrada en .karajan/policy-exceptions.jsonl (${e.justification})`);
 
-function printVerdict(record) {
+function printVerdict(record, rounds = 0) {
   if (record.verdict === "approved") {
     const ws = record.workspace ? ` [${record.workspace}]` : "";
     console.log(`✓ APPROVED by ${record.reviewer} (diff ${record.diffHash.slice(0, 12)})${ws}`);
     if (record.summary) console.log(`  ${record.summary}`);
+    if (rounds > 0) console.log(`  ${correctionNote(rounds)}`);
     return;
   }
   console.log(`✗ REJECTED by ${record.reviewer} — ${record.issues.length} blocking issue(s):`);
@@ -577,7 +579,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   }
 
   const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord, ui: uiRecord });
-  printVerdict(record);
+  printVerdict(record, record.verdict === "approved" ? await reviewCorrectionRounds(projectDir, record) : 0);
   process.exitCode = record.verdict === "approved" ? 0 : 1;
   return record;
 }

package/src/commands/worktree.js

@@ -11,13 +11,15 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { bootstrapWorktree } from "../hu/worktree-bootstrap.js";
+import { classifyLanes, liveProcesses } from "../hu/lane-prune.js";
+import { recordGateDecision } from "../policy/decisions.js";
 
 const execFileAsync = promisify(execFile);
 const WORKTREE_DIR = ".kj/worktrees"; // shared with the headless lanes
 
 const SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
-export async function worktreeCommand({ config = null, action, args = [], flags = {} }) {
+export async function worktreeCommand({ config = null, action, args = [], flags = {}, deps = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const git = (gitArgs, cwd = projectDir) => execFileAsync("git", gitArgs, { cwd });
   const lanePath = (slug) => path.join(projectDir, WORKTREE_DIR, slug);
@@ -72,5 +74,27 @@ export async function worktreeCommand({ config = null, action, args = [], flags
     return { removed: true, slug };
   }
 
-  throw new Error(`unknown action "${action}" — use: start | list | done`);
+  if (action === "prune") {
+    const { processes = liveProcesses() } = deps;
+    const lanes = await classifyLanes({ git, laneRoot: path.join(projectDir, WORKTREE_DIR), base: config?.base_branch || "main", processes, now: deps.now });
+    const abandoned = lanes.filter((l) => l.reasons.length === 0);
+    const kept = lanes.filter((l) => l.reasons.length > 0);
+    for (const l of kept) console.log(`kept    ${l.slug.padEnd(24)} ${l.reasons.join("; ")}`);
+    if (lanes.length === 0) console.log("no kj lanes");
+    if (flags.dryRun) {
+      for (const l of abandoned) console.log(`would retire ${l.slug} (${l.branch ?? "detached"})`);
+      return { wouldRemove: abandoned, kept };
+    }
+    for (const l of abandoned) {
+      await git(["worktree", "remove", l.path]);
+      if (l.branch) await git(["branch", "-D", l.branch]);
+      console.log(`✓ retired ${l.slug} (${l.branch ?? "detached"})`);
+    }
+    if (abandoned.length > 0) {
+      recordGateDecision(projectDir, { decision: "allow", chokepoint: "tool", kind: "worktree-prune", lanes: abandoned.map((l) => l.slug) });
+    }
+    return { removed: abandoned, kept };
+  }
+
+  throw new Error(`unknown action "${action}" — use: start | list | done | prune`);
 }

package/src/environment/playbook.js

@@ -70,6 +70,8 @@ Invariants (the git gates enforce these — they are not suggestions):
 - Every diff is reviewed by a DIFFERENT AI before it is committed
   (\`kj review --staged\`): verdicts bind to the exact diff — change the code
   and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.
+  A correction from the other AI is the method working: apply it and move
+  on, no apology, and never report it as your mistake.
 ${panel ? `${panel}\n` : ""}- Security findings are never overridable — not even by arbitration. You
   absorb the security role: \`kj brief security\` states what must be true.
   Task touches auth, user input, secrets, network or deps? Run

package/src/hu/lane-prune.js

@@ -0,0 +1,74 @@
+/**
+ * KJC-TSK-1036 (owner's decision, 14-oct): a lane kj created is retired only when
+ * it is provably abandoned: clean tree, no commits beyond the base, and no live
+ * process working inside it. Anything else is listed with its reason, never
+ * touched, so a session may run this without risking anyone's work.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const IDLE_HOURS = 24;
+const REGENERABLE = new Set(["node_modules", "dist", "build", "coverage", ".venv", "venv", "__pycache__", ".cache", "target"]);
+
+/**
+ * This user's live processes (another user's cannot write in our worktrees): the
+ * cwds that can be read and how many cannot (non-dumpable ones: ssh-agent, systemd,
+ * some JVMs). null when the platform has no /proc.
+ */
+export function liveProcesses() {
+  let pids;
+  try { pids = fs.readdirSync("/proc").filter((p) => /^\d+$/.test(p)); } catch { return null; }
+  const cwds = new Set();
+  let unseen = 0;
+  for (const pid of pids) {
+    try {
+      if (fs.statSync(`/proc/${pid}`).uid !== process.getuid()) continue;
+      cwds.add(fs.readlinkSync(`/proc/${pid}/cwd`));
+    } catch (err) {
+      if (err.code !== "ENOENT" && err.code !== "ESRCH") unseen += 1;
+    }
+  }
+  return { cwds, unseen };
+}
+
+/** Hours since anything in the lane moved: its dir, and its git index and HEAD. */
+async function idleHours(git, lanePath, now) {
+  const { stdout } = await git(["rev-parse", "--absolute-git-dir"], lanePath);
+  const gitDir = stdout.trim();
+  const times = [lanePath, path.join(gitDir, "index"), path.join(gitDir, "HEAD")]
+    .map((f) => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } });
+  return (now - Math.max(...times)) / 3_600_000;
+}
+
+const inside = (cwd, dir) => cwd === dir || cwd.startsWith(dir + path.sep);
+
+/** @returns {Promise<{slug: string, path: string, branch: string|null, reasons: string[]}[]>} */
+export async function classifyLanes({ git, laneRoot, base, processes, now = Date.now() }) {
+  const { stdout } = await git(["worktree", "list", "--porcelain"]);
+  const lanes = [];
+  let current = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      current = { path: line.slice(9).trim(), branch: null };
+      if (current.path.startsWith(laneRoot + path.sep)) lanes.push(current);
+    } else if (line.startsWith("branch ") && current) current.branch = line.slice(7).trim().replace("refs/heads/", "");
+  }
+  return Promise.all(lanes.map(async (lane) => {
+    const reasons = [];
+    const { stdout: status } = await git(["status", "--porcelain", "--ignored=matching"], lane.path);
+    const entries = status.split("\n").filter(Boolean);
+    if (entries.some((e) => !e.startsWith("!! "))) reasons.push("uncommitted changes");
+    // Ignored files can be valuable (.env, local artifacts); only regenerable dirs are not.
+    const precious = entries.filter((e) => e.startsWith("!! ") && !REGENERABLE.has(e.slice(3).split("/")[0]));
+    if (precious.length > 0) reasons.push(`ignored files that are not regenerable (${precious[0].slice(3)}${precious.length > 1 ? ", …" : ""})`);
+    // The lane's HEAD, branch or detached: a detached lane's commits have no other name.
+    const { stdout: ahead } = await git(["rev-list", "--count", `${base}..HEAD`], lane.path);
+    if (Number(ahead) > 0) reasons.push(`${Number(ahead)} commit(s) not in ${base}`);
+    if (processes === null) reasons.push("cannot check for live processes on this platform");
+    else if ([...processes.cwds].some((cwd) => inside(cwd, lane.path))) reasons.push("a live process works in it");
+    else if (processes.unseen > 0 && (await idleHours(git, lane.path, now)) < IDLE_HOURS) {
+      reasons.push(`${processes.unseen} process(es) of yours cannot be inspected and the lane changed in the last ${IDLE_HOURS} h`);
+    }
+    return { slug: path.basename(lane.path), path: lane.path, branch: lane.branch, reasons };
+  }));
+}

package/src/mcp/handlers/direct-handlers.js

@@ -11,7 +11,7 @@ import { createAgent } from "../../agents/index.js";
 import { buildPlannerPrompt } from "../../prompts/planner.js";
 import { buildCoderPrompt } from "../../prompts/coder.js";
 import { buildReviewerPrompt } from "../../prompts/reviewer.js";
-import { parseMaybeJsonString } from "../../review/parser.js";
+import { parseMaybeJsonString, agentAnswerText } from "../../review/parser.js";
 import { computeBaseRef, generateDiff } from "../../review/diff-generator.js";
 import { resolveReviewProfile } from "../../review/profiles.js";
 import { createRunLog } from "../../utils/run-log.js";
@@ -322,7 +322,7 @@ export async function handleReviewDirect(a, server, extra) {
   }
 
   sendTrackerLog(server, "reviewer", "done");
-  const parsed = parseMaybeJsonString(result.output);
+  const parsed = parseMaybeJsonString(agentAnswerText(result.output));
   return { ok: true, review: parsed || result.output, raw: result.output };
 }
 

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

@@ -15,6 +15,7 @@ import { invokeSolomon } from "../solomon-escalation.js";
 import { detectRateLimit } from "../../utils/rate-limit-detector.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
 import { applyQuotaSimulation } from "../../utils/quota-simulator.js";
+import { correctionNote } from "../../review/correction-rounds.js";
 
 function categorizeIssues(issues) {
   const categories = { security: 0, correctness: 0, tests: 0, style: 0, other: 0 };
@@ -33,6 +34,12 @@ function categorizeIssues(issues) {
   return categories;
 }
 
+// KJC-TSK-1017: the rejections before an approval are review corrections.
+export function approvedMessage(session) {
+  const rejections = (session.checkpoints || []).filter((cp) => cp.stage === "reviewer" && cp.approved === false).length;
+  return ["Review approved", correctionNote(rejections)].filter(Boolean).join(" — ");
+}
+
 function buildReviewHistory(session) {
   return (session.checkpoints || [])
     .filter(cp => cp.stage === "reviewer")
@@ -402,7 +409,7 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
     emitter,
     makeEvent("reviewer:end", { ...eventBase, stage: "reviewer" }, {
       status: review.approved ? "ok" : "fail",
-      message: review.approved ? "Review approved" : `Review rejected (${review.blocking_issues.length} blocking)`,
+      message: review.approved ? approvedMessage(session) : `Review rejected (${review.blocking_issues.length} blocking)`,
       detail: {
         approved: review.approved,
         blockingCount: review.blocking_issues.length,

package/src/review/correction-rounds.js

@@ -0,0 +1,40 @@
+/**
+ * KJC-TSK-1017: a rejection followed by an approval is the method working: the
+ * second AI exists to catch what the first one misses, by how models work, not
+ * because the coder did it badly. kj names it a review correction with its
+ * round count, never a coder error.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+
+export const correctionNote = (rounds) => (rounds > 0
+  ? `review correction: ${rounds} round(s) before this approval, the cross-AI method working`
+  : "");
+
+/** Rejections on the branch since its last approval, the current record aside. */
+export function rejectionsBeforeApproval(records, { branch, hash }) {
+  const mine = records
+    .filter((r) => r.branch === branch && r.diffHash !== hash)
+    .toSorted((a, b) => String(a.timestamp).localeCompare(String(b.timestamp)));
+  let rounds = 0;
+  for (const r of mine) rounds = r.verdict === "approved" ? 0 : rounds + 1;
+  return rounds;
+}
+
+export async function branchOf(projectDir, run = runCommand) {
+  const res = await run("git", ["-C", projectDir, "rev-parse", "--abbrev-ref", "HEAD"]);
+  return res.exitCode === 0 ? res.stdout.trim() : null;
+}
+
+export async function reviewCorrectionRounds(projectDir, record) {
+  if (!record?.branch) return 0;
+  const dir = path.join(projectDir, ".karajan", "reviews");
+  const names = await fs.readdir(dir).catch(() => []);
+  const records = [];
+  for (const name of names.filter((n) => n.endsWith(".json"))) {
+    // A report, not a gate: an unreadable verdict file is left out of the count.
+    try { records.push(JSON.parse(await fs.readFile(path.join(dir, name), "utf8"))); } catch { /* see above */ }
+  }
+  return rejectionsBeforeApproval(records, { branch: record.branch, hash: record.diffHash });
+}

package/src/review/one-shot-review.js

@@ -12,12 +12,13 @@ import { createAgent } from "../agents/index.js";
 import { resolveRole } from "../config/role-resolver.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveReviewProfile } from "./profiles.js";
-import { parseMaybeJsonString, normalizeReviewPayload } from "./parser.js";
+import { parseMaybeJsonString, normalizeReviewPayload, agentAnswerText } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
 import { saveVerdict, diffHash } from "./verdict-store.js";
 import { summarizeGeneratedFiles } from "./prompt-diff.js";
 import { reportUnparseableVerdict } from "./unparseable-verdict.js";
 import { detectWorkspace } from "./workspace.js";
+import { branchOf } from "./correction-rounds.js";
 import { isQuotaExhausted, candidateStatus, pickQuotaFallback, formatCandidateMenu } from "./reviewer-fallback.js";
 
 // Cross-AI preference when the configured reviewer IS the host.
@@ -116,7 +117,7 @@ export async function runOneShotReview({
   // back, wrapper and all. Yesterday's fix taught normalizeReviewPayload to unwrap {ok, result},
   // but this path never called it, so the bug survived with a green test on the wrong function.
   // A test can only prove the code it actually exercises.
-  const parsed = normalizeReviewPayload(parseMaybeJsonString(result.output));
+  const parsed = normalizeReviewPayload(parseMaybeJsonString(agentAnswerText(result.output)));
   if (!parsed || typeof parsed.approved !== "boolean") {
     // KJC-BUG-0146: keep the answer. Throwing it away is what left eight occurrences undiagnosed.
     throw new Error(await reportUnparseableVerdict({ projectDir, reviewer: activeReviewer, output: result.output, hash: diffHash(diff) }));
@@ -128,6 +129,8 @@ export async function runOneShotReview({
     host: hostAgent || null,
     // KJC-TSK-0680: where the review ran — makes any isolation claim auditable.
     workspace: await detectWorkspace(projectDir),
+    // KJC-TSK-1017: the branch lets an approval count the corrections before it.
+    branch: await branchOf(projectDir),
     issues: parsed.blocking_issues || [],
     suggestions: parsed.non_blocking_suggestions || [],
     summary: parsed.summary || parsed.raw_summary || "",

package/src/review/parser.js

@@ -10,6 +10,22 @@ export function parseMaybeJsonString(value) {
   return extractFirstJson(value);
 }
 
+/**
+ * KJC-BUG-0357 (#2151): claude's reviewTask answers with its whole stream-json
+ * event stream, which opens with hook and init events, so its first JSON is no
+ * answer. The answer is the text of the final `result` event; any other output
+ * is returned as it came.
+ */
+export function agentAnswerText(raw) {
+  if (typeof raw !== "string") return raw;
+  const lines = raw.trim().split("\n");
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const event = extractFirstJson(lines[i]);
+    if (event?.type === "result" && typeof event.result === "string") return event.result;
+  }
+  return raw;
+}
+
 function isReviewPayload(obj) {
   return obj?.approved !== undefined && obj?.blocking_issues !== undefined;
 }

package/src/review/solomon-arbitration.js

@@ -13,7 +13,7 @@
  *    reject keeps it closed. Both record the full conflict for audit.
  */
 import { createAgent } from "../agents/index.js";
-import { parseMaybeJsonString } from "./parser.js";
+import { parseMaybeJsonString, agentAnswerText } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
 import { diffHash, loadVerdict, saveVerdict } from "./verdict-store.js";
 import { summarizeGeneratedFiles } from "./prompt-diff.js";
@@ -95,7 +95,7 @@ export async function runSolomonArbitration({
       : `No other agent CLI on this machine can arbitrate (needs one distinct from brain "${hostAgent}" and reviewer "${verdict.reviewer}") — install a third agent CLI or fix ${solomon}.`;
     throw new Error(`solomon ${solomon} failed: ${String(result?.error || "no output").slice(0, 400)}\n${hint}`);
   }
-  const parsed = parseMaybeJsonString(result.output);
+  const parsed = parseMaybeJsonString(agentAnswerText(result.output));
   if (!parsed || !["approve", "reject"].includes(parsed.ruling)) {
     throw new Error(`solomon ${solomon} returned no parseable ruling`);
   }