cortad 0.2.3 → 0.3.0-rc.3

package/lib/stick.mjs

@@ -0,0 +1,99 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { cliSpec, npxName } from "./spec.mjs";
+
+// `npx cortad stick`: one line in each coding agent's own instructions file in this repository, and
+// a hook in the two clients that run one after an edit. `unstick` takes out exactly what stick put
+// in. Both are idempotent, print what they changed, and never touch git.
+//
+// The hook command carries --hook: Claude Code and Codex both drop plain stdout from a PostToolUse
+// hook, and read only hookSpecificOutput.additionalContext. The command follows lib/spec.mjs, and
+// unstick knows the line and the hook under any spec.
+export const lineFor = (name) => `After changing prompts, tools, models or retrieval, check with Cortad before committing: npx ${name} status`;
+export const hookFor = (name) => `npx ${name} status --changed --hook`;
+const IS_LINE = /^After changing prompts, tools, models or retrieval, check with Cortad before committing: npx \S+ status$/;
+const IS_HOOK = /^npx \S+ status --changed --hook$/;
+const hasLine = (text) => text.split("\n").some((l) => IS_LINE.test(l.trim()));
+const ours = (entry) => entry?.hooks?.some((h) => IS_HOOK.test(h.command ?? ""));
+const LINE_FILES = ["AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"];
+const HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
+const RULE_FILE = ".cursor/rules/cortad.mdc";
+
+export const hookOutput = (text) => JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text } });
+
+export function stick(root, { spec = cliSpec() } = {}) {
+  const line = lineFor(npxName(spec));
+  const hook = hookFor(npxName(spec));
+  const rule = `---\ndescription: Checking AI behavior with Cortad\nalwaysApply: true\n---\n${line}\n`;
+  const said = LINE_FILES.map((rel, i) => write(root, rel, (text) => {
+    if (hasLine(text)) return null;
+    return `${text}${text && !text.endsWith("\n") ? "\n" : ""}${text ? "\n" : ""}${line}\n`;
+  }, i === 0 ? `added "${line}"` : "added the same line"));
+  said.push(write(root, RULE_FILE, (text) => (hasLine(text) ? null : rule), "written, with the same line, applied always"));
+  said.push(...HOOK_FILES.map((rel, i) => write(root, rel, (text) => {
+    const config = parse(text);
+    if (config === undefined) return undefined;
+    const list = config.hooks?.PostToolUse ?? [];
+    if (list.some(ours)) return null;
+    config.hooks = { ...config.hooks, PostToolUse: [...list, { matcher: "Edit|Write", hooks: [{ type: "command", command: hook }] }] };
+    return `${JSON.stringify(config, null, 2)}\n`;
+  }, i === 0 ? `added a PostToolUse hook on Edit|Write that runs ${hook}` : "added the same hook")));
+  return said;
+}
+
+export function unstick(root) {
+  const said = LINE_FILES.map((rel) => write(root, rel, (text) => {
+    if (!hasLine(text)) return null;
+    return text.split("\n").filter((l) => !IS_LINE.test(l.trim())).join("\n").replace(/\n+$/, "\n");
+  }, "removed the line"));
+  said.push(write(root, RULE_FILE, (text) => (text ? "" : null), "removed"));
+  said.push(...HOOK_FILES.map((rel) => write(root, rel, (text) => {
+    const config = parse(text);
+    if (config === undefined) return undefined;
+    const list = config.hooks?.PostToolUse;
+    if (!list?.some(ours)) return null;
+    const kept = list.map((e) => ({ ...e, hooks: (e.hooks ?? []).filter((h) => !IS_HOOK.test(h.command ?? "")) })).filter((e) => e.hooks.length);
+    if (kept.length) config.hooks.PostToolUse = kept;
+    else delete config.hooks.PostToolUse;
+    if (!Object.keys(config.hooks).length) delete config.hooks;
+    return Object.keys(config).length ? `${JSON.stringify(config, null, 2)}\n` : "";
+  }, "removed the hook")));
+  return said;
+}
+
+// One file: `change` gets its text ("" when absent) and returns the new text, null for nothing to
+// do, or undefined when it cannot be read. An empty result removes the file, and the folders it
+// leaves empty. A path that leaves the repository, through a symbolic link or otherwise, is left alone.
+function write(root, rel, change, done) {
+  const file = resolve(root, rel);
+  if (!inside(root, file)) return `${rel}: left alone, it points outside this repository`;
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const next = change(text);
+  if (next === undefined) return `${rel}: left alone, it is not valid JSON`;
+  if (next === null) return `${rel}: nothing to change`;
+  if (next.trim() === "") {
+    rmSync(file);
+    for (let dir = dirname(file); dir.startsWith(`${resolve(root)}${sep}`) && !readdirSync(dir).length; dir = dirname(dir)) rmdirSync(dir);
+    return `${rel}: removed, it held only what stick wrote`;
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, next);
+  return `${rel}: ${done}`;
+}
+
+function inside(root, file) {
+  const base = realpathSync(root);
+  let dir = dirname(file);
+  while (!existsSync(dir)) dir = dirname(dir);
+  const real = realpathSync(dir);
+  if (real !== base && !real.startsWith(base + sep)) return false;
+  try { return !lstatSync(file).isSymbolicLink(); } catch { return true; }
+}
+
+function parse(text) {
+  if (!text.trim()) return {};
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+  } catch { return undefined; }
+}

