karajan-code 3.12.0 → 3.12.2

package/node_modules/@karajan/core/src/cost/index.js

@@ -1,102 +0,0 @@
-/**
- * Cost aggregator (Cost B — KJC-TSK-0513).
- *
- * Turns a list of token-usage events emitted by the orchestrator into
- * a USD breakdown for a single run / HU. The pipeline calls this once
- * when a HU finishes; the result is what Cost C will persist in
- * board.db and Cost E will expose as `/api/projects/:id/cost`.
- *
- * Inputs are deliberately permissive: any extra field on an event is
- * ignored. We only require `role`, `model`, `tokensIn`, `tokensOut`.
- *
- * Unknown models do NOT throw. Their token counts accumulate into
- * `unknownModelTokens` and the function returns a flag so the caller
- * can surface it in the UI (orange badge instead of `$X.XXXX`).
- */
-
-import { getModelPricing } from "../pricing/index.js";
-
-const DEFAULT_ROUND_DECIMALS = 4;
-
-function round(n, decimals = DEFAULT_ROUND_DECIMALS) {
-  const f = 10 ** decimals;
-  return Math.round(n * f) / f;
-}
-
-function priceTokens(pricing, tokensIn, tokensOut) {
-  const inUsd = (tokensIn / 1_000_000) * pricing.inputPerMTok;
-  const outUsd = (tokensOut / 1_000_000) * pricing.outputPerMTok;
-  return inUsd + outUsd;
-}
-
-/**
- * Aggregate cost of a run.
- *
- * @param {object} args
- * @param {Array<{role:string, model:string, tokensIn:number, tokensOut:number}>} args.events
- * @param {(level:"warn"|"info", msg:string, ctx?:object)=>void} [args.logger]
- *        Optional structured logger. When a model is unknown we call
- *        logger("warn", ...) so the user sees it once per run.
- * @returns {{
- *   totalUsd:number,
- *   byRole:Record<string,number>,
- *   byModel:Record<string,number>,
- *   unknownModelTokens:{ tokensIn:number, tokensOut:number, models:string[] },
- *   hasUnknown:boolean,
- *   currency:string
- * }}
- */
-export function aggregateRunCost({ events, logger } = {}) {
-  const safeEvents = Array.isArray(events) ? events : [];
-  const byRole = {};
-  const byModel = {};
-  const unknownModels = new Set();
-  let totalUsd = 0;
-  let unknownIn = 0;
-  let unknownOut = 0;
-
-  for (const ev of safeEvents) {
-    if (!ev || typeof ev !== "object") continue;
-    const role = typeof ev.role === "string" && ev.role.length > 0 ? ev.role : "unknown";
-    const model = typeof ev.model === "string" ? ev.model : "";
-    const tokensIn = Number.isFinite(ev.tokensIn) ? ev.tokensIn : 0;
-    const tokensOut = Number.isFinite(ev.tokensOut) ? ev.tokensOut : 0;
-    if (tokensIn === 0 && tokensOut === 0) continue;
-
-    const pricing = getModelPricing(model);
-    if (!pricing) {
-      unknownIn += tokensIn;
-      unknownOut += tokensOut;
-      if (model.length > 0) unknownModels.add(model);
-      if (typeof logger === "function") {
-        logger("warn", "cost-aggregator: unknown model pricing", { model, role, tokensIn, tokensOut });
-      }
-      continue;
-    }
-
-    const cost = priceTokens(pricing, tokensIn, tokensOut);
-    totalUsd += cost;
-    byRole[role] = (byRole[role] || 0) + cost;
-    byModel[model] = (byModel[model] || 0) + cost;
-  }
-
-  const roundedByRole = Object.fromEntries(
-    Object.entries(byRole).map(([k, v]) => [k, round(v)])
-  );
-  const roundedByModel = Object.fromEntries(
-    Object.entries(byModel).map(([k, v]) => [k, round(v)])
-  );
-
-  return {
-    totalUsd: round(totalUsd),
-    byRole: roundedByRole,
-    byModel: roundedByModel,
-    unknownModelTokens: {
-      tokensIn: unknownIn,
-      tokensOut: unknownOut,
-      models: Array.from(unknownModels).sort(),
-    },
-    hasUnknown: unknownIn > 0 || unknownOut > 0,
-    currency: "USD",
-  };
-}

