@tekyzinc/gsd-t 3.21.11 → 3.22.10

package/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.22.10] — M50 Universal Playwright Bootstrap + Deterministic UI Enforcement
+
+### Added — three deterministic enforcement layers replace prose-only Playwright Readiness Guard
+
+Closes the gap that allowed M48 viewer fixes to ship without Playwright tests despite the existing prose Readiness Guard. Prior pattern was prose in `~/.claude/CLAUDE.md` + per-command-file reminders that agents could read and decide to skip. M50 converts every layer to executable code so agents cannot self-approve their way around it.
+
+**Layer 1 — Bootstrap library (D1):**
+- `bin/playwright-bootstrap.cjs` (new) — `hasPlaywright`, `detectPackageManager`, `installPlaywright`, `installPlaywrightSync`, `verifyPlaywrightHealth`. Idempotent installer: detects package manager (npm/pnpm/yarn/bun), installs `@playwright/test` + chromium, writes `playwright.config.ts` from a single-source template (contract §6), scaffolds `e2e/__placeholder.spec.ts`. Preserves existing config + e2e contents on re-run. Error classifier maps subprocess stderr to `{package-manager-not-found, network, chromium, disk}` with caller-actionable hints; chromium-failure surfaces `partial: true`. Zero external runtime deps.
+- `bin/ui-detection.cjs` (new) — `hasUI`, `detectUIFlavor`. Synchronous, depth-bounded ≤3 BFS, never throws. Detects React/Vue/Svelte/Next/Angular/Flutter/Tailwind via `package.json`, `pubspec.yaml`, `tailwind.config.{js,ts,mjs,cjs}`, or any UI extension (`.tsx`/`.jsx`/`.vue`/`.svelte`/`.css`/`.scss`).
+- `bin/gsd-t.js`: inline `hasPlaywright` (was lines 201-204) replaced with `require('./playwright-bootstrap.cjs')`. `init` flow auto-installs Playwright when `hasUI && !hasPlaywright`. `update-all` auto-installs across all registered UI projects + reports counts (`Auto-installed Playwright in: N project(s)`). New `gsd-t setup-playwright [path] [--force]` subcommand. New `gsd-t doctor --install-playwright` flag. New `gsd-t doctor --install-hooks` flag (D2).
+
+**Layer 2 — Spawn-time gate (D2):**
+- `bin/headless-auto-spawn.cjs::autoSpawnHeadless()`: new gate runs before the spawn. When the command is in the `TESTING_OR_UI_COMMANDS` whitelist (9 commands: execute, test-sync, verify, quick, wave, milestone, complete-milestone, debug, integrate) AND `hasUI(projectDir)` AND `!hasPlaywright(projectDir)`, the gate calls `installPlaywrightSync(projectDir)` synchronously. On install failure, writes `mode: 'blocked-needs-human'` + `reason: 'playwright-install-failed'` to the headless session-state file and exits 4. Hot path: three filesystem checks; no install attempt when gate doesn't fire.
+
+**Layer 3 — Commit-time gate (D2):**
+- `scripts/hooks/pre-commit-playwright-gate` (new, executable bash) — opt-in via `gsd-t doctor --install-hooks`. Reads `.gsd-t/.last-playwright-pass` (Unix epoch ms in a single line). Detects staged viewer-source files (`scripts/gsd-t-transcript.html`, `scripts/gsd-t-dashboard-server.js`, `e2e/viewer/**`); if any file's mtime exceeds the last-pass timestamp, blocks the commit (exit 1 + clear stderr message). Fails open on missing/corrupt timestamps — broken hook is worse than a permissive one.
+
+**E2E specs delivered (the M47/M48/M49 viewer specs we owed):**
+- `playwright.config.ts` (root) — testDir `./e2e`, chromium project, `webServer` omitted (specs manage their own server lifecycle).
+- `e2e/viewer/title.spec.ts` — M48 Bug 1 regression (project basename in `<title>` + header `.title` for `/transcripts` and `/transcripts/{spawn-id}`).
+- `e2e/viewer/timestamps.spec.ts` — M48 Bug 2 regression (per-frame `frame.ts`, not per-batch `new Date()`).
+- `e2e/viewer/chat-bubbles.spec.ts` — M48 Bug 3 regression (`user_turn`/`assistant_turn`/`session_start`/`tool_use_line` render as bubbles, not JSON.stringify dumps).
+- `e2e/viewer/dual-pane.spec.ts` — M48 Bug 4 regression (bottom pane never connects to in-session-* SSE).
+- `e2e/viewer/lazy-dashboard.spec.ts` — M49 banner regression (file-path + visualize hint when no dashboard; URL when alive).
+
+**Tests:**
+- `test/m50-d1-ui-detection.test.js` — 18 unit tests (8 mandatory fixtures + 4 hardening + 6 Red Team regressions).
+- `test/m50-d1-playwright-bootstrap.test.js` — 20 unit tests (`hasPlaywright`, `detectPackageManager`, `verifyPlaywrightHealth`, 9 install-path branches).
+- `test/m50-d1-cli-integration.test.js` — 5 CLI wire-up tests (re-export, init gate, doctor flag, setup-playwright).
+- `test/m50-d2-viewer-specs-smoke.test.js` — 4 meta-tests (config + scripts + zero-runtime-dep invariant).
+- `test/m50-d2-spawn-gate.test.js` — 9 gate-firing matrix tests (whitelist + 5 firing scenarios + hot-path overhead).
+- `test/m50-d2-pre-commit-hook.test.js` — 6 hook-behavior tests (clean / blocked / fresh / missing / corrupt / e2e/viewer pattern).
+
+Total: 62 new M50 tests; full suite 2163/2166 (3 pre-existing env-flakes preserved). Zero regressions.
+
+**Doc-ripple:**
+- `~/.claude/CLAUDE.md` § Playwright Readiness Guard — collapsed to a layered referral.
+- `templates/CLAUDE-global.md` — mirror.
+- `commands/gsd-t-init.md` Step 11 — points at `installPlaywright()` instead of carrying inline package-manager commands.
+- `docs/architecture.md` — new "Playwright Deterministic Enforcement (M50)" subsection.
+- `.gsd-t/contracts/playwright-bootstrap-contract.md` v1.0.0 — new contract.
+- `.gsd-t/contracts/m50-integration-points.md` — D1→D2 checkpoint flipped to PUBLISHED.
+
+## [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/README.md

