karajan-code 3.7.0 → 3.7.2

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v3.7.0 released** — Autonomous delivery: `kj autorun <spec>` chains spec → plan → run every user story → outcome in one command, unattended. An **Arbiter** resolves agent conflicts by picking the least-bad call (acceptance tests > must-fix > nice-to-have), no stage blocks for a human, a wall-clock backstop stops runaways, and it ends with an auditable "delivered, with known defects" report. Autonomy is opt-in (`--autonomous` / `--autonomy <level>`); interactive runs are unchanged. Verified live end-to-end. Full notes in [CHANGELOG.md](CHANGELOG.md).
+> **v3.7.1 released** — Patch: fixes a `kj init` crash when configuring the Plan B fallback, and makes pnpm installs safe — `kj doctor` now flags when pnpm skipped `better-sqlite3`'s native build and tells you exactly how to fix it (`pnpm approve-builds better-sqlite3`). The release gate checks pnpm too. Built on **v3.7.0 — Autonomous delivery**: `kj autorun <spec>` chains spec → plan → run every user story → outcome in one command, unattended, with an **Arbiter** that resolves agent conflicts by picking the least-bad call; autonomy is opt-in, interactive runs are unchanged. 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.
 
@@ -71,6 +71,33 @@ Two technical facts worth keeping straight:
 
 Full write-up with mental mapping for Genkit / Mastra / LangChain / Vercel AI SDK developers: **[docs/COMPARISON.md](./docs/COMPARISON.md)**.
 
+## Loop engineering
+
+Prompt engineering got one good answer from one good prompt. Context engineering
+curated what the model saw. The 2026 frontier is **loop engineering**: you stop
+prompting the agent by hand and design the control system that prompts it, checks
+it, and decides what happens next — until the goal is met or it hands back to you.
+
+Karajan is a loop-engineering runtime, built around the loop before the term
+caught on:
+
+- **Maker / checker split** — a coder against independent reviewer / tester /
+  security roles, with Solomon judging disputes. The maker never grades its own work.
+- **Deterministic verification** — TDD, per-HU acceptance tests, SonarQube gates,
+  and deterministic guards. Checking is tests, not vibes.
+- **The autonomy ladder (L1 → L2 → L3)** — the `interactive | assisted |
+  autonomous` axis (v3.7.0). Report, then assisted fixes, then unattended
+  `kj autorun` — defaulting to `interactive`, so you opt in.
+- **A durable state spine** — sessions, the HU Board, journals, the RAG index and
+  `kj resume` keep the loop alive outside any one conversation.
+
+The honest caveat loop engineering insists on — *unattended loops make unattended
+mistakes* — is designed in: autonomous runs list their residual defects, every HU
+lands behind a PR, and `kj-trash` snapshots destructive operations.
+
+Full mapping of the loop-engineering building blocks onto Karajan:
+**[docs/loop-engineering.md](./docs/loop-engineering.md)**.
+
 ## Install
 
 **npm** (recommended):
@@ -83,6 +110,8 @@ npm install -g karajan-code
 brew install manufosela/tap/karajan-code
 ```
 
+> **Installing with pnpm?** pnpm blocks dependency build scripts by default, so `better-sqlite3`'s native addon won't compile on install and DB-backed commands (`board`, `rag`, cost tracking) will fail. After installing, run `pnpm approve-builds better-sqlite3` — or just use npm. `kj doctor` flags this if it happens.
+
 **Standalone binary** (no Node.js needed):
 ```bash
 # macOS (Apple Silicon)

package/package.json

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

package/scripts/verify-pack.mjs

