@gobing-ai/spur 0.4.0 → 0.4.2

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

@@ -2,189 +2,29 @@
 /**
  * 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 Claude Code transcript (resolved like session-timeline,
- * or `--transcript`). One file → one row per state visit; several → one row per run. Each row is
- * windowed by its attempt timestamps and slices the transcript: work, operator wait, tool calls and
- * tokens rendered `<total> / <non-cached>`. A driver-overhead row makes rows sum to the total;
- * `--since <iso>` starts the total at the command's invocation. A window with no host transcript
- * record (a subprocess stage) reads `n/a`, never 0. `--markdown` prints the table. Reporting only:
- * no transcript → `{available:false}` (or one `n/a` line), exit 0. Node builtins only.
+ * (`--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 {
-    accumulate,
-    formatDuration,
-    formatTokenSplit,
-    newAcc,
-    parseRows,
-    promptText,
-    resolveTranscript,
-    type Span,
-    sumSpans,
-    sumTokens,
-    type Tokens,
-    zeroTokens,
-} from '../lib/transcript';
-
-interface ProgressAttempt {
-    startedAt?: string;
-    completedAt?: string;
-}
-
-/** The subset of `spur workflow progress <run-id> --json` the summary reads. */
-export interface Progress {
-    runId: string;
-    workflow?: string;
-    status?: string;
-    states?: { state: string; visit?: number; status?: string; actions?: { attempts?: ProgressAttempt[] }[] }[];
-}
-
-/** A stage row; `toolCalls`/`tokens` are null when the window holds no host transcript record. */
-export interface SummaryRow {
-    stage: string;
-    status: string;
-    workMs: number;
-    waitMs: number;
-    toolCalls: number | null;
-    tokens: Tokens | null;
-    time: string;
-    wait: string;
-    token: string;
-}
-
-export interface RunSummary {
-    available: true;
-    transcript?: string;
-    rows: SummaryRow[];
-    total: SummaryRow;
-    skippedLines: number;
-}
-
-interface Window {
-    stage: string;
-    status: string;
-    start: number;
-    end: number;
-}
-
-function attemptWindow(attempts: ProgressAttempt[]): [number, number] | undefined {
-    const starts = attempts.map((a) => Date.parse(a.startedAt ?? '')).filter((n) => !Number.isNaN(n));
-    const ends = attempts.map((a) => Date.parse(a.completedAt ?? '')).filter((n) => !Number.isNaN(n));
-    return starts.length && ends.length ? [Math.min(...starts), Math.max(...ends)] : undefined;
-}
-
-function summaryRow(stage: string, status: string, span: Span, measured: boolean): SummaryRow {
-    return {
-        stage,
-        status,
-        workMs: span.workMs,
-        waitMs: span.waitMs,
-        toolCalls: measured ? span.toolCalls : null,
-        tokens: measured ? span.tokens : null,
-        time: formatDuration(span.workMs),
-        wait: formatDuration(span.waitMs),
-        token: formatTokenSplit(measured ? span.tokens : null),
-    };
-}
-
-/**
- * dev-run / dev-runall execution summary. One progress file → one row per state visit; several →
- * one row per run. Each window spans its first attempt start → last completion (inclusive) and
- * slices the host transcript; work = window − AskUserQuestion answer time.
- */
-export function buildRunSummary(
-    lines: string[],
-    inputs: { label?: string; progress: Progress }[],
-    since?: string,
-): RunSummary {
-    const windows: Window[] = [];
-    for (const { label, progress } of inputs) {
-        const states = (progress.states ?? []).flatMap((s) => {
-            const w = attemptWindow((s.actions ?? []).flatMap((a) => a.attempts ?? []));
-            return w ? [{ s, w }] : [];
-        });
-        if (!states.length) throw new Error(`progress for run ${progress.runId} has no timed attempts`);
-        if (inputs.length === 1) {
-            for (const { s, w } of states) {
-                const stage = (s.visit ?? 1) > 1 ? `${s.state} (visit ${s.visit})` : s.state;
-                windows.push({ stage, status: s.status ?? '', start: w[0], end: w[1] });
-            }
-        } else {
-            const stage = label ?? `${progress.workflow ?? 'run'} ${progress.runId.slice(0, 8)}`;
-            const start = Math.min(...states.map(({ w }) => w[0]));
-            windows.push({
-                stage,
-                status: progress.status ?? '',
-                start,
-                end: Math.max(...states.map(({ w }) => w[1])),
-            });
-        }
-    }
-    windows.sort((a, b) => a.start - b.start);
-
-    const { rows, skippedLines } = parseRows(lines);
-    const measure = (start: number, end: number): { span: Span; measured: boolean } => {
-        const acc = newAcc(start);
-        for (const [row, ts] of rows)
-            if (ts >= start && ts <= end && promptText(row) === undefined) accumulate(acc, row, ts);
-        const span = {
-            workMs: end - start - acc.askMs,
-            waitMs: acc.askMs,
-            toolCalls: acc.toolIds.size,
-            tokens: sumTokens([...acc.messages.values()]),
-        };
-        return { span, measured: acc.toolIds.size > 0 || acc.messages.size > 0 };
-    };
-
-    const sinceMs = since ? Date.parse(since) : Number.NaN;
-    const totalStart = Number.isNaN(sinceMs) ? Math.min(...windows.map((w) => w.start)) : sinceMs;
-    let totalEnd = Math.max(...windows.map((w) => w.end));
-    // With --since the total runs to the latest host activity, so setup/close work lands in overhead.
-    if (!Number.isNaN(sinceMs)) for (const [, ts] of rows) if (ts >= sinceMs) totalEnd = Math.max(totalEnd, ts);
-
-    const stageRows = windows.map((w) => {
-        const { span, measured } = measure(w.start, w.end);
-        return summaryRow(w.stage, w.status, span, measured);
-    });
-    const totalMeasure = measure(totalStart, totalEnd);
-    const statuses = [...new Set(inputs.map((i) => i.progress.status ?? ''))].join('/');
-    const total = summaryRow('Total', statuses, totalMeasure.span, totalMeasure.measured);
-
-    // Parallel runs overlap, so their rows cannot partition the total: no overhead row then.
-    const overlaps = windows.some((w, i) => i > 0 && w.start < (windows[i - 1]?.end ?? 0));
-    const sum = sumSpans(
-        stageRows.map((r) => ({ ...r, toolCalls: r.toolCalls ?? 0, tokens: r.tokens ?? zeroTokens() })),
-    );
-    const overhead: Span = {
-        workMs: total.workMs - sum.workMs,
-        waitMs: total.waitMs - sum.waitMs,
-        toolCalls: (total.toolCalls ?? 0) - sum.toolCalls,
-        tokens: Object.fromEntries(
-            (Object.keys(sum.tokens) as (keyof Tokens)[]).map((k) => [k, (total.tokens?.[k] ?? 0) - sum.tokens[k]]),
-        ) as Tokens,
-    };
-    if (!overlaps && overhead.workMs > 0)
-        stageRows.push(summaryRow('driver overhead', '', overhead, totalMeasure.measured));
-
-    return { available: true, rows: stageRows, total, skippedLines };
-}
-
-export function renderSummaryMarkdown(summary: RunSummary): string {
-    const line = (r: SummaryRow, bold = false) => {
-        const stage = bold ? `**${r.stage}**` : r.stage;
-        return `| ${stage} | ${r.status} | ${r.time} | ${r.wait} | ${r.toolCalls ?? 'n/a'} | ${r.token} |`;
-    };
-    return [
-        '| Stage | Status | Time | Wait | Tool calls | Token (total / non-cached) |',
-        '| --- | --- | ---: | ---: | ---: | ---: |',
-        ...summary.rows.map((r) => line(r)),
-        line(summary.total, true),
-    ].join('\n');
-}
+    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 ...] [--transcript <path>] [--since <iso>] [--markdown]';
+    'usage: run-summary (--progress [<label>=]<file> [--progress ...] | --rollup [<label>=]<summary.json> [--rollup ...]) [--transcript <path>] [--since <iso>] [--markdown]';
 
 export function main(
     argv: string[],
@@ -196,10 +36,12 @@ export function main(
     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])
