@computesdk/pi-loops 1.0.1 → 1.0.3

package/README.md

@@ -42,9 +42,9 @@ Morph and Particle ship as their own packages, so you can install either one wit
 | Provider | Package | Key | Models |
 | --- | --- | --- | --- |
 | Particle AI | `pi-particle` | `PARTICLE_API_KEY` (`pai-…`) | `particle-1`, `deepseek-ai/deepseek-v41-flash-1017`, `glm-5.3-flash` |
-| Morph | `pi-morph` | `MORPH_API_KEY` | `morph-kimik3`, `morph-kimik3-fast`, `morph-glm53-744b`, `morph-glm53flash`, `morph-dsv41flash`, `morph-dsv41flash-1017`, `morph-dsv4flash` |
+| Morph | `@computesdk/pi-morph` | `MORPH_API_KEY` | `morph-kimik3`, `morph-kimik3-fast`, `morph-glm53-744b`, `morph-glm53flash`, `morph-dsv41flash`, `morph-dsv41flash-1017`, `morph-dsv4flash` |
 
-They live in this repo under `packages/pi-morph` and `packages/pi-particle`; install them with `pi install npm:pi-morph` (or `pi install npm:pi-particle`). Loops itself is model-agnostic — it runs on whatever your TUI is on.
+They live in this repo under `packages/pi-morph` and `packages/pi-particle`; install them with `pi install npm:@computesdk/pi-morph` (or `pi install npm:pi-particle`). Loops itself is model-agnostic — it runs on whatever your TUI is on.
 
 ## The one tool
 
