@tekyzinc/gsd-t 3.21.11 → 3.21.12

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.21.12] - 2026-05-06
+
+### Fixed — dashboard orphan accumulation (M49 lazy autostart + idle-TTL + doctor-prune)
+
+88 dead `gsd-t-dashboard-server.js` processes accumulated under v3.21.11 (164 under v3.20.13). Root cause: `bin/headless-auto-spawn.cjs::autoSpawnHeadless()` called `ensureDashboardRunning()` on every spawn, fork-detaching a fresh dashboard for every gsd-t-execute / gsd-t-debug / gsd-t-wave invocation across any project across any session. 99% of those autostarted dashboards are never opened by the user (the live-transcript URL banner is just-in-case observability), so they accumulated on the project-scoped port range 7433–7532 until the user manually killed them.
+
+**Changes:**
+- `bin/headless-auto-spawn.cjs::autoSpawnHeadless()`: removed the `ensureDashboardRunning()` call. Spawns no longer autostart dashboards. New synchronous `_probeDashboardLazy(projectDir)` reads `.gsd-t/.dashboard.pid` and verifies the pid is alive via `process.kill(pid, 0)` (cheap; runs on every spawn). Banner is now conditional:
+  - Dashboard running: `▶ Live transcript: http://127.0.0.1:{port}/transcript/{spawn-id}` (existing M43 D6-T3 shape).
+  - No dashboard: `▶ Transcript file: {logPath}\n  (to view live: gsd-t-visualize)` — points at the on-disk log + tells the user how to open the dashboard if they want it.
+- `scripts/gsd-t-dashboard-server.js`: idle-TTL self-shutdown. Default 4 hours, configurable via env `GSD_T_DASHBOARD_IDLE_TTL_MS` or `--idle-ttl-ms` flag. "Idle" means zero HTTP requests AND zero active SSE connections for the full TTL window. setInterval check every 60s; on shutdown, removes `.gsd-t/.dashboard.pid` so the lazy probe sees a clean state. SSE-active dashboards never exit — `_wrapSseHandler` increments/decrements an active-connection counter on req/res `close` events.
+- `bin/gsd-t.js doctor`: new `Dashboard Orphans` check + `--prune` flag. Scans for live `gsd-t-dashboard-server.js` processes via `ps -eo pid,command`; cross-references each pid against pidfiles in cwd, `GSD_T_PROJECT_DIR`, and the registered-projects list. Reports orphans (process running, pidfile missing or mismatched). With `--prune`, sends SIGTERM to each orphan. Recovery for any orphans that piled up under earlier versions.
+- `commands/gsd-t-visualize.md` (unchanged): the explicit user opt-in path still calls `ensureDashboardRunning()` via `--detach` — the dashboard starts when (and only when) the user runs `/gsd-t-visualize`.
+
+**Tests:**
+- `test/m49-lazy-dashboard.test.js` (9): probe correctness across 5 pidfile states (missing / dead / live / garbage / empty), probe speed (< 50ms for 100 calls), `autoSpawnHeadless` does NOT invoke `ensureDashboardRunning` (require-cache stub), URL banner shape when running, file-path banner shape when not running.
+- `test/m49-dashboard-idle-ttl.test.js` (7): `tracker.bump` resets `lastActivity`, SSE connect/disconnect counter, TTL fires when window elapses with no SSE, TTL does NOT fire while `activeSseConnections > 0`, recent `bump` prevents fire, `_wrapSseHandler` tracks idempotently on close, `startServer` accepts `idleTtlMs` opt without crashing.
+- `test/m49-doctor-orphan-check.test.js` (4): no-process baseline, fake-dashboard process detected as orphan, `--prune` actually kills the orphan PID, tracked dashboard (pidfile lists pid) is NOT an orphan.
+- `test/m43-url-banner.test.js`: updated for M49 — file-path banner expected by default; URL banner exercised with a pre-written pidfile pointing at the test runner's pid (proxy for "live").
+
+**Migration:** existing autostarted dashboards stay running until they hit the 4h idle-TTL or are pruned via `gsd-t doctor --prune`. New spawns no longer add to the count. Re-running `/gsd-t-visualize` continues to work as before.
+
+**Suite:** 2103/2105 (2 pre-existing env-sensitive flakes preserved per M47/M48 baseline). +20 new M49 tests, 0 regressions.
+
 ## [3.21.11] - 2026-05-06
 
 ### Fixed — viewer: 4 rendering regressions surfaced post-M47

