pi-bro 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.31.0] - 2026-11-07
+
+### Added
+
+- Automatic Overthink second-look notes after fully settled substantive Pi work (after retry, compaction and queued continuations), using the active model, thinking level and current session projection to allow prompt-cache reuse.
+- `/bro overthink` private notes viewer with force retry, help, copy and session-question editing.
+- Session-position markers label older notes OUTDATED after later work or branch movement; a generation check prevents a stale automatic-settings read from scheduling a check for newer work.
+- One editable question-list UI for global defaults (`/bro config → Features → Overthink`) and independent per-session question snapshots. Reset global to factory and session to global; store latest notes as session-only custom entries.
+
+### Limits
+
+- Same-model criticism is not an independent review. Automatic checks start on; Features → Overthink can turn them off while keeping manual retry. Usage and cost are shown only when reported by the provider; high-effort reasoning can still be expensive. The second request retains Pi's context, which may include tool descriptions, but does not execute tools. Actual cache reuse and billable savings require live verification. Full TUI and PiG qualification still require real sessions.
+
 ## [0.30.0] - 2026-11-06
 
 ### Added

package/README.md

@@ -51,6 +51,7 @@ For a first success, type this in Pi after setting up a backend:
 | `/bro show` | Draws the current session's recent conversation, if any |
 | `/bro architecture` | Creates or refreshes `docs/architecture/` for this project |
 | `/bro grill-me Should agents talk freely to each other?` | Questions your assumptions privately, one at a time |
