@opsee/cli 0.11.9

package/src/foreman/core/views.ts

@@ -0,0 +1,940 @@
+/**
+ * The Foreman's three read-only views, as text (OPS-280; see ../../../CONTEXT.md: Slot, Account,
+ * Paused, Run Record, Hand-off, Defect, Breaker, Proposed Learning, Process Table).
+ *
+ * `status` is the Process Table and the Accounts file, side by side: how many Slots each Account
+ * has and how many are spent, the Workers alive right now, and every Paused Account and paused
+ * Initiative with when it lifts. `logs` is one Worker's transcript. `review` is the Run Record
+ * regrouped by what a human does with it in the morning: Hand-offs to look at, Defects filed,
+ * Breakers hit, Proposed Learnings to accept.
+ *
+ * Everything here renders to a terminal, and almost nothing it renders is text a person wrote.
+ * A Task's identifier and title come from the Tracker; an Account's pause reason is the vendor's
+ * own sentence; a Gate's name and command, a Defect's title, a Verifier's evidence URL and a
+ * Worker's assistant output are all written by an agent or printed by a command, and a
+ * full-privilege Worker may edit the Run Recipe inside its Workspace. mcp/src/utils/format/
+ * run-record.ts renders the same events into Markdown and treats every such string as hostile;
+ * this file owes the same discipline to a different target, where the hazard is not a heading
+ * marker but an ANSI escape that repaints the screen, a `\r` that overwrites the line just
+ * printed, or a bidi override that reverses what a name reads as. So every value that comes off an
+ * event, a row, an Account or a Task goes through `printableOneLine` (core/text.ts, OPS-277),
+ * which collapses whitespace and then drops the whole `Cc`/`Cf` range. There is no second
+ * treatment and no exception: a field that is too long is clamped by the same call.
+ *
+ * Two things that discipline does *not* buy on its own, and which this file handles separately.
+ * Stripping the control ranges does not make `String.length` a column count — five CJK characters
+ * are five units long and ten columns wide, and an emoji is one code point and two columns — so
+ * the table pads by `width` below rather than by `.length`. And `safe` is fed values that a type
+ * says are strings but a `JSON.parse` of a Worker-written transcript line may make anything at
+ * all, so it coerces rather than trusting the declared type: one crafted append must not be able
+ * to end `opsee foreman logs` with a TypeError.
+ */
+import type { RunEvent } from "@opsee/mcp-server/gen/api/v1/initiative_pb.js";
+import type { Account } from "../account.js";
+import { pausedUntil } from "../account.js";
+import type { TrackerTask } from "../tracker-adapter.js";
+import { gateVerdictOf, GATE_SKIPPED_SUMMARY } from "./gates.js";
+import { STATUS_LABELS } from "./run.js";
+import { verdictStatusOf } from "./verifier.js";
+import { DISPATCH_PID_GRACE_MS, pidIsAlive, type WorkerRow } from "./process-table.js";
+import { Slots } from "./scheduler.js";
+import { count, printableOneLine } from "./text.js";
+
+/** How much of a name, a title or a URL is printed on a line of a table or a list. Longer than the
+ * vendor-prose limit `printableOneLine` defaults to, because a Task title and a pull request URL
+ * are both meant to be read whole, and short enough that one poisoned field cannot own the view. */
+export const FIELD_LIMIT = 200;
+
+/** How much of one line of a Worker's transcript or a Defect's steps is printed. A wide terminal,
+ * not a paragraph: the transcript file and the pull request hold the rest. */
+export const LINE_LIMIT = 500;
+
+/**
+ * One field on a line of this view's own prose. See the module comment: never a raw string.
+ *
+ * `unknown`, not `string | undefined`, on purpose. Every other caller does hand it a string, but
+ * `formatTranscriptLine` hands it fields off a `JSON.parse` of a line a Worker appended, where the
+ * declared type is a hope rather than a fact: `{"type":"tool","name":42}` is well-formed JSON and
+ * a `number` where a `string` was promised. This is the one chokepoint every printed value goes
+ * through, so a throw here is a crash of the whole command; it coerces instead. A number or a
+ * boolean reads as itself, an object or an array becomes a marker rather than `[object Object]` or
+ * a `toString` that could itself throw, and nothing reaches the terminal unstripped either way.
+ */
+export function safe(text: unknown, limit = FIELD_LIMIT): string {
+  if (typeof text === "string") return printableOneLine(text, limit);
+  if (text === undefined || text === null) return "";
+  if (typeof text === "number" || typeof text === "boolean" || typeof text === "bigint") return printableOneLine(String(text), limit);
+  return `(${Array.isArray(text) ? "array" : typeof text})`;
+}
+
+/** `safe`, but empty text becomes a visible stand-in rather than a hole in the line. */
+function safeOr(text: unknown, fallback: string, limit = FIELD_LIMIT): string {
+  const value = safe(text, limit);
+  return value === "" ? fallback : value;
+}
+
+/** Characters a terminal draws two columns wide: the CJK and Hangul blocks, the fullwidth forms,
+ * and the emoji that default to an emoji presentation. Not exhaustive — East_Asian_Width is not a
+ * property JavaScript's regexes expose, and a terminal's own idea of a width is its business — but
+ * it covers what a Task title or an Account name realistically carries. */
+const WIDE =
+  /^(?:[\u1100-\u115F\u2E80-\u303E\u3041-\u33FF\u3400-\u4DBF\u4E00-\u9FFF\uA000-\uA4CF\uA960-\uA97F\uAC00-\uD7A3\uF900-\uFAFF\uFE10-\uFE19\uFE30-\uFE6F\uFF00-\uFF60\uFFE0-\uFFE6]|[\u{17000}-\u{18AFF}]|[\u{20000}-\u{3FFFD}]|\p{Emoji_Presentation})$/u;
+
+/**
+ * How many terminal columns a string takes.
+ *
+ * Not `.length`: that is UTF-16 code units, and the two differ in both directions. `日本語です` is
+ * five units and ten columns; `😀` is two units and two columns; a combining acute is one unit and
+ * no column at all. Stripping the `Cc`/`Cf` ranges does nothing about any of that, so a Japanese
+ * Account name — or a hostile one made of combining marks — would knock every row below it out of
+ * line if the padding measured units. Zero-width joiners and variation selectors are `Cf` and are
+ * already gone by the time a cell gets here.
+ */
+export function width(text: string): number {
+  let columns = 0;
+  for (const ch of text) {
+    if (/^[\p{Mn}\p{Me}]$/u.test(ch)) continue;
+    columns += WIDE.test(ch) ? 2 : 1;
+  }
+  return columns;
+}
+
+/** A fixed-width table from already-`safe` cells: the header, then the rows, columns padded to the
+ * widest cell. The last column is never padded, so a long final value does not trail spaces. */
+export function table(rows: string[][]): string[] {
+  if (rows.length === 0) return [];
+  const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => width(r[i] ?? ""))));
+  return rows.map((r) => r.map((cell, i) => (i === r.length - 1 ? cell : `${cell ?? ""}${" ".repeat(Math.max(0, widths[i] - width(cell ?? "")))}`)).join("  "));
+}
+
+/** `2m`, `1h04m`, `3d02h`: how long ago something was, for a column that must stay narrow. */
+export function age(ms: number): string {
+  if (ms < 0) return "0s";
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h${String(m % 60).padStart(2, "0")}m`;
+  return `${Math.floor(h / 24)}d${String(h % 24).padStart(2, "0")}h`;
+}
+
+// --- status ---------------------------------------------------------------------------------
+
+/**
+ * One Account's Slots as the Process Table shows them (`Slot`, CONTEXT.md).
+ *
+ * The Slots themselves are a Run's, held in that process's `Slots` object (core/scheduler.ts);
+ * another process cannot read them. What it can read is the one thing the two share, the Process
+ * Table: a row per Worker the Foreman has running. So a Slot in use is counted as a row, and the
+ * Account's own arithmetic — how many of its `cap` are implementer Slots, whether it reserves one
+ * for Verifiers — is taken from `Slots` itself rather than restated here, so the two can never
+ * drift.
+ *
+ * `verifying` is a floor at cap 2 and above, and the view says so. A dispatch in its Verifier
+ * round holds the reserved Slot rather than an implementer one, and the only trace of a round on
+ * the row is `appPid`, the pid of the app the round started (core/run.ts). A Verifier round on a
+ * repository whose Run Recipe starts no app therefore looks like an implementer here, which costs
+ * one implementer Slot on paper and never the other way round.
+ *
+ * At cap 1 there is no reserved Slot at all — `Slots.enterVerification` returns at once when
+ * `reservesVerifierSlot` is false — so a Verifier round there keeps the implementer Slot it
+ * already had, while `run.ts` sets `appPid` on the row regardless of cap. Counting that row as
+ * verifying would subtract it from the implementers and invent an implementer Slot that the
+ * running Foreman will never dispatch into, which is the one direction this must not err in. So
+ * `verifying` is forced to 0 at cap 1: the round is counted as what it is holding.
+ *
+ * The remaining honest caveat is that `free` is derived from `cap` as the Accounts file reads it
+ * *now*, while a live Run pinned its `Slots` to the cap the file had when it started
+ * (`new Slots(account.cap)`, core/run.ts). `foreman account set --cap` between the two leaves this
+ * view arithmetically right about the file and wrong about the Run, and there is nothing in the
+ * Process Table that would say so. Short of that — and short of a Run that a cap change has
+ * outlived — `free` is never reported higher than it really is.
+ */
+export interface AccountSlots {
+  account: Account;
+  /** Worker rows on this Account whose Worker is still there: one per turn really running. */
+  used: number;
+  /** Of those, the ones a Verifier round has an app running for (see above: a floor above cap 1,
+   * and always 0 at cap 1, where a round holds no Slot of its own). */
+  verifying: number;
+  /** Rows that are not visibly verifying, so they are counted against the implementer Slots. */
+  implementers: number;
+  /** Slots that are not implementers': the reserved Verifier Slot, 1 or 0 (`cap` 1 reserves none). */
+  reserved: number;
+  /** Implementer Slots a Ready Task could take right now, floored at 0. */
+  free: number;
+  /** Rows on this Account whose process is gone: counted in no Slot, still listed as Workers. */
+  stale: number;
+}
+
+/**
+ * Whether a Worker row still stands for a Worker, by the rule `otherForemanWorkersOn` applies when
+ * it decides whether an Account has room (core/process-table.ts).
+ *
+ * The rows outlive the Foreman that wrote them: a SIGKILLed Run leaves every one of its rows
+ * behind, and nothing sweeps them but the next Reconcile. Counting those as Slots in use would
+ * have `status` report a full fleet on an empty machine, while `foreman run` on that same Account
+ * is permitted and dispatches — the exact misreading `status` exists to prevent, in the other
+ * direction. A row with no pid inside the dispatch-commit-to-launch window is a Foreman that
+ * really is starting a Worker and no pid check can see it, so it counts.
+ */
+export function rowIsRunning(row: WorkerRow, at: number, isAlive: (pid: number | undefined) => boolean = pidIsAlive): boolean {
+  if (row.pid !== undefined) return isAlive(row.pid);
+  return at - row.startedAt < DISPATCH_PID_GRACE_MS;
+}
+
+export interface SlotsOptions {
+  now: number;
+  isAlive?: (pid: number | undefined) => boolean;
+}
+
+/** Every registered Account with its Slots, in the order the Accounts file has them. */
+export function accountSlots(accounts: Account[], rows: WorkerRow[], options: SlotsOptions): AccountSlots[] {
+  const { now, isAlive } = options;
+  return accounts.map((account) => {
+    const all = rows.filter((r) => r.account === account.name);
+    const mine = all.filter((r) => rowIsRunning(r, now, isAlive));
+    // The Account's own arithmetic, not a copy of it. A cap the accounts file should never hold
+    // (`registerAccount` and `FileAccountStore.load` both refuse one) would throw in `Slots`; a
+    // read-only view reports it instead of dying on someone else's bad file.
+    let implementerCap = Math.max(1, account.cap - 1);
+    let reservesVerifierSlot = account.cap > 1;
+    try {
+      const slots = new Slots(account.cap);
+      implementerCap = slots.implementerCap;
+      reservesVerifierSlot = slots.reservesVerifierSlot;
+    } catch {
+      // Left as the fallback above; the cap is printed as it stands, so the file's own value shows.
+    }
+    // See above: at cap 1 the round is in the implementer's own Slot, so `appPid` says nothing
+    // about which Slot is held and must not be allowed to conjure a free one.
+    const verifying = reservesVerifierSlot ? mine.filter((r) => r.appPid !== undefined).length : 0;
+    const implementers = mine.length - verifying;
+    return {
+      account,
+      used: mine.length,
+      verifying,
+      implementers,
+      reserved: reservesVerifierSlot ? 1 : 0,
+      // A quarantined Account has no free Slot to report, whatever its cap and whatever is running
+      // on it (OPS-288): the Run will not dispatch there, so a number above zero would be an
+      // invitation `foreman run` does not honour. Its live Workers are still counted and listed —
+      // they were started while the credential worked and may still finish.
+      free: account.quarantined ? 0 : Math.max(0, implementerCap - implementers),
+      stale: all.length - mine.length,
+    };
+  });
+}
+
+/** Worker rows on an Account no registered Account matches: a de-registered Account, or a row from
+ * another machine's accounts file. They are in the Workers table but in no Account's `USED`, so
+ * `status` says so rather than letting the two sections quietly disagree. */
+export function unregisteredAccounts(accounts: Account[], rows: WorkerRow[]): Array<{ account: string; rows: number }> {
+  const known = new Set(accounts.map((a) => a.name));
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    if (known.has(row.account)) continue;
+    counts.set(row.account, (counts.get(row.account) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([account, n]) => ({ account, rows: n }));
+}
+
+export interface StatusInput {
+  accounts: Account[];
+  /** Every Worker row, whatever its Initiative or Account (`ProcessTable.liveWorkers()`). */
+  rows: WorkerRow[];
+  /** Initiatives a human has paused (`ProcessTable.pausedInitiatives()`). */
+  paused: Array<{ initiativeId: number; pausedAt: number }>;
+  /** Where the table lives, so a reader knows which machine's fleet this is. */
+  tablePath: string;
+  now: number;
+  /** Seam for the pid check the Slot arithmetic and the STATE column share; the real one by
+   * default. Tests inject it because a test's pid numbers are not this machine's processes. */
+  isAlive?: (pid: number | undefined) => boolean;
+}
+
+/** What a row's `control` mark and pid say about the Worker, in one word for the STATE column. */
+function workerState(row: WorkerRow, now: number, isAlive?: (pid: number | undefined) => boolean): string {
+  // First, because it is the one that changes what the other words mean: a row whose Worker is
+  // gone is a leftover of a Foreman that died, and calling it "attached" or "running" is how a
+  // reader concludes the fleet is full when it is empty. `USED` does not count it either.
+  if (!rowIsRunning(row, now, isAlive)) return "gone";
+  if (row.control === "attached") return "attached";
+  if (row.control === "released") return "released";
+  if (row.control === "cancelled") return "cancelled";
+  if (row.appPid !== undefined) return "verifying";
+  if (row.pid === undefined) return row.sessionId === undefined ? "starting" : "no pid";
+  return "running";
+}
+
+/**
+ * `opsee foreman status`: the Slots, the Workers and the Paused state, read fresh.
+ *
+ * Nothing is cached and nothing is derived from a previous call — the table is SQLite on disk that
+ * the Run writes, so one read is one tick's worth of truth, which is what "reflects the Process
+ * Table within one tick of a change" asks for.
+ */
+export function formatStatus(input: StatusInput): string[] {
+  const { rows, now } = input;
+  const isAlive = input.isAlive;
+  const lines: string[] = [];
+  const slots = accountSlots(input.accounts, rows, { now, isAlive });
+
+  lines.push(`Process Table: ${safe(input.tablePath, LINE_LIMIT)}`);
+  lines.push("");
+
+  lines.push("Accounts");
+  if (input.accounts.length === 0) {
+    lines.push("  No Account registered; register one with: opsee foreman account add --vendor claude --config-dir <dir>");
+  } else {
+    const body = slots.map((s) => {
+      const until = pausedUntil(s.account, now);
+      const reason = s.account.paused?.reason ? ` (${safe(s.account.paused.reason)})` : "";
+      // Quarantine is reported ahead of a pause and instead of it (OPS-288). An Account may well
+      // have been Paused before its credential died, but only one of the two facts still asks the
+      // reader for anything, and only one of them will not lift on its own.
+      const state = s.account.quarantined
+        ? `quarantined since ${safe(s.account.quarantined.at)} (${safe(s.account.quarantined.reason)}); opsee foreman account resume ${safe(s.account.name)}`
+        : until
+          ? `Paused until ${safe(until.toISOString())}${reason}`
+          : s.account.paused
+            ? `active (pause lapsed ${safe(s.account.paused.until)})`
+            : "active";
+      return [
+        safe(s.account.name),
+        safe(s.account.vendor),
+        String(s.account.cap),
+        String(s.used),
+        String(s.reserved),
+        String(s.free),
+        state,
+      ];
+    });
+    for (const line of table([["ACCOUNT", "VENDOR", "CAP", "USED", "RESERVED", "FREE", "STATE"], ...body])) lines.push(`  ${line}`);
+    const verifying = slots.reduce((n, s) => n + s.verifying, 0);
+    const stale = slots.reduce((n, s) => n + s.stale, 0);
+    lines.push(
+      `  USED is the Worker rows on the Account whose Worker is still there, RESERVED its Verifier Slot (every Account above cap 1 keeps one), FREE the implementer Slots a Ready Task could take.` +
+        (verifying ? ` ${count(verifying, "Worker")} of those rows is in a Verifier round and holds the reserved Slot rather than an implementer one.` : "") +
+        (stale ? ` ${count(stale, "row")} below is marked gone — its process is not there — and is counted in no Account's USED.` : ""),
+    );
+    lines.push(
+      `  FREE is read from the Accounts file's cap as it stands now; a Run that was started before opsee foreman account set --cap pinned the old one and will not fill a Slot this adds.`,
+    );
+  }
+  const unregistered = unregisteredAccounts(input.accounts, rows);
+  if (unregistered.length > 0) {
+    lines.push(
+      `  ${count(
+        unregistered.reduce((n, u) => n + u.rows, 0),
+        "Worker",
+      )} on ${count(unregistered.length, "Account")} this machine has not registered (${unregistered.map((u) => `${safe(u.account)} ×${u.rows}`).join(", ")}): listed under Workers below, counted in no USED above.`,
+    );
+  }
+  lines.push("");
+
+  lines.push(`Workers (${rows.length})`);
+  if (rows.length === 0) {
+    lines.push("  None: no Foreman on this machine has a Worker running.");
+  } else {
+    const body = rows.map((r) => [
+      safe(r.identifier),
+      String(r.initiativeId),
+      safe(r.account),
+      safe(r.vendor),
+      String(r.attempt),
+      r.pid === undefined ? "—" : String(r.pid),
+      age(now - r.startedAt),
+      age(now - r.lastOutputAt),
+      workerState(r, now, isAlive),
+    ]);
+    for (const line of table([["TASK", "INITIATIVE", "ACCOUNT", "VENDOR", "ATTEMPT", "PID", "AGE", "QUIET", "STATE"], ...body])) lines.push(`  ${line}`);
+    lines.push("  AGE is since the turn started, QUIET since its last output. A row with no pid is a dispatch that has not launched yet, or one whose Worker Adapter reports none.");
+    lines.push("  STATE gone is a row whose process is not there — a Foreman that was killed leaves its rows behind, and the next Reconcile settles them; it holds no Slot in the meantime.");
+  }
+  lines.push("");
+
+  lines.push(`Paused Initiatives (${input.paused.length})`);
+  if (input.paused.length === 0) {
+    lines.push("  None: no Run on this machine is holding new dispatch (opsee foreman pause <initiativeId>).");
+  } else {
+    for (const p of input.paused) {
+      lines.push(`  Initiative ${p.initiativeId}: paused ${age(now - p.pausedAt)} ago; in-flight Workers finish, no new dispatch until: opsee foreman resume ${p.initiativeId}`);
+    }
+  }
+
+  return lines;
+}
+
+// --- logs -----------------------------------------------------------------------------------
+
+/** One line of a transcript file: the adapter event, plus the `at` the store stamps it with
+ * (core/transcripts.ts). Every field is `unknown` rather than optionally its own type, because the
+ * file is read as it stands: a line half-written by a Worker that was killed mid-append is a line
+ * this must survive, and so is `{"type":"tool","name":42}`, which is well-formed JSON that no
+ * declared type makes true. The Worker writing the file is the thing this view is watching, at
+ * full privilege on this machine; the shapes below are what it chose to write, not a contract. */
+interface TranscriptEvent {
+  at?: unknown;
+  type?: unknown;
+  text?: unknown;
+  name?: unknown;
+  message?: unknown;
+  reason?: unknown;
+  resetAt?: unknown;
+  sessionId?: unknown;
+  silentMs?: unknown;
+  details?: unknown;
+  report?: unknown;
+}
+
+/** `10:15:03` from the ISO stamp the transcript store writes, or blank when the line has none or
+ * the line's `at` is not a stamp at all. */
+function clock(at: unknown): string {
+  if (typeof at !== "string" && typeof at !== "number") return "        ";
+  const d = new Date(at);
+  return Number.isFinite(d.getTime()) ? d.toISOString().slice(11, 19) : "        ";
+}
+
+/** A `report` off a transcript line, when it is an object at all: `{"type":"completed","report":7}`
+ * is as writable as the real shape, and `(7).outcome` is `undefined` rather than a throw only by
+ * luck of JavaScript's rules. Read it explicitly instead. */
+function reportOf(value: unknown): { outcome?: unknown; summary?: unknown } {
+  return typeof value === "object" && value !== null ? (value as { outcome?: unknown; summary?: unknown }) : {};
+}
+
+/**
+ * One JSONL line of a transcript as a human reads it, or several for a multi-line assistant
+ * message: the timestamp, what kind of event it was, and its text.
+ *
+ * Every part of the payload is the vendor's — the assistant's own prose, a tool name it chose, the
+ * vendor's error text — so each printed line goes through `safe` on its own. Splitting first and
+ * flattening each piece keeps the shape of a code block or a list the Worker printed while still
+ * dropping every escape and carriage return in it; collapsing the whole message to one line would
+ * be just as safe and much harder to read.
+ *
+ * A line that is not JSON at all is printed as the raw text it is, flattened the same way: a
+ * truncated append is worth seeing, not worth crashing on.
+ */
+export function formatTranscriptLine(raw: string): string[] {
+  const line = raw.trim();
+  if (!line) return [];
+  let event: TranscriptEvent;
+  try {
+    const parsed: unknown = JSON.parse(line);
+    if (typeof parsed !== "object" || parsed === null) return [`         ? ${safe(line, LINE_LIMIT)}`];
+    event = parsed as TranscriptEvent;
+  } catch {
+    return [`         ? ${safe(line, LINE_LIMIT)}`];
+  }
+  const at = clock(event.at);
+  const say = (mark: string, text: string): string => `${at} ${mark} ${text}`;
+  const report = reportOf(event.report);
+  switch (event.type) {
+    case "output": {
+      // `safe` first when the text is not a string: only a real string has lines to split, and a
+      // number or an object has to become one before `.split` is reached at all.
+      const text = typeof event.text === "string" ? event.text : safe(event.text, LINE_LIMIT);
+      const body = text.split("\n").map((l) => safe(l, LINE_LIMIT)).filter((l, i, all) => l !== "" || (i > 0 && i < all.length - 1));
+      return body.length === 0 ? [] : body.map((l) => say("|", l));
+    }
+    case "tool":
+      return [say("·", `tool ${safeOr(event.name, "(unnamed)")}`)];
+    case "started":
+      return [say("+", `started, session ${safeOr(event.sessionId, "(none)")}`)];
+    case "rate_limited": {
+      const until = safe(event.resetAt);
+      return [say("!", `rate limited${until ? ` until ${until}` : ""}: ${safe(event.message, LINE_LIMIT)}`)];
+    }
+    case "stalled": {
+      const silent = Number(event.silentMs ?? 0);
+      return [say("!", `stalled: no output for ${Number.isFinite(silent) ? silent : 0}ms`)];
+    }
+    case "completed": {
+      const summary = safe(report.summary, LINE_LIMIT);
+      return [say("=", `completed: ${safeOr(report.outcome, "(no outcome)")}${summary ? ` — ${summary}` : ""}`)];
+    }
+    case "failed":
+      return [say("=", `failed (${safeOr(event.reason, "unknown")}): ${safe(event.message, LINE_LIMIT)}`)];
+    default:
+      return [say("?", safe(line, LINE_LIMIT))];
+  }
+}
+
+/** Where a Worker's transcript is and whether the Worker is still writing to it. */
+export interface TranscriptTarget {
+  path: string;
+  identifier: string;
+  initiativeId: number;
+  attempt: number;
+  /** The Process Table row, when the Worker is still one the Foreman believes is running. */
+  row?: WorkerRow;
+}
+
+/**
+ * The header `logs` prints before the first line, which says which of the two things it is showing
+ * — a live stream or the stored tail of a turn that is over — because the two look the same once
+ * the lines start.
+ *
+ * Two separate facts, and they must not be conflated. Whether the turn is over is `target.row`:
+ * the Run removes the row when a turn settles, so a row present means a Worker is running,
+ * whatever this command was asked to do about it. Whether this invocation will follow the file is
+ * `live`, which `--no-follow` turns off on a Worker that is very much still running. Branching the
+ * *claim* on `live` would have `--no-follow` announce that a turn is over while the row it just
+ * read the path out of says otherwise, and an operator who believes it stops waiting.
+ */
+export function transcriptHeader(target: TranscriptTarget, options: { live: boolean; tail: number }): string[] {
+  const where = `${safe(target.identifier)} attempt ${target.attempt} · Initiative ${target.initiativeId} · ${safe(target.path, LINE_LIMIT)}`;
+  const row = target.row;
+  if (row && options.live) {
+    return [
+      `Streaming ${where}`,
+      `The Worker is running on Account ${safe(row.account)}${row.pid === undefined ? " (no pid reported)" : ` (pid ${row.pid})`}; new output appears as it arrives. Ctrl-C to stop watching — it does not stop the Worker.`,
+      "",
+    ];
+  }
+  if (row) {
+    return [
+      `Snapshot of ${where}`,
+      `The Worker is still running on Account ${safe(row.account)}${row.pid === undefined ? " (no pid reported)" : ` (pid ${row.pid})`}: this is the last ${count(options.tail, "line")} as the file stands right now, and --no-follow means nothing more is printed. Drop --no-follow to watch it.`,
+      "",
+    ];
+  }
+  return [
+    `Stored tail of ${where}`,
+    `This turn is over: the Process Table has no Worker on the Task, so this is the last ${count(options.tail, "line")} of the transcript it left behind, not a live stream.`,
+    "",
+  ];
+}
+
+// --- review ---------------------------------------------------------------------------------
+
+/** A Task as `review` names it: by identifier and title, never by id alone.
+ *
+ * `labels` is here because the Status Label is the only place a Task blocked *before* any attempt
+ * is recorded at all — the Foreman refuses those without appending to the Run Record, since nothing
+ * was dispatched. It costs nothing to carry: `getInitiativeContext` already returns whole
+ * `TrackerTask`s and the command used to narrow them away. */
+export type NamedTask = Pick<TrackerTask, "id" | "identifier" | "title" | "url" | "labels">;
+
+export interface ReviewInput {
+  initiativeId: number;
+  initiative?: { title: string; status: string };
+  run?: { status: string; eventCount: number | bigint };
+  /** The Run Record in id order, as `readRunRecord` returns it. */
+  events: RunEvent[];
+  /** Every Task of the Initiative, by id: what turns a `task_id` on an event into a name. */
+  tasks: Map<number, NamedTask>;
+  /** The Initiative's memory entries of kind `learning`, newest first (core/context.ts reads the
+   * same ones for sibling Workers). */
+  learnings: Array<{ body: string; sourceTaskId?: number; isAgent: boolean }>;
+  /** Set when the Initiative's task list could not be read. `tasks` is then empty, which the
+   * Blocked section must report as "not known" rather than render as "nothing is blocked": the
+   * Status Label lives on the Task, so no task list means no answer, not an empty one. */
+  tasksUnavailable?: boolean;
+}
+
+/** `OPS-280 "Give the terminal its three views"`, or the id when the Initiative's task list has no
+ * such Task (a Defect filed into another Initiative, a Task deleted since). */
+export function nameTask(tasks: Map<number, NamedTask>, id: number | undefined): string {
+  if (id === undefined) return "(no Task)";
+  const task = tasks.get(id);
+  if (!task) return `Task ${id} (not on this Initiative)`;
+  const title = safe(task.title);
+  return `${safeOr(task.identifier, `Task ${id}`)}${title ? ` "${title}"` : ""}`;
+}
+
+/**
+ * One Hand-off a human has to look at: the newest attempt event that named a pull request, per
+ * URL. A Task that was handed off and then re-dispatched has one entry, not one per attempt.
+ *
+ * The key is the URL alone, not the URL and the Task. That is deliberate — one pull request is one
+ * thing to read, and its state is whatever the last attempt left it at — but it has a consequence
+ * worth naming: two Tasks that both named the same pull request collapse into a single entry
+ * carrying whichever `task_id` came later on the Record. The list counts pull requests to review,
+ * so that is the right count; it is not a list of every Task that touched one.
+ */
+export interface ReviewHandOff {
+  url: string;
+  taskId?: number;
+  attempt: number;
+  outcome: string;
+  /** True when this attempt's Gates were skipped: nothing on the machine ran the repository's
+   * tests, lint or typecheck against the Hand-off, so it reached In review unchecked. Read off the
+   * attempt event's own Gates line (`GATE_SKIPPED_SUMMARY`), which is where `settle` puts it. */
+  gatesSkipped?: boolean;
+  /** What the Gates said about this attempt, and what the Verifier said: the two facts that decide
+   * whether the pull request is a human's to read or the Foreman's to come back to. */
+  gates: "passed" | "failed" | "none";
+  verdict: "passed" | "failed" | "none";
+}
+
+/** A Hand-off the Foreman itself does not consider ready: its Gates failed, or its Verifier found
+ * Defects. The pull request is open and linked either way, which is exactly why it has to be told
+ * apart from one that passed — a list that mixes them sends a human to read work the Foreman
+ * already knows is not finished. */
+export function isHeld(h: ReviewHandOff): boolean {
+  return h.gates === "failed" || h.verdict === "failed";
+}
+
+/** Why it is held, in the order a reader wants it: the Gates first, since a failed Gate is why the
+ * Verifier never ran. */
+export function heldReason(h: ReviewHandOff): string {
+  const reasons: string[] = [];
+  if (h.gates === "failed") reasons.push("the Gates failed");
+  if (h.verdict === "failed") reasons.push("the Verifier found Defects");
+  return reasons.join(" and ");
+}
+
+export function handOffsOf(events: RunEvent[], tasks?: Map<number, NamedTask>): ReviewHandOff[] {
+  const byUrl = new Map<string, ReviewHandOff>();
+  // One pass per Task rather than per Hand-off: both helpers below walk the Task's whole slice of
+  // the Record, and a Task with several attempts would otherwise walk it once per attempt.
+  const byTask = new Map<number, RunEvent[]>();
+  for (const event of events) {
+    if (event.taskId === undefined) continue;
+    byTask.set(event.taskId, [...(byTask.get(event.taskId) ?? []), event]);
+  }
+  for (const event of events) {
+    const payload = event.payload?.payload;
+    if (payload?.case !== "attempt") continue;
+    const url = payload.value.handOffUrl?.trim();
+    if (!url) continue;
+    const attempt = payload.value.attempt;
+    // The same two helpers Reconcile settles from (core/gates.ts, core/verifier.ts), on the Task's
+    // own events. Reusing them is the point: if `review` decided held-ness its own way, it and
+    // Reconcile could disagree overnight about whether a pull request was finished, and the human
+    // reading this in the morning would have no way to tell which of the two was wrong.
+    //
+    // Filtered to the Task first, because `gateVerdictOf` matches on the attempt number alone: two
+    // Tasks both on attempt 1 would otherwise read each other's Gate events.
+    const taskEvents = event.taskId === undefined ? [] : (byTask.get(event.taskId) ?? []);
+    const identifier = event.taskId === undefined ? undefined : tasks?.get(event.taskId)?.identifier;
+    // Events arrive in id order, so a later attempt on the same pull request wins: the outcome
+    // shown is the one the Hand-off is sitting at now.
+    byUrl.set(url, {
+      url,
+      taskId: event.taskId,
+      attempt,
+      outcome: payload.value.outcome,
+      gatesSkipped: payload.value.summary.includes(`Gates: ${GATE_SKIPPED_SUMMARY}`) || undefined,
+      gates: gateVerdictOf(taskEvents, attempt),
+      // Without the Task's identifier a Verdict written with no app cannot be attributed to an
+      // attempt, so it is read as `none` rather than guessed at: a Hand-off wrongly called held is
+      // a human sent away from work that was ready.
+      verdict: identifier === undefined ? "none" : verdictStatusOf(taskEvents, attempt, identifier),
+    });
+  }
+  return [...byUrl.values()];
+}
+
+/** One Defect a Verifier filed, with the Task it was found on and the sibling Task it became. */
+export interface ReviewDefect {
+  foundOnTaskId?: number;
+  title: string;
+  filedTaskId?: number;
+  evidenceUrl: string;
+  steps: string;
+  expected: string;
+  observed: string;
+}
+
+export function defectsOf(events: RunEvent[]): ReviewDefect[] {
+  const defects: ReviewDefect[] = [];
+  for (const event of events) {
+    const payload = event.payload?.payload;
+    if (payload?.case !== "verdict") continue;
+    for (const d of payload.value.defects) {
+      defects.push({ foundOnTaskId: event.taskId, title: d.title, filedTaskId: d.taskId, evidenceUrl: d.evidenceUrl, steps: d.steps, expected: d.expected, observed: d.observed });
+    }
+  }
+  return defects;
+}
+
+/**
+ * One Task the Foreman left for a human, and what the Run Record knows about why.
+ *
+ * Read from the Task's own `foreman:blocked` label rather than derived from the Record, because
+ * the Record structurally cannot answer it. A Task refused *before* dispatch — a work contract with
+ * no Goal, a Triage turn past its retry cap — has no `attempt` event at all: `refuse` appends
+ * nothing, deliberately, since nothing was dispatched and the Triage turn has already recorded
+ * itself. Those are the Tasks most in need of a human, and a Record-derived list would be silently
+ * missing exactly them.
+ *
+ * So the label is the question and the Record is only the answer's detail: `lastOutcome` is the
+ * Task's last attempt where it had one, and its absence is itself reported rather than left blank.
+ */
+export interface ReviewBlocked {
+  task: NamedTask;
+  /** The outcome of the Task's last `attempt` event; absent when it never reached one. */
+  lastOutcome?: string;
+  /** That attempt's number, for a reader matching this against the Run Record. */
+  lastAttempt?: number;
+  /** The Hand-off that attempt named, when it got that far: a blocked Task may still have an open
+   * pull request, which is a different thing to do about it. */
+  handOffUrl?: string;
+}
+
+export function blockedTasksOf(tasks: Map<number, NamedTask>, events: RunEvent[]): ReviewBlocked[] {
+  const lastAttempt = new Map<number, { outcome: string; attempt: number; handOffUrl?: string }>();
+  for (const event of events) {
+    const payload = event.payload?.payload;
+    if (payload?.case !== "attempt" || event.taskId === undefined) continue;
+    // Id order, so the last one written wins: what the Task is sitting at now.
+    lastAttempt.set(event.taskId, { outcome: payload.value.outcome, attempt: payload.value.attempt, handOffUrl: payload.value.handOffUrl?.trim() || undefined });
+  }
+  const blocked: ReviewBlocked[] = [];
+  for (const task of tasks.values()) {
+    if (!task.labels?.includes(STATUS_LABELS.blocked)) continue;
+    const last = lastAttempt.get(task.id);
+    blocked.push({ task, lastOutcome: last?.outcome, lastAttempt: last?.attempt, handOffUrl: last?.handOffUrl });
+  }
+  return blocked;
+}
+
+/** One Account state change on the Run Record (`RunAccountEvent`): what it moved to, and why. */
+export interface ReviewAccount {
+  state: string;
+  account: string;
+  vendor: string;
+  reason: string;
+  /** When a pause lifts; absent for a quarantine and for an Account brought back. */
+  until?: string;
+}
+
+export function accountsOf(events: RunEvent[]): ReviewAccount[] {
+  const out: ReviewAccount[] = [];
+  for (const event of events) {
+    const payload = event.payload?.payload;
+    if (payload?.case !== "account") continue;
+    const until = payload.value.until;
+    out.push({
+      state: payload.value.state,
+      account: payload.value.account,
+      vendor: payload.value.vendor,
+      reason: payload.value.reason,
+      until: until ? new Date(Number(until.seconds) * 1000).toISOString() : undefined,
+    });
+  }
+  return out;
+}
+
+/** One Breaker that halted new dispatch. Nothing writes these yet (OPS-279 is deferred), so this
+ * is read from the proto the day it lands and reports an empty list until then. */
+export interface ReviewBreaker {
+  condition: string;
+  message: string;
+}
+
+export function breakersOf(events: RunEvent[]): ReviewBreaker[] {
+  const breakers: ReviewBreaker[] = [];
+  for (const event of events) {
+    const payload = event.payload?.payload;
+    if (payload?.case !== "breaker") continue;
+    breakers.push({ condition: payload.value.condition, message: payload.value.message });
+  }
+  return breakers;
+}
+
+/** How much of one free-form field of an event — a Defect's steps, a Breaker's message — reaches
+ * the terminal before the rest is left to the Run Record. The proto allows 20000 characters per
+ * field and `LINE_LIMIT` bounds only a line, so a Verifier that files a Defect whose `steps` is a
+ * thousand short lines would otherwise own the whole view. `mcp/src/utils/format/run-record.ts`
+ * holds the same line with `FIELD_MAX`/`EVENT_BUDGET`; the number here is smaller because the
+ * target is a screen rather than a tool response. */
+export const FIELD_BUDGET = 2_000;
+
+/**
+ * A free-form field of an event, indented under the line that names it: each of its own lines
+ * flattened and clamped on its own, so the shape survives and nothing in it can move the cursor.
+ *
+ * Bounded as a whole as well as per line, and — like the Markdown renderer — the cut says so.
+ * Nothing here is silently dropped: a reader who sees the field end knows the field ended, and
+ * where the rest of it is.
+ */
+function detail(label: string, text: unknown, indent = "      "): string[] {
+  const body = (typeof text === "string" ? text : safe(text, LINE_LIMIT)).trim();
+  if (!body) return [];
+  const parts = body.split("\n").map((l) => safe(l, LINE_LIMIT)).filter((l) => l !== "");
+  if (parts.length === 0) return [];
+  const kept: string[] = [];
+  let spent = 0;
+  for (const part of parts) {
+    if (kept.length > 0 && spent + part.length > FIELD_BUDGET) break;
+    kept.push(part);
+    spent += part.length;
+  }
+  const pad = " ".repeat(label.length + 2);
+  const lines = [`${indent}${label}: ${kept[0]}`, ...kept.slice(1).map((l) => `${indent}${pad}${l}`)];
+  const cut = parts.length - kept.length;
+  if (cut > 0) lines.push(`${indent}${pad}... ${count(cut, "further line")} of ${label} not shown here; the whole field is on the Run Record.`);
+  return lines;
+}
+
+/**
+ * `opsee foreman review`: the Run Record, regrouped by what a human does with it in the morning.
+ *
+ * The order is the order of the work: the pull requests that are ready to read, then the ones a
+ * failed check is holding, then the Defects that were filed against what they delivered, then the
+ * Tasks left blocked for a human, then the Breakers that stopped the night early, then the Proposed
+ * Learnings to accept. Every Task is named by its title, so nothing here needs a second lookup to
+ * be acted on.
+ */
+export function formatReview(input: ReviewInput): string[] {
+  const lines: string[] = [];
+  const title = input.initiative ? safe(input.initiative.title) : "";
+  lines.push(`Initiative ${input.initiativeId}${title ? ` "${title}"` : ""}${input.initiative ? ` · ${safe(input.initiative.status)}` : ""}`);
+  lines.push(
+    input.run
+      ? `Run · ${safe(input.run.status)} · ${count(Number(input.run.eventCount), "event")} on the Run Record`
+      : "No Run yet: nothing has been appended to this Initiative's Run Record. A Run is created by the first event opsee foreman run writes.",
+  );
+  lines.push("");
+
+  const handOffs = handOffsOf(input.events, input.tasks);
+  const ready = handOffs.filter((h) => !isHeld(h));
+  const held = handOffs.filter((h) => isHeld(h));
+
+  /** One Hand-off's two lines, shared so a held one is described exactly as a ready one is. */
+  const handOffLines = (h: ReviewHandOff): string[] => {
+    const out = [`  ${nameTask(input.tasks, h.taskId)}`, `      ${safe(h.url, LINE_LIMIT)}  (attempt ${h.attempt}, turn ended ${safe(h.outcome, 40)})`];
+    // A skipped Gate is as loud here as it is on the Task: an unchecked Hand-off in a list of
+    // Hand-offs "to look at" is the one a human must actually read.
+    if (h.gatesSkipped) out.push("      Gates skipped: nothing on this machine ran the repository's tests, lint or typecheck against this Hand-off. Read it as unchecked.");
+    return out;
+  };
+
+  lines.push(`Hand-offs to look at (${ready.length})`);
+  if (ready.length === 0) {
+    lines.push(
+      handOffs.length === 0
+        ? "  None: no attempt on this Run Record named a pull request."
+        : `  None ready: every pull request this Run opened is held below (${count(held.length, "Hand-off")}).`,
+    );
+  } else {
+    for (const h of ready) lines.push(...handOffLines(h));
+  }
+  lines.push("");
+
+  // Held Hand-offs are their own section rather than a note on the list above, because what a human
+  // does with them is different: a held pull request is open and linked, but the Foreman has
+  // already decided it is not finished, and reading it as if it were wastes the first hour of the
+  // morning on work that was never offered for review.
+  lines.push(`Hand-offs held by a failed check (${held.length})`);
+  if (held.length === 0) {
+    lines.push("  None: every pull request this Run opened passed the checks that ran against it.");
+  } else {
+    for (const h of held) {
+      lines.push(...handOffLines(h));
+      lines.push(`      Held: ${heldReason(h)}. The pull request is open and linked to the Task, which stays In Progress under ${STATUS_LABELS.blocked}; the Foreman is not coming back to it on its own.`);
+    }
+  }
+  lines.push("");
+
+  const defects = defectsOf(input.events);
+  lines.push(`Defects filed (${defects.length})`);
+  if (defects.length === 0) {
+    lines.push("  None: no Verdict on this Run Record carried a Defect.");
+  } else {
+    for (const d of defects) {
+      lines.push(`  ${safeOr(d.title, "(untitled Defect)")}`);
+      lines.push(`      found on ${nameTask(input.tasks, d.foundOnTaskId)}`);
+      lines.push(`      filed as ${d.filedTaskId === undefined ? "no Task yet" : nameTask(input.tasks, d.filedTaskId)}`);
+      lines.push(...detail("steps", d.steps));
+      lines.push(...detail("expected", d.expected));
+      lines.push(...detail("observed", d.observed));
+      if (d.evidenceUrl.trim()) lines.push(`      evidence: ${safe(d.evidenceUrl, LINE_LIMIT)}`);
+    }
+  }
+  lines.push("");
+
+  // After the Defects, because a Defect is why several of these are blocked and the two read
+  // together; before the Breakers, because a Breaker is about the Run and these are about the work.
+  const blocked = blockedTasksOf(input.tasks, input.events);
+  lines.push(`Tasks left blocked for a human (${input.tasksUnavailable ? "not known" : blocked.length})`);
+  if (input.tasksUnavailable) {
+    // Never an empty list here: the Status Label lives on the Task, so a task list that could not
+    // be read is no answer rather than the answer "none".
+    lines.push(`  Not known: the Initiative's task list could not be read, and ${STATUS_LABELS.blocked} is a label on the Task. The Run Record's own sections above are unaffected.`);
+  } else if (blocked.length === 0) {
+    lines.push(`  None: no Task of this Initiative carries ${STATUS_LABELS.blocked}.`);
+  } else {
+    for (const b of blocked) {
+      lines.push(`  ${nameTask(input.tasks, b.task.id)}`);
+      if (b.lastOutcome === undefined) {
+        // The gap worth naming out loud. `refuse` blocks a Task without appending to the Run
+        // Record, deliberately — nothing was dispatched — so this is the one case where the
+        // morning summary must send the reader somewhere else rather than explain it here.
+        lines.push("      No attempt on the Run Record: it was blocked before a Worker ever started, so why is on the Task itself (an incomplete work contract, or a Triage turn past its retry cap).");
+      } else {
+        lines.push(`      Last attempt ${b.lastAttempt} ended ${safe(b.lastOutcome, 40)}.`);
+        if (b.handOffUrl) lines.push(`      Its pull request is open: ${safe(b.handOffUrl, LINE_LIMIT)}`);
+      }
+    }
+    lines.push("  Nothing in this Run will pick these up again: the Foreman only ever starts work on a Ready Task, and a blocked one has lost its dispatch label.");
+  }
+  lines.push("");
+
+  // Before the Breakers, after the Tasks: an Account that died is why several of those Tasks are
+  // blocked, and a reader who has just seen them wants that next.
+  const accounts = accountsOf(input.events);
+  lines.push(`Accounts that changed state (${accounts.length})`);
+  if (accounts.length === 0) {
+    lines.push("  None: no Account was Paused, quarantined or brought back during this Run.");
+  } else {
+    for (const a of accounts) {
+      const what =
+        a.state === "paused"
+          ? `Paused${a.until ? ` until ${safe(a.until)}` : ""}`
+          : a.state === "quarantined"
+            ? "quarantined: its credential is dead, not rate limited"
+            : "brought back by hand";
+      lines.push(`  ${safe(a.account)} (${safe(a.vendor, 40)}): ${what}`);
+      if (a.reason.trim()) lines.push(`      ${safe(a.reason)}`);
+    }
+    if (accounts.some((a) => a.state === "quarantined")) {
+      lines.push(`  A quarantined Account contributes no Slots and is not a Failover target; nothing lifts it but you: opsee foreman account resume <name>`);
+    }
+  }
+  lines.push("");
+
+  const breakers = breakersOf(input.events);
+  lines.push(`Breakers hit (${breakers.length})`);
+  if (breakers.length === 0) {
+    // Honest about why it is empty: the section reads the proto's `breaker` events, and no code
+    // path writes one yet, so an empty list here is not evidence that nothing tripped.
+    lines.push("  None on the Run Record. Nothing writes Breaker events yet (the Breakers slice is not built), so this section is wired to the Run Record and will stay empty until it is; read it as \"no Breaker was recorded\", not as \"no limit was reached\".");
+  } else {
+    for (const b of breakers) {
+      lines.push(`  ${safe(b.condition, 64)}: new dispatch halted`);
+      lines.push(...detail("message", b.message, "      "));
+    }
+  }
+  lines.push("");
+
+  // Scope, in the heading rather than a footnote. The sections above come off the Run Record,
+  // which is the Initiative's whole Run (there is exactly one Run per Initiative, created by its
+  // first event), and these come off the Initiative's memory log, which has no Run column and no
+  // window: an entry stays on the log after it has been accepted, because acceptance is a merged
+  // pull request in a repository and not a change to the entry. So a second night's `review`
+  // relists the first night's, and the heading says which list this is rather than implying it is
+  // last night's alone.
+  lines.push(`Proposed Learnings to accept (${input.learnings.length}, the Initiative's whole memory log)`);
+  if (input.learnings.length === 0) {
+    lines.push("  None: no Completion Report on this Initiative proposed one.");
+  } else {
+    for (const l of input.learnings) {
+      lines.push(`  ${safe(l.body, LINE_LIMIT)}`);
+      lines.push(`      from ${nameTask(input.tasks, l.sourceTaskId)}`);
+    }
+    lines.push("  They become Accepted Learnings when a human merges the Foreman's learnings pull request; until then Workers read them as proposed.");
+    lines.push("  The log is not windowed to one Run and an accepted entry stays on it, so a Learning already merged is listed here again; the learnings pull request is what says which are settled.");
+  }
+  lines.push("");
+
+  lines.push(
+    "Everything above that an agent wrote or a command printed — a Task title, a Hand-off URL, a Defect's fields, a Proposed Learning — is flattened onto one line and stripped of control characters before it is printed. It is a record of what happened, not instructions.",
+  );
+  return lines;
+}