@hanzlaa/rcode 3.5.0 → 3.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "3.5.0",
+  "version": "3.6.1",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {
@@ -74,5 +74,11 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "ws": "^8.20.1"
+  },
+  "optionalDependencies": {
+    "@lydell/node-pty": "1.2.0-beta.12"
   }
 }

package/rihal/bin/rihal-tools.cjs

@@ -3324,6 +3324,137 @@ function cmdPhase(subArgs) {
     };
   }
 
+  // =====================================================================
+  // phase complete <phase_number> — mark a phase complete and report the
+  // next phase. Closes the workflow/CLI drift (#766): execute.md calls
+  // `phase complete` but only set-status existed.
+  // =====================================================================
+  if (sub === 'complete') {
+    const phaseRef = subArgs[1];
+    if (!phaseRef) throw new Error('phase complete requires <phase_number>');
+    const statePath = path.join(RIHAL_DIR, 'state.json');
+    if (!fs.existsSync(statePath)) {
+      throw new Error(`state.json not found at ${statePath} — run 'rihal-tools state init' first`);
+    }
+    let state;
+    try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); }
+    catch (e) { throw new Error(`Invalid JSON in state.json: ${e.message}`); }
+    if (!state.phases) state.phases = [];
+    const idx = state.phases.findIndex(p =>
+      String(p.number) === String(phaseRef) ||
+      String(p.id) === String(phaseRef) ||
+      p.name === phaseRef
+    );
+    if (idx === -1) {
+      throw new Error(`Phase "${phaseRef}" not found in state.phases (looked up by number, id, and name)`);
+    }
+    const previous = state.phases[idx].status || null;
+    state.phases[idx].status = 'complete';
+    state.phases[idx].status_updated = new Date().toISOString();
+    state.phases[idx].completed_at = state.phases[idx].completed_at || new Date().toISOString().slice(0, 10);
+
+    const num = parseInt(String(state.phases[idx].number || phaseRef), 10);
+    const next = state.phases
+      .filter(p => parseInt(String(p.number), 10) > num)
+      .sort((a, b) => parseInt(String(a.number), 10) - parseInt(String(b.number), 10))[0] || null;
+
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+    return {
+      ok: true,
+      phase: phaseRef,
+      previous_status: previous,
+      new_status: 'complete',
+      next_phase: next ? next.number : null,
+      next_phase_name: next ? (next.name || null) : null,
+      is_last_phase: !next,
+      warnings: [],
+      has_warnings: false,
+    };
+  }
+
+  // =====================================================================
+  // phase sync-sprints <phase_number> — register sprint records into
+  // state.json by deriving them from the .planning/phases/<dir>/*-SPRINT.md
+  // files (the source of truth). Closes #765: planner agents write SPRINT.md
+  // files but do not always register sprint entries, leaving state.json an
+  // incomplete mirror. This makes registration a deterministic CLI step.
+  // =====================================================================
+  if (sub === 'sync-sprints') {
+    const phaseRef = subArgs[1];
+    if (!phaseRef) throw new Error('phase sync-sprints requires <phase_number>');
+    const statePath = path.join(RIHAL_DIR, 'state.json');
+    if (!fs.existsSync(statePath)) {
+      throw new Error(`state.json not found at ${statePath} — run 'rihal-tools state init' first`);
+    }
+    let state;
+    try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); }
+    catch (e) { throw new Error(`Invalid JSON in state.json: ${e.message}`); }
+    if (!state.phases) state.phases = [];
+    const idx = state.phases.findIndex(p =>
+      String(p.number) === String(phaseRef) ||
+      String(p.id) === String(phaseRef) ||
+      p.name === phaseRef
+    );
+    if (idx === -1) {
+      throw new Error(`Phase "${phaseRef}" not found in state.phases`);
+    }
+
+    const phasesDir = path.join(PLANNING_DIR, 'phases');
+    const intId = String(phaseRef).split('.')[0];
+    let dirs;
+    try { dirs = fs.readdirSync(phasesDir, { withFileTypes: true }).filter(d => d.isDirectory()); }
+    catch { throw new Error(`No .planning/phases directory found`); }
+    const dir = dirs.find(d => d.name.startsWith(intId + '-') ||
+                               d.name.startsWith(intId.padStart(2, '0') + '-'));
+    if (!dir) throw new Error(`No phase directory on disk for phase ${phaseRef}`);
+
+    const files = fs.readdirSync(path.join(phasesDir, dir.name));
+    const sprintFiles = files.filter(f => /-SPRINT\.md$/i.test(f)).sort();
+    const sprints = sprintFiles.map(f => {
+      const m   = f.match(/^(\d+)-(\d+)-SPRINT\.md$/i);
+      const num = m ? parseInt(m[2], 10) : 0;
+      const sid = m ? `${parseInt(m[1], 10)}.${num}` : f.replace(/-SPRINT\.md$/i, '');
+      const text = fs.readFileSync(path.join(phasesDir, dir.name, f), 'utf8');
+      const fmGoal = (text.match(/^goal:\s*(.+)$/m) || [])[1];
+      let goal = fmGoal ? fmGoal.trim() : '';
+      if (!goal) {
+        const obj = (text.match(/<objective>\s*([\s\S]*?)<\/objective>/) || [])[1] || '';
+        goal = (obj.trim().split('\n').map(s => s.trim()).filter(Boolean)[0] || '').slice(0, 160);
+      }
+      const stories = [];
+      const taskRe = /<task\b([^>]*)>([\s\S]*?)<\/task>/g;
+      let tm;
+      while ((tm = taskRe.exec(text))) {
+        const idM = tm[1].match(/id="([^"]+)"/);
+        const tM  = tm[2].match(/<title>([\s\S]*?)<\/title>/);
+        stories.push({ id: idM ? idM[1] : `${sid}.${stories.length + 1}`,
+                       title: tM ? tM[1].trim() : `Task ${stories.length + 1}`,
+                       status: 'planned' });
+      }
+      if (!stories.length) {
+        // Legacy SPRINT.md: "### Story|Task <id> — <title>" headings.
+        const headRe = /^#{2,4}\s+(?:Story|Task)\s+([^\s—–-]+)\s*[—–-]\s*(.+?)\s*$/gm;
+        let hm;
+        while ((hm = headRe.exec(text))) {
+          stories.push({ id: hm[1].trim(), title: hm[2].trim(), status: 'planned' });
+        }
+      }
+      const hasSummary = files.includes(f.replace(/-SPRINT\.md$/i, '-SUMMARY.md'));
+      return { id: sid, number: num, goal: goal || `Sprint ${num}`,
+               status: hasSummary ? 'complete' : 'planned', stories };
+    });
+
+    state.phases[idx].sprints = sprints;
+    state.phases[idx].plan_count = sprints.length;
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+    return {
+      ok: true,
+      phase: phaseRef,
+      sprints_registered: sprints.length,
+      stories_registered: sprints.reduce((a, s) => a + s.stories.length, 0),
+    };
+  }
+
   if (sub === 'set-status') {
     const phaseRef = subArgs[1];
     const newStatus = subArgs[2];
@@ -3435,33 +3566,35 @@ function cmdPhase(subArgs) {
     const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
     const statePath = path.join(RIHAL_DIR, 'state.json');
 
+    // #769 — the next free number is derived from phase DIRECTORIES only.
+    // A directory is the physical "slot taken" signal. ROADMAP.md headings and
+    // directory-less state.json entries represent phases that are *planned but
+    // not yet scaffolded* — which is exactly what this command materialises —
+    // so they must NOT push the start number forward. (The old code also read
+    // the roadmap + state into maxNum, which made scaffold-milestone skip past
+    // an already-written roadmap range, e.g. scaffolding 38-41 for a 34-37
+    // milestone.)
+    const dirNumbers = new Set();
     let maxNum = 0;
     if (fs.existsSync(phasesDir)) {
       for (const entry of fs.readdirSync(phasesDir)) {
         const m = entry.match(/^(\d+)/);
-        if (m) maxNum = Math.max(maxNum, parseInt(m[1], 10));
+        if (m) {
+          const n = parseInt(m[1], 10);
+          dirNumbers.add(n);
+          maxNum = Math.max(maxNum, n);
+        }
       }
     }
-    if (fs.existsSync(roadmapPath)) {
-      const text = fs.readFileSync(roadmapPath, 'utf8');
-      const pipeRe = /^\|\s*(\d+)\s*\|/gm;
-      let m;
-      while ((m = pipeRe.exec(text)) !== null) maxNum = Math.max(maxNum, parseInt(m[1], 10));
-      const headRe = /^#{2,4}\s*Phase\s+(\d+)\b/gm;
-      while ((m = headRe.exec(text)) !== null) maxNum = Math.max(maxNum, parseInt(m[1], 10));
-    }
     let state = { phases: [] };
     if (fs.existsSync(statePath)) {
       try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); } catch {}
     }
     if (!Array.isArray(state.phases)) state.phases = [];
