@mmerterden/multi-agent-pipeline 20.23.1 → 20.24.0

package/pipeline/scripts/transcript-index.mjs

@@ -0,0 +1,950 @@
+#!/usr/bin/env node
+/**
+ * @file transcript-index.mjs  -  what a run did, read out of its session
+ * transcripts, as evidence a post-mortem can cite.
+ *
+ * The run log says what each phase decided. The transcript says what the
+ * session actually did on the way: which tool calls it repeated, where it sat
+ * waiting, where the context was compacted, which subagent failed, what was
+ * denied. This reads a Claude Code session file (`<session>.jsonl`, plus the
+ * subagent files beside it) and extracts those facts deterministically, so the
+ * same transcript always gives the same index and every finding carries the
+ * `file:line` it came from. Interpreting them is left to the model that writes
+ * the post-mortem (/multi-agent:postmortem); nothing here guesses.
+ *
+ * Extracted:
+ *   turns        one per prompt the user typed (or slash command), with tool
+ *                call count, token usage and duration
+ *   toolCalls    name, a redacted input excerpt, duration (reported by the
+ *                tool when it says, else the timestamp difference), error flag
+ *   loops        identical calls (same tool, same input) made at least
+ *                `loopThreshold` times in one file, with the longest streak
+ *   stalls       gaps of at least `stallMinutes` between two records while the
+ *                session was working, with the tool that was running
+ *   compactions  boundaries with trigger and token figures, and the summary
+ *                turn that follows each
+ *   subagents    each dispatch with its type, result status, duration, tokens,
+ *                and the background notification when one arrives
+ *   errors       tool errors, denials, hook blocks, API errors, interrupts
+ *   invocations  slash commands and skills
+ *   usage        token totals, each assistant message counted once
+ *
+ * PRIVACY. A transcript holds whatever the session read. Every string taken
+ * from one passes through the redactor before it is placed in the index:
+ * credentials by the outbound gate's certain rules (lib/redact.mjs) and the
+ * shapes those have no prefix for (_redact.mjs redactCredentials), then links, addresses, hosts, machine paths and home directories (_redact.mjs
+ * scrubCounted), then the transcript directory's own project slug, which
+ * spells the home directory with dashes. The index reports how many items of
+ * each kind were replaced, and before anything is printed the whole output is
+ * run through the outbound gate once more: a certain finding left in it stops
+ * the script with nothing written. Nothing is sent anywhere.
+ *
+ * Usage:
+ *   transcript-index.mjs <session.jsonl>...   index these files
+ *   transcript-index.mjs --run <task-id|#N>   find the run's session files, index them
+ *   transcript-index.mjs --run <id> --locate  only report where the run and its files are
+ *   options: --json  --no-subagents  --max-mb N  --max-events N
+ *            --loop-threshold N  --stall-minutes N  --excerpt N
+ *
+ * TRANSCRIPTS_ROOT overrides ~/.claude/projects, LOGS_ROOT the run log root.
+ *
+ * Exit codes: 0 indexed | 2 usage | 3 nothing to read | 4 redaction guard
+ *
+ * @module pipeline/scripts/transcript-index
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { readJsonl } from "./_jsonl.mjs";
+import { redactCredentials, scrubCounted } from "./_redact.mjs";
+import { listRuns, logsRoot, taskIdVariants } from "./_run-paths.mjs";
+import { redact } from "../lib/redact.mjs";
+import { scan } from "../lib/outbound-gate.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const DEFAULTS = {
+  loopThreshold: 3,
+  stallMinutes: 5,
+  excerpt: 160,
+  maxEvents: 400,
+  maxBytes: 256 * 1024 * 1024,
+  subagents: true,
+};
+
+const SUBAGENT_TOOLS = new Set(["Agent", "Task"]);
+const DENIAL =
+  /doesn't want to proceed|User rejected tool use|^Permission to use \S+ (?:has been|was) denied|permission denied by the user/i;
+const HOOK_BLOCK = /\bhook (?:error|blocked)|PreToolUse:|PostToolUse:/;
+const INTERRUPT = /^\[Request interrupted by user/;
+
+export const defaultProjectsRoot = () =>
+  process.env.TRANSCRIPTS_ROOT || join(homedir(), ".claude", "projects");
+
+/** A session id as Claude Code writes it (a UUID), or any token safe as a file name. */
+const SAFE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+/** The directory name Claude Code gives a working directory under ~/.claude/projects. */
+export const projectSlug = (dir) => String(dir).replace(/[^A-Za-z0-9]/g, "-");
+
+// --- redaction ---------------------------------------------------------------
+
+const MARKER = /\[redacted:([a-z0-9-]+)\]/g;
+const countMarkers = (s) => {
+  const out = {};
+  for (const m of s.matchAll(MARKER)) out[m[1]] = (out[m[1]] || 0) + 1;
+  return out;
+};
+const TOKEN_CHAR = /[A-Za-z0-9_\-./+=:@~%]/;
+
+/**
+ * `text` cut to `limit` characters, backed off to the start of a token that
+ * the cut would split, so no half-credential survives on the boundary.
+ */
+function cut(text, limit) {
+  if (text.length <= limit) return text;
+  let end = limit;
+  while (end > 0 && TOKEN_CHAR.test(text[end]) && TOKEN_CHAR.test(text[end - 1])) end--;
+  return `${text.slice(0, end).trimEnd()} ...`;
+}
+
+/**
+ * One redactor per index, so its counts are the index's counts.
+ *
+ * @param {{home?: string}} [opts] the home directory whose dashed spelling (a
+ *   transcript directory name) is replaced; defaults to this machine's
+ */
+export function createRedactor({ home = homedir() } = {}) {
+  const byKind = {};
+  const bump = (kind, n = 1) => (byKind[kind] = (byKind[kind] || 0) + n);
+  const homeSlug = home && home.length > 1 ? projectSlug(home) : null;
+  const GENERIC_SLUG = /(?<![\w~])-(?:Users|home)-[A-Za-z0-9_]+/g;
+
+  function clean(value) {
+    if (value === null || value === undefined) return "";
+    const raw = String(value);
+    if (!raw) return "";
+    const before = countMarkers(raw);
+    let out = redactCredentials(redact(raw));
+    for (const [k, n] of Object.entries(countMarkers(out))) {
+      const added = n - (before[k] || 0);
+      if (added > 0) bump(k, added);
+    }
+    const s = scrubCounted(out);
+    out = s.text;
+    for (const [k, n] of Object.entries(s.counts)) bump(k, n);
+    if (homeSlug && out.includes(homeSlug)) {
+      const parts = out.split(homeSlug);
+      bump("home-path", parts.length - 1);
+      out = parts.join("~");
+    }
+    out = out.replace(GENERIC_SLUG, () => {
+      bump("home-path");
+      return "~";
+    });
+    return out;
+  }
+
+  /** A short, single-line, redacted excerpt. */
+  function excerpt(value, limit = DEFAULTS.excerpt) {
+    const flat = String(value ?? "")
+      .replace(/\s+/g, " ")
+      .trim();
+    return cut(clean(cut(flat, Math.max(limit * 4, 1024))), limit);
+  }
+
+  const total = () => Object.values(byKind).reduce((a, n) => a + n, 0);
+  return { clean, excerpt, byKind, total };
+}
+
+/**
+ * Throws when `text` still carries something the outbound gate is certain is a
+ * credential. Only the rule names are reported, never the match.
+ */
+export function assertClean(text) {
+  const hits = scan(text).filter((f) => f.certain);
+  if (hits.length) {
+    const names = [...new Set(hits.map((h) => h.rule))].join(", ");
+    const err = new Error(`redaction incomplete: ${names}`);
+    err.code = "REDACTION";
+    throw err;
+  }
+}
+
+// --- reading -----------------------------------------------------------------
+
+const textOf = (content) => {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((b) => (typeof b === "string" ? b : b?.type === "text" ? b.text || "" : ""))
+    .filter(Boolean)
+    .join("\n");
+};
+
+const stable = (v) => {
+  if (Array.isArray(v)) return `[${v.map(stable).join(",")}]`;
+  if (v && typeof v === "object")
+    return `{${Object.keys(v)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stable(v[k])}`)
+      .join(",")}}`;
+  return JSON.stringify(v ?? null);
+};
+
+const digest = (s) => createHash("sha256").update(s).digest("hex").slice(0, 12);
+
+/** The part of a tool input worth showing: the command, the path, the pattern. */
+function inputGist(name, input) {
+  if (!input || typeof input !== "object") return "";
+  for (const k of [
+    "command",
+    "file_path",
+    "path",
+    "pattern",
+    "url",
+    "query",
+    "skill",
+    "description",
+  ]) {
+    if (typeof input[k] === "string" && input[k]) return input[k];
+  }
+  return stable(input);
+}
+
+const tsOf = (rec) => {
+  const t = Date.parse(rec?.timestamp || "");
+  return Number.isFinite(t) ? t : null;
+};
+
+const numberOr = (v, fallback = 0) => (Number.isFinite(Number(v)) ? Number(v) : fallback);
+
+/** The .jsonl names in `dir`, sorted; none when it cannot be read. */
+function listJsonl(dir) {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Session files plus, unless disabled, the subagent files Claude Code keeps beside them. */
+function expandFiles(paths, withSubagents) {
+  const out = [];
+  for (const p of paths) {
+    out.push(p);
+    if (!withSubagents) continue;
+    const dir = join(dirname(p), basename(p, ".jsonl"), "subagents");
+    for (const f of listJsonl(dir)) out.push(join(dir, f));
+  }
+  return out;
+}
+
+/**
+ * Index one or more transcript files.
+ *
+ * @param {string[]} paths
+ * @param {Partial<typeof DEFAULTS> & {home?: string}} [options]
+ */
+export async function indexTranscripts(paths, options = {}) {
+  const o = { ...DEFAULTS, ...options };
+  const R = createRedactor({ home: o.home });
+  const ex = (v) => R.excerpt(v, o.excerpt);
+  const stallMs = o.stallMinutes * 60_000;
+
+  const files = [];
+  const turns = [];
+  const toolCalls = [];
+  const compactions = [];
+  const subagents = [];
+  const errors = [];
+  const invocations = [];
+  const stalls = [];
+  const loops = [];
+  const timeline = [];
+  const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, messages: 0 };
+  const seenMessages = new Set();
+  const subagentByToolId = new Map();
+  const subagentByAgentId = new Map();
+  let idleGaps = 0;
+
+  for (const path of expandFiles(paths, o.subagents)) {
+    const name = basename(path);
+    const at = (line) => `${name}:${line}`;
+    const stats = {};
+    const fileRow = { name, path: R.clean(path), sidechain: false, malformedAt: [] };
+    const pending = new Map();
+    const groups = new Map();
+    let lastKey = null;
+    let streak = 0;
+    let turn = null;
+    let prev = null;
+
+    const openTurn = (line, ts, prompt) => {
+      turn = {
+        at: at(line),
+        prompt,
+        firstTs: ts,
+        lastTs: ts,
+        toolCalls: 0,
+        assistantMessages: 0,
+        errors: 0,
+        durationMs: null,
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, peakContext: 0 },
+      };
+      turns.push(turn);
+    };
+    const push = (event) => timeline.push(event);
+
+    for await (const row of readJsonl(path, { stats, maxBytes: o.maxBytes })) {
+      if (!row.record) {
+        if (row.reason !== "truncated") fileRow.malformedAt.push(at(row.line));
+        continue;
+      }
+      const rec = row.record;
+      const line = row.line;
+      const ts = tsOf(rec);
+      if (rec.isSidechain) fileRow.sidechain = true;
+
+      if (ts !== null && prev && prev.ts !== null) {
+        const gap = ts - prev.ts;
+        if (gap >= stallMs) {
+          const startsTurn = rec.type === "user" && isPrompt(rec);
+          if (startsTurn && pending.size === 0) idleGaps++;
+          else {
+            const running = [...pending.values()].at(-1);
+            stalls.push({
+              from: at(prev.line),
+              to: at(line),
+              gapMs: gap,
+              pendingTool: running ? running.name : null,
+            });
+          }
+        }
+      }
+      if (ts !== null) prev = { ts, line };
+      if (turn && ts !== null) turn.lastTs = ts;
+
+      if (rec.type === "system") {
+        if (rec.subtype === "compact_boundary") {
+          const m = rec.compactMetadata || {};
+          compactions.push({
+            at: at(line),
+            kind: "boundary",
+            trigger: R.clean(m.trigger || "unknown"),
+            preTokens: numberOr(m.preTokens, null),
+            postTokens: numberOr(m.postTokens, null),
+          });
+          push({ at: at(line), role: "system", kind: "compaction" });
+        } else if (rec.subtype === "turn_duration") {
+          if (turn) turn.durationMs = numberOr(rec.durationMs, null);
+        } else if (Array.isArray(rec.hookErrors) && rec.hookErrors.length) {
+          errors.push({ at: at(line), kind: "hook", tool: null, text: ex(textOf(rec.hookErrors)) });
+          if (turn) turn.errors++;
+        } else if (rec.level === "error") {
+          errors.push({ at: at(line), kind: "system", tool: null, text: ex(rec.content) });
+          if (turn) turn.errors++;
+        }
+        continue;
+      }
+
+      if (rec.type === "user") {
+        const content = rec.message?.content;
+        if (rec.isCompactSummary) {
+          compactions.push({ at: at(line), kind: "summary" });
+          continue;
+        }
+        if (Array.isArray(content) && content.some((b) => b?.type === "tool_result")) {
+          let first = true;
+          for (const b of content) {
+            if (b?.type !== "tool_result") continue;
+            const call = pending.get(b.tool_use_id);
+            pending.delete(b.tool_use_id);
+            const result = first && rec.toolUseResult !== undefined ? rec.toolUseResult : undefined;
+            first = false;
+            const body = textOf(b.content) || (typeof result === "string" ? result : "");
+            const denied = DENIAL.test(body) || (typeof result === "string" && DENIAL.test(result));
+            const isError = b.is_error === true || denied;
+            if (call) {
+              call.resultAt = at(line);
+              call.isError = isError;
+              const reported =
+                result && typeof result === "object"
+                  ? (result.durationMs ?? result.totalDurationMs)
+                  : undefined;
+              if (Number.isFinite(reported)) {
+                call.durationMs = reported;
+                call.durationSource = "reported";
+              } else if (call.ts !== null && ts !== null) {
+                call.durationMs = ts - call.ts;
+                call.durationSource = "timestamps";
+              }
+              if (call.group) call.group.errors += isError ? 1 : 0;
+              const sub = subagentByToolId.get(b.tool_use_id);
+              if (sub) {
+                sub.resultAt = at(line);
+                if (result && typeof result === "object") {
+                  sub.status = R.clean(result.status || (isError ? "error" : "completed"));
+                  if (result.agentId) subagentByAgentId.set(String(result.agentId), sub);
+                  if (Number.isFinite(result.totalDurationMs))
+                    sub.durationMs = result.totalDurationMs;
+                  if (Number.isFinite(result.totalTokens)) sub.tokens = result.totalTokens;
+                  if (Number.isFinite(result.totalToolUseCount))
+                    sub.toolUses = result.totalToolUseCount;
+                } else {
+                  sub.status = isError ? "error" : "completed";
+                }
+                if (
+                  !sub.durationMs &&
+                  call.durationMs !== undefined &&
+                  sub.status !== "async_launched"
+                )
+                  sub.durationMs = call.durationMs;
+                sub.result = ex(body);
+              }
+            }
+            if (isError) {
+              const kind = denied ? "denial" : HOOK_BLOCK.test(body) ? "hook" : "error";
+              errors.push({ at: at(line), kind, tool: call ? call.name : null, text: ex(body) });
+              if (turn) turn.errors++;
+              push({ at: at(line), role: "user", kind, name: call ? call.name : null });
+            }
+          }
+          continue;
+        }
+
+        const text = textOf(content);
+        if (rec.isSidechain) continue;
+        const notice = text.match(/<task-notification>([\s\S]*?)<\/task-notification>/);
+        if (notice) {
+          const id = (notice[1].match(/<task-id>([^<]+)<\/task-id>/) || [])[1];
+          const status = (notice[1].match(/<status>([^<]+)<\/status>/) || [])[1];
+          const sub = id ? subagentByAgentId.get(id.trim()) : null;
+          if (sub) {
+            sub.notifiedAt = at(line);
+            if (status) sub.status = R.clean(status.trim());
+          }
+          push({ at: at(line), role: "user", kind: "notification", text: ex(status || "") });
+          continue;
+        }
+        if (INTERRUPT.test(text)) {
+          errors.push({ at: at(line), kind: "interrupt", tool: null, text: ex(text) });
+          if (turn) turn.errors++;
+          push({ at: at(line), role: "user", kind: "interrupt" });
+          continue;
+        }
+        if (rec.isMeta) continue;
+        const command = text.match(/<command-name>\s*([^<\s]+)\s*<\/command-name>/);
+        if (command) {
+          const cmd = R.clean(command[1]);
+          invocations.push({ at: at(line), kind: "command", name: cmd });
+          openTurn(line, ts, cmd);
+          push({ at: at(line), role: "user", kind: "command", name: cmd });
+          continue;
+        }
+        if (!text.trim()) continue;
+        const prompt = ex(text);
+        openTurn(line, ts, prompt);
+        push({ at: at(line), role: "user", kind: "prompt", text: prompt });
+        continue;
+      }
+
+      if (rec.type === "assistant") {
+        const msg = rec.message || {};
+        if (!turn && !rec.isSidechain) openTurn(line, ts, null);
+        if (turn) turn.assistantMessages++;
+        const u = msg.usage;
+        if (u && !(msg.id && seenMessages.has(msg.id))) {
+          if (msg.id) seenMessages.add(msg.id);
+          const add = {
+            input: numberOr(u.input_tokens),
+            output: numberOr(u.output_tokens),
+            cacheRead: numberOr(u.cache_read_input_tokens),
+            cacheWrite: numberOr(u.cache_creation_input_tokens),
+          };
+          for (const k of Object.keys(add)) usage[k] += add[k];
+          usage.messages++;
+          if (turn) {
+            for (const k of Object.keys(add)) turn.usage[k] += add[k];
+            const ctx = add.input + add.cacheRead + add.cacheWrite;
+            if (ctx > turn.usage.peakContext) turn.usage.peakContext = ctx;
+          }
+        }
+        if (rec.isApiErrorMessage) {
+          errors.push({
+            at: at(line),
+            kind: "api-error",
+            tool: null,
+            text: ex(textOf(msg.content)),
+          });
+          if (turn) turn.errors++;
+        }
+        for (const b of Array.isArray(msg.content) ? msg.content : []) {
+          if (b?.type === "text" && b.text?.trim()) {
+            push({ at: at(line), role: "assistant", kind: "text", text: ex(b.text) });
+            continue;
+          }
+          if (b?.type !== "tool_use") continue;
+          const toolName = R.clean(b.name || "unknown");
+          const input = b.input || {};
+          const key = `${b.name}\u0000${stable(input)}`;
+          let group = groups.get(key);
+          if (!group) {
+            group = { name: toolName, hash: digest(key), at: [], errors: 0, consecutive: 0 };
+            group.input = ex(inputGist(b.name, input));
+            groups.set(key, group);
+          }
+          group.at.push(at(line));
+          streak = key === lastKey ? streak + 1 : 1;
+          lastKey = key;
+          if (streak > group.consecutive) group.consecutive = streak;
+          const call = {
+            at: at(line),
+            name: toolName,
+            input: group.input,
+            ts,
+            durationMs: undefined,
+            durationSource: null,
+            resultAt: null,
+            isError: false,
+            group,
+          };
+          toolCalls.push(call);
+          if (b.id) pending.set(b.id, call);
+          if (turn) turn.toolCalls++;
+          push({ at: at(line), role: "assistant", kind: "tool", name: toolName, text: call.input });
+
+          if (SUBAGENT_TOOLS.has(b.name)) {
+            const sub = {
+              at: at(line),
+              agentType: R.clean(input.subagent_type || "general-purpose"),
+              description: ex(input.description || ""),
+              background: input.run_in_background === true,
+              model: input.model ? R.clean(input.model) : null,
+              status: null,
+              resultAt: null,
+              notifiedAt: null,
+              durationMs: null,
+              tokens: null,
+              toolUses: null,
+              result: null,
+            };
+            subagents.push(sub);
+            if (b.id) subagentByToolId.set(b.id, sub);
+          }
+          if (b.name === "Skill" && (input.skill || input.command)) {
+            invocations.push({
+              at: at(line),
+              kind: "skill",
+              name: R.clean(input.skill || input.command),
+            });
+          }
+          if (b.name === "SlashCommand" && input.command) {
+            invocations.push({ at: at(line), kind: "command", name: R.clean(input.command) });
+          }
+        }
+      }
+    }
+
+    for (const g of groups.values()) {
+      if (g.at.length >= o.loopThreshold) {
+        loops.push({
+          name: g.name,
+          hash: g.hash,
+          count: g.at.length,
+          consecutive: g.consecutive,
+          errors: g.errors,
+          input: g.input,
+          at: g.at,
+        });
+      }
+    }
+    fileRow.lines = stats.lines;
+    fileRow.malformed = stats.malformed;
+    fileRow.oversized = stats.oversized;
+    fileRow.truncated = stats.truncated;
+    fileRow.unreadable = stats.unreadable;
+    fileRow.bytesRead = stats.bytes;
+    files.push(fileRow);
+  }
+
+  loops.sort((a, b) => b.count - a.count || b.consecutive - a.consecutive);
+  for (const t of turns) {
+    if (t.durationMs === null && t.firstTs !== null && t.lastTs !== null)
+      t.durationMs = t.lastTs - t.firstTs;
+    delete t.firstTs;
+    delete t.lastTs;
+  }
+
+  let elided = 0;
+  let kept = timeline;
+  if (timeline.length > o.maxEvents) {
+    const half = Math.floor(o.maxEvents / 2);
+    elided = timeline.length - 2 * half;
+    kept = [...timeline.slice(0, half), ...timeline.slice(-half)];
+  }
+
+  return {
+    schema: "transcript-index/1",
+    files,
+    counts: {
+      turns: turns.length,
+      toolCalls: toolCalls.length,
+      loops: loops.length,
+      stalls: stalls.length,
+      idleGaps,
+      compactions: compactions.filter((c) => c.kind === "boundary").length,
+      subagents: subagents.length,
+      errors: errors.length,
+      malformedLines: files.reduce((a, f) => a + f.malformed, 0),
+    },
+    usage,
+    turns,
+    loops,
+    stalls,
+    compactions,
+    subagents,
+    errors,
+    invocations,
+    toolCalls: toolCalls.map(({ group: _group, ts: _ts, ...c }) => c),
+    timeline: kept,
+    timelineElided: elided,
+    redaction: { total: R.total(), byKind: { ...R.byKind } },
+  };
+}
+
+function isPrompt(rec) {
+  if (rec.isMeta || rec.isCompactSummary || rec.isSidechain) return false;
+  const c = rec.message?.content;
+  if (Array.isArray(c) && c.some((b) => b?.type === "tool_result")) return false;
+  const t = textOf(c);
+  return Boolean(t.trim()) && !t.includes("<task-notification>");
+}
+
+// --- finding a run's transcripts -----------------------------------------------
+
+function firstTimestamp(path) {
+  return (async () => {
+    for await (const row of readJsonl(path, { maxBytes: 1024 * 1024 })) {
+      const t = row.record ? tsOf(row.record) : null;
+      if (t !== null) return t;
+    }
+    return null;
+  })();
+}
+
+function readState(dir) {
+  for (const p of [join(dir, "agent-state.json"), join(dir, "artifacts", "agent-state.json")]) {
+    if (!existsSync(p)) continue;
+    const doc = readRegularJson(p, null);
+    if (doc && typeof doc === "object") return { path: p, doc };
+  }
+  return null;
+}
+
+function locateRun(id, root) {
+  const runs = listRuns(root);
+  const variants = new Set(taskIdVariants(id));
+  for (const r of runs) {
+    if (!variants.has(r.taskId)) continue;
+    const s = readState(r.dir);
+    return { run: r, state: s };
+  }
+  const short = String(id).replace(/^#/, "");
+  if (/^\d+$/.test(short)) {
+    for (const r of runs) {
+      const s = readState(r.dir);
+      if (s && Number(s.doc.shortId) === Number(short)) return { run: r, state: s };
+    }
+  }
+  return null;
+}
+
+async function windowMatches(dirs, start, end) {
+  const files = [];
+  for (const d of dirs) {
+    for (const f of listJsonl(d)) {
+      const p = join(d, f);
+      let mtime;
+      try {
+        mtime = statSync(p).mtimeMs;
+      } catch {
+        continue;
+      }
+      if (mtime < start) continue;
+      const first = await firstTimestamp(p);
+      if (first === null || first > end) continue;
+      files.push(p);
+    }
+  }
+  return files;
+}
+
+/**
+ * The session files a run ran in.
+ *
+ * A run launched with a session id (continuous mode, a client that set
+ * MULTI_AGENT_SESSION_ID) has it recorded in agent-state.json, and the file is
+ * `<sessionId>.jsonl` in whichever project directory holds it. An attended run
+ * records none, so the fallback is the sessions whose working directory was
+ * the worktree or the main checkout and whose time span overlaps the run's:
+ * started before the run finished, last written after it started. That match
+ * is a heuristic and is reported as `time-window`.
+ *
+ * @returns {Promise<{taskId:string|null, runDir:string|null, matchedBy:"session"|"time-window"|null, files:string[], reason?:string}>}
+ */
+export async function findRunTranscripts(
+  id,
+  { logsRoot: root = logsRoot(), projectsRoot = defaultProjectsRoot() } = {},
+) {
+  const hit = locateRun(id, root);
+  if (!hit)
+    return {
+      taskId: null,
+      runDir: null,
+      matchedBy: null,
+      files: [],
+      reason: "no run with this id",
+    };
+  const doc = hit.state?.doc || {};
+  const base = { taskId: doc.taskId || hit.run.taskId, runDir: hit.run.dir };
+  const none = (reason) => ({ ...base, matchedBy: null, files: [], reason });
+
+  let projectDirs;
+  try {
+    projectDirs = readdirSync(projectsRoot).map((d) => join(projectsRoot, d));
+  } catch {
+    return none("no transcript directory");
+  }
+
+  if (typeof doc.sessionId === "string" && SAFE_SESSION_ID.test(doc.sessionId)) {
+    const files = projectDirs
+      .map((d) => join(d, `${doc.sessionId}.jsonl`))
+      .filter((p) => existsSync(p));
+    if (files.length) return { ...base, matchedBy: "session", files };
+  }
+
+  const start = Date.parse(doc.startedAt || "");
+  let end = Date.parse(doc.finishedAt || "");
+  if (!Number.isFinite(end)) {
+    try {
+      end = statSync(hit.state.path).mtimeMs;
+    } catch {
+      end = Date.now();
+    }
+  }
+  const cwds = [doc.worktreePath, doc.projectRoot];
+  for (const p of Array.isArray(doc.projects) ? doc.projects : [])
+    cwds.push(p?.worktreePath, p?.projectRoot);
+  const slugs = new Set(cwds.filter((c) => typeof c === "string" && c).map(projectSlug));
+  const dirs = projectDirs.filter((d) => slugs.has(basename(d)));
+  if (!Number.isFinite(start) || !dirs.length)
+    return none("no session id recorded and no transcript directory for the run's checkout");
+
+  const files = await windowMatches(dirs, start, end);
+  return files.length
+    ? { ...base, matchedBy: "time-window", files }
+    : none("no session overlaps the run's time window");
+}
+
+// --- rendering -----------------------------------------------------------------
+
+const dur = (ms) => {
+  if (ms === null || ms === undefined || !Number.isFinite(ms)) return "-";
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m${String(s % 60).padStart(2, "0")}s`;
+  return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+};
+const k = (n) => (n >= 1000 ? `${Math.round(n / 1000)}k` : String(n));
+const citeList = (ats, max = 6) => {
+  const shown = ats.slice(0, max).join(", ");
+  return ats.length > max ? `${shown}, ... (${ats.length - max} more)` : shown;
+};
+
+/** The index as compact text, one section per kind of finding. */
+export function renderIndex(idx) {
+  const L = [];
+  const c = idx.counts;
+  const by = Object.entries(idx.redaction.byKind)
+    .sort((a, b) => b[1] - a[1])
+    .map(([kind, n]) => `${kind} ${n}`)
+    .join(", ");
+  L.push(
+    `transcript index - ${idx.files.length} file(s), ${c.turns} turn(s), ${c.toolCalls} tool call(s), ` +
+      `${c.malformedLines} malformed line(s) skipped, redacted ${idx.redaction.total} item(s)${by ? ` (${by})` : ""}`,
+  );
+  L.push(
+    `usage: in ${k(idx.usage.input)} / out ${k(idx.usage.output)} / cache read ${k(idx.usage.cacheRead)} / cache write ${k(idx.usage.cacheWrite)} over ${idx.usage.messages} message(s)`,
+  );
+  L.push("", "files");
+  for (const f of idx.files) {
+    const flags = [
+      f.sidechain ? "subagent" : null,
+      f.malformed ? `malformed ${f.malformed} (${citeList(f.malformedAt, 4)})` : null,
+      f.oversized ? `oversized ${f.oversized}` : null,
+      f.truncated ? "truncated at the byte cap" : null,
+      f.unreadable ? "unreadable" : null,
+    ].filter(Boolean);
+    L.push(`  ${f.name}  ${f.lines} lines${flags.length ? `  ${flags.join("  ")}` : ""}`);
+  }
+  L.push("", `turns (${idx.turns.length})`);
+  idx.turns.forEach((t, i) => {
+    const u = t.usage;
+    L.push(
+      `  #${i + 1} ${t.at}  ${t.toolCalls} tool(s)  ${t.errors} error(s)  out ${k(u.output)}  peak ctx ${k(u.peakContext)}  ${dur(t.durationMs)}  ${t.prompt ? `"${t.prompt}"` : "(no prompt)"}`,
+    );
+  });
+  L.push("", `loops - identical calls repeated (${idx.loops.length})`);
+  if (!idx.loops.length) L.push("  none");
+  for (const l of idx.loops)
+    L.push(
+      `  ${l.name} x${l.count}  longest streak ${l.consecutive}  errored ${l.errors}  "${l.input}"  at ${citeList(l.at)}`,
+    );
+  L.push(
+    "",
+    `stalls - gaps while working (${idx.stalls.length}; idle gaps between turns: ${idx.counts.idleGaps})`,
+  );
+  if (!idx.stalls.length) L.push("  none");
+  for (const s of idx.stalls)
+    L.push(
+      `  ${dur(s.gapMs)}  ${s.from} -> ${s.to}${s.pendingTool ? `  running: ${s.pendingTool}` : ""}`,
+    );
+  L.push("", `compactions (${idx.counts.compactions})`);
+  if (!idx.compactions.length) L.push("  none");
+  for (const m of idx.compactions)
+    L.push(
+      m.kind === "boundary"
+        ? `  ${m.at}  ${m.trigger}  ${k(m.preTokens ?? 0)} -> ${k(m.postTokens ?? 0)} tokens`
+        : `  ${m.at}  summary turn`,
+    );
+  L.push("", `subagents (${idx.subagents.length})`);
+  if (!idx.subagents.length) L.push("  none");
+  for (const s of idx.subagents)
+    L.push(
+      `  ${s.at}  ${s.agentType}${s.background ? " (background)" : ""}  ${s.status ?? "no result"}  ${dur(s.durationMs)}` +
+        `${s.tokens !== null ? `  ${k(s.tokens)} tokens` : ""}  "${s.description}"` +
+        `${s.resultAt ? `  result ${s.resultAt}` : ""}${s.notifiedAt ? `  notified ${s.notifiedAt}` : ""}`,
+    );
+  L.push("", `errors and denials (${idx.errors.length})`);
+  if (!idx.errors.length) L.push("  none");
+  for (const e of idx.errors.slice(0, 40))
+    L.push(`  ${e.at}  ${e.kind}${e.tool ? ` ${e.tool}` : ""}  "${e.text}"`);
+  if (idx.errors.length > 40) L.push(`  ... ${idx.errors.length - 40} more`);
+  L.push("", `invocations (${idx.invocations.length})`);
+  if (!idx.invocations.length) L.push("  none");
+  for (const v of idx.invocations) L.push(`  ${v.at}  ${v.kind} ${v.name}`);
+  const slow = idx.toolCalls
+    .filter((t) => Number.isFinite(t.durationMs))
+    .sort((a, b) => b.durationMs - a.durationMs)
+    .slice(0, 5);
+  L.push("", "slowest tool calls");
+  if (!slow.length) L.push("  none timed");
+  for (const t of slow) L.push(`  ${dur(t.durationMs)}  ${t.at}  ${t.name}  "${t.input}"`);
+  L.push(
+    "",
+    `timeline (${idx.timeline.length} event(s)${idx.timelineElided ? `, ${idx.timelineElided} in the middle elided` : ""})`,
+  );
+  for (const e of idx.timeline)
+    L.push(
+      `  ${e.at}  ${e.role} ${e.kind}${e.name ? ` ${e.name}` : ""}${e.text ? `  "${e.text}"` : ""}`,
+    );
+  return `${L.join("\n")}\n`;
+}
+
+// --- CLI -----------------------------------------------------------------------
+
+const NUMERIC = {
+  "--max-mb": "maxBytes",
+  "--max-events": "maxEvents",
+  "--loop-threshold": "loopThreshold",
+  "--stall-minutes": "stallMinutes",
+  "--excerpt": "excerpt",
+};
+
+function parseArgs(argv) {
+  const a = { files: [], json: false, locate: false, run: null, opts: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const v = argv[i];
+    if (v === "--json") a.json = true;
+    else if (v === "--locate") a.locate = true;
+    else if (v === "--no-subagents") a.opts.subagents = false;
+    else if (v === "--run") a.run = argv[++i] ?? null;
+    else if (NUMERIC[v]) {
+      const n = Number(argv[++i]);
+      if (!Number.isFinite(n) || n <= 0) return { error: `${v} takes a positive number` };
+      a.opts[NUMERIC[v]] = v === "--max-mb" ? Math.floor(n * 1024 * 1024) : n;
+    } else if (v.startsWith("--")) return { error: `unknown option ${v}` };
+    else a.files.push(v);
+  }
+  if (a.run === "") a.run = null;
+  if (!a.run && !a.files.length) return { error: "give transcript files or --run <id>" };
+  if (a.locate && !a.run) return { error: "--locate needs --run" };
+  return a;
+}
+
+const tilde = (p) => {
+  const h = homedir();
+  return p && h && p.startsWith(`${h}/`) ? `~${p.slice(h.length)}` : p;
+};
+
+async function main() {
+  const a = parseArgs(process.argv.slice(2));
+  if (a.error) {
+    process.stderr.write(
+      `transcript-index: ${a.error}\nusage: transcript-index.mjs <file.jsonl>... | --run <id> [--locate] [--json] [--no-subagents] [--max-mb N] [--max-events N] [--loop-threshold N] [--stall-minutes N] [--excerpt N]\n`,
+    );
+    process.exitCode = 2;
+    return;
+  }
+  let files = a.files;
+  let run = null;
+  if (a.run) {
+    run = await findRunTranscripts(a.run);
+    if (a.locate) {
+      const R = createRedactor();
+      const out = {
+        taskId: run.taskId ? R.clean(run.taskId) : null,
+        runDir: run.runDir ? tilde(run.runDir) : null,
+        matchedBy: run.matchedBy,
+        files: run.files.map((f) => basename(f)),
+        reason: run.reason ?? null,
+      };
+      process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+      process.exitCode = run.files.length ? 0 : 3;
+      return;
+    }
+    files = run.files;
+  }
+  if (!files.length) {
+    process.stderr.write(
+      `transcript-index: nothing to read${run?.reason ? ` (${run.reason})` : ""}\n`,
+    );
+    process.exitCode = 3;
+    return;
+  }
+  const idx = await indexTranscripts(files, a.opts);
+  if (run) idx.run = { taskId: run.taskId, matchedBy: run.matchedBy };
+  if (!idx.files.some((f) => f.lines > 0)) {
+    process.stderr.write("transcript-index: nothing to read (empty or unreadable files)\n");
+    process.exitCode = 3;
+    return;
+  }
+  const out = a.json ? `${JSON.stringify(idx, null, 2)}\n` : renderIndex(idx);
+  try {
+    assertClean(out);
+  } catch (err) {
+    process.stderr.write(`transcript-index: ${err.message}; nothing was printed\n`);
+    process.exitCode = 4;
+    return;
+  }
+  process.stdout.write(out);
+}
+
+if (invokedDirectly(import.meta.url)) runMain("transcript-index", main, { code: 2 });