tracegist-mcp-bridge 0.2.14 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to `tracegist-mcp-bridge`.
+
+## 0.3.0
+
+**Breaking changes:**
+
+- Local Whisper now runs via the bundled
+  [`nodejs-whisper`](https://www.npmjs.com/package/nodejs-whisper) (whisper.cpp).
+  The bridge no longer requires Python 3, `openai-whisper`, or system `ffmpeg`.
+- An install-time C/C++ toolchain is required so `nodejs-whisper` can compile
+  whisper.cpp. macOS Xcode CLI tools and Linux `build-essential` are commonly
+  already installed; Windows users typically need to install Visual Studio
+  Build Tools (the "Desktop development with C++" workload) explicitly.
+- **Legacy session zips with `.webm` voice notes will no longer transcribe
+  out of the box** on the new bridge. nodejs-whisper falls back to ffmpeg for
+  non-wav inputs; if ffmpeg isn't on PATH, transcription fails with a hint
+  pointing at the fix. Re-export the affected sessions with the matching
+  TraceGist extension version (which now records 16 kHz mono wav directly),
+  or install ffmpeg.
+
+**Other changes:**
+
+- The default Whisper model is `base.en`, auto-downloaded on first use
+  (~150 MB). Override via the `TRACEGIST_WHISPER_MODEL` env var (e.g.
+  `tiny.en`, `small.en`, `large-v3`).
+- Removed the legacy `formatExecError` helper (unused after the Python /
+  ffmpeg removal).
+- The local Whisper path now surfaces a re-export hint when given a non-wav
+  voice note, matching the existing OpenRouter error message.
+- Fixed a crash in the live-shadow WebSocket server: when port 19384 (and the
+  retry range) was already in use, `EADDRINUSE` propagated from the http server
+  onto the `WebSocketServer` instance, which had no `error` listener and tore
+  the bridge down before the retry path could run. Now swallowed so the retry
+  fallback (and "all ports in use, live shadowing disabled" log) actually
+  surface.
+- Live-shadow WebSocket now rejects upgrades from `http://` / `https://`
+  origins. Only `chrome-extension://` / `moz-extension://` and origin-less
+  clients (CLI, extensions that don't send the header) are accepted. CORS does
+  not apply to WebSockets, so without this any web page the user visits could
+  connect to `ws://127.0.0.1:19384` and read live session events / screenshots.
+- `watch_live_session` now paginates: `limit` (default 100, max 500), and
+  responses include `nextSeq` + `hasMore`. Long sessions no longer return
+  thousands of events in a single response.
+- `extract_tracegist_package_file` now declares an `outputSchema` and emits
+  `structuredContent` (`{ zipPath, entryName, outputPath, bytesWritten }`).
+- New env var `TRACEGIST_DISABLE_LIVE=1` skips the live-shadow WebSocket
+  server. Useful when running the bridge under MCP Inspector (which spawns
+  many parallel children) or in CI / non-interactive contexts where live
+  shadowing is not needed.
+
+## 0.2.18
+
+- Added `transcribeViaOpenRouter` and a unified `transcribeAudio` path that
+  tries OpenRouter (when `OPENROUTER_API_KEY` is set) before falling back to
+  local Whisper.
+- Added `get_tracegist_issue_draft` MCP tool for building tracker-agnostic
+  issue payloads from a session package.
+- Added structured handoff parsing in `lib.mjs` (`parseTier0Table`,
+  `parseEnvironmentLines`, `parseMarkerBlocks`, `pickPrimaryMarker`,
+  `severityFromSignals`, `computeIssueFingerprint`, `buildIssueDraft`).
+- Fixed transcript parsing to handle both bridge-injected and
+  exporter-emitted formats.
+- Closed a severity-classification gap for uncaught JS errors.
+
+## 0.2.x and earlier
+
+Initial public release of the MCP bridge: package listing, handoff markdown
+retrieval, file extraction, and Python-Whisper-based voice-note
+transcription. See git history for individual changes.

package/README.md

@@ -41,10 +41,11 @@ Set `TRACEGIST_DIR` to change where the bridge looks for packages (defaults to `
 | ------------------------------------------ | --------------------------------------------------------------- |
 | `list_tracegist_packages`                  | List package ZIPs in Downloads                                  |
 | `get_tracegist_package_overview`           | Manifest + truncated handoff preview                            |
-| `get_tracegist_handoff_markdown`           | Full handoff markdown                                           |
+| `get_tracegist_handoff_markdown`           | Full handoff markdown (with voice transcripts injected)         |
 | `read_tracegist_package_file`              | Read any file from the ZIP (e.g. `network/api-requests.jsonl`)  |
 | `extract_tracegist_package_file`           | Extract a file to disk                                          |
-| `transcribe_tracegist_package_voice_notes` | Local Whisper transcription                                     |
+| `transcribe_tracegist_package_voice_notes` | Voice-note transcription (OpenRouter or local Whisper)          |
+| `get_tracegist_issue_draft`                | Tracker-agnostic JSON for filing a Linear / GitHub / Jira issue |
 | `watch_live_session`                       | Poll real-time session events while recording is active         |
 | `get_live_screenshot`                      | Request and retrieve a screenshot of the current tab            |
 | `ask_tester_question`                      | Send a question to the tester (shown as a browser toast)        |
@@ -63,8 +64,60 @@ Each session ZIP may include:
 | `network/api-requests.jsonl` | API request/response bodies (opt-in, requires Deep Diagnostics + body capture enabled) |
 | `markers/marker-NN-*/`       | Per-marker screenshots, voice notes, highlight captures                                |
 
-## Prerequisites for transcription
+## Voice-note transcription
 
-- Python 3
-- `pip install openai-whisper`
-- `ffmpeg`
+Local Whisper is bundled — no Python, no system ffmpeg. The TraceGist extension
+records voice notes as 16 kHz mono wav, which whisper.cpp accepts directly.
+
+### Default — local Whisper (bundled, private, no external calls)
+
+`tracegist-mcp-bridge` depends on
+[`nodejs-whisper`](https://www.npmjs.com/package/nodejs-whisper), which compiles
+whisper.cpp at install time. The first transcription auto-downloads the model
+(~150 MB for the default `base.en`) into the package's cache.
+
+Override the model via env var:
+
+```json
+{
+  "mcpServers": {
+    "tracegist": {
+      "command": "npx",
+      "args": ["-y", "tracegist-mcp-bridge"],
+      "env": {
+        "TRACEGIST_WHISPER_MODEL": "small.en"
+      }
+    }
+  }
+}
+```
+
+Common models: `tiny.en`, `base.en` (default), `small.en`, `medium.en`,
+`large-v3`. English-only `*.en` variants are smaller and faster for English
+voice notes. Drop the `.en` suffix for multilingual.
+
+**Install-time requirement:** a C/C++ toolchain. Xcode CLI tools (macOS) and
+`build-essential` (Linux) are commonly already installed; on Windows you'll
+typically need to install Visual Studio Build Tools (the "Desktop
+development with C++" workload) explicitly.
+
+### Optional — OpenRouter (cloud, fastest first response)
+
+Set `OPENROUTER_API_KEY` when launching the bridge. When set, OpenRouter is
+tried first and local Whisper acts as fallback:
+
+```json
+{
+  "mcpServers": {
+    "tracegist": {
+      "command": "npx",
+      "args": ["-y", "tracegist-mcp-bridge"],
+      "env": {
+        "OPENROUTER_API_KEY": "sk-or-..."
+      }
+    }
+  }
+}
+```
+
+The bridge logs the active paths at startup (`Voice transcription path(s): ...`).

package/bin/lib.mjs

@@ -1,10 +1,14 @@
 import path from "node:path";
+import crypto from "node:crypto";
 
 const PACKAGE_SUFFIX = "-package.zip";
 const HANDOFF_SUFFIXES = ["-coding-agent-handoff.md", "-cursor-handoff.md"];
 
 export function isTraceGistPackageFile(fileName) {
-  return fileName.startsWith("tracegist-") && fileName.endsWith(PACKAGE_SUFFIX);
+  return (
+    (fileName.startsWith("tracegistcom-") || fileName.startsWith("tracegist-")) &&
+    fileName.endsWith(PACKAGE_SUFFIX)
+  );
 }
 
 export function normalizeZipBaseName(entryName) {
@@ -21,7 +25,7 @@ export function renderPackagesText(
   if (packages.length === 0) {
     return [
       `No TraceGist package zips found in ${directory}.`,
-      "Expected naming pattern: tracegist-...-package.zip",
+      "Expected naming pattern: tracegistcom-...-package.zip",
     ].join("\n");
   }
   const countLabel =
@@ -197,9 +201,478 @@ export function toolError(err) {
   };
 }
 
-export function formatExecError(err) {
-  if (err instanceof Error && err.message) return err.message;
-  return String(err);
+/**
+ * Extract a known audio format token from a MIME type or filename.
+ * Uses non-alphanumeric boundaries so substrings like "webmaster" don't match.
+ */
+export function audioFormatFromMime(mimeType, fallback = "webm") {
+  const m = String(mimeType || "")
+    .toLowerCase()
+    .match(/(?:^|[^a-z0-9])(wav|mp3|m4a|ogg|flac|webm)(?:[^a-z0-9]|$)/);
+  return m ? m[1] : fallback;
+}
+
+/**
+ * Parse a boolean-ish env-var value. Treats "0", "false", "no", "off"
+ * (case-insensitive) and empty/undefined as falsy; everything else as truthy.
+ * Avoids the JS footgun where `Boolean("0") === true`, so users who set
+ * `MY_FLAG=0` get the "off" behavior they expect.
+ */
+export function envFlagEnabled(value) {
+  if (value === undefined || value === null) return false;
+  const trimmed = String(value).trim();
+  if (trimmed === "") return false;
+  return !["0", "false", "no", "off"].includes(trimmed.toLowerCase());
+}
+
+/**
+ * Returns true if a WebSocket upgrade request should be accepted on the
+ * live-shadow server. Rejects http(s) page origins to prevent a malicious
+ * web page from connecting via DNS-rebinding-style attacks (CORS does not
+ * apply to WebSockets, so the page-level same-origin policy alone is not
+ * sufficient). Allows chrome-extension:// / moz-extension:// origins and
+ * missing/empty origins (the TraceGist extension and CLI clients).
+ *
+ * Note: non-browser callers can spoof the Origin header, so this defends
+ * specifically against the "malicious web page" threat model — local code
+ * with arbitrary HTTP capability is out of scope.
+ */
+export function isAllowedLiveShadowOrigin(originHeader) {
+  if (!originHeader) return true;
+  const lower = String(originHeader).toLowerCase();
+  if (lower.startsWith("chrome-extension://")) return true;
+  if (lower.startsWith("moz-extension://")) return true;
+  return false;
 }
 
 export { HANDOFF_SUFFIXES };
+
+// ---------------------------------------------------------------------------
+// Issue-draft extraction
+//
+// The bridge's structured access to a TraceGist package is split between the
+// manifest JSON (typed counts, file paths, marker metadata) and the handoff
+// markdown (free-form text including AI-generated title/summary/transcripts).
+// The helpers below parse the handoff back into the fields a downstream issue
+// tracker (Linear / GitHub / Jira via their MCPs) needs.
+// ---------------------------------------------------------------------------
+
+/** Parse the `## Tier 0: Quick Summary` markdown table into a key→value map. */
+export function parseTier0Table(tier0Content) {
+  if (!tier0Content) return {};
+  const out = {};
+  for (const rawLine of tier0Content.split("\n")) {
+    const line = rawLine.trim();
+    if (!line.startsWith("|") || line.startsWith("|---") || /^\|\s*Field\s*\|/i.test(line)) {
+      continue;
+    }
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((c) => c.trim());
+    if (cells.length === 2 && cells[0] && cells[1]) {
+      out[cells[0]] = cells[1];
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse the `## Session Environment` bullet list into structured fields.
+ * Lines come from formatEnvironmentSnapshot in lib/export-agent.ts.
+ */
+export function parseEnvironmentLines(envContent) {
+  if (!envContent) return null;
+  const env = {};
+  for (const rawLine of envContent.split("\n")) {
+    const line = rawLine.trim();
+    let m;
+    if ((m = line.match(/^-\s+Viewport:\s+(\d+)\D+(\d+)px/i))) {
+      env.viewport = { width: Number(m[1]), height: Number(m[2]) };
+    } else if ((m = line.match(/^-\s+Device pixel ratio:\s+([\d.]+)/i))) {
+      env.devicePixelRatio = Number(m[1]);
+    } else if ((m = line.match(/^-\s+Screen:\s+(\d+)\D+(\d+)px/i))) {
+      env.screen = { width: Number(m[1]), height: Number(m[2]) };
+    } else if ((m = line.match(/^-\s+User agent:\s+(.+)$/i))) {
+      env.userAgent = m[1].trim();
+    } else if ((m = line.match(/^-\s+Scroll position:\s+\((-?\d+),\s*(-?\d+)\)px/i))) {
+      env.scroll = { x: Number(m[1]), y: Number(m[2]) };
+    }
+  }
+  return Object.keys(env).length > 0 ? env : null;
+}
+
+/**
+ * Split a Marker Timeline section into individual marker blocks and parse the
+ * known `- Field: value` lines emitted by lib/export-agent.ts.
+ */
+export function parseMarkerBlocks(markerTimelineContent) {
+  if (!markerTimelineContent) return [];
+  const lines = markerTimelineContent.split("\n");
+  const blocks = [];
+  let current = null;
+
+  const flush = () => {
+    if (current) blocks.push(current);
+  };
+
+  for (const line of lines) {
+    const headerMatch = line.match(/^###\s+Marker\s+(\d+)\s*\(([^)]+)\)(.*)$/i);
+    if (headerMatch) {
+      flush();
+      current = {
+        order: Number(headerMatch[1]),
+        timestampLabel: headerMatch[2].trim(),
+        flags: headerMatch[3].trim(),
+        isSessionContextNote: /session-context-note/i.test(headerMatch[3] || ""),
+        rawLines: [],
+      };
+      continue;
+    }
+    if (!current) continue;
+    current.rawLines.push(line);
+
+    const fieldMatch = line.match(/^-\s+([^:]+):\s*(.*)$/);
+    if (!fieldMatch) continue;
+    const key = fieldMatch[1].trim();
+    const value = fieldMatch[2].trim();
+    switch (key) {
+      case "Marker ID":
+        current.markerId = value;
+        break;
+      case "Type":
+        current.type = value;
+        break;
+      case "Trigger type":
+        current.triggerType = value;
+        break;
+      case "Trigger":
+        current.triggerMessage = value;
+        break;
+      case "Trigger status code":
+        current.triggerStatusCode = Number(value);
+        break;
+      case "Trigger URL":
+        current.triggerUrl = value;
+        break;
+      case "URL":
+        current.url = value;
+        break;
+      case "Page title":
+        current.pageTitle = value;
+        break;
+      case "Has transcript":
+        current.hasTranscript = /^yes\b/i.test(value);
+        break;
+      case "Has AI assessment":
+        current.hasAiAssessment = /^yes\b/i.test(value);
+        break;
+      case "AI title":
+        current.aiTitle = value;
+        break;
+      case "AI summary":
+        current.aiSummary = value;
+        break;
+      case "AI technical context":
+        current.aiTechnicalContext = value;
+        break;
+      case "Voice note transcript": {
+        // Bridge-injected format: `- Voice note transcript: "<text>"`
+        current.voiceTranscript = value.replace(/^"(.*)"$/, "$1");
+        break;
+      }
+      case "Transcript": {
+        // Exporter-emitted format (lib/export-agent.ts): `- Transcript:` followed
+        // by `  - <text>` on the next line. value is empty here; capture the
+        // continuation by recording a flag and reading on the next iteration.
+        current._awaitingTranscriptContinuation = true;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  flush();
+
+  for (const b of blocks) {
+    // Resolve `- Transcript:` continuation lines now that rawLines is complete.
+    if (b._awaitingTranscriptContinuation && !b.voiceTranscript) {
+      const idx = b.rawLines.findIndex((l) => /^-\s+Transcript:\s*$/.test(l));
+      if (idx >= 0 && idx + 1 < b.rawLines.length) {
+        const next = b.rawLines[idx + 1];
+        const m = next.match(/^\s{2,}-\s+(.+)$/);
+        if (m) b.voiceTranscript = m[1].trim();
+      }
+    }
+    delete b._awaitingTranscriptContinuation;
+    const errorIdx = b.rawLines.findIndex((l) => /^-\s+Errors\/failures in window/i.test(l));
+    if (errorIdx >= 0) {
+      const errs = [];
+      for (let i = errorIdx + 1; i < b.rawLines.length; i++) {
+        const l = b.rawLines[i];
+        if (/^\s{2}-\s+/.test(l)) {
+          errs.push(l.replace(/^\s{2}-\s+/, "").trim());
+        } else if (/^-\s+/.test(l)) {
+          break;
+        }
+      }
+      b.windowErrors = errs;
+    } else {
+      b.windowErrors = [];
+    }
+  }
+  return blocks;
+}
+
+/**
+ * Pick the marker most likely to drive the issue title/body.
+ * Preference order: manual + AI assessment + window errors → manual + AI →
+ * manual → first marker. Session-context-notes are deprioritized.
+ */
+export function pickPrimaryMarker(markers) {
+  if (!markers || markers.length === 0) return null;
+  const eligible = markers.filter((m) => !m.isSessionContextNote);
+  const pool = eligible.length > 0 ? eligible : markers;
+  const score = (m) => {
+    let s = 0;
+    if (m.type === "manual") s += 4;
+    if (m.hasAiAssessment) s += 2;
+    if (m.hasTranscript) s += 1;
+    if (m.windowErrors && m.windowErrors.length > 0) s += 3;
+    if (m.triggerStatusCode && m.triggerStatusCode >= 500) s += 2;
+    return s;
+  };
+  return [...pool].sort((a, b) => {
+    const ds = score(b) - score(a);
+    if (ds !== 0) return ds;
+    return (a.order || 0) - (b.order || 0);
+  })[0];
+}
+
+/**
+ * Heuristic severity from notableEvents counts and primary-marker triggers.
+ * Returns { severity: "high"|"medium"|"low", rationale: string[] }.
+ */
+export function severityFromSignals({ notableEvents, primaryMarker, markers }) {
+  const rationale = [];
+  const networkErrors = notableEvents?.networkErrors || [];
+  const consoleErrors = notableEvents?.consoleErrors || [];
+  const windowErrors = primaryMarker?.windowErrors || [];
+  const has5xx = networkErrors.some((e) => / 5\d{2}\b/.test(String(e.message || "")));
+  const hasAuto5xx = (markers || []).some(
+    (m) => m.type === "auto" && m.triggerStatusCode && m.triggerStatusCode >= 500,
+  );
+  const SEVERE_JS_ERROR =
+    /uncaught|unhandled|jserror|js-error|TypeError|ReferenceError|SyntaxError/i;
+  const hasUncaughtMarker = (markers || []).some(
+    (m) => m.type === "auto" && SEVERE_JS_ERROR.test(m.triggerType || ""),
+  );
+  const hasSevereConsole = consoleErrors.some((e) =>
+    SEVERE_JS_ERROR.test(String(e?.message || e?.type || "")),
+  );
+
+  let severity = "low";
+  if (has5xx || hasAuto5xx) {
+    severity = "high";
+    rationale.push("server error (5xx) observed");
+  }
+  if (hasUncaughtMarker) {
+    severity = "high";
+    rationale.push("uncaught JS error triggered an auto-marker");
+  }
+  if (hasSevereConsole) {
+    severity = "high";
+    rationale.push("severe JS error in console (TypeError/ReferenceError/uncaught/etc.)");
+  }
+  if (severity !== "high" && windowErrors.length > 0) {
+    // Errors observed in the marker's ±5s window are direct evidence the marker
+    // captured a real failure, even if notableEvents looks empty.
+    severity = "medium";
+  }
+  // A single benign console error alone stays "low" — they're often noise
+  // (deprecation warnings, third-party scripts). networkErrors of any count and
+  // >1 console errors bump to medium.
+  if (severity !== "high" && (networkErrors.length > 0 || consoleErrors.length > 1)) {
+    severity = "medium";
+  }
+  if (severity !== "low") {
+    rationale.push(
+      `${networkErrors.length} notable network error(s), ${consoleErrors.length} console error(s)`,
+    );
+  }
+  if (windowErrors.length > 0) {
+    rationale.push(`primary marker window contains ${windowErrors.length} error(s)`);
+  }
+  if (rationale.length === 0) {
+    rationale.push("no errors detected in notable events or primary marker window");
+  }
+  return { severity, rationale };
+}
+
+// Normalize numeric and hex-id segments so cosmetically-different inputs
+// (e.g. /users/123 vs /users/456, "request 7d3f4a8b" vs "request a1b2c3d4")
+// hash the same.
+function normalizeForFingerprint(s) {
+  return String(s || "")
+    .toLowerCase()
+    .replace(/[a-f0-9]{8,}/g, "ID")
+    .replace(/\b\d+\b/g, "N")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Stable 16-hex fingerprint for dedup against existing tracker issues. */
+export function computeIssueFingerprint(url, errorMessage) {
+  let urlPath = "";
+  try {
+    if (url) urlPath = new URL(url).pathname.replace(/\/+$/, "") || "/";
+  } catch {
+    urlPath = String(url || "").trim();
+  }
+  const normalizedPath = normalizeForFingerprint(urlPath);
+  const normalizedError = normalizeForFingerprint(errorMessage).slice(0, 200);
+  const input = `${normalizedPath}|${normalizedError}`;
+  return crypto.createHash("sha1").update(input).digest("hex").slice(0, 16);
+}
+
+/**
+ * Build a tracker-agnostic issue draft from a manifest + parsed handoff.
+ * Pure: no I/O, no zip access. Caller supplies the inputs.
+ */
+export function buildIssueDraft({ zipPath, manifest, handoffMarkdown }) {
+  const sections = parseMarkdownSections(handoffMarkdown || "");
+  const sectionByName = new Map(sections.map((s) => [s.name.toLowerCase(), s]));
+
+  const tier0 = sectionByName.get("tier 0: quick summary");
+  const tier0Fields = parseTier0Table(tier0?.content || "");
+
+  const markerSection = sectionByName.get("marker timeline");
+  const markers = parseMarkerBlocks(markerSection?.content || "");
+  const primaryMarker = pickPrimaryMarker(markers);
+
+  const envSection = sectionByName.get("session environment");
+  const environment = parseEnvironmentLines(envSection?.content || "");
+
+  const sessionUrl = tier0Fields.URL || primaryMarker?.url || null;
+  const notableEvents = manifest?.notableEvents || { consoleErrors: [], networkErrors: [] };
+  const { severity, rationale } = severityFromSignals({
+    notableEvents,
+    primaryMarker,
+    markers,
+  });
+
+  const topError =
+    notableEvents.networkErrors[0] ||
+    notableEvents.consoleErrors[0] ||
+    (primaryMarker?.triggerMessage
+      ? {
+          type: primaryMarker.triggerType || "trigger",
+          message: primaryMarker.triggerMessage,
+          timestampLabel: primaryMarker.timestampLabel,
+        }
+      : null) ||
+    (primaryMarker?.windowErrors?.[0]
+      ? { type: "window-error", message: primaryMarker.windowErrors[0] }
+      : null);
+
+  let title = primaryMarker?.aiTitle?.trim();
+  if (!title && primaryMarker?.voiceTranscript) {
+    title = primaryMarker.voiceTranscript.split(/[.?!]/)[0].slice(0, 100).trim();
+  }
+  if (!title && topError?.message) {
+    title = `${topError.type ? `${topError.type}: ` : ""}${topError.message}`.slice(0, 120);
+  }
+  if (!title) {
+    const path = (() => {
+      try {
+        return sessionUrl ? new URL(sessionUrl).pathname : "";
+      } catch {
+        return "";
+      }
+    })();
+    title = `TraceGist session bug${path ? ` on ${path}` : ""}`;
+  }
+
+  const expected = primaryMarker?.aiSummary || null;
+  const actual =
+    primaryMarker?.aiTechnicalContext ||
+    (primaryMarker?.windowErrors?.length ? primaryMarker.windowErrors[0] : null) ||
+    topError?.message ||
+    null;
+
+  const reproductionSteps = [];
+  if (manifest?.pythonPlaywrightScriptPath) {
+    reproductionSteps.push(
+      `Run the included Python Playwright repro: \`python ${manifest.pythonPlaywrightScriptPath}\``,
+    );
+  }
+  if (manifest?.playwrightScriptPath) {
+    reproductionSteps.push(
+      `Or run the TypeScript repro: \`npx playwright test ${manifest.playwrightScriptPath}\``,
+    );
+  }
+  if (primaryMarker?.voiceTranscript) {
+    reproductionSteps.push(`Tester voice note: "${primaryMarker.voiceTranscript}"`);
+  }
+
+  const evidencePaths = [];
+  if (primaryMarker?.markerId && manifest?.markers) {
+    const manifestMarker = manifest.markers.find((m) => m.markerId === primaryMarker.markerId);
+    if (manifestMarker) {
+      const dir = manifestMarker.markerDirectory;
+      for (const f of manifestMarker.files || []) {
+        if (f.filename) evidencePaths.push(`${dir}/${f.filename}`);
+      }
+    }
+  }
+
+  const fingerprint = computeIssueFingerprint(sessionUrl, topError?.message);
+
+  const notes = [];
+  if (!handoffMarkdown) notes.push("handoff markdown was not present in the package");
+  if (!primaryMarker) notes.push("no markers detected; title/body fall back to URL only");
+  if (primaryMarker && !primaryMarker.hasAiAssessment) {
+    notes.push(
+      "primary marker has no AI assessment — expected/actual are best-effort from logs and transcript",
+    );
+  }
+  if (!environment) notes.push("session environment section missing; environment field is null");
+
+  return {
+    zipPath: zipPath || null,
+    title,
+    severity,
+    severityRationale: rationale,
+    sessionUrl,
+    pageTitle: primaryMarker?.pageTitle || null,
+    sessionStartIso: manifest?.sessionStartTimeIso || null,
+    duration: tier0Fields.Duration || null,
+    environment,
+    expected,
+    actual,
+    topError,
+    reproductionSteps,
+    evidencePaths,
+    primaryMarker: primaryMarker
+      ? {
+          markerId: primaryMarker.markerId,
+          order: primaryMarker.order,
+          type: primaryMarker.type,
+          timestampLabel: primaryMarker.timestampLabel,
+          hasAiAssessment: !!primaryMarker.hasAiAssessment,
+          hasTranscript: !!primaryMarker.hasTranscript,
+        }
+      : null,
+    counts: {
+      markers: manifest?.markerCount ?? markers.length,
+      networkErrors: notableEvents.networkErrors.length,
+      consoleErrors: notableEvents.consoleErrors.length,
+    },
+    playwrightScripts: {
+      typescript: manifest?.playwrightScriptPath || null,
+      python: manifest?.pythonPlaywrightScriptPath || null,
+    },
+    fingerprint,
+    notes,
+  };
+}