karajan-code 4.24.0 → 4.25.0

package/README.md

@@ -65,7 +65,7 @@ Already installed and just want to work — even with no computing background? O
 kj go
 ```
 
-It detects your agent (Claude Code or Codex; asks which one only if you have both), prepares the project silently the first time, opens the board in your browser, and drops you into a conversation that already follows the method. Your agent account and login stay yours — kj never touches credentials.
+It detects your agent (Claude Code or Codex; asks which one only if you have both), prepares the project silently the first time, opens the board in your browser, and drops you into a conversation that already follows the method. Your agent account and login stay yours — kj never touches credentials. Prefer everything in ONE browser window? `kj go --window` embeds the agent's real terminal inside the board (loopback-only, single-session token).
 
 Requires git and at least one AI agent CLI — two enables cross-AI review; three enables arbitration. The npm route is `npm install -g @karajan-family/code` (published as `karajan-code` before joining the scope; the legacy name still installs the same versions). All install routes (npm, binaries, brew, Python wrapper) in the [install docs](https://karajancode.com/docs/v4/install/).
 

package/package.json

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

package/packages/hu-board/package.json

@@ -13,13 +13,16 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "karajan-core": "*",
+    "@xterm/xterm": "^6.0.0",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0",
-    "js-yaml": "^4.2.0"
+    "js-yaml": "^4.2.0",
+    "karajan-core": "*",
+    "node-pty": "^1.1.0",
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "supertest": "^7.1.0",

package/packages/hu-board/public/index.html

@@ -5,6 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Karajan HU Board</title>
   <link rel="stylesheet" href="/styles.css">
+  <link rel="stylesheet" href="/vendor/xterm/css/xterm.css">
   <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><rect width='32' height='32' rx='6' fill='%237c3aed'/><text x='16' y='22' text-anchor='middle' fill='white' font-size='16' font-family='sans-serif' font-weight='bold'>K</text></svg>">
 </head>
 <body>
@@ -35,6 +36,7 @@
         <button class="control-btn" id="help-btn" title="What does each view do? Quick reference for Board / Graph / Dashboard / Sessions / Pipeline.">?</button>
         <button class="control-btn" id="config-btn" title="Configurar Karajan (modelos, agentes, tope de iteraciones, …)">⚙</button>
         <button class="control-btn" id="commands-btn" title="Launch a Karajan CLI command (kj plan, kj architect, kj clean…)">⚡</button>
+        <button class="control-btn" id="conversation-btn" title="Conversación con tu agente — la terminal real, dentro del board (ADR 0008)" onclick="openConversationPanel()">💬</button>
         <button class="control-btn" id="restart-btn" title="Restart the HU Board server (preserves URL, the page reconnects automatically)">🔁</button>
         <button class="control-btn" id="sync-btn" title="Re-scan disk for new batches">🔄</button>
         <button class="control-btn" id="force-refresh-btn" title="Force a clean reload — wipes browser caches and reloads. Use when the UI looks stale and a normal refresh isn't fixing it." onclick="window.forceRefresh()">🧹</button>
@@ -67,6 +69,8 @@
   <script src="/utils/preflight-view.js"></script>
   <script src="/utils/plan-rollup-view.js"></script>
   <script src="/utils/log-panel.js"></script>
+  <script src="/vendor/xterm/lib/xterm.js"></script>
+  <script src="/utils/terminal-panel.js"></script>
   <script src="/utils/hu-actions.js"></script>
   <script src="/utils/project-actions.js"></script>
   <script src="/utils/story-edit-form.js"></script>

package/packages/hu-board/public/utils/maggle-mode.js

@@ -39,6 +39,9 @@ const MAGGLE_LABELS = {
   'launcher.cancel': 'Cancelar',
   'launcher.more': 'Más opciones…',
   'launcher.confirm': 'Voy a convertir tu petición en tareas del tablero. Tardará unos minutos y podrás seguir la actividad en esta ventana. ¿Sigo?',
+  'conversation.title': 'Habla con tu agente',
+  'conversation.hide': 'Ocultar — la conversación sigue viva',
+  'conversation.end': 'Terminar la sesión del agente',
   'log.label': 'Actividad',
   'log.connecting': 'conectando…',
   'log.footer': 'Cerrar esta ventana NO detiene el trabajo: sigue en marcha. Vuelve a abrirla con el botón «📜 Ver actividad» del tablero.',

package/packages/hu-board/public/utils/terminal-panel.js

@@ -0,0 +1,132 @@
+// KJC-TSK-0816 (MGL-E, ADR 0008) — el panel «Conversación»: la terminal
+// REAL del agente dentro del board. Script clásico, como el resto.
+//
+// Globals: Terminal (de /vendor/xterm), esc(), maggleText(), showError().
+// El token del pty llega de /api/terminal/start (tras el auth del board)
+// y viaja al WS como SUBPROTOCOLO, nunca en la URL.
+
+let conversationState = { ws: null, term: null, panel: null, termId: null, token: null, opening: false };
+
+async function openConversationPanel() {
+  if (conversationState.panel && conversationState.dead) {
+    // La conexión murió (agente terminado o red): reabrir = sesión fresca.
+    conversationState.panel.remove();
+    conversationState = { ws: null, term: null, panel: null, termId: null, token: null, opening: false };
+  }
+  if (conversationState.panel) {
+    conversationState.panel.style.display = 'flex';
+    conversationState.term?.focus();
+    return;
+  }
+  // Un doble clic (o ?window=1 + clic) no debe abrir dos sesiones.
+  if (conversationState.opening) return;
+  conversationState.opening = true;
+  let started;
+  try {
+    const res = await fetch('/api/terminal/start', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      // Sin agente en el body: decide el servidor (kj go --window fija el
+      // elegido por env; sin él, claude).
+      body: JSON.stringify({}),
+    });
+    started = await res.json();
+    if (!res.ok) throw new Error(started.error || `HTTP ${res.status}`);
+  } catch (err) {
+    conversationState.opening = false;
+    await showError(err.message, { title: 'La conversación no pudo arrancar' });
+    return;
+  }
+  conversationState.opening = false;
+  conversationState.termId = started.termId;
+  conversationState.token = started.token;
+
+  const panel = document.createElement('section');
+  panel.id = 'kj-conversation-panel';
+  panel.style.cssText = [
+    'position:fixed', 'top:0', 'right:0', 'bottom:0',
+    'width:min(720px, 55vw)', 'display:flex', 'flex-direction:column',
+    'background:#0b0b0c', 'border-left:1px solid var(--border)',
+    'box-shadow:-12px 0 40px rgba(0,0,0,0.45)', 'z-index:9998',
+  ].join(';');
+  panel.innerHTML = `
+    <header style="display:flex;align-items:center;justify-content:space-between;padding:8px 12px;
+                   background:var(--bg-primary);border-bottom:1px solid var(--border);flex-shrink:0">
+      <strong style="color:var(--text)">${esc(maggleText('conversation.title', 'Conversación con tu agente'))}</strong>
+      <div style="display:flex;gap:6px">
+        <button id="conv-hide" type="button" class="control-btn" title="${esc(maggleText('conversation.hide', 'Ocultar — la conversación sigue viva'))}"
+                style="padding:4px 10px;border:1px solid var(--border);background:var(--bg-primary);color:var(--text);border-radius:var(--radius-sm);cursor:pointer">_</button>
+        <button id="conv-end" type="button" class="control-btn" title="${esc(maggleText('conversation.end', 'Terminar la sesión del agente'))}"
+                style="padding:4px 10px;border:1px solid var(--border);background:var(--bg-primary);color:#f87171;border-radius:var(--radius-sm);cursor:pointer">✕</button>
+      </div>
+    </header>
+    <div id="conv-term" style="flex:1 1 auto;min-height:0;padding:6px"></div>
+  `;
+  document.body.appendChild(panel);
+  conversationState.panel = panel;
+
+  const term = new Terminal({
+    convertEol: false,
+    cursorBlink: true,
+    fontFamily: 'JetBrains Mono, monospace',
+    fontSize: 13,
+    theme: { background: '#0b0b0c' },
+  });
+  term.open(panel.querySelector('#conv-term'));
+  conversationState.term = term;
+
+  const proto = location.protocol === 'https:' ? 'wss' : 'ws';
+  const ws = new WebSocket(
+    `${proto}://${location.host}/api/terminal/ws?termId=${encodeURIComponent(started.termId)}`,
+    ['kj-terminal', started.token],
+  );
+  conversationState.ws = ws;
+  ws.onmessage = (e) => term.write(typeof e.data === 'string' ? e.data : '');
+  ws.onclose = () => {
+    conversationState.dead = true;
+    term.write('\r\n[conexión cerrada — vuelve a abrir el panel para reconectar]\r\n');
+  };
+  term.onData((data) => {
+    if (ws.readyState === WebSocket.OPEN) ws.send(data);
+  });
+
+  const sendResize = () => {
+    const el = panel.querySelector('#conv-term');
+    const cols = Math.max(40, Math.floor(el.clientWidth / 8));
+    const rows = Math.max(10, Math.floor(el.clientHeight / 18));
+    term.resize(cols, rows);
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(`\u0000${JSON.stringify({ type: 'resize', cols, rows })}`);
+    }
+  };
+  ws.onopen = () => { sendResize(); term.focus(); };
+  window.addEventListener('resize', sendResize);
+
+  panel.querySelector('#conv-hide').addEventListener('click', () => {
+    panel.style.display = 'none';
+  });
+  panel.querySelector('#conv-end').addEventListener('click', async () => {
+    try {
+      await fetch('/api/terminal/stop', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ termId: conversationState.termId, token: conversationState.token }),
+      });
+    } finally {
+      ws.close();
+      panel.remove();
+      conversationState = { ws: null, term: null, panel: null, termId: null, token: null, opening: false };
+    }
+  });
+}
+
+// kj go --window abre el board con ?window=1: la conversación arranca sola.
+if (typeof document !== 'undefined' && document.addEventListener) {
+  document.addEventListener('DOMContentLoaded', () => {
+    try {
+      if (new URLSearchParams(location.search).get('window') === '1') openConversationPanel();
+    } catch {
+      // Sin soporte de URLSearchParams no hay auto-apertura; el botón queda.
+    }
+  });
+}

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/src/cli/register-meta.js

@@ -154,6 +154,7 @@ export function registerMeta(program, { pkgVersion }) {
   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 });

package/src/commands/go.js

@@ -46,12 +46,13 @@ export function buildGoPrompt() {
 async function defaultPrepare({ config, logger }) {
   await envInstallCommand({ config, logger, flags: { yes: true } });
 }
-export async function defaultBoard({ config, logger, runBoard = boardCommand }) {
+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.
-  await runBoard({ action: "open", port, bind: "127.0.0.1", path: "/?maggle=1", logger });
+  // 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
@@ -96,13 +97,41 @@ export async function goCommand({ config = {}, logger = console, flags = {}, dep
     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) {
-    try { await (deps.board ?? defaultBoard)({ config, logger }); } catch (err) { logger.warn?.(`El tablero no pudo abrirse (${err.message}) — la conversación arranca igual.`); }
+    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.");
   }
-  const prompt = (deps.prompt ?? buildGoPrompt)();
   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;