@karajan-family/code 4.21.0

package/src/utils/role-assigner.js

@@ -0,0 +1,137 @@
+// Smart role assignment based on available AI agents.
+// Used by both kj init (interactive) and auto-init (non-interactive).
+
+import { detectAvailableAgents } from "./agent-detect.js";
+
+// Agent capability tiers (higher = more capable for complex reasoning)
+const CAPABILITY_TIERS = {
+  claude: 5, // Best for reasoning, orchestration, complex tasks
+  codex: 4,  // Strong coder, good reviewer
+  gemini: 3, // Good general purpose
+  aider: 2,  // Good coder, limited reasoning
+  opencode: 2 // Similar to aider
+};
+
+// Role requirements: what capability level is ideal for each role
+const ROLE_PREFERENCES = {
+  brain: { minTier: 4, prefer: "claude", description: "Karajan Brain (orchestrator)" },
+  // KJC-BUG-0113: Solomon preferred gemini, but Google retired the Gemini
+  // Code Assist CLI for individuals — a binary that answers --version yet
+  // dies with IneligibleTierError on every real call. Any machine with the
+  // stale CLI on PATH got a judge that could never rule. Claude matches
+  // the brain default; diversifyReviewer still picks a different agent
+  // when more than one healthy option exists.
+  solomon: { minTier: 3, prefer: "claude", description: "Solomon (judge/arbiter)" },
+  coder: { minTier: 2, prefer: "claude", description: "Coder" },
+  reviewer: { minTier: 3, prefer: "codex", description: "Reviewer" },
+  planner: { minTier: 4, prefer: "claude", description: "Planner" },
+  researcher: { minTier: 3, prefer: "claude", description: "Researcher" },
+  architect: { minTier: 4, prefer: "claude", description: "Architect" },
+  tester: { minTier: 3, prefer: "claude", description: "Tester" },
+  security: { minTier: 3, prefer: "claude", description: "Security" },
+  triage: { minTier: 3, prefer: "claude", description: "Triage" }
+};
+
+/**
+ * Assign the best available agent to a role.
+ * Prefers the role's preferred agent if available, then falls back by capability tier.
+ */
+function assignRole(roleName, availableAgents) {
+  const pref = ROLE_PREFERENCES[roleName];
+  if (!pref) return availableAgents[0]?.name || "claude";
+
+  // Preferred agent available?
+  if (availableAgents.find(a => a.name === pref.prefer)) {
+    return pref.prefer;
+  }
+
+  // Sort by capability tier (descending) and pick the best available
+  const sorted = [...availableAgents].sort(
+    (a, b) => (CAPABILITY_TIERS[b.name] || 1) - (CAPABILITY_TIERS[a.name] || 1)
+  );
+
+  return sorted[0]?.name || "claude";
+}
+
+/**
+ * Try to diversify: if possible, use a different agent for reviewer than coder.
+ */
+function diversifyReviewer(coderAgent, availableAgents) {
+  const alternatives = availableAgents.filter(a => a.name !== coderAgent);
+  if (alternatives.length === 0) return coderAgent;
+
+  const sorted = [...alternatives].sort(
+    (a, b) => (CAPABILITY_TIERS[b.name] || 1) - (CAPABILITY_TIERS[a.name] || 1)
+  );
+  return sorted[0].name;
+}
+
+/**
+ * Auto-assign all roles based on detected agents. Non-interactive.
+ * Returns a config-ready object with role assignments.
+ */
+export async function autoAssignRoles(logger) {
+  const agents = await detectAvailableAgents();
+  const available = agents.filter(a => a.available);
+
+  if (available.length === 0) {
+    logger?.warn?.("No AI agents detected. Using claude as default for all roles.");
+    return { assignments: getDefaultAssignments("claude"), agents, available: [] };
+  }
+
+  logger?.info?.(`Detected ${available.length} AI agent(s): ${available.map(a => `${a.name} (${a.version})`).join(", ")}`);
+
+  const coder = assignRole("coder", available);
+  const reviewer = available.length > 1 ? diversifyReviewer(coder, available) : coder;
+  const brain = assignRole("brain", available);
+  const solomon = available.length > 1 ? diversifyReviewer(brain, available) : brain;
+
+  const assignments = {
+    brain,
+    solomon,
+    coder,
+    reviewer,
+    planner: assignRole("planner", available),
+    researcher: assignRole("researcher", available),
+    architect: assignRole("architect", available),
+    tester: assignRole("tester", available),
+    security: assignRole("security", available),
+    triage: assignRole("triage", available)
+  };
+
+  logger?.info?.(`Role assignments: Brain=${brain}, Solomon=${solomon}, Coder=${coder}, Reviewer=${reviewer}`);
+
+  return { assignments, agents, available };
+}
+
+function getDefaultAssignments(agent) {
+  return {
+    brain: agent, solomon: agent, coder: agent, reviewer: agent,
+    planner: agent, researcher: agent, architect: agent,
+    tester: agent, security: agent, triage: agent
+  };
+}
+
+/**
+ * Apply role assignments to a Karajan config object.
+ */
+export function applyRoleAssignments(config, assignments) {
+  config.coder = assignments.coder;
+  config.reviewer = assignments.reviewer;
+
+  const roleNames = ["coder", "reviewer", "planner", "researcher", "architect",
+    "tester", "security", "triage", "solomon"];
+
+  for (const role of roleNames) {
+    config.roles = config.roles || {};
+    config.roles[role] = config.roles[role] || {};
+    config.roles[role].provider = assignments[role] || assignments.coder;
+  }
+
+  // Brain is a new top-level config (not in roles yet — will be when KarajanBrainRole is implemented)
+  config.brain = { provider: assignments.brain };
+
+  return config;
+}
+
+export { CAPABILITY_TIERS };

