@computesdk/pi-loops 1.0.5 → 1.0.6

package/README.md

@@ -74,6 +74,8 @@ Screenshots come from `lib/shot.ts`: headless Chrome driven over the Chrome DevT
 
 **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.
 
+**What a round spends.** Every nested model call — the attempts, each judge sample, the council — is counted: the result carries `usage`, and the card ends with `Spent 68.8k tok · $0.0000`. A round started from the TUI returns before it finishes, so there is no tool result to carry that; instead Loops writes one `type: "usage"` entry per model to the session (kind `loops`, note naming the run), which is the entry kind Pi sums into its token and cost totals and shows in the footer. So a background round lands in `/cost` and the footer like any other model call, and `/resume` of that session still adds up.
+
 **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.
 
 Before round 1 of a bench run a **council** (two proposals + a synthesis) writes the rubric the judge judges against; your `rules` become decisive criteria in it.

package/extensions/loop.ts

@@ -14,6 +14,7 @@ import { better as betterOf, git, restoreProtected, sh, diffText, errText, type
 import { addRule, fromRules, newRubric, parseJson, rubricText, writeRubric } from "../lib/rubric.ts";
 import { sheet } from "../lib/sheet.ts";
 import { findChrome } from "../lib/shot.ts";
+import { appendAnswer, appendQuestion, findQuestion, newQuestion, pendingQuestions, questionsOf, questionsText, questionText, type Question, type QuestionOption } from "../lib/questions.ts";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** Package root: `agents/`, `prompts/` and `lib/` sit one level up from `extensions/`. */
@@ -21,20 +22,47 @@ 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 } });
+/** Usage of a whole round, and of each model in it: a round's attempts, judge and council can be different models. */
+export type UsageTotals = { input: number; output: number; cacheRead: number; cacheWrite: number; totalTokens: number; cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number } };
+export type Meter = UsageTotals & { byModel: Record<string, UsageTotals> };
+export const emptyTotals = (): UsageTotals => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } });
+export const newMeter = (): Meter => ({ ...emptyTotals(), byModel: {} });
 /** 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) {
+function addTo(t: UsageTotals, u: any) {
+  t.input += u.input || 0; t.output += u.output || 0; t.cacheRead += u.cacheRead || 0; t.cacheWrite += u.cacheWrite || 0;
+  t.totalTokens += u.totalTokens || 0;
+  t.cost.input += u.cost?.input || 0; t.cost.output += u.cost?.output || 0;
+  t.cost.cacheRead += u.cost?.cacheRead || 0; t.cost.cacheWrite += u.cost?.cacheWrite || 0;
+  t.cost.total += typeof u.cost === "number" ? u.cost : u.cost?.total || 0;
+}
+export function addUsage(m: Meter | undefined, u: any, model?: string | null) {
   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;
+  addTo(m, u);
+  if (model) { m.byModel[model] ??= emptyTotals(); addTo(m.byModel[model], u); }
+}
+/** The `usage` a tool result carries: the totals, without the per-model split. */
+export const meterUsage = (m: Meter): UsageTotals => { const { byModel: _byModel, ...totals } = m; return totals; };
+
+/**
+ * A background round cannot report its spend on a tool result — the card arrives as a message — so it records
+ * usage entries on the session instead: Pi's totals and the footer scan entries of `type: "usage"`, and such an
+ * entry is model-attributed and never enters the LLM context. One entry per model, since each is billed separately.
+ */
+export function recordUsage(sm: SessionManagerLike | undefined, meter: Meter, note: string): string[] {
+  const recorded: string[] = [];
+  for (const [spec, u] of Object.entries(meter.byModel)) {
+    if (!u.totalTokens) continue;
+    const cut = spec.indexOf("/");
+    const provider = cut > 0 ? spec.slice(0, cut) : spec;
+    const model = cut > 0 ? spec.slice(cut + 1) : "unknown";
+    if (typeof sm?.appendUsage !== "function") break; // a session manager from an older Pi: nothing to record against
+    try { sm.appendUsage("loops", provider, model, u, note); recorded.push(spec); } catch {}
+  }
+  return recorded;
 }
+
 /** `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)}` : "";
+export const meterText = (m: UsageTotals | 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/;
@@ -87,7 +115,9 @@ export type ModelRegistryLike = {
   getRegisteredNativeProvider?: (provider: string) => unknown;
 };
 /** The session-manager methods Loops calls. */
