karajan-code 4.24.0 → 4.26.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.26.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/app.js

@@ -163,6 +163,9 @@ let lastOpenedLog = null;     // { id, label, tailUrl(offset) }
  */
 function navigate(view) {
   currentView = view;
+  // KJC-TSK-0820: going back to the Dashboard unloads the project — it is
+  // the only place where a (different) project gets picked.
+  if (view === 'dashboard' && !scopedProjectSlug) selectedProject = '';
   window.location.hash = selectedProject ? `${view}/${selectedProject}` : view;
 
   // Update active nav button
@@ -179,14 +182,43 @@ function navigate(view) {
  */
 function selectProject(projectId) {
   selectedProject = projectId;
-  document.getElementById('project-select').value = projectId;
   navigate('board');
 }
 
+/**
+ * KJC-TSK-0820 — two-level nav. Which nav bars are visible: the generic
+ * one always; the project sub-bar only while a project is loaded, and
+ * never on the Dashboard (that's where projects get picked). Pure.
+ * @param {string} view
+ * @param {string} projectId
+ * @returns {{ generic: boolean, project: boolean }}
+ */
+function projectNavVisibility(view, projectId) {
+  return { generic: true, project: Boolean(projectId) && view !== 'dashboard' };
+}
+
+/**
+ * Applies projectNavVisibility() to the DOM and stamps the loaded
+ * project's name on the sub-bar.
+ */
+function updateProjectNav() {
+  const bar = document.getElementById('project-nav');
+  if (!bar) return;
+  const visible = projectNavVisibility(currentView, selectedProject).project;
+  bar.hidden = !visible;
+  if (!visible) return;
+  const nameEl = document.getElementById('project-nav-name');
+  nameEl.textContent = projectNameCache[selectedProject] || humaniseProjectName(selectedProject);
+  resolveProjectMeta(selectedProject).then((meta) => {
+    if (meta.name) nameEl.textContent = meta.name;
+  });
+}
+
 /**
  * Renders the current view.
  */
 function render() {
+  updateProjectNav();
   switch (currentView) {
     case 'dashboard': return renderDashboard();
     case 'board': return renderBoard();
@@ -197,46 +229,6 @@ function render() {
   }
 }
 
-/**
- * Populates the project selector dropdown.
- */
-async function populateProjectSelect() {
-  try {
-    const projects = await api('/api/projects');
-    const select = document.getElementById('project-select');
-    // Which project should appear pre-selected? Order:
-    //   1. scopedProjectSlug (URL is /p/<slug>)  — locked, never changes
-    //   2. selectedProject (route state, ej. #board/<slug>)
-    //   3. ""                                    — "All Projects"
-    // PR-D: the previous version cleared innerHTML and never marked
-    // any option as selected, so the dropdown showed "All Projects"
-    // even when scoped to one. handleRoute() set .value separately
-    // BUT the value was lost in the race because the matching option
-    // didn't exist yet when handleRoute ran. Setting .selected on
-    // the option directly avoids the race.
-    const desired = scopedProjectSlug || selectedProject || '';
-    select.innerHTML = '';
-    const all = document.createElement('option');
-    all.value = '';
-    all.textContent = 'All Projects';
-    if (desired === '') all.selected = true;
-    select.appendChild(all);
-    for (const p of projects) {
-      const opt = document.createElement('option');
-      opt.value = p.id;
-      opt.textContent = p.name || p.id;
-      if (p.id === desired) opt.selected = true;
-      select.appendChild(opt);
-    }
-    // Final guard: if `desired` did not match any rendered option
-    // (project not on the board yet), still set the value so
-    // handleRoute's expectation holds.
-    if (desired) select.value = desired;
-  } catch {
-    // Silently fail — project list will be empty
-  }
-}
-
 /**
  * Parses the hash route and renders.
  */
@@ -248,13 +240,15 @@ function handleRoute() {
   // In scoped mode the project is locked — the hash controls the view
   // only. `board/<slug>` becomes `board` and the slug stays fixed.
   currentView = parts[0] || 'board';
-  selectedProject = scopedProjectSlug || parts[1] || '';
+  // Dashboard never carries a loaded project (KJC-TSK-0820): it is the
+  // project picker, so a `#dashboard/<slug>` deep-link drops the slug.
+  selectedProject = scopedProjectSlug
+    || (currentView === 'dashboard' ? '' : parts[1] || '');
 
   document.querySelectorAll('.nav-btn').forEach((btn) => {
     btn.classList.toggle('active', btn.dataset.view === currentView);
   });
 
-  document.getElementById('project-select').value = selectedProject;
   render();
 }
 

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>
@@ -20,21 +21,12 @@
       </div>
     </div>
     <nav class="header__nav">
-      <button class="nav-btn active" data-view="board" title="Kanban board: every HU of the selected project, grouped by status (Pending → Certified → Done). Click an HU card to expand the detail panel.">Board</button>
-      <button class="nav-btn" data-view="graph" title="Dependency graph of the selected project's HUs — who blocks whom. Useful before scheduling work.">Graph</button>
-      <button class="nav-btn" data-view="dashboard" title="Per-project landing: stats grid + project list. Click a project card to focus the kanban / graph on that project.">Dashboard</button>
-      <button class="nav-btn" data-view="sessions" title="Every kj run that has touched the board, newest first. Filter by project; click a session to inspect its iterations, commits and checkpoints.">Sessions</button>
-      <button class="nav-btn" data-view="governance" title="The acta: policy rules by friction, the hash-chained decision log and its anchor, standing exceptions with owner and expiry, renewals and signals.">Governance</button>
-      <a class="nav-btn" href="/pipeline.html" title="Live observability of pipeline runs (Karajan v2.7+): stage timings, agent calls, decision logs.">Pipeline</a>
-      <a class="nav-btn" href="/rag.html" title="RAG retrieval-quality dashboard: chunk counts, embedder provider, db size.">RAG</a>
-      <a class="nav-btn" href="/wiki.html" title="Search the per-project QMD semantic wiki (docs, plans, reviews).">Wiki</a>
-      <select class="project-select" id="project-select">
-        <option value="">All Projects</option>
-      </select>
+      <button class="nav-btn active" data-view="dashboard" title="Per-project landing: stats grid + project list. Click a project card to load that project — its views appear in the project bar below.">Dashboard</button>
       <div class="header__controls">
         <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>
@@ -42,6 +34,20 @@
     </nav>
   </header>
 
+  <!-- KJC-TSK-0820: project sub-bar. Hidden until a project is loaded from
+       the dashboard; every entry here shows data of THAT project. Switching
+       projects = back to Dashboard (the select is gone on purpose). -->
+  <nav class="project-nav" id="project-nav" hidden>
+    <span class="project-nav__name" id="project-nav-name"></span>
+    <button class="nav-btn nav-btn--project" data-view="board" title="Kanban board: every HU of the loaded project, grouped by status (Pending → Certified → Done). Click an HU card to expand the detail panel.">Board</button>
+    <button class="nav-btn nav-btn--project" data-view="graph" title="Dependency graph of the loaded project's HUs — who blocks whom. Useful before scheduling work.">Graph</button>
+    <button class="nav-btn nav-btn--project" data-view="sessions" title="Every kj run of the loaded project, newest first. Click a session to inspect its iterations, commits and checkpoints.">Sessions</button>
+    <button class="nav-btn nav-btn--project" data-view="governance" title="The acta: policy rules by friction, the hash-chained decision log and its anchor, standing exceptions with owner and expiry, renewals and signals.">Governance</button>
+    <a class="nav-btn nav-btn--project" href="/pipeline.html" title="Live observability of pipeline runs (Karajan v2.7+): stage timings, agent calls, decision logs.">Pipeline</a>
+    <a class="nav-btn nav-btn--project" href="/rag.html" title="RAG retrieval-quality dashboard: chunk counts, embedder provider, db size.">RAG</a>
+    <a class="nav-btn nav-btn--project" href="/wiki.html" title="Search the per-project QMD semantic wiki (docs, plans, reviews).">Wiki</a>
+  </nav>
+
   <main class="main" id="app">
     <div class="loading">
       <div class="loading__spinner"></div>
@@ -67,6 +73,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/styles.css

@@ -124,20 +124,36 @@ a:hover {
   border-color: var(--accent-purple);
 }
 
-.project-select {
-  background: var(--bg-primary);
-  border: 1px solid var(--border);
-  color: var(--text-primary);
-  padding: 6px 12px;
-  border-radius: var(--radius-sm);
-  font-family: var(--font-sans);
+/* ---- Project sub-bar (KJC-TSK-0820) ----
+ * Second nav level, only visible while a project is loaded. Teal, not
+ * purple: project-scoped actions must read as a different tier from the
+ * generic header. */
+.project-nav {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  flex-wrap: wrap;
+  padding: 8px 24px;
+  background: var(--bg-card);
+  border-bottom: 1px solid var(--border);
+}
+
+.project-nav[hidden] {
+  display: none;
+}
+
+.project-nav__name {
+  color: var(--accent-teal);
+  font-weight: 600;
   font-size: 0.85rem;
-  cursor: pointer;
+  margin-right: 8px;
 }
 
-.project-select:focus {
-  outline: none;
-  border-color: var(--accent-purple);
+.nav-btn--project:hover,
+.nav-btn--project.active {
+  background: var(--accent-teal-dim);
+  color: var(--bg-primary);
+  border-color: var(--accent-teal-dim);
 }
 
 .header__controls {
@@ -955,13 +971,12 @@ a:hover {
 /* ---- Scoped-project mode (URL: /p/<slug>) ---- */
 /* Hide multi-project affordances when the board is scoped to a single
  * project — the page only makes sense as "this project's Kanban".
- * Multi-project UX (the All Projects selector, the Sessions tab, the
+ * Multi-project UX (the Dashboard picker, the Sessions tab, the
  * Pipeline page link) adds noise and broke the user's mental model
  * during dogfooding. */
-body.scoped-mode .project-select,
 body.scoped-mode .nav-btn[data-view="sessions"],
 body.scoped-mode .nav-btn[data-view="dashboard"],
-body.scoped-mode .header__nav a[href="/pipeline.html"] {
+body.scoped-mode a[href="/pipeline.html"] {
   display: none;
 }
 

package/packages/hu-board/public/utils/graph-view.js

@@ -99,7 +99,7 @@ async function renderGraph() {
   if (!selectedProject) {
     app.innerHTML = renderEmptyState(
       'Pick a project first',
-      'The dependency graph is per-project. Choose one in the dropdown above and I will draw its HU DAG.'
+      'The dependency graph is per-project. Pick one on the Dashboard and I will draw its HU DAG.'
     );
     return;
   }

package/packages/hu-board/public/utils/init-listeners.js

@@ -6,8 +6,7 @@
 // the boot block run.
 //
 // Globals consumed from earlier scripts / app.js:
-//   - navigate(), render(), handleRoute(),
-//     populateProjectSelect()         (app.js)
+//   - navigate(), render(), handleRoute() (app.js)
 //   - showCommandLauncher(),
 //     nextIsTestValue()               (utils/command-launcher.js)
 //   - showHelp(), showConfirm(),
@@ -32,13 +31,6 @@ document.querySelectorAll('.nav-btn').forEach((btn) => {
   btn.addEventListener('click', () => navigate(btn.dataset.view));
 });
 
-// Project selector
-document.getElementById('project-select').addEventListener('change', (e) => {
-  selectedProject = e.target.value;
-  window.location.hash = selectedProject ? `${currentView}/${selectedProject}` : currentView;
-  render();
-});
-
 // Sync button — re-scan disk for new batches
 document.getElementById('sync-btn').addEventListener('click', async () => {
   const btn = document.getElementById('sync-btn');
@@ -46,7 +38,6 @@ document.getElementById('sync-btn').addEventListener('click', async () => {
   btn.textContent = '⏳';
   try {
     await fetch('/api/sync', { method: 'POST' });
-    await populateProjectSelect();
     render();
   } catch { /* ignore */ }
   btn.textContent = '🔄';
@@ -106,7 +97,6 @@ document.addEventListener('click', async (e) => {
     });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
     // Re-render the project list so the badge reflects the new value.
-    await populateProjectSelect();
     render();
   } catch (err) {
     await showError(err.message, { title: 'Failed to update is_test' });
@@ -130,7 +120,6 @@ document.addEventListener('click', async (e) => {
   try {
     const res = await fetch(`/api/projects/${encodeURIComponent(projectId)}`, { method: 'DELETE' });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    await populateProjectSelect();
     render();
   } catch (err) {
     await showError(err.message, { title: 'Failed to delete project' });
@@ -161,7 +150,6 @@ startStandbyPolling();
 
 // Initial load — sync disk data first so new batches are visible
 triggerSync().then(() => {
-  populateProjectSelect();
   handleRoute();
   subscribeToServerEvents();
 });
@@ -174,7 +162,6 @@ triggerSync().then(() => {
 refreshInterval = setInterval(async () => {
   if (document.getElementById('modal-backdrop').classList.contains('hidden')) {
     await triggerSync();
-    await populateProjectSelect();
     await smartRefresh(null);
   }
 }, 60_000);

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

@@ -29,7 +29,7 @@ const MAGGLE_LABELS = {
   'nav.board': 'Tablero',
   'nav.dashboard': 'Proyectos',
   'nav.more': 'Más',
-  'picker.hint': 'Elige un proyecto para ver su tablero. Puedes cambiar de proyecto arriba a la derecha.',
+  'picker.hint': 'Elige un proyecto para ver su tablero. Para cambiar de proyecto, vuelve a «Proyectos».',
   'picker.project': 'proyecto',
   'launcher.title': '📝 Pedir trabajo a Karajan',
   'launcher.planLabel': '📝 Pedir trabajo nuevo',
@@ -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.',
@@ -83,7 +86,10 @@ function applyMaggleChrome() {
   if (!nav) return;
   const KEEP = { board: MAGGLE_LABELS['nav.board'], dashboard: MAGGLE_LABELS['nav.dashboard'] };
   const advanced = [];
-  for (const btn of nav.querySelectorAll('.nav-btn')) {
+  // KJC-TSK-0820: nav buttons live in TWO bars now — the generic header
+  // and the project sub-bar (#project-nav). Fold both; Tablero stays in
+  // the sub-bar so it only shows once a project is loaded.
+  for (const btn of document.querySelectorAll('.header__nav .nav-btn, .project-nav .nav-btn')) {
     const view = btn.dataset.view;
     if (view && KEEP[view]) {
       btn.title = `${btn.textContent.trim()} — ${btn.title}`;
@@ -115,8 +121,11 @@ function applyMaggleChrome() {
       expert.remove();
     }
   });
-  // After the LAST nav button, so the plain row reads Tablero | Proyectos | Más.
-  advanced.at(-1).after(more);
+  // In the GENERIC bar (before the control buttons), so the plain header
+  // reads Proyectos | Más and the sub-bar keeps only Tablero.
+  const controls = nav.querySelector('.header__controls');
+  if (controls) controls.before(more);
+  else nav.append(more);
 }
 
 if (typeof document !== 'undefined' && document.addEventListener) {

package/packages/hu-board/public/utils/project-actions.js

@@ -11,8 +11,7 @@
 //   - formatDuration()            (utils/formatters.js)
 //   - projectNameCache            (mutable in app.js — assignment crosses
 //                                  scripts transparently)
-//   - populateProjectSelect()     (app.js)
-//   - renderBoard()               (app.js)
+//   - render()                    (app.js)
 
 /**
  * PR-G: rename a project from the header ✎ button. Opens a small
@@ -67,11 +66,11 @@ window.renameProjectModal = function renameProjectModal(projectId, currentName)
         return;
       }
       // Update the cached display name + refresh the board so the
-      // header, dropdown and project picker all show the new value.
+      // header, project bar and project picker all show the new value.
       projectNameCache[projectId] = newName;
       try { dlg.close(); } catch { /* ignore */ }
-      await populateProjectSelect();
-      await renderBoard();
+      // render() (not renderBoard()) so the project bar name refreshes too.
+      await render();
     } catch (err) {
       errorEl.style.display = 'block';
       errorEl.textContent = err.message || String(err);

package/packages/hu-board/public/utils/project-picker-view.js

@@ -74,7 +74,7 @@ async function renderProjectPicker() {
       <span class="section-header__count">${sorted.length} ${maggleText('picker.project', 'project')}${sorted.length === 1 ? '' : 's'}</span>
     </div>
     <p style="padding:8px 4px 16px;color:var(--text-muted);font-size:0.9rem">
-      ${maggleText('picker.hint', 'Pick a project to see its kanban. Use the project selector in the header to switch later.')}
+      ${maggleText('picker.hint', 'Pick a project to see its kanban. To switch later, go back to the Dashboard.')}
     </p>
     <div style="display:grid;grid-template-columns:repeat(auto-fill, minmax(320px, 1fr));gap:14px">
       ${sorted.map((p) => {

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/db.js

@@ -377,6 +377,19 @@ export function ensureDb() {
  * @param {{ id: string, name?: string, first_seen?: string, last_activity?: string, total_stories?: number }} project
  */
 export function upsertProject(project) {
+  // KJC-BUG-0163 — the iron rule: a project NAME is unique on the dashboard.
+  // Two projects with the same visible name are indistinguishable in the
+  // picker; registering the second fails LOUD instead of blending in.
+  if (project.name) {
+    const clash = getDb()
+      .prepare('SELECT id FROM projects WHERE name = ? AND id != ?')
+      .get(project.name, project.id);
+    if (clash) {
+      throw new Error(
+        `board: el nombre "${project.name}" ya pertenece al proyecto "${clash.id}" — dos proyectos no pueden llamarse igual (KJC-BUG-0163); renombra el plan o el directorio de "${project.id}"`,
+      );
+    }
+  }
   // is_shared (KJC-PRP-0002 PR3) is set by sync when a plan came from
   // `.karajan-shared/`. COALESCE with the existing column keeps the badge
   // once it's been promoted — a second non-shared plan won't unset it.

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,