package/node_modules/@karajan/core/src/hu-snapshot.js

@@ -1,105 +0,0 @@
-// KJC-TSK-0408: snapshots de ficheros por HU para soportar Undo.
-//
-// Antes de ejecutar una HU, guardamos un ref git apuntando al HEAD
-// actual (`refs/kj-snapshots/<huId>`). Si el usuario hace Undo después,
-// hacemos `git reset --hard <ref>` para volver al estado pre-run.
-//
-// Por qué refs en lugar de stash/tarball:
-//   - Refs son objetos git nativos. No mueven blobs (todos compartidos
-//     con HEAD), así que crear el snapshot es O(1).
-//   - El snapshot persiste a través de checkouts y rebases.
-//   - Si el ref ya apunta al SHA correcto, restore es no-op.
-//
-// El runner es inyectable para que los tests no necesiten un repo git real.
-
-import { runCommand } from "./process.js";
-
-const REF_PREFIX = "refs/kj-snapshots/";
-
-/**
- * Sanitiza un huId para uso como nombre de ref. Git rechaza:
- *   - `..`, `:`, `~`, `^`, `?`, `*`, `[`, `\`, espacios, control chars
- *   - segmentos que empiecen por `.` o terminen en `.lock`
- * Reemplazamos cualquier no [a-zA-Z0-9_-] por `_`.
- */
-export function snapshotRefForHu(huId) {
-  if (!huId) throw new Error("huId requerido");
-  const safe = String(huId).replaceAll(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
-  return REF_PREFIX + safe;
-}
-
-async function defaultRunner(args, opts = {}) {
-  return runCommand("git", args, opts);
-}
-
-/**
- * Crea (o actualiza) el ref del snapshot apuntando al HEAD actual.
- *
- * @param {object} args
- * @param {string} args.projectDir
- * @param {string} args.huId
- * @param {Function} [args.runner] - sustituye git CLI en tests
- * @returns {Promise<{ ok: boolean, ref?: string, sha?: string, error?: string }>}
- */
-export async function createHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const head = await run(["rev-parse", "HEAD"], { cwd: projectDir });
-  if (head.exitCode !== 0) {
-    return { ok: false, error: `rev-parse HEAD failed: ${(head.stderr || "").trim()}` };
-  }
-  const sha = (head.stdout || "").trim();
-  if (!sha) return { ok: false, error: "HEAD vacío" };
-  const update = await run(["update-ref", ref, sha], { cwd: projectDir });
-  if (update.exitCode !== 0) {
-    return { ok: false, error: `update-ref falló: ${(update.stderr || "").trim()}` };
-  }
-  return { ok: true, ref, sha };
-}
-
-/**
- * @param {object} args
- * @param {string} args.projectDir
- * @param {string} args.huId
- * @param {Function} [args.runner]
- * @returns {Promise<{ ok: boolean, sha?: string }>}
- */
-export async function hasHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const r = await run(["rev-parse", "--verify", "--quiet", ref], { cwd: projectDir });
-  if (r.exitCode !== 0) return { ok: false };
-  return { ok: true, sha: (r.stdout || "").trim() };
-}
-
-/**
- * Restaura el workspace al snapshot. DESTRUCTIVO: hace `git reset --hard`,
- * lo que descarta cambios no committeados. Caller debe avisar al usuario.
- *
- * @returns {Promise<{ ok: boolean, sha?: string, error?: string }>}
- */
-export async function restoreHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const has = await hasHuSnapshot({ projectDir, huId, runner: run });
-  if (!has.ok) return { ok: false, error: `snapshot no encontrado para HU ${huId}` };
-  const r = await run(["reset", "--hard", ref], { cwd: projectDir });
-  if (r.exitCode !== 0) {
-    return { ok: false, error: `reset --hard falló: ${(r.stderr || "").trim()}` };
-  }
-  return { ok: true, sha: has.sha };
-}
-
-/**
- * Borra el ref del snapshot. Idempotente: si no existe, devuelve ok:true.
- */
-export async function removeHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const r = await run(["update-ref", "-d", ref], { cwd: projectDir });
-  // git update-ref -d devuelve 0 incluso si el ref no existía.
-  if (r.exitCode !== 0) {
-    return { ok: false, error: `update-ref -d falló: ${(r.stderr || "").trim()}` };
-  }
-  return { ok: true };
-}

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

