catherd-cli 0.2.1 → 1.1.0

package/src/services/session-view.ts

@@ -0,0 +1,152 @@
+import { statSync } from "node:fs";
+import { liveSessionFile, readSessionFiles, type SessionFile } from "../infra/claude-session.ts";
+import { type Run, runPaths } from "./run-store.ts";
+import { readSessionRows } from "./sessions.ts";
+
+/**
+ * Spec §4: runs grouped by the Claude Code session that drove them. A run belongs to the session that started it
+ * (`meta.startedBy`); a run listed in another session's rows of `sessions.jsonl` also appears under that session,
+ * as "continued here", and under its starting session it says "continued in <name>", naming the session that
+ * owns it now (the last row of `sessions.jsonl`; a run that came back to its starter is not "continued" at
+ * all). Only the current owner's group counts its live roles and landings. Runs from 1.0 (no
+ * `startedBy`) go under "earlier runs".
+ */
+
+/** A session as the runs page shows it: its name read live while it runs, else the last one recorded. */
+export interface RunSession {
+  sessionId: string;
+  hostSessionId: string | null;
+  name: string;
+  /** the session's process runs now */
+  live: boolean;
+}
+
+export interface GroupedRun {
+  run: Run;
+  /** "here": this session continued a run another started; "elsewhere": another session continued it */
+  continued: "here" | "elsewhere" | null;
+  /** the session that owns it now, for "elsewhere" */
+  continuedIn: string | null;
+  /** the run lives on in this session now (it is the run's current owner): its live roles count here */
+  current: boolean;
+}
+
+export interface SessionGroup {
+  /** null: "earlier runs", the 1.0 runs no session is recorded for */
+  session: RunSession | null;
+  runs: GroupedRun[];
+  /** when anything last happened in one of its runs, ms since the epoch */
+  lastActivity: number;
+}
+
+/** Newest of the run's creation and its state and record files' last writes. */
+export function runActivity(run: Run): number {
+  const p = runPaths(run.dir);
+  let t = Date.parse(run.meta.createdAt) || 0;
+  for (const f of [p.stateJson, p.runs, p.state, p.agents]) {
+    try {
+      t = Math.max(t, statSync(f).mtimeMs);
+    } catch {
+      // not written yet
+    }
+  }
+  return t;
+}
+
+/** The sessions each run has had, oldest first: its starter, then each one that took it over. */
+function trailOf(
+  run: Run,
+): { sessionId: string; hostSessionId: string | null; name: string | null; at: string }[] {
+  const rows = readSessionRows(run);
+  const s = run.meta.startedBy;
+  if (s && !rows.some((r) => r.sessionId === s.sessionId)) return [{ ...s, at: run.meta.createdAt }, ...rows];
+  return rows;
+}
+
+/** Every run grouped by session, the groups newest activity first, the runs in each newest first. */
+export function groupRuns(runs: Run[], files: SessionFile[] = readSessionFiles()): SessionGroup[] {
+  // the last name recorded for each session, in any run
+  const recorded = new Map<string, { name: string | null; host: string | null; at: string }>();
+  const trails = new Map(runs.map((r) => [r.id, trailOf(r)]));
+  for (const t of trails.values())
+    for (const row of t) {
+      const was = recorded.get(row.sessionId);
+      if (!was || row.at >= was.at)
+        recorded.set(row.sessionId, {
+          name: row.name ?? was?.name ?? null,
+          host: row.hostSessionId ?? was?.host ?? null,
+          at: row.at,
+        });
+    }
+  const sessionOf = (id: string): RunSession => {
+    const live = liveSessionFile(id, files);
+    const rec = recorded.get(id);
+    return {
+      sessionId: id,
+      hostSessionId: live?.hostSessionId ?? rec?.host ?? null,
+      name: live?.name ?? rec?.name ?? `session ${id.slice(0, 8)}`,
+      live: live !== null,
+    };
+  };
+  const groups = new Map<string | null, SessionGroup>();
+  const add = (id: string | null, g: GroupedRun, at: number) => {
+    let group = groups.get(id);
+    if (!group) {
+      group = { session: id === null ? null : sessionOf(id), runs: [], lastActivity: 0 };
+      groups.set(id, group);
+    }
+    group.runs.push(g);
+    group.lastActivity = Math.max(group.lastActivity, at);
+  };
+  for (const run of runs) {
+    const at = runActivity(run);
+    const trail = trails.get(run.id) ?? [];
+    const starter = run.meta.startedBy?.sessionId ?? null;
+    // the run lives on in its current owner: the last session that took it (a run can come back to its starter)
+    const owner = trail.at(-1)?.sessionId ?? starter;
+    const moved = owner !== starter && owner !== null;
+    // a run that lives on elsewhere counts, in a session it left, from when that session last took it
+    const tookAt = (id: string | null): number =>
+      Date.parse(trail.findLast((t) => t.sessionId === id)?.at ?? run.meta.createdAt) || 0;
+    add(
+      starter,
+      {
+        run,
+        continued: moved ? "elsewhere" : null,
+        continuedIn: moved ? sessionOf(owner).name : null,
+        current: !moved,
+      },
+      moved ? tookAt(starter) : at,
+    );
+    for (const id of new Set(trail.map((t) => t.sessionId)))
+      if (id !== starter)
+        add(
+          id,
+          { run, continued: "here", continuedIn: null, current: id === owner },
+          id === owner ? at : tookAt(id),
+        );
+  }
+  const out = [...groups.values()];
+  for (const g of out)
+    g.runs.sort(
+      (a, b) =>
+        runActivity(b.run) - runActivity(a.run) || b.run.meta.createdAt.localeCompare(a.run.meta.createdAt),
+    );
+  // "earlier runs" last, whatever its activity: 1.0 runs are history
+  return out.sort((a, b) =>
+    a.session === null ? 1 : b.session === null ? -1 : b.lastActivity - a.lastActivity,
+  );
+}
+
+/**
+ * The session a run started in, as the runs page names it now (null for a run from before 1.1), and the session
+ * that continued it, if another did.
+ */
+export function sessionFacts(
+  run: Run,
+  files: SessionFile[] = readSessionFiles(),
+): { session: RunSession | null; continuedIn: string | null } {
+  const starter = run.meta.startedBy?.sessionId ?? null;
+  const own = groupRuns([run], files).find((g) => (g.session?.sessionId ?? null) === starter);
+  return { session: own?.session ?? null, continuedIn: own?.runs[0]?.continuedIn ?? null };
+}