package/src/utils/role-env.js

@@ -0,0 +1,58 @@
+/**
+ * role-env — env allowlist for agent subprocesses (KJC-TSK-0693).
+ *
+ * Agents inherit only what their function requires: system essentials, the
+ * spawned CLI's own auth/config vars, and KJ_* lane vars. Long-lived secrets
+ * that no agent needs (cloud keys, registry tokens, DB URLs) never reach the
+ * child, so a compromised agent or an injected prompt cannot exfiltrate them.
+ * Escapes: `security.env_passthrough` (exact names or trailing-* globs) and
+ * `security.env_allowlist: false` to disable filtering entirely.
+ */
+
+const EXACT = new Set([
+  "PATH", "Path", "HOME", "USER", "LOGNAME", "SHELL", "TERM", "COLORTERM", "LANG",
+  "TZ", "TMPDIR", "TMP", "TEMP", "EDITOR", "CI", "OLLAMA_HOST",
+  // Windows child-process essentials: executable resolution and profile dirs.
+  "SystemRoot", "SYSTEMROOT", "windir", "COMSPEC", "ComSpec", "PATHEXT",
+  "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "APPDATA", "LOCALAPPDATA", "PROGRAMDATA",
+  // SSH agent socket: local-only handle, needed for git fetch/pull over SSH
+  // inside worktrees. Unusable off-machine, unlike a long-lived token.
+  "SSH_AUTH_SOCK", "SSH_AGENT_PID",
+  "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "http_proxy", "https_proxy", "no_proxy",
+]);
+
+// Per-CLI auth/config families. GOOGLE_ covers GOOGLE_APPLICATION_CREDENTIALS
+// (gemini via Vertex); npm_ covers npm_config_* that Node tooling reads.
+const PREFIXES = [
+  "LC_", "XDG_", "KJ_", "NODE_", "npm_",
+  "ANTHROPIC_", "CLAUDE", "OPENAI_", "CODEX", "GEMINI", "GOOGLE_",
+  "QWEN", "DASHSCOPE_", "OPENCODE", "AIDER_", "OPENROUTER_",
+];
+
+// Vars only ONE agent authenticates with — granting them globally would
+// defeat the point (the coder does not need your GitHub token; copilot does).
+export const AGENT_EXTRAS = {
+  copilot: ["GITHUB_", "GH_"],
+  kimi: ["KIMI_", "MOONSHOT_"],
+};
+
+const matches = (pattern, key) =>
+  pattern.endsWith("*") ? key.startsWith(pattern.slice(0, -1)) : key === pattern;
+
+/**
+ * Filter an environment down to what the given agent's subprocess needs.
+ * @param {Record<string,string|undefined>} base - env to filter
+ * @param {{agent?: string|null, passthrough?: string[]}} [opts]
+ * @returns {Record<string,string|undefined>}
+ */
+export function buildAgentEnv(base = process.env, { agent = null, passthrough = [] } = {}) {
+  const prefixes = [...PREFIXES, ...(AGENT_EXTRAS[agent] || [])];
+  const out = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (EXACT.has(key) || prefixes.some((p) => key.startsWith(p)) || passthrough.some((p) => matches(p, key))) {
+      out[key] = value;
+    }
+  }
+  return out;
+}

