@tekyzinc/gsd-t 3.21.11 → 3.22.10

package/bin/ui-detection.cjs

@@ -0,0 +1,151 @@
+"use strict";
+
+// UI detection probe — synchronous, never throws, depth-bounded.
+// Contract: .gsd-t/contracts/playwright-bootstrap-contract.md §4
+//
+// hasUI(projectDir): true iff the project has any UI signal.
+//   Probe order (first match wins, short-circuit):
+//     1. package.json deps/devDeps include react/vue/svelte/next/@angular/core/@vue/runtime-core
+//     2. pubspec.yaml at project root (Flutter)
+//     3. tailwind.config.{js,ts}
+//     4. any .tsx/.jsx/.vue/.svelte/.css/.scss within depth 3, excluding ignored dirs
+//
+// detectUIFlavor(projectDir): more specific category, or null when hasUI() is false.
+
+const fs = require("fs");
+const path = require("path");
+
+const FRAMEWORK_DEPS = {
+  next: "next",
+  angular: "@angular/core",
+  react: "react",
+  vue: "vue",
+  svelte: "svelte",
+  // @vue/runtime-core implies vue
+  "vue-runtime": "@vue/runtime-core",
+};
+
+const UI_FILE_EXTS = new Set([".tsx", ".jsx", ".vue", ".svelte", ".css", ".scss"]);
+
+const IGNORED_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".nuxt",
+  "coverage",
+  ".gsd-t",
+]);
+
+const MAX_WALK_DEPTH = 3;
+
+function _readPkgDeps(projectDir) {
+  const pkgPath = path.join(projectDir, "package.json");
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    const raw = fs.readFileSync(pkgPath, "utf8");
+    const pkg = JSON.parse(raw);
+    const deps = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+    return deps;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function _frameworkFromDeps(deps) {
+  if (!deps) return null;
+  // Order matters: next before react (Next ships with react), vue-runtime → vue, angular, svelte.
+  if (deps[FRAMEWORK_DEPS.next]) return "next";
+  if (deps[FRAMEWORK_DEPS.angular]) return "angular";
+  if (deps[FRAMEWORK_DEPS.vue] || deps[FRAMEWORK_DEPS["vue-runtime"]]) return "vue";
+  if (deps[FRAMEWORK_DEPS.svelte]) return "svelte";
+  if (deps[FRAMEWORK_DEPS.react]) return "react";
+  return null;
+}
+
+function _isFile(p) {
+  try {
+    const st = fs.statSync(p, { throwIfNoEntry: false });
+    return !!(st && st.isFile());
+  } catch (_e) {
+    return false;
+  }
+}
+
+function _hasFlutter(projectDir) {
+  return _isFile(path.join(projectDir, "pubspec.yaml"));
+}
+
+function _hasTailwindConfig(projectDir) {
+  return (
+    _isFile(path.join(projectDir, "tailwind.config.js")) ||
+    _isFile(path.join(projectDir, "tailwind.config.ts")) ||
+    _isFile(path.join(projectDir, "tailwind.config.mjs")) ||
+    _isFile(path.join(projectDir, "tailwind.config.cjs"))
+  );
+}
+
+// Depth-bounded short-circuit walk. Returns true on first UI file found.
+function _findUIFileWithinDepth(rootDir, maxDepth) {
+  // BFS-style iterative walk (avoid recursion depth + stack issues on weird trees).
+  const stack = [{ dir: rootDir, depth: 0 }];
+  while (stack.length > 0) {
+    const { dir, depth } = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (_e) {
+      continue;
+    }
+    for (const entry of entries) {
+      const name = entry.name;
+      if (entry.isFile()) {
+        const ext = path.extname(name).toLowerCase();
+        if (UI_FILE_EXTS.has(ext)) return true;
+      } else if (entry.isDirectory()) {
+        // Contract §4 enumerates the exclusion set — do not over-exclude
+        // dot-prefixed dirs (e.g. .storybook houses real UI code).
+        if (IGNORED_DIRS.has(name)) continue;
+        if (depth + 1 <= maxDepth) {
+          stack.push({ dir: path.join(dir, name), depth: depth + 1 });
+        }
+      }
+    }
+  }
+  return false;
+}
+
+function hasUI(projectDir) {
+  if (typeof projectDir !== "string" || projectDir.length === 0) return false;
+  try {
+    const deps = _readPkgDeps(projectDir);
+    if (_frameworkFromDeps(deps) !== null) return true;
+    if (_hasFlutter(projectDir)) return true;
+    if (_hasTailwindConfig(projectDir)) return true;
+    if (_findUIFileWithinDepth(projectDir, MAX_WALK_DEPTH)) return true;
+    return false;
+  } catch (_e) {
+    return false;
+  }
+}
+
+function detectUIFlavor(projectDir) {
+  if (typeof projectDir !== "string" || projectDir.length === 0) return null;
+  try {
+    const deps = _readPkgDeps(projectDir);
+    const framework = _frameworkFromDeps(deps);
+    if (framework !== null) return framework;
+    if (_hasFlutter(projectDir)) return "flutter";
+    if (_hasTailwindConfig(projectDir)) return "css-only";
+    if (_findUIFileWithinDepth(projectDir, MAX_WALK_DEPTH)) return "css-only";
+    return null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+module.exports = {
+  hasUI,
+  detectUIFlavor,
+};

package/commands/gsd-t-init.md

@@ -332,25 +332,23 @@ After initialization, verify all created documentation is consistent:
 
 ## Step 11: Playwright Setup (MANDATORY)
 
-Every GSD-T project must have Playwright ready for E2E testing. If `playwright.config.*` does not exist:
-
-1. **Detect package manager**: Check for `bun.lockb` (bun), `yarn.lock` (yarn), `pnpm-lock.yaml` (pnpm), `package-lock.json` or `package.json` (npm), `requirements.txt`/`pyproject.toml` (Python)
-2. **Install Playwright**:
-   - bun: `bun add -d @playwright/test && bunx playwright install chromium`
-   - npm: `npm install -D @playwright/test && npx playwright install chromium`
-   - yarn: `yarn add -D @playwright/test && yarn playwright install chromium`
-   - pnpm: `pnpm add -D @playwright/test && pnpm exec playwright install chromium`
-   - Python: `pip install playwright && playwright install chromium`
-   - No package manager detected: `npm init -y && npm install -D @playwright/test && npx playwright install chromium`
-3. **Create `playwright.config.ts`** (or `.js` if not using TypeScript) with sensible defaults:
-   - `testDir: './e2e'` (or `./tests/e2e`)
-   - `use: { baseURL: 'http://localhost:3000' }` (adjust based on project)
-   - Chromium only (keep it fast; user can add more browsers later)
-   - Screenshot on failure enabled
-4. **Create the E2E test directory** (`e2e/` or `tests/e2e/`) with a placeholder spec
-5. **Add test script** to `package.json` if it exists: `"test:e2e": "playwright test"`
-
-Skip silently if `playwright.config.*` already exists.
+M50: this step is now executable code, not prose. The `bin/gsd-t.js init` flow calls `installPlaywright(projectDir)` from `bin/playwright-bootstrap.cjs` automatically when `hasUI(projectDir) && !hasPlaywright(projectDir)`. See `.gsd-t/contracts/playwright-bootstrap-contract.md`.
+
+The installer:
+1. Detects the package manager via `detectPackageManager(projectDir)` (`pnpm-lock.yaml` → `pnpm`; `yarn.lock` → `yarn`; `bun.lockb` → `bun`; default `npm`).
+2. Installs `@playwright/test` as a devDependency + `npx playwright install chromium`.
+3. Writes `playwright.config.ts` (testDir `./e2e`, chromium project) idempotently — does NOT overwrite an existing config.
+4. Creates `e2e/__placeholder.spec.ts` (empty `test.skip`) when `e2e/` is absent or empty.
+
+Fallback (when not running through `bin/gsd-t.js init`):
+- bun: `bun add -d @playwright/test && bunx playwright install chromium`
+- npm: `npm install -D @playwright/test && npx playwright install chromium`
+- yarn: `yarn add -D @playwright/test && yarn playwright install chromium`
+- pnpm: `pnpm add -D @playwright/test && pnpm exec playwright install chromium`
+
+Operator overrides: `gsd-t setup-playwright [path]` (explicit single-project install) or `gsd-t doctor --install-playwright`.
+
+The spawn-time gate in `bin/headless-auto-spawn.cjs` re-runs the install on first need if the project skipped this step (e.g., older project that pre-dates M50).
 
 ## Step 12: Test Verification
 

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).
 
@@ -1086,3 +1086,17 @@ Contract: `.gsd-t/contracts/headless-default-contract.md` v2.1.0 §Worker Sub-Di
 The production main loop currently runs exactly one iter per pass (`batchSize === 1`) always, unless a caller explicitly threads `opts.maxIterParallel` as a number through `_computeIterBatchSize` — which today's supervisor CLI does not. The four helpers are exported via `module.exports.__test__` so the T7 unit suite and any future caller can exercise batched iteration deterministically, but iter-parallelism at this layer is **scaffolded, not engaged in production**. The gate is intentional: `_runOneIter` mutates shared `state` fields (`state.iter`, heartbeat bookkeeping, the `writeState` side effect) that are not safe to execute concurrently against the same state object. Backlog #24 tracks the follow-up to make `_runOneIter` state-clone-safe and lift the production gate so the supervisor CLI can set a non-1 default.
 
 Contract: `.gsd-t/contracts/iter-parallel-contract.md` v1.0.0.
+
+## Playwright Deterministic Enforcement (M50, v3.21.x+)
+
+M50 retires the prose-only "Playwright Readiness Guard" in favor of executable enforcement. Three layers, each runnable from the CLI or from any caller via the exported library:
+
+1. **Bootstrap library** (`bin/playwright-bootstrap.cjs` + `bin/ui-detection.cjs`) — single-source library exposing `hasPlaywright`, `detectPackageManager`, `installPlaywright`, `installPlaywrightSync`, `verifyPlaywrightHealth`, `hasUI`, `detectUIFlavor`. Zero external runtime dependencies. The async + sync install variants share the same template, error classifier, and idempotency invariants per `playwright-bootstrap-contract.md` §3-§8.
+
+2. **Spawn-time gate** (`bin/headless-auto-spawn.cjs::autoSpawnHeadless`) — when the command being spawned is in the `TESTING_OR_UI_COMMANDS` whitelist (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`, `gsd-t-integrate`) AND `hasUI(projectDir)` AND `!hasPlaywright(projectDir)`, the gate auto-installs via `installPlaywrightSync`. On install failure, the gate writes `mode: 'blocked-needs-human'` to the headless session-state file and exits with code 4. Hot-path overhead: three filesystem checks (Set lookup + depth-bounded fs walk + existsSync).
+
+3. **Commit-time gate** (`scripts/hooks/pre-commit-playwright-gate`) — opt-in via `gsd-t doctor --install-hooks`. The bash hook reads `.gsd-t/.last-playwright-pass` (Unix epoch ms) and blocks commits that touch viewer-source files (`scripts/gsd-t-transcript.html`, `scripts/gsd-t-dashboard-server.js`, `e2e/viewer/**`) when any staged file's mtime exceeds the recorded pass. Fails open on missing/corrupt timestamps — a broken hook is worse than a permissive one.
+
+CLI surface added in M50: `gsd-t setup-playwright [path]` (single-project explicit installer), `gsd-t doctor --install-playwright` (fix-it-now flag), `gsd-t doctor --install-hooks` (pre-commit-gate installer). `gsd-t init` and `gsd-t update-all` invoke `installPlaywright` automatically for any UI project that's missing it.
+
+Contract: `.gsd-t/contracts/playwright-bootstrap-contract.md` v1.0.0.

package/docs/requirements.md

@@ -700,3 +700,30 @@ Acceptance:
 | REQ-M47-D2-02 | New `GET /api/main-session` endpoint returns `{ filename, sessionId, mtimeMs }` for the most-recently-modified `in-session-*.ndjson` (or `{ null, null, null }` when none exist); path-traversal-guarded; no caching. | m47-d2-server-helpers | T2, T5 | done |
 | REQ-M47-D2-03 | `dashboard-server-contract.md` bumped to v1.3.0 documenting the additive `status` field semantics + `/api/main-session` schema; module exports updated. | m47-d2-server-helpers | T3 | done |
 | REQ-M47-D2-04 | Test suite passes baseline 2045/2047 + new M47 tests (D1 + D2 net add); no NEW regressions in the 7 existing viewer-route/HTML tests (success criterion 5). | m47-d1-viewer-redesign + m47-d2-server-helpers | D1 T7, D2 T4–T5 | done |
+
+
+## M50 Universal Playwright Bootstrap + Deterministic UI Enforcement (planned — 2026-05-06)
+
+| REQ-ID | Requirement Summary | Domain | Task(s) | Status |
+|--------|---------------------|--------|---------|--------|
+| REQ-M50-D1-01 | `bin/playwright-bootstrap.cjs` exports `hasPlaywright`, `detectPackageManager`, `installPlaywright` (idempotent), `verifyPlaywrightHealth`. Zero external runtime deps. | m50-bootstrap-and-detection | T2, T3 | done |
+| REQ-M50-D1-02 | `bin/ui-detection.cjs` exports `hasUI` (depth-bounded, short-circuits on first hit) + `detectUIFlavor`. Recognizes React/Vue/Svelte/Next/Angular/Flutter/Tailwind/css-only. | m50-bootstrap-and-detection | T1 | done |
+| REQ-M50-D1-03 | `bin/gsd-t.js` migrates inline `hasPlaywright` (line 201-204) to `require('./playwright-bootstrap.cjs')`; `init`/`update-all`/`doctor` invoke `installPlaywright` when `hasUI && !hasPlaywright`. | m50-bootstrap-and-detection | T4 | done |
+| REQ-M50-D1-04 | New `gsd-t setup-playwright` subcommand: explicit one-shot `installPlaywright(cwd)` invocation with verbose output. | m50-bootstrap-and-detection | T4 | done |
+| REQ-M50-D1-05 | New flag `gsd-t doctor --install-playwright` directly invokes `installPlaywright(cwd)`. Fixes all 14 of 19 registered projects flagged Playwright-missing in one command. | m50-bootstrap-and-detection | T4 | done |
+| REQ-M50-D1-06 | ~25 unit tests across `test/m50-d1-playwright-bootstrap.test.js` + `test/m50-d1-ui-detection.test.js` + `test/m50-d1-cli-integration.test.js` pass. | m50-bootstrap-and-detection | T1, T2, T3, T4, T5 | done |
+| REQ-M50-D2-01 | `bin/headless-auto-spawn.cjs::autoSpawnHeadless()` inserts a spawn-gate: when `isTestingOrUICommand && hasUI && !hasPlaywright`, auto-installs; on install fail, exits with `mode: 'blocked-needs-human'` (exit code 4). Hot-path overhead ≤ 10ms when no install is needed. | m50-gates-and-specs | T2 | done |
+| REQ-M50-D2-02 | `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 any touched viewer-source file's mtime > the timestamp. Fail-open on config errors. | m50-gates-and-specs | T3 | done |
+| REQ-M50-D2-03 | `playwright.config.ts` at GSD-T project root with `testDir: 'e2e'`, chromium project, `webServer: undefined` (specs manage their own server lifecycle). | m50-gates-and-specs | T1 | done |
+| REQ-M50-D2-04 | `e2e/viewer/title.spec.ts` regression-tests M48 Bug 1 (project basename in `<title>` + header `.title` for `/transcripts` and `/transcripts/{spawnId}`). | m50-gates-and-specs | T4 | done |
+| REQ-M50-D2-05 | `e2e/viewer/timestamps.spec.ts` regression-tests M48 Bug 2 (per-frame timestamps from `frame.ts`, not per-batch `new Date()`). | m50-gates-and-specs | T5 | done |
+| REQ-M50-D2-06 | `e2e/viewer/chat-bubbles.spec.ts` regression-tests M48 Bug 3 (`user_turn`/`assistant_turn`/`session_start`/`tool_use_line` render as styled bubbles, not `JSON.stringify` dumps). | m50-gates-and-specs | T6 | done |
+| REQ-M50-D2-07 | `e2e/viewer/dual-pane.spec.ts` regression-tests M48 Bug 4 (clicking `in-session-*` rail entry pins to top pane only; bottom pane stays on its own SSE stream). | m50-gates-and-specs | T7 | done |
+| REQ-M50-D2-08 | `e2e/viewer/lazy-dashboard.spec.ts` regression-tests M49 banner (URL banner when dashboard alive; fallback "Transcript file:" banner when not). | m50-gates-and-specs | T8 | done |
+| REQ-M50-D2-09 | ~14 unit tests across `test/m50-d2-spawn-gate.test.js` + `test/m50-d2-pre-commit-hook.test.js` + `test/m50-d2-viewer-specs-smoke.test.js` pass. | m50-gates-and-specs | T1, T2, T3 | done |
+| REQ-M50-D2-10 | Doc-ripple: `~/.claude/CLAUDE.md` + `templates/CLAUDE-global.md` + 8 command files (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`) + `docs/architecture.md` + `CHANGELOG.md`. Replace prose Playwright reminders with referrals to `playwright-bootstrap-contract.md`. | m50-gates-and-specs | T9 | done |
+| REQ-M50-VERIFY | Full unit suite: 2104 baseline + ~25 D1 + ~14 D2 = ~2143 expected, ≥2141 passing (preserves 2 known env-sensitive flakes). All 5 E2E specs pass. Spawn-gate fixture + pre-commit-hook fixture pass. | both | T10 (D2) | done |
+
+Supporting contracts:
+- `.gsd-t/contracts/playwright-bootstrap-contract.md` v1.0.0 — D1 library API + CLI wiring + idempotency invariants + error-path contract.
+- `.gsd-t/contracts/m50-integration-points.md` — D1↔D2 cross-domain checkpoint, the `bin/gsd-t.js` file-overlap coordination rules, and the doc-ripple ordering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.21.11",
+  "version": "3.22.10",
   "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",
@@ -23,8 +23,13 @@
   },
   "scripts": {
     "test": "node --test",
+    "e2e": "playwright test",
+    "e2e:install": "playwright install chromium",
     "prepublishOnly": "npm test"
   },
+  "devDependencies": {
+    "@playwright/test": "^1.55.0"
+  },
   "files": [
     "bin/",
     "commands/",

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);
 }

package/scripts/hooks/pre-commit-playwright-gate

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# GSD-T Playwright gate (M50 D2)
+# Blocks commits that touch viewer/UI source files when Playwright tests have
+# not passed since the most recent change. Reads `.gsd-t/.last-playwright-pass`
+# (Unix epoch ms in a single line) — written by `npx playwright test` post-pass.
+#
+# Install (opt-in):  gsd-t doctor --install-hooks
+# Remove:            rm .git/hooks/pre-commit  (or remove this block if merged
+#                    into an existing hook)
+#
+# Exit codes:
+#   0 — clean (no viewer-source files staged, OR fresh pass, OR fail-open path)
+#   1 — blocked (viewer-source modified after the last playwright pass)
+#
+# Fail-open philosophy (per m50 D2 constraints): a broken hook is worse than a
+# permissive one. Missing or corrupt `.last-playwright-pass` → exit 0 with a
+# stderr warning, never block.
+
+set -e
+
+# Resolve the project root (the dir that contains the repository's .git).
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+PASS_FILE="$ROOT/.gsd-t/.last-playwright-pass"
+
+# Patterns that count as "viewer/UI source" for gating purposes. Globs are
+# checked against the staged file list returned by git.
+VIEWER_SOURCE_PATTERNS=(
+  "scripts/gsd-t-transcript.html"
+  "scripts/gsd-t-dashboard-server.js"
+  "e2e/viewer/"
+)
+
+# Load staged file list (only added/modified — deletions don't need testing).
+STAGED="$(git diff --cached --name-only --diff-filter=AM 2>/dev/null || true)"
+
+# Quick exit when nothing is staged.
+[ -z "$STAGED" ] && exit 0
+
+# Find any staged path matching a viewer-source pattern.
+matches=""
+while IFS= read -r f; do
+  for p in "${VIEWER_SOURCE_PATTERNS[@]}"; do
+    case "$f" in
+      "$p"|"$p"*) matches="$matches $f"; break ;;
+    esac
+  done
+done <<EOF
+$STAGED
+EOF
+
+# No viewer-source files staged → silent pass.
+if [ -z "$matches" ]; then
+  exit 0
+fi
+
+# Viewer-source staged. Now require a fresh pass.
+if [ ! -f "$PASS_FILE" ]; then
+  echo "[playwright-gate] WARNING: .gsd-t/.last-playwright-pass missing — fail-open. Run 'npx playwright test' to record a pass." >&2
+  exit 0
+fi
+
+# Read timestamp; fail-open on corrupt content.
+LAST_PASS="$(tr -d '[:space:]' < "$PASS_FILE")"
+if ! echo "$LAST_PASS" | grep -Eq '^[0-9]+$'; then
+  echo "[playwright-gate] WARNING: .gsd-t/.last-playwright-pass is not a valid timestamp — fail-open." >&2
+  exit 0
+fi
+
+# Compare each staged viewer-source file's mtime (in ms) against LAST_PASS.
+# If any file has mtime > LAST_PASS, block.
+stale=""
+for f in $matches; do
+  fpath="$ROOT/$f"
+  if [ -f "$fpath" ]; then
+    # GNU stat: -c %Y (seconds); BSD stat: -f %m. We want milliseconds.
+    if mtime_s=$(stat -c %Y "$fpath" 2>/dev/null) || mtime_s=$(stat -f %m "$fpath" 2>/dev/null); then
+      mtime_ms=$((mtime_s * 1000))
+      if [ "$mtime_ms" -gt "$LAST_PASS" ]; then
+        stale="$stale $f"
+      fi
+    fi
+  fi
+done
+
+if [ -n "$stale" ]; then
+  echo "[playwright-gate] BLOCKED: viewer-source modified since last playwright pass." >&2
+  echo "  Stale files:$stale" >&2
+  echo "  Last pass:  $(date -r "$((LAST_PASS / 1000))" 2>/dev/null || echo "$LAST_PASS")" >&2
+  echo "" >&2
+  echo "  Run 'npx playwright test' before committing, or run 'gsd-t doctor --install-playwright' if Playwright isn't set up." >&2
+  exit 1
+fi
+
+exit 0

package/templates/CLAUDE-global.md

@@ -194,15 +194,19 @@ If any are missing:
 
 **Exempt commands** (do not trigger auto-init): `gsd-t-init`, `gsd-t-init-scan-setup`, `gsd-t-help`, `gsd-t-version-update`, `gsd-t-version-update-all`.
 
-## Playwright Readiness Guard
+## Playwright Readiness Guard (M50 — deterministic enforcement)
 
-Before any command that involves testing (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`), check if `playwright.config.*` exists in the project. If it does not:
-1. Detect the package manager and install Playwright (`@playwright/test` + chromium)
-2. Create a basic `playwright.config.ts` with sensible defaults
-3. Create the E2E test directory with a placeholder spec
-4. Then continue with the original command
+Playwright readiness is enforced by executable code, not prose. Three layers:
 
-Playwright must always be ready before any testing occurs. Do not skip this check. Do not defer setup to "later."
+1. **Bootstrap library** — `bin/playwright-bootstrap.cjs` exports `hasPlaywright`, `detectPackageManager`, `installPlaywright`, `verifyPlaywrightHealth`. `bin/ui-detection.cjs` exports `hasUI`, `detectUIFlavor`. See `.gsd-t/contracts/playwright-bootstrap-contract.md`.
+2. **Spawn-time gate** — `bin/headless-auto-spawn.cjs::autoSpawnHeadless()` auto-installs Playwright before the spawn proceeds, when the command being run is in the testing/UI whitelist (`gsd-t-execute`, `gsd-t-test-sync`, `gsd-t-verify`, `gsd-t-quick`, `gsd-t-wave`, `gsd-t-milestone`, `gsd-t-complete-milestone`, `gsd-t-debug`, `gsd-t-integrate`) AND `hasUI(projectDir)` AND `!hasPlaywright(projectDir)`. On install failure, the gate writes `mode: 'blocked-needs-human'` to the headless session-state file and exits 4.
+3. **Commit-time gate** — `scripts/hooks/pre-commit-playwright-gate` (opt-in via `gsd-t doctor --install-hooks`) blocks commits that touch viewer/UI source files when Playwright tests have not passed since the most recent change. Reads `.gsd-t/.last-playwright-pass`; fails open on missing/corrupt timestamps.
+
+Operator overrides:
+- Manual install: `gsd-t setup-playwright [path]` (or `gsd-t doctor --install-playwright`).
+- Health check: `gsd-t doctor` reports `playwright missing` for any UI project without `playwright.config.*`.
+
+You no longer need to run a check yourself before testing commands — the gate runs every spawn.
 
 ### Playwright Cleanup