-export type SessionManagerLike = { getBranch?: () => any[]; getSessionDir?: () => string; getSessionFile?: () => string | undefined };
+export type SessionManagerLike = { getBranch?: () => any[]; getSessionDir?: () => string; getSessionFile?: () => string | undefined;
+  /** Record spend that came from a session other than this one (`type: "usage"`), which Pi adds to its totals. */
+  appendUsage?: (kind: string, provider: string, model: string, usage: any, note?: string) => unknown };
 /** The subset of Pi's UI the extension calls. */
 export type Ui = {
   notify: (message: string, type?: string) => void;
@@ -101,6 +131,8 @@ export type PickCtx = { cwd: string; model?: ModelRef | null; modelRegistry?: Mo
 /** The Pi command/tool context Loops uses (only these fields are touched). */
 export type Ctx = PickCtx & {
   hasUI?: boolean;
+  /** `tui` in the terminal, `rpc`/`json` in a programmatic session: only the TUI wants a notify nudge. */
+  mode?: string;
   sessionManager?: SessionManagerLike;
   switchSession?: (file: string) => Promise<void>;
 };
@@ -384,6 +416,7 @@ async function oneShot({ role, model, content, cwd, pick, registry, settings, me
   const spec = model ?? settings.models[role] ?? null;
   const agent = loadAgent(role, { cwd, agentDir });
   let session: AgentSession | null = null;
+  let pickedModel: Model | null = null; // named in the finally, so the spend can be attributed to it
   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
@@ -400,7 +433,8 @@ async function oneShot({ role, model, content, cwd, pick, registry, settings, me
       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: pick(spec ?? agent.model), noTools: "all" });
+    pickedModel = pick(spec ?? agent.model);
+    const { session: created } = await createAgentSessionFromServices({ services, sessionManager: SessionManager.inMemory(cwd), model: pickedModel, noTools: "all" });
     session = track(created);
     const { text, images } = flattenParts(content);
     signal?.addEventListener("abort", onAbort, { once: true });
@@ -418,7 +452,7 @@ async function oneShot({ role, model, content, cwd, pick, registry, settings, me
     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);
+      for (const m of session.messages) if (m.role === "assistant") addUsage(meter, (m as { usage?: unknown }).usage, pickedModel ? modelSpec(pickedModel) : null);
       release(session);
     }
   }
@@ -444,7 +478,7 @@ async function runAttempt({ state, style, n, dir, cwd, pick, settings, model, me
     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);
+      addUsage(meter, e.message.usage, modelSpec(picked));
       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);
@@ -522,14 +556,31 @@ async function agentJSON({ role, model, prompt, ok, cwd, ctx, settings, signal,
 }
 
 /* ---------- the tool ---------- */
+/** The `loop` result's artifact pointers: a frontend renders a run without guessing where its worktrees keep things. */
+const Artifacts = {
+  /** Paths (relative to the repo) that each attempt's build writes — the same paths in every attempt worktree. */
+  shots: Type.Optional(Type.Array(Type.String())),
+  sheet: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  dir: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  files: Type.Optional(Type.Any()),
+  tokens: Type.Optional(Type.Number()),
+  cost: Type.Optional(Type.Number()),
+  judgeTokens: Type.Optional(Type.Number()),
+  judgeCost: Type.Optional(Type.Number()),
+  from: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+};
 const Metric = Type.Object({ key: Type.Optional(Type.String({ description: "JSON key in the bench output; default ms" })), unit: Type.Optional(Type.String()), better: Type.Optional(Type.Union([Type.Literal("lower"), Type.Literal("higher")])) });
 const RoundOut = Type.Object({ n: Type.Number(), pick: Type.Union([Type.String(), Type.Null()]), why: Type.Union([Type.String(), Type.Null()]), scores: Type.Record(Type.String(), Type.Union([Type.Number(), Type.Null()])), reasons: Type.Record(Type.String(), Type.String()), sheet: Type.Union([Type.String(), Type.Null()]),
-  attempts: Type.Array(Type.Object({ label: Type.String(), style: Type.String(), status: Type.String(), model: Type.Union([Type.String(), Type.Null()]), commit: Type.Union([Type.String(), Type.Null()]), session: Type.Union([Type.String(), Type.Null()]), summary: Type.String(), cost: Type.Number() })) });
+  from: Artifacts.from, judgeTokens: Artifacts.judgeTokens, judgeCost: Artifacts.judgeCost,
+  attempts: Type.Array(Type.Object({ label: Type.String(), style: Type.String(), status: Type.String(), model: Type.Union([Type.String(), Type.Null()]), commit: Type.Union([Type.String(), Type.Null()]), session: Type.Union([Type.String(), Type.Null()]), summary: Type.String(), cost: Type.Number(), dir: Artifacts.dir, tokens: Artifacts.tokens, bench: Type.Optional(Type.Any()), review: Type.Optional(Type.Any()), vetoed: Type.Optional(Type.Boolean()), restored: Type.Optional(Type.Boolean()) })) });
 export const LoopResult = Type.Object({
   run: Type.String(), status: Type.String(), kind: Type.String(), goal: Type.String(), baseCommit: Type.String(),
   metric: Type.Object({ key: Type.Union([Type.String(), Type.Null()]), unit: Type.Union([Type.String(), Type.Null()]), better: Type.Union([Type.String(), Type.Null()]) }),
-  best: Type.Object({ label: Type.Union([Type.String(), Type.Null()]), commit: Type.Union([Type.String(), Type.Null()]), score: Type.Union([Type.Number(), Type.Null()]), branch: Type.Union([Type.String(), Type.Null()]) }),
+  best: Type.Object({ label: Type.Union([Type.String(), Type.Null()]), commit: Type.Union([Type.String(), Type.Null()]), score: Type.Union([Type.Number(), Type.Null()]), branch: Type.Union([Type.String(), Type.Null()]), round: Type.Optional(Type.Union([Type.Number(), Type.Null()])), dir: Artifacts.dir, files: Artifacts.files }),
+  shots: Artifacts.shots,
+  rules: Type.Optional(Type.Array(Type.String())),
   rounds: Type.Array(RoundOut),
+  questions: Type.Optional(Type.Array(Type.Object({ id: Type.String(), kind: Type.String(), title: Type.String(), options: Type.Array(Type.String()) }))),
 });
 /** `loop_status`: what a script polling a run gets. */
 export const StatusResult = Type.Object({ run: Type.String(), phase: Type.String() });
@@ -537,15 +588,37 @@ export const StatusResult = Type.Object({ run: Type.String(), phase: Type.String
 export const InitResult = Type.Object({ phase: Type.String(), note: Type.Optional(Type.String()), serve: Type.Optional(Type.String()), check: Type.Optional(Type.String()), bench: Type.Optional(Type.String()), protect: Type.Optional(Type.Array(Type.String())) });
 /** `loop_apply`: what landed in the checkout, and what was deliberately left out. */
 export const ApplyResult = Type.Object({ run: Type.String(), applied: Type.Array(Type.String()), commit: Type.Union([Type.String(), Type.Null()]), added: Type.Array(Type.String()), removed: Type.Array(Type.String()) });
+/** `loop_ask`: the queued question, and where a frontend reads it from. */
+export const AskResult = Type.Object({ id: Type.String(), question: Type.String(), options: Type.Array(Type.String()), pending: Type.Number() });
+
+/** The `loop` result's artifact pointers: a frontend renders a run without guessing where its worktrees keep things. */
+const ArtifactsOld = null;
 
-export function structuredResult(state: Pick<State, "id" | "status" | "kind" | "goal" | "baseCommit" | "metric" | "best">, rounds: Round[]) {
+export function structuredResult(state: Pick<State, "id" | "status" | "kind" | "goal" | "baseCommit" | "metric" | "best"> & Partial<State>, rounds: Round[]) {
   const n = (v: unknown): number | null => (typeof v === "number" && Number.isFinite(v) ? v : null);
   return {
-    run: state.id, status: state.status, kind: state.kind, goal: state.goal, baseCommit: state.baseCommit,
+    run: state.id, status: state.status, kind: state.kind, goal: state.goal, baseCommit: state.baseCommit ?? "",
     metric: { key: state.metric?.key ?? null, unit: state.metric?.unit ?? null, better: state.metric?.better ?? null },
-    best: { label: state.best?.label ?? null, commit: state.best?.commit ?? null, score: n(state.best?.score), branch: state.best?.branch ?? null },
-    rounds: rounds.map((r) => ({ n: r.n, pick: r.judge?.pick ?? null, why: r.judge?.why ?? null, scores: Object.fromEntries(Object.entries(r.judge?.scores ?? {}).map(([k, v]) => [k, n(v)])), reasons: Object.fromEntries(Object.entries(r.judge?.reasons ?? {}).map(([k, v]) => [k, String(v)])), sheet: r.sheet ?? null,
-      attempts: r.attempts.map((a) => ({ label: a.label, style: a.style, status: a.status, model: a.model ?? null, commit: a.commit ?? null, session: a.session ?? null, summary: a.summary ?? "", cost: n(a.cost) ?? 0 })) })),
+    shots: state.shots ?? [],
+    rules: state.rules ?? [],
+    best: { label: state.best?.label ?? null, commit: state.best?.commit ?? null, score: n(state.best?.score), branch: state.best?.branch ?? null, round: n(state.best?.round), dir: state.best?.dir ?? null, files: state.winner?.files ?? null },
+    rounds: rounds.map((r) => ({ n: r.n, from: r.from ?? null, pick: r.judge?.pick ?? null, why: r.judge?.why ?? null, scores: Object.fromEntries(Object.entries(r.judge?.scores ?? {}).map(([k, v]) => [k, n(v)])), reasons: Object.fromEntries(Object.entries(r.judge?.reasons ?? {}).map(([k, v]) => [k, String(v)])), sheet: r.sheet ?? null, judgeTokens: n(r.judgeTokens), judgeCost: n(r.judgeCost),
+      attempts: r.attempts.map((a) => ({ label: a.label, style: a.style, status: a.status, model: a.model ?? null, commit: a.commit ?? null, session: a.session ?? null, summary: a.summary ?? "", cost: n(a.cost) ?? 0, tokens: n(a.tokens), dir: a.dir ?? null, ...(a.bench ? { bench: a.bench } : {}), ...(a.review ? { review: a.review } : {}), ...(a.vetoed ? { vetoed: true } : {}), ...(a.restored ? { restored: true } : {}) })) })),
+  };
+}
+
+/** One judged round as a session entry: history that survives deleting `.pi/loops/<run>.json` and needs no query. */
+export function roundEntry(state: State, r: Round) {
+  return {
+    run: state.id, n: r.n, status: r.status, kind: state.kind, goal: state.goal, metric: state.metric ?? null,
+    from: r.from ?? null, baseCommit: state.baseCommit ?? null, shots: state.shots ?? [], rules: state.rules ?? [],
+    pick: r.judge?.pick ?? null, why: r.judge?.why ?? null, human: !!r.judge?.human,
+    scores: r.judge?.scores ?? {}, reasons: r.judge?.reasons ?? {}, byModel: r.judge?.byModel ?? null,
+    sheet: r.sheet ?? null, judgeSession: r.judgeSession ?? null, judgeTokens: r.judgeTokens ?? null, judgeCost: r.judgeCost ?? null,
+    startedAt: r.startedAt ?? null, endedAt: r.endedAt ?? null,
+    best: { label: state.best?.label ?? null, commit: state.best?.commit ?? null, score: state.best?.score ?? null, round: state.best?.round ?? null, dir: state.best?.dir ?? null },
+    attempts: r.attempts.map((a) => ({ label: a.label, style: a.style, model: a.model ?? null, status: a.status, commit: a.commit ?? null, session: a.session ?? null, dir: a.dir ?? null, summary: a.summary ?? "", tokens: a.tokens ?? null, cost: a.cost ?? null, bench: a.bench ?? null, review: a.review ?? null })),
+    at: Date.now(),
   };
 }
 export const LoopParams = Type.Object({
@@ -787,18 +860,19 @@ export function runsText(cwd: string): string {
   return files.map((f) => { try { const st = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")); return `${st.id} — ${st.status} — ${st.goal.slice(0, 60)}\n${climbText(st).split("\n").map((l) => "  " + l).join("\n")}`; } catch { return f; } }).join("\n");
 }
 
-export const SUBCOMMANDS = ["init", "models", "rounds", "budget", "timeout", "open", "runs"];
+export const SUBCOMMANDS = ["init", "models", "rounds", "budget", "timeout", "open", "runs", "questions", "answer"];
 /** Bare, or a subcommand word with at most its argument(s) — anything longer is a goal ("rounds of golf should load faster"); bad values error in loopsCommand instead of starting a round. */
 export function isSubcommand(args?: string | null): boolean {
   const w = (args ?? "").trim().split(/\s+/).filter(Boolean);
   if (!w.length) return true;
   const sub = w[0].toLowerCase();
   if (!SUBCOMMANDS.includes(sub)) return false;
-  if (sub === "models" || sub === "runs" || sub === "init") return w.length === 1;
+  if (sub === "models" || sub === "runs" || sub === "init" || sub === "questions") return w.length === 1;
   if (sub === "open") return w.length <= 3;
+  if (sub === "answer") return w.length >= 2 && w.length <= 8;
   return w.length <= 2;
 }
-const LOOPS_USAGE = "/loop — card and picker · /loop <goal> — run a round · /loop init — project setup (serve, check, bench, protect) · /loop models · /loop rounds <n> · /loop budget <tokens, e.g. 800k|1.5m> · /loop timeout <min> · /loop open <R1-safe|judge> [run] · /loop runs";
+const LOOPS_USAGE = "/loop — card and picker · /loop <goal> — run a round · /loop init — project setup (serve, check, bench, protect) · /loop models · /loop rounds <n> · /loop budget <tokens, e.g. 800k|1.5m> · /loop timeout <min> · /loop open <R1-safe|judge> [run] · /loop runs · /loop questions · /loop answer <id> [option]";
 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();
@@ -822,6 +896,34 @@ export async function loopsCommand(args: string, ctx: Ctx, pi: Pi): Promise<void
     case "open": { if (!rest[0]) { ctx.ui.notify("/loop open <R1-safe|judge> [run id]", "info"); return; } await openSession(ctx, rest[0], rest[1]); return; }
     case "init": await pi.sendUserMessage?.(initPrompt()); return;
     case "runs": ctx.ui.notify(runsText(ctx.cwd), "info"); return;
+    case "questions": {
+      const list = questionsOf(ctx);
+      ctx.ui.notify(questionsText(list.slice(0, 12)), "info");
+      const open = pendingQuestions(ctx);
+      if (open.length) {
+        const q = open[0];
+        const choice = await ctx.ui.select(questionText(q), q.options.map((o) => o.label));
+        if (choice) await loopsCommand(`answer ${q.id} ${choice}`, ctx, pi);
+      }
+      return;
+    }
+    case "answer": {
+      const open = questionsOf(ctx).filter((x) => !x.answer);
+      const q = findQuestion(open.map((x) => x.question), rest[0]);
+      if (!q) { ctx.ui.notify(`no open question ${rest[0] ?? ""} — /loop questions`, "error"); return; }
+      const want = rest.slice(1).join(" ").trim();
+      if (!want) { ctx.ui.notify(`which answer? ${q.options.map((o) => o.label).join(" · ")}`, "error"); return; }
+      const num = Number(want);
+      const choice = Number.isInteger(num) && num >= 1 && num <= q.options.length ? q.options[num - 1].label
+        : q.options.find((o) => o.label.toLowerCase() === want.toLowerCase())?.label
+        ?? q.options.find((o) => o.label.toLowerCase().includes(want.toLowerCase()))?.label;
+      if (!choice) { ctx.ui.notify(`"${want}" is not one of: ${q.options.map((o) => o.label).join(" · ")}`, "error"); return; }
+      appendAnswer(pi, { id: q.id, choice, by: "human", answeredAt: Date.now() });
+      ctx.ui.notify(`answered ${q.id}: ${choice}`, "info");
+      // the answer has to reach the agent: it arrives as a user message, the same way any other steering does
+      await pi.sendUserMessage?.(`Answer to ${q.id}${q.run ? ` (${q.run}${q.round ? ` r${q.round}` : ""})` : ""} — ${q.title}\n${choice}\n\nIf this changes a run, act on it now with loop_pick / loop_rule / loop_stop / loop_apply / loop({ from }).`);
+      return;
+    }
     default: ctx.ui.notify(LOOPS_USAGE, "info");
   }
 }
@@ -904,8 +1006,9 @@ export default function loopsExtension(pi: Pi): void {
     // replaced (`runner.assertActive()`), so the background run holds only values read while it is still alive: the
     // model registry object itself, the session paths, and the status sink. `bindUI` rebinds the new session's UI,
     // so the old one is not touched after a switch.
-    const sessionDir = ctx.sessionManager?.getSessionDir?.();
-    const sessionFile = ctx.sessionManager?.getSessionFile?.() ?? null;
+    const sessionManager = ctx.sessionManager;
+    const sessionDir = sessionManager?.getSessionDir?.();
+    const sessionFile = sessionManager?.getSessionFile?.() ?? null;
     const pickCtx: PickCtx = { cwd, model: ctx.model, modelRegistry: ctx.modelRegistry, ui: ctx.ui };
     const pick: ModelPicker = (spec) => pickModel(pickCtx, spec);
     const statusSink = ctx.ui;
@@ -923,6 +1026,17 @@ export default function loopsExtension(pi: Pi): void {
       if (hasUI && !live) { const r = await ctx.ui.select(title, options); return r ?? fallback; }
       return fallback;
     };
+    // A queued question never blocks the round: it is an append-only session entry that the TUI, a script and a
+    // frontend all read, and that stops being shown on its own if the round makes it moot.
+    const askHuman = (fields: { kind: Question["kind"]; title: string; body?: string | null; options: QuestionOption[]; expiresInMin?: number }): Question | null => {
+      try {
+        const q = newQuestion({ run: state.id, round: details.round ?? null, kind: fields.kind, title: fields.title, body: fields.body ?? null, options: fields.options, expiresAt: Date.now() + (fields.expiresInMin ?? 360) * 60_000 });
+        appendQuestion(pi, q);
+        // the TUI has no queue to open: nudge once, and /loop questions shows the card
+        try { if (ctx.mode === "tui") ctx.ui.notify(`Question for you (${q.kind})\n${questionText(q)}\n\n/loop questions · /loop answer ${q.id}`, "info"); } catch {}
+        return q;
+      } catch { return null; }
+    };
 
     if (!state.rubric && settings.council !== false && state.kind === "bench") {
       push("council writes the rubric");
@@ -1064,6 +1178,14 @@ export default function loopsExtension(pi: Pi): void {
         }
       }
       saveState(cwd, state);
+      try { pi.appendEntry?.("loops-round", roundEntry(state, round)); } catch {}
+      if (live) {
+        const vetoed = results.filter((a) => a.review && a.review.ok === false);
+        const bestTakeable = takeable.find((a) => a.label === judge.pick) ?? takeable[0];
+        if (!takeable.length) askHuman({ kind: "stall", title: `Round ${n} of ${state.id} kept nothing`, body: String(judge.why ?? "").slice(0, 400), options: [{ label: "Keep climbing", suggested: true }, { label: "Stop the loop" }, { label: "Change the rules first" }] });
+        else if (judge.pick === "CURRENT") askHuman({ kind: "close-call", title: `Round ${n}: nothing beat the current best — take ${bestTakeable.label} anyway?`, body: String(judge.why ?? "").slice(0, 400), options: [{ label: "Keep the current best", suggested: true }, { label: `Take ${bestTakeable.label} anyway` }] });
+        else if (vetoed.length) askHuman({ kind: "veto", title: `Round ${n}: ${vetoed.map((a) => a.label).join(", ")} vetoed by the judge`, body: vetoed.map((a) => `${a.label}${a.summary ? ` — ${a.summary}` : ""}: ${a.review?.note ?? "rule break"}`).join("\n").slice(0, 400), options: [{ label: `Keep ${judge.pick}`, suggested: true }, ...vetoed.map((a) => ({ label: `Take ${a.label} anyway` }))] });
+      }
       done.push(round);
       push(`round ${n}: kept ${judge.pick}`);
     }
@@ -1071,12 +1193,19 @@ export default function loopsExtension(pi: Pi): void {
     state.status = aborted ? "aborted" : "done";
     saveState(cwd, state);
     link();
+    // The winner is a commit in a worktree, not in the checkout: the last question a run asks is whether to land it.
+    if (live && state.status === "done" && state.winner?.files?.changed?.length) {
+      const files: string[] = state.winner.files.changed;
+      askHuman({ kind: "apply", expiresInMin: 24 * 60, title: `Apply ${state.best.label} to the checkout?`, body: `Replaces ${files.slice(0, 6).join(", ")}${files.length > 6 ? ` and ${files.length - 6} more` : ""} (tracked files only, one commit)${state.best.score != null ? ` — ${fmt(state.best.score, state.metric?.unit)} from the start` : ""}.`, options: [{ label: "Apply to the checkout", suggested: true }, { label: "Not now" }] });
+    }
     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;
+    // a background round's spend has no tool result to ride on, so it goes into the session's own entries
+    if (live) recordUsage(sessionManager, meter, `loop ${state.id}`);
     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, 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 })) } };
+    return { content, usage: meter.totalTokens ? meterUsage(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?.({
@@ -1165,6 +1294,19 @@ export default function loopsExtension(pi: Pi): void {
       return { ...said(lines.join("\n")), details: { run: state.id, applied: r.applied, commit: r.commit, files: r.files },
         structuredContent: { run: state.id, applied: r.applied, commit: r.commit ?? null, added: r.files.added, removed: r.files.removed } };
     } });
+  pi.registerTool?.({ name: "loop_ask", exposure: "model-only", executionMode: "sequential",
+    promptSnippet: "ask the person a decision as tap-able options (queued, never blocking)",
+    promptGuidelines: ["Use `loop_ask` instead of asking in prose when the decision is the person's (which direction, whether to keep a version, whether to stop, whether to apply a winner): 2-4 options of a few words each. It does not block you; the answer arrives as a user message starting `Answer to <id>`."],
+    label: "loop_ask", outputSchema: AskResult, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    description: "Ask the person who owns this repo a decision, as a queued card with tap-able options. Nothing blocks: the question is a session entry that the TUI shows via /loop questions and a frontend shows as a card, and the answer arrives later as a user message. Round outcomes (a veto, a close call, nothing passing, a winner to apply) raise these on their own.",
+    parameters: Type.Object({ question: Type.String({ description: "One line, phrased as the decision" }), options: Type.Array(Type.String(), { description: "2-4 short answers" }), body: Type.Optional(Type.String({ description: "A sentence or two of context" })), suggested: Type.Optional(Type.Number({ description: "1-based index of the option you recommend" })), expiresInMin: Type.Optional(Type.Number({ description: "Hours-ish window before it stops being shown; default a day" })), id: idParam }),
+    async execute(_id, p, _signal, _onUpdate, ctx) {
+      const options: QuestionOption[] = (p.options as string[]).map((s, i) => ({ label: s, ...(p.suggested === i + 1 ? { suggested: true } : {}) }));
+      const q = newQuestion({ run: p.id && p.id !== "last" ? p.id : null, kind: "ask", title: p.question, body: p.body ?? null, options, expiresAt: Date.now() + (p.expiresInMin ?? 24 * 60) * 60_000 });
+      appendQuestion(pi, q);
+      try { if (ctx.mode === "tui") ctx.ui.notify(`Question for you\n${questionText(q)}\n\n/loop answer ${q.id}`, "info"); } catch {}
+      return { content: [{ type: "text", text: `asked ${q.id}: ${q.title} — ${options.map((o) => o.label).join(" / ")}. The answer arrives as a user message.` }], details: { id: q.id }, structuredContent: { id: q.id, question: q.title, options: options.map((o) => o.label), pending: pendingQuestions(ctx).length } };
+    } });
   pi.registerTool?.({ name: "loop_stop", promptSnippet: "stop a running round; its worktrees stay", 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/questions.ts

@@ -0,0 +1,106 @@
+// Queued questions: a loop asks, the person answers when they get to it.
+//
+// A question is two session entries, `loops-question` and `loops-answer`, so the TUI, a script and any frontend read
+// the same append-only truth and nothing needs a side channel. Nothing here blocks: the loop keeps climbing while a
+// question sits unanswered, and a question that the loop itself made moot (an attempt picked by hand, a new rule) is
+// simply left to expire.
+import { randomBytes } from "node:crypto";
+
+export type QuestionOption = { label: string; suggested?: boolean };
+
+/** What a loop needs from the person running it. */
+export type Question = {
+  id: string;
+  /** The run that asked, when it came from one. */
+  run?: string | null;
+  round?: number | null;
+  /** `ask` is raised on purpose; the rest are raised by a round's outcome. */
+  kind: "ask" | "close-call" | "veto" | "stall" | "apply";
+  title: string;
+  body?: string | null;
+  options: QuestionOption[];
+  createdAt: number;
+  /** When it stops being worth showing; the UI hides it, nothing deletes it. */
+  expiresAt?: number | null;
+};
+
+export type Answer = { id: string; choice: string; by?: string; answeredAt: number };
+export type QuestionWithAnswer = { question: Question; answer: Answer | null };
+
+export const QUESTION_ENTRY = "loops-question";
+export const ANSWER_ENTRY = "loops-answer";
+
+/** The bits of Pi's extension API this needs, so tests can pass a stub. */
+export type QuestionPi = { appendEntry?: (type: string, data?: unknown) => void };
+export type QuestionCtx = { sessionManager?: { getBranch?: () => unknown[] } };
+
+const str = (v: unknown): string | null => (typeof v === "string" && v.trim() ? v.trim() : null);
+
+export function newQuestion(fields: Omit<Question, "id" | "createdAt"> & { id?: string; createdAt?: number }): Question {
+  return {
+    id: fields.id ?? `q-${Date.now().toString(36)}${randomBytes(2).toString("hex")}`,
+    run: fields.run ?? null,
+    round: fields.round ?? null,
+    kind: fields.kind,
+    title: fields.title,
+    body: fields.body ?? null,
+    options: fields.options,
+    createdAt: fields.createdAt ?? Date.now(),
+    expiresAt: fields.expiresAt ?? null,
+  };
+}
+
+/** Every question the session's branch holds, newest first, with its answer when one was given. */
+export function questionsOf(ctx: QuestionCtx): QuestionWithAnswer[] {
+  let entries: any[] = [];
+  try { entries = (ctx.sessionManager?.getBranch?.() ?? []) as any[]; } catch { return []; }
+  const answers = new Map<string, Answer>();
+  const asked: Question[] = [];
+  for (const e of entries) {
+    if (e?.type !== "custom") continue;
+    if (e.customType === ANSWER_ENTRY && str(e.data?.id)) {
+      answers.set(String(e.data.id), { id: String(e.data.id), choice: String(e.data?.choice ?? ""), by: str(e.data?.by) ?? undefined, answeredAt: Number(e.data?.answeredAt ?? 0) });
+    } else if (e.customType === QUESTION_ENTRY && str(e.data?.id)) {
+      const d = e.data as any;
+      asked.push({ id: String(d.id), run: str(d.run), round: typeof d.round === "number" ? d.round : null, kind: d.kind ?? "ask", title: String(d.title ?? ""), body: str(d.body), options: Array.isArray(d.options) ? d.options.map((o: any) => (typeof o === "string" ? { label: o } : { label: String(o?.label ?? ""), suggested: !!o?.suggested })).filter((o: QuestionOption) => o.label) : [], createdAt: Number(d.createdAt ?? 0), expiresAt: typeof d.expiresAt === "number" ? d.expiresAt : null });
+    }
+  }
+  // answers are appended after their question, so they are folded in once every entry has been read
+  return asked.reverse().map((question) => ({ question, answer: answers.get(question.id) ?? null }));
+}
+
+/** Unanswered questions that have not expired, newest first. */
+export function pendingQuestions(ctx: QuestionCtx, now: number = Date.now(), run?: string | null): Question[] {
+  return questionsOf(ctx).filter((x) => !x.answer && !(x.question.expiresAt && x.question.expiresAt < now) && (!run || x.question.run === run)).map((x) => x.question);
+}
+
+export function appendQuestion(pi: QuestionPi, q: Question): Question {
+  try { pi.appendEntry?.(QUESTION_ENTRY, q); } catch {}
+  return q;
+}
+
+export function appendAnswer(pi: QuestionPi, answer: Answer): Answer {
+  try { pi.appendEntry?.(ANSWER_ENTRY, answer); } catch {}
+  return answer;
+}
+
+/** `q-abc123` as a whole, or the shortest unique tail a person would type (`abc123`, `q3`). */
+export function findQuestion(list: Question[], wanted: unknown): Question | null {
+  const want = String(wanted ?? "").trim().toLowerCase();
+  if (!want) return null;
+  return list.find((q) => q.id.toLowerCase() === want) ?? list.find((q) => q.id.toLowerCase().endsWith(want.replace(/^q-?/, ""))) ?? null;
+}
+
+/** One question as the card the TUI and the UI both draw. `picked` marks the answer in the list. */
+export function questionText(q: Question, picked?: string | null): string {
+  const opts = q.options.map((o, i) => `  ${picked && picked === o.label ? "✓" : String(i + 1) + "."} ${o.label}${o.suggested ? "  (suggested)" : ""}`).join("\n");
+  return [q.kind === "ask" ? q.title : `${q.title}`, q.body ?? "", opts].filter(Boolean).join("\n");
+}
+
+export function questionsText(list: QuestionWithAnswer[]): string {
+  if (!list.length) return "no questions — a loop raises one when it needs a decision from you";
+  return list.map(({ question: q, answer }) => {
+    const head = `${q.id}${q.run ? ` · ${q.run}${q.round ? ` r${q.round}` : ""}` : ""} · ${q.kind}${answer ? ` · answered: ${answer.choice}` : ""}`;
+    return `${head}\n${questionText(q, answer?.choice ?? null)}`;
+  }).join("\n\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@computesdk/pi-loops",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "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/shot.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/questions.ts && node test/loop.ts"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",