karajan-code 2.19.0 → 2.19.2

package/packages/hu-board/src/auth.js

@@ -0,0 +1,92 @@
+/**
+ * Bearer-token authentication middleware for HU Board.
+ *
+ * Threat model — KJC-TSK-0355:
+ *   The board is a localhost dev tool. The "shared dev machine" risk
+ *   only kicks in when the server binds beyond loopback (e.g.
+ *   `--bind 0.0.0.0` to access from another laptop on LAN). For pure
+ *   loopback traffic, the OS already enforces "only the local user
+ *   can connect", so a token would be UX friction with zero benefit
+ *   (the browser opens `http://localhost:4000` and would stop working
+ *   without manual `?token=...` injection on every link).
+ *
+ * Behaviour:
+ *   - When `HU_BOARD_TOKEN` is set AND the request is from a non-
+ *     loopback address → require the token in `Authorization: Bearer`
+ *     header, `?token=` query param, or `kj_board_token` cookie.
+ *   - When the request comes from loopback (127.0.0.1 / ::1 / ::ffff:127.0.0.1)
+ *     → skip auth. The browser running on the same machine just works.
+ *   - When `HU_BOARD_TOKEN` is unset → skip auth entirely. Tests and
+ *     legacy callers keep working.
+ */
+
+/** Loopback addresses we trust without auth, regardless of token state. */
+const LOOPBACK_ADDRESSES = new Set([
+  "127.0.0.1",
+  "::1",
+  "::ffff:127.0.0.1",
+]);
+
+/**
+ * Returns an Express middleware that enforces token auth for non-
+ * loopback requests when HU_BOARD_TOKEN is defined.
+ *
+ * @returns {import('express').RequestHandler}
+ */
+export function authMiddleware() {
+  return (req, res, next) => {
+    const expected = process.env.HU_BOARD_TOKEN;
+    if (!expected) return next();
+
+    if (isLoopback(req)) return next();
+
+    const token = extractToken(req);
+    if (token === expected) return next();
+
+    return res.status(401).json({
+      error: "Unauthorized",
+      message:
+        "HU Board is bound to a non-loopback interface. Pass the token from " +
+        "~/.karajan/hu-board/token via Authorization: Bearer <token>, " +
+        "?token=<token>, or the kj_board_token cookie.",
+    });
+  };
+}
+
+/**
+ * @param {import('express').Request} req
+ * @returns {boolean}
+ */
+function isLoopback(req) {
+  // Express populates req.ip from req.socket.remoteAddress unless
+  // `trust proxy` is set (we don't, by design — the board never sits
+  // behind a proxy in its supported deployment). req.ip is therefore
+  // the actual peer address.
+  const ip = req.ip || req.socket?.remoteAddress || "";
+  return LOOPBACK_ADDRESSES.has(ip);
+}
+
+/**
+ * @param {import('express').Request} req
+ * @returns {string|undefined}
+ */
+function extractToken(req) {
+  const authHeader = req.headers.authorization;
+  if (authHeader && authHeader.startsWith("Bearer ")) {
+    return authHeader.slice(7);
+  }
+  if (req.query && typeof req.query.token === "string") {
+    return req.query.token;
+  }
+  // Cookie parsing: we don't pull cookie-parser as a dep just for one
+  // header. Express stores the raw header in req.headers.cookie; the
+  // grammar is `name=value; name2=value2`. Good enough for one key.
+  const cookieHeader = req.headers.cookie;
+  if (cookieHeader) {
+    for (const part of cookieHeader.split(";")) {
+      const [name, ...rest] = part.trim().split("=");
+      if (name === "kj_board_token") return rest.join("=");
+    }
+  }
+  return undefined;
+}

package/packages/hu-board/src/boot-info.js

@@ -0,0 +1,16 @@
+/**
+ * Process-scoped boot info (KJC-TSK-0379).
+ *
+ * BOOT_TIME is captured at module load and exposed via /api/version so
+ * the client can detect server restarts and trigger a reload. Lives in
+ * its own module to avoid the server.js ↔ routes/api.js import cycle.
+ */
+
+import { createRequire } from 'node:module';
+
+export const BOOT_TIME = new Date().toISOString();
+
+const require = createRequire(import.meta.url);
+export const PKG_VERSION = (() => {
+  try { return require('../package.json').version; } catch { return 'unknown'; }
+})();