package/src/utils/rtk-detect.js

@@ -0,0 +1,18 @@
+import { runCommand } from "./process.js";
+
+/**
+ * Detect whether RTK (Rust Token Killer) is installed and available.
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectRtk() {
+  try {
+    const result = await runCommand("rtk", ["--version"]);
+    if (result.exitCode === 0) {
+      const version = (result.stdout || "").trim() || null;
+      return { available: true, version };
+    }
+    return { available: false, version: null };
+  } catch { /* rtk binary not found */
+    return { available: false, version: null };
+  }
+}

package/src/utils/rtk-install.js

@@ -0,0 +1,38 @@
+import { runCommand } from "./process.js";
+import { getInstallCommand } from "./os-detect.js";
+import { detectRtk } from "./rtk-detect.js";
+
+/**
+ * Install RTK (Rust Token Killer) using the OS-appropriate command.
+ * @param {object} logger - Logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, version: string|null, error: string|null }>}
+ */
+export async function installRtk(logger) {
+  const command = getInstallCommand("rtk");
+
+  logger.info("Installing RTK (Rust Token Killer)...");
+
+  try {
+    const result = await runCommand("sh", ["-c", command], { timeout: 120_000 });
+
+    if (result.exitCode !== 0) {
+      const error = (result.stderr || "").trim() || `exit code ${result.exitCode}`;
+      logger.warn(`RTK install failed: ${error}`);
+      return { ok: false, version: null, error };
+    }
+
+    // Verify installation
+    const check = await detectRtk();
+    if (check.available) {
+      logger.info(`RTK ${check.version || ""} installed successfully.`);
+      return { ok: true, version: check.version, error: null };
+    }
+
+    logger.warn("RTK install command succeeded but rtk binary not found in PATH.");
+    return { ok: false, version: null, error: "Binary not found after install" };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`RTK install failed: ${error}`);
+    return { ok: false, version: null, error };
+  }
+}

package/src/utils/rtk-wrapper.js

