@jhizzard/termdeck 0.10.3 → 0.11.0

package/packages/server/src/config.js

@@ -298,6 +298,54 @@ function addProject({ name, path: projectPath, defaultTheme, defaultCommand }) {
   return parsed.projects;
 }
 
+// Remove a project from ~/.termdeck/config.yaml and return the updated projects
+// map. Mirrors addProject for the inverse operation. Throws ENOENT-shaped
+// errors with `code` set so callers can map cleanly to HTTP status. Files on
+// disk at the project's `path` are NEVER touched — this only edits the YAML
+// entry. The user retains all source code.
+function removeProject(name, configPath = CONFIG_PATH) {
+  if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+    const err = new Error('Project name must be non-empty and contain only letters, digits, . _ or -');
+    err.code = 'BAD_NAME';
+    throw err;
+  }
+
+  const yaml = require('yaml');
+  let parsed = {};
+  if (fs.existsSync(configPath)) {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    try {
+      parsed = yaml.parse(raw) || {};
+    } catch (err) {
+      throw new Error(`config.yaml is not valid YAML — cannot safely rewrite: ${err.message}`);
+    }
+  }
+
+  if (!parsed.projects || typeof parsed.projects !== 'object' || !parsed.projects[name]) {
+    const err = new Error(`Project "${name}" not found in config.yaml`);
+    err.code = 'NOT_FOUND';
+    throw err;
+  }
+
+  delete parsed.projects[name];
+
+  if (fs.existsSync(configPath)) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const bak = `${configPath}.${ts}.bak`;
+    try {
+      fs.copyFileSync(configPath, bak);
+    } catch (err) {
+      console.warn('[config] Could not write backup before removing project:', err.message);
+    }
+  }
+
+  const out = yaml.stringify(parsed);
+  fs.writeFileSync(configPath, out, 'utf-8');
+  console.log(`[config] Removed project "${name}" (files on disk untouched)`);
+
+  return parsed.projects;
+}
+
 // Apply a structural patch to ~/.termdeck/config.yaml. Sprint 36 introduces
 // this for the dashboard RAG toggle (PATCH /api/config) but the helper is
 // generic — pass a deep partial of the config tree, every leaf in `patch` that
