karajan-code 2.7.4 → 2.9.0

package/src/utils/derive-project-name-from-cwd.js

@@ -0,0 +1,119 @@
+/**
+ * Derive a sensible default project name from the working directory,
+ * trying several signals in order:
+ *
+ *   1. `package.json` "name" field (most authoritative — that's what
+ *      the user already chose for their npm/pnpm project).
+ *   2. Git remote URL basename (strip protocol, user, `.git` suffix —
+ *      e.g. `git@github.com:foo/weather-dashboard.git` → `weather-dashboard`).
+ *   3. The cwd directory basename.
+ *
+ * Any of these is then prettified: kebab/snake → spaces, words
+ * capitalised. So `weather-dashboard` becomes `Weather Dashboard`.
+ *
+ * Returns null when no signal yields anything useful — caller can then
+ * fall back to its old "derive from task text" heuristic. This keeps
+ * the function pure / sync-friendly even though git/fs lookups are
+ * sync — they're cheap on a single-shot CLI startup.
+ *
+ * Why this matters: pre-fix, running `kj plan generate --task-file
+ * SPEC.md` inside `~/ws_demo/weather-dashboard` (an initialised git
+ * repo) suggested a project name made from the words of the SPEC's
+ * first sentence. That ignored both the directory the user was
+ * standing in and the repo they had just `git init`-ed. The right
+ * default is "the project I'm in", not "the topic of the document
+ * I just wrote".
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+/**
+ * Turn `weather-dashboard` / `weather_dashboard` / `WeatherDashboard`
+ * into `Weather Dashboard`. Preserves single-token names as-is when
+ * already title-cased.
+ */
+function prettifyName(raw) {
+  if (!raw || typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  // Insert space at camelCase boundaries, then split on -/_/whitespace.
+  const spaced = trimmed
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!spaced) return null;
+  return spaced
+    .split(" ")
+    .map((w) => (w.length ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(" ");
+}
+
+function readPackageJsonName(cwd) {
+  try {
+    const pkgPath = path.join(cwd, "package.json");
+    if (!fs.existsSync(pkgPath)) return null;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    if (typeof pkg.name === "string" && pkg.name.trim()) {
+      // Strip npm scope if present: @org/name → name
+      const unscoped = pkg.name.includes("/") ? pkg.name.split("/").pop() : pkg.name;
+      return unscoped;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function readGitRemoteBasename(cwd) {
+  try {
+    // -C points git at the cwd without us cd'ing the process.
+    // Audit follow-up: was using execSync with template-string interpolation
+    // of `cwd`. Switched to execFileSync with arg arrays so no interpolation
+    // reaches /bin/sh.
+    const out = execFileSync("git", ["-C", String(cwd), "config", "--get", "remote.origin.url"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8",
+      timeout: 1500,
+    }).trim();
+    if (!out) return null;
+    // Strip optional protocol + user, .git suffix, trailing slash.
+    // Examples:
+    //   git@github.com:foo/weather-dashboard.git
+    //   https://github.com/foo/weather-dashboard
+    //   git@gitlab.com:team/weather-dashboard
+    const last = out.replace(/\.git\/?$/, "").split(/[/:]/).pop();
+    return last || null;
+  } catch {
+    return null;
+  }
+}
+
+function readCwdBasename(cwd) {
+  const base = path.basename(cwd || process.cwd());
+  if (!base || base === "/" || base === ".") return null;
+  return base;
+}
+
+/**
+ * Try every signal in priority order and return the first prettified
+ * non-empty result. Returns null when nothing useful is available.
+ *
+ * @param {string} [cwd] — defaults to process.cwd()
+ * @returns {string|null}
+ */
+export function deriveProjectNameFromCwd(cwd = process.cwd()) {
+  const fromPkg = prettifyName(readPackageJsonName(cwd));
+  if (fromPkg) return fromPkg;
+  const fromGit = prettifyName(readGitRemoteBasename(cwd));
+  if (fromGit) return fromGit;
+  const fromCwd = prettifyName(readCwdBasename(cwd));
+  if (fromCwd) return fromCwd;
+  return null;
+}
+
+// Exposed for unit tests so they can drive the individual signals
+// without real filesystem / git side-effects.
+export const __test__ = { prettifyName, readPackageJsonName, readGitRemoteBasename, readCwdBasename };

package/src/utils/display/event-handlers.js

@@ -342,7 +342,7 @@ export const EVENT_HANDLERS = {
 };
 
 /** Event types suppressed in quiet mode (internal/noise events). */
-export const QUIET_SUPPRESSED = new Set([
+const QUIET_SUPPRESSED = new Set([
   "agent:output",
   "agent:stall",
   "pipeline:simplify",

package/src/utils/display/header.js

@@ -8,7 +8,7 @@ import { ANSI } from "./formatters.js";
 const DISPLAY_PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../package.json");
 const DISPLAY_VERSION = JSON.parse(readFileSync(DISPLAY_PKG_PATH, "utf8")).version;
 
-export const BAR = `${ANSI.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${ANSI.reset}`;
+const BAR = `${ANSI.dim}\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${ANSI.reset}`;
 
 /**
  * Print task, configuration and pipeline header

package/src/utils/display/session-summary.js

@@ -15,7 +15,7 @@ export function printSessionStages(stages) {
   printSessionSonar(stages.sonar);
 }
 
-export function printSessionPlanner(planner) {
+function printSessionPlanner(planner) {
   if (!planner?.title && !planner?.approach && !planner?.completedSteps?.length) return;
   const planParts = [];
   if (planner.title) planParts.push(planner.title);
@@ -26,7 +26,7 @@ export function printSessionPlanner(planner) {
   }
 }
 
-export function printSessionSonar(sonar) {
+function printSessionSonar(sonar) {
   if (!sonar) return;
   const gateLabel = sonar.gateStatus === "OK" ? ANSI.green : ANSI.red;
   console.log(`  ${ANSI.dim}\ud83d\udd0d Sonar: ${gateLabel}${sonar.gateStatus}${ANSI.reset}${ANSI.dim} (${sonar.openIssues ?? 0} issues)${ANSI.reset}`);
@@ -55,7 +55,7 @@ export function printSessionGit(git) {
   }
 }
 
-export function isBudgetUnavailable(budget) {
+function isBudgetUnavailable(budget) {
   return budget.usage_available === false ||
     (budget.total_tokens === 0 && budget.total_cost_usd === 0 && Object.keys(budget.breakdown_by_role || {}).length > 0);
 }

package/src/utils/display/solomon.js

@@ -1,6 +1,6 @@
 import { ANSI } from "./formatters.js";
 
-export const SOLOMON_RULING_HANDLERS = {
+const SOLOMON_RULING_HANDLERS = {
   approve(detail, elapsed) {
     const dismissedCount = detail?.dismissed?.length || 0;
     const dismissedSuffix = dismissedCount > 0 ? ` (${dismissedCount} dismissed)` : "";

package/src/utils/garbage-collector.js

@@ -0,0 +1,396 @@
+/**
+ * Karajan garbage collector — keeps `~/.kj/` and `~/.karajan/` from
+ * accumulating dead state across runs.
+ *
+ * Dogfood motivation: after ~1 year the user's `~/.kj/plans/` had 2 464
+ * plans in `home_manu_ws_npm-packages_karajan-code/` plus 35 plans from
+ * worktrees that no longer exist. Same story for `~/.karajan/sessions/`
+ * and `hu-stories/`. None ever got cleaned because no command did it.
+ */
+
+/**
+ * Two entry points:
+ *   - `runAutoGC(opts)` — silent, called at the top of every `kj run`
+ *     and `kj plan`. Prints a single one-liner ONLY when something was
+ *     removed.
+ *   - `runManualGC(opts)` — backs `kj clean`. Caller decides `dryRun`;
+ *     returns the full `{ removed, bytesFreed, errors }` record.
+ *
+ * Retention policy (all adjustable via opts):
+ *   • Plans whose stamped `projectDir` no longer exists → delete.
+ *   • Plans with final status (approved/rejected/executed) older than
+ *     `planRetentionDays` (30) → delete.
+ *   • Draft plans older than `draftRetentionDays` (60) → delete.
+ *   • Finalised sessions older than `sessionRetentionDays` (7) → delete.
+ *   • HU story batches older than `huRetentionDays` (14) → delete.
+ *
+ * Failures are NEVER fatal — every op is try/catch and non-blocking.
+ * Tested against an isolated tmp KJ_HOME so production data is safe.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+const FINAL_PLAN_STATUSES = new Set([
+  // Terminal plan states the user explicitly opted into — retention applies.
+  "approved", "rejected", "executed", "completed", "ready",
+]);
+const KNOWN_PLAN_STATUSES = new Set([...FINAL_PLAN_STATUSES, "draft", "running"]);
+const FINAL_SESSION_STATUSES = new Set(["approved", "failed", "stopped", "rejected", "completed"]);
+
+function getKjHome() {
+  return process.env.KJ_HOME || path.join(os.homedir(), ".kj");
+}
+
+function getKarajanHome() {
+  return process.env.KARAJAN_HOME || path.join(os.homedir(), ".karajan");
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * @typedef {Object} GCOptions
+ * @property {number} [planRetentionDays=30]
+ * @property {number} [draftRetentionDays=60]
+ * @property {number} [sessionRetentionDays=7]
+ * @property {number} [huRetentionDays=14]
+ * @property {boolean} [dryRun=false]   - only report what would be removed
+ * @property {Date}    [now]            - clock injection for tests
+ */
+
+/**
+ * @typedef {Object} GCResult
+ * @property {Array<{path: string, reason: string, kind: string, bytes?: number}>} removed
+ * @property {number} bytesFreed
+ * @property {Array<{path: string, error: string}>} errors
+ */
+
+async function tryReadJson(file) {
+  try {
+    const txt = await fs.readFile(file, "utf8");
+    return JSON.parse(txt);
+  } catch {
+    return null;
+  }
+}
+
+async function tryStat(p) {
+  try { return await fs.stat(p); } catch { return null; }
+}
+
+async function exists(p) {
+  return Boolean(await tryStat(p));
+}
+
+async function listDir(dir) {
+  try { return await fs.readdir(dir, { withFileTypes: true }); } catch { return []; }
+}
+
+async function unlinkOrRm(p, dryRun) {
+  if (dryRun) return;
+  try {
+    const st = await fs.stat(p);
+    if (st.isDirectory()) await fs.rm(p, { recursive: true, force: true });
+    else await fs.unlink(p);
+  } catch { /* best-effort */ }
+}
+
+function ageInDays(stat, now) {
+  return (now.getTime() - stat.mtimeMs) / DAY_MS;
+}
+
+// Slugs are lossy — we CAN'T recover a path from one because `_` in
+// the slug could have come from either `/` in the path or a literal
+// `_` in a directory name (e.g. `ws_ai` vs `ws/ai`). That's why plans
+// saved via `savePlan()` now stamp their absolute `projectDir`; the GC
+// reads it from there. Legacy plans without the field fall back to
+// age-only retention — never marked as orphans on the way up.
+
+/**
+ * Per-plan classifier. Pulled out so the surrounding GC can evaluate
+ * candidates in parallel — every plan is independent (no shared state
+ * across iterations except the result accumulator, which is folded back
+ * after the bursts settle).
+ */
+async function classifyPlan(filePath, opts, now) {
+  const stat = await tryStat(filePath);
+  if (!stat) return { skip: true };
+  const data = await tryReadJson(filePath);
+  const status = data?.status || "draft";
+  const storedDir = typeof data?.projectDir === "string" ? data.projectDir : null;
+  const days = ageInDays(stat, now);
+
+  let reason = null;
+  // Orphan check: only when the plan stamped its origin projectDir.
+  // Plans older than the savePlan-stamping change don't have it, so
+  // we refuse to guess and just apply age-based retention.
+  if (storedDir && !(await exists(storedDir))) {
+    reason = "orphaned (project dir no longer exists)";
+  } else if (FINAL_PLAN_STATUSES.has(status) && days > opts.planRetentionDays) {
+    reason = `${status} plan older than ${opts.planRetentionDays}d (${Math.round(days)}d)`;
+  } else if (status === "draft" && days > opts.draftRetentionDays) {
+    reason = `stale draft older than ${opts.draftRetentionDays}d (${Math.round(days)}d)`;
+  } else if (!KNOWN_PLAN_STATUSES.has(status) && days > opts.draftRetentionDays) {
+    // Unknown status (corrupt/legacy/plan from a future version) —
+    // apply the draft window. Doing nothing would leak them forever.
+    reason = `plan with unknown status "${status}" older than ${opts.draftRetentionDays}d (${Math.round(days)}d)`;
+  }
+  return { skip: false, stat, reason };
+}
+
+async function gcPlans(opts) {
+  const result = { removed: [], bytesFreed: 0, errors: [] };
+  const now = opts.now || new Date();
+  const plansRoot = path.join(getKjHome(), "plans");
+  if (!(await exists(plansRoot))) return result;
+
+  // Audit follow-up: was nested sequential for-of with multiple awaits per
+  // iteration. Plans are independent files so we now classify them in
+  // parallel per project directory. Each project dir's bursts complete
+  // before we move to the next so the order of `result.removed` stays
+  // deterministic for tests; cross-project parallelism wasn't worth the
+  // complexity given KJ_HOME rarely has more than a handful of projects.
+  const projEntries = (await listDir(plansRoot)).filter((e) => e.isDirectory());
+  for (const projEntry of projEntries) {
+    const projDir = path.join(plansRoot, projEntry.name);
+    const planEntries = (await listDir(projDir))
+      .filter((e) => e.isFile() && e.name.endsWith(".json"));
+
+    const verdicts = await Promise.all(
+      planEntries.map(async (planEntry) => {
+        const filePath = path.join(projDir, planEntry.name);
+        const verdict = await classifyPlan(filePath, opts, now);
+        return { filePath, verdict };
+      })
+    );
+
+    let removedCountInDir = 0;
+    const totalCountInDir = planEntries.length;
+    for (const { filePath, verdict } of verdicts) {
+      if (verdict.skip || !verdict.reason) continue;
+      try {
+        await unlinkOrRm(filePath, opts.dryRun);
+        result.removed.push({ path: filePath, reason: verdict.reason, kind: "plan", bytes: verdict.stat.size });
+        result.bytesFreed += verdict.stat.size;
+        removedCountInDir += 1;
+      } catch (err) {
+        result.errors.push({ path: filePath, error: err.message });
+      }
+    }
+
+    // If we just emptied the project dir, remove it too.
+    if (removedCountInDir === totalCountInDir && totalCountInDir > 0) {
+      try {
+        await unlinkOrRm(projDir, opts.dryRun);
+      } catch { /* ignore */ }
+    }
+  }
+  return result;
+}
+
+async function gcSessions(opts) {
+  const result = { removed: [], bytesFreed: 0, errors: [] };
+  const now = opts.now || new Date();
+  const sessionsRoot = path.join(getKarajanHome(), "sessions");
+  if (!(await exists(sessionsRoot))) return result;
+
+  // Pipelines that get SIGKILL'd (power off, terminal closed, OOM…) leave
+  // their session.json stuck at status="running" forever. The original GC
+  // only reclaimed FINAL statuses and these zombies accumulated on the
+  // board. After `staleRunningDays` with no activity we assume the run is
+  // dead and sweep them. Default mirrors sessionRetentionDays so there is
+  // only one knob to reason about.
+  const staleRunningDays = opts.staleRunningDays ?? opts.sessionRetentionDays;
+
+  // Audit follow-up: parallelise the per-session classification (read
+  // session.json + stat the dir). Deletion stays sequential so the
+  // result.removed order is deterministic for tests.
+  const sessEntries = (await listDir(sessionsRoot)).filter((e) => e.isDirectory());
+  const verdicts = await Promise.all(
+    sessEntries.map(async (sessEntry) => {
+      const sessDir = path.join(sessionsRoot, sessEntry.name);
+      const sessionFile = path.join(sessDir, "session.json");
+      const stat = await tryStat(sessDir);
+      if (!stat) return { sessDir, reason: null };
+      const data = await tryReadJson(sessionFile);
+      const status = data?.status;
+      const days = ageInDays(stat, now);
+
+      let reason = null;
+      if (status && FINAL_SESSION_STATUSES.has(status) && days > opts.sessionRetentionDays) {
+        reason = `${status} session older than ${opts.sessionRetentionDays}d (${Math.round(days)}d)`;
+      } else if ((!status || status === "running") && days > staleRunningDays) {
+        reason = `zombie ${status || "unknown-status"} session older than ${staleRunningDays}d (${Math.round(days)}d)`;
+      }
+      return { sessDir, reason };
+    })
+  );
+
+  for (const { sessDir, reason } of verdicts) {
+    if (!reason) continue;
+    try {
+      await unlinkOrRm(sessDir, opts.dryRun);
+      result.removed.push({ path: sessDir, reason, kind: "session" });
+    } catch (err) {
+      result.errors.push({ path: sessDir, error: err.message });
+    }
+  }
+  return result;
+}
+
+async function gcHuStories(opts) {
+  const result = { removed: [], bytesFreed: 0, errors: [] };
+  const now = opts.now || new Date();
+  const huRoot = path.join(getKarajanHome(), "hu-stories");
+  if (!(await exists(huRoot))) return result;
+
+  // Audit follow-up: stat-then-classify in parallel; deletion stays
+  // sequential for deterministic ordering.
+  const batchEntries = (await listDir(huRoot)).filter((e) => e.isDirectory());
+  const verdicts = await Promise.all(
+    batchEntries.map(async (batchEntry) => {
+      const batchDir = path.join(huRoot, batchEntry.name);
+      const stat = await tryStat(batchDir);
+      if (!stat) return null;
+      const days = ageInDays(stat, now);
+      if (days <= opts.huRetentionDays) return null;
+      return {
+        batchDir,
+        reason: `HU batch older than ${opts.huRetentionDays}d (${Math.round(days)}d)`,
+      };
+    })
+  );
+
+  for (const v of verdicts) {
+    if (!v) continue;
+    try {
+      await unlinkOrRm(v.batchDir, opts.dryRun);
+      result.removed.push({ path: v.batchDir, reason: v.reason, kind: "hu-batch" });
+    } catch (err) {
+      result.errors.push({ path: v.batchDir, error: err.message });
+    }
+  }
+  return result;
+}
+
+function mergeResults(...parts) {
+  const out = { removed: [], bytesFreed: 0, errors: [] };
+  for (const r of parts) {
+    out.removed.push(...r.removed);
+    out.bytesFreed += r.bytesFreed;
+    out.errors.push(...r.errors);
+  }
+  return out;
+}
+
+function defaultOpts(opts = {}) {
+  return {
+    planRetentionDays: opts.planRetentionDays ?? 30,
+    draftRetentionDays: opts.draftRetentionDays ?? 60,
+    sessionRetentionDays: opts.sessionRetentionDays ?? 7,
+    huRetentionDays: opts.huRetentionDays ?? 14,
+    dryRun: Boolean(opts.dryRun),
+    now: opts.now || new Date(),
+  };
+}
+
+/**
+ * Manual GC — backs `kj clean`. Caller decides dryRun via opts.
+ *
+ * @param {GCOptions} [opts]
+ * @returns {Promise<GCResult>}
+ */
+export async function runManualGC(opts = {}) {
+  const o = defaultOpts(opts);
+  // Audit follow-up: was 3 sequential awaits. Plans, sessions and HU
+  // stories live in different directory subtrees and don't share state,
+  // so Promise.all is safe and roughly halves end-to-end GC latency on
+  // a populated KJ_HOME.
+  const [plans, sessions, huStories] = await Promise.all([
+    gcPlans(o),
+    gcSessions(o),
+    gcHuStories(o),
+  ]);
+  return mergeResults(plans, sessions, huStories);
+}
+
+/**
+ * Auto GC — silent, called at the top of `kj run` / `kj plan`. Always
+ * destructive (dryRun ignored). Returns the same result so the caller
+ * can print a one-liner summary if anything was removed.
+ *
+ * @param {Omit<GCOptions, 'dryRun'>} [opts]
+ * @returns {Promise<GCResult>}
+ */
+export async function runAutoGC(opts = {}) {
+  return runManualGC({ ...opts, dryRun: false });
+}
+
+/**
+ * Wipe the HU board SQLite database (+WAL + SHM + pidfile). Used by
+ * `kj clean --nuke` as the "reset everything" button.
+ *
+ * When the caller also stops the board process (we do so best-effort
+ * here via the pidfile), re-starting the board with `kj board start`
+ * or via the post-`kj plan` autostart recreates the DB empty.
+ *
+ * @param {{ dryRun?: boolean }} [opts]
+ * @returns {Promise<GCResult>}
+ */
+export async function nukeBoardDb(opts = {}) {
+  const result = { removed: [], bytesFreed: 0, errors: [] };
+  const dryRun = Boolean(opts.dryRun);
+  const kHome = getKarajanHome();
+
+  // Stop the board if we find a live pidfile — UNLESS we're being
+  // invoked from inside the board itself (the user clicked ⚡ →
+  // `kj clean --nuke` in the launcher). In that case killing the
+  // board would kill the page they're looking at, mid-confirm.
+  // command-runner.js sets KJ_INSIDE_BOARD=1 on every spawn so we
+  // can detect this. The nuke still wipes the DB; the board picks
+  // up the empty DB on its next chokidar tick.
+  const insideBoard = process.env.KJ_INSIDE_BOARD === "1";
+  const pidFile = path.join(kHome, "hu-board.pid");
+  try {
+    const pid = Number.parseInt(await fs.readFile(pidFile, "utf8"), 10);
+    if (!dryRun && Number.isFinite(pid) && !insideBoard) {
+      try { process.kill(pid, 0); process.kill(pid, "SIGTERM"); } catch { /* already dead */ }
+    }
+  } catch { /* no pidfile */ }
+
+  // The DB (+ WAL / SHM) can be hundreds of MB on old installs; report
+  // the bytes freed so the user sees the reward.
+  for (const name of ["hu-board.db", "hu-board.db-wal", "hu-board.db-shm", "hu-board.pid"]) {
+    const p = path.join(kHome, name);
+    const stat = await tryStat(p);
+    if (!stat) continue;
+    try {
+      await unlinkOrRm(p, dryRun);
+      result.removed.push({ path: p, reason: "board db wiped (--nuke)", kind: "board", bytes: stat.size });
+      result.bytesFreed += stat.size;
+    } catch (err) {
+      result.errors.push({ path: p, error: err.message });
+    }
+  }
+  return result;
+}
+
+/**
+ * Format a GC result as a single human-readable line. Used by the
+ * silent auto-GC path so the user only sees one line in the rare case
+ * something was actually cleaned.
+ *
+ * @param {GCResult} result
+ * @returns {string|null}    null when nothing was removed
+ */
+export function summarizeGC(result) {
+  if (!result.removed.length) return null;
+  const byKind = {};
+  for (const r of result.removed) {
+    byKind[r.kind] = (byKind[r.kind] || 0) + 1;
+  }
+  const parts = Object.entries(byKind).map(([k, n]) => `${n} ${k}${n === 1 ? "" : "s"}`);
+  const kb = Math.round(result.bytesFreed / 1024);
+  return `[gc] removed ${parts.join(", ")}${kb ? ` (${kb} KiB)` : ""}`;
+}

package/src/utils/git.js

@@ -1,18 +1,30 @@
 import { runCommand } from "./process.js";
+import { getRunContext } from "./run-context.js";
 
-/** @type {((command: string, args?: string[], options?: object) => Promise<object>)|null} */
+/**
+ * Module-scoped runner — legacy back-compat for callers outside a
+ * `withRunContext` scope (CLI bootstrap, checks/system.js). When running
+ * inside a pipeline, `getRunContext()?.runner` takes precedence and
+ * provides per-run isolation (TSK-0338). When neither is set we fall
+ * back to the bare `runCommand`.
+ *
+ * @type {((command: string, args?: string[], options?: object) => Promise<object>)|null}
+ */
 let _runner = null;
 
 /**
- * Inject an RTK-aware runner so all git operations in this module benefit from token savings.
- * @param {(command: string, args?: string[], options?: object) => Promise<object>} runner
+ * Set the module-scope runner. Retained for back-compat: concurrent
+ * `runFlow` invocations should rely on `withRunContext` for isolation,
+ * not on this setter (the setter is process-wide and would cause the
+ * exact cross-run contamination TSK-0338 eliminates).
  */
 export function setRunner(runner) {
   _runner = runner;
 }
 
 function run(command, args, ...rest) {
-  return (_runner || runCommand)(command, args, ...rest);
+  const ctxRunner = getRunContext()?.runner;
+  return (ctxRunner || _runner || runCommand)(command, args, ...rest);
 }
 
 function slugifyTask(task) {

package/src/utils/locale.js

@@ -35,7 +35,7 @@ function extractLangCode(locale) {
   const trimmed = locale.trim();
   if (!trimmed || trimmed === "C" || trimmed === "POSIX") return null;
   // Match first 2 lowercase letters before _, ., or end
-  const match = /^([a-z]{2})(?:[_.\-]|$)/i.exec(trimmed);
+  const match = /^([a-z]{2})(?:[_.-]|$)/i.exec(trimmed);
   if (match) return match[1].toLowerCase();
   return null;
 }

package/src/utils/paths.js

@@ -1,11 +1,31 @@
 import os from "node:os";
 import path from "node:path";
 
+// Per-process tmp dir for VITEST runs that forget to set KJ_HOME. Same
+// rationale as src/plan/plan-store.js — without this, tests that use
+// real session/board paths leak files into the developer's real
+// `~/.karajan/` and pollute the HU Board's SQLite DB. Memoised so
+// every helper in the same process agrees on the path. The trailing
+// segment is `.karajan` to keep semantic parity with non-VITEST
+// defaults (existing tests assert paths contain ".karajan/...").
+let _vitestKarajanHome = null;
+function vitestTmpKarajanHome() {
+  if (_vitestKarajanHome) return _vitestKarajanHome;
+  _vitestKarajanHome = path.join(
+    os.tmpdir(),
+    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
+    ".karajan"
+  );
+  return _vitestKarajanHome;
+}
+
 export function getKarajanHome() {
   if (process.env.KJ_HOME) {
     return path.resolve(process.env.KJ_HOME);
   }
-
+  if (process.env.VITEST) {
+    return vitestTmpKarajanHome();
+  }
   return path.join(os.homedir(), ".karajan");
 }
 

package/src/utils/process.js

@@ -149,7 +149,7 @@ export async function runCommand(command, args = [], options = {}) {
   }
 }
 
-function enrichResult(result, stdoutAccum, stderrAccum) {
+function enrichResult(result, stdoutAccum, _stderrAccum) {
   if (result.timedOut) return result;
 
   const killed = result.killed || !!result.signal;