@jhizzard/termdeck 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # TermDeck
 
-[![Install Smoke](https://github.com/jhizzard/termdeck/workflows/install-smoke/badge.svg)](https://github.com/jhizzard/termdeck/actions/workflows/install-smoke.yml)
+[![CI](https://github.com/jhizzard/termdeck/actions/workflows/ci.yml/badge.svg)](https://github.com/jhizzard/termdeck/actions/workflows/ci.yml)
 
 > **The terminal that remembers what you fixed last month.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"
@@ -39,15 +39,13 @@
     "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1",
     "better-sqlite3": "^12.9.0",
     "chalk": "^5.3.0",
-    "express": "^4.18.2",
-    "open": "^10.0.0",
+    "express": "^5.2.1",
     "pg": "^8.20.0",
-    "uuid": "^13.0.0",
     "ws": "^8.16.0",
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.39.0"
+    "@anthropic-ai/sdk": "^0.96.0"
   },
   "keywords": [
     "terminal",

package/packages/cli/src/index.js

@@ -164,8 +164,8 @@ function reclaimStalePort(port) {
       try { process.kill(parseInt(pid, 10), 'SIGKILL'); } catch (_e) {}
     }
   } else {
-    console.error(`\n  \x1b[31m✗ Port ${port} is in use by a non-TermDeck process (PIDs: ${pids.join(' ')})\x1b[0m`);
-    console.error(`  \x1b[2mTry a different port: termdeck --port ${port + 1}\x1b[0m\n`);
+    process.stderr.write(`\n  \x1b[31m✗ Port ${port} is in use by a non-TermDeck process (PIDs: ${pids.join(' ')})\x1b[0m\n`);
+    process.stderr.write(`  \x1b[2mTry a different port: termdeck --port ${port + 1}\x1b[0m\n\n`);
     process.exit(1);
   }
 }

package/packages/client/public/app.js

@@ -438,6 +438,7 @@
                 <a class="theme-reset" id="theme-reset-${id}" href="javascript:void(0)" onclick="resetTheme('${id}')" title="Revert to project / global default from config.yaml" style="font-size:11px;color:#7aa2f7;text-decoration:none;margin-left:4px;opacity:0.7;cursor:pointer">↺ default</a>
                 <button class="ctrl-btn" onclick="focusPanel('${id}')">focus</button>
                 <button class="ctrl-btn" onclick="halfPanel('${id}')">half</button>
+                <button class="ctrl-btn orch-toggle${isOrchestratorRole(meta.role) ? ' is-orch' : ''}" id="orch-toggle-${id}" type="button" onclick="toggleOrchestratorRole('${id}')" title="${isOrchestratorRole(meta.role) ? 'Unmark this panel as the orchestrator' : 'Mark this panel as the orchestrator — gold border, ORCH badge, pinned row'}">${orchToggleLabel(meta.role)}</button>
                 <button class="ctrl-btn reply-toggle" id="reply-btn-${id}" onclick="toggleReplyForm('${id}')" title="Send text to another terminal">reply ▸</button>
                 <input type="text" class="ctrl-input" id="ai-${id}" placeholder="Ask about this terminal..." onkeydown="if(event.key==='Enter')askAI('${id}', this.value)">
               </div>
@@ -729,11 +730,17 @@
       return panelProject === selectedFilter;
     }
 
-    // The chip row is only worth showing when there is real filtering to do:
-    // at least two project buckets, or one project plus some untagged panels.
+    // Sprint 66 T1 (Task 1.1) — the chip row renders whenever there is at
+    // least one project bucket, so the project-filter feature is *discoverable*
+    // rather than hidden until a second project shows up. Brad's 2026-05-13 v2
+    // spec asked for an always-visible rail; his single-live-panel setup sat
+    // below the old ≥2 threshold and saw nothing. With one project the row is
+    // [ All ] + that one project chip — harmless, and it advertises the filter.
+    // `hasNullProject` is retained in the signature for call-site / test
+    // compatibility; with ≥1 project the row shows regardless of it, and with
+    // zero projects an All-only row carries no filter value so it stays hidden.
     function shouldShowChipRow(projects, hasNullProject) {
-      const n = (projects || []).length;
-      return n >= 2 || (n >= 1 && hasNullProject === true);
+      return (projects || []).length >= 1;
     }
 
     // Approach A (Brad's 2026-05-13 spec): orchestrator identity is the
@@ -742,6 +749,21 @@
       return role === 'orchestrator';
     }
 
