@computesdk/pi-loops 0.0.0-stage → 1.0.0

package/extensions/loop.ts

@@ -0,0 +1,1019 @@
+// Loops as Pi units: one `loop` tool. Your session is the parent; each attempt is a forked Pi session in its own
+// git worktree, driven by a style agent (agents/*.md); the attempt sets its project up and measures itself. The judge is an
+// agent with read/bash that re-measures every candidate where it lives and reads the diffs; the council is a one-shot session.
+// State: .pi/loops/<run>.json (+ the worktrees under .pi/loops/<run>/). Nothing else is written.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import { createAgentSession, DefaultResourceLoader, SessionManager, getAgentDir, type AgentSession, type ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { pickWinner, panelJudge } from "../lib/judge.ts";
+import { better as betterOf, git, restoreProtected, sh, diffText, errText, type GitRunner } from "../lib/measure.ts";
+import { addRule, fromRules, newRubric, parseJson, rubricText, writeRubric } from "../lib/rubric.ts";
+import { sheet } from "../lib/sheet.ts";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/** Package root: `agents/`, `prompts/` and `lib/` sit one level up from `extensions/`. */
+const ROOT = path.resolve(HERE, "..");
+export const STYLES = ["safe", "bold", "wild"];
+export const DEFAULTS = { attempts: 3, rounds: 1, timeoutMin: 15, tokenBudget: null, repeat: 2, minGain: 0.05, judgeSamples: 3, judgePairs: 2, judgePanel: true, council: true, models: {} };
+const STATE_DIR = path.join(".pi", "loops");
+
+/** One agent markdown file: frontmatter (name, model, tools, …) plus body. */
+export type Agent = { role?: string; file?: string; name?: string; model?: string; tools?: string[]; body: string; [key: string]: any };
+/** The model each role runs on: `loops.models` where set, else the attempts and council spread over the pool. */
+export type ModelPlan = { spread: boolean; pool: string[]; safe?: string | null; bold?: string | null; wild?: string | null; judge?: string | null; council?: (string | null)[]; [key: string]: any };
+/** Merged settings: DEFAULTS, then `loops` in settings.json, then ~/.pi/agent/loops.json, then <repo>/.pi/loops.json. */
+export type LoopSettings = { attempts: number; rounds: number; timeoutMin: number; tokenBudget: number | null; repeat: number; minGain: number; judgeSamples: number; judgePairs: number; judgePanel: boolean; council: boolean; models: Record<string, any>; check?: string; bench?: string; metric?: any; protect?: string[]; serve?: string; routes?: string[]; [key: string]: any };
+/** One finished attempt: its worktree, session, cost, and how it ended. */
+export type Attempt = { style: string; label: string; dir?: string; model?: string | null; session?: string | null; tokens?: number; cost?: number; summary?: string; status: string; error?: string; commit?: string; branch?: string; cut?: string; restored?: boolean; bench?: any; review?: any; [key: string]: any };
+/** An attempt that finished and committed: the only kind the judge sees. */
+export type Finished = Attempt & { dir: string; commit: string };
+const finished = (a: Attempt): a is Finished => a.status === "done" && !!a.commit && !!a.dir;
+
+/** A model as Pi names it (`provider` + `id`). */
+export type ModelRef = { provider: string; id: string };
+/** A model as Pi hands it to extensions: what `createAgentSession` takes. */
+export type Model = ReturnType<ModelRegistry["getAvailable"]>[number];
+/** The model-registry methods Loops calls. */
+export type ModelRegistryLike = { getAvailable?: () => ModelRef[]; find?: (provider: string, id: string) => ModelRef | undefined };
+/** The session-manager methods Loops calls. */
+export type SessionManagerLike = { getBranch?: () => any[]; getSessionDir?: () => string; getSessionFile?: () => string | undefined };
+/** The subset of Pi's UI the extension calls. */
+export type Ui = {
+  notify: (message: string, type?: string) => void;
+  select: (title: string, options: string[]) => Promise<string | null>;
+  input?: (title: string, placeholder?: string) => Promise<string | null>;
+  editor?: (title: string, text: string) => Promise<void>;
+  setStatus?: (key: string, text?: string) => void;
+};
+/** The context a model picker needs: no session manager, no UI beyond notify/select/input. */
+export type PickCtx = { cwd: string; model?: ModelRef | null; modelRegistry?: ModelRegistryLike; ui: Ui };
+/** The Pi command/tool context Loops uses (only these fields are touched). */
+export type Ctx = PickCtx & {
+  hasUI?: boolean;
+  sessionManager?: SessionManagerLike;
+  switchSession?: (file: string) => Promise<void>;
+};
+/** The subset of Pi's extension API the extension calls. */
+export type Pi = {
+  registerTool?: (tool: ToolDef) => void;
+  registerCommand?: (name: string, command: { description?: string; handler: (args: string, ctx: Ctx) => Promise<void> | void }) => void;
+  on?: (event: string, handler: (...args: any[]) => any) => void;
+  appendEntry?: (type: string, data?: any) => void;
+  sendUserMessage?: (message: any, options?: any) => void | Promise<void>;
+  getSettings?: () => any;
+  [key: string]: any;
+};
+/** A Pi tool registration (only the parts Loops uses). */
+export type ToolDef<P = any> = {
+  name: string;
+  label: string;
+  description: string;
+  parameters: any;
+  outputSchema?: any;
+  execute: (id: string, params: P, signal: AbortSignal, onUpdate: (update: any) => void, ctx: Ctx) => Promise<any>;
+  renderCall?: (args: any, theme: any) => any;
+  renderResult?: (result: any, options: { expanded: boolean; isPartial: boolean }, theme: any) => any;
+};
+/** A candidate for the judge: a checked-out directory at a commit. */
+export type Candidate = { label: string; dir: string; commit: string; fresh?: boolean };
+/** One round of a run. */
+export type Round = { n: number; from?: string; status: string; attempts: Attempt[]; judge?: any; judgeSession?: string | null; judgeTokens?: number; judgeCost?: number; startedAt?: number; endedAt?: number; sheet?: string | null };
+/** A run's persisted state (`.pi/loops/<run>.json`). */
+export type State = {
+  v?: number;
+  id: string;
+  goal: string;
+  kind: string;
+  status: string;
+  baseCommit: string;
+  metric?: any;
+  rules: string[];
+  protect?: string[];
+  build?: string;
+  shots?: string[];
+  directions?: Record<string, string>;
+  best: { label?: string | null; commit: string; session?: string | null; branch?: string | null; dir?: string | null; score?: number | null; reason?: string | null; round?: number };
+  winner?: any;
+  rounds: Round[];
+  rubric?: any;
+  models?: any;
+  editedBaseline?: boolean;
+  openNext?: string | null;
+  parentSession?: string | null;
+  check?: string;
+  bench?: string;
+  [key: string]: any;
+};
+/** The parameters of the `loop` tool, and of a brief. */
+export type LoopParamsIn = {
+  goal?: string;
+  check?: string;
+  bench?: string;
+  metric?: any;
+  protect?: string[];
+  build?: string;
+  shots?: string[];
+  rounds?: number;
+  from?: string;
+  rules?: string[];
+  routes?: string[];
+  directions?: Record<string, string>;
+  confirm?: boolean;
+  wait?: boolean;
+};
+/** A brief: the tool params plus whatever the project's .pi/loops.json contributes. */
+export type SpecView = LoopParamsIn & { serve?: string | null };
+/** What the build wrote, or why it could not. */
+export type ShotFiles = { error?: string; files?: string[]; have: string[] };
+/** One attempt's live progress, as the tool's details carry it. */
+export type AttemptDetail = { style: string; status: string; tool: string | null; tools: number; tokens: number; text: string };
+/** The tool's structured details: what the renderer draws while a round runs. */
+export type Details = { run: string | null; kind: string; round: number | null; judge?: any; attempts: AttemptDetail[]; phase: string; spec?: any; [key: string]: any };
+
+/* ---------- agents (Pi agent markdown) ---------- */
+export function parseAgent(md: string): Agent {
+  const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(md);
+  const fm: Record<string, string> = {};
+  if (m) for (const line of m[1].split("\n")) { const i = line.indexOf(":"); if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim(); }
+  const tools = fm.tools === undefined ? undefined : fm.tools.split(",").map((s) => s.trim()).filter(Boolean);
+  return { ...fm, tools, body: (m ? m[2] : md).trim() };
+}
+/** agents/<role>.md from the project (.pi/agents), the user (~/.pi/agent/agents), then this package. */
+export function loadAgent(role: string, { cwd, agentDir = getAgentDir() }: { cwd?: string; agentDir?: string } = {}): Agent {
+  for (const dir of [cwd && path.join(cwd, ".pi", "agents"), path.join(agentDir, "agents"), path.join(ROOT, "agents")]) {
+    const f = dir && path.join(dir, `${role}.md`);
+    if (f && fs.existsSync(f)) return { role, file: f, ...parseAgent(fs.readFileSync(f, "utf8")) };
+  }
+  throw new Error(`no agent markdown for ${role}`);
+}
+
+/* ---------- config: ~/.pi/agent/loops.json (your defaults) + <repo>/.pi/loops.json (this repo; wins per key) ---------- */
+export const CONFIG_FILE = "loops.json";
+export const configFiles = (cwd: string, agentDir: string = getAgentDir()) => ({ user: path.join(agentDir, CONFIG_FILE), project: path.join(cwd, ".pi", CONFIG_FILE) });
+function readJson(f: string): Record<string, any> { if (!fs.existsSync(f)) return {}; const j = JSON.parse(fs.readFileSync(f, "utf8")); if (!j || typeof j !== "object" || Array.isArray(j)) throw new Error(`${f} is not a JSON object`); return j; }
+export function loopSettings(pi: Pi | null, cwd: string, agentDir: string = getAgentDir()): LoopSettings {
+  let s: Record<string, any> = {};
+  const merge = (j: Record<string, any>) => { s = { ...s, ...j, models: { ...(s.models ?? {}), ...(j.models ?? {}) } }; };
+  // legacy, lowest precedence: `loops` in Pi's settings.json (user, then project), or whatever Pi hands us
+  for (const f of [path.join(agentDir, "settings.json"), path.join(cwd, ".pi", "settings.json")]) { try { merge(readJson(f).loops ?? {}); } catch {} }
+  try { merge(pi?.getSettings?.()?.loops ?? {}); } catch {}
+  const { user, project } = configFiles(cwd, agentDir);
+  for (const f of [user, project]) { let j = {}; try { j = readJson(f); } catch {} merge(j); }
+  return { ...DEFAULTS, ...s, models: { ...DEFAULTS.models, ...(s.models ?? {}) } };
+}
+/** Merge `patch` into <repo>/.pi/loops.json (models merged one level deeper). Throws when the file exists but isn't a JSON object. */
+export function saveConfig(cwd: string, patch: Record<string, any>): Record<string, any> {
+  const f = configFiles(cwd).project;
+  const cur = readJson(f);
+  const next: Record<string, any> = { ...cur, ...patch, ...(patch.models ? { models: { ...(cur.models ?? {}), ...patch.models } } : {}) };
+  for (const k of Object.keys(next)) if (next[k] === null) delete next[k];
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, JSON.stringify(next, null, 2) + "\n");
+  return next;
+}
+export function parseBudget(v: unknown): number | null {
+  const m = String(v ?? "").trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*([km])?$/);
+  if (!m) return null;
+  return Math.round(Number(m[1]) * (m[2] === "m" ? 1_000_000 : m[2] === "k" ? 1_000 : 1));
+}
+
+const modelSpec = (m: ModelRef) => `${m.provider}/${m.id}`;
+const globRe = (pat: string) => new RegExp("^" + pat.split("*").map((x) => x.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$");
+/** Which model each role runs on. Explicit `loops.models` wins; otherwise the attempts and council members are spread over the pool
+ *  (`loops.models.pool`, else Pi's `enabledModels`) so a round compares models too; with no pool everything runs on the current model. */
+export function resolveModels({ settings, available = [], current = null, enabledModels = [] }: { settings: { models?: Record<string, any> }; available?: ModelRef[]; current?: string | null; enabledModels?: string[] }): ModelPlan {
+  const m = settings.models ?? {};
+  const specs = available.map(modelSpec);
+  const patterns: string[] = Array.isArray(m.pool) && m.pool.length ? m.pool : enabledModels;
+  let pool = patterns.flatMap((p) => specs.filter((sp) => sp === p || sp.endsWith("/" + p) || (p.includes("*") && globRe(p).test(sp))));
+  pool = [...new Set(pool)];
+  if (current && pool.includes(current)) pool = [current, ...pool.filter((x) => x !== current)];
+  const spread = pool.length >= 2;
+  const out: ModelPlan = { spread, pool };
+  STYLES.forEach((style, i) => { out[style] = m[style] ?? (pool.length ? pool[i % pool.length] : null); });
+  out.judge = m.judge ?? null;
+  const council = Array.isArray(m.council) ? m.council : m.council ? [m.council, m.council] : pool.length ? pool.slice(0, 3) : [null, null];
+  out.council = council.length >= 2 ? council : [...council, ...council].slice(0, 2);
+  return out;
+}
+export function modelsOf(ctx: PickCtx, settings: LoopSettings, pi: Pi | null): ModelPlan {
+  let enabled: string[] = [];
+  try { enabled = pi?.getSettings?.()?.enabledModels ?? []; } catch {}
+  if (!enabled.length) { try { enabled = JSON.parse(fs.readFileSync(path.join(getAgentDir(), "settings.json"), "utf8")).enabledModels ?? []; } catch {} }
+  const available = ctx.modelRegistry?.getAvailable?.() ?? [];
+  return resolveModels({ settings, available, current: ctx.model ? modelSpec(ctx.model) : null, enabledModels: enabled });
+}
+export const shortModel = (spec?: string | null) => (spec ? spec.split("/").pop() ?? spec : "current");
+function pickModel(ctx: Ctx, spec?: string | null): Model {
+  const reg = ctx.modelRegistry;
+  // At runtime these are full Pi models; the registry is typed loosely so tests can pass { provider, id } stubs.
+  if (spec) {
+    const [provider, ...rest] = spec.split("/");
+    const m = (rest.length ? reg?.find?.(provider, rest.join("/")) : reg?.getAvailable?.().find((x) => x.id === spec)) as Model | undefined;
+    if (m) return m;
+    throw new Error(`model "${spec}" is not available (check /login, models.json or the loops.models setting)`);
+  }
+  const m = (ctx.model ?? reg?.getAvailable?.()[0]) as Model | undefined;
+  if (!m) throw new Error("no model available: log in with /login first");
+  return m;
+}
+
+/* ---------- state: .pi/loops/<run>.json ---------- */
+const stateFile = (cwd: string, id: string) => path.join(cwd, STATE_DIR, `${id}.json`);
+export function saveState(cwd: string, state: State) {
+  const f = stateFile(cwd, state.id);
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const gi = path.join(cwd, ".gitignore");
+  const cur = fs.existsSync(gi) ? fs.readFileSync(gi, "utf8") : "";
+  if (!cur.split("\n").some((l) => /^\/?\.pi\/loops\/?$/.test(l.trim()))) fs.writeFileSync(gi, (cur && !cur.endsWith("\n") ? cur + "\n" : cur) + ".pi/loops\n");
+  fs.writeFileSync(f + ".tmp", JSON.stringify(state, null, 2));
+  fs.renameSync(f + ".tmp", f);
+  return f;
+}
+/** Screenshots and the shots dir stay out of every worktree's commits: the repo's info/exclude applies to all of them. */
+export function excludeShots(cwd: string, shots: string[] | null | undefined, g: GitRunner = git) {
+  const want = [".loops-shots/", ...(shots ?? [])].map((f) => f.replace(/^\.\//, ""));
+  const common = path.resolve(cwd, g(cwd, "rev-parse", "--git-common-dir"));
+  const f = path.join(common, "info", "exclude");
+  const cur = fs.existsSync(f) ? fs.readFileSync(f, "utf8") : "";
+  const missing = want.filter((w) => !cur.split("\n").some((l) => l.trim() === w));
+  if (!missing.length) return;
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, (cur && !cur.endsWith("\n") ? cur + "\n" : cur) + missing.join("\n") + "\n");
+}
+/** The runs this session started (newest first), from its own transcript entries — not the repo's whole .pi/loops/. */
+export function sessionRuns(ctx: { sessionManager?: SessionManagerLike }): string[] {
+  try { return (ctx.sessionManager?.getBranch?.() ?? []).filter((e) => e.type === "custom" && e.customType === "loops-run" && e.data?.id).map((e) => e.data.id).reverse().filter((id, i, a) => a.indexOf(id) === i); } catch { return []; }
+}
+export function loadState(cwd: string, from?: string | null): State {
+  const dir = path.join(cwd, STATE_DIR);
+  let id = from;
+  if (!id || id === "last") {
+    const runs = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort((a, b) => fs.statSync(path.join(dir, a)).mtimeMs - fs.statSync(path.join(dir, b)).mtimeMs || a.localeCompare(b)) : [];
+    if (!runs.length) throw new Error(`no runs in ${STATE_DIR}/ to resume`);
+    id = runs[runs.length - 1].replace(/\.json$/, "");
+  }
+  const f = stateFile(cwd, id.replace(/\.json$/, ""));
+  if (!fs.existsSync(f)) throw new Error(`no run ${id} in ${STATE_DIR}/`);
+  return JSON.parse(fs.readFileSync(f, "utf8"));
+}
+
+/* ---------- prompts ---------- */
+export function attemptPrompt(state: State, style: string, n: number, settings: Partial<LoopSettings> = DEFAULTS) {
+  const rules = state.rules.length ? `Rules:\n${state.rules.map((r) => "- " + r).join("\n")}\n` : "";
+  const how = [state.check && `Check (must pass): ${state.check}`, state.bench && `Benchmark: ${state.bench} (prints ${state.metric?.unit ?? "ms"}; ${state.metric?.better ?? "lower"} is better)`,
+    state.protect?.length && `Protected files, do not edit: ${state.protect.join(", ")}`, state.build && `Build: ${state.build}${state.shots?.length ? ` (must write ${state.shots.join(", ")})` : ""}`].filter(Boolean).join("\n");
+  const best = state.best;
+  const lead = n === 1 ? `Round 1 of a hill-climbing loop. Goal: ${state.goal}`
+    : `Round ${n}. The version you are looking at was judged the best so far${best.score != null ? ` (${best.score} ${state.metric?.unit ?? ""})` : ""}${best.reason ? `. Feedback: "${best.reason}"` : ""}. Improve on it further.\nGoal: ${state.goal}`;
+  return `${lead}\n${rules}${how}\nBudget: about ${settings.tokenBudget ? `${Math.round(settings.tokenBudget / 1000)}k tokens` : "unlimited tokens"} and ${settings.timeoutMin ?? "unlimited"} minutes; whatever is committed when it runs out is judged, so land a working change early and refine after. Your direction: ${style.toUpperCase()}${state.directions?.[style] ? ` — ${state.directions[style]}` : ""}. Work in the current directory only. It is a fresh checkout: if the project needs setting up (dependencies installed, the way the repo's docs say), do that first. Before you finish, run the check${state.bench ? " and the benchmark" : state.build ? " and the build" : ""} yourself${state.bench ? " and put the benchmark number in your summary" : ""}. Leave no scratch or helper files behind unless the goal needs them (delete temporary checks before you finish). When finished, reply with exactly ONE line summarising what you changed.`;
+}
+
+/** session.prompt takes text + images separately: number each image in place so the text still says which candidate it belongs to. */
+export function flattenParts(content: string | any[]): { text: string; images: any[] } {
+  const parts = typeof content === "string" ? [{ type: "text", text: content }] : content;
+  const images: any[] = [];
+  const text = parts.map((p) => (p.type === "image" ? (images.push(p), `[image ${images.length}]`) : p.text)).join("\n");
+  return { text, images };
+}
+
+/* ---------- rounds running in the background, so the parent can steer them while they run ---------- */
+export const RUNS = new Map<string, any>();
+export function liveRun(id?: string | null) {
+  if (id && id !== "last") { const r = RUNS.get(id); if (!r) throw new Error(`${id} is not running${RUNS.size ? ` (running: ${[...RUNS.keys()].join(", ")})` : ""}`); return r; }
+  const r = [...RUNS.values()].pop();
+  if (!r) throw new Error("no loop is running");
+  return r;
+}
+export function findAttempt(live: { attempts: Map<string, any> }, name: unknown): string | null {
+  const want = String(name).toLowerCase();
+  return [...live.attempts.keys()].find((k) => k.toLowerCase() === want || k.toLowerCase().endsWith("-" + want)) ?? null;
+}
+
+/* ---------- live child sessions, so a session_shutdown mid-round can stop them ---------- */
+const active = new Set<any>();
+let shuttingDown = false;
+const track = (session: AgentSession) => { if (shuttingDown) { try { session.dispose(); } catch {} throw new Error("Pi is shutting down"); } active.add(session); return session; };
+const release = (session: AgentSession) => { active.delete(session); try { session.dispose(); } catch {} };
+export async function stopAll() { shuttingDown = true; const all = [...active]; active.clear(); await Promise.allSettled(all.map((s) => s.abort?.().catch(() => {}))); for (const s of all) { try { s.dispose(); } catch {} } return all.length; }
+
+/* ---------- one-shot agent sessions (visual judge panel / council): no tools, Pi auth + session header ---------- */
+async function oneShot({ role, model, content, cwd, ctx, settings, signal }: { role: string; model?: string | null; content: any; cwd: string; ctx: Ctx; settings: LoopSettings; signal?: AbortSignal }) {
+  const agentDir = getAgentDir();
+  const agent = loadAgent(role, { cwd, agentDir });
+  const loader = new DefaultResourceLoader({ cwd, agentDir, noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true, systemPrompt: agent.body });
+  await loader.reload();
+  const { session: created } = await createAgentSession({ cwd, agentDir, model: pickModel(ctx, model ?? settings.models[role] ?? agent.model), noTools: "all", resourceLoader: loader, sessionManager: SessionManager.inMemory(cwd) });
+  const session = track(created);
+  const { text, images } = flattenParts(content);
+  const onAbort = () => session.abort().catch(() => {});
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    await session.prompt(text, { images, expandPromptTemplates: false });
+    let last = session.messages.filter((m) => m.role === "assistant").pop();
+    if (last?.stopReason === "error") throw new Error(last.errorMessage || `${role} errored`);
+    if (!(session.getLastAssistantText() ?? "").trim()) {
+      await session.prompt("You answered with nothing. Answer now with the JSON object asked for and nothing else.", { expandPromptTemplates: false });
+      last = session.messages.filter((m) => m.role === "assistant").pop();
+      if (last?.stopReason === "error") throw new Error(last.errorMessage || `${role} errored`);
+    }
+    return parseJson(session.getLastAssistantText());
+  } finally { signal?.removeEventListener("abort", onAbort); release(session); }
+}
+
+/* ---------- an attempt: forked session + worktree + style agent ---------- */
+async function runAttempt({ state, style, n, dir, ctx, settings, model, signal, onProgress, live }: { state: State; style: string; n: number; dir: string; ctx: Ctx; settings: LoopSettings; model?: string | null; signal?: AbortSignal; onProgress: (progress: any) => void; live?: any }): Promise<Attempt> {
+  const agentDir = getAgentDir();
+  const agent = loadAgent(style, { cwd: ctx.cwd, agentDir });
+  const sessionDir = ctx.sessionManager?.getSessionDir?.();
+  const src = state.best.session ?? ctx.sessionManager?.getSessionFile?.();
+  const sessionManager = src && fs.existsSync(src) ? SessionManager.forkFrom(src, dir, sessionDir) : SessionManager.create(dir, sessionDir);
+  const loader = new DefaultResourceLoader({ cwd: dir, agentDir, noExtensions: true, noPromptTemplates: true, noThemes: true, appendSystemPrompt: [agent.body] });
+  await loader.reload();
+  const picked = pickModel(ctx, model ?? settings.models[style] ?? agent.model);
+  const { session: created } = await createAgentSession({ cwd: dir, agentDir, model: picked, tools: agent.tools?.length ? agent.tools : undefined, resourceLoader: loader, sessionManager });
+  const session = track(created);
+  live?.attempts.set(`R${n}-${style}`, session);
+  const p: { style: string; status: string; tool: string | null; tools: number; tokens: number; cost: number; text: string } = { style, status: "running", tool: null, tools: 0, tokens: 0, cost: 0, text: "" };
+  let ended: string | null = null;
+  const unsub = session.subscribe((e) => {
+    if (e.type === "tool_execution_start") { p.tool = e.toolName; p.tools++; onProgress(p); }
+    else if (e.type === "tool_execution_end") { p.tool = null; onProgress(p); }
+    else if (e.type === "message_end" && e.message?.role === "assistant") {
+      p.tokens += e.message.usage?.totalTokens || 0;
+      p.cost += typeof e.message.usage?.cost === "number" ? e.message.usage.cost : e.message.usage?.cost?.total || 0;
+      const t = (e.message.content || []).filter((c) => c.type === "text").map((c) => c.text).join("").trim();
+      if (t) p.text = t.slice(-200);
+      onProgress(p);
+      if (settings.tokenBudget && p.tokens > settings.tokenBudget && !ended) { ended = "budget"; session.abort().catch(() => {}); }
+    }
+  });
+  const timer = settings.timeoutMin ? setTimeout(() => { ended ??= "timeout"; session.abort().catch(() => {}); }, settings.timeoutMin * 60_000) : null;
+  const onAbort = () => { ended ??= "aborted"; session.abort().catch(() => {}); };
+  if (signal?.aborted) onAbort(); else signal?.addEventListener("abort", onAbort, { once: true });
+  let err = "";
+  try { await session.prompt(attemptPrompt(state, style, n, settings), { expandPromptTemplates: false }); } catch (e) { err = errText(e); }
+  finally { if (timer) clearTimeout(timer); signal?.removeEventListener("abort", onAbort); unsub(); }
+  const last = session.messages.filter((m) => m.role === "assistant").pop();
+  if (!ended && last?.stopReason === "error") err ||= last.errorMessage || "agent error";
+  const out = { style, label: `R${n}-${style}`, dir, model: modelSpec(picked), session: session.sessionFile ?? null, tokens: p.tokens, cost: +p.cost.toFixed(4), summary: (session.getLastAssistantText() ?? "").trim().split("\n").pop()?.slice(0, 200) ?? "" };
+  release(session);
+  live?.attempts.delete(`R${n}-${style}`);
+  if (ended === "aborted") return { ...out, status: ended, error: err };
+  if (!ended && err) return { ...out, status: "error", error: err.slice(0, 300) };
+  try { git(dir, "add", "-A"); if (state.shots?.length) { try { git(dir, "reset", "-q", "--", ...state.shots); } catch {} } git(dir, "commit", "-q", "-m", `${out.label}: ${out.summary || "attempt"}`); } catch {}
+  const commit = git(dir, "rev-parse", "HEAD");
+  if (commit === state.best.commit) return { ...out, status: ended ?? "unchanged", commit, error: err };
+  return { ...out, status: "done", commit, ...(ended ? { cut: ended } : {}) };
+}
+
+/* ---------- the judge: an agent with read/bash re-measures every candidate where it lives and reads the diffs ---------- */
+export function verifyPrompt(state: State, n: number, cands: Candidate[], { repeat = 2 }: { repeat?: number } = {}) {
+  const unit = state.metric?.unit || "ms", better = state.metric?.better ?? "lower";
+  const rules = state.rules.length ? `Rules every attempt must follow:\n${state.rules.map((r) => "- " + r).join("\n")}\n` : "";
+  const rubric = state.rubric ? `Rubric (the council wrote it; a change that fails a criterion is not ok):\n${rubricText(state.rubric)}\n` : "";
+  const list = cands.map((c) => `- ${c.label}: ${c.dir} at commit ${c.commit.slice(0, 7)}${c.label === "CURRENT" ? (c.fresh ? " — the best so far, a fresh checkout: set it up the way the attempts did before measuring" : n === 1 ? " — the best so far; the user's own checkout, already set up. Do not modify it." : " — the best so far (the previous winner's worktree, already set up)") : " — set up by the attempt itself; if the check or benchmark cannot run only because of missing setup, set it up (install dependencies); never edit source files"}`).join("\n");
+  const protect = state.protect?.length ? ` (${state.protect.join(", ")} were restored to the base version before judging; ignore them)` : "";
+  return `You judge round ${n} of a hill-climbing loop. Goal: ${state.goal}
+${rules}${rubric}Check (must exit 0): ${state.check ?? "none"}
+Benchmark: ${state.bench} — prints ${unit}; ${better} is better. Run it ${repeat} times per candidate and keep the best sample.
+
+Candidates. Each is a checked-out directory; measure every one yourself, in that directory, on this machine, under the same conditions:
+${list}
+
+For each attempt (not CURRENT) read its change too: \`git diff ${cands[0].commit.slice(0, 7)} HEAD\` in its directory${protect}. Veto rule breaks and cheating: special-casing benchmark inputs, caching results across calls, skipping work the goal requires, weakening the check or the benchmark.
+
+Do not edit any file anywhere. When done, reply with exactly one JSON object and nothing else:
+{"CURRENT":{"value":<best sample, number or null>,"note":"<=15 words"},"<attempt label>":{"check":true|false,"value":<best sample, number or null>,"ok":true|false,"note":"<=20 words: what the change does, or why it failed or is vetoed"}}`;
+}
+
+async function judgeRound({ state, n, cands, cwd, ctx, settings, model, signal, onProgress }: { state: State; n: number; cands: Candidate[]; cwd: string; ctx: Ctx; settings: LoopSettings; model?: string | null; signal?: AbortSignal; onProgress: (progress: any) => void }) {
+  return agentJSON({ role: "judge", model, prompt: verifyPrompt(state, n, cands, settings), ok: (out: any) => "CURRENT" in out, cwd, ctx, settings, signal, onProgress });
+}
+
+async function agentJSON({ role, model, prompt, ok, cwd, ctx, settings, signal, onProgress }: { role: string; model?: string | null; prompt: string; ok: (out: any) => boolean; cwd: string; ctx: Ctx; settings: LoopSettings; signal?: AbortSignal; onProgress: (progress: any) => void }) {
+  const agentDir = getAgentDir();
+  const agent = loadAgent(role, { cwd, agentDir });
+  const loader = new DefaultResourceLoader({ cwd, agentDir, noExtensions: true, noPromptTemplates: true, noThemes: true, appendSystemPrompt: [agent.body] });
+  await loader.reload();
+  const { session: created } = await createAgentSession({ cwd, agentDir, model: pickModel(ctx, model ?? settings.models[role] ?? agent.model), tools: agent.tools?.length ? agent.tools : undefined, resourceLoader: loader, sessionManager: SessionManager.create(cwd, ctx.sessionManager?.getSessionDir?.()) });
+  const session = track(created);
+  const p: { tool: string | null; tools: number; tokens: number; cost: number } = { tool: null, tools: 0, tokens: 0, cost: 0 };
+  const unsub = session.subscribe((e) => {
+    if (e.type === "tool_execution_start") { p.tool = e.toolName; p.tools++; onProgress(p); }
+    else if (e.type === "tool_execution_end") { p.tool = null; onProgress(p); }
+    else if (e.type === "message_end" && e.message?.role === "assistant") { p.tokens += e.message.usage?.totalTokens || 0; p.cost += typeof e.message.usage?.cost === "number" ? e.message.usage.cost : e.message.usage?.cost?.total || 0; onProgress(p); }
+  });
+  const onAbort = () => session.abort().catch(() => {});
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    for (let i = 0; i < 2; i++) {
+      await session.prompt(prompt, { expandPromptTemplates: false });
+      const last = session.messages.filter((m) => m.role === "assistant").pop();
+      if (last?.stopReason === "error") throw new Error(last.errorMessage || `${role} errored`);
+      try { const out = parseJson(session.getLastAssistantText()); if (out && typeof out === "object" && ok(out)) return { out, session: session.sessionFile ?? null, tokens: p.tokens, cost: +p.cost.toFixed(4) }; } catch {}
+      prompt = "Reply with only the JSON object described, nothing else.";
+    }
+    throw new Error(`${role} never answered in shape`);
+  } finally { signal?.removeEventListener("abort", onAbort); unsub(); release(session); }
+}
+
+/* ---------- the tool ---------- */
+const Metric = Type.Object({ key: Type.Optional(Type.String({ description: "JSON key in the bench output; default ms" })), unit: Type.Optional(Type.String()), better: Type.Optional(Type.Union([Type.Literal("lower"), Type.Literal("higher")])) });
+const RoundOut = Type.Object({ n: Type.Number(), pick: Type.Union([Type.String(), Type.Null()]), why: Type.Union([Type.String(), Type.Null()]), scores: Type.Record(Type.String(), Type.Union([Type.Number(), Type.Null()])), reasons: Type.Record(Type.String(), Type.String()), sheet: Type.Union([Type.String(), Type.Null()]),
+  attempts: Type.Array(Type.Object({ label: Type.String(), style: Type.String(), status: Type.String(), model: Type.Union([Type.String(), Type.Null()]), commit: Type.Union([Type.String(), Type.Null()]), session: Type.Union([Type.String(), Type.Null()]), summary: Type.String(), cost: Type.Number() })) });
+export const LoopResult = Type.Object({
+  run: Type.String(), status: Type.String(), kind: Type.String(), goal: Type.String(), baseCommit: Type.String(),
+  metric: Type.Object({ key: Type.Union([Type.String(), Type.Null()]), unit: Type.Union([Type.String(), Type.Null()]), better: Type.Union([Type.String(), Type.Null()]) }),
+  best: Type.Object({ label: Type.Union([Type.String(), Type.Null()]), commit: Type.Union([Type.String(), Type.Null()]), score: Type.Union([Type.Number(), Type.Null()]), branch: Type.Union([Type.String(), Type.Null()]) }),
+  rounds: Type.Array(RoundOut),
+});
+export function structuredResult(state: Pick<State, "id" | "status" | "kind" | "goal" | "baseCommit" | "metric" | "best">, rounds: Round[]) {
+  const n = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+  return {
+    run: state.id, status: state.status, kind: state.kind, goal: state.goal, baseCommit: state.baseCommit,
+    metric: { key: state.metric?.key ?? null, unit: state.metric?.unit ?? null, better: state.metric?.better ?? null },
+    best: { label: state.best?.label ?? null, commit: state.best?.commit ?? null, score: n(state.best?.score), branch: state.best?.branch ?? null },
+    rounds: rounds.map((r) => ({ n: r.n, pick: r.judge?.pick ?? null, why: r.judge?.why ?? null, scores: Object.fromEntries(Object.entries(r.judge?.scores ?? {}).map(([k, v]) => [k, n(v)])), reasons: Object.fromEntries(Object.entries(r.judge?.reasons ?? {}).map(([k, v]) => [k, String(v)])), sheet: r.sheet ?? null,
+      attempts: r.attempts.map((a) => ({ label: a.label, style: a.style, status: a.status, model: a.model ?? null, commit: a.commit ?? null, session: a.session ?? null, summary: a.summary ?? "", cost: n(a.cost) ?? 0 })) })),
+  };
+}
+export const LoopParams = Type.Object({
+  confirm: Type.Optional(Type.Boolean({ description: "Show the spec and ask approve / change / discuss before running (default true in the TUI; never without a UI)" })),
+  wait: Type.Optional(Type.Boolean({ description: "Block until the round is done (always the case without a UI, e.g. pi -p); default in the TUI: return once the round has started and deliver the card as a message" })),
+  goal: Type.Optional(Type.String({ description: "What to improve. Required unless `from` is set." })),
+  check: Type.Optional(Type.String({ description: "Command that must pass (tests)" })),
+  bench: Type.Optional(Type.String({ description: "Command that prints the metric (a JSON line or a number); sets bench mode" })),
+  metric: Type.Optional(Metric),
+  protect: Type.Optional(Type.Array(Type.String(), { description: "Files attempts may not change (restored before judging)" })),
+  build: Type.Optional(Type.String({ description: "Visual mode: command that builds the page and writes the screenshots" })),
+  shots: Type.Optional(Type.Array(Type.String(), { description: "Visual mode: screenshot files the build writes, judged as images" })),
+  rounds: Type.Optional(Type.Number({ description: "Rounds to run now (default 1)" })),
+  from: Type.Optional(Type.String({ description: "Run id (or \"last\") to continue from its last judged round" })),
+  rules: Type.Optional(Type.Array(Type.String(), { description: "Rules every attempt must follow; the judge vetoes breaches" })),
+  routes: Type.Optional(Type.Array(Type.String(), { description: "Visual goals: routes to screenshot (e.g. /pricing) with the project's `serve` from .pi/loops.json; builds `build` + `shots` for you" })),
+  directions: Type.Optional(Type.Object({ safe: Type.Optional(Type.String()), bold: Type.Optional(Type.String()), wild: Type.Optional(Type.String()) }, { description: "Goal-specific angle for each attempt style" })),
+});
+export const InitParams = Type.Object({
+  serve: Type.Optional(Type.String({ description: "Starts the app on $PORT, e.g. `npm run dev -- --port $PORT`; omit when there is no web app" })),
+  check: Type.Optional(Type.String({ description: "Tests / typecheck command that must pass" })),
+  bench: Type.Optional(Type.String({ description: "Script that prints the number to climb" })),
+  metric: Type.Optional(Metric),
+  protect: Type.Optional(Type.Array(Type.String(), { description: "Files attempts may not edit" })),
+});
+
+const fmt = (x: unknown, unit?: string | null) => (x == null ? "—" : `${x} ${unit ?? ""}`.trim());
+export function roundTable(state: State, round: Round): string {
+  const unit = state.metric?.unit ?? (state.kind === "bench" ? "ms" : "");
+  const j = round.judge ?? {};
+  const kept = (label: string) => (j.pick === label ? "✓" : "");
+  const rows = round.attempts.map((a) => [kept(a.label), a.label, a.style, a.model ? shortModel(a.model) : "", a.status !== "done" ? a.status : a.vetoed || (a.review && a.review.ok === false) ? "vetoed" : fmt(j.scores?.[a.label] ?? a.bench?.value, unit), (j.reasons?.[a.label] ?? a.error ?? a.summary ?? "").slice(0, 90)]);
+  if (j.scores?.CURRENT != null) rows.unshift([kept("CURRENT"), "CURRENT", "best so far", "", fmt(j.scores.CURRENT, unit), j.reasons?.CURRENT ?? ""]);
+  const head = ["", "attempt", "style", "model", state.kind === "bench" ? "result" : "score", "judge"];
+  const w = head.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i]).length)));
+  const line = (r: string[]) => r.map((c, i) => String(c).padEnd(w[i])).join("  ").trimEnd();
+  return [line(head), line(w.map((n, i) => (head[i] ? "-" : " ").repeat(n))), ...rows.map(line)].join("\n");
+}
+/** What the winner changed vs the baseline: files tracked in the baseline (safe to apply) vs files the attempt added or removed. */
+export function winnerFiles(cwd: string, base: string, commit: string, g: GitRunner = git) {
+  const changed: string[] = [], added: string[] = [], removed: string[] = [];
+  for (const line of g(cwd, "diff", "--name-status", `${base}..${commit}`).split("\n").filter(Boolean)) {
+    const [st, ...rest] = line.split("\t");
+    const f = rest[rest.length - 1];
+    if (st.startsWith("A")) added.push(f); else if (st.startsWith("D")) removed.push(f); else changed.push(f);
+  }
+  return { changed, added, removed };
+}
+export function applyHint(best: { commit: string; label?: string | null; score?: number | null }, files: { changed: string[]; added: string[]; removed: string[] }): string[] {
+  const q = (xs: string[]) => xs.map((f) => (/[^\w./-]/.test(f) ? JSON.stringify(f) : f)).join(" ");
+  const lines: string[] = [];
+  if (files.changed.length) lines.push(`Apply (tracked files only): git checkout ${best.commit.slice(0, 7)} -- ${q(files.changed)}`);
+  else lines.push("Apply: nothing — the winner changed no tracked file.");
+  if (files.added.length) lines.push(`Not applied — new files the attempt left in its worktree: ${q(files.added)} (take one explicitly with git checkout ${best.commit.slice(0, 7)} -- <file>)`);
+  if (files.removed.length) lines.push(`Not applied — files the attempt deleted: ${q(files.removed)} (git rm them yourself if intended)`);
+  return lines;
+}
+
+/** Take a run's best into the checkout: the winner's changed tracked files from its commit, committed. New/deleted files are reported, not applied. */
+export function applyBest(cwd: string, state: State, g: GitRunner = git) {
+  const best: Partial<State["best"]> = state.best ?? {};
+  if (!best.commit || best.commit === state.baseCommit) throw new Error(`${state.id}: nothing to apply — no attempt beat the baseline`);
+  const files = winnerFiles(cwd, state.baseCommit, best.commit, g);
+  if (!files.changed.length) return { applied: [], files, commit: null };
+  const dirty = g(cwd, "status", "--porcelain", "--untracked-files=no").split("\n").filter((l) => l.trim()).map((l) => l.trim().split(/\s+/).pop());
+  const clash = files.changed.filter((f) => dirty.includes(f));
+  if (clash.length) throw new Error(`uncommitted changes in ${clash.join(", ")} — commit or stash them first`);
+  g(cwd, "checkout", best.commit, "--", ...files.changed);
+  g(cwd, "add", "--", ...files.changed);
+  if (!g(cwd, "status", "--porcelain", "--", ...files.changed).trim()) return { applied: [], files, commit: null, already: true };
+  const score = best.score != null ? ` (${best.score}${state.metric?.unit ? " " + state.metric.unit : ""})` : "";
+  g(cwd, "commit", "-q", "-m", `${(state.goal ?? "loop").slice(0, 60)} — ${best.label} from ${state.id}${score}`);
+  return { applied: files.changed, files, commit: g(cwd, "rev-parse", "HEAD") };
+}
+
+/** The climb so far, one line per round: CURRENT, each attempt with its delta, what was kept. */
+export function climbText(state: State): string {
+  const unit = state.metric?.unit ?? "";
+  const lines: string[] = [];
+  for (const r of state.rounds ?? []) {
+    const j = r.judge; if (!j) { lines.push(`r${r.n}  (not judged)`); continue; }
+    const cur = j.scores?.CURRENT;
+    const parts = r.attempts.map((a) => {
+      const v = j.scores?.[a.label];
+      const who = a.model ? `${a.style}/${shortModel(a.model)}` : a.style;
+      if (a.status !== "done") return `${who} ${a.status}`;
+      if (v == null) return `${who} ${(j.reasons?.[a.label] ?? "no number").slice(0, 24)}`;
+      const d = cur != null && cur !== 0 ? ` (${v < cur ? "" : "+"}${(((v - cur) / cur) * 100).toFixed(1)}%)` : "";
+      return `${who} ${fmt(v, unit)}${d}${j.pick === a.label ? " ✓" : ""}`;
+    });
+    lines.push(`r${r.n}  CURRENT ${cur != null ? fmt(cur, unit) : "?"}  │  ${parts.join("  ·  ")}  →  kept ${j.pick}${j.human ? " (yours)" : ""}${r.sheet ? `  [${r.sheet}]` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+export function resultText(state: State, rounds: Round[], cwd: string): string {
+  const out: string[] = [];
+  const unit = state.metric?.unit ?? (state.kind === "bench" ? "ms" : "");
+  // Scan order: the verdict (what was kept, why) and the next action first, the attempt table second, supporting detail last.
+  const last = rounds[rounds.length - 1];
+  for (const r of rounds) {
+    const j = r.judge;
+    const score = j && j.pick !== "CURRENT" ? j.scores?.[j.pick] : null;
+    out.push(`Round ${r.n}${j ? ` — kept ${j.pick}${score != null ? ` at ${fmt(score, unit)}` : ""}` : " — not judged"}`);
+    if (j?.why) out.push(`Why: ${j.why}`);
+    for (const l of Object.keys(j?.byModel ?? {})) { const xs = Object.values(j.byModel[l]) as number[]; if (xs.length > 1 && Math.max(...xs) - Math.min(...xs) >= 3) out.push(`Panel split on ${l}: ${Object.entries(j.byModel[l]).map(([m, x]) => `${m} ${x}`).join(" · ")}`); }
+    if (r === last) out.push(`Next round: loop({ from: "${state.id}" })`);
+    out.push("", roundTable(state, r), "");
+  }
+  const best = state.best;
+  if (best.commit && best.commit !== state.baseCommit) {
+    let stat = ""; let files: { changed: string[]; added: string[]; removed: string[] } = { changed: [], added: [], removed: [] };
+    try { stat = git(cwd, "diff", "--stat", `${state.baseCommit}..${best.commit}`); files = winnerFiles(cwd, state.baseCommit, best.commit); } catch {}
+    out.push(`Best so far: ${best.label} (${best.commit.slice(0, 7)}, branch ${best.branch ?? "?"})${best.score != null ? ` at ${fmt(best.score, state.metric?.unit)}` : ""}`);
+    if (stat) out.push(stat);
+    out.push(...applyHint(best, files), "");
+  } else out.push("No attempt beat the baseline yet.", "");
+  if ((state.rounds?.length ?? 0) > 1 || state.shots?.length) out.push("Climb:", climbText(state), "");
+  if (state.models && !state.models.spread && !STYLES.some((st) => state.models[st])) out.push("All roles ran on your current model — /loop models gives each attempt its own (or set enabledModels in Pi's settings to spread them).", "");
+  if (state.openNext) out.push(`/loop open ${state.openNext} — resume that attempt's session and ask it what it did.`, "");
+  return out.join("\n").trim();
+}
+
+export function specText(p: SpecView): string {
+  const dirs = p.directions ?? {};
+  const anyDirs = Object.values(dirs).some(Boolean);
+  const lines = [
+    `goal     ${p.goal ?? ""}`,
+    `rules    ${p.rules?.length ? "\n" + p.rules.map((r) => `  - ${r}`).join("\n") : "none"}`,
+    `angles   ${anyDirs ? "\n" + STYLES.filter((st) => dirs[st]).map((st) => `  ${st.padEnd(5)} ${dirs[st]}`).join("\n") : "the standard safe / bold / wild"}`,
+    `shots    ${p.routes?.length ? p.routes.join(", ") : p.shots?.length ? `${p.shots.join(", ")}  (build: ${p.build ?? "none"})` : "none — judged on the diffs"}`,
+    `project  check ${p.check ?? "none"} · bench ${p.bench ? `${p.bench} (${p.metric?.unit ?? p.metric?.key ?? "number"}, ${p.metric?.better ?? "lower"} is better)` : "none"} · protect ${p.protect?.length ? p.protect.join(", ") : "none"}${p.routes?.length ? ` · serve ${p.serve ?? "MISSING — run /loop init"}` : ""}`,
+  ];
+  return lines.join("\n");
+}
+
+export const SETUP_KEYS = ["serve", "check", "bench", "metric", "protect"];
+export function projectSetup(cwd: string): Record<string, any> { const c = loopSettings(null, cwd); return Object.fromEntries(SETUP_KEYS.filter((k) => c[k] != null && (!Array.isArray(c[k]) || c[k].length)).map((k) => [k, c[k]])); }
+export function setupText(p: Record<string, any>): string {
+  return [`serve    ${p.serve ?? "none (no web app to screenshot)"}`, `check    ${p.check ?? "none"}`, `bench    ${p.bench ? `${p.bench}  (${p.metric?.unit ?? p.metric?.key ?? "number"}, ${p.metric?.better ?? "lower"} is better)` : "none"}`, `protect  ${p.protect?.length ? p.protect.join(", ") : "none"}`].join("\n");
+}
+const INIT_STEP = `Set the project up for loops first (one time): from package.json and the config files actually present — read, don't run, no bash — work out serve (the command that starts the app on $PORT, e.g. \`npm run dev -- --port $PORT\`; none if this isn't a web app), check (tests / typecheck as this repo runs them; none if none), bench (a script that prints the number to climb, with its unit and whether lower or higher is better; usually none) and protect (the check / bench / config files attempts could game), then call \`loop_init\` with them — it shows them to me and saves .pi/loops.json.`;
+export function projectText(cwd: string): string {
+  const p = projectSetup(cwd);
+  if (!p.serve && !p.check) return `This repo is not set up for loops yet. ${INIT_STEP} Then the brief below.`;
+  return `Project setup (.pi/loops.json, written once by /loop init; say if it is wrong):\n${setupText(p)}`;
+}
+/** The dialog version: a select's title is not scrollable, so keep it to a few short lines; the full brief goes to the tool's progress output. */
+export function specBrief(p: SpecView, width: number = 96): string {
+  const cut = (t: unknown) => { const s = String(t ?? "").replace(/\s+/g, " ").trim(); return s.length > width ? s.slice(0, width - 1) + "…" : s; };
+  const dirs = p.directions ?? {};
+  const anyDirs = Object.values(dirs).some(Boolean);
+  return [
+    `goal     ${cut(p.goal)}`,
+    `rules    ${p.rules?.length ? `${p.rules.length}: ${cut(p.rules.join(" · "))}` : "none"}`,
+    `angles   ${anyDirs ? cut(STYLES.filter((st) => dirs[st]).map((st) => `${st}: ${dirs[st]}`).join(" · ")) : "standard safe / bold / wild"}`,
+    `shots    ${p.routes?.length ? cut(p.routes.join(", ")) : p.shots?.length ? cut(p.shots.join(", ")) : "none — judged on the diffs"}`,
+    `project  ${cut(`check ${p.check ?? "none"} · bench ${p.bench ?? "none"} · protect ${p.protect?.length ? p.protect.join(", ") : "none"}${p.routes?.length ? ` · serve ${p.serve ?? "MISSING — run /loop init"}` : ""}`)}`,
+  ].join("\n");
+}
+
+export function loopPrompt(ask: string, cwd: string = process.cwd()): string {
+  const md = fs.readFileSync(path.join(ROOT, "prompts", "loop.md"), "utf8");
+  const body = md.replace(/^---[\s\S]*?---\n/, "");
+  return body.replace("$PROJECT", () => projectText(cwd)).replace("$@", () => ask.trim());
+}
+export function initPrompt() { return fs.readFileSync(path.join(ROOT, "prompts", "init.md"), "utf8").replace(/^---[\s\S]*?---\n/, "").replace("$INIT", () => INIT_STEP); }
+
+export const modelsText = (models: Record<string, any>) => Object.entries(models).filter(([k]) => k !== "pool").map(([k, v]) => `${k} ${Array.isArray(v) ? v.map(shortModel).join("+") : shortModel(v)}`).join(" · ") || "everything on the current model";
+
+/** What `/loop models` reports: the models it saved and where, or why it could not save them. */
+export type PickResult = { models: Record<string, any>; file: string } | { error: string };
+
+/** Walk through one model per role and save them to <repo>/.pi/loops.json; null when cancelled or there is nothing to pick from, { error } when the file can't be written. */
+export async function pickModels(ctx: PickCtx, { reason }: { reason?: string } = {}): Promise<PickResult | null> {
+  const available = (ctx.modelRegistry?.getAvailable?.() ?? []).map(modelSpec);
+  if (!available.length) { ctx.ui.notify("no models available — /login first", "error"); return null; }
+  const current = ctx.model ? modelSpec(ctx.model) : null;
+  const TYPE = "type a model…";
+  const options = [...(current ? [`${current} (current)`] : []), TYPE, ...available.filter((m) => m !== current)];
+  const pick = async (title: string) => {
+    for (;;) {
+      const r = await ctx.ui.select(title, options);
+      if (r == null) return null;
+      if (r !== TYPE) return r.replace(/ \(current\)$/, "");
+      const typed = (await ctx.ui.input?.(title, "part of a model id, e.g. haiku or gpt-5.6"))?.trim().toLowerCase();
+      if (!typed) continue;
+      const hits = available.filter((m) => m.toLowerCase().includes(typed));
+      if (hits.length === 1) return hits[0];
+      ctx.ui.notify(hits.length ? `${hits.length} models match "${typed}": ${hits.map(shortModel).slice(0, 8).join(", ")}${hits.length > 8 ? "…" : ""} — be more specific` : `no model matches "${typed}"`, "warning");
+    }
+  };
+  const models: Record<string, any> = {};
+  const hint: Record<string, string> = { safe: "smallest safe change", bold: "structural redesign", wild: "unconventional idea" };
+  for (const role of STYLES) { const r = await pick(`${reason ? reason + ": " : ""}model for the ${role} attempt (${hint[role]}) — each attempt its own`); if (r == null) return null; models[role] = r; }
+  const judge = await pick("Model for the judge (measures, vetoes — your strongest)"); if (judge == null) return null;
+  models.judge = judge;
+  models.council = [...new Set(STYLES.map((r) => models[r]))];
+  if (models.council.length < 2) models.council.push(judge);
+  const file = configFiles(ctx.cwd).project;
+  let saved;
+  try { saved = saveConfig(ctx.cwd, { models }); } catch (e) { const error = `${path.relative(ctx.cwd, file)}: ${errText(e).slice(0, 80)}; fix it and run /loop models again`; ctx.ui.notify(error, "error"); return { error }; }
+  return { models: saved.models, file: path.relative(ctx.cwd, file) };
+}
+
+/** The /loops card: what this repo's loops run with, and the last run. */
+export function configCard(settings: LoopSettings, cwd: string, lastState?: State | null, effective: ModelPlan = resolveModels({ settings })): string {
+  const m = settings.models ?? {};
+  const roles = STYLES.map((r) => `${r} ${shortModel(effective[r])}`).join(" · ");
+  const council = (effective.council ?? []).map(shortModel).join("+");
+  const lines = [
+    `models   ${roles} · judge ${shortModel(effective.judge)} · council ${council}${m.pool?.length ? ` · pool ${m.pool.join(", ")}` : ""}`,
+    `rounds   ${settings.rounds ?? 1} per /loop`,
+    `budget   ${settings.tokenBudget ? `${Math.round(settings.tokenBudget / 1000)}k tokens per attempt` : "no token cap (the timeout limits attempts)"}`,
+    `timeout  ${settings.timeoutMin} min per attempt`,
+    `minGain  ${settings.minGain} (bench mode)`,
+  ];
+  if (lastState) {
+    const r = lastState.rounds?.at(-1);
+    lines.push(`last run ${lastState.id} — ${lastState.status}${r?.judge ? `, r${r.n} kept ${r.judge.pick}` : ""}${lastState.best?.commit && lastState.best.commit !== lastState.baseCommit ? `, best ${lastState.best.label} (${lastState.best.commit.slice(0, 7)})` : ""}`);
+  }
+  lines.push(`config   ${path.relative(cwd, configFiles(cwd).project)} (this repo) · ${configFiles(cwd).user} (your defaults)`);
+  return lines.join("\n");
+}
+
+export async function openSession(ctx: Ctx, label: string, runId?: string | null): Promise<boolean> {
+  let state: State; try { state = loadState(ctx.cwd, runId || "last"); } catch (e) { ctx.ui.notify(errText(e), "error"); return false; }
+  const rounds = state.rounds ?? [];
+  const file = label === "judge" ? [...rounds].reverse().find((r) => r.judgeSession)?.judgeSession : rounds.flatMap((r) => r.attempts).find((a) => a.label.toLowerCase() === label.toLowerCase())?.session;
+  if (!file || !fs.existsSync(file)) { ctx.ui.notify(`no session file for ${label} in ${state.id}`, "error"); return false; }
+  await ctx.switchSession?.(file);
+  return true;
+}
+
+export function runsText(cwd: string): string {
+  const dir = path.join(cwd, STATE_DIR);
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort() : [];
+  if (!files.length) return `no runs in ${STATE_DIR}/`;
+  return files.map((f) => { try { const st = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")); return `${st.id} — ${st.status} — ${st.goal.slice(0, 60)}\n${climbText(st).split("\n").map((l) => "  " + l).join("\n")}`; } catch { return f; } }).join("\n");
+}
+
+export const SUBCOMMANDS = ["init", "models", "rounds", "budget", "timeout", "open", "runs"];
+/** Bare, or a subcommand word with at most its argument(s) — anything longer is a goal ("rounds of golf should load faster"); bad values error in loopsCommand instead of starting a round. */
+export function isSubcommand(args?: string | null): boolean {
+  const w = (args ?? "").trim().split(/\s+/).filter(Boolean);
+  if (!w.length) return true;
+  const sub = w[0].toLowerCase();
+  if (!SUBCOMMANDS.includes(sub)) return false;
+  if (sub === "models" || sub === "runs" || sub === "init") return w.length === 1;
+  if (sub === "open") return w.length <= 3;
+  return w.length <= 2;
+}
+const LOOPS_USAGE = "/loop — card and picker · /loop <goal> — run a round · /loop init — project setup (serve, check, bench, protect) · /loop models · /loop rounds <n> · /loop budget <tokens, e.g. 800k|1.5m> · /loop timeout <min> · /loop open <R1-safe|judge> [run] · /loop runs";
+export async function loopsCommand(args: string, ctx: Ctx, pi: Pi): Promise<void> {
+  const [first, ...rest] = (args ?? "").trim().split(/\s+/).filter(Boolean);
+  const sub = first?.toLowerCase();
+  const settings = loopSettings(pi, ctx.cwd);
+  const set = (patch: Record<string, any>, what: string) => { try { saveConfig(ctx.cwd, patch); ctx.ui.notify(`${path.relative(ctx.cwd, configFiles(ctx.cwd).project)}: ${what}`, "info"); } catch (e) { ctx.ui.notify(errText(e), "error"); } };
+  switch (sub) {
+    case undefined: {
+      let last: State | null = null; try { last = loadState(ctx.cwd, sessionRuns(ctx).find((id) => fs.existsSync(stateFile(ctx.cwd, id))) ?? "last"); } catch {}
+      ctx.ui.notify(configCard(settings, ctx.cwd, last, modelsOf(ctx, settings, pi)), "info");
+      const choice = await ctx.ui.select("Change (esc to leave)", ["models", "rounds", "budget", "timeout"]);
+      if (!choice) return;
+      if (choice === "models") return loopsCommand("models", ctx, pi);
+      const v = await ctx.ui.input?.(`${choice} — currently ${choice === "rounds" ? settings.rounds ?? 1 : choice === "budget" ? (settings.tokenBudget ? `${Math.round(settings.tokenBudget / 1000)}k` : "none") : settings.timeoutMin}`, choice === "budget" ? "e.g. 800k or 1.5m" : "a number");
+      if (v == null || !v.trim()) return;
+      return loopsCommand(`${choice} ${v.trim()}`, ctx, pi);
+    }
+    case "models": { const r = await pickModels(ctx); if (r && "models" in r) ctx.ui.notify(`${r.file}: ${modelsText(r.models)}`, "info"); return; }
+    case "rounds": { const n = Number(rest[0]); if (!Number.isInteger(n) || n < 1) { ctx.ui.notify("/loop rounds <n ≥ 1>", "error"); return; } return set({ rounds: n }, `rounds ${n} per /loop`); }
+    case "budget": { const n = parseBudget(rest[0]); if (!n) { ctx.ui.notify("/loop budget <tokens: 800k, 1.5m, 400000>", "error"); return; } return set({ tokenBudget: n }, `budget ${Math.round(n / 1000)}k tokens per attempt`); }
+    case "timeout": { const n = Number(rest[0]); if (!(Number.isFinite(n) && n > 0)) { ctx.ui.notify("/loop timeout <minutes>", "error"); return; } return set({ timeoutMin: n }, `timeout ${n} min per attempt`); }
+    case "open": { if (!rest[0]) { ctx.ui.notify("/loop open <R1-safe|judge> [run id]", "info"); return; } await openSession(ctx, rest[0], rest[1]); return; }
+    case "init": await pi.sendUserMessage?.(initPrompt()); return;
+    case "runs": ctx.ui.notify(runsText(ctx.cwd), "info"); return;
+    default: ctx.ui.notify(LOOPS_USAGE, "info");
+  }
+}
+
+export default function loopsExtension(pi: Pi): void {
+  pi.registerCommand?.("loop", {
+    description: "Run a hill-climbing round: /loop <goal>[; check is <cmd>; bench is <cmd> and prints <unit>]. Bare /loop shows this repo's loops card; /loop models|rounds <n>|budget <tokens>|timeout <min>|open <attempt>|runs configure and inspect",
+    handler: async (args, ctx) => {
+      if (isSubcommand(args)) return loopsCommand(args, ctx, pi);
+      await pi.sendUserMessage?.(loopPrompt(args, ctx.cwd));
+    },
+  });
+  pi.on?.("session_shutdown", async () => { for (const r of RUNS.values()) r.ctrl.abort(); await stopAll(); });
+  async function run(params: LoopParamsIn, signal: AbortSignal | undefined, onUpdate: ((update: any) => void) | undefined, ctx: Ctx, live: any) {
+    const cwd = ctx.cwd;
+    let settings = loopSettings(pi, cwd);
+    const chosen = Object.keys(settings.models).some((k) => k !== "pool");
+    if (!params.from && !chosen && ctx.hasUI && (ctx.modelRegistry?.getAvailable?.() ?? []).length > 1) {
+      const r = await pickModels(ctx, { reason: "First loop here" });
+      if (r && "error" in r) throw new Error(r.error);
+      if (r && "models" in r) settings = { ...settings, models: { ...settings.models, ...r.models } };
+    }
+    const models = modelsOf(ctx, settings, pi);
+    let state: State;
+    if (params.from) {
+      const mine = params.from === "last" ? sessionRuns(ctx).find((id) => fs.existsSync(stateFile(cwd, id))) : null;
+      state = loadState(cwd, mine ?? params.from);
+      for (const k of ["check", "bench", "metric", "protect", "build", "shots"] as const) if (params[k] != null) state[k] = params[k];
+      for (const r of params.rules ?? []) if (!state.rules.includes(r)) { state.rules.push(r); if (state.rubric) addRule(state.rubric, r); }
+    } else {
+      if (!params.goal) throw new Error("loop needs a goal (or `from` to continue a run)");
+      let baseCommit: string; try { baseCommit = git(cwd, "rev-parse", "HEAD"); } catch { throw new Error("loop needs a git repo with at least one commit"); }
+      const edited = git(cwd, "status", "--porcelain", "--untracked-files=no").split("\n").some((l) => l.trim() && !/\s\.gitignore$/.test(l));
+      const stashed = edited ? git(cwd, "stash", "create", "loops baseline") : "";
+      if (stashed) baseCommit = stashed;
+      const id = `loop-${new Date().toISOString().replace(/[-:]/g, "").slice(0, 15)}-${randomBytes(2).toString("hex")}`;
+      const kind = params.bench ? "bench" : "visual";
+      let build = params.build, shots: string[] = params.shots ?? [];
+      if (!build && params.routes?.length) {
+        if (!settings.serve) throw new Error("routes need `serve` in .pi/loops.json — run /loop init first");
+        const tool = path.join(ROOT, "lib", "shot.ts"), q = (v: unknown) => `'${String(v).replace(/'/g, `'\\''`)}'`;
+        const slug = (r: string) => r.replace(/^\/+|\/+$/g, "").replace(/[^a-z0-9]+/gi, "-").toLowerCase() || "index";
+        shots = params.routes.map((r) => `.loops-shots/${slug(r)}.png`);
+        build = params.routes.map((r, i) => `node ${q(tool)} --serve ${q(settings.serve)} --url ${q(r)} --out ${q(shots[i])}`).join(" && ");
+      }
+      state = { v: 2, id, goal: params.goal, kind, editedBaseline: !!stashed, check: params.check ?? settings.check, bench: params.bench, metric: { key: "ms", unit: kind === "bench" ? "ms" : "", better: "lower", ...(params.bench && params.bench === settings.bench ? settings.metric ?? {} : {}), ...(params.metric ?? {}) }, protect: params.protect ?? settings.protect ?? [], build, shots, rules: params.rules ?? [], directions: params.directions ?? {}, baseCommit, best: { label: "base", commit: baseCommit, session: null, score: null, reason: null }, winner: null, status: "running", rounds: [], rubric: null, parentSession: ctx.sessionManager?.getSessionFile?.() ?? null };
+    }
+    state.status = "running";
+    saveState(cwd, state);
+    const link = () => { try { pi.appendEntry?.("loops-run", { id: state.id, status: state.status, goal: state.goal, kind: state.kind, best: state.best?.label ?? null, rounds: state.rounds?.length ?? 0 }); } catch {} };
+    link();
+    if (state.shots?.length) { try { excludeShots(cwd, state.shots); } catch {} }
+    const runDir = path.join(cwd, STATE_DIR, state.id);
+    const details: Details = { run: state.id, kind: state.kind, round: null, judge: null, attempts: [], phase: "starting" };
+    if (live) { live.id = state.id; live.state = state; live.details = details; live.cwd = cwd; live.started?.(); }
+    const push = (phase?: string) => { details.phase = phase ?? details.phase; if (live) { try { ctx.ui.setStatus?.("loops", `${state.id} r${details.round ?? "?"} · ${details.phase}`); } catch {} } onUpdate?.({ content: [{ type: "text", text: `${state.id} r${details.round ?? "?"} · ${details.phase}\n${details.attempts.map((a) => `  ${a.style.padEnd(5)} ${a.status.padEnd(8)} ${a.tool ? `[${a.tool}] ` : ""}${a.tools} tools, ${a.tokens} tok${a.text ? ` — ${a.text.split("\n").pop()?.slice(0, 80) ?? ""}` : ""}`).join("\n")}` }], details: structuredClone(details) }); };
+    const askModel = (role: string, i: number = 0) => (content: any) => oneShot({ role, model: role === "council" ? (models.council ?? [])[i % (models.council?.length || 1)] : models[role], content, cwd, ctx, settings, signal });
+    const askAs = (role: string, model?: string | null) => (content: any) => oneShot({ role, model, content, cwd, ctx, settings, signal });
+    // the judge panel: every council model (the attempts' models) scores every candidate, labels blind; the judge model keeps vetoes and the head-to-head
+    const panel = settings.council !== false && settings.judgePanel !== false && (models.council?.length ?? 0) > 1 ? (models.council ?? []).map((m) => ({ name: shortModel(m), ask: askAs("judge", m) })) : undefined;
+    state.models = { ...Object.fromEntries(STYLES.map((st) => [st, models[st]])), judge: models.judge, council: models.council, spread: models.spread };
+    const needsYou = async (title: string, options: string[], fallback: string): Promise<string> => {
+      if (ctx.hasUI && !live) { const r = await ctx.ui.select(title, options); return r ?? fallback; }
+      return fallback;
+    };
+
+    if (!state.rubric && settings.council !== false && state.kind === "bench") {
+      push("council writes the rubric");
+      try { state.rubric = newRubric(await writeRubric({ goal: state.goal, kind: state.kind, rules: state.rules, subject: "the code", members: models.council?.length ?? 0, ask: (role, prompt, i) => askModel(role, i)(prompt) }), "council"); }
+      catch (e) { state.rubric = fromRules(state.rules, errText(e).slice(0, 200)); }
+      saveState(cwd, state);
+    }
+
+    const done: Round[] = [];
+    const want = Math.max(1, params.rounds ?? settings.rounds ?? 1);
+    for (let k = 0; k < want; k++) {
+      if (signal?.aborted) break;
+      let round = state.rounds[state.rounds.length - 1];
+      if (!round || round.judge) { round = { n: state.rounds.length + 1, from: state.best.commit, status: "running", attempts: [], judge: null, startedAt: Date.now() }; state.rounds.push(round); saveState(cwd, state); }
+      const n = round.n;
+      details.round = n;
+      const styles = STYLES.slice(0, Math.min(STYLES.length, settings.attempts));
+      const keep = round.attempts.filter(finished);
+      details.attempts = styles.map((s) => keep.find((a) => a.style === s) ? { style: s, status: "done", tool: null, tools: 0, tokens: 0, text: "kept from before" } : { style: s, status: "queued", tool: null, tools: 0, tokens: 0, text: "" });
+      push("attempts");
+      const results = await Promise.all(styles.map(async (style) => {
+        const kept = keep.find((a) => a.style === style);
+        if (kept) return kept;
+        const dir = path.join(runDir, `r${n}-${style}`);
+        const branch = `loops/${state.id}/r${n}-${style}`;
+        fs.mkdirSync(runDir, { recursive: true });
+        try { git(cwd, "worktree", "remove", "-f", dir); } catch {}
+        git(cwd, "worktree", "add", "-q", "-f", "-B", branch, dir, round.from ?? state.baseCommit);
+        const slot = details.attempts.find((a) => a.style === style)!;
+        const r = await runAttempt({ state, style, n, dir, ctx, settings, model: models[style], signal, live, onProgress: (p) => { Object.assign(slot, p); push(); } });
+        Object.assign(slot, { status: r.status, tool: null, text: r.summary || r.error || "" }); push();
+        return { ...r, branch, dir: path.relative(cwd, dir) };
+      }));
+      round.attempts = results;
+      if (signal?.aborted) { round.status = "aborted"; saveState(cwd, state); done.push(round); break; }
+      saveState(cwd, state);
+
+      push("judging");
+      const valid = results.filter(finished);
+      let judge: any;
+      const curRel = n > 1 && state.best.dir && fs.existsSync(path.join(cwd, state.best.dir)) ? state.best.dir : null;
+      let curDir = curRel ? path.join(cwd, curRel) : cwd, curFresh = false;
+      if (n > 1 && !curRel) { curDir = path.join(runDir, "best"); curFresh = true; try { git(cwd, "worktree", "remove", "-f", curDir); } catch {} git(cwd, "worktree", "add", "-q", "-f", "--detach", curDir, state.best.commit); }
+      for (const a of valid) { const adir = path.join(cwd, a.dir); if (restoreProtected({ cwd: adir, protect: state.protect, baseCommit: state.baseCommit })) { a.commit = git(adir, "rev-parse", "HEAD"); a.restored = true; } }
+      const shotFiles = (dir: string): ShotFiles => {
+        const files = (state.shots ?? []).map((f) => path.join(dir, f));
+        const missing = files.filter((f) => !fs.existsSync(f));
+        return missing.length ? { error: `no screenshot: ${missing.map((f) => path.basename(f)).join(", ")}`, have: files.filter((f) => fs.existsSync(f)) } : { files, have: files };
+      };
+      const ensureShots = async (dir: string, force: boolean = false): Promise<ShotFiles> => { if (state.shots?.length && state.build && (force || shotFiles(dir).error)) await sh(dir, state.build); return shotFiles(dir); };
+      if (state.kind === "bench") {
+        const cands: Candidate[] = [{ label: "CURRENT", dir: curDir, commit: state.best.commit, fresh: curFresh }, ...valid.map((a) => ({ label: a.label, dir: path.join(cwd, a.dir), commit: a.commit }))];
+        const num = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
+        let cur: { value: number | null; note: any } = { value: null, note: null }, failure: string | null = null;
+        try {
+          const j = await judgeRound({ state, n, cands, cwd, ctx, settings, model: models.judge, signal, onProgress: (p) => { details.judge = { ...p }; push(`judging${p.tool ? ` [${p.tool}]` : ""} · ${p.tools} tools, ${p.tokens} tok`); } });
+          round.judgeSession = j.session; round.judgeTokens = j.tokens; round.judgeCost = j.cost;
+          cur = { value: num(j.out.CURRENT?.value), note: j.out.CURRENT?.note };
+          for (const a of valid) {
+            const r = j.out[a.label] ?? {};
+            a.bench = r.check === false ? { passed: false, tests: String(r.note ?? "check failed") } : { passed: true, value: num(r.value), ...(num(r.value) == null ? { error: String(r.note || "the judge got no benchmark number") } : {}) };
+            a.review = { ok: r.ok !== false, note: String(r.note ?? "") };
+            const slot = details.attempts.find((x) => x.style === a.style); if (slot) { slot.text = a.bench.error ?? (a.bench.passed ? `${fmt(a.bench.value, state.metric.unit)}${a.review.ok ? "" : " vetoed"}` : "check fails"); push(); }
+          }
+        } catch (e) { failure = errText(e).slice(0, 200); for (const a of valid) a.bench = { passed: true, error: `not judged: ${failure}` }; }
+        judge = pickWinner({ cur: { value: cur.value }, attempts: valid, metric: state.metric, minGain: settings.minGain });
+        if (failure) judge.why = `The judge failed (${failure}); kept the current best.`;
+        if (cur.value == null) judge.reasons.CURRENT = failure ?? cur.note ?? "baseline could not be measured";
+      } else {
+        const shots = shotFiles;
+        const reasons: Record<string, string> = {};
+        const curShots = await ensureShots(curDir, curFresh);
+        const codeOnly = !state.shots?.length;
+        const diffOf = (dir: string, commit: string) => diffText(dir, state.best.commit, commit);
+        const candidates: { label: string; shots?: string[]; text?: string }[] = curShots.files ? [{ label: "CURRENT", shots: curShots.files, ...(codeOnly ? { text: "CURRENT is the code as it stands; every other candidate below is a diff against it. Judge whether each diff makes the code better for the goal (correctness, clarity, idiom, no needless churn or deleted safety)." } : {}) }] : [];
+        if (!curShots.files) reasons.CURRENT = `${curShots.error} in ${path.relative(cwd, curDir) || "."}; attempts were scored on the goal alone`;
+        else if (n === 1 && state.editedBaseline) reasons.CURRENT = "your checkout, uncommitted edits included; attempts started from the same state";
+        for (const a of valid) {
+          const adir = path.join(cwd, a.dir);
+          if (a.restored && state.build) { const b = await sh(adir, state.build); if (b.code !== 0) { a.bench = { passed: false, tests: "rebuild after restoring protected files failed: " + b.out.slice(-200) }; reasons[a.label] = a.bench.tests.slice(0, 120); continue; } }
+          if (state.check) { const c = await sh(adir, state.check); if (c.code !== 0) { a.bench = { passed: false, tests: c.out.slice(-200) }; reasons[a.label] = "check fails"; continue; } }
+          a.bench = { passed: true };
+          let s = shots(adir);
+          if (s.error && state.build) { const b = await sh(adir, state.build); if (b.code !== 0) { a.bench.error = `build failed: ${b.out.trim().split("\n").pop()?.slice(0, 160) ?? ""}`; reasons[a.label] = a.bench.error.slice(0, 120); continue; } s = shots(adir); }
+          if (s.error) { a.bench.error = s.error; reasons[a.label] = s.error.slice(0, 120); continue; }
+          candidates.push({ label: a.label, shots: s.files, ...(codeOnly ? { text: diffOf(adir, a.commit) } : {}) });
+        }
+        const img = (f: string) => ({ type: "image", data: fs.readFileSync(f).toString("base64"), mimeType: f.endsWith(".jpg") || f.endsWith(".jpeg") ? "image/jpeg" : "image/png" });
+        judge = candidates.some((c) => c.label !== "CURRENT") ? await panelJudge({ ask: askModel("judge"), panel, img, subject: codeOnly ? "the code" : "the page", goal: state.goal, rules: state.rules, rubric: state.rubric ?? undefined, candidates, samples: settings.judgeSamples, pairs: settings.judgePairs }) : { scores: {}, reasons: {}, pick: "CURRENT", why: valid.length ? `No attempt could be judged: ${valid.map((a) => `${a.label} — ${reasons[a.label] ?? a.bench?.error ?? "?"}`).join("; ") || "none finished"}.` : "No attempt finished." };
+        Object.assign(judge.reasons, reasons);
+      }
+      for (const a of results) if (a.status !== "done") judge.reasons[a.label] ??= a.error ? `${a.status}: ${a.error}` : a.status;
+      for (const a of results) if (a.cut) judge.reasons[a.label] = `${judge.reasons[a.label] ? judge.reasons[a.label] + " — " : ""}cut off by ${a.cut === "budget" ? "the token budget" : a.cut === "timeout" ? "the time limit" : a.cut}`;
+
+      if (state.shots?.length) {
+        push("sheet");
+        const unit = state.metric?.unit ?? "";
+        const tag = (label: string, a?: Attempt) => judge.reasons?.[label] && (a?.bench?.passed === false || a?.bench?.error) ? `${label} — ${String(judge.reasons[label]).slice(0, 28)}` : `${label}${judge.scores?.[label] != null ? ` ${fmt(judge.scores[label], unit)}` : ""}${judge.pick === label ? " ✓" : ""}`;
+        const tiles = [{ label: tag("CURRENT"), files: (await ensureShots(curDir, curFresh)).have }];
+        for (const a of valid) tiles.push({ label: tag(a.label, a), files: (await ensureShots(path.join(cwd, a.dir))).have });
+        try { const f = sheet({ tiles, out: path.join(runDir, `r${n}.png`) }); if (f) round.sheet = path.relative(cwd, f); } catch {}
+      }
+
+      const takeable = valid.filter((a) => a.bench?.passed && !a.bench.error);
+      if (live?.pick) {
+        const want = String(live.pick).toLowerCase();
+        const a = takeable.find((x) => x.label.toLowerCase() === want || x.style === want);
+        if (a) { judge.pick = a.label; judge.why = `You picked ${a.label}. ${judge.why}`; judge.human = true; }
+        else if (want === "current") { judge.pick = "CURRENT"; judge.why = `You kept CURRENT. ${judge.why}`; judge.human = true; }
+        else judge.why = `${judge.why} (your pick ${live.pick} was not a passing attempt)`;
+        live.pick = null;
+      }
+      if (ctx.hasUI && !live && takeable.length) {
+        for (;;) {
+          const others = takeable.filter((a) => a.label !== judge.pick);
+          const opts = [`Keep ${judge.pick}${judge.pick === "CURRENT" ? " (nothing beat it)" : " (judge's pick)"}`, ...others.map((a) => `Take ${a.label} instead`), ...valid.map((a) => `Show ${a.label}'s diff`), ...valid.filter((a) => a.session).map((a) => `Open ${a.label}'s session after the run`)];
+          const choice = await ctx.ui.select(`Round ${n}: ${judge.why}${round.sheet ? `  Sheet: ${round.sheet}` : ""}`, opts);
+          if (choice == null || choice.startsWith("Keep")) break;
+          const a = valid.find((x) => choice.includes(x.label));
+          if (!a) break;
+          if (choice.startsWith("Take")) { judge.pick = a.label; judge.why = `You picked ${a.label}. ${judge.why}`; judge.human = true; break; }
+          if (choice.startsWith("Show")) { let d: string; try { d = `${git(cwd, "diff", "--stat", `${round.from}..${a.commit}`)}\n\n${git(cwd, "diff", `${round.from}..${a.commit}`)}`.slice(0, 60000); } catch (e) { d = errText(e); } await ctx.ui.editor?.(`${a.label} vs CURRENT (read-only; close to return)`, d); }
+          if (choice.startsWith("Open")) { state.openNext = a.label; ctx.ui.notify(`After the run: /loop open ${a.label} resumes ${a.label}'s session (/loop open judge for the judge).`, "info"); }
+        }
+      } else if (judge.pick === "CURRENT" && takeable.length) {
+        const choice = await needsYou(`Round ${n}: ${judge.why} Keep the current best?`, ["Keep the current best", ...takeable.map((a) => `Take ${a.label} anyway`)], "Keep the current best");
+        const forced = takeable.find((a) => choice === `Take ${a.label} anyway`);
+        if (forced) { judge.pick = forced.label; judge.why = `You picked ${forced.label}. ${judge.why}`; judge.human = true; }
+      }
+      round.judge = judge;
+      round.status = "done";
+      round.endedAt = Date.now();
+      if (judge.pick !== "CURRENT") {
+        const w = results.filter(finished).find((a) => a.label === judge.pick);
+        if (w) {
+          state.best = { label: w.label, commit: w.commit, session: w.session, branch: w.branch, dir: w.dir, score: judge.scores[w.label] ?? null, reason: judge.reasons[w.label] ?? null, round: n };
+          let files: any = null; try { files = winnerFiles(cwd, state.baseCommit, w.commit); } catch {}
+          state.winner = { style: w.style, label: w.label, round: n, commit: w.commit, branch: w.branch, session: w.session, bench: state.kind === "bench" ? { value: judge.scores[w.label] ?? null, unit: state.metric?.unit ?? "" } : null, score: judge.scores[w.label] ?? null, reason: judge.reasons[w.label] ?? null, files };
+        }
+      }
+      saveState(cwd, state);
+      done.push(round);
+      push(`round ${n}: kept ${judge.pick}`);
+    }
+    const aborted = !!signal?.aborted;
+    state.status = aborted ? "aborted" : "done";
+    saveState(cwd, state);
+    link();
+    const text = (aborted ? `Aborted during round ${details.round}; attempts' worktrees are kept under ${path.relative(cwd, runDir)}/. Resume with loop({ from: "${state.id}" }).\n\n` : "") + resultText(state, done, cwd);
+    const lastSheet = [...done].reverse().find((r) => r.sheet)?.sheet;
+    const content: any[] = [{ type: "text", text }];
+    if (lastSheet) { try { content.push({ type: "image", data: fs.readFileSync(path.join(cwd, lastSheet)).toString("base64"), mimeType: "image/png" }); } catch {} }
+    return { content, structuredContent: structuredResult(state, state.rounds), details: { ...structuredClone(details), phase: aborted ? "aborted" : "done", status: state.status, best: state.best, winner: state.winner, rounds: done.map((r) => ({ n: r.n, pick: r.judge?.pick ?? null, why: r.judge?.why ?? null })) } };
+  }
+
+  pi.registerTool?.({
+    name: "loop",
+    label: "loop",
+    outputSchema: LoopResult,
+    description: "Run hill-climbing round(s) on the current git repo: three forked attempt sessions (safe/bold/wild agents) in their own worktrees, a judge keeps the best. Bench mode when `bench` is set (each attempt sets up and measures itself; a judge agent re-measures every candidate, reads the diffs and vetoes rule breaks); visual mode otherwise (`build` writes `shots`, a judge panel scores them). `from` continues a run from its last judged round.",
+    parameters: LoopParams,
+    async execute(_id, params, signal, onUpdate, ctx) {
+      if (ctx.hasUI && !params.from && params.confirm !== false) {
+        const st = loopSettings(pi, ctx.cwd);
+        const view = { ...params, check: params.check ?? st.check, protect: params.protect ?? st.protect, serve: st.serve, metric: params.metric ?? (params.bench && params.bench === st.bench ? st.metric : undefined) };
+        const spec = specText(view);
+        onUpdate?.({ content: [{ type: "text", text: `Brief\n${spec}` }], details: { run: null, kind: params.bench ? "bench" : "visual", round: null, attempts: [], phase: "brief" } });
+        const notRun = (phase: string, text: string) => ({ content: [{ type: "text", text }], details: { run: null, kind: params.bench ? "bench" : "visual", round: null, attempts: [], phase, spec: { ...params } }, structuredContent: structuredResult({ id: "", status: phase, kind: params.bench ? "bench" : "visual", goal: params.goal ?? "", baseCommit: "", metric: params.metric ?? {}, best: { commit: "" } }, []) });
+        const choice = await ctx.ui.select(`Brief for this loop (full text above)\n\n${specBrief(view)}\n`, ["Approve — run the round", "Change…", "Discuss"]);
+        if (choice?.startsWith("Change")) {
+          const note = (await ctx.ui.input?.("What should change?", "e.g. also protect src/lib/data.ts; check is npm test"))?.trim();
+          return notRun("change", note ? `Not run. Change requested: ${note}\nRevise the spec accordingly and call loop again.` : "Not run. Revise the spec with me in chat, then call loop again.");
+        }
+        if (!choice?.startsWith("Approve")) return notRun("discuss", "Not run. Discuss the spec with me in chat (what is unclear, what should be different), then call loop again when we agree.");
+      }
+      if (!ctx.hasUI || params.wait) return run(params, signal, onUpdate, ctx, null);
+      const live: any = { id: null, state: null, details: null, cwd: ctx.cwd, attempts: new Map(), pick: null, last: null, error: null, ctrl: new AbortController(), startedAt: Date.now() };
+      const started = new Promise((resolve) => { live.started = resolve; });
+      live.promise = run(params, live.ctrl.signal, (u) => { live.last = u; }, ctx, live).then(
+        (r) => { try { pi.sendUserMessage?.(r.content, { deliverAs: "followUp" }); } catch {} },
+        (e) => { live.error = e; if (live.id) { try { pi.sendUserMessage?.(`Loop ${live.id} failed: ${e.message}`, { deliverAs: "followUp" }); } catch {} } }
+      ).finally(() => { if (live.id) RUNS.delete(live.id); live.started?.(); try { ctx.ui.setStatus?.("loops", undefined); } catch {} });
+      await started;
+      if (!live.id) throw live.error ?? new Error("the loop did not start");
+      RUNS.set(live.id, live);
+      const text = `${live.id} started (${live.state.kind}; ${STYLES.slice(0, Math.min(STYLES.length, loopSettings(pi, ctx.cwd).attempts)).join(" / ")} attempts). The round card arrives here as a message when the judge is done. Until then: loop_status for progress, loop_talk to tell an attempt something, loop_rule to add a rule, loop_pick to decide the winner yourself.`;
+      return { content: [{ type: "text", text }], details: { run: live.id, kind: live.state.kind, round: null, attempts: [], phase: "started" }, structuredContent: structuredResult(live.state, []) };
+    },
+    renderCall(args, theme) {
+      const what = args.from ? `continue ${args.from}` : (args.goal ?? "").slice(0, 70);
+      return new Text(theme.fg("toolTitle", theme.bold("loop ")) + theme.fg("accent", what) + theme.fg("muted", ` ×${args.rounds ?? 1}${args.bench ? " bench" : args.goal ? " visual" : ""}`), 0, 0);
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      const d = result.details;
+      if (!d) return new Text(result.content?.[0]?.text ?? "", 0, 0);
+      const head = theme.fg(isPartial ? "warning" : d.phase === "aborted" ? "error" : "success", `${d.run} r${d.round ?? "?"} · ${d.phase}`);
+      const lines = ((d.attempts ?? []) as AttemptDetail[]).map((a) => `  ${theme.fg("accent", a.style.padEnd(5))} ${theme.fg(a.status === "done" ? "success" : a.status === "running" ? "warning" : "muted", a.status.padEnd(9))}${a.tool ? theme.fg("dim", `[${a.tool}] `) : ""}${theme.fg("muted", `${a.tools} tools · ${a.tokens} tok`)}${a.text ? theme.fg("dim", ` — ${a.text.split("\n").pop()?.slice(0, 70) ?? ""}`) : ""}`);
+      const body = !isPartial || d.phase === "brief" ? "\n" + (result.content?.[0]?.text ?? "") : "";
+      return new Text([head, ...lines].join("\n") + body, 0, 0);
+    },
+  });
+  const said = (t: string) => ({ content: [{ type: "text", text: t }] });
+  const idParam = Type.Optional(Type.String({ description: "Run id; default: the round started most recently" }));
+  pi.registerTool?.({ name: "loop_init", label: "loop_init", description: "Project setup for loops, written once to .pi/loops.json: serve (start the app on $PORT), check, bench + metric, protect. In the TUI it shows them and asks Save / Change / Discuss.", parameters: InitParams,
+    async execute(_id, p, _signal, _onUpdate, ctx) {
+      const fields = Object.fromEntries(SETUP_KEYS.filter((k) => p[k] != null && (!Array.isArray(p[k]) || p[k].length)).map((k) => [k, p[k]]));
+      if (ctx.hasUI) {
+        const choice = await ctx.ui.select(`Project setup for loops (.pi/loops.json)\n\n${setupText(fields)}\n`, ["Save", "Change…", "Discuss"]);
+        if (choice?.startsWith("Change")) { const note = (await ctx.ui.input?.("What should change?", "e.g. serve is npm start -- -p $PORT; no check"))?.trim(); return { content: [{ type: "text", text: note ? `Not saved. Change requested: ${note}\nRevise and call loop_init again.` : "Not saved. Revise with me in chat, then call loop_init again." }], details: { phase: "change", note } }; }
+        if (choice !== "Save") return { content: [{ type: "text", text: "Not saved. Discuss the setup with me in chat, then call loop_init again." }], details: { phase: "discuss" } };
+      }
+      saveConfig(ctx.cwd, { ...Object.fromEntries(SETUP_KEYS.map((k) => [k, null])), ...fields });
+      return { content: [{ type: "text", text: `Saved ${path.relative(ctx.cwd, configFiles(ctx.cwd).project)}:\n${setupText(fields)}` }], details: { phase: "saved", setup: fields } };
+    } });
+  pi.registerTool?.({ name: "loop_status", label: "loop_status", description: "Progress of a loop round running in the background: phase, each attempt's status, tools and tokens.", parameters: Type.Object({ id: idParam }),
+    async execute(_id, p) { const r = liveRun(p.id); return { content: r.last?.content ?? [{ type: "text", text: `${r.id} starting` }], details: r.details }; } });
+  pi.registerTool?.({ name: "loop_talk", label: "loop_talk", description: "Tell a running attempt something (R1-bold, or just bold): delivered into its session as a steering message it acts on next.", parameters: Type.Object({ attempt: Type.String(), message: Type.String(), id: idParam }),
+    async execute(_id, p) { const r = liveRun(p.id); const key = findAttempt(r, p.attempt); if (!key) throw new Error(`${p.attempt} is not running (running: ${[...r.attempts.keys()].join(", ") || "none"})`); await r.attempts.get(key).steer(`Message from the person running this loop: ${p.message}`); return said(`told ${key}: ${p.message}`); } });
+  pi.registerTool?.({ name: "loop_rule", label: "loop_rule", description: "Add a rule to a running loop: every running attempt is told now, the judge enforces it from this round on, and it stays for later rounds.", parameters: Type.Object({ rule: Type.String(), id: idParam }),
+    async execute(_id, p) { const r = liveRun(p.id); if (!r.state.rules.includes(p.rule)) { r.state.rules.push(p.rule); if (r.state.rubric) addRule(r.state.rubric, p.rule); saveState(r.cwd, r.state); } await Promise.allSettled([...r.attempts.values()].map((s) => s.steer(`New rule for this loop, from the person running it: ${p.rule}`))); return said(`rule added: ${p.rule} (told ${r.attempts.size} running attempt${r.attempts.size === 1 ? "" : "s"})`); } });
+  pi.registerTool?.({ name: "loop_pick", label: "loop_pick", description: "Decide the running round yourself: when the judge is done, keep this attempt (R1-wild, or just wild; or CURRENT) as the best if its check passes, whatever the judge scored.", parameters: Type.Object({ attempt: Type.String(), id: idParam }),
+    async execute(_id, p) { const r = liveRun(p.id); r.pick = p.attempt; return said(`when round ${r.details?.round ?? "?"} of ${r.id} is judged, ${p.attempt} is kept`); } });
+  pi.registerTool?.({ name: "loop_apply", label: "loop_apply", description: "Take a run's best into the checkout: checks out the winner's changed tracked files from its commit and commits them (files it added or deleted are listed, not applied). Default: this session's last run.", parameters: Type.Object({ id: idParam }),
+    async execute(_id, p, _signal, _onUpdate, ctx) {
+      const mine = !p.id || p.id === "last" ? sessionRuns(ctx).find((id) => fs.existsSync(stateFile(ctx.cwd, id))) : null;
+      const state = loadState(ctx.cwd, mine ?? p.id);
+      if (RUNS.has(state.id)) throw new Error(`${state.id} is still running — loop_stop it or wait for the card`);
+      const r = applyBest(ctx.cwd, state);
+      const lines = [r.commit ? `Applied ${state.best.label} (${state.best.commit.slice(0, 7)}) as ${r.commit.slice(0, 7)}: ${r.applied.join(", ")}` : r.already ? `${state.best.label} is already in the checkout.` : "Nothing applied — the winner changed no tracked file."];
+      if (r.files.added.length) lines.push(`Not applied — files it added: ${r.files.added.join(", ")} (git checkout ${state.best.commit.slice(0, 7)} -- <file> to take one)`);
+      if (r.files.removed.length) lines.push(`Not applied — files it deleted: ${r.files.removed.join(", ")}`);
+      return { ...said(lines.join("\n")), details: { run: state.id, applied: r.applied, commit: r.commit, files: r.files } };
+    } });
+  pi.registerTool?.({ name: "loop_stop", label: "loop_stop", description: "Stop a round running in the background: aborts its attempts and judge. What they committed stays in the worktrees; loop({ from }) resumes the run.", parameters: Type.Object({ id: idParam }),
+    async execute(_id, p) { const r = liveRun(p.id); r.ctrl.abort(); await r.promise.catch(() => {}); return said(`${r.id} stopped. Resume with loop({ from: "${r.id}" }).`); } });
+}