catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/services/scorecard.ts

@@ -0,0 +1,382 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+import { CatherdError } from "../domain/errors.ts";
+import { latestOutcomes } from "../domain/route.ts";
+import {
+  assertLabel,
+  SCORECARD_TASKS,
+  assertScorecardRows,
+  type ScorecardFile,
+  ScorecardFileSchema,
+  type ScorecardTask,
+  ScorecardTaskSchema,
+  type ScorecardTaskId,
+  type TaskScore,
+} from "../domain/scorecard.ts";
+import { assetPath } from "../infra/assets.ts";
+import { git, gitHead } from "../infra/git.ts";
+import { dataDir } from "../infra/paths.ts";
+import { ensurePrivateDir, readVersioned, writeJsonAtomic } from "../infra/store.ts";
+import { landedMilestones, reviewRounds } from "./milestones.ts";
+import { checkEnvFor, runCheck } from "./preflight.ts";
+import { runMilestones } from "./protocol.ts";
+import { openQuestions } from "./questions.ts";
+import {
+  findRun,
+  listRuns,
+  readAgentRuns,
+  readOutcomes,
+  readRecords,
+  type Run,
+  supersededBy,
+} from "./run-store.ts";
+import { failoverRecovered, interventionsOf, pausedMs, runEnd } from "./scorecard-metrics.ts";
+import { quotaByBackend } from "./summary.ts";
+
+// Plan 28: prepare a scorecard task's reproducible starting point, score the run that ended there, store the row.
+
+/** The checkout's `scorecard/` folder, or null for an installed package (it ships no fixtures). */
+export const scorecardRoot = (): string | null => {
+  const root = assetPath("scorecard");
+  return existsSync(root) ? root : null;
+};
+
+export const defaultPreparedRoot = (): string => join(dataDir(), "scorecard");
+
+const minutes = (ms: number): number => Math.round(ms / 6000) / 10;
+
+export function loadTask(id: string, root: string): ScorecardTask {
+  if (!(SCORECARD_TASKS as readonly string[]).includes(id))
+    throw new CatherdError("E_INPUT_INVALID", `no scorecard task ${id}`, {
+      fix: `catherd scorecard prepare ${SCORECARD_TASKS.join("|")}`,
+    });
+  const file = join(root, "tasks", id, "task.json");
+  const task = readVersioned(file, ScorecardTaskSchema, 1);
+  if (task.id !== id)
+    throw new CatherdError("E_CONFIG_INVALID", `${file} names task ${task.id}, not ${id}`, {
+      fix: `set "id" to ${id} in ${file}`,
+    });
+  return task;
+}
+
+const PreparedSchema = z.looseObject({
+  schema: z.literal(1),
+  task: z.enum(SCORECARD_TASKS),
+  dir: z.string(),
+  repo: z.string(),
+  plan: z.string(),
+  startCommit: z.string(),
+  limits: z.string().nullable(),
+  shim: z.string().nullable(),
+  preparedAt: z.string(),
+  prompt: z.string(),
+});
+export type Prepared = z.infer<typeof PreparedSchema> & { task: ScorecardTaskId };
+
+/** A URL (`scheme://`) or an scp-like `user@host:path`: anything else is a local path. */
+const REMOTE = /^(?:[a-z][a-z0-9+.-]*:\/\/|[^/\s]+@[^/\s:]+:)/i;
+
+const GIT_LONG = 30 * 60_000;
+
+/** A git command that must succeed: its failure is `fail`'s error. */
+async function must(
+  repo: string,
+  args: string[],
+  fail: () => CatherdError,
+  timeoutMs?: number,
+): Promise<string> {
+  const r = await git(repo, args, timeoutMs);
+  if (r.kind !== "ok") throw fail();
+  return r.out;
+}
+
+export async function prepareTask(i: {
+  task: ScorecardTask;
+  root: string;
+  into: string;
+  source?: string;
+  now: Date;
+  setup: boolean;
+}): Promise<Prepared> {
+  const { task } = i;
+  const given = i.source ?? task.source;
+  if (!given)
+    throw new CatherdError("E_INPUT_INVALID", `${task.id} names no source`, {
+      fix: `catherd scorecard prepare ${task.id} --source <path or URL>`,
+    });
+  // the clone runs inside the new folder, so a local path must be absolute before it gets there
+  const src = REMOTE.test(given) ? given : resolve(given);
+  ensurePrivateDir(dirname(i.into));
+  try {
+    mkdirSync(i.into);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "EEXIST")
+      throw new CatherdError("E_INPUT_INVALID", `${i.into} already exists`, {
+        fix: "prepare again: the folder name carries the time",
+      });
+    throw e;
+  }
+  // the run's own repo toplevel is the real path; findRun and listRuns key runs by it
+  const into = realpathSync(i.into);
+  const repo = join(into, "repo");
+  const io = (what: string) => () =>
+    new CatherdError("E_IO_UNEXPECTED", `${what} failed in ${into}`, {
+      fix: `check that git works in ${into}`,
+    });
+  await must(
+    into,
+    ["clone", "--quiet", "--no-checkout", src, "repo"],
+    () =>
+      new CatherdError("E_INPUT_INVALID", `cannot clone ${src}`, {
+        fix: `catherd scorecard prepare ${task.id} --source <path or URL>`,
+      }),
+    GIT_LONG,
+  );
+  await must(
+    repo,
+    ["checkout", "--quiet", "-b", `scorecard/${task.id}`, task.commit],
+    () =>
+      new CatherdError("E_INPUT_INVALID", `${src} has no commit ${task.commit}`, {
+        fix: `catherd scorecard prepare ${task.id} --source <a clone that has it>`,
+      }),
+  );
+  await must(repo, ["remote", "remove", "origin"], io("git remote remove"));
+
+  if (task.inject) {
+    for (const e of task.inject.edits) {
+      const file = join(repo, e.path);
+      const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+      const parts = text.split(e.find);
+      if (parts.length !== 2)
+        throw new CatherdError(
+          "E_CONFIG_INVALID",
+          `${e.path}: the inject text is there ${parts.length - 1} times, not once`,
+          {
+            fix: `update scorecard/tasks/${task.id}/task.json`,
+          },
+        );
+      writeFileSync(file, parts.join(e.replace));
+    }
+    await must(repo, ["add", "-A"], io("git add"));
+    await must(
+      repo,
+      [
+        "-c",
+        "user.name=catherd-scorecard",
+        "-c",
+        "user.email=scorecard@catherd.invalid",
+        "commit",
+        "--quiet",
+        "-m",
+        task.inject.message,
+      ],
+      io("git commit"),
+    );
+  }
+
+  let plan: string;
+  if ("file" in task.plan) {
+    plan = join(into, "plan.md");
+    copyFileSync(join(i.root, "tasks", task.id, task.plan.file), plan);
+  } else {
+    plan = join(repo, task.plan.repoPath);
+    if (!existsSync(plan))
+      throw new CatherdError("E_CONFIG_INVALID", `${task.plan.repoPath} is not in ${src} at ${task.commit}`, {
+        fix: `update scorecard/tasks/${task.id}/task.json`,
+      });
+  }
+
+  let limits: string | null = null;
+  if (task.limits > 0) {
+    limits = join(into, "limits");
+    mkdirSync(join(limits, "taken"), { recursive: true });
+    mkdirSync(join(limits, "tokens"));
+    for (let n = 1; n <= task.limits; n++)
+      writeFileSync(join(limits, "tokens", String(n)), "", { flag: "w" });
+  }
+
+  if (i.setup) {
+    const env = await checkEnvFor(repo);
+    for (const cmd of task.setup) {
+      const r = await runCheck(repo, cmd, GIT_LONG, env);
+      if (r.code !== 0 || r.timedOut)
+        throw new CatherdError(
+          "E_IO_UNEXPECTED",
+          `setup \`${cmd}\` failed in ${repo}: ${r.tail.at(-1) ?? "no output"}`,
+          {
+            fix: `fix it and run it in ${repo}, or prepare again`,
+          },
+        );
+    }
+  }
+
+  const startCommit = (await must(repo, ["rev-parse", "HEAD"], io("git rev-parse"))).trim();
+  const prepared: Prepared = {
+    schema: 1,
+    task: task.id,
+    dir: into,
+    repo,
+    plan,
+    startCommit,
+    limits,
+    shim: limits ? join(i.root, "shim") : null,
+    preparedAt: i.now.toISOString(),
+    prompt: task.prompt.replaceAll("{plan}", () => plan).replaceAll("{acceptance}", () => task.acceptance),
+  };
+  writeJsonAtomic(join(into, "prepared.json"), prepared);
+  return prepared;
+}
+
+export function readPrepared(dir: string): Prepared {
+  const file = join(dir, "prepared.json");
+  if (!existsSync(file))
+    throw new CatherdError("E_INPUT_INVALID", `${dir} is not a prepared scorecard task`, {
+      fix: `catherd scorecard prepare ${SCORECARD_TASKS.join("|")}`,
+    });
+  return readVersioned(file, PreparedSchema, 1) as Prepared;
+}
+
+/** The one run to score: the named one, else the only open run created in the prepared repo since it was prepared. */
+function pickRun(p: Prepared, id: string | undefined): Run {
+  if (id) {
+    const run = findRun(id);
+    if (run.meta.repo !== p.repo)
+      throw new CatherdError("E_INPUT_INVALID", `run ${id} belongs to ${run.meta.repo}, not ${p.repo}`, {
+        fix: "name a run of the prepared repo, or leave --run out",
+      });
+    return run;
+  }
+  const since = Date.parse(p.preparedAt);
+  const runs = listRuns([p.repo]).runs.filter(
+    (r) => Date.parse(r.meta.createdAt) >= since && !supersededBy(r),
+  );
+  if (runs.length === 0)
+    throw new CatherdError("E_INPUT_INVALID", `no run in ${p.repo} yet`, {
+      fix: "run the task's start line, paste its prompt, and record once it has landed or been given up",
+    });
+  if (runs.length > 1)
+    throw new CatherdError("E_INPUT_INVALID", `${p.repo} has runs ${runs.map((r) => r.id).join(", ")}`, {
+      fix: `catherd scorecard record ${p.dir} --label <l> --run <id>`,
+    });
+  return runs[0] as Run;
+}
+
+export async function scoreTask(i: {
+  dir: string;
+  root: string;
+  run?: string;
+  chat?: number;
+  now: number;
+}): Promise<TaskScore> {
+  const p = readPrepared(i.dir);
+  const task = loadTask(p.task, i.root);
+  const run = pickRun(p, i.run);
+  const milestones = runMilestones(run);
+  const landed = landedMilestones(run);
+  const finished =
+    milestones.length > 0 &&
+    milestones.every((m) => landed.includes(m)) &&
+    openQuestions(run).length === 0 &&
+    !supersededBy(run);
+  const end = runEnd(run);
+  const start = Date.parse(run.meta.createdAt);
+
+  const copies = task.acceptFiles.map((f) => ({
+    from: join(i.root, "tasks", task.id, f.from),
+    to: join(p.repo, f.to),
+  }));
+  for (const c of copies)
+    if (existsSync(c.to))
+      throw new CatherdError(
+        "E_INPUT_INVALID",
+        `${c.to.slice(p.repo.length + 1)} already exists in the run's tree`,
+        {
+          fix: "the run wrote a file the hidden acceptance test needs; rename the file in the run, or score it by hand",
+        },
+      );
+  const done: string[] = [];
+  let check: Awaited<ReturnType<typeof runCheck>>;
+  const head = await gitHead(p.repo);
+  try {
+    for (const c of copies) {
+      mkdirSync(dirname(c.to), { recursive: true });
+      copyFileSync(c.from, c.to);
+      done.push(c.to);
+    }
+    check = await runCheck(
+      p.repo,
+      task.acceptance,
+      task.acceptanceTimeoutMin * 60_000,
+      await checkEnvFor(p.repo),
+    );
+  } finally {
+    for (const f of done) rmSync(f, { force: true });
+  }
+  const acceptance = {
+    passed: check.code === 0 && !check.timedOut,
+    code: check.code,
+    timedOut: check.timedOut,
+    tail: check.tail,
+  };
+
+  const outcomes = latestOutcomes(readOutcomes(run));
+  const takenDir = p.limits ? join(p.limits, "taken") : null;
+  return {
+    task: task.id,
+    run: run.id,
+    catherdVersion: run.meta.catherdVersion,
+    startCommit: p.startCommit,
+    head,
+    milestones,
+    landed,
+    finished,
+    interventions: interventionsOf(run, end, i.chat ?? 0),
+    reviewRounds: milestones.reduce((n, m) => n + reviewRounds(run, m), 0),
+    lanes: {
+      total: outcomes.length,
+      landed: outcomes.filter((o) => o.landed).length,
+      climbs: outcomes.reduce((n, o) => n + o.climbs.length, 0),
+    },
+    wallMinutes: minutes(end - start),
+    pausedMinutes: minutes(pausedMs(run, end)),
+    quota: {
+      backends: quotaByBackend(readRecords(run).records),
+      claudeAgentTokens: readAgentRuns(run).reduce((n, a) => n + a.totalTokens, 0),
+    },
+    acceptance,
+    firstTry: acceptance.passed && finished && new Set(landed).size === landed.length,
+    injected:
+      task.limits > 0
+        ? {
+            limits: takenDir && existsSync(takenDir) ? readdirSync(takenDir).length : 0,
+            standInOk: failoverRecovered(run),
+          }
+        : null,
+    recordedAt: new Date(i.now).toISOString(),
+  };
+}
+
+export const resultsFile = (dir: string, label: string): string => join(dir, `${assertLabel(label)}.json`);
+
+export function readScorecard(file: string): ScorecardFile | null {
+  return existsSync(file) ? assertScorecardRows(readVersioned(file, ScorecardFileSchema, 1), file) : null;
+}
+
+/** Sets the task's row in the label's file (a re-record replaces it) and returns the file's contents. */
+export function saveTaskScore(file: string, label: string, s: TaskScore): ScorecardFile {
+  const f = readScorecard(file) ?? { schema: 1 as const, label, tasks: {} };
+  f.tasks[s.task] = s;
+  ensurePrivateDir(dirname(file));
+  writeJsonAtomic(file, f);
+  return f;
+}