package/src/services/sessions.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { sessionFileFor } from "../infra/claude-session.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { appendJsonl, ensureJsonlHeader, readJsonl, writeJsonAtomic } from "../infra/store.ts";
+import type { Deps } from "./ports.ts";
+import { type Run, runPaths } from "./run-store.ts";
+import { readNotes } from "./state.ts";
+
+/** Spec §4: a Claude Code session as catherd records it. */
+export interface SessionRef {
+  sessionId: string;
+  hostSessionId: string | null;
+  name: string | null;
+}
+
+/**
+ * The session this process serves (spec §3.3), read live: its registry file's id and name when it has one (the
+ * id in the environment goes stale after /clear), else the environment's. Null outside Claude Code.
+ */
+export function currentSession(deps: Deps): SessionRef | null {
+  const env = deps.session;
+  if (!env) return null;
+  const file = sessionFileFor(env);
+  const sessionId = file?.sessionId ?? env.sessionId;
+  if (!sessionId) return null;
+  return { sessionId, hostSessionId: file?.hostSessionId ?? env.hostSessionId, name: file?.name ?? null };
+}
+
+const OwnerSchema = z.object({ sessionId: z.string(), since: z.string() });
+export type Owner = z.infer<typeof OwnerSchema>;
+
+/** The run's owner session (state.json `owner`), or null for a run no session has owned (1.0, a terminal). */
+export function runOwner(run: Run): Owner | null {
+  const r = OwnerSchema.safeParse((readNotes(run) as Record<string, unknown>).owner);
+  return r.success ? r.data : null;
+}
+
+/** Whether this process serves a session and that session owns the run now. */
+export function ownsRun(deps: Deps, run: Run): boolean {
+  const me = currentSession(deps);
+  return me !== null && runOwner(run)?.sessionId === me.sessionId;
+}
+
+const SessionRowSchema = z.looseObject({
+  sessionId: z.string(),
+  hostSessionId: z.string().nullable(),
+  name: z.string().nullable(),
+  at: z.string(),
+});
+export type SessionRow = z.infer<typeof SessionRowSchema>;
+
+/** `R/sessions.jsonl`: every session that has owned the run, in the order they took it. */
+export function readSessionRows(run: Run): SessionRow[] {
+  return readJsonl<unknown>(runPaths(run.dir).sessions).rows.flatMap((row) => {
+    const r = SessionRowSchema.safeParse(row);
+    return r.success ? [r.data] : [];
+  });
+}
+
+/**
+ * Spec §3.3: `run_start`, `dispatch` and `peek` make the calling session the run's owner when it is not, and
+ * append it to `R/sessions.jsonl`: that is how a run moves when it is continued from another session. Outside
+ * Claude Code it changes nothing. Returns whether the owner changed.
+ */
+export async function claimRun(deps: Deps, run: Run): Promise<boolean> {
+  const me = currentSession(deps);
+  if (!me) return false;
+  const p = runPaths(run.dir);
+  const at = new Date(deps.now()).toISOString();
+  const row = (since: string): void => {
+    ensureJsonlHeader(p.sessions, "sessions");
+    appendJsonl(p.sessions, {
+      sessionId: me.sessionId,
+      hostSessionId: me.hostSessionId,
+      name: me.name,
+      at: since,
+    });
+  };
+  // the trail row goes in under the same lock: the trail's last row is the owner (session-view reads it so)
+  return withFileLock(p.stateJson, () => {
+    const notes = readNotes(run);
+    const owner = runOwner(run);
+    if (owner?.sessionId === me.sessionId) {
+      // a crash between the state.json write and the append left the trail without its owner: repaired here
+      if (readSessionRows(run).at(-1)?.sessionId !== me.sessionId) row(owner.since);
+      return false;
+    }
+    writeJsonAtomic(p.stateJson, { ...notes, owner: { sessionId: me.sessionId, since: at } });
+    row(at);
+    return true;
+  });
+}

