@computesdk/pi-loops 1.0.4 → 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>;
 };
@@ -123,6 +155,8 @@ export type ToolDef<P = any> = {
   outputSchema?: any;
   /** One line for the default system prompt's "Available tools" section: without it Pi omits the tool there. */
   promptSnippet?: string;
+  /** Rules for the Guidelines section, shown only while this tool is active. Workflow belongs here, not in the snippet. */
+  promptGuidelines?: string[];
   /** `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. */
@@ -133,6 +167,8 @@ export type ToolDef<P = any> = {
   renderCall?: (args: any, theme: any) => any;
   renderResult?: (result: any, options: { expanded: boolean; isPartial: boolean }, theme: any) => any;
 };
+/** Resolve a model spec against the registry captured while the ctx was alive. */
+export type ModelPicker = (spec?: string | null) => Model;
 /** A candidate for the judge: a checked-out directory at a commit. */
 export type Candidate = { label: string; dir: string; commit: string; fresh?: boolean };
 /** One round of a run. */
@@ -366,20 +402,21 @@ export async function stopAll() { shuttingDown = true; const all = [...active];
  * *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 {
+function explainAuth(e: unknown, role: string, spec: string | null, registry?: ModelRegistryLike): 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);
+  const hostKnows = (registry?.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 }) {
+async function oneShot({ role, model, content, cwd, pick, registry, settings, meter, signal }: { role: string; model?: string | null; content: any; cwd: string; pick: ModelPicker; registry?: ModelRegistryLike; settings: LoopSettings; meter?: Meter; signal?: AbortSignal }) {
   const agentDir = getAgentDir();
   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
@@ -388,15 +425,16 @@ async function oneShot({ role, model, content, cwd, ctx, settings, meter, signal
     // "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?.() ?? []) {
+    for (const id of registry?.getRegisteredProviderIds?.() ?? []) {
       if (known.has(id)) continue;
-      const config = ctx.modelRegistry?.getRegisteredProviderConfig?.(id);
+      const config = registry?.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
+      const native = registry?.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" });
+    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 });
@@ -409,26 +447,26 @@ async function oneShot({ role, model, content, cwd, ctx, settings, meter, signal
       if (last?.stopReason === "error") throw new Error(last.errorMessage || `${role} errored`);
     }
     return parseJson(session.getLastAssistantText());
-  } catch (e) { throw explainAuth(e, role, spec, ctx); }
+  } catch (e) { throw explainAuth(e, role, spec, registry); }
   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);
+      for (const m of session.messages) if (m.role === "assistant") addUsage(meter, (m as { usage?: unknown }).usage, pickedModel ? modelSpec(pickedModel) : null);
       release(session);
     }
   }
 }
 
 /* ---------- an attempt: forked session + worktree + style agent ---------- */
-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> {
+async function runAttempt({ state, style, n, dir, cwd, pick, settings, model, meter, sessionDir, src, signal, onProgress, live }: { state: State; style: string; n: number; dir: string; cwd: string; pick: ModelPicker; 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, 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);
+  const picked = pick(model ?? settings.models[style] ?? agent.model);
   const { session: created } = await createAgentSession({ cwd: dir, agentDir, model: picked, tools: agent.tools?.length ? agent.tools : undefined, resourceLoader: loader, sessionManager });
   const session = track(created);
   live?.attempts.set(`R${n}-${style}`, session);
@@ -440,7 +478,7 @@ async function runAttempt({ state, style, n, dir, cwd, ctx, settings, model, met
     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);
@@ -518,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() });
@@ -533,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({
@@ -783,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();
@@ -818,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");
   }
 }
@@ -832,12 +938,20 @@ export default function loopsExtension(pi: Pi): void {
   });
   // 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(); });
+  pi.on?.("session_shutdown", async () => {
+    shuttingDown = true;
+    const runs = [...RUNS.values()];
+    for (const r of runs) r.ctrl.abort();
+    // disposing the session invalidates the ctx, so the runs must be finished before this returns, not just aborted
+    await Promise.allSettled(runs.map((r) => r.promise));
+    await stopAll();
+  });
   async function run(params: LoopParamsIn, signal: AbortSignal | undefined, onUpdate: ((update: any) => void) | undefined, ctx: Ctx, live: any) {
     const cwd = ctx.cwd;
+    const hasUI = ctx.hasUI ?? false; // a getter on the ctx proxy: stale after replacement, so read it once
     let settings = loopSettings(pi, cwd);
     const chosen = Object.keys(settings.models).some((k) => k !== "pool");
-    if (!params.from && !chosen && ctx.hasUI && (ctx.modelRegistry?.getAvailable?.() ?? []).length > 1) {
+    if (!params.from && !chosen && hasUI && (ctx.modelRegistry?.getAvailable?.() ?? []).length > 1) {
       const r = await pickModels(ctx, { reason: "First loop here" });
       if (r && "error" in r) throw new Error(r.error);
       if (r && "models" in r) settings = { ...settings, models: { ...settings.models, ...r.models } };
@@ -872,7 +986,7 @@ export default function loopsExtension(pi: Pi): void {
     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 asModel = (spec: string | null | undefined) => { try { return pick(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) },
@@ -888,23 +1002,41 @@ export default function loopsExtension(pi: Pi): void {
     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 {} };
+    // A TUI call returns as soon as the round starts, and `ctx` is a getter proxy that throws once the session is
+    // 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 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;
+    let alive = true;
+    const setStatus = (text?: string) => { if (alive) { try { statusSink.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) 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 });
+    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, pick, registry: pickCtx.modelRegistry, settings, meter, signal });
+    const askAs = (role: string, model?: string | null) => (content: any) => oneShot({ role, model, content, cwd, pick, registry: pickCtx.modelRegistry, 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 };
     const needsYou = async (title: string, options: string[], fallback: string): Promise<string> => {
-      if (ctx.hasUI && !live) { const r = await ctx.ui.select(title, options); return r ?? fallback; }
+      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");
@@ -934,7 +1066,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, cwd, ctx, settings, model: models[style], meter, sessionDir, src: sessionFile, signal, live, onProgress: (p) => { Object.assign(slot, p); push(); } });
+        const r = await runAttempt({ state, style, n, dir, cwd, pick, 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) };
       }));