package/lib/text.mjs

@@ -0,0 +1,234 @@
+import { readLines } from "./read-text.mjs";
+import { at, clip, has, num, PAGE_CHARS, pageOf, plural, SIDE, upper } from "./words.mjs";
+
+// What each verb prints. A result is data for the coding agent: a line meant for the person starts
+// with "For the person:", and a run_status result ends with the next call. A field the API leaves
+// out prints nothing, so the text follows the API as it grows.
+
+const DONE = new Set(["succeeded", "failed", "canceled"]);
+const UNIT = { sweeps: ["run", "runs"], runs: ["run", "runs"], trials: ["verify trial", "verify trials"] };
+export const STARTING = "Starting your app for the run. Call run_status; it answers as soon as the run has an id.";
+
+const signed = (x) => (Math.round(x) > 0 ? `+${num(x)}` : num(x));
+const units = (n, unit) => { const [one, many] = UNIT[unit] ?? [unit, unit]; return `${num(n)} ${n === 1 ? one : many}`; };
+const kn = (x) => (has(x?.k) ? `${num(x.k)} of ${num(x.n)}` : num(x));
+const interval = (ci) => (ci && has(ci.low) ? `, interval ${num(ci.low)} to ${num(ci.high)}` : "");
+
+export const finished = (run) => Boolean(run) && (run.finished ?? DONE.has(run.status));
+
+export function statusText(d) {
+  const lines = [];
+  if (d.repository?.name) lines.push(`Cortad · ${d.repository.name}`);
+  const plan = planLine(d.plan);
+  if (plan) lines.push(plan);
+  if (d.app?.said) lines.push(`App: ${d.app.said}`);
+  if (d.read) lines.push(...readLines(d.read));
+  if (d.run === null) lines.push("No run yet.");
+  else if (d.run) lines.push(...runLines(d.run, "latest "));
+  if (d.field) lines.push(`Production: ${d.field.connected ? "connected" : "not connected"}.`);
+  if (d.links?.lab && (d.read || d.run)) lines.push(`For the person: ${d.links.lab} shows this in the browser.`);
+  if (d.run && !finished(d.run)) lines.push(`next: run_status ${d.run.jobId}`);
+  return lines.join("\n");
+}
+
+function planLine(p) {
+  if (!p?.name) return null;
+  const parts = [];
+  if (has(p.runsLeft) && has(p.runsAllowed)) parts.push(`${num(p.runsLeft)} of ${plural(p.runsAllowed, "run")} left this month`);
+  if (has(p.verifyTrialsLeft) && has(p.verifyTrialsAllowed)) parts.push(`${num(p.verifyTrialsLeft)} of ${plural(p.verifyTrialsAllowed, "verify trial")} left`);
+  return parts.length ? `${p.name}: ${parts.join(", ")}.` : `Plan: ${p.name}.`;
+}
+
+function runLines(d, prefix = "") {
+  const done = finished(d);
+  const played = d.of ? `${num(d.played ?? 0)} of ${plural(d.of, "trial")} played` : "no trial played yet";
+  const lines = [`${upper(`${prefix}${d.kind === "verify" ? "verify" : "run"}`)} ${d.jobId}: ${d.status === "succeeded" || !d.status ? (done ? "finished" : "running") : d.status}, ${played}.`];
+  if (done && typeof d.score === "number") lines.push(`Score ${num(d.score)} of 100${interval(d.ci)}.`);
+  if (done && has(d.findings)) lines.push(`${plural(d.findings, "finding")}.`);
+  const reads = readingsLine(d);
+  if (reads) lines.push(reads);
+  if (d.stopped) lines.push(stoppedLine(d));
+  for (const f of d.faults ?? []) lines.push(`Fault${SIDE[f.side] ? ` ${SIDE[f.side]}` : ""}: ${f.what}${f.fix ? ` ${f.fix}` : ""}`);
+  if (d.error) lines.push(`Error: ${d.error}`);
+  if (d.verify) lines.push(...verifyLines(d.verify));
+  return lines;
+}
+
+// A reading is one question checked against one reply.
+function readingsLine(d) {
+  if (!has(d.readings) && !has(d.questionsAsked)) return null;
+  const r = has(d.readings) ? plural(d.readings, "reading") : null;
+  const q = has(d.questionsAsked) ? plural(d.questionsAsked, "question") : null;
+  const split = [has(d.decided) && `${num(d.decided)} decided`, has(d.unclear) && `${num(d.unclear)} unclear`].filter(Boolean).join(", ");
+  return `${r && q ? `${r} of ${q}` : r ?? `${q} asked`}${split ? `: ${split}` : ""}.`;
+}
+
+// A run that stopped before its last trial says where; one that stopped after it is a note.
+function stoppedLine(d) {
+  const s = d.stopped;
+  const turn = has(s.after) ? ` at turn ${s.after}` : "";
+  const fix = s.fix ? ` ${s.fix}` : "";
+  if (d.of && d.played < d.of) return `Stopped at ${num(d.played)} of ${plural(d.of, "trial")}${SIDE[s.side] ? `, ${SIDE[s.side]}` : ""}: ${s.why}${turn}.${fix}`;
+  return `${upper(s.why)}${turn}${SIDE[s.side] ? `, ${SIDE[s.side]}` : ""}.${fix}`;
+}
+
+const moveText = (m) => `held ${kn(m.before)} readings before, ${kn(m.after)} after; ${m.moved}, ${signed(m.point)} points${interval(m)}${m.insideNoise ? ", inside the noise" : ""}.`;
+
+function verifyLines(v) {
+  const lines = [`Verify of ${v.findingId}${v.path ? ` at ${at(v.path, v.line)}` : ""}.`];
+  if (v.visible) lines.push(`Visible trials: ${moveText(v.visible)}`);
+  if (v.holdout) lines.push(`Held-out trials: ${moveText(v.holdout)}`);
+  else if (v.holdout === null) lines.push("Held-out trials: no pair for this question.");
+  if (v.overfit) lines.push("Overfit: the visible trials moved and the held-out trials did not.");
+  if (v.said) lines.push(v.said);
+  return lines;
+}
+
+export function nextCall(d) {
+  if (!finished(d)) return `run_status ${d.jobId}`;
+  return d.kind === "verify" || d.findings > 0 ? "findings" : "status";
+}
+
+export function runText(d) {
+  const lines = runLines(d);
+  if (finished(d) && d.url) lines.push(`For the person: the report is at ${d.url}`);
+  lines.push(`next: ${nextCall(d)}`);
+  return lines.join("\n");
+}
+
+export function startedText(d, kind, findingId) {
+  const verify = (d.kind ?? kind) === "verify";
+  const what = verify ? `Verify${findingId && !d.joined ? ` of ${findingId}` : ""}` : "Run";
+  return `${what} ${d.joined ? "already playing" : "started"}: ${d.jobId}.\nnext: run_status ${d.jobId}`;
+}
+
+export const waitingText = (p, now, limitMs) =>
+  `Your app is still starting for the ${p.kind === "verify" ? "verify" : "run"}: ${num((now - Date.parse(p.startedAt)) / 1000)} of up to ${num(limitMs / 1000)} seconds.\nnext: run_status pending`;
+
+// A spent plan: what the last run found, what was fixed since, what the next run would play.
+export function refusedText(d) {
+  const lines = [];
+  if (has(d.used) && has(d.allowed) && d.unit) lines.push(`Refused: ${num(d.used)} of ${units(d.allowed, d.unit)} used${d.plan?.name ? ` on the ${d.plan.name} plan` : ""}.`);
+  else if (d.why) lines.push(`Refused: ${d.why}`);
+  if (d.ledger) lines.push(...ledgerLines(d.ledger));
+  if (!d.ledger?.plan && d.plans?.length) lines.push(`Plans: ${d.plans.map((p) => `${p.name} $${p.monthlyUsd} a month`).join(", ")}.`);
+  lines.push("Nothing ran.");
+  if (d.checkout) lines.push(`For the person: plans and checkout at ${d.checkout}`);
+  return lines.join("\n");
+}
+
+function ledgerLines(l) {
+  const lines = [];
+  const r = l.lastRun;
+  if (r) {
+    const parts = [has(r.score) && `score ${num(r.score)} of 100${interval(r.ci)}`, has(r.findings) && plural(r.findings, "finding"), r.of && `${num(r.played ?? 0)} of ${plural(r.of, "trial")} played`].filter(Boolean);
+    lines.push(`Last run ${r.jobId}: ${parts.join(", ")}.`);
+  }
+  if (l.fixed) {
+    lines.push(`${plural(l.fixed.length, "fix", "fixes")} verified since that run${l.fixed.length ? ":" : "."}`);
+    for (const f of l.fixed) lines.push(`  ${at(f.path, f.line)} (${f.findingId}): held ${kn(f.before)} readings before, ${kn(f.after)} after; ${f.moved}, ${signed(f.move)} points${interval(f)}.`);
+  }
+  const n = l.nextRun;
+  if (n) lines.push(`The next run would play ${[plural(n.trials, "trial"), has(n.heldOut) && `${num(n.heldOut)} held out`, has(n.newFromChanges) && `${num(n.newFromChanges)} new from the changes`].filter(Boolean).join(", ")}.`);
+  const p = l.plan;
+  if (p) lines.push(`The ${p.name} plan, $${p.monthlyUsd} a month${has(p.allowed) ? `, includes ${units(p.allowed, p.unit)}` : ""}.`);
+  if (l.field === null) lines.push("Production: not connected.");
+  else if (l.field) lines.push(`Production, last ${plural(l.field.days, "day")}: ${plural(l.field.conversations, "conversation")}${has(l.field.brokenRate) ? `, ${Math.round(l.field.brokenRate * 100)}% of them broke a rule` : ""}.`);
+  return lines;
+}
+
+// Findings grouped by the line they live at: the server's byLine, or the findings' own file and
+// line when it sends none. The same line from two server pages is one group.
+export function linesOf(d) {
+  const rows = d.byLine ?? (d.findings ?? []).filter((f) => f.file).map((f) => ({ path: f.file, line: f.line, findingIds: [f.id] }));
+  const merged = new Map();
+  for (const r of rows) {
+    const key = at(r.path, r.line);
+    if (merged.has(key)) merged.get(key).findingIds.push(...r.findingIds);
+    else merged.set(key, { path: r.path, line: r.line, findingIds: [...r.findingIds] });
+  }
+  return [...merged.values()];
+}
+
+export const findingsText = (d, page = 1) => pageOf(findingsPages(d), page, (n) => `findings with page ${n}`);
+
+function findingsHead(d) {
+  const lines = [`Run ${d.runId}: ${plural(d.findings?.length ?? 0, "finding")}.`];
+  if (typeof d.score === "number") lines.push(`Score ${num(d.score)} of 100${interval(d.ci)}.`);
+  const reads = readingsLine(d);
+  if (reads) lines.push(reads);
+  if (d.baseRunId) lines.push(`Compared with run ${d.baseRunId}.`);
+  for (const s of [d.read, d.heldBack, d.findings?.length ? null : d.why]) if (s) lines.push(s);
+  return lines.join("\n");
+}
+
+// Whole findings, worst first as the server orders them, packed into pages that stay under
+// PAGE_CHARS. A group that crosses a page carries its header again.
+function findingsPages(d, budget = PAGE_CHARS - 60) {
+  const head = findingsHead(d);
+  if (!d.findings?.length) return [head];
+  const byId = new Map(d.findings.map((f) => [f.id, f]));
+  const groups = linesOf(d).map((g) => ({ label: `${plural(g.findingIds.length, "finding")} at ${at(g.path, g.line)}`, placed: true, items: g.findingIds.map((id) => byId.get(id)).filter(Boolean) }));
+  const grouped = new Set(groups.flatMap((g) => g.items.map((f) => f.id)));
+  const rest = d.findings.filter((f) => !grouped.has(f.id));
+  if (rest.length) groups.push({ label: `${plural(rest.length, "finding")} without a line`, placed: false, items: rest });
+
+  const pages = [];
+  let page = head;
+  let filled = false;
+  let open = null;
+  for (const g of groups) {
+    g.items.forEach((f, i) => {
+      const block = findingBlock(f, g.placed);
+      const label = () => (open === g ? "" : `\n\n${i === 0 ? g.label : `${g.label}, continued`}`);
+      if (filled && page.length + label().length + block.length + 1 > budget) {
+        pages.push(page);
+        page = `Run ${d.runId}, findings continued.`;
+        filled = false;
+        open = null;
+      }
+      page += `${label()}\n${block}`;
+      filled = true;
+      open = g;
+    });
+  }
+  pages.push(page);
+  return pages;
+}
+
+function findingBlock(f, placed) {
+  const lines = [`${f.id}  ${f.asks}`];
+  if (!placed && f.file) lines.push(`  At ${at(f.file, f.line)}`);
+  if (f.criteria) lines.push(`  Criteria: ${clip(f.criteria, 600)}`);
+  if (f.door) lines.push(`  Endpoint: ${f.door}`);
+  if (f.where) lines.push(`  Situation: ${f.where}`);
+  const r = f.rate;
+  if (r) lines.push(`  Held in ${num(r.k)} of ${plural(r.n, "reply", "replies")}${r.n ? `, ${Math.round((100 * r.k) / r.n)}%` : ""}${has(r.lo) ? `, interval ${Math.round(r.lo * 100)}% to ${Math.round(r.hi * 100)}%` : ""}.`);
+  if (f.unsettled) lines.push("  Unsettled: under the 22-reading floor.");
+  const by = [f.decidedBy?.code && `code in ${plural(f.decidedBy.code, "reading")}`, f.decidedBy?.model && `a model in ${plural(f.decidedBy.model, "reading")}`].filter(Boolean);
+  if (by.length) lines.push(`  Decided by ${by.join(", by ")}.`);
+  for (const q of (f.quotes ?? []).slice(0, 3)) {
+    const about = [typeof q.p === "number" && `confidence ${q.p.toFixed(2)}`, q.trialId && `trial ${q.trialId}`].filter(Boolean).join(", ");
+    lines.push(`  Reply ${q.reply}: "${clip(q.quote, 400)}"${about ? ` (${about})` : ""}`);
+  }
+  for (const line of (f.log ?? []).slice(0, 8)) lines.push(`  Log: ${clip(line, 300)}`);
+  if (f.replay) lines.push(`  Replay: ${plural(f.replay.trials, "trial")}, verify ${f.id}`);
+  return lines.join("\n");
+}
+
+export function fieldText(d) {
+  const t = d.totals;
+  const pct = (k, n) => (n ? `${Math.round((100 * k) / n)}%` : "n/a");
+  const link = d.url ? [`For the person: ${d.url}`] : [];
+  if (!t || !t.n) return [`No production conversations read in the last ${plural(d.days, "day")}.`, ...link].join("\n");
+  const lines = [
+    `Production, last ${plural(d.days, "day")}: ${plural(t.n, "conversation")}, ${num(t.read)} read.`,
+    `Rule checks held: ${pct(t.rulingsHeld, t.rulings)} of ${num(t.rulings)}${t.rulingsUnsure ? ` (${num(t.rulingsUnsure)} unsure)` : ""}. Resolved ${pct(t.resolved, t.read)}, frustrated ${pct(t.frustrated, t.read)}, asked for a human ${pct(t.wantsHuman, t.read)}, unanswered ${pct(t.unanswered, t.read)}.`,
+  ];
+  const broke = (d.rules ?? []).filter((r) => r.broke > 0).sort((a, b) => b.broke - a.broke).slice(0, 5);
+  if (broke.length) lines.push(`Rules broken most: ${broke.map((r) => `${r.id} (${num(r.broke)})`).join(", ")}.`);
+  if (d.journeys?.length) lines.push(`By journey: ${d.journeys.slice(0, 6).map((j) => `${j.value} ${plural(j.n, "conversation")}, ${pct(j.rulingsHeld, j.rulings)} held`).join("; ")}.`);
+  return [...lines, ...link].join("\n");
+}
+
+export const fieldConnectText = (d) => [d.connected ? "Production is connected." : "Production is not connected.", ...(d.steps ?? []).map((s, i) => `${i + 1}. ${s}`)].join("\n");