@@ -0,0 +1,87 @@
+import { runCommand } from "./process.js";
+
+/**
+ * Commands that RTK can safely wrap for token-optimized output.
+ */
+export const RTK_SUPPORTED_COMMANDS = [
+  "git", "ls", "find", "grep", "cat", "head", "tail",
+  "wc", "diff", "tree", "du", "file"
+];
+
+const supportedSet = new Set(RTK_SUPPORTED_COMMANDS);
+
+/**
+ * Wrap a command with RTK if available and the command is in the whitelist.
+ * @param {string} command
+ * @param {string[]} args
+ * @param {boolean} rtkAvailable
+ * @returns {{ command: string, args: string[] }}
+ */
+export function wrapWithRtk(command, args, rtkAvailable) {
+  if (rtkAvailable && supportedSet.has(command)) {
+    return { command: "rtk", args: [command, ...args] };
+  }
+  return { command, args };
+}
+
+/**
+ * Session-level accumulator for RTK byte savings.
+ */
+export class RtkSavingsTracker {
+  constructor() {
+    this.originalBytes = 0;
+    this.rtkBytes = 0;
+    this.callCount = 0;
+  }
+
+  record(originalSize, rtkSize) {
+    this.originalBytes += originalSize;
+    this.rtkBytes += rtkSize;
+    this.callCount += 1;
+  }
+
+  summary() {
+    const savedBytes = this.originalBytes - this.rtkBytes;
+    const savedPct = this.originalBytes > 0
+      ? Number(((savedBytes / this.originalBytes) * 100).toFixed(1))
+      : 0;
+    const estimatedTokensSaved = Math.floor(savedBytes / 4);
+    return {
+      originalBytes: this.originalBytes,
+      rtkBytes: this.rtkBytes,
+      savedBytes,
+      savedPct,
+      estimatedTokensSaved,
+      callCount: this.callCount
+    };
+  }
+
+  /** Returns true if any commands were recorded. */
+  hasData() {
+    return this.callCount > 0;
+  }
+}
+
+/**
+ * Create a runner function that transparently wraps supported commands with RTK.
+ * @param {boolean} rtkAvailable
+ * @param {RtkSavingsTracker} [tracker] - Optional savings tracker
+ * @returns {(command: string, args?: string[], options?: object) => Promise<object>}
+ */
+export function createRtkRunner(rtkAvailable, tracker = null) {
+  return async (command, args = [], options = {}) => {
+    const wrapped = wrapWithRtk(command, args, rtkAvailable);
+    const result = await runCommand(wrapped.command, wrapped.args, options);
+
+    if (tracker && rtkAvailable && supportedSet.has(command)) {
+      const outputSize = Buffer.byteLength(result.stdout || "", "utf8");
+      // For RTK-wrapped calls, the output is already compressed.
+      // We estimate the original size as outputSize (conservative — real savings
+      // would require running the command without RTK, which defeats the purpose).
+      // The tracker is useful when the caller provides real estimates externally.
+      tracker.record(outputSize, outputSize);
+    }
+
+    return result;
+  };
+}

package/src/utils/run-context.js

