karajan-code 4.12.0 → 4.14.0

package/README.md

@@ -22,7 +22,7 @@
 
 ---
 
-Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code. **Karajan governs how it happens**: it installs a method your agent follows on every task, and enforces it with git gates that make a false green structurally impossible.
+Your AI agent (Claude Code, Codex, Copilot, Antigravity, Cursor…) writes the code. **Karajan governs how it happens**: it installs a method your agent follows on every task, and enforces it with git gates that make a false green structurally impossible.
 
 - **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses. The install wires it as a native MCP tool (`kj_rag_query`) so querying the index is the agent's cheapest path. Works out of the box: local Ollama, or the built-in ONNX embedder when nothing can be installed; cloud embedders require an explicit sensitivity declaration and PII-redact every chunk. A distilled engineering canon rides along: `kj rag query --library` serves pattern cards (when it applies, when it does NOT, the canonical citation) so plans name a greenfield alternative instead of following the legacy line by inertia.
 - **Card first, on YOUR board** — every piece of work is tracked before it starts: kj's HU Board (`kj hu add|move|list`), the Planning Game, or the board the project already uses (Linear, Trello, Jira, GitHub Issues) via your agent's own MCP/tools. Declared, verified at install, never optional — Karajan does not run without a board. ADRs live in git (`kj adr add|list`).