package/packages/hu-board/src/cleanup-zombies.js

@@ -0,0 +1,142 @@
+/**
+ * Cleanup zombi resources of the HU Board (KJC-TSK-0380 PR C).
+ *
+ * Detects and removes orphan / abandoned entries that survive across
+ * dogfooding sessions and would otherwise reappear on every fullScan:
+ *
+ *  1. Ephemeral projects (`tmp_*`, `test_*`, `demo_*`, `kj-test-*`,
+ *     `s_*`, `plan-*`) older than `staleProjectDays` (default 7).
+ *  2. Stale prompts (no `.answer.json` and file mtime older than
+ *     `stalePromptHours`, default 24).
+ *  3. Orphan session directories (`~/.karajan/sessions/<id>/`) older
+ *     than `staleProjectDays` with no matching DB row.
+ *
+ * Each removal goes through the same path the API endpoints use:
+ * tombstone + fs cleanup. So nothing resurrects on the next sync.
+ *
+ * Usage:
+ *   import { cleanupZombies } from './cleanup-zombies.js';
+ *   const report = cleanupZombies({ dryRun: false });
+ *
+ * Pure module; no HTTP. Safe to call with the server down.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import {
+  getDb,
+  getKjHome,
+  addTombstone,
+  isTombstoned,
+  deleteProject,
+  deleteSession,
+  initDb,
+  closeDb,
+} from './db.js';
+
+// Re-export the db lifecycle helpers so callers (e.g. `kj board cleanup`)
+// can do a single `await import('cleanup-zombies.js')` and stay within
+// the project's dynamic-import budget. The script otherwise needs both
+// initDb/closeDb (lifecycle) and cleanupZombies (logic).
+export { initDb, closeDb };
+
+const EPHEMERAL_PREFIXES = ['tmp_', 'test_', 'demo_', 'kj-test-', 's_', 'plan-'];
+
+function isEphemeralId(id) {
+  return EPHEMERAL_PREFIXES.some((p) => id.startsWith(p));
+}
+
+function plansRoot() {
+  return process.env.KJ_PLANS_DIR || path.join(homedir(), '.kj', 'plans');
+}
+
+function olderThanDays(isoStr, days) {
+  if (!isoStr) return true;
+  const t = Date.parse(isoStr);
+  if (Number.isNaN(t)) return true;
+  return (Date.now() - t) > days * 24 * 60 * 60 * 1000;
+}
+
+function olderThanHours(mtimeMs, hours) {
+  return (Date.now() - mtimeMs) > hours * 60 * 60 * 1000;
+}
+
+/**
+ * @param {object} opts
+ * @param {boolean} [opts.dryRun=false] - Compute the report without writing.
+ * @param {number}  [opts.staleProjectDays=7]
+ * @param {number}  [opts.stalePromptHours=24]
+ * @returns {{ projects: string[], prompts: string[], sessions: string[], dryRun: boolean }}
+ */
+export function cleanupZombies(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const staleProjectDays = opts.staleProjectDays ?? 7;
+  const stalePromptHours = opts.stalePromptHours ?? 24;
+
+  const report = { projects: [], prompts: [], sessions: [], dryRun };
+  const db = getDb();
+
+  // (1) Ephemeral projects -------------------------------------------------
+  const allProjects = db.prepare('SELECT id, last_activity FROM projects').all();
+  for (const proj of allProjects) {
+    if (!isEphemeralId(proj.id)) continue;
+    if (!olderThanDays(proj.last_activity, staleProjectDays)) continue;
+    report.projects.push(proj.id);
+    if (dryRun) continue;
+
+    const storyIds = db.prepare('SELECT id FROM stories WHERE project_id = ?').all(proj.id).map((r) => r.id);
+    const sessionIds = db.prepare('SELECT id FROM sessions WHERE project_id = ?').all(proj.id).map((r) => r.id);
+    const fsPaths = [
+      ...storyIds.map((sid) => path.join(getKjHome(), 'hu-stories', sid)),
+      ...sessionIds.map((sid) => path.join(getKjHome(), 'sessions', sid)),
+      path.join(plansRoot(), proj.id),
+    ];
+    deleteProject(proj.id);
+    addTombstone('project', proj.id, { source: 'auto-cleanup', fsPaths });
+    for (const sid of storyIds) addTombstone('story', sid, { source: 'auto-cleanup' });
+    for (const sid of sessionIds) addTombstone('session', sid, { source: 'auto-cleanup' });
+    for (const p of fsPaths) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* */ } }
+  }
+
+  // (2) Stale prompts ------------------------------------------------------
+  const promptsDir = path.join(getKjHome(), 'prompts');
+  if (fs.existsSync(promptsDir)) {
+    for (const name of fs.readdirSync(promptsDir)) {
+      if (!name.endsWith('.json') || name.endsWith('.answer.json')) continue;
+      const promptId = name.replace(/\.json$/, '');
+      if (isTombstoned('prompt', promptId)) continue;
+      const fullPath = path.join(promptsDir, name);
+      const answerPath = path.join(promptsDir, `${promptId}.answer.json`);
+      if (fs.existsSync(answerPath)) continue; // already resolved
+      const stat = fs.statSync(fullPath);
+      if (!olderThanHours(stat.mtimeMs, stalePromptHours)) continue;
+      report.prompts.push(promptId);
+      if (dryRun) continue;
+      addTombstone('prompt', promptId, { source: 'auto-cleanup', fsPaths: [fullPath, answerPath] });
+      try { fs.unlinkSync(fullPath); } catch { /* */ }
+    }
+  }
+
+  // (3) Orphan session directories ----------------------------------------
+  const sessionsDir = path.join(getKjHome(), 'sessions');
+  if (fs.existsSync(sessionsDir)) {
+    for (const dir of fs.readdirSync(sessionsDir)) {
+      if (isTombstoned('session', dir)) continue;
+      const fullPath = path.join(sessionsDir, dir);
+      const stat = fs.statSync(fullPath);
+      if (!stat.isDirectory()) continue;
+      const inDb = db.prepare('SELECT id FROM sessions WHERE id = ?').get(dir);
+      if (inDb) continue; // active session, not orphan
+      const mtimeIso = new Date(stat.mtimeMs).toISOString();
+      if (!olderThanDays(mtimeIso, staleProjectDays)) continue;
+      report.sessions.push(dir);
+      if (dryRun) continue;
+      deleteSession(dir);
+      addTombstone('session', dir, { source: 'auto-cleanup', fsPaths: [fullPath] });
+      try { fs.rmSync(fullPath, { recursive: true, force: true }); } catch { /* */ }
+    }
+  }
+
+  return report;
+}