package/src/services/scratch.ts

@@ -0,0 +1,60 @@
+import { existsSync, lstatSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tryLock } from "../infra/filelock.ts";
+import { liveDispatches } from "./dispatches.ts";
+import { findRun, listRuns, type Run, runPaths } from "./run-store.ts";
+
+export interface ScratchCleaned {
+  /** the runs whose scratch folder was removed, with what it held */
+  removed: { run: string; bytes: number }[];
+  /** the runs left alone, and why: a role still writes there */
+  kept: { run: string; why: string }[];
+}
+
+/** The bytes under `dir`, links not followed; 0 for what cannot be read. */
+function sizeOf(dir: string): number {
+  let total = 0;
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      total += e.isDirectory() ? sizeOf(p) : (lstatSync(p, { throwIfNoEntry: false })?.size ?? 0);
+    }
+  } catch {
+    // gone or unreadable: counts as nothing
+  }
+  return total;
+}
+
+/**
+ * Spec 1.5 plan 21: `catherd runs clean [run]` removes the roles' scratch folders (`<run>/scratch/`, each role's
+ * TMPDIR) of a run with no live role, or of every such run. The run's own files, records and replies stay. A run
+ * whose admission is in progress is kept: that admission may have just created a role's scratch.
+ */
+export function cleanScratch(o: { run?: string; now?: number } = {}): ScratchCleaned {
+  const runs: Run[] = o.run ? [findRun(o.run)] : listRuns().runs;
+  const out: ScratchCleaned = { removed: [], kept: [] };
+  for (const run of runs) {
+    const dir = runPaths(run.dir).scratch;
+    if (!existsSync(dir)) continue;
+    // admission creates a role's scratch and admits its dispatch under this lock, so while cleanup holds it no
+    // scratch is half-admitted, and one an admission holds now belongs to a dispatch about to go live
+    const release = tryLock(runPaths(run.dir).admission);
+    if (!release) {
+      out.kept.push({ run: run.id, why: "a dispatch is being admitted" });
+      continue;
+    }
+    try {
+      const live = liveDispatches(run, o.now ?? Date.now());
+      if (live.length) {
+        out.kept.push({ run: run.id, why: `${live.map((d) => d.admit.name).join(", ")} still running` });
+        continue;
+      }
+      const bytes = sizeOf(dir);
+      rmSync(dir, { recursive: true, force: true });
+      out.removed.push({ run: run.id, bytes });
+    } finally {
+      release();
+    }
+  }
+  return out;
+}

