@karajan-family/code 4.21.0

package/scripts/verify-pack.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/**
+ * Pre-publish tarball smoke gate (KJC-TSK-0553).
+ *
+ * WHY: the test suite runs against the linked workspace, where
+ * `karajan-core` and its deps resolve via symlink — so a broken
+ * PUBLISHED artifact (bundleDependencies dragging in sqlite-vec without
+ * its entry point, KJC-BUG-0082 / 0086) passed CI yet failed on every
+ * clean `npm install`. v3.2.0, v3.3.0 and v3.4.1 all shipped unable to
+ * run even `kj --version`.
+ *
+ * WHAT: pack the real tarball, install it into an isolated tmpdir
+ * (outside the repo, with CLAUDECODE stripped), and assert the binary
+ * actually starts and its native-ish deps resolve. Exit non-zero on any
+ * failure so `prepublishOnly` aborts the publish and CI blocks the PR.
+ *
+ * `npm pack` fires prepack/postpack, NOT prepublishOnly — so invoking
+ * this from prepublishOnly does not recurse.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+const expectedVersion = pkg.version;
+// MIG-A (KJC-TSK-0751): el nombre sale del manifest — el MISMO verify-pack
+// valida el tarball unscoped y el @karajan-family/* del dual-publish.
+const pkgName = pkg.name;
+
+// Subprocess env: strip CLAUDECODE (Claude Code blocks nested non-interactive
+// runs otherwise) and force a non-interactive, quiet npm.
+const { CLAUDECODE: _omit, ...cleanEnv } = process.env;
+const childEnv = { ...cleanEnv, npm_config_yes: "true", CI: "1" };
+
+function run(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, {
+    encoding: "utf8",
+    env: childEnv,
+    stdio: ["ignore", "pipe", "pipe"],
+    ...opts,
+  });
+}
+
+function fail(msg, detail) {
+  console.error(`\n✗ verify-pack: ${msg}`);
+  if (detail) console.error(String(detail).split("\n").slice(0, 20).join("\n"));
+  process.exit(1);
+}
+
+let tgzPath = null;
+let tmpDir = null;
+let gTmp = null;
+let pnpmTmp = null;
+let qsTmp = null;
+try {
+  console.log(`verify-pack: packing ${pkgName}@${expectedVersion}…`);
+  // --json gives us the exact filename without parsing human output.
+  const packOut = run("npm", ["pack", "--json", "--silent"], { cwd: repoRoot });
+  const filename = JSON.parse(packOut)[0]?.filename;
+  if (!filename) fail("npm pack did not report a filename", packOut);
+  // npm --json reports the exact filename (scoped names normalized to
+  // scope-name-x.y.z.tgz); the file lands in cwd under that name.
+  tgzPath = path.join(repoRoot, filename);
+  if (!fs.existsSync(tgzPath)) fail(`packed tarball not found at ${tgzPath}`);
+
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-pack-"));
+  console.log(`verify-pack: installing the tarball into ${tmpDir} (clean, isolated)…`);
+  run("npm", ["install", tgzPath, "--no-audit", "--no-fund", "--silent", "--prefix", tmpDir], {
+    cwd: tmpDir,
+  });
+
+  const binPath = path.join(tmpDir, "node_modules", ".bin", "kj");
+  if (!fs.existsSync(binPath)) fail(`kj binary missing after install: ${binPath}`);
+
+  // 1. kj --version must start AND report the version we just packed.
+  let versionOut;
+  try {
+    versionOut = run(binPath, ["--version"]).trim();
+  } catch (err) {
+    fail("`kj --version` crashed on a clean install", err.stderr || err.message);
+  }
+  if (!versionOut.includes(expectedVersion)) {
+    fail(`kj --version returned "${versionOut}", expected ${expectedVersion}`);
+  }
+  console.log(`verify-pack: kj --version → ${versionOut} ✓`);
+
+  // 1.5 Privacy boundary (KJC-TSK-0706): nothing personal or secret-shaped
+  // ships inside the tarball. Scans the INSTALLED package with the same
+  // engine as the pre-commit gate: denylist + token shapes abort the
+  // publish; generic PII only counts (code trees always carry a few
+  // pattern lookalikes).
+  const { scanPaths, loadPrivacyList } = await import(
+    path.join(repoRoot, "src", "privacy", "scan.js")
+  );
+  const shippedDir = path.join(tmpDir, "node_modules", ...pkgName.split("/"));
+  const pFindings = scanPaths([shippedDir], { list: loadPrivacyList() });
+  const pBlocks = pFindings.filter((f) => f.severity === "block");
+  if (pBlocks.length > 0) {
+    for (const f of pBlocks) console.error(`✗ [${f.type}] ${path.relative(shippedDir, f.source)}:${f.line} → ${f.masked}`);
+    fail(`${pBlocks.length} personal-data/secret hit(s) INSIDE the tarball — this must not publish`);
+  }
+  console.log(`verify-pack: tarball privacy scan ✓ (${pFindings.length} generic warning(s))`);
+
+  // 2. kj --help must exit 0 (exercises the command tree wiring).
+  try {
+    run(binPath, ["--help"]);
+  } catch (err) {
+    fail("`kj --help` failed on a clean install", err.stderr || err.message);
+  }
+  console.log("verify-pack: kj --help ✓");
+
+  // 3. The deps that broke before must resolve in the installed tree.
+  // karajan-core is a registry dep since KJC-BUG-0103 (no bundling), so it
+  // hoists to the consumer's top-level node_modules like everything else.
+  const checks = [
+    path.join(tmpDir, "node_modules", "sqlite-vec", "index.mjs"),
+    path.join(tmpDir, "node_modules", "karajan-core", "src", "vec-store.js"),
+  ];
+  for (const p of checks) {
+    if (!fs.existsSync(p)) fail(`expected resolved path missing in install: ${p}`);
+  }
+  console.log("verify-pack: sqlite-vec + karajan-core resolve ✓");
+
+  // 4. kj-trash (ai-trash safety binary) must ship + link onto PATH and boot
+  // without a module-resolution crash. It was silently absent from the tarball
+  // until KJC-BUG-0089 — every npm user got "kj-trash not found".
+  const trashBin = path.join(tmpDir, "node_modules", ".bin", "kj-trash");
+  if (!fs.existsSync(trashBin)) fail(`kj-trash binary missing after install: ${trashBin}`);
+  const trash = spawnSync(trashBin, ["--help"], { encoding: "utf8", env: childEnv });
+  // The CLI exits 2 on --help (usage); only a real crash (module not found, or
+  // an unexpected non-0/2 exit) is a failure.
+  if (![0, 2].includes(trash.status) || /ERR_MODULE_NOT_FOUND|Cannot find/.test(trash.stderr || "")) {
+    fail("`kj-trash --help` crashed on a clean install", trash.stderr || `exit ${trash.status}`);
+  }
+  console.log("verify-pack: kj-trash ships + boots ✓");
+
+  // 5. GLOBAL install smoke (KJC-BUG-0103). `npm install -g` nests every dep
+  // under karajan-code/node_modules; with bundleDependencies present, npm
+  // treated that whole subtree as "already in the tarball" and skipped
+  // fetching better-sqlite3 & friends — EMPTY dirs whose install scripts then
+  // crashed. Local installs hoist and never hit it, which is exactly why the
+  // check above stayed green for ~15 broken releases. A fresh global install
+  // must succeed and kj must boot.
+  gTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-g-"));
+  console.log(`verify-pack: installing the tarball GLOBALLY into ${gTmp}…`);
+  try {
+    run("npm", ["install", "-g", tgzPath, "--no-audit", "--no-fund", "--silent", "--prefix", gTmp]);
+  } catch (err) {
+    fail("`npm install -g` of the tarball failed (KJC-BUG-0103 class)", err.stderr || err.message);
+  }
+  const gBin = process.platform === "win32"
+    ? path.join(gTmp, "kj.cmd")
+    : path.join(gTmp, "bin", "kj");
+  if (!fs.existsSync(gBin)) fail(`kj binary missing after global install: ${gBin}`);
+  let gVersion;
+  try {
+    gVersion = run(gBin, ["--version"]).trim();
+  } catch (err) {
+    fail("`kj --version` crashed on a fresh GLOBAL install", err.stderr || err.message);
+  }
+  if (!gVersion.includes(expectedVersion)) {
+    fail(`kj --version (global) returned "${gVersion}", expected ${expectedVersion}`);
+  }
+  console.log(`verify-pack: global install + kj --version → ${gVersion} ✓`);
+
+  // 5.5 Quickstart smoke (KJC-TSK-0635) — the landing's Getting Started
+  // sequence against the INSTALLED tarball, no LLM involved. Born from
+  // 2026-07-19: following the docs to the letter caught 3 field bugs
+  // (silent 2.34.0 install, Solomon loop on no-remote repos, retired
+  // gemini CLI) that 6000 unit tests never saw. Aux bootstraps (ollama,
+  // rtk, squeezr, qmd, harden) are skipped — this validates kj's own
+  // init + config on the canonical no-remote scenario, not the network.
+  qsTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-qs-"));
+  console.log(`verify-pack: quickstart smoke (init on a no-remote repo) in ${qsTmp}…`);
+  run("git", ["init", "-q", "-b", "main"], { cwd: qsTmp });
+  // KARAJAN_HOME points at an isolated dir: faithful to a brand-new user
+  // (no pre-existing global config — `--local` without one is rejected by
+  // design, which is exactly what this smoke caught on its first CI run)
+  // AND hermetic (never touches the real ~/.karajan).
+  const qsEnv = { ...childEnv, KARAJAN_HOME: path.join(qsTmp, "karajan-home") };
+  delete qsEnv.CLAUDECODE;
+  const initRes = spawnSync(gBin, ["init", "--no-interactive", "--no-ollama", "--no-rtk", "--no-squeezr", "--no-qmd", "--no-harden"], {
+    encoding: "utf8", cwd: qsTmp, env: qsEnv, timeout: 180000,
+  });
+  if (initRes.status !== 0) {
+    fail("`kj init --no-interactive` failed on a fresh no-remote repo", (initRes.stderr || initRes.stdout || "").slice(-800));
+  }
+  const qsCfgLocal = path.join(qsTmp, ".karajan", "kj.config.yml");
+  const qsCfgGlobal = path.join(qsTmp, "karajan-home", "kj.config.yml");
+  const qsCfg = fs.existsSync(qsCfgLocal) ? qsCfgLocal : qsCfgGlobal;
+  if (!fs.existsSync(qsCfg)) fail(`kj init did not write ${qsCfg}`);
+  if (!/coder:\s*\S+/.test(fs.readFileSync(qsCfg, "utf8"))) {
+    fail("generated kj.config.yml has no coder assignment");
+  }
+  const reportRes = spawnSync(gBin, ["report"], { encoding: "utf8", cwd: qsTmp, env: qsEnv, timeout: 60000 });
+  const reportOut = `${reportRes.stdout || ""}${reportRes.stderr || ""}`;
+  if (reportRes.status !== 0 && !/no session|sin sesi|not found/i.test(reportOut)) {
+    fail("`kj report` crashed on a project with no sessions", reportOut.slice(-400));
+  }
+  console.log("verify-pack: quickstart smoke (init + report, no-remote repo) ✓");
+
+  // 6. pnpm install smoke (KJC-TSK-0580). pnpm's layout differs from npm's
+  // (a symlinked virtual store), so it can break resolution of the bundled
+  // karajan-core the way npm packaging breakage did before (KJC-BUG-0082/0086).
+  // Verify a pnpm install resolves the JS tree and `kj --version` boots — every
+  // release catches a pnpm packaging regression. (pnpm also blocks
+  // better-sqlite3's native build by default, so DB-backed commands need
+  // `pnpm approve-builds`; that's surfaced as a doctor warning, KJC-BUG-0092 —
+  // not a gate failure, since it's inherent to pnpm.) Auto-skips without pnpm.
+  // KJC-BUG-0135: `npm run` leaks npm_config_* into the child env, and pnpm
+  // maps those variables onto its own config — which can re-anchor it to THIS
+  // repo (7-aug incident: the repo's node_modules converted to pnpm layout,
+  // native bindings wiped, and simple-git-hooks' hook overwrote
+  // .karajan/hooks). The smoke runs with a scrubbed env and a pinned --dir,
+  // and the tripwire below turns any host contamination into a loud gate
+  // failure instead of a silent green.
+  const pnpmEnv = Object.fromEntries(Object.entries(childEnv).filter(([k]) => !/^npm_config_/i.test(k)));
+  const HOST_MARKERS = ["pnpm-lock.yaml", "pnpm-workspace.yaml", path.join("node_modules", ".pnpm")];
+  const hostMarkersBefore = new Set(HOST_MARKERS.filter((m) => fs.existsSync(path.join(repoRoot, m))));
+  const hasPnpm = spawnSync("pnpm", ["--version"], { encoding: "utf8", env: pnpmEnv }).status === 0;
+  if (!hasPnpm) {
+    console.log("verify-pack: pnpm not installed — skipping pnpm smoke (npm path covered above) ⚠");
+  } else {
+    pnpmTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-pnpm-"));
+    fs.writeFileSync(
+      path.join(pnpmTmp, "package.json"),
+      JSON.stringify({ name: "kj-verify-pnpm", private: true }),
+    );
+    console.log(`verify-pack: installing the tarball with pnpm into ${pnpmTmp}…`);
+    // pnpm exits non-zero on ERR_PNPM_IGNORED_BUILDS (it skips native build
+    // scripts by default) — expected here, so don't treat the exit as failure.
+    // minimum-release-age=0: modern pnpm quarantines freshly published
+    // versions (supply-chain protection), so right after publishing
+    // karajan-core it silently resolves an OLD one and this smoke fails on
+    // missing subpaths. The gate verifies packaging, not release-age policy.
+    spawnSync(
+      "pnpm",
+      ["add", tgzPath, "--dir", pnpmTmp, "--ignore-workspace", "--store-dir", path.join(pnpmTmp, ".store"), "--config.minimum-release-age=0"],
+      { encoding: "utf8", env: pnpmEnv, cwd: pnpmTmp },
+    );
+    const pnpmBin = path.join(pnpmTmp, "node_modules", ".bin", "kj");
+    if (!fs.existsSync(pnpmBin)) fail(`kj binary missing after pnpm install: ${pnpmBin}`);
+    let pnpmVersion;
+    try {
+      pnpmVersion = run(pnpmBin, ["--version"], { cwd: pnpmTmp }).trim();
+    } catch (err) {
+      fail("`kj --version` crashed under a pnpm install (packaging regression)", err.stderr || err.message);
+    }
+    if (!pnpmVersion.includes(expectedVersion)) {
+      fail(`kj --version under pnpm returned "${pnpmVersion}", expected ${expectedVersion}`);
+    }
+    console.log(`verify-pack: pnpm install + kj --version → ${pnpmVersion} ✓ (DB build needs \`pnpm approve-builds\`)`);
+  }
+  // Tripwire (KJC-BUG-0135): the smoke must NEVER touch the host repo. If a
+  // pnpm artifact appeared at the repo root during this run, the gate fails
+  // naming it — never a green over a contaminated tree.
+  const contaminated = HOST_MARKERS.filter(
+    (m) => !hostMarkersBefore.has(m) && fs.existsSync(path.join(repoRoot, m)),
+  );
+  if (contaminated.length > 0) {
+    fail(
+      `pnpm smoke contaminated the host repo: ${contaminated.join(", ")} appeared at the repo root`,
+      "remove the listed files and run `npm ci` to restore the npm layout; then verify .karajan/hooks with `git status`",
+    );
+  }
+
+  console.log(`\n✓ verify-pack: ${pkgName}@${expectedVersion} installs clean and runs.`);
+} finally {
+  if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });
+  if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  if (gTmp && fs.existsSync(gTmp)) fs.rmSync(gTmp, { recursive: true, force: true });
+  if (pnpmTmp && fs.existsSync(pnpmTmp)) fs.rmSync(pnpmTmp, { recursive: true, force: true });
+  if (qsTmp && fs.existsSync(qsTmp)) fs.rmSync(qsTmp, { recursive: true, force: true });
+}

package/src/activity-log.js

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getSessionRoot } from "./utils/paths.js";
+import { ensureDir } from "./utils/fs.js";
+
+function formatLine(entry) {
+  const ts = entry.timestamp || new Date().toISOString();
+  const lvl = (entry.level || "info").toUpperCase().padEnd(5);
+  const ctx = entry.context
+    ? Object.entries(entry.context)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(" ")
+    : "";
+  const ctxStr = ctx ? ` ${ctx}` : "";
+  return `${ts} [${lvl}]${ctxStr} ${entry.message || ""}`;
+}
+
+export function createActivityLog(sessionId) {
+  const logPath = path.join(getSessionRoot(), sessionId, "activity.log");
+  let buffer = [];
+  let flushing = false;
+
+  async function flush() {
+    if (flushing || buffer.length === 0) return;
+    flushing = true;
+    const lines = buffer.splice(0);
+    try {
+      await ensureDir(path.dirname(logPath));
+      await fs.appendFile(logPath, lines.join("\n") + "\n", "utf8");
+    } catch {
+      // best-effort: I/O errors do not crash the flow
+    }
+    flushing = false;
+    if (buffer.length > 0) flush();
+  }
+
+  return {
+    write(logEntry) {
+      buffer.push(formatLine(logEntry));
+      flush();
+    },
+    writeEvent(progressEvent) {
+      const entry = {
+        timestamp: progressEvent.timestamp,
+        level: progressEvent.status === "fail" ? "error" : "info",
+        context: {
+          iteration: progressEvent.iteration,
+          stage: progressEvent.stage
+        },
+        message: progressEvent.message || progressEvent.type
+      };
+      this.write(entry);
+    },
+    get path() {
+      return logPath;
+    }
+  };
+}

package/src/agents/agy-agent.js

@@ -0,0 +1,62 @@
+import { BaseAgent } from "./base-agent.js";
+import { resolveBin } from "./resolve-bin.js";
+
+/**
+ * Antigravity CLI (`agy`) — KJC-TSK-0729 fase 2b: the ninth built-in agent.
+ * Google's official successor to the retired gemini CLI (dead 2026-06-18),
+ * covered by the user's Google AI Pro/Ultra subscription — the natural
+ * third AI for solomon arbitration, back at last.
+ *
+ * Verified live against agy 1.1.10:
+ *  - `-p <prompt>` runs print mode; `--output-format json` emits ONE JSON
+ *    object: {status: "SUCCESS", response, usage}. Non-SUCCESS status can
+ *    arrive with exit 0, so ok checks BOTH.
+ *  - `--disable-slash-commands` keeps prompt content (diffs can contain
+ *    "/lines") from expanding as slash commands in print mode.
+ *  - Permission prompts are denied in print mode unless
+ *    `--dangerously-skip-permissions` (coder mode only).
+ *  - Auth lives under ~/.gemini/antigravity-cli (device/browser login).
+ */
+export class AgyAgent extends BaseAgent {
+  async runTask(task) {
+    return this._exec(task, this.getRoleModel(task.role || "coder"), ["--dangerously-skip-permissions"]);
+  }
+
+  async reviewTask(task) {
+    return this._exec(
+      { ...task, prompt: `Do NOT use any tools. Answer directly from this prompt only.\n\n${task.prompt}` },
+      this.getRoleModel(task.role || "reviewer"),
+      [],
+    );
+  }
+
+  async _exec(task, model, extraArgs) {
+    const args = ["-p", task.prompt, "--output-format", "json", "--disable-slash-commands", ...extraArgs];
+    if (model) args.push("--model", model);
+    const res = await this.runCommand(resolveBin("agy"), args, {
+      onOutput: task.onOutput,
+      silenceTimeoutMs: task.silenceTimeoutMs,
+      timeout: task.timeoutMs,
+      cwd: task.cwd,
+    });
+    const parsed = extractAgyOutput(res.stdout);
+    const ok = res.exitCode === 0 && parsed?.status === "SUCCESS";
+    return {
+      ok,
+      output: parsed?.response ?? res.stdout,
+      error: ok ? res.stderr : parsed?.error || res.stderr || `agy status: ${parsed?.status || "unparseable"}`,
+      exitCode: res.exitCode,
+    };
+  }
+}
+
+/** Parse agy's single-object JSON print output ({status, response}), null if not JSON. */
+export function extractAgyOutput(stdout) {
+  if (!stdout) return null;
+  try {
+    const obj = JSON.parse(stdout.trim());
+    return typeof obj === "object" && obj !== null ? obj : null;
+  } catch {
+    return null;
+  }
+}