@@ -16,6 +16,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **External Task Orchestrator + Streaming Watcher UI (M40, v3.14.10)** — JS orchestrator drives `claude -p` one task per spawn: short-lived, fresh context, architecturally compaction-free. Benchmarks 0.72× wall-clock vs in-session on 20-task/3-wave workloads. Paired with a zero-Claude-cost local streaming UI at `127.0.0.1:7842` that renders all workers' stream-json output as a continuous claude.ai-style feed — task/wave banners, duration + usage chips, token corner bar, localStorage filters, replay via `WS /feed?from=N`. Recovery: `--resume` reconciles interrupted runs using commit + progress.md evidence; ambiguous tasks (commit without progress entry) are flagged for operator triage, never silently claimed done. CLI: `gsd-t orchestrate`, `gsd-t benchmark-orchestrator`, `gsd-t stream-feed`. Contracts: `stream-json-sink-contract.md` v1.1.0, `wave-join-contract.md`, `completion-signal-contract.md`, `metrics-schema-contract.md`.
 **Always-Headless Spawn (M43 D4, v3.16.x+) — Channel Separation** — every GSD-T command spawns detached, unconditionally. No `--watch`, no `--in-session`, no `--headless` opt-in, no context-meter threshold that reroutes. The dialog channel is reserved for human↔Claude conversation; every workflow turn is a detached headless child. Interactive session shows a launch banner + live-transcript URL + event-stream path, then exits — results surface via the read-back banner on the user's next message. Detached workers emit JSONL events to `.gsd-t/events/YYYY-MM-DD.jsonl` at every phase boundary — shared by dashboard and (historically) the watch command. The only in-session surface is the `/gsd` router (for dialog-only exploratory turns). See `.gsd-t/contracts/headless-default-contract.md` v2.0.0 and `unattended-event-stream-contract.md` v1.0.0.
 **Live Transcript as Primary Surface (M43 D6, v3.16.13 — extended in M47, v3.21.10)** — every detached spawn prints a one-line banner (`▶ Live transcript: http://127.0.0.1:{port}/transcript/{id}`) pointing at a browser viewer that SSE-streams the child's stdout and renders a collapsible "Tool Cost" sidebar panel showing per-tool attributed tokens and cost (sourced from `/transcript/:id/tool-cost`, which proxies to the M43 D2 tool-attribution library). The dashboard server auto-starts (`scripts/gsd-t-dashboard-autostart.cjs`) idempotently on each spawn — a port probe backs off when a server is already running, otherwise a fork-detach writes `.gsd-t/.dashboard.pid`. Port is project-scoped via `projectScopedDefaultPort(projectDir)` so multi-project workflows don't clobber each other.