@@ -0,0 +1,75 @@
+/**
+ * Per-run context store — makes module-level state in `utils/git.js`,
+ * `review/diff-generator.js`, etc. safe under concurrent `runFlow` calls.
+ *
+ * Pre-v2.7.5 the orchestrator mutated module-scope variables at pipeline
+ * start:
+ *   setDiffRunner(rtkRunner); setDiffProjectDir(diffScope);
+ *   setGitRunner(rtkRunner);
+ *   // …later…
+ *   // every git/diff op reads those globals
+ *
+ * That is fine for a single-threaded CLI invocation but corrupts when the
+ * MCP server fields two `kj_run` tool calls in parallel: each run would
+ * overwrite the others' runner/projectDir during setup, and subsequent
+ * reads would see a mix.
+ *
+ * TSK-0338 isolates that state to a per-run AsyncLocalStorage scope.
+ * `runFlow` wraps its execution in `withRunContext(ctx, fn)`, and the
+ * read paths in git.js / diff-generator.js look up
+ * `getRunContext()?.runner` before falling back to the module-level
+ * `_runner` (kept as a back-compat entry for callers outside a
+ * `runFlow` — CLI helpers, tests — that set state directly).
+ *
+ * What lives here vs. elsewhere:
+ *   - `runContext` (this module) — runner, projectDir, snapshot — the
+ *     pieces git/diff touches synchronously on every op.
+ *   - `PipelineContext` (src/orchestrator/pipeline-context.js) — the
+ *     richer structure ferried between stages. The two could merge
+ *     eventually, but PipelineContext is created after preflight, and
+ *     the runner/projectDir must be in scope BEFORE preflight runs
+ *     (which itself calls git commands).
+ *
+ * The invariant `tests/orchestrator/concurrent-runs.test.js` exercises
+ * the isolation: two parallel `withRunContext(A, …)` and
+ * `withRunContext(B, …)` see their own runner, not each other's.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * @typedef {Object} RunContext
+ * @property {((command: string, args?: string[], options?: object) => Promise<object>)|null} [runner]
+ *   Pipeline-scoped command runner. When present, git.js + diff-generator.js
+ *   route commands through it instead of the default `runCommand`.
+ * @property {string|null} [projectDir]
+ *   Directory scope for `git diff`. Prevents leaking unrelated subdir
+ *   changes when `kj run` is invoked from a subpath of a monorepo.
+ * @property {Map<string, string>|null} [snapshot]
+ *   Pre-coder filesystem snapshot for snapshot-based diff when git is
+ *   unavailable (greenfield projects with no initial commit).
+ */
+
+const runStore = new AsyncLocalStorage();
+
+/**
+ * Run `fn` with `ctx` as the active RunContext. All reads of
+ * `getRunContext()` inside (including from awaited callees) see `ctx`.
+ * Concurrent `withRunContext` invocations are fully isolated from each
+ * other — that's what AsyncLocalStorage guarantees.
+ *
+ * @param {RunContext} ctx
+ * @param {() => Promise<any>} fn
+ * @returns {Promise<any>}
+ */
+export function withRunContext(ctx, fn) {
+  return runStore.run(ctx ?? {}, fn);
+}
+
+/**
+ * @returns {RunContext|undefined} the active RunContext, or undefined when
+ *   called outside any `withRunContext` scope (legacy CLI paths, tests).
+ */
+export function getRunContext() {
+  return runStore.getStore();
+}

package/src/utils/run-log.js