package/src/agents/aider-agent.js

@@ -0,0 +1,78 @@
+import { BaseAgent } from "./base-agent.js";
+import { resolveBin } from "./resolve-bin.js";
+
+/**
+ * Extract token usage from Aider's stdout. Two shapes are supported:
+ *
+ *   1. LiteLLM passthrough — an OpenAI-style JSON `usage` block surfaces
+ *      `prompt_tokens_details.cached_tokens` for prompt-cache hits.
+ *   2. Aider's native footer "Tokens: <sent> sent, <received> received
+ *      [, <cached> cache hit]." (supports comma-separated and `k` suffix).
+ *
+ * Returns `{tokens_in, tokens_out, cached_tokens}` or null when no usage
+ * is found (= unmeasured; callers leave the fields undefined).
+ */
+function extractAiderUsage(text) {
+  if (!text) return null;
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t.startsWith("{")) continue;
+    let obj;
+    try { obj = JSON.parse(t); } catch { continue; }
+    const u = obj?.usage ?? (typeof obj?.prompt_tokens === "number" ? obj : null);
+    if (!u || typeof u.prompt_tokens !== "number") continue;
+    return {
+      tokens_in: u.prompt_tokens,
+      tokens_out: u.completion_tokens ?? 0,
+      cached_tokens: u.prompt_tokens_details?.cached_tokens ?? 0
+    };
+  }
+  const m = text.match(/Tokens:\s*([\d.,]+k?)\s*sent,\s*([\d.,]+k?)\s*received(?:,\s*([\d.,]+k?)\s*cache\s*hit)?/i);
+  if (!m) return null;
+  const parse = (s) => {
+    const c = s.replaceAll(",", "");
+    return c.toLowerCase().endsWith("k")
+      ? Math.round(parseFloat(c.slice(0, -1)) * 1000)
+      : Number(c);
+  };
+  const sent = parse(m[1]);
+  const recv = parse(m[2]);
+  if (!Number.isFinite(sent) || !Number.isFinite(recv)) return null;
+  return { tokens_in: sent, tokens_out: recv, cached_tokens: m[3] ? parse(m[3]) : 0 };
+}
+
+export class AiderAgent extends BaseAgent {
+  async runTask(task) {
+    const role = task.role || "coder";
+    const model = this.getRoleModel(role);
+    const result = await this._exec(task, model);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Aider model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null);
+    }
+    return result;
+  }
+
+  async reviewTask(task) {
+    const role = task.role || "reviewer";
+    const model = this.getRoleModel(role);
+    const result = await this._exec(task, model);
+    if (!result.ok && model && this.isModelNotSupportedError(result)) {
+      this.logger?.warn(`Aider model "${model}" not supported — retrying with agent default`);
+      return this._exec(task, null);
+    }
+    return result;
+  }
+
+  async _exec(task, model) {
+    const args = ["--yes", "--message", task.prompt];
+    if (model) args.push("--model", model);
+    const res = await this.runCommand(resolveBin("aider"), args, {
+      onOutput: task.onOutput,
+      silenceTimeoutMs: task.silenceTimeoutMs,
+      timeout: task.timeoutMs
+    });
+    const usage = extractAiderUsage(res.stdout) ?? extractAiderUsage(res.stderr);
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode, ...usage };
+  }
+}