package/src/services/sessions.ts

@@ -69,9 +69,11 @@ export function readSessionRows(run: Run): SessionRow[] {
 
 /**
  * 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. Without host session identity it changes nothing. Returns whether the owner changed.
+ * append it to `R/sessions.jsonl`: that is how a run moves when it is continued from another session. Without host session identity it changes nothing, and neither does a role's process (`deps.role`, spec 1.5 plan 21). Returns whether the owner changed.
  */
 export async function claimRun(deps: Deps, run: Run): Promise<boolean> {
+  // spec 1.5 plan 21: a role's process never becomes the run's owner, whatever host identity it has
+  if (deps.role) return false;
   const me = currentSession(deps);
   if (!me) return false;
   const p = runPaths(run.dir);

package/src/services/state.ts

@@ -19,6 +19,8 @@ const NotesSchema = z.looseObject({
   lastLandedAt: z.string().nullable(),
   /** spec 1.1 §8: the milestones waiting on the owner */
   parked: z.array(z.string()).optional(),
+  /** spec 1.5: what changed since the run's pin, as dispatch last saw it */
+  pinChanges: z.array(z.string()).optional(),
 });
 export type Notes = z.infer<typeof NotesSchema>;
 export type NotesPatch = Partial<Omit<Notes, "schema">>;
@@ -68,6 +70,7 @@ export function updateState(run: Run, change: NotesPatch | ((n: Notes) => NotesP
         brief: relative(run.dir, dispatchPaths(d.dir).brief),
       })),
       lastCheck: next.lastCheck,
+      pinChanges: next.pinChanges ?? [],
       next: next.next,
       protocol: protocolNext(run, next.parked ?? []),
     });