package/bin/gsd-t.js

@@ -2758,7 +2758,145 @@ async function checkDoctorContextMeter(projectDir) {
   return issues;
 }
 
-async function doDoctor() {
+// M49 — Detect dashboard server processes whose pidfile is missing or
+// mismatched ("orphans"). The lazy-dashboard + idle-TTL changes prevent new
+// orphans from accumulating, but recovery is still needed for any that piled
+// up under earlier versions. With `--prune`, kills the orphan PIDs.
+//
+// "Orphan" = a `gsd-t-dashboard-server.js` process whose pidfile (at
+// `{projectDir}/.gsd-t/.dashboard.pid` resolved from the process's cwd / the
+// `GSD_T_PROJECT_DIR` env / the registered-projects list) doesn't list the pid.
+//
+// Detection is best-effort across platforms — `ps` shape varies. We use:
+//   - macOS / Linux:  `ps -eo pid,command` (no `=`-stripped header)
+//   - Windows:        unsupported here (logged as N/A)
+//
+// Returns an issue count (0 if clean, 1 if orphans found and not pruned).
+function checkDoctorDashboardOrphans(opts) {
+  const prune = !!(opts && opts.prune);
+  let issues = 0;
+  heading("Dashboard Orphans");
+
+  if (process.platform === "win32") {
+    info("Skipping (Windows process inventory not yet supported)");
+    return 0;
+  }
+
+  let psOut;
+  try {
+    psOut = execFileSync("ps", ["-eo", "pid,command"], {
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch {
+    warn("Could not run `ps -eo pid,command` — orphan detection skipped");
+    return 0;
+  }
+
+  const dashPids = [];
+  for (const line of psOut.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    if (!t.includes("gsd-t-dashboard-server.js")) continue;
+    if (t.includes("ps -eo")) continue; // never list ourselves
+    if (t.includes("grep")) continue;
+    const m = t.match(/^(\d+)\s+(.+)$/);
+    if (!m) continue;
+    const pid = parseInt(m[1], 10);
+    if (!Number.isFinite(pid) || pid <= 0) continue;
+    // Red Team — only treat as a dashboard process if the first argv token is
+    // a `node`-flavored binary AND the second token ends with the script
+    // filename. Filters out e.g. `cat gsd-t-dashboard-server.js`,
+    // `vim gsd-t-dashboard-server.js`, etc. that happen to mention the path.
+    const argv = m[2].trim().split(/\s+/);
+    if (argv.length < 2) continue;
+    const exe = argv[0];
+    const script = argv[1] || "";
+    const exeIsNode = /(^|\/)node([0-9.]+)?$/.test(exe);
+    const scriptMatches = script.endsWith("gsd-t-dashboard-server.js");
+    if (!exeIsNode || !scriptMatches) continue;
+    dashPids.push({ pid, cmd: m[2] });
+  }
+
+  if (dashPids.length === 0) {
+    success("No dashboard processes running");
+    return 0;
+  }
+
+  // Collect candidate pidfiles. We probe (a) cwd + GSD_T_PROJECT_DIR for the
+  // current shell, (b) each registered project. Each contributes one
+  // {projectDir → pidfile pid} mapping. An orphan is a live dashboard pid
+  // that doesn't match any pidfile we found.
+  const projects = new Set();
+  projects.add(process.cwd());
+  if (process.env.GSD_T_PROJECT_DIR) projects.add(process.env.GSD_T_PROJECT_DIR);
+  try {
+    for (const p of getRegisteredProjects()) projects.add(p);
+  } catch { /* registry may not exist */ }
+
+  const knownPids = new Set();
+  for (const proj of projects) {
+    const pidFile = path.join(proj, ".gsd-t", ".dashboard.pid");
+    try {
+      const raw = fs.readFileSync(pidFile, "utf8").trim();
+      const pid = parseInt(raw, 10);
+      if (Number.isFinite(pid) && pid > 0) knownPids.add(pid);
+    } catch { /* missing or unreadable */ }
+    // Also accept the older M38 pidfile (no leading dot).
+    const legacyPidFile = path.join(proj, ".gsd-t", "dashboard.pid");
+    try {
+      const raw = fs.readFileSync(legacyPidFile, "utf8").trim();
+      const pid = parseInt(raw, 10);
+      if (Number.isFinite(pid) && pid > 0) knownPids.add(pid);
+    } catch { /* missing */ }
+  }
+
+  const orphans = dashPids.filter((d) => !knownPids.has(d.pid));
+
+  log(`  Detected ${dashPids.length} dashboard process${dashPids.length === 1 ? "" : "es"} ` +
+      `(${knownPids.size} tracked via pidfile, ${orphans.length} orphan${orphans.length === 1 ? "" : "s"})`);
+
+  if (orphans.length === 0) {
+    success("No orphans");
+    return 0;
+  }
+
+  for (const o of orphans) {
+    log(`  ${YELLOW}orphan${RESET} pid=${o.pid}`);
+  }
+
+  if (prune) {
+    let killed = 0;
+    let failed = 0;
+    for (const o of orphans) {
+      try {
+        process.kill(o.pid, "SIGTERM");
+        killed++;
+      } catch (err) {
+        if (err && err.code === "ESRCH") {
+          // Already gone — count as success.
+          killed++;
+        } else {
+          failed++;
+        }
+      }
+    }
+    if (failed === 0) {
+      success(`Pruned ${killed} orphan${killed === 1 ? "" : "s"}`);
+    } else {
+      warn(`Pruned ${killed}, failed ${failed}`);
+      issues++;
+    }
+  } else {
+    info("Run `gsd-t doctor --prune` to kill orphans");
+    issues++;
+  }
+
+  return issues;
+}
+
+async function doDoctor(opts) {
   heading("GSD-T Doctor");
   log("");
   let issues = 0;
@@ -2767,6 +2905,7 @@ async function doDoctor() {
   issues += checkDoctorProject();
   issues += checkDoctorCgc();
   issues += await checkDoctorContextMeter(process.cwd());
+  issues += checkDoctorDashboardOrphans(opts);
   log("");
   if (issues === 0) {
     log(`${GREEN}${BOLD}  All checks passed!${RESET}`);
@@ -3881,7 +4020,7 @@ function showHelp() {
   log(`  ${CYAN}register${RESET}       Register current directory as a GSD-T project`);
   log(`  ${CYAN}status${RESET}         Show installation status + check for updates`);
   log(`  ${CYAN}uninstall${RESET}      Remove GSD-T commands (keeps project files)`);
-  log(`  ${CYAN}doctor${RESET}         Diagnose common issues`);
+  log(`  ${CYAN}doctor${RESET}         Diagnose common issues (use --prune to kill dashboard orphans)`);
   log(`  ${CYAN}changelog${RESET}      Open changelog in the browser`);
   log(`  ${CYAN}graph${RESET}          Code graph operations (index, status, query)`);
   log(`  ${CYAN}headless${RESET}       Non-interactive execution via claude -p + fast state queries`);
@@ -3946,6 +4085,8 @@ module.exports = {
   checkDoctorClaudeMd,
   checkDoctorSettings,
   checkDoctorEncoding,
+  checkDoctorDashboardOrphans,
+  doDoctor,
   mergeGsdtSection,
   migrateToMarkers,
   appendGsdtToClaudeMd,
@@ -4034,9 +4175,14 @@ if (require.main === module) {
     case "uninstall":
       doUninstall();
       break;
-    case "doctor":
-      doDoctor().catch((e) => { error(e.message || String(e)); process.exit(1); });
+    case "doctor": {
+      const doctorOpts = { prune: false };
+      for (let i = 1; i < args.length; i++) {
+        if (args[i] === "--prune") doctorOpts.prune = true;
+      }
+      doDoctor(doctorOpts).catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
+    }
     case "changelog":
       doChangelog();
       break;

package/bin/headless-auto-spawn.cjs

@@ -55,6 +55,8 @@ module.exports = {
   // it now unconditionally returns true. See headless-default-contract
   // v2.0.0 §Invariants.
   shouldSpawnHeadless: () => true,
+  // M49 — exported for tests. Synchronous probe; never throws.
+  _probeDashboardLazy,
 };
 
 // M43 D4 — one-shot deprecation banner when a caller still passes `watch`
@@ -126,16 +128,18 @@ function autoSpawnHeadless(opts) {
   ensureDir(path.join(projectDir, LOG_DIR_REL));
   ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
 
-  // M43 D6-T4 — Ensure dashboard is running (idempotent; no-op if already up).
-  // Must happen BEFORE the URL banner print (D6-T3) so the link is live.
-  // Never throws — autostart is best-effort.
-  let autostartInfo = null;
-  try {
-    const { ensureDashboardRunning } = require("../scripts/gsd-t-dashboard-autostart.cjs");
-    autostartInfo = ensureDashboardRunning({ projectDir });
-  } catch (_) {
-    /* best-effort; fall through without banner port info */
-  }
+  // M49 — Lazy dashboard. Spawns no longer autostart the dashboard. Each
+  // spawn would otherwise fork-detach a fresh `gsd-t-dashboard-server.js`
+  // (M43 D6-T4); 99% of those banners are never opened so they accumulated
+  // to 88+ orphans on the project-scoped port range. The dashboard now only
+  // starts when the user explicitly invokes `/gsd-t-visualize`. The banner
+  // below remains, but becomes conditional on whether a dashboard is already
+  // listening on the project's scoped port.
+  //
+  // Probe is sync + cheap: read `.gsd-t/.dashboard.pid` and `process.kill(pid, 0)`.
+  // Falls back to "no dashboard" on any error — never throws.
+  // See .gsd-t/contracts/headless-default-contract.md v2.0.0 §M49 (lazy banner).
+  const dashboardInfo = _probeDashboardLazy(projectDir);
 
   // M46 follow-up — Date + version banner. Printed before the transcript URL
   // so multi-day-old read-backs are immediately dated. Best-effort.
@@ -155,17 +159,27 @@ function autoSpawnHeadless(opts) {
     /* best-effort — never crash the spawn on banner failure */
   }
 
-  // M43 D6-T3 — Live transcript URL banner. Printed for every spawn so the
-  // viewer at :PORT is "the" primary watching surface. Never throws.
-  // Text is coordinated with D4 — exact line shape is part of
-  // dashboard-server-contract.md §Banner Format.
+  // M49 — Conditional transcript banner. If a dashboard is already running
+  // on the project's scoped port, point at the live URL (M43 D6-T3 shape).
+  // Otherwise, point at the on-disk log path and hint at /gsd-t-visualize so
+  // the user knows how to open the viewer if they want it. The viewer URL
+  // is no longer printed for spawns where no listener exists — that is what
+  // caused users to assume one was running and accumulated orphans on retry.
+  //
+  // Text is coordinated with D4 — banner format spec in
+  // .gsd-t/contracts/dashboard-server-contract.md v1.3.0 §Banner Format
+  // and headless-default-contract.md v2.0.0 §M49.
   try {
-    let port = autostartInfo && autostartInfo.port;
-    if (!port) {
-      const { projectScopedDefaultPort } = require("../scripts/gsd-t-dashboard-server.js");
-      port = projectScopedDefaultPort(projectDir);
+    if (dashboardInfo.running && dashboardInfo.port) {
+      process.stdout.write(
+        `▶ Live transcript: http://127.0.0.1:${dashboardInfo.port}/transcript/${id}\n`,
+      );
+    } else {
+      const relLog = path.relative(projectDir, logPath);
+      process.stdout.write(
+        `▶ Transcript file: ${relLog}\n  (to view live: gsd-t-visualize)\n`,
+      );
     }
-    process.stdout.write(`▶ Live transcript: http://127.0.0.1:${port}/transcript/${id}\n`);
   } catch (_) {
     /* best-effort — never crash the spawn on banner failure */
   }
@@ -515,6 +529,57 @@ function appendTokenLog(projectDir, entry) {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
+/**
+ * M49 — Cheap synchronous probe: is a dashboard listening on this project's
+ * scoped port? Strategy: read `.gsd-t/.dashboard.pid`; if the pid is alive
+ * (`process.kill(pid, 0)` doesn't throw), assume the dashboard is up and
+ * resolve the port via `projectScopedDefaultPort(projectDir)`. No child
+ * process forking — this runs on every spawn and must be cheap.
+ *
+ * Returns `{ running: boolean, port: number|null, pid: number|null }`. Never
+ * throws. A return of `{ running: false }` is the safe fallback that drives
+ * the file-path-only banner.
+ *
+ * @param {string} projectDir
+ * @returns {{ running: boolean, port: number|null, pid: number|null }}
+ */
+function _probeDashboardLazy(projectDir) {
+  const out = { running: false, port: null, pid: null };
+  try {
+    const pidFile = path.join(projectDir, ".gsd-t", ".dashboard.pid");
+    if (!fs.existsSync(pidFile)) return out;
+    const raw = fs.readFileSync(pidFile, "utf8").trim();
+    const pid = parseInt(raw, 10);
+    if (!pid || Number.isNaN(pid) || pid <= 0) return out;
+    // process.kill(pid, 0) — signal 0 only checks for existence/permission.
+    // Throws ESRCH if no such process; EPERM if process exists but owned by
+    // someone else. EPERM still implies "alive", so treat both ESRCH-only as
+    // dead.
+    try {
+      process.kill(pid, 0);
+    } catch (err) {
+      if (err && err.code === "EPERM") {
+        // Alive but not owned by us — still a live listener; treat as running.
+      } else {
+        return out; // ESRCH or unknown — treat as dead.
+      }
+    }
+    out.pid = pid;
+    out.running = true;
+    try {
+      const { projectScopedDefaultPort } = require("../scripts/gsd-t-dashboard-server.js");
+      out.port = projectScopedDefaultPort(projectDir);
+    } catch (_) {
+      // Without the port we can't render the URL — fall back to file banner.
+      out.running = false;
+      out.port = null;
+    }
+  } catch (_) {
+    /* probe is best-effort */
+  }
+  return out;
+}
+
 function ensureDir(d) {
   if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
 }

package/docs/architecture.md

@@ -73,8 +73,8 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 ### Transcript Viewer as Primary Surface (M43 D6 — complete v3.16.13)
 - **Dashboard server additions** (`scripts/gsd-t-dashboard-server.js`): two new HTTP routes for the per-spawn viewer. `GET /transcript/:id/usage` → `{spawn_id, rows, truncated}` filtered from `.gsd-t/metrics/token-usage.jsonl` by `row.spawn_id === id` OR (no `spawn_id` column + `row.session_id === id` — the session-id branch covers M43 D1 Branch B in-session rows). `GET /transcript/:id/tool-cost` → proxies to `bin/gsd-t-tool-attribution.cjs::aggregateByTool` (M43 D2); returns 503 `{error: "tool-attribution library not yet available"}` when D2 isn't on disk so D6 could ship before D2 in Wave 2 without crashing callers.
 - **Transcript viewer panel** (`scripts/gsd-t-transcript.html`): collapsible "Tool Cost" sidebar panel that fetches `/transcript/:id/tool-cost` on viewer load and debounces a 2s refresh on each SSE `turn_complete` / `result` frame. Renders top-N tools sorted by attributed tokens with name, call count, tokens, and USD cost. Live badge green while SSE is open, muted otherwise. 503 → friendly "tool attribution not yet wired" row. `window.__gsdtRenderToolCostPanel` exposed for DOM tests.
-- **URL banner** (`bin/headless-auto-spawn.cjs`): every detached spawn prints `▶ Live transcript: http://127.0.0.1:{port}/transcript/{spawn-id}` on stdout. Port sourced from `ensureDashboardRunning().port` with `projectScopedDefaultPort(projectDir)` fallback. Best-effort — banner failure never crashes the spawn.
-- **Dashboard autostart** (`scripts/gsd-t-dashboard-autostart.cjs`, ~160 lines, zero deps): `ensureDashboardRunning({projectDir, port?})` probes the port synchronously via a short-lived subprocess (`_isPortBusySync` issues `net.createServer().listen(port)` host-less — matches the server's IPv6-wildcard bind on macOS dual-stack; specifying `127.0.0.1` would falsely report free). If free, fork-detaches the server with `spawn(…, {detached:true, stdio:'ignore'})` + `child.unref()` + writes `.gsd-t/.dashboard.pid` (hyphen → dot distinguishes this lifecycle from M38's `.gsd-t/dashboard.pid`). Idempotent on repeated invocation. Called at the top of `autoSpawnHeadless` so the banner printed immediately after resolves to a live listener.
+- **URL banner** (`bin/headless-auto-spawn.cjs`, M49 — lazy): every detached spawn prints either `▶ Live transcript: http://127.0.0.1:{port}/transcript/{spawn-id}` (when a dashboard is already listening, detected via `_probeDashboardLazy()` reading `.gsd-t/.dashboard.pid` + `process.kill(pid, 0)`) OR `▶ Transcript file: {logPath}\n  (to view live: gsd-t-visualize)` (when no dashboard is up). Pre-M49 the spawn unconditionally autostarted a dashboard via `ensureDashboardRunning()` and printed the URL — that accumulated 88+ orphan dashboard processes because 99% of those URLs are never opened. M49 removed the autostart from the spawn path; the dashboard now only starts when the user explicitly invokes `/gsd-t-visualize`. Best-effort — banner failure never crashes the spawn.
+- **Dashboard autostart** (`scripts/gsd-t-dashboard-autostart.cjs`, ~160 lines, zero deps): `ensureDashboardRunning({projectDir, port?})` probes the port synchronously via a short-lived subprocess (`_isPortBusySync` issues `net.createServer().listen(port)` host-less — matches the server's IPv6-wildcard bind on macOS dual-stack; specifying `127.0.0.1` would falsely report free). If free, fork-detaches the server with `spawn(…, {detached:true, stdio:'ignore'})` + `child.unref()` + writes `.gsd-t/.dashboard.pid` (hyphen → dot distinguishes this lifecycle from M38's `.gsd-t/dashboard.pid`). Idempotent on repeated invocation. **M49 — only called by `/gsd-t-visualize` now**, never by the spawn path; combined with the dashboard's idle-TTL self-shutdown (4-hour default, configurable via `GSD_T_DASHBOARD_IDLE_TTL_MS` or `--idle-ttl-ms`) this caps the long-tail orphan accumulation.
 - **Contract**: `.gsd-t/contracts/dashboard-server-contract.md` v1.2.0 — new §HTTP Endpoints entries, §Banner Format, §Autostart sections. (Bumped to v1.3.0 in M47 — see Focused Visualizer Redesign below.)
 - **Tests**: `test/m43-dashboard-tool-cost-route.test.js` (9), `test/m43-transcript-panel.test.js` (12), `test/m43-dashboard-autostart.test.js` (6), `test/m43-url-banner.test.js` (3).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.21.11",
+  "version": "3.21.12",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-dashboard-server.js

@@ -773,13 +773,106 @@ function handleSpawnPlanUpdates(req, res, projectDir) {
   req.on("close", () => { clearInterval(timer); if (dirWatcher) { try { dirWatcher.close(); } catch { /* ok */ } } });
 }
 
-function startServer(port, eventsDir, htmlPath, projectDir, transcriptHtmlPath) {
+// ── M49 — Idle-TTL self-shutdown ────────────────────────────────────────────
+//
+// A dashboard with zero HTTP requests AND zero active SSE connections for the
+// full TTL window self-exits cleanly. Safety net for any dashboard that
+// somehow gets started and then walks away — even if a future bug lets one
+// be auto-started, it dies on its own. Configurable via env
+// `GSD_T_DASHBOARD_IDLE_TTL_MS` or `--idle-ttl-ms` flag.
+//
+// "Idle" means: zero HTTP requests AND zero active SSE connections for the
+// full TTL window. `lastActivity` is bumped on every HTTP request handler
+// entry and on SSE connect/disconnect. SSE-active dashboards never exit.
+//
+// On shutdown, removes `.gsd-t/.dashboard.pid` so the lazy probe (M49 in
+// `bin/headless-auto-spawn.cjs`) sees a clean state.
+
+const DEFAULT_IDLE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+const IDLE_CHECK_INTERVAL_MS = 60 * 1000;        // 60s
+
+function _activityTracker() {
+  let lastActivity = Date.now();
+  let activeSseConnections = 0;
+  return {
+    bump() { lastActivity = Date.now(); },
+    sseConnect() { activeSseConnections++; lastActivity = Date.now(); },
+    sseDisconnect() {
+      if (activeSseConnections > 0) activeSseConnections--;
+      lastActivity = Date.now();
+    },
+    snapshot() { return { lastActivity, activeSseConnections }; },
+  };
+}
+
+/**
+ * Wrap an SSE handler so it bumps the connect/disconnect counters.
+ */
+function _wrapSseHandler(handler, tracker) {
+  return function (req, res, ...rest) {
+    tracker.sseConnect();
+    let closed = false;
+    const onClose = () => {
+      if (closed) return;
+      closed = true;
+      tracker.sseDisconnect();
+    };
+    req.on("close", onClose);
+    res.on("close", onClose);
+    res.on("finish", onClose);
+    return handler(req, res, ...rest);
+  };
+}
+
+/**
+ * @param {object} opts { ttlMs, intervalMs, projectDir, server }
+ * @returns timer handle (so callers can clearInterval in tests).
+ */
+function _startIdleTtlTimer({ ttlMs, intervalMs, projectDir, server, tracker, onShutdown }) {
+  const interval = setInterval(() => {
+    const { lastActivity, activeSseConnections } = tracker.snapshot();
+    const idle = Date.now() - lastActivity;
+    if (activeSseConnections === 0 && idle >= ttlMs) {
+      clearInterval(interval);
+      try {
+        // Remove pid file so the lazy probe in headless-auto-spawn sees clean state.
+        if (projectDir) {
+          const pidFile = path.join(projectDir, ".gsd-t", ".dashboard.pid");
+          try { fs.unlinkSync(pidFile); } catch { /* may not exist */ }
+        }
+      } catch { /* best-effort */ }
+      try { if (typeof onShutdown === "function") onShutdown(); } catch { /* best-effort */ }
+      try {
+        if (server) server.close(() => process.exit(0));
+        else process.exit(0);
+      } catch { process.exit(0); }
+    }
+  }, intervalMs);
+  if (typeof interval.unref === "function") interval.unref();
+  return interval;
+}
+
+function startServer(port, eventsDir, htmlPath, projectDir, transcriptHtmlPath, opts) {
   const projDir = projectDir || path.resolve(eventsDir, "..", "..");
   const tHtmlPath = transcriptHtmlPath || path.join(path.dirname(htmlPath), "gsd-t-transcript.html");
+  const tracker = _activityTracker();
+  const ttlMs = (opts && Number.isFinite(opts.idleTtlMs))
+    ? opts.idleTtlMs
+    : (Number.parseInt(process.env.GSD_T_DASHBOARD_IDLE_TTL_MS || "", 10) || DEFAULT_IDLE_TTL_MS);
+  const intervalMs = (opts && Number.isFinite(opts.idleCheckIntervalMs))
+    ? opts.idleCheckIntervalMs
+    : IDLE_CHECK_INTERVAL_MS;
+
+  // Wrap the three SSE handlers with the connect/disconnect tracker.
+  const handleEventsSse = _wrapSseHandler(handleEvents, tracker);
+  const handleTranscriptStreamSse = _wrapSseHandler(handleTranscriptStream, tracker);
+  const handleSpawnPlanUpdatesSse = _wrapSseHandler(handleSpawnPlanUpdates, tracker);
+
   const server = http.createServer((req, res) => {
+    tracker.bump(); // bump on every HTTP request handler entry
     const url = req.url.split("?")[0];
     if (url === "/" || url === "") return handleRoot(req, res, htmlPath);
-    if (url === "/events") return handleEvents(req, res, eventsDir);
+    if (url === "/events") return handleEventsSse(req, res, eventsDir);
     if (url === "/metrics") return handleMetrics(req, res, projDir);
     if (url === "/ping") return handlePing(req, res, port);
     if (url === "/stop") return handleStop(req, res, server);
@@ -788,7 +881,7 @@ function startServer(port, eventsDir, htmlPath, projectDir, transcriptHtmlPath)
     if (url === "/api/main-session") return handleMainSession(req, res, projDir);
     // M44 D8 — spawn plans: GET list + SSE change stream
     if (url === "/api/spawn-plans") return handleSpawnPlans(req, res, projDir);
-    if (url === "/api/spawn-plans/stream") return handleSpawnPlanUpdates(req, res, projDir);
+    if (url === "/api/spawn-plans/stream") return handleSpawnPlanUpdatesSse(req, res, projDir);
     // M44 D9 — parallelism observability (additive, read-only)
     if (url === "/api/parallelism") return handleParallelism(req, res, projDir);
     if (url === "/api/parallelism/report") return handleParallelismReport(req, res, projDir);
@@ -805,14 +898,30 @@ function startServer(port, eventsDir, htmlPath, projectDir, transcriptHtmlPath)
     if (usageMatch) return handleTranscriptUsage(req, res, decodeURIComponent(usageMatch[1]), projDir);
     // /transcript/:spawnId/stream — SSE tail of per-spawn ndjson
     const streamMatch = url.match(/^\/transcript\/([^/]+)\/stream$/);
-    if (streamMatch) return handleTranscriptStream(req, res, decodeURIComponent(streamMatch[1]), projDir);
+    if (streamMatch) return handleTranscriptStreamSse(req, res, decodeURIComponent(streamMatch[1]), projDir);
     // /transcript/:spawnId — HTML viewer page
     const pageMatch = url.match(/^\/transcript\/([^/]+)$/);
     if (pageMatch) return handleTranscriptPage(req, res, decodeURIComponent(pageMatch[1]), tHtmlPath, projDir);
     res.writeHead(404); res.end("Not found");
   });
   server.listen(port);
-  return { server, url: `http://localhost:${port}` };
+
+  // M49 — install idle-TTL self-shutdown timer. Skipped only when caller
+  // explicitly passes `idleTtlMs: 0` (used by tests that don't want the
+  // server to self-exit mid-test).
+  let idleTimer = null;
+  if (ttlMs > 0) {
+    idleTimer = _startIdleTtlTimer({
+      ttlMs,
+      intervalMs,
+      projectDir: projDir,
+      server,
+      tracker,
+      onShutdown: opts && opts.onShutdown,
+    });
+  }
+
+  return { server, url: `http://localhost:${port}`, tracker, idleTimer };
 }
 
 module.exports = {
@@ -850,6 +959,11 @@ module.exports = {
   handleParallelism,
   handleParallelismReport,
   handleUnattendedStop,
+  // M49 — idle-TTL exports for tests
+  _activityTracker,
+  _wrapSseHandler,
+  _startIdleTtlTimer,
+  DEFAULT_IDLE_TTL_MS,
 };
 
 if (require.main === module) {
@@ -875,9 +989,25 @@ if (require.main === module) {
     fs.writeFileSync(pidFile, String(child.pid));
     process.exit(0);
   }
-  const { server, url } = startServer(port, eventsDir, htmlPath, projectDir, transcriptHtmlPath);
+  // M49 — idle-TTL flag/env override. Falls through to startServer's default
+  // (env var GSD_T_DASHBOARD_IDLE_TTL_MS or 4h).
+  const ttlArg = getArg("--idle-ttl-ms");
+  const startOpts = {};
+  if (ttlArg != null && ttlArg !== "") {
+    const n = Number.parseInt(ttlArg, 10);
+    if (Number.isFinite(n)) startOpts.idleTtlMs = n;
+  }
+
+  const { server, url } = startServer(port, eventsDir, htmlPath, projectDir, transcriptHtmlPath, startOpts);
   process.stdout.write("GSD-T Dashboard: " + url + "\n");
-  function cleanup() { try { fs.unlinkSync(pidFile); } catch { /* ok */ } server.close(() => process.exit(0)); }
+  function cleanup() {
+    try { fs.unlinkSync(pidFile); } catch { /* ok */ }
+    // M49 — also remove the lazy-probe pidfile so headless-auto-spawn sees clean state.
+    try {
+      fs.unlinkSync(path.join(projectDir, ".gsd-t", ".dashboard.pid"));
+    } catch { /* ok */ }
+    server.close(() => process.exit(0));
+  }
   process.on("SIGTERM", cleanup);
   process.on("SIGINT", cleanup);
 }