@@ -209,6 +51,27 @@ export function main(
             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;
@@ -228,6 +91,7 @@ export function main(
             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`,
         );

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

@@ -14,7 +14,8 @@ 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"]);
+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);
@@ -35,6 +36,20 @@ function formatTokenSplit(t) {
   return `${formatTokens(nonCached + t.cacheRead)} / ${formatTokens(nonCached)}`;
 }
 function promptText(row) {
+  if (row.type === "custom_message") {
+    if (row.display === false)
+      return;
+    const text = typeof row.content === "string" ? row.content.trim() : "";
+    return text === "" ? undefined : text;
+  }
+  if (row.type === "message") {
+    if (row.message?.role !== "user")
+      return;
+    const text = firstTextContent(row);
+    if (text === undefined)
+      return;
+    return skillInvocationPrompt(text) ?? text;
+  }
   if (row.type !== "user" || row.isMeta || row.isCompactSummary)
     return;
   const content = row.message?.content;
@@ -44,6 +59,22 @@ function promptText(row) {
     return;
   return content.find((b) => b.type === "text")?.text;
 }
+function firstTextContent(row) {
+  const content = row.message?.content;
+  if (typeof content === "string")
+    return content;
+  if (!Array.isArray(content))
+    return;
+  return content.find((b) => b.type === "text")?.text;
+}
+function skillInvocationPrompt(text) {
+  const name = /^\s*<skill name="([^"]+)"/.exec(text)?.[1];
+  if (name === undefined)
+    return;
+  const close = text.lastIndexOf("</skill>");
+  const args = close < 0 ? "" : text.slice(close + "</skill>".length).trim();
+  return args === "" ? `/${name}` : `/${name} ${args}`;
+}
 function sumTokens(all) {
   const total = zeroTokens();
   for (const t of all)
@@ -64,10 +95,37 @@ var newAcc = (ts) => ({
   askMs: 0,
   asks: new Map,
   toolIds: new Set,
-  messages: new Map
+  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) {
@@ -88,6 +146,15 @@ function accumulate(acc, row, ts) {
     });
   }
 }
+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;
@@ -105,14 +172,22 @@ function parseRows(lines) {
     if (!Number.isNaN(ts))
       rows.push([row, ts]);
   }
-  return { rows, skippedLines };
+  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)
-    return { ok: false, reason: "no host session id (CLAUDE_CODE_SESSION_ID); pass --transcript <path>" };
+  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))
@@ -146,7 +221,8 @@ function parseGroups(spec, count) {
 }
 function buildTimeline(lines, group) {
   const open = [];
-  const { rows, skippedLines } = parseRows(lines);
+  const { rows, skippedLines, format } = parseRows(lines);
+  const isPi = format === "pi";
   for (const [row, ts] of rows) {
     const prompt = promptText(row);
     if (prompt !== undefined) {
@@ -161,7 +237,7 @@ function buildTimeline(lines, group) {
     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();
-    return render({
+    const span = {
       index: i + 1,
       start: new Date(seg.start).toISOString(),
       prompt: oneLine.length > PROMPT_EXCERPT ? `${oneLine.slice(0, PROMPT_EXCERPT)}\u2026` : oneLine,
@@ -169,15 +245,17 @@ function buildTimeline(lines, group) {
       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({ ...sumSpans(segments), elapsedMs, elapsed: formatDuration(elapsedMs) }),
+    totals: render(isPi ? { ...totals, compactions: segments.reduce((n, s) => n + (s.compactions ?? 0), 0) } : totals),
     skippedLines
   };
   if (group) {
@@ -186,6 +264,19 @@ function buildTimeline(lines, group) {
   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})`;
+  }
+  return `${format} transcript with no operator prompts (${rows.length} rows)`;
+}
 function main(argv, env = getEnvVars(), write = (s) => process.stdout.write(s), projectsRoot, writeErr = (s) => process.stderr.write(s)) {
   let transcript;
   let group;
@@ -210,8 +301,14 @@ function main(argv, env = getEnvVars(), write = (s) => process.stdout.write(s),
     return 0;
   }
   try {
-    const timeline = buildTimeline(readFileSync(resolved.path, "utf8").split(`
-`), group);
+    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;
@@ -223,6 +320,7 @@ function main(argv, env = getEnvVars(), write = (s) => process.stdout.write(s),
 }
 process.exit(main(process.argv.slice(2)));
 export {
+  zeroSegmentReason,
   resolveTranscript,
   parseGroups,
   main,

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

@@ -19,8 +19,10 @@ import {
     newAcc,
     parseRows,
     promptText,
+    type Row,
     resolveTranscript,
     type Span,
+    sniffFormat,
     sumSpans,
     sumTokens,
 } from '../lib/transcript';
@@ -33,9 +35,9 @@ 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 }>[];
+    segments: Rendered<Span & { index: number; start: string; prompt: string; compactions?: number }>[];
     stages?: Rendered<Span & { segments: string }>[];
-    totals: Rendered<Span & { elapsedMs: number; elapsed: string }>;
+    totals: Rendered<Span & { elapsedMs: number; elapsed: string; compactions?: number }>;
     skippedLines: number;
 }
 
@@ -68,7 +70,8 @@ interface Open extends Acc {
 
 export function buildTimeline(lines: string[], group?: string): Timeline {
     const open: Open[] = [];
-    const { rows, skippedLines } = parseRows(lines);
+    const { rows, skippedLines, format } = parseRows(lines);
+    const isPi = format === 'pi';
 
     for (const [row, ts] of rows) {
         const prompt = promptText(row);
@@ -80,28 +83,34 @@ export function buildTimeline(lines: string[], group?: string): Timeline {
         if (seg) accumulate(seg, row, ts); // rows before the first prompt are session preamble
     }
 
-    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();
-        return render({
-            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()]),
-        });
-    });
+    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({ ...sumSpans(segments), elapsedMs, elapsed: formatDuration(elapsedMs) }),
+        totals: render(
+            isPi ? { ...totals, compactions: segments.reduce((n, s) => n + (s.compactions ?? 0), 0) } : totals,
+        ),
         skippedLines,
     };
     if (group) {
@@ -114,6 +123,30 @@ export function buildTimeline(lines: string[], group?: string): 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; an unknown one lists the top-5 row-type census. (1151 R2 removed the pi-only injected
+ * count: pi injects no skill bodies, so a wrapper row is an operator prompt and the class is gone.)
+ */
+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})`;
+    }
+    return `${format} transcript with no operator prompts (${rows.length} rows)`;
+}
+
 export function main(
     argv: string[],
     env: Record<string, string | undefined> = getEnvVars(),
@@ -140,7 +173,12 @@ export function main(
         return 0;
     }
     try {
-        const timeline = buildTimeline(readFileSync(resolved.path, 'utf8').split('\n'), group);
+        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) {