@@ -50,6 +50,7 @@ function fail(msg, detail) {
 
 let tgzPath = null;
 let tmpDir = null;
+let pnpmTmp = null;
 try {
   console.log(`verify-pack: packing karajan-code@${expectedVersion}…`);
   // --json gives us the exact filename without parsing human output.
@@ -114,8 +115,48 @@ try {
   }
   console.log("verify-pack: kj-trash ships + boots ✓");
 
+  // 5. 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).
+  // Verify a pnpm install resolves the JS tree and `kj --version` boots — every
+  // release catches a pnpm packaging regression. (pnpm also blocks
+  // better-sqlite3's native build by default, so DB-backed commands need
+  // `pnpm approve-builds`; that's surfaced as a doctor warning, KJC-BUG-0092 —
+  // not a gate failure, since it's inherent to pnpm.) Auto-skips without pnpm.
+  const hasPnpm = spawnSync("pnpm", ["--version"], { encoding: "utf8", env: childEnv }).status === 0;
+  if (!hasPnpm) {
+    console.log("verify-pack: pnpm not installed — skipping pnpm smoke (npm path covered above) ⚠");
+  } else {
+    pnpmTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-pnpm-"));
+    fs.writeFileSync(
+      path.join(pnpmTmp, "package.json"),
+      JSON.stringify({ name: "kj-verify-pnpm", private: true }),
+    );
+    console.log(`verify-pack: installing the tarball with pnpm into ${pnpmTmp}…`);
+    // pnpm exits non-zero on ERR_PNPM_IGNORED_BUILDS (it skips native build
+    // scripts by default) — expected here, so don't treat the exit as failure.
+    spawnSync("pnpm", ["add", tgzPath, "--store-dir", path.join(pnpmTmp, ".store")], {
+      encoding: "utf8",
+      env: childEnv,
+      cwd: pnpmTmp,
+    });
+    const pnpmBin = path.join(pnpmTmp, "node_modules", ".bin", "kj");
+    if (!fs.existsSync(pnpmBin)) fail(`kj binary missing after pnpm install: ${pnpmBin}`);
+    let pnpmVersion;
+    try {
+      pnpmVersion = run(pnpmBin, ["--version"], { cwd: pnpmTmp }).trim();
+    } catch (err) {
+      fail("`kj --version` crashed under a pnpm install (packaging regression)", err.stderr || err.message);
+    }
+    if (!pnpmVersion.includes(expectedVersion)) {
+      fail(`kj --version under pnpm returned "${pnpmVersion}", expected ${expectedVersion}`);
+    }
+    console.log(`verify-pack: pnpm install + kj --version → ${pnpmVersion} ✓ (DB build needs \`pnpm approve-builds\`)`);
+  }
+
   console.log(`\n✓ verify-pack: karajan-code@${expectedVersion} installs clean and runs.`);
 } finally {
   if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });
   if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  if (pnpmTmp && fs.existsSync(pnpmTmp)) fs.rmSync(pnpmTmp, { recursive: true, force: true });
 }

package/src/agents/availability.js

@@ -29,3 +29,24 @@ export async function assertAgentsAvailable(agentNames = []) {
   }
   throw new Error(lines.join("\n"));
 }
+
+/**
+ * Non-throwing counterpart to assertAgentsAvailable: probe each agent CLI in
+ * parallel and return the subset whose `--version` succeeds. Used by the
+ * audit fallback (KJC-BUG-0094) to skip uninstalled providers instead of
+ * aborting the whole command when any one is missing.
+ * @param {string[]} agentNames
+ * @returns {Promise<string[]>}
+ */
+export async function filterAvailableAgents(agentNames = []) {
+  const unique = [...new Set(agentNames.filter(Boolean))];
+  const probes = await Promise.all(
+    unique.map(async (name) => {
+      const meta = getAgentMeta(name);
+      if (!meta?.bin) return null;
+      const res = await runCommand(resolveBin(meta.bin), ["--version"]);
+      return res.exitCode === 0 ? name : null;
+    })
+  );
+  return probes.filter(Boolean);
+}

package/src/audit/audit-fallback.js