@@ -70,6 +70,8 @@ loop({
 
 **Visual mode** (no `bench`): each attempt runs `build` itself and must leave the `shots` files (PNG/JPEG) in its worktree; a **judge** panel scores them (median of 3) and the top two go head-to-head against CURRENT, both orders; a candidate wins with a clear majority and a score not below CURRENT's. CURRENT's shots are taken with the same `build` in your checkout (round 1) or the previous winner's worktree. Uncommitted edits in your checkout are part of the baseline in both modes: round 1 forks from a commit of your working tree (`git stash create`, your checkout is untouched), so attempts and CURRENT start from the same state.
 
+Screenshots come from `lib/shot.ts`: headless Chrome driven over the Chrome DevTools Protocol, no dependencies (CDP over Node's built-in `WebSocket`). The default is the **whole page**, not the 900px fold — a judge scoring a screenshot should see all of it — with `--viewport` for the fold and `--selector '#card'` for one element. Any Chrome/Chromium works, including `chrome-headless-shell`, the headless-only binary that has no `--screenshot` flag at all and is what `npx playwright install chromium-headless-shell` puts in `~/.cache/ms-playwright`; `LOOPS_CHROME` overrides discovery. Loops looks for one **before** the round starts and, when there is none, fails once with the install hint instead of three `build failed` lines. A route that 404s or refuses the connection is an error, never a picture of the browser's error page. The sheet is `montage` (ImageMagick) when installed.
+
 **The pick is yours.** After every judged round you get the round card: when the run has `shots` (either mode) a side-by-side **sheet** of CURRENT and the attempts with their numbers (`.pi/loops/<run>/r<n>.png`, also shown inline in terminals with image support), and a picker — keep the judge's pick, take another attempt instead, show an attempt's diff, or mark an attempt's session to open afterwards (`/loop-open R1-bold`, `/loop-open judge`). The result ends with the **climb**: one line per round, CURRENT, each attempt with its delta, what was kept.
 
 **Steering while it runs.** In the TUI the tool returns as soon as the round has started and the card arrives as a message when the judge is done, so the conversation stays open: `loop_status` (progress), `loop_talk("R1-bold", "…")` (a steering message into that attempt's session), `loop_rule("…")` (told to every running attempt, enforced by the judge from this round on, kept for later rounds), `loop_pick("wild")` (keep that attempt, or `CURRENT`, whatever the judge scores), `loop_stop()` (abort; worktrees stay, `loop({ from })` resumes). After the card, `loop_apply()` takes the run's best into the checkout — the winner's changed tracked files from its commit, as one commit; files it added or deleted are listed, not applied. Headless (`pi -p`) or with `wait: true` the tool blocks until the round is done, as before.
@@ -108,7 +110,7 @@ Config is Loops' own file, the way Pi extensions keep theirs: `<repo>/.pi/loops.
 }
 ```
 
-**Judging.** Visual and code-only rounds are scored by a panel: every council model (by default the attempts' models) scores every candidate 0–10 against the goal and rules, labels blind, median across models and samples; the `judge` model keeps the vetoes and the head-to-head against CURRENT that decides the round. The card says when the panel split (`Panel split on R1-wild: kimi-k3 3 · qwen3.8-flash 8 · glm-5.3 8`). `"judgePanel": false` in `.pi/loops.json` goes back to the judge alone; bench rounds are measured, not scored.
+**Judging.** A visual round is judged on screenshots, so the judge — and every panel member, when the panel is on — must be a model that can see images; one that cannot is refused before the round starts (it would score every candidate the same, which reads as a tie), with the fix in the message. The one-shot sessions the judge and council run in load no extensions, so Loops copies the host's provider registrations into them: providers added by an extension (rather than built into Pi) can judge just as the attempts can, and nothing else about that session changes — no tools, no extension commands. Visual and code-only rounds are scored by a panel: every council model (by default the attempts' models) scores every candidate 0–10 against the goal and rules, labels blind, median across models and samples; the `judge` model keeps the vetoes and the head-to-head against CURRENT that decides the round. The card says when the panel split (`Panel split on R1-wild: kimi-k3 3 · qwen3.8-flash 8 · glm-5.3 8`). `"judgePanel": false` in `.pi/loops.json` goes back to the judge alone; bench rounds are measured, not scored.
 
 **Models.** A round is also a comparison of models: the three attempts and the council members should each run on a different one. The first `/loop` in a repo (interactive, nothing set yet, more than one model available) asks four times — a model for each attempt, one for the judge (the council is the attempts' models) — and writes them to `.pi/loops.json`; `/loop models` re-opens that picker. `models` keys are the roles — `safe`, `bold`, `wild`, `judge`, `scout`, and `council` (a string or a list, one member per model). Roles left unset are spread over the **pool**: `models.pool` (a list of `provider/id`, `id` or `provider/*` patterns), else Pi's own `enabledModels`, starting from your current model; with no pool everything runs on your current model and the result says so. The round table and climb show each attempt's model. `"scout": false` turns the scout off (a bare goal then runs in visual mode on the goal alone).
 
@@ -120,6 +122,6 @@ Ctrl+C aborts the attempts and leaves their worktrees and sessions in place. `lo
 
 ## Library
 
-`lib/measure.ts` (shell runner, protect restore, diff), `lib/judge.ts` (`pickWinner` over the judge's numbers, the visual `panelJudge`), `lib/rubric.ts` (council synthesis, human rules), `lib/shot.ts` (serve + headless-Chrome screenshot CLI), `lib/sheet.ts` (the labelled sheet, via ImageMagick's `montage` when installed). All model calls are injected, so `pnpm test` runs them against stubs — no model needed. The whole package is TypeScript: Pi loads the `.ts` files directly (no build step), and `pnpm check` (or `pnpm -r check` from the repo root) checks them. It ships no `main`/`exports` on purpose — Node refuses to strip types inside `node_modules`, so a programmatic `import "@computesdk/pi-loops"` would need a build; Pi loads the files through jiti and does not.
+`lib/measure.ts` (shell runner, protect restore, diff), `lib/judge.ts` (`pickWinner` over the judge's numbers, the visual `panelJudge`), `lib/rubric.ts` (council synthesis, human rules), `lib/shot.ts` (serve + headless-Chrome screenshot CLI over CDP: full page, viewport or one selector), `lib/sheet.ts` (the labelled sheet, via ImageMagick's `montage` when installed). All model calls are injected, so `pnpm test` runs them against stubs — no model needed. The whole package is TypeScript: Pi loads the `.ts` files directly (no build step), and `pnpm check` (or `pnpm -r check` from the repo root) checks them. It ships no `main`/`exports` on purpose — Node refuses to strip types inside `node_modules`, so a programmatic `import "@computesdk/pi-loops"` would need a build; Pi loads the files through jiti and does not.
 
 `test/fixtures/fuzzy/bench` is the test repo: `cp -r test/fixtures/fuzzy/bench /tmp/fuzzy && cd /tmp/fuzzy && git init && git add -A && git commit -m base`, then run the `/loop` above.

package/extensions/loop.ts

@@ -6,13 +6,14 @@ 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 { createAgentSession, createAgentSessionFromServices, createAgentSessionServices, DefaultResourceLoader, SessionManager, getAgentDir, withFileMutationQueue, 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";
+import { findChrome } from "../lib/shot.ts";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** Package root: `agents/`, `prompts/` and `lib/` sit one level up from `extensions/`. */
@@ -20,6 +21,46 @@ 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");
+/** Usage of a whole round: every attempt session, judge sample and council member, so the tool can report it. */
+export type Meter = { input: number; output: number; cacheRead: number; cacheWrite: number; totalTokens: number; cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number } };
+export const newMeter = (): Meter => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } });
+/** Add one message's `usage`. Providers report what they report: anything missing counts as zero, never as NaN. */
+export function addUsage(m: Meter | undefined, u: any) {
+  if (!m || !u) return;
+  m.input += u.input || 0; m.output += u.output || 0; m.cacheRead += u.cacheRead || 0; m.cacheWrite += u.cacheWrite || 0;
+  m.totalTokens += u.totalTokens || 0;
+  m.cost.input += u.cost?.input || 0; m.cost.output += u.cost?.output || 0;
+  m.cost.cacheRead += u.cost?.cacheRead || 0; m.cost.cacheWrite += u.cost?.cacheWrite || 0;
+  m.cost.total += typeof u.cost === "number" ? u.cost : u.cost?.total || 0;
+}
+/** `3.2k tok · $0.0410`, for the card and the result. */
+export const meterText = (m: Meter | undefined) => m && m.totalTokens ? `${Math.round(m.totalTokens / 100) / 10}k tok · $${m.cost.total.toFixed(4)}` : "";
+
+/** A `build` that is our own screenshot CLI (written by `routes`): it needs a browser, so check for one up front. */
+const SELF_SHOT = /[\\/]shot\.ts/;
+
+/** Can this model see images? `null` when the model object does not say (a stub, or a catalog entry without `input`). */
+export const seesImages = (m: unknown): boolean | null => {
+  const input = (m as { input?: unknown } | null | undefined)?.input;
+  return Array.isArray(input) ? input.includes("image") : null;
+};
+
+/**
+ * A visual round is judged on screenshots, so a judge that cannot see them scores every candidate the same and the round
+ * reads as a tie: worse than not running, because it looks like it worked. Refuse up front instead. Bare-goal rounds are
+ * `kind: "visual"` too but are judged on diffs, so the gate is about screenshots, not the kind.
+ * Returns the problem, or null when every role that looks at pictures can.
+ */
+export const judgedOnScreenshots = (state: { kind?: string; shots?: string[] | null }) => state.kind === "visual" && !!state.shots?.length;
+
+export function visionProblem(roles: { role: string; key: string; spec: string | null | undefined; model: unknown }[]): string | null {
+  for (const r of roles) {
+    if (r.model == null || seesImages(r.model) !== false) continue;
+    return `visual mode judges screenshots, and the ${r.role}${r.spec ? ` (${r.spec})` : ""} cannot see images — it would score every candidate the same. ` +
+      `Pick a vision model for the ${r.role} (/loop models, or "models": { "${r.key}": "…" } in .pi/loops.json), or pass \`bench\` so the round is measured instead of looked at.`;
+  }
+  return null;
+}
 
 /** 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 };
@@ -38,7 +79,13 @@ 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 };
+export type ModelRegistryLike = {
+  getAvailable?: () => ModelRef[]; find?: (provider: string, id: string) => ModelRef | undefined;
+  /** Providers an *extension* registered (pi-particle, pi-morph, anything not built into Pi), with their config. */
+  getRegisteredProviderIds?: () => readonly string[];
+  getRegisteredProviderConfig?: (provider: string) => unknown;
+  getRegisteredNativeProvider?: (provider: string) => unknown;
+};
 /** 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. */