package/src/agents/availability.js

@@ -0,0 +1,52 @@
+import { runCommand } from "../utils/process.js";
+import { resolveBin } from "./resolve-bin.js";
+import { getAgentMeta } from "./index.js";
+
+export async function assertAgentsAvailable(agentNames = []) {
+  const unique = [...new Set(agentNames.filter(Boolean))];
+
+  // PR-J (audit quick win): probe every agent CLI in parallel via
+  // Promise.all instead of awaiting in a for-of loop. Each probe is
+  // an independent fork+exec with no shared state, so serialising
+  // them was wasted preflight latency: O(n) shell-outs becomes O(1)
+  // (max of all probes). On 4 agents at ~80ms each this drops the
+  // wait from ~320ms to ~80ms.
+  const probes = await Promise.all(
+    unique.map(async (name) => {
+      const meta = getAgentMeta(name);
+      if (!meta?.bin) return null;
+      const res = await runCommand(resolveBin(meta.bin), ["--version"]);
+      return res.exitCode !== 0 ? { name, ...meta } : null;
+    })
+  );
+  const missing = probes.filter(Boolean);
+
+  if (missing.length === 0) return;
+
+  const lines = ["Missing required AI CLIs for this command:"];
+  for (const m of missing) {
+    lines.push(`- ${m.name}: command '${m.bin}' not found`, `  Install: ${m.installUrl}`);
+  }
+  throw new Error(lines.join("\n"));
+}
+
+/**
+ * Non-throwing counterpart to assertAgentsAvailable: probe each agent CLI in
+ * parallel and return the subset whose `--version` succeeds. Used by the
+ * audit fallback (KJC-BUG-0094) to skip uninstalled providers instead of
+ * aborting the whole command when any one is missing.
+ * @param {string[]} agentNames
+ * @returns {Promise<string[]>}
+ */
+export async function filterAvailableAgents(agentNames = []) {
+  const unique = [...new Set(agentNames.filter(Boolean))];
+  const probes = await Promise.all(
+    unique.map(async (name) => {
+      const meta = getAgentMeta(name);
+      if (!meta?.bin) return null;
+      const res = await runCommand(resolveBin(meta.bin), ["--version"]);
+      return res.exitCode === 0 ? name : null;
+    })
+  );
+  return probes.filter(Boolean);
+}