+    // Sprint 66 T1 (Task 1.3) — the binary "mark / unmark orchestrator" toggle.
+    // nextRoleForToggle: the role the toggle moves a panel TO, given its
+    // current role — orchestrator ⇄ unroled (null). A worker/reviewer/auditor
+    // panel is "not orchestrator", so the toggle promotes it to orchestrator;
+    // it does NOT preserve a prior non-orch role (the affordance is a binary
+    // ORCH switch, not a role-history stack — it matches "mark / unmark as
+    // orchestrator"). orchToggleLabel: the toggle button's text for a role.
+    // Both pure — unit-tested in tests/dashboard-panels-client.test.js.
+    function nextRoleForToggle(currentRole) {
+      return currentRole === 'orchestrator' ? null : 'orchestrator';
+    }
+    function orchToggleLabel(role) {
+      return role === 'orchestrator' ? 'unmark orch' : 'mark orch';
+    }
+
     // Belt-and-suspenders for missed panel_exited frames: panel ids the
     // dashboard still has a tile for, but which no longer appear in the
     // server's broadcast session list. Works whether or not T2 filters exited
@@ -912,10 +934,15 @@
       }
     }
 
-    // 1.2 — defensive reconcile: keep every tile in the container its role
-    // dictates. meta.role is immutable post-spawn so this is a no-op after a
-    // panel's first placement; it only acts if a panel was somehow built
-    // before its role was known. Returns true if any tile moved.
+    // 1.2 — reconcile: keep every tile in the container its role dictates.
+    // Re-evaluates isOrchestratorRole() for every panel on each call, so it is
+    // the primary mover whenever a role CHANGES — not merely a placement
+    // safety net. Sprint 66 T1 (Task 1.2) made meta.role mutable post-spawn
+    // (PATCH /api/sessions/:id {role}); a role flip arrives via status_broadcast,
+    // updatePanelMeta() merges it into entry.session.meta, scheduleChromeRefresh()
+    // runs this, and the panel moves into / out of the ORCH row carrying the
+    // panel--role-orch class (the gold border + "ORCH " badge are pure CSS on
+    // that class). Returns true if any tile moved.
     function reconcileOrchRow() {
       const orchRow = document.getElementById('orch-pin-row');
       const grid = document.getElementById('termGrid');
@@ -2177,6 +2204,64 @@
       if (sel && sel.value !== resolved) sel.value = resolved;
     }
 
+    // Sprint 66 T1 (Task 1.3) — mark / unmark a LIVE panel as the orchestrator
+    // in place. Brad's existing orchestrator panel was spawned with no role and
+    // there was no way to set one short of destroy+recreate via the raw API.
+    // This PATCHes meta.role (the Task 1.2 endpoint); on success the panel
+    // moves into the pinned ORCH row and gains the gold border + "ORCH " badge
+    // with no reload — reconcileOrchRow() (via refreshDashboardChrome) moves it.
+    // Multi-orchestrator is allowed: marking panel B does not unmark panel A
+    // (the ORCH row holds more than one; the operator explicitly unmarks). A
+    // global function — invoked from the Overview-tab button's inline onclick.
+    async function toggleOrchestratorRole(id) {
+      const entry = state.sessions.get(id);
+      if (!entry || entry._mounting || !entry.session) return;
+      const current = entry.session.meta ? entry.session.meta.role : null;
+      const next = nextRoleForToggle(current);
+      const btn = document.getElementById(`orch-toggle-${id}`);
+      if (btn) btn.disabled = true;
+      try {
+        const updated = await api('PATCH', `/api/sessions/${id}`, { role: next });
+        // api() returns the parsed body; a non-2xx body is annotated with
+        // `.error` (annotateApiFailure). The toggle only ever sends a
+        // whitelisted value so a 400 should not occur — but a 404 (panel gone)
+        // or a network failure can, and must not be applied as success.
+        if (updated && updated.error) {
+          console.error('[client] orchestrator-role toggle failed:', updated.error);
+          return;
+        }
+        // Apply the authoritative server role from the PATCH response, then
+        // re-route + re-skin the panel. The 2s status_broadcast converges to
+        // the same value (eventually-consistent — same model as changeTheme).
+        if (entry.session.meta) {
+          entry.session.meta.role = (updated && updated.meta) ? updated.meta.role : next;
+        }
+        refreshDashboardChrome();
+      } catch (err) {
+        console.error('[client] orchestrator-role toggle error:', err);
+      } finally {
+        if (btn) btn.disabled = false;
+        syncOrchToggle(id);
+      }
+    }
+
+    // Sprint 66 T1 (Task 1.3) — keep a panel's orch-toggle button in sync with
+    // its current meta.role (label, active class, tooltip). Called after a
+    // toggle and on every status_broadcast (updatePanelMeta), so the button is
+    // correct even when the role is changed from another dashboard tab.
+    function syncOrchToggle(id) {
+      const entry = state.sessions.get(id);
+      const btn = document.getElementById(`orch-toggle-${id}`);
+      if (!entry || entry._mounting || !entry.session || !btn) return;
+      const role = entry.session.meta ? entry.session.meta.role : null;
+      const isOrch = isOrchestratorRole(role);
+      btn.textContent = orchToggleLabel(role);
+      btn.classList.toggle('is-orch', isOrch);
+      btn.title = isOrch
+        ? 'Unmark this panel as the orchestrator'
+        : 'Mark this panel as the orchestrator — gold border, ORCH badge, pinned row';
+    }
+
     async function askAI(id, question) {
       if (!question.trim()) return;
       const entry = state.sessions.get(id);
@@ -3405,6 +3490,11 @@
         entry.session.meta = { ...entry.session.meta, ...meta };
       }
 
