@tekyzinc/gsd-t 3.23.10 → 3.24.10

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

@@ -1008,6 +1008,15 @@ defined in `.gsd-t/contracts/parallelism-report-contract.md` v1.0.0.
 Per-spawn timeline, Per-gate decisions, Per-worker Gantt, Token cost, and
 Notes sections.
 
+**Install location**: the dashboard server (installed at
+`~/.claude/scripts/gsd-t-dashboard-server.js`) resolves
+`require(path.join(__dirname, "..", "bin", "parallelism-report.cjs"))` at
+request time, so the module must live at **`~/.claude/bin/parallelism-report.cjs`**.
+The installer handles this via `installGlobalBinTools()` (driven by
+`GLOBAL_BIN_TOOLS` in `bin/gsd-t.js`), and `gsd-t doctor` flags any missing
+entry. This is distinct from `PROJECT_BIN_TOOLS`, which copies into each
+registered project's local `bin/`.
+
 **Data flow**:
 
 ```
@@ -1117,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
+