@gobing-ai/spur 0.3.99 → 0.4.1

package/plugins/sp/scripts/run-summary.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env bun
+/**
+ * run-summary — the measured execution summary `/sp:dev-run` and `/sp:dev-runall` print by default
+ * (`--no-summary` skips it). Inputs: one or more `spur workflow progress <run-id> --json` files
+ * (`--progress [<label>=]<file>`) and the host transcript (resolved like session-timeline, or
+ * `--transcript`), OR the close-written per-run summary files (`--rollup [<label>=]<file>`, 1146 R3).
+ * Measurement and rendering live in `../lib/run-summary-core` (ADR-130 glue budget); this script is
+ * argv parsing and dispatch. Reporting only: no transcript or no timed attempts → an `n/a` result,
+ * exit 0. Node builtins only.
+ */
+import { readFileSync } from 'node:fs';
+import { getEnvVars } from '../lib/env';
+import {
+    buildRunSummary,
+    gateFromReceipt,
+    type Progress,
+    type RollupInput,
+    renderRollupMarkdown,
+    renderSummaryMarkdown,
+} from '../lib/run-summary-core';
+import { resolveTranscript } from '../lib/transcript';
+
+// Re-exported so the suite and any consumer keep one import path for the whole surface.
+export * from '../lib/run-summary-core';
+
+export const RUN_SUMMARY_USAGE =
+    'usage: run-summary (--progress [<label>=]<file> [--progress ...] | --rollup [<label>=]<summary.json> [--rollup ...]) [--transcript <path>] [--since <iso>] [--markdown]';
+
+export function main(
+    argv: string[],
+    env: Record<string, string | undefined> = getEnvVars(),
+    write: (s: string) => void = (s) => process.stdout.write(s),
+    projectsRoot?: string,
+): number {
+    let transcript: string | undefined;
+    let since: string | undefined;
+    let markdown = false;
+    const progressArgs: string[] = [];
+    const rollupArgs: string[] = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--transcript' && argv[i + 1]) transcript = argv[++i];
+        else if (arg === '--progress' && argv[i + 1]) progressArgs.push(argv[++i] as string);
+        else if (arg === '--rollup' && argv[i + 1]) rollupArgs.push(argv[++i] as string);
+        else if (arg === '--since' && argv[i + 1]) since = argv[++i];
+        else if (arg === '--markdown') markdown = true;
+        else if (arg === '--spur-bin' && argv[i + 1])
+            i++; // 0482 R2: accepted, unused (no spur calls)
+        else {
+            process.stderr.write(`${RUN_SUMMARY_USAGE}\n`);
+            return 2;
+        }
+    }
+    // 1146 AC5: --rollup is a different mode — it reads close-written summary files and never
+    // re-measures, so combining it with a measurement source is a usage error.
+    if (rollupArgs.length > 0 && (progressArgs.length > 0 || since !== undefined || transcript !== undefined)) {
+        process.stderr.write(`${RUN_SUMMARY_USAGE}\n`);
+        return 2;
+    }
+    if (rollupArgs.length > 0) {
+        try {
+            const inputs: RollupInput[] = rollupArgs.map((arg) => {
+                const eq = arg.indexOf('=');
+                const [label, file] = eq > 0 ? [arg.slice(0, eq), arg.slice(eq + 1)] : [undefined, arg];
+                const summary = JSON.parse(readFileSync(file as string, 'utf8')) as RollupInput['summary'];
+                return { label: label ?? summary.runId ?? (file as string), summary };
+            });
+            write(`${renderRollupMarkdown(inputs)}\n`);
+            return 0;
+        } catch (error) {
+            process.stderr.write(`run-summary: ${(error as Error).message}\n`);
+            return 2;
+        }
+    }
+    if (!progressArgs.length) {
+        process.stderr.write(`${RUN_SUMMARY_USAGE}\n`);
+        return 2;
+    }
+    const resolved = resolveTranscript(env, projectsRoot, transcript);
+    if (!resolved.ok) {
+        const out = markdown
+            ? `Execution summary: n/a (${resolved.reason})`
+            : JSON.stringify({ available: false, reason: resolved.reason });
+        write(`${out}\n`);
+        return 0;
+    }
+    try {
+        const inputs = progressArgs.map((arg) => {
+            const eq = arg.indexOf('=');
+            const [label, file] = eq > 0 ? [arg.slice(0, eq), arg.slice(eq + 1)] : [undefined, arg];
+            return { label, progress: JSON.parse(readFileSync(file, 'utf8')) as Progress };
+        });
+        const summary = buildRunSummary(readFileSync(resolved.path, 'utf8').split('\n'), inputs, since);
+        summary.gate = gateFromReceipt(process.cwd(), inputs[0]?.progress.runId ?? '');
+        write(
+            `${markdown ? renderSummaryMarkdown(summary) : JSON.stringify({ ...summary, transcript: resolved.path })}\n`,
+        );
+        return 0;
+    } catch (error) {
+        process.stderr.write(`run-summary: ${(error as Error).message}\n`);
+        return 2;
+    }
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)));