@@ -0,0 +1,217 @@
+/**
+ * File-based run logger.
+ *
+ * Writes progress events to a known file so that external tools
+ * (tail -f, kj_status, another Claude process) can monitor what
+ * Karajan is doing in real time.
+ *
+ * Log location: <projectDir>/.kj/run.log  (overwritten each run)
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const LOG_FILENAME = "run.log";
+
+function resolveLogDir(baseDir) {
+  return path.join(baseDir || process.cwd(), ".kj");
+}
+
+function resolveLogPath(baseDir) {
+  return path.join(resolveLogDir(baseDir), LOG_FILENAME);
+}
+
+function ensureDir(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch { /* already exists */ }
+}
+
+function formatLine(event) {
+  const ts = new Date().toISOString().slice(11, 23);
+  const stage = event.stage || event.detail?.stage || "";
+  const type = event.type || "info";
+  const msg = event.message || "";
+  const extra = [];
+
+  if (event.detail?.provider) extra.push(`agent=${event.detail.provider}`);
+  if (event.detail?.lineCount !== undefined) extra.push(`lines=${event.detail.lineCount}`);
+  if (event.detail?.elapsedMs !== undefined) extra.push(`elapsed=${Math.round(event.detail.elapsedMs / 1000)}s`);
+  if (event.detail?.silenceMs !== undefined) extra.push(`silence=${Math.round(event.detail.silenceMs / 1000)}s`);
+  if (event.detail?.severity) extra.push(`severity=${event.detail.severity}`);
+  if (event.detail?.stream) extra.push(`stream=${event.detail.stream}`);
+  if (event.detail?.cooldownUntil) extra.push(`until=${event.detail.cooldownUntil}`);
+  if (event.detail?.retryCount !== undefined) extra.push(`retry=${event.detail.retryCount}/${event.detail.maxRetries || "?"}`);
+  if (event.detail?.remainingMs !== undefined) extra.push(`remaining=${Math.round(event.detail.remainingMs / 1000)}s`);
+
+  const extraStr = extra.length ? ` (${extra.join(", ")})` : "";
+  const stageStr = stage ? `[${stage}] ` : "";
+  return `${ts} [${type}] ${stageStr}${msg}${extraStr}`;
+}
+
+export function createRunLog(projectDir) {
+  const logPath = resolveLogPath(projectDir);
+  const logDir = resolveLogDir(projectDir);
+  ensureDir(logDir);
+
+  // Truncate/create the log file
+  fs.writeFileSync(logPath, `--- Karajan run started at ${new Date().toISOString()} ---\n`);
+
+  // Audit recommendation (perf-LOW): suggested createWriteStream + queue.
+  // Tried it; broke the contract. `readRunLog` (used by `kj_status`,
+  // `kj-tail`, and the HU board's chokidar tick) reads the file with
+  // `fs.readFileSync` and expects every prior write to be visible the
+  // moment the writer's `logEvent()` returns — which is what
+  // `fs.writeSync(fd, ...)` guarantees and `stream.write()` does NOT.
+  //
+  // The current shape is already opened-once: `fs.openSync(logPath, "a")`
+  // returns an fd that every subsequent `fs.writeSync` reuses (no extra
+  // open/close per call). The hot-path complaint was about the FALLBACK
+  // `fs.appendFileSync` line, which only fires when openSync itself
+  // fails (rare; FS error or RO mount).
+  let fd = null;
+  try {
+    fd = fs.openSync(logPath, "a");
+  } catch {
+    // If we can't open for append, use writeFile fallback
+  }
+
+  function write(line) {
+    try {
+      if (fd === null) {
+        fs.appendFileSync(logPath, line + "\n");
+      } else {
+        fs.writeSync(fd, line + "\n");
+      }
+    } catch { /* best-effort */ }
+  }
+
+  function logEvent(event) {
+    write(formatLine(event));
+  }
+
+  function logText(text) {
+    const ts = new Date().toISOString().slice(11, 23);
+    write(`${ts} ${text}`);
+  }
+
+  function close() {
+    try {
+      if (fd !== null) {
+        fs.closeSync(fd);
+        fd = null;
+      }
+    } catch { /* best-effort */ }
+  }
+
+  return {
+    logEvent,
+    logText,
+    close,
+    get path() { return logPath; }
+  };
+}
+
+const KJ_TOOLS = ["kj_run", "kj_code", "kj_plan"];
+
+function detectRunStart(line, status) {
+  const started = KJ_TOOLS.some(t => line.includes(`[${t}] started`));
+  if (!started) return;
+  status.isRunning = true;
+  status.currentStage = KJ_TOOLS.find(t => line.includes(t));
+  const tsMatch = /^(\d{2}:\d{2}:\d{2}\.\d{3})/.exec(line);
+  if (tsMatch) status.startedAt = tsMatch[1];
+}
+
+function detectRunFinish(line, status) {
+  const isToolFinish = KJ_TOOLS.some(t => line.includes(`[${t}] finished`) || line.includes(`[${t}]`));
+  if (line.includes("finished") && isToolFinish) {
+    status.isRunning = false;
+  }
+}
+
+function detectStageTransitions(line, status) {
+  const stageStart = /\[(\w+):start\]/.exec(line);
+  if (stageStart) status.currentStage = stageStart[1];
+
+  const stageDone = /\[(\w+):done\]|\[(\w+)\] finished/.exec(line);
+  if (stageDone) {
+    const doneName = stageDone[1] || stageDone[2];
+    if (doneName === status.currentStage) status.currentStage = "idle";
+  }
+}
+
+function detectMetadata(line, status) {
+  const agentMatch = /agent=(\w+)/.exec(line);
+  if (agentMatch) status.currentAgent = agentMatch[1];
+
+  const iterMatch = /[Ii]teration\s+(\d+)/.exec(line);
+  if (iterMatch) status.iteration = Number.parseInt(iterMatch[1], 10);
+
+  if (/\[.*:fail\]|\[.*error\]/i.test(line) || line.includes("ERROR")) {
+    status.errors.push(line.trim());
+  }
+
+  if (line.includes("[standby]") || line.includes("standby")) {
+    status.currentStage = "standby";
+  }
+}
+
+/**
+ * Parse the run log to extract current status information.
+ */
+function parseRunStatus(lines) {
+  const status = {
+    currentStage: null,
+    currentAgent: null,
+    startedAt: null,
+    isRunning: false,
+    lastEvent: null,
+    iteration: null,
+    errors: []
+  };
+
+  for (const line of lines) {
+    detectRunStart(line, status);
+    detectRunFinish(line, status);
+    detectStageTransitions(line, status);
+    detectMetadata(line, status);
+    status.lastEvent = line.trim();
+  }
+
+  if (status.errors.length > 3) status.errors = status.errors.slice(-3);
+  return status;
+}
+
+/**
+ * Read the current run log contents.
+ * Returns the last N lines (default 50) plus a parsed status summary.
+ */
+export function readRunLog(projectDir, maxLines = 50) {
+  const logPath = resolveLogPath(projectDir);
+  try {
+    const content = fs.readFileSync(logPath, "utf8");
+    const lines = content.split("\n").filter(Boolean);
+    const total = lines.length;
+    const shown = lines.slice(-maxLines);
+    const status = parseRunStatus(lines);
+    const MAX_LINE_CHARS = 2000;
+    const truncated = shown.map(l => l.length > MAX_LINE_CHARS ? l.slice(0, MAX_LINE_CHARS) + "… [truncated]" : l);
+    return {
+      ok: true,
+      path: logPath,
+      totalLines: total,
+      status,
+      lines: truncated,
+      summary: truncated.join("\n")
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      path: logPath,
+      error: err.code === "ENOENT"
+        ? "No active run log found. Start a run with kj_run first."
+        : `Failed to read log: ${err.message}`
+    };
+  }
+}