+**Universal Playwright Bootstrap + Deterministic UI Enforcement (M50, v3.22.10)** — converts the prose-only "Playwright Readiness Guard" into three executable enforcement layers so agents cannot skip UI tests. Layer 1: `bin/playwright-bootstrap.cjs` + `bin/ui-detection.cjs` wired into `init`/`update-all`/`doctor`/new `gsd-t setup-playwright [path]` subcommand — idempotent installer detects package manager, installs `@playwright/test` + chromium, writes config from a contract-locked template, scaffolds `e2e/`. Layer 2: `bin/headless-auto-spawn.cjs::autoSpawnHeadless()` auto-installs before any of 9 whitelisted testing/UI commands when `hasUI && !hasPlaywright`; install failure → `mode: 'blocked-needs-human'` exit-4. Layer 3: `scripts/hooks/pre-commit-playwright-gate` (opt-in via `gsd-t doctor --install-hooks`) reads `.gsd-t/.last-playwright-pass` and blocks viewer-source commits when staged files are newer than the last playwright test pass. Also ships the M47/M48/M49 E2E viewer specs (`e2e/viewer/title`, `timestamps`, `chat-bubbles`, `dual-pane`, `lazy-dashboard`). 62 new unit tests; E2E 8/9 pass.
 **Focused Visualizer Redesign (M47, v3.21.10)** — `/transcripts` opens directly to a dual-pane focused view: the **top pane** auto-streams the orchestrator's main in-session conversation (zero clicks — fetched via new `GET /api/main-session`), and the **bottom pane** streams whichever spawn the user clicks. A keyboard- and mouse-resizable splitter sits between them, with position persisted in `sessionStorage` (along with selection, completed-section toggle, and right-rail collapsed state). The left rail splits into three sections — `★ Main Session`, `Live Spawns`, and `Completed` (last 100 spawns, newest first, status-badged, collapsible). When a spawn transitions running → completed it moves rail sections live without a full reload, and stays selected if focused. The right rail (Spawn Plan / Parallelism / Tool Cost) is preserved under a new collapsible toggle. Bookmarks to `/transcript/:spawnId` continue to land that spawn pre-selected in the bottom pane. Contract: `dashboard-server-contract.md` v1.3.0 (additive — `status: 'active' \| 'completed'` field on in-session entries, derived from a 30s mtime window; `/api/main-session` endpoint with path-traversal guard + `Cache-Control: no-store`).
 - **Surgical model selection** — `bin/model-selector.js` assigns haiku/sonnet/opus per phase via a declarative rules table; `/advisor` escalation path with convention-based fallback.
 - **Per-spawn token telemetry** — `.gsd-t/token-metrics.jsonl` records one 18-field row per Task subagent spawn.

package/bin/gsd-t.js

@@ -198,10 +198,15 @@ function copyFile(src, dest, label) {
   }
 }
 
