karajan-code 3.4.0 → 3.4.1

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.4.0 released** — Cache-friendly prompts (epic KJC-PCS-0057 / Phase 1 closed). Every Karajan prompt is now split into a stable block (identical across iterations and HUs, rendered first so automatic prefix caching hits on it) and a volatile tail; on Claude the stable block ships via `--append-system-prompt` so the CLI's cache breakpoints serve it from cache on every call. Real data: cold-run cache_pct jumps **47.2% → 99.6%** and coder cost drops **76%** ($0.61 → $0.14 per HU). A prefix-stability regression suite freezes the contract in CI. Drop-in upgrade from v3.3.0. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.4.1 released** — Post-Phase-1 hardening. The session journal (Cache hits, budget, commits) is now written on EVERY run ending — not just approved ones; the audit role reports its cached tokens (it was the most expensive role and reported 0); and a new preflight check fails fast with an actionable message when Sonar cannot derive a project key, instead of burning coder iterations and dying in `sonar_repeat`. Plus the top of the v3.4.0 self-audit: shared `escapeRegExp()`, 23 dead exports pruned, 4 complex regexes decomposed, and the HU Board API with zero sync fs calls + mtime-cached plan scans. Full notes in [CHANGELOG.md](CHANGELOG.md).
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 

package/package.json

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

package/packages/hu-board/src/routes/api.js

@@ -1,5 +1,26 @@
 import { Router } from 'express';
 import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+
+/** Async existence probe (KJC-TSK-0539 — no sync fs in handlers). */
+const pathExists = (p) => fsp.access(p).then(() => true, () => false);
+
+/**
+ * mtime-keyed cache for parsed plan JSON (KJC-TSK-0539). The plan scans
+ * used to re-read and re-parse every plan file on EVERY request; with N
+ * plans and the board polling, that was O(N) parses per poll. The cache
+ * serves the parsed object while the file's mtime is unchanged and
+ * re-reads transparently when kj writes the plan.
+ */
+const planFileCache = new Map();
+export async function readPlanCached(p) {
+  const { mtimeMs } = await fsp.stat(p);
+  const hit = planFileCache.get(p);
+  if (hit && hit.mtimeMs === mtimeMs) return hit.plan;
+  const plan = JSON.parse(await fsp.readFile(p, 'utf8'));
+  planFileCache.set(p, { mtimeMs, plan });
+  return plan;
+}
 import os from 'node:os';
 import path from 'node:path';
 import { spawn as spawnChild } from 'node:child_process';