package/plugins/sp/scripts/session-timeline.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/session-timeline.ts
+import { readFileSync } from "fs";
+
+// plugins/sp/lib/env.ts
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/lib/transcript.ts
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var SESSION_ID = /^[A-Za-z0-9_-]+$/;
+var OPERATOR_TOOLS = new Set(["AskUserQuestion", "ask_user_question"]);
+var PI_ROLES = new Set(["user", "assistant", "toolResult"]);
+var zeroTokens = () => ({ input: 0, cacheCreate: 0, cacheRead: 0, output: 0 });
+function formatDuration(ms) {
+  const s = Math.round(ms / 1000);
+  const h = Math.floor(s / 3600);
+  const m = Math.floor(s % 3600 / 60);
+  const ss = String(s % 60).padStart(2, "0");
+  return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${ss}` : `${m}:${ss}`;
+}
+function formatTokens(n) {
+  if (n >= 999500)
+    return `${(n / 1e6).toFixed(1)}M`;
+  return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n);
+}
+function formatTokenSplit(t) {
+  if (!t)
+    return "n/a";
+  const nonCached = t.input + t.cacheCreate + t.output;
+  return `${formatTokens(nonCached + t.cacheRead)} / ${formatTokens(nonCached)}`;
+}
+function promptText(row) {
+  if (row.type === "message") {
+    if (row.message?.role !== "user")
+      return;
+    if (isInjectedPrompt(row))
+      return;
+    const content2 = row.message.content;
+    if (typeof content2 === "string")
+      return content2;
+    if (!Array.isArray(content2))
+      return;
+    return content2.find((b) => b.type === "text")?.text;
+  }
+  if (row.type !== "user" || row.isMeta || row.isCompactSummary)
+    return;
+  const content = row.message?.content;
+  if (typeof content === "string")
+    return content;
+  if (!Array.isArray(content) || content.some((b) => b.type === "tool_result"))
+    return;
+  return content.find((b) => b.type === "text")?.text;
+}
+function isInjectedPrompt(row) {
+  if (row.type !== "message" || row.message?.role !== "user")
+    return false;
+  const content = row.message.content;
+  const text = typeof content === "string" ? content : Array.isArray(content) ? content.find((b) => b.type === "text")?.text : undefined;
+  return typeof text === "string" && text.replace(/^\s+/, "").startsWith('<skill name="');
+}
+function sumTokens(all) {
+  const total = zeroTokens();
+  for (const t of all)
+    for (const k of Object.keys(total))
+      total[k] += t[k];
+  return total;
+}
+function sumSpans(spans) {
+  return {
+    workMs: spans.reduce((n, s) => n + s.workMs, 0),
+    waitMs: spans.reduce((n, s) => n + s.waitMs, 0),
+    toolCalls: spans.reduce((n, s) => n + s.toolCalls, 0),
+    tokens: sumTokens(spans.map((s) => s.tokens))
+  };
+}
+var newAcc = (ts) => ({
+  last: ts,
+  askMs: 0,
+  asks: new Map,
+  toolIds: new Set,
+  messages: new Map,
+  compactions: 0
+});
+function accumulate(acc, row, ts) {
+  acc.last = Math.max(acc.last, ts);
+  if (row.type === "message") {
+    const m = row.message;
+    if (m?.role === "assistant") {
+      const blocks2 = Array.isArray(m.content) ? m.content : [];
+      for (const b of blocks2) {
+        if (b.type === "toolCall" && b.id) {
+          acc.toolIds.add(b.id);
+          if (b.name && OPERATOR_TOOLS.has(b.name))
+            acc.asks.set(b.id, ts);
+        }
+      }
+      const u2 = m.usage;
+      if (u2 && row.id)
+        acc.messages.set(row.id, {
+          input: u2.input ?? 0,
+          cacheCreate: u2.cacheWrite ?? 0,
+          cacheRead: u2.cacheRead ?? 0,
+          output: u2.output ?? 0
+        });
+    } else if (m?.role === "toolResult" && m.toolCallId && acc.asks.has(m.toolCallId)) {
+      acc.askMs += ts - (acc.asks.get(m.toolCallId) ?? ts);
+    }
+    return;
+  }
+  if (row.type === "compaction")
+    acc.compactions++;
+  const blocks = Array.isArray(row.message?.content) ? row.message.content : [];
+  for (const b of blocks) {
+    if (b.type === "tool_use" && b.id) {
+      acc.toolIds.add(b.id);
+      if (b.name && OPERATOR_TOOLS.has(b.name))
+        acc.asks.set(b.id, ts);
+    } else if (b.type === "tool_result" && b.tool_use_id && acc.asks.has(b.tool_use_id)) {
+      acc.askMs += ts - (acc.asks.get(b.tool_use_id) ?? ts);
+    }
+  }
+  const u = row.message?.usage;
+  if (row.type === "assistant" && u && row.message?.id) {
+    acc.messages.set(row.message.id, {
+      input: u.input_tokens ?? 0,
+      cacheCreate: u.cache_creation_input_tokens ?? 0,
+      cacheRead: u.cache_read_input_tokens ?? 0,
+      output: u.output_tokens ?? 0
+    });
+  }
+}
+function sniffFormat(rows) {
+  for (const row of rows) {
+    if (row.type === "message" && PI_ROLES.has(row.message?.role ?? ""))
+      return "pi";
+    if (row.type === "user" || row.type === "assistant")
+      return "claude";
+  }
+  return "unknown";
+}
+function parseRows(lines) {
+  const rows = [];
+  let skippedLines = 0;
+  for (const line of lines) {
+    if (!line.trim())
+      continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      skippedLines++;
+      continue;
+    }
+    const ts = row.timestamp ? Date.parse(row.timestamp) : Number.NaN;
+    if (!Number.isNaN(ts))
+      rows.push([row, ts]);
+  }
+  return { rows, skippedLines, format: sniffFormat(rows.map(([r]) => r)) };
+}
+function resolveTranscript(env, projectsRoot = join(homedir(), ".claude", "projects"), override) {
+  if (override)
+    return existsSync(override) ? { ok: true, path: override } : { ok: false, reason: "no transcript" };
+  const id = env.CLAUDE_CODE_SESSION_ID;
+  if (!id) {
+    const piFile = env.PI_SESSION_FILE;
+    if (piFile !== undefined && piFile !== "") {
+      return existsSync(piFile) ? { ok: true, path: piFile } : { ok: false, reason: `PI_SESSION_FILE ${piFile} does not exist` };
+    }
+    return {
+      ok: false,
+      reason: "no host session id; pass --transcript <path> (pi: ~/.pi/agent/sessions/<cwd-slug>/<file>.jsonl, " + "or set PI_SESSION_FILE)"
+    };
+  }
+  if (!SESSION_ID.test(id))
+    return { ok: false, reason: "refusing a session id with path characters" };
+  if (!existsSync(projectsRoot))
+    return { ok: false, reason: `no transcript root ${projectsRoot}` };
+  for (const dir of readdirSync(projectsRoot)) {
+    const path = join(projectsRoot, dir, `${id}.jsonl`);
+    if (existsSync(path))
+      return { ok: true, path };
+  }
+  return { ok: false, reason: `no transcript for session ${id}` };
+}
+
+// plugins/sp/scripts/session-timeline.ts
+var PROMPT_EXCERPT = 80;
+var render = (span) => ({
+  ...span,
+  work: formatDuration(span.workMs),
+  wait: formatDuration(span.waitMs),
+  token: formatTokenSplit(span.tokens)
+});
+function parseGroups(spec, count) {
+  let next = 1;
+  return spec.split(",").map((part) => {
+    const [a = Number.NaN, b = a] = part.trim().split("-").map(Number);
+    if (!Number.isInteger(a) || !Number.isInteger(b) || a < next || b < a || b > count) {
+      throw new Error(`invalid --group "${part}" (segments 1-${count}, ascending, no overlap)`);
+    }
+    next = b + 1;
+    return [a, b];
+  });
+}
+function buildTimeline(lines, group) {
+  const open = [];
+  const { rows, skippedLines, format } = parseRows(lines);
+  const isPi = format === "pi";
+  let injectedPrompts = 0;
+  for (const [row, ts] of rows) {
+    if (isPi && isInjectedPrompt(row)) {
+      injectedPrompts++;
+      const injectedSeg = open.at(-1);
+      if (injectedSeg)
+        accumulate(injectedSeg, row, ts);
+      continue;
+    }
+    const prompt = promptText(row);
+    if (prompt !== undefined) {
+      open.push({ start: ts, prompt, ...newAcc(ts) });
+      continue;
+    }
+    const seg = open.at(-1);
+    if (seg)
+      accumulate(seg, row, ts);
+  }
+  const segments = open.map((seg, i) => {
+    const next = open[i + 1]?.start;
+    const idle = next === undefined ? 0 : Math.max(0, next - seg.last);
+    const oneLine = seg.prompt.replace(/\s+/g, " ").trim();
+    const span = {
+      index: i + 1,
+      start: new Date(seg.start).toISOString(),
+      prompt: oneLine.length > PROMPT_EXCERPT ? `${oneLine.slice(0, PROMPT_EXCERPT)}\u2026` : oneLine,
+      workMs: seg.last - seg.start - seg.askMs,
+      waitMs: idle + seg.askMs,
+      toolCalls: seg.toolIds.size,
+      tokens: sumTokens([...seg.messages.values()])
+    };
+    return render(isPi ? { ...span, compactions: seg.compactions } : span);
+  });
+  const first = open[0];
+  const last = open.at(-1);
+  const elapsedMs = first && last ? last.last - first.start : 0;
+  const totals = { ...sumSpans(segments), elapsedMs, elapsed: formatDuration(elapsedMs) };
+  const timeline = {
+    available: true,
+    segments,
+    totals: render(isPi ? { ...totals, compactions: segments.reduce((n, s) => n + (s.compactions ?? 0), 0) } : totals),
+    skippedLines,
+    ...isPi ? { injectedPrompts } : {}
+  };
+  if (group) {
+    timeline.stages = parseGroups(group, segments.length).map(([a, b]) => render({ ...sumSpans(segments.slice(a - 1, b)), segments: a === b ? `${a}` : `${a}-${b}` }));
+  }
+  return timeline;
+}
+var SESSION_TIMELINE_USAGE = 'usage: session-timeline [--transcript <path>] [--group "1-3,4,..."]';
+function zeroSegmentReason(rows) {
+  const format = sniffFormat(rows.map(([r]) => r));
+  if (format === "unknown") {
+    const counts = new Map;
+    for (const [r] of rows) {
+      const kind = typeof r.type === "string" && r.type !== "" ? r.type : "(untyped)";
+      counts.set(kind, (counts.get(kind) ?? 0) + 1);
+    }
+    const census = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 5).map(([kind, n]) => `${kind} ${n}`).join(", ");
+    return `unrecognized transcript format (row types: ${census})`;
+  }
+  const injected = rows.filter(([r]) => isInjectedPrompt(r)).length;
+  return `${format} transcript with no operator prompts (${rows.length} rows, ${injected} injected)`;
+}
+function main(argv, env = getEnvVars(), write = (s) => process.stdout.write(s), projectsRoot, writeErr = (s) => process.stderr.write(s)) {
+  let transcript;
+  let group;
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--transcript" && argv[i + 1])
+      transcript = argv[++i];
+    else if (arg === "--group" && argv[i + 1])
+      group = argv[++i];
+    else if (arg === "--spur-bin" && argv[i + 1])
+      i++;
+    else {
+      writeErr(`${SESSION_TIMELINE_USAGE}
+`);
+      return 2;
+    }
+  }
+  const resolved = resolveTranscript(env, projectsRoot, transcript);
+  if (!resolved.ok) {
+    write(`${JSON.stringify({ available: false, reason: resolved.reason })}
+`);
+    return 0;
+  }
+  try {
+    const lines = readFileSync(resolved.path, "utf8").split(`
+`);
+    const timeline = buildTimeline(lines, group);
+    if (timeline.segments.length === 0) {
+      write(`${JSON.stringify({ available: false, reason: zeroSegmentReason(parseRows(lines).rows) })}
+`);
+      return 0;
+    }
+    write(`${JSON.stringify({ ...timeline, transcript: resolved.path })}
+`);
+    return 0;
+  } catch (error) {
+    writeErr(`session-timeline: ${error.message}
+`);
+    return 2;
+  }
+}
+process.exit(main(process.argv.slice(2)));
+export {
+  zeroSegmentReason,
+  resolveTranscript,
+  parseGroups,
+  main,
+  formatTokens,
+  formatTokenSplit,
+  formatDuration,
+  buildTimeline,
+  SESSION_TIMELINE_USAGE
+};

package/plugins/sp/scripts/session-timeline.ts

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+/**
+ * session-timeline — measured time and token evidence for the sp:session-review Time breakdown.
+ * The visible conversation carries no timestamps or usage (so the table read `n/a`); the host
+ * transcript carries both. Reads the active Claude Code JSONL read-only
+ * (`~/.claude/projects/<slug>/<CLAUDE_CODE_SESSION_ID>.jsonl`, or `--transcript`), one segment per
+ * operator prompt: work = prompt → last activity; wait = idle until the next prompt plus time spent
+ * answering an AskUserQuestion; tokens counted once per message id and rendered `<total> /
+ * <non-cached>`. `--group "1-3,4"` sums segments into stages. No transcript → `{available:false}`,
+ * exit 0, and the review renders `n/a` instead of guessing. Node builtins only (standalone plugin).
+ */
+import { readFileSync } from 'node:fs';
+import { getEnvVars } from '../lib/env';
+import {
+    type Acc,
+    accumulate,
+    formatDuration,
+    formatTokenSplit,
+    isInjectedPrompt,
+    newAcc,
+    parseRows,
+    promptText,
+    type Row,
+    resolveTranscript,
+    type Span,
+    sniffFormat,
+    sumSpans,
+    sumTokens,
+} from '../lib/transcript';
+
+export { formatDuration, formatTokenSplit, formatTokens, resolveTranscript } from '../lib/transcript';
+
+/** A span plus its `M:SS` / `H:MM:SS` and token renderings, so the review table needs no arithmetic. */
+export type Rendered<T> = T & { work: string; wait: string; token: string };
+
+export interface Timeline {
+    available: true;
+    transcript?: string;
+    segments: Rendered<Span & { index: number; start: string; prompt: string; compactions?: number }>[];
+    stages?: Rendered<Span & { segments: string }>[];
+    totals: Rendered<Span & { elapsedMs: number; elapsed: string; compactions?: number }>;
+    skippedLines: number;
+    /** pi only (1138 R2): skill-injected user bodies counted as activity, never as segments. */
+    injectedPrompts?: number;
+}
+
+const PROMPT_EXCERPT = 80;
+
+const render = <T extends Span>(span: T): Rendered<T> => ({
+    ...span,
+    work: formatDuration(span.workMs),
+    wait: formatDuration(span.waitMs),
+    token: formatTokenSplit(span.tokens),
+});
+
+/** "1-3,4" → [[1,3],[4,4]]; 1-based, ascending, in range, non-overlapping. */
+export function parseGroups(spec: string, count: number): [number, number][] {
+    let next = 1;
+    return spec.split(',').map((part) => {
+        const [a = Number.NaN, b = a] = part.trim().split('-').map(Number);
+        if (!Number.isInteger(a) || !Number.isInteger(b) || a < next || b < a || b > count) {
+            throw new Error(`invalid --group "${part}" (segments 1-${count}, ascending, no overlap)`);
+        }
+        next = b + 1;
+        return [a, b] as [number, number];
+    });
+}
+
+interface Open extends Acc {
+    start: number;
+    prompt: string;
+}
+
+export function buildTimeline(lines: string[], group?: string): Timeline {
+    const open: Open[] = [];
+    const { rows, skippedLines, format } = parseRows(lines);
+    const isPi = format === 'pi';
+    let injectedPrompts = 0;
+
+    for (const [row, ts] of rows) {
+        // 1138 R2: an injected skill body is activity, not a prompt — accumulate it into the open
+        // segment (its tools and usage are real work) and count it, never open a segment.
+        if (isPi && isInjectedPrompt(row)) {
+            injectedPrompts++;
+            const injectedSeg = open.at(-1);
+            if (injectedSeg) accumulate(injectedSeg, row, ts);
+            continue;
+        }
+        const prompt = promptText(row);
+        if (prompt !== undefined) {
+            open.push({ start: ts, prompt, ...newAcc(ts) });
+            continue;
+        }
+        const seg = open.at(-1);
+        if (seg) accumulate(seg, row, ts); // rows before the first prompt are session preamble
+    }
+
+    const segments = open.map(
+        (seg, i): Rendered<Span & { index: number; start: string; prompt: string; compactions?: number }> => {
+            const next = open[i + 1]?.start;
+            const idle = next === undefined ? 0 : Math.max(0, next - seg.last);
+            const oneLine = seg.prompt.replace(/\s+/g, ' ').trim();
+            const span = {
+                index: i + 1,
+                start: new Date(seg.start).toISOString(),
+                prompt: oneLine.length > PROMPT_EXCERPT ? `${oneLine.slice(0, PROMPT_EXCERPT)}…` : oneLine,
+                workMs: seg.last - seg.start - seg.askMs,
+                waitMs: idle + seg.askMs,
+                toolCalls: seg.toolIds.size,
+                tokens: sumTokens([...seg.messages.values()]),
+            };
+            return render(isPi ? { ...span, compactions: seg.compactions } : span);
+        },
+    );
+
+    const first = open[0];
+    const last = open.at(-1);
+    const elapsedMs = first && last ? last.last - first.start : 0;
+    const totals = { ...sumSpans(segments), elapsedMs, elapsed: formatDuration(elapsedMs) };
+    const timeline: Timeline = {
+        available: true,
+        segments,
+        totals: render(
+            isPi ? { ...totals, compactions: segments.reduce((n, s) => n + (s.compactions ?? 0), 0) } : totals,
+        ),
+        skippedLines,
+        // Emitted only for pi, as `compactions` is, so Claude output is unchanged (1138 R2).
+        ...(isPi ? { injectedPrompts } : {}),
+    };
+    if (group) {
+        timeline.stages = parseGroups(group, segments.length).map(([a, b]) =>
+            render({ ...sumSpans(segments.slice(a - 1, b)), segments: a === b ? `${a}` : `${a}-${b}` }),
+        );
+    }
+    return timeline;
+}
+
+export const SESSION_TIMELINE_USAGE = 'usage: session-timeline [--transcript <path>] [--group "1-3,4,..."]';
+
+/**
+ * 1138 R3: a zero-segment result must say WHAT was detected, so an unparseable-but-recognised
+ * transcript can never read as an authoritative all-zero timeline. A known format names the
+ * row count and the injected count; an unknown one lists the top-5 row-type census.
+ */
+export function zeroSegmentReason(rows: [Row, number][]): string {
+    const format = sniffFormat(rows.map(([r]) => r));
+    if (format === 'unknown') {
+        const counts = new Map<string, number>();
+        for (const [r] of rows) {
+            const kind = typeof r.type === 'string' && r.type !== '' ? r.type : '(untyped)';
+            counts.set(kind, (counts.get(kind) ?? 0) + 1);
+        }
+        const census = [...counts.entries()]
+            .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+            .slice(0, 5)
+            .map(([kind, n]) => `${kind} ${n}`)
+            .join(', ');
+        return `unrecognized transcript format (row types: ${census})`;
+    }
+    const injected = rows.filter(([r]) => isInjectedPrompt(r)).length;
+    return `${format} transcript with no operator prompts (${rows.length} rows, ${injected} injected)`;
+}
+
+export function main(
+    argv: string[],
+    env: Record<string, string | undefined> = getEnvVars(),
+    write: (s: string) => void = (s) => process.stdout.write(s),
+    projectsRoot?: string,
+    writeErr: (s: string) => void = (s) => process.stderr.write(s),
+): number {
+    let transcript: string | undefined;
+    let group: string | undefined;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--transcript' && argv[i + 1]) transcript = argv[++i];
+        else if (arg === '--group' && argv[i + 1]) group = argv[++i];
+        else if (arg === '--spur-bin' && argv[i + 1])
+            i++; // 0482 R2: accepted, unused (no spur calls)
+        else {
+            writeErr(`${SESSION_TIMELINE_USAGE}\n`);
+            return 2;
+        }
+    }
+    const resolved = resolveTranscript(env, projectsRoot, transcript);
+    if (!resolved.ok) {
+        write(`${JSON.stringify({ available: false, reason: resolved.reason })}\n`);
+        return 0;
+    }
+    try {
+        const lines = readFileSync(resolved.path, 'utf8').split('\n');
+        const timeline = buildTimeline(lines, group);
+        if (timeline.segments.length === 0) {
+            write(`${JSON.stringify({ available: false, reason: zeroSegmentReason(parseRows(lines).rows) })}\n`);
+            return 0;
+        }
+        write(`${JSON.stringify({ ...timeline, transcript: resolved.path })}\n`);
+        return 0;
+    } catch (error) {
+        writeErr(`session-timeline: ${(error as Error).message}\n`);
+        return 2;
+    }
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)));