-function hasPlaywright(projectDir) {
-  const configs = ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs"];
-  return configs.some((f) => fs.existsSync(path.join(projectDir, f)));
-}
+// M50 D1: hasPlaywright migrated to bin/playwright-bootstrap.cjs.
+// Re-exported here for back-compat with any caller still requiring it via
+// bin/gsd-t.js. See .gsd-t/contracts/playwright-bootstrap-contract.md §3.
+const {
+  hasPlaywright,
+  installPlaywright,
+  detectPackageManager: _detectPlaywrightPackageManager,
+} = require("./playwright-bootstrap.cjs");
+const { hasUI } = require("./ui-detection.cjs");
 
 function readProjectDeps(projectDir) {
   const pkgPath = path.join(projectDir, "package.json");
@@ -571,6 +576,47 @@ function installContextMeter(projectDir) {
 // to .git/hooks/pre-commit; if the file doesn't exist, copies our stock
 // script. Never overwrites an existing hook.
 const CAPTURE_LINT_HOOK_MARKER = "# GSD-T capture lint";
+// M50 D2 — Playwright pre-commit gate marker. Installed via
+// `gsd-t doctor --install-hooks`. Idempotent: appends a delimited block to
+// `.git/hooks/pre-commit` if the marker isn't already present.
+const PLAYWRIGHT_GATE_HOOK_MARKER = "# GSD-T playwright gate";
+
+function installPlaywrightGateHook(projectDir) {
+  const gitDir = path.join(projectDir, ".git");
+  if (!fs.existsSync(gitDir)) {
+    warn("No .git directory — not a git repo; skipping playwright-gate install");
+    return false;
+  }
+  const hooksDir = path.join(gitDir, "hooks");
+  try { fs.mkdirSync(hooksDir, { recursive: true }); } catch (_) {}
+  const hookPath = path.join(hooksDir, "pre-commit");
+  const stockSrc = path.join(PKG_ROOT, "scripts", "hooks", "pre-commit-playwright-gate");
+  let stock = "";
+  try { stock = fs.readFileSync(stockSrc, "utf8"); } catch (_) {
+    warn("Could not read pre-commit-playwright-gate script from package");
+    return false;
+  }
+  if (!fs.existsSync(hookPath)) {
+    fs.writeFileSync(hookPath, stock);
+    try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+    success(`Playwright gate installed at ${path.relative(projectDir, hookPath)}`);
+    info("The hook reads .gsd-t/.last-playwright-pass to gate viewer-source commits");
+    return true;
+  }
+  const existing = fs.readFileSync(hookPath, "utf8");
+  if (existing.includes(PLAYWRIGHT_GATE_HOOK_MARKER)) {
+    info("Playwright-gate block already present in pre-commit hook — no change");
+    return true;
+  }
+  const appended = existing.trimEnd() +
+    "\n\n" + PLAYWRIGHT_GATE_HOOK_MARKER + "\n" +
+    stock.replace(/^#!.*\n/, "") + "\n";
+  fs.writeFileSync(hookPath, appended);
+  try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+  success(`Playwright-gate block appended to ${path.relative(projectDir, hookPath)}`);
+  return true;
+}
+
 function installCaptureLintHook(projectDir) {
   const gitDir = path.join(projectDir, ".git");
   if (!fs.existsSync(gitDir)) {
@@ -1655,6 +1701,25 @@ async function doInit(projectName) {
 
   if (registerProject(projectDir)) success("Registered in ~/.claude/.gsd-t-projects");
 
+  // M50 D1: Universal Playwright bootstrap. If the project has UI signal but
+  // no playwright.config.*, install @playwright/test + chromium and scaffold
+  // playwright.config.ts + e2e/. See playwright-bootstrap-contract.md §5.
+  if (hasUI(projectDir) && !hasPlaywright(projectDir)) {
+    info("Installing Playwright (chromium)…");
+    try {
+      const r = await installPlaywright(projectDir);
+      if (r.ok) {
+        success("Playwright installed (playwright.config.ts + e2e/ scaffold)");
+      } else {
+        warn(`Playwright install failed: ${r.err}`);
+        if (r.hint) info(r.hint);
+      }
+    } catch (e) {
+      warn(`Playwright install errored: ${e.message || e}`);
+      info("Re-run with: gsd-t doctor --install-playwright");
+    }
+  }
+
   showInitTree(projectDir);
 }
 
@@ -1968,10 +2033,12 @@ function createProjectChangelog(projectDir, projectName) {
   }
 }
 
-function checkProjectHealth(projects) {
+async function checkProjectHealth(projects) {
   heading("Project Health");
   const playwrightMissing = [];
   const swaggerMissing = [];
+  const playwrightAutoInstalled = [];
+  const playwrightInstallFailed = [];
 
   for (const projectDir of projects) {
     if (!fs.existsSync(projectDir)) continue;
@@ -1980,19 +2047,56 @@ function checkProjectHealth(projects) {
     if (hasApi(projectDir) && !hasSwagger(projectDir)) swaggerMissing.push(name);
   }
 
+  // M50 D1: auto-install Playwright for any UI project that's missing it.
+  // Non-UI projects stay missing — they don't need Playwright.
+  for (const projectDir of projects) {
+    if (!fs.existsSync(projectDir)) continue;
+    if (hasPlaywright(projectDir)) continue;
+    if (!hasUI(projectDir)) continue;
+    const name = path.basename(projectDir);
+    try {
+      const r = await installPlaywright(projectDir);
+      if (r.ok) playwrightAutoInstalled.push(name);
+      else playwrightInstallFailed.push({ name, err: r.err, hint: r.hint });
+    } catch (e) {
+      playwrightInstallFailed.push({ name, err: e.message || String(e) });
+    }
+  }
+
   if (playwrightMissing.length === 0 && swaggerMissing.length === 0) {
     success("All projects have Playwright and Swagger configured");
   } else {
     if (playwrightMissing.length > 0) {
       warn(`Playwright missing: ${playwrightMissing.join(", ")}`);
-      info("Playwright will be auto-installed when you run a GSD-T command in each project");
+      if (playwrightAutoInstalled.length > 0) {
+        success(`Auto-installed Playwright in: ${playwrightAutoInstalled.join(", ")}`);
+      }
+      if (playwrightInstallFailed.length > 0) {
+        for (const f of playwrightInstallFailed) {
+          warn(`  ${f.name} — install failed: ${f.err}`);
+          if (f.hint) info(`  ${f.hint}`);
+        }
+      }
+      const stillMissing = playwrightMissing.filter(
+        (n) => !playwrightAutoInstalled.includes(n),
+      );
+      if (stillMissing.length > 0) {
+        info(
+          `Remaining (no UI signal — skipped): ${stillMissing.join(", ")}`,
+        );
+      }
     }
     if (swaggerMissing.length > 0) {
       warn(`Swagger/OpenAPI missing (API detected): ${swaggerMissing.join(", ")}`);
       info("Swagger will be auto-configured when an API endpoint is created or modified");
     }
   }
-  return { playwrightMissing, swaggerMissing };
+  return {
+    playwrightMissing,
+    swaggerMissing,
+    playwrightAutoInstalled,
+    playwrightInstallFailed,
+  };
 }
 
 // ── Global Rule Sync (M27) ──────────────────────────────────────────────────
@@ -2163,8 +2267,19 @@ async function doUpdateAll() {
   // Global rule sync — propagate proven rules across projects
   const syncCount = syncGlobalRules(projects);
 
-  const { playwrightMissing, swaggerMissing } = checkProjectHealth(projects);
-  showUpdateAllSummary(projects.length, counts, playwrightMissing, swaggerMissing, syncCount);
+  const {
+    playwrightMissing,
+    swaggerMissing,
+    playwrightAutoInstalled,
+  } = await checkProjectHealth(projects);
+  showUpdateAllSummary(
+    projects.length,
+    counts,
+    playwrightMissing,
+    swaggerMissing,
+    syncCount,
+    playwrightAutoInstalled,
+  );
 }
 
 // Upgrade the globally-installed @tekyzinc/gsd-t to @latest. Returns
@@ -2510,7 +2625,14 @@ function ensureUnattendedGitignore(projectDir, projectName) {
   return added;
 }
 
-function showUpdateAllSummary(total, counts, playwrightMissing, swaggerMissing, syncCount) {
+function showUpdateAllSummary(
+  total,
+  counts,
+  playwrightMissing,
+  swaggerMissing,
+  syncCount,
+  playwrightAutoInstalled,
+) {
   log("");
   heading("Update All Complete");
   log(`  Projects registered: ${total}`);
@@ -2519,6 +2641,9 @@ function showUpdateAllSummary(total, counts, playwrightMissing, swaggerMissing,
   if (counts.missing > 0) log(`  Not found:           ${counts.missing}`);
   if (counts.errors > 0) log(`  Errors:              ${counts.errors}`);
   if (playwrightMissing.length > 0) log(`  Missing Playwright:  ${playwrightMissing.length}`);
+  if (Array.isArray(playwrightAutoInstalled) && playwrightAutoInstalled.length > 0) {
+    log(`  Auto-installed Playwright in: ${playwrightAutoInstalled.length} project(s)`);
+  }
   if (swaggerMissing.length > 0) log(`  Missing Swagger:     ${swaggerMissing.length}`);
   if (syncCount > 0) log(`  Global rules synced: ${syncCount}`);
   log("");
@@ -2604,14 +2729,32 @@ function checkDoctorEncoding(installed) {
   return 0;
 }
 
-function checkDoctorProject() {
+async function checkDoctorProject(opts) {
   let issues = 0;
   const cwd = process.cwd();
+  const installFlag = !!(opts && opts.installPlaywright);
   if (hasPlaywright(cwd)) {
     success("Playwright configured");
+  } else if (installFlag && hasUI(cwd)) {
+    info("Installing Playwright (chromium)…");
+    try {
+      const r = await installPlaywright(cwd);
+      if (r.ok) {
+        success("Playwright installed (playwright.config.ts + e2e/ scaffold)");
+      } else {
+        error(`Playwright install failed: ${r.err}`);
+        if (r.hint) info(r.hint);
+        issues++;
+      }
+    } catch (e) {
+      error(`Playwright install errored: ${e.message || e}`);
+      issues++;
+    }
+  } else if (installFlag && !hasUI(cwd)) {
+    info("Playwright skipped — no UI signal in this project");
   } else {
     warn("Playwright not configured in this project");
-    info("Will be auto-installed when you run a GSD-T testing command");
+    info("Re-run with --install-playwright, or run any GSD-T testing command (auto-install)");
     issues++;
   }
   if (hasApi(cwd)) {
@@ -2758,15 +2901,160 @@ 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;
   issues += checkDoctorEnvironment();
   issues += checkDoctorInstallation();
-  issues += checkDoctorProject();
+  issues += await checkDoctorProject(opts);
   issues += checkDoctorCgc();
   issues += await checkDoctorContextMeter(process.cwd());
+  issues += checkDoctorDashboardOrphans(opts);
+  // M50 D2: opt-in install of the playwright-gate pre-commit hook.
+  if (opts && opts.installHooks) {
+    log("");
+    heading("Installing pre-commit hooks");
+    installPlaywrightGateHook(process.cwd());
+  }
   log("");
   if (issues === 0) {
     log(`${GREEN}${BOLD}  All checks passed!${RESET}`);
@@ -3881,7 +4169,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 +4234,8 @@ module.exports = {
   checkDoctorClaudeMd,
   checkDoctorSettings,
   checkDoctorEncoding,
+  checkDoctorDashboardOrphans,
+  doDoctor,
   mergeGsdtSection,
   migrateToMarkers,
   appendGsdtToClaudeMd,
@@ -4034,9 +4324,52 @@ 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, installPlaywright: false, installHooks: false };
+      for (let i = 1; i < args.length; i++) {
+        if (args[i] === "--prune") doctorOpts.prune = true;
+        if (args[i] === "--install-playwright") doctorOpts.installPlaywright = true;
+        if (args[i] === "--install-hooks") doctorOpts.installHooks = true;
+      }
+      doDoctor(doctorOpts).catch((e) => { error(e.message || String(e)); process.exit(1); });
+      break;
+    }
+    case "setup-playwright": {
+      // Single-project explicit installer. Thin wrapper around installPlaywright().
+      const targetDir = args[1] && !args[1].startsWith("-") ? path.resolve(args[1]) : process.cwd();
+      heading(`Setup Playwright: ${targetDir}`);
+      log("");
+      if (!fs.existsSync(targetDir)) {
+        error(`Path not found: ${targetDir}`);
+        process.exit(1);
+      }
+      if (hasPlaywright(targetDir)) {
+        info("Playwright already configured (playwright.config.* present)");
+        process.exit(0);
+      }
+      if (!hasUI(targetDir)) {
+        warn("No UI signal detected. Installing anyway? Re-run with --force to install regardless.");
+        const force = args.includes("--force");
+        if (!force) {
+          info("Skipping. Use --force to install Playwright in a non-UI project.");
+          process.exit(0);
+        }
+      }
+      info("Installing Playwright (chromium)…");
+      installPlaywright(targetDir)
+        .then((r) => {
+          if (r.ok) {
+            success("Playwright installed (playwright.config.ts + e2e/ scaffold)");
+            process.exit(0);
+          } else {
+            error(`Playwright install failed: ${r.err}`);
+            if (r.hint) info(r.hint);
+            process.exit(1);
+          }
+        })
+        .catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
+    }
     case "changelog":
       doChangelog();
       break;