karajan-code 3.3.0 → 3.4.1

package/node_modules/@karajan/core/src/process.js

@@ -0,0 +1,188 @@
+import { execa } from "execa";
+
+const isWin = process.platform === "win32";
+const KILL_SIGNAL = isWin ? "SIGTERM" : "SIGKILL";
+
+function buildSilenceKilledResult(silenceTimeoutMs, stdout, signal) {
+  return {
+    exitCode: 143,
+    stdout,
+    stderr: `Command killed after ${Number(silenceTimeoutMs)}ms without output`,
+    timedOut: true,
+    signal: signal || KILL_SIGNAL
+  };
+}
+
+function setupOutputStreaming(subprocess, onOutput, partialOutputFlushMs) {
+  const flushMs = Number(partialOutputFlushMs) > 0 ? Number(partialOutputFlushMs) : 2000;
+  const streams = {};
+  const makeHandler = (stream) => {
+    const state = { partial: "", dirty: false };
+    streams[stream] = state;
+    return (chunk) => {
+      state.partial += chunk.toString();
+      const lines = state.partial.split(/\r\n|\n|\r/);
+      state.partial = lines.pop() ?? "";
+      state.dirty = state.partial.length > 0;
+      for (const line of lines) {
+        if (line) onOutput({ stream, line });
+      }
+    };
+  };
+
+  const flushPartials = () => {
+    for (const [stream, state] of Object.entries(streams)) {
+      if (!state.dirty || !state.partial) continue;
+      onOutput({ stream, line: state.partial });
+      state.partial = "";
+      state.dirty = false;
+    }
+  };
+
+  if (subprocess.stdout) subprocess.stdout.on("data", makeHandler("stdout"));
+  if (subprocess.stderr) subprocess.stderr.on("data", makeHandler("stderr"));
+  const flushInterval = setInterval(flushPartials, flushMs);
+  flushInterval.unref?.();
+
+  subprocess.finally(() => {
+    flushPartials();
+    clearInterval(flushInterval);
+  });
+}
+
+async function awaitWithTimeout(subprocess, timeout, getStdout) {
+  let timer = null;
+  const timeoutResult = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      try {
+        subprocess.kill(KILL_SIGNAL, { forceKillAfterDelay: 1000 });
+      } catch {
+        // no-op
+      }
+      resolve({
+        exitCode: 143,
+        stdout: getStdout(),
+        stderr: `Command timed out after ${timeout}ms`,
+        timedOut: true,
+        signal: KILL_SIGNAL
+      });
+    }, timeout);
+  });
+
+  const result = await Promise.race([subprocess, timeoutResult]);
+  if (timer) clearTimeout(timer);
+  return result;
+}
+
+export async function runCommand(command, args = [], options = {}) {
+  const { timeout, onOutput, silenceTimeoutMs, partialOutputFlushMs, ...rest } = options;
+  // Detach stdin unless the caller provides input (e.g. Codex uses input: prompt).
+  // Without this, a subprocess prompting for input hangs forever since there is no TTY.
+  if (!rest.stdin && !rest.input) rest.stdin = "ignore";
+  const subprocess = execa(command, args, { reject: false, ...rest });
+
+  let stdoutAccum = "";
+  let stderrAccum = "";
+  let outputSilenceTimer = null;
+  let silenceTimedOut = false;
+
+  function clearSilenceTimer() {
+    if (outputSilenceTimer) {
+      clearTimeout(outputSilenceTimer);
+      outputSilenceTimer = null;
+    }
+  }
+
+  function armSilenceTimer() {
+    const ms = Number(silenceTimeoutMs);
+    if (!Number.isFinite(ms) || ms <= 0 || silenceTimedOut) return;
+    clearSilenceTimer();
+    outputSilenceTimer = setTimeout(() => {
+      silenceTimedOut = true;
+      try {
+        subprocess.kill(KILL_SIGNAL, { forceKillAfterDelay: 1000 });
+      } catch {
+        // no-op
+      }
+    }, ms);
+  }
+
+  if (subprocess.stdout) {
+    subprocess.stdout.on("data", (chunk) => {
+      stdoutAccum += chunk.toString();
+      armSilenceTimer();
+    });
+  }
+  if (subprocess.stderr) {
+    subprocess.stderr.on("data", (chunk) => {
+      stderrAccum += chunk.toString();
+      armSilenceTimer();
+    });
+  }
+
+  if (onOutput) {
+    setupOutputStreaming(subprocess, onOutput, partialOutputFlushMs);
+  }
+  armSilenceTimer();
+
+  try {
+    const result = timeout
+      ? await awaitWithTimeout(subprocess, timeout, () => stdoutAccum)
+      : await subprocess;
+    clearSilenceTimer();
+    if (silenceTimedOut) return buildSilenceKilledResult(silenceTimeoutMs, stdoutAccum);
+    return enrichResult(result, stdoutAccum, stderrAccum);
+  } catch (error) {
+    clearSilenceTimer();
+    if (silenceTimedOut) return buildSilenceKilledResult(silenceTimeoutMs, error?.stdout || stdoutAccum, error?.signal);
+
+    const details = [error?.shortMessage, error?.originalMessage, error?.stderr, error?.stdout, error?.message]
+      .filter(Boolean)
+      .join("\n");
+
+    return {
+      exitCode: 1,
+      stdout: error?.stdout || stdoutAccum,
+      stderr: details || String(error),
+      signal: error?.signal || null
+    };
+  }
+}
+
+function enrichResult(result, stdoutAccum, _stderrAccum) {
+  if (result.timedOut) return result;
+
+  // execa with reject:false RESOLVES (does not throw) on a spawn
+  // failure — ENOENT (binary not in PATH), EACCES, etc. The result
+  // then carries exitCode null/undefined, an empty stderr, and the
+  // real cause only in `code` / `shortMessage`. Surface it: a missing
+  // agent CLI used to fail with a completely empty error message,
+  // leaving the user with "coder failed" and no idea what to install.
+  if (result.failed && result.exitCode == null && !result.signal) {
+    const reason = result.shortMessage || result.message
+      || `spawn failed${result.code ? ` (${result.code})` : ""}`;
+    return {
+      ...result,
+      exitCode: 1,
+      stdout: result.stdout || stdoutAccum,
+      stderr: result.stderr || reason,
+      spawnError: result.code || true,
+    };
+  }
+
+  const killed = result.killed || !!result.signal;
+  const signal = result.signal || null;
+
+  if (killed && !result.stderr) {
+    return {
+      ...result,
+      stdout: result.stdout || stdoutAccum,
+      stderr: signal
+        ? `Process killed by signal ${signal}`
+        : "Process was killed externally",
+      signal
+    };
+  }
+
+  return result;
+}

