karajan-code 1.38.2 → 1.40.0

package/README.md

@@ -110,87 +110,23 @@ kj-tail --help           # Full options
 **Typical workflow:**
 
 ```
-┌─────────────────────────┐    ┌─────────────────────────┐
-│  Terminal 1              │    │  Terminal 2              │
-│                          │    │                          │
-│  $ claude                │    │  $ kj-tail               │
-│  > implement the next    │    │                          │
-│    priority task         │    │  ├─ 📋 Triage: medium    │
-│                          │    │  ├─ 🔬 Researcher ✅     │
-│  (Claude calls kj_run   │    │  ├─ 🧠 Planner ✅        │
-│   via MCP, you see       │    │  ├─ 🔨 Coder ✅          │
-│   only the final result) │    │  ├─ 🔍 Sonar: OK        │
-│                          │    │  ├─ 👁️ Reviewer ❌       │
-│                          │    │  ├─ ⚖️ Solomon: 2 cond.  │
-│                          │    │  ├─ 🔨 Coder (iter 2) ✅ │
-│                          │    │  ├─ ✅ Review: APPROVED   │
-│                          │    │  ├─ 🧪 Tester: passed    │
-│                          │    │  └─ 🏁 Result: APPROVED  │
-└─────────────────────────┘    └─────────────────────────┘
-```
-
-**Full pipeline example**, a complex task with all roles:
-
-```
-┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
-│                                                                              │
-│  $ claude                                                                    │
-│                                                                              │
-│  > Build a REST API for a booking system. Requirements:                      │
-│  > - Express + TypeScript with Zod validation on every endpoint              │
-│  > - Endpoints: POST /bookings, GET /bookings/:id, PATCH /bookings/:id/cancel│
-│  > - A booking has: id, guestName, roomType (standard|suite|penthouse),      │
-│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
-│  > - Validate: checkOut must be after checkIn, no past dates,                │
-│  >   roomType must be a valid enum value                                     │
-│  > - Cancel returns 409 if already cancelled                                 │
-│  > - Use TDD. Run it through Karajan with architect and planner enabled,     │
-│  >   paranoid review mode. Coder claude, reviewer codex.                     │
-│                                                                              │
-│  Claude calls kj_run via MCP with:                                           │
-│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
-
-┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
-│                                                                              │
-│  kj-tail v1.38.1 — .kj/run.log                                              │
-│                                                                              │
-│  ├─ 📋 Triage: medium (sw) — enabling researcher, architect, planner         │
-│  ├─ ⚙️ Preflight passed — all checks OK                                     │
-│  ├─ 🔬 Researcher: 8 files analyzed, 3 patterns, 5 constraints              │
-│  ├─ 🏗️ Architect: 3-layer design (routes → service → validators)            │
-│  ├─ 🧠 Planner: 6 steps — tests first, then routes, service, validators     │
-│  │                                                                           │
-│  ▶ Iteration 1/5                                                             │
-│  ├─ 🔨 Coder (claude): implemented 3 endpoints + 18 tests                   │
-│  ├─ 📋 TDD: PASS (3 src, 2 test files)                                      │
-│  ├─ 🔍 Sonar: Quality gate OK — 0 blockers                                  │
-│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
-│  │   "Missing 404 for GET nonexistent booking"                               │
-│  │   "Cancel endpoint lacks idempotency test"                                │
-│  ├─ ⚖️ Solomon: approve_with_conditions (2 conditions)                      │
-│  │   "Add 404 response and test for GET /bookings/:id with unknown id"       │
-│  │   "Add test: cancel already-cancelled booking returns 409, not 500"       │
-│  │                                                                           │
-│  ▶ Iteration 2/5                                                             │
-│  ├─ 🔨 Coder (claude): fixed — 22 tests now                                 │
-│  ├─ 📋 TDD: PASS                                                            │
-│  ├─ 🔍 Sonar: OK                                                            │
-│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
-│  ├─ 🧪 Tester: passed — coverage 94%, 22 tests                              │
-│  ├─ 🔒 Security: passed — 0 critical, 1 low (helmet recommended)            │
-│  ├─ 📊 Audit: CERTIFIED (with 3 advisory warnings)                          │
-│  │                                                                           │
-│  🏁 Result: APPROVED                                                         │
-│     🔬 Research: 8 files, 3 patterns identified                              │
-│     🗺 Plan: 6 steps (tests first)                                           │
-│     🧪 Coverage: 94%, 22 tests                                               │
-│     🔒 Security: passed                                                      │
-│     🔍 Sonar: OK                                                             │
-│     💰 Budget: $0.42 (claude: $0.38, codex: $0.04)                           │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
+Terminal 1                       Terminal 2
+
+$ claude                         $ kj-tail
+> implement the next
+  priority task                  [triage]     medium (sw)
+                                 [researcher] 3 patterns, 5 constraints
+(Claude calls kj_run             [planner]    6 steps (tests first)
+ via MCP, you see                [coder]      3 endpoints + 18 tests
+ only the final result)          [tdd]        PASS (3 src, 2 test)
+                                 [sonar]      Quality gate OK
+                                 [reviewer]   REJECTED (2 blocking)
+                                 [solomon]    2 conditions
+                                 [coder]      fixed, 22 tests now
+                                 [reviewer]   APPROVED
+                                 [tester]     94% coverage, 22 tests
+                                 [security]   passed
+                                 Result: APPROVED
 ```
 
 [**Watch the full pipeline demo**](https://karajancode.com#demo): triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.

package/package.json

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

package/src/cli.js

@@ -25,9 +25,14 @@ import { architectCommand } from "./commands/architect.js";
 import { auditCommand } from "./commands/audit.js";
 import { boardCommand } from "./commands/board.js";
 
+import { printUpdateNotice } from "./utils/update-check.js";
+
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
 
+// Non-blocking update check (runs in background, prints after command output)
+printUpdateNotice(PKG_VERSION).catch(() => {});
+
 async function withConfig(commandName, flags, fn) {
   const { config } = await loadConfig();
   const merged = applyRunOverrides(config, flags || {});

package/src/commands/init.js

@@ -158,6 +158,15 @@ async function setupSonarQube(config, logger) {
     logger.info("SonarQube disabled — skipping container setup.");
     return;
   }
+
+  // Check Docker first — if not available, disable sonar gracefully
+  const dockerCheck = await runCommand("docker", ["--version"]);
+  if (dockerCheck.exitCode !== 0) {
+    logger.info("Docker not found — disabling SonarQube. Install Docker to enable it later.");
+    config.sonarqube.enabled = false;
+    return;
+  }
+
   const vmCheck = await checkVmMaxMapCount(os.platform());
   if (!vmCheck.ok) {
     logger.warn(`vm.max_map_count check failed: ${vmCheck.reason}`);
@@ -168,7 +177,9 @@ async function setupSonarQube(config, logger) {
 
   const sonar = await sonarUp();
   if (sonar.exitCode !== 0) {
-    throw new Error(`Failed to start SonarQube: ${sonar.stderr || sonar.stdout}`);
+    logger.info(`SonarQube could not be started — disabling for now. You can enable it later with 'kj sonar start'.`);
+    config.sonarqube.enabled = false;
+    return;
   }
 
   logger.info("SonarQube container started");

package/src/mcp/server-handlers.js

@@ -25,6 +25,8 @@ import { createRunLog, readRunLog } from "../utils/run-log.js";
 import { currentBranch } from "../utils/git.js";
 import { isPreflightAcked, ackPreflight, getSessionOverrides } from "./preflight.js";
 import { ensureBootstrap } from "../bootstrap.js";
+import { validateSovereignty } from "./sovereignty-guard.js";
+import { handleSuggestion } from "./suggest-handler.js";
 
 /**
  * Resolve the user's project directory.
@@ -823,6 +825,19 @@ async function handleRun(a, server, extra) {
       return failPayload(`Invalid taskType "${a.taskType}". Valid values: ${[...validTypes].join(", ")}`);
     }
   }
+
+  // Sovereignty guard: sanitise params and check for active sessions
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const sovereignty = validateSovereignty(a, { projectDir });
+  if (sovereignty.error) {
+    return failPayload(sovereignty.error);
+  }
+  if (sovereignty.warnings.length > 0) {
+    const logger = createLogger("info", "mcp");
+    for (const w of sovereignty.warnings) logger.warn(`[sovereignty] ${w}`);
+  }
+  Object.assign(a, sovereignty.params);
+
   await runBootstrapGate(server, a);
   if (!isPreflightAcked()) {
     // Auto-acknowledge with defaults for autonomous operation
@@ -963,6 +978,17 @@ async function handleScan(a, server) {
   return runKjCommand({ command: "scan", options: a });
 }
 
+async function handleSuggest(a) {
+  if (!a.suggestion) {
+    return failPayload("Missing required field: suggestion");
+  }
+  return handleSuggestion({
+    suggestion: a.suggestion,
+    context: a.context || null,
+    projectDir: a.projectDir || null
+  });
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -986,7 +1012,8 @@ const toolHandlers = {
   kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
   kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
   kj_board:       (a) => handleBoard(a),
-  kj_hu:          (a, server) => handleHu(a, server)
+  kj_hu:          (a, server) => handleHu(a, server),
+  kj_suggest:     (a) => handleSuggest(a)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/sovereignty-guard.js

@@ -0,0 +1,112 @@
+/**
+ * Sovereignty guard for MCP inputs.
+ *
+ * Validates kj_run parameters and rejects host-AI attempts to override
+ * pipeline decisions that Karajan makes internally (triage, hu-reviewer, etc.).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Parameters that the host AI is allowed to pass through without restriction. */
+const ALLOWED_PARAMS = new Set([
+  "task", "projectDir", "pgTask", "pgProject",
+  "planner", "coder", "reviewer", "refactorer",
+  "plannerModel", "coderModel", "reviewerModel", "refactorerModel",
+  "enablePlanner", "enableReviewer", "enableRefactorer", "enableResearcher",
+  "enableTester", "enableSecurity", "enableImpeccable",
+  "enableDiscover", "enableArchitect",
+  "architectModel", "huFile",
+  "enableSerena", "enableBecaria",
+  "reviewerFallback", "reviewerRetries",
+  "mode", "maxIterations", "maxIterationMinutes", "maxTotalMinutes",
+  "baseBranch", "baseRef", "methodology",
+  "autoCommit", "autoPush", "autoPr", "autoRebase", "branchPrefix",
+  "autoSimplify", "smartModels", "checkpointInterval",
+  "taskType", "quiet", "noSonar", "enableSonarcloud",
+  "kjHome", "sonarToken", "timeoutMs",
+  // Sovereign flags — validated below but still "known"
+  "enableTriage", "enableHuReviewer",
+]);
+
+const MIN_ITERATIONS = 1;
+const MAX_ITERATIONS = 10;
+const ACTIVE_SESSION_THRESHOLD_MS = 60_000;
+
+/**
+ * Check if a pipeline is already running for this project.
+ * Looks at .kj/run.log modification time.
+ *
+ * @param {string} projectDir - Project root directory
+ * @returns {{ active: boolean, message?: string }}
+ */
+export function checkActiveSession(projectDir) {
+  if (!projectDir) return { active: false };
+  const logPath = path.join(projectDir, ".kj", "run.log");
+  try {
+    const stat = fs.statSync(logPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < ACTIVE_SESSION_THRESHOLD_MS) {
+      return {
+        active: true,
+        message:
+          "A pipeline is already running for this project. " +
+          "Wait for it to complete or use kj_status to check progress.",
+      };
+    }
+  } catch {
+    // File doesn't exist or can't be read — no active session
+  }
+  return { active: false };
+}
+
+/**
+ * Validate and sanitise kj_run parameters.
+ *
+ * @param {Record<string, unknown>} params - Raw parameters from the MCP call
+ * @param {{ projectDir?: string }} context - Runtime context
+ * @returns {{ params: Record<string, unknown>, warnings: string[], error?: string }}
+ */
+export function validateSovereignty(params, context = {}) {
+  const warnings = [];
+  const sanitized = { ...params };
+
+  // 1. Strip unknown parameters
+  for (const key of Object.keys(sanitized)) {
+    if (!ALLOWED_PARAMS.has(key)) {
+      warnings.push(`Unknown parameter "${key}" stripped`);
+      delete sanitized[key];
+    }
+  }
+
+  // 2. Sovereign flags — pipeline decides, not the host AI
+  if (sanitized.enableHuReviewer === false) {
+    warnings.push("Pipeline decides hu-reviewer activation, ignoring override");
+    delete sanitized.enableHuReviewer;
+  }
+
+  if (sanitized.enableTriage === false) {
+    warnings.push("Triage is mandatory, ignoring override");
+    delete sanitized.enableTriage;
+  }
+
+  // 3. Clamp maxIterations to [1, 10]
+  if (sanitized.maxIterations !== undefined) {
+    const n = Number(sanitized.maxIterations);
+    if (!Number.isFinite(n) || n < MIN_ITERATIONS) {
+      warnings.push(`maxIterations ${sanitized.maxIterations} clamped to ${MIN_ITERATIONS}`);
+      sanitized.maxIterations = MIN_ITERATIONS;
+    } else if (n > MAX_ITERATIONS) {
+      warnings.push(`maxIterations ${sanitized.maxIterations} clamped to ${MAX_ITERATIONS}`);
+      sanitized.maxIterations = MAX_ITERATIONS;
+    }
+  }
+
+  // 4. Active session detection
+  const session = checkActiveSession(context.projectDir);
+  if (session.active) {
+    return { params: sanitized, warnings, error: session.message };
+  }
+
+  return { params: sanitized, warnings };
+}

package/src/mcp/suggest-handler.js

@@ -0,0 +1,91 @@
+/**
+ * Handler for kj_suggest MCP tool.
+ * Allows the host AI to propose observations to Solomon without override power.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSessionRoot } from "../utils/paths.js";
+
+/**
+ * Find the most recent running session for a given projectDir.
+ * If projectDir is not provided, returns the most recent running session overall.
+ */
+async function findActiveSession(projectDir) {
+  const sessionRoot = getSessionRoot();
+  let entries;
+  try {
+    entries = await fs.readdir(sessionRoot, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+  // Walk backwards (most recent first)
+  for (let i = dirs.length - 1; i >= 0; i--) {
+    try {
+      const raw = await fs.readFile(path.join(sessionRoot, dirs[i], "session.json"), "utf8");
+      const session = JSON.parse(raw);
+      if (session.status !== "running") continue;
+      if (projectDir && session.projectDir && session.projectDir !== projectDir) continue;
+      return session;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Handle a suggestion from the host AI.
+ * Logs it to the active session's suggestions array for Solomon to evaluate.
+ *
+ * @param {object} params
+ * @param {string} params.suggestion - The observation or proposal
+ * @param {string} [params.context] - Additional context
+ * @param {string} [params.projectDir] - Project directory to scope session lookup
+ * @returns {Promise<object>} Result with accepted status and message
+ */
+export async function handleSuggestion({ suggestion, context, projectDir }) {
+  if (!suggestion || typeof suggestion !== "string" || suggestion.trim() === "") {
+    return {
+      accepted: false,
+      reason: "Suggestion text is required and must be a non-empty string."
+    };
+  }
+
+  const session = await findActiveSession(projectDir);
+
+  if (!session) {
+    return {
+      accepted: false,
+      reason: "No active pipeline session. Suggestions are only evaluated during pipeline execution."
+    };
+  }
+
+  // Initialize suggestions array if not present
+  if (!Array.isArray(session.suggestions)) {
+    session.suggestions = [];
+  }
+
+  const entry = {
+    suggestion: suggestion.trim(),
+    context: context || null,
+    timestamp: new Date().toISOString()
+  };
+
+  session.suggestions.push(entry);
+
+  // Persist the updated session
+  const sessionRoot = getSessionRoot();
+  const sessionFile = path.join(sessionRoot, session.id, "session.json");
+  session.updated_at = new Date().toISOString();
+  await fs.writeFile(sessionFile, JSON.stringify(session, null, 2), "utf8");
+
+  return {
+    accepted: true,
+    status: "logged",
+    sessionId: session.id,
+    message: "Suggestion logged for Solomon evaluation in next iteration. Solomon will decide whether to act on it."
+  };
+}

package/src/mcp/tools.js

@@ -334,5 +334,18 @@ export const tools = [
         projectDir: { type: "string", description: "Project directory (defaults to cwd)" }
       }
     }
+  },
+  {
+    name: "kj_suggest",
+    description: "Propose an observation or suggestion to Karajan's Solomon engine. Solomon will evaluate it and decide whether to accept, reject, or ask the human. You CANNOT override pipeline decisions through this tool, only propose.",
+    inputSchema: {
+      type: "object",
+      required: ["suggestion"],
+      properties: {
+        suggestion: { type: "string", description: "What you observed or want to propose" },
+        context: { type: "string", description: "Additional context (current HU, iteration, etc.)" },
+        projectDir: { type: "string", description: "Project directory" }
+      }
+    }
   }
 ];

package/src/orchestrator/solomon-escalation.js

@@ -1,5 +1,5 @@
 import { SolomonRole } from "../roles/solomon-role.js";
-import { addCheckpoint, pauseSession } from "../session-store.js";
+import { addCheckpoint, pauseSession, saveSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 
 /**
@@ -80,11 +80,19 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
     })
   );
 
+  // Collect pending suggestions from the session for Solomon's context
+  const pendingSuggestions = Array.isArray(session.suggestions) && session.suggestions.length > 0
+    ? session.suggestions.slice()
+    : null;
+
   const solomon = new SolomonRole({ config, logger, emitter });
   await solomon.init({ task: conflict.task || session.task, iteration });
   let ruling;
   try {
-    ruling = await solomon.run({ conflict });
+    const conflictWithSuggestions = pendingSuggestions
+      ? { ...conflict, hostSuggestions: pendingSuggestions }
+      : conflict;
+    ruling = await solomon.run({ conflict: conflictWithSuggestions });
   } catch (err) {
     logger.warn(`Solomon threw: ${err.message}`);
     return escalateToHuman({
@@ -93,6 +101,12 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
     });
   }
 
+  // Clear processed suggestions from session
+  if (pendingSuggestions) {
+    session.suggestions = [];
+    try { await saveSession(session); } catch { /* best-effort */ }
+  }
+
   const solomonError = ruling.result?.error;
   if (!ruling.ok && solomonError) {
     logger.warn(`Solomon execution failed: ${solomonError}`);

package/src/utils/update-check.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "./paths.js";
+
+const CACHE_FILE = "update-check.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const PACKAGE_NAME = "karajan-code";
+
+/**
+ * Check npm for a newer version. Non-blocking, cached for 24h.
+ * Returns { updateAvailable, latest, current } or null if check fails/cached.
+ */
+export async function checkForUpdate(currentVersion) {
+  try {
+    const cachePath = path.join(getKarajanHome(), CACHE_FILE);
+
+    // Check cache first
+    try {
+      const raw = await fs.readFile(cachePath, "utf8");
+      const cache = JSON.parse(raw);
+      if (cache.checkedAt && Date.now() - cache.checkedAt < CACHE_TTL_MS) {
+        if (!cache.latest || cache.latest === currentVersion) return null;
+        return { updateAvailable: true, latest: cache.latest, current: currentVersion };
+      }
+    } catch { /* no cache or expired */ }
+
+    // Fetch from npm (timeout 3s, don't block)
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      signal: controller.signal,
+      headers: { "Accept": "application/json" },
+    });
+    clearTimeout(timeout);
+
+    if (!res.ok) return null;
+    const data = await res.json();
+    const latest = data.version;
+
+    // Save cache
+    await fs.mkdir(getKarajanHome(), { recursive: true });
+    await fs.writeFile(cachePath, JSON.stringify({ latest, checkedAt: Date.now() }), "utf8");
+
+    if (latest === currentVersion) return null;
+    if (compareVersions(latest, currentVersion) > 0) {
+      return { updateAvailable: true, latest, current: currentVersion };
+    }
+    return null;
+  } catch {
+    return null; // Network error, offline, etc. Never block.
+  }
+}
+
+/**
+ * Print update notice if available. Call at CLI startup, non-blocking.
+ */
+export async function printUpdateNotice(currentVersion) {
+  const result = await checkForUpdate(currentVersion);
+  if (result?.updateAvailable) {
+    console.log(`\n  Update available: v${result.current} → v${result.latest}`);
+    console.log(`  Run: npm install -g ${PACKAGE_NAME}\n`);
+  }
+}
+
+/** Simple semver compare: returns >0 if a > b, <0 if a < b, 0 if equal */
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}