+      // Sprint 66 T1 (Task 1.3) — re-sync the orch-toggle button from the just-
+      // merged role, so a role changed from another dashboard tab is reflected
+      // here too (the per-tab toggle path syncs in its own finally block).
+      syncOrchToggle(id);
+
       const dot = document.getElementById(`dot-${id}`);
       const status = document.getElementById(`status-${id}`);
       const metaLast = document.getElementById(`meta-last-${id}`);

package/packages/client/public/style.css

@@ -694,6 +694,15 @@
     .ctrl-btn:hover { color: var(--tg-text); border-color: var(--tg-border-active); }
     .ctrl-btn.active { color: var(--tg-accent); border-color: var(--tg-accent-dim); }
 
+    /* Sprint 66 T1 (Task 1.3) — the "mark / unmark orchestrator" toggle in the
+       Overview controls. When the panel IS the orchestrator the button takes
+       the gold/amber accent — the same hue as the ORCH-pin border + badge — so
+       the control and the panel treatment read as one feature. */
+    .ctrl-btn.orch-toggle.is-orch {
+      color: var(--tg-accent-orch, #d4a017);
+      border-color: var(--tg-accent-orch, #d4a017);
+    }
+
     .theme-select {
       background: var(--tg-bg);
       border: 1px solid var(--tg-border);

package/packages/server/src/index.js

@@ -10,7 +10,6 @@ const os = require('os');
 const fs = require('fs');
 const dns = require('dns');
 const { spawn: spawnChild } = require('child_process');
-const { v4: uuidv4 } = require('uuid');
 const { createCachedLookup, createFailureLogger } = require('./rumen-pool-resilience');
 
 // Conditional imports (graceful fallback if not installed yet)
@@ -29,7 +28,7 @@ try {
     console.error('[db] better-sqlite3 native ABI mismatch (Node was upgraded after install).');
     console.error('[db] TermDeck cannot serve memory features without a working SQLite.');
     console.error('[db] Fix:');
-    console.error('       cd "$(npm root -g)/@jhizzard/termdeck" && npm rebuild better-sqlite3');
+    process.stderr.write('       cd "$(npm root -g)/@jhizzard/termdeck" && npm rebuild better-sqlite3\n');
     console.error('[db] Then restart TermDeck. Aborting.');
     process.exit(1);
   }
@@ -210,13 +209,13 @@ function _defaultSpawnSessionEndHookImpl(hookPath, payload, env) {
     env,
   });
   child.on('error', (err) => {
-    console.error('[onPanelClose] hook spawn error:', err && err.message ? err.message : err);
+    console.error('[panel-close] hook spawn error:', err && err.message ? err.message : err);
   });
   try {
     child.stdin.write(JSON.stringify(payload));
     child.stdin.end();
   } catch (err) {
-    console.error('[onPanelClose] hook stdin write failed:', err && err.message ? err.message : err);
+    console.error('[panel-close] hook stdin write failed:', err && err.message ? err.message : err);
   }
   child.unref();
   return child;
@@ -292,7 +291,7 @@ async function onPanelClose(session) {
       ...readTermdeckSecretsForPty(),
     });
   } catch (err) {
-    console.error('[onPanelClose] error:', err && err.message ? err.message : err);
+    console.error('[panel-close] error:', err && err.message ? err.message : err);
   }
 }
 