+| `/bro overthink` | Views private automatic second-look notes; Ctrl+R forces a new check |
 | `/bro elevate Improve how we search company documents` | Find expert gaps before giving Pi a task |
 
 File and webpage examples need your own real path or URL; see [how to explain them](docs/features/explain.md#explain-a-document). For a step-by-step first run, see [Getting started](docs/getting-started.md).
@@ -64,6 +65,7 @@ File and webpage examples need your own real path or URL; see [how to explain th
 | `/bro architecture [focus]` | **[Architecture Docs](docs/features/architecture.md).** Inspects the project and writes Markdown, diagrams and an offline interactive `architecture.html` under `docs/architecture/`. Uses BTW model settings. |
 | `/bro elevate` or **Ctrl+Shift+E** | **[Elevate](docs/elevate.md).** Discover missing expert considerations, select useful improvements, and rewrite your task without submitting it. Shares BTW backend settings. |
 | `/bro remember-me [thought]` | **[Remember Me](docs/remember-me.md).** Privately clarify and approve short personal memories with unfoldable background. Agents can call `about_user` to read summaries and expand IDs. |
+| `/bro overthink` | **[Overthink](docs/overthink.md).** Quietly checks meaningful work with the active Pi model, using editable global/session questions and a private notes modal. Automatic checks can be switched off in config. No separate backend. |
 | `/bro grill-me` | **[Grill Me](docs/grill-me.md) (experimental).** A private, opinionated decision interview: light, balanced or exhaustive; one question per round; `/consolidate` drafts a brief without ending the interview; `/insert-last-message` explicitly returns the latest reply to the editor. Uses BTW model settings; read-only restrictions vary by backend. |
 | `/bro btw` | **[Side questions](docs/features/btw.md#bro-btw-side-conversation).** A separate conversation seeded with recent context, so you can ask without interrupting the agent. ⚠️ [Full-permission mode](#what-leaves-your-machine) can edit files. |
 | `/bro guided-review <PR>` | **[Guided Review](docs/guided-review.md).** An explanation and quality assessment of a GitHub PR, with ranked findings, source evidence and private questions. Claude, Muse, or Pi is recommended for untrusted PRs. |
@@ -77,7 +79,7 @@ Guided Review has its own [guide](docs/guided-review.md).
 
 ## Requirements
 
-- Pi `>=1.3.0` and Node.js `>=22.19.0`.
+- Pi `>=1.3.0` and Node.js `>=22.19.0`. Overthink always uses the host Pi model, independently of Bro's backend configuration.
 - macOS or Linux. Windows is untested; there, cancelling stops only the
   backend's direct process, not anything it started.
 - At least one backend on your `PATH`, signed in once from your terminal, **or the built-in Pi backend**. You only need the one you use:
@@ -108,6 +110,7 @@ which may keep it under their own policies. Paths below are under
 | Show | User and assistant text from recent turns (no tool calls, tool results, reasoning or images), plus your preferences | Diagram pages in `pi-bro-<uid>/` in your system temp folder |
 | Side questions | Your questions and up to the last 8 turns of conversation text, plus your preferences | Nothing; the thread stays in memory |
 | Grill Me | Topic, interview turns, up to the last 8 main-session text turns and preferences; any workspace files the selected inspector reads | Nothing; interview and brief are in memory |
+| Overthink | Current session projection, including tool evidence, plus private user-editable questions, to the active Pi provider | Global questions in `bro-overthink-defaults.json`; per-session questions and latest private note in Pi session custom entries |
 | Elevate | Your objective, selected findings, all current-branch user/assistant text; Full also includes tool-call arguments and text results, and preferences | Nothing; the workflow stays in memory |
 | Guided Review | The PR description and diff, the files the backend reads, your questions, plus your preferences | Reviews and captured source in `bro-reviews/`, with no automatic cleanup |
 | Advisor | The agent's system instructions, tool list and whole conversation, including tool calls and results (reasoning and images omitted), plus your steering | Steering in `bro-advisor.md` and the session file |

package/THIRD_PARTY_NOTICES.md

@@ -26,6 +26,34 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+## pi-heads-up
+
+The automatic same-model follow-up request and private note UI in Overthink are adapted from
+[pi-heads-up](https://github.com/Pringled/pi-extensions/tree/main/packages/pi-heads-up),
+copyright (c) 2026 Thomas van Dongen, licensed under the MIT License:
+
+MIT License
+
+Copyright (c) 2026 Thomas van Dongen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 ## Speak like you eat
 
 The prompt benchmark fixtures and mechanical checks are adapted from

package/docs/README.md

@@ -15,6 +15,7 @@ Start with what you want to do. The [README](../README.md) explains the product,
 - [Document a repository's architecture](features/architecture.md) — create or refresh Markdown, diagrams and an offline HTML map.
 - [Ask a private side question](features/btw.md#bro-btw-side-conversation) — BTW.
 - [Remember personal context for agents](remember-me.md) — approved short memories, expandable background and the read-only `about_user` tool.
+- [Review work quietly with Overthink](overthink.md) — automatic same-model second look with editable session questions.
 - [Get grilled on a decision](grill-me.md) — one question at a time in a private modal, then copy a decision brief.
 - [Improve a request before sending it](elevate.md) — Elevate: discover expert gaps, choose improvements, rewrite the task.
 - [Investigate a PR](guided-review.md) — Guided Review.

package/docs/overthink.md

@@ -0,0 +1,48 @@
+# Overthink — private second look
+
+Overthink gives Pi's work a small, skeptical second pass. It checks the direction, the assumptions, the risks and the next move, without making a new agent or interrupting the original conversation. It is inspired by [pi-heads-up](https://github.com/Pringled/pi-extensions/tree/main/packages/pi-heads-up).
+
+## Normal use
+
+With **automatic checks on** (the factory default), after a **fully settled substantial task** (currently at least three tool results across the run), Overthink sends one extra private assessment to the **same active Pi model, at the same thinking level**. A short note appears above the input only if there is something material to flag. If the reply already covered the issue, or there is nothing important to add, Overthink stays quiet. A question-only turn is not enough to trigger a check.
+
+Run `/bro overthink` to **view** the latest assessment. Opening the modal makes **no model request**. The notes never enter Pi's user/assistant conversation and do not direct the agent to perform work.
+
+In the modal:
+
+- **Ctrl+R** — force a fresh assessment (also works for smaller tasks). A check uses the **current** session context.
+- **Ctrl+E** — edit the questions for **this Pi session**.
+- **?** — show or hide help.
+- **Ctrl+C** — copy the latest findings.
+- **Esc** — close or leave Help.
+- **↑/↓** — scroll.
+
+If the last assessment found nothing, the modal says so. The note records the model-relevant session entry it assessed. When a later task (even a trivial turn), compaction, context edit, or branch move changes that position, the viewer explicitly marks the old note **OUTDATED**. Older notes without position metadata are marked **source position not recorded**. Editing questions also marks an existing note as using earlier questions.
+
+## Question editor
+
+The same ordered, editable list is used in both places:
+
+- **Global defaults:** `/bro config → Features → Overthink → Default questions`.
+- **Automatic checks:** `/bro config → Features → Overthink → Automatic checks` toggles the global on/off switch. It starts **On**. Turning it off does not delete questions or notes; the viewer and manual **Ctrl+R** still work.
+- **Session questions:** `/bro overthink`, then **Ctrl+E**.
+
+Use **↑/↓** to choose an entry; **Enter** to edit; **Ctrl+N** to add; **Ctrl+X** to delete; **Alt+↑/↓** to reorder; **Ctrl+S** to save; **Esc** to cancel. Saving an empty list disables checks. Unsaved changes are protected by a second-Esc warning.
+
+**Ctrl+D** twice resets the editor draft. In the global editor it restores Bro's factory questions; in the session editor it restores the **current global defaults**. Press Ctrl+S to save that reset. A new session inherits the current global defaults once and can then be edited independently. Existing sessions do not change when the global defaults are updated.
+
+## Model, cache and privacy
+
+Overthink **never** uses the BTW or Bro backend/model setting. It calls Pi's current `modelRegistry.streamSimple` using `buildSessionProjection()` plus a single appended private review instruction. It uses the active physical session model and reasoning level, makes **one call for all questions**, **never executes tools**, and does not add the assessment to the main model context. The request may still contain Pi's tool descriptions as part of the original context; the prompt tells the model to respond in text and not call tools. An unexpected tool-use response is treated as a failed check, not executed. The call sends the session context (including tool evidence exposed by Pi's projection) to that model's provider, under the provider's data policy.
+
+This largely preserves the request prefix and **can** reuse provider prompt-cache input. The benefit varies by provider, model, elapsed time, tool/context changes, other extensions' context hooks, and prompt-cache policy. It does not replicate every live Pi context modification. In Pi 1.3 and 1.5, `context_with_system` can observe a prepared context just before a provider call, while `before_provider_request` can observe a provider-specific payload; neither provides a portable, complete, settled-session request that can simply be appended and replayed through `streamSimple`. A recorded pre-call context also lacks the final agent response that Overthink needs to review. Bro therefore keeps the explicit projection path until a real provider-side comparison shows a safe improvement. **A cached prefix is not free:** high thinking effort can add substantial reasoning tokens on top of the visible-output limit, and both output and reasoning can cost money. The viewer shows *provider-reported* input, cache-read, cache-write, output and reasoning tokens when available. It labels USD cost separately as **estimated cost** from Pi's model price table, not a provider-billed amount; subscription or OAuth users may pay differently. A reported cache-read value of **0** could mean no hit **or unsupported caching**; it is not proof that caching works. Some providers report no usage fields. Check actual billed cost before treating Overthink as cheap.
+
+Overthink stores editable global defaults in `getAgentDir()/bro-overthink-defaults.json` and session questions plus the **latest** private check in Pi session `custom` entries (`bro-overthink`). Those entries are outside LLM prompts. Session forks inherit their branch's last state; later edits are independent. The viewer resolves only the **latest** note. Pi stores session custom entries by appending, so **each completed check adds another entry to the session file**, even though Bro does not provide a history browser or archive. This is a deliberate reuse of Pi's branch-aware persistence, not a claim that only one physical record exists. Keep this storage growth in mind for long sessions. It does not write to your project files.
+
+## Limits and verification
+
+- The second look is self-criticism by the **same** model; it is not an independent external review. Use `bro_advisor` when a genuinely separate view matters.
+- An automatic check can fail without an on-screen error; it must not disturb the main run. Force retry in the modal to see the error.
+- Automatic work is triggered at Pi's `agent_settled` lifecycle event (supported from Pi 1.3), not `agent_end`. The earlier event collects tool-use evidence; only a normal final settlement, without queued messages, may start the check. A new agent turn, model change, question edit or session navigation cancels or invalidates stale checks. A returned note is not proof that every listed concern is true.
+- Running Heads-up and Overthink together can cause **two extra calls** after a substantive turn. Disable one if that cost is not wanted.
+- Host events and cache accounting vary. See [manual qualification](TESTING.md) before claiming live TUI, PiG or cache-cost behavior.

package/docs/reference/commands.md

@@ -20,7 +20,7 @@ text directly captures a new source the same way.
 
 ## Default command suggestions
 
-Typing `/bro ` displays nine task-level suggestions: `simplify`, `show`, `btw`, `guided-review`, `architecture`, `elevate`, `grill-me`, `remember-me`, and `config`. Every other documented command remains callable and discoverable by typing its prefix (e.g., `/bro doc`).
+Typing `/bro ` displays ten task-level suggestions: `simplify`, `show`, `btw`, `guided-review`, `architecture`, `elevate`, `grill-me`, `remember-me`, `overthink`, and `config`. Every other documented command remains callable and discoverable by typing its prefix (e.g., `/bro doc`).
 
 ## Commands
 
@@ -37,11 +37,12 @@ Typing `/bro ` displays nine task-level suggestions: `simplify`, `show`, `btw`,
 | `/bro doctor` | Check Bro's settings, preferences, and each selected backend, with the effective backend/model/effort per feature. |
 | `/bro mode [brief\|balanced\|faithful]` | View or choose the explanation mode. |
 | `/bro preferences` | View or edit what Bro knows about you and how you like answers; see [Preferences](settings.md#preferences). |
-| `/bro config` | Open Global (defaults, preferences and Doctor) or Features (per-feature overrides, BTW inheritance and Advisor steering). |
+| `/bro config` | Open Global (defaults, preferences and Doctor) or Features (per-feature overrides, BTW inheritance, Overthink automatic checks/default questions and Advisor steering). |
 | `/bro architecture [focus]` | Read the current project and create or refresh `docs/architecture/` with Markdown, an editable graph and offline HTML. Inherits BTW backend settings. [Guide](../features/architecture.md). |
 | `/bro guided-review <PR number or URL>` | Automatically explain and assess a captured PR in local Pi, with source evidence and optional private questions. Opening the same PR restores its saved review. |
 | `/bro guided-review` | List saved reviews; `resume` is an alias. |
 | `/bro remember-me [thought]` | Start a private memory-writing conversation, browse and expand memories, and approve saves explicitly. [Guide](../remember-me.md). |
+| `/bro overthink` | View the latest private automatic second-look notes, without a model call. Ctrl+R retry, Ctrl+E edit session questions, ? help, Ctrl+C copy. [Guide](../overthink.md). |
 | `/bro grill-me [topic]` | Private one-question-at-a-time decision interview. Supply a topic to start fresh; omit it to resume. `/consolidate` drafts a brief; `/insert-last-message` inserts explicitly without sending. `/help` lists modal controls. [Guide](../grill-me.md). |
 | `/bro elevate [request]` | Improve an assignment before execution. Discover up to five gaps, choose useful findings, and insert a revised request without submitting it. **Ctrl+Shift+E** can use your unsent draft. See [Elevate](../elevate.md). |
 | `/bro btw [question]` | Open a side conversation in a modal, seeded with recent main-session context. Starts conversation-only; type `/mode` inside to toggle full permission (read and edit the workspace) without losing the thread. |

package/docs/reference/data-and-permissions.md

@@ -94,6 +94,8 @@ See [feature guide](../features/architecture.md).
 
 ## Privacy and safety
 
+- **Overthink requests:** after a substantive Pi turn, Bro makes one additional provider call using Pi's active model and current session conversation projection (including exposed tool evidence), appending the current session's questions. Overthink never executes tool calls. It may still send tool descriptions copied from Pi's existing context to support cache reuse; a tool-use response is rejected without executing the tool. The provider may retain input under its policy. Results and questions are stored in private Pi session custom entries, not LLM turns; global questions use `bro-overthink-defaults.json` in the agent home. This cannot promise a cache hit or fixed incremental cost. Features → Overthink has an on/off switch (on by default). The viewer displays provider-reported input/cache-read/cache-write/output/reasoning tokens and USD cost when available; a reported cache-read value of zero may mean either a cache miss or unsupported caching. See [Overthink](../overthink.md).
+
 - **External requests**: Bro sends the latest completed assistant response,
   pasted text, extracted document text, extracted webpage text, or recent
   session conversation text (tool calls, tool results, reasoning, and images

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "A sidekick for you and your Pi agent: plain-language explanations, side questions, diagrams, PR review and second opinions, without cluttering the agent's context.",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "show",
     "btw",
     "side-conversation",
+    "overthink",
     "advisor",
     "second-opinion",
     "codex",
@@ -51,6 +52,9 @@
     "src/elevate-engine.ts",
     "src/grill.ts",
     "src/grill-engine.ts",
+    "src/overthink.ts",
+    "src/overthink-state.ts",
+    "src/overthink-questions-ui.ts",
     "src/remember-store.ts",
     "src/remember-engine.ts",
     "src/remember-tool.ts",
@@ -84,6 +88,7 @@
     "docs/guided-review.md",
     "docs/elevate.md",
     "docs/grill-me.md",
+    "docs/overthink.md",
     "docs/remember-me.md",
     "docs/examples.md",
     "docs/features",
@@ -99,7 +104,7 @@
   "scripts": {
     "docs:check": "node scripts/check-docs.mjs && node --test test/docs-quality.test.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && npm run docs:check && node .github/scripts/release-utils.mjs selftest && node --test test/architecture.test.mjs test/architecture-review.test.mjs test/architecture-controller.test.mjs test/elevate-docs.test.mjs test/elevate.test.ts test/simplify.test.ts test/simplify-modal.test.mjs test/grill.test.ts test/config-navigation.test.ts test/config-navigation-modal.test.mjs test/remember.test.ts test/remember-modal.test.mjs test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts test/modal-contract.test.mjs benchmark/*.test.ts && sh ./test/smoke-test.sh",
+    "test": "npm run typecheck && npm run docs:check && node .github/scripts/release-utils.mjs selftest && node --test test/architecture.test.mjs test/architecture-review.test.mjs test/architecture-controller.test.mjs test/elevate-docs.test.mjs test/elevate.test.ts test/overthink.test.ts test/simplify.test.ts test/simplify-modal.test.mjs test/grill.test.ts test/config-navigation.test.ts test/config-navigation-modal.test.mjs test/remember.test.ts test/remember-modal.test.mjs test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts test/modal-contract.test.mjs benchmark/*.test.ts && sh ./test/smoke-test.sh",
     "benchmark:dry-run": "node benchmark/run.ts dry-run",
     "benchmark:run": "node benchmark/run.ts run",
     "benchmark:report": "node benchmark/run.ts report",

package/src/bro.ts

@@ -12,6 +12,7 @@ import { setPiHostContext } from "./backend.ts";
 import { openElevateModal } from "./elevate.ts";
 import { openArchitectureDocs } from "./architecture.ts";
 import { openGrillModal } from "./grill.ts";
+import { registerOverthink } from "./overthink.ts";
 import { openRememberModal } from "./remember.ts";
 import { openSimplifyWorkflow, type SimplifyState } from "./simplify-ui.ts";
 import { registerAboutUserTool } from "./remember-tool.ts";
@@ -68,6 +69,8 @@ export * from "./remember-engine.ts";
 export * from "./explain-modal.ts";
 export * from "./simplify-engine.ts";
 export * from "./simplify-ui.ts";
+export * from "./overthink-state.ts";
+export * from "./overthink.ts";
 
 const COMMANDS = [
 	{ value: "architecture", label: "architecture", description: "Document this repository in docs/architecture/ with diagrams and an offline map" },
@@ -85,6 +88,7 @@ const COMMANDS = [
 	{ value: "elevate", label: "elevate", description: "Discover missing expert considerations, then improve a request" },
 	{ value: "remember-me", label: "remember-me", description: "Help write and review personal memories; agents can unfold them on demand" },
 	{ value: "grill-me", label: "grill-me", description: "A private, one-question-at-a-time decision interview" },
+	{ value: "overthink", label: "overthink", description: "View private automatic second-look notes and session questions" },
 	{ value: "config", label: "config", description: "Global defaults, diagnostics and feature settings" },
 	{ value: "advisor", label: "advisor", description: "Check whether the executor's advisor tool is available right now" },
 	{ value: "advisor-steer", label: "advisor-steer", description: "View, edit, save, or clear the advisor's persistent steering brief" },
@@ -93,7 +97,7 @@ const COMMANDS = [
 const KNOWN_ACTIONS = new Set(COMMANDS.map((command) => command.value));
 /** Only capability-level commands appear by default; all existing commands remain discoverable by prefix. */
 export const FEATURED_BRO_COMMANDS = [
-  "simplify","show","btw","guided-review","architecture","elevate","grill-me","remember-me","config",
+  "simplify","show","btw","guided-review","architecture","elevate","grill-me","remember-me","overthink","config",
 ] as const;
 const FEATURED_COMMANDS = new Set<string>(FEATURED_BRO_COMMANDS);
 
@@ -121,6 +125,7 @@ export default async function bro(pi: ExtensionAPI) {
 
 	registerAdvisorTool(pi);
 	registerAboutUserTool(pi);
+	const overthink = registerOverthink(pi);
 
 	pi.registerCommand("bro", {
 		description: "Explain text, documents, and webpages; draw session turns; open a side conversation; configure Bro and the executor's advisor tool",
@@ -321,6 +326,13 @@ export default async function bro(pi: ExtensionAPI) {
 				return;
 			}
 
+			if (action === "overthink") {
+				if (value) { ctx.ui.notify("Use /bro overthink to open private notes; retry inside the modal.", "warning"); return; }
+				try { await overthink.open(ctx); }
+				catch (error) { ctx.ui.notify("Overthink: " + errorMessage(error), "error"); }
+				return;
+			}
+
 			if (action === "elevate") {
 				if (!hasBroCustomUi(ctx)) { ctx.ui.notify("Use /bro elevate in Pi interactive UI.", "warning"); return; }
 				try { await openElevateModal(ctx, value); }

package/src/config-navigation-ui.ts

@@ -11,10 +11,14 @@ import {
 } from "./config-navigation.ts";
 
 type MenuItem = {value:string;label:string};
-const rowsFor=(screen:ConfigNavScreen):readonly MenuItem[]=>{
+const rowsFor=(screen:ConfigNavScreen, automatic:boolean):readonly MenuItem[]=>{
   if(screen==="root")return CONFIG_ROOT;
   if(screen==="global")return CONFIG_GLOBAL;
   if(screen==="features")return CONFIG_FEATURES;
+  if(screen==="overthink")return [
+    {value:"overthink-defaults",label:"Default questions — edit starting set"},
+    {value:"overthink-toggle",label:"Automatic checks — "+(automatic?"On":"Off")+" (Enter to toggle)"},
+  ];
   if(screen==="advisor")return [
     {value:"advisor-settings",label:"Backend, model and effort"},
     {value:"advisor-steer",label:"Persistent advisor steering brief"},
@@ -25,6 +29,7 @@ const rowsFor=(screen:ConfigNavScreen):readonly MenuItem[]=>{
 export function createConfigNavigationModal(
   state:ConfigNavState,
   settings:BroSettings,
+  automatic = true,
 ): (tui:TuiLike,theme:Theme,keys:unknown,done:(result:ConfigNavAction)=>void)=>Component {
   return (tui,theme,_keys,done)=>{
     let closed=false;
@@ -33,7 +38,7 @@ export function createConfigNavigationModal(
     const finish=(result:ConfigNavAction)=>{if(closed)return;closed=true;done(result);};
     const go=(screen:ConfigNavScreen)=>{
       state.screen=screen;
-      const items=rowsFor(screen) as SelectItem[];
+      const items=rowsFor(screen, automatic) as SelectItem[];
       list=new SelectList(items,Math.min(items.length,Math.max(1,modalHeight(tui)-10)),getSelectListTheme());
       list.onSelect=item=>choose(item.value);
       list.onCancel=back;
@@ -53,11 +58,16 @@ export function createConfigNavigationModal(
       }
       if(state.screen==="features"){
         if(value==="advisor"){go("advisor");return;}
+        if(value==="overthink"){go("overthink");return;}
         if(value==="elevate"||value==="grill-me"||value==="remember-me"||value==="architecture"){
           state.inherited=value;go("inherited");return;
         }
         if(value==="explain"||value==="show"||value==="btw"||value==="review")return finish({kind:"settings",page:value});
       }
+      if(state.screen==="overthink"){
+        if(value==="overthink-defaults")return finish({kind:"overthink-defaults"});
+        if(value==="overthink-toggle")return finish({kind:"overthink-toggle"});
+      }
       if(state.screen==="advisor"){
         if(value==="advisor-steer")return finish({kind:"advisor-steer"});
         if(value==="advisor-settings")return finish({kind:"settings",page:"advisor"});
@@ -73,6 +83,7 @@ export function createConfigNavigationModal(
         s==="global"?"Bro · config / Global":
         s==="features"?"Bro · config / Features":
         s==="advisor"?"Bro · config / Features / Advisor":
+        s==="overthink"?"Bro · config / Features / Overthink":
         "Bro · config / Features / "+(state.inherited??"Inherited");
     };
     const subtitle=()=>{
@@ -80,6 +91,7 @@ export function createConfigNavigationModal(
       if(state.screen==="global")return "Defaults are shared. Doctor runs only when selected.";
       if(state.screen==="features")return "Feature model overrides are optional; inherited features use BTW.";
       if(state.screen==="advisor")return "Steering keeps its own file; changing models does not change steering.";
+      if(state.screen==="overthink")return "Automatic checks use the active Pi model. No backend override.";
       if(state.inherited)return inheritedConfigDescription(settings,state.inherited);
       return "Inherits BTW";
     };

package/src/config-navigation.ts

@@ -4,11 +4,11 @@ import { capabilityBackend, capabilityOverride, capabilityPair } from "./setting
 import { reviewBackendNotice } from "./backend.ts";
 
 export type ConfigSettingsPage = "defaults" | Capability;
-export type ConfigNavScreen = "root" | "global" | "features" | "advisor" | "inherited";
+export type ConfigNavScreen = "root" | "global" | "features" | "advisor" | "inherited" | "overthink";
 export type ConfigNavState = { screen: ConfigNavScreen; inherited?: "elevate"|"grill-me"|"remember-me"|"architecture" };
 export type ConfigNavAction =
   | {kind:"settings";page:ConfigSettingsPage}
-  | {kind:"preferences"|"doctor"|"advisor-steer"|"close"};
+  | {kind:"preferences"|"doctor"|"advisor-steer"|"overthink-defaults"|"overthink-toggle"|"close"};
 
 export const CONFIG_ROOT = [
   {value:"global",label:"Global — shared defaults, preferences and Doctor"},
@@ -28,6 +28,7 @@ export const CONFIG_FEATURES = [
   {value:"elevate",label:"Elevate — inherits BTW"},
   {value:"grill-me",label:"Grill Me — inherits BTW"},
   {value:"remember-me",label:"Remember Me — inherits BTW"},
+  {value:"overthink",label:"Overthink — automatic checks and default questions"},
   {value:"architecture",label:"Architecture Docs — inherits BTW"},
 ] as const;
 

package/src/doctor.ts

@@ -22,6 +22,8 @@ import { createConfigNavigationModal } from "./config-navigation-ui.ts";
 import { type ConfigNavAction, type ConfigNavState } from "./config-navigation.ts";
 import { showBroModal, showPreferencesModal, showAdvisorSteerModal } from "./explain-modal.ts";
 import { openBroOverlay } from "./modal-kit.ts";
+import { openOverthinkDefaults } from "./overthink.ts";
+import { readAutomaticChecks, writeAutomaticChecks } from "./overthink-state.ts";
 import {
 	type AgyEffort,
 	type AgyModelFamily,
@@ -661,8 +663,11 @@ export async function showBroConfigModal(ctx: ExtensionCommandContext, pi: Exten
 			ctx.ui.notify("Settings unavailable: "+errorMessage(error)+". Global > Doctor can diagnose.", "warning");
 			current = { backend:"agy",model:"(unavailable)",effort:"default",mode:"balanced",showTurns:1,overrides:{} };
 		}
+		let automatic = true;
+		try { automatic = await readAutomaticChecks(); }
+		catch (error) { ctx.ui.notify("Overthink automatic setting: " + errorMessage(error), "warning"); }
 		const selected = await openBroOverlay<ConfigNavAction>(
-			ctx, createConfigNavigationModal(navigation,current), {mouse:true}
+			ctx, createConfigNavigationModal(navigation,current,automatic), {mouse:true}
 		);
 		if (!selected || selected.kind === "close") return;
 		if (selected.kind === "preferences") {
@@ -673,6 +678,19 @@ export async function showBroConfigModal(ctx: ExtensionCommandContext, pi: Exten
 			await showAdvisorSteerModal(ctx,pi);
 			continue;
 		}
+		if (selected.kind === "overthink-toggle") {
+			try {
+				const next = !(await readAutomaticChecks());
+				await writeAutomaticChecks(next);
+				ctx.ui.notify("Overthink automatic checks: " + (next ? "On" : "Off"), "info");
+			} catch (error) { ctx.ui.notify("Overthink automatic checks: " + errorMessage(error), "error"); }
+			continue;
+		}
+		if (selected.kind === "overthink-defaults") {
+			try { await openOverthinkDefaults(ctx); }
+			catch (error) { ctx.ui.notify("Overthink defaults: " + errorMessage(error), "error"); }
+			continue;
+		}
 		if (selected.kind === "doctor") {
 			await showBroModal(ctx,{
 				loadingText:"Checking Bro setup…",

package/src/explain-modal.ts

@@ -414,6 +414,11 @@ Quick reference. Full user guide: https://github.com/tranhoangnguyen03/pi-bro/bl
 
 - \`/bro grill-me [topic]\` — private decision interview. Use /consolidate, /insert-last-message or /help. Full-access risk: docs/grill-me.md.
 
+## Overthink
+
+- \`/bro overthink\` — view private automatic second-look notes without running a model. Ctrl+R forces retry; Ctrl+E edits this session's questions; ? shows help; Ctrl+C copies. Uses the active Pi model and thinking level only. No separate backend settings.
+- \`/bro config\` → Features → Overthink provides automatic on/off and editable global starting questions; session edits stay with their Pi session. See docs/overthink.md.
+
 ## Side conversation
 
 - \`/bro btw [question]\` — open a side conversation seeded with recent main-session context. It starts conversation-only; reopening keeps the thread and its mode.
@@ -429,7 +434,7 @@ Quick reference. Full user guide: https://github.com/tranhoangnguyen03/pi-bro/bl
 ## Configure and check
 
 - \`/bro preferences\` — tell Bro about yourself and how you like answers; added to explain, show, btw, Elevate and Guided Review prompts, never the advisor (**Ctrl+S** save, **Ctrl+K** delete, **Ctrl+C** copy, **Esc** close)
-- \`/bro config\` — Global (shared defaults, preferences, Doctor) and Features (Simplify, Show, BTW, Review, Advisor and BTW-inherited workflows). The same model pickers, safe saves and error handling remain; Esc backs out.
+- \`/bro config\` — Global (shared defaults, preferences, Doctor) and Features (Simplify, Show, BTW, Review, Advisor, Overthink defaults and BTW-inherited workflows). The same model pickers, safe saves and error handling remain; Esc backs out.
 - \`/bro mode [brief|balanced|faithful]\` — view or choose the explanation mode
 - \`/bro doctor\` — check settings, preferences, and every selected backend without running a model turn
 

package/src/modal-kit.ts

@@ -118,10 +118,13 @@ export class Scroller {
 	private follow = false;
 
 	/** `followEnd`: scrolling to the end pins the view to new text until the reader scrolls up. */
-	constructor(
-		private readonly onScroll: () => void,
-		private readonly options: { followEnd?: boolean } = {},
-	) {}
+	private readonly onScroll: () => void;
+	private readonly options: { followEnd?: boolean };
+
+	constructor(onScroll: () => void, options: { followEnd?: boolean } = {}) {
+		this.onScroll = onScroll;
+		this.options = options;
+	}
 
 	view(lines: string[], rows: number): string[] {
 		this.rows = Math.max(1, rows);

package/src/overthink-questions-ui.ts

@@ -0,0 +1,131 @@
+/** One question list editor for global defaults and session snapshots. */
+import { Input, matchesKey, truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
+import { modalHeight, openBroOverlay, renderFrame, Scroller, formatNotice, type Theme } from "./modal-kit.ts";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { checkQuestions, MAX_OVERTHINK_QUESTIONS, MAX_OVERTHINK_QUESTION_CHARS } from "./overthink-state.ts";
+import { errorMessage } from "./util.ts";
+
+type EditorOptions = {
+  title: string; questions: string[]; reset: () => Promise<string[]>;
+  save: (questions: string[]) => Promise<void> | void;
+};
+
+export function createOverthinkQuestionEditor(options: EditorOptions) {
+  return (tui: TUI, theme: Theme, _keys: unknown, done: (value?: void) => void): Component => {
+    let questions = [...options.questions];
+    let saved = JSON.stringify(questions);
+    let cursor = 0;
+    let mode: "list" | "edit" = "list";
+    let input = new Input();
+    let editingIndex = -1;
+    let pending = false;
+    let closed = false;
+    let resetArmed = false;
+    let discardArmed = false;
+    let notice = "";
+    const scroller = new Scroller(() => tui.requestRender());
+    const dirty = () => JSON.stringify(questions) !== saved;
+    const warn = (message: string, tone: "info" | "success" | "error" | "warning" = "info") => {
+      notice = formatNotice(theme, message, tone); tui.requestRender();
+    };
+    const beginEdit = (index: number) => {
+      mode = "edit"; editingIndex = index;
+      input = new Input();
+      input.setValue(questions[index] ?? "");
+      input.onSubmit = (value: string) => {
+        const trimmed = value.trim();
+        if (!trimmed || trimmed.length > MAX_OVERTHINK_QUESTION_CHARS || /[\r\n]/.test(trimmed)) {
+          warn("Enter one nonempty question (max " + MAX_OVERTHINK_QUESTION_CHARS + " characters).", "warning"); return;
+        }
+        if (editingIndex === questions.length) questions.push(trimmed);
+        else questions[editingIndex] = trimmed;
+        mode = "list"; cursor = editingIndex; resetArmed = false;
+        discardArmed = false; notice = ""; tui.requestRender();
+      };
+      tui.requestRender();
+    };
+    const save = async () => {
+      if (pending) return;
+      let clean: string[];
+      try { clean = checkQuestions(questions); }
+      catch (error) { warn(errorMessage(error), "error"); return; }
+      pending = true; tui.requestRender();
+      try { await options.save(clean); saved = JSON.stringify(clean); questions = clean; warn("Questions saved.", "success"); }
+      catch (error) { warn("Save failed: " + errorMessage(error), "error"); }
+      finally { pending = false; tui.requestRender(); }
+    };
+    const reset = async () => {
+      pending = true; tui.requestRender();
+      try {
+        questions = checkQuestions(await options.reset());
+        cursor = 0; scroller.toStart(); resetArmed = false; discardArmed = false;
+        warn("Reset in editor. Ctrl+S to save.", "warning");
+      } catch (error) { warn("Reset failed: " + errorMessage(error), "error"); }
+      finally { pending = false; tui.requestRender(); }
+    };
+    return {
+      render(width: number) {
+        const height = modalHeight(tui);
+        const list = questions.length ? questions.map((question, index) =>
+          (index === cursor ? theme.fg("accent", "> ") : "  ") +
+          theme.fg(index === cursor ? "accent" : "text", truncateToWidth(String(index + 1) + ". " + question, Math.max(8, width - 6), "…"))
+        ) : [theme.fg("muted", "No questions. Add one, or save an empty list to disable checks.")];
+        return renderFrame(theme, width, height, {
+          header: () => theme.fg("accent", theme.bold(options.title)) + (dirty() ? " *" : ""),
+          body: (rows, inner) => mode === "edit"
+            ? ["Edit question:", ...input.render(inner)].slice(0, rows)
+            : scroller.view(list, rows),
+          notice,
+          hints: mode === "edit" ? "Enter apply · Esc cancel edit" :
+            "↑/↓ select · Enter edit · Ctrl+N add · Ctrl+X delete · Alt+↑/↓ move · Ctrl+D reset · Ctrl+S save · Esc close",
+          fill: true,
+        });
+      },
+      invalidate() {},
+      handleInput(data: string) {
+        if (pending || closed) return;
+        if (mode === "edit") {
+          if (matchesKey(data, "escape")) { mode = "list"; notice = ""; tui.requestRender(); return; }
+          input.handleInput(data); tui.requestRender(); return;
+        }
+        if (matchesKey(data, "escape")) {
+          if (resetArmed) { resetArmed = false; warn("Reset cancelled."); return; }
+          if (dirty() && !discardArmed) { discardArmed = true; warn("Unsaved questions. Esc again to discard, Ctrl+S to save.", "warning"); return; }
+          closed = true; done(); return;
+        }
+        discardArmed = false;
+        if (matchesKey(data, "ctrl+s")) { void save(); return; }
+        if (matchesKey(data, "ctrl+n")) {
+          if (questions.length >= MAX_OVERTHINK_QUESTIONS) { warn("Maximum " + MAX_OVERTHINK_QUESTIONS + " questions.", "warning"); return; }
+          beginEdit(questions.length); return;
+        }
+        if (matchesKey(data, "ctrl+d")) {
+          if (!resetArmed) { resetArmed = true; warn("Ctrl+D again to reset this list, then Ctrl+S to save.", "warning"); return; }
+          void reset(); return;
+        }
+        resetArmed = false;
+        if (matchesKey(data, "ctrl+x") && questions.length) {
+          questions.splice(cursor, 1); cursor = Math.min(cursor, Math.max(0, questions.length - 1));
+          warn("Question removed from draft. Ctrl+S to save."); return;
+        }
+        if (matchesKey(data, "alt+up") && cursor > 0) {
+          [questions[cursor - 1], questions[cursor]] = [questions[cursor]!, questions[cursor - 1]!];
+          cursor--; tui.requestRender(); return;
+        }
+        if (matchesKey(data, "alt+down") && cursor < questions.length - 1) {
+          [questions[cursor + 1], questions[cursor]] = [questions[cursor]!, questions[cursor + 1]!];
+          cursor++; tui.requestRender(); return;
+        }
+        if (matchesKey(data, "up")) { cursor = Math.max(0, cursor - 1); scroller.by(-1); tui.requestRender(); return; }
+        if (matchesKey(data, "down")) { cursor = Math.min(questions.length - 1, cursor + 1); scroller.by(1); tui.requestRender(); return; }
+        if (matchesKey(data, "return") || matchesKey(data, "enter")) {
+          if (questions.length) beginEdit(cursor);
+        }
+      },
+    };
+  };
+}
+
+export async function openOverthinkQuestionEditor(ctx: ExtensionCommandContext, options: EditorOptions): Promise<void> {
+  await openBroOverlay<void>(ctx, createOverthinkQuestionEditor(options));
+}

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 };
+}