package/node_modules/@karajan/core/src/run-registry.js

@@ -0,0 +1,115 @@
+/**
+ * Run registry — registro persistente de `kj run` activos.
+ *
+ * KJC-TSK-0396 (extensión): el HU Board necesita ver runs lanzados desde
+ * la terminal externa (no solo los lanzados desde el propio board). Para
+ * eso, cada `kj run` escribe su PID + planId + huIds + projectDir a un
+ * archivo en `~/.karajan/runs/<runId>.json` al arrancar, y lo borra al
+ * terminar (success o crash con cleanup vía finally).
+ *
+ * El board lee ese directorio en startup + cada vez que sirve el endpoint
+ * `/api/runs/:planId/active`, descartando los registros con PID muerto
+ * (filtrado con `process.kill(pid, 0)`). Resultado: bidireccionalidad
+ * total terminal ↔ board.
+ *
+ * Compartido entre el CLI (src/commands/run.js) y el board
+ * (packages/hu-board/src/run-tracker.js) vía `@karajan/core/run-registry`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { writeJsonAtomicSync } from "./atomic-write.js";
+import { getRunsDir } from "./paths.js";
+
+/**
+ * Directorio raíz donde viven los registros de run.
+ * Delega en `getRunsDir()` (KJC-TSK-0420) — respeta KARAJAN_HOME,
+ * KJ_HOME (con warning de deprecación), VITEST tmp y default.
+ */
+export function runsDir() {
+  return getRunsDir();
+}
+
+/**
+ * Registra un nuevo run en disco. El runId es derivado del PID + timestamp
+ * para ser único por proceso.
+ *
+ * @param {{ pid: number, planId?: string|null, huIds?: string[]|null, projectDir?: string|null, source?: string }} info
+ * @returns {string|null} runId o null si la escritura falló (no bloquea al caller).
+ */
+export function registerRun(info = {}) {
+  if (!info?.pid) return null;
+  try {
+    fs.mkdirSync(runsDir(), { recursive: true });
+    // Sufijo random para evitar colisiones cuando 2 runs del mismo PID
+    // se registran en el mismo ms (raro en CLI, posible en tests).
+    const runId = `run-${Date.now()}-${info.pid}-${Math.random().toString(36).slice(2, 8)}`;
+    const filePath = path.join(runsDir(), `${runId}.json`);
+    const entry = {
+      runId,
+      pid: info.pid,
+      planId: info.planId || null,
+      huIds: Array.isArray(info.huIds) ? info.huIds : null,
+      projectDir: info.projectDir || null,
+      source: info.source || "cli",
+      startedAt: new Date().toISOString(),
+    };
+    writeJsonAtomicSync(filePath, entry);
+    return runId;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Borra el registro de un run. Idempotente — silencia ENOENT.
+ *
+ * @param {string} runId
+ */
+export function unregisterRun(runId) {
+  if (!runId) return;
+  try {
+    fs.unlinkSync(path.join(runsDir(), `${runId}.json`));
+  } catch {
+    // Idempotente
+  }
+}
+
+/**
+ * Lista todos los runs activos en disco, filtrando los con PID muerto.
+ * Los muertos se borran del FS (auto-cleanup defensivo).
+ *
+ * @param {{ planId?: string }} [filter] - si se pasa planId, devuelve solo los runs de ese plan.
+ * @returns {Array<{runId, pid, planId, huIds, projectDir, source, startedAt}>}
+ */
+export function listActiveRuns(filter = {}) {
+  const dir = runsDir();
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  let files;
+  try { files = fs.readdirSync(dir); } catch { return []; }
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue;
+    const filePath = path.join(dir, f);
+    let entry;
+    try { entry = JSON.parse(fs.readFileSync(filePath, "utf8")); }
+    catch { try { fs.unlinkSync(filePath); } catch { /* swallow */ } continue; }
+    if (!isAlive(entry.pid)) {
+      try { fs.unlinkSync(filePath); } catch { /* swallow */ }
+      continue;
+    }
+    if (filter.planId && entry.planId !== filter.planId) continue;
+    out.push(entry);
+  }
+  return out;
+}
+
+/**
+ * Verifica si un PID sigue vivo. `process.kill(pid, 0)` NO envía
+ * señal — solo lanza ESRCH si el proceso no existe.
+ */
+function isAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (err) { return err.code === "EPERM"; }
+}