package/src/agents/base-agent.js

@@ -0,0 +1,134 @@
+/**
+ * Base class for provider-specific agent adapters (claude, codex, gemini, ...).
+ * Every concrete agent must implement runTask() and may override reviewTask().
+ *
+ * @typedef {import("../types/config.js").KarajanConfig} KarajanConfig
+ * @typedef {import("../types/stage.js").Logger} Logger
+ * @typedef {import("../types/agent.js").AgentResult} AgentResult
+ * @typedef {import("../infrastructure/environment.js").Environment} Environment
+ * @typedef {import("../infrastructure/command-runner.js").CommandRunResult} CommandRunResult
+ * @typedef {import("../infrastructure/command-runner.js").CommandRunOptions} CommandRunOptions
+ */
+
+import { defaultEnvironment } from "../infrastructure/environment.js";
+import { buildAgentEnv } from "../utils/role-env.js";
+import { isModelCompatible } from "../config/role-resolver.js";
+
+const MODEL_NOT_SUPPORTED_PATTERNS = [
+  /model.{0,30}is not supported/i,
+  /model.{0,30}not available/i,
+  /model.{0,30}does not exist/i,
+  /unsupported model/i,
+  /invalid model/i,
+  /model_not_found/i
+];
+
+export class BaseAgent {
+  /**
+   * @param {string} name                    - agent slug (claude|codex|gemini|aider|opencode)
+   * @param {KarajanConfig} config
+   * @param {Logger} logger
+   * @param {Environment} [environment]      - DI-friendly fs + runner bundle. Defaults
+   *                                           to the native filesystem and execa-based
+   *                                           command runner. Tests pass a mock env to
+   *                                           unit-test agent paths without spawning
+   *                                           real processes.
+   */
+  constructor(name, config, logger, environment = defaultEnvironment) {
+    this.name = name;
+    this.config = config;
+    this.logger = logger;
+    this.environment = environment;
+  }
+
+  /**
+   * Run a shell command through the injected CommandRunner. Subclasses should
+   * call this instead of importing runCommand directly so tests can swap in
+   * MockCommandRunner.
+   * @param {string} command
+   * @param {string[]} [args]
+   * @param {CommandRunOptions} [options]
+   * @returns {Promise<CommandRunResult>}
+   */
+  async runCommand(command, args = [], options = {}) {
+    // KJC-TSK-0693: the subprocess gets an env allowlist, never the user's
+    // whole environment. security.env_allowlist:false opts out.
+    if (this.config?.security?.env_allowlist !== false) {
+      // Solomon-arbitrated contract (KJC-TSK-0693): an explicit env WITH a
+      // PATH is a COMPLETE child env (agents build those from process.env and
+      // deliberately strip vars — cleanExecaOpts drops CLAUDECODE, qwen
+      // unsets gemini's trust var) and is filtered AS GIVEN. An env WITHOUT
+      // a PATH is a partial overlay and merges over the inherited env first,
+      // so an overlay caller can never cost the child PATH/HOME.
+      const complete = options.env && ("PATH" in options.env || "Path" in options.env);
+      const base = complete ? options.env : { ...process.env, ...options.env };
+      options = {
+        ...options,
+        env: buildAgentEnv(base, {
+          agent: this.name,
+          passthrough: this.config?.security?.env_passthrough || [],
+        }),
+      };
+    }
+    return this.environment.runner.run(command, args, options);
+  }
+
+  /**
+   * Execute a coding/agentic task. Subclasses MUST override.
+   * @param {string|Object} _task
+   * @returns {Promise<AgentResult>}
+   */
+  async runTask(_task) {
+    throw new Error("runTask not implemented");
+  }
+
+  /**
+   * Execute a review task. Subclasses MAY override for different behaviour.
+   * @param {string|Object} _task
+   * @returns {Promise<AgentResult>}
+   */
+  async reviewTask(_task) {
+    throw new Error("reviewTask not implemented");
+  }
+
+  /**
+   * @param {string} role
+   * @returns {string|null}
+   */
+  getRoleModel(role) {
+    const roleModel =
+      this.config?.roles?.[role]?.model ||
+      (role === "reviewer" ? this.config?.reviewer_options?.model : this.config?.coder_options?.model) ||
+    null;
+    // KJC-BUG-0144 (campo, issue #1465): un default por-rol (start: haiku)
+    // puede caer sobre un provider de OTRA familia (agy, codex...) — el
+    // modelo se descarta con aviso y el agente usa su propio default,
+    // nunca se le pasa un --model ajeno.
+    if (roleModel && !isModelCompatible(this.name, roleModel)) {
+      this.logger?.warn?.(`model "${roleModel}" belongs to another family — dropping it for ${this.name} (role ${role})`);
+      return null;
+    }
+    return roleModel;
+  }
+
+  /**
+   * @param {string} role
+   * @returns {boolean}
+   */
+  isAutoApproveEnabled(role) {
+    if (role === "reviewer") return false;
+    return Boolean(this.config?.coder_options?.auto_approve);
+  }
+
+  /**
+   * Heuristic: does the agent's error look like "model not supported"?
+   * Used by the retry/fallback path.
+   * @param {Partial<AgentResult>} result
+   * @returns {boolean}
+   */
+  isModelNotSupportedError(result) {
+    const text = [result?.error, result?.output, result?.stderr, result?.stdout]
+      .filter(Boolean).join("\n");
+    return MODEL_NOT_SUPPORTED_PATTERNS.some(re => re.test(text));
+  }
+}