@@ -74,6 +121,12 @@ export type ToolDef<P = any> = {
   description: string;
   parameters: any;
   outputSchema?: any;
+  /** `model-only` for the tools that ask the user or orchestrate: never callable from scripts. */
+  exposure?: "direct" | "model-only" | "codemode" | "deferred" | "hidden";
+  /** "sequential" for tools that share in-memory state, so one message's calls cannot interleave. */
+  executionMode?: "sequential" | "parallel";
+  /** MCP tool hints: what a permission extension needs to decide whether to ask. */
+  annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean };
   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;
@@ -166,6 +219,10 @@ export function loopSettings(pi: Pi | null, cwd: string, agentDir: string = getA
   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. */
+/** `saveConfig` is a read-merge-write, so the whole of it takes the file queue; two tools must not interleave. */
+export const saveConfigQueued = (cwd: string, patch: Record<string, any>) =>
+  withFileMutationQueue(configFiles(cwd).project, async () => saveConfig(cwd, patch));
+
 export function saveConfig(cwd: string, patch: Record<string, any>): Record<string, any> {
   const f = configFiles(cwd).project;
   const cur = readJson(f);
@@ -302,17 +359,45 @@ const release = (session: AgentSession) => { active.delete(session); try { sessi
 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 }) {
+/**
+ * A one-shot session (judge, council) loads no extensions — that keeps it lean and tool-free — so a provider that an
+ * *extension* adds (rather than one built into Pi) is unknown inside it and its credential cannot be resolved. Say that
+ * instead of pi's "No API key found", which points at /login and sends people the wrong way.
+ */
+function explainAuth(e: unknown, role: string, spec: string | null, ctx: Ctx): unknown {
+  const provider = errText(e).match(/No API key found for ([\w.-]+)/)?.[1]?.replace(/\.+$/, ""); // pi ends the sentence with a period
+  if (!provider) return e;
+  // the host can see a model on that provider (so this session is missing something the host has), not a bare missing login
+  const hostKnows = (ctx.modelRegistry?.getAvailable?.() ?? []).some((m) => (m as { provider?: string }).provider === provider);
+  if (!hostKnows) return e;
+  return new Error(`the ${role} cannot run on ${spec ?? provider}: "${provider}" is a Pi extension's provider, and a one-shot ${role} session loads no extensions, so it has no credentials there — give the ${role} a provider built into Pi (attempts can still use ${provider}).`, { cause: e });
+}
+
+async function oneShot({ role, model, content, cwd, ctx, settings, meter, signal }: { role: string; model?: string | null; content: any; cwd: string; ctx: Ctx; settings: LoopSettings; meter?: Meter; signal?: AbortSignal }) {
   const agentDir = getAgentDir();
+  const spec = model ?? settings.models[role] ?? null;
   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 });
+  let session: AgentSession | null = null;
+  const onAbort = () => session?.abort().catch(() => {});
   try {
+    // what a one-shot wants: no extensions, no skills, no tools — just the role's system prompt and one answer
+    const services = await createAgentSessionServices({ cwd, agentDir,
+      resourceLoaderOptions: { noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true, systemPrompt: agent.body } });
+    // "no extensions" would also drop the *providers* extensions add (anything not built into Pi), and an unregistered
+    // provider has no credentials. Copy the host's registrations over: config only, no extension code runs, still no tools.
+    const known = new Set(services.modelRuntime.getRegisteredProviderIds());
+    for (const id of ctx.modelRegistry?.getRegisteredProviderIds?.() ?? []) {
+      if (known.has(id)) continue;
+      const config = ctx.modelRegistry?.getRegisteredProviderConfig?.(id);
+      if (config) { services.modelRuntime.registerProvider(id, config as any); continue; }
+      const native = ctx.modelRegistry?.getRegisteredNativeProvider?.(id); // a provider built with createProvider, not config
+      if (native) services.modelRuntime.registerNativeProvider(native as any);
+    }
+    // creating the session resolves the credential too, so it belongs inside this try: that is where an unusable provider shows up
+    const { session: created } = await createAgentSessionFromServices({ services, sessionManager: SessionManager.inMemory(cwd), model: pickModel(ctx, spec ?? agent.model), noTools: "all" });
+    session = track(created);
+    const { text, images } = flattenParts(content);
+    signal?.addEventListener("abort", onAbort, { once: true });
     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`);
@@ -322,16 +407,23 @@ async function oneShot({ role, model, content, cwd, ctx, settings, signal }: { r
       if (last?.stopReason === "error") throw new Error(last.errorMessage || `${role} errored`);
     }
     return parseJson(session.getLastAssistantText());
-  } finally { signal?.removeEventListener("abort", onAbort); release(session); }
+  } catch (e) { throw explainAuth(e, role, spec, ctx); }
+  finally {
+    signal?.removeEventListener("abort", onAbort);
+    if (session) {
+      // a one-shot is a whole session with real spend: hand it to the round's meter before the session goes away
+      for (const m of session.messages) if (m.role === "assistant") addUsage(meter, (m as { usage?: unknown }).usage);
+      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> {
+async function runAttempt({ state, style, n, dir, cwd, ctx, settings, model, meter, sessionDir, src, signal, onProgress, live }: { state: State; style: string; n: number; dir: string; cwd: string; ctx: PickCtx; settings: LoopSettings; model?: string | null; meter?: Meter; sessionDir?: string; src?: 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 agent = loadAgent(style, { cwd, agentDir });
+  const fork = state.best.session ?? src;
+  const sessionManager = fork && fs.existsSync(fork) ? SessionManager.forkFrom(fork, 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);
@@ -346,6 +438,7 @@ async function runAttempt({ state, style, n, dir, ctx, settings, model, signal,
     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;
+      addUsage(meter, e.message.usage);
       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);
@@ -641,7 +734,7 @@ export async function pickModels(ctx: PickCtx, { reason }: { reason?: string } =
   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 }; }
+  try { saved = await saveConfigQueued(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) };
 }
 
@@ -697,7 +790,7 @@ 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"); } };
+  const set = async (patch: Record<string, any>, what: string) => { try { await saveConfigQueued(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 {}
@@ -728,7 +821,9 @@ export default function loopsExtension(pi: Pi): void {
       await pi.sendUserMessage?.(loopPrompt(args, ctx.cwd));
     },
   });
-  pi.on?.("session_shutdown", async () => { for (const r of RUNS.values()) r.ctrl.abort(); await stopAll(); });
+  // state is module-scoped, so a session that starts after one has shut down must not inherit its latch
+  pi.on?.("session_start", async () => { shuttingDown = false; RUNS.clear(); });
+  pi.on?.("session_shutdown", async () => { shuttingDown = true; 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);
@@ -763,17 +858,37 @@ export default function loopsExtension(pi: Pi): void {
       }
       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 };
     }
+    // a run that rebuilds its shots with our CLI needs a browser: fail once here, before three attempt sessions and a
+    // judge panel start, whatever wrote the `build` (routes, resume, or by hand). The message names the fix.
+    if (SELF_SHOT.test(state.build ?? "")) findChrome();
+    // a visual round is only as good as the eyes on it: refuse a judge (or panel member) that cannot see the screenshots
+    if (judgedOnScreenshots(state)) {
+      const asModel = (spec: string | null | undefined) => { try { return pickModel(ctx, spec); } catch { return null; } }; // an unavailable model reports itself later
+      const panelOn = settings.council !== false && settings.judgePanel !== false && (models.council?.length ?? 0) > 1;
+      const problem = visionProblem([
+        { role: "judge", key: "judge", spec: models.judge, model: asModel(models.judge) },
+        ...(panelOn ? (models.council ?? []).map((spec, i) => ({ role: `panel member ${i + 1}`, key: "council", spec, model: asModel(spec) })) : []),
+      ]);
+      if (problem) throw new Error(problem);
+    }
     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);
+    // every nested model call in this round — attempts, judge samples, council — adds to one meter, reported as the result's `usage`
+    const meter = newMeter();
+    // a TUI call returns as soon as the round starts, and session replacement invalidates the old ctx: capture what the
+    // background run needs as plain data now (the model registry is the one shared object that stays valid)
+    const sessionDir = ctx.sessionManager?.getSessionDir?.();
+    const sessionFile = ctx.sessionManager?.getSessionFile?.() ?? null;
+    const setStatus = (text?: string) => { try { ctx.ui.setStatus?.("loops", text); } catch {} };
     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 });
+    const push = (phase?: string) => { details.phase = phase ?? details.phase; if (live) setStatus(`${state.id} r${details.round ?? "?"} · ${details.phase}`); 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, meter, signal });
+    const askAs = (role: string, model?: string | null) => (content: any) => oneShot({ role, model, content, cwd, ctx, settings, meter, 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 };
@@ -810,7 +925,7 @@ export default function loopsExtension(pi: Pi): void {
         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(); } });
+        const r = await runAttempt({ state, style, n, dir, cwd, ctx, settings, model: models[style], meter, sessionDir, src: sessionFile, 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) };
       }));
@@ -931,13 +1046,14 @@ export default function loopsExtension(pi: Pi): void {
     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 }];
+    const spend = meterText(meter);
+    const content: any[] = [{ type: "text", text: spend ? `${text}\nSpent ${spend} on this run's models.` : 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 })) } };
+    return { content, usage: meter.totalTokens ? meter : undefined, structuredContent: structuredResult(state, state.rounds), details: { ...structuredClone(details), phase: aborted ? "aborted" : "done", status: state.status, best: state.best, winner: state.winner, spent: spend || null, rounds: done.map((r) => ({ n: r.n, pick: r.judge?.pick ?? null, why: r.judge?.why ?? null })) } };
   }
 
   pi.registerTool?.({
-    name: "loop",
+    name: "loop", exposure: "model-only", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     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.",
@@ -984,7 +1100,7 @@ export default function loopsExtension(pi: Pi): void {
   });
   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,
+  pi.registerTool?.({ name: "loop_init", exposure: "model-only", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, 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) {
@@ -992,28 +1108,29 @@ export default function loopsExtension(pi: Pi): void {
         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 });
+      await saveConfigQueued(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 }),
+  pi.registerTool?.({ name: "loop_status",  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, 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 }),
+  pi.registerTool?.({ name: "loop_talk", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, 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 }),
+  pi.registerTool?.({ name: "loop_rule", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, 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 }),
+  pi.registerTool?.({ name: "loop_pick", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, 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 }),
+  pi.registerTool?.({ name: "loop_apply", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, 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);
+      // a git checkout + commit in the user's checkout: serialise it against other mutations of that repo
+      const r = await withFileMutationQueue(path.join(ctx.cwd, ".git"), async () => 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 }),
+  pi.registerTool?.({ name: "loop_stop", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, 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}" }).`); } });
 }

package/lib/judge.ts

@@ -139,7 +139,7 @@ export async function panelJudge(o: JudgeOptions): Promise<PanelResult> {
   const per = Math.max(1, Math.ceil(n / panel.length));
   const settled = await Promise.allSettled(panel.flatMap((m) => Array.from({ length: per }, () => scoreOnce({ ...o, ask: m.ask }).then((r) => ({ ...r, by: m.name })))));
   const runs = settled.filter((r): r is PromiseFulfilledResult<any> => r.status === "fulfilled").map((r) => r.value);
-  if (!runs.length) throw new Error(`judge failed (all samples): ${[...new Set(settled.map((s) => String(s.status === "rejected" ? s.reason?.message ?? s.reason : "unknown").slice(0, 120)))].join(" | ")}`);
+  if (!runs.length) throw new Error(`judge failed (all samples): ${[...new Set(settled.map((s) => String(s.status === "rejected" ? s.reason?.message ?? s.reason : "unknown").slice(0, 240)))].join(" | ")}`);
   const labels = o.candidates.map((c) => c.label);
   const scores: Record<string, number> = {}, spread: Record<string, number> = {}, reasons: Record<string, string> = {};
   for (const l of labels) {

package/lib/shot.ts

@@ -1,26 +1,63 @@
 #!/usr/bin/env node
-// Screenshot a route of a web app with headless Chrome, starting the app first when asked. No dependencies.
+// Screenshot a route of a web app with headless Chrome, driving it over the Chrome DevTools Protocol,
+// starting the app first when asked. No dependencies: CDP over Node's built-in WebSocket.
 //   node shot.ts --url /pricing --out shots/pricing.png --serve "npm start"        (app is given $PORT)
 //   node shot.ts --url http://localhost:3000/ --out shots/home.png                 (already running)
 // Options: --port N (default: a free one), --width 1440 --height 900, --wait ms (settle time after load, default 1500),
-//          --timeout s (how long to wait for the server, default 180), --chrome <path> (or $LOOPS_CHROME / $CHROME).
-import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+//          --timeout s (how long to wait for the server, default 180), --load-timeout s (the page, default 30),
+//          --chrome <path> (or $LOOPS_CHROME / $CHROME),
+//          --viewport (capture the viewport only; the default is the whole page), --selector <css> (capture one element).
+// The default is the whole page, not the fold: a judge scoring a screenshot should see all of it.
+// Any Chrome/Chromium works, including chrome-headless-shell — the headless binary Playwright installs, which has
+// no `--screenshot` flag at all and can only be driven over CDP. That is why this file speaks CDP.
+import { spawn, type ChildProcess } from "node:child_process";
 import fs from "node:fs";
 import net from "node:net";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const CHROMES = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "chrome", "brave-browser", "microsoft-edge",
-  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium",
-  "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"];
+/** Commands looked up on $PATH, in this order. The last three are the headless-only binaries. */
+const NAMES = ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "chrome", "brave-browser", "microsoft-edge",
+  "chrome-headless-shell", "headless-shell", "headless_shell"];
+/** Absolute paths, for installs that are not on $PATH. */
+const PATHS = ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  "/headless-shell/headless-shell", // exe.dev VMs ship the headless shell Shelley drives here
+  "/usr/lib/chromium/chromium", "/snap/bin/chromium", "/opt/google/chrome/chrome"];
 
+const which = (cmd: string) => { for (const dir of (process.env.PATH ?? "").split(path.delimiter)) { const p = path.join(dir, cmd); if (fs.existsSync(p)) return p; } return null; };
+const isPath = (c: string) => c.includes("/");
+
+/** Newest first: Playwright's cache is versioned, and the last install is the one to use. */
+function playwrightShells(): string[] {
+  const root = process.env.PLAYWRIGHT_BROWSERS_PATH || path.join(os.homedir(), ".cache", "ms-playwright");
+  let entries: string[];
+  try { entries = fs.readdirSync(root); } catch { return []; }
+  const found: string[] = [];
+  for (const e of entries.sort().reverse()) {
+    if (e.startsWith("chromium_headless_shell-")) found.push(path.join(root, e, "chrome-headless-shell-linux64", "chrome-headless-shell"), path.join(root, e, "chrome-headless-shell-mac-arm64", "chrome-headless-shell"), path.join(root, e, "chrome-headless-shell-mac-x64", "chrome-headless-shell"));
+    else if (e.startsWith("chromium-")) found.push(path.join(root, e, "chrome-linux", "chrome"), path.join(root, e, "chrome-mac", "Chromium.app", "Contents", "MacOS", "Chromium"));
+  }
+  return found;
+}
+
+/** Where a browser could be, in the order we trust it: what you asked for, $PATH, known install dirs. */
+export function chromeCandidates(explicit?: string): string[] {
+  const named = [explicit, process.env.LOOPS_CHROME, process.env.CHROME, process.env.PUPPETEER_EXECUTABLE_PATH].filter((c): c is string => !!c);
+  const fromNames = NAMES.map(which).filter((p): p is string => !!p);
+  return [...named, ...fromNames, ...PATHS, ...playwrightShells()];
+}
+
+/** The first usable browser binary; throws a message that says what to do about it when there is none. */
 export function findChrome(explicit?: string): string {
-  const cands = [explicit, process.env.LOOPS_CHROME, process.env.CHROME, process.env.PUPPETEER_EXECUTABLE_PATH, ...CHROMES].filter((c): c is string => !!c);
-  for (const c of cands) {
-    if (c.includes("/")) { if (fs.existsSync(c)) return c; continue; }
-    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) { const p = path.join(dir, c); if (fs.existsSync(p)) return p; }
+  for (const c of chromeCandidates(explicit)) {
+    if (isPath(c)) { if (fs.existsSync(c)) return c; continue; }
+    const p = which(c); if (p) return p;
   }
-  throw new Error("no Chrome/Chromium found; install one or set LOOPS_CHROME=/path/to/chrome");
+  throw new Error("no Chrome/Chromium found — visual mode screenshots routes with headless Chrome. Any Chromium works: install one, " +
+    "`npx playwright install chromium-headless-shell` puts one where loops looks (~/.cache/ms-playwright), or " +
+    "point LOOPS_CHROME at a binary, e.g. LOOPS_CHROME=/usr/bin/chromium");
 }
 
 export const freePort = () => new Promise<number>((res, rej) => { const s = net.createServer(); s.unref(); s.on("error", rej); s.listen(0, "127.0.0.1", () => { const addr = s.address(); const port = typeof addr === "object" && addr ? addr.port : 0; s.close(() => res(port)); }); });
@@ -35,12 +72,124 @@ async function waitFor(url: string, timeoutMs: number, child: ChildProcess | nul
   throw new Error(`server did not answer at ${url} within ${timeoutMs / 1000}s`);
 }
 
-export async function shot({ url, out, serve, port, width = 1440, height = 900, wait = 1500, timeout = 180, chrome, cwd = process.cwd(), log = () => {} }: {
-  url?: string; out?: string; serve?: string; port?: number; width?: number; height?: number;
-  wait?: number; timeout?: number; chrome?: string; cwd?: string; log?: (msg: string) => void;
+/* ---------- CDP: launch, connect, capture ---------- */
+
+type Send = (method: string, params?: Record<string, unknown>, sessionId?: string) => Promise<any>;
+type Cdp = { send: Send; close: () => void; on: (method: string, fn: (params: any) => void) => () => void };
+
+async function connect(wsUrl: string): Promise<Cdp> {
+  const sock = new WebSocket(wsUrl);
+  const pending = new Map<number, { ok: (v: any) => void; fail: (e: Error) => void }>();
+  const listeners = new Map<string, Set<(params: any) => void>>();
+  let id = 0;
+  sock.addEventListener("message", (e) => {
+    const m = JSON.parse(String(e.data));
+    if (m.id) { const p = pending.get(m.id); if (!p) return; pending.delete(m.id); if (m.error) p.fail(new Error(m.error.message)); else p.ok(m.result); return; }
+    for (const fn of listeners.get(m.method) ?? []) { try { fn(m.params); } catch {} }
+  });
+  await new Promise<void>((res, rej) => {
+    sock.addEventListener("open", () => res());
+    sock.addEventListener("error", () => rej(new Error("could not connect to the browser's DevTools endpoint")));
+  });
+  const send: Send = (method, params = {}, sessionId) => new Promise((ok, fail) => {
+    const n = ++id; pending.set(n, { ok, fail });
+    sock.send(JSON.stringify({ id: n, method, params, ...(sessionId ? { sessionId } : {}) }));
+  });
+  return {
+    send, close: () => { try { sock.close(); } catch {} },
+    on: (method, fn) => { const s = listeners.get(method) ?? new Set(); s.add(fn); listeners.set(method, s); return () => { s.delete(fn); }; },
+  };
+}
+
+/** Start the browser on a port Chrome picks itself, and read the endpoint it prints. */
+function launch(bin: string): { child: ChildProcess; endpoint: Promise<string> } {
+  const child = spawn(bin, ["--headless=new", "--no-sandbox", "--disable-gpu", "--hide-scrollbars", "--disable-dev-shm-usage",
+    "--remote-debugging-port=0", "about:blank"], { stdio: ["ignore", "ignore", "pipe"], detached: true });
+  const endpoint = new Promise<string>((res, rej) => {
+    let buf = "";
+    const t = setTimeout(() => rej(new Error(`the browser did not open a DevTools endpoint: ${buf.split("\n").filter((l) => !/dbus|gpu|vulkan|fontconfig/i.test(l)).slice(-2).join(" ").slice(0, 240)}`)), 30000);
+    child.stderr?.on("data", (d) => { buf += String(d); const m = buf.match(/DevTools listening on (ws:\/\/\S+)/); if (m) { clearTimeout(t); res(m[1]); } });
+    child.on("exit", (code) => { clearTimeout(t); rej(new Error(`the browser exited (${code}) before it was ready`)); });
+  });
+  return { child, endpoint };
+}
+
+const kill = (child: ChildProcess) => {
+  const pid = child.pid; if (!pid) return;
+  try { process.kill(-pid, "SIGTERM"); } catch { try { child.kill("SIGTERM"); } catch {} }
+  setTimeout(() => { try { process.kill(-pid, "SIGKILL"); } catch {} }, 1500).unref();
+};
+
+/** An element's box in page coordinates, for `--selector`. */
+async function boxOf(to: Send, selector: string) {
+  await to("DOM.enable");
+  const { root } = await to("DOM.getDocument", { depth: -1 });
+  const { nodeId } = await to("DOM.querySelector", { nodeId: root.nodeId, selector });
+  if (!nodeId) throw new Error(`no element matches ${selector}`);
+  const { model } = await to("DOM.getBoxModel", { nodeId });
+  const [x1, y1, , , x2, , , y2] = model.border as number[]; // TL, TR, BR, BL → width/height from the opposite corners
+  return { x: x1, y: y1, width: Math.max(x2 - x1, 1), height: Math.max(y2 - y1, 1) };
+}
+
+/** Chrome refuses absurd surfaces; a 12000px page still shows everything a judge needs. */
+const MAX_HEIGHT = 12000;
+
+/**
+ * Screenshot `url` into `out`: the whole page unless `viewport`, or one element when `selector` is given.
+ * Throws when no browser is installed (findChrome's message says what to do), when the page does not load
+ * (a route that 404s or refuses the connection is an error, never a screenshot of the browser's error page),
+ * or on a bad selector.
+ */
+export async function capture({ url, out, width = 1440, height = 900, wait = 1500, loadTimeout = 30, viewport = false, selector, chrome, cwd = process.cwd() }: {
+  url: string; out: string; width?: number; height?: number; wait?: number; /** seconds to wait for the page to load */ loadTimeout?: number;
+  viewport?: boolean; selector?: string; chrome?: string; cwd?: string;
+}): Promise<string> {
+  const bin = findChrome(chrome);
+  const { child, endpoint } = launch(bin);
+  let cdp: Cdp | null = null;
+  try {
+    cdp = await connect(await endpoint);
+    // about:blank first, then navigate: the page has to be watched from before its first request
+    const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await cdp.send("Target.attachToTarget", { targetId, flatten: true });
+    const to: Send = (method, params = {}) => cdp!.send(method, params, sessionId);
+    await to("Page.enable");
+    await to("Network.enable");
+    await to("Emulation.setDeviceMetricsOverride", { width, height, deviceScaleFactor: 1, mobile: false });
+    const failures: string[] = [];
+    let loaded = false;
+    cdp.on("Page.loadEventFired", () => { loaded = true; });
+    cdp.on("Network.loadingFailed", (p) => { if (p?.type === "Document") failures.push(p.errorText ?? "the document failed to load"); });
+    cdp.on("Network.responseReceived", (p) => { if (p?.type === "Document" && p.response?.status >= 400) failures.push(`HTTP ${p.response.status}`); });
+    const nav = await to("Page.navigate", { url });
+    if (nav?.errorText) failures.push(nav.errorText);
+    for (const t0 = Date.now(); !loaded && !failures.length && Date.now() - t0 < loadTimeout * 1000;) await new Promise((r) => setTimeout(r, 100));
+    if (wait) await new Promise((r) => setTimeout(r, wait));
+    if (failures.length) throw new Error(`${url}: ${failures[0]}`);
+    const layout = await to("Page.getLayoutMetrics");
+    const pageSize = layout.cssContentSize ?? layout.contentSize;
+    const clip = selector ? await boxOf(to, selector)
+      : viewport ? { x: 0, y: 0, width, height }
+      : { x: 0, y: 0, width: Math.max(Math.ceil(pageSize.width), width), height: Math.min(Math.max(Math.ceil(pageSize.height), height), MAX_HEIGHT) };
+    const { data } = await to("Page.captureScreenshot", { format: "png", captureBeyondViewport: true, fromSurface: true, clip: { ...clip, scale: 1 } });
+    const file = path.resolve(cwd, out);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, Buffer.from(data, "base64"));
+    return file;
+  } finally {
+    cdp?.close();
+    kill(child);
+  }
+}
+
+/* ---------- CLI: serve the app, then capture ---------- */
+
+export async function shot({ url, out, serve, port, width = 1440, height = 900, wait = 1500, timeout = 180, chrome, cwd = process.cwd(), viewport = false, selector, loadTimeout = 30, log = () => {} }: {
+  url?: string; out?: string; serve?: string; port?: number; width?: number; height?: number; wait?: number; timeout?: number;
+  chrome?: string; cwd?: string; viewport?: boolean; selector?: string; loadTimeout?: number; log?: (msg: string) => void;
 }) {
   if (!url || !out) throw new Error("shot needs --url and --out");
-  const bin = findChrome(chrome);
+  findChrome(chrome); // fail before starting anything, with the message that says what to install
   let child: ChildProcess | null = null, logFile: string | null = null;
   if (serve) {
     port ??= await freePort();
@@ -53,12 +202,9 @@ export async function shot({ url, out, serve, port, width = 1440, height = 900,
   const target = /^https?:\/\//.test(url) ? url : `http://localhost:${port ?? (() => { throw new Error("a relative --url needs --serve or --port"); })()}${url.startsWith("/") ? "" : "/"}${url}`;
   try {
     if (child || port) await waitFor(target, timeout * 1000, child);
-    fs.mkdirSync(path.dirname(path.resolve(cwd, out)), { recursive: true });
-    const args = ["--headless=new", "--no-sandbox", "--disable-gpu", "--hide-scrollbars", "--disable-dev-shm-usage", `--window-size=${width},${height}`,
-      `--virtual-time-budget=${wait}`, `--screenshot=${path.resolve(cwd, out)}`, target];
-    const r = spawnSync(bin, args, { cwd, encoding: "utf8", timeout: 120000 });
-    if (r.status !== 0 || !fs.existsSync(path.resolve(cwd, out))) throw new Error(`chrome failed (${r.status}): ${(r.stderr || "").split("\n").filter((l) => !/dbus|gpu|vulkan|fontconfig/i.test(l)).slice(-3).join(" ")}`);
-    return path.resolve(cwd, out);
+    const file = await capture({ url: target, out, width, height, wait, loadTimeout, viewport, selector, chrome, cwd });
+    log(`${selector ?? (viewport ? "viewport" : "full page")} → ${out}`);
+    return file;
   } finally {
     if (child) {
       if (child.pid) { try { process.kill(-child.pid, "SIGTERM"); } catch {} }
@@ -69,7 +215,7 @@ export async function shot({ url, out, serve, port, width = 1440, height = 900,
   }
 }
 
-type ShotArgs = Partial<{ url: string; out: string; serve: string; port: number; width: number; height: number; wait: number; timeout: number; chrome: string }>;
+type ShotArgs = Partial<{ url: string; out: string; serve: string; port: number; width: number; height: number; wait: number; timeout: number; loadTimeout: number; chrome: string; selector: string; viewport: boolean }>;
 
 function parseArgs(argv: string[]): ShotArgs {
   const o: Record<string, unknown> = {};
@@ -77,7 +223,9 @@ function parseArgs(argv: string[]): ShotArgs {
     const a = argv[i];
     if (!a.startsWith("--")) continue;
     const k = a.slice(2); const v = argv[i + 1];
-    if (["width", "height", "wait", "timeout", "port"].includes(k)) { o[k] = Number(v); i++; }
+    if (k === "load-timeout") { (o as any).loadTimeout = Number(v); i++; continue; }
+    if (["width", "height", "wait", "timeout", "load-timeout", "port"].includes(k)) { o[k] = Number(v); i++; }
+    else if (k === "viewport" || k === "full") { o.viewport = k === "viewport"; }
     else { o[k] = v; i++; }
   }
   return o as ShotArgs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@computesdk/pi-loops",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Hill-climbing loops as Pi units: one `loop` tool, style agents, forked attempt sessions in git worktrees, a judge keeps the best.",
   "keywords": [
     "pi-package",
@@ -49,7 +49,7 @@
   ],
   "scripts": {
     "check": "tsc --noEmit",
-    "test": "tsc --noEmit && node test/rubric.ts && node test/judge.ts && node test/measure.ts && node test/loop.ts"
+    "test": "tsc --noEmit && node test/rubric.ts && node test/judge.ts && node test/measure.ts && node test/shot.ts && node test/loop.ts"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",