@@ -1,18 +0,0 @@
-// Barrel export for @karajan/core. Subpath imports
-// (e.g. `@karajan/core/atomic-write`) are the preferred shape — this
-// barrel only exists so a single `import { writeJsonAtomic } from
-// "@karajan/core"` keeps working for callers that want the whole API.
-
-export * from "./atomic-write.js";
-export * from "./shared-paths.js";
-export * from "./port-check.js";
-export * from "./paths.js";
-export * from "./run-registry.js";
-export * from "./vec-store.js";
-export * from "./plan-id.js";
-export * from "./plan-hu-ops.js";
-export * from "./plan-validation.js";
-export * from "./process.js";
-export * from "./hu-snapshot.js";
-export * from "./standby-store.js";
-export * from "./standby-scheduler.js";

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

@@ -1,123 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-// Per-process vitest root. We memoise the *root* (not the suffixed
-// `.karajan` / `.kj` path) so callers with different legacy defaults
-// — plan-store wants `.kj`, db.js wants `.karajan` — can share one
-// random tmp prefix per test run without colliding.
-let _vitestRoot = null;
-function vitestRoot() {
-  if (_vitestRoot) return _vitestRoot;
-  _vitestRoot = path.join(
-    os.tmpdir(),
-    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
-  );
-  // KJC-BUG-0075: clean up on clean exit so /tmp doesn't accumulate one
-  // dir per fork × run. `process.on('exit')` runs synchronously and only
-  // for graceful exits — SIGKILL leaks survive but are caught by the
-  // global-setup mtime purge at the start of the next run.
-  process.on("exit", () => {
-    try {
-      fs.rmSync(_vitestRoot, { recursive: true, force: true });
-    } catch {
-      // best-effort: never crash a test process on cleanup failure
-    }
-  });
-  return _vitestRoot;
-}
-
-function vitestTmpHome(defaultSegment) {
-  return path.join(vitestRoot(), defaultSegment);
-}
-
-// One-shot warning so users with KJ_HOME set in their shell rcfile do
-// not get spammed once per `kj` invocation. Reset across processes,
-// which is the granularity that matters for a humans-reading-stderr
-// audience.
-let _kjHomeWarned = false;
-function emitKjHomeDeprecationWarning() {
-  if (_kjHomeWarned) return;
-  _kjHomeWarned = true;
-  // eslint-disable-next-line no-console
-  console.warn(
-    "\x1b[33m[warn]\x1b[0m KJ_HOME is deprecated, rename to KARAJAN_HOME (KJ_HOME will be removed in a future release)"
-  );
-}
-
-/**
- * Unified resolver for Karajan's HOME-level storage root. Used by every
- * helper that previously rolled its own `getKjHome()` with subtly
- * different defaults and VITEST handling.
- *
- * Precedence (highest first):
- *   1. KARAJAN_HOME env var — explicit, no warning
- *   2. KJ_HOME env var      — explicit, prints deprecation warning once
- *   3. VITEST tmp dir       — auto-isolation under `os.tmpdir()/karajan-vitest-<pid>-<rand>/<defaultSegment>`
- *   4. `~/<defaultSegment>` — production default
- *
- * Callers pass `defaultSegment` so we can preserve `.kj` for legacy
- * paths (plan-store, standby-store) and `.karajan` for the canonical
- * root, until PR 3 unifies the defaults too.
- *
- * @param {object} [options]
- * @param {string} [options.defaultSegment=".karajan"]  HOME subdir name
- * @returns {string} absolute path
- */
-export function resolveHome({ defaultSegment = ".karajan" } = {}) {
-  if (process.env.KARAJAN_HOME) {
-    return path.resolve(process.env.KARAJAN_HOME);
-  }
-  if (process.env.KJ_HOME) {
-    emitKjHomeDeprecationWarning();
-    return path.resolve(process.env.KJ_HOME);
-  }
-  if (process.env.VITEST) {
-    return vitestTmpHome(defaultSegment);
-  }
-  return path.join(os.homedir(), defaultSegment);
-}
-
-/**
- * Canonical Karajan home (`~/.karajan` by default). Every helper that
- * used to roll its own `getKjHome()` now goes through this one — see
- * KJC-PCS-0047 PR 3 for the consolidation.
- */
-export function getKarajanHome() {
-  return resolveHome({ defaultSegment: ".karajan" });
-}
-
-// Test-only export. Tests that depend on observing the deprecation
-// warning being emitted exactly once need to reset the latch between
-// cases.
-export function __resetKjHomeWarningForTests() {
-  _kjHomeWarned = false;
-}
-
-export function getSessionRoot() {
-  return path.join(getKarajanHome(), "sessions");
-}
-
-export function getSonarComposePath() {
-  return path.join(getKarajanHome(), "docker-compose.sonar.yml");
-}
-
-/** Ollama RAG embedder compose: `<karajan-home>/docker-compose.ollama.yml` — KJC-TSK-0435. */
-export function getOllamaComposePath() {
-  return path.join(getKarajanHome(), "docker-compose.ollama.yml");
-}
-
-/** Webperf cache: `<karajan-home>/webperf/` — KJC-TSK-0420. */
-export function getWebperfDir() {
-  return path.join(getKarajanHome(), "webperf");
-}
-
-/** Run-registry: `<karajan-home>/runs/` — KJC-TSK-0420. */
-export function getRunsDir() {
-  return path.join(getKarajanHome(), "runs");
-}
-
-/** Board prompt bridge: `<karajan-home>/prompts/` — KJC-TSK-0420. */
-export function getPromptsDir() {
-  return path.join(getKarajanHome(), "prompts");
-}