@@ -74,10 +95,10 @@ function huStoriesDir() {
 /**
  * Best-effort removal of the hu-stories/<id>/ directory.
  */
-function removeBatchDir(batchId) {
+async function removeBatchDir(batchId) {
   try {
     const dir = path.join(huStoriesDir(), batchId);
-    fs.rmSync(dir, { recursive: true, force: true });
+    await fsp.rm(dir, { recursive: true, force: true });
     return true;
   } catch {
     return false;
@@ -207,10 +228,10 @@ router.get('/projects/:id/preflight', async (req, res) => {
     try {
       outer: for (const root of getHuBoardPlansDirs()) {
         const plansDir = path.join(root, projectId);
-        if (!fs.existsSync(plansDir)) continue;
-        for (const f of fs.readdirSync(plansDir).filter((x) => x.endsWith('.json'))) {
+        if (!(await pathExists(plansDir))) continue;
+        for (const f of (await fsp.readdir(plansDir)).filter((x) => x.endsWith('.json'))) {
           try {
-            const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
+            const plan = await readPlanCached(path.join(plansDir, f));
             if (plan?.projectDir) { projectDir = plan.projectDir; break outer; }
           } catch { /* try next file */ }
         }
@@ -231,7 +252,7 @@ router.get('/projects/:id/preflight', async (req, res) => {
  * failed · 15 min" banner. Plans that haven't finished yet have a
  * null outcome — the front handles that by hiding the banner.
  */
-router.get('/projects/:id/plans-outcome', (req, res) => {
+router.get('/projects/:id/plans-outcome', async (req, res) => {
   try {
     const projectId = req.params.id;
     // KJC-BUG-0059 (v2.19.3): scan canonical + legacy roots so users
@@ -239,10 +260,10 @@ router.get('/projects/:id/plans-outcome', (req, res) => {
     const out = [];
     for (const root of getHuBoardPlansDirs()) {
       const plansDir = path.join(root, projectId);
-      if (!fs.existsSync(plansDir)) continue;
-      for (const f of fs.readdirSync(plansDir).filter(n => n.endsWith('.json'))) {
+      if (!(await pathExists(plansDir))) continue;
+      for (const f of (await fsp.readdir(plansDir)).filter(n => n.endsWith('.json'))) {
         try {
-          const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
+          const plan = await readPlanCached(path.join(plansDir, f));
           if (plan?.version !== 2) continue;
           out.push({
           planId: plan.planId,
@@ -363,7 +384,7 @@ router.get('/sessions', (_req, res) => {
  * Also removes the hu-stories/<id>/ directory from disk so the next sync
  * does not re-import it.
  */
-router.delete('/projects/:id', (req, res) => {
+router.delete('/projects/:id', async (req, res) => {
   try {
     const id = req.params.id;
     // Gather filesystem paths to remove BEFORE deleting DB rows so we
@@ -397,7 +418,7 @@ router.delete('/projects/:id', (req, res) => {
     // Best-effort fs cleanup; failure does NOT undo the tombstones.
     let pathsRemoved = 0;
     for (const p of fsPaths) {
-      try { fs.rmSync(p, { recursive: true, force: true }); pathsRemoved++; } catch { /* */ }
+      try { await fsp.rm(p, { recursive: true, force: true }); pathsRemoved++; } catch { /* */ }
     }
     res.json({ deleted: true, pathsRemoved, tombstoned: 1 + storyIds.length + sessionIds.length });
   } catch (err) {
@@ -411,7 +432,7 @@ router.delete('/projects/:id', (req, res) => {
  * prompt id so a stale chokidar event can't recreate it, and emits a
  * `prompt:resolved` event so all open boards close the modal.
  */
-router.delete('/prompts/:promptId', (req, res) => {
+router.delete('/prompts/:promptId', async (req, res) => {
   try {
     const promptId = req.params.promptId;
     const dir = promptsDir();
@@ -419,7 +440,7 @@ router.delete('/prompts/:promptId', (req, res) => {
     const answer = path.join(dir, `${promptId}.answer.json`);
     let removed = 0;
     for (const p of [main, answer]) {
-      try { fs.unlinkSync(p); removed++; } catch { /* missing is fine */ }
+      try { await fsp.unlink(p); removed++; } catch { /* missing is fine */ }
     }
     addTombstone('prompt', promptId, { source: 'api', fsPaths: [main, answer] });
     // Re-use the same event the runner emits when answered, so any open
@@ -439,7 +460,7 @@ router.delete('/prompts/:promptId', (req, res) => {
  * it. Pre-tombstones this endpoint was a DB-only soft hide that the next
  * chokidar event undid silently.
  */
-router.delete('/stories/:id', (req, res) => {
+router.delete('/stories/:id', async (req, res) => {
   try {
     const id = req.params.id;
     const dir = path.join(huStoriesDir(), id);
@@ -447,7 +468,7 @@ router.delete('/stories/:id', (req, res) => {
     if (!ok) return res.status(404).json({ error: 'Story not found' });
     addTombstone('story', id, { source: 'api', fsPaths: [dir] });
     let dirRemoved = false;
-    try { fs.rmSync(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
+    try { await fsp.rm(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
     res.json({ deleted: true, dirRemoved });
   } catch (err) {
     res.status(500).json({ error: err.message });
@@ -459,7 +480,7 @@ router.delete('/stories/:id', (req, res) => {
  *
  * Tombstones + removes `~/.karajan/sessions/<id>/` (KJC-TSK-0380).
  */
-router.delete('/sessions/:id', (req, res) => {
+router.delete('/sessions/:id', async (req, res) => {
   try {
     const id = req.params.id;
     const dir = path.join(getKjHome(), 'sessions', id);
@@ -467,7 +488,7 @@ router.delete('/sessions/:id', (req, res) => {
     if (!ok) return res.status(404).json({ error: 'Session not found' });
     addTombstone('session', id, { source: 'api', fsPaths: [dir] });
     let dirRemoved = false;
-    try { fs.rmSync(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
+    try { await fsp.rm(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
     res.json({ deleted: true, dirRemoved });
   } catch (err) {
     res.status(500).json({ error: err.message });
@@ -482,7 +503,7 @@ router.delete('/sessions/:id', (req, res) => {
  * delete the project: a project can have multiple plans, deleting one
  * plan only removes that plan's HUs from the board.
  */
-router.delete('/plans/:planId', (req, res) => {
+router.delete('/plans/:planId', async (req, res) => {
   try {
     const planId = req.params.planId;
     // Locate the plan file by scanning both canonical and legacy plans
@@ -492,15 +513,15 @@ router.delete('/plans/:planId', (req, res) => {
     let foundPath = null;
     try {
       outer: for (const plansRoot of getHuBoardPlansDirs()) {
-        if (!fs.existsSync(plansRoot)) continue;
-        for (const projSlug of fs.readdirSync(plansRoot)) {
+        if (!(await pathExists(plansRoot))) continue;
+        for (const projSlug of await fsp.readdir(plansRoot)) {
           const candidate = path.join(plansRoot, projSlug, `plan-${planId}.json`);
-          if (fs.existsSync(candidate)) { foundPath = candidate; break outer; }
+          if (await pathExists(candidate)) { foundPath = candidate; break outer; }
         }
       }
     } catch { /* plansRoot missing */ }
     addTombstone('plan', planId, { source: 'api', fsPaths: foundPath ? [foundPath] : [] });
-    if (foundPath) { try { fs.unlinkSync(foundPath); } catch { /* */ } }
+    if (foundPath) { try { await fsp.unlink(foundPath); } catch { /* */ } }
     res.json({ deleted: true, fileRemoved: !!foundPath });
   } catch (err) {
     res.status(500).json({ error: err.message });
@@ -770,11 +791,11 @@ function promptsDir() {
 // Solomon escalation; anything older is a crashed runner.
 const PROMPT_ZOMBIE_TTL_MS = 30 * 60 * 1000;
 
-router.get('/prompts', (_req, res) => {
+router.get('/prompts', async (_req, res) => {
   try {
     const dir = promptsDir();
-    if (!fs.existsSync(dir)) return res.json([]);
-    const entries = fs.readdirSync(dir);
+    if (!(await pathExists(dir))) return res.json([]);
+    const entries = await fsp.readdir(dir);
     const result = [];
     const now = Date.now();
     for (const name of entries) {
@@ -784,21 +805,21 @@ router.get('/prompts', (_req, res) => {
       const answerPath = path.join(dir, `${promptId}.answer.json`);
       // KJC-TSK-0380 — skip tombstoned prompts and clean their files.
       if (isTombstonedFn('prompt', promptId)) {
-        try { fs.unlinkSync(mainPath); } catch { /* */ }
-        try { fs.unlinkSync(answerPath); } catch { /* */ }
+        try { await fsp.unlink(mainPath); } catch { /* */ }
+        try { await fsp.unlink(answerPath); } catch { /* */ }
         continue;
       }
       let parsed;
       try {
-        parsed = JSON.parse(fs.readFileSync(mainPath, 'utf-8'));
+        parsed = JSON.parse(await fsp.readFile(mainPath, 'utf-8'));
       } catch { continue; /* malformed — skip */ }
       // KJC-BUG-0038: zombie detection. Prefer parsed.createdAt; fall back
       // to mtime if the runner skipped the timestamp (older formats).
       const createdMs = Date.parse(parsed?.createdAt || '');
-      const ageRef = Number.isFinite(createdMs) ? createdMs : safeMtime(mainPath);
+      const ageRef = Number.isFinite(createdMs) ? createdMs : await safeMtime(mainPath);
       if (ageRef && (now - ageRef) > PROMPT_ZOMBIE_TTL_MS) {
-        try { fs.unlinkSync(mainPath); } catch { /* */ }
-        try { fs.unlinkSync(answerPath); } catch { /* */ }
+        try { await fsp.unlink(mainPath); } catch { /* */ }
+        try { await fsp.unlink(answerPath); } catch { /* */ }
         addTombstone('prompt', promptId, { source: 'zombie-ttl', fsPaths: [mainPath, answerPath] });
         continue;
       }
@@ -811,8 +832,8 @@ router.get('/prompts', (_req, res) => {
   }
 });
 
-function safeMtime(p) {
-  try { return fs.statSync(p).mtimeMs; } catch { return 0; }
+async function safeMtime(p) {
+  try { return (await fsp.stat(p)).mtimeMs; } catch { return 0; }
 }
 
 /**
@@ -821,20 +842,20 @@ function safeMtime(p) {
  * it, deletes both files, and resolves askQuestion. An answer of
  * "stop" tells the runner to abort the session.
  */
-router.post('/prompts/:promptId/answer', (req, res) => {
+router.post('/prompts/:promptId/answer', async (req, res) => {
   try {
     const { answer } = req.body || {};
     if (typeof answer !== 'string') {
       return res.status(400).json({ error: 'Body must contain an "answer" string' });
     }
     const dir = promptsDir();
-    fs.mkdirSync(dir, { recursive: true });
+    await fsp.mkdir(dir, { recursive: true });
     const promptPath = path.join(dir, `${req.params.promptId}.json`);
-    if (!fs.existsSync(promptPath)) {
+    if (!(await pathExists(promptPath))) {
       return res.status(404).json({ error: `Prompt not found: ${req.params.promptId}` });
     }
     const answerPath = path.join(dir, `${req.params.promptId}.answer.json`);
-    fs.writeFileSync(
+    await fsp.writeFile(
       answerPath,
       JSON.stringify({ answer, answeredAt: new Date().toISOString() }, null, 2),
       'utf-8'
@@ -912,14 +933,14 @@ router.get('/events', (req, res) => {
  * Path is the same one that `runPlan` wrote to:
  *   ~/.karajan/hu-board-runs/<planId>.log (honours KJ_HOME in tests).
  */
-router.get('/plans/:planId/log', (req, res) => {
+router.get('/plans/:planId/log', async (req, res) => {
   try {
     const runsDir = getHuBoardRunsDir(); // KJC-TSK-0421
     const logPath = path.join(runsDir, `${req.params.planId}.log`);
-    if (!fs.existsSync(logPath)) {
+    if (!(await pathExists(logPath))) {
       return res.json({ exists: false, size: 0, content: '' });
     }
-    const stat = fs.statSync(logPath);
+    const stat = await fsp.stat(logPath);
     const offset = Math.max(0, Math.min(stat.size, Number(req.query.offset) || 0));
     // Cap per-request read to 1 MiB so a huge log can't blow up the
     // response. The client will keep polling and catch up.
@@ -927,13 +948,13 @@ router.get('/plans/:planId/log', (req, res) => {
     const length = Math.min(MAX_READ, stat.size - offset);
     let content = '';
     if (length > 0) {
-      const fd = fs.openSync(logPath, 'r');
+      const fh = await fsp.open(logPath, 'r');
       try {
         const buf = Buffer.alloc(length);
-        fs.readSync(fd, buf, 0, length, offset);
+        await fh.read(buf, 0, length, offset);
         content = buf.toString('utf-8');
       } finally {
-        fs.closeSync(fd);
+        await fh.close();
       }
     }
     res.json({ exists: true, size: stat.size, content });
@@ -1230,26 +1251,26 @@ router.post('/runs/:planId/stop', async (req, res) => {
   }
 });
 
-router.get('/runs/:commandId/log', (req, res) => {
+router.get('/runs/:commandId/log', async (req, res) => {
   try {
     const runsDir = getHuBoardRunsDir(); // KJC-TSK-0421
     const logPath = path.join(runsDir, `${req.params.commandId}.log`);
-    if (!fs.existsSync(logPath)) {
+    if (!(await pathExists(logPath))) {
       return res.json({ exists: false, size: 0, content: '' });
     }
-    const stat = fs.statSync(logPath);
+    const stat = await fsp.stat(logPath);
     const offset = Math.max(0, Math.min(stat.size, Number(req.query.offset) || 0));
     const MAX_READ = 1024 * 1024;
     const length = Math.min(MAX_READ, stat.size - offset);
     let content = '';
     if (length > 0) {
-      const fd = fs.openSync(logPath, 'r');
+      const fh = await fsp.open(logPath, 'r');
       try {
         const buf = Buffer.alloc(length);
-        fs.readSync(fd, buf, 0, length, offset);
+        await fh.read(buf, 0, length, offset);
         content = buf.toString('utf-8');
       } finally {
-        fs.closeSync(fd);
+        await fh.close();
       }
     }
     res.json({ exists: true, size: stat.size, content });

package/packages/hu-board/src/zombie-reaper.js

@@ -130,7 +130,7 @@ export function appendZombieCheckpoint(existingJson, reason, isoTimestamp) {
  * @returns {string}
  */
 import { getKjHome } from "./db.js";
-export function getSessionsDir() {
+function getSessionsDir() {
   return path.join(getKjHome(), "sessions");
 }
 

package/src/agents/aider-agent.js

@@ -12,7 +12,7 @@ import { resolveBin } from "./resolve-bin.js";
  * Returns `{tokens_in, tokens_out, cached_tokens}` or null when no usage
  * is found (= unmeasured; callers leave the fields undefined).
  */
-export function extractAiderUsage(text) {
+function extractAiderUsage(text) {
   if (!text) return null;
   for (const line of text.split("\n")) {
     const t = line.trim();

package/src/agents/gemini-agent.js

@@ -12,7 +12,7 @@ import { resolveBin } from "./resolve-bin.js";
  * so the caller leaves `cached_tokens` undefined (= unmeasured,
  * distinct from a measured 0).
  */
-export function extractGeminiUsage(text) {
+function extractGeminiUsage(text) {
   if (!text) return null;
   const candidates = [];
   for (const line of text.split("\n")) {

package/src/agents/opencode-agent.js

@@ -10,7 +10,7 @@ import { resolveBin } from "./resolve-bin.js";
  * nested `usage` object. Returns `{tokens_in, tokens_out, cached_tokens}`
  * or null (= unmeasured).
  */
-export function extractOpenCodeUsage(text) {
+function extractOpenCodeUsage(text) {
   if (!text) return null;
   const candidates = [text.trim()];
   for (const line of text.split("\n")) {

package/src/audit/agent-readiness.js

@@ -16,6 +16,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { escapeRegExp } from "../utils/escape-regexp.js";
 
 const PAGE_BYTE_LIMIT = 32 * 1024; // ≈ 8K tokens, the typical agent budget per fetch
 
@@ -65,7 +66,7 @@ const CHECKS = [
       if (!found) return { ok: false, hint: "Add robots.txt with `User-agent: GPTBot|ClaudeBot|PerplexityBot\\nAllow: /` blocks.", details: {} };
       const text = safeRead(path.join(rootDir, found));
       const aiBots = ["GPTBot", "ClaudeBot", "PerplexityBot", "anthropic-ai", "Google-Extended"];
-      const allowed = aiBots.filter((bot) => new RegExp(`User-agent:\\s*${bot}[\\s\\S]*?Allow:\\s*/`, "i").test(text));
+      const allowed = aiBots.filter((bot) => new RegExp(`User-agent:\\s*${escapeRegExp(bot)}[\\s\\S]*?Allow:\\s*/`, "i").test(text));
       const ok = allowed.length > 0;
       return ok
         ? { ok: true, hint: null, details: { found, allowed } }

package/src/audit/deterministic-summary.js

@@ -71,7 +71,8 @@ function formatInjectionBlock(inj) {
       if (items.length === 0) continue;
       lines.push(`  - ${severity} (${items.length}):`);
       for (const f of items.slice(0, MAX_SAMPLE_INJECTION_PER_SEVERITY)) {
-        lines.push(`    - ${f.file || "(unknown)"}${f.line ? `:${f.line}` : ""} [${f.type}] ${f.pattern}`);
+        const lineSuffix = f.line ? `:${f.line}` : "";
+        lines.push(`    - ${f.file || "(unknown)"}${lineSuffix} [${f.type}] ${f.pattern}`);
       }
       if (items.length > MAX_SAMPLE_INJECTION_PER_SEVERITY) lines.push(`    - ... and ${items.length - MAX_SAMPLE_INJECTION_PER_SEVERITY} more in ${severity}`);
     }
@@ -85,7 +86,8 @@ function formatCircularDepsBlock(circularDeps) {
     return ["### Circular Dependencies (architecture)", `- Status: not available — ${circularDeps.reason || "madge not available"}`, ""];
   }
   const lines = ["### Circular Dependencies (architecture)"];
-  lines.push(`- Total cycles: ${circularDeps.total ?? 0}${circularDeps.suppressedCount ? ` (+${circularDeps.suppressedCount} suppressed)` : ""}`);
+  const suppressedSuffix = circularDeps.suppressedCount ? ` (+${circularDeps.suppressedCount} suppressed)` : "";
+  lines.push(`- Total cycles: ${circularDeps.total ?? 0}${suppressedSuffix}`);
   if ((circularDeps.total ?? 0) > 0) {
     const groups = groupCyclesBySeverity(circularDeps.cycles || []);
     for (const [severity, cycles] of Object.entries(groups)) {
@@ -118,7 +120,8 @@ function formatSemgrepBlock(semgrepFindings) {
       if (findings.length === 0) continue;
       lines.push(`  - ${severity} (${findings.length}):`);
       for (const f of findings.slice(0, MAX_SAMPLE_SEMGREP_PER_SEVERITY)) {
-        const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+        const lineSuffix = f.line ? `:${f.line}` : "";
+        const loc = f.file ? `${f.file}${lineSuffix}` : "";
         lines.push(`    - ${loc} [${f.rule}]`);
       }
       if (findings.length > MAX_SAMPLE_SEMGREP_PER_SEVERITY) {
@@ -172,7 +175,9 @@ function formatDeadExportsBlock(deadExports) {
       if (items.length === 0) continue;
       lines.push(`  - ${severity} (${items.length}):`);
       for (const item of items.slice(0, MAX_SAMPLE_KNIP_PER_SEVERITY)) {
-        lines.push(`    - ${item.path}${item.line ? `:${item.line}` : ""} [${item.rule}]${item.name ? ` \`${item.name}\`` : ""}`);
+        const lineSuffix = item.line ? `:${item.line}` : "";
+        const nameSuffix = item.name ? ` \`${item.name}\`` : "";
+        lines.push(`    - ${item.path}${lineSuffix} [${item.rule}]${nameSuffix}`);
       }
       if (items.length > MAX_SAMPLE_KNIP_PER_SEVERITY) {
         lines.push(`    - ... and ${items.length - MAX_SAMPLE_KNIP_PER_SEVERITY} more in ${severity}`);
@@ -246,7 +251,8 @@ function formatSonarBlock(sonarFindings) {
       if (issues.length === 0) continue;
       lines.push(`  - ${severity} (${issues.length}):`);
       for (const issue of issues.slice(0, MAX_SAMPLE_SONAR_PER_SEVERITY)) {
-        const loc = issue.component ? `${issue.component}${issue.line ? `:${issue.line}` : ""}` : "";
+        const lineSuffix = issue.line ? `:${issue.line}` : "";
+        const loc = issue.component ? `${issue.component}${lineSuffix}` : "";
         const rule = issue.rule ? ` [${issue.rule}]` : "";
         lines.push(`    - ${loc}${rule} ${issue.message || ""}`.trim());
       }

package/src/audit/issue-filter.js

@@ -16,6 +16,7 @@
 // metadata for auditability — no silent dropping.
 
 import fs from "node:fs";
+import { escapeRegExp } from "../utils/escape-regexp.js";
 
 export const DEFAULT_FALSE_POSITIVES = [
   {
@@ -59,8 +60,8 @@ export function hasInlineIgnore(filePath, line, ruleId, tool = "sonar") {
     const lines = fs.readFileSync(filePath, "utf8").split("\n");
     const idx = line - 1;
     const candidates = [lines[idx], lines[idx - 1]].filter(Boolean);
-    const escapedRule = escapeRegex(ruleId);
-    const escapedTool = escapeRegex(tool);
+    const escapedRule = escapeRegExp(ruleId);
+    const escapedTool = escapeRegExp(tool);
     // New generalised marker + legacy sonar-only marker.
     const reAudit = new RegExp(`karajan-audit-ignore\\s*:\\s*${escapedTool}:${escapedRule}\\b`);
     const reLegacy = tool === "sonar"
@@ -72,10 +73,6 @@ export function hasInlineIgnore(filePath, line, ruleId, tool = "sonar") {
   }
 }
 
-function escapeRegex(s) {
-  return String(s).replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
 /**
  * Filter a list of normalised audit findings into kept + suppressed.
  *

package/src/audit/plan-adherence.js

@@ -7,6 +7,8 @@
  * See docs/plan-adherence.md (PR-C) for the full spec.
  */
 
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
 const WEIGHTS = {
   commit_attribution: 40,
   acceptance_tests: 30,
@@ -20,7 +22,7 @@ const WEIGHTS = {
  * appear inside HU ids so we anchor on whole-token rather than \b.
  */
 function huIdMatcher(huId) {
-  const escaped = String(huId).replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&");
+  const escaped = escapeRegExp(huId);
   return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, "i");
 }
 

package/src/audit/semgrep-findings.js

@@ -72,6 +72,10 @@ export async function collectSemgrepFindings(projectDir, logger = null) {
   return { available: true, ...parseSemgrepOutput(parsed, projectDir) };
 }
 
+function relativizeSemgrepPath(p, projectDir) {
+  return p.startsWith(projectDir + "/") ? p.slice(projectDir.length + 1) : p;
+}
+
 /**
  * Convert semgrep's JSON shape into the flat findings list the prompt
  * builder consumes. Semgrep emits results[] with rule id, severity,
@@ -86,7 +90,7 @@ export function parseSemgrepOutput(raw, projectDir = "") {
   const findings = [];
   for (const r of results) {
     const file = r.path && projectDir
-      ? r.path.startsWith(projectDir + "/") ? r.path.slice(projectDir.length + 1) : r.path
+      ? relativizeSemgrepPath(r.path, projectDir)
       : r.path || "";
     findings.push({
       rule: r.check_id || "(unknown)",

package/src/brain/agent-error-classifier.js

@@ -37,7 +37,14 @@ const SILENCED_PATTERNS = /killed\s+after\s+\d+\s*ms|silence\s*timeout|no\s+outp
 // ("You've hit your session limit · resets 10:10pm"). Without them the
 // message fell through to UNKNOWN_FATAL and the run aborted instead of
 // hibernating until the reset.
-const RATE_LIMIT_PATTERNS = /usage\s+limit|rate\s*limit|too\s+many\s+requests|\b429\b|throttl|exceeded\s+your\s+current\s+quota|resource\s+exhausted|quota\s+exceeded|token\s+limit\s+reached|monthly\s+limit|weekly\s+limit|daily\s+limit|session\s+limit/i;
+// Decomposed by family (S5843, complexity 36 → 3 named groups). The
+// union of tokens is identical to the original single alternation.
+const RATE_LIMIT_GROUPS = [
+  /rate\s*limit|too\s+many\s+requests|\b429\b|throttl/i,
+  /exceeded\s+your\s+current\s+quota|resource\s+exhausted|quota\s+exceeded|token\s+limit\s+reached/i,
+  /usage\s+limit|monthly\s+limit|weekly\s+limit|daily\s+limit|session\s+limit/i,
+];
+const RATE_LIMIT_PATTERNS = { test: (text) => RATE_LIMIT_GROUPS.some((re) => re.test(text)) };
 const API_DOWN_PATTERNS = /\b50[0-4]\b|bad\s+gateway|service\s+unavailable|gateway\s+timeout|overloaded|internal\s+server\s+error/i;
 const NETWORK_PATTERNS = /ECONNREFUSED|ECONNRESET|ETIMEDOUT|socket\s+hang\s+up|fetch\s+failed|network\s+error/i;
 

package/src/brain/decisor.js

@@ -179,8 +179,8 @@ export function buildDecision({ triage, task: _task, config = {}, overrides = {}
     solomonReason = "triage returned no level";
   }
 
-  const rolesOn = Array.from(roles).sort();
-  const rolesOff = Array.from(VALID_ROLES).filter((r) => !roles.has(r)).sort();
+  const rolesOn = Array.from(roles).sort((a, b) => a.localeCompare(b));
+  const rolesOff = Array.from(VALID_ROLES).filter((r) => !roles.has(r)).sort((a, b) => a.localeCompare(b));
 
   const rationale = buildRationale({ level, taskType, rolesOn, appliedOverrides, triage });
 

package/src/brain/solomon-consult.js

@@ -161,8 +161,8 @@ export function applyRulingToDecision(decision, ruling, logger) {
 
   return {
     ...decision,
-    rolesOn: Array.from(rolesOn).sort(),
-    rolesOff: Array.from(rolesOff).sort(),
+    rolesOn: Array.from(rolesOn).sort((a, b) => a.localeCompare(b)),
+    rolesOff: Array.from(rolesOff).sort((a, b) => a.localeCompare(b)),
     appliedOverrides: [...decision.appliedOverrides, ...applied],
     confidence: applied.length > 0 ? "high" : decision.confidence,
     consultSolomon: false,

package/src/brain/standby-scheduler.js

@@ -5,6 +5,4 @@ export {
   scheduleResume,
   cancelScheduled,
   reconcileAll,
-  acquireStandbyLock,
-  markStandbyDone,
 } from "@karajan/core/standby-scheduler";

package/src/commands/audit.js

@@ -38,7 +38,8 @@ function promptContinueWithLlm({ promptFn = null } = {}) {
 function formatFindings(findings) {
   const lines = [];
   for (const f of findings) {
-    const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+    const lineSuffix = f.line ? `:${f.line}` : "";
+    const loc = f.file ? `${f.file}${lineSuffix}` : "";
     const rule = f.rule ? ` [${f.rule}]` : "";
     lines.push(`  - [${f.severity.toUpperCase()}] ${loc}${rule}`);
     lines.push(`    ${f.description}`);
@@ -116,7 +117,8 @@ function formatAudit(parsed, usage = null) {
 function formatUsageSummary(usage) {
   if (!usage) return null;
   const lines = ["## LLM Usage"];
-  lines.push(`- Provider: ${usage.provider}${usage.model ? ` (${usage.model})` : ""}`);
+  const modelSuffix = usage.model ? ` (${usage.model})` : "";
+  lines.push(`- Provider: ${usage.provider}${modelSuffix}`);
   if (typeof usage.durationMs === "number") {
     lines.push(`- Duration: ${(usage.durationMs / 1000).toFixed(1)}s`);
   }
@@ -130,6 +132,9 @@ function formatUsageSummary(usage) {
   // locale-less Node and "1,234" on a US-locale workstation).
   const fmt = (n) => n.toLocaleString("en-US");
   lines.push(`- Tokens: ${fmt(usage.total_tokens)} total (${fmt(usage.tokens_in)} in, ${fmt(usage.tokens_out)} out)`);
+  if (typeof usage.cached_tokens === "number" && usage.cached_tokens > 0) {
+    lines.push(`- Cached tokens: ${fmt(usage.cached_tokens)} (prompt-cache hits)`);
+  }
   if (typeof usage.cost_usd === "number") {
     lines.push(`- Estimated cost: $${usage.cost_usd.toFixed(4)} USD`);
   }
@@ -402,4 +407,4 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
 }
 
 // Exposed for tests — kept module-private otherwise.
-export { formatAudit, formatUsageSummary, AUDIT_DIMENSIONS };
+export { formatAudit, formatUsageSummary };

package/src/commands/board.js

@@ -128,7 +128,7 @@ export function waitForEarlyExit(child, logPath) {
 // out, so we never announce "HU Board started" for an unreachable
 // server. Overridable with KJ_BOARD_READY_TIMEOUT_MS (tests set it
 // low to stay fast).
-export async function waitForBoardReachable(port, totalTimeoutMs) {
+async function waitForBoardReachable(port, totalTimeoutMs) {
   const envTimeout = Number(process.env.KJ_BOARD_READY_TIMEOUT_MS);
   const budget = Number.isFinite(envTimeout) && envTimeout >= 0
     ? envTimeout

package/src/commands/standby.js

@@ -49,7 +49,10 @@ export async function standbyListCommand({ json } = {}) {
     const ms = new Date(s.cooldownUntil).getTime() - now;
     const status = ms <= 0 ? "✓ lista para resume" : `⏳ resume en ${formatCountdown(ms)}`;
     console.log(`  ${s.sessionId}  · ${s.reason || "?"}  · ${status}`);
-    if (s.planId) console.log(`    plan: ${s.planId}${s.huId ? `, HU: ${s.huId}` : ""}`);
+    if (s.planId) {
+      const huSuffix = s.huId ? `, HU: ${s.huId}` : "";
+      console.log(`    plan: ${s.planId}${huSuffix}`);
+    }
   }
 }
 

package/src/config/loader.js

@@ -187,8 +187,8 @@ function stripRuntimeOnlyKeys(config) {
   // warning on every subsequent kj run.
   if (out.sonarqube && typeof out.sonarqube === "object"
       && Object.prototype.hasOwnProperty.call(out.sonarqube, "enabled")) {
-    const { enabled: _drop, ...rest } = out.sonarqube;
-    void _drop;
+    const rest = { ...out.sonarqube };
+    delete rest.enabled;
     out.sonarqube = rest;
   }
   return out;