package/node_modules/@karajan/core/src/shared-paths.js

@@ -0,0 +1,41 @@
+/**
+ * Team-shared HU Board paths — KJC-PRP-0002 / v2.31.0 PR1.
+ *
+ * The shared root lives INSIDE the project, not in `~/.karajan/`, so a team
+ * can commit it to git (or sync via Drive/SyncThing) and share plans + HU
+ * stories without each member regenerating them locally.
+ *
+ *   <projectDir>/.karajan-shared/
+ *     plans/<planId>.json     ← `kj plan share <planId>` copies here
+ *     hu-stories/<huId>.md    ← reserved for PR2+ (board reads it)
+ *
+ * Keep the dir name in lockstep with the HU Board sync layer
+ * (`packages/hu-board/src/sync.js`) — diverging the constant breaks the
+ * watcher silently. One source of truth lives here.
+ */
+
+import path from "node:path";
+
+export const SHARED_DIR_NAME = ".karajan-shared";
+
+export function getSharedRoot(projectDir) {
+  return path.join(projectDir, SHARED_DIR_NAME);
+}
+
+export function getSharedPlansDir(projectDir) {
+  return path.join(getSharedRoot(projectDir), "plans");
+}
+
+export function getSharedHuStoriesDir(projectDir) {
+  return path.join(getSharedRoot(projectDir), "hu-stories");
+}
+
+/**
+ * Quick check used by callers that decide whether a plan came from local
+ * (`~/.karajan/plans/`) or from the shared dir. The HU Board uses this to
+ * stamp a `source` column on each record so the UI can render a 🌐 badge.
+ */
+export function isSharedPath(p) {
+  if (!p) return false;
+  return p.split(path.sep).includes(SHARED_DIR_NAME);
+}