@@ -0,0 +1,66 @@
+// Resilient provider/model fallback for the `kj audit` CLI (KJC-BUG-0094).
+// The CLI audit calls AuditRole.executeWithDeterministic directly, bypassing
+// the orchestrator's recovery paths, so a dead configured model (e.g. an
+// inherited "claude-fable-5") killed the command. The LLM phase now tries:
+// configured provider+model → same provider default model → remaining known
+// providers. First success wins; the deterministic context is reused.
+import { resolveRole } from "../config.js";
+import { AuditRole } from "../roles/audit-role.js";
+
+const KNOWN_PROVIDERS = ["claude", "codex", "gemini"];
+
+/** Ordered, de-duplicated fallback candidates for the audit role. */
+export function buildAuditFallbackCandidates(config) {
+  const effective = resolveRole(config, "audit");
+  const primary = effective.provider || "claude";
+  const candidates = [{ provider: primary, model: effective.model ?? null }];
+  if (effective.model) candidates.push({ provider: primary, model: null });
+  for (const p of KNOWN_PROVIDERS) {
+    if (p !== primary) candidates.push({ provider: p, model: null });
+  }
+  const seen = new Set();
+  return candidates.filter((c) => {
+    const key = `${c.provider}::${c.model ?? ""}`;
+    return seen.has(key) ? false : (seen.add(key), true);
+  });
+}
+
+// Pin the audit role to a provider/model. Sets BOTH the per-role override and
+// `coder_options.model` (the audit role inherits its model from the coder
+// bucket); a null model neutralizes both so the provider default is used.
+export function withAuditProvider(config, provider, model) {
+  return {
+    ...config,
+    roles: { ...(config?.roles || {}), audit: { ...(config?.roles?.audit || {}), provider, model: model ?? undefined } },
+    coder_options: { ...(config?.coder_options || {}), model: model ?? undefined },
+  };
+}
+
+/** Run the audit LLM phase with automatic provider/model fallback. */
+export async function runAuditWithFallback({
+  config, logger, roleInput, deterministicCtx, available, candidates, onFallback, createRole,
+}) {
+  const makeRole = createRole || ((cfg) => new AuditRole({ config: cfg, logger }));
+  const all = candidates || buildAuditFallbackCandidates(config);
+  const usable = available ? all.filter((c) => available.includes(c.provider)) : all;
+  if (usable.length === 0) {
+    throw new Error("No available audit provider — install claude, codex, or gemini, or set roles.audit.provider");
+  }
+
+  let last = null;
+  let attempts = 0;
+  for (const cand of usable) {
+    attempts += 1;
+    if (attempts > 1) onFallback?.(cand, attempts);
+    const role = makeRole(withAuditProvider(config, cand.provider, cand.model));
+    const meta = { provider: cand.provider, model: cand.model ?? null };
+    try {
+      const result = await role.executeWithDeterministic(roleInput, deterministicCtx);
+      if (result?.ok) return { ...result, ...meta, attempts };
+      last = { ...result, ...meta };
+    } catch (err) {
+      last = { ok: false, result: { error: err.message, provider: cand.provider }, summary: `Audit failed: ${err.message}`, ...meta };
+    }
+  }
+  return { ...last, attempts, exhausted: true };
+}

package/src/checks/native-build.js

@@ -0,0 +1,64 @@
+/**
+ * Native build availability check (KJC-BUG-0092).
+ *
+ * better-sqlite3 ships a native addon compiled in a postinstall step. pnpm
+ * blocks dependency build scripts by default (ERR_PNPM_IGNORED_BUILDS), so a
+ * `pnpm add -g karajan-code` leaves the addon uncompiled: `kj --version` still
+ * works (it never opens a DB) but any DB-backed command (board, rag, cost
+ * tracking) crashes with "Cannot find module 'better-sqlite3'". This surfaces a
+ * WARN in `kj doctor` with the exact remedy instead of a cryptic runtime crash.
+ */
+
+import { STRATEGY } from "./types.js";
+
+/** pnpm lays packages out under a `.pnpm` virtual store and symlinks them in. */
+function isPnpmInstall() {
+  return (
+    import.meta.url.includes("/.pnpm/") ||
+    (process.env.npm_config_user_agent || "").includes("pnpm")
+  );
+}
+
+/** Force the native binding to load by opening an in-memory database. */
+async function defaultLoadDb() {
+  const Database = (await import("better-sqlite3")).default;
+  new Database(":memory:").close();
+}
+
+export function createNativeBuildCheck({ loadDb = defaultLoadDb, isPnpm = isPnpmInstall } = {}) {
+  return {
+    name: "native-build",
+    label: "native modules (better-sqlite3)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        await loadDb();
+        return {
+          ok: true,
+          severity: "info",
+          detail: "better-sqlite3 native addon loads — DB-backed commands available",
+        };
+      } catch (err) {
+        const firstLine = String(err?.message || err).split("\n")[0];
+        if (isPnpm()) {
+          return {
+            ok: false,
+            severity: "warn",
+            detail: "better-sqlite3 native build was skipped — pnpm blocks dependency build scripts by default",
+            fix: "Approve the build then reinstall: `pnpm approve-builds better-sqlite3` — or install with npm: `npm i -g karajan-code`",
+          };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `better-sqlite3 failed to load: ${firstLine}`,
+          fix: "Reinstall to rebuild native modules: `npm i -g karajan-code`",
+        };
+      }
+    },
+  };
+}
+
+export function getNativeBuildChecks() {
+  return [createNativeBuildCheck()];
+}

