@jhizzard/termdeck 1.2.0 → 1.4.0

package/packages/server/src/index.js

@@ -120,6 +120,45 @@ const { resolveSpawnShell } = require('./spawn-shell');
 // Code does not shell-expand MCP env values; same trap applies anywhere the
 // secrets file flows through a non-shell consumer).
 let _termdeckSecretsCache = null;
+
+// Sprint 64 T1 (ORCH SCOPE 16:29 ET item 4) — management-grade tokens that
+// MUST NEVER be merged from ~/.termdeck/secrets.env into a spawned child's
+// env. The wizard's --auto path now explicitly avoids persisting the
+// Supabase PAT here (see packages/cli/src/init.js Phase 3 + the AUDIT-RED
+// resolution comment), but a user might still paste one manually via
+// `vi ~/.termdeck/secrets.env` — defense-in-depth at the reader caps that
+// failure mode. Keys hold:
+//   • SUPABASE_ACCESS_TOKEN: Supabase PAT — org-wide management privileges
+//     (can create/delete projects, set vault secrets, deploy functions
+//     against every project in the org). Highest blast-radius credential
+//     in the standard TermDeck stack. The Mnestra hook does NOT need it
+//     (per-project SUPABASE_SERVICE_ROLE_KEY is what the hook uses), so
+//     dropping it from the PTY merge is loss-free for the running stack.
+//   • GITHUB_TOKEN / GITHUB_PAT: Personal Access Tokens for GitHub —
+//     repo write access at minimum, often org-wide. Brad's R730 likely
+//     doesn't carry one but Joshua's daily-driver does (publish wave
+//     workflow). Preventive.
+//   • OPENAI_ADMIN_KEY: OpenAI Admin key — billing/org-management.
+//     Distinct from OPENAI_API_KEY which is the per-project usage key
+//     that Mnestra DOES need. Preventive.
+//   • NPM_TOKEN: registry publish token. Preventive.
+const SECRETS_EXCLUDED_FROM_PTY = new Set([
+  'SUPABASE_ACCESS_TOKEN',
+  'GITHUB_TOKEN',
+  'GITHUB_PAT',
+  'OPENAI_ADMIN_KEY',
+  'NPM_TOKEN',
+]);
+
+// Sprint 65 T2 (2.1) — explicit operator-role whitelist for the optional
+// `role` field on POST /api/sessions (Brad's 2026-05-13 v2 dashboard spec,
+// Approach A). `null` is the valid "unroled" value; an absent field also
+// defaults to null. The dashboard renders the ORCH pin when
+// `meta.role === 'orchestrator'`; worker/reviewer/auditor are accepted now
+// for forward-compat with the canonical 3+1+1 role taxonomy. Unknown values
+// are rejected with 400 at the route. Exported for the route-fence test.
+const ALLOWED_SESSION_ROLES = ['orchestrator', 'worker', 'reviewer', 'auditor', null];
+
 function readTermdeckSecretsForPty() {
   if (_termdeckSecretsCache !== null) return _termdeckSecretsCache;
   const secretsPath = path.join(os.homedir(), '.termdeck', 'secrets.env');
@@ -137,6 +176,10 @@ function readTermdeckSecretsForPty() {
       }
       if (v.startsWith('${') && v.endsWith('}')) continue;
       if (v === '') continue;
+      // Sprint 64 T1 (ORCH SCOPE 16:29 ET item 4): EXCLUDE management-grade
+      // tokens from the PTY/child-process env merge. See
+      // SECRETS_EXCLUDED_FROM_PTY constant above for the rationale per key.
+      if (SECRETS_EXCLUDED_FROM_PTY.has(m[1])) continue;
       out[m[1]] = v;
     }
   } catch (_err) {
@@ -183,6 +226,19 @@ function _setSpawnSessionEndHookImplForTesting(fn) {
   _spawnSessionEndHookImpl = typeof fn === 'function' ? fn : _defaultSpawnSessionEndHookImpl;
 }
 
+// Sprint 64 T3 — periodic-capture spawn (Investigation 2 of
+// docs/CRITICAL-READ-FIRST-2026-05-07.md). Parallel to _spawnSessionEndHookImpl
+// but targets memory-pre-compact.js. Same indirection rationale: tests stub
+// this to capture the payload deterministically without running detached
+// children inside the test runner.
+function _defaultSpawnPeriodicCaptureHookImpl(hookPath, payload, env) {
+  return _defaultSpawnSessionEndHookImpl(hookPath, payload, env);
+}
+let _spawnPeriodicCaptureHookImpl = _defaultSpawnPeriodicCaptureHookImpl;
+function _setSpawnPeriodicCaptureHookImplForTesting(fn) {
+  _spawnPeriodicCaptureHookImpl = typeof fn === 'function' ? fn : _defaultSpawnPeriodicCaptureHookImpl;
+}
+
 // Fires when a panel's PTY exits. Routes through the adapter registry's
 // new `resolveTranscriptPath` field (10th adapter field, Sprint 50) and
 // invokes the bundled `~/.claude/hooks/memory-session-end.js` with the
@@ -240,6 +296,92 @@ async function onPanelClose(session) {
   }
 }
 