package/packages/hu-board/src/command-runner.js

@@ -0,0 +1,134 @@
+/**
+ * Generic Karajan-CLI launcher used by the board's "Commands" panel.
+ * Wraps the same spawn-detached-with-log pattern that `runPlan`
+ * already uses (see plan-mutations.js), but covers the broader set
+ * of commands the user wants to trigger from the UI: plan,
+ * architect, clean, etc.
+ *
+ * Security: the command name is matched against an explicit
+ * whitelist. Free-form arg arrays are NOT allowed — each command
+ * builds its argv from a typed schema. This keeps a curious browser
+ * client from doing `node cli.js -e "rm -rf /"` via a crafted POST.
+ *
+ * Output: each command writes to `~/.karajan/hu-board-runs/
+ * cmd-<commandId>.log`, which the existing `/api/plans/:planId/log`
+ * endpoint can tail (we generalise it to take a log id, not just a
+ * planId, in routes/api.js).
+ */
+
+import { mkdirSync, openSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+
+// Repo root → so we can spawn `node <repo>/src/cli.js …` regardless
+// of whether `kj` is on $PATH for the board process.
+const REPO_ROOT = (() => {
+  const here = dirname(fileURLToPath(import.meta.url));     // packages/hu-board/src
+  return join(here, "..", "..", "..");                       // → repo root
+})();
+const KJ_CLI = join(REPO_ROOT, "src", "cli.js");
+
+// Path now lives in db.js::getHuBoardRunsDir() — KJC-TSK-0421
+// unification. The local helper is gone; callers import directly.
+import { getHuBoardRunsDir } from "./db.js";
+
+/**
+ * Whitelist + argv builders. Each entry maps a logical command name
+ * (`plan`, `architect`, `clean`) to a function that turns the
+ * board-side input into a CLI argv. Adding a new command means: add
+ * an entry here and an entry in the board UI's `COMMANDS` table.
+ *
+ * Why typed builders instead of a generic args array: the browser
+ * client can't smuggle arbitrary flags. Anything that's not in the
+ * whitelist is rejected with 400.
+ *
+ * Each builder returns `{ args, projectDir? }`. `projectDir` is the
+ * cwd the spawn should use (defaults to the board's cwd).
+ */
+const COMMAND_BUILDERS = {
+  plan: (input) => {
+    const args = ["plan"];
+    if (input.taskFile) args.push("--task-file", String(input.taskFile));
+    if (input.context) args.push("--context", String(input.context));
+    if (input.quick) args.push("--quick");
+    if (input.noTestsSynth) args.push("--no-tests-synth");
+    if (input.noPlanReview) args.push("--no-plan-review");
+    // Positional task goes last when no --task-file was given.
+    if (!input.taskFile && input.task) args.push(String(input.task));
+    return { args, projectDir: input.projectDir };
+  },
+  architect: (input) => {
+    const args = ["architect"];
+    if (input.taskFile) args.push("--task-file", String(input.taskFile));
+    if (input.context) args.push("--context", String(input.context));
+    if (!input.taskFile && input.task) args.push(String(input.task));
+    return { args, projectDir: input.projectDir };
+  },
+  clean: (input) => {
+    const args = ["clean", "--yes"];      // never prompt; UI confirms ahead
+    if (input.nuke) args.push("--nuke");
+    if (input.dryRun) args.push("--dry-run");
+    return { args };
+  },
+};
+
+/**
+ * Spawn the requested CLI command as a detached child. Returns
+ * `{ ok, commandId, pid, logPath, argv }` so the caller can offer
+ * the log to the user via the existing log viewer.
+ *
+ * Test seam: `KJ_RUN_SPAWN_MODE=echo` short-circuits the spawn so
+ * vitest doesn't actually boot the orchestrator.
+ *
+ * @param {object} args
+ * @param {string} args.command  - one of the COMMAND_BUILDERS keys
+ * @param {object} [args.input]
+ * @returns {{ ok: boolean, commandId?: string, pid?: number,
+ *             logPath?: string, argv?: string[], error?: string }}
+ */
+export function runKjCommand({ command, input = {} } = {}) {
+  const build = COMMAND_BUILDERS[command];
+  if (!build) {
+    return { ok: false, error: `Unsupported command: ${command}. Allowed: ${Object.keys(COMMAND_BUILDERS).join(", ")}` };
+  }
+
+  let built;
+  try {
+    built = build(input);
+  } catch (err) {
+    return { ok: false, error: `Bad input for "${command}": ${err.message}` };
+  }
+
+  const dir = getHuBoardRunsDir();
+  mkdirSync(dir, { recursive: true });
+  const commandId = `cmd-${command}-${Date.now()}-${randomUUID().slice(0, 8)}`;
+  const logPath = join(dir, `${commandId}.log`);
+  const argv = [KJ_CLI, ...built.args];
+
+  if (process.env.KJ_RUN_SPAWN_MODE === "echo") {
+    return { ok: true, commandId, pid: 0, logPath, argv: [process.execPath, ...argv] };
+  }
+
+  const out = openSync(logPath, "a");
+  const err = openSync(logPath, "a");
+  const child = spawn(process.execPath, argv, {
+    cwd: built.projectDir || process.cwd(),
+    detached: true,
+    stdio: ["ignore", out, err],
+    // KJ_INSIDE_BOARD: lets `kj clean --nuke` skip SIGTERMing the
+    // board (it'd kill the page the user is looking at). Other
+    // future "is this run hosted by the board" branches can read
+    // the same flag.
+    env: { ...process.env, CLAUDECODE: undefined, KJ_INSIDE_BOARD: "1" },
+  });
+  child.unref();
+  return { ok: true, commandId, pid: child.pid ?? 0, logPath };
+}
+
+/** Test helper: list of command names exposed. */
+export function listSupportedCommands() {
+  return Object.keys(COMMAND_BUILDERS);
+}

package/packages/hu-board/src/config-yaml.js

@@ -0,0 +1,285 @@
+/**
+ * Read / write the global Karajan config (~/.karajan/kj.config.yml)
+ * from the board.
+ *
+ * The board is a Node Express server that the user already has
+ * running, so it's the natural place to expose a "settings" page —
+ * no extra terminal trip, no risk of malformed YAML, plain Spanish
+ * labels for non-technical users.
+ *
+ * Design notes:
+ *
+ * - The yml may contain dozens of fields (legacy, advanced, future
+ *   experiments). The board only EXPOSES + EDITS a small whitelist
+ *   that maps to the labels the UI shows. Everything else is read,
+ *   preserved verbatim, and written back unchanged. So a power
+ *   user editing the file by hand never loses keys when they later
+ *   touch the modal.
+ *
+ * - Writes go through a tmp-file + atomic rename so a partial
+ *   write never leaves the user with a corrupt yml.
+ *
+ * - A `.bak` copy is kept of the previous content so the user can
+ *   recover from a botched save outside the modal (rare but
+ *   irrecoverable otherwise).
+ *
+ * - VITEST aware: when KJ_HOME is set we honour it (every test
+ *   harness uses tmp dirs already). When not set we use
+ *   `~/.karajan/kj.config.yml` like the rest of Karajan does.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import yaml from 'js-yaml';
+import { getKjHome } from './db.js';
+
+function configPath() {
+  // Same path the parent uses (src/utils/paths.js::getKarajanHome).
+  // KJC-TSK-0420: delegate to db.js::getKjHome — gives us KARAJAN_HOME
+  // priority + KJ_HOME fallback + VITEST guard from one place, instead
+  // of duplicating the precedence here.
+  return join(getKjHome(), 'kj.config.yml');
+}
+
+function backupPath() { return `${configPath()}.bak`; }
+
+/**
+ * Whitelist of fields the board's modal exposes. Everything else
+ * stays untouched in the yml. Each entry says where in the yml the
+ * field lives (`path`) and how to render it for the UI (`type`,
+ * `label`, `options` for selects).
+ *
+ * The path is a dotted notation we resolve manually (so we never
+ * need to take a runtime dep on lodash for `_.get`/`_.set`).
+ */
+export const EDITABLE_FIELDS = [
+  {
+    key: 'coder',
+    path: 'coder',
+    type: 'select',
+    label: 'Agente para el rol "coder"',
+    help: 'Quién escribe el código. Claude es el más fiable, Codex es más rápido.',
+    options: ['claude', 'codex', 'gemini', 'aider'],
+    default: 'claude',
+  },
+  {
+    key: 'reviewer',
+    path: 'reviewer',
+    type: 'select',
+    label: 'Agente para el rol "reviewer"',
+    help: 'Quién revisa el código del coder. Conviene que sea un agente distinto al coder para detectar errores.',
+    options: ['claude', 'codex', 'gemini', 'aider'],
+    default: 'codex',
+  },
+  {
+    key: 'modelMode',
+    path: '_modelMode_virtual',
+    type: 'select',
+    label: 'Estrategia de modelos',
+    help: 'Auto = Karajan elige el modelo según la complejidad (haiku/sonnet/opus). Sonnet siempre = barato, ideal para pruebas. Opus siempre = caro, máxima calidad.',
+    options: ['auto', 'sonnet', 'opus'],
+    default: 'auto',
+    // Virtual field: doesn't map 1:1 to a yml key. Translate when
+    // reading + writing (see readConfig + writeConfigPatch).
+  },
+  {
+    key: 'maxIterationMinutes',
+    path: 'session.max_iteration_minutes',
+    type: 'number',
+    label: 'Tope de minutos por iteración',
+    help: 'Si una iteración (coder + reviewer) supera este tiempo, Karajan la corta y Solomon decide qué hacer.',
+    min: 1,
+    max: 120,
+    default: 30,
+  },
+  {
+    key: 'maxTotalMinutes',
+    path: 'session.max_total_minutes',
+    type: 'number',
+    label: 'Tope de minutos total por sesión',
+    help: 'Tope absoluto del wall-clock de la sesión. Si se llega aquí, Karajan para aunque queden HUs.',
+    min: 5,
+    max: 480,
+    default: 120,
+  },
+  {
+    key: 'sonarEnabled',
+    path: 'sonarqube.enabled',
+    type: 'boolean',
+    label: 'Activar análisis SonarQube',
+    help: 'Pasa el código por SonarQube y bloquea si el quality gate falla. Requiere SonarQube corriendo.',
+    default: false,
+  },
+];
+
+const ROLES_FOR_MODEL_MODE = [
+  'planner', 'architect', 'coder', 'reviewer', 'triage',
+  'researcher', 'tester', 'security', 'refactorer', 'impeccable'
+];
+
+function getDeep(obj, path) {
+  if (!obj || !path) return undefined;
+  const parts = path.split('.');
+  let cur = obj;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function setDeep(obj, path, value) {
+  const parts = path.split('.');
+  const last = parts.pop();
+  let cur = obj;
+  for (const p of parts) {
+    if (cur[p] == null || typeof cur[p] !== 'object') cur[p] = {};
+    cur = cur[p];
+  }
+  cur[last] = value;
+}
+
+function deleteDeep(obj, path) {
+  const parts = path.split('.');
+  const last = parts.pop();
+  let cur = obj;
+  for (const p of parts) {
+    if (cur == null || typeof cur !== 'object') return;
+    cur = cur[p];
+  }
+  if (cur && typeof cur === 'object') delete cur[last];
+}
+
+/**
+ * Derive the virtual `modelMode` from the actual yml shape. Looks at
+ * roles.<role>.model: if every editable role pins the same model,
+ * that's the mode. Otherwise "auto" (the default — Karajan's
+ * smart-select picks per role).
+ */
+function deriveModelMode(parsed) {
+  const roles = parsed?.roles;
+  if (!roles || typeof roles !== 'object') return 'auto';
+  const seen = new Set();
+  for (const r of ROLES_FOR_MODEL_MODE) {
+    const m = roles[r]?.model;
+    if (m) seen.add(String(m).toLowerCase());
+  }
+  if (seen.size === 1) {
+    const only = [...seen][0];
+    if (only === 'sonnet' || only === 'opus') return only;
+  }
+  return 'auto';
+}
+
+/**
+ * Apply the virtual `modelMode` back to the yml: 'auto' deletes the
+ * roles.<r>.model overrides; 'sonnet' / 'opus' set them on every
+ * editable role. Other yml keys are left alone.
+ */
+function applyModelMode(parsed, mode) {
+  if (!parsed.roles) parsed.roles = {};
+  if (mode === 'auto') {
+    for (const r of ROLES_FOR_MODEL_MODE) {
+      if (parsed.roles[r]?.model) delete parsed.roles[r].model;
+      if (parsed.roles[r] && Object.keys(parsed.roles[r]).length === 0) delete parsed.roles[r];
+    }
+    if (Object.keys(parsed.roles).length === 0) delete parsed.roles;
+    return;
+  }
+  for (const r of ROLES_FOR_MODEL_MODE) {
+    if (!parsed.roles[r] || typeof parsed.roles[r] !== 'object') parsed.roles[r] = {};
+    parsed.roles[r].model = mode;
+  }
+}
+
+/**
+ * Read the current config + flatten it into the shape the UI wants:
+ *   {
+ *     path: "/abs/path",
+ *     fields: [{ key, label, help, type, options?, value, default }],
+ *     raw: <full parsed yml>          // power-user inspection
+ *   }
+ *
+ * Returns sane defaults when the file doesn't exist yet.
+ */
+export function readConfig() {
+  const p = configPath();
+  let parsed = {};
+  let exists = false;
+  if (existsSync(p)) {
+    try {
+      parsed = yaml.load(readFileSync(p, 'utf8'), { json: true }) || {};
+      exists = true;
+    } catch (err) {
+      throw new Error(`No se pudo parsear ${p}: ${err.message}`);
+    }
+  }
+  const fields = EDITABLE_FIELDS.map((f) => {
+    let value;
+    if (f.key === 'modelMode') value = deriveModelMode(parsed);
+    else value = getDeep(parsed, f.path);
+    if (value === undefined) value = f.default;
+    return { ...f, value };
+  });
+  return { path: p, exists, fields, raw: parsed };
+}
+
+/**
+ * Apply a patch (subset of EDITABLE_FIELDS keys → new values) to the
+ * yml. Validates each field; refuses unknown keys. Writes via tmp +
+ * rename; keeps a .bak.
+ *
+ * @returns {{ path: string, written: boolean, applied: object[], errors: string[] }}
+ */
+export function writeConfigPatch(patch) {
+  if (!patch || typeof patch !== 'object') {
+    return { path: configPath(), written: false, applied: [], errors: ['patch debe ser un objeto'] };
+  }
+  // Read current state (or empty if file doesn't exist yet).
+  const p = configPath();
+  let parsed = {};
+  if (existsSync(p)) {
+    try { parsed = yaml.load(readFileSync(p, 'utf8'), { json: true }) || {}; }
+    catch (err) { return { path: p, written: false, applied: [], errors: [`No se pudo parsear el yml actual: ${err.message}`] }; }
+  }
+  const errors = [];
+  const applied = [];
+  for (const [key, val] of Object.entries(patch)) {
+    const field = EDITABLE_FIELDS.find((f) => f.key === key);
+    if (!field) { errors.push(`Campo desconocido: ${key}`); continue; }
+
+    if (field.type === 'select' && !field.options.includes(val)) {
+      errors.push(`${key}: valor inválido "${val}". Permitidos: ${field.options.join(', ')}`);
+      continue;
+    }
+    if (field.type === 'number') {
+      const n = Number(val);
+      if (!Number.isFinite(n)) { errors.push(`${key}: debe ser un número`); continue; }
+      if (field.min != null && n < field.min) { errors.push(`${key}: mínimo ${field.min}`); continue; }
+      if (field.max != null && n > field.max) { errors.push(`${key}: máximo ${field.max}`); continue; }
+    }
+    if (field.type === 'boolean' && typeof val !== 'boolean') {
+      errors.push(`${key}: debe ser true o false`);
+      continue;
+    }
+
+    if (field.key === 'modelMode') applyModelMode(parsed, val);
+    else setDeep(parsed, field.path, field.type === 'number' ? Number(val) : val);
+    applied.push({ key, value: val });
+  }
+  if (errors.length > 0) return { path: p, written: false, applied, errors };
+
+  // Write atomically: serialize → write to .tmp → rename. Backup the
+  // existing file first so the user can recover.
+  const dir = dirname(p);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  if (existsSync(p)) { try { copyFileSync(p, backupPath()); } catch { /* best-effort */ } }
+  const dump = yaml.dump(parsed, { lineWidth: 120 });
+  // mkstemp would be nicer but we want to stay in the same dir for
+  // a guaranteed-atomic rename across the same filesystem.
+  const tmpFile = join(dir, `.kj.config.yml.${process.pid}.${Date.now()}.tmp`);
+  writeFileSync(tmpFile, dump, 'utf8');
+  renameSync(tmpFile, p);
+  return { path: p, written: true, applied, errors: [] };
+}