@@ -394,6 +442,7 @@ function updateConfig(patch, configPath = CONFIG_PATH) {
 module.exports = {
   loadConfig,
   addProject,
+  removeProject,
   updateConfig,
   // exported for tests / introspection
   _parseDotenv: parseDotenv,

package/packages/server/src/index.js

@@ -62,11 +62,13 @@ const { TranscriptWriter } = require('./transcripts');
 const { createHealthHandler, runPreflight } = require('./preflight');
 const { getFullHealth } = require('./health');
 const { themes, statusColors } = require('./themes');
-const { loadConfig, addProject, updateConfig } = require('./config');
+const { loadConfig, addProject, removeProject, updateConfig } = require('./config');
 const { createAuthMiddleware, verifyWebSocketUpgrade, hasAuth } = require('./auth');
 const { createSprintRoutes } = require('./sprint-routes');
 const { createGraphRoutes } = require('./graph-routes');
+const { createProjectsRoutes } = require('./projects-routes');
 const orchestrationPreview = require('./orchestration-preview');
+const { createPtyReaper } = require('./pty-reaper');
 
 // Sprint 37 T3 — lazy resolution of T2's CLI modules. The orchestration-preview
 // helper is decoupled from T2's templates.js / init-project.js; we resolve
@@ -167,6 +169,33 @@ function createServer(config) {
   // Initialize session manager
   const sessions = new SessionManager(db);
 
+  // PTY orphan reaper (Sprint 42 T2). Periodically walks the live process
+  // tree, tracks descendants of each session's shell PTY, and SIGTERMs any
+  // that survive the leader's death — closing the kern.tty.ptmx_max leak
+  // path that bit Joshua on 2026-04-28 (forkpty: Device not configured).
+  // Skipped when node-pty is unavailable (no PTYs to reap) and when the
+  // explicit kill switch is set (tests / opt-out).
+  const ptyReaperEnabled = pty
+    && process.env.TERMDECK_PTY_REAPER !== 'off'
+    && config.ptyReaper?.enabled !== false;
+  const ptyReaperIntervalMs = Number.parseInt(
+    process.env.TERMDECK_PTY_REAPER_INTERVAL_MS
+      || config.ptyReaper?.intervalMs
+      || 30000,
+    10
+  );
+  const ptyReaper = ptyReaperEnabled
+    ? createPtyReaper({ sessions, intervalMs: ptyReaperIntervalMs })
+    : null;
+  if (ptyReaper) {
+    ptyReaper.start();
+    console.log(`[pty-reaper] enabled (interval ${ptyReaperIntervalMs}ms)`);
+  } else if (!pty) {
+    console.log('[pty-reaper] disabled (node-pty unavailable)');
+  } else {
+    console.log('[pty-reaper] disabled by config');
+  }
+
   // Initialize RAG + Mnestra bridge
   const rag = new RAGIntegration(config, db);
   const mnestraBridge = createBridge(config);
@@ -1262,20 +1291,29 @@ function createServer(config) {
     res.json(payload);
   });
 
-  // POST /api/projects - add a new project on the fly, persist to config.yaml
-  // Body: { name, path, defaultTheme?, defaultCommand? }
-  // Updates both the on-disk config.yaml and the in-memory config so new
-  // sessions can select the project immediately without a server restart.
-  app.post('/api/projects', (req, res) => {
-    const { name, path: projectPath, defaultTheme, defaultCommand } = req.body || {};
-    try {
-      const updatedProjects = addProject({ name, path: projectPath, defaultTheme, defaultCommand });
-      config.projects = updatedProjects;
-      res.json({ ok: true, projects: updatedProjects });
-    } catch (err) {
-      console.error('[config] addProject failed:', err.message);
-      res.status(400).json({ error: err.message });
-    }
+  // POST /api/projects (add) + DELETE /api/projects/:name (remove) — Sprint 42
+  // T4 extracted both into projects-routes.js so tests can drive them without
+  // bootstrapping the full server. Sessions are passed via getSessions() so
+  // DELETE can enforce the 409 live-PTY guard. Files on disk at the project's
+  // `path` are NEVER touched by remove — only the YAML entry is rewritten.
+  createProjectsRoutes({
+    app,
+    config,
+    getSessions: () => sessions.getAll(),
+    addProject,
+    removeProject,
+    broadcast: (payload) => {
+      try {
+        const wsPayload = JSON.stringify(payload);
+        wss.clients.forEach((client) => {
+          if (client.readyState === 1) {
+            try { client.send(wsPayload); } catch (err) { console.error('[ws] projects_changed send failed:', err); }
+          }
+        });
+      } catch (err) {
+        console.error('[ws] projects_changed broadcast failed:', err);
+      }
+    },
   });
 
   // GET /api/projects/:name/orchestration-preview — Sprint 37 T3.
@@ -1404,6 +1442,20 @@ function createServer(config) {
     res.json({ count: events.length, events });
   });
 
+  // GET /api/pty-reaper/status — Sprint 42 T2 observability surface.
+  // Returns the live registry (per-session PTY pid + tracked descendants) and
+  // the reaped-history ring buffer so heavy-use installs can tell whether the
+  // reaper is firing and what it's killing. Read-only.
+  app.get('/api/pty-reaper/status', (req, res) => {
+    if (!ptyReaper) {
+      return res.json({
+        enabled: false,
+        reason: !pty ? 'node-pty-unavailable' : 'disabled-by-config',
+      });
+    }
+    res.json({ enabled: true, ...ptyReaper.status() });
+  });
+
   // ==================== Transcript endpoints (Sprint 6 T3) ====================
 
   // GET /api/transcripts/search - FTS across all sessions
@@ -1757,7 +1809,7 @@ function createServer(config) {
     res.sendFile(path.join(clientDir, 'index.html'));
   });
 
-  return { app, server, wss, sessions, rag, db, transcriptWriter };
+  return { app, server, wss, sessions, rag, db, transcriptWriter, ptyReaper };
 }
 
 // ==================== Setup-configure helpers (Sprint 23 T2) ====================
@@ -1975,7 +2027,7 @@ if (require.main === module) {
     }
   }
 
