pi-daddy 0.41.0 → 0.43.0

package/src/products/episode-outcomes.ts

@@ -0,0 +1,317 @@
+/** Compute durable episode outcomes from Git, CI metadata, and the next recorded operator turn. */
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { appendLedgerEvent, buildEpisodeOutcomeEvent } from "../governance/ledger.ts";
+import { readRecords } from "../governance/record.ts";
+import { isEpisodeId } from "../kernel/episode-id.ts";
+import { readActivityContent, type ContentReference } from "./activity-timeline.ts";
+
+const execFileAsync = promisify(execFile);
+const FORTY_EIGHT_HOURS = 48 * 60 * 60 * 1_000;
+const TWENTY_FOUR_HOURS = 24 * 60 * 60 * 1_000;
+export const CORRECTION_PREFIXES = ["no,", "that's wrong", "undo", "revert"] as const;
+
+type CiSignal = "green" | "red" | "none";
+type OutcomeLabel = "positive" | "negative" | "unknown";
+export interface EpisodeOutcomeSignals {
+  episodeId: string;
+  commit: string;
+  survived: boolean;
+  ci: CiSignal;
+  amended: boolean;
+  corrected: boolean;
+  label: OutcomeLabel;
+}
+interface CommitFact {
+  sha: string;
+  parents: string[];
+  authoredMs: number;
+  message: string;
+  episodes: string[];
+}
+export interface GitCommandResult {
+  stdout: string;
+  code: number;
+}
+export type GitRunner = (args: string[]) => Promise<GitCommandResult>;
+export type GhRunner = (sha: string) => Promise<string | null>;
+
+async function command(cwd: string, file: string, args: string[]): Promise<GitCommandResult> {
+  try {
+    const result = await execFileAsync(file, args, { cwd, maxBuffer: 32 * 1024 * 1024 });
+    return { stdout: result.stdout, code: 0 };
+  } catch (error) {
+    const failure = error as { stdout?: string; code?: number | string };
+    return { stdout: failure.stdout ?? "", code: typeof failure.code === "number" ? failure.code : 127 };
+  }
+}
+
+function commitsFromLog(log: string): CommitFact[] {
+  const commits: CommitFact[] = [];
+  for (const entry of log.split("\u001e")) {
+    const [sha, parentText, authored, ...messageParts] = entry.trim().split("\u001f");
+    if (!/^[a-f0-9]{40}$/i.test(sha ?? "")) continue;
+    const parents = parentText.split(" ").filter((parent) => /^[a-f0-9]{40}$/i.test(parent));
+    const message = messageParts.join("\u001f");
+    const episodes = [...message.matchAll(/^Pi-Episode:\s*(\S+)\s*$/gim)]
+      .map((match) => (match[1].startsWith("episode:") ? match[1] : `episode:${match[1]}`))
+      .filter(isEpisodeId);
+    commits.push({ sha, parents, authoredMs: Date.parse(authored), message, episodes });
+  }
+  return commits;
+}
+
+function absentOrThrow(result: GitCommandResult, operation: string): boolean {
+  if (result.code === 1) return true;
+  if (result.code !== 0) throw new Error(`pi-daddy outcomes: git ${operation} failed`);
+  return false;
+}
+
+async function defaultBranch(runGit: GitRunner): Promise<string> {
+  const remote = await runGit(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+  if (remote.code === 0 && remote.stdout.trim()) return remote.stdout.trim();
+  absentOrThrow(remote, "symbolic-ref");
+  for (const name of ["main", "master"]) {
+    const local = await runGit(["show-ref", "--verify", "--quiet", `refs/heads/${name}`]);
+    if (local.code === 0) return name;
+    absentOrThrow(local, "show-ref");
+  }
+  const current = await runGit(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  if (current.code === 0 && current.stdout.trim()) return current.stdout.trim();
+  absentOrThrow(current, "symbolic-ref");
+  throw new Error("pi-daddy outcomes: no default branch could be resolved");
+}
+
+export async function gitIsAncestor(
+  cwd: string,
+  older: string,
+  newer: string,
+  runGit: GitRunner = (args) => command(cwd, "git", args),
+): Promise<boolean> {
+  const result = await runGit(["merge-base", "--is-ancestor", older, newer]);
+  if (result.code === 0) return true;
+  if (result.code === 1) return false;
+  throw new Error(`pi-daddy outcomes: git merge-base failed for ${older} and ${newer}`);
+}
+
+async function filesFor(runGit: GitRunner, sha: string): Promise<Set<string>> {
+  const result = await runGit(["diff-tree", "--root", "--no-commit-id", "--name-only", "-r", sha]);
+  if (result.code !== 0) throw new Error(`pi-daddy outcomes: could not read files for ${sha}`);
+  return new Set(result.stdout.split("\n").filter(Boolean));
+}
+
+async function diffFor(runGit: GitRunner, from: string, to: string): Promise<string> {
+  const result = await runGit(["diff", "--binary", from, to, "--"]);
+  if (result.code !== 0) throw new Error(`pi-daddy outcomes: git diff failed for ${from} and ${to}`);
+  return result.stdout;
+}
+
+async function commitDiff(runGit: GitRunner, commit: CommitFact): Promise<string> {
+  if (commit.parents[0]) return diffFor(runGit, commit.parents[0], commit.sha);
+  const result = await runGit(["show", "--format=", "--binary", "--root", commit.sha, "--"]);
+  if (result.code !== 0) throw new Error(`pi-daddy outcomes: git show failed for ${commit.sha}`);
+  return result.stdout;
+}
+
+function commitChildren(commits: CommitFact[]): Map<string, string[]> {
+  const children = new Map<string, string[]>();
+  for (const commit of commits)
+    for (const parent of commit.parents) children.set(parent, [...(children.get(parent) ?? []), commit.sha]);
+  return children;
+}
+
+function laterDescendants(
+  candidate: CommitFact,
+  commits: Map<string, CommitFact>,
+  children: Map<string, string[]>,
+): CommitFact[] {
+  const later: CommitFact[] = [];
+  const pending = [...(children.get(candidate.sha) ?? [])];
+  const visited = new Set<string>();
+  while (pending.length > 0) {
+    const sha = pending.pop()!;
+    if (visited.has(sha)) continue;
+    visited.add(sha);
+    const commit = commits.get(sha);
+    if (commit) later.push(commit);
+    pending.push(...(children.get(sha) ?? []));
+  }
+  return later;
+}
+
+function cached<T>(cache: Map<string, Promise<T>>, key: string, load: () => Promise<T>): Promise<T> {
+  const existing = cache.get(key);
+  if (existing) return existing;
+  const value = load();
+  cache.set(key, value);
+  return value;
+}
+
+async function wasReverted(
+  runGit: GitRunner,
+  candidate: CommitFact,
+  later: CommitFact[],
+  commitDiffs: Map<string, Promise<string>>,
+  inverseDiffs: Map<string, Promise<string>>,
+): Promise<boolean> {
+  const named = later.some((commit) => {
+    const lower = commit.message.toLowerCase();
+    return lower.includes(candidate.sha.toLowerCase()) || lower.includes(candidate.sha.slice(0, 12).toLowerCase());
+  });
+  if (named) return true;
+  const original = await cached(commitDiffs, candidate.sha, () => commitDiff(runGit, candidate));
+  for (const commit of later) {
+    const inverse = await cached(inverseDiffs, commit.sha, () => diffFor(runGit, commit.sha, `${commit.sha}^`));
+    if (inverse === original) return true;
+  }
+  return false;
+}
+
+async function wasAmended(
+  runGit: GitRunner,
+  candidate: CommitFact,
+  later: CommitFact[],
+  filesByCommit: Map<string, Promise<Set<string>>>,
+): Promise<boolean> {
+  const files = await cached(filesByCommit, candidate.sha, () => filesFor(runGit, candidate.sha));
+  if (files.size === 0) return false;
+  for (const commit of later) {
+    const elapsed = commit.authoredMs - candidate.authoredMs;
+    if (elapsed < 0 || elapsed > TWENTY_FOUR_HOURS) continue;
+    if (!/^(fix|fixup|amend)(?:\b|:)/i.test(commit.message.trim())) continue;
+    const touched = await cached(filesByCommit, commit.sha, () => filesFor(runGit, commit.sha));
+    if ([...touched].some((file) => files.has(file))) return true;
+  }
+  return false;
+}
+
+async function defaultGh(cwd: string, sha: string): Promise<string | null> {
+  if ((await command(cwd, "gh", ["--version"])).code !== 0) return null;
+  const result = await command(cwd, "gh", ["run", "list", "--commit", sha, "--json", "conclusion", "--limit", "100"]);
+  if (result.code !== 0) throw new Error(`pi-daddy outcomes: gh run list failed for ${sha}`);
+  return result.stdout;
+}
+
+function ciFrom(value: string | null): CiSignal {
+  if (value === null) return "none";
+  try {
+    const conclusions = (JSON.parse(value) as Array<{ conclusion?: unknown }>).map((run) =>
+      String(run.conclusion ?? ""),
+    );
+    if (
+      conclusions.some((item) =>
+        ["failure", "cancelled", "timed_out", "action_required", "startup_failure"].includes(item),
+      )
+    )
+      return "red";
+    return conclusions.some((item) => ["success", "neutral", "skipped"].includes(item)) ? "green" : "none";
+  } catch {
+    throw new Error("pi-daddy outcomes: gh run list returned invalid JSON");
+  }
+}
+
+async function corrections(activityPath: string): Promise<Set<string>> {
+  let text: string;
+  try {
+    text = await readFile(activityPath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return new Set();
+    throw error;
+  }
+  const parsed = readRecords(text);
+  if (parsed.damage) throw new Error(`activity ledger damaged at line ${parsed.damage.line}: ${parsed.damage.reason}`);
+  const turns = new Map<string, Array<{ at: number; prompt?: ContentReference }>>();
+  for (const record of parsed.records) {
+    const body = record.body as Record<string, unknown>;
+    if (record.kind !== "activity" || body.kind !== "task_started" || body.agentId !== undefined) continue;
+    if (!isEpisodeId(body.episodeId)) continue;
+    const list = turns.get(body.episodeId) ?? [];
+    list.push({ at: Date.parse(String(body.at)), prompt: body.prompt as ContentReference | undefined });
+    turns.set(body.episodeId, list);
+  }
+  const corrected = new Set<string>();
+  for (const [episode, entries] of turns) {
+    const next = entries.sort((a, b) => a.at - b.at)[1];
+    if (!next?.prompt?.ref) continue;
+    const prompt = (await readActivityContent(activityPath, next.prompt)).trimStart().toLowerCase();
+    if (CORRECTION_PREFIXES.some((prefix) => prompt.startsWith(prefix))) corrected.add(episode);
+  }
+  return corrected;
+}
+
+function priorSignals(ledgerText: string): Map<string, EpisodeOutcomeSignals> {
+  const parsed = readRecords(ledgerText);
+  if (parsed.damage) throw new Error(`grants ledger damaged at line ${parsed.damage.line}: ${parsed.damage.reason}`);
+  const prior = new Map<string, EpisodeOutcomeSignals>();
+  for (const record of parsed.records) {
+    const body = record.body as Partial<EpisodeOutcomeSignals> & { event?: unknown };
+    if (body.event === "episode_outcome" && body.episodeId) prior.set(body.episodeId, body as EpisodeOutcomeSignals);
+  }
+  return prior;
+}
+
+function sameSignals(left: EpisodeOutcomeSignals | undefined, right: EpisodeOutcomeSignals): boolean {
+  return (
+    left?.survived === right.survived &&
+    left.ci === right.ci &&
+    left.amended === right.amended &&
+    left.corrected === right.corrected &&
+    left.label === right.label
+  );
+}
+
+export async function updateEpisodeOutcomes(options: {
+  cwd: string;
+  ledgerPath: string;
+  activityPath: string;
+  now?: Date;
+  runGh?: GhRunner;
+  runGit?: GitRunner;
+}): Promise<{ appended: number; outcomes: EpisodeOutcomeSignals[] }> {
+  const now = options.now ?? new Date();
+  const runGit = options.runGit ?? ((args: string[]) => command(options.cwd, "git", args));
+  let ledgerText = "";
+  try {
+    ledgerText = await readFile(options.ledgerPath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const log = await runGit(["log", "--all", "--reflog", "--format=%H%x1f%P%x1f%aI%x1f%B%x1e"]);
+  if (log.code !== 0) throw new Error("pi-daddy outcomes: git history could not be read");
+  const commits = commitsFromLog(log.stdout);
+  const branch = await defaultBranch(runGit);
+  const correctedEpisodes = await corrections(options.activityPath);
+  const commitsBySha = new Map(commits.map((commit) => [commit.sha, commit]));
+  const children = commitChildren(commits);
+  const latest = new Map<string, CommitFact>();
+  for (const commit of commits)
+    for (const episode of commit.episodes) if (!latest.has(episode)) latest.set(episode, commit);
+  const outcomes: EpisodeOutcomeSignals[] = [];
+  const commitDiffs = new Map<string, Promise<string>>();
+  const inverseDiffs = new Map<string, Promise<string>>();
+  const filesByCommit = new Map<string, Promise<Set<string>>>();
+  for (const [episodeId, candidate] of latest) {
+    const later = laterDescendants(candidate, commitsBySha, children);
+    const reverted = await wasReverted(runGit, candidate, later, commitDiffs, inverseDiffs);
+    const survived = (await gitIsAncestor(options.cwd, candidate.sha, branch, runGit)) && !reverted;
+    const ci = ciFrom(await (options.runGh ?? ((sha) => defaultGh(options.cwd, sha)))(candidate.sha));
+    const amended = await wasAmended(runGit, candidate, later, filesByCommit);
+    const corrected = correctedEpisodes.has(episodeId);
+    const oldEnough = now.getTime() - candidate.authoredMs >= FORTY_EIGHT_HOURS;
+    const label: OutcomeLabel = !oldEnough
+      ? "unknown"
+      : !survived || ci === "red" || corrected
+        ? "negative"
+        : "positive";
+    outcomes.push({ episodeId, commit: candidate.sha, survived, ci, amended, corrected, label });
+  }
+  const prior = priorSignals(ledgerText);
+  let appended = 0;
+  for (const outcome of outcomes) {
+    if (sameSignals(prior.get(outcome.episodeId), outcome)) continue;
+    await appendLedgerEvent({ path: options.ledgerPath }, buildEpisodeOutcomeEvent({ ...outcome, now }));
+    appended += 1;
+  }
+  return { appended, outcomes };
+}

package/src/products/episode-report.ts

@@ -0,0 +1,372 @@
+/** Read-only episode accounting over the governance ledger and activity timeline. */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readRecords } from "../governance/record.ts";
+
+const execFileAsync = promisify(execFile);
+const TERMINAL = new Set(["completed", "failed"]);
+
+export type EpisodeGroupBy = "definition" | "model" | "thinking";
+export interface EpisodeReportOptions {
+  since?: string;
+  definition?: string;
+  model?: string;
+  groupBy?: EpisodeGroupBy;
+}
+export interface EpisodeReportRow {
+  episode: string;
+  started: string;
+  definition: string;
+  definitionHash: string;
+  resolvedModel: string;
+  modelSource: string;
+  thinkingLevel: string;
+  thinkingSource: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  reasoningTokens: number;
+  cost: number;
+  compactions: number;
+  turns: number;
+  durationMs: number;
+  children: number;
+  commit: string;
+  outcome: "" | "positive" | "negative" | "unknown";
+}
+export interface EpisodeReportGroup {
+  value: string;
+  count: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  reasoningTokens: number;
+  cost: number;
+}
+export interface EpisodeReport {
+  rows: EpisodeReportRow[];
+  groups?: EpisodeReportGroup[];
+  groupBy?: EpisodeGroupBy;
+  totals?: { episodes: number; cost: number; tokens: number; p50EpisodeCost: number; p95EpisodeCost: number };
+}
+interface EpisodeAccumulator {
+  episode: string;
+  startedMs: number;
+  endedMs: number;
+  definitions: Set<string>;
+  hashes: Set<string>;
+  models: Set<string>;
+  modelIds: Set<string>;
+  modelSources: Set<string>;
+  thinkingLevels: Set<string>;
+  thinkingSources: Set<string>;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  reasoningTokens: number;
+  cost: number;
+  compactions: number;
+  turns: number;
+  children: Set<string>;
+  terminalExecutions: Set<string>;
+}
+
+const object = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+const number = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+const text = (value: unknown): string => (typeof value === "string" ? value : "");
+const joined = (values: Set<string>): string => [...values].filter(Boolean).sort().join(",");
+function timestamp(value: unknown, fallback: string): number {
+  const parsed = Date.parse(typeof value === "string" ? value : fallback);
+  return Number.isFinite(parsed) ? parsed : Date.parse(fallback);
+}
+function episodeOf(episodes: Map<string, EpisodeAccumulator>, id: string, at: number): EpisodeAccumulator {
+  const existing = episodes.get(id);
+  if (existing) {
+    existing.startedMs = Math.min(existing.startedMs, at);
+    existing.endedMs = Math.max(existing.endedMs, at);
+    return existing;
+  }
+  const episode: EpisodeAccumulator = {
+    episode: id,
+    startedMs: at,
+    endedMs: at,
+    definitions: new Set(),
+    hashes: new Set(),
+    models: new Set(),
+    modelIds: new Set(),
+    modelSources: new Set(),
+    thinkingLevels: new Set(),
+    thinkingSources: new Set(),
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    reasoningTokens: 0,
+    cost: 0,
+    compactions: 0,
+    turns: 0,
+    children: new Set(),
+    terminalExecutions: new Set(),
+  };
+  episodes.set(id, episode);
+  return episode;
+}
+function percentile(values: number[], fraction: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.ceil(sorted.length * fraction) - 1] ?? 0;
+}
+
+export function reportEpisodes(input: {
+  ledgerText: string;
+  activityText: string;
+  commitByEpisode: ReadonlyMap<string, string>;
+  options: EpisodeReportOptions;
+}): EpisodeReport {
+  const episodes = new Map<string, EpisodeAccumulator>();
+  const outcomes = new Map<string, "positive" | "negative" | "unknown">();
+  const ledger = readRecords(input.ledgerText);
+  if (ledger.damage) throw new Error(`grants ledger damaged at line ${ledger.damage.line}: ${ledger.damage.reason}`);
+  for (const record of ledger.records) {
+    if (!object(record.body)) continue;
+    const body = record.body;
+    const episodeId = text(body.episodeId);
+    if (!episodeId) continue;
+    if (body.event === "episode_outcome") {
+      if (["positive", "negative", "unknown"].includes(text(body.label)))
+        outcomes.set(episodeId, body.label as "positive" | "negative" | "unknown");
+      continue;
+    }
+    const episode = episodeOf(episodes, episodeId, timestamp(body.ts, record.at));
+    if (text(body.definitionHash)) episode.hashes.add(text(body.definitionHash).slice(0, 12));
+    if (body.event === "capability_decision") {
+      if (body.agentType !== "delegate") episode.definitions.add(text(body.agentType));
+      continue;
+    }
+    if (body.event !== "child_lifecycle") continue;
+    const executionId = text(body.executionId);
+    if (executionId) episode.children.add(executionId);
+    if (!TERMINAL.has(text(body.state)) || episode.terminalExecutions.has(executionId)) continue;
+    episode.terminalExecutions.add(executionId);
+    if (object(body.resolvedModel)) {
+      const provider = text(body.resolvedModel.provider),
+        modelId = text(body.resolvedModel.modelId);
+      if (modelId) {
+        episode.modelIds.add(modelId);
+        episode.models.add(provider ? `${provider}/${modelId}` : modelId);
+      }
+    }
+    if (text(body.modelSource)) episode.modelSources.add(text(body.modelSource));
+    if (object(body.thinkingLevel)) {
+      if (text(body.thinkingLevel.level)) episode.thinkingLevels.add(text(body.thinkingLevel.level));
+      if (text(body.thinkingLevel.source)) episode.thinkingSources.add(text(body.thinkingLevel.source));
+    }
+    if (text(body.thinkingSource)) episode.thinkingSources.add(text(body.thinkingSource));
+    const usage = object(body.usage) ? body.usage : undefined;
+    if (object(body.tokenDetail)) {
+      episode.inputTokens += number(body.tokenDetail.inputTokens);
+      episode.outputTokens += number(body.tokenDetail.outputTokens);
+      episode.cacheReadTokens += number(body.tokenDetail.cacheReadTokens);
+      episode.reasoningTokens += number(body.tokenDetail.reasoningTokens);
+    } else if (usage) {
+      episode.inputTokens += number(usage.input);
+      episode.outputTokens += number(usage.output);
+      episode.cacheReadTokens += number(usage.cacheRead);
+      episode.reasoningTokens += number(usage.reasoning);
+    }
+    if (usage && object(usage.cost)) episode.cost += number(usage.cost.total);
+    episode.compactions += number(body.compactionCount);
+  }
+  const activity = readRecords(input.activityText);
+  if (activity.damage)
+    throw new Error(`activity ledger damaged at line ${activity.damage.line}: ${activity.damage.reason}`);
+  for (const record of activity.records) {
+    if (record.kind !== "activity" || !object(record.body)) continue;
+    const event = record.body;
+    const episodeId = text(event.episodeId);
+    if (!episodeId) continue;
+    const episode = episodeOf(episodes, episodeId, timestamp(event.at, record.at));
+    if (event.kind === "task_started" && !text(event.agentId)) episode.turns += 1;
+  }
+  const since = input.options.since ? Date.parse(input.options.since) : Number.NEGATIVE_INFINITY;
+  let rows: EpisodeReportRow[] = [...episodes.values()]
+    .map((episode): EpisodeReportRow => ({
+      episode: episode.episode,
+      started: new Date(episode.startedMs).toISOString(),
+      definition: joined(episode.definitions),
+      definitionHash: joined(episode.hashes),
+      resolvedModel: joined(episode.models),
+      modelSource: joined(episode.modelSources),
+      thinkingLevel: joined(episode.thinkingLevels),
+      thinkingSource: joined(episode.thinkingSources),
+      inputTokens: episode.inputTokens,
+      outputTokens: episode.outputTokens,
+      cacheReadTokens: episode.cacheReadTokens,
+      reasoningTokens: episode.reasoningTokens,
+      cost: episode.cost,
+      compactions: episode.compactions,
+      turns: episode.turns,
+      durationMs: Math.max(0, episode.endedMs - episode.startedMs),
+      children: episode.children.size,
+      commit: input.commitByEpisode.get(episode.episode) ?? "",
+      outcome: outcomes.get(episode.episode) ?? "",
+    }))
+    .filter((row) => Date.parse(row.started) >= since)
+    .filter((row) => !input.options.definition || row.definition.split(",").includes(input.options.definition))
+    .filter((row) => {
+      if (!input.options.model) return true;
+      const source = episodes.get(row.episode)!;
+      return source.modelIds.has(input.options.model) || source.models.has(input.options.model);
+    })
+    .sort((a, b) => Date.parse(a.started) - Date.parse(b.started) || a.episode.localeCompare(b.episode));
+  if (input.options.groupBy) {
+    const field =
+      input.options.groupBy === "thinking"
+        ? "thinkingLevel"
+        : input.options.groupBy === "model"
+          ? "resolvedModel"
+          : "definition";
+    const groups = new Map<string, EpisodeReportGroup>();
+    for (const row of rows) {
+      const value = row[field] || "(none)";
+      const group = groups.get(value) ?? {
+        value,
+        count: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        reasoningTokens: 0,
+        cost: 0,
+      };
+      group.count += 1;
+      group.inputTokens += row.inputTokens;
+      group.outputTokens += row.outputTokens;
+      group.cacheReadTokens += row.cacheReadTokens;
+      group.reasoningTokens += row.reasoningTokens;
+      group.cost += row.cost;
+      groups.set(value, group);
+    }
+    return {
+      rows: [],
+      groups: [...groups.values()].sort((a, b) => a.value.localeCompare(b.value)),
+      groupBy: input.options.groupBy,
+    };
+  }
+  const costs = rows.map((row) => row.cost);
+  return {
+    rows,
+    totals: {
+      episodes: rows.length,
+      cost: costs.reduce((sum, value) => sum + value, 0),
+      tokens: rows.reduce((sum, row) => sum + row.inputTokens + row.outputTokens, 0),
+      p50EpisodeCost: percentile(costs, 0.5),
+      p95EpisodeCost: percentile(costs, 0.95),
+    },
+  };
+}
+
+const escapeCell = (value: unknown): string => String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
+const cost = (value: number): string => value.toFixed(6).replace(/\.?0+$/, "") || "0";
+function duration(ms: number): string {
+  const seconds = Math.round(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  return minutes ? `${minutes}m ${seconds % 60}s` : `${seconds}s`;
+}
+function table(headers: string[], rows: unknown[][]): string {
+  return [
+    `| ${headers.join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+    ...rows.map((row) => `| ${row.map(escapeCell).join(" | ")} |`),
+  ].join("\n");
+}
+export function renderEpisodeReport(report: EpisodeReport, json: boolean): string {
+  if (json) return `${JSON.stringify(report, null, 2)}\n`;
+  if (report.groups && report.groupBy) {
+    const headers = [
+      report.groupBy,
+      "count",
+      "inputTokens",
+      "outputTokens",
+      "cacheReadTokens",
+      "reasoningTokens",
+      "cost",
+    ];
+    return `${table(
+      headers,
+      report.groups.map((group) => [
+        group.value,
+        group.count,
+        group.inputTokens,
+        group.outputTokens,
+        group.cacheReadTokens,
+        group.reasoningTokens,
+        cost(group.cost),
+      ]),
+    )}\n`;
+  }
+  const headers = [
+    "episode",
+    "started",
+    "definition",
+    "definitionHash",
+    "resolvedModel",
+    "modelSource",
+    "thinkingLevel",
+    "thinkingSource",
+    "inputTokens",
+    "outputTokens",
+    "cacheReadTokens",
+    "reasoningTokens",
+    "cost",
+    "compactions",
+    "turns",
+    "duration",
+    "children",
+    "commit",
+    "outcome",
+  ];
+  const rows = report.rows.map((row) => [
+    row.episode,
+    row.started,
+    row.definition,
+    row.definitionHash,
+    row.resolvedModel,
+    row.modelSource,
+    row.thinkingLevel,
+    row.thinkingSource,
+    row.inputTokens,
+    row.outputTokens,
+    row.cacheReadTokens,
+    row.reasoningTokens,
+    cost(row.cost),
+    row.compactions,
+    row.turns,
+    duration(row.durationMs),
+    row.children,
+    row.commit,
+    row.outcome,
+  ]);
+  const totals = report.totals!;
+  const totalsTable = table(
+    ["episodes", "cost", "tokens", "p50 episode cost", "p95 episode cost"],
+    [[totals.episodes, cost(totals.cost), totals.tokens, cost(totals.p50EpisodeCost), cost(totals.p95EpisodeCost)]],
+  );
+  return `${table(headers, rows)}\n\n${totalsTable}\n`;
+}
+
+export function commitsFromGitLog(log: string): Map<string, string> {
+  const commits = new Map<string, string>();
+  for (const entry of log.split("\u001e")) {
+    const [sha, ...body] = entry.trim().split("\n");
+    if (!/^[a-f0-9]{8,40}$/i.test(sha ?? "")) continue;
+    for (const match of body.join("\n").matchAll(/^Pi-Episode:\s*(\S+)\s*$/gim)) {
+      const episode = match[1].startsWith("episode:") ? match[1] : `episode:${match[1]}`;
+      if (!commits.has(episode)) commits.set(episode, sha.slice(0, 8));
+    }
+  }
+  return commits;
+}
+export async function commitsForRepo(cwd: string): Promise<Map<string, string>> {
+  const { stdout } = await execFileAsync("git", ["log", "--format=%H%n%B%x1e"], { cwd, maxBuffer: 16 * 1024 * 1024 });
+  return commitsFromGitLog(stdout);
+}