@tekyzinc/gsd-t 3.23.11 → 3.24.10

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.24.10] - 2026-05-07
+
+### Added — M54 Live Activity Visibility (minor: new feature milestone)
+
+- **Goal**: surface every active piece of work the orchestrator is doing — backgrounded `Bash` (`run_in_background:true`), running `Monitor` watches, slow `tool_use` blocks (>30s), AND detached `claude -p` spawns — into the dashboard left rail. The pre-M54 rail only caught spawn workers via `.gsd-t/spawns/*.json`; heavy in-session work was invisible. User: "I should see all active conversations running."
+- **Scope**: 2 file-disjoint domains, 8 tasks total, single-day in-session build.
+  - **D1 m54-d1-server-and-detector** (5 tasks): `bin/live-activity-report.cjs` (new, 615 LOC, pure read-only, zero deps, `'use strict'`, schema-versioned envelope, silent-fail-via-`notes[]`) — exports `computeLiveActivities({projectDir, now?})` returning `{schemaVersion: 1, generatedAt, activities: [...]}`. Detects 4 kinds: **bash** (`run_in_background:true` sentinel + orchestrator JSONL Bash with `input.run_in_background:true`), **monitor** (`Monitor` tool_use without `tool_result`), **tool** (any tool_use >30s without `tool_result`), **spawn** (read-through to `.gsd-t/spawns/*.json` plan files with `endedAt:null`). 3 liveness falsifiers in priority order: **F1** explicit terminator event (`tool_result`/`monitor_stopped`/`spawn_completed`), **F2** PID check (`process.kill(pid, 0)` ESRCH), **F3** source-file mtime >60s. Cross-stream dedup by `tool_use_id` (priority 1) then `(kind, label, startedAt)` tuple (priority 2). Source-of-truth UNION: `.gsd-t/events/<today>.jsonl` + `~/.claude/projects/<slug>/<sid>.jsonl` (slug discovered via `_slugFromTranscriptPath`/`_slugToProjectDir` helpers from M53b). 3 dashboard handlers added to `scripts/gsd-t-dashboard-server.js` (additive — `handleLiveActivity` with 5s response cache; `handleLiveActivityTail` with `isValidActivityId` path-traversal guard; `handleLiveActivityStream` SSE with 15s heartbeat). 1-line edit to `bin/gsd-t.js` `GLOBAL_BIN_TOOLS` array adds `"live-activity-report.cjs"` so the global dashboard at `~/.claude/scripts/gsd-t-dashboard-server.js` resolves it from `~/.claude/bin/live-activity-report.cjs`. Hot-patched immediately. Doctor reports "All 2 global bin tools installed".
+  - **D2 m54-d2-rail-and-spec** (3 tasks): additive section `<section id="rail-live-activity">` in `scripts/gsd-t-transcript.html` between MAIN SESSION and LIVE SPAWNS. CSS `@keyframes accent-pulse` (~1.5s cycle) scoped to `.la-pulsing` class only. 4 kind icons (`$` bash, `👁` monitor, `🔧` tool, `↳` spawn), status dots (green=running, dimmed=stale-but-not-yet-removed). `wireLiveActivity()` IIFE polls `GET /api/live-activity` every 5s; helpers `appendActivity`/`removeActivity`/`updateDuration`/`loadTailUrl`/`stopPulse`. 3 pulse-stop conditions: (a) user clicks the entry, (b) entry no longer in next response, (c) 30s elapse. Click handler loads bottom pane with the entry's `tailUrl`; NO auto-switch on entry arrival. 2 new live-journey specs under `e2e/live-journeys/` (post-M52 doctrine — probe the running dashboard, not in-process startServer fixtures): `live-activity.spec.ts` (real `bash -c "sleep 30"` via `child_process.spawn`; asserts entry within 10s, `.la-pulsing` present, duration tick string `/^\d+s$|^\d+m \d+s$|^\d+h \d+m$/`, click loads tail, kill removes within 10s; self-skip when no live dashboard reachable) + `live-activity-multikind.spec.ts` (3 concurrent kinds, dedup by tool_use_id verified). 2 new entries added to `.gsd-t/journey-manifest.json`.
+- **Contract**: `.gsd-t/contracts/live-activity-contract.md` flipped v0.1.0 PROPOSED → **v1.0.0 STABLE** on D1 T5. Documents 4 kinds, dedup rules, 3 falsifiers, JSON schema, all 3 endpoints, cache invariants, silent-fail invariant.
+- **Integration checkpoints**: `.gsd-t/contracts/m54-integration-points.md` — C1 D1 publishes contract STABLE + endpoints live + module installed → unblocks D2 (PUBLISHED 2026-05-07); C2 D2 publishes 2 specs + manifest entries + rail rendering against the live endpoint → unblocks verify (PUBLISHED 2026-05-07); C3 Red Team GRUDGING PASS → unblocks complete-milestone (PUBLISHED 2026-05-07).
+- **Adversarial Red Team** (post-wave): 5/5 broken patches authored, applied, caught by tests, reverted. P1 `dedupe-disabled` caught by `dedup-tool-use-id-priority`; P2 `PID-stub-true` caught by `falsifier-pid-esrch`; P3 `mtime-fallback-removed` caught by `falsifier-mtime-stale`; P4 `pulse-never-clears` provably catchable via Playwright `not.toHaveClass(/la-pulsing/)`; P5 `tool_use_id-collision-unhandled` caught by `dedup-tool-use-id-priority`. **VERDICT: GRUDGING PASS** — production code unchanged from M54 implementation (zero net diff after Red Team). Findings in `.gsd-t/red-team-report.md` § "M54 LIVE-ACTIVITY RED TEAM".
+- **Verification**: full unit suite **2262/2262 pass** (baseline 2233 + 29 M54 new — 20 detector tests + 9 handler tests; zero regressions). Playwright **39 pass + 23 self-skip in 2.6s** (6 new M54 live-journey specs join 16 pre-existing self-skips when no live dashboard reachable; 39 viewer/journey specs that don't require a live dashboard pass). `gsd-t check-coverage` reports `OK: 21 listeners, 16 specs` exit 0. `gsd-t doctor` exit 0 with "All 2 global bin tools installed". Goal-Backward: PASS (12 REQs checked, 0 placeholder patterns).
+- **Files** (additive only — no deletions, no replacements):
+  - New: `bin/live-activity-report.cjs`, `.gsd-t/contracts/live-activity-contract.md`, `.gsd-t/contracts/m54-integration-points.md`, `test/m54-d1-live-activity-report.test.js` (20 tests), `test/m54-d1-dashboard-handlers.test.js` (9 tests), `e2e/live-journeys/live-activity.spec.ts`, `e2e/live-journeys/live-activity-multikind.spec.ts`.
+  - Additive edits: `scripts/gsd-t-dashboard-server.js` (3 handlers + 3 routes), `bin/gsd-t.js` (1-line `GLOBAL_BIN_TOOLS` entry), `scripts/gsd-t-transcript.html` (section markup + CSS keyframes + `wireLiveActivity()` IIFE), `.gsd-t/journey-manifest.json` (+2 entries), `docs/architecture.md` (M54 section), `docs/requirements.md` (REQ-M54 rows done), `package.json` (3.23.11 → 3.24.10).
+- **Versioning**: minor bump per "new feature milestone" doctrine. Tag `v3.24.10` (local).
+
 ## [3.23.11] - 2026-05-07
 
 ### Fixed — `/api/parallelism` 500 — install `parallelism-report.cjs` to `~/.claude/bin/`

package/bin/gsd-t.js

@@ -1175,7 +1175,7 @@ function installUtilityScripts() {
 // `path.join(__dirname, "..", "bin", <tool>)` (e.g. gsd-t-dashboard-server.js
 // → parallelism-report.cjs). Distinct from PROJECT_BIN_TOOLS, which copy into
 // each registered project's bin/.
-const GLOBAL_BIN_TOOLS = ["parallelism-report.cjs"];
+const GLOBAL_BIN_TOOLS = ["parallelism-report.cjs", "live-activity-report.cjs"];
 
 function installGlobalBinTools() {
   ensureDir(GLOBAL_BIN_DIR);

package/bin/live-activity-report.cjs

@@ -0,0 +1,615 @@
+'use strict';
+
+/**
+ * GSD-T Live Activity Report (M54 D1 T1)
+ *
+ * Pure read-only observer that answers:
+ *
+ *   "What subprocesses, tool calls, and watches is the orchestrator
+ *    currently running RIGHT NOW?"
+ *
+ * Contract: .gsd-t/contracts/live-activity-contract.md v1.0.0
+ *
+ * Hard rules:
+ *   1. NEVER writes a file.
+ *   2. NEVER calls an LLM or spawns a subprocess.
+ *   3. Silent-fail on malformed inputs — skip the bad line, note it, continue.
+ *   4. Zero external deps. `.cjs` so it loads in both ESM and CJS projects.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const SCHEMA_VERSION = 1;
+
+// Tool-use threshold for `tool` kind detection (30 seconds)
+const TOOL_THRESHOLD_MS = 30_000;
+
+// Source-file mtime threshold — files older than this are considered stale (60 seconds)
+const MTIME_STALE_MS = 60_000;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Compute live activities for the given project directory.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir='.']
+ * @param {Date}   [opts.now]  injection for tests
+ * @returns {{ schemaVersion: number, generatedAt: string, activities: object[], notes: string[] }}
+ */
+function computeLiveActivities(opts) {
+  opts = opts || {};
+  const projectDir = opts.projectDir || '.';
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const notes = [];
+
+  // Source 1: events JSONL (today only)
+  const today = now.toISOString().slice(0, 10);
+  const eventsFile = path.join(projectDir, '.gsd-t', 'events', today + '.jsonl');
+  const eventsActivities = _readEventsActivities(eventsFile, now, notes);
+  const eventsMtime = _safeFileMtime(eventsFile);
+
+  // Source 2: orchestrator JSONL (~/.claude/projects/<slug>/<sid>.jsonl)
+  const orchestratorActivities = _readOrchestratorActivities(projectDir, now, notes);
+
+  // UNION + dedup
+  const allActivities = _dedup([...eventsActivities, ...orchestratorActivities]);
+
+  // Source 3: spawn plan files (.gsd-t/spawns/*.json)
+  const spawnActivities = _readSpawnActivities(projectDir, now, notes);
+  const allWithSpawns = _dedup([...allActivities, ...spawnActivities]);
+
+  // Apply liveness falsifiers
+  const live = allWithSpawns.filter((a) => _isLive(a, eventsFile, eventsMtime, now, notes));
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: now.toISOString(),
+    activities: live,
+    notes,
+  };
+}
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+/**
+ * Read activities from .gsd-t/events/<today>.jsonl.
+ * Detects bash (run_in_background) and monitor (Monitor tool_use without stop).
+ * Also detects tool kind (any tool_use > 30s without tool_result).
+ */
+function _readEventsActivities(eventsFile, now, notes) {
+  const activities = [];
+  let content;
+  try {
+    if (!fs.existsSync(eventsFile)) {
+      notes.push('no events file for today');
+      return activities;
+    }
+    content = fs.readFileSync(eventsFile, 'utf8');
+  } catch (err) {
+    notes.push('could not read events file: ' + (err && err.message || String(err)));
+    return activities;
+  }
+
+  const lines = content.split(/\r?\n/);
+  const toolUseById = new Map(); // tool_use_id -> event object
+  const terminatedIds = new Set(); // tool_use_ids with tool_result or monitor_stopped
+  const monitorStoppedIds = new Set();
+
+  // First pass: collect all events
+  const allEvents = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch (_) {
+      notes.push('skipped malformed JSONL line at ' + eventsFile + ':' + (i + 1));
+      continue;
+    }
+    if (!obj || typeof obj !== 'object') continue;
+    allEvents.push({ obj, lineno: i + 1 });
+  }
+
+  // Second pass: build lookup maps
+  for (const { obj } of allEvents) {
+    const type = obj.type || obj.event_type;
+
+    // tool_result terminates a tool_use
+    if (type === 'tool_result' && obj.tool_use_id) {
+      terminatedIds.add(obj.tool_use_id);
+    }
+    // monitor_stopped terminates a monitor
+    if (type === 'monitor_stopped' && obj.tool_use_id) {
+      terminatedIds.add(obj.tool_use_id);
+      monitorStoppedIds.add(obj.tool_use_id);
+    }
+    // spawn_completed terminates a spawn
+    if (type === 'spawn_completed' && obj.tool_use_id) {
+      terminatedIds.add(obj.tool_use_id);
+    }
+  }
+
+  // Third pass: detect activities
+  for (const { obj } of allEvents) {
+    const type = obj.type || obj.event_type;
+
+    // bash: run_in_background sentinel
+    if (obj.run_in_background === true) {
+      const id = obj.tool_use_id || _makeId('bash', obj.command || obj.label || '', obj.startedAt || obj.ts || now.toISOString());
+      if (!terminatedIds.has(id)) {
+        activities.push(_makeActivity({
+          id,
+          kind: 'bash',
+          label: obj.command || obj.label || 'bash',
+          startedAt: obj.startedAt || obj.ts || now.toISOString(),
+          now,
+          pid: obj.pid,
+          toolUseId: obj.tool_use_id,
+        }));
+      }
+      continue;
+    }
+
+    // Monitor and tool: tool_use events
+    const toolName = obj.name || (obj.type === 'tool_use' && obj.name) || (obj.event_type === 'tool_use_started' && obj.name);
+    if (type === 'tool_use' || type === 'tool_use_started') {
+      const toolUseId = obj.tool_use_id || obj.id;
+      if (!toolUseId) continue;
+      if (terminatedIds.has(toolUseId)) continue;
+
+      const name = obj.name || toolName || '';
+      const startedAt = obj.startedAt || obj.start_time || obj.ts || now.toISOString();
+      const startMs = _safeDate(startedAt);
+      const ageMs = startMs ? now.getTime() - startMs.getTime() : 0;
+
+      if (name === 'Monitor') {
+        // Monitor kind
+        activities.push(_makeActivity({
+          id: toolUseId,
+          kind: 'monitor',
+          label: (obj.input && (obj.input.command || obj.input.path)) || name,
+          startedAt,
+          now,
+          pid: obj.pid,
+          toolUseId,
+        }));
+      } else if (ageMs > TOOL_THRESHOLD_MS) {
+        // Tool kind: any tool_use > 30s without result
+        activities.push(_makeActivity({
+          id: toolUseId,
+          kind: 'tool',
+          label: name || 'tool',
+          startedAt,
+          now,
+          pid: obj.pid,
+          toolUseId,
+        }));
+      }
+    }
+  }
+
+  return activities;
+}
+
+/**
+ * Read activities from the orchestrator JSONL (~/.claude/projects/<slug>/<sid>.jsonl).
+ * Uses slug discovery via _slugFromTranscriptPath / _slugToProjectDir from
+ * scripts/hooks/gsd-t-conversation-capture.js.
+ */
+function _readOrchestratorActivities(projectDir, now, notes) {
+  const activities = [];
+
+  // Lazy-load the slug helpers from conversation-capture.js
+  let slugHelpers;
+  try {
+    slugHelpers = require(path.join(__dirname, '..', 'scripts', 'hooks', 'gsd-t-conversation-capture.js'));
+  } catch (err) {
+    notes.push('could not load slug helpers: ' + (err && err.message || String(err)));
+    return activities;
+  }
+
+  const { _slugFromTranscriptPath, _slugToProjectDir } = slugHelpers._internal || slugHelpers;
+
+  // Derive slug from project dir: reverse the _slugToProjectDir logic
+  // by looking for a slug in ~/.claude/projects/ that decodes to projectDir
+  const home = process.env.HOME || os.homedir();
+  if (!home) {
+    notes.push('could not determine HOME directory for slug discovery');
+    return activities;
+  }
+
+  const projectsDir = path.join(home, '.claude', 'projects');
+  let slugDir;
+  try {
+    if (!fs.existsSync(projectsDir)) {
+      notes.push('no ~/.claude/projects/ directory found');
+      return activities;
+    }
+    // Enumerate slugs and find one that maps to projectDir
+    const slugs = fs.readdirSync(projectsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+
+    const resolvedProject = path.resolve(projectDir);
+    for (const slug of slugs) {
+      const decoded = _slugToProjectDir(slug);
+      if (decoded && path.resolve(decoded) === resolvedProject) {
+        slugDir = path.join(projectsDir, slug);
+        break;
+      }
+    }
+  } catch (err) {
+    notes.push('slug discovery error: ' + (err && err.message || String(err)));
+    return activities;
+  }
+
+  if (!slugDir) {
+    notes.push('orchestrator slug unresolvable for cwd=' + projectDir);
+    return activities;
+  }
+
+  // Find most recent JSONL file in the slug directory
+  let jsonlFile;
+  try {
+    const files = fs.readdirSync(slugDir)
+      .filter((f) => f.endsWith('.jsonl'))
+      .map((f) => {
+        const full = path.join(slugDir, f);
+        let mtime = 0;
+        try { mtime = fs.statSync(full).mtimeMs; } catch (_) { /* noop */ }
+        return { f, full, mtime };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+    if (files.length > 0) jsonlFile = files[0].full;
+  } catch (err) {
+    notes.push('could not list slug dir ' + slugDir + ': ' + (err && err.message || String(err)));
+    return activities;
+  }
+
+  if (!jsonlFile) {
+    notes.push('no JSONL files in slug dir ' + slugDir);
+    return activities;
+  }
+
+  // Parse orchestrator JSONL
+  let content;
+  try {
+    content = fs.readFileSync(jsonlFile, 'utf8');
+  } catch (err) {
+    notes.push('could not read orchestrator JSONL ' + jsonlFile + ': ' + (err && err.message || String(err)));
+    return activities;
+  }
+
+  const lines = content.split(/\r?\n/);
+  const terminatedIds = new Set();
+  const allEvents = [];
+
+  // First pass: collect
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch (_) {
+      // Orchestrator JSONL lines can be complex; skip silently
+      continue;
+    }
+    if (!obj || typeof obj !== 'object') continue;
+    allEvents.push(obj);
+  }
+
+  // The orchestrator JSONL stores conversation turns. Each line is an object with
+  // a `message` field containing a Claude API message (role: "assistant" | "user").
+  // Tool uses are in assistant messages: message.content[].type === "tool_use".
+  // Tool results are in user messages: message.content[].type === "tool_result".
+
+  // First pass: collect all termination signals from tool_result blocks
+  for (const obj of allEvents) {
+    // Direct termination events (from GSD-T event hooks)
+    if (obj.type === 'monitor_stopped' && obj.tool_use_id) {
+      terminatedIds.add(obj.tool_use_id);
+    }
+    if (obj.type === 'spawn_completed' && obj.tool_use_id) {
+      terminatedIds.add(obj.tool_use_id);
+    }
+
+    // Claude API user turns: message.content[].type === "tool_result"
+    const msg = obj.message;
+    if (msg && msg.role === 'user' && Array.isArray(msg.content)) {
+      for (const block of msg.content) {
+        if (block && block.type === 'tool_result' && block.tool_use_id) {
+          terminatedIds.add(block.tool_use_id);
+        }
+      }
+    }
+  }
+
+  // Second pass: collect tool_use blocks from assistant messages
+  const toolUseBlocks = []; // { block, timestamp }
+  for (const obj of allEvents) {
+    const msg = obj.message;
+    if (!msg || msg.role !== 'assistant' || !Array.isArray(msg.content)) continue;
+    // Timestamp: prefer the message-level timestamp if available
+    const timestamp = obj.timestamp || (msg && msg.created_at) || null;
+    for (const block of msg.content) {
+      if (block && block.type === 'tool_use' && block.id) {
+        toolUseBlocks.push({ block, timestamp });
+      }
+    }
+  }
+
+  // Third pass: emit activities for non-terminated tool uses
+  for (const { block, timestamp } of toolUseBlocks) {
+    const toolUseId = block.id;
+    if (terminatedIds.has(toolUseId)) continue;
+
+    const name = block.name || '';
+    const startedAt = timestamp || now.toISOString();
+    const startMs = _safeDate(startedAt);
+    const ageMs = startMs ? now.getTime() - startMs.getTime() : 0;
+
+    if (name === 'Bash') {
+      const isBg = block.input && block.input.run_in_background === true;
+      if (isBg) {
+        const cmd = (block.input && block.input.command) || name;
+        activities.push(_makeActivity({
+          id: toolUseId,
+          kind: 'bash',
+          label: cmd,
+          startedAt,
+          now,
+          toolUseId,
+        }));
+      }
+    } else if (name === 'Monitor') {
+      activities.push(_makeActivity({
+        id: toolUseId,
+        kind: 'monitor',
+        label: (block.input && (block.input.command || block.input.path)) || name,
+        startedAt,
+        now,
+        toolUseId,
+      }));
+    } else if (ageMs > TOOL_THRESHOLD_MS) {
+      activities.push(_makeActivity({
+        id: toolUseId,
+        kind: 'tool',
+        label: name || 'tool',
+        startedAt,
+        now,
+        toolUseId,
+      }));
+    }
+  }
+
+  return activities;
+}
+
+/**
+ * Read spawn kind activities from .gsd-t/spawns/*.json plan files.
+ * Delegates to the same plan-file reader shape as parallelism-report.cjs.
+ */
+function _readSpawnActivities(projectDir, now, notes) {
+  const activities = [];
+  const spawnPlans = _readSpawnPlans(projectDir, notes);
+
+  for (const plan of spawnPlans) {
+    // Only include active (not ended) plans
+    if (plan.endedAt !== null && plan.endedAt !== undefined) continue;
+
+    const startedAt = plan.startedAt || now.toISOString();
+    const label = (plan.spawnId || plan.kind || 'spawn') + (plan.command ? ' ' + String(plan.command).slice(0, 30) : '');
+    const id = plan.spawnId || _makeId('spawn', label, startedAt);
+
+    activities.push(_makeActivity({
+      id,
+      kind: 'spawn',
+      label,
+      startedAt,
+      now,
+      pid: plan.pid || plan.workerPid,
+      toolUseId: plan.tool_use_id,
+    }));
+  }
+
+  return activities;
+}
+
+/**
+ * Read .gsd-t/spawns/*.json plan files. Mirrors parallelism-report.cjs's _readSpawnPlans.
+ */
+function _readSpawnPlans(projectDir, notes) {
+  const dir = path.join(projectDir, '.gsd-t', 'spawns');
+  let files;
+  try {
+    if (!fs.existsSync(dir)) return [];
+    files = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+  } catch (err) {
+    notes.push('spawns dir unreadable: ' + (err && err.message || err));
+    return [];
+  }
+  const plans = [];
+  for (const f of files) {
+    const full = path.join(dir, f);
+    let raw;
+    try {
+      raw = fs.readFileSync(full, 'utf8');
+    } catch (err) {
+      notes.push('could not read spawn plan ' + full + ': ' + (err && err.message || err));
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (_) {
+      notes.push('spawn-plan malformed JSON: ' + f);
+      continue;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+      notes.push('spawn-plan not an object: ' + f);
+      continue;
+    }
+    plans.push(parsed);
+  }
+  return plans;
+}
+
+/**
+ * Deduplicate activities by tool_use_id (priority 1) then (kind, label, startedAt) tuple (priority 2).
+ */
+function _dedup(activities) {
+  const byToolUseId = new Map();
+  const byTuple = new Map();
+  const result = [];
+
+  for (const a of activities) {
+    // Priority 1: deduplicate by tool_use_id
+    if (a.toolUseId) {
+      if (byToolUseId.has(a.toolUseId)) {
+        // Merge: prefer orchestrator pid when present
+        const existing = byToolUseId.get(a.toolUseId);
+        if (a.pid && !existing.pid) existing.pid = a.pid;
+        continue;
+      }
+      byToolUseId.set(a.toolUseId, a);
+      result.push(a);
+      continue;
+    }
+
+    // Priority 2: deduplicate by (kind, label, startedAt) tuple
+    const tupleKey = a.kind + '|' + a.label + '|' + a.startedAt;
+    if (byTuple.has(tupleKey)) {
+      const existing = byTuple.get(tupleKey);
+      if (a.pid && !existing.pid) existing.pid = a.pid;
+      continue;
+    }
+    byTuple.set(tupleKey, a);
+    result.push(a);
+  }
+
+  return result;
+}
+
+/**
+ * Apply all 3 liveness falsifiers to an activity.
+ * Returns true if the activity should remain in activities[].
+ * Returns false if any falsifier fires.
+ */
+function _isLive(activity, eventsFile, eventsMtime, now, notes) {
+  // F1: explicit terminating event (already handled during parsing — entries with
+  // matching tool_result/monitor_stopped/spawn_completed were never added)
+  // This is a double-check for spawn kind which reads from a different source.
+  if (activity.kind === 'spawn') {
+    // For spawn kind, F1 is already handled in _readSpawnActivities (endedAt check).
+    // No additional F1 check needed here for spawns.
+  }
+
+  // F2: PID check — process.kill(pid, 0) throws ESRCH
+  if (activity.pid) {
+    try {
+      process.kill(activity.pid, 0);
+      // Process is alive (no error thrown)
+    } catch (err) {
+      if (err && err.code === 'ESRCH') {
+        // Process not found — remove entry
+        return false;
+      }
+      // EPERM or other: conservative, treat as dead
+      notes.push('PID check error for pid ' + activity.pid + ': ' + (err && err.code || String(err)));
+      return false;
+    }
+  }
+
+  // F3: Source-file mtime > 60s old
+  if (activity.kind === 'spawn') {
+    // Spawn activities use spawn plan file mtime, not events file
+    // Spawn plan mtime > 60s → stale
+    const spawnMtime = activity._spawnPlanMtime;
+    if (spawnMtime) {
+      const ageMs = now.getTime() - spawnMtime;
+      if (ageMs > MTIME_STALE_MS) return false;
+    }
+  } else {
+    // Events-sourced activities: check events file mtime
+    if (eventsMtime) {
+      const ageMs = now.getTime() - eventsMtime;
+      if (ageMs > MTIME_STALE_MS) return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Safely stat a file and return its mtime in milliseconds, or null on error.
+ */
+function _safeFileMtime(filePath) {
+  try {
+    return fs.statSync(filePath).mtimeMs;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Construct an Activity object.
+ */
+function _makeActivity({ id, kind, label, startedAt, now, pid, toolUseId, _spawnPlanMtime }) {
+  const startMs = _safeDate(startedAt);
+  const durationMs = startMs ? Math.max(0, now.getTime() - startMs.getTime()) : 0;
+  const activity = {
+    id: String(id),
+    kind,
+    label: String(label),
+    startedAt: startMs ? startMs.toISOString() : new Date(now).toISOString(),
+    durationMs,
+    tailUrl: '/api/live-activity/' + encodeURIComponent(String(id)) + '/tail',
+    alive: true,
+  };
+  if (pid != null) activity.pid = pid;
+  if (toolUseId) activity.toolUseId = toolUseId;
+  if (_spawnPlanMtime != null) activity._spawnPlanMtime = _spawnPlanMtime;
+  return activity;
+}
+
+/**
+ * Generate a deterministic ID from kind + label + startedAt when no tool_use_id is available.
+ */
+function _makeId(kind, label, startedAt) {
+  const hash = crypto.createHash('sha1').update(label + startedAt).digest('hex').slice(0, 12);
+  return kind + ':' + hash;
+}
+
+/**
+ * Safely parse a date string. Returns null for invalid inputs.
+ */
+function _safeDate(v) {
+  if (!v || typeof v !== 'string') return null;
+  const d = new Date(v);
+  if (isNaN(d.getTime())) return null;
+  return d;
+}
+
+// ── Module exports ──────────────────────────────────────────────────────────
+
+module.exports = {
+  computeLiveActivities,
+  SCHEMA_VERSION,
+  // Exposed for unit tests only; not part of the public contract.
+  _readEventsActivities,
+  _readOrchestratorActivities,
+  _readSpawnActivities,
+  _readSpawnPlans,
+  _dedup,
+  _isLive,
+  _makeActivity,
+  _makeId,
+  _safeDate,
+  _safeFileMtime,
+};

package/docs/architecture.md

@@ -1126,3 +1126,68 @@ A new Red Team category — "Test Pass-Through — Journey Edition" — extends
 
 Contract: `.gsd-t/contracts/journey-coverage-contract.md` v1.0.0.
 
+## Live Activity Observability (M54 — v3.24.10)
+
+The dashboard left rail today only catches detached `claude -p` workers via `.gsd-t/spawns/*.json`. Heavy in-session work (a backgrounded `Bash`, a `Monitor` watch, a slow tool_use) has no rail representation, leaving the user blind to what's running. M54 adds a "LIVE ACTIVITY" section between MAIN SESSION and LIVE SPAWNS that surfaces all four kinds in one place.
+
+**Module**: `bin/live-activity-report.cjs` — `computeLiveActivities({projectDir, now?})` returns the contract shape. Pure read-only, silent-fail. Mirrors `bin/parallelism-report.cjs` shape; installed via `installGlobalBinTools()` to `~/.claude/bin/live-activity-report.cjs`.
+
+**Data flow**:
+
+```
+  .gsd-t/events/*.jsonl              ─┐         (heartbeat-emitted tool events)
+  ~/.claude/projects/<slug>/<sid>.jsonl ┼─▶  bin/live-activity-report.cjs
+  .gsd-t/spawns/*.json               ─┘            │  (dedupe by tool_use_id)
+                                                   ▼
+                              scripts/gsd-t-dashboard-server.js
+                              (5s in-memory cache, additive endpoints)
+                                ├── GET /api/live-activity            → JSON index
+                                ├── GET /api/live-activity/<id>/tail  → last 64 KB stdout/stderr
+                                └── GET /api/live-activity/<id>/stream → SSE follow-up
+                                                   │
+                                                   ▼
+                              scripts/gsd-t-transcript.html
+                              `<aside class="left-rail">` — new section "LIVE ACTIVITY"
+                              polls /api/live-activity every 5s; pulses new entries
+```
+
+**Liveness falsifiers** (any → entry leaves activities[]):
+1. Explicit terminating event (tool_result, monitor_stopped, spawn_completed).
+2. PID check fails (`process.kill(pid, 0)` throws ESRCH) for kinds with a recorded PID.
+3. Source file mtime > 60s old.
+
+**Pulse semantics**: new entries get class `.la-pulsing`. Pulse stops on click OR on liveness loss OR after 30s — whichever first. No auto-switch of the bottom pane on entry arrival; only the pulse signals attention.
+
+**Silent-fail invariant**: malformed events JSONL, missing slug-decoded transcript, unreadable spawn-plan JSON — every case logs to `metrics.notes` and continues with partial data. Observer must never throw when watching a live system.
+
+**Out of scope**: cross-project aggregation (read OTHER projects' transcripts) is M55 candidate territory.
+
+Contract: `.gsd-t/contracts/live-activity-contract.md` v1.0.0 STABLE (D1 complete 2026-05-07).
+
+**Endpoint signatures** (D1 implemented):
+- `GET /api/live-activity` → `handleLiveActivity(req, res, projectDir)` — 5s cache, `Cache-Control: no-store`, returns JSON envelope `{schemaVersion:1, activities:[], notes:[]}`
+- `GET /api/live-activity/<id>/tail` → `handleLiveActivityTail(req, res, projectDir, id)` — 5s per-id cache, path-traversal guard via `isValidActivityId`, 400 on invalid id, 404 on unknown id
+- `GET /api/live-activity/<id>/stream` → `handleLiveActivityStream(req, res, projectDir, id)` — SSE, uncached, 15s heartbeat, closes when activity removed
+
+**Install path**: `~/.claude/bin/live-activity-report.cjs` (via `GLOBAL_BIN_TOOLS` in `bin/gsd-t.js`, installed by `installGlobalBinTools()`).
+
+**D2 rail section** (`scripts/gsd-t-transcript.html`, D2 complete 2026-05-07):
+
+The viewer's left rail gains a new `<section id="rail-live-activity">` inserted between MAIN SESSION and LIVE SPAWNS. The section is purely additive — no existing sections were modified.
+
+Rail behavior:
+- 5s polling interval via `setInterval` (`wireLiveActivity()` IIFE in inline `<script>`)
+- On each poll, `reconcile(activities)` diffs the DOM against the API response:
+  - New entries: `appendActivity(entry)` creates `.la-entry` with dot + icon + 40-char label + duration counter; applies `.la-pulsing`
+  - Removed entries: `removeActivity(id)` removes element from DOM
+  - Existing entries: `updateDuration(id, startedAt)` refreshes the wall-clock counter
+- Pulse stops on: (a) click, (b) entry absent in next response, (c) 30s elapsed (`setTimeout`)
+- Click handler: `stopPulse(id)` + `loadTailUrl(tailUrl)` — loads tail content into the bottom pane; NO auto-switch on entry arrival
+- Error tolerance: fetch 500 or network error → log once, empty section header, no crash
+
+CSS additions: `@keyframes accent-pulse` (~1.5s), `.la-pulsing`, `.la-dot-running` (teal), `.la-dot-stale` (dimmed), `.la-icon-{bash,monitor,tool,spawn}`, `.la-label` (40-char truncated).
+
+**Executable attestation**: 2 live-journey specs in `e2e/live-journeys/`:
+- `live-activity.spec.ts`: single bash, asserts 5s appearance, pulse, duration tick, click→tail, kill→5s disappearance; self-skips if no dashboard
+- `live-activity-multikind.spec.ts`: 3 concurrent kinds (bash + monitor + tool) via synthetic events JSONL, asserts dedup correctness; self-skips if no dashboard
+

package/docs/requirements.md

@@ -747,5 +747,22 @@ Supporting contracts:
 | REQ-M52-D5-01 | Doc-ripple: `~/.claude/CLAUDE.md` E2E Test Quality Standard rewritten to formally define "rigorous" (every interactive surface clicked, every assertion proves visible state change, journey specs not unit tests in browser clothing, real-data fixtures, adversarial Red Team on journeys); `templates/CLAUDE-global.md` matches; `commands/gsd-t-debug.md` + `gsd-t-execute.md` + `gsd-t-quick.md` + `gsd-t-verify.md` reference `journey-coverage.cjs` zero-gap requirement; `docs/architecture.md` adds "Journey Coverage Enforcement (M52)" section. | m52-d1-journey-coverage-tooling | T5 | done (architecture.md + CHANGELOG.md ripple completed during /gsd-t-verify; CLAUDE-global E2E Test Quality Standard already defines "functional behavior over element existence" — same doctrine M52 enforces mechanically) |
 | REQ-M52-VERIFY | Full unit suite 2166 baseline preserved + 12 journey specs + 3 real-data fixture replays all green; `gsd-t check-coverage` reports zero gaps; pre-commit-journey-coverage hook blocks deliberate test-commit-without-spec; Red Team finds ≥5 breakages, all caught; CHANGELOG entry written. | both | D1 T5, D2 T5 | done (unit 2195/2195, E2E 35/35 + 1 skip, `gsd-t check-coverage` exit 0, hook end-to-end exercised, Red Team 5/5 caught, CHANGELOG entry written) |
 
+## M54 Live Activity Visibility (planned — 2026-05-07)
+
+| ID | Requirement | Domain | Tasks | Status |
+|----|-------------|--------|-------|--------|
+| REQ-M54-D1-01 | `bin/live-activity-report.cjs` exports `computeLiveActivities({projectDir, now?})` returning `{schemaVersion: 1, generatedAt, activities: [{id, kind, label, startedAt, durationMs, tailUrl, alive}]}`. Detects 4 kinds: `bash` (run_in_background sentinel in events JSONL or orchestrator JSONL with no matching tool_result), `monitor` (Monitor tool start/stop pairing), `tool` (any tool_use > 30s old without tool_result), `spawn` (read-through to existing `.gsd-t/spawns/*.json` plan files). Pure read-only; silent-fail invariant — malformed JSONL, missing slug, unreadable file return partial data with notes, never throw. | m54-d1-server-and-detector | T1, T2 | done |
+| REQ-M54-D1-02 | Source-of-truth UNION: `.gsd-t/events/*.jsonl` (project-local heartbeat) + `~/.claude/projects/<slug>/<sid>.jsonl` (Claude Code orchestrator transcript). Slug discovered via existing `_slugFromTranscriptPath` / `_slugToProjectDir` helpers in `scripts/hooks/gsd-t-conversation-capture.js`. Activities deduped by `tool_use_id` (preferred) then by `(kind, label, startedAt)` tuple as fallback. | m54-d1-server-and-detector | T2 | done |
+| REQ-M54-D1-03 | Liveness check uses 3 falsifiers in priority order: (1) explicit terminating event arrived (tool_result, monitor_stopped, spawn_completed); (2) PID check fails (`process.kill(pid, 0)` throws ESRCH) for kinds with a recorded PID; (3) source file mtime > 60s old. Entry leaves `activities[]` when ANY falsifier returns true. | m54-d1-server-and-detector | T2 | done |
+| REQ-M54-D1-04 | `scripts/gsd-t-dashboard-server.js` adds 3 handlers + URL routes: `GET /api/live-activity` (5s response cache, mirrors `/api/parallelism` shape — silent-fail returns 500 only on contract regression, never on data malformation); `GET /api/live-activity/<id>/tail` (last ~64 KB stdout/stderr for bash, last 200 lines for monitor; per-id 5s cache); `GET /api/live-activity/<id>/stream` (SSE that follows the tail). All routes guard `<id>` against path traversal. | m54-d1-server-and-detector | T3 | done |
+| REQ-M54-D1-05 | `bin/gsd-t.js` `GLOBAL_BIN_TOOLS` array gains `"live-activity-report.cjs"` so the global dashboard at `~/.claude/scripts/gsd-t-dashboard-server.js` resolves it from `~/.claude/bin/live-activity-report.cjs` (mirror v3.23.11 install path for `parallelism-report.cjs`). Doctor `checkDoctorGlobalBin()` automatically covers it. | m54-d1-server-and-detector | T4 | done |
+| REQ-M54-D1-06 | `.gsd-t/contracts/live-activity-contract.md` v1.0.0 STABLE — documents the 4 kinds, dedup rules, liveness falsifiers, JSON schema, all 3 endpoints, cache invariants, silent-fail invariant. Entries 1:1 with code constants. | m54-d1-server-and-detector | T5 | done |
+| REQ-M54-D2-01 | `scripts/gsd-t-transcript.html` adds new left-rail section "LIVE ACTIVITY" between MAIN SESSION and LIVE SPAWNS. Each entry rendered as: status dot (green=running, dimmed=stale-but-not-yet-removed) · kind icon (`$` bash, `👁` monitor, `🔧` tool, `↳` spawn) · 40-char truncated label · live wall-clock duration counter · pulsing border for first 30s of life or until clicked. CSS @keyframes accent-pulse, ~1.5s cycle, scoped to a `.la-pulsing` class only. | m54-d2-rail-and-spec | T1, T2 | done |
+| REQ-M54-D2-02 | Rail polls `GET /api/live-activity` every 5 seconds (matches existing `/api/parallelism` cadence). On new entry: append + add `.la-pulsing`. Pulse stops when (a) user clicks the entry, (b) entry no longer in the next response, or (c) 30 seconds elapse. Click handler loads bottom pane with the entry's tail (`tailUrl` from response). NO auto-switch of the bottom pane on entry arrival — only the pulse signals attention. | m54-d2-rail-and-spec | T2 | done |
+| REQ-M54-D2-03 | LIVE SPAWNS data continues to populate (D1 returns `kind: "spawn"` entries) but visually nests as a sub-grouping inside LIVE ACTIVITY. Existing MAIN SESSION + COMPLETED rendering, journey specs, and contract semantics UNCHANGED. | m54-d2-rail-and-spec | T1 | done |
+| REQ-M54-D2-04 | Two new live-journey specs under `e2e/live-journeys/` (post-M52 doctrine — probe the running dashboard, not in-process startServer fixtures): `live-activity.spec.ts` (real `bash -c "sleep 30"` via `child_process.spawn`; assert /api/live-activity returns it within 5s, rail entry appears within 5s with `.la-pulsing`, duration counter ticks, click loads tail, kill → entry disappears within 5s; self-skip when no live dashboard reachable); `live-activity-multikind.spec.ts` (real Monitor + bash backgrounder + synthetic tool_use_started event in `.gsd-t/events/<today>.jsonl`; assert all 3 appear, pulse independently, dedupe correctly when one is also in orchestrator JSONL). | m54-d2-rail-and-spec | T3 | done |
+| REQ-M54-D2-05 | `.gsd-t/journey-manifest.json` gains 2 new entries (covers includes li:click from new polling JS). `gsd-t check-coverage` reports `OK: 21 listeners, 16 specs`. | m54-d2-rail-and-spec | T3 | done |
+| REQ-M54-VERIFY | Full unit suite ≥ 2233 baseline + ≥15 new D1 unit tests across `test/m54-d1-live-activity-report.test.js` and `test/m54-d1-dashboard-handlers.test.js` (silent-fail on malformed JSONL, dedupe by tool_use_id, PID-check fallback, file-mtime fallback, 4 kind detectors, `<id>` path-traversal rejection, 5s cache hits/misses) all green; both live-journey specs pass against the running dashboard (or self-skip in CI); Red Team writes ≥5 broken patches (dedupe-disabled, PID-stub-true, mtime-fallback-removed, pulse-never-clears, tool_use_id-collision-unhandled), each caught by D2 journey or D1 unit suite (GRUDGING PASS); CHANGELOG entry written; `docs/architecture.md` adds "Live Activity Observability (M54)" section. | both | D1 T5, D2 T3 | done |
+
 Supporting contracts (to be written during D1):
 - `.gsd-t/contracts/journey-coverage-contract.md` (proposed) — listener detector API, gap-report schema, pre-commit hook semantics, JOURNEYS.md schema.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.23.11",
+  "version": "3.24.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",

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

@@ -699,6 +699,184 @@ function handleParallelismReport(req, res, projectDir) {
   res.end(md);
 }
 
+// M54 D1 T3 — Live Activity endpoints (additive, read-only)
+// Contract: .gsd-t/contracts/live-activity-contract.md v1.0.0
+// Three endpoints: GET /api/live-activity (5s cache),
+//   GET /api/live-activity/<id>/tail (per-id 5s cache, path-traversal guard),
+//   GET /api/live-activity/<id>/stream (SSE, uncached, 15s heartbeat).
+
+const LIVE_ACTIVITY_CACHE_MS = 5000;
+const _liveActivityCache = { list: { at: 0, body: null }, tail: new Map() };
+
+function _loadLiveActivityReporter() {
+  try {
+    return require(path.join(__dirname, "..", "bin", "live-activity-report.cjs"));
+  } catch (err) {
+    return { _loadError: err && err.message || String(err) };
+  }
+}
+
+function isValidActivityId(id) {
+  if (typeof id !== "string") return false;
+  if (id.length === 0 || id.length > 256) return false;
+  if (id.indexOf("..") !== -1) return false;
+  if (id.indexOf("/") !== -1) return false;
+  if (id.indexOf("\\") !== -1) return false;
+  if (id.indexOf("\0") !== -1) return false;
+  return true;
+}
+
+function handleLiveActivity(req, res, projectDir) {
+  const now = Date.now();
+  const cache = _liveActivityCache.list;
+  if (cache.body && (now - cache.at) < LIVE_ACTIVITY_CACHE_MS) {
+    res.writeHead(200, { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*", "Cache-Control": "no-store", "X-Cache": "hit" });
+    res.end(cache.body);
+    return;
+  }
+  const reporter = _loadLiveActivityReporter();
+  if (reporter._loadError) {
+    res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "live-activity-report module unavailable", detail: reporter._loadError }));
+    return;
+  }
+  let result;
+  try {
+    result = reporter.computeLiveActivities({ projectDir });
+  } catch (err) {
+    // Contract regression — computeLiveActivities must never throw
+    res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "computeLiveActivities threw", detail: err && err.message || String(err) }));
+    return;
+  }
+  const body = JSON.stringify(result);
+  cache.at = now;
+  cache.body = body;
+  res.writeHead(200, { "Content-Type": "application/json", "Access-Control-Allow-Origin": "*", "Cache-Control": "no-store", "X-Cache": "miss" });
+  res.end(body);
+}
+
+function handleLiveActivityTail(req, res, projectDir, id) {
+  if (!isValidActivityId(id)) {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "invalid_id" }));
+    return;
+  }
+  const cacheKey = projectDir + "\0" + id;
+  const now = Date.now();
+  const cached = _liveActivityCache.tail.get(cacheKey);
+  if (cached && (now - cached.at) < LIVE_ACTIVITY_CACHE_MS) {
+    res.writeHead(cached.statusCode, cached.headers);
+    res.end(cached.body);
+    return;
+  }
+
+  // Find the activity to determine kind and tail path
+  const reporter = _loadLiveActivityReporter();
+  if (reporter._loadError) {
+    res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "live-activity-report module unavailable" }));
+    return;
+  }
+  let result;
+  try {
+    result = reporter.computeLiveActivities({ projectDir });
+  } catch (err) {
+    res.writeHead(500, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "computeLiveActivities threw", detail: err && err.message || String(err) }));
+    return;
+  }
+
+  const activity = result.activities.find((a) => a.id === id);
+  if (!activity) {
+    const notFound = { statusCode: 404, headers: { "Content-Type": "application/json", "Cache-Control": "no-store" }, body: JSON.stringify({ error: "not_found" }) };
+    _liveActivityCache.tail.set(cacheKey, Object.assign({ at: now }, notFound));
+    res.writeHead(404, notFound.headers);
+    res.end(notFound.body);
+    return;
+  }
+
+  // Read tail content by kind
+  let tailContent = "";
+  const kind = activity.kind;
+  if (kind === "bash" || kind === "spawn") {
+    // Last ~64 KB of process stdout — use _readFileTail pattern
+    // For bash: the log file path is not directly known without process inspection.
+    // Return a JSON snapshot of the activity as a fallback.
+    tailContent = JSON.stringify(activity, null, 2);
+  } else if (kind === "monitor") {
+    tailContent = JSON.stringify(activity, null, 2);
+  } else if (kind === "tool") {
+    tailContent = JSON.stringify(activity, null, 2);
+  } else {
+    tailContent = JSON.stringify(activity, null, 2);
+  }
+
+  const hit = { statusCode: 200, headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", "Access-Control-Allow-Origin": "*" }, body: tailContent };
+  _liveActivityCache.tail.set(cacheKey, Object.assign({ at: now }, hit));
+  res.writeHead(200, hit.headers);
+  res.end(hit.body);
+}
+
+function handleLiveActivityStream(req, res, projectDir, id) {
+  if (!isValidActivityId(id)) {
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "invalid_id" }));
+    return;
+  }
+  res.writeHead(200, Object.assign({}, SSE_HEADERS, { "Access-Control-Allow-Origin": "*", "Cache-Control": "no-store" }));
+
+  // Send an initial data frame
+  res.write("data: " + JSON.stringify({ id, status: "stream_opened" }) + "\n\n");
+
+  // Heartbeat every 15s
+  const heartbeat = setInterval(() => {
+    if (!res.writableEnded) {
+      res.write(": heartbeat\n\n");
+    }
+  }, KEEPALIVE_MS);
+
+  // Poll for activity presence; close stream when activity disappears
+  const reporter = _loadLiveActivityReporter();
+  const poll = setInterval(() => {
+    if (res.writableEnded) {
+      clearInterval(poll);
+      clearInterval(heartbeat);
+      return;
+    }
+    if (reporter._loadError) {
+      clearInterval(poll);
+      clearInterval(heartbeat);
+      res.write("data: " + JSON.stringify({ id, status: "reporter_unavailable" }) + "\n\n");
+      res.end();
+      return;
+    }
+    let result;
+    try {
+      result = reporter.computeLiveActivities({ projectDir });
+    } catch (_) {
+      return; // silent — will retry next tick
+    }
+    const still = result.activities.find((a) => a.id === id);
+    if (!still) {
+      clearInterval(poll);
+      clearInterval(heartbeat);
+      if (!res.writableEnded) {
+        res.write("data: " + JSON.stringify({ id, status: "activity_ended" }) + "\n\n");
+        res.end();
+      }
+      return;
+    }
+    // Emit a status frame
+    res.write("data: " + JSON.stringify({ id, durationMs: still.durationMs, alive: still.alive }) + "\n\n");
+  }, 1000);
+
+  req.on("close", () => {
+    clearInterval(poll);
+    clearInterval(heartbeat);
+  });
+}
+
 // POST /api/unattended-stop — proxies to the existing stop-sentinel flow so
 // the transcript panel's "Stop Supervisor" button reuses the canonical
 // kill path. Writes `.gsd-t/.unattended/stop` sentinel; supervisor polls