package/src/services/setup.ts

@@ -0,0 +1,87 @@
+import { existsSync, readdirSync, readFileSync, renameSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Issue } from "../domain/profile-rules.ts";
+import { configDir } from "../infra/paths.ts";
+import { type Refreshed, refreshDiscovery } from "./catalog-service.ts";
+import type { Synced } from "./agent-links.ts";
+import { activate, resetProfile, withProfilesLock } from "./profile-service.ts";
+import { configFile, profilesDir, projectsFile } from "./profile-store.ts";
+import { ensurePrivateDir } from "../infra/store.ts";
+
+/** True when profile `name` has a file (`default` exists as a name even before it has one). */
+export const hasProfileFile = (name: string): boolean => existsSync(join(profilesDir(), `${name}.json`));
+
+/** A JSON file written by catherd 0.x: readable JSON with no `schema` field. */
+function isLegacy(file: string): boolean {
+  try {
+    const v = JSON.parse(readFileSync(file, "utf8")) as { schema?: unknown } | null;
+    return typeof v === "object" && v !== null && v.schema === undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Spec D2, a clean break: 1.0 never reads a 0.x config.json, projects.json or profile, so `init` moves
+ * them to `<config>/0.x-backup-<stamp>/`, under the profiles lock. Returns the files moved.
+ */
+export function moveLegacy(now: Date = new Date()): string[] {
+  return withProfilesLock(() => moveLegacyUnlocked(now));
+}
+
+function moveLegacyUnlocked(now: Date): string[] {
+  const candidates = [
+    configFile(),
+    projectsFile(),
+    ...(existsSync(profilesDir())
+      ? readdirSync(profilesDir())
+          .filter((f) => f.endsWith(".json"))
+          .map((f) => join(profilesDir(), f))
+      : []),
+  ].filter((f) => existsSync(f) && isLegacy(f));
+  if (candidates.length === 0) return [];
+  const backup = join(configDir(), `0.x-backup-${now.toISOString().replace(/[:.]/g, "-")}`);
+  ensurePrivateDir(join(backup, "profiles"));
+  return candidates.map((f) => {
+    const to = join(backup, f.startsWith(profilesDir()) ? join("profiles", basename(f)) : basename(f));
+    renameSync(f, to);
+    return to;
+  });
+}
+
+export interface InitResult {
+  moved: string[];
+  profile: string;
+  /** true when the default profile was written under `profile` */
+  created: boolean;
+  /** why the default profile was not written: it does not validate against this machine's catalog */
+  errors: Issue[];
+  /** false when nothing was made active: the profile was not written and has no file */
+  active: boolean;
+  synced: Synced | null;
+  refreshed: Refreshed[];
+}
+
+/**
+ * Spec §8 `catherd init`, the setup half: moves 0.x files aside, writes the default profile (spec §7.2)
+ * unless a 1.0 one exists and `overwrite` is not set, makes it active and links its agents, and lists
+ * every backend's models. It never throws for a default profile that does not validate here: it writes
+ * nothing, returns the errors, and activates the profile only when it has a file.
+ */
+export async function initSetup(
+  o: { profile?: string; overwrite?: boolean; now?: Date } = {},
+): Promise<InitResult> {
+  const moved = moveLegacy(o.now);
+  const profile = o.profile ?? "default";
+  let created = false;
+  let errors: Issue[] = [];
+  if (!hasProfileFile(profile) || o.overwrite === true) {
+    const saved = resetProfile(profile);
+    created = saved.saved;
+    errors = saved.errors;
+  }
+  const active = hasProfileFile(profile);
+  const synced = active ? activate(profile) : null;
+  const refreshed = await refreshDiscovery();
+  return { moved, profile, created, errors, active, synced, refreshed };
+}

package/src/services/state.ts

@@ -0,0 +1,111 @@
+import { relative } from "node:path";
+import { z } from "zod";
+import { errorMessage, isCatherdError } from "../domain/errors.ts";
+import { overlaps } from "../domain/lane.ts";
+import { renderState, withParked } from "../domain/state.ts";
+import { dispatchPaths } from "../infra/dispatch-dir.ts";
+import { withFileLock } from "../infra/filelock.ts";
+import { gitHead, statusSnapshot } from "../infra/git.ts";
+import { readVersioned, writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
+import { liveDispatches } from "./dispatches.ts";
+import { protocolNext } from "./protocol.ts";
+import { type Run, runPaths } from "./run-store.ts";
+
+/** state.json: the orchestrator's notes that state.md shows beside the live facts. */
+const NotesSchema = z.looseObject({
+  schema: z.literal(1),
+  next: z.string(),
+  lastCheck: z.string().nullable(),
+  lastLandedAt: z.string().nullable(),
+  /** spec 1.1 §8: the milestones waiting on the owner */
+  parked: z.array(z.string()).optional(),
+});
+export type Notes = z.infer<typeof NotesSchema>;
+export type NotesPatch = Partial<Omit<Notes, "schema">>;
+
+/** Every writer's next step keeps the parked milestones in front of it (spec 1.1 §8). */
+const parkedNext = (n: Notes): Notes => ({ ...n, next: withParked(n.next, n.parked ?? []) });
+
+const FRESH: Notes = { schema: 1, next: "plan the milestones", lastCheck: null, lastLandedAt: null };
+
+export function readNotes(run: Run): Notes {
+  try {
+    return readVersioned(runPaths(run.dir).stateJson, NotesSchema, 1);
+  } catch (e) {
+    if (isCatherdError(e) && e.code === "E_CONFIG_NEWER_SCHEMA") throw e;
+    return { ...FRESH };
+  }
+}
+
+/**
+ * Rewrites state.json and state.md under the run's state lock, so concurrent writers never lose a
+ * field (audit C11). `change` may be a function of the current notes; it runs inside the lock.
+ * Throws E_IO_UNEXPECTED, writing nothing, when git fails: state.md must not show a broken git as clean.
+ */
+export function updateState(run: Run, change: NotesPatch | ((n: Notes) => NotesPatch) = {}): Promise<string> {
+  const p = runPaths(run.dir);
+  return withFileLock(p.stateJson, async () => {
+    // git first: a failed snapshot throws before either file is written, so they never disagree
+    const [head, snap] = await Promise.all([gitHead(run.meta.repo), statusSnapshot(run.meta.repo)]);
+    const notes = readNotes(run);
+    const next = parkedNext({ ...notes, ...(typeof change === "function" ? change(notes) : change) });
+    writeJsonAtomic(p.stateJson, next);
+    const live = liveDispatches(run);
+    const text = renderState({
+      title: run.meta.title,
+      head: head ?? "none",
+      dirty: Object.keys(snap)
+        .sort()
+        .map((path) => ({
+          path,
+          owner: live.find((d) => overlaps([path], d.admit.owns).length > 0)?.admit.name ?? null,
+        })),
+      running: live.map((d) => ({
+        name: d.admit.name,
+        rung: d.admit.rung,
+        thread: d.admit.thread,
+        since: d.admit.admittedAt.slice(11, 16),
+        brief: relative(run.dir, dispatchPaths(d.dir).brief),
+      })),
+      lastCheck: next.lastCheck,
+      next: next.next,
+      protocol: protocolNext(run, next.parked ?? []),
+    });
+    writeTextAtomic(p.state, text);
+    return text;
+  });
+}
+
+/**
+ * Ruling (b): a failed state.md refresh (git broken) never fails the call. The notes still go to state.json
+ * under the state lock (state.md stays as it was), and the message comes back as a hint.
+ */
+export async function refreshState(
+  run: Run,
+  change: NotesPatch | ((n: Notes) => NotesPatch) = {},
+): Promise<{ text: string | null; hints: string[] }> {
+  let applied = false;
+  const apply = (n: Notes): NotesPatch => {
+    applied = true;
+    return typeof change === "function" ? change(n) : change;
+  };
+  try {
+    return { text: await updateState(run, apply), hints: [] };
+  } catch (e) {
+    const hints = [`state.md not refreshed: ${errorMessage(e)}`];
+    // git fails before updateState reaches the notes: keep them, so a later refresh still shows them
+    if (!applied) {
+      const stateJson = runPaths(run.dir).stateJson;
+      try {
+        await withFileLock(stateJson, () => {
+          const notes = readNotes(run);
+          writeJsonAtomic(stateJson, parkedNext({ ...notes, ...apply(notes) }));
+        });
+      } catch (e2) {
+        // the lock outwaited (a slow git under another refresh): still never fail the call
+        hints.push(`notes not saved: ${errorMessage(e2)}`);
+      }
+    }
+    return { text: null, hints };
+  }
+}

package/src/services/summary.ts

@@ -0,0 +1,241 @@
+import { resolve } from "node:path";
+import { type BudgetStatus, budgetStatus } from "../domain/budget.ts";
+import { isCatherdError } from "../domain/errors.ts";
+import type { Tokens } from "../domain/record.ts";
+import { median } from "../domain/util.ts";
+import { nonBlankLines, readJsonl } from "../infra/store.ts";
+import { spendOf } from "./budget.ts";
+import { latestVerifierStep, type VerifierStep } from "./gate-service.ts";
+import { type OpenQuestion, openQuestions } from "./questions.ts";
+import { type DispatchState, liveDispatches } from "./dispatches.ts";
+import { type RunSession, sessionFacts } from "./session-view.ts";
+import type { Deps } from "./ports.ts";
+import {
+  findRun,
+  listRuns,
+  readAgentRuns,
+  readRecords,
+  readRoutes,
+  type Run,
+  runPaths,
+} from "./run-store.ts";
+
+export interface RunSummary {
+  id: string;
+  /** spec 1.1 §8: the owner questions not answered yet, listed first */
+  questions: OpenQuestion[];
+  title: string;
+  repo: string;
+  createdAt: string;
+  /** spec §4: the Claude Code session that started it (null before 1.1), named live while it runs */
+  session: RunSession | null;
+  /** the session that continued it, when another did */
+  continuedIn: string | null;
+  stateTail: string[];
+  live: { name: string; rung: string; state: DispatchState; secs: number; dispatchId: string }[];
+  totals: { runs: number; ok: number; notOk: string[]; tokens: Tokens; costUsd: number; wallMinutes: number };
+  /** native subagent runs, as the orchestrator reported them: reported, not measured (spec §14) */
+  agents: { runs: number; totalTokens: number; costUsd: number };
+  jev: { decisions: number; fallbacks: number };
+  /** per backend, how many of this run's dispatches ran with the user's harness (native) and isolated */
+  harness: { backend: string; native: number; isolated: number }[];
+  budget: BudgetStatus | null;
+  milestones: string[];
+  /** spec 1.1 §7: the verifier's latest gate_check, so the user sees where it is */
+  verifier: VerifierStep | null;
+  warnings: string[];
+}
+
+/** One run at a glance. Spec §3.4: reads are pure; nothing here finalizes a dispatch or writes a file. */
+export function summarizeRun(deps: Deps, run: Run): RunSummary {
+  const now = deps.now();
+  const { records, corrupt } = readRecords(run);
+  const live = liveDispatches(run, now);
+  const agents = readAgentRuns(run);
+  const jev = readJsonl<{ source?: string }>(runPaths(run.dir).jev).rows;
+  const sum = (f: (t: Tokens) => number) => records.reduce((n, r) => n + f(r.tokens), 0);
+  let budget: BudgetStatus | null = null;
+  const warnings = corrupt ? [`runs.jsonl: skipped ${corrupt} unreadable row(s)`] : [];
+  try {
+    budget = budgetStatus(spendOf(run, records, live, now), deps.profiles.forRepo(run.meta.repo).budget);
+  } catch (e) {
+    warnings.push(`budget: ${isCatherdError(e) ? e.message : String(e)}`);
+  }
+  return {
+    id: run.id,
+    questions: openQuestions(run),
+    title: run.meta.title,
+    repo: run.meta.repo,
+    createdAt: run.meta.createdAt,
+    ...sessionFacts(run),
+    stateTail: nonBlankLines(runPaths(run.dir).state).slice(-3),
+    live: live.map((d) => ({
+      name: d.admit.name,
+      rung: d.admit.rung,
+      state: d.state,
+      secs: Math.max(0, Math.round((now - Date.parse(d.admit.admittedAt)) / 1000)),
+      dispatchId: d.admit.dispatchId,
+    })),
+    totals: {
+      runs: records.length,
+      ok: records.filter((r) => r.status === "ok").length,
+      notOk: records.filter((r) => r.status !== "ok").map((r) => `${r.name} (${r.status})`),
+      tokens: { input: sum((t) => t.input), cached: sum((t) => t.cached), output: sum((t) => t.output) },
+      costUsd: records.reduce((n, r) => n + (r.costUsd ?? 0), 0),
+      wallMinutes: Math.round((now - Date.parse(run.meta.createdAt)) / 60_000),
+    },
+    agents: {
+      runs: agents.length,
+      totalTokens: agents.reduce((n, a) => n + a.totalTokens, 0),
+      costUsd: agents.reduce((n, a) => n + (a.costUsd ?? 0), 0),
+    },
+    // a jev-kind, lane or default source is a decision Jev did not make whole
+    jev: { decisions: jev.length, fallbacks: jev.filter((j) => j.source !== "jev").length },
+    harness: [...new Set(records.map((r) => r.backend))].sort().map((backend) => {
+      const of = records.filter((r) => r.backend === backend);
+      return {
+        backend,
+        native: of.filter((r) => !r.isolated).length,
+        isolated: of.filter((r) => r.isolated).length,
+      };
+    }),
+    budget,
+    milestones: nonBlankLines(runPaths(run.dir).ledger).slice(1),
+    verifier: latestVerifierStep(run),
+    warnings,
+  };
+}
+
+/** `status(run?)`: that run; without one, every run with a live role, else the newest run. */
+export function status(
+  deps: Deps,
+  runId?: string,
+): { version: string; runs: RunSummary[]; warnings: string[] } {
+  if (runId) return { version: deps.version, runs: [summarizeRun(deps, findRun(runId))], warnings: [] };
+  const { runs, corrupt } = listRuns();
+  const warnings = corrupt.map((c) => `skipped run ${c.id}: ${c.reason}`);
+  const all = runs.map((r) => summarizeRun(deps, r));
+  const live = all.filter((s) => s.live.length > 0);
+  return { version: deps.version, runs: live.length ? live : all.slice(0, 1), warnings };
+}
+
+export interface RungStats {
+  role: string;
+  rung: string;
+  runs: number;
+  ok: number;
+  refusals: number;
+  climbsFrom: number;
+  secs: number;
+  tokens: Tokens;
+}
+
+export interface HarnessCost {
+  backend: string;
+  nativeRuns: number;
+  isolatedRuns: number;
+  nativeMedian: number | null;
+  isolatedMedian: number | null;
+  extraPerRun: number | null;
+}
+
+/** A median in whole tokens: an even count's mean of the two middle values is rounded. */
+function tokenMedian(xs: number[]): number | null {
+  const m = median(xs);
+  return m === null ? null : Math.round(m);
+}
+
+/** Fewer first-turn samples than this on either side, and the harness line gives no figure. */
+const HARNESS_MIN_RUNS = 3;
+
+/**
+ * What the user's own harness setup costs per run: median first-turn input, native against isolated.
+ * No figure below HARNESS_MIN_RUNS a side, nor when native is not dearer: noise, not a cost.
+ */
+function harnessCosts(runs: Run[]): HarnessCost[] {
+  type Row = { backend: string; isolated: boolean; firstTurnInput: number };
+  const rows = runs.flatMap((r) => readJsonl<Row>(runPaths(r.dir).harness).rows);
+  return [...new Set(rows.map((r) => r.backend))].sort().map((backend) => {
+    const pick = (isolated: boolean) =>
+      rows.filter((r) => r.backend === backend && r.isolated === isolated).map((r) => r.firstTurnInput);
+    const nativeRuns = pick(false).length;
+    const isolatedRuns = pick(true).length;
+    const native = tokenMedian(pick(false));
+    const isolated = tokenMedian(pick(true));
+    const enough = nativeRuns >= HARNESS_MIN_RUNS && isolatedRuns >= HARNESS_MIN_RUNS;
+    const extra = native !== null && isolated !== null ? native - isolated : 0;
+    return {
+      backend,
+      nativeRuns,
+      isolatedRuns,
+      nativeMedian: native,
+      isolatedMedian: isolated,
+      extraPerRun: enough && extra > 0 ? extra : null,
+    };
+  });
+}
+
+/** Per role and rung over past runs: runs, ok, refusals, climbs from it, seconds and tokens. Reads only. */
+export function runsSummary(f: { run?: string; repo?: string; role?: string; sinceDays?: number }): {
+  rungs: RungStats[];
+  agents: { rung: string; runs: number; totalTokens: number; secs: number }[];
+  harness: HarnessCost[];
+} {
+  const since = f.sinceDays ? Date.now() - f.sinceDays * 86_400_000 : 0;
+  const repo = f.repo ? resolve(f.repo) : null;
+  const all = listRuns().runs.filter(
+    (r) => (!repo || r.meta.repo === repo) && Date.parse(r.meta.createdAt) >= since,
+  );
+  const runs = all.filter((r) => !f.run || r.id === f.run);
+  // with a run given, the harness line compares like with like: every run of that run's repo
+  const harnessRepo = f.run ? runs[0]?.meta.repo : undefined;
+  const harnessRuns = f.run ? all.filter((r) => r.meta.repo === harnessRepo) : runs;
+  const stats = new Map<string, RungStats>();
+  const at = (role: string, rung: string): RungStats => {
+    const key = `${role} ${rung}`;
+    let s = stats.get(key);
+    if (!s) {
+      s = {
+        role,
+        rung,
+        runs: 0,
+        ok: 0,
+        refusals: 0,
+        climbsFrom: 0,
+        secs: 0,
+        tokens: { input: 0, cached: 0, output: 0 },
+      };
+      stats.set(key, s);
+    }
+    return s;
+  };
+  const agents = new Map<string, { rung: string; runs: number; totalTokens: number; secs: number }>();
+  for (const run of runs) {
+    for (const r of readRecords(run).records) {
+      if (f.role && r.role !== f.role) continue;
+      const s = at(r.role, r.rung);
+      s.runs++;
+      if (r.status === "ok") s.ok++;
+      if (r.replyStatus === "refused" || r.replyStatus === "blocked") s.refusals++;
+      s.secs += r.secs;
+      s.tokens.input += r.tokens.input;
+      s.tokens.cached += r.tokens.cached;
+      s.tokens.output += r.tokens.output;
+    }
+    for (const c of readRoutes(run))
+      if (c.source === "climb" && c.from && (!f.role || c.role === f.role)) at(c.role, c.from).climbsFrom++;
+    for (const a of readAgentRuns(run)) {
+      if (f.role && a.role !== f.role) continue;
+      const s = agents.get(a.rung) ?? { rung: a.rung, runs: 0, totalTokens: 0, secs: 0 };
+      s.runs++;
+      s.totalTokens += a.totalTokens;
+      s.secs += a.secs ?? 0;
+      agents.set(a.rung, s);
+    }
+  }
+  return {
+    rungs: [...stats.values()].sort((a, b) => a.role.localeCompare(b.role) || a.rung.localeCompare(b.rung)),
+    agents: [...agents.values()].sort((a, b) => a.rung.localeCompare(b.rung)),
+    harness: harnessCosts(harnessRuns),
+  };
+}