package/src/utils/run-registry.js

@@ -0,0 +1,9 @@
+// Shim: run-registry now lives in karajan-core/run-registry so the
+// hu-board workspace can consume it without a relative dep on the CLI
+// src tree. KJC-TSK-0511 PR3.
+export {
+  runsDir,
+  registerRun,
+  unregisterRun,
+  listActiveRuns,
+} from "karajan-core/run-registry";

package/src/utils/shared-paths.js

@@ -0,0 +1,12 @@
+// Shim — the real implementation now lives in karajan-core/shared-paths.
+// Kept here so CLI callers (src/**/*.js) keep importing
+// "../utils/shared-paths.js" without churn during KJC-TSK-0511 (decouple
+// @karajan/hu-board). Will be retired once every consumer migrates to
+// the karajan-core import.
+export {
+  SHARED_DIR_NAME,
+  getSharedRoot,
+  getSharedPlansDir,
+  getSharedHuStoriesDir,
+  isSharedPath,
+} from "karajan-core/shared-paths";

package/src/utils/squeezr-detect.js

@@ -0,0 +1,21 @@
+import { runCommand } from "./process.js";
+
+/**
+ * Detect whether Squeezr is installed and available.
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectSqueezr() {
+  try {
+    const result = await runCommand("squeezr", ["--version"]);
+    if (result.exitCode === 0) {
+      // `squeezr --version` may append an "update available" banner box; keep
+      // just the semver so callers never render that noise (KJC-BUG-0088).
+      const raw = (result.stdout || "").trim();
+      const version = raw.match(/\d+\.\d+\.\d+[\w.-]*/)?.[0] || raw.split("\n")[0].trim() || null;
+      return { available: true, version };
+    }
+    return { available: false, version: null };
+  } catch { /* squeezr binary not found */
+    return { available: false, version: null };
+  }
+}