karajan-code 4.1.3 → 4.1.5

package/docs/README.es.md

@@ -1,286 +1,69 @@
 <p align="center">
-  <img src="karajan-code-logo-small.png" alt="Karajan Code" width="180">
+  <img src="karajan-orbit.svg" alt="Karajan Code" width="220">
 </p>
 
 <h1 align="center">Karajan Code</h1>
 
 <p align="center">
-  Orquestador local multi-agente. TDD-first, basado en MCP, JavaScript vanilla.
+  El entorno que gobierna el desarrollo con IA — tu agente orquesta, Karajan gobierna.
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/v/karajan-code.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/dw/karajan-code.svg" alt="npm downloads"></a>
-  <a href="https://github.com/manufosela/karajan-code/actions"><img src="https://github.com/manufosela/karajan-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js"></a>
-  <a href="https://github.com/manufosela/homebrew-tap"><img src="https://img.shields.io/badge/homebrew-tap-orange.svg" alt="Homebrew"></a>
-</p>
-
-<p align="center">
-  <a href="../README.md">Read in English</a> · <a href="https://karajancode.com">Documentacion</a> · <a href="https://planning-game-xp.web.app/public/?project=Karajan%20Code">Roadmap publico</a>
+  <a href="../README.md">Read in English</a> · <a href="https://karajancode.com">Documentación</a> · <a href="https://planning-game-xp.web.app/public/?project=Karajan%20Code">Roadmap público</a>
 </p>
 
 ---
 
-Tu describes lo que quieres construir. Karajan orquesta multiples agentes de IA para planificarlo, implementarlo, testearlo, revisarlo con SonarQube e iterar. Sin que tengas que supervisar cada paso.
-
-## Que es Karajan?
-
-Karajan es un orquestador de codigo local. Corre en tu maquina, usa tus proveedores de IA existentes (Claude, Codex, Gemini, Aider, OpenCode) y coordina un pipeline de agentes especializados que trabajan juntos en tu codigo.
-
-No es un servicio en la nube. No es una extension de VS Code. Es una herramienta que instalas una vez y usas desde la terminal o como servidor MCP dentro de tu agente de IA.
-
-El nombre viene de Herbert von Karajan, el director de orquesta que creia que las mejores orquestas estan formadas por grandes musicos independientes que saben exactamente cuando tocar y cuando escuchar. La misma idea, aplicada a agentes de IA.
-
-## Por que no usar solo Claude Code?
-
-Claude Code es excelente. Usalo para codificacion interactiva basada en sesiones.
-
-Usa Karajan cuando quieras:
-
-- **Un pipeline repetible y documentado** que corre igual cada vez
-- **TDD por defecto.** Los tests se escriben antes de la implementacion, no despues
-- **Integracion con SonarQube.** Quality gates como parte del flujo, no como algo secundario
-- **Solomon como jefe del pipeline.** Cada rechazo del reviewer es evaluado por un supervisor que decide si es valido o solo ruido de estilo
-- **Enrutamiento multi-proveedor.** Claude como coder, Codex como reviewer, o cualquier combinacion
-- **Operacion zero-config.** Auto-detecta frameworks de test, arranca SonarQube, simplifica el pipeline para tareas triviales
-- **Arquitectura de roles composable.** Comportamientos de agente definidos como ficheros markdown que viajan con tu proyecto
-- **Local-first.** Tu codigo, tus claves, tu maquina. Ningun dato sale salvo que tu lo digas
-- **Zero costes de API.** Karajan usa CLIs de agentes de IA (Claude Code, Codex, Gemini CLI), no APIs. Pagas tu suscripcion existente (Claude Pro, ChatGPT Plus), no tarifas por token
-
-Si Claude Code es un programador de pares inteligente, Karajan es el pipeline CI/CD para desarrollo asistido por IA. Funcionan genial juntos: Karajan esta diseñado para usarse como servidor MCP dentro de Claude Code.
-
-## Instalacion
-
-**npm** (recomendado):
-```bash
-npm install -g karajan-code
-```
-
-**Homebrew** (macOS):
-```bash
-brew install manufosela/tap/karajan-code
-```
-
-**Binario standalone** (sin Node.js):
-```bash
-# macOS (Apple Silicon)
-curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-darwin-arm64 -o kj && chmod +x kj
-
-# Linux x64
-curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-linux-x64 -o kj && chmod +x kj
-
-# Windows
-curl -L https://github.com/manufosela/karajan-code/releases/latest/download/kj-win-x64.exe -o kj.exe
-```
-
-**One-liner** (detecta SO, instala via npm):
-```bash
-curl -fsSL https://raw.githubusercontent.com/manufosela/karajan-code/main/scripts/install-kj.sh | sh
-```
-
-**Docker**:
-```bash
-docker run --rm -v $(pwd):/workspace karajan-code kj --version
-```
-
-`kj init` auto-detecta tus agentes instalados e instala RTK para optimizacion de tokens.
-
-## Tres formas de usar Karajan
-
-Karajan instala **tres comandos**: `kj`, `kj-tail` y `karajan-mcp`.
-
-### 1. CLI: directamente desde terminal
-
-Ejecuta Karajan directamente. Ves la salida completa del pipeline en tiempo real.
-
-```bash
-kj run "Crea una utilidad que valide numeros de DNI español, con tests"
-kj code "Añade validacion de inputs al formulario de registro"     # Solo coder
-kj review "Revisa los cambios de autenticacion"                     # Revisar diff actual
-kj audit "Analisis completo de salud de este codebase"              # Auditoria solo-lectura
-kj plan "Refactorizar la capa de base de datos"                     # Planificar sin codificar
-```
-
-### 2. MCP: dentro de tu agente de IA
-
-Este es el caso de uso principal. Karajan corre como servidor MCP dentro de Claude Code, Codex o Gemini. Le pides algo a tu agente de IA y el delega el trabajo pesado al pipeline de Karajan.
-
-```
-Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
-```
-
-El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 27 herramientas (`kj_run`, `kj_code`, `kj_review`, `kj_hu`, etc.) y las usa segun necesite.
+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.
 