@@ -33,6 +33,8 @@ Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code. **Kar
 - **Least privilege for agents** — spawned agent subprocesses receive an env allowlist (their own CLI's auth, never your cloud keys or registry tokens), and `kj check` inventories every MCP the project can reach, flagging what appeared since the last check. Sensitive-surface tasks self-invoke `kj audit --security` — a zero-token pass (prompt-injection over the agent-context files + OSV + Semgrep + Sonar) — and remediate before review.
 - **Nothing personal ships** — every outbound boundary audits before it leaves the machine: the pre-commit rejects a staged diff carrying your denylisted personal data, hardcoded platform tokens (`ghp_`, `sk-`, `AKIA`…) block outright, `verify-pack`-style tarball scans guard the publish, and `kj privacy scan <dir>` audits any build output. Your denylist lives in `~/.karajan/privacy.yml` — the install asks and writes it for you.
 - **Installing IS activating** — `kj env install` performs the enforcement itself (git hooks, verdict gate, tool gate) instead of trusting the agent to run setup steps, and ends by printing the method into the very conversation that installed it. A commit outside the method is rejected, not narrated.
+- **The turn cannot end red — the Sentinel** — a deterministic supervisor (zero LLM) wired into the harness's synchronous hooks records the method state of the session as tools run, and a Stop hook blocks the agent from ending its turn while method violations are open. The program rules, the agent thinks. See [guarantee levels](#guarantee-levels-governed-vs-supervised).
+- **The review panel never runs dry** — nine built-in agents (Claude Code, Codex, GitHub Copilot, Antigravity `agy` — the gemini successor —, Kimi Code, Qwen, OpenCode, Aider, Gemini legacy), and when the configured reviewer exhausts its quota, `kj review` switches to an authenticated candidate with a LOUD notice — or hands you the menu of candidates with their tier (free / subscription / local) and the exact login command. Never a silent failure, never the brain reviewing itself.
 
 This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
 
@@ -67,6 +69,12 @@ Requires git and at least one AI agent CLI — two enables cross-AI review; thre
 
 Full method: [Work with your agent](https://karajancode.com/docs/v4/working-with-your-agent/) · [The gates](https://karajancode.com/docs/v4/gates/) · [Command reference](https://karajancode.com/docs/v4/commands/).
 
+## Guarantee levels: governed vs supervised
+
+Karajan **governs** any agent with git gates — the false green is structurally impossible no matter who writes, because the gates live in the repository, not in the agent's goodwill. On top of that, the **Karajan Sentinel** adds **supervision inside the turn**: `kj harden` wires deterministic hooks into the harness — one records the method state of the session as tools run (sources edited vs tests touched, escapes used), and a Stop hook blocks the agent from ending its turn while violations are open: sources edited on the base branch, a branch without a card, code without a single test touched. Every block states the exact violation and its remediation; `kj sentinel status` shows what the supervisor sees. It fails open — and says so — rather than ever hanging a session, and every `KJ_ALLOW_*` escape is recorded.
+
+Synchronous blocking hooks exist today only in Claude Code. That makes the supported setup explicit: **to guarantee a harness that controls the LLM, use Claude Code as the host** — Claude writes, Codex reviews (a review subprocess needs no hooks), and a third CLI arbitrates when available. On any other host Karajan still governs at the full git-gate level and tells you which level is active — it never pretends a supervision it cannot enforce.
+
 ## Headless mode
 
 The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. Agents and CI pass `--non-interactive` (or `KJ_NON_INTERACTIVE=1`): safe gates auto-answer, FAIL findings stop the run with a real exit code. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).

package/docs/README.es.md

@@ -14,7 +14,7 @@
 
 ---
 
-Tu agente de IA (Claude Code, Codex, Gemini CLI, Cursor…) escribe el código. **Karajan gobierna cómo ocurre**: instala un método que tu agente sigue en cada tarea y lo hace cumplir con gates de git que hacen el falso verde estructuralmente imposible.
+Tu agente de IA (Claude Code, Codex, Copilot, Antigravity, Cursor…) escribe el código. **Karajan gobierna cómo ocurre**: instala un método que tu agente sigue en cada tarea y lo hace cumplir con gates de git que hacen el falso verde estructuralmente imposible.
 
 - **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina. La instalación lo cablea como herramienta MCP nativa (`kj_rag_query`), de modo que consultar el índice sea el camino más barato del agente. Funciona de serie: Ollama local, o el embedder ONNX integrado cuando no se puede instalar nada; los embedders cloud exigen declarar la sensibilidad y redactan PII de cada chunk. Y viaja con un canon de ingeniería destilado: `kj rag query --library` sirve fichas de patrón (cuándo aplica, cuándo NO, la cita canónica) para que los planes nombren una alternativa greenfield en vez de seguir la línea del legacy por inercia.
 - **Card primero, en TU board** — todo trabajo se registra antes de empezar: el HU Board de kj (`kj hu add|move|list`), el Planning Game, o el board que el proyecto ya use (Linear, Trello, Jira, GitHub Issues) vía los MCP/tools de tu agente. Declarado, verificado en la instalación, jamás opcional — Karajan no funciona sin board. Los ADRs viven en git (`kj adr add|list`).
@@ -25,6 +25,8 @@ Tu agente de IA (Claude Code, Codex, Gemini CLI, Cursor…) escribe el código.
 - **Mínimo privilegio para agentes** — los subprocesos de agente reciben un allowlist de entorno (la auth de su propio CLI, jamás tus claves cloud ni tokens de registro), y `kj check` inventaría cada MCP alcanzable del proyecto marcando lo aparecido desde el último check. Las tareas con superficie sensible se auto-invocan `kj audit --security` — pasada de cero tokens (prompt-injection sobre los ficheros de contexto del agente + OSV + Semgrep + Sonar) — y remedian antes del review.
 - **Nada personal se publica** — cada boundary de salida se audita antes de dejar la máquina: el pre-commit rechaza un diff con tus datos vetados, los tokens de plataforma hardcodeados (`ghp_`, `sk-`, `AKIA`…) bloquean directamente, el scan del tarball guarda el publish, y `kj privacy scan <dir>` audita cualquier build. Tu denylist vive en `~/.karajan/privacy.yml` — la instalación pregunta y la escribe por ti.
 - **Instalar ES activar** — `kj env install` ejecuta él mismo el enforcement (hooks de git, gate de veredicto, tool gate) en vez de confiar en que el agente corra pasos de setup, y termina imprimiendo el método en la propia conversación que instaló. Un commit fuera del método se rechaza, no se narra.
+- **El turno no puede terminar en rojo — el Sentinel** — un supervisor determinista (cero LLM) cableado a los hooks síncronos del harness registra el estado del método de la sesión según corren las herramientas, y un hook Stop bloquea que el agente termine su turno mientras haya violaciones abiertas. El programa manda, el agente piensa. Ver [niveles de garantía](#niveles-de-garantía-gobernado-vs-supervisado).
+- **El panel de revisión nunca se seca** — nueve agentes integrados (Claude Code, Codex, GitHub Copilot, Antigravity `agy` — el sucesor de gemini —, Kimi Code, Qwen, OpenCode, Aider, Gemini legacy), y cuando al reviewer configurado se le agota la cuota, `kj review` cambia a un candidato autenticado AVISANDO en alto — o te entrega el menú de candidatos con su tier (gratis / suscripción / local) y el comando de login exacto. Jamás un fallo mudo, jamás el brain revisándose a sí mismo.
 
 Este repo corre bajo su propio entorno: cada commit de karajan-code lleva un veredicto de IA cruzada.
 
@@ -59,6 +61,12 @@ Requiere git y al menos un CLI de agente de IA — con dos hay revisión cruzada
 
 Método completo: [Trabaja con tu agente](https://karajancode.com/docs/es/v4/working-with-your-agent/) · [Los gates](https://karajancode.com/docs/es/v4/gates/) · [Referencia de comandos](https://karajancode.com/docs/es/v4/commands/).
 
+## Niveles de garantía: gobernado vs supervisado
+
+Karajan **gobierna** a cualquier agente con gates de git — el falso verde es estructuralmente imposible escriba quien escriba, porque los gates viven en el repositorio, no en la buena voluntad del agente. Encima de eso, el **Karajan Sentinel** añade **supervisión dentro del turno**: `kj harden` cablea hooks deterministas al harness — uno registra el estado del método de la sesión según corren las herramientas (fuentes editadas vs tests tocados, escapes usados), y un hook Stop bloquea que el agente termine su turno mientras haya violaciones abiertas: fuentes editadas en la rama base, rama sin card, código sin tocar un solo test. Cada bloqueo dice la violación exacta y su remediación; `kj sentinel status` muestra lo que ve el supervisor. Ante cualquier duda falla en abierto — y lo dice — antes que colgar una sesión, y cada escape `KJ_ALLOW_*` queda registrado.
+
+Los hooks síncronos con capacidad de bloqueo hoy solo existen en Claude Code. Eso hace explícito el montaje soportado: **para garantizar un harness que controle al LLM, usa Claude Code como anfitrión** — Claude escribe, Codex revisa (un subproceso de revisión no necesita hooks), y un tercer CLI arbitra cuando está disponible. Con cualquier otro anfitrión Karajan sigue gobernando al nivel completo de gates de git y te dice qué nivel está activo — jamás finge una supervisión que no puede imponer.
+
 ## Modo headless
 
 El pipeline multiagente clásico sigue vivo para CI y automatización: `kj run "<tarea>"` orquesta roles coder/reviewer/tester en subprocesos sin humano delante, con los mismos gates. Agentes y CI pasan `--non-interactive` (o `KJ_NON_INTERACTIVE=1`): los gates seguros se auto-responden y los findings FAIL paran el run con exit code de verdad. `kj advanced` lista la superficie completa. [Doc del modo headless](https://karajancode.com/docs/es/v4/headless/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -76,8 +76,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
+    "lint": "eslint src/ packages/",
+    "lint:fix": "eslint src/ packages/ --fix",
     "lint:syntax": "((command -v rg >/dev/null 2>&1 && rg --files src tests | rg '\\.js$') || find src tests -type f -name '*.js') | while IFS= read -r f; do node --check \"$f\"; done",
     "format:check": "prettier --check .",
     "format:fix": "prettier --write .",

package/packages/ai-trash/src/cli.js

@@ -113,7 +113,9 @@ async function cmdPurge(root, id, out, err) {
 async function cmdEmpty(root, flags, out) {
   await ensureRoot(root);
   const m = await loadManifest(root);
-  let dropped = [];
+  // Assigned in every branch below (the trailing else covers the default),
+  // so an initializer would never be read (no-useless-assignment).
+  let dropped;
   if (flags["older-than-days"]) {
     const days = Number(flags["older-than-days"]);
     if (!Number.isFinite(days) || days < 0) throw new Error("--older-than-days must be >= 0");

package/packages/hu-board/public/utils/formatters.js

@@ -117,7 +117,7 @@ function humaniseProjectName(id) {
   if (!id || typeof id !== 'string') return id || '';
   const tail = id.split(/[/_]/).filter(Boolean).pop() || id;
   const words = tail
-    .split(/[\s\-]+/)
+    .split(/[\s-]+/)
     .map((w) => w.replace(/[^\p{L}\p{N}]/gu, ''))
     .filter((w) => w.length > 0);
   if (words.length === 0) return id;

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

@@ -23,7 +23,6 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { homedir } from 'node:os';
 import {
   getDb,
   getKjHome,

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

@@ -18,7 +18,6 @@
 
 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";

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

@@ -30,7 +30,6 @@
 
 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';
 
@@ -448,7 +447,7 @@ export function readConfig({ scope = 'global' } = {}) {
       parsed = yaml.load(readFileSync(p, 'utf8'), { json: true }) || {};
       exists = true;
     } catch (err) {
-      throw new Error(`No se pudo parsear ${p}: ${err.message}`);
+      throw new Error(`No se pudo parsear ${p}: ${err.message}`, { cause: err });
     }
   }
   const fields = EDITABLE_FIELDS.map((f) => {

package/packages/hu-board/src/ephemeral-cleaner.js

@@ -150,8 +150,6 @@ export function cleanupEphemeralProjects({
   const candidates = findEphemeralProjects(allProjects, { ...opts, now: now() });
   if (candidates.length === 0) return [];
 
-  const countStories = db.prepare("SELECT COUNT(*) AS n FROM stories WHERE project_id = ?");
-  const countSessions = db.prepare("SELECT COUNT(*) AS n FROM sessions WHERE project_id = ?");
   const delStories = db.prepare("DELETE FROM stories WHERE project_id = ?");
   const delSessions = db.prepare("DELETE FROM sessions WHERE project_id = ?");
   const delProject = db.prepare("DELETE FROM projects WHERE id = ?");

package/packages/hu-board/src/plan-mutations.js

@@ -16,7 +16,6 @@
  */
 import { readFileSync, existsSync, readdirSync, mkdirSync, openSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
 import { writeJsonAtomicSync } from 'karajan-core/atomic-write';
 import { spawn } from 'node:child_process';
 import { trackRun, untrack } from './run-tracker.js';

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

@@ -28,7 +28,7 @@
  */
 
 import { execSync } from 'node:child_process';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { getHuBoardPlansDirs } from './db.js';
 

package/packages/hu-board/src/routes/api.js

@@ -21,7 +21,6 @@ export async function readPlanCached(p) {
   planFileCache.set(p, { mtimeMs, plan });
   return plan;
 }
-import os from 'node:os';
 import path from 'node:path';
 import { spawn as spawnChild } from 'node:child_process';
 import {
@@ -36,7 +35,6 @@ import {
   getKjHome,
   getHuBoardRunsDir,
   getHuBoardPlansDir,
-  getHuBoardLegacyPlansDir,
   getHuBoardPlansDirs,
   getStoryRow,
   listPlanIdsForProject,
@@ -93,19 +91,6 @@ function huStoriesDir() {
   return path.join(getKjHome(), 'hu-stories');
 }
 
-/**
- * Best-effort removal of the hu-stories/<id>/ directory.
- */
-async function removeBatchDir(batchId) {
-  try {
-    const dir = path.join(huStoriesDir(), batchId);
-    await fsp.rm(dir, { recursive: true, force: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * GET /api/dashboard - Global dashboard statistics.
  */

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

@@ -4,7 +4,6 @@ import rateLimit from 'express-rate-limit';
 import { join, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { writeFileSync, rmSync, mkdirSync, realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { initDb, closeDb } from './db.js';
 import { fullScan, startWatcher } from './sync.js';
 import apiRoutes from './routes/api.js';

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

@@ -1,5 +1,5 @@
 import { watch } from 'chokidar';
-import { readFileSync, readdirSync, existsSync, statSync, rmSync } from 'node:fs';
+import { readFileSync, readdirSync, existsSync, rmSync } from 'node:fs';
 import { dirname, join, basename } from 'node:path';
 import { homedir } from 'node:os';
 import {

package/packages/hu-board/src/token-store.js

@@ -12,7 +12,6 @@
 
 import { randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync, chmodSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 const TOKEN_BYTES = 32;

package/packages/hu-board/src/zombie-reaper.js

@@ -45,7 +45,6 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 
 const DEFAULT_CODING_HOURS = 6;
 const DEFAULT_PAUSED_HOURS = 24;

package/src/agents/agy-agent.js

@@ -0,0 +1,61 @@
+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,
+    });
+    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/index.js

@@ -5,6 +5,8 @@ import { AiderAgent } from "./aider-agent.js";
 import { OpenCodeAgent } from "./opencode-agent.js";
 import { QwenAgent } from "./qwen-agent.js";
 import { CopilotAgent } from "./copilot-agent.js";
+import { KimiAgent } from "./kimi-agent.js";
+import { AgyAgent } from "./agy-agent.js";
 
 const agentRegistry = new Map();
 
@@ -53,3 +55,5 @@ registerAgent("aider", AiderAgent, { bin: "aider", installUrl: "https://aider.ch
 registerAgent("opencode", OpenCodeAgent, { bin: "opencode", installUrl: "https://opencode.ai" });
 registerAgent("qwen", QwenAgent, { bin: "qwen", installUrl: "https://github.com/QwenLM/qwen-code" });
 registerAgent("copilot", CopilotAgent, { bin: "copilot", installUrl: "https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli" });
+registerAgent("kimi", KimiAgent, { bin: "kimi", installUrl: "https://github.com/MoonshotAI/kimi-code" });
+registerAgent("agy", AgyAgent, { bin: "agy", installUrl: "https://antigravity.google" });

package/src/agents/kimi-agent.js

@@ -0,0 +1,44 @@
+import { BaseAgent } from "./base-agent.js";
+import { resolveBin } from "./resolve-bin.js";
+
+/**
+ * Kimi Code (Moonshot, binary `kimi`) — KJC-TSK-0729 fase 2: the eighth
+ * built-in agent and the free-tier reserve of the reviewer/solomon panel.
+ *
+ * Verified live against kimi-code 0.27.0:
+ *  - `-p <prompt>` runs one prompt non-interactively and prints the
+ *    response (text output by default) — the prompt travels as an argument,
+ *    same E2BIG caveat as claude/copilot (KJC-BUG-0121) for huge diffs.
+ *  - `-m <model>` picks a model alias; `-y` auto-approves actions.
+ *  - Auth is the device-code login (`kimi login`), no env keys involved;
+ *    "No model configured" on a logged machine means the login did not
+ *    populate the managed provider (re-run `kimi login`).
+ */
+export class KimiAgent extends BaseAgent {
+  async runTask(task) {
+    // Coder mode IS an agentic run: file edits and shell need approval.
+    return this._exec(task, this.getRoleModel(task.role || "coder"), ["-y"]);
+  }
+
+  async reviewTask(task) {
+    // Review/arbitration answers from the prompt alone — no auto-approval,
+    // and an explicit no-tools instruction so a headless run never stalls
+    // waiting for a permission prompt nobody can answer.
+    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, ...extraArgs];
+    if (model) args.push("-m", model);
+    const res = await this.runCommand(resolveBin("kimi"), args, {
+      onOutput: task.onOutput,
+      silenceTimeoutMs: task.silenceTimeoutMs,
+      timeout: task.timeoutMs,
+    });
+    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+  }
+}

package/src/checks/ai-surface.js

@@ -50,8 +50,11 @@ export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir
  * Diff the current surface against the last-seen snapshot and persist the
  * new state. First run records the baseline silently.
  */
-export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), statePath = path.join(os.homedir(), ".karajan", "ai-surface.json") } = {}) {
-  const surface = collectAiSurface({ projectDir, home });
+export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), statePath = path.join(os.homedir(), ".karajan", "ai-surface.json"), extraSurface = [] } = {}) {
+  // KJC-TSK-0728: extraSurface carries entries the (async) caller collected
+  // outside config files — e.g. observed agent CLIs as "grok (cli)" — so
+  // they ride the same snapshot and the same "NEW since last check" drift.
+  const surface = [...new Set([...collectAiSurface({ projectDir, home }), ...extraSurface])].sort();
   let state = {};
   try { state = JSON.parse(readFileSync(statePath, "utf8")); } catch { /* first run or corrupt → baseline */ }
   const prev = Array.isArray(state[projectDir]) ? state[projectDir] : null;

package/src/checks/binaries.js

@@ -12,7 +12,7 @@
  * the install command and can offer to run it).
  */
 
-import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
+import { checkBinary, KNOWN_AGENTS, detectObservedAgents } from "../utils/agent-detect.js";
 import { runCommand } from "../utils/process.js";
 import { withDocLink } from "../utils/doc-links.js";
 import { getInstallHint, appliesToStack } from "../utils/install-hints.js";
@@ -38,6 +38,33 @@ function createAgentCheck(agent) {
   };
 }
 
+/**
+ * KJC-TSK-0728 — ONE aggregate line for the observation census (agent CLIs
+ * kj sees but does not drive). Only FOUND CLIs are listed; the missing ones
+ * make no noise, and the check never fails. `detector` is injectable for
+ * tests.
+ */
+export function createObservedAgentsCheck({ detector = detectObservedAgents } = {}) {
+  return {
+    name: "agents:observed",
+    label: "Agent CLIs observed (not driven)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      let found = [];
+      try {
+        found = (await detector()).filter((a) => a.available);
+      } catch { /* census is best-effort */ }
+      return {
+        ok: true,
+        severity: "info",
+        detail: found.length
+          ? found.map((a) => `${a.name} (${(a.version || "").split(" ").at(-1) || "?"})`).join(", ")
+          : "none detected",
+      };
+    },
+  };
+}
+
 /**
  * Check the presence of a core binary (node, npm, git).
  */
@@ -165,6 +192,7 @@ export function getBinaryChecks() {
   for (const agent of KNOWN_AGENTS) {
     checks.push(createAgentCheck(agent));
   }
+  checks.push(createObservedAgentsCheck());
   for (const bin of ["node", "npm", "git"]) {
     checks.push(createCoreBinaryCheck(bin));
   }

package/src/cli/advanced-commands.js

@@ -31,7 +31,7 @@ export const ADVANCED_GROUPS = [
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release"] },
-  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
 ];

package/src/cli/register-meta.js

@@ -28,6 +28,10 @@ import { worktreeCommand } from "../commands/worktree.js";
 import { addAdr, listAdrs } from "../environment/adr.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
 import { withConfig } from "./_shared.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { verifySentinelScripts, resolveSentinelRoot } from "../harden/sentinel-hooks.js";
 
 /**
  * Register the "meta" / single-role / housekeeping commands: pre-pipeline
@@ -280,6 +284,29 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0713 — the Sentinel: the method state the harness hooks record.
+  const sentinel = program.command("sentinel").description("Deterministic method supervisor wired into the harness hooks (Claude Code)");
+  sentinel.command("status")
+    .description("Print the per-session method facts (sources/tests edited, escapes used) and any open violation the Stop gate would block on")
+    .action(() => {
+      const script = join(resolveSentinelRoot(), ".karajan", "harness", "stop.mjs");
+      if (!existsSync(script)) {
+        console.log("sentinel: not installed in this project — run `kj harden` (standard profile or higher)");
+        process.exitCode = 1;
+        return;
+      }
+      process.exitCode = spawnSync("node", [script, "--status"], { stdio: "inherit" }).status ?? 0;
+    });
+  sentinel.command("verify")
+    .description("Verify the harness scripts match this kj install — the root of trust is the installed package, not the project tree; exit 1 lists what was modified")
+    .option("--json", "Machine-readable result")
+    .action((flags) => {
+      const res = verifySentinelScripts();
+      if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+      else console.log(res.ok ? "sentinel verify: scripts intactos" : `sentinel verify: modificados fuera de kj harden: ${res.mismatched.join(", ")} — restaura con kj harden`);
+      process.exitCode = res.ok ? 0 : 1;
+    });
+
   // KJC-TSK-0704 — the outbound privacy boundary: audit before anything ships.
   const privacy = program.command("privacy").description("Personal-data (PII) auditing of outbound boundaries: staged diffs, build outputs, docs trees");
   privacy.command("scan [paths...]")

package/src/commands/check.js

@@ -7,6 +7,7 @@
 import { checkHarden } from "../harden/check.js";
 import { collectMethodStats, formatMethodStats } from "../checks/method.js";
 import { checkAiSurface, formatAiSurface } from "../checks/ai-surface.js";
+import { detectObservedAgents } from "../utils/agent-detect.js";
 
 export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
   const result = await checkHarden({ projectDir, profile });
@@ -14,8 +15,15 @@ export async function checkCommand({ projectDir = process.cwd(), profile = "stan
   // rides along in check output but never affects the exit code.
   const method = await collectMethodStats({ projectDir }).catch(() => null);
   // KJC-TSK-0694: same deal for the MCP inventory — a nudge, never a gate.
+  // KJC-TSK-0728: observed agent CLIs ride the same snapshot as "(cli)"
+  // entries, so a newly-appeared agent binary trips the same drift question.
   let aiSurface = null;
-  try { aiSurface = checkAiSurface({ projectDir }); } catch { /* inventory is best-effort */ }
+  try {
+    const clis = (await detectObservedAgents().catch(() => []))
+      .filter((a) => a.available)
+      .map((a) => `${a.name} (cli)`);
+    aiSurface = checkAiSurface({ projectDir, extraSurface: clis });
+  } catch { /* inventory is best-effort */ }
 
   if (json) {
     logger.info?.(JSON.stringify({ ...result, method, aiSurface }));

package/src/commands/harden.js

@@ -19,6 +19,7 @@ import { installGuidelines } from "../harden/guidelines-engine.js";
 import { commandsForLanguage } from "../harden/hook-commands.js";
 import { installHooks } from "../harden/harden-engine.js";
 import { installHarnessHooks } from "../harden/harness-hooks.js";
+import { installSentinelHooks } from "../harden/sentinel-hooks.js";
 import { detectStackRoots } from "../harden/stack-roots.js";
 import { installWorkflows } from "../harden/workflow-engine.js";
 import { detectTestFramework } from "../utils/project-detect.js";
@@ -146,6 +147,10 @@ export async function hardenCommand({
     if (profile !== "minimal" && !dryRun) {
       const hh = installHarnessHooks({ projectDir, logger });
       result.harnessHooks = hh.wired ? "wired" : "script-only";
+      // KJC-TSK-0713 — the Sentinel: method state + Stop gate (turn cannot
+      // end red). Same Claude-only harness surface as the tool gate.
+      const sh = installSentinelHooks({ projectDir, logger });
+      result.sentinelHooks = sh.wired ? "wired" : "script-only";
     }
   } catch (err) {
     if (json) logger.info?.(JSON.stringify({ ok: false, error: err.message }));

package/src/commands/report.js

@@ -162,6 +162,9 @@ async function buildReport(dir, sessionId) {
   if (session.pg_task_id) report.pg_task_id = session.pg_task_id;
   if (session.pg_project_id) report.pg_project_id = session.pg_project_id;
   if (session.rtk_savings) report.rtk_savings = session.rtk_savings;
+  // The session may belong to another workspace: its snapshot knows the
+  // project dir the sentinel state lives in (same source solomon-rules uses).
+  if (session.config_snapshot?.projectDir) report.project_dir = session.config_snapshot.projectDir;
   return report;
 }
 
@@ -210,6 +213,36 @@ function printTextReport(report) {
   console.log(formatCommitsText(report.commits_generated));
 }
 
+/**
+ * KJC-TSK-0715 — escapes are the user's decisions, never the agent's silent
+ * shortcuts: every KJ_ALLOW_* the sentinel honored surfaces in the report.
+ */
+export function formatSentinelEscapes(state) {
+  const events = Array.isArray(state?.escape_events) ? state.escape_events : [];
+  if (events.length === 0) return null;
+  const lines = events.map(
+    (e) => `  ${e.ts ? new Date(e.ts).toISOString() : "?"} ${e.escape} (tool: ${e.tool || "?"}, session: ${e.sid || "?"})`
+  );
+  return `Sentinel escapes used (${events.length}):\n${lines.join("\n")}`;
+}
+
+// The sentinel state is a PROJECT artifact (<project>/.karajan/harness), not
+// a session artifact: the `dir` the report handlers receive is the GLOBAL
+// sessions root (~/.karajan/sessions) and never contains it. `kj report` is
+// run from inside the project, so the project dir is the cwd — overridable
+// for callers reporting on another workspace.
+async function printSentinelEscapes({ projectDir = process.cwd(), format } = {}) {
+  if (format === "json") return;
+  try {
+    const raw = await fs.readFile(path.join(projectDir, ".karajan", "harness", "sentinel-state.json"), "utf8");
+    const text = formatSentinelEscapes(JSON.parse(raw));
+    if (text) {
+      console.log("");
+      console.log(text);
+    }
+  } catch { /* no sentinel state in this project — nothing to report */ }
+}
+
 function formatDuration(ms) {
   if (ms === null || ms === undefined) return "-";
   if (ms < 1000) return `${ms}ms`;
@@ -384,6 +417,7 @@ async function handlePgTaskReport({ dir, pgTask, list, sessionId, format, trace,
   } else {
     printTextReport(report);
   }
+  await printSentinelEscapes({ projectDir: report.project_dir, format });
 }
 
 async function handleSingleSessionReport({ dir, entries, sessionId, format, trace, currency }) {
@@ -405,9 +439,10 @@ async function handleSingleSessionReport({ dir, entries, sessionId, format, trac
   if (trace) {
     const { cur, rate } = await resolveTraceOptions(currency);
     printTraceReport(report, cur, rate);
-    return;
+  } else {
+    printTextReport(report);
   }
-  printTextReport(report);
+  await printSentinelEscapes({ projectDir: report.project_dir, format });
 }
 
 export async function reportCommand({ list = false, sessionId = null, format = "text", trace = false, currency = "usd", pgTask = null }) {

package/src/config/overrides.js

@@ -81,7 +81,14 @@ function applyRoleOverrides(out, flags) {
   // boolean means the flag belongs to the command itself (`kj audit
   // --security`, KJC-TSK-0695) and must not become a provider.
   for (const [flag, role] of ROLE_PROVIDER_FLAGS) {
-    if (typeof flags[flag] === "string" && flags[flag]) out.roles[role].provider = flags[flag];
+    if (typeof flags[flag] === "string" && flags[flag]) {
+      // A model pin belongs to the provider it was written for — switching
+      // provider by flag drops it (KJC-TSK-0729: codex's pinned mini reached
+      // agy, which answered with its model list instead of a verdict). An
+      // explicit --<role>-model flag re-pins below, after this loop.
+      if (out.roles[role].provider && out.roles[role].provider !== flags[flag]) out.roles[role].model = null;
+      out.roles[role].provider = flags[flag];
+    }
   }
   // coder/reviewer also update top-level aliases
   if (flags.coder) out.coder = flags.coder;