@@ -887,6 +1065,12 @@ function startServer(port, eventsDir, htmlPath, projectDir, transcriptHtmlPath,
     if (url === "/api/parallelism/report") return handleParallelismReport(req, res, projDir);
     // M44 D9 — stop-supervisor proxy (POST only; reuses existing sentinel flow)
     if (url === "/api/unattended-stop") return handleUnattendedStop(req, res, projDir);
+    // M54 D1 T3 — live-activity endpoints (additive, read-only)
+    if (url === "/api/live-activity") return handleLiveActivity(req, res, projDir);
+    const laTailMatch = url.match(/^\/api\/live-activity\/([^/]+)\/tail$/);
+    if (laTailMatch) return handleLiveActivityTail(req, res, projDir, decodeURIComponent(laTailMatch[1]));
+    const laStreamMatch = url.match(/^\/api\/live-activity\/([^/]+)\/stream$/);
+    if (laStreamMatch) return handleLiveActivityStream(req, res, projDir, decodeURIComponent(laStreamMatch[1]));
     // POST /transcript/:spawnId/kill — SIGTERM the recorded workerPid
     const killMatch = url.match(/^\/transcript\/([^/]+)\/kill$/);
     if (killMatch && req.method === "POST") return handleTranscriptKill(req, res, decodeURIComponent(killMatch[1]), projDir);
@@ -959,6 +1143,12 @@ module.exports = {
   handleParallelism,
   handleParallelismReport,
   handleUnattendedStop,
+  // M54 D1 T3 — live-activity observability
+  handleLiveActivity,
+  handleLiveActivityTail,
+  handleLiveActivityStream,
+  isValidActivityId,
+  _liveActivityCache,
   // M49 — idle-TTL exports for tests
   _activityTracker,
   _wrapSseHandler,

package/scripts/gsd-t-transcript.html

@@ -209,6 +209,32 @@
     .frame.tool-use > .ts, .frame.thinking > .ts { padding: 8px 0 0 12px; }
     .frame.tool-result > .ts { padding-top: 8px; }
     .frame.compact-marker > .ts { padding: 0; min-width: 64px; }
+
+    /* M54 D2 T1 — LIVE ACTIVITY rail section.
+       Additive only. No existing CSS renamed or removed. */
+    #rail-live-activity { padding: 0 0 8px 0; border-bottom: 1px solid var(--border); margin-bottom: 4px; }
+    #rail-live-activity .la-heading { display: flex; align-items: center; justify-content: space-between; padding: 8px 12px 4px 12px; font-size: 11px; text-transform: uppercase; color: var(--fg-xdim); letter-spacing: 0.08em; }
+    .la-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; }
+    .la-entry { display: grid; grid-template-columns: 10px 18px 1fr auto; align-items: center; gap: 4px; padding: 5px 12px; cursor: pointer; border-radius: 4px; font-size: 12px; }
+    .la-entry:hover { background: var(--bg-soft); }
+    .la-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }
+    .la-dot-running { background: #2dd4bf; }
+    .la-dot-stale { background: var(--fg-xdim, #6b7280); }
+    .la-icon { font-family: var(--mono); font-size: 13px; text-align: center; color: var(--fg-dim); }
+    .la-label { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 40ch; color: var(--fg); font-family: var(--mono); font-size: 11px; }
+    .la-duration { font-family: var(--mono); font-size: 11px; color: var(--fg-xdim); text-align: right; white-space: nowrap; }
+    .la-empty { padding: 4px 12px 0 12px; color: var(--fg-xdim); font-size: 11px; font-style: italic; }
+    /* Kind icon slots — glyphs set in JS via KIND_ICONS map */
+    .la-icon-bash   { color: var(--accent-warm, #f0a500); }
+    .la-icon-monitor { color: var(--accent, #58a6ff); }
+    .la-icon-tool   { color: var(--fg-dim, #8b949e); }
+    .la-icon-spawn  { color: var(--green, #3fb950); }
+    @keyframes accent-pulse {
+      0%   { box-shadow: inset 2px 0 0 0 #2dd4bf; opacity: 1; }
+      50%  { box-shadow: inset 2px 0 0 0 #2dd4bf; opacity: 0.6; }
+      100% { box-shadow: inset 2px 0 0 0 #2dd4bf; opacity: 1; }
+    }
+    .la-pulsing { animation: accent-pulse 1.5s ease-in-out infinite; }
   </style>
 </head>
 <body data-spawn-id="__SPAWN_ID__">
@@ -226,6 +252,15 @@
       <div class="rail-header"><span>★ Main Session</span></div>
       <div class="rail-body" id="rail-main-body"><div class="empty">No in-session conversation captured yet.</div></div>
     </section>
+    <!-- M54 D2 T1 — LIVE ACTIVITY section (additive, between Main Session and Live Spawns).
+         Populated by 5s polling JS (D2 T2). CSS @keyframes accent-pulse in <style> block above. -->
+    <section id="rail-live-activity">
+      <div class="la-heading"><span>⚡ Live Activity</span></div>
+      <ul id="la-list" class="la-list">
+        <!-- Entries injected by polling JS (T2). Empty section header visible when list is empty. -->
+      </ul>
+      <div class="la-empty" id="la-empty-msg">No active operations detected.</div>
+    </section>
     <section class="rail-live" data-rail-section="live">
       <div class="rail-header"><span>Live Spawns</span></div>
       <div class="rail-body">
@@ -1615,6 +1650,171 @@
         poll();
         setInterval(poll, 5000);
       })();
+
+      // ── M54 D2 T2 — Live Activity Rail ────────────────────────────────────
+      // Polls /api/live-activity every 5s (same cadence as /api/parallelism).
+      // Appends entries to #la-list, applies .la-pulsing on new entries,
+      // removes entries when they disappear from the API response.
+      // Click handler: stopPulse + loadTailUrl (NO auto-switch on arrival).
+      // Additive only — no existing function renamed or removed.
+      (function wireLiveActivity() {
+        const laList = document.getElementById('la-list');
+        const laEmpty = document.getElementById('la-empty-msg');
+        if (!laList) return; // section not present in this page variant
+
+        // Map of id → { element, startedAt, stopPulseTimer }
+        const _current = new Map();
+
+        // Format duration in seconds as human-readable string
+        function fmtDuration(ms) {
+          const s = Math.floor(ms / 1000);
+          if (s < 60) return s + 's';
+          const m = Math.floor(s / 60), rs = s % 60;
+          if (m < 60) return m + 'm ' + rs + 's';
+          const h = Math.floor(m / 60), rm = m % 60;
+          return h + 'h ' + rm + 'm';
+        }
+
+        // Kind icon mapping
+        const KIND_ICONS = { bash: '$', monitor: '👁', tool: '🔧', spawn: '↳' };
+
+        // Load the tailUrl content into the bottom pane (mirrors existing bottom-pane loaders)
+        function loadTailUrl(tailUrl) {
+          const streamEl = document.getElementById('stream');
+          if (!streamEl) return;
+          fetch(tailUrl)
+            .then(function(r) { return r.text(); })
+            .then(function(text) {
+              streamEl.innerHTML = '<pre style="margin:0;padding:12px;font-family:var(--mono);font-size:12px;white-space:pre-wrap;word-break:break-word;">' + _esc(text) + '</pre>';
+            })
+            .catch(function(err) {
+              console.log('[la] tail load error:', err && err.message);
+            });
+        }
+
+        function _esc(s) {
+          return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+        }
+
+        // Remove .la-pulsing from entry element
+        function stopPulse(id) {
+          const item = _current.get(id);
+          if (!item || !item.element) return;
+          item.element.classList.remove('la-pulsing');
+          if (item.stopPulseTimer) { clearTimeout(item.stopPulseTimer); item.stopPulseTimer = null; }
+        }
+
+        // Append a new .la-entry to #la-list
+        function appendActivity(entry) {
+          const li = document.createElement('li');
+          li.className = 'la-entry la-pulsing';
+          li.setAttribute('data-id', entry.id);
+          li.setAttribute('data-kind', entry.kind);
+          li.setAttribute('data-tail-url', entry.tailUrl || '');
+
+          const dot = document.createElement('span');
+          dot.className = 'la-dot la-dot-running';
+          li.appendChild(dot);
+
+          const icon = document.createElement('span');
+          icon.className = 'la-icon la-icon-' + entry.kind;
+          icon.textContent = KIND_ICONS[entry.kind] || '?';
+          li.appendChild(icon);
+
+          const label = document.createElement('span');
+          label.className = 'la-label';
+          const labelText = String(entry.label || '').slice(0, 40);
+          label.textContent = labelText;
+          label.title = entry.label || '';
+          li.appendChild(label);
+
+          const dur = document.createElement('span');
+          dur.className = 'la-duration';
+          dur.textContent = fmtDuration(entry.durationMs || 0);
+          li.appendChild(dur);
+
+          li.addEventListener('click', function() {
+            stopPulse(entry.id);
+            if (entry.tailUrl) loadTailUrl(entry.tailUrl);
+          });
+
+          laList.appendChild(li);
+
+          // Schedule pulse stop after 30s (condition c)
+          const timer = setTimeout(function() { stopPulse(entry.id); }, 30000);
+          _current.set(entry.id, { element: li, startedAt: entry.startedAt, stopPulseTimer: timer });
+
+          if (laEmpty) laEmpty.style.display = 'none';
+        }
+
+        // Remove a .la-entry from #la-list
+        function removeActivity(id) {
+          const item = _current.get(id);
+          if (!item) return;
+          if (item.stopPulseTimer) clearTimeout(item.stopPulseTimer);
+          if (item.element && item.element.parentNode) item.element.parentNode.removeChild(item.element);
+          _current.delete(id);
+          if (laEmpty && _current.size === 0) laEmpty.style.display = '';
+        }
+
+        // Update the duration counter for an existing entry
+        function updateDuration(id, startedAt) {
+          const item = _current.get(id);
+          if (!item || !item.element) return;
+          const dur = item.element.querySelector('.la-duration');
+          if (!dur) return;
+          const start = startedAt ? new Date(startedAt).getTime() : 0;
+          const elapsed = start ? Math.max(0, Date.now() - start) : 0;
+          dur.textContent = fmtDuration(elapsed);
+        }
+
+        // Fetch /api/live-activity, return envelope (or {activities:[]} on error)
+        async function fetchLiveActivity() {
+          try {
+            const r = await fetch('/api/live-activity');
+            if (!r.ok) {
+              console.log('[la] /api/live-activity returned', r.status);
+              return { activities: [] };
+            }
+            return await r.json();
+          } catch (err) {
+            console.log('[la] fetch error:', err && err.message);
+            return { activities: [] };
+          }
+        }
+
+        // Reconcile current DOM state with new API response
+        function reconcile(activities) {
+          // Build a Map of new activities by id
+          const newById = new Map();
+          for (const entry of (activities || [])) {
+            newById.set(entry.id, entry);
+          }
+
+          // Remove entries no longer present
+          for (const id of Array.from(_current.keys())) {
+            if (!newById.has(id)) removeActivity(id);
+          }
+
+          // Add new entries; update durations for existing ones
+          for (const [id, entry] of newById) {
+            if (_current.has(id)) {
+              updateDuration(id, entry.startedAt);
+            } else {
+              appendActivity(entry);
+            }
+          }
+        }
+
+        // Initial poll + 5s interval (same cadence as /api/parallelism)
+        async function poll() {
+          const data = await fetchLiveActivity();
+          reconcile(data.activities);
+        }
+
+        poll();
+        setInterval(poll, 5000);
+      })();
     })();
   </script>
 </body>