@tekyzinc/gsd-t 3.23.10 → 3.23.11

package/CHANGELOG.md

@@ -2,7 +2,47 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
-## [Unreleased]
+## [3.23.11] - 2026-05-07
+
+### Fixed — `/api/parallelism` 500 — install `parallelism-report.cjs` to `~/.claude/bin/`
+
+- **Root cause**: `scripts/gsd-t-dashboard-server.js::_loadParallelismReporter` resolves `require(path.join(__dirname, "..", "bin", "parallelism-report.cjs"))`. With `__dirname = ~/.claude/scripts/`, it looks for `~/.claude/bin/parallelism-report.cjs` — but no installer code path ever populated `~/.claude/bin/`. Every dashboard 500'd on `/api/parallelism` with `Cannot find module …/parallelism-report.cjs`; the right-rail PARALLELISM panel silently dimmed for every project. The break suggests `~/.claude/bin/` propagation has been silently broken since the M44 D9 panel shipped.
+- **Fix** (`bin/gsd-t.js`, ~30 LOC additive): new `GLOBAL_BIN_DIR = ~/.claude/bin` constant; new `GLOBAL_BIN_TOOLS = ["parallelism-report.cjs"]` array; new `installGlobalBinTools()` mirroring `installUtilityScripts` shape (symlink-safe `copyFile`, eol-normalised idempotent compare, `+x` chmod). Wired into `doInstall()` between Utility Scripts and Context Meter so it runs on both `install` and `update`. `gsd-t doctor` gains `checkDoctorGlobalBin()` flagging missing tools with a clear "re-run install" hint.
+- **Hot-patch**: `mkdir -p ~/.claude/bin && cp bin/parallelism-report.cjs ~/.claude/bin/` applied immediately so the live dashboard recovers without waiting for npm publish. Verified `curl http://localhost:7488/api/parallelism` returns 200 with the schema-versioned envelope (was 500 module-unavailable).
+- **Doctrinal shift**: per the user's "test the real setup" directive, the regression spec lives under a new `e2e/live-journeys/` tree that probes the **running** dashboard instead of an in-process `startServer(0, ...)` fixture. Two specs added:
+  - `e2e/live-journeys/parallelism-endpoint.spec.ts` (4 tests) — schema envelope, no-500 sentinel, right-rail DOM populates from `/transcripts`, file-system regression sentinel for `~/.claude/bin/parallelism-report.cjs` existence.
+  - `e2e/live-journeys/dashboard-endpoint-coverage.spec.ts` (12 tests) — covers every dashboard route (`/`, `/transcripts`, `/ping`, `/metrics`, `/api/main-session`, `/api/spawn-plans`, `/api/parallelism`, `/api/parallelism/report`, `/events`, `/api/spawn-plans/stream`, 404 catch-all) plus a regression sentinel for the "parallelism-report module unavailable" string.
+  - Both specs `test.skip()` cleanly when no dashboard is reachable (`GSD_T_LIVE_DASHBOARD_URL` env override; default `http://localhost:7488`), keeping non-local CI green.
+- **Adversarial Red Team** (focused, in-session): reviewed `update-all` self-heal gap (mitigated by `gsd-t doctor`), symlink safety (covered via `copyFile`), cross-platform path resolution (covered via `os.homedir()`), project-bin sweep collision (`parallelism-report.cjs` not in `DEPRECATED_BIN_STRAYS` so existing project copies are untouched). VERDICT: GRUDGING PASS — 0 blocking issues.
+- **Verification**: unit suite **2233/2233 pass** (zero regressions). Playwright `e2e/journeys/` + `e2e/viewer/` **43/43 pass + 1 placeholder skip**. New live spec **4/4 pass** against the running :7488 dashboard.
+- **Architecture doc**: `docs/architecture.md` Parallelism Observability section now records the install location and the distinction between `GLOBAL_BIN_TOOLS` (`~/.claude/bin/`) and `PROJECT_BIN_TOOLS` (per-project `bin/`).
+
+### Fixed — M53b conversation-capture project-routing: parallel sessions cross-talk
+
+- **Root cause**: `scripts/hooks/gsd-t-conversation-capture.js::_resolveProjectDir(payload)` fell through to `_walkUpForProject(process.cwd())` when `GSD_T_PROJECT_DIR` was unset and `payload.cwd` was absent. `process.cwd()` for a Claude Code Stop/UserPromptSubmit hook is the directory the user launched `claude` from. When two parallel Claude Code sessions ran in different projects (`/Users/david/projects/GSD-T` and `/Users/david/projects/Move-Zoom-Recordings-to-GDrive`), the SAME node-runtime hook process resolved to whichever project the hook inherited via cwd — frames from one session landed in the other project's `.gsd-t/transcripts/` dir. Confirmed concrete misroute: GSD-T orchestrator's NDJSON written into `Move-Zoom-Recordings-to-GDrive/.gsd-t/transcripts/in-session-800d4b3b-….ndjson`.
+- **Fix**: `_resolveProjectDir` now decodes `payload.transcript_path`'s `~/.claude/projects/{slug}/{sid}.jsonl` slug back to the real project root. New helpers:
+  - `_slugFromTranscriptPath(p)` — extracts the slug (first path segment after `~/.claude/projects/`); rejects paths outside that root.
+  - `_slugToProjectDir(slug)` — DFS-walks the filesystem, greedily consuming `-`-separated tokens as directory names; first leaf where `.gsd-t/` exists wins. Disambiguates literal-hyphen project names like `Move-Zoom-Recordings-to-GDrive` by consulting the disk. Rejects slugs containing `..`, `/`, `\\`, `\0`, or not starting with `-`.
+  - `_resolveProjectDir` priority is now: env → transcript_path slug → `payload.cwd` → cwd walk-up. Walk-up emits a one-line stderr warning ("project-dir resolved via cwd walk-up — unreliable for parallel sessions") so misroutes stay diagnosable.
+- **Tests**: `test/m53b-conversation-routing.test.js` (new, 16 tests) covers happy-path slug-decode, parallel-session no-cross-talk, literal-hyphen disambiguation, non-GSD-T target fallthrough, path-traversal slug rejection, env-priority preservation, plus 8 unit-level helper tests. `test/m53b-conversation-routing-redteam.test.js` (new, 7 tests) — three adversarial `_resolveProjectDir` variants (walk-up only / naive slug-decode without `.gsd-t/` check / literal-slug-as-path) each violate at least one of four named invariants (I1 own-project / I2 .gsd-t/-existence / I3 slug-decoded / I4 not-neutral-cwd), with two positive controls proving the real fix passes all four on both clean-name and literal-hyphen projects.
+- **Journey spec**: `e2e/journeys/conversation-routing.spec.ts` (new, 3 tests) — fires the real hook process twice with two different `transcript_path` values pointing at slugs encoding two different projects under a fake `$HOME`; asserts each NDJSON lands in the matching project, neither cross-routes, neutral-cwd has no `.gsd-t/transcripts/` tree (proves walk-up did not fire), and slug-as-literal-path attack is rejected. Manifest entry added to `.gsd-t/journey-manifest.json`.
+- **Verification**: full unit suite **2226/2226 pass** (was 2210; +16 routing + 7 redteam = +23, zero regressions; the 2 pre-existing flakes from gsd-t-debug-env-induced `event-stream.test.js` / `watch-progress-writer.test.js` remain unchanged — pass cleanly when those env vars are unset). Playwright `e2e/journeys/` **16/16 pass** (was 13; +3 conversation-routing).
+- **Note**: existing misrouted NDJSONs in `Move-Zoom-Recordings-to-GDrive/.gsd-t/transcripts/` remain (acceptable historical records). Going-forward NDJSONs will route correctly. Hot-patch applied to `~/.claude/scripts/hooks/gsd-t-conversation-capture.js`; full propagation on next `npm publish` + `/gsd-t-version-update-all`.
+- **Contract**: `conversation-capture-contract.md` v1.1.0 → v1.2.0 (project-dir resolution algorithm documented with priority order + slug-decode protocol + defenses-against-pitfalls table; schema unchanged).
+
+### Fixed — M45 D2 conversation-capture regression: bodyless `assistant_turn` frames
+
+- **Root cause**: `scripts/hooks/gsd-t-conversation-capture.js::_extractAssistantContent` tried payload shapes (`assistant_message`, `message.content`, `content`) that Claude Code's Stop hook never sends. Stop hook payload is `{session_id, transcript_path, hook_event_name, stop_hook_active}` — message body lives in the transcript JSONL at `transcript_path`. Function fell through to `null`; every `assistant_turn` frame written since v3.18.14 (M45 D2 ship 2026-04-23) was bodyless. Two weeks of broken capture; viewer correctly rendered empty bubbles.
+- **Fix**: hook now reads the assistant body from `transcript_path`. New helpers:
+  - `_safeTranscriptPath(p)` — locks the path to `${HOME}/.claude/projects/`. Path-traversal attempts (`/etc/passwd`, relative paths) fail open (`return null`).
+  - `_readFileTail(filePath, 64*1024)` — opens fd, reads last 64 KB, drops leading mid-line partial. Multi-MB transcripts never get fully loaded.
+  - `_readAssistantFromTranscript(transcriptPath)` — scans tail bottom-up, parses each line as JSON (skips corrupt), picks the latest `type === 'assistant' && isSidechain !== true` row, concatenates all `text`-type content blocks (ignores `tool_use` / `tool_result` / `thinking`), skips tool_use-only rows.
+  - `_extractAssistantContent(payload)` — transcript-first; original 3 fallback shapes preserved for legacy/test payloads.
+- **Tests**: `test/m45-d2-conversation-capture.test.js` +11 cases (transcript happy-path, multi-block concatenation, latest-row selection, sidechain skipping, tool_use-only skipping, /etc/passwd rejection, relative-path rejection, missing transcript_path → fallback, unreadable file → stub, >1 MB tail-only read, corrupt-JSON line skipping). `test/m53-conversation-content-redteam.test.js` (new, 4 tests) — three broken extractor variants (regress-to-old-code, picks-user-message, first-text-block-only) each violate one of three named invariants (I1 non-empty / I2 marker-match / I3 tail-marker-present), with a positive control proving the harness isn't trivially broken.
+- **Journey spec**: `e2e/journeys/conversation-content.spec.ts` — writes a 7-frame in-session NDJSON fixture with 3 assistant_turn frames (one multi-paragraph with HEAD + TAIL markers); navigates to `/transcripts`; asserts `#main-stream .frame.assistant-turn` count = 3, every `.body` non-empty, each carries its expected marker, multi-paragraph TAIL marker present, USER-PROMPT marker absent from any assistant bubble, no `.frame.raw` JSON-dump fallback.
+- **Verification**: full unit suite **2210/2210 pass** (was 2195; +11 M45 D2 + 4 M53 redteam = +15, zero regressions). Playwright `e2e/journeys/` + `e2e/viewer/` **36/36 pass** (was 35; +1 conversation-content).
+- **Note**: existing 6 bodyless NDJSONs (`Move-Zoom-Recordings-to-GDrive/.gsd-t/transcripts/`) remain — historical records, acceptable. Going-forward NDJSONs will be populated. The installed hook at `~/.claude/scripts/hooks/gsd-t-conversation-capture.js` syncs on next `npm publish` + `/gsd-t-version-update-all`.
+- **Contract**: `conversation-capture-contract.md` v1.0.0 → v1.1.0 (assistant-body extraction protocol documented; schema unchanged — same `assistant_turn` frame, just populated where v1.0.0 was bodyless).
 
 ## [3.23.10] - 2026-05-06
 

