karajan-code 4.23.0 → 4.25.0

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

@@ -13,6 +13,9 @@ import wikiRoutes from './routes/wiki.js';
 import governanceRoutes from './routes/governance.js';
 import { authMiddleware } from './auth.js';
 import { getOrCreateToken, getTokenPath } from './token-store.js';
+import { createRequire } from 'node:module';
+import { createTerminalManager } from './terminal.js';
+import { terminalRouter, attachTerminalWs } from './terminal-wire.js';
 import { reapZombieSessions } from './zombie-reaper.js';
 import { reapZombieHus } from './hu-zombie-reaper.js';
 import { setHuStatus as setHuStatusPlanMutation, setHuFailResult as setHuFailResultPlanMutation } from './plan-mutations.js';
@@ -295,6 +298,8 @@ async function main() {
 
   // Create Express app
   const app = express();
+  // node-pty es CJS nativo y @xterm se localiza por resolve: require clásico.
+  const requireCjs = createRequire(import.meta.url);
   app.use(...buildSecurityMiddleware());
   app.use(express.json());
   app.use(express.static(PUBLIC_DIR, { setHeaders: noStoreHeaders, etag: false, lastModified: false }));
@@ -304,6 +309,25 @@ async function main() {
   app.use('/api/wiki', authMiddleware(), wikiRoutes);
   app.use('/api/governance', authMiddleware(), governanceRoutes);
 
+  // Terminal embebida (KJC-TSK-0816, ADR 0008): la lógica vive en
+  // terminal.js; aquí solo el montaje. El agente arranca en el cwd del
+  // daemon (kj go arranca el board desde el proyecto) u override por env.
+  // xterm se sirve DESDE la dependencia — nada vendorizado al repo.
+  const terminalManager = createTerminalManager({
+    spawnPty: (...args) => requireCjs('node-pty').spawn(...args),
+    cwd: process.env.HU_BOARD_TERMINAL_CWD || process.cwd(),
+    promptArg: process.env.HU_BOARD_TERMINAL_PROMPT,
+  });
+  app.use(
+    '/api/terminal',
+    authMiddleware(),
+    terminalRouter(terminalManager, { defaultAgent: process.env.HU_BOARD_TERMINAL_AGENT || 'claude' }),
+  );
+  app.use(
+    '/vendor/xterm',
+    express.static(dirname(requireCjs.resolve('@xterm/xterm/package.json'))),
+  );
+
   // SPA fallback: serve index.html for non-API, non-static routes
   app.get('/{*splat}', (_req, res) => {
     res.setHeader('Cache-Control', 'no-store, must-revalidate');
@@ -318,6 +342,7 @@ async function main() {
   const isLoopback = LOOPBACK_ADDRESSES.has(bindHost);
 
   const server = app.listen(port, bindHost, () => {
+    attachTerminalWs(server, terminalManager);
     // Write the PID file so the CLI's `kj board status / stop` and
     // the next `kj plan`'s startBoard() check find this server. The
     // file used to be written only by `kj board start`'s launcher,

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

@@ -1,6 +1,7 @@
 import { watch } from 'chokidar';
+import { execFileSync } from 'node:child_process';
 import { readFileSync, readdirSync, existsSync, rmSync } from 'node:fs';
-import { dirname, join, basename } from 'node:path';
+import { dirname, join, basename, isAbsolute, resolve as resolvePath } from 'node:path';
 import { homedir } from 'node:os';
 import {
   getKjHome,
@@ -93,7 +94,7 @@ function deriveProjectName(data, fallbackId) {
  * @param {string} projectDir
  * @returns {string}
  */
-function deriveProjectIdFromDir(projectDir) {
+export function deriveProjectIdFromDir(projectDir) {
   if (!projectDir || typeof projectDir !== 'string') return 'unknown';
   // Same slug rule the plan-store uses, so identifiers match if we ever
   // cross-reference `~/.kj/plans/<slug>/` with this project_id.
@@ -104,6 +105,42 @@ function deriveProjectIdFromDir(projectDir) {
     .slice(0, 120);
 }
 
+/** git-common-dir del directorio, con el stderr silenciado (no-git = throw). */
+const defaultGitCommonDir = (dir) =>
+  execFileSync('git', ['-C', dir, 'rev-parse', '--git-common-dir'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+
+const canonicalDirCache = new Map();
+
+/**
+ * Resolve a projectDir to the REPO's identity (KJC-BUG-0160): a linked
+ * worktree (`.claude/worktrees/*`, kj lanes) used to register the same
+ * repo as a brand-new project — 13+ same-named entries in a real picker.
+ * `git rev-parse --git-common-dir` points every worktree at the main
+ * tree's `.git`; its parent is the canonical root. A non-git directory
+ * keeps its own path as identity, as always.
+ *
+ * @param {string} projectDir
+ * @param {(dir: string) => string} [gitCommonDir] Inyectable en tests.
+ * @returns {string}
+ */
+export function canonicalProjectDir(projectDir, gitCommonDir = defaultGitCommonDir) {
+  if (!projectDir || typeof projectDir !== 'string') return projectDir;
+  if (canonicalDirCache.has(projectDir)) return canonicalDirCache.get(projectDir);
+  let canonical = projectDir;
+  try {
+    const common = gitCommonDir(projectDir);
+    const absCommon = isAbsolute(common) ? common : resolvePath(projectDir, common);
+    canonical = dirname(absCommon);
+  } catch {
+    // Sin git no hay más identidad que la ruta — comportamiento de siempre.
+  }
+  canonicalDirCache.set(projectDir, canonical);
+  return canonical;
+}
+
 /**
  * Turn a directory basename into a human-friendly Title Case string,
  * preserving every meaningful word. Unlike `slugToTitle`, this one does
@@ -379,9 +416,10 @@ export function syncPlanFile(filePath) {
     // under a single board entry. Legacy plans without `projectDir` still
     // fall back to `planId` (conservative — they at least continue to show
     // up, just each on its own card).
-    const projectId = data.projectDir
-      ? deriveProjectIdFromDir(data.projectDir)
-      : data.planId;
+    // KJC-BUG-0160: la identidad es el ROOT del repo — un plan creado desde
+    // un worktree/carril agrupa bajo el mismo proyecto que el árbol principal.
+    const canonicalDir = data.projectDir ? canonicalProjectDir(data.projectDir) : null;
+    const projectId = canonicalDir ? deriveProjectIdFromDir(canonicalDir) : data.planId;
 
     if (skipIfTombstoned('plan', data.planId, filePath)) return;
     // KJC-BUG-0055 (supersedes KJC-BUG-0050): gating por timestamp.
@@ -419,7 +457,7 @@ export function syncPlanFile(filePath) {
     //      misleadingly say "Hu Board" — that's why plan.name wins.
     //   3. slugToTitle of the task / projectId as a last resort.
     const projectName = data.name
-      || (data.projectDir ? titleCaseBasename(basename(data.projectDir)) : null)
+      || (canonicalDir ? titleCaseBasename(basename(canonicalDir)) : null)
       || slugToTitle(data.task || '')
       || projectId;
 

package/packages/hu-board/src/terminal-wire.js

@@ -0,0 +1,96 @@
+// KJC-TSK-0816 — pegamento fino de la terminal embebida: rutas REST para
+// arrancar/parar la sesión y el upgrade WebSocket que puentea el pty.
+// La LÓGICA (tokens, catálogo, ciclo de vida) vive en terminal.js y está
+// testeada con dobles; esto es cableado deliberadamente delgado.
+//
+// El token NO viaja en la URL: el cliente lo manda como subprotocolo
+// WebSocket (['kj-terminal', token]) — las URLs acaban en logs; los
+// subprotocolos, no.
+import { Router } from 'express';
+import { WebSocket, WebSocketServer } from 'ws';
+
+const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+const WS_PATH = '/api/terminal/ws';
+
+/**
+ * Monta las rutas REST de la terminal sobre un Router de express.
+ * @param {ReturnType<import('./terminal.js').createTerminalManager>} manager
+ */
+export function terminalRouter(manager, { defaultAgent = 'claude' } = {}) {
+  const router = Router();
+  router.post('/start', (req, res) => {
+    try {
+      res.json(manager.start({ agent: req.body?.agent ?? defaultAgent }));
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+  router.get('/alive', (_req, res) => res.json({ alive: manager.alive() }));
+  router.post('/stop', (req, res) => {
+    try {
+      manager.stop({ termId: req.body?.termId, token: req.body?.token });
+      res.json({ stopped: true });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+  return router;
+}
+
+/**
+ * Registra el upgrade WS en el servidor http. Entrada del cliente: bytes
+ * crudos = teclado; un mensaje que empiece por \x00 es control JSON
+ * ({type:'resize', cols, rows}) — el prefijo evita confundir un '{'
+ * tecleado con un mensaje de control.
+ *
+ * @param {import('node:http').Server} server
+ * @param {ReturnType<import('./terminal.js').createTerminalManager>} manager
+ */
+export function attachTerminalWs(server, manager) {
+  const wss = new WebSocketServer({ noServer: true });
+  server.on('upgrade', (req, socket, head) => {
+    const url = new URL(req.url, 'http://localhost');
+    if (url.pathname !== WS_PATH) return;
+    if (!LOOPBACK.has(req.socket.remoteAddress)) {
+      socket.destroy();
+      return;
+    }
+    const termId = url.searchParams.get('termId');
+    const protocols = String(req.headers['sec-websocket-protocol'] ?? '')
+      .split(',')
+      .map((p) => p.trim());
+    const token = protocols[1] ?? '';
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      let detach;
+      try {
+        detach = manager.attach({
+          termId,
+          token,
+          send: (data) => {
+            if (ws.readyState === WebSocket.OPEN) ws.send(data);
+          },
+        });
+      } catch (err) {
+        ws.close(1008, err.message);
+        return;
+      }
+      ws.on('message', (raw) => {
+        const text = raw.toString('utf8');
+        try {
+          if (text.charCodeAt(0) === 0) {
+            const msg = JSON.parse(text.slice(1));
+            if (msg.type === 'resize') {
+              manager.resize({ termId, token, cols: msg.cols, rows: msg.rows });
+            }
+            return;
+          }
+          manager.write({ termId, token, data: text });
+        } catch {
+          // Una trama malformada no tumba la sesión: se ignora y se sigue.
+        }
+      });
+      ws.on('close', () => detach());
+    });
+  });
+  return wss;
+}

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

@@ -0,0 +1,122 @@
+// KJC-TSK-0816 (MGL-E, ADR 0008) — la ventana única: la terminal REAL del
+// agente embebida en el board; el proceso es el agente interactivo de
+// siempre, con los hooks del Sentinel intactos. Seguridad de la superficie:
+// server solo en loopback, token aleatorio de 128 bits entregado tras el
+// auth del board y comparado en tiempo constante, y catálogo de agentes
+// CERRADO — por la red viaja qué agente, jamás un comando arbitrario.
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+/** Catálogo cerrado: los mismos agentes que kj go sabe lanzar. */
+export const TERMINAL_AGENTS = Object.freeze({
+  claude: { command: 'claude', args: [] },
+  codex: { command: 'codex', args: [] },
+});
+
+const tokenMatches = (expected, given) => {
+  const a = Buffer.from(String(expected));
+  const b = Buffer.from(String(given ?? ''));
+  return a.length === b.length && timingSafeEqual(a, b);
+};
+
+/**
+ * Gestor de LA sesión de terminal del board (singleton por diseño: una
+ * conversación por board acota la superficie; multi-terminal queda fuera
+ * del alcance del ADR).
+ *
+ * @param {Object} deps
+ * @param {(command: string, args: string[], opts: object) => object} deps.spawnPty
+ *   Factoría del pty (node-pty.spawn en producción; fake en tests).
+ * @param {string} deps.cwd Directorio del proyecto donde vive el agente.
+ * @param {Record<string, string|undefined>} [deps.env]
+ * @param {string} [deps.promptArg] Prompt inicial del agente (kj go --window
+ *   lo pasa por env al daemon) — SIEMPRE del lado servidor, jamás de la red.
+ */
+export function createTerminalManager({ spawnPty, cwd, env = process.env, promptArg }) {
+  /** @type {{termId: string, token: string, pty: object, subscribers: Set<Function>, buffer: string[]} | null} */
+  let session = null;
+
+  const requireSession = (termId, token) => {
+    if (!session || session.termId !== termId) {
+      throw new Error('terminal: no hay sesión viva con ese id.');
+    }
+    if (!tokenMatches(session.token, token)) {
+      throw new Error('terminal: token inválido.');
+    }
+    return session;
+  };
+
+  return {
+    /** Arranca (o devuelve) LA sesión — reutilizar la viva evita que cada
+     *  recarga multiplique agentes. @param {{agent: string}} params */
+    start({ agent }) {
+      if (session) return { termId: session.termId, token: session.token, reused: true };
+      // hasOwn: sin él, "constructor"/"__proto__" indexarían el prototipo.
+      const spec = Object.hasOwn(TERMINAL_AGENTS, agent) ? TERMINAL_AGENTS[agent] : null;
+      if (!spec) {
+        throw new Error(
+          `terminal: agente "${agent}" fuera del catálogo (${Object.keys(TERMINAL_AGENTS).join(', ')}).`,
+        );
+      }
+      // CLAUDECODE fuera: un Claude anidado se niega a arrancar con ella
+      // (la misma peculiaridad que ya maneja kj go).
+      const { CLAUDECODE: _omit, ...cleanEnv } = env;
+      const args = promptArg ? [...spec.args, promptArg] : spec.args;
+      const pty = spawnPty(spec.command, args, {
+        name: 'xterm-256color',
+        cols: 120,
+        rows: 32,
+        cwd,
+        env: cleanEnv,
+      });
+      const current = {
+        termId: `term-${randomBytes(8).toString('hex')}`,
+        token: randomBytes(16).toString('hex'),
+        pty,
+        subscribers: new Set(),
+        buffer: [],
+      };
+      pty.onData((data) => {
+        // Búfer corto para que una reconexión no arranque en negro.
+        current.buffer.push(data);
+        if (current.buffer.length > 200) current.buffer.shift();
+        for (const send of current.subscribers) send(data);
+      });
+      pty.onExit(() => {
+        for (const send of current.subscribers) send('\r\n[la sesión del agente terminó]\r\n');
+        // El exit tardío de un pty viejo no debe anular una sesión nueva.
+        if (session === current) session = null;
+      });
+      session = current;
+      return { termId: current.termId, token: current.token, reused: false };
+    },
+
+    /**
+     * Conecta un receptor de salida. Devuelve el detach; soltar la
+     * conexión NO mata el pty — el agente sigue y se puede volver.
+     */
+    attach({ termId, token, send }) {
+      const s = requireSession(termId, token);
+      for (const chunk of s.buffer) send(chunk);
+      s.subscribers.add(send);
+      return () => s.subscribers.delete(send);
+    },
+
+    write({ termId, token, data }) {
+      requireSession(termId, token).pty.write(data);
+    },
+
+    resize({ termId, token, cols, rows }) {
+      requireSession(termId, token).pty.resize(cols, rows);
+    },
+
+    stop({ termId, token }) {
+      const s = requireSession(termId, token);
+      s.pty.kill();
+      session = null;
+    },
+
+    alive() {
+      return session ? { termId: session.termId } : null;
+    },
+  };
+}

package/scripts/install-binary.ps1

@@ -62,7 +62,10 @@ try {
       Write-Host "kj-install: Node $(& node --version) found — installing via npm (full product)..."
       & npm install -g (Get-NpmPkg)
       if ($LASTEXITCODE -ne 0) { throw "npm install failed (exit $LASTEXITCODE)." }
-      Write-Host "kj-install: installed. Run 'kj doctor' next, then 'kj install-tools' to complete the whole stack."
+      Write-Host ""
+      Write-Host "  Listo. Ahora escribe:  kj go"
+      Write-Host ""
+      Write-Host "  (avanzado: 'kj doctor' revisa la instalacion, 'kj install-tools' completa el stack)"
       return
     }
 
@@ -137,7 +140,10 @@ try {
     Add-UserPath $installDir
     $installed = (& (Join-Path $installDir "kj.cmd") --version) 2>$null
     Write-Host "kj-install: installed kj $installed (full product) — kj at $(Join-Path $installDir 'kj.cmd')"
-    Write-Host "kj-install: next — run 'kj doctor', then 'kj install-tools' to complete the whole stack."
+    Write-Host ""
+    Write-Host "  Listo. Ahora escribe:  kj go"
+    Write-Host ""
+    Write-Host "  (avanzado: 'kj doctor' revisa la instalacion, 'kj install-tools' completa el stack)"
     return
   }
 
@@ -168,7 +174,10 @@ try {
   Add-UserPath $installDir
   $installed = (& $dest --version) 2>$null
   Write-Host "kj-install: installed standalone kj $installed to $dest"
-  Write-Host "kj-install: next — run 'kj doctor'. For the full product later: re-run without KJ_STANDALONE."
+  Write-Host ""
+  Write-Host "  Listo. Ahora escribe:  kj go"
+  Write-Host ""
+  Write-Host "  (avanzado: 'kj doctor' revisa la instalacion; para el producto completo, re-ejecuta sin KJ_STANDALONE)"
 } finally {
   Remove-Item -Path $tmp -Recurse -Force -ErrorAction SilentlyContinue
 }

package/scripts/install-binary.sh

@@ -71,7 +71,11 @@ if [ "$MODE" = "full" ]; then
   if node_ok; then
     echo "kj-install: Node $(node --version) found — installing via npm (full product)..."
     npm install -g "$(npm_pkg)" || die "npm install failed. If it was a permissions error, set a user prefix (npm config set prefix ~/.local) and re-run."
-    echo "kj-install: installed $(kj --version 2>/dev/null || echo karajan-code). Run 'kj doctor' next."
+    echo "kj-install: installed $(kj --version 2>/dev/null || echo karajan-code)."
+    echo ""
+    echo "  Listo. Ahora escribe:  kj go"
+    echo ""
+    echo "  (avanzado: 'kj doctor' revisa la instalacion, 'kj install-tools' completa el stack)"
     exit 0
   fi
 
@@ -125,7 +129,10 @@ if [ "$MODE" = "full" ]; then
   installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
   echo "kj-install: installed kj ${installed} (full product) — kj at ${INSTALL_DIR}/kj"
   path_hint "$INSTALL_DIR"
-  echo "kj-install: next — run 'kj doctor', then 'kj install-tools' to complete the whole stack."
+  echo ""
+  echo "  Listo. Ahora escribe:  kj go"
+  echo ""
+  echo "  (avanzado: 'kj doctor' revisa la instalacion, 'kj install-tools' completa el stack)"
   exit 0
 fi
 
@@ -156,4 +163,7 @@ fi
 installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
 echo "kj-install: installed standalone kj ${installed} to ${INSTALL_DIR}/kj"
 path_hint "$INSTALL_DIR"
-echo "kj-install: next — run 'kj doctor'. For the full product later: re-run this installer without --standalone."
+echo ""
+echo "  Listo. Ahora escribe:  kj go"
+echo ""
+echo "  (avanzado: 'kj doctor' revisa la instalacion; para el producto completo, re-ejecuta sin --standalone)"

package/src/cli/advanced-commands.js

@@ -7,6 +7,7 @@
 
 /** The few commands a newcomer needs. Shown in `kj --help`. */
 export const CORE_COMMANDS = [
+  "go",
   "start",
   "init",
   "run",

package/src/cli/register-meta.js

@@ -4,6 +4,7 @@ import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
 import { startCommand } from "../commands/start.js";
+import { goCommand } from "../commands/go.js";
 import { identityCommand } from "../commands/identity.js";
 import { policyCommand } from "../commands/policy.js";
 import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
@@ -148,6 +149,18 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // MGL-A (KJC-TSK-0808): the muggle launcher — one command, at most one
+  // question, and the person lands inside a governed conversation.
+  program
+    .command("go")
+    .description("Arranca Karajan sin saber nada: detecta tu agente, prepara el proyecto, abre el tablero y te deja en la conversación")
+    .option("--window", "La ventana única (ADR 0008): la conversación vive DENTRO del tablero del navegador")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "go", flags, async ({ config, logger }) => {
+        await goCommand({ config, logger, flags });
+      });
+    });
+
   program
     .command("start")
     .description("Single entry point: assess the project and recommend the next step")

package/src/commands/board.js

@@ -87,8 +87,23 @@ async function findAvailablePort(desiredPort, maxTries = 10) {
  * @returns {string}
  */
 export function buildBoardUrl(port, projectSlug) {
-  const base = `http://localhost:${port}`;
-  return projectSlug ? `${base}/#board/${projectSlug}` : base;
+  return projectSlug ? boardUrl(port, `/#board/${projectSlug}`) : boardUrl(port);
+}
+
+/**
+ * Base board URL plus an optional absolute path (query and/or hash) —
+ * `kj go` opens `/?maggle=1` so the frontend renders in plain language
+ * (KJC-TSK-0810). A relative path is a caller bug, not something to fix
+ * up silently.
+ * @param {number} port
+ * @param {string} [path]
+ * @returns {string}
+ */
+export function boardUrl(port, path = "") {
+  if (path && !path.startsWith("/")) {
+    throw new Error(`board path must start with "/": ${path}`);
+  }
+  return `http://localhost:${port}${path}`;
 }
 
 /**
@@ -368,7 +383,7 @@ export function renderBoardBanner({ url, status, projectName }) {
   return ["", rule, ...content, rule, ""].join("\n");
 }
 
-export async function boardCommand({ action = "start", port = 4000, bind = "127.0.0.1", logger }) {
+export async function boardCommand({ action = "start", port = 4000, bind = "127.0.0.1", logger, path }) {
   switch (action) {
     case "start": {
       let result;
@@ -422,7 +437,7 @@ export async function boardCommand({ action = "start", port = 4000, bind = "127.
         logger.info("HU Board is not running. Starting it first...");
         await startBoard(port);
       }
-      const url = `http://localhost:${port}`;
+      const url = boardUrl(port, path);
       // eslint-disable-next-line import-x/no-unresolved -- optional peer; the .catch handles its absence
       const { default: open } = await import("open").catch(() => ({ default: null }));
       if (open) {

package/src/commands/go.js

@@ -0,0 +1,139 @@
+/**
+ * `kj go` (MGL-A, KJC-TSK-0808, epic KJC-PCS-0084) — the muggle launcher.
+ * One command for a person with no computing background: detect their agents,
+ * ask AT MOST one question, prepare the project silently, open the board, and
+ * leave them inside a conversation that already knows the method. What cannot
+ * be hidden is said honestly: the agent's account and login are THEIRS — kj
+ * never touches credentials. Everything is injectable so tests spawn nothing.
+ */
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { checkBinary } from "../utils/agent-detect.js";
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
+import { envInstallCommand } from "./env.js";
+import { boardCommand } from "./board.js";
+// The interactive launchers a muggle can live inside (v1: the two the epic
+// names). Auth heuristics are the same cheap file checks reviewer-fallback
+// uses: menu signal, never a spawned process.
+export const MAGGLE_AGENTS = [
+  { name: "claude", label: "Claude Code (Anthropic)", authPaths: [".claude.json", ".claude"], install: "npm install -g @anthropic-ai/claude-code", login: "claude   (sigue el enlace de inicio de sesión que te muestre)" },
+  { name: "codex", label: "Codex (OpenAI)", authPaths: [".codex/auth.json"], install: "npm install -g @openai/codex", login: "codex login" },
+];
+export async function detectMaggleAgents({ home = os.homedir(), checkBin = checkBinary } = {}) {
+  return Promise.all(
+    MAGGLE_AGENTS.map(async (a) => {
+      let installed = false;
+      try { installed = (await checkBin(a.name)).ok; } catch { /* not installed */ }
+      const authenticated = installed && a.authPaths.some((p) => existsSync(path.join(home, p)));
+      return { ...a, installed, authenticated };
+    }),
+  );
+}
+/** The session's opening prompt — SHORT and in plain language. The full
+ * playbook already lives in the agent files env-install wrote; duplicating it
+ * here would dilute it. This prompt sets the tone for a muggle. */
+export function buildGoPrompt() {
+  return [
+    "Arrancas dentro de un proyecto gobernado por Karajan (las reglas del método ya están en los ficheros de agente de este proyecto: síguelas siempre).",
+    "La persona que te habla puede no saber programar. Habla en lenguaje llano: sin jerga, sin siglas sin explicar, y resume cada resultado en una o dos frases antes del detalle.",
+    "Antes de cambios importantes, di en llano qué vas a hacer y qué pasará. Si algo falla, explica qué pasó y cuál es el siguiente paso — nunca un volcado de error a secas.",
+    "El tablero del proyecto está abierto en su navegador: cuando termines algo, recuérdale que puede verlo ahí.",
+    "Empieza presentándote en dos frases y preguntando qué quiere construir o cambiar hoy.",
+  ].join("\n");
+}
+async function defaultPrepare({ config, logger }) {
+  await envInstallCommand({ config, logger, flags: { yes: true } });
+}
+export async function defaultBoard({ config, logger, runBoard = boardCommand, openPath = "/?maggle=1" }) {
+  const port = config.hu_board?.port || 4000;
+  await runBoard({ action: "start", port, bind: "127.0.0.1", logger });
+  // /?maggle=1 switches the frontend to plain language (KJC-TSK-0810) —
+  // the muggle's window opens already speaking their language. With
+  // &window=1 (KJC-TSK-0816) the conversation itself lives IN the board.
+  await runBoard({ action: "open", port, bind: "127.0.0.1", path: openPath, logger });
+}
+function defaultLaunch(agent, prompt) {
+  // Interactive session: the muggle LIVES here. CLAUDECODE is stripped so a
+  // nested Claude does not refuse to start (the known subprocess quirk).
+  const { CLAUDECODE: _omit, ...env } = process.env;
+  return new Promise((resolvePromise) => {
+    const child = spawn(agent.name, [prompt], { stdio: "inherit", env });
+    child.on("exit", (code) => resolvePromise(code ?? 0));
+    child.on("error", (err) => {
+      console.error(`No se pudo arrancar ${agent.label}: ${err.message}`);
+      resolvePromise(1);
+    });
+  });
+}
+export async function goCommand({ config = {}, logger = console, flags = {}, deps = {} } = {}) {
+  const projectDir = config.projectDir || process.cwd();
+  const agents = await (deps.detect ?? detectMaggleAgents)();
+  const ready = agents.filter((a) => a.installed && a.authenticated);
+  const needLogin = agents.filter((a) => a.installed && !a.authenticated);
+  if (ready.length === 0) {
+    if (needLogin.length > 0) {
+      logger.error?.("Tienes el agente instalado pero falta iniciar sesión — eso solo puedes hacerlo tú (la cuenta es tuya; Karajan nunca toca tus credenciales):");
+      for (const a of needLogin) logger.error?.(`  ${a.label}:  ${a.login}`);
+      logger.error?.("Cuando hayas iniciado sesión, vuelve a escribir: kj go");
+    } else {
+      logger.error?.("Karajan trabaja con un agente de IA que aún no tienes instalado. Elige uno, instálalo con su comando, e inicia sesión con TU cuenta (la cuenta es tuya):");
+      for (const a of agents) logger.error?.(`  ${a.label}:  ${a.install}`);
+      logger.error?.("Después, vuelve a escribir: kj go");
+    }
+    process.exitCode = 1;
+    return 1;
+  }
+  let chosen = ready[0];
+  if (ready.length > 1) {
+    const ask = deps.ask ?? createCliAskQuestion({ flags });
+    const answer = await ask("¿Con cuál de tus agentes quieres trabajar?", { options: ready.map((a) => a.name), default: ready[0].name });
+    chosen = ready.find((a) => a.name === String(answer).trim()) ?? ready[0];
+  }
+  logger.info?.(`Trabajarás con ${chosen.label}.`);
+  // Prepare ONCE: decisions already taken are never re-asked.
+  if (!existsSync(path.join(projectDir, ".karajan", "review-gate"))) {
+    logger.info?.("Preparando tu proyecto (solo la primera vez)…");
+    await (deps.prepare ?? defaultPrepare)({ config, logger });
+  }
+  const prompt = (deps.prompt ?? buildGoPrompt)();
+  // --window (MGL-E, ADR 0008): la conversación vive DENTRO del board — el
+  // daemon hereda por env (HU_BOARD_TERMINAL_CWD/AGENT/PROMPT) el cwd, el
+  // agente elegido y el prompt inicial, y el pty arranca el agente REAL
+  // (harness intacto). La fase 1 sigue siendo el default: sin el flag,
+  // nada cambia.
+  const windowMode = Boolean(flags.window);
+  if (windowMode) {
+    process.env.HU_BOARD_TERMINAL_CWD = projectDir;
+    process.env.HU_BOARD_TERMINAL_AGENT = chosen.name;
+    process.env.HU_BOARD_TERMINAL_PROMPT = prompt;
+  }
+  // The board is the muggle's window — unless the project turned it off
+  // (hu_board.enabled false is respected: KJC-BUG-0152). A board failure is
+  // said and never stops the conversation from starting.
+  let boardOpened = false;
+  if (config.hu_board?.enabled !== false) {
+    const openPath = windowMode ? "/?maggle=1&window=1" : "/?maggle=1";
+    try {
+      await (deps.board ?? defaultBoard)({ config, logger, openPath });
+      boardOpened = true;
+    } catch (err) {
+      logger.warn?.(`El tablero no pudo abrirse (${err.message}) — la conversación arranca igual.`);
+    }
+  }
+  if (windowMode && boardOpened) {
+    logger.info?.("Tu conversación vive en la ventana del navegador que se acaba de abrir. Si el tablero ya estaba arrancado de antes, reinícialo con kj board stop && kj go --window para que recoja este proyecto.");
+    process.exitCode = 0;
+    return 0;
+  }
+  if (windowMode) {
+    // Sin board no hay ventana: se dice y la conversación arranca en la
+    // terminal — el maggle nunca se queda sin sesión (catch de codex).
+    logger.warn?.("Sin tablero no hay ventana única: abro la conversación aquí mismo.");
+  }
+  logger.info?.("Abriendo tu conversación… (escribe ahí lo que necesites, en tu idioma)");
+  const code = await (deps.launch ?? defaultLaunch)(chosen, prompt);
+  process.exitCode = code;
+  return code;
+}