package/node_modules/@karajan/core/src/standby-scheduler.js

@@ -0,0 +1,92 @@
+// KJC-TSK-0414 PR 1: scheduler event-driven para hibernación.
+//
+// Diseño: setTimeout único por sesión, dispara EXACTAMENTE en cooldownUntil.
+// Cero polling. Si el proceso muere antes del fire, reconcileAll() al
+// arrancar el board re-programa los timeouts pendientes (o reanuda
+// inmediatamente los expirados).
+
+import { listPendingStandby, acquireStandbyLock, markStandbyDone } from "./standby-store.js";
+
+// Mapa sessionId → NodeJS.Timeout — accesible para test/cancel.
+const _scheduled = new Map();
+
+export function _resetScheduledForTests() {
+  for (const t of _scheduled.values()) clearTimeout(t);
+  _scheduled.clear();
+}
+
+/**
+ * Programa un único setTimeout que dispara `onResume(sessionId)` en cooldownUntil.
+ *
+ * @param {object} args
+ * @param {string} args.sessionId
+ * @param {string} args.cooldownUntil - ISO timestamp
+ * @param {Function} args.onResume - callback(sessionId) cuando llega el momento
+ * @param {object} [args.logger]
+ * @returns {{ scheduled: boolean, msUntil?: number, immediate?: boolean }}
+ */
+export function scheduleResume({ sessionId, cooldownUntil, onResume, logger }) {
+  if (!sessionId || !cooldownUntil || typeof onResume !== "function") {
+    return { scheduled: false };
+  }
+  cancelScheduled(sessionId);
+  const targetMs = new Date(cooldownUntil).getTime();
+  if (Number.isNaN(targetMs)) return { scheduled: false };
+  const delay = targetMs - Date.now();
+  if (delay <= 0) {
+    // Ya expiró — reanudar inmediato (caso: board reiniciado tras llegar la hora).
+    logger?.info?.(`[standby-scheduler] ${sessionId}: cooldown ya expirado, resume inmediato`);
+    Promise.resolve().then(() => onResume(sessionId)).catch(() => { /* swallow */ });
+    return { scheduled: true, immediate: true };
+  }
+  const timer = setTimeout(() => {
+    _scheduled.delete(sessionId);
+    logger?.info?.(`[standby-scheduler] ${sessionId}: cooldown alcanzado, disparando resume`);
+    try { onResume(sessionId); } catch (err) { logger?.warn?.(`[standby-scheduler] onResume threw: ${err.message}`); }
+  }, delay);
+  if (typeof timer.unref === "function") timer.unref();
+  _scheduled.set(sessionId, timer);
+  logger?.info?.(`[standby-scheduler] ${sessionId}: scheduled in ${Math.round(delay / 1000)}s (until ${cooldownUntil})`);
+  return { scheduled: true, msUntil: delay };
+}
+
+/** Cancela el setTimeout de una sesión (caso: usuario hizo kj resume manual). */
+export function cancelScheduled(sessionId) {
+  const t = _scheduled.get(sessionId);
+  if (!t) return false;
+  clearTimeout(t);
+  _scheduled.delete(sessionId);
+  return true;
+}
+
+/**
+ * Reconciliación al arrancar el board / kj. Lee todas las sesiones pendientes
+ * y para cada una:
+ *   - cooldownUntil < now → onResume inmediato
+ *   - cooldownUntil > now → re-programa setTimeout
+ *
+ * Idempotente: el lockfile en standby-store previene dobles spawns si
+ * reconcileAll() corre dos veces concurrentes (board reload).
+ *
+ * @param {object} args
+ * @param {Function} args.onResume - callback(sessionId)
+ * @param {object} [args.logger]
+ * @returns {{ scheduled: number, immediate: number, total: number }}
+ */
+export function reconcileAll({ onResume, logger }) {
+  const sessions = listPendingStandby();
+  let scheduled = 0;
+  let immediate = 0;
+  for (const s of sessions) {
+    if (!s?.sessionId || !s?.cooldownUntil) continue;
+    const r = scheduleResume({ sessionId: s.sessionId, cooldownUntil: s.cooldownUntil, onResume, logger });
+    if (r.scheduled && r.immediate) immediate += 1;
+    else if (r.scheduled) scheduled += 1;
+  }
+  logger?.info?.(`[standby-scheduler] reconcile: ${sessions.length} sesiones (${immediate} resume inmediato, ${scheduled} programadas)`);
+  return { scheduled, immediate, total: sessions.length };
+}
+
+// Re-export para que callers no tengan que importar standby-store si solo
+// necesitan el flow scheduler → lock → done.
+export { acquireStandbyLock, markStandbyDone };