package/bin/gsd-t.js

@@ -45,6 +45,7 @@ const { mapHeadlessExitCode } = require(path.join(__dirname, "headless-exit-code
 const CLAUDE_DIR = path.join(os.homedir(), ".claude");
 const COMMANDS_DIR = path.join(CLAUDE_DIR, "commands");
 const SCRIPTS_DIR = path.join(CLAUDE_DIR, "scripts");
+const GLOBAL_BIN_DIR = path.join(CLAUDE_DIR, "bin");
 const CLAUDE_TEMPLATES_DIR = path.join(CLAUDE_DIR, "templates");
 const GLOBAL_CLAUDE_MD = path.join(CLAUDE_DIR, "CLAUDE.md");
 const SETTINGS_JSON = path.join(CLAUDE_DIR, "settings.json");
@@ -1169,6 +1170,33 @@ function installUtilityScripts() {
   }
 }
 
+// ─── Global Bin Tools (~/.claude/bin/) ───────────────────────────────────────
+// Modules resolved by globally-installed scripts via
+// `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"];
+
+function installGlobalBinTools() {
+  ensureDir(GLOBAL_BIN_DIR);
+  for (const tool of GLOBAL_BIN_TOOLS) {
+    const src = path.join(PKG_ROOT, "bin", tool);
+    const dest = path.join(GLOBAL_BIN_DIR, tool);
+    if (!fs.existsSync(src)) {
+      warn(`Global bin tool source missing: ${tool} — skipping`);
+      continue;
+    }
+    const srcContent = fs.readFileSync(src, "utf8");
+    const destContent = fs.existsSync(dest) ? fs.readFileSync(dest, "utf8") : "";
+    if (normalizeEol(srcContent) !== normalizeEol(destContent)) {
+      copyFile(src, dest, `bin/${tool}`);
+      try { fs.chmodSync(dest, 0o755); } catch {}
+    } else {
+      info(`bin/${tool} unchanged`);
+    }
+  }
+}
+
 // ─── CGC (CodeGraphContext) ──────────────────────────────────────────────────
 
 function installCgc() {
@@ -1508,6 +1536,9 @@ async function doInstall(opts = {}) {
   heading("Utility Scripts");
   installUtilityScripts();
 
+  heading("Global Bin Tools (~/.claude/bin/)");
+  installGlobalBinTools();
+
   heading("Context Meter (PostToolUse)");
   const cmHook = configureContextMeterHooks(SETTINGS_JSON);
   if (cmHook.installed) {
@@ -2725,6 +2756,20 @@ function checkDoctorInstallation() {
   issues += checkDoctorClaudeMd();
   issues += checkDoctorSettings();
   issues += checkDoctorEncoding(installed);
+  issues += checkDoctorGlobalBin();
+  return issues;
+}
+
+function checkDoctorGlobalBin() {
+  let issues = 0;
+  const missing = GLOBAL_BIN_TOOLS.filter((tool) => !fs.existsSync(path.join(GLOBAL_BIN_DIR, tool)));
+  if (missing.length === 0) {
+    success(`All ${GLOBAL_BIN_TOOLS.length} global bin tool${GLOBAL_BIN_TOOLS.length === 1 ? "" : "s"} installed (~/.claude/bin/)`);
+  } else {
+    warn(`Missing global bin tool${missing.length === 1 ? "" : "s"} in ~/.claude/bin/: ${missing.join(", ")}`);
+    info("Fix: re-run `npx @tekyzinc/gsd-t install` (or `update`)");
+    issues++;
+  }
   return issues;
 }
 

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**:
 
 ```

package/package.json

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

@@ -16,16 +16,20 @@
  * - Never throws to the caller — catches all errors, logs to stderr, exits 0.
  * - `content` is capped at 16 KB per frame; over-cap writes `truncated: true`.
  * - Append-only; never overwrites an existing in-session NDJSON file.
- * - Project-dir discovery: prefers `GSD_T_PROJECT_DIR`, then `payload.cwd`,
+ * - Project-dir discovery: prefers `GSD_T_PROJECT_DIR`, then decodes
+ *   `payload.transcript_path`'s `~/.claude/projects/{slug}` to a real project
+ *   root (session-specific signal — required when multiple parallel Claude
+ *   Code sessions share one node-runtime hook process), then `payload.cwd`,
  *   then walks up from `process.cwd()` looking for `.gsd-t/progress.md`.
  *   Silent no-op if no project dir found.
  *
- * Contract: .gsd-t/contracts/conversation-capture-contract.md v1.0.0
+ * Contract: .gsd-t/contracts/conversation-capture-contract.md v1.2.0
  */
 
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const os = require('os');
 
 const DEFAULT_SCRIPT_GUARD_MS = 5000;
 const CONTENT_CAP_BYTES = 16 * 1024; // 16 KB
@@ -69,15 +73,102 @@ function _walkUpForProject(startDir) {
   return null;
 }
 
+// Decode a Claude Code project slug (the directory name under
+// `~/.claude/projects/`) back to an absolute project root that contains a
+// `.gsd-t/` directory. The slug encoding is lossy — `/` and literal `-` both
+// map to `-` — so we DFS-walk the filesystem, greedily consuming token runs as
+// directory names. First match whose `.gsd-t/` exists wins. Returns null if
+// nothing matches or the slug is malformed.
+//
+// Why this exists: Claude Code Stop hook payloads carry `transcript_path` =
+// `~/.claude/projects/{slug}/{sessionId}.jsonl`. The hook runs as one shared
+// node-runtime process across parallel Claude Code sessions, so `process.cwd()`
+// can resolve to the wrong project. The slug is the only *session-specific*
+// signal we have for project routing.
+function _slugToProjectDir(slug) {
+  if (typeof slug !== 'string' || slug.length === 0) return null;
+  if (slug[0] !== '-') return null; // must encode leading '/'
+  // Reject anything that could traversal-escape after decode.
+  if (slug.includes('/') || slug.includes('\\') || slug.includes('\0')) return null;
+  if (slug.includes('..')) return null;
+  const tokens = slug.slice(1).split('-'); // strip leading '-' (the leading '/')
+  if (tokens.length === 0 || tokens.some((t) => t.length === 0)) return null;
+  // DFS over how many '-'-separated tokens form each directory segment.
+  // Greedy preference: try fewest tokens first (most '/' separators) so deeper
+  // paths win when both interpretations exist.
+  function walk(prefix, idx) {
+    if (idx >= tokens.length) {
+      try {
+        if (fs.existsSync(path.join(prefix, '.gsd-t'))) return prefix;
+      } catch (_) { /* swallow */ }
+      return null;
+    }
+    for (let k = 1; k <= tokens.length - idx; k++) {
+      const seg = tokens.slice(idx, idx + k).join('-');
+      const next = path.join(prefix, seg);
+      // Re-validate after path.join — defense against weird inputs.
+      if (next.includes('..')) continue;
+      let exists = false;
+      try { exists = fs.existsSync(next); } catch (_) { exists = false; }
+      if (!exists) continue;
+      const found = walk(next, idx + k);
+      if (found) return found;
+    }
+    return null;
+  }
+  return walk('/', 0);
+}
+
+// Extract the slug ({dir-name} under `~/.claude/projects/`) from a
+// transcript_path. Returns null on malformed input.
+function _slugFromTranscriptPath(p) {
+  if (typeof p !== 'string' || !path.isAbsolute(p)) return null;
+  const home = process.env.HOME || os.homedir();
+  if (!home) return null;
+  const root = path.resolve(home, '.claude', 'projects') + path.sep;
+  const resolved = path.resolve(p);
+  if (!resolved.startsWith(root)) return null;
+  const rest = resolved.slice(root.length);
+  // First path segment after the projects/ root is the slug.
+  const sep = rest.indexOf(path.sep);
+  const slug = sep === -1 ? rest : rest.slice(0, sep);
+  if (!slug) return null;
+  return slug;
+}
+
 function _resolveProjectDir(payload) {
+  // 1. Explicit env override (preserved for tests + operator overrides).
   const env = process.env.GSD_T_PROJECT_DIR;
   if (env && fs.existsSync(path.join(env, '.gsd-t'))) return env;
+  // 2. Session-specific signal: decode the transcript_path slug. This is the
+  //    ONLY source that's per-session under parallel Claude Code instances —
+  //    cwd / walk-up resolve to whichever project the hook process happens to
+  //    inherit, which misroutes frames across projects.
+  if (payload && typeof payload.transcript_path === 'string') {
+    const slug = _slugFromTranscriptPath(payload.transcript_path);
+    if (slug) {
+      const fromSlug = _slugToProjectDir(slug);
+      if (fromSlug) return fromSlug;
+    }
+  }
+  // 3. payload.cwd (Claude Code may carry it on some events).
   if (payload && typeof payload.cwd === 'string' && path.isAbsolute(payload.cwd)
       && fs.existsSync(path.join(payload.cwd, '.gsd-t'))) {
     return payload.cwd;
   }
+  // 4. Last resort: walk up from process.cwd(). Known-unreliable for parallel
+  //    sessions sharing a node-runtime hook process — emit a one-line warning
+  //    so misroutes are diagnosable from stderr.
   const walked = _walkUpForProject(process.cwd());
-  if (walked) return walked;
+  if (walked) {
+    try {
+      process.stderr.write(
+        'gsd-t-conversation-capture: project-dir resolved via cwd walk-up (' +
+        walked + ') — unreliable for parallel sessions\n'
+      );
+    } catch (_) { /* noop */ }
+    return walked;
+  }
   return null;
 }
 
@@ -134,9 +225,93 @@ function _extractUserContent(payload) {
   return null;
 }
 
+// Tail-read the last `bytes` of a file as UTF-8. Returns '' on any error.
+// Used so multi-MB transcripts don't get fully loaded into RAM.
+function _readFileTail(filePath, bytes) {
+  let fd = -1;
+  try {
+    const st = fs.statSync(filePath);
+    if (!st.isFile()) return '';
+    const size = st.size;
+    if (size === 0) return '';
+    const want = Math.min(bytes, size);
+    const start = size - want;
+    fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(want);
+    fs.readSync(fd, buf, 0, want, start);
+    let str = buf.toString('utf8');
+    // If we sliced mid-line, drop the (possibly malformed) leading partial.
+    if (start > 0) {
+      const nl = str.indexOf('\n');
+      if (nl >= 0) str = str.slice(nl + 1);
+    }
+    return str;
+  } catch (_) {
+    return '';
+  } finally {
+    if (fd >= 0) { try { fs.closeSync(fd); } catch (_) { /* noop */ } }
+  }
+}
+
+// Validate `transcript_path` from a hook payload before reading. Stop hooks
+// from Claude Code put the file under `~/.claude/projects/`; we lock to that
+// to defeat path-traversal attempts (BUG-1 sanitizer pattern). Fail open
+// (return null) on anything suspicious.
+function _safeTranscriptPath(p) {
+  if (typeof p !== 'string' || p.length === 0) return null;
+  if (!path.isAbsolute(p)) return null;
+  const home = process.env.HOME || os.homedir();
+  if (!home) return null;
+  const allowedRoot = path.resolve(home, '.claude', 'projects') + path.sep;
+  const resolved = path.resolve(p);
+  if (!resolved.startsWith(allowedRoot)) return null;
+  return resolved;
+}
+
+// Pull the assistant body out of a Claude Code transcript JSONL by scanning
+// from the tail. Each line is one event; the latest `type === 'assistant'`
+// row carries the message. Concatenate all `text`-type content blocks; ignore
+// tool_use / tool_result / thinking blocks. Returns null if no assistant row
+// is found or every candidate is body-less (tool_use only).
+function _readAssistantFromTranscript(transcriptPath) {
+  const safe = _safeTranscriptPath(transcriptPath);
+  if (!safe) return null;
+  const tail = _readFileTail(safe, 64 * 1024);
+  if (!tail) return null;
+  const lines = tail.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!line) continue;
+    let row;
+    try { row = JSON.parse(line); } catch (_) { continue; }
+    if (!row || row.type !== 'assistant') continue;
+    // Skip subagent turns — orchestrator transcripts record both, but only
+    // the orchestrator's own assistant turn belongs in this in-session file.
+    if (row.isSidechain === true) continue;
+    const msg = row.message;
+    if (!msg) continue;
+    const blocks = msg.content;
+    if (typeof blocks === 'string') return blocks;
+    if (!Array.isArray(blocks)) continue;
+    const texts = [];
+    for (const b of blocks) {
+      if (b && b.type === 'text' && typeof b.text === 'string') texts.push(b.text);
+    }
+    if (texts.length === 0) continue; // tool_use-only turn — keep scanning
+    return texts.join('');
+  }
+  return null;
+}
+
 function _extractAssistantContent(payload) {
-  // Stop hook payloads vary. Try the common shapes; fall back to null so we
-  // still emit a stub frame (ts + session_id only).
+  // PRIMARY: Claude Code Stop hook payload carries `transcript_path` to the
+  // orchestrator's JSONL. Read the most recent assistant row from the tail.
+  if (payload && typeof payload.transcript_path === 'string') {
+    const fromTranscript = _readAssistantFromTranscript(payload.transcript_path);
+    if (fromTranscript != null) return fromTranscript;
+  }
+  // Fallback shapes — kept so older / non-Claude-Code payload shapes still
+  // work (and so unit tests can exercise the hook without a real transcript).
   if (payload && typeof payload.assistant_message === 'string') return payload.assistant_message;
   if (payload && payload.message && typeof payload.message.content === 'string') {
     return payload.message.content;
@@ -253,6 +428,12 @@ module.exports = {
     _buildToolUseFrame,
     _appendFrame,
     _handle,
+    _extractAssistantContent,
+    _readAssistantFromTranscript,
+    _safeTranscriptPath,
+    _readFileTail,
+    _slugFromTranscriptPath,
+    _slugToProjectDir,
     CONTENT_CAP_BYTES,
   },
 };