package/node_modules/@karajan/core/src/plan-hu-ops.js

@@ -1,338 +0,0 @@
-/**
- * HU CRUD operations on a v2 plan.
- * All functions mutate the plan in-place and return it.
- */
-
-import { generateHuId } from "./plan-id.js";
-
-/**
- * Get the next sequential HU number for this plan.
- */
-function nextSeq(plan) {
-  if (!plan.hus || plan.hus.length === 0) return 1;
-  const nums = plan.hus
-    .map(h => {
-      const m = h.id.match(/_(\d+)$/);
-      return m ? Number(m[1]) : 0;
-    })
-    .filter(n => n > 0);
-  return nums.length > 0 ? Math.max(...nums) + 1 : plan.hus.length + 1;
-}
-
-/**
- * Add an HU to the plan. Auto-generates a globally unique ID.
- * @param {object} plan - v2 plan
- * @param {object} huData - { title, task_type?, scope?, acceptance_criteria?, acceptance_tests?, blocked_by?, reuse? }
- * @returns {object} the created HU (with id assigned)
- */
-export function addHu(plan, huData) {
-  const seq = nextSeq(plan);
-  const id = generateHuId(plan.planId, seq);
-  const hu = {
-    id,
-    title: huData.title,
-    task_type: huData.task_type || "sw",
-    status: "pending",
-    // KJC-TSK-0394: result ortogonal al status (último resultado conocido
-    // de la ejecución; null = nunca ejecutada). Se actualiza cuando el
-    // pipeline termina con pass / fail / partial. Nombre `result` (no
-    // `outcome`) porque `outcome` ya está en uso como blob JSON con
-    // iterations/duration/commits del run.
-    result: huData.result ?? null,
-    // Humanización IDs: short_id es el id legible que el planner asignó
-    // al step (ej "INFRA-001", "AUTH-SIGNUP"). El `id` largo
-    // (`hu_<planId>_<NNN>`) sigue siendo la clave canónica, pero el
-    // CLI / board prefieren short_id para mostrar y aceptarlo como
-    // referencia en `--hu`. Null cuando el planner no lo emitió.
-    short_id: huData.short_id || null,
-    blocked_by: huData.blocked_by || [],
-    // KJC-BUG-0044 / P3: ids of OTHER HUs whose implementation this HU
-    // piggy-backs on instead of reimplementing the same logic. Set by
-    // the planner; consumed by the coder prompt + plan-reviewer to
-    // avoid duplicate code generation.
-    reuse: huData.reuse || [],
-    scope: huData.scope || null,
-    acceptance_criteria: huData.acceptance_criteria || [],
-    acceptance_tests: huData.acceptance_tests || [],
-    // Spec mapping (v2.7.5 PR C): the SPEC.md section / heading this
-    // HU implements. Lets the coder cite "this implements SPEC §5.3"
-    // in PRs and the reviewer trace coverage gaps when the SPEC is
-    // re-read. Free-form string — typically "5.3", "§5.3 Initial
-    // Scope", or whatever the planner extracted from the source spec.
-    spec_section: huData.spec_section || null,
-    // KJC-TSK-0405: coder_model y reviewer_model asignados por el
-    // triage según complexity. null = usar el del config global / role
-    // resolver. Independientes — el usuario puede overridearlos por HU
-    // desde el board sin tocar el resto del plan.
-    coder_model: huData.coder_model ?? null,
-    coder_provider: huData.coder_provider ?? null,
-    reviewer_model: huData.reviewer_model ?? null,
-    reviewer_provider: huData.reviewer_provider ?? null,
-    // KJC-PRP-0002 PR6: optional handle of the human (or AI dev_XXX) who
-    // owns this HU in a team-shared board. null = unassigned. Free-form
-    // string — the board prints it as-is; no entity table is enforced
-    // because team rosters are out of scope (and would force every solo
-    // dev to register themselves).
-    assignee: huData.assignee ?? null,
-    createdAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString()
-  };
-  plan.hus.push(hu);
-  plan.updatedAt = new Date().toISOString();
-  return hu;
-}
-
-/**
- * Remove an HU from the plan. Also cleans blocked_by references.
- * @returns {boolean} true if removed
- */
-export function removeHu(plan, huId) {
-  const idx = plan.hus.findIndex(h => h.id === huId);
-  if (idx === -1) return false;
-  plan.hus.splice(idx, 1);
-  // Clean up blocked_by + reuse refs
-  for (const hu of plan.hus) {
-    hu.blocked_by = (hu.blocked_by || []).filter(dep => dep !== huId);
-    hu.reuse = (hu.reuse || []).filter(dep => dep !== huId);
-  }
-  plan.updatedAt = new Date().toISOString();
-  return true;
-}
-
-/**
- * Partial update of an HU.
- * @param {object} plan
- * @param {string} huId
- * @param {object} patch - fields to update (title, scope, task_type, acceptance_criteria, acceptance_tests, blocked_by)
- * @returns {object|null} updated HU or null if not found
- */
-export function updateHu(plan, huId, patch) {
-  const hu = plan.hus.find(h => h.id === huId);
-  if (!hu) return null;
-  // KJC-TSK-0405: coder_model y reviewer_model son override per-HU del
-  // routing automático del triage. Independientes — el usuario puede
-  // subir el reviewer sin tocar el coder, o viceversa.
-  const allowed = ["title", "task_type", "scope", "acceptance_criteria", "acceptance_tests", "blocked_by", "reuse", "spec_section", "result", "short_id", "coder_model", "reviewer_model", "coder_provider", "reviewer_provider", "assignee"];
-  for (const key of allowed) {
-    if (patch[key] !== undefined) hu[key] = patch[key];
-  }
-  hu.updatedAt = new Date().toISOString();
-  plan.updatedAt = new Date().toISOString();
-  return hu;
-}
-
-/**
- * Update HU status.
- * @returns {boolean} true if updated
- */
-export function updateHuStatus(plan, huId, status) {
-  const hu = plan.hus.find(h => h.id === huId);
-  if (!hu) return false;
-  hu.status = status;
-  hu.updatedAt = new Date().toISOString();
-  plan.updatedAt = new Date().toISOString();
-  return true;
-}
-
-/**
- * Stamp the per-HU outcome — what actually happened during execution.
- * Written ONCE per HU, at the end of runSingleHu in hu-sub-pipeline.
- * Consumed by the board to render the per-HU summary indicator and
- * by `kj report` for retrospective inspection.
- *
- * Shape (every field optional except status + finishedAt):
- *   {
- *     status:       "done" | "failed" | "blocked",
- *     iterations:   number,        // how many coder→reviewer rounds
- *     duration_ms:  number,        // wall-clock for this HU
- *     branch:       string|null,   // git branch the coder used
- *     commits:      string[],      // SHA list captured during the run
- *     pr_url:       string|null,
- *     blockers:     string[],      // why it failed/was blocked, plain
- *     summary:      string,        // 1-2 sentence human summary
- *     finishedAt:   ISO timestamp
- *   }
- *
- * @returns {boolean} true if the HU was found and the outcome stored
- */
-export function setHuOutcome(plan, huId, outcome) {
-  const hu = plan.hus.find(h => h.id === huId);
-  if (!hu) return false;
-  hu.outcome = {
-    status: outcome.status || hu.status || null,
-    iterations: outcome.iterations ?? null,
-    duration_ms: outcome.duration_ms ?? null,
-    branch: outcome.branch ?? null,
-    commits: Array.isArray(outcome.commits) ? outcome.commits : [],
-    pr_url: outcome.pr_url ?? null,
-    blockers: Array.isArray(outcome.blockers) ? outcome.blockers : [],
-    summary: outcome.summary || "",
-    finishedAt: outcome.finishedAt || new Date().toISOString(),
-  };
-  hu.updatedAt = new Date().toISOString();
-  plan.updatedAt = new Date().toISOString();
-  return true;
-}
-
-/**
- * Stamp the plan-level rollup once every HU has finished. Built from
- * the per-HU outcomes so the board can show "Plan finished · 8 done
- * · 2 failed · 1 blocked · 15 min" in one banner.
- *
- *   {
- *     status:       "done" | "partial" | "failed",
- *     total:        number,
- *     counts:       { done, failed, blocked, pending },
- *     duration_ms:  number,
- *     prs:          string[],            // unique pr_url across HUs
- *     blockers:     string[],            // dedup'd blockers
- *     finishedAt:   ISO timestamp,
- *   }
- */
-export function setPlanOutcome(plan, outcome) {
-  plan.outcome = {
-    status: outcome.status || "partial",
-    total: outcome.total ?? (plan.hus?.length || 0),
-    counts: outcome.counts || { done: 0, failed: 0, blocked: 0, pending: 0 },
-    duration_ms: outcome.duration_ms ?? null,
-    prs: Array.isArray(outcome.prs) ? [...new Set(outcome.prs.filter(Boolean))] : [],
-    blockers: Array.isArray(outcome.blockers) ? [...new Set(outcome.blockers.filter(Boolean))] : [],
-    finishedAt: outcome.finishedAt || new Date().toISOString(),
-  };
-  plan.updatedAt = new Date().toISOString();
-}
-
-/**
- * PR-E: auto-promote every pending HU with at least one acceptance
- * test to "certified". The intermediate "certified" state was an
- * invisible wall — there's no UI button for it and the user had no
- * way to discover `kj plan ready`. Treating pending-with-tests as
- * runnable removes the wall while keeping the test contract gate.
- *
- * Mutates plan in place. HUs in done / failed / blocked are left
- * alone so re-runs stay explicit (use --hu <id>).
- *
- * @returns {number} how many HUs were promoted (0 if nothing changed).
- */
-export function autoCertifyPendingHus(plan) {
-  if (!plan?.hus?.length) return 0;
-  let promoted = 0;
-  const now = new Date().toISOString();
-  for (const hu of plan.hus) {
-    if (hu.status === "pending" && Array.isArray(hu.acceptance_tests) && hu.acceptance_tests.length > 0) {
-      hu.status = "certified";
-      hu.updatedAt = now;
-      promoted += 1;
-    }
-  }
-  if (promoted > 0) plan.updatedAt = now;
-  return promoted;
-}
-
-/**
- * PR-E: assert that the plan has at least one HU that's actually
- * going to run. Throws with a plain-Spanish message otherwise so
- * `kj run --plan` can never silently fall back to single-task mode
- * and burn tokens for nothing.
- *
- * The set of "runnable" statuses matches the sub-pipeline filter
- * (today: certified). The caller should run autoCertifyPendingHus()
- * BEFORE this so pending-with-tests get a chance.
- *
- * @throws {Error} when no HU is runnable.
- */
-export function assertPlanRunnable(plan, planId) {
-  if (!plan?.hus?.length) {
-    throw new Error(
-      `El plan ${planId} no contiene ninguna HU. `
-      + `Edita el plan o vuelve a generarlo con \`kj plan\`. `
-      + `Aborto para no malgastar tokens en un fallback de "single task".`
-    );
-  }
-  const certified = plan.hus.filter((h) => h.status === "certified").length;
-  if (certified > 0) return;
-  const counts = plan.hus.reduce((acc, h) => {
-    const k = h.status || "pending";
-    acc[k] = (acc[k] || 0) + 1;
-    return acc;
-  }, {});
-  const summary = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(", ");
-  throw new Error(
-    `Plan ${planId}: 0 HU(s) listas para ejecutar (estados: ${summary}). `
-    + `Si las HU(s) están en done/failed/blocked y quieres relanzarlas, usa --hu <id>. `
-    + `Aborto para no malgastar tokens en un fallback de "single task".`
-  );
-}
-
-/**
- * Compute the rollup from the per-HU outcomes already stamped on the
- * plan. Invoked by syncResultsToPlan in plan-executor when the run
- * ends so the caller doesn't have to assemble the counts by hand.
- */
-export function computePlanOutcome(plan, { duration_ms = null } = {}) {
-  const hus = plan.hus || [];
-  const counts = { done: 0, failed: 0, blocked: 0, pending: 0 };
-  const prs = [];
-  const blockers = [];
-  for (const hu of hus) {
-    const status = hu.outcome?.status || hu.status || "pending";
-    if (counts[status] !== undefined) counts[status] += 1;
-    else counts.pending += 1;
-    if (hu.outcome?.pr_url) prs.push(hu.outcome.pr_url);
-    if (Array.isArray(hu.outcome?.blockers)) blockers.push(...hu.outcome.blockers);
-  }
-  let status = "done";
-  if (counts.failed > 0 || counts.blocked > 0) status = counts.done > 0 ? "partial" : "failed";
-  if (counts.done === 0 && counts.failed === 0 && counts.blocked === 0) status = "pending";
-  return {
-    status,
-    total: hus.length,
-    counts,
-    duration_ms,
-    // Dedupe at the rollup boundary — same PR / blocker reported by
-    // multiple HUs is noise in the banner.
-    prs: [...new Set(prs.filter(Boolean))],
-    blockers: [...new Set(blockers.filter(Boolean))],
-    finishedAt: new Date().toISOString(),
-  };
-}
-
-/**
- * Mark all pending HUs as certified (ready to execute).
- * Sets plan status to "ready".
- * @returns {number} count of certified HUs
- */
-export function certifyAllHus(plan) {
-  let count = 0;
-  for (const hu of plan.hus) {
-    if (hu.status === "pending") {
-      hu.status = "certified";
-      hu.updatedAt = new Date().toISOString();
-      count++;
-    }
-  }
-  plan.status = "ready";
-  plan.updatedAt = new Date().toISOString();
-  return count;
-}
-
-/**
- * Reorder HUs by providing an ordered list of IDs.
- * Updates blocked_by to reflect the linear order.
- * @param {object} plan
- * @param {string[]} orderedIds
- */
-export function reorderHus(plan, orderedIds) {
-  const map = new Map(plan.hus.map(h => [h.id, h]));
-  const reordered = [];
-  for (const id of orderedIds) {
-    const hu = map.get(id);
-    if (hu) reordered.push(hu);
-  }
-  // Add any HUs not in the ordered list at the end
-  for (const hu of plan.hus) {
-    if (!orderedIds.includes(hu.id)) reordered.push(hu);
-  }
-  plan.hus = reordered;
-  plan.updatedAt = new Date().toISOString();
-}