@saadnvd1/agent-os 0.3.470 → 0.3.471

package/lib/orchestrator/signoff.ts

@@ -9,7 +9,7 @@
 
 import { MERGED_AS, type MergeMethod } from "../tasks/merge-policy";
 import { prFor } from "../tasks/session";
-import { codeReviewRefusal, signOffTask } from "../tasks";
+import { codeReviewGate, signOffTask } from "../tasks";
 import { signOffRefusal } from "../stacks/guard";
 import { getStack, landInBackground } from "../stacks";
 import { LAND_DEFAULTS } from "../stacks/land";
@@ -91,11 +91,12 @@ export async function judge(
       fromCard: !!task.lh_card_id,
       scope: getCheck(task.id, sha, "scope"),
       stackRefusal: landing ? null : signOffRefusal(task.id),
-      codeReviewRefusal: codeReviewRefusal(
-        pr.codeReview,
-        sha,
-        restackedOf(task)
-      ),
+      codeReview: codeReviewGate({
+        head: sha,
+        attribution: pr.attribution,
+        review: (at) => getCheck(task.id, at, "review"),
+        restacked: restackedOf(task),
+      }),
     }),
     opts
   );
@@ -129,7 +130,8 @@ export async function gateVerdict(
   const held = holdingEscalations(work.id);
   // Saad approved merging this exact commit. On an ask the orchestrator
   // raised (ask_saad with its task and sha), held or not, it merges once
-  // whatever the gates say, but only with a code review of that commit and
+  // whatever the gates say, but only once an independent review of that
+  // commit finished (its findings are his to override, not that it ran) and
   // its stack parent merged: the orchestrator wrote that ask, and no answer
   // to it stands in for those. An approval of the gates' own ask on a held
   // task merges as it always has (heldVerdict).
@@ -139,7 +141,10 @@ export async function gateVerdict(
     (approval.raised_by === "orchestrator" || !held.length)
   ) {
     const i = await inputs();
-    const refusal = i.codeReviewRefusal ?? i.stackRefusal;
+    const refusal =
+      i.codeReview.refusal ??
+      (i.codeReview.ran ? null : i.codeReview.wait) ??
+      i.stackRefusal;
     if (refusal)
       return no(
         `${work.name} (PR #${pr.number} at ${short(sha)}): Saad approved this commit, but ${refusal}`

package/lib/session-audit/render.ts

@@ -427,7 +427,7 @@ export function renderSummary(
     )
   );
   out.push(
-    "\nThe reviewer the orchestrator runs (`review`) uses `claude -p --no-session-persistence` and leaves no transcript; reviews are counted from the checks above and from do-code-review subagents."
+    "\nThe reviewer the orchestrator runs (`review`) uses `claude -p --no-session-persistence` and leaves no transcript; each run's tokens are recorded in `check_runs` and shown in Usage."
   );
   return out.join("\n") + "\n";
 }

package/lib/stacks/land.ts

@@ -1,7 +1,7 @@
 /**
  * Land a stack: merge every PR bottom-up, ported from dispatch's `land`.
- * A preflight checks EVERY PR before anything merges: CI, and a Code review
- * section in its body for its head commit. Each sign-off restacks
+ * A preflight checks EVERY PR before anything merges: CI, and a passing
+ * independent review of its head commit (tasks/code-review.ts). Each sign-off restacks
  * what sits on it, so a restacked PR's checks are waited out again (its green
  * was against the parent's branch). It stops at the first failure and says
  * what landed. A chat item's agent is stopped between turns before anything
@@ -17,6 +17,8 @@ import {
   codeReviewRefusal,
   type TaskPR,
 } from "../tasks";
+import type { ReviewState } from "../tasks/code-review";
+import { getCheck } from "../orchestrator/checks";
 import { itemName } from "./guard";
 import { refreshItems } from "./tick";
 import { outputOf } from "./git";
@@ -34,6 +36,8 @@ export interface LandDeps {
   signOff: (sessionId: string, head?: string) => Promise<void>;
   beforeMerge?: MergeGate;
   prOf: (session: Session) => Promise<TaskPR | null>;
+  // The independent review of a task at a commit.
+  reviewOf: (sessionId: string, sha: string) => ReviewState | null;
   sleep: (ms: number) => Promise<void>;
   refresh: (stackId: string) => Promise<void>;
   waitMs: number;
@@ -52,6 +56,7 @@ export const LAND_DEFAULTS: LandDeps = {
     await signOffTask(id, { wait: true, head });
   },
   prOf: (s) => taskPR(s, true),
+  reviewOf: (id, sha) => getCheck(id, sha, "review"),
   sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
   refresh: refreshItems,
   waitMs: 45 * 60_000,
@@ -90,8 +95,20 @@ async function waitGreen(
   }
 }
 
+// Why an item can't merge on its review: none passed of its head, or of
+// the head the task pushed before a restack moved it.
+function unreviewed(item: StackItemRow, pr: TaskPR, deps: LandDeps) {
+  return codeReviewRefusal({
+    head: pr.head,
+    attribution: pr.attribution,
+    review: (sha) =>
+      item.session_id ? deps.reviewOf(item.session_id, sha) : null,
+    restacked: { from: item.restacked_from, to: item.restacked_to },
+  });
+}
+
 // Without the orchestrator's gate: the item's head right before merging,
-// only if its Code review section covers that commit. A push since the
+// only if a passing review covers that commit. A push since the
 // preflight needs a new review; the merge is pinned to this head.
 async function reviewedHead(
   item: StackItemRow,
@@ -100,12 +117,7 @@ async function reviewedHead(
   const now = q.item(db, item.id) ?? item;
   const session = sessionOf(now.session_id);
   const pr = session ? await deps.prOf(session) : null;
-  const refusal = pr
-    ? codeReviewRefusal(pr.codeReview, pr.head, {
-        from: now.restacked_from,
-        to: now.restacked_to,
-      })
-    : "its PR is gone";
+  const refusal = pr ? unreviewed(now, pr, deps) : "its PR is gone";
   if (refusal) throw new Stop(`stopped at ${itemName(now)}: ${refusal}`);
   return pr!.head!;
 }
@@ -157,14 +169,9 @@ export async function landStack(
       const pr =
         session && item.status === "pr" ? await deps.prOf(session) : null;
       const verdict = canSignOff(pr);
-      const unreviewed =
-        pr &&
-        codeReviewRefusal(pr.codeReview, pr.head, {
-          from: item.restacked_from,
-          to: item.restacked_to,
-        });
+      const refusal = pr && unreviewed(item, pr, deps);
       if (!verdict.ok) missing.push(`${itemName(item)}: ${verdict.reason}`);
-      else if (unreviewed) missing.push(`${itemName(item)}: ${unreviewed}`);
+      else if (refusal) missing.push(`${itemName(item)}: ${refusal}`);
       else if (item.error) missing.push(`${itemName(item)}: ${item.error}`);
       hadChecks.set(item.id, pr?.checks !== "none");
     }

package/lib/tasks/brief.ts

@@ -16,18 +16,9 @@ function stackedLines(baseBranch: string, stack: StackedOn): string {
   return `
 - This task is STACKED on ${stack.name} (${on}), which has not merged. Its commits are already in your branch and are not yours: don't change or revert them.
 - Open your pull request against ${baseBranch} (\`gh pr create --base ${baseBranch}\`) so its diff is only your commits, and start the body with the line "Stacked on ${on} (${stack.name})".
-- Never merge or rebase onto the default branch yourself. When the parent merges, AgentOS rebases your branch and retargets your PR, then tells you; re-run your checks when it does. Your code review still counts for the head AgentOS's restack left; if you push after that, review again and update the section.${also}`;
+- Never merge or rebase onto the default branch yourself. When the parent merges, AgentOS rebases your branch and retargets your PR, then tells you; re-run your checks when it does. AgentOS reviews your PR itself; a review of your head still counts for the head its restack left, and a push after that gets a new one.${also}`;
 }
 
-// What the PR body's review section looks like. lib/tasks/code-review.ts
-// parses it, and merges refuse a PR without one for its head commit.
-export const CODE_REVIEW_SECTION = `
-  ## Code review
-  Reviewed: <the full sha of the commit you reviewed, which is the PR's head>
-  Agents: <the review agents that ran>
-  Fixed: <each finding fixed, one line each, or "none">
-  Deferred: <each finding not fixed and why, or "none">`;
-
 // The system brief every task agent runs under. It finishes by opening a PR
 // and stopping: merging is the human's sign-off, never the agent's.
 export function buildTaskBrief(opts: {
@@ -39,10 +30,8 @@ export function buildTaskBrief(opts: {
 
 - Branch: ${opts.branch} (based on ${opts.baseBranch}). Stay in this directory and on this branch.
 - Do the task fully. Run the project's own checks (typecheck, tests, lint) when they exist and keep them passing.
-- When the work is done, commit with a conventional commit message, then review it before any pull request: run \`/do-code-review\` (the project's skill in .claude/skills/do-code-review; if the project has none, \`/code-review\`). Fix every Blocking and High finding, commit, and review again until none are left (two rounds at most; past that, list what's still open in the PR body).
-- Then run \`git push -u origin ${opts.branch}\` and open a pull request against ${opts.baseBranch} with \`gh pr create\`, using a clear title and a short body that says what changed and how you verified it, and ends with this section:
-${CODE_REVIEW_SECTION}
-  Merges are refused without it, and when its "Reviewed:" commit is not the PR's head: if you push again, review again and update the body (\`gh pr edit --body-file\`). Then stop and wait.
+- When the work is done, commit with a conventional commit message, run \`git push -u origin ${opts.branch}\` and open a pull request against ${opts.baseBranch} with \`gh pr create\`, using a clear title and a short body that says what changed and how you verified it. Then stop and wait.
+- You don't need to review it yourself: AgentOS runs an independent review of the PR's exact head commit before it can merge, and the orchestrator sends you any blocking findings to fix. For a risky change you may still run \`/do-code-review\` (or \`/code-review\`) before the PR.
 - Never merge the pull request, never push to ${opts.baseBranch}, and never delete branches or worktrees. A human reviews and merges.${opts.stack ? stackedLines(opts.baseBranch, opts.stack) : ""}
 - Write scratch files (PR bodies, review notes, logs, test output) outside the worktree, in your scratchpad or \$TMPDIR. Anything uncommitted left in the worktree keeps it from being removed when the task is done.
 - Do not add any AI or assistant attribution to commits or the pull request.

package/lib/tasks/code-review.ts

@@ -1,27 +1,13 @@
-// The "Code review" section every task's PR body carries (the task brief
-// asks for it, after /do-code-review). Merges refuse a PR without one for
-// its head commit. No imports: CI runs this file on its own
-// (scripts/check-code-review.ts).
-
-export interface CodeReviewSection {
-  // The commit the review covered, as written in the section.
-  sha: string | null;
-  // A "Restacked: <from> -> <to>" line AgentOS wrote after rebasing the
-  // branch itself. Only CI reads it: AgentOS's own gates go by what it
-  // recorded, never by what a body says.
-  restacked?: Restacked;
-  // What kind of AI attribution the body carries, when it does: a fixed
-  // label, never the body's own text, which goes into gate messages.
-  attribution?: AttributionKind;
-}
+// The code-review gate, the same for every PR: a passing independent
+// review (lib/orchestrator/review) of its exact head, and a body with no AI
+// attribution. Tasks don't write a review section in the body any more: the
+// orchestrator's review is the one review.
 
 // Matched one line at a time, never across lines: the body is written by
 // the task, and a regex that backtracks over it would block the server.
 // Only what renders counts: fenced code and HTML comments are skipped, so an
-// example of the section isn't read as the section.
+// example isn't read as the real thing.
 const MAX_BODY = 65_536;
-const HEADING = /^ {0,3}(#{1,6}) *code review *:?$/i;
-const ANY_HEADING = /^ {0,3}(#{1,6}) +\S/;
 const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 // AI attribution ("Co-Authored-By: Claude", "Generated with [Claude Code]").
 // The same rule as the commit-msg hook's ATTRIBUTION_ERE in
@@ -45,10 +31,6 @@ function attributionKind(line: string): AttributionKind | undefined {
   if (/^claude-session:/i.test(line)) return "a Claude-Session link";
   return 'a "Generated with" AI footer';
 }
-const REVIEWED =
-  /^[>*_ -]*reviewed(?: (?:commit|sha|at))?[*_ ]*:[*_` ]*([0-9a-f]{12,40})\b/i;
-const RESTACKED =
-  /^[>*_ -]*restacked[*_ ]*:[*_` ]*([0-9a-f]{40})[*_` ]*(?:->|→)[*_` ]*([0-9a-f]{40})\b/i;
 
 export function renderedLines(body: string): string[] {
   let text = body.slice(0, MAX_BODY);
@@ -70,45 +52,7 @@ export function renderedLines(body: string): string[] {
   return lines;
 }
 
-// The last Code review section that names a commit (or the last one, when
-// none does); null when the body has none. A section runs to the next
-// heading of its level or higher, so its own subheadings stay inside it.
-export function parseCodeReview(
-  body: string | null | undefined
-): CodeReviewSection | null {
-  if (!body) return null;
-  const sections: CodeReviewSection[] = [];
-  let level = 0;
-  let attribution: AttributionKind | undefined;
-  for (const line of renderedLines(body)) {
-    attribution ??= attributionKind(line.trimStart());
-    const heading = HEADING.exec(line);
-    if (heading) {
-      level = heading[1].length;
-      sections.push({ sha: null });
-      continue;
-    }
-    const other = ANY_HEADING.exec(line);
-    if (other && other[1].length <= level) level = 0;
-    const current = sections.at(-1);
-    if (!level || !current) continue;
-    if (current.sha) {
-      const moved = RESTACKED.exec(line);
-      if (moved)
-        current.restacked = {
-          from: moved[1].toLowerCase(),
-          to: moved[2].toLowerCase(),
-        };
-      continue;
-    }
-    const sha = REVIEWED.exec(line)?.[1];
-    if (sha) current.sha = sha.toLowerCase();
-  }
-  const found = sections.findLast((s) => s.sha) ?? sections.at(-1) ?? null;
-  return found && attribution ? { ...found, attribution } : found;
-}
-
-// The AI attribution a body carries anywhere, Code review section or not.
+// The AI attribution a body carries anywhere.
 export function attributionIn(
   body: string | null | undefined
 ): AttributionKind | undefined {
@@ -119,57 +63,75 @@ export function attributionIn(
   }
 }
 
-// A branch AgentOS rebased itself (a stack restack): the head the task
-// pushed and reviewed, and the head the restack left.
+// A branch AgentOS rebased itself (a stack restack, or the automatic
+// rebase onto its base): the head the task pushed, and the head AgentOS
+// left.
 export interface Restacked {
   from: string | null;
   to: string | null;
 }
 
-// Why a PR can't merge on its code review, or null when it can. Fails
-// closed: an unread body or an unknown head refuses. A review of the head
-// the task pushed still counts after AgentOS restacked it, but only while
-// the head is exactly the one the restack left: a push by the task after
-// that needs a new review.
-export function codeReviewRefusal(
-  section: CodeReviewSection | null | undefined,
-  head: string | undefined,
-  restacked?: Restacked | null,
-  fix = "the task has to run /do-code-review and put a Code review section naming the reviewed commit in the PR body"
-): string | null {
-  if (section === undefined) return `the PR body couldn't be read: ${fix}`;
-  if (!head) return `the PR's head commit is unknown: ${fix}`;
-  if (!section) return `the PR body has no Code review section: ${fix}`;
-  if (section.attribution)
-    return `the PR body carries AI attribution (${section.attribution}): remove it with \`gh pr edit --body-file\``;
-  if (!section.sha)
-    return `the PR's Code review section doesn't name the reviewed commit ("Reviewed: <sha>"): ${fix}`;
-  const covers = (sha: string | null | undefined) =>
-    !!sha && sha.toLowerCase().startsWith(section.sha!);
-  if (covers(head)) return null;
-  if (restacked?.to === head && covers(restacked.from)) return null;
-  return `the PR's code review covers ${section.sha.slice(0, 7)}, not its head ${head.slice(0, 7)}: ${fix}`;
+export interface ReviewState {
+  sha: string;
+  status: "running" | "pass" | "block" | "error";
+}
+
+export interface CodeReviewGate {
+  // Fails the gate: counts against the task.
+  refusal: string | null;
+  // Not covered yet, but a review will cover it.
+  wait: string | null;
+  // A review covering the head finished, passing or not. Saad's approval
+  // of the commit overrides what it found, never whether one ran.
+  ran?: boolean;
 }
 
-// The body with its Code review section saying AgentOS rebased the
-// reviewed head `from` to `to`: a "Restacked:" line right after the
-// section's "Reviewed:" line, replacing one already there. Null when the
-// body has no section, or its review isn't of `from`.
-export function withRestackedLine(
-  body: string,
-  from: string,
-  to: string
+const short = (sha: string) => sha.slice(0, 7);
+
+// Fails closed: an unread body or an unknown head refuses. A review of the
+// head the task pushed still counts after AgentOS restacked or rebased it
+// cleanly, but only while the head is exactly the one AgentOS left: a push
+// by the task after that needs a new review.
+export function codeReviewGate(opts: {
+  head: string | undefined;
+  // The AI attribution in the PR body (attributionIn): null for none,
+  // undefined when the body couldn't be read.
+  attribution: AttributionKind | null | undefined;
+  review: (sha: string) => ReviewState | null;
+  restacked?: Restacked | null;
+}): CodeReviewGate {
+  const { head, restacked } = opts;
+  const no = (refusal: string) => ({ refusal, wait: null });
+  const { attribution } = opts;
+  if (attribution === undefined) return no("the PR body couldn't be read");
+  if (!head) return no("the PR's head commit is unknown");
+  if (attribution)
+    return no(
+      `the PR body carries AI attribution (${attribution}): remove it with \`gh pr edit --body-file\``
+    );
+  // The reviews that cover the head: its own, and the one of the head the
+  // task pushed while the head is the one AgentOS left.
+  const covering = [
+    opts.review(head),
+    restacked?.to === head && restacked.from
+      ? opts.review(restacked.from)
+      : null,
+  ];
+  if (covering.some((r) => r?.status === "pass"))
+    return { refusal: null, wait: null, ran: true };
+  const now = covering[0];
+  return {
+    refusal: null,
+    wait: `no passing independent review of ${short(head)}${now?.status === "running" ? " yet (it's running)" : now?.status === "block" ? " (it has blocking findings)" : ": call review"}`,
+    ran: covering.some((r) => r?.status === "block"),
+  };
+}
+
+// The gate as one reason, for paths that only merge or refuse (a stack
+// landing, an approved merge): a wait refuses there too.
+export function codeReviewRefusal(
+  opts: Parameters<typeof codeReviewGate>[0]
 ): string | null {
-  const section = parseCodeReview(body);
-  if (!section?.sha || !from.toLowerCase().startsWith(section.sha)) return null;
-  const lines = body.split("\n");
-  const at = lines.findLastIndex(
-    (l) =>
-      REVIEWED.exec(l.replace(/\t/g, " "))?.[1]?.toLowerCase() === section.sha
-  );
-  if (at < 0) return null;
-  const line = `Restacked: ${from} -> ${to} (AgentOS rebased the reviewed commit onto its base; the PR's own changes are the ones reviewed)`;
-  const next = lines[at + 1]?.replace(/\t/g, " ") ?? "";
-  lines.splice(at + 1, RESTACKED.test(next) ? 1 : 0, line);
-  return lines.join("\n");
+  const gate = codeReviewGate(opts);
+  return gate.refusal ?? gate.wait;
 }

package/lib/tasks/gh.ts

@@ -1,7 +1,7 @@
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { git } from "../git-exec";
-import { parseCodeReview } from "./code-review";
+import { attributionIn } from "./code-review";
 import { parseScopeChange } from "./scope-change";
 import { assertGhAllowed, noteGhFailure, noteGhSuccess } from "./gh-limit";
 import {
@@ -114,7 +114,8 @@ export async function toTaskPR(repoDir: string, pr: ListedPR): Promise<TaskPR> {
     failing: failingCheck(rollup),
     failingUrl: failingUrl(rollup),
     checkCount: (pr.statusCheckRollup ?? []).length,
-    codeReview: pr.body === undefined ? undefined : parseCodeReview(pr.body),
+    attribution:
+      pr.body === undefined ? undefined : (attributionIn(pr.body) ?? null),
     scopeChange: parseScopeChange(pr.body),
     ...(pr.mergeable && { mergeable: pr.mergeable }),
   };

package/lib/tasks/index.ts

@@ -49,7 +49,7 @@ import { chatStateNow } from "../chat/runner";
 import { saidSinceLastMessage } from "../chat/store";
 
 export * from "./state";
-export { codeReviewRefusal, parseCodeReview } from "./code-review";
+export { codeReviewGate, codeReviewRefusal } from "./code-review";
 export { signOffTask, dropTask, signingOff, mergeSettled } from "./finish";
 export { prFor as taskPR } from "./session";
 export { moveTask } from "./move-flow";

package/lib/tasks/state.ts

@@ -1,4 +1,4 @@
-import type { CodeReviewSection } from "./code-review";
+import type { AttributionKind } from "./code-review";
 
 export type TaskStatus =
   | "running"
@@ -22,9 +22,9 @@ export interface TaskPR {
   failingUrl?: string | null;
   // How many checks are registered on the head.
   checkCount?: number;
-  // The body's Code review section: null when it has none, undefined
-  // when the body wasn't read.
-  codeReview?: CodeReviewSection | null;
+  // The AI attribution the body carries (tasks/code-review.ts): null for
+  // none, undefined when the body wasn't read.
+  attribution?: AttributionKind | null;
   // The body's "Scope change" note (tasks/scope-change.ts), when it has one.
   scopeChange?: string | null;
   // GitHub's word on merging it into its base: CONFLICTING once the base

package/lib/usage/check-runs.ts

@@ -0,0 +1,167 @@
+/**
+ * What the orchestrator's one-shot checks cost: each `claude -p` run of the
+ * independent reviewer and the scope check, read from its JSON result.
+ * They run with --no-session-persistence and leave no transcript, so this
+ * is the only record of their tokens.
+ */
+
+import { db } from "../db";
+import { formatTokens } from "../chat/context";
+
+export interface RunUsage {
+  model: string | null;
+  inputTokens: number;
+  cacheWriteTokens: number;
+  cacheReadTokens: number;
+  outputTokens: number;
+  costUsd: number;
+  durationMs: number | null;
+}
+
+interface ModelUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+  costUSD?: number;
+}
+
+const n = (v: unknown) => (typeof v === "number" && v > 0 ? v : 0);
+
+// The usage in a `claude -p --output-format json` result, or null when it
+// carries none. Per-model usage covers every model the run used; the model
+// named is the one that cost the most.
+export function runUsageOf(result: unknown): RunUsage | null {
+  if (!result || typeof result !== "object") return null;
+  const r = result as {
+    usage?: {
+      input_tokens?: number;
+      output_tokens?: number;
+      cache_read_input_tokens?: number;
+      cache_creation_input_tokens?: number;
+    };
+    modelUsage?: Record<string, ModelUsage>;
+    total_cost_usd?: number;
+    duration_ms?: number;
+  };
+  const models = Object.entries(r.modelUsage ?? {});
+  if (!r.usage && !models.length) return null;
+  const durationMs = n(r.duration_ms) || null;
+  if (models.length) {
+    const sum = (k: keyof ModelUsage) =>
+      models.reduce((t, [, m]) => t + n(m[k]), 0);
+    const [model] = models.reduce((a, b) =>
+      n(b[1].costUSD) > n(a[1].costUSD) ? b : a
+    );
+    return {
+      model,
+      inputTokens: sum("inputTokens"),
+      cacheWriteTokens: sum("cacheCreationInputTokens"),
+      cacheReadTokens: sum("cacheReadInputTokens"),
+      outputTokens: sum("outputTokens"),
+      costUsd: n(r.total_cost_usd) || sum("costUSD"),
+      durationMs,
+    };
+  }
+  const u = r.usage!;
+  return {
+    model: null,
+    inputTokens: n(u.input_tokens),
+    cacheWriteTokens: n(u.cache_creation_input_tokens),
+    cacheReadTokens: n(u.cache_read_input_tokens),
+    outputTokens: n(u.output_tokens),
+    costUsd: n(r.total_cost_usd),
+    durationMs,
+  };
+}
+
+export interface CheckRunTarget {
+  workspaceId: string;
+  // The task's session id, or an external PR's id.
+  sessionId: string;
+  // How the Usage page names it: "task add-a", "PR o/r#5".
+  label: string;
+  prNumber: number | null;
+  sha: string;
+  kind: "review" | "scope";
+}
+
+export function recordCheckRun(
+  target: CheckRunTarget,
+  u: RunUsage,
+  at = Date.now()
+): void {
+  db.prepare(
+    `INSERT INTO check_runs (workspace_id, session_id, label, pr_number, sha, kind, model,
+       input_tokens, cache_write_tokens, cache_read_tokens, output_tokens, cost_usd, duration_ms, at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    target.workspaceId,
+    target.sessionId,
+    target.label,
+    target.prNumber,
+    target.sha,
+    target.kind,
+    u.model,
+    u.inputTokens,
+    u.cacheWriteTokens,
+    u.cacheReadTokens,
+    u.outputTokens,
+    u.costUsd,
+    u.durationMs,
+    at
+  );
+}
+
+// A recorder for one check, that never lets a write break the check.
+export function checkRunRecorder(target: CheckRunTarget) {
+  return (u: RunUsage) => {
+    try {
+      recordCheckRun(target, u);
+    } catch (e) {
+      console.error(`[check-runs] recording ${target.label}:`, e);
+    }
+  };
+}
+
+export interface CheckRunTotals {
+  runs: number;
+  tokens: number;
+  costUsd: number;
+  durationMs: number;
+  models: string[];
+}
+
+// Everything the checks of one commit cost, every part and retry.
+export function checkRunTotals(
+  sessionId: string,
+  sha: string
+): CheckRunTotals | null {
+  const row = db
+    .prepare(
+      `SELECT count(*) AS runs,
+         coalesce(sum(input_tokens + cache_write_tokens + cache_read_tokens + output_tokens), 0) AS tokens,
+         coalesce(sum(cost_usd), 0) AS costUsd,
+         coalesce(sum(duration_ms), 0) AS durationMs,
+         group_concat(DISTINCT model) AS models
+       FROM check_runs WHERE session_id = ? AND sha = ?`
+    )
+    .get(sessionId, sha) as Omit<CheckRunTotals, "models"> & {
+    models: string | null;
+  };
+  if (!row.runs) return null;
+  return { ...row, models: row.models ? row.models.split(",") : [] };
+}
+
+// "2 runs · 412k tokens · $0.84 · 3m 10s · claude-opus-5-5"
+export function describeCheckRuns(t: CheckRunTotals): string {
+  const s = Math.round(t.durationMs / 1000);
+  const time = s >= 60 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${s}s`;
+  return [
+    `${t.runs} run${t.runs === 1 ? "" : "s"}`,
+    `${formatTokens(t.tokens)} tokens`,
+    `$${t.costUsd.toFixed(2)}`,
+    time,
+    ...t.models,
+  ].join(" · ");
+}

package/lib/usage/report.ts

@@ -18,3 +18,28 @@ export function usageReport(range: UsageRange, now = Date.now()) {
   const names = Object.fromEntries(listWorkspaces().map((w) => [w.id, w.name]));
   return aggregateUsage(rows, range, names, now);
 }
+
+// What the orchestrator's reviewer and scope check cost over the range
+// (lib/usage/check-runs), by PR: a "turn" is one run.
+export function checkRunReport(range: UsageRange, now = Date.now()) {
+  const rows = db
+    .prepare(
+      `SELECT session_id, label, pr_number, workspace_id, at, cost_usd, input_tokens,
+         output_tokens, cache_read_tokens, cache_write_tokens
+       FROM check_runs WHERE at >= ? ORDER BY at`
+    )
+    .all(rangeStart(range, now)) as (Omit<TurnRow, "session_name"> & {
+    label: string;
+    pr_number: number | null;
+  })[];
+  const named: TurnRow[] = rows.map(({ label, pr_number, ...r }) => ({
+    ...r,
+    // An external PR's label already names it.
+    session_name:
+      pr_number === null || label.startsWith("PR ")
+        ? label
+        : `${label} · PR #${pr_number}`,
+  }));
+  const names = Object.fromEntries(listWorkspaces().map((w) => [w.id, w.name]));
+  return aggregateUsage(named, range, names, now);
+}