karajan-code 2.7.4 → 2.8.0

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;

package/src/utils/prompt-project-name.js

@@ -0,0 +1,35 @@
+/**
+ * PR-H: ask the user "Nombre del proyecto?" before saving a plan.
+ *
+ * The user's words: "El nombre del board debería de deducirse del
+ * cwd o del nombre del plan, pero no darlo por hecho, preguntar al
+ * usuario siempre, por si quiere cambiarlo."
+ *
+ * Pre-fills the prompt with the suggested name (derived from the
+ * task / cwd) so accepting the default is one ENTER away. Returns
+ * the trimmed answer; falls back to the default when the user just
+ * hits ENTER (empty input).
+ *
+ * Caller is responsible for skipping this when stdin/stdout are not
+ * a TTY, when --yes is set, or when --json is set.
+ */
+
+import readline from "node:readline";
+
+/**
+ * @param {string} defaultName — pre-filled suggestion shown in [brackets]
+ * @returns {Promise<string>} the user's answer (defaults to defaultName)
+ */
+export async function promptProjectName(defaultName) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const fallback = String(defaultName || "").trim();
+  const hint = fallback ? ` [${fallback}]` : "";
+  return new Promise((resolve) => {
+    rl.question(`Nombre del proyecto${hint}: `, (answer) => {
+      rl.close();
+      const trimmed = String(answer || "").trim();
+      resolve(trimmed || fallback);
+    });
+    rl.on("SIGINT", () => { rl.close(); resolve(fallback); });
+  });
+}

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

@@ -57,6 +57,18 @@ export function createRunLog(projectDir) {
   // 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");

package/src/utils/task-file.js

@@ -49,7 +49,7 @@ export async function readTaskFile(filePath, opts = {}) {
   try {
     stat = await fs.stat(resolved);
   } catch (err) {
-    throw new Error(`Task file not found: ${resolved} (${err.code || err.message})`);
+    throw new Error(`Task file not found: ${resolved} (${err.code || err.message})`, { cause: err });
   }
   if (!stat.isFile()) {
     throw new Error(`Task file is not a regular file: ${resolved}`);

package/src/utils/telemetry.js

@@ -32,7 +32,19 @@ export async function sendTelemetryEvent(eventName, data, config) {
     } finally {
       clearTimeout(timeout);
     }
-  } catch { /* never block, never fail */ }
+  } catch (err) {
+    // Audit follow-up: was a silent catch{}. Telemetry MUST stay
+    // fire-and-forget (never block the user's pipeline, never throw),
+    // but completely silent failures hide DNS/network bugs that matter
+    // when debugging the telemetry pipeline itself. Surface the error
+    // to stderr only when KJ_DEBUG=1 is explicitly set, so normal runs
+    // are still silent.
+    if (process.env.KJ_DEBUG === "1") {
+      // Stderr (not console — telemetry runs from CLI commands and is
+      // legitimate user-visible diagnostic output under KJ_DEBUG).
+      process.stderr.write(`[telemetry-debug] ${eventName}: ${err.message}\n`);
+    }
+  }
 }
 
 /**

package/src/webperf/devtools-detect.js

@@ -3,7 +3,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import { isOpenSkillsAvailable, installSkill, listSkills } from "../skills/openskills-client.js";
+import { isOpenSkillsAvailable, listSkills } from "../skills/openskills-client.js";
 
 /** Skill names relevant for WebPerf analysis. Already installed globally via openskills. */
 export const WEBPERF_SKILLS = [

package/templates/coder-rules.md

@@ -22,3 +22,16 @@
 - Keep changes minimal and focused on the task.
 - Do not modify code unrelated to the task.
 - Follow existing code conventions and patterns in the repository.
+
+## Tests location (MANDATORY)
+
+- Tests live in a top-level `tests/` directory mirroring `src/` (e.g. a function in
+  `src/services/foo.js` is tested by `tests/services/foo.test.js`).
+- DO NOT scatter `*.test.js` files inside `src/` unless the project's local
+  `.karajan/coder-rules.md` explicitly overrides this.
+- When generating a project from scratch:
+  - Create `tests/` and point the test runner at it (`include: ['tests/**/*.test.{js,ts}']`).
+  - Exclude `tests/` from the production bundle.
+  - If you write `sonar-project.properties`, set `sonar.tests=tests` AND make sure
+    that directory exists. Never declare a path that doesn't exist — Sonar will
+    refuse to scan and the run will fail every iteration with the same error.