karajan-code 2.19.0 → 2.19.2

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

@@ -0,0 +1,207 @@
+/**
+ * Zombie session reaper for the HU Board (board-polish #2,
+ * KJC dogfooding 2026-05-07).
+ *
+ * Why this exists
+ * ===============
+ *
+ * Sessions in the SQLite db can stay "in flight" forever when the
+ * orchestrator process dies between iterations: their `status` stays
+ * `coding` / `stalled` / `paused`, the UI keeps surfacing them as
+ * actionable, and `kj board start` weeks later still pops a
+ * "Karajan needs an answer" modal for a checkpoint nobody owns
+ * anymore.
+ *
+ * Concretely, on 2026-05-07 the user opened the board on a fresh
+ * `kj board start` and saw the popup of an HU from 2026-04-27 — 9
+ * days dead, status still `paused`. The fix per his explicit
+ * mandate:
+ *
+ *   "No puede quedarse nada zombie. Debe haber algun sistema que lo
+ *    compruebe al arrancar y mate esos zombies."
+ *
+ * Thresholds (per his decision in the same session):
+ *   - status in (coding | stalled) and >= 6h since updated_at  → reap
+ *   - status === paused and >= 24h since updated_at            → reap
+ *   - everything else                                          → skip
+ *
+ * What "reap" means: write `status: "failed"` BOTH to the DB row
+ * AND to the underlying `~/.karajan/sessions/<id>/session.json`,
+ * append a structured checkpoint of the form
+ *   { stage: 'zombie-reap', reason: <reason>, at: <iso> }
+ * so the audit trail survives. The session row stays in place
+ * (we don't DELETE — the user can still inspect what happened).
+ *
+ * Why update the JSON on disk too
+ * -------------------------------
+ *
+ * The board's `fullScan()` reads every session.json on startup and
+ * upserts the row, OVERWRITING any DB-only mutation. If the reaper
+ * only updated the DB, the next reboot would reset the status back
+ * to `paused`/`stalled` because the JSON still says so. Persisting
+ * to disk makes the reap permanent on the first reboot — the user
+ * sees the cleanup once, and never again.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const DEFAULT_CODING_HOURS = 6;
+const DEFAULT_PAUSED_HOURS = 24;
+const CODING_LIKE_STATUSES = new Set(["coding", "stalled", "running", "in_progress"]);
+const PAUSED_STATUSES = new Set(["paused", "checkpoint", "awaiting_answer"]);
+
+/**
+ * Decide whether a single session row qualifies as zombie at `now`.
+ * Pure function — no I/O. Used by both the reaper itself and the
+ * unit tests.
+ *
+ * @param {{ id: string, status: string, updated_at?: string|null,
+ *           created_at?: string|null }} session
+ * @param {{ now: number, codingHours: number, pausedHours: number }} ctx
+ * @returns {{ zombie: boolean, reason?: string }}
+ */
+export function classifyZombie(session, ctx) {
+  if (!session || !session.status) return { zombie: false };
+  const status = String(session.status).toLowerCase();
+  // Reference timestamp: prefer updated_at (the daemon writes that on
+  // every checkpoint sync), fall back to created_at (in case the row
+  // was inserted but never touched again).
+  const refIso = session.updated_at || session.created_at;
+  if (!refIso) return { zombie: false };
+  const refTs = new Date(refIso).getTime();
+  if (Number.isNaN(refTs)) return { zombie: false };
+  const ageHours = (ctx.now - refTs) / 3_600_000;
+  if (ageHours <= 0) return { zombie: false };
+  if (CODING_LIKE_STATUSES.has(status) && ageHours >= ctx.codingHours) {
+    return { zombie: true, reason: `${status} ${ageHours.toFixed(1)}h inactive (>= ${ctx.codingHours}h)` };
+  }
+  if (PAUSED_STATUSES.has(status) && ageHours >= ctx.pausedHours) {
+    return { zombie: true, reason: `${status} ${ageHours.toFixed(1)}h inactive (>= ${ctx.pausedHours}h)` };
+  }
+  return { zombie: false };
+}
+
+/**
+ * Filter a list of session rows down to the zombie ones. Pure.
+ *
+ * @param {Array<object>} sessions
+ * @param {{ now?: number, codingHours?: number, pausedHours?: number }} [opts]
+ * @returns {Array<{ session: object, reason: string }>}
+ */
+export function findZombieSessions(sessions, opts = {}) {
+  const ctx = {
+    now: opts.now ?? Date.now(),
+    codingHours: opts.codingHours ?? DEFAULT_CODING_HOURS,
+    pausedHours: opts.pausedHours ?? DEFAULT_PAUSED_HOURS,
+  };
+  const out = [];
+  for (const session of sessions || []) {
+    const verdict = classifyZombie(session, ctx);
+    if (verdict.zombie) out.push({ session, reason: verdict.reason });
+  }
+  return out;
+}
+
+/**
+ * Append a `zombie-reap` checkpoint to a JSON-encoded checkpoints
+ * blob (the on-disk format). Returns the new JSON string.
+ *
+ * Defensive about malformed input: if the existing blob isn't a
+ * JSON array, replaces it with a fresh array containing the new
+ * entry — never throws.
+ */
+export function appendZombieCheckpoint(existingJson, reason, isoTimestamp) {
+  let arr = [];
+  if (existingJson) {
+    try {
+      const parsed = JSON.parse(existingJson);
+      if (Array.isArray(parsed)) arr = parsed;
+    } catch { /* fall through with empty arr */ }
+  }
+  arr.push({ stage: "zombie-reap", reason, at: isoTimestamp });
+  return JSON.stringify(arr);
+}
+
+/**
+ * Default location of the on-disk session JSON files. Delegates to
+ * db.js::getKjHome (KJC-TSK-0420): KARAJAN_HOME > KJ_HOME > VITEST > default.
+ * @returns {string}
+ */
+import { getKjHome } from "./db.js";
+export function getSessionsDir() {
+  return path.join(getKjHome(), "sessions");
+}
+
+/**
+ * Persist `status: "failed"` and the new zombie-reap checkpoint to
+ * the on-disk session.json. This stops the next `fullScan()` from
+ * resurrecting the zombi.
+ *
+ * Safe-by-default: if the file is missing, malformed, or the write
+ * fails, this returns `false` and the caller logs a warning. We
+ * never throw and we never block the daemon's startup.
+ *
+ * @param {string} sessionId
+ * @param {string} reason
+ * @param {string} reapedAtIso
+ * @param {{ sessionsDir?: string }} [opts]
+ * @returns {boolean} true when the file was rewritten successfully
+ */
+export function markSessionFailedOnDisk(sessionId, reason, reapedAtIso, opts = {}) {
+  const dir = opts.sessionsDir || getSessionsDir();
+  const file = path.join(dir, sessionId, "session.json");
+  let raw;
+  try { raw = fs.readFileSync(file, "utf8"); } catch { return false; }
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return false; }
+  if (!parsed || typeof parsed !== "object") return false;
+  parsed.status = "failed";
+  parsed.updated_at = reapedAtIso;
+  parsed.checkpoints = Array.isArray(parsed.checkpoints) ? parsed.checkpoints : [];
+  parsed.checkpoints.push({ stage: "zombie-reap", reason, at: reapedAtIso });
+  try {
+    fs.writeFileSync(file, JSON.stringify(parsed, null, 2));
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Reap every zombie session in the DB AND in the underlying
+ * session.json files. Side-effecting. Returns the list of reaped
+ * sessions so the server can log them.
+ *
+ * @param {object} deps
+ * @param {object} deps.db        better-sqlite3 Database handle
+ * @param {object} [deps.opts]    threshold + sessionsDir overrides
+ * @param {Function} [deps.now]   () => number, for tests
+ * @returns {Array<{ id: string, status_before: string, reason: string, disk_persisted: boolean }>}
+ */
+export function reapZombieSessions({ db, opts = {}, now = () => Date.now() }) {
+  if (!db) return [];
+  const allSessions = db.prepare(
+    "SELECT id, status, updated_at, created_at, checkpoints FROM sessions WHERE status NOT IN ('failed', 'approved', 'cancelled', 'done')",
+  ).all();
+  const zombies = findZombieSessions(allSessions, { ...opts, now: now() });
+  if (zombies.length === 0) return [];
+  const update = db.prepare(
+    "UPDATE sessions SET status = 'failed', checkpoints = ?, updated_at = ? WHERE id = ?",
+  );
+  const reapedAt = new Date(now()).toISOString();
+  const reaped = [];
+  for (const { session, reason } of zombies) {
+    const newCheckpoints = appendZombieCheckpoint(session.checkpoints, reason, reapedAt);
+    update.run(newCheckpoints, reapedAt, session.id);
+    const diskPersisted = markSessionFailedOnDisk(session.id, reason, reapedAt, {
+      sessionsDir: opts.sessionsDir,
+    });
+    reaped.push({
+      id: session.id,
+      status_before: session.status,
+      reason,
+      disk_persisted: diskPersisted,
+    });
+  }
+  return reaped;
+}

package/src/audit/webperf-input.js

@@ -28,15 +28,12 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 import { evaluateCwv, CWV_THRESHOLDS } from "../webperf/cwv-gate.js";
+import { getWebperfDir } from "../utils/paths.js";
 
-// Resolve per call — `os.homedir()` reads $HOME each time, so test
-// suites that override $HOME for hermetic tmp dirs work without
-// special re-imports.
-function webperfHome() {
-  return path.join(os.homedir(), ".karajan", "webperf");
-}
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME (with deprecation warning) / VITEST tmp.
+function webperfHome() { return getWebperfDir(); }
 
 function projectSlug(projectDir) {
   return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");

package/src/checks/dir-setup.js

@@ -7,6 +7,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { STRATEGY } from "./types.js";
+import { getKarajanHome } from "../utils/paths.js";
 
 const REQUIRED_DIRS = [
   "", // ~/.karajan/
@@ -26,8 +27,9 @@ export function createKarajanDirsCheck() {
     strategy: STRATEGY.AUTO,
     describe: "Create missing ~/.karajan subdirectories",
     async detect() {
-      const home = os.homedir();
-      const root = path.join(home, ".karajan");
+      // KJC-TSK-0420: KARAJAN_HOME / KJ_HOME aware via getKarajanHome().
+      const root = getKarajanHome();
+      const home = os.homedir(); // still needed for path.relative() below
       const missing = [];
       for (const sub of REQUIRED_DIRS) {
         const full = sub ? path.join(root, sub) : root;
@@ -82,7 +84,7 @@ export function createLegacyKjHomeCheck() {
       try {
         const entries = await fs.readdir(legacy);
         if (entries.length === 0) return { ok: true, severity: "info", detail: "Empty legacy ~/.kj/" };
-        const marker = path.join(os.homedir(), ".karajan", ".kj-migrated.json");
+        const marker = path.join(getKarajanHome(), ".kj-migrated.json"); // KJC-TSK-0420
         try { await fs.access(marker); return { ok: true, severity: "info", detail: "Already migrated" }; }
         catch { /* no marker, still pending */ }
         return {

package/src/cli/register-pipeline.js

@@ -105,6 +105,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--brain <mode>", "Brain decisor: on|off (default: on). When off, only legacy flags drive routing.")
     .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
     .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
+    .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
     .option("--dry-run", "Show what would be executed without running anything")
     .option("--json", "Output JSON only (no styled display)")
     .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")

package/src/cli/register-plan.js

@@ -40,6 +40,7 @@ export function registerPlan(program, { pkgVersion }) {
     // flags only if you explicitly want a fast / sketch plan.
     .option("--no-tests-synth", "Skip the tests-synthesizer pass that fills in missing acceptance_tests")
     .option("--no-plan-review", "Skip the high-level plan reviewer pass (gaps / deps / overlap / order)")
+    .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
     .option("--quick", "Sketch mode — skip every quality pass after the initial planner call")
     .option("-y, --yes", "Skip the project-name prompt (use the auto-derived default).")
     .option("--no-interactive", "Force non-interactive mode (no prompts, use defaults).")

package/src/commands/plan/generate.js

@@ -13,6 +13,7 @@ import { recommendModelsForHu, complexityFromTaskType } from "../../hu/model-rou
 import { withBrainRecovery } from "../../brain/with-brain-recovery.js";
 import { buildStandbyState } from "../../brain/standby-store.js";
 import { printResumeHint } from "../../utils/display/resume-hint.js";
+import { runSpecReview } from "../../spec-review/run-spec-review.js";
 import { formatPlan, formatHuTable } from "./_shared.js";
 
 /**
@@ -40,6 +41,20 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     }
   }
 
+  // Spec-reviewer pre-planner audit (KJC-PCS-0048). Static import —
+  // role runs every invocation (modulo bypass); no lazy-load benefit.
+  const reviewResult = await runSpecReview({
+    spec: task, config, logger, flags,
+    askQuestion: json ? null : (typeof flags?.askQuestion === "function" ? flags.askQuestion : null),
+  });
+  if (!reviewResult.proceed) {
+    logger?.info?.("Aborted by user after spec review.");
+    return { ok: false, aborted: true, reason: "spec-review-cancelled" };
+  }
+  if (reviewResult.refined && reviewResult.finalSpec) {
+    task = reviewResult.finalSpec; // downstream runs the refined spec
+  }
+
   const plannerRole = resolveRole(config, "planner");
   await assertAgentsAvailable([plannerRole.provider]);
   runLog.logText(`[planner] provider=${plannerRole.provider}`);

package/src/commands/run.js

@@ -11,6 +11,7 @@ import { printResumeHint } from "../utils/display/resume-hint.js";
 import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 import { confirmCwd } from "../utils/cwd-confirm.js";
+import { runSpecReview } from "../spec-review/run-spec-review.js";
 
 function createCliAskQuestion(opts = {}) {
   const { sessionId = null } = opts;
@@ -163,9 +164,26 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     }
 
     const askQuestion = createCliAskQuestion();
+
+    // Spec-reviewer pre-pipeline audit (KJC-PCS-0048). Runs BEFORE
+    // anything else — surfaces ambiguity / missing scope / missing AC
+    // and lets the user bail out cheap, before any tokens burn.
+    // Bypass with --skip-spec-review. Static import — the role runs
+    // on every kj invocation (modulo bypass), no lazy-load benefit.
+    const reviewResult = await runSpecReview({ spec: task, config, logger, askQuestion, flags });
+    if (!reviewResult.proceed) {
+      logger.info("Aborted by user after spec review.");
+      cleanupRegistry();
+      return { ok: false, aborted: true, reason: "spec-review-cancelled" };
+    }
+    // If the user refined the spec via [r]efine, downstream runs the
+    // REFINED text (not the original) so the pipeline acts on what the
+    // user actually approved.
+    const effectiveTask = reviewResult.refined && reviewResult.finalSpec ? reviewResult.finalSpec : task;
+
     let result;
     try {
-      result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+      result = await runFlow({ task: effectiveTask, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
     } finally {
       // KJC-TSK-0396: limpia el registro pase lo que pase (éxito,
       // throw, o paused). Los handlers de SIGINT/SIGTERM/exit son

package/src/commands/webperf.js

@@ -9,16 +9,14 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
 import yaml from "js-yaml";
 import { runWebperfScan } from "../webperf/scanner.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
 
-// Resolve home each call so tests that override $HOME for hermetic
-// tmp dirs work without re-importing the module.
-function defaultReportDir() {
-  return path.join(os.homedir(), ".karajan", "webperf");
-}
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME / VITEST tmp / default.
+import { getWebperfDir } from "../utils/paths.js";
+function defaultReportDir() { return getWebperfDir(); }
 
 /**
  * Slug a project directory the same way audit/basal-cost.js and

package/src/config/role-resolver.js

@@ -49,7 +49,9 @@ function isModelCompatible(agent, model) {
 // Roles that inherit provider/model from the coder when not explicitly configured
 const CODER_INHERITED_ROLES = new Set([
   "planner", "refactorer", "solomon", "researcher", "tester", "security",
-  "impeccable", "triage", "discover", "architect", "audit", "hu_reviewer", "hu-reviewer"
+  "impeccable", "triage", "discover", "architect", "audit",
+  "hu_reviewer", "hu-reviewer",
+  "spec_reviewer", "spec-reviewer",
 ]);
 
 function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {

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

@@ -47,6 +47,9 @@ function applySessionOverrides(a, roleKeys) {
 }
 
 export async function handlePlanDirect(a, server, extra) {
+  // KJC-PCS-0048 PR 3b: same `specReviewMode: skip` → skipSpecReview
+  // mapping as kj_run. Default "auto" keeps the reviewer enabled.
+  if (a.specReviewMode === "skip") a.skipSpecReview = true;
   const { normalizePlanArgs } = await import("../tool-arg-normalizers.js");
   const options = normalizePlanArgs(a);
   const config = await buildConfig(options, "plan");

package/src/mcp/handlers/run-handler.js

@@ -113,6 +113,11 @@ function collectRequiredProviders(config) {
 }
 
 export async function handleRunDirect(a, server, extra) {
+  // KJC-PCS-0048 PR 3b: respect specReviewMode without changing the
+  // existing handler contract. "skip" maps to the same flag the CLI
+  // honours; "auto" (default) leaves the reviewer enabled but the
+  // non-TTY runSpecReview path never blocks the pipeline.
+  if (a.specReviewMode === "skip") a.skipSpecReview = true;
   const config = await buildConfig(a);
   await assertNotOnBaseBranch(config, { allowForRun: true });
   const logger = createLogger(config.output.log_level, "mcp");

package/src/mcp/tools.js

@@ -113,7 +113,8 @@ export const tools = [
         domain: { type: "string", description: "Domain knowledge: inline text describing the project domain, or absolute path to a .md file. Auto-saved to .karajan/domains/ for the curator." },
         brain: { type: "string", enum: ["on", "off"], description: "Brain decisor: on|off. Controls whether intent-driven routing overrides pipeline flags." },
         forceRole: { type: "array", items: { type: "string" }, description: "Force roles ON regardless of triage (e.g. [\"security\"])" },
-        skipRole: { type: "array", items: { type: "string" }, description: "Force roles OFF regardless of triage (e.g. [\"tester\"])" }
+        skipRole: { type: "array", items: { type: "string" }, description: "Force roles OFF regardless of triage (e.g. [\"tester\"])" },
+        specReviewMode: { type: "string", enum: ["auto", "skip"], description: "Pre-pipeline spec-reviewer behaviour (KJC-PCS-0048). `auto` (default): the role runs, findings stream to the client via progress events; the pipeline continues regardless. `skip`: bypass the reviewer entirely (mirrors the --skip-spec-review CLI flag)." }
       }
     }
   },
@@ -245,7 +246,8 @@ export const tools = [
         coder: { type: "string", description: "Legacy alias for planner" },
         coderModel: { type: "string", description: "Legacy alias for plannerModel" },
         projectDir: { type: "string", description: "Absolute path to the project directory" },
-        kjHome: { type: "string" }
+        kjHome: { type: "string" },
+        specReviewMode: { type: "string", enum: ["auto", "skip"], description: "Pre-planner spec-reviewer behaviour (KJC-PCS-0048). `auto` (default): runs the reviewer, findings stream as progress, planner continues. `skip`: bypass entirely." }
       }
     }
   },

package/src/prompts/spec-reviewer.js

@@ -0,0 +1,66 @@
+// Prompt builder for the `spec-reviewer` role (KJC-PCS-0048 PR 1).
+// Mirrors src/prompts/triage.js — project-level override at
+// `<projectDir>/.karajan/roles/spec-reviewer.md` is injected via `instructions`.
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT execute or plan the task. Do NOT mention Karajan.",
+  "Do NOT use any MCP tools. Your only job is to audit the user's spec.",
+].join(" ");
+
+const VALID_CATEGORIES = [
+  "ambiguity", "missing_scope", "missing_ac", "contradiction",
+  "stack", "assumptions", "out_of_scope",
+];
+
+const SCHEMA_HINT = JSON.stringify({
+  severity: "ok|info|warn|fail",
+  findings: [{
+    id: "F-001",
+    severity: "info|warn|fail",
+    category: VALID_CATEGORIES.join("|"),
+    message: "concrete description",
+    suggestion: "concrete sentence the user can paste",
+  }],
+  reasoning: "one or two sentences",
+}, null, 2);
+
+export function buildSpecReviewerPrompt({ spec, instructions } = {}) {
+  const sections = [SUBAGENT_PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(
+    "You are the **Spec Reviewer** for Karajan Code.",
+    `Categories (pick one per finding): ${VALID_CATEGORIES.join(", ")}.`,
+    "Severity: `info` (nuance), `warn` (real gap), `fail` (unworkable). Top-level severity is the WORST of any finding (or `ok` if none).",
+    "Return JSON only:",
+    "```json", SCHEMA_HINT, "```",
+    "## Spec to audit", "```", String(spec || "").trim(), "```",
+  );
+  return sections.join("\n");
+}
+
+/**
+ * Build the refine prompt — used when the user picks `[r]efine`. The
+ * agent must rewrite the spec to fix the listed findings, returning
+ * ONLY the rewritten spec (no JSON, no preamble, no fence). The refine
+ * loop will persist this verbatim as `spec-v2.md`.
+ */
+export function buildSpecRefinerPrompt({ originalSpec, findings, instructions } = {}) {
+  const sections = [SUBAGENT_PREAMBLE];
+  if (instructions) sections.push(instructions);
+  const findingsBlock = (findings || []).map((f, i) => {
+    const idx = i + 1;
+    return `${idx}. [${f.severity}/${f.category}] ${f.message}${f.suggestion ? `\n   Fix: ${f.suggestion}` : ""}`;
+  }).join("\n");
+  sections.push(
+    "Your task: produce a rewritten version of the user's spec that addresses every finding listed below.",
+    "Output the rewritten spec verbatim — no JSON, no preamble, no markdown fences, no commentary.",
+    "Preserve the user's intent; do not invent new requirements or scope beyond the existing spec.",
+    "## Original spec", "```", String(originalSpec || "").trim(), "```",
+    "## Findings to address", findingsBlock || "(none — pass-through)",
+    "## Rewritten spec",
+  );
+  return sections.join("\n");
+}
+
+export { VALID_CATEGORIES };

package/src/roles/perf-role.js

@@ -20,7 +20,6 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
 import { BaseRole } from "./base-role.js";
 import { runWebperfScan } from "../webperf/scanner.js";
 
@@ -28,9 +27,10 @@ function projectSlug(projectDir) {
   return path.basename(projectDir || process.cwd()).replaceAll(/[^a-zA-Z0-9_-]/g, "_");
 }
 
-function defaultPersistDir() {
-  return path.join(os.homedir(), ".karajan", "webperf");
-}
+// Delegated to src/utils/paths.js (KJC-TSK-0420) — respects
+// KARAJAN_HOME / KJ_HOME / VITEST tmp / default.
+import { getWebperfDir } from "../utils/paths.js";
+function defaultPersistDir() { return getWebperfDir(); }
 
 async function persistResult(result, projectDir) {
   if (!result?.ok) return null;

package/src/roles/spec-reviewer-role.js

@@ -0,0 +1,106 @@
+// Spec Reviewer role (KJC-PCS-0048 PR 1). Runs BEFORE intent/triage/planner;
+// audits the user's spec and returns structured findings. Does NOT execute.
+
+import { AgentRole } from "./agent-role.js";
+import { buildSpecReviewerPrompt, buildSpecRefinerPrompt, VALID_CATEGORIES } from "../prompts/spec-reviewer.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+const F_SEVS = new Set(["info", "warn", "fail"]);
+const T_SEVS = new Set(["ok", "info", "warn", "fail"]);
+const CATS = new Set(VALID_CATEGORIES);
+const ORDER = { ok: 0, info: 1, warn: 2, fail: 3 };
+
+function normalise(findings) {
+  if (!Array.isArray(findings)) return [];
+  return findings.map((f, i) => ({
+    id: typeof f?.id === "string" && f.id.trim() ? f.id.trim() : `F-${String(i + 1).padStart(3, "0")}`,
+    severity: F_SEVS.has(f?.severity) ? f.severity : "warn",
+    category: CATS.has(f?.category) ? f.category : "ambiguity",
+    message: String(f?.message || "").trim() || "(no description)",
+    suggestion: typeof f?.suggestion === "string" && f.suggestion.trim() ? f.suggestion.trim() : null,
+  }));
+}
+
+const worstOf = (findings) => findings.reduce((m, f) => (ORDER[f.severity] > ORDER[m] ? f.severity : m), "ok");
+
+export class SpecReviewerRole extends AgentRole {
+  constructor(opts) { super({ ...opts, name: "spec-reviewer" }); }
+
+  extractInput(input) {
+    if (typeof input === "string") return { spec: input, onOutput: null };
+    return {
+      spec: input?.spec || input?.task || this.context?.task || "",
+      onOutput: input?.onOutput || null,
+      sessionState: input?.sessionState || null,
+    };
+  }
+
+  async buildPrompt({ spec }) {
+    return { prompt: buildSpecReviewerPrompt({ spec, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const findings = normalise(parsed?.findings);
+    const declared = T_SEVS.has(parsed?.severity) ? parsed.severity : null;
+    const derived = worstOf(findings);
+    // Trust the worse of declared vs derived — agents sometimes report
+    // `severity: "ok"` while still listing fail-level findings.
+    const severity = !declared || ORDER[derived] > ORDER[declared] ? derived : declared;
+    return { severity, findings, reasoning: String(parsed?.reasoning || "").trim() || null, provider };
+  }
+
+  buildSummary(parsed) {
+    const findings = normalise(parsed?.findings);
+    if (findings.length === 0) return "Spec OK (no findings)";
+    return `Spec ${worstOf(findings)}: ${findings.length} finding${findings.length === 1 ? "" : "s"}`;
+  }
+
+  // Parse failures degrade to a soft warning so the pipeline never blocks.
+  handleParseNull(r, p) { return this.#degraded(r, p, "parse-null", "LLM output was unstructured"); }
+  handleParseError(e, r, p) { return this.#degraded(r, p, "parse-error", e?.message || "unknown"); }
+
+  /**
+   * Refine mode (KJC-PCS-0048 PR 3). Bypasses the JSON-only `execute()`
+   * flow: returns the LLM output verbatim as the rewritten spec, so the
+   * refine loop can persist it as `spec-v2.md`.
+   * @returns {Promise<{ ok:boolean, refinedSpec?:string, error?:string, provider:string, usage?:object }>}
+   */
+  async refineSpec({ spec, findings }) {
+    if (!this._initialized) await this.init({ task: spec });
+    const provider = this.resolveProvider();
+    const agent = this.createAgentInstance(provider);
+    const prompt = buildSpecRefinerPrompt({ originalSpec: spec, findings, instructions: this.instructions });
+    const result = await withBrainRecovery({
+      agent: { runTask: (a) => agent.runTask(a), provider },
+      taskArgs: { prompt, role: this.name },
+      role: this.name, provider, emitter: this.emitter, logger: this.logger,
+    });
+    if (!result.ok) {
+      return { ok: false, error: result.error || "refine failed", provider, usage: result.usage };
+    }
+    const refinedSpec = String(result.output || "").replace(/^```[a-z]*\n?|```$/g, "").trim();
+    if (!refinedSpec) return { ok: false, error: "empty refined spec", provider, usage: result.usage };
+    return { ok: true, refinedSpec, provider, usage: result.usage };
+  }
+
+  #degraded(agentResult, provider, reason, detail) {
+    return {
+      ok: true,
+      result: {
+        severity: "warn",
+        findings: [{
+          id: "F-DEG", severity: "warn", category: "assumptions",
+          message: `[spec-reviewer] degraded (${reason}): ${detail}`,
+          suggestion: "Re-run with --skip-spec-review if this keeps failing.",
+        }],
+        reasoning: "Spec reviewer could not parse the LLM output; treating as a soft warning.",
+        provider, degraded: true,
+      },
+      summary: `Spec reviewer degraded: ${reason}`,
+      usage: agentResult?.usage,
+    };
+  }
+}

package/src/sonar/api.js

@@ -3,6 +3,7 @@ import { withRetry } from "../utils/retry.js";
 import { resolveSonarProjectKey } from "./project-key.js";
 import { resolveSonarToken } from "./config-resolver.js";
 import { filterFalsePositives } from "./issue-filter.js";
+import { recoverSonarToken } from "./token-recovery.js";
 
 class SonarApiError extends Error {
   constructor(message, { url, httpStatus, hint } = {}) {
@@ -25,7 +26,7 @@ function parseHttpResponse(stdout) {
   return { httpCode, body };
 }
 
-async function sonarFetchOnce(config, urlPath) {
+async function sonarFetchOnce(config, urlPath, { _retriedAfterRecovery = false, logger = null } = {}) {
   const token = tokenFromConfig(config);
   const url = `${config.sonarqube.host}${urlPath}`;
   const res = await runCommand("curl", ["-s", "-w", "\n%{http_code}", "-u", `${token}:`, url]);
@@ -42,9 +43,22 @@ async function sonarFetchOnce(config, urlPath) {
   const { httpCode, body } = parseHttpResponse(res.stdout);
 
   if (httpCode === 401) {
+    // KJC-BUG-0057 (v2.19.2): try to bootstrap a fresh token via the Sonar
+    // REST API and retry ONCE. If recovery still fails — or this was already
+    // the retry — surface the actionable error like before.
+    if (!_retriedAfterRecovery) {
+      const recovery = await recoverSonarToken(config, logger);
+      if (recovery.ok) {
+        return sonarFetchOnce(config, urlPath, { _retriedAfterRecovery: true, logger });
+      }
+      throw new SonarApiError(
+        `SonarQube authentication failed (HTTP 401) and auto-recovery failed: ${recovery.reason}. Regenerate the token manually with 'kj init' or save admin user/password in ~/.karajan/sonar-credentials.json.`,
+        { url, httpStatus: 401, hint: "Run 'kj init' to regenerate the SonarQube token, or save admin credentials in ~/.karajan/sonar-credentials.json so Karajan can re-bootstrap automatically." }
+      );
+    }
     throw new SonarApiError(
-      `SonarQube authentication failed (HTTP 401). Token may be invalid or expired. Regenerate with 'kj init'.`,
-      { url, httpStatus: 401, hint: "Run 'kj init' to regenerate the SonarQube token." }
+      `SonarQube authentication failed (HTTP 401) even after auto-recovery. The newly generated token is also being rejected — the Sonar instance may be in an inconsistent state.`,
+      { url, httpStatus: 401, hint: "Inspect the Sonar UI directly; consider 'kj sonar restart'." }
     );
   }