@computesdk/loops 0.0.0-stage → 0.1.0

package/API.md

@@ -0,0 +1,106 @@
+# The API
+
+The SPA in this package is one client of this API. Another app can be another one — that is the point of the split:
+everything a UI needs is HTTP, and the rendering is yours.
+
+- **Base**: `http://<host>:<port>/api/v1` (the same routes also answer on `/api`, which is what this package's own
+  client uses).
+- **Auth**: `Authorization: Bearer <token>`. `GET /api/v1/meta` and `GET /api/health` are open. A server on loopback
+  may have no token at all; a server that listens on anything else always does.
+- **Errors**: a failed request is `{"error": "..."}` with a 4xx/5xx. Success bodies are JSON unless noted.
+- **CORS**: any origin unless the server was started with `--allow-origin a,b`. The token is the authorization, not a
+  cookie, so credentials are never sent implicitly.
+
+A typed client with no dependencies lives in [`client.ts`](./client.ts):
+
+```ts
+import { LoopsClient } from "@computesdk/pi-loops-ui";
+
+const loops = new LoopsClient({ server: "http://box:3000", token: process.env.LOOPS_TOKEN! });
+const off = loops.events(chat, {
+  state: (s) => render(s),          // whole picture, every change
+  error: (e) => console.warn(e),    // the stream reconnects on its own
+});
+await loops.prompt(chat, "make search() faster; bench is node bench.mjs");
+```
+
+## Reading
+
+| Route | Returns |
+|---|---|
+| `GET /meta` | name, api version, package version, host, whether a token is required, and the workspaces |
+| `GET /workspaces` | `Workspace[]`: `{ id, path, sessionDir, title }` — the repos this server may loop in |
+| `GET /chats?ws=` | `ChatInfo[]`: `{ id, title, last, ws, summary }`, newest first, all repos or one |
+| `GET /state?chat=` | `ChatState`: `{ chat, title, items, live, runs, questions, dialogs, workspaces, ws, proposals }` |
+| `GET /chats/:id/runs` | `Run[]` for a canvas, without the transcript |
+| `GET /config?chat=` | `{ cwd, keys: [{ key, value, source }] }` — each setting with the file it came from |
+| `GET /session?run=&name=` | one attempt's transcript (`ParentItem[]`) |
+| `GET /diff?run=&name=` | `text/plain` unified diff (`name` is an attempt label or a style; `best` works too) |
+| `GET /shot?run=&attempt=&f=` | `image/png` — an attempt's screenshot |
+| `GET /sheet?run=&f=` | `image/png` — the round's contact sheet |
+| `GET /size?run=` | `{ bytes, dirs }` — what a run's worktrees hold (what `clean` would free) |
+| `GET /ui?chat=` | `extension_ui_request[]` still waiting for an answer |
+
+### The event stream
+
+```
+GET /chats/:id/events          Accept: text/event-stream
+
+  id: 6f3a…                    ← the session entry cursor
+  event: state                 ← the same object GET /state returns
+  event: proposals             ← an agent rewrote .pi/loops.json and the server held it
+  event: ping                  ← keep-alive, every 20s
+```
+
+The first frame is always a full `state`, so a client paints immediately and never needs a second call to bootstrap.
+On reconnect send `Last-Event-ID: <the last id you saw>`; the server answers with a snapshot stamped with the newest
+cursor, so nothing is missed while the client was away. `EventSource` cannot set headers — use `fetch` + a stream
+reader (the client above does) so the token can travel in `Authorization`.
+
+## Writing
+
+| Route | Body | Effect |
+|---|---|---|
+| `POST /chat` | `{ ws? }` | new chat in a workspace (default: the server's repo) |
+| `POST /rename` | `{ chat, name }` | names the Pi session, so the TUI sees it too |
+| `POST /chat/delete` | `{ chat }` | deletes the conversation; its loops stay in the repo |
+| `POST /workspaces` | `{ path }` | add a repo (path on the server's machine) |
+| `POST /workspaces/remove` | `{ id }` | forget a repo (not the one the server was started in) |
+| `POST /prompt` | `{ chat, text, behavior? }` | send a message; `behavior` is `steer`/`followUp` while running |
+| `POST /abort` | `{ chat }` | stop the active turn |
+| `POST /answer` | `{ chat, question, choice }` | answer a queued question (a "needs you" card) |
+| `POST /ui` | `{ chat, id, response }` | answer an extension dialog: `{ value }`, `{ confirmed }` or `{ cancelled }` |
+| `POST /steer` | `{ chat, run, action, … }` | engine actions, below |
+| `POST /config` | `{ chat, key, value }` | write one setting (the engine's own writer) |
+| `POST /doctor` | `{ chat }` | boot the app, run the check, ask the judge to read an image |
+| `POST /talk` | `{ chat, run, name, text }` | message the attempt that is running |
+| `POST /live` | `{ run }` | run the winner, return `{ url }` (one slot per server) |
+| `POST /live/stop` | `{ run }` | stop it |
+
+`POST /steer` — the actions a UI offers on a run:
+
+```json
+{ "chat": "chat-…", "run": "loop-…", "action": "take",  "attempt": "R1-bold" }
+{ "chat": "chat-…", "run": "loop-…", "action": "apply" }
+{ "chat": "chat-…", "run": "loop-…", "action": "stop" }
+{ "chat": "chat-…", "run": "loop-…", "action": "clean" }
+{ "chat": "chat-…", "run": "loop-…", "action": "rule", "rule": "never touch test.mjs" }
+{ "chat": "chat-…", "run": "loop-…", "action": "talk", "attempt": "R1-safe", "text": "keep going" }
+{ "chat": "chat-…", "run": "loop-…", "action": "more", "text": 2 }
+```
+
+`take` continues from an attempt even if the judge rejected it, `apply` lands the winner in the checkout and commits,
+`clean` frees the attempt worktrees (the winner's stays), `more` asks the agent for another round. Responses say
+`{"ok": true, "sent": "<disposition>"}`; `sent: "handled"` means an extension consumed the prompt and no run started.
+
+## The loop lifecycle, for a client
+
+1. `prompt` → the agent may call `loop`. In a repo with no config it first raises a **dialog** (`select`: save/change/
+   discuss the setup) — answer it with `POST /ui`, or the tool call waits forever.
+2. `loop` returns as soon as the round starts; the round card arrives later as a chat message. Follow both through the
+   event stream: `state.live` is the turn, `state.runs[].rounds[].inProgress` is the round, `state.dialogs` are the
+   questions that block.
+3. When the round is judged, `runs[].questions` gains a `veto` / `close` / `stall` / `apply` question. Answer it with
+   `POST /answer` — the answer becomes a message to the agent, which acts (`take`, `apply`, …).
+4. Scores, per-attempt outcomes and the judge's reasons are in the round entry; screenshots and diffs are the
+   `GET /shot|/diff|/sheet` routes above.

package/README.md

@@ -1,3 +1,222 @@
-# Temporary Holding Version
+# @computesdk/loops
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Loops for people who do not live in a terminal: a `loops` CLI and a localhost web UI, both clients of
+[`@computesdk/pi-loops`](../pi-loops). The extension is the foundation — it owns the loops, the records and every
+capability. This package owns none of that; it drives the engine.
+
+```sh
+loops status                  # what ran here, read straight from the records (no pi process, no tokens)
+loops doctor --live           # can a round work here? boots serve, runs check, asks the judge to read an image
+loops run "<goal>"            # a round — the one verb that costs tokens
+loops clean | apply | take | rule | questions | answer
+loops serve                   # the browser app for this repo, and the URL to open
+```
+
+Installed from npm it is one command, and that is the one to hand someone:
+
+```sh
+npx @computesdk/loops serve
+```
+
+It is a **client of a real Pi session**, not a re-implementation of one. There is no database and no poll loop:
+the session is the durable record, and `.pi/loops/` is a rebuildable index plus the worktrees it points at.
+
+| What the UI shows | Where it comes from |
+|---|---|
+| the transcript | `get_messages` from the chat's `pi --mode rpc` child |
+| a loop, its rounds, its scores | the `loops-state` snapshot and `loops-round` entries the extension appends to that session |
+| the current winner / applied commit | the newest `loops-state` snapshot (`best`, `winner`, `baseCommit`) |
+| a round in flight | the `loops-progress` entries it appends while it works (throttled; phase changes always) |
+| questions for you | `loops-question` / `loops-answer` entries — append-only, so nothing is rewritten |
+| the brief / approve card | the extension's `ctx.ui.select`, as an `extension_ui_request` |
+| diffs, screenshots, sheets | read-only routes over the run's worktrees and archived shots under `.pi/loops/` |
+
+A chat's repo is also recoverable from Pi itself: each session header records its `cwd`, and the session dir names the
+workspace. `workspaces.json` is a cache — if it is lost or stale, the server rebuilds the chat-to-repo binding from the
+sessions on startup, and writes it atomically.
+
+## Local only, by design
+
+The server binds `127.0.0.1` and refuses any other `--host`. It is not a service: it can prompt an agent that has
+`bash` on this machine, and it serves code that attempts wrote. There is no auth because there is no remote. If you need
+it from another device, tunnel to it (`ssh -L 8001:127.0.0.1:8001 …`) rather than exposing the port.
+
+## Run it
+
+Start it once for the machine, then point it at repos from the tab bar:
+
+```sh
+npx @computesdk/loops serve        # from npm — the one command, from any repo
+# from a checkout:
+loops serve                        # or: node server/index.ts --port 8001
+# or: pi-loops-ui --port 8001 --cwd ~/code/some-repo   (seeds one tab)
+```
+
+It ships as one bundled server plus the built SPA, so there is no build step on the other end. The `pi-loops` extension
+is a runtime dependency and is resolved out of `node_modules`; `pi` itself still has to be on the machine for a round
+to run, which the boot says out loud rather than at the first prompt.
+
+It prints the address and opens it:
+
+```
+  open  http://127.0.0.1:8001
+  loopback only
+```
+
+`--no-open` (or `LOOPS_UI_OPEN=0`) prints the address without launching a browser. When the URL carries a token — off
+loopback — the opened address is the attach form, `/?server=…&token=…`, which the app adopts once and strips from the
+address bar.
+
+A loop needs the engine, so the boot says when it is missing rather than leaving you to find out on the first prompt:
+if `pi` is not on PATH, or an `--extensions` path does not exist, it prints what is wrong and the fix under `!! a loop
+cannot run here yet`, and `/api/health` reports `ok: false` with the same list. The app still serves — you can add
+repos and read what already ran.
+
+A **tab is a repo** ("workspace"): its chats, its runs, its `.pi/loops.json`. `+` adds a repo — the path is resolved
+server-side and must be a directory — and `×` closes it; loops and chats stay on disk. Workspaces, the tab you had
+open, and chats are remembered in `~/.pi/loops-ui`, so a restart resumes everything. A chat remembers its repo, so
+its `pi --mode rpc` child spawns in that directory with that directory's session dir.
+
+Flags (each has a `LOOPS_UI_*` environment variable):
+
+| flag | default | meaning |
+|---|---|---|
+| `--port` | `8001` | where the app listens |
+| `--cwd` | `process.cwd()` | the repo the loops work in |
+| `--pi` | `pi` | the Pi executable each chat spawns |
+| `--extensions` | `../pi-loops/extensions/loop.ts` | comma-separated `-e` paths for the child |
+| `--data` | `~/.pi/loops-ui` | workspaces.json and the chats of every repo |
+| `--host` | `127.0.0.1` | loopback only; anything else is refused (this drives an agent with tools) |
+| `--model` | Pi's default | the model every chat starts on |
+| `--no-open` | off | print the URL without opening a browser (`LOOPS_UI_OPEN=0`) |
+| `--dev` | off | proxy the SPA to Vite on `:5173` (`npm run dev`) |
+
+## Attach to a server on another machine
+
+The SPA is a client. By default it talks to the process that served it; it can be pointed at another one:
+
+```sh
+# on the box that owns the repos — off-loopback listening needs a token
+node server/index.ts --port 3000 --host 0.0.0.0 --token     # prints the URL + token once
+
+# anywhere else: either open the served UI at box:3000, or attach this one to it
+http://box:3000/?server=http://box:3000&token=<printed>
+```
+
+The `server`/`token` pair is adopted once and stripped from the address bar; after that the sidebar footer names the
+server you are attached to (click it to change). A URL that lands in a log is not a problem because the token lives in
+`localStorage` afterwards, but treat it as the password it is: `~/.pi/loops-ui/token`, mode 0600, `--token` to rotate.
+
+**The API is the product.** Anything that wants its own chat UI, its own loop canvas, or its own needs-you inbox should
+use it rather than this SPA: see [`API.md`](./API.md) for every route and the loop lifecycle, and [`client.ts`](./client.ts)
+for a typed client (no dependencies) that can be imported straight into another app.
+
+The routes are the contract, not the SPA: `GET /api/workspaces`, `/api/chats?ws=`, `/api/state?chat=`, `/api/config?chat=`,
+`POST /api/chat|prompt|steer|answer|ui|config|live`, and **one event stream per chat**:
+
+```
+GET /api/chats/:id/events        Accept: text/event-stream
+  id: <session entry id>         ← the cursor; send it back as Last-Event-ID after a drop
+  event: state                   ← the same snapshot /api/state returns
+  event: ping                    ← keep-alive every 20s
+```
+
+SSE over `fetch` (not `EventSource`) so the token can travel in a header, and so a reconnect resumes from the cursor
+instead of starting blind. Any origin may attach (CORS is answered); the token is the authorization.
+
+## What it is made of
+
+```
+server/
+  index.ts      Hono: /api/state, /api/prompt, /api/ui, /api/steer, /api/shot, /api/diff, /ws, static
+  chats.ts      one Chat per session: spawns `pi --mode rpc`, folds its events into one snapshot
+  pi-rpc.ts     the RPC client: JSONL framing, id correlation, extension dialogs
+  runs.ts       the durable session entries first, the `.pi/loops` index as fallback -> the shapes the canvas draws
+  workspaces.ts the repos this process may touch; chats are bound to one
+  config.ts     settings with provenance, agent-write proposals, and the doctor checks
+  live.ts       one live server for the winner, on demand
+src/
+  shared/      the wire types both halves use
+  client/      the SPA (React 19 + Tailwind v4), ported from the POC at ~/factory/mock
+```
+
+### Why an event stream and not a poll
+
+A loop runs **in the background** in Pi: the `loop` tool returns as soon as the round starts, and the round card arrives
+later as a message. In a terminal that is fine — the status line and the card are enough. A canvas wants more, so the
+extension appends a `loops-progress` entry (at most one per 1.5s, always on a phase change) and calls `setStatus`, which
+reaches us as an `extension_ui_request`. Either one wakes the server, which re-reads the session with a cursor
+(`get_entries?since=`). One event in, at most one cheap read out — and a browser that reloads mid-round rebuilds the same
+picture from the entries alone.
+
+### Proof that the judge saw the picture
+
+A judge that never received an image used to score a visual round anyway — the visible symptom was
+`reasons: "Image unavailable"` next to a 5–5 "tie". Two mechanisms make that impossible to miss:
+
+- **Declared capability is checked first.** A judge (or panel member) whose model does not claim image input is
+  refused before an attempt runs, with the setting to change. No model, no round.
+- **Every judged screenshot carries a code in its top-right corner.** The judge must read it back
+  (`"tokens": {"<label>": "<code>"}`); one edit apart counts as a misread, anything else does not count at all. A
+  candidate whose code was not read back is `unseen`: it gets **no score**, the round is marked **inconclusive**
+  (never "even"), and a question is raised — retry, switch the judge, or keep the current best.
+
+The code lives in the pixels only, so it cannot be echoed from the prompt. `lib/shot.ts` does the stamping
+(`stamp`, `canaryImage`), `lib/judge.ts` the comparison (`sameCode`), and `probeVision()` can settle a model's
+capability offline — not inside a tool call, where creating a session waits on the runtime the turn holds.
+
+### Live: one server, on demand
+
+A screenshot is a still of an app that already runs — `lib/shot.ts` starts `serve` inside an attempt's worktree to take
+it. `Run it` keeps that same server alive for the winner instead: one slot, started when you ask, killed when you stop
+it, after ten idle minutes, or when this process exits. It is offered only when the repo has `serve` in
+`.pi/loops.json`. The iframe gets an opaque origin (`sandbox`, no `allow-same-origin`), because the code inside it was
+written by an attempt.
+
+### Judging happens in a child process
+
+An in-session `prompt(text, { images })` does not deliver the picture on this Pi — the message carries the block, the
+provider request does not — so a judge that has to look at screenshots is asked through `pi --print` (the same binary,
+model and auth, with `@file` arguments, which do carry images). Two plumbing rules matter there and both cost a bug
+each: close stdin (`ignore`) or `--print` waits for EOF forever, and parse **stdout only** (pi warns on stderr).
+
+### The checkout is not the attempts' to touch
+
+An attempt has bash and inherits the repo's absolute path, so it can edit or commit into your checkout instead of its
+worktree. Every round therefore checks, after the attempts: did HEAD move, did the working tree gain changes, while
+every attempt's own worktree stayed at the base commit? If so the round is inconclusive (nothing of theirs exists to
+compare), your tree is put back, and the card says what happened — the loop's promise is that your checkout is
+untouched until `loop_apply`.
+
+### Cleanup
+
+Worktrees are scratch copies: the commit lives in the repo and on the branch `loops/<run>/rN-<style>`, so removing a
+worktree loses only what the attempt left uncommitted. `clean up` (or `/loop clean [run|all]`) removes the attempts'
+worktrees, drops the losing branches and runs `git worktree prune`, keeping the winner's worktree, the durable session
+snapshot, the JSON index, the sessions and the archived screenshots. `loop_apply` does it for the losers as soon as a
+winner lands.
+
+### Settings that change under you
+
+`.pi/loops.json` decides which models judge, what the checks are and how much runs. The server watches it and the app
+shows what changed (`models judge exe/… → particle/…`) while it is open — an agent editing config is a real event, not
+a detail.
+
+### Actions
+
+The buttons talk to the engine, not to a model: `/loop take`, `/loop apply`, `/loop stop`, `/loop rule`, `/loop talk`,
+`/loop answer`. Anything that needs judgement ("two more rounds", "steer it this way") is sent to the agent as a message,
+because that is a decision the agent owns.
+
+## Parity
+
+`npm run shots` writes `./shots/` at 1440, 1024 and 430 wide. The pass condition for this port was the screens the POC at
+`~/factory/mock` shows, at the same density; see [`PARITY.md`](./PARITY.md) for the state-by-state comparison.
+
+## Development
+
+```sh
+npm run dev      # Hono on :8001 proxying the SPA to Vite on :5173
+npm run check    # typecheck the server and the client separately
+npm run shots    # headless-chrome screenshots of every state
+```

package/bin/loops.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// `loops` — the foundation without a TUI.
+//
+// Two kinds of verb, and the difference matters:
+//   • bookkeeping (status) reads the records the engine writes; no pi process, no tokens, scriptable
+//   • everything else asks the engine to do it, by running the same `/loop …` command a person would type.
+// The CLI owns no loop logic. If it ever computed a run itself there would be two answers to "what is a run",
+// and the one an agent used would disagree with the one you printed.
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG = path.resolve(HERE, "..");
+const argv = process.argv.slice(2);
+const flag = (name) => argv.includes(`--${name}`);
+const opt = (name, fallback = undefined) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 ? argv[i + 1] : fallback;
+};
+/** Arguments that are not flags or flag values. */
+function positional() {
+  const out = [];
+  const takesValue = new Set(["cwd", "port", "extension", "pi", "run", "attempt", "option", "goal"]);
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith("--")) { if (takesValue.has(argv[i].slice(2))) i++; continue; }
+    out.push(argv[i]);
+  }
+  return out;
+}
+
+const CWD = path.resolve(opt("cwd", process.cwd()));
+const STATE_DIR = path.join(CWD, ".pi", "loops");
+const PI = opt("pi", process.env.LOOPS_PI ?? "pi");
+
+/** The extension this CLI drives: the installed package if we can find it, else the sibling checkout. */
+function extensionPath() {
+  const explicit = opt("extension", process.env.LOOPS_EXTENSION);
+  if (explicit) return path.resolve(explicit);
+  const candidates = [
+    path.resolve(PKG, "../pi-loops/extensions/loop.ts"), // monorepo checkout
+    path.resolve(PKG, "node_modules/@computesdk/pi-loops/extensions/loop.ts"), // installed next to us
+    path.resolve(HERE, "../../../pi-loops/extensions/loop.ts"),
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
+  // npm keeps the dependency flat: ask Node where that package actually is
+  try {
+    const req = spawnSync(process.execPath, ["-e", "console.log(require.resolve('@computesdk/pi-loops/package.json'))"], { encoding: "utf8", cwd: PKG });
+    const found = req.stdout?.trim();
+    if (found) return path.join(path.dirname(found), "extensions", "loop.ts");
+  } catch {}
+  return null;
+}
+
+const usage = `loops — hill-climbing loops for a repo, without the TUI
+
+  loops status [--json] [--run <id>]     what ran here: goal, rounds, best, whether it is still working
+  loops doctor [--live] [--json]         can a round work here? (--live boots serve, runs check, tests the judge)
+  loops config                           every setting in force, and which file it came from
+  loops run "<goal>" [loop options]      start a round (costs tokens; this one needs a model)
+  loops questions                        decisions waiting for you
+  loops answer <id> <option>             answer one
+  loops take <R1-bold> [run]             keep that attempt and climb from it
+  loops rule <run|last> "<rule>"         add a judging rule
+  loops apply [run]                      land the winner in your checkout
+  loops clean [run|all]                  remove attempt worktrees (commits and the winner stay)
+  loops serve [--port 8001] [--no-open]
+                 the browser app for this repo (localhost only), prints the URL and opens it
+  loops ui       same thing, by the older name
+
+  --cwd <repo>      the checkout to work on (default: this directory)
+  --extension <p>   the pi-loops extension to load
+  --pi <path>       the pi executable
+  --json            machine-readable output where the verb supports it
+
+Anything that needs a model runs the same /loop command you would type in pi.`;
+
+const say = (line = "") => process.stderr.write(`${line}\n`);
+
+/** Runs are read straight off the records the engine writes: no process, no tokens. */
+function runs({ run } = {}) {
+  if (!fs.existsSync(STATE_DIR)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(STATE_DIR).filter((f) => f.endsWith(".json"))) {
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(STATE_DIR, f), "utf8"));
+      if (!s?.id || (run && s.id !== run)) continue;
+      const judged = (s.rounds ?? []).filter((r) => r.judge);
+      out.push({
+        id: s.id, goal: s.goal, kind: s.kind, status: s.status,
+        rounds: (s.rounds ?? []).length, judged: judged.length,
+        best: s.best?.label ?? null, bestRound: s.best?.round ?? null, score: s.best?.score ?? null,
+        unit: s.metric?.unit ?? "", escaped: (s.rounds ?? []).some((r) => r.escaped),
+        inconclusive: (s.rounds ?? []).some((r) => r.inconclusive),
+        startedAt: s.rounds?.[0]?.startedAt ?? null, endedAt: s.rounds?.at(-1)?.endedAt ?? null,
+        file: path.relative(CWD, path.join(STATE_DIR, f)),
+      });
+    } catch {}
+  }
+  return out.sort((a, b) => String(b.startedAt ?? "").localeCompare(String(a.startedAt ?? "")));
+}
+
+const fmt = (r) => {
+  const score = r.score == null ? "–" : `${r.score}${r.unit ? ` ${r.unit}` : ""}`;
+  const state = r.status === "running" ? "running" : r.escaped ? "ran in your checkout" : r.inconclusive ? "inconclusive" : r.status;
+  return `${r.id}  ${r.kind.padEnd(6)} ${state.padEnd(20)} r${r.rounds}/${r.judged} ${r.best ?? "–"} ${score}`.trimEnd() + `\n    ${r.goal ?? ""}`;
+};
+
+function status() {
+  const list = runs({ run: opt("run") });
+  if (flag("json")) return process.stdout.write(JSON.stringify(list, null, 2) + "\n");
+  if (!list.length) return say(`no runs in ${path.relative(process.cwd(), STATE_DIR) || STATE_DIR} — start one with: loops run "<goal>"`);
+  for (const r of list) say(fmt(r) + "\n");
+  const live = list.filter((r) => r.status === "running").length;
+  say(`${list.length} run${list.length === 1 ? "" : "s"}${live ? `, ${live} running` : ""}`);
+}
+
+/* ---------- the verbs that ask pi ---------- */
+
+function commandFor(verb) {
+  const p = positional().slice(1); // drop the verb itself
+  switch (verb) {
+    case "questions": return "/loop questions";
+    case "answer": return `/loop answer ${p[0] ?? ""} ${p.slice(1).join(" ")}`.trim();
+    case "take": return `/loop take ${p[0] ?? ""} ${p[1] ?? ""}`.trim();
+    case "rule": return `/loop rule ${p[0] ?? "last"} ${p.slice(1).join(" ")}`;
+    case "apply": return `/loop apply ${p[0] ?? ""}`.trim();
+    case "clean": return `/loop clean ${p[0] ?? ""}`.trim();
+    case "stop": return "/loop stop";
+    case "config": return "/loop config";
+    case "doctor": return flag("live") ? "/loop doctor live" : "/loop doctor";
+    default: return null;
+  }
+}
+
+/** Run one /loop command in a pi child and pass its output straight through. */
+function askEngine(command) {
+  const ext = extensionPath();
+  if (!ext) {
+    say(`cannot find the pi-loops extension — pass --extension <path to extensions/loop.ts>`);
+    return 2;
+  }
+  const args = ["-p", "-e", ext, command];
+  const child = spawn(PI, args, { cwd: CWD, stdio: ["ignore", "inherit", "inherit"], env: { ...process.env, PI_OFFLINE: process.env.PI_OFFLINE ?? "1" } });
+  return new Promise((resolve) => child.on("close", (code) => resolve(code ?? 1)));
+}
+
+/** A round needs a model, so this is the one verb that spends tokens. */
+function runRound() {
+  const goal = positional()[1] ?? opt("goal");
+  if (!goal) { say(`usage: loops run "<goal>" [--bench "<cmd>"] [--check "<cmd>"] [--rounds n]`); return 2; }
+  const parts = [goal];
+  if (opt("check")) parts.push(`check is ${opt("check")}`);
+  if (opt("bench")) parts.push(`bench is ${opt("bench")} and prints ${opt("unit", "ms")}`);
+  say(`starting a round — this one costs tokens\n`);
+  return askEngine(parts.join("; "));
+}
+
+async function main() {
+  const verb = positional()[0] ?? "";
+  if (!verb || verb === "help" || flag("help")) { say(usage); return 0; }
+  if (verb === "status") { status(); return 0; }
+  if (verb === "ui" || verb === "serve") {
+    // Published, the server is one bundled file — Node refuses to strip types inside node_modules, so the .ts is only
+    // the entry in a checkout, where node's stripper runs it directly. Same flags either way.
+    const bundle = path.join(PKG, "dist", "server.mjs");
+    const entry = fs.existsSync(bundle)
+      ? [bundle]
+      : ["--experimental-strip-types", path.join(PKG, "server", "index.ts")];
+    const args = [...entry, "--cwd", CWD, "--port", String(opt("port", "8001"))];
+    if (flag("no-open")) args.push("--no-open");
+    // The extension is a runtime dependency, so it resolves on an install as well as in this workspace; without it the
+    // server's own boot check says so instead of the first prompt failing.
+    const ext = extensionPath();
+    if (ext) args.push("--extensions", ext);
+    const child = spawn(process.execPath, args, { stdio: "inherit", env: process.env });
+    return new Promise((resolve) => child.on("close", (code) => resolve(code ?? 1)));
+  }
+  if (verb === "run") return runRound();
+  const command = commandFor(verb);
+  if (command) return askEngine(command);
+  say(`unknown command "${verb}"\n\n${usage}`);
+  return 2;
+}
+
+process.exitCode = await main();

package/bin/pi-loops-ui.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// The old name, kept so nothing breaks: `pi-loops-ui --port 8001` is `loops ui --port 8001`.
+process.argv.splice(2, 0, "ui");
+await import("./loops.mjs");