@@ -367,7 +366,7 @@ async function onPanelPeriodicCapture(session) {
     session._periodicCapture.lastSize = stat.size;
     session._periodicCapture.lastFireMs = Date.now();
   } catch (err) {
-    console.error('[onPanelPeriodicCapture] error:', err && err.message ? err.message : err);
+    console.error('[periodic-capture] error:', err && err.message ? err.message : err);
   }
 }
 
@@ -424,7 +423,7 @@ function _getT2DestFor() {
 
 function _termdeckVersion() {
   try { return require('../../../package.json').version; }
-  catch { return '0.0.0'; }
+  catch (err) { console.error('[version] package.json read failed:', err); return '0.0.0'; }
 }
 
 // Sprint 60 v1.0.14 (Item 3) — safe PTY resize. Brad's 2026-05-07 r730 crash
@@ -432,7 +431,7 @@ function _termdeckVersion() {
 // EBADF/ENOTTY` per 13h uptime. Race: WS `resize` message arrives for a PTY
 // that pty-reaper has already closed (or the child has exited), and
 // `pty.resize()` ioctls a stale fd. The error is race-expected, not a bug,
-// but the noisy console.error trace pollutes diagnostics and obscures real
+// but the noisy stderr trace pollutes diagnostics and obscures real
 // errors. This helper guards against the race and downgrades the known
 // race-class errors (EBADF, ENOTTY) to a silent return. Set
 // TERMDECK_DEBUG_PTY_RACES=1 to log to console.debug for diagnostics.
@@ -1457,7 +1456,7 @@ function createServer(config) {
             session._periodicCapture = { lastSize: 0, lastFireMs: 0, timer: null };
             session._periodicCapture.timer = setInterval(() => {
               onPanelPeriodicCapture(session).catch((err) => {
-                console.error('[onPanelPeriodicCapture] async error:', err && err.message ? err.message : err);
+                console.error('[periodic-capture] async error:', err && err.message ? err.message : err);
               });
             }, intervalMs);
             // Don't keep the event loop alive solely for this timer — the PTY
@@ -1549,7 +1548,7 @@ function createServer(config) {
           // skip-claude + skip-when-no-transcript. Fire-and-forget; any
           // error logs and never blocks teardown.
           onPanelClose(session).catch((err) => {
-            console.error('[onPanelClose] async error:', err && err.message ? err.message : err);
+            console.error('[panel-close] async error:', err && err.message ? err.message : err);
           });
 
           // Sprint 59 T4-CODEX UPLOAD-AUDIT-CONCERN closure: blow away the
@@ -1754,7 +1753,19 @@ function createServer(config) {
 
   // PATCH /api/sessions/:id - update session metadata
   app.patch('/api/sessions/:id', (req, res) => {
-    const session = sessions.updateMeta(req.params.id, req.body);
+    // Sprint 66 T1 (Task 1.2) — `role` is PATCH-mutable so an operator can tag
+    // a live panel as orchestrator in place. Validate it exactly as POST
+    // /api/sessions does (index.js — the `invalid_role` 400 above): an absent
+    // field is fine, any present value must be in ALLOWED_SESSION_ROLES
+    // (orchestrator/worker/reviewer/auditor/null) — an unknown value is a 400
+    // so a typo surfaces immediately rather than silently mis-tagging the
+    // panel. Validation runs BEFORE updateMeta so a bad role never reaches the
+    // whitelist apply or the SQLite write.
+    const body = req.body || {};
+    if (body.role !== undefined && !ALLOWED_SESSION_ROLES.includes(body.role)) {
+      return res.status(400).json({ ok: false, code: 'invalid_role', allowed: ALLOWED_SESSION_ROLES });
+    }
+    const session = sessions.updateMeta(req.params.id, body);
     if (!session) return res.status(404).json({ error: 'Session not found' });
     res.json(session.toJSON());
   });
@@ -2023,7 +2034,7 @@ function createServer(config) {
       return res.status(410).json({ error: 'PTY is gone (session exited)' });
     }
 
-    const { cols, rows } = req.body;
+    const { cols, rows } = req.body || {};
     try {
       const resized = safelyResizePty(session, cols, rows);
       if (!resized) {
@@ -2603,7 +2614,7 @@ function createServer(config) {
 
   // POST /api/ai/query - query Mnestra memory via the bridge (direct|webhook|mcp)
   app.post('/api/ai/query', async (req, res) => {
-    let { question, sessionId, project } = req.body;
+    let { question, sessionId, project } = req.body || {};
     if (!question) return res.status(400).json({ error: 'Missing question' });
 
     let searchAll = false;
@@ -2758,8 +2769,9 @@ function createServer(config) {
     });
   }, 2000);
 
-  // Fallback route → serve index.html
-  app.get('*', (req, res) => {
+  // Fallback route → serve index.html. Express 5: named wildcard '/{*splat}'
+  // (path-to-regexp v8 — a bare '*' throws at registration; this matches all paths incl. root).
+  app.get('/{*splat}', (req, res) => {
     res.sendFile(path.join(clientDir, 'index.html'));
   });
 

package/packages/server/src/orchestration-preview.js

@@ -187,7 +187,7 @@ async function generateScaffolding({ name, projects, cwd, force, initProject, te
   // Refuse on existing non-empty dir without force, mirroring T2's CLI semantics.
   if (fs.existsSync(targetPath)) {
     const entries = (() => {
-      try { return fs.readdirSync(targetPath); } catch { return []; }
+      try { return fs.readdirSync(targetPath); } catch (err) { console.error('[orch-preview] readdir failed:', err); return []; }
     })();
     const nonEmpty = entries.length > 0;
     if (nonEmpty && !force) {

package/packages/server/src/session.js

@@ -10,7 +10,7 @@
 // metadata broadcast in index.js untouched — `s.meta.theme` already returns
 // the right thing whenever index.js dereferences it.
 
-const { v4: uuidv4 } = require('uuid');
+const { randomUUID } = require('crypto');
 const os = require('os');
 const path = require('path');
 const { resolveTheme } = require('./theme-resolver');
@@ -135,7 +135,7 @@ const PATTERNS = {
 
 class Session {
   constructor(options) {
-    this.id = options.id || uuidv4();
+    this.id = options.id || randomUUID();
     this.pid = null;
     this.pty = null;
     this.ws = null;
@@ -634,7 +634,15 @@ class SessionManager {
     'label',
     'project',
     'ragEnabled',
-    'flashbackEnabled'
+    'flashbackEnabled',
+    // Sprint 66 T1 (Task 1.2) — `role` is now PATCH-mutable so an operator can
+    // tag a live panel as orchestrator in place (Brad's existing orch panel
+    // was spawned with no role and had no way to set one short of a raw-API
+    // destroy + recreate). The PATCH /api/sessions/:id route validates the
+    // value against ALLOWED_SESSION_ROLES before this whitelist is consulted —
+    // the same "route validates, model trusts" boundary as POST /api/sessions
+    // and the Session constructor.
+    'role'
   ]);
 
   updateMeta(id, updates) {
@@ -657,6 +665,16 @@ class SessionManager {
         .run(applied.theme == null ? null : applied.theme, id);
     }
 
+    // Sprint 66 T1 (Task 1.2) — persist a role change to SQLite so a panel
+    // tagged orchestrator via PATCH keeps the role across a server restart /
+    // dashboard reload, exactly as a spawn-time role does. create() writes the
+    // `role` column on INSERT; this is its UPDATE counterpart. The column was
+    // added by Sprint 65 T2 (CREATE TABLE + a PRAGMA-guarded ALTER migration).
+    if ('role' in applied && this.db) {
+      this.db.prepare('UPDATE sessions SET role = ? WHERE id = ?')
+        .run(applied.role == null ? null : applied.role, id);
+    }
+
     this._emit('session:updated', session);
     return session;
   }

package/packages/server/src/sprint-inject.js

@@ -233,7 +233,7 @@ async function injectSprintPrompts({
           } else {
             anyPending = true;
           }
-        } catch {
+        } catch (_err) {
           anyPending = true;
         }
       }
@@ -257,7 +257,7 @@ async function injectSprintPrompts({
         const s = await getStatus(lane.sessionId);
         lane.finalStatus = s && s.status ? s.status : lane.finalStatus;
         if (lane.finalStatus === 'thinking') lane.verified = true;
-      } catch {
+      } catch (_err) {
         // ignore
       }
     }