+// Sprint 64 T3.4 — periodic-capture timer for non-Claude panels.
+//
+// PreCompact only fires inside Claude Code. Codex/Gemini/Grok don't have a
+// PreCompact-equivalent — verified 2026-05-11, see docs/RESTART-PROMPT-
+// 2026-05-11.md § Sprint 64 candidates ("Codex CLI specifically lacks a pre-
+// compact hook surface — `codex --help` exposes no hooks subcommand").
+// Long sessions on those agents grow their transcripts indefinitely; without
+// a periodic snapshot to Mnestra, all of that context evaporates if the
+// process crashes BEFORE the SessionEnd hook can fire on /exit.
+//
+// Strategy: every N minutes (default 10 min, override via
+// `TERMDECK_PERIODIC_CAPTURE_INTERVAL_MS`) the timer resolves the panel's
+// on-disk transcript via the same `adapter.resolveTranscriptPath` path
+// `onPanelClose` uses, then spawns memory-pre-compact.js with
+// `mode: 'periodic_checkpoint'`. The hook handles parsing + embed + POST.
+//
+// Throttle (per the T3 brief): skip if the transcript hasn't grown by
+// >= 1 KB since the last fire. Stop firing once `meta.status === 'exited'`
+// (close-out capture covers that path).
+//
+// Skip rules mirror onPanelClose (Claude has its own PreCompact hook,
+// missing adapter / resolveTranscriptPath / hook file → no-op).
+async function onPanelPeriodicCapture(session) {
+  try {
+    if (!session || !session.meta) return;
+    if (session.meta.status === 'exited') return;
+    const adapter = AGENT_ADAPTERS[session.meta.type]
+      || Object.values(AGENT_ADAPTERS).find((a) => a.sessionType === session.meta.type);
+    if (!adapter) return;
+    if (adapter.sessionType === 'claude-code') return;
+    if (typeof adapter.resolveTranscriptPath !== 'function') return;
+
+    const transcriptPath = await adapter.resolveTranscriptPath(session);
+    if (!transcriptPath) return;
+
+    // Throttle: compare current transcript size against last-fire bookmark.
+    // 1 KB minimum delta keeps the bill bounded on quiet panels (a panel
+    // sitting idle at the prompt produces ~0 new bytes per interval).
+    let stat;
+    try { stat = fs.statSync(transcriptPath); }
+    catch (_e) { return; }
+    if (!session._periodicCapture) session._periodicCapture = { lastSize: 0, lastFireMs: 0 };
+    const grew = stat.size - session._periodicCapture.lastSize;
+    if (grew < 1024) return;
+
+    const hookPath = path.join(os.homedir(), '.claude', 'hooks', 'memory-pre-compact.js');
+    if (!fs.existsSync(hookPath)) return;
+
+    const payload = {
+      transcript_path: transcriptPath,
+      cwd: session.meta.cwd,
+      session_id: session.id,
+      sessionType: adapter.sessionType,
+      source_agent: adapter.name,
+      // Mode discriminator the hook reads in resolveFiringContext —
+      // distinguishes "TermDeck server periodic capture" from "Claude Code
+      // PreCompact harness fire."
+      mode: 'periodic_checkpoint',
+    };
+
+    _spawnPeriodicCaptureHookImpl(hookPath, payload, {
+      ...process.env,
+      ...readTermdeckSecretsForPty(),
+    });
+
+    // Update bookmark immediately — even if the spawn fails downstream we
+    // don't want to retry the same byte range on the next tick. Worst case
+    // we lose one tick; the next 1 KB of growth fires again.
+    session._periodicCapture.lastSize = stat.size;
+    session._periodicCapture.lastFireMs = Date.now();
+  } catch (err) {
+    console.error('[onPanelPeriodicCapture] error:', err && err.message ? err.message : err);
+  }
+}
+
+// Default interval (10 min). Override via env var; setting to 0 disables the
+// timer entirely. Tests pass a much smaller value (e.g. 100ms) via the env
+// var to exercise the timer path without waiting.
+function _resolvePeriodicCaptureIntervalMs() {
+  const raw = process.env.TERMDECK_PERIODIC_CAPTURE_INTERVAL_MS;
+  if (!raw) return 10 * 60 * 1000;
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n) || n < 0) return 10 * 60 * 1000;
+  return n;
+}
+
 // 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
 // them here and pass them into the helper. If a module is missing (e.g.