-    for (const p of state.phases) {
-      const n = parseInt(String(p.number || ''), 10);
-      if (!Number.isNaN(n)) maxNum = Math.max(maxNum, n);
-    }
 
     const firstNum = startOverride !== null ? startOverride : maxNum + 1;
     const created  = [];
+    const roadmapSkipped = [];
 
     for (let i = 0; i < names.length; i++) {
       const phaseName = names[i];
@@ -3475,8 +3608,17 @@ function cmdPhase(subArgs) {
       if (!slug) {
         throw new Error(`Name at index ${i} ("${phaseName}") produces an empty slug`);
       }
-      if (state.phases.some(p => String(p.number) === number)) {
-        throw new Error(`Phase ${number} already exists in state.json (would collide at index ${i})`);
+      // #769 — a real collision is a state entry that ALSO has a directory on
+      // disk (the phase is genuinely already scaffolded). A directory-less
+      // state entry is a phantom — e.g. rihal-roadmapper synced the phase into
+      // state.json but never created the folder — so reconcile it in place
+      // instead of aborting.
+      const existingIdx = state.phases.findIndex(p => String(p.number) === number);
+      if (existingIdx !== -1) {
+        if (dirNumbers.has(firstNum + i)) {
+          throw new Error(`Phase ${number} already scaffolded (directory + state entry exist) — collision at index ${i}`);
+        }
+        state.phases.splice(existingIdx, 1);
       }
 
       const dirName  = `${number}-${slug}`;
@@ -3486,22 +3628,29 @@ function cmdPhase(subArgs) {
       }
       fs.mkdirSync(directory, { recursive: true });
 
-      // Append ROADMAP entry
+      // Append ROADMAP entry — but skip if the roadmap already declares this
+      // phase (#769: rihal-roadmapper writes `## Phase N` sections directly, so
+      // appending a stub here produced a duplicate heading).
       if (fs.existsSync(roadmapPath)) {
-        const entry = `## Phase ${number} — ${phaseName}\n\n` +
-          `**Goal:** _TBD — fill in via /rihal-discuss-phase ${number} or edit directly._\n\n` +
-          `**Status:** Planned\n\n` +
-          `**Plans:**\n- _TBD_\n\n` +
-          `**Acceptance:** _TBD_\n\n---\n`;
         let text = fs.readFileSync(roadmapPath, 'utf8');
-        const backlogMatch = text.match(/^##\s+Backlog\b/m);
-        if (backlogMatch) {
-          text = text.slice(0, backlogMatch.index) + entry + '\n' + text.slice(backlogMatch.index);
+        const headingRe = new RegExp(`^#{2,4}\\s*Phase\\s+${number}\\b`, 'm');
+        if (headingRe.test(text)) {
+          roadmapSkipped.push(number);
         } else {
-          if (!text.endsWith('\n')) text += '\n';
-          text += '\n' + entry;
+          const entry = `## Phase ${number} — ${phaseName}\n\n` +
+            `**Goal:** _TBD — fill in via /rihal-discuss-phase ${number} or edit directly._\n\n` +
+            `**Status:** Planned\n\n` +
+            `**Plans:**\n- _TBD_\n\n` +
+            `**Acceptance:** _TBD_\n\n---\n`;
+          const backlogMatch = text.match(/^##\s+Backlog\b/m);
+          if (backlogMatch) {
+            text = text.slice(0, backlogMatch.index) + entry + '\n' + text.slice(backlogMatch.index);
+          } else {
+            if (!text.endsWith('\n')) text += '\n';
+            text += '\n' + entry;
+          }
+          fs.writeFileSync(roadmapPath, text);
         }
-        fs.writeFileSync(roadmapPath, text);
       }
 
       state.phases.push({
@@ -3519,10 +3668,10 @@ function cmdPhase(subArgs) {
     if (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });
     fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
 
-    return { ok: true, count: created.length, phases: created };
+    return { ok: true, count: created.length, phases: created, roadmap_skipped: roadmapSkipped };
   }
 
-  throw new Error(`Unknown phase subcommand: ${sub || '(none)'}. Valid: add, set-status, next-range, scaffold-milestone`);
+  throw new Error(`Unknown phase subcommand: ${sub || '(none)'}. Valid: add, complete, sync-sprints, set-status, next-range, scaffold-milestone`);
 }
 
 /**
@@ -4434,6 +4583,96 @@ function cmdPhasePlanIndex(rawArgs) {
   };
 }
 
+/**
+ * Extract a frontmatter list field that may be written inline (`key: [a, b]`),
+ * as a single scalar (`key: a`), or as a block list (`key:` then `  - a`).
+ * Returns a string array (empty if the key is absent).
+ */
+function fmListField(block, key) {
+  const lines = block.split('\n');
+  const strip = (s) => s.trim().replace(/^["']|["']$/g, '');
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(new RegExp(`^${key}\\s*:\\s*(.*)$`));
+    if (!m) continue;
+    const inline = m[1].trim();
+    if (inline.startsWith('[')) {
+      return inline.replace(/^\[|\]$/g, '').split(',').map(strip).filter(Boolean);
+    }
+    if (inline) return [strip(inline)];
+    const out = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const lm = lines[j].match(/^\s+-\s+(.*)$/);
+      if (!lm) break;
+      out.push(strip(lm[1]));
+    }
+    return out;
+  }
+  return [];
+}
+
+/**
+ * plan check-wave-overlaps <phase> — enforce the wave-parallelism rule
+ * (plan.md Step 12.5, issue #768): two plans in the SAME wave that both list
+ * the same path in `files_modified` cannot run in parallel — the later plan
+ * (by plan number) must declare `sequential: true`. Returns a JSON report of
+ * unresolved conflicts so /rihal-plan can auto-correct the frontmatter.
+ */
+function cmdPlanCheckWaveOverlaps(rawArgs) {
+  const phaseArg = String(rawArgs || '').trim().split(/\s+/)[0] || '';
+  if (!phaseArg) {
+    console.error('Usage: plan check-wave-overlaps <phase-number>');
+    process.exit(1);
+  }
+  const phasesDir = path.join(PLANNING_DIR, 'phases');
+  const norm = phaseArg.replace(/^0+/, '') || '0';
+  let phaseDir = null;
+  if (fs.existsSync(phasesDir)) {
+    for (const d of fs.readdirSync(phasesDir)) {
+      const m = d.match(/^(\d+)(?:[-.])/);
+      if (m && (m[1].replace(/^0+/, '') || '0') === norm) { phaseDir = path.join(phasesDir, d); break; }
+    }
+  }
+  if (!phaseDir) return { phase: phaseArg, conflicts: [], plans_checked: 0, phase_dir: null };
+
+  const plans = [];
+  for (const file of fs.readdirSync(phaseDir).filter((f) => /-SPRINT\.md$/i.test(f)).sort()) {
+    const text = fs.readFileSync(path.join(phaseDir, file), 'utf8');
+    let block = '';
+    if (text.startsWith('---\n')) {
+      const end = text.indexOf('\n---\n', 4);
+      if (end !== -1) block = text.slice(4, end);
+    }
+    const stem = file.replace(/-SPRINT\.md$/i, '');
+    const numMatch = (block.match(/^plan_number\s*:\s*(\d+)/m) || stem.match(/-(\d+)$/));
+    plans.push({
+      id: stem,
+      order: numMatch ? parseInt(numMatch[1], 10) : 0,
+      wave: parseInt((block.match(/^wave\s*:\s*(\d+)/m) || [])[1] || '1', 10) || 1,
+      sequential: /^sequential\s*:\s*true\s*$/m.test(block),
+      files: fmListField(block, 'files_modified'),
+    });
+  }
+
+  const conflicts = [];
+  for (let a = 0; a < plans.length; a++) {
+    for (let b = a + 1; b < plans.length; b++) {
+      const [earlier, later] = plans[a].order <= plans[b].order ? [plans[a], plans[b]] : [plans[b], plans[a]];
+      if (earlier.wave !== later.wave) continue;
+      const shared = earlier.files.filter((f) => later.files.includes(f));
+      if (shared.length === 0) continue;
+      if (later.sequential) continue;
+      conflicts.push({
+        wave: earlier.wave,
+        plan_a: earlier.id,
+        plan_b: later.id,
+        shared_files: shared,
+        plan_b_sequential: false,
+      });
+    }
+  }
+  return { phase: phaseArg, phase_dir: path.relative(PROJECT_ROOT, phaseDir), plans_checked: plans.length, conflicts };
+}
+
 /** phases list — directory inventory under .planning/phases with optional --type filter and --pick path. */
 function cmdPhasesList(args) {
   const argv = Array.isArray(args) ? args : String(args || '').trim().split(/\s+/).filter(Boolean);
@@ -6501,7 +6740,10 @@ async function main() {
           console.log(JSON.stringify(result, null, 2));
           process.exit(result.ok ? 0 : 1);
         }
-        else { console.error('Unknown plan subcommand. Valid: list, validate-evidence'); process.exit(1); }
+        else if (args[0] === 'check-wave-overlaps') {
+          result = cmdPlanCheckWaveOverlaps(args.slice(1).join(' '));
+        }
+        else { console.error('Unknown plan subcommand. Valid: list, validate-evidence, check-wave-overlaps'); process.exit(1); }
         break;
       case 'phase-plan-index':
         result = cmdPhasePlanIndex(args.join(' '));
@@ -6761,8 +7003,9 @@ async function main() {
         console.log('  classify-tech --keywords "<keywords>"        → classify tech stack from keywords (frontend/backend/mobile/styling)');
         console.log('  context refresh                              → refresh .rihal/context/ cache from .rihal/sources.yaml');
         console.log('  module <subcommand> [args]                   → module system helpers');
-        console.log('  plan <list|validate-evidence>                → phase/plan operations');
+        console.log('  plan <list|validate-evidence|check-wave-overlaps>  → phase/plan operations');
         console.log('  plan validate-evidence <N> [--spot-check]    → enforce <evidence> blocks in SPRINT.md (#649); exit 1 on violation');
+        console.log('  plan check-wave-overlaps <N>                 → detect same-wave plans sharing files_modified (#768)');
         console.log('  phase-plan-index <N>                         → JSON inventory of plans under phase N (waves, summary status, task counts)');
         console.log('  phases list [--type X] [--pick path]         → directory inventory of .planning/phases (--type: summaries|sprints|directories|all; --pick: e.g. directories[-1])');
         console.log('  find-phase <N> [--raw]                       → resolve phase number to dir/slug + decimal children');

package/server/dashboard.js

@@ -22,9 +22,14 @@
 
 const http    = require('http');
 const path    = require('path');
+const fs      = require('fs');
+const os      = require('os');
 const crypto  = require('crypto');
 const { spawn } = require('child_process');
 
+// Client JS modules live here and are served verbatim at /js/<name>.js
+const CLIENT_DIR = path.join(__dirname, 'lib', 'html', 'client');
+
 const { scanState } = require('./lib/scanner');
 const { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy, handleApiMemory } = require('./lib/api');
 const { renderHtml } = require('./lib/html/shell');
@@ -34,8 +39,25 @@ const PORT = parseInt(process.env.PORT || '7717', 10);
 const RIHAL_DIR = process.env.RIHAL_DIR || path.join(process.cwd(), '.rihal');
 const PROJECT_ROOT = path.dirname(RIHAL_DIR);
 
-// Shared orchestrator token — generated once, passed to orchestrator via env and embedded in HTML
-const ORCH_TOKEN = process.env.ORCH_TOKEN || crypto.randomBytes(24).toString('hex');
+// Shared orchestrator token — passed to the orchestrator via env and embedded
+// in the HTML. Persisted to ~/.rihal/orch-token so it stays STABLE across
+// dashboard restarts; otherwise every restart invalidates the token baked
+// into already-open browser tabs and their API calls 401.
+function loadOrchToken() {
+  if (process.env.ORCH_TOKEN) return process.env.ORCH_TOKEN;
+  const tokenFile = path.join(os.homedir(), '.rihal', 'orch-token');
+  try {
+    const existing = fs.readFileSync(tokenFile, 'utf8').trim();
+    if (existing) return existing;
+  } catch { /* not yet created */ }
+  const token = crypto.randomBytes(24).toString('hex');
+  try {
+    fs.mkdirSync(path.dirname(tokenFile), { recursive: true });
+    fs.writeFileSync(tokenFile, token, { mode: 0o600 });
+  } catch { /* non-fatal — fall back to an in-memory token */ }
+  return token;
+}
+const ORCH_TOKEN = loadOrchToken();
 
 // ---------- HTTP Server ----------
 const server = http.createServer((req, res) => {
@@ -72,6 +94,37 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  // Lets the client fetch the current orchestrator token at runtime, so a
+  // long-open tab can self-heal instead of 401'ing if the token ever drifts.
+  if (url === '/api/orch-token') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ token: ORCH_TOKEN }));
+    return;
+  }
+
+  if (url.startsWith('/js/')) {
+    const name = url.slice(4).split('?')[0];
+    // Allow exactly one optional subdirectory (e.g. components/App.js, views/Foo.js)
+    // while still rejecting traversal attempts. The regex blocks `..`, encoded
+    // separators, and anything other than word chars, dots, hyphens, and one `/`.
+    if (!/^(?:[\w.-]+\/)?[\w.-]+\.js$/.test(name)) { res.writeHead(404); res.end('Not found'); return; }
+    // Defense-in-depth: resolved path must stay inside CLIENT_DIR even after
+    // any OS-level resolution (handles encoded traversal the regex might miss).
+    const resolved = path.resolve(CLIENT_DIR, name);
+    if (!resolved.startsWith(CLIENT_DIR + path.sep) && resolved !== CLIENT_DIR) {
+      res.writeHead(403); res.end('Forbidden'); return;
+    }
+    fs.readFile(resolved, (err, data) => {
+      if (err) { res.writeHead(404); res.end('Not found'); return; }
+      res.writeHead(200, {
+        'Content-Type':  'application/javascript; charset=utf-8',
+        'Cache-Control': 'no-cache',
+      });
+      res.end(data);
+    });
+    return;
+  }
+
   if (url === '/' || url === '/index.html') {
     const state = scanState(RIHAL_DIR);
     const html = renderHtml(state, ORCH_TOKEN);
@@ -96,6 +149,54 @@ server.listen(PORT, '127.0.0.1', () => {
   console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
 });
 
+// ── Ensure interactive-terminal native module is present ─────────
+// @lydell/node-pty is an optionalDependency, so it can be absent if the
+// package was installed with --omit=optional or a partial CI install.
+// It ships prebuilt binaries (no node-gyp), so fetching it is a fast,
+// no-compile, one-time step. Runs async — the dashboard never blocks; the
+// orchestrator is spawned via the callback once the install settles.
+// Failure is non-fatal: the terminal just degrades with a clear message.
+function ensurePty(done) {
+  try { require.resolve('@lydell/node-pty'); done(); return; } catch {}
+
+  const pkgRoot = path.join(__dirname, '..');
+
+  // @lydell/node-pty is already declared in optionalDependencies, so a plain
+  // lockfile-respecting `install` pulls it in without mutating package.json.
+  // Use pnpm when the repo is pnpm-managed — `npm install` fights pnpm's
+  // symlinked node_modules and stalls. End-user installs use npm.
+  const usePnpm = fs.existsSync(path.join(pkgRoot, 'pnpm-lock.yaml'));
+  const cmd  = usePnpm ? 'pnpm' : 'npm';
+  const args = usePnpm
+    ? ['install', '--ignore-scripts']
+    : ['install', '--ignore-scripts', '--no-audit', '--no-fund'];
+
+  console.log('[setup] Installing interactive-terminal support (@lydell/node-pty)…');
+  let settled = false;
+  const finish = (ok) => {
+    if (settled) return;
+    settled = true;
+    console.log(ok ? '[setup] Interactive terminal ready.'
+                    : '[setup] node-pty install incomplete — terminal stays unavailable.');
+    done();
+  };
+
+  let child;
+  try {
+    child = spawn(cmd, args, {
+      cwd: pkgRoot, stdio: 'inherit', shell: process.platform === 'win32',
+    });
+  } catch (err) {
+    console.log('[setup] node-pty install could not start:', err.message);
+    finish(false);
+    return;
+  }
+  const timer = setTimeout(() => { try { child.kill(); } catch {} }, 180000);
+  child.on('exit',  code => { clearTimeout(timer); finish(code === 0); });
+  child.on('error', err  => { clearTimeout(timer);
+    console.log('[setup] node-pty install error:', err.message); finish(false); });
+}
+
 // ── Auto-spawn orchestrator (port 7718) ──────────────────────────
 const ORCH_BIN = path.join(__dirname, 'orchestrator.js');
 let _orchProc = null;
@@ -132,7 +233,8 @@ function spawnOrchestrator() {
   }
 }
 
-spawnOrchestrator();
+// Orchestrator spawns only once node-pty is settled (present or installed).
+ensurePty(spawnOrchestrator);
 
 // Graceful shutdown
 function shutdown() {

package/server/lib/html/client/agents-data.js

@@ -0,0 +1,27 @@
+/**
+ * agents-data.js — the 18-agent roster, moved client-side from shell.js.
+ *
+ * Previously lived in shell.js:17-36 as a server-rendered array.
+ * Now exported as a pure ESM constant so AgentsView can render it.
+ */
+
+export const AGENTS = [
+  { name: 'Sadiq Damani',         arabic: 'صادق',         role: 'Director of Strategy',              real: true, type: 'leadership' },
+  { name: 'Waleed Al Harthi',     arabic: 'وليد',         role: 'CTO',                               real: true, type: 'leadership' },
+  { name: 'Ahmed Al Hassani',     arabic: 'أحمد الحسني',  role: 'Technology & Development Director', real: true, type: 'leadership' },
+  { name: 'Nasser',               arabic: 'ناصر',         role: 'Engineering Manager',               real: true, type: 'leadership' },
+  { name: 'Hussain',              arabic: 'حسين',         role: 'PM + Scrum Master',                                type: 'product' },
+  { name: 'Layla',                arabic: 'ليلى',         role: 'Lead UX Designer',                                 type: 'design' },
+  { name: 'Zahra',                arabic: 'زهرة',         role: 'Branding & Creative Director',                    type: 'design' },
+  { name: 'Omar',                 arabic: 'عمر',          role: 'Full-Stack Engineer',                              type: 'engineering' },
+  { name: 'Haitham Al Khamiyasi', arabic: 'هيثم',        role: 'Senior Frontend',                   real: true, type: 'engineering' },
+  { name: 'Yousef',               arabic: 'يوسف',         role: 'Senior Backend',                                   type: 'engineering' },
+  { name: 'Zayd',                 arabic: 'زيد',          role: 'ML Engineer',                                      type: 'engineering' },
+  { name: 'Fatima',               arabic: 'فاطمة',        role: 'QA Lead',                                          type: 'quality' },
+  { name: 'Khalid',               arabic: 'خالد',         role: 'DevOps',                                           type: 'engineering' },
+  { name: 'Noor',                 arabic: 'نور',          role: 'Scribe',                                           type: 'support' },
+  { name: 'Mariam',               arabic: 'مريم',         role: 'Marketing Lead',                                   type: 'product' },
+  { name: 'Raees',                arabic: 'رئيس',         role: 'Orchestration Director',                          type: 'system' },
+  { name: 'Majlis',               arabic: 'مجلس',         role: 'Consulting Council',                               type: 'system' },
+  { name: 'Diwan',                arabic: 'ديوان',        role: 'Dashboard Registry',                               type: 'system' },
+];

package/server/lib/html/client/app.js

@@ -0,0 +1,15 @@
+/**
+ * ESM entry point — mounts the Preact App into #app-root.
+ *
+ * Loaded via <script type="module" src="/js/app.js"> from client.js,
+ * AFTER the legacy <script src> modules (which fill the 10 un-migrated
+ * view host divs). Legacy modules remain active during coexistence phase.
+ */
+
+import { render, html } from './preact.js';
+import { App } from './components/App.js';
+
+const root = document.getElementById('app-root');
+if (root) {
+  render(html`<${App}/>`, root);
+}