package/src/commands/audit.js

@@ -3,10 +3,11 @@ import fs from "node:fs/promises";
 import readline from "node:readline";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { assertAgentsAvailable } from "../agents/availability.js";
+import { assertAgentsAvailable, filterAvailableAgents } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { AUDIT_DIMENSIONS } from "../prompts/audit.js";
 import { AuditRole } from "../roles/audit-role.js";
+import { buildAuditFallbackCandidates, runAuditWithFallback } from "../audit/audit-fallback.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { runAgentReadiness, formatAgentReadinessReport } from "../audit/agent-readiness.js";
@@ -260,7 +261,11 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
 
   return withCliRunLog("audit", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
     const auditRoleConfig = resolveRole(config, "audit");
-    await assertAgentsAvailable([auditRoleConfig.provider]);
+    // KJC-BUG-0094: proceed if any fallback candidate is installed; throw only when NONE are.
+    const fallbackCandidates = buildAuditFallbackCandidates(config);
+    const candidateProviders = [...new Set(fallbackCandidates.map((c) => c.provider))];
+    const available = await filterAvailableAgents(candidateProviders);
+    if (available.length === 0) await assertAgentsAvailable([auditRoleConfig.provider]);
     logger.info(`Audit (${auditRoleConfig.provider}) starting...`);
     runLog.logText(`[audit] provider=${auditRoleConfig.provider} dimensions=${dimensions || "all"} deterministicOnly=${deterministicOnly}`);
 
@@ -347,7 +352,18 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
     const progress = createCliProgressReporter({ role: "auditor" });
     let roleResult;
     try {
-      roleResult = await role.executeWithDeterministic({ ...roleInput, onOutput: progress.onOutput }, deterministicCtx);
+      // KJC-BUG-0094: resilient fallback — if the configured provider/model
+      // is down (e.g. an inherited model like "claude-fable-5" is offline),
+      // degrade to the provider default, then to the next installed provider,
+      // reusing the deterministic context so no static analysis is re-run.
+      roleResult = await runAuditWithFallback({
+        config, logger,
+        roleInput: { ...roleInput, onOutput: progress.onOutput },
+        deterministicCtx,
+        available,
+        candidates: fallbackCandidates,
+        onFallback: (cand) => logger.warn(`Audit provider fallback → ${cand.provider}${cand.model ? ` (${cand.model})` : " (default model)"}`),
+      });
       progress.finish(roleResult.ok ? "done" : "failed");
     } catch (err) { progress.finish("failed"); throw err; }
 

package/src/commands/board.js

@@ -77,15 +77,18 @@ async function findAvailablePort(desiredPort, maxTries = 10) {
 
 /**
  * Build the board URL. When `projectSlug` is provided, the URL points at
- * the per-project view (`/p/<slug>`) so the caller's project shows up
- * pre-filtered instead of "All projects".
+ * the per-project view via the SPA hash route (`#board/<slug>`) so the
+ * caller's project shows up pre-filtered instead of "All projects". The
+ * frontend router is hash-based (see public/utils/init-listeners.js); a
+ * real `/p/<slug>` path is not a route and silently falls back to the
+ * global dashboard. KJC-BUG-0093.
  * @param {number} port
  * @param {string|null} [projectSlug]
  * @returns {string}
  */
-function buildBoardUrl(port, projectSlug) {
+export function buildBoardUrl(port, projectSlug) {
   const base = `http://localhost:${port}`;
-  return projectSlug ? `${base}/p/${projectSlug}` : base;
+  return projectSlug ? `${base}/#board/${projectSlug}` : base;
 }
 
 /**

package/src/commands/doctor.js

@@ -26,6 +26,7 @@ import { getSqueezrChecks } from "../checks/squeezr.js";
 import { getAiTrashChecks } from "../checks/ai-trash.js";
 import { getQmdChecks } from "../checks/qmd.js";
 import { getNodeChecks } from "../checks/node.js";
+import { getNativeBuildChecks } from "../checks/native-build.js";
 import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
 import { getMcpHealthChecks } from "../checks/mcp-health.js";
@@ -54,6 +55,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
   return [
     ...getSystemChecks(),
     ...getNodeChecks(),
+    ...getNativeBuildChecks(),
     ...getHardwareChecks(),
     ...getDirSetupChecks(),
     ...getConfigFileChecks(),

package/src/commands/plan/generate.js

@@ -513,8 +513,8 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       const { projectSlug: slugFor } = await import("../../plan/plan-store.js");
       const boardPort = config?.hu_board?.port ?? 4000;
       // `projectSlug` scopes the board URL to this project's view
-      // (`/p/<slug>`) instead of the global "All projects" dashboard. The
-      // board UI hides multi-project chrome when it sees that prefix.
+      // (`#board/<slug>`) instead of the global "All projects" dashboard.
+      // The hash route opens the board pre-filtered to that project.
       const boardResult = await startBoard(boardPort, { projectSlug: slugFor(projectDir) });
       const status = boardResult.alreadyRunning ? "already running" : "started";
       console.log(renderBoardBanner({ url: boardResult.url, status, projectName: plan.name }));

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

@@ -347,8 +347,8 @@ export async function tryAutoStartBoard(config, logger, emitter, eventBase) {
   try {
     const { startBoard, renderBoardBanner } = await import("../../commands/board.js");
     const boardPort = config.hu_board.port || 4000;
-    // Scope the board URL to the current run's project (`/p/<slug>`) so
-    // the user lands on a filtered view, not the global dashboard.
+    // Scope the board URL to the current run's project (`#board/<slug>`)
+    // so the user lands on a filtered view, not the global dashboard.
     const slug = config.projectDir ? slugFor(config.projectDir) : null;
     const boardResult = await startBoard(boardPort, { projectSlug: slug });
     const status = boardResult.alreadyRunning ? "already running" : "started";

package/src/utils/wizard.js

@@ -1,7 +1,7 @@
 import readline from "node:readline";
 
-export function createWizard(input = process.stdin, output = process.stdout) {
-  const rl = readline.createInterface({ input, output, terminal: false });
+export function createWizard(inputStream = process.stdin, output = process.stdout) {
+  const rl = readline.createInterface({ input: inputStream, output, terminal: false });
 
   function ask(question) {
     return new Promise((resolve) => {
@@ -16,6 +16,12 @@ export function createWizard(input = process.stdin, output = process.stdout) {
     return /^y(es)?$/i.test(answer);
   }
 
+  async function input(question, defaultValue = "") {
+    const hint = defaultValue !== "" ? ` [${defaultValue}]` : "";
+    const answer = await ask(`${question}${hint} `);
+    return answer === "" ? defaultValue : answer;
+  }
+
   async function select(question, options) {
     output.write(`${question}\n`);
     for (let i = 0; i < options.length; i++) {
@@ -33,7 +39,7 @@ export function createWizard(input = process.stdin, output = process.stdout) {
     rl.close();
   }
 
-  return { ask, confirm, select, close };
+  return { ask, confirm, input, select, close };
 }
 
 export function isTTY() {