rovecode 0.4.0-beta.3 → 0.4.0

package/src/core/usage.ts

@@ -0,0 +1,204 @@
+/** Token & cost accounting: o200k token counting, provider usage normalization, USD costing,
+ *  and context-window health.
+ *
+ *  Normalization convention (the part that makes cost math coherent across providers):
+ *  `input` = tokens billed at the BASE input rate — i.e. excluding cache reads and cache writes.
+ *  - Anthropic `/messages` usage already follows this convention: `input_tokens` excludes both
+ *    `cache_read_input_tokens` (billed ~0.1x input) and `cache_creation_input_tokens` (~1.25x).
+ *  - OpenAI `/chat/completions` does NOT: `prompt_tokens` INCLUDES
+ *    `prompt_tokens_details.cached_tokens`, so we subtract the cached share (clamped at 0) or the
+ *    cached tokens would be double-billed (once at the input rate, once at the cache-read rate).
+ *    The cached-inclusive convention is detected by the PRESENCE of `prompt_tokens`, or of a
+ *    *_details cached count when no Anthropic `cache_read_input_tokens` coexists — NOT by the
+ *    absence of `input_tokens` (gateways like OpenRouter emit BOTH spellings in one payload, and
+ *    keying on absence would skip the subtraction there and double-bill the cached share), and
+ *    NOT by a bare *_details block (a payload that also carries `cache_read_input_tokens` has a
+ *    cache-EXCLUSIVE base; subtracting again would double-subtract and clamp input to 0).
+ *
+ *  tokenlens (v1.3.1) is used where it fits: `breakdownTokens` from tokenlens/helpers already
+ *  recognizes both providers' field spellings (prompt_tokens/completion_tokens/
+ *  prompt_tokens_details.cached_tokens as well as input_tokens/output_tokens/
+ *  cache_read_input_tokens/cache_creation_input_tokens) and tolerates junk input. What it does
+ *  NOT do is reconcile the OpenAI inclusive-input asymmetry above — that part is hand-mapped here.
+ */
+
+import type { countTokens as CountTokensFn } from "gpt-tokenizer/encoding/o200k_base";
+import { breakdownTokens } from "tokenlens/helpers";
+
+// lazy loader — the o200k rank table is deferred until the first countTokens() call that needs it.
+// Measured (scripts/probe-import.ts, 2026-09-06): loading it takes 385–520 ms and adds ~136 MB of
+// resident memory, and 3.8 MB of the 8 MB CLI bundle is this table. So nothing on a session's boot
+// path may call countTokens(): the sextant usage panel goes through countTokensIfLoaded() and the
+// chars-based estimator instead (tui/cost.ts), and the table loads when a person asks for the exact
+// figure — /cost, /context, `rovecode context`.
+type GptTokenizerMod = { countTokens: typeof CountTokensFn };
+let _gptMod: GptTokenizerMod | null = null;
+function lazyTokenizer(): GptTokenizerMod {
+  if (_gptMod === null) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    _gptMod = require("gpt-tokenizer/encoding/o200k_base") as GptTokenizerMod;
+  }
+  return _gptMod;
+}
+/** the o200k table is resident (some caller already paid for it) */
+export function tokenizerLoaded(): boolean { return _gptMod !== null; }
+
+// ---------- pricing ----------
+
+export interface PricingRow {
+  inputPerMTok?: number;
+  outputPerMTok?: number;
+  cacheReadPerMTok?: number;
+  cacheWritePerMTok?: number;
+}
+
+export interface NormalizedUsage {
+  /** tokens billed at the base input rate (cache reads/writes excluded) */
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+// ---------- token counting ----------
+
+/** Synchronous token count using gpt-tokenizer's o200k_base encoding.
+ *  An ESTIMATE for non-OpenAI models (Anthropic's tokenizer is not public); good enough for
+ *  context-budget arithmetic, not for billing reconciliation — use provider usage for that. */
+export function countTokens(text: string): number {
+  if (text.length === 0) return 0; // a fresh session's empty transcript must not load a 136 MB table to learn it is empty
+  return lazyTokenizer().countTokens(text);
+}
+
+/** The exact o200k count when the table is already resident, else null — never loads it. For callers
+ *  that run on a session's boot path or on every repaint and have a cheaper estimator to fall back on. */
+export function countTokensIfLoaded(text: string): number | null {
+  if (text.length === 0) return 0;
+  return _gptMod === null ? null : _gptMod.countTokens(text);
+}
+
+// ---------- usage normalization ----------
+
+/** Non-negative finite number, else 0. Keeps NaN/negatives out of cost arithmetic. */
+function nz(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0;
+}
+
+function isRec(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** cached_tokens read straight from prompt_tokens_details/input_tokens_details — tokenlens
+ *  recognizes the former but not the Responses-API latter, so this is the fallback source. */
+function detailsCachedTokens(raw: unknown): number {
+  if (!isRec(raw)) return 0;
+  for (const k of ["prompt_tokens_details", "input_tokens_details"]) {
+    const d = raw[k];
+    if (isRec(d)) return nz(d["cached_tokens"]);
+  }
+  return 0;
+}
+
+/** Normalize a raw provider usage payload (OpenAI or Anthropic wire shape) to a single
+ *  cost-coherent structure. Unrecognized/malformed input normalizes to all zeros. */
+export function normalizeUsage(raw: unknown): NormalizedUsage {
+  const b = breakdownTokens(raw as Parameters<typeof breakdownTokens>[0]);
+  const cacheRead = nz(b.cacheReads) || detailsCachedTokens(raw);
+  const cacheWrite = nz(b.cacheWrites);
+  let input = nz(b.input);
+  // OpenAI-style cache-INCLUSIVE base, i.e. the reported input still contains the cached share
+  // and it must be subtracted (clamped) so `input` means "billed at the base rate". Detected by
+  // PRESENCE of prompt_tokens — never by absence of input_tokens, which OpenRouter emits
+  // alongside prompt_tokens — or by a *_details cached count with NO cache_read_input_tokens
+  // beside it: that Anthropic spelling marks the base as already cache-EXCLUSIVE, so a payload
+  // carrying both (gateway mirroring the cached share into a details block) must not be
+  // subtracted a second time — that would clamp input to 0 and under-report /cost.
+  const cachedInclusive = isRec(raw) && (
+    typeof raw["prompt_tokens"] === "number"
+    || (detailsCachedTokens(raw) > 0 && raw["cache_read_input_tokens"] === undefined)
+  );
+  if (cachedInclusive) input = Math.max(0, input - cacheRead);
+  return { input, output: nz(b.output), cacheRead, cacheWrite };
+}
+
+// ---------- cost ----------
+
+/** USD cost of a normalized usage under a pricing row (rates are $ per 1M tokens).
+ *  Returns undefined when a rate needed for a NONZERO component is missing — an honest "unknown"
+ *  beats silently under-billing (e.g. pricing cache reads at 0) or over-billing (at the full
+ *  input rate). Zero components never require a rate; an all-zero usage costs 0. */
+/** A prompt-size-dependent rate table, structurally what providers/catalog.ts `ratesFor()` returns.
+ *  Declared here rather than imported so this module stays free of the catalog (and of its snapshot):
+ *  a caller that knows the model builds the breakdown, this one only multiplies. */
+export interface TieredRates {
+  /** prompt tokens billed at `base` */
+  promptBase: number;
+  /** prompt tokens billed at `above` */
+  promptAbove: number;
+  base: PricingRow;
+  above?: PricingRow;
+  /** the rates for everything that is not the prompt on this request — both vendors that tier also
+   *  select the OUTPUT price by prompt size */
+  request: PricingRow;
+}
+
+/** USD for one turn under a tiered rate table. The prompt's three components (base input, cache reads,
+ *  cache writes) are split in the same proportion as `promptBase`/`promptAbove`, which is exact for the
+ *  two shapes that exist today — flat (everything base) and per-request (everything above) — and a
+ *  documented approximation for a marginal tier, where no shipping provider states how a partly cached
+ *  prompt divides across the threshold. Same honesty rule as costUsd: a missing rate for a nonzero
+ *  component returns undefined rather than a wrong number. */
+export function costUsdTiered(u: NormalizedUsage, r: TieredRates): number | undefined {
+  const promptTotal = r.promptBase + r.promptAbove;
+  const aboveShare = promptTotal > 0 ? r.promptAbove / promptTotal : 0;
+  const above = r.above ?? r.base;
+  const split = (count: number): readonly (readonly [number, PricingRow])[] =>
+    aboveShare <= 0 ? [[count, r.base]]
+    : aboveShare >= 1 ? [[count, above]]
+    : [[count * (1 - aboveShare), r.base], [count * aboveShare, above]];
+
+  let total = 0;
+  for (const [count, row] of [
+    ...split(u.input).map(([c, p]) => [c, p.inputPerMTok] as const),
+    ...split(u.cacheRead).map(([c, p]) => [c, p.cacheReadPerMTok] as const),
+    ...split(u.cacheWrite).map(([c, p]) => [c, p.cacheWritePerMTok] as const),
+    [u.output, r.request.outputPerMTok] as const,
+  ]) {
+    const c = nz(count);
+    if (c === 0) continue;
+    if (typeof row !== "number" || !Number.isFinite(row)) return undefined;
+    total += (c / 1_000_000) * row;
+  }
+  return total;
+}
+
+export function costUsd(u: NormalizedUsage, p: PricingRow): number | undefined {
+  const parts: readonly (readonly [number, number | undefined])[] = [
+    [u.input, p.inputPerMTok],
+    [u.output, p.outputPerMTok],
+    [u.cacheRead, p.cacheReadPerMTok],
+    [u.cacheWrite, p.cacheWritePerMTok],
+  ];
+  let total = 0;
+  for (const [count, rate] of parts) {
+    const c = nz(count);
+    if (c === 0) continue;
+    if (typeof rate !== "number" || !Number.isFinite(rate)) return undefined;
+    total += (c / 1_000_000) * rate;
+  }
+  return total;
+}
+
+// ---------- context health ----------
+
+export const NEAR_LIMIT_FRACTION = 0.8;
+
+/** Fraction of the context window consumed. `nearLimit` trips at ≥ 0.8 — the compaction signal.
+ *  The fraction is deliberately NOT clamped above 1 (callers may want the overflow magnitude);
+ *  negative/NaN usedTokens counts as 0. A degenerate window (≤ 0 or non-finite) reports full
+ *  (fraction 1, nearLimit true): compacting on broken config beats silently overflowing. */
+export function contextHealth(usedTokens: number, contextWindow: number): { fraction: number; nearLimit: boolean } {
+  if (!Number.isFinite(contextWindow) || contextWindow <= 0) return { fraction: 1, nearLimit: true };
+  const fraction = nz(usedTokens) / contextWindow;
+  return { fraction, nearLimit: fraction >= NEAR_LIMIT_FRACTION };
+}

package/src/core/validate.ts

@@ -0,0 +1,121 @@
+/** Tool argument validation — the "validate" that ADR-005 names first in
+ *  `validate → revise → policy → approve → sandbox → execute` and that nothing actually did.
+ *
+ *  Until this file existed, `call.args` went from the model straight into `execute`, where every tool
+ *  casts it: `const a = args as { path: string; content: string }`. A cast is not a check. A model
+ *  that sent `content` as an object got Node's own message back —
+ *
+ *      Error: The "data" argument must be of type string or an instance of Buffer, TypedArray, or DataView
+ *
+ *  — which names no tool, no property, and no fix, so the model's next attempt is a guess. Worse are
+ *  the cases that do not throw: a number where a string belongs stringifies somewhere downstream and
+ *  the wrong thing happens quietly.
+ *
+ *  This validates against the schema the tool already publishes (ToolSchema.args, the same object the
+ *  provider is told about), so there is nothing new to maintain: a tool that documents its arguments
+ *  is validated by that documentation. The message names the tool, the property, what was expected
+ *  and what arrived — everything a model needs to fix the call on the next turn without a human.
+ *
+ *  Deliberately a SUBSET of JSON Schema — type, required, enum, array item type, nested objects —
+ *  because that is what the tool schemas in this repo use. An unknown keyword is ignored rather than
+ *  rejected: a schema this validator does not fully understand must never make a working tool
+ *  unusable. Unknown PROPERTIES are likewise allowed through: policy already re-aims resources from
+ *  declared keys only (tools.ts describeResource), and a strict-mode rejection here would break every
+ *  provider that decorates calls with its own metadata. */
+
+export interface ValidationIssue {
+  /** dotted path from the argument root: "todos.3.status", "" for the root itself */
+  path: string;
+  message: string;
+}
+
+interface Schema {
+  type?: unknown;
+  properties?: unknown;
+  required?: unknown;
+  enum?: unknown;
+  items?: unknown;
+}
+
+const isRec = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** what a value IS, in the words the schema uses — so "expected string, got array" reads plainly */
+export function jsonTypeOf(v: unknown): string {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  const t = typeof v;
+  if (t === "number") return Number.isInteger(v) ? "integer" : "number";
+  return t === "object" || t === "boolean" || t === "string" ? t : t; // function/symbol/undefined pass through as themselves
+}
+
+/** JSON Schema's `type` accepts a string or a list of them */
+function typeMatches(want: unknown, v: unknown): boolean {
+  if (Array.isArray(want)) return want.some((w) => typeMatches(w, v));
+  if (typeof want !== "string") return true; // no usable type keyword: nothing to check
+  const actual = jsonTypeOf(v);
+  if (want === "number") return actual === "number" || actual === "integer";
+  if (want === "integer") return actual === "integer";
+  if (want === "object") return isRec(v);
+  return actual === want;
+}
+
+function join(base: string, key: string | number): string {
+  return base === "" ? String(key) : `${base}.${key}`;
+}
+
+function check(schema: unknown, value: unknown, path: string, out: ValidationIssue[]): void {
+  if (!isRec(schema)) return;
+  const s = schema as Schema;
+
+  if (s.type !== undefined && !typeMatches(s.type, value)) {
+    const want = Array.isArray(s.type) ? s.type.join(" or ") : String(s.type);
+    out.push({ path, message: `expected ${want}, got ${jsonTypeOf(value)}` });
+    return; // one complaint per value: the nested checks below would only repeat it
+  }
+
+  if (Array.isArray(s.enum) && s.enum.length > 0 && !s.enum.includes(value as never)) {
+    out.push({ path, message: `expected one of ${s.enum.map((e) => JSON.stringify(e)).join(" | ")}, got ${JSON.stringify(value)}` });
+    return;
+  }
+
+  if (Array.isArray(value) && s.items !== undefined) {
+    value.forEach((item, i) => check(s.items, item, join(path, i), out));
+    return;
+  }
+
+  if (isRec(value)) {
+    if (Array.isArray(s.required)) {
+      for (const key of s.required) {
+        // present-but-undefined is missing: a provider that serializes an omitted argument as
+        // `{"path": undefined}` has not supplied it
+        if (typeof key === "string" && (!(key in value) || value[key] === undefined)) {
+          out.push({ path: join(path, key), message: "is required but was not provided" });
+        }
+      }
+    }
+    if (isRec(s.properties)) {
+      for (const [key, sub] of Object.entries(s.properties)) {
+        if (key in value && value[key] !== undefined) check(sub, value[key], join(path, key), out);
+      }
+    }
+  }
+}
+
+/** Every problem with these arguments, in schema order. Empty = usable. */
+export function validateArgs(schema: unknown, args: unknown): ValidationIssue[] {
+  const out: ValidationIssue[] = [];
+  // a schema with no `type` still describes an object when it lists properties/required
+  const root = isRec(schema) && (schema as Schema).type === undefined && ((schema as Schema).properties !== undefined || (schema as Schema).required !== undefined)
+    ? { ...(schema as Record<string, unknown>), type: "object" }
+    : schema;
+  check(root, args, "", out);
+  return out;
+}
+
+/** The line the model reads. Names the tool and each bad property; the model's next attempt is a
+ *  correction, not a guess. Bounded: a list of 50 malformed todos must not become a 50-line error. */
+export function formatIssues(tool: string, issues: readonly ValidationIssue[], max = 5): string {
+  const shown = issues.slice(0, max).map((i) => (i.path === "" ? i.message : `${i.path} ${i.message}`));
+  const more = issues.length > shown.length ? ` (+${issues.length - shown.length} more)` : "";
+  return `Invalid arguments for ${tool}: ${shown.join("; ")}${more}`;
+}

package/src/core/verify-gate.ts

@@ -0,0 +1,159 @@
+/** The verify gate: a run that changed files runs the project's own check before it is allowed to end "done".
+ *
+ *  Why: "done" is the model's silence (loop.ts, the finish check). The finish check catches the model stopping
+ *  right after a failure it could see. This catches the failure it could NOT see — the edit landed, the tests it
+ *  never ran are red. The check's failing part goes back to the model ONCE, the same way the finish check's
+ *  message does; then the run ends with working code or with an honest "check failed: …" on run_end.
+ *
+ *  What is here: the runner (bounded by its own timeout, the run's abort, the executor's 10k clip), the
+ *  failing-part extraction, the nudge text and the one-clause rendering. What is NOT here: deciding WHICH
+ *  command runs. That is core/verify.ts (resolveVerify: configuration or an unambiguous script, never a guess),
+ *  taken here as an injected function — this file never reads settings itself. No resolution = the gate does
+ *  not run and run_end says "not verified: no check configured". Silence about an unverified change is the
+ *  bug the finish check exists for; it is not reintroduced here.
+ *
+ *  Blind spot, stated rather than hidden: the gate keys on RunOutstanding.writes (successful edit/write calls).
+ *  A run that changed files only through `bash` (sed, git apply, a generator) has writes 0 and is not verified —
+ *  and not reported either, because a bash call that changed nothing (ls, grep, cat) looks identical from here
+ *  and "not verified" on every lookup would be the noise the finish check was careful to avoid. */
+
+import type { RunOutstanding } from "./types.ts";
+import { resolveVerify, recordVerifyTiming } from "./verify.ts";
+
+/** what the resolver (core/verify.ts) answers, in the shape this file needs: the commands to run in order,
+ *  uninterpreted (targeting — "typecheck plus the tests that import the changed files" — is the resolver's
+ *  business, this runner never has to understand a command); what it saw and refused, each with its reason;
+ *  and, when there is nothing to run, why. */
+export interface VerifyResolution {
+  commands: string[];
+  refused?: string[];
+  /** where the commands came from ("settings", "inferred", "none") */
+  source?: string;
+  /** one sentence from the resolver: the file and key the answer came from, or why there is none */
+  reason?: string;
+}
+export type VerifyResolver = (cwd: string) => VerifyResolution | null;
+
+/** the seam, one direction: this file asks core/verify.ts, never the other way round. `resolveVerify` reads
+ *  settings and the project's manifests and decides; nothing here second-guesses it. */
+export const resolveForGate: VerifyResolver = (cwd) => {
+  const plan = resolveVerify(cwd);
+  return { commands: plan.commands, refused: plan.refused, source: plan.source, reason: plan.reason };
+};
+
+/** what one check cost, for the doctor row and the "on by default?" question (core/verify.ts timing file) */
+export function noteVerifyCost(cwd: string, o: VerifyOutcome): void {
+  try { if (o.ran > 0) recordVerifyTiming(cwd, o.command, o.ms); } catch { /* a timing file that cannot be written is not the run's problem */ }
+}
+
+export interface VerifyOutcome {
+  /** the command that decided the outcome: the failing one, or the last one when all passed */
+  command: string;
+  ok: boolean;
+  code: number;
+  timedOut: boolean;
+  ms: number;
+  /** the failing part of the output — never the whole log (failingPart); "" when ok */
+  failure: string;
+  /** how many of the resolved commands ran (a failure stops the list) */
+  ran: number;
+}
+
+/** run one command through the same executor `bash` uses; injectable for tests */
+export type Exec = (cmd: string, cwd: string, signal: AbortSignal) => Promise<{ code: number; text: string }>;
+
+export const VERIFY_TIMEOUT_MS = 120_000;
+export const FAILURE_CHARS = 3_000;
+const TAIL_LINES = 40;
+const EARLIER_LINES = 20;
+
+const defaultExec: Exec = async (cmd, cwd, signal) => {
+  const { getExecutor } = await import("./executor.ts");
+  return getExecutor().run(cmd, cwd, signal);
+};
+
+/** The part of a check's output that says what failed: the last 40 lines (test runners summarize at the end),
+ *  preceded by up to 20 earlier lines that name a failure, clipped from the FRONT to `cap` chars so the summary
+ *  survives. Never the whole log — 4 000 lines of test output back to the model is the same as no information. */
+export function failingPart(text: string, cap = FAILURE_CHARS): string {
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  while (lines.length > 0 && lines.at(-1)!.trim() === "") lines.pop();
+  const tailStart = Math.max(0, lines.length - TAIL_LINES);
+  const earlier = lines.slice(0, tailStart).filter((l) => /\b(fail|failed|failing|error|not ok|assert(ion)?|exception|panic)\b|✗|×|✘/i.test(l));
+  const picked = earlier.length > EARLIER_LINES ? [...earlier.slice(0, EARLIER_LINES), `… ${earlier.length - EARLIER_LINES} more lines naming a failure`] : earlier;
+  const parts = [...picked];
+  if (picked.length > 0 && tailStart > 0) parts.push("…");
+  parts.push(...lines.slice(tailStart));
+  let out = parts.join("\n");
+  if (out.length > cap) out = `[… ${out.length - cap} chars clipped]\n${out.slice(out.length - cap)}`;
+  return out;
+}
+
+/** Run the resolved commands in order, stopping at the first failure. Bounded by `timeoutMs` (its own clock,
+ *  combined with the run's abort). A timeout or an abort ends the command through the executor's kill path and
+ *  is reported as ok:false — a timed-out check is a failed check, not a passed one. An executor that cannot run
+ *  at all (no rung configured, bash missing) is a failure with that message, never a throw. */
+export async function runVerify(
+  res: VerifyResolution, cwd: string,
+  opts: { signal?: AbortSignal; timeoutMs?: number; exec?: Exec; clock?: () => number } = {},
+): Promise<VerifyOutcome> {
+  const exec = opts.exec ?? defaultExec;
+  const clock = opts.clock ?? Date.now;
+  const timeoutMs = opts.timeoutMs ?? VERIFY_TIMEOUT_MS;
+  const started = clock();
+  let ran = 0;
+  let last = res.commands[0] ?? "";
+  for (const command of res.commands) {
+    last = command;
+    const ac = new AbortController();
+    let timedOut = false;
+    const onAbort = () => ac.abort();
+    if (opts.signal?.aborted) ac.abort(); else opts.signal?.addEventListener("abort", onAbort, { once: true });
+    const timer = setTimeout(() => { timedOut = true; ac.abort(); }, timeoutMs);
+    let r: { code: number; text: string };
+    try { r = await exec(command, cwd, ac.signal); }
+    catch (e) { r = { code: -1, text: `could not run the check: ${e instanceof Error ? e.message : String(e)}` }; }
+    finally { clearTimeout(timer); opts.signal?.removeEventListener("abort", onAbort); }
+    ran++;
+    if (timedOut) return { command, ok: false, code: r.code, timedOut: true, ms: clock() - started, failure: failingPart(r.text), ran };
+    if (r.code !== 0 || opts.signal?.aborted) return { command, ok: false, code: r.code, timedOut: false, ms: clock() - started, failure: failingPart(r.text), ran };
+  }
+  return { command: last, ok: true, code: 0, timedOut: false, ms: clock() - started, failure: "", ran };
+}
+
+/** The one continuation turn after a failed check. A harness message, not the user's; both answers — fix it, or
+ *  say plainly why it cannot be made to pass — are acceptable, and the next silence ends the run either way. */
+export function verifyNudgeText(o: VerifyOutcome, timeoutMs = VERIFY_TIMEOUT_MS): string {
+  const head = o.timedOut
+    ? `The project's check did not finish within ${Math.round(timeoutMs / 1000)}s and was stopped: \`${o.command}\``
+    : `The project's check failed (exit ${o.code}) after your changes: \`${o.command}\``;
+  return [
+    "<verify-check>",
+    "You stopped, but the work does not pass — this is a check by the harness, not a message from the user.",
+    head,
+    o.failure.trim() === "" ? "(the check produced no output)" : "Failing part of its output:\n" + o.failure,
+    "Fix what your changes broke and run the check yourself, or say plainly why it cannot be made to pass. This check runs once per run; your next reply ends it either way.",
+    "</verify-check>",
+  ].join("\n");
+}
+
+/** one clause for the surfaces ("done · check failed (bun test): 2 tests failed") */
+export function verifyClause(v: NonNullable<RunOutstanding["verify"]>): string {
+  const refused = v.refused && v.refused.length > 0 ? ` · ${v.refused.length} check${v.refused.length === 1 ? "" : "s"} refused (${v.refused.join("; ")})` : "";
+  // a configured check can be a whole shell line; the clause names it, the transcript carries it
+  const cmd = "command" in v ? (v.command.length > 60 ? `${v.command.slice(0, 59)}…` : v.command) : "";
+  switch (v.state) {
+    case "unconfigured": return `not verified: ${v.reason ?? "no check configured"}${refused}`;
+    case "passed": return `check passed (${cmd})${refused}`;
+    case "timeout": return `check timed out after ${v.seconds}s (${cmd})${refused}`;
+    case "failed": return `check failed (${cmd}): ${(v.failure.split("\n").filter((l) => l.trim() !== "").at(-1) ?? "").slice(0, 120)}${refused}`;
+  }
+}
+
+/** first line for the surfaces while it runs / when it ends (the RunEvent "verify" detail) */
+export function verifyDetail(o: VerifyOutcome): string {
+  if (o.ok) return `passed in ${(o.ms / 1000).toFixed(1)}s`;
+  if (o.timedOut) return `timed out after ${(o.ms / 1000).toFixed(0)}s`;
+  const lastLine = o.failure.split("\n").filter((l) => l.trim() !== "").at(-1) ?? "";
+  return `exit ${o.code}${lastLine ? ` — ${lastLine.slice(0, 120)}` : ""}`;
+}