-**El problema**: cuando Karajan corre dentro de un agente de IA, pierdes visibilidad. El agente te muestra el resultado final, pero no las etapas del pipeline, iteraciones o decisiones de Solomon en tiempo real.
+- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina.
+- **Card primero** — todo trabajo se registra (`kj hu add|move|list`) antes de empezar; las decisiones de arquitectura viven como ADRs en git (`kj adr add|list`).
+- **Los tests prueban el comportamiento** — el test que falla existe primero; la suite nunca se queda en rojo.
+- **Revisión IA-cruzada en cada commit** — `kj review --staged` liga el veredicto de una IA *distinta* al sha256 del diff exacto. Cambia el código y hay que revisarlo de nuevo. Sin veredicto aprobado, **el commit no entra** (gate pre-commit).
+- **Una tercera IA arbitra las disputas** — `kj solomon` decide cuando brain y reviewer discrepan. Los hallazgos de seguridad no los anula nadie — ni siquiera el arbitraje.
+- **Rama primero** — la rama base solo se mueve por PRs atómicas.
 
-### 3. kj-tail: monitorizar desde otro terminal
+Este repo corre bajo su propio entorno: cada commit de karajan-code lleva un veredicto de IA cruzada.
 
-**La herramienta compañera.** Abre un segundo terminal en el **mismo directorio del proyecto** donde esta trabajando tu agente de IA:
+## Instalación
 