package/node_modules/@karajan/core/src/standby-store.js

@@ -0,0 +1,168 @@
+// KJC-TSK-0414 PR 1: persistencia de sesiones hibernadas al disco.
+//
+// Cuando Brain decide hibernar (QUOTA_EXHAUSTED_DAILY con retryAfter > 5min),
+// serializa el estado completo del run en ~/.kj/standby/<sessionId>.json.
+// El proceso de kj run muere (exit 0) tras persistir; el board (o kj resume)
+// lo reanuda cuando llega cooldownUntil.
+//
+// Layout en disco:
+//   ~/.kj/standby/
+//     <sessionId>.json    ← sesiones pendientes (scheduler les mete setTimeout)
+//     <sessionId>.lock    ← lockfile durante spawn de kj resume
+//     done/
+//       <sessionId>.json  ← finalizadas (consumibles por GC en TSK-0414 PR3)
+
+import fs from "node:fs";
+import path from "node:path";
+import { writeJsonAtomicSync } from "./atomic-write.js";
+import { resolveHome } from "./paths.js";
+
+const FILENAME_RE = /^[a-zA-Z0-9._-]+\.json$/;
+
+// Delegates to the unified resolver. PR 3 of KJC-PCS-0047 switched
+// the default to `.karajan` — hibernated sessions now persist under
+// `~/.karajan/standby/`, migrated automatically from the legacy
+// `~/.kj/standby/` on the next `kj` invocation.
+function getKjHome() {
+  return resolveHome({ defaultSegment: ".karajan" });
+}
+
+export function standbyDir() {
+  return path.join(getKjHome(), "standby");
+}
+
+export function standbyDoneDir() {
+  return path.join(standbyDir(), "done");
+}
+
+function sanitizeId(sessionId) {
+  if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId requerido");
+  return sessionId.replaceAll(/[^a-zA-Z0-9._-]/g, "_").slice(0, 120);
+}
+
+/**
+ * Persiste el estado completo de un run hibernado.
+ *
+ * @param {object} state - shape:
+ *   { sessionId, planId?, huId?, role, iteration?, prompt, agentConfig,
+ *     retryCount?, cooldownUntil, reason, snapshot_sha?, outcome_so_far? }
+ * @returns {string} path absoluto del JSON escrito
+ */
+export function persistStandby(state) {
+  if (!state || !state.sessionId) throw new Error("state.sessionId requerido");
+  if (!state.cooldownUntil) throw new Error("state.cooldownUntil requerido");
+  const dir = standbyDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `${sanitizeId(state.sessionId)}.json`);
+  const payload = {
+    ...state,
+    createdAt: state.createdAt || new Date().toISOString(),
+    persistedAt: new Date().toISOString(),
+  };
+  writeJsonAtomicSync(file, payload);
+  return file;
+}
+
+// Only these env vars are carried into the standby snapshot. NEVER
+// persist the whole `process.env` — that would leak API keys and other
+// secrets into ~/.kj/standby/*.json. `kj standby resume` re-spawns with
+// the live env merged on top, so the snapshot only needs what is needed
+// to relaunch from the right place.
+const STANDBY_ENV_ALLOWLIST = ["KJ_HOME", "HOME", "PATH"];
+
+/**
+ * Builds the `sessionState` object that `withBrainRecovery` persists when
+ * a run hibernates. Pulls the session id, the relaunch metadata and an
+ * allowlisted env subset so `kj standby resume` can re-spawn the command.
+ * @param {object} args
+ * @param {object} args.session    - the pipeline session ({ id, plan_id? })
+ * @param {object} [args.config]   - resolved config ({ projectDir?, plan? })
+ * @param {string|null} [args.huId]
+ * @returns {object|null} sessionState, or null when there is no session id
+ */
+export function buildStandbyState({ session, config = {}, huId = null } = {}) {
+  if (!session?.id) return null;
+  const env = {};
+  for (const key of STANDBY_ENV_ALLOWLIST) {
+    if (process.env[key] != null) env[key] = process.env[key];
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("KJ_") && value != null) env[key] = value;
+  }
+  return {
+    sessionId: session.id,
+    planId: session.plan_id || config.plan || null,
+    huId: huId || null,
+    argv: process.argv.slice(2),
+    cwd: config.projectDir || process.cwd(),
+    env,
+  };
+}
+
+/**
+ * @param {string} sessionId
+ * @returns {object|null}
+ */
+export function loadStandby(sessionId) {
+  const file = path.join(standbyDir(), `${sanitizeId(sessionId)}.json`);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lista todas las sesiones pendientes (no las de done/).
+ * @returns {object[]}
+ */
+export function listPendingStandby() {
+  const dir = standbyDir();
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => FILENAME_RE.test(f))
+    .map((f) => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Mueve una sesión a done/ — consumible por GC en TSK-0414 PR3.
+ * @param {string} sessionId
+ * @returns {boolean} true si se movió
+ */
+export function markStandbyDone(sessionId) {
+  const id = sanitizeId(sessionId);
+  const src = path.join(standbyDir(), `${id}.json`);
+  if (!fs.existsSync(src)) return false;
+  const doneDir = standbyDoneDir();
+  fs.mkdirSync(doneDir, { recursive: true });
+  const dst = path.join(doneDir, `${id}-${Date.now()}.json`);
+  fs.renameSync(src, dst);
+  return true;
+}
+
+/**
+ * Lockfile para evitar dobles spawns de kj resume sobre la misma sesión.
+ * Devuelve { acquired: true, release: () => void } o { acquired: false } si ya hay lock.
+ *
+ * @param {string} sessionId
+ * @returns {{ acquired: boolean, release?: Function }}
+ */
+export function acquireStandbyLock(sessionId) {
+  const id = sanitizeId(sessionId);
+  const lockFile = path.join(standbyDir(), `${id}.lock`);
+  try {
+    fs.mkdirSync(standbyDir(), { recursive: true });
+    fs.writeFileSync(lockFile, String(process.pid), { flag: "wx" });
+    return { acquired: true, release: () => { try { fs.unlinkSync(lockFile); } catch { /* */ } } };
+  } catch {
+    return { acquired: false };
+  }
+}