@@ -76,6 +79,24 @@ export function updateState(run: Run, change: NotesPatch | ((n: Notes) => NotesP
   });
 }
 
+/**
+ * Writes state.json's notes only, with no git, under the state lock; for a writer that must not wait on git
+ * while it holds another lock (`land` in a workspace, #43 finding 5). It waits out a refresh's git (15 s).
+ */
+export function patchNotes(run: Run, change: (n: Notes) => NotesPatch): Promise<Notes> {
+  const stateJson = runPaths(run.dir).stateJson;
+  return withFileLock(
+    stateJson,
+    () => {
+      const notes = readNotes(run);
+      const next = parkedNext({ ...notes, ...change(notes) });
+      writeJsonAtomic(stateJson, next);
+      return next;
+    },
+    { timeoutMs: 30_000 },
+  );
+}
+
 /**
  * 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.

package/src/services/summary.ts

@@ -3,16 +3,22 @@ import type { QueueCapability } from "../infra/codex-queue.ts";
 import { inspectionHost, inspectDeliveries, type DeliveryInspection } from "./run-debug.ts";
 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 { errorMessage, isCatherdError } from "../domain/errors.ts";
+import type { RunRecord, Tokens } from "../domain/record.ts";
+import type { QuotaRow } from "../domain/scorecard.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 { ensureDaemon } from "./daemon.ts";
+import { verifierStepView, type VerifierStepView } from "./verifier-step.ts";
+import { type Pause, pausesOver } from "./pause.ts";
+import { pinChanges } from "./run-pin.ts";
 import { type OpenQuestion, openQuestions } from "./questions.ts";
 import { type DispatchState, listDispatches, liveDispatches } from "./dispatches.ts";
+import { readDelivery, ROLE_THREAD_REFUSAL } from "../infra/delivery.ts";
 import { type RunSession, sessionFacts } from "./session-view.ts";
 import type { Deps } from "./ports.ts";
+import { orchestratorWait, type OrchestratorWait } from "./orchestrator-wait.ts";
 import {
   findRun,
   listRuns,
@@ -21,11 +27,18 @@ import {
   readRoutes,
   type Run,
   runPaths,
+  supersededBy,
 } from "./run-store.ts";
 
 export interface RunSummary {
+  /** No live roles and at least one durable completion the orchestrator has not collected. */
+  waiting?: OrchestratorWait | null;
   delivery: (DeliveryInspection & { name: string; dispatchId: string })[];
   id: string;