@@ -1107,7 +1249,15 @@ function createServer(config) {
 
   // GET /api/sessions - list all active sessions
   app.get('/api/sessions', (req, res) => {
-    res.json(sessions.getAll());
+    // Sprint 65 T2 (2.2) — exited (dead-PTY) sessions are excluded by default
+    // so an orchestrator polling this endpoint doesn't see dead panels as
+    // live (Brad's "18 windows open, 10 were dead codex cli" — BACKLOG § D.5).
+    // `?includeExited=true` returns the legacy full shape for `termdeck
+    // doctor` + debug tooling. The 2s status_broadcast is intentionally NOT
+    // filtered (it calls bare getAll()) so the dashboard's missed-exit
+    // reconciliation still has exited sessions to work from.
+    const includeExited = req.query.includeExited === 'true';
+    res.json(sessions.getAll({ includeExited }));
   });
 
   // Reusable PTY spawn + wire helper. Used by POST /api/sessions and the
@@ -1115,7 +1265,7 @@ function createServer(config) {
   // the same wiring (transcripts, RAG, Mnestra flashback) without copy-paste.
   // Returns the Session object regardless of PTY success — status will be
   // 'errored' if pty.spawn threw.
-  function spawnTerminalSession({ command, cwd, project, label, type, theme, reason }) {
+  function spawnTerminalSession({ command, cwd, project, label, type, theme, reason, role }) {
     const rawCwd = cwd || config.projects?.[project]?.path || os.homedir();
     const resolvedCwd = path.resolve(rawCwd.replace(/^~/, os.homedir()));
 
@@ -1126,29 +1276,84 @@ function createServer(config) {
       command: command || config.shell,
       cwd: resolvedCwd,
       theme: theme || config.projects?.[project]?.defaultTheme || config.defaultTheme,
-      reason: reason || 'launched via API'
+      reason: reason || 'launched via API',
+      // Sprint 65 T2 (2.1) — explicit operator role. Route validation has
+      // already rejected unknown values; here `undefined`/`null` → null.
+      role: role || null,
     });
 
     if (pty) {
-      // Three launch shapes:
+      // Four launch shapes (Sprint 64 T2 carve-out 2.4 extends the original three):
       //   (1) no command            → spawn the default shell interactively
       //   (2) command is a plain shell name (zsh, bash, fish, ...)
       //                             → spawn THAT shell interactively, no -c wrapper
       //                               (otherwise `zsh -c zsh` exits immediately)
-      //   (3) command is a real command string
+      //   (3) command exactly matches a known agent-adapter binary AND that
+      //       adapter declares `spawn.shellWrap === false`
+      //                             → spawn the adapter's binary directly with
+      //                               its declared defaultArgs + env merge, no
+      //                               shell wrapper. Closes Sprint 63
+      //                               EXIT-CAPTURE-VERIFICATION.md § 6 (the
+      //                               `zsh -c codex` wrap that likely cost the
+      //                               codex canary panel its interactive-TTY
+      //                               context during the 2026-05-11 update-picker
+      //                               event). The exact-binary gate preserves
+      //                               user-supplied flags like `claude --resume
+      //                               <uuid>` — those still fall through to (4).
+      //   (4) command is a real command string
       //                             → spawn default shell with -c <command>
       const cmdTrim = (command || '').trim();
       const PLAIN_SHELLS = /^(zsh|bash|fish|sh|dash|tcsh|ksh|csh|pwsh|powershell)$/i;
       const isPlainShell = PLAIN_SHELLS.test(cmdTrim);
 
+      // Sprint 64 T2 (carve-out 2.4) — resolve the matching agent adapter from
+      // the command string. Walk the registry in declaration order; the first
+      // adapter whose `matches(command)` returns true claims the spawn. We
+      // honor `adapter.spawn.shellWrap === false` ONLY when the trimmed command
+      // is exactly the adapter's binary name (no extra args). User-supplied
+      // flags like `codex resume <id>` keep the legacy `zsh -c <command>` path
+      // so we don't silently drop their args.
+      let directSpawnAdapter = null;
+      if (cmdTrim && !isPlainShell) {
+        for (const adapter of Object.values(AGENT_ADAPTERS)) {
+          if (!adapter || typeof adapter.matches !== 'function') continue;
+          if (!adapter.matches(cmdTrim)) continue;
+          const spawnDecl = adapter.spawn;
+          if (!spawnDecl || spawnDecl.shellWrap !== false) continue;
+          const binary = spawnDecl.binary;
+          if (typeof binary !== 'string' || binary.length === 0) continue;
+          // Exact-binary gate: only switch to direct-spawn for bare-binary
+          // launches. `codex --resume xyz` falls through to the shell-wrap path.
+          if (cmdTrim !== binary) continue;
+          directSpawnAdapter = adapter;
+          break;
+        }
+      }
+
       // Sprint 59 T2 — Brad #5: resolveSpawnShell chains config.shell →
       // $SHELL → /bin/sh so a host without zsh (Alpine, minimal Ubuntu after
       // `apt remove zsh`) still spawns a working interactive shell instead of
       // failing silently from execvp(/bin/zsh).
-      const spawnShell = isPlainShell
-        ? cmdTrim
-        : resolveSpawnShell('', config.shell, process.env.SHELL);
-      const args = (cmdTrim && !isPlainShell) ? ['-c', cmdTrim] : [];
+      let spawnShell;
+      let args;
+      let adapterSpawnEnv = {};
+      if (directSpawnAdapter) {
+        const decl = directSpawnAdapter.spawn;
+        spawnShell = decl.binary;
+        args = Array.isArray(decl.defaultArgs) ? decl.defaultArgs.slice() : [];
+        // Adapter-declared env overlays (e.g. grok's GROK_MODEL). Empty/`undefined`
+        // values are filtered so they don't shadow process.env.
+        if (decl.env && typeof decl.env === 'object') {
+          for (const [k, v] of Object.entries(decl.env)) {
+            if (typeof v === 'string' && v.length > 0) adapterSpawnEnv[k] = v;
+          }
+        }
+      } else {
+        spawnShell = isPlainShell
+          ? cmdTrim
+          : resolveSpawnShell('', config.shell, process.env.SHELL);
+        args = (cmdTrim && !isPlainShell) ? ['-c', cmdTrim] : [];
+      }
 
       try {
         // Sprint 48 T4: merge ~/.termdeck/secrets.env into the PTY env so
@@ -1163,6 +1368,17 @@ function createServer(config) {
             secretFallback[k] = v;
           }
         }
+        // Sprint 64 T2 (carve-out 2.3) — codex pre-spawn version probe.
+        // Fire-and-forget; never blocks spawn. WARN-only when
+        // CODEX_PINNED_VERSION drifts from observed (default install: no probe
+        // comparison, no warning). See codex.js `probeCodexVersion` for full
+        // rationale.
+        if (directSpawnAdapter && directSpawnAdapter.name === 'codex'
+            && typeof directSpawnAdapter.probeCodexVersion === 'function') {
+          try {
+            directSpawnAdapter.probeCodexVersion();
+          } catch (_probeErr) { /* fail-soft */ }
+        }
         const term = pty.spawn(spawnShell, args, {
           name: 'xterm-256color',
           cols: 120,
@@ -1171,6 +1387,12 @@ function createServer(config) {
           env: {
             ...process.env,
             ...secretFallback,
+            // Sprint 64 T2 (carve-out 2.4) — adapter-declared env overlays
+            // (e.g. grok's `GROK_MODEL`, codex's `OPENAI_API_KEY` pass-through)
+            // land last so they win over process.env defaults on direct-spawn.
+            // For shell-wrap launches `adapterSpawnEnv` is empty; this is a
+            // no-op spread.
+            ...adapterSpawnEnv,
             TERMDECK_SESSION: session.id,
             TERMDECK_PROJECT: project || '',
             TERM: 'xterm-256color',
@@ -1188,6 +1410,61 @@ function createServer(config) {
         session.pty = term;
         session.pid = term.pid;
         session.meta.status = 'active';
+        // Sprint 64 T2 (carve-out 2.4 closure) — when direct-spawn matched
+        // a known adapter, promote `session.meta.type` from its `'shell'`
+        // default to the adapter's canonical `sessionType` immediately. Two
+        // downstream paths benefit:
+        //   • T3's periodic-capture timer (Sprint 64) looks up
+        //     `getAdapterForSessionType(session.meta.type)` at session-create
+        //     time — without this promotion, a bare `command:'codex'` launch
+        //     stays as `meta.type='shell'` until adapter output triggers
+        //     auto-detect, and the periodic timer never registers
+        //     (T4-CODEX 2026-05-14 16:25/16:31 AUDIT-CONCERN).
+        //   • `getAdapterForSessionType` callers in session.js' output
+        //     analyzer (`_updateStatus`) get the right pattern set on the
+        //     very first PTY chunk instead of waiting for the auto-detect
+        //     branch.
+        // Only promotes when the caller didn't already specify a concrete
+        // type (i.e., `meta.type === 'shell'`) so explicit requests are
+        // never overridden.
+        if (directSpawnAdapter && session.meta.type === 'shell') {
+          session.meta.type = directSpawnAdapter.sessionType;
+        }
+        // Sprint 64 T2 (carve-out 2.1) — strict spawn timestamp consumed by
+        // codex.js `resolveTranscriptPath` to gate rollout-file candidates
+        // against cross-panel contamination. `session.meta.createdAt` is set
+        // earlier in `sessions.create()` and predates `pty.spawn` by O(ms);
+        // `spawnTimestampMs` captures the actual fork-time so we can reject
+        // pre-spawn rollout files even when another panel's mtime briefly
+        // races past createdAt. See `packages/server/src/agent-adapters/codex.js`
+        // header for the bug shape.
+        session.meta.spawnTimestampMs = Date.now();
+
+        // Sprint 64 T3.4 — register the periodic-capture timer for non-Claude
+        // panels. Claude Code uses the PreCompact hook (Investigation 2
+        // primary signal) — the timer below is the orthogonal fallback for
+        // Codex/Gemini/Grok which have no equivalent harness hook. Cleared
+        // in term.onExit below. Disabled when the interval env var is set
+        // to 0.
+        try {
+          const adapter = AGENT_ADAPTERS[session.meta.type]
+            || Object.values(AGENT_ADAPTERS).find((a) => a.sessionType === session.meta.type);
+          const isNonClaudeAdapter = adapter
+            && adapter.sessionType !== 'claude-code'
+            && typeof adapter.resolveTranscriptPath === 'function';
+          const intervalMs = _resolvePeriodicCaptureIntervalMs();
+          if (isNonClaudeAdapter && intervalMs > 0) {
+            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);
+              });
+            }, intervalMs);
+            // Don't keep the event loop alive solely for this timer — the PTY
+            // / WS / HTTP listeners are the real lifetime anchors.
+            if (session._periodicCapture.timer.unref) session._periodicCapture.timer.unref();
+          }
+        } catch (_periodicErr) { /* fail-soft */ }
 
         // PTY output → analyze + broadcast to WebSocket + transcript archive
         term.onData((data) => {
@@ -1211,6 +1488,10 @@ function createServer(config) {
         term.onExit(({ exitCode, signal }) => {
           session.meta.status = 'exited';
           session.meta.exitCode = exitCode;
+          // Sprint 65 T2 (2.4) — stamp the exit timestamp so the panel_exited
+          // WS frame (below) and the 410 body on POST .../input can both
+          // report when the panel died.
+          session.meta.exitedAt = new Date().toISOString();
           session.meta.statusDetail = `Exited (${exitCode})${signal ? `, signal ${signal}` : ''}`;
 
           if (session.ws && session.ws.readyState === 1) {
@@ -1221,11 +1502,47 @@ function createServer(config) {
             }));
           }
 
+          // Sprint 65 T2 (2.4) — broadcast panel_exited to ALL dashboard WS
+          // clients so the grid can auto-remove the dead tile (Brad's
+          // 2026-05-12 item 2b — CLI panels must auto-close on PTY exit).
+          // Distinct from the `exit` frame above, which targets ONLY this
+          // panel's own socket; panel_exited goes to every connected client
+          // because any of them may be rendering this tile in its grid.
+          // Inlined wss.clients broadcast — same idiom as status_broadcast /
+          // config_changed / projects_changed elsewhere in this file.
+          try {
+            const exitPayload = JSON.stringify({
+              type: 'panel_exited',
+              sessionId: session.id,
+              exitCode,
+              signal: signal || null,
+              exitedAt: session.meta.exitedAt,
+            });
+            wss.clients.forEach((client) => {
+              if (client.readyState === 1) {
+                try { client.send(exitPayload); }
+                catch (err) { console.error('[ws] panel_exited send failed:', err); }
+              }
+            });
+          } catch (err) {
+            console.error('[ws] panel_exited broadcast failed:', err);
+          }
+
           rag.onSessionEnded(session);
 
           // Fire-and-forget session log (T2.5)
           writeSessionLog({ session, config, db, getSessionHistory });
 
+          // Sprint 64 T3.4 — clear the periodic-capture timer first so a
+          // tick mid-teardown doesn't race onPanelClose. The bookmark stays
+          // on `session._periodicCapture.lastSize` for any future inspection
+          // (test fixtures consult it post-exit).
+          if (session._periodicCapture && session._periodicCapture.timer) {
+            try { clearInterval(session._periodicCapture.timer); }
+            catch (_clrErr) { /* fail-soft */ }
+            session._periodicCapture.timer = null;
+          }
+
           // Sprint 50 T1 — fire the bundled SessionEnd hook for non-Claude
           // panels so Codex / Gemini / Grok /exits write to Mnestra the way
           // Claude Code already does. onPanelClose handles dispatch +
@@ -1396,8 +1713,17 @@ function createServer(config) {
 
   // POST /api/sessions - create a new terminal session
   app.post('/api/sessions', (req, res) => {
-    const { command, cwd, project, label, type, theme, reason } = req.body || {};
-    const session = spawnTerminalSession({ command, cwd, project, label, type, theme, reason });
+    const { command, cwd, project, label, type, theme, reason, role } = req.body || {};
+    // Sprint 65 T2 (2.1) — validate the optional explicit operator-role flag
+    // (Approach A). An absent field (`undefined`) is fine — it defaults to
+    // null in spawnTerminalSession. Any present value must be in the
+    // whitelist (case-sensitive exact match; `null` is allowed). Unknown
+    // values are a 400 so a typo'd role surfaces immediately rather than
+    // silently rendering as an unroled panel.
+    if (role !== undefined && !ALLOWED_SESSION_ROLES.includes(role)) {
+      return res.status(400).json({ ok: false, code: 'invalid_role', allowed: ALLOWED_SESSION_ROLES });
+    }
+    const session = spawnTerminalSession({ command, cwd, project, label, type, theme, reason, role });
     res.status(201).json(session.toJSON());
   });
 
@@ -1462,8 +1788,25 @@ function createServer(config) {
   app.post('/api/sessions/:id/input', (req, res) => {
     const session = sessions.get(req.params.id);
     if (!session) return res.status(404).json({ error: 'Session not found' });
+    // Sprint 65 T2 (2.3) — inject to a dead panel returns 410 Gone, not the
+    // pre-Sprint-65 silent 404. The orchestrator POSTing to an exited panel
+    // (Brad's D.5 item 3 — "10 dead codex cli") got a 404 that reads as
+    // "session never existed"; 410 = "the resource was here, has been
+    // intentionally removed" — the semantically correct + debuggable signal.
+    // Mirrors POST /api/sessions/:id/resize (Sprint 63). The body carries
+    // `error` (backward-compat with the client api()/sendReply() path that
+    // treats a missing `.error` as success — T4-CODEX 19:44) AND `code`
+    // (programmatic discriminator) AND `ok:false`.
     if (session.meta.status === 'exited' || !session.pty) {
-      return res.status(404).json({ error: 'Session is exited' });
+      const msg = `Panel ${req.params.id} has exited`;
+      return res.status(410).json({
+        ok: false,
+        code: 'panel_exited',
+        error: msg,
+        message: msg,
+        exitCode: session.meta.exitCode ?? null,
+        exitedAt: session.meta.exitedAt || null,
+      });
     }
 
     const { text, source, fromSessionId } = req.body || {};
@@ -2702,9 +3045,18 @@ module.exports = {
   // Sprint 48 T4 — exported for unit testing the secrets.env → PTY env merge.
   readTermdeckSecretsForPty,
   _resetTermdeckSecretsCache,
+  // Sprint 64 T1 (ORCH SCOPE 16:29 item 4) — management-token exclusion list.
+  // Exported for `packages/cli/tests/spawn-env-exclusion.test.js` fence.
+  SECRETS_EXCLUDED_FROM_PTY,
+  // Sprint 65 T2 (2.1) — operator-role whitelist, exported for the route fence.
+  ALLOWED_SESSION_ROLES,
   // Sprint 50 T1 — exported for unit testing the per-agent SessionEnd
   // hook trigger (skip-claude, no-transcript, no-hook-installed,
   // payload shape, fire-and-forget).
   onPanelClose,
   _setSpawnSessionEndHookImplForTesting,
+  // Sprint 64 T3.4 — periodic-capture surface (Investigation 2 closure).
+  onPanelPeriodicCapture,
+  _setSpawnPeriodicCaptureHookImplForTesting,
+  _resolvePeriodicCaptureIntervalMs,
 };

package/packages/server/src/session.js

@@ -162,6 +162,13 @@ class Session {
     this.meta = {
       type: options.type || 'shell',        // shell, claude-code, gemini, python-server, one-shot
       project: options.project || null,
+      // Sprint 65 T2 (2.1) — explicit operator role (Approach A). One of
+      // orchestrator / worker / reviewer / auditor / null. Set at spawn time
+      // via POST /api/sessions (route-validated against ALLOWED_SESSION_ROLES);
+      // flows through status_broadcast unchanged so the dashboard can pin the
+      // ORCH panel. Distinct from `type` (the agent CLI) — role is operator
+      // intent, type is the running program.
+      role: options.role || null,
       label: options.label || '',
       command: options.command || '',
       cwd: options.cwd || os.homedir(),
@@ -575,8 +582,8 @@ class SessionManager {
     //                     a PATCH from the dropdown sets it (see updateMeta).
     if (this.db) {
       this.db.prepare(`
-        INSERT INTO sessions (id, type, project, label, command, cwd, created_at, reason, theme, theme_override)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        INSERT INTO sessions (id, type, project, label, command, cwd, created_at, reason, theme, theme_override, role)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `).run(
         session.id,
         session.meta.type,
@@ -587,7 +594,8 @@ class SessionManager {
         session.meta.createdAt,
         session.meta.reason,
         session.meta.theme,           // resolved snapshot, legacy column
-        session.theme_override        // NULL by default
+        session.theme_override,       // NULL by default
+        session.meta.role             // Sprint 65 T2 — operator role, NULL by default
       );
     }
 
@@ -599,8 +607,20 @@ class SessionManager {
     return this.sessions.get(id);
   }
 
-  getAll() {
-    return Array.from(this.sessions.values()).map(s => s.toJSON());
+  // Sprint 65 T2 (2.2) — `opts.includeExited` controls whether PTY-exited
+  // sessions appear in the listing. Default is legacy (include everything):
+  // the 2s status_broadcast (index.js:2675) and the projects-route live-PTY
+  // guard both call bare getAll() and must keep seeing the full set. Only
+  // GET /api/sessions opts into the filtered view (default on at the route).
+  // Brad's "18 windows open, 10 were dead codex cli" report (BACKLOG § D.5)
+  // is the orchestrator polling /api/sessions and seeing dead panels as live.
+  getAll(opts = {}) {
+    const all = Array.from(this.sessions.values());
+    const includeExited = opts.includeExited !== false;
+    const visible = includeExited
+      ? all
+      : all.filter((s) => s.meta.status !== 'exited');
+    return visible.map((s) => s.toJSON());
   }
 
   // Fields a client is allowed to modify via PATCH /api/sessions/:id.

package/packages/server/src/setup/supabase-mcp.js

@@ -17,6 +17,34 @@ const DEFAULT_TIMEOUT_MS = 8000;
 const PACKAGE_SPEC = '@supabase/mcp-server-supabase';
 const BINARY_NAME = 'mcp-server-supabase';
 
+// Sprint 64 T1 — source-side credential redaction per ORCH SCOPE 16:14 ET.
+//
+// JSON-RPC error messages and child stderr tails from the MCP server may
+// echo back the JWT (anon/service_role keys) or the Supabase PAT that the
+// caller passed in. Wrapping every error string with `redactSecrets()`
+// before throwing prevents accidental leakage into stderr / logs at the
+// source — defense-in-depth complementing caller-side
+// `sanitizeErrorForLogs()` in `packages/cli/src/mcp-supabase-provision.js`.
+//
+// Patterns (greedy match — longest token wins):
+//   • JWT-shaped (anon / service_role keys) — `eyJ<>.<>.<>` triple-base64
+//     with `[A-Za-z0-9_-]{10,}` per segment. Lower bound at 10 chars per
+//     segment avoids false-positive matches on three-part JSON identifiers.
+//   • PAT-shaped (`sbp_...`) — Supabase Personal Access Tokens start with
+//     `sbp_` and carry 40+ URL-safe characters.
+//
+// Output replaces matches with `[REDACTED:JWT]` / `[REDACTED:PAT]` so a
+// downstream caller can see WHAT shape was redacted without seeing the value.
+const JWT_PATTERN = /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g;
+const PAT_PATTERN = /sbp_[A-Za-z0-9]{40,}/g;
+
+function redactSecrets(message) {
+  if (typeof message !== 'string' || message.length === 0) return message;
+  return message
+    .replace(JWT_PATTERN, '[REDACTED:JWT]')
+    .replace(PAT_PATTERN, '[REDACTED:PAT]');
+}
+
 // Detect whether @supabase/mcp-server-supabase can be invoked on this host.
 // Resolution order:
 //   1. A globally installed `mcp-server-supabase` binary on PATH.
@@ -167,8 +195,12 @@ async function callTool(pat, method, params, opts) {
         }
         if (msg && msg.id === id) {
           if (msg.error) {
+            // Sprint 64 T1 (ORCH SCOPE 16:14 ET): redact JWT / PAT-shaped
+            // substrings from the propagated error message before throwing.
+            // Source-side defense; complements caller-side
+            // `sanitizeErrorForLogs()` in mcp-supabase-provision.js.
             const detail = msg.error.message || JSON.stringify(msg.error);
-            settle(reject, new Error(detail));
+            settle(reject, new Error(redactSecrets(detail)));
           } else {
             settle(resolve, msg.result);
           }
@@ -179,7 +211,11 @@ async function callTool(pat, method, params, opts) {
 
     child.on('exit', (code, signal) => {
       if (settled) return;
-      const tail = stderrBuf.slice(-512).trim();
+      // Sprint 64 T1 (ORCH SCOPE 16:14 ET): redact JWT / PAT-shaped
+      // substrings from the stderr tail before throwing. A misbehaving
+      // MCP child could echo back the SUPABASE_ACCESS_TOKEN env or one of
+      // the keys we passed in via params; the redact pass scrubs them.
+      const tail = redactSecrets(stderrBuf.slice(-512).trim());
       const why = signal ? `signal=${signal}` : `code=${code}`;
       settle(reject, new Error(`mcp exited (${why})${tail ? ': ' + tail : ''}`));
     });
@@ -192,4 +228,7 @@ async function callTool(pat, method, params, opts) {
   });
 }
 
-module.exports = { callTool, detectMcp };
+module.exports = { callTool, detectMcp, redactSecrets };
+// Sprint 64 T1 — exposed for fence tests in packages/cli/tests/mcp-supabase-provision.test.js.
+module.exports.JWT_PATTERN = JWT_PATTERN;
+module.exports.PAT_PATTERN = PAT_PATTERN;