-```bash
-kj-tail
-```
-
-Veras la salida del pipeline en vivo (etapas, resultados, iteraciones, errores) tal como ocurren. La misma vista que ejecutar `kj run` directamente.
-
-```
-kj-tail                  # Seguir pipeline en tiempo real (por defecto)
-kj-tail -v               # Verbose: incluir heartbeats de agente y presupuesto
-kj-tail -t               # Mostrar timestamps
-kj-tail -s               # Snapshot: mostrar log actual y salir
-kj-tail -n 50            # Mostrar ultimas 50 lineas y seguir
-kj-tail --help           # Todas las opciones
-```
-
-> **Importante**: `kj-tail` debe ejecutarse desde el mismo directorio donde el agente de IA esta trabajando. Lee `<proyecto>/.kj/run.log`, que se crea cuando Karajan arranca un pipeline via MCP.
-
-[**Ver la demo completa del pipeline**](https://karajancode.com#demo): triage, arquitectura, TDD, SonarQube, code review, arbitraje de Solomon, auditoria de seguridad.
-
-## El pipeline
-
-```
-pre-loop:  intent → hu-reviewer? → triage? → domain-curator? → discover? → skills? → researcher? → architect? → planner? → acceptance?
-iteration: coder → refactorer? → guard(output) → guard(perf) → sonar? → tdd → reviewer → solomon? → brain?   (bucle 1..N)
-post-loop: tester? → security? → perf? → impeccable? → audit?
-```
-
-**24 etapas** repartidas en tres fases: 18 roles respaldados por agente IA (tabla abajo), 6 etapas deterministas sin llamada al LLM (`intent`, `skills`, `acceptance`, `guard(output)`, `guard(perf)`, `tdd`). Dos clases extra (`commiter`, `repairer`) son post-aprobación / auxiliares internas, no etapas independientes del pipeline. Cada rol IA es ejecutado por el agente que tú elijas:
-
-| Rol | Que hace | Por defecto |
-|-----|----------|-------------|
-| **hu-reviewer** | Certifica historias de usuario antes de codificar (6 dimensiones, 7 antipatrones) | Auto (media/compleja) |
-| **triage** | Clasifica complejidad, activa roles, detecta domain hints | **On** |
-| **domain-curator** | Descubre, propone y sintetiza conocimiento de dominio de negocio para el pipeline | Auto (cuando existen dominios) |
-| **discover** | Detecta huecos en requisitos (Mom Test, Wendel, JTBD) | Off |
-| **architect** | Diseña la arquitectura de la solucion antes de planificar | Off |
-| **planner** | Genera planes de implementacion estructurados | Off |
-| **coder** | Escribe codigo y tests siguiendo metodologia TDD | **Siempre on** |
-| **refactorer** | Mejora la claridad del codigo sin cambiar comportamiento | Off |
-| **sonar** | Analisis estatico SonarQube con quality gate enforcement | On (auto-gestionado) |
-| **impeccable** | Auditoria UI/UX para tareas frontend (a11y, rendimiento, theming) | Auto (frontend) |
-| **reviewer** | Code review con perfiles de exigencia configurables | **Siempre on** |
-| **tester** | Quality gate de tests y verificacion de cobertura | **On** |
-| **security** | Auditoria de seguridad OWASP | **On** |
-| **solomon** | Jefe del pipeline: evalua cada rechazo, anula bloqueos solo de estilo | **On** |
-| **commiter** | Automatizacion de git commit, push y PR tras aprobacion | Off |
-| **researcher** | Investiga el codebase antes de planificar (mapa de ficheros + signatures + tests relacionados) | Off |
-| **perf** | Quality gate WebPerf — Core Web Vitals (LCP, CLS, INP) via Lighthouse | Off |
-| **brain** | Orquestador IA central: routing, enriquecimiento de feedback, compresión de salidas | **On** |
-| **audit** | Analisis de salud del codebase solo-lectura (5 dimensiones, scores A-F) | Standalone |
-
-> **Etapas deterministas (sin clase):** `intent` (clasificador de tipo de tarea — `sw` / `infra` / `doc` / `add-tests` / `refactor` / `audit`), `skills` (superficie de slash-commands), `acceptance` (tests de aceptación ejecutables), `guard(output)` (operaciones destructivas + fugas de credenciales), `guard(perf)` (anti-patrones frontend), `tdd` (verificación de cobertura).
->
-> **Auxiliares internas (tienen clase, no etapa independiente):** `commiter` (automatización git post-aprobación), `repairer` (repara tests de aceptación rotos en runtime, invocado por `acceptance` / `tdd`).
->
-> Referencia completa por etapa: [Roles del pipeline](https://karajan-code.web.app/docs/es/handbook/pipeline-roles/) (handbook).
-
-## 5 agentes de IA soportados
-
-| Agente | CLI | Instalacion |
-|--------|-----|-------------|
-| **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
-| **Codex** | `codex` | `npm install -g @openai/codex` |
-| **Gemini** | `gemini` | Ver [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
-| **Aider** | `aider` | `pipx install aider-chat` (o `pip3 install aider-chat`) |
-| **OpenCode** | `opencode` | Ver [OpenCode docs](https://github.com/nicepkg/opencode) |
-
-Mezcla y combina. Usa Claude como coder y Codex como reviewer. Karajan auto-detecta agentes instalados durante `kj init`.
-
-## Servidor MCP (27 herramientas)
-
-Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y Codex. Config manual si es necesario:
+Dile a tu agente — en el directorio donde quieras trabajar:
 
-```bash
-# Claude: añadir a ~/.claude.json → "mcpServers":
-# { "karajan-mcp": { "command": "karajan-mcp" } }
-
-# Codex: añadir a ~/.codex/config.toml → [mcp_servers."karajan-mcp"]
-# command = "karajan-mcp"
+```text
+Quiero usar Karajan en este proyecto: lee https://karajancode.com/start.md
+y haz lo que dice.
 ```
 
-**27 herramientas** disponibles: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_board`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_hu`, `kj_skills`, `kj_suggest`, `kj_undo`, `kj_clean`, `kj_rag_query`, `kj_rag_index`.
-
-Usa `kj-tail` en un terminal separado para ver lo que el pipeline esta haciendo en tiempo real (ver [Tres formas de usar Karajan](#tres-formas-de-usar-karajan)).
-
-## La arquitectura de roles
+El prompt enrutador instala el stack completo si hace falta, detecta si el proyecto es nuevo o existente, activa el entorno, y **para a esperarte** cuando un paso necesita sudo o una cuenta (código de salida 3 de `kj` = pendiente de ti — una instalación parcial es una instalación fallida).
 
-Cada rol en Karajan esta definido por un fichero markdown: un documento plano que describe como debe comportarse el agente, que revisar y como es un buen output.
+Equivalente manual:
 
+```sh
+curl -fsSL https://karajancode.com/install.sh | sh   # producto completo (npm-first; --standalone para solo-CLI)
+kj doctor && kj install-tools                        # completa el stack
+kj init && kj env install && kj harden && kj review --install-gate
+git config core.hooksPath .karajan/hooks
 ```
-.karajan/roles/         # Overrides de proyecto (opcional)
-~/.karajan/roles/       # Overrides globales (opcional)
-templates/roles/        # Defaults built-in (incluidos en el paquete)
-```
-
-Puedes sobreescribir cualquier rol built-in o crear nuevos. Sin codigo. Los agentes leen los ficheros de rol y adaptan su comportamiento. Codifica las convenciones de tu equipo, reglas de dominio y estandares de calidad, y cada ejecucion de Karajan los aplica automaticamente.
-
-Usa `kj roles show <rol>` para inspeccionar cualquier template.
-
-## Zero-config por diseño
-
-Karajan auto-detecta y auto-configura todo lo que puede:
-
-- **TDD**: Detecta framework de tests para 12 lenguajes (vitest, jest, JUnit, pytest, go test, cargo test, y mas). Auto-activa TDD para tareas de codigo, lo salta para doc/infra
-- **Bootstrap gate**: Valida todos los prerequisitos (repo git, remote, config, agentes, SonarQube) antes de ejecutar. Falla con instrucciones claras, nunca degrada silenciosamente
-- **Injection guard**: Escanea diffs en busca de prompt injection antes del review de IA. Detecta directivas de override, Unicode invisible, payloads en comentarios sobredimensionados. Tambien como GitHub Action en cada PR
-- **SonarQube**: Auto-arranca contenedor Docker, espera hasta 60s al arranque, genera config si falta
-- **Complejidad del pipeline**: Triage clasifica la tarea, las triviales saltan el loop del reviewer
-- **Caidas de proveedor**: Reintentos en 500/502/503/504 con backoff (igual que rate limits)
-- **Cobertura**: Fallos de quality gate solo por cobertura se tratan como advisory
-- **HU Manager**: Las tareas complejas se descomponen automaticamente en historias de usuario formales con dependencias. Cada HU se ejecuta como su propio sub-pipeline con seguimiento de estado visible en el HU Board
-
-Sin configuracion por proyecto requerida. Si quieres personalizar, la config se apila: sesion > proyecto > global.
 
-## Por que JavaScript vanilla?
+Requiere git y al menos un CLI de agente de IA — con dos hay revisión cruzada; con tres, arbitraje. Todas las rutas de instalación (npm, binarios, brew, wrapper Python) en la [doc de instalación](https://karajancode.com/docs/es/v4/install/).
 
-No es nostalgia ni cabezoneria. Es que llevo usando JavaScript desde 1997, cuando Brendan Eich lo creo en una semana y nos cambio la vida a los que haciamos webs. Conozco sus tripas, sus bugs, sus rarezas. Y se que quien conoce JS de verdad convierte esos bugs en features. TypeScript existe para que developers acostumbrados a lenguajes fuertemente tipados no entren en panico al ver JS. Respeto eso. Pero yo no lo necesito. Los tests son mi seguridad de tipos. JSDoc y un buen IDE son mi intellisense. Y no tener un compilador entre el codigo y yo es lo que me permite moverme a 57 releases en 45 dias sin miedo.
+## El bucle diario
 
-[Por que JavaScript vanilla: la version larga](why-vanilla-js.md)
+1. Describes lo que quieres. Tu agente crea la card (`kj hu add`), consulta el RAG, escribe el test que falla y después el código.
+2. `kj review --staged` — una IA distinta revisa el diff exacto. Aprobado → el commit entra. Rechazado → se corrige, o se escala a `kj solomon`.
+3. PR atómica a la rama base. `kj report` muestra el rastro; el HU Board (`kj board`) muestra el trabajo.
+4. ¿Tu agente choca con un bug de kj? `kj report-issue` lo sube — sanitizado, deduplicado y solo con tu aprobación. El ecosistema se repara solo.
 
-## Compañeros recomendados
+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/).
 
-| Herramienta | Por que |
-|-------------|---------|
-| [**RTK**](https://github.com/rtk-ai/rtk) | Reduce consumo de tokens 60-90% en salidas de comandos Bash |
-| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Gestion agil de proyectos (tareas, sprints, estimacion), nativo XP |
-| [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Crear PRs, gestionar issues directamente desde el agente |
-| [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Verificar cambios de UI visualmente tras modificar frontend |
+## Modo headless
 
-## Contribuir
+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. `kj advanced` lista la superficie completa. [Doc del modo headless](https://karajancode.com/docs/es/v4/headless/).
 
-```bash
-git clone https://github.com/manufosela/karajan-code.git
-cd karajan-code
-npm install
-npm test              # Ejecutar ~5 368 tests en 482 ficheros con Vitest
-npm run validate      # Lint + test
-```
-
-Issues y pull requests bienvenidos. Si algo no funciona como esta documentado, [abre un issue](https://github.com/manufosela/karajan-code/issues). Es la contribucion mas util en esta fase.
-
-## Telemetria
-
-Karajan recopila estadisticas de uso anonimas para mejorar la herramienta:
-version, sistema operativo, comando utilizado, duracion del pipeline y tasa de exito.
-No se envia nunca codigo, descripciones de tareas ni datos personales.
-
-Desactivar: establece `telemetry: false` en `~/.karajan/kj.config.yml`
-
-## Enlaces
-
-- [Web](https://karajancode.com) (tambien [kj-code.com](https://kj-code.com))
-- [Documentacion completa](https://karajancode.com/docs/)
-- [Changelog](../CHANGELOG.md)
-- [Politica de seguridad](../SECURITY.md)
-- [Licencia (AGPL-3.0)](../LICENSE)
-
----
+## v3 (histórico)
 
-Construido por [@manufosela](https://github.com/manufosela). Head of Engineering en Geniova Technologies, co-organizador de NodeJS Madrid, autor de [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 90+ paquetes npm publicados.
+Karajan v1–v3 fue un pipeline multiagente headless dirigido por completo mediante orquestación de subprocesos. Su historia íntegra — pipeline, 24 roles, servidor MCP, step mode, carriles paralelos — se conserva en el **[README de v3 (archivo histórico)](README.v3.es.md)** y en el [archivo de docs v3](https://karajancode.com/docs/es/getting-started/introduction/).
 
-### Contributors
+## Contribuir y licencia
 
-- [@aitormf](https://github.com/aitormf) — Agente OpenCode (5o agente built-in)
-- [@reiaguilera](https://github.com/reiaguilera) — Beta testing, propuestas de mejora y feedback de calidad
+Issues y PRs bienvenidas — los informes de fricción vía `kj report-issue` valen oro. Licencia [AGPL-3.0](../LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.1.3",
+  "version": "4.1.5",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/agents/gemini-agent.js

@@ -37,12 +37,16 @@ function extractGeminiUsage(text) {
 }
 
 export class GeminiAgent extends BaseAgent {
+  // Overridden by forks with the same headless interface (QwenAgent).
+  get cliBin() { return "gemini"; }
+  get spawnEnv() { return { GEMINI_CLI_TRUST_WORKSPACE: "true" }; }
+
   async runTask(task) {
     const role = task.role || "coder";
     const model = this.getRoleModel(role);
     const result = await this._exec(task, model, "run");
     if (!result.ok && model && this.isModelNotSupportedError(result)) {
-      this.logger?.warn(`Gemini model "${model}" not supported — retrying with agent default`);
+      this.logger?.warn(`${this.cliBin} model "${model}" not supported — retrying with agent default`);
       return this._exec(task, null, "run");
     }
     return result;
@@ -53,17 +57,24 @@ export class GeminiAgent extends BaseAgent {
     const model = this.getRoleModel(role);
     const result = await this._exec(task, model, "review");
     if (!result.ok && model && this.isModelNotSupportedError(result)) {
-      this.logger?.warn(`Gemini model "${model}" not supported — retrying with agent default`);
+      this.logger?.warn(`${this.cliBin} model "${model}" not supported — retrying with agent default`);
       return this._exec(task, null, "review");
     }
     return result;
   }
 
   async _exec(task, model, mode) {
-    const args = ["-p", task.prompt];
+    // KJC-BUG-0121: the prompt NEVER travels as a CLI argument — a solomon
+    // prompt embeds the full diff, and large diffs blow past the kernel's
+    // per-argument limit (E2BIG). gemini reads the prompt from stdin in
+    // headless mode. Same bug's layer 2: headless gemini refuses untrusted
+    // workspaces unless GEMINI_CLI_TRUST_WORKSPACE is set.
+    const args = [];
     if (mode === "review") args.push("--output-format", "json");
     if (model) args.push("--model", model);
-    const res = await this.runCommand(resolveBin("gemini"), args, {
+    const res = await this.runCommand(resolveBin(this.cliBin), args, {
+      input: task.prompt,
+      env: this.spawnEnv,
       onOutput: task.onOutput,
       silenceTimeoutMs: task.silenceTimeoutMs,
       timeout: task.timeoutMs

package/src/agents/index.js

@@ -3,6 +3,7 @@ import { CodexAgent } from "./codex-agent.js";
 import { GeminiAgent } from "./gemini-agent.js";
 import { AiderAgent } from "./aider-agent.js";
 import { OpenCodeAgent } from "./opencode-agent.js";
+import { QwenAgent } from "./qwen-agent.js";
 
 const agentRegistry = new Map();
 
@@ -49,3 +50,4 @@ registerAgent("codex", CodexAgent, { bin: "codex", installUrl: "https://develope
 registerAgent("gemini", GeminiAgent, { bin: "gemini", installUrl: "https://github.com/google-gemini/gemini-cli" });
 registerAgent("aider", AiderAgent, { bin: "aider", installUrl: "https://aider.chat/docs/install.html" });
 registerAgent("opencode", OpenCodeAgent, { bin: "opencode", installUrl: "https://opencode.ai" });
+registerAgent("qwen", QwenAgent, { bin: "qwen", installUrl: "https://github.com/QwenLM/qwen-code" });

package/src/agents/qwen-agent.js

@@ -0,0 +1,20 @@
+import { GeminiAgent } from "./gemini-agent.js";
+
+/**
+ * Qwen Code (@qwen-code/qwen-code, binary `qwen`) — KJC-TSK-0665.
+ *
+ * A gemini-cli fork with the same headless interface (prompt on stdin,
+ * `--output-format json`, `--model`, identical usageMetadata shape), so it
+ * inherits everything from GeminiAgent including the KJC-BUG-0121 stdin
+ * contract. Cloud-backed and free with a Qwen account: the sixth built-in
+ * agent, and the natural third AI for solomon arbitration now that the
+ * gemini individual tier is retired.
+ */
+export class QwenAgent extends GeminiAgent {
+  get cliBin() { return "qwen"; }
+  // qwen has no workspace-trust gate. execa merges this object over
+  // process.env, so the explicit undefined REMOVES gemini's var from the
+  // child even when the parent shell exported it (manual workarounds) —
+  // returning no env at all would let it leak through inheritance.
+  get spawnEnv() { return { GEMINI_CLI_TRUST_WORKSPACE: undefined }; }
+}

package/src/review/solomon-arbitration.js

@@ -81,7 +81,18 @@ export async function runSolomonArbitration({
   logger?.info?.(`kj solomon: brain=${hostAgent || "?"} vs reviewer=${verdict.reviewer} → arbiter=${solomon}`);
   const agent = createAgentFn(solomon, config, logger);
   const result = await agent.reviewTask({ prompt, role: "solomon" });
-  if (!result?.ok) throw new Error(`solomon ${solomon} failed: ${result?.error || "no output"}`);
+  if (!result?.ok) {
+    // KJC-BUG-0121 layer 3: a binary on PATH is not an OPERATIONAL arbiter
+    // (dead account tier, auth, trust). Fail with the way out, not just the
+    // wreckage: name the other agents that could arbitrate instead.
+    const others = (await detectAgents())
+      .filter((a) => a.available && a.name !== solomon && a.name !== hostAgent && a.name !== verdict.reviewer)
+      .map((a) => a.name);
+    const hint = others.length > 0
+      ? `If ${solomon} is not operational on this machine (account tier, auth, workspace trust), set roles.solomon.provider in your kj config to another agent: ${others.join(", ")}.`
+      : `No other agent CLI on this machine can arbitrate (needs one distinct from brain "${hostAgent}" and reviewer "${verdict.reviewer}") — install a third agent CLI or fix ${solomon}.`;
+    throw new Error(`solomon ${solomon} failed: ${String(result?.error || "no output").slice(0, 400)}\n${hint}`);
+  }
   const parsed = parseMaybeJsonString(result.output);
   if (!parsed || !["approve", "reject"].includes(parsed.ruling)) {
     throw new Error(`solomon ${solomon} returned no parseable ruling`);

package/src/utils/agent-detect.js

@@ -7,7 +7,8 @@ const KNOWN_AGENTS = [
   { name: "codex", install: getInstallCommand("codex") },
   { name: "gemini", install: getInstallCommand("gemini") },
   { name: "aider", install: getInstallCommand("aider") },
-  { name: "opencode", install: getInstallCommand("opencode") }
+  { name: "opencode", install: getInstallCommand("opencode") },
+  { name: "qwen", install: getInstallCommand("qwen") }
 ];
 
 export async function checkBinary(name, versionArg = "--version") {

package/src/utils/binary-sources.js

@@ -44,6 +44,12 @@ export function osvScannerSource(platform = process.platform, arch = process.arc
  */
 export function semgrepFallback(available = {}) {
   if (available.docker) return { via: "docker", command: "docker pull semgrep/semgrep" };
+  // KJC-BUG-0120 (issue #1256): on Debian/Ubuntu-like systems the system
+  // Python is externally managed (PEP 668) and often ships without pip at
+  // all — `python3 -m pip install --user` is guaranteed to fail there.
+  // pipx must come from the distro's own package manager.
+  if (available.apt) return { via: "apt", command: "sudo apt update && sudo apt install -y pipx && pipx install semgrep" };
+  if (available.dnf) return { via: "dnf", command: "sudo dnf install -y pipx && pipx install semgrep" };
   return { via: "pipx", command: "python3 -m pip install --user pipx && pipx install semgrep" };
 }
 

package/src/utils/display/header.js

@@ -4,7 +4,6 @@ import { fileURLToPath } from "node:url";
 import { printBanner } from "../banner.js";
 import { ANSI } from "./formatters.js";
 
-// TODO: i18n display messages
 const DISPLAY_PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../package.json");
 const DISPLAY_VERSION = JSON.parse(readFileSync(DISPLAY_PKG_PATH, "utf8")).version;
 

package/src/utils/install-hints.js

@@ -80,8 +80,13 @@ export async function getInstallHint(tool, available = null) {
   for (const { manager, command } of candidates) {
     if (avail[manager]) return { command, manager, manualUrl: MANUAL_URLS[tool] };
   }
-  // Nothing matched — fall back to the first candidate's command as a
-  // suggestion, so the user at least sees a working recipe.
+  // Nothing matched — suggest a recipe that actually works on this system.
+  // KJC-BUG-0120 (issue #1256): distro-aware fallbacks first (PEP 668 makes
+  // the generic pip bootstrap fail on Debian/Ubuntu); these are display-only
+  // (manager: null), never auto-run — sudo stays in the user's hands.
+  for (const { when, command } of DISTRO_FALLBACKS[tool] || []) {
+    if (avail[when]) return { command, manager: null, manualUrl: MANUAL_URLS[tool] };
+  }
   const first = candidates[0];
   return {
     command: first ? first.command : null,
@@ -90,6 +95,13 @@ export async function getInstallHint(tool, available = null) {
   };
 }
 
+const DISTRO_FALLBACKS = {
+  semgrep: [
+    { when: "apt", command: "sudo apt update && sudo apt install -y pipx && pipx install semgrep" },
+    { when: "dnf", command: "sudo dnf install -y pipx && pipx install semgrep" },
+  ],
+};
+
 const INSTALL_CANDIDATES = {
   semgrep: [
     { manager: "pipx", command: "pipx install semgrep" },

package/src/utils/os-detect.js

@@ -51,6 +51,11 @@ const INSTALL_COMMANDS = {
     linux: "curl -fsSL https://opencode.ai/install | bash",
     windows: "See https://github.com/nicepkg/opencode for Windows install"
   },
+  qwen: {
+    macos: "npm install -g @qwen-code/qwen-code",
+    linux: "npm install -g @qwen-code/qwen-code",
+    windows: "npm install -g @qwen-code/qwen-code"
+  },
   docker: {
     macos: "brew install --cask docker",
     linux: "sudo apt install docker.io docker-compose-v2 (or see https://docs.docker.com/engine/install/)",

package/src/utils/pending-user-action.js

@@ -25,7 +25,9 @@ const OS_COMMANDS = {
     win32: ["winget install Git.Git"],
   },
   semgrep: {
-    linux: ["python3 -m pip install --user semgrep   # or: pipx install semgrep"],
+    // PEP 668 (#1256): system Python is externally managed on modern
+    // distros — pipx comes from the distro package manager, never from pip.
+    linux: ["sudo apt update && sudo apt install -y pipx && pipx install semgrep   # Debian/Ubuntu", "sudo dnf install -y pipx && pipx install semgrep   # Fedora/RHEL"],
     darwin: ["brew install semgrep"],
     win32: ["python -m pip install --user semgrep"],
   },
@@ -75,10 +77,11 @@ export function renderPendingBlock(pending, { platform = process.platform, retry
   for (const r of pending) {
     const why = r.error ? `install failed: ${r.error}` : r.reason || "no automatic route on this machine";
     lines.push(`  ▸ ${r.tool}  (${why})`);
-    const commands = r.commands
-      ?? (r.command ? [r.command] : null)
-      ?? (r.suggested ? [r.suggested] : null)
-      ?? (osCommandsFor(r.tool, platform).length > 0 ? osCommandsFor(r.tool, platform) : null)
+    const os = osCommandsFor(r.tool, platform);
+    const own = r.commands ?? (r.command ? [r.command] : null) ?? (r.suggested ? [r.suggested] : null);
+    // A FAILED install must not be re-suggested verbatim (#1256: the pip
+    // route that just broke) — the curated per-OS route goes first there.
+    const commands = (r.action === "failed" ? (os.length > 0 ? os : own) : (own ?? (os.length > 0 ? os : null)))
       ?? [`see ${r.manualUrl || "the tool's install docs"}`];
     for (const c of commands) lines.push(`      ${c}`);
     lines.push("");