pi-bro 0.29.0 → 0.31.0

package/src/overthink-state.ts

@@ -0,0 +1,204 @@
+/** Small private Overthink settings and session entries; custom entries never enter LLM context. */
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "./util.ts";
+
+export const OVERTHINK_ENTRY = "bro-overthink";
+export const OVERTHINK_DEFAULTS_FILE = "bro-overthink-defaults.json";
+export const FACTORY_QUESTIONS = [
+  "Are we going in the right direction?",
+  "Where are we now, where do we want to be, and where are we actually going?",
+  "Are we solving the real problem, or just completing the tasks in front of us?",
+  "What are we taking for granted that might be wrong?",
+  "What important risks or failure modes are we overlooking?",
+  "Have we drifted from the original intent or added complexity without enough value?",
+  "What is the most useful correction or next move we can make now?",
+] as const;
+
+export const MAX_OVERTHINK_QUESTIONS = 32;
+export const MAX_OVERTHINK_QUESTION_CHARS = 500;
+const MAX_NOTE_CHARS = 8000;
+export type OverthinkUsage = { cacheRead?: number; cacheWrite?: number; input?: number; output?: number; reasoning?: number; costTotal?: number };
+export type OverthinkNote = {
+  text: string; checkedAt: string; model: string; questionKey: string;
+  /** Last model-relevant session entry at the time of the assessment. */
+  sourcePosition?: string;
+  usage?: OverthinkUsage;
+};
+export type OverthinkSession = { questions?: string[]; note?: OverthinkNote; initialized: boolean };
+
+export function checkQuestions(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length > MAX_OVERTHINK_QUESTIONS) {
+    throw new Error("Overthink allows at most 32 questions.");
+  }
+  const questions = value.map((item: unknown) => {
+    if (typeof item !== "string" || !item.trim() || item.length > MAX_OVERTHINK_QUESTION_CHARS || /[\r\n\u0000-\u001f]/.test(item)) {
+      throw new Error("Each question must be a single nonempty line of at most 500 characters.");
+    }
+    return item.trim();
+  });
+  return questions;
+}
+
+export function questionKey(questions: readonly string[]): string { return JSON.stringify(questions); }
+
+/**
+ * Session location represented by an assessment. Ignore Bro's custom entries
+ * so recording a note or editing questions does not itself make the note stale.
+ * Content edits and compaction count: they can change what the model sees.
+ */
+export function overthinkContextPosition(branch: readonly SessionEntry[]): string | undefined {
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i]!;
+    if (entry.type === "message" || entry.type === "custom_message" ||
+        entry.type === "context_edit" || entry.type === "compaction" || entry.type === "branch_summary") {
+      return entry.id;
+    }
+  }
+  return undefined;
+}
+
+export function overthinkIsStale(note: OverthinkNote | undefined, position: string | undefined): boolean {
+  return Boolean(note && (!note.sourcePosition || note.sourcePosition !== position));
+}
+
+
+export function resolveOverthinkSession(branch: readonly SessionEntry[]): OverthinkSession {
+  const state: OverthinkSession = { initialized: false };
+  for (const entry of branch) {
+    if (entry.type !== "custom" || entry.customType !== OVERTHINK_ENTRY || !isRecord(entry.data) || entry.data.version !== 1) continue;
+    if (entry.data.kind === "questions") {
+      try { state.questions = checkQuestions(entry.data.questions); state.initialized = true; }
+      catch { /* Ignore damaged historical records without granting them authority. */ }
+    } else if (entry.data.kind === "note") {
+      const data = entry.data;
+      if (typeof data.text === "string" && data.text.length <= MAX_NOTE_CHARS &&
+          typeof data.checkedAt === "string" && typeof data.model === "string" &&
+          typeof data.questionKey === "string") {
+        const note: OverthinkNote = {
+          text: data.text, checkedAt: data.checkedAt, model: data.model, questionKey: data.questionKey,
+          ...(typeof data.sourcePosition === "string" && data.sourcePosition ? { sourcePosition: data.sourcePosition } : {}),
+        };
+        if (isRecord(data.usage)) {
+          const usage: OverthinkUsage = {};
+          for (const key of ["cacheRead", "cacheWrite", "input", "output", "reasoning", "costTotal"] as const) {
+            const val = data.usage[key];
+            if (typeof val === "number" && Number.isFinite(val) && val >= 0) usage[key] = val;
+          }
+          note.usage = usage;
+        }
+        state.note = note;
+      }
+    }
+  }
+  return state;
+}
+
+export function globalQuestionsFile(dir = getAgentDir()): string {
+  return join(dir, OVERTHINK_DEFAULTS_FILE);
+}
+export type OverthinkGlobal = { questions: string[]; automatic: boolean };
+/** Missing flag defaults to on, including files written before the on/off switch existed. */
+export async function readGlobalOverthink(dir = getAgentDir()): Promise<OverthinkGlobal> {
+  const file = globalQuestionsFile(dir);
+  let info;
+  try { info = await lstat(file); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { questions: [...FACTORY_QUESTIONS], automatic: true };
+    throw error;
+  }
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 32768) throw new Error("Unsafe or oversized Overthink defaults file: " + file);
+  const data = JSON.parse(await readFile(file, "utf8")) as unknown;
+  if (!isRecord(data) || data.version !== 1 ||
+      (data.automatic !== undefined && typeof data.automatic !== "boolean")) {
+    throw new Error("Unsupported Overthink defaults format: " + file);
+  }
+  return { questions: checkQuestions(data.questions), automatic: data.automatic ?? true };
+}
+
+export async function readGlobalQuestions(dir = getAgentDir()): Promise<string[]> {
+  return (await readGlobalOverthink(dir)).questions;
+}
+export async function readAutomaticChecks(dir = getAgentDir()): Promise<boolean> {
+  return (await readGlobalOverthink(dir)).automatic;
+}
+
+async function writeGlobalOverthink(settings: OverthinkGlobal, dir = getAgentDir()): Promise<void> {
+  const cleaned = checkQuestions([...settings.questions]);
+  if (typeof settings.automatic !== "boolean") throw new Error("Automatic checks must be on or off.");
+  await mkdir(dir, { recursive: true });
+  const file = globalQuestionsFile(dir);
+  try {
+    const info = await lstat(file);
+    if (!info.isFile() || info.isSymbolicLink()) throw new Error("Unsafe Overthink defaults file: " + file);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const temp = file + "." + randomUUID() + ".tmp";
+  try {
+    await writeFile(temp, JSON.stringify({ version: 1, questions: cleaned, automatic: settings.automatic }, null, 2) + "\n", {
+      encoding: "utf8", mode: 0o600, flag: "wx", flush: true,
+    });
+    await rename(temp, file);
+  } finally { await rm(temp, { force: true }).catch(() => undefined); }
+}
+
+export async function writeGlobalQuestions(questions: readonly string[], dir = getAgentDir()): Promise<void> {
+  const previous = await readGlobalOverthink(dir);
+  await writeGlobalOverthink({ ...previous, questions: checkQuestions([...questions]) }, dir);
+}
+export async function writeAutomaticChecks(automatic: boolean, dir = getAgentDir()): Promise<void> {
+  const previous = await readGlobalOverthink(dir);
+  await writeGlobalOverthink({ ...previous, automatic }, dir);
+}
+
+export async function ensureOverthinkSession(pi: ExtensionAPI, branch: readonly SessionEntry[]): Promise<OverthinkSession> {
+  const current = resolveOverthinkSession(branch);
+  if (current.initialized) return current;
+  const questions = await readGlobalQuestions();
+  pi.appendEntry(OVERTHINK_ENTRY, { version: 1, kind: "questions", questions });
+  return { ...current, initialized: true, questions };
+}
+
+export function saveSessionQuestions(pi: ExtensionAPI, questions: readonly string[]): void {
+  pi.appendEntry(OVERTHINK_ENTRY, { version: 1, kind: "questions", questions: checkQuestions([...questions]) });
+}
+export function saveOverthinkNote(pi: ExtensionAPI, note: OverthinkNote): void {
+  pi.appendEntry(OVERTHINK_ENTRY, { version: 1, kind: "note", ...note });
+}
+
+export function overthinkPrompt(questions: readonly string[]): string {
+  return [
+    "[Bro Overthink: private second look]",
+    "Reassess the current work using the preceding Pi conversation as evidence. Consider these user-written questions:",
+    ...questions.map((q, i) => String(i + 1) + ". " + q),
+    "Find only material points that could change the next decision or the quality of the work.",
+    "Prefer direction, assumptions, evidence, risks, coherence, and the next useful move. Do not fabricate problems, demand checks for hypothetical edge cases, or restate concerns already clear in the last assistant reply.",
+    "Write in the user's language. Keep it short: at most three specific findings with evidence and a useful next move. Answer in plain text only; do not call tools or take actions. No mandatory template or question-by-question answers.",
+    "When nothing material is worth bringing up, return exactly NONE.",
+  ].join("\n");
+}
+export function parseOverthinkAnswer(text: string): string {
+  const cleaned = text.replace(/\u001b\[[0-9;]*m/g, "").trim();
+  if (/^none\.?$/i.test(cleaned)) return "";
+  return cleaned.slice(0, MAX_NOTE_CHARS);
+}
+
+/** Only use provider-reported values; absence means unknown, never zero. */
+export function readOverthinkUsage(raw: unknown): OverthinkUsage | undefined {
+  if (!isRecord(raw)) return undefined;
+  const usage: OverthinkUsage = {};
+  const fields = { cacheRead: ["cacheReadTokens", "cacheRead"], cacheWrite: ["cacheWriteTokens", "cacheWrite"], input: ["inputTokens", "input"], output: ["outputTokens", "output"], reasoning: ["reasoningTokens", "reasoning"] } as const;
+  for (const key of Object.keys(fields) as (keyof typeof fields)[]) {
+    for (const field of fields[key]) {
+      const value = raw[field];
+      if (typeof value === "number" && Number.isFinite(value) && value >= 0) { usage[key] = value; break; }
+    }
+  }
+  if (isRecord(raw.cost) && typeof raw.cost.total === "number" && Number.isFinite(raw.cost.total) && raw.cost.total >= 0) {
+    usage.costTotal = raw.cost.total;
+  }
+  return Object.keys(usage).length ? usage : undefined;
+}

package/src/overthink.ts

@@ -0,0 +1,323 @@
+/** Automatic same-model second look. No separate CLI, agent or model override. */
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { convertToLlm, copyToClipboard } from "@earendil-works/pi-coding-agent";
+import { normalizeContext } from "@earendil-works/pi-ai";
+import { matchesKey, wrapTextWithAnsi, type Component, type TUI } from "@earendil-works/pi-tui";
+import { modalHeight, openBroOverlay, renderFrame, Scroller, formatNotice, type Theme } from "./modal-kit.ts";
+import { hasBroCustomUi } from "./ui-capabilities.ts";
+import {
+  FACTORY_QUESTIONS, ensureOverthinkSession, overthinkPrompt, parseOverthinkAnswer,
+  questionKey, readAutomaticChecks, readGlobalQuestions, readOverthinkUsage, resolveOverthinkSession,
+  overthinkContextPosition, overthinkIsStale,
+  saveOverthinkNote, saveSessionQuestions, writeGlobalQuestions,
+  type OverthinkNote,
+} from "./overthink-state.ts";
+import { openOverthinkQuestionEditor } from "./overthink-questions-ui.ts";
+import { errorMessage } from "./util.ts";
+
+const MIN_TOOL_RESULTS = 3;
+const WIDGET = "bro-overthink";
+const NOTE_TIMEOUT_MS = 90_000;
+
+type ViewerAction = "close" | "edit";
+type CheckResult = OverthinkNote;
+type CheckContext = ExtensionContext | ExtensionCommandContext;
+
+export type OverthinkRunEvidence = { toolResults: number; normalFinish: boolean };
+/** Collect evidence at each agent_end, but never start a check until agent_settled. */
+export function accumulateOverthinkEvidence(
+  prior: OverthinkRunEvidence | undefined,
+  event: { messages: readonly { role: string; stopReason?: string }[] },
+): OverthinkRunEvidence {
+  const last = event.messages.at(-1);
+  return {
+    toolResults: (prior?.toolResults ?? 0) + event.messages.filter(m => m.role === "toolResult").length,
+    normalFinish: last?.role === "assistant" && last.stopReason === "stop",
+  };
+}
+
+export function overthinkReady(evidence: OverthinkRunEvidence | undefined, aborted: boolean, pending: boolean): boolean {
+  return !aborted && !pending && Boolean(evidence?.normalFinish && evidence.toolResults >= MIN_TOOL_RESULTS);
+}
+
+
+function noteWidget(ctx: CheckContext, note?: string): void {
+  if (ctx.mode !== "tui") return;
+  ctx.ui.setWidget(WIDGET, note
+    ? (_tui, theme) => ({
+        invalidate() {},
+        render(width: number) {
+          const label = "◇ Overthink: ";
+          const lines = wrapTextWithAnsi(note.replace(/\s+/g, " "), Math.max(12, width - label.length - 2)).slice(0, 3);
+          return ["", ...lines.map((line, index) =>
+            (index === 0 ? theme.fg("warning", label) : " ".repeat(label.length)) + theme.fg("muted", line)
+          ), theme.fg("dim", "  /bro overthink to view the private assessment")];
+        },
+      })
+    : undefined);
+}
+
+export function questionStatus(note: OverthinkNote | undefined, questions: string[], position?: string): string {
+  if (!note) return "No assessment yet.";
+  const changed = note.questionKey !== questionKey(questions) ? " · questions changed since check" : "";
+  const freshness = overthinkIsStale(note, position)
+    ? (note.sourcePosition ? " · OUTDATED: conversation has changed since this check" : " · source position not recorded")
+    : " · current for this session position";
+  return "Checked: " + note.checkedAt + " · " + note.model + freshness + changed;
+}
+
+/** A reported zero may mean a miss OR a provider that does not support cache accounting. */
+export function usageStatus(note: OverthinkNote | undefined): string[] {
+  const u = note?.usage;
+  if (!u) return ["Cost/usage: not reported by provider."];
+  const totals = [
+    u.input !== undefined ? "input " + u.input.toLocaleString("en-US") : undefined,
+    u.cacheRead !== undefined ? "cache read " + u.cacheRead.toLocaleString("en-US") : undefined,
+    u.cacheWrite !== undefined ? "cache write " + u.cacheWrite.toLocaleString("en-US") : undefined,
+    u.output !== undefined ? "output " + u.output.toLocaleString("en-US") : undefined,
+    u.reasoning !== undefined ? "reasoning " + u.reasoning.toLocaleString("en-US") : undefined,
+  ].filter((value): value is string => value !== undefined);
+  const cost = u.costTotal !== undefined ? " · est. cost $" + u.costTotal.toFixed(6) + " (Pi price table; not billed amount)" : "";
+  return [
+    "Provider-reported tokens: " + (totals.length ? totals.join(" · ") : "token counts unavailable") + cost,
+    ...(u.cacheRead === 0 ? ["Cache read 0 can mean no hit or caching unsupported."] : []),
+  ];
+}
+
+export function createOverthinkViewer(
+  read: () => { questions: string[]; note?: OverthinkNote; position?: string },
+  retry: () => Promise<CheckResult>,
+) {
+  return (tui: TUI, theme: Theme, _keys: unknown, done: (action: ViewerAction) => void): Component => {
+    let help = false;
+    let busy = false;
+    let closed = false;
+    let notice = "";
+    const scroller = new Scroller(() => tui.requestRender());
+    const copy = async () => {
+      const note = read().note;
+      if (!note?.text) { notice = formatNotice(theme, "Nothing to copy yet.", "warning"); tui.requestRender(); return; }
+      try { await copyToClipboard(note.text); notice = formatNotice(theme, "Assessment copied.", "success"); }
+      catch (error) { notice = formatNotice(theme, "Copy failed: " + errorMessage(error), "error"); }
+      tui.requestRender();
+    };
+    const rerun = async () => {
+      if (busy || closed) return;
+      busy = true; notice = ""; tui.requestRender();
+      try {
+        const result = await retry();
+        if (!closed) { scroller.toStart(); notice = formatNotice(theme, result.text ? "Assessment refreshed." : "No material concerns found.", "success"); }
+      } catch (error) {
+        if (!closed) notice = formatNotice(theme, "Retry failed: " + errorMessage(error), "error");
+      } finally { busy = false; if (!closed) tui.requestRender(); }
+    };
+    return {
+      render(width: number) {
+        const { questions, note, position } = read();
+        const inner = Math.max(1, width - 2);
+        const body = help
+          ? [
+              "Overthink checks substantive Pi tasks automatically with the active session model.",
+              "Results are private and never enter the main conversation.",
+              "",
+              "Ctrl+R  Force a fresh check (even after a small task)",
+              "Ctrl+E  Edit this session's questions",
+              "?       Toggle help",
+              "Ctrl+C  Copy latest findings",
+              "Esc     Close / back from help",
+              "",
+              "No separate backend or model picker. Cached input is measured when the provider reports it.",
+            ]
+          : [
+              questionStatus(note, questions, position),
+              "Questions: " + questions.length + (questions.length ? "" : " (checks disabled)"),
+              ...usageStatus(note),
+              "",
+              busy ? "Checking the current Pi session…" : note
+                ? note.text || "No material concerns found in the last check."
+                : "No assessment yet. Bro checks automatically after meaningful work. Ctrl+R forces one now.",
+            ];
+        const lines = body.flatMap(line => wrapTextWithAnsi(line, inner));
+        return renderFrame(theme, width, modalHeight(tui), {
+          header: () => theme.fg("accent", theme.bold("Bro · Overthink")) + (busy ? " · running" : ""),
+          body: (rows) => scroller.view(lines, rows),
+          notice,
+          hints: "↑/↓ scroll · Ctrl+R retry · Ctrl+E session questions · ? help · Ctrl+C copy · Esc close",
+        });
+      },
+      invalidate() {},
+      handleInput(data: string) {
+        if (matchesKey(data, "escape")) {
+          if (help) { help = false; scroller.toStart(); tui.requestRender(); }
+          else { closed = true; done("close"); }
+          return;
+        }
+        if (matchesKey(data, "?")) { help = !help; scroller.toStart(); tui.requestRender(); return; }
+        if (matchesKey(data, "ctrl+r")) { void rerun(); return; }
+        if (matchesKey(data, "ctrl+c")) { void copy(); return; }
+        if (matchesKey(data, "ctrl+e") && !busy) { closed = true; done("edit"); return; }
+        scroller.handleKey(data);
+      },
+    };
+  };
+}
+
+export async function openOverthinkDefaults(ctx: ExtensionCommandContext): Promise<void> {
+  const current = await readGlobalQuestions();
+  await openOverthinkQuestionEditor(ctx, {
+    title: "Bro · Overthink / Default questions",
+    questions: current,
+    reset: async () => [...FACTORY_QUESTIONS],
+    save: writeGlobalQuestions,
+  });
+}
+
+export function registerOverthink(pi: ExtensionAPI, loadAutomaticChecks = readAutomaticChecks): {
+  open(ctx: ExtensionCommandContext): Promise<void>;
+} {
+  let active: AbortController | undefined;
+  let generation = 0;
+  let evidence: OverthinkRunEvidence | undefined;
+  const invalidate = (_event: unknown, ctx: ExtensionContext) => {
+    generation++;
+    evidence = undefined;
+    active?.abort(); active = undefined;
+    noteWidget(ctx);
+  };
+
+  // The first session event locks its question defaults; subsequent branch/fork views
+  // inherit the nearest private custom entry rather than sharing a project setting.
+  pi.on("session_start", async (_event, ctx) => {
+    invalidate(_event, ctx);
+    try { await ensureOverthinkSession(pi, ctx.sessionManager.getBranch()); }
+    catch (error) { if (ctx.mode === "tui") ctx.ui.notify("Overthink settings: " + errorMessage(error), "warning"); }
+  });
+  pi.on("session_tree", invalidate);
+  pi.on("agent_start", (_event, ctx) => {
+    // A continuation or retry can begin a new agent loop before the overall
+    // run settles. Cancel in-flight checks and stale scheduling, but keep the
+    // tool evidence until agent_settled decides whether the full run qualifies.
+    generation++;
+    active?.abort(); active = undefined;
+    noteWidget(ctx);
+  });
+  pi.on("session_shutdown", async (_event, ctx) => { invalidate(_event, ctx); });
+
+  type Trigger = { generation: number; sessionId: string; position?: string };
+  const run = async (ctx: CheckContext, forced: boolean, trigger?: Trigger): Promise<CheckResult> => {
+    if (!ctx.model) throw new Error("No active Pi model; Overthink cannot choose a different one.");
+    const marker = trigger?.generation ?? generation;
+    const sessionId = trigger?.sessionId ?? ctx.sessionManager.getSessionId();
+    const position = trigger?.position ?? overthinkContextPosition(ctx.sessionManager.getBranch());
+    const stillCurrent = () => marker === generation &&
+      sessionId === ctx.sessionManager.getSessionId() &&
+      position === overthinkContextPosition(ctx.sessionManager.getBranch());
+    if (!stillCurrent()) throw new Error("Session moved before assessment could start.");
+    const state = await ensureOverthinkSession(pi, ctx.sessionManager.getBranch());
+    const questions = state.questions ?? [];
+    if (!questions.length) throw new Error("No Overthink questions. Edit session questions to enable checks.");
+    if (!stillCurrent()) throw new Error("Session changed; assessment cancelled.");
+
+    const projected = ctx.sessionManager.buildSessionProjection().messages;
+    if (!projected.length && forced) throw new Error("Nothing in the current conversation to assess.");
+    if (!projected.length) throw new Error("No conversation to assess.");
+
+    active?.abort();
+    const controller = new AbortController();
+    active = controller;
+    const model = ctx.model;
+    const name = model.provider + "/" + model.id;
+    const effort = pi.getThinkingLevel();
+    const ask = { role: "user" as const, content: [{ type: "text" as const, text: overthinkPrompt(questions) }], timestamp: Date.now() };
+    const timer = setTimeout(() => controller.abort(), NOTE_TIMEOUT_MS);
+    try {
+      // The exact projected message prefix is the basis of provider cache reuse.
+      // No second agent session, generated summary, extra tools or backend override.
+      const answer = await ctx.modelRegistry.streamSimple(
+        model,
+        normalizeContext({ messages: convertToLlm([...projected, ask]) }),
+        {
+          reasoning: model.reasoning && effort !== "off" ? effort : undefined,
+          maxTokens: 2200,
+          sessionId: sessionId ?? undefined,
+          signal: controller.signal,
+        },
+      ).result();
+      if (controller.signal.aborted) throw new Error("Assessment cancelled or timed out.");
+      if (!stillCurrent() ||
+          ctx.model?.provider !== model.provider || ctx.model?.id !== model.id ||
+          active !== controller) throw new Error("Session or model changed; stale result discarded.");
+      if (answer.stopReason !== "stop") throw new Error("Model did not finish its assessment (" + answer.stopReason + ").");
+      const currentQuestions = resolveOverthinkSession(ctx.sessionManager.getBranch()).questions ?? [];
+      if (questionKey(currentQuestions) !== questionKey(questions)) throw new Error("Questions changed during check; stale result discarded.");
+      const text = parseOverthinkAnswer(answer.content.filter(part => part.type === "text").map(part => part.text).join(""));
+      const usage = readOverthinkUsage(answer.usage);
+      const note: OverthinkNote = {
+        text, checkedAt: new Date().toISOString(), model: name, questionKey: questionKey(questions),
+        ...(position ? { sourcePosition: position } : {}),
+        ...(usage ? { usage } : {}),
+      };
+      saveOverthinkNote(pi, note);
+      noteWidget(ctx, text);
+      return note;
+    } finally {
+      clearTimeout(timer);
+      if (active === controller) active = undefined;
+    }
+  };
+
+  pi.on("agent_end", (event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    evidence = accumulateOverthinkEvidence(evidence, event);
+  });
+
+  // agent_end is not guaranteed to mean Pi has finished continuation, retry or
+  // compaction. agent_settled is available in Pi >=1.3, our supported floor.
+  pi.on("agent_settled", (event, ctx) => {
+    const completed = evidence;
+    evidence = undefined;
+    if (ctx.mode !== "tui" || !ctx.model ||
+        !overthinkReady(completed, event.aborted, ctx.hasPendingMessages())) return;
+    // Capture BEFORE the asynchronous settings read. A new run, fork or
+    // compaction must not turn an older settlement into a request for new work.
+    const trigger = {
+      generation, sessionId: ctx.sessionManager.getSessionId(),
+      position: overthinkContextPosition(ctx.sessionManager.getBranch()),
+    };
+    void (async () => {
+      if (!(await loadAutomaticChecks())) return;
+      if (trigger.generation !== generation ||
+          trigger.sessionId !== ctx.sessionManager.getSessionId() ||
+          trigger.position !== overthinkContextPosition(ctx.sessionManager.getBranch()) ||
+          ctx.hasPendingMessages()) return;
+      await run(ctx, false, trigger);
+    })().catch(() => undefined); // Optional review must never fail the main task.
+  });
+
+  const open = async (ctx: ExtensionCommandContext): Promise<void> => {
+    if (!hasBroCustomUi(ctx)) {
+      ctx.ui.notify("Use /bro overthink in Pi's interactive UI.", "warning");
+      return;
+    }
+    await ensureOverthinkSession(pi, ctx.sessionManager.getBranch());
+    for (;;) {
+      const action = await openBroOverlay<ViewerAction>(ctx, createOverthinkViewer(
+        () => {
+          const state = resolveOverthinkSession(ctx.sessionManager.getBranch());
+          return { questions: state.questions ?? [], note: state.note,
+            position: overthinkContextPosition(ctx.sessionManager.getBranch()) };
+        },
+        () => run(ctx, true),
+      ));
+      if (action !== "edit") return;
+      const state = resolveOverthinkSession(ctx.sessionManager.getBranch());
+      await openOverthinkQuestionEditor(ctx, {
+        title: "Bro · Overthink / Session questions",
+        questions: state.questions ?? [],
+        reset: readGlobalQuestions,
+        save: (questions) => saveSessionQuestions(pi, questions),
+      });
+    }
+  };
+  return { open };
+}