@@ -1017,7 +1149,7 @@ export default function loopsExtension(pi: Pi): void {
         else judge.why = `${judge.why} (your pick ${live.pick} was not a passing attempt)`;
         live.pick = null;
       }
-      if (ctx.hasUI && !live && takeable.length) {
+      if (hasUI && !live && takeable.length) {
         for (;;) {
           const others = takeable.filter((a) => a.label !== judge.pick);
           const opts = [`Keep ${judge.pick}${judge.pick === "CURRENT" ? " (nothing beat it)" : " (judge's pick)"}`, ...others.map((a) => `Take ${a.label} instead`), ...valid.map((a) => `Show ${a.label}'s diff`), ...valid.filter((a) => a.session).map((a) => `Open ${a.label}'s session after the run`)];
@@ -1046,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}`);
     }
@@ -1053,17 +1193,28 @@ 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?.({
     name: "loop", exposure: "model-only", executionMode: "sequential",
-    promptSnippet: "run hill-climbing rounds: three forked attempts in git worktrees, a judge keeps the best", annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    promptSnippet: "run hill-climbing rounds: three forked attempts in git worktrees, a judge keeps the best",
+    promptGuidelines: [
+      "When the ask is comparative — make this faster, improve this, which of these is better — prefer `loop` over editing by hand: it forks attempts into their own worktrees and a judge keeps the best, and your checkout is untouched until `loop_apply`.",
+      "Give a `loop` round a `bench` when a number can be measured, and `routes` when the goal is what a page looks like; without either it is judged on the diffs.",
+    ], 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.",
@@ -1083,12 +1234,13 @@ export default function loopsExtension(pi: Pi): void {
         if (!choice?.startsWith("Approve")) return notRun("discuss", "Not run. Discuss the spec with me in chat (what is unclear, what should be different), then call loop again when we agree.");
       }
       if (!ctx.hasUI || params.wait) return run(params, signal, onUpdate, ctx, null);
+      const ui = ctx.ui; // the object, held by value: the ctx getter throws once the session is replaced
       const live: any = { id: null, state: null, details: null, cwd: ctx.cwd, attempts: new Map(), pick: null, last: null, error: null, ctrl: new AbortController(), startedAt: Date.now() };
       const started = new Promise((resolve) => { live.started = resolve; });
       live.promise = run(params, live.ctrl.signal, (u) => { live.last = u; }, ctx, live).then(
         (r) => { try { pi.sendUserMessage?.(r.content, { deliverAs: "followUp" }); } catch {} },
         (e) => { live.error = e; if (live.id) { try { pi.sendUserMessage?.(`Loop ${live.id} failed: ${e.message}`, { deliverAs: "followUp" }); } catch {} } }
-      ).finally(() => { if (live.id) RUNS.delete(live.id); live.started?.(); try { ctx.ui.setStatus?.("loops", undefined); } catch {} });
+      ).finally(() => { if (live.id) RUNS.delete(live.id); live.started?.(); try { ui.setStatus?.("loops", undefined); } catch {} });
       await started;
       if (!live.id) throw live.error ?? new Error("the loop did not start");
       RUNS.set(live.id, live);
@@ -1123,13 +1275,13 @@ export default function loopsExtension(pi: Pi): void {
     } });
   pi.registerTool?.({ name: "loop_status", promptSnippet: "progress of a loop round running in the background", outputSchema: StatusResult, 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, structuredContent: { run: r.id, phase: String(r.details?.phase ?? "starting") } }; } });
-  pi.registerTool?.({ name: "loop_talk", promptSnippet: "tell a running attempt something", 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 }),
+  pi.registerTool?.({ name: "loop_talk", promptSnippet: "tell a running attempt something", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, 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", promptSnippet: "add a rule a running loop must follow", 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", promptSnippet: "keep a specific attempt as the winner yourself", 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", promptSnippet: "take a run's best into the checkout (tracked files only)", outputSchema: ApplyResult, 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 }),
+  pi.registerTool?.({ name: "loop_apply", promptSnippet: "take a run's best into the checkout (tracked files only)", outputSchema: ApplyResult, executionMode: "sequential", promptGuidelines: ["`loop_apply` takes the winner's changed *tracked* files as one commit; files it added or deleted are listed, not applied — copy those yourself if the round needs them."], 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);
@@ -1142,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.4",
+  "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": "*",