+  /** spec 1.5 "runs supersede": the run that took this one over; status() without a run hides it */
+  supersededBy?: string | null;
+  /** spec 1.5: what changed since the run's pin; dispatch keeps the pinned values */
+  pinChanges?: string[];
   /** spec 1.1 §8: the owner questions not answered yet, listed first */
   questions: OpenQuestion[];
   title: string;
@@ -45,14 +58,21 @@ export interface RunSummary {
   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;
+  /** spec 1.1 §7: the verifier's latest gate_check, so the user sees where it is; plan 22: its age, and what closed it */
+  verifier: VerifierStepView | 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 warnings: string[] = [];
+  // an unfinished 2.0 run whose daemon died gets it back from any reader: status, watch, the panel
+  try {
+    ensureDaemon(run);
+  } catch (e) {
+    warnings.push(`daemon: ${errorMessage(e)}`);
+  }
   const { records, corrupt } = readRecords(run);
   const live = liveDispatches(run, now);
   const recorded = new Set(records.map((r) => r.dispatchId));
@@ -60,7 +80,10 @@ export function summarizeRun(deps: Deps, run: Run): RunSummary {
   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)`] : [];
+  if (corrupt) warnings.push(`runs.jsonl: skipped ${corrupt} unreadable row(s)`);
+  // spec 1.5 "Pinned per run": a change since the pin, which dispatch does not follow
+  const pinned = pinChanges(deps, run);
+  for (const c of pinned) warnings.push(`pinned: ${c}; dispatch keeps the pinned value (run_pin re-pins)`);
   try {
     budget = budgetStatus(
       spendOf(run, records, live, now),
@@ -69,7 +92,18 @@ export function summarizeRun(deps: Deps, run: Run): RunSummary {
   } catch (e) {
     warnings.push(`budget: ${isCatherdError(e) ? e.message : String(e)}`);
   }
+  // spec 1.5 plan 21: a notice refused because its target was a role's thread, while that is its latest attempt
+  for (const d of listDispatches(run)) {
+    try {
+      const last = readDelivery(d.dir).at(-1);
+      if (last?.status === "failed" && last.reason?.startsWith(ROLE_THREAD_REFUSAL))
+        warnings.push(`${d.admit.name}: its notice was not sent: ${last.reason}`);
+    } catch {
+      // unreadable delivery evidence is the delivery row's to show
+    }
+  }
   return {
+    waiting: orchestratorWait(run, now, records, live.length > 0),
     delivery: listDispatches(run).flatMap((d) =>
       inspectDeliveries(run, d, recorded.has(d.admit.dispatchId)).map((inspection) => ({
         name: d.admit.name,
@@ -78,6 +112,8 @@ export function summarizeRun(deps: Deps, run: Run): RunSummary {
       })),
     ),
     id: run.id,
+    supersededBy: supersededBy(run)?.by ?? null,
+    pinChanges: pinned,
     questions: openQuestions(run),
     title: run.meta.title,
     repo: run.meta.repo,
@@ -116,40 +152,53 @@ export function summarizeRun(deps: Deps, run: Run): RunSummary {
     }),
     budget,
     milestones: nonBlankLines(runPaths(run.dir).ledger).slice(1),
-    verifier: latestVerifierStep(run),
+    verifier: verifierStepView(run, now),
     warnings,
   };
 }
 
-/** `status(run?)`: that run; without one, every run with a live role, else the newest run. */
+/**
+ * `status(run?)`: that run; without one, the live runs, else the runs waiting for their orchestrator (a current
+ * owner, a recent unread record: plan 22), else the newest run.
+ */
 export function status(
   deps: Deps,
   runId?: string,
   queue: QueueCapability | null = null,
 ): {
+  /** spec 1.5 "Group pause": the machine's pause and the listed runs' workspace pauses, shown first */
+  paused: Pause[];
   version: string;
   runs: RunSummary[];
   warnings: string[];
   host: HostContext;
   queue: QueueCapability | null;
 } {
-  if (runId)
+  if (runId) {
+    const run = findRun(runId);
     return {
+      paused: pausesOver([run]),
       host: inspectionHost(deps.host),
       queue,
       version: deps.version,
-      runs: [summarizeRun(deps, findRun(runId))],
+      runs: [summarizeRun(deps, run)],
       warnings: [],
     };
-  const { runs, corrupt } = listRuns();
+  }
+  const { runs: listed, corrupt } = listRuns();
   const warnings = corrupt.map((c) => `skipped run ${c.id}: ${c.reason}`);
+  // a superseded run is closed: only status(run) shows it
+  const runs = listed.filter((r) => !supersededBy(r));
   const all = runs.map((r) => summarizeRun(deps, r));
   const live = all.filter((s) => s.live.length > 0);
+  const waiting = all.filter((s) => s.waiting);
+  const shown = live.length ? live : waiting.length ? waiting : all.slice(0, 1);
   return {
+    paused: pausesOver(runs.filter((r) => shown.some((s) => s.id === r.id))),
     host: inspectionHost(deps.host),
     queue,
     version: deps.version,
-    runs: live.length ? live : all.slice(0, 1),
+    runs: shown,
     warnings,
   };
 }
@@ -210,6 +259,21 @@ function harnessCosts(runs: Run[]): HarnessCost[] {
   });
 }
 
+/** Plan 28: tokens and usage limits per backend over `records`, sorted by backend. */
+export function quotaByBackend(records: RunRecord[]): QuotaRow[] {
+  const by = new Map<string, QuotaRow>();
+  for (const r of records) {
+    const q = by.get(r.backend) ?? { backend: r.backend, runs: 0, input: 0, cached: 0, output: 0, limits: 0 };
+    q.runs++;
+    q.input += r.tokens.input;
+    q.cached += r.tokens.cached;
+    q.output += r.tokens.output;
+    if (r.status === "limit") q.limits++;
+    by.set(r.backend, q);
+  }
+  return [...by.values()].sort((a, b) => a.backend.localeCompare(b.backend));
+}
+
 /** 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[];