-  const { server, transcriptWriter } = createServer(config);
+  const { server, transcriptWriter, ptyReaper } = createServer(config);
 
   // Graceful shutdown — flush transcript buffer before exit
   let shutdownInProgress = false;
@@ -1983,6 +2035,11 @@ if (require.main === module) {
     if (shutdownInProgress) return;
     shutdownInProgress = true;
     console.log(`\n[server] ${signal} received, shutting down...`);
+    if (ptyReaper) {
+      try { ptyReaper.stop(); } catch (err) {
+        console.error('[pty-reaper] stop failed:', err.message);
+      }
+    }
     if (transcriptWriter) {
       console.log('[transcript] Flushing buffer before exit...');
       try { await transcriptWriter.close(); } catch (err) {

package/packages/server/src/projects-routes.js

@@ -0,0 +1,119 @@
+// Projects routes — POST /api/projects (add) + DELETE /api/projects/:name
+// (remove) extracted into a small factory so tests can drive them without
+// bootstrapping the full server. Sprint 42 T4.
+//
+// Surface contract:
+//
+//   POST   /api/projects                       → add (existing v0.2 behavior)
+//   DELETE /api/projects/:name[?force=true]    → remove
+//
+// DELETE semantics:
+//   - 404 if the project is not in config.yaml
+//   - 409 if any live PTY session has meta.project === name (i.e.
+//     meta.status !== 'exited'), unless ?force=true is set
+//   - On success: rewrites ~/.termdeck/config.yaml (with .bak), updates the
+//     in-memory config map, broadcasts `projects_changed` to all WS clients,
+//     and returns { ok, removed, projects, files_on_disk: 'untouched' }
+//
+// File contents at the project's `path` are NEVER touched here — the user's
+// source code stays put. The dashboard modal copy reflects this so users
+// don't fear data loss.
+
+function createProjectsRoutes({
+  app,
+  config,
+  getSessions,           // () => array of session objects with .meta.{project,status}
+  addProject,            // (opts) => updated projects map (mutates config.yaml)
+  removeProject,         // (name) => updated projects map (mutates config.yaml)
+  broadcast,             // ({ type, projects }) => void   (optional)
+}) {
+  if (!app) throw new Error('createProjectsRoutes: app is required');
+  if (typeof addProject !== 'function') throw new Error('createProjectsRoutes: addProject is required');
+  if (typeof removeProject !== 'function') throw new Error('createProjectsRoutes: removeProject is required');
+
+  const safeBroadcast = (payload) => {
+    if (typeof broadcast !== 'function') return;
+    try { broadcast(payload); }
+    catch (err) { console.error('[projects-routes] broadcast failed:', err); }
+  };
+
+  // POST /api/projects — add a project, persist to config.yaml, broadcast.
+  // Body: { name, path, defaultTheme?, defaultCommand? }
+  app.post('/api/projects', (req, res) => {
+    const { name, path: projectPath, defaultTheme, defaultCommand } = req.body || {};
+    try {
+      const updatedProjects = addProject({ name, path: projectPath, defaultTheme, defaultCommand });
+      config.projects = updatedProjects;
+      safeBroadcast({ type: 'projects_changed', projects: updatedProjects });
+      res.json({ ok: true, projects: updatedProjects });
+    } catch (err) {
+      console.error('[config] addProject failed:', err.message);
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // DELETE /api/projects/:name — remove a project. ?force=true to override
+  // the live-session 409 guard. Files on disk are untouched.
+  app.delete('/api/projects/:name', (req, res) => {
+    const name = req.params.name;
+    if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+      return res.status(400).json({ error: 'Project name must be non-empty and contain only letters, digits, . _ or -' });
+    }
+
+    const projects = (config && config.projects) || {};
+    if (!projects[name]) {
+      return res.status(404).json({ error: `Project "${name}" not found` });
+    }
+
+    const force = req.query && (req.query.force === 'true' || req.query.force === '1');
+
+    let liveSessions = [];
+    try {
+      const all = (typeof getSessions === 'function' ? getSessions() : []) || [];
+      liveSessions = all.filter((s) => {
+        if (!s || !s.meta) return false;
+        return s.meta.project === name && s.meta.status !== 'exited';
+      });
+    } catch (err) {
+      console.error('[projects-routes] getSessions failed:', err);
+      liveSessions = [];
+    }
+
+    if (liveSessions.length > 0 && !force) {
+      return res.status(409).json({
+        error: `Project "${name}" has ${liveSessions.length} live PTY session${liveSessions.length === 1 ? '' : 's'}. Close them first, or pass ?force=true.`,
+        liveSessions: liveSessions.length,
+        sessionIds: liveSessions.map((s) => s.id).filter(Boolean),
+      });
+    }
+
+    let updatedProjects;
+    try {
+      updatedProjects = removeProject(name);
+    } catch (err) {
+      if (err && err.code === 'NOT_FOUND') {
+        return res.status(404).json({ error: err.message });
+      }
+      if (err && err.code === 'BAD_NAME') {
+        return res.status(400).json({ error: err.message });
+      }
+      console.error('[config] removeProject failed:', err.message);
+      return res.status(500).json({ error: err.message });
+    }
+
+    config.projects = updatedProjects;
+    safeBroadcast({ type: 'projects_changed', projects: updatedProjects });
+
+    res.json({
+      ok: true,
+      removed: name,
+      forced: !!force,
+      projects: updatedProjects,
+      files_on_disk: 'untouched',
+    });
+  });
+}
+
+module.exports = {
+  createProjectsRoutes,
+};

package/packages/server/src/pty-reaper.js

@@ -0,0 +1,297 @@
+// PTY orphan reaper (Sprint 42 T2).
+//
+// Each TermDeck session spawns one shell PTY (`term.pid` from node-pty). That
+// shell typically forks Claude Code, which in turn forks MCP children
+// (rag-system, imessage-mcp, …). When the user closes a panel TermDeck calls
+// `term.kill()`, which delivers SIGHUP to the leader's process group — but
+// some MCPs `setsid` to detach, escape the pgroup, and survive the parent.
+// Reparented to launchd, those processes keep holding their PTY file
+// descriptors, and on macOS that drains `kern.tty.ptmx_max` (511 by default).
+// Joshua's 2026-04-28 morning incident: 585 PTY refs, `forkpty: Device not
+// configured` blocking new terminals.
+//
+// This module periodically (every 30s by default) walks the live process tree
+// and, for each known session, tracks descendants of its PTY leader. When the
+// leader is gone or the session has transitioned to `exited`, any descendants
+// that survived get SIGTERM'd and recorded to a ring buffer surfaced via
+// /api/pty-reaper/status.
+//
+// All side-effects (`ps`, `kill`, `now`, the timer) are injectable so the
+// tests in tests/pty-reaper.test.js can drive deterministic orphan scenarios
+// without forking real processes.
+//
+// Public surface:
+//   createPtyReaper({ sessions, intervalMs?, ps?, kill?, now?, logger? })
+//     → { start(), stop(), tick(), status(), _resetForTest() }
+
+const { execFileSync } = require('child_process');
+
+const RING_SIZE = 200;
+const DEFAULT_INTERVAL_MS = 30000;
+
+// Default `ps` boundary — execFileSync is sandbox-friendly (no shell).
+// `-e` lists every process; the trailing `=` on each column header suppresses
+// the header row, so the output is one process per line: "<pid> <ppid> <cmd>".
+function defaultPs() {
+  const stdout = execFileSync('ps', ['-e', '-o', 'pid=,ppid=,command='], {
+    encoding: 'utf8',
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  return parsePsOutput(stdout);
+}
+
+function parsePsOutput(stdout) {
+  const out = [];
+  const lines = stdout.split('\n');
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    // Two leading whitespace-separated integers, then the rest is command.
+    const m = line.match(/^(\d+)\s+(\d+)\s+(.*)$/);
+    if (!m) continue;
+    const pid = parseInt(m[1], 10);
+    const ppid = parseInt(m[2], 10);
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid)) continue;
+    out.push({ pid, ppid, command: m[3] });
+  }
+  return out;
+}
+
+function defaultKill(pid, signal) {
+  process.kill(pid, signal);
+}
+
+function createPtyReaper({
+  sessions,
+  intervalMs = DEFAULT_INTERVAL_MS,
+  ps = defaultPs,
+  kill = defaultKill,
+  now = Date.now,
+  logger = console,
+} = {}) {
+  if (!sessions) {
+    throw new Error('createPtyReaper: sessions (SessionManager) is required');
+  }
+
+  // Per-session registry: sessionId → { ptyPid, descendants:Set<pid>,
+  // firstSeenAt, lastSeenAliveAt }. Refreshed each tick while the leader is
+  // alive so when it dies we still know which descendants to chase.
+  const registry = new Map();
+  let reapedHistory = [];
+  let tickCount = 0;
+  let lastTickAt = null;
+  let lastError = null;
+  let timer = null;
+
+  function isoNow() {
+    return new Date(now()).toISOString();
+  }
+
+  function recordReap(entry) {
+    reapedHistory.push(entry);
+    if (reapedHistory.length > RING_SIZE) {
+      reapedHistory = reapedHistory.slice(-RING_SIZE);
+    }
+  }
+
+  function bfsDescendants(rootPid, childrenByPpid) {
+    const out = new Set();
+    const stack = [rootPid];
+    const seen = new Set([rootPid]);
+    while (stack.length) {
+      const cur = stack.pop();
+      const kids = childrenByPpid.get(cur);
+      if (!kids) continue;
+      for (const kid of kids) {
+        if (seen.has(kid.pid)) continue;
+        seen.add(kid.pid);
+        out.add(kid.pid);
+        stack.push(kid.pid);
+      }
+    }
+    return out;
+  }
+
+  function iterSessions() {
+    // SessionManager.sessions is a Map<id, Session>; iterate the values
+    // directly so we get the live Session instances (not toJSON copies).
+    if (sessions.sessions && typeof sessions.sessions.values === 'function') {
+      return Array.from(sessions.sessions.values());
+    }
+    return [];
+  }
+
+  function tick() {
+    tickCount += 1;
+    lastTickAt = isoNow();
+
+    let snapshot;
+    try {
+      snapshot = ps();
+    } catch (err) {
+      lastError = err && err.message ? err.message : String(err);
+      if (logger && logger.error) {
+        logger.error('[pty-reaper] ps() failed:', lastError);
+      }
+      return { reaped: 0, refreshed: 0, error: lastError };
+    }
+
+    if (!Array.isArray(snapshot)) snapshot = [];
+    const livePids = new Set();
+    const procByPid = new Map();
+    const childrenByPpid = new Map();
+    for (const proc of snapshot) {
+      if (!proc || !Number.isFinite(proc.pid)) continue;
+      livePids.add(proc.pid);
+      procByPid.set(proc.pid, proc);
+      const kids = childrenByPpid.get(proc.ppid);
+      if (kids) kids.push(proc);
+      else childrenByPpid.set(proc.ppid, [proc]);
+    }
+
+    let refreshed = 0;
+    let reaped = 0;
+    const liveSessionIds = new Set();
+
+    // Pass 1: refresh registry for every known session whose leader is alive.
+    for (const session of iterSessions()) {
+      if (!session || !session.id) continue;
+      liveSessionIds.add(session.id);
+      const ptyPid = session.pid;
+      if (!Number.isFinite(ptyPid)) continue;
+
+      const leaderAlive = livePids.has(ptyPid);
+      const exited = session.meta && session.meta.status === 'exited';
+
+      if (leaderAlive && !exited) {
+        const descendants = bfsDescendants(ptyPid, childrenByPpid);
+        const existing = registry.get(session.id);
+        registry.set(session.id, {
+          ptyPid,
+          descendants,
+          firstSeenAt: existing ? existing.firstSeenAt : isoNow(),
+          lastSeenAliveAt: isoNow(),
+        });
+        refreshed += 1;
+      }
+    }
+
+    // Pass 2: for each registry entry whose leader has died OR whose session
+    // has transitioned to 'exited' (or whose Session has been removed from
+    // the manager entirely), kill any descendants still alive and drop the
+    // entry. We rely on the descendant snapshot captured by the most recent
+    // refresh — once the leader is reaped we can't BFS from a dead pid.
+    for (const [sessionId, entry] of Array.from(registry.entries())) {
+      const session = sessions.get ? sessions.get(sessionId) : null;
+      const stillRegistered = liveSessionIds.has(sessionId);
+      const leaderAlive = livePids.has(entry.ptyPid);
+      const exited = session && session.meta && session.meta.status === 'exited';
+
+      if (stillRegistered && leaderAlive && !exited) continue;
+
+      const reason = !leaderAlive
+        ? 'leader_dead'
+        : exited
+          ? 'session_exited'
+          : 'session_removed';
+
+      for (const descPid of entry.descendants) {
+        if (!livePids.has(descPid)) continue;
+        const meta = procByPid.get(descPid) || { pid: descPid, ppid: null, command: '' };
+        try {
+          kill(descPid, 'SIGTERM');
+          recordReap({
+            ts: isoNow(),
+            sessionId,
+            ptyPid: entry.ptyPid,
+            pid: descPid,
+            ppid: meta.ppid,
+            command: (meta.command || '').slice(0, 200),
+            reason,
+            outcome: 'signaled',
+          });
+          reaped += 1;
+        } catch (err) {
+          // ESRCH = already dead; anything else we record but don't throw.
+          const code = err && err.code ? err.code : null;
+          recordReap({
+            ts: isoNow(),
+            sessionId,
+            ptyPid: entry.ptyPid,
+            pid: descPid,
+            ppid: meta.ppid,
+            command: (meta.command || '').slice(0, 200),
+            reason,
+            outcome: code === 'ESRCH' ? 'already_dead' : 'kill_failed',
+            error: err && err.message ? err.message : String(err),
+          });
+        }
+      }
+      registry.delete(sessionId);
+    }
+
+    return { reaped, refreshed, error: null };
+  }
+
+  function start() {
+    if (timer) return;
+    timer = setInterval(() => {
+      try {
+        tick();
+      } catch (err) {
+        lastError = err && err.message ? err.message : String(err);
+        if (logger && logger.error) {
+          logger.error('[pty-reaper] tick() threw:', lastError);
+        }
+      }
+    }, intervalMs);
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  function stop() {
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+
+  function status() {
+    const registrySnapshot = [];
+    for (const [sessionId, entry] of registry) {
+      registrySnapshot.push({
+        sessionId,
+        ptyPid: entry.ptyPid,
+        descendantPids: Array.from(entry.descendants),
+        firstSeenAt: entry.firstSeenAt,
+        lastSeenAliveAt: entry.lastSeenAliveAt,
+      });
+    }
+    return {
+      tickCount,
+      lastTickAt,
+      intervalMs,
+      lastError,
+      registry: registrySnapshot,
+      reapedCount: reapedHistory.length,
+      reapedHistory: reapedHistory.slice(),
+    };
+  }
+
+  function _resetForTest() {
+    stop();
+    registry.clear();
+    reapedHistory = [];
+    tickCount = 0;
+    lastTickAt = null;
+    lastError = null;
+  }
+
+  return { start, stop, tick, status, _resetForTest };
+}
+
+module.exports = {
+  createPtyReaper,
+  parsePsOutput,
+  RING_SIZE,
+  DEFAULT_INTERVAL_MS,
+};

package/packages/server/src/setup/index.js

@@ -10,6 +10,7 @@ module.exports = {
   yaml: require('./yaml-io'),
   supabaseUrl: require('./supabase-url'),
   migrations: require('./migrations'),
+  migrationTemplating: require('./migration-templating'),
   pgRunner: require('./pg-runner'),
   migrationRunner: require('./migration-runner'),
   preconditions: require('./preconditions')