package/lib/verbs.mjs

@@ -1,11 +1,25 @@
-// The eight things a coding agent may ask of Cortad, each one call to the API with this machine's
-// key and one rendering as short text. The MCP tools and the `npx cortad <verb>` commands are the
-// same functions, so both faces say the same thing.
-
-const NOT_CONNECTED = "This project is not connected to Cortad yet. Ask the person to open cortad.com, sign in, and run the command the connect screen shows, from this folder.";
-
-export function makeVerbs({ api, token, fetchImpl = fetch, ensureRunner = async () => ({ ok: true }) }) {
-  const call = async (method, path, body) => {
+import { realpathSync, statSync } from "node:fs";
+import { resolve as resolvePath, sep } from "node:path";
+import { SHOW, showText } from "./read-text.mjs";
+import { fieldConnectText, fieldText, findingsText, linesOf, refusedText, runText, STARTING, startedText, statusText, waitingText } from "./text.mjs";
+
+// The eight things a coding agent may ask of Cortad, each a call to the API with this machine's key
+// and a rendering from lib/text.mjs. The MCP tools and the `npx cortad <verb>` commands are the same
+// functions, so both faces say the same thing.
+//
+// Codex, Cursor CLI and Copilot CLI cut an MCP call at about 60 seconds. `run` and `verify` answer
+// within a second; `run_status` holds for up to 45 seconds on the server and 58 in all.
+
+const NOT_CONNECTED = "This folder is not connected to Cortad.\nFor the person: sign in at cortad.com and run the command the connect screen shows, in this folder.";
+const HOLD_S = 45;
+// What the process that starts a run for an app that is still coming up allows it; lib/cli.mjs.
+export const READY_MS = 240_000;
+
+// `pending` keeps the run this machine asked for in ~/.cortad/<project>/pending.json: { kind,
+// startedAt, after } while the app comes up, then its jobId, or the error that ended it. `after` is
+// the latest run at the time, so a newer run on the server outranks a stale file.
+export function makeVerbs({ api, token, fetchImpl = fetch, startApp, pending, root, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+  const call = async (method, path, body, timeoutMs = 30_000) => {
     const key = typeof token === "function" ? token() : token;
     if (!key) return { status: 0, ok: false, data: { error: NOT_CONNECTED } };
     let res;
@@ -14,10 +28,10 @@ export function makeVerbs({ api, token, fetchImpl = fetch, ensureRunner = async
         method,
         headers: { authorization: `Bearer ${key}`, ...(body === undefined ? {} : { "content-type": "application/json" }) },
         body: body === undefined ? undefined : JSON.stringify(body),
-        signal: AbortSignal.timeout(60_000),
+        signal: AbortSignal.timeout(timeoutMs),
       });
     } catch (err) {
-      return { status: 0, ok: false, data: { error: `could not reach Cortad: ${err?.name === "TimeoutError" ? "it did not answer in time" : "the connection failed"}` } };
+      return { status: 0, ok: false, data: { error: `Could not reach Cortad: ${err?.name === "TimeoutError" ? "it did not answer in time" : "the connection failed"}.` } };
     }
     const text = await res.text();
     let data = null;
@@ -25,37 +39,102 @@ export function makeVerbs({ api, token, fetchImpl = fetch, ensureRunner = async
     return { status: res.status, ok: res.ok, data };
   };
   const failed = (res) => ({ text: res.data?.why ?? res.data?.error ?? `Cortad answered ${res.status}.`, data: res.data, isError: true });
+  const iso = () => new Date(now()).toISOString();
+
+  // With show, one section of the read in full, paged; a name that is not a section is the plain status.
+  const status = async ({ show, page } = {}) => {
+    const section = SHOW.includes(show) ? show : null;
+    const res = await call("GET", `/mcp/status${section ? `?show=${section}` : ""}`);
+    if (!res.ok) return failed(res);
+    return { text: section ? showText(res.data, section, page) : statusText(res.data), data: res.data };
+  };
 
-  const status = async () => {
-    const res = await call("GET", "/mcp/status");
-    return res.ok ? { text: statusText(res.data), data: res.data } : failed(res);
+  // Asks the server for the run and keeps its id here, so run_status finds it without one.
+  const post = async (args, kind) => {
+    const res = await call("POST", "/mcp/run", args);
+    if (res.status === 202 || (res.ok && res.data?.joined)) {
+      pending.write({ jobId: res.data.jobId, kind: res.data.kind ?? kind, startedAt: iso() });
+      return { text: startedText(res.data, kind, args.findingId), data: res.data };
+    }
+    if (res.status === 402) return { text: refusedText(res.data), data: res.data, isError: true };
+    if (res.status === 409) return { text: `${res.data?.why ?? "The run could not start."}\nNothing ran.`, data: res.data, isError: true };
+    return failed(res);
   };
 
-  // A run, or a verify when a finding is named. When the app is not up on this machine, the runner
-  // is started first: the process that uploads the tree, starts the app and answers the knocks.
+  // An app that is up gets the run now. One that is not is started in the background, and the run
+  // is posted from there once it answers.
   const start = async (args, kind) => {
     const before = await call("GET", "/mcp/status");
     if (!before.ok) return failed(before);
-    if (before.data.app?.state !== "ready-to-test") {
-      const runner = await ensureRunner(before.data);
-      if (!runner.ok) return { text: runner.why, data: runner, isError: true };
+    if (before.data.app?.state === "ready-to-test") return post(args, kind);
+    pending.write({ kind, startedAt: iso(), after: before.data.run?.jobId ?? null });
+    const began = await startApp(args, kind);
+    if (!began.ok) {
+      pending.write({ kind, startedAt: iso(), error: began.why });
+      return { text: began.why, isError: true };
     }
-    const res = await call("POST", "/mcp/run", args);
-    if (res.status === 202 || (res.ok && res.data?.joined)) return { text: startedText(res.data, kind), data: res.data };
-    if (res.status === 402) return { text: refusedText(res.data), data: res.data, isError: true };
-    return failed(res);
+    return { text: STARTING, data: { pending: true } };
   };
   const run = () => start({}, "run");
-  const verify = ({ findingId, jobId }) => start({ findingId, ...(jobId ? { jobId } : {}) }, "verify");
+  const verify = ({ findingId, jobId } = {}) => start({ findingId, ...(jobId ? { jobId } : {}) }, "verify");
+
+  // With no id: the run this machine is still starting, held here until it has an id, or else the
+  // latest run on the server.
+  const resolve = async (until) => {
+    const latest = await call("GET", "/mcp/status");
+    if (!latest.ok) return failed(latest);
+    const newest = latest.data.run?.jobId ?? null;
+    let p = pending.read();
+    if (!p || p.jobId || (p.after ?? null) !== newest) return newest ? { id: newest } : { text: "No run yet.\nnext: status" };
+    const stale = () => now() - Date.parse(p.startedAt) > READY_MS + 30_000;
+    while (!p.jobId && !p.error && !stale() && now() < until) {
+      await sleep(1000);
+      p = pending.read() ?? p;
+    }
+    if (p.jobId) return { id: p.jobId };
+    if (p.error) return { text: `${p.error}\nnext: status`, isError: true };
+    if (stale()) return { text: "The process starting your app for the run ended without a result.\nNothing ran.\nnext: status", isError: true };
+    return { text: waitingText(p, now(), READY_MS) };
+  };
+
+  const runStatus = async ({ jobId } = {}) => {
+    const began = now();
+    let id = jobId && jobId !== "pending" ? String(jobId) : null;
+    if (!id) {
+      const found = await resolve(began + HOLD_S * 1000);
+      if (!found.id) return found;
+      id = found.id;
+    }
+    const hold = Math.max(0, HOLD_S - Math.ceil((now() - began) / 1000));
+    const res = await call("GET", `/mcp/run/${encodeURIComponent(id)}${hold ? `?wait=${hold}` : ""}`, undefined, (hold + 13) * 1000);
+    if (!res.ok) {
+      const out = failed(res);
+      return { ...out, text: `${out.text}\nnext: run_status ${id}` };
+    }
+    return { text: runText(res.data), data: res.data };
+  };
 
-  const runStatus = async ({ jobId }) => {
-    const res = await call("GET", `/mcp/run/${encodeURIComponent(jobId)}`);
-    return res.ok ? { text: runText(res.data), data: res.data } : failed(res);
+  // Every server page of a run's findings, so the pages the agent reads are cut by size here.
+  const gather = async (jobId) => {
+    const path = (page, id) => {
+      const q = new URLSearchParams({ ...(id ? { jobId: id } : {}), ...(page > 1 ? { page: String(page) } : {}) }).toString();
+      return `/mcp/findings${q ? `?${q}` : ""}`;
+    };
+    const first = await call("GET", path(1, jobId));
+    if (!first.ok) return first;
+    const d = first.data;
+    for (let page = 2; page <= Math.min(d.pages ?? 1, 20); page += 1) {
+      const more = await call("GET", path(page, d.runId ?? jobId));
+      if (!more.ok) return more;
+      d.findings = [...(d.findings ?? []), ...(more.data.findings ?? [])];
+      if (more.data.byLine) d.byLine = [...(d.byLine ?? []), ...more.data.byLine];
+    }
+    return first;
   };
 
-  const findings = async ({ jobId } = {}) => {
-    const res = await call("GET", `/mcp/findings${jobId ? `?jobId=${encodeURIComponent(jobId)}` : ""}`);
-    return res.ok ? { text: findingsText(res.data), data: res.data } : failed(res);
+  const findings = async ({ jobId, page } = {}) => {
+    const res = await gather(jobId);
+    return res.ok ? { text: findingsText(res.data, page), data: res.data } : failed(res);
   };
 
   const dispute = async ({ findingId, why, question, jobId }) => {
@@ -65,9 +144,7 @@ export function makeVerbs({ api, token, fetchImpl = fetch, ensureRunner = async
 
   const fieldConnect = async () => {
     const res = await call("POST", "/mcp/field/connect");
-    if (!res.ok) return failed(res);
-    const d = res.data;
-    return { text: [d.connected ? "Production is connected." : "Production is not connected yet.", ...d.steps.map((s, i) => `${i + 1}. ${s}`)].join("\n"), data: d };
+    return res.ok ? { text: fieldConnectText(res.data), data: res.data } : failed(res);
   };
 
   const field = async ({ days } = {}) => {
@@ -75,82 +152,40 @@ export function makeVerbs({ api, token, fetchImpl = fetch, ensureRunner = async
     return res.ok ? { text: fieldText(res.data), data: res.data } : failed(res);
   };
 
-  return { status, run, run_status: runStatus, findings, verify, dispute, field_connect: fieldConnect, field };
-}
-
-const pct = (k, n) => (n ? `${Math.round((100 * k) / n)}%` : "n/a");
-const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
-
-export function statusText(d) {
-  const p = d.plan;
-  const lines = [
-    `Cortad · ${d.repository.name} · ${p.name}: ${p.runs.left} of ${plural(p.runs.allowed, "run")} left this month, ${p.trials.left} of ${p.trials.allowed} verify trials.`,
-    `App: ${d.app.said}`,
-    `Conversations written: ${d.cases.written}.${d.cases.ready ? " A run can start." : ""}`,
-  ];
-  lines.push(d.run ? `Latest ${runText(d.run)}` : "No run yet.");
-  lines.push(d.field.connected ? "Production: connected." : `Production: not connected. field_connect says how.`);
-  return lines.join("\n");
-}
-
-export function startedText(d, kind) {
-  if (d.joined) return `A ${d.kind ?? kind} is already in flight: ${d.jobId}. Poll run_status every 30 seconds. Watch it: ${d.url}`;
-  return `${kind === "verify" ? "Verify" : "Run"} started: ${d.jobId}. Poll run_status every 30 seconds and stay quiet unless the count moved. Watch it: ${d.url}`;
-}
-
-export function refusedText(d) {
-  const plans = (d.plans ?? []).map((p) => `${p.name} ($${p.monthlyUsd}/month)`).join(" or ");
-  if (d.refused === "plan") return `The first run was free. Another needs ${plans || "a plan"}: ${d.checkout}\nShow this link to the person in one sentence and wait for them.`;
-  return `${d.why} More on ${plans || "a bigger plan"}: ${d.checkout}\nShow this link to the person and wait.`;
-}
-
-export function runText(d) {
-  const head = `${d.kind} ${d.jobId} ${d.status}: ${d.of ? `played ${d.played} of ${d.of}.` : "starting, nothing played yet."}`;
-  const tail = [];
-  if (d.finished && typeof d.score === "number") tail.push(`Score ${d.score} of 100.`);
-  if (d.finished && typeof d.findings === "number") tail.push(d.findings ? `${plural(d.findings, "finding")}; call findings.` : "No findings stood out.");
-  if (d.stopped) {
-    const side = d.stopped.side === "theirs" ? " (their side)" : d.stopped.side === "ours" ? " (Cortad's side)" : "";
-    const why = `${d.stopped.why[0].toUpperCase()}${d.stopped.why.slice(1)} at turn ${d.stopped.after}${side}. ${d.stopped.fix}`;
-    tail.push(d.of && d.played < d.of ? `Stopped at ${d.played} of ${d.of}: ${why}` : why);
-  }
-  for (const f of d.faults ?? []) tail.push(`${f.what} ${f.fix}`);
-  if (d.error) tail.push(`Error: ${d.error}`);
-  if (d.verify) tail.push(verifyText(d.verify));
-  if (!d.finished) tail.push("Poll again in 30 seconds.");
-  return [head, ...tail, d.url].join(" ");
-}
-
-export function verifyText(v) {
-  const move = v.visible;
-  const line = move
-    ? `${v.file}:${v.line} · held ${move.before.k} of ${move.before.n} before, ${move.after.k} of ${move.after.n} after · move ${move.point} (${move.low} to ${move.high}) · ${move.moved}${move.insideNoise ? ", inside the noise" : ""}.`
-    : "";
-  const held = v.holdout ? ` Held-out situations: ${v.holdout.moved}.` : " Held-out situations: no pair.";
-  return `Verify of ${v.findingId}: ${line}${held}${v.overfit ? " OVERFIT: the visible cases moved and the held-out ones did not." : ""} ${v.said}`;
-}
+  // `status --changed`: the files Cortad cites that changed since the latest run started, with the
+  // findings at them. Empty when there is nothing to say, or nothing could be asked.
+  const changed = async () => {
+    const [s, f] = await Promise.all([call("GET", "/mcp/status"), gather()]);
+    const r = s.ok ? s.data?.run : null;
+    if (!r) return { text: "" };
+    const kept = pending.read();
+    const since = r.startedAt ?? (kept?.jobId === r.jobId ? kept.startedAt : null);
+    const lines = f.ok ? linesOf(f.data) : [];
+    const read = s.data.read ?? {};
+    const paths = [
+      ...lines.map((l) => l.path),
+      ...(read.rules?.examples ?? []).map((e) => e.path),
+      ...(read.machine?.misses ?? []).map((m) => m.path),
+      ...(Array.isArray(read.rules?.files) ? read.rules.files : []),
+    ].filter((p) => typeof p === "string" && p);
+    return { text: changedLine({ root, since, runId: r.jobId, paths, lines }) };
+  };
 
-export function findingsText(d) {
-  if (!d.findings?.length) return [d.why ?? `Run ${d.runId}: no question held worse in one situation than this app does everywhere else.`, d.read, d.heldBack, d.url].filter(Boolean).join(" ");
-  const rows = d.findings.map((f, i) => [
-    `${i + 1}. ${f.id} · ${f.asks}`,
-    `   held ${f.rate.k} of ${f.rate.n} (${pct(f.rate.k, f.rate.n)}, interval ${pct(Math.round(f.rate.lo * f.rate.n), f.rate.n)} to ${pct(Math.round(f.rate.hi * f.rate.n), f.rate.n)}) · ${f.file}:${f.line} · ${f.where}`,
-    ...f.quotes.slice(0, 1).map((q) => `   reply ${q.reply}: "${q.quote}" (p=${q.p.toFixed(2)})`),
-    `   replay: ${plural(f.replay.trials, "trial")} · verify ${f.id}`,
-  ].join("\n"));
-  return [`Run ${d.runId}. ${d.read} ${d.heldBack}`, ...rows, `Fix one finding at a time, in the file it names, then verify it. ${d.url}`].join("\n");
+  // `post` and `changed` serve lib/cli.mjs; the MCP answers only the names in TOOLS.
+  return { status, run, run_status: runStatus, findings, verify, dispute, field_connect: fieldConnect, field, post, changed };
 }
 
-export function fieldText(d) {
-  const t = d.totals;
-  if (!t || !t.n) return `No production conversations read in the last ${d.days} days. ${d.url}`;
-  const lines = [
-    `Production, last ${d.days} days: ${plural(t.n, "conversation")}, ${t.read} read.`,
-    `Rulings held: ${pct(t.rulingsHeld, t.rulings)} of ${t.rulings}${t.rulingsUnsure ? ` (${t.rulingsUnsure} unsure)` : ""}. Resolved ${pct(t.resolved, t.read)}, frustrated ${pct(t.frustrated, t.read)}, asked for a human ${pct(t.wantsHuman, t.read)}, unanswered ${pct(t.unanswered, t.read)}.`,
-  ];
-  const broke = (d.rules ?? []).filter((r) => r.broke > 0).sort((a, b) => b.broke - a.broke).slice(0, 5);
-  if (broke.length) lines.push(`Rules broken most: ${broke.map((r) => `${r.id} (${r.broke})`).join(", ")}.`);
-  if (d.journeys?.length) lines.push(`By journey: ${d.journeys.slice(0, 6).map((j) => `${j.value} ${plural(j.n, "conv")}, ${pct(j.rulingsHeld, j.rulings)} held`).join("; ")}.`);
-  lines.push(d.url);
-  return lines.join("\n");
+// Only paths inside the repository are looked at; a path from the server never reaches outside it.
+export function changedLine({ root, since, runId, paths, lines }) {
+  const t = Date.parse(since ?? "");
+  if (!Number.isFinite(t)) return "";
+  const base = realpathSync(root);
+  const changedFiles = [...new Set(paths)].filter((rel) => {
+    const abs = resolvePath(base, rel);
+    if (!abs.startsWith(base + sep)) return false;
+    try { return statSync(abs).mtimeMs > t; } catch { return false; }
+  });
+  if (!changedFiles.length) return "";
+  const at = (rel) => lines.filter((l) => l.path === rel).flatMap((l) => l.findingIds);
+  return `Changed since run ${runId}: ${changedFiles.map((rel) => (at(rel).length ? `${rel} (${at(rel).join(", ")})` : rel)).join(", ")}.`;
 }