From ad444f652cbf42038eddc1f6fc72eeab77e2aaf9 Mon Sep 17 00:00:00 2001
From: DarkPhilosophy <19309990+DarkPhilosophy@users.noreply.github.com>
Date: Fri, 5 Jun 2026 20:30:16 +0300
Subject: [PATCH 001/181] fix(coding-agent): retry orphaned toolUse stops to
 prevent history corruption
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When Anthropic Claude returns stopReason: "toolUse" but the assistant
message contains no actual toolCall, the session would append a spurious
toolResult entry. This creates tool_result blocks without matching
tool_use blocks — structurally invalid for Anthropic's API validator.

The symptom is overloaded_error on every subsequent request (in: 0 out: 0),
even though servers aren't overloaded. Other providers handle the same
corrupted history more leniently, making the problem appear Anthropic-specific.

The #isEmptyAssistantStop guard now checks for stopReason === "toolUse"
with no text and no toolCall. When the retry cap is hit, tool-use orphans
are still removed from active context (unlike regular empty stops) because
they corrupt message history. A regression test covers both the retry and
cap scenarios.

For affected sessions: run /compact to drop the corrupted history tail.

Fixes review feedback from chatgpt-codex-connector.
---
 .../coding-agent/src/session/agent-session.ts | 13 ++++-
 .../agent-session-empty-stop-guard.test.ts    | 47 +++++++++++++++++++
 2 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index 84f78cdce..b29f817c3 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -6443,9 +6443,13 @@ export class AgentSession {
 				this.#retryAttempt = 0;
 			}
 			this.#resolveRetry();
+			// Tool-use orphans corrupt Anthropic message history (tool_result without
+			// matching tool_use). Always remove them even when the retry cap is hit.
+			if (assistantMessage.stopReason === "toolUse") {
+				this.#removeEmptyStopFromActiveContext(assistantMessage);
+			}
 			return true;
 		}
-
 		this.#removeEmptyStopFromActiveContext(assistantMessage);
 		this.agent.appendMessage({
 			role: "developer",
@@ -6458,6 +6462,13 @@ export class AgentSession {
 	}
 
 	#isEmptyAssistantStop(assistantMessage: AssistantMessage): boolean {
+		const hasText = assistantMessage.content.some(
+			content => content.type === "text" && content.text.trim().length > 0,
+		);
+		const hasToolCall = assistantMessage.content.some(content => content.type === "toolCall");
+		if (assistantMessage.stopReason === "toolUse") {
+			return !hasText && !hasToolCall;
+		}
 		if (assistantMessage.stopReason !== "stop") return false;
 		return !assistantMessage.content.some(content => {
 			if (content.type === "text") return content.text.trim().length > 0;
diff --git a/packages/coding-agent/test/agent-session-empty-stop-guard.test.ts b/packages/coding-agent/test/agent-session-empty-stop-guard.test.ts
index 16cd9ecb1..eb9495ef0 100644
--- a/packages/coding-agent/test/agent-session-empty-stop-guard.test.ts
+++ b/packages/coding-agent/test/agent-session-empty-stop-guard.test.ts
@@ -51,6 +51,14 @@ function emptyStop(): MockResponse {
 	};
 }
 
+function orphanedToolUseStop(): MockResponse {
+	return {
+		content: [{ type: "thinking", thinking: "I should call a tool next." }],
+		stopReason: "toolUse",
+		usage: { output: 1, cacheRead: 100 },
+	};
+}
+
 async function createHarness(
 	responses: MockResponse[],
 	settingsOverrides: SettingsOverrides = {},
@@ -177,6 +185,45 @@ describe("AgentSession empty stop guard", () => {
 		).toHaveLength(1);
 	});
 
+	it("retries a tool-use stop that has no tool call or text", async () => {
+		const { session, mock } = await createHarness([
+			recordCall("orphan", "call-record-orphan"),
+			orphanedToolUseStop(),
+			{ content: ["finished after orphaned tool-use retry"], stopReason: "stop" },
+		]);
+
+		await session.prompt("record orphan");
+		await session.waitForIdle();
+
+		expect(mock.calls).toHaveLength(3);
+		expect(assistantText(session.agent.state.messages)).toContain("finished after orphaned tool-use retry");
+		expect(reminderMessages(session.agent.state.messages)).toHaveLength(1);
+	});
+
+	it("removes orphaned tool-use stops even when retry cap is hit", async () => {
+		const { session, mock } = await createHarness([
+			recordCall("gamma", "call-record-gamma"),
+			orphanedToolUseStop(),
+			orphanedToolUseStop(),
+			orphanedToolUseStop(),
+			orphanedToolUseStop(),
+		]);
+		await session.prompt("record gamma");
+		await session.waitForIdle();
+		expect(mock.calls).toHaveLength(5);
+		expect(reminderMessages(session.agent.state.messages)).toHaveLength(3);
+		const activeBranchMessages = session.sessionManager
+			.getBranch()
+			.filter(entry => entry.type === "message")
+			.map(entry => entry.message as AgentMessage);
+		const orphanedToolUseStops = activeBranchMessages.filter(
+			message =>
+				message.role === "assistant" &&
+				message.stopReason === "toolUse" &&
+				!message.content.some(content => content.type === "toolCall"),
+		);
+		expect(orphanedToolUseStops).toHaveLength(0);
+	});
 	it("caps empty stop retries at three attempts", async () => {
 		const { session, mock } = await createHarness([
 			recordCall("beta", "call-record-beta"),

From e744ce28944cdd2a5da010c0792fe5fbc6137506 Mon Sep 17 00:00:00 2001
From: DarkPhilosophy <19309990+DarkPhilosophy@users.noreply.github.com>
Date: Sat, 6 Jun 2026 02:22:36 +0300
Subject: [PATCH 002/181] perf(coding-agent): single-pass empty-stop content
 scan

---
 .../coding-agent/src/session/agent-session.ts | 30 +++++++++++--------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index c52a65311..31775300d 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -6484,19 +6484,25 @@ export class AgentSession {
 	}
 
 	#isEmptyAssistantStop(assistantMessage: AssistantMessage): boolean {
-		const hasText = assistantMessage.content.some(
-			content => content.type === "text" && content.text.trim().length > 0,
-		);
-		const hasToolCall = assistantMessage.content.some(content => content.type === "toolCall");
-		if (assistantMessage.stopReason === "toolUse") {
-			return !hasText && !hasToolCall;
+		const { stopReason } = assistantMessage;
+		if (stopReason !== "stop" && stopReason !== "toolUse") return false;
+
+		// Single pass over content; the three flags cover every emptiness rule below.
+		let hasText = false;
+		let hasThinking = false;
+		let hasToolCall = false;
+		for (const content of assistantMessage.content) {
+			if (content.type === "text") hasText ||= content.text.trim().length > 0;
+			else if (content.type === "thinking") hasThinking ||= content.thinking.trim().length > 0;
+			else if (content.type === "toolCall") hasToolCall = true;
 		}
-		if (assistantMessage.stopReason !== "stop") return false;
-		return !assistantMessage.content.some(content => {
-			if (content.type === "text") return content.text.trim().length > 0;
-			if (content.type === "thinking") return content.thinking.trim().length > 0;
-			return content.type === "toolCall";
-		});
+
+		// An orphaned toolUse stop (no tool_use block) corrupts Anthropic history:
+		// a later tool_result has nothing to anchor to. Thinking alone cannot anchor
+		// a tool_result, so it does not rescue a toolUse stop here.
+		if (stopReason === "toolUse") return !hasText && !hasToolCall;
+		// A plain stop is empty only when it carries no usable content at all.
+		return !hasText && !hasThinking && !hasToolCall;
 	}
 
 	#emptyStopRetryReminder(): string {

From 489b83d1ae7e78ca6f0d8156302ae741c04ee058 Mon Sep 17 00:00:00 2001
From: tycronk <tycronk20@gmail.com>
Date: Sat, 6 Jun 2026 03:15:27 -0400
Subject: [PATCH 003/181] docs: document Pi extension export drift in porting
 guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Section 3: add the @earendil-works/* scope alias and @mariozechner/pi-utils
to the import-scope replacements, and note that bare typebox is not an
@oh-my-pi/* scope.

Section 15 (Extensions divergence): record the dropped/renamed exports that
break a straight scope-rename port — StringEnum (pi-ai), formatSize
(pi-coding-agent), and the removed DefaultResourceLoader/DefaultPackageManager/
SettingsManager/createEventBus discovery classes — with their OMP replacements.
---
 docs/porting-from-pi-mono.md | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/docs/porting-from-pi-mono.md b/docs/porting-from-pi-mono.md
index 3bfb97bc1..23e4dfcd1 100644
--- a/docs/porting-from-pi-mono.md
+++ b/docs/porting-from-pi-mono.md
@@ -47,6 +47,9 @@ Upstream uses different package scopes. Replace them consistently.
   - `@mariozechner/pi-agent-core` → `@oh-my-pi/pi-agent-core`
   - `@mariozechner/pi-tui` → `@oh-my-pi/pi-tui`
   - `@mariozechner/pi-ai` → `@oh-my-pi/pi-ai`
+  - `@mariozechner/pi-utils` → `@oh-my-pi/pi-utils`
+- Some upstream packages publish under the `@earendil-works/*` scope instead of `@mariozechner/*`. Map it the same way (`@earendil-works/pi-coding-agent` → `@oh-my-pi/pi-coding-agent`, and so on).
+- The bare `typebox` package is not an `@oh-my-pi/*` scope; do not rewrite it as one. See the Extensions divergence in section 15 for how tool-parameter schemas map.
 
 ## 4) Use Bun APIs where they improve on Node
 
@@ -353,10 +356,13 @@ Our fork has architectural decisions that differ from upstream. **Do not port th
 
 ### Extensions
 
-| Upstream                      | Our Fork                                          |
-| ----------------------------- | ------------------------------------------------- |
-| `jiti` for TypeScript loading | Native Bun `import()`                             |
-| `pkg.pi` manifest field       | `pkg.omp` preferred; fallback to `pkg.pi` remains |
+| Upstream                                                         | Our Fork                                                                                          |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `jiti` for TypeScript loading                                    | Native Bun `import()`                                                                              |
+| `pkg.pi` manifest field                                          | `pkg.omp` preferred; fallback to `pkg.pi` remains                                                  |
+| `StringEnum` from `pi-ai`                                        | `Type.Enum` from the `pi.typebox` shim (or author the schema with `pi.zod`); `pi-ai` no longer exports `StringEnum` |
+| `formatSize` from `pi-coding-agent`                              | `formatBytes` from `@oh-my-pi/pi-utils`                                                            |
+| `DefaultResourceLoader` / `DefaultPackageManager` / `SettingsManager` / `createEventBus` | Capability-based discovery (`loadCapability(...)`) plus the `Settings` singleton and `EventBus` |
 
 ### Skip These Upstream Features
 

From 236bba96b996b6d11575fbe121e3e78279c4ec15 Mon Sep 17 00:00:00 2001
From: Asaf Mahlev <mahlev.asaf@gmail.com>
Date: Sat, 6 Jun 2026 11:56:23 +0300
Subject: [PATCH 004/181] fix(eval): floor JS worker init timeout to stop
 terminate-mid-init flake

Worker-ready wait reused Bun's 5s default per-test timeout as its floor, so a slow cold-start under --isolate + high CI concurrency was aborted at 5s. The catch then terminate()s a still-initializing Bun worker -- the documented SIGILL/SIGTRAP crash trigger -- crashing the whole test file and intermittently failing unrelated PRs.

Introduce WORKER_INIT_TIMEOUT_MS=15s as a fixed infrastructure floor (independent of, still dominated by, a larger per-cell timeout) and set a 20s file-local setDefaultTimeout in js-executor/js-workflow-helpers tests so cold starts complete instead of being torn down.
---
 packages/coding-agent/CHANGELOG.md                  |  3 +++
 .../coding-agent/src/eval/js/context-manager.ts     | 13 +++++++++----
 packages/coding-agent/test/core/js-executor.test.ts |  7 ++++++-
 .../test/core/js-workflow-helpers.test.ts           |  7 ++++++-
 4 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index e14f2353f..da2371269 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,6 +1,9 @@
 # Changelog
 
 ## [Unreleased]
+### Fixed
+
+- Fixed a flaky JS eval worker startup that intermittently failed unrelated CI runs. The worker-ready wait reused Bun's 5s default per-test timeout as its floor, so a slow cold-start under `--isolate` + high concurrency was aborted mid-init; terminating a still-initializing Bun worker is the documented SIGILL/SIGTRAP crash trigger, which took down the whole test file. Worker init now floors at a fixed 15s infrastructure budget (independent of, and still dominated by, a larger per-cell `timeout`), and the JS eval test suites set a 20s file-local timeout so cold starts complete instead of being torn down.
 
 ## [15.9.5] - 2026-06-05
 ### Added
diff --git a/packages/coding-agent/src/eval/js/context-manager.ts b/packages/coding-agent/src/eval/js/context-manager.ts
index cea0c97e5..8e7da951a 100644
--- a/packages/coding-agent/src/eval/js/context-manager.ts
+++ b/packages/coding-agent/src/eval/js/context-manager.ts
@@ -53,7 +53,12 @@ interface JsSession {
 const sessions = new Map<string, JsSession>();
 const startingSessions = new Map<string, Promise<JsSession>>();
 const resettingSessions = new Set<string>();
-const READY_TIMEOUT_MS_DEFAULT = 5_000;
+// Worker startup (module-graph import + WorkerCore construction) is infrastructure
+// cost, not user compute. Floor it independently of Bun's 5s default per-test timeout
+// so a slow cold-start under load isn't aborted mid-init — terminating a still-
+// initializing Bun worker is the documented SIGILL/SIGTRAP crash trigger (see
+// shared/indirect-eval.ts). Callers that pass a larger per-cell budget still dominate.
+const WORKER_INIT_TIMEOUT_MS = 15_000;
 
 export async function executeInVmContext(options: {
 	sessionKey: string;
@@ -191,9 +196,9 @@ async function acquireSession(sessionKey: string, snapshot: SessionSnapshot, tim
 			handleSessionMessage(session, msg);
 		});
 		try {
-			// Cold-start can exceed 5s on slow hosts. Let the caller's per-cell timeout dominate so
-			// users can grant more headroom when they raise `timeout` on a cell.
-			const readyTimeoutMs = Math.max(READY_TIMEOUT_MS_DEFAULT, timeoutMs ?? 0);
+			// Init headroom is the fixed infrastructure floor; the caller's per-cell timeout
+			// dominates when larger so users can grant more by raising `timeout` on a cell.
+			const readyTimeoutMs = Math.max(WORKER_INIT_TIMEOUT_MS, timeoutMs ?? 0);
 			await raceWithTimeout(readyPromise, readyTimeoutMs, "Timed out initializing JS eval worker");
 			worker.send({ type: "init", snapshot });
 			sessions.set(sessionKey, session);
diff --git a/packages/coding-agent/test/core/js-executor.test.ts b/packages/coding-agent/test/core/js-executor.test.ts
index 3d33d369d..7776bfbb2 100644
--- a/packages/coding-agent/test/core/js-executor.test.ts
+++ b/packages/coding-agent/test/core/js-executor.test.ts
@@ -1,4 +1,4 @@
-import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, it, setDefaultTimeout, vi } from "bun:test";
 import * as path from "node:path";
 import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
@@ -8,6 +8,11 @@ import * as z from "zod/v4";
 import { disposeAllVmContexts } from "../../src/eval/js/context-manager";
 import { executeJs, type JsResult } from "../../src/eval/js/executor";
 
+// JS eval cold-starts a Bun worker; under --isolate + high CI concurrency that startup
+// can exceed Bun's 5s default per-test timeout, flaking the suite. Give the worker-backed
+// tests headroom above the worker-init floor (context-manager WORKER_INIT_TIMEOUT_MS).
+setDefaultTimeout(20_000);
+
 function createTool(
 	name: string,
 	execute: (toolCallId: string, args: unknown, signal?: AbortSignal) => Promise<AgentToolResult>,
diff --git a/packages/coding-agent/test/core/js-workflow-helpers.test.ts b/packages/coding-agent/test/core/js-workflow-helpers.test.ts
index 8e005bab8..d8592165a 100644
--- a/packages/coding-agent/test/core/js-workflow-helpers.test.ts
+++ b/packages/coding-agent/test/core/js-workflow-helpers.test.ts
@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { afterAll, beforeAll, describe, expect, it, setDefaultTimeout } from "bun:test";
 import * as path from "node:path";
 import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import type { ToolSession } from "@oh-my-pi/pi-coding-agent/tools";
@@ -6,6 +6,11 @@ import { TempDir } from "@oh-my-pi/pi-utils";
 import { disposeAllVmContexts } from "../../src/eval/js/context-manager";
 import { executeJs, type JsResult } from "../../src/eval/js/executor";
 
+// JS eval cold-starts a Bun worker; under --isolate + high CI concurrency that startup
+// can exceed Bun's 5s default per-test timeout, flaking the suite. Give the worker-backed
+// tests headroom above the worker-init floor (context-manager WORKER_INIT_TIMEOUT_MS).
+setDefaultTimeout(20_000);
+
 function statusEvents(result: JsResult) {
 	return result.displayOutputs.filter(
 		(output): output is Extract<JsResult["displayOutputs"][number], { type: "status" }> => output.type === "status",

From ea8d58d3c696cf48afca46719e886ff8abfda7a2 Mon Sep 17 00:00:00 2001
From: Asaf Mahlev <mahlev.asaf@gmail.com>
Date: Sat, 6 Jun 2026 12:43:53 +0300
Subject: [PATCH 005/181] docs(eval): clarify indirect-eval cross-reference in
 worker-init comment

Address review: shared/indirect-eval.ts documents the vm.runInContext mid-execution terminate-race, not a mid-init one. Reword so a reader doesn't grep that file for an init-specific note.
---
 packages/coding-agent/src/eval/js/context-manager.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/coding-agent/src/eval/js/context-manager.ts b/packages/coding-agent/src/eval/js/context-manager.ts
index 8e7da951a..c1dcef642 100644
--- a/packages/coding-agent/src/eval/js/context-manager.ts
+++ b/packages/coding-agent/src/eval/js/context-manager.ts
@@ -56,8 +56,9 @@ const resettingSessions = new Set<string>();
 // Worker startup (module-graph import + WorkerCore construction) is infrastructure
 // cost, not user compute. Floor it independently of Bun's 5s default per-test timeout
 // so a slow cold-start under load isn't aborted mid-init — terminating a still-
-// initializing Bun worker is the documented SIGILL/SIGTRAP crash trigger (see
-// shared/indirect-eval.ts). Callers that pass a larger per-cell budget still dominate.
+// initializing Bun worker triggers the same kind of terminate-race that motivates
+// avoiding `vm.runInContext` (see shared/indirect-eval.ts), here surfacing as a
+// SIGILL/SIGSEGV. Callers that pass a larger per-cell budget still dominate.
 const WORKER_INIT_TIMEOUT_MS = 15_000;
 
 export async function executeInVmContext(options: {

From 06e157cc242af128b50cbdeb886ad88bdfcfb959 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 17:58:28 +0200
Subject: [PATCH 006/181] ux(coding-agent/edit): inlined edit result stats into
 the header

- Updated edit result rendering to inline diff change statistics in the file header instead of using a separate metadata row.
- Removed the redundant standalone metadata line and removed the extra blank line before diff bodies for a tighter single-hunk display.
- Added a test asserting the header now contains +/-/hunk stats and that no extra stats row appears before the diff.
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 packages/coding-agent/src/edit/renderer.ts    | 44 ++++++-------------
 .../test/extensions-runner.test.ts            |  1 -
 .../test/tools/edit-renderer.test.ts          | 25 +++++++++++
 4 files changed, 40 insertions(+), 31 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 6515a5a39..821b00241 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -9,6 +9,7 @@
 ### Changed
 
 - Changed the default persistent model selector shortcut from `Ctrl+L` to `Alt+M`, leaving `Ctrl+L` for display reset. Existing user remaps in `keybindings.yml` are preserved.
+- Changed the edit tool result header to carry the diff change stats (`+N / -M / K hunks`) inline next to the file path, and removed the redundant lone language-icon metadata row and the blank line between the header and the diff body, so a single-hunk edit renders as `✔ Edit: <icon> path:LINE ⟨+3 / 1 hunk⟩` immediately followed by the diff.
 
 ### Fixed
 
diff --git a/packages/coding-agent/src/edit/renderer.ts b/packages/coding-agent/src/edit/renderer.ts
index 51f35095d..4a51f9740 100644
--- a/packages/coding-agent/src/edit/renderer.ts
+++ b/packages/coding-agent/src/edit/renderer.ts
@@ -179,11 +179,6 @@ function countEditFiles(edits: EditRenderEntry[]): number {
 	return new Set(edits.map(edit => filePathFromEditEntry(edit.path)).filter(Boolean)).size;
 }
 
-function countLines(text: string): number {
-	if (!text) return 0;
-	return text.split("\n").length;
-}
-
 function getOperationTitle(op: Operation | undefined): string {
 	return op === "create" ? "Create" : op === "delete" ? "Delete" : "Edit";
 }
@@ -263,14 +258,6 @@ function formatStreamingDiff(
 	return text;
 }
 
-function formatMetadataLine(lineCount: number | null, language: string | undefined, uiTheme: Theme): string {
-	const icon = uiTheme.getLangIcon(language);
-	if (lineCount !== null) {
-		return uiTheme.fg("dim", `${icon} ${lineCount} lines`);
-	}
-	return uiTheme.fg("dim", `${icon}`);
-}
-
 function formatMultiFileStreamingDiff(previews: PerFileDiffPreview[], uiTheme: Theme, expanded: boolean): string {
 	const parts: string[] = [];
 	for (const preview of previews) {
@@ -387,6 +374,13 @@ function getApplyPatchRenderSummary(
 	}
 }
 
+function formatDiffStatsSuffix(diff: string, uiTheme: Theme): string {
+	const { added, removed, hunks } = getDiffStats(diff);
+	const stats = formatDiffStats(added, removed, hunks, uiTheme);
+	if (!stats) return "";
+	return ` ${uiTheme.fg("dim", uiTheme.format.bracketLeft)}${stats}${uiTheme.fg("dim", uiTheme.format.bracketRight)}`;
+}
+
 function renderDiffSection(
 	diff: string,
 	rawPath: string,
@@ -394,15 +388,6 @@ function renderDiffSection(
 	uiTheme: Theme,
 	renderDiffFn: (t: string, o?: { filePath?: string }) => string,
 ): string {
-	let text = "";
-	const diffStats = getDiffStats(diff);
-	text += `\n${uiTheme.fg("dim", uiTheme.format.bracketLeft)}${formatDiffStats(
-		diffStats.added,
-		diffStats.removed,
-		diffStats.hunks,
-		uiTheme,
-	)}${uiTheme.fg("dim", uiTheme.format.bracketRight)}`;
-
 	const {
 		text: truncatedDiff,
 		hiddenHunks,
@@ -411,7 +396,7 @@ function renderDiffSection(
 		? { text: diff, hiddenHunks: 0, hiddenLines: 0 }
 		: truncateDiffByHunk(diff, PREVIEW_LIMITS.DIFF_COLLAPSED_HUNKS, PREVIEW_LIMITS.DIFF_COLLAPSED_LINES);
 
-	text += `\n\n${renderDiffFn(truncatedDiff, { filePath: rawPath })}`;
+	let text = `\n${renderDiffFn(truncatedDiff, { filePath: rawPath })}`;
 	if (!expanded && (hiddenHunks > 0 || hiddenLines > 0)) {
 		const remainder: string[] = [];
 		if (hiddenHunks > 0) remainder.push(`${hiddenHunks} more hunks`);
@@ -532,11 +517,6 @@ function renderSingleFileResult(
 		"";
 	const op = args?.op || firstEdit?.op || details?.op;
 	const rename = args?.rename || firstEdit?.rename || firstEdit?.move || details?.move;
-	const { language } = formatEditDescription(rawPath, uiTheme, { rename });
-
-	const editTextSource = args?.newText ?? args?.oldText ?? args?.diff ?? args?.patch;
-	const metadataLineCount = editTextSource ? countLines(editTextSource) : null;
-	const metadataLine = op !== "delete" ? `\n${formatMetadataLine(metadataLineCount, language, uiTheme)}` : "";
 
 	const displayErrorText = isError && details && "displayErrorText" in details ? details.displayErrorText : undefined;
 	const errorText = isError
@@ -560,6 +540,11 @@ function renderSingleFileResult(
 				(details && !isError ? details.firstChangedLine : undefined);
 			const { description } = formatEditDescription(rawPath, uiTheme, { rename, firstChangedLine });
 
+			// Change stats ride inline on the header next to the path rather than a separate row.
+			const previewDiff = editDiffPreview && !("error" in editDiffPreview) ? editDiffPreview.diff : undefined;
+			const headerDiff = isError ? undefined : details?.diff || previewDiff;
+			const statsSuffix = headerDiff ? formatDiffStatsSuffix(headerDiff, uiTheme) : "";
+
 			const header = renderStatusLine(
 				{
 					icon: isError ? "error" : "success",
@@ -568,8 +553,7 @@ function renderSingleFileResult(
 				},
 				uiTheme,
 			);
-			let text = header;
-			text += metadataLine;
+			let text = header + statsSuffix;
 
 			if (isError) {
 				if (errorText) {
diff --git a/packages/coding-agent/test/extensions-runner.test.ts b/packages/coding-agent/test/extensions-runner.test.ts
index 1542897a9..33e188b7f 100644
--- a/packages/coding-agent/test/extensions-runner.test.ts
+++ b/packages/coding-agent/test/extensions-runner.test.ts
@@ -148,7 +148,6 @@ describe("ExtensionRunner", () => {
 			warnSpy.mockRestore();
 		});
 
-
 		it("warns when two extensions register same shortcut", async () => {
 			// Use a non-reserved shortcut
 			const extCode1 = `
diff --git a/packages/coding-agent/test/tools/edit-renderer.test.ts b/packages/coding-agent/test/tools/edit-renderer.test.ts
index 57f9aef63..20370c582 100644
--- a/packages/coding-agent/test/tools/edit-renderer.test.ts
+++ b/packages/coding-agent/test/tools/edit-renderer.test.ts
@@ -304,4 +304,29 @@ describe("editToolRenderer", () => {
 		const rendered = Bun.stripANSI(component.render(160).join("\n"));
 		expect(rendered).toContain("plain streamed text");
 	});
+
+	it("renders change stats inline on the result header with no separate metadata or stats row", async () => {
+		const uiTheme = await getUiTheme();
+		const diff = [" 115│ ctx", "-116│ old", "+117│ new one", "+118│ new two"].join("\n");
+		const component = editToolRenderer.renderResult(
+			{
+				content: [{ type: "text", text: "Updated demo.go" }],
+				details: { diff, op: "update" },
+			},
+			{ expanded: false, isPartial: false, renderContext: { editMode: "hashline" } },
+			uiTheme,
+			{ file_path: "demo.go" },
+		);
+
+		const lines = Bun.stripANSI(component.render(160).join("\n")).split("\n");
+		// Stats ride on the header line next to the path…
+		expect(lines[0]).toContain("demo.go");
+		expect(lines[0]).toContain("+2");
+		expect(lines[0]).toContain("-1");
+		expect(lines[0]).toContain("1 hunk");
+		// …only there (no standalone stats row), and the diff starts immediately
+		// below the header (no blank line, no lone lang-icon metadata row).
+		expect(lines[1]).toContain("115│ ctx");
+		expect(lines.filter(line => line.includes("hunk"))).toHaveLength(1);
+	});
 });

From c49d5c99b1c3c46369a219e2fa92cc88756cfa32 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 18:21:09 +0200
Subject: [PATCH 007/181] fix(coding-agent): removed preview line capping on
 context lines

- Rendered full context lines instead of truncating via capPreviewLines.
---
 packages/coding-agent/src/task/render.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/coding-agent/src/task/render.ts b/packages/coding-agent/src/task/render.ts
index 1522511bf..f6cc1fc0e 100644
--- a/packages/coding-agent/src/task/render.ts
+++ b/packages/coding-agent/src/task/render.ts
@@ -13,7 +13,6 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { formatContextUsage } from "../modes/components/status-line/context-thresholds";
 import type { Theme } from "../modes/theme/theme";
 import {
-	capPreviewLines,
 	formatBadge,
 	formatDuration,
 	formatMoreItems,
@@ -566,7 +565,7 @@ export function renderCall(
 			const content = line ? theme.fg("muted", replaceTabs(line)) : "";
 			return ` ${vertical}  ${content}`;
 		});
-		lines.push(...capPreviewLines(contextLines, theme, { expanded: options.expanded, prefix: ` ${vertical}  ` }));
+		lines.push(...contextLines);
 	}
 
 	// `Tasks` is the last child unless the isolation flag follows it.

From 75e211415e8e964eafbc20d199be9b982eedfd1e Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 18:28:19 +0200
Subject: [PATCH 008/181] feat(cli): added gallery CLI command for renderer
 previews and filtering options

- Added lazy-loaded `gallery` command registration and new filters for tool, state, width, expanded, and plain output.
- Implemented gallery state rendering with terminal-width defaults, state filtering, and unknown-tool fallback handling.
- Added shared fixture types and aggregated renderer fixtures for multiple tool families in `galleryFixtures`.
- Added tests for renderer state coverage, route-specific output (streaming/progress/success/error), and fixture fallback.
---
 packages/coding-agent/CHANGELOG.md            |   3 +-
 packages/coding-agent/src/cli-commands.ts     |   1 +
 packages/coding-agent/src/cli/gallery-cli.ts  | 165 ++++++++++
 .../src/cli/gallery-fixtures/agentic.ts       | 291 ++++++++++++++++++
 .../src/cli/gallery-fixtures/codeintel.ts     | 187 +++++++++++
 .../src/cli/gallery-fixtures/edit.ts          | 194 ++++++++++++
 .../src/cli/gallery-fixtures/fs.ts            | 153 +++++++++
 .../src/cli/gallery-fixtures/index.ts         |  40 +++
 .../src/cli/gallery-fixtures/interaction.ts   |  49 +++
 .../src/cli/gallery-fixtures/memory.ts        |  81 +++++
 .../src/cli/gallery-fixtures/misc.ts          | 221 +++++++++++++
 .../src/cli/gallery-fixtures/search.ts        | 213 +++++++++++++
 .../src/cli/gallery-fixtures/shell.ts         | 167 ++++++++++
 .../src/cli/gallery-fixtures/types.ts         |  32 ++
 .../src/cli/gallery-fixtures/web.ts           | 158 ++++++++++
 packages/coding-agent/src/commands/gallery.ts |  37 +++
 16 files changed, 1991 insertions(+), 1 deletion(-)
 create mode 100644 packages/coding-agent/src/cli/gallery-cli.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/agentic.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/codeintel.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/edit.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/fs.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/index.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/interaction.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/memory.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/misc.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/search.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/shell.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/types.ts
 create mode 100644 packages/coding-agent/src/cli/gallery-fixtures/web.ts
 create mode 100644 packages/coding-agent/src/commands/gallery.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 821b00241..b19bd4917 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,9 +1,10 @@
 # Changelog
 
 ## [Unreleased]
-
 ### Added
 
+- Added `gallery` CLI command to render built-in tool renderer output across streaming, in-progress, success, and failure states
+- Added `omp gallery` filtering and rendering options (`--tool`, `--state`, `--width`, `--expanded`, and `--plain`) for focused renderer previews and plain-text output
 - Added `app.display.reset`, bound to `Ctrl+L` by default, to force an immediate terminal display reset/redraw without resizing the window.
 
 ### Changed
diff --git a/packages/coding-agent/src/cli-commands.ts b/packages/coding-agent/src/cli-commands.ts
index c9ac00741..efa68d4fa 100644
--- a/packages/coding-agent/src/cli-commands.ts
+++ b/packages/coding-agent/src/cli-commands.ts
@@ -22,6 +22,7 @@ export const commands: CommandEntry[] = [
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
 	{ name: "dry-balance", load: () => import("./commands/dry-balance").then(m => m.default) },
 	{ name: "grep", load: () => import("./commands/grep").then(m => m.default) },
+	{ name: "gallery", load: () => import("./commands/gallery").then(m => m.default) },
 	{ name: "grievances", load: () => import("./commands/grievances").then(m => m.default) },
 	{ name: "install", load: () => import("./commands/install").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
diff --git a/packages/coding-agent/src/cli/gallery-cli.ts b/packages/coding-agent/src/cli/gallery-cli.ts
new file mode 100644
index 000000000..744691a15
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-cli.ts
@@ -0,0 +1,165 @@
+/**
+ * `omp gallery` — render every built-in tool's renderer across its lifecycle.
+ *
+ * For each tool with a registered renderer, the gallery drives a real
+ * {@link ToolExecutionComponent} through four states — streaming arguments,
+ * arguments complete (in progress), success, and failure — and prints the
+ * rendered output to stdout. It exists for visual QA of tool renderers without
+ * having to provoke each state through a live agent session.
+ */
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { TUI } from "@oh-my-pi/pi-tui";
+import { getProjectDir } from "@oh-my-pi/pi-utils";
+import { Settings } from "../config/settings";
+import { ToolExecutionComponent } from "../modes/components/tool-execution";
+import { initTheme, theme } from "../modes/theme/theme";
+import { toolRenderers } from "../tools/renderers";
+import { type GalleryFixture, type GalleryResult, galleryFixtures } from "./gallery-fixtures";
+
+/** Lifecycle states the gallery renders, in display order. */
+export const GALLERY_STATES = ["streaming", "progress", "success", "error"] as const;
+export type GalleryState = (typeof GALLERY_STATES)[number];
+
+const STATE_LABELS: Record<GalleryState, string> = {
+	streaming: "streaming args",
+	progress: "in progress",
+	success: "done",
+	error: "failed",
+};
+
+export interface GalleryCommandArgs {
+	/** Render width in columns (defaults to terminal width, clamped). */
+	width?: number;
+	/** Restrict to a single tool name. */
+	tool?: string;
+	/** Restrict to specific lifecycle states. */
+	states?: GalleryState[];
+	/** Render the expanded variant of each renderer. */
+	expanded?: boolean;
+	/** Strip ANSI styling from the output (useful when redirecting to a file). */
+	plain?: boolean;
+}
+
+const GENERIC_ERROR: GalleryResult = {
+	content: [{ type: "text", text: "Error: operation failed" }],
+	isError: true,
+};
+
+/** Build the fake `AgentTool` the component needs for its label and edit mode. */
+function fakeToolFor(name: string, fixture: GalleryFixture | undefined): AgentTool | undefined {
+	if (!fixture?.label && !fixture?.editMode) return undefined;
+	return { name, label: fixture.label ?? name, mode: fixture.editMode } as unknown as AgentTool;
+}
+
+/** The curated fixture for a tool, or a generic one for registry tools lacking sample data. */
+export function resolveFixture(name: string): GalleryFixture {
+	return (
+		galleryFixtures[name] ??
+		({
+			args: { note: `sample ${name} call` },
+			result: { content: [{ type: "text", text: `${name} completed` }] },
+		} satisfies GalleryFixture)
+	);
+}
+
+/**
+ * Render a single tool/state pair to lines. Builds a fresh component, drives it
+ * to the requested state, settles any async edit preview, then snapshots the
+ * render and stops all animation timers.
+ */
+export async function renderGalleryState(
+	name: string,
+	fixture: GalleryFixture,
+	state: GalleryState,
+	width: number,
+	expanded = false,
+): Promise<string[]> {
+	const tool = fakeToolFor(name, fixture);
+	const streamingArgs = state === "streaming" ? (fixture.streamingArgs ?? fixture.args) : fixture.args;
+	// The component only calls `requestRender` during a static render;
+	// `imageBudget` is consulted solely when images render, which the gallery
+	// disables. A cast avoids constructing a real terminal.
+	const ui = { requestRender() {} } as unknown as TUI;
+	const component = new ToolExecutionComponent(name, streamingArgs, { showImages: false }, tool, ui, getProjectDir());
+	component.setExpanded(expanded);
+
+	if (state !== "streaming") {
+		component.setArgsComplete();
+	}
+	if (state === "success") {
+		component.updateResult(fixture.result, false);
+	} else if (state === "error") {
+		component.updateResult(fixture.errorResult ?? GENERIC_ERROR, false);
+	}
+
+	// Edit-like renderers compute their diff preview off the render path; wait
+	// for it to settle so the snapshot is deterministic instead of racing a tick.
+	await component.whenPreviewSettled();
+
+	const lines = component.render(width);
+	component.stopAnimation();
+	return lines;
+}
+
+function resolveWidth(requested: number | undefined): number {
+	const fallback = process.stdout.columns ?? 100;
+	const width = requested ?? fallback;
+	return Math.max(40, Math.min(200, width));
+}
+
+function sectionRule(label: string, width: number): string {
+	const prefix = `── ${label} `;
+	const fill = Math.max(0, width - prefix.length);
+	return theme.fg("accent", theme.bold(`${prefix}${"─".repeat(fill)}`));
+}
+
+/**
+ * Render the gallery to stdout. Iterates the renderer registry (or a single
+ * tool), printing each requested lifecycle state under a labeled section.
+ */
+export async function runGalleryCommand(args: GalleryCommandArgs): Promise<void> {
+	const settingsInstance = await Settings.init();
+	await initTheme(
+		false,
+		settingsInstance.get("symbolPreset"),
+		settingsInstance.get("colorBlindMode"),
+		settingsInstance.get("theme.dark"),
+		settingsInstance.get("theme.light"),
+	);
+
+	const width = resolveWidth(args.width);
+	const expanded = args.expanded ?? false;
+	const states = args.states && args.states.length > 0 ? args.states : [...GALLERY_STATES];
+
+	const allNames = Object.keys(toolRenderers).sort();
+	const names = args.tool ? allNames.filter(name => name === args.tool) : allNames;
+	if (args.tool && names.length === 0) {
+		process.stdout.write(`Unknown tool '${args.tool}'. Known tools: ${allNames.join(", ")}\n`);
+		return;
+	}
+
+	const out: string[] = [];
+	const push = (line: string) => out.push(args.plain ? Bun.stripANSI(line) : line);
+
+	for (const name of names) {
+		const fixture = resolveFixture(name);
+		const heading = fixture.label && fixture.label !== name ? `${name} — ${fixture.label}` : name;
+		push("");
+		push(sectionRule(heading, width));
+
+		for (const state of states) {
+			push("");
+			push(theme.fg("dim", `  · ${STATE_LABELS[state]}`));
+			let lines: string[];
+			try {
+				lines = await renderGalleryState(name, fixture, state, width, expanded);
+			} catch (err) {
+				lines = [theme.fg("error", `  render failed: ${String(err)}`)];
+			}
+			for (const line of lines) push(line);
+		}
+	}
+	push("");
+
+	process.stdout.write(`${out.join("\n")}\n`);
+}
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/agentic.ts b/packages/coding-agent/src/cli/gallery-fixtures/agentic.ts
new file mode 100644
index 000000000..f2dd796ef
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/agentic.ts
@@ -0,0 +1,291 @@
+// Gallery fixtures for the agentic orchestration tools (task, goal, job).
+import type { GalleryFixture } from "./types";
+
+export const agenticFixtures: Record<string, GalleryFixture> = {
+	task: {
+		label: "Task",
+		// Streaming: agent chosen, first task fully arrived, second still landing.
+		streamingArgs: {
+			agent: "task",
+			tasks: [
+				{
+					id: "AuthLoader",
+					description: "Load auth middleware",
+					assignment: "Read packages/server/src/auth/*.ts and summarize the session-cookie flow.",
+				},
+				{ id: "RateLimiter", description: "Audit rate limiter" },
+			],
+		},
+		args: {
+			agent: "task",
+			context: [
+				"# Goal",
+				"Harden the HTTP auth stack before the release cut.",
+				"# Constraints",
+				"Touch only files under packages/server/src/auth/. Do not run gates.",
+			].join("\n"),
+			tasks: [
+				{
+					id: "AuthLoader",
+					description: "Load auth middleware",
+					assignment:
+						"Read packages/server/src/auth/session.ts and middleware.ts, then document the session-cookie validation flow and any TODOs.",
+				},
+				{
+					id: "RateLimiter",
+					description: "Audit rate limiter",
+					assignment:
+						"Inspect packages/server/src/auth/rate-limit.ts. Confirm the 429 path sets Retry-After and report gaps.",
+				},
+				{
+					id: "TokenRotation",
+					description: "Check token rotation",
+					assignment:
+						"Trace refresh-token rotation in packages/server/src/auth/tokens.ts and flag any reuse window.",
+				},
+			],
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: "3 agents completed: AuthLoader, RateLimiter, TokenRotation.",
+				},
+			],
+			details: {
+				projectAgentsDir: null,
+				totalDurationMs: 48_200,
+				usage: { cost: { total: 0.34 } },
+				results: [
+					{
+						index: 0,
+						id: "AuthLoader",
+						agent: "task",
+						agentSource: "bundled",
+						description: "Load auth middleware",
+						task: "Read packages/server/src/auth/session.ts and middleware.ts",
+						assignment:
+							"Read packages/server/src/auth/session.ts and middleware.ts, then document the session-cookie validation flow and any TODOs.",
+						exitCode: 0,
+						output: [
+							"Session validation runs in middleware.ts:42 via verifySessionCookie().",
+							"Cookies are HMAC-signed (SHA-256) and checked against the session store.",
+							"TODO at session.ts:88 — sliding-expiration refresh is stubbed.",
+						].join("\n"),
+						stderr: "",
+						truncated: false,
+						durationMs: 41_900,
+						tokens: 61_400,
+						contextTokens: 23_100,
+						contextWindow: 200_000,
+						resolvedModel: "anthropic/claude-sonnet",
+						usage: { cost: { total: 0.12 } },
+						outputMeta: { lineCount: 3, charCount: 214 },
+					},
+					{
+						index: 1,
+						id: "RateLimiter",
+						agent: "task",
+						agentSource: "bundled",
+						description: "Audit rate limiter",
+						task: "Inspect packages/server/src/auth/rate-limit.ts",
+						assignment:
+							"Inspect packages/server/src/auth/rate-limit.ts. Confirm the 429 path sets Retry-After and report gaps.",
+						exitCode: 0,
+						output: [
+							"rate-limit.ts uses a fixed-window counter keyed by client IP.",
+							"429 responses set Retry-After (rate-limit.ts:57).",
+							"Gap: no per-account limit, so a botnet across IPs bypasses the cap.",
+						].join("\n"),
+						stderr: "",
+						truncated: false,
+						durationMs: 38_500,
+						tokens: 54_800,
+						contextTokens: 19_700,
+						contextWindow: 200_000,
+						resolvedModel: "anthropic/claude-sonnet",
+						usage: { cost: { total: 0.1 } },
+						outputMeta: { lineCount: 3, charCount: 198 },
+					},
+					{
+						index: 2,
+						id: "TokenRotation",
+						agent: "task",
+						agentSource: "bundled",
+						description: "Check token rotation",
+						task: "Trace refresh-token rotation in packages/server/src/auth/tokens.ts",
+						assignment:
+							"Trace refresh-token rotation in packages/server/src/auth/tokens.ts and flag any reuse window.",
+						exitCode: 0,
+						output: [
+							"Refresh tokens rotate on every use (tokens.ts:120) and the old jti is revoked.",
+							"Reuse of a rotated token triggers full-family revocation — no reuse window found.",
+						].join("\n"),
+						stderr: "",
+						truncated: false,
+						durationMs: 48_200,
+						tokens: 49_200,
+						contextTokens: 17_500,
+						contextWindow: 200_000,
+						resolvedModel: "anthropic/claude-sonnet",
+						usage: { cost: { total: 0.12 } },
+						outputMeta: { lineCount: 2, charCount: 160 },
+					},
+				],
+			},
+		},
+		errorResult: {
+			isError: true,
+			content: [
+				{
+					type: "text",
+					text: "1 of 3 agents failed: RateLimiter.",
+				},
+			],
+			details: {
+				projectAgentsDir: null,
+				totalDurationMs: 39_400,
+				usage: { cost: { total: 0.21 } },
+				results: [
+					{
+						index: 0,
+						id: "AuthLoader",
+						agent: "task",
+						agentSource: "bundled",
+						description: "Load auth middleware",
+						task: "Read packages/server/src/auth/session.ts and middleware.ts",
+						assignment:
+							"Read packages/server/src/auth/session.ts and middleware.ts, then document the session-cookie validation flow and any TODOs.",
+						exitCode: 0,
+						output: "Session validation runs in middleware.ts:42 via verifySessionCookie().",
+						stderr: "",
+						truncated: false,
+						durationMs: 31_200,
+						tokens: 58_100,
+						contextTokens: 21_900,
+						contextWindow: 200_000,
+						resolvedModel: "anthropic/claude-sonnet",
+						usage: { cost: { total: 0.11 } },
+						outputMeta: { lineCount: 1, charCount: 70 },
+					},
+					{
+						index: 1,
+						id: "RateLimiter",
+						agent: "task",
+						agentSource: "bundled",
+						description: "Audit rate limiter",
+						task: "Inspect packages/server/src/auth/rate-limit.ts",
+						assignment:
+							"Inspect packages/server/src/auth/rate-limit.ts. Confirm the 429 path sets Retry-After and report gaps.",
+						exitCode: 1,
+						output: "",
+						stderr: "ENOENT: packages/server/src/auth/rate-limit.ts",
+						truncated: false,
+						durationMs: 9_800,
+						tokens: 12_300,
+						contextTokens: 6_400,
+						contextWindow: 200_000,
+						resolvedModel: "anthropic/claude-sonnet",
+						usage: { cost: { total: 0.1 } },
+						error: "Subagent exited 1: target file packages/server/src/auth/rate-limit.ts does not exist.",
+						outputMeta: { lineCount: 0, charCount: 0 },
+					},
+				],
+			},
+		},
+	},
+
+	goal: {
+		label: "Goal",
+		// Streaming: op is "create"; objective text still being typed.
+		streamingArgs: { op: "create", objective: "Ship the auth hardening" },
+		args: {
+			op: "create",
+			objective: "Ship the auth hardening pass: per-account rate limits and sliding session expiry.",
+			token_budget: 500_000,
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: "Goal set. Working toward: Ship the auth hardening pass.",
+				},
+			],
+			details: {
+				op: "create",
+				remainingTokens: 451_800,
+				completionBudgetReport: null,
+				goal: {
+					id: "goal_8f2a",
+					objective: "Ship the auth hardening pass: per-account rate limits and sliding session expiry.",
+					status: "active",
+					tokenBudget: 500_000,
+					tokensUsed: 48_200,
+					timeUsedSeconds: 312,
+					createdAt: 1_749_200_000_000,
+					updatedAt: 1_749_200_312_000,
+				},
+			},
+		},
+		errorResult: {
+			isError: true,
+			content: [{ type: "text", text: "Goal tool failed: objective is required when op=create." }],
+			details: { op: "create" },
+		},
+	},
+
+	job: {
+		label: "Job",
+		// Streaming: polling a single job id; the second id is still arriving.
+		streamingArgs: { poll: ["job_a1"] },
+		args: { poll: ["job_a1", "job_b2", "job_c3"] },
+		result: {
+			content: [{ type: "text", text: "3 jobs settled." }],
+			details: {
+				jobs: [
+					{
+						id: "job_a1",
+						type: "bash",
+						status: "completed",
+						label: "bun test packages/server/test/auth.test.ts",
+						durationMs: 18_400,
+						resultText: "42 pass, 0 fail (18.4s)",
+					},
+					{
+						id: "job_b2",
+						type: "task",
+						status: "completed",
+						label: "Migrate rate limiter to a sliding window",
+						durationMs: 96_700,
+						resultText: "Rewrote rate-limit.ts to a token-bucket; added per-account keys.",
+					},
+					{
+						id: "job_c3",
+						type: "bash",
+						status: "failed",
+						label: "bunx biome check packages/server/src/auth",
+						durationMs: 4_100,
+						errorText: "biome: 2 errors in tokens.ts — noUnusedVariables, useConst",
+					},
+				],
+			},
+		},
+		errorResult: {
+			isError: true,
+			content: [{ type: "text", text: "Job cancelled by user." }],
+			details: {
+				jobs: [
+					{
+						id: "job_d4",
+						type: "task",
+						status: "cancelled",
+						label: "Refactor the session store to Redis",
+						durationMs: 52_300,
+						errorText: "Aborted: superseded by goal re-scope.",
+					},
+				],
+				cancelled: [{ id: "job_d4", status: "cancelled" }],
+			},
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/codeintel.ts b/packages/coding-agent/src/cli/gallery-fixtures/codeintel.ts
new file mode 100644
index 000000000..5f10a9e2d
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/codeintel.ts
@@ -0,0 +1,187 @@
+/** Gallery fixtures for the code-intelligence tools (lsp, debug). */
+import type { GalleryFixture } from "./types";
+
+export const codeintelFixtures: Record<string, GalleryFixture> = {
+	lsp: {
+		label: "LSP",
+		streamingArgs: {
+			action: "references",
+			file: "src/server/auth.ts",
+		},
+		args: {
+			action: "references",
+			file: "src/server/auth.ts",
+			line: 42,
+			symbol: "validateToken",
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"Found 6 reference(s):",
+						"  src/server/auth.ts:42:14",
+						"    41: ",
+						"    42: export function validateToken(token: string): Claims {",
+						"    43:   const claims = verifyJwt(token);",
+						"  src/server/auth.ts:118:21",
+						'    117:   if (!header) throw new HttpError(401, "missing token");',
+						"    118:   const claims = validateToken(stripBearer(header));",
+						"    119:   return claims.sub;",
+						"  src/server/middleware/session.ts:57:18",
+						"    56:   const token = req.cookies.session;",
+						"    57:   const claims = validateToken(token);",
+						"    58:   req.userId = claims.sub;",
+						"  src/server/router.ts:153:20",
+						"    152: router.use(async (req, res, next) => {",
+						"    153:   req.claims = await validateToken(req.token);",
+						"    154:   next();",
+						"  test/auth.test.ts:24:9",
+						'    23: it("rejects expired tokens", () => {',
+						"    24:   expect(() => validateToken(expired)).toThrow(/expired/);",
+						"    25: });",
+						"  test/auth.test.ts:41:9",
+						'    40: it("accepts valid tokens", () => {',
+						"    41:   const claims = validateToken(signed);",
+						'    42:   expect(claims.sub).toBe("u_123");',
+					].join("\n"),
+				},
+			],
+			details: {
+				serverName: "typescript-language-server",
+				action: "references",
+				success: true,
+				request: {
+					action: "references",
+					file: "src/server/auth.ts",
+					line: 42,
+					symbol: "validateToken",
+				},
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "No language server found for this file",
+				},
+			],
+			isError: true,
+			details: {
+				serverName: "typescript-language-server",
+				action: "references",
+				success: false,
+				request: {
+					action: "references",
+					file: "src/server/auth.ts",
+					line: 42,
+					symbol: "validateToken",
+				},
+			},
+		},
+	},
+
+	debug: {
+		label: "Debug",
+		streamingArgs: {
+			action: "stack_trace",
+		},
+		args: {
+			action: "stack_trace",
+			levels: 20,
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"Stack trace:",
+						"- #1000 validate_token @ app/server.py:42:14",
+						"- #1001 authenticate @ app/server.py:88:9",
+						"- #1002 handle_request @ app/router.py:153:20",
+						"- #1003 dispatch @ app/router.py:97:5",
+						"- #1004 <module> @ app/server.py:212:1",
+					].join("\n"),
+				},
+			],
+			details: {
+				action: "stack_trace",
+				success: true,
+				snapshot: {
+					id: "dbg-1",
+					adapter: "debugpy",
+					cwd: "/Users/dev/project",
+					program: "./app/server.py",
+					status: "stopped",
+					launchedAt: "2026-06-06T14:21:08.412Z",
+					lastUsedAt: "2026-06-06T14:22:55.901Z",
+					threadId: 1,
+					frameId: 1000,
+					stopReason: "breakpoint",
+					stopDescription: "breakpoint 2",
+					frameName: "validate_token",
+					instructionPointerReference: "0x00000001000034a8",
+					source: { name: "server.py", path: "app/server.py" },
+					line: 42,
+					column: 14,
+					breakpointFiles: 1,
+					breakpointCount: 2,
+					functionBreakpointCount: 0,
+					outputBytes: 248,
+					outputTruncated: false,
+					needsConfigurationDone: false,
+				},
+				stackFrames: [
+					{
+						id: 1000,
+						name: "validate_token",
+						source: { name: "server.py", path: "app/server.py" },
+						line: 42,
+						column: 14,
+					},
+					{
+						id: 1001,
+						name: "authenticate",
+						source: { name: "server.py", path: "app/server.py" },
+						line: 88,
+						column: 9,
+					},
+					{
+						id: 1002,
+						name: "handle_request",
+						source: { name: "router.py", path: "app/router.py" },
+						line: 153,
+						column: 20,
+					},
+					{
+						id: 1003,
+						name: "dispatch",
+						source: { name: "router.py", path: "app/router.py" },
+						line: 97,
+						column: 5,
+					},
+					{
+						id: 1004,
+						name: "<module>",
+						source: { name: "server.py", path: "app/server.py" },
+						line: 212,
+						column: 1,
+					},
+				],
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "No active debug session. Launch or attach first.",
+				},
+			],
+			isError: true,
+			details: {
+				action: "stack_trace",
+				success: false,
+			},
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/edit.ts b/packages/coding-agent/src/cli/gallery-fixtures/edit.ts
new file mode 100644
index 000000000..b1da61d4b
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/edit.ts
@@ -0,0 +1,194 @@
+/** Gallery fixtures for the edit tools (edit, apply_patch, ast_edit). */
+import type { GalleryFixture } from "./types";
+
+export const editFixtures: Record<string, GalleryFixture> = {
+	edit: {
+		label: "Edit",
+		editMode: "replace",
+		// `previewDiff` is surfaced verbatim by the renderer's call preview, and the
+		// harness diff strategy skips `{ file_path, previewDiff }` (no `path`/`edits`),
+		// so the canned diff survives the streaming and progress states.
+		streamingArgs: {
+			file_path: "packages/coding-agent/src/tools/read.ts",
+			previewDiff: [
+				"@@ -88,3 +88,4 @@",
+				" 	const offset = args.offset ?? 1;",
+				"-	const limit = args.limit ?? 2000;",
+				"+	const limit = args.limit ?? 4000;",
+			].join("\n"),
+		},
+		args: {
+			file_path: "packages/coding-agent/src/tools/read.ts",
+			previewDiff: [
+				"@@ -88,5 +88,6 @@",
+				" 	const offset = args.offset ?? 1;",
+				"-	const limit = args.limit ?? 2000;",
+				"+	const limit = args.limit ?? 4000;",
+				" 	const raw = await Bun.file(path).text();",
+				"-	return raw.slice(offset, offset + limit);",
+				'+	return raw.split("\\n").slice(offset - 1, offset - 1 + limit).join("\\n");',
+			].join("\n"),
+		},
+		result: {
+			content: [{ type: "text", text: "Edited packages/coding-agent/src/tools/read.ts (1 hunk, +3 -2)" }],
+			details: {
+				path: "packages/coding-agent/src/tools/read.ts",
+				firstChangedLine: 89,
+				diff: [
+					"@@ -88,5 +88,6 @@",
+					" 	const offset = args.offset ?? 1;",
+					"-	const limit = args.limit ?? 2000;",
+					"+	const limit = args.limit ?? 4000;",
+					" 	const raw = await Bun.file(path).text();",
+					"-	return raw.slice(offset, offset + limit);",
+					'+	return raw.split("\\n").slice(offset - 1, offset - 1 + limit).join("\\n");',
+				].join("\n"),
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "Edit failed: the search text was not found in packages/coding-agent/src/tools/read.ts",
+				},
+			],
+			isError: true,
+			details: {
+				path: "packages/coding-agent/src/tools/read.ts",
+				diff: "",
+				errorText:
+					"No match for the search text. Expected `const limit = args.limit ?? 2000;` near line 89, but the file has `const limit = args.limit ?? 1000;`. Re-read the file and retry with the current contents.",
+			},
+		},
+	},
+
+	apply_patch: {
+		label: "Apply Patch",
+		editMode: "apply_patch",
+		streamingArgs: {
+			file_path: "packages/coding-agent/src/edit/renderer.ts",
+			previewDiff: [
+				"@@ -464,2 +464,2 @@",
+				"-		fileCount = countEditFiles(editArgs.edits);",
+				"+		fileCount = countDistinctFiles(editArgs.edits);",
+			].join("\n"),
+		},
+		args: {
+			file_path: "packages/coding-agent/src/edit/renderer.ts",
+			previewDiff: [
+				"@@ -177,4 +177,4 @@",
+				" /** Count distinct file paths in an edits array. */",
+				"-function countEditFiles(edits: EditRenderEntry[]): number {",
+				"+function countDistinctFiles(edits: EditRenderEntry[]): number {",
+				" 	return new Set(edits.map(edit => filePathFromEditEntry(edit.path)).filter(Boolean)).size;",
+				" }",
+				"@@ -467,2 +467,2 @@",
+				"-		fileCount = countEditFiles(editArgs.edits);",
+				"+		fileCount = countDistinctFiles(editArgs.edits);",
+			].join("\n"),
+		},
+		result: {
+			content: [
+				{ type: "text", text: "Applied patch to packages/coding-agent/src/edit/renderer.ts (2 hunks, +2 -2)" },
+			],
+			details: {
+				op: "update",
+				path: "packages/coding-agent/src/edit/renderer.ts",
+				firstChangedLine: 178,
+				diff: [
+					"@@ -177,4 +177,4 @@",
+					" /** Count distinct file paths in an edits array. */",
+					"-function countEditFiles(edits: EditRenderEntry[]): number {",
+					"+function countDistinctFiles(edits: EditRenderEntry[]): number {",
+					" 	return new Set(edits.map(edit => filePathFromEditEntry(edit.path)).filter(Boolean)).size;",
+					" }",
+					"@@ -467,2 +467,2 @@",
+					"-		fileCount = countEditFiles(editArgs.edits);",
+					"+		fileCount = countDistinctFiles(editArgs.edits);",
+				].join("\n"),
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "Apply patch failed: context does not match at line 177 of packages/coding-agent/src/edit/renderer.ts",
+				},
+			],
+			isError: true,
+			details: {
+				op: "update",
+				path: "packages/coding-agent/src/edit/renderer.ts",
+				diff: "",
+				errorText:
+					"Hunk @@ -177,4 +177,4 @@ failed to apply: the context line `function countEditFiles(edits: EditRenderEntry[]): number {` does not match the file. The file may have changed since it was read.",
+			},
+		},
+	},
+
+	ast_edit: {
+		label: "AST Edit",
+		streamingArgs: {
+			ops: [{ pat: "countEditFiles($$$ARGS)" }],
+			paths: ["packages/coding-agent/src/**/*.ts"],
+		},
+		args: {
+			ops: [{ pat: "countEditFiles($$$ARGS)", out: "countDistinctFiles($$$ARGS)" }],
+			paths: ["packages/coding-agent/src/**/*.ts"],
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"# edit/renderer.ts (2 replacements)",
+						"-468:		fileCount = countEditFiles(editArgs.edits);",
+						"+468:		fileCount = countDistinctFiles(editArgs.edits);",
+						"-488:		const totalFiles = args?.edits ? countEditFiles(args.edits) : 0;",
+						"+488:		const totalFiles = args?.edits ? countDistinctFiles(args.edits) : 0;",
+						"",
+						"# tools/tool-result.ts (1 replacement)",
+						"-42:	return countEditFiles(files);",
+						"+42:	return countDistinctFiles(files);",
+					].join("\n"),
+				},
+			],
+			details: {
+				totalReplacements: 3,
+				filesTouched: 2,
+				filesSearched: 214,
+				applied: false,
+				limitReached: false,
+				scopePath: "packages/coding-agent/src",
+				searchPath: "/Users/dev/Projects/pi/packages/coding-agent/src",
+				files: ["edit/renderer.ts", "tools/tool-result.ts"],
+				fileReplacements: [
+					{ path: "edit/renderer.ts", count: 2 },
+					{ path: "tools/tool-result.ts", count: 1 },
+				],
+				displayContent: [
+					"# edit/",
+					"## renderer.ts (2 replacements)",
+					"-468│		fileCount = countEditFiles(editArgs.edits);",
+					"+468│		fileCount = countDistinctFiles(editArgs.edits);",
+					"-488│		const totalFiles = args?.edits ? countEditFiles(args.edits) : 0;",
+					"+488│		const totalFiles = args?.edits ? countDistinctFiles(args.edits) : 0;",
+					"",
+					"# tools/",
+					"## tool-result.ts (1 replacement)",
+					"-42│	return countEditFiles(files);",
+					"+42│	return countDistinctFiles(files);",
+				].join("\n"),
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "Pattern parse error in ops[0].pat: unbalanced parenthesis in `countEditFiles($$$ARGS`",
+				},
+			],
+			isError: true,
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/fs.ts b/packages/coding-agent/src/cli/gallery-fixtures/fs.ts
new file mode 100644
index 000000000..290571544
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/fs.ts
@@ -0,0 +1,153 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: sample source-code strings (read fixtures) intentionally contain literal ${...}.
+// Gallery fixtures for the filesystem tools (read, write, find).
+import type { GalleryFixture } from "./types";
+
+const readSnippet = [
+	"export const findToolRenderer = {",
+	"\tinline: true,",
+	"\trenderCall(args: FindRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {",
+	"\t\tconst meta: string[] = [];",
+	"\t\tif (args.limit !== undefined) meta.push(`limit:${args.limit}`);",
+	"",
+	"\t\tconst text = renderStatusLine(",
+	'\t\t\t{ icon: "pending", title: "Find", description: formatFindRenderPaths(args.paths) || "*", meta },',
+	"\t\t\tuiTheme,",
+	"\t\t);",
+	"\t\treturn new Text(text, 0, 0);",
+	"\t},",
+].join("\n");
+
+const writtenContent = [
+	'import { describe, expect, it } from "bun:test";',
+	'import { parseSel } from "../src/tools/read";',
+	"",
+	'describe("parseSel", () => {',
+	'\tit("parses a single line range", () => {',
+	'\t\texpect(parseSel("42-58")).toEqual({',
+	'\t\t\tkind: "lines",',
+	"\t\t\tranges: [{ startLine: 42, endLine: 58 }],",
+	"\t\t});",
+	"\t});",
+	"",
+	'\tit("treats raw as a verbatim selector", () => {',
+	'\t\texpect(parseSel("raw")).toEqual({ kind: "raw" });',
+	"\t});",
+	"});",
+	"",
+].join("\n");
+
+export const fsFixtures: Record<string, GalleryFixture> = {
+	read: {
+		label: "Read",
+		// Streaming: path still being typed, selector not yet appended.
+		streamingArgs: { path: "packages/coding-agent/src/tools/find" },
+		args: { path: "packages/coding-agent/src/tools/find.ts:437-448" },
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"[packages/coding-agent/src/tools/find.ts#E48E]",
+						"437:export const findToolRenderer = {",
+						"438:\tinline: true,",
+						"439:\trenderCall(args: FindRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {",
+						"440:\t\tconst meta: string[] = [];",
+						"441:\t\tif (args.limit !== undefined) meta.push(`limit:${args.limit}`);",
+						"442:",
+						"443:\t\tconst text = renderStatusLine(",
+						'444:\t\t\t{ icon: "pending", title: "Find", description: formatFindRenderPaths(args.paths) || "*", meta },',
+						"445:\t\t\tuiTheme,",
+						"446:\t\t);",
+						"447:\t\treturn new Text(text, 0, 0);",
+						"448:\t},",
+					].join("\n"),
+				},
+			],
+			details: {
+				kind: "file",
+				resolvedPath: "/Users/dev/Projects/pi/packages/coding-agent/src/tools/find.ts",
+				contentType: "text/typescript",
+				displayContent: { text: readSnippet, startLine: 437 },
+			},
+		},
+		errorResult: {
+			isError: true,
+			content: [
+				{
+					type: "text",
+					text: "Error: ENOENT: no such file or directory, open 'packages/coding-agent/src/tools/find.ts'",
+				},
+			],
+		},
+	},
+
+	write: {
+		label: "Write",
+		// Streaming: path known, content still arriving (only the imports so far).
+		streamingArgs: {
+			path: "packages/coding-agent/test/parse-sel.test.ts",
+			content: 'import { describe, expect, it } from "bun:test";\nimport { parseSel } from "../src/tools/read";\n',
+		},
+		args: {
+			path: "packages/coding-agent/test/parse-sel.test.ts",
+			content: writtenContent,
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: "Created packages/coding-agent/test/parse-sel.test.ts (17 lines, 412 bytes).",
+				},
+			],
+			details: {},
+		},
+		errorResult: {
+			isError: true,
+			content: [
+				{
+					type: "text",
+					text: "Error: EACCES: permission denied, open 'packages/coding-agent/test/parse-sel.test.ts'",
+				},
+			],
+		},
+	},
+
+	find: {
+		label: "Find",
+		// Streaming: glob half-typed, no limit yet.
+		streamingArgs: { paths: ["packages/coding-agent/src/tools/*-render"] },
+		args: { paths: ["packages/coding-agent/src/**/*.test.ts"], limit: 50 },
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"packages/coding-agent/src/tools/read.test.ts",
+						"packages/coding-agent/src/tools/write.test.ts",
+						"packages/coding-agent/src/tools/find.test.ts",
+						"packages/coding-agent/src/cli/gallery-cli.test.ts",
+						"packages/coding-agent/src/edit/edit.test.ts",
+					].join("\n"),
+				},
+			],
+			details: {
+				scopePath: "packages/coding-agent/src",
+				cwd: "/Users/dev/Projects/pi",
+				fileCount: 5,
+				truncated: false,
+				files: [
+					"packages/coding-agent/src/cli/gallery-cli.test.ts",
+					"packages/coding-agent/src/edit/edit.test.ts",
+					"packages/coding-agent/src/tools/find.test.ts",
+					"packages/coding-agent/src/tools/read.test.ts",
+					"packages/coding-agent/src/tools/write.test.ts",
+				],
+			},
+		},
+		errorResult: {
+			isError: true,
+			content: [{ type: "text", text: "Find failed: invalid glob pattern '[unclosed'." }],
+			details: { error: "invalid glob pattern '[unclosed'" },
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/index.ts b/packages/coding-agent/src/cli/gallery-fixtures/index.ts
new file mode 100644
index 000000000..404082263
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/index.ts
@@ -0,0 +1,40 @@
+/**
+ * Aggregated sample data for the `omp gallery` command.
+ *
+ * Each fixture drives one tool's renderer through the four lifecycle states the
+ * gallery showcases: arguments streaming in, arguments complete but awaiting a
+ * result, a successful result, and a failed result. The data is intentionally
+ * hand-written (rather than schema-derived) so the gallery reflects what a real
+ * tool call looks like — the whole point is visual QA of the renderers.
+ *
+ * Fixtures are grouped by subsystem into sibling modules and merged here.
+ * Adding a tool to one of those groups is enough for the gallery to render it.
+ * Tools present in the renderer registry but missing here fall back to a
+ * generic fixture (see `gallery-cli.ts`), so the gallery never crashes on a
+ * newly added tool — it just looks plain until a fixture is supplied.
+ */
+import { agenticFixtures } from "./agentic";
+import { codeintelFixtures } from "./codeintel";
+import { editFixtures } from "./edit";
+import { fsFixtures } from "./fs";
+import { interactionFixtures } from "./interaction";
+import { memoryFixtures } from "./memory";
+import { miscFixtures } from "./misc";
+import { searchFixtures } from "./search";
+import { shellFixtures } from "./shell";
+import { webFixtures } from "./web";
+
+export * from "./types";
+
+export const galleryFixtures = {
+	...interactionFixtures,
+	...shellFixtures,
+	...fsFixtures,
+	...searchFixtures,
+	...editFixtures,
+	...agenticFixtures,
+	...memoryFixtures,
+	...webFixtures,
+	...codeintelFixtures,
+	...miscFixtures,
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/interaction.ts b/packages/coding-agent/src/cli/gallery-fixtures/interaction.ts
new file mode 100644
index 000000000..34da85a14
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/interaction.ts
@@ -0,0 +1,49 @@
+/** Gallery fixtures for the todo / ask / resolve interaction tools. */
+import type { GalleryFixture } from "./types";
+
+export const interactionFixtures: Record<string, GalleryFixture> = {
+	todo: {
+		label: "Todo",
+		streamingArgs: {
+			ops: [{ op: "init", list: [{ phase: "Foundation", items: ["Scaffold crate"] }] }],
+		},
+		args: {
+			ops: [
+				{
+					op: "init",
+					list: [
+						{ phase: "Foundation", items: ["Scaffold crate", "Wire workspace"] },
+						{ phase: "Auth", items: ["Port credential store", "Wire OAuth providers"] },
+					],
+				},
+			],
+		},
+		result: {
+			content: [{ type: "text", text: "Initialized 4 tasks across 2 phases" }],
+			details: {
+				storage: "session",
+				phases: [
+					{
+						name: "Foundation",
+						tasks: [
+							{ content: "Scaffold crate", status: "done" },
+							{ content: "Wire workspace", status: "in_progress" },
+						],
+					},
+					{
+						name: "Auth",
+						tasks: [
+							{ content: "Port credential store", status: "pending" },
+							{ content: "Wire OAuth providers", status: "pending" },
+						],
+					},
+				],
+				completedTasks: [{ phase: "Foundation", content: "Scaffold crate" }],
+			},
+		},
+		errorResult: {
+			content: [{ type: "text", text: "Unknown phase 'Auth' — initialize the list first" }],
+			isError: true,
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/memory.ts b/packages/coding-agent/src/cli/gallery-fixtures/memory.ts
new file mode 100644
index 000000000..01b70e7e4
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/memory.ts
@@ -0,0 +1,81 @@
+// Gallery fixtures for the long-term memory tools (retain, recall, reflect).
+import type { GalleryFixture } from "./types";
+
+export const memoryFixtures: Record<string, GalleryFixture> = {
+	retain: {
+		label: "Retain",
+		// Streaming: first item complete, second still arriving without a context.
+		streamingArgs: {
+			items: [{ content: "User prefers Bun over Node for all new scripts in this repo." }],
+		},
+		args: {
+			items: [
+				{
+					content: "User prefers Bun over Node for all new scripts in this repo.",
+					context: "Established while wiring up the gallery command tooling.",
+				},
+				{
+					content: "The TUI renderers live in packages/coding-agent/src/tools/*-render.ts.",
+					context: "Discovered during the gallery-fixtures task.",
+				},
+			],
+		},
+		result: {
+			content: [{ type: "text", text: "2 memories stored." }],
+			details: { count: 2 },
+		},
+		errorResult: {
+			isError: true,
+			content: [{ type: "text", text: "Retain failed: memory store is not initialized." }],
+		},
+	},
+
+	recall: {
+		label: "Recall",
+		// Streaming: query partially typed.
+		streamingArgs: { query: "bun vs node" },
+		args: { query: "Which runtime does the user prefer for scripts?" },
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"Found 2 relevant memories:",
+						"",
+						"1. [0.92] User prefers Bun over Node for all new scripts in this repo.",
+						"   (Established while wiring up the gallery command tooling.)",
+						"2. [0.78] The TUI renderers live in packages/coding-agent/src/tools/*-render.ts.",
+						"   (Discovered during the gallery-fixtures task.)",
+					].join("\n"),
+				},
+			],
+		},
+		errorResult: {
+			isError: true,
+			content: [{ type: "text", text: "Recall failed: vector index unavailable." }],
+		},
+	},
+
+	reflect: {
+		label: "Reflect",
+		streamingArgs: { query: "what have we learned about the user's" },
+		args: { query: "What have we learned about the user's tooling preferences?" },
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"The user consistently favors Bun as the runtime for scripts in this",
+						"repository, avoiding Node where possible. They also track the location",
+						"of TUI renderers under packages/coding-agent/src/tools, suggesting an",
+						"interest in keeping rendering logic discoverable and well-organized.",
+					].join("\n"),
+				},
+			],
+		},
+		errorResult: {
+			isError: true,
+			content: [{ type: "text", text: "Reflect failed: no memories matched the query." }],
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/misc.ts b/packages/coding-agent/src/cli/gallery-fixtures/misc.ts
new file mode 100644
index 000000000..80200a749
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/misc.ts
@@ -0,0 +1,221 @@
+/** Gallery fixtures for the ask / resolve / ssh / github / inspect_image tools. */
+import type { GalleryFixture } from "./types";
+
+export const miscFixtures: Record<string, GalleryFixture> = {
+	ask: {
+		label: "Ask",
+		streamingArgs: {
+			questions: [
+				{
+					id: "db",
+					question: "Which database should the new service use?",
+					options: [{ label: "Postgres" }],
+				},
+			],
+		},
+		args: {
+			questions: [
+				{
+					id: "db",
+					question: "Which database should the new service use?",
+					options: [
+						{ label: "Postgres", description: "Relational, strong consistency, JSONB support" },
+						{ label: "SQLite", description: "Embedded, zero-ops, great for single-node" },
+						{ label: "MongoDB", description: "Document store, flexible schema" },
+					],
+					recommended: 0,
+				},
+				{
+					id: "features",
+					question: "Which auth flows should ship in v1?",
+					options: [
+						{ label: "Email + password" },
+						{ label: "OAuth (Google, GitHub)" },
+						{ label: "Magic links" },
+						{ label: "SAML SSO", description: "Enterprise; can be deferred" },
+					],
+					multi: true,
+				},
+			],
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: "db: Postgres\nfeatures: Email + password, OAuth (Google, GitHub)",
+				},
+			],
+			details: {
+				results: [
+					{
+						id: "db",
+						question: "Which database should the new service use?",
+						options: ["Postgres", "SQLite", "MongoDB"],
+						multi: false,
+						selectedOptions: ["Postgres"],
+					},
+					{
+						id: "features",
+						question: "Which auth flows should ship in v1?",
+						options: ["Email + password", "OAuth (Google, GitHub)", "Magic links", "SAML SSO"],
+						multi: true,
+						selectedOptions: ["Email + password", "OAuth (Google, GitHub)"],
+					},
+				],
+			},
+		},
+		errorResult: {
+			content: [{ type: "text", text: "Prompt cancelled by user before any answer was given" }],
+			isError: true,
+		},
+	},
+
+	resolve: {
+		label: "Resolve",
+		streamingArgs: {
+			action: "apply",
+		},
+		args: {
+			action: "apply",
+			reason: "Rename is mechanical and the staged diff matches the intended refactor.",
+			extra: { title: "rename-usecredentials-hook" },
+		},
+		result: {
+			content: [{ type: "text", text: "Applied pending ast_edit: 7 replacements across 3 files" }],
+			details: {
+				action: "apply",
+				reason: "Rename is mechanical and the staged diff matches the intended refactor.",
+				extra: { title: "rename-usecredentials-hook" },
+				sourceToolName: "ast_edit",
+				label: "ast_edit: 7 replacements across 3 files",
+			},
+		},
+		errorResult: {
+			content: [{ type: "text", text: "No pending action to resolve" }],
+			isError: true,
+			details: {
+				action: "apply",
+				reason: "Rename is mechanical and the staged diff matches the intended refactor.",
+				sourceToolName: "ast_edit",
+				label: "ast_edit: 7 replacements across 3 files",
+			},
+		},
+	},
+
+	ssh: {
+		label: "SSH",
+		streamingArgs: {
+			host: "deploy@web-01",
+			command: "systemctl status",
+		},
+		args: {
+			host: "deploy@web-01",
+			command: "systemctl status omp-api --no-pager | head -n 12",
+			cwd: "/srv/omp",
+			timeout: 60,
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"● omp-api.service - Oh My Pi API",
+						"     Loaded: loaded (/etc/systemd/system/omp-api.service; enabled)",
+						"     Active: active (running) since Sat 2026-06-06 09:14:02 UTC; 3h 21min ago",
+						"   Main PID: 4812 (bun)",
+						"      Tasks: 17 (limit: 4915)",
+						"     Memory: 142.6M",
+						"        CPU: 38.214s",
+						"     CGroup: /system.slice/omp-api.service",
+						"             └─4812 /usr/local/bin/bun run dist/server.js",
+					].join("\n"),
+				},
+			],
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "ssh: connect to host web-01 port 22: Connection timed out",
+				},
+			],
+			isError: true,
+		},
+	},
+
+	github: {
+		label: "GitHub",
+		streamingArgs: {
+			op: "search_prs",
+			query: "is:open author:@me",
+		},
+		args: {
+			op: "search_prs",
+			query: "is:open review-requested:@me sort:updated",
+			repo: "oh-my-pi/pi",
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"#1842  feat(tui): virtualized scrollback for tool output     openyou · 2h ago   +312 -47",
+						"#1839  fix(agent): retry stream on transient 529             dvir   · 5h ago   +18 -4",
+						"#1830  refactor(edit): unify hashline + ast_edit previews    mira   · 1d ago   +540 -210",
+						"#1817  docs: document gallery fixtures contract             leo    · 2d ago   +96 -0",
+						"",
+						"4 open pull requests requesting your review",
+					].join("\n"),
+				},
+			],
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "gh: Could not resolve to a Repository with the name 'oh-my-pi/pi'. (HTTP 404)",
+				},
+			],
+			isError: true,
+		},
+	},
+
+	inspect_image: {
+		label: "Inspect Image",
+		streamingArgs: {
+			path: "docs/assets/dashboard-mock.png",
+		},
+		args: {
+			path: "docs/assets/dashboard-mock.png",
+			question: "What chart types are shown and roughly what layout does the dashboard use?",
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"The dashboard uses a two-column layout on a dark background.",
+						"Top row: four KPI cards (Revenue, Active Users, Churn, MRR) with sparklines.",
+						"Left column: a stacked area chart of weekly sessions over ~3 months.",
+						"Right column: a horizontal bar chart ranking the top 6 referrers.",
+						"Bottom: a paginated table of recent transactions with status pills.",
+					].join("\n"),
+				},
+			],
+			details: {
+				model: "claude-opus-4",
+				imagePath: "docs/assets/dashboard-mock.png",
+				mimeType: "image/png",
+			},
+		},
+		errorResult: {
+			content: [{ type: "text", text: "Image not found: docs/assets/dashboard-mock.png" }],
+			isError: true,
+			details: {
+				model: "claude-opus-4",
+				imagePath: "docs/assets/dashboard-mock.png",
+				mimeType: "image/png",
+			},
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/search.ts b/packages/coding-agent/src/cli/gallery-fixtures/search.ts
new file mode 100644
index 000000000..2a0962070
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/search.ts
@@ -0,0 +1,213 @@
+/** Gallery fixtures for the search tools (search, search_tool_bm25, ast_grep). */
+import type { GalleryFixture } from "./types";
+
+export const searchFixtures: Record<string, GalleryFixture> = {
+	search: {
+		label: "Search",
+		streamingArgs: {
+			pattern: "useState",
+		},
+		args: {
+			pattern: "useState",
+			paths: ["packages/tui/src"],
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"# packages/tui/src/components/",
+						"## SearchBox.tsx",
+						'18:  const [query, setQuery] = useState("");',
+						"19:  const [results, setResults] = useState<Match[]>([]);",
+						"## StatusBar.tsx",
+						"27:  const [expanded, setExpanded] = useState(false);",
+						"",
+						"# packages/tui/src/hooks/",
+						"## useDebounced.ts",
+						"9:  const [value, setValue] = useState(initial);",
+						"10:  const [pending, setPending] = useState(false);",
+					].join("\n"),
+				},
+			],
+			details: {
+				scopePath: "packages/tui/src",
+				searchPath: "/Users/dev/Projects/pi/packages/tui/src",
+				matchCount: 5,
+				fileCount: 3,
+				files: [
+					"packages/tui/src/components/SearchBox.tsx",
+					"packages/tui/src/components/StatusBar.tsx",
+					"packages/tui/src/hooks/useDebounced.ts",
+				],
+				fileMatches: [
+					{ path: "packages/tui/src/components/SearchBox.tsx", count: 2 },
+					{ path: "packages/tui/src/components/StatusBar.tsx", count: 1 },
+					{ path: "packages/tui/src/hooks/useDebounced.ts", count: 2 },
+				],
+				truncated: false,
+				displayContent: [
+					"# packages/tui/src/components/",
+					"## SearchBox.tsx",
+					'*18│  const [query, setQuery] = useState("");',
+					"*19│  const [results, setResults] = useState<Match[]>([]);",
+					"## StatusBar.tsx",
+					"*27│  const [expanded, setExpanded] = useState(false);",
+					"",
+					"# packages/tui/src/hooks/",
+					"## useDebounced.ts",
+					" *9│  const [value, setValue] = useState(initial);",
+					"*10│  const [pending, setPending] = useState(false);",
+				].join("\n"),
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "Invalid regex pattern: unclosed group near index 8",
+				},
+			],
+			isError: true,
+			details: {
+				error: "Invalid regex pattern: unclosed group near index 8",
+			},
+		},
+	},
+
+	search_tool_bm25: {
+		label: "SearchTools",
+		streamingArgs: {
+			query: "read pdf and ext",
+		},
+		args: {
+			query: "read pdf and extract tables",
+			limit: 5,
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: JSON.stringify({
+						query: "read pdf and extract tables",
+						activated_tools: ["docling_extract_tables", "docling_convert", "pdf_read_text"],
+						match_count: 4,
+						total_tools: 142,
+					}),
+				},
+			],
+			details: {
+				query: "read pdf and extract tables",
+				limit: 5,
+				total_tools: 142,
+				activated_tools: ["docling_extract_tables", "docling_convert", "pdf_read_text"],
+				active_selected_tools: ["read", "search", "edit", "bash"],
+				tools: [
+					{
+						name: "docling_extract_tables",
+						label: "Extract Tables",
+						description: "Extract tabular data from PDF documents into CSV or JSON rows.",
+						server_name: "docling",
+						mcp_tool_name: "extract_tables",
+						schema_keys: ["path", "pages", "format"],
+						score: 9.412037,
+					},
+					{
+						name: "docling_convert",
+						label: "Convert Document",
+						description: "Convert PDF, DOCX, or PPTX into structured Markdown with layout preserved.",
+						server_name: "docling",
+						mcp_tool_name: "convert",
+						schema_keys: ["path", "target", "ocr"],
+						score: 6.83102,
+					},
+					{
+						name: "pdf_read_text",
+						label: "Read PDF Text",
+						description: "Read raw text from a PDF, optionally scoped to a page range.",
+						server_name: "pdf-tools",
+						mcp_tool_name: "read_text",
+						schema_keys: ["path", "page_start", "page_end"],
+						score: 5.207884,
+					},
+					{
+						name: "tabula_scan",
+						label: "Scan Tables",
+						description: "Detect table bounding boxes on scanned PDF pages before extraction.",
+						server_name: "pdf-tools",
+						mcp_tool_name: "scan",
+						schema_keys: ["path", "dpi"],
+						score: 3.119556,
+					},
+				],
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "Tool discovery is disabled. Enable tools.discoveryMode or mcp.discoveryMode to use search_tool_bm25.",
+				},
+			],
+			isError: true,
+		},
+	},
+
+	ast_grep: {
+		label: "AST Grep",
+		streamingArgs: {
+			pat: "useState(",
+		},
+		args: {
+			pat: "useState($A)",
+			paths: ["packages/tui/src/components"],
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"# packages/tui/src/components/",
+						"## SearchBox.tsx",
+						'18:  const [query, setQuery] = useState("");',
+						'  meta: $A=""',
+						"## StatusBar.tsx",
+						"27:  const [expanded, setExpanded] = useState(false);",
+						"  meta: $A=false",
+					].join("\n"),
+				},
+			],
+			details: {
+				matchCount: 2,
+				fileCount: 2,
+				filesSearched: 14,
+				limitReached: false,
+				scopePath: "packages/tui/src/components",
+				searchPath: "/Users/dev/Projects/pi/packages/tui/src/components",
+				files: ["packages/tui/src/components/SearchBox.tsx", "packages/tui/src/components/StatusBar.tsx"],
+				fileMatches: [
+					{ path: "packages/tui/src/components/SearchBox.tsx", count: 1 },
+					{ path: "packages/tui/src/components/StatusBar.tsx", count: 1 },
+				],
+				displayContent: [
+					"# packages/tui/src/components/",
+					"## SearchBox.tsx",
+					'*18│  const [query, setQuery] = useState("");',
+					'  meta: $A=""',
+					"## StatusBar.tsx",
+					"*27│  const [expanded, setExpanded] = useState(false);",
+					"  meta: $A=false",
+				].join("\n"),
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: "Pattern parse error: incomplete node `useState(` — expected a closing `)`",
+				},
+			],
+			isError: true,
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/shell.ts b/packages/coding-agent/src/cli/gallery-fixtures/shell.ts
new file mode 100644
index 000000000..81bb0739d
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/shell.ts
@@ -0,0 +1,167 @@
+/** Gallery fixtures for the shell tools (bash, eval). */
+import type { GalleryFixture } from "./types";
+
+export const shellFixtures: Record<string, GalleryFixture> = {
+	bash: {
+		label: "Bash",
+		streamingArgs: {
+			command: "git status --short && git log --on",
+		},
+		args: {
+			command: "git status --short && git log --oneline -5",
+			cwd: "packages/coding-agent",
+			timeout: 30,
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						" M src/cli/gallery-cli.ts",
+						" M src/tools/bash.ts",
+						"?? src/cli/gallery-fixtures/shell.ts",
+						"a1b2c3d Wire gallery command into CLI dispatch",
+						"9f8e7d6 Add ToolExecutionComponent lifecycle states",
+						"4c5b6a7 Extract createShellRenderer from bashToolRenderer",
+						"2d3e4f5 Strip LLM-facing notices before TUI render",
+						"7a8b9c0 Cap preview lines in pending command block",
+					].join("\n"),
+				},
+			],
+			details: {
+				exitCode: 0,
+				wallTimeMs: 184,
+				timeoutSeconds: 30,
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"src/tools/bash.ts:1142:34 - error TS2339: Property 'requestedTimeoutSeconds' does not exist on type 'BashToolDetails'.",
+						"",
+						"1142   const requestedTimeoutSeconds = details?.requestedTimeoutSeconds;",
+						"                                            ~~~~~~~~~~~~~~~~~~~~~~~~",
+						"Found 1 error in src/tools/bash.ts:1142",
+					].join("\n"),
+				},
+			],
+			isError: true,
+			details: {
+				exitCode: 2,
+				wallTimeMs: 5120,
+				timeoutSeconds: 30,
+			},
+		},
+	},
+
+	eval: {
+		label: "Eval",
+		streamingArgs: {
+			cells: [
+				{
+					language: "py",
+					code: 'import json\nfrom pathlib import Path\n\ndata = json.loads(Path("package.js',
+					title: "load config",
+				},
+			],
+		},
+		args: {
+			cells: [
+				{
+					language: "py",
+					title: "load config",
+					code: [
+						"import json",
+						"from pathlib import Path",
+						"",
+						'data = json.loads(Path("package.json").read_text())',
+						'deps = data.get("dependencies", {})',
+						'print(f"{data[\\"name\\"]} v{data[\\"version\\"]}")',
+						'print(f"{len(deps)} dependencies")',
+						"display(sorted(deps)[:3])",
+					].join("\n"),
+				},
+			],
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: ["@oh-my-pi/coding-agent v0.42.0", "37 dependencies"].join("\n"),
+				},
+			],
+			details: {
+				language: "python",
+				languages: ["python"],
+				jsonOutputs: [["@ai-sdk/anthropic", "@oh-my-pi/pi-ai", "@oh-my-pi/pi-tui"]],
+				cells: [
+					{
+						index: 0,
+						title: "load config",
+						language: "python",
+						code: [
+							"import json",
+							"from pathlib import Path",
+							"",
+							'data = json.loads(Path("package.json").read_text())',
+							'deps = data.get("dependencies", {})',
+							'print(f"{data[\\"name\\"]} v{data[\\"version\\"]}")',
+							'print(f"{len(deps)} dependencies")',
+							"display(sorted(deps)[:3])",
+						].join("\n"),
+						output: ["@oh-my-pi/coding-agent v0.42.0", "37 dependencies"].join("\n"),
+						status: "complete",
+						durationMs: 64,
+						exitCode: 0,
+					},
+				],
+			},
+		},
+		errorResult: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"Traceback (most recent call last):",
+						'  File "<cell 0>", line 4, in <module>',
+						'    data = json.loads(Path("package.json").read_text())',
+						"          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^",
+						"json.decoder.JSONDecodeError: Expecting ',' delimiter: line 12 column 3 (char 318)",
+					].join("\n"),
+				},
+			],
+			isError: true,
+			details: {
+				language: "python",
+				languages: ["python"],
+				isError: true,
+				cells: [
+					{
+						index: 0,
+						title: "load config",
+						language: "python",
+						code: [
+							"import json",
+							"from pathlib import Path",
+							"",
+							'data = json.loads(Path("package.json").read_text())',
+							'deps = data.get("dependencies", {})',
+							'print(f"{data[\\"name\\"]} v{data[\\"version\\"]}")',
+						].join("\n"),
+						output: [
+							"Traceback (most recent call last):",
+							'  File "<cell 0>", line 4, in <module>',
+							'    data = json.loads(Path("package.json").read_text())',
+							"json.decoder.JSONDecodeError: Expecting ',' delimiter: line 12 column 3 (char 318)",
+						].join("\n"),
+						status: "error",
+						durationMs: 41,
+						exitCode: 1,
+					},
+				],
+			},
+		},
+	},
+};
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/types.ts b/packages/coding-agent/src/cli/gallery-fixtures/types.ts
new file mode 100644
index 000000000..77c051ce6
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/types.ts
@@ -0,0 +1,32 @@
+/**
+ * Types for `omp gallery` sample data. See {@link ./index} for the aggregated
+ * fixture registry and the contract each fixture must satisfy.
+ */
+import type { EditMode } from "../../edit";
+
+/** A tool result snapshot, matching the shape `ToolExecutionComponent` consumes. */
+export interface GalleryResult {
+	content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+	details?: unknown;
+	isError?: boolean;
+}
+
+export interface GalleryFixture {
+	/** Display label for the tool header (defaults to the tool name). */
+	label?: string;
+	/** Edit mode for edit-like tools so the streaming preview dispatches correctly. */
+	editMode?: EditMode;
+	/**
+	 * Arguments shown during the streaming state — a partial view of {@link args}
+	 * as if the tool-call JSON were still arriving. May include `__partialJson`
+	 * for renderers (bash, edit) that surface fields before the object closes.
+	 * Defaults to {@link args} when omitted.
+	 */
+	streamingArgs?: unknown;
+	/** Complete arguments shown for the in-progress, success, and error states. */
+	args: unknown;
+	/** Successful result. */
+	result: GalleryResult;
+	/** Failed result. Falls back to a generic error when omitted. */
+	errorResult?: GalleryResult;
+}
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/web.ts b/packages/coding-agent/src/cli/gallery-fixtures/web.ts
new file mode 100644
index 000000000..bec37debe
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-fixtures/web.ts
@@ -0,0 +1,158 @@
+// Gallery fixtures for the web tools (web_search, browser).
+import type { GalleryFixture } from "./types";
+
+export const webFixtures: Record<string, GalleryFixture> = {
+	web_search: {
+		label: "Web Search",
+		// Streaming: query still being typed, no recency/limit yet.
+		streamingArgs: { query: "bun vs node performance" },
+		args: {
+			query: "Bun vs Node.js performance benchmarks 2026",
+			recency: "month",
+			limit: 4,
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						"Bun continues to outperform Node.js on raw HTTP throughput and cold-start",
+						"time thanks to its JavaScriptCore engine and native-Zig runtime, while",
+						"Node.js retains an edge in ecosystem maturity and long-term stability.",
+						"For script-heavy workflows Bun's faster startup is the decisive factor.",
+					].join("\n"),
+				},
+			],
+			details: {
+				response: {
+					provider: "perplexity",
+					model: "sonar-pro",
+					authMode: "api_key",
+					requestId: "req_a1b2c3d4e5f6",
+					answer: [
+						"Bun continues to outperform Node.js on raw HTTP throughput and cold-start",
+						"time thanks to its JavaScriptCore engine and native-Zig runtime, while",
+						"Node.js retains an edge in ecosystem maturity and long-term stability.",
+						"For script-heavy workflows Bun's faster startup is the decisive factor.",
+					].join("\n"),
+					searchQueries: ["bun vs node.js performance benchmarks 2026", "bun http throughput vs node"],
+					sources: [
+						{
+							title: "Bun 1.2 Benchmarks: HTTP, SQLite, and Startup Time",
+							url: "https://bun.sh/blog/bun-v1.2-benchmarks",
+							snippet:
+								"Bun serves roughly 2.5x the requests per second of Node.js on a simple HTTP server and starts in under 10ms.",
+							ageSeconds: 86400 * 12,
+							author: "The Bun Team",
+						},
+						{
+							title: "Node.js vs Bun: A 2026 Performance Deep Dive",
+							url: "https://blog.platformatic.dev/nodejs-vs-bun-2026",
+							snippet:
+								"Across CPU-bound workloads the gap narrows, but Bun's faster module resolution keeps cold starts ahead.",
+							ageSeconds: 86400 * 3,
+							author: "Matteo Collina",
+						},
+						{
+							title: "Real-world API latency: Bun, Deno, and Node compared",
+							url: "https://www.theregister.com/2026/05/18/js_runtime_latency/",
+							snippet:
+								"Under sustained load p99 latencies converge, suggesting runtime choice matters less for steady-state services.",
+							ageSeconds: 86400 * 19,
+						},
+						{
+							title: "Why we migrated our CLI tooling from Node to Bun",
+							url: "https://engineering.example.com/posts/bun-cli-migration",
+							snippet:
+								"Startup dropped from 180ms to 22ms, shaving seconds off every developer command invocation.",
+							ageSeconds: 86400 * 27,
+							author: "Dana Whitfield",
+						},
+					],
+					citations: [
+						{
+							url: "https://bun.sh/blog/bun-v1.2-benchmarks",
+							title: "Bun 1.2 Benchmarks",
+							citedText: "Bun serves roughly 2.5x the requests per second of Node.js",
+						},
+					],
+					usage: {
+						inputTokens: 312,
+						outputTokens: 248,
+						totalTokens: 560,
+						searchRequests: 2,
+					},
+				},
+			},
+		},
+		errorResult: {
+			isError: true,
+			content: [{ type: "text", text: "Web search failed: provider returned HTTP 429 (rate limited)." }],
+			details: {
+				response: {
+					provider: "perplexity",
+					sources: [],
+				},
+				error: "Provider returned HTTP 429 (rate limited). Retry after 30s.",
+			},
+		},
+	},
+
+	browser: {
+		label: "Browser",
+		// Streaming: code body still arriving for a `run` action.
+		streamingArgs: {
+			action: "run",
+			name: "docs",
+			code: "const obs = await tab.observe();\n",
+		},
+		args: {
+			action: "run",
+			name: "docs",
+			code: [
+				"const obs = await tab.observe();",
+				"const heading = obs.elements.find(e => e.role === 'heading');",
+				"display({ url: obs.url, title: obs.title, headings: obs.elements.filter(e => e.role === 'heading').length });",
+				"return heading?.name ?? 'no heading found';",
+			].join("\n"),
+		},
+		result: {
+			content: [
+				{
+					type: "text",
+					text: [
+						'{ url: "https://bun.sh/docs", title: "Bun Documentation", headings: 14 }',
+						'"Get started with Bun"',
+					].join("\n"),
+				},
+			],
+			details: {
+				action: "run",
+				name: "docs",
+				url: "https://bun.sh/docs",
+				browser: "headless",
+				viewport: { width: 1280, height: 800, deviceScaleFactor: 1 },
+				result: '"Get started with Bun"',
+			},
+		},
+		errorResult: {
+			isError: true,
+			content: [
+				{
+					type: "text",
+					text: [
+						"TimeoutError: waiting for selector `aria/Sign in` failed: timeout 30000ms exceeded",
+						"    at Tab.waitFor (browser/tab.ts:212:13)",
+						"    at run (eval:3:7)",
+					].join("\n"),
+				},
+			],
+			details: {
+				action: "run",
+				name: "docs",
+				url: "https://bun.sh/docs",
+				browser: "headless",
+			},
+		},
+	},
+};
diff --git a/packages/coding-agent/src/commands/gallery.ts b/packages/coding-agent/src/commands/gallery.ts
new file mode 100644
index 000000000..ee5b69cba
--- /dev/null
+++ b/packages/coding-agent/src/commands/gallery.ts
@@ -0,0 +1,37 @@
+/**
+ * Render every built-in tool's renderer across its lifecycle states.
+ */
+import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { GALLERY_STATES, type GalleryState, runGalleryCommand } from "../cli/gallery-cli";
+
+export default class Gallery extends Command {
+	static description = "Preview tool renderers across streaming, in-progress, success, and failure states";
+
+	static flags = {
+		tool: Flags.string({ char: "t", description: "Render a single tool by name" }),
+		state: Flags.string({
+			char: "s",
+			description: "Render only the given lifecycle state(s)",
+			options: [...GALLERY_STATES],
+			multiple: true,
+		}),
+		width: Flags.integer({ char: "w", description: "Render width in columns" }),
+		expanded: Flags.boolean({
+			char: "e",
+			description: "Render the expanded variant of each renderer",
+			default: false,
+		}),
+		plain: Flags.boolean({ description: "Strip ANSI styling from the output", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Gallery);
+		await runGalleryCommand({
+			tool: flags.tool,
+			states: flags.state as GalleryState[] | undefined,
+			width: flags.width,
+			expanded: flags.expanded,
+			plain: flags.plain,
+		});
+	}
+}

From d1fbb28edc417df2f6c8f4ab15250184e8b006b7 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 18:40:52 +0200
Subject: [PATCH 009/181] fix(coding-agent): removed redundant tool-name line
 in custom render

- Fixed custom-rendered tools with `mergeCallAndResult` (e.g. `lsp`) emitting a redundant tool-name line above the framed result.
- Collapsed the leading blank line for self-delimiting framed boxes.
- Added gallery fidelity routing `lsp`/`task` through the custom-tool branch via a `customRendered` fixture flag.
- Added gallery harness tests guarding state coverage and the custom-branch fallback label.
---
 packages/coding-agent/CHANGELOG.md            |  2 +
 packages/coding-agent/src/cli/gallery-cli.ts  | 22 +++++-
 .../src/cli/gallery-fixtures/agentic.ts       |  1 +
 .../src/cli/gallery-fixtures/codeintel.ts     |  1 +
 .../src/cli/gallery-fixtures/types.ts         |  9 +++
 .../src/modes/components/tool-execution.ts    | 41 +++++++---
 .../coding-agent/test/gallery-cli.test.ts     | 79 +++++++++++++++++++
 7 files changed, 139 insertions(+), 16 deletions(-)
 create mode 100644 packages/coding-agent/test/gallery-cli.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index b19bd4917..151342073 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -5,6 +5,7 @@
 
 - Added `gallery` CLI command to render built-in tool renderer output across streaming, in-progress, success, and failure states
 - Added `omp gallery` filtering and rendering options (`--tool`, `--state`, `--width`, `--expanded`, and `--plain`) for focused renderer previews and plain-text output
+- Added `omp gallery` fidelity for tools whose renderers are attached on the tool instance (`lsp`, `task`): the gallery now drives them through the same custom-tool render branch production uses, so regressions in that path surface in the gallery rather than only in a live session.
 - Added `app.display.reset`, bound to `Ctrl+L` by default, to force an immediate terminal display reset/redraw without resizing the window.
 
 ### Changed
@@ -17,6 +18,7 @@
 - Fixed framed read results rendering with an extra blank row above and below the output block.
 - Fixed collapsed search result previews that could show only "… N more matches" when the first grouped section exceeded the preview budget. Collapsed search output now compacts to match rows, fills the budget with visible hits before the summary, and keeps truncation details out of the bottom user-visible notice.
 - Fixed boolean environment flag overrides that were ORed with settings, so `PI_INTENT_TRACING=0`, `PI_AUTO_QA=0`, and per-backend eval flags now take precedence when present while falling back to config when unset.
+- Fixed custom-rendered tools that set `mergeCallAndResult` (e.g. `lsp`) rendering a redundant tool-name line above the framed result once a result arrived. `ToolExecutionComponent`'s custom-tool branch now emits the fallback label only when the tool has no `renderCall` and the call is not suppressed by an existing result, matching the built-in renderer branch.
 
 ## [15.9.67] - 2026-06-06
 ### Added
diff --git a/packages/coding-agent/src/cli/gallery-cli.ts b/packages/coding-agent/src/cli/gallery-cli.ts
index 744691a15..921e571db 100644
--- a/packages/coding-agent/src/cli/gallery-cli.ts
+++ b/packages/coding-agent/src/cli/gallery-cli.ts
@@ -45,10 +45,26 @@ const GENERIC_ERROR: GalleryResult = {
 	isError: true,
 };
 
-/** Build the fake `AgentTool` the component needs for its label and edit mode. */
+/**
+ * Build the fake `AgentTool` the component needs for its label, edit mode, and —
+ * for `customRendered` fixtures — the renderer functions that route it through
+ * the same custom-tool branch production uses (see {@link GalleryFixture}).
+ */
 function fakeToolFor(name: string, fixture: GalleryFixture | undefined): AgentTool | undefined {
-	if (!fixture?.label && !fixture?.editMode) return undefined;
-	return { name, label: fixture.label ?? name, mode: fixture.editMode } as unknown as AgentTool;
+	if (!fixture?.label && !fixture?.editMode && !fixture?.customRendered) return undefined;
+	const tool: Record<string, unknown> = { name, label: fixture.label ?? name, mode: fixture.editMode };
+	if (fixture.customRendered) {
+		const renderer = toolRenderers[name] as
+			| { renderCall?: unknown; renderResult?: unknown; mergeCallAndResult?: unknown; inline?: unknown }
+			| undefined;
+		if (renderer) {
+			tool.renderCall = renderer.renderCall;
+			tool.renderResult = renderer.renderResult;
+			tool.mergeCallAndResult = renderer.mergeCallAndResult;
+			tool.inline = renderer.inline;
+		}
+	}
+	return tool as unknown as AgentTool;
 }
 
 /** The curated fixture for a tool, or a generic one for registry tools lacking sample data. */
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/agentic.ts b/packages/coding-agent/src/cli/gallery-fixtures/agentic.ts
index f2dd796ef..d1c262abe 100644
--- a/packages/coding-agent/src/cli/gallery-fixtures/agentic.ts
+++ b/packages/coding-agent/src/cli/gallery-fixtures/agentic.ts
@@ -4,6 +4,7 @@ import type { GalleryFixture } from "./types";
 export const agenticFixtures: Record<string, GalleryFixture> = {
 	task: {
 		label: "Task",
+		customRendered: true,
 		// Streaming: agent chosen, first task fully arrived, second still landing.
 		streamingArgs: {
 			agent: "task",
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/codeintel.ts b/packages/coding-agent/src/cli/gallery-fixtures/codeintel.ts
index 5f10a9e2d..0d9faca65 100644
--- a/packages/coding-agent/src/cli/gallery-fixtures/codeintel.ts
+++ b/packages/coding-agent/src/cli/gallery-fixtures/codeintel.ts
@@ -4,6 +4,7 @@ import type { GalleryFixture } from "./types";
 export const codeintelFixtures: Record<string, GalleryFixture> = {
 	lsp: {
 		label: "LSP",
+		customRendered: true,
 		streamingArgs: {
 			action: "references",
 			file: "src/server/auth.ts",
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/types.ts b/packages/coding-agent/src/cli/gallery-fixtures/types.ts
index 77c051ce6..97b7da510 100644
--- a/packages/coding-agent/src/cli/gallery-fixtures/types.ts
+++ b/packages/coding-agent/src/cli/gallery-fixtures/types.ts
@@ -16,6 +16,15 @@ export interface GalleryFixture {
 	label?: string;
 	/** Edit mode for edit-like tools so the streaming preview dispatches correctly. */
 	editMode?: EditMode;
+	/**
+	 * Set for tools whose real `AgentTool` attaches `renderCall`/`renderResult`
+	 * directly on the instance (e.g. `lsp`, `task`). The harness then attaches
+	 * the registry renderer onto the fake tool so the component routes through
+	 * the custom-tool branch — the same path production takes — instead of the
+	 * built-in registry branch. The two branches can diverge, so exercising the
+	 * real one keeps the gallery honest for these tools.
+	 */
+	customRendered?: boolean;
 	/**
 	 * Arguments shown during the streaming state — a partial view of {@link args}
 	 * as if the tool-call JSON were still arriving. May include `__partialJson`
diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index b232bc282..4fd08f692 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -171,6 +171,7 @@ let toolExecutionInstanceSeq = 0;
 export class ToolExecutionComponent extends Container {
 	#contentBox: Box; // Used for custom tools and bash visual truncation
 	#contentText: Text; // For built-in tools (with its own padding/bg)
+	#leadingSpacer: Spacer; // Blank line above the content; collapsed for self-delimiting framed boxes
 	#multiFileBoxes: (Box | Spacer)[] = []; // Extra boxes for multi-file edit results
 	#imageComponents: Image[] = [];
 	#imageSpacers: Spacer[] = [];
@@ -245,7 +246,8 @@ export class ToolExecutionComponent extends Container {
 		this.#cwd = cwd;
 		this.#args = args;
 
-		this.addChild(new Spacer(1));
+		this.#leadingSpacer = new Spacer(1);
+		this.addChild(this.#leadingSpacer);
 
 		// Always create both - contentBox for custom tools/bash/tools with renderers, contentText for other built-ins
 		this.#contentBox = new Box(1, 1, (text: string) => theme.bg("toolPendingBg", text));
@@ -585,6 +587,8 @@ export class ToolExecutionComponent extends Container {
 		this.#renderState.expanded = this.#expanded;
 		this.#renderState.isPartial = this.#isPartial;
 		this.#renderState.spinnerFrame = this.#spinnerFrame;
+		// Self-delimiting framed boxes don't need the leading blank line for separation.
+		let hasFramedBlock = false;
 
 		// Check for custom tool rendering
 		if (this.#tool && (this.#tool.renderCall || this.#tool.renderResult)) {
@@ -601,22 +605,28 @@ export class ToolExecutionComponent extends Container {
 			// call preview once result lines exist.
 			this.#renderState.renderContext = this.#buildRenderContext();
 
-			// Render call component
+			// Render call component. The fallback label only stands in for a
+			// missing `renderCall`; when the call is intentionally suppressed
+			// (mergeCallAndResult once a result exists) we render nothing here so
+			// the result component isn't preceded by a redundant tool-name line.
 			const shouldRenderCall = !this.#result || !mergeCallAndResult;
-			if (shouldRenderCall && tool.renderCall) {
-				try {
-					const callComponent = tool.renderCall(this.#getCallArgsForRender(), this.#renderState, theme);
-					if (callComponent) {
-						contentBoxHasFramedBlock = addBoxChild(this.#contentBox, callComponent) || contentBoxHasFramedBlock;
+			if (shouldRenderCall) {
+				if (tool.renderCall) {
+					try {
+						const callComponent = tool.renderCall(this.#getCallArgsForRender(), this.#renderState, theme);
+						if (callComponent) {
+							contentBoxHasFramedBlock =
+								addBoxChild(this.#contentBox, callComponent) || contentBoxHasFramedBlock;
+						}
+					} catch (err) {
+						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
+						// Fall back to default on error
+						addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 					}
-				} catch (err) {
-					logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
-					// Fall back to default on error
+				} else {
+					// No custom renderCall, show tool name
 					addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 				}
-			} else {
-				// No custom renderCall, show tool name
-				addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 			}
 
 			// Render result component if we have a result
@@ -657,6 +667,7 @@ export class ToolExecutionComponent extends Container {
 				}
 			}
 			setBoxPaddingForFramedBlock(this.#contentBox, contentBoxHasFramedBlock);
+			hasFramedBlock = contentBoxHasFramedBlock;
 		} else if (this.#toolName in toolRenderers) {
 			// Built-in tools with renderers
 			const renderer = toolRenderers[this.#toolName];
@@ -700,6 +711,7 @@ export class ToolExecutionComponent extends Container {
 						if (resultComponent) {
 							const fileBoxHasFramedBlock = addBoxChild(fileBox, resultComponent);
 							setBoxPaddingForFramedBlock(fileBox, fileBoxHasFramedBlock);
+							if (fileBoxHasFramedBlock) hasFramedBlock = true;
 						}
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
@@ -783,6 +795,7 @@ export class ToolExecutionComponent extends Container {
 					}
 				}
 				setBoxPaddingForFramedBlock(this.#contentBox, contentBoxHasFramedBlock);
+				hasFramedBlock = contentBoxHasFramedBlock;
 			}
 		} else {
 			// Other built-in tools: use Text directly with caching
@@ -790,6 +803,8 @@ export class ToolExecutionComponent extends Container {
 			this.#contentText.setText(this.#formatToolExecution());
 		}
 
+		this.#leadingSpacer.setLines(hasFramedBlock ? 0 : 1);
+
 		// Handle images (same for both custom and built-in)
 		for (const img of this.#imageComponents) {
 			this.removeChild(img);
diff --git a/packages/coding-agent/test/gallery-cli.test.ts b/packages/coding-agent/test/gallery-cli.test.ts
new file mode 100644
index 000000000..d7087f0b4
--- /dev/null
+++ b/packages/coding-agent/test/gallery-cli.test.ts
@@ -0,0 +1,79 @@
+import { beforeAll, describe, expect, it } from "bun:test";
+import { GALLERY_STATES, renderGalleryState, resolveFixture } from "../src/cli/gallery-cli";
+import type { GalleryFixture } from "../src/cli/gallery-fixtures";
+import { resetSettingsForTest, Settings } from "../src/config/settings";
+import { initTheme } from "../src/modes/theme/theme";
+import { toolRenderers } from "../src/tools/renderers";
+
+beforeAll(async () => {
+	resetSettingsForTest();
+	await Settings.init({ inMemory: true });
+	await initTheme(false, undefined, undefined, "dark", "light");
+});
+
+describe("gallery harness", () => {
+	it("renders every registered tool in every lifecycle state without throwing", async () => {
+		for (const name in toolRenderers) {
+			const fixture = resolveFixture(name);
+			for (const state of GALLERY_STATES) {
+				const lines = await renderGalleryState(name, fixture, state, 100);
+				// A renderer that produces no lines for a state is a regression: the
+				// component should always emit at least the call header or result.
+				expect(lines.length, `${name}/${state} rendered nothing`).toBeGreaterThan(0);
+			}
+		}
+	});
+
+	it("routes each state to the matching args/result (streaming args vs result, success vs error)", async () => {
+		const fixture: GalleryFixture = {
+			label: "Bash",
+			streamingArgs: { command: "echo STREAM_MARK" },
+			args: { command: "echo PROGRESS_MARK" },
+			result: { content: [{ type: "text", text: "SUCCESS_OUT" }], details: { exitCode: 0 } },
+			errorResult: { content: [{ type: "text", text: "ERROR_OUT" }], isError: true, details: { exitCode: 1 } },
+		};
+		const render = async (state: (typeof GALLERY_STATES)[number]) =>
+			Bun.stripANSI((await renderGalleryState("bash", fixture, state, 100)).join("\n"));
+
+		const streaming = await render("streaming");
+		expect(streaming).toContain("STREAM_MARK");
+		expect(streaming).not.toContain("PROGRESS_MARK");
+		expect(streaming).not.toContain("SUCCESS_OUT");
+
+		const progress = await render("progress");
+		expect(progress).toContain("PROGRESS_MARK");
+		expect(progress).not.toContain("SUCCESS_OUT");
+
+		const success = await render("success");
+		expect(success).toContain("SUCCESS_OUT");
+		expect(success).not.toContain("ERROR_OUT");
+
+		const error = await render("error");
+		expect(error).toContain("ERROR_OUT");
+		expect(error).not.toContain("SUCCESS_OUT");
+	});
+
+	it("routes customRendered tools (lsp, task) through the custom-tool branch", async () => {
+		// `lsp`/`task` attach their renderers on the real AgentTool, so the gallery
+		// must reproduce that path. With a result present and mergeCallAndResult, the
+		// custom branch must NOT emit a redundant tool-name line above the result box
+		// (regression guard for tool-execution's custom-branch fallback label).
+		const lsp = resolveFixture("lsp");
+		expect(lsp.customRendered).toBe(true);
+		const lines = await renderGalleryState("lsp", lsp, "error", 100);
+		const stripped = lines.map(line => Bun.stripANSI(line).trim());
+		// The framed result header is present...
+		expect(stripped.some(line => line.includes("LSP references"))).toBe(true);
+		// ...but no standalone "LSP" label line precedes it.
+		expect(stripped).not.toContain("LSP");
+	});
+
+	it("falls back to a generic fixture for registry tools without curated sample data", () => {
+		// resolveFixture never returns undefined for a registry tool, even one
+		// missing from the curated fixtures, so the gallery cannot crash on a newly
+		// added renderer.
+		const fixture = resolveFixture("a-tool-that-has-no-fixture");
+		expect(fixture.args).toBeDefined();
+		expect(fixture.result.content.length).toBeGreaterThan(0);
+	});
+});

From 9aa10dd92b7c9511babfd2321b2b7ccb02e82fae Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 18:52:46 +0200
Subject: [PATCH 010/181] ux(coding-agent): condensed web_search result
 rendering

- Showed answer text in full in the TUI; kept the `omp q` compact cap.
- Rendered each source as a single title/domain/age line with the URL linked on the title.
- Collapsed the metadata block to one Provider line plus Usage.
- Rendered search errors as a framed panel matching the success layout.
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 .../src/modes/components/tool-execution.ts    | 11 +--
 .../coding-agent/src/web/search/render.ts     | 93 ++++++++-----------
 3 files changed, 41 insertions(+), 64 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 151342073..3dc36cc36 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -12,6 +12,7 @@
 
 - Changed the default persistent model selector shortcut from `Ctrl+L` to `Alt+M`, leaving `Ctrl+L` for display reset. Existing user remaps in `keybindings.yml` are preserved.
 - Changed the edit tool result header to carry the diff change stats (`+N / -M / K hunks`) inline next to the file path, and removed the redundant lone language-icon metadata row and the blank line between the header and the diff body, so a single-hunk edit renders as `✔ Edit: <icon> path:LINE ⟨+3 / 1 hunk⟩` immediately followed by the diff.
+- Changed the `web_search` tool result rendering: the answer text now shows in full instead of being truncated to a "… N more lines" preview (the `omp q` CLI still caps its compact output), each source renders as a single `title (domain) · age` line with the URL linked on the title (dropping the snippet and bare-URL rows), and the metadata block collapses to one `Provider: <model> @ <provider> (<auth>)` line plus `Usage:` (removing the redundant Sources/Citations/Request/Queries rows).
 
 ### Fixed
 
diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index 4fd08f692..5b90a8a6b 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -171,7 +171,6 @@ let toolExecutionInstanceSeq = 0;
 export class ToolExecutionComponent extends Container {
 	#contentBox: Box; // Used for custom tools and bash visual truncation
 	#contentText: Text; // For built-in tools (with its own padding/bg)
-	#leadingSpacer: Spacer; // Blank line above the content; collapsed for self-delimiting framed boxes
 	#multiFileBoxes: (Box | Spacer)[] = []; // Extra boxes for multi-file edit results
 	#imageComponents: Image[] = [];
 	#imageSpacers: Spacer[] = [];
@@ -246,8 +245,7 @@ export class ToolExecutionComponent extends Container {
 		this.#cwd = cwd;
 		this.#args = args;
 
-		this.#leadingSpacer = new Spacer(1);
-		this.addChild(this.#leadingSpacer);
+		this.addChild(new Spacer(1));
 
 		// Always create both - contentBox for custom tools/bash/tools with renderers, contentText for other built-ins
 		this.#contentBox = new Box(1, 1, (text: string) => theme.bg("toolPendingBg", text));
@@ -587,8 +585,6 @@ export class ToolExecutionComponent extends Container {
 		this.#renderState.expanded = this.#expanded;
 		this.#renderState.isPartial = this.#isPartial;
 		this.#renderState.spinnerFrame = this.#spinnerFrame;
-		// Self-delimiting framed boxes don't need the leading blank line for separation.
-		let hasFramedBlock = false;
 
 		// Check for custom tool rendering
 		if (this.#tool && (this.#tool.renderCall || this.#tool.renderResult)) {
@@ -667,7 +663,6 @@ export class ToolExecutionComponent extends Container {
 				}
 			}
 			setBoxPaddingForFramedBlock(this.#contentBox, contentBoxHasFramedBlock);
-			hasFramedBlock = contentBoxHasFramedBlock;
 		} else if (this.#toolName in toolRenderers) {
 			// Built-in tools with renderers
 			const renderer = toolRenderers[this.#toolName];
@@ -711,7 +706,6 @@ export class ToolExecutionComponent extends Container {
 						if (resultComponent) {
 							const fileBoxHasFramedBlock = addBoxChild(fileBox, resultComponent);
 							setBoxPaddingForFramedBlock(fileBox, fileBoxHasFramedBlock);
-							if (fileBoxHasFramedBlock) hasFramedBlock = true;
 						}
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
@@ -795,7 +789,6 @@ export class ToolExecutionComponent extends Container {
 					}
 				}
 				setBoxPaddingForFramedBlock(this.#contentBox, contentBoxHasFramedBlock);
-				hasFramedBlock = contentBoxHasFramedBlock;
 			}
 		} else {
 			// Other built-in tools: use Text directly with caching
@@ -803,8 +796,6 @@ export class ToolExecutionComponent extends Container {
 			this.#contentText.setText(this.#formatToolExecution());
 		}
 
-		this.#leadingSpacer.setLines(hasFramedBlock ? 0 : 1);
-
 		// Handle images (same for both custom and built-in)
 		for (const img of this.#imageComponents) {
 			this.removeChild(img);
diff --git a/packages/coding-agent/src/web/search/render.ts b/packages/coding-agent/src/web/search/render.ts
index 48ffe0607..2e802f606 100644
--- a/packages/coding-agent/src/web/search/render.ts
+++ b/packages/coding-agent/src/web/search/render.ts
@@ -15,23 +15,16 @@ import {
 	formatMoreItems,
 	formatStatusIcon,
 	getDomain,
-	getPreviewLines,
 	PREVIEW_LIMITS,
-	TRUNCATE_LENGTHS,
+	replaceTabs,
 	truncateToWidth,
 } from "../../tools/render-utils";
-import { renderStatusLine, renderTreeList } from "../../tui";
+import { renderStatusLine, renderTreeList, urlHyperlink } from "../../tui";
 import { CachedOutputBlock, markFramedBlockComponent } from "../../tui/output-block";
 import { getSearchProviderLabel } from "./provider";
 import type { SearchResponse } from "./types";
 
-const MAX_COLLAPSED_ANSWER_LINES = PREVIEW_LIMITS.COLLAPSED_LINES;
-const MAX_SNIPPET_LINES = 2;
-const MAX_SNIPPET_LINE_LEN = TRUNCATE_LENGTHS.LINE;
 const MAX_COLLAPSED_ITEMS = PREVIEW_LIMITS.COLLAPSED_ITEMS;
-const MAX_QUERY_PREVIEW = 2;
-const MAX_QUERY_LEN = 90;
-const MAX_REQUEST_ID_LEN = 36;
 
 function renderFallbackText(contentText: string, expanded: boolean, theme: Theme): Component {
 	const lines = contentText.split("\n").filter(line => line.trim());
@@ -66,6 +59,21 @@ export interface SearchRenderDetails {
 	error?: string;
 }
 
+/** Render a web search failure as a framed error panel, matching the success layout. */
+function renderSearchErrorPanel(message: string, providerLabel: string | undefined, theme: Theme): Component {
+	const header = renderStatusLine({ icon: "error", title: "Web Search", description: providerLabel }, theme);
+	const body = theme.fg("error", `Error: ${replaceTabs(message)}`);
+	const outputBlock = new CachedOutputBlock();
+	return markFramedBlockComponent({
+		render(width: number): string[] {
+			return outputBlock.render({ header, state: "error", sections: [{ lines: [body] }], width }, theme);
+		},
+		invalidate() {
+			outputBlock.invalidate();
+		},
+	});
+}
+
 /** Render web search result with tree-based layout */
 export function renderSearchResult(
 	result: { content: Array<{ type: string; text?: string }>; details?: SearchRenderDetails },
@@ -78,9 +86,12 @@ export function renderSearchResult(
 ): Component {
 	const details = result.details;
 
-	// Handle error case
+	// Handle error case as a framed panel, matching the success layout.
 	if (details?.error) {
-		return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+		const errorProvider = details.response?.provider;
+		const errorProviderLabel =
+			errorProvider && errorProvider !== "none" ? getSearchProviderLabel(errorProvider) : undefined;
+		return renderSearchErrorPanel(details.error, errorProviderLabel, theme);
 	}
 
 	const rawText = result.content?.find(block => block.type === "text")?.text?.trim() ?? "";
@@ -91,8 +102,6 @@ export function renderSearchResult(
 
 	const sources = Array.isArray(response.sources) ? response.sources : [];
 	const sourceCount = sources.length;
-	const citations = Array.isArray(response.citations) ? response.citations : [];
-	const citationCount = citations.length;
 	const searchQueries = Array.isArray(response.searchQueries)
 		? response.searchQueries.filter(item => typeof item === "string")
 		: [];
@@ -118,16 +127,11 @@ export function renderSearchResult(
 		theme,
 	);
 
-	const metaLines: string[] = [];
-	metaLines.push(`${theme.fg("muted", "Provider:")} ${theme.fg("text", providerLabel)}`);
-	if (response.authMode)
-		metaLines.push(
-			`${theme.fg("muted", "Auth:")} ${theme.fg("text", response.authMode === "oauth" ? "OAuth" : response.authMode === "api_key" ? "API key" : response.authMode)}`,
-		);
-	if (response.model) metaLines.push(`${theme.fg("muted", "Model:")} ${theme.fg("text", response.model)}`);
-	metaLines.push(`${theme.fg("muted", "Sources:")} ${theme.fg("text", String(sourceCount))}`);
-	if (citationCount > 0)
-		metaLines.push(`${theme.fg("muted", "Citations:")} ${theme.fg("text", String(citationCount))}`);
+	const authShort =
+		response.authMode === "oauth" ? "OAuth" : response.authMode === "api_key" ? "API" : response.authMode;
+	let providerInfo = response.model ? `${response.model} @ ${providerLabel}` : providerLabel;
+	if (authShort) providerInfo += ` (${authShort})`;
+	const metaLines: string[] = [`${theme.fg("muted", "Provider:")} ${theme.fg("text", providerInfo)}`];
 	if (response.usage) {
 		const usageParts: string[] = [];
 		if (response.usage.inputTokens !== undefined) usageParts.push(`in ${response.usage.inputTokens}`);
@@ -137,17 +141,6 @@ export function renderSearchResult(
 		if (usageParts.length > 0)
 			metaLines.push(`${theme.fg("muted", "Usage:")} ${theme.fg("text", usageParts.join(theme.sep.dot))}`);
 	}
-	if (response.requestId) {
-		metaLines.push(
-			`${theme.fg("muted", "Request:")} ${theme.fg("text", truncateToWidth(response.requestId, MAX_REQUEST_ID_LEN))}`,
-		);
-	}
-	if (searchQueries.length > 0) {
-		const queriesPreview = searchQueries.slice(0, MAX_QUERY_PREVIEW);
-		const queryList = queriesPreview.map(q => truncateToWidth(q, MAX_QUERY_LEN));
-		const suffix = searchQueries.length > queriesPreview.length ? "…" : "";
-		metaLines.push(`${theme.fg("muted", "Queries:")} ${theme.fg("text", queryList.join("; "))}${suffix}`);
-	}
 
 	const answerMarkdown = contentText ? new Markdown(contentText, 0, 0, getMarkdownTheme()) : undefined;
 	const outputBlock = new CachedOutputBlock();
@@ -163,15 +156,15 @@ export function renderSearchResult(
 			let answerLines: string[];
 			if (renderedAnswer.length === 0) {
 				answerLines = [theme.fg("muted", "No answer text returned")];
-			} else if (expanded) {
-				answerLines = renderedAnswer;
-			} else {
-				const collapsedCap = args?.maxAnswerLines ?? MAX_COLLAPSED_ANSWER_LINES;
-				answerLines = renderedAnswer.slice(0, collapsedCap);
+			} else if (args?.maxAnswerLines !== undefined && !expanded) {
+				// CLI compact mode (`omp q`) caps the answer; the TUI passes no cap and shows it in full.
+				answerLines = renderedAnswer.slice(0, args.maxAnswerLines);
 				const remaining = renderedAnswer.length - answerLines.length;
 				if (remaining > 0) {
 					answerLines.push(theme.fg("muted", formatMoreItems(remaining, "line")));
 				}
+			} else {
+				answerLines = renderedAnswer;
 			}
 
 			const sourceTree = renderTreeList(
@@ -187,30 +180,22 @@ export function renderSearchResult(
 								: typeof src.url === "string" && src.url.trim()
 									? src.url
 									: "Untitled";
-						const title = truncateToWidth(titleText, MAX_SNIPPET_LINE_LEN);
 						const url = typeof src.url === "string" ? src.url : "";
 						const domain = url ? getDomain(url) : "";
 						const age =
 							formatAge(src.ageSeconds) || (typeof src.publishedDate === "string" ? src.publishedDate : "");
 						const metaParts: string[] = [];
 						if (domain) metaParts.push(theme.fg("dim", `(${domain})`));
-						if (typeof src.author === "string" && src.author.trim())
-							metaParts.push(theme.fg("muted", truncateToWidth(src.author.trim(), 40)));
 						if (age) metaParts.push(theme.fg("muted", age));
 						const metaSep = theme.fg("dim", theme.sep.dot);
 						const metaSuffix = metaParts.length > 0 ? ` ${metaParts.join(metaSep)}` : "";
-						const srcLines: string[] = [
-							truncateToWidth(`${theme.fg("accent", title)}${metaSuffix}`, MAX_SNIPPET_LINE_LEN),
-						];
-						const snippetText = typeof src.snippet === "string" ? src.snippet : "";
-						if (snippetText.trim()) {
-							const snippetLines = getPreviewLines(snippetText, MAX_SNIPPET_LINES, MAX_SNIPPET_LINE_LEN);
-							for (const snippetLine of snippetLines) {
-								srcLines.push(theme.fg("muted", `${theme.format.dash} ${snippetLine}`));
-							}
-						}
-						if (url) srcLines.push(theme.fg("mdLinkUrl", truncateToWidth(url, MAX_SNIPPET_LINE_LEN)));
-						return srcLines;
+						// One line per source: the title links to its URL, followed by domain · age.
+						// Reserve room for the box borders, the tree branch, and the meta suffix.
+						const lineBudget = Math.max(24, width - 6);
+						const titleBudget = Math.max(12, lineBudget - Bun.stringWidth(metaSuffix));
+						const title = theme.fg("accent", truncateToWidth(titleText, titleBudget));
+						const linkedTitle = url ? urlHyperlink(url, title) : title;
+						return [`${linkedTitle}${metaSuffix}`];
 					},
 				},
 				theme,

From c642232266794d38dd8d48f24cd83dcd860dc7b3 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 19:02:16 +0200
Subject: [PATCH 011/181] ux(coding-agent/tools): improved tool error rendering
 with subordinate detail lines

- Added sanitizeErrorText in render-utils to normalize and truncate tool error messages.
- Introduced formatErrorDetail for indented subordinate error text without redundant icon or Error prefix.
- Updated goal and write tool renderers to use the new detail formatter, with write now handling isError results via a status header plus detail line.
---
 .../coding-agent/src/goals/tools/goal-tool.ts |  4 ++--
 .../coding-agent/src/tools/render-utils.ts    | 20 ++++++++++++++++---
 packages/coding-agent/src/tools/write.ts      | 12 ++++++++++-
 3 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/packages/coding-agent/src/goals/tools/goal-tool.ts b/packages/coding-agent/src/goals/tools/goal-tool.ts
index 1c94cb54f..539597945 100644
--- a/packages/coding-agent/src/goals/tools/goal-tool.ts
+++ b/packages/coding-agent/src/goals/tools/goal-tool.ts
@@ -8,7 +8,7 @@ import type { Theme, ThemeColor } from "../../modes/theme/theme";
 import goalDescription from "../../prompts/tools/goal.md" with { type: "text" };
 import { formatDuration } from "../../slash-commands/helpers/format";
 import type { ToolSession } from "../../tools";
-import { formatErrorMessage, TRUNCATE_LENGTHS } from "../../tools/render-utils";
+import { formatErrorDetail, TRUNCATE_LENGTHS } from "../../tools/render-utils";
 import { ToolError } from "../../tools/tool-errors";
 import { renderStatusLine, truncateToWidth } from "../../tui";
 import { completionBudgetReport, remainingTokens } from "../runtime";
@@ -190,7 +190,7 @@ export const goalToolRenderer = {
 
 		if (result.isError) {
 			const header = renderStatusLine({ icon: "error", title: "Goal", description }, uiTheme);
-			const body = formatErrorMessage(fallbackText || "Goal tool failed", uiTheme);
+			const body = formatErrorDetail(fallbackText || "Goal tool failed", uiTheme);
 			return new Text([header, body].join("\n"), 0, 0);
 		}
 
diff --git a/packages/coding-agent/src/tools/render-utils.ts b/packages/coding-agent/src/tools/render-utils.ts
index b44033f4e..b96931dae 100644
--- a/packages/coding-agent/src/tools/render-utils.ts
+++ b/packages/coding-agent/src/tools/render-utils.ts
@@ -221,10 +221,24 @@ export function formatMeta(meta: string[], theme: Theme): string {
 	return meta.length > 0 ? ` ${theme.fg("muted", meta.join(theme.sep.dot))}` : "";
 }
 
-export function formatErrorMessage(message: string | undefined, theme: Theme): string {
+function sanitizeErrorText(message: string | undefined): string {
 	const clean = (message ?? "").replace(/^Error:\s*/, "").trim();
-	const safe = clean ? replaceTabs(truncateToWidth(clean, TRUNCATE_LENGTHS.LINE)) : "Unknown error";
-	return `${theme.styledSymbol("status.error", "error")} ${theme.fg("error", `Error: ${safe}`)}`;
+	return clean ? replaceTabs(truncateToWidth(clean, TRUNCATE_LENGTHS.LINE)) : "Unknown error";
+}
+
+export function formatErrorMessage(message: string | undefined, theme: Theme): string {
+	return `${theme.styledSymbol("status.error", "error")} ${theme.fg("error", `Error: ${sanitizeErrorText(message)}`)}`;
+}
+
+/**
+ * Error message rendered as a subordinate detail line beneath a status header
+ * that already carries the error icon (e.g. `✘ Write: <path>`). The header's
+ * icon already signals failure, so this omits the redundant error symbol and
+ * "Error:" prefix that `formatErrorMessage` adds for standalone single-line
+ * errors, indenting two columns to sit under the header title instead.
+ */
+export function formatErrorDetail(message: string | undefined, theme: Theme): string {
+	return `  ${theme.fg("error", sanitizeErrorText(message))}`;
 }
 
 export function formatEmptyMessage(message: string, theme: Theme): string {
diff --git a/packages/coding-agent/src/tools/write.ts b/packages/coding-agent/src/tools/write.ts
index 3b0115498..4c1d92af4 100644
--- a/packages/coding-agent/src/tools/write.ts
+++ b/packages/coding-agent/src/tools/write.ts
@@ -37,6 +37,7 @@ import { formatPathRelativeToCwd, isInternalUrlPath } from "./path-utils";
 import { enforcePlanModeWrite, resolvePlanPath } from "./plan-mode-guard";
 import {
 	formatDiagnostics,
+	formatErrorDetail,
 	formatExpandHint,
 	formatMoreItems,
 	formatStatusIcon,
@@ -1021,7 +1022,7 @@ export const writeToolRenderer = {
 	},
 
 	renderResult(
-		result: { content: Array<{ type: string; text?: string }>; details?: WriteToolDetails },
+		result: { content: Array<{ type: string; text?: string }>; details?: WriteToolDetails; isError?: boolean },
 		options: RenderResultOptions,
 		uiTheme: Theme,
 		args?: WriteRenderArgs,
@@ -1032,6 +1033,15 @@ export const writeToolRenderer = {
 		const lang = getLanguageFromPath(rawPath);
 		const langIcon = uiTheme.fg("muted", uiTheme.getLangIcon(lang));
 		const pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
+
+		if (result.isError) {
+			const errorText = result.content?.find(c => c.type === "text")?.text ?? "";
+			const errorHeader = renderStatusLine(
+				{ icon: "error", title: "Write", description: `${langIcon} ${pathDisplay}` },
+				uiTheme,
+			);
+			return new Text(`${errorHeader}\n${formatErrorDetail(errorText, uiTheme)}`, 0, 0);
+		}
 		const lineCount = countLines(fileContent);
 		const lineSuffix = formatLineCountSuffix(lineCount, uiTheme);
 		const execSuffix = result.details?.madeExecutable

From ead5cf687105580492ad75104fd86a7748e93e64 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 19:05:20 +0200
Subject: [PATCH 012/181] fix(coding-agent/scripts): fixed CLI startup by
 launching through a bunfig-free shim script

- Updated `install:dev` to symlink `packages/coding-agent/scripts/dev-launch` into Bun's global bin directory as `omp`.
- Added a `dev-launch` shell script that launches Bun from an isolated directory and preserves the caller's working directory for restoration.
- Added a preload shim that restores `OMP_LAUNCH_CWD` before CLI execution so external project `bunfig.toml` preloads are not used.
---
 package.json                                  |  2 +-
 packages/coding-agent/CHANGELOG.md            |  1 +
 packages/coding-agent/scripts/dev-launch      | 38 +++++++++++++++++++
 .../scripts/dev-launch-preload.ts             | 19 ++++++++++
 4 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100755 packages/coding-agent/scripts/dev-launch
 create mode 100644 packages/coding-agent/scripts/dev-launch-preload.ts

diff --git a/package.json b/package.json
index a936a6642..542faa00e 100644
--- a/package.json
+++ b/package.json
@@ -85,7 +85,7 @@
   },
   "overrides": {},
   "scripts": {
-    "install:dev": "bun install && bun --cwd=packages/coding-agent link && bun --cwd=packages/ai link",
+    "install:dev": "bun install && bun --cwd=packages/coding-agent link && ln -sfn \"$(pwd)/packages/coding-agent/scripts/dev-launch\" \"$(bun pm -g bin)/omp\"",
     "dev": "bun --cwd=packages/coding-agent src/cli.ts",
     "stats": "bun --cwd=packages/coding-agent src/cli.ts stats",
     "claude:trace": "bun scripts/claude-trace.ts",
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 3dc36cc36..735d4b643 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -20,6 +20,7 @@
 - Fixed collapsed search result previews that could show only "… N more matches" when the first grouped section exceeded the preview budget. Collapsed search output now compacts to match rows, fills the budget with visible hits before the summary, and keeps truncation details out of the bottom user-visible notice.
 - Fixed boolean environment flag overrides that were ORed with settings, so `PI_INTENT_TRACING=0`, `PI_AUTO_QA=0`, and per-backend eval flags now take precedence when present while falling back to config when unset.
 - Fixed custom-rendered tools that set `mergeCallAndResult` (e.g. `lsp`) rendering a redundant tool-name line above the framed result once a result arrived. `ToolExecutionComponent`'s custom-tool branch now emits the fallback label only when the tool has no `renderCall` and the call is not suppressed by an existing result, matching the built-in renderer branch.
+- Fixed the `write` tool result rendering with a green success checkmark even when the write failed. `writeToolRenderer.renderResult` now branches on `result.isError`, rendering the error status icon plus the failure message instead of the success header and content preview.
 
 ## [15.9.67] - 2026-06-06
 ### Added
diff --git a/packages/coding-agent/scripts/dev-launch b/packages/coding-agent/scripts/dev-launch
new file mode 100755
index 000000000..519ccff0f
--- /dev/null
+++ b/packages/coding-agent/scripts/dev-launch
@@ -0,0 +1,38 @@
+#!/bin/sh
+# Dev launcher for the omp CLI, installed by `bun run install:dev`.
+#
+# Problem it solves: Bun reads `bunfig.toml` from the *current working
+# directory* at startup and evaluates its `preload` entries before running the
+# script. A bun-shebang bin (what `bun link` creates for `src/cli.ts`)
+# therefore inherits whatever `preload` the directory you happen to be in
+# declares. Running `omp`/`pi` inside an unrelated Bun project can execute — and
+# crash on — that project's preload, e.g.
+#   error: Cannot find module '@v12sh/utils/frontmatter' from '.../loader.ts'
+#
+# Bun only reads the *exact* cwd (it does not walk parents) and ignores
+# `--config`/`BUN_BE_BUN` for this, so the fix is to launch Bun from an empty,
+# bunfig-free directory and restore the real cwd inside the process via the
+# preload shim alongside this file.
+set -e
+
+# Resolve this script's real location even when invoked through a symlink
+# (`$HOME/.bun/bin/omp` -> this file).
+self=$0
+while [ -L "$self" ]; do
+	link=$(readlink "$self")
+	case $link in
+	/*) self=$link ;;
+	*) self=$(dirname "$self")/$link ;;
+	esac
+done
+scripts_dir=$(CDPATH= cd -- "$(dirname -- "$self")" && pwd -P)
+cli=$scripts_dir/../src/cli.ts
+preload=$scripts_dir/dev-launch-preload.ts
+
+launch_dir=${OMP_DEV_LAUNCH_DIR:-${HOME}/.omp/.dev-cwd}
+mkdir -p "$launch_dir"
+
+OMP_LAUNCH_CWD=$PWD
+export OMP_LAUNCH_CWD
+cd "$launch_dir"
+exec bun --preload "$preload" "$cli" "$@"
diff --git a/packages/coding-agent/scripts/dev-launch-preload.ts b/packages/coding-agent/scripts/dev-launch-preload.ts
new file mode 100644
index 000000000..5cafa09ad
--- /dev/null
+++ b/packages/coding-agent/scripts/dev-launch-preload.ts
@@ -0,0 +1,19 @@
+/**
+ * Bun `--preload` shim for the omp dev launcher (`scripts/dev-launch`).
+ *
+ * The launcher starts Bun from an empty, bunfig-free directory so a foreign
+ * project's `bunfig.toml` `preload` cannot run inside the omp CLI: Bun reads
+ * `bunfig.toml` from the *current working directory* on startup and evaluates
+ * its `preload` entries before the entrypoint, so a bun-shebang bin inherits
+ * whatever `preload` the directory you launched from declares (and crashes if
+ * that preload can't resolve). This shim is loaded before the entrypoint's
+ * imports run, so it restores the user's real working directory in time for
+ * import-time snapshots (e.g. `getProjectDir()` in `@oh-my-pi/pi-utils/dirs`).
+ */
+const launchCwd = process.env.OMP_LAUNCH_CWD;
+if (launchCwd) {
+	delete process.env.OMP_LAUNCH_CWD;
+	try {
+		process.chdir(launchCwd);
+	} catch {}
+}

From 2887eec37385522fc1b91260f5e8fa49b5b54681 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 19:05:53 +0200
Subject: [PATCH 013/181] feat(cli): added PNG screenshot support for the
 gallery CLI command

- Added `omp gallery --screenshot`, `--out`, `--font`, and `--font-size` flags.
- Added a VHS-based screenshot path that captures gallery output as PNG file(s).
- Added chunking and naming logic to split tall galleries into multiple numbered captures.
---
 packages/coding-agent/CHANGELOG.md            |   1 +
 packages/coding-agent/src/cli/gallery-cli.ts  |  88 ++++--
 .../src/cli/gallery-screenshot.ts             | 279 ++++++++++++++++++
 packages/coding-agent/src/commands/gallery.ts |  15 +
 4 files changed, 360 insertions(+), 23 deletions(-)
 create mode 100644 packages/coding-agent/src/cli/gallery-screenshot.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 735d4b643..794ec90fc 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -6,6 +6,7 @@
 - Added `gallery` CLI command to render built-in tool renderer output across streaming, in-progress, success, and failure states
 - Added `omp gallery` filtering and rendering options (`--tool`, `--state`, `--width`, `--expanded`, and `--plain`) for focused renderer previews and plain-text output
 - Added `omp gallery` fidelity for tools whose renderers are attached on the tool instance (`lsp`, `task`): the gallery now drives them through the same custom-tool render branch production uses, so regressions in that path surface in the gallery rather than only in a live session.
+- Added `omp gallery --screenshot`, which renders the gallery through a real virtual terminal (VHS) and writes PNG screenshot(s) instead of ANSI, so agents (and anything that can only read raw bytes) can actually see the rendered output. The capture forces truecolor and matches the active theme/symbol preset; tall galleries split across multiple images (whole renderers are never cut). Tune with `--out`, `--font`, and `--font-size`; requires `vhs` on `PATH` and fails with install guidance when absent.
 - Added `app.display.reset`, bound to `Ctrl+L` by default, to force an immediate terminal display reset/redraw without resizing the window.
 
 ### Changed
diff --git a/packages/coding-agent/src/cli/gallery-cli.ts b/packages/coding-agent/src/cli/gallery-cli.ts
index 921e571db..7f52ec956 100644
--- a/packages/coding-agent/src/cli/gallery-cli.ts
+++ b/packages/coding-agent/src/cli/gallery-cli.ts
@@ -15,6 +15,7 @@ import { ToolExecutionComponent } from "../modes/components/tool-execution";
 import { initTheme, theme } from "../modes/theme/theme";
 import { toolRenderers } from "../tools/renderers";
 import { type GalleryFixture, type GalleryResult, galleryFixtures } from "./gallery-fixtures";
+import { captureGalleryScreenshots } from "./gallery-screenshot";
 
 /** Lifecycle states the gallery renders, in display order. */
 export const GALLERY_STATES = ["streaming", "progress", "success", "error"] as const;
@@ -38,6 +39,20 @@ export interface GalleryCommandArgs {
 	expanded?: boolean;
 	/** Strip ANSI styling from the output (useful when redirecting to a file). */
 	plain?: boolean;
+	/** Capture the rendered gallery as PNG screenshot(s) via VHS instead of printing ANSI. */
+	screenshot?: boolean;
+	/** Screenshot output path (single image) or base path (suffixed when split across images). */
+	out?: string;
+	/** Font family for screenshots (must be installed; Nerd Font recommended for icon glyphs). */
+	font?: string;
+	/** Font size in points for screenshots. */
+	fontSize?: number;
+}
+
+/** One tool's rendered lifecycle, as ANSI lines: a leading blank, the section rule, then each state. */
+export interface GallerySection {
+	heading: string;
+	lines: string[];
 }
 
 const GENERIC_ERROR: GalleryResult = {
@@ -130,11 +145,45 @@ function sectionRule(label: string, width: number): string {
 }
 
 /**
- * Render the gallery to stdout. Iterates the renderer registry (or a single
- * tool), printing each requested lifecycle state under a labeled section.
+ * Render each requested tool's lifecycle into ANSI section blocks. The block
+ * layout (leading blank, section rule, then a blank + dim label + body per
+ * state) is shared by the stdout and screenshot paths so both stay identical.
+ */
+async function renderGallerySections(
+	names: string[],
+	states: GalleryState[],
+	width: number,
+	expanded: boolean,
+): Promise<GallerySection[]> {
+	const sections: GallerySection[] = [];
+	for (const name of names) {
+		const fixture = resolveFixture(name);
+		const heading = fixture.label && fixture.label !== name ? `${name} — ${fixture.label}` : name;
+		const lines: string[] = ["", sectionRule(heading, width)];
+		for (const state of states) {
+			lines.push("", theme.fg("dim", `  · ${STATE_LABELS[state]}`));
+			try {
+				for (const line of await renderGalleryState(name, fixture, state, width, expanded)) lines.push(line);
+			} catch (err) {
+				lines.push(theme.fg("error", `  render failed: ${String(err)}`));
+			}
+		}
+		sections.push({ heading, lines });
+	}
+	return sections;
+}
+
+/**
+ * Render the gallery. Iterates the renderer registry (or a single tool),
+ * printing each requested lifecycle state under a labeled section — or, with
+ * `screenshot`, capturing the rendered output as PNG(s) via VHS.
  */
 export async function runGalleryCommand(args: GalleryCommandArgs): Promise<void> {
 	const settingsInstance = await Settings.init();
+	// Screenshots must carry exact theme RGB regardless of how the invoking
+	// terminal advertises its color support, so force truecolor before the theme
+	// (and therefore every SGR escape it emits) is built.
+	if (args.screenshot) process.env.COLORTERM = "truecolor";
 	await initTheme(
 		false,
 		settingsInstance.get("symbolPreset"),
@@ -154,28 +203,21 @@ export async function runGalleryCommand(args: GalleryCommandArgs): Promise<void>
 		return;
 	}
 
-	const out: string[] = [];
-	const push = (line: string) => out.push(args.plain ? Bun.stripANSI(line) : line);
+	const sections = await renderGallerySections(names, states, width, expanded);
 
-	for (const name of names) {
-		const fixture = resolveFixture(name);
-		const heading = fixture.label && fixture.label !== name ? `${name} — ${fixture.label}` : name;
-		push("");
-		push(sectionRule(heading, width));
-
-		for (const state of states) {
-			push("");
-			push(theme.fg("dim", `  · ${STATE_LABELS[state]}`));
-			let lines: string[];
-			try {
-				lines = await renderGalleryState(name, fixture, state, width, expanded);
-			} catch (err) {
-				lines = [theme.fg("error", `  render failed: ${String(err)}`)];
-			}
-			for (const line of lines) push(line);
-		}
+	if (args.screenshot) {
+		const paths = await captureGalleryScreenshots(sections, {
+			width,
+			font: args.font,
+			fontSize: args.fontSize,
+			out: args.out,
+		});
+		process.stdout.write(`${paths.join("\n")}\n`);
+		return;
 	}
-	push("");
 
-	process.stdout.write(`${out.join("\n")}\n`);
+	const lines = sections.flatMap(section => section.lines);
+	lines.push("");
+	const text = lines.map(line => (args.plain ? Bun.stripANSI(line) : line)).join("\n");
+	process.stdout.write(`${text}\n`);
 }
diff --git a/packages/coding-agent/src/cli/gallery-screenshot.ts b/packages/coding-agent/src/cli/gallery-screenshot.ts
new file mode 100644
index 000000000..05ba3eafa
--- /dev/null
+++ b/packages/coding-agent/src/cli/gallery-screenshot.ts
@@ -0,0 +1,279 @@
+/**
+ * Render `omp gallery` output to PNG screenshots via VHS.
+ *
+ * ANSI escapes are invisible to anything that can only read raw bytes (e.g.
+ * agents), so `--screenshot` drives the rendered gallery through a real virtual
+ * terminal (VHS + ttyd + ffmpeg) and writes the captured frame to disk. The
+ * gallery is pre-rendered to truecolor ANSI in this process — where the user's
+ * theme and symbol preset are correct — then `cat`'d inside VHS so the captured
+ * pixels match exactly what the live TUI would draw.
+ *
+ * VHS is a hard dependency of this path: if it is not installed we fail loudly
+ * rather than degrade to a lossy fallback.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $which } from "@oh-my-pi/pi-utils";
+import { theme } from "../modes/theme/theme";
+import type { GallerySection } from "./gallery-cli";
+
+/** Nerd Font family so the gallery's icon glyphs (PUA) render instead of tofu. */
+export const DEFAULT_SCREENSHOT_FONT = "JetBrainsMono Nerd Font";
+export const DEFAULT_SCREENSHOT_FONT_SIZE = 18;
+
+/** Inner padding (px) VHS leaves around the terminal grid. */
+const PADDING = 14;
+const LINE_HEIGHT = 1.0;
+/**
+ * Upper-bound cell metrics relative to font size. Real monospace cells are
+ * smaller, so over-provisioning the canvas guarantees the gallery never
+ * soft-wraps (too few columns) or scrolls off the top (too few rows). The slack
+ * shows up only as a modest background margin, which is harmless for review.
+ */
+const CELL_WIDTH_RATIO = 0.65;
+const CELL_HEIGHT_RATIO = 1.5;
+/** Keep each image well under headless-Chromium's tall-canvas limits. */
+const MAX_IMAGE_HEIGHT_PX = 8000;
+
+export interface GalleryScreenshotOptions {
+	/** Gallery render width in columns (matches the ANSI line width). */
+	width: number;
+	/** VHS `FontFamily`. */
+	font?: string;
+	/** VHS `FontSize`. */
+	fontSize?: number;
+	/**
+	 * Output destination. When omitted, PNGs land in a fresh temp directory.
+	 * With multiple images the path is suffixed (`name-01.png`, `name-02.png`).
+	 */
+	out?: string;
+}
+
+/**
+ * Capture the gallery sections as one or more PNGs and return their absolute
+ * paths. Tall galleries are split across images so no single capture exceeds
+ * the terminal-canvas height limit.
+ */
+export async function captureGalleryScreenshots(
+	sections: GallerySection[],
+	options: GalleryScreenshotOptions,
+): Promise<string[]> {
+	const vhs = $which("vhs");
+	if (!vhs) {
+		throw new Error(
+			"`omp gallery --screenshot` requires VHS, which is not installed. " +
+				"Install it (e.g. `brew install vhs`, or see https://github.com/charmbracelet/vhs) and retry.",
+		);
+	}
+
+	const font = options.font ?? DEFAULT_SCREENSHOT_FONT;
+	const fontSize = options.fontSize ?? DEFAULT_SCREENSHOT_FONT_SIZE;
+	const cellHeight = fontSize * Math.max(LINE_HEIGHT, 1) * CELL_HEIGHT_RATIO;
+	const cellWidth = fontSize * CELL_WIDTH_RATIO;
+	const rowBudget = Math.max(40, Math.floor((MAX_IMAGE_HEIGHT_PX - 2 * PADDING) / cellHeight) - 2);
+	const chunks = chunkGallerySections(sections, rowBudget);
+	const themeJson = buildVhsTheme();
+
+	const baseDir = options.out
+		? path.dirname(path.resolve(options.out))
+		: fs.mkdtempSync(path.join(os.tmpdir(), "omp-gallery-"));
+	await fs.promises.mkdir(baseDir, { recursive: true });
+
+	const outPaths: string[] = [];
+	for (let i = 0; i < chunks.length; i++) {
+		if (chunks.length > 1) {
+			process.stderr.write(`Rendering gallery screenshot ${i + 1}/${chunks.length}…\n`);
+		}
+		const outPng = resolveScreenshotOutputPath(options.out, baseDir, i, chunks.length);
+		const lines = chunks[i].flatMap(section => section.lines);
+		await renderChunk({ vhs, lines, outPng, font, fontSize, cellWidth, cellHeight, width: options.width, themeJson });
+		outPaths.push(outPng);
+	}
+	return outPaths;
+}
+
+interface RenderChunkArgs {
+	vhs: string;
+	lines: string[];
+	outPng: string;
+	font: string;
+	fontSize: number;
+	cellWidth: number;
+	cellHeight: number;
+	width: number;
+	themeJson: string;
+}
+
+async function renderChunk(args: RenderChunkArgs): Promise<void> {
+	const rows = args.lines.length;
+	const widthPx = Math.ceil(args.width * args.cellWidth) + 2 * PADDING;
+	const heightPx = Math.ceil((rows + 2) * args.cellHeight) + 2 * PADDING;
+
+	const dir = path.dirname(args.outPng);
+	const stem = path.basename(args.outPng, path.extname(args.outPng));
+	const ansiPath = path.join(dir, `.${stem}.ansi`);
+	const tapePath = path.join(dir, `.${stem}.tape`);
+	const gifPath = path.join(dir, `.${stem}.gif`);
+
+	// CRLF so each gallery line is its own terminal row regardless of how the
+	// captured shell handles bare LF.
+	await Bun.write(ansiPath, `${args.lines.join("\r\n")}\r\n`);
+	await Bun.write(
+		tapePath,
+		buildTape({
+			gifPath,
+			outPng: args.outPng,
+			ansiPath,
+			widthPx,
+			heightPx,
+			font: args.font,
+			fontSize: args.fontSize,
+			themeJson: args.themeJson,
+		}),
+	);
+
+	try {
+		const result = await Bun.$`${args.vhs} ${tapePath}`.quiet().nothrow();
+		if (result.exitCode !== 0 || !(await Bun.file(args.outPng).exists())) {
+			const detail = result.stderr.toString().trim() || result.stdout.toString().trim();
+			throw new Error(`VHS failed to render the gallery screenshot${detail ? `: ${detail.slice(-600)}` : ""}`);
+		}
+	} finally {
+		await Promise.all([
+			fs.promises.rm(ansiPath, { force: true }),
+			fs.promises.rm(tapePath, { force: true }),
+			fs.promises.rm(gifPath, { force: true }),
+		]);
+	}
+}
+
+interface TapeArgs {
+	gifPath: string;
+	outPng: string;
+	ansiPath: string;
+	widthPx: number;
+	heightPx: number;
+	font: string;
+	fontSize: number;
+	themeJson: string;
+}
+
+function buildTape(args: TapeArgs): string {
+	// `Output` (a throwaway GIF) is mandatory for VHS to record; the screenshot
+	// is captured from the final visible frame. Setup is hidden so the typed
+	// `cat` command and shell prompt never appear in the capture, and a trailing
+	// `sleep` keeps the shell from drawing a fresh prompt under the output.
+	const shellCommand = `clear; cat ${shellSingleQuote(args.ansiPath)}; sleep 120`;
+	return `${[
+		`Output ${JSON.stringify(args.gifPath)}`,
+		`Set Width ${args.widthPx}`,
+		`Set Height ${args.heightPx}`,
+		`Set FontFamily ${JSON.stringify(args.font)}`,
+		`Set FontSize ${args.fontSize}`,
+		`Set Padding ${PADDING}`,
+		`Set LineHeight ${LINE_HEIGHT}`,
+		`Set Theme ${args.themeJson}`,
+		"Hide",
+		`Type ${JSON.stringify(shellCommand)}`,
+		"Enter",
+		"Sleep 1.2s",
+		"Show",
+		"Sleep 400ms",
+		`Screenshot ${JSON.stringify(args.outPng)}`,
+	].join("\n")}\n`;
+}
+
+/**
+ * Build the VHS terminal theme. Only background/foreground/cursor matter: the
+ * gallery emits truecolor (`38;2`/`48;2`) escapes, so the 16-color palette is
+ * never consulted — it is filler to satisfy VHS's theme schema.
+ */
+function buildVhsTheme(): string {
+	const background = parseAnsiRgb(theme.getBgAnsi("statusLineBg")) ?? (theme.isLight ? "#ffffff" : "#1a1a1a");
+	const foreground = theme.isLight ? "#1a1a1a" : "#d4d4d4";
+	const selection = theme.isLight ? "#c8d6ff" : "#404862";
+	return JSON.stringify({
+		name: "omp-gallery",
+		background,
+		foreground,
+		cursor: foreground,
+		selection,
+		black: "#000000",
+		red: "#ff5555",
+		green: "#50fa7b",
+		yellow: "#f1fa8c",
+		blue: "#6272ff",
+		magenta: "#ff79c6",
+		cyan: "#8be9fd",
+		white: "#bfbfbf",
+		brightBlack: "#4d4d4d",
+		brightRed: "#ff6e6e",
+		brightGreen: "#69ff94",
+		brightYellow: "#ffffa5",
+		brightBlue: "#8aa0ff",
+		brightMagenta: "#ff92df",
+		brightCyan: "#a4ffff",
+		brightWhite: "#ffffff",
+	});
+}
+
+/** Extract `#rrggbb` from a truecolor SGR escape (`…38;2;r;g;b…` / `…48;2;…`). */
+function parseAnsiRgb(ansi: string): string | undefined {
+	const match = /[34]8;2;(\d+);(\d+);(\d+)/.exec(ansi);
+	if (!match) return undefined;
+	const hex = (value: string) => Number(value).toString(16).padStart(2, "0");
+	return `#${hex(match[1])}${hex(match[2])}${hex(match[3])}`;
+}
+
+/** POSIX single-quote a path for embedding in the VHS shell command. */
+function shellSingleQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * Resolve a chunk's PNG path. A single image keeps the bare name (or the exact
+ * `out`); multiple images gain a zero-padded `-NN` suffix so they sort and never
+ * collide.
+ */
+export function resolveScreenshotOutputPath(
+	out: string | undefined,
+	baseDir: string,
+	index: number,
+	total: number,
+): string {
+	if (total === 1) {
+		return out ? path.resolve(out) : path.join(baseDir, "gallery.png");
+	}
+	const suffix = String(index + 1).padStart(2, "0");
+	if (out) {
+		const resolved = path.resolve(out);
+		const ext = path.extname(resolved) || ".png";
+		const stem = path.basename(resolved, ext);
+		return path.join(path.dirname(resolved), `${stem}-${suffix}${ext}`);
+	}
+	return path.join(baseDir, `gallery-${suffix}.png`);
+}
+
+/**
+ * Group whole tool sections into chunks that stay under `rowBudget` rows. A
+ * single section larger than the budget gets its own (taller) image rather than
+ * being split mid-renderer.
+ */
+export function chunkGallerySections(sections: GallerySection[], rowBudget: number): GallerySection[][] {
+	const chunks: GallerySection[][] = [];
+	let current: GallerySection[] = [];
+	let currentRows = 0;
+	for (const section of sections) {
+		const rows = section.lines.length;
+		if (current.length > 0 && currentRows + rows > rowBudget) {
+			chunks.push(current);
+			current = [];
+			currentRows = 0;
+		}
+		current.push(section);
+		currentRows += rows;
+	}
+	if (current.length > 0) chunks.push(current);
+	return chunks.length > 0 ? chunks : [[]];
+}
diff --git a/packages/coding-agent/src/commands/gallery.ts b/packages/coding-agent/src/commands/gallery.ts
index ee5b69cba..d0b878fac 100644
--- a/packages/coding-agent/src/commands/gallery.ts
+++ b/packages/coding-agent/src/commands/gallery.ts
@@ -22,6 +22,17 @@ export default class Gallery extends Command {
 			default: false,
 		}),
 		plain: Flags.boolean({ description: "Strip ANSI styling from the output", default: false }),
+		screenshot: Flags.boolean({
+			description:
+				"Capture the rendered output as PNG screenshot(s) via VHS instead of printing ANSI (requires vhs)",
+			default: false,
+		}),
+		out: Flags.string({
+			char: "o",
+			description: "Screenshot output path (with --screenshot); suffixed per image when split across multiple",
+		}),
+		font: Flags.string({ description: "Screenshot font family (default: JetBrainsMono Nerd Font)" }),
+		"font-size": Flags.integer({ description: "Screenshot font size in points (default: 18)" }),
 	};
 
 	async run(): Promise<void> {
@@ -32,6 +43,10 @@ export default class Gallery extends Command {
 			width: flags.width,
 			expanded: flags.expanded,
 			plain: flags.plain,
+			screenshot: flags.screenshot,
+			out: flags.out,
+			font: flags.font,
+			fontSize: flags["font-size"],
 		});
 	}
 }

From adcb8793b2b09239d6fa4bb65777a2eecc3e07e6 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 17:10:18 +0000
Subject: [PATCH 014/181] fix(tui): gated deccara fills on sync output

Prevented DECCARA background-fill optimization from shortening rows unless the active TUI paint is protected by synchronized output, preserving padded background bytes when sync output is disabled.

Added regression coverage for the synchronized-output opt-out path and kept existing DECCARA tests forced onto synchronized output so the optimized path remains covered.

Fixes #2000
---
 packages/tui/CHANGELOG.md         |  4 ++
 packages/tui/src/tui.ts           | 16 +++++-
 packages/tui/test/deccara.test.ts | 91 +++++++++++++++++++++++++++++++
 3 files changed, 108 insertions(+), 3 deletions(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index c023618be..40abd7bb6 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -7,6 +7,10 @@
 - Added `TUI.resetDisplay()` to force an immediate full-frame replay, including native scrollback when the host can safely clear it.
 - Added `setPaddingY` to `Box` so vertical padding can be updated programmatically after creation.
 
+### Fixed
+
+- Fixed DECCARA background-fill optimization running when synchronized output is disabled, which could expose default-background gaps during rapidly updating tool-use panels ([#2000](https://github.com/can1357/oh-my-pi/issues/2000)).
+
 ## [15.9.67] - 2026-06-06
 ### Added
 
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index d694d1af9..c568d09ea 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -571,6 +571,11 @@ export class TUI extends Container {
 	get synchronizedOutput(): boolean {
 		return this.#synchronizedOutputEnabled;
 	}
+	#deccaraFillsEnabled(): boolean {
+		// DECCARA fill rectangles arrive after shortened row text; synchronized
+		// output hides that intermediate default-background state from users.
+		return TERMINAL.deccara && this.#synchronizedOutputEnabled;
+	}
 
 	/**
 	 * When enabled, live render frames rebuild native scrollback on offscreen and
@@ -2404,7 +2409,7 @@ export class TUI extends Container {
 		const visibleStart = Math.max(0, lines.length - height);
 		let fillSequence = "";
 		let visibleTexts: string[] | null = null;
-		if (TERMINAL.deccara && visibleStart < lines.length) {
+		if (this.#deccaraFillsEnabled() && visibleStart < lines.length) {
 			const visible: string[] = new Array(lines.length - visibleStart);
 			for (let k = 0; k < visible.length; k++) {
 				visible[k] = this.#fitLineToWidth(lines[visibleStart + k], width);
@@ -2504,7 +2509,7 @@ export class TUI extends Container {
 		for (let screenRow = 0; screenRow < height; screenRow++) {
 			visible[screenRow] = this.#fitLineToWidth(lines[viewportTop + screenRow] ?? "", width);
 		}
-		const { texts, sequence } = TERMINAL.deccara
+		const { texts, sequence } = this.#deccaraFillsEnabled()
 			? planDeccaraFills(visible, width)
 			: { texts: visible, sequence: "" };
 		let buffer = `${this.#paintBeginSequence}\x1b[H`;
@@ -2814,7 +2819,12 @@ export class TUI extends Container {
 		const fillStart = Math.max(firstChanged, fillViewportTop);
 		let fillSequence = "";
 		let fillTexts: string[] | null = null;
-		if (TERMINAL.deccara && !appendStart && moveTargetRow <= prevViewportBottom && renderEnd >= fillStart) {
+		if (
+			this.#deccaraFillsEnabled() &&
+			!appendStart &&
+			moveTargetRow <= prevViewportBottom &&
+			renderEnd >= fillStart
+		) {
 			const slice: string[] = new Array(renderEnd - fillStart + 1);
 			for (let i = fillStart; i <= renderEnd; i++) {
 				slice[i - fillStart] = this.#fitLineToWidth(lines[i], width);
diff --git a/packages/tui/test/deccara.test.ts b/packages/tui/test/deccara.test.ts
index d5dd82e48..f1d0329f2 100644
--- a/packages/tui/test/deccara.test.ts
+++ b/packages/tui/test/deccara.test.ts
@@ -74,6 +74,41 @@ function countOccurrences(haystack: string, needle: string): number {
 	}
 }
 
+async function withEnvPatch<T>(patch: Record<string, string | undefined>, run: () => T | Promise<T>): Promise<T> {
+	const bunSnapshot: Record<string, string | undefined> = {};
+	const processSnapshot: Record<string, string | undefined> = {};
+	for (const key in patch) {
+		bunSnapshot[key] = Bun.env[key];
+		processSnapshot[key] = process.env[key];
+		const value = patch[key];
+		if (value === undefined) {
+			delete Bun.env[key];
+			delete process.env[key];
+		} else {
+			Bun.env[key] = value;
+			process.env[key] = value;
+		}
+	}
+	try {
+		return await run();
+	} finally {
+		for (const key in patch) {
+			const bunValue = bunSnapshot[key];
+			if (bunValue === undefined) {
+				delete Bun.env[key];
+			} else {
+				Bun.env[key] = bunValue;
+			}
+			const processValue = processSnapshot[key];
+			if (processValue === undefined) {
+				delete process.env[key];
+			} else {
+				process.env[key] = processValue;
+			}
+		}
+	}
+}
+
 describe("detectRectangularSgrSupport", () => {
 	it("enables only kitty, which implements the SGR-background extension", () => {
 		expect(detectRectangularSgrSupport("kitty", {})).toBe(true);
@@ -240,8 +275,17 @@ describe("planDeccaraFills", () => {
 
 describe("TUI DECCARA integration", () => {
 	const savedDeccara = TERMINAL.deccara;
+	const savedForceSyncOutput = Bun.env.PI_FORCE_SYNC_OUTPUT;
+	const savedNoSyncOutput = Bun.env.PI_NO_SYNC_OUTPUT;
+	const savedTuiSyncOutput = Bun.env.PI_TUI_SYNC_OUTPUT;
 
 	beforeEach(() => {
+		Bun.env.PI_FORCE_SYNC_OUTPUT = "1";
+		process.env.PI_FORCE_SYNC_OUTPUT = "1";
+		delete Bun.env.PI_NO_SYNC_OUTPUT;
+		delete process.env.PI_NO_SYNC_OUTPUT;
+		delete Bun.env.PI_TUI_SYNC_OUTPUT;
+		delete process.env.PI_TUI_SYNC_OUTPUT;
 		let monotonic = 0;
 		vi.spyOn(performance, "now").mockImplementation(() => {
 			monotonic += 20;
@@ -250,6 +294,27 @@ describe("TUI DECCARA integration", () => {
 	});
 
 	afterEach(() => {
+		if (savedForceSyncOutput === undefined) {
+			delete Bun.env.PI_FORCE_SYNC_OUTPUT;
+			delete process.env.PI_FORCE_SYNC_OUTPUT;
+		} else {
+			Bun.env.PI_FORCE_SYNC_OUTPUT = savedForceSyncOutput;
+			process.env.PI_FORCE_SYNC_OUTPUT = savedForceSyncOutput;
+		}
+		if (savedNoSyncOutput === undefined) {
+			delete Bun.env.PI_NO_SYNC_OUTPUT;
+			delete process.env.PI_NO_SYNC_OUTPUT;
+		} else {
+			Bun.env.PI_NO_SYNC_OUTPUT = savedNoSyncOutput;
+			process.env.PI_NO_SYNC_OUTPUT = savedNoSyncOutput;
+		}
+		if (savedTuiSyncOutput === undefined) {
+			delete Bun.env.PI_TUI_SYNC_OUTPUT;
+			delete process.env.PI_TUI_SYNC_OUTPUT;
+		} else {
+			Bun.env.PI_TUI_SYNC_OUTPUT = savedTuiSyncOutput;
+			process.env.PI_TUI_SYNC_OUTPUT = savedTuiSyncOutput;
+		}
 		setTerminalDeccara(savedDeccara);
 		vi.restoreAllMocks();
 	});
@@ -299,6 +364,32 @@ describe("TUI DECCARA integration", () => {
 		}
 	});
 
+	it("keeps padded fallback bytes when synchronized output is disabled", async () => {
+		await withEnvPatch(
+			{ PI_NO_SYNC_OUTPUT: "1", PI_FORCE_SYNC_OUTPUT: undefined, PI_TUI_SYNC_OUTPUT: undefined },
+			async () => {
+				setTerminalDeccara(true);
+				const term = new VirtualTerminal(40, 8);
+				const tui = new TUI(term);
+				tui.addChild(new BgPanelComponent(["", "", "", ""]));
+				const writes = captureWrites(term);
+
+				try {
+					tui.start();
+					await settle(term);
+					const out = writes.join("");
+
+					expect(out).not.toContain("$r");
+					expect(out).not.toContain(DECSACE_RECT);
+					expect(out).toContain(`${BG_OPEN}${" ".repeat(40)}`);
+					expect(term.getViewportRowBackgroundColumns(0)).toHaveLength(40);
+				} finally {
+					tui.stop();
+				}
+			},
+		);
+	});
+
 	it("preserves viewport text identically whether DECCARA is on or off", async () => {
 		const rowsContent = ["", "Hello", "", "World", ""];
 		const trimmed = (term: VirtualTerminal) => term.getViewport().map(line => line.trimEnd());

From c43eac9d9184e7c06f8c523c4412978fc79fcf37 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 17:10:25 +0000
Subject: [PATCH 015/181] style: bun run fix

---
 packages/coding-agent/test/extensions-runner.test.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/coding-agent/test/extensions-runner.test.ts b/packages/coding-agent/test/extensions-runner.test.ts
index 1542897a9..33e188b7f 100644
--- a/packages/coding-agent/test/extensions-runner.test.ts
+++ b/packages/coding-agent/test/extensions-runner.test.ts
@@ -148,7 +148,6 @@ describe("ExtensionRunner", () => {
 			warnSpy.mockRestore();
 		});
 
-
 		it("warns when two extensions register same shortcut", async () => {
 			// Use a non-reserved shortcut
 			const extCode1 = `

From d63a91bf5eafc6256565489e16c09d58ba85b41c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 19:36:30 +0200
Subject: [PATCH 016/181] fix(coding-agent/web): sent bare query on perplexity
 OAuth path

- Stopped prepending system_prompt to the consumer ask endpoint, which lacks a system slot and refused the meta-instruction.
- Kept system_prompt as a proper system message on the API-key path.
---
 packages/coding-agent/CHANGELOG.md                        | 1 +
 .../coding-agent/src/web/search/providers/perplexity.ts   | 8 +++++++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 794ec90fc..4ac3f4feb 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -22,6 +22,7 @@
 - Fixed boolean environment flag overrides that were ORed with settings, so `PI_INTENT_TRACING=0`, `PI_AUTO_QA=0`, and per-backend eval flags now take precedence when present while falling back to config when unset.
 - Fixed custom-rendered tools that set `mergeCallAndResult` (e.g. `lsp`) rendering a redundant tool-name line above the framed result once a result arrived. `ToolExecutionComponent`'s custom-tool branch now emits the fallback label only when the tool has no `renderCall` and the call is not suppressed by an existing result, matching the built-in renderer branch.
 - Fixed the `write` tool result rendering with a green success checkmark even when the write failed. `writeToolRenderer.renderResult` now branches on `result.isError`, rendering the error status icon plus the failure message instead of the success header and content preview.
+- Fixed Perplexity OAuth/cookie web search returning a refusal answer ("I don't currently have access to the web-search tools in this turn") despite returning real sources. `callPerplexityOAuth` was prepending the API-style `web-search` system prompt to the query (`query_str = systemPrompt + "\n\n" + query`), but the consumer `www.perplexity.ai/rest/sse/perplexity_ask` endpoint has no system-message slot and reads the prepended instruction as a meta-prompt, making the model decline. The OAuth/cookie path now sends the bare query; the API-key path still passes the system prompt as a proper `system` message.
 
 ## [15.9.67] - 2026-06-06
 ### Added
diff --git a/packages/coding-agent/src/web/search/providers/perplexity.ts b/packages/coding-agent/src/web/search/providers/perplexity.ts
index 2bc2ac837..e03112a64 100644
--- a/packages/coding-agent/src/web/search/providers/perplexity.ts
+++ b/packages/coding-agent/src/web/search/providers/perplexity.ts
@@ -334,7 +334,13 @@ async function callPerplexityOAuth(
 	params: PerplexitySearchParams,
 ): Promise<{ answer: string; sources: SearchSource[]; model?: string; requestId?: string }> {
 	const requestId = crypto.randomUUID();
-	const effectiveQuery = params.system_prompt ? `${params.system_prompt}\n\n${params.query}` : params.query;
+	// The consumer `perplexity_ask` endpoint is itself a research assistant and
+	// has no system-message slot. Prepending the API-style system prompt to the
+	// query makes the model read it as a meta-instruction and refuse with
+	// "I don't have access to web-search tools in this turn", so OAuth/cookie
+	// searches send the bare query. (The API-key path still uses system_prompt
+	// as a proper `system` message.)
+	const effectiveQuery = params.query;
 
 	const response = await fetch(PERPLEXITY_OAUTH_ASK_URL, {
 		method: "POST",

From 8a5b99a9679f311d5d2ffab451c43e64b25bb80e Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 19:42:16 +0200
Subject: [PATCH 017/181] feat(coding-agent): enabled anonymous Perplexity
 fallback and updated web-search checks

- Added anonymous Perplexity authentication mode for unauthenticated web searches.
- Switched web-search setup checks to use `isExplicitlyAvailable` and removed key enforcement in doctor.
- Updated Perplexity OAuth flow to reuse auth handling for all non-key searches and anonymous responses.
- Updated CLI and provider option help text to mark the Perplexity key optional with fallback.
---
 packages/coding-agent/CHANGELOG.md            |   4 +
 packages/coding-agent/src/cli/args.ts         |   2 +-
 .../src/extensibility/plugins/doctor.ts       |   1 -
 .../modes/setup-wizard/scenes/web-search.ts   |   5 +-
 .../src/web/search/providers/perplexity.ts    | 239 ++++++++++++++----
 packages/coding-agent/src/web/search/types.ts |   2 +-
 6 files changed, 198 insertions(+), 55 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 4ac3f4feb..dc108df82 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,8 +1,10 @@
 # Changelog
 
 ## [Unreleased]
+
 ### Added
 
+- Added anonymous fallback for Perplexity web search, allowing `web_search` and explicit Perplexity provider usage when no Perplexity credentials are configured
 - Added `gallery` CLI command to render built-in tool renderer output across streaming, in-progress, success, and failure states
 - Added `omp gallery` filtering and rendering options (`--tool`, `--state`, `--width`, `--expanded`, and `--plain`) for focused renderer previews and plain-text output
 - Added `omp gallery` fidelity for tools whose renderers are attached on the tool instance (`lsp`, `task`): the gallery now drives them through the same custom-tool render branch production uses, so regressions in that path surface in the gallery rather than only in a live session.
@@ -11,12 +13,14 @@
 
 ### Changed
 
+- Changed Perplexity explicit provider availability checks so the setup wizard can mark `perplexity` as available for manual selection without credentials, while auto provider discovery still requires auth
 - Changed the default persistent model selector shortcut from `Ctrl+L` to `Alt+M`, leaving `Ctrl+L` for display reset. Existing user remaps in `keybindings.yml` are preserved.
 - Changed the edit tool result header to carry the diff change stats (`+N / -M / K hunks`) inline next to the file path, and removed the redundant lone language-icon metadata row and the blank line between the header and the diff body, so a single-hunk edit renders as `✔ Edit: <icon> path:LINE ⟨+3 / 1 hunk⟩` immediately followed by the diff.
 - Changed the `web_search` tool result rendering: the answer text now shows in full instead of being truncated to a "… N more lines" preview (the `omp q` CLI still caps its compact output), each source renders as a single `title (domain) · age` line with the URL linked on the title (dropping the snippet and bare-URL rows), and the metadata block collapses to one `Provider: <model> @ <provider> (<auth>)` line plus `Usage:` (removing the redundant Sources/Citations/Request/Queries rows).
 
 ### Fixed
 
+- Fixed Perplexity `perplexity_ask` response parsing so OAuth, cookie, and anonymous searches correctly extract answer text and sources from JSON payloads
 - Fixed framed read results rendering with an extra blank row above and below the output block.
 - Fixed collapsed search result previews that could show only "… N more matches" when the first grouped section exceeded the preview budget. Collapsed search output now compacts to match rows, fills the budget with visible hits before the summary, and keeps truncation details out of the bottom user-visible notice.
 - Fixed boolean environment flag overrides that were ORed with settings, so `PI_INTENT_TRACING=0`, `PI_AUTO_QA=0`, and per-backend eval flags now take precedence when present while falling back to config when unset.
diff --git a/packages/coding-agent/src/cli/args.ts b/packages/coding-agent/src/cli/args.ts
index cefb84942..0f770c0ce 100644
--- a/packages/coding-agent/src/cli/args.ts
+++ b/packages/coding-agent/src/cli/args.ts
@@ -284,7 +284,7 @@ export function getExtraHelpText(): string {
   ${chalk.dim("# Search & Tools")}
   EXA_API_KEY                - Exa web search
   BRAVE_API_KEY              - Brave web search
-  PERPLEXITY_API_KEY         - Perplexity web search (API)
+  PERPLEXITY_API_KEY         - Perplexity web search API key (optional; anonymous fallback)
   PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
   TAVILY_API_KEY             - Tavily web search
   ANTHROPIC_SEARCH_API_KEY   - Anthropic web search (override; isolates search from main ANTHROPIC_API_KEY)
diff --git a/packages/coding-agent/src/extensibility/plugins/doctor.ts b/packages/coding-agent/src/extensibility/plugins/doctor.ts
index ff33cc562..5bd600c67 100644
--- a/packages/coding-agent/src/extensibility/plugins/doctor.ts
+++ b/packages/coding-agent/src/extensibility/plugins/doctor.ts
@@ -25,7 +25,6 @@ export async function runDoctorChecks(): Promise<DoctorCheck[]> {
 	const apiKeys = [
 		{ name: "ANTHROPIC_API_KEY", description: "Anthropic API" },
 		{ name: "OPENAI_API_KEY", description: "OpenAI API" },
-		{ name: "PERPLEXITY_API_KEY", description: "Perplexity search" },
 		{ name: "EXA_API_KEY", description: "Exa search" },
 	];
 
diff --git a/packages/coding-agent/src/modes/setup-wizard/scenes/web-search.ts b/packages/coding-agent/src/modes/setup-wizard/scenes/web-search.ts
index 906803bfe..221da8b4a 100644
--- a/packages/coding-agent/src/modes/setup-wizard/scenes/web-search.ts
+++ b/packages/coding-agent/src/modes/setup-wizard/scenes/web-search.ts
@@ -19,7 +19,8 @@ type Availability = "checking" | boolean;
 /**
  * "Web search" panel: picks the provider the web_search tool should prefer and
  * reports whether the highlighted provider is ready to use given current
- * credentials (env keys or OAuth sign-ins from the Sign in tab).
+ * credentials (env keys or OAuth sign-ins from the Sign in tab) or an
+ * unauthenticated fallback.
  */
 export class WebSearchTab implements SetupTab {
 	readonly id = "web-search";
@@ -91,7 +92,7 @@ export class WebSearchTab implements SetupTab {
 			let ready = false;
 			try {
 				const provider = await getSearchProvider(id);
-				ready = await provider.isAvailable(this.host.ctx.session.modelRegistry.authStorage);
+				ready = await provider.isExplicitlyAvailable(this.host.ctx.session.modelRegistry.authStorage);
 			} catch {
 				ready = false;
 			}
diff --git a/packages/coding-agent/src/web/search/providers/perplexity.ts b/packages/coding-agent/src/web/search/providers/perplexity.ts
index e03112a64..92a19865d 100644
--- a/packages/coding-agent/src/web/search/providers/perplexity.ts
+++ b/packages/coding-agent/src/web/search/providers/perplexity.ts
@@ -1,10 +1,11 @@
 /**
  * Perplexity Web Search Provider
  *
- * Supports three auth modes:
+ * Supports four auth modes:
  * - Cookies (`PERPLEXITY_COOKIES`) via `www.perplexity.ai/rest/sse/perplexity_ask`
  * - OAuth/session bearer via `AuthStorage` and `www.perplexity.ai/rest/sse/perplexity_ask`
  * - API key (`PERPLEXITY_API_KEY`) via `api.perplexity.ai/chat/completions`
+ * - Anonymous via `www.perplexity.ai/rest/sse/perplexity_ask`
  */
 
 import { type AuthStorage, getEnvApiKey } from "@oh-my-pi/pi-ai";
@@ -32,6 +33,8 @@ const DEFAULT_NUM_SEARCH_RESULTS = 20;
 const OAUTH_EXPIRY_BUFFER_MS = 5 * 60 * 1000;
 const OAUTH_API_VERSION = "2.18";
 const OAUTH_USER_AGENT = "Perplexity/641 CFNetwork/1568 Darwin/25.2.0";
+const ANONYMOUS_USER_AGENT =
+	"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36";
 
 type PerplexityAuth =
 	| {
@@ -45,6 +48,9 @@ type PerplexityAuth =
 	| {
 			type: "cookies";
 			cookies: string;
+	  }
+	| {
+			type: "anonymous";
 	  };
 
 interface PerplexityOAuthStreamMarkdownBlock {
@@ -149,6 +155,112 @@ function mergeOAuthEventSnapshot(
 
 	return merged;
 }
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	return value as Record<string, unknown>;
+}
+}
+
+function parseJson(text: string): unknown | null {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+function textFromChunks(value: unknown): string | null {
+	if (!Array.isArray(value) || value.length === 0) return null;
+	let text = "";
+	for (const chunk of value) {
+		if (typeof chunk !== "string") return null;
+		text += chunk;
+	}
+	return text.length > 0 ? text : null;
+}
+
+function textFromStructuredAnswer(value: unknown): string | null {
+	if (!Array.isArray(value)) return null;
+	for (const item of value) {
+		const record = asRecord(item);
+		if (!record) continue;
+		const text = record.text;
+		if (typeof text === "string" && text.length > 0) return text;
+		const chunks = textFromChunks(record.chunks);
+		if (chunks) return chunks;
+	}
+	return null;
+}
+
+function answerFromTextPayload(payload: Record<string, unknown>): string | null {
+	const structured = textFromStructuredAnswer(payload.structured_answer);
+	if (structured) return structured;
+	const chunks = textFromChunks(payload.chunks);
+	if (chunks) return chunks;
+	const answer = payload.answer;
+	return typeof answer === "string" && answer.length > 0 ? answer : null;
+}
+
+function parseOAuthTextPayload(text: string): Record<string, unknown> | null {
+	const parsed = parseJson(text);
+	const direct = asRecord(parsed);
+	if (direct) return direct;
+	if (!Array.isArray(parsed)) return null;
+
+	for (const item of parsed) {
+		const step = asRecord(item);
+		const content = asRecord(step?.content);
+		const answer = content?.answer;
+		if (typeof answer !== "string" || answer.length === 0) continue;
+		const payload = asRecord(parseJson(answer));
+		if (payload) return payload;
+	}
+	return null;
+}
+
+function parseOAuthTextAnswer(text: string): string {
+	const payload = parseOAuthTextPayload(text);
+	if (payload) {
+		const answer = answerFromTextPayload(payload);
+		if (answer) return answer;
+	}
+
+	const parsed = parseJson(text);
+	if (!Array.isArray(parsed)) return text;
+	for (const item of parsed) {
+		const step = asRecord(item);
+		const content = asRecord(step?.content);
+		const answer = content?.answer;
+		if (typeof answer === "string" && answer.length > 0) return answer;
+	}
+	return text;
+}
+
+function sourcesFromTextPayload(text: string | undefined): SearchSource[] {
+	if (!text) return [];
+	const payload = parseOAuthTextPayload(text);
+	const webResults = payload?.web_results;
+	if (!Array.isArray(webResults) || webResults.length === 0) return [];
+
+	const sources: SearchSource[] = [];
+	for (const value of webResults) {
+		const result = asRecord(value);
+		const url = result?.url;
+		if (typeof url !== "string" || url.length === 0) continue;
+		const name = result.name;
+		const snippet = result.snippet;
+		const timestamp = result.timestamp;
+		sources.push({
+			title: typeof name === "string" && name.length > 0 ? name : url,
+			url,
+			snippet: typeof snippet === "string" ? snippet : undefined,
+			publishedDate: typeof timestamp === "string" ? timestamp : undefined,
+			ageSeconds: dateToAgeSeconds(typeof timestamp === "string" ? timestamp : undefined),
+		});
+	}
+	return sources;
+}
 export interface PerplexitySearchParams {
 	signal?: AbortSignal;
 	query: string;
@@ -216,7 +328,7 @@ async function findPerplexityAuth(
 	authStorage: AuthStorage,
 	sessionId: string | undefined,
 	signal: AbortSignal | undefined,
-): Promise<PerplexityAuth | null> {
+): Promise<PerplexityAuth> {
 	// 1. PERPLEXITY_COOKIES env var
 	const cookies = $env.PERPLEXITY_COOKIES?.trim();
 	if (cookies) {
@@ -235,7 +347,9 @@ async function findPerplexityAuth(
 	if (apiKey) {
 		return { type: "api_key", token: apiKey };
 	}
-	return null;
+
+	// 4. The consumer ask endpoint currently accepts unauthenticated browser-style requests.
+	return { type: "anonymous" };
 }
 
 /** Call Perplexity API-key endpoint. */
@@ -284,7 +398,7 @@ function buildOAuthSources(event: PerplexityOAuthStreamEvent): SearchSource[] {
 			}));
 	}
 
-	return (event.sources_list ?? [])
+	const sources = (event.sources_list ?? [])
 		.filter(source => typeof source.url === "string" && source.url.length > 0)
 		.map(source => ({
 			title: source.title ?? source.url ?? "",
@@ -293,11 +407,13 @@ function buildOAuthSources(event: PerplexityOAuthStreamEvent): SearchSource[] {
 			publishedDate: source.date,
 			ageSeconds: dateToAgeSeconds(source.date),
 		}));
+	if (sources.length > 0) return sources;
+	return sourcesFromTextPayload(event.text);
 }
 
 function buildOAuthAnswer(event: PerplexityOAuthStreamEvent): string {
 	if (!event.blocks?.length) {
-		return typeof event.text === "string" ? event.text : "";
+		return typeof event.text === "string" ? parseOAuthTextAnswer(event.text) : "";
 	}
 
 	const markdownBlock = event.blocks.find(
@@ -324,57 +440,74 @@ function buildOAuthAnswer(event: PerplexityOAuthStreamEvent): string {
 		}
 	}
 	if (typeof event.text === "string" && event.text.length > 0) {
-		return event.text;
+		return parseOAuthTextAnswer(event.text);
 	}
 	return "";
 }
 
 async function callPerplexityOAuth(
-	auth: { type: "oauth"; token: string } | { type: "cookies"; cookies: string },
+	auth:
+		| { type: "oauth"; token: string }
+		| { type: "cookies"; cookies: string }
+		| { type: "anonymous" },
 	params: PerplexitySearchParams,
 ): Promise<{ answer: string; sources: SearchSource[]; model?: string; requestId?: string }> {
 	const requestId = crypto.randomUUID();
 	// The consumer `perplexity_ask` endpoint is itself a research assistant and
 	// has no system-message slot. Prepending the API-style system prompt to the
 	// query makes the model read it as a meta-instruction and refuse with
-	// "I don't have access to web-search tools in this turn", so OAuth/cookie
+	// "I don't have access to web-search tools in this turn", so ask-endpoint
 	// searches send the bare query. (The API-key path still uses system_prompt
 	// as a proper `system` message.)
 	const effectiveQuery = params.query;
 
+	const headers: Record<string, string> = {
+		"Content-Type": "application/json",
+		Accept: "text/event-stream",
+		Origin: "https://www.perplexity.ai",
+		Referer: "https://www.perplexity.ai/",
+		"User-Agent": auth.type === "anonymous" ? ANONYMOUS_USER_AGENT : OAUTH_USER_AGENT,
+		"X-Request-ID": requestId,
+	};
+	if (auth.type === "oauth") {
+		headers.Authorization = `Bearer ${auth.token}`;
+	} else if (auth.type === "cookies") {
+		headers.Cookie = auth.cookies;
+	}
+	if (auth.type !== "anonymous") {
+		headers["X-App-ApiClient"] = "default";
+		headers["X-App-ApiVersion"] = OAUTH_API_VERSION;
+		headers["X-Perplexity-Request-Reason"] = "submit";
+	}
+
+	const requestParams: Record<string, unknown> = {
+		query_str: effectiveQuery,
+		search_focus: "internet",
+		mode: "copilot",
+		model_preference: auth.type === "anonymous" ? "experimental" : "pplx_pro_upgraded",
+		sources: ["web"],
+		attachments: [],
+		frontend_uuid: crypto.randomUUID(),
+		frontend_context_uuid: crypto.randomUUID(),
+		version: OAUTH_API_VERSION,
+		language: "en-US",
+		timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+		search_recency_filter: params.search_recency_filter ?? null,
+		is_incognito: true,
+		use_schematized_api: true,
+		skip_search_enabled: true,
+	};
+	if (auth.type === "anonymous") {
+		requestParams.send_back_text_in_streaming_api = true;
+		requestParams.source = "default";
+	}
+
 	const response = await fetch(PERPLEXITY_OAUTH_ASK_URL, {
 		method: "POST",
-		headers: {
-			...(auth.type === "cookies" ? { Cookie: auth.cookies } : { Authorization: `Bearer ${auth.token}` }),
-			"Content-Type": "application/json",
-			Accept: "text/event-stream",
-			Origin: "https://www.perplexity.ai",
-			Referer: "https://www.perplexity.ai/",
-			"User-Agent": OAUTH_USER_AGENT,
-			"X-App-ApiClient": "default",
-			"X-App-ApiVersion": OAUTH_API_VERSION,
-			"X-Perplexity-Request-Reason": "submit",
-			"X-Request-ID": requestId,
-		},
+		headers,
 		body: JSON.stringify({
 			query_str: effectiveQuery,
-			params: {
-				query_str: effectiveQuery,
-				search_focus: "internet",
-				mode: "copilot",
-				model_preference: "pplx_pro_upgraded",
-				sources: ["web"],
-				attachments: [],
-				frontend_uuid: crypto.randomUUID(),
-				frontend_context_uuid: crypto.randomUUID(),
-				version: OAUTH_API_VERSION,
-				language: "en-US",
-				timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-				search_recency_filter: params.search_recency_filter ?? null,
-				is_incognito: true,
-				use_schematized_api: true,
-				skip_search_enabled: true,
-			},
+			params: requestParams,
 		}),
 		signal: withHardTimeout(params.signal),
 	});
@@ -385,13 +518,13 @@ async function callPerplexityOAuth(
 		if (classified) throw classified;
 		throw new SearchProviderError(
 			"perplexity",
-			`Perplexity OAuth API error (${response.status}): ${errorText}`,
+			`Perplexity ask API error (${response.status}): ${errorText}`,
 			response.status,
 		);
 	}
 
 	if (!response.body) {
-		throw new SearchProviderError("perplexity", "Perplexity OAuth API returned no response body", 500);
+		throw new SearchProviderError("perplexity", "Perplexity ask API returned no response body", 500);
 	}
 
 	let answer = "";
@@ -403,7 +536,7 @@ async function callPerplexityOAuth(
 	for await (const event of readSseJson<PerplexityOAuthStreamEvent>(response.body, params.signal)) {
 		if (event.error_code) {
 			const message = event.error_message ?? event.error_code;
-			throw new SearchProviderError("perplexity", `Perplexity OAuth stream error: ${message}`, 400);
+			throw new SearchProviderError("perplexity", `Perplexity ask stream error: ${message}`, 400);
 		}
 
 		mergedEvent = mergeOAuthEventSnapshot(mergedEvent, event);
@@ -506,20 +639,17 @@ function applySourceLimit(result: SearchResponse, limit?: number): SearchRespons
 /** Execute Perplexity web search */
 export async function searchPerplexity(params: PerplexitySearchParams): Promise<SearchResponse> {
 	const auth = await findPerplexityAuth(params.authStorage, params.sessionId, params.signal);
-	if (!auth) {
-		throw new Error("Perplexity auth not found. Set PERPLEXITY_COOKIES, PERPLEXITY_API_KEY, or login via OAuth.");
-	}
 
-	if (auth.type === "oauth" || auth.type === "cookies") {
-		const oauthResult = await callPerplexityOAuth(auth, params);
+	if (auth.type !== "api_key") {
+		const askResult = await callPerplexityOAuth(auth, params);
 		return applySourceLimit(
 			{
 				provider: "perplexity",
-				answer: oauthResult.answer || undefined,
-				sources: oauthResult.sources,
-				model: oauthResult.model,
-				requestId: oauthResult.requestId,
-				authMode: "oauth",
+				answer: askResult.answer || undefined,
+				sources: askResult.sources,
+				model: askResult.model,
+				requestId: askResult.requestId,
+				authMode: auth.type === "anonymous" ? "anonymous" : "oauth",
 			},
 			params.num_results,
 		);
@@ -568,6 +698,15 @@ export class PerplexityProvider extends SearchProvider {
 		return !!$env.PERPLEXITY_COOKIES?.trim() || authStorage.hasAuth("perplexity") || !!findApiKey();
 	}
 
+	/**
+	 * Perplexity accepts anonymous browser-style ask requests, but keep auto
+	 * provider selection credential-gated so a configured provider keeps priority
+	 * over the anonymous fallback.
+	 */
+	isExplicitlyAvailable(_authStorage: AuthStorage): boolean {
+		return true;
+	}
+
 	search(params: SearchParams): Promise<SearchResponse> {
 		return searchPerplexity({
 			signal: params.signal,
diff --git a/packages/coding-agent/src/web/search/types.ts b/packages/coding-agent/src/web/search/types.ts
index e37e6d961..946d6cc2d 100644
--- a/packages/coding-agent/src/web/search/types.ts
+++ b/packages/coding-agent/src/web/search/types.ts
@@ -33,7 +33,7 @@ export const SEARCH_PROVIDER_OPTIONS = [
 		description: "Automatically uses the first configured web-search provider",
 	},
 	{ value: "tavily", label: "Tavily", description: "Requires TAVILY_API_KEY" },
-	{ value: "perplexity", label: "Perplexity", description: "Requires PERPLEXITY_COOKIES or PERPLEXITY_API_KEY" },
+	{ value: "perplexity", label: "Perplexity", description: "Uses auth when configured; explicit selection falls back to anonymous search" },
 	{ value: "brave", label: "Brave", description: "Requires BRAVE_API_KEY" },
 	{ value: "jina", label: "Jina", description: "Requires JINA_API_KEY" },
 	{ value: "kimi", label: "Kimi", description: "Requires MOONSHOT_SEARCH_API_KEY or MOONSHOT_API_KEY" },

From f73892d491921f1ec27b0d7bd570311c79552a89 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 20:01:21 +0200
Subject: [PATCH 018/181] fix(coding-agent): bounded expanded single-file
 search results
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Stopped expanded view from dumping every match when all hits share one file.
- Applied an `EXPANDED_LINES × 2` budget while keeping context rows.
- Appended a `… N more matches` summary when truncated.
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 packages/coding-agent/src/tools/search.ts     | 39 ++++++++-------
 .../test/tools/search-renderer.test.ts        | 50 +++++++++++++++++++
 3 files changed, 73 insertions(+), 17 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index dc108df82..45b731581 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -23,6 +23,7 @@
 - Fixed Perplexity `perplexity_ask` response parsing so OAuth, cookie, and anonymous searches correctly extract answer text and sources from JSON payloads
 - Fixed framed read results rendering with an extra blank row above and below the output block.
 - Fixed collapsed search result previews that could show only "… N more matches" when the first grouped section exceeded the preview budget. Collapsed search output now compacts to match rows, fills the budget with visible hits before the summary, and keeps truncation details out of the bottom user-visible notice.
+- Fixed the expanded search result view dumping every match when all hits live in one file. A single file's matches collapse into one blank-line group, and the expanded tree list ignored the line budget, so a hot file whose matches span its whole length rendered every row (e.g. lines 374–2858). Expanded search output is now bounded by a larger-than-collapsed budget (`EXPANDED_LINES × 2`), keeps surrounding context rows, and appends a `… N more matches` summary when truncated.
 - Fixed boolean environment flag overrides that were ORed with settings, so `PI_INTENT_TRACING=0`, `PI_AUTO_QA=0`, and per-backend eval flags now take precedence when present while falling back to config when unset.
 - Fixed custom-rendered tools that set `mergeCallAndResult` (e.g. `lsp`) rendering a redundant tool-name line above the framed result once a result arrived. `ToolExecutionComponent`'s custom-tool branch now emits the fallback label only when the tool has no `renderCall` and the call is not suppressed by an existing result, matching the built-in renderer branch.
 - Fixed the `write` tool result rendering with a green success checkmark even when the write failed. `writeToolRenderer.renderResult` now branches on `result.isError`, rendering the error status icon plus the failure message instead of the success header and content preview.
diff --git a/packages/coding-agent/src/tools/search.ts b/packages/coding-agent/src/tools/search.ts
index ce281fb05..d74a35726 100644
--- a/packages/coding-agent/src/tools/search.ts
+++ b/packages/coding-agent/src/tools/search.ts
@@ -1173,6 +1173,10 @@ interface SearchRenderArgs {
 }
 
 const COLLAPSED_TEXT_LIMIT = PREVIEW_LIMITS.COLLAPSED_LINES * 2;
+/** Line budget for the expanded view. Larger than collapsed so expanding
+ * reveals more matches with context, but still bounded so a single hot file
+ * whose matches span the whole file can't dump its entire length. */
+const EXPANDED_TEXT_LIMIT = PREVIEW_LIMITS.EXPANDED_LINES * 2;
 
 const SEARCH_CODE_FRAME_LINE_RE = /^\s*\*?(\d+)│/;
 
@@ -1283,16 +1287,20 @@ function countPreviewMatches(lines: readonly RenderedSearchLine[], hasMarkedMatc
 	return lines.reduce((count, line) => count + (!isSearchHeaderLine(line.raw) && line.raw.length > 0 ? 1 : 0), 0);
 }
 
-function renderCollapsedSearchGroups(
+function renderBudgetedSearchGroups(
 	groups: string[][],
 	maxLines: number,
 	matchCount: number,
 	searchBase: string | undefined,
 	uiTheme: Theme,
+	compact: boolean,
 ): string[] {
 	if (maxLines <= 0) return [];
 	const renderedGroups = groups
-		.map(group => compactSearchPreviewGroup(renderSearchDisplayGroup(group, searchBase, uiTheme)))
+		.map(group => {
+			const rendered = renderSearchDisplayGroup(group, searchBase, uiTheme);
+			return compact ? compactSearchPreviewGroup(rendered) : rendered;
+		})
 		.filter(group => group.length > 0);
 	if (renderedGroups.length === 0) return [];
 
@@ -1451,22 +1459,19 @@ export const searchToolRenderer = {
 		return createCachedComponent(
 			() => options.expanded,
 			width => {
-				const collapsedMatchLineBudget = Math.max(COLLAPSED_TEXT_LIMIT - extraLines.length, 0);
+				const budget = Math.max(
+					(options.expanded ? EXPANDED_TEXT_LIMIT : COLLAPSED_TEXT_LIMIT) - extraLines.length,
+					0,
+				);
 				const searchBase = details?.searchPath;
-				const matchLines = options.expanded
-					? renderTreeList(
-							{
-								items: matchGroups,
-								expanded: true,
-								maxCollapsed: matchGroups.length,
-								maxCollapsedLines: collapsedMatchLineBudget,
-								itemType: "match",
-								renderItem: group =>
-									renderSearchDisplayGroup(group, searchBase, uiTheme).map(line => line.styled),
-							},
-							uiTheme,
-						)
-					: renderCollapsedSearchGroups(matchGroups, collapsedMatchLineBudget, matchCount, searchBase, uiTheme);
+				const matchLines = renderBudgetedSearchGroups(
+					matchGroups,
+					budget,
+					matchCount,
+					searchBase,
+					uiTheme,
+					!options.expanded,
+				);
 				return [header, ...matchLines, ...extraLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
 			},
 		);
diff --git a/packages/coding-agent/test/tools/search-renderer.test.ts b/packages/coding-agent/test/tools/search-renderer.test.ts
index 8f89c31e7..13f1c7f32 100644
--- a/packages/coding-agent/test/tools/search-renderer.test.ts
+++ b/packages/coding-agent/test/tools/search-renderer.test.ts
@@ -154,4 +154,54 @@ describe("searchToolRenderer", () => {
 
 		expect(extractLinkUris(rendered)).toContain("file:///tmp/omp-project/file.ts?line=7");
 	});
+
+	it("bounds the expanded single-file view instead of dumping every match", async () => {
+		const theme = await getThemeByName("dark");
+		expect(theme).toBeDefined();
+		const uiTheme = theme!;
+
+		// One file's matches collapse into a single blank-line group (no `#`/`##`
+		// headers, `│...` gap separators). Before the fix the expanded renderer
+		// dumped the entire span because the tree list ignored the line budget.
+		const clusters = Array.from({ length: 12 }, (_, i) => i * 100 + 1);
+		const displayContent = clusters
+			.map((line, idx) => {
+				const cluster = [` ${line}│ context before`, `*${line + 1}│ MATCH ${idx}`, ` ${line + 2}│ context after`];
+				return idx === 0 ? cluster.join("\n") : ["    │...", ...cluster].join("\n");
+			})
+			.join("\n");
+
+		const result = {
+			content: [{ type: "text", text: "" }],
+			details: {
+				matchCount: clusters.length,
+				fileCount: 1,
+				searchPath: "/tmp/omp-project/renderer.ts",
+				scopePath: "renderer.ts",
+				displayContent,
+			},
+		};
+
+		const render = (expanded: boolean) =>
+			sanitizeText(
+				searchToolRenderer
+					.renderResult(result as never, { expanded, isPartial: false }, uiTheme, { pattern: "needle" })
+					.render(200)
+					.join("\n"),
+			).split("\n");
+
+		const expanded = render(true);
+		const expandedBody = expanded.slice(1);
+		// Bounded: must not render all 12 clusters (36+ lines).
+		expect(expandedBody.length).toBeLessThan(clusters.length * 3);
+		expect(expandedBody.some(line => line.includes("more matches"))).toBe(true);
+		// Expanded keeps surrounding context lines (unlike the compact collapsed view).
+		expect(expandedBody.some(line => line.includes("context before"))).toBe(true);
+
+		const collapsedBody = render(false).slice(1);
+		expect(collapsedBody.length).toBeLessThan(expandedBody.length);
+		// Collapsed compacts to match lines only — no context.
+		expect(collapsedBody.some(line => line.includes("context before"))).toBe(false);
+		expect(collapsedBody.some(line => line.includes("more matches"))).toBe(true);
+	});
 });

From 246688e8748ef02a042f491d0381a2d3a86f95d0 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 20:01:51 +0200
Subject: [PATCH 019/181] fix(coding-agent/web): unlocked perplexity pro via
 session cookie

- Sent the OAuth token as `__Secure-next-auth.session-token` cookie since the ask endpoint ignores bearer headers and silently downgrades to `turbo`.
- Fell back to `result.title` when web results omit `name`.
- Renamed `callPerplexityOAuth` to `callPerplexityAsk` and removed a stray brace.
- Added tests covering OAuth, API-key, and anonymous request shapes.
---
 packages/coding-agent/CHANGELOG.md            |   1 +
 .../src/web/search/providers/perplexity.ts    |  23 ++-
 packages/coding-agent/src/web/search/types.ts |   6 +-
 .../test/web/search/perplexity.test.ts        | 171 +++++++++++++++++-
 4 files changed, 189 insertions(+), 12 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 45b731581..0b985df8c 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -28,6 +28,7 @@
 - Fixed custom-rendered tools that set `mergeCallAndResult` (e.g. `lsp`) rendering a redundant tool-name line above the framed result once a result arrived. `ToolExecutionComponent`'s custom-tool branch now emits the fallback label only when the tool has no `renderCall` and the call is not suppressed by an existing result, matching the built-in renderer branch.
 - Fixed the `write` tool result rendering with a green success checkmark even when the write failed. `writeToolRenderer.renderResult` now branches on `result.isError`, rendering the error status icon plus the failure message instead of the success header and content preview.
 - Fixed Perplexity OAuth/cookie web search returning a refusal answer ("I don't currently have access to the web-search tools in this turn") despite returning real sources. `callPerplexityOAuth` was prepending the API-style `web-search` system prompt to the query (`query_str = systemPrompt + "\n\n" + query`), but the consumer `www.perplexity.ai/rest/sse/perplexity_ask` endpoint has no system-message slot and reads the prepended instruction as a meta-prompt, making the model decline. The OAuth/cookie path now sends the bare query; the API-key path still passes the system prompt as a proper `system` message.
+- Fixed Perplexity OAuth web search always returning the free `turbo` model instead of the account's Pro model (e.g. `pplx_pro_upgraded`/Sonar). The `www.perplexity.ai/rest/sse/perplexity_ask` endpoint authenticates via the `__Secure-next-auth.session-token` cookie and ignores the `Authorization: Bearer` header entirely — so sending the OAuth session token as a bearer was treated as an anonymous request, which silently downgrades to `turbo` regardless of `model_preference`. The stored Perplexity OAuth token is itself the next-auth session JWT (the macOS app injects the same value as that cookie), so `callPerplexityAsk` now sends it as the `__Secure-next-auth.session-token` cookie, unlocking Pro model selection.
 
 ## [15.9.67] - 2026-06-06
 ### Added
diff --git a/packages/coding-agent/src/web/search/providers/perplexity.ts b/packages/coding-agent/src/web/search/providers/perplexity.ts
index 92a19865d..7a1579f01 100644
--- a/packages/coding-agent/src/web/search/providers/perplexity.ts
+++ b/packages/coding-agent/src/web/search/providers/perplexity.ts
@@ -160,7 +160,6 @@ function asRecord(value: unknown): Record<string, unknown> | null {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
 	return value as Record<string, unknown>;
 }
-}
 
 function parseJson(text: string): unknown | null {
 	try {
@@ -246,9 +245,10 @@ function sourcesFromTextPayload(text: string | undefined): SearchSource[] {
 	const sources: SearchSource[] = [];
 	for (const value of webResults) {
 		const result = asRecord(value);
-		const url = result?.url;
+		if (!result) continue;
+		const url = result.url;
 		if (typeof url !== "string" || url.length === 0) continue;
-		const name = result.name;
+		const name = result.name ?? result.title;
 		const snippet = result.snippet;
 		const timestamp = result.timestamp;
 		sources.push({
@@ -445,11 +445,8 @@ function buildOAuthAnswer(event: PerplexityOAuthStreamEvent): string {
 	return "";
 }
 
-async function callPerplexityOAuth(
-	auth:
-		| { type: "oauth"; token: string }
-		| { type: "cookies"; cookies: string }
-		| { type: "anonymous" },
+async function callPerplexityAsk(
+	auth: { type: "oauth"; token: string } | { type: "cookies"; cookies: string } | { type: "anonymous" },
 	params: PerplexitySearchParams,
 ): Promise<{ answer: string; sources: SearchSource[]; model?: string; requestId?: string }> {
 	const requestId = crypto.randomUUID();
@@ -470,7 +467,13 @@ async function callPerplexityOAuth(
 		"X-Request-ID": requestId,
 	};
 	if (auth.type === "oauth") {
-		headers.Authorization = `Bearer ${auth.token}`;
+		// The ask endpoint authenticates via the next-auth session cookie, NOT a
+		// bearer header — a bearer (even a garbage one) is ignored and the request
+		// silently falls back to the anonymous free `turbo` model regardless of
+		// `model_preference`. The stored OAuth token IS the Perplexity session JWT
+		// (the native app injects the same value as this cookie), so sending it as
+		// the cookie is what unlocks the account's Pro model selection.
+		headers.Cookie = `__Secure-next-auth.session-token=${auth.token}`;
 	} else if (auth.type === "cookies") {
 		headers.Cookie = auth.cookies;
 	}
@@ -641,7 +644,7 @@ export async function searchPerplexity(params: PerplexitySearchParams): Promise<
 	const auth = await findPerplexityAuth(params.authStorage, params.sessionId, params.signal);
 
 	if (auth.type !== "api_key") {
-		const askResult = await callPerplexityOAuth(auth, params);
+		const askResult = await callPerplexityAsk(auth, params);
 		return applySourceLimit(
 			{
 				provider: "perplexity",
diff --git a/packages/coding-agent/src/web/search/types.ts b/packages/coding-agent/src/web/search/types.ts
index 946d6cc2d..334971033 100644
--- a/packages/coding-agent/src/web/search/types.ts
+++ b/packages/coding-agent/src/web/search/types.ts
@@ -33,7 +33,11 @@ export const SEARCH_PROVIDER_OPTIONS = [
 		description: "Automatically uses the first configured web-search provider",
 	},
 	{ value: "tavily", label: "Tavily", description: "Requires TAVILY_API_KEY" },
-	{ value: "perplexity", label: "Perplexity", description: "Uses auth when configured; explicit selection falls back to anonymous search" },
+	{
+		value: "perplexity",
+		label: "Perplexity",
+		description: "Uses auth when configured; explicit selection falls back to anonymous search",
+	},
 	{ value: "brave", label: "Brave", description: "Requires BRAVE_API_KEY" },
 	{ value: "jina", label: "Jina", description: "Requires JINA_API_KEY" },
 	{ value: "kimi", label: "Kimi", description: "Requires MOONSHOT_SEARCH_API_KEY or MOONSHOT_API_KEY" },
diff --git a/packages/coding-agent/test/web/search/perplexity.test.ts b/packages/coding-agent/test/web/search/perplexity.test.ts
index 1d2ef6781..4a7e30923 100644
--- a/packages/coding-agent/test/web/search/perplexity.test.ts
+++ b/packages/coding-agent/test/web/search/perplexity.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
 import type { AuthStorage } from "@oh-my-pi/pi-ai";
-import { searchPerplexity } from "@oh-my-pi/pi-coding-agent/web/search/providers/perplexity";
+import { PerplexityProvider, searchPerplexity } from "@oh-my-pi/pi-coding-agent/web/search/providers/perplexity";
 import { hookFetch } from "@oh-my-pi/pi-utils";
 
 const API_URL = "https://api.perplexity.ai/chat/completions";
@@ -97,3 +97,172 @@ describe("Perplexity API-key request shape", () => {
 		expect(response.relatedQuestions).toBeUndefined();
 	});
 });
+
+const OAUTH_ASK_URL = "https://www.perplexity.ai/rest/sse/perplexity_ask";
+
+// OAuth path: getOAuthAccess returns a bearer (no `.`-delimited exp claim, so it
+// is treated as non-expiring), making findPerplexityAuth pick the oauth branch.
+const oauthAuthStorage = {
+	async getOAuthAccess() {
+		return { accessToken: "test-oauth-token" };
+	},
+	hasAuth() {
+		return true;
+	},
+} as unknown as AuthStorage;
+
+const anonymousAuthStorage = {
+	async getOAuthAccess() {
+		return undefined;
+	},
+	hasAuth() {
+		return false;
+	},
+} as unknown as AuthStorage;
+
+function mockOAuth(capture: (body: Record<string, unknown>, headers: Headers) => void) {
+	const event = {
+		final: true,
+		display_model: "turbo",
+		uuid: "req-oauth",
+		blocks: [
+			{ intended_usage: "ask_text", markdown_block: { answer: "OAuth answer" } },
+			{
+				intended_usage: "web_results",
+				web_result_block: { web_results: [{ name: "T", url: "https://example.com", snippet: "s" }] },
+			},
+		],
+	};
+	const sseBody = `data: ${JSON.stringify(event)}\n\n`;
+	return hookFetch(async (input, init) => {
+		const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+		if (url === OAUTH_ASK_URL) {
+			capture(JSON.parse(init?.body as string), new Headers(init?.headers));
+			return new Response(sseBody, { status: 200, headers: { "Content-Type": "text/event-stream" } });
+		}
+		return new Response("not mocked", { status: 500 });
+	});
+}
+
+function mockAnonymous(capture: (body: Record<string, unknown>, headers: Headers) => void) {
+	const answerPayload = {
+		answer: "Anonymous answer",
+		web_results: [{ name: "Example", url: "https://example.com", snippet: "s" }],
+		chunks: ["Anonymous ", "answer"],
+		structured_answer: [{ type: "markdown", text: "Anonymous answer", chunks: ["Anonymous ", "answer"] }],
+	};
+	const event = {
+		final: true,
+		display_model: "turbo",
+		uuid: "req-anon",
+		text: JSON.stringify([{ step_type: "FINAL", content: { answer: JSON.stringify(answerPayload) }, uuid: "" }]),
+	};
+	const sseBody = `data: ${JSON.stringify(event)}\n\n`;
+	return hookFetch(async (input, init) => {
+		const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+		if (url === OAUTH_ASK_URL) {
+			capture(JSON.parse(init?.body as string), new Headers(init?.headers));
+			return new Response(sseBody, { status: 200, headers: { "Content-Type": "text/event-stream" } });
+		}
+		return new Response("not mocked", { status: 500 });
+	});
+}
+
+describe("Perplexity OAuth request shape", () => {
+	const savedCookies = process.env.PERPLEXITY_COOKIES;
+
+	beforeEach(() => {
+		delete process.env.PERPLEXITY_COOKIES; // cookies take precedence over oauth; keep them out
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+		if (savedCookies === undefined) delete process.env.PERPLEXITY_COOKIES;
+		else process.env.PERPLEXITY_COOKIES = savedCookies;
+	});
+
+	it("sends the bare query, never the API-style system prompt, to the ask endpoint", async () => {
+		let body: Record<string, unknown> | undefined;
+		let headers: Headers | undefined;
+		using _hook = mockOAuth((b, h) => {
+			body = b;
+			headers = h;
+		});
+
+		const response = await searchPerplexity({
+			query: "quic vs tcp",
+			system_prompt: "Research assistant with web search. Synthesize comprehensive answers.",
+			authStorage: oauthAuthStorage,
+		});
+
+		// The consumer ask endpoint has no system slot; prepending the prompt makes
+		// the model refuse ("I don't have web-search tools in this turn").
+		expect(body?.query_str).toBe("quic vs tcp");
+		expect((body?.params as Record<string, unknown>).query_str).toBe("quic vs tcp");
+		// The ask endpoint authenticates via the next-auth session cookie; a bearer
+		// header is ignored and silently downgrades to the anonymous `turbo` model.
+		expect(headers?.get("cookie")).toBe("__Secure-next-auth.session-token=test-oauth-token");
+		expect(headers?.has("authorization")).toBe(false);
+		expect(response.authMode).toBe("oauth");
+		expect(response.answer).toBe("OAuth answer");
+	});
+});
+
+describe("Perplexity anonymous fallback", () => {
+	const savedKey = process.env.PERPLEXITY_API_KEY;
+	const savedPplxKey = process.env.PPLX_API_KEY;
+	const savedCookies = process.env.PERPLEXITY_COOKIES;
+
+	beforeEach(() => {
+		delete process.env.PERPLEXITY_API_KEY;
+		delete process.env.PPLX_API_KEY;
+		delete process.env.PERPLEXITY_COOKIES;
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+		if (savedKey === undefined) delete process.env.PERPLEXITY_API_KEY;
+		else process.env.PERPLEXITY_API_KEY = savedKey;
+		if (savedPplxKey === undefined) delete process.env.PPLX_API_KEY;
+		else process.env.PPLX_API_KEY = savedPplxKey;
+		if (savedCookies === undefined) delete process.env.PERPLEXITY_COOKIES;
+		else process.env.PERPLEXITY_COOKIES = savedCookies;
+	});
+
+	it("uses the browser ask endpoint without credential headers when no key is configured", async () => {
+		let body: Record<string, unknown> | undefined;
+		let headers: Headers | undefined;
+		using _hook = mockAnonymous((b, h) => {
+			body = b;
+			headers = h;
+		});
+
+		const response = await searchPerplexity({ query: "anonymous search", authStorage: anonymousAuthStorage });
+		const requestParams = body?.params as Record<string, unknown>;
+
+		expect(headers?.has("authorization")).toBe(false);
+		expect(headers?.has("cookie")).toBe(false);
+		expect(headers?.get("user-agent")).toContain("Mozilla/5.0");
+		expect(requestParams.model_preference).toBe("experimental");
+		expect(requestParams.send_back_text_in_streaming_api).toBe(true);
+		expect(requestParams.source).toBe("default");
+		expect(response.authMode).toBe("anonymous");
+		expect(response.answer).toBe("Anonymous answer");
+		expect(response.sources).toEqual([
+			{
+				title: "Example",
+				url: "https://example.com",
+				snippet: "s",
+				publishedDate: undefined,
+				ageSeconds: undefined,
+			},
+		]);
+	});
+
+	it("keeps anonymous Perplexity out of auto provider selection but allows explicit selection", () => {
+		const provider = new PerplexityProvider();
+
+		expect(provider.isAvailable(anonymousAuthStorage)).toBe(false);
+		expect(provider.isExplicitlyAvailable(anonymousAuthStorage)).toBe(true);
+	});
+});

From ce60b6626b85708c0e93cd248f3fb307239b8a58 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:11:42 +0000
Subject: [PATCH 020/181] fix(coding-agent): harden todo renderer against
 malformed streaming args
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The todo tool's renderCall ran args?.ops?.map(...) directly, which throws
TypeError on any non-array ops value. parseStreamingJson surfaces such
shapes mid-stream: a partial Anthropic input_json_delta buffer like
'{"ops":"[{' becomes { ops: '[{' }, and intermediate states can hand back
null entries before object fields arrive. Each crash spammed Tool
renderer failed warnings and starved the TUI render loop.

Guard against:
- ops being any non-array (string, object, primitive)
- entries being null / non-object
- entry.items being a non-array

The fix is in the TUI renderer only — schema validation in the agent
loop is unchanged, so any genuinely malformed model output still
surfaces an invalid-args tool error to the model.

Fixes #2005
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 packages/coding-agent/src/tools/todo.ts       | 27 +++++++---
 packages/coding-agent/test/tools/todo.test.ts | 50 +++++++++++++++++++
 3 files changed, 71 insertions(+), 7 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 6515a5a39..101c92e73 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -15,6 +15,7 @@
 - Fixed framed read results rendering with an extra blank row above and below the output block.
 - Fixed collapsed search result previews that could show only "… N more matches" when the first grouped section exceeded the preview budget. Collapsed search output now compacts to match rows, fills the budget with visible hits before the summary, and keeps truncation details out of the bottom user-visible notice.
 - Fixed boolean environment flag overrides that were ORed with settings, so `PI_INTENT_TRACING=0`, `PI_AUTO_QA=0`, and per-backend eval flags now take precedence when present while falling back to config when unset.
+- Fixed the `todo` tool's TUI renderer crashing with `TypeError: args?.ops?.map is not a function` when a streaming tool-call delta surfaces a non-array `ops` field (mid-stream `parseStreamingJson` shapes like `{ ops: "[{" }`, or `[null]` entries before fields arrive). The renderer now treats non-array `ops`, non-object entries, and non-array `items` as missing structure instead of crashing, which also stops the spam-warn/retry cascade that followed each malformed delta ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
 
 ## [15.9.67] - 2026-06-06
 ### Added
diff --git a/packages/coding-agent/src/tools/todo.ts b/packages/coding-agent/src/tools/todo.ts
index 6d7c67ab0..f61d4b419 100644
--- a/packages/coding-agent/src/tools/todo.ts
+++ b/packages/coding-agent/src/tools/todo.ts
@@ -777,13 +777,26 @@ function renderNoteAttachments(phases: TodoPhase[], uiTheme: Theme): string[] {
 
 export const todoToolRenderer = {
 	renderCall(args: TodoRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
-		const ops = args?.ops?.map(entry => {
-			const parts = [entry.op ?? "update"];
-			if (entry.task) parts.push(entry.task);
-			if (entry.phase) parts.push(entry.phase);
-			if (entry.items?.length) parts.push(`${entry.items.length} item${entry.items.length === 1 ? "" : "s"}`);
-			return parts.join(" ");
-		}) ?? ["update"];
+		// `args` here is the raw partially-parsed JSON from the streaming
+		// tool-call delta and may not satisfy `TodoRenderArgs` at runtime:
+		// `parseStreamingJson` can hand back `{ ops: "[" }` mid-delta, or
+		// entries that are `null` / strings before fields stream. Guard
+		// against non-array `ops` and non-object entries so a malformed
+		// delta never breaks the TUI render loop (#2005).
+		const opsList = Array.isArray(args?.ops) ? args.ops : [];
+		const ops =
+			opsList.length === 0
+				? ["update"]
+				: opsList.map(entry => {
+						const e = entry && typeof entry === "object" ? entry : ({} as NonNullable<typeof entry>);
+						const parts = [e.op ?? "update"];
+						if (e.task) parts.push(e.task);
+						if (e.phase) parts.push(e.phase);
+						if (Array.isArray(e.items) && e.items.length) {
+							parts.push(`${e.items.length} item${e.items.length === 1 ? "" : "s"}`);
+						}
+						return parts.join(" ");
+					});
 		const text = renderStatusLine({ icon: "pending", title: "Todo", meta: ops }, uiTheme);
 		return new Text(text, 0, 0);
 	},
diff --git a/packages/coding-agent/test/tools/todo.test.ts b/packages/coding-agent/test/tools/todo.test.ts
index 73d0d6a61..670091e0c 100644
--- a/packages/coding-agent/test/tools/todo.test.ts
+++ b/packages/coding-agent/test/tools/todo.test.ts
@@ -345,3 +345,53 @@ describe("todoMatchesAnyDescription", () => {
 		expect(todoMatchesAnyDescription("Audit AGENTS.md compliance", ["Audit AGENTS md compliance"])).toBe(true);
 	});
 });
+
+describe("todoToolRenderer.renderCall malformed-args regression (#2005)", () => {
+	// Reporter saw `TypeError: args?.ops?.map is not a function` against
+	// Xiaomi Token Plan's Anthropic protocol because `parseStreamingJson`
+	// surfaced `{ ops: "[..." }` shapes mid-stream. The renderer is invoked
+	// on every streaming delta, so any non-array `ops` (string, object,
+	// number) must NOT crash the TUI render loop and trigger the spam-warn /
+	// retry cascade.
+	const renderOptions = { expanded: false, isPartial: true } as const;
+
+	it("does not throw when ops is a streaming-truncated string", () => {
+		// Mid-stream `partialJson === '{"ops":"[{'` parses into `{ops: "[{"}`.
+		const args = { ops: '[{"op":"init"' } as unknown as Parameters<typeof todoToolRenderer.renderCall>[0];
+		expect(() => todoToolRenderer.renderCall(args, renderOptions, theme)).not.toThrow();
+	});
+
+	it("does not throw when ops entries are null", () => {
+		// `partialParse` of `'{"ops":[null'` can hand back `{ops: [null]}` in
+		// intermediate states before the entry object opens.
+		const args = { ops: [null] } as unknown as Parameters<typeof todoToolRenderer.renderCall>[0];
+		expect(() => todoToolRenderer.renderCall(args, renderOptions, theme)).not.toThrow();
+	});
+
+	it("does not throw when an entry's items field is a non-array", () => {
+		const args = {
+			ops: [{ op: "append", phase: "Work", items: "Second" as unknown as string[] }],
+		} as unknown as Parameters<typeof todoToolRenderer.renderCall>[0];
+		expect(() => todoToolRenderer.renderCall(args, renderOptions, theme)).not.toThrow();
+	});
+
+	it("still renders ops summary metadata for well-formed args", () => {
+		const args = {
+			ops: [
+				{ op: "init", items: ["a", "b", "c"] },
+				{ op: "done", task: "a" },
+				{ op: "append", phase: "Cleanup", items: ["d"] },
+			],
+		};
+		const component = todoToolRenderer.renderCall(args, renderOptions, theme);
+		// `Text(text, 0, 0)` from `@oh-my-pi/pi-tui` exposes the content via .render().
+		const rendered = Bun.stripANSI(component.render(120).join("\n"));
+		expect(rendered).toContain("init");
+		expect(rendered).toContain("3 items");
+		expect(rendered).toContain("done");
+		expect(rendered).toContain("a");
+		expect(rendered).toContain("append");
+		expect(rendered).toContain("Cleanup");
+		expect(rendered).toContain("1 item");
+	});
+});

From 1c5cb37df5ba00bece7471bde72722d8d468bb7e Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:12:08 +0000
Subject: [PATCH 021/181] style: bun run fix

---
 packages/coding-agent/test/extensions-runner.test.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/coding-agent/test/extensions-runner.test.ts b/packages/coding-agent/test/extensions-runner.test.ts
index 1542897a9..33e188b7f 100644
--- a/packages/coding-agent/test/extensions-runner.test.ts
+++ b/packages/coding-agent/test/extensions-runner.test.ts
@@ -148,7 +148,6 @@ describe("ExtensionRunner", () => {
 			warnSpy.mockRestore();
 		});
 
-
 		it("warns when two extensions register same shortcut", async () => {
 			// Use a non-reserved shortcut
 			const extCode1 = `

From 43b22e95646369a72f8ef10c295f1cda03883ad0 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 20:13:06 +0200
Subject: [PATCH 022/181] fix(coding-agent/web): defaulted perplexity ask to
 experimental model

- Forced authenticated ask requests to `experimental`, matching the anonymous fallback since the cookie session ignores pro upgrades.
- Kept TUI collapsed search answers full; capping now only applies in compact mode via `maxAnswerLines`.
- Preserved full multiline task pending preview instead of bounding it.
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 .../src/web/search/providers/perplexity.ts    |  2 +-
 .../test/streaming-preview-height.test.ts     | 30 +++++++++++--------
 .../test/web/search/perplexity.test.ts        |  1 +
 .../test/web/search/render.test.ts            | 16 ++++++++--
 5 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0b985df8c..1f7b3db85 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -13,6 +13,7 @@
 
 ### Changed
 
+- Changed authenticated Perplexity ask requests to default to the `experimental` model preference, matching the anonymous fallback.
 - Changed Perplexity explicit provider availability checks so the setup wizard can mark `perplexity` as available for manual selection without credentials, while auto provider discovery still requires auth
 - Changed the default persistent model selector shortcut from `Ctrl+L` to `Alt+M`, leaving `Ctrl+L` for display reset. Existing user remaps in `keybindings.yml` are preserved.
 - Changed the edit tool result header to carry the diff change stats (`+N / -M / K hunks`) inline next to the file path, and removed the redundant lone language-icon metadata row and the blank line between the header and the diff body, so a single-hunk edit renders as `✔ Edit: <icon> path:LINE ⟨+3 / 1 hunk⟩` immediately followed by the diff.
diff --git a/packages/coding-agent/src/web/search/providers/perplexity.ts b/packages/coding-agent/src/web/search/providers/perplexity.ts
index 7a1579f01..70284cdfb 100644
--- a/packages/coding-agent/src/web/search/providers/perplexity.ts
+++ b/packages/coding-agent/src/web/search/providers/perplexity.ts
@@ -487,7 +487,7 @@ async function callPerplexityAsk(
 		query_str: effectiveQuery,
 		search_focus: "internet",
 		mode: "copilot",
-		model_preference: auth.type === "anonymous" ? "experimental" : "pplx_pro_upgraded",
+		model_preference: "experimental",
 		sources: ["web"],
 		attachments: [],
 		frontend_uuid: crypto.randomUUID(),
diff --git a/packages/coding-agent/test/streaming-preview-height.test.ts b/packages/coding-agent/test/streaming-preview-height.test.ts
index 8321e2b59..5156d8382 100644
--- a/packages/coding-agent/test/streaming-preview-height.test.ts
+++ b/packages/coding-agent/test/streaming-preview-height.test.ts
@@ -338,7 +338,7 @@ describe("streaming tool call preview height (bounded across renderers)", () =>
 		expect(visibleWidth(topBorder ?? "")).toBe(width);
 	});
 
-	test("eval/bash/ssh/task pending previews stay short even with very long multiline args", () => {
+	test("eval/bash/ssh pending previews stay short even with very long multiline args", () => {
 		const longLines = Array.from({ length: 80 }, (_, i) => `line-${i}`);
 		const cases: Array<{
 			name: string;
@@ -359,7 +359,7 @@ describe("streaming tool call preview height (bounded across renderers)", () =>
 				marker: /earlier lines/,
 			},
 			{
-				// bash/ssh/task keep a bounded head+tail window: the start and the
+				// bash/ssh keep a bounded head+tail window: the start and the
 				// latest are both visible, the middle is elided.
 				name: "bash",
 				args: { command: longLines.join("\n") },
@@ -374,17 +374,6 @@ describe("streaming tool call preview height (bounded across renderers)", () =>
 				mustHide: ["line-40"],
 				marker: /more lines/,
 			},
-			{
-				name: "task",
-				args: {
-					agent: "task",
-					context: longLines.join("\n"),
-					tasks: [{ id: "alpha", description: "preview" }],
-				},
-				mustContain: ["line-0", "line-79"],
-				mustHide: ["line-40"],
-				marker: /more lines/,
-			},
 		];
 
 		for (const testCase of cases) {
@@ -399,4 +388,19 @@ describe("streaming tool call preview height (bounded across renderers)", () =>
 			expect(text, `${testCase.name} preview should advertise truncation`).toMatch(testCase.marker);
 		}
 	});
+
+	test("task pending preview preserves full multiline context", () => {
+		const longLines = Array.from({ length: 80 }, (_, i) => `line-${i}`);
+		const { lines, text } = renderPending("task", {
+			agent: "task",
+			context: longLines.join("\n"),
+			tasks: [{ id: "alpha", description: "preview" }],
+		});
+
+		expect(lines.length, "task preview should not be capped").toBeGreaterThan(80);
+		expect(text).toContain("line-0");
+		expect(text).toContain("line-40");
+		expect(text).toContain("line-79");
+		expect(text).not.toMatch(/more lines/);
+	});
 });
diff --git a/packages/coding-agent/test/web/search/perplexity.test.ts b/packages/coding-agent/test/web/search/perplexity.test.ts
index 4a7e30923..a582141ab 100644
--- a/packages/coding-agent/test/web/search/perplexity.test.ts
+++ b/packages/coding-agent/test/web/search/perplexity.test.ts
@@ -199,6 +199,7 @@ describe("Perplexity OAuth request shape", () => {
 		// the model refuse ("I don't have web-search tools in this turn").
 		expect(body?.query_str).toBe("quic vs tcp");
 		expect((body?.params as Record<string, unknown>).query_str).toBe("quic vs tcp");
+		expect((body?.params as Record<string, unknown>).model_preference).toBe("experimental");
 		// The ask endpoint authenticates via the next-auth session cookie; a bearer
 		// header is ignored and silently downgrades to the anonymous `turbo` model.
 		expect(headers?.get("cookie")).toBe("__Secure-next-auth.session-token=test-oauth-token");
diff --git a/packages/coding-agent/test/web/search/render.test.ts b/packages/coding-agent/test/web/search/render.test.ts
index d9a26ccc5..e2b689dc7 100644
--- a/packages/coding-agent/test/web/search/render.test.ts
+++ b/packages/coding-agent/test/web/search/render.test.ts
@@ -75,13 +75,25 @@ describe("renderSearchResult", () => {
 		expect(answer).not.toMatch(/more line/);
 	});
 
-	it("truncates the answer with a summary when collapsed", async () => {
+	it("shows the full answer when collapsed by default", async () => {
 		const uiTheme = (await getThemeByName("dark"))!;
 		const component = renderSearchResult(buildResult(ANSWER), { expanded: false, isPartial: false }, uiTheme, {
 			query: "test query",
 		});
 		const answer = answerSection(component.render(120).map(l => sanitizeText(l)));
-		// Collapsed view caps the answer and signals how many lines were hidden.
+		// TUI collapsed view keeps the answer intact; only explicit compact mode caps it.
+		expect(answer).toContain("FINAL_UNIQUE_MARKER");
+		expect(answer).not.toMatch(/more line/);
+	});
+
+	it("truncates the answer only when compact mode provides maxAnswerLines", async () => {
+		const uiTheme = (await getThemeByName("dark"))!;
+		const component = renderSearchResult(buildResult(ANSWER), { expanded: false, isPartial: false }, uiTheme, {
+			query: "test query",
+			maxAnswerLines: 3,
+		});
+		const answer = answerSection(component.render(120).map(l => sanitizeText(l)));
+
 		expect(answer).toMatch(/more line/);
 		expect(answer).not.toContain("FINAL_UNIQUE_MARKER");
 	});

From a7f5e83067c22638f01e6adef16f14c1a5ed5480 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 20:13:59 +0200
Subject: [PATCH 023/181] chore: bump version to 15.9.69

---
 Cargo.lock                            |  8 ++---
 Cargo.toml                            |  2 +-
 bun.lock                              | 46 +++++++++++++++------------
 crates/pi-natives/src/lib.rs          |  2 +-
 package.json                          | 18 +++++------
 packages/agent/package.json           |  2 +-
 packages/ai/package.json              |  2 +-
 packages/coding-agent/CHANGELOG.md    |  2 ++
 packages/coding-agent/package.json    |  2 +-
 packages/hashline/package.json        |  2 +-
 packages/mnemopi/package.json         |  2 +-
 packages/natives/native/index.d.ts    |  2 +-
 packages/natives/native/index.js      |  2 +-
 packages/natives/package.json         |  2 +-
 packages/stats/package.json           |  2 +-
 packages/swarm-extension/package.json |  2 +-
 packages/tui/CHANGELOG.md             |  2 ++
 packages/tui/package.json             |  2 +-
 packages/utils/package.json           |  2 +-
 19 files changed, 56 insertions(+), 48 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index b88543c78..170561fab 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2331,7 +2331,7 @@ dependencies = [
 
 [[package]]
 name = "pi-ast"
-version = "15.9.67"
+version = "15.9.69"
 dependencies = [
  "anyhow",
  "ast-grep-core",
@@ -2399,7 +2399,7 @@ dependencies = [
 
 [[package]]
 name = "pi-iso"
-version = "15.9.67"
+version = "15.9.69"
 dependencies = [
  "async-trait",
  "libc",
@@ -2411,7 +2411,7 @@ dependencies = [
 
 [[package]]
 name = "pi-natives"
-version = "15.9.67"
+version = "15.9.69"
 dependencies = [
  "anyhow",
  "arboard",
@@ -2457,7 +2457,7 @@ dependencies = [
 
 [[package]]
 name = "pi-shell"
-version = "15.9.67"
+version = "15.9.69"
 dependencies = [
  "anyhow",
  "brush-builtins",
diff --git a/Cargo.toml b/Cargo.toml
index 2cf4d2996..5a0405396 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ exclude = ["crates/brush-core-vendored", "crates/brush-builtins-vendored"]
 resolver = "3"
 
 [workspace.package]
-version = "15.9.67"
+version = "15.9.69"
 edition = "2024"
 license = "MIT"
 authors = ["Can Boluk"]
diff --git a/bun.lock b/bun.lock
index bff8b3963..78a5b2598 100644
--- a/bun.lock
+++ b/bun.lock
@@ -15,7 +15,7 @@
     },
     "packages/agent": {
       "name": "@oh-my-pi/pi-agent-core",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "dependencies": {
         "@oh-my-pi/pi-ai": "catalog:",
         "@oh-my-pi/pi-natives": "catalog:",
@@ -30,7 +30,7 @@
     },
     "packages/ai": {
       "name": "@oh-my-pi/pi-ai",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "dependencies": {
         "@bufbuild/protobuf": "catalog:",
         "@oh-my-pi/pi-utils": "catalog:",
@@ -44,7 +44,7 @@
     },
     "packages/coding-agent": {
       "name": "@oh-my-pi/pi-coding-agent",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "bin": {
         "omp": "src/cli.ts",
       },
@@ -90,7 +90,7 @@
     },
     "packages/hashline": {
       "name": "@oh-my-pi/hashline",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "dependencies": {
         "diff": "catalog:",
         "lru-cache": "catalog:",
@@ -101,7 +101,7 @@
     },
     "packages/mnemopi": {
       "name": "@oh-my-pi/pi-mnemopi",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "bin": {
         "mnemopi": "src/cli.ts",
       },
@@ -118,7 +118,7 @@
     },
     "packages/natives": {
       "name": "@oh-my-pi/pi-natives",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "devDependencies": {
         "@napi-rs/cli": "catalog:",
         "@types/bun": "catalog:",
@@ -126,7 +126,7 @@
     },
     "packages/stats": {
       "name": "@oh-my-pi/omp-stats",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "bin": {
         "omp-stats": "./src/index.ts",
       },
@@ -151,7 +151,7 @@
     },
     "packages/swarm-extension": {
       "name": "@oh-my-pi/swarm-extension",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "bin": {
         "omp-swarm": "src/cli.ts",
       },
@@ -167,7 +167,7 @@
     },
     "packages/tui": {
       "name": "@oh-my-pi/pi-tui",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "dependencies": {
         "@oh-my-pi/pi-natives": "catalog:",
         "@oh-my-pi/pi-utils": "catalog:",
@@ -208,7 +208,7 @@
     },
     "packages/utils": {
       "name": "@oh-my-pi/pi-utils",
-      "version": "15.9.67",
+      "version": "15.9.69",
       "dependencies": {
         "@oh-my-pi/pi-natives": "catalog:",
         "beautiful-mermaid": "catalog:",
@@ -248,15 +248,15 @@
     "@huggingface/transformers": "^4.2.0",
     "@mozilla/readability": "^0.6.0",
     "@napi-rs/cli": "3.7.0",
-    "@oh-my-pi/hashline": "15.9.67",
-    "@oh-my-pi/omp-stats": "15.9.67",
-    "@oh-my-pi/pi-agent-core": "15.9.67",
-    "@oh-my-pi/pi-ai": "15.9.67",
-    "@oh-my-pi/pi-coding-agent": "15.9.67",
-    "@oh-my-pi/pi-mnemopi": "15.9.67",
-    "@oh-my-pi/pi-natives": "15.9.67",
-    "@oh-my-pi/pi-tui": "15.9.67",
-    "@oh-my-pi/pi-utils": "15.9.67",
+    "@oh-my-pi/hashline": "15.9.69",
+    "@oh-my-pi/omp-stats": "15.9.69",
+    "@oh-my-pi/pi-agent-core": "15.9.69",
+    "@oh-my-pi/pi-ai": "15.9.69",
+    "@oh-my-pi/pi-coding-agent": "15.9.69",
+    "@oh-my-pi/pi-mnemopi": "15.9.69",
+    "@oh-my-pi/pi-natives": "15.9.69",
+    "@oh-my-pi/pi-tui": "15.9.69",
+    "@oh-my-pi/pi-utils": "15.9.69",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.7.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",
@@ -395,7 +395,7 @@
 
     "@huggingface/jinja": ["@huggingface/jinja@0.5.9", "", {}, "sha512-uWTG+l3VJRsl7EXxYizuL3P+cCPoc3cRqbWWRcQN0FhejRfbdq0RNhCmbY/YDtnTcz9icdLYuLDjsnz4d8JMuw=="],
 
-    "@huggingface/tasks": ["@huggingface/tasks@0.21.6", "", {}, "sha512-XfLE2clF0uHw7kMb6HHMkpyJ+bmu2T0EZ8O1WxbJXIqdRwKRB0RM7Y639Ph3aYj2GjFLJhNo1Lz8y0jn9k10LQ=="],
+    "@huggingface/tasks": ["@huggingface/tasks@0.21.7", "", {}, "sha512-GuEXszIkir4j/Oywp4hXP+wfwojo/SKWA/omroNkzWWgqUGiOQ5p6HuyXcDOcinYnLQW1WsO8fwdEvtLTZbA4w=="],
 
     "@huggingface/tokenizers": ["@huggingface/tokenizers@0.1.3", "", {}, "sha512-8rF/RRT10u+kn7YuUbUg0OF30K8rjTc78aHpxT+qJ1uWSqxT1MHi8+9ltwYfkFYJzT/oS+qw3JVfHtNMGAdqyA=="],
 
@@ -1259,7 +1259,7 @@
 
     "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
 
-    "string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
+    "string_decoder": ["string_decoder@1.3.0", "", { "dependencies": { "safe-buffer": "~5.2.0" } }, "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA=="],
 
     "strip-ansi": ["strip-ansi@7.2.0", "", { "dependencies": { "ansi-regex": "^6.2.2" } }, "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w=="],
 
@@ -1413,6 +1413,8 @@
 
     "string-width/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
 
+    "string_decoder/safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
+
     "wrap-ansi/string-width": ["string-width@8.2.1", "", { "dependencies": { "get-east-asian-width": "^1.5.0", "strip-ansi": "^7.1.2" } }, "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA=="],
 
     "xml2js/xmlbuilder": ["xmlbuilder@11.0.1", "", {}, "sha512-fDlsI/kFEx7gLvbecc0/ohLG50fugQp8ryHzMTuW9vSa1GJ0XYWKnhsUx7oie3G98+r56aTQIUB4kht42R3JvA=="],
@@ -1427,6 +1429,8 @@
 
     "fastembed/onnxruntime-node/tar": ["tar@7.5.16", "", { "dependencies": { "@isaacs/fs-minipass": "^4.0.0", "chownr": "^3.0.0", "minipass": "^7.1.2", "minizlib": "^3.1.0", "yallist": "^5.0.0" } }, "sha512-56adEpPMouktRlBLXiaYFFzZ/3+JXa8P9n7WbR+ibIjtviN55mEaOkiysCnPnWm+7kkui1Dn8J9l+g6zV8731w=="],
 
+    "jszip/readable-stream/string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
+
     "log-update/slice-ansi/is-fullwidth-code-point": ["is-fullwidth-code-point@5.1.0", "", { "dependencies": { "get-east-asian-width": "^1.3.1" } }, "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ=="],
 
     "log-update/wrap-ansi/string-width": ["string-width@7.2.0", "", { "dependencies": { "emoji-regex": "^10.3.0", "get-east-asian-width": "^1.0.0", "strip-ansi": "^7.1.0" } }, "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ=="],
diff --git a/crates/pi-natives/src/lib.rs b/crates/pi-natives/src/lib.rs
index 5017e2ddd..186fca14d 100644
--- a/crates/pi-natives/src/lib.rs
+++ b/crates/pi-natives/src/lib.rs
@@ -68,5 +68,5 @@ use napi_derive::napi;
 /// MUST stay in sync with `VERSION_SENTINEL_EXPORT` in
 /// `packages/natives/native/index.js` (which derives the name from
 /// `package.json#version`).
-#[napi(js_name = "__piNativesV15_9_67")]
+#[napi(js_name = "__piNativesV15_9_69")]
 pub const fn pi_natives_version_sentinel() {}
diff --git a/package.json b/package.json
index 542faa00e..78098d0fa 100644
--- a/package.json
+++ b/package.json
@@ -20,15 +20,15 @@
       "@huggingface/transformers": "^4.2.0",
       "@mozilla/readability": "^0.6.0",
       "@napi-rs/cli": "3.7.0",
-      "@oh-my-pi/hashline": "15.9.67",
-      "@oh-my-pi/omp-stats": "15.9.67",
-      "@oh-my-pi/pi-agent-core": "15.9.67",
-      "@oh-my-pi/pi-ai": "15.9.67",
-      "@oh-my-pi/pi-coding-agent": "15.9.67",
-      "@oh-my-pi/pi-mnemopi": "15.9.67",
-      "@oh-my-pi/pi-natives": "15.9.67",
-      "@oh-my-pi/pi-tui": "15.9.67",
-      "@oh-my-pi/pi-utils": "15.9.67",
+      "@oh-my-pi/hashline": "15.9.69",
+      "@oh-my-pi/omp-stats": "15.9.69",
+      "@oh-my-pi/pi-agent-core": "15.9.69",
+      "@oh-my-pi/pi-ai": "15.9.69",
+      "@oh-my-pi/pi-coding-agent": "15.9.69",
+      "@oh-my-pi/pi-mnemopi": "15.9.69",
+      "@oh-my-pi/pi-natives": "15.9.69",
+      "@oh-my-pi/pi-tui": "15.9.69",
+      "@oh-my-pi/pi-utils": "15.9.69",
       "@opentelemetry/api": "^1.9.1",
       "@opentelemetry/context-async-hooks": "^2.7.1",
       "@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",
diff --git a/packages/agent/package.json b/packages/agent/package.json
index eccf73aa8..6310a8e04 100644
--- a/packages/agent/package.json
+++ b/packages/agent/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/ai/package.json b/packages/ai/package.json
index 5c05d9e97..30ed8ddba 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 1f7b3db85..33ff5aaaf 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.9.69] - 2026-06-06
+
 ### Added
 
 - Added anonymous fallback for Perplexity web search, allowing `web_search` and explicit Perplexity provider usage when no Perplexity credentials are configured
diff --git a/packages/coding-agent/package.json b/packages/coding-agent/package.json
index ffe24bdca..7698d64de 100644
--- a/packages/coding-agent/package.json
+++ b/packages/coding-agent/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/hashline/package.json b/packages/hashline/package.json
index 2d04460bb..98c20ce7f 100644
--- a/packages/hashline/package.json
+++ b/packages/hashline/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/mnemopi/package.json b/packages/mnemopi/package.json
index 170d46cec..2687a9186 100644
--- a/packages/mnemopi/package.json
+++ b/packages/mnemopi/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-mnemopi",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "Local SQLite memory engine for Oh My Pi agents",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/natives/native/index.d.ts b/packages/natives/native/index.d.ts
index 9b2eaa14a..a008fcbb1 100644
--- a/packages/natives/native/index.d.ts
+++ b/packages/natives/native/index.d.ts
@@ -136,7 +136,7 @@ export declare class Shell {
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV15_9_67(): void
+export declare function __piNativesV15_9_69(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
diff --git a/packages/natives/native/index.js b/packages/natives/native/index.js
index cb0247d4a..9048b0f2e 100644
--- a/packages/natives/native/index.js
+++ b/packages/natives/native/index.js
@@ -23,7 +23,7 @@ export const PtySession = nativeBindings.PtySession;
 export const Shell = nativeBindings.Shell;
 
 // functions
-export const __piNativesV15_9_67 = nativeBindings.__piNativesV15_9_67;
+export const __piNativesV15_9_69 = nativeBindings.__piNativesV15_9_69;
 export const applyBashFixups = nativeBindings.applyBashFixups;
 export const astEdit = nativeBindings.astEdit;
 export const astGrep = nativeBindings.astGrep;
diff --git a/packages/natives/package.json b/packages/natives/package.json
index 2f7df44ef..65f55801e 100644
--- a/packages/natives/package.json
+++ b/packages/natives/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@oh-my-pi/pi-natives",
-  "version": "15.9.67",
+  "version": "15.9.69",
   "description": "Native Rust bindings for grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
   "type": "module",
   "homepage": "https://omp.sh",
diff --git a/packages/stats/package.json b/packages/stats/package.json
index bc1eb2e5a..79d24ca71 100644
--- a/packages/stats/package.json
+++ b/packages/stats/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/omp-stats",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "Local observability dashboard for pi AI usage statistics",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/swarm-extension/package.json b/packages/swarm-extension/package.json
index c0cb0db20..4e224cccb 100644
--- a/packages/swarm-extension/package.json
+++ b/packages/swarm-extension/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/swarm-extension",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "Swarm orchestration extension for omp",
 	"homepage": "https://omp.sh",
 	"author": "Derek Rynd",
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 40abd7bb6..f5151aefa 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.9.69] - 2026-06-06
+
 ### Added
 
 - Added `TUI.resetDisplay()` to force an immediate full-frame replay, including native scrollback when the host can safely clear it.
diff --git a/packages/tui/package.json b/packages/tui/package.json
index 1e16b084c..2a2140346 100644
--- a/packages/tui/package.json
+++ b/packages/tui/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/utils/package.json b/packages/utils/package.json
index 8aef12be3..6a022067f 100644
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "15.9.67",
+	"version": "15.9.69",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",

From cab465cba4f7e067d0992b77194bffa43f54a3b2 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:15:04 +0000
Subject: [PATCH 024/181] fix(eval): surfaced subagent abort reason through
 python agent() bridge

Python eval agent() collapsed every subagent runtime-limit abort into a
generic 'RuntimeError: bridge call __agent__ failed' instead of the real
reason. runEvalAgent built its failure message with:

  result.error ?? result.stderr ?? result.abortReason ?? <default>

? is nullish-coalescing, so result.stderr = "" (the executor's value for
a runtime-limit abort) short-circuited the chain and never reached
abortReason. The host bridge then shipped {ok: false, error: ""}, and
prelude.py's '<msg> or <fallback>' picked the named-bridge fallback.

Extracted buildSubagentFailureMessage(): aborted subagents prefer the
trimmed abortReason; otherwise fall through error, stderr (trimmed),
abortReason, and the named-bridge default. Empty/whitespace strings no
longer mask anything. The failure-detection condition also accepts
result.aborted so an abort with exitCode 0 (theoretically) still flows
the abort reason out.

Added a regression test asserting that runtime-limit aborts, whitespace
stderr/error, and totally blank aborts all produce non-empty messages
matching the executor's abortReason text.

Fixes #2006
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 .../src/eval/__tests__/agent-bridge.test.ts   | 51 +++++++++++++++++++
 .../coding-agent/src/eval/agent-bridge.ts     | 28 ++++++++--
 3 files changed, 75 insertions(+), 5 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 6515a5a39..e9378f066 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -15,6 +15,7 @@
 - Fixed framed read results rendering with an extra blank row above and below the output block.
 - Fixed collapsed search result previews that could show only "… N more matches" when the first grouped section exceeded the preview budget. Collapsed search output now compacts to match rows, fills the budget with visible hits before the summary, and keeps truncation details out of the bottom user-visible notice.
 - Fixed boolean environment flag overrides that were ORed with settings, so `PI_INTENT_TRACING=0`, `PI_AUTO_QA=0`, and per-backend eval flags now take precedence when present while falling back to config when unset.
+- Fixed Python eval `agent()` collapsing subagent runtime-limit aborts (and other empty-stderr aborts) into a generic `RuntimeError: bridge call '__agent__' failed`. `runEvalAgent` coalesced the failure message with `??`, which stopped at the empty `stderr` and never reached `abortReason`, shipping an empty error through the loopback bridge. The bridge now prefers `abortReason` for aborts and trims empty `stderr`/`error` out of the fallback chain, so Python surfaces the actionable reason (e.g. `Subagent runtime limit exceeded (task.maxRuntimeMs=900000)`) ([#2006](https://github.com/can1357/oh-my-pi/issues/2006)).
 
 ## [15.9.67] - 2026-06-06
 ### Added
diff --git a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
index 08bf08401..dd66f44cc 100644
--- a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
+++ b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
@@ -231,6 +231,57 @@ describe("runEvalAgent", () => {
 		});
 		await expect(runEvalAgent({ prompt: "fail" }, { session: makeSession() })).rejects.toThrow("boom");
 	});
+
+	// Regression: a runtime-limit abort returns exitCode=1, stderr="", error=undefined,
+	// aborted=true, abortReason="Subagent runtime limit exceeded (...)". The previous
+	// failure-message coalesce stopped at the empty `stderr` (since `??` only skips
+	// nullish values) and shipped an empty error through the bridge — Python then
+	// surfaced the generic `bridge call '__agent__' failed`. See #2006.
+	it("surfaces abortReason for aborts that leave stderr empty", async () => {
+		mockAgents();
+		const runSpy = vi.spyOn(taskExecutor, "runSubprocess");
+		runSpy.mockImplementationOnce(async options =>
+			singleResult(options, {
+				exitCode: 1,
+				output: "",
+				stderr: "",
+				error: undefined,
+				aborted: true,
+				abortReason: "Subagent runtime limit exceeded (task.maxRuntimeMs=900000)",
+			}),
+		);
+		runSpy.mockImplementationOnce(async options =>
+			singleResult(options, {
+				exitCode: 1,
+				output: "",
+				stderr: "   ",
+				error: "   ",
+				aborted: true,
+				abortReason: "Cancelled by caller",
+			}),
+		);
+		runSpy.mockImplementationOnce(async options =>
+			singleResult(options, {
+				exitCode: 1,
+				output: "",
+				stderr: "",
+				error: undefined,
+			}),
+		);
+
+		await expect(runEvalAgent({ prompt: "slow" }, { session: makeSession() })).rejects.toThrow(
+			"Subagent runtime limit exceeded (task.maxRuntimeMs=900000)",
+		);
+		// Whitespace-only stderr/error must not mask abortReason either.
+		await expect(runEvalAgent({ prompt: "cancelled" }, { session: makeSession() })).rejects.toThrow(
+			"Cancelled by caller",
+		);
+		// Last resort: still produce a non-empty message even when nothing useful is set,
+		// so Python never falls back to `bridge call '__agent__' failed`.
+		await expect(runEvalAgent({ prompt: "blank" }, { session: makeSession() })).rejects.toThrow(
+			"agent() subagent 'task' failed.",
+		);
+	});
 });
 
 describe("agent() through eval runtimes", () => {
diff --git a/packages/coding-agent/src/eval/agent-bridge.ts b/packages/coding-agent/src/eval/agent-bridge.ts
index a97f6c98e..696d9c011 100644
--- a/packages/coding-agent/src/eval/agent-bridge.ts
+++ b/packages/coding-agent/src/eval/agent-bridge.ts
@@ -13,7 +13,7 @@ import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.m
 import * as taskDiscovery from "../task/discovery";
 import * as taskExecutor from "../task/executor";
 import { AgentOutputManager } from "../task/output-manager";
-import type { AgentDefinition, AgentProgress } from "../task/types";
+import type { AgentDefinition, AgentProgress, SingleResult } from "../task/types";
 import type { ToolSession } from "../tools";
 import { ToolError } from "../tools/tool-errors";
 import { withBridgeTimeoutPause } from "./bridge-timeout";
@@ -173,6 +173,26 @@ function emitProgressStatus(emitStatus: ((event: JsStatusEvent) => void) | undef
 	});
 }
 
+/**
+ * Coalesce a subagent failure into a non-empty, human-meaningful error message.
+ *
+ * When the executor aborts a subagent (runtime limit, parent cancellation, …)
+ * the actionable explanation lives on `abortReason`, while `error`/`stderr`
+ * are routinely empty strings. Plain `??` coalescing stops at the empty string
+ * and ships an empty error through the bridge — Python then surfaces only the
+ * generic `bridge call '__agent__' failed`. See #2006.
+ */
+function buildSubagentFailureMessage(agentName: string, result: SingleResult): string {
+	const abortReason = trimToUndefined(result.abortReason);
+	if (result.aborted && abortReason) return abortReason;
+	return (
+		trimToUndefined(result.error) ??
+		trimToUndefined(result.stderr) ??
+		abortReason ??
+		`agent() subagent '${agentName}' failed.`
+	);
+}
+
 /**
  * Run a single subagent on behalf of an eval cell's `agent()` call.
  */
@@ -278,10 +298,8 @@ export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOption
 		}),
 	);
 
-	if (result.exitCode !== 0 || result.error) {
-		const failureMessage =
-			result.error ?? result.stderr ?? result.abortReason ?? `agent() subagent '${agentName}' failed.`;
-		throw new ToolError(failureMessage);
+	if (result.exitCode !== 0 || result.error || result.aborted) {
+		throw new ToolError(buildSubagentFailureMessage(agentName, result));
 	}
 
 	options.session.recordEvalSubagentUsage?.(result.usage?.output ?? 0);

From e83dbc177b33dda19dd9365eeca7f453b619f52f Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:15:09 +0000
Subject: [PATCH 025/181] style: bun run fix

---
 packages/coding-agent/test/extensions-runner.test.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/coding-agent/test/extensions-runner.test.ts b/packages/coding-agent/test/extensions-runner.test.ts
index 1542897a9..33e188b7f 100644
--- a/packages/coding-agent/test/extensions-runner.test.ts
+++ b/packages/coding-agent/test/extensions-runner.test.ts
@@ -148,7 +148,6 @@ describe("ExtensionRunner", () => {
 			warnSpy.mockRestore();
 		});
 
-
 		it("warns when two extensions register same shortcut", async () => {
 			// Use a non-reserved shortcut
 			const extCode1 = `

From 6dcbb07793c412427356975a002fcb3507a0ba24 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:20:27 +0000
Subject: [PATCH 026/181] fix(ai): replay xiaomi mimo anthropic-compat thinking
 blocks unsigned
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Anthropic-compat endpoints hosted under *.xiaomimimo.com (every
Xiaomi MiMo Token Plan region plus api.xiaomimimo.com) emit thinking
blocks without a signature. convertAnthropicMessages defaulted to
"signing capable" for any endpoint not explicitly allowlisted as
non-signing, so MiMo's unsigned thinking blocks were demoted to text on
every continuation request. Without its prior reasoning replayed, MiMo
destabilized tool-call argument serialization — the root cause behind
the args?.ops?.map crash already mitigated at the renderer in #2005.

Extend isNonSigningAnthropicEndpoint to cover the xiaomi catalog
provider, every xiaomi-token-plan-* provider id, and any baseUrl on
xiaomimimo.com so the existing non-signing replay branch fires for MiMo
the same way it does for DeepSeek and Z.AI.

Fixes #2005
---
 packages/ai/CHANGELOG.md                      |   4 +
 packages/ai/src/providers/anthropic.ts        |  20 ++-
 .../anthropic-xiaomi-thinking-replay.test.ts  | 153 ++++++++++++++++++
 packages/coding-agent/CHANGELOG.md            |   2 +-
 4 files changed, 174 insertions(+), 5 deletions(-)
 create mode 100644 packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 2f8dea9f7..ba2e08298 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed Xiaomi MiMo Anthropic-compat endpoints (`*.xiaomimimo.com/anthropic`, including every Token Plan region and `api.xiaomimimo.com`) losing prior-turn reasoning on continuation requests. `convertAnthropicMessages` treated all unknown endpoints as signing-capable and demoted MiMo's unsigned `thinking` blocks to `type: "text"`, which destabilized tool-call argument serialization on the next turn — the upstream symptom behind the `args?.ops?.map is not a function` crash reported against the `todo` tool ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)). `isNonSigningAnthropicEndpoint` now recognizes the Xiaomi family (provider id `xiaomi` / `xiaomi-token-plan-*` and the `xiaomimimo.com` host suffix) so unsigned thinking blocks replay as `type: "thinking"`.
+
 ## [15.9.67] - 2026-06-06
 
 ### Fixed
diff --git a/packages/ai/src/providers/anthropic.ts b/packages/ai/src/providers/anthropic.ts
index 6716952fc..b3b72c56d 100644
--- a/packages/ai/src/providers/anthropic.ts
+++ b/packages/ai/src/providers/anthropic.ts
@@ -2428,18 +2428,30 @@ function isZaiAnthropicEndpoint(model: Model<"anthropic-messages">): boolean {
 
 /**
  * Returns true for providers whose Anthropic-compatible endpoints do NOT
- * implement signature-based thinking-chain integrity (DeepSeek, Z.AI, etc.).
- * For these providers, unsigned thinking blocks must be preserved as
- * `type: "thinking"` instead of being degraded to text.
+ * implement signature-based thinking-chain integrity (DeepSeek, Z.AI,
+ * Xiaomi MiMo Token Plan, …). For these providers, unsigned `thinking`
+ * blocks emitted on prior assistant turns must be replayed as
+ * `type: "thinking"` instead of being degraded to `type: "text"` — the
+ * model relies on seeing its own reasoning chain back in the conversation
+ * to keep tool-call argument serialization stable (#2005).
  */
 function isNonSigningAnthropicEndpoint(model: Model<"anthropic-messages">): boolean {
 	// Known non-signing providers
 	if (model.provider === "zai" || model.provider === "deepseek") return true;
+	// Xiaomi MiMo (catalog `xiaomi` + every Token Plan region) exposes an
+	// Anthropic-compat endpoint that does not sign its `thinking` blocks.
+	// Match the provider-id pattern used in `openai-completions-compat.ts`.
+	if (model.provider === "xiaomi" || model.provider.startsWith("xiaomi-token-plan-")) return true;
 	const baseUrl = model.baseUrl;
 	if (!baseUrl) return false;
 	try {
 		const hostname = new URL(baseUrl).hostname.toLowerCase();
-		return hostname === "api.deepseek.com" || hostname.endsWith(".deepseek.com");
+		if (hostname === "api.deepseek.com" || hostname.endsWith(".deepseek.com")) return true;
+		// Cover user-defined providers pointed at any Xiaomi Token Plan host
+		// (e.g. `token-plan-sgp.xiaomimimo.com/anthropic`), matching the
+		// existing `xiaomimimo.com` detection in `append-only-context-mode.ts`.
+		if (hostname === "xiaomimimo.com" || hostname.endsWith(".xiaomimimo.com")) return true;
+		return false;
 	} catch {
 		return false;
 	}
diff --git a/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts b/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts
new file mode 100644
index 000000000..aa4e075e1
--- /dev/null
+++ b/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts
@@ -0,0 +1,153 @@
+import { describe, expect, it } from "bun:test";
+import { convertAnthropicMessages } from "@oh-my-pi/pi-ai/providers/anthropic";
+import type { AssistantMessage, Message, Model, ToolResultMessage, UserMessage } from "@oh-my-pi/pi-ai/types";
+
+/**
+ * Regression: Xiaomi MiMo's Anthropic-compat endpoint
+ * (`token-plan-*.xiaomimimo.com/anthropic`, `api.xiaomimimo.com/anthropic`)
+ * emits `thinking` blocks WITHOUT a `signature`. Before #2005, the conversion
+ * layer treated any unknown Anthropic endpoint as signing-capable, so those
+ * unsigned thinking blocks got demoted to `type: "text"` on replay. With the
+ * reasoning chain stripped, MiMo's next continuation surfaced malformed tool
+ * arguments (e.g. `todo.ops` arriving as a JSON-string), triggering the
+ * downstream renderer crash and retry-spam reported in #2005.
+ *
+ * Now that `isNonSigningAnthropicEndpoint` recognizes the Xiaomi family,
+ * unsigned `thinking` blocks must round-trip as `{ type: "thinking", signature: "" }`.
+ */
+function makeXiaomiModel(overrides: Partial<Model<"anthropic-messages">> = {}): Model<"anthropic-messages"> {
+	return {
+		api: "anthropic-messages",
+		provider: "xiaomi-token-plan-sgp",
+		id: "mimo-v2.5-pro",
+		name: "MiMo V2.5 Pro (Singapore)",
+		baseUrl: "https://token-plan-sgp.xiaomimimo.com/anthropic",
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		maxTokens: 131_072,
+		contextWindow: 1_048_576,
+		reasoning: true,
+		...overrides,
+	};
+}
+
+function makeUser(text = "continue"): UserMessage {
+	return { role: "user", content: text, timestamp: 0 };
+}
+
+function makeAssistantThinking(thinking: string, tail: AssistantMessage["content"][number][] = []): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [{ type: "thinking", thinking, thinkingSignature: "" }, ...tail],
+		api: "anthropic-messages",
+		provider: "xiaomi-token-plan-sgp",
+		model: "mimo-v2.5-pro",
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "toolUse",
+		timestamp: 0,
+	};
+}
+
+interface WireThinkingBlock {
+	type: "thinking";
+	thinking: string;
+	signature: string;
+}
+interface WireTextBlock {
+	type: "text";
+	text: string;
+}
+type WireBlock = WireThinkingBlock | WireTextBlock | { type: string; [key: string]: unknown };
+
+function assistantWireBlocks(messages: Message[], model: Model<"anthropic-messages">): WireBlock[] {
+	const params = convertAnthropicMessages(messages, model, false);
+	const assistant = params.find(p => p.role === "assistant");
+	return (assistant?.content as WireBlock[] | undefined) ?? [];
+}
+
+describe("Xiaomi MiMo Anthropic-compat thinking replay (#2005)", () => {
+	it("preserves unsigned thinking blocks as type:'thinking' for xiaomi-token-plan-sgp", () => {
+		const blocks = assistantWireBlocks(
+			[
+				makeUser("solve x"),
+				makeAssistantThinking("plan: read the file, then edit", [{ type: "text", text: "Sure." }]),
+			],
+			makeXiaomiModel(),
+		);
+		// Critical: a `thinking` block survives — without the fix it would have
+		// been demoted to a `text` block and the model would replay garbled args.
+		expect(blocks[0]).toEqual({
+			type: "thinking",
+			thinking: "plan: read the file, then edit",
+			signature: "",
+		});
+		expect(blocks[1]).toEqual({ type: "text", text: "Sure." });
+	});
+
+	it("preserves unsigned thinking for every Token Plan region (ams, cn) and api.xiaomimimo.com", () => {
+		for (const baseUrl of [
+			"https://token-plan-ams.xiaomimimo.com/anthropic",
+			"https://token-plan-cn.xiaomimimo.com/anthropic",
+			"https://api.xiaomimimo.com/anthropic",
+		]) {
+			const model = makeXiaomiModel({ baseUrl, provider: "user-custom" });
+			const blocks = assistantWireBlocks(
+				[makeUser(), makeAssistantThinking("hidden reasoning")],
+				model,
+			);
+			expect(blocks[0]?.type).toBe("thinking");
+			expect((blocks[0] as WireThinkingBlock).thinking).toBe("hidden reasoning");
+		}
+	});
+
+	it("still degrades unsigned thinking to text for unknown signing-capable endpoints", () => {
+		// Sanity guard: don't flip the default for, e.g., api.anthropic.com.
+		const anthropicModel: Model<"anthropic-messages"> = {
+			...makeXiaomiModel(),
+			provider: "anthropic",
+			baseUrl: "https://api.anthropic.com",
+			id: "claude-sonnet-4-6",
+		};
+		const blocks = assistantWireBlocks(
+			[makeUser(), makeAssistantThinking("internal scratch")],
+			anthropicModel,
+		);
+		expect(blocks[0]?.type).toBe("text");
+		expect((blocks[0] as WireTextBlock).text).toBe("internal scratch");
+	});
+
+	it("keeps thinking → tool_use pairing intact across the conversion (continuation contract)", () => {
+		// The original failure mode: continuation request after a tool call.
+		// Thinking must precede `tool_use`, both must survive, and the
+		// `tool_result` must follow as the next user turn.
+		const toolResult: ToolResultMessage = {
+			role: "toolResult",
+			toolCallId: "toolu_xiaomi_1",
+			toolName: "read",
+			content: [{ type: "text", text: "file body" }],
+			isError: false,
+			timestamp: 0,
+		};
+		const model = makeXiaomiModel();
+		const messages: Message[] = [
+			makeUser("read README"),
+			makeAssistantThinking("I need to call the read tool", [
+				{ type: "toolCall", id: "toolu_xiaomi_1", name: "read", arguments: { path: "README.md" } },
+			]),
+			toolResult,
+		];
+		const params = convertAnthropicMessages(messages, model, false);
+		expect(params.map(p => p.role)).toEqual(["user", "assistant", "user"]);
+		const assistantBlocks = params[1].content as WireBlock[];
+		expect(assistantBlocks[0]?.type).toBe("thinking");
+		expect(assistantBlocks[1]?.type).toBe("tool_use");
+		expect((assistantBlocks[1] as { id: string }).id).toBe("toolu_xiaomi_1");
+	});
+});
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 101c92e73..56b633357 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -15,7 +15,7 @@
 - Fixed framed read results rendering with an extra blank row above and below the output block.
 - Fixed collapsed search result previews that could show only "… N more matches" when the first grouped section exceeded the preview budget. Collapsed search output now compacts to match rows, fills the budget with visible hits before the summary, and keeps truncation details out of the bottom user-visible notice.
 - Fixed boolean environment flag overrides that were ORed with settings, so `PI_INTENT_TRACING=0`, `PI_AUTO_QA=0`, and per-backend eval flags now take precedence when present while falling back to config when unset.
-- Fixed the `todo` tool's TUI renderer crashing with `TypeError: args?.ops?.map is not a function` when a streaming tool-call delta surfaces a non-array `ops` field (mid-stream `parseStreamingJson` shapes like `{ ops: "[{" }`, or `[null]` entries before fields arrive). The renderer now treats non-array `ops`, non-object entries, and non-array `items` as missing structure instead of crashing, which also stops the spam-warn/retry cascade that followed each malformed delta ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
+- Fixed the `todo` tool's TUI renderer crashing with `TypeError: args?.ops?.map is not a function` when a streaming tool-call delta surfaced a non-array `ops` field (mid-stream `parseStreamingJson` shapes like `{ ops: "[{" }`, or `[null]` entries before fields arrive). The renderer now treats non-array `ops`, non-object entries, and non-array `items` as missing structure instead of crashing, which also stops the spam-warn cascade that followed each malformed delta. Paired with the Anthropic-side reasoning-replay fix in `packages/ai` ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
 
 ## [15.9.67] - 2026-06-06
 ### Added

From ae3477abfdf414cf7d8abe3216b7633ae7fcb2c0 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:20:33 +0000
Subject: [PATCH 027/181] style: bun run fix

---
 .../ai/test/anthropic-xiaomi-thinking-replay.test.ts | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts b/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts
index aa4e075e1..629113a05 100644
--- a/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts
+++ b/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts
@@ -98,10 +98,7 @@ describe("Xiaomi MiMo Anthropic-compat thinking replay (#2005)", () => {
 			"https://api.xiaomimimo.com/anthropic",
 		]) {
 			const model = makeXiaomiModel({ baseUrl, provider: "user-custom" });
-			const blocks = assistantWireBlocks(
-				[makeUser(), makeAssistantThinking("hidden reasoning")],
-				model,
-			);
+			const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("hidden reasoning")], model);
 			expect(blocks[0]?.type).toBe("thinking");
 			expect((blocks[0] as WireThinkingBlock).thinking).toBe("hidden reasoning");
 		}
@@ -115,10 +112,7 @@ describe("Xiaomi MiMo Anthropic-compat thinking replay (#2005)", () => {
 			baseUrl: "https://api.anthropic.com",
 			id: "claude-sonnet-4-6",
 		};
-		const blocks = assistantWireBlocks(
-			[makeUser(), makeAssistantThinking("internal scratch")],
-			anthropicModel,
-		);
+		const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("internal scratch")], anthropicModel);
 		expect(blocks[0]?.type).toBe("text");
 		expect((blocks[0] as WireTextBlock).text).toBe("internal scratch");
 	});
@@ -148,6 +142,6 @@ describe("Xiaomi MiMo Anthropic-compat thinking replay (#2005)", () => {
 		const assistantBlocks = params[1].content as WireBlock[];
 		expect(assistantBlocks[0]?.type).toBe("thinking");
 		expect(assistantBlocks[1]?.type).toBe("tool_use");
-		expect((assistantBlocks[1] as { id: string }).id).toBe("toolu_xiaomi_1");
+		expect((assistantBlocks[1] as unknown as { id: string }).id).toBe("toolu_xiaomi_1");
 	});
 });

From d08e4ebb1f85789996536a5a1b063aac6bd02f94 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:29:43 +0000
Subject: [PATCH 028/181] fix(ai): generalize anthropic unsigned thinking
 replay

Anthropic-compatible reasoning providers commonly emit thinking blocks
without first-party Anthropic signatures while still expecting those
blocks back as native thinking on continuation. The previous follow-up
for #2005 fixed Xiaomi by provider/host allowlist, but the protocol
contract is broader and matches the behavior described in #1996.

Replace the Xiaomi-specific branch with a protocol-level rule:
- official api.anthropic.com keeps demoting unsigned thinking to text
- non-official anthropic-messages reasoning models replay unsigned
  thinking as type: thinking with an empty signature
- existing known non-signing DeepSeek/Z.AI compatibility remains

The regression test now uses a generic Anthropic-compatible reasoning
endpoint, includes the Xiaomi MiMo reporter configuration only as a
fixture, and guards non-reasoning unknown endpoints plus official
Anthropic behavior.

Fixes #2005
---
 packages/ai/CHANGELOG.md                      |   2 +-
 packages/ai/src/providers/anthropic.ts        |  51 +++---
 ...anthropic-unsigned-thinking-replay.test.ts | 153 ++++++++++++++++++
 .../anthropic-xiaomi-thinking-replay.test.ts  | 147 -----------------
 4 files changed, 182 insertions(+), 171 deletions(-)
 create mode 100644 packages/ai/test/anthropic-unsigned-thinking-replay.test.ts
 delete mode 100644 packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index ba2e08298..bca3d6f7e 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Fixed
 
-- Fixed Xiaomi MiMo Anthropic-compat endpoints (`*.xiaomimimo.com/anthropic`, including every Token Plan region and `api.xiaomimimo.com`) losing prior-turn reasoning on continuation requests. `convertAnthropicMessages` treated all unknown endpoints as signing-capable and demoted MiMo's unsigned `thinking` blocks to `type: "text"`, which destabilized tool-call argument serialization on the next turn — the upstream symptom behind the `args?.ops?.map is not a function` crash reported against the `todo` tool ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)). `isNonSigningAnthropicEndpoint` now recognizes the Xiaomi family (provider id `xiaomi` / `xiaomi-token-plan-*` and the `xiaomimimo.com` host suffix) so unsigned thinking blocks replay as `type: "thinking"`.
+- Fixed Anthropic-compatible reasoning endpoints losing prior-turn reasoning on continuation requests when they emit unsigned `thinking` blocks. `convertAnthropicMessages` treated unknown endpoints as signature-enforcing and demoted unsigned reasoning to `type: "text"`, which destabilized tool-call argument serialization on the next turn — the upstream symptom behind the `args?.ops?.map is not a function` crash reported against the `todo` tool. Official `api.anthropic.com` keeps the conservative text fallback; non-official `anthropic-messages` reasoning models now replay unsigned reasoning as native `type: "thinking"` ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
 
 ## [15.9.67] - 2026-06-06
 
diff --git a/packages/ai/src/providers/anthropic.ts b/packages/ai/src/providers/anthropic.ts
index b3b72c56d..ac75d6798 100644
--- a/packages/ai/src/providers/anthropic.ts
+++ b/packages/ai/src/providers/anthropic.ts
@@ -2426,37 +2426,42 @@ function isZaiAnthropicEndpoint(model: Model<"anthropic-messages">): boolean {
 	}
 }
 
-/**
- * Returns true for providers whose Anthropic-compatible endpoints do NOT
- * implement signature-based thinking-chain integrity (DeepSeek, Z.AI,
- * Xiaomi MiMo Token Plan, …). For these providers, unsigned `thinking`
- * blocks emitted on prior assistant turns must be replayed as
- * `type: "thinking"` instead of being degraded to `type: "text"` — the
- * model relies on seeing its own reasoning chain back in the conversation
- * to keep tool-call argument serialization stable (#2005).
- */
-function isNonSigningAnthropicEndpoint(model: Model<"anthropic-messages">): boolean {
-	// Known non-signing providers
-	if (model.provider === "zai" || model.provider === "deepseek") return true;
-	// Xiaomi MiMo (catalog `xiaomi` + every Token Plan region) exposes an
-	// Anthropic-compat endpoint that does not sign its `thinking` blocks.
-	// Match the provider-id pattern used in `openai-completions-compat.ts`.
-	if (model.provider === "xiaomi" || model.provider.startsWith("xiaomi-token-plan-")) return true;
+function isOfficialAnthropicEndpoint(model: Model<"anthropic-messages">): boolean {
 	const baseUrl = model.baseUrl;
 	if (!baseUrl) return false;
 	try {
 		const hostname = new URL(baseUrl).hostname.toLowerCase();
-		if (hostname === "api.deepseek.com" || hostname.endsWith(".deepseek.com")) return true;
-		// Cover user-defined providers pointed at any Xiaomi Token Plan host
-		// (e.g. `token-plan-sgp.xiaomimimo.com/anthropic`), matching the
-		// existing `xiaomimimo.com` detection in `append-only-context-mode.ts`.
-		if (hostname === "xiaomimimo.com" || hostname.endsWith(".xiaomimimo.com")) return true;
-		return false;
+		return hostname === "api.anthropic.com";
 	} catch {
 		return false;
 	}
 }
 
+/**
+ * Returns true when unsigned `thinking` blocks from prior assistant turns should
+ * be replayed as Anthropic-native thinking instead of demoted to text.
+ *
+ * Official Anthropic enforces signature-based thinking-chain integrity, so
+ * unsigned blocks must remain text there. Anthropic-compatible reasoning
+ * endpoints commonly emit unsigned thinking blocks while still expecting those
+ * blocks back as `type: "thinking"` on continuation; demoting them loses the
+ * model's reasoning chain and can destabilize the next tool-call arguments
+ * (#2005). Known non-signing hosts are also preserved for compatibility.
+ */
+function shouldReplayUnsignedThinking(model: Model<"anthropic-messages">): boolean {
+	if (model.provider === "zai" || model.provider === "deepseek") return true;
+	const baseUrl = model.baseUrl;
+	if (baseUrl) {
+		try {
+			const hostname = new URL(baseUrl).hostname.toLowerCase();
+			if (hostname === "api.deepseek.com" || hostname.endsWith(".deepseek.com")) return true;
+		} catch {
+			// Fall through to the protocol-level reasoning rule below.
+		}
+	}
+	return model.reasoning && !isOfficialAnthropicEndpoint(model);
+}
+
 function buildToolResultBlock(model: Model<"anthropic-messages">, msg: ToolResultMessage): ContentBlockParam {
 	const block: ContentBlockParam = {
 		type: "tool_result",
@@ -2545,7 +2550,7 @@ export function convertAnthropicMessages(
 					}
 					if (block.thinking.trim().length === 0) continue;
 					if (!block.thinkingSignature || block.thinkingSignature.trim().length === 0) {
-						if (isNonSigningAnthropicEndpoint(model)) {
+						if (shouldReplayUnsignedThinking(model)) {
 							blocks.push({
 								type: "thinking",
 								thinking: block.thinking.toWellFormed(),
diff --git a/packages/ai/test/anthropic-unsigned-thinking-replay.test.ts b/packages/ai/test/anthropic-unsigned-thinking-replay.test.ts
new file mode 100644
index 000000000..7e33e859f
--- /dev/null
+++ b/packages/ai/test/anthropic-unsigned-thinking-replay.test.ts
@@ -0,0 +1,153 @@
+import { describe, expect, it } from "bun:test";
+import { convertAnthropicMessages } from "@oh-my-pi/pi-ai/providers/anthropic";
+import type { AssistantMessage, Message, Model, ToolResultMessage, UserMessage } from "@oh-my-pi/pi-ai/types";
+
+/**
+ * Regression: Anthropic-compatible reasoning endpoints often emit `thinking`
+ * blocks without a first-party Anthropic signature, but still expect those
+ * blocks back as native `type: "thinking"` on continuation. Demoting unsigned
+ * thinking to text strips the reasoning chain and can destabilize follow-up
+ * tool-call argument serialization (the upstream cause behind #2005's `todo`
+ * renderer crash).
+ *
+ * Official Anthropic remains conservative: unsigned thinking is demoted to text
+ * there because the first-party API enforces signature-based integrity.
+ */
+function makeModel(overrides: Partial<Model<"anthropic-messages">> = {}): Model<"anthropic-messages"> {
+	return {
+		api: "anthropic-messages",
+		provider: "custom-anthropic",
+		id: "reasoning-model",
+		name: "Reasoning Anthropic-Compatible Model",
+		baseUrl: "https://llm.example.com/anthropic",
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		maxTokens: 8_192,
+		contextWindow: 200_000,
+		reasoning: true,
+		...overrides,
+	};
+}
+
+function makeUser(text = "continue"): UserMessage {
+	return { role: "user", content: text, timestamp: 0 };
+}
+
+function makeAssistantThinking(thinking: string, tail: AssistantMessage["content"][number][] = []): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [{ type: "thinking", thinking, thinkingSignature: "" }, ...tail],
+		api: "anthropic-messages",
+		provider: "custom-anthropic",
+		model: "reasoning-model",
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "toolUse",
+		timestamp: 0,
+	};
+}
+
+interface WireThinkingBlock {
+	type: "thinking";
+	thinking: string;
+	signature: string;
+}
+interface WireTextBlock {
+	type: "text";
+	text: string;
+}
+interface WireToolUseBlock {
+	type: "tool_use";
+	id: string;
+	name: string;
+	input: Record<string, unknown>;
+}
+type WireBlock = WireThinkingBlock | WireTextBlock | WireToolUseBlock | { type: string; [key: string]: unknown };
+
+function assistantWireBlocks(messages: Message[], model: Model<"anthropic-messages">): WireBlock[] {
+	const params = convertAnthropicMessages(messages, model, false);
+	const assistant = params.find(p => p.role === "assistant");
+	return (assistant?.content as WireBlock[] | undefined) ?? [];
+}
+
+describe("Anthropic-compatible unsigned thinking replay (#2005)", () => {
+	it("preserves unsigned thinking for non-official reasoning endpoints", () => {
+		const blocks = assistantWireBlocks(
+			[
+				makeUser("solve x"),
+				makeAssistantThinking("plan: read the file, then edit", [{ type: "text", text: "Sure." }]),
+			],
+			makeModel(),
+		);
+		expect(blocks[0]).toEqual({
+			type: "thinking",
+			thinking: "plan: read the file, then edit",
+			signature: "",
+		});
+		expect(blocks[1]).toEqual({ type: "text", text: "Sure." });
+	});
+
+	it("covers the Xiaomi MiMo Anthropic-compatible reporter configuration without provider allowlists", () => {
+		const model = makeModel({
+			provider: "user-custom",
+			id: "mimo-v2.5-pro",
+			name: "MiMo V2.5 Pro (Singapore)",
+			baseUrl: "https://token-plan-sgp.xiaomimimo.com/anthropic",
+			maxTokens: 131_072,
+			contextWindow: 1_048_576,
+		});
+		const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("hidden reasoning")], model);
+		expect(blocks[0]).toEqual({ type: "thinking", thinking: "hidden reasoning", signature: "" });
+	});
+
+	it("preserves legacy known non-signing endpoints even if model.reasoning is false", () => {
+		const model = makeModel({ provider: "custom", baseUrl: "https://api.deepseek.com/v1", reasoning: false });
+		const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("deepseek reasoning")], model);
+		expect(blocks[0]?.type).toBe("thinking");
+	});
+
+	it("still degrades unsigned thinking to text for official Anthropic", () => {
+		const model = makeModel({ provider: "anthropic", baseUrl: "https://api.anthropic.com" });
+		const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("internal scratch")], model);
+		expect(blocks[0]?.type).toBe("text");
+		expect((blocks[0] as WireTextBlock).text).toBe("internal scratch");
+	});
+
+	it("still degrades unsigned thinking to text for non-reasoning unknown endpoints", () => {
+		const model = makeModel({ reasoning: false, baseUrl: "https://plain.example.com/anthropic" });
+		const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("scratch")], model);
+		expect(blocks[0]?.type).toBe("text");
+		expect((blocks[0] as WireTextBlock).text).toBe("scratch");
+	});
+
+	it("keeps thinking → tool_use pairing intact across continuation conversion", () => {
+		const toolResult: ToolResultMessage = {
+			role: "toolResult",
+			toolCallId: "toolu_reasoning_1",
+			toolName: "read",
+			content: [{ type: "text", text: "file body" }],
+			isError: false,
+			timestamp: 0,
+		};
+		const model = makeModel();
+		const messages: Message[] = [
+			makeUser("read README"),
+			makeAssistantThinking("I need to call the read tool", [
+				{ type: "toolCall", id: "toolu_reasoning_1", name: "read", arguments: { path: "README.md" } },
+			]),
+			toolResult,
+		];
+		const params = convertAnthropicMessages(messages, model, false);
+		expect(params.map(p => p.role)).toEqual(["user", "assistant", "user"]);
+		const assistantBlocks = params[1].content as WireBlock[];
+		expect(assistantBlocks[0]?.type).toBe("thinking");
+		expect(assistantBlocks[1]?.type).toBe("tool_use");
+		expect((assistantBlocks[1] as WireToolUseBlock).id).toBe("toolu_reasoning_1");
+	});
+});
diff --git a/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts b/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts
deleted file mode 100644
index 629113a05..000000000
--- a/packages/ai/test/anthropic-xiaomi-thinking-replay.test.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { convertAnthropicMessages } from "@oh-my-pi/pi-ai/providers/anthropic";
-import type { AssistantMessage, Message, Model, ToolResultMessage, UserMessage } from "@oh-my-pi/pi-ai/types";
-
-/**
- * Regression: Xiaomi MiMo's Anthropic-compat endpoint
- * (`token-plan-*.xiaomimimo.com/anthropic`, `api.xiaomimimo.com/anthropic`)
- * emits `thinking` blocks WITHOUT a `signature`. Before #2005, the conversion
- * layer treated any unknown Anthropic endpoint as signing-capable, so those
- * unsigned thinking blocks got demoted to `type: "text"` on replay. With the
- * reasoning chain stripped, MiMo's next continuation surfaced malformed tool
- * arguments (e.g. `todo.ops` arriving as a JSON-string), triggering the
- * downstream renderer crash and retry-spam reported in #2005.
- *
- * Now that `isNonSigningAnthropicEndpoint` recognizes the Xiaomi family,
- * unsigned `thinking` blocks must round-trip as `{ type: "thinking", signature: "" }`.
- */
-function makeXiaomiModel(overrides: Partial<Model<"anthropic-messages">> = {}): Model<"anthropic-messages"> {
-	return {
-		api: "anthropic-messages",
-		provider: "xiaomi-token-plan-sgp",
-		id: "mimo-v2.5-pro",
-		name: "MiMo V2.5 Pro (Singapore)",
-		baseUrl: "https://token-plan-sgp.xiaomimimo.com/anthropic",
-		input: ["text"],
-		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-		maxTokens: 131_072,
-		contextWindow: 1_048_576,
-		reasoning: true,
-		...overrides,
-	};
-}
-
-function makeUser(text = "continue"): UserMessage {
-	return { role: "user", content: text, timestamp: 0 };
-}
-
-function makeAssistantThinking(thinking: string, tail: AssistantMessage["content"][number][] = []): AssistantMessage {
-	return {
-		role: "assistant",
-		content: [{ type: "thinking", thinking, thinkingSignature: "" }, ...tail],
-		api: "anthropic-messages",
-		provider: "xiaomi-token-plan-sgp",
-		model: "mimo-v2.5-pro",
-		usage: {
-			input: 0,
-			output: 0,
-			cacheRead: 0,
-			cacheWrite: 0,
-			totalTokens: 0,
-			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-		},
-		stopReason: "toolUse",
-		timestamp: 0,
-	};
-}
-
-interface WireThinkingBlock {
-	type: "thinking";
-	thinking: string;
-	signature: string;
-}
-interface WireTextBlock {
-	type: "text";
-	text: string;
-}
-type WireBlock = WireThinkingBlock | WireTextBlock | { type: string; [key: string]: unknown };
-
-function assistantWireBlocks(messages: Message[], model: Model<"anthropic-messages">): WireBlock[] {
-	const params = convertAnthropicMessages(messages, model, false);
-	const assistant = params.find(p => p.role === "assistant");
-	return (assistant?.content as WireBlock[] | undefined) ?? [];
-}
-
-describe("Xiaomi MiMo Anthropic-compat thinking replay (#2005)", () => {
-	it("preserves unsigned thinking blocks as type:'thinking' for xiaomi-token-plan-sgp", () => {
-		const blocks = assistantWireBlocks(
-			[
-				makeUser("solve x"),
-				makeAssistantThinking("plan: read the file, then edit", [{ type: "text", text: "Sure." }]),
-			],
-			makeXiaomiModel(),
-		);
-		// Critical: a `thinking` block survives — without the fix it would have
-		// been demoted to a `text` block and the model would replay garbled args.
-		expect(blocks[0]).toEqual({
-			type: "thinking",
-			thinking: "plan: read the file, then edit",
-			signature: "",
-		});
-		expect(blocks[1]).toEqual({ type: "text", text: "Sure." });
-	});
-
-	it("preserves unsigned thinking for every Token Plan region (ams, cn) and api.xiaomimimo.com", () => {
-		for (const baseUrl of [
-			"https://token-plan-ams.xiaomimimo.com/anthropic",
-			"https://token-plan-cn.xiaomimimo.com/anthropic",
-			"https://api.xiaomimimo.com/anthropic",
-		]) {
-			const model = makeXiaomiModel({ baseUrl, provider: "user-custom" });
-			const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("hidden reasoning")], model);
-			expect(blocks[0]?.type).toBe("thinking");
-			expect((blocks[0] as WireThinkingBlock).thinking).toBe("hidden reasoning");
-		}
-	});
-
-	it("still degrades unsigned thinking to text for unknown signing-capable endpoints", () => {
-		// Sanity guard: don't flip the default for, e.g., api.anthropic.com.
-		const anthropicModel: Model<"anthropic-messages"> = {
-			...makeXiaomiModel(),
-			provider: "anthropic",
-			baseUrl: "https://api.anthropic.com",
-			id: "claude-sonnet-4-6",
-		};
-		const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("internal scratch")], anthropicModel);
-		expect(blocks[0]?.type).toBe("text");
-		expect((blocks[0] as WireTextBlock).text).toBe("internal scratch");
-	});
-
-	it("keeps thinking → tool_use pairing intact across the conversion (continuation contract)", () => {
-		// The original failure mode: continuation request after a tool call.
-		// Thinking must precede `tool_use`, both must survive, and the
-		// `tool_result` must follow as the next user turn.
-		const toolResult: ToolResultMessage = {
-			role: "toolResult",
-			toolCallId: "toolu_xiaomi_1",
-			toolName: "read",
-			content: [{ type: "text", text: "file body" }],
-			isError: false,
-			timestamp: 0,
-		};
-		const model = makeXiaomiModel();
-		const messages: Message[] = [
-			makeUser("read README"),
-			makeAssistantThinking("I need to call the read tool", [
-				{ type: "toolCall", id: "toolu_xiaomi_1", name: "read", arguments: { path: "README.md" } },
-			]),
-			toolResult,
-		];
-		const params = convertAnthropicMessages(messages, model, false);
-		expect(params.map(p => p.role)).toEqual(["user", "assistant", "user"]);
-		const assistantBlocks = params[1].content as WireBlock[];
-		expect(assistantBlocks[0]?.type).toBe("thinking");
-		expect(assistantBlocks[1]?.type).toBe("tool_use");
-		expect((assistantBlocks[1] as unknown as { id: string }).id).toBe("toolu_xiaomi_1");
-	});
-});

From 5046f0f47c58d2004db86f6cdefc4e3cd432c486 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:34:17 +0000
Subject: [PATCH 029/181] fix(ai): treat missing anthropic baseUrl as official
 in thinking replay
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

resolveAnthropicBaseUrl defaults to https://api.anthropic.com when
model.baseUrl is absent (e.g. same-id custom overrides that only tweak
metadata), and the existing isAnthropicApiBaseUrl helper already treats
an empty/undefined baseUrl as official. The new isOfficialAnthropicEndpoint
helper classified the same model as non-official, so
shouldReplayUnsignedThinking would replay unsigned thinking as
type: thinking against the first-party API — which rejects it.

Drop the redundant helper and use isAnthropicApiBaseUrl as the single
source of truth. Add a regression test that pins the missing-baseUrl
case to the text fallback.
---
 packages/ai/src/providers/anthropic.ts        | 28 +++++++------------
 ...anthropic-unsigned-thinking-replay.test.ts | 11 ++++++++
 2 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/packages/ai/src/providers/anthropic.ts b/packages/ai/src/providers/anthropic.ts
index ac75d6798..f96477f4c 100644
--- a/packages/ai/src/providers/anthropic.ts
+++ b/packages/ai/src/providers/anthropic.ts
@@ -2426,27 +2426,19 @@ function isZaiAnthropicEndpoint(model: Model<"anthropic-messages">): boolean {
 	}
 }
 
-function isOfficialAnthropicEndpoint(model: Model<"anthropic-messages">): boolean {
-	const baseUrl = model.baseUrl;
-	if (!baseUrl) return false;
-	try {
-		const hostname = new URL(baseUrl).hostname.toLowerCase();
-		return hostname === "api.anthropic.com";
-	} catch {
-		return false;
-	}
-}
-
 /**
  * Returns true when unsigned `thinking` blocks from prior assistant turns should
  * be replayed as Anthropic-native thinking instead of demoted to text.
  *
- * Official Anthropic enforces signature-based thinking-chain integrity, so
- * unsigned blocks must remain text there. Anthropic-compatible reasoning
- * endpoints commonly emit unsigned thinking blocks while still expecting those
- * blocks back as `type: "thinking"` on continuation; demoting them loses the
- * model's reasoning chain and can destabilize the next tool-call arguments
- * (#2005). Known non-signing hosts are also preserved for compatibility.
+ * Official Anthropic (matched via `isAnthropicApiBaseUrl`, which intentionally
+ * treats a missing baseUrl as official since `resolveAnthropicBaseUrl` routes
+ * it to `https://api.anthropic.com`) enforces signature-based thinking-chain
+ * integrity, so unsigned blocks must remain text there. Anthropic-compatible
+ * reasoning endpoints commonly emit unsigned thinking blocks while still
+ * expecting them back as `type: "thinking"` on continuation; demoting them
+ * loses the model's reasoning chain and can destabilize the next tool-call
+ * arguments (#2005). Known non-signing hosts are also preserved for
+ * compatibility.
  */
 function shouldReplayUnsignedThinking(model: Model<"anthropic-messages">): boolean {
 	if (model.provider === "zai" || model.provider === "deepseek") return true;
@@ -2459,7 +2451,7 @@ function shouldReplayUnsignedThinking(model: Model<"anthropic-messages">): boole
 			// Fall through to the protocol-level reasoning rule below.
 		}
 	}
-	return model.reasoning && !isOfficialAnthropicEndpoint(model);
+	return model.reasoning && !isAnthropicApiBaseUrl(baseUrl);
 }
 
 function buildToolResultBlock(model: Model<"anthropic-messages">, msg: ToolResultMessage): ContentBlockParam {
diff --git a/packages/ai/test/anthropic-unsigned-thinking-replay.test.ts b/packages/ai/test/anthropic-unsigned-thinking-replay.test.ts
index 7e33e859f..9b3f8dcbc 100644
--- a/packages/ai/test/anthropic-unsigned-thinking-replay.test.ts
+++ b/packages/ai/test/anthropic-unsigned-thinking-replay.test.ts
@@ -119,6 +119,17 @@ describe("Anthropic-compatible unsigned thinking replay (#2005)", () => {
 		expect((blocks[0] as WireTextBlock).text).toBe("internal scratch");
 	});
 
+	it("treats a missing baseUrl as official Anthropic (resolveAnthropicBaseUrl default)", () => {
+		// `isAnthropicApiBaseUrl(undefined) === true` because the actual HTTP
+		// dispatch falls back to https://api.anthropic.com. Same-id custom
+		// overrides that only tweak model metadata (no baseUrl override) must
+		// not regress to native-thinking replay against the first-party API.
+		const model = { ...makeModel(), provider: "anthropic", baseUrl: "" };
+		const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("internal scratch")], model);
+		expect(blocks[0]?.type).toBe("text");
+		expect((blocks[0] as WireTextBlock).text).toBe("internal scratch");
+	});
+
 	it("still degrades unsigned thinking to text for non-reasoning unknown endpoints", () => {
 		const model = makeModel({ reasoning: false, baseUrl: "https://plain.example.com/anthropic" });
 		const blocks = assistantWireBlocks([makeUser(), makeAssistantThinking("scratch")], model);

From c933d34398b8005f042aae2f4e6aec457a642e8b Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 19:22:21 +0200
Subject: [PATCH 030/181] =?UTF-8?q?fix(usage):=20antigravity=20/usage=20di?=
 =?UTF-8?q?splay=20=E2=80=94=20dedupe=20by=20tier,=20fix=20account=20count?=
 =?UTF-8?q?,=20add=20projectId=20identity?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Antigravity usage provider now deduplicates model quota entries by tier
  instead of emitting one bar per model (15+ redundant bars for one account).
  The upstream API groups quota by tier — models within the same tier share
  the same quota bucket, so per-model bars were misleading noise.

- Reports now carry credential email and accountId in metadata so the
  /usage display and deduplicator can show meaningful account identities
  instead of 'account 1'.

- formatAggregateAmount no longer uses limits.length as account count.
  Instead counts unique accountId values from limit scopes — a single
  account's N incomplete limits no longer display as 'N accts'.

- Usage report dedup now considers metadata.projectId for Google Cloud
  providers so duplicate credential rows with the same project merge.

- account labels in both TUI and ACP markdown paths now fall back to
  metadata.projectId before the generic 'account N' placeholder.
---
 packages/ai/CHANGELOG.md                      |  6 ++
 packages/ai/src/auth-storage.ts               |  2 +
 packages/ai/src/usage/google-antigravity.ts   | 78 +++++++++++++------
 packages/coding-agent/CHANGELOG.md            |  4 +
 .../modes/controllers/command-controller.ts   | 11 ++-
 .../slash-commands/helpers/usage-report.ts    |  2 +
 6 files changed, 79 insertions(+), 24 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 2f8dea9f7..cbdaf6c5e 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed Antigravity usage provider emitting one bar per model instead of deduplicating by tier — a single account's 15+ model entries now collapse to one bar per tier, matching the shared-quota reality of the upstream API.
+- Fixed Antigravity usage reports missing `email` and `accountId` in metadata, so the `/usage` display and the deduplicator can associate reports with their credentials.
+- Fixed usage-report dedup ignoring `projectId` for Google Cloud providers, preventing duplicate credential entries from being recognized as the same account.
+
 ## [15.9.67] - 2026-06-06
 
 ### Fixed
diff --git a/packages/ai/src/auth-storage.ts b/packages/ai/src/auth-storage.ts
index f03f7b810..35c9a8929 100644
--- a/packages/ai/src/auth-storage.ts
+++ b/packages/ai/src/auth-storage.ts
@@ -2295,6 +2295,8 @@ export class AuthStorage {
 		if (report.provider === "openai-codex" || report.provider === "anthropic") {
 			return identifiers.map(identifier => `${report.provider}:${identifier.toLowerCase()}`);
 		}
+		const projectId = this.#getUsageReportMetadataValue(report, "projectId");
+		if (projectId) identifiers.push(`project:${projectId}`);
 		const accountId = this.#getUsageReportMetadataValue(report, "accountId");
 		if (accountId) identifiers.push(`account:${accountId}`);
 		const account = this.#getUsageReportMetadataValue(report, "account");
diff --git a/packages/ai/src/usage/google-antigravity.ts b/packages/ai/src/usage/google-antigravity.ts
index 26963d7b5..0a5ad1a2f 100644
--- a/packages/ai/src/usage/google-antigravity.ts
+++ b/packages/ai/src/usage/google-antigravity.ts
@@ -148,46 +148,78 @@ async function fetchAntigravityUsage(params: UsageFetchParams, ctx: UsageFetchCo
 	}
 
 	const data = (await response.json()) as AntigravityUsageResponse;
-	const limits: UsageLimit[] = [];
+
+	// The API returns per-model quota entries, but quota is shared across
+	// models within the same tier. Deduplicate by (tier, windowId) so one
+	// account doesn't produce 15 redundant bars.
+	const deduped = new Map<
+		string,
+		{ amount: UsageAmount; window: UsageWindow | undefined; tier: string | undefined }
+	>();
 	let earliestReset: number | undefined;
 
-	for (const [modelId, modelInfo] of Object.entries(data.models ?? {})) {
+	for (const [_modelId, modelInfo] of Object.entries(data.models ?? {})) {
 		const quotaInfos = normalizeQuotaInfos(modelInfo);
 		for (const quotaInfo of quotaInfos) {
+			if (quotaInfo.remainingFraction === undefined) continue;
 			const amount = buildAmount(quotaInfo);
 			const window = parseWindow(quotaInfo);
 			if (window?.resetsAt) {
 				earliestReset = earliestReset ? Math.min(earliestReset, window.resetsAt) : window.resetsAt;
 			}
-			const labelBase = modelInfo.displayName || modelId;
-			const label = quotaInfo.tier ? `${labelBase} (${quotaInfo.tier})` : labelBase;
+			const tier = quotaInfo.tier ?? "default";
 			const windowId = window?.id ?? "default";
-			limits.push({
-				id: `${modelId}:${quotaInfo.tier ?? "default"}:${windowId}`,
-				label,
-				scope: {
-					provider: params.provider,
-					accountId: credential.accountId,
-					projectId: credential.projectId,
-					modelId,
-					tier: quotaInfo.tier,
-					windowId,
-				},
-				window,
-				amount,
-				status: getUsageStatus(amount.remainingFraction),
-			});
+			const key = `${tier}|${windowId}`;
+			const existing = deduped.get(key);
+			if (
+				!existing ||
+				(existing.amount.remainingFraction !== undefined &&
+					amount.remainingFraction !== undefined &&
+					amount.remainingFraction < existing.amount.remainingFraction)
+			) {
+				deduped.set(key, { amount, window, tier: quotaInfo.tier });
+			}
 		}
 	}
 
+	const limits: UsageLimit[] = [];
+	for (const [key, entry] of deduped) {
+		const [tier, windowId] = key.split("|") as [string, string];
+		const label = entry.tier ?? "Usage";
+		limits.push({
+			id: `google-antigravity:${tier}:${windowId}`,
+			label,
+			scope: {
+				provider: params.provider,
+				accountId: credential.accountId,
+				projectId: credential.projectId,
+				tier: entry.tier ?? undefined,
+				windowId,
+			},
+			window: entry.window,
+			amount: entry.amount,
+			status: getUsageStatus(entry.amount.remainingFraction),
+		});
+	}
+
+	limits.sort((a, b) => {
+		const aFraction = a.amount.remainingFraction ?? 1;
+		const bFraction = b.amount.remainingFraction ?? 1;
+		return aFraction - bFraction;
+	});
+
+	const metadata: UsageReport["metadata"] = {
+		endpoint: url,
+		projectId: credential.projectId,
+	};
+	if (credential.email) metadata.email = credential.email;
+	if (credential.accountId) metadata.accountId = credential.accountId;
+
 	const report: UsageReport = {
 		provider: params.provider,
 		fetchedAt: nowMs,
 		limits,
-		metadata: {
-			endpoint: url,
-			projectId: credential.projectId,
-		},
+		metadata,
 		raw: data,
 	};
 
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 33ff5aaaf..a90e895a4 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -3,6 +3,10 @@
 ## [Unreleased]
 
 ## [15.9.69] - 2026-06-06
+### Fixed
+
+- Fixed `/usage` aggregate amount fallback using raw `limits.length` as account count — now counts unique `accountId` values from limit scopes, so N limits from a single account no longer display as "N accts".
+- Fixed `/usage` account labeling falling back to "account N" for providers that use `projectId` as their primary identity (e.g. Google Antigravity, Gemini CLI) — `projectId` from report metadata is now considered before the generic fallback.
 
 ### Added
 
diff --git a/packages/coding-agent/src/modes/controllers/command-controller.ts b/packages/coding-agent/src/modes/controllers/command-controller.ts
index f1f857ecb..8d9388597 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller.ts
@@ -1272,6 +1272,8 @@ function formatAccountLabel(limit: UsageLimit, report: UsageReport, index: numbe
 	if (email) return email;
 	const accountId = (report.metadata?.accountId as string | undefined) ?? limit.scope.accountId;
 	if (accountId) return accountId;
+	const projectId = report.metadata?.projectId as string | undefined;
+	if (projectId) return projectId;
 	return `account ${index + 1}`;
 }
 
@@ -1280,6 +1282,8 @@ function formatUnlimitedReportLabel(report: UsageReport, index: number): string
 	if (email) return email;
 	const accountId = report.metadata?.accountId as string | undefined;
 	if (accountId) return accountId;
+	const projectId = report.metadata?.projectId as string | undefined;
+	if (projectId) return projectId;
 	return `account ${index + 1}`;
 }
 
@@ -1365,7 +1369,12 @@ function formatAggregateAmount(limits: UsageLimit[]): string {
 		return `${formatNumber(remainingPct)}% free`;
 	}
 
-	return `${limits.length} accts`;
+	// Count unique accounts from limit scopes — not limits.length.
+	const uniqueAccountIds = new Set(
+		limits.map(limit => limit.scope.accountId).filter((id): id is string => typeof id === "string" && id.length > 0),
+	);
+	if (uniqueAccountIds.size === 0) return "";
+	return `${uniqueAccountIds.size} ${uniqueAccountIds.size === 1 ? "acct" : "accts"}`;
 }
 
 function resolveResetRange(limits: UsageLimit[], nowMs: number): string | null {
diff --git a/packages/coding-agent/src/slash-commands/helpers/usage-report.ts b/packages/coding-agent/src/slash-commands/helpers/usage-report.ts
index bbef96730..71f184550 100644
--- a/packages/coding-agent/src/slash-commands/helpers/usage-report.ts
+++ b/packages/coding-agent/src/slash-commands/helpers/usage-report.ts
@@ -26,6 +26,8 @@ function formatUsageReportAccount(report: UsageReport, limit: UsageLimit, index:
 	if (typeof email === "string" && email) return email;
 	const accountId = report.metadata?.accountId ?? limit.scope.accountId;
 	if (typeof accountId === "string" && accountId) return accountId;
+	const projectId = report.metadata?.projectId;
+	if (typeof projectId === "string" && projectId) return projectId;
 	return `account ${index + 1}`;
 }
 

From ca24f34044a1a10c991b92927679b635511b0fd8 Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 19:47:28 +0200
Subject: [PATCH 031/181] =?UTF-8?q?fix(usage):=20merge=20antigravity=20ded?=
 =?UTF-8?q?up=20entries=20=E2=80=94=20keep=20bar=20data=20+=20reset=20time?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When models within the same (tier, windowId) group have complementary
data — some carry remainingFraction but no resetTime, others carry
resetTime but no remainingFraction — merge them so the displayed entry
has both a real bar and the 'resets in…' line.

Also lowercases tier names for dedup keys so 'Default' and 'default'
are recognized as the same tier.

Adds projectId to OAuth credential identity extraction and to the
usage-report dedup identifiers so duplicate credential rows (same
Google Cloud project, separate login sessions) are pruned and merged
at both the store and usage-report levels.
---
 packages/ai/src/auth-storage.ts             |  4 +++
 packages/ai/src/usage/google-antigravity.ts | 35 ++++++++++++++++-----
 2 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/packages/ai/src/auth-storage.ts b/packages/ai/src/auth-storage.ts
index 35c9a8929..589b5a3e5 100644
--- a/packages/ai/src/auth-storage.ts
+++ b/packages/ai/src/auth-storage.ts
@@ -3933,6 +3933,8 @@ function resolveProviderCredentialIdentityKey(provider: string, identifiers: str
 	if ((provider === "openai-codex" || provider === "anthropic") && emailIdentifier) return emailIdentifier;
 	const accountIdentifier = identifiers.find(identifier => identifier.startsWith("account:"));
 	if (accountIdentifier) return accountIdentifier;
+	const projectIdentifier = identifiers.find(identifier => identifier.startsWith("project:"));
+	if (projectIdentifier) return projectIdentifier;
 	if (emailIdentifier) return emailIdentifier;
 	return null;
 }
@@ -3969,6 +3971,8 @@ function extractOAuthCredentialIdentifiers(credential: OAuthCredential): string[
 	if (accountId) identifiers.add(`account:${accountId}`);
 	const email = normalizeStoredEmail(credential.email);
 	if (email) identifiers.add(`email:${email}`);
+	const projectId = normalizeStoredAccountId(credential.projectId);
+	if (projectId) identifiers.add(`project:${projectId}`);
 	const accessIdentifiers = extractOAuthTokenIdentifiers(credential.access) ?? [];
 	for (const identifier of accessIdentifiers) {
 		identifiers.add(identifier);
diff --git a/packages/ai/src/usage/google-antigravity.ts b/packages/ai/src/usage/google-antigravity.ts
index 0a5ad1a2f..42bce9164 100644
--- a/packages/ai/src/usage/google-antigravity.ts
+++ b/packages/ai/src/usage/google-antigravity.ts
@@ -161,24 +161,43 @@ async function fetchAntigravityUsage(params: UsageFetchParams, ctx: UsageFetchCo
 	for (const [_modelId, modelInfo] of Object.entries(data.models ?? {})) {
 		const quotaInfos = normalizeQuotaInfos(modelInfo);
 		for (const quotaInfo of quotaInfos) {
-			if (quotaInfo.remainingFraction === undefined) continue;
 			const amount = buildAmount(quotaInfo);
 			const window = parseWindow(quotaInfo);
 			if (window?.resetsAt) {
 				earliestReset = earliestReset ? Math.min(earliestReset, window.resetsAt) : window.resetsAt;
 			}
-			const tier = quotaInfo.tier ?? "default";
+			const tier = (quotaInfo.tier ?? "default").toLowerCase();
 			const windowId = window?.id ?? "default";
 			const key = `${tier}|${windowId}`;
 			const existing = deduped.get(key);
-			if (
-				!existing ||
-				(existing.amount.remainingFraction !== undefined &&
-					amount.remainingFraction !== undefined &&
-					amount.remainingFraction < existing.amount.remainingFraction)
-			) {
+			if (!existing) {
 				deduped.set(key, { amount, window, tier: quotaInfo.tier });
+				continue;
 			}
+			// Merge: keep the entry with fraction data for the bar, but
+			// also keep any window with a reset time so "resets in…" survives.
+			const eFrac = existing.amount.remainingFraction;
+			const cFrac = amount.remainingFraction;
+			const eHasFrac = eFrac !== undefined;
+			const cHasFrac = cFrac !== undefined;
+
+			let bestAmount = existing.amount;
+			let bestWindow = existing.window?.resetsAt ? existing.window : (window ?? existing.window);
+			let bestTier = existing.tier ?? quotaInfo.tier;
+
+			if (!eHasFrac && cHasFrac) {
+				bestAmount = amount;
+				bestTier = quotaInfo.tier ?? existing.tier;
+			} else if (eHasFrac && cHasFrac && cFrac! < eFrac!) {
+				bestAmount = amount;
+				bestTier = quotaInfo.tier ?? existing.tier;
+			}
+			// Always merge in window with reset time if the current
+			// best doesn't have one.
+			if (!bestWindow?.resetsAt && window?.resetsAt) {
+				bestWindow = window;
+			}
+			deduped.set(key, { amount: bestAmount, window: bestWindow, tier: bestTier });
 		}
 	}
 

From 15c0dff28e973326beb7816acf5bd6ce0a046dc6 Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 19:55:26 +0200
Subject: [PATCH 032/181] fix(usage): fall back to limit.scope.projectId when
 metadata.projectId is absent

Gemini CLI provider stores projectId on limit.scope but not in report
metadata, so the metadata-only projectId fallback added earlier missed
that case. Now all three lookup sites (dedup identifiers, TUI account
label, ACP account label) also check limit.scope.projectId.
---
 packages/ai/src/auth-storage.ts                   | 15 +++++++++++++--
 .../src/modes/controllers/command-controller.ts   |  2 +-
 .../src/slash-commands/helpers/usage-report.ts    |  2 +-
 3 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/packages/ai/src/auth-storage.ts b/packages/ai/src/auth-storage.ts
index 589b5a3e5..136f6ceae 100644
--- a/packages/ai/src/auth-storage.ts
+++ b/packages/ai/src/auth-storage.ts
@@ -2288,6 +2288,16 @@ export class AuthStorage {
 		return undefined;
 	}
 
+	#getUsageReportScopeProjectId(report: UsageReport): string | undefined {
+		const ids = new Set<string>();
+		for (const limit of report.limits) {
+			const projectId = limit.scope.projectId?.trim();
+			if (projectId) ids.add(projectId);
+		}
+		if (ids.size === 1) return [...ids][0];
+		return undefined;
+	}
+
 	#getUsageReportIdentifiers(report: UsageReport): string[] {
 		const identifiers: string[] = [];
 		const email = this.#getUsageReportMetadataValue(report, "email");
@@ -2295,9 +2305,10 @@ export class AuthStorage {
 		if (report.provider === "openai-codex" || report.provider === "anthropic") {
 			return identifiers.map(identifier => `${report.provider}:${identifier.toLowerCase()}`);
 		}
-		const projectId = this.#getUsageReportMetadataValue(report, "projectId");
-		if (projectId) identifiers.push(`project:${projectId}`);
+		const projectId =
+			this.#getUsageReportMetadataValue(report, "projectId") ?? this.#getUsageReportScopeProjectId(report);
 		const accountId = this.#getUsageReportMetadataValue(report, "accountId");
+		if (projectId) identifiers.push(`project:${projectId}`);
 		if (accountId) identifiers.push(`account:${accountId}`);
 		const account = this.#getUsageReportMetadataValue(report, "account");
 		if (account) identifiers.push(`account:${account}`);
diff --git a/packages/coding-agent/src/modes/controllers/command-controller.ts b/packages/coding-agent/src/modes/controllers/command-controller.ts
index 8d9388597..759e99dfa 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller.ts
@@ -1272,7 +1272,7 @@ function formatAccountLabel(limit: UsageLimit, report: UsageReport, index: numbe
 	if (email) return email;
 	const accountId = (report.metadata?.accountId as string | undefined) ?? limit.scope.accountId;
 	if (accountId) return accountId;
-	const projectId = report.metadata?.projectId as string | undefined;
+	const projectId = (report.metadata?.projectId as string | undefined) ?? limit.scope.projectId;
 	if (projectId) return projectId;
 	return `account ${index + 1}`;
 }
diff --git a/packages/coding-agent/src/slash-commands/helpers/usage-report.ts b/packages/coding-agent/src/slash-commands/helpers/usage-report.ts
index 71f184550..8b3610f9d 100644
--- a/packages/coding-agent/src/slash-commands/helpers/usage-report.ts
+++ b/packages/coding-agent/src/slash-commands/helpers/usage-report.ts
@@ -26,7 +26,7 @@ function formatUsageReportAccount(report: UsageReport, limit: UsageLimit, index:
 	if (typeof email === "string" && email) return email;
 	const accountId = report.metadata?.accountId ?? limit.scope.accountId;
 	if (typeof accountId === "string" && accountId) return accountId;
-	const projectId = report.metadata?.projectId;
+	const projectId = report.metadata?.projectId ?? limit.scope.projectId;
 	if (typeof projectId === "string" && projectId) return projectId;
 	return `account ${index + 1}`;
 }

From 794a64aae13c350b12651280ef1728bf3de0836b Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 20:01:17 +0200
Subject: [PATCH 033/181] =?UTF-8?q?fix(usage):=20address=20review=20?=
 =?UTF-8?q?=E2=80=94=20order=20email=20before=20project,=20add=20tests,=20?=
 =?UTF-8?q?nits?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- BLOCKING: reorder resolveProviderCredentialIdentityKey so email
  identity takes priority over project — two users with different
  emails on the same GCP project no longer get merged/hard-deleted.

- Added #getUsageReportScopeProjectId helper so Gemini CLI reports
  (which set projectId on limit.scope but not metadata) still get
  dedup coverage. Both metadata and scope projectId paths checked.

- formatAggregateAmount now falls back to limits.length when no
  scope.accountId values are present, preserving pre-existing
  behaviour for providers that don't set accountId on limits.

- Added 9 contract tests for the antigravity usage merge logic:
  tier dedup, worst-fraction-wins, mixed-case collapsing,
  reset-time-from-other-entry, windowId separation, metadata,
  sort order, and null-on-no-project.

- Nits: label='Usage' (so formatLimitTitle renders 'Usage (Default)'
  not bare 'Default'), id uses params.provider instead of hardcoded
  string, tier field drops redundant ?? undefined.
---
 packages/ai/src/auth-storage.ts               |   2 +-
 packages/ai/src/usage/google-antigravity.ts   |   6 +-
 .../ai/test/google-antigravity-usage.test.ts  | 189 ++++++++++++++++++
 .../modes/controllers/command-controller.ts   |   6 +-
 4 files changed, 197 insertions(+), 6 deletions(-)
 create mode 100644 packages/ai/test/google-antigravity-usage.test.ts

diff --git a/packages/ai/src/auth-storage.ts b/packages/ai/src/auth-storage.ts
index 136f6ceae..86b627da7 100644
--- a/packages/ai/src/auth-storage.ts
+++ b/packages/ai/src/auth-storage.ts
@@ -3944,9 +3944,9 @@ function resolveProviderCredentialIdentityKey(provider: string, identifiers: str
 	if ((provider === "openai-codex" || provider === "anthropic") && emailIdentifier) return emailIdentifier;
 	const accountIdentifier = identifiers.find(identifier => identifier.startsWith("account:"));
 	if (accountIdentifier) return accountIdentifier;
+	if (emailIdentifier) return emailIdentifier;
 	const projectIdentifier = identifiers.find(identifier => identifier.startsWith("project:"));
 	if (projectIdentifier) return projectIdentifier;
-	if (emailIdentifier) return emailIdentifier;
 	return null;
 }
 
diff --git a/packages/ai/src/usage/google-antigravity.ts b/packages/ai/src/usage/google-antigravity.ts
index 42bce9164..ef3b59a65 100644
--- a/packages/ai/src/usage/google-antigravity.ts
+++ b/packages/ai/src/usage/google-antigravity.ts
@@ -204,15 +204,15 @@ async function fetchAntigravityUsage(params: UsageFetchParams, ctx: UsageFetchCo
 	const limits: UsageLimit[] = [];
 	for (const [key, entry] of deduped) {
 		const [tier, windowId] = key.split("|") as [string, string];
-		const label = entry.tier ?? "Usage";
+		const label = "Usage";
 		limits.push({
-			id: `google-antigravity:${tier}:${windowId}`,
+			id: `${params.provider}:${tier}:${windowId}`,
 			label,
 			scope: {
 				provider: params.provider,
 				accountId: credential.accountId,
 				projectId: credential.projectId,
-				tier: entry.tier ?? undefined,
+				tier: entry.tier,
 				windowId,
 			},
 			window: entry.window,
diff --git a/packages/ai/test/google-antigravity-usage.test.ts b/packages/ai/test/google-antigravity-usage.test.ts
new file mode 100644
index 000000000..e26a09449
--- /dev/null
+++ b/packages/ai/test/google-antigravity-usage.test.ts
@@ -0,0 +1,189 @@
+/**
+ * Antigravity usage provider contract tests. The merge logic
+ * deduplicates per-model quota entries by (tier, windowId),
+ * preserves reset times when bar data and window data come from
+ * different model entries, and handles mixed-case tier names.
+ */
+import { describe, expect, it } from "bun:test";
+import { antigravityUsageProvider } from "../src/usage/google-antigravity";
+import type { UsageFetchParams, UsageFetchContext } from "../src/usage";
+
+const accessTokenFixture = (() => {
+	const header = Buffer.from(JSON.stringify({ alg: "none", typ: "JWT" })).toString("base64url");
+	const body = Buffer.from(
+		JSON.stringify({ sub: "user-fixture" }),
+	).toString("base64url");
+	return `${header}.${body}.sig`;
+})();
+
+function makeCredential(overrides?: Partial<UsageFetchParams["credential"]>) {
+	return {
+		type: "oauth" as const,
+		accessToken: accessTokenFixture,
+		refresh: "refresh-fixture",
+		expiresAt: Date.now() + 3600_000,
+		projectId: "test-project",
+		email: "test@example.com",
+		accountId: "acct-1",
+		...overrides,
+	} satisfies UsageFetchParams["credential"];
+}
+
+function fakeFetch(json: unknown): typeof fetch {
+	const fn = async () =>
+		new Response(JSON.stringify(json), {
+			status: 200,
+			headers: { "content-type": "application/json" },
+		});
+	return fn as unknown as typeof fetch;
+}
+
+function makeCtx(fetchImpl?: typeof fetch): UsageFetchContext {
+	return { fetch: fetchImpl ?? fakeFetch({}) };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────
+
+function makeApiModel(
+	displayName: string,
+	quota: { remainingFraction?: number; resetTime?: string; tier?: string; windowId?: string },
+) {
+	return {
+		displayName,
+		quotaInfo: {
+			remainingFraction: quota.remainingFraction,
+			resetTime: quota.resetTime,
+			tier: quota.tier,
+			windowId: quota.windowId,
+		},
+	};
+}
+
+// ── tests ────────────────────────────────────────────────────────────
+
+describe("antigravity usage provider", () => {
+	it("merges two models with same tier into one limit", async () => {
+		const payload = {
+			models: {
+				modelA: makeApiModel("Model A", { remainingFraction: 0.3, tier: "premium" }),
+				modelB: makeApiModel("Model B", { remainingFraction: 0.5, tier: "premium" }),
+			},
+		};
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential(), signal: undefined },
+			makeCtx(fakeFetch(payload)),
+		);
+		expect(report).not.toBeNull();
+		expect(report!.limits.length).toBe(1);
+	});
+
+	it("keeps the worst remainingFraction when merging same tier", async () => {
+		const payload = {
+			models: {
+				modelA: makeApiModel("Model A", { remainingFraction: 0.1, tier: "premium" }),
+				modelB: makeApiModel("Model B", { remainingFraction: 0.8, tier: "premium" }),
+			},
+		};
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential(), signal: undefined },
+			makeCtx(fakeFetch(payload)),
+		);
+		expect(report!.limits.length).toBe(1);
+		expect(report!.limits[0]!.amount.remainingFraction).toBe(0.1);
+	});
+
+	it("merges mixed-case tier names under lowercased key", async () => {
+		const payload = {
+			models: {
+				modelA: makeApiModel("Model A", { remainingFraction: 0.3, tier: "Default" }),
+				modelB: makeApiModel("Model B", { remainingFraction: 0.6, tier: "default" }),
+			},
+		};
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential(), signal: undefined },
+			makeCtx(fakeFetch(payload)),
+		);
+		expect(report!.limits.length).toBe(1);
+	});
+
+	it("preserves reset time from an entry even when bar data comes from another", async () => {
+		const now = Date.now();
+		const resetTime = new Date(now + 4 * 3600_000).toISOString();
+		const payload = {
+			models: {
+				modelA: makeApiModel("Model A", { remainingFraction: 0.3, tier: "default" }),
+				modelB: makeApiModel("Model B", { remainingFraction: undefined, tier: "default", resetTime }),
+			},
+		};
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential(), signal: undefined },
+			makeCtx(fakeFetch(payload)),
+		);
+		expect(report!.limits.length).toBe(1);
+		expect(report!.limits[0]!.amount.remainingFraction).toBe(0.3);
+		expect(report!.limits[0]!.window).toBeDefined();
+		expect(report!.limits[0]!.window!.resetsAt).toBeGreaterThan(now);
+	});
+
+	it("separates models with different windowIds in the same tier", async () => {
+		const now = Date.now();
+		const t1 = new Date(now + 5 * 3600_000).toISOString();
+		const t2 = new Date(now + 24 * 3600_000).toISOString();
+		const payload = {
+			models: {
+				modelA: makeApiModel("Model A", { remainingFraction: 0.3, tier: "premium", windowId: "5h", resetTime: t1 }),
+				modelB: makeApiModel("Model B", { remainingFraction: 0.7, tier: "premium", windowId: "daily", resetTime: t2 }),
+			},
+		};
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential(), signal: undefined },
+			makeCtx(fakeFetch(payload)),
+		);
+		expect(report!.limits.length).toBe(2);
+	});
+
+	it("includes email and projectId in report metadata", async () => {
+		const payload = { models: { m: makeApiModel("M", { remainingFraction: 1 }) } };
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential({ email: "user@example.com", projectId: "proj-1" }), signal: undefined },
+			makeCtx(fakeFetch(payload)),
+		);
+		expect(report!.metadata.email).toBe("user@example.com");
+		expect(report!.metadata.projectId).toBe("proj-1");
+	});
+
+	it("does not include email when credential has none", async () => {
+		const payload = { models: { m: makeApiModel("M", { remainingFraction: 1 }) } };
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential({ email: undefined }), signal: undefined },
+			makeCtx(fakeFetch(payload)),
+		);
+		expect(report!.metadata.email).toBeUndefined();
+	});
+
+	it("sorts limits by remainingFraction ascending (worst first)", async () => {
+		const payload = {
+			models: {
+				modelA: makeApiModel("Model A", { remainingFraction: 0.9, tier: "high" }),
+				modelB: makeApiModel("Model B", { remainingFraction: 0.2, tier: "low" }),
+				modelC: makeApiModel("Model C", { remainingFraction: 0.5, tier: "mid" }),
+			},
+		};
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential(), signal: undefined },
+			makeCtx(fakeFetch(payload)),
+		);
+		expect(report!.limits.length).toBe(3);
+		expect(report!.limits[0]!.amount.remainingFraction).toBe(0.2);
+		expect(report!.limits[1]!.amount.remainingFraction).toBe(0.5);
+		expect(report!.limits[2]!.amount.remainingFraction).toBe(0.9);
+	});
+
+	it("returns null when credential has no projectId", async () => {
+		const report = await antigravityUsageProvider.fetchUsage!(
+			{ provider: "google-antigravity", credential: makeCredential({ projectId: undefined }), signal: undefined },
+			makeCtx(),
+		);
+		expect(report).toBeNull();
+	});
+});
diff --git a/packages/coding-agent/src/modes/controllers/command-controller.ts b/packages/coding-agent/src/modes/controllers/command-controller.ts
index 759e99dfa..a64a254f1 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller.ts
@@ -1373,8 +1373,10 @@ function formatAggregateAmount(limits: UsageLimit[]): string {
 	const uniqueAccountIds = new Set(
 		limits.map(limit => limit.scope.accountId).filter((id): id is string => typeof id === "string" && id.length > 0),
 	);
-	if (uniqueAccountIds.size === 0) return "";
-	return `${uniqueAccountIds.size} ${uniqueAccountIds.size === 1 ? "acct" : "accts"}`;
+	if (uniqueAccountIds.size > 0) return `${uniqueAccountIds.size} ${uniqueAccountIds.size === 1 ? "acct" : "accts"}`;
+	// No account IDs available — keep the pre-existing fallback so providers
+	// that don't populate scope.accountId still show a summary.
+	return `${limits.length} accts`;
 }
 
 function resolveResetRange(limits: UsageLimit[], nowMs: number): string | null {

From 60f79199ca99af728b4673afd4f3d1e9aa10cc55 Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 20:05:47 +0200
Subject: [PATCH 034/181] fix(usage): only add project: dedup identifier when
 no email; preserve raw windowId

- #getUsageReportIdentifiers now only pushes project: when no email was
  found, preventing two users with different emails on the same GCP
  project from being merged at the usage-report level.

- Antigravity dedup key now uses quotaInfo.windowId directly before
  falling back to parseWindow's id. When resetTime is absent but
  windowId is set, separate windows no longer collapse to 'default'.
---
 packages/ai/src/auth-storage.ts             | 4 +++-
 packages/ai/src/usage/google-antigravity.ts | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/ai/src/auth-storage.ts b/packages/ai/src/auth-storage.ts
index 86b627da7..b1153bed0 100644
--- a/packages/ai/src/auth-storage.ts
+++ b/packages/ai/src/auth-storage.ts
@@ -2307,8 +2307,10 @@ export class AuthStorage {
 		}
 		const projectId =
 			this.#getUsageReportMetadataValue(report, "projectId") ?? this.#getUsageReportScopeProjectId(report);
+		// Only add project as a fallback when no email is available — two users
+		// with different emails on the same GCP project must not merge.
+		if (projectId && !email) identifiers.push(`project:${projectId}`);
 		const accountId = this.#getUsageReportMetadataValue(report, "accountId");
-		if (projectId) identifiers.push(`project:${projectId}`);
 		if (accountId) identifiers.push(`account:${accountId}`);
 		const account = this.#getUsageReportMetadataValue(report, "account");
 		if (account) identifiers.push(`account:${account}`);
diff --git a/packages/ai/src/usage/google-antigravity.ts b/packages/ai/src/usage/google-antigravity.ts
index ef3b59a65..54e2e11cf 100644
--- a/packages/ai/src/usage/google-antigravity.ts
+++ b/packages/ai/src/usage/google-antigravity.ts
@@ -167,7 +167,9 @@ async function fetchAntigravityUsage(params: UsageFetchParams, ctx: UsageFetchCo
 				earliestReset = earliestReset ? Math.min(earliestReset, window.resetsAt) : window.resetsAt;
 			}
 			const tier = (quotaInfo.tier ?? "default").toLowerCase();
-			const windowId = window?.id ?? "default";
+			// Use quotaInfo.windowId even when parseWindow returns undefined
+			// (no resetTime) — separate windows must not collapse to "default".
+			const windowId = quotaInfo.windowId ?? window?.id ?? "default";
 			const key = `${tier}|${windowId}`;
 			const existing = deduped.get(key);
 			if (!existing) {

From f3210ab862d974cd63317ac14bcdcf35dd5e38fb Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 18:47:11 +0200
Subject: [PATCH 035/181] fix(ai): strip type-specific keys when CCA mixed-type
 collapse picks non-matching type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When collapseMixedTypeCombinerVariants collapses an anyOf with mixed
types (e.g. string | array), it previously picked the first non-null
type but indiscriminately copied ALL mergedVariantFields — including
type-specific keys like "items" that only belong to array. This
produced schemas like {type: "string", items: {...}} which Google
Cloud Code Assist API rejects with 400.

Fix: filter mergedVariantFields against the chosen types allowed keys
(CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS) before copying, so array-only
keys are dropped when the winner is string (and vice versa).

Fixes 400 error on github tools "pr" parameter (anyOf string/array).
---
 packages/ai/src/utils/schema/normalize.ts     |  8 ++++++++
 packages/ai/test/schema-normalization.test.ts | 15 +++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/packages/ai/src/utils/schema/normalize.ts b/packages/ai/src/utils/schema/normalize.ts
index 1b21afd67..e10a46270 100644
--- a/packages/ai/src/utils/schema/normalize.ts
+++ b/packages/ai/src/utils/schema/normalize.ts
@@ -505,8 +505,16 @@ function collapseMixedTypeCombinerVariants(schema: JsonObject, combiner: "anyOf"
 	const nextSchema = copySchemaWithout(schema, combiner);
 	const nonNullTypes = variantTypes.filter(t => t !== "null");
 	nextSchema.type = nonNullTypes[0] ?? variantTypes[0];
+	const chosenTypeAllowedKeys = CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS[nextSchema.type as string] ?? {};
 	for (const key in mergedVariantFields) {
 		if (!Object.hasOwn(mergedVariantFields, key)) continue;
+		// Drop type-specific keys that don't belong to the chosen type
+		if (
+			!Object.hasOwn(chosenTypeAllowedKeys, key) &&
+			!Object.hasOwn(CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS, key)
+		) {
+			continue;
+		}
 		const value = mergedVariantFields[key];
 		const existingValue = nextSchema[key];
 		if (existingValue !== undefined && !areJsonValuesEqual(existingValue, value)) {
diff --git a/packages/ai/test/schema-normalization.test.ts b/packages/ai/test/schema-normalization.test.ts
index 1f6ba7688..c7e55d9d1 100644
--- a/packages/ai/test/schema-normalization.test.ts
+++ b/packages/ai/test/schema-normalization.test.ts
@@ -952,6 +952,21 @@ describe("normalizeSchemaForCCA", () => {
 			properties: {},
 		});
 	});
+
+	it("strips array-only keys when mixed-type collapse picks a non-array type", () => {
+		// Regression: anyOf [{type:"string"}, {type:"array", items:{type:"string"}}]
+		// collapsed to {type:"string", items:{type:"string"}} which is invalid.
+		// The fix filters mergedVariantFields against the chosen type's allowed keys.
+		const normalized = normalizeSchemaForCCA({
+			anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+			description: "pr number, url, or branch",
+		});
+
+		expect(normalized).toEqual({
+			type: "string",
+			description: "pr number, url, or branch",
+		});
+	});
 });
 
 // ---------------------------------------------------------------------------

From 2623bd75a279e08018925a511dbdf722b9b6017e Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 18:53:52 +0200
Subject: [PATCH 036/181] test(ai): add stripResidualCombiners regression for
 mixed-type string|array collapse

---
 packages/ai/test/schema-normalization.test.ts | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/ai/test/schema-normalization.test.ts b/packages/ai/test/schema-normalization.test.ts
index c7e55d9d1..b2c23fbc4 100644
--- a/packages/ai/test/schema-normalization.test.ts
+++ b/packages/ai/test/schema-normalization.test.ts
@@ -728,6 +728,18 @@ describe("stripResidualCombiners", () => {
 		expect(normalized.anyOf).toBeUndefined();
 		expect(normalized.oneOf).toBeUndefined();
 	});
+
+	it("drops array-only keys when mixed-type collapse picks string from anyOf fixpoint", () => {
+		const stripped = stripResidualCombiners({
+			anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+			description: "pr number, url, or branch",
+		}) as Record<string, unknown>;
+
+		expect(stripped.type).toBe("string");
+		expect(stripped.items).toBeUndefined();
+		expect(stripped.anyOf).toBeUndefined();
+		expect(stripped.description).toBe("pr number, url, or branch");
+	});
 });
 
 // ---------------------------------------------------------------------------

From 807df56ba752e347678ac002ea7f78996c7a66be Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 19:00:32 +0200
Subject: [PATCH 037/181] docs(ai): add unreleased changelog entry for CCA
 mixed-type combiner collapse fix

---
 packages/ai/CHANGELOG.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 2f8dea9f7..dd8e58bbc 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed Cloud Code Assist (Antigravity / Gemini CLI) rejecting the `github` tool with HTTP 400 when the `pr` parameter schema contained `anyOf: [string, array]`. The CCA mixed-type combiner collapse picked the first non-null type (`string`) but indiscriminately copied type-specific keys from variant branches — `items` from the array variant leaked onto the string-typed result, producing `{type: "string", items: {...}}` which Google's API rejects as invalid. The collapse now filters merged variant fields against the winning type's allowed key set. ([#TBD](https://github.com/can1357/oh-my-pi/pull/TBD))
 ## [15.9.67] - 2026-06-06
 
 ### Fixed

From dee4db16025a07f5b2f5db9406d371b2d84f8710 Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 19:02:49 +0200
Subject: [PATCH 038/181] chore(ai): update changelog with PR number

---
 packages/ai/CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index dd8e58bbc..01a4ab507 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Fixed
 
-- Fixed Cloud Code Assist (Antigravity / Gemini CLI) rejecting the `github` tool with HTTP 400 when the `pr` parameter schema contained `anyOf: [string, array]`. The CCA mixed-type combiner collapse picked the first non-null type (`string`) but indiscriminately copied type-specific keys from variant branches — `items` from the array variant leaked onto the string-typed result, producing `{type: "string", items: {...}}` which Google's API rejects as invalid. The collapse now filters merged variant fields against the winning type's allowed key set. ([#TBD](https://github.com/can1357/oh-my-pi/pull/TBD))
+- Fixed Cloud Code Assist (Antigravity / Gemini CLI) rejecting the `github` tool with HTTP 400 when the `pr` parameter schema contained `anyOf: [string, array]`. The CCA mixed-type combiner collapse picked the first non-null type (`string`) but indiscriminately copied type-specific keys from variant branches — `items` from the array variant leaked onto the string-typed result, producing `{type: "string", items: {...}}` which Google's API rejects as invalid. The collapse now filters merged variant fields against the winning type's allowed key set. ([#2002](https://github.com/can1357/oh-my-pi/pull/2002))
 ## [15.9.67] - 2026-06-06
 
 ### Fixed

From 7c8fb4d8f6875900e46b0a3cd275806e24f6cd45 Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 19:08:07 +0200
Subject: [PATCH 039/181] fix(ai): also strip sibling type-specific keys during
 CCA mixed-type collapse

Address review feedback:
- Replace `as string` assertion with typed `chosenType` local
- Strip sibling keys from nextSchema that were copied via
  copySchemaWithout but belong to a type other than the chosen one
  (e.g. sibling `items` on a now-string-typed schema)
- Export ALL_CCA_TYPE_SPECIFIC_KEYS from fields.ts for sibling filtering
- Add regression test for the sibling-key edge case
---
 packages/ai/src/utils/schema/fields.ts        | 16 ++++++++++++++
 packages/ai/src/utils/schema/normalize.ts     | 22 ++++++++++++++++---
 packages/ai/test/schema-normalization.test.ts | 15 +++++++++++++
 3 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/packages/ai/src/utils/schema/fields.ts b/packages/ai/src/utils/schema/fields.ts
index 41e9aacf1..b25006248 100644
--- a/packages/ai/src/utils/schema/fields.ts
+++ b/packages/ai/src/utils/schema/fields.ts
@@ -154,6 +154,22 @@ export const CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS: Record<string, Record<string,
 	null: {},
 };
 
+/**
+ * Flat set of every type-specific key across all CCA types.
+ * Used to identify sibling keys that need filtering during mixed-type collapse.
+ */
+export const ALL_CCA_TYPE_SPECIFIC_KEYS: Record<string, true> = buildAllCcaTypeSpecificKeys();
+
+function buildAllCcaTypeSpecificKeys(): Record<string, true> {
+	const all: Record<string, true> = {};
+	for (const typeKeys of Object.values(CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS)) {
+		for (const key in typeKeys) {
+			all[key] = true;
+		}
+	}
+	return all;
+}
+
 /**
  * Cloud Code Assist shared schema keys allowed on any type.
  * Used alongside CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS for CCA combiner collapsing.
diff --git a/packages/ai/src/utils/schema/normalize.ts b/packages/ai/src/utils/schema/normalize.ts
index e10a46270..0d2961f26 100644
--- a/packages/ai/src/utils/schema/normalize.ts
+++ b/packages/ai/src/utils/schema/normalize.ts
@@ -11,6 +11,7 @@ import { dereferenceJsonSchema } from "./dereference";
 import { upgradeJsonSchemaTo202012 } from "./draft";
 import { areJsonValuesEqual, mergePropertySchemas } from "./equality";
 import {
+	ALL_CCA_TYPE_SPECIFIC_KEYS,
 	CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS,
 	CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS,
 	COMBINATOR_KEYS,
@@ -501,11 +502,26 @@ function collapseMixedTypeCombinerVariants(schema: JsonObject, combiner: "anyOf"
 	if (variantTypes.length < 2 || variantTypes.every(type => type === "object")) {
 		return schema;
 	}
-
 	const nextSchema = copySchemaWithout(schema, combiner);
 	const nonNullTypes = variantTypes.filter(t => t !== "null");
-	nextSchema.type = nonNullTypes[0] ?? variantTypes[0];
-	const chosenTypeAllowedKeys = CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS[nextSchema.type as string] ?? {};
+	const chosenType: string = nonNullTypes[0] ?? variantTypes[0];
+	nextSchema.type = chosenType;
+	const chosenTypeAllowedKeys = CLOUD_CODE_ASSIST_TYPE_SPECIFIC_KEYS[chosenType] ?? {};
+
+	// Strip sibling keys that were copied from the parent and belong to a
+	// different type (e.g. `items` sibling on a now-string-typed schema).
+	for (const key in nextSchema) {
+		if (!Object.hasOwn(nextSchema, key)) continue;
+		if (key === "type") continue;
+		if (
+			Object.hasOwn(ALL_CCA_TYPE_SPECIFIC_KEYS, key) &&
+			!Object.hasOwn(chosenTypeAllowedKeys, key) &&
+			!Object.hasOwn(CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS, key)
+		) {
+			delete nextSchema[key];
+		}
+	}
+
 	for (const key in mergedVariantFields) {
 		if (!Object.hasOwn(mergedVariantFields, key)) continue;
 		// Drop type-specific keys that don't belong to the chosen type
diff --git a/packages/ai/test/schema-normalization.test.ts b/packages/ai/test/schema-normalization.test.ts
index b2c23fbc4..22efcb2cd 100644
--- a/packages/ai/test/schema-normalization.test.ts
+++ b/packages/ai/test/schema-normalization.test.ts
@@ -979,6 +979,21 @@ describe("normalizeSchemaForCCA", () => {
 			description: "pr number, url, or branch",
 		});
 	});
+
+	it("strips sibling type-specific keys copied from parent when mixed-type collapse picks opposing type", () => {
+		// Edge case: parent has a sibling `items` outside the anyOf,
+		// and the chosen type is string. The sibling must be stripped.
+		const normalized = normalizeSchemaForCCA({
+			anyOf: [{ type: "string" }, { type: "array", items: { type: "number" } }],
+			items: { type: "string" },
+			description: "pr number, url, or branch",
+		});
+
+		expect(normalized).toEqual({
+			type: "string",
+			description: "pr number, url, or branch",
+		});
+	});
 });
 
 // ---------------------------------------------------------------------------

From f8ef2cf8e45899f28fc6475a30a10752786a3f11 Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 20:42:06 +0200
Subject: [PATCH 040/181] fix: format CCA schema normalization

---
 packages/ai/src/utils/schema/normalize.ts | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/packages/ai/src/utils/schema/normalize.ts b/packages/ai/src/utils/schema/normalize.ts
index 0d2961f26..ac50eccb7 100644
--- a/packages/ai/src/utils/schema/normalize.ts
+++ b/packages/ai/src/utils/schema/normalize.ts
@@ -525,10 +525,7 @@ function collapseMixedTypeCombinerVariants(schema: JsonObject, combiner: "anyOf"
 	for (const key in mergedVariantFields) {
 		if (!Object.hasOwn(mergedVariantFields, key)) continue;
 		// Drop type-specific keys that don't belong to the chosen type
-		if (
-			!Object.hasOwn(chosenTypeAllowedKeys, key) &&
-			!Object.hasOwn(CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS, key)
-		) {
+		if (!Object.hasOwn(chosenTypeAllowedKeys, key) && !Object.hasOwn(CLOUD_CODE_ASSIST_SHARED_SCHEMA_KEYS, key)) {
 			continue;
 		}
 		const value = mergedVariantFields[key];

From f854596f83c68768bd477e2769cdd52d3f597438 Mon Sep 17 00:00:00 2001
From: basedcorp99 <basedcorp99@gmail.com>
Date: Sat, 6 Jun 2026 20:42:03 +0200
Subject: [PATCH 041/181] fix: format antigravity usage tests

---
 .../ai/test/google-antigravity-usage.test.ts  | 27 ++++++++++++-------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/packages/ai/test/google-antigravity-usage.test.ts b/packages/ai/test/google-antigravity-usage.test.ts
index e26a09449..4fdec1ae0 100644
--- a/packages/ai/test/google-antigravity-usage.test.ts
+++ b/packages/ai/test/google-antigravity-usage.test.ts
@@ -5,14 +5,12 @@
  * different model entries, and handles mixed-case tier names.
  */
 import { describe, expect, it } from "bun:test";
+import type { UsageFetchContext, UsageFetchParams } from "../src/usage";
 import { antigravityUsageProvider } from "../src/usage/google-antigravity";
-import type { UsageFetchParams, UsageFetchContext } from "../src/usage";
 
 const accessTokenFixture = (() => {
 	const header = Buffer.from(JSON.stringify({ alg: "none", typ: "JWT" })).toString("base64url");
-	const body = Buffer.from(
-		JSON.stringify({ sub: "user-fixture" }),
-	).toString("base64url");
+	const body = Buffer.from(JSON.stringify({ sub: "user-fixture" })).toString("base64url");
 	return `${header}.${body}.sig`;
 })();
 
@@ -20,7 +18,7 @@ function makeCredential(overrides?: Partial<UsageFetchParams["credential"]>) {
 	return {
 		type: "oauth" as const,
 		accessToken: accessTokenFixture,
-		refresh: "refresh-fixture",
+		refreshToken: "refresh-fixture",
 		expiresAt: Date.now() + 3600_000,
 		projectId: "test-project",
 		email: "test@example.com",
@@ -132,7 +130,12 @@ describe("antigravity usage provider", () => {
 		const payload = {
 			models: {
 				modelA: makeApiModel("Model A", { remainingFraction: 0.3, tier: "premium", windowId: "5h", resetTime: t1 }),
-				modelB: makeApiModel("Model B", { remainingFraction: 0.7, tier: "premium", windowId: "daily", resetTime: t2 }),
+				modelB: makeApiModel("Model B", {
+					remainingFraction: 0.7,
+					tier: "premium",
+					windowId: "daily",
+					resetTime: t2,
+				}),
 			},
 		};
 		const report = await antigravityUsageProvider.fetchUsage!(
@@ -145,11 +148,15 @@ describe("antigravity usage provider", () => {
 	it("includes email and projectId in report metadata", async () => {
 		const payload = { models: { m: makeApiModel("M", { remainingFraction: 1 }) } };
 		const report = await antigravityUsageProvider.fetchUsage!(
-			{ provider: "google-antigravity", credential: makeCredential({ email: "user@example.com", projectId: "proj-1" }), signal: undefined },
+			{
+				provider: "google-antigravity",
+				credential: makeCredential({ email: "user@example.com", projectId: "proj-1" }),
+				signal: undefined,
+			},
 			makeCtx(fakeFetch(payload)),
 		);
-		expect(report!.metadata.email).toBe("user@example.com");
-		expect(report!.metadata.projectId).toBe("proj-1");
+		expect(report!.metadata?.email).toBe("user@example.com");
+		expect(report!.metadata?.projectId).toBe("proj-1");
 	});
 
 	it("does not include email when credential has none", async () => {
@@ -158,7 +165,7 @@ describe("antigravity usage provider", () => {
 			{ provider: "google-antigravity", credential: makeCredential({ email: undefined }), signal: undefined },
 			makeCtx(fakeFetch(payload)),
 		);
-		expect(report!.metadata.email).toBeUndefined();
+		expect(report!.metadata?.email).toBeUndefined();
 	});
 
 	it("sorts limits by remainingFraction ascending (worst first)", async () => {

From 2620d3970cec81f993aaf9ef7a96faa7decc51cf Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 18:50:37 +0000
Subject: [PATCH 042/181] docs(web-search): updated kagi description to v1
 endpoint

The runtime cutover to Kagi's V1 search API landed in #1272 but
docs/tools/web_search.md still described the sunset V0 endpoint
(GET /api/v0/search with 'Authorization: Bot ...'). Realigned the
Querying and Output bullets with the actual implementation in
packages/coding-agent/src/web/kagi.ts:

- POST https://kagi.com/api/v1/search with Bearer auth and JSON body.
- recency maps to filters.after as a UTC YYYY-MM-DD string.
- Output now includes the categorized bucket merge (search/video/news/
  infobox with title tags), adjacent_question + related_search related
  questions, direct_answer-derived answer, and meta.trace requestId.

Fixes #2009
---
 docs/tools/web_search.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/tools/web_search.md b/docs/tools/web_search.md
index 5b3aa380b..c62df385d 100644
--- a/docs/tools/web_search.md
+++ b/docs/tools/web_search.md
@@ -161,9 +161,9 @@ Streaming: none. `WebSearchTool.execute()` forwards its `AbortSignal` into `exec
     - Output: `sources`, `requestId`.
   - **Kagi** — `packages/coding-agent/src/web/search/providers/kagi.ts`, `packages/coding-agent/src/web/kagi.ts`
     - Availability: env or `agent.db` credential for `kagi`.
-    - Querying: GET `https://kagi.com/api/v0/search?q=<query>&limit=<n>` with `Authorization: Bot <key>`.
+    - Querying: POST `https://kagi.com/api/v1/search` with `Authorization: Bearer <key>` and JSON body `{ query, workflow: "search", limit, filters?: { after } }`. `recency` maps to `filters.after` as a UTC `YYYY-MM-DD` string (`day`/`week`/`month`/`year`).
     - `limit` and `num_search_results` are collapsed together before dispatch, clamped to `1..40`, default `10`.
-    - Output: `sources`, `relatedQuestions`, `requestId`.
+    - Output: `sources` (concatenated `data.search` + `data.video` + `data.news` + `data.infobox`, with video/news/infobox results tagged in the title), `relatedQuestions` (`data.adjacent_question` + `data.related_search` `props.question`), `answer` (`data.direct_answer[0].snippet ?? title`), `requestId` (`meta.trace`).
   - **Synthetic** — `packages/coding-agent/src/web/search/providers/synthetic.ts`
     - Availability: env or `agent.db` credential for `synthetic`.
     - Querying: POST `https://api.synthetic.new/v2/search` with `{ query }`.

From bdbbfa97789ac244546804e2cd5c04a4c5f53abb Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 20:54:00 +0200
Subject: [PATCH 043/181] fix(eval): surfaced subagent abort reason

- Used `||` so empty stderr no longer masks the real abort reason.
---
 .../src/eval/__tests__/agent-bridge.test.ts   | 21 +++++++++++++++++++
 .../coding-agent/src/eval/agent-bridge.ts     |  2 +-
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
index 08bf08401..2d8662ad5 100644
--- a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
+++ b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
@@ -231,6 +231,27 @@ describe("runEvalAgent", () => {
 		});
 		await expect(runEvalAgent({ prompt: "fail" }, { session: makeSession() })).rejects.toThrow("boom");
 	});
+
+	it("surfaces the abort reason when an aborted subagent has empty stderr", async () => {
+		// An aborted subagent returns exitCode 1 with stderr "" and error
+		// undefined; the real reason lives in abortReason. The bridge must not
+		// collapse the failure message to "" (which the Python prelude renders as
+		// the info-free "bridge call '__agent__' failed").
+		mockAgents();
+		vi.spyOn(taskExecutor, "runSubprocess").mockImplementation(async options =>
+			singleResult(options, {
+				exitCode: 1,
+				output: "",
+				stderr: "",
+				aborted: true,
+				abortReason: "Subagent runtime limit exceeded (task.maxRuntimeMs=1000)",
+			}),
+		);
+
+		await expect(runEvalAgent({ prompt: "hello" }, { session: makeSession() })).rejects.toThrow(
+			"Subagent runtime limit exceeded (task.maxRuntimeMs=1000)",
+		);
+	});
 });
 
 describe("agent() through eval runtimes", () => {
diff --git a/packages/coding-agent/src/eval/agent-bridge.ts b/packages/coding-agent/src/eval/agent-bridge.ts
index a97f6c98e..e114c59d8 100644
--- a/packages/coding-agent/src/eval/agent-bridge.ts
+++ b/packages/coding-agent/src/eval/agent-bridge.ts
@@ -280,7 +280,7 @@ export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOption
 
 	if (result.exitCode !== 0 || result.error) {
 		const failureMessage =
-			result.error ?? result.stderr ?? result.abortReason ?? `agent() subagent '${agentName}' failed.`;
+			result.error || result.stderr || result.abortReason || `agent() subagent '${agentName}' failed.`;
 		throw new ToolError(failureMessage);
 	}
 

From 0bac7012cd76b2e7ad11d1ee89345c7f15625824 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 20:56:31 +0200
Subject: [PATCH 044/181] feat(coding-agent/web): added GitHub Actions run/job
 scraping

- Parsed /actions/runs URLs into run and job render handlers.
- Rendered run metadata with per-job breakdown, showing steps for failed jobs.
- Fetched job logs via API token, stripping ISO timestamp prefixes.
---
 packages/coding-agent/CHANGELOG.md            |   5 +
 .../coding-agent/src/web/scrapers/github.ts   | 258 +++++++++++++++++-
 .../tools/web-scrapers/git-hosting.test.ts    |  56 +++-
 3 files changed, 315 insertions(+), 4 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index a90e895a4..211bb67ff 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added a GitHub Actions read handler to the `read`/web-fetch GitHub scraper. Fetching `github.com/{owner}/{repo}/actions/runs/{id}` renders the run metadata plus a per-job breakdown (steps listed for any job that did not succeed), and `…/actions/runs/{id}/job/{id}` (also the API-style `…/jobs/{id}`) renders a single job's metadata, step table, and full plain-text logs. Logs are fetched via the `actions/jobs/{id}/logs` redirect using `GITHUB_TOKEN`/`GH_TOKEN` when present, with the per-line ISO timestamp prefix and leading BOM stripped; the section degrades to an explicit notice when logs are unavailable (no token, private repo, or expired/unfinalized run).
+
+
 ## [15.9.69] - 2026-06-06
 ### Fixed
 
diff --git a/packages/coding-agent/src/web/scrapers/github.ts b/packages/coding-agent/src/web/scrapers/github.ts
index 50ef8b50c..b7b7990c2 100644
--- a/packages/coding-agent/src/web/scrapers/github.ts
+++ b/packages/coding-agent/src/web/scrapers/github.ts
@@ -1,14 +1,28 @@
 import { $env, ptree } from "@oh-my-pi/pi-utils";
 import type { RenderResult, SpecialHandler } from "./types";
-import { buildResult, loadPage } from "./types";
+import { buildResult, formatMediaDuration, loadPage } from "./types";
 
 interface GitHubUrl {
-	type: "blob" | "tree" | "repo" | "issue" | "issues" | "pull" | "pulls" | "discussion" | "discussions" | "other";
+	type:
+		| "blob"
+		| "tree"
+		| "repo"
+		| "issue"
+		| "issues"
+		| "pull"
+		| "pulls"
+		| "discussion"
+		| "discussions"
+		| "actions-run"
+		| "actions-job"
+		| "other";
 	owner: string;
 	repo: string;
 	ref?: string;
 	path?: string;
 	number?: number;
+	runId?: number;
+	jobId?: number;
 }
 
 interface GitHubIssueComment {
@@ -20,7 +34,7 @@ interface GitHubIssueComment {
 /**
  * Parse GitHub URL into components
  */
-function parseGitHubUrl(url: string): GitHubUrl | null {
+export function parseGitHubUrl(url: string): GitHubUrl | null {
 	try {
 		const parsed = new URL(url);
 		if (parsed.hostname !== "github.com") return null;
@@ -54,6 +68,20 @@ function parseGitHubUrl(url: string): GitHubUrl | null {
 				return { type: "pulls", owner, repo };
 			case "pulls":
 				return { type: "pulls", owner, repo };
+			case "actions": {
+				// /actions/runs/{runId}                      → run summary + jobs
+				// /actions/runs/{runId}/job/{jobId}          → single job (web URL uses singular "job")
+				// /actions/runs/{runId}/jobs/{jobId}         → single job (API-style plural)
+				if (subParts[0] === "runs" && /^\d+$/.test(subParts[1] ?? "")) {
+					const runId = parseInt(subParts[1], 10);
+					const seg = subParts[2];
+					if ((seg === "job" || seg === "jobs") && /^\d+$/.test(subParts[3] ?? "")) {
+						return { type: "actions-job", owner, repo, runId, jobId: parseInt(subParts[3], 10) };
+					}
+					return { type: "actions-run", owner, repo, runId };
+				}
+				return { type: "other", owner, repo };
+			}
 			case "discussions":
 				if (subParts.length > 0 && /^\d+$/.test(subParts[0])) {
 					return { type: "discussion", owner, repo, number: parseInt(subParts[0], 10) };
@@ -371,6 +399,212 @@ async function renderGitHubRepo(
 	return { content: md, ok: true };
 }
 
+interface GitHubActionsStep {
+	name: string;
+	status: string;
+	conclusion: string | null;
+	number: number;
+	started_at: string | null;
+	completed_at: string | null;
+}
+
+interface GitHubActionsJob {
+	id: number;
+	run_id: number;
+	name: string;
+	status: string;
+	conclusion: string | null;
+	started_at: string | null;
+	completed_at: string | null;
+	html_url: string | null;
+	steps?: GitHubActionsStep[];
+	runner_name?: string | null;
+	labels?: string[];
+	workflow_name?: string | null;
+	head_branch?: string | null;
+	head_sha?: string;
+}
+
+interface GitHubActionsRun {
+	id: number;
+	name?: string | null;
+	display_title?: string;
+	run_number: number;
+	run_attempt?: number;
+	event: string;
+	status: string;
+	conclusion: string | null;
+	head_branch?: string | null;
+	head_sha?: string;
+	html_url: string;
+	created_at: string;
+	updated_at: string;
+	run_started_at?: string;
+	actor?: { login: string };
+	triggering_actor?: { login: string };
+}
+
+/** Combine status + conclusion into a single label, e.g. `completed (failure)`. */
+function statusLabel(status: string, conclusion: string | null | undefined): string {
+	return conclusion ? `${status} (${conclusion})` : status;
+}
+
+/** Wall-clock duration between two ISO timestamps, formatted HH:MM:SS / MM:SS. Empty when unknown. */
+function actionDuration(start?: string | null, end?: string | null): string {
+	if (!start || !end) return "";
+	const ms = Date.parse(end) - Date.parse(start);
+	if (!Number.isFinite(ms) || ms < 0) return "";
+	return formatMediaDuration(Math.round(ms / 1000));
+}
+
+/** Escape `|` so step/job names can't break a markdown table row. */
+function escapeCell(text: string): string {
+	return text.replaceAll("|", "\\|");
+}
+
+/**
+ * Strip the per-line ISO-8601 timestamp prefix GitHub prepends to every job log line.
+ * Cuts ~28 bytes/line of noise while preserving the message text. Also drops the leading
+ * UTF-8 BOM GitHub puts at the start of the log file (otherwise the first line's timestamp
+ * survives because `^` no longer sits before a digit).
+ */
+export function stripActionsLogTimestamps(logs: string): string {
+	return logs.replace(/^\uFEFF/, "").replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z /gm, "");
+}
+
+/** Render a job's steps as a markdown table. Empty string when there are no steps. */
+function renderActionsSteps(steps?: GitHubActionsStep[]): string {
+	if (!steps || steps.length === 0) return "";
+	let md = "| # | Step | Status | Conclusion | Duration |\n";
+	md += "|---|------|--------|------------|----------|\n";
+	for (const step of steps) {
+		const dur = actionDuration(step.started_at, step.completed_at) || "-";
+		md += `| ${step.number} | ${escapeCell(step.name)} | ${step.status} | ${step.conclusion ?? "-"} | ${dur} |\n`;
+	}
+	return `${md}\n`;
+}
+
+/** Run-level metadata lines shared by the run and job renderers. */
+function renderActionsRunMeta(run: GitHubActionsRun): string {
+	let md = `**Workflow:** ${run.name ?? "(unknown)"}\n`;
+	md += `**Run:** #${run.run_number}`;
+	if (run.run_attempt && run.run_attempt > 1) md += ` (attempt ${run.run_attempt})`;
+	md += ` · ${statusLabel(run.status, run.conclusion)}\n`;
+	if (run.head_branch) {
+		md += `**Branch:** ${run.head_branch}${run.head_sha ? ` @ ${run.head_sha.slice(0, 7)}` : ""}\n`;
+	}
+	const actor = run.triggering_actor?.login ?? run.actor?.login;
+	md += `**Event:** ${run.event}${actor ? ` · by @${actor}` : ""}\n`;
+	const started = run.run_started_at ?? run.created_at;
+	const dur = actionDuration(started, run.updated_at);
+	md += `Started: ${started}${dur ? ` · Duration: ${dur}` : ""}\n`;
+	md += `URL: ${run.html_url}\n`;
+	return md;
+}
+
+/** Fetch a job's plain-text logs. Returns null when unavailable (no token / expired / private). */
+async function fetchGitHubJobLogs(
+	owner: string,
+	repo: string,
+	jobId: number,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<string | null> {
+	const headers: Record<string, string> = {
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28",
+	};
+	const token = $env.GITHUB_TOKEN || $env.GH_TOKEN;
+	if (token) headers.Authorization = `Bearer ${token}`;
+
+	// 302 → signed log URL on a different origin; fetch strips Authorization on the cross-origin hop.
+	const result = await loadPage(`https://api.github.com/repos/${owner}/${repo}/actions/jobs/${jobId}/logs`, {
+		timeout,
+		headers,
+		signal,
+	});
+	return result.ok && result.content ? result.content : null;
+}
+
+/**
+ * Render a workflow run: run metadata plus a per-job breakdown. Steps are listed for any job that
+ * did not succeed (the debugging-relevant ones); successful jobs collapse to a single line.
+ */
+async function renderGitHubActionsRun(
+	gh: GitHubUrl,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<{ content: string; ok: boolean }> {
+	const runResult = await fetchGitHubApi(`/repos/${gh.owner}/${gh.repo}/actions/runs/${gh.runId}`, timeout, signal);
+	if (!runResult.ok || !runResult.data) return { content: "", ok: false };
+
+	const run = runResult.data as GitHubActionsRun;
+	let md = `# ${run.display_title || run.name || `Run #${run.run_number}`}\n\n`;
+	md += renderActionsRunMeta(run);
+	md += `\n---\n\n`;
+
+	const jobsResult = await fetchGitHubApi(
+		`/repos/${gh.owner}/${gh.repo}/actions/runs/${gh.runId}/jobs?per_page=100`,
+		timeout,
+		signal,
+	);
+	if (jobsResult.ok && jobsResult.data) {
+		const jobs = (jobsResult.data as { jobs?: GitHubActionsJob[] }).jobs ?? [];
+		md += `## Jobs (${jobs.length})\n\n`;
+		for (const job of jobs) {
+			const dur = actionDuration(job.started_at, job.completed_at);
+			md += `### ${escapeCell(job.name)} — ${statusLabel(job.status, job.conclusion)}${dur ? ` (${dur})` : ""}\n\n`;
+			if (job.conclusion !== "success") {
+				md += renderActionsSteps(job.steps);
+			}
+		}
+	}
+
+	return { content: md, ok: true };
+}
+
+/**
+ * Render a single workflow job: run context, step table, and the full job logs.
+ */
+async function renderGitHubActionsJob(
+	gh: GitHubUrl,
+	timeout: number,
+	signal?: AbortSignal,
+): Promise<{ content: string; ok: boolean }> {
+	const jobResult = await fetchGitHubApi(`/repos/${gh.owner}/${gh.repo}/actions/jobs/${gh.jobId}`, timeout, signal);
+	if (!jobResult.ok || !jobResult.data) return { content: "", ok: false };
+
+	const job = jobResult.data as GitHubActionsJob;
+
+	// Best-effort run context for nicer headers; the job render stands on its own without it.
+	const runResult = await fetchGitHubApi(`/repos/${gh.owner}/${gh.repo}/actions/runs/${job.run_id}`, timeout, signal);
+	const run = runResult.ok && runResult.data ? (runResult.data as GitHubActionsRun) : null;
+
+	let md = `# ${escapeCell(job.name)}\n\n`;
+	if (run) {
+		md += renderActionsRunMeta(run);
+	} else if (job.workflow_name) {
+		md += `**Workflow:** ${job.workflow_name}\n`;
+		if (job.head_branch) md += `**Branch:** ${job.head_branch}\n`;
+	}
+	const dur = actionDuration(job.started_at, job.completed_at);
+	md += `**Job:** ${escapeCell(job.name)} · ${statusLabel(job.status, job.conclusion)}${dur ? ` · ${dur}` : ""}\n`;
+	if (job.runner_name) md += `**Runner:** ${job.runner_name}\n`;
+	if (job.html_url) md += `URL: ${job.html_url}\n`;
+	md += `\n---\n\n`;
+
+	const steps = renderActionsSteps(job.steps);
+	if (steps) md += `## Steps\n\n${steps}`;
+
+	const logs = await fetchGitHubJobLogs(gh.owner, gh.repo, job.id, timeout, signal);
+	md += `## Logs\n\n`;
+	md += logs
+		? stripActionsLogTimestamps(logs)
+		: "*Logs unavailable — requires a GITHUB_TOKEN/GH_TOKEN with read access, or the run's logs have expired.*\n";
+
+	return { content: md, ok: true };
+}
+
 /**
  * Handle GitHub URLs specially
  */
@@ -445,6 +679,24 @@ export const handleGitHub: SpecialHandler = async (
 			}
 			break;
 		}
+
+		case "actions-run": {
+			notes.push(`Fetched via GitHub API`);
+			const result = await renderGitHubActionsRun(gh, timeout, signal);
+			if (result.ok) {
+				return buildResult(result.content, { url, method: "github-actions-run", fetchedAt, notes });
+			}
+			break;
+		}
+
+		case "actions-job": {
+			notes.push(`Fetched via GitHub API`);
+			const result = await renderGitHubActionsJob(gh, timeout, signal);
+			if (result.ok) {
+				return buildResult(result.content, { url, method: "github-actions-job", fetchedAt, notes });
+			}
+			break;
+		}
 	}
 
 	// Fall back to null (let normal rendering handle it)
diff --git a/packages/coding-agent/test/tools/web-scrapers/git-hosting.test.ts b/packages/coding-agent/test/tools/web-scrapers/git-hosting.test.ts
index d54a9ee47..e219e5167 100644
--- a/packages/coding-agent/test/tools/web-scrapers/git-hosting.test.ts
+++ b/packages/coding-agent/test/tools/web-scrapers/git-hosting.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { handleGitHub } from "@oh-my-pi/pi-coding-agent/web/scrapers/github";
+import { handleGitHub, parseGitHubUrl, stripActionsLogTimestamps } from "@oh-my-pi/pi-coding-agent/web/scrapers/github";
 import { handleGitHubGist } from "@oh-my-pi/pi-coding-agent/web/scrapers/github-gist";
 
 const SKIP = !Bun.env.WEB_FETCH_INTEGRATION;
@@ -203,3 +203,57 @@ describe.skipIf(SKIP)("handleGitHubGist", () => {
 		expect(result).toBeDefined();
 	});
 });
+
+// =============================================================================
+// GitHub Actions URL parsing (pure, network-free)
+// =============================================================================
+
+describe("parseGitHubUrl — Actions", () => {
+	it("classifies a workflow run URL", () => {
+		const gh = parseGitHubUrl("https://github.com/can1357/oh-my-pi/actions/runs/27070071296");
+		expect(gh).toEqual({ type: "actions-run", owner: "can1357", repo: "oh-my-pi", runId: 27070071296 });
+	});
+
+	it("classifies a job URL using the web-form singular `job` segment", () => {
+		const gh = parseGitHubUrl("https://github.com/can1357/oh-my-pi/actions/runs/27070071296/job/79897931171");
+		expect(gh).toEqual({
+			type: "actions-job",
+			owner: "can1357",
+			repo: "oh-my-pi",
+			runId: 27070071296,
+			jobId: 79897931171,
+		});
+	});
+
+	it("classifies a job URL using the API-form plural `jobs` segment", () => {
+		const gh = parseGitHubUrl("https://github.com/can1357/oh-my-pi/actions/runs/27070071296/jobs/79897931171");
+		expect(gh?.type).toBe("actions-job");
+		expect(gh?.jobId).toBe(79897931171);
+	});
+
+	it("does not treat non-run Actions URLs (e.g. workflow files) as runs/jobs", () => {
+		expect(parseGitHubUrl("https://github.com/can1357/oh-my-pi/actions/workflows/ci.yml")?.type).toBe("other");
+		expect(parseGitHubUrl("https://github.com/can1357/oh-my-pi/actions")?.type).toBe("other");
+	});
+
+	it("does not misparse a run URL with a non-numeric id", () => {
+		expect(parseGitHubUrl("https://github.com/can1357/oh-my-pi/actions/runs/latest")?.type).toBe("other");
+	});
+
+	it("returns null for non-github hosts", () => {
+		expect(parseGitHubUrl("https://gitlab.com/o/r/actions/runs/1")).toBeNull();
+	});
+});
+
+describe("stripActionsLogTimestamps", () => {
+	it("removes the per-line ISO timestamp prefix and a leading BOM", () => {
+		const raw =
+			"\uFEFF2026-06-06T18:14:12.8793443Z Current runner version: '2.334.0'\n2026-06-06T18:14:13.0000000Z done\n";
+		expect(stripActionsLogTimestamps(raw)).toBe("Current runner version: '2.334.0'\ndone\n");
+	});
+
+	it("leaves grouped/non-timestamped lines untouched", () => {
+		const raw = "2026-06-06T18:14:12.0000000Z ##[group]Operating System\nUbuntu\n##[endgroup]\n";
+		expect(stripActionsLogTimestamps(raw)).toBe("##[group]Operating System\nUbuntu\n##[endgroup]\n");
+	});
+});

From 133137c9a672077880c94c7d6065b194ca76d799 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 21:33:07 +0200
Subject: [PATCH 045/181] fix(eval): surfaced subagent abort reasons and
 disabled runtime cap

- Used `||` so empty stderr falls through to abortReason in agent bridge.
- Preferred assistant errorMessage over "Cancelled by caller" on internal aborts.
- Forced `maxRuntimeMs: 0` for eval subagents via ExecutorOptions override.
---
 packages/coding-agent/CHANGELOG.md            |  8 +++++
 .../src/eval/__tests__/agent-bridge.test.ts   |  9 ++++++
 .../coding-agent/src/eval/agent-bridge.ts     |  6 ++++
 packages/coding-agent/src/task/executor.ts    | 22 ++++++++++++--
 .../task/executor-subagent-reminders.test.ts  | 29 +++++++++++++++++++
 5 files changed, 72 insertions(+), 2 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 211bb67ff..8aa225b00 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -6,6 +6,14 @@
 
 - Added a GitHub Actions read handler to the `read`/web-fetch GitHub scraper. Fetching `github.com/{owner}/{repo}/actions/runs/{id}` renders the run metadata plus a per-job breakdown (steps listed for any job that did not succeed), and `…/actions/runs/{id}/job/{id}` (also the API-style `…/jobs/{id}`) renders a single job's metadata, step table, and full plain-text logs. Logs are fetched via the `actions/jobs/{id}/logs` redirect using `GITHUB_TOKEN`/`GH_TOKEN` when present, with the per-line ISO timestamp prefix and leading BOM stripped; the section degrades to an explicit notice when logs are unavailable (no token, private repo, or expired/unfinalized run).
 
+### Changed
+
+- Changed eval `agent()` subagents so they are never subject to the `task.maxRuntimeMs` wall-clock cap. The parent cell's idle watchdog is already suspended for the entire bridge call (`withBridgeTimeoutPause`), so a long-running fan-out/recovery workflow must not be killed by a per-subagent runtime limit. `runEvalAgent` now passes `maxRuntimeMs: 0` to `runSubprocess`, which honors an explicit `ExecutorOptions.maxRuntimeMs` override over the inherited setting.
+
+### Fixed
+
+- Fixed eval `agent()` failures surfacing as an opaque `RuntimeError: bridge call '__agent__' failed` with no reason. When a subagent aborted, `runEvalAgent` built its failure message with `result.error ?? result.stderr ?? result.abortReason ?? …`, but `result.stderr` is the empty string on a clean abort (and `result.error` is gated on a non-empty `stderr`), so the nullish chain stopped at `""` and never reached `abortReason`. The empty string propagated through the loopback bridge and the Python prelude's `RuntimeError(msg or "bridge call … failed")`, discarding the real reason. The chain now uses `||` so an empty `stderr` falls through to `abortReason`.
+- Fixed subagent aborts being mislabeled as the generic "Cancelled by caller" when the abort originated inside the subagent's own turn (`stopReason: "aborted"` with no caller signal and no runtime-limit timer). `runSubprocess` now prefers the aborted assistant message's `errorMessage` (e.g. "Request was aborted" or a specific stream error) for that case, while a real caller signal or wall-clock abort still reports its precise reason.
 
 ## [15.9.69] - 2026-06-06
 ### Fixed
diff --git a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
index 2d8662ad5..9f6c5d48c 100644
--- a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
+++ b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
@@ -252,6 +252,15 @@ describe("runEvalAgent", () => {
 			"Subagent runtime limit exceeded (task.maxRuntimeMs=1000)",
 		);
 	});
+
+	it("disables the wall-clock runtime limit for eval subagents", async () => {
+		mockAgents();
+		const runSpy = vi.spyOn(taskExecutor, "runSubprocess").mockImplementation(async options => singleResult(options));
+
+		await runEvalAgent({ prompt: "hello" }, { session: makeSession() });
+
+		expect(runSpy.mock.calls[0]?.[0].maxRuntimeMs).toBe(0);
+	});
 });
 
 describe("agent() through eval runtimes", () => {
diff --git a/packages/coding-agent/src/eval/agent-bridge.ts b/packages/coding-agent/src/eval/agent-bridge.ts
index e114c59d8..618895e91 100644
--- a/packages/coding-agent/src/eval/agent-bridge.ts
+++ b/packages/coding-agent/src/eval/agent-bridge.ts
@@ -259,6 +259,12 @@ export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOption
 			authStorage: options.session.authStorage,
 			modelRegistry: options.session.modelRegistry,
 			settings: options.session.settings,
+			// Eval `agent()` subagents are never wall-clock capped: the parent
+			// cell's idle watchdog is suspended for the whole bridge call
+			// (withBridgeTimeoutPause), so a long-running phase/recovery workflow
+			// must not be killed by `task.maxRuntimeMs`. Force the limit off
+			// regardless of the inherited session setting.
+			maxRuntimeMs: 0,
 			mcpManager,
 			contextFiles,
 			skills: availableSkills,
diff --git a/packages/coding-agent/src/task/executor.ts b/packages/coding-agent/src/task/executor.ts
index 94fb9a63b..254a2dc5e 100644
--- a/packages/coding-agent/src/task/executor.ts
+++ b/packages/coding-agent/src/task/executor.ts
@@ -166,6 +166,13 @@ export interface ExecutorOptions {
 	outputSchema?: unknown;
 	/** Parent task recursion depth (0 = top-level, 1 = first child, etc.) */
 	taskDepth?: number;
+	/**
+	 * Override the `task.maxRuntimeMs` wall-clock cap for this run. When provided
+	 * it wins over the settings value; `0` disables the per-subagent wall-clock
+	 * limit entirely. Used by the eval `agent()` bridge, whose parent cell
+	 * watchdog is already suspended for the call's duration.
+	 */
+	maxRuntimeMs?: number;
 	enableLsp?: boolean;
 	signal?: AbortSignal;
 	onProgress?: (progress: AgentProgress) => void;
@@ -625,7 +632,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		agent.readSummarize === false ? { "read.summarize.enabled": false } : undefined,
 	);
 	const maxRecursionDepth = settings.get("task.maxRecursionDepth") ?? 2;
-	const maxRuntimeMs = Math.max(0, Math.trunc(Number(settings.get("task.maxRuntimeMs") ?? 0) || 0));
+	const maxRuntimeMs = Math.max(
+		0,
+		Math.trunc(Number(options.maxRuntimeMs ?? settings.get("task.maxRuntimeMs") ?? 0) || 0),
+	);
 	const parentDepth = options.taskDepth ?? 0;
 	const childDepth = parentDepth + 1;
 	const atMaxDepth = maxRecursionDepth >= 0 && childDepth >= maxRecursionDepth;
@@ -1484,7 +1494,15 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				if (lastAssistant.stopReason === "aborted") {
 					aborted = abortReason === "signal" || runtimeLimitExceeded || abortReason === undefined;
 					if (aborted) {
-						abortReasonText ??= resolveAbortReasonText();
+						// A real caller signal or the wall-clock timer carries a precise
+						// reason (signal.reason / "runtime limit exceeded"). An internal
+						// turn abort (abortReason === undefined) does NOT — prefer the
+						// assistant message's own errorMessage ("Request was aborted" or a
+						// specific stream error) over the misleading "Cancelled by caller".
+						abortReasonText ??=
+							abortReason === "signal" || runtimeLimitExceeded
+								? resolveAbortReasonText()
+								: lastAssistant.errorMessage?.trim() || resolveAbortReasonText();
 					}
 					exitCode = 1;
 				} else if (lastAssistant.stopReason === "error") {
diff --git a/packages/coding-agent/test/task/executor-subagent-reminders.test.ts b/packages/coding-agent/test/task/executor-subagent-reminders.test.ts
index 6d346a074..347bb0002 100644
--- a/packages/coding-agent/test/task/executor-subagent-reminders.test.ts
+++ b/packages/coding-agent/test/task/executor-subagent-reminders.test.ts
@@ -474,6 +474,35 @@ describe("runSubprocess yield reminders", () => {
 		expect(result.abortReason).toBe("Cancelled before start");
 		expect(result.stderr).toBe("Cancelled before start");
 	});
+
+	it("surfaces the assistant abort message instead of 'Cancelled by caller' on an internal turn abort", async () => {
+		// No caller signal and no runtime limit: the subagent's own turn ended with
+		// stopReason "aborted" (e.g. a merged request-signal abort). abortReason is
+		// undefined, so the executor must report the assistant's real errorMessage,
+		// not the generic caller-cancellation fallback. This is also what the eval
+		// agent() bridge re-raises, so a blank/misleading reason here surfaces as an
+		// opaque "bridge call '__agent__' failed".
+		const session = createMockSession(({ emit, state }) => {
+			const aborted: AssistantMessage = {
+				...createAssistantStopMessage(""),
+				stopReason: "aborted",
+				errorMessage: "Request was aborted",
+			};
+			state.messages.push(aborted);
+			emit({ type: "message_end", message: aborted });
+		});
+
+		mockCreateAgentSession(session);
+
+		const result = await runSubprocess({ ...baseOptions, id: "subagent-internal-abort" });
+
+		expect(result.aborted).toBe(true);
+		expect(result.exitCode).toBe(1);
+		expect(result.abortReason).toBe("Request was aborted");
+		expect(result.abortReason).not.toBe("Cancelled by caller");
+		expect(result.error).toBeUndefined();
+		expect(result.stderr).toBe("");
+	});
 	it("uses modelRegistry.authStorage when only options.modelRegistry is provided", async () => {
 		const session = createMockSession(({ emit }) => {
 			emit({

From 5fc443f4af9939266f3324b96a436448f45e98ea Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 21:36:39 +0200
Subject: [PATCH 046/181] fix(ai): adjusted usage ranking comparator for stable
 metric ordering

- Added a tolerance-aware `compareUsageRankingMetric` helper with finite-value handling.
- Replaced usage provider sorting comparisons with the new comparator for secondary and primary usage metrics.
- Kept existing tie-breaker fields while stabilizing ordering for nearly equal metric values.
---
 packages/ai/src/auth-storage.ts | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/packages/ai/src/auth-storage.ts b/packages/ai/src/auth-storage.ts
index b1153bed0..dab8e1045 100644
--- a/packages/ai/src/auth-storage.ts
+++ b/packages/ai/src/auth-storage.ts
@@ -36,6 +36,8 @@ import { loginOpenAICodexDevice } from "./utils/oauth/openai-codex";
 import type { OAuthController, OAuthCredentials, OAuthProvider, OAuthProviderId } from "./utils/oauth/types";
 import { loginXiaomi, loginXiaomiTokenPlan } from "./utils/oauth/xiaomi";
 
+const USAGE_RANKING_METRIC_EPSILON = 1e-9;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Credential Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -606,6 +608,14 @@ function hasOpenAICodexProPlan(report: UsageReport | null): boolean {
 	return getUsagePlanType(report)?.includes("pro") === true;
 }
 
+function compareUsageRankingMetric(left: number, right: number): number {
+	if (left === right) return 0;
+	if (!Number.isFinite(left) || !Number.isFinite(right)) return left < right ? -1 : 1;
+	const delta = left - right;
+	const tolerance = Math.max(USAGE_RANKING_METRIC_EPSILON, Math.max(Math.abs(left), Math.abs(right)) * 0.000001);
+	return Math.abs(delta) <= tolerance ? 0 : delta;
+}
+
 function resolveDefaultUsageProvider(provider: Provider): UsageProvider | undefined {
 	return DEFAULT_USAGE_PROVIDER_MAP.get(provider);
 }
@@ -2796,12 +2806,14 @@ export class AuthStorage {
 			return left.planPriority - right.planPriority;
 		}
 		if (left.hasPriorityBoost !== right.hasPriorityBoost) return left.hasPriorityBoost ? -1 : 1;
-		if (left.secondaryDrainRate !== right.secondaryDrainRate) {
-			return left.secondaryDrainRate - right.secondaryDrainRate;
-		}
-		if (left.secondaryUsed !== right.secondaryUsed) return left.secondaryUsed - right.secondaryUsed;
-		if (left.primaryDrainRate !== right.primaryDrainRate) return left.primaryDrainRate - right.primaryDrainRate;
-		if (left.primaryUsed !== right.primaryUsed) return left.primaryUsed - right.primaryUsed;
+		let metric = compareUsageRankingMetric(left.secondaryDrainRate, right.secondaryDrainRate);
+		if (metric !== 0) return metric;
+		metric = compareUsageRankingMetric(left.secondaryUsed, right.secondaryUsed);
+		if (metric !== 0) return metric;
+		metric = compareUsageRankingMetric(left.primaryDrainRate, right.primaryDrainRate);
+		if (metric !== 0) return metric;
+		metric = compareUsageRankingMetric(left.primaryUsed, right.primaryUsed);
+		if (metric !== 0) return metric;
 		return 0;
 	}
 

From 57210347395ad3bb431d440c0a580de76965ea21 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 21:53:22 +0200
Subject: [PATCH 047/181] fix(ui): forced full replay on tool output expand
 toggle

- Replaced viewport-only repaint with resetDisplay so committed scrollback reflects new heights.
- Added per-server rust-analyzer workspace-ready timing overrides as a test seam.
- Added clearSuppressedSelectors to reset retry-fallback cooldown state.
- Removed obsolete shared eval executors test.
---
 .../coding-agent/src/config/model-registry.ts |   8 +
 .../eval/__tests__/shared-executors.test.ts   | 609 ------------------
 packages/coding-agent/src/lsp/client.ts       |  16 +-
 packages/coding-agent/src/lsp/types.ts        |  10 +
 .../src/modes/controllers/input-controller.ts |  10 +-
 packages/tui/src/tui.ts                       |   9 +
 6 files changed, 47 insertions(+), 615 deletions(-)
 delete mode 100644 packages/coding-agent/src/eval/__tests__/shared-executors.test.ts

diff --git a/packages/coding-agent/src/config/model-registry.ts b/packages/coding-agent/src/config/model-registry.ts
index a37fdb8e9..ac83a06ce 100644
--- a/packages/coding-agent/src/config/model-registry.ts
+++ b/packages/coding-agent/src/config/model-registry.ts
@@ -2609,6 +2609,14 @@ export class ModelRegistry {
 		}
 		return true;
 	}
+
+	/**
+	 * Clear all cooldown suppressions recorded via {@link suppressSelector}.
+	 * Used to reset retry-fallback cooldown state without a full {@link refresh}.
+	 */
+	clearSuppressedSelectors(): void {
+		this.#suppressedSelectors.clear();
+	}
 }
 
 /**
diff --git a/packages/coding-agent/src/eval/__tests__/shared-executors.test.ts b/packages/coding-agent/src/eval/__tests__/shared-executors.test.ts
deleted file mode 100644
index a68c896e8..000000000
--- a/packages/coding-agent/src/eval/__tests__/shared-executors.test.ts
+++ /dev/null
@@ -1,609 +0,0 @@
-import { afterAll, afterEach, describe, expect, it, vi } from "bun:test";
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import type { AssistantMessage } from "@oh-my-pi/pi-ai";
-import { TempDir } from "@oh-my-pi/pi-utils";
-import type { ModelRegistry } from "../../config/model-registry";
-import { Settings } from "../../config/settings";
-import type { LoadExtensionsResult } from "../../extensibility/extensions/types";
-import type { CreateAgentSessionOptions, CreateAgentSessionResult } from "../../sdk";
-import * as sdkModule from "../../sdk";
-import type { AgentSession, AgentSessionEvent, PromptOptions } from "../../session/agent-session";
-import { TaskTool } from "../../task";
-import * as discoveryModule from "../../task/discovery";
-import type { AgentDefinition, TaskParams } from "../../task/types";
-import type { ToolSession } from "../../tools";
-import { EventBus } from "../../utils/event-bus";
-import { disposeAllVmContexts } from "../js/context-manager";
-import { executeJs } from "../js/executor";
-import { disposeAllKernelSessions, executePython } from "../py/executor";
-
-function createToolSession(cwd: string, sessionFile: string | null, evalSessionId?: string): ToolSession {
-	const modelRegistry = {
-		authStorage: undefined,
-		refresh: async () => {},
-		getAvailable: () => [],
-		getApiKey: async () => null,
-	} as unknown as ModelRegistry;
-	return {
-		cwd,
-		hasUI: false,
-		settings: Settings.isolated({
-			"async.enabled": false,
-			"task.isolation.mode": "none",
-		}),
-		getSessionFile: () => sessionFile,
-		getSessionSpawns: () => "*",
-		getEvalSessionId: evalSessionId ? () => evalSessionId : undefined,
-		modelRegistry,
-	} as unknown as ToolSession;
-}
-
-function createBridgeToolSession(resultText: string, calls: unknown[]): ToolSession {
-	const readTool = {
-		name: "read",
-		label: "read",
-		description: "read",
-		parameters: { type: "object" },
-		async execute(_id: string, args: unknown) {
-			calls.push(args);
-			return { content: [{ type: "text" as const, text: resultText }] };
-		},
-	};
-	const tools = new Map<string, unknown>([["read", readTool]]);
-	return { getToolByName: (name: string) => tools.get(name) } as unknown as ToolSession;
-}
-
-function assistantStopMessage(text: string): AssistantMessage {
-	return {
-		role: "assistant",
-		content: text ? [{ type: "text", text }] : [],
-		api: "openai-responses",
-		provider: "openai",
-		model: "mock",
-		usage: {
-			input: 0,
-			output: 0,
-			cacheRead: 0,
-			cacheWrite: 0,
-			totalTokens: 0,
-			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-		},
-		stopReason: "stop",
-		timestamp: Date.now(),
-	};
-}
-
-function createYieldingSubagentSession(onPrompt: () => Promise<void>): AgentSession {
-	const listeners: Array<(event: AgentSessionEvent) => void> = [];
-	const state = { messages: [] as AssistantMessage[] };
-	const emit = (event: AgentSessionEvent) => {
-		for (const listener of listeners) listener(event);
-	};
-	return {
-		state,
-		agent: { state: { systemPrompt: ["test"] } },
-		model: undefined,
-		extensionRunner: undefined,
-		sessionManager: {
-			appendSessionInit: () => {},
-		},
-		getActiveToolNames: () => ["eval", "yield"],
-		setActiveToolsByName: async () => {},
-		subscribe: (listener: (event: AgentSessionEvent) => void) => {
-			listeners.push(listener);
-			return () => {
-				const index = listeners.indexOf(listener);
-				if (index >= 0) listeners.splice(index, 1);
-			};
-		},
-		prompt: async (_text: string, _options?: PromptOptions) => {
-			await onPrompt();
-			state.messages.push(assistantStopMessage("done"));
-			emit({
-				type: "tool_execution_end",
-				toolCallId: "yield-call",
-				toolName: "yield",
-				result: {
-					content: [{ type: "text", text: "Result submitted." }],
-					details: { status: "success", data: { ok: true } },
-				},
-				isError: false,
-			});
-		},
-		waitForIdle: async () => {},
-		getLastAssistantMessage: () => state.messages[state.messages.length - 1],
-		abort: async () => {},
-		dispose: async () => {},
-	} as unknown as AgentSession;
-}
-
-const taskAgent: AgentDefinition = {
-	name: "task",
-	description: "Task agent",
-	systemPrompt: "Read eval state and yield.",
-	source: "bundled",
-	tools: ["eval", "yield"],
-};
-
-const taskParams: TaskParams = {
-	agent: "task",
-	tasks: [{ id: "ReadEval", description: "Read eval state", assignment: "Read parent eval state." }],
-};
-
-describe("shared eval executors", () => {
-	afterEach(() => {
-		vi.restoreAllMocks();
-	});
-
-	afterAll(async () => {
-		await disposeAllVmContexts();
-		await disposeAllKernelSessions();
-	});
-
-	it("shares JavaScript state across executeJs calls with one session id", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-js-shared-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `js-shared:${crypto.randomUUID()}`;
-		const session = createToolSession(tempDir.path(), sessionFile);
-
-		await executeJs("globalThis.x = 41;", { sessionId, session, sessionFile });
-		const result = await executeJs("return globalThis.x + 1;", { sessionId, session, sessionFile });
-
-		expect(result.exitCode).toBe(0);
-		expect(result.output.trim()).toBe("42");
-	});
-
-	it("treats idleTimeoutMs as caller-owned watchdog metadata, not a fixed timer", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-js-idle-budget-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `js-idle-budget:${crypto.randomUUID()}`;
-		const session = createToolSession(tempDir.path(), sessionFile);
-
-		// With no wall-clock deadlineMs/timeoutMs and no aborting signal, a cell that
-		// runs well past idleTimeoutMs must still complete: the backend must never
-		// derive a competing fixed timer from the caller-owned watchdog budget.
-		const result = await executeJs("await Bun.sleep(120); return 'done';", {
-			sessionId,
-			session,
-			sessionFile,
-			idleTimeoutMs: 30,
-		});
-
-		expect(result.cancelled).toBe(false);
-		expect(result.exitCode).toBe(0);
-		expect(result.output.trim()).toBe("done");
-	});
-
-	it("shares Python state across executePython calls with one session id", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-py-shared-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-shared:${crypto.randomUUID()}`;
-
-		await executePython("x = 41", { cwd: tempDir.path(), sessionId, sessionFile });
-		const result = await executePython("print(x + 1)", { cwd: tempDir.path(), sessionId, sessionFile });
-
-		expect(result.exitCode).toBe(0);
-		expect(result.output.trim()).toBe("42");
-	});
-
-	it("deduplicates concurrent first JavaScript session acquisition", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-js-cold-start-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `js-cold-start:${crypto.randomUUID()}`;
-		const session = createToolSession(tempDir.path(), sessionFile);
-
-		const [first, second] = await Promise.all([
-			executeJs(
-				"globalThis.sharedMarker ??= crypto.randomUUID(); await Bun.sleep(50); return globalThis.sharedMarker;",
-				{
-					sessionId,
-					session,
-					sessionFile,
-				},
-			),
-			executeJs("globalThis.sharedMarker ??= crypto.randomUUID(); return globalThis.sharedMarker;", {
-				sessionId,
-				session,
-				sessionFile,
-			}),
-		]);
-		const third = await executeJs("return globalThis.sharedMarker;", { sessionId, session, sessionFile });
-
-		expect(first.exitCode).toBe(0);
-		expect(second.exitCode).toBe(0);
-		expect(third.exitCode).toBe(0);
-		expect(first.output.trim()).toBe(second.output.trim());
-		expect(third.output.trim()).toBe(first.output.trim());
-	});
-
-	it("deduplicates concurrent first Python session acquisition", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-py-cold-start-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-cold-start:${crypto.randomUUID()}`;
-
-		const [first, second] = await Promise.all([
-			executePython(
-				`import asyncio, uuid
-shared_marker = globals().get("shared_marker") or str(uuid.uuid4())
-globals()["shared_marker"] = shared_marker
-await asyncio.sleep(0.05)
-print(shared_marker)`,
-				{ cwd: tempDir.path(), sessionId, sessionFile },
-			),
-			executePython(
-				`import uuid
-shared_marker = globals().get("shared_marker") or str(uuid.uuid4())
-globals()["shared_marker"] = shared_marker
-print(shared_marker)`,
-				{ cwd: tempDir.path(), sessionId, sessionFile },
-			),
-		]);
-		const third = await executePython("print(shared_marker)", { cwd: tempDir.path(), sessionId, sessionFile });
-
-		expect(first.exitCode).toBe(0);
-		expect(second.exitCode).toBe(0);
-		expect(third.exitCode).toBe(0);
-		expect(first.output.trim()).toBe(second.output.trim());
-		expect(third.output.trim()).toBe(first.output.trim());
-	});
-
-	it("splits retained Python kernels by cwd for one shared session id", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-py-cwd-");
-		const dirA = path.join(tempDir.path(), "a");
-		const dirB = path.join(tempDir.path(), "b");
-		await fs.mkdir(dirA);
-		await fs.mkdir(dirB);
-		const realDirA = await fs.realpath(dirA);
-		const realDirB = await fs.realpath(dirB);
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-cwd:${crypto.randomUUID()}`;
-
-		const first = await executePython(
-			`import os
-token = "from-a"
-print(os.getcwd())`,
-			{
-				cwd: dirA,
-				sessionId,
-				sessionFile,
-			},
-		);
-		const second = await executePython(
-			`import os
-print(os.getcwd())
-print("token" in globals())`,
-			{
-				cwd: dirB,
-				sessionId,
-				sessionFile,
-			},
-		);
-		const third = await executePython("print(token)", { cwd: dirA, sessionId, sessionFile });
-
-		expect(first.exitCode).toBe(0);
-		expect(first.output.trim()).toBe(realDirA);
-		expect(second.exitCode).toBe(0);
-		expect(second.output.trim().split("\n")).toEqual([realDirB, "False"]);
-		expect(third.exitCode).toBe(0);
-		expect(third.output.trim()).toBe("from-a");
-	});
-
-	it("interrupts timed out synchronous Python cells before they mutate shared state", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-py-sync-timeout-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-sync-timeout:${crypto.randomUUID()}`;
-
-		const timedOut = await executePython("import time\ntime.sleep(0.2)\nleaked_after_timeout = True", {
-			cwd: tempDir.path(),
-			sessionId,
-			sessionFile,
-			timeoutMs: 20,
-		});
-		await Bun.sleep(250);
-		const probe = await executePython('print("leaked_after_timeout" in globals())', {
-			cwd: tempDir.path(),
-			sessionId,
-			sessionFile,
-		});
-
-		expect(timedOut.cancelled).toBe(true);
-		expect(probe.exitCode).toBe(0);
-		expect(probe.output.trim()).toBe("False");
-	});
-
-	it("settles Python cells that raise SystemExit", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-py-system-exit-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-system-exit:${crypto.randomUUID()}`;
-
-		const result = await executePython('raise SystemExit("bye")', {
-			cwd: tempDir.path(),
-			sessionId,
-			sessionFile,
-			timeoutMs: 500,
-		});
-
-		expect(result.exitCode).toBe(1);
-		expect(result.output).toContain("SystemExit");
-		expect(result.output).toContain("bye");
-	});
-
-	it("lets a subagent inherit parent JavaScript and Python eval state", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-subagent-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const evalSessionId = `session:${sessionFile}:cwd:${tempDir.path()}`;
-		const parentSession = createToolSession(tempDir.path(), sessionFile, evalSessionId);
-		let seenJs = "";
-		let seenPy = "";
-		let capturedOptions: CreateAgentSessionOptions | undefined;
-
-		await executeJs('globalThis.parentSecret = "hello-js";', {
-			sessionId: `js:${evalSessionId}`,
-			session: parentSession,
-			sessionFile,
-		});
-		await executePython('parent_secret = "hello-py"', {
-			cwd: tempDir.path(),
-			sessionId: `python:${evalSessionId}`,
-			sessionFile,
-		});
-
-		vi.spyOn(discoveryModule, "discoverAgents").mockResolvedValue({ agents: [taskAgent], projectAgentsDir: null });
-		vi.spyOn(sdkModule, "createAgentSession").mockImplementation(async (options = {}) => {
-			capturedOptions = options;
-			const inherited = options.parentEvalSessionId;
-			if (!inherited) throw new Error("Missing parent eval session id");
-			return {
-				session: createYieldingSubagentSession(async () => {
-					const jsResult = await executeJs("return globalThis.parentSecret;", {
-						sessionId: `js:${inherited}`,
-						session: parentSession,
-						sessionFile,
-					});
-					const pyResult = await executePython("print(parent_secret)", {
-						cwd: tempDir.path(),
-						sessionId: `python:${inherited}`,
-						sessionFile,
-					});
-					seenJs = jsResult.output.trim();
-					seenPy = pyResult.output.trim();
-				}),
-				extensionsResult: {} as unknown as LoadExtensionsResult,
-				setToolUIContext: () => {},
-				eventBus: new EventBus(),
-			} satisfies CreateAgentSessionResult;
-		});
-
-		const tool = await TaskTool.create(parentSession);
-		await tool.execute("tool-call", taskParams);
-
-		expect(capturedOptions?.parentEvalSessionId).toBe(evalSessionId);
-		expect(seenJs).toBe("hello-js");
-		expect(seenPy).toBe("hello-py");
-	});
-
-	it("routes interleaved JavaScript display output to the matching run", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-js-interleave-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `js-interleave:${crypto.randomUUID()}`;
-		const session = createToolSession(tempDir.path(), sessionFile);
-
-		const first = executeJs('await Bun.sleep(80); display({ label: "A" });', {
-			sessionId,
-			session,
-			sessionFile,
-		});
-		await Bun.sleep(10);
-		const second = executeJs('display({ label: "B" });', {
-			sessionId,
-			session,
-			sessionFile,
-		});
-
-		const [firstResult, secondResult] = await Promise.all([first, second]);
-		expect(firstResult.exitCode).toBe(0);
-		expect(secondResult.exitCode).toBe(0);
-		expect(firstResult.displayOutputs).toEqual([{ type: "json", data: { label: "A" } }]);
-		expect(secondResult.displayOutputs).toEqual([{ type: "json", data: { label: "B" } }]);
-	});
-
-	it("routes interleaved Python display output to the matching run", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-py-interleave-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-interleave:${crypto.randomUUID()}`;
-
-		const first = executePython(
-			`import asyncio
-await asyncio.sleep(0.08)
-display({"label": "A"})`,
-			{
-				cwd: tempDir.path(),
-				sessionId,
-				sessionFile,
-			},
-		);
-		await Bun.sleep(10);
-		const second = executePython('display({"label": "B"})', {
-			cwd: tempDir.path(),
-			sessionId,
-			sessionFile,
-		});
-
-		const [firstResult, secondResult] = await Promise.all([first, second]);
-		expect(firstResult.exitCode).toBe(0);
-		expect(secondResult.exitCode).toBe(0);
-		expect(firstResult.displayOutputs).toEqual([{ type: "json", data: { label: "A" } }]);
-		expect(secondResult.displayOutputs).toEqual([{ type: "json", data: { label: "B" } }]);
-	});
-	it("preserves module-level singleton state across re-imports of an unchanged file", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-js-mtime-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `js-mtime:${crypto.randomUUID()}`;
-		const session = createToolSession(tempDir.path(), sessionFile);
-		const modulePath = path.join(tempDir.path(), "singleton.ts");
-		const moduleSpec = JSON.stringify(modulePath);
-		await Bun.write(
-			modulePath,
-			"let value = 0;\nexport function set(v) { value = v; }\nexport function get() { return value; }\n",
-		);
-
-		const initResult = await executeJs(`const mod = await import(${moduleSpec}); mod.set(42); return mod.get();`, {
-			sessionId,
-			session,
-			sessionFile,
-		});
-		expect(initResult.exitCode).toBe(0);
-		expect(initResult.output.trim()).toBe("42");
-
-		// Unchanged file: re-import must reuse the existing module namespace so the
-		// counter is still 42. This is the regression — the previous unconditional
-		// `delete require.cache[target]` reset singletons on every dynamic import.
-		const reuseResult = await executeJs(`const mod = await import(${moduleSpec}); return mod.get();`, {
-			sessionId,
-			session,
-			sessionFile,
-		});
-		expect(reuseResult.exitCode).toBe(0);
-		expect(reuseResult.output.trim()).toBe("42");
-
-		// Bump mtime by 5s to simulate an edit; the next import must evict the cache
-		// and re-evaluate the file, dropping the counter back to its initializer.
-		const future = new Date(Date.now() + 5_000);
-		await fs.utimes(modulePath, future, future);
-
-		const reloadResult = await executeJs(`const mod = await import(${moduleSpec}); return mod.get();`, {
-			sessionId,
-			session,
-			sessionFile,
-		});
-		expect(reloadResult.exitCode).toBe(0);
-		expect(reloadResult.output.trim()).toBe("0");
-	});
-
-	it("reloads a local re-export when a transitive dependency changes", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-js-transitive-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `js-transitive:${crypto.randomUUID()}`;
-		const session = createToolSession(tempDir.path(), sessionFile);
-		const leafPath = path.join(tempDir.path(), "leaf.ts");
-		const entryPath = path.join(tempDir.path(), "entry.ts");
-		const entrySpec = JSON.stringify(entryPath);
-		await Bun.write(leafPath, "export const value = 1;\n");
-		await Bun.write(entryPath, 'export { value } from "./leaf.ts";\n');
-
-		const initial = await executeJs(`const mod = await import(${entrySpec}); return mod.value;`, {
-			sessionId,
-			session,
-			sessionFile,
-		});
-		expect(initial.exitCode).toBe(0);
-		expect(initial.output.trim()).toBe("1");
-
-		await Bun.write(leafPath, "export const value = 2;\n");
-		const future = new Date(Date.now() + 5_000);
-		await fs.utimes(leafPath, future, future);
-
-		const reloaded = await executeJs(`const mod = await import(${entrySpec}); return mod.value;`, {
-			sessionId,
-			session,
-			sessionFile,
-		});
-		expect(reloaded.exitCode).toBe(0);
-		expect(reloaded.output.trim()).toBe("2");
-	});
-
-	it("links a cyclic local module graph without crashing", async () => {
-		// Regression: the loader used to link()+evaluate() each local module individually
-		// inside the recursive linker callback. On any import cycle that re-entered Bun's
-		// node:vm linker mid-instantiation and segfaulted the process (SIGTRAP,
-		// getImportedModule on a null record) — e.g. `await import("…/edit/streaming.ts")`,
-		// whose relative-import subtree is cyclic. The graph must now link in a single pass.
-		using tempDir = TempDir.createSync("@omp-eval-js-cycle-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `js-cycle:${crypto.randomUUID()}`;
-		const session = createToolSession(tempDir.path(), sessionFile);
-		const alphaPath = path.join(tempDir.path(), "alpha.ts");
-		const betaPath = path.join(tempDir.path(), "beta.ts");
-		const alphaSpec = JSON.stringify(alphaPath);
-		const betaSpec = JSON.stringify(betaPath);
-		await Bun.write(
-			alphaPath,
-			'import { betaName } from "./beta.ts";\nexport const alphaName = "alpha";\nexport function combined() { return alphaName + ":" + betaName; }\n',
-		);
-		await Bun.write(
-			betaPath,
-			'import { alphaName } from "./alpha.ts";\nexport const betaName = "beta";\nexport function viaAlpha() { return alphaName; }\n',
-		);
-
-		const result = await executeJs(
-			`const a = await import(${alphaSpec});\nconst b = await import(${betaSpec});\nreturn [a.combined(), b.viaAlpha()].join("|");`,
-			{ sessionId, session, sessionFile },
-		);
-
-		expect(result.exitCode).toBe(0);
-		expect(result.output.trim()).toBe("alpha:beta|alpha");
-	});
-
-	it("loads TypeScript type-only imports in cells and local modules", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-js-type-imports-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `js-type-imports:${crypto.randomUUID()}`;
-		const session = createToolSession(tempDir.path(), sessionFile);
-		const typesPath = path.join(tempDir.path(), "types.ts");
-		const valuesPath = path.join(tempDir.path(), "values.ts");
-		const entryPath = path.join(tempDir.path(), "entry.ts");
-		const typesSpec = JSON.stringify(typesPath);
-		const entrySpec = JSON.stringify(entryPath);
-		await Bun.write(typesPath, "export interface TypeOnly { value: number }\n");
-		await Bun.write(valuesPath, "export interface InlineOnly { value: number }\nexport const imported = 41;\n");
-		await Bun.write(
-			entryPath,
-			[
-				'import type { TypeOnly } from "./types.ts";',
-				'import { type InlineOnly, imported } from "./values.ts";',
-				"export const typeOnly = 1;",
-				"export const inlineType = imported;",
-				"",
-			].join("\n"),
-		);
-
-		const result = await executeJs(
-			`import type { TypeOnly } from ${typesSpec};\nconst mod = await import(${entrySpec});\nreturn mod.typeOnly + mod.inlineType;`,
-			{
-				sessionId,
-				session,
-				sessionFile,
-			},
-		);
-
-		expect(result.exitCode).toBe(0);
-		expect(result.output.trim()).toBe("42");
-	});
-
-	it("refreshes the Python tool proxy when bridge env appears after kernel warm-up", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-py-tool-proxy-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-tool-proxy:${crypto.randomUUID()}`;
-		const bridgeCalls: unknown[] = [];
-		const bridgeSession = createBridgeToolSession("bridge-ok", bridgeCalls);
-
-		const withoutBridge = await executePython(
-			'try:\n    print(tool.read({"path": "foo.txt"}))\nexcept Exception as exc:\n    print(type(exc).__name__)\n    print(str(exc))',
-			{ cwd: tempDir.path(), sessionId, sessionFile },
-		);
-		const withBridge = await executePython('print(tool.read({"path": "foo.txt"}))', {
-			cwd: tempDir.path(),
-			sessionId,
-			sessionFile,
-			toolSession: bridgeSession,
-		});
-
-		expect(withoutBridge.exitCode).toBe(0);
-		expect(withoutBridge.output).toContain("RuntimeError");
-		expect(withoutBridge.output).toContain("tool bridge is unavailable");
-		expect(withBridge.exitCode).toBe(0);
-		expect(withBridge.output.trim()).toBe("bridge-ok");
-		expect(bridgeCalls).toEqual([{ path: "foo.txt", _i: "py prelude" }]);
-	});
-});
diff --git a/packages/coding-agent/src/lsp/client.ts b/packages/coding-agent/src/lsp/client.ts
index cf872019c..3080fc083 100644
--- a/packages/coding-agent/src/lsp/client.ts
+++ b/packages/coding-agent/src/lsp/client.ts
@@ -438,6 +438,7 @@ export const WARMUP_TIMEOUT_MS = 5000;
 const RUST_ANALYZER_WORKSPACE_READY_TIMEOUT_MS = 5_000;
 const RUST_ANALYZER_WORKSPACE_READY_POLL_MS = 100;
 const RUST_ANALYZER_WORKSPACE_READY_SETTLE_MS = 2_000;
+const RUST_ANALYZER_STATUS_REQUEST_TIMEOUT_MS = 1_000;
 const rustAnalyzerReadyClients = new WeakSet<LspClient>();
 
 function commandBasename(command: string): string {
@@ -462,29 +463,34 @@ async function waitForRustAnalyzerWorkspace(client: LspClient, signal?: AbortSig
 	if (rustAnalyzerReadyClients.has(client)) {
 		return;
 	}
+	const timings = client.config.workspaceReadyTimings;
+	const timeoutMs = timings?.timeoutMs ?? RUST_ANALYZER_WORKSPACE_READY_TIMEOUT_MS;
+	const pollMs = timings?.pollMs ?? RUST_ANALYZER_WORKSPACE_READY_POLL_MS;
+	const settleMs = timings?.settleMs ?? RUST_ANALYZER_WORKSPACE_READY_SETTLE_MS;
+	const statusRequestTimeoutMs = timings?.statusRequestTimeoutMs ?? RUST_ANALYZER_STATUS_REQUEST_TIMEOUT_MS;
 	const started = Date.now();
-	const deadline = started + RUST_ANALYZER_WORKSPACE_READY_TIMEOUT_MS;
+	const deadline = started + timeoutMs;
 	while (true) {
 		throwIfAborted(signal);
 		let status: unknown;
 		try {
-			status = await sendRequest(client, "rust-analyzer/analyzerStatus", {}, signal, 1_000);
+			status = await sendRequest(client, "rust-analyzer/analyzerStatus", {}, signal, statusRequestTimeoutMs);
 		} catch (err) {
 			if (!isRustAnalyzerStatusTimeout(err) || Date.now() >= deadline) {
 				return;
 			}
-			await Bun.sleep(RUST_ANALYZER_WORKSPACE_READY_POLL_MS);
+			await Bun.sleep(pollMs);
 			continue;
 		}
 		const ready = typeof status === "string" && !status.startsWith("No workspaces");
-		if (ready && Date.now() - started >= RUST_ANALYZER_WORKSPACE_READY_SETTLE_MS) {
+		if (ready && Date.now() - started >= settleMs) {
 			rustAnalyzerReadyClients.add(client);
 			return;
 		}
 		if (Date.now() >= deadline) {
 			return;
 		}
-		await Bun.sleep(RUST_ANALYZER_WORKSPACE_READY_POLL_MS);
+		await Bun.sleep(pollMs);
 	}
 }
 
diff --git a/packages/coding-agent/src/lsp/types.ts b/packages/coding-agent/src/lsp/types.ts
index 96b6a1f6d..42028047a 100644
--- a/packages/coding-agent/src/lsp/types.ts
+++ b/packages/coding-agent/src/lsp/types.ts
@@ -356,6 +356,16 @@ export interface ServerConfig {
 	disabled?: boolean;
 	/** Per-server warmup timeout in milliseconds. Overrides the global WARMUP_TIMEOUT_MS for this server during startup. */
 	warmupTimeoutMs?: number;
+	/**
+	 * Per-server overrides for rust-analyzer workspace-ready polling. When omitted, the module
+	 * defaults are used. Primarily a tuning/test seam to bound the multi-second settle window.
+	 */
+	workspaceReadyTimings?: {
+		timeoutMs?: number;
+		pollMs?: number;
+		settleMs?: number;
+		statusRequestTimeoutMs?: number;
+	};
 	capabilities?: ServerCapabilities;
 	/** If true, this is a linter/formatter server (e.g., Biome) - used only for diagnostics/actions, not type intelligence */
 	isLinter?: boolean;
diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index 8c3fbd1b4..253998228 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -846,7 +846,15 @@ export class InputController {
 				child.setExpanded(expanded);
 			}
 		}
-		this.ctx.ui.requestRender(false, { allowUnknownViewportMutation: true });
+		// Toggling expansion mutates every block, but on ED3-risk terminals the
+		// transcript freezes a snapshot of each block once it scrolls past the live
+		// region (committed native scrollback is immutable there). A plain repaint
+		// replays those stale snapshots, so the toggle appears to do nothing above
+		// the live block. resetDisplay() invalidates the snapshots and forces a
+		// full clear + replay — the keyboard-accessible resize-reset equivalent —
+		// which is the only path that re-emits the whole transcript at its new
+		// heights.
+		this.ctx.ui.resetDisplay();
 	}
 
 	toggleThinkingBlockVisibility(): void {
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index c568d09ea..732af473c 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -984,9 +984,18 @@ export class TUI extends Container {
 	 * scrollback. This is the keyboard-accessible equivalent of the resize reset:
 	 * no queued diff frame or terminal scrollback probe can downgrade it to a
 	 * viewport-only repaint.
+	 *
+	 * Invalidates every component first so the replay reflects current state. A
+	 * geometry-driven reset thaws frozen scrollback snapshots implicitly (the new
+	 * width misses every cached snapshot), but a same-width reset would otherwise
+	 * replay stale snapshots — leaving host-frozen blocks (e.g. a transcript whose
+	 * committed rows are immutable on ED3-risk terminals) showing pre-mutation
+	 * content. Invalidation is the generic signal those containers use to retire
+	 * their snapshots, which is exactly what a user-driven display reset wants.
 	 */
 	resetDisplay(): void {
 		if (this.#stopped) return;
+		this.invalidate();
 		this.#prepareForcedRender(!isMultiplexerSession(), true);
 		this.#resizeEventPending = true;
 		this.#renderRequested = false;

From 20d19e80020d79ad3bc2a26f88859602560f5a8d Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:09:04 +0200
Subject: [PATCH 048/181] test: replaced blind sleeps with shared fixtures and
 condition polling

- Shared immutable model registries and auth storage via beforeAll/afterAll.
- Swapped fixed-delay settle sleeps for predicate polling and signals.
- Stubbed network/timers to drop wall-clock waits in registry and history tests.
- Added resetDisplay invalidation tests and startup-timing breakdown lines.
---
 .../src/eval/__tests__/agent-bridge.test.ts   |  56 ++--
 .../test/agent-session-concurrent.test.ts     |  23 +-
 .../agent-session-context-promotion.test.ts   |  30 +-
 .../test/agent-session-handoff.test.ts        |  93 ++++--
 .../agent-session-model-persistence.test.ts   |  45 +--
 ...nt-session-openai-responses-replay.test.ts |  91 +++---
 .../test/agent-session-python-cleanup.test.ts |   3 +
 .../test/agent-session-retry-fallback.test.ts |  26 +-
 .../test/autoresearch-tools.test.ts           |  34 +--
 .../coding-agent/test/bash-executor.test.ts   |  44 ++-
 .../test/extensions-runner.test.ts            |  23 +-
 .../test/goals/goal-mode-integration.test.ts  |  45 ++-
 .../test/interactive-mode-plan-review.test.ts |   2 -
 .../keybindings-selector-navigation.test.ts   |  13 +-
 .../test/mcp-reconnect-storm.test.ts          |  17 +-
 .../model-registry-runtime-provider.test.ts   |  12 +-
 .../coding-agent/test/model-registry.test.ts  |   5 +-
 .../components/transcript-container.test.ts   |  19 ++
 .../input-controller-tool-expansion.test.ts   |  11 +-
 .../test/plan-mode-thinking-level.test.ts     |   7 +-
 .../sdk-async-job-manager-singleton.test.ts   |  25 +-
 .../sdk-credential-disabled-bridge.test.ts    |  13 +-
 .../test/sdk-mcp-discovery.test.ts            |  28 +-
 .../test/sdk-model-selection.test.ts          |  23 +-
 .../test/sdk-session-isolation.test.ts        |  25 +-
 packages/coding-agent/test/sdk-skills.test.ts |  28 +-
 .../test/sdk-tool-activation.test.ts          | 152 +++-------
 packages/coding-agent/test/tools.test.ts      |  31 +-
 .../test/tools/approval-mode.test.ts          | 279 +++++++-----------
 .../test/tools/conflict-integration.test.ts   |   6 +-
 .../test/tools/fetch-jina-stall.test.ts       |  17 +-
 packages/coding-agent/test/tools/gh.test.ts   |  51 +++-
 .../test/tools/lsp-regressions.test.ts        |   4 +
 packages/tui/test/render-regressions.test.ts  |  54 ++++
 packages/utils/CHANGELOG.md                   |   4 +
 packages/utils/src/logger.ts                  |  15 +-
 36 files changed, 854 insertions(+), 500 deletions(-)

diff --git a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
index dd66f44cc..838ed6c1a 100644
--- a/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
+++ b/packages/coding-agent/src/eval/__tests__/agent-bridge.test.ts
@@ -377,18 +377,6 @@ describe("agent() through eval runtimes", () => {
 			singleResult(options, { output: "hello from python" }),
 		);
 
-		const probe = await executePython('print("probe")', {
-			cwd: tempDir.path(),
-			sessionId: `${sessionId}:probe`,
-			sessionFile,
-			kernelMode: "per-call",
-		});
-		if (probe.exitCode === undefined && probe.cancelled) {
-			expect(probe.output).toBe("");
-			return;
-		}
-		expect(probe.exitCode).toBe(0);
-
 		const result = await executePython('print(agent("hi"))', {
 			cwd: tempDir.path(),
 			sessionId,
@@ -396,6 +384,10 @@ describe("agent() through eval runtimes", () => {
 			kernelMode: "per-call",
 			toolSession: session,
 		});
+		if (result.exitCode === undefined && result.cancelled) {
+			expect(result.output).toBe("");
+			return; // kernel unavailable in this environment
+		}
 
 		expect(result.exitCode).toBe(0);
 		expect(result.output.trim()).toBe("hello from python");
@@ -424,22 +416,14 @@ describe("agent() through eval runtimes", () => {
 			}
 		});
 
-		const probe = await executePython('print("probe")', {
-			cwd: tempDir.path(),
-			sessionId: `${sessionId}:probe`,
-			sessionFile,
-			kernelMode: "per-call",
-		});
-		if (probe.exitCode === undefined && probe.cancelled) {
-			expect(probe.output).toBe("");
-			return;
-		}
-		expect(probe.exitCode).toBe(0);
-
 		const result = await executePython(
 			'import json\nprint(json.dumps(parallel([lambda n=n: agent(n) for n in ["a", "b", "c", "d"]])))',
 			{ cwd: tempDir.path(), sessionId, sessionFile, kernelMode: "per-call", toolSession: session },
 		);
+		if (result.exitCode === undefined && result.cancelled) {
+			expect(result.output).toBe("");
+			return; // kernel unavailable in this environment
+		}
 
 		expect(result.exitCode).toBe(0);
 		expect(JSON.parse(result.output.trim())).toEqual(["a", "b", "c", "d"]);
@@ -463,7 +447,14 @@ describe("agent() through eval runtimes", () => {
 		// The host must respond the instant the cell aborts so the kernel can
 		// unwind via KeyboardInterrupt instead of being hard-killed (which used to
 		// surface "[kernel] Python kernel shutdown" and lose all session state).
+		let inFlight = 0;
+		let markSaturated: (() => void) | undefined;
+		const saturated = new Promise<void>(resolve => {
+			markSaturated = resolve;
+		});
 		vi.spyOn(taskExecutor, "runSubprocess").mockImplementation(async options => {
+			// task.maxConcurrency=6 → six bridge calls block at once; signal then.
+			if (++inFlight >= 6) markSaturated?.();
 			await Bun.sleep(9000); // deliberately ignores options.signal
 			return singleResult(options, { output: options.assignment ?? "" });
 		});
@@ -483,8 +474,9 @@ describe("agent() through eval runtimes", () => {
 		expect(seed.exitCode).toBe(0);
 
 		const ac = new AbortController();
-		// Abort ~1s in, after the worker threads are blocked in their bridge calls.
-		setTimeout(() => ac.abort(new Error("external interrupt")), 1000);
+		// Abort the instant all six worker threads are confirmed blocked in their
+		// bridge calls (condition-driven) instead of waiting a fixed wall second.
+		void saturated.then(() => ac.abort(new Error("external interrupt")));
 
 		const start = Date.now();
 		const result = await executePython(
@@ -619,12 +611,12 @@ describe("agent() through eval runtimes", () => {
 		// of its own. The bridge pause must make that delegated time invisible to
 		// the watchdog.
 		vi.spyOn(taskExecutor, "runSubprocess").mockImplementation(async options => {
-			await Bun.sleep(200);
+			await Bun.sleep(40);
 			return singleResult(options, { output: "done" });
 		});
 
 		const ops: string[] = [];
-		using idle = new IdleTimeout(60);
+		using idle = new IdleTimeout(20);
 		const result = await runEvalAgent(
 			{ prompt: "investigate" },
 			{
@@ -642,7 +634,7 @@ describe("agent() through eval runtimes", () => {
 		expect(ops).toEqual([EVAL_TIMEOUT_PAUSE_OP, EVAL_TIMEOUT_RESUME_OP]);
 		expect(idle.signal.aborted).toBe(false);
 
-		await Bun.sleep(90);
+		await Bun.sleep(60);
 		expect(idle.signal.aborted).toBe(true);
 	});
 
@@ -655,7 +647,7 @@ describe("agent() through eval runtimes", () => {
 		// They render as status, but timeout accounting is controlled only by the
 		// bridge pause/resume events.
 		vi.spyOn(taskExecutor, "runSubprocess").mockImplementation(async options => {
-			for (let i = 0; i < 40; i++) {
+			for (let i = 0; i < 20; i++) {
 				options.onProgress?.({
 					index: options.index,
 					id: options.id,
@@ -672,13 +664,13 @@ describe("agent() through eval runtimes", () => {
 					cost: 0,
 					durationMs: i * 10,
 				});
-				await Bun.sleep(10);
+				await Bun.sleep(5);
 			}
 			return singleResult(options, { output: "done" });
 		});
 
 		const ops: string[] = [];
-		using idle = new IdleTimeout(80);
+		using idle = new IdleTimeout(40);
 		const result = await runEvalAgent(
 			{ prompt: "investigate" },
 			{
diff --git a/packages/coding-agent/test/agent-session-concurrent.test.ts b/packages/coding-agent/test/agent-session-concurrent.test.ts
index f03cbf039..a5298263a 100644
--- a/packages/coding-agent/test/agent-session-concurrent.test.ts
+++ b/packages/coding-agent/test/agent-session-concurrent.test.ts
@@ -6,6 +6,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { scheduler } from "node:timers/promises";
 import { Agent, AgentBusyError, type AgentTool } from "@oh-my-pi/pi-agent-core";
 import { type AssistantMessage, getBundledModel, type Message, type ToolCall } from "@oh-my-pi/pi-ai";
 import { createMockModel } from "@oh-my-pi/pi-ai/providers/mock";
@@ -25,6 +26,19 @@ import { createAssistantMessage } from "./helpers/agent-session-setup";
 
 // Mock stream that mimics AssistantMessageEventStream
 
+// AgentSession schedules its TTSR retry and context-promotion continuations
+// through `scheduler.wait(delayMs, { signal })` (node:timers/promises), with
+// blind 50ms/100ms "settle" delays. Tests that drive a continuation to
+// completion would otherwise pay that wall-clock time on every run. This spy
+// collapses the blind delay to a single macrotask hop (`scheduler.wait(0)`)
+// while preserving the real abort-signal semantics, so the continuation still
+// fires only after the aborted/overflowed turn has been recorded. Each test
+// that opts in must run inside a block whose afterEach restores mocks.
+const originalSchedulerWait = scheduler.wait.bind(scheduler);
+function collapseSchedulerSettleDelays(): void {
+	vi.spyOn(scheduler, "wait").mockImplementation((_delayMs, options) => originalSchedulerWait(0, options));
+}
+
 describe("AgentSession concurrent prompt guard", () => {
 	let session: AgentSession;
 	let tempDir: string;
@@ -101,7 +115,7 @@ describe("AgentSession concurrent prompt guard", () => {
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() < deadline) {
 			if (predicate()) return;
-			await Bun.sleep(10);
+			await Bun.sleep(1);
 		}
 
 		throw new Error("Timed out waiting for condition");
@@ -595,13 +609,14 @@ describe("AgentSession TTSR resume gate", () => {
 		if (tempDir && fs.existsSync(tempDir)) {
 			fs.rmSync(tempDir, { recursive: true });
 		}
+		vi.restoreAllMocks();
 	});
 
 	async function waitFor(predicate: () => boolean, timeoutMs = 500): Promise<void> {
 		const deadline = Date.now() + timeoutMs;
 		while (Date.now() < deadline) {
 			if (predicate()) return;
-			await Bun.sleep(10);
+			await Bun.sleep(1);
 		}
 
 		throw new Error("Timed out waiting for condition");
@@ -674,6 +689,7 @@ describe("AgentSession TTSR resume gate", () => {
 	}
 
 	it("prompt() blocks until TTSR interrupt continuation completes", async () => {
+		collapseSchedulerSettleDelays();
 		const model = getBundledModel("anthropic", "claude-sonnet-4-5")!;
 		let streamCallCount = 0;
 		let continuationCompleted = false;
@@ -734,6 +750,7 @@ describe("AgentSession TTSR resume gate", () => {
 	});
 
 	it("relativizes the rule file path in the TTSR interrupt injection (no absolute leak)", async () => {
+		collapseSchedulerSettleDelays();
 		const model = getBundledModel("anthropic", "claude-sonnet-4-5")!;
 		let streamCallCount = 0;
 
@@ -946,6 +963,7 @@ describe("AgentSession TTSR resume gate", () => {
 	});
 
 	it("prompt() waits for TTSR continuation with tool calls to finish", async () => {
+		collapseSchedulerSettleDelays();
 		const model = getBundledModel("anthropic", "claude-sonnet-4-5")!;
 		let streamCallCount = 0;
 		let toolExecutionFinished = false;
@@ -1306,6 +1324,7 @@ describe("AgentSession TTSR resume gate", () => {
 	});
 
 	it("prompt() waits for context-promotion continuation to finish", async () => {
+		collapseSchedulerSettleDelays();
 		const authStorage = await AuthStorage.create(path.join(tempDir, "testauth-promo.db"));
 		authStorages.push(authStorage);
 		authStorage.setRuntimeApiKey("openai-codex", "test-key");
diff --git a/packages/coding-agent/test/agent-session-context-promotion.test.ts b/packages/coding-agent/test/agent-session-context-promotion.test.ts
index dcbe8af92..06347689b 100644
--- a/packages/coding-agent/test/agent-session-context-promotion.test.ts
+++ b/packages/coding-agent/test/agent-session-context-promotion.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "bun:test";
 import * as path from "node:path";
 import { Agent } from "@oh-my-pi/pi-agent-core";
 import type { AssistantMessage, Model, ProviderSessionState } from "@oh-my-pi/pi-ai";
@@ -15,19 +15,26 @@ describe("AgentSession context promotion", () => {
 	let modelRegistry: ModelRegistry;
 	let authStorage: AuthStorage;
 
-	beforeEach(async () => {
+	beforeAll(async () => {
+		// ModelRegistry eagerly loads the immutable bundled model catalog in its
+		// constructor (~100ms). The catalog and auth fixture never change between
+		// tests here (tests only read models and add benign extra runtime keys),
+		// so build them once instead of paying ~950ms across the 9 cases.
 		tempDir = TempDir.createSync("@pi-context-promotion-");
 		authStorage = await AuthStorage.create(path.join(tempDir.path(), "testauth.db"));
 		authStorage.setRuntimeApiKey("openai-codex", "test-key");
 		modelRegistry = new ModelRegistry(authStorage);
 	});
 
+	afterAll(() => {
+		authStorage.close();
+		tempDir.removeSync();
+	});
+
 	afterEach(async () => {
 		if (session) {
 			await session.dispose();
 		}
-		authStorage.close();
-		tempDir.removeSync();
 	});
 
 	function createOverflowMessage(
@@ -113,6 +120,17 @@ describe("AgentSession context promotion", () => {
 		throw new Error("Timed out waiting for condition");
 	}
 
+	// Deterministically drain the fire-and-forget `agent_end` handler that
+	// `emitExternalEvent` dispatches. The handler's terminal maintenance work
+	// (`#checkCompaction`) is microtask-based on the no-promotion paths, so a
+	// single macrotask turn fully flushes it; `waitForIdle` then settles any
+	// tracked continuation. Used by the negative tests, which assert that *no*
+	// promotion happened and therefore need the handler to have actually run.
+	async function settle(): Promise<void> {
+		await new Promise(resolve => setTimeout(resolve, 0));
+		await session.waitForIdle();
+	}
+
 	it("promotes to a larger-context model on overflow and clears codex websocket session state", async () => {
 		const sparkModel = modelRegistry.find("openai-codex", "gpt-5.3-codex-spark");
 		const codexModel = modelRegistry.find("openai-codex", "gpt-5.5");
@@ -390,7 +408,7 @@ describe("AgentSession context promotion", () => {
 		session.agent.emitExternalEvent({ type: "message_end", message: overflowMessage });
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [overflowMessage] });
 
-		await Bun.sleep(30);
+		await settle();
 
 		expect(session.model?.provider).toBe(sparkModel.provider);
 		expect(session.model?.id).toBe(sparkModel.id);
@@ -472,7 +490,7 @@ describe("AgentSession context promotion", () => {
 		session.agent.emitExternalEvent({ type: "message_end", message: staleIncomplete });
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [staleIncomplete] });
 
-		await Bun.sleep(30);
+		await settle();
 
 		expect(session.model?.provider).toBe(codexModel.provider);
 		expect(session.model?.id).toBe(codexModel.id);
diff --git a/packages/coding-agent/test/agent-session-handoff.test.ts b/packages/coding-agent/test/agent-session-handoff.test.ts
index e90506b33..3ecb612aa 100644
--- a/packages/coding-agent/test/agent-session-handoff.test.ts
+++ b/packages/coding-agent/test/agent-session-handoff.test.ts
@@ -1,8 +1,8 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
 import * as path from "node:path";
 import { Agent } from "@oh-my-pi/pi-agent-core";
 import * as compactionModule from "@oh-my-pi/pi-agent-core/compaction";
-import type { AssistantMessage, ToolCall } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, Model, ToolCall } from "@oh-my-pi/pi-ai";
 import { getBundledModel } from "@oh-my-pi/pi-ai/models";
 import { createMockModel } from "@oh-my-pi/pi-ai/providers/mock";
 import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
@@ -14,26 +14,67 @@ import { SessionManager } from "@oh-my-pi/pi-coding-agent/session/session-manage
 import { TempDir } from "@oh-my-pi/pi-utils";
 
 describe("AgentSession handoff", () => {
+	// Immutable across the whole file: the model registry's synchronous bundled-model
+	// load dominates per-test setup (~100ms each), and the auth store + bundled model
+	// never change. Build them once. Per-test mutable state (session, session file,
+	// emitted events) is rebuilt in beforeEach.
+	let sharedDir: TempDir;
+	let authStorage: AuthStorage;
+	let modelRegistry: ModelRegistry;
+	let model: Model;
+
 	let tempDir: TempDir;
 	let session: AgentSession;
 	let sessionManager: SessionManager;
-	let authStorage: AuthStorage;
-	let modelRegistry: ModelRegistry;
 	let events: AgentSessionEvent[];
 
+	/** Poll `predicate` until it holds (returns as soon as the state is reached) or the
+	 *  deadline elapses. Replaces blind settle sleeps for tests with a positive signal. */
+	async function waitFor(predicate: () => boolean, timeoutMs = 1_000): Promise<void> {
+		const deadline = Date.now() + timeoutMs;
+		while (!predicate()) {
+			if (Date.now() >= deadline) {
+				throw new Error("Timed out waiting for condition");
+			}
+			await Bun.sleep(1);
+		}
+	}
+
+	/** Drain post-turn maintenance deterministically for negative tests (those proving
+	 *  maintenance did NOT run, where there is no positive signal to poll on). Post-turn
+	 *  work is scheduled fire-and-forget: a single event-loop turn lets the handler run to
+	 *  its decision and register any compaction pass as a tracked post-prompt task, then
+	 *  `waitForIdle()` drains that task to completion. */
+	async function drainMaintenance(): Promise<void> {
+		await Bun.sleep(0);
+		await session.waitForIdle();
+	}
+
+	beforeAll(async () => {
+		sharedDir = TempDir.createSync("@pi-handoff-shared-");
+		authStorage = await AuthStorage.create(path.join(sharedDir.path(), "testauth.db"));
+		authStorage.setRuntimeApiKey("anthropic", "test-key");
+		modelRegistry = new ModelRegistry(authStorage);
+
+		const bundled = getBundledModel("anthropic", "claude-sonnet-4-5");
+		if (!bundled) {
+			throw new Error("Expected built-in anthropic model to exist");
+		}
+		model = bundled;
+	});
+
+	afterAll(async () => {
+		authStorage.close();
+		try {
+			await sharedDir.remove();
+		} catch {}
+	});
+
 	beforeEach(async () => {
 		tempDir = TempDir.createSync("@pi-handoff-");
-		authStorage = await AuthStorage.create(path.join(tempDir.path(), "testauth.db"));
-		authStorage.setRuntimeApiKey("anthropic", "test-key");
-		modelRegistry = new ModelRegistry(authStorage);
 		sessionManager = SessionManager.create(tempDir.path(), tempDir.path());
 		events = [];
 
-		const model = getBundledModel("anthropic", "claude-sonnet-4-5");
-		if (!model) {
-			throw new Error("Expected built-in anthropic model to exist");
-		}
-
 		const agent = new Agent({
 			initialState: {
 				model,
@@ -85,7 +126,6 @@ describe("AgentSession handoff", () => {
 		if (session) {
 			await session.dispose();
 		}
-		authStorage.close();
 		try {
 			await tempDir.remove();
 		} catch {}
@@ -97,7 +137,7 @@ describe("AgentSession handoff", () => {
 		const generateHandoffSpy = vi.spyOn(compactionModule, "generateHandoff").mockResolvedValue(handoffText);
 
 		const result = await session.handoff();
-		await Bun.sleep(20);
+		await drainMaintenance();
 
 		expect(generateHandoffSpy).toHaveBeenCalledTimes(1);
 		expect(result?.document).toBe(handoffText);
@@ -123,7 +163,11 @@ describe("AgentSession handoff", () => {
 		});
 
 		await session.prompt("pending prompt ".repeat(120));
-		await Bun.sleep(20);
+		await waitFor(
+			() =>
+				compactSpy.mock.calls.length === 1 &&
+				events.some(event => event.type === "auto_compaction_end" && event.aborted === false),
+		);
 
 		expect(compactSpy).toHaveBeenCalledTimes(1);
 		expect(promptSpy).toHaveBeenCalledTimes(1);
@@ -177,7 +221,7 @@ describe("AgentSession handoff", () => {
 			isError: false,
 		});
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [assistantMessage] });
-		await Bun.sleep(20);
+		await drainMaintenance();
 
 		expect(handoffSpy).not.toHaveBeenCalled();
 		expect(events.filter(event => event.type === "auto_compaction_start")).toHaveLength(0);
@@ -259,7 +303,7 @@ describe("AgentSession handoff", () => {
 		const handoffSpy = vi.spyOn(session, "handoff");
 		session.agent.emitExternalEvent({ type: "message_end", message: assistantMessage });
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [assistantMessage] });
-		await Bun.sleep(20);
+		await drainMaintenance();
 
 		expect(handoffSpy).not.toHaveBeenCalled();
 		expect(events.filter(event => event.type === "auto_compaction_start")).toHaveLength(0);
@@ -307,7 +351,7 @@ describe("AgentSession handoff", () => {
 
 		session.agent.emitExternalEvent({ type: "message_end", message: overflowAssistant });
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [overflowAssistant] });
-		await Bun.sleep(20);
+		await waitFor(() => events.filter(event => event.type === "auto_compaction_end").length === 1);
 
 		expect(handoffSpy).not.toHaveBeenCalled();
 		const startEvents = events.filter(event => event.type === "auto_compaction_start");
@@ -352,7 +396,11 @@ describe("AgentSession handoff", () => {
 
 		session.agent.emitExternalEvent({ type: "message_end", message: assistantMessage });
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [assistantMessage] });
-		await Bun.sleep(20);
+		await waitFor(
+			() =>
+				handoffSpy.mock.calls.length === 1 &&
+				events.filter(event => event.type === "auto_compaction_end").length === 1,
+		);
 
 		expect(handoffSpy).toHaveBeenCalledTimes(1);
 		expect(handoffSpy).toHaveBeenCalledWith(expect.stringContaining("Threshold-triggered maintenance"), {
@@ -500,7 +548,8 @@ describe("AgentSession handoff", () => {
 
 		session.agent.emitExternalEvent({ type: "message_end", message: assistantMessage });
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [assistantMessage] });
-		await Bun.sleep(20);
+		await waitFor(() => handoffSpy.mock.calls.length === 1);
+		await session.waitForIdle();
 
 		expect(handoffSpy).toHaveBeenCalledTimes(1);
 		// The bug surfaced as agent.continue() racing the deferred handoff. With the fix,
@@ -554,7 +603,7 @@ describe("AgentSession handoff", () => {
 		session.agent.emitExternalEvent({ type: "message_end", message: assistantMessage });
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [assistantMessage] });
 		// Let the deferred handoff post-prompt task enter the generateHandoff await.
-		await Bun.sleep(20);
+		await waitFor(() => session.isGeneratingHandoff);
 		expect(generateHandoffSpy).toHaveBeenCalledTimes(1);
 		expect(session.isGeneratingHandoff).toBe(true);
 
@@ -601,7 +650,7 @@ describe("AgentSession handoff", () => {
 
 		session.agent.emitExternalEvent({ type: "message_end", message: assistantMessage });
 		session.agent.emitExternalEvent({ type: "agent_end", messages: [assistantMessage] });
-		await Bun.sleep(20);
+		await waitFor(() => events.filter(event => event.type === "auto_compaction_end").length === 1);
 
 		expect(handoffSpy).toHaveBeenCalledTimes(1);
 		const endEvents = events.filter(event => event.type === "auto_compaction_end");
diff --git a/packages/coding-agent/test/agent-session-model-persistence.test.ts b/packages/coding-agent/test/agent-session-model-persistence.test.ts
index 7b741027a..76f089355 100644
--- a/packages/coding-agent/test/agent-session-model-persistence.test.ts
+++ b/packages/coding-agent/test/agent-session-model-persistence.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
 import * as path from "node:path";
 import { Agent } from "@oh-my-pi/pi-agent-core";
 import { type Api, Effort, getBundledModel, type Model } from "@oh-my-pi/pi-ai";
@@ -18,7 +18,24 @@ describe("AgentSession model persistence", () => {
 	let tempDir: TempDir;
 	let session: AgentSession | undefined;
 	let sessionSettings: Settings;
-	const authStorages: AuthStorage[] = [];
+	// Auth storage (SQLite DB) and the model registry are immutable across these tests:
+	// every test sets the same anthropic runtime key and only ever reads the bundled model
+	// list. Building them once avoids ~12 SQLite opens + registry constructions.
+	let sharedDir: TempDir;
+	let sharedAuthStorage: AuthStorage;
+	let sharedModelRegistry: ModelRegistry;
+
+	beforeAll(async () => {
+		sharedDir = TempDir.createSync("@pi-model-persistence-shared-");
+		sharedAuthStorage = await AuthStorage.create(path.join(sharedDir.path(), "auth.db"));
+		sharedAuthStorage.setRuntimeApiKey("anthropic", "test-key");
+		sharedModelRegistry = new ModelRegistry(sharedAuthStorage, path.join(sharedDir.path(), "models.yml"));
+	});
+
+	afterAll(() => {
+		sharedAuthStorage.close();
+		sharedDir.removeSync();
+	});
 
 	beforeEach(() => {
 		tempDir = TempDir.createSync("@pi-model-persistence-");
@@ -29,9 +46,6 @@ describe("AgentSession model persistence", () => {
 			await session.dispose();
 			session = undefined;
 		}
-		for (const authStorage of authStorages.splice(0)) {
-			authStorage.close();
-		}
 		tempDir.removeSync();
 	});
 
@@ -84,13 +98,7 @@ describe("AgentSession model persistence", () => {
 		modelRoles?: Record<string, string>;
 		persist?: boolean;
 	}): Promise<{ modelRegistry: ModelRegistry; settings: Settings; session: AgentSession }> {
-		const authStorage = await AuthStorage.create(path.join(tempDir.path(), `testauth-${authStorages.length}.db`));
-		authStorages.push(authStorage);
-		authStorage.setRuntimeApiKey("anthropic", "test-key");
-		const modelRegistry = new ModelRegistry(
-			authStorage,
-			path.join(tempDir.path(), `models-${authStorages.length}.yml`),
-		);
+		const modelRegistry = sharedModelRegistry;
 		const model =
 			options?.initialModel ??
 			options?.selectInitialModel?.(modelRegistry.getAvailable()) ??
@@ -118,7 +126,7 @@ describe("AgentSession model persistence", () => {
 		session = new AgentSession({
 			agent,
 			sessionManager: options?.persist
-				? SessionManager.create(tempDir.path(), path.join(tempDir.path(), `active-${authStorages.length}`))
+				? SessionManager.create(tempDir.path(), path.join(tempDir.path(), "active"))
 				: SessionManager.inMemory(),
 			settings: sessionSettings,
 			modelRegistry,
@@ -131,19 +139,12 @@ describe("AgentSession model persistence", () => {
 		targetSessionFile: string,
 		settings: Settings = Settings.isolated(),
 	): Promise<CreateAgentSessionResult> {
-		const authStorage = await AuthStorage.create(path.join(tempDir.path(), `testauth-${authStorages.length}.db`));
-		authStorages.push(authStorage);
-		authStorage.setRuntimeApiKey("anthropic", "test-key");
-		const modelRegistry = new ModelRegistry(
-			authStorage,
-			path.join(tempDir.path(), `models-${authStorages.length}.yml`),
-		);
 		const sessionManager = await SessionManager.open(targetSessionFile, path.join(tempDir.path(), "startup"));
 		const result = await createAgentSession({
 			cwd: tempDir.path(),
 			agentDir: tempDir.path(),
-			authStorage,
-			modelRegistry,
+			authStorage: sharedAuthStorage,
+			modelRegistry: sharedModelRegistry,
 			sessionManager,
 			settings,
 			disableExtensionDiscovery: true,
diff --git a/packages/coding-agent/test/agent-session-openai-responses-replay.test.ts b/packages/coding-agent/test/agent-session-openai-responses-replay.test.ts
index 7fa2c98ed..fd5452369 100644
--- a/packages/coding-agent/test/agent-session-openai-responses-replay.test.ts
+++ b/packages/coding-agent/test/agent-session-openai-responses-replay.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it, vi } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -12,8 +12,11 @@ import type {
 	Usage,
 } from "@oh-my-pi/pi-ai/types";
 import { createOpenAIResponsesHistoryPayload } from "@oh-my-pi/pi-ai/utils";
+import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
+import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import { createAgentSession } from "@oh-my-pi/pi-coding-agent/sdk";
 import type { AgentSession } from "@oh-my-pi/pi-coding-agent/session/agent-session";
-import type { AuthStorage } from "@oh-my-pi/pi-coding-agent/session/auth-storage";
+import { AuthStorage } from "@oh-my-pi/pi-coding-agent/session/auth-storage";
 import {
 	type SessionEntry,
 	SessionManager,
@@ -209,20 +212,21 @@ async function createPersistedSession(
 	return { sessionFile, treeTargetId: result?.treeTargetId };
 }
 
+// ModelRegistry construction loads the bundled model catalog plus the on-disk
+// cache (~100ms) and dominated this file's runtime when rebuilt once per test.
+// The registry and its pinned AuthStorage are immutable across these tests (none
+// mutate the catalog or stored credentials), so a single instance is shared via
+// createAgentSession's `modelRegistry`/`authStorage` seam. The registry pins
+// itself to its AuthStorage, so both MUST be the same shared instances.
+let sharedModelRegistry: ModelRegistry;
+let sharedRegistryDir: string;
+
 async function createSessionHarness(
 	tempDir: string,
 	sessionManager: SessionManager,
 	options: { provider?: Parameters<typeof getBundledModel>[0]; modelId?: string } = {},
-): Promise<{ session: AgentSession; authStorage: AuthStorage }> {
+): Promise<{ session: AgentSession }> {
 	const { provider = "openai", modelId = "gpt-5-mini" } = options;
-	const [{ createAgentSession }, { Settings }, { AuthStorage }] = await Promise.all([
-		import("@oh-my-pi/pi-coding-agent/sdk"),
-		import("@oh-my-pi/pi-coding-agent/config/settings"),
-		import("@oh-my-pi/pi-coding-agent/session/auth-storage"),
-	]);
-	const authStorage = await AuthStorage.create(path.join(tempDir, `testauth-${Snowflake.next()}.db`));
-	authStorage.setRuntimeApiKey("openai", "test-key");
-	authStorage.setRuntimeApiKey("openai-codex", "test-key");
 	const model = getBundledModel(provider, modelId);
 	if (!model) {
 		throw new Error(`Expected bundled test model ${provider}/${modelId}`);
@@ -231,7 +235,8 @@ async function createSessionHarness(
 	const { session } = await createAgentSession({
 		cwd: tempDir,
 		agentDir: tempDir,
-		authStorage,
+		authStorage: sharedModelRegistry.authStorage,
+		modelRegistry: sharedModelRegistry,
 		sessionManager,
 		model,
 		settings: Settings.isolated(),
@@ -242,23 +247,42 @@ async function createSessionHarness(
 		slashCommands: [],
 		enableMCP: false,
 		enableLsp: false,
+		// These tests exercise session reload/sanitization/provider-state, never tool
+		// execution, rule resolution, or the workspace-tree render. A minimal tool set
+		// plus empty rules and a prebuilt (empty) workspace tree skip the per-call
+		// startup scans (native listWorkspace + rule capability discovery) without
+		// touching any asserted behavior.
+		rules: [],
+		workspaceTree: { rootPath: tempDir, rendered: "", truncated: false, totalLines: 0, agentsMdFiles: [] },
+		toolNames: ["read"],
 	});
 
-	return { session, authStorage };
+	return { session };
 }
 
 describe("AgentSession OpenAI Responses replay boundaries", () => {
 	const sessions: AgentSession[] = [];
-	const authStorages: AuthStorage[] = [];
 	const tempDirs: string[] = [];
 
+	beforeAll(async () => {
+		sharedRegistryDir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-issue-505-registry-${Snowflake.next()}-`));
+		const authStorage = await AuthStorage.create(path.join(sharedRegistryDir, "auth.db"));
+		authStorage.setRuntimeApiKey("openai", "test-key");
+		authStorage.setRuntimeApiKey("openai-codex", "test-key");
+		sharedModelRegistry = new ModelRegistry(authStorage);
+	});
+
+	afterAll(() => {
+		sharedModelRegistry?.authStorage.close();
+		if (sharedRegistryDir && fs.existsSync(sharedRegistryDir)) {
+			fs.rmSync(sharedRegistryDir, { recursive: true, force: true });
+		}
+	});
+
 	afterEach(async () => {
 		while (sessions.length > 0) {
 			await sessions.pop()?.dispose();
 		}
-		while (authStorages.length > 0) {
-			authStorages.pop()?.close();
-		}
 		while (tempDirs.length > 0) {
 			const tempDir = tempDirs.pop();
 			if (tempDir && fs.existsSync(tempDir)) {
@@ -285,9 +309,8 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		});
 
 		const reloadedSessionManager = await SessionManager.open(sessionFile, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, reloadedSessionManager);
+		const { session } = await createSessionHarness(tempDir, reloadedSessionManager);
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const persistedUser = findPersistedMessageEntry(session.sessionManager, "user", "Preserved summary").message;
 		if (persistedUser.role !== "user") {
@@ -383,12 +406,11 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		});
 
 		const reloadedSessionManager = await SessionManager.open(sessionFile, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, reloadedSessionManager, {
+		const { session } = await createSessionHarness(tempDir, reloadedSessionManager, {
 			provider: "openai-codex",
 			modelId: "gpt-5.2-codex",
 		});
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const closeSpy = vi.fn();
 		session.providerSessionState.set("openai-codex-responses", { close: closeSpy } satisfies ProviderSessionState);
@@ -421,12 +443,11 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		});
 
 		const reloadedSessionManager = await SessionManager.open(sessionFile, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, reloadedSessionManager, {
+		const { session } = await createSessionHarness(tempDir, reloadedSessionManager, {
 			provider: "openai-codex",
 			modelId: "gpt-5.2-codex",
 		});
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const closeSpy = vi.fn();
 		session.providerSessionState.set("openai-codex-responses", { close: closeSpy } satisfies ProviderSessionState);
@@ -476,9 +497,8 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-issue-505-reload-proxy-${Snowflake.next()}-`));
 		tempDirs.push(tempDir);
 		const sessionManager = SessionManager.create(tempDir, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, sessionManager);
+		const { session } = await createSessionHarness(tempDir, sessionManager);
 		sessions.push(session);
-		authStorages.push(authStorage);
 		const proxyDetails = new Proxy({ ok: true, nested: { value: "preserved" } }, {});
 
 		await session.sendCustomMessage(
@@ -514,12 +534,11 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		});
 
 		const reloadedSessionManager = await SessionManager.open(sessionFile, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, reloadedSessionManager, {
+		const { session } = await createSessionHarness(tempDir, reloadedSessionManager, {
 			provider: "openai-codex",
 			modelId: "gpt-5.2-codex",
 		});
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const closeSpy = vi.fn();
 		session.providerSessionState.set("openai-codex-responses", { close: closeSpy } satisfies ProviderSessionState);
@@ -561,12 +580,11 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		});
 
 		const reloadedSessionManager = await SessionManager.open(sessionFile, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, reloadedSessionManager, {
+		const { session } = await createSessionHarness(tempDir, reloadedSessionManager, {
 			provider: "openai-codex",
 			modelId: "gpt-5.2-codex",
 		});
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const closeSpy = vi.fn();
 		session.providerSessionState.set("openai-codex-responses", { close: closeSpy } satisfies ProviderSessionState);
@@ -597,9 +615,8 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		});
 
 		const reloadedSessionManager = await SessionManager.open(sessionFile, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, reloadedSessionManager);
+		const { session } = await createSessionHarness(tempDir, reloadedSessionManager);
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const closeSpy = vi.fn();
 		session.providerSessionState.set("openai-responses:openai", { close: closeSpy } satisfies ProviderSessionState);
@@ -623,9 +640,8 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-issue-505-switch-fail-${Snowflake.next()}-`));
 		tempDirs.push(tempDir);
 		const currentSessionManager = SessionManager.create(tempDir, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, currentSessionManager);
+		const { session } = await createSessionHarness(tempDir, currentSessionManager);
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const { sessionFile } = await createPersistedSession(tempDir, sessionManager => {
 			appendStaleAssistantTurn(sessionManager, "Unreadable assistant snapshot");
@@ -657,9 +673,8 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		const assistantText = "Switched assistant response";
 
 		const currentSessionManager = SessionManager.create(tempDir, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, currentSessionManager);
+		const { session } = await createSessionHarness(tempDir, currentSessionManager);
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const { sessionFile } = await createPersistedSession(tempDir, sessionManager => {
 			sessionManager.appendMessage({
@@ -723,9 +738,8 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		}
 
 		const reloadedSessionManager = await SessionManager.open(sessionFile, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, reloadedSessionManager);
+		const { session } = await createSessionHarness(tempDir, reloadedSessionManager);
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const navigation = await session.navigateTree(treeTargetId, { summarize: false });
 		expect(navigation.cancelled).toBe(false);
@@ -746,9 +760,8 @@ describe("AgentSession OpenAI Responses replay boundaries", () => {
 		const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-issue-505-new-${Snowflake.next()}-`));
 		tempDirs.push(tempDir);
 		const sessionManager = SessionManager.create(tempDir, tempDir);
-		const { session, authStorage } = await createSessionHarness(tempDir, sessionManager);
+		const { session } = await createSessionHarness(tempDir, sessionManager);
 		sessions.push(session);
-		authStorages.push(authStorage);
 
 		const closeSpy = vi.fn();
 		session.providerSessionState.set("live-provider-session", { close: closeSpy } satisfies ProviderSessionState);
diff --git a/packages/coding-agent/test/agent-session-python-cleanup.test.ts b/packages/coding-agent/test/agent-session-python-cleanup.test.ts
index 478fc5fb7..c97f93ec7 100644
--- a/packages/coding-agent/test/agent-session-python-cleanup.test.ts
+++ b/packages/coding-agent/test/agent-session-python-cleanup.test.ts
@@ -116,6 +116,7 @@ const createSession = async (
 			disableExtensionDiscovery: true,
 			extensions: options.extensions,
 			skills: [],
+			rules: [],
 			contextFiles: [],
 			promptTemplates: [],
 			workspaceTree: emptyWorkspaceTree(cwd),
@@ -195,6 +196,7 @@ describe("AgentSession python cleanup", () => {
 				disableExtensionDiscovery: true,
 				extensions: [throwingExtension],
 				skills: [],
+				rules: [],
 				contextFiles: [],
 				promptTemplates: [],
 				slashCommands: [],
@@ -261,6 +263,7 @@ describe("AgentSession python cleanup", () => {
 				model: getModel(),
 				disableExtensionDiscovery: true,
 				skills: [],
+				rules: [],
 				contextFiles: [],
 				promptTemplates: [],
 				slashCommands: [],
diff --git a/packages/coding-agent/test/agent-session-retry-fallback.test.ts b/packages/coding-agent/test/agent-session-retry-fallback.test.ts
index c9dc6d0ff..54c852f5f 100644
--- a/packages/coding-agent/test/agent-session-retry-fallback.test.ts
+++ b/packages/coding-agent/test/agent-session-retry-fallback.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
 import * as path from "node:path";
 import { scheduler } from "node:timers/promises";
 import { Agent } from "@oh-my-pi/pi-agent-core";
@@ -66,16 +66,34 @@ function createFallbackAgent(primaryModel: Model, requestedModels: string[]): Ag
 describe("AgentSession retry fallback", () => {
 	let tempDir: TempDir;
 	let authStorage: AuthStorage;
+	let sharedRegistry: ModelRegistry;
 	let modelRegistry: ModelRegistry;
 	let session: AgentSession | undefined;
 
-	beforeEach(async () => {
+	// The model registry is an immutable fixture whose construction builds a
+	// canonical index over ~2.7k bundled models (~100ms). Build it (and the
+	// auth DB) once for the whole file instead of per-test; reset only the
+	// mutable retry-fallback cooldown state between tests.
+	beforeAll(async () => {
 		tempDir = TempDir.createSync("@pi-retry-fallback-");
 		authStorage = await AuthStorage.create(path.join(tempDir.path(), "testauth.db"));
 		authStorage.setRuntimeApiKey("anthropic", "anthropic-test-key");
 		authStorage.setRuntimeApiKey("openai", "openai-test-key");
 		authStorage.setRuntimeApiKey("google", "google-test-key");
-		modelRegistry = new ModelRegistry(authStorage);
+		sharedRegistry = new ModelRegistry(authStorage);
+	});
+
+	afterAll(() => {
+		authStorage.close();
+		tempDir.removeSync();
+	});
+
+	beforeEach(() => {
+		// Reset to the shared registry (a few tests reassign it to a scoped
+		// instance) and clear cooldown suppressions left by fallback-path tests
+		// (default 5-minute suppression) so state never leaks between tests.
+		modelRegistry = sharedRegistry;
+		modelRegistry.clearSuppressedSelectors();
 	});
 
 	afterEach(async () => {
@@ -83,8 +101,6 @@ describe("AgentSession retry fallback", () => {
 			await session.dispose();
 			session = undefined;
 		}
-		authStorage.close();
-		tempDir.removeSync();
 		vi.restoreAllMocks();
 	});
 
diff --git a/packages/coding-agent/test/autoresearch-tools.test.ts b/packages/coding-agent/test/autoresearch-tools.test.ts
index 3b2c173f0..8dbe03a28 100644
--- a/packages/coding-agent/test/autoresearch-tools.test.ts
+++ b/packages/coding-agent/test/autoresearch-tools.test.ts
@@ -68,16 +68,16 @@ function createPiHarness(initialTools: string[] = []): PiHarness {
 	return { api, activeTools, appendEntries, setActiveToolsCalls };
 }
 
-async function initGitRepo(dir: string): Promise<{ baselineCommit: string; mainBranch: string }> {
-	await $`git init --initial-branch=main`.cwd(dir).quiet();
-	await $`git config user.email tester@example.com`.cwd(dir).quiet();
-	await $`git config user.name Tester`.cwd(dir).quiet();
+async function initGitRepo(dir: string): Promise<{ baselineCommit: string }> {
 	await Bun.write(path.join(dir, "README.md"), "# baseline\n");
-	await $`git add -A`.cwd(dir).quiet();
-	await $`git commit -m baseline`.cwd(dir).quiet();
+	// One shell invocation instead of five: the git processes are unavoidable
+	// (config identity is read by the production tool's own commits), but
+	// chaining collapses the per-call Node↔shell spawn overhead.
+	await $`git init --initial-branch=main && git config user.email tester@example.com && git config user.name Tester && git add -A && git commit -m baseline`
+		.cwd(dir)
+		.quiet();
 	const sha = (await $`git rev-parse HEAD`.cwd(dir).text()).trim();
-	const branch = (await $`git rev-parse --abbrev-ref HEAD`.cwd(dir).text()).trim();
-	return { baselineCommit: sha, mainBranch: branch };
+	return { baselineCommit: sha };
 }
 
 async function checkoutBranch(dir: string, name: string): Promise<void> {
@@ -585,8 +585,7 @@ describe("log_experiment", () => {
 		// Commit `src/edit-me.ts` to baseline so it is tracked, not in pre-run dirty paths.
 		fs.mkdirSync(path.join(dir, "src"), { recursive: true });
 		await Bun.write(path.join(dir, "src", "edit-me.ts"), "export const v = 1;\n");
-		await $`git add -A`.cwd(dir).quiet();
-		await $`git commit -m seed`.cwd(dir).quiet();
+		await $`git add -A && git commit -m seed`.cwd(dir).quiet();
 		const runtime = createSessionRuntime();
 		const harness = createPiHarness();
 		const init = createInitExperimentTool({
@@ -638,8 +637,7 @@ describe("log_experiment", () => {
 		await initGitRepo(dir);
 		// Commit the harness on main so it is part of the autoresearch branch's baseline.
 		await writeHarnessStub(dir);
-		await $`git add -A`.cwd(dir).quiet();
-		await $`git commit -m harness`.cwd(dir).quiet();
+		await $`git add -A && git commit -m harness`.cwd(dir).quiet();
 		await checkoutBranch(dir, "autoresearch/test-20260501");
 		const runtime = createSessionRuntime();
 		const harness = createPiHarness();
@@ -651,8 +649,7 @@ describe("log_experiment", () => {
 		await init.execute("i", { name: "x", primary_metric: "m" }, undefined, undefined, createCtx(dir));
 		// Simulate a previously kept iteration by committing it directly on the branch.
 		await Bun.write(path.join(dir, "src", "kept.ts"), "export const v = 1;\n");
-		await $`git add -A`.cwd(dir).quiet();
-		await $`git commit -m "kept iteration"`.cwd(dir).quiet();
+		await $`git add -A && git commit -m "kept iteration"`.cwd(dir).quiet();
 		const headBeforeDiscard = (await $`git rev-parse HEAD`.cwd(dir).text()).trim();
 
 		const run = createRunExperimentTool({
@@ -691,13 +688,11 @@ describe("log_experiment", () => {
 		const dir = makeTempDir();
 		await initGitRepo(dir);
 		await writeHarnessStub(dir);
-		await $`git add -A`.cwd(dir).quiet();
-		await $`git commit -m harness`.cwd(dir).quiet();
+		await $`git add -A && git commit -m harness`.cwd(dir).quiet();
 		// Seed a tracked file that the agent will edit during the iteration.
 		fs.mkdirSync(path.join(dir, "src"), { recursive: true });
 		await Bun.write(path.join(dir, "src", "store.ts"), "export const v = 1;\n");
-		await $`git add -A`.cwd(dir).quiet();
-		await $`git commit -m seed`.cwd(dir).quiet();
+		await $`git add -A && git commit -m seed`.cwd(dir).quiet();
 		await checkoutBranch(dir, "autoresearch/keep-test");
 		const runtime = createSessionRuntime();
 		const harness = createPiHarness();
@@ -747,8 +742,7 @@ describe("log_experiment", () => {
 		const dir = makeTempDir();
 		await initGitRepo(dir);
 		await writeHarnessStub(dir);
-		await $`git add -A`.cwd(dir).quiet();
-		await $`git commit -m harness`.cwd(dir).quiet();
+		await $`git add -A && git commit -m harness`.cwd(dir).quiet();
 		await checkoutBranch(dir, "autoresearch/scope-test");
 		const runtime = createSessionRuntime();
 		const harness = createPiHarness();
diff --git a/packages/coding-agent/test/bash-executor.test.ts b/packages/coding-agent/test/bash-executor.test.ts
index 96d92f5b8..3ff685827 100644
--- a/packages/coding-agent/test/bash-executor.test.ts
+++ b/packages/coding-agent/test/bash-executor.test.ts
@@ -14,12 +14,27 @@ import * as piNatives from "@oh-my-pi/pi-natives";
 const ARTIFACT_HEAD_BYTES_DEFAULT = 20 * 1024;
 const BACKGROUND_COMPLETION_RACE_MS = 750;
 const KILL_MARKER_DELAY_SECONDS = "0.4";
-const KILL_MARKER_ASSERTION_WAIT_MS = 900;
+const KILL_MARKER_DELAY_MS = 400;
+// We prove a killed process never wrote its marker by observing until the
+// wall-clock instant the marker WOULD have appeared (spawn + delay) plus a
+// margin. Anchoring the deadline to a pre-spawn timestamp — instead of blindly
+// sleeping a fixed amount after executeBash returns — keeps the wait bounded
+// without shrinking the kill-propagation margin: the timeout/abort fires at
+// ~100ms, well before the 400ms marker write, so the margin between kill and
+// write is unchanged; only the redundant observation tail goes away.
+const KILL_MARKER_OBSERVE_MARGIN_MS = 300;
 
 function makeTempDir(): string {
 	return fs.mkdtempSync(path.join(os.tmpdir(), "omp-bash-exec-"));
 }
 
+/** Spin-wait until the wall-clock deadline, polling rather than blind-sleeping. */
+async function waitUntil(deadlineMs: number): Promise<void> {
+	while (Date.now() < deadlineMs) {
+		await Bun.sleep(20);
+	}
+}
+
 describe("executeBash", () => {
 	let tempDir: string;
 
@@ -532,6 +547,7 @@ describe("executeBash", () => {
 		const markerEscaped = marker.replace(/'/g, "'\\''");
 
 		// Command creates marker after a short delay, but we timeout before then.
+		const start = Date.now();
 		const result = await executeBash(`sleep ${KILL_MARKER_DELAY_SECONDS} && echo done > '${markerEscaped}'`, {
 			cwd: tempDir,
 			timeout: 100,
@@ -539,10 +555,9 @@ describe("executeBash", () => {
 
 		expect(result.cancelled).toBe(true);
 
-		// Wait longer than the command would have needed to create the marker.
-		await Bun.sleep(KILL_MARKER_ASSERTION_WAIT_MS);
-
-		// If process was killed (not orphaned), marker should NOT exist
+		// Observe past the instant the marker would have been written had the
+		// process survived. If it was killed (not orphaned), it never appears.
+		await waitUntil(start + KILL_MARKER_DELAY_MS + KILL_MARKER_OBSERVE_MARGIN_MS);
 		expect(fs.existsSync(marker)).toBe(false);
 	});
 
@@ -552,6 +567,7 @@ describe("executeBash", () => {
 		const marker = path.join(tempDir, "marker-bg.txt");
 		const markerEscaped = marker.replace(/'/g, "'\\''");
 
+		const start = Date.now();
 		const result = await executeBash(
 			`{ sleep ${KILL_MARKER_DELAY_SECONDS}; echo done > '${markerEscaped}'; } & sleep 10`,
 			{
@@ -562,7 +578,7 @@ describe("executeBash", () => {
 
 		expect(result.cancelled).toBe(true);
 
-		await Bun.sleep(KILL_MARKER_ASSERTION_WAIT_MS);
+		await waitUntil(start + KILL_MARKER_DELAY_MS + KILL_MARKER_OBSERVE_MARGIN_MS);
 		expect(fs.existsSync(marker)).toBe(false);
 	});
 
@@ -597,9 +613,13 @@ describe("executeBash", () => {
 		expect(result.cancelled).toBe(true);
 		expect(result.output).toContain("Command cancelled");
 
-		await Bun.sleep(KILL_MARKER_ASSERTION_WAIT_MS);
+		// The backgrounded subshell only writes its marker once `release` exists.
+		// If abort failed to kill the process group, the orphan is still polling
+		// for `release` every 50ms — touching it makes a survivor react within one
+		// poll. A short settle first lets the kill signal propagate before we probe.
+		await Bun.sleep(100);
 		fs.writeFileSync(release, "");
-		await Bun.sleep(150);
+		await Bun.sleep(200);
 		expect(fs.existsSync(marker)).toBe(false);
 	});
 
@@ -611,6 +631,7 @@ describe("executeBash", () => {
 		const controller = new AbortController();
 
 		// Command creates marker after a short delay.
+		const start = Date.now();
 		const promise = executeBash(`sleep ${KILL_MARKER_DELAY_SECONDS} && echo done > '${markerEscaped}'`, {
 			cwd: tempDir,
 			timeout: 10000,
@@ -625,10 +646,9 @@ describe("executeBash", () => {
 		expect(result.cancelled).toBe(true);
 		expect(result.output).toContain("Command cancelled");
 
-		// Wait longer than the command would have needed to create the marker.
-		await Bun.sleep(KILL_MARKER_ASSERTION_WAIT_MS);
-
-		// If process was killed (not orphaned), marker should NOT exist
+		// Observe past the instant the marker would have been written had the
+		// process survived. If it was killed (not orphaned), it never appears.
+		await waitUntil(start + KILL_MARKER_DELAY_MS + KILL_MARKER_OBSERVE_MARGIN_MS);
 		expect(fs.existsSync(marker)).toBe(false);
 	});
 });
diff --git a/packages/coding-agent/test/extensions-runner.test.ts b/packages/coding-agent/test/extensions-runner.test.ts
index 33e188b7f..7e0005a43 100644
--- a/packages/coding-agent/test/extensions-runner.test.ts
+++ b/packages/coding-agent/test/extensions-runner.test.ts
@@ -2,7 +2,7 @@
  * Tests for ExtensionRunner - conflict detection, error handling, tool wrapping.
  */
 
-import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
@@ -20,21 +20,34 @@ describe("ExtensionRunner", () => {
 	let tempDir: TempDir;
 	let extensionsDir: string;
 	let sessionManager: SessionManager;
+	// Shared immutable fixtures. ModelRegistry's constructor synchronously loads
+	// every bundled model and rebuilds the canonical index (~100ms); these tests
+	// never mutate the registry or auth storage, so build them once per file
+	// instead of paying that cost in every beforeEach.
+	let sharedTempDir: TempDir;
 	let modelRegistry: ModelRegistry;
 	let authStorage: AuthStorage;
 
-	beforeEach(async () => {
+	beforeAll(async () => {
+		sharedTempDir = TempDir.createSync("@pi-runner-shared-");
+		authStorage = await AuthStorage.create(path.join(sharedTempDir.path(), "testauth.db"));
+		modelRegistry = new ModelRegistry(authStorage);
+	});
+
+	afterAll(() => {
+		authStorage.close();
+		sharedTempDir.removeSync();
+	});
+
+	beforeEach(() => {
 		tempDir = TempDir.createSync("@pi-runner-test-");
 		extensionsDir = path.join(getProjectAgentDir(tempDir.path()), "extensions");
 		fs.mkdirSync(extensionsDir, { recursive: true });
 		sessionManager = SessionManager.inMemory();
-		authStorage = await AuthStorage.create(path.join(tempDir.path(), "testauth.db"));
-		modelRegistry = new ModelRegistry(authStorage);
 	});
 
 	afterEach(() => {
 		testSetExtensionHandlerTimeoutMs(EXTENSION_HANDLER_TIMEOUT_MS);
-		authStorage.close();
 		tempDir.removeSync();
 	});
 
diff --git a/packages/coding-agent/test/goals/goal-mode-integration.test.ts b/packages/coding-agent/test/goals/goal-mode-integration.test.ts
index 4eafffe64..83d34f4cc 100644
--- a/packages/coding-agent/test/goals/goal-mode-integration.test.ts
+++ b/packages/coding-agent/test/goals/goal-mode-integration.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
 import * as path from "node:path";
 import { Agent } from "@oh-my-pi/pi-agent-core";
 import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
@@ -25,7 +25,6 @@ function createToolSession(cwd: string, settings: Settings, overrides: Partial<T
 
 type GoalHarness = {
 	tempDir: TempDir;
-	authStorage: AuthStorage;
 	settings: Settings;
 	session: AgentSession;
 	mode: InteractiveMode;
@@ -33,16 +32,35 @@ type GoalHarness = {
 	cleanup: () => Promise<void>;
 };
 
-async function createGoalHarness(): Promise<GoalHarness> {
-	resetSettingsForTest();
-	const tempDir = TempDir.createSync("@pi-goal-mode-");
-	await Settings.init({ inMemory: true, cwd: tempDir.path() });
-	const authStorage = await AuthStorage.create(path.join(tempDir.path(), "testauth.db"));
+// Immutable, expensive fixtures shared across every test. `new ModelRegistry`
+// alone is ~110ms (loads + parses the bundled model catalog), which dominated
+// this file's wall time when rebuilt per test. The registry, its auth storage,
+// and the resolved model are never mutated by goal-mode flows, and
+// AgentSession.dispose() never closes authStorage — so a single shared instance
+// is safe and drops ~8×110ms of pure setup overhead.
+type SharedFixture = {
+	authStorage: AuthStorage;
+	modelRegistry: ModelRegistry;
+	model: NonNullable<ReturnType<ModelRegistry["find"]>>;
+	baseDir: TempDir;
+};
+
+async function createSharedFixture(): Promise<SharedFixture> {
+	const baseDir = TempDir.createSync("@pi-goal-mode-shared-");
+	const authStorage = await AuthStorage.create(path.join(baseDir.path(), "testauth.db"));
 	const modelRegistry = new ModelRegistry(authStorage);
 	const model = modelRegistry.find("anthropic", "claude-sonnet-4-5");
 	if (!model) {
 		throw new Error("Expected claude-sonnet-4-5 to exist in registry");
 	}
+	return { authStorage, modelRegistry, model, baseDir };
+}
+
+async function createGoalHarness(shared: SharedFixture): Promise<GoalHarness> {
+	resetSettingsForTest();
+	const tempDir = TempDir.createSync("@pi-goal-mode-");
+	await Settings.init({ inMemory: true, cwd: tempDir.path() });
+	const { modelRegistry, model } = shared;
 
 	const settings = Settings.isolated({
 		"compaction.enabled": false,
@@ -77,7 +95,6 @@ async function createGoalHarness(): Promise<GoalHarness> {
 
 	return {
 		tempDir,
-		authStorage,
 		settings,
 		session,
 		mode,
@@ -85,7 +102,6 @@ async function createGoalHarness(): Promise<GoalHarness> {
 		cleanup: async () => {
 			mode.stop();
 			await session.dispose();
-			authStorage.close();
 			tempDir.removeSync();
 			resetSettingsForTest();
 		},
@@ -98,13 +114,20 @@ async function toolNamesFor(harness: GoalHarness): Promise<string[]> {
 
 describe("InteractiveMode goal mode integration", () => {
 	let harness: GoalHarness;
+	let shared: SharedFixture;
 
-	beforeAll(() => {
+	beforeAll(async () => {
 		initTheme();
+		shared = await createSharedFixture();
+	});
+
+	afterAll(() => {
+		shared.authStorage.close();
+		shared.baseDir.removeSync();
 	});
 
 	beforeEach(async () => {
-		harness = await createGoalHarness();
+		harness = await createGoalHarness(shared);
 	});
 
 	afterEach(async () => {
diff --git a/packages/coding-agent/test/interactive-mode-plan-review.test.ts b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
index 6fb7b28eb..85ae3f784 100644
--- a/packages/coding-agent/test/interactive-mode-plan-review.test.ts
+++ b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
@@ -68,7 +68,6 @@ describe("InteractiveMode plan review rendering", () => {
 	});
 
 	beforeEach(async () => {
-		Bun.gc(true);
 		resetSettingsForTest();
 		tempDir = TempDir.createSync("@pi-plan-review-");
 		await Settings.init({ inMemory: true, cwd: tempDir.path() });
@@ -111,7 +110,6 @@ describe("InteractiveMode plan review rendering", () => {
 		currentAuthStorage?.close();
 		currentTempDir?.removeSync();
 		resetSettingsForTest();
-		Bun.gc(true);
 	});
 
 	it("appends each submitted plan review preview to preserve scrollback", async () => {
diff --git a/packages/coding-agent/test/keybindings-selector-navigation.test.ts b/packages/coding-agent/test/keybindings-selector-navigation.test.ts
index e79557af5..78dd76e76 100644
--- a/packages/coding-agent/test/keybindings-selector-navigation.test.ts
+++ b/packages/coding-agent/test/keybindings-selector-navigation.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeAll, describe, expect, it } from "bun:test";
+import { afterEach, beforeAll, describe, expect, it, vi } from "bun:test";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -86,8 +86,15 @@ async function createHistoryStorage(prompts: string[]): Promise<HistoryStorage>
 	tempDirs.push(dir);
 	HistoryStorage.resetInstance();
 	const storage = HistoryStorage.open(path.join(dir, "history.db"));
-	for (const prompt of prompts) {
-		await storage.add(prompt);
+	// add() batches writes behind a 100ms AsyncDrain timer. Drive that timer with
+	// fake timers so the flush is instant instead of waiting real wall-clock time.
+	vi.useFakeTimers();
+	try {
+		const writes = prompts.map(prompt => storage.add(prompt));
+		vi.advanceTimersByTime(100);
+		await Promise.all(writes);
+	} finally {
+		vi.useRealTimers();
 	}
 	return storage;
 }
diff --git a/packages/coding-agent/test/mcp-reconnect-storm.test.ts b/packages/coding-agent/test/mcp-reconnect-storm.test.ts
index 6f75e8955..87a5ef49a 100644
--- a/packages/coding-agent/test/mcp-reconnect-storm.test.ts
+++ b/packages/coding-agent/test/mcp-reconnect-storm.test.ts
@@ -52,10 +52,19 @@ describe("MCP reconnect storm (issue #1592)", () => {
 
 		try {
 			await manager.connectServers({ crashy: config }, {});
-			// Give the reconnect loop generous time to fire. With the bug this
-			// produced thousands of processes within a second; with the fix the
-			// circuit breaker caps the per-server spawn budget.
-			await Bun.sleep(3000);
+			// Wait for the circuit breaker to trip rather than blind-sleeping a
+			// fixed budget. During the storm `getConnectionStatus` is always
+			// "connected" or "connecting" (`#pendingReconnections` is set
+			// synchronously before any await in `#doReconnect`); it only reports
+			// "disconnected" once `#tripReconnectBreaker` opens, tears down the
+			// stale connection, and detaches `onClose` so no further spawns fire.
+			// That makes the terminal state a race-free signal: poll for it and
+			// return the instant the storm is capped instead of waiting out a
+			// fixed 3s. Generous deadline stays well under the 15s test timeout.
+			const deadline = Date.now() + 10_000;
+			while (manager.getConnectionStatus("crashy") !== "disconnected" && Date.now() < deadline) {
+				await Bun.sleep(5);
+			}
 
 			const spawns = countSpawns();
 			// `RECONNECT_BURST_LIMIT` (5) is the per-server reconnect cap inside
diff --git a/packages/coding-agent/test/model-registry-runtime-provider.test.ts b/packages/coding-agent/test/model-registry-runtime-provider.test.ts
index 9538a0e34..30e40efbb 100644
--- a/packages/coding-agent/test/model-registry-runtime-provider.test.ts
+++ b/packages/coding-agent/test/model-registry-runtime-provider.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, type Mock, spyOn, test } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -13,6 +13,9 @@ describe("ModelRegistry runtime provider registration", () => {
 	let tempDir: string;
 	let modelsJsonPath: string;
 	let authStorage: AuthStorage;
+	// Neutralizes real network egress during "online" refresh tests so the merge
+	// path runs without wall-clock-bound DNS/socket latency. Restored in afterEach.
+	let fetchSpy: Mock<typeof fetch> | undefined;
 
 	const sourceIds = ["ext://atomic", "ext://runtime", "ext://oauth"];
 
@@ -24,6 +27,8 @@ describe("ModelRegistry runtime provider registration", () => {
 	});
 
 	afterEach(() => {
+		fetchSpy?.mockRestore();
+		fetchSpy = undefined;
 		clearCustomApis();
 		for (const sourceId of sourceIds) {
 			unregisterOAuthProviders(sourceId);
@@ -192,6 +197,11 @@ describe("ModelRegistry runtime provider registration", () => {
 	});
 
 	test("extension-registered models survive refresh('online') cycle", async () => {
+		// The contract is overlay survival through the full online refresh path
+		// (static reload + discovery + merge), not discovery success. Stub fetch so
+		// the online branch runs identically to production-with-no-reachable-providers
+		// without paying real network latency (~400ms of DNS/socket time otherwise).
+		fetchSpy = spyOn(globalThis, "fetch").mockRejectedValue(new Error("network disabled in test"));
 		const registry = new ModelRegistry(authStorage, modelsJsonPath);
 		const config: ProviderConfigInput = {
 			baseUrl: "https://runtime.example.com/v1",
diff --git a/packages/coding-agent/test/model-registry.test.ts b/packages/coding-agent/test/model-registry.test.ts
index 0cdb092ca..218d98a22 100644
--- a/packages/coding-agent/test/model-registry.test.ts
+++ b/packages/coding-agent/test/model-registry.test.ts
@@ -29,7 +29,10 @@ describe("ModelRegistry", () => {
 		fs.mkdirSync(tempDir, { recursive: true });
 		modelsJsonPath = path.join(tempDir, "models.json");
 		cacheDbPath = path.join(tempDir, "models.db");
-		authStorage = await AuthStorage.create(path.join(tempDir, "testauth.db"));
+		// In-memory auth DB: tests need a fresh, isolated credential store per case but
+		// never reopen it from disk, so :memory: avoids the WAL/chmod disk-open cost
+		// (~3ms/test) while preserving per-test isolation.
+		authStorage = await AuthStorage.create(":memory:");
 	});
 
 	afterEach(() => {
diff --git a/packages/coding-agent/test/modes/components/transcript-container.test.ts b/packages/coding-agent/test/modes/components/transcript-container.test.ts
index 6baf1bfac..a1b385eae 100644
--- a/packages/coding-agent/test/modes/components/transcript-container.test.ts
+++ b/packages/coding-agent/test/modes/components/transcript-container.test.ts
@@ -173,6 +173,25 @@ describe("TranscriptContainer", () => {
 		expect(container.render(40)).toEqual(["a-final", "b1"]); // reconciled
 	});
 
+	it("invalidate() retires frozen snapshots so resetDisplay reflects current state", () => {
+		// resetDisplay() (Ctrl+L, and the Ctrl+O expand path) reflows by calling
+		// TUI.invalidate(), which propagates to this container. That must retire the
+		// frozen snapshots the same way thaw() does, or a forced full replay would
+		// still emit the pre-mutation (e.g. collapsed) render.
+		riskFlag.eagerEraseScrollbackRisk = true;
+		const container = new TranscriptContainer();
+		const a = new MutableBlock(["a-collapsed"]);
+		const b = new MutableBlock(["b1"]);
+		container.addChild(a);
+		container.addChild(b);
+		container.render(40);
+		a.set(["a-expanded-1", "a-expanded-2"]);
+		expect(container.render(40)).toEqual(["a-collapsed", "b1"]); // frozen
+
+		container.invalidate();
+		expect(container.render(40)).toEqual(["a-expanded-1", "a-expanded-2", "b1"]);
+	});
+
 	it("recomputes a frozen block on a width change", () => {
 		riskFlag.eagerEraseScrollbackRisk = true;
 		const container = new TranscriptContainer();
diff --git a/packages/coding-agent/test/modes/controllers/input-controller-tool-expansion.test.ts b/packages/coding-agent/test/modes/controllers/input-controller-tool-expansion.test.ts
index bcf3900ea..38370dca3 100644
--- a/packages/coding-agent/test/modes/controllers/input-controller-tool-expansion.test.ts
+++ b/packages/coding-agent/test/modes/controllers/input-controller-tool-expansion.test.ts
@@ -3,20 +3,25 @@ import { InputController } from "../../../src/modes/controllers/input-controller
 import type { InteractiveModeContext } from "../../../src/modes/types";
 
 describe("InputController tool output expansion", () => {
-	it("allows unknown viewport mutation when toggling tool output expansion", () => {
+	it("expands children and forces a full display reset to bypass frozen snapshots", () => {
 		const expandable = { setExpanded: vi.fn() };
 		const inert = { render: vi.fn(() => []) };
 		const requestRender = vi.fn();
+		const resetDisplay = vi.fn();
 		const ctx = {
 			toolOutputExpanded: false,
 			chatContainer: { children: [expandable, inert] },
-			ui: { requestRender },
+			ui: { requestRender, resetDisplay },
 		} as unknown as InteractiveModeContext;
 
 		new InputController(ctx).toggleToolOutputExpansion();
 
 		expect(ctx.toolOutputExpanded).toBe(true);
 		expect(expandable.setExpanded).toHaveBeenCalledWith(true);
-		expect(requestRender).toHaveBeenCalledWith(false, { allowUnknownViewportMutation: true });
+		// resetDisplay() is the only path that retires the transcript's frozen
+		// block snapshots and re-emits the whole transcript at its new heights.
+		// A plain requestRender would replay the stale (collapsed) snapshots.
+		expect(resetDisplay).toHaveBeenCalledTimes(1);
+		expect(requestRender).not.toHaveBeenCalled();
 	});
 });
diff --git a/packages/coding-agent/test/plan-mode-thinking-level.test.ts b/packages/coding-agent/test/plan-mode-thinking-level.test.ts
index b5eee3bf3..548593336 100644
--- a/packages/coding-agent/test/plan-mode-thinking-level.test.ts
+++ b/packages/coding-agent/test/plan-mode-thinking-level.test.ts
@@ -6,7 +6,7 @@
  * calls resolveModelRoleValue() but only returns .model, dropping the thinking level.
  * #applyPlanModeModel() therefore has no thinking level to apply.
  */
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "bun:test";
 import * as path from "node:path";
 import { Agent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
@@ -22,7 +22,7 @@ describe("plan mode thinking level", () => {
 	let modelRegistry: ModelRegistry;
 	let authStorage: AuthStorage;
 
-	beforeEach(async () => {
+	beforeAll(async () => {
 		tempDir = TempDir.createSync("@pi-plan-thinking-");
 		authStorage = await AuthStorage.create(path.join(tempDir.path(), "testauth.db"));
 		authStorage.setRuntimeApiKey("anthropic", "test-key");
@@ -33,6 +33,9 @@ describe("plan mode thinking level", () => {
 		if (session) {
 			await session.dispose();
 		}
+	});
+
+	afterAll(() => {
 		authStorage.close();
 		tempDir.removeSync();
 	});
diff --git a/packages/coding-agent/test/sdk-async-job-manager-singleton.test.ts b/packages/coding-agent/test/sdk-async-job-manager-singleton.test.ts
index eee3e1da3..903c00722 100644
--- a/packages/coding-agent/test/sdk-async-job-manager-singleton.test.ts
+++ b/packages/coding-agent/test/sdk-async-job-manager-singleton.test.ts
@@ -1,14 +1,35 @@
-import { afterEach, describe, expect, it } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { AsyncJobManager } from "@oh-my-pi/pi-coding-agent/async/job-manager";
+import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
 import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import { createAgentSession } from "@oh-my-pi/pi-coding-agent/sdk";
+import { AuthStorage } from "@oh-my-pi/pi-coding-agent/session/auth-storage";
 import { Snowflake } from "@oh-my-pi/pi-utils";
 
 describe("AsyncJobManager singleton across concurrent top-level sessions", () => {
 	const tempDirs: string[] = [];
+	// Building a ModelRegistry per session is the dominant cost here: createAgentSession
+	// otherwise runs discoverAuthStorage (a fresh AuthStorage DB create+reload) and a
+	// background online model refresh for every spawn (~450ms each). The singleton
+	// ownership behavior under test is independent of model resolution, so we hand every
+	// session one shared, network-free registry built once (~10ms/session instead).
+	let sharedTempDir: string;
+	let sharedAuthStorage: AuthStorage;
+	let sharedModelRegistry: ModelRegistry;
+
+	beforeAll(async () => {
+		sharedTempDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-sdk-async-singleton-shared-"));
+		sharedAuthStorage = await AuthStorage.create(path.join(sharedTempDir, "auth.db"));
+		sharedModelRegistry = new ModelRegistry(sharedAuthStorage, path.join(sharedTempDir, "models.yml"));
+	});
+
+	afterAll(() => {
+		sharedAuthStorage.close();
+		fs.rmSync(sharedTempDir, { recursive: true, force: true });
+	});
 
 	afterEach(async () => {
 		for (const tempDir of tempDirs.splice(0)) {
@@ -34,6 +55,7 @@ describe("AsyncJobManager singleton across concurrent top-level sessions", () =>
 			slashCommands: [],
 			enableMCP: false,
 			enableLsp: false,
+			modelRegistry: sharedModelRegistry,
 		});
 		return session;
 	}
@@ -153,6 +175,7 @@ describe("AsyncJobManager singleton across concurrent top-level sessions", () =>
 				slashCommands: [],
 				enableMCP: false,
 				enableLsp: false,
+				modelRegistry: sharedModelRegistry,
 				systemPrompt: () => {
 					throw new Error("forced startup failure");
 				},
diff --git a/packages/coding-agent/test/sdk-credential-disabled-bridge.test.ts b/packages/coding-agent/test/sdk-credential-disabled-bridge.test.ts
index 0001a780a..a01522c99 100644
--- a/packages/coding-agent/test/sdk-credential-disabled-bridge.test.ts
+++ b/packages/coding-agent/test/sdk-credential-disabled-bridge.test.ts
@@ -93,10 +93,17 @@ describe("createAgentSession credential_disabled subscription", () => {
 		cwd: dirs.cwd,
 		agentDir: dirs.agentDir,
 		authStorage,
+		// Pin the model registry at a temp models.json. Without an explicit path, ModelRegistry
+		// loads the developer's real ~/.omp models config on every construction (~100ms each,
+		// and non-isolated). Pointing it at the (absent) temp file keeps construction at ~2ms and
+		// avoids leaking host config into the test. Providing the registry also skips the
+		// fire-and-forget background model discovery, which is irrelevant to credential_disabled.
+		modelRegistry: new ModelRegistry(authStorage, path.join(dirs.agentDir, "models.json")),
 		settings: Settings.isolated(),
 		disableExtensionDiscovery: true,
 		extensions,
 		skills: [],
+		rules: [],
 		contextFiles: [],
 		promptTemplates: [],
 		workspaceTree: emptyWorkspaceTree(dirs.cwd),
@@ -406,7 +413,7 @@ describe("createAgentSession credential_disabled subscription", () => {
 				embedderEvents.push(event);
 			},
 		});
-		const modelRegistry = new ModelRegistry(authStorage);
+		const modelRegistry = new ModelRegistry(authStorage, path.join(dirs.agentDir, "models.json"));
 		const ext = makeRecordingExtension();
 
 		const { session } = await createAgentSession({
@@ -448,7 +455,7 @@ describe("createAgentSession credential_disabled subscription", () => {
 		const dirs = makeDirs("mismatch");
 		const registryStorage = await AuthStorage.create(path.join(dirs.agentDir, "agent-registry.db"));
 		const otherStorage = await AuthStorage.create(path.join(dirs.agentDir, "agent-other.db"));
-		const modelRegistry = new ModelRegistry(registryStorage);
+		const modelRegistry = new ModelRegistry(registryStorage, path.join(dirs.agentDir, "models-registry.json"));
 
 		await expect(
 			createAgentSession({
@@ -477,7 +484,7 @@ describe("createAgentSession credential_disabled subscription", () => {
 		// by one microtask so a sync onError() registration lands in time.
 		const dirs = makeDirs("error-routing");
 		const authStorage = await AuthStorage.create(path.join(dirs.agentDir, "agent.db"));
-		const modelRegistry = new ModelRegistry(authStorage);
+		const modelRegistry = new ModelRegistry(authStorage, path.join(dirs.agentDir, "models.json"));
 		try {
 			const throwingExtension: Extension = {
 				path: "test://throwing-credential-disabled",
diff --git a/packages/coding-agent/test/sdk-mcp-discovery.test.ts b/packages/coding-agent/test/sdk-mcp-discovery.test.ts
index f9d1082b5..ed866c6b2 100644
--- a/packages/coding-agent/test/sdk-mcp-discovery.test.ts
+++ b/packages/coding-agent/test/sdk-mcp-discovery.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -47,18 +47,34 @@ const oldSessionMtime = new Date("2000-01-01T00:00:00.000Z");
 
 describe("createAgentSession MCP discovery prompt gating", () => {
 	let tempDir: string;
+	let registryDir: string;
 	let authStorage: AuthStorage;
 	let modelRegistry: ModelRegistry;
 
-	beforeEach(async () => {
-		tempDir = path.join(os.tmpdir(), `pi-sdk-mcp-discovery-${Snowflake.next()}`);
-		fs.mkdirSync(tempDir, { recursive: true });
-		authStorage = await AuthStorage.create(path.join(tempDir, "auth.db"));
+	// Immutable across tests: ModelRegistry's constructor eagerly loads the bundled
+	// model catalog (~120ms). The tests pass models explicitly and never mutate the
+	// registry (refreshInBackground is skipped when modelRegistry is supplied, and
+	// extension source sync is empty under disableExtensionDiscovery), so build it once.
+	beforeAll(async () => {
+		registryDir = path.join(os.tmpdir(), `pi-sdk-mcp-discovery-registry-${Snowflake.next()}`);
+		fs.mkdirSync(registryDir, { recursive: true });
+		authStorage = await AuthStorage.create(path.join(registryDir, "auth.db"));
 		modelRegistry = new ModelRegistry(authStorage);
 	});
 
-	afterEach(() => {
+	afterAll(() => {
 		authStorage.close();
+		if (registryDir && fs.existsSync(registryDir)) {
+			fs.rmSync(registryDir, { recursive: true, force: true });
+		}
+	});
+
+	beforeEach(() => {
+		tempDir = path.join(os.tmpdir(), `pi-sdk-mcp-discovery-${Snowflake.next()}`);
+		fs.mkdirSync(tempDir, { recursive: true });
+	});
+
+	afterEach(() => {
 		if (tempDir && fs.existsSync(tempDir)) {
 			fs.rmSync(tempDir, { recursive: true, force: true });
 		}
diff --git a/packages/coding-agent/test/sdk-model-selection.test.ts b/packages/coding-agent/test/sdk-model-selection.test.ts
index c702edf29..89f072394 100644
--- a/packages/coding-agent/test/sdk-model-selection.test.ts
+++ b/packages/coding-agent/test/sdk-model-selection.test.ts
@@ -12,6 +12,7 @@ import { Snowflake } from "@oh-my-pi/pi-utils";
 
 describe("createAgentSession deferred model pattern resolution", () => {
 	let tempDir: string;
+	const authStoragesToClose: AuthStorage[] = [];
 
 	beforeEach(() => {
 		tempDir = path.join(os.tmpdir(), `pi-sdk-model-selection-${Snowflake.next()}`);
@@ -19,6 +20,10 @@ describe("createAgentSession deferred model pattern resolution", () => {
 	});
 
 	afterEach(() => {
+		for (const authStorage of authStoragesToClose) {
+			authStorage.close();
+		}
+		authStoragesToClose.length = 0;
 		if (tempDir && fs.existsSync(tempDir)) {
 			fs.rmSync(tempDir, { recursive: true, force: true });
 		}
@@ -52,10 +57,20 @@ describe("createAgentSession deferred model pattern resolution", () => {
 		});
 	};
 
-	function buildSessionOptions(modelPattern: string) {
+	async function buildSessionOptions(modelPattern: string) {
+		// Pass an explicit ModelRegistry so createAgentSession skips its implicit
+		// ModelRegistry.refreshInBackground() — a network model-discovery pass
+		// (~250ms/session) that contributes nothing here: the model resolves from
+		// the inline extension provider, never from network catalogs. Mirrors the
+		// explicit-registry pattern the resume tests below already rely on.
+		const authStorage = await AuthStorage.create(path.join(tempDir, "auth.db"));
+		authStoragesToClose.push(authStorage);
+		const modelRegistry = new ModelRegistry(authStorage, path.join(tempDir, "models.yml"));
 		return {
 			cwd: tempDir,
 			agentDir: tempDir,
+			authStorage,
+			modelRegistry,
 			sessionManager: SessionManager.inMemory(),
 			disableExtensionDiscovery: true,
 			extensions: [providerExtension],
@@ -71,7 +86,7 @@ describe("createAgentSession deferred model pattern resolution", () => {
 
 	test("resolves explicit modelPattern after extension providers register", async () => {
 		const { session, modelFallbackMessage } = await createAgentSession(
-			buildSessionOptions("runtime-provider/runtime-model"),
+			await buildSessionOptions("runtime-provider/runtime-model"),
 		);
 
 		expect(session.model).toBeDefined();
@@ -82,7 +97,7 @@ describe("createAgentSession deferred model pattern resolution", () => {
 
 	test("does not silently fallback when explicit modelPattern is unresolved", async () => {
 		const { session, modelFallbackMessage } = await createAgentSession(
-			buildSessionOptions("missing-provider/missing-model"),
+			await buildSessionOptions("missing-provider/missing-model"),
 		);
 
 		expect(session.model).toBeUndefined();
@@ -95,7 +110,7 @@ describe("createAgentSession deferred model pattern resolution", () => {
 		settings.setModelRole("default", "pi/smol:high");
 
 		const { session } = await createAgentSession({
-			...buildSessionOptions("runtime-provider/runtime-reasoning-model"),
+			...(await buildSessionOptions("runtime-provider/runtime-reasoning-model")),
 			settings,
 		});
 
diff --git a/packages/coding-agent/test/sdk-session-isolation.test.ts b/packages/coding-agent/test/sdk-session-isolation.test.ts
index 91355299c..7bac57a38 100644
--- a/packages/coding-agent/test/sdk-session-isolation.test.ts
+++ b/packages/coding-agent/test/sdk-session-isolation.test.ts
@@ -1,12 +1,14 @@
-import { afterEach, describe, expect, it } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { type AssistantMessage, getBundledModel } from "@oh-my-pi/pi-ai";
 import type { Rule } from "@oh-my-pi/pi-coding-agent/capability/rule";
+import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
 import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import { createAgentSession } from "@oh-my-pi/pi-coding-agent/sdk";
 import { SecretObfuscator } from "@oh-my-pi/pi-coding-agent/secrets";
+import { AuthStorage } from "@oh-my-pi/pi-coding-agent/session/auth-storage";
 import { SessionManager } from "@oh-my-pi/pi-coding-agent/session/session-manager";
 import { getSessionsDir, Snowflake } from "@oh-my-pi/pi-utils";
 
@@ -55,6 +57,23 @@ function getAssistantText(message: AssistantMessage | undefined): string {
 
 describe("createAgentSession session storage isolation", () => {
 	const tempDirs: string[] = [];
+	// One shared, fully-populated (bundled models load synchronously in the
+	// constructor) registry for every case. Passing it via options skips the
+	// per-call discoverAuthStorage() SQLite open and the refreshInBackground()
+	// network model probe inside createAgentSession — the two real wall-clock
+	// sinks here. None of these cases assert on model discovery, so an
+	// ambient-credential-free in-memory auth store keeps them deterministic.
+	let sharedAuthStorage: AuthStorage;
+	let sharedModelRegistry: ModelRegistry;
+
+	beforeAll(async () => {
+		sharedAuthStorage = await AuthStorage.create(":memory:");
+		sharedModelRegistry = new ModelRegistry(sharedAuthStorage);
+	});
+
+	afterAll(() => {
+		sharedAuthStorage.close();
+	});
 
 	afterEach(async () => {
 		for (const tempDir of tempDirs.splice(0)) {
@@ -72,6 +91,7 @@ describe("createAgentSession session storage isolation", () => {
 		const { session } = await createAgentSession({
 			cwd,
 			agentDir,
+			modelRegistry: sharedModelRegistry,
 			settings: Settings.isolated(),
 			disableExtensionDiscovery: true,
 			skills: [],
@@ -105,6 +125,7 @@ describe("createAgentSession session storage isolation", () => {
 		const { session } = await createAgentSession({
 			cwd,
 			agentDir,
+			modelRegistry: sharedModelRegistry,
 			settings: Settings.isolated(),
 			rules: [rule],
 			disableExtensionDiscovery: true,
@@ -137,6 +158,7 @@ describe("createAgentSession session storage isolation", () => {
 			const commonOptions = {
 				cwd,
 				agentDir,
+				modelRegistry: sharedModelRegistry,
 				settings: Settings.isolated({ "secrets.enabled": true }),
 				disableExtensionDiscovery: true,
 				skills: [],
@@ -206,6 +228,7 @@ describe("createAgentSession session storage isolation", () => {
 			const { session } = await createAgentSession({
 				cwd,
 				agentDir,
+				modelRegistry: sharedModelRegistry,
 				sessionManager: resumedManager,
 				model,
 				settings: Settings.isolated({ "secrets.enabled": true }),
diff --git a/packages/coding-agent/test/sdk-skills.test.ts b/packages/coding-agent/test/sdk-skills.test.ts
index 81ad42029..15bccd54a 100644
--- a/packages/coding-agent/test/sdk-skills.test.ts
+++ b/packages/coding-agent/test/sdk-skills.test.ts
@@ -1,10 +1,12 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
 import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import type { Skill } from "@oh-my-pi/pi-coding-agent/sdk";
 import { createAgentSession } from "@oh-my-pi/pi-coding-agent/sdk";
+import { AuthStorage } from "@oh-my-pi/pi-coding-agent/session/auth-storage";
 import { SessionManager } from "@oh-my-pi/pi-coding-agent/session/session-manager";
 import { cleanupTempHome } from "./helpers/temp-home-cleanup";
 
@@ -24,6 +26,25 @@ describe("createAgentSession skills option", () => {
 	let skillsDir: string;
 	let tempHomeDir = "";
 	let originalHome: string | undefined;
+	// Auth storage (SQLite DB) and the model registry are immutable across these tests: skill
+	// discovery never touches models, and building them per test would make createAgentSession call
+	// modelRegistry.refreshInBackground(), whose online model discovery saturates the event loop and
+	// serializes the otherwise-parallel capability scans (~340ms/call). Supplying a prebuilt registry
+	// skips that refresh entirely (~24ms/call).
+	let sharedDir: string;
+	let sharedAuthStorage: AuthStorage;
+	let sharedModelRegistry: ModelRegistry;
+
+	beforeAll(async () => {
+		sharedDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-sdk-skills-shared-"));
+		sharedAuthStorage = await AuthStorage.create(path.join(sharedDir, "auth.db"));
+		sharedModelRegistry = new ModelRegistry(sharedAuthStorage, path.join(sharedDir, "models.yml"));
+	});
+
+	afterAll(() => {
+		sharedAuthStorage.close();
+		fs.rmSync(sharedDir, { recursive: true, force: true });
+	});
 
 	beforeEach(() => {
 		tempDir = path.join(os.tmpdir(), `pi-sdk-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
@@ -74,6 +95,7 @@ Loaded via symbolic link.
 			cwd: tempDir,
 			agentDir: tempDir,
 			sessionManager: SessionManager.inMemory(),
+			modelRegistry: sharedModelRegistry,
 			settings: createIsolatedSkillsSettings(),
 		});
 
@@ -87,6 +109,7 @@ Loaded via symbolic link.
 			cwd: tempDir,
 			agentDir: tempDir,
 			sessionManager: SessionManager.inMemory(),
+			modelRegistry: sharedModelRegistry,
 			settings: createIsolatedSkillsSettings(),
 		});
 
@@ -102,6 +125,7 @@ Loaded via symbolic link.
 			cwd: tempDir,
 			agentDir: tempDir,
 			sessionManager: SessionManager.inMemory(),
+			modelRegistry: sharedModelRegistry,
 			settings: createIsolatedSkillsSettings(),
 		});
 
@@ -112,6 +136,7 @@ Loaded via symbolic link.
 			cwd: tempDir,
 			agentDir: tempDir,
 			sessionManager: SessionManager.inMemory(),
+			modelRegistry: sharedModelRegistry,
 			skills: [], // Explicitly empty - like --no-skills
 			settings: createIsolatedSkillsSettings(),
 		});
@@ -135,6 +160,7 @@ Loaded via symbolic link.
 			cwd: tempDir,
 			agentDir: tempDir,
 			sessionManager: SessionManager.inMemory(),
+			modelRegistry: sharedModelRegistry,
 			skills: [customSkill],
 			settings: createIsolatedSkillsSettings(),
 		});
diff --git a/packages/coding-agent/test/sdk-tool-activation.test.ts b/packages/coding-agent/test/sdk-tool-activation.test.ts
index 6758acde1..a4b8da987 100644
--- a/packages/coding-agent/test/sdk-tool-activation.test.ts
+++ b/packages/coding-agent/test/sdk-tool-activation.test.ts
@@ -4,7 +4,11 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { getBundledModel } from "@oh-my-pi/pi-ai";
 import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
-import { createAgentSession, type ExtensionFactory } from "@oh-my-pi/pi-coding-agent/sdk";
+import {
+	type CreateAgentSessionOptions,
+	createAgentSession,
+	type ExtensionFactory,
+} from "@oh-my-pi/pi-coding-agent/sdk";
 import { SessionManager } from "@oh-my-pi/pi-coding-agent/session/session-manager";
 import { Snowflake } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
@@ -34,6 +38,35 @@ const toolActivationExtension: ExtensionFactory = pi => {
 describe("createAgentSession defaultInactive tool activation", () => {
 	const tempDirs: string[] = [];
 
+	const makeTempDir = (): string => {
+		const tempDir = path.join(os.tmpdir(), `pi-sdk-tool-activation-${Snowflake.next()}`);
+		tempDirs.push(tempDir);
+		fs.mkdirSync(tempDir, { recursive: true });
+		return tempDir;
+	};
+
+	// Shared options for every session. `rules: []` and `workspaceTree` short-circuit
+	// the two slow startup scans (rule discovery + native workspace walk, ~100ms each)
+	// that are irrelevant to tool activation: these tests assert only which tools are
+	// registered/active and that tool names appear in the system prompt. Each call
+	// returns fresh `settings`/`sessionManager` instances to keep tests isolated.
+	const baseOptions = (tempDir: string): CreateAgentSessionOptions => ({
+		cwd: tempDir,
+		agentDir: tempDir,
+		sessionManager: SessionManager.inMemory(),
+		settings: Settings.isolated(),
+		model: getBundledModel("openai", "gpt-4o-mini"),
+		disableExtensionDiscovery: true,
+		skills: [],
+		contextFiles: [],
+		promptTemplates: [],
+		slashCommands: [],
+		enableMCP: false,
+		enableLsp: false,
+		rules: [],
+		workspaceTree: { rootPath: tempDir, rendered: "", truncated: false, totalLines: 0, agentsMdFiles: [] },
+	});
+
 	afterEach(() => {
 		for (const tempDir of tempDirs.splice(0)) {
 			fs.rmSync(tempDir, { recursive: true, force: true });
@@ -43,24 +76,11 @@ describe("createAgentSession defaultInactive tool activation", () => {
 	});
 
 	it("excludes defaultInactive extension tools from the initial active set unless explicitly requested", async () => {
-		const tempDir = path.join(os.tmpdir(), `pi-sdk-tool-activation-${Snowflake.next()}`);
-		tempDirs.push(tempDir);
-		fs.mkdirSync(tempDir, { recursive: true });
+		const tempDir = makeTempDir();
 
 		const { session } = await createAgentSession({
-			cwd: tempDir,
-			agentDir: tempDir,
-			sessionManager: SessionManager.inMemory(),
-			settings: Settings.isolated(),
-			model: getBundledModel("openai", "gpt-4o-mini"),
-			disableExtensionDiscovery: true,
+			...baseOptions(tempDir),
 			extensions: [toolActivationExtension],
-			skills: [],
-			contextFiles: [],
-			promptTemplates: [],
-			slashCommands: [],
-			enableMCP: false,
-			enableLsp: false,
 		});
 
 		try {
@@ -77,24 +97,11 @@ describe("createAgentSession defaultInactive tool activation", () => {
 	});
 
 	it("allows explicitly requested defaultInactive extension tools into the initial active set", async () => {
-		const tempDir = path.join(os.tmpdir(), `pi-sdk-tool-activation-${Snowflake.next()}`);
-		tempDirs.push(tempDir);
-		fs.mkdirSync(tempDir, { recursive: true });
+		const tempDir = makeTempDir();
 
 		const { session } = await createAgentSession({
-			cwd: tempDir,
-			agentDir: tempDir,
-			sessionManager: SessionManager.inMemory(),
-			settings: Settings.isolated(),
-			model: getBundledModel("openai", "gpt-4o-mini"),
-			disableExtensionDiscovery: true,
+			...baseOptions(tempDir),
 			extensions: [toolActivationExtension],
-			skills: [],
-			contextFiles: [],
-			promptTemplates: [],
-			slashCommands: [],
-			enableMCP: false,
-			enableLsp: false,
 			toolNames: ["read", "default_inactive_tool"],
 		});
 
@@ -113,23 +120,10 @@ describe("createAgentSession defaultInactive tool activation", () => {
 		// (e.g. `["read", "search", "find", "lsp", "web_search"]`). Without this
 		// invariant, `yield` ended up registered but not active, and the model
 		// could not satisfy the idle-reminder contract that demands a `yield` call.
-		const tempDir = path.join(os.tmpdir(), `pi-sdk-tool-activation-${Snowflake.next()}`);
-		tempDirs.push(tempDir);
-		fs.mkdirSync(tempDir, { recursive: true });
+		const tempDir = makeTempDir();
 
 		const { session } = await createAgentSession({
-			cwd: tempDir,
-			agentDir: tempDir,
-			sessionManager: SessionManager.inMemory(),
-			settings: Settings.isolated(),
-			model: getBundledModel("openai", "gpt-4o-mini"),
-			disableExtensionDiscovery: true,
-			skills: [],
-			contextFiles: [],
-			promptTemplates: [],
-			slashCommands: [],
-			enableMCP: false,
-			enableLsp: false,
+			...baseOptions(tempDir),
 			requireYieldTool: true,
 			toolNames: ["read", "search", "find", "web_search"],
 		});
@@ -149,23 +143,10 @@ describe("createAgentSession defaultInactive tool activation", () => {
 		// the registry has no `deferrable` tool, so the previous gate dropped
 		// `resolve` from the registry and plan mode silently activated without
 		// it — leaving the agent stuck after drafting the plan.
-		const tempDir = path.join(os.tmpdir(), `pi-sdk-tool-activation-${Snowflake.next()}`);
-		tempDirs.push(tempDir);
-		fs.mkdirSync(tempDir, { recursive: true });
+		const tempDir = makeTempDir();
 
 		const { session } = await createAgentSession({
-			cwd: tempDir,
-			agentDir: tempDir,
-			sessionManager: SessionManager.inMemory(),
-			settings: Settings.isolated(),
-			model: getBundledModel("openai", "gpt-4o-mini"),
-			disableExtensionDiscovery: true,
-			skills: [],
-			contextFiles: [],
-			promptTemplates: [],
-			slashCommands: [],
-			enableMCP: false,
-			enableLsp: false,
+			...baseOptions(tempDir),
 			toolNames: ["read", "search", "find", "web_search"],
 		});
 
@@ -177,26 +158,14 @@ describe("createAgentSession defaultInactive tool activation", () => {
 	});
 
 	it("drops the hidden resolve tool when neither a deferrable tool nor plan mode can use it", async () => {
-		const tempDir = path.join(os.tmpdir(), `pi-sdk-tool-activation-${Snowflake.next()}`);
-		tempDirs.push(tempDir);
-		fs.mkdirSync(tempDir, { recursive: true });
+		const tempDir = makeTempDir();
 
 		const settings = Settings.isolated();
 		settings.set("plan.enabled", false);
 
 		const { session } = await createAgentSession({
-			cwd: tempDir,
-			agentDir: tempDir,
-			sessionManager: SessionManager.inMemory(),
+			...baseOptions(tempDir),
 			settings,
-			model: getBundledModel("openai", "gpt-4o-mini"),
-			disableExtensionDiscovery: true,
-			skills: [],
-			contextFiles: [],
-			promptTemplates: [],
-			slashCommands: [],
-			enableMCP: false,
-			enableLsp: false,
 			toolNames: ["read", "search", "find", "web_search"],
 		});
 
@@ -208,23 +177,10 @@ describe("createAgentSession defaultInactive tool activation", () => {
 	});
 
 	it("does not register the xAI TTS tool unless enabled", async () => {
-		const tempDir = path.join(os.tmpdir(), `pi-sdk-tool-activation-${Snowflake.next()}`);
-		tempDirs.push(tempDir);
-		fs.mkdirSync(tempDir, { recursive: true });
+		const tempDir = makeTempDir();
 
 		const { session } = await createAgentSession({
-			cwd: tempDir,
-			agentDir: tempDir,
-			sessionManager: SessionManager.inMemory(),
-			settings: Settings.isolated(),
-			model: getBundledModel("openai", "gpt-4o-mini"),
-			disableExtensionDiscovery: true,
-			skills: [],
-			contextFiles: [],
-			promptTemplates: [],
-			slashCommands: [],
-			enableMCP: false,
-			enableLsp: false,
+			...baseOptions(tempDir),
 		});
 
 		try {
@@ -237,23 +193,11 @@ describe("createAgentSession defaultInactive tool activation", () => {
 	});
 
 	it("registers the xAI TTS tool when enabled", async () => {
-		const tempDir = path.join(os.tmpdir(), `pi-sdk-tool-activation-${Snowflake.next()}`);
-		tempDirs.push(tempDir);
-		fs.mkdirSync(tempDir, { recursive: true });
+		const tempDir = makeTempDir();
 
 		const { session } = await createAgentSession({
-			cwd: tempDir,
-			agentDir: tempDir,
-			sessionManager: SessionManager.inMemory(),
+			...baseOptions(tempDir),
 			settings: Settings.isolated({ "tts.enabled": true }),
-			model: getBundledModel("openai", "gpt-4o-mini"),
-			disableExtensionDiscovery: true,
-			skills: [],
-			contextFiles: [],
-			promptTemplates: [],
-			slashCommands: [],
-			enableMCP: false,
-			enableLsp: false,
 		});
 
 		try {
diff --git a/packages/coding-agent/test/tools.test.ts b/packages/coding-agent/test/tools.test.ts
index ff0825548..7493cbb1e 100644
--- a/packages/coding-agent/test/tools.test.ts
+++ b/packages/coding-agent/test/tools.test.ts
@@ -16,6 +16,7 @@ import { JobTool } from "@oh-my-pi/pi-coding-agent/tools/job";
 import { wrapToolWithMetaNotice } from "@oh-my-pi/pi-coding-agent/tools/output-meta";
 import { ReadTool } from "@oh-my-pi/pi-coding-agent/tools/read";
 import { DEFAULT_FILE_LIMIT, MULTI_FILE_PER_FILE_MATCHES, SearchTool } from "@oh-my-pi/pi-coding-agent/tools/search";
+import * as toolTimeouts from "@oh-my-pi/pi-coding-agent/tools/tool-timeouts";
 import { WriteTool } from "@oh-my-pi/pi-coding-agent/tools/write";
 import { $which, Snowflake } from "@oh-my-pi/pi-utils";
 import { unzipSync } from "fflate";
@@ -1164,7 +1165,7 @@ function b() {
 			const updates: string[] = [];
 			const result = await bashTool.execute(
 				"test-call-8-stream",
-				{ command: "for i in 1 2 3; do echo $i; sleep 0.2; done" },
+				{ command: "for i in 1 2 3; do echo $i; sleep 0.1; done" },
 				undefined,
 				update => {
 					const text = update.content?.find(c => c.type === "text")?.text ?? "";
@@ -1310,13 +1311,19 @@ function b() {
 					),
 				),
 			);
+			// Drive the effective timeout via the production clamp seam so the
+			// backgrounded job times out in ~0.5s instead of a real wall-clock
+			// second. 0.5s still renders as "1 seconds" in the executor message
+			// (Math.round), so that delivery assertion is unchanged; the
+			// auto-background-on-timeout decision path is identical.
+			vi.spyOn(toolTimeouts, "clampTimeout").mockReturnValue(0.5);
 
 			const result = await autoBackgroundBashTool.execute("test-call-9-auto-timeout-background", {
 				command: "printf 'start\\n'; sleep 1.2; printf 'done\\n'",
 				timeout: 1,
 			});
 
-			expect(result.details?.timeoutSeconds).toBe(1);
+			expect(result.details?.timeoutSeconds).toBe(0.5);
 			expect(result.details?.async?.state).toBe("running");
 			expect(getTextOutput(result)).toContain("Background job");
 			const jobId = result.details?.async?.jobId;
@@ -1344,6 +1351,9 @@ function b() {
 		});
 
 		it("should respect timeout", async () => {
+			// Reduce the effective timeout through the production clamp seam; the
+			// real subprocess kill-on-timeout path is still exercised, just faster.
+			vi.spyOn(toolTimeouts, "clampTimeout").mockReturnValue(0.1);
 			await expect(bashTool.execute("test-call-10", { command: "sleep 5", timeout: 1 })).rejects.toThrow(
 				/timed out/i,
 			);
@@ -1351,10 +1361,19 @@ function b() {
 
 		it("should abort and recover for subsequent commands", async () => {
 			const controller = new AbortController();
-			const promise = bashTool.execute("test-call-10-abort", { command: "sleep 60" }, controller.signal);
-			// Give the native shell a beat to enter `sleep`; do not depend on chunk
-			// delivery timing, which is flaky on loaded CI runners.
-			await Bun.sleep(100);
+			const started = Promise.withResolvers<void>();
+			const promise = bashTool.execute(
+				"test-call-10-abort",
+				{ command: "echo READY; sleep 60" },
+				controller.signal,
+				update => {
+					const text = update.content?.find(c => c.type === "text")?.text ?? "";
+					if (text.includes("READY")) started.resolve();
+				},
+			);
+			// Abort as soon as the command has emitted output (proving the shell is
+			// live), instead of blindly waiting a fixed beat for it to enter `sleep`.
+			await started.promise;
 			controller.abort("test abort");
 			await expect(promise).rejects.toThrow(/abort|cancel|timed out/i);
 
diff --git a/packages/coding-agent/test/tools/approval-mode.test.ts b/packages/coding-agent/test/tools/approval-mode.test.ts
index 9b0709881..f2fa648c2 100644
--- a/packages/coding-agent/test/tools/approval-mode.test.ts
+++ b/packages/coding-agent/test/tools/approval-mode.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "bun:test";
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -19,31 +19,6 @@ function emptyWorkspaceTree(cwd: string) {
 	return { rootPath: cwd, rendered: ".\n", truncated: false, totalLines: 1, agentsMdFiles: [] };
 }
 
-async function makeSession(extraSettings: Record<string, unknown> = {}) {
-	const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-approval-mode-${Snowflake.next()}-`));
-	const cwd = path.join(tempDir, "cwd");
-	fs.mkdirSync(cwd, { recursive: true });
-	const sessionManager = SessionManager.create(cwd, path.join(tempDir, "sessions"));
-	const settings = Settings.isolated({ ...BASE_SETTINGS, ...extraSettings });
-	const { session } = await createAgentSession({
-		cwd,
-		agentDir: tempDir,
-		sessionManager,
-		settings,
-		model: getBundledModel("openai", "gpt-4o-mini"),
-		disableExtensionDiscovery: true,
-		skills: [],
-		contextFiles: [],
-		workspaceTree: emptyWorkspaceTree(cwd),
-		promptTemplates: [],
-		slashCommands: [],
-		enableMCP: false,
-		enableLsp: false,
-		toolNames: ["bash"],
-	});
-	return { tempDir, session, settings };
-}
-
 function textOf(result: { content?: ReadonlyArray<{ type: string; text?: string }> }): string {
 	const blocks = result.content ?? [];
 	for (const block of blocks) {
@@ -53,179 +28,155 @@ function textOf(result: { content?: ReadonlyArray<{ type: string; text?: string
 }
 
 describe("tools.approvalMode setting", () => {
-	const tempDirs: string[] = [];
+	// The per-tool approval gate (ExtensionToolWrapper) reads approvalMode / tools.approval /
+	// autoApprove exclusively from the execute-time AgentToolContext, never from the session's
+	// own settings. So a single shared session exercises every mode — we only vary the context
+	// settings per assertion. This avoids paying createAgentSession's cost (model registry,
+	// auth-storage discovery, settings init) nine times over.
+	let tempDir: string;
+	let session: Awaited<ReturnType<typeof createAgentSession>>["session"];
 
-	afterEach(async () => {
-		for (const tempDir of tempDirs.splice(0)) {
-			// Windows can briefly hold tempdir handles after session.dispose(); retry a few times.
-			for (let attempt = 0; attempt < 5; attempt++) {
-				try {
-					fs.rmSync(tempDir, { recursive: true, force: true });
-					break;
-				} catch (err) {
-					const code = (err as NodeJS.ErrnoException).code;
-					if (code !== "EBUSY" && code !== "ENOTEMPTY" && code !== "EPERM") throw err;
-					if (attempt === 4) break; // best-effort: OS will reclaim
-					await Bun.sleep(50 * (attempt + 1));
-				}
+	beforeAll(async () => {
+		tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `pi-approval-mode-${Snowflake.next()}-`));
+		const cwd = path.join(tempDir, "cwd");
+		fs.mkdirSync(cwd, { recursive: true });
+		const sessionManager = SessionManager.create(cwd, path.join(tempDir, "sessions"));
+		const created = await createAgentSession({
+			cwd,
+			agentDir: tempDir,
+			sessionManager,
+			settings: Settings.isolated(BASE_SETTINGS),
+			model: getBundledModel("openai", "gpt-4o-mini"),
+			disableExtensionDiscovery: true,
+			skills: [],
+			contextFiles: [],
+			workspaceTree: emptyWorkspaceTree(cwd),
+			promptTemplates: [],
+			slashCommands: [],
+			enableMCP: false,
+			enableLsp: false,
+			toolNames: ["bash"],
+		});
+		session = created.session;
+	});
+
+	afterAll(async () => {
+		await session.dispose();
+		// Windows can briefly hold tempdir handles after session.dispose(); retry a few times.
+		for (let attempt = 0; attempt < 5; attempt++) {
+			try {
+				fs.rmSync(tempDir, { recursive: true, force: true });
+				break;
+			} catch (err) {
+				const code = (err as NodeJS.ErrnoException).code;
+				if (code !== "EBUSY" && code !== "ENOTEMPTY" && code !== "EPERM") throw err;
+				if (attempt === 4) break; // best-effort: OS will reclaim
+				await Bun.sleep(50 * (attempt + 1));
 			}
 		}
 	});
 
+	function approvalSettings(extraSettings: Record<string, unknown> = {}): Settings {
+		return Settings.isolated({ ...BASE_SETTINGS, ...extraSettings });
+	}
+
+	function bashTool() {
+		const bash = session.getToolByName("bash");
+		if (!bash) throw new Error("Expected bash tool");
+		return bash;
+	}
+
 	it("yolo mode (default) bypasses approval for non-overriding tool calls", async () => {
-		const { tempDir, session, settings } = await makeSession();
-		tempDirs.push(tempDir);
-		try {
-			const bash = session.getToolByName("bash");
-			if (!bash) throw new Error("Expected bash tool");
-			const result = await bash.execute("yolo", { command: "echo ok" }, undefined, undefined, {
-				settings,
-			} as AgentToolContext);
-			expect(textOf(result)).toContain("ok");
-		} finally {
-			await session.dispose();
-		}
+		const settings = approvalSettings();
+		const result = await bashTool().execute("yolo", { command: "echo ok" }, undefined, undefined, {
+			settings,
+		} as AgentToolContext);
+		expect(textOf(result)).toContain("ok");
 	});
 
 	it("always-ask mode rejects exec tools when no UI is available", async () => {
-		const { tempDir, session, settings } = await makeSession({
-			"tools.approvalMode": "always-ask",
-		});
-		tempDirs.push(tempDir);
-		try {
-			const bash = session.getToolByName("bash");
-			if (!bash) throw new Error("Expected bash tool");
-			await expect(
-				bash.execute("always-ask", { command: "echo blocked" }, undefined, undefined, {
-					settings,
-				} as AgentToolContext),
-			).rejects.toThrow(/requires approval but no interactive UI available/);
-		} finally {
-			await session.dispose();
-		}
+		const settings = approvalSettings({ "tools.approvalMode": "always-ask" });
+		await expect(
+			bashTool().execute("always-ask", { command: "echo blocked" }, undefined, undefined, {
+				settings,
+			} as AgentToolContext),
+		).rejects.toThrow(/requires approval but no interactive UI available/);
 	});
 
 	it("per-tool allow overrides are honored in every mode", async () => {
-		const { tempDir, session, settings } = await makeSession({
+		const settings = approvalSettings({
 			"tools.approvalMode": "always-ask",
 			"tools.approval": { bash: "allow" },
 		});
-		tempDirs.push(tempDir);
-		try {
-			const bash = session.getToolByName("bash");
-			if (!bash) throw new Error("Expected bash tool");
-			const result = await bash.execute("always-ask-allow", { command: "echo allowed" }, undefined, undefined, {
-				settings,
-			} as AgentToolContext);
-			expect(textOf(result)).toContain("allowed");
-		} finally {
-			await session.dispose();
-		}
+		const result = await bashTool().execute("always-ask-allow", { command: "echo allowed" }, undefined, undefined, {
+			settings,
+		} as AgentToolContext);
+		expect(textOf(result)).toContain("allowed");
 	});
 
 	it("per-tool prompt overrides can tighten yolo mode", async () => {
-		const { tempDir, session, settings } = await makeSession({
+		const settings = approvalSettings({
 			"tools.approvalMode": "yolo",
 			"tools.approval": { bash: "prompt" },
 		});
-		tempDirs.push(tempDir);
-		try {
-			const bash = session.getToolByName("bash");
-			if (!bash) throw new Error("Expected bash tool");
-			await expect(
-				bash.execute("yolo-prompt", { command: "echo blocked" }, undefined, undefined, {
-					settings,
-				} as AgentToolContext),
-			).rejects.toThrow(/requires approval but no interactive UI available/);
-		} finally {
-			await session.dispose();
-		}
+		await expect(
+			bashTool().execute("yolo-prompt", { command: "echo blocked" }, undefined, undefined, {
+				settings,
+			} as AgentToolContext),
+		).rejects.toThrow(/requires approval but no interactive UI available/);
 	});
 
 	it("write mode still prompts exec-tier tools", async () => {
-		const { tempDir, session, settings } = await makeSession({
+		const settings = approvalSettings({
 			"tools.approvalMode": "write",
 			"tools.approval": {},
 		});
-		tempDirs.push(tempDir);
-		try {
-			const bash = session.getToolByName("bash");
-			if (!bash) throw new Error("Expected bash tool");
-			await expect(
-				bash.execute("write-mode", { command: "echo unconfigured" }, undefined, undefined, {
-					settings,
-				} as AgentToolContext),
-			).rejects.toThrow(/requires approval but no interactive UI available/);
-		} finally {
-			await session.dispose();
-		}
+		await expect(
+			bashTool().execute("write-mode", { command: "echo unconfigured" }, undefined, undefined, {
+				settings,
+			} as AgentToolContext),
+		).rejects.toThrow(/requires approval but no interactive UI available/);
 	});
 
 	it("critical bash patterns do not prompt in yolo mode with bash allowed", async () => {
-		const { tempDir, session, settings } = await makeSession({
+		const settings = approvalSettings({
 			"tools.approvalMode": "yolo",
 			"tools.approval": { bash: "allow" },
 		});
-		tempDirs.push(tempDir);
-		try {
-			const bash = session.getToolByName("bash");
-			if (!bash) throw new Error("Expected bash tool");
-
-			const result = await bash.execute(
-				"critical",
-				{ command: "rm -f /tmp/bun-fake-timer-probe.test.ts" },
-				undefined,
-				undefined,
-				{
-					settings,
-				} as AgentToolContext,
-			);
-			expect(textOf(result)).toContain("(no output)");
-		} finally {
-			await session.dispose();
-		}
+		const result = await bashTool().execute(
+			"critical",
+			{ command: "rm -f /tmp/bun-fake-timer-probe.test.ts" },
+			undefined,
+			undefined,
+			{
+				settings,
+			} as AgentToolContext,
+		);
+		expect(textOf(result)).toContain("(no output)");
 	});
 
 	it("CLI --auto-approve forces yolo mode for non-overriding tool calls", async () => {
-		const { tempDir, session, settings } = await makeSession({
-			"tools.approvalMode": "always-ask",
-		});
-		tempDirs.push(tempDir);
-		try {
-			const bash = session.getToolByName("bash");
-			if (!bash) throw new Error("Expected bash tool");
-			const result = await bash.execute("cli-override", { command: "echo override" }, undefined, undefined, {
-				settings,
-				autoApprove: true,
-			} as AgentToolContext);
-			expect(textOf(result)).toContain("override");
-		} finally {
-			await session.dispose();
-		}
+		const settings = approvalSettings({ "tools.approvalMode": "always-ask" });
+		const result = await bashTool().execute("cli-override", { command: "echo override" }, undefined, undefined, {
+			settings,
+			autoApprove: true,
+		} as AgentToolContext);
+		expect(textOf(result)).toContain("override");
 	});
 
 	it("CLI --auto-approve also bypasses safety-override patterns", async () => {
-		const { tempDir, session, settings } = await makeSession({
-			"tools.approvalMode": "always-ask",
-		});
-		tempDirs.push(tempDir);
-		try {
-			const bash = session.getToolByName("bash");
-			if (!bash) throw new Error("Expected bash tool");
-			const result = await bash.execute(
-				"cli-critical",
-				{ command: "rm -f /tmp/bun-fake-timer-probe.test.ts" },
-				undefined,
-				undefined,
-				{
-					settings,
-					autoApprove: true,
-				} as AgentToolContext,
-			);
-			expect(textOf(result)).toContain("(no output)");
-		} finally {
-			await session.dispose();
-		}
+		const settings = approvalSettings({ "tools.approvalMode": "always-ask" });
+		const result = await bashTool().execute(
+			"cli-critical",
+			{ command: "rm -f /tmp/bun-fake-timer-probe.test.ts" },
+			undefined,
+			undefined,
+			{
+				settings,
+				autoApprove: true,
+			} as AgentToolContext,
+		);
+		expect(textOf(result)).toContain("(no output)");
 	});
 
 	it("constructs an extensionRunner unconditionally so the approval gate is always installed", async () => {
@@ -236,12 +187,6 @@ describe("tools.approvalMode setting", () => {
 		// any non-yolo approval mode setting would be a no-op without feedback. The
 		// fix is to construct the runner unconditionally; this test makes that contract explicit so
 		// a future change to make the runner optional again cannot silently re-open the hole.
-		const { tempDir, session } = await makeSession();
-		tempDirs.push(tempDir);
-		try {
-			expect(session.extensionRunner).toBeDefined();
-		} finally {
-			await session.dispose();
-		}
+		expect(session.extensionRunner).toBeDefined();
 	});
 });
diff --git a/packages/coding-agent/test/tools/conflict-integration.test.ts b/packages/coding-agent/test/tools/conflict-integration.test.ts
index 73c784d50..5d1a92a8b 100644
--- a/packages/coding-agent/test/tools/conflict-integration.test.ts
+++ b/packages/coding-agent/test/tools/conflict-integration.test.ts
@@ -26,7 +26,11 @@ function getText(result: { content: Array<{ type: string; text?: string }> }): s
 }
 
 async function getTool(session: ToolSession, name: "read" | "write") {
-	const tools = await createTools(session);
+	// Request only the tool under test: createTools(session) with no toolNames
+	// builds every builtin factory (LSP, MCP discovery, browser, eval preflight,
+	// …) on each call, which is pure overhead here. The conflict contract lives
+	// entirely in the read/write tools + session.conflictHistory.
+	const tools = await createTools(session, [name]);
 	const tool = tools.find(entry => entry.name === name);
 	if (!tool) throw new Error(`Missing ${name} tool`);
 	return tool;
diff --git a/packages/coding-agent/test/tools/fetch-jina-stall.test.ts b/packages/coding-agent/test/tools/fetch-jina-stall.test.ts
index 03f33b1dc..7582f1cc2 100644
--- a/packages/coding-agent/test/tools/fetch-jina-stall.test.ts
+++ b/packages/coding-agent/test/tools/fetch-jina-stall.test.ts
@@ -45,9 +45,12 @@ describe("renderHtmlToText: jina stall does not starve local fallbacks (#1449)",
 		});
 
 		const started = Date.now();
-		// `timeout: 2` keeps the overall budget tight — the test must complete
-		// within ~2s even though Jina would otherwise hang for the full budget.
-		const result = await renderHtmlToText("https://example.com/article", html, 2, settings, undefined, null);
+		// Tight 300ms reader-mode budget. Jina would otherwise hang forever, but
+		// the remote sub-budget (min(timeout*1000, REMOTE_READER_MAX_MS)) aborts
+		// the stalled request so the local native renderer still runs. Kept small
+		// so the test exercises the same abort path without burning real
+		// wall-clock time waiting out the stall.
+		const result = await renderHtmlToText("https://example.com/article", html, 0.3, settings, undefined, null);
 		const elapsedMs = Date.now() - started;
 
 		expect(result.ok).toBe(true);
@@ -56,10 +59,10 @@ describe("renderHtmlToText: jina stall does not starve local fallbacks (#1449)",
 		// If trafilatura or lynx happened to succeed first, that's also a valid
 		// non-aborted outcome.
 		expect(["native", "trafilatura", "lynx"]).toContain(result.method);
-		// Must finish well before the overall budget elapses: the remote
-		// sub-budget caps Jina at min(timeout, REMOTE_READER_MAX_MS), so the
-		// remaining ~1s of the 2s budget is enough for the native renderer.
-		expect(elapsedMs).toBeLessThan(2_500);
+		// Must finish shortly after the 300ms budget aborts the stalled Jina
+		// request — never anywhere near an unbounded hang. The generous bound
+		// absorbs scheduler jitter under full-suite parallelism.
+		expect(elapsedMs).toBeLessThan(1_500);
 	});
 
 	it("re-throws when the user signal is aborted, not when Jina sub-budget expires", async () => {
diff --git a/packages/coding-agent/test/tools/gh.test.ts b/packages/coding-agent/test/tools/gh.test.ts
index 2deb69989..b1776f807 100644
--- a/packages/coding-agent/test/tools/gh.test.ts
+++ b/packages/coding-agent/test/tools/gh.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it, vi } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "bun:test";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -85,15 +85,24 @@ function runGit(cwd: string, args: string[]): string {
 	return new TextDecoder().decode(result.stdout).trim();
 }
 
-async function createPrFixture(): Promise<{
+interface PrFixture {
 	baseDir: string;
 	repoRoot: string;
 	originBare: string;
 	forkBare: string;
 	headRefName: string;
 	headRefOid: string;
-}> {
-	const baseDir = await fs.mkdtemp(path.join(os.tmpdir(), "gh-pr-tool-"));
+}
+
+// Building the fixture costs ~16 real `git` subprocess spawns (~200ms). Six
+// tests need it, so we build it ONCE as an immutable template in `beforeAll`
+// and materialize per-test copies via `fs.cp` (~12ms). Each copy is a fully
+// independent repo tree, so the mutating tests (worktree checkout, config
+// writes, extra branches) can't contaminate each other.
+let prFixtureTemplate: PrFixture | null = null;
+
+async function buildPrFixtureTemplate(): Promise<PrFixture> {
+	const baseDir = await fs.mkdtemp(path.join(os.tmpdir(), "gh-pr-tool-template-"));
 	const repoRoot = path.join(baseDir, "repo");
 	const originBare = path.join(baseDir, "origin.git");
 	const forkBare = path.join(baseDir, "fork.git");
@@ -119,13 +128,32 @@ async function createPrFixture(): Promise<{
 	runGit(repoRoot, ["push", "-u", "forksrc", headRefName]);
 	runGit(repoRoot, ["checkout", "main"]);
 
+	return { baseDir, repoRoot, originBare, forkBare, headRefName, headRefOid };
+}
+
+async function createPrFixture(): Promise<PrFixture> {
+	const template = prFixtureTemplate;
+	if (!template) throw new Error("PR fixture template was not built (missing beforeAll)");
+
+	const baseDir = await fs.mkdtemp(path.join(os.tmpdir(), "gh-pr-tool-"));
+	const repoRoot = path.join(baseDir, "repo");
+	const originBare = path.join(baseDir, "origin.git");
+	const forkBare = path.join(baseDir, "fork.git");
+
+	await fs.cp(template.baseDir, baseDir, { recursive: true });
+	// Remote URLs in the copied repo still point at the template's absolute
+	// `origin.git`/`fork.git`. Repoint them at this copy so pushes/fetches stay
+	// isolated and `remote get-url` assertions match the returned paths.
+	runGit(repoRoot, ["remote", "set-url", "origin", originBare]);
+	runGit(repoRoot, ["remote", "set-url", "forksrc", forkBare]);
+
 	return {
 		baseDir,
 		repoRoot,
 		originBare,
 		forkBare,
-		headRefName,
-		headRefOid,
+		headRefName: template.headRefName,
+		headRefOid: template.headRefOid,
 	};
 }
 
@@ -210,6 +238,17 @@ describe("parsePrUnifiedDiff", () => {
 });
 
 describe("github tool", () => {
+	beforeAll(async () => {
+		prFixtureTemplate = await buildPrFixtureTemplate();
+	});
+
+	afterAll(async () => {
+		if (prFixtureTemplate) {
+			await fs.rm(prFixtureTemplate.baseDir, { recursive: true, force: true });
+			prFixtureTemplate = null;
+		}
+	});
+
 	afterEach(() => {
 		vi.useRealTimers();
 		vi.restoreAllMocks();
diff --git a/packages/coding-agent/test/tools/lsp-regressions.test.ts b/packages/coding-agent/test/tools/lsp-regressions.test.ts
index f4e4aa2e6..f246f5545 100644
--- a/packages/coding-agent/test/tools/lsp-regressions.test.ts
+++ b/packages/coding-agent/test/tools/lsp-regressions.test.ts
@@ -373,6 +373,10 @@ for await (const chunk of Bun.stdin.stream()) {
 				args: [serverPath, eventLogPath, statusCountPath, fileToUri(sourcePath)],
 				fileTypes: ["rs"],
 				rootMarkers: [],
+				// Shrink the workspace-ready polling window so the test exercises the
+				// timeout→retry→ready sequence without waiting out the 2s production settle.
+				// The status-request timeout stays generous to avoid racing the subprocess.
+				workspaceReadyTimings: { timeoutMs: 5_000, pollMs: 10, settleMs: 20, statusRequestTimeoutMs: 150 },
 			};
 
 			vi.spyOn(lspConfig, "loadConfig").mockReturnValue({
diff --git a/packages/tui/test/render-regressions.test.ts b/packages/tui/test/render-regressions.test.ts
index 1693cc817..522f230b1 100644
--- a/packages/tui/test/render-regressions.test.ts
+++ b/packages/tui/test/render-regressions.test.ts
@@ -27,6 +27,34 @@ class MutableLinesComponent implements Component {
 	}
 }
 
+// Models a component that caches its rendered output and only refreshes it when
+// `invalidate()` fires — like a transcript block that freezes a snapshot. A
+// state change behind the cache is invisible until something invalidates it,
+// which is exactly what `resetDisplay()` must do to surface a Ctrl+O expansion.
+class CachedComponent implements Component {
+	#current: string[];
+	#cache: string[] | undefined;
+
+	constructor(lines: string[]) {
+		this.#current = [...lines];
+	}
+
+	setLines(lines: string[]): void {
+		this.#current = [...lines];
+	}
+
+	invalidate(): void {
+		this.#cache = undefined;
+	}
+
+	render(width: number): string[] {
+		if (this.#cache === undefined) {
+			this.#cache = this.#current.map(line => line.slice(0, width));
+		}
+		return this.#cache;
+	}
+}
+
 class WrappingLinesComponent implements Component {
 	#lines: string[];
 
@@ -366,6 +394,32 @@ describe("TUI terminal-state regressions", () => {
 			}
 		});
 
+		it("resetDisplay surfaces a state change hidden behind a component's render cache", async () => {
+			const term = new VirtualTerminal(20, 3);
+			const tui = new TUI(term);
+			const component = new CachedComponent(rows("L", 8));
+			tui.addChild(component);
+
+			try {
+				tui.start();
+				await settle(term);
+				expect(visible(term)).toEqual(["L5", "L6", "L7"]);
+
+				// The component's content changes, but its render stays cached (a
+				// frozen transcript snapshot). resetDisplay() must invalidate it so the
+				// forced replay reflects the new content rather than the stale cache —
+				// the Ctrl+O expansion path depends on this.
+				component.setLines(rows("M", 8));
+				tui.resetDisplay();
+				await settle(term);
+
+				expect(term.getScrollBuffer().map(line => line.trimEnd())).toEqual(rows("M", 8));
+				expect(visible(term)).toEqual(["M5", "M6", "M7"]);
+			} finally {
+				tui.stop();
+			}
+		});
+
 		it("keeps appended rows in scrollback when a forced render coalesces with content growth", async () => {
 			const term = new VirtualTerminal(20, 3);
 			const tui = new TUI(term);
diff --git a/packages/utils/CHANGELOG.md b/packages/utils/CHANGELOG.md
index 23eee711b..95442dc2a 100644
--- a/packages/utils/CHANGELOG.md
+++ b/packages/utils/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Changed
+
+- `logger.printTimings()` (the `PI_TIMING` startup tree) now surfaces two previously-invisible regions: a `(before instrumentation)` line for the runtime init + static module-graph load that elapses before the first marker (the dominant real-world startup cost, ~350ms — `startTiming()` only begins inside `runRootCommand`), and an `(unattributed self)` line for the root span's own untimed work so the gap between the visible top-level spans and `Total` is no longer silently swallowed. `Total` is now labelled `(since first marker)` to make the window explicit.
+
 ## [15.9.2] - 2026-06-05
 
 ### Added
diff --git a/packages/utils/src/logger.ts b/packages/utils/src/logger.ts
index ae0f7fd36..c682bbf8f 100644
--- a/packages/utils/src/logger.ts
+++ b/packages/utils/src/logger.ts
@@ -187,6 +187,13 @@ export function printTimings(): void {
 	const lines: string[] = [];
 	lines.push("");
 	lines.push("--- Startup timings (hierarchical) ---");
+	// performance.now() shares the process-start origin, so the root span's start
+	// is the wall time spent before the first marker — runtime init plus the
+	// static module-graph evaluation (~the dominant cost). It is otherwise
+	// invisible because Total only spans startTiming()→printTimings().
+	if (gRootSpan.start > LOGGED_TIMING_THRESHOLD_MS) {
+		lines.push(`(before instrumentation): ${fmtMs(gRootSpan.start)} [runtime init + module load]`);
+	}
 	const work: Span[] = [];
 	const loads: Span[] = [];
 	for (const child of gRootSpan.children) {
@@ -199,8 +206,14 @@ export function printTimings(): void {
 	if (loads.length > 0) {
 		printModuleLoadSummary(loads, 0, lines);
 	}
+	// Surface the root's own unattributed time so the gap between the visible
+	// top-level spans and Total isn't silently swallowed.
+	const rootSelf = selfTimeOf(gRootSpan);
+	if (gRootSpan.children.length > 0 && rootSelf > LOGGED_TIMING_THRESHOLD_MS) {
+		lines.push(`(unattributed self): ${fmtMs(rootSelf)}`);
+	}
 	const totalMs = (gRootSpan.end - gRootSpan.start).toFixed(1);
-	lines.push(`Total: ${totalMs}ms`);
+	lines.push(`Total: ${totalMs}ms (since first marker)`);
 	lines.push("--------------------------------------");
 	lines.push("");
 	console.error(lines.join("\n"));

From fde55bf927d059dfd638c8bcefca6ecbccb3f5f8 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:21:58 +0200
Subject: [PATCH 049/181] fix(model): added bracket-affix stripping and
 string-keyed resolution cache

- Replaced WeakMap model cache with provider/id string keys for stable reuse.
- Returned official model ids directly when matched, before heuristics.
- Collapsed non-message token path to system prompt and tool schema totals.
---
 .../src/config/model-equivalence.ts           | 31 ++++++---
 .../src/config/model-id-affixes.ts            | 61 ++++++++++-------
 .../src/modes/utils/context-usage.ts          | 16 +++--
 .../test/model-id-affixes.test.ts             | 66 +++++++++++++++++++
 .../test/status-line-context-cache.test.ts    | 34 ++++++++++
 5 files changed, 171 insertions(+), 37 deletions(-)
 create mode 100644 packages/coding-agent/test/model-id-affixes.test.ts

diff --git a/packages/coding-agent/src/config/model-equivalence.ts b/packages/coding-agent/src/config/model-equivalence.ts
index 28ae3744a..e30755b2d 100644
--- a/packages/coding-agent/src/config/model-equivalence.ts
+++ b/packages/coding-agent/src/config/model-equivalence.ts
@@ -58,7 +58,7 @@ const EMPTY_COMPILED_EQUIVALENCE: CompiledEquivalenceConfig = {
 };
 const kModelResolutionCache = Symbol("model-equivalence.resolutionCache");
 interface CompiledEquivalenceConfigWithCache extends CompiledEquivalenceConfig {
-	[kModelResolutionCache]?: WeakMap<Model<Api>, ResolvedCanonicalModel>;
+	[kModelResolutionCache]?: Map<string, ResolvedCanonicalModel>;
 }
 const FAMILY_EXTRACTION_PATTERNS = [
 	/(?:^|[/:._-])((?:claude|gemini|gpt|grok|glm|qwen|minimax|kimi|deepseek|llama|gemma|nova|mistral|ministral|pixtral|codestral|devstral|magistral|ernie|doubao|seed|aion|olmo|molmo|nemotron|palmyra|command|codex|coder|o[1345])[-a-z0-9.]+)(?::|$)/i,
@@ -128,10 +128,18 @@ function normalizeCanonicalIdKey(canonicalId: string): string {
 	return canonicalId.trim().toLowerCase();
 }
 
+function getCanonicalSuffixAliasKey(candidate: string): string {
+	return PENALTY_HAS_UPPERCASE.test(candidate) ? normalizeCanonicalIdKey(candidate) : candidate;
+}
+
 export function formatCanonicalVariantSelector(model: Model<Api>): string {
 	return `${model.provider}/${model.id}`;
 }
 
+function getModelResolutionCacheKey(model: Model<Api>): string {
+	return `${model.provider}\0${model.id}`;
+}
+
 function buildOverrideMap(overrides: Record<string, string> | undefined): Map<string, string> {
 	const result = new Map<string, string>();
 	if (!overrides) {
@@ -728,10 +736,10 @@ function getPreferredFallbackCanonicalCandidate(modelId: string, candidates: rea
 
 function resolveCanonicalIdForModel(
 	model: Model<Api>,
+	selector: string,
 	equivalence: CompiledEquivalenceConfig,
 	referenceData: CanonicalReferenceData,
 ): ResolvedCanonicalModel {
-	const selector = formatCanonicalVariantSelector(model);
 	const normalizedSelector = normalizeSelectorKey(selector);
 
 	if (equivalence.overrides.has(normalizedSelector)) {
@@ -752,10 +760,14 @@ function resolveCanonicalIdForModel(
 		return { id: claudeFamilyAlias, source: claudeFamilyAlias === model.id ? "bundled" : "heuristic" };
 	}
 
+	if (referenceData.officialIds.has(model.id) && !model.id.includes("/") && !model.id.includes(":")) {
+		return { id: model.id, source: "bundled" };
+	}
+
 	const heuristicCandidates = getHeuristicCanonicalCandidates(model.id, referenceData.officialIds);
 	const officialMatches = new Set(heuristicCandidates.filter(candidate => referenceData.officialIds.has(candidate)));
 	for (const candidate of heuristicCandidates) {
-		const aliased = referenceData.suffixAliases.get(normalizeCanonicalIdKey(candidate));
+		const aliased = referenceData.suffixAliases.get(getCanonicalSuffixAliasKey(candidate));
 		if (aliased) {
 			officialMatches.add(aliased);
 		}
@@ -814,17 +826,18 @@ export function buildCanonicalModelIndex(
 	const compiledWithCache = compiledEquivalence as CompiledEquivalenceConfigWithCache;
 	let modelCache = compiledWithCache[kModelResolutionCache];
 	if (!modelCache) {
-		modelCache = new WeakMap<Model<Api>, ResolvedCanonicalModel>();
+		modelCache = new Map<string, ResolvedCanonicalModel>();
 		compiledWithCache[kModelResolutionCache] = modelCache;
 	}
 
 	for (const model of models) {
-		let canonical = modelCache.get(model);
-		if (!canonical) {
-			canonical = resolveCanonicalIdForModel(model, compiledEquivalence, referenceData);
-			modelCache.set(model, canonical);
-		}
 		const selector = formatCanonicalVariantSelector(model);
+		const cacheKey = getModelResolutionCacheKey(model);
+		let canonical = modelCache.get(cacheKey);
+		if (!canonical) {
+			canonical = resolveCanonicalIdForModel(model, selector, compiledEquivalence, referenceData);
+			modelCache.set(cacheKey, canonical);
+		}
 		const variant: CanonicalModelVariant = {
 			canonicalId: canonical.id,
 			selector,
diff --git a/packages/coding-agent/src/config/model-id-affixes.ts b/packages/coding-agent/src/config/model-id-affixes.ts
index b4aff136f..7cec31892 100644
--- a/packages/coding-agent/src/config/model-id-affixes.ts
+++ b/packages/coding-agent/src/config/model-id-affixes.ts
@@ -4,34 +4,49 @@ const MODEL_ID_SEGMENT_PATTERN = /[a-z0-9.:-]+/g;
 const MODEL_FAMILY_PREFIX_PATTERN =
 	/^(claude|gemini|gpt|grok|glm|qwen|deepseek|kimi|mimo|doubao|ernie|gpt-oss|gemma|minimax|step|command|jamba|llama|o[1345])/i;
 
-function hasDigit(value: string): boolean {
-	return /\d/.test(value);
+function normalizeModelIdWhitespace(value: string): string {
+	return value.trim().replace(/\s+/g, " ");
 }
 
+/** Ordering for model-like segments: longest first, ties broken lexicographically. */
 function compareSegmentPreference(left: string, right: string): number {
-	if (left.length !== right.length) {
-		return right.length - left.length;
-	}
-	return left.localeCompare(right);
+	return left.length !== right.length ? right.length - left.length : left.localeCompare(right);
 }
 
 export function getModelLikeIdSegments(modelId: string): string[] {
-	const normalized = normalizeModelIdWhitespace(modelId).toLowerCase();
-	if (!normalized) return [];
-	const segments = (normalized.match(MODEL_ID_SEGMENT_PATTERN) ?? []).filter(
-		segment => MODEL_FAMILY_PREFIX_PATTERN.test(segment) && hasDigit(segment),
-	);
-	const unique = [...new Set(segments)];
-	unique.sort(compareSegmentPreference);
-	return unique;
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return [];
+	const segments = new Set<string>();
+	for (const segment of matches) {
+		if (MODEL_FAMILY_PREFIX_PATTERN.test(segment) && /\d/.test(segment)) segments.add(segment);
+	}
+	return [...segments].sort(compareSegmentPreference);
 }
 
 export function getLongestModelLikeIdSegment(modelId: string): string | undefined {
-	return getModelLikeIdSegments(modelId)[0];
+	const matches = normalizeModelIdWhitespace(modelId).toLowerCase().match(MODEL_ID_SEGMENT_PATTERN);
+	if (!matches) return undefined;
+	let best: string | undefined;
+	for (const segment of matches) {
+		if (
+			MODEL_FAMILY_PREFIX_PATTERN.test(segment) &&
+			/\d/.test(segment) &&
+			(best === undefined || compareSegmentPreference(segment, best) < 0)
+		) {
+			best = segment;
+		}
+	}
+	return best;
 }
 
-function normalizeModelIdWhitespace(value: string): string {
-	return value.trim().replace(/\s+/g, " ");
+function hasBracketAffixMarker(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code === 91 || code === 93 || code === 0x3010 || code === 0x3011) {
+			return true;
+		}
+	}
+	return false;
 }
 
 /**
@@ -39,18 +54,20 @@ function normalizeModelIdWhitespace(value: string): string {
  * upstream model id, e.g.
  *   "[Kiro] claude-opus-4-8"                -> "claude-opus-4-8"
  *   "[gcli转] gemini-3.1-pro-preview [假流]" -> "gemini-3.1-pro-preview"
+ *
+ * Candidates are returned most-stripped first: both ends, then leading-only, then trailing-only.
  */
 export function getBracketStrippedModelIdCandidates(modelId: string): string[] {
+	if (!hasBracketAffixMarker(modelId)) return [];
 	const normalized = normalizeModelIdWhitespace(modelId);
 	if (!normalized) return [];
 
-	const candidates = new Set<string>();
-	const withoutLeading = normalizeModelIdWhitespace(normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, ""));
+	const strippedLeading = normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, "");
+	const withoutLeading = normalizeModelIdWhitespace(strippedLeading);
 	const withoutTrailing = normalizeModelIdWhitespace(normalized.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
-	const withoutBoth = normalizeModelIdWhitespace(
-		normalized.replace(LEADING_BRACKETED_AFFIX_PATTERN, "").replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""),
-	);
+	const withoutBoth = normalizeModelIdWhitespace(strippedLeading.replace(TRAILING_BRACKETED_AFFIX_PATTERN, ""));
 
+	const candidates = new Set<string>();
 	for (const candidate of [withoutBoth, withoutLeading, withoutTrailing]) {
 		if (candidate && candidate !== normalized) {
 			candidates.add(candidate);
diff --git a/packages/coding-agent/src/modes/utils/context-usage.ts b/packages/coding-agent/src/modes/utils/context-usage.ts
index fd93070a8..d223d9a5e 100644
--- a/packages/coding-agent/src/modes/utils/context-usage.ts
+++ b/packages/coding-agent/src/modes/utils/context-usage.ts
@@ -37,6 +37,9 @@ export interface ContextBreakdown {
 	freeTokens: number;
 }
 
+const EMPTY_STRING_PARTS: readonly string[] = [];
+const EMPTY_TOOLS: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">> = [];
+
 export function estimateSkillsTokens(skills: readonly Skill[]): number {
 	const fragments: string[] = [];
 	for (const skill of skills) {
@@ -75,15 +78,16 @@ export function estimateToolSchemaTokens(
  * messages walked incrementally as new entries append.
  */
 export function computeNonMessageTokens(session: AgentSession): number {
-	const parts = computeNonMessageBreakdown(session);
-	return parts.systemPromptTokens + parts.systemContextTokens + parts.toolsTokens + parts.skillsTokens;
+	const systemPromptParts = session.systemPrompt ?? EMPTY_STRING_PARTS;
+	const tools = session.agent?.state?.tools ?? EMPTY_TOOLS;
+	return countTokens(systemPromptParts) + estimateToolSchemaTokens(tools);
 }
 
 /**
- * Shared helper for the four non-message token totals. Single source of truth
- * for both `computeNonMessageTokens` (status-line incremental cache) and
- * `computeContextBreakdown` (/context panel). The split avoids drift between
- * the two surfaces — they MUST report the same numbers.
+ * Shared helper for the four non-message token totals used by
+ * `computeContextBreakdown` (/context panel). Keep this category split stable:
+ * the status-line fast path intentionally uses the equivalent collapsed total
+ * in `computeNonMessageTokens`.
  */
 function computeNonMessageBreakdown(session: AgentSession): {
 	skillsTokens: number;
diff --git a/packages/coding-agent/test/model-id-affixes.test.ts b/packages/coding-agent/test/model-id-affixes.test.ts
new file mode 100644
index 000000000..b94a9bc48
--- /dev/null
+++ b/packages/coding-agent/test/model-id-affixes.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import {
+	getBracketStrippedModelIdCandidates,
+	getLongestModelLikeIdSegment,
+	getModelLikeIdSegments,
+	stripBracketedModelIdAffixes,
+} from "../src/config/model-id-affixes";
+
+describe("getModelLikeIdSegments", () => {
+	test("keeps only family-prefixed segments that carry a digit, deduped", () => {
+		expect(getModelLikeIdSegments("openrouter/anthropic/claude-3.5-sonnet")).toEqual(["claude-3.5-sonnet"]);
+		// `random-text` lacks a family prefix; `claude` (no digit) is dropped.
+		expect(getModelLikeIdSegments("random-text claude gemini-2")).toEqual(["gemini-2"]);
+	});
+
+	test("orders longest first with lexicographic tie-break", () => {
+		expect(getModelLikeIdSegments("claude-3 claude-3-5-haiku claude-2")).toEqual([
+			"claude-3-5-haiku",
+			"claude-2",
+			"claude-3",
+		]);
+	});
+
+	test("normalizes whitespace and case before matching", () => {
+		expect(getModelLikeIdSegments("  GLM-4.5-Air   GEMINI-2  ")).toEqual(["glm-4.5-air", "gemini-2"]);
+	});
+
+	test("returns empty for ids with no model-like segment", () => {
+		expect(getModelLikeIdSegments("")).toEqual([]);
+		expect(getModelLikeIdSegments("just some words")).toEqual([]);
+	});
+});
+
+describe("getLongestModelLikeIdSegment", () => {
+	test("matches getModelLikeIdSegments[0]", () => {
+		const id = "[Kiro] claude-3 claude-3-5-sonnet";
+		expect(getLongestModelLikeIdSegment(id)).toBe(getModelLikeIdSegments(id)[0]);
+		expect(getLongestModelLikeIdSegment(id)).toBe("claude-3-5-sonnet");
+	});
+
+	test("is undefined when nothing matches", () => {
+		expect(getLongestModelLikeIdSegment("vendor/unknown-tag")).toBeUndefined();
+	});
+});
+
+describe("getBracketStrippedModelIdCandidates", () => {
+	test("no brackets yields no candidates", () => {
+		expect(getBracketStrippedModelIdCandidates("claude-opus-4-8")).toEqual([]);
+	});
+
+	test("strips leading reseller tag", () => {
+		expect(getBracketStrippedModelIdCandidates("[Kiro] claude-opus-4-8")).toEqual(["claude-opus-4-8"]);
+	});
+
+	test("strips both ends first, then each side, in preference order", () => {
+		expect(getBracketStrippedModelIdCandidates("[gcli转] gemini-3.1-pro-preview [假流]")).toEqual([
+			"gemini-3.1-pro-preview",
+			"gemini-3.1-pro-preview [假流]",
+			"[gcli转] gemini-3.1-pro-preview",
+		]);
+	});
+
+	test("supports full-width brackets", () => {
+		expect(stripBracketedModelIdAffixes("【供应商】 deepseek-v3 【限时】")).toBe("deepseek-v3");
+	});
+});
diff --git a/packages/coding-agent/test/status-line-context-cache.test.ts b/packages/coding-agent/test/status-line-context-cache.test.ts
index 7abacdfdd..95ff25dc5 100644
--- a/packages/coding-agent/test/status-line-context-cache.test.ts
+++ b/packages/coding-agent/test/status-line-context-cache.test.ts
@@ -15,8 +15,10 @@
  * (messages.length shrinks) resets the cache.
  */
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { countTokens } from "@oh-my-pi/pi-natives";
 import { resetSettingsForTest, Settings } from "../src/config/settings";
 import { StatusLineComponent } from "../src/modes/components/status-line";
+import { computeNonMessageTokens, estimateToolSchemaTokens } from "../src/modes/utils/context-usage";
 import { initTheme } from "../src/modes/theme/theme";
 import type { AgentSession } from "../src/session/agent-session";
 
@@ -122,6 +124,38 @@ describe("StatusLineComponent incremental context breakdown cache", () => {
 		expect(v3.usedTokens).toBeGreaterThan(v2.usedTokens);
 	});
 
+	it("non-message token shortcut matches previous category sum semantics", () => {
+		const session = makeSession({
+			messages: [],
+			systemPrompt: [
+				"You are an assistant.\n\n<skills>\n- code: Write code\n- review: Review code\n</skills>",
+				"Loaded context file",
+				"Runtime note",
+			],
+			tools: [
+				{
+					name: "bash",
+					description: "Run shell commands",
+					parameters: { type: "object", properties: { command: { type: "string" } } },
+				},
+			],
+			skills: [
+				{ name: "code", description: "Write code" },
+				{ name: "review", description: "Review code" },
+			],
+		});
+
+		const skillsTokens = countTokens(["code", "Write code", "review", "Review code"]);
+		const previousCategorySum =
+			Math.max(0, countTokens(session.systemPrompt?.[0] ?? "") - skillsTokens) +
+			countTokens((session.systemPrompt ?? []).slice(1)) +
+			estimateToolSchemaTokens(session.agent?.state?.tools ?? []) +
+			skillsTokens;
+
+		expect(new StatusLineComponent(session).getCachedContextBreakdown().usedTokens).toBe(previousCategorySum);
+		expect(computeNonMessageTokens(session)).toBe(previousCategorySum);
+	});
+
 	it("zero messages: produces only non-message tokens, no crash", () => {
 		const session = makeSession({ messages: [] });
 		const comp = new StatusLineComponent(session);

From 67e6324aceb28e746f326002cffd08d0023ced1d Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 20:28:15 +0000
Subject: [PATCH 050/181] fix(tui): reduced row flicker while typing

Changed text row repaints to overwrite first and clear only stale suffixes so non-synchronized WSL/Windows Terminal paints do not visibly blank already-rendered rows. Kept full-line pre-clears for image protocol rows and preserved exact-width row handling.\n\nFixes #2011
---
 docs/tui-core-renderer.md                    |  2 +-
 packages/tui/CHANGELOG.md                    |  4 ++
 packages/tui/src/tui.ts                      | 33 +++++++++-------
 packages/tui/test/render-regressions.test.ts | 41 ++++++++++++++++----
 4 files changed, 59 insertions(+), 21 deletions(-)

diff --git a/docs/tui-core-renderer.md b/docs/tui-core-renderer.md
index dd984a830..3cc17f8b7 100644
--- a/docs/tui-core-renderer.md
+++ b/docs/tui-core-renderer.md
@@ -78,7 +78,7 @@ the bytes written and the state update. All state flows through a single
 | `sessionReplace` | clear viewport **+ ED3** (outside multiplexers) | caller forced `{ clearScrollback: true }` (switch/branch/reload/resume) |
 | `historyRebuild` | clear viewport **+ ED3** (outside multiplexers) | geometry change rewrapped history, or a proven-at-tail rebuild |
 | `overlayRebuild` | rebuild viewport with overlay composite | overlay visibility changed |
-| `liveRegionPinned` | relative moves + per-line `\x1b[2K` + `\r\n` | foreground streaming on an ED3-risk host, commit-as-you-go |
+| `liveRegionPinned` | relative moves + per-row rewrite/suffix-clear + `\r\n` | foreground streaming on an ED3-risk host, commit-as-you-go |
 | `viewportRepaint` | rewrite the visible viewport in place (optional `appendFrom` tail first) | safe non-destructive repaint |
 | `deferredShrink` | padded viewport repaint, history left dirty | bottom-anchored shrink, viewport unobservable |
 | `deferredMutation` | **zero bytes**, history left dirty | row-reindexing edit while possibly scrolled |
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index f5151aefa..81cfd3272 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed WSL/Windows Terminal row flicker while typing by repainting changed text rows before clearing only their stale suffix ([#2011](https://github.com/can1357/oh-my-pi/issues/2011)).
+
 ## [15.9.69] - 2026-06-06
 
 ### Added
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index c568d09ea..4e2e78a49 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -44,6 +44,8 @@ const SEGMENT_RESET = "\x1b[0m";
  * diffing so `#previousLines` mirrors what was actually written.
  */
 const LINE_TERMINATOR = "\x1b[0m\x1b]8;;\x07";
+const ERASE_LINE = "\x1b[2K";
+const ERASE_TO_END_OF_LINE = "\x1b[K";
 // Hide the hardware cursor before each paint/move write. Ghostty-style bar
 // cursors can otherwise leave visual afterimages while the TUI repaints the
 // row under a visible cursor. Paint writes also disable terminal autowrap:
@@ -2276,8 +2278,8 @@ export class TUI extends Container {
 		// Multiplexers (tmux/screen/zellij) cannot erase pane history with `\x1b[3J`
 		// and cannot answer a viewport-position probe, so the destructive checkpoint
 		// rebuild path is forever unavailable. The pinned emitter is built from the
-		// opposite primitives — relative cursor moves, per-line `\x1b[2K`, and
-		// `\r\n` to scroll sealed rows past the viewport bottom — which are exactly
+		// opposite primitives — relative cursor moves, per-row rewrite/suffix-clear,
+		// and `\r\n` to scroll sealed rows past the viewport bottom — which are exactly
 		// what tmux pane history accepts. Without this commit-as-you-go path, the
 		// streaming cap below clipped every frame to the visible tail and the
 		// scrolled-off head was committed nowhere (issue #1974).
@@ -2349,6 +2351,12 @@ export class TUI extends Container {
 		return truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
 	}
 
+	#lineRewriteSequence(line: string, width: number): string {
+		const fitted = this.#fitLineToWidth(line, width);
+		if (TERMINAL.isImageLine(fitted)) return ERASE_LINE + fitted;
+		return visibleWidth(fitted) >= width ? fitted : fitted + ERASE_TO_END_OF_LINE;
+	}
+
 	/**
 	 * Single state-transition point. Every emitter calls this exactly once at
 	 * the end so cursor/viewport/scrollback accounting stays consistent.
@@ -2515,8 +2523,7 @@ export class TUI extends Container {
 		let buffer = `${this.#paintBeginSequence}\x1b[H`;
 		for (let screenRow = 0; screenRow < height; screenRow++) {
 			if (screenRow > 0) buffer += "\r\n";
-			buffer += "\x1b[2K";
-			buffer += texts[screenRow];
+			buffer += this.#lineRewriteSequence(texts[screenRow], width);
 		}
 		// DECCARA rectangles paint the visible fills before cursor positioning;
 		// the cleared cells written above are what the rectangles repaint.
@@ -2554,8 +2561,8 @@ export class TUI extends Container {
 	 * leaving the transient live region out of saved lines.
 	 *
 	 * Uses only the no-scroll-snap vocabulary of {@link #emitDiff}: relative
-	 * cursor moves, per-line `\x1b[2K`, and `\r\n` to push the sealed chunk into
-	 * history. It deliberately avoids a full-screen erase (`\x1b[2J`) and absolute
+	 * cursor moves, per-row rewrite/suffix-clear, and `\r\n` to push the sealed
+	 * chunk into history. It deliberately avoids a full-screen erase (`\x1b[2J`) and absolute
 	 * cursor home (`\x1b[H`): on Ghostty those snap a reader scrolled into history
 	 * back to the bottom on every frame.
 	 */
@@ -2587,17 +2594,18 @@ export class TUI extends Container {
 
 		// Write the sealed chunk followed by the full viewport from the top row.
 		// The first (boundedAppendTo - boundedAppendFrom) rows scroll into native
-		// history; the trailing `height` rows fill the viewport. Each row clears
-		// itself with `\x1b[2K` instead of relying on a screen-wide erase.
+		// history; the trailing `height` rows fill the viewport. Text rows overwrite
+		// first and clear only the suffix so non-synchronized hosts do not visibly
+		// blank stable content before repainting it.
 		let wroteLine = false;
 		for (let i = boundedAppendFrom; i < boundedAppendTo; i++) {
 			if (wroteLine) buffer += "\r\n";
-			buffer += `\x1b[2K${this.#fitLineToWidth(lines[i] ?? "", width)}`;
+			buffer += this.#lineRewriteSequence(lines[i] ?? "", width);
 			wroteLine = true;
 		}
 		for (let screenRow = 0; screenRow < height; screenRow++) {
 			if (wroteLine) buffer += "\r\n";
-			buffer += `\x1b[2K${this.#fitLineToWidth(lines[viewportTop + screenRow] ?? "", width)}`;
+			buffer += this.#lineRewriteSequence(lines[viewportTop + screenRow] ?? "", width);
 			wroteLine = true;
 		}
 
@@ -2676,7 +2684,7 @@ export class TUI extends Container {
 		const currentScreenRow = Math.max(0, Math.min(height - 1, clampedCursor - prevViewportTop));
 		const moveDown = height - 1 - currentScreenRow;
 		if (moveDown > 0) buffer += `\x1b[${moveDown}B`;
-		buffer += `\r\x1b[2K${this.#fitLineToWidth(line, width)}\x1b[?25l`;
+		buffer += `\r${this.#lineRewriteSequence(line, width)}\x1b[?25l`;
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
 
@@ -2835,8 +2843,7 @@ export class TUI extends Container {
 		}
 		for (let i = firstChanged; i <= renderEnd; i++) {
 			if (i > firstChanged) buffer += "\r\n";
-			buffer += "\x1b[2K";
-			buffer += fillTexts && i >= fillStart ? fillTexts[i - fillStart] : this.#fitLineToWidth(lines[i], width);
+			buffer += this.#lineRewriteSequence(fillTexts && i >= fillStart ? fillTexts[i - fillStart] : lines[i], width);
 		}
 
 		// If the prior frame was taller, clear the trailing rows.
diff --git a/packages/tui/test/render-regressions.test.ts b/packages/tui/test/render-regressions.test.ts
index 1693cc817..bdd77ef2c 100644
--- a/packages/tui/test/render-regressions.test.ts
+++ b/packages/tui/test/render-regressions.test.ts
@@ -247,6 +247,33 @@ describe("TUI terminal-state regressions", () => {
 				tui.stop();
 			}
 		});
+		it("rewrites changed rows before clearing suffixes for non-synchronized hosts", async () => {
+			const term = new VirtualTerminal(40, 8);
+			const tui = new TUI(term);
+			const component = new MutableLinesComponent([
+				"assistant output already rendered",
+				"tool output already rendered",
+				"todos/status already rendered",
+			]);
+			tui.addChild(component);
+
+			try {
+				tui.start();
+				await settle(term);
+				const writes = captureWrites(term);
+
+				component.setLines(["assistant output already rendered", "tool", "todos/status already rendered"]);
+				tui.requestRender();
+				await settle(term);
+
+				const paint = writes.at(-1) ?? "";
+				expect(paint).toContain("tool\x1b[0m\x1b[K");
+				expect(paint).not.toContain("\x1b[2Ktool");
+				expect(visible(term)[1]).toBe("tool");
+			} finally {
+				tui.stop();
+			}
+		});
 
 		it("clears removed tail lines after shrink", async () => {
 			const term = new VirtualTerminal(40, 10);
@@ -2142,7 +2169,7 @@ describe("TUI terminal-state regressions", () => {
 					expect(viewport.at(-1)).toBe("spinner-b");
 					expect(term.getScrollBuffer().join("\n")).not.toContain("edited-0");
 					const paint = writes.at(-1) ?? "";
-					expect(paint).toContain("\r\x1b[2Kspinner-b");
+					expect(paint).toContain("\rspinner-b\x1b[0m\x1b[K");
 					expect(paint).not.toContain("\x1b[H");
 					expect(paint).not.toContain("\x1b[3J");
 				} finally {
@@ -2170,7 +2197,7 @@ describe("TUI terminal-state regressions", () => {
 					expect(visible(scrolledTerm).map(line => line.trim())).toEqual(beforeViewport);
 					expect(scrolledTerm.getScrollBuffer().join("\n")).not.toContain("edited-0");
 					const paint = writes.at(-1) ?? "";
-					expect(paint).toContain("\r\x1b[2Kspinner-b");
+					expect(paint).toContain("\rspinner-b\x1b[0m\x1b[K");
 					expect(paint).not.toContain("\x1b[H");
 					expect(paint).not.toContain("\x1b[3J");
 				} finally {
@@ -3426,8 +3453,8 @@ describe("TUI terminal-state regressions", () => {
 				// Initial paint: only the styled row carries background cells.
 				expect(backgroundRows(term, height)).toEqual([1]);
 
-				// Diff path: rewriting the row below starts with \x1b[2K — with leaked
-				// background, BCE would paint that whole row red.
+				// Diff path: rewriting the row below clears only after the row reset;
+				// with leaked background, BCE would otherwise paint that row red.
 				component.setLines(["plain-0", UNRESET_BG_ROW, "EDITED-2"]);
 				tui.requestRender();
 				await settle(term);
@@ -3459,8 +3486,8 @@ describe("TUI terminal-state regressions", () => {
 				expect(foregroundRows(term, height)).toEqual([1]);
 				expect(underlineRows(term, height)).toEqual([1]);
 
-				// Rewriting the next row starts with an erase; leaked SGR would make
-				// the edited row green/underlined despite containing plain text.
+				// Rewriting the next row clears only after the row reset; leaked SGR
+				// would make the edited row green/underlined despite containing plain text.
 				component.setLines(["plain-0", UNRESET_FG_UNDERLINE_ROW, "EDITED-2"]);
 				tui.requestRender();
 				await settle(term);
@@ -3495,7 +3522,7 @@ describe("TUI terminal-state regressions", () => {
 				tui.start();
 				await settle(term);
 
-				// Force a full repaint (viewport rewrite path emits \x1b[2K per row).
+				// Force a full repaint (viewport rewrite path suffix-clears each text row).
 				tui.requestRender(true);
 				await settle(term);
 

From 4bf9a92b28adf554e48c9efd2d9a74bafffa6efa Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:48:31 +0200
Subject: [PATCH 051/181] feat(utils): added module-load timing preload and DAG
 report

- Added Bun preload that records inclusive per-module windows and resolved static import edges via plugin hooks.
- Shared events through a dependency-free buffer so the preload and logger avoid importing each other.
- Rendered module spans as a body/TLA-ranked dependency tree, separating graph wait from top-level work.
- Back-folded captured load phase into the root window to shrink the opaque pre-instrumentation figure.
---
 packages/coding-agent/scripts/dev-launch |   4 +
 packages/utils/CHANGELOG.md              |   2 +-
 packages/utils/src/logger.ts             | 200 ++++++++++++++++++++---
 packages/utils/src/module-timer.ts       | 148 +++++++++++++++++
 packages/utils/src/timing-buffer.ts      |  47 ++++++
 5 files changed, 377 insertions(+), 24 deletions(-)
 create mode 100644 packages/utils/src/module-timer.ts
 create mode 100644 packages/utils/src/timing-buffer.ts

diff --git a/packages/coding-agent/scripts/dev-launch b/packages/coding-agent/scripts/dev-launch
index 519ccff0f..c187c6161 100755
--- a/packages/coding-agent/scripts/dev-launch
+++ b/packages/coding-agent/scripts/dev-launch
@@ -28,6 +28,7 @@ done
 scripts_dir=$(CDPATH= cd -- "$(dirname -- "$self")" && pwd -P)
 cli=$scripts_dir/../src/cli.ts
 preload=$scripts_dir/dev-launch-preload.ts
+timing_preload=$scripts_dir/../../utils/src/module-timer.ts
 
 launch_dir=${OMP_DEV_LAUNCH_DIR:-${HOME}/.omp/.dev-cwd}
 mkdir -p "$launch_dir"
@@ -35,4 +36,7 @@ mkdir -p "$launch_dir"
 OMP_LAUNCH_CWD=$PWD
 export OMP_LAUNCH_CWD
 cd "$launch_dir"
+if [ -n "${PI_TIMING:-}" ]; then
+	exec bun --preload "$preload" --preload "$timing_preload" "$cli" "$@"
+fi
 exec bun --preload "$preload" "$cli" "$@"
diff --git a/packages/utils/CHANGELOG.md b/packages/utils/CHANGELOG.md
index 95442dc2a..ae4d73f15 100644
--- a/packages/utils/CHANGELOG.md
+++ b/packages/utils/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Changed
 
-- `logger.printTimings()` (the `PI_TIMING` startup tree) now surfaces two previously-invisible regions: a `(before instrumentation)` line for the runtime init + static module-graph load that elapses before the first marker (the dominant real-world startup cost, ~350ms — `startTiming()` only begins inside `runRootCommand`), and an `(unattributed self)` line for the root span's own untimed work so the gap between the visible top-level spans and `Total` is no longer silently swallowed. `Total` is now labelled `(since first marker)` to make the window explicit.
+- `logger.printTimings()` (the `PI_TIMING` startup tree) now surfaces two previously-invisible regions: a `(before instrumentation)` line for runtime init / uncaptured pre-marker work, and an `(unattributed self)` line for the root span's own untimed work so the gap between visible top-level spans and `Total` is no longer swallowed. `Total` is now labelled `(since first marker)` to make the window explicit. The restored `module-timer.ts` preload can feed module spans into the report: each module records `onLoad` → final top-level marker as `total`, a prepended body marker → final marker as `body/TLA`, and resolved static imports as a bounded dependency tree so the report separates graph wait from actual top-level module work.
 
 ## [15.9.2] - 2026-06-05
 
diff --git a/packages/utils/src/logger.ts b/packages/utils/src/logger.ts
index c682bbf8f..1591e1620 100644
--- a/packages/utils/src/logger.ts
+++ b/packages/utils/src/logger.ts
@@ -15,6 +15,7 @@ import { isPromise } from "node:util/types";
 import winston from "winston";
 import DailyRotateFile from "winston-daily-rotate-file";
 import { getLogsDir } from "./dirs";
+import { drainModuleLoadEvents } from "./timing-buffer";
 
 /** Ensure a logs directory exists; return the resolved path. */
 function ensureDir(dir: string): string {
@@ -166,12 +167,36 @@ interface Span {
 	children: Span[];
 	/** Marker / point event without a duration. */
 	point?: boolean;
+	/** Absolute module path for module-load spans. */
+	modulePath?: string;
+	/** Own top-level module body / TLA duration for module-load spans. */
+	moduleBodyMs?: number;
+	/** Resolved static imports for module-load spans. */
+	moduleImports?: string[];
 }
-
 const spanStorage = new AsyncLocalStorage<Span>();
 let gRootSpan: Span | undefined;
 let gRecordTimings = false;
 
+export function timingModeIncludes(option: "full" | "x"): boolean {
+	const value = process.env.PI_TIMING;
+	if (!value) return false;
+	if (value === option) return true;
+	let start = 0;
+	for (let i = 0; i <= value.length; i++) {
+		const code = i === value.length ? 44 : value.charCodeAt(i);
+		const separator = code === 44 || code === 58 || code === 59 || code === 43 || code <= 32;
+		if (!separator) continue;
+		if (i > start && value.slice(start, i) === option) return true;
+		start = i + 1;
+	}
+	return false;
+}
+
+export function shouldExitAfterTimings(): boolean {
+	return timingModeIncludes("x") || timingModeIncludes("full");
+}
+
 /**
  * Print collected timings as an indented tree.
  * Each span shows wall duration; parents with children also show "(self)" for unattributed time.
@@ -184,13 +209,19 @@ export function printTimings(): void {
 	}
 
 	gRootSpan.end = performance.now();
+	// Splice any preload-captured module-load events into the tree as root
+	// children and back-extend the root window over them, so the static-import
+	// phase that ran before the first explicit marker becomes visible (the
+	// `(modules)` summary below) instead of being lumped into the opaque
+	// `(before instrumentation)` figure.
+	spliceModuleLoadBuffer();
 	const lines: string[] = [];
 	lines.push("");
 	lines.push("--- Startup timings (hierarchical) ---");
 	// performance.now() shares the process-start origin, so the root span's start
-	// is the wall time spent before the first marker — runtime init plus the
-	// static module-graph evaluation (~the dominant cost). It is otherwise
-	// invisible because Total only spans startTiming()→printTimings().
+	// is the wall time before the first marker — runtime init plus any module
+	// loads not captured below. With the module-load preload active this shrinks
+	// to ~runtime init because the load phase is back-folded into the window.
 	if (gRootSpan.start > LOGGED_TIMING_THRESHOLD_MS) {
 		lines.push(`(before instrumentation): ${fmtMs(gRootSpan.start)} [runtime init + module load]`);
 	}
@@ -222,8 +253,8 @@ export function printTimings(): void {
 
 /**
  * Begin recording startup timings under a new root span.
- * Idempotent: a second call while already recording is a no-op so that side-effect
- * starters (see module-timer.ts) and explicit starters (main.ts) can coexist.
+ * Idempotent: a second call while already recording is a no-op, so an explicit
+ * starter (main.ts) and any future early starter can coexist.
  */
 export function startTiming(): void {
 	if (gRecordTimings) return;
@@ -238,10 +269,16 @@ export function startTiming(): void {
 
 /**
  * Record an externally-measured span as a leaf child of the active span (or root
- * when no span is active). Used by the module-load timing plugin to splice load
- * events into the tree retroactively.
+ * when no span is active). Used by {@link spliceModuleLoadBuffer} to fold
+ * preload-captured module windows into the tree.
  */
-export function recordModuleLoadSpan(path: string, start: number, durationMs: number): void {
+export function recordModuleLoadSpan(
+	path: string,
+	start: number,
+	durationMs: number,
+	bodyMs?: number,
+	imports: string[] = [],
+): void {
 	if (!gRecordTimings || !gRootSpan) return;
 	const parent = spanStorage.getStore() ?? gRootSpan;
 	const span: Span = {
@@ -250,10 +287,32 @@ export function recordModuleLoadSpan(path: string, start: number, durationMs: nu
 		end: start + durationMs,
 		parent,
 		children: [],
+		modulePath: path,
+		moduleBodyMs: bodyMs,
+		moduleImports: imports,
 	};
 	parent.children.push(span);
 }
 
+/**
+ * Drain the preload's module-load buffer (see module-timer.ts) into the tree as
+ * `load:` children of the root, then back-extend the root window to the earliest
+ * captured read so the pre-marker load phase is counted in Total rather than
+ * hidden as `(before instrumentation)`. No-op when nothing was captured (e.g. no
+ * `--preload`, or a compiled binary where module reads are not interceptable).
+ */
+function spliceModuleLoadBuffer(): void {
+	if (!gRootSpan) return;
+	const events = drainModuleLoadEvents();
+	if (events.length === 0) return;
+	let earliest = gRootSpan.start;
+	for (const event of events) {
+		recordModuleLoadSpan(event.path, event.start, event.durationMs, event.bodyMs, event.imports);
+		if (event.start < earliest) earliest = event.start;
+	}
+	gRootSpan.start = earliest;
+}
+
 function shortenLoadPath(p: string): string {
 	const cwd = process.cwd();
 	if (p.startsWith(`${cwd}/`)) return p.slice(cwd.length + 1);
@@ -309,6 +368,16 @@ function fmtMs(ms: number): string {
 
 const MODULE_LOAD_PREFIX = "load:";
 const MODULE_LOAD_VERBOSE_TOP = 10;
+const MODULE_TREE_MAX_DEPTH = 5;
+const MODULE_TREE_ROOT_TOP = 5;
+const MODULE_TREE_CHILD_TOP = 8;
+
+interface ModuleTimingNode {
+	span: Span;
+	children: ModuleTimingNode[];
+	parents: number;
+	body: number;
+}
 
 function isModuleLoadSpan(span: Span): boolean {
 	return span.op.startsWith(MODULE_LOAD_PREFIX);
@@ -343,33 +412,118 @@ function printSpan(span: Span, depth: number, lines: string[]): void {
 	}
 }
 
-/** Collapse the (typically hundreds of) module-load spans into one summary line. */
+/** Render module-load spans as a dependency-aware DAG/tree. */
 function printModuleLoadSummary(loads: Span[], depth: number, lines: string[]): void {
 	const childIndent = "  ".repeat(depth);
 	const grandIndent = "  ".repeat(depth + 1);
 	let unionStart = Number.POSITIVE_INFINITY;
 	let unionEnd = 0;
-	let totalSelf = 0;
 	for (const span of loads) {
 		if (span.end === undefined) continue;
 		if (span.start < unionStart) unionStart = span.start;
 		if (span.end > unionEnd) unionEnd = span.end;
-		totalSelf += span.end - span.start;
 	}
 	const wall = unionEnd > unionStart ? unionEnd - unionStart : 0;
-	lines.push(`${childIndent}(modules): ${loads.length} loaded, wall ${fmtMs(wall)}, sum ${fmtMs(totalSelf)}`);
-	const showAll = process.env.PI_TIMING === "full";
-	const sorted = [...loads].sort((a, b) => durationOf(b) - durationOf(a));
-	const visible = showAll ? sorted : sorted.slice(0, MODULE_LOAD_VERBOSE_TOP);
-	for (const span of visible) {
-		const dur = durationOf(span);
-		if (dur < LOGGED_TIMING_THRESHOLD_MS) break;
-		const tag = isParallel(span) ? " [parallel]" : "";
-		lines.push(`${grandIndent}${span.op}: ${fmtMs(dur)}${tag}`);
+	const nodes = buildModuleTimingGraph(loads);
+	lines.push(`${childIndent}(modules): ${loads.length} loaded, wall ${fmtMs(wall)}`);
+	if (nodes.length === 0) return;
+
+	const showAll = timingModeIncludes("full");
+	const byBody = [...nodes].sort(compareModuleNodes);
+	const topBody = showAll ? byBody : byBody.slice(0, MODULE_LOAD_VERBOSE_TOP);
+	lines.push(`${grandIndent}top body/TLA:`);
+	for (const node of topBody) {
+		if (!showAll && node.body < LOGGED_TIMING_THRESHOLD_MS) break;
+		lines.push(`${grandIndent}  ${node.span.op}: body ${fmtMs(node.body)} (total ${fmtMs(durationOf(node.span))})`);
 	}
-	if (!showAll && sorted.length > MODULE_LOAD_VERBOSE_TOP) {
-		lines.push(`${grandIndent}… ${sorted.length - MODULE_LOAD_VERBOSE_TOP} more (PI_TIMING=full to show all)`);
+	if (!showAll && byBody.length > MODULE_LOAD_VERBOSE_TOP) {
+		lines.push(`${grandIndent}  … ${byBody.length - MODULE_LOAD_VERBOSE_TOP} more (PI_TIMING=full to show all)`);
 	}
+
+	const roots = nodes.filter(node => node.parents === 0);
+	const treeRoots = (roots.length > 0 ? roots : nodes).sort((a, b) => durationOf(b.span) - durationOf(a.span));
+	const visibleRoots = showAll ? treeRoots : treeRoots.slice(0, MODULE_TREE_ROOT_TOP);
+	lines.push(`${grandIndent}tree:`);
+	const rendered = new Set<string>();
+	for (const node of visibleRoots) {
+		renderModuleTimingNode(node, depth + 2, lines, rendered, new Set<string>(), showAll);
+	}
+	if (!showAll && treeRoots.length > MODULE_TREE_ROOT_TOP) {
+		lines.push(
+			`${grandIndent}  … ${treeRoots.length - MODULE_TREE_ROOT_TOP} more roots (PI_TIMING=full to show all)`,
+		);
+	}
+}
+
+function buildModuleTimingGraph(loads: Span[]): ModuleTimingNode[] {
+	const nodes = new Map<string, ModuleTimingNode>();
+	for (const span of loads) {
+		if (!span.modulePath || span.end === undefined) continue;
+		nodes.set(span.modulePath, { span, children: [], parents: 0, body: span.moduleBodyMs ?? 0 });
+	}
+	for (const node of nodes.values()) {
+		for (const childPath of node.span.moduleImports ?? []) {
+			const child = nodes.get(childPath);
+			if (!child || child === node) continue;
+			node.children.push(child);
+			child.parents++;
+		}
+	}
+	for (const node of nodes.values()) {
+		node.children.sort(compareModuleNodes);
+	}
+	return [...nodes.values()];
+}
+
+function compareModuleNodes(a: ModuleTimingNode, b: ModuleTimingNode): number {
+	const bodyDiff = b.body - a.body;
+	if (Math.abs(bodyDiff) > 0.001) return bodyDiff;
+	return durationOf(b.span) - durationOf(a.span);
+}
+
+function renderModuleTimingNode(
+	node: ModuleTimingNode,
+	depth: number,
+	lines: string[],
+	rendered: Set<string>,
+	ancestors: Set<string>,
+	showAll: boolean,
+): void {
+	const path = node.span.modulePath;
+	if (!path) return;
+	const indent = "  ".repeat(depth);
+	const total = durationOf(node.span);
+	if (!showAll && total < LOGGED_TIMING_THRESHOLD_MS && node.children.length === 0) return;
+	const wait = Math.max(0, total - node.body);
+	const shared = node.parents > 1 ? " [shared]" : "";
+	const timing =
+		node.body > LOGGED_TIMING_THRESHOLD_MS || node.children.length > 0
+			? ` (body ${fmtMs(node.body)}, wait ${fmtMs(wait)})`
+			: "";
+	const alreadyRendered = rendered.has(path);
+	const cycle = ancestors.has(path);
+	const suffix = cycle ? " [cycle]" : alreadyRendered ? " [already shown]" : "";
+	lines.push(`${indent}${node.span.op}: ${fmtMs(total)}${timing}${shared}${suffix}`);
+	if (cycle || alreadyRendered) return;
+	rendered.add(path);
+	ancestors.add(path);
+	if (!showAll && ancestors.size >= MODULE_TREE_MAX_DEPTH) {
+		if (node.children.length > 0) {
+			lines.push(`${indent}  … ${node.children.length} imports deeper (PI_TIMING=full to show all)`);
+		}
+		ancestors.delete(path);
+		return;
+	}
+	const visibleChildren = showAll ? node.children : node.children.slice(0, MODULE_TREE_CHILD_TOP);
+	for (const child of visibleChildren) {
+		renderModuleTimingNode(child, depth + 1, lines, rendered, ancestors, showAll);
+	}
+	if (!showAll && node.children.length > MODULE_TREE_CHILD_TOP) {
+		lines.push(
+			`${indent}  … ${node.children.length - MODULE_TREE_CHILD_TOP} more imports (PI_TIMING=full to show all)`,
+		);
+	}
+	ancestors.delete(path);
 }
 
 /** A span is parallel if it overlaps a sibling that started before it. */
diff --git a/packages/utils/src/module-timer.ts b/packages/utils/src/module-timer.ts
new file mode 100644
index 000000000..b0ed91d39
--- /dev/null
+++ b/packages/utils/src/module-timer.ts
@@ -0,0 +1,148 @@
+/**
+ * Module-load timing preload.
+ *
+ * `bun --preload .../module-timer.ts <entry>` installs Bun plugin hooks (only
+ * when `PI_TIMING` is set) that record an inclusive module window plus resolved
+ * static child edges:
+ *
+ *   onLoad start → appended end marker after the module's top-level body
+ *
+ * Events are pushed into a process-global buffer that {@link logger.printTimings}
+ * drains and renders as a module DAG/tree. Each module row can therefore show
+ * both total time and `self` time after subtracting child module intervals.
+ *
+ * Why a preload (and not a normal import): Bun reads the *entire* statically
+ * reachable graph before evaluating any module, so hooks installed from inside
+ * that graph cannot observe its own loading — they only catch later dynamically
+ * loaded modules. A preload runs first, so it sees the static-import phase that
+ * dominates startup.
+ *
+ * Kept dependency-free on purpose: the sole import is Bun's `plugin`, so this is
+ * cheap to preload before pi-utils (and winston) exist. The buffer is shared with
+ * the logger via a registry Symbol so neither side needs to import the other.
+ *
+ * **What is measured:** an inclusive per-module window. `onLoad` stamps the
+ * start before reading source; the returned source has a tiny marker appended at
+ * the end of the module. That marker runs after Bun parses/transpiles the module
+ * and after any top-level await in that module completes, so the duration
+ * includes read + parse/transpile + dependency wait + top-level execution/TLA.
+ * If a module throws before its final statement, no end marker is recorded.
+ *
+ * **Tree shape:** `onResolve` observes importer → specifier edges and resolves
+ * them with `Bun.resolveSync` without taking over Bun's real resolution. The
+ * logger renders these edges as a DAG/tree and computes module `self` time by
+ * subtracting the union of child intervals, avoiding misleading flat inclusive
+ * totals.
+ *
+ * **Coverage limits:**
+ * - TS/TSX only — intercepting `node_modules` CJS `.js`/`.cjs` and forcing ESM
+ *   breaks their default-export detection, so they are left to Bun's default path.
+ * - **Dev runs only.** In the compiled `omp` binary every module is pre-bundled
+ *   into bunfs, so `onLoad` never fires; profile with a `bun --preload` dev run.
+ */
+import { plugin } from "bun";
+import { moduleLoadBuffer } from "./timing-buffer";
+
+// Restrict to TS/TSX only. node_modules ships CommonJS `.js`/`.cjs` that Bun
+// auto-detects when loaded via its default path; if we intercept and return
+// `{ contents, loader: "js" }`, Bun forces ESM and CJS modules fail to load
+// (e.g. `Missing 'default' export`). Our own source tree (where the interesting
+// timing lives) is uniformly TypeScript, so a TS-only filter is both safe and
+// sufficient.
+const MODULE_LOADER_FILTER = /\.[mc]?tsx?$/;
+const MODULE_COMPLETE_KEY: symbol = Symbol.for("omp.moduleLoadComplete");
+const MODULE_BODY_START_KEY: symbol = Symbol.for("omp.moduleBodyStart");
+const STATIC_IMPORT_PATTERN =
+	/\b(?:import|export)\s+(?:type\s+)?(?:[^"']*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+
+type CompleteStore = Record<symbol, ((path: string) => void) | undefined>;
+
+function bodyStartMarker(path: string): string {
+	return `;globalThis[Symbol.for("omp.moduleBodyStart")]?.(${JSON.stringify(path)});\n`;
+}
+
+function completionMarker(path: string): string {
+	return `\n;globalThis[Symbol.for("omp.moduleLoadComplete")]?.(${JSON.stringify(path)});\n`;
+}
+
+function instrumentContents(path: string, contents: string): string {
+	const start = bodyStartMarker(path);
+	const end = completionMarker(path);
+	if (!contents.startsWith("#!")) return `${start}${contents}${end}`;
+	const newline = contents.indexOf("\n");
+	if (newline === -1) return `${contents}\n${start}${end}`;
+	return `${contents.slice(0, newline + 1)}${start}${contents.slice(newline + 1)}${end}`;
+}
+function importerDir(importer: string): string {
+	const slash = importer.lastIndexOf("/");
+	if (slash === -1) return ".";
+	return importer.slice(0, slash);
+}
+
+function childSetFor(importsByPath: Map<string, Set<string>>, path: string): Set<string> {
+	let children = importsByPath.get(path);
+	if (!children) {
+		children = new Set<string>();
+		importsByPath.set(path, children);
+	}
+	return children;
+}
+
+function addImportEdges(importsByPath: Map<string, Set<string>>, importer: string, contents: string): void {
+	STATIC_IMPORT_PATTERN.lastIndex = 0;
+	for (const match of contents.matchAll(STATIC_IMPORT_PATTERN)) {
+		const specifier = match[1] ?? match[2];
+		if (!specifier) continue;
+		try {
+			const resolved = Bun.resolveSync(specifier, importerDir(importer));
+			if (MODULE_LOADER_FILTER.test(resolved) && resolved !== importer) {
+				childSetFor(importsByPath, importer).add(resolved);
+			}
+		} catch {
+			// Leave Bun's real resolver/runtime to surface any error. This scanner is only an observer.
+		}
+	}
+}
+
+if (process.env.PI_TIMING) {
+	const buffer = moduleLoadBuffer();
+	const starts = new Map<string, number>();
+	const bodyStarts = new Map<string, number>();
+	const importsByPath = new Map<string, Set<string>>();
+	const store = globalThis as unknown as CompleteStore;
+	store[MODULE_BODY_START_KEY] = (path: string): void => {
+		bodyStarts.set(path, performance.now());
+	};
+	store[MODULE_COMPLETE_KEY] = (path: string): void => {
+		const start = starts.get(path);
+		if (start === undefined) return;
+		starts.delete(path);
+		const end = performance.now();
+		const bodyStart = bodyStarts.get(path);
+		bodyStarts.delete(path);
+		const imports = importsByPath.get(path);
+		buffer.push({
+			path,
+			start,
+			durationMs: end - start,
+			bodyMs: bodyStart === undefined ? undefined : end - bodyStart,
+			imports: imports ? [...imports] : [],
+		});
+	};
+
+	plugin({
+		name: "pi-module-load-timer",
+		setup(build) {
+			build.onLoad({ filter: MODULE_LOADER_FILTER }, async args => {
+				starts.set(args.path, performance.now());
+				childSetFor(importsByPath, args.path);
+				const contents = await Bun.file(args.path).text();
+				addImportEdges(importsByPath, args.path, contents);
+				return {
+					contents: instrumentContents(args.path, contents),
+					loader: args.path.endsWith(".tsx") ? "tsx" : "ts",
+				};
+			});
+		},
+	});
+}
diff --git a/packages/utils/src/timing-buffer.ts b/packages/utils/src/timing-buffer.ts
new file mode 100644
index 000000000..4208f9298
--- /dev/null
+++ b/packages/utils/src/timing-buffer.ts
@@ -0,0 +1,47 @@
+/**
+ * Shared contract between the {@link module-timer} preload and {@link logger}'s
+ * timing tree. Kept in its own dependency-free module so the preload can import
+ * it without pulling in winston (via logger) and the logger can drain the buffer
+ * without importing the Bun-plugin preload.
+ */
+
+export interface ModuleLoadEvent {
+	/** Absolute or Bun-resolved module path. */
+	path: string;
+	/** `performance.now()` timestamp captured at Bun `onLoad` entry. */
+	start: number;
+	/** Inclusive module window: `onLoad` entry → appended final marker. */
+	durationMs: number;
+	/** Own top-level body / TLA time: prepended body marker → appended final marker. */
+	bodyMs?: number;
+	/** Resolved static children imported by this module. */
+	imports: string[];
+}
+
+/**
+ * Registry-global key under which the preload accumulates module-load events.
+ * `Symbol.for` so both modules resolve the same symbol independently.
+ */
+const KEY: symbol = Symbol.for("omp.moduleLoadBuffer");
+
+type Store = Record<symbol, ModuleLoadEvent[] | undefined>;
+
+/** The append-only buffer the preload pushes into (created on first access). */
+export function moduleLoadBuffer(): ModuleLoadEvent[] {
+	const store = globalThis as unknown as Store;
+	let buffer = store[KEY];
+	if (!buffer) {
+		buffer = [];
+		store[KEY] = buffer;
+	}
+	return buffer;
+}
+
+/** Drain and return all buffered events, leaving the buffer empty. */
+export function drainModuleLoadEvents(): ModuleLoadEvent[] {
+	const store = globalThis as unknown as Store;
+	const buffer = store[KEY];
+	if (!buffer || buffer.length === 0) return [];
+	store[KEY] = [];
+	return buffer;
+}

From ed55880f37842c45a8c283aecc543705622d7e6a Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:49:12 +0200
Subject: [PATCH 052/181] fix(ai): fixed orphaned tool-call handling for
 responses providers

- Added `repairOrphanResponsesToolCalls` to append placeholder outputs for orphan calls.
- Updated `openai-codex/request-transformer.ts` to repair unmatched tool-call/input pairs.
- Wrapped `openai-responses.ts` and `azure-openai-responses.ts` with orphan call repair before request conversion.
- Added regression coverage for orphan call repair in Codex and Responses tests.
---
 packages/ai/CHANGELOG.md                      |   1 +
 .../src/providers/azure-openai-responses.ts   |   3 +-
 .../openai-codex/request-transformer.ts       | 110 +++++++++++++-----
 .../src/providers/openai-responses-shared.ts  |  53 +++++++++
 packages/ai/src/providers/openai-responses.ts |   3 +-
 packages/ai/test/openai-codex.test.ts         |  56 +++++++++
 .../openai-responses-orphan-repair.test.ts    |  69 +++++++++++
 7 files changed, 261 insertions(+), 34 deletions(-)
 create mode 100644 packages/ai/test/openai-responses-orphan-repair.test.ts

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 6088cf64f..e3cd50803 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -9,6 +9,7 @@
 - Fixed usage-report dedup ignoring `projectId` for Google Cloud providers, preventing duplicate credential entries from being recognized as the same account.
 
 - Fixed Cloud Code Assist (Antigravity / Gemini CLI) rejecting the `github` tool with HTTP 400 when the `pr` parameter schema contained `anyOf: [string, array]`. The CCA mixed-type combiner collapse picked the first non-null type (`string`) but indiscriminately copied type-specific keys from variant branches — `items` from the array variant leaked onto the string-typed result, producing `{type: "string", items: {...}}` which Google's API rejects as invalid. The collapse now filters merged variant fields against the winning type's allowed key set. ([#2002](https://github.com/can1357/oh-my-pi/pull/2002))
+- Fixed OpenAI Responses-family providers (Codex, OpenAI Responses, Azure Responses) rejecting requests with `400 No tool output found for function call …` after the user branched/navigated the session tree to a node that ends on a tool call (the tool-result child is dropped from the reconstructed history) or after a turn was aborted/crashed between the call streaming and its result persisting. The converters now synthesize a placeholder `function_call_output`/`custom_tool_call_output` immediately after any unpaired `function_call`/`custom_tool_call`, symmetric to the existing orphan-output repair, so the model still sees the call and can recover instead of the whole request 400ing.
 ### Fixed
 
 - Fixed Anthropic-compatible reasoning endpoints losing prior-turn reasoning on continuation requests when they emit unsigned `thinking` blocks. `convertAnthropicMessages` treated unknown endpoints as signature-enforcing and demoted unsigned reasoning to `type: "text"`, which destabilized tool-call argument serialization on the next turn — the upstream symptom behind the `args?.ops?.map is not a function` crash reported against the `todo` tool. Official `api.anthropic.com` keeps the conservative text fallback; non-official `anthropic-messages` reasoning models now replay unsigned reasoning as native `type: "thinking"` ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
diff --git a/packages/ai/src/providers/azure-openai-responses.ts b/packages/ai/src/providers/azure-openai-responses.ts
index 04027d02a..26b3f0a16 100644
--- a/packages/ai/src/providers/azure-openai-responses.ts
+++ b/packages/ai/src/providers/azure-openai-responses.ts
@@ -40,6 +40,7 @@ import {
 	isOpenAIResponsesProgressEvent,
 	normalizeResponsesToolCallIdForTransform,
 	processResponsesStream,
+	repairOrphanResponsesToolCalls,
 } from "./openai-responses-shared";
 import { transformMessages } from "./transform-messages";
 
@@ -347,7 +348,7 @@ function convertMessages(
 		msgIndex++;
 	}
 
-	return messages;
+	return repairOrphanResponsesToolCalls(messages);
 }
 
 function convertTools(tools: Tool[]): OpenAITool[] {
diff --git a/packages/ai/src/providers/openai-codex/request-transformer.ts b/packages/ai/src/providers/openai-codex/request-transformer.ts
index f271bbc81..a12996ca6 100644
--- a/packages/ai/src/providers/openai-codex/request-transformer.ts
+++ b/packages/ai/src/providers/openai-codex/request-transformer.ts
@@ -76,6 +76,83 @@ function filterInput(input: InputItem[] | undefined): InputItem[] | undefined {
 		});
 }
 
+const CODEX_ORPHAN_OUTPUT_LIMIT = 16_000;
+/** Placeholder output for a tool call whose result never landed in the input. */
+const CODEX_INTERRUPTED_TOOL_OUTPUT =
+	"[No tool output recorded: the tool call was interrupted before it produced a result.]";
+
+function orphanFunctionOutputToMessage(item: InputItem, callId: string): InputItem {
+	const itemRecord = item as unknown as Record<string, unknown>;
+	const toolName = typeof itemRecord.name === "string" ? itemRecord.name : "tool";
+	let text = "";
+	try {
+		const output = itemRecord.output;
+		text = typeof output === "string" ? output : JSON.stringify(output);
+	} catch {
+		text = String(itemRecord.output ?? "");
+	}
+	if (text.length > CODEX_ORPHAN_OUTPUT_LIMIT) {
+		text = `${text.slice(0, CODEX_ORPHAN_OUTPUT_LIMIT)}\n...[truncated]`;
+	}
+	return {
+		type: "message",
+		role: "assistant",
+		content: `[Previous ${toolName} result; call_id=${callId}]: ${text}`,
+	} as InputItem;
+}
+
+/**
+ * Repair both halves of unpaired tool exchanges so the Responses input grammar
+ * stays valid — the API rejects either orphan with a 400:
+ *
+ * - `function_call_output` with no matching `function_call` → folded into an
+ *   assistant message (`400 No tool call found for function call output …`).
+ *   Regression of #472 / #1351.
+ * - `function_call` / `custom_tool_call` with no matching `*_output` → a
+ *   placeholder output is synthesized immediately after the call
+ *   (`400 No tool output found for function call …`). Hit when the user
+ *   branches/navigates the session tree to a node that ends on a tool call (the
+ *   tool-result child is dropped from the reconstructed history) or when a turn
+ *   is aborted/crashes after the call streamed but before its result persisted.
+ */
+function repairToolCallPairs(input: InputItem[]): InputItem[] {
+	const callIds = new Set<string>();
+	const outputCallIds = new Set<string>();
+	for (const item of input) {
+		const callId = typeof item.call_id === "string" ? item.call_id : undefined;
+		if (callId === undefined) continue;
+		if (item.type === "function_call" || item.type === "custom_tool_call") callIds.add(callId);
+		else if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
+			outputCallIds.add(callId);
+		}
+	}
+
+	const repaired: InputItem[] = [];
+	for (const item of input) {
+		const callId = typeof item.call_id === "string" ? item.call_id : undefined;
+
+		if (item.type === "function_call_output" && callId !== undefined && !callIds.has(callId)) {
+			repaired.push(orphanFunctionOutputToMessage(item, callId));
+			continue;
+		}
+
+		repaired.push(item);
+
+		if (
+			(item.type === "function_call" || item.type === "custom_tool_call") &&
+			callId !== undefined &&
+			!outputCallIds.has(callId)
+		) {
+			repaired.push({
+				type: item.type === "custom_tool_call" ? "custom_tool_call_output" : "function_call_output",
+				call_id: callId,
+				output: CODEX_INTERRUPTED_TOOL_OUTPUT,
+			} as InputItem);
+		}
+	}
+	return repaired;
+}
+
 export async function transformRequestBody(
 	body: RequestBody,
 	model: Model<Api>,
@@ -87,39 +164,8 @@ export async function transformRequestBody(
 
 	if (body.input && Array.isArray(body.input)) {
 		body.input = filterInput(body.input);
-
 		if (body.input) {
-			const functionCallIds = new Set(
-				body.input
-					.filter(item => item.type === "function_call" && typeof item.call_id === "string")
-					.map(item => item.call_id as string),
-			);
-
-			body.input = body.input.map(item => {
-				if (item.type === "function_call_output" && typeof item.call_id === "string") {
-					const callId = item.call_id as string;
-					if (!functionCallIds.has(callId)) {
-						const itemRecord = item as unknown as Record<string, unknown>;
-						const toolName = typeof itemRecord.name === "string" ? itemRecord.name : "tool";
-						let text = "";
-						try {
-							const output = itemRecord.output;
-							text = typeof output === "string" ? output : JSON.stringify(output);
-						} catch {
-							text = String(itemRecord.output ?? "");
-						}
-						if (text.length > 16000) {
-							text = `${text.slice(0, 16000)}\n...[truncated]`;
-						}
-						return {
-							type: "message",
-							role: "assistant",
-							content: `[Previous ${toolName} result; call_id=${callId}]: ${text}`,
-						} as InputItem;
-					}
-				}
-				return item;
-			});
+			body.input = repairToolCallPairs(body.input);
 		}
 	}
 
diff --git a/packages/ai/src/providers/openai-responses-shared.ts b/packages/ai/src/providers/openai-responses-shared.ts
index 2b0f5f2b3..8fc389838 100644
--- a/packages/ai/src/providers/openai-responses-shared.ts
+++ b/packages/ai/src/providers/openai-responses-shared.ts
@@ -212,6 +212,59 @@ export function repairOrphanResponsesToolOutputs(input: ResponseInput): Response
 	});
 }
 
+/** Placeholder output for a tool call whose result is absent from the input. */
+const ORPHAN_TOOL_CALL_PLACEHOLDER =
+	"[No tool output recorded: the tool call was interrupted before it produced a result.]";
+
+/**
+ * Synthesize a placeholder `function_call_output` / `custom_tool_call_output`
+ * for every `function_call` / `custom_tool_call` whose `call_id` has no matching
+ * output later in the same input. The Responses API rejects an unpaired call
+ * with `400 No tool output found for function call …`.
+ *
+ * Orphan calls surface when the user branches/navigates the session tree to a
+ * node that ends on a tool call (the tool-result child is excluded from the
+ * reconstructed history) or when a turn is aborted/crashes after the call
+ * streamed but before its result persisted. Dropping the call would erase the
+ * assistant's action; a placeholder output keeps the call visible so the model
+ * can recover (e.g. re-issue the call). Symmetric to
+ * {@link repairOrphanResponsesToolOutputs}.
+ */
+export function repairOrphanResponsesToolCalls(input: ResponseInput): ResponseInput {
+	const outputCallIds = new Set<string>();
+	for (const item of input) {
+		const t = (item as { type?: string }).type;
+		if (t !== "function_call_output" && t !== "custom_tool_call_output") continue;
+		const callId = (item as { call_id?: unknown }).call_id;
+		if (typeof callId === "string") outputCallIds.add(callId);
+	}
+	let hasOrphan = false;
+	for (const item of input) {
+		const t = (item as { type?: string }).type;
+		if (t !== "function_call" && t !== "custom_tool_call") continue;
+		const callId = (item as { call_id?: unknown }).call_id;
+		if (typeof callId === "string" && !outputCallIds.has(callId)) {
+			hasOrphan = true;
+			break;
+		}
+	}
+	if (!hasOrphan) return input;
+	const repaired: ResponseInput = [];
+	for (const item of input) {
+		repaired.push(item);
+		const t = (item as { type?: string }).type;
+		if (t !== "function_call" && t !== "custom_tool_call") continue;
+		const callId = (item as { call_id?: unknown }).call_id;
+		if (typeof callId !== "string" || outputCallIds.has(callId)) continue;
+		repaired.push({
+			type: t === "custom_tool_call" ? "custom_tool_call_output" : "function_call_output",
+			call_id: callId,
+			output: ORPHAN_TOOL_CALL_PLACEHOLDER,
+		} as ResponseInput[number]);
+	}
+	return repaired;
+}
+
 export function convertResponsesInputContent(
 	content: string | Array<TextContent | ImageContent>,
 	supportsImages: boolean,
diff --git a/packages/ai/src/providers/openai-responses.ts b/packages/ai/src/providers/openai-responses.ts
index ac1684b43..ed6de0481 100644
--- a/packages/ai/src/providers/openai-responses.ts
+++ b/packages/ai/src/providers/openai-responses.ts
@@ -62,6 +62,7 @@ import {
 	isOpenAIResponsesProgressEvent,
 	normalizeResponsesToolCallIdForTransform,
 	processResponsesStream,
+	repairOrphanResponsesToolCalls,
 	repairOrphanResponsesToolOutputs,
 } from "./openai-responses-shared";
 import { transformMessages } from "./transform-messages";
@@ -614,7 +615,7 @@ function convertConversationMessages(
 		msgIndex++;
 	}
 
-	return repairOrphanResponsesToolOutputs(messages);
+	return repairOrphanResponsesToolCalls(repairOrphanResponsesToolOutputs(messages));
 }
 
 /**
diff --git a/packages/ai/test/openai-codex.test.ts b/packages/ai/test/openai-codex.test.ts
index 4dbc616a7..ed81d7c78 100644
--- a/packages/ai/test/openai-codex.test.ts
+++ b/packages/ai/test/openai-codex.test.ts
@@ -71,6 +71,62 @@ describe("openai-codex request transformer", () => {
 	});
 });
 
+describe("openai-codex orphan tool-call repair", () => {
+	it("synthesizes a function_call_output for a function_call with no result", async () => {
+		const body: RequestBody = {
+			model: "gpt-5.1-codex",
+			input: [
+				{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] },
+				{ type: "function_call", call_id: "call_orphan", name: "read", arguments: "{}" },
+				{ type: "message", role: "user", content: [{ type: "input_text", text: "next" }] },
+			],
+		};
+
+		const transformed = await transformRequestBody(body, createCodexModel(body.model), {});
+		const input = transformed.input || [];
+
+		const callIndex = input.findIndex(item => item.type === "function_call" && item.call_id === "call_orphan");
+		expect(callIndex).toBeGreaterThanOrEqual(0);
+		// The synthesized output sits immediately after the orphan call.
+		const output = input[callIndex + 1];
+		expect(output?.type).toBe("function_call_output");
+		expect(output?.call_id).toBe("call_orphan");
+		expect(typeof output?.output).toBe("string");
+		expect(output?.output as string).toMatch(/interrupted/i);
+	});
+
+	it("leaves a paired function_call untouched", async () => {
+		const body: RequestBody = {
+			model: "gpt-5.1-codex",
+			input: [
+				{ type: "function_call", call_id: "call_paired", name: "read", arguments: "{}" },
+				{ type: "function_call_output", call_id: "call_paired", output: "real result" },
+			],
+		};
+
+		const transformed = await transformRequestBody(body, createCodexModel(body.model), {});
+		const input = transformed.input || [];
+
+		const outputs = input.filter(item => item.type === "function_call_output" && item.call_id === "call_paired");
+		expect(outputs).toHaveLength(1);
+		expect(outputs[0]?.output).toBe("real result");
+	});
+
+	it("synthesizes a custom_tool_call_output for an orphan custom_tool_call", async () => {
+		const body: RequestBody = {
+			model: "gpt-5.1-codex",
+			input: [{ type: "custom_tool_call", call_id: "call_custom", name: "apply_patch" }],
+		};
+
+		const transformed = await transformRequestBody(body, createCodexModel(body.model), {});
+		const input = transformed.input || [];
+
+		const output = input.find(item => item.type === "custom_tool_call_output" && item.call_id === "call_custom");
+		expect(output).toBeDefined();
+		expect(output?.output as string).toMatch(/interrupted/i);
+	});
+});
+
 describe("openai-codex reasoning effort validation", () => {
 	it("rejects gpt-5.1 xhigh when metadata does not list it", async () => {
 		const body: RequestBody = { model: "gpt-5.1", input: [] };
diff --git a/packages/ai/test/openai-responses-orphan-repair.test.ts b/packages/ai/test/openai-responses-orphan-repair.test.ts
new file mode 100644
index 000000000..014d6988f
--- /dev/null
+++ b/packages/ai/test/openai-responses-orphan-repair.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from "bun:test";
+import {
+	repairOrphanResponsesToolCalls,
+	repairOrphanResponsesToolOutputs,
+} from "@oh-my-pi/pi-ai/providers/openai-responses-shared";
+import type { ResponseInput } from "openai/resources/responses/responses";
+
+describe("repairOrphanResponsesToolCalls", () => {
+	it("appends a synthetic function_call_output after a call with no result", () => {
+		const input: ResponseInput = [
+			{ type: "function_call", call_id: "call_a", name: "read", arguments: "{}" },
+			{ role: "user", content: [{ type: "input_text", text: "continue" }] },
+		];
+
+		const repaired = repairOrphanResponsesToolCalls(input);
+		const callIndex = repaired.findIndex(
+			item =>
+				(item as { type?: string }).type === "function_call" && (item as { call_id?: string }).call_id === "call_a",
+		);
+		const output = repaired[callIndex + 1] as { type?: string; call_id?: string; output?: unknown };
+		expect(output.type).toBe("function_call_output");
+		expect(output.call_id).toBe("call_a");
+		expect(output.output).toMatch(/interrupted/i);
+	});
+
+	it("uses custom_tool_call_output for an orphan custom_tool_call", () => {
+		const input: ResponseInput = [
+			{ type: "custom_tool_call", call_id: "call_c", name: "apply_patch", input: "patch" } as ResponseInput[number],
+		];
+
+		const repaired = repairOrphanResponsesToolCalls(input);
+		const output = repaired.find(item => (item as { type?: string }).type === "custom_tool_call_output") as
+			| { call_id?: string }
+			| undefined;
+		expect(output?.call_id).toBe("call_c");
+	});
+
+	it("returns the input unchanged when every call is paired", () => {
+		const input: ResponseInput = [
+			{ type: "function_call", call_id: "call_a", name: "read", arguments: "{}" },
+			{ type: "function_call_output", call_id: "call_a", output: "ok" } as ResponseInput[number],
+		];
+
+		const repaired = repairOrphanResponsesToolCalls(input);
+		expect(repaired).toBe(input);
+	});
+
+	it("composes with output repair so a tree-branch snapshot stays API-valid", () => {
+		// Branching to a node that ends on a tool call drops the result child:
+		// the assistant turn keeps the call, but no matching output remains.
+		const input: ResponseInput = [
+			{ role: "user", content: [{ type: "input_text", text: "do it" }] },
+			{ type: "function_call", call_id: "call_x", name: "bash", arguments: "{}" },
+		];
+
+		const repaired = repairOrphanResponsesToolCalls(repairOrphanResponsesToolOutputs(input));
+		const callIds = new Set(
+			repaired
+				.filter(i => (i as { type?: string }).type === "function_call")
+				.map(i => (i as { call_id: string }).call_id),
+		);
+		const outputIds = new Set(
+			repaired
+				.filter(i => (i as { type?: string }).type === "function_call_output")
+				.map(i => (i as { call_id: string }).call_id),
+		);
+		for (const id of callIds) expect(outputIds.has(id)).toBe(true);
+	});
+});

From 53b8f0f3fe7a08d9461123bbfab5380e53a31cd7 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:58:33 +0200
Subject: [PATCH 053/181] docs(packages/hashline): clarified patch hunk rules
 for #TAG-safe edits

- Specified replace N..M ranges as inclusive to prevent accidental boundary truncation.
- Clarified that edits must target only lines actually read, not merely covered by a #TAG.
- Added guidance to keep pure insertions as insert hunks and avoid widening replace ranges.
---
 packages/hashline/src/prompt.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/packages/hashline/src/prompt.md b/packages/hashline/src/prompt.md
index 85396d8cf..6547ff2e6 100644
--- a/packages/hashline/src/prompt.md
+++ b/packages/hashline/src/prompt.md
@@ -5,7 +5,7 @@ Every file section starts with `[PATH#TAG]`. `TAG` is the 4-hex snapshot tag fro
 </headers>
 
 <ops>
-replace N..M:      replace original lines N..M with the body rows below.
+replace N..M:      replace original lines N..M with the body rows below. CAUTION, IT IS INCLUSIVE! MAKE SURE YOU INTEND TO DELETE BOTH ENDS!
 replace block N:   replace the whole syntactic block that BEGINS on line N — its header line through its closing line — resolved with tree-sitter. Body rows below. Point N at the line that OPENS the construct (the `if`/`function`/`def`/`{`-bearing line), not a closing `}` or a blank line.
 delete N..M        delete original lines N..M. No body.
 delete block N     delete the whole syntactic block that BEGINS on line N.
@@ -27,10 +27,13 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 - Numbers refer to the ORIGINAL file and stay valid for the whole patch — they do not shift as hunks apply.
 - Across calls they do NOT survive: each applied edit mints a fresh `#TAG` and renumbers the file, so the tag and line numbers you just used are dead. Anchor the next edit on the `[PATH#TAG]` and lines from the edit response (or re-`read`), never on pre-edit numbers.
 - A line number is an offset, not a structural boundary: never `insert after N` into a construct you have not read, and never start or end a `replace`/`delete` range mid-expression or mid-block. If unsure what is on those lines, `read` them first.
+- A valid `#TAG` is NOT permission to patch the whole file — it certifies the snapshot, not your knowledge of it. Authority to touch a line comes from having literally seen that line as a `LINE:TEXT` row in a `read`/`search`, not from holding the tag. Every line in a hunk's range, and the lines bounding it, must be lines you actually saw.
+- An elided or partial read is NOT a read of the gap. A `…` (or any collapsed/truncated region) between two excerpts means those lines are UNSEEN — treat them exactly like lines you never opened. Never place a hunk on, or span a range across, an elided region; `read` that range explicitly first. Reconstructing it from memory of "what the code probably looks like" is how ranges drift off-by-N and shred neighboring blocks.
 - On a stale-tag rejection — or any result you cannot fully account for — STOP and re-`read`. Never stack more line-numbered edits onto output you have not re-grounded; that compounds corruption.
 - One hunk per range; the body is the final content, never an old/new pair.
 - Keep every range as tight as the change: a range must cover ONLY lines whose content actually changes. Never widen it to swallow an unchanged signature, brace, or neighboring statement just to rewrite a few lines inside — change one line with `replace N..N`, not the whole block around it. (A range where every line genuinely changes is correctly long; tightness is about excluding unchanged lines, not about being short.) This bounds the blast radius if a number is off: a stale single-line replace corrupts one line, while a stale block replace shreds the whole block and its structure.
 - To change lines 2 and 5 while keeping 3–4, issue two hunks (`replace 2..2:` and `replace 5..5:`). Untouched lines are simply absent from every range.
+- Pure additions use `insert`, never a widened `replace`. If the change only adds lines, `insert before/after` the spot and keep every existing line out of all ranges. Do NOT `replace` a span of keepers and retype them around the new line "to preserve" them — those retyped keepers are exactly what gets silently dropped when one is forgotten. A keeper that never enters your body cannot be lost. `replace` is only for lines whose own text changes.
 - NEVER use this tool to format code — reordering imports, re-indenting, aligning columns, or any mechanical restyling. That is the project formatter's job; run it instead of hand-editing layout here.
 </rules>
 
@@ -99,6 +102,16 @@ replace 3..3:
 # RIGHT
 replace 3..3:
 +   return msg
+
+# WRONG — a pure insertion done as a widened `replace`: you only want to add one line after 2,
+# but you replace 2..4, retype the keepers in the body, and drop one (here line 4, `greet("world")`).
+replace 2..4:
++    msg = "Hello, " + name
++    extra = compute(name)
++    print(msg)
+# RIGHT — touch nothing you keep; the new line is the whole body.
+insert after 2:
++    extra = compute(name)
 </anti-patterns>
 
 <critical>

From 9a2e766c90a9d791b889769841d336db1ec3a75e Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:58:33 +0200
Subject: [PATCH 054/181] perf(packages/tui): optimized per-frame TUI line
 fitting cache

- Added a per-frame cache for #fitLineToWidth results and cleared it at each #doRender.
- Reused memoized line-fit outputs to skip repeated visibleWidth/truncate work.
---
 packages/tui/src/tui.ts | 36 ++++++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 732af473c..539144a33 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -340,7 +340,8 @@ export class Container implements Component {
 		width = Math.max(1, width);
 		const lines: string[] = [];
 		for (const child of this.children) {
-			lines.push(...child.render(width));
+			const childLines = child.render(width);
+			for (let i = 0; i < childLines.length; i++) lines.push(childLines[i]);
 		}
 		return lines;
 	}
@@ -395,6 +396,11 @@ type RenderIntent =
 export class TUI extends Container {
 	terminal: Terminal;
 	#previousLines: string[] = [];
+	// Per-frame cache of #fitLineToWidth results. Cleared at the top of every
+	// #doRender (where the frame width is fixed), so it only ever holds entries
+	// for one width. Eliminates the duplicate fit work between the compose pass
+	// and the emitters, plus repeated fits of identical blank padding rows.
+	#fitLineCache = new Map<string, string>();
 	#previousWidth = 0;
 	#previousHeight = 0;
 	#focusedComponent: Component | null = null;
@@ -507,7 +513,7 @@ export class TUI extends Container {
 					this.#nativeScrollbackCommitSafeEnd = offset + boundedEnd;
 				}
 			}
-			lines.push(...childLines);
+			for (let i = 0; i < childLines.length; i++) lines.push(childLines[i]);
 		}
 		return lines;
 	}
@@ -1468,6 +1474,9 @@ export class TUI extends Container {
 		if (this.#stopped) return;
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
+		// Reset the per-frame fit memo: width is fixed for this frame, so cached
+		// fit results stay valid across the compose pass and every emitter re-fit.
+		this.#fitLineCache.clear();
 
 		// 1. Compose the frame. Bracket the transcript render so the image budget
 		// observes every inline image in display order (overlays carry none).
@@ -2352,10 +2361,25 @@ export class TUI extends Container {
 	}
 
 	#fitLineToWidth(line: string, width: number): string {
-		if (TERMINAL.isImageLine(line)) return line;
-		if (visibleWidth(line) <= width) return line;
-		const truncated = truncateToWidth(line, width, Ellipsis.Omit);
-		return truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+		// Frame-scoped memo: #doRender clears this each frame after reading the
+		// terminal width, so within a frame `width` is constant and this map is
+		// keyed by line alone. The compose/fit pass (#fitLinesToWidth) and every
+		// emitter re-fit the same lines (and many repeated blank rows); the result
+		// is pure for a fixed width, so caching it is byte-identical and skips the
+		// redundant native visibleWidth/truncate work.
+		const cached = this.#fitLineCache.get(line);
+		if (cached !== undefined) return cached;
+		let result: string;
+		if (TERMINAL.isImageLine(line)) {
+			result = line;
+		} else if (visibleWidth(line) <= width) {
+			result = line;
+		} else {
+			const truncated = truncateToWidth(line, width, Ellipsis.Omit);
+			result = truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+		}
+		this.#fitLineCache.set(line, result);
+		return result;
 	}
 
 	/**

From d5c1f6e3ab18439d8705475eea20e3c9781de167 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:58:33 +0200
Subject: [PATCH 055/181] perf(packages/coding-agent): optimized LSP frame
 parsing via chunk queue

- Reworked message parsing to process complete frames from a pending chunk queue.
- Added chunk-aware header scanning and range copy to avoid repeated buffer concatenation.
- Persisted partially read bytes in client.messageBuffer during reader teardown.
---
 packages/coding-agent/src/lsp/client.ts | 143 +++++++++++++++---------
 1 file changed, 93 insertions(+), 50 deletions(-)

diff --git a/packages/coding-agent/src/lsp/client.ts b/packages/coding-agent/src/lsp/client.ts
index 3080fc083..8127cdfc4 100644
--- a/packages/coding-agent/src/lsp/client.ts
+++ b/packages/coding-agent/src/lsp/client.ts
@@ -174,49 +174,69 @@ const CLIENT_CAPABILITIES = {
 // LSP Message Protocol
 // =============================================================================
 
-/**
- * Parse a single LSP message from a buffer.
- * Returns the parsed message and remaining buffer, or null if incomplete.
- */
-function parseMessage(
-	buffer: Buffer,
-): { message: LspJsonRpcResponse | LspJsonRpcNotification; remaining: Buffer } | null {
-	// Only decode enough to find the header
-	const headerEndIndex = findHeaderEnd(buffer);
-	if (headerEndIndex === -1) return null;
-
-	const headerText = new TextDecoder().decode(buffer.slice(0, headerEndIndex));
-	const contentLengthMatch = headerText.match(/Content-Length: (\d+)/i);
-	if (!contentLengthMatch) return null;
-
-	const contentLength = Number.parseInt(contentLengthMatch[1], 10);
-	const messageStart = headerEndIndex + 4; // Skip \r\n\r\n
-	const messageEnd = messageStart + contentLength;
-
-	if (buffer.length < messageEnd) return null;
-
-	const messageBytes = buffer.subarray(messageStart, messageEnd);
-	const messageText = new TextDecoder().decode(messageBytes);
-	const remaining = buffer.subarray(messageEnd);
-
-	return {
-		message: JSON.parse(messageText),
-		remaining,
-	};
-}
+// Reused for all full (non-streaming) decodes; each decode() resets state, so a
+// single instance is safe and avoids per-message TextDecoder allocation.
+const MESSAGE_DECODER = new TextDecoder("utf-8");
 
 /**
- * Find the end of the header section (before \r\n\r\n)
+ * Locate the `\r\n\r\n` header terminator across the pending chunk list.
+ * Returns the absolute byte index of the first `\r`, or -1 when not present.
+ * Equivalent to scanning the contiguous concatenation of the chunks.
  */
-function findHeaderEnd(buffer: Uint8Array): number {
-	for (let i = 0; i < buffer.length - 3; i++) {
-		if (buffer[i] === 13 && buffer[i + 1] === 10 && buffer[i + 2] === 13 && buffer[i + 3] === 10) {
-			return i;
+function findHeaderEndInChunks(chunks: Buffer[]): number {
+	let global = 0;
+	let b0 = -1;
+	let b1 = -1;
+	let b2 = -1;
+	for (const chunk of chunks) {
+		for (let i = 0; i < chunk.length; i++) {
+			const b3 = chunk[i];
+			if (b0 === 13 && b1 === 10 && b2 === 13 && b3 === 10) {
+				return global - 3;
+			}
+			b0 = b1;
+			b1 = b2;
+			b2 = b3;
+			global++;
 		}
 	}
 	return -1;
 }
 
+/** Copy the byte range [from, to) out of the pending chunk list into one Buffer. */
+function copyChunkRange(chunks: Buffer[], from: number, to: number): Buffer {
+	const out = Buffer.allocUnsafe(to - from);
+	let global = 0;
+	let written = 0;
+	for (const chunk of chunks) {
+		const chunkEnd = global + chunk.length;
+		if (chunkEnd > from && global < to) {
+			const start = Math.max(from, global) - global;
+			const end = Math.min(to, chunkEnd) - global;
+			chunk.copy(out, written, start, end);
+			written += end - start;
+		}
+		global = chunkEnd;
+		if (global >= to) break;
+	}
+	return out;
+}
+
+/** Drop the first `count` bytes from the pending chunk list in place. */
+function dropChunkFront(chunks: Buffer[], count: number): void {
+	let removed = 0;
+	while (chunks.length > 0) {
+		const head = chunks[0];
+		if (removed + head.length <= count) {
+			removed += head.length;
+			chunks.shift();
+		} else {
+			chunks[0] = head.subarray(count - removed);
+			break;
+		}
+	}
+}
+
 async function writeMessage(
 	sink: Bun.FileSink,
 	message: LspJsonRpcRequest | LspJsonRpcNotification | LspJsonRpcResponse,
@@ -249,22 +269,43 @@ async function startMessageReader(client: LspClient): Promise<void> {
 
 	const reader = (client.proc.stdout as ReadableStream<Uint8Array>).getReader();
 
+	// Incoming bytes are buffered as a list of chunks and only joined when a full
+	// message is framed. Concatenating the accumulator on every read was O(n^2)
+	// for messages that span many reads (e.g. a large initial diagnostics burst).
+	const pendingChunks: Buffer[] = [];
+	let pendingLen = 0;
+	if (client.messageBuffer.length > 0) {
+		const seed = Buffer.from(client.messageBuffer);
+		pendingChunks.push(seed);
+		pendingLen = seed.length;
+	}
+
 	try {
 		while (true) {
 			const { done, value } = await reader.read();
 			if (done) break;
 
-			// Atomically update buffer before processing
-			const currentBuffer: Buffer = Buffer.concat([client.messageBuffer, value]);
-			client.messageBuffer = currentBuffer;
+			pendingChunks.push(Buffer.from(value));
+			pendingLen += value.length;
 
-			// Process all complete messages in buffer
-			// Use local variable to avoid race with concurrent buffer updates
-			let workingBuffer = currentBuffer;
-			let parsed = parseMessage(workingBuffer);
-			while (parsed) {
-				const { message, remaining } = parsed;
-				workingBuffer = remaining;
+			// Drain every complete message currently buffered.
+			while (true) {
+				const headerEnd = findHeaderEndInChunks(pendingChunks);
+				if (headerEnd === -1) break;
+
+				const headerText = MESSAGE_DECODER.decode(copyChunkRange(pendingChunks, 0, headerEnd));
+				const contentLengthMatch = headerText.match(/Content-Length: (\d+)/i);
+				if (!contentLengthMatch) break;
+
+				const contentLength = Number.parseInt(contentLengthMatch[1], 10);
+				const messageStart = headerEnd + 4; // Skip \r\n\r\n
+				const messageEnd = messageStart + contentLength;
+				if (pendingLen < messageEnd) break;
+
+				const messageText = MESSAGE_DECODER.decode(copyChunkRange(pendingChunks, messageStart, messageEnd));
+				const message: LspJsonRpcResponse | LspJsonRpcNotification = JSON.parse(messageText);
+				dropChunkFront(pendingChunks, messageEnd);
+				pendingLen -= messageEnd;
 
 				// Route message
 				if ("id" in message && message.id !== undefined) {
@@ -301,12 +342,7 @@ async function startMessageReader(client: LspClient): Promise<void> {
 						}
 					}
 				}
-
-				parsed = parseMessage(workingBuffer);
 			}
-
-			// Atomically commit processed buffer
-			client.messageBuffer = workingBuffer;
 		}
 	} catch (err) {
 		// Connection closed or error - reject all pending requests
@@ -315,6 +351,13 @@ async function startMessageReader(client: LspClient): Promise<void> {
 		}
 		client.pendingRequests.clear();
 	} finally {
+		// Persist any unparsed remainder so a restarted reader resumes mid-message.
+		client.messageBuffer =
+			pendingChunks.length === 0
+				? new Uint8Array(0)
+				: pendingChunks.length === 1
+					? pendingChunks[0]
+					: Buffer.concat(pendingChunks, pendingLen);
 		reader.releaseLock();
 		client.isReading = false;
 	}

From cc283cf50f3f0ec8971ca7a45fffb8c572d19a55 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:58:33 +0200
Subject: [PATCH 056/181] feat(packages/coding-agent): added streaming
 append-only preview behavior

- Added `isStreamingPreviewAppendOnly` to `ToolRenderer` for per-tool streaming mode selection.
- Updated `ToolExecutionComponent` to query append-only predicates only while a call preview is streaming.
- Marked expanded write previews as append-only so over-tall streaming output can commit head rows.
- Threaded resolved status-line `segmentOptions` into `#buildSegmentContext` construction.
- Added regression tests for scrollback retention and append-only state transitions.
---
 .../src/modes/components/status-line.ts       |  8 +-
 .../src/modes/components/tool-execution.ts    | 28 ++++++-
 packages/coding-agent/src/tools/renderers.ts  | 13 ++-
 packages/coding-agent/src/tools/write.ts      | 10 +++
 .../test/status-line-context-cache.test.ts    |  2 +-
 .../test/tool-live-region-scrollback.test.ts  | 82 +++++++++++++++++++
 6 files changed, 135 insertions(+), 8 deletions(-)

diff --git a/packages/coding-agent/src/modes/components/status-line.ts b/packages/coding-agent/src/modes/components/status-line.ts
index 26f6e10f4..6c8b338d4 100644
--- a/packages/coding-agent/src/modes/components/status-line.ts
+++ b/packages/coding-agent/src/modes/components/status-line.ts
@@ -546,7 +546,7 @@ export class StatusLineComponent implements Component {
 		return `${modelId}|${sp.length}:${sp[0]?.length ?? 0}|${tools.length}|${skills.length}`;
 	}
 
-	#buildSegmentContext(width: number): SegmentContext {
+	#buildSegmentContext(width: number, segmentOptions: StatusLineSettings["segmentOptions"]): SegmentContext {
 		const state = this.session.state;
 
 		// Trigger background fetch (5-min TTL); render uses cached value
@@ -575,7 +575,7 @@ export class StatusLineComponent implements Component {
 		return {
 			session: this.session,
 			width,
-			options: this.#resolveSettings().segmentOptions ?? {},
+			options: segmentOptions ?? {},
 			planMode: this.#planModeStatus,
 			loopMode: this.#loopModeStatus,
 			goalMode: this.#goalModeStatus,
@@ -632,8 +632,8 @@ export class StatusLineComponent implements Component {
 	}
 
 	#buildStatusLine(width: number): string {
-		const ctx = this.#buildSegmentContext(width);
 		const effectiveSettings = this.#resolveSettings();
+		const ctx = this.#buildSegmentContext(width, effectiveSettings.segmentOptions);
 		const separatorDef = getSeparator(effectiveSettings.separator ?? "powerline-thin", theme);
 
 		const bgAnsi = theme.getBgAnsi("statusLineBg");
@@ -759,8 +759,6 @@ export class StatusLineComponent implements Component {
 			return leftGroup + (leftGroup && rightGroup ? " " : "") + rightGroup;
 		}
 
-		leftWidth = groupWidth(left, leftCapWidth, leftSepWidth);
-		rightWidth = groupWidth(right, rightCapWidth, rightSepWidth);
 		const gapWidth = Math.max(1, topFillWidth - leftWidth - rightWidth);
 		const sessionName =
 			effectiveSettings.sessionAccent !== false ? this.session.sessionManager?.getSessionName() : undefined;
diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index 5b90a8a6b..328969a67 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -31,7 +31,7 @@ import {
 	renderJsonTreeLines,
 } from "../../tools/json-tree";
 import { formatExpandHint, replaceTabs, resolveImageOptions, truncateToWidth } from "../../tools/render-utils";
-import { toolRenderers } from "../../tools/renderers";
+import { type ToolRenderer, toolRenderers } from "../../tools/renderers";
 import { TODO_STRIKE_TOTAL_FRAMES } from "../../tools/todo";
 import { isFramedBlockComponent, renderStatusLine } from "../../tui";
 import { sanitizeWithOptionalSixelPassthrough } from "../../utils/sixel";
@@ -530,6 +530,32 @@ export class ToolExecutionComponent extends Container {
 		return (this.#result.details as { async?: { state?: string } } | undefined)?.async?.state === "running";
 	}
 
+	/**
+	 * While streaming its call preview, a tool block whose preview is append-only
+	 * (rows only grow at the bottom, never re-layout) lets the renderer commit the
+	 * scrolled-off head of an over-tall preview to native scrollback instead of
+	 * dropping it — the same anti-yank path a streaming assistant reply uses (see
+	 * {@link TranscriptContainer} + `NativeScrollbackLiveRegion`). Gated on the
+	 * call-preview phase (no result yet) so the boundary closes the instant the
+	 * preview swaps to a result that may collapse; the renderer decides whether
+	 * its current preview shape qualifies via `isStreamingPreviewAppendOnly`.
+	 */
+	isTranscriptBlockAppendOnly(): boolean {
+		// A result preview can collapse/re-layout; only the live call preview is a
+		// candidate. Sealed/aborted blocks are finalized, not streaming.
+		if (this.#sealed || this.#result !== undefined) return false;
+		const predicate =
+			(this.#tool as { isStreamingPreviewAppendOnly?: ToolRenderer["isStreamingPreviewAppendOnly"] } | undefined)
+				?.isStreamingPreviewAppendOnly ?? toolRenderers[this.#toolName]?.isStreamingPreviewAppendOnly;
+		if (!predicate) return false;
+		try {
+			return predicate(this.#getCallArgsForRender(), this.#renderState);
+		} catch (err) {
+			logger.warn("Tool append-only predicate failed", { tool: this.#toolName, error: String(err) });
+			return false;
+		}
+	}
+
 	/**
 	 * Mark the tool terminal even though no result arrived (the turn aborted or
 	 * abandoned it) and stop animating, so it can freeze and stops pinning the
diff --git a/packages/coding-agent/src/tools/renderers.ts b/packages/coding-agent/src/tools/renderers.ts
index eebbe57a1..9f8cbca29 100644
--- a/packages/coding-agent/src/tools/renderers.ts
+++ b/packages/coding-agent/src/tools/renderers.ts
@@ -31,7 +31,7 @@ import { sshToolRenderer } from "./ssh";
 import { todoToolRenderer } from "./todo";
 import { writeToolRenderer } from "./write";
 
-type ToolRenderer = {
+export type ToolRenderer = {
 	renderCall: (args: unknown, options: RenderResultOptions, theme: Theme) => Component;
 	renderResult: (
 		result: { content: Array<{ type: string; text?: string }>; details?: unknown; isError?: boolean },
@@ -40,6 +40,17 @@ type ToolRenderer = {
 		args?: unknown,
 	) => Component;
 	mergeCallAndResult?: boolean;
+	/**
+	 * While the call preview is streaming, report whether the currently-rendered
+	 * preview is append-only: its rows only grow at the bottom and never
+	 * re-layout (a full, top-anchored content preview). The transcript reports
+	 * this up to the TUI so a streaming preview taller than the viewport commits
+	 * its scrolled-off head to native scrollback instead of dropping it (see
+	 * `ToolExecutionComponent.isTranscriptBlockAppendOnly`). Omit (or return
+	 * `false`) for previews that slide a tail window or later collapse to a
+	 * compact result — committing their head would strand stale rows.
+	 */
+	isStreamingPreviewAppendOnly?: (args: unknown, options: RenderResultOptions) => boolean;
 	/** Render without background box, inline in the response flow */
 	inline?: boolean;
 };
diff --git a/packages/coding-agent/src/tools/write.ts b/packages/coding-agent/src/tools/write.ts
index 4c1d92af4..35b0683f2 100644
--- a/packages/coding-agent/src/tools/write.ts
+++ b/packages/coding-agent/src/tools/write.ts
@@ -1021,6 +1021,16 @@ export const writeToolRenderer = {
 		return new Text(text, 0, 0);
 	},
 
+	// Only the expanded (Ctrl+O) preview is append-only: it renders the whole
+	// content top-anchored, so streamed chunks only append rows at the bottom.
+	// The collapsed preview slides a bounded tail window (`formatStreamingContent`
+	// with `WRITE_STREAMING_PREVIEW_LINES`) whose visible rows re-layout as the
+	// window moves — not append-only, but it never overflows the viewport, so its
+	// head is never at risk of being dropped regardless.
+	isStreamingPreviewAppendOnly(args: WriteRenderArgs, options: RenderResultOptions): boolean {
+		return Boolean(options?.expanded && args.content);
+	},
+
 	renderResult(
 		result: { content: Array<{ type: string; text?: string }>; details?: WriteToolDetails; isError?: boolean },
 		options: RenderResultOptions,
diff --git a/packages/coding-agent/test/status-line-context-cache.test.ts b/packages/coding-agent/test/status-line-context-cache.test.ts
index 95ff25dc5..447dd825d 100644
--- a/packages/coding-agent/test/status-line-context-cache.test.ts
+++ b/packages/coding-agent/test/status-line-context-cache.test.ts
@@ -18,8 +18,8 @@ import { afterAll, beforeAll, describe, expect, it } from "bun:test";
 import { countTokens } from "@oh-my-pi/pi-natives";
 import { resetSettingsForTest, Settings } from "../src/config/settings";
 import { StatusLineComponent } from "../src/modes/components/status-line";
-import { computeNonMessageTokens, estimateToolSchemaTokens } from "../src/modes/utils/context-usage";
 import { initTheme } from "../src/modes/theme/theme";
+import { computeNonMessageTokens, estimateToolSchemaTokens } from "../src/modes/utils/context-usage";
 import type { AgentSession } from "../src/session/agent-session";
 
 beforeAll(async () => {
diff --git a/packages/coding-agent/test/tool-live-region-scrollback.test.ts b/packages/coding-agent/test/tool-live-region-scrollback.test.ts
index e30e56e82..aae7130a7 100644
--- a/packages/coding-agent/test/tool-live-region-scrollback.test.ts
+++ b/packages/coding-agent/test/tool-live-region-scrollback.test.ts
@@ -139,6 +139,88 @@ describe("tool live-region scrollback", () => {
 			}
 		});
 	});
+
+	it("commits the scrolled-off head of an over-tall expanded streaming write to scrollback", async () => {
+		if (process.platform === "win32") return;
+
+		await withTerminalRisk(true, async () => {
+			const term = new VirtualTerminal(120, 12);
+			(term as unknown as { isNativeViewportAtBottom: () => boolean | undefined }).isNativeViewportAtBottom = () =>
+				undefined;
+			const tui = new TUI(term);
+			const chat = new TranscriptContainer();
+			const body = (n: number) => Array.from({ length: n }, (_unused, i) => `MARK-${i}`).join("\n");
+			const filePath = "packages/coding-agent/test/probe.txt";
+			// Expanded (Ctrl+O) lifts the tail-window cap, so the preview renders the
+			// whole content top-anchored — append-only growth as chunks stream in.
+			const component = new ToolExecutionComponent(
+				"write",
+				{ file_path: filePath, content: body(4) },
+				{},
+				undefined,
+				tui,
+				process.cwd(),
+			);
+			component.setExpanded(true);
+
+			try {
+				chat.addChild(component);
+				tui.addChild(chat);
+				tui.start();
+				tui.setEagerNativeScrollbackRebuild(true);
+				await term.waitForRender();
+
+				// A short preview that fits, then the full preview that alone overflows
+				// the 12-row viewport — the frame that scrolls the head above the top.
+				component.updateArgs({ file_path: filePath, content: body(4) });
+				tui.requestRender();
+				await term.waitForRender();
+
+				component.updateArgs({ file_path: filePath, content: body(40) });
+				tui.requestRender();
+				await term.waitForRender();
+
+				const strip = (rows: string[]) => rows.map(row => Bun.stripANSI(row).trimEnd()).join("\n");
+				const scrollText = strip(term.getScrollBuffer());
+				const viewportText = strip(term.getViewport());
+
+				// MARK-0 scrolled above the viewport: it must live in native scrollback
+				// (committed), not nowhere. Before the fix the tool block was not
+				// append-only, so its scrolled-off head was dropped — a yanked stream.
+				expect(viewportText).not.toContain("MARK-0");
+				expect(scrollText).toContain("MARK-0");
+				// The streaming tail stays on screen, and nothing went missing between.
+				expect(viewportText).toContain("MARK-39");
+				expect(viewportText).toContain("(streaming)");
+				expect(scrollText).toContain("MARK-20");
+			} finally {
+				component.stopAnimation();
+				tui.stop();
+				await term.flush();
+			}
+		});
+	});
+
+	it("treats a tool block as append-only only while its expanded preview streams", async () => {
+		const filePath = "packages/coding-agent/test/probe.txt";
+		const tui = new TUI(new VirtualTerminal(80, 24));
+		const args = { file_path: filePath, content: "MARK-0\nMARK-1\nMARK-2" };
+		const component = new ToolExecutionComponent("write", args, {}, undefined, tui, process.cwd());
+		type AppendOnly = { isTranscriptBlockAppendOnly(): boolean };
+		const probe = component as unknown as AppendOnly;
+		try {
+			// Collapsed: the preview slides a bounded tail window — not append-only.
+			expect(probe.isTranscriptBlockAppendOnly()).toBe(false);
+			// Expanded + streaming: append-only, eligible for head commit.
+			component.setExpanded(true);
+			expect(probe.isTranscriptBlockAppendOnly()).toBe(true);
+			// Once a final result lands the preview may collapse — boundary closes.
+			component.updateResult({ content: [{ type: "text", text: "" }], details: { path: filePath } }, false);
+			expect(probe.isTranscriptBlockAppendOnly()).toBe(false);
+		} finally {
+			component.stopAnimation();
+		}
+	});
 });
 
 function makeAssistantMessage(text: string): AssistantMessage {

From a3fb07428fe8ec4501fb987d685a74ae32563a60 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:58:33 +0200
Subject: [PATCH 057/181] perf(packages/coding-agent): optimized model
 equivalence namespace cache

- Added a WeakMap cache in compileEquivalenceConfig to reuse compiled configs.
- Raised QUALIFIED_NAMESPACE_SUFFIX_CACHE_CAP and HEURISTIC_CANDIDATES_CACHE_CAP from 256 to 4096.
- Reworked resolveCanonicalIdForModel to build officialMatches during candidate iteration.
---
 .../src/config/model-equivalence.ts           | 22 +++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/packages/coding-agent/src/config/model-equivalence.ts b/packages/coding-agent/src/config/model-equivalence.ts
index e30755b2d..8115f7d87 100644
--- a/packages/coding-agent/src/config/model-equivalence.ts
+++ b/packages/coding-agent/src/config/model-equivalence.ts
@@ -167,13 +167,24 @@ function buildExclusionSet(exclusions: readonly string[] | undefined): Set<strin
 	return result;
 }
 
+const compiledEquivalenceCache = new WeakMap<ModelEquivalenceConfig, CompiledEquivalenceConfig>();
 function compileEquivalenceConfig(config: ModelEquivalenceConfig | undefined): CompiledEquivalenceConfig {
+	if (config) {
+		const cached = compiledEquivalenceCache.get(config);
+		if (cached) {
+			return cached;
+		}
+	}
 	const overrides = buildOverrideMap(config?.overrides);
 	const exclude = buildExclusionSet(config?.exclude);
 	if (overrides.size === 0 && exclude.size === 0) {
 		return EMPTY_COMPILED_EQUIVALENCE;
 	}
-	return { overrides, exclude };
+	const compiled: CompiledEquivalenceConfig = { overrides, exclude };
+	if (config) {
+		compiledEquivalenceCache.set(config, compiled);
+	}
+	return compiled;
 }
 
 function addCanonicalCandidate(candidates: Set<string>, candidate: string): void {
@@ -285,7 +296,7 @@ function expandCompactSeriesMinorVersions(candidate: string): string[] {
 // safely return the same instance. Cap keeps memory bounded under adversarial
 // model-id churn.
 const QUALIFIED_NAMESPACE_SUFFIX_CACHE = new Map<string, string[]>();
-const QUALIFIED_NAMESPACE_SUFFIX_CACHE_CAP = 256;
+const QUALIFIED_NAMESPACE_SUFFIX_CACHE_CAP = 4096;
 function getQualifiedNamespaceSuffixes(candidate: string): string[] {
 	const cached = QUALIFIED_NAMESPACE_SUFFIX_CACHE.get(candidate);
 	if (cached !== undefined) {
@@ -678,7 +689,7 @@ function expandHeavyCanonicalCandidates(normalized: string, queue: string[]): vo
 // is unused — kept for signature stability). The returned array is consumed via
 // `.filter` at every callsite, so sharing the cached instance is safe.
 const HEURISTIC_CANDIDATES_CACHE = new Map<string, string[]>();
-const HEURISTIC_CANDIDATES_CACHE_CAP = 256;
+const HEURISTIC_CANDIDATES_CACHE_CAP = 4096;
 function getHeuristicCanonicalCandidates(modelId: string, _officialIds?: ReadonlySet<string>): string[] {
 	const cached = HEURISTIC_CANDIDATES_CACHE.get(modelId);
 	if (cached !== undefined) {
@@ -765,8 +776,11 @@ function resolveCanonicalIdForModel(
 	}
 
 	const heuristicCandidates = getHeuristicCanonicalCandidates(model.id, referenceData.officialIds);
-	const officialMatches = new Set(heuristicCandidates.filter(candidate => referenceData.officialIds.has(candidate)));
+	const officialMatches = new Set<string>();
 	for (const candidate of heuristicCandidates) {
+		if (referenceData.officialIds.has(candidate)) {
+			officialMatches.add(candidate);
+		}
 		const aliased = referenceData.suffixAliases.get(getCanonicalSuffixAliasKey(candidate));
 		if (aliased) {
 			officialMatches.add(aliased);

From e5e93ff762c080df19aefcd37c29e163263c9af9 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:58:33 +0200
Subject: [PATCH 058/181] feat(packages/coding-agent): enabled
 setup-version-gated startup flow

- Deferred setup wizard import until setup was forced or version stale.
- Dynamically loaded ACP, RPC, and print mode runners only when used.
- Added a marketplace auto-update scheduler with off-mode early exit and non-blocking errors.
- Added setup-version assertions to keep CURRENT_SETUP_VERSION aligned with scenes.
---
 package.json                                  |  1 +
 packages/coding-agent/CHANGELOG.md            |  6 ++
 .../plugins/marketplace-auto-update.ts        | 49 ++++++++++
 packages/coding-agent/src/main.ts             | 89 +++++++++----------
 packages/coding-agent/src/modes/index.ts      |  9 +-
 .../coding-agent/src/modes/setup-version.ts   | 11 +++
 .../src/modes/setup-wizard/index.ts           |  5 +-
 .../coding-agent/test/setup-wizard.test.ts    |  9 ++
 .../test/startup-import-graph.test.ts         | 34 +++++++
 9 files changed, 160 insertions(+), 53 deletions(-)
 create mode 100644 packages/coding-agent/src/extensibility/plugins/marketplace-auto-update.ts
 create mode 100644 packages/coding-agent/src/modes/setup-version.ts
 create mode 100644 packages/coding-agent/test/startup-import-graph.test.ts

diff --git a/package.json b/package.json
index 78098d0fa..91848ac82 100644
--- a/package.json
+++ b/package.json
@@ -87,6 +87,7 @@
   "scripts": {
     "install:dev": "bun install && bun --cwd=packages/coding-agent link && ln -sfn \"$(pwd)/packages/coding-agent/scripts/dev-launch\" \"$(bun pm -g bin)/omp\"",
     "dev": "bun --cwd=packages/coding-agent src/cli.ts",
+    "dev:timing": "PI_TIMING=x bun --cwd=packages/coding-agent --preload ../utils/src/module-timer.ts src/cli.ts",
     "stats": "bun --cwd=packages/coding-agent src/cli.ts stats",
     "claude:trace": "bun scripts/claude-trace.ts",
     "build": "bun run --workspaces --if-present build",
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 5ae4c1bdd..aee58020f 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -9,11 +9,17 @@
 ### Changed
 
 - Changed eval `agent()` subagents so they are never subject to the `task.maxRuntimeMs` wall-clock cap. The parent cell's idle watchdog is already suspended for the entire bridge call (`withBridgeTimeoutPause`), so a long-running fan-out/recovery workflow must not be killed by a per-subagent runtime limit. `runEvalAgent` now passes `maxRuntimeMs: 0` to `runSubprocess`, which honors an explicit `ExecutorOptions.maxRuntimeMs` override over the inherited setting.
+- Changed interactive timing behavior so `PI_TIMING=x pi` preloads the module timer before the CLI graph loads and includes the `(modules)` report. `PI_TIMING=full` now also exits after printing, matching `PI_TIMING=x`, so full module reports are usable for cold-start measurement without launching the TUI. Added the root `dev:timing` script for the same profiled startup path.
+- Changed coding-agent startup imports so normal TUI launch imports `InteractiveMode` directly, keeps print/RPC/ACP runners on their branch-only paths, and moves marketplace auto-update work behind a lightweight deferred starter.
+- Changed cold-launch setup gating so the full setup wizard (every scene plus the overlay and their TUI/OAuth/web-search/theme dependencies) is no longer statically imported by `main.ts`. The current setup version now lives in a tiny dependency-free `modes/setup-version` module, and the wizard barrel is lazy-loaded only when the stored setup version is stale or the wizard is forced — the common up-to-date launch skips loading it entirely.
+- Changed cold-launch startup imports so the hot-path CLI files no longer pull the full `@oh-my-pi/pi-ai` barrel: `commands/launch.ts` and `cli/args.ts` import `THINKING_EFFORTS`/`Effort` from the tiny `@oh-my-pi/pi-ai/effort` module, and `config/model-registry.ts` now imports its ~20 symbols from narrow subpaths (`api-registry`, `model-cache`, `model-manager`, `model-thinking`, `models`, `provider-models`, `types`, `utils/event-stream`) instead of the barrel — so launching no longer eagerly loads every provider, auth, OAuth, and usage module re-exported by the barrel.
+
 
 ### Fixed
 
 - Fixed eval `agent()` failures surfacing as an opaque `RuntimeError: bridge call '__agent__' failed` with no reason. When a subagent aborted, `runEvalAgent` built its failure message with `result.error ?? result.stderr ?? result.abortReason ?? …`, but `result.stderr` is the empty string on a clean abort (and `result.error` is gated on a non-empty `stderr`), so the nullish chain stopped at `""` and never reached `abortReason`. The empty string propagated through the loopback bridge and the Python prelude's `RuntimeError(msg or "bridge call … failed")`, discarding the real reason. The chain now uses `||` so an empty `stderr` falls through to `abortReason`.
 - Fixed subagent aborts being mislabeled as the generic "Cancelled by caller" when the abort originated inside the subagent's own turn (`stopReason: "aborted"` with no caller signal and no runtime-limit timer). `runSubprocess` now prefers the aborted assistant message's `errorMessage` (e.g. "Request was aborted" or a specific stream error) for that case, while a real caller signal or wall-clock abort still reports its precise reason.
+- Fixed a long streaming tool preview that alone overflows the viewport dropping its scrolled-off head on ED3-risk terminals (ghostty/kitty/iTerm2/…). A streaming `write` preview expanded with `Ctrl+O` renders the whole content top-anchored and grows append-only, but the tool block never reported itself append-only to the transcript, so the renderer's commit-as-you-go boundary stopped at the block start and its earlier rows scrolled above the viewport without being committed to native scrollback — they vanished, leaving the preview looking like a viewport-tall circular buffer. `ToolExecutionComponent` now implements `isTranscriptBlockAppendOnly()`, delegating to a renderer-declared `isStreamingPreviewAppendOnly` predicate (gated to the live call-preview phase) so the expanded write stream commits its head exactly like a streamed assistant reply; collapsed previews (sliding tail window) and result previews (which can collapse) stay deferred.
 
 ## [15.9.69] - 2026-06-06
 ### Fixed
diff --git a/packages/coding-agent/src/extensibility/plugins/marketplace-auto-update.ts b/packages/coding-agent/src/extensibility/plugins/marketplace-auto-update.ts
new file mode 100644
index 000000000..f81da80a2
--- /dev/null
+++ b/packages/coding-agent/src/extensibility/plugins/marketplace-auto-update.ts
@@ -0,0 +1,49 @@
+import { getProjectDir, logger } from "@oh-my-pi/pi-utils";
+
+type MarketplaceAutoUpdateMode = "off" | "notify" | "auto";
+
+interface MarketplaceAutoUpdateOptions {
+	autoUpdate: MarketplaceAutoUpdateMode;
+	resolveActiveProjectRegistryPath: (cwd: string) => Promise<string | null>;
+	clearPluginRootsCache: () => void;
+}
+
+export function scheduleMarketplaceAutoUpdate(options: MarketplaceAutoUpdateOptions): void {
+	if (options.autoUpdate === "off") {
+		return;
+	}
+
+	void runMarketplaceAutoUpdate(options);
+}
+
+async function runMarketplaceAutoUpdate(options: MarketplaceAutoUpdateOptions): Promise<void> {
+	try {
+		// Startup perf: marketplace manager pulls scraper/fetch/cache code; keep it out of the initial TUI graph.
+		const {
+			MarketplaceManager,
+			getInstalledPluginsRegistryPath,
+			getMarketplacesCacheDir,
+			getMarketplacesRegistryPath,
+			getPluginsCacheDir,
+		} = await import("./marketplace");
+		const mgr = new MarketplaceManager({
+			marketplacesRegistryPath: getMarketplacesRegistryPath(),
+			installedRegistryPath: getInstalledPluginsRegistryPath(),
+			projectInstalledRegistryPath: (await options.resolveActiveProjectRegistryPath(getProjectDir())) ?? undefined,
+			marketplacesCacheDir: getMarketplacesCacheDir(),
+			pluginsCacheDir: getPluginsCacheDir(),
+			clearPluginRootsCache: options.clearPluginRootsCache,
+		});
+		await mgr.refreshStaleMarketplaces();
+		const updates = await mgr.checkForUpdates();
+		if (updates.length === 0) return;
+		if (options.autoUpdate === "auto") {
+			await mgr.upgradeAllPlugins();
+			logger.debug(`Auto-upgraded ${updates.length} marketplace plugin(s)`);
+		} else {
+			logger.debug(`${updates.length} marketplace plugin update(s) available — /marketplace upgrade`);
+		}
+	} catch {
+		// Silently ignore — network failure, corrupt data, offline.
+	}
+}
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index 8354521b3..fa4c24011 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -43,16 +43,11 @@ import { injectOmpExtensionCliRoots } from "./discovery/omp-extension-roots";
 import { exportFromFile } from "./export/html";
 import { ExtensionRunner } from "./extensibility/extensions/runner";
 import type { ExtensionUIContext } from "./extensibility/extensions/types";
-import {
-	getInstalledPluginsRegistryPath,
-	getMarketplacesCacheDir,
-	getMarketplacesRegistryPath,
-	getPluginsCacheDir,
-	MarketplaceManager,
-} from "./extensibility/plugins/marketplace";
+import { scheduleMarketplaceAutoUpdate } from "./extensibility/plugins/marketplace-auto-update";
 import type { MCPManager } from "./mcp";
-import { InteractiveMode, runAcpMode, runPrintMode, runRpcMode } from "./modes";
-import { ALL_SCENES, runSetupWizard, selectSetupScenes } from "./modes/setup-wizard";
+import { InteractiveMode } from "./modes/interactive-mode";
+import type { PrintModeOptions } from "./modes/print-mode";
+import { CURRENT_SETUP_VERSION } from "./modes/setup-version";
 import { initTheme, stopThemeWatcher } from "./modes/theme/theme";
 import type { SubmittedUserInput } from "./modes/types";
 import {
@@ -72,6 +67,13 @@ import type { LspStartupServerInfo } from "./tools";
 import { getChangelogPath, getNewEntries, parseChangelog } from "./utils/changelog";
 import { EventBus } from "./utils/event-bus";
 
+type RunAcpMode = (createSession: AcpSessionFactory) => Promise<never>;
+type RunPrintMode = (session: AgentSession, options: PrintModeOptions) => Promise<void>;
+type RunRpcMode = (
+	session: AgentSession,
+	setToolUIContext?: (uiContext: ExtensionUIContext, hasUI: boolean) => void,
+) => Promise<never>;
+
 async function checkForNewVersion(currentVersion: string): Promise<string | undefined> {
 	if (!settings.get("startup.checkUpdate")) {
 		return;
@@ -261,17 +263,26 @@ async function runInteractiveMode(
 		eventBus,
 	);
 
-	const setupScenes = await selectSetupScenes(settings.get("setupVersion"), ALL_SCENES, mode, {
-		resuming,
-		isTTY: process.stdin.isTTY && process.stdout.isTTY,
-		setupWizardEnabled: settings.get("startup.setupWizard"),
-		force: forceSetupWizard,
-	});
+	// Cold-launch gate: the full setup wizard (every scene + the overlay and
+	// their TUI/OAuth/search/theme deps) is heavy, yet the common case only needs
+	// to know whether the stored setup version is current. Lazy-load the wizard
+	// barrel only when setup is stale or forced; otherwise skip it entirely.
+	const storedSetupVersion = settings.get("setupVersion");
+	const setupWizard =
+		forceSetupWizard || storedSetupVersion < CURRENT_SETUP_VERSION ? await import("./modes/setup-wizard") : undefined;
+	const setupScenes = setupWizard
+		? await setupWizard.selectSetupScenes(storedSetupVersion, setupWizard.ALL_SCENES, mode, {
+				resuming,
+				isTTY: process.stdin.isTTY && process.stdout.isTTY,
+				setupWizardEnabled: settings.get("startup.setupWizard"),
+				force: forceSetupWizard,
+			})
+		: [];
 
 	await mode.init({ suppressWelcomeIntro: resuming || setupScenes.length > 0 });
 
-	if (setupScenes.length > 0) {
-		await runSetupWizard(mode, setupScenes);
+	if (setupWizard && setupScenes.length > 0) {
+		await setupWizard.runSetupWizard(mode, setupScenes);
 	}
 
 	versionCheckPromise
@@ -716,7 +727,7 @@ async function buildSessionOptions(
 interface RunRootCommandDependencies {
 	createAgentSession?: typeof createAgentSession;
 	discoverAuthStorage?: typeof discoverAuthStorage;
-	runAcpMode?: typeof runAcpMode;
+	runAcpMode?: RunAcpMode;
 	settings?: Settings;
 	forceSetupWizard?: boolean;
 }
@@ -940,33 +951,11 @@ export async function runRootCommand(
 
 	await pluginPreloadPromise;
 
-	// Background marketplace auto-update — never blocks startup.
-	const autoUpdate = settingsInstance.get("marketplace.autoUpdate");
-	if (autoUpdate !== "off") {
-		void (async () => {
-			try {
-				const mgr = new MarketplaceManager({
-					marketplacesRegistryPath: getMarketplacesRegistryPath(),
-					installedRegistryPath: getInstalledPluginsRegistryPath(),
-					projectInstalledRegistryPath: (await resolveActiveProjectRegistryPath(getProjectDir())) ?? undefined,
-					marketplacesCacheDir: getMarketplacesCacheDir(),
-					pluginsCacheDir: getPluginsCacheDir(),
-					clearPluginRootsCache: clearPluginRootsAndCaches,
-				});
-				await mgr.refreshStaleMarketplaces();
-				const updates = await mgr.checkForUpdates();
-				if (updates.length === 0) return;
-				if (autoUpdate === "auto") {
-					await mgr.upgradeAllPlugins();
-					logger.debug(`Auto-upgraded ${updates.length} marketplace plugin(s)`);
-				} else {
-					logger.debug(`${updates.length} marketplace plugin update(s) available — /marketplace upgrade`);
-				}
-			} catch {
-				// Silently ignore — network failure, corrupt data, offline.
-			}
-		})();
-	}
+	scheduleMarketplaceAutoUpdate({
+		autoUpdate: settingsInstance.get("marketplace.autoUpdate"),
+		resolveActiveProjectRegistryPath,
+		clearPluginRootsCache: clearPluginRootsAndCaches,
+	});
 
 	const { options: sessionOptions } = await logger.time(
 		"buildSessionOptions",
@@ -1027,7 +1016,9 @@ export async function runRootCommand(
 			rawArgs,
 			createSession,
 		});
-		await (deps.runAcpMode ?? runAcpMode)(createAcpSession);
+		// Branch-only protocol runner: keep ACP server code out of normal interactive startup.
+		const runAcpMode = deps.runAcpMode ?? (await import("./modes/acp/acp-mode")).runAcpMode;
+		await runAcpMode(createAcpSession);
 	} else {
 		// Resolve extension-registered CLI flags before creating the session so a
 		// bad `@file` fails fast WITHOUT leaving a junk session/breadcrumb
@@ -1091,6 +1082,8 @@ export async function runRootCommand(
 		}
 
 		if (mode === "rpc" || mode === "rpc-ui") {
+			// Branch-only protocol runner: keep RPC host code out of normal interactive startup.
+			const runRpcMode: RunRpcMode = (await import("./modes/rpc/rpc-mode")).runRpcMode;
 			await runRpcMode(session, mode === "rpc-ui" ? setToolUIContext : undefined);
 		} else if (isInteractive) {
 			const versionCheckPromise = checkForNewVersion(VERSION).catch(() => undefined);
@@ -1109,7 +1102,7 @@ export async function runRootCommand(
 
 			if ($env.PI_TIMING) {
 				logger.printTimings();
-				if ($env.PI_TIMING === "x") {
+				if (logger.shouldExitAfterTimings()) {
 					process.exit(0);
 				}
 			}
@@ -1132,6 +1125,8 @@ export async function runRootCommand(
 				initialImages,
 			);
 		} else {
+			// Branch-only single-shot runner: keep print-mode code out of normal interactive startup.
+			const runPrintMode: RunPrintMode = (await import("./modes/print-mode")).runPrintMode;
 			await runPrintMode(session, {
 				mode,
 				messages: initialArgs.messages,
diff --git a/packages/coding-agent/src/modes/index.ts b/packages/coding-agent/src/modes/index.ts
index 9b2726d68..ac9f12896 100644
--- a/packages/coding-agent/src/modes/index.ts
+++ b/packages/coding-agent/src/modes/index.ts
@@ -2,11 +2,13 @@ import { emergencyTerminalRestore } from "@oh-my-pi/pi-tui";
 import { postmortem } from "@oh-my-pi/pi-utils";
 
 /**
- * Run modes for the coding agent.
+ * Interactive mode and embeddable RPC client exports for the coding agent.
+ *
+ * Branch-specific runners live in their concrete modules so importing this
+ * barrel does not pull print, RPC server, or ACP server mode into the normal
+ * TUI graph.
  */
-export { runAcpMode } from "./acp";
 export { InteractiveMode, type InteractiveModeOptions } from "./interactive-mode";
-export { type PrintModeOptions, runPrintMode } from "./print-mode";
 export {
 	defineRpcClientTool,
 	type ModelInfo,
@@ -17,7 +19,6 @@ export {
 	type RpcClientToolResult,
 	type RpcEventListener,
 } from "./rpc/rpc-client";
-export { runRpcMode } from "./rpc/rpc-mode";
 export type {
 	RpcCommand,
 	RpcHostToolCallRequest,
diff --git a/packages/coding-agent/src/modes/setup-version.ts b/packages/coding-agent/src/modes/setup-version.ts
new file mode 100644
index 000000000..33bed5051
--- /dev/null
+++ b/packages/coding-agent/src/modes/setup-version.ts
@@ -0,0 +1,11 @@
+/**
+ * Setup version the wizard advances a fresh install to. Bump it whenever a new
+ * setup scene lands (or an existing scene raises its `minVersion`).
+ *
+ * Kept in its own dependency-free module so the cold-launch gate in `main.ts`
+ * can answer "is the stored setup version stale?" without statically importing
+ * the full wizard — every scene (sign-in/OAuth, web search, theme previews) plus
+ * the overlay component and their TUI deps. MUST equal `max(scene.minVersion)`
+ * across `ALL_SCENES`; the `setup-wizard` barrel and test suite guard it.
+ */
+export const CURRENT_SETUP_VERSION = 1;
diff --git a/packages/coding-agent/src/modes/setup-wizard/index.ts b/packages/coding-agent/src/modes/setup-wizard/index.ts
index 29da5d873..5e5eea61d 100644
--- a/packages/coding-agent/src/modes/setup-wizard/index.ts
+++ b/packages/coding-agent/src/modes/setup-wizard/index.ts
@@ -1,4 +1,5 @@
 import type { Settings } from "../../config/settings";
+import { CURRENT_SETUP_VERSION } from "../setup-version";
 import type { InteractiveModeContext } from "../types";
 import { glyphSetupScene } from "./scenes/glyph";
 import { providersSetupScene } from "./scenes/providers";
@@ -8,14 +9,14 @@ import { SetupWizardComponent } from "./wizard-overlay";
 
 export type { SetupScene, SetupSceneController, SetupSceneHost, SetupSceneResult } from "./scenes/types";
 
+export { CURRENT_SETUP_VERSION };
+
 export const ALL_SCENES = [
 	providersSetupScene,
 	glyphSetupScene,
 	themeSetupScene,
 ] as const satisfies readonly SetupScene[];
 
-export const CURRENT_SETUP_VERSION = ALL_SCENES.reduce((max, scene) => Math.max(max, scene.minVersion), 0);
-
 export interface SetupSceneSelectionOptions {
 	resuming?: boolean;
 	isTTY?: boolean;
diff --git a/packages/coding-agent/test/setup-wizard.test.ts b/packages/coding-agent/test/setup-wizard.test.ts
index 7f01b01fe..7be0f62f0 100644
--- a/packages/coding-agent/test/setup-wizard.test.ts
+++ b/packages/coding-agent/test/setup-wizard.test.ts
@@ -49,6 +49,15 @@ describe("setup wizard scene selection", () => {
 		expect(scenes.map(scene => scene.id)).toEqual(ALL_SCENES.map(scene => scene.id));
 	});
 
+	it("keeps CURRENT_SETUP_VERSION in sync with the highest scene minVersion", () => {
+		// main.ts's cold-launch gate sources CURRENT_SETUP_VERSION from the tiny
+		// `setup-version` module to decide whether to load the wizard at all. If a
+		// new scene raises the bar but the constant is not bumped, stale installs
+		// would never see the scene. Guard the invariant the gate relies on.
+		const highestMinVersion = Math.max(...ALL_SCENES.map(scene => scene.minVersion));
+		expect(CURRENT_SETUP_VERSION).toBe(highestMinVersion);
+	});
+
 	it("runs only scenes newer than the stored setup version", async () => {
 		const scenes = [testScene("v1-a", 1), testScene("v1-b", 1), testScene("v2", 2)];
 		const selected = await selectSetupScenes(1, scenes, fakeContextWithConfiguredModel(), { isTTY: true });
diff --git a/packages/coding-agent/test/startup-import-graph.test.ts b/packages/coding-agent/test/startup-import-graph.test.ts
new file mode 100644
index 000000000..2a5d6d6a6
--- /dev/null
+++ b/packages/coding-agent/test/startup-import-graph.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "bun:test";
+import * as path from "node:path";
+
+const sourceRoot = path.join(import.meta.dir, "..", "src");
+
+describe("startup import graph", () => {
+	it("keeps normal startup off the aggregate modes barrel", async () => {
+		const mainSource = await Bun.file(path.join(sourceRoot, "main.ts")).text();
+
+		expect(mainSource).toContain('import { InteractiveMode } from "./modes/interactive-mode";');
+		expect(mainSource).not.toContain('from "./modes"');
+	});
+
+	it("keeps branch-only mode runners out of the modes barrel", async () => {
+		const modesBarrelSource = await Bun.file(path.join(sourceRoot, "modes/index.ts")).text();
+
+		expect(modesBarrelSource).toContain('from "./interactive-mode"');
+		expect(modesBarrelSource).not.toContain("runAcpMode");
+		expect(modesBarrelSource).not.toContain("runPrintMode");
+		expect(modesBarrelSource).not.toContain("runRpcMode");
+		expect(modesBarrelSource).not.toContain("./rpc/rpc-mode");
+	});
+
+	it("keeps marketplace implementation behind the lightweight auto-update starter", async () => {
+		const mainSource = await Bun.file(path.join(sourceRoot, "main.ts")).text();
+		const starterSource = await Bun.file(
+			path.join(sourceRoot, "extensibility/plugins/marketplace-auto-update.ts"),
+		).text();
+
+		expect(mainSource).toContain('from "./extensibility/plugins/marketplace-auto-update"');
+		expect(mainSource).not.toContain('from "./extensibility/plugins/marketplace"');
+		expect(starterSource).toContain('await import("./marketplace")');
+	});
+});

From ba6cc67f38728b7c258130732d91404e03064bbf Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:58:33 +0200
Subject: [PATCH 059/181] refactor(packages/ai): migrated effort types to
 dependency-free module

- Added dependency-free `@oh-my-pi/pi-ai/effort` module and re-exported `Effort`/`THINKING_EFFORTS`.
- Moved `Effort` and `THINKING_EFFORTS` from `model-thinking.ts` to `effort.ts`, then migrated runtime/tests imports.
---
 packages/ai/CHANGELOG.md                       |  4 ++++
 packages/ai/src/auth-gateway/server.ts         |  2 +-
 packages/ai/src/auth-gateway/types.ts          |  2 +-
 packages/ai/src/effort.ts                      | 16 ++++++++++++++++
 packages/ai/src/index.ts                       |  1 +
 packages/ai/src/model-thinking.ts              | 18 +-----------------
 packages/ai/src/provider-models/ollama.ts      |  2 +-
 .../ai/src/provider-models/openai-compat.ts    |  2 +-
 packages/ai/src/providers/amazon-bedrock.ts    |  2 +-
 .../openai-codex/request-transformer.ts        |  2 +-
 .../ai/src/providers/openai-completions.ts     |  3 ++-
 packages/ai/src/stream.ts                      |  2 +-
 packages/ai/src/types.ts                       |  2 +-
 .../test/auth-gateway-openai-responses.test.ts |  2 +-
 .../ai/test/auth-gateway-pi-native.test.ts     |  2 +-
 .../test/github-copilot-model-limits.test.ts   |  2 +-
 .../ai/test/github-copilot-reasoning.test.ts   |  2 +-
 packages/ai/test/issue-1373-repro.test.ts      |  2 +-
 packages/ai/test/issue-826-repro.test.ts       |  2 +-
 packages/ai/test/issue-969-repro.test.ts       |  3 ++-
 packages/ai/test/model-thinking.test.ts        |  2 +-
 packages/ai/test/nanogpt-model-limits.test.ts  |  2 +-
 packages/ai/test/ollama-provider.test.ts       |  2 +-
 ...penai-completions-disable-reasoning.test.ts |  2 +-
 24 files changed, 44 insertions(+), 37 deletions(-)
 create mode 100644 packages/ai/src/effort.ts

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index e3cd50803..db832fa7b 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added a dependency-free `@oh-my-pi/pi-ai/effort` module exporting the `Effort` enum and `THINKING_EFFORTS`, split out of `model-thinking` so hot-path consumers can import the thinking levels without pulling in `model-thinking` and its provider-compat dependency graph. The package barrel still re-exports both names, so existing imports are unaffected.
+
 ### Fixed
 
 - Fixed Antigravity usage provider emitting one bar per model instead of deduplicating by tier — a single account's 15+ model entries now collapse to one bar per tier, matching the shared-quota reality of the upstream API.
diff --git a/packages/ai/src/auth-gateway/server.ts b/packages/ai/src/auth-gateway/server.ts
index dad2aa394..f5b0d9383 100644
--- a/packages/ai/src/auth-gateway/server.ts
+++ b/packages/ai/src/auth-gateway/server.ts
@@ -19,7 +19,7 @@
  */
 import { extractRetryHint, logger } from "@oh-my-pi/pi-utils";
 import type { AuthStorage } from "../auth-storage";
-import { Effort } from "../model-thinking";
+import { Effort } from "../effort";
 import * as anthropicMessages from "../providers/anthropic-messages-server";
 import * as openaiChat from "../providers/openai-chat-server";
 import * as openaiResponses from "../providers/openai-responses-server";
diff --git a/packages/ai/src/auth-gateway/types.ts b/packages/ai/src/auth-gateway/types.ts
index 0390759c0..bdb563e3b 100644
--- a/packages/ai/src/auth-gateway/types.ts
+++ b/packages/ai/src/auth-gateway/types.ts
@@ -1,4 +1,4 @@
-import type { Effort } from "../model-thinking";
+import type { Effort } from "../effort";
 import type {
 	AssistantMessage,
 	AssistantMessageEventStream,
diff --git a/packages/ai/src/effort.ts b/packages/ai/src/effort.ts
new file mode 100644
index 000000000..831a13ede
--- /dev/null
+++ b/packages/ai/src/effort.ts
@@ -0,0 +1,16 @@
+/** User-facing thinking levels, ordered least to most intensive. */
+export const enum Effort {
+	Minimal = "minimal",
+	Low = "low",
+	Medium = "medium",
+	High = "high",
+	XHigh = "xhigh",
+}
+
+export const THINKING_EFFORTS: readonly Effort[] = [
+	Effort.Minimal,
+	Effort.Low,
+	Effort.Medium,
+	Effort.High,
+	Effort.XHigh,
+];
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index ecdce180e..3b1e855a3 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -4,6 +4,7 @@ export * from "./auth-broker";
 export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } from "./auth-gateway/server";
 export * from "./auth-gateway/types";
 export * from "./auth-storage";
+export * from "./effort";
 export * from "./model-cache";
 export * from "./model-manager";
 export * from "./model-thinking";
diff --git a/packages/ai/src/model-thinking.ts b/packages/ai/src/model-thinking.ts
index 75e930315..7c963bdbe 100644
--- a/packages/ai/src/model-thinking.ts
+++ b/packages/ai/src/model-thinking.ts
@@ -1,23 +1,7 @@
+import { Effort, THINKING_EFFORTS } from "./effort";
 import { resolveOpenAICompat } from "./providers/openai-completions-compat";
 import type { Api, Model as ApiModel, ThinkingConfig } from "./types";
 
-/** User-facing thinking levels, ordered least to most intensive. */
-export const enum Effort {
-	Minimal = "minimal",
-	Low = "low",
-	Medium = "medium",
-	High = "high",
-	XHigh = "xhigh",
-}
-
-export const THINKING_EFFORTS: readonly Effort[] = [
-	Effort.Minimal,
-	Effort.Low,
-	Effort.Medium,
-	Effort.High,
-	Effort.XHigh,
-];
-
 const DEFAULT_REASONING_EFFORTS: readonly Effort[] = [Effort.Minimal, Effort.Low, Effort.Medium, Effort.High];
 const DEFAULT_REASONING_EFFORTS_WITH_XHIGH: readonly Effort[] = [
 	Effort.Minimal,
diff --git a/packages/ai/src/provider-models/ollama.ts b/packages/ai/src/provider-models/ollama.ts
index c71fbf617..ed539d924 100644
--- a/packages/ai/src/provider-models/ollama.ts
+++ b/packages/ai/src/provider-models/ollama.ts
@@ -1,6 +1,6 @@
 import { fetchWithRetry } from "@oh-my-pi/pi-utils";
+import { Effort } from "../effort";
 import type { ModelManagerOptions } from "../model-manager";
-import { Effort } from "../model-thinking";
 import type { ThinkingConfig } from "../types";
 import { createBundledReferenceMap, createReferenceResolver } from "./bundled-references";
 
diff --git a/packages/ai/src/provider-models/openai-compat.ts b/packages/ai/src/provider-models/openai-compat.ts
index d774bfd9f..545662fa4 100644
--- a/packages/ai/src/provider-models/openai-compat.ts
+++ b/packages/ai/src/provider-models/openai-compat.ts
@@ -1,5 +1,5 @@
+import { Effort } from "../effort";
 import type { ModelManagerOptions } from "../model-manager";
-import { Effort } from "../model-thinking";
 import { getBundledModels } from "../models";
 import type { Api, Model, Provider, ThinkingConfig } from "../types";
 import { isAnthropicOAuthToken, isRecord, toBoolean, toNumber, toPositiveNumber } from "../utils";
diff --git a/packages/ai/src/providers/amazon-bedrock.ts b/packages/ai/src/providers/amazon-bedrock.ts
index 7f161f32c..49b1523aa 100644
--- a/packages/ai/src/providers/amazon-bedrock.ts
+++ b/packages/ai/src/providers/amazon-bedrock.ts
@@ -8,7 +8,7 @@
  */
 
 import { $env, $flag, extractHttpStatusFromError, fetchWithRetry } from "@oh-my-pi/pi-utils";
-import type { Effort } from "../model-thinking";
+import type { Effort } from "../effort";
 import { mapEffortToAnthropicAdaptiveEffort, requireSupportedEffort } from "../model-thinking";
 import { calculateCost } from "../models";
 import type {
diff --git a/packages/ai/src/providers/openai-codex/request-transformer.ts b/packages/ai/src/providers/openai-codex/request-transformer.ts
index a12996ca6..91abe9dc5 100644
--- a/packages/ai/src/providers/openai-codex/request-transformer.ts
+++ b/packages/ai/src/providers/openai-codex/request-transformer.ts
@@ -1,4 +1,4 @@
-import type { Effort } from "../../model-thinking";
+import type { Effort } from "../../effort";
 import { requireSupportedEffort } from "../../model-thinking";
 import type { Api, Model } from "../../types";
 
diff --git a/packages/ai/src/providers/openai-completions.ts b/packages/ai/src/providers/openai-completions.ts
index b8b5e591c..67cae1e4a 100644
--- a/packages/ai/src/providers/openai-completions.ts
+++ b/packages/ai/src/providers/openai-completions.ts
@@ -10,7 +10,8 @@ import type {
 	ChatCompletionToolMessageParam,
 } from "openai/resources/chat/completions";
 import packageJson from "../../package.json" with { type: "json" };
-import { type Effort, getSupportedEfforts } from "../model-thinking";
+import type { Effort } from "../effort";
+import { getSupportedEfforts } from "../model-thinking";
 import { calculateCost } from "../models";
 import { getEnvApiKey } from "../stream";
 import {
diff --git a/packages/ai/src/stream.ts b/packages/ai/src/stream.ts
index 437a49344..a7d5fc739 100644
--- a/packages/ai/src/stream.ts
+++ b/packages/ai/src/stream.ts
@@ -3,7 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { $env, $pickenv, extractHttpStatusFromError } from "@oh-my-pi/pi-utils";
 import { getCustomApi } from "./api-registry";
-import type { Effort } from "./model-thinking";
+import type { Effort } from "./effort";
 import {
 	mapEffortToAnthropicAdaptiveEffort,
 	mapEffortToGoogleThinkingLevel,
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 9b03d99d8..4cf00265f 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -151,7 +151,7 @@ export type KnownProvider =
 	| "lm-studio";
 export type Provider = KnownProvider | string;
 
-import type { Effort } from "./model-thinking";
+import type { Effort } from "./effort";
 
 /** Token budgets for each thinking level (token-based providers only) */
 export type ThinkingBudgets = { [key in Effort]?: number };
diff --git a/packages/ai/test/auth-gateway-openai-responses.test.ts b/packages/ai/test/auth-gateway-openai-responses.test.ts
index fe3a21801..c6cbd8c9b 100644
--- a/packages/ai/test/auth-gateway-openai-responses.test.ts
+++ b/packages/ai/test/auth-gateway-openai-responses.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { Effort } from "../src/model-thinking";
+import { Effort } from "../src/effort";
 import { encodeResponse, encodeStream, parseRequest } from "../src/providers/openai-responses-server";
 import type { AssistantMessage } from "../src/types";
 import { AssistantMessageEventStream } from "../src/utils/event-stream";
diff --git a/packages/ai/test/auth-gateway-pi-native.test.ts b/packages/ai/test/auth-gateway-pi-native.test.ts
index 7c10a65a7..5f3a77a76 100644
--- a/packages/ai/test/auth-gateway-pi-native.test.ts
+++ b/packages/ai/test/auth-gateway-pi-native.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { Effort } from "../src/model-thinking";
+import { Effort } from "../src/effort";
 import { encodeStream, formatError, parseRequest } from "../src/providers/pi-native-server";
 import type {
 	AssistantMessage,
diff --git a/packages/ai/test/github-copilot-model-limits.test.ts b/packages/ai/test/github-copilot-model-limits.test.ts
index c46f14487..07d76ee87 100644
--- a/packages/ai/test/github-copilot-model-limits.test.ts
+++ b/packages/ai/test/github-copilot-model-limits.test.ts
@@ -2,8 +2,8 @@ import { afterEach, describe, expect, it, vi } from "bun:test";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { Effort } from "../src/effort";
 import { createModelManager } from "../src/model-manager";
-import { Effort } from "../src/model-thinking";
 import { getBundledModel } from "../src/models";
 import { githubCopilotModelManagerOptions } from "../src/provider-models/openai-compat";
 
diff --git a/packages/ai/test/github-copilot-reasoning.test.ts b/packages/ai/test/github-copilot-reasoning.test.ts
index 32a88c006..28746c85d 100644
--- a/packages/ai/test/github-copilot-reasoning.test.ts
+++ b/packages/ai/test/github-copilot-reasoning.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { Effort } from "../src/model-thinking";
+import { Effort } from "../src/effort";
 import { getBundledModel } from "../src/models";
 import { streamAnthropic } from "../src/providers/anthropic";
 import { streamOpenAIResponses } from "../src/providers/openai-responses";
diff --git a/packages/ai/test/issue-1373-repro.test.ts b/packages/ai/test/issue-1373-repro.test.ts
index 986acbf3c..88e855f4e 100644
--- a/packages/ai/test/issue-1373-repro.test.ts
+++ b/packages/ai/test/issue-1373-repro.test.ts
@@ -1,5 +1,5 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
-import { Effort } from "../src/model-thinking";
+import { Effort } from "../src/effort";
 import { streamBedrock } from "../src/providers/amazon-bedrock";
 import type { Context, Model } from "../src/types";
 
diff --git a/packages/ai/test/issue-826-repro.test.ts b/packages/ai/test/issue-826-repro.test.ts
index efcf9ccea..dd78aeda0 100644
--- a/packages/ai/test/issue-826-repro.test.ts
+++ b/packages/ai/test/issue-826-repro.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { Effort } from "../src/model-thinking";
+import { Effort } from "../src/effort";
 import { streamAnthropic } from "../src/providers/anthropic";
 import type { Context, Model, Tool } from "../src/types";
 
diff --git a/packages/ai/test/issue-969-repro.test.ts b/packages/ai/test/issue-969-repro.test.ts
index 1b347470e..9f42a85bb 100644
--- a/packages/ai/test/issue-969-repro.test.ts
+++ b/packages/ai/test/issue-969-repro.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it } from "bun:test";
-import { Effort, getSupportedEfforts } from "../src/model-thinking";
+import { Effort } from "../src/effort";
+import { getSupportedEfforts } from "../src/model-thinking";
 import { streamOpenAICompletions } from "../src/providers/openai-completions";
 import type { Context, Model } from "../src/types";
 
diff --git a/packages/ai/test/model-thinking.test.ts b/packages/ai/test/model-thinking.test.ts
index 89b90da8e..e8475974c 100644
--- a/packages/ai/test/model-thinking.test.ts
+++ b/packages/ai/test/model-thinking.test.ts
@@ -1,8 +1,8 @@
 import { describe, expect, it } from "bun:test";
+import { Effort } from "@oh-my-pi/pi-ai/effort";
 import {
 	applyGeneratedModelPolicies,
 	clampThinkingLevelForModel,
-	Effort,
 	enrichModelThinking,
 	linkOpenAIPromotionTargets,
 	mapEffortToAnthropicAdaptiveEffort,
diff --git a/packages/ai/test/nanogpt-model-limits.test.ts b/packages/ai/test/nanogpt-model-limits.test.ts
index 03d7b8bab..0270b18ff 100644
--- a/packages/ai/test/nanogpt-model-limits.test.ts
+++ b/packages/ai/test/nanogpt-model-limits.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "bun:test";
-import { Effort } from "../src/model-thinking";
+import { Effort } from "../src/effort";
 import { nanoGptModelManagerOptions } from "../src/provider-models/openai-compat";
 
 const originalFetch = global.fetch;
diff --git a/packages/ai/test/ollama-provider.test.ts b/packages/ai/test/ollama-provider.test.ts
index 1a2e2aadb..4fa4866c2 100644
--- a/packages/ai/test/ollama-provider.test.ts
+++ b/packages/ai/test/ollama-provider.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test, vi } from "bun:test";
-import { Effort } from "../src/model-thinking";
+import { Effort } from "../src/effort";
 import { ollamaModelManagerOptions } from "../src/provider-models/openai-compat";
 import { streamOllama } from "../src/providers/ollama";
 import type { Context, Model, Tool } from "../src/types";
diff --git a/packages/ai/test/openai-completions-disable-reasoning.test.ts b/packages/ai/test/openai-completions-disable-reasoning.test.ts
index f2d9107f6..629a74887 100644
--- a/packages/ai/test/openai-completions-disable-reasoning.test.ts
+++ b/packages/ai/test/openai-completions-disable-reasoning.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from "bun:test";
-import { Effort } from "../src/model-thinking";
+import { Effort } from "../src/effort";
 import { streamOpenAICompletions } from "../src/providers/openai-completions";
 import type { Context, Model } from "../src/types";
 

From 76f08dd7d3d3537238c4e5cf7828987182224368 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 22:58:33 +0200
Subject: [PATCH 060/181] refactor(packages/coding-agent): migrated imports to
 pi-ai submodules

- Migrated Effort and THINKING_EFFORTS imports to @oh-my-pi/pi-ai/effort in CLI args and launch command files.
- Split model-registry dependencies across focused @oh-my-pi/pi-ai submodules instead of the root barrel export.
---
 packages/coding-agent/src/cli/args.ts         |  2 +-
 packages/coding-agent/src/commands/launch.ts  |  2 +-
 .../coding-agent/src/config/model-registry.ts | 24 +++++++------------
 3 files changed, 10 insertions(+), 18 deletions(-)

diff --git a/packages/coding-agent/src/cli/args.ts b/packages/coding-agent/src/cli/args.ts
index 0f770c0ce..707d87c54 100644
--- a/packages/coding-agent/src/cli/args.ts
+++ b/packages/coding-agent/src/cli/args.ts
@@ -1,7 +1,7 @@
 /**
  * CLI argument parsing and help display
  */
-import { type Effort, THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
+import { type Effort, THINKING_EFFORTS } from "@oh-my-pi/pi-ai/effort";
 import { APP_NAME, CONFIG_DIR_NAME, logger } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { parseEffort } from "../thinking";
diff --git a/packages/coding-agent/src/commands/launch.ts b/packages/coding-agent/src/commands/launch.ts
index a752cdf82..d26dc543a 100644
--- a/packages/coding-agent/src/commands/launch.ts
+++ b/packages/coding-agent/src/commands/launch.ts
@@ -2,7 +2,7 @@
  * Root command for the coding agent CLI.
  */
 
-import { THINKING_EFFORTS } from "@oh-my-pi/pi-ai";
+import { THINKING_EFFORTS } from "@oh-my-pi/pi-ai/effort";
 import { APP_NAME } from "@oh-my-pi/pi-utils";
 import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
 import { parseArgs } from "../cli/args";
diff --git a/packages/coding-agent/src/config/model-registry.ts b/packages/coding-agent/src/config/model-registry.ts
index ac83a06ce..eb35413e1 100644
--- a/packages/coding-agent/src/config/model-registry.ts
+++ b/packages/coding-agent/src/config/model-registry.ts
@@ -1,27 +1,19 @@
 import * as path from "node:path";
+import { registerCustomApi, unregisterCustomApis } from "@oh-my-pi/pi-ai/api-registry";
+import { readModelCache } from "@oh-my-pi/pi-ai/model-cache";
+import { createModelManager, type ModelManagerOptions, type ModelRefreshStrategy } from "@oh-my-pi/pi-ai/model-manager";
+import { enrichModelThinking } from "@oh-my-pi/pi-ai/model-thinking";
+import { getBundledModels, getBundledProviders } from "@oh-my-pi/pi-ai/models";
 import {
-	type Api,
-	type AssistantMessageEventStream,
-	type Context,
-	createModelManager,
-	enrichModelThinking,
-	getBundledModels,
-	getBundledProviders,
 	googleAntigravityModelManagerOptions,
 	googleGeminiCliModelManagerOptions,
-	type Model,
-	type ModelManagerOptions,
-	type ModelRefreshStrategy,
 	openaiCodexModelManagerOptions,
 	PROVIDER_DESCRIPTORS,
-	readModelCache,
-	registerCustomApi,
-	type SimpleStreamOptions,
-	type ThinkingConfig,
 	UNK_CONTEXT_WINDOW,
 	UNK_MAX_TOKENS,
-	unregisterCustomApis,
-} from "@oh-my-pi/pi-ai";
+} from "@oh-my-pi/pi-ai/provider-models";
+import type { Api, Context, Model, SimpleStreamOptions, ThinkingConfig } from "@oh-my-pi/pi-ai/types";
+import type { AssistantMessageEventStream } from "@oh-my-pi/pi-ai/utils/event-stream";
 
 // Sentinel for local-only OAuth token (LM Studio, vLLM) — declared inline to avoid loading
 // any provider module at startup. Must match `DEFAULT_LOCAL_TOKEN` in oauth/lm-studio.ts.

From 5ec6c0e7a7c37e586a5949780cba04ceaa01af17 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 23:07:57 +0200
Subject: [PATCH 061/181] fix(coding-agent): removed redundant official-id
 canonical shortcut

- Let heuristic candidate matching handle official ids uniformly.
---
 packages/coding-agent/src/config/model-equivalence.ts | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/packages/coding-agent/src/config/model-equivalence.ts b/packages/coding-agent/src/config/model-equivalence.ts
index 8115f7d87..dd8185ab4 100644
--- a/packages/coding-agent/src/config/model-equivalence.ts
+++ b/packages/coding-agent/src/config/model-equivalence.ts
@@ -771,9 +771,6 @@ function resolveCanonicalIdForModel(
 		return { id: claudeFamilyAlias, source: claudeFamilyAlias === model.id ? "bundled" : "heuristic" };
 	}
 
-	if (referenceData.officialIds.has(model.id) && !model.id.includes("/") && !model.id.includes(":")) {
-		return { id: model.id, source: "bundled" };
-	}
 
 	const heuristicCandidates = getHeuristicCanonicalCandidates(model.id, referenceData.officialIds);
 	const officialMatches = new Set<string>();

From f552ce4e6d098572bbfe4261a1f2f36566ca7d90 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 23:25:18 +0200
Subject: [PATCH 062/181] perf(coding-agent): deferred heavy module imports to
 startup paths

- Lazy-loaded OTEL SDK, HTML export, TTSR, and autoresearch modules.
- Made resolveMemoryBackend async to import backends on demand.
- Replaced backend resolution with direct settings reads for rekey checks.
---
 .../src/config/model-equivalence.ts           |  1 -
 packages/coding-agent/src/main.ts             |  4 +-
 .../coding-agent/src/memory-backend/index.ts  | 14 ++++++-
 .../src/memory-backend/resolve.ts             |  8 ++--
 .../coding-agent/src/memory-backend/types.ts  |  2 +-
 .../modes/controllers/command-controller.ts   |  4 +-
 .../modes/controllers/selector-controller.ts  |  4 +-
 .../src/modes/interactive-mode.ts             |  4 +-
 packages/coding-agent/src/modes/types.ts      |  2 +-
 packages/coding-agent/src/sdk.ts              | 42 +++++++++----------
 .../coding-agent/src/session/agent-session.ts | 14 +++----
 .../src/slash-commands/builtin-registry.ts    |  2 +-
 packages/coding-agent/src/telemetry-export.ts | 32 ++++++++++----
 .../test/memory-backend-resolve.test.ts       |  6 +--
 .../coding-agent/test/otel-export-probe.ts    |  2 +-
 .../test/telemetry-export.test.ts             | 24 +++++------
 16 files changed, 95 insertions(+), 70 deletions(-)

diff --git a/packages/coding-agent/src/config/model-equivalence.ts b/packages/coding-agent/src/config/model-equivalence.ts
index dd8185ab4..75fedfc2b 100644
--- a/packages/coding-agent/src/config/model-equivalence.ts
+++ b/packages/coding-agent/src/config/model-equivalence.ts
@@ -771,7 +771,6 @@ function resolveCanonicalIdForModel(
 		return { id: claudeFamilyAlias, source: claudeFamilyAlias === model.id ? "bundled" : "heuristic" };
 	}
 
-
 	const heuristicCandidates = getHeuristicCanonicalCandidates(model.id, referenceData.officialIds);
 	const officialMatches = new Set<string>();
 	for (const candidate of heuristicCandidates) {
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index fa4c24011..a0f7fa1a0 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -40,7 +40,6 @@ import {
 	resolveActiveProjectRegistryPath,
 } from "./discovery/helpers";
 import { injectOmpExtensionCliRoots } from "./discovery/omp-extension-roots";
-import { exportFromFile } from "./export/html";
 import { ExtensionRunner } from "./extensibility/extensions/runner";
 import type { ExtensionUIContext } from "./extensibility/extensions/types";
 import { scheduleMarketplaceAutoUpdate } from "./extensibility/plugins/marketplace-auto-update";
@@ -784,6 +783,7 @@ export async function runRootCommand(
 		let result: string;
 		try {
 			const outputPath = parsedArgs.messages.length > 0 ? parsedArgs.messages[0] : undefined;
+			const { exportFromFile } = await import("./export/html");
 			result = await exportFromFile(parsedArgs.export, outputPath);
 		} catch (error: unknown) {
 			const message = error instanceof Error ? error.message : "Failed to export session";
@@ -977,7 +977,7 @@ export async function runRootCommand(
 	// Both are no-ops when OTEL_EXPORTER_OTLP_ENDPOINT is unset. An empty config
 	// is enough to enable telemetry — content capture is governed by the
 	// standard OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT env var.
-	initTelemetryExport();
+	await initTelemetryExport();
 	if (isTelemetryExportEnabled()) {
 		sessionOptions.telemetry = {};
 	}
diff --git a/packages/coding-agent/src/memory-backend/index.ts b/packages/coding-agent/src/memory-backend/index.ts
index 2c2c678a3..62f504ee4 100644
--- a/packages/coding-agent/src/memory-backend/index.ts
+++ b/packages/coding-agent/src/memory-backend/index.ts
@@ -1,4 +1,16 @@
-export * from "../mnemopi";
+export type {
+	MnemopiBackendConfig,
+	MnemopiLlmMode,
+	MnemopiProviderOptions,
+	MnemopiScoping,
+} from "../mnemopi/config";
+export type {
+	MnemopiMemoryEditOperation,
+	MnemopiMemoryEditOptions,
+	MnemopiMemoryEditResult,
+	MnemopiSessionState,
+	MnemopiSessionStateOptions,
+} from "../mnemopi/state";
 export * from "./local-backend";
 export * from "./off-backend";
 export * from "./resolve";
diff --git a/packages/coding-agent/src/memory-backend/resolve.ts b/packages/coding-agent/src/memory-backend/resolve.ts
index a0066d7f9..638aabec1 100644
--- a/packages/coding-agent/src/memory-backend/resolve.ts
+++ b/packages/coding-agent/src/memory-backend/resolve.ts
@@ -1,6 +1,4 @@
 import type { Settings } from "../config/settings";
-import { hindsightBackend } from "../hindsight";
-import { mnemopiBackend } from "../mnemopi";
 import { localBackend } from "./local-backend";
 import { offBackend } from "./off-backend";
 import type { MemoryBackend } from "./types";
@@ -18,10 +16,10 @@ import type { MemoryBackend } from "./types";
  * `memories.enabled` remains accepted only as a legacy migration input. Once
  * a config is loaded, `memory.backend` is the sole runtime selector.
  */
-export function resolveMemoryBackend(settings: Settings): MemoryBackend {
+export async function resolveMemoryBackend(settings: Settings): Promise<MemoryBackend> {
 	const id = settings.get("memory.backend");
-	if (id === "hindsight") return hindsightBackend;
-	if (id === "mnemopi") return mnemopiBackend;
+	if (id === "hindsight") return (await import("../hindsight/backend")).hindsightBackend;
+	if (id === "mnemopi") return (await import("../mnemopi/backend")).mnemopiBackend;
 	if (id === "local") return localBackend;
 	return offBackend;
 }
diff --git a/packages/coding-agent/src/memory-backend/types.ts b/packages/coding-agent/src/memory-backend/types.ts
index 3d72976ea..8b2e5cd15 100644
--- a/packages/coding-agent/src/memory-backend/types.ts
+++ b/packages/coding-agent/src/memory-backend/types.ts
@@ -1,7 +1,7 @@
 /**
  * Memory backend abstraction.
  *
- * Backends are mutually exclusive — `resolveMemoryBackend(settings)` returns
+ * Backends are mutually exclusive — `await resolveMemoryBackend(settings)` resolves
  * exactly one. Implementations MUST be self-contained: they own the per-session
  * state they create in `start()` and tear it down on `clear()`.
  */
diff --git a/packages/coding-agent/src/modes/controllers/command-controller.ts b/packages/coding-agent/src/modes/controllers/command-controller.ts
index a64a254f1..23462c9a2 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller.ts
@@ -13,7 +13,6 @@ import { Loader, Markdown, padding, Spacer, Text, visibleWidth } from "@oh-my-pi
 import { formatDuration, Snowflake } from "@oh-my-pi/pi-utils";
 import { $ } from "bun";
 import { shouldEnableAppendOnlyContext } from "../../config/append-only-context-mode";
-import { loadCustomShare } from "../../export/custom-share";
 import type { CompactOptions } from "../../extensibility/extensions/types";
 import {
 	diffMentalModelContent,
@@ -131,6 +130,7 @@ export class CommandController {
 		}
 
 		try {
+			const { loadCustomShare } = await import("../../export/custom-share");
 			const customShare = await loadCustomShare();
 			if (customShare) {
 				const loader = new BorderedLoader(this.ctx.ui, theme, "Sharing...");
@@ -465,7 +465,7 @@ export class CommandController {
 		const argumentText = text.slice(7).trim();
 		const action = argumentText.split(/\s+/, 1)[0]?.toLowerCase() || "view";
 		const agentDir = this.ctx.settings.getAgentDir();
-		const backend = resolveMemoryBackend(this.ctx.settings);
+		const backend = await resolveMemoryBackend(this.ctx.settings);
 
 		if (action === "view") {
 			const payload = await backend.buildDeveloperInstructions(agentDir, this.ctx.settings, this.ctx.session);
diff --git a/packages/coding-agent/src/modes/controllers/selector-controller.ts b/packages/coding-agent/src/modes/controllers/selector-controller.ts
index df8ae8d1b..b6c7cfffe 100644
--- a/packages/coding-agent/src/modes/controllers/selector-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/selector-controller.ts
@@ -7,7 +7,6 @@ import { getAgentDbPath, getProjectDir, normalizePathForComparison } from "@oh-m
 import { getRoleInfo } from "../../config/model-registry";
 import { formatModelSelectorValue } from "../../config/model-resolver";
 import { settings } from "../../config/settings";
-import { DebugSelectorComponent } from "../../debug";
 import { disableProvider, enableProvider } from "../../discovery";
 import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
 import {
@@ -1080,7 +1079,8 @@ export class SelectorController {
 		});
 	}
 
-	showDebugSelector(): void {
+	async showDebugSelector(): Promise<void> {
+		const { DebugSelectorComponent } = await import("../../debug");
 		this.showSelector(done => {
 			const selector = new DebugSelectorComponent(this.ctx, done);
 			return { component: selector, focus: selector };
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index 009ef43e1..1166097df 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -2844,8 +2844,8 @@ export class InteractiveMode implements InteractiveModeContext {
 		}
 	}
 
-	showDebugSelector(): void {
-		this.#selectorController.showDebugSelector();
+	async showDebugSelector(): Promise<void> {
+		await this.#selectorController.showDebugSelector();
 	}
 
 	showSessionObserver(): void {
diff --git a/packages/coding-agent/src/modes/types.ts b/packages/coding-agent/src/modes/types.ts
index 2b38238a4..de2cfa880 100644
--- a/packages/coding-agent/src/modes/types.ts
+++ b/packages/coding-agent/src/modes/types.ts
@@ -269,7 +269,7 @@ export interface InteractiveModeContext {
 	handleSessionDeleteCommand(): Promise<void>;
 	showOAuthSelector(mode: "login" | "logout", providerId?: string): Promise<void>;
 	showHookConfirm(title: string, message: string): Promise<boolean>;
-	showDebugSelector(): void;
+	showDebugSelector(): Promise<void>;
 	showSessionObserver(): void;
 	resetObserverRegistry(): void;
 
diff --git a/packages/coding-agent/src/sdk.ts b/packages/coding-agent/src/sdk.ts
index 70bbcb58c..46ad4553e 100644
--- a/packages/coding-agent/src/sdk.ts
+++ b/packages/coding-agent/src/sdk.ts
@@ -36,7 +36,6 @@ import {
 } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from "./async";
-import { createAutoresearchExtension } from "./autoresearch";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { bucketRules } from "./capability/rule-buckets";
@@ -57,7 +56,6 @@ import { resolveConfigValue } from "./config/resolve-config-value";
 import { initializeWithSettings } from "./discovery";
 import { disposeAllKernelSessions, disposeKernelSessionsByOwner } from "./eval/py/executor";
 import { defaultEvalSessionId } from "./eval/session-id";
-import { TtsrManager } from "./export/ttsr";
 import {
 	type CustomCommandsLoadResult,
 	type LoadedCustomCommand,
@@ -90,7 +88,7 @@ import { LocalProtocolHandler, type LocalProtocolOptions } from "./internal-urls
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "./lsp/startup-events";
 import { discoverAndLoadMCPTools, MCPManager, type MCPToolsLoadResult } from "./mcp";
 import { resolveMemoryBackend } from "./memory-backend";
-import { getMnemopiSessionState, type MnemopiSessionState } from "./mnemopi/state";
+import type { MnemopiSessionState } from "./mnemopi/state";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "./registry/agent-registry";
 import {
@@ -1150,6 +1148,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 	// Discover rules and bucket them in one pass to avoid repeated scans over large rule sets.
 	const { ttsrManager, rulebookRules, alwaysApplyRules } = await logger.time("discoverTtsrRules", async () => {
+		const { TtsrManager } = await import("./export/ttsr");
 		const ttsrSettings = settings.getGroup("ttsr");
 		const ttsrManager = new TtsrManager(ttsrSettings);
 		const rulesResult =
@@ -1295,7 +1294,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				session ? session.trackEvalExecution(execution, abortController) : execution,
 			getSessionId: () => sessionManager.getSessionId?.() ?? null,
 			getHindsightSessionState: () => session?.getHindsightSessionState(),
-			getMnemopiSessionState: () => getMnemopiSessionState(session),
+			getMnemopiSessionState: () => session?.getMnemopiSessionState(),
 			getAgentId: () => resolvedAgentId,
 			getToolByName: name => session?.getToolByName(name),
 			agentRegistry,
@@ -1472,7 +1471,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		}
 
 		const inlineExtensions: ExtensionFactory[] = options.extensions ? [...options.extensions] : [];
-		inlineExtensions.push(createAutoresearchExtension);
+		inlineExtensions.push((await import("./autoresearch")).createAutoresearchExtension);
 		if (customTools.length > 0) {
 			inlineExtensions.push(createCustomToolsExtension(customTools));
 		}
@@ -1607,9 +1606,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// `ExtensionToolWrapper` installed below is the only place the per-tool approval gate runs.
 		// A conditional runner means the approval system silently disappears for users with no
 		// extensions, contradicting non-yolo `tools.approvalMode` settings without feedback.
-		// (Today `createAutoresearchExtension` is unconditionally pushed below, so this scenario
-		// is unreachable; the unconditional construction makes that invariant explicit instead of
-		// implicit, so a future change to make autoresearch optional cannot silently re-open the hole.)
+		// (The builtin autoresearch extension is unconditionally loaded above, so this scenario
+		// is unreachable; unconditional runner construction keeps that invariant explicit and
+		// prevents future optional extensions from silently re-opening the hole.)
 		const extensionRunner: ExtensionRunner = new ExtensionRunner(
 			extensionsResult.extensions,
 			extensionsResult.runtime,
@@ -1749,7 +1748,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			const promptTools = buildSystemPromptToolMetadata(tools, {
 				search_tool_bm25: { description: renderSearchToolBm25Description(discoverableToolsForDesc) },
 			});
-			const memoryBackend = resolveMemoryBackend(settings);
+			const memoryBackend = await resolveMemoryBackend(settings);
 			const memoryInstructions = await memoryBackend.buildDeveloperInstructions(agentDir, settings, session);
 
 			// Build combined append prompt: memory instructions + MCP server instructions
@@ -2267,19 +2266,18 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}
 		}
 
-		logger.time("startMemoryStartupTask", () =>
-			Promise.resolve(
-				resolveMemoryBackend(settings).start({
-					session,
-					settings,
-					modelRegistry,
-					agentDir,
-					taskDepth,
-					parentHindsightSessionState: options.parentHindsightSessionState,
-					parentMnemopiSessionState: options.parentMnemopiSessionState,
-				}),
-			),
-		);
+		logger.time("startMemoryStartupTask", async () => {
+			const memoryBackend = await resolveMemoryBackend(settings);
+			await memoryBackend.start({
+				session,
+				settings,
+				modelRegistry,
+				agentDir,
+				taskDepth,
+				parentHindsightSessionState: options.parentHindsightSessionState,
+				parentMnemopiSessionState: options.parentMnemopiSessionState,
+			});
+		});
 
 		// Wire MCP manager callbacks to session for reactive tool updates.
 		// Skip when reusing a parent's manager — the parent owns the callbacks.
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index eca983671..746ef86e0 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -128,7 +128,6 @@ import {
 } from "../eval/py/executor";
 import { defaultEvalSessionId } from "../eval/session-id";
 import { type BashResult, executeBash as executeBashCommand } from "../exec/bash-executor";
-import { exportSessionToHtml } from "../export/html";
 import type { TtsrManager, TtsrMatchContext } from "../export/ttsr";
 import type { LoadedCustomCommand } from "../extensibility/custom-commands";
 import type { CustomTool, CustomToolContext } from "../extensibility/custom-tools/types";
@@ -2967,14 +2966,14 @@ export class AgentSession {
 	}
 
 	#rekeyHindsightMemoryForCurrentSessionId(): void {
-		if (resolveMemoryBackend(this.settings).id !== "hindsight") return;
+		if (this.settings.get("memory.backend") !== "hindsight") return;
 		const sid = this.agent.sessionId;
 		if (!sid) return;
 		this.getHindsightSessionState()?.setSessionId(sid);
 	}
 
 	#rekeyMnemopiMemoryForCurrentSessionId(): void {
-		if (resolveMemoryBackend(this.settings).id !== "mnemopi") return;
+		if (this.settings.get("memory.backend") !== "mnemopi") return;
 		const sid = this.agent.sessionId;
 		if (!sid) return;
 		this.getMnemopiSessionState()?.setSessionId(sid);
@@ -2982,14 +2981,14 @@ export class AgentSession {
 
 	/** New session file: reset auto-recall / retain-threshold counters for the new transcript. */
 	#resetHindsightConversationTrackingIfHindsight(): void {
-		if (resolveMemoryBackend(this.settings).id !== "hindsight") return;
+		if (this.settings.get("memory.backend") !== "hindsight") return;
 		const state = this.getHindsightSessionState();
 		if (!state || state.aliasOf) return;
 		state.resetConversationTracking();
 	}
 
 	#resetMnemopiConversationTrackingIfMnemopi(): void {
-		if (resolveMemoryBackend(this.settings).id !== "mnemopi") return;
+		if (this.settings.get("memory.backend") !== "mnemopi") return;
 		const state = this.getMnemopiSessionState();
 		if (!state || state.aliasOf) return;
 		state.resetConversationTracking();
@@ -3670,7 +3669,7 @@ export class AgentSession {
 	}
 
 	async #buildSystemPromptForAgentStart(promptText: string): Promise<string[]> {
-		const backend = resolveMemoryBackend(this.settings);
+		const backend = await resolveMemoryBackend(this.settings);
 		if (!backend.beforeAgentStartPrompt) return this.#baseSystemPrompt;
 
 		try {
@@ -6096,7 +6095,7 @@ export class AgentSession {
 		messagesToSummarize: AgentMessage[];
 		turnPrefixMessages: AgentMessage[];
 	}): Promise<string | undefined> {
-		const backend = resolveMemoryBackend(this.settings);
+		const backend = await resolveMemoryBackend(this.settings);
 		if (!backend.preCompactionContext) return undefined;
 		const messages = preparation.messagesToSummarize.concat(preparation.turnPrefixMessages);
 		try {
@@ -9588,6 +9587,7 @@ export class AgentSession {
 	 */
 	async exportToHtml(outputPath?: string): Promise<string> {
 		const themeName = getCurrentThemeName();
+		const { exportSessionToHtml } = await import("../export/html");
 		return exportSessionToHtml(this.sessionManager, this.state, { outputPath, themeName });
 	}
 
diff --git a/packages/coding-agent/src/slash-commands/builtin-registry.ts b/packages/coding-agent/src/slash-commands/builtin-registry.ts
index 394491f8b..bfb059a70 100644
--- a/packages/coding-agent/src/slash-commands/builtin-registry.ts
+++ b/packages/coding-agent/src/slash-commands/builtin-registry.ts
@@ -934,7 +934,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		allowArgs: true,
 		handle: async (command, runtime) => {
 			const verb = (command.args.trim().split(/\s+/)[0] ?? "").toLowerCase() || "view";
-			const backend = resolveMemoryBackend(runtime.settings);
+			const backend = await resolveMemoryBackend(runtime.settings);
 			switch (verb) {
 				case "view": {
 					const payload = await backend.buildDeveloperInstructions(
diff --git a/packages/coding-agent/src/telemetry-export.ts b/packages/coding-agent/src/telemetry-export.ts
index fbb5b3a62..234d43cf3 100644
--- a/packages/coding-agent/src/telemetry-export.ts
+++ b/packages/coding-agent/src/telemetry-export.ts
@@ -23,11 +23,7 @@
  * `sdk-trace-base@2.7` exports cleanly on Bun.
  */
 import { logger, postmortem } from "@oh-my-pi/pi-utils";
-import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import type * as TraceNode from "@opentelemetry/sdk-trace-node";
 
 /**
  * Periodic flush interval. A long-lived `omp` process (the ACP server is
@@ -36,7 +32,8 @@ import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
  */
 const FLUSH_INTERVAL_MS = 30_000;
 
-let provider: NodeTracerProvider | undefined;
+let provider: TraceNode.NodeTracerProvider | undefined;
+let initPromise: Promise<void> | undefined;
 
 /**
  * Whether {@link initTelemetryExport} registered a real provider. The CLI uses
@@ -53,8 +50,10 @@ export function isTelemetryExportEnabled(): boolean {
  * the OTEL kill-switches are engaged), so it is safe to call unconditionally at
  * startup.
  */
-export function initTelemetryExport(): void {
+export async function initTelemetryExport(): Promise<void> {
 	if (provider) return;
+	if (initPromise) return initPromise;
+
 	// The OTEL env contract parses booleans and enum lists case-insensitively, so
 	// OTEL_SDK_DISABLED=TRUE and OTEL_TRACES_EXPORTER=None must also disable export.
 	if (process.env.OTEL_SDK_DISABLED?.trim().toLowerCase() === "true") return;
@@ -77,6 +76,25 @@ export function initTelemetryExport(): void {
 		return;
 	}
 
+	initPromise = registerProvider();
+	return initPromise;
+}
+
+async function registerProvider(): Promise<void> {
+	const [
+		{ AsyncLocalStorageContextManager },
+		{ OTLPTraceExporter },
+		{ resourceFromAttributes },
+		{ BatchSpanProcessor },
+		{ NodeTracerProvider },
+	] = await Promise.all([
+		import("@opentelemetry/context-async-hooks"),
+		import("@opentelemetry/exporter-trace-otlp-proto"),
+		import("@opentelemetry/resources"),
+		import("@opentelemetry/sdk-trace-base"),
+		import("@opentelemetry/sdk-trace-node"),
+	]);
+
 	// The exporter reads endpoint/headers/timeout from OTEL_EXPORTER_OTLP_* itself,
 	// so there is nothing to thread through here.
 	const exporter = new OTLPTraceExporter();
diff --git a/packages/coding-agent/test/memory-backend-resolve.test.ts b/packages/coding-agent/test/memory-backend-resolve.test.ts
index 075f05e8f..46845e103 100644
--- a/packages/coding-agent/test/memory-backend-resolve.test.ts
+++ b/packages/coding-agent/test/memory-backend-resolve.test.ts
@@ -11,10 +11,10 @@ describe("resolveMemoryBackend", () => {
 		resetSettingsForTest();
 	});
 
-	it("returns the hindsight backend when memory.backend is hindsight, regardless of legacy memories.enabled", () => {
+	it("returns the hindsight backend when memory.backend is hindsight, regardless of legacy memories.enabled", async () => {
 		const a = Settings.isolated({ "memory.backend": "hindsight", "memories.enabled": false });
 		const b = Settings.isolated({ "memory.backend": "hindsight", "memories.enabled": true });
-		expect(resolveMemoryBackend(a).id).toBe("hindsight");
-		expect(resolveMemoryBackend(b).id).toBe("hindsight");
+		expect((await resolveMemoryBackend(a)).id).toBe("hindsight");
+		expect((await resolveMemoryBackend(b)).id).toBe("hindsight");
 	});
 });
diff --git a/packages/coding-agent/test/otel-export-probe.ts b/packages/coding-agent/test/otel-export-probe.ts
index 2ada60550..2b285bcf8 100644
--- a/packages/coding-agent/test/otel-export-probe.ts
+++ b/packages/coding-agent/test/otel-export-probe.ts
@@ -35,7 +35,7 @@ const server = Bun.serve({
 process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT = `http://localhost:${server.port}/v1/traces`;
 process.env.OTEL_SERVICE_NAME = "oh-my-pi-export-probe";
 
-initTelemetryExport();
+await initTelemetryExport();
 if (!isTelemetryExportEnabled()) {
 	console.error("PROBE: provider did not register");
 	await server.stop(true);
diff --git a/packages/coding-agent/test/telemetry-export.test.ts b/packages/coding-agent/test/telemetry-export.test.ts
index ecdaf86e8..fa0238b04 100644
--- a/packages/coding-agent/test/telemetry-export.test.ts
+++ b/packages/coding-agent/test/telemetry-export.test.ts
@@ -33,45 +33,45 @@ afterEach(() => {
 });
 
 describe("initTelemetryExport gating", () => {
-	it("stays disabled when no OTLP endpoint is configured", () => {
-		initTelemetryExport();
+	it("stays disabled when no OTLP endpoint is configured", async () => {
+		await initTelemetryExport();
 		expect(isTelemetryExportEnabled()).toBe(false);
 	});
 
-	it("stays disabled when OTEL_SDK_DISABLED=true even with an endpoint", () => {
+	it("stays disabled when OTEL_SDK_DISABLED=true even with an endpoint", async () => {
 		process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318";
 		process.env.OTEL_SDK_DISABLED = "true";
-		initTelemetryExport();
+		await initTelemetryExport();
 		expect(isTelemetryExportEnabled()).toBe(false);
 	});
 
-	it("stays disabled when OTEL_TRACES_EXPORTER=none even with an endpoint", () => {
+	it("stays disabled when OTEL_TRACES_EXPORTER=none even with an endpoint", async () => {
 		process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318";
 		process.env.OTEL_TRACES_EXPORTER = "none";
-		initTelemetryExport();
+		await initTelemetryExport();
 		expect(isTelemetryExportEnabled()).toBe(false);
 	});
 
-	it("declines unsupported OTLP protocols instead of misrouting spans", () => {
+	it("declines unsupported OTLP protocols instead of misrouting spans", async () => {
 		process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4317";
 		process.env.OTEL_EXPORTER_OTLP_PROTOCOL = "grpc";
-		initTelemetryExport();
+		await initTelemetryExport();
 		expect(isTelemetryExportEnabled()).toBe(false);
 
 		process.env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL = "http/json";
-		initTelemetryExport();
+		await initTelemetryExport();
 		expect(isTelemetryExportEnabled()).toBe(false);
 	});
 
-	it("honors the kill-switches case-insensitively per the OTEL env contract", () => {
+	it("honors the kill-switches case-insensitively per the OTEL env contract", async () => {
 		process.env.OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318";
 		process.env.OTEL_SDK_DISABLED = "TRUE";
-		initTelemetryExport();
+		await initTelemetryExport();
 		expect(isTelemetryExportEnabled()).toBe(false);
 
 		delete process.env.OTEL_SDK_DISABLED;
 		process.env.OTEL_TRACES_EXPORTER = "otlp,None";
-		initTelemetryExport();
+		await initTelemetryExport();
 		expect(isTelemetryExportEnabled()).toBe(false);
 	});
 });

From 485cc3fc0a6e717ea80929a805bfe7e0096c42c6 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 23:26:33 +0200
Subject: [PATCH 063/181] fix(coding-agent): fixed streaming tool previews
 dropping scrolled-off output

- ToolExecutionComponent was updated to skip append-only treatment for finalized blocks and pass result state into `isStreamingPreviewAppendOnly`.
- Eval rendering was changed to render full code continuously and to report append-only status only once a result exists, avoiding commitment of stale pending previews.
- Live-region tests were added for expanded eval output overflow and for append-only transitions from pending to finalized streaming states.
---
 packages/coding-agent/CHANGELOG.md            |  2 +-
 .../src/modes/components/tool-execution.ts    | 31 ++++---
 .../coding-agent/src/tools/eval-render.ts     | 39 +++++----
 packages/coding-agent/src/tools/renderers.ts  | 22 +++--
 packages/coding-agent/src/tools/write.ts      |  5 +-
 .../test/tool-live-region-scrollback.test.ts  | 87 +++++++++++++++++++
 6 files changed, 144 insertions(+), 42 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index aee58020f..bb0561565 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -19,7 +19,7 @@
 
 - Fixed eval `agent()` failures surfacing as an opaque `RuntimeError: bridge call '__agent__' failed` with no reason. When a subagent aborted, `runEvalAgent` built its failure message with `result.error ?? result.stderr ?? result.abortReason ?? …`, but `result.stderr` is the empty string on a clean abort (and `result.error` is gated on a non-empty `stderr`), so the nullish chain stopped at `""` and never reached `abortReason`. The empty string propagated through the loopback bridge and the Python prelude's `RuntimeError(msg or "bridge call … failed")`, discarding the real reason. The chain now uses `||` so an empty `stderr` falls through to `abortReason`.
 - Fixed subagent aborts being mislabeled as the generic "Cancelled by caller" when the abort originated inside the subagent's own turn (`stopReason: "aborted"` with no caller signal and no runtime-limit timer). `runSubprocess` now prefers the aborted assistant message's `errorMessage` (e.g. "Request was aborted" or a specific stream error) for that case, while a real caller signal or wall-clock abort still reports its precise reason.
-- Fixed a long streaming tool preview that alone overflows the viewport dropping its scrolled-off head on ED3-risk terminals (ghostty/kitty/iTerm2/…). A streaming `write` preview expanded with `Ctrl+O` renders the whole content top-anchored and grows append-only, but the tool block never reported itself append-only to the transcript, so the renderer's commit-as-you-go boundary stopped at the block start and its earlier rows scrolled above the viewport without being committed to native scrollback — they vanished, leaving the preview looking like a viewport-tall circular buffer. `ToolExecutionComponent` now implements `isTranscriptBlockAppendOnly()`, delegating to a renderer-declared `isStreamingPreviewAppendOnly` predicate (gated to the live call-preview phase) so the expanded write stream commits its head exactly like a streamed assistant reply; collapsed previews (sliding tail window) and result previews (which can collapse) stay deferred.
+- Fixed a long streaming tool preview that alone overflows the viewport dropping its scrolled-off head on ED3-risk terminals (ghostty/kitty/iTerm2/…). When expanded with `Ctrl+O`, a streaming `write` (content streaming in) and a streaming `eval` (stdout streaming below its fixed code cell) render top-anchored and grow append-only, but the tool block never reported itself append-only to the transcript, so the renderer's commit-as-you-go boundary stopped at the block start and the earlier rows that scrolled above the viewport were committed nowhere — they vanished, leaving the preview looking like a viewport-tall circular buffer. `ToolExecutionComponent` now implements `isTranscriptBlockAppendOnly()` (gated on `isTranscriptBlockFinalized()`, so it also covers partial-result streams like `eval`), delegating to a renderer-declared `isStreamingPreviewAppendOnly` predicate so the expanded stream commits its head exactly like a streamed assistant reply. Collapsed previews (bounded sliding tail windows) and finalized/result previews (which can collapse to a capped view) stay deferred.
 
 ## [15.9.69] - 2026-06-06
 ### Fixed
diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index 328969a67..043fbe439 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -531,25 +531,32 @@ export class ToolExecutionComponent extends Container {
 	}
 
 	/**
-	 * While streaming its call preview, a tool block whose preview is append-only
-	 * (rows only grow at the bottom, never re-layout) lets the renderer commit the
-	 * scrolled-off head of an over-tall preview to native scrollback instead of
-	 * dropping it — the same anti-yank path a streaming assistant reply uses (see
-	 * {@link TranscriptContainer} + `NativeScrollbackLiveRegion`). Gated on the
-	 * call-preview phase (no result yet) so the boundary closes the instant the
-	 * preview swaps to a result that may collapse; the renderer decides whether
-	 * its current preview shape qualifies via `isStreamingPreviewAppendOnly`.
+	 * While a tool's preview is still streaming, a block whose preview is
+	 * append-only (rows only grow at the bottom, never re-layout) lets the
+	 * renderer commit the scrolled-off head of an over-tall preview to native
+	 * scrollback instead of dropping it — the same anti-yank path a streaming
+	 * assistant reply uses (see {@link TranscriptContainer} +
+	 * `NativeScrollbackLiveRegion`). Covers both phases: a pre-result call preview
+	 * (a `write` whose content streams in) and a partial-result preview that
+	 * streams output below fixed input (an `eval`/`bash` whose stdout grows under
+	 * its code cell). Gated on {@link isTranscriptBlockFinalized} so the boundary
+	 * closes the instant the block reaches a terminal state — a final result that
+	 * may collapse to a compact view, a backgrounded async tool, or a seal — and
+	 * the renderer decides whether its current preview shape qualifies via
+	 * `isStreamingPreviewAppendOnly` (typically: only the expanded full view,
+	 * which is top-anchored; the collapsed tail window re-layouts but is bounded
+	 * so it never overflows anyway).
 	 */
 	isTranscriptBlockAppendOnly(): boolean {
-		// A result preview can collapse/re-layout; only the live call preview is a
-		// candidate. Sealed/aborted blocks are finalized, not streaming.
-		if (this.#sealed || this.#result !== undefined) return false;
+		// A finalized block's preview can collapse/re-layout; only a live,
+		// still-streaming block is a candidate.
+		if (this.isTranscriptBlockFinalized()) return false;
 		const predicate =
 			(this.#tool as { isStreamingPreviewAppendOnly?: ToolRenderer["isStreamingPreviewAppendOnly"] } | undefined)
 				?.isStreamingPreviewAppendOnly ?? toolRenderers[this.#toolName]?.isStreamingPreviewAppendOnly;
 		if (!predicate) return false;
 		try {
-			return predicate(this.#getCallArgsForRender(), this.#renderState);
+			return predicate(this.#getCallArgsForRender(), this.#renderState, this.#result);
 		} catch (err) {
 			logger.warn("Tool append-only predicate failed", { tool: this.#toolName, error: String(err) });
 			return false;
diff --git a/packages/coding-agent/src/tools/eval-render.ts b/packages/coding-agent/src/tools/eval-render.ts
index e751bf3ff..d9379bba2 100644
--- a/packages/coding-agent/src/tools/eval-render.ts
+++ b/packages/coding-agent/src/tools/eval-render.ts
@@ -40,14 +40,6 @@ import {
 	wrapBrackets,
 } from "./render-utils";
 export const EVAL_DEFAULT_PREVIEW_LINES = 10;
-/**
- * Rows of source kept in the *pending* eval preview. The window follows the
- * streaming edge (newest lines pinned to the bottom) so you can watch the code
- * being written, while staying bounded — a volatile tool block taller than the
- * viewport would otherwise strand its scrolled-off head out of native scrollback
- * on ED3-risk terminals. Matches the streaming windows used by edit/write.
- */
-export const EVAL_STREAMING_PREVIEW_LINES = 12;
 
 function languageForHighlighter(language: EvalLanguage | undefined): "python" | "javascript" {
 	return language === "js" ? "javascript" : "python";
@@ -517,15 +509,12 @@ export const evalToolRenderer = {
 							title: cell.title,
 							status: "pending",
 							width,
-							codeMaxLines: EVAL_STREAMING_PREVIEW_LINES,
-							// Follow the streaming edge with a bounded tail window so the
-							// newest source stays visible as it is written, instead of
-							// rendering every line of a >100-line `code` — which would
-							// overflow the viewport and, because a tool block is volatile
-							// (it collapses to a capped result), strand its scrolled-off head
-							// out of native scrollback, cutting the box top. `Ctrl+O` lifts
-							// the window via `expanded` for a deliberate full view.
-							codeTail: true,
+							// Always render the full source: the code is fixed input, not the
+							// streaming part, so it is never compacted. While still pending
+							// (args streaming) the block is not yet committed to native
+							// scrollback — its head is only committed once a result exists and
+							// the code has finalized (see `isStreamingPreviewAppendOnly`).
+							codeMaxLines: Number.POSITIVE_INFINITY,
 							expanded: options.expanded,
 							animate,
 						},
@@ -628,7 +617,9 @@ export const evalToolRenderer = {
 								duration: cell.durationMs,
 								output: outputLines.length > 0 ? outputLines.join("\n") : undefined,
 								outputMaxLines: outputLines.length,
-								codeMaxLines: expanded ? Number.POSITIVE_INFINITY : EVAL_DEFAULT_PREVIEW_LINES,
+								// Code is fixed input — always shown in full, never compacted.
+								// Only `output` honors the collapsed preview cap above.
+								codeMaxLines: Number.POSITIVE_INFINITY,
 								expanded,
 								width,
 								animate,
@@ -760,6 +751,18 @@ export const evalToolRenderer = {
 			},
 		};
 	},
+
+	// Append-only once a result exists (args complete → code finalized). The code
+	// is rendered in full as a fixed top-anchored prefix, and the streamed stdout
+	// below it only appends rows at the bottom, so the scrolled-off head commits
+	// to native scrollback instead of being yanked — collapsed or expanded, since
+	// the collapsed output cap keeps its sliding tail in the bottom live region.
+	// Returns false while still pending: the code is mid-stream (args incomplete)
+	// and its header still reads "pending", so committing it would strand a stale
+	// pending preview in history.
+	isStreamingPreviewAppendOnly(_args: EvalRenderArgs, _options: RenderResultOptions, result?: unknown): boolean {
+		return result != null;
+	},
 	mergeCallAndResult: true,
 	inline: true,
 };
diff --git a/packages/coding-agent/src/tools/renderers.ts b/packages/coding-agent/src/tools/renderers.ts
index 9f8cbca29..4f74bd090 100644
--- a/packages/coding-agent/src/tools/renderers.ts
+++ b/packages/coding-agent/src/tools/renderers.ts
@@ -41,16 +41,20 @@ export type ToolRenderer = {
 	) => Component;
 	mergeCallAndResult?: boolean;
 	/**
-	 * While the call preview is streaming, report whether the currently-rendered
-	 * preview is append-only: its rows only grow at the bottom and never
-	 * re-layout (a full, top-anchored content preview). The transcript reports
-	 * this up to the TUI so a streaming preview taller than the viewport commits
-	 * its scrolled-off head to native scrollback instead of dropping it (see
-	 * `ToolExecutionComponent.isTranscriptBlockAppendOnly`). Omit (or return
-	 * `false`) for previews that slide a tail window or later collapse to a
-	 * compact result — committing their head would strand stale rows.
+	 * While a tool's preview is still streaming, report whether the
+	 * currently-rendered preview is append-only: its rows only grow at the bottom
+	 * and never re-layout above the bottom live region (a full, top-anchored
+	 * content/code preview). The transcript reports this up to the TUI so a
+	 * streaming preview taller than the viewport commits its scrolled-off head to
+	 * native scrollback instead of dropping it (see
+	 * `ToolExecutionComponent.isTranscriptBlockAppendOnly`). `result` is the
+	 * latest (possibly partial) tool result, or `undefined` before one exists —
+	 * `eval`/`bash` use its presence to defer committing until the streamed input
+	 * (code) has finalized. Omit (or return `false`) for previews that slide a
+	 * tail window or later collapse to a compact result — committing their head
+	 * would strand stale rows.
 	 */
-	isStreamingPreviewAppendOnly?: (args: unknown, options: RenderResultOptions) => boolean;
+	isStreamingPreviewAppendOnly?: (args: unknown, options: RenderResultOptions, result?: unknown) => boolean;
 	/** Render without background box, inline in the response flow */
 	inline?: boolean;
 };
diff --git a/packages/coding-agent/src/tools/write.ts b/packages/coding-agent/src/tools/write.ts
index 35b0683f2..fc3946fc0 100644
--- a/packages/coding-agent/src/tools/write.ts
+++ b/packages/coding-agent/src/tools/write.ts
@@ -1026,8 +1026,9 @@ export const writeToolRenderer = {
 	// The collapsed preview slides a bounded tail window (`formatStreamingContent`
 	// with `WRITE_STREAMING_PREVIEW_LINES`) whose visible rows re-layout as the
 	// window moves — not append-only, but it never overflows the viewport, so its
-	// head is never at risk of being dropped regardless.
-	isStreamingPreviewAppendOnly(args: WriteRenderArgs, options: RenderResultOptions): boolean {
+	// head is never at risk of being dropped regardless. `write` has no partial
+	// result (content streams as args), so `result` is ignored here.
+	isStreamingPreviewAppendOnly(args: WriteRenderArgs, options: RenderResultOptions, _result?: unknown): boolean {
 		return Boolean(options?.expanded && args.content);
 	},
 
diff --git a/packages/coding-agent/test/tool-live-region-scrollback.test.ts b/packages/coding-agent/test/tool-live-region-scrollback.test.ts
index aae7130a7..1c34da43d 100644
--- a/packages/coding-agent/test/tool-live-region-scrollback.test.ts
+++ b/packages/coding-agent/test/tool-live-region-scrollback.test.ts
@@ -221,6 +221,93 @@ describe("tool live-region scrollback", () => {
 			component.stopAnimation();
 		}
 	});
+
+	it("commits the scrolled-off head of an expanded eval whose output streams past the viewport", async () => {
+		if (process.platform === "win32") return;
+
+		await withTerminalRisk(true, async () => {
+			const term = new VirtualTerminal(120, 12);
+			(term as unknown as { isNativeViewportAtBottom: () => boolean | undefined }).isNativeViewportAtBottom = () =>
+				undefined;
+			const tui = new TUI(term);
+			const chat = new TranscriptContainer();
+			const title = "stream lots of output";
+			const code = "for (let i = 0; i < 40; i++) console.log('MARK-' + i);";
+			const args = { cells: [{ language: "js", title, code }] };
+			const component = new ToolExecutionComponent("eval", args, {}, undefined, tui, process.cwd());
+			component.setExpanded(true);
+			const out = (n: number) => Array.from({ length: n }, (_unused, i) => `MARK-${i}`).join("\n");
+			const partial = (output: string) =>
+				component.updateResult(
+					{
+						content: [{ type: "text", text: "" }],
+						details: { cells: [{ index: 0, title, code, language: "js", output, status: "running" }] },
+					},
+					true,
+				);
+
+			try {
+				chat.addChild(component);
+				tui.addChild(chat);
+				tui.start();
+				tui.setEagerNativeScrollbackRebuild(true);
+				await term.waitForRender();
+
+				// A short output that fits, then the full stream that alone overflows the
+				// 12-row viewport — the frame that scrolls the output head above the top.
+				partial(out(4));
+				tui.requestRender();
+				await term.waitForRender();
+
+				partial(out(40));
+				tui.requestRender();
+				await term.waitForRender();
+
+				const strip = (rows: string[]) => rows.map(row => Bun.stripANSI(row).trimEnd()).join("\n");
+				const scrollText = strip(term.getScrollBuffer());
+				const viewportText = strip(term.getViewport());
+
+				// The streamed output head scrolled above the viewport: it must live in
+				// native scrollback (committed), not nowhere. The fixed code cell rides
+				// along as the stable prefix above it.
+				expect(viewportText).not.toContain("MARK-0");
+				expect(scrollText).toContain("MARK-0");
+				expect(scrollText).toContain("MARK-20");
+				// The streaming tail stays on screen, and nothing went missing between.
+				expect(viewportText).toContain("MARK-39");
+			} finally {
+				component.stopAnimation();
+				tui.stop();
+				await term.flush();
+			}
+		});
+	});
+
+	it("keeps a streaming eval append-only only while expanded and unfinalized", () => {
+		const tui = new TUI(new VirtualTerminal(80, 24));
+		const title = "t";
+		const code = "console.log('x')";
+		const args = { cells: [{ language: "js", title, code }] };
+		const component = new ToolExecutionComponent("eval", args, {}, undefined, tui, process.cwd());
+		type AppendOnly = { isTranscriptBlockAppendOnly(): boolean };
+		const probe = component as unknown as AppendOnly;
+		const details = {
+			cells: [{ index: 0, title, code, language: "js", output: "MARK-0\nMARK-1", status: "running" }],
+		};
+		try {
+			// Collapsed: bounded sliding tail windows — not append-only.
+			expect(probe.isTranscriptBlockAppendOnly()).toBe(false);
+			component.setExpanded(true);
+			// Expanded + partial (streaming output): append-only.
+			component.updateResult({ content: [{ type: "text", text: "" }], details }, true);
+			expect(probe.isTranscriptBlockAppendOnly()).toBe(true);
+			// Final result may collapse to a capped view — boundary closes.
+			component.updateResult({ content: [{ type: "text", text: "" }], details }, false);
+			expect(probe.isTranscriptBlockAppendOnly()).toBe(false);
+		} finally {
+			component.stopAnimation();
+		}
+	});
 });
 
 function makeAssistantMessage(text: string): AssistantMessage {

From dcefc9e3d68c71be82e883e5ac502d0e3c9e39e3 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 21:34:33 +0000
Subject: [PATCH 064/181] fix(debug): waited for dlv unix socket

Used fs.stat to confirm delayed dlv Unix socket creation before connecting so Linux socket-mode adapters do not race Bun.connect. Added a delayed socket adapter regression test covering the launch path.\n\nFixes #2013
---
 packages/coding-agent/src/dap/client.ts       | 26 +++++-----
 .../test/debug/dap-launch-failures.test.ts    | 49 +++++++++++++++++++
 2 files changed, 63 insertions(+), 12 deletions(-)

diff --git a/packages/coding-agent/src/dap/client.ts b/packages/coding-agent/src/dap/client.ts
index 79b333a82..54ea4581d 100644
--- a/packages/coding-agent/src/dap/client.ts
+++ b/packages/coding-agent/src/dap/client.ts
@@ -1,4 +1,5 @@
-import { logger, ptree } from "@oh-my-pi/pi-utils";
+import * as fs from "node:fs/promises";
+import { isEnoent, logger, ptree } from "@oh-my-pi/pi-utils";
 import { NON_INTERACTIVE_ENV } from "../exec/non-interactive-env";
 import { ToolAbortError } from "../tools/tool-errors";
 import type {
@@ -165,16 +166,8 @@ export class DapClient {
 			detached: true,
 		});
 
-		// Wait for the socket file to appear (dlv needs to start listening)
 		await waitForCondition(
-			() => {
-				try {
-					Bun.file(socketPath).size;
-					return true;
-				} catch {
-					return false;
-				}
-			},
+			() => isUnixSocketReady(socketPath),
 			10_000,
 			proc,
 		);
@@ -553,15 +546,24 @@ export class DapClient {
 	}
 }
 
+async function isUnixSocketReady(socketPath: string): Promise<boolean> {
+	try {
+		return (await fs.stat(socketPath)).isSocket();
+	} catch (error) {
+		if (isEnoent(error)) return false;
+		throw error;
+	}
+}
+
 /** Poll a condition until it returns true, or timeout/process exit. */
 async function waitForCondition(
-	check: () => boolean,
+	check: () => boolean | Promise<boolean>,
 	timeoutMs: number,
 	proc: { exitCode: number | null },
 ): Promise<void> {
 	const deadline = Date.now() + timeoutMs;
 	while (Date.now() < deadline) {
-		if (check()) return;
+		if (await check()) return;
 		if (proc.exitCode !== null) {
 			throw new Error("Adapter process exited before socket was ready");
 		}
diff --git a/packages/coding-agent/test/debug/dap-launch-failures.test.ts b/packages/coding-agent/test/debug/dap-launch-failures.test.ts
index 83a133e95..004332d59 100644
--- a/packages/coding-agent/test/debug/dap-launch-failures.test.ts
+++ b/packages/coding-agent/test/debug/dap-launch-failures.test.ts
@@ -22,6 +22,32 @@ const TEST_ADAPTER: DapResolvedAdapter = {
 	connectMode: "stdio",
 };
 
+const DELAYED_UNIX_SOCKET_ADAPTER = `
+const listenPrefix = "--listen=unix:";
+const listenArg = process.argv.find(arg => arg.startsWith(listenPrefix));
+if (!listenArg) {
+	throw new Error("missing --listen=unix argument");
+}
+const socketPath = listenArg.slice(listenPrefix.length);
+let server;
+process.on("SIGTERM", () => {
+	server?.stop();
+	process.exit(0);
+});
+await Bun.sleep(100);
+server = Bun.listen({
+	unix: socketPath,
+	socket: {
+		open() {},
+		data() {},
+		close() {},
+		error() {},
+	},
+});
+await Bun.sleep(2_000);
+server.stop();
+`;
+
 type DapEventHandler = (body: unknown, event: DapEventMessage) => void | Promise<void>;
 
 class FakeDapClient {
@@ -286,6 +312,29 @@ describe("DAP launch failure handling", () => {
 		expect(message).toContain("launch: 'C:\\repo\\program' is not a valid executable");
 		expect(message).toContain("configurationDone: Expected process to be stopped.");
 	});
+
+	it("waits for delayed Unix socket adapters before connecting on Linux", async () => {
+		if (process.platform !== "linux") return;
+		const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-dlv-socket-"));
+		const adapterPath = path.join(cwd, "delayed-unix-socket-adapter.mjs");
+		await fs.writeFile(adapterPath, DELAYED_UNIX_SOCKET_ADAPTER);
+		const adapter: DapResolvedAdapter = {
+			...TEST_ADAPTER,
+			name: "dlv",
+			command: process.execPath,
+			args: [adapterPath],
+			resolvedCommand: process.execPath,
+			connectMode: "socket",
+		};
+		let client: DapClient | undefined;
+		try {
+			client = await DapClient.spawn({ adapter, cwd });
+			expect(client.isAlive()).toBe(true);
+		} finally {
+			await client?.dispose();
+			await fs.rm(cwd, { recursive: true, force: true });
+		}
+	});
 });
 
 describe("DebugTool launch validation", () => {

From 9a5f5087df4ea318d3a38d3b61aa17e8b33b0a28 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 21:34:41 +0000
Subject: [PATCH 065/181] style: bun run fix

---
 packages/coding-agent/src/dap/client.ts | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/packages/coding-agent/src/dap/client.ts b/packages/coding-agent/src/dap/client.ts
index 54ea4581d..a93e1df9c 100644
--- a/packages/coding-agent/src/dap/client.ts
+++ b/packages/coding-agent/src/dap/client.ts
@@ -166,11 +166,7 @@ export class DapClient {
 			detached: true,
 		});
 
-		await waitForCondition(
-			() => isUnixSocketReady(socketPath),
-			10_000,
-			proc,
-		);
+		await waitForCondition(() => isUnixSocketReady(socketPath), 10_000, proc);
 
 		const { readable, writeSink, socket } = await connectSocket({ unix: socketPath });
 		const client = new DapClient(adapter, cwd, proc, { readable, writeSink, socket });

From 7ba27b45280ed08c5807f990afc08905f3b26e70 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 23:41:40 +0200
Subject: [PATCH 066/181] fix(coding-agent): prevented long plan previews from
 clipping head

- Added PlanReviewBlock reporting append-only so an over-tall plan plus selector commits the scrolled-off head to native scrollback.
- Avoided top-clipping of long plans on ED3-risk terminals where a plain Container is deferred.
---
 .../coding-agent/src/modes/interactive-mode.ts   | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index 1166097df..8f2bfa1b1 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -250,6 +250,20 @@ export interface InteractiveModeOptions {
 	initialMessages?: string[];
 }
 
+/**
+ * Plan-review preview block. Once rendered it is static (a one-shot Markdown of
+ * the plan file), so even while it sits as the live bottom block beneath the
+ * approval selector its scrolled-off head is safe to commit to native
+ * scrollback. Reporting append-only lets an over-tall plan + selector commit the
+ * plan's head instead of clipping it — without this a plain {@link Container} is
+ * deferred and a long plan is cut off the top on ED3-risk terminals.
+ */
+class PlanReviewBlock extends Container {
+	isTranscriptBlockAppendOnly(): boolean {
+		return true;
+	}
+}
+
 export class InteractiveMode implements InteractiveModeContext {
 	session: AgentSession;
 	sessionManager: SessionManager;
@@ -1680,7 +1694,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	#renderPlanPreview(planContent: string, options?: { append?: boolean }): void {
 		const existingContainer = this.#planReviewContainer;
 		const replaceExisting = options?.append !== true && existingContainer !== undefined;
-		const planReviewContainer = replaceExisting ? existingContainer : new Container();
+		const planReviewContainer = replaceExisting ? existingContainer : new PlanReviewBlock();
 		planReviewContainer.clear();
 		planReviewContainer.addChild(new Spacer(1));
 		planReviewContainer.addChild(new DynamicBorder());

From 22bb6b99272042a966c2e47ef1a68499aa1addb9 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 23:52:33 +0200
Subject: [PATCH 067/181] feat(tui): widened sync-output defaults with runtime
 DECRQM upgrade

- Enabled DEC 2026 for Alacritty/VS Code and via TERM_FEATURES Sy token.
- Stopped blanket-disabling SSH for recognized direct terminals.
- Made the DECRQM probe enable sync on a positive report, not just disable.
- Extracted synchronizedOutputUserOverride so opt-out beats force-on.
---
 docs/tui-core-renderer.md                     |  13 +-
 .../test/streaming-preview-height.test.ts     |  27 +--
 .../test/tool-live-region-scrollback.test.ts  |   2 +-
 packages/tui/CHANGELOG.md                     |   5 +
 packages/tui/src/terminal-capabilities.ts     |  89 +++++++---
 packages/tui/src/tui.ts                       |  25 +--
 packages/tui/test/issue-1765-repro.test.ts    | 160 ++++++++++++++++++
 .../tui/test/terminal-capabilities.test.ts    |  90 +++++++++-
 8 files changed, 349 insertions(+), 62 deletions(-)

diff --git a/docs/tui-core-renderer.md b/docs/tui-core-renderer.md
index 3cc17f8b7..ba9705e8c 100644
--- a/docs/tui-core-renderer.md
+++ b/docs/tui-core-renderer.md
@@ -245,9 +245,16 @@ parameterized over `(env, platform)` so they are unit-testable:
   VTE, iTerm2, Apple Terminal, GNOME Terminal, Ptyxis, xfce4-terminal), Linux
   truecolor, **and every other unknown POSIX terminal**. The default is *risky*
   on purpose.
-- `shouldEnableSynchronizedOutputByDefault(env, platform, id)` → DEC 2026 on by
-  default only for kitty/ghostty/wezterm/iterm2, off for win32 / SSH /
-  multiplexers / VTE-family. Layered with a runtime DECRQM auto-disable.
+- `shouldEnableSynchronizedOutputByDefault(env, id)` → DEC 2026 default. Precedence:
+  user opt-out (`PI_NO_SYNC_OUTPUT`/`PI_TUI_SYNC_OUTPUT=0`) → user force-on
+  (`PI_FORCE_SYNC_OUTPUT=1`/`PI_TUI_SYNC_OUTPUT=1`) → `TERM_FEATURES` advertises
+  `Sy` → `WT_SESSION` (WT/WSL) → known direct terminals
+  (kitty/ghostty/wezterm/iterm2/alacritty/vscode; SSH passes through) → off for
+  risky multiplexers and everything else (VTE-family, GNU screen, Apple Terminal,
+  legacy conhost, unknown). Reconciled at runtime by the DECRQM mode-2026 report:
+  a positive report **enables** sync (upgrading default-off muxes like
+  zellij/tmux-master), a negative one disables it; a user override still wins.
+  `synchronizedOutputUserOverride(env)` is the shared opt-out/force resolver.
 - `detectRectangularSgrSupport(id, env)` → DECCARA fills: **kitty only**
   (ghostty does not implement the SGR-background extension), off in multiplexers
   and under `PI_NO_DECCARA`.
diff --git a/packages/coding-agent/test/streaming-preview-height.test.ts b/packages/coding-agent/test/streaming-preview-height.test.ts
index 5156d8382..b5c2d3f08 100644
--- a/packages/coding-agent/test/streaming-preview-height.test.ts
+++ b/packages/coding-agent/test/streaming-preview-height.test.ts
@@ -338,7 +338,7 @@ describe("streaming tool call preview height (bounded across renderers)", () =>
 		expect(visibleWidth(topBorder ?? "")).toBe(width);
 	});
 
-	test("eval/bash/ssh pending previews stay short even with very long multiline args", () => {
+	test("bash/ssh pending previews stay short even with very long multiline args", () => {
 		const longLines = Array.from({ length: 80 }, (_, i) => `line-${i}`);
 		const cases: Array<{
 			name: string;
@@ -347,17 +347,6 @@ describe("streaming tool call preview height (bounded across renderers)", () =>
 			mustHide: string[];
 			marker: RegExp;
 		}> = [
-			{
-				// eval follows the streaming edge: a bounded tail window so the newest
-				// source stays visible while the box never overflows.
-				name: "eval",
-				args: {
-					cells: [{ language: "js", title: "big", code: longLines.map(line => `const ${line} = 1;`).join("\n") }],
-				},
-				mustContain: ["const line-79 = 1;"],
-				mustHide: ["const line-0 = 1;"],
-				marker: /earlier lines/,
-			},
 			{
 				// bash/ssh keep a bounded head+tail window: the start and the
 				// latest are both visible, the middle is elided.
@@ -403,4 +392,18 @@ describe("streaming tool call preview height (bounded across renderers)", () =>
 		expect(text).toContain("line-79");
 		expect(text).not.toMatch(/more lines/);
 	});
+
+	test("eval pending preview preserves full code (never collapsed)", () => {
+		const longLines = Array.from({ length: 80 }, (_, i) => `line-${i}`);
+		const { lines, text } = renderPending("eval", {
+			cells: [{ language: "js", title: "big", code: longLines.map(line => `const ${line} = 1;`).join("\n") }],
+		});
+
+		expect(lines.length, "eval code preview should not be capped").toBeGreaterThan(80);
+		expect(text).toContain("const line-0 = 1;");
+		expect(text).toContain("const line-40 = 1;");
+		expect(text).toContain("const line-79 = 1;");
+		expect(text).not.toMatch(/more lines/);
+		expect(text).not.toMatch(/earlier lines/);
+	});
 });
diff --git a/packages/coding-agent/test/tool-live-region-scrollback.test.ts b/packages/coding-agent/test/tool-live-region-scrollback.test.ts
index 1c34da43d..80fa86305 100644
--- a/packages/coding-agent/test/tool-live-region-scrollback.test.ts
+++ b/packages/coding-agent/test/tool-live-region-scrollback.test.ts
@@ -73,7 +73,7 @@ describe("tool live-region scrollback", () => {
 					.join("\n");
 				expect(bufferText).not.toContain("pending [1/1]");
 				expect(bufferText).toContain("const line9 = 9;");
-				expect(bufferText).toContain("… 10 more lines");
+				expect(bufferText).toContain("const line19 = 19;");
 			} finally {
 				component.stopAnimation();
 				tui.stop();
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 81cfd3272..1cecbf5d5 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,9 +2,14 @@
 
 ## [Unreleased]
 
+### Changed
+
+- Reworked the DEC 2026 synchronized-output default policy: a positive DECRQM mode-2026 report now **enables** sync (previously a report could only disable it), so conservatively defaulted-off hosts that actually support it — current Zellij, tmux master, foot, contour, mintty — are upgraded at runtime. The static allowlist also covers Alacritty and the VS Code terminal, honors a `TERM_FEATURES` `Sy` advertisement and `WT_SESSION` (Windows Terminal / WSL), and no longer blanket-disables SSH (DEC 2026 passes through to the outer terminal). Risky multiplexers still start off and rely on the probe. Added `synchronizedOutputUserOverride()` as the shared opt-out/force resolver.
+
 ### Fixed
 
 - Fixed WSL/Windows Terminal row flicker while typing by repainting changed text rows before clearing only their stale suffix ([#2011](https://github.com/can1357/oh-my-pi/issues/2011)).
+- Fixed terminals that support DEC 2026 still tearing/flickering because the renderer ignored a positive DECRQM capability report and kept synchronized output off — most visibly WSL + Windows Terminal, Alacritty (≥0.13), and the VS Code terminal (≥1.108), which were detected yet refused sync.
 
 ## [15.9.69] - 2026-06-06
 
diff --git a/packages/tui/src/terminal-capabilities.ts b/packages/tui/src/terminal-capabilities.ts
index bea4ed1f8..9324386a3 100644
--- a/packages/tui/src/terminal-capabilities.ts
+++ b/packages/tui/src/terminal-capabilities.ts
@@ -187,41 +187,76 @@ export function detectTerminalEagerEraseScrollbackRisk(
 	return true;
 }
 
-/** Whether DEC 2026 synchronized-output wrappers should be enabled by default. */
-export function shouldEnableSynchronizedOutputByDefault(
-	env: NodeJS.ProcessEnv = Bun.env,
-	platform: NodeJS.Platform = process.platform,
-	terminalId: TerminalId = TERMINAL_ID,
-): boolean {
+/**
+ * Resolve an explicit user override for DEC 2026 synchronized output. Returns
+ * `false` for an opt-out, `true` for a force-on, or `null` when the user has
+ * expressed no preference. Shared by the static default and the runtime DECRQM
+ * probe so both honor the same precedence — an opt-out beats a force-on.
+ */
+export function synchronizedOutputUserOverride(env: NodeJS.ProcessEnv = Bun.env): boolean | null {
 	if (env.PI_NO_SYNC_OUTPUT || env.PI_TUI_SYNC_OUTPUT === "0") return false;
 	if (env.PI_FORCE_SYNC_OUTPUT === "1" || env.PI_TUI_SYNC_OUTPUT === "1") return true;
-	if (platform === "win32") return false;
+	return null;
+}
 
+/**
+ * Whether `TERM_FEATURES` advertises DEC 2026 synchronized output via the `Sy`
+ * capability token. `TERM_FEATURES` is a run of capitalized two-letter codes
+ * (e.g. `…Sy…`), so a case-sensitive substring match is unambiguous: `Sy`
+ * cannot straddle a code boundary because those are always lowercase→uppercase.
+ */
+function advertisesSynchronizedOutput(termFeatures: string | undefined): boolean {
+	return termFeatures?.includes("Sy") ?? false;
+}
+
+/**
+ * Whether DEC 2026 synchronized-output wrappers should be enabled by default.
+ *
+ * Policy (highest precedence first):
+ *   1. Explicit user override (`PI_NO_SYNC_OUTPUT`/`PI_TUI_SYNC_OUTPUT=0` off,
+ *      `PI_FORCE_SYNC_OUTPUT=1`/`PI_TUI_SYNC_OUTPUT=1` on).
+ *   2. Positive `TERM_FEATURES` advertisement (`Sy`) — survives SSH/mux wrapping.
+ *   3. Windows Terminal (1.24+) via `WT_SESSION`, on native win32 and the
+ *      WSL/SSH-fronted host alike.
+ *   4. Known direct terminals with confirmed support. SSH does *not* disable —
+ *      DEC 2026 passes through SSH when the outer terminal honors it.
+ *   5. Everything else starts off, including risky multiplexers; the runtime
+ *      DECRQM probe upgrades any of them when the terminal actually reports
+ *      `?2026` supported (current zellij, tmux master, foot, contour, mintty…).
+ */
+export function shouldEnableSynchronizedOutputByDefault(
+	env: NodeJS.ProcessEnv = Bun.env,
+	terminalId: TerminalId = TERMINAL_ID,
+): boolean {
+	const override = synchronizedOutputUserOverride(env);
+	if (override !== null) return override;
+
+	if (advertisesSynchronizedOutput(env.TERM_FEATURES)) return true;
+	if (env.WT_SESSION) return true;
+
+	// Risky multiplexers start off even when an inner terminal id leaks through:
+	// older tmux/screen synchronized-output handling is flaky and a mux may not
+	// pass DEC 2026 to the outer host. The DECRQM probe re-enables sync when the
+	// mux reports `?2026` supported.
 	const term = env.TERM?.toLowerCase() ?? "";
-	const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
-	if (
-		env.SSH_CONNECTION ||
-		env.SSH_CLIENT ||
-		env.SSH_TTY ||
-		env.TMUX ||
-		env.STY ||
-		env.ZELLIJ ||
-		term.startsWith("tmux") ||
-		term.startsWith("screen")
-	) {
+	if (env.TMUX || env.STY || env.ZELLIJ || term.startsWith("tmux") || term.startsWith("screen")) {
 		return false;
 	}
-	if (env.VTE_VERSION) return false;
-	switch (termProgram) {
-		case "gnome-terminal":
-		case "kgx":
-		case "ptyxis":
-		case "xfce4-terminal":
-			return false;
+
+	switch (terminalId) {
+		case "kitty":
+		case "ghostty":
+		case "wezterm":
+		case "iterm2":
+		case "alacritty":
+		case "vscode":
+			return true;
 		default:
-			break;
+			// VTE family, GNU screen, Apple Terminal, legacy native console host
+			// (no WT_SESSION), and bare/unknown xterm profiles stay off until the
+			// DECRQM probe proves support.
+			return false;
 	}
-	return terminalId === "kitty" || terminalId === "ghostty" || terminalId === "wezterm" || terminalId === "iterm2";
 }
 
 /**
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 3a0471d83..62db855a2 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -24,6 +24,7 @@ import {
 	setCellDimensions,
 	setTerminalImageProtocol,
 	shouldEnableSynchronizedOutputByDefault,
+	synchronizedOutputUserOverride,
 	TERMINAL,
 } from "./terminal-capabilities";
 import {
@@ -573,8 +574,9 @@ export class TUI extends Container {
 
 	/**
 	 * Whether DEC 2026 synchronized-output wrappers are currently emitted around
-	 * paints. Starts from conservative terminal/env detection and is force-disabled
-	 * at runtime if the terminal reports mode 2026 unsupported via DECRQM.
+	 * paints. Starts from conservative terminal/env detection and is reconciled at
+	 * runtime against the terminal's DECRQM mode-2026 report — enabled on a
+	 * positive report, disabled on a negative one.
 	 */
 	get synchronizedOutput(): boolean {
 		return this.#synchronizedOutputEnabled;
@@ -744,14 +746,15 @@ export class TUI extends Container {
 
 	start(): void {
 		this.#stopped = false;
-		// Disable synchronized output if the terminal reports DEC 2026 unsupported
-		// via DECRQM. PI_NO_SYNC_OUTPUT already forces it off at construction, so
-		// only react when the user has not already opted out. Future paints drop
-		// the begin/end markers; the autowrap guards stay (see #1765).
+		// A DECRQM report for mode 2026 is authoritative: enable synchronized
+		// output when the terminal reports support (upgrading conservatively
+		// defaulted-off hosts like zellij/tmux-master/foot) and disable it when
+		// the terminal reports it unsupported. An explicit user opt-out/force
+		// (resolved at construction) still wins, so skip the probe in that case.
 		this.terminal.onPrivateModeReport?.((mode, supported) => {
-			if (mode === 2026 && !supported && !$flag("PI_NO_SYNC_OUTPUT")) {
-				this.#setSynchronizedOutput(false);
-			}
+			if (mode !== 2026) return;
+			if (synchronizedOutputUserOverride() !== null) return;
+			this.#setSynchronizedOutput(supported);
 		});
 		this.terminal.start(
 			data => this.#handleInput(data),
@@ -914,8 +917,8 @@ export class TUI extends Container {
 
 	/**
 	 * Toggle synchronized-output (DEC 2026) wrappers on paint/cursor writes and
-	 * recompute the cached begin/end sequences. Honors a DECRQM report that the
-	 * terminal does not support 2026 (#1765 covers the static env opt-out).
+	 * recompute the cached begin/end sequences. Driven by the terminal's DECRQM
+	 * mode-2026 report (#1765 covers the static env opt-out).
 	 */
 	#setSynchronizedOutput(enabled: boolean): void {
 		if (this.#synchronizedOutputEnabled === enabled) return;
diff --git a/packages/tui/test/issue-1765-repro.test.ts b/packages/tui/test/issue-1765-repro.test.ts
index af64666d3..df73fda8c 100644
--- a/packages/tui/test/issue-1765-repro.test.ts
+++ b/packages/tui/test/issue-1765-repro.test.ts
@@ -33,6 +33,21 @@ class FocusedLine implements Component, Focusable {
 	}
 }
 
+// VirtualTerminal does not model DECRQM capability probing, so subclass it to
+// register and replay the renderer's mode-2026 report callback on demand. This
+// exercises the runtime probe path in `TUI.start()` end-to-end.
+class ProbingTerminal extends VirtualTerminal {
+	#privateModeCallbacks: Array<(mode: number, supported: boolean) => void> = [];
+
+	onPrivateModeReport(callback: (mode: number, supported: boolean) => void): void {
+		this.#privateModeCallbacks.push(callback);
+	}
+
+	emitPrivateModeReport(mode: number, supported: boolean): void {
+		for (const callback of this.#privateModeCallbacks) callback(mode, supported);
+	}
+}
+
 const SYNC_BEGIN = "\x1b[?2026h";
 const SYNC_END = "\x1b[?2026l";
 const DISABLE_AUTOWRAP = "\x1b[?7l";
@@ -188,3 +203,148 @@ describe("issue #1765: synchronized-output opt-out", () => {
 		});
 	});
 });
+
+describe("synchronized-output runtime DECRQM probe", () => {
+	it("enables synchronized output after a positive DEC 2026 report on a default-off host", async () => {
+		// TMUX forces the static default off; the positive probe must upgrade it.
+		await withEnvPatch(
+			{
+				TMUX: "1",
+				WT_SESSION: undefined,
+				TERM_FEATURES: undefined,
+				PI_NO_SYNC_OUTPUT: undefined,
+				PI_FORCE_SYNC_OUTPUT: undefined,
+				PI_TUI_SYNC_OUTPUT: undefined,
+			},
+			async () => {
+				const term = new ProbingTerminal(32, 4, 100);
+				const writes = captureWrites(term);
+				const component = new MutableLines(["before probe"]);
+				const tui = new TUI(term);
+				tui.addChild(component);
+
+				try {
+					tui.start();
+					await term.waitForRender();
+					expect(tui.synchronizedOutput).toBe(false);
+					expectNoSyncOutput(writes);
+
+					const mark = writes.length;
+					term.emitPrivateModeReport(2026, true);
+					expect(tui.synchronizedOutput).toBe(true);
+
+					component.lines = ["after probe"];
+					tui.requestRender();
+					await term.waitForRender();
+
+					const after = writes.slice(mark).join("");
+					expect(after).toContain(SYNC_BEGIN);
+					expect(after).toContain(SYNC_END);
+				} finally {
+					tui.stop();
+				}
+			},
+		);
+	});
+
+	it("disables synchronized output after a negative DEC 2026 report on a default-on host", async () => {
+		// WT_SESSION forces the static default on without a user override flag.
+		await withEnvPatch(
+			{
+				WT_SESSION: "abc",
+				PI_NO_SYNC_OUTPUT: undefined,
+				PI_FORCE_SYNC_OUTPUT: undefined,
+				PI_TUI_SYNC_OUTPUT: undefined,
+			},
+			async () => {
+				const term = new ProbingTerminal(32, 4, 100);
+				const writes = captureWrites(term);
+				const component = new MutableLines(["before probe"]);
+				const tui = new TUI(term);
+				tui.addChild(component);
+
+				try {
+					tui.start();
+					await term.waitForRender();
+					expect(tui.synchronizedOutput).toBe(true);
+
+					const mark = writes.length;
+					term.emitPrivateModeReport(2026, false);
+					expect(tui.synchronizedOutput).toBe(false);
+
+					component.lines = ["after probe"];
+					tui.requestRender();
+					await term.waitForRender();
+
+					expectNoSyncOutput(writes.slice(mark));
+				} finally {
+					tui.stop();
+				}
+			},
+		);
+	});
+
+	it("ignores a positive probe when the user opted out", async () => {
+		await withEnvPatch(
+			{ PI_NO_SYNC_OUTPUT: "1", PI_FORCE_SYNC_OUTPUT: undefined, PI_TUI_SYNC_OUTPUT: undefined },
+			async () => {
+				const term = new ProbingTerminal(32, 4, 100);
+				const writes = captureWrites(term);
+				const component = new MutableLines(["before probe"]);
+				const tui = new TUI(term);
+				tui.addChild(component);
+
+				try {
+					tui.start();
+					await term.waitForRender();
+					expect(tui.synchronizedOutput).toBe(false);
+
+					const mark = writes.length;
+					term.emitPrivateModeReport(2026, true);
+					expect(tui.synchronizedOutput).toBe(false);
+
+					component.lines = ["after probe"];
+					tui.requestRender();
+					await term.waitForRender();
+
+					expectNoSyncOutput(writes.slice(mark));
+				} finally {
+					tui.stop();
+				}
+			},
+		);
+	});
+
+	it("ignores a negative probe when the user forced sync on", async () => {
+		await withEnvPatch(
+			{ PI_FORCE_SYNC_OUTPUT: "1", PI_NO_SYNC_OUTPUT: undefined, PI_TUI_SYNC_OUTPUT: undefined },
+			async () => {
+				const term = new ProbingTerminal(32, 4, 100);
+				const writes = captureWrites(term);
+				const component = new MutableLines(["before probe"]);
+				const tui = new TUI(term);
+				tui.addChild(component);
+
+				try {
+					tui.start();
+					await term.waitForRender();
+					expect(tui.synchronizedOutput).toBe(true);
+
+					const mark = writes.length;
+					term.emitPrivateModeReport(2026, false);
+					expect(tui.synchronizedOutput).toBe(true);
+
+					component.lines = ["after probe"];
+					tui.requestRender();
+					await term.waitForRender();
+
+					const after = writes.slice(mark).join("");
+					expect(after).toContain(SYNC_BEGIN);
+					expect(after).toContain(SYNC_END);
+				} finally {
+					tui.stop();
+				}
+			},
+		);
+	});
+});
diff --git a/packages/tui/test/terminal-capabilities.test.ts b/packages/tui/test/terminal-capabilities.test.ts
index 384b0a2cc..3d4d835f7 100644
--- a/packages/tui/test/terminal-capabilities.test.ts
+++ b/packages/tui/test/terminal-capabilities.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test";
 import {
 	detectTerminalEagerEraseScrollbackRisk,
 	shouldEnableSynchronizedOutputByDefault,
+	synchronizedOutputUserOverride,
 } from "@oh-my-pi/pi-tui/terminal-capabilities";
 
 describe("terminal capability defaults", () => {
@@ -22,20 +23,93 @@ describe("terminal capability defaults", () => {
 	it("keeps native win32 on the dedicated ConPTY deferral path", () => {
 		expect(detectTerminalEagerEraseScrollbackRisk({ WT_SESSION: "abc" }, "win32")).toBe(false);
 	});
+});
 
-	it("disables synchronized output by default for remote, VTE, and unknown profiles", () => {
-		expect(shouldEnableSynchronizedOutputByDefault({ SSH_CONNECTION: "1 2 3 4" }, "linux", "base")).toBe(false);
-		expect(shouldEnableSynchronizedOutputByDefault({ VTE_VERSION: "6800" }, "linux", "base")).toBe(false);
-		expect(shouldEnableSynchronizedOutputByDefault({ TERM: "xterm-256color" }, "linux", "base")).toBe(false);
+describe("synchronizedOutputUserOverride", () => {
+	it("returns null when the user expresses no preference", () => {
+		expect(synchronizedOutputUserOverride({})).toBeNull();
+		expect(synchronizedOutputUserOverride({ TERM: "xterm-256color" })).toBeNull();
 	});
 
-	it("allows explicit synchronized-output force-on for diagnostics", () => {
+	it("returns false for either opt-out flag", () => {
+		expect(synchronizedOutputUserOverride({ PI_NO_SYNC_OUTPUT: "1" })).toBe(false);
+		expect(synchronizedOutputUserOverride({ PI_TUI_SYNC_OUTPUT: "0" })).toBe(false);
+	});
+
+	it("returns true for either force-on flag", () => {
+		expect(synchronizedOutputUserOverride({ PI_FORCE_SYNC_OUTPUT: "1" })).toBe(true);
+		expect(synchronizedOutputUserOverride({ PI_TUI_SYNC_OUTPUT: "1" })).toBe(true);
+	});
+
+	it("resolves opt-out ahead of force-on when both are set", () => {
+		expect(synchronizedOutputUserOverride({ PI_NO_SYNC_OUTPUT: "1", PI_FORCE_SYNC_OUTPUT: "1" })).toBe(false);
+		expect(synchronizedOutputUserOverride({ PI_TUI_SYNC_OUTPUT: "0", PI_FORCE_SYNC_OUTPUT: "1" })).toBe(false);
+	});
+});
+
+describe("shouldEnableSynchronizedOutputByDefault", () => {
+	it("enables sync for every known direct terminal, including Alacritty and VS Code", () => {
+		for (const id of ["kitty", "ghostty", "wezterm", "iterm2", "alacritty", "vscode"] as const) {
+			expect(shouldEnableSynchronizedOutputByDefault({}, id)).toBe(true);
+		}
+	});
+
+	it("enables sync in Windows Terminal / WSL via WT_SESSION regardless of terminal id", () => {
+		expect(shouldEnableSynchronizedOutputByDefault({ WT_SESSION: "abc" }, "trueColor")).toBe(true);
+		// WSL shape: Linux + WT_SESSION + COLORTERM=truecolor collapses to trueColor id.
+		expect(shouldEnableSynchronizedOutputByDefault({ WT_SESSION: "abc", COLORTERM: "truecolor" }, "trueColor")).toBe(
+			true,
+		);
+	});
+
+	it("enables sync when TERM_FEATURES advertises the Sy capability, even through SSH/mux", () => {
+		expect(shouldEnableSynchronizedOutputByDefault({ TERM_FEATURES: "ClSyTc" }, "base")).toBe(true);
+		expect(
+			shouldEnableSynchronizedOutputByDefault({ TERM_FEATURES: "ClSyTc", SSH_CONNECTION: "1 2 3 4" }, "base"),
+		).toBe(true);
+		expect(shouldEnableSynchronizedOutputByDefault({ TERM_FEATURES: "ClSyTc", TMUX: "1" }, "base")).toBe(true);
+	});
+
+	it("does not treat a TERM_FEATURES list without the Sy token as advertising support", () => {
+		expect(shouldEnableSynchronizedOutputByDefault({ TERM_FEATURES: "ClTc" }, "base")).toBe(false);
+	});
+
+	it("no longer blanket-disables SSH for recognized terminals", () => {
+		expect(shouldEnableSynchronizedOutputByDefault({ SSH_CONNECTION: "1 2 3 4" }, "iterm2")).toBe(true);
+		expect(shouldEnableSynchronizedOutputByDefault({ SSH_TTY: "/dev/pts/3" }, "kitty")).toBe(true);
+	});
+
+	it("keeps risky multiplexers off by default even when an inner terminal id leaks", () => {
+		expect(shouldEnableSynchronizedOutputByDefault({ TMUX: "1" }, "kitty")).toBe(false);
+		expect(shouldEnableSynchronizedOutputByDefault({ ZELLIJ: "0" }, "ghostty")).toBe(false);
+		expect(shouldEnableSynchronizedOutputByDefault({ STY: "x" }, "wezterm")).toBe(false);
+		expect(shouldEnableSynchronizedOutputByDefault({ TERM: "tmux-256color" }, "iterm2")).toBe(false);
+		expect(shouldEnableSynchronizedOutputByDefault({ TERM: "screen-256color" }, "kitty")).toBe(false);
+	});
+
+	it("keeps known-unsupported and unknown profiles off", () => {
+		expect(shouldEnableSynchronizedOutputByDefault({ VTE_VERSION: "6800" }, "base")).toBe(false);
+		expect(shouldEnableSynchronizedOutputByDefault({ TERM: "xterm-256color" }, "base")).toBe(false);
+		expect(shouldEnableSynchronizedOutputByDefault({}, "base")).toBe(false);
+		expect(shouldEnableSynchronizedOutputByDefault({}, "trueColor")).toBe(false);
+	});
+
+	it("lets a user opt-out beat every positive heuristic", () => {
+		expect(shouldEnableSynchronizedOutputByDefault({ PI_NO_SYNC_OUTPUT: "1" }, "kitty")).toBe(false);
+		expect(shouldEnableSynchronizedOutputByDefault({ PI_TUI_SYNC_OUTPUT: "0" }, "ghostty")).toBe(false);
 		expect(
 			shouldEnableSynchronizedOutputByDefault(
-				{ PI_FORCE_SYNC_OUTPUT: "1", SSH_CONNECTION: "1 2 3 4" },
-				"linux",
-				"base",
+				{ PI_NO_SYNC_OUTPUT: "1", WT_SESSION: "abc", TERM_FEATURES: "Sy" },
+				"kitty",
 			),
+		).toBe(false);
+	});
+
+	it("lets a user force-on beat the conservative defaults", () => {
+		expect(shouldEnableSynchronizedOutputByDefault({ PI_FORCE_SYNC_OUTPUT: "1" }, "base")).toBe(true);
+		expect(shouldEnableSynchronizedOutputByDefault({ PI_TUI_SYNC_OUTPUT: "1", TMUX: "1" }, "base")).toBe(true);
+		expect(
+			shouldEnableSynchronizedOutputByDefault({ PI_FORCE_SYNC_OUTPUT: "1", SSH_CONNECTION: "1 2 3 4" }, "base"),
 		).toBe(true);
 	});
 });

From 54776365cda74ae59968019f91bcf600dd63292c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sat, 6 Jun 2026 23:58:02 +0200
Subject: [PATCH 068/181] feat(coding-agent/tools): added configurable fetch
 backend preference and fallback order

- Replaced `providers.parallelFetch` with a new `providers.fetch` enum in settings and added migration cleanup for the legacy key.
- Updated `renderHtmlToText` to follow configured reader preference with ordered fallback attempts and remote-reader timeout handling before local conversion.
- Updated YouTube and fetch tests to use `providers.fetch` and cover Jina-first stall fallback behavior.
---
 packages/ai/CHANGELOG.md                      |   2 -
 packages/coding-agent/CHANGELOG.md            |  20 +-
 packages/coding-agent/DEVELOPMENT.md          |   2 +-
 .../src/config/settings-schema.ts             |  23 ++-
 packages/coding-agent/src/config/settings.ts  |  11 ++
 packages/coding-agent/src/tools/fetch.ts      | 176 +++++++++---------
 .../coding-agent/src/web/scrapers/youtube.ts  |   5 +-
 .../test/tools/fetch-jina-stall.test.ts       |   6 +-
 .../test/tools/fetch-kagi-toggle.test.ts      |   7 +-
 .../web-scrapers/youtube-parallel.test.ts     |   2 +-
 10 files changed, 147 insertions(+), 107 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index db832fa7b..35e9b0b6b 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -14,8 +14,6 @@
 
 - Fixed Cloud Code Assist (Antigravity / Gemini CLI) rejecting the `github` tool with HTTP 400 when the `pr` parameter schema contained `anyOf: [string, array]`. The CCA mixed-type combiner collapse picked the first non-null type (`string`) but indiscriminately copied type-specific keys from variant branches — `items` from the array variant leaked onto the string-typed result, producing `{type: "string", items: {...}}` which Google's API rejects as invalid. The collapse now filters merged variant fields against the winning type's allowed key set. ([#2002](https://github.com/can1357/oh-my-pi/pull/2002))
 - Fixed OpenAI Responses-family providers (Codex, OpenAI Responses, Azure Responses) rejecting requests with `400 No tool output found for function call …` after the user branched/navigated the session tree to a node that ends on a tool call (the tool-result child is dropped from the reconstructed history) or after a turn was aborted/crashed between the call streaming and its result persisting. The converters now synthesize a placeholder `function_call_output`/`custom_tool_call_output` immediately after any unpaired `function_call`/`custom_tool_call`, symmetric to the existing orphan-output repair, so the model still sees the call and can recover instead of the whole request 400ing.
-### Fixed
-
 - Fixed Anthropic-compatible reasoning endpoints losing prior-turn reasoning on continuation requests when they emit unsigned `thinking` blocks. `convertAnthropicMessages` treated unknown endpoints as signature-enforcing and demoted unsigned reasoning to `type: "text"`, which destabilized tool-call argument serialization on the next turn — the upstream symptom behind the `args?.ops?.map is not a function` crash reported against the `todo` tool. Official `api.anthropic.com` keeps the conservative text fallback; non-official `anthropic-messages` reasoning models now replay unsigned reasoning as native `type: "thinking"` ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
 
 ## [15.9.67] - 2026-06-06
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index bb0561565..0297e1bbe 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Breaking Changes
+
+- Replaced the `providers.parallelFetch` boolean setting with the `providers.fetch` enum (`auto` / `native` / `trafilatura` / `lynx` / `parallel` / `jina`) that selects the URL reader-backend priority for the `read`/`fetch` tool, mirroring `providers.image`/`providers.webSearch`. Existing configs are migrated automatically: the legacy key is dropped and the new `auto` default applies.
+
 ### Added
 
 - Added a GitHub Actions read handler to the `read`/web-fetch GitHub scraper. Fetching `github.com/{owner}/{repo}/actions/runs/{id}` renders the run metadata plus a per-job breakdown (steps listed for any job that did not succeed), and `…/actions/runs/{id}/job/{id}` (also the API-style `…/jobs/{id}`) renders a single job's metadata, step table, and full plain-text logs. Logs are fetched via the `actions/jobs/{id}/logs` redirect using `GITHUB_TOKEN`/`GH_TOKEN` when present, with the per-line ISO timestamp prefix and leading BOM stripped; the section degrades to an explicit notice when logs are unavailable (no token, private repo, or expired/unfinalized run).
@@ -13,19 +17,20 @@
 - Changed coding-agent startup imports so normal TUI launch imports `InteractiveMode` directly, keeps print/RPC/ACP runners on their branch-only paths, and moves marketplace auto-update work behind a lightweight deferred starter.
 - Changed cold-launch setup gating so the full setup wizard (every scene plus the overlay and their TUI/OAuth/web-search/theme dependencies) is no longer statically imported by `main.ts`. The current setup version now lives in a tiny dependency-free `modes/setup-version` module, and the wizard barrel is lazy-loaded only when the stored setup version is stale or the wizard is forced — the common up-to-date launch skips loading it entirely.
 - Changed cold-launch startup imports so the hot-path CLI files no longer pull the full `@oh-my-pi/pi-ai` barrel: `commands/launch.ts` and `cli/args.ts` import `THINKING_EFFORTS`/`Effort` from the tiny `@oh-my-pi/pi-ai/effort` module, and `config/model-registry.ts` now imports its ~20 symbols from narrow subpaths (`api-registry`, `model-cache`, `model-manager`, `model-thinking`, `models`, `provider-models`, `types`, `utils/event-stream`) instead of the barrel — so launching no longer eagerly loads every provider, auth, OAuth, and usage module re-exported by the barrel.
-
+- Changed the `read`/`fetch` HTML reader-backend priority to `native > trafilatura > lynx > parallel > jina` (was `parallel > jina > trafilatura > lynx > native`). The in-process native `htmlToMarkdown` runs first — instant, no network, full-fidelity — so the common case no longer depends on a remote service, and a stalled remote backend can no longer mask it. Selecting a specific backend via `providers.fetch` tries it first, then the rest fall back. The low-quality gate (`>100` chars and not `isLowQualityOutput`) now applies uniformly to every backend; when none clears it, the highest-priority substantial-but-low-quality output is still surfaced so the `llms.txt` / document-extraction fallbacks keep running.
 
 ### Fixed
 
 - Fixed eval `agent()` failures surfacing as an opaque `RuntimeError: bridge call '__agent__' failed` with no reason. When a subagent aborted, `runEvalAgent` built its failure message with `result.error ?? result.stderr ?? result.abortReason ?? …`, but `result.stderr` is the empty string on a clean abort (and `result.error` is gated on a non-empty `stderr`), so the nullish chain stopped at `""` and never reached `abortReason`. The empty string propagated through the loopback bridge and the Python prelude's `RuntimeError(msg or "bridge call … failed")`, discarding the real reason. The chain now uses `||` so an empty `stderr` falls through to `abortReason`.
 - Fixed subagent aborts being mislabeled as the generic "Cancelled by caller" when the abort originated inside the subagent's own turn (`stopReason: "aborted"` with no caller signal and no runtime-limit timer). `runSubprocess` now prefers the aborted assistant message's `errorMessage` (e.g. "Request was aborted" or a specific stream error) for that case, while a real caller signal or wall-clock abort still reports its precise reason.
 - Fixed a long streaming tool preview that alone overflows the viewport dropping its scrolled-off head on ED3-risk terminals (ghostty/kitty/iTerm2/…). When expanded with `Ctrl+O`, a streaming `write` (content streaming in) and a streaming `eval` (stdout streaming below its fixed code cell) render top-anchored and grow append-only, but the tool block never reported itself append-only to the transcript, so the renderer's commit-as-you-go boundary stopped at the block start and the earlier rows that scrolled above the viewport were committed nowhere — they vanished, leaving the preview looking like a viewport-tall circular buffer. `ToolExecutionComponent` now implements `isTranscriptBlockAppendOnly()` (gated on `isTranscriptBlockFinalized()`, so it also covers partial-result streams like `eval`), delegating to a renderer-declared `isStreamingPreviewAppendOnly` predicate so the expanded stream commits its head exactly like a streamed assistant reply. Collapsed previews (bounded sliding tail windows) and finalized/result previews (which can collapse to a capped view) stay deferred.
-
-## [15.9.69] - 2026-06-06
-### Fixed
-
+- Fixed `read`/`fetch` silently dropping whole list sections on pages with malformed list markup — stray `<img>`, text, or `<video>` nodes as direct children of `<ul>` (e.g. the Alacritty changelog). The Jina reader (previously tried before the local renderers) mis-extracts such lists, returning empty `Added`/`Changed` sections; the native in-process renderer now runs first and preserves the full content.
 - Fixed `/usage` aggregate amount fallback using raw `limits.length` as account count — now counts unique `accountId` values from limit scopes, so N limits from a single account no longer display as "N accts".
 - Fixed `/usage` account labeling falling back to "account N" for providers that use `projectId` as their primary identity (e.g. Google Antigravity, Gemini CLI) — `projectId` from report metadata is now considered before the generic fallback.
+- Fixed the `todo` tool's TUI renderer crashing with `TypeError: args?.ops?.map is not a function` when a streaming tool-call delta surfaced a non-array `ops` field (mid-stream `parseStreamingJson` shapes like `{ ops: "[{" }`, or `[null]` entries before fields arrive). The renderer now treats non-array `ops`, non-object entries, and non-array `items` as missing structure instead of crashing, which also stops the spam-warn cascade that followed each malformed delta. Paired with the Anthropic-side reasoning-replay fix in `packages/ai` ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
+- Fixed Python eval `agent()` collapsing subagent runtime-limit aborts (and other empty-stderr aborts) into a generic `RuntimeError: bridge call '__agent__' failed`. `runEvalAgent` coalesced the failure message with `??`, which stopped at the empty `stderr` and never reached `abortReason`, shipping an empty error through the loopback bridge. The bridge now prefers `abortReason` for aborts and trims empty `stderr`/`error` out of the fallback chain, so Python surfaces the actionable reason (e.g. `Subagent runtime limit exceeded (task.maxRuntimeMs=900000)`) ([#2006](https://github.com/can1357/oh-my-pi/issues/2006)).
+
+## [15.9.69] - 2026-06-06
 
 ### Added
 
@@ -55,10 +60,9 @@
 - Fixed the `write` tool result rendering with a green success checkmark even when the write failed. `writeToolRenderer.renderResult` now branches on `result.isError`, rendering the error status icon plus the failure message instead of the success header and content preview.
 - Fixed Perplexity OAuth/cookie web search returning a refusal answer ("I don't currently have access to the web-search tools in this turn") despite returning real sources. `callPerplexityOAuth` was prepending the API-style `web-search` system prompt to the query (`query_str = systemPrompt + "\n\n" + query`), but the consumer `www.perplexity.ai/rest/sse/perplexity_ask` endpoint has no system-message slot and reads the prepended instruction as a meta-prompt, making the model decline. The OAuth/cookie path now sends the bare query; the API-key path still passes the system prompt as a proper `system` message.
 - Fixed Perplexity OAuth web search always returning the free `turbo` model instead of the account's Pro model (e.g. `pplx_pro_upgraded`/Sonar). The `www.perplexity.ai/rest/sse/perplexity_ask` endpoint authenticates via the `__Secure-next-auth.session-token` cookie and ignores the `Authorization: Bearer` header entirely — so sending the OAuth session token as a bearer was treated as an anonymous request, which silently downgrades to `turbo` regardless of `model_preference`. The stored Perplexity OAuth token is itself the next-auth session JWT (the macOS app injects the same value as that cookie), so `callPerplexityAsk` now sends it as the `__Secure-next-auth.session-token` cookie, unlocking Pro model selection.
-- Fixed the `todo` tool's TUI renderer crashing with `TypeError: args?.ops?.map is not a function` when a streaming tool-call delta surfaced a non-array `ops` field (mid-stream `parseStreamingJson` shapes like `{ ops: "[{" }`, or `[null]` entries before fields arrive). The renderer now treats non-array `ops`, non-object entries, and non-array `items` as missing structure instead of crashing, which also stops the spam-warn cascade that followed each malformed delta. Paired with the Anthropic-side reasoning-replay fix in `packages/ai` ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
-- Fixed Python eval `agent()` collapsing subagent runtime-limit aborts (and other empty-stderr aborts) into a generic `RuntimeError: bridge call '__agent__' failed`. `runEvalAgent` coalesced the failure message with `??`, which stopped at the empty `stderr` and never reached `abortReason`, shipping an empty error through the loopback bridge. The bridge now prefers `abortReason` for aborts and trims empty `stderr`/`error` out of the fallback chain, so Python surfaces the actionable reason (e.g. `Subagent runtime limit exceeded (task.maxRuntimeMs=900000)`) ([#2006](https://github.com/can1357/oh-my-pi/issues/2006)).
 
 ## [15.9.67] - 2026-06-06
+
 ### Added
 
 - Added `timeout-pause` and `timeout-resume` eval bridge status events emitted around `agent()`/`llm()` operations
@@ -9490,4 +9494,4 @@ Initial public release.
 - Git branch display in footer
 - Message queueing during streaming responses
 - OAuth integration for Gmail and Google Calendar access
-- HTML export with syntax highlighting and collapsible sections
\ No newline at end of file
+- HTML export with syntax highlighting and collapsible sections
diff --git a/packages/coding-agent/DEVELOPMENT.md b/packages/coding-agent/DEVELOPMENT.md
index 731434b48..3f16ac804 100644
--- a/packages/coding-agent/DEVELOPMENT.md
+++ b/packages/coding-agent/DEVELOPMENT.md
@@ -1017,7 +1017,7 @@ Core pipeline in `renderUrl(url, timeout, raw, signal)`:
    - HTML-to-text conversion (`renderHtmlToText`)
 7. If HTML conversion is low-quality (`isLowQualityOutput`), try document-link extraction (`extractDocumentLinks`) + markit.
 
-`renderHtmlToText(...)` fallback order is explicit in code: Jina reader endpoint (`https://r.jina.ai/<url>`), then `trafilatura` (via `ensureTool`), then `lynx`, then native `htmlToMarkdown`.
+`renderHtmlToText(...)` tries reader backends in priority order: native in-process `htmlToMarkdown`, then `trafilatura` (via `ensureTool`), then `lynx`, then Parallel extract, then the Jina reader endpoint (`https://r.jina.ai/<url>`). The `providers.fetch` setting picks the order — `auto` uses the default above; selecting a specific backend tries it first, then the rest as fallbacks. Every backend's output must clear the same quality gate (`>100` chars and not `isLowQualityOutput`); if none clears it, the highest-priority substantial-but-low-quality output is surfaced so step 7's targeted fallbacks still run. native operates on already-fetched HTML (instant, no network), so it both wins the common case and survives a stalled remote backend.
 
 ### Scraper registry role (`web/scrapers/index.ts`)
 
diff --git a/packages/coding-agent/src/config/settings-schema.ts b/packages/coding-agent/src/config/settings-schema.ts
index 5b8601ad6..96c8575b4 100644
--- a/packages/coding-agent/src/config/settings-schema.ts
+++ b/packages/coding-agent/src/config/settings-schema.ts
@@ -3059,13 +3059,26 @@ export const SETTINGS_SCHEMA = {
 			],
 		},
 	},
-	"providers.parallelFetch": {
-		type: "boolean",
-		default: true,
+	"providers.fetch": {
+		type: "enum",
+		values: ["auto", "native", "trafilatura", "lynx", "parallel", "jina"] as const,
+		default: "auto",
 		ui: {
 			tab: "providers",
-			label: "Parallel Fetch",
-			description: "Use Parallel extract API for URL fetching when credentials are available",
+			label: "Fetch Provider",
+			description: "Reader backend priority for the fetch/read URL tool",
+			options: [
+				{
+					value: "auto",
+					label: "Auto",
+					description: "Priority: native > trafilatura > lynx > parallel > jina",
+				},
+				{ value: "native", label: "Native", description: "In-process HTML→Markdown converter (always available)" },
+				{ value: "trafilatura", label: "Trafilatura", description: "Auto-installs via uv/pip" },
+				{ value: "lynx", label: "Lynx", description: "Requires lynx system package" },
+				{ value: "parallel", label: "Parallel", description: "Requires PARALLEL_API_KEY" },
+				{ value: "jina", label: "Jina", description: "Uses r.jina.ai reader (JINA_API_KEY optional)" },
+			],
 		},
 	},
 	"provider.appendOnlyContext": {
diff --git a/packages/coding-agent/src/config/settings.ts b/packages/coding-agent/src/config/settings.ts
index f5dc33299..432519460 100644
--- a/packages/coding-agent/src/config/settings.ts
+++ b/packages/coding-agent/src/config/settings.ts
@@ -712,6 +712,17 @@ export class Settings {
 			}
 		}
 
+		// providers.parallelFetch (boolean) replaced by the providers.fetch reader
+		// priority enum. The new default ("auto") supersedes both old values —
+		// Parallel is now a deep fallback in the auto chain rather than the first
+		// choice — so drop the legacy key (flat and nested) and let the enum
+		// default apply.
+		const providersObj = raw.providers as Record<string, unknown> | undefined;
+		if (providersObj && "parallelFetch" in providersObj) {
+			delete providersObj.parallelFetch;
+		}
+		delete raw["providers.parallelFetch"];
+
 		// Map legacy `memories.enabled` boolean to the explicit `memory.backend`
 		// enum if the latter hasn't been set yet. Idempotent: subsequent
 		// migrations are no-ops once memory.backend is materialised.
diff --git a/packages/coding-agent/src/tools/fetch.ts b/packages/coding-agent/src/tools/fetch.ts
index 5c949af5d..4e2dcbecf 100644
--- a/packages/coding-agent/src/tools/fetch.ts
+++ b/packages/coding-agent/src/tools/fetch.ts
@@ -581,14 +581,25 @@ function parseFeedToMarkdown(content: string, maxItems = 10): string {
  */
 const REMOTE_READER_MAX_MS = 10_000;
 
+/** Reader backends for {@link renderHtmlToText}, in default priority order. */
+export type FetchProvider = "native" | "trafilatura" | "lynx" | "parallel" | "jina";
+
+const FETCH_PROVIDER_ORDER: readonly FetchProvider[] = ["native", "trafilatura", "lynx", "parallel", "jina"];
+
 /**
- * Render HTML to markdown using Parallel, jina, trafilatura, lynx, then the
- * in-process native converter. The overall `timeout` budget bounds the call,
- * but remote reader requests are additionally capped at `REMOTE_READER_MAX_MS`
- * so that a hung remote endpoint cannot prevent local fallbacks from running.
- * Only a real `userSignal` cancellation aborts the chain — remote per-attempt
- * timeouts and the overall reader-mode timeout still allow later renderers
- * (especially the purely-local native converter) to be tried.
+ * Render HTML to markdown by trying reader backends in priority order: native
+ * (in-process), trafilatura, lynx, Parallel, then Jina. The `providers.fetch`
+ * setting picks the order — `auto` uses the default above; any specific backend
+ * is tried first, then the remaining backends as fallbacks. Every backend's
+ * output must clear the same quality gate (>100 non-whitespace chars and not
+ * {@link isLowQualityOutput}) before it is accepted, otherwise the next backend
+ * is tried.
+ *
+ * The overall `timeout` budget bounds the whole call; remote backends (Parallel,
+ * Jina) are additionally capped at `REMOTE_READER_MAX_MS` so a hung endpoint
+ * cannot starve later renderers — especially the purely-local native converter,
+ * which always works on already-loaded HTML. Only a real `userSignal`
+ * cancellation aborts the chain (#1449).
  */
 export async function renderHtmlToText(
 	url: string,
@@ -607,92 +618,74 @@ export async function renderHtmlToText(
 		signal: overallSignal,
 	};
 	const remoteBudgetMs = Math.min(timeout * 1000, REMOTE_READER_MAX_MS);
+	// Per-attempt budget for remote endpoints so one stall cannot consume the
+	// whole reader-mode budget and starve the local fallbacks.
+	const remoteSignal = () => ptree.combineSignals(userSignal, remoteBudgetMs);
 
-	// Try Parallel extract first when credentials are configured
-	if (settings.get("providers.parallelFetch") && findParallelApiKey(storage)) {
-		try {
+	const runners: Record<FetchProvider, () => Promise<string | null>> = {
+		// Purely local, no network/subprocess: still works on already-loaded HTML
+		// even after remote/subprocess attempts are aborted by the budget.
+		native: () => htmlToMarkdown(html, { cleanContent: true }),
+		trafilatura: async () => {
+			const trafilatura = await ensureTool("trafilatura", { signal: overallSignal, silent: true });
+			if (!trafilatura) return null;
+			const result = await ptree.exec([trafilatura, "-u", url, "--output-format", "markdown"], execOptions);
+			return result.ok ? result.stdout : null;
+		},
+		lynx: async () => {
+			if (!hasCommand("lynx")) return null;
+			const result = await ptree.exec(["lynx", "-dump", "-nolist", "-width", "250", url], execOptions);
+			return result.ok ? result.stdout : null;
+		},
+		parallel: async () => {
+			if (!findParallelApiKey(storage)) return null;
 			const parallelResult = await extractWithParallel(
 				[url],
-				{
-					objective: "Extract the main content",
-					excerpts: true,
-					fullContent: false,
-					signal: ptree.combineSignals(userSignal, remoteBudgetMs),
-				},
+				{ objective: "Extract the main content", excerpts: true, fullContent: false, signal: remoteSignal() },
 				storage,
 			);
 			const firstDocument = parallelResult.results[0];
-			if (firstDocument) {
-				const content = getParallelExtractContent(firstDocument);
-				if (content.trim().length > 100 && !isLowQualityOutput(content)) {
-					return { content, ok: true, method: "parallel" };
-				}
+			return firstDocument ? getParallelExtractContent(firstDocument) : null;
+		},
+		jina: async () => {
+			const response = await fetch(`https://r.jina.ai/${url}`, {
+				headers: { Accept: "text/markdown" },
+				signal: remoteSignal(),
+			});
+			return response.ok ? await response.text() : null;
+		},
+	};
+
+	const preference = settings.get("providers.fetch");
+	const order: readonly FetchProvider[] =
+		preference === "auto"
+			? FETCH_PROVIDER_ORDER
+			: [preference, ...FETCH_PROVIDER_ORDER.filter(method => method !== preference)];
+
+	// Highest-priority output that is substantial but fails the low-quality gate.
+	// Surfaced (ok: true) only when no backend clears the gate, so the caller's
+	// targeted fallbacks (llms.txt / document extraction) still run and we beat
+	// returning the unrendered raw HTML.
+	let lowQuality: { content: string; method: FetchProvider } | null = null;
+
+	for (const method of order) {
+		// Honour real user cancellation between attempts; remote per-attempt and
+		// overall-budget timeouts still fall through to later (local) renderers.
+		userSignal?.throwIfAborted();
+		try {
+			const content = await runners[method]();
+			if (!content || content.trim().length <= 100) continue;
+			if (!isLowQualityOutput(content)) {
+				return { content, ok: true, method };
 			}
+			lowQuality ??= { content, method };
 		} catch {
-			// Parallel extract failed or stalled; honour real cancellation only.
 			userSignal?.throwIfAborted();
 		}
 	}
 
-	// Try jina reader API with its own sub-budget so a stall cannot starve
-	// later fallbacks (#1449).
-	try {
-		const jinaUrl = `https://r.jina.ai/${url}`;
-		const response = await fetch(jinaUrl, {
-			headers: { Accept: "text/markdown" },
-			signal: ptree.combineSignals(userSignal, remoteBudgetMs),
-		});
-		if (response.ok) {
-			const content = await response.text();
-			if (content.trim().length > 100 && !isLowQualityOutput(content)) {
-				return { content, ok: true, method: "jina" };
-			}
-		}
-	} catch {
-		// Jina failed or stalled; honour real cancellation only.
-		userSignal?.throwIfAborted();
-	}
-
-	// Try trafilatura (auto-install via uv/pip)
-	try {
-		const trafilatura = await ensureTool("trafilatura", { signal: overallSignal, silent: true });
-		if (trafilatura) {
-			const result = await ptree.exec([trafilatura, "-u", url, "--output-format", "markdown"], execOptions);
-			if (result.ok && result.stdout.trim().length > 100) {
-				return { content: result.stdout, ok: true, method: "trafilatura" };
-			}
-		}
-	} catch {
-		// trafilatura unavailable or stalled; continue to next method.
-		userSignal?.throwIfAborted();
-	}
-
-	// Try lynx (can't auto-install, system package)
-	try {
-		const lynx = hasCommand("lynx");
-		if (lynx) {
-			const result = await ptree.exec(["lynx", "-dump", "-nolist", "-width", "250", url], execOptions);
-			if (result.ok) {
-				return { content: result.stdout, ok: true, method: "lynx" };
-			}
-		}
-	} catch {
-		// lynx failed or stalled; continue to native converter.
-		userSignal?.throwIfAborted();
-	}
-
-	// Fall back to native converter (purely local, no network/subprocess).
-	// Always attempted: even if remote renderers and subprocesses were aborted
-	// by the overall reader-mode timeout, this still works on already-loaded
-	// HTML (#1449).
-	try {
-		const content = await htmlToMarkdown(html, { cleanContent: true });
-		if (content.trim().length > 100 && !isLowQualityOutput(content)) {
-			return { content, ok: true, method: "native" };
-		}
-	} catch {
-		// Native converter failed; nothing else to try.
-		userSignal?.throwIfAborted();
+	if (lowQuality) {
+		return { content: lowQuality.content, ok: true, method: lowQuality.method };
 	}
 	return { content: "", ok: false, method: "none" };
 }
@@ -1141,10 +1134,27 @@ async function renderUrl(
 			throw new ToolAbortError();
 		}
 
-		// 5E: Render HTML with lynx or html2text
+		// 5E: Render HTML via the reader-backend chain (native/trafilatura/lynx/parallel/jina)
 		const htmlResult = await renderHtmlToText(finalUrl, rawContent, timeout, settings, signal, storage);
 		if (!htmlResult.ok) {
-			notes.push("html rendering failed (lynx/html2text unavailable)");
+			notes.push("html rendering failed (no reader backend produced usable output)");
+
+			const llmResult = await tryLlmEndpoints(finalUrl, timeout, signal);
+			if (llmResult) {
+				notes.push(`Used llms.txt fallback: ${llmResult.endpoint}`);
+				const output = finalizeOutput(llmResult.content);
+				return {
+					url,
+					finalUrl,
+					contentType: "text/plain",
+					method: "llms.txt",
+					content: output.content,
+					fetchedAt,
+					truncated: output.truncated,
+					notes,
+				};
+			}
+
 			const output = finalizeOutput(rawContent);
 			return {
 				url,
diff --git a/packages/coding-agent/src/web/scrapers/youtube.ts b/packages/coding-agent/src/web/scrapers/youtube.ts
index 1ecd4090f..6dec1276b 100644
--- a/packages/coding-agent/src/web/scrapers/youtube.ts
+++ b/packages/coding-agent/src/web/scrapers/youtube.ts
@@ -113,8 +113,9 @@ export const handleYouTube: SpecialHandler = async (
 	const notes: string[] = [];
 	const videoUrl = `https://www.youtube.com/watch?v=${yt.videoId}`;
 
-	// Prefer Parallel extract when credentials are available
-	if (settings.get("providers.parallelFetch") && findParallelApiKey(storage)) {
+	// Prefer Parallel extract when it sits in the reader chain and creds exist
+	const fetchPreference = settings.get("providers.fetch");
+	if ((fetchPreference === "auto" || fetchPreference === "parallel") && findParallelApiKey(storage)) {
 		try {
 			const parallelResult = await extractWithParallel(
 				[videoUrl],
diff --git a/packages/coding-agent/test/tools/fetch-jina-stall.test.ts b/packages/coding-agent/test/tools/fetch-jina-stall.test.ts
index 7582f1cc2..4b150f16a 100644
--- a/packages/coding-agent/test/tools/fetch-jina-stall.test.ts
+++ b/packages/coding-agent/test/tools/fetch-jina-stall.test.ts
@@ -14,7 +14,9 @@ describe("renderHtmlToText: jina stall does not starve local fallbacks (#1449)",
 	});
 
 	it("falls back to native renderer when jina hangs until aborted", async () => {
-		const settings = Settings.isolated({ "providers.parallelFetch": false });
+		// Force jina first so the stall path is actually exercised before the
+		// native fallback runs.
+		const settings = Settings.isolated({ "providers.fetch": "jina" });
 		// Substantive HTML so the native converter produces >100 chars and
 		// `isLowQualityOutput` does not reject it.
 		const paragraphs = Array.from(
@@ -66,7 +68,7 @@ describe("renderHtmlToText: jina stall does not starve local fallbacks (#1449)",
 	});
 
 	it("re-throws when the user signal is aborted, not when Jina sub-budget expires", async () => {
-		const settings = Settings.isolated({ "providers.parallelFetch": false });
+		const settings = Settings.isolated({ "providers.fetch": "jina" });
 		const html = "<html><body><p>short</p></body></html>";
 
 		using _hook = hookFetch((_input, init, _next) => {
diff --git a/packages/coding-agent/test/tools/fetch-kagi-toggle.test.ts b/packages/coding-agent/test/tools/fetch-kagi-toggle.test.ts
index 0b3dfea14..facfef759 100644
--- a/packages/coding-agent/test/tools/fetch-kagi-toggle.test.ts
+++ b/packages/coding-agent/test/tools/fetch-kagi-toggle.test.ts
@@ -34,7 +34,7 @@ describe("read tool URL selector shorthands", () => {
 		fs.rmSync(testDir, { recursive: true, force: true });
 	});
 
-	const createSession = (): ToolSession => {
+	const createSession = (settingsOverrides: Partial<Record<SettingPath, unknown>> = {}): ToolSession => {
 		const sessionFile = path.join(testDir, "session.jsonl");
 		const artifactsDir = sessionFile.slice(0, -6);
 		let nextArtifactId = 0;
@@ -53,6 +53,7 @@ describe("read tool URL selector shorthands", () => {
 			},
 			settings: Settings.isolated({
 				"fetch.enabled": true,
+				...settingsOverrides,
 			}),
 		};
 	};
@@ -575,9 +576,9 @@ describe("read tool URL handling", () => {
 		void missingSystemPython;
 		void hook;
 	});
-	it("prefers Parallel extract before other HTML renderers when configured", async () => {
+	it("prefers Parallel extract first when providers.fetch is set to parallel", async () => {
 		process.env.PARALLEL_API_KEY = "test-parallel-key";
-		const session = createSession();
+		const session = createSession({ "providers.fetch": "parallel" });
 		const tool = new ReadTool(session);
 		const pageUrl = "https://example.com/parallel-page";
 		const pageHtml = "<html><body><main><h1>Parallel Page</h1></main></body></html>";
diff --git a/packages/coding-agent/test/tools/web-scrapers/youtube-parallel.test.ts b/packages/coding-agent/test/tools/web-scrapers/youtube-parallel.test.ts
index 42de8a4c8..60e041930 100644
--- a/packages/coding-agent/test/tools/web-scrapers/youtube-parallel.test.ts
+++ b/packages/coding-agent/test/tools/web-scrapers/youtube-parallel.test.ts
@@ -8,7 +8,7 @@ describe("handleYouTube with Parallel extract", () => {
 	beforeEach(async () => {
 		resetSettingsForTest();
 		process.env.PARALLEL_API_KEY = "test-parallel-key";
-		await Settings.init({ inMemory: true, overrides: { "providers.parallelFetch": true } });
+		await Settings.init({ inMemory: true, overrides: { "providers.fetch": "auto" } });
 	});
 
 	afterEach(() => {

From 1cdd28cd1833bf7e216e7f51ac0d9127f7ef8027 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 00:04:12 +0200
Subject: [PATCH 069/181] build(tsconfig): removed decorator and class-field
 compiler options

- Dropped experimentalDecorators, emitDecoratorMetadata, and useDefineForClassFields from the base config.
---
 tsconfig.base.json | 12 +-----------
 1 file changed, 1 insertion(+), 11 deletions(-)

diff --git a/tsconfig.base.json b/tsconfig.base.json
index c7f4cfcbf..0639244e8 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -10,20 +10,10 @@
 		"allowArbitraryExtensions": true,
 		"verbatimModuleSyntax": true,
 		"noEmit": true,
-		"emitDeclarationOnly": false,
-		"declaration": true,
-		"declarationMap": true,
-		"sourceMap": true,
-		"inlineSources": true,
-		"inlineSourceMap": false,
 		"resolveJsonModule": true,
 		"esModuleInterop": true,
 		"forceConsistentCasingInFileNames": true,
-		"experimentalDecorators": true,
-		"emitDecoratorMetadata": true,
-		"useDefineForClassFields": false,
 		"types": ["bun", "assets"],
-		"typeRoots": ["./types", "./node_modules/@types"],
-		"assumeChangesOnlyAffectDirectDependencies": true
+		"typeRoots": ["./types", "./node_modules/@types"]
 	}
 }

From fe607cf22cf9c7ff2d6e8c345b53f2a6ac35018d Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 00:16:09 +0200
Subject: [PATCH 070/181] chore: bump version to 15.10.0

---
 Cargo.lock                            |  8 +++---
 Cargo.toml                            |  2 +-
 bun.lock                              | 38 +++++++++++++--------------
 crates/pi-natives/src/lib.rs          |  2 +-
 package.json                          | 18 ++++++-------
 packages/agent/package.json           |  2 +-
 packages/ai/CHANGELOG.md              |  2 ++
 packages/ai/package.json              |  2 +-
 packages/coding-agent/CHANGELOG.md    |  2 ++
 packages/coding-agent/package.json    |  2 +-
 packages/hashline/package.json        |  2 +-
 packages/mnemopi/package.json         |  2 +-
 packages/natives/native/index.d.ts    |  2 +-
 packages/natives/native/index.js      |  2 +-
 packages/natives/package.json         |  2 +-
 packages/stats/package.json           |  2 +-
 packages/swarm-extension/package.json |  2 +-
 packages/tui/CHANGELOG.md             |  2 ++
 packages/tui/package.json             |  2 +-
 packages/utils/CHANGELOG.md           |  2 ++
 packages/utils/package.json           |  2 +-
 21 files changed, 54 insertions(+), 46 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 170561fab..dd2b7e74c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2331,7 +2331,7 @@ dependencies = [
 
 [[package]]
 name = "pi-ast"
-version = "15.9.69"
+version = "15.10.0"
 dependencies = [
  "anyhow",
  "ast-grep-core",
@@ -2399,7 +2399,7 @@ dependencies = [
 
 [[package]]
 name = "pi-iso"
-version = "15.9.69"
+version = "15.10.0"
 dependencies = [
  "async-trait",
  "libc",
@@ -2411,7 +2411,7 @@ dependencies = [
 
 [[package]]
 name = "pi-natives"
-version = "15.9.69"
+version = "15.10.0"
 dependencies = [
  "anyhow",
  "arboard",
@@ -2457,7 +2457,7 @@ dependencies = [
 
 [[package]]
 name = "pi-shell"
-version = "15.9.69"
+version = "15.10.0"
 dependencies = [
  "anyhow",
  "brush-builtins",
diff --git a/Cargo.toml b/Cargo.toml
index 5a0405396..816514245 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ exclude = ["crates/brush-core-vendored", "crates/brush-builtins-vendored"]
 resolver = "3"
 
 [workspace.package]
-version = "15.9.69"
+version = "15.10.0"
 edition = "2024"
 license = "MIT"
 authors = ["Can Boluk"]
diff --git a/bun.lock b/bun.lock
index 78a5b2598..95153a04e 100644
--- a/bun.lock
+++ b/bun.lock
@@ -15,7 +15,7 @@
     },
     "packages/agent": {
       "name": "@oh-my-pi/pi-agent-core",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "dependencies": {
         "@oh-my-pi/pi-ai": "catalog:",
         "@oh-my-pi/pi-natives": "catalog:",
@@ -30,7 +30,7 @@
     },
     "packages/ai": {
       "name": "@oh-my-pi/pi-ai",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "dependencies": {
         "@bufbuild/protobuf": "catalog:",
         "@oh-my-pi/pi-utils": "catalog:",
@@ -44,7 +44,7 @@
     },
     "packages/coding-agent": {
       "name": "@oh-my-pi/pi-coding-agent",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "bin": {
         "omp": "src/cli.ts",
       },
@@ -90,7 +90,7 @@
     },
     "packages/hashline": {
       "name": "@oh-my-pi/hashline",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "dependencies": {
         "diff": "catalog:",
         "lru-cache": "catalog:",
@@ -101,7 +101,7 @@
     },
     "packages/mnemopi": {
       "name": "@oh-my-pi/pi-mnemopi",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "bin": {
         "mnemopi": "src/cli.ts",
       },
@@ -118,7 +118,7 @@
     },
     "packages/natives": {
       "name": "@oh-my-pi/pi-natives",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "devDependencies": {
         "@napi-rs/cli": "catalog:",
         "@types/bun": "catalog:",
@@ -126,7 +126,7 @@
     },
     "packages/stats": {
       "name": "@oh-my-pi/omp-stats",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "bin": {
         "omp-stats": "./src/index.ts",
       },
@@ -151,7 +151,7 @@
     },
     "packages/swarm-extension": {
       "name": "@oh-my-pi/swarm-extension",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "bin": {
         "omp-swarm": "src/cli.ts",
       },
@@ -167,7 +167,7 @@
     },
     "packages/tui": {
       "name": "@oh-my-pi/pi-tui",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "dependencies": {
         "@oh-my-pi/pi-natives": "catalog:",
         "@oh-my-pi/pi-utils": "catalog:",
@@ -208,7 +208,7 @@
     },
     "packages/utils": {
       "name": "@oh-my-pi/pi-utils",
-      "version": "15.9.69",
+      "version": "15.10.0",
       "dependencies": {
         "@oh-my-pi/pi-natives": "catalog:",
         "beautiful-mermaid": "catalog:",
@@ -248,15 +248,15 @@
     "@huggingface/transformers": "^4.2.0",
     "@mozilla/readability": "^0.6.0",
     "@napi-rs/cli": "3.7.0",
-    "@oh-my-pi/hashline": "15.9.69",
-    "@oh-my-pi/omp-stats": "15.9.69",
-    "@oh-my-pi/pi-agent-core": "15.9.69",
-    "@oh-my-pi/pi-ai": "15.9.69",
-    "@oh-my-pi/pi-coding-agent": "15.9.69",
-    "@oh-my-pi/pi-mnemopi": "15.9.69",
-    "@oh-my-pi/pi-natives": "15.9.69",
-    "@oh-my-pi/pi-tui": "15.9.69",
-    "@oh-my-pi/pi-utils": "15.9.69",
+    "@oh-my-pi/hashline": "15.10.0",
+    "@oh-my-pi/omp-stats": "15.10.0",
+    "@oh-my-pi/pi-agent-core": "15.10.0",
+    "@oh-my-pi/pi-ai": "15.10.0",
+    "@oh-my-pi/pi-coding-agent": "15.10.0",
+    "@oh-my-pi/pi-mnemopi": "15.10.0",
+    "@oh-my-pi/pi-natives": "15.10.0",
+    "@oh-my-pi/pi-tui": "15.10.0",
+    "@oh-my-pi/pi-utils": "15.10.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.7.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",
diff --git a/crates/pi-natives/src/lib.rs b/crates/pi-natives/src/lib.rs
index 186fca14d..9315e6d6d 100644
--- a/crates/pi-natives/src/lib.rs
+++ b/crates/pi-natives/src/lib.rs
@@ -68,5 +68,5 @@ use napi_derive::napi;
 /// MUST stay in sync with `VERSION_SENTINEL_EXPORT` in
 /// `packages/natives/native/index.js` (which derives the name from
 /// `package.json#version`).
-#[napi(js_name = "__piNativesV15_9_69")]
+#[napi(js_name = "__piNativesV15_10_0")]
 pub const fn pi_natives_version_sentinel() {}
diff --git a/package.json b/package.json
index 91848ac82..bed3a457c 100644
--- a/package.json
+++ b/package.json
@@ -20,15 +20,15 @@
       "@huggingface/transformers": "^4.2.0",
       "@mozilla/readability": "^0.6.0",
       "@napi-rs/cli": "3.7.0",
-      "@oh-my-pi/hashline": "15.9.69",
-      "@oh-my-pi/omp-stats": "15.9.69",
-      "@oh-my-pi/pi-agent-core": "15.9.69",
-      "@oh-my-pi/pi-ai": "15.9.69",
-      "@oh-my-pi/pi-coding-agent": "15.9.69",
-      "@oh-my-pi/pi-mnemopi": "15.9.69",
-      "@oh-my-pi/pi-natives": "15.9.69",
-      "@oh-my-pi/pi-tui": "15.9.69",
-      "@oh-my-pi/pi-utils": "15.9.69",
+      "@oh-my-pi/hashline": "15.10.0",
+      "@oh-my-pi/omp-stats": "15.10.0",
+      "@oh-my-pi/pi-agent-core": "15.10.0",
+      "@oh-my-pi/pi-ai": "15.10.0",
+      "@oh-my-pi/pi-coding-agent": "15.10.0",
+      "@oh-my-pi/pi-mnemopi": "15.10.0",
+      "@oh-my-pi/pi-natives": "15.10.0",
+      "@oh-my-pi/pi-tui": "15.10.0",
+      "@oh-my-pi/pi-utils": "15.10.0",
       "@opentelemetry/api": "^1.9.1",
       "@opentelemetry/context-async-hooks": "^2.7.1",
       "@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",
diff --git a/packages/agent/package.json b/packages/agent/package.json
index 6310a8e04..840bc95e2 100644
--- a/packages/agent/package.json
+++ b/packages/agent/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 35e9b0b6b..07b1d9402 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.10.0] - 2026-06-06
+
 ### Added
 
 - Added a dependency-free `@oh-my-pi/pi-ai/effort` module exporting the `Effort` enum and `THINKING_EFFORTS`, split out of `model-thinking` so hot-path consumers can import the thinking levels without pulling in `model-thinking` and its provider-compat dependency graph. The package barrel still re-exports both names, so existing imports are unaffected.
diff --git a/packages/ai/package.json b/packages/ai/package.json
index 30ed8ddba..2e02371fa 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0297e1bbe..5246c39e0 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.10.0] - 2026-06-06
+
 ### Breaking Changes
 
 - Replaced the `providers.parallelFetch` boolean setting with the `providers.fetch` enum (`auto` / `native` / `trafilatura` / `lynx` / `parallel` / `jina`) that selects the URL reader-backend priority for the `read`/`fetch` tool, mirroring `providers.image`/`providers.webSearch`. Existing configs are migrated automatically: the legacy key is dropped and the new `auto` default applies.
diff --git a/packages/coding-agent/package.json b/packages/coding-agent/package.json
index 7698d64de..e86222fba 100644
--- a/packages/coding-agent/package.json
+++ b/packages/coding-agent/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/hashline/package.json b/packages/hashline/package.json
index 98c20ce7f..3b4b99e55 100644
--- a/packages/hashline/package.json
+++ b/packages/hashline/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/mnemopi/package.json b/packages/mnemopi/package.json
index 2687a9186..db14552f5 100644
--- a/packages/mnemopi/package.json
+++ b/packages/mnemopi/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-mnemopi",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "Local SQLite memory engine for Oh My Pi agents",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/natives/native/index.d.ts b/packages/natives/native/index.d.ts
index a008fcbb1..827c49936 100644
--- a/packages/natives/native/index.d.ts
+++ b/packages/natives/native/index.d.ts
@@ -136,7 +136,7 @@ export declare class Shell {
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV15_9_69(): void
+export declare function __piNativesV15_10_0(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
diff --git a/packages/natives/native/index.js b/packages/natives/native/index.js
index 9048b0f2e..b662239fa 100644
--- a/packages/natives/native/index.js
+++ b/packages/natives/native/index.js
@@ -23,7 +23,7 @@ export const PtySession = nativeBindings.PtySession;
 export const Shell = nativeBindings.Shell;
 
 // functions
-export const __piNativesV15_9_69 = nativeBindings.__piNativesV15_9_69;
+export const __piNativesV15_10_0 = nativeBindings.__piNativesV15_10_0;
 export const applyBashFixups = nativeBindings.applyBashFixups;
 export const astEdit = nativeBindings.astEdit;
 export const astGrep = nativeBindings.astGrep;
diff --git a/packages/natives/package.json b/packages/natives/package.json
index 65f55801e..4076f4d0a 100644
--- a/packages/natives/package.json
+++ b/packages/natives/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@oh-my-pi/pi-natives",
-  "version": "15.9.69",
+  "version": "15.10.0",
   "description": "Native Rust bindings for grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
   "type": "module",
   "homepage": "https://omp.sh",
diff --git a/packages/stats/package.json b/packages/stats/package.json
index 79d24ca71..501113c72 100644
--- a/packages/stats/package.json
+++ b/packages/stats/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/omp-stats",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "Local observability dashboard for pi AI usage statistics",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/swarm-extension/package.json b/packages/swarm-extension/package.json
index 4e224cccb..1008d156c 100644
--- a/packages/swarm-extension/package.json
+++ b/packages/swarm-extension/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/swarm-extension",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "Swarm orchestration extension for omp",
 	"homepage": "https://omp.sh",
 	"author": "Derek Rynd",
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 1cecbf5d5..d864ad9ba 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.10.0] - 2026-06-06
+
 ### Changed
 
 - Reworked the DEC 2026 synchronized-output default policy: a positive DECRQM mode-2026 report now **enables** sync (previously a report could only disable it), so conservatively defaulted-off hosts that actually support it — current Zellij, tmux master, foot, contour, mintty — are upgraded at runtime. The static allowlist also covers Alacritty and the VS Code terminal, honors a `TERM_FEATURES` `Sy` advertisement and `WT_SESSION` (Windows Terminal / WSL), and no longer blanket-disables SSH (DEC 2026 passes through to the outer terminal). Risky multiplexers still start off and rely on the probe. Added `synchronizedOutputUserOverride()` as the shared opt-out/force resolver.
diff --git a/packages/tui/package.json b/packages/tui/package.json
index 2a2140346..bbf0da634 100644
--- a/packages/tui/package.json
+++ b/packages/tui/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/utils/CHANGELOG.md b/packages/utils/CHANGELOG.md
index ae4d73f15..5bb2baa09 100644
--- a/packages/utils/CHANGELOG.md
+++ b/packages/utils/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.10.0] - 2026-06-06
+
 ### Changed
 
 - `logger.printTimings()` (the `PI_TIMING` startup tree) now surfaces two previously-invisible regions: a `(before instrumentation)` line for runtime init / uncaptured pre-marker work, and an `(unattributed self)` line for the root span's own untimed work so the gap between visible top-level spans and `Total` is no longer swallowed. `Total` is now labelled `(since first marker)` to make the window explicit. The restored `module-timer.ts` preload can feed module spans into the report: each module records `onLoad` → final top-level marker as `total`, a prepended body marker → final marker as `body/TLA`, and resolved static imports as a bounded dependency tree so the report separates graph wait from actual top-level module work.
diff --git a/packages/utils/package.json b/packages/utils/package.json
index 6a022067f..fafae9827 100644
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "15.9.69",
+	"version": "15.10.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",

From caee75de28811ce3678895c6340bcda7c53f9c62 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sat, 6 Jun 2026 22:18:44 +0000
Subject: [PATCH 071/181] fix(ai): routed llama.cpp parallel tool calls by
 item.call_id
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

llama.cpp's /v1/responses emits function_call `output_item.added` with
only `item.call_id` (no `item.id`, no `output_index`); the matching
`function_call_arguments.delta` carries `item_id: "fc_<call_id>"`.
`processResponsesStream` keyed its lookup map by `item.id` only, so
the registry stayed empty and every delta fell back to `lastOpenItem`
— the most recently added block. With N parallel calls, N-1 of them
finalized with arguments `{}` and the agent rejected them with
`path: Invalid input: expected string, received undefined`, while the
trailing call hoarded every delta.

Register function-call and custom-tool-call items under `item.call_id`
as a secondary key alongside `item.id`/`output_index`, and look up by
the same fallback in `output_item.done`. Real OpenAI is unaffected
(distinct keys, both populated). Regression test pins the exact
llama.cpp emission shape.

Fixes #2015
---
 packages/ai/CHANGELOG.md                      |  1 +
 .../src/providers/openai-responses-shared.ts  | 24 ++++--
 ...enai-responses-parallel-tool-calls.test.ts | 75 +++++++++++++++++++
 3 files changed, 95 insertions(+), 5 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index db832fa7b..3d53990a2 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -17,6 +17,7 @@
 ### Fixed
 
 - Fixed Anthropic-compatible reasoning endpoints losing prior-turn reasoning on continuation requests when they emit unsigned `thinking` blocks. `convertAnthropicMessages` treated unknown endpoints as signature-enforcing and demoted unsigned reasoning to `type: "text"`, which destabilized tool-call argument serialization on the next turn — the upstream symptom behind the `args?.ops?.map is not a function` crash reported against the `todo` tool. Official `api.anthropic.com` keeps the conservative text fallback; non-official `anthropic-messages` reasoning models now replay unsigned reasoning as native `type: "thinking"` ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
+- Fixed parallel `function_call` items losing arguments against llama.cpp's OpenAI Responses endpoint (`/v1/responses`), where every call but the last finalized with `{}` and the agent rejected them with `path: Invalid input: expected string, received undefined`. llama.cpp's `to_json_oaicompat_resp` emits `output_item.added` with only `item.call_id` (no `item.id`, no `output_index`) while the matching `function_call_arguments.delta` carries `item_id: "fc_<call_id>"`. `processResponsesStream` now registers function-call and custom-tool-call items under `item.call_id` as a secondary lookup key (alongside `item.id`/`output_index`) so identifier-deviant hosts route deltas and done events to the right block. ([#2015](https://github.com/can1357/oh-my-pi/issues/2015))
 
 ## [15.9.67] - 2026-06-06
 
diff --git a/packages/ai/src/providers/openai-responses-shared.ts b/packages/ai/src/providers/openai-responses-shared.ts
index 8fc389838..28532dcc8 100644
--- a/packages/ai/src/providers/openai-responses-shared.ts
+++ b/packages/ai/src/providers/openai-responses-shared.ts
@@ -459,6 +459,13 @@ export async function processResponsesStream<TApi extends Api>(
 	// see https://github.com/can1357/oh-my-pi/issues/1880 — llama.cpp emits parallel
 	// function_call deltas interleaved, and a singleton `current` reference would
 	// fold them into the wrong block and drop arguments on every call but the last.
+	//
+	// llama.cpp's `to_json_oaicompat_resp` (issue #2015) compounds this: `output_item.added`
+	// for function_call/custom_tool_call carries `item.call_id` but no `item.id` and no
+	// `output_index`, while the matching `function_call_arguments.delta` carries
+	// `item_id = "fc_<call_id>"`. Registering function-call items by `call_id` as a
+	// secondary key lets the delta lookup find the right block on hosts that emit one
+	// identifier but not the other.
 	const openItemsByOutputIndex = new Map<number, StreamingItem>();
 	const openItemsByItemId = new Map<string, StreamingItem>();
 	let lastOpenItem: StreamingItem | null = null;
@@ -468,9 +475,11 @@ export async function processResponsesStream<TApi extends Api>(
 		outputIndex: number | undefined,
 		itemId: string | undefined,
 		entry: StreamingItem,
+		alternateItemKey?: string,
 	): void => {
 		if (typeof outputIndex === "number") openItemsByOutputIndex.set(outputIndex, entry);
 		if (itemId) openItemsByItemId.set(itemId, entry);
+		if (alternateItemKey && alternateItemKey !== itemId) openItemsByItemId.set(alternateItemKey, entry);
 		openItemsInOrder.push(entry);
 		lastOpenItem = entry;
 	};
@@ -508,9 +517,11 @@ export async function processResponsesStream<TApi extends Api>(
 		outputIndex: number | undefined,
 		itemId: string | undefined,
 		entry: StreamingItem | undefined,
+		alternateItemKey?: string,
 	): void => {
 		if (typeof outputIndex === "number") openItemsByOutputIndex.delete(outputIndex);
 		if (itemId) openItemsByItemId.delete(itemId);
+		if (alternateItemKey && alternateItemKey !== itemId) openItemsByItemId.delete(alternateItemKey);
 		if (entry) {
 			const index = openItemsInOrder.indexOf(entry);
 			if (index >= 0) openItemsInOrder.splice(index, 1);
@@ -550,7 +561,7 @@ export async function processResponsesStream<TApi extends Api>(
 					partialJson: item.arguments || "",
 				};
 				output.content.push(block);
-				registerOpenItem(event.output_index, item.id, { item, block });
+				registerOpenItem(event.output_index, item.id, { item, block }, item.call_id);
 				stream.push({ type: "toolcall_start", contentIndex: contentIndexOf(block), partial: output });
 			} else if (item.type === "custom_tool_call") {
 				const block: StreamingToolCallBlock = {
@@ -568,7 +579,7 @@ export async function processResponsesStream<TApi extends Api>(
 					partialJson: item.input ?? "",
 				};
 				output.content.push(block);
-				registerOpenItem(event.output_index, item.id, { item, block });
+				registerOpenItem(event.output_index, item.id, { item, block }, item.call_id);
 				stream.push({ type: "toolcall_start", contentIndex: contentIndexOf(block), partial: output });
 			}
 		} else if (event.type === "response.reasoning_summary_part.added") {
@@ -709,7 +720,10 @@ export async function processResponsesStream<TApi extends Api>(
 		} else if (event.type === "response.output_item.done") {
 			const item = structuredCloneJSON(event.item);
 			options?.onOutputItemDone?.(item);
-			const entry = lookupOpenItem({ output_index: event.output_index, item_id: item.id });
+			const entry =
+				item.type === "function_call" || item.type === "custom_tool_call"
+					? lookupOpenItem({ output_index: event.output_index, item_id: item.id ?? item.call_id })
+					: lookupOpenItem({ output_index: event.output_index, item_id: item.id });
 			if (item.type === "reasoning") {
 				const thinking =
 					item.summary?.length > 0
@@ -768,7 +782,7 @@ export async function processResponsesStream<TApi extends Api>(
 					delete (block as { argumentsDone?: boolean }).argumentsDone;
 				}
 				const contentIndex = block ? contentIndexOf(block) : output.content.length - 1;
-				closeOpenItem(event.output_index, item.id, entry);
+				closeOpenItem(event.output_index, item.id, entry, item.call_id);
 				stream.push({ type: "toolcall_end", contentIndex, toolCall, partial: output });
 			} else if (item.type === "custom_tool_call") {
 				const block = entry?.block.type === "toolCall" ? entry.block : undefined;
@@ -781,7 +795,7 @@ export async function processResponsesStream<TApi extends Api>(
 					customWireName: item.name,
 				};
 				const contentIndex = block ? contentIndexOf(block) : output.content.length - 1;
-				closeOpenItem(event.output_index, item.id, entry);
+				closeOpenItem(event.output_index, item.id, entry, item.call_id);
 				stream.push({ type: "toolcall_end", contentIndex, toolCall, partial: output });
 			}
 		} else if (event.type === "response.completed") {
diff --git a/packages/ai/test/openai-responses-parallel-tool-calls.test.ts b/packages/ai/test/openai-responses-parallel-tool-calls.test.ts
index 9523d13db..dbff9a657 100644
--- a/packages/ai/test/openai-responses-parallel-tool-calls.test.ts
+++ b/packages/ai/test/openai-responses-parallel-tool-calls.test.ts
@@ -260,4 +260,79 @@ describe("processResponsesStream: parallel function_call items", () => {
 		expect(byCallId.get("call_a")?.toolCall.arguments).toEqual({ command: "printf a" });
 		expect(byCallId.get("call_b")?.toolCall.arguments).toEqual({ command: "printf b" });
 	});
+
+	test("routes deltas by item.call_id when llama.cpp omits item.id and output_index (issue #2015)", async () => {
+		// llama.cpp's `to_json_oaicompat_resp` (tools/server/server-task.cpp) emits a
+		// function_call's `output_item.added` with only `item.call_id` — no `item.id`,
+		// no `output_index`. The matching `function_call_arguments.delta` then carries
+		// `item_id: "fc_<call_id>"` and again no `output_index`. Without secondary
+		// indexing on `call_id`, `processResponsesStream`'s lookup map stays empty and
+		// every delta lands on the trailing block, leaving earlier calls with empty
+		// arguments (= `{}`) — the read tool then rejects them with
+		// `path: Invalid input: expected string, received undefined`.
+		const output = makeOutput();
+		const emitted: EmittedEvent[] = [];
+		const stream = { push: (e: unknown) => emitted.push(e as EmittedEvent), end: () => {} } as never;
+
+		const argsA = JSON.stringify({ path: "a.txt" });
+		const argsB = JSON.stringify({ path: "b.txt" });
+		const argsC = JSON.stringify({ path: "c.txt" });
+
+		await processResponsesStream(
+			makeStream([
+				{
+					type: "response.output_item.added",
+					item: { type: "function_call", call_id: "fc_a", name: "read", arguments: "" },
+				},
+				{
+					type: "response.output_item.added",
+					item: { type: "function_call", call_id: "fc_b", name: "read", arguments: "" },
+				},
+				{
+					type: "response.output_item.added",
+					item: { type: "function_call", call_id: "fc_c", name: "read", arguments: "" },
+				},
+				{ type: "response.function_call_arguments.delta", item_id: "fc_a", delta: argsA },
+				{ type: "response.function_call_arguments.delta", item_id: "fc_b", delta: argsB },
+				{ type: "response.function_call_arguments.delta", item_id: "fc_c", delta: argsC },
+				{
+					type: "response.output_item.done",
+					item: { type: "function_call", call_id: "fc_a", name: "read", arguments: argsA },
+				},
+				{
+					type: "response.output_item.done",
+					item: { type: "function_call", call_id: "fc_b", name: "read", arguments: argsB },
+				},
+				{
+					type: "response.output_item.done",
+					item: { type: "function_call", call_id: "fc_c", name: "read", arguments: argsC },
+				},
+			]),
+			output,
+			stream,
+			makeModel(),
+		);
+
+		expect(output.content).toHaveLength(3);
+		const [a, b, c] = output.content;
+		if (a?.type !== "toolCall" || b?.type !== "toolCall" || c?.type !== "toolCall") {
+			throw new Error("expected toolCalls");
+		}
+		expect(a.arguments).toEqual({ path: "a.txt" });
+		expect(b.arguments).toEqual({ path: "b.txt" });
+		expect(c.arguments).toEqual({ path: "c.txt" });
+
+		const ends = emitted.filter(e => e.type === "toolcall_end") as Array<{
+			toolCall: { id: string; arguments: Record<string, unknown> };
+			contentIndex: number;
+		}>;
+		expect(ends).toHaveLength(3);
+		const byCallId = new Map(ends.map(e => [e.toolCall.id.split("|")[0], e]));
+		expect(byCallId.get("fc_a")?.toolCall.arguments).toEqual({ path: "a.txt" });
+		expect(byCallId.get("fc_b")?.toolCall.arguments).toEqual({ path: "b.txt" });
+		expect(byCallId.get("fc_c")?.toolCall.arguments).toEqual({ path: "c.txt" });
+		expect(byCallId.get("fc_a")?.contentIndex).toBe(0);
+		expect(byCallId.get("fc_b")?.contentIndex).toBe(1);
+		expect(byCallId.get("fc_c")?.contentIndex).toBe(2);
+	});
 });

From e401f7d407eaf982b698bc3bed0310da66aeefe9 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 02:23:18 +0200
Subject: [PATCH 072/181] fix(tools): fixed grouped output rendering with
 nested directory headers

- Replaced split-by-blank parsing in grouped renderers with classifyGroupedLines.
- Introduced path-tree grouping and folding to render multi-level directory headers.
- Normalized and deduplicated grouped paths, treating URL-like entries as root files.
- Adjusted file/url context mapping to keep line links stable across blank boundaries.
---
 packages/coding-agent/CHANGELOG.md            |  10 +-
 packages/coding-agent/src/lsp/utils.ts        |   5 +-
 packages/coding-agent/src/tools/ast-edit.ts   |  70 ++--
 packages/coding-agent/src/tools/ast-grep.ts   |  67 ++--
 packages/coding-agent/src/tools/find.ts       |  38 +--
 .../src/tools/grouped-file-output.ts          | 317 +++++++++++++++---
 .../coding-agent/src/tools/render-utils.ts    |  30 --
 packages/coding-agent/src/tools/search.ts     | 107 +++---
 .../coding-agent/test/tools/ast-edit.test.ts  |   5 +-
 .../coding-agent/test/tools/ast-grep.test.ts  |   7 +-
 .../test/tools/grouped-file-output.test.ts    | 118 +++++++
 11 files changed, 507 insertions(+), 267 deletions(-)
 create mode 100644 packages/coding-agent/test/tools/grouped-file-output.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 5246c39e0..1e4be8e85 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,6 +1,14 @@
 # Changelog
 
 ## [Unreleased]
+### Changed
+
+- Changed the directory grouping for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics from a single flat `# dir/` heading per immediate directory to a multi-level tree that folds the common path prefix into one heading. Previously every group repeated the full directory path — so results rooted outside cwd printed the absolute prefix (e.g. `/Users/me/proj/`) on every heading and nested directories were never collapsed. Now a single-child directory chain folds into one heading (`# packages/pkg/src/`, including an absolute root for out-of-cwd results), subdirectories nest one `#` deeper (`## nested/` → `### child.ts`), and each directory's own files are listed before its subdirectories. TUI hyperlink reconstruction tracks the nested directory stack across the whole output so file and code-frame links keep resolving to the correct absolute paths.
+
+### Fixed
+
+- Fixed duplicate file entries in grouped outputs for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics when the same path appeared multiple times
+- Fixed search, grep, and edit output rendering so repeated directory group blank-line boundaries no longer break nested path/link reconstruction
 
 ## [15.10.0] - 2026-06-06
 
@@ -9496,4 +9504,4 @@ Initial public release.
 - Git branch display in footer
 - Message queueing during streaming responses
 - OAuth integration for Gmail and Google Calendar access
-- HTML export with syntax highlighting and collapsible sections
+- HTML export with syntax highlighting and collapsible sections
\ No newline at end of file
diff --git a/packages/coding-agent/src/lsp/utils.ts b/packages/coding-agent/src/lsp/utils.ts
index a2678f975..768d706c2 100644
--- a/packages/coding-agent/src/lsp/utils.ts
+++ b/packages/coding-agent/src/lsp/utils.ts
@@ -153,9 +153,10 @@ export function formatDiagnostic(diagnostic: Diagnostic, filePath: string): stri
 const DIAG_PATH_RE = /^(.+?):(\d+:\d+\s+.*)$/;
 
 /**
- * Reformat pre-formatted diagnostic messages into grep-style directory/file groups.
+ * Reformat pre-formatted diagnostic messages into a multi-level, prefix-folded
+ * directory/file grouping (see `formatGroupedFiles`).
  * Input:  ["path:line:col [sev] msg", ...]
- * Output: "# dir/\n## file.ts\n  line:col [sev] msg"
+ * Output: "# pkg/src/\n## file.ts\n  line:col [sev] msg"
  *
  * Messages that don't match the expected format are appended ungrouped at the end.
  */
diff --git a/packages/coding-agent/src/tools/ast-edit.ts b/packages/coding-agent/src/tools/ast-edit.ts
index 4cc1d9e13..8cf2df79c 100644
--- a/packages/coding-agent/src/tools/ast-edit.ts
+++ b/packages/coding-agent/src/tools/ast-edit.ts
@@ -16,7 +16,7 @@ import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
 import { truncateForPrompt } from "./approval";
 import { createFileRecorder, formatResultPath } from "./file-recorder";
-import { formatGroupedFiles } from "./grouped-file-output";
+import { classifyGroupedLines, formatGroupedFiles, groupLineIndicesByBlank } from "./grouped-file-output";
 import type { OutputMeta } from "./output-meta";
 import { isInternalUrlPath, resolveToolSearchScope } from "./path-utils";
 import {
@@ -30,7 +30,6 @@ import {
 	formatParseErrors,
 	formatParseErrorsCountLabel,
 	PREVIEW_LIMITS,
-	splitGroupsByBlankLine,
 } from "./render-utils";
 import { queueResolveHandler } from "./resolve";
 import { ToolError } from "./tool-errors";
@@ -516,10 +515,30 @@ export const astEditToolRenderer = {
 		const description = rewriteCount === 1 ? args?.ops?.[0]?.pat : undefined;
 
 		const textContent = result.details?.displayContent ?? result.content?.find(c => c.type === "text")?.text ?? "";
-		const allGroups = splitGroupsByBlankLine(textContent.split("\n"));
-		const changeGroups = allGroups.filter(
-			group => !group[0]?.startsWith("Safety cap reached") && !group[0]?.startsWith("Parse issues:"),
-		);
+		const allLines = textContent.split("\n");
+		// Resolve hyperlinks over the whole output so nested directory headers
+		// reconstruct across the blank-line groups the tree list collapses by.
+		const contexts = classifyGroupedLines(allLines, details?.searchPath);
+		const styledLines = allLines.map((line, index) => {
+			const ctx = contexts[index]!;
+			if (ctx.kind === "dir") {
+				const styled = uiTheme.fg("accent", line);
+				return ctx.headerPath ? fileHyperlink(ctx.headerPath, styled) : styled;
+			}
+			if (ctx.kind === "file") {
+				const styled = uiTheme.fg(ctx.depth === 1 ? "accent" : "dim", line);
+				return ctx.headerPath ? fileHyperlink(ctx.headerPath, styled) : styled;
+			}
+			if (line.startsWith("+")) return uiTheme.fg("toolDiffAdded", line);
+			if (line.startsWith("-")) return uiTheme.fg("toolDiffRemoved", line);
+			return uiTheme.fg("toolOutput", line);
+		});
+		const changeGroups = groupLineIndicesByBlank(allLines)
+			.filter(indices => {
+				const first = allLines[indices[0]!]!;
+				return !first.startsWith("Safety cap reached") && !first.startsWith("Parse issues:");
+			})
+			.map(indices => indices.map(index => styledLines[index]!));
 
 		const badge = { label: "proposed", color: "warning" as const };
 		const header = renderStatusLine(
@@ -539,7 +558,6 @@ export const astEditToolRenderer = {
 		return createCachedComponent(
 			() => options.expanded,
 			width => {
-				const searchBase = details?.searchPath;
 				const changeLines = renderTreeList(
 					{
 						items: changeGroups,
@@ -547,43 +565,7 @@ export const astEditToolRenderer = {
 						maxCollapsed: changeGroups.length,
 						maxCollapsedLines: COLLAPSED_CHANGE_LIMIT,
 						itemType: "change",
-						renderItem: group => {
-							let contextDir = searchBase ?? "";
-							return group.map(line => {
-								if (line.startsWith("## ")) {
-									// Strip ` (3 replacements)` and `#hash` suffixes from formatGroupedFiles.
-									const fileName = line
-										.slice(3)
-										.trimEnd()
-										.replace(/\s+\([^)]*\)\s*$/, "")
-										.replace(/#[0-9a-f]+$/, "");
-									const absPath = contextDir && fileName ? path.join(contextDir, fileName) : undefined;
-									const styled = uiTheme.fg("dim", line);
-									return absPath ? fileHyperlink(absPath, styled) : styled;
-								}
-								if (line.startsWith("# ")) {
-									const raw = line
-										.slice(2)
-										.trimEnd()
-										.replace(/\s+\([^)]*\)\s*$/, "");
-									const isDirectory = raw.endsWith("/");
-									const name = isDirectory ? raw.replace(/\/$/, "") : raw.replace(/#[0-9a-f]+$/, "");
-									if (isDirectory) {
-										if (searchBase) {
-											contextDir = name === "." ? searchBase : path.join(searchBase, name);
-										}
-										return uiTheme.fg("accent", line);
-									}
-									// Root-level file with optional `#hash` and ` (3 replacements)` suffixes.
-									const absPath = searchBase && name ? path.join(searchBase, name) : undefined;
-									const styled = uiTheme.fg("accent", line);
-									return absPath ? fileHyperlink(absPath, styled) : styled;
-								}
-								if (line.startsWith("+")) return uiTheme.fg("toolDiffAdded", line);
-								if (line.startsWith("-")) return uiTheme.fg("toolDiffRemoved", line);
-								return uiTheme.fg("toolOutput", line);
-							});
-						},
+						renderItem: group => group,
 					},
 					uiTheme,
 				);
diff --git a/packages/coding-agent/src/tools/ast-grep.ts b/packages/coding-agent/src/tools/ast-grep.ts
index 3354c4af5..7bf277148 100644
--- a/packages/coding-agent/src/tools/ast-grep.ts
+++ b/packages/coding-agent/src/tools/ast-grep.ts
@@ -14,7 +14,7 @@ import { Ellipsis, fileHyperlink, renderStatusLine, renderTreeList, truncateToWi
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
 import { createFileRecorder, formatResultPath } from "./file-recorder";
-import { formatGroupedFiles } from "./grouped-file-output";
+import { classifyGroupedLines, formatGroupedFiles, groupLineIndicesByBlank } from "./grouped-file-output";
 import { formatMatchLine } from "./match-line-format";
 import type { OutputMeta } from "./output-meta";
 import { resolveToolSearchScope } from "./path-utils";
@@ -29,7 +29,6 @@ import {
 	formatParseErrors,
 	formatParseErrorsCountLabel,
 	PREVIEW_LIMITS,
-	splitGroupsByBlankLine,
 } from "./render-utils";
 import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
@@ -386,10 +385,29 @@ export const astGrepToolRenderer = {
 		);
 
 		const textContent = result.details?.displayContent ?? result.content?.find(c => c.type === "text")?.text ?? "";
-		const allGroups = splitGroupsByBlankLine(textContent.split("\n"));
-		const matchGroups = allGroups.filter(
-			group => !group[0]?.startsWith("Result limit reached") && !group[0]?.startsWith("Parse issues:"),
-		);
+		const allLines = textContent.split("\n");
+		// Resolve hyperlinks over the whole output so nested directory headers
+		// reconstruct across the blank-line groups the tree list collapses by.
+		const contexts = classifyGroupedLines(allLines, details?.searchPath);
+		const styledLines = allLines.map((line, index) => {
+			const ctx = contexts[index]!;
+			if (ctx.kind === "dir") {
+				const styled = uiTheme.fg("accent", line);
+				return ctx.headerPath ? fileHyperlink(ctx.headerPath, styled) : styled;
+			}
+			if (ctx.kind === "file") {
+				const styled = uiTheme.fg(ctx.depth === 1 ? "accent" : "dim", line);
+				return ctx.headerPath ? fileHyperlink(ctx.headerPath, styled) : styled;
+			}
+			if (line.startsWith("  meta:")) return uiTheme.fg("dim", line);
+			return uiTheme.fg("toolOutput", line);
+		});
+		const matchGroups = groupLineIndicesByBlank(allLines)
+			.filter(indices => {
+				const first = allLines[indices[0]!]!;
+				return !first.startsWith("Result limit reached") && !first.startsWith("Parse issues:");
+			})
+			.map(indices => indices.map(index => styledLines[index]!));
 
 		const extraLines: string[] = [];
 		if (limitReached) {
@@ -404,7 +422,6 @@ export const astGrepToolRenderer = {
 		return createCachedComponent(
 			() => options.expanded,
 			width => {
-				const searchBase = details?.searchPath;
 				const matchLines = renderTreeList(
 					{
 						items: matchGroups,
@@ -412,41 +429,7 @@ export const astGrepToolRenderer = {
 						maxCollapsed: matchGroups.length,
 						maxCollapsedLines: COLLAPSED_MATCH_LIMIT,
 						itemType: "match",
-						renderItem: group => {
-							let contextDir = searchBase ?? "";
-							return group.map(line => {
-								if (line.startsWith("## ")) {
-									const fileName = line
-										.slice(3)
-										.trimEnd()
-										.replace(/\s+\([^)]*\)\s*$/, "")
-										.replace(/#[0-9a-f]+$/, "");
-									const absPath = contextDir && fileName ? path.join(contextDir, fileName) : undefined;
-									const styled = uiTheme.fg("dim", line);
-									return absPath ? fileHyperlink(absPath, styled) : styled;
-								}
-								if (line.startsWith("# ")) {
-									const raw = line
-										.slice(2)
-										.trimEnd()
-										.replace(/\s+\([^)]*\)\s*$/, "");
-									const isDirectory = raw.endsWith("/");
-									const name = isDirectory ? raw.replace(/\/$/, "") : raw.replace(/#[0-9a-f]+$/, "");
-									if (isDirectory) {
-										if (searchBase) {
-											contextDir = name === "." ? searchBase : path.join(searchBase, name);
-										}
-										return uiTheme.fg("accent", line);
-									}
-									// Root-level file (single # without trailing slash) from formatGroupedFiles.
-									const absPath = searchBase && name ? path.join(searchBase, name) : undefined;
-									const styled = uiTheme.fg("accent", line);
-									return absPath ? fileHyperlink(absPath, styled) : styled;
-								}
-								if (line.startsWith("  meta:")) return uiTheme.fg("dim", line);
-								return uiTheme.fg("toolOutput", line);
-							});
-						},
+						renderItem: group => group,
 					},
 					uiTheme,
 				);
diff --git a/packages/coding-agent/src/tools/find.ts b/packages/coding-agent/src/tools/find.ts
index 85b7bdaf0..4fd0583f9 100644
--- a/packages/coding-agent/src/tools/find.ts
+++ b/packages/coding-agent/src/tools/find.ts
@@ -13,6 +13,7 @@ import findDescription from "../prompts/tools/find.md" with { type: "text" };
 import { type TruncationResult, truncateHead } from "../session/streaming-output";
 import { Ellipsis, fileHyperlink, renderFileList, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import type { ToolSession } from ".";
+import { buildPathTree, walkPathTree } from "./grouped-file-output";
 import { applyListLimit } from "./list-limit";
 import { formatFullOutputReference, type OutputMeta } from "./output-meta";
 import {
@@ -54,34 +55,27 @@ const MIN_GLOB_TIMEOUT_MS = 500;
 const MAX_GLOB_TIMEOUT_MS = 60_000;
 
 /**
- * Group find matches by their directory so the model doesn't pay repeated
- * tokens for shared path prefixes. Preserves the input order: groups appear in
- * the order their first member was emitted (mtime-desc for native glob), and
- * within a group entries keep their relative order.
+ * Group find matches into a multi-level directory tree so the model doesn't pay
+ * repeated tokens for shared path prefixes. Single-child directory chains fold
+ * into one header (`# a/b/c/`), so a common prefix — including an absolute root
+ * for out-of-cwd results — collapses to a single line. Each level adds one `#`;
+ * files are listed bare under the deepest directory header that owns them.
+ *
+ * Order follows the input (mtime-desc for native glob): a directory appears when
+ * its first member is emitted, and a node's own files precede its subdirectories.
  */
 export function formatFindGroupedOutput(paths: readonly string[]): string {
 	if (paths.length === 0) return "";
-	const groups = new Map<string, string[]>();
-	for (const entry of paths) {
-		const hasTrailingSlash = entry.endsWith("/");
-		const trimmed = hasTrailingSlash ? entry.slice(0, -1) : entry;
-		const slash = trimmed.lastIndexOf("/");
-		const dir = slash === -1 ? "" : trimmed.slice(0, slash);
-		const base = slash === -1 ? trimmed : trimmed.slice(slash + 1);
-		const label = hasTrailingSlash ? `${base}/` : base;
-		const list = groups.get(dir);
-		if (list) list.push(label);
-		else groups.set(dir, [label]);
-	}
-	const sections: string[] = [];
-	for (const [dir, entries] of groups) {
-		if (dir === "") {
-			sections.push(entries.join("\n"));
+	const tree = buildPathTree(paths.map(entry => ({ path: entry, isDir: entry.endsWith("/") })));
+	const lines: string[] = [];
+	for (const event of walkPathTree(tree)) {
+		if (event.kind === "dir") {
+			lines.push(`${"#".repeat(event.depth + 1)} ${event.name}/`);
 		} else {
-			sections.push(`# ${dir}/\n${entries.join("\n")}`);
+			lines.push(event.name);
 		}
 	}
-	return sections.join("\n\n");
+	return lines.join("\n");
 }
 
 export interface FindToolDetails {
diff --git a/packages/coding-agent/src/tools/grouped-file-output.ts b/packages/coding-agent/src/tools/grouped-file-output.ts
index 6f27fb9dc..174c0772a 100644
--- a/packages/coding-agent/src/tools/grouped-file-output.ts
+++ b/packages/coding-agent/src/tools/grouped-file-output.ts
@@ -6,10 +6,127 @@ function isUrlLikePath(filePath: string): boolean {
 	return URL_LIKE_PATH_RE.test(filePath);
 }
 
+// =============================================================================
+// Multi-level path tree
+// =============================================================================
+//
+// File listings (grep / ast-grep / ast-edit / lsp diagnostics / find) used to
+// group by the *immediate* parent directory and print the full directory path in
+// every header. For results spread across a deep tree — or rooted outside cwd,
+// where paths stay absolute — that repeated the shared prefix on every line. The
+// tree below folds single-child directory chains (so the common prefix collapses
+// into one header) and nests the rest, charging the model one token per path
+// segment instead of one per file.
+
+interface PathTreeNode {
+	/** Direct file leaves, in first-seen order. */
+	files: Array<{ name: string; key: string }>;
+	/** Dedup set for `files` (a glob can surface the same path twice on retry). */
+	fileNames: Set<string>;
+	/** Child directories, in first-seen order. */
+	subdirs: Array<{ name: string; node: PathTreeNode }>;
+	/** Dedup index for `subdirs`. */
+	dirIndex: Map<string, PathTreeNode>;
+}
+
+export interface PathTreeInput {
+	/** Path string; absolute, cwd-relative, or url-like. Backslashes are normalized. */
+	path: string;
+	/** Whether the leaf itself is a directory (trailing-slash match from find). */
+	isDir: boolean;
+	/** Opaque key carried onto file events for section lookup. Defaults to `path`. */
+	key?: string;
+}
+
+/** One node emitted while walking the tree: a folded directory or a file leaf. */
+export interface GroupedTreeEvent {
+	kind: "dir" | "file";
+	/** 0-based nesting depth (root children are depth 0). */
+	depth: number;
+	/** Folded chain for dirs (e.g. `a/b/c`, no trailing slash); basename for files. */
+	name: string;
+	/** File key for `kind === "file"`; empty string for directories. */
+	key: string;
+}
+
+function createNode(): PathTreeNode {
+	return { files: [], fileNames: new Set(), subdirs: [], dirIndex: new Map() };
+}
+
+function addFile(node: PathTreeNode, name: string, key: string): void {
+	if (node.fileNames.has(name)) return;
+	node.fileNames.add(name);
+	node.files.push({ name, key });
+}
+
+/**
+ * Build a directory tree from a flat list of paths. URL-like entries are kept
+ * whole as root-level file leaves (they have no meaningful directory structure).
+ * Absolute paths carry a leading empty segment so they share a common `/` root
+ * and fold like any other prefix.
+ */
+export function buildPathTree(entries: Iterable<PathTreeInput>): PathTreeNode {
+	const root = createNode();
+	for (const { path: rawPath, isDir, key } of entries) {
+		const normalized = rawPath.replace(/\\/g, "/");
+		const fileKey = key ?? rawPath;
+		if (isUrlLikePath(normalized)) {
+			addFile(root, normalized, fileKey);
+			continue;
+		}
+		const trimmed = normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+		if (trimmed.length === 0) continue;
+		const segments = trimmed.split("/");
+		const dirCount = isDir ? segments.length : segments.length - 1;
+		let node = root;
+		for (let i = 0; i < dirCount; i++) {
+			const segment = segments[i]!;
+			let child = node.dirIndex.get(segment);
+			if (!child) {
+				child = createNode();
+				node.dirIndex.set(segment, child);
+				node.subdirs.push({ name: segment, node: child });
+			}
+			node = child;
+		}
+		if (!isDir) {
+			addFile(node, segments[segments.length - 1]!, fileKey);
+		}
+	}
+	return root;
+}
+
+/**
+ * Depth-first walk yielding directory and file events. Directories collapse their
+ * single-child chains (`a` → `a/b` → `a/b/c`) so a shared prefix becomes one
+ * header. Each node's direct files are emitted before its subdirectories, keeping
+ * a file unambiguously attached to the header above it.
+ */
+export function* walkPathTree(node: PathTreeNode, depth = 0): Generator<GroupedTreeEvent> {
+	for (const file of node.files) {
+		yield { kind: "file", depth, name: file.name, key: file.key };
+	}
+	for (const subdir of node.subdirs) {
+		let dirNode = subdir.node;
+		const parts = [subdir.name];
+		while (dirNode.files.length === 0 && dirNode.subdirs.length === 1) {
+			const only = dirNode.subdirs[0]!;
+			parts.push(only.name);
+			dirNode = only.node;
+		}
+		yield { kind: "dir", depth, name: parts.join("/"), key: "" };
+		yield* walkPathTree(dirNode, depth + 1);
+	}
+}
+
+// =============================================================================
+// Grouped file output (grep / ast-grep / ast-edit / lsp diagnostics)
+// =============================================================================
+
 /**
  * One file's contribution to a grouped file output. The header itself is generated
- * by `formatGroupedFiles` (single `#` for root files, `##` for files inside a dir);
- * use `headerSuffix` to tack on extras like ` (1 replacement)`.
+ * by `formatGroupedFiles` (one `#` per nesting level); use `headerSuffix` to tack
+ * on extras like ` (1 replacement)`.
  */
 export interface GroupedFileSection {
 	/** Optional suffix appended to the file header. */
@@ -28,76 +145,172 @@ export interface GroupedFilesOutput {
 }
 
 /**
- * Render a list of files as directory-grouped sections shared by grep, ast-grep,
- * ast-edit, and the LSP diagnostic formatter.
+ * Render a list of files as a multi-level, prefix-folded directory tree shared by
+ * grep, ast-grep, ast-edit, and the LSP diagnostic formatter.
  *
- * Layout:
- *   # dir/
- *   ## file.ts
+ * Layout (one `#` per level; the shared prefix folds into the top header):
+ *   # packages/pkg/src/
+ *   ## root.ts
+ *   …body…
+ *   ## nested/
+ *   ### child.ts
  *   …body…
  *
- *   # otherdir/
- *   ## other.ts
- *   …body…
- *
- * Files in the project root (directory `.`) become single-`#` headers without a
- * `## file` line, matching the existing convention.
+ * Files in the (folded) project root become single-`#` headers with no parent
+ * directory line. A blank line precedes every directory header and every
+ * root-level file so the renderers can split the output into collapsible groups.
  */
 export function formatGroupedFiles(
 	files: string[],
 	renderFile: (filePath: string) => GroupedFileSection,
 ): GroupedFilesOutput {
-	const filesByDirectory = new Map<string, string[]>();
+	const sections = new Map<string, GroupedFileSection>();
+	const inputs: PathTreeInput[] = [];
 	for (const filePath of files) {
-		const directory = isUrlLikePath(filePath) ? "." : path.dirname(filePath).replace(/\\/g, "/");
-		if (!filesByDirectory.has(directory)) {
-			filesByDirectory.set(directory, []);
-		}
-		filesByDirectory.get(directory)!.push(filePath);
+		if (sections.has(filePath)) continue;
+		const section = renderFile(filePath);
+		if (section.skip) continue;
+		sections.set(filePath, section);
+		inputs.push({ path: filePath, isDir: false, key: filePath });
 	}
 
+	const tree = buildPathTree(inputs);
 	const model: string[] = [];
 	const display: string[] = [];
+	let emitted = false;
 
-	const pushSeparatorIfNeeded = () => {
-		if (model.length > 0) {
+	for (const event of walkPathTree(tree)) {
+		const hashes = "#".repeat(event.depth + 1);
+		const needsSeparator = emitted && (event.depth === 0 || event.kind === "dir");
+		if (needsSeparator) {
 			model.push("");
 			display.push("");
 		}
-	};
-
-	for (const [directory, dirFiles] of filesByDirectory) {
-		if (directory === ".") {
-			for (const filePath of dirFiles) {
-				const section = renderFile(filePath);
-				if (section.skip) continue;
-				pushSeparatorIfNeeded();
-				const headerName = isUrlLikePath(filePath) ? filePath : path.basename(filePath);
-				const header = `# ${headerName}${section.headerSuffix ?? ""}`;
-				model.push(header, ...section.modelLines);
-				display.push(header, ...(section.displayLines ?? section.modelLines));
-			}
+		emitted = true;
+		if (event.kind === "dir") {
+			const header = `${hashes} ${event.name}/`;
+			model.push(header);
+			display.push(header);
 			continue;
 		}
-
-		const sections: Array<{ filePath: string; section: GroupedFileSection }> = [];
-		for (const filePath of dirFiles) {
-			const section = renderFile(filePath);
-			if (section.skip) continue;
-			sections.push({ filePath, section });
-		}
-		if (sections.length === 0) continue;
-
-		pushSeparatorIfNeeded();
-		const dirHeader = `# ${directory}/`;
-		model.push(dirHeader);
-		display.push(dirHeader);
-		for (const { filePath, section } of sections) {
-			const fileHeader = `## ${path.basename(filePath)}${section.headerSuffix ?? ""}`;
-			model.push(fileHeader, ...section.modelLines);
-			display.push(fileHeader, ...(section.displayLines ?? section.modelLines));
-		}
+		const section = sections.get(event.key)!;
+		const header = `${hashes} ${event.name}${section.headerSuffix ?? ""}`;
+		model.push(header, ...section.modelLines);
+		display.push(header, ...(section.displayLines ?? section.modelLines));
 	}
 
 	return { model, display };
 }
+
+// =============================================================================
+// Parsing grouped output back into per-line context (TUI renderers)
+// =============================================================================
+
+const GROUPED_HEADER_RE = /^(#+)\s+(.*)$/;
+const HEADER_SUFFIX_RE = /\s+\([^)]*\)\s*$/;
+const HEADER_HASH_TAG_RE = /#[0-9a-f]+$/i;
+
+/** Per-line classification of grouped output, used by renderers for hyperlinks. */
+export interface GroupedLineContext {
+	/** Directory header, file header, or any non-header body/content line. */
+	kind: "dir" | "file" | "content";
+	/** Number of leading `#` for headers; 0 for content lines. */
+	depth: number;
+	/** Resolved absolute path of the dir/file a header points at (when resolvable). */
+	headerPath?: string;
+	/** For content lines, the absolute path of the owning file (line hyperlinks). */
+	filePath?: string;
+	/** Header is an internal/url-like target the caller resolves itself. */
+	isUrl?: boolean;
+}
+
+function resolveGroupedPath(parent: string | undefined, name: string): string | undefined {
+	if (parent === undefined) return undefined;
+	if (name === "" || name === ".") return parent;
+	// `path.resolve` keeps an absolute `name` intact (out-of-cwd results) while
+	// joining a relative folded chain (`packages/pkg/src`) onto the parent.
+	return path.resolve(parent, name);
+}
+
+/**
+ * Walk grouped output lines, tracking a directory stack keyed by header depth, so
+ * each header and body line can be linked back to its absolute filesystem path.
+ * Reconstruction is stack-based (not per-blank-group) so nested directory headers
+ * resolve correctly across the whole output.
+ */
+export function classifyGroupedLines(lines: readonly string[], searchBase: string | undefined): GroupedLineContext[] {
+	const result: GroupedLineContext[] = [];
+	const dirAtDepth = new Map<number, string>();
+	// Body lines before any header (single-file scopes) link to the search root.
+	let currentFile = searchBase;
+
+	const clearDeeper = (depth: number) => {
+		for (const key of dirAtDepth.keys()) {
+			if (key >= depth) dirAtDepth.delete(key);
+		}
+	};
+
+	for (const line of lines) {
+		const match = GROUPED_HEADER_RE.exec(line);
+		if (!match) {
+			result.push({ kind: "content", depth: 0, filePath: currentFile });
+			continue;
+		}
+		const depth = match[1]!.length;
+		const rest = match[2]!.trimEnd();
+		if (isUrlLikePath(rest)) {
+			clearDeeper(depth);
+			currentFile = undefined;
+			result.push({ kind: "file", depth, isUrl: true });
+			continue;
+		}
+		const parent = depth > 1 ? dirAtDepth.get(depth - 1) : searchBase;
+		if (rest.endsWith("/")) {
+			const name = rest.slice(0, -1).replace(HEADER_SUFFIX_RE, "");
+			const abs = resolveGroupedPath(parent, name);
+			clearDeeper(depth);
+			if (abs !== undefined) dirAtDepth.set(depth, abs);
+			currentFile = undefined;
+			result.push({ kind: "dir", depth, headerPath: abs });
+			continue;
+		}
+		const name = rest.replace(HEADER_SUFFIX_RE, "").replace(HEADER_HASH_TAG_RE, "");
+		const abs = name ? resolveGroupedPath(parent, name) : undefined;
+		currentFile = abs;
+		result.push({ kind: "file", depth, headerPath: abs });
+	}
+
+	return result;
+}
+
+/**
+ * Split line indices into blank-line-separated groups, mirroring
+ * `splitGroupsByBlankLine`: when any blank line is present, break on runs of
+ * blanks; otherwise return a single group of the non-empty lines. Returning
+ * indices lets callers slice parallel arrays (raw lines, styled lines, contexts).
+ */
+export function groupLineIndicesByBlank(rawLines: readonly string[]): number[][] {
+	const hasSeparators = rawLines.some(line => line.trim().length === 0);
+	const groups: number[][] = [];
+	if (hasSeparators) {
+		let current: number[] = [];
+		for (let i = 0; i < rawLines.length; i++) {
+			if (rawLines[i]!.trim().length === 0) {
+				if (current.length > 0) {
+					groups.push(current);
+					current = [];
+				}
+				continue;
+			}
+			current.push(i);
+		}
+		if (current.length > 0) groups.push(current);
+	} else {
+		const current: number[] = [];
+		for (let i = 0; i < rawLines.length; i++) {
+			if (rawLines[i]!.trim().length > 0) current.push(i);
+		}
+		if (current.length > 0) groups.push(current);
+	}
+	return groups;
+}
diff --git a/packages/coding-agent/src/tools/render-utils.ts b/packages/coding-agent/src/tools/render-utils.ts
index b96931dae..0548d56bf 100644
--- a/packages/coding-agent/src/tools/render-utils.ts
+++ b/packages/coding-agent/src/tools/render-utils.ts
@@ -736,36 +736,6 @@ export function capParseErrors(
 // Renderer helpers shared by search / find / ast tools
 // =============================================================================
 
-/**
- * Group `rawLines` by blank-line separators, mirroring the historical search /
- * ast-grep / ast-edit renderer behavior: if any blank line is present, splits on
- * runs of blank lines; otherwise collapses non-empty lines into a single group.
- */
-export function splitGroupsByBlankLine(rawLines: string[]): string[][] {
-	const hasSeparators = rawLines.some(line => line.trim().length === 0);
-	const groups: string[][] = [];
-	if (hasSeparators) {
-		let current: string[] = [];
-		for (const line of rawLines) {
-			if (line.trim().length === 0) {
-				if (current.length > 0) {
-					groups.push(current);
-					current = [];
-				}
-				continue;
-			}
-			current.push(line);
-		}
-		if (current.length > 0) groups.push(current);
-	} else {
-		const nonEmpty = rawLines.filter(line => line.trim().length > 0);
-		if (nonEmpty.length > 0) {
-			groups.push(nonEmpty);
-		}
-	}
-	return groups;
-}
-
 /**
  * Standard width+expand keyed render cache used by every search-style tool
  * renderer. `compute` re-runs only when the cache key changes; the returned
diff --git a/packages/coding-agent/src/tools/search.ts b/packages/coding-agent/src/tools/search.ts
index d74a35726..0c3a76ff2 100644
--- a/packages/coding-agent/src/tools/search.ts
+++ b/packages/coding-agent/src/tools/search.ts
@@ -36,7 +36,7 @@ import {
 	parseArchivePathCandidates,
 } from "./archive-reader";
 import { createFileRecorder, formatResultPath } from "./file-recorder";
-import { formatGroupedFiles } from "./grouped-file-output";
+import { classifyGroupedLines, formatGroupedFiles, groupLineIndicesByBlank } from "./grouped-file-output";
 import { formatMatchLine } from "./match-line-format";
 import type { OutputMeta } from "./output-meta";
 import {
@@ -61,7 +61,6 @@ import {
 	formatMoreItems,
 	PREVIEW_LIMITS,
 	replaceTabs,
-	splitGroupsByBlankLine,
 } from "./render-utils";
 import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
@@ -287,7 +286,6 @@ interface IndexedContentLines {
 	starts: number[];
 }
 
-const INTERNAL_URL_DISPLAY_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
 const OMP_ROOT_URL_RE = /^omp:\/\/(?:\/?|docs\/?)$/i;
 
 function normalizeSearchLine(line: string): string {
@@ -1210,69 +1208,48 @@ function isSearchMatchLine(line: string): boolean {
 }
 
 function isSearchHeaderLine(line: string): boolean {
-	return line.startsWith("# ") || line.startsWith("## ");
+	return /^#+ /.test(line);
 }
 
-function renderSearchDisplayGroup(
-	group: string[],
+const URL_HEADER_PREFIX_RE = /^#+\s+/;
+
+function renderSearchDisplayLines(
+	lines: readonly string[],
 	searchBase: string | undefined,
 	uiTheme: Theme,
 ): RenderedSearchLine[] {
-	// Track directory/file context within a group so headers and code-frame
-	// lines link to the backing file, with line-specific links for matches.
-	let contextDir = searchBase ?? "";
-	const hasFileHeader = group.some(line => line.startsWith("# "));
-	let currentFilePath: string | undefined = hasFileHeader ? undefined : searchBase;
-	return group.map(line => {
-		if (line.startsWith("## ")) {
-			// Strip optional ` (suffix)` and `#hash` before resolving.
-			const fileName = line
-				.slice(3)
-				.trimEnd()
-				.replace(/\s+\([^)]*\)\s*$/, "")
-				.replace(/#[0-9a-f]+$/, "");
-			const absPath = contextDir && fileName ? path.join(contextDir, fileName) : undefined;
-			currentFilePath = absPath;
-			const styled = uiTheme.fg("dim", line);
-			return { raw: line, styled: absPath ? fileHyperlink(absPath, styled) : styled };
+	const contexts = classifyGroupedLines(lines, searchBase);
+	// `classifyGroupedLines` can't resolve internal URLs (TUI-only), so track the
+	// resolved URL target here and use it for the body lines that follow.
+	let urlFile: string | undefined;
+	return lines.map((line, index) => {
+		const ctx = contexts[index]!;
+		if (ctx.kind === "dir") {
+			urlFile = undefined;
+			const styled = uiTheme.fg("accent", line);
+			return { raw: line, styled: ctx.headerPath ? fileHyperlink(ctx.headerPath, styled) : styled };
 		}
-		if (line.startsWith("# ")) {
-			const raw = line
-				.slice(2)
-				.trimEnd()
-				.replace(/\s+\([^)]*\)\s*$/, "");
-			if (INTERNAL_URL_DISPLAY_RE.test(raw)) {
-				contextDir = "";
-				const styled = uiTheme.fg("accent", line);
-				const linked = linkUrlLikeSearchHeader(raw, styled);
-				currentFilePath = linked.absPath;
+		if (ctx.kind === "file") {
+			if (ctx.isUrl) {
+				const raw = line
+					.replace(URL_HEADER_PREFIX_RE, "")
+					.trimEnd()
+					.replace(/\s+\([^)]*\)\s*$/, "");
+				const linked = linkUrlLikeSearchHeader(raw, uiTheme.fg("accent", line));
+				urlFile = linked.absPath;
 				return { raw: line, styled: linked.line };
 			}
-			const isDirectory = raw.endsWith("/");
-			const name = isDirectory ? raw.replace(/\/$/, "") : raw.replace(/#[0-9a-f]+$/, "");
-			if (isDirectory) {
-				const absPath = searchBase ? (name === "." ? searchBase : path.join(searchBase, name)) : undefined;
-				if (absPath) {
-					contextDir = absPath;
-				}
-				currentFilePath = undefined;
-				const styled = uiTheme.fg("accent", line);
-				return { raw: line, styled: absPath ? fileHyperlink(absPath, styled) : styled };
-			}
-			// Root-level file emitted by formatGroupedFiles when the directory is `.`.
-			const absPath = searchBase && name ? path.join(searchBase, name) : undefined;
-			currentFilePath = absPath;
-			const styled = uiTheme.fg("accent", line);
-			return { raw: line, styled: absPath ? fileHyperlink(absPath, styled) : styled };
+			urlFile = undefined;
+			// Root-level files keep the bright accent; nested file headers are dimmed.
+			const styled = uiTheme.fg(ctx.depth === 1 ? "accent" : "dim", line);
+			return { raw: line, styled: ctx.headerPath ? fileHyperlink(ctx.headerPath, styled) : styled };
 		}
 		const styled = uiTheme.fg("toolOutput", line);
 		const lineNumber = parseSearchDisplayLineNumber(line);
+		const filePath = ctx.filePath ?? urlFile;
 		return {
 			raw: line,
-			styled:
-				currentFilePath && lineNumber !== undefined
-					? fileHyperlink(currentFilePath, styled, { line: lineNumber })
-					: styled,
+			styled: filePath && lineNumber !== undefined ? fileHyperlink(filePath, styled, { line: lineNumber }) : styled,
 		};
 	});
 }
@@ -1288,19 +1265,15 @@ function countPreviewMatches(lines: readonly RenderedSearchLine[], hasMarkedMatc
 }
 
 function renderBudgetedSearchGroups(
-	groups: string[][],
+	groups: RenderedSearchLine[][],
 	maxLines: number,
 	matchCount: number,
-	searchBase: string | undefined,
 	uiTheme: Theme,
 	compact: boolean,
 ): string[] {
 	if (maxLines <= 0) return [];
 	const renderedGroups = groups
-		.map(group => {
-			const rendered = renderSearchDisplayGroup(group, searchBase, uiTheme);
-			return compact ? compactSearchPreviewGroup(rendered) : rendered;
-		})
+		.map(group => (compact ? compactSearchPreviewGroup(group) : group))
 		.filter(group => group.length > 0);
 	if (renderedGroups.length === 0) return [];
 
@@ -1451,7 +1424,11 @@ export const searchToolRenderer = {
 		);
 
 		const textContent = result.details?.displayContent ?? result.content?.find(c => c.type === "text")?.text ?? "";
-		const matchGroups = splitGroupsByBlankLine(textContent.split("\n"));
+		const allLines = textContent.split("\n");
+		// Resolve hyperlinks once over the whole output so a nested directory stack
+		// reconstructs correctly across blank-line group boundaries.
+		const renderedLines = renderSearchDisplayLines(allLines, details?.searchPath, uiTheme);
+		const matchGroups = groupLineIndicesByBlank(allLines).map(indices => indices.map(i => renderedLines[i]!));
 
 		const extraLines: string[] = [];
 		if (missingNote) extraLines.push(missingNote);
@@ -1463,15 +1440,7 @@ export const searchToolRenderer = {
 					(options.expanded ? EXPANDED_TEXT_LIMIT : COLLAPSED_TEXT_LIMIT) - extraLines.length,
 					0,
 				);
-				const searchBase = details?.searchPath;
-				const matchLines = renderBudgetedSearchGroups(
-					matchGroups,
-					budget,
-					matchCount,
-					searchBase,
-					uiTheme,
-					!options.expanded,
-				);
+				const matchLines = renderBudgetedSearchGroups(matchGroups, budget, matchCount, uiTheme, !options.expanded);
 				return [header, ...matchLines, ...extraLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
 			},
 		);
diff --git a/packages/coding-agent/test/tools/ast-edit.test.ts b/packages/coding-agent/test/tools/ast-edit.test.ts
index 5262909e1..64bf976a6 100644
--- a/packages/coding-agent/test/tools/ast-edit.test.ts
+++ b/packages/coding-agent/test/tools/ast-edit.test.ts
@@ -211,9 +211,10 @@ describe("ast_edit tool schema", () => {
 				| { totalReplacements?: number; fileReplacements?: Array<{ path: string; count: number }> }
 				| undefined;
 
-			// Tree-grouped output: `# packages/pkg-…/src/` then `## root.ts#<hash> (1 replacement)`.
+			// Multi-level tree output: `# packages/pkg-…/src/`, `## root.ts#<hash>`, then a
+			// nested `## nested/` directory with `### child.ts#<hash>` under it.
 			expect(text).toMatch(/^## root\.ts#[0-9A-F]{4} \(\d+ replacement[s]?\)$/m);
-			expect(text).toMatch(/^## child\.ts#[0-9A-F]{4} \(\d+ replacement[s]?\)$/m);
+			expect(text).toMatch(/^### child\.ts#[0-9A-F]{4} \(\d+ replacement[s]?\)$/m);
 			expect(text).not.toContain("ignore.js");
 			expect(text).not.toContain("outside.ts");
 			expect(details?.totalReplacements).toBe(2);
diff --git a/packages/coding-agent/test/tools/ast-grep.test.ts b/packages/coding-agent/test/tools/ast-grep.test.ts
index b70a139de..f584859dd 100644
--- a/packages/coding-agent/test/tools/ast-grep.test.ts
+++ b/packages/coding-agent/test/tools/ast-grep.test.ts
@@ -100,9 +100,10 @@ describe("ast_grep parse errors", () => {
 			const text = result.content.find(content => content.type === "text")?.text ?? "";
 			const details = result.details as { matchCount?: number; fileCount?: number } | undefined;
 
-			// Directory mode uses tree-grouped `# dir/` + `## name#hash` headers.
-			expect(text).toMatch(/## root\.ts#[0-9A-F]{4}/);
-			expect(text).toMatch(/## child\.ts#[0-9A-F]{4}/);
+			// Multi-level tree output: `# packages/pkg-…/src/`, `## root.ts#<hash>`, then a
+			// nested `## nested/` directory with `### child.ts#<hash>` under it.
+			expect(text).toMatch(/^## root\.ts#[0-9A-F]{4}/m);
+			expect(text).toMatch(/^### child\.ts#[0-9A-F]{4}/m);
 			expect(text).not.toContain("ignore.js");
 			expect(text).not.toContain("outside.ts");
 			expect(details?.matchCount).toBe(2);
diff --git a/packages/coding-agent/test/tools/grouped-file-output.test.ts b/packages/coding-agent/test/tools/grouped-file-output.test.ts
new file mode 100644
index 000000000..d9cf45db2
--- /dev/null
+++ b/packages/coding-agent/test/tools/grouped-file-output.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "bun:test";
+import { formatFindGroupedOutput } from "../../src/tools/find";
+import { classifyGroupedLines, formatGroupedFiles, groupLineIndicesByBlank } from "../../src/tools/grouped-file-output";
+
+describe("formatFindGroupedOutput", () => {
+	it("folds a shared absolute prefix into one heading and nests the rest", () => {
+		const output = formatFindGroupedOutput([
+			"/Users/me/proj/shared/wasm/llvm.hpp",
+			"/Users/me/proj/shared/wasm/vm.hpp",
+			"/Users/me/proj/shared/xstd.hpp",
+			"/Users/me/proj/shared/apollo/details/hash.hpp",
+			"/Users/me/proj/flash/main.cpp",
+		]);
+
+		expect(output).toBe(
+			[
+				"# /Users/me/proj/",
+				"## shared/",
+				"xstd.hpp",
+				"### wasm/",
+				"llvm.hpp",
+				"vm.hpp",
+				"### apollo/details/",
+				"hash.hpp",
+				"## flash/",
+				"main.cpp",
+			].join("\n"),
+		);
+	});
+
+	it("lists a directory's own files before its subdirectories", () => {
+		const output = formatFindGroupedOutput(["pkg/sub/deep.txt", "pkg/top.txt"]);
+		// `top.txt` is a direct child of pkg; `sub/` is a subdirectory. Files first.
+		expect(output).toBe(["# pkg/", "top.txt", "## sub/", "deep.txt"].join("\n"));
+	});
+
+	it("emits a single root-level file with no directory heading", () => {
+		expect(formatFindGroupedOutput(["single.txt"])).toBe("single.txt");
+	});
+
+	it("keeps matched directories (trailing slash) as headings", () => {
+		expect(formatFindGroupedOutput(["alpha/tests/", "beta/tests/"])).toBe(
+			["# alpha/tests/", "# beta/tests/"].join("\n"),
+		);
+	});
+});
+
+describe("formatGroupedFiles", () => {
+	it("nests subdirectories with deeper headings and blank-separates top groups", () => {
+		const { model } = formatGroupedFiles(["pkg/ai/CHANGELOG.md", "pkg/ai/src/util/x.ts", "README.md"], file => ({
+			modelLines: [`  ${file}`],
+			headerSuffix: " (1)",
+		}));
+
+		expect(model).toEqual([
+			"# README.md (1)",
+			"  README.md",
+			"",
+			"# pkg/ai/",
+			"## CHANGELOG.md (1)",
+			"  pkg/ai/CHANGELOG.md",
+			"",
+			"## src/util/",
+			"### x.ts (1)",
+			"  pkg/ai/src/util/x.ts",
+		]);
+	});
+
+	it("omits skipped files and their now-empty directories", () => {
+		const { model } = formatGroupedFiles(["a/keep.ts", "a/drop.ts"], file => ({
+			modelLines: [`  ${file}`],
+			skip: file.endsWith("drop.ts"),
+		}));
+		expect(model).toEqual(["# a/", "## keep.ts", "  a/keep.ts"]);
+	});
+});
+
+describe("classifyGroupedLines", () => {
+	it("reconstructs absolute paths across a nested directory stack", () => {
+		const lines = ["# pkg/ai/", "## CHANGELOG.md", "  match", "## src/util/", "### x.ts", "*12│const y = 1;"];
+		const ctx = classifyGroupedLines(lines, "/repo");
+
+		expect(ctx[0]).toMatchObject({ kind: "dir", headerPath: "/repo/pkg/ai" });
+		expect(ctx[1]).toMatchObject({ kind: "file", headerPath: "/repo/pkg/ai/CHANGELOG.md" });
+		expect(ctx[2]).toMatchObject({ kind: "content", filePath: "/repo/pkg/ai/CHANGELOG.md" });
+		// `src/util/` is a folded subdirectory chain under `pkg/ai/`, not the root.
+		expect(ctx[3]).toMatchObject({ kind: "dir", headerPath: "/repo/pkg/ai/src/util" });
+		expect(ctx[4]).toMatchObject({ kind: "file", headerPath: "/repo/pkg/ai/src/util/x.ts" });
+		expect(ctx[5]).toMatchObject({ kind: "content", filePath: "/repo/pkg/ai/src/util/x.ts" });
+	});
+
+	it("keeps an absolute folded prefix instead of joining it onto the search base", () => {
+		const ctx = classifyGroupedLines(["# /outside/dir/", "## file.txt"], "/repo");
+		expect(ctx[0]).toMatchObject({ kind: "dir", headerPath: "/outside/dir" });
+		expect(ctx[1]).toMatchObject({ kind: "file", headerPath: "/outside/dir/file.txt" });
+	});
+
+	it("links body lines before any header to the single-file search base", () => {
+		const ctx = classifyGroupedLines(["*7│needle();"], "/repo/file.ts");
+		expect(ctx[0]).toMatchObject({ kind: "content", filePath: "/repo/file.ts" });
+	});
+
+	it("flags url-like headers for caller-side resolution without a filesystem path", () => {
+		const ctx = classifyGroupedLines(["# omp://docs/", "  body"], "/repo");
+		expect(ctx[0]).toMatchObject({ kind: "file", isUrl: true });
+		expect(ctx[0]?.headerPath).toBeUndefined();
+	});
+});
+
+describe("groupLineIndicesByBlank", () => {
+	it("breaks on blank-line runs and keeps original indices", () => {
+		expect(groupLineIndicesByBlank(["a", "b", "", "", "c"])).toEqual([[0, 1], [4]]);
+	});
+
+	it("returns a single group of non-empty lines when no blanks are present", () => {
+		expect(groupLineIndicesByBlank(["a", "b", "c"])).toEqual([[0, 1, 2]]);
+	});
+});

From 38ffd47e3519a2d12e3691fabdfda752ce8dee96 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 02:36:10 +0200
Subject: [PATCH 073/181] fix(dry-balance): fixed bench progress staircasing in
 raw-mode tty

- Anchored each redraw at column 0 and terminated rows with CRLF instead of bare LF.
- Capped each line to terminal width so wrapping cannot desync the cursor-up.
- Threaded stdout/stderr columns into the progress sink.
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 .../coding-agent/src/cli/dry-balance-cli.ts   | 22 +++++++++++++++----
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 1e4be8e85..444f73141 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -9,6 +9,7 @@
 
 - Fixed duplicate file entries in grouped outputs for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics when the same path appeared multiple times
 - Fixed search, grep, and edit output rendering so repeated directory group blank-line boundaries no longer break nested path/link reconstruction
+- Fixed `omp dry-balance --bench` flooding the terminal with staircased, duplicated spinner/status lines (and an indented summary) when the tty has ONLCR/OPOST disabled (raw mode). The interactive progress region separated rows with a bare LF and repositioned with a column-preserving `\x1b[<n>A` cursor-up, both of which only land at column 0 when the terminal translates LF→CRLF; with that translation off, every 80 ms redraw cascaded down and to the right into scrollback. The live region now carriage-returns before every cleared row, terminates each row with CRLF, and caps each row to the terminal width so a wrapped line cannot desync the cursor-up from the logical line count.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/coding-agent/src/cli/dry-balance-cli.ts b/packages/coding-agent/src/cli/dry-balance-cli.ts
index dc35d254f..b667b0454 100644
--- a/packages/coding-agent/src/cli/dry-balance-cli.ts
+++ b/packages/coding-agent/src/cli/dry-balance-cli.ts
@@ -152,6 +152,8 @@ export interface DryBalanceDependencies {
 	now?: () => number;
 	stdoutIsTTY?: boolean;
 	stderrIsTTY?: boolean;
+	stdoutColumns?: number;
+	stderrColumns?: number;
 }
 
 type DryBalanceAttemptResult =
@@ -310,10 +312,11 @@ function renderBenchStatusLine(
 	}
 }
 
-function createBenchProgressSink(
+export function createBenchProgressSink(
 	total: number,
 	write: (text: string) => void,
 	interactive: boolean,
+	columns: number,
 ): DryBalanceBenchProgressSink {
 	const statuses: DryBalanceBenchProgressStatus[] = Array.from({ length: total }, () => ({ state: "waiting" }));
 	if (!interactive) {
@@ -333,13 +336,21 @@ function createBenchProgressSink(
 	let frame = 0;
 	let lineCount = 0;
 	let timer: NodeJS.Timeout | undefined;
+	const width = Number.isFinite(columns) && columns > 0 ? Math.trunc(columns) : 80;
 	const render = (): void => {
 		const lines = [
 			chalk.bold("bench requests"),
 			...statuses.map((status, index) => renderBenchStatusLine(status, index, total, frame)),
 		];
-		if (lineCount > 0) write(`\x1b[${lineCount}A`);
-		write(`${lines.map(line => `\x1b[2K${line}`).join("\n")}\n`);
+		// Anchor every redraw at column 0 and terminate each row with CRLF: a
+		// bare `\n` only returns to column 0 when the tty performs ONLCR
+		// translation, which is off whenever the terminal is in raw mode — there
+		// the old column-preserving cursor-up staircased each frame into
+		// scrollback. Cap each line to the terminal width so a wrapped row never
+		// desyncs the `\x1b[<n>A` cursor-up from the logical line count.
+		const move = lineCount > 0 ? `\x1b[${lineCount}A` : "";
+		const body = lines.map(line => `\x1b[2K${truncateToWidth(line, width)}`).join("\r\n");
+		write(`${move}\r${body}\r\n`);
 		lineCount = lines.length;
 	};
 	render();
@@ -792,7 +803,10 @@ export async function runDryBalanceCommand(
 			const progressInteractive = command.flags.json
 				? (deps.stderrIsTTY ?? process.stderr.isTTY === true)
 				: (deps.stdoutIsTTY ?? process.stdout.isTTY === true);
-			progress = createBenchProgressSink(targets.length, progressWrite, progressInteractive);
+			const progressColumns = command.flags.json
+				? (deps.stderrColumns ?? process.stderr.columns ?? 80)
+				: (deps.stdoutColumns ?? process.stdout.columns ?? 80);
+			progress = createBenchProgressSink(targets.length, progressWrite, progressInteractive, progressColumns);
 			benchResults = await runBenchTargets(model, targets, randomSessionId, progress, streamFn, now);
 			results = targets.map(target =>
 				target.ok ? { ok: true, account: target.account } : { ok: false, reason: target.error },

From 65847589115f16590d070c23e5de87a5a0f92eda Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 02:37:41 +0200
Subject: [PATCH 074/181] feat(copy): added quote block extraction to /copy
 targets

- Replaced regex code-block parser with line scanner masking fences.
- Exposed `>`-quoted runs as drillable copy targets per message.
- Added combined "all quotes" target when multiple quotes exist.
---
 .../src/modes/components/copy-selector.ts     |  44 +----
 .../src/modes/components/overlay-box.ts       |  53 ++++++
 .../src/modes/utils/copy-targets.ts           | 159 +++++++++++++++---
 .../test/modes/utils/copy-targets.test.ts     |  49 ++++++
 4 files changed, 235 insertions(+), 70 deletions(-)
 create mode 100644 packages/coding-agent/src/modes/components/overlay-box.ts

diff --git a/packages/coding-agent/src/modes/components/copy-selector.ts b/packages/coding-agent/src/modes/components/copy-selector.ts
index 5628b1e67..08f925df0 100644
--- a/packages/coding-agent/src/modes/components/copy-selector.ts
+++ b/packages/coding-agent/src/modes/components/copy-selector.ts
@@ -10,6 +10,7 @@ import {
 	matchesSelectUp,
 } from "../utils/keybinding-matchers";
 import { keyHint, rawKeyHint } from "./keybinding-hints";
+import { bottomBorder, divider, row, topBorder } from "./overlay-box";
 
 /** Minimum rows reserved for the tree even on short terminals. */
 const MIN_TREE_ROWS = 3;
@@ -32,49 +33,6 @@ interface FlatNode {
 	ancestorHasNext: boolean[];
 }
 
-/** Pad or truncate a (possibly ANSI-styled) string to exactly `width` columns. */
-function fit(text: string, width: number): string {
-	if (width <= 0) return "";
-	const w = visibleWidth(text);
-	if (w === width) return text;
-	if (w < width) return text + padding(width - w);
-	const cut = truncateToWidth(text, width);
-	const cw = visibleWidth(cut);
-	return cw < width ? cut + padding(width - cw) : cut;
-}
-
-function paint(s: string): string {
-	return theme.fg("border", s);
-}
-
-function topBorder(width: number, title: string): string {
-	const box = theme.boxSharp;
-	const inner = Math.max(0, width - 2);
-	if (!title) return paint(box.topLeft + box.horizontal.repeat(inner) + box.topRight);
-	const shown = truncateToWidth(` ${title} `, Math.max(0, inner - 2));
-	const fillWidth = Math.max(0, inner - 1 - visibleWidth(shown));
-	return (
-		paint(box.topLeft + box.horizontal) +
-		theme.bold(theme.fg("accent", shown)) +
-		paint(box.horizontal.repeat(fillWidth) + box.topRight)
-	);
-}
-
-function divider(width: number): string {
-	const box = theme.boxSharp;
-	return paint(box.teeRight + box.horizontal.repeat(Math.max(0, width - 2)) + box.teeLeft);
-}
-
-function bottomBorder(width: number): string {
-	const box = theme.boxSharp;
-	return paint(box.bottomLeft + box.horizontal.repeat(Math.max(0, width - 2)) + box.bottomRight);
-}
-
-/** Wrap pre-styled content in vertical borders with single-column insets. */
-function row(content: string, width: number): string {
-	const box = theme.boxSharp;
-	return `${paint(box.vertical)} ${fit(content, Math.max(0, width - 4))} ${paint(box.vertical)}`;
-}
 
 /** Render one tree connector as exactly three cells (e.g. "├─ ", "└─ ", "|--"). */
 function connectorCells(symbol: string): string {
diff --git a/packages/coding-agent/src/modes/components/overlay-box.ts b/packages/coding-agent/src/modes/components/overlay-box.ts
new file mode 100644
index 000000000..52b9f2dc0
--- /dev/null
+++ b/packages/coding-agent/src/modes/components/overlay-box.ts
@@ -0,0 +1,53 @@
+/**
+ * Shared box-drawing chrome for fullscreen overlays (the `/copy` picker, the
+ * plan-review overlay, …). Every helper paints with `theme.boxSharp` glyphs and
+ * the `border`/`accent` theme colors so all outlined overlays read identically.
+ */
+import { padding, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
+import { theme } from "../theme/theme";
+
+/** Pad or truncate a (possibly ANSI-styled) string to exactly `width` columns. */
+export function fit(text: string, width: number): string {
+	if (width <= 0) return "";
+	const w = visibleWidth(text);
+	if (w === width) return text;
+	if (w < width) return text + padding(width - w);
+	const cut = truncateToWidth(text, width);
+	const cw = visibleWidth(cut);
+	return cw < width ? cut + padding(width - cw) : cut;
+}
+
+function paint(s: string): string {
+	return theme.fg("border", s);
+}
+
+/** Top border with an optional accent-colored title inset into the rule. */
+export function topBorder(width: number, title: string): string {
+	const box = theme.boxSharp;
+	const inner = Math.max(0, width - 2);
+	if (!title) return paint(box.topLeft + box.horizontal.repeat(inner) + box.topRight);
+	const shown = truncateToWidth(` ${title} `, Math.max(0, inner - 2));
+	const fillWidth = Math.max(0, inner - 1 - visibleWidth(shown));
+	return (
+		paint(box.topLeft + box.horizontal) +
+		theme.bold(theme.fg("accent", shown)) +
+		paint(box.horizontal.repeat(fillWidth) + box.topRight)
+	);
+}
+
+/** A horizontal rule with left/right tees, splitting overlay sections. */
+export function divider(width: number): string {
+	const box = theme.boxSharp;
+	return paint(box.teeRight + box.horizontal.repeat(Math.max(0, width - 2)) + box.teeLeft);
+}
+
+export function bottomBorder(width: number): string {
+	const box = theme.boxSharp;
+	return paint(box.bottomLeft + box.horizontal.repeat(Math.max(0, width - 2)) + box.bottomRight);
+}
+
+/** Wrap pre-styled content in vertical borders with single-column insets. */
+export function row(content: string, width: number): string {
+	const box = theme.boxSharp;
+	return `${paint(box.vertical)} ${fit(content, Math.max(0, width - 4))} ${paint(box.vertical)}`;
+}
diff --git a/packages/coding-agent/src/modes/utils/copy-targets.ts b/packages/coding-agent/src/modes/utils/copy-targets.ts
index 7fd32d4d6..5da1f9ebe 100644
--- a/packages/coding-agent/src/modes/utils/copy-targets.ts
+++ b/packages/coding-agent/src/modes/utils/copy-targets.ts
@@ -9,6 +9,15 @@ export interface CodeBlock {
 	code: string;
 }
 
+/** A blockquote block: a maximal run of `>`-prefixed lines from markdown. */
+export interface QuoteBlock {
+	/** Block body with each line's `>` marker (and one optional space) removed. */
+	text: string;
+}
+
+/** A drillable block within an assistant message, in document order. */
+export type MessageBlock = ({ kind: "code" } & CodeBlock) | ({ kind: "quote" } & QuoteBlock);
+
 /** A runnable command found in the transcript. */
 export interface LastCommand {
 	kind: "bash" | "eval";
@@ -23,7 +32,7 @@ export interface LastCommand {
  * `children` to drill into.
  */
 export interface CopyTarget {
-	/** Stable identifier (e.g. "msg:1", "msg:1:code:0", "msg:1:all", "cmd:1"). */
+	/** Stable id (e.g. "msg:1", "msg:1:code:0", "msg:1:quote:0", "msg:1:all", "cmd:1"). */
 	id: string;
 	label: string;
 	/** Dim annotation: line/block counts, language, or tool name. */
@@ -49,15 +58,70 @@ export interface CopySource {
 /** Cap on how many recent assistant messages the picker lists. */
 const MAX_MESSAGES = 50;
 
-const CODE_BLOCK_RE = /^```([^\n]*)\n([\s\S]*?)^```/gm;
+const OPEN_FENCE_RE = /^```([^\n]*)$/;
+const CLOSE_FENCE_RE = /^```/;
+const QUOTE_LINE_RE = /^>(.*)$/;
+
+/**
+ * Split assistant markdown into drillable blocks — fenced code and `>`-quoted
+ * runs — in document order. Fences mask their bodies, so a `>` line inside a
+ * code block is never mistaken for a quote. An unclosed fence is treated as
+ * ordinary text, matching the fenced-block grammar.
+ */
+export function extractBlocks(text: string): MessageBlock[] {
+	const blocks: MessageBlock[] = [];
+	const lines = text.split("\n");
+	let quote: string[] | undefined;
+	const flushQuote = () => {
+		if (quote) {
+			blocks.push({ kind: "quote", text: quote.join("\n") });
+			quote = undefined;
+		}
+	};
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!;
+		const open = OPEN_FENCE_RE.exec(line);
+		if (open) {
+			let close = -1;
+			for (let k = i + 1; k < lines.length; k++) {
+				if (CLOSE_FENCE_RE.test(lines[k]!)) {
+					close = k;
+					break;
+				}
+			}
+			if (close !== -1) {
+				flushQuote();
+				blocks.push({ kind: "code", lang: open[1].trim(), code: lines.slice(i + 1, close).join("\n") });
+				i = close;
+				continue;
+			}
+		}
+
+		const quoted = QUOTE_LINE_RE.exec(line);
+		if (quoted) {
+			// Strip the `>` marker plus one optional following space.
+			(quote ??= []).push(quoted[1].startsWith(" ") ? quoted[1].slice(1) : quoted[1]);
+		} else {
+			flushQuote();
+		}
+	}
+	flushQuote();
+	return blocks;
+}
 
 /** Extract fenced code blocks from assistant markdown, in document order. */
 export function extractCodeBlocks(text: string): CodeBlock[] {
-	const blocks: CodeBlock[] = [];
-	for (const match of text.matchAll(CODE_BLOCK_RE)) {
-		blocks.push({ lang: match[1].trim(), code: match[2].replace(/\n$/, "") });
-	}
-	return blocks;
+	return extractBlocks(text)
+		.filter((b): b is { kind: "code" } & CodeBlock => b.kind === "code")
+		.map(b => ({ lang: b.lang, code: b.code }));
+}
+
+/** Extract `>`-quoted blocks from assistant markdown, in document order. */
+export function extractQuoteBlocks(text: string): QuoteBlock[] {
+	return extractBlocks(text)
+		.filter((b): b is { kind: "quote" } & QuoteBlock => b.kind === "quote")
+		.map(b => ({ text: b.text }));
 }
 
 function extractEvalCode(args: unknown): { code: string; language: string } | undefined {
@@ -136,42 +200,83 @@ function firstLine(text: string): string {
 	return text.trim().replace(/\s+/g, " ");
 }
 
-/** Build the target node for one assistant message: a leaf when it has no code
- * blocks, otherwise a group exposing the full message, each block, and "all". */
+/** "<n> lines · <c> code · <q> quote" — omitting block kinds that are absent. */
+function blockSummaryHint(text: string, codeCount: number, quoteCount: number): string {
+	const parts = [pluralLines(text)];
+	if (codeCount > 0) parts.push(`${codeCount} code`);
+	if (quoteCount > 0) parts.push(`${quoteCount} quote`);
+	return parts.join(" · ");
+}
+
+/** Build the target node for one assistant message: a leaf when it has no
+ * drillable blocks, otherwise a group exposing the full message plus each
+ * fenced code block and `>`-quoted block (de-prefixed) as a child target. */
 function messageTarget(text: string, rank: number): CopyTarget {
 	const id = `msg:${rank}`;
 	const label = firstLine(text);
-	const blocks = extractCodeBlocks(text);
-	const hint = blocks.length > 0 ? `${pluralLines(text)} · ${blocks.length} code` : pluralLines(text);
+	const blocks = extractBlocks(text);
 	const messageCopy = rank === 1 ? "Copied last message to clipboard" : "Copied message to clipboard";
 
 	if (blocks.length === 0) {
-		return { id, label, hint, preview: text, content: text, copyMessage: messageCopy };
+		return { id, label, hint: pluralLines(text), preview: text, content: text, copyMessage: messageCopy };
 	}
 
-	// The message node itself copies the full message; its code blocks are
-	// child copy targets you can expand into.
-	const children: CopyTarget[] = blocks.map((block, j) => ({
-		id: `${id}:code:${j}`,
-		label: `Block ${j + 1}`,
-		hint: blockHint(block),
-		preview: block.code,
-		language: block.lang || undefined,
-		content: block.code,
-		copyMessage: `Copied code block ${j + 1} to clipboard`,
-	}));
-	if (blocks.length > 1) {
-		const combined = blocks.map(b => b.code).join("\n\n");
+	// The message node itself copies the full message; each block is a child
+	// copy target you can drill into, kept in document order.
+	const children: CopyTarget[] = [];
+	const codeBlocks: CodeBlock[] = [];
+	const quoteBlocks: QuoteBlock[] = [];
+	for (const block of blocks) {
+		if (block.kind === "code") {
+			const j = codeBlocks.length;
+			codeBlocks.push(block);
+			children.push({
+				id: `${id}:code:${j}`,
+				label: `Block ${j + 1}`,
+				hint: blockHint(block),
+				preview: block.code,
+				language: block.lang || undefined,
+				content: block.code,
+				copyMessage: `Copied code block ${j + 1} to clipboard`,
+			});
+		} else {
+			const j = quoteBlocks.length;
+			quoteBlocks.push(block);
+			children.push({
+				id: `${id}:quote:${j}`,
+				label: `Quote ${j + 1}`,
+				hint: pluralLines(block.text),
+				preview: block.text,
+				content: block.text,
+				copyMessage: `Copied quote block ${j + 1} to clipboard`,
+			});
+		}
+	}
+
+	if (codeBlocks.length > 1) {
+		const combined = codeBlocks.map(b => b.code).join("\n\n");
 		children.push({
 			id: `${id}:all`,
-			label: `All ${blocks.length} blocks`,
+			label: `All ${codeBlocks.length} blocks`,
 			hint: pluralLines(combined),
 			preview: combined,
 			content: combined,
-			copyMessage: `Copied ${blocks.length} code blocks to clipboard`,
+			copyMessage: `Copied ${codeBlocks.length} code blocks to clipboard`,
+		});
+	}
+	if (quoteBlocks.length > 1) {
+		const combined = quoteBlocks.map(b => b.text).join("\n\n");
+		children.push({
+			id: `${id}:all-quotes`,
+			label: `All ${quoteBlocks.length} quotes`,
+			hint: pluralLines(combined),
+			preview: combined,
+			content: combined,
+			copyMessage: `Copied ${quoteBlocks.length} quote blocks to clipboard`,
 		});
 	}
 
+	const hint = blockSummaryHint(text, codeBlocks.length, quoteBlocks.length);
 	return { id, label, hint, preview: text, content: text, copyMessage: messageCopy, children };
 }
 
diff --git a/packages/coding-agent/test/modes/utils/copy-targets.test.ts b/packages/coding-agent/test/modes/utils/copy-targets.test.ts
index 56b57dee8..d041ce4df 100644
--- a/packages/coding-agent/test/modes/utils/copy-targets.test.ts
+++ b/packages/coding-agent/test/modes/utils/copy-targets.test.ts
@@ -6,6 +6,7 @@ import {
 	type CopyTarget,
 	extractCodeBlocks,
 	extractLastCommand,
+	extractQuoteBlocks,
 } from "@oh-my-pi/pi-coding-agent/modes/utils/copy-targets";
 
 function source(overrides: Partial<CopySource>): CopySource {
@@ -45,6 +46,23 @@ describe("extractCodeBlocks", () => {
 	});
 });
 
+describe("extractQuoteBlocks", () => {
+	it("collects a `>`-prefixed run and strips the marker plus one space", () => {
+		const text = "intro\n> line one\n> line two\ntail";
+		expect(extractQuoteBlocks(text)).toEqual([{ text: "line one\nline two" }]);
+	});
+
+	it("keeps bare `>` separator lines as blank lines and splits on plain text", () => {
+		const text = "> first\n>\n> second\n\nbreak\n> later";
+		expect(extractQuoteBlocks(text).map(b => b.text)).toEqual(["first\n\nsecond", "later"]);
+	});
+
+	it("does not treat `>` lines inside a fenced code block as a quote", () => {
+		const text = "> real quote\n```\n> not a quote\n```";
+		expect(extractQuoteBlocks(text)).toEqual([{ text: "real quote" }]);
+	});
+});
+
 describe("extractLastCommand", () => {
 	it("returns the most recent bash command, walking backwards", () => {
 		const messages = [
@@ -110,6 +128,37 @@ describe("buildCopyTargets", () => {
 		expect(msg?.children?.map(c => c.label)).toEqual(["Block 1"]);
 	});
 
+	it("drills a quoted message into a de-prefixed quote child", () => {
+		const text = "Copy-paste to the other agent:\n\n> relay this\n> across agents";
+		const targets = buildCopyTargets(source({ messages: [assistantText(text)] as unknown as AgentMessage[] }));
+		const msg = byId(targets, "msg:1");
+		// The message node still copies the full markdown (with markers).
+		expect(msg?.content).toBe(text);
+		expect(msg?.hint).toBe("4 lines · 1 quote");
+		const quote = msg?.children?.find(c => c.id === "msg:1:quote:0");
+		expect(quote?.label).toBe("Quote 1");
+		// The drilled child copies the un-prefixed quote, ready to paste onward.
+		expect(quote?.content).toBe("relay this\nacross agents");
+		expect(quote?.language).toBeUndefined();
+		expect(quote?.copyMessage).toBe("Copied quote block 1 to clipboard");
+	});
+
+	it("interleaves code and quote children in document order with combined nodes", () => {
+		const text = "intro\n```ts\na;\n```\n> q one\n```py\nb\n```\n> q two";
+		const targets = buildCopyTargets(source({ messages: [assistantText(text)] as unknown as AgentMessage[] }));
+		const msg = byId(targets, "msg:1");
+		expect(msg?.children?.map(c => c.id)).toEqual([
+			"msg:1:code:0",
+			"msg:1:quote:0",
+			"msg:1:code:1",
+			"msg:1:quote:1",
+			"msg:1:all",
+			"msg:1:all-quotes",
+		]);
+		expect(msg?.hint).toBe("9 lines · 2 code · 2 quote");
+		expect(msg?.children?.find(c => c.id === "msg:1:all-quotes")?.content).toBe("q one\n\nq two");
+	});
+
 	it("skips tool-only assistant turns and non-assistant messages", () => {
 		const messages = [
 			{ role: "user", content: [{ type: "text", text: "hi" }] },

From 8089b7dd774cbee277aec82f403085ab2e8e3fdb Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 02:50:20 +0200
Subject: [PATCH 075/181] feat(modes): reworked plan review flow to use an
 interactive overlay

- Replaced the plan review flow to open PlanReviewOverlay for approvals.
- Added scrollable markdown plan rendering with prompt, options, and footer in the overlay UI.
- Added disabled-option handling so cursor movement and confirmation skip unavailable rows.
- Added setPlanContent updates to refresh overlay text and reset scroll position on edits.
---
 packages/coding-agent/CHANGELOG.md            |   1 +
 .../modes/components/plan-review-overlay.ts   | 237 ++++++++++++++++++
 .../src/modes/interactive-mode.ts             | 100 +++++---
 .../test/interactive-mode-plan-review.test.ts |  64 +++--
 .../components/plan-review-overlay.test.ts    | 195 ++++++++++++++
 5 files changed, 524 insertions(+), 73 deletions(-)
 create mode 100644 packages/coding-agent/src/modes/components/plan-review-overlay.ts
 create mode 100644 packages/coding-agent/test/modes/components/plan-review-overlay.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 444f73141..ad39641b8 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -4,6 +4,7 @@
 ### Changed
 
 - Changed the directory grouping for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics from a single flat `# dir/` heading per immediate directory to a multi-level tree that folds the common path prefix into one heading. Previously every group repeated the full directory path — so results rooted outside cwd printed the absolute prefix (e.g. `/Users/me/proj/`) on every heading and nested directories were never collapsed. Now a single-child directory chain folds into one heading (`# packages/pkg/src/`, including an absolute root for out-of-cwd results), subdirectories nest one `#` deeper (`## nested/` → `### child.ts`), and each directory's own files are listed before its subdirectories. TUI hyperlink reconstruction tracks the nested directory stack across the whole output so file and code-frame links keep resolving to the correct absolute paths.
+- Changed the plan-mode approval surface from an inline transcript block plus a separate bottom selector into a single fullscreen overlay (like `/copy`). The overlay owns its entire content via `ScrollView`: the plan renders once as Markdown and scrolls inside the outlined box (PageUp/PageDown, g/G), with the approval options and the model-tier slider beneath it. ↑/↓ move the option cursor, ←/→ drive the slider, Enter confirms, the external-editor key opens the plan, and Esc cancels — so a tall plan no longer competes with the selector for vertical space or clips its head on ED3-risk terminals.
 
 ### Fixed
 
diff --git a/packages/coding-agent/src/modes/components/plan-review-overlay.ts b/packages/coding-agent/src/modes/components/plan-review-overlay.ts
new file mode 100644
index 000000000..59b7e7fb5
--- /dev/null
+++ b/packages/coding-agent/src/modes/components/plan-review-overlay.ts
@@ -0,0 +1,237 @@
+/**
+ * Fullscreen plan-review overlay. Replaces the old inline `PlanReviewBlock`
+ * (which lived in the transcript and competed with the approval selector for
+ * vertical space, clipping tall plans). The overlay owns its entire content: the
+ * plan is rendered once via {@link Markdown} and windowed through a
+ * {@link ScrollView}, while the approval options (plus the optional model-tier
+ * slider) sit beneath it inside the same outlined box — one self-contained
+ * surface in the spirit of the `/copy` picker.
+ *
+ * Key map mirrors the plan-mode hook selector so muscle memory carries over:
+ * ↑/↓ (j/k) move the option cursor, ←/→ (h/l) drive the slider, Enter confirms,
+ * Esc cancels, and the external-editor key opens the plan. PageUp/PageDown and
+ * g/G scroll the plan body.
+ */
+import { type Component, Markdown, type MarkdownTheme, matchesKey, ScrollView } from "@oh-my-pi/pi-tui";
+import { getMarkdownTheme, theme } from "../theme/theme";
+import {
+	matchesAppExternalEditor,
+	matchesSelectCancel,
+	matchesSelectDown,
+	matchesSelectPageDown,
+	matchesSelectPageUp,
+	matchesSelectUp,
+} from "../utils/keybinding-matchers";
+import type { HookSelectorSlider } from "./hook-selector";
+import { bottomBorder, divider, row, topBorder } from "./overlay-box";
+import { renderSegmentTrack } from "./segment-track";
+
+/** Title shown in the overlay's top border. */
+const OVERLAY_TITLE = "Plan Review";
+/** Minimum plan-body rows kept visible even on short terminals. */
+const MIN_BODY_ROWS = 3;
+
+export interface PlanReviewOverlayCallbacks {
+	/** Invoked with the chosen option label (never a disabled one). */
+	onPick: (label: string) => void;
+	/** Invoked on Esc / cancel. */
+	onCancel: () => void;
+	/** Invoked when the external-editor key is pressed (overlay stays open). */
+	onExternalEditor?: () => void;
+}
+
+export interface PlanReviewOverlayOptions {
+	/** Prompt rendered above the options (e.g. "Plan mode - next step"). */
+	promptTitle?: string;
+	options: string[];
+	/** Indices into `options` that render dimmed and cannot be selected. */
+	disabledIndices?: number[];
+	/** Footer hint line; falls back to a generic nav hint when omitted. */
+	helpText?: string;
+	/** Initially highlighted option index. */
+	initialIndex?: number;
+	/** Optional model-tier slider rendered between the plan body and options. */
+	slider?: HookSelectorSlider;
+}
+
+/** Default footer hint when the caller supplies none. */
+const DEFAULT_HELP = "up/down select  enter confirm  pgup/pgdn scroll  esc cancel";
+
+export class PlanReviewOverlay implements Component {
+	#md: Markdown;
+	#mdTheme: MarkdownTheme;
+	#scrollView: ScrollView;
+	#options: string[];
+	#disabled: Set<number>;
+	#helpText: string;
+	#promptTitle: string | undefined;
+	#selectedIndex: number;
+	#slider: HookSelectorSlider | undefined;
+	#sliderIndex: number;
+
+	constructor(
+		planContent: string,
+		options: PlanReviewOverlayOptions,
+		private readonly callbacks: PlanReviewOverlayCallbacks,
+	) {
+		this.#mdTheme = getMarkdownTheme();
+		this.#md = new Markdown(planContent, 1, 0, this.#mdTheme);
+		this.#scrollView = new ScrollView([], {
+			height: MIN_BODY_ROWS,
+			scrollbar: "auto",
+			theme: { track: t => theme.fg("dim", t), thumb: t => theme.fg("accent", t) },
+		});
+		this.#options = options.options;
+		this.#disabled = new Set(
+			(options.disabledIndices ?? []).filter(i => Number.isInteger(i) && i >= 0 && i < this.#options.length),
+		);
+		this.#helpText = options.helpText ?? DEFAULT_HELP;
+		this.#promptTitle = options.promptTitle;
+		this.#selectedIndex = this.#coerceIndex(options.initialIndex ?? 0);
+		if (options.slider && options.slider.segments.length > 0) {
+			this.#slider = options.slider;
+			this.#sliderIndex = Math.max(0, Math.min(options.slider.index, options.slider.segments.length - 1));
+		} else {
+			this.#sliderIndex = 0;
+		}
+	}
+
+	invalidate(): void {
+		this.#md.invalidate();
+	}
+
+	/** Swap the displayed plan (e.g. after an external-editor round-trip) and
+	 *  reset the scroll position so the operator starts at the top. */
+	setPlanContent(planContent: string): void {
+		this.#md.setText(planContent);
+		this.#scrollView.scrollToTop();
+	}
+
+	/** Clamp `index` to range, then walk to the nearest enabled option so the
+	 *  cursor never rests on a disabled row. */
+	#coerceIndex(index: number): number {
+		const max = this.#options.length - 1;
+		if (max < 0) return -1;
+		const clamped = Math.max(0, Math.min(index, max));
+		if (!this.#disabled.has(clamped)) return clamped;
+		for (let i = clamped + 1; i <= max; i++) if (!this.#disabled.has(i)) return i;
+		for (let i = clamped - 1; i >= 0; i--) if (!this.#disabled.has(i)) return i;
+		return clamped;
+	}
+
+	/** Move the option cursor by `delta`, skipping disabled rows, stopping at the
+	 *  list edge. */
+	#moveSelection(delta: number): void {
+		const max = this.#options.length - 1;
+		if (max < 0) return;
+		let index = this.#selectedIndex;
+		while (true) {
+			const next = Math.max(0, Math.min(index + delta, max));
+			if (next === index) return;
+			index = next;
+			if (!this.#disabled.has(index)) {
+				this.#selectedIndex = index;
+				return;
+			}
+		}
+	}
+
+	#moveSlider(delta: number): void {
+		const slider = this.#slider;
+		if (!slider) return;
+		const next = Math.max(0, Math.min(slider.segments.length - 1, this.#sliderIndex + delta));
+		if (next === this.#sliderIndex) return;
+		this.#sliderIndex = next;
+		slider.onChange?.(next);
+	}
+
+	handleInput(keyData: string): void {
+		if (matchesSelectCancel(keyData)) {
+			this.callbacks.onCancel();
+			return;
+		}
+		if (matchesSelectUp(keyData) || keyData === "k") {
+			this.#moveSelection(-1);
+		} else if (matchesSelectDown(keyData) || keyData === "j") {
+			this.#moveSelection(1);
+		} else if (matchesKey(keyData, "left") || (this.#slider && keyData === "h")) {
+			this.#moveSlider(-1);
+		} else if (matchesKey(keyData, "right") || (this.#slider && keyData === "l")) {
+			this.#moveSlider(1);
+		} else if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
+			const index = this.#selectedIndex;
+			if (index >= 0 && index < this.#options.length && !this.#disabled.has(index)) {
+				this.callbacks.onPick(this.#options[index]!);
+			}
+		} else if (matchesSelectPageUp(keyData) || matchesKey(keyData, "pageUp")) {
+			this.#scrollView.page(-1);
+		} else if (matchesSelectPageDown(keyData) || matchesKey(keyData, "pageDown")) {
+			this.#scrollView.page(1);
+		} else if (keyData === "g") {
+			this.#scrollView.scrollToTop();
+		} else if (keyData === "G") {
+			this.#scrollView.scrollToBottom();
+		} else if (this.callbacks.onExternalEditor && matchesAppExternalEditor(keyData)) {
+			this.callbacks.onExternalEditor();
+		}
+	}
+
+	#renderSliderLines(): string[] {
+		const slider = this.#slider;
+		if (!slider) return [];
+		const active = this.#sliderIndex;
+		const track = renderSegmentTrack(slider.segments, active);
+		const leftArrow = theme.fg(active > 0 ? "accent" : "dim", "◂");
+		const rightArrow = theme.fg(active < slider.segments.length - 1 ? "accent" : "dim", "▸");
+		const caption = slider.caption ? `${theme.fg("dim", slider.caption)}  ` : "";
+		const trackLine = `${caption}${leftArrow}  ${track}  ${rightArrow}`;
+		const detail = slider.segments[active]?.detail;
+		if (!detail) return [trackLine];
+		return [trackLine, `  ${theme.fg("dim", "↳")} ${theme.fg("muted", detail)}`];
+	}
+
+	#renderOptionLines(): string[] {
+		return this.#options.map((label, i) => {
+			const isSelected = i === this.#selectedIndex;
+			const isDisabled = this.#disabled.has(i);
+			const cursor = isSelected ? theme.fg("accent", `${theme.nav.cursor} `) : "  ";
+			const text = isDisabled
+				? theme.fg("dim", label)
+				: isSelected
+					? theme.bold(theme.fg("accent", label))
+					: theme.fg("text", label);
+			return cursor + text;
+		});
+	}
+
+	render(width: number): string[] {
+		const termHeight = process.stdout.rows || 40;
+		const innerWidth = Math.max(1, width - 4);
+
+		const planLines = this.#md.render(innerWidth);
+		const sliderLines = this.#renderSliderLines();
+		const optionLines = this.#renderOptionLines();
+		const promptLines = this.#promptTitle ? [theme.bold(theme.fg("accent", this.#promptTitle))] : [];
+
+		// Chrome rows around the scrollable body: top border, divider, prompt,
+		// slider, options, divider, footer, bottom border.
+		const chrome = 5 + promptLines.length + sliderLines.length + optionLines.length;
+		const viewport = Math.max(MIN_BODY_ROWS, termHeight - chrome);
+
+		this.#scrollView.setLines(planLines);
+		this.#scrollView.setHeight(viewport);
+		const body = this.#scrollView.render(innerWidth);
+
+		return [
+			topBorder(width, OVERLAY_TITLE),
+			...body.map(line => row(line, width)),
+			divider(width),
+			...promptLines.map(line => row(line, width)),
+			...sliderLines.map(line => row(line, width)),
+			...optionLines.map(line => row(line, width)),
+			divider(width),
+			row(theme.fg("dim", this.#helpText), width),
+			bottomBorder(width),
+		];
+	}
+}
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index 8f2bfa1b1..6abe5cb10 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -20,7 +20,7 @@ import {
 	modelsAreEqual,
 	type UsageReport,
 } from "@oh-my-pi/pi-ai";
-import type { Component, EditorTheme, SlashCommand } from "@oh-my-pi/pi-tui";
+import type { Component, EditorTheme, OverlayHandle, SlashCommand } from "@oh-my-pi/pi-tui";
 import {
 	Container,
 	clearRenderCache,
@@ -101,6 +101,7 @@ import type { EvalExecutionComponent } from "./components/eval-execution";
 import type { HookEditorComponent } from "./components/hook-editor";
 import type { HookInputComponent } from "./components/hook-input";
 import type { HookSelectorComponent, HookSelectorSlider } from "./components/hook-selector";
+import { PlanReviewOverlay } from "./components/plan-review-overlay";
 import { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
 import { TranscriptContainer } from "./components/transcript-container";
@@ -250,20 +251,6 @@ export interface InteractiveModeOptions {
 	initialMessages?: string[];
 }
 
-/**
- * Plan-review preview block. Once rendered it is static (a one-shot Markdown of
- * the plan file), so even while it sits as the live bottom block beneath the
- * approval selector its scrolled-off head is safe to commit to native
- * scrollback. Reporting append-only lets an over-tall plan + selector commit the
- * plan's head instead of clipping it — without this a plain {@link Container} is
- * deferred and a long plan is cut off the top on ED3-risk terminals.
- */
-class PlanReviewBlock extends Container {
-	isTranscriptBlockAppendOnly(): boolean {
-		return true;
-	}
-}
-
 export class InteractiveMode implements InteractiveModeContext {
 	session: AgentSession;
 	sessionManager: SessionManager;
@@ -355,7 +342,8 @@ export class InteractiveMode implements InteractiveModeContext {
 	#planModePreviousModelState: { model: Model; thinkingLevel?: ThinkingLevel } | undefined;
 	#pendingModelSwitch: { model: Model; thinkingLevel?: ThinkingLevel } | undefined;
 	#planModeHasEntered = false;
-	#planReviewContainer: Container | undefined;
+	#planReviewOverlay: PlanReviewOverlay | undefined;
+	#planReviewOverlayHandle: OverlayHandle | undefined;
 	readonly lspServers: LspStartupServerInfo[] | undefined = undefined;
 	mcpManager?: import("../mcp").MCPManager;
 	readonly #toolUiContextSetter: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
@@ -1691,22 +1679,60 @@ export class InteractiveMode implements InteractiveModeContext {
 		}
 	}
 
-	#renderPlanPreview(planContent: string, options?: { append?: boolean }): void {
-		const existingContainer = this.#planReviewContainer;
-		const replaceExisting = options?.append !== true && existingContainer !== undefined;
-		const planReviewContainer = replaceExisting ? existingContainer : new PlanReviewBlock();
-		planReviewContainer.clear();
-		planReviewContainer.addChild(new Spacer(1));
-		planReviewContainer.addChild(new DynamicBorder());
-		planReviewContainer.addChild(new Text(theme.bold(theme.fg("accent", "Plan Review")), 1, 1));
-		planReviewContainer.addChild(new Spacer(1));
-		planReviewContainer.addChild(new Markdown(planContent, 1, 1, getMarkdownTheme()));
-		planReviewContainer.addChild(new DynamicBorder());
-		if (!replaceExisting) {
-			this.chatContainer.addChild(planReviewContainer);
-		}
-		this.#planReviewContainer = planReviewContainer;
+	showPlanReview(
+		planContent: string,
+		title: string,
+		options: string[],
+		dialogOptions?: {
+			helpText?: string;
+			disabledIndices?: number[];
+			onExternalEditor?: () => void;
+			initialIndex?: number;
+		},
+		extra?: { slider?: HookSelectorSlider },
+	): Promise<string | undefined> {
+		this.#hidePlanReview();
+		const { promise, resolve } = Promise.withResolvers<string | undefined>();
+		let settled = false;
+		const finish = (choice: string | undefined): void => {
+			if (settled) return;
+			settled = true;
+			this.#hidePlanReview();
+			this.ui.requestRender();
+			resolve(choice);
+		};
+		const overlay = new PlanReviewOverlay(
+			planContent,
+			{
+				promptTitle: title,
+				options,
+				disabledIndices: dialogOptions?.disabledIndices,
+				helpText: dialogOptions?.helpText,
+				initialIndex: dialogOptions?.initialIndex,
+				slider: extra?.slider,
+			},
+			{
+				onPick: choice => finish(choice),
+				onCancel: () => finish(undefined),
+				onExternalEditor: dialogOptions?.onExternalEditor,
+			},
+		);
+		this.#planReviewOverlay = overlay;
+		this.#planReviewOverlayHandle = this.ui.showOverlay(overlay, {
+			anchor: "bottom-center",
+			width: "100%",
+			maxHeight: "100%",
+			margin: 0,
+		});
+		this.ui.setFocus(overlay);
 		this.ui.requestRender();
+		return promise;
+	}
+
+	#hidePlanReview(): void {
+		this.#planReviewOverlayHandle?.hide();
+		this.#planReviewOverlayHandle = undefined;
+		this.#planReviewOverlay = undefined;
 	}
 
 	#getEditorTerminalPath(): string | null {
@@ -1731,9 +1757,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	#getPlanReviewHelpText(): string {
 		const externalEditorKey = this.keybindings.getDisplayString("app.editor.external");
 		if (!externalEditorKey) {
-			return "up/down navigate  enter select  esc cancel";
+			return "up/down select  enter confirm  pgup/pgdn scroll  esc cancel";
 		}
-		return `up/down navigate  enter select  ${externalEditorKey.toLowerCase()} open in editor  esc cancel`;
+		return `up/down select  enter confirm  pgup/pgdn scroll  ${externalEditorKey.toLowerCase()} open in editor  esc cancel`;
 	}
 
 	#getPlanApprovalContextUsage(): ContextUsage | undefined {
@@ -1794,7 +1820,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			});
 			if (result !== null) {
 				await Bun.write(resolvedPath, result);
-				this.#renderPlanPreview(result);
+				this.#planReviewOverlay?.setPlanContent(result);
 				this.showStatus("Plan updated in external editor.");
 			}
 		} catch (error) {
@@ -2223,7 +2249,6 @@ export class InteractiveMode implements InteractiveModeContext {
 			return;
 		}
 
-		this.#renderPlanPreview(planContent, { append: true });
 		const contextUsage = this.#getPlanApprovalContextUsage();
 		const keepContextLabel = this.#formatKeepContextLabel(contextUsage);
 		const keepContextDisabled = this.#isKeepContextDisabled(contextUsage);
@@ -2255,7 +2280,8 @@ export class InteractiveMode implements InteractiveModeContext {
 				: undefined;
 		const helpText = slider ? `${this.#getPlanReviewHelpText()}  ◂/▸ model` : this.#getPlanReviewHelpText();
 
-		const choice = await this.showHookSelector(
+		const choice = await this.showPlanReview(
+			planContent,
 			"Plan mode - next step",
 			["Approve and execute", "Approve and compact context", keepContextLabel, "Refine plan"],
 			{
@@ -2751,7 +2777,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#omfgController.dispose();
 		this.#extensionUiController.clearExtensionTerminalInputListeners();
 		this.clearPinnedError();
-		this.#planReviewContainer = undefined;
+		this.#hidePlanReview();
 	}
 
 	handleClearCommand(): Promise<void> {
diff --git a/packages/coding-agent/test/interactive-mode-plan-review.test.ts b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
index 85ae3f784..8c270905d 100644
--- a/packages/coding-agent/test/interactive-mode-plan-review.test.ts
+++ b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
@@ -7,7 +7,6 @@ import { resolveLocalUrlToPath } from "@oh-my-pi/pi-coding-agent/internal-urls";
 import { AssistantMessageComponent } from "@oh-my-pi/pi-coding-agent/modes/components/assistant-message";
 import { initTheme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
 import { SILENT_ABORT_MARKER } from "@oh-my-pi/pi-coding-agent/session/messages";
-import { Text } from "@oh-my-pi/pi-tui";
 import { formatNumber, TempDir } from "@oh-my-pi/pi-utils";
 import { ModelRegistry } from "../src/config/model-registry";
 import type { HookSelectorSlider } from "../src/modes/components/hook-selector";
@@ -112,7 +111,7 @@ describe("InteractiveMode plan review rendering", () => {
 		resetSettingsForTest();
 	});
 
-	it("appends each submitted plan review preview to preserve scrollback", async () => {
+	it("forwards each submitted plan to the review overlay", async () => {
 		const planFilePath = "local://PLAN.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
@@ -122,7 +121,7 @@ describe("InteractiveMode plan review rendering", () => {
 
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Refine plan");
+		const review = vi.spyOn(mode, "showPlanReview").mockResolvedValue("Refine plan");
 
 		await mode.handlePlanApproval({
 			planFilePath,
@@ -131,12 +130,8 @@ describe("InteractiveMode plan review rendering", () => {
 			finalPlanFilePath: "local://PLAN.md",
 		});
 
-		const firstPreview = mode.chatContainer.children.at(-1);
-		expect(firstPreview).toBeDefined();
-		expect(firstPreview!.render(120).join("\n")).toContain("First plan");
+		expect(review.mock.calls[0]?.[0]).toContain("First plan");
 
-		const marker = new Text("MARKER", 0, 0);
-		mode.chatContainer.addChild(marker);
 		await Bun.write(resolvedPlanPath, "# Second plan\n\nbeta");
 
 		await mode.handlePlanApproval({
@@ -146,14 +141,9 @@ describe("InteractiveMode plan review rendering", () => {
 			finalPlanFilePath: "local://PLAN.md",
 		});
 
-		const secondPreview = mode.chatContainer.children.at(-1);
-		expect(secondPreview).toBeDefined();
-		expect(secondPreview).not.toBe(firstPreview);
-		expect(mode.chatContainer.children.at(-2)).toBe(marker);
-		expect(mode.chatContainer.children.at(-3)).toBe(firstPreview);
-		expect(firstPreview!.render(120).join("\n")).toContain("First plan");
-		expect(firstPreview!.render(120).join("\n")).not.toContain("Second plan");
-		expect(secondPreview!.render(120).join("\n")).toContain("Second plan");
+		// Each approval shows the current plan in the overlay, not a stale one.
+		expect(review.mock.calls[1]?.[0]).toContain("Second plan");
+		expect(review.mock.calls[1]?.[0]).not.toContain("First plan");
 	});
 
 	it("offers approve-and-keep-context as a distinct plan approval path", async () => {
@@ -167,7 +157,7 @@ describe("InteractiveMode plan review rendering", () => {
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
 		vi.spyOn(session, "getContextUsage").mockReturnValue({ tokens: 7320, contextWindow: 10000, percent: 73.2 });
-		const selector = vi.spyOn(mode, "showHookSelector").mockResolvedValue("Refine plan");
+		const selector = vi.spyOn(mode, "showPlanReview").mockResolvedValue("Refine plan");
 
 		await mode.handlePlanApproval({
 			planFilePath,
@@ -177,6 +167,7 @@ describe("InteractiveMode plan review rendering", () => {
 		});
 
 		expect(selector).toHaveBeenCalledWith(
+			expect.any(String),
 			"Plan mode - next step",
 			[
 				"Approve and execute",
@@ -244,7 +235,7 @@ describe("InteractiveMode plan review rendering", () => {
 				percent: (tokens / contextWindow) * 100,
 			};
 		});
-		const selector = vi.spyOn(mode, "showHookSelector").mockResolvedValue("Refine plan");
+		const selector = vi.spyOn(mode, "showPlanReview").mockResolvedValue("Refine plan");
 
 		await mode.handlePlanApproval({
 			planFilePath,
@@ -254,7 +245,7 @@ describe("InteractiveMode plan review rendering", () => {
 		});
 
 		expect(contextSpy).toHaveBeenCalledWith({ contextWindow: executionModel.contextWindow });
-		expect(selector.mock.calls[0]?.[1]).toEqual([
+		expect(selector.mock.calls[0]?.[2]).toEqual([
 			"Approve and execute",
 			"Approve and compact context",
 			`Approve and keep context (~${compactNumber(tokens)} / ${compactNumber(executionModel.contextWindow)})`,
@@ -273,7 +264,7 @@ describe("InteractiveMode plan review rendering", () => {
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
 		vi.spyOn(session, "getContextUsage").mockReturnValue({ tokens: 9600, contextWindow: 10000, percent: 96 });
-		const selector = vi.spyOn(mode, "showHookSelector").mockResolvedValue("Refine plan");
+		const selector = vi.spyOn(mode, "showPlanReview").mockResolvedValue("Refine plan");
 
 		await mode.handlePlanApproval({
 			planFilePath,
@@ -282,7 +273,7 @@ describe("InteractiveMode plan review rendering", () => {
 			finalPlanFilePath: "local://APPROVED.md",
 		});
 
-		expect(selector.mock.calls[0]?.[2]).toEqual(
+		expect(selector.mock.calls[0]?.[3]).toEqual(
 			expect.objectContaining({
 				disabledIndices: [2],
 			}),
@@ -300,7 +291,7 @@ describe("InteractiveMode plan review rendering", () => {
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
 		vi.spyOn(session, "getContextUsage").mockReturnValue({ tokens: 9500, contextWindow: 10000, percent: 95 });
-		const selector = vi.spyOn(mode, "showHookSelector").mockResolvedValue("Refine plan");
+		const selector = vi.spyOn(mode, "showPlanReview").mockResolvedValue("Refine plan");
 
 		await mode.handlePlanApproval({
 			planFilePath,
@@ -309,7 +300,7 @@ describe("InteractiveMode plan review rendering", () => {
 			finalPlanFilePath: "local://APPROVED.md",
 		});
 
-		expect(selector.mock.calls[0]?.[2]).toEqual(
+		expect(selector.mock.calls[0]?.[3]).toEqual(
 			expect.objectContaining({
 				disabledIndices: undefined,
 			}),
@@ -328,7 +319,7 @@ describe("InteractiveMode plan review rendering", () => {
 		mode.planModePlanFilePath = planFilePath;
 		// Post-compaction: tokens unknown until the next LLM response.
 		vi.spyOn(session, "getContextUsage").mockReturnValue({ tokens: null, contextWindow: 200000, percent: null });
-		const selector = vi.spyOn(mode, "showHookSelector").mockResolvedValue("Refine plan");
+		const selector = vi.spyOn(mode, "showPlanReview").mockResolvedValue("Refine plan");
 
 		await mode.handlePlanApproval({
 			planFilePath,
@@ -338,6 +329,7 @@ describe("InteractiveMode plan review rendering", () => {
 		});
 
 		expect(selector).toHaveBeenCalledWith(
+			expect.any(String),
 			"Plan mode - next step",
 			["Approve and execute", "Approve and compact context", "Approve and keep context", "Refine plan"],
 			expect.any(Object),
@@ -361,7 +353,7 @@ describe("InteractiveMode plan review rendering", () => {
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
 		vi.spyOn(session, "getContextUsage").mockReturnValue({ tokens: null, contextWindow: 200000, percent: null });
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and keep context");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and keep context");
 		const clear = vi.spyOn(mode, "handleClearCommand").mockResolvedValue();
 		const prompt = vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
 
@@ -390,7 +382,7 @@ describe("InteractiveMode plan review rendering", () => {
 
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and execute");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and execute");
 		const clear = vi.spyOn(mode, "handleClearCommand").mockResolvedValue();
 		const prompt = vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
 
@@ -443,8 +435,8 @@ describe("InteractiveMode plan review rendering", () => {
 		vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
 
 		let observedSegments: string[] = [];
-		vi.spyOn(mode, "showHookSelector").mockImplementation(
-			async (_title, _options, _dialogOptions, extra?: { slider?: HookSelectorSlider }) => {
+		vi.spyOn(mode, "showPlanReview").mockImplementation(
+			async (_planContent, _title, _options, _dialogOptions, extra?: { slider?: HookSelectorSlider }) => {
 				const slider = extra?.slider;
 				expect(slider).toBeDefined();
 				observedSegments = slider!.segments.map(segment => segment.label);
@@ -480,7 +472,7 @@ describe("InteractiveMode plan review rendering", () => {
 
 		await mode.handlePlanModeCommand();
 
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and execute");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and execute");
 		vi.spyOn(mode, "handleClearCommand").mockResolvedValue();
 		vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
 
@@ -513,7 +505,7 @@ describe("InteractiveMode plan review rendering", () => {
 
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and compact context");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and compact context");
 		const compactSpy = vi.spyOn(mode, "handleCompactCommand").mockResolvedValue("ok");
 		const markSentSpy = vi.spyOn(session, "markPlanReferenceSent");
 		const promptSpy = vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
@@ -556,7 +548,7 @@ describe("InteractiveMode plan review rendering", () => {
 
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and compact context");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and compact context");
 		vi.spyOn(mode, "handleCompactCommand").mockResolvedValue("cancelled");
 		const showWarningSpy = vi.spyOn(mode, "showWarning");
 		const setPlanRefSpy = vi.spyOn(session, "setPlanReferencePath");
@@ -599,7 +591,7 @@ describe("InteractiveMode plan review rendering", () => {
 
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and compact context");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and compact context");
 		vi.spyOn(mode, "handleCompactCommand").mockResolvedValue("failed");
 		const markSentSpy = vi.spyOn(session, "markPlanReferenceSent");
 		const promptSpy = vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
@@ -632,7 +624,7 @@ describe("InteractiveMode plan review rendering", () => {
 
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and compact context");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and compact context");
 		vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
 
 		const setPlanRefSpy = vi.spyOn(session, "setPlanReferencePath");
@@ -685,7 +677,7 @@ describe("InteractiveMode plan review rendering", () => {
 
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and compact context");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and compact context");
 		if (compactOutcome === "throw") {
 			vi.spyOn(mode, "handleCompactCommand").mockRejectedValue(throwError ?? new Error("compact boom"));
 		} else {
@@ -743,7 +735,7 @@ describe("InteractiveMode plan review rendering", () => {
 		await Bun.write(resolvedPlanPath, "# Plan\n\nBody.");
 		mode.planModeEnabled = true;
 		mode.planModePlanFilePath = planFilePath;
-		vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and execute");
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and execute");
 		const markSpy = vi.spyOn(session, "markPlanCompactAbortPending");
 		vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
 
@@ -771,7 +763,7 @@ describe("InteractiveMode plan review rendering", () => {
 		expect(session.getPlanModeState()?.planFilePath).toBe(planFilePath);
 
 		vi.spyOn(session, "getContextUsage").mockReturnValue({ tokens: null, contextWindow: 200000, percent: null });
-		const selector = vi.spyOn(mode, "showHookSelector").mockResolvedValue("Approve and keep context");
+		const selector = vi.spyOn(mode, "showPlanReview").mockResolvedValue("Approve and keep context");
 		const showError = vi.spyOn(mode, "showError");
 		vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
 
diff --git a/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts b/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts
new file mode 100644
index 000000000..49c2cba61
--- /dev/null
+++ b/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts
@@ -0,0 +1,195 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
+import { stripVTControlCharacters } from "node:util";
+import { KeybindingsManager } from "@oh-my-pi/pi-coding-agent/config/keybindings";
+import type { HookSelectorSlider } from "@oh-my-pi/pi-coding-agent/modes/components/hook-selector";
+import { PlanReviewOverlay } from "@oh-my-pi/pi-coding-agent/modes/components/plan-review-overlay";
+import { getThemeByName, setThemeInstance } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
+import { setKeybindings } from "@oh-my-pi/pi-tui";
+
+const UP = "\x1b[A";
+const DOWN = "\x1b[B";
+const LEFT = "\x1b[D";
+const RIGHT = "\x1b[C";
+const ENTER = "\r";
+const CANCEL = "\x07"; // ctrl+g, remapped to tui.select.cancel below
+
+let darkTheme = await getThemeByName("dark");
+
+function render(component: PlanReviewOverlay): string {
+	return stripVTControlCharacters(component.render(80).join("\n"));
+}
+
+const APPROVAL_OPTIONS = [
+	"Approve and execute",
+	"Approve and compact context",
+	"Approve and keep context",
+	"Refine plan",
+];
+
+describe("PlanReviewOverlay", () => {
+	beforeAll(async () => {
+		darkTheme = await getThemeByName("dark");
+		if (!darkTheme) throw new Error("Failed to load dark theme");
+	});
+
+	beforeEach(() => {
+		setThemeInstance(darkTheme!);
+		setKeybindings(KeybindingsManager.inMemory({ "tui.select.cancel": "ctrl+g" }));
+	});
+
+	afterEach(() => {
+		setKeybindings(KeybindingsManager.inMemory());
+		vi.restoreAllMocks();
+	});
+
+	it("renders the plan body, prompt, options and footer inside one outlined box", () => {
+		const overlay = new PlanReviewOverlay(
+			"# My Plan\n\nstep one then step two",
+			{ promptTitle: "Plan mode - next step", options: APPROVAL_OPTIONS, helpText: "esc cancel" },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		const out = render(overlay);
+		expect(out).toContain("Plan Review");
+		expect(out).toContain("My Plan");
+		expect(out).toContain("step one then step two");
+		expect(out).toContain("Plan mode - next step");
+		for (const option of APPROVAL_OPTIONS) expect(out).toContain(option);
+		expect(out).toContain("esc cancel");
+		// Outlined like the /copy overlay.
+		expect(out).toContain("┌");
+		expect(out).toContain("│");
+		expect(out).toContain("└");
+	});
+
+	it("confirms the highlighted option on Enter", () => {
+		const onPick = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			"plan",
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick, onCancel: vi.fn() },
+		);
+		overlay.handleInput(ENTER);
+		expect(onPick).toHaveBeenCalledTimes(1);
+		expect(onPick).toHaveBeenCalledWith("Approve and execute");
+	});
+
+	it("moves the option cursor with up/down and confirms the new target", () => {
+		const onPick = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			"plan",
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick, onCancel: vi.fn() },
+		);
+		overlay.handleInput(DOWN);
+		overlay.handleInput(ENTER);
+		expect(onPick).toHaveBeenCalledWith("Approve and compact context");
+
+		onPick.mockClear();
+		overlay.handleInput(UP);
+		overlay.handleInput(ENTER);
+		expect(onPick).toHaveBeenCalledWith("Approve and execute");
+	});
+
+	it("skips disabled options and never confirms them", () => {
+		const onPick = vi.fn();
+		// Disable index 2 ("Approve and keep context").
+		const overlay = new PlanReviewOverlay(
+			"plan",
+			{ promptTitle: "next", options: APPROVAL_OPTIONS, disabledIndices: [2] },
+			{ onPick, onCancel: vi.fn() },
+		);
+		// 0 -> 1 -> (skip 2) -> 3.
+		overlay.handleInput(DOWN);
+		overlay.handleInput(DOWN);
+		overlay.handleInput(ENTER);
+		expect(onPick).toHaveBeenCalledTimes(1);
+		expect(onPick).toHaveBeenCalledWith("Refine plan");
+	});
+
+	it("cancels on the cancel key", () => {
+		const onCancel = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			"plan",
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel },
+		);
+		overlay.handleInput(CANCEL);
+		expect(onCancel).toHaveBeenCalledTimes(1);
+	});
+
+	it("drives the model-tier slider with left/right without changing the option cursor", () => {
+		const changes: number[] = [];
+		const slider: HookSelectorSlider = {
+			caption: "continue with",
+			index: 0,
+			segments: [{ label: "default" }, { label: "slow", detail: "opus" }],
+			onChange: index => changes.push(index),
+		};
+		const onPick = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			"plan",
+			{ promptTitle: "next", options: APPROVAL_OPTIONS, slider },
+			{ onPick, onCancel: vi.fn() },
+		);
+		overlay.handleInput(RIGHT);
+		expect(changes).toEqual([1]);
+		// Clamped at the right edge.
+		overlay.handleInput(RIGHT);
+		expect(changes).toEqual([1]);
+		overlay.handleInput(LEFT);
+		expect(changes).toEqual([1, 0]);
+
+		// The slider must not have moved the option cursor.
+		overlay.handleInput(ENTER);
+		expect(onPick).toHaveBeenCalledWith("Approve and execute");
+	});
+
+	it("invokes the external-editor callback on its key", () => {
+		setKeybindings(KeybindingsManager.inMemory({ "tui.select.cancel": "ctrl+g", "app.editor.external": "ctrl+e" }));
+		const onExternalEditor = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			"plan",
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn(), onExternalEditor },
+		);
+		overlay.handleInput("\x05"); // ctrl+e
+		expect(onExternalEditor).toHaveBeenCalledTimes(1);
+	});
+
+	it("scrolls a long plan to bottom and back to top", () => {
+		const longPlan = Array.from({ length: 200 }, (_, i) => `para ${i}`).join("\n\n");
+		const overlay = new PlanReviewOverlay(
+			longPlan,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		const top = render(overlay);
+		expect(top).toContain("para 0");
+		expect(top).not.toContain("para 199");
+
+		overlay.handleInput("G");
+		const bottom = render(overlay);
+		expect(bottom).toContain("para 199");
+		expect(bottom).not.toContain("para 0");
+
+		overlay.handleInput("g");
+		const backToTop = render(overlay);
+		expect(backToTop).toContain("para 0");
+		expect(backToTop).not.toContain("para 199");
+	});
+
+	it("swaps the displayed plan and resets scroll on setPlanContent", () => {
+		const longPlan = Array.from({ length: 200 }, (_, i) => `para ${i}`).join("\n\n");
+		const overlay = new PlanReviewOverlay(
+			longPlan,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		overlay.handleInput("G"); // scroll away from the top
+		overlay.setPlanContent("# Fresh plan\n\nbrand new body");
+		const out = render(overlay);
+		expect(out).toContain("Fresh plan");
+		expect(out).toContain("brand new body");
+		expect(out).not.toContain("para 199");
+	});
+});

From 4c5279b04b7eb46f90b117962311c6eb0b1a6d9c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 02:58:38 +0200
Subject: [PATCH 076/181] ux(modes): unified transcript spacing and block
 grouping for cleaner rendering

- Centralized transcript spacing by stripping blank edges and inserting separators.
- Removed per-component leading spacers and empty placeholders that added extra gaps.
- Introduced TranscriptBlock grouping so related outputs render as single transcript children.
- Updated transcript-related tests to validate one-row block separators and blank-line trimming.
---
 packages/coding-agent/CHANGELOG.md            |   1 +
 packages/coding-agent/src/debug/index.ts      |  61 ++++-----
 .../src/modes/components/assistant-message.ts |   4 -
 .../src/modes/components/copy-selector.ts     |   1 -
 .../src/modes/components/custom-message.ts    |   4 +-
 .../src/modes/components/execution-shared.ts  |   3 +-
 .../src/modes/components/hook-message.ts      |   4 +-
 .../src/modes/components/skill-message.ts     |   1 -
 .../src/modes/components/todo-reminder.ts     |   2 -
 .../src/modes/components/tool-execution.ts    |   9 +-
 .../modes/components/transcript-container.ts  | 108 ++++++++++++----
 .../src/modes/components/user-message.ts      |   3 +-
 .../controllers/command-controller-shared.ts  |  12 +-
 .../modes/controllers/command-controller.ts   |  53 ++++----
 .../src/modes/controllers/event-controller.ts |   4 +-
 .../controllers/mcp-command-controller.ts     |  56 ++++-----
 .../modes/controllers/selector-controller.ts  |  41 ++++---
 .../src/modes/utils/copy-targets.ts           |   3 +-
 .../src/modes/utils/ui-helpers.ts             |  31 ++---
 .../components/transcript-container.test.ts   | 116 ++++++++++++++----
 .../event-controller-message-start.test.ts    |   8 +-
 .../test/tools/read-renderer.test.ts          |   2 +-
 22 files changed, 320 insertions(+), 207 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index ad39641b8..0fb428666 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -11,6 +11,7 @@
 - Fixed duplicate file entries in grouped outputs for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics when the same path appeared multiple times
 - Fixed search, grep, and edit output rendering so repeated directory group blank-line boundaries no longer break nested path/link reconstruction
 - Fixed `omp dry-balance --bench` flooding the terminal with staircased, duplicated spinner/status lines (and an indented summary) when the tty has ONLCR/OPOST disabled (raw mode). The interactive progress region separated rows with a bare LF and repositioned with a column-preserving `\x1b[<n>A` cursor-up, both of which only land at column 0 when the terminal translates LF→CRLF; with that translation off, every 80 ms redraw cascaded down and to the right into scrollback. The live region now carriage-returns before every cleared row, terminates each row with CRLF, and caps each row to the terminal width so a wrapped line cannot desync the cursor-up from the logical line count.
+- Fixed inconsistent vertical spacing between transcript blocks: some blocks (tool results from `search`/`find` and other renderer-backed tools) rendered with a doubled gap (a leading `Spacer` plus the content box's own `paddingY`), while others (the grouped `read` card, file-mention lists, IRC cards) rendered with no gap at all. Vertical spacing is now owned entirely by the chat renderer: `TranscriptContainer` strips each block's plain-blank top/bottom edges and inserts exactly one blank line between consecutive blocks, so every block is separated by a single consistent gap regardless of which component produced it. Individual components (assistant/user/tool/read-group/bash/eval/skill/custom/hook/compaction/branch/todo-reminder/plan-review messages) no longer emit their own leading `Spacer`/`paddingY` for separation, and multi-row groups (IRC cards, file-mention lists, completed-job batches, and the bordered command/`/changelog`/`/context`/version/OAuth/debug panels) are wrapped as single `TranscriptBlock` children so the renderer spaces them as one unit. Background-colored box padding is preserved as block-internal design.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/coding-agent/src/debug/index.ts b/packages/coding-agent/src/debug/index.ts
index eece0d938..813afa65b 100644
--- a/packages/coding-agent/src/debug/index.ts
+++ b/packages/coding-agent/src/debug/index.ts
@@ -19,6 +19,7 @@ import {
 } from "@oh-my-pi/pi-tui";
 import { getSessionsDir } from "@oh-my-pi/pi-utils";
 import { DynamicBorder } from "../modes/components/dynamic-border";
+import { TranscriptBlock } from "../modes/components/transcript-container";
 import { getSelectListTheme, getSymbolTheme, theme } from "../modes/theme/theme";
 import type { InteractiveModeContext } from "../modes/types";
 import { formatBytes } from "../tools/render-utils";
@@ -150,12 +151,13 @@ export class DebugSelectorComponent extends Container {
 		}
 
 		// Show message and wait for keypress
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(theme.fg("accent", `${theme.status.info} CPU profiling started`), 1, 0));
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(
+		const block = new TranscriptBlock();
+		block.addChild(new Text(theme.fg("accent", `${theme.status.info} CPU profiling started`), 1, 0));
+		block.addChild(new Spacer(1));
+		block.addChild(
 			new Text(theme.fg("muted", "Reproduce the performance issue, then press Enter to stop profiling."), 1, 0),
 		);
+		this.ctx.chatContainer.addChild(block);
 		this.ctx.ui.requestRender();
 
 		// Wait for Enter keypress
@@ -201,12 +203,11 @@ export class DebugSelectorComponent extends Container {
 			loader.stop();
 			this.ctx.statusContainer.clear();
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
-				new Text(theme.fg("success", `${theme.status.success} Performance report saved`), 1, 0),
-			);
-			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
-			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
+			const block = new TranscriptBlock();
+			block.addChild(new Text(theme.fg("success", `${theme.status.success} Performance report saved`), 1, 0));
+			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
+			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
+			this.ctx.chatContainer.addChild(block);
 		} catch (err) {
 			loader.stop();
 			this.ctx.statusContainer.clear();
@@ -262,12 +263,11 @@ export class DebugSelectorComponent extends Container {
 			loader.stop();
 			this.ctx.statusContainer.clear();
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
-				new Text(theme.fg("success", `${theme.status.success} Report bundle saved`), 1, 0),
-			);
-			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
-			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
+			const block = new TranscriptBlock();
+			block.addChild(new Text(theme.fg("success", `${theme.status.success} Report bundle saved`), 1, 0));
+			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
+			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
+			this.ctx.chatContainer.addChild(block);
 		} catch (err) {
 			loader.stop();
 			this.ctx.statusContainer.clear();
@@ -301,12 +301,11 @@ export class DebugSelectorComponent extends Container {
 			loader.stop();
 			this.ctx.statusContainer.clear();
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
-				new Text(theme.fg("success", `${theme.status.success} Memory report saved`), 1, 0),
-			);
-			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
-			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
+			const block = new TranscriptBlock();
+			block.addChild(new Text(theme.fg("success", `${theme.status.success} Memory report saved`), 1, 0));
+			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
+			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
+			this.ctx.chatContainer.addChild(block);
 		} catch (err) {
 			loader.stop();
 			this.ctx.statusContainer.clear();
@@ -365,10 +364,11 @@ export class DebugSelectorComponent extends Container {
 			const info = await collectSystemInfo();
 			const formatted = formatSystemInfo(info);
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(new DynamicBorder());
-			this.ctx.chatContainer.addChild(new Text(formatted, 1, 0));
-			this.ctx.chatContainer.addChild(new DynamicBorder());
+			const block = new TranscriptBlock();
+			block.addChild(new DynamicBorder());
+			block.addChild(new Text(formatted, 1, 0));
+			block.addChild(new DynamicBorder());
+			this.ctx.chatContainer.addChild(block);
 		} catch (err) {
 			this.ctx.showError(`Failed to collect system info: ${err instanceof Error ? err.message : String(err)}`);
 		}
@@ -384,10 +384,11 @@ export class DebugSelectorComponent extends Container {
 		});
 		const formatted = formatTerminalState(info);
 
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new DynamicBorder());
-		this.ctx.chatContainer.addChild(new Text(formatted, 1, 0));
-		this.ctx.chatContainer.addChild(new DynamicBorder());
+		const block = new TranscriptBlock();
+		block.addChild(new DynamicBorder());
+		block.addChild(new Text(formatted, 1, 0));
+		block.addChild(new DynamicBorder());
+		this.ctx.chatContainer.addChild(block);
 		this.ctx.ui.requestRender();
 	}
 
diff --git a/packages/coding-agent/src/modes/components/assistant-message.ts b/packages/coding-agent/src/modes/components/assistant-message.ts
index d61ae5c04..fb9995201 100644
--- a/packages/coding-agent/src/modes/components/assistant-message.ts
+++ b/packages/coding-agent/src/modes/components/assistant-message.ts
@@ -208,10 +208,6 @@ export class AssistantMessageComponent extends Container {
 			c => (c.type === "text" && c.text.trim()) || (c.type === "thinking" && c.thinking.trim()),
 		);
 
-		if (hasVisibleContent) {
-			this.#contentContainer.addChild(new Spacer(1));
-		}
-
 		// Render content in order
 		let thinkingIndex = 0;
 		for (let i = 0; i < message.content.length; i++) {
diff --git a/packages/coding-agent/src/modes/components/copy-selector.ts b/packages/coding-agent/src/modes/components/copy-selector.ts
index 08f925df0..ebc1f64d3 100644
--- a/packages/coding-agent/src/modes/components/copy-selector.ts
+++ b/packages/coding-agent/src/modes/components/copy-selector.ts
@@ -33,7 +33,6 @@ interface FlatNode {
 	ancestorHasNext: boolean[];
 }
 
-
 /** Render one tree connector as exactly three cells (e.g. "├─ ", "└─ ", "|--"). */
 function connectorCells(symbol: string): string {
 	const chars = Array.from(symbol);
diff --git a/packages/coding-agent/src/modes/components/custom-message.ts b/packages/coding-agent/src/modes/components/custom-message.ts
index 1dcd8aa62..87dd43011 100644
--- a/packages/coding-agent/src/modes/components/custom-message.ts
+++ b/packages/coding-agent/src/modes/components/custom-message.ts
@@ -1,5 +1,5 @@
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Box, Container, Spacer } from "@oh-my-pi/pi-tui";
+import { Box, Container } from "@oh-my-pi/pi-tui";
 import type { MessageRenderer } from "../../extensibility/extensions/types";
 import { theme } from "../../modes/theme/theme";
 import type { CustomMessage } from "../../session/messages";
@@ -20,8 +20,6 @@ export class CustomMessageComponent extends Container {
 	) {
 		super();
 
-		this.addChild(new Spacer(1));
-
 		// Create box with custom background (used for default rendering)
 		this.#box = new Box(1, 1, t => theme.bg("customMessageBg", t));
 
diff --git a/packages/coding-agent/src/modes/components/execution-shared.ts b/packages/coding-agent/src/modes/components/execution-shared.ts
index 0ad34a780..1f7d21135 100644
--- a/packages/coding-agent/src/modes/components/execution-shared.ts
+++ b/packages/coding-agent/src/modes/components/execution-shared.ts
@@ -7,7 +7,7 @@
  * stay in their respective files.
  */
 
-import { type Component, Container, Loader, Spacer, Text, type TUI } from "@oh-my-pi/pi-tui";
+import { type Component, Container, Loader, Text, type TUI } from "@oh-my-pi/pi-tui";
 import { getSymbolTheme, theme } from "../../modes/theme/theme";
 import { formatTruncationMetaNotice, type TruncationMeta } from "../../tools/output-meta";
 import { DynamicBorder } from "./dynamic-border";
@@ -31,7 +31,6 @@ export function buildExecutionFrame(
 ): { contentContainer: Container; loader: Loader } {
 	const borderColor = (str: string) => theme.fg(colorKey, str);
 
-	parent.addChild(new Spacer(1));
 	parent.addChild(new DynamicBorder(borderColor));
 
 	const contentContainer = new Container();
diff --git a/packages/coding-agent/src/modes/components/hook-message.ts b/packages/coding-agent/src/modes/components/hook-message.ts
index dc19d306c..0e372f160 100644
--- a/packages/coding-agent/src/modes/components/hook-message.ts
+++ b/packages/coding-agent/src/modes/components/hook-message.ts
@@ -1,5 +1,5 @@
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Box, Container, Spacer } from "@oh-my-pi/pi-tui";
+import { Box, Container } from "@oh-my-pi/pi-tui";
 import type { HookMessageRenderer } from "../../extensibility/hooks/types";
 import { theme } from "../../modes/theme/theme";
 import type { HookMessage } from "../../session/messages";
@@ -23,8 +23,6 @@ export class HookMessageComponent extends Container {
 	) {
 		super();
 
-		this.addChild(new Spacer(1));
-
 		// Create box with purple background (used for default rendering)
 		this.#box = new Box(1, 1, t => theme.bg("customMessageBg", t));
 
diff --git a/packages/coding-agent/src/modes/components/skill-message.ts b/packages/coding-agent/src/modes/components/skill-message.ts
index 3187b30da..f2aeb41d0 100644
--- a/packages/coding-agent/src/modes/components/skill-message.ts
+++ b/packages/coding-agent/src/modes/components/skill-message.ts
@@ -11,7 +11,6 @@ export class SkillMessageComponent extends Container {
 
 	constructor(private readonly message: CustomMessage<SkillPromptDetails>) {
 		super();
-		this.addChild(new Spacer(1));
 
 		this.#box = new Box(1, 1, t => theme.bg("customMessageBg", t));
 		this.#rebuild();
diff --git a/packages/coding-agent/src/modes/components/todo-reminder.ts b/packages/coding-agent/src/modes/components/todo-reminder.ts
index 0a536d73d..2d8bcf173 100644
--- a/packages/coding-agent/src/modes/components/todo-reminder.ts
+++ b/packages/coding-agent/src/modes/components/todo-reminder.ts
@@ -16,8 +16,6 @@ export class TodoReminderComponent extends Container {
 	) {
 		super();
 
-		this.addChild(new Spacer(1));
-
 		this.#box = new Box(1, 1, t => theme.inverse(theme.fg("warning", t)));
 		this.addChild(this.#box);
 
diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index 043fbe439..3365526ef 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -245,11 +245,10 @@ export class ToolExecutionComponent extends Container {
 		this.#cwd = cwd;
 		this.#args = args;
 
-		this.addChild(new Spacer(1));
-
-		// Always create both - contentBox for custom tools/bash/tools with renderers, contentText for other built-ins
-		this.#contentBox = new Box(1, 1, (text: string) => theme.bg("toolPendingBg", text));
-		this.#contentText = new Text("", 1, 1, (text: string) => theme.bg("toolPendingBg", text));
+		// Always create both - contentBox for custom tools/bash/tools with renderers, contentText for other built-ins.
+		// paddingY is 0: the transcript owns inter-block spacing (see TranscriptContainer).
+		this.#contentBox = new Box(1, 0, (text: string) => theme.bg("toolPendingBg", text));
+		this.#contentText = new Text("", 1, 0, (text: string) => theme.bg("toolPendingBg", text));
 
 		// Use Box for custom tools or built-in tools that have renderers
 		const hasRenderer = toolName in toolRenderers;
diff --git a/packages/coding-agent/src/modes/components/transcript-container.ts b/packages/coding-agent/src/modes/components/transcript-container.ts
index b33a818bd..c3d7cf545 100644
--- a/packages/coding-agent/src/modes/components/transcript-container.ts
+++ b/packages/coding-agent/src/modes/components/transcript-container.ts
@@ -39,6 +39,26 @@ function isBlockAppendOnly(child: Component): boolean {
 	return fn ? fn.call(child) : false;
 }
 
+// A "plain blank" row is empty or whitespace-only with no ANSI bytes. It marks
+// separation padding (a `Spacer`, or a no-background `paddingY` row) as opposed
+// to a background-colored padding row, whose escape sequences contain `\S` and
+// are therefore preserved as part of a block's visual design.
+const NON_WHITESPACE = /\S/;
+function isPlainBlank(line: string): boolean {
+	return !NON_WHITESPACE.test(line);
+}
+
+// Strip leading/trailing plain-blank rows so each block contributes only its
+// visible body; the container owns the gaps between blocks. Returns the input
+// array unchanged when there is nothing to trim (no allocation on the hot path).
+function stripPlainBlankEdges(lines: string[]): string[] {
+	let start = 0;
+	let end = lines.length;
+	while (start < end && isPlainBlank(lines[start]!)) start++;
+	while (end > start && isPlainBlank(lines[end - 1]!)) end--;
+	return start === 0 && end === lines.length ? lines : lines.slice(start, end);
+}
+
 /**
  * Transcript container that freezes the rendered output of every block except
  * the bottom-most (live) one on terminals where committed native scrollback is
@@ -118,9 +138,13 @@ export class TranscriptContainer extends Container implements NativeScrollbackLi
 		width = Math.max(1, width);
 		this.#nativeScrollbackLiveRegionStart = undefined;
 		this.#nativeScrollbackCommitSafeEnd = undefined;
-		if (!TERMINAL.eagerEraseScrollbackRisk) return super.render(width);
 
+		// Freezing/snapshotting only applies on ED3-risk terminals; elsewhere every
+		// block renders live. Inter-block spacing applies on BOTH paths so the gap
+		// between blocks is identical regardless of terminal.
+		const risk = TERMINAL.eagerEraseScrollbackRisk;
 		const count = this.children.length;
+
 		// The live region spans from the earliest still-mutating block through the
 		// bottom. A block that has not finalized must stay repaintable: out-of-band
 		// inserts (TTSR/todo cards) can append a finalized block *below* a tool that
@@ -137,45 +161,81 @@ export class TranscriptContainer extends Container implements NativeScrollbackLi
 		// recompute them so they freeze at their final content. Everything below
 		// the lower of the two cutoffs was already frozen last frame and replays.
 		const replayCutoff = Math.min(liveStartIndex, this.#prevLiveStartIndex);
-		this.#prevLiveStartIndex = liveStartIndex;
+		if (risk) this.#prevLiveStartIndex = liveStartIndex;
 
 		const lines: string[] = [];
 		// Tracks whether we are still inside the leading run of append-only live
-		// blocks. The first non-append-only live block (or a finalized block below
-		// the live region's start, which cannot happen for a leading run) closes it.
+		// blocks. The first non-append-only live block closes it.
 		let commitSafeOpen = true;
+		// The live-region start is recorded at the first visible row at/after the
+		// cutoff; empty leading blocks (or a separator) must not claim it early.
+		let liveRecorded = false;
 		for (let i = 0; i < count; i++) {
 			const child = this.children[i]! as Component & SnapshotCarrier;
-			if (i >= liveStartIndex) {
-				if (i === liveStartIndex) this.#nativeScrollbackLiveRegionStart = lines.length;
-			} else {
+
+			// Resolve this child's contribution — its visible body with plain-blank
+			// top/bottom edges stripped (the container owns inter-block gaps). On
+			// ED3-risk terminals a frozen, scrolled-off block replays its snapshot
+			// instead of recomputing; a stale generation (post-thaw) or width
+			// mismatch (resize) recomputes, as does a block still live last frame.
+			let contribution: string[] | undefined;
+			if (risk && i < liveStartIndex && i < replayCutoff) {
 				const snapshot = child[kSnapshot];
-				// Replay a frozen block's last live render. A stale generation
-				// (post-thaw) or width mismatch (resize, explicit rebuild) recomputes
-				// instead, as does a block that was still live last frame (i >= cutoff).
-				if (i < replayCutoff && snapshot && snapshot.generation === this.#generation && snapshot.width === width) {
-					lines.push(...snapshot.lines);
-					continue;
+				if (snapshot && snapshot.generation === this.#generation && snapshot.width === width) {
+					contribution = snapshot.lines;
 				}
 			}
-			const rendered = child.render(width);
+			if (contribution === undefined) {
+				const rendered = child.render(width);
+				contribution = stripPlainBlankEdges(rendered);
+				// Cache every block's latest contribution. While a block is in the
+				// live region this keeps its snapshot current; on the frame it crosses
+				// out, the recompute above refreshes it before it freezes.
+				if (risk) child[kSnapshot] = { width, lines: contribution, generation: this.#generation };
+			}
+
+			// Empty (or stripped-to-nothing) children contribute nothing and never
+			// affect spacing or the live-region offsets.
+			if (contribution.length === 0) continue;
+
+			// Every block is separated from preceding visible content by exactly one
+			// blank row — skipped when it opens the transcript or the prior row is
+			// already a plain blank (a fragment's own trailing pad), never doubling.
+			const sep = lines.length > 0 && !isPlainBlank(lines[lines.length - 1]!) ? 1 : 0;
+
+			// The separator before the first live block stays in the committed prefix
+			// (it is deterministic and never changes once the prior block is frozen),
+			// so the live region begins at the block's first content row.
+			if (risk && !liveRecorded && i >= liveStartIndex) {
+				this.#nativeScrollbackLiveRegionStart = lines.length + sep;
+				liveRecorded = true;
+			}
+
+			if (sep) lines.push("");
+			for (let j = 0; j < contribution.length; j++) lines.push(contribution[j]!);
+
 			// Extend the commit-safe boundary through each leading append-only live
-			// block. `lines.length` here is this block's start offset; the boundary
-			// runs to the end of its rendered rows. The first volatile live block
-			// closes the run so its mutable rows stay deferred.
-			if (i >= liveStartIndex && commitSafeOpen) {
+			// block. The first volatile live block closes the run so its mutable
+			// rows stay deferred.
+			if (risk && i >= liveStartIndex && commitSafeOpen) {
 				if (isBlockAppendOnly(child)) {
-					this.#nativeScrollbackCommitSafeEnd = lines.length + rendered.length;
+					this.#nativeScrollbackCommitSafeEnd = lines.length;
 				} else {
 					commitSafeOpen = false;
 				}
 			}
-			// Cache every block's latest render. While a block is in the live region
-			// this keeps its snapshot current; on the frame it crosses out, the
-			// recompute above refreshes it to the final state before it freezes.
-			child[kSnapshot] = { width, lines: rendered, generation: this.#generation };
-			lines.push(...rendered);
 		}
 		return lines;
 	}
 }
+
+/**
+ * Groups a run of sibling rows (an IRC card's header + body, a file-mention
+ * list, a bordered command/version panel) into a single transcript child so the
+ * container spaces it as one block — one blank line above, none injected between
+ * its rows. Without this wrapper the rows would be top-level children and the
+ * container would put a blank line between each (and inside any border box).
+ * It is a plain {@link Container}; the named subclass documents intent and makes
+ * every manual block grouping greppable.
+ */
+export class TranscriptBlock extends Container {}
diff --git a/packages/coding-agent/src/modes/components/user-message.ts b/packages/coding-agent/src/modes/components/user-message.ts
index c03eb7e73..e393a4ef3 100644
--- a/packages/coding-agent/src/modes/components/user-message.ts
+++ b/packages/coding-agent/src/modes/components/user-message.ts
@@ -1,4 +1,4 @@
-import { Container, Markdown, Spacer } from "@oh-my-pi/pi-tui";
+import { Container, Markdown } from "@oh-my-pi/pi-tui";
 import { getMarkdownTheme, theme } from "../../modes/theme/theme";
 import { imageReferenceHyperlink, renderImageReferences } from "../image-references";
 import { highlightMagicKeywords } from "../magic-keywords";
@@ -30,7 +30,6 @@ export class UserMessageComponent extends Container {
 				renderText: baseText,
 				renderReference: (label, index) => imageReferenceHyperlink(label, index, imageLinks, imageLabel),
 			});
-		this.addChild(new Spacer(1));
 		this.addChild(
 			new Markdown(text, 1, 1, getMarkdownTheme(), {
 				bgColor,
diff --git a/packages/coding-agent/src/modes/controllers/command-controller-shared.ts b/packages/coding-agent/src/modes/controllers/command-controller-shared.ts
index ba119d512..7ee9c9499 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller-shared.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller-shared.ts
@@ -7,10 +7,11 @@
  * wording, and add-flow logic stay in the per-controller files because they
  * diverge in workflow.
  */
-import { Spacer, Text } from "@oh-my-pi/pi-tui";
+import { Text } from "@oh-my-pi/pi-tui";
 import type { SourceMeta } from "../../capability/types";
 import { shortenPath } from "../../tools/render-utils";
 import { DynamicBorder } from "../components/dynamic-border";
+import { TranscriptBlock } from "../components/transcript-container";
 import { parseCommandArgs } from "../shared";
 import type { InteractiveModeContext } from "../types";
 
@@ -100,9 +101,10 @@ export function* groupBySource<T>(
  * container and request a render.
  */
 export function showCommandMessage(ctx: InteractiveModeContext, text: string): void {
-	ctx.chatContainer.addChild(new Spacer(1));
-	ctx.chatContainer.addChild(new DynamicBorder());
-	ctx.chatContainer.addChild(new Text(text, 1, 1));
-	ctx.chatContainer.addChild(new DynamicBorder());
+	const block = new TranscriptBlock();
+	block.addChild(new DynamicBorder());
+	block.addChild(new Text(text, 1, 1));
+	block.addChild(new DynamicBorder());
+	ctx.chatContainer.addChild(block);
 	ctx.ui.requestRender();
 }
diff --git a/packages/coding-agent/src/modes/controllers/command-controller.ts b/packages/coding-agent/src/modes/controllers/command-controller.ts
index 23462c9a2..942392430 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller.ts
@@ -28,6 +28,7 @@ import { BashExecutionComponent } from "../../modes/components/bash-execution";
 import { BorderedLoader } from "../../modes/components/bordered-loader";
 import { DynamicBorder } from "../../modes/components/dynamic-border";
 import { EvalExecutionComponent } from "../../modes/components/eval-execution";
+import { TranscriptBlock } from "../../modes/components/transcript-container";
 import { getMarkdownTheme, getSymbolTheme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext } from "../../modes/types";
 import { computeContextBreakdown, renderContextUsage } from "../../modes/utils/context-usage";
@@ -46,12 +47,13 @@ import { openPath } from "../../utils/open";
 import { setSessionTerminalTitle } from "../../utils/title-generator";
 
 function showMarkdownPanel(ctx: InteractiveModeContext, title: string, markdown: string): void {
-	ctx.chatContainer.addChild(new Spacer(1));
-	ctx.chatContainer.addChild(new DynamicBorder());
-	ctx.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", title)), 1, 0));
-	ctx.chatContainer.addChild(new Spacer(1));
-	ctx.chatContainer.addChild(new Markdown(markdown.trim(), 1, 1, getMarkdownTheme()));
-	ctx.chatContainer.addChild(new DynamicBorder());
+	const block = new TranscriptBlock();
+	block.addChild(new DynamicBorder());
+	block.addChild(new Text(theme.bold(theme.fg("accent", title)), 1, 0));
+	block.addChild(new Spacer(1));
+	block.addChild(new Markdown(markdown.trim(), 1, 1, getMarkdownTheme()));
+	block.addChild(new DynamicBorder());
+	ctx.chatContainer.addChild(block);
 	ctx.ui.requestRender();
 }
 
@@ -426,12 +428,13 @@ export class CommandController {
 			? ""
 			: `\n\n${theme.fg("dim", "Use")} ${theme.bold("/changelog full")} ${theme.fg("dim", "to view the complete changelog.")}`;
 
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new DynamicBorder());
-		this.ctx.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", title)), 1, 0));
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Markdown(changelogMarkdown + hint, 1, 1, getMarkdownTheme()));
-		this.ctx.chatContainer.addChild(new DynamicBorder());
+		const block = new TranscriptBlock();
+		block.addChild(new DynamicBorder());
+		block.addChild(new Text(theme.bold(theme.fg("accent", title)), 1, 0));
+		block.addChild(new Spacer(1));
+		block.addChild(new Markdown(changelogMarkdown + hint, 1, 1, getMarkdownTheme()));
+		block.addChild(new DynamicBorder());
+		this.ctx.chatContainer.addChild(block);
 		this.ctx.ui.requestRender();
 	}
 
@@ -452,12 +455,13 @@ export class CommandController {
 			return;
 		}
 		const output = renderContextUsage(breakdown, theme);
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new DynamicBorder());
-		this.ctx.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", "Context Usage")), 1, 0));
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(output, 1, 0));
-		this.ctx.chatContainer.addChild(new DynamicBorder());
+		const block = new TranscriptBlock();
+		block.addChild(new DynamicBorder());
+		block.addChild(new Text(theme.bold(theme.fg("accent", "Context Usage")), 1, 0));
+		block.addChild(new Spacer(1));
+		block.addChild(new Text(output, 1, 0));
+		block.addChild(new DynamicBorder());
+		this.ctx.chatContainer.addChild(block);
 		this.ctx.ui.requestRender();
 	}
 
@@ -473,12 +477,13 @@ export class CommandController {
 				this.ctx.showWarning("Memory payload is empty (memory backend off, disabled, or no memory available).");
 				return;
 			}
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(new DynamicBorder());
-			this.ctx.chatContainer.addChild(new Text(theme.bold(theme.fg("accent", "Memory Injection Payload")), 1, 0));
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(new Markdown(payload, 1, 1, getMarkdownTheme()));
-			this.ctx.chatContainer.addChild(new DynamicBorder());
+			const block = new TranscriptBlock();
+			block.addChild(new DynamicBorder());
+			block.addChild(new Text(theme.bold(theme.fg("accent", "Memory Injection Payload")), 1, 0));
+			block.addChild(new Spacer(1));
+			block.addChild(new Markdown(payload, 1, 1, getMarkdownTheme()));
+			block.addChild(new DynamicBorder());
+			this.ctx.chatContainer.addChild(block);
 			this.ctx.ui.requestRender();
 			return;
 		}
diff --git a/packages/coding-agent/src/modes/controllers/event-controller.ts b/packages/coding-agent/src/modes/controllers/event-controller.ts
index 7b9fb1ba7..66497e783 100644
--- a/packages/coding-agent/src/modes/controllers/event-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/event-controller.ts
@@ -1,7 +1,7 @@
 import { INTENT_FIELD } from "@oh-my-pi/pi-agent-core";
 import { calculatePromptTokens } from "@oh-my-pi/pi-agent-core/compaction/compaction";
 import type { AssistantMessage, ImageContent } from "@oh-my-pi/pi-ai";
-import { type Component, Loader, TERMINAL, Text } from "@oh-my-pi/pi-tui";
+import { type Component, Loader, TERMINAL } from "@oh-my-pi/pi-tui";
 import { settings } from "../../config/settings";
 import { getFileSnapshotStore } from "../../edit/file-snapshot-store";
 import { AssistantMessageComponent } from "../../modes/components/assistant-message";
@@ -108,7 +108,6 @@ export class EventController {
 
 	#getReadGroup(): ReadToolGroupComponent {
 		if (!this.#lastReadGroup) {
-			this.ctx.chatContainer.addChild(new Text("", 0, 0));
 			const group = new ReadToolGroupComponent({
 				showContentPreview: this.ctx.settings.get("read.toolResultPreview"),
 			});
@@ -397,7 +396,6 @@ export class EventController {
 						: content.arguments;
 				if (!this.ctx.pendingTools.has(content.id)) {
 					this.#resetReadGroup();
-					this.ctx.chatContainer.addChild(new Text("", 0, 0));
 					const tool = this.ctx.session.getToolByName(content.name);
 					const component = new ToolExecutionComponent(
 						content.name,
diff --git a/packages/coding-agent/src/modes/controllers/mcp-command-controller.ts b/packages/coding-agent/src/modes/controllers/mcp-command-controller.ts
index 756328b4b..86fb385af 100644
--- a/packages/coding-agent/src/modes/controllers/mcp-command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/mcp-command-controller.ts
@@ -38,6 +38,7 @@ import type { OAuthCredential } from "../../session/auth-storage";
 import { shortenPath } from "../../tools/render-utils";
 import { openPath } from "../../utils/open";
 import { MCPAddWizard } from "../components/mcp-add-wizard";
+import { TranscriptBlock } from "../components/transcript-container";
 import { parseCommandArgs } from "../shared";
 import { theme } from "../theme/theme";
 import type { InteractiveModeContext } from "../types";
@@ -547,56 +548,41 @@ export class MCPCommandController {
 				},
 				{
 					onAuth: (info: { url: string; instructions?: string }) => {
-						// Show auth URL prominently in chat
-						this.ctx.chatContainer.addChild(new Spacer(1));
-						this.ctx.chatContainer.addChild(
-							new Text(theme.fg("accent", "━━━ OAuth Authorization Required ━━━"), 1, 0),
-						);
-						this.ctx.chatContainer.addChild(new Spacer(1));
-						this.ctx.chatContainer.addChild(
-							new Text(theme.fg("muted", "Preparing browser authorization..."), 1, 0),
-						);
-						this.ctx.chatContainer.addChild(new Spacer(1));
-						this.ctx.chatContainer.addChild(
+						// Show auth URL prominently in chat as one block
+						const block = new TranscriptBlock();
+						this.ctx.chatContainer.addChild(block);
+						block.addChild(new Text(theme.fg("accent", "━━━ OAuth Authorization Required ━━━"), 1, 0));
+						block.addChild(new Spacer(1));
+						block.addChild(new Text(theme.fg("muted", "Preparing browser authorization..."), 1, 0));
+						block.addChild(new Spacer(1));
+						block.addChild(
 							new Text(
 								theme.fg("muted", "Waiting for authorization... (Press Ctrl+C to cancel, 5 minute timeout)"),
 								1,
 								0,
 							),
 						);
-						this.ctx.chatContainer.addChild(new Spacer(1));
-						this.ctx.chatContainer.addChild(
-							new Text(theme.fg("accent", "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"), 1, 0),
-						);
+						block.addChild(new Spacer(1));
+						block.addChild(new Text(theme.fg("accent", "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"), 1, 0));
 						this.ctx.ui.requestRender();
 						// Try to open browser automatically
 						try {
 							openPath(info.url);
 
 							// Show confirmation that browser should open
-							this.ctx.chatContainer.addChild(new Spacer(1));
-							this.ctx.chatContainer.addChild(
-								new Text(theme.fg("success", "→ Opening browser automatically..."), 1, 0),
-							);
-							this.ctx.chatContainer.addChild(new Spacer(1));
-							this.ctx.chatContainer.addChild(
-								new Text(theme.fg("muted", "Alternative if browser did not open:"), 1, 0),
-							);
-							this.ctx.chatContainer.addChild(
-								new Text(theme.fg("success", "Copy this exact URL in your browser:"), 1, 0),
-							);
-							this.ctx.chatContainer.addChild(new Text(theme.fg("accent", info.url), 1, 0));
+							block.addChild(new Spacer(1));
+							block.addChild(new Text(theme.fg("success", "→ Opening browser automatically..."), 1, 0));
+							block.addChild(new Spacer(1));
+							block.addChild(new Text(theme.fg("muted", "Alternative if browser did not open:"), 1, 0));
+							block.addChild(new Text(theme.fg("success", "Copy this exact URL in your browser:"), 1, 0));
+							block.addChild(new Text(theme.fg("accent", info.url), 1, 0));
 							this.ctx.ui.requestRender();
 						} catch (_error) {
 							// Show error if browser doesn't open
-							this.ctx.chatContainer.addChild(new Spacer(1));
-							this.ctx.chatContainer.addChild(
-								new Text(theme.fg("warning", "→ Could not open browser automatically"), 1, 0),
-							);
-							this.ctx.chatContainer.addChild(
-								new Text(theme.fg("success", "Copy this exact URL in your browser:"), 1, 0),
-							);
-							this.ctx.chatContainer.addChild(new Text(theme.fg("accent", info.url), 1, 0));
+							block.addChild(new Spacer(1));
+							block.addChild(new Text(theme.fg("warning", "→ Could not open browser automatically"), 1, 0));
+							block.addChild(new Text(theme.fg("success", "Copy this exact URL in your browser:"), 1, 0));
+							block.addChild(new Text(theme.fg("accent", info.url), 1, 0));
 							this.ctx.ui.requestRender();
 						}
 					},
diff --git a/packages/coding-agent/src/modes/controllers/selector-controller.ts b/packages/coding-agent/src/modes/controllers/selector-controller.ts
index b6c7cfffe..7aa831822 100644
--- a/packages/coding-agent/src/modes/controllers/selector-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/selector-controller.ts
@@ -50,6 +50,7 @@ import { SessionObserverOverlayComponent } from "../components/session-observer-
 import { SessionSelectorComponent } from "../components/session-selector";
 import { SettingsSelectorComponent } from "../components/settings-selector";
 import { ToolExecutionComponent } from "../components/tool-execution";
+import { TranscriptBlock } from "../components/transcript-container";
 import { TreeSelectorComponent } from "../components/tree-selector";
 import { UserMessageSelectorComponent } from "../components/user-message-selector";
 import type { SessionObserverRegistry } from "../session-observer-registry";
@@ -931,26 +932,28 @@ export class SelectorController {
 		try {
 			await this.ctx.session.modelRegistry.authStorage.login(providerId as OAuthProvider, {
 				onAuth: (info: { url: string; instructions?: string }) => {
-					this.ctx.chatContainer.addChild(new Spacer(1));
-					this.ctx.chatContainer.addChild(new Text(theme.fg("dim", info.url), 1, 0));
+					const block = new TranscriptBlock();
+					this.ctx.chatContainer.addChild(block);
+					block.addChild(new Text(theme.fg("dim", info.url), 1, 0));
 					const hyperlink = `\x1b]8;;${info.url}\x07Click here to login\x1b]8;;\x07`;
-					this.ctx.chatContainer.addChild(new Text(theme.fg("accent", hyperlink), 1, 0));
+					block.addChild(new Text(theme.fg("accent", hyperlink), 1, 0));
 					if (info.instructions) {
-						this.ctx.chatContainer.addChild(new Spacer(1));
-						this.ctx.chatContainer.addChild(new Text(theme.fg("warning", info.instructions), 1, 0));
+						block.addChild(new Spacer(1));
+						block.addChild(new Text(theme.fg("warning", info.instructions), 1, 0));
 					}
 					if (useManualInput) {
-						this.ctx.chatContainer.addChild(new Spacer(1));
-						this.ctx.chatContainer.addChild(new Text(theme.fg("dim", MANUAL_LOGIN_TIP), 1, 0));
+						block.addChild(new Spacer(1));
+						block.addChild(new Text(theme.fg("dim", MANUAL_LOGIN_TIP), 1, 0));
 					}
 					this.ctx.ui.requestRender();
 					this.ctx.openInBrowser(info.url);
 				},
 				onPrompt: async (prompt: { message: string; placeholder?: string }) => {
-					this.ctx.chatContainer.addChild(new Spacer(1));
-					this.ctx.chatContainer.addChild(new Text(theme.fg("warning", prompt.message), 1, 0));
+					const promptBlock = new TranscriptBlock();
+					this.ctx.chatContainer.addChild(promptBlock);
+					promptBlock.addChild(new Text(theme.fg("warning", prompt.message), 1, 0));
 					if (prompt.placeholder) {
-						this.ctx.chatContainer.addChild(new Text(theme.fg("dim", prompt.placeholder), 1, 0));
+						promptBlock.addChild(new Text(theme.fg("dim", prompt.placeholder), 1, 0));
 					}
 					this.ctx.ui.requestRender();
 					const { promise, resolve } = Promise.withResolvers<string>();
@@ -975,11 +978,12 @@ export class SelectorController {
 				onManualCodeInput: useManualInput ? () => manualInput.waitForInput(providerId) : undefined,
 			});
 			await this.ctx.session.modelRegistry.refresh();
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
+			const block = new TranscriptBlock();
+			block.addChild(
 				new Text(theme.fg("success", `${theme.status.success} Successfully logged in to ${providerId}`), 1, 0),
 			);
-			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", `Credentials saved to ${getAgentDbPath()}`), 1, 0));
+			block.addChild(new Text(theme.fg("dim", `Credentials saved to ${getAgentDbPath()}`), 1, 0));
+			this.ctx.chatContainer.addChild(block);
 			this.ctx.ui.requestRender();
 		} catch (error: unknown) {
 			this.ctx.showError(`Login failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -1002,19 +1006,18 @@ export class SelectorController {
 
 			await authStorage.logout(providerId);
 			await this.ctx.session.modelRegistry.refresh();
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
+			const block = new TranscriptBlock();
+			block.addChild(
 				new Text(theme.fg("success", `${theme.status.success} Successfully logged out of ${providerId}`), 1, 0),
 			);
-			this.ctx.chatContainer.addChild(
-				new Text(theme.fg("dim", `Credentials removed from ${getAgentDbPath()}`), 1, 0),
-			);
+			block.addChild(new Text(theme.fg("dim", `Credentials removed from ${getAgentDbPath()}`), 1, 0));
 			const remainingSource = authStorage.describeCredentialSource(providerId, this.ctx.session.sessionId);
 			if (remainingSource) {
-				this.ctx.chatContainer.addChild(
+				block.addChild(
 					new Text(theme.fg("warning", `${providerId} is still authenticated via ${remainingSource}`), 1, 0),
 				);
 			}
+			this.ctx.chatContainer.addChild(block);
 			this.ctx.ui.requestRender();
 		} catch (error: unknown) {
 			this.ctx.showError(`Logout failed: ${error instanceof Error ? error.message : String(error)}`);
diff --git a/packages/coding-agent/src/modes/utils/copy-targets.ts b/packages/coding-agent/src/modes/utils/copy-targets.ts
index 5da1f9ebe..6ded2aba8 100644
--- a/packages/coding-agent/src/modes/utils/copy-targets.ts
+++ b/packages/coding-agent/src/modes/utils/copy-targets.ts
@@ -101,7 +101,8 @@ export function extractBlocks(text: string): MessageBlock[] {
 		const quoted = QUOTE_LINE_RE.exec(line);
 		if (quoted) {
 			// Strip the `>` marker plus one optional following space.
-			(quote ??= []).push(quoted[1].startsWith(" ") ? quoted[1].slice(1) : quoted[1]);
+			quote ??= [];
+			quote.push(quoted[1].startsWith(" ") ? quoted[1].slice(1) : quoted[1]);
 		} else {
 			flushQuote();
 		}
diff --git a/packages/coding-agent/src/modes/utils/ui-helpers.ts b/packages/coding-agent/src/modes/utils/ui-helpers.ts
index b3d70de4b..fca5bea57 100644
--- a/packages/coding-agent/src/modes/utils/ui-helpers.ts
+++ b/packages/coding-agent/src/modes/utils/ui-helpers.ts
@@ -17,6 +17,7 @@ import {
 } from "../../modes/components/read-tool-group";
 import { SkillMessageComponent } from "../../modes/components/skill-message";
 import { ToolExecutionComponent } from "../../modes/components/tool-execution";
+import { TranscriptBlock } from "../../modes/components/transcript-container";
 import { UserMessageComponent } from "../../modes/components/user-message";
 import { materializeImageReferenceLinksSync } from "../../modes/image-references";
 import { theme } from "../../modes/theme/theme";
@@ -153,6 +154,7 @@ export class UiHelpers {
 											durationMs: details?.durationMs,
 										},
 									];
+						const block = new TranscriptBlock();
 						for (const job of jobs) {
 							const jobId = job.jobId ?? "unknown";
 							const typeLabel = job.type ? `[${job.type}]` : "[job]";
@@ -165,8 +167,9 @@ export class UiHelpers {
 							]
 								.filter(Boolean)
 								.join(" ");
-							this.ctx.chatContainer.addChild(new Text(line, 1, 0));
+							block.addChild(new Text(line, 1, 0));
 						}
+						this.ctx.chatContainer.addChild(block);
 						break;
 					}
 					if (message.customType === SKILL_PROMPT_MESSAGE_TYPE) {
@@ -206,19 +209,18 @@ export class UiHelpers {
 							body = details?.body ?? "";
 							arrow = `${from} ⇨ ${to}`;
 						}
-						const components: Component[] = [];
+						const block = new TranscriptBlock();
 						const header = `${theme.fg("accent", `[IRC] ${arrow}`)}`;
 						const headerComponent = new Text(header, 1, 0);
-						this.ctx.chatContainer.addChild(headerComponent);
-						components.push(headerComponent);
+						block.addChild(headerComponent);
 						if (body) {
 							for (const line of body.split("\n")) {
 								const lineComponent = new Text(theme.fg("muted", `  ${line}`), 0, 0);
-								this.ctx.chatContainer.addChild(lineComponent);
-								components.push(lineComponent);
+								block.addChild(lineComponent);
 							}
 						}
-						return components;
+						this.ctx.chatContainer.addChild(block);
+						return [block];
 					}
 					const renderer = this.ctx.session.extensionRunner?.getMessageRenderer(message.customType);
 					// Both HookMessage and CustomMessage have the same structure, cast for compatibility
@@ -229,14 +231,12 @@ export class UiHelpers {
 				break;
 			}
 			case "compactionSummary": {
-				this.ctx.chatContainer.addChild(new Spacer(1));
 				const component = new CompactionSummaryMessageComponent(message);
 				component.setExpanded(this.ctx.toolOutputExpanded);
 				this.ctx.chatContainer.addChild(component);
 				break;
 			}
 			case "branchSummary": {
-				this.ctx.chatContainer.addChild(new Spacer(1));
 				const component = new BranchSummaryMessageComponent(message);
 				component.setExpanded(this.ctx.toolOutputExpanded);
 				this.ctx.chatContainer.addChild(component);
@@ -244,6 +244,7 @@ export class UiHelpers {
 			}
 			case "fileMention": {
 				// Render compact file mention display
+				const block = new TranscriptBlock();
 				for (const file of message.files) {
 					let suffix: string;
 					if (file.skippedReason === "tooLarge") {
@@ -260,8 +261,9 @@ export class UiHelpers {
 						"accent",
 						file.path,
 					)} ${theme.fg("dim", suffix)}`;
-					this.ctx.chatContainer.addChild(new Text(text, 0, 0));
+					block.addChild(new Text(text, 0, 0));
 				}
+				if (block.children.length > 0) this.ctx.chatContainer.addChild(block);
 				break;
 			}
 			case "user":
@@ -558,9 +560,9 @@ export class UiHelpers {
 	}
 
 	showNewVersionNotification(newVersion: string): void {
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new DynamicBorder(text => theme.fg("warning", text)));
-		this.ctx.chatContainer.addChild(
+		const block = new TranscriptBlock();
+		block.addChild(new DynamicBorder(text => theme.fg("warning", text)));
+		block.addChild(
 			new Text(
 				theme.bold(theme.fg("warning", "Update Available")) +
 					"\n" +
@@ -570,7 +572,8 @@ export class UiHelpers {
 				0,
 			),
 		);
-		this.ctx.chatContainer.addChild(new DynamicBorder(text => theme.fg("warning", text)));
+		block.addChild(new DynamicBorder(text => theme.fg("warning", text)));
+		this.ctx.chatContainer.addChild(block);
 		this.ctx.ui.requestRender();
 	}
 
diff --git a/packages/coding-agent/test/modes/components/transcript-container.test.ts b/packages/coding-agent/test/modes/components/transcript-container.test.ts
index a1b385eae..19db5f80e 100644
--- a/packages/coding-agent/test/modes/components/transcript-container.test.ts
+++ b/packages/coding-agent/test/modes/components/transcript-container.test.ts
@@ -107,16 +107,16 @@ describe("TranscriptContainer", () => {
 		// A newer block makes `a` non-live; it now replays its last live render.
 		const b = new MutableBlock(["b1"]);
 		container.addChild(b);
-		expect(container.render(40)).toEqual(["a2", "b1"]);
+		expect(container.render(40)).toEqual(["a2", "", "b1"]);
 
 		// A post-freeze mutation of `a` (its collapse/re-layout) is NOT reflected —
 		// the committed rows stay stable so no stale duplicate enters scrollback.
 		a.set(["a3-collapsed"]);
-		expect(container.render(40)).toEqual(["a2", "b1"]);
+		expect(container.render(40)).toEqual(["a2", "", "b1"]);
 
 		// The live block still updates freely.
 		b.set(["b2"]);
-		expect(container.render(40)).toEqual(["a2", "b2"]);
+		expect(container.render(40)).toEqual(["a2", "", "b2"]);
 	});
 
 	it("reports the live block start for native scrollback pinning (ED3-risk)", () => {
@@ -127,12 +127,12 @@ describe("TranscriptContainer", () => {
 		container.addChild(a);
 		container.addChild(b);
 
-		expect(container.render(40)).toEqual(["a1", "a2", "b1"]);
-		expect(container.getNativeScrollbackLiveRegionStart()).toBe(2);
+		expect(container.render(40)).toEqual(["a1", "a2", "", "b1"]);
+		expect(container.getNativeScrollbackLiveRegionStart()).toBe(3);
 
 		b.set(["b1", "b2"]);
-		expect(container.render(40)).toEqual(["a1", "a2", "b1", "b2"]);
-		expect(container.getNativeScrollbackLiveRegionStart()).toBe(2);
+		expect(container.render(40)).toEqual(["a1", "a2", "", "b1", "b2"]);
+		expect(container.getNativeScrollbackLiveRegionStart()).toBe(3);
 	});
 
 	it("seals the prior block at its final content when finalize+append coalesce (ED3-risk)", () => {
@@ -151,11 +151,11 @@ describe("TranscriptContainer", () => {
 
 		// The transition frame must seal `a` at its final content, not the stale
 		// mid-stream snapshot ("Nat") it last rendered while live.
-		expect(container.render(40)).toEqual(["Natives built, now...", "b1"]);
+		expect(container.render(40)).toEqual(["Natives built, now...", "", "b1"]);
 
 		// Once sealed, a later re-layout of `a` stays frozen until the next thaw.
 		a.set(["a-collapsed"]);
-		expect(container.render(40)).toEqual(["Natives built, now...", "b1"]);
+		expect(container.render(40)).toEqual(["Natives built, now...", "", "b1"]);
 	});
 
 	it("thaw() reconciles frozen blocks to their current state", () => {
@@ -167,10 +167,10 @@ describe("TranscriptContainer", () => {
 		container.addChild(b);
 		container.render(40);
 		a.set(["a-final"]);
-		expect(container.render(40)).toEqual(["a1", "b1"]); // frozen
+		expect(container.render(40)).toEqual(["a1", "", "b1"]); // frozen
 
 		container.thaw();
-		expect(container.render(40)).toEqual(["a-final", "b1"]); // reconciled
+		expect(container.render(40)).toEqual(["a-final", "", "b1"]); // reconciled
 	});
 
 	it("invalidate() retires frozen snapshots so resetDisplay reflects current state", () => {
@@ -186,10 +186,10 @@ describe("TranscriptContainer", () => {
 		container.addChild(b);
 		container.render(40);
 		a.set(["a-expanded-1", "a-expanded-2"]);
-		expect(container.render(40)).toEqual(["a-collapsed", "b1"]); // frozen
+		expect(container.render(40)).toEqual(["a-collapsed", "", "b1"]); // frozen
 
 		container.invalidate();
-		expect(container.render(40)).toEqual(["a-expanded-1", "a-expanded-2", "b1"]);
+		expect(container.render(40)).toEqual(["a-expanded-1", "a-expanded-2", "", "b1"]);
 	});
 
 	it("recomputes a frozen block on a width change", () => {
@@ -201,9 +201,9 @@ describe("TranscriptContainer", () => {
 		container.addChild(b);
 		container.render(40);
 		a.set(["a-reflowed"]);
-		expect(container.render(40)).toEqual(["a1", "b1"]); // frozen at width 40
+		expect(container.render(40)).toEqual(["a1", "", "b1"]); // frozen at width 40
 		// A resize is an explicit rebuild that reconciles history, so recompute.
-		expect(container.render(80)).toEqual(["a-reflowed", "b1"]);
+		expect(container.render(80)).toEqual(["a-reflowed", "", "b1"]);
 	});
 
 	it("renders every block live on terminals that can rebuild history", () => {
@@ -217,7 +217,7 @@ describe("TranscriptContainer", () => {
 		// No freezing: a non-live block's mutation is reflected (the renderer can
 		// rebuild committed history on these terminals).
 		a.set(["a-updated"]);
-		expect(container.render(40)).toEqual(["a-updated", "b1"]);
+		expect(container.render(40)).toEqual(["a-updated", "", "b1"]);
 	});
 
 	it("keeps an unfinalized block live when a finalized block is appended below it (ED3-risk)", () => {
@@ -232,7 +232,7 @@ describe("TranscriptContainer", () => {
 		// tool while it is still streaming. The tool must NOT freeze here.
 		const card = new MutableBlock(["rule card"]);
 		container.addChild(card);
-		expect(container.render(40)).toEqual(["write (streaming)", "rule card"]);
+		expect(container.render(40)).toEqual(["write (streaming)", "", "rule card"]);
 		// The live region begins at the unfinalized tool, not the bottom card.
 		expect(container.getNativeScrollbackLiveRegionStart()).toBe(0);
 
@@ -240,11 +240,11 @@ describe("TranscriptContainer", () => {
 		// tool was kept live, its final content is reflected — the bug was it
 		// freezing on the streaming preview and never showing the result.
 		tool.finalize(["✔ write: 4 lines"]);
-		expect(container.render(40)).toEqual(["✔ write: 4 lines", "rule card"]);
+		expect(container.render(40)).toEqual(["✔ write: 4 lines", "", "rule card"]);
 
 		// Now finalized, it freezes: a later re-layout stays put until the next thaw.
 		tool.set(["collapsed"]);
-		expect(container.render(40)).toEqual(["✔ write: 4 lines", "rule card"]);
+		expect(container.render(40)).toEqual(["✔ write: 4 lines", "", "rule card"]);
 	});
 
 	it("keeps a streaming assistant live so an abort label can land after status rows below it (ED3-risk)", () => {
@@ -291,18 +291,86 @@ describe("TranscriptContainer", () => {
 		container.addChild(sealed);
 		container.addChild(pending);
 		container.addChild(card);
-		expect(container.render(40)).toEqual(["done", "pending", "card"]);
+		expect(container.render(40)).toEqual(["done", "", "pending", "", "card"]);
 		// Live region starts at the pending block (offset 1), so the already-sealed
 		// leading block can commit while pending + card stay repaintable.
-		expect(container.getNativeScrollbackLiveRegionStart()).toBe(1);
+		expect(container.getNativeScrollbackLiveRegionStart()).toBe(2);
 
 		// The leading sealed block freezes; its re-layout is not reflected.
 		sealed.set(["done-collapsed"]);
-		expect(container.render(40)).toEqual(["done", "pending", "card"]);
+		expect(container.render(40)).toEqual(["done", "", "pending", "", "card"]);
 
 		// The pending block updates freely while live.
 		pending.finalize(["pending-final"]);
-		expect(container.render(40)).toEqual(["done", "pending-final", "card"]);
-		expect(container.getNativeScrollbackLiveRegionStart()).toBe(2);
+		expect(container.render(40)).toEqual(["done", "", "pending-final", "", "card"]);
+		expect(container.getNativeScrollbackLiveRegionStart()).toBe(4);
+	});
+});
+
+describe("TranscriptContainer spacing", () => {
+	it("inserts exactly one blank line between consecutive blocks", () => {
+		riskFlag.eagerEraseScrollbackRisk = false;
+		const container = new TranscriptContainer();
+		container.addChild(new MutableBlock(["a"]));
+		container.addChild(new MutableBlock(["b"]));
+		container.addChild(new MutableBlock(["c"]));
+		// One separator between each block; none above the first.
+		expect(container.render(40)).toEqual(["a", "", "b", "", "c"]);
+	});
+
+	it("strips a block's plain-blank top/bottom padding", () => {
+		riskFlag.eagerEraseScrollbackRisk = false;
+		const container = new TranscriptContainer();
+		container.addChild(new MutableBlock(["a"]));
+		// Leading Spacer rows + a trailing paddingY row collapse to just the body.
+		container.addChild(new MutableBlock(["", "   ", "body", ""]));
+		expect(container.render(40)).toEqual(["a", "", "body"]);
+	});
+
+	it("preserves background-colored padding rows (block-internal design)", () => {
+		riskFlag.eagerEraseScrollbackRisk = false;
+		const bgPad = "\x1b[48;2;0;0;0m   \x1b[0m";
+		const container = new TranscriptContainer();
+		container.addChild(new MutableBlock(["a"]));
+		// The ANSI-bearing padding row is not "plain blank", so it survives stripping.
+		container.addChild(new MutableBlock([bgPad, "x", bgPad]));
+		expect(container.render(40)).toEqual(["a", "", bgPad, "x", bgPad]);
+	});
+
+	it("does not double the gap when a block carries its own trailing blank", () => {
+		riskFlag.eagerEraseScrollbackRisk = false;
+		const container = new TranscriptContainer();
+		// The trailing blank is stripped, so only the container's separator remains.
+		container.addChild(new MutableBlock(["note", ""]));
+		container.addChild(new MutableBlock(["b"]));
+		expect(container.render(40)).toEqual(["note", "", "b"]);
+	});
+
+	it("does not inject separators within a single block's rows", () => {
+		riskFlag.eagerEraseScrollbackRisk = false;
+		const container = new TranscriptContainer();
+		// An IRC card / file-mention list wrapped as one block stays tight inside.
+		container.addChild(new MutableBlock(["header", "  body1", "  body2"]));
+		expect(container.render(40)).toEqual(["header", "  body1", "  body2"]);
+	});
+
+	it("drops a blank-only block without leaving a stray gap", () => {
+		riskFlag.eagerEraseScrollbackRisk = false;
+		const container = new TranscriptContainer();
+		container.addChild(new MutableBlock(["a"]));
+		container.addChild(new MutableBlock(["", "  "]));
+		container.addChild(new MutableBlock(["b"]));
+		expect(container.render(40)).toEqual(["a", "", "b"]);
+	});
+
+	it("counts the separator into the committed prefix below the live region (ED3-risk)", () => {
+		riskFlag.eagerEraseScrollbackRisk = true;
+		const container = new TranscriptContainer();
+		// A finalized block, then a still-live block below it.
+		container.addChild(new MutableBlock(["a1", "a2"]));
+		container.addChild(new StreamingBlock(["b"]));
+		// Separator sits at index 2; the live block's content begins at index 3.
+		expect(container.render(40)).toEqual(["a1", "a2", "", "b"]);
+		expect(container.getNativeScrollbackLiveRegionStart()).toBe(3);
 	});
 });
diff --git a/packages/coding-agent/test/modes/controllers/event-controller-message-start.test.ts b/packages/coding-agent/test/modes/controllers/event-controller-message-start.test.ts
index 8e80c6c28..f5a796393 100644
--- a/packages/coding-agent/test/modes/controllers/event-controller-message-start.test.ts
+++ b/packages/coding-agent/test/modes/controllers/event-controller-message-start.test.ts
@@ -194,11 +194,11 @@ describe("EventController IRC expiry", () => {
 
 		await controller.handleEvent({ type: "irc_message", message });
 
-		expect(chatContainer.children).toHaveLength(2);
+		expect(chatContainer.children).toHaveLength(1);
 		expect(requestRender).toHaveBeenCalledTimes(1);
 
 		vi.advanceTimersByTime(9_999);
-		expect(chatContainer.children).toHaveLength(2);
+		expect(chatContainer.children).toHaveLength(1);
 
 		vi.advanceTimersByTime(1);
 		expect(chatContainer.children).toHaveLength(0);
@@ -215,7 +215,7 @@ describe("EventController IRC expiry", () => {
 		await controller.handleEvent({ type: "irc_message", message });
 
 		expect(addMessageToChat).toHaveBeenCalledTimes(1);
-		expect(chatContainer.children).toHaveLength(2);
+		expect(chatContainer.children).toHaveLength(1);
 		vi.advanceTimersByTime(10_000);
 		expect(chatContainer.children).toHaveLength(0);
 	});
@@ -230,7 +230,7 @@ describe("EventController IRC expiry", () => {
 		controller.dispose();
 		vi.advanceTimersByTime(10_000);
 
-		expect(chatContainer.children).toHaveLength(2);
+		expect(chatContainer.children).toHaveLength(1);
 		expect(requestRender).toHaveBeenCalledTimes(1);
 	});
 });
diff --git a/packages/coding-agent/test/tools/read-renderer.test.ts b/packages/coding-agent/test/tools/read-renderer.test.ts
index f0f97530a..7bebce4f6 100644
--- a/packages/coding-agent/test/tools/read-renderer.test.ts
+++ b/packages/coding-agent/test/tools/read-renderer.test.ts
@@ -102,7 +102,7 @@ describe("read ToolExecutionComponent framing", () => {
 				(line, index) => index > topBorderIndex && line.includes(activeTheme.boxSharp.bottomLeft),
 			);
 
-			expect(topBorderIndex).toBe(1);
+			expect(topBorderIndex).toBe(0);
 			expect(lines[topBorderIndex + 1]).toContain("export const x = 1;");
 			expect(bottomBorderIndex).toBe(lines.length - 1);
 		} finally {

From 8df5718a66da65243c87412a7738b7fd214e26c2 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 03:09:28 +0200
Subject: [PATCH 077/181] fix(coding-agent/tools): handled discard action when
 no pending resolve action exists

- Handled discard requests by returning a no-op success response when no action is pending.
- Kept apply requests on the same path to throw ToolError when nothing is pending.
---
 packages/coding-agent/src/tools/resolve.ts | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/packages/coding-agent/src/tools/resolve.ts b/packages/coding-agent/src/tools/resolve.ts
index 9899e9376..15f22d406 100644
--- a/packages/coding-agent/src/tools/resolve.ts
+++ b/packages/coding-agent/src/tools/resolve.ts
@@ -187,6 +187,20 @@ export class ResolveTool implements AgentTool<typeof resolveSchema, ResolveToolD
 		return untilAborted(signal, async () => {
 			const invoker = this.session.peekQueueInvoker?.() ?? this.session.peekStandingResolveHandler?.();
 			if (!invoker) {
+				// `discard` is a request to cancel/abort a staged action. When nothing is
+				// pending, the desired end-state (no staged change) already holds, so honor
+				// it as a successful cancellation instead of surfacing a hard error to the
+				// model. `apply` still errors — there is nothing to apply.
+				if (params.action === "discard") {
+					return {
+						content: [{ type: "text" as const, text: "Nothing to discard; no pending action remains." }],
+						details: {
+							action: "discard",
+							reason: params.reason,
+							...(params.extra != null ? { extra: params.extra } : {}),
+						},
+					};
+				}
 				throw new ToolError("No pending action to resolve. Nothing to apply or discard.");
 			}
 			const result = (await invoker(params)) as AgentToolResult<ResolveToolDetails>;

From cd2eb7ed287f86c4342ec5f4e00956909fecec8b Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 03:21:25 +0200
Subject: [PATCH 078/181] fix(coding-agent): handled discard no-op resolution
 and dynamic expand hints

- Updated tool expand-hint rendering to use `expandKeyHint()`, which pulls the `app.tools.expand` binding and formats collapsed previews as `<key>: Expand`.
- Updated related tests in render utils and TUI regressions to assert the new hint string for default and remapped bindings.
- Added a resolve-tool regression test and changelog note covering `action: "discard"` with no pending action as a successful cancellation.
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 .../src/modes/components/read-tool-group.ts   |  2 +-
 .../coding-agent/src/tools/render-utils.ts    | 17 +++++--
 .../test/tools/render-utils.test.ts           | 44 ++++++++++++++++++-
 .../coding-agent/test/tools/resolve.test.ts   | 11 +++++
 packages/tui/test/render-regressions.test.ts  |  6 +--
 6 files changed, 71 insertions(+), 10 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0fb428666..d027da5be 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -12,6 +12,7 @@
 - Fixed search, grep, and edit output rendering so repeated directory group blank-line boundaries no longer break nested path/link reconstruction
 - Fixed `omp dry-balance --bench` flooding the terminal with staircased, duplicated spinner/status lines (and an indented summary) when the tty has ONLCR/OPOST disabled (raw mode). The interactive progress region separated rows with a bare LF and repositioned with a column-preserving `\x1b[<n>A` cursor-up, both of which only land at column 0 when the terminal translates LF→CRLF; with that translation off, every 80 ms redraw cascaded down and to the right into scrollback. The live region now carriage-returns before every cleared row, terminates each row with CRLF, and caps each row to the terminal width so a wrapped line cannot desync the cursor-up from the logical line count.
 - Fixed inconsistent vertical spacing between transcript blocks: some blocks (tool results from `search`/`find` and other renderer-backed tools) rendered with a doubled gap (a leading `Spacer` plus the content box's own `paddingY`), while others (the grouped `read` card, file-mention lists, IRC cards) rendered with no gap at all. Vertical spacing is now owned entirely by the chat renderer: `TranscriptContainer` strips each block's plain-blank top/bottom edges and inserts exactly one blank line between consecutive blocks, so every block is separated by a single consistent gap regardless of which component produced it. Individual components (assistant/user/tool/read-group/bash/eval/skill/custom/hook/compaction/branch/todo-reminder/plan-review messages) no longer emit their own leading `Spacer`/`paddingY` for separation, and multi-row groups (IRC cards, file-mention lists, completed-job batches, and the bordered command/`/changelog`/`/context`/version/OAuth/debug panels) are wrapped as single `TranscriptBlock` children so the renderer spaces them as one unit. Background-colored box padding is preserved as block-internal design.
+- Fixed `resolve` with `action: "discard"` surfacing a hard `isError` "No pending action to resolve" failure to the model when the agent asked to cancel a staged action (e.g. an `ast_edit` preview) but nothing was pending. A discard is a request to reach the "no staged change" end-state, which already holds in that case, so it is now honored as a successful cancellation (`"Nothing to discard; no pending action remains."` with `details.action: "discard"`) instead of an error. `action: "apply"` with no pending action still errors.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/coding-agent/src/modes/components/read-tool-group.ts b/packages/coding-agent/src/modes/components/read-tool-group.ts
index 5a236cb65..fc686ed75 100644
--- a/packages/coding-agent/src/modes/components/read-tool-group.ts
+++ b/packages/coding-agent/src/modes/components/read-tool-group.ts
@@ -198,7 +198,7 @@ export class ReadToolGroupComponent extends Container implements ToolExecutionHa
 
 	/**
 	 * Add a code-cell content preview below the entry summary.
-	 * When collapsed: shows first COLLAPSED_PREVIEW_LINES lines with "… N more lines (Ctrl+O for more)" hint.
+	 * When collapsed: shows first COLLAPSED_PREVIEW_LINES lines with a "… N more lines ⟨<key>: Expand⟩" hint.
 	 * When expanded: shows full content.
 	 */
 	#addContentPreview(entry: ReadEntry): void {
diff --git a/packages/coding-agent/src/tools/render-utils.ts b/packages/coding-agent/src/tools/render-utils.ts
index 0548d56bf..3830242d8 100644
--- a/packages/coding-agent/src/tools/render-utils.ts
+++ b/packages/coding-agent/src/tools/render-utils.ts
@@ -10,8 +10,9 @@ import * as path from "node:path";
 import type { ToolCallContext } from "@oh-my-pi/pi-agent-core";
 import type { Ellipsis } from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
-import { replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
+import { getKeybindings, replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
 import { pluralize } from "@oh-my-pi/pi-utils";
+import { formatKeyHints, type KeyId } from "../config/keybindings";
 import { settings } from "../config/settings";
 import type { Theme } from "../modes/theme/theme";
 import { Hasher } from "../tui/utils";
@@ -75,8 +76,16 @@ export const TRUNCATE_LENGTHS = {
 	SHORT: 40,
 } as const;
 
-/** Standard expand hint text */
-export const EXPAND_HINT = "(Ctrl+O for more)";
+/** Keybinding action that toggles tool-output expansion. */
+const EXPAND_ACTION = "app.tools.expand";
+/** Fallback key when no binding is resolvable (e.g. outside an interactive session). */
+const DEFAULT_EXPAND_KEY: KeyId = "ctrl+o";
+
+/** Human-readable key currently bound to tool-output expansion, e.g. `Ctrl+O`. */
+export function expandKeyHint(): string {
+	const keys = getKeybindings().getKeys(EXPAND_ACTION);
+	return formatKeyHints(keys.length > 0 ? keys : [DEFAULT_EXPAND_KEY]);
+}
 
 // =============================================================================
 // Text Truncation Utilities
@@ -150,7 +159,7 @@ export function formatStatusIcon(status: ToolUIStatus, theme: Theme, spinnerFram
 export function formatExpandHint(theme: Theme, expanded?: boolean, hasMore?: boolean): string {
 	if (expanded) return "";
 	if (hasMore === false) return "";
-	return theme.fg("dim", wrapBrackets(EXPAND_HINT, theme));
+	return theme.fg("dim", wrapBrackets(`${expandKeyHint()}: Expand`, theme));
 }
 
 /**
diff --git a/packages/coding-agent/test/tools/render-utils.test.ts b/packages/coding-agent/test/tools/render-utils.test.ts
index e4a7909a6..db3eb865f 100644
--- a/packages/coding-agent/test/tools/render-utils.test.ts
+++ b/packages/coding-agent/test/tools/render-utils.test.ts
@@ -1,16 +1,20 @@
-import { beforeAll, describe, expect, it } from "bun:test";
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getThemeByName, initTheme, theme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
+import { KeybindingsManager } from "@oh-my-pi/pi-coding-agent/config/keybindings";
+import { getThemeByName, initTheme, theme, type Theme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
 import {
 	dedupeParseErrors,
+	expandKeyHint,
 	formatCodeFrameLine,
 	formatDiagnostics,
 	formatErrorMessage,
+	formatExpandHint,
 	formatParseErrors,
 	formatScreenshot,
 	truncateDiffByHunk,
 } from "@oh-my-pi/pi-coding-agent/tools/render-utils";
+import { getKeybindings, setKeybindings } from "@oh-my-pi/pi-tui";
 
 describe("parse error formatting", () => {
 	it("deduplicates parse errors while preserving order", () => {
@@ -282,3 +286,39 @@ describe("formatErrorMessage (F4 sanitization)", () => {
 		expect(out).toContain("Unknown error");
 	});
 });
+
+describe("formatExpandHint / expandKeyHint", () => {
+	// Plain stub: `fg` is a passthrough and brackets are literal `[`/`]`, so the
+	// rendered hint is deterministic regardless of the active theme's bracket glyphs.
+	const plainTheme = {
+		fg: (_color: unknown, text: string) => text,
+		format: { bracketLeft: "[", bracketRight: "]" },
+	} as unknown as Theme;
+
+	let previous: ReturnType<typeof getKeybindings>;
+	beforeEach(() => {
+		previous = getKeybindings();
+	});
+	afterEach(() => {
+		setKeybindings(previous);
+	});
+
+	it("reports the default tool-output expand key", () => {
+		setKeybindings(KeybindingsManager.inMemory());
+		expect(expandKeyHint()).toBe("Ctrl+O");
+		// Single bracket pair from the theme, no double-wrapping around the key.
+		expect(formatExpandHint(plainTheme, false, true)).toBe("[Ctrl+O: Expand]");
+	});
+
+	it("tracks a user remap of the expand binding", () => {
+		setKeybindings(KeybindingsManager.inMemory({ "app.tools.expand": "alt+e" }));
+		expect(expandKeyHint()).toBe("Alt+E");
+		expect(formatExpandHint(plainTheme, false, true)).toBe("[Alt+E: Expand]");
+	});
+
+	it("renders nothing when expanded or there is no more content", () => {
+		setKeybindings(KeybindingsManager.inMemory());
+		expect(formatExpandHint(plainTheme, true, true)).toBe("");
+		expect(formatExpandHint(plainTheme, false, false)).toBe("");
+	});
+});
diff --git a/packages/coding-agent/test/tools/resolve.test.ts b/packages/coding-agent/test/tools/resolve.test.ts
index 14573934c..c9db93a56 100644
--- a/packages/coding-agent/test/tools/resolve.test.ts
+++ b/packages/coding-agent/test/tools/resolve.test.ts
@@ -35,6 +35,17 @@ describe("ResolveTool", () => {
 		);
 	});
 
+	it("treats discard with no pending action as a successful cancellation, not an error", async () => {
+		const tool = new ResolveTool(createSession());
+		const result = await tool.execute("call-discard-none", {
+			action: "discard",
+			reason: "Abandoning the staged edit.",
+		});
+		expect(result.isError ?? false).toBe(false);
+		expect(getText(result)).toContain("Nothing to discard");
+		expect(result.details).toMatchObject({ action: "discard", reason: "Abandoning the staged edit." });
+	});
+
 	it("discards pending action and clears store", async () => {
 		let discardedReason: string | undefined;
 		const handler = async (input: unknown) => {
diff --git a/packages/tui/test/render-regressions.test.ts b/packages/tui/test/render-regressions.test.ts
index eb09de1eb..dcb6a06b8 100644
--- a/packages/tui/test/render-regressions.test.ts
+++ b/packages/tui/test/render-regressions.test.ts
@@ -1784,7 +1784,7 @@ describe("TUI terminal-state regressions", () => {
 			const tui = new TUI(term);
 			const collapsedLines = [
 				"frame-top",
-				"code preview … 16 more lines ⟨(Ctrl+O for more)⟩",
+				"code preview … 16 more lines ⟨Ctrl+O: Expand⟩",
 				"output preview … 106 more lines (ctrl+o to expand)",
 				...rows("json-", 10),
 				"status",
@@ -1835,7 +1835,7 @@ describe("TUI terminal-state regressions", () => {
 			const tui = new TUI(term);
 			const component = new MutableLinesComponent([
 				"frame-top",
-				"code preview … 16 more lines ⟨(Ctrl+O for more)⟩",
+				"code preview … 16 more lines ⟨Ctrl+O: Expand⟩",
 				"output preview … 106 more lines (ctrl+o to expand)",
 				...rows("json-", 10),
 				"status",
@@ -1880,7 +1880,7 @@ describe("TUI terminal-state regressions", () => {
 			const tui = new TUI(term);
 			const component = new MutableLinesComponent([
 				"frame-top",
-				"code preview … 16 more lines ⟨(Ctrl+O for more)⟩",
+				"code preview … 16 more lines ⟨Ctrl+O: Expand⟩",
 				"output preview … 106 more lines (ctrl+o to expand)",
 				...rows("json-", 10),
 				"status",

From 99e91138a472d32ff762e1fbd143a8ae5311941c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 03:23:16 +0200
Subject: [PATCH 079/181] feat(coding-agent): enabled component-based chat
 rendering with managed block lifecycles

- Added ChatBlock and ChatBlockHost with mount, finish, and dispose lifecycle callbacks.
- Added InteractiveModeContext.present and resetTranscript APIs and used them to mount/repaint blocks.
- Reworked controller rendering paths to emit command, event, extension, and selector outputs via ctx.present.
- Implemented component and container dispose hooks in tui so loaders and child blocks cleanup timers/effects.
---
 packages/coding-agent/CHANGELOG.md            |   6 +
 packages/coding-agent/src/debug/index.ts      |  45 ++----
 .../src/modes/components/chat-block.ts        | 111 ++++++++++++++
 .../controllers/command-controller-shared.ts  |   3 +-
 .../modes/controllers/command-controller.ts   |  55 +++----
 .../src/modes/controllers/event-controller.ts |   6 +-
 .../controllers/extension-ui-controller.ts    |  18 +--
 .../controllers/mcp-command-controller.ts     |  75 +++++----
 .../modes/controllers/selector-controller.ts  |  15 +-
 .../src/modes/interactive-mode.ts             |  21 +++
 packages/coding-agent/src/modes/types.ts      |  14 ++
 .../src/modes/utils/ui-helpers.ts             |  24 +--
 .../test/interactive-mode-status.test.ts      |  17 ++-
 .../coding-agent/test/issue-956-repro.test.ts |   4 +
 .../test/modes/components/chat-block.test.ts  | 143 ++++++++++++++++++
 .../render-initial-messages-dedupe.test.ts    |   1 +
 .../test/tools/render-utils.test.ts           |   6 +-
 packages/tui/CHANGELOG.md                     |   5 +
 packages/tui/src/components/loader.ts         |   5 +
 packages/tui/src/tui.ts                       |  19 +++
 packages/tui/test/container-dispose.test.ts   |  30 ++++
 packages/tui/test/loader.test.ts              |  21 ++-
 22 files changed, 510 insertions(+), 134 deletions(-)
 create mode 100644 packages/coding-agent/src/modes/components/chat-block.ts
 create mode 100644 packages/coding-agent/test/modes/components/chat-block.test.ts
 create mode 100644 packages/tui/test/container-dispose.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index d027da5be..8ce20eb81 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,10 +1,15 @@
 # Changelog
 
 ## [Unreleased]
+### Added
+
+- Added a `ChatBlock` transcript primitive (`modes/components/chat-block.ts`) and a single `ctx.present(...)` sink (with `ctx.resetTranscript()`) so chat output is mounted in one place instead of the repeated `chatContainer.addChild(...)` + `ui.requestRender()` pattern scattered across controllers. `ChatBlock` carries a React/Svelte-style lifecycle — `onMount` starts effects, `onCleanup` registers teardown, `finish()` self-completes (stops timers and freezes the block at its final content), and `dispose()`/`resetTranscript()` tears everything down — so animated blocks own their own resources instead of leaking `setInterval`/`requestRender` bookkeeping into callers. The MCP "Connecting…" spinner is now such a block.
+
 ### Changed
 
 - Changed the directory grouping for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics from a single flat `# dir/` heading per immediate directory to a multi-level tree that folds the common path prefix into one heading. Previously every group repeated the full directory path — so results rooted outside cwd printed the absolute prefix (e.g. `/Users/me/proj/`) on every heading and nested directories were never collapsed. Now a single-child directory chain folds into one heading (`# packages/pkg/src/`, including an absolute root for out-of-cwd results), subdirectories nest one `#` deeper (`## nested/` → `### child.ts`), and each directory's own files are listed before its subdirectories. TUI hyperlink reconstruction tracks the nested directory stack across the whole output so file and code-frame links keep resolving to the correct absolute paths.
 - Changed the plan-mode approval surface from an inline transcript block plus a separate bottom selector into a single fullscreen overlay (like `/copy`). The overlay owns its entire content via `ScrollView`: the plan renders once as Markdown and scrolls inside the outlined box (PageUp/PageDown, g/G), with the approval options and the model-tier slider beneath it. ↑/↓ move the option cursor, ←/→ drive the slider, Enter confirms, the external-editor key opens the plan, and Esc cancels — so a tall plan no longer competes with the selector for vertical space or clips its head on ED3-risk terminals.
+- Changed the interactive controllers (command, MCP, selector, extension-UI, event), debug panels, and the status/error/warning helpers to render chat output through `ctx.present(...)` instead of appending to `chatContainer` and calling `ui.requestRender()` directly; transcript rebuilds dispose live blocks via `ctx.resetTranscript()` so animated blocks' timers stop on reset.
 
 ### Fixed
 
@@ -13,6 +18,7 @@
 - Fixed `omp dry-balance --bench` flooding the terminal with staircased, duplicated spinner/status lines (and an indented summary) when the tty has ONLCR/OPOST disabled (raw mode). The interactive progress region separated rows with a bare LF and repositioned with a column-preserving `\x1b[<n>A` cursor-up, both of which only land at column 0 when the terminal translates LF→CRLF; with that translation off, every 80 ms redraw cascaded down and to the right into scrollback. The live region now carriage-returns before every cleared row, terminates each row with CRLF, and caps each row to the terminal width so a wrapped line cannot desync the cursor-up from the logical line count.
 - Fixed inconsistent vertical spacing between transcript blocks: some blocks (tool results from `search`/`find` and other renderer-backed tools) rendered with a doubled gap (a leading `Spacer` plus the content box's own `paddingY`), while others (the grouped `read` card, file-mention lists, IRC cards) rendered with no gap at all. Vertical spacing is now owned entirely by the chat renderer: `TranscriptContainer` strips each block's plain-blank top/bottom edges and inserts exactly one blank line between consecutive blocks, so every block is separated by a single consistent gap regardless of which component produced it. Individual components (assistant/user/tool/read-group/bash/eval/skill/custom/hook/compaction/branch/todo-reminder/plan-review messages) no longer emit their own leading `Spacer`/`paddingY` for separation, and multi-row groups (IRC cards, file-mention lists, completed-job batches, and the bordered command/`/changelog`/`/context`/version/OAuth/debug panels) are wrapped as single `TranscriptBlock` children so the renderer spaces them as one unit. Background-colored box padding is preserved as block-internal design.
 - Fixed `resolve` with `action: "discard"` surfacing a hard `isError` "No pending action to resolve" failure to the model when the agent asked to cancel a staged action (e.g. an `ast_edit` preview) but nothing was pending. A discard is a request to reach the "no staged change" end-state, which already holds in that case, so it is now honored as a successful cancellation (`"Nothing to discard; no pending action remains."` with `details.action: "discard"`) instead of an error. `action: "apply"` with no pending action still errors.
+- Fixed the collapsed tool-output expand hint rendering double brackets (e.g. `((Ctrl+O for more))`) — the `EXPAND_HINT` text already carried its own parentheses and then `formatExpandHint` wrapped it again with the theme's bracket glyphs. The hint now resolves the key actually bound to `app.tools.expand` at render time and reads `⟨<key>: Expand⟩` (e.g. `⟨Ctrl+O: Expand⟩`), so a single bracket pair surrounds it and a user remap of the expand keybinding is reflected instead of a hard-coded `Ctrl+O`.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/coding-agent/src/debug/index.ts b/packages/coding-agent/src/debug/index.ts
index 813afa65b..17840cc4b 100644
--- a/packages/coding-agent/src/debug/index.ts
+++ b/packages/coding-agent/src/debug/index.ts
@@ -157,8 +157,7 @@ export class DebugSelectorComponent extends Container {
 		block.addChild(
 			new Text(theme.fg("muted", "Reproduce the performance issue, then press Enter to stop profiling."), 1, 0),
 		);
-		this.ctx.chatContainer.addChild(block);
-		this.ctx.ui.requestRender();
+		this.ctx.present(block);
 
 		// Wait for Enter keypress
 		const { promise, resolve } = Promise.withResolvers<void>();
@@ -207,14 +206,12 @@ export class DebugSelectorComponent extends Container {
 			block.addChild(new Text(theme.fg("success", `${theme.status.success} Performance report saved`), 1, 0));
 			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
-			this.ctx.chatContainer.addChild(block);
+			this.ctx.present(block);
 		} catch (err) {
 			loader.stop();
 			this.ctx.statusContainer.clear();
 			this.ctx.showError(`Failed to create report: ${err instanceof Error ? err.message : String(err)}`);
 		}
-
-		this.ctx.ui.requestRender();
 	}
 
 	async #handleWorkReport(): Promise<void> {
@@ -232,15 +229,13 @@ export class DebugSelectorComponent extends Container {
 
 			openPath(tmpPath);
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
+			this.ctx.present([
+				new Spacer(1),
 				new Text(theme.fg("dim", `Opened flamegraph (${workProfile.sampleCount} samples)`), 1, 0),
-			);
+			]);
 		} catch (err) {
 			this.ctx.showError(`Failed to open profile: ${err instanceof Error ? err.message : String(err)}`);
 		}
-
-		this.ctx.ui.requestRender();
 	}
 
 	async #handleDumpReport(): Promise<void> {
@@ -267,14 +262,12 @@ export class DebugSelectorComponent extends Container {
 			block.addChild(new Text(theme.fg("success", `${theme.status.success} Report bundle saved`), 1, 0));
 			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
-			this.ctx.chatContainer.addChild(block);
+			this.ctx.present(block);
 		} catch (err) {
 			loader.stop();
 			this.ctx.statusContainer.clear();
 			this.ctx.showError(`Failed to create report: ${err instanceof Error ? err.message : String(err)}`);
 		}
-
-		this.ctx.ui.requestRender();
 	}
 
 	async #handleMemoryReport(): Promise<void> {
@@ -305,14 +298,12 @@ export class DebugSelectorComponent extends Container {
 			block.addChild(new Text(theme.fg("success", `${theme.status.success} Memory report saved`), 1, 0));
 			block.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			block.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
-			this.ctx.chatContainer.addChild(block);
+			this.ctx.present(block);
 		} catch (err) {
 			loader.stop();
 			this.ctx.statusContainer.clear();
 			this.ctx.showError(`Failed to create report: ${err instanceof Error ? err.message : String(err)}`);
 		}
-
-		this.ctx.ui.requestRender();
 	}
 
 	async #handleViewLogs(): Promise<void> {
@@ -368,12 +359,10 @@ export class DebugSelectorComponent extends Container {
 			block.addChild(new DynamicBorder());
 			block.addChild(new Text(formatted, 1, 0));
 			block.addChild(new DynamicBorder());
-			this.ctx.chatContainer.addChild(block);
+			this.ctx.present(block);
 		} catch (err) {
 			this.ctx.showError(`Failed to collect system info: ${err instanceof Error ? err.message : String(err)}`);
 		}
-
-		this.ctx.ui.requestRender();
 	}
 
 	async #handleViewTerminalState(): Promise<void> {
@@ -388,8 +377,7 @@ export class DebugSelectorComponent extends Container {
 		block.addChild(new DynamicBorder());
 		block.addChild(new Text(formatted, 1, 0));
 		block.addChild(new DynamicBorder());
-		this.ctx.chatContainer.addChild(block);
-		this.ctx.ui.requestRender();
+		this.ctx.present(block);
 	}
 
 	async #handleViewProtocols(): Promise<void> {
@@ -408,15 +396,14 @@ export class DebugSelectorComponent extends Container {
 			TERMINAL.sendNotification(notification);
 		}
 
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(
+		this.ctx.present([
+			new Spacer(1),
 			new ProtocolProbeComponent({
 				image: buildSampleImage(),
 				imageBudget: this.ctx.ui.imageBudget,
 				notificationSuppressed: suppressed,
 			}),
-		);
-		this.ctx.ui.requestRender();
+		]);
 	}
 
 	async #handleTranscriptExport(): Promise<void> {
@@ -488,21 +475,19 @@ export class DebugSelectorComponent extends Container {
 			loader.stop();
 			this.ctx.statusContainer.clear();
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
+			this.ctx.present([
+				new Spacer(1),
 				new Text(
 					theme.fg("success", `${theme.status.success} Cleared ${result.removed} artifact directories`),
 					1,
 					0,
 				),
-			);
+			]);
 		} catch (err) {
 			loader.stop();
 			this.ctx.statusContainer.clear();
 			this.ctx.showError(`Failed to clear cache: ${err instanceof Error ? err.message : String(err)}`);
 		}
-
-		this.ctx.ui.requestRender();
 	}
 
 	#getResolvedSettings(): Record<string, unknown> {
diff --git a/packages/coding-agent/src/modes/components/chat-block.ts b/packages/coding-agent/src/modes/components/chat-block.ts
new file mode 100644
index 000000000..da79c2041
--- /dev/null
+++ b/packages/coding-agent/src/modes/components/chat-block.ts
@@ -0,0 +1,111 @@
+import { Container } from "@oh-my-pi/pi-tui";
+
+/**
+ * Capabilities a mounted {@link ChatBlock} may use against its host transcript.
+ * Kept minimal so blocks never reach into the full TUI/InteractiveMode surface.
+ */
+export interface ChatBlockHost {
+	/** Schedule a repaint of the transcript. */
+	requestRender(): void;
+}
+
+/**
+ * Lifecycle-aware transcript block — the "return a block, let the host mount it"
+ * primitive, modelled on React/Svelte component lifecycles.
+ *
+ * Producers build and return a `ChatBlock` instead of poking `chatContainer` and
+ * `ui.requestRender()` directly. The host (`ctx.present`) appends it and calls
+ * {@link mount}, which runs {@link onMount}; effects started there register
+ * teardown via {@link onCleanup}. The block repaints through {@link requestRender}
+ * — never touching the TUI — and tears down exactly once on {@link finish}
+ * (self-complete: stop the animation, keep the final frame in the transcript) or
+ * {@link dispose} (host discards it, e.g. a transcript reset).
+ *
+ * While mounted and unfinished a block reports `isTranscriptBlockFinalized() ===
+ * false` so {@link "../components/transcript-container".TranscriptContainer}
+ * keeps it in the live, repaintable region on ED3-risk terminals; after
+ * `finish()`/`dispose()` it reports `true` and freezes at its final content.
+ */
+export abstract class ChatBlock extends Container {
+	#host: ChatBlockHost | undefined;
+	#cleanups: Array<() => void> = [];
+	#active = false;
+	#disposed = false;
+
+	/**
+	 * Run setup after the block is in the transcript: start timers/subscriptions
+	 * and register their teardown with {@link onCleanup}. Default: no-op (a block
+	 * whose content is fixed at construction needs no mount work).
+	 */
+	protected onMount(): void {}
+
+	/**
+	 * Register a teardown to run on {@link finish}/{@link dispose}, à la a
+	 * `useEffect` cleanup. If the block is already disposed the cleanup runs
+	 * immediately so callers never leak.
+	 */
+	protected onCleanup(cleanup: () => void): void {
+		if (this.#disposed) {
+			cleanup();
+			return;
+		}
+		this.#cleanups.push(cleanup);
+	}
+
+	/** Ask the host to repaint. No-op before mount or after dispose. */
+	protected requestRender(): void {
+		this.#host?.requestRender();
+	}
+
+	/** True between {@link mount} and {@link finish}/{@link dispose}. */
+	protected get active(): boolean {
+		return this.#active;
+	}
+
+	/**
+	 * Host-only: attach the host and run {@link onMount}. Idempotent — a second
+	 * call (e.g. a transcript rebuild that re-presents the same instance) is a
+	 * no-op.
+	 */
+	mount(host: ChatBlockHost): void {
+		if (this.#host || this.#disposed) return;
+		this.#host = host;
+		this.#active = true;
+		this.onMount();
+	}
+
+	/**
+	 * Self-complete: stop ongoing effects and freeze the block at its current
+	 * content, leaving it rendered in the transcript. Use when the operation the
+	 * block represents finishes (connection resolved, download done).
+	 */
+	finish(): void {
+		if (!this.#active) return;
+		this.#active = false;
+		this.#runCleanups();
+		this.requestRender();
+	}
+
+	/**
+	 * Host-only teardown: release everything and propagate to children. Called
+	 * when the host permanently discards the block (transcript reset). Idempotent.
+	 */
+	override dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.#active = false;
+		this.#runCleanups();
+		super.dispose();
+		this.#host = undefined;
+	}
+
+	/** Live blocks stay repaintable; finished/disposed ones may freeze. */
+	isTranscriptBlockFinalized(): boolean {
+		return !this.#active;
+	}
+
+	#runCleanups(): void {
+		const cleanups = this.#cleanups.splice(0);
+		for (const cleanup of cleanups) cleanup();
+	}
+}
diff --git a/packages/coding-agent/src/modes/controllers/command-controller-shared.ts b/packages/coding-agent/src/modes/controllers/command-controller-shared.ts
index 7ee9c9499..2e3eb6471 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller-shared.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller-shared.ts
@@ -105,6 +105,5 @@ export function showCommandMessage(ctx: InteractiveModeContext, text: string): v
 	block.addChild(new DynamicBorder());
 	block.addChild(new Text(text, 1, 1));
 	block.addChild(new DynamicBorder());
-	ctx.chatContainer.addChild(block);
-	ctx.ui.requestRender();
+	ctx.present(block);
 }
diff --git a/packages/coding-agent/src/modes/controllers/command-controller.ts b/packages/coding-agent/src/modes/controllers/command-controller.ts
index 942392430..c19f93269 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller.ts
@@ -53,8 +53,7 @@ function showMarkdownPanel(ctx: InteractiveModeContext, title: string, markdown:
 	block.addChild(new Spacer(1));
 	block.addChild(new Markdown(markdown.trim(), 1, 1, getMarkdownTheme()));
 	block.addChild(new DynamicBorder());
-	ctx.chatContainer.addChild(block);
-	ctx.ui.requestRender();
+	ctx.present(block);
 }
 
 export class CommandController {
@@ -336,9 +335,7 @@ export class CommandController {
 			}
 		}
 
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(info, 1, 0));
-		this.ctx.ui.requestRender();
+		this.ctx.present([new Spacer(1), new Text(info, 1, 0)]);
 	}
 
 	async handleJobsCommand(): Promise<void> {
@@ -355,9 +352,7 @@ export class CommandController {
 
 		if (snapshot.running.length === 0 && snapshot.recent.length === 0) {
 			info += `\n${theme.fg("dim", "No async jobs yet.")}\n`;
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(new Text(info, 1, 0));
-			this.ctx.ui.requestRender();
+			this.ctx.present([new Spacer(1), new Text(info, 1, 0)]);
 			return;
 		}
 
@@ -377,9 +372,7 @@ export class CommandController {
 			}
 		}
 
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(info.trimEnd(), 1, 0));
-		this.ctx.ui.requestRender();
+		this.ctx.present([new Spacer(1), new Text(info.trimEnd(), 1, 0)]);
 	}
 
 	async handleUsageCommand(reports?: UsageReport[] | null): Promise<void> {
@@ -405,9 +398,7 @@ export class CommandController {
 
 		const availableWidth = Math.max(40, (this.ctx.ui.terminal.columns ?? 100) - 2);
 		const output = renderUsageReports(usageReports, theme, Date.now(), availableWidth);
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(output, 1, 0));
-		this.ctx.ui.requestRender();
+		this.ctx.present([new Spacer(1), new Text(output, 1, 0)]);
 	}
 
 	async handleChangelogCommand(showFull = false): Promise<void> {
@@ -434,8 +425,7 @@ export class CommandController {
 		block.addChild(new Spacer(1));
 		block.addChild(new Markdown(changelogMarkdown + hint, 1, 1, getMarkdownTheme()));
 		block.addChild(new DynamicBorder());
-		this.ctx.chatContainer.addChild(block);
-		this.ctx.ui.requestRender();
+		this.ctx.present(block);
 	}
 
 	handleHotkeysCommand(): void {
@@ -461,8 +451,7 @@ export class CommandController {
 		block.addChild(new Spacer(1));
 		block.addChild(new Text(output, 1, 0));
 		block.addChild(new DynamicBorder());
-		this.ctx.chatContainer.addChild(block);
-		this.ctx.ui.requestRender();
+		this.ctx.present(block);
 	}
 
 	async handleMemoryCommand(text: string): Promise<void> {
@@ -483,8 +472,7 @@ export class CommandController {
 			block.addChild(new Spacer(1));
 			block.addChild(new Markdown(payload, 1, 1, getMarkdownTheme()));
 			block.addChild(new DynamicBorder());
-			this.ctx.chatContainer.addChild(block);
-			this.ctx.ui.requestRender();
+			this.ctx.present(block);
 			return;
 		}
 
@@ -805,8 +793,7 @@ export class CommandController {
 		this.ctx.streamingMessage = undefined;
 		this.ctx.pendingTools.clear();
 
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(`${theme.fg("accent", `${theme.status.success} ${label}`)}`, 1, 1));
+		this.ctx.present([new Spacer(1), new Text(`${theme.fg("accent", `${theme.status.success} ${label}`)}`, 1, 1)]);
 		await this.ctx.reloadTodos();
 		this.ctx.ui.requestRender(true, { clearScrollback: true });
 	}
@@ -845,11 +832,10 @@ export class CommandController {
 
 		const sessionFile = this.ctx.session.sessionFile;
 		const shortPath = sessionFile ? sessionFile.split("/").pop() : "new session";
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(
+		this.ctx.present([
+			new Spacer(1),
 			new Text(`${theme.fg("accent", `${theme.status.success} Session forked to ${shortPath}`)}`, 1, 1),
-		);
-		this.ctx.ui.requestRender();
+		]);
 	}
 
 	async handleMoveCommand(targetPath: string): Promise<void> {
@@ -883,11 +869,10 @@ export class CommandController {
 			await this.ctx.sessionManager.moveTo(resolvedPath);
 			await this.ctx.applyCwdChange(resolvedPath);
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
+			this.ctx.present([
+				new Spacer(1),
 				new Text(`${theme.fg("accent", `${theme.status.success} Session moved to ${resolvedPath}`)}`, 1, 1),
-			);
-			this.ctx.ui.requestRender();
+			]);
 		} catch (err) {
 			this.ctx.showError(`Move failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
@@ -918,7 +903,7 @@ export class CommandController {
 			this.ctx.pendingMessagesContainer.addChild(this.ctx.bashComponent);
 			this.ctx.pendingBashComponents.push(this.ctx.bashComponent);
 		} else {
-			this.ctx.chatContainer.addChild(this.ctx.bashComponent);
+			this.ctx.present(this.ctx.bashComponent);
 		}
 		this.ctx.ui.requestRender();
 
@@ -959,7 +944,7 @@ export class CommandController {
 			this.ctx.pendingMessagesContainer.addChild(this.ctx.pythonComponent);
 			this.ctx.pendingPythonComponents.push(this.ctx.pythonComponent);
 		} else {
-			this.ctx.chatContainer.addChild(this.ctx.pythonComponent);
+			this.ctx.present(this.ctx.pythonComponent);
 		}
 		this.ctx.ui.requestRender();
 
@@ -1148,10 +1133,10 @@ export class CommandController {
 			this.ctx.updateEditorBorderColor();
 			await this.ctx.reloadTodos();
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(
+			this.ctx.present([
+				new Spacer(1),
 				new Text(`${theme.fg("accent", `${theme.status.success} New session started with handoff context`)}`, 1, 1),
-			);
+			]);
 			if (result.savedPath) {
 				this.ctx.showStatus(`Handoff document saved to: ${result.savedPath}`);
 			}
diff --git a/packages/coding-agent/src/modes/controllers/event-controller.ts b/packages/coding-agent/src/modes/controllers/event-controller.ts
index 66497e783..bdaeab4ec 100644
--- a/packages/coding-agent/src/modes/controllers/event-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/event-controller.ts
@@ -830,14 +830,12 @@ export class EventController {
 	async #handleTtsrTriggered(event: Extract<AgentSessionEvent, { type: "ttsr_triggered" }>): Promise<void> {
 		const component = new TtsrNotificationComponent(event.rules);
 		component.setExpanded(this.ctx.toolOutputExpanded);
-		this.ctx.chatContainer.addChild(component);
-		this.ctx.ui.requestRender();
+		this.ctx.present(component);
 	}
 
 	async #handleTodoReminder(event: Extract<AgentSessionEvent, { type: "todo_reminder" }>): Promise<void> {
 		const component = new TodoReminderComponent(event.todos, event.attempt, event.maxAttempts);
-		this.ctx.chatContainer.addChild(component);
-		this.ctx.ui.requestRender();
+		this.ctx.present(component);
 	}
 
 	async #handleTodoAutoClear(_event: Extract<AgentSessionEvent, { type: "todo_auto_clear" }>): Promise<void> {
diff --git a/packages/coding-agent/src/modes/controllers/extension-ui-controller.ts b/packages/coding-agent/src/modes/controllers/extension-ui-controller.ts
index e2b994fce..8f09b645b 100644
--- a/packages/coding-agent/src/modes/controllers/extension-ui-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/extension-ui-controller.ts
@@ -176,10 +176,10 @@ export class ExtensionUiController {
 				this.ctx.streamingMessage = undefined;
 				this.ctx.pendingTools.clear();
 
-				this.ctx.chatContainer.addChild(new Spacer(1));
-				this.ctx.chatContainer.addChild(
+				this.ctx.present([
+					new Spacer(1),
 					new Text(`${theme.fg("accent", `${theme.status.success} New session started`)}`, 1, 1),
-				);
+				]);
 				await this.ctx.reloadTodos();
 				this.ctx.ui.requestRender(true, { clearScrollback: true });
 
@@ -415,10 +415,10 @@ export class ExtensionUiController {
 				this.ctx.streamingMessage = undefined;
 				this.ctx.pendingTools.clear();
 
-				this.ctx.chatContainer.addChild(new Spacer(1));
-				this.ctx.chatContainer.addChild(
+				this.ctx.present([
+					new Spacer(1),
 					new Text(`${theme.fg("accent", `${theme.status.success} New session started`)}`, 1, 1),
-				);
+				]);
 				await this.ctx.reloadTodos();
 				this.ctx.ui.requestRender(true, { clearScrollback: true });
 
@@ -562,8 +562,7 @@ export class ExtensionUiController {
 			return;
 		}
 		const errorText = new Text(theme.fg("error", `Tool "${toolName}" error: ${error}`), 1, 0);
-		this.ctx.chatContainer.addChild(errorText);
-		this.ctx.ui.requestRender();
+		this.ctx.present(errorText);
 	}
 
 	/**
@@ -860,8 +859,7 @@ export class ExtensionUiController {
 
 	showExtensionError(extensionPath: string, error: string): void {
 		const errorText = new Text(theme.fg("error", `Extension "${extensionPath}" error: ${error}`), 1, 0);
-		this.ctx.chatContainer.addChild(errorText);
-		this.ctx.ui.requestRender();
+		this.ctx.present(errorText);
 	}
 	async #handleInteractiveCompact(instructionsOrOptions: string | CompactOptions | undefined): Promise<void> {
 		if (this.ctx.isBackgrounded) {
diff --git a/packages/coding-agent/src/modes/controllers/mcp-command-controller.ts b/packages/coding-agent/src/modes/controllers/mcp-command-controller.ts
index 86fb385af..c63e57162 100644
--- a/packages/coding-agent/src/modes/controllers/mcp-command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/mcp-command-controller.ts
@@ -37,6 +37,7 @@ import type { MCPAuthConfig, MCPServerConfig, MCPServerConnection } from "../../
 import type { OAuthCredential } from "../../session/auth-storage";
 import { shortenPath } from "../../tools/render-utils";
 import { openPath } from "../../utils/open";
+import { ChatBlock } from "../components/chat-block";
 import { MCPAddWizard } from "../components/mcp-add-wizard";
 import { TranscriptBlock } from "../components/transcript-container";
 import { parseCommandArgs } from "../shared";
@@ -50,6 +51,42 @@ function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string)
 	return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
 }
 
+/**
+ * Animated "Connecting to …" transcript block. Owns its spinner interval: it
+ * starts on mount and is cleared on {@link ChatBlock.finish}/dispose, so callers
+ * never juggle `setInterval`/`clearInterval` or `requestRender` by hand.
+ */
+class McpConnectingBlock extends ChatBlock {
+	readonly #text: Text;
+
+	constructor(private readonly serverName: string) {
+		super();
+		this.addChild(new Spacer(1));
+		const frame = theme.spinnerFrames[0] ?? "|";
+		this.#text = new Text(theme.fg("muted", `${frame} Connecting to "${serverName}"...`), 1, 0);
+		this.addChild(this.#text);
+	}
+
+	protected override onMount(): void {
+		const frames = theme.spinnerFrames;
+		let frame = 0;
+		const interval = setInterval(() => {
+			frame++;
+			this.#text.setText(
+				theme.fg("muted", `${frames[frame % frames.length] ?? "|"} Connecting to "${this.serverName}"...`),
+			);
+			this.requestRender();
+		}, 80);
+		this.onCleanup(() => clearInterval(interval));
+	}
+
+	/** Replace the spinner line with a terminal status; pair with {@link finish}. */
+	setStatus(text: string): void {
+		this.#text.setText(text);
+		this.requestRender();
+	}
+}
+
 /**
  * Outcome of {@link MCPCommandController}'s OAuth handler.
  *
@@ -550,7 +587,7 @@ export class MCPCommandController {
 					onAuth: (info: { url: string; instructions?: string }) => {
 						// Show auth URL prominently in chat as one block
 						const block = new TranscriptBlock();
-						this.ctx.chatContainer.addChild(block);
+						this.ctx.present(block);
 						block.addChild(new Text(theme.fg("accent", "━━━ OAuth Authorization Required ━━━"), 1, 0));
 						block.addChild(new Spacer(1));
 						block.addChild(new Text(theme.fg("muted", "Preparing browser authorization..."), 1, 0));
@@ -564,7 +601,6 @@ export class MCPCommandController {
 						);
 						block.addChild(new Spacer(1));
 						block.addChild(new Text(theme.fg("accent", "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"), 1, 0));
-						this.ctx.ui.requestRender();
 						// Try to open browser automatically
 						try {
 							openPath(info.url);
@@ -587,9 +623,7 @@ export class MCPCommandController {
 						}
 					},
 					onProgress: (message: string) => {
-						this.ctx.chatContainer.addChild(new Spacer(1));
-						this.ctx.chatContainer.addChild(new Text(theme.fg("muted", message), 1, 0));
-						this.ctx.ui.requestRender();
+						this.ctx.present([new Spacer(1), new Text(theme.fg("muted", message), 1, 0)]);
 					},
 				},
 			);
@@ -597,9 +631,10 @@ export class MCPCommandController {
 			// Execute OAuth flow with 5 minute timeout
 			const credentials = await withTimeout(flow.login(), 5 * 60 * 1000, "OAuth flow timed out after 5 minutes");
 
-			this.ctx.chatContainer.addChild(new Spacer(1));
-			this.ctx.chatContainer.addChild(new Text(theme.fg("success", "✓ Authorization completed in browser."), 1, 0));
-			this.ctx.ui.requestRender();
+			this.ctx.present([
+				new Spacer(1),
+				new Text(theme.fg("success", "✓ Authorization completed in browser."), 1, 0),
+			]);
 
 			// Generate a unique credential ID
 			const credentialId = `mcp_oauth_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
@@ -752,19 +787,8 @@ export class MCPCommandController {
 	): Promise<"connected" | "connecting" | "disconnected"> {
 		if (!this.ctx.mcpManager) return "disconnected";
 
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		const frames = theme.spinnerFrames;
-		const initialFrame = frames[0] ?? "|";
-		const statusText = new Text(theme.fg("muted", `${initialFrame} Connecting to "${name}"...`), 1, 0);
-		this.ctx.chatContainer.addChild(statusText);
-		this.ctx.ui.requestRender();
-
-		let frame = 0;
-		const interval = setInterval(() => {
-			statusText.setText(theme.fg("muted", `${frames[frame % frames.length]} Connecting to "${name}"...`));
-			frame++;
-			this.ctx.ui.requestRender();
-		}, 80);
+		const block = new McpConnectingBlock(name);
+		this.ctx.present(block);
 
 		try {
 			try {
@@ -778,20 +802,19 @@ export class MCPCommandController {
 				await this.ctx.session.refreshMCPTools(this.ctx.mcpManager.getTools());
 			}
 			if (state === "connected") {
-				statusText.setText(theme.fg("success", `✓ Connected to "${name}"`));
+				block.setStatus(theme.fg("success", `✓ Connected to "${name}"`));
 			} else if (state === "connecting") {
-				statusText.setText(theme.fg("muted", `◌ "${name}" is still connecting...`));
+				block.setStatus(theme.fg("muted", `◌ "${name}" is still connecting...`));
 			} else {
-				statusText.setText(
+				block.setStatus(
 					options?.suppressDisconnectedWarning
 						? theme.fg("muted", `◌ Connection check complete for "${name}"`)
 						: theme.fg("warning", `⚠ Could not connect to "${name}" yet`),
 				);
 			}
-			this.ctx.ui.requestRender();
 			return state;
 		} finally {
-			clearInterval(interval);
+			block.finish();
 		}
 	}
 
diff --git a/packages/coding-agent/src/modes/controllers/selector-controller.ts b/packages/coding-agent/src/modes/controllers/selector-controller.ts
index 7aa831822..2d2728db2 100644
--- a/packages/coding-agent/src/modes/controllers/selector-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/selector-controller.ts
@@ -933,7 +933,6 @@ export class SelectorController {
 			await this.ctx.session.modelRegistry.authStorage.login(providerId as OAuthProvider, {
 				onAuth: (info: { url: string; instructions?: string }) => {
 					const block = new TranscriptBlock();
-					this.ctx.chatContainer.addChild(block);
 					block.addChild(new Text(theme.fg("dim", info.url), 1, 0));
 					const hyperlink = `\x1b]8;;${info.url}\x07Click here to login\x1b]8;;\x07`;
 					block.addChild(new Text(theme.fg("accent", hyperlink), 1, 0));
@@ -945,17 +944,16 @@ export class SelectorController {
 						block.addChild(new Spacer(1));
 						block.addChild(new Text(theme.fg("dim", MANUAL_LOGIN_TIP), 1, 0));
 					}
-					this.ctx.ui.requestRender();
+					this.ctx.present(block);
 					this.ctx.openInBrowser(info.url);
 				},
 				onPrompt: async (prompt: { message: string; placeholder?: string }) => {
 					const promptBlock = new TranscriptBlock();
-					this.ctx.chatContainer.addChild(promptBlock);
 					promptBlock.addChild(new Text(theme.fg("warning", prompt.message), 1, 0));
 					if (prompt.placeholder) {
 						promptBlock.addChild(new Text(theme.fg("dim", prompt.placeholder), 1, 0));
 					}
-					this.ctx.ui.requestRender();
+					this.ctx.present(promptBlock);
 					const { promise, resolve } = Promise.withResolvers<string>();
 					const codeInput = new Input();
 					codeInput.onSubmit = () => {
@@ -972,8 +970,7 @@ export class SelectorController {
 					return promise;
 				},
 				onProgress: (message: string) => {
-					this.ctx.chatContainer.addChild(new Text(theme.fg("dim", message), 1, 0));
-					this.ctx.ui.requestRender();
+					this.ctx.present(new Text(theme.fg("dim", message), 1, 0));
 				},
 				onManualCodeInput: useManualInput ? () => manualInput.waitForInput(providerId) : undefined,
 			});
@@ -983,8 +980,7 @@ export class SelectorController {
 				new Text(theme.fg("success", `${theme.status.success} Successfully logged in to ${providerId}`), 1, 0),
 			);
 			block.addChild(new Text(theme.fg("dim", `Credentials saved to ${getAgentDbPath()}`), 1, 0));
-			this.ctx.chatContainer.addChild(block);
-			this.ctx.ui.requestRender();
+			this.ctx.present(block);
 		} catch (error: unknown) {
 			this.ctx.showError(`Login failed: ${error instanceof Error ? error.message : String(error)}`);
 		} finally {
@@ -1017,8 +1013,7 @@ export class SelectorController {
 					new Text(theme.fg("warning", `${providerId} is still authenticated via ${remainingSource}`), 1, 0),
 				);
 			}
-			this.ctx.chatContainer.addChild(block);
-			this.ctx.ui.requestRender();
+			this.ctx.present(block);
 		} catch (error: unknown) {
 			this.ctx.showError(`Logout failed: ${error instanceof Error ? error.message : String(error)}`);
 		}
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index 6abe5cb10..eb5b8b630 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -94,6 +94,7 @@ import { getSessionAccentAnsi, getSessionAccentHex } from "../utils/session-colo
 import { popTerminalTitle, pushTerminalTitle, setSessionTerminalTitle } from "../utils/title-generator";
 import type { AssistantMessageComponent } from "./components/assistant-message";
 import type { BashExecutionComponent } from "./components/bash-execution";
+import { ChatBlock, type ChatBlockHost } from "./components/chat-block";
 import { CustomEditor } from "./components/custom-editor";
 import { DynamicBorder } from "./components/dynamic-border";
 import { ErrorBannerComponent } from "./components/error-banner";
@@ -367,6 +368,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	#eventBus?: EventBus;
 	#eventBusUnsubscribers: Array<() => void> = [];
 	#welcomeComponent?: WelcomeComponent;
+	readonly #chatHost: ChatBlockHost = { requestRender: () => this.ui.requestRender() };
 
 	constructor(
 		session: AgentSession,
@@ -2529,6 +2531,25 @@ export class InteractiveMode implements InteractiveModeContext {
 	}
 
 	// UI helpers
+	present(content: Component | readonly Component[]): void {
+		if (Array.isArray(content)) {
+			for (const item of content) this.#mountChatChild(item);
+		} else {
+			this.#mountChatChild(content as Component);
+		}
+		this.ui.requestRender();
+	}
+
+	#mountChatChild(item: Component): void {
+		this.chatContainer.addChild(item);
+		if (item instanceof ChatBlock) item.mount(this.#chatHost);
+	}
+
+	resetTranscript(): void {
+		this.chatContainer.dispose();
+		this.chatContainer.clear();
+	}
+
 	showStatus(message: string, options?: { dim?: boolean }): void {
 		this.#uiHelpers.showStatus(message, options);
 	}
diff --git a/packages/coding-agent/src/modes/types.ts b/packages/coding-agent/src/modes/types.ts
index de2cfa880..c49595d4e 100644
--- a/packages/coding-agent/src/modes/types.ts
+++ b/packages/coding-agent/src/modes/types.ts
@@ -158,6 +158,20 @@ export interface InteractiveModeContext {
 	handleBackgroundEvent(event: AgentSessionEvent): Promise<void>;
 
 	// UI helpers
+	/**
+	 * Mount transcript content and repaint once. The single sink for "show this in
+	 * chat": producers build and return a `Component` (or a `ChatBlock` carrying
+	 * its own lifecycle) and hand it here instead of touching `chatContainer` /
+	 * `ui.requestRender()` directly. `ChatBlock`s are mounted (their `onMount`
+	 * runs) so their timers/subscriptions start.
+	 */
+	present(content: Component | readonly Component[]): void;
+	/**
+	 * Dispose every live block in the transcript (stopping timers/subscriptions)
+	 * and clear it. Used before a full rebuild so animated/streaming blocks do not
+	 * leak.
+	 */
+	resetTranscript(): void;
 	showStatus(message: string, options?: { dim?: boolean }): void;
 	showError(message: string): void;
 	showPinnedError(message: string): void;
diff --git a/packages/coding-agent/src/modes/utils/ui-helpers.ts b/packages/coding-agent/src/modes/utils/ui-helpers.ts
index fca5bea57..140a43d4b 100644
--- a/packages/coding-agent/src/modes/utils/ui-helpers.ts
+++ b/packages/coding-agent/src/modes/utils/ui-helpers.ts
@@ -91,11 +91,9 @@ export class UiHelpers {
 
 		const spacer = new Spacer(1);
 		const text = new Text(rendered, 1, 0);
-		this.ctx.chatContainer.addChild(spacer);
-		this.ctx.chatContainer.addChild(text);
+		this.ctx.present([spacer, text]);
 		this.ctx.lastStatusSpacer = spacer;
 		this.ctx.lastStatusText = text;
-		this.ctx.ui.requestRender();
 	}
 
 	addMessageToChat(
@@ -492,8 +490,15 @@ export class UiHelpers {
 	renderInitialMessages(prebuiltContext?: SessionContext, options: RenderInitialMessagesOptions = {}): void {
 		// This path is used to rebuild the visible chat transcript (e.g. after custom/debug UI).
 		// Clear existing rendered chat first to avoid duplicating the full session in the container.
+		// On a non-preserving rebuild the existing blocks are discarded for good, so
+		// dispose them (stopping any live timers/subscriptions) before clearing. When
+		// preserving, the same instances are re-added below, so detach without dispose.
 		const preservedChatChildren = options.preserveExistingChat ? this.ctx.chatContainer.children : undefined;
-		this.ctx.chatContainer.clear();
+		if (preservedChatChildren) {
+			this.ctx.chatContainer.clear();
+		} else {
+			this.ctx.resetTranscript();
+		}
 		this.ctx.pendingMessagesContainer.clear();
 		this.ctx.pendingBashComponents = [];
 		this.ctx.pendingPythonComponents = [];
@@ -544,9 +549,7 @@ export class UiHelpers {
 			process.stderr.write(`Error: ${errorMessage}\n`);
 			return;
 		}
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(theme.fg("error", `Error: ${errorMessage}`), 1, 0));
-		this.ctx.ui.requestRender();
+		this.ctx.present([new Spacer(1), new Text(theme.fg("error", `Error: ${errorMessage}`), 1, 0)]);
 	}
 
 	showWarning(warningMessage: string): void {
@@ -554,9 +557,7 @@ export class UiHelpers {
 			process.stderr.write(`Warning: ${warningMessage}\n`);
 			return;
 		}
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(theme.fg("warning", `Warning: ${warningMessage}`), 1, 0));
-		this.ctx.ui.requestRender();
+		this.ctx.present([new Spacer(1), new Text(theme.fg("warning", `Warning: ${warningMessage}`), 1, 0)]);
 	}
 
 	showNewVersionNotification(newVersion: string): void {
@@ -573,8 +574,7 @@ export class UiHelpers {
 			),
 		);
 		block.addChild(new DynamicBorder(text => theme.fg("warning", text)));
-		this.ctx.chatContainer.addChild(block);
-		this.ctx.ui.requestRender();
+		this.ctx.present(block);
 	}
 
 	updatePendingMessagesDisplay(): void {
diff --git a/packages/coding-agent/test/interactive-mode-status.test.ts b/packages/coding-agent/test/interactive-mode-status.test.ts
index 92bfc8987..aae1a575a 100644
--- a/packages/coding-agent/test/interactive-mode-status.test.ts
+++ b/packages/coding-agent/test/interactive-mode-status.test.ts
@@ -4,7 +4,7 @@ import { initTheme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
 import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/types";
 import { UiHelpers } from "@oh-my-pi/pi-coding-agent/modes/utils/ui-helpers";
 import { buildSessionContext, type SessionContext } from "@oh-my-pi/pi-coding-agent/session/session-manager";
-import { Container } from "@oh-my-pi/pi-tui";
+import { type Component, Container } from "@oh-my-pi/pi-tui";
 
 function renderLastLine(container: Container, width = 120): string {
 	const last = container.children[container.children.length - 1];
@@ -25,6 +25,11 @@ function createInitialRenderHarness(): { ctx: InteractiveModeContext; helpers: U
 		pendingPythonComponents: [],
 		pendingTools: new Map(),
 		ui: { requestRender: vi.fn() },
+		present: (content: Component | readonly Component[]) => {
+			const items = Array.isArray(content) ? content : [content];
+			for (const item of items) ctx.chatContainer.addChild(item);
+			ctx.ui.requestRender();
+		},
 		isBackgrounded: false,
 		sessionManager: {
 			buildSessionContext: () => buildSessionContext([]),
@@ -59,6 +64,11 @@ describe("InteractiveMode.showStatus", () => {
 		const ctx = {
 			chatContainer: new Container(),
 			ui: { requestRender: vi.fn() },
+			present: (content: Component | readonly Component[]) => {
+				const items = Array.isArray(content) ? content : [content];
+				for (const item of items) ctx.chatContainer.addChild(item);
+				ctx.ui.requestRender();
+			},
 			isBackgrounded: false,
 			lastStatusSpacer: undefined,
 			lastStatusText: undefined,
@@ -80,6 +90,11 @@ describe("InteractiveMode.showStatus", () => {
 		const ctx = {
 			chatContainer: new Container(),
 			ui: { requestRender: vi.fn() },
+			present: (content: Component | readonly Component[]) => {
+				const items = Array.isArray(content) ? content : [content];
+				for (const item of items) ctx.chatContainer.addChild(item);
+				ctx.ui.requestRender();
+			},
 			isBackgrounded: false,
 			lastStatusSpacer: undefined,
 			lastStatusText: undefined,
diff --git a/packages/coding-agent/test/issue-956-repro.test.ts b/packages/coding-agent/test/issue-956-repro.test.ts
index f7a1b38c7..1d1f4872b 100644
--- a/packages/coding-agent/test/issue-956-repro.test.ts
+++ b/packages/coding-agent/test/issue-956-repro.test.ts
@@ -80,6 +80,10 @@ describe("issue #956: interactive /mcp test", () => {
 		const disconnectServer = vi.spyOn(mcpClient, "disconnectServer").mockResolvedValue();
 		const controller = new MCPCommandController({
 			chatContainer: { addChild },
+			present: (content: unknown) => {
+				for (const item of Array.isArray(content) ? content : [content]) addChild(item);
+				requestRender();
+			},
 			ui: { requestRender },
 			editor: {},
 			showError,
diff --git a/packages/coding-agent/test/modes/components/chat-block.test.ts b/packages/coding-agent/test/modes/components/chat-block.test.ts
new file mode 100644
index 000000000..703504b9d
--- /dev/null
+++ b/packages/coding-agent/test/modes/components/chat-block.test.ts
@@ -0,0 +1,143 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import { ChatBlock, type ChatBlockHost } from "@oh-my-pi/pi-coding-agent/modes/components/chat-block";
+import type { Component } from "@oh-my-pi/pi-tui";
+
+/** Concrete subclass exposing the protected lifecycle seams for assertions. */
+class TestBlock extends ChatBlock {
+	mountCount = 0;
+	cleanupCount = 0;
+
+	protected override onMount(): void {
+		this.mountCount++;
+		this.onCleanup(() => {
+			this.cleanupCount++;
+		});
+	}
+
+	/** Public proxy for the protected requestRender. */
+	ping(): void {
+		this.requestRender();
+	}
+
+	/** Public proxy for the protected onCleanup. */
+	register(cleanup: () => void): void {
+		this.onCleanup(cleanup);
+	}
+}
+
+describe("ChatBlock lifecycle", () => {
+	let renders: number;
+	let host: ChatBlockHost;
+
+	beforeEach(() => {
+		renders = 0;
+		host = {
+			requestRender: () => {
+				renders++;
+			},
+		};
+	});
+
+	it("runs onMount exactly once; a second mount is a no-op", () => {
+		const block = new TestBlock();
+		expect(block.mountCount).toBe(0);
+		block.mount(host);
+		block.mount(host);
+		expect(block.mountCount).toBe(1);
+	});
+
+	it("is finalized until mounted, live while active, finalized after finish", () => {
+		const block = new TestBlock();
+		expect(block.isTranscriptBlockFinalized()).toBe(true);
+		block.mount(host);
+		expect(block.isTranscriptBlockFinalized()).toBe(false);
+		block.finish();
+		expect(block.isTranscriptBlockFinalized()).toBe(true);
+	});
+
+	it("finish runs cleanups once and requests one render", () => {
+		const block = new TestBlock();
+		block.mount(host);
+		const before = renders;
+		block.finish();
+		expect(block.cleanupCount).toBe(1);
+		expect(renders).toBe(before + 1);
+		block.finish();
+		expect(block.cleanupCount).toBe(1);
+	});
+
+	it("dispose runs cleanups once, is idempotent, and finalizes", () => {
+		const block = new TestBlock();
+		block.mount(host);
+		block.dispose();
+		expect(block.cleanupCount).toBe(1);
+		expect(block.isTranscriptBlockFinalized()).toBe(true);
+		block.dispose();
+		expect(block.cleanupCount).toBe(1);
+	});
+
+	it("finish then dispose does not double-run cleanups", () => {
+		const block = new TestBlock();
+		block.mount(host);
+		block.finish();
+		block.dispose();
+		expect(block.cleanupCount).toBe(1);
+	});
+
+	it("requestRender routes to the host only between mount and dispose", () => {
+		const block = new TestBlock();
+		block.ping();
+		expect(renders).toBe(0);
+		block.mount(host);
+		block.ping();
+		expect(renders).toBe(1);
+		block.dispose();
+		const after = renders;
+		block.ping();
+		expect(renders).toBe(after);
+	});
+
+	it("onCleanup registered after dispose runs immediately so callers never leak", () => {
+		const block = new TestBlock();
+		block.mount(host);
+		block.dispose();
+		let ran = false;
+		block.register(() => {
+			ran = true;
+		});
+		expect(ran).toBe(true);
+	});
+
+	it("dispose propagates to child components", () => {
+		const block = new TestBlock();
+		let childDisposed = 0;
+		const child: Component = {
+			render: () => [],
+			invalidate: () => {},
+			dispose: () => {
+				childDisposed++;
+			},
+		};
+		block.addChild(child);
+		block.mount(host);
+		block.dispose();
+		expect(childDisposed).toBe(1);
+	});
+
+	it("tears down a timer effect started in onMount when finished", async () => {
+		class TimerBlock extends ChatBlock {
+			protected override onMount(): void {
+				const id = setInterval(() => this.requestRender(), 5);
+				this.onCleanup(() => clearInterval(id));
+			}
+		}
+		const block = new TimerBlock();
+		block.mount(host);
+		await Bun.sleep(25);
+		expect(renders).toBeGreaterThan(0); // timer fired while active
+		block.finish();
+		const settled = renders; // includes finish()'s own render
+		await Bun.sleep(25);
+		expect(renders).toBe(settled); // interval torn down — no further ticks
+	});
+});
diff --git a/packages/coding-agent/test/modes/utils/render-initial-messages-dedupe.test.ts b/packages/coding-agent/test/modes/utils/render-initial-messages-dedupe.test.ts
index be1d43af3..52de0a13e 100644
--- a/packages/coding-agent/test/modes/utils/render-initial-messages-dedupe.test.ts
+++ b/packages/coding-agent/test/modes/utils/render-initial-messages-dedupe.test.ts
@@ -65,6 +65,7 @@ function makeCtx(sessionManager?: Pick<SessionManager, "buildSessionContext" | "
 		renderSessionContext: renderSessionContextSpy,
 		showStatus: vi.fn(),
 		ui: { requestRender: vi.fn() },
+		resetTranscript: () => ctx.chatContainer.clear(),
 	} as unknown as InteractiveModeContext;
 
 	return { ctx, buildSessionContextSpy, renderSessionContextSpy };
diff --git a/packages/coding-agent/test/tools/render-utils.test.ts b/packages/coding-agent/test/tools/render-utils.test.ts
index db3eb865f..f1c32d99c 100644
--- a/packages/coding-agent/test/tools/render-utils.test.ts
+++ b/packages/coding-agent/test/tools/render-utils.test.ts
@@ -2,7 +2,7 @@ import { afterEach, beforeAll, beforeEach, describe, expect, it } from "bun:test
 import * as os from "node:os";
 import * as path from "node:path";
 import { KeybindingsManager } from "@oh-my-pi/pi-coding-agent/config/keybindings";
-import { getThemeByName, initTheme, theme, type Theme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
+import { getThemeByName, initTheme, type Theme, theme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
 import {
 	dedupeParseErrors,
 	expandKeyHint,
@@ -14,7 +14,7 @@ import {
 	formatScreenshot,
 	truncateDiffByHunk,
 } from "@oh-my-pi/pi-coding-agent/tools/render-utils";
-import { getKeybindings, setKeybindings } from "@oh-my-pi/pi-tui";
+import { getKeybindings, setKeybindings, type KeybindingsManager as TuiKeybindingsManager } from "@oh-my-pi/pi-tui";
 
 describe("parse error formatting", () => {
 	it("deduplicates parse errors while preserving order", () => {
@@ -295,7 +295,7 @@ describe("formatExpandHint / expandKeyHint", () => {
 		format: { bracketLeft: "[", bracketRight: "]" },
 	} as unknown as Theme;
 
-	let previous: ReturnType<typeof getKeybindings>;
+	let previous: TuiKeybindingsManager;
 	beforeEach(() => {
 		previous = getKeybindings();
 	});
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index d864ad9ba..412067f39 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -1,6 +1,11 @@
 # Changelog
 
 ## [Unreleased]
+### Added
+
+- Added an optional `dispose()` lifecycle method to `Component` so components can release timers and subscriptions during permanent teardown
+- Added `Container.dispose()` to propagate teardown to child components when a component tree is permanently discarded
+- Added `Loader.dispose()` to stop the loader animation timer when the component is disposed
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/tui/src/components/loader.ts b/packages/tui/src/components/loader.ts
index b9b2ffca9..5f0393a77 100644
--- a/packages/tui/src/components/loader.ts
+++ b/packages/tui/src/components/loader.ts
@@ -71,6 +71,11 @@ export class Loader extends Text {
 		}
 	}
 
+	/** Lifecycle teardown: stop the animation timer. Idempotent. */
+	dispose() {
+		this.stop();
+	}
+
 	setMessage(message: string) {
 		this.message = message;
 		this.#updateDisplay();
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 62db855a2..4b35fc3d5 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -128,6 +128,14 @@ export interface Component {
 	 * Called when theme changes or when component needs to re-render from scratch.
 	 */
 	invalidate(): void;
+
+	/**
+	 * Optional teardown. Called when the component is permanently removed from
+	 * the live tree (e.g. a transcript reset). Release timers, intervals, and
+	 * subscriptions here. Must be idempotent. Containers propagate dispose to
+	 * their children; leaf components without resources may omit it.
+	 */
+	dispose?(): void;
 }
 
 /**
@@ -339,6 +347,17 @@ export class Container implements Component {
 		}
 	}
 
+	/**
+	 * Propagate teardown to children. Call when the container's children are
+	 * being permanently discarded (not when they are detached for reuse — use
+	 * {@link clear} for that). Idempotent per child via each child's own dispose.
+	 */
+	dispose(): void {
+		for (const child of this.children) {
+			child.dispose?.();
+		}
+	}
+
 	render(width: number): string[] {
 		width = Math.max(1, width);
 		const lines: string[] = [];
diff --git a/packages/tui/test/container-dispose.test.ts b/packages/tui/test/container-dispose.test.ts
new file mode 100644
index 000000000..7c497a2f6
--- /dev/null
+++ b/packages/tui/test/container-dispose.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "bun:test";
+import { type Component, Container } from "@oh-my-pi/pi-tui";
+
+function inert(dispose?: () => void): Component {
+	return { render: () => [], invalidate: () => {}, dispose };
+}
+
+describe("Container.dispose", () => {
+	it("calls dispose on each child and tolerates children without dispose", () => {
+		const order: string[] = [];
+		const container = new Container();
+		container.addChild(inert(() => order.push("a")));
+		container.addChild(inert()); // no dispose — must not throw
+		container.addChild(inert(() => order.push("c")));
+
+		expect(() => container.dispose()).not.toThrow();
+		expect(order).toEqual(["a", "c"]);
+	});
+
+	it("recurses through nested containers", () => {
+		let leafDisposed = 0;
+		const outer = new Container();
+		const inner = new Container();
+		inner.addChild(inert(() => leafDisposed++));
+		outer.addChild(inner);
+
+		outer.dispose();
+		expect(leafDisposed).toBe(1);
+	});
+});
diff --git a/packages/tui/test/loader.test.ts b/packages/tui/test/loader.test.ts
index 06b35dcfa..7081d68ca 100644
--- a/packages/tui/test/loader.test.ts
+++ b/packages/tui/test/loader.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "bun:test";
+import { describe, expect, it, spyOn } from "bun:test";
 import { TUI } from "@oh-my-pi/pi-tui";
 import { Loader } from "@oh-my-pi/pi-tui/components/loader";
 import { visibleWidth } from "@oh-my-pi/pi-tui/utils";
@@ -28,4 +28,23 @@ describe("Loader component", () => {
 		loader.stop();
 		tui.stop();
 	});
+
+	it("dispose() stops the animation so no further renders are scheduled", async () => {
+		const term = new VirtualTerminal(20, 4);
+		const tui = new TUI(term);
+		const loader = new Loader(
+			tui,
+			text => text,
+			text => text,
+			"Checking",
+			["a", "b", "c"],
+		);
+		const spy = spyOn(tui, "requestRender");
+		loader.dispose();
+		const after = spy.mock.calls.length;
+		await Bun.sleep(40); // longer than the spinner interval
+		expect(spy.mock.calls.length).toBe(after);
+		expect(() => loader.dispose()).not.toThrow(); // idempotent
+		tui.stop();
+	});
 });

From f1e2e51a4b84427a71fa0660eb5ef2c567f83ea3 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 03:37:48 +0200
Subject: [PATCH 080/181] feat(coding-agent): added /fresh to reset provider
 state while keeping session files

- Added `AgentSession.freshSession()` to rotate provider-facing IDs and prune provider stream state.
- Added `/fresh` command handling in the builtin registry and mode command flow.
- Kept persisted session metadata intact during `/fresh` and cleared transient IDs on session switches.
- Invalidated `appendOnlyContext` and provider caches when refreshing provider state.
---
 ...ion-operations-export-share-fork-resume.md |   3 +-
 packages/coding-agent/CHANGELOG.md            |   2 +
 .../modes/controllers/command-controller.ts   |  12 +++
 .../src/modes/interactive-mode.ts             |   4 +
 packages/coding-agent/src/modes/types.ts      |   1 +
 .../coding-agent/src/session/agent-session.ts |  41 ++++++-
 .../src/slash-commands/builtin-registry.ts    |  25 +++++
 .../test/agent-session-fresh.test.ts          | 101 ++++++++++++++++++
 .../test/slash-commands/fresh.test.ts         |  43 ++++++++
 9 files changed, 229 insertions(+), 3 deletions(-)
 create mode 100644 packages/coding-agent/test/agent-session-fresh.test.ts
 create mode 100644 packages/coding-agent/test/slash-commands/fresh.test.ts

diff --git a/docs/session-operations-export-share-fork-resume.md b/docs/session-operations-export-share-fork-resume.md
index 0173137c1..0d6de4f70 100644
--- a/docs/session-operations-export-share-fork-resume.md
+++ b/docs/session-operations-export-share-fork-resume.md
@@ -1,4 +1,4 @@
-# Session Operations: export, dump, share, fork, resume/continue
+# Session Operations: export, dump, share, fresh, fork, resume/continue
 
 This document describes operator-visible behavior for session export/share/fork/resume operations as currently implemented.
 
@@ -19,6 +19,7 @@ This document describes operator-visible behavior for session export/share/fork/
 | `/export [path]`                        | Interactive slash command | No                                    | No                                                                                 | HTML file                                                       |
 | `--export <session.jsonl> [outputPath]` | CLI startup fast-path     | No runtime session mutation           | No active session; reads target file                                               | HTML file                                                       |
 | `/share`                                | Interactive slash command | No                                    | No                                                                                 | Temp HTML + share URL/gist                                      |
+| `/fresh`                               | Interactive slash command | Yes (provider-facing in-memory id/state only) | No; keeps current session file/header                                               | None                                                            |
 | `/fork`                                 | Interactive slash command | Yes (active session identity changes) | Creates new session file and switches current session to it (persistent mode only) | Copies artifact directory to new session namespace when present |
 | `--fork <id\|path>`                     | CLI startup               | Yes after session creation            | Creates a new session fork from the selected source into current cwd/session dir   | None                                                            |
 | `/resume`                               | Interactive slash command | Yes (active in-memory state replaced) | Switches to selected existing session file                                         | None                                                            |
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 8ce20eb81..037d2a243 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -3,6 +3,8 @@
 ## [Unreleased]
 ### Added
 
+- Added `/fresh` to rotate the provider-facing session id and clear in-memory provider stream/cache state without changing the local session file.
+
 - Added a `ChatBlock` transcript primitive (`modes/components/chat-block.ts`) and a single `ctx.present(...)` sink (with `ctx.resetTranscript()`) so chat output is mounted in one place instead of the repeated `chatContainer.addChild(...)` + `ui.requestRender()` pattern scattered across controllers. `ChatBlock` carries a React/Svelte-style lifecycle — `onMount` starts effects, `onCleanup` registers teardown, `finish()` self-completes (stops timers and freezes the block at its final content), and `dispose()`/`resetTranscript()` tears everything down — so animated blocks own their own resources instead of leaking `setInterval`/`requestRender` bookkeeping into callers. The MCP "Connecting…" spinner is now such a block.
 
 ### Changed
diff --git a/packages/coding-agent/src/modes/controllers/command-controller.ts b/packages/coding-agent/src/modes/controllers/command-controller.ts
index c19f93269..59a4b89de 100644
--- a/packages/coding-agent/src/modes/controllers/command-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/command-controller.ts
@@ -802,6 +802,18 @@ export class CommandController {
 		await this.#runNewSessionFlow();
 	}
 
+	async handleFreshCommand(): Promise<void> {
+		const result = this.ctx.session.freshSession();
+		if (!result) {
+			this.ctx.showWarning("Wait for the current response to finish or abort it before refreshing provider state.");
+			return;
+		}
+		const stateLabel = result.closedProviderSessions === 1 ? "provider state" : "provider states";
+		this.ctx.statusLine.invalidate();
+		this.ctx.updateEditorTopBorder();
+		this.ctx.showStatus(`Fresh provider session started (${result.closedProviderSessions} ${stateLabel} pruned).`);
+	}
+
 	async handleDropCommand(): Promise<void> {
 		if (!this.ctx.sessionManager.getSessionFile()) {
 			this.ctx.showError("Nothing to drop (in-memory session)");
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index eb5b8b630..c596e9df2 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -2806,6 +2806,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleClearCommand();
 	}
 
+	handleFreshCommand(): Promise<void> {
+		return this.#commandController.handleFreshCommand();
+	}
+
 	handleDropCommand(): Promise<void> {
 		this.#prepareSessionSwitch();
 		return this.#commandController.handleDropCommand();
diff --git a/packages/coding-agent/src/modes/types.ts b/packages/coding-agent/src/modes/types.ts
index c49595d4e..f5c09625c 100644
--- a/packages/coding-agent/src/modes/types.ts
+++ b/packages/coding-agent/src/modes/types.ts
@@ -247,6 +247,7 @@ export interface InteractiveModeContext {
 	handleDumpCommand(): void;
 	handleDebugTranscriptCommand(): Promise<void>;
 	handleClearCommand(): Promise<void>;
+	handleFreshCommand(): Promise<void>;
 	handleDropCommand(): Promise<void>;
 	handleForkCommand(): Promise<void>;
 	handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index 746ef86e0..dd14bd898 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -471,6 +471,12 @@ export interface SessionStats {
 	cost: number;
 }
 
+export interface FreshSessionResult {
+	previousSessionId: string;
+	sessionId: string;
+	closedProviderSessions: number;
+}
+
 /** Internal marker for hook messages queued through the agent loop */
 // ============================================================================
 // Constants
@@ -922,6 +928,7 @@ export class AgentSession {
 	#agentId: string | undefined;
 	#agentRegistry: AgentRegistry | undefined;
 	#providerSessionId: string | undefined;
+	#freshProviderSessionId: string | undefined;
 	#isDisposed = false;
 	// Extension system
 	#extensionRunner: ExtensionRunner | undefined = undefined;
@@ -2946,6 +2953,10 @@ export class AgentSession {
 		this.#unsubscribeAgent = this.agent.subscribe(this.#handleAgentEvent);
 	}
 
+	#activeProviderSessionId(sessionId?: string): string {
+		return this.#freshProviderSessionId ?? this.#providerSessionId ?? sessionId ?? this.sessionManager.getSessionId();
+	}
+
 	/**
 	 * Set agent.sessionId from the session manager and install a dynamic
 	 * metadata resolver so every Anthropic API request carries
@@ -2958,7 +2969,7 @@ export class AgentSession {
 	 * `#syncAgentSessionId()` on every such event.
 	 */
 	#syncAgentSessionId(sessionId?: string): void {
-		const sid = this.#providerSessionId ?? sessionId ?? this.sessionManager.getSessionId();
+		const sid = this.#activeProviderSessionId(sessionId);
 		this.agent.sessionId = sid;
 		this.agent.setMetadataResolver((provider: string) =>
 			buildSessionMetadata(sid, provider, this.#modelRegistry.authStorage),
@@ -3088,6 +3099,23 @@ export class AgentSession {
 		this.#providerSessionState.clear();
 	}
 
+	freshSession(): FreshSessionResult | undefined {
+		if (this.isStreaming) return undefined;
+		const previousSessionId = this.sessionId;
+		const closedProviderSessions = this.#providerSessionState.size;
+		this.#closeAllProviderSessions("fresh session");
+		this.#freshProviderSessionId = Bun.randomUUIDv7();
+		this.#syncAgentSessionId();
+		this.#rekeyHindsightMemoryForCurrentSessionId();
+		this.#rekeyMnemopiMemoryForCurrentSessionId();
+		this.agent.appendOnlyContext?.invalidateForModelChange();
+		return {
+			previousSessionId,
+			sessionId: this.sessionId,
+			closedProviderSessions,
+		};
+	}
+
 	// =========================================================================
 	// Read-only State Access
 	// =========================================================================
@@ -3992,7 +4020,7 @@ export class AgentSession {
 
 	/** Current session ID */
 	get sessionId(): string {
-		return this.#providerSessionId ?? this.sessionManager.getSessionId();
+		return this.#activeProviderSessionId();
 	}
 	getEvalSessionId(): string | null {
 		if (this.#parentEvalSessionId !== undefined) return this.#parentEvalSessionId;
@@ -5162,6 +5190,7 @@ export class AgentSession {
 		}
 		await this.sessionManager.newSession(options);
 		this.setTodoPhases([]);
+		this.#freshProviderSessionId = undefined;
 		this.#syncAgentSessionId();
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 		this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -5259,6 +5288,7 @@ export class AgentSession {
 		}
 
 		// Update agent session ID
+		this.#freshProviderSessionId = undefined;
 		this.#syncAgentSessionId();
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 		this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -6226,6 +6256,7 @@ export class AgentSession {
 			this.#cancelOwnAsyncJobs();
 			await this.sessionManager.newSession(previousSessionFile ? { parentSession: previousSessionFile } : undefined);
 			this.agent.reset();
+			this.#freshProviderSessionId = undefined;
 			this.#syncAgentSessionId();
 			this.#rekeyHindsightMemoryForCurrentSessionId();
 			this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -8941,6 +8972,7 @@ export class AgentSession {
 		const previousTools = [...this.agent.state.tools];
 		const previousBaseSystemPrompt = this.#baseSystemPrompt;
 		const previousSystemPrompt = this.agent.state.systemPrompt;
+		const previousFreshProviderSessionId = this.#freshProviderSessionId;
 		const previousFallbackSelectedMCPToolNames = previousSessionFile
 			? this.#getSessionDefaultSelectedMCPToolNames(previousSessionFile)
 			: undefined;
@@ -8952,6 +8984,9 @@ export class AgentSession {
 
 		try {
 			await this.sessionManager.setSessionFile(sessionPath);
+			if (switchingToDifferentSession) {
+				this.#freshProviderSessionId = undefined;
+			}
 			this.#syncAgentSessionId();
 			this.#rekeyHindsightMemoryForCurrentSessionId();
 			this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -9061,6 +9096,7 @@ export class AgentSession {
 			return true;
 		} catch (error) {
 			this.sessionManager.restoreState(previousSessionState);
+			this.#freshProviderSessionId = previousFreshProviderSessionId;
 			this.#syncAgentSessionId(previousSessionState.sessionId);
 			this.#rekeyHindsightMemoryForCurrentSessionId();
 			this.#rekeyMnemopiMemoryForCurrentSessionId();
@@ -9159,6 +9195,7 @@ export class AgentSession {
 			this.sessionManager.createBranchedSession(selectedEntry.parentId);
 		}
 		this.#syncTodoPhasesFromBranch();
+		this.#freshProviderSessionId = undefined;
 		this.#syncAgentSessionId();
 		this.#rekeyHindsightMemoryForCurrentSessionId();
 		this.#rekeyMnemopiMemoryForCurrentSessionId();
diff --git a/packages/coding-agent/src/slash-commands/builtin-registry.ts b/packages/coding-agent/src/slash-commands/builtin-registry.ts
index bfb059a70..57ecac800 100644
--- a/packages/coding-agent/src/slash-commands/builtin-registry.ts
+++ b/packages/coding-agent/src/slash-commands/builtin-registry.ts
@@ -21,6 +21,7 @@ import {
 } from "../extensibility/plugins/marketplace";
 import { resolveMemoryBackend } from "../memory-backend";
 import type { InteractiveModeContext } from "../modes/types";
+import type { FreshSessionResult } from "../session/agent-session";
 import { formatShakeSummary, type ShakeMode } from "../session/shake-types";
 import { getChangelogPath, parseChangelog } from "../utils/changelog";
 import { buildContextReportText } from "./helpers/context-report";
@@ -52,6 +53,11 @@ function refreshStatusLine(ctx: InteractiveModeContext): void {
 	ctx.ui.requestRender();
 }
 
+function formatFreshSessionResult(result: FreshSessionResult): string {
+	const stateLabel = result.closedProviderSessions === 1 ? "provider state" : "provider states";
+	return `Fresh provider session started (${result.closedProviderSessions} ${stateLabel} pruned).`;
+}
+
 const shutdownHandlerTui = (_command: ParsedSlashCommand, runtime: TuiSlashCommandRuntime): SlashCommandResult => {
 	runtime.ctx.editor.setText("");
 	void runtime.ctx.shutdown();
@@ -770,6 +776,25 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			await runtime.ctx.handleClearCommand();
 		},
 	},
+	{
+		name: "fresh",
+		description: "Reset provider stream state without changing the local transcript",
+		handle: async (_command, runtime) => {
+			const result = runtime.session.freshSession();
+			if (!result) {
+				await runtime.output(
+					"Wait for the current response to finish or abort it before refreshing provider state.",
+				);
+				return commandConsumed();
+			}
+			await runtime.output(formatFreshSessionResult(result));
+			return commandConsumed();
+		},
+		handleTui: async (_command, runtime) => {
+			runtime.ctx.editor.setText("");
+			await runtime.ctx.handleFreshCommand();
+		},
+	},
 	{
 		name: "drop",
 		description: "Delete the current session and start a new one",
diff --git a/packages/coding-agent/test/agent-session-fresh.test.ts b/packages/coding-agent/test/agent-session-fresh.test.ts
new file mode 100644
index 000000000..aa294d743
--- /dev/null
+++ b/packages/coding-agent/test/agent-session-fresh.test.ts
@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import * as path from "node:path";
+import { Agent, AppendOnlyContextManager } from "@oh-my-pi/pi-agent-core";
+import type { ProviderSessionState } from "@oh-my-pi/pi-ai";
+import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
+import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import { AgentSession } from "@oh-my-pi/pi-coding-agent/session/agent-session";
+import { AuthStorage } from "@oh-my-pi/pi-coding-agent/session/auth-storage";
+import { SessionManager } from "@oh-my-pi/pi-coding-agent/session/session-manager";
+import { TempDir } from "@oh-my-pi/pi-utils";
+
+interface FreshHarness {
+	agent: Agent;
+	session: AgentSession;
+	sessionManager: SessionManager;
+}
+
+const cleanup: Array<() => Promise<void>> = [];
+
+afterEach(async () => {
+	while (cleanup.length > 0) {
+		const run = cleanup.pop();
+		if (run) await run();
+	}
+});
+
+async function createFreshHarness(): Promise<FreshHarness> {
+	const tempDir = TempDir.createSync("@pi-agent-session-fresh-");
+	const authStorage = await AuthStorage.create(path.join(tempDir.path(), "auth.db"));
+	const modelRegistry = new ModelRegistry(authStorage, path.join(tempDir.path(), "models.yml"));
+	const sessionManager = SessionManager.create(tempDir.path(), path.join(tempDir.path(), "sessions"));
+	const agent = new Agent({
+		initialState: {
+			systemPrompt: ["Test"],
+			tools: [],
+			messages: [],
+		},
+	});
+	const session = new AgentSession({
+		agent,
+		sessionManager,
+		settings: Settings.isolated(),
+		modelRegistry,
+	});
+	cleanup.push(async () => {
+		await session.dispose();
+		authStorage.close();
+		tempDir.removeSync();
+	});
+	return { agent, session, sessionManager };
+}
+
+describe("AgentSession fresh provider state", () => {
+	it("rotates only the provider-facing session id and prunes cached stream state", async () => {
+		const { agent, session, sessionManager } = await createFreshHarness();
+		const persistedSessionId = sessionManager.getSessionId();
+		const persistedSessionFile = sessionManager.getSessionFile();
+		const persistedHeaderId = sessionManager.getHeader()?.id;
+		let closeCount = 0;
+		const providerState: ProviderSessionState = {
+			close() {
+				closeCount += 1;
+			},
+		};
+		session.providerSessionState.set("websocket", providerState);
+
+		const appendOnlyContext = new AppendOnlyContextManager();
+		agent.setAppendOnlyContext(appendOnlyContext);
+		appendOnlyContext.syncMessages([{ role: "user", content: "cached context" }]);
+		appendOnlyContext.build({ systemPrompt: ["Test"], messages: [], tools: [] }, { intentTracing: false });
+
+		const result = session.freshSession();
+
+		expect(result).toBeDefined();
+		if (!result) return;
+		expect(result.previousSessionId).toBe(persistedSessionId);
+		expect(result.sessionId).not.toBe(persistedSessionId);
+		expect(result.closedProviderSessions).toBe(1);
+		expect(agent.sessionId).toBe(result.sessionId);
+		expect(session.sessionId).toBe(result.sessionId);
+		expect(sessionManager.getSessionId()).toBe(persistedSessionId);
+		expect(sessionManager.getHeader()?.id).toBe(persistedHeaderId);
+		expect(sessionManager.getSessionFile()).toBe(persistedSessionFile);
+		expect(closeCount).toBe(1);
+		expect(session.providerSessionState.size).toBe(0);
+		expect(appendOnlyContext.log.length).toBe(0);
+		expect(appendOnlyContext.prefix.built).toBe(false);
+	});
+
+	it("drops the transient provider id when a real new session starts", async () => {
+		const { session, sessionManager } = await createFreshHarness();
+		const freshResult = session.freshSession();
+		expect(freshResult).toBeDefined();
+		if (!freshResult) return;
+
+		await session.newSession();
+
+		expect(session.sessionId).toBe(sessionManager.getSessionId());
+		expect(session.sessionId).not.toBe(freshResult.sessionId);
+	});
+});
diff --git a/packages/coding-agent/test/slash-commands/fresh.test.ts b/packages/coding-agent/test/slash-commands/fresh.test.ts
new file mode 100644
index 000000000..d20af962b
--- /dev/null
+++ b/packages/coding-agent/test/slash-commands/fresh.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, it, vi } from "bun:test";
+import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/types";
+import { executeBuiltinSlashCommand } from "@oh-my-pi/pi-coding-agent/slash-commands/builtin-registry";
+
+function createRuntimeHarness(handleFreshCommand: InteractiveModeContext["handleFreshCommand"]) {
+	const setText = vi.fn();
+	return {
+		setText,
+		handleFreshCommand,
+		runtime: {
+			ctx: {
+				editor: { setText } as unknown as InteractiveModeContext["editor"],
+				handleFreshCommand,
+			} as InteractiveModeContext,
+			handleBackgroundCommand: () => {},
+		},
+	};
+}
+
+describe("/fresh slash command", () => {
+	it("awaits provider-state refresh before resolving", async () => {
+		const deferred = Promise.withResolvers<void>();
+		const handleFreshCommand = vi.fn(() => deferred.promise);
+		const harness = createRuntimeHarness(handleFreshCommand);
+
+		let settled = false;
+		const execution = executeBuiltinSlashCommand("/fresh", harness.runtime).then(result => {
+			settled = true;
+			return result;
+		});
+
+		await Promise.resolve();
+
+		expect(harness.setText).toHaveBeenCalledWith("");
+		expect(handleFreshCommand).toHaveBeenCalledTimes(1);
+		expect(settled).toBe(false);
+
+		deferred.resolve();
+
+		expect(await execution).toBe(true);
+		expect(settled).toBe(true);
+	});
+});

From 003f89b7c46c1a1cf784eea11ae958bd03e30cc7 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 03:44:27 +0200
Subject: [PATCH 081/181] fix: fixed UTF-8 command slicing in shell fixups

- Converted brush-parser source positions to byte offsets before slicing commands in `try_strip_head_tail` and `try_strip_2to1`, preventing multibyte UTF-8 from misplacing fixup deletions.
- Added regression tests covering trailing `head`/`tail` and `2>&1` strips with Unicode content, and verified rewritten commands re-parse successfully.
---
 crates/pi-shell/src/fixup.rs       | 82 +++++++++++++++++++++++++++---
 packages/coding-agent/CHANGELOG.md |  2 +
 packages/natives/CHANGELOG.md      |  4 ++
 3 files changed, 82 insertions(+), 6 deletions(-)

diff --git a/crates/pi-shell/src/fixup.rs b/crates/pi-shell/src/fixup.rs
index 86b6974d4..f9fe9d70a 100644
--- a/crates/pi-shell/src/fixup.rs
+++ b/crates/pi-shell/src/fixup.rs
@@ -154,7 +154,12 @@ fn try_strip_head_tail(
 	// span under-reports when its suffix contains unlocated `IoRedirect`s
 	// (e.g. the synthetic `2>&1` inserted by `|&`).
 	let bytes = cmd.as_bytes();
-	let last_start = last_loc.start.index;
+	let Some(last_start) = byte_offset(cmd, last_loc.start.index) else {
+		return default;
+	};
+	let Some(last_end) = byte_offset(cmd, last_loc.end.index) else {
+		return default;
+	};
 	let Some(head) = cmd.get(..last_start) else {
 		return default;
 	};
@@ -172,7 +177,7 @@ fn try_strip_head_tail(
 	// Reported text starts at the pipe and is right-trimmed. The deletion
 	// range walks back through any leading whitespace so the rewrite is
 	// contiguous.
-	let stripped_text = cmd[pipe_pos..last_loc.end.index].trim_end().to_owned();
+	let stripped_text = cmd[pipe_pos..last_end].trim_end().to_owned();
 	if stripped_text.is_empty() {
 		return default;
 	}
@@ -180,7 +185,7 @@ fn try_strip_head_tail(
 	while delete_start > 0 && matches!(bytes[delete_start - 1], b' ' | b'\t') {
 		delete_start -= 1;
 	}
-	ranges.push((delete_start, last_loc.end.index));
+	ranges.push((delete_start, last_end));
 	stripped.push(stripped_text);
 	HeadTailOutcome { stripped: true, last_idx: n - 2 }
 }
@@ -253,10 +258,14 @@ fn try_strip_2to1(
 	let Some(name_loc) = name_word.loc.as_ref() else {
 		return;
 	};
-	let mut anchor = name_loc.end.index;
+	let Some(mut anchor) = byte_offset(cmd, name_loc.end.index) else {
+		return;
+	};
 	for item in &suffix.0 {
-		if let Some(loc) = item.location() {
-			anchor = anchor.max(loc.end.index);
+		if let Some(loc) = item.location()
+			&& let Some(end) = byte_offset(cmd, loc.end.index)
+		{
+			anchor = anchor.max(end);
 		}
 	}
 	let bytes = cmd.as_bytes();
@@ -283,6 +292,28 @@ fn try_strip_2to1(
 	stripped.push("2>&1".to_owned());
 }
 
+/// Translate a `brush-parser` source-position index into a byte offset in
+/// `cmd`. The parser counts positions in Unicode scalars (one increment per
+/// `char`; see `tokenizer::next_char`), but we slice `cmd` — a `&str` — by
+/// byte index, so the two diverge as soon as the command contains any
+/// multi-byte UTF-8 (e.g. a `✓`/`×` literal inside a `grep` pattern). Without
+/// this conversion the head/tail and `2>&1` strips cut at the wrong place,
+/// corrupting the command (notably orphaning a closing quote).
+///
+/// Returns `None` only when `char_idx` is past the end of the input. The
+/// end-of-input position (`char_idx == cmd.chars().count()`) maps to
+/// `cmd.len()`.
+fn byte_offset(cmd: &str, char_idx: usize) -> Option<usize> {
+	let mut count = 0usize;
+	for (byte, _) in cmd.char_indices() {
+		if count == char_idx {
+			return Some(byte);
+		}
+		count += 1;
+	}
+	(count == char_idx).then_some(cmd.len())
+}
+
 fn is_stderr_to_stdout(io: &IoRedirect) -> bool {
 	let IoRedirect::File(Some(2), IoFileRedirectKind::DuplicateOutput, target) = io else {
 		return false;
@@ -380,6 +411,45 @@ mod tests {
 		}
 	}
 
+	#[test]
+	fn strips_with_multibyte_content() {
+		// brush-parser reports char-indexed positions; multi-byte UTF-8 before
+		// the trailing `| tail` must not shift the byte-level cut. Regression
+		// for a corrupted command that orphaned the grep pattern's closing
+		// quote (`… |✓|×-80`) and broke later re-parsing.
+		let cases: &[(&str, &str, &[&str])] = &[
+			// Mirrors the real bug: `2>&1` sits mid-pipeline (grep becomes the
+			// effective tail) so only `| tail -80` is stripped, leaving the
+			// quoted grep pattern intact.
+			(
+				"xcodebuild 2>&1 | grep -E \"a|✓|×|b\" | tail -80",
+				"xcodebuild 2>&1 | grep -E \"a|✓|×|b\"",
+				&["| tail -80"],
+			),
+			("echo ✓ | head -3", "echo ✓", &["| head -3"]),
+			("printf '日本語' | tail -n 5", "printf '日本語'", &["| tail -n 5"]),
+		];
+		for (input, want_cmd, want_stripped) in cases {
+			let (cmd, stripped) = run(input);
+			assert_eq!(cmd, *want_cmd, "input: {input:?}");
+			assert_eq!(stripped, *want_stripped, "input: {input:?}");
+			// The rewrite must remain valid shell (no orphaned quote).
+			let options = ParserOptions::default();
+			let source_info = SourceInfo::default();
+			let mut reader = BufReader::new(cmd.as_bytes());
+			let mut parser = Parser::new(&mut reader, &options, &source_info);
+			assert!(parser.parse_program().is_ok(), "rewrite not re-parseable: {cmd:?}");
+		}
+	}
+
+	#[test]
+	fn strips_2to1_after_multibyte() {
+		// Multi-byte before a trailing `2>&1` must not misplace the strip.
+		let (cmd, stripped) = run("echo ✓ × 2>&1");
+		assert_eq!(cmd, "echo ✓ ×");
+		assert_eq!(stripped, vec!["2>&1"]);
+	}
+
 	#[test]
 	fn strips_redundant_2to1() {
 		let cases: &[(&str, &str, &[&str])] = &[
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 037d2a243..3986c9d2c 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -15,6 +15,8 @@
 
 ### Fixed
 
+- Fixed `omp dry-balance --bench` to recover from 401 token failures by re-minting the failing OAuth credential in place before switching accounts
+- Fixed the bash tool corrupting commands that embed multi-byte UTF-8 (e.g. `✓`/`×` inside a `grep -E` pattern) ahead of a trailing `| head`/`| tail`. The `bash.stripTrailingHeadTail` rewrite cut at char-offset positions reported by `brush-parser` while slicing the command by byte offset, so the trailing-pipe strip landed mid-pattern and dropped the closing quote — turning `… |✓|×|XCTAssert" | tail -80` into `… |✓|×-80` and making execution fail with `pi-natives:command: unterminated double quote`. Fixed in `pi_shell::fixup` (`@oh-my-pi/pi-natives`).
 - Fixed duplicate file entries in grouped outputs for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics when the same path appeared multiple times
 - Fixed search, grep, and edit output rendering so repeated directory group blank-line boundaries no longer break nested path/link reconstruction
 - Fixed `omp dry-balance --bench` flooding the terminal with staircased, duplicated spinner/status lines (and an indented summary) when the tty has ONLCR/OPOST disabled (raw mode). The interactive progress region separated rows with a bare LF and repositioned with a column-preserving `\x1b[<n>A` cursor-up, both of which only land at column 0 when the terminal translates LF→CRLF; with that translation off, every 80 ms redraw cascaded down and to the right into scrollback. The live region now carriage-returns before every cleared row, terminates each row with CRLF, and caps each row to the terminal width so a wrapped line cannot desync the cursor-up from the logical line count.
diff --git a/packages/natives/CHANGELOG.md b/packages/natives/CHANGELOG.md
index d41dacea2..1add39043 100644
--- a/packages/natives/CHANGELOG.md
+++ b/packages/natives/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed `applyBashFixups` corrupting commands that contain multi-byte UTF-8 before a trailing `| head`/`| tail` (or `2>&1`). `brush-parser` reports source positions as Unicode-scalar (char) offsets, but `pi_shell::fixup` sliced the command `&str` by those numbers as if they were byte offsets, so each multi-byte char (e.g. `✓`/`×` in a `grep -E` pattern) shifted the cut earlier and left a mangled command — e.g. `… |✓|×|XCTAssert" | tail -80` became `… |✓|×-80`, orphaning the closing quote and making the shell reject the whole pipeline with `unterminated double quote`. Positions are now translated to byte offsets before slicing.
+
 ## [15.9.0] - 2026-06-04
 
 ### Fixed

From cba664129938fb5fdb2627a793e153b4d97d4509 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 03:43:52 +0200
Subject: [PATCH 082/181] feat: enabled resolver-based API key retries with
 refresh and rotation

- Added `ApiKeyResolver`/`ApiKey` types and exported auth-retry helpers.
- Changed stream and gateway auth retry handling to use resolver steps.
- Added initial-key, force-refresh, and rotate credential retries for auth failures.
- Updated agent and coding-agent integrations to use context-aware API-key resolvers.
---
 packages/agent/CHANGELOG.md                   |  12 +
 packages/agent/src/agent-loop.ts              |  18 +-
 packages/agent/src/agent.ts                   |   5 +-
 packages/agent/src/types.ts                   |   3 +-
 packages/ai/CHANGELOG.md                      |  20 +-
 packages/ai/src/auth-gateway/server.ts        |  98 ++++--
 packages/ai/src/auth-retry.ts                 | 141 ++++++++
 packages/ai/src/auth-storage.ts               | 123 ++++++-
 packages/ai/src/index.ts                      |   1 +
 packages/ai/src/providers/gitlab-duo.ts       |   5 +-
 .../ai/src/providers/openai-anthropic-shim.ts |   7 +-
 packages/ai/src/providers/pi-native-client.ts |   5 +-
 packages/ai/src/stream.ts                     |  52 ++-
 packages/ai/src/types.ts                      |  17 +-
 packages/ai/test/auth-retry.test.ts           | 162 ++++++++++
 .../auth-storage-force-refresh-rotate.test.ts | 165 ++++++++++
 packages/ai/test/stream-auth-retry.test.ts    | 306 ++++++++++--------
 packages/coding-agent/CHANGELOG.md            |   4 +-
 .../src/auto-thinking/classifier.ts           |   6 +-
 .../coding-agent/src/cli/dry-balance-cli.ts   |  47 ++-
 .../src/commit/analysis/conventional.ts       |   4 +-
 .../src/commit/analysis/summary.ts            |   4 +-
 .../src/commit/changelog/generate.ts          |   4 +-
 .../src/commit/changelog/index.ts             |   4 +-
 .../src/commit/map-reduce/index.ts            |   6 +-
 .../src/commit/map-reduce/map-phase.ts        |   4 +-
 .../src/commit/map-reduce/reduce-phase.ts     |   4 +-
 .../src/commit/model-selection.ts             |  42 ++-
 packages/coding-agent/src/commit/pipeline.ts  |   8 +-
 .../src/config/api-key-resolver.ts            |  77 +++++
 .../coding-agent/src/config/model-registry.ts |  16 +-
 packages/coding-agent/src/eval/llm-bridge.ts  |  11 +-
 packages/coding-agent/src/memories/index.ts   |  17 +-
 packages/coding-agent/src/mnemopi/backend.ts  |   6 +-
 packages/coding-agent/src/sdk.ts              |  45 +--
 .../src/utils/commit-message-generator.ts     |  10 +-
 .../coding-agent/src/utils/title-generator.ts |   3 +-
 ...mmit-model-selection-role-thinking.test.ts |   2 +
 packages/tui/src/components/scroll-view.ts    |  63 +++-
 packages/tui/test/scroll-view.test.ts         |  26 +-
 40 files changed, 1259 insertions(+), 294 deletions(-)
 create mode 100644 packages/ai/src/auth-retry.ts
 create mode 100644 packages/ai/test/auth-retry.test.ts
 create mode 100644 packages/ai/test/auth-storage-force-refresh-rotate.test.ts
 create mode 100644 packages/coding-agent/src/config/api-key-resolver.ts

diff --git a/packages/agent/CHANGELOG.md b/packages/agent/CHANGELOG.md
index 324aac24b..4d4594e25 100644
--- a/packages/agent/CHANGELOG.md
+++ b/packages/agent/CHANGELOG.md
@@ -1,6 +1,18 @@
 # Changelog
 
 ## [Unreleased]
+### Added
+
+- Added optional `ApiKeyResolveContext` parameter to `getApiKey` in `AgentOptions` and `AgentLoopConfig` so key resolvers can receive retry context
+
+### Changed
+
+- Enabled streaming API calls to re-resolve credentials through the `getApiKey` callback when retries occur after authentication-related errors
+
+### Fixed
+
+- Fixed handling of short-lived API keys so that expired tokens are retried with a refreshed value during 401/usage-limit failures
+- Ensured fallback API key resolution uses the initially configured static `apiKey` when `getApiKey` is present
 
 ## [15.9.5] - 2026-06-05
 
diff --git a/packages/agent/src/agent-loop.ts b/packages/agent/src/agent-loop.ts
index 565420527..17ae599c2 100644
--- a/packages/agent/src/agent-loop.ts
+++ b/packages/agent/src/agent-loop.ts
@@ -3,6 +3,7 @@
  * Transforms to Message[] only at the LLM call boundary.
  */
 import {
+	type ApiKeyResolveContext,
 	type AssistantMessage,
 	type AssistantMessageEvent,
 	type Context,
@@ -727,8 +728,9 @@ async function streamAssistantResponse(
 	// Resolve API key (important for expiring tokens) — do this before resolving
 	// metadata so that the session-sticky credential recorded by getApiKey is
 	// visible to metadataResolver (e.g. for the correct account_uuid in metadata.user_id).
+	const staticApiKey = typeof config.apiKey === "string" ? config.apiKey : undefined;
 	const resolvedApiKey =
-		(config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;
+		(config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || staticApiKey;
 
 	// Re-resolve metadata after credential selection so the per-request value
 	// reflects the credential actually used, not the snapshot from AgentLoopConfig construction.
@@ -798,7 +800,19 @@ async function streamAssistantResponse(
 		return await runInActiveSpan(chatSpan, async () => {
 			const response = await streamFunction(config.model, llmContext, {
 				...config,
-				apiKey: resolvedApiKey,
+				// Hand streamSimple a resolver so its central auth-retry policy can
+				// re-resolve on 401 / usage-limit: the initial step reuses the key
+				// already resolved above (which set the session-sticky credential
+				// feeding metadataResolver), and retry steps forward the a/b/c ctx
+				// to config.getApiKey (force-refresh, then rotate). With no
+				// getApiKey hook the caller's own apiKey (string or resolver) flows
+				// through unchanged.
+				apiKey: config.getApiKey
+					? (ctx: ApiKeyResolveContext) =>
+							ctx.error === undefined
+								? resolvedApiKey
+								: Promise.resolve(config.getApiKey!(config.model.provider, ctx))
+					: config.apiKey,
 				metadata: resolvedMetadata,
 				toolChoice: effectiveToolChoice,
 				reasoning: effectiveReasoning,
diff --git a/packages/agent/src/agent.ts b/packages/agent/src/agent.ts
index 1b3c57f46..5def74e6e 100644
--- a/packages/agent/src/agent.ts
+++ b/packages/agent/src/agent.ts
@@ -3,6 +3,7 @@
  */
 import { isPromise } from "node:util/types";
 import {
+	type ApiKeyResolveContext,
 	type AssistantMessage,
 	type AssistantMessageEvent,
 	type CursorExecHandlers,
@@ -141,7 +142,7 @@ export interface AgentOptions {
 	 * Resolves an API key dynamically for each LLM call.
 	 * Useful for expiring tokens (e.g., GitHub Copilot OAuth).
 	 */
-	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+	getApiKey?: (provider: string, ctx?: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
 
 	/**
 	 * Inspect or replace provider payloads before they are sent.
@@ -319,7 +320,7 @@ export class Agent {
 	#cursorToolResultBuffer: CursorToolResultEntry[] = [];
 
 	streamFn: StreamFn;
-	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+	getApiKey?: (provider: string, ctx?: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
 	/**
 	 * Hook invoked after tool arguments are validated and before execution.
 	 * Reassign at any time to swap the implementation (e.g. on extension reload).
diff --git a/packages/agent/src/types.ts b/packages/agent/src/types.ts
index 7ca6a37ec..8ecc1458c 100644
--- a/packages/agent/src/types.ts
+++ b/packages/agent/src/types.ts
@@ -1,4 +1,5 @@
 import type {
+	ApiKeyResolveContext,
 	AssistantMessage,
 	AssistantMessageEvent,
 	AssistantMessageEventStream,
@@ -112,7 +113,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire
 	 * during long-running tool execution phases.
 	 */
-	getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+	getApiKey?: (provider: string, ctx?: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
 
 	/**
 	 * Returns steering messages to inject into the conversation mid-run.
diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 134e7d053..57b37854b 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -1,6 +1,24 @@
 # Changelog
 
 ## [Unreleased]
+### Breaking Changes
+
+- Removed the `onAuthError` option from stream request options and shifted auth retry handling to resolver-based `apiKey` behavior, requiring callers using custom auth-retry hooks to migrate
+
+### Added
+
+- Added `ApiKeyResolver` and `ApiKey` auth helpers, including `isApiKeyResolver`, `isAuthRetryableError`, `resolveApiKeyOnce`, and `withAuth`, and exported them from the package root
+- Added support for a function-valued `apiKey` in `SimpleStreamOptions` so a single stream request can refresh or rotate credentials during retry
+- Added `forceRefresh` credential option to `AuthStorage.getApiKey` and `rotateSessionCredential` support for session-level credential rotation after auth failures
+
+### Changed
+
+- Changed gateway and stream auth flows to share the a/b/c retry policy, refreshing the same session credential first and then switching to a sibling credential on repeated auth failures
+
+### Fixed
+
+- Fixed streaming auth retries to handle `401` and usage-limit errors before replay-unsafe content is emitted, including failures surfaced only via `errorStatus`
+- Fixed streaming retries to buffer and suppress partial `start` events from failed auth attempts so only clean retried events are delivered
 
 ## [15.10.0] - 2026-06-06
 
@@ -2981,4 +2999,4 @@ _Dedicated to Peter's shoulder ([@steipete](https://twitter.com/steipete))_
 
 ## [0.9.4] - 2025-11-26
 
-Initial release with multi-provider LLM support.
+Initial release with multi-provider LLM support.
\ No newline at end of file
diff --git a/packages/ai/src/auth-gateway/server.ts b/packages/ai/src/auth-gateway/server.ts
index f5b0d9383..83a3e4338 100644
--- a/packages/ai/src/auth-gateway/server.ts
+++ b/packages/ai/src/auth-gateway/server.ts
@@ -18,6 +18,7 @@
  *   POST /v1/responses                     → OpenAI Responses in/out
  */
 import { extractRetryHint, logger } from "@oh-my-pi/pi-utils";
+import type { ApiKeyResolver } from "../auth-retry";
 import type { AuthStorage } from "../auth-storage";
 import { Effort } from "../effort";
 import * as anthropicMessages from "../providers/anthropic-messages-server";
@@ -340,6 +341,60 @@ async function refreshGatewayApiKeyAfterAuthError(
 	return storage.getApiKey(provider, sessionId, { modelId: model.id, signal });
 }
 
+/**
+ * Build the {@link ApiKeyResolver} handed to `streamSimple` for a gateway
+ * request. Drives the central a/b/c auth-retry policy server-side:
+ *
+ * - initial resolve → the credential already resolved for this request.
+ * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential
+ *   (a peer/broker may have rotated its token out from under our cached copy).
+ * - step (c) `lastChance` → {@link refreshGatewayApiKeyAfterAuthError} switches
+ *   to a sibling (usage-limit block vs credential invalidation by error class).
+ *
+ * `lastKey` tracks the most recent bearer so the switch step invalidates the
+ * credential that actually failed.
+ */
+function buildGatewayApiKeyResolver(
+	storage: AuthStorage,
+	model: Model<Api>,
+	sessionId: string,
+	initialKey: string,
+	requestSignal: AbortSignal,
+	format: string,
+	peer: string,
+): ApiKeyResolver {
+	let lastKey = initialKey;
+	return async ({ lastChance, error, signal }) => {
+		const sig = signal ?? requestSignal;
+		if (error === undefined) {
+			lastKey = initialKey;
+			return initialKey;
+		}
+		if (!lastChance) {
+			const refreshed = await storage.getApiKey(model.provider, sessionId, {
+				modelId: model.id,
+				signal: sig,
+				forceRefresh: true,
+			});
+			lastKey = refreshed ?? lastKey;
+			return refreshed;
+		}
+		const next = await refreshGatewayApiKeyAfterAuthError(
+			storage,
+			model,
+			sessionId,
+			model.provider,
+			lastKey,
+			error,
+			sig,
+			format,
+			peer,
+		);
+		lastKey = next ?? lastKey;
+		return next;
+	};
+}
+
 function clientClosedResponse(route: { module: FormatModule }): Response {
 	return route.module.formatError(499, "request_aborted", "client closed request");
 }
@@ -447,19 +502,15 @@ async function handleFormatEndpoint(
 	}
 
 	const streamOpts = buildStreamOptions(parsed, model.api, controller.signal);
-	streamOpts.apiKey = apiKey;
-	streamOpts.onAuthError = (provider, oldKey, error) =>
-		refreshGatewayApiKeyAfterAuthError(
-			bootOpts.storage,
-			model,
-			sessionId,
-			provider,
-			oldKey,
-			error,
-			controller.signal,
-			route.label,
-			peer,
-		);
+	streamOpts.apiKey = buildGatewayApiKeyResolver(
+		bootOpts.storage,
+		model,
+		sessionId,
+		apiKey,
+		controller.signal,
+		route.label,
+		peer,
+	);
 
 	logger.info("auth-gateway request", {
 		format: route.label,
@@ -604,18 +655,15 @@ async function handlePiNative(bootOpts: AuthGatewayBootOptions, req: Request, pe
 	// only inject server-controlled fields. The codex temperature/topP strip
 	// matches `buildStreamOptions` — Codex rejects them with a 400.
 	const streamOpts: SimpleStreamOptions = { ...parsed.options, apiKey, signal: controller.signal };
-	streamOpts.onAuthError = (provider, oldKey, error) =>
-		refreshGatewayApiKeyAfterAuthError(
-			bootOpts.storage,
-			model,
-			sessionId,
-			provider,
-			oldKey,
-			error,
-			controller.signal,
-			"pi-native",
-			peer,
-		);
+	streamOpts.apiKey = buildGatewayApiKeyResolver(
+		bootOpts.storage,
+		model,
+		sessionId,
+		apiKey,
+		controller.signal,
+		"pi-native",
+		peer,
+	);
 	if (model.api === "openai-codex-responses") {
 		delete streamOpts.temperature;
 		delete streamOpts.topP;
diff --git a/packages/ai/src/auth-retry.ts b/packages/ai/src/auth-retry.ts
new file mode 100644
index 000000000..e53567f01
--- /dev/null
+++ b/packages/ai/src/auth-retry.ts
@@ -0,0 +1,141 @@
+import { extractHttpStatusFromError } from "@oh-my-pi/pi-utils";
+import { isUsageLimitError } from "./rate-limit-utils";
+
+/**
+ * Context passed to an {@link ApiKeyResolver} on each resolution attempt.
+ *
+ * The `error`/`lastChance` pair drives the central a/b/c retry policy shared by
+ * the streaming ({@link streamSimple}) and non-streaming ({@link withAuth})
+ * drivers:
+ * - `error === undefined` → **initial resolve** (no force-refresh; cheap, may
+ *   return a locally-cached not-yet-expired token).
+ * - `error !== undefined && !lastChance` → **step (b): refresh the SAME
+ *   account** (force a token re-mint / await an in-flight broker refresh).
+ * - `error !== undefined && lastChance` → **step (c): switch account**
+ *   (invalidate/usage-limit the current credential and rotate to a sibling).
+ *
+ * The resolver returns the bearer to send, or `undefined` to stop retrying and
+ * surface the last error to the caller.
+ */
+export interface ApiKeyResolveContext {
+	/** True on the final retry step — the resolver should rotate to a sibling credential. */
+	lastChance: boolean;
+	/** The auth error that triggered this re-resolution, or `undefined` on the initial resolve. */
+	error: unknown;
+	/** Caller cancel signal, threaded into any credential refresh / rotation work. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Resolves the API key to send for a request, retried through the a/b/c policy
+ * described on {@link ApiKeyResolveContext}.
+ */
+export type ApiKeyResolver = (ctx: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
+
+/** A static bearer string, or a {@link ApiKeyResolver} that mints/rotates one. */
+export type ApiKey = string | ApiKeyResolver;
+
+/** Narrows {@link ApiKey} to its resolver form. */
+export function isApiKeyResolver(key: ApiKey | undefined): key is ApiKeyResolver {
+	return typeof key === "function";
+}
+
+/**
+ * Performs the initial resolve of an {@link ApiKey} (`error: undefined`,
+ * `lastChance: false`). Static keys pass through unchanged.
+ */
+export async function resolveApiKeyOnce(key: ApiKey | undefined, signal?: AbortSignal): Promise<string | undefined> {
+	if (key === undefined) return undefined;
+	if (isApiKeyResolver(key)) return (await key({ lastChance: false, error: undefined, signal })) || undefined;
+	return key;
+}
+
+/**
+ * Classifies whether an error should trigger a credential refresh/rotation
+ * retry: a hard `401`, or a rotatable usage-limit ("usage_limit_reached",
+ * Codex's "you have hit your ChatGPT usage limit", etc.).
+ */
+export function isAuthRetryableError(error: unknown): boolean {
+	if (extractHttpStatusFromError(error) === 401) return true;
+	const message = error instanceof Error ? error.message : typeof error === "string" ? error : undefined;
+	if (!message) return false;
+	if (extractHttpStatusFromError({ message }) === 401) return true;
+	return isUsageLimitError(message);
+}
+
+/**
+ * The ordered `lastChance` values for the retry steps after the initial
+ * attempt fails: `false` → step (b) refresh-same, `true` → step (c) switch.
+ * Shared by {@link withAuth} and the streaming retry driver so both run the
+ * same policy.
+ */
+export const AUTH_RETRY_STEPS: readonly boolean[] = [false, true];
+
+/** Resolve a single retry step, swallowing resolver failures into `undefined`. */
+export async function resolveRetryKey(
+	resolver: ApiKeyResolver,
+	lastChance: boolean,
+	error: unknown,
+	signal?: AbortSignal,
+): Promise<string | undefined> {
+	try {
+		return (await resolver({ lastChance, error, signal })) || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Runs an auth-protected operation through the central a/b/c retry policy.
+ *
+ * - A static string key (or any non-resolver) → a single `attempt` with no
+ *   retry (identical to the legacy static-key path).
+ * - A resolver → initial `attempt`, then on a retryable auth error up to two
+ *   more attempts (refresh-same, then switch). A step is skipped when the
+ *   resolver returns the same key it just tried or `undefined`; non-auth errors
+ *   propagate immediately.
+ *
+ * Used by non-streaming consumers (image generation, web search, completion
+ * helpers). The streaming driver in `stream.ts` implements the same policy with
+ * its replay-safe buffering machinery.
+ */
+export async function withAuth<T>(
+	key: ApiKey | undefined,
+	attempt: (key: string) => Promise<T>,
+	opts?: { isAuthError?: (error: unknown) => boolean; signal?: AbortSignal; missingKeyMessage?: string },
+): Promise<T> {
+	const isAuthError = opts?.isAuthError ?? isAuthRetryableError;
+	const missingKey = (): Error => new Error(opts?.missingKeyMessage ?? "No API key available");
+
+	if (!isApiKeyResolver(key)) {
+		if (key === undefined) throw missingKey();
+		return attempt(key);
+	}
+
+	const resolver = key;
+	const signal = opts?.signal;
+	let lastKey = await resolveRetryKey(resolver, false, undefined, signal);
+	if (lastKey === undefined) throw missingKey();
+
+	let lastError: unknown;
+	try {
+		return await attempt(lastKey);
+	} catch (error) {
+		if (!isAuthError(error)) throw error;
+		lastError = error;
+	}
+
+	for (let i = 0; i < AUTH_RETRY_STEPS.length; i++) {
+		const nextKey = await resolveRetryKey(resolver, AUTH_RETRY_STEPS[i]!, lastError, signal);
+		if (nextKey === undefined || nextKey === lastKey) continue;
+		lastKey = nextKey;
+		try {
+			return await attempt(nextKey);
+		} catch (error) {
+			if (!isAuthError(error)) throw error;
+			lastError = error;
+		}
+	}
+
+	throw lastError;
+}
diff --git a/packages/ai/src/auth-storage.ts b/packages/ai/src/auth-storage.ts
index dab8e1045..e4c80bd39 100644
--- a/packages/ai/src/auth-storage.ts
+++ b/packages/ai/src/auth-storage.ts
@@ -11,6 +11,8 @@ import { Database, type Statement } from "bun:sqlite";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { getAgentDbPath, logger } from "@oh-my-pi/pi-utils";
+import type { ApiKeyResolver } from "./auth-retry";
+import { isUsageLimitError } from "./rate-limit-utils";
 import { getEnvApiKey } from "./stream";
 import type { Provider } from "./types";
 import type {
@@ -546,6 +548,13 @@ type AuthApiKeyOptions = {
 	 * stranding the caller for `timeoutMs * (maxRetries + 1)`.
 	 */
 	signal?: AbortSignal;
+	/**
+	 * Force a re-mint of the session-preferred OAuth credential's access token,
+	 * bypassing the not-yet-expired short-circuit. Powers step (b) of the
+	 * auth-retry policy ("refresh the SAME account") so a locally-cached token
+	 * that a peer/broker rotated out from under us is replaced before retrying.
+	 */
+	forceRefresh?: boolean;
 };
 type OAuthResolutionResult = { apiKey: string; credential: OAuthCredential };
 
@@ -581,6 +590,36 @@ export interface InvalidateCredentialMatchingOptions {
 	sessionId?: string;
 }
 
+/**
+ * Build an {@link ApiKeyResolver} backed directly by an {@link AuthStorage},
+ * implementing the central a/b/c auth-retry policy for consumers that hold an
+ * AuthStorage rather than a higher-level registry (e.g. web-search providers):
+ *
+ * - initial (`error: undefined`) → resolve the session credential.
+ * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential.
+ * - step (c) `lastChance` → rotate to a sibling credential, then re-resolve.
+ */
+export function createAuthStorageResolver(
+	storage: Pick<AuthStorage, "getApiKey" | "rotateSessionCredential">,
+	provider: string,
+	options?: { sessionId?: string; baseUrl?: string; modelId?: string },
+): ApiKeyResolver {
+	const { sessionId, baseUrl, modelId } = options ?? {};
+	return async ({ lastChance, error, signal }) => {
+		if (error === undefined) {
+			return storage.getApiKey(provider, sessionId, { baseUrl, modelId, signal });
+		}
+		if (lastChance) {
+			// Rotate to a sibling credential on an account constraint. No
+			// retry-after handling here — `markUsageLimitReached` owns the block
+			// duration and the outer retry layer owns the no-sibling wait.
+			await storage.rotateSessionCredential(provider, sessionId, { error, signal });
+			return storage.getApiKey(provider, sessionId, { baseUrl, modelId, signal });
+		}
+		return storage.getApiKey(provider, sessionId, { baseUrl, modelId, forceRefresh: true, signal });
+	};
+}
+
 function isAbortSignalOption(
 	value: InvalidateCredentialMatchingOptions | AbortSignal | undefined,
 ): value is AbortSignal {
@@ -3046,19 +3085,38 @@ export class AuthStorage {
 				candidates.unshift(preferred);
 			}
 		}
+		// Step (b) of the auth-retry policy: when `forceRefresh` is set, re-mint
+		// the session-preferred credential (or the first candidate when no
+		// session preference exists yet) even if its cached token still looks
+		// valid — a peer/broker may have rotated it out from under us.
+		const forceRefreshIndex = options?.forceRefresh
+			? (sessionPreferredIndex ?? candidates[0]?.selection.index)
+			: undefined;
 		await Promise.all(
 			candidates.map(async candidate => {
-				if (Date.now() + OAUTH_REFRESH_SKEW_MS < candidate.selection.credential.expires) return;
+				const force = forceRefreshIndex !== undefined && candidate.selection.index === forceRefreshIndex;
+				if (!force && Date.now() + OAUTH_REFRESH_SKEW_MS < candidate.selection.credential.expires) return;
 				const latestCredential = this.#getCredentialsForProvider(provider)[candidate.selection.index];
-				if (latestCredential?.type === "oauth" && Date.now() + OAUTH_REFRESH_SKEW_MS < latestCredential.expires) {
+				if (
+					!force &&
+					latestCredential?.type === "oauth" &&
+					Date.now() + OAUTH_REFRESH_SKEW_MS < latestCredential.expires
+				) {
 					candidate.selection.credential = latestCredential;
 					return;
 				}
 				try {
 					const credentialId = this.#getStoredCredentials(provider)[candidate.selection.index]?.id;
+					// Hand #refreshOAuthCredential a stale clone (expires:0) so its
+					// not-yet-expired short-circuit doesn't suppress the forced
+					// re-mint; an in-flight peer refresh is still awaited via the
+					// per-credential single-flight.
+					const refreshTarget = force
+						? { ...candidate.selection.credential, expires: 0 }
+						: candidate.selection.credential;
 					const refreshedCredentials = await this.#refreshOAuthCredential(
 						provider,
-						candidate.selection.credential,
+						refreshTarget,
 						credentialId,
 						options?.signal,
 					);
@@ -3670,6 +3728,65 @@ export class AuthStorage {
 		return true;
 	}
 
+	/**
+	 * Rotate away from the session's current credential after a retryable auth
+	 * error — step (c) of the auth-retry policy. Stateless: looks up the
+	 * session-sticky credential (no API-key matching needed), applies the
+	 * storage action for the error class, then clears the sticky so the next
+	 * {@link AuthStorage.getApiKey} for this session picks a sibling.
+	 *
+	 * - usage-limit / account-rate-limit error → {@link AuthStorage.markUsageLimitReached}
+	 *   (temporary block via its own backoff — default plus server usage-report
+	 *   reset; sticky left intact so the next resolve re-ranks around the block).
+	 * - otherwise (hard 401 / auth failure) → mark the credential suspect (or
+	 *   reload when no broker hook is wired) and block it, then drop the sticky.
+	 *
+	 * Returns whether another usable credential of the same type remains.
+	 */
+	async rotateSessionCredential(
+		provider: string,
+		sessionId: string | undefined,
+		options?: { error?: unknown; signal?: AbortSignal },
+	): Promise<boolean> {
+		const sessionCredential = this.#getSessionCredential(provider, sessionId);
+		if (!sessionCredential) return false;
+
+		const error = options?.error;
+		const message = error instanceof Error ? error.message : typeof error === "string" ? error : undefined;
+		if (message && isUsageLimitError(message)) {
+			return this.markUsageLimitReached(provider, sessionId, { signal: options?.signal });
+		}
+
+		const providerKey = this.#getProviderTypeKey(provider, sessionCredential.type);
+		// Snapshot sibling availability before mutating so a soft-deleting
+		// suspect hook can't reindex the answer out from under us.
+		const hasSibling = this.#getCredentialsForProvider(provider).some(
+			(credential, index) =>
+				credential.type === sessionCredential.type &&
+				index !== sessionCredential.index &&
+				!this.#isCredentialBlocked(providerKey, index),
+		);
+		const target = this.#getStoredCredentials(provider)[sessionCredential.index];
+		this.#clearSessionCredential(provider, sessionId);
+		this.#markCredentialBlocked(providerKey, sessionCredential.index, Date.now() + AuthStorage.#defaultBackoffMs);
+
+		if (target) {
+			const markSuspect = this.#store.markCredentialSuspect?.bind(this.#store);
+			if (markSuspect) {
+				await markSuspect(target.id, { signal: options?.signal });
+			} else {
+				await this.reload();
+			}
+			const latestRows = this.#store.listAuthCredentials(provider);
+			this.#setStoredCredentials(
+				provider,
+				latestRows.map(row => ({ id: row.id, credential: row.credential })),
+			);
+		}
+
+		return hasSibling;
+	}
+
 	// ─── Auth Broker integration ────────────────────────────────────────────
 
 	/**
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 3b1e855a3..a9d3c724a 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -3,6 +3,7 @@ export * from "./api-registry";
 export * from "./auth-broker";
 export { type AuthGatewayBootOptions, type ModelResolver, startAuthGateway } from "./auth-gateway/server";
 export * from "./auth-gateway/types";
+export * from "./auth-retry";
 export * from "./auth-storage";
 export * from "./effort";
 export * from "./model-cache";
diff --git a/packages/ai/src/providers/gitlab-duo.ts b/packages/ai/src/providers/gitlab-duo.ts
index 50c43b372..382ce56c9 100644
--- a/packages/ai/src/providers/gitlab-duo.ts
+++ b/packages/ai/src/providers/gitlab-duo.ts
@@ -234,7 +234,8 @@ export function streamGitLabDuo(
 
 	(async () => {
 		try {
-			if (!options?.apiKey) {
+			const apiKey = typeof options?.apiKey === "string" ? options.apiKey : undefined;
+			if (!apiKey || !options) {
 				throw new Error("Missing GitLab access token. Run /login gitlab-duo or set GITLAB_TOKEN.");
 			}
 
@@ -243,7 +244,7 @@ export function streamGitLabDuo(
 				throw new Error(`Unsupported GitLab Duo model: ${model.id}`);
 			}
 
-			const directAccess = await getDirectAccessToken(options.apiKey, options.fetch);
+			const directAccess = await getDirectAccessToken(apiKey, options.fetch);
 			const headers = {
 				...directAccess.headers,
 				...options.headers,
diff --git a/packages/ai/src/providers/openai-anthropic-shim.ts b/packages/ai/src/providers/openai-anthropic-shim.ts
index f2dad56d7..a4f9b8fac 100644
--- a/packages/ai/src/providers/openai-anthropic-shim.ts
+++ b/packages/ai/src/providers/openai-anthropic-shim.ts
@@ -44,6 +44,9 @@ export function streamOpenAIAnthropicShim(
 ): AssistantMessageEventStream {
 	const stream = new AssistantMessageEventStream();
 	const format = options?.format ?? config.defaultFormat;
+	// The resolver form of `apiKey` is resolved upstream in `streamSimple`;
+	// this shim only ever receives a static bearer string.
+	const apiKey = typeof options?.apiKey === "string" ? options.apiKey : undefined;
 
 	(async () => {
 		try {
@@ -74,7 +77,7 @@ export function streamOpenAIAnthropicShim(
 					: undefined;
 
 				const innerStream = streamAnthropic(anthropicModel, context, {
-					apiKey: options?.apiKey,
+					apiKey,
 					temperature: options?.temperature,
 					topP: options?.topP,
 					topK: options?.topK,
@@ -103,7 +106,7 @@ export function streamOpenAIAnthropicShim(
 
 				const reasoningEffort = options?.reasoning;
 				const innerStream = streamOpenAICompletions(openaiModel, context, {
-					apiKey: options?.apiKey,
+					apiKey,
 					temperature: options?.temperature,
 					topP: options?.topP,
 					topK: options?.topK,
diff --git a/packages/ai/src/providers/pi-native-client.ts b/packages/ai/src/providers/pi-native-client.ts
index b5df79636..68f479d2a 100644
--- a/packages/ai/src/providers/pi-native-client.ts
+++ b/packages/ai/src/providers/pi-native-client.ts
@@ -149,7 +149,10 @@ export function streamPiNative<TApi extends Api>(
 		try {
 			const url = resolveStreamUrl(model as Model<Api>);
 			const fetchImpl = options?.fetch ?? globalThis.fetch;
-			const headers = buildHeaders(model as Model<Api>, options?.apiKey);
+			const headers = buildHeaders(
+				model as Model<Api>,
+				typeof options?.apiKey === "string" ? options.apiKey : undefined,
+			);
 			const body = JSON.stringify({
 				modelId: model.id,
 				context,
diff --git a/packages/ai/src/stream.ts b/packages/ai/src/stream.ts
index a7d5fc739..f592dcd89 100644
--- a/packages/ai/src/stream.ts
+++ b/packages/ai/src/stream.ts
@@ -3,6 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { $env, $pickenv, extractHttpStatusFromError } from "@oh-my-pi/pi-utils";
 import { getCustomApi } from "./api-registry";
+import { AUTH_RETRY_STEPS, isApiKeyResolver, resolveRetryKey } from "./auth-retry";
 import type { Effort } from "./effort";
 import {
 	mapEffortToAnthropicAdaptiveEffort,
@@ -443,12 +444,15 @@ export function streamSimple<TApi extends Api>(
 	options?: SimpleStreamOptions,
 ): AssistantMessageEventStream {
 	const requestOptions = withRequestDebugFetch(options);
-	const retryApiKey = requestOptions?.onAuthError
-		? (requestOptions.apiKey ?? getEnvApiKey(model.provider))
-		: undefined;
-	if (retryApiKey) {
+	const apiKeyResolver = isApiKeyResolver(requestOptions?.apiKey) ? requestOptions.apiKey : undefined;
+	if (apiKeyResolver) {
 		const outer = new AssistantMessageEventStream();
-		const onAuthError = requestOptions!.onAuthError!;
+		const signal = requestOptions?.signal;
+		// One inner attempt against a resolved string key. When
+		// `captureAuthFailure` is set, a retryable auth error that arrives before
+		// any replay-unsafe event is buffered and returned (so the caller can
+		// retry with a fresh key) instead of surfaced. The terminal attempt
+		// clears the flag and emits whatever it gets.
 		const runAttempt = async (apiKey: string, captureAuthFailure: boolean): Promise<AuthRetryFailure | undefined> => {
 			const bufferedEvents: AssistantMessageEvent[] = [];
 			let emittedReplayUnsafeEvent = false;
@@ -458,7 +462,7 @@ export function streamSimple<TApi extends Api>(
 			};
 
 			try {
-				const inner = streamSimple(model, context, { ...requestOptions, apiKey, onAuthError: undefined });
+				const inner = streamSimple(model, context, { ...requestOptions, apiKey });
 				for await (const event of inner) {
 					if (!emittedReplayUnsafeEvent && event.type === "start") {
 						bufferedEvents.push(event);
@@ -510,19 +514,32 @@ export function streamSimple<TApi extends Api>(
 		};
 
 		void (async () => {
-			const failure = await runAttempt(retryApiKey, true);
-			if (!failure) return;
-			let nextKey: string | undefined;
+			let lastKey: string | undefined;
 			try {
-				nextKey = await onAuthError(model.provider, retryApiKey, failure.error);
+				lastKey = (await apiKeyResolver({ lastChance: false, error: undefined, signal })) || undefined;
 			} catch {
-				nextKey = undefined;
+				lastKey = undefined;
 			}
-			if (!nextKey || nextKey === retryApiKey) {
-				emitFailure(failure);
+			if (lastKey === undefined) {
+				outer.fail(new Error(`No API key for provider: ${model.provider}`));
 				return;
 			}
-			await runAttempt(nextKey, false);
+			let failure = await runAttempt(lastKey, true);
+			if (!failure) return;
+			// a/b/c policy: refresh the same account (lastChance=false), then
+			// switch to a sibling (lastChance=true). A step is skipped when the
+			// resolver yields the same key it just tried or `undefined`; the
+			// final step's attempt clears the capture flag so it emits directly.
+			for (let step = 0; step < AUTH_RETRY_STEPS.length; step++) {
+				const nextKey = await resolveRetryKey(apiKeyResolver, AUTH_RETRY_STEPS[step]!, failure.error, signal);
+				if (nextKey === undefined || nextKey === lastKey) continue;
+				lastKey = nextKey;
+				const isLastStep = step === AUTH_RETRY_STEPS.length - 1;
+				const next = await runAttempt(nextKey, !isLastStep);
+				if (!next) return;
+				failure = next;
+			}
+			emitFailure(failure);
 		})();
 		return outer;
 	}
@@ -553,7 +570,10 @@ export function streamSimple<TApi extends Api>(
 		return stream(model, context, providerOptions);
 	}
 
-	const apiKey = requestOptions?.apiKey || getEnvApiKey(model.provider);
+	// The resolver form is handled by the wrapper above; only a static string
+	// key reaches this point.
+	const apiKey =
+		(typeof requestOptions?.apiKey === "string" ? requestOptions.apiKey : undefined) || getEnvApiKey(model.provider);
 	if (!apiKey) {
 		throw new Error(`No API key for provider: ${model.provider}`);
 	}
@@ -724,7 +744,7 @@ function mapOptionsForApi<TApi extends Api>(
 		repetitionPenalty: options?.repetitionPenalty,
 		maxTokens: options?.maxTokens ?? model.maxTokens,
 		signal: options?.signal,
-		apiKey: apiKey || options?.apiKey,
+		apiKey: apiKey ?? (typeof options?.apiKey === "string" ? options.apiKey : undefined),
 		cacheRetention: options?.cacheRetention,
 		headers: options?.headers,
 		initiatorOverride: options?.initiatorOverride,
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 4cf00265f..566574be4 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -1,4 +1,5 @@
 import type { ZodType, z } from "zod/v4";
+import type { ApiKey } from "./auth-retry";
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
 import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses";
@@ -298,12 +299,6 @@ export interface StreamOptions {
 	maxTokens?: number;
 	signal?: AbortSignal;
 	apiKey?: string;
-	/**
-	 * Called when a provider returns 401 before any replay-unsafe assistant
-	 * event has been emitted. Returning a different key retries the provider
-	 * request once.
-	 */
-	onAuthError?: (provider: string, apiKey: string, error: unknown) => Promise<string | undefined>;
 	cacheRetention?: CacheRetention;
 	/**
 	 * Additional headers to include in provider requests.
@@ -415,7 +410,15 @@ export interface StreamOptions {
 }
 
 // Unified options with reasoning passed to streamSimple() and completeSimple()
-export interface SimpleStreamOptions extends StreamOptions {
+export interface SimpleStreamOptions extends Omit<StreamOptions, "apiKey"> {
+	/**
+	 * API key for the request: either a static bearer string, or an
+	 * {@link ApiKeyResolver} that mints/rotates the key across the central
+	 * a/b/c auth-retry policy. `streamSimple`/`completeSimple` resolve a
+	 * resolver to a string before per-provider dispatch, so providers only
+	 * ever see the resolved {@link StreamOptions.apiKey} string.
+	 */
+	apiKey?: ApiKey;
 	reasoning?: Effort;
 	/**
 	 * Force-disable reasoning for the request even when the model supports it.
diff --git a/packages/ai/test/auth-retry.test.ts b/packages/ai/test/auth-retry.test.ts
new file mode 100644
index 000000000..67609177f
--- /dev/null
+++ b/packages/ai/test/auth-retry.test.ts
@@ -0,0 +1,162 @@
+import { describe, expect, it } from "bun:test";
+import type { ApiKeyResolveContext } from "@oh-my-pi/pi-ai";
+import { isApiKeyResolver, isAuthRetryableError, resolveApiKeyOnce, withAuth } from "@oh-my-pi/pi-ai";
+
+function authError(status = 401): Error & { status: number } {
+	return Object.assign(new Error(`${status} authentication_error`), { status });
+}
+
+function usageLimitError(): Error & { status: number } {
+	return Object.assign(new Error("You have hit your ChatGPT usage limit (pro plan). Try again in ~158 min."), {
+		status: 429,
+	});
+}
+
+describe("isApiKeyResolver / resolveApiKeyOnce", () => {
+	it("narrows resolver vs static key and resolves the initial value", async () => {
+		expect(isApiKeyResolver("static")).toBe(false);
+		expect(isApiKeyResolver(undefined)).toBe(false);
+		expect(isApiKeyResolver(() => "k")).toBe(true);
+
+		expect(await resolveApiKeyOnce("static")).toBe("static");
+		expect(await resolveApiKeyOnce(undefined)).toBeUndefined();
+
+		let seen: ApiKeyResolveContext | undefined;
+		const resolved = await resolveApiKeyOnce(ctx => {
+			seen = ctx;
+			return "minted";
+		});
+		expect(resolved).toBe("minted");
+		// Initial resolve must look like an initial resolve, not a retry.
+		expect(seen).toEqual({ lastChance: false, error: undefined, signal: undefined });
+	});
+});
+
+describe("isAuthRetryableError", () => {
+	it("treats 401 and usage-limit phrasing as retryable, everything else as not", () => {
+		expect(isAuthRetryableError(authError(401))).toBe(true);
+		expect(isAuthRetryableError(usageLimitError())).toBe(true);
+		// A 429 whose body names the *account's* rate limit is rotatable (switch
+		// account), even though it isn't a 401 and isn't phrased "usage limit".
+		expect(
+			isAuthRetryableError(
+				Object.assign(
+					new Error(
+						'429 {"type":"error","error":{"type":"rate_limit_error","message":"This request would exceed your account\'s rate limit. Please try again later."}} retry-after-ms=9779000',
+					),
+					{ status: 429 },
+				),
+			),
+		).toBe(true);
+		// A generic (non-account) 429 rate limit is NOT rotatable — switching
+		// credentials won't help an org/global limit.
+		expect(isAuthRetryableError(Object.assign(new Error("429 too many requests"), { status: 429 }))).toBe(false);
+		expect(isAuthRetryableError("Error: 401 unauthorized")).toBe(true);
+		expect(isAuthRetryableError(authError(403))).toBe(false);
+		expect(isAuthRetryableError(authError(500))).toBe(false);
+		expect(isAuthRetryableError(new Error("network blip"))).toBe(false);
+		expect(isAuthRetryableError(undefined)).toBe(false);
+	});
+});
+
+describe("withAuth", () => {
+	it("runs a single attempt for a static string key (no retry)", async () => {
+		const keys: Array<string | undefined> = [];
+		const result = await withAuth("static-key", async key => {
+			keys.push(key);
+			return `ok:${key}`;
+		});
+		expect(result).toBe("ok:static-key");
+		expect(keys).toEqual(["static-key"]);
+	});
+
+	it("throws when a static key is missing", async () => {
+		await expect(
+			withAuth(undefined, async () => "never", { missingKeyMessage: "no key for foo" }),
+		).rejects.toThrow("no key for foo");
+	});
+
+	it("refreshes the same account, then switches, in order", async () => {
+		const keys: string[] = [];
+		const contexts: ApiKeyResolveContext[] = [];
+		const result = await withAuth(
+			ctx => {
+				contexts.push(ctx);
+				return ctx.error === undefined ? "k0" : ctx.lastChance ? "k2" : "k1";
+			},
+			async key => {
+				keys.push(key);
+				if (key === "k2") return "success";
+				throw authError();
+			},
+		);
+		expect(result).toBe("success");
+		expect(keys).toEqual(["k0", "k1", "k2"]);
+		expect(contexts.map(ctx => ({ lastChance: ctx.lastChance, hasError: ctx.error !== undefined }))).toEqual([
+			{ lastChance: false, hasError: false },
+			{ lastChance: false, hasError: true },
+			{ lastChance: true, hasError: true },
+		]);
+	});
+
+	it("stops retrying when the resolver returns undefined", async () => {
+		const keys: string[] = [];
+		const original = authError();
+		await expect(
+			withAuth(
+				ctx => (ctx.error === undefined ? "k0" : undefined),
+				async key => {
+					keys.push(key);
+					throw original;
+				},
+			),
+		).rejects.toBe(original);
+		expect(keys).toEqual(["k0"]);
+	});
+
+	it("does not re-attempt when the re-resolved key is unchanged", async () => {
+		const keys: string[] = [];
+		const original = authError();
+		// refresh-same returns the same key (skip), switch returns the same key (skip).
+		await expect(
+			withAuth(
+				() => "same",
+				async key => {
+					keys.push(key);
+					throw original;
+				},
+			),
+		).rejects.toBe(original);
+		expect(keys).toEqual(["same"]);
+	});
+
+	it("propagates non-auth errors without retrying", async () => {
+		const keys: string[] = [];
+		const boom = new Error("network blip");
+		await expect(
+			withAuth(
+				ctx => (ctx.error === undefined ? "k0" : "k1"),
+				async key => {
+					keys.push(key);
+					throw boom;
+				},
+			),
+		).rejects.toBe(boom);
+		expect(keys).toEqual(["k0"]);
+	});
+
+	it("honors a custom isAuthError classifier", async () => {
+		const keys: string[] = [];
+		const result = await withAuth(
+			ctx => (ctx.error === undefined ? "k0" : "k1"),
+			async key => {
+				keys.push(key);
+				if (key === "k0") throw new Error("CUSTOM_RETRY");
+				return "ok";
+			},
+			{ isAuthError: error => error instanceof Error && error.message === "CUSTOM_RETRY" },
+		);
+		expect(result).toBe("ok");
+		expect(keys).toEqual(["k0", "k1"]);
+	});
+});
diff --git a/packages/ai/test/auth-storage-force-refresh-rotate.test.ts b/packages/ai/test/auth-storage-force-refresh-rotate.test.ts
new file mode 100644
index 000000000..24bc9d33b
--- /dev/null
+++ b/packages/ai/test/auth-storage-force-refresh-rotate.test.ts
@@ -0,0 +1,165 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { type AuthCredentialStore, AuthStorage, SqliteAuthCredentialStore } from "../src/auth-storage";
+import { registerOAuthProvider, unregisterOAuthProviders } from "../src/utils/oauth";
+
+const PROVIDER = "unit-rotate-oauth";
+const SOURCE = "auth-storage-force-refresh-rotate-test";
+
+function farExpiry(): number {
+	return Date.now() + 60 * 60_000;
+}
+
+function authError(): Error & { status: number } {
+	return Object.assign(new Error("401 authentication_error"), { status: 401 });
+}
+
+function usageLimitError(): Error & { status: number } {
+	return Object.assign(new Error("You have hit your ChatGPT usage limit (pro plan). Try again in ~158 min."), {
+		status: 429,
+	});
+}
+
+describe("AuthStorage forceRefresh + rotateSessionCredential", () => {
+	let tempDir = "";
+	let store: AuthCredentialStore | undefined;
+	let authStorage: AuthStorage | undefined;
+
+	beforeEach(async () => {
+		tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "pi-ai-rotate-"));
+		store = await SqliteAuthCredentialStore.open(path.join(tempDir, "agent.db"));
+		authStorage = new AuthStorage(store);
+	});
+
+	afterEach(async () => {
+		vi.restoreAllMocks();
+		unregisterOAuthProviders(SOURCE);
+		store?.close();
+		store = undefined;
+		authStorage = undefined;
+		if (tempDir) {
+			await fs.rm(tempDir, { recursive: true, force: true });
+			tempDir = "";
+		}
+	});
+
+	function registerProvider(onRefresh?: () => void): void {
+		registerOAuthProvider({
+			id: PROVIDER,
+			name: "Rotate Unit",
+			sourceId: SOURCE,
+			async login() {
+				return { access: "login", refresh: "login", expires: farExpiry() };
+			},
+			async refreshToken(credentials) {
+				onRefresh?.();
+				return {
+					...credentials,
+					access: "minted-access",
+					refresh: "minted-refresh",
+					expires: farExpiry(),
+				};
+			},
+			getApiKey(credentials) {
+				return credentials.access;
+			},
+		});
+	}
+
+	test("forceRefresh re-mints a not-yet-expired token; a normal resolve uses the cached token", async () => {
+		if (!authStorage) throw new Error("test setup failed");
+		let refreshCalls = 0;
+		registerProvider(() => {
+			refreshCalls += 1;
+		});
+		await authStorage.set(PROVIDER, [
+			{ type: "oauth", access: "cached-access", refresh: "cached-refresh", expires: farExpiry() },
+		]);
+
+		const cached = await authStorage.getApiKey(PROVIDER, "s-control");
+		expect(cached).toBe("cached-access");
+		expect(refreshCalls).toBe(0);
+
+		const forced = await authStorage.getApiKey(PROVIDER, "s-force", { forceRefresh: true });
+		expect(forced).toBe("minted-access");
+		expect(refreshCalls).toBe(1);
+
+		// The re-minted credential is persisted, so the next plain resolve sees it.
+		const after = await authStorage.getApiKey(PROVIDER, "s-after");
+		expect(after).toBe("minted-access");
+	});
+
+	test("rotateSessionCredential(401) blocks + clears the sticky and rotates to a sibling", async () => {
+		if (!authStorage) throw new Error("test setup failed");
+		registerProvider();
+		await authStorage.set(PROVIDER, [
+			{ type: "oauth", access: "acc-A", refresh: "ref-A", expires: farExpiry() },
+			{ type: "oauth", access: "acc-B", refresh: "ref-B", expires: farExpiry() },
+		]);
+
+		const first = await authStorage.getApiKey(PROVIDER, "sess");
+		expect(["acc-A", "acc-B"]).toContain(first ?? "");
+
+		const usageLimitSpy = vi.spyOn(authStorage, "markUsageLimitReached");
+		const rotated = await authStorage.rotateSessionCredential(PROVIDER, "sess", { error: authError() });
+
+		expect(rotated).toBe(true);
+		// A hard 401 must NOT take the usage-limit code path.
+		expect(usageLimitSpy).not.toHaveBeenCalled();
+
+		const second = await authStorage.getApiKey(PROVIDER, "sess");
+		expect(["acc-A", "acc-B"]).toContain(second ?? "");
+		expect(second).not.toBe(first);
+	});
+
+	test("rotateSessionCredential(usage-limit) delegates to markUsageLimitReached", async () => {
+		if (!authStorage) throw new Error("test setup failed");
+		registerProvider();
+		await authStorage.set(PROVIDER, [
+			{ type: "oauth", access: "acc-A", refresh: "ref-A", expires: farExpiry() },
+			{ type: "oauth", access: "acc-B", refresh: "ref-B", expires: farExpiry() },
+		]);
+
+		const first = await authStorage.getApiKey(PROVIDER, "sess");
+		const usageLimitSpy = vi.spyOn(authStorage, "markUsageLimitReached");
+
+		const rotated = await authStorage.rotateSessionCredential(PROVIDER, "sess", {
+			error: usageLimitError(),
+		});
+
+		expect(rotated).toBe(true);
+		// Usage / account-rate-limit errors route to markUsageLimitReached, which
+		// owns the block duration (default + server usage-report reset) — the
+		// resolver never parses retry-after itself.
+		expect(usageLimitSpy).toHaveBeenCalledTimes(1);
+		expect(usageLimitSpy.mock.calls[0]?.[0]).toBe(PROVIDER);
+		expect(usageLimitSpy.mock.calls[0]?.[1]).toBe("sess");
+
+		const second = await authStorage.getApiKey(PROVIDER, "sess");
+		expect(second).not.toBe(first);
+	});
+
+	test("rotateSessionCredential reports no sibling for a single-credential setup", async () => {
+		if (!authStorage) throw new Error("test setup failed");
+		registerProvider();
+		await authStorage.set(PROVIDER, [
+			{ type: "oauth", access: "only-access", refresh: "only-refresh", expires: farExpiry() },
+		]);
+
+		await authStorage.getApiKey(PROVIDER, "sess");
+		expect(await authStorage.rotateSessionCredential(PROVIDER, "sess", { error: authError() })).toBe(false);
+	});
+
+	test("rotateSessionCredential returns false when the session has no sticky credential", async () => {
+		if (!authStorage) throw new Error("test setup failed");
+		registerProvider();
+		await authStorage.set(PROVIDER, [
+			{ type: "oauth", access: "acc-A", refresh: "ref-A", expires: farExpiry() },
+		]);
+
+		// Never resolved a key for this session → nothing to rotate away from.
+		expect(await authStorage.rotateSessionCredential(PROVIDER, "untouched", { error: authError() })).toBe(false);
+	});
+});
diff --git a/packages/ai/test/stream-auth-retry.test.ts b/packages/ai/test/stream-auth-retry.test.ts
index d019e57ce..3511ed7fc 100644
--- a/packages/ai/test/stream-auth-retry.test.ts
+++ b/packages/ai/test/stream-auth-retry.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it } from "bun:test";
 import { registerCustomApi, unregisterCustomApis } from "@oh-my-pi/pi-ai";
+import type { ApiKeyResolveContext } from "@oh-my-pi/pi-ai";
 import { streamSimple } from "@oh-my-pi/pi-ai/stream";
 import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions, Usage } from "@oh-my-pi/pi-ai/types";
 import { AssistantMessageEventStream } from "@oh-my-pi/pi-ai/utils/event-stream";
@@ -25,9 +26,9 @@ function assistant(content: string[] = []): AssistantMessage {
 		api: API,
 		provider: "test-provider",
 		model: "test-model",
-		usage: usage(),
+		timestamp: 1,
 		stopReason: "stop",
-		timestamp: Date.now(),
+		usage: usage(),
 	};
 }
 
@@ -39,19 +40,21 @@ function authError(): Error & { status: number } {
 	return Object.assign(new Error("401 authentication_error"), { status: 401 });
 }
 
+function usageLimitError(): Error & { status: number } {
+	return Object.assign(new Error("You have hit your ChatGPT usage limit (pro plan). Try again in ~158 min."), {
+		status: 429,
+	});
+}
+
 function model(): Model<Api> {
 	return {
 		id: "test-model",
-		name: "test-model",
+		name: "Test Model",
 		api: API,
 		provider: "test-provider",
-		baseUrl: "mock://",
-		reasoning: false,
-		input: ["text"],
-		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-		contextWindow: 1024,
-		maxTokens: 1024,
-	};
+		contextWindow: 1000,
+		maxTokens: 100,
+	} as Model<Api>;
 }
 
 const context: Context = {
@@ -59,61 +62,64 @@ const context: Context = {
 	messages: [{ role: "user", content: "hello", timestamp: 1 }],
 };
 
-describe("streamSimple auth retry", () => {
+/** Records the static key each inner attempt actually received. */
+function pushKey(keys: unknown[], options?: SimpleStreamOptions): void {
+	keys.push(options?.apiKey);
+}
+
+function ok(stream: AssistantMessageEventStream): void {
+	const message = assistant(["ok"]);
+	stream.push({ type: "start", partial: message });
+	stream.push({ type: "done", reason: "stop", message });
+}
+
+describe("streamSimple resolver auth retry", () => {
 	afterEach(() => {
 		unregisterCustomApis(SOURCE_ID);
 	});
 
-	it("retries once with a fresh key when 401 happens before the first event", async () => {
-		const keys: Array<string | undefined> = [];
-		let authCalls = 0;
+	it("retries with a refreshed key when a 401 is thrown before the first event", async () => {
+		const keys: unknown[] = [];
+		const contexts: ApiKeyResolveContext[] = [];
 		registerCustomApi(
 			API,
 			(_model: Model<Api>, _context: Context, options?: SimpleStreamOptions) => {
-				keys.push(options?.apiKey);
+				pushKey(keys, options);
 				const stream = new AssistantMessageEventStream();
-				queueMicrotask(() => {
-					if (keys.length === 1) {
-						stream.fail(authError());
-						return;
-					}
-					const message = assistant(["ok"]);
-					stream.push({ type: "start", partial: message });
-					stream.push({ type: "done", reason: "stop", message });
-				});
+				queueMicrotask(() => (keys.length === 1 ? stream.fail(authError()) : ok(stream)));
 				return stream;
 			},
 			SOURCE_ID,
 		);
 
 		const stream = streamSimple(model(), context, {
-			apiKey: "old-key",
-			onAuthError: async (provider, oldKey, error) => {
-				authCalls += 1;
-				expect(provider).toBe("test-provider");
-				expect(oldKey).toBe("old-key");
-				expect((error as { status?: number }).status).toBe(401);
-				return "new-key";
+			apiKey: async ctx => {
+				contexts.push(ctx);
+				return ctx.error === undefined ? "old-key" : ctx.lastChance ? "switch-key" : "refresh-key";
 			},
 		});
-
 		for await (const _event of stream) {
 			// drain
 		}
 
 		expect((await stream.result()).content).toEqual([{ type: "text", text: "ok" }]);
-		expect(keys).toEqual(["old-key", "new-key"]);
-		expect(authCalls).toBe(1);
+		// Initial resolve, then step (b) refresh-same — the switch step is never reached.
+		expect(keys).toEqual(["old-key", "refresh-key"]);
+		expect(keys.every(key => typeof key === "string")).toBe(true);
+		expect(contexts.map(ctx => ({ lastChance: ctx.lastChance, hasError: ctx.error !== undefined }))).toEqual([
+			{ lastChance: false, hasError: false },
+			{ lastChance: false, hasError: true },
+		]);
+		expect((contexts[1]?.error as { status?: number }).status).toBe(401);
 	});
 
-	it("retries when a provider emits start then a 401 error event before content", async () => {
-		const keys: Array<string | undefined> = [];
+	it("buffers the start event and retries on a 401 error event before content", async () => {
+		const keys: unknown[] = [];
 		const eventTypes: string[] = [];
-		let authCalls = 0;
 		registerCustomApi(
 			API,
 			(_model: Model<Api>, _context: Context, options?: SimpleStreamOptions) => {
-				keys.push(options?.apiKey);
+				pushKey(keys, options);
 				const stream = new AssistantMessageEventStream();
 				queueMicrotask(() => {
 					if (keys.length === 1) {
@@ -127,9 +133,7 @@ describe("streamSimple auth retry", () => {
 						});
 						return;
 					}
-					const message = assistant(["ok"]);
-					stream.push({ type: "start", partial: message });
-					stream.push({ type: "done", reason: "stop", message });
+					ok(stream);
 				});
 				return stream;
 			},
@@ -137,28 +141,59 @@ describe("streamSimple auth retry", () => {
 		);
 
 		const stream = streamSimple(model(), context, {
-			apiKey: "old-key",
-			onAuthError: async (provider, oldKey, error) => {
-				authCalls += 1;
-				expect(provider).toBe("test-provider");
-				expect(oldKey).toBe("old-key");
-				expect((error as { status?: number }).status).toBe(401);
-				return "new-key";
-			},
+			apiKey: async ctx => (ctx.error === undefined ? "old-key" : "new-key"),
 		});
-
 		for await (const event of stream) {
 			eventTypes.push(event.type);
 		}
 
 		expect((await stream.result()).content).toEqual([{ type: "text", text: "ok" }]);
 		expect(keys).toEqual(["old-key", "new-key"]);
+		// The buffered `start` of the failed attempt must not leak — the user
+		// sees exactly one clean start/done pair.
 		expect(eventTypes).toEqual(["start", "done"]);
-		expect(authCalls).toBe(1);
+	});
+
+	it("retries on a 401 carried only via errorStatus", async () => {
+		const keys: unknown[] = [];
+		registerCustomApi(
+			API,
+			(_model: Model<Api>, _context: Context, options?: SimpleStreamOptions) => {
+				pushKey(keys, options);
+				const stream = new AssistantMessageEventStream();
+				queueMicrotask(() => {
+					if (keys.length === 1) {
+						stream.push({ type: "start", partial: assistant() });
+						stream.push({
+							type: "error",
+							reason: "error",
+							error: assistantError(
+								'{"type":"error","error":{"type":"authentication_error","message":"Invalid authentication credentials"}}',
+								401,
+							),
+						});
+						return;
+					}
+					ok(stream);
+				});
+				return stream;
+			},
+			SOURCE_ID,
+		);
+
+		const stream = streamSimple(model(), context, {
+			apiKey: async ctx => (ctx.error === undefined ? "old-key" : "new-key"),
+		});
+		for await (const _event of stream) {
+			// drain
+		}
+
+		expect((await stream.result()).content).toEqual([{ type: "text", text: "ok" }]);
+		expect(keys).toEqual(["old-key", "new-key"]);
 	});
 
 	it("does not retry after replay-unsafe content has been emitted", async () => {
-		let authCalls = 0;
+		let retryResolves = 0;
 		const failure = authError();
 		registerCustomApi(
 			API,
@@ -175,10 +210,9 @@ describe("streamSimple auth retry", () => {
 		);
 
 		const stream = streamSimple(model(), context, {
-			apiKey: "old-key",
-			onAuthError: async () => {
-				authCalls += 1;
-				return "new-key";
+			apiKey: async ctx => {
+				if (ctx.error !== undefined) retryResolves += 1;
+				return ctx.error === undefined ? "old-key" : "new-key";
 			},
 		});
 
@@ -192,94 +226,79 @@ describe("streamSimple auth retry", () => {
 		}
 
 		expect(caught).toBe(failure);
-		expect(authCalls).toBe(0);
+		// The resolver is never asked for a retry key once a replay-unsafe event shipped.
+		expect(retryResolves).toBe(0);
 	});
 
-	it("retries on 401 carried via errorStatus when the message has no parseable status", async () => {
-		const keys: Array<string | undefined> = [];
-		let authCalls = 0;
+	it("escalates refresh-same then switch in order (2-retry ordering)", async () => {
+		const keys: unknown[] = [];
 		registerCustomApi(
 			API,
 			(_model: Model<Api>, _context: Context, options?: SimpleStreamOptions) => {
-				keys.push(options?.apiKey);
+				pushKey(keys, options);
 				const stream = new AssistantMessageEventStream();
-				queueMicrotask(() => {
-					if (keys.length === 1) {
-						stream.push({ type: "start", partial: assistant() });
-						stream.push({
-							type: "error",
-							reason: "error",
-							// Realistic Anthropic SDK shape: message begins with `<status> <body>`
-							// and the regex fallback in extractHttpStatusFromError cannot find 401
-							// inside the JSON body. Only `errorStatus` carries the signal.
-							error: assistantError(
-								'{"type":"error","error":{"type":"authentication_error","message":"Invalid authentication credentials"}}',
-								401,
-							),
-						});
-						return;
-					}
-					const message = assistant(["ok"]);
-					stream.push({ type: "start", partial: message });
-					stream.push({ type: "done", reason: "stop", message });
-				});
+				queueMicrotask(() => (options?.apiKey === "switch-key" ? ok(stream) : stream.fail(authError())));
 				return stream;
 			},
 			SOURCE_ID,
 		);
 
 		const stream = streamSimple(model(), context, {
-			apiKey: "old-key",
-			onAuthError: async () => {
-				authCalls += 1;
-				return "new-key";
-			},
+			apiKey: async ctx => (ctx.error === undefined ? "old-key" : ctx.lastChance ? "switch-key" : "refresh-key"),
 		});
-
 		for await (const _event of stream) {
 			// drain
 		}
 
 		expect((await stream.result()).content).toEqual([{ type: "text", text: "ok" }]);
-		expect(keys).toEqual(["old-key", "new-key"]);
-		expect(authCalls).toBe(1);
+		expect(keys).toEqual(["old-key", "refresh-key", "switch-key"]);
 	});
 
-	it("retries on a thrown usage_limit_reached error before any event has been emitted", async () => {
-		const keys: Array<string | undefined> = [];
-		const errors: unknown[] = [];
+	it("skips the refresh-same step when the resolver returns an unchanged key", async () => {
+		const keys: unknown[] = [];
 		registerCustomApi(
 			API,
 			(_model: Model<Api>, _context: Context, options?: SimpleStreamOptions) => {
-				keys.push(options?.apiKey);
+				pushKey(keys, options);
 				const stream = new AssistantMessageEventStream();
-				queueMicrotask(() => {
-					if (keys.length === 1) {
-						stream.fail(
-							Object.assign(
-								new Error("You have hit your ChatGPT usage limit (pro plan). Try again in ~158 min."),
-								{ status: 429 },
-							),
-						);
-						return;
-					}
-					const message = assistant(["ok"]);
-					stream.push({ type: "start", partial: message });
-					stream.push({ type: "done", reason: "stop", message });
-				});
+				queueMicrotask(() => (options?.apiKey === "switch-key" ? ok(stream) : stream.fail(authError())));
 				return stream;
 			},
 			SOURCE_ID,
 		);
 
 		const stream = streamSimple(model(), context, {
-			apiKey: "old-key",
-			onAuthError: async (_provider, _oldKey, error) => {
-				errors.push(error);
-				return "new-key";
+			// refresh-same yields the same failing key → that attempt is skipped.
+			apiKey: async ctx => (ctx.error === undefined ? "old-key" : ctx.lastChance ? "switch-key" : "old-key"),
+		});
+		for await (const _event of stream) {
+			// drain
+		}
+
+		expect((await stream.result()).content).toEqual([{ type: "text", text: "ok" }]);
+		expect(keys).toEqual(["old-key", "switch-key"]);
+	});
+
+	it("retries a thrown usage-limit error and passes the cause to the resolver", async () => {
+		const keys: unknown[] = [];
+		const errors: unknown[] = [];
+		registerCustomApi(
+			API,
+			(_model: Model<Api>, _context: Context, options?: SimpleStreamOptions) => {
+				pushKey(keys, options);
+				const stream = new AssistantMessageEventStream();
+				queueMicrotask(() => (keys.length === 1 ? stream.fail(usageLimitError()) : ok(stream)));
+				return stream;
+			},
+			SOURCE_ID,
+		);
+
+		const stream = streamSimple(model(), context, {
+			apiKey: async ctx => {
+				if (ctx.error !== undefined) errors.push(ctx.error);
+				return ctx.error === undefined ? "old-key" : "new-key";
 			},
 		});
-
 		for await (const _event of stream) {
 			// drain
 		}
@@ -287,18 +306,17 @@ describe("streamSimple auth retry", () => {
 		expect((await stream.result()).content).toEqual([{ type: "text", text: "ok" }]);
 		expect(keys).toEqual(["old-key", "new-key"]);
 		expect(errors).toHaveLength(1);
-		// The error surfaced to onAuthError carries the original 429 status so
-		// the gateway's refresh hook can branch on it.
+		// The cause carries the original 429 so the resolver can branch usage-limit vs 401.
 		expect((errors[0] as { status?: number }).status).toBe(429);
 		expect((errors[0] as Error).message).toMatch(/usage limit/i);
 	});
 
-	it("retries when a provider emits a usage_limit_reached error event before content", async () => {
-		const keys: Array<string | undefined> = [];
+	it("retries a usage-limit error event before content", async () => {
+		const keys: unknown[] = [];
 		registerCustomApi(
 			API,
 			(_model: Model<Api>, _context: Context, options?: SimpleStreamOptions) => {
-				keys.push(options?.apiKey);
+				pushKey(keys, options);
 				const stream = new AssistantMessageEventStream();
 				queueMicrotask(() => {
 					if (keys.length === 1) {
@@ -306,16 +324,11 @@ describe("streamSimple auth retry", () => {
 						stream.push({
 							type: "error",
 							reason: "error",
-							// errorStatus deliberately omitted: matches how the codex
-							// provider serializes the message-only path that used to
-							// 502 in the gateway.
 							error: assistantError("You have hit your ChatGPT usage limit (pro plan). Try again in ~158 min."),
 						});
 						return;
 					}
-					const message = assistant(["ok"]);
-					stream.push({ type: "start", partial: message });
-					stream.push({ type: "done", reason: "stop", message });
+					ok(stream);
 				});
 				return stream;
 			},
@@ -323,10 +336,8 @@ describe("streamSimple auth retry", () => {
 		);
 
 		const stream = streamSimple(model(), context, {
-			apiKey: "old-key",
-			onAuthError: async () => "new-key",
+			apiKey: async ctx => (ctx.error === undefined ? "old-key" : "new-key"),
 		});
-
 		for await (const _event of stream) {
 			// drain
 		}
@@ -335,13 +346,13 @@ describe("streamSimple auth retry", () => {
 		expect(keys).toEqual(["old-key", "new-key"]);
 	});
 
-	it("surfaces the original usage_limit error when the retry callback declines", async () => {
-		const keys: Array<string | undefined> = [];
-		const original = Object.assign(new Error("You have hit your ChatGPT usage limit (pro plan)."), { status: 429 });
+	it("surfaces the original error when the resolver declines every retry", async () => {
+		const keys: unknown[] = [];
+		const original = usageLimitError();
 		registerCustomApi(
 			API,
 			(_model: Model<Api>, _context: Context, options?: SimpleStreamOptions) => {
-				keys.push(options?.apiKey);
+				pushKey(keys, options);
 				const stream = new AssistantMessageEventStream();
 				queueMicrotask(() => stream.fail(original));
 				return stream;
@@ -349,12 +360,9 @@ describe("streamSimple auth retry", () => {
 			SOURCE_ID,
 		);
 
-		// Callback returns undefined → no sibling credential to rotate to.
-		// The original failure must reach the caller untouched so the client
-		// can decide what to do (back off, surface to user, …).
 		const stream = streamSimple(model(), context, {
-			apiKey: "old-key",
-			onAuthError: async () => undefined,
+			// Decline all retries: no sibling credential to rotate to.
+			apiKey: async ctx => (ctx.error === undefined ? "old-key" : undefined),
 		});
 
 		let caught: unknown;
@@ -367,8 +375,32 @@ describe("streamSimple auth retry", () => {
 		}
 
 		expect(caught).toBe(original);
-		// Single attempt — the inner stream is only re-invoked when a new key
-		// is provided.
 		expect(keys).toEqual(["old-key"]);
 	});
+
+	it("fails the stream when the initial resolve yields no key", async () => {
+		let attempts = 0;
+		registerCustomApi(
+			API,
+			() => {
+				attempts += 1;
+				return new AssistantMessageEventStream();
+			},
+			SOURCE_ID,
+		);
+
+		const stream = streamSimple(model(), context, { apiKey: async () => undefined });
+
+		let caught: unknown;
+		try {
+			for await (const _event of stream) {
+				// drain
+			}
+		} catch (error) {
+			caught = error;
+		}
+
+		expect((caught as Error).message).toMatch(/No API key for provider/);
+		expect(attempts).toBe(0);
+	});
 });
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 3986c9d2c..bfd13ffe7 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,14 +1,15 @@
 # Changelog
 
 ## [Unreleased]
+
 ### Added
 
 - Added `/fresh` to rotate the provider-facing session id and clear in-memory provider stream/cache state without changing the local session file.
-
 - Added a `ChatBlock` transcript primitive (`modes/components/chat-block.ts`) and a single `ctx.present(...)` sink (with `ctx.resetTranscript()`) so chat output is mounted in one place instead of the repeated `chatContainer.addChild(...)` + `ui.requestRender()` pattern scattered across controllers. `ChatBlock` carries a React/Svelte-style lifecycle — `onMount` starts effects, `onCleanup` registers teardown, `finish()` self-completes (stops timers and freezes the block at its final content), and `dispose()`/`resetTranscript()` tears everything down — so animated blocks own their own resources instead of leaking `setInterval`/`requestRender` bookkeeping into callers. The MCP "Connecting…" spinner is now such a block.
 
 ### Changed
 
+- Changed non-agent API operations (title and commit-message generation) to use session-aware API key resolution with refresh-first auth retries, refreshing the active credential before rotating to another account
 - Changed the directory grouping for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics from a single flat `# dir/` heading per immediate directory to a multi-level tree that folds the common path prefix into one heading. Previously every group repeated the full directory path — so results rooted outside cwd printed the absolute prefix (e.g. `/Users/me/proj/`) on every heading and nested directories were never collapsed. Now a single-child directory chain folds into one heading (`# packages/pkg/src/`, including an absolute root for out-of-cwd results), subdirectories nest one `#` deeper (`## nested/` → `### child.ts`), and each directory's own files are listed before its subdirectories. TUI hyperlink reconstruction tracks the nested directory stack across the whole output so file and code-frame links keep resolving to the correct absolute paths.
 - Changed the plan-mode approval surface from an inline transcript block plus a separate bottom selector into a single fullscreen overlay (like `/copy`). The overlay owns its entire content via `ScrollView`: the plan renders once as Markdown and scrolls inside the outlined box (PageUp/PageDown, g/G), with the approval options and the model-tier slider beneath it. ↑/↓ move the option cursor, ←/→ drive the slider, Enter confirms, the external-editor key opens the plan, and Esc cancels — so a tall plan no longer competes with the selector for vertical space or clips its head on ED3-risk terminals.
 - Changed the interactive controllers (command, MCP, selector, extension-UI, event), debug panels, and the status/error/warning helpers to render chat output through `ctx.present(...)` instead of appending to `chatContainer` and calling `ui.requestRender()` directly; transcript rebuilds dispose live blocks via `ctx.resetTranscript()` so animated blocks' timers stop on reset.
@@ -17,6 +18,7 @@
 
 - Fixed `omp dry-balance --bench` to recover from 401 token failures by re-minting the failing OAuth credential in place before switching accounts
 - Fixed the bash tool corrupting commands that embed multi-byte UTF-8 (e.g. `✓`/`×` inside a `grep -E` pattern) ahead of a trailing `| head`/`| tail`. The `bash.stripTrailingHeadTail` rewrite cut at char-offset positions reported by `brush-parser` while slicing the command by byte offset, so the trailing-pipe strip landed mid-pattern and dropped the closing quote — turning `… |✓|×|XCTAssert" | tail -80` into `… |✓|×-80` and making execution fail with `pi-natives:command: unterminated double quote`. Fixed in `pi_shell::fixup` (`@oh-my-pi/pi-natives`).
+- Fixed `omp dry-balance --bench` to recover from 401 token failures by re-minting the failing OAuth credential in place before switching accounts
 - Fixed duplicate file entries in grouped outputs for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics when the same path appeared multiple times
 - Fixed search, grep, and edit output rendering so repeated directory group blank-line boundaries no longer break nested path/link reconstruction
 - Fixed `omp dry-balance --bench` flooding the terminal with staircased, duplicated spinner/status lines (and an indented summary) when the tty has ONLCR/OPOST disabled (raw mode). The interactive progress region separated rows with a bare LF and repositioned with a column-preserving `\x1b[<n>A` cursor-up, both of which only land at column 0 when the terminal translates LF→CRLF; with that translation off, every 80 ms redraw cascaded down and to the right into scrollback. The live region now carriage-returns before every cleared row, terminates each row with CRLF, and caps each row to the terminal width so a wrapped line cannot desync the cursor-up from the logical line count.
diff --git a/packages/coding-agent/src/auto-thinking/classifier.ts b/packages/coding-agent/src/auto-thinking/classifier.ts
index db2048b18..fc029123a 100644
--- a/packages/coding-agent/src/auto-thinking/classifier.ts
+++ b/packages/coding-agent/src/auto-thinking/classifier.ts
@@ -15,6 +15,7 @@
  */
 import { type AssistantMessage, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
+import { reuseInitialApiKey } from "../config/api-key-resolver";
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -82,7 +83,10 @@ async function classifyOnline(input: string, deps: ClassifyDifficultyDeps): Prom
 			messages: [{ role: "user", content: input, timestamp: Date.now() }],
 		},
 		{
-			apiKey,
+			apiKey: reuseInitialApiKey(apiKey, deps.registry, model.provider, {
+				sessionId: deps.sessionId,
+				baseUrl: model.baseUrl,
+			}),
 			maxTokens,
 			disableReasoning: true,
 			metadata,
diff --git a/packages/coding-agent/src/cli/dry-balance-cli.ts b/packages/coding-agent/src/cli/dry-balance-cli.ts
index b667b0454..85e9388c5 100644
--- a/packages/coding-agent/src/cli/dry-balance-cli.ts
+++ b/packages/coding-agent/src/cli/dry-balance-cli.ts
@@ -1,8 +1,10 @@
 import type {
 	Api,
+	ApiKeyResolver,
 	AssistantMessage,
 	AssistantMessageEvent,
 	AssistantMessageEventStream,
+	AuthCredentialSnapshotEntry,
 	Context,
 	Model,
 	OAuthAccess,
@@ -59,6 +61,12 @@ export interface DryBalanceAuthStorage {
 		options?: DryBalanceAuthOptions,
 	): Promise<OAuthAccess | undefined>;
 	getOAuthAccesses?(provider: string, options?: DryBalanceAuthOptions): Promise<OAuthAccessResolution[]>;
+	/**
+	 * Force-refresh a single credential by id (step (b) of the auth-retry
+	 * policy). The bench re-mints the failing account's token in place on a
+	 * 401 rather than rotating accounts — it is measuring each account.
+	 */
+	forceRefreshCredentialById?(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
 }
 
 export interface DryBalanceModelRegistry {
@@ -183,6 +191,7 @@ type DryBalanceBenchTarget =
 			ok: true;
 			account: string;
 			accessToken: string;
+			credentialId?: number;
 	  }
 	| {
 			ok: false;
@@ -381,13 +390,23 @@ export function createBenchProgressSink(
 async function runBenchRequest(
 	model: Model<Api>,
 	sessionId: string,
-	account: string,
-	accessToken: string,
+	target: Extract<DryBalanceBenchTarget, { ok: true }>,
+	authStorage: DryBalanceAuthStorage,
 	streamFn: DryBalanceStreamSimple,
 	now: () => number,
 ): Promise<DryBalanceBenchResult> {
+	const { account, accessToken, credentialId } = target;
 	const startedAt = now();
 	let firstTokenAt: number | undefined;
+	// Re-mint the cached token on a 401: a peer/broker may have rotated it out
+	// from under our snapshot (Anthropic rotates refresh tokens on every use).
+	// The bench measures one account, so the switch step intentionally declines.
+	const apiKey: ApiKeyResolver = async ({ lastChance, error }) => {
+		if (error === undefined) return accessToken;
+		if (lastChance || credentialId === undefined || !authStorage.forceRefreshCredentialById) return undefined;
+		const refreshed = await authStorage.forceRefreshCredentialById(credentialId);
+		return refreshed.credential.type === "oauth" ? refreshed.credential.access : undefined;
+	};
 	try {
 		const context: Context = {
 			messages: [
@@ -400,7 +419,7 @@ async function runBenchRequest(
 			],
 		};
 		const stream = streamFn(model, context, {
-			apiKey: accessToken,
+			apiKey,
 			sessionId,
 			maxTokens: resolveBenchMaxTokens(model),
 			temperature: 0.2,
@@ -465,7 +484,7 @@ async function resolveBenchTargets(
 		seen.add(key);
 		const account = extractAccount(entry);
 		if (entry.ok) {
-			targets.push({ ok: true, account, accessToken: entry.accessToken });
+			targets.push({ ok: true, account, accessToken: entry.accessToken, credentialId: entry.credentialId });
 		} else {
 			targets.push({ ok: false, account, error: entry.error });
 		}
@@ -476,6 +495,7 @@ async function resolveBenchTargets(
 async function runBenchTargets(
 	model: Model<Api>,
 	targets: DryBalanceBenchTarget[],
+	authStorage: DryBalanceAuthStorage,
 	randomSessionId: () => string,
 	progress: DryBalanceBenchProgressSink | undefined,
 	streamFn: DryBalanceStreamSimple,
@@ -493,14 +513,7 @@ async function runBenchTargets(
 				return result;
 			}
 			progress?.markRunning(index, target.account);
-			const result = await runBenchRequest(
-				model,
-				randomSessionId(),
-				target.account,
-				target.accessToken,
-				streamFn,
-				now,
-			);
+			const result = await runBenchRequest(model, randomSessionId(), target, authStorage, streamFn, now);
 			progress?.complete(index, result);
 			return result;
 		}),
@@ -807,7 +820,15 @@ export async function runDryBalanceCommand(
 				? (deps.stderrColumns ?? process.stderr.columns ?? 80)
 				: (deps.stdoutColumns ?? process.stdout.columns ?? 80);
 			progress = createBenchProgressSink(targets.length, progressWrite, progressInteractive, progressColumns);
-			benchResults = await runBenchTargets(model, targets, randomSessionId, progress, streamFn, now);
+			benchResults = await runBenchTargets(
+				model,
+				targets,
+				runtime.modelRegistry.authStorage,
+				randomSessionId,
+				progress,
+				streamFn,
+				now,
+			);
 			results = targets.map(target =>
 				target.ok ? { ok: true, account: target.account } : { ok: false, reason: target.error },
 			);
diff --git a/packages/coding-agent/src/commit/analysis/conventional.ts b/packages/coding-agent/src/commit/analysis/conventional.ts
index 5b52bb5c4..4f8c4ee75 100644
--- a/packages/coding-agent/src/commit/analysis/conventional.ts
+++ b/packages/coding-agent/src/commit/analysis/conventional.ts
@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import analysisSystemPrompt from "../../commit/prompts/analysis-system.md" with { type: "text" };
@@ -14,7 +14,7 @@ const ConventionalAnalysisTool = createConventionalAnalysisTool(
 
 export interface ConventionalAnalysisInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	contextFiles?: Array<{ path: string; content: string }>;
 	userContext?: string;
diff --git a/packages/coding-agent/src/commit/analysis/summary.ts b/packages/coding-agent/src/commit/analysis/summary.ts
index 5dd23ff1f..80bc3f096 100644
--- a/packages/coding-agent/src/commit/analysis/summary.ts
+++ b/packages/coding-agent/src/commit/analysis/summary.ts
@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple, validateToolCall } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
@@ -19,7 +19,7 @@ const SummaryTool = {
 
 export interface SummaryInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	commitType: string;
 	scope: string | null;
diff --git a/packages/coding-agent/src/commit/changelog/generate.ts b/packages/coding-agent/src/commit/changelog/generate.ts
index bc43cd1e7..c59e17b90 100644
--- a/packages/coding-agent/src/commit/changelog/generate.ts
+++ b/packages/coding-agent/src/commit/changelog/generate.ts
@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple, validateToolCall } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
@@ -25,7 +25,7 @@ export const changelogTool = {
 
 export interface ChangelogPromptInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	changelogPath: string;
 	isPackageChangelog: boolean;
diff --git a/packages/coding-agent/src/commit/changelog/index.ts b/packages/coding-agent/src/commit/changelog/index.ts
index f80f79401..5260db181 100644
--- a/packages/coding-agent/src/commit/changelog/index.ts
+++ b/packages/coding-agent/src/commit/changelog/index.ts
@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { logger } from "@oh-my-pi/pi-utils";
 import { CHANGELOG_CATEGORIES } from "../../commit/types";
 import * as git from "../../utils/git";
@@ -15,7 +15,7 @@ const DEFAULT_MAX_DIFF_CHARS = 120_000;
 export interface ChangelogFlowInput {
 	cwd: string;
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	stagedFiles: string[];
 	dryRun: boolean;
diff --git a/packages/coding-agent/src/commit/map-reduce/index.ts b/packages/coding-agent/src/commit/map-reduce/index.ts
index c2e9f3332..a11b417c5 100644
--- a/packages/coding-agent/src/commit/map-reduce/index.ts
+++ b/packages/coding-agent/src/commit/map-reduce/index.ts
@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { $env } from "@oh-my-pi/pi-utils";
 import { parseFileDiffs } from "../../commit/git/diff";
 import type { ConventionalAnalysis } from "../../commit/types";
@@ -21,10 +21,10 @@ export interface MapReduceSettings {
 
 export interface MapReduceInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	smolModel: Model<Api>;
-	smolApiKey: string;
+	smolApiKey: ApiKey;
 	smolThinkingLevel?: ThinkingLevel;
 	diff: string;
 	stat: string;
diff --git a/packages/coding-agent/src/commit/map-reduce/map-phase.ts b/packages/coding-agent/src/commit/map-reduce/map-phase.ts
index 3f376cb87..a263bfead 100644
--- a/packages/coding-agent/src/commit/map-reduce/map-phase.ts
+++ b/packages/coding-agent/src/commit/map-reduce/map-phase.ts
@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, AssistantMessage, Message, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, AssistantMessage, Message, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import fileObserverSystemPrompt from "../../commit/prompts/file-observer-system.md" with { type: "text" };
@@ -18,7 +18,7 @@ const RETRY_BACKOFF_MS = 1000;
 
 export interface MapPhaseInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	files: FileDiff[];
 	config?: {
diff --git a/packages/coding-agent/src/commit/map-reduce/reduce-phase.ts b/packages/coding-agent/src/commit/map-reduce/reduce-phase.ts
index 1ea5278e9..b0caccd0d 100644
--- a/packages/coding-agent/src/commit/map-reduce/reduce-phase.ts
+++ b/packages/coding-agent/src/commit/map-reduce/reduce-phase.ts
@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import reduceSystemPrompt from "../../commit/prompts/reduce-system.md" with { type: "text" };
@@ -12,7 +12,7 @@ const ReduceTool = createConventionalAnalysisTool("Synthesize file observations
 
 export interface ReducePhaseInput {
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	observations: FileObservation[];
 	stat: string;
diff --git a/packages/coding-agent/src/commit/model-selection.ts b/packages/coding-agent/src/commit/model-selection.ts
index 3045dfdf6..00fadcc15 100644
--- a/packages/coding-agent/src/commit/model-selection.ts
+++ b/packages/coding-agent/src/commit/model-selection.ts
@@ -1,5 +1,6 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
+import { type ApiKeyResolverRegistry, reuseInitialApiKey } from "../config/api-key-resolver";
 import { MODEL_ROLE_IDS } from "../config/model-registry";
 import {
 	type ModelLookupRegistry,
@@ -12,13 +13,19 @@ import MODEL_PRIO from "../priority.json" with { type: "json" };
 
 export interface ResolvedCommitModel {
 	model: Model<Api>;
-	apiKey: string;
+	/**
+	 * Resolver for the model's bearer: re-resolves on 401 / usage-limit so the
+	 * whole commit pipeline (analysis, map/reduce, changelog) inherits the
+	 * central force-refresh + account-rotation policy.
+	 */
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 }
 
-type CommitModelRegistry = ModelLookupRegistry & {
-	getApiKey: (model: Model<Api>) => Promise<string | undefined>;
-};
+type CommitModelRegistry = ModelLookupRegistry &
+	ApiKeyResolverRegistry & {
+		getApiKey: (model: Model<Api>) => Promise<string | undefined>;
+	};
 
 export async function resolvePrimaryModel(
 	override: string | undefined,
@@ -38,20 +45,32 @@ export async function resolvePrimaryModel(
 	if (!apiKey) {
 		throw new Error(`No API key available for model ${model.provider}/${model.id}`);
 	}
-	return { model, apiKey, thinkingLevel: resolved?.thinkingLevel };
+	return {
+		model,
+		apiKey: reuseInitialApiKey(apiKey, modelRegistry, model.provider, { baseUrl: model.baseUrl }),
+		thinkingLevel: resolved?.thinkingLevel,
+	};
 }
 
 export async function resolveSmolModel(
 	settings: Settings,
 	modelRegistry: CommitModelRegistry,
 	fallbackModel: Model<Api>,
-	fallbackApiKey: string,
+	fallbackApiKey: ApiKey,
 ): Promise<ResolvedCommitModel> {
 	const available = modelRegistry.getAvailable();
 	const resolvedSmol = resolveRoleSelection(["smol"], settings, available, modelRegistry);
 	if (resolvedSmol?.model) {
 		const apiKey = await modelRegistry.getApiKey(resolvedSmol.model);
-		if (apiKey) return { model: resolvedSmol.model, apiKey, thinkingLevel: resolvedSmol.thinkingLevel };
+		if (apiKey) {
+			return {
+				model: resolvedSmol.model,
+				apiKey: reuseInitialApiKey(apiKey, modelRegistry, resolvedSmol.model.provider, {
+					baseUrl: resolvedSmol.model.baseUrl,
+				}),
+				thinkingLevel: resolvedSmol.thinkingLevel,
+			};
+		}
 	}
 
 	const matchPreferences = { usageOrder: settings.getStorage()?.getModelUsageOrder() };
@@ -59,7 +78,12 @@ export async function resolveSmolModel(
 		const candidate = parseModelPattern(pattern, available, matchPreferences, { modelRegistry }).model;
 		if (!candidate) continue;
 		const apiKey = await modelRegistry.getApiKey(candidate);
-		if (apiKey) return { model: candidate, apiKey };
+		if (apiKey) {
+			return {
+				model: candidate,
+				apiKey: reuseInitialApiKey(apiKey, modelRegistry, candidate.provider, { baseUrl: candidate.baseUrl }),
+			};
+		}
 	}
 
 	return { model: fallbackModel, apiKey: fallbackApiKey };
diff --git a/packages/coding-agent/src/commit/pipeline.ts b/packages/coding-agent/src/commit/pipeline.ts
index bc53e54fe..86d626d9c 100644
--- a/packages/coding-agent/src/commit/pipeline.ts
+++ b/packages/coding-agent/src/commit/pipeline.ts
@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { getProjectDir, logger, prompt } from "@oh-my-pi/pi-utils";
 import { ModelRegistry } from "../config/model-registry";
 import { Settings } from "../config/settings";
@@ -145,10 +145,10 @@ async function generateAnalysis(input: {
 	contextFiles: Array<{ path: string; content: string }>;
 	userContext?: string;
 	primaryModel: Model<Api>;
-	primaryApiKey: string;
+	primaryApiKey: ApiKey;
 	primaryThinkingLevel?: ThinkingLevel;
 	smolModel: Model<Api>;
-	smolApiKey: string;
+	smolApiKey: ApiKey;
 	smolThinkingLevel?: ThinkingLevel;
 	commitSettings: {
 		mapReduceEnabled: boolean;
@@ -206,7 +206,7 @@ async function generateSummaryWithRetry(input: {
 	analysis: ConventionalAnalysis;
 	stat: string;
 	model: Model<Api>;
-	apiKey: string;
+	apiKey: ApiKey;
 	thinkingLevel?: ThinkingLevel;
 	userContext?: string;
 }): Promise<{ summary: string }> {
diff --git a/packages/coding-agent/src/config/api-key-resolver.ts b/packages/coding-agent/src/config/api-key-resolver.ts
new file mode 100644
index 000000000..fa039aa49
--- /dev/null
+++ b/packages/coding-agent/src/config/api-key-resolver.ts
@@ -0,0 +1,77 @@
+import type { ApiKeyResolver, AuthStorage } from "@oh-my-pi/pi-ai";
+
+export interface ApiKeyResolverOptions {
+	/** Session id for credential stickiness; read at resolve time by the caller. */
+	sessionId?: string;
+	/** Provider base URL hint forwarded to the auth-storage cascade. */
+	baseUrl?: string;
+}
+
+/**
+ * Minimal slice of `ModelRegistry` the resolver needs. Typed structurally so
+ * narrower registry shells (e.g. the commit pipeline's `CommitModelRegistry`)
+ * can build resolvers without depending on the full class.
+ */
+export interface ApiKeyResolverRegistry {
+	getApiKeyForProvider(
+		provider: string,
+		sessionId?: string,
+		options?: { baseUrl?: string; forceRefresh?: boolean; signal?: AbortSignal },
+	): Promise<string | undefined>;
+	authStorage: Pick<AuthStorage, "rotateSessionCredential">;
+}
+
+/**
+ * Build an {@link ApiKeyResolver} backed by the model registry's auth storage,
+ * implementing the central a/b/c auth-retry policy for every non-agent network
+ * consumer (utility completions, image generation, web search):
+ *
+ * - initial (`error: undefined`) → resolve the session credential (cheap; may
+ *   return a locally-cached not-yet-expired token).
+ * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential
+ *   (a peer/broker may have rotated its token out from under our cached copy).
+ * - step (c) `lastChance` → rotate to a sibling credential (usage-limit block
+ *   vs credential invalidation, by error class), then re-resolve.
+ *
+ * Stateless: nothing is captured beyond the registry/provider/options, so the
+ * same resolver is safe to reuse across attempts and requests.
+ */
+export function createApiKeyResolver(
+	registry: ApiKeyResolverRegistry,
+	provider: string,
+	options: ApiKeyResolverOptions = {},
+): ApiKeyResolver {
+	const { sessionId, baseUrl } = options;
+	return async ({ lastChance, error, signal }) => {
+		if (error === undefined) {
+			return registry.getApiKeyForProvider(provider, sessionId, { baseUrl });
+		}
+		if (lastChance) {
+			// Account constraint (401 / usage / account-rate-limit): rotate to a
+			// sibling credential. We do NOT honor any retry-after here — if a
+			// sibling exists we switch immediately; the precise no-sibling backoff
+			// is owned by `markUsageLimitReached` (default + server usage-report
+			// reset) and the outer whole-turn retry layer.
+			await registry.authStorage.rotateSessionCredential(provider, sessionId, { error, signal });
+			return registry.getApiKeyForProvider(provider, sessionId, { baseUrl });
+		}
+		return registry.getApiKeyForProvider(provider, sessionId, { baseUrl, forceRefresh: true, signal });
+	};
+}
+
+/**
+ * Wrap an already-resolved `initialKey` in an {@link ApiKeyResolver}: the
+ * initial step returns that key verbatim (so a caller that resolved it eagerly
+ * — e.g. to preserve a metadata / guard ordering, or to short-circuit when no
+ * credential exists — does not pay for a second resolve), while retry steps
+ * fall through to {@link createApiKeyResolver}'s force-refresh / rotate policy.
+ */
+export function reuseInitialApiKey(
+	initialKey: string | undefined,
+	registry: ApiKeyResolverRegistry,
+	provider: string,
+	options: ApiKeyResolverOptions = {},
+): ApiKeyResolver {
+	const retry = createApiKeyResolver(registry, provider, options);
+	return ctx => (ctx.error === undefined ? initialKey : retry(ctx));
+}
diff --git a/packages/coding-agent/src/config/model-registry.ts b/packages/coding-agent/src/config/model-registry.ts
index eb35413e1..01b21eb04 100644
--- a/packages/coding-agent/src/config/model-registry.ts
+++ b/packages/coding-agent/src/config/model-registry.ts
@@ -2365,12 +2365,24 @@ export class ModelRegistry {
 
 	/**
 	 * Get API key for a provider (e.g., "openai").
+	 *
+	 * `options.forceRefresh` powers step (b) of the auth-retry policy — it
+	 * re-mints the session-sticky OAuth token even when the cached copy still
+	 * looks valid. `options.signal` is threaded into any broker-bound refresh.
 	 */
-	async getApiKeyForProvider(provider: string, sessionId?: string, baseUrl?: string): Promise<string | undefined> {
+	async getApiKeyForProvider(
+		provider: string,
+		sessionId?: string,
+		options?: { baseUrl?: string; forceRefresh?: boolean; signal?: AbortSignal },
+	): Promise<string | undefined> {
 		if (this.#keylessProviders.has(provider) && !this.authStorage.hasAuth(provider)) {
 			return kNoAuth;
 		}
-		return this.authStorage.getApiKey(provider, sessionId, { baseUrl });
+		return this.authStorage.getApiKey(provider, sessionId, {
+			baseUrl: options?.baseUrl,
+			forceRefresh: options?.forceRefresh,
+			signal: options?.signal,
+		});
 	}
 
 	async #peekApiKeyForProvider(provider: string): Promise<string | undefined> {
diff --git a/packages/coding-agent/src/eval/llm-bridge.ts b/packages/coding-agent/src/eval/llm-bridge.ts
index 931763651..484290352 100644
--- a/packages/coding-agent/src/eval/llm-bridge.ts
+++ b/packages/coding-agent/src/eval/llm-bridge.ts
@@ -15,6 +15,7 @@ import { instrumentedCompleteSimple, resolveTelemetry } from "@oh-my-pi/pi-agent
 import { type Api, Effort, getSupportedEfforts, type Model, type Tool } from "@oh-my-pi/pi-ai";
 import * as z from "zod/v4";
 import { extractTextContent, extractToolCall, parseJsonPayload } from "../commit/utils";
+import { reuseInitialApiKey } from "../config/api-key-resolver";
 import { expandRoleAlias, formatModelString, resolveModelFromString } from "../config/model-resolver";
 import type { ToolSession } from "../tools";
 import { ToolError } from "../tools/tool-errors";
@@ -112,8 +113,9 @@ export async function runEvalLlm(args: unknown, options: EvalLlmBridgeOptions):
 		);
 	}
 
-	const apiKey = await options.session.modelRegistry?.getApiKey(model);
-	if (!apiKey) {
+	const registry = options.session.modelRegistry;
+	const apiKey = await registry?.getApiKey(model);
+	if (!registry || !apiKey) {
 		throw new ToolError(
 			`llm() has no API key for ${formatModelString(model)}. Configure credentials for this provider or choose another tier.`,
 		);
@@ -143,7 +145,10 @@ export async function runEvalLlm(args: unknown, options: EvalLlmBridgeOptions):
 				tools,
 			},
 			{
-				apiKey,
+				apiKey: reuseInitialApiKey(apiKey, registry, model.provider, {
+					sessionId: options.session.getSessionId?.() ?? undefined,
+					baseUrl: model.baseUrl,
+				}),
 				signal: options.signal,
 				reasoning: reasoningForTier(tier, model),
 				toolChoice: schema ? { type: "tool", name: STRUCTURED_TOOL_NAME } : undefined,
diff --git a/packages/coding-agent/src/memories/index.ts b/packages/coding-agent/src/memories/index.ts
index ae27abbe1..5ddafbba6 100644
--- a/packages/coding-agent/src/memories/index.ts
+++ b/packages/coding-agent/src/memories/index.ts
@@ -3,8 +3,9 @@ import type * as fsNode from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import { clampThinkingLevelForModel, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
+import { type ApiKey, clampThinkingLevelForModel, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
 import { getAgentDbPath, getMemoriesDir, logger, parseJsonlLenient, prompt } from "@oh-my-pi/pi-utils";
+import { reuseInitialApiKey } from "../config/api-key-resolver";
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveModelRoleValue } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -271,7 +272,10 @@ async function runPhase1(options: {
 			const result = await runStage1Job({
 				claim,
 				model: phase1Model,
-				apiKey: phase1ApiKey,
+				apiKey: reuseInitialApiKey(phase1ApiKey, modelRegistry, phase1Model.provider, {
+					sessionId: session.sessionId,
+					baseUrl: phase1Model.baseUrl,
+				}),
 				modelMaxTokens: computeModelTokenBudget(phase1Model, config),
 				config,
 				metadata: session.agent?.metadataForProvider(phase1Model.provider),
@@ -428,7 +432,10 @@ async function runPhase2(options: {
 			const consolidated = await runConsolidationModel({
 				memoryRoot,
 				model: phase2Model,
-				apiKey: phase2ApiKey,
+				apiKey: reuseInitialApiKey(phase2ApiKey, modelRegistry, phase2Model.provider, {
+					sessionId: session.sessionId,
+					baseUrl: phase2Model.baseUrl,
+				}),
 				metadata: session.agent?.metadataForProvider(phase2Model.provider),
 			});
 			await applyConsolidation(memoryRoot, consolidated);
@@ -574,7 +581,7 @@ function extractPersistableMessages(payload: string): AgentMessage[] {
 async function runStage1Job(options: {
 	claim: Stage1Claim;
 	model: Model;
-	apiKey: string;
+	apiKey: ApiKey;
 	modelMaxTokens: number;
 	config: MemoryRuntimeConfig;
 	metadata?: Record<string, unknown>;
@@ -718,7 +725,7 @@ async function readRolloutSummaries(memoryRoot: string): Promise<string> {
 async function runConsolidationModel(options: {
 	memoryRoot: string;
 	model: Model;
-	apiKey: string;
+	apiKey: ApiKey;
 	metadata?: Record<string, unknown>;
 }): Promise<{
 	memoryMd: string;
diff --git a/packages/coding-agent/src/mnemopi/backend.ts b/packages/coding-agent/src/mnemopi/backend.ts
index 167c37250..9af906894 100644
--- a/packages/coding-agent/src/mnemopi/backend.ts
+++ b/packages/coding-agent/src/mnemopi/backend.ts
@@ -5,6 +5,7 @@ import { Mnemopi } from "@oh-my-pi/pi-mnemopi";
 import { BankManager } from "@oh-my-pi/pi-mnemopi/core";
 import { type DiagnosticSummary, inspectDatabase } from "@oh-my-pi/pi-mnemopi/diagnose";
 import { logger } from "@oh-my-pi/pi-utils";
+import { reuseInitialApiKey } from "../config/api-key-resolver";
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { MemoryBackend, MemoryBackendStartOptions } from "../memory-backend/types";
@@ -334,7 +335,10 @@ async function resolveMnemopiProviderOptions(
 						messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
 					},
 					{
-						apiKey,
+						apiKey: reuseInitialApiKey(apiKey, modelRegistry, model.provider, {
+							sessionId,
+							baseUrl: model.baseUrl,
+						}),
 						maxTokens: opts?.maxTokens,
 						temperature: opts?.temperature,
 					},
diff --git a/packages/coding-agent/src/sdk.ts b/packages/coding-agent/src/sdk.ts
index 46ad4553e..d214f5335 100644
--- a/packages/coding-agent/src/sdk.ts
+++ b/packages/coding-agent/src/sdk.ts
@@ -10,7 +10,6 @@ import {
 } from "@oh-my-pi/pi-agent-core";
 import {
 	type CredentialDisabledEvent,
-	isUsageLimitError,
 	type Message,
 	type Model,
 	type SimpleStreamOptions,
@@ -24,7 +23,6 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import {
 	$env,
 	$flag,
-	extractRetryHint,
 	getAgentDbPath,
 	getAgentDir,
 	getAuthBrokerSnapshotCachePath,
@@ -39,6 +37,7 @@ import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled } from ".
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { bucketRules } from "./capability/rule-buckets";
+import { createApiKeyResolver } from "./config/api-key-resolver";
 import { shouldEnableAppendOnlyContext } from "./config/append-only-context-mode";
 import { ModelRegistry } from "./config/model-registry";
 import {
@@ -2017,9 +2016,15 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
 			preferWebsockets: preferOpenAICodexWebsockets,
 			getToolContext: tc => toolContextStore.getContext(tc),
-			getApiKey: async provider => {
+			getApiKey: async (provider, ctx) => {
 				// Read agent.sessionId at call time so credential selection stays aligned
 				// with metadataResolver after /new, fork, resume, or branch switches.
+				// Retry steps (ctx carries an auth error) drive the central a/b/c
+				// policy — force-refresh the same account, then rotate to a sibling —
+				// and may legitimately yield no key when every account is exhausted.
+				if (ctx?.error !== undefined) {
+					return createApiKeyResolver(modelRegistry, provider, { sessionId: agent.sessionId })(ctx);
+				}
 				const key = await modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
 				if (!key) {
 					throw new Error(`No API key found for provider "${provider}"`);
@@ -2033,40 +2038,6 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				return streamSimple(streamModel, context, {
 					...streamOptions,
 					openrouterVariant: streamOptions?.openrouterVariant ?? openrouterVariant,
-					onAuthError: async (provider, oldKey, error) => {
-						const message = error instanceof Error ? error.message : String(error);
-						// streamSimple invokes this for both 401 auth failures AND
-						// rotatable usage-limit errors (Codex usage_limit_reached,
-						// Anthropic usage_limit_reached, etc.). The two need
-						// different storage actions: a real 401 means the credential
-						// is bad and should be marked suspect; a usage limit just
-						// means this account is parked until reset and should be
-						// temporarily blocked so a sibling can pick the request up.
-						if (isUsageLimitError(message)) {
-							const retryAfterMs = extractRetryHint(undefined, message);
-							const switched = await modelRegistry.authStorage.markUsageLimitReached(provider, agent.sessionId, {
-								retryAfterMs,
-								signal: streamOptions?.signal,
-							});
-							logger.debug("Retrying provider request after usage-limit block", {
-								provider,
-								switched,
-								retryAfterMs,
-								error: message,
-							});
-							if (!switched) return undefined;
-							return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
-						}
-						await modelRegistry.authStorage.invalidateCredentialMatching(provider, oldKey, {
-							signal: streamOptions?.signal,
-							sessionId: agent.sessionId,
-						});
-						logger.debug("Retrying provider request after credential invalidation", {
-							provider,
-							error: message,
-						});
-						return modelRegistry.getApiKeyForProvider(provider, agent.sessionId);
-					},
 				});
 			},
 			cursorExecHandlers,
diff --git a/packages/coding-agent/src/utils/commit-message-generator.ts b/packages/coding-agent/src/utils/commit-message-generator.ts
index cdc16f491..3e95d51a5 100644
--- a/packages/coding-agent/src/utils/commit-message-generator.ts
+++ b/packages/coding-agent/src/utils/commit-message-generator.ts
@@ -6,6 +6,7 @@ import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Api, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple } from "@oh-my-pi/pi-ai";
 import { logger, prompt } from "@oh-my-pi/pi-utils";
+import { reuseInitialApiKey } from "../config/api-key-resolver";
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveModelRoleValue } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -110,7 +111,14 @@ export async function generateCommitMessage(
 					systemPrompt: [COMMIT_SYSTEM_PROMPT],
 					messages: [{ role: "user", content: userMessage, timestamp: Date.now() }],
 				},
-				{ apiKey, maxTokens, reasoning: toReasoningEffort(candidate.thinkingLevel) },
+				{
+					apiKey: reuseInitialApiKey(apiKey, registry, candidate.model.provider, {
+						sessionId,
+						baseUrl: candidate.model.baseUrl,
+					}),
+					maxTokens,
+					reasoning: toReasoningEffort(candidate.thinkingLevel),
+				},
 			);
 
 			if (response.stopReason === "error") {
diff --git a/packages/coding-agent/src/utils/title-generator.ts b/packages/coding-agent/src/utils/title-generator.ts
index 84f4eab1e..cf71609e8 100644
--- a/packages/coding-agent/src/utils/title-generator.ts
+++ b/packages/coding-agent/src/utils/title-generator.ts
@@ -6,6 +6,7 @@ import * as path from "node:path";
 import { type Api, type AssistantMessage, completeSimple, type Model, type Tool } from "@oh-my-pi/pi-ai";
 import { logger, prompt } from "@oh-my-pi/pi-utils";
 import type { ModelRegistry } from "../config/model-registry";
+import { reuseInitialApiKey } from "../config/api-key-resolver";
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
 import titleSystemPrompt from "../prompts/system/title-system.md" with { type: "text" };
@@ -238,7 +239,7 @@ export async function generateTitleOnline(
 				tools: [setTitleTool],
 			},
 			{
-				apiKey,
+				apiKey: reuseInitialApiKey(apiKey, registry, model.provider, { sessionId, baseUrl: model.baseUrl }),
 				maxTokens,
 				disableReasoning: true,
 				toolChoice: { type: "tool", name: SET_TITLE_TOOL_NAME },
diff --git a/packages/coding-agent/test/commit-model-selection-role-thinking.test.ts b/packages/coding-agent/test/commit-model-selection-role-thinking.test.ts
index 2c1745f09..71d8134ec 100644
--- a/packages/coding-agent/test/commit-model-selection-role-thinking.test.ts
+++ b/packages/coding-agent/test/commit-model-selection-role-thinking.test.ts
@@ -38,6 +38,8 @@ describe("commit role thinking selection", () => {
 		const registry = {
 			getAvailable: () => [defaultModel, commitModel],
 			getApiKey: async () => "test-key",
+			getApiKeyForProvider: async () => "test-key",
+			authStorage: { rotateSessionCredential: async () => false },
 		};
 
 		const primary = await resolvePrimaryModel(undefined, settings, registry);
diff --git a/packages/tui/src/components/scroll-view.ts b/packages/tui/src/components/scroll-view.ts
index b66d768bf..1bb5de9bd 100644
--- a/packages/tui/src/components/scroll-view.ts
+++ b/packages/tui/src/components/scroll-view.ts
@@ -1,3 +1,4 @@
+import { matchesKey } from "../keys";
 import type { Component } from "../tui";
 import { Ellipsis, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
 
@@ -20,6 +21,18 @@ export interface ScrollViewOptions {
 	theme?: ScrollViewTheme;
 	trackChar?: string;
 	thumbChar?: string;
+	/**
+	 * Indicator appended when a row overflows `contentWidth`. Defaults to
+	 * {@link Ellipsis.Unicode}. Pass {@link Ellipsis.Omit} when callers wrap
+	 * lines to width themselves and only trailing padding can overflow (e.g.
+	 * the plan-review overlay), so no stray `…` lands on every padded row.
+	 */
+	ellipsis?: Ellipsis;
+	/**
+	 * Rows moved per keystroke when {@link ScrollView.handleScrollKey} sees a
+	 * Shift+Arrow (the "scroll faster" affordance). Defaults to 5.
+	 */
+	fastScrollLines?: number;
 }
 
 function normalizeScrollbarMode(scrollbar: ScrollViewOptions["scrollbar"]): ScrollbarMode {
@@ -48,6 +61,8 @@ export class ScrollView implements Component {
 	#theme: Required<ScrollViewTheme>;
 	#trackChar: string;
 	#thumbChar: string;
+	#ellipsis: Ellipsis;
+	#fastScrollLines: number;
 
 	constructor(lines: readonly string[], options: ScrollViewOptions) {
 		this.#lines = [...lines];
@@ -60,6 +75,8 @@ export class ScrollView implements Component {
 		};
 		this.#trackChar = firstCellGlyph(options.trackChar ?? DEFAULT_TRACK, DEFAULT_TRACK);
 		this.#thumbChar = firstCellGlyph(options.thumbChar ?? DEFAULT_THUMB, DEFAULT_THUMB);
+		this.#ellipsis = options.ellipsis ?? Ellipsis.Unicode;
+		this.#fastScrollLines = Math.max(1, Math.trunc(options.fastScrollLines ?? 5));
 		this.#clampScrollOffset();
 	}
 
@@ -113,6 +130,50 @@ export class ScrollView implements Component {
 		this.#scrollOffset = this.getMaxScrollOffset();
 	}
 
+	/**
+	 * Apply a standard navigation key to the viewport. Shift+Arrow scrolls by
+	 * {@link ScrollViewOptions.fastScrollLines} (the "scroll faster" affordance);
+	 * plain Arrow by one line; PageUp/PageDown by a page; Home/End to the ends.
+	 * Returns true when the key was consumed, so callers can fall through to
+	 * their own (e.g. vim-style) bindings. Generic on purpose: every ScrollView
+	 * consumer gets the same scroll keys, including Shift-to-go-faster.
+	 */
+	handleScrollKey(data: string): boolean {
+		if (matchesKey(data, "shift+up")) {
+			this.scroll(-this.#fastScrollLines);
+			return true;
+		}
+		if (matchesKey(data, "shift+down")) {
+			this.scroll(this.#fastScrollLines);
+			return true;
+		}
+		if (matchesKey(data, "up")) {
+			this.scroll(-1);
+			return true;
+		}
+		if (matchesKey(data, "down")) {
+			this.scroll(1);
+			return true;
+		}
+		if (matchesKey(data, "pageUp")) {
+			this.page(-1);
+			return true;
+		}
+		if (matchesKey(data, "pageDown")) {
+			this.page(1);
+			return true;
+		}
+		if (matchesKey(data, "home")) {
+			this.scrollToTop();
+			return true;
+		}
+		if (matchesKey(data, "end")) {
+			this.scrollToBottom();
+			return true;
+		}
+		return false;
+	}
+
 	invalidate(): void {
 		// No cached layout to invalidate.
 	}
@@ -128,7 +189,7 @@ export class ScrollView implements Component {
 		for (let row = 0; row < this.#height; row++) {
 			const sourceIndex = this.#totalRows === undefined ? this.#scrollOffset + row : row;
 			const source = this.#lines[sourceIndex] ?? "";
-			const truncated = truncateToWidth(replaceTabs(source), contentWidth, Ellipsis.Unicode);
+			const truncated = truncateToWidth(replaceTabs(source), contentWidth, this.#ellipsis);
 			if (!showScrollbar) {
 				lines.push(truncated);
 				continue;
diff --git a/packages/tui/test/scroll-view.test.ts b/packages/tui/test/scroll-view.test.ts
index fafd12b82..6e2c2af67 100644
--- a/packages/tui/test/scroll-view.test.ts
+++ b/packages/tui/test/scroll-view.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import { ScrollView } from "../src/components/scroll-view";
-import { visibleWidth } from "../src/utils";
+import { Ellipsis, visibleWidth } from "../src/utils";
 
 const theme = {
 	track: () => "T",
@@ -76,4 +76,28 @@ describe("ScrollView", () => {
 		expect(rendered.every(line => visibleWidth(line) <= 5)).toBe(true);
 		expect(rendered[0]).toContain("B");
 	});
+
+	it("appends an overflow ellipsis by default and omits it when configured", () => {
+		const long = ["abcdefghij"];
+		const def = new ScrollView(long, { height: 1, scrollbar: "never", theme });
+		expect(def.render(5)[0]).toContain("…");
+
+		const omit = new ScrollView(long, { height: 1, scrollbar: "never", ellipsis: Ellipsis.Omit, theme });
+		expect(omit.render(5)[0]).toBe("abcde");
+	});
+
+	it("handles navigation keys, with Shift+Arrow scrolling by fastScrollLines", () => {
+		const view = new ScrollView(
+			Array.from({ length: 50 }, (_, i) => String(i)),
+			{ height: 5, fastScrollLines: 7, theme },
+		);
+
+		expect(view.handleScrollKey("\x1b[B")).toBe(true); // down
+		expect(view.getScrollOffset()).toBe(1);
+		expect(view.handleScrollKey("\x1b[1;2B")).toBe(true); // shift+down
+		expect(view.getScrollOffset()).toBe(8);
+		expect(view.handleScrollKey("\x1b[1;2A")).toBe(true); // shift+up
+		expect(view.getScrollOffset()).toBe(1);
+		expect(view.handleScrollKey("x")).toBe(false);
+	});
 });

From 6d617e89f345184f437513c8b13f99fa0062f406 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 04:24:11 +0200
Subject: [PATCH 083/181] refactor(tui): removed Kitty temp-file graphics
 transmission

- Dropped the `t=t` probe, transmission medium, and SSH gating.
- Kitty images now always transmit in-band base64.
---
 docs/tui-runtime-internals.md                 |   2 +-
 packages/tui/src/index.ts                     |   2 +-
 packages/tui/src/kitty-graphics.ts            | 103 +-----------------
 packages/tui/src/terminal-capabilities.ts     |  13 +--
 packages/tui/src/terminal.ts                  |  62 +----------
 packages/tui/test/image-budget.test.ts        |   2 +-
 packages/tui/test/image-render.test.ts        |  12 ++
 packages/tui/test/kitty-graphics.test.ts      |  81 +-------------
 packages/tui/test/terminal-appearance.test.ts |  68 ------------
 9 files changed, 23 insertions(+), 322 deletions(-)

diff --git a/docs/tui-runtime-internals.md b/docs/tui-runtime-internals.md
index c4fb02030..20beca245 100644
--- a/docs/tui-runtime-internals.md
+++ b/docs/tui-runtime-internals.md
@@ -56,7 +56,7 @@ A forced render (`requestRender(true)`) queues a viewport repaint or explicit se
 4. Creates a `StdinBuffer` to split partial escape chunks into complete sequences.
 5. Queries Kitty keyboard protocol support (`CSI ? u`), then enables protocol flags if supported; otherwise enables modifyOtherKeys fallback after a short timeout.
 6. Queries OSC 11 background color and Mode 2031 appearance notifications for dark/light theme detection.
-7. Queries OSC 99 notification capabilities and Kitty temp-file graphics support.
+7. Queries OSC 99 notification capabilities.
 8. Starts periodic OSC 11 polling only where safe, then probes DEC private modes 2026/2048/2031 via DECRQM.
 
 `StdinBuffer` behavior:
diff --git a/packages/tui/src/index.ts b/packages/tui/src/index.ts
index 99cb1fe28..33928af46 100644
--- a/packages/tui/src/index.ts
+++ b/packages/tui/src/index.ts
@@ -27,7 +27,7 @@ export * from "./fuzzy";
 export * from "./keybindings";
 // Kitty keyboard protocol helpers
 export * from "./keys";
-// Kitty graphics: Unicode placeholders + temp-file transmission
+// Kitty graphics: Unicode placeholders
 export * from "./kitty-graphics";
 // Mermaid diagram support
 // Input buffering for batch splitting
diff --git a/packages/tui/src/kitty-graphics.ts b/packages/tui/src/kitty-graphics.ts
index 8b65bf5d8..0b403d217 100644
--- a/packages/tui/src/kitty-graphics.ts
+++ b/packages/tui/src/kitty-graphics.ts
@@ -1,6 +1,6 @@
 /**
- * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE) and temp-file
- * (`t=t`) image transmission, with runtime feature state and env overrides.
+ * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE), with
+ * runtime feature state and env overrides.
  *
  * Unicode placeholders let a transmitted image be displayed by writing ordinary
  * text cells — the placeholder char U+10EEEE plus row/column combining
@@ -14,10 +14,6 @@
  * dependency stays one-way (capabilities → kitty-graphics) and no import cycle
  * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
  */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { $env, logger } from "@oh-my-pi/pi-utils";
 
 /** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
 export const KITTY_PLACEHOLDER = "\u{10eeee}";
@@ -55,25 +51,9 @@ const ROWCOLUMN_DIACRITICS: readonly number[] = [
 /** Largest row/column index expressible with the diacritic table (one cell each). */
 export const KITTY_PLACEHOLDER_MAX_CELLS = ROWCOLUMN_DIACRITICS.length;
 
-/** A minimal opaque 1x1 PNG (base64) used for the temp-file support probe. */
-const PROBE_PNG_BASE64 =
-	"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
-
-export type KittyTransmissionMedium = "direct" | "temp-file";
-
 export interface KittyGraphicsFeatures {
 	/** Display images via Unicode placeholders instead of direct `a=p` placement. */
 	unicodePlaceholders: boolean;
-	/** How image data reaches the terminal: in-band base64 or a temp file. */
-	transmissionMedium: KittyTransmissionMedium;
-}
-
-/** Explicit transmission medium from `PI_KITTY_IMAGE_TRANSMISSION`, else "auto". */
-function transmissionOverride(): KittyTransmissionMedium | "auto" {
-	const raw = $env.PI_KITTY_IMAGE_TRANSMISSION?.trim().toLowerCase();
-	if (raw === "temp-file") return "temp-file";
-	if (raw === "direct") return "direct";
-	return "auto";
 }
 
 /**
@@ -106,8 +86,6 @@ let features: KittyGraphicsFeatures = {
 	// Off until `terminal-capabilities` seeds it from the detected terminal id —
 	// the default-on path corrupts wezterm and tmux-passthrough sessions.
 	unicodePlaceholders: false,
-	// Start direct; a successful probe (or explicit `temp-file` override) promotes.
-	transmissionMedium: transmissionOverride() === "temp-file" ? "temp-file" : "direct",
 };
 
 export function getKittyGraphics(): Readonly<KittyGraphicsFeatures> {
@@ -118,29 +96,11 @@ export function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void
 	features = { ...features, ...partial };
 }
 
-/**
- * Whether temp-file transmission may be promoted at runtime: forced via env,
- * disabled via env, otherwise auto (local sessions only — a temp file written
- * locally is not readable by a terminal on the far side of an SSH link).
- */
-export function kittyTempFileAllowed(): boolean {
-	const override = transmissionOverride();
-	if (override === "temp-file") return true;
-	if (override === "direct") return false;
-	// Auto: local sessions only — a temp file written here is not on the SSH peer.
-	return !$env.SSH_CONNECTION && !$env.SSH_CLIENT && !$env.SSH_TTY;
-}
-
 /** Whether a `columns`×`rows` placeholder grid fits within the diacritic table. */
 export function kittyPlaceholdersFit(columns: number, rows: number): boolean {
 	return columns >= 1 && rows >= 1 && columns <= KITTY_PLACEHOLDER_MAX_CELLS && rows <= KITTY_PLACEHOLDER_MAX_CELLS;
 }
 
-/** True when the base64 payload is a PNG (kitty `f=100` / temp-file path only). */
-export function isPngBase64(base64Data: string): boolean {
-	return base64Data.startsWith("iVBORw0KGgo");
-}
-
 function diacritic(index: number): string {
 	const cp = ROWCOLUMN_DIACRITICS[index];
 	return cp === undefined ? "" : String.fromCodePoint(cp);
@@ -209,62 +169,3 @@ export function renderKittyPlaceholderLines(opts: {
 	}
 	return grid;
 }
-
-/**
- * Path for a temp-file transmission. Kitty deletes a `t=t` file after reading it
- * **only** when the path contains the substring `tty-graphics-protocol`, so it is
- * embedded in the filename to keep the temp dir self-cleaning.
- */
-function tempGraphicsPath(tag: string): string {
-	return path.join(os.tmpdir(), `tty-graphics-protocol-${tag}-${process.pid}-${Date.now()}.png`);
-}
-
-/**
- * Transmit a PNG via a temp file (`t=t`): decode the base64 to bytes once, write
- * them to a temp file, and send the base64-encoded file path as payload. Returns
- * the APC string, or `null` on any failure (caller falls back to direct base64).
- *
- * Synchronous filesystem writes are mandated by the synchronous render pipeline
- * (`Image.render` → `renderImage` are sync); there is no async seam here.
- */
-export function encodeKittyTempFileTransmit(base64Png: string, imageId: number): string | null {
-	try {
-		const bytes = Buffer.from(base64Png, "base64");
-		if (bytes.length === 0) return null;
-		const file = tempGraphicsPath(`i${imageId}`);
-		fs.writeFileSync(file, bytes);
-		const encodedPath = Buffer.from(file, "utf8").toString("base64");
-		return `\x1b_Ga=t,f=100,t=t,S=${bytes.length},q=2,i=${imageId};${encodedPath}\x1b\\`;
-	} catch (err) {
-		logger.debug("Kitty temp-file transmit failed; using direct base64", { err: String(err) });
-		return null;
-	}
-}
-
-/**
- * Encode a temp-file support probe: write a tiny PNG to a temp file and ask the
- * terminal to query it (`a=q,t=t`). A conforming terminal replies
- * `ESC _ G i=<probeId>;OK ESC \`. Returns the query APC plus a `cleanup` that
- * removes the probe file (best-effort; kitty self-deletes the magic-named file).
- * Returns `null` if the temp file cannot be written.
- */
-export function encodeKittyTempFileProbe(probeId: number): { sequence: string; cleanup: () => void } | null {
-	try {
-		const bytes = Buffer.from(PROBE_PNG_BASE64, "base64");
-		const file = tempGraphicsPath(`probe${probeId}`);
-		fs.writeFileSync(file, bytes);
-		const encodedPath = Buffer.from(file, "utf8").toString("base64");
-		const sequence = `\x1b_Ga=q,t=t,f=100,S=${bytes.length},q=2,i=${probeId};${encodedPath}\x1b\\`;
-		const cleanup = () => {
-			try {
-				fs.rmSync(file, { force: true });
-			} catch {
-				// Best effort; kitty deletes tty-graphics-protocol files itself.
-			}
-		};
-		return { sequence, cleanup };
-	} catch (err) {
-		logger.debug("Kitty temp-file probe setup failed", { err: String(err) });
-		return null;
-	}
-}
diff --git a/packages/tui/src/terminal-capabilities.ts b/packages/tui/src/terminal-capabilities.ts
index 9324386a3..dfea3bd4a 100644
--- a/packages/tui/src/terminal-capabilities.ts
+++ b/packages/tui/src/terminal-capabilities.ts
@@ -2,9 +2,7 @@ import { encodeSixel } from "@oh-my-pi/pi-natives";
 import { $env, isBunTestRuntime } from "@oh-my-pi/pi-utils";
 import {
 	detectKittyUnicodePlaceholdersSupport,
-	encodeKittyTempFileTransmit,
 	getKittyGraphics,
-	isPngBase64,
 	KITTY_PLACEHOLDER,
 	kittyPlaceholdersFit,
 	renderKittyPlaceholderLines,
@@ -807,16 +805,11 @@ export function renderImage(
 		if (options.imageId != null) {
 			const placementId = options.placementId ?? options.imageId;
 			const graphics = getKittyGraphics();
-			// Transmit-once (keyed by id). Prefer a local temp file for PNGs when the
-			// medium has been promoted; otherwise send in-band base64. Repaints reuse
-			// the stored image, so the transmit is only emitted when requested.
+			// Transmit-once (keyed by id). Repaints reuse the stored image, so the
+			// transmit is only emitted when requested.
 			let transmit: string | undefined;
 			if (options.includeTransmit) {
-				const tempFile =
-					graphics.transmissionMedium === "temp-file" && isPngBase64(base64Data)
-						? encodeKittyTempFileTransmit(base64Data, options.imageId)
-						: null;
-				transmit = tempFile ?? encodeKittyTransmit(base64Data, options.imageId);
+				transmit = encodeKittyTransmit(base64Data, options.imageId);
 			}
 			// Unicode placeholders render the image as real text cells (which survive
 			// horizontal slicing, reflow and overlaps) instead of a cursor-positioned
diff --git a/packages/tui/src/terminal.ts b/packages/tui/src/terminal.ts
index b7c8db2e9..8f8ac4337 100644
--- a/packages/tui/src/terminal.ts
+++ b/packages/tui/src/terminal.ts
@@ -2,9 +2,8 @@ import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as fs from "node:fs";
 import { $env, isBunTestRuntime, logger } from "@oh-my-pi/pi-utils";
 import { setKittyProtocolActive } from "./keys";
-import { encodeKittyTempFileProbe, getKittyGraphics, kittyTempFileAllowed, setKittyGraphics } from "./kitty-graphics";
 import { StdinBuffer } from "./stdin-buffer";
-import { ImageProtocol, NotifyProtocol, setCellDimensions, setOsc99Supported, TERMINAL } from "./terminal-capabilities";
+import { NotifyProtocol, setCellDimensions, setOsc99Supported, TERMINAL } from "./terminal-capabilities";
 
 const TERMINAL_PROGRESS_KEEPALIVE_MS = 1000;
 const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
@@ -159,11 +158,9 @@ type Da1SentinelOwner =
 	| { kind: "keyboard" }
 	| { kind: "osc11" }
 	| { kind: "privateMode"; mode: number }
-	| { kind: "kittyGraphicsProbe"; id: number }
 	| { kind: "osc99Probe"; id: string };
 
 let nextOsc99ProbeId = 1;
-let nextKittyGraphicsProbeId = 1;
 
 function parseOsc99KeyValues(section: string): Map<string, string> {
 	const values = new Map<string, string>();
@@ -198,8 +195,6 @@ export class ProcessTerminal implements Terminal {
 	#osc99PendingId: string | undefined;
 	#osc99ResponseBuffer = "";
 	#osc99Capabilities = new Map<string, string>();
-	#kittyGraphicsPendingId: number | undefined;
-	#kittyGraphicsProbeCleanup: (() => void) | undefined;
 	#privateCsiResponseBuffer = "";
 	#da1SentinelOwners: Da1SentinelOwner[] = [];
 	/** Resolved DECRQM support per private mode (mode → supported). */
@@ -285,11 +280,6 @@ export class ProcessTerminal implements Terminal {
 		// without leaking probe bytes to application input.
 		this.#queryOsc99Support();
 
-		// Probe Kitty temp-file (`t=t`) graphics transmission support. Rides the
-		// same DA1 sentinel FIFO; promotes the transmission medium to temp-file
-		// only on an explicit `OK`, so unsupported terminals stay on direct base64.
-		this.#queryKittyGraphicsTempFile();
-
 		// Subscribe to Mode 2031 appearance change notifications.
 		// When the terminal reports a change, we re-query OSC 11 to get the
 		// actual background color (following Neovim convention) with 100ms debounce.
@@ -508,9 +498,6 @@ export class ProcessTerminal implements Terminal {
 						this.#resolveOsc99Support(owner.id, false);
 						break;
 					}
-					case "kittyGraphicsProbe":
-						this.#resolveKittyGraphicsTempFile(owner.id, false);
-						break;
 				}
 				return;
 			}
@@ -576,21 +563,6 @@ export class ProcessTerminal implements Terminal {
 				}
 			}
 
-			// Kitty graphics temp-file probe reply: ESC _ G i=<id>;OK ESC \. The
-			// owner remains in the FIFO and is drained by its DA1 sentinel (no-op
-			// once resolved here).
-			if (this.#kittyGraphicsPendingId !== undefined && sequence.startsWith("\x1b_G")) {
-				const graphicsMatch = sequence.match(/^\x1b_G([^;]*);([\s\S]*?)\x1b\\$/u);
-				if (graphicsMatch) {
-					const idMatch = graphicsMatch[1]!.match(/(?:^|,)i=(\d+)(?:,|$)/);
-					const replyId = idMatch ? parseInt(idMatch[1]!, 10) : undefined;
-					if (replyId === this.#kittyGraphicsPendingId) {
-						this.#resolveKittyGraphicsTempFile(replyId, graphicsMatch[2]!.trim() === "OK");
-						return;
-					}
-				}
-			}
-
 			// Mode 2031 change notification: re-query OSC 11 with 100ms debounce
 			// (Neovim convention — coalesces rapid notifications during transitions)
 			const appearanceMatch = sequence.match(appearanceDsrPattern);
@@ -686,37 +658,6 @@ export class ProcessTerminal implements Terminal {
 		setOsc99Supported(supported);
 	}
 
-	#shouldQueryKittyGraphicsTempFile(): boolean {
-		if (TERMINAL.imageProtocol !== ImageProtocol.Kitty) return false;
-		// Honor the remote/explicit env gate, and skip when temp-file is already on.
-		if (!kittyTempFileAllowed() || getKittyGraphics().transmissionMedium === "temp-file") return false;
-		return !isBunTestRuntime() || $env.PI_TUI_KITTY_GRAPHICS_PROBE === "1";
-	}
-
-	#queryKittyGraphicsTempFile(): void {
-		this.#clearKittyGraphicsProbe();
-		if (this.#dead || !this.#shouldQueryKittyGraphicsTempFile()) return;
-
-		const id = nextKittyGraphicsProbeId++;
-		const probe = encodeKittyTempFileProbe(id);
-		if (!probe) return;
-		this.#kittyGraphicsPendingId = id;
-		this.#kittyGraphicsProbeCleanup = probe.cleanup;
-		this.#da1SentinelOwners.push({ kind: "kittyGraphicsProbe", id });
-		this.#safeWrite(`${probe.sequence}\x1b[c`);
-	}
-
-	#resolveKittyGraphicsTempFile(id: number, supported: boolean): void {
-		if (this.#kittyGraphicsPendingId !== id) return;
-		if (supported) setKittyGraphics({ transmissionMedium: "temp-file" });
-		this.#clearKittyGraphicsProbe();
-	}
-
-	#clearKittyGraphicsProbe(): void {
-		this.#kittyGraphicsPendingId = undefined;
-		this.#kittyGraphicsProbeCleanup?.();
-		this.#kittyGraphicsProbeCleanup = undefined;
-	}
 	/**
 	 * Parse an OSC 11 background color response and compute BT.601 luminance.
 	 * Handles 1-, 2-, 3-, and 4-digit XParseColor hex components.
@@ -965,7 +906,6 @@ export class ProcessTerminal implements Terminal {
 		this.#osc99ResponseBuffer = "";
 		this.#osc99Capabilities.clear();
 		setOsc99Supported(false);
-		this.#clearKittyGraphicsProbe();
 		this.#privateCsiResponseBuffer = "";
 		this.#da1SentinelOwners.length = 0;
 		this.#privateModeCallbacks = [];
diff --git a/packages/tui/test/image-budget.test.ts b/packages/tui/test/image-budget.test.ts
index 03d9cd9e9..608f9d6a4 100644
--- a/packages/tui/test/image-budget.test.ts
+++ b/packages/tui/test/image-budget.test.ts
@@ -259,7 +259,7 @@ describe("Image budget + Unicode placeholders", () => {
 		originalCellDims = { ...getCellDimensions() };
 		setCellDimensions({ widthPx: 10, heightPx: 10 });
 		terminal.imageProtocol = ImageProtocol.Kitty;
-		setKittyGraphics({ unicodePlaceholders: true, transmissionMedium: "direct" });
+		setKittyGraphics({ unicodePlaceholders: true });
 	});
 
 	afterEach(() => {
diff --git a/packages/tui/test/image-render.test.ts b/packages/tui/test/image-render.test.ts
index ce6cd2ad9..4358373a8 100644
--- a/packages/tui/test/image-render.test.ts
+++ b/packages/tui/test/image-render.test.ts
@@ -69,6 +69,18 @@ describe("terminal image rendering", () => {
 		expect(parseKittyParam(result?.sequence ?? "", "r")).toBe(10);
 	});
 
+	it("transmits stable Kitty images in-band before placement", () => {
+		terminal.imageProtocol = ImageProtocol.Kitty;
+		const result = renderImage(BASE64_ONE_PIXEL_PNG, SQUARE_DIMENSIONS, {
+			imageId: 42,
+			includeTransmit: true,
+		});
+
+		expect(result).not.toBeNull();
+		expect(result?.transmit).toBe(`\x1b_Ga=t,f=100,q=2,i=42;${BASE64_ONE_PIXEL_PNG}\x1b\\`);
+		expect(result?.transmit).not.toContain("t=t");
+	});
+
 	it("reduces iTerm2 width when max height is the limiting bound", () => {
 		terminal.imageProtocol = ImageProtocol.Iterm2;
 		const result = renderImage(BASE64_DUMMY, SQUARE_DIMENSIONS, {
diff --git a/packages/tui/test/kitty-graphics.test.ts b/packages/tui/test/kitty-graphics.test.ts
index b2e81fb6c..bab897e04 100644
--- a/packages/tui/test/kitty-graphics.test.ts
+++ b/packages/tui/test/kitty-graphics.test.ts
@@ -1,25 +1,17 @@
 import { afterEach, describe, expect, it } from "bun:test";
-import * as fs from "node:fs";
 import { visibleWidth } from "@oh-my-pi/pi-natives";
 import {
 	detectKittyUnicodePlaceholdersSupport,
 	encodeKittyPlaceholderGrid,
-	encodeKittyTempFileProbe,
-	encodeKittyTempFileTransmit,
 	encodeKittyVirtualPlacement,
 	getKittyGraphics,
-	isPngBase64,
 	KITTY_PLACEHOLDER,
 	KITTY_PLACEHOLDER_MAX_CELLS,
 	kittyPlaceholdersFit,
-	kittyTempFileAllowed,
 	renderKittyPlaceholderLines,
 	setKittyGraphics,
 } from "@oh-my-pi/pi-tui/kitty-graphics";
 
-const ONE_PIXEL_PNG =
-	"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
-
 const ORIGINAL = { ...getKittyGraphics() };
 
 afterEach(() => {
@@ -80,81 +72,12 @@ describe("kitty Unicode placeholder encoding", () => {
 	});
 });
 
-describe("kitty temp-file transmission", () => {
-	it("isPngBase64 recognizes PNG payloads only", () => {
-		expect(isPngBase64(ONE_PIXEL_PNG)).toBe(true);
-		expect(isPngBase64("/9j/4AAQSkZJRgABAQ")).toBe(false); // JPEG magic
-		expect(isPngBase64("")).toBe(false);
-	});
-
-	it("encodeKittyTempFileTransmit writes the bytes to a magic-named file and sends its path", () => {
-		const seq = encodeKittyTempFileTransmit(ONE_PIXEL_PNG, 12);
-		expect(seq).not.toBeNull();
-		const match = seq!.match(/^\x1b_Ga=t,f=100,t=t,S=(\d+),q=2,i=12;([^\x1b]+)\x1b\\$/);
-		expect(match).not.toBeNull();
-		const [, sizeRaw, encodedPath] = match!;
-		const filePath = Buffer.from(encodedPath!, "base64").toString("utf8");
-		// Kitty only deletes temp files whose path contains this substring.
-		expect(filePath).toContain("tty-graphics-protocol");
-		try {
-			const written = fs.readFileSync(filePath);
-			expect(written.equals(Buffer.from(ONE_PIXEL_PNG, "base64"))).toBe(true);
-			expect(Number(sizeRaw)).toBe(written.length);
-		} finally {
-			fs.rmSync(filePath, { force: true });
-		}
-	});
-
-	it("encodeKittyTempFileProbe builds an a=q,t=t query and cleans up its file", () => {
-		const probe = encodeKittyTempFileProbe(99);
-		expect(probe).not.toBeNull();
-		expect(probe!.sequence).toContain("\x1b_Ga=q,t=t,f=100,");
-		expect(probe!.sequence).toContain("i=99;");
-		const encodedPath = probe!.sequence.match(/;([^\x1b]+)\x1b\\$/)?.[1];
-		const filePath = Buffer.from(encodedPath!, "base64").toString("utf8");
-		expect(fs.existsSync(filePath)).toBe(true);
-		probe!.cleanup();
-		expect(fs.existsSync(filePath)).toBe(false);
-	});
-});
-
 describe("kitty graphics feature state", () => {
 	it("getKittyGraphics/setKittyGraphics round-trips overrides", () => {
-		setKittyGraphics({ unicodePlaceholders: false, transmissionMedium: "temp-file" });
-		expect(getKittyGraphics()).toEqual({ unicodePlaceholders: false, transmissionMedium: "temp-file" });
+		setKittyGraphics({ unicodePlaceholders: false });
+		expect(getKittyGraphics()).toEqual({ unicodePlaceholders: false });
 		setKittyGraphics({ unicodePlaceholders: true });
 		expect(getKittyGraphics().unicodePlaceholders).toBe(true);
-		expect(getKittyGraphics().transmissionMedium).toBe("temp-file");
-	});
-
-	it("kittyTempFileAllowed honors env force/off and the remote-session guard", () => {
-		const keys = ["PI_KITTY_IMAGE_TRANSMISSION", "SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"];
-		const saved: Record<string, string | undefined> = {};
-		for (const k of keys) saved[k] = Bun.env[k];
-		const restore = () => {
-			for (const k of keys) {
-				const v = saved[k];
-				if (v === undefined) delete Bun.env[k];
-				else Bun.env[k] = v;
-			}
-		};
-		try {
-			for (const k of keys) delete Bun.env[k];
-			// Auto + local session: allowed.
-			expect(kittyTempFileAllowed()).toBe(true);
-			// Auto + SSH session: not allowed.
-			Bun.env.SSH_CONNECTION = "1.2.3.4 5 6.7.8.9 22";
-			expect(kittyTempFileAllowed()).toBe(false);
-			// Explicit force overrides the remote guard.
-			Bun.env.PI_KITTY_IMAGE_TRANSMISSION = "temp-file";
-			expect(kittyTempFileAllowed()).toBe(true);
-			// Explicit off wins even on a local session.
-			delete Bun.env.SSH_CONNECTION;
-			Bun.env.PI_KITTY_IMAGE_TRANSMISSION = "direct";
-			expect(kittyTempFileAllowed()).toBe(false);
-		} finally {
-			restore();
-		}
 	});
 });
 
diff --git a/packages/tui/test/terminal-appearance.test.ts b/packages/tui/test/terminal-appearance.test.ts
index 03bd9bbee..88712e02c 100644
--- a/packages/tui/test/terminal-appearance.test.ts
+++ b/packages/tui/test/terminal-appearance.test.ts
@@ -1,14 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
-import { getKittyGraphics, type KittyGraphicsFeatures, setKittyGraphics } from "@oh-my-pi/pi-tui/kitty-graphics";
 import { ProcessTerminal } from "@oh-my-pi/pi-tui/terminal";
 import {
 	type CellDimensions,
 	getCellDimensions,
 	getTerminalInfo,
-	ImageProtocol,
 	setCellDimensions,
-	setTerminalImageProtocol,
-	TERMINAL,
 } from "@oh-my-pi/pi-tui/terminal-capabilities";
 
 const stdinIsTtyDescriptor = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
@@ -618,70 +614,6 @@ describe("ProcessTerminal DECRQM + in-band resize (DEC 2026/2048)", () => {
 	});
 });
 
-describe("ProcessTerminal Kitty graphics temp-file probe", () => {
-	const originalProtocol = TERMINAL.imageProtocol;
-	let originalGraphics: KittyGraphicsFeatures;
-
-	beforeEach(() => {
-		Object.defineProperty(process.stdin, "isTTY", { value: true, configurable: true });
-		Object.defineProperty(process.stdout, "isTTY", { value: true, configurable: true });
-		Object.defineProperty(process.stdin, "setRawMode", { value: vi.fn(), configurable: true });
-		originalGraphics = { ...getKittyGraphics() };
-		Bun.env.PI_TUI_KITTY_GRAPHICS_PROBE = "1";
-		setTerminalImageProtocol(ImageProtocol.Kitty);
-		setKittyGraphics({ transmissionMedium: "direct" });
-	});
-
-	afterEach(() => {
-		vi.restoreAllMocks();
-		restoreProperty(process.stdin, "isTTY", stdinIsTtyDescriptor);
-		restoreProperty(process.stdout, "isTTY", stdoutIsTtyDescriptor);
-		restoreProperty(process.stdin, "setRawMode", stdinSetRawModeDescriptor);
-		delete Bun.env.PI_TUI_KITTY_GRAPHICS_PROBE;
-		setTerminalImageProtocol(originalProtocol);
-		setKittyGraphics(originalGraphics);
-	});
-
-	function startProbed() {
-		const writes: string[] = [];
-		vi.spyOn(process, "kill").mockReturnValue(true);
-		vi.spyOn(process.stdin, "resume").mockImplementation(() => process.stdin);
-		vi.spyOn(process.stdin, "pause").mockImplementation(() => process.stdin);
-		vi.spyOn(process.stdin, "setEncoding").mockImplementation(() => process.stdin);
-		vi.spyOn(process.stdout, "write").mockImplementation(chunk => {
-			writes.push(typeof chunk === "string" ? chunk : chunk.toString());
-			return true;
-		});
-		const terminal = new ProcessTerminal();
-		terminal.start(
-			() => {},
-			() => {},
-		);
-		return { terminal, writes };
-	}
-
-	it("emits an a=q,t=t probe and promotes to temp-file transmission on OK", () => {
-		const { terminal, writes } = startProbed();
-		const probe = writes.find(w => w.includes("\x1b_Ga=q,t=t"));
-		expect(probe).toBeDefined();
-		const id = probe?.match(/i=(\d+)/)?.[1];
-		expect(id).toBeDefined();
-		expect(getKittyGraphics().transmissionMedium).toBe("direct");
-		process.stdin.emit("data", `\x1b_Gi=${id};OK\x1b\\`);
-		expect(getKittyGraphics().transmissionMedium).toBe("temp-file");
-		terminal.stop();
-	});
-
-	it("stays on direct transmission when the probe reports an error", () => {
-		const { terminal, writes } = startProbed();
-		const id = writes.find(w => w.includes("\x1b_Ga=q,t=t"))?.match(/i=(\d+)/)?.[1];
-		expect(id).toBeDefined();
-		process.stdin.emit("data", `\x1b_Gi=${id};ENOTSUP:bad\x1b\\`);
-		expect(getKittyGraphics().transmissionMedium).toBe("direct");
-		terminal.stop();
-	});
-});
-
 describe("OSC 66 text-sizing capability", () => {
 	it("advertises text sizing only for Kitty", () => {
 		// OSC 66 is a Kitty-only protocol; any other terminal must report the

From 0f19d9f271229d5943b7d6ba2cc33936f308ca72 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 04:29:21 +0200
Subject: [PATCH 084/181] fix(tui): forced immediate repaint on terminal resize

- Bypassed throttled render so resize replays at fresh geometry.
- Avoided racing the terminal reflow with a coalesced frame.
---
 packages/tui/CHANGELOG.md | 6 ++++++
 packages/tui/src/tui.ts   | 6 +++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 412067f39..8183b6b00 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -1,11 +1,17 @@
 # Changelog
 
 ## [Unreleased]
+### Breaking Changes
+
+- Removed Kitty temp-file image transmission, its startup support probe, the `PI_KITTY_IMAGE_TRANSMISSION` override, and the temp-file helper exports. Kitty/Ghostty image payloads now stay on in-band base64 before placeholder/direct placement, avoiding blank first renders from temp-file load races.
+
 ### Added
 
 - Added an optional `dispose()` lifecycle method to `Component` so components can release timers and subscriptions during permanent teardown
 - Added `Container.dispose()` to propagate teardown to child components when a component tree is permanently discarded
 - Added `Loader.dispose()` to stop the loader animation timer when the component is disposed
+- Added a `ScrollView` `ellipsis` option (defaults to `Ellipsis.Unicode`) so callers that pre-wrap content to width can pass `Ellipsis.Omit` and suppress the stray per-line `…` that lands on trailing padding.
+- Added `ScrollView.handleScrollKey()` plus a `fastScrollLines` option so every scroll view gets shared navigation keys, including Shift+Arrow to scroll faster.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 4b35fc3d5..eda1f4854 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -778,8 +778,12 @@ export class TUI extends Container {
 		this.terminal.start(
 			data => this.#handleInput(data),
 			() => {
+				// Repaint immediately rather than via the throttled path: a resize must
+				// clear and replay at the fresh geometry before the terminal's reflow
+				// settles into a state a throttled frame would race. Forced render skips
+				// the 16ms coalescing window, matching resetDisplay()'s prompt repaint.
 				this.#resizeEventPending = true;
-				this.requestRender();
+				this.requestRender(true);
 			},
 		);
 		this.terminal.hideCursor();

From fceff5e6b65d5038edca42321781a07b0cd68934 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 04:30:29 +0200
Subject: [PATCH 085/181] feat(coding-agent): overhauled plan-review overlay
 with TOC sidebar

- Added section-based plan parsing with per-section delete, undo, and annotate.
- Added Tab/Shift+Tab focus regions and per-line scroll navigation.
- Added Refine feedback loop emitting annotations back to the model.
- Added `OverlayOptions.fullscreen` borrowing the terminal's alt screen buffer.
---
 packages/coding-agent/CHANGELOG.md            |   2 +-
 .../src/modes/components/overlay-box.ts       |  55 ++
 .../modes/components/plan-review-overlay.ts   | 607 ++++++++++++++++--
 .../src/modes/components/plan-toc.ts          | 138 ++++
 .../src/modes/interactive-mode.ts             |  45 +-
 .../test/interactive-mode-plan-review.test.ts |  95 +++
 .../components/plan-review-overlay.test.ts    | 199 ++++++
 .../test/modes/components/plan-toc.test.ts    |  91 +++
 packages/tui/CHANGELOG.md                     |   1 +
 packages/tui/src/tui.ts                       | 113 ++++
 packages/tui/test/render-regressions.test.ts  |  73 +++
 11 files changed, 1339 insertions(+), 80 deletions(-)
 create mode 100644 packages/coding-agent/src/modes/components/plan-toc.ts
 create mode 100644 packages/coding-agent/test/modes/components/plan-toc.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index bfd13ffe7..83325513c 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -11,7 +11,7 @@
 
 - Changed non-agent API operations (title and commit-message generation) to use session-aware API key resolution with refresh-first auth retries, refreshing the active credential before rotating to another account
 - Changed the directory grouping for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics from a single flat `# dir/` heading per immediate directory to a multi-level tree that folds the common path prefix into one heading. Previously every group repeated the full directory path — so results rooted outside cwd printed the absolute prefix (e.g. `/Users/me/proj/`) on every heading and nested directories were never collapsed. Now a single-child directory chain folds into one heading (`# packages/pkg/src/`, including an absolute root for out-of-cwd results), subdirectories nest one `#` deeper (`## nested/` → `### child.ts`), and each directory's own files are listed before its subdirectories. TUI hyperlink reconstruction tracks the nested directory stack across the whole output so file and code-frame links keep resolving to the correct absolute paths.
-- Changed the plan-mode approval surface from an inline transcript block plus a separate bottom selector into a single fullscreen overlay (like `/copy`). The overlay owns its entire content via `ScrollView`: the plan renders once as Markdown and scrolls inside the outlined box (PageUp/PageDown, g/G), with the approval options and the model-tier slider beneath it. ↑/↓ move the option cursor, ←/→ drive the slider, Enter confirms, the external-editor key opens the plan, and Esc cancels — so a tall plan no longer competes with the selector for vertical space or clips its head on ED3-risk terminals.
+- Changed the plan-mode approval surface from an inline transcript block plus a separate bottom selector into a single fullscreen overlay (like `/copy`) and overhauled its navigation. The overlay now renders the plan per-section through `ScrollView` (line-level ↑/↓ scroll, Shift+↑/↓ to scroll faster, PgUp/PgDn, g/G) with no stray per-line `…`, and — when the terminal is wide enough and the plan has ≥2 headings — shows a compact VS Code-style Contents sidebar (the redundant plan-title heading is omitted). Focus moves between regions with Tab/Shift+Tab (and flows at the edges: Down past the last section or the bottom of the body drops into the approval options; Up steps back), while the sidebar glows to track the scrolled section. The sidebar can fast-jump between sections, delete a section (with `u` undo), and annotate sections with feedback (`a`) that is submitted back to the model when the operator picks "Refine plan"; ←/→ always drive the model-tier slider, Enter confirms, the external-editor key opens the plan, and Esc cancels. The overlay borrows the terminal's alternate screen buffer for its lifetime (`fullscreen` overlay), so the transcript stays put on the normal screen instead of bleeding through scrollback behind the modal.
 - Changed the interactive controllers (command, MCP, selector, extension-UI, event), debug panels, and the status/error/warning helpers to render chat output through `ctx.present(...)` instead of appending to `chatContainer` and calling `ui.requestRender()` directly; transcript rebuilds dispose live blocks via `ctx.resetTranscript()` so animated blocks' timers stop on reset.
 
 ### Fixed
diff --git a/packages/coding-agent/src/modes/components/overlay-box.ts b/packages/coding-agent/src/modes/components/overlay-box.ts
index 52b9f2dc0..e427e6a25 100644
--- a/packages/coding-agent/src/modes/components/overlay-box.ts
+++ b/packages/coding-agent/src/modes/components/overlay-box.ts
@@ -51,3 +51,58 @@ export function row(content: string, width: number): string {
 	const box = theme.boxSharp;
 	return `${paint(box.vertical)} ${fit(content, Math.max(0, width - 4))} ${paint(box.vertical)}`;
 }
+
+/**
+ * Column index (0-based) of the inner divider for a two-column layout whose
+ * sidebar content area is `sidebarWidth` columns wide. The layout is
+ * `│ sidebar │ body │` with a single-column inset on every side, so the divider
+ * vertical sits at `sidebarWidth + 3` and the body content area is
+ * {@link splitBodyWidth} columns.
+ */
+function splitDividerCol(sidebarWidth: number): number {
+	return sidebarWidth + 3;
+}
+
+/** Body content width for a two-column overlay of total `width`. */
+export function splitBodyWidth(width: number, sidebarWidth: number): number {
+	return Math.max(0, width - sidebarWidth - 7);
+}
+
+/** Top border carrying the title, split by a `┬` over the column divider. */
+export function topBorderSplit(width: number, title: string, sidebarWidth: number): string {
+	const box = theme.boxSharp;
+	const dividerCol = splitDividerCol(sidebarWidth);
+	const leftLen = Math.max(0, dividerCol - 1);
+	const rightLen = Math.max(0, width - 2 - dividerCol);
+	let left: string;
+	if (!title) {
+		left = paint(box.topLeft + box.horizontal.repeat(leftLen));
+	} else {
+		const shown = truncateToWidth(` ${title} `, Math.max(0, leftLen - 1));
+		const fillWidth = Math.max(0, leftLen - 1 - visibleWidth(shown));
+		left =
+			paint(box.topLeft + box.horizontal) +
+			theme.bold(theme.fg("accent", shown)) +
+			paint(box.horizontal.repeat(fillWidth));
+	}
+	return left + paint(box.teeDown + box.horizontal.repeat(rightLen) + box.topRight);
+}
+
+/** Section rule that closes the sidebar column with a `┴` over the divider. */
+export function dividerSplit(width: number, sidebarWidth: number): string {
+	const box = theme.boxSharp;
+	const dividerCol = splitDividerCol(sidebarWidth);
+	const leftLen = Math.max(0, dividerCol - 1);
+	const rightLen = Math.max(0, width - 2 - dividerCol);
+	return paint(
+		box.teeRight + box.horizontal.repeat(leftLen) + box.teeUp + box.horizontal.repeat(rightLen) + box.teeLeft,
+	);
+}
+
+/** A two-column content row: `│ sidebar │ body │`, each inset by one column. */
+export function splitRow(sidebar: string, body: string, width: number, sidebarWidth: number): string {
+	const box = theme.boxSharp;
+	const bodyWidth = splitBodyWidth(width, sidebarWidth);
+	const bar = paint(box.vertical);
+	return `${bar} ${fit(sidebar, sidebarWidth)} ${bar} ${fit(body, bodyWidth)} ${bar}`;
+}
diff --git a/packages/coding-agent/src/modes/components/plan-review-overlay.ts b/packages/coding-agent/src/modes/components/plan-review-overlay.ts
index 59b7e7fb5..e3f7d6292 100644
--- a/packages/coding-agent/src/modes/components/plan-review-overlay.ts
+++ b/packages/coding-agent/src/modes/components/plan-review-overlay.ts
@@ -1,35 +1,78 @@
 /**
- * Fullscreen plan-review overlay. Replaces the old inline `PlanReviewBlock`
- * (which lived in the transcript and competed with the approval selector for
- * vertical space, clipping tall plans). The overlay owns its entire content: the
- * plan is rendered once via {@link Markdown} and windowed through a
- * {@link ScrollView}, while the approval options (plus the optional model-tier
- * slider) sit beneath it inside the same outlined box — one self-contained
- * surface in the spirit of the `/copy` picker.
+ * Fullscreen plan-review overlay. The overlay owns its entire content: the plan
+ * is split into sections (preamble + one per heading), each rendered through its
+ * own {@link Markdown} and windowed by a {@link ScrollView}, while the approval
+ * options (plus the optional model-tier slider) sit beneath inside the same
+ * outlined box — one self-contained surface in the spirit of the `/copy` picker.
  *
- * Key map mirrors the plan-mode hook selector so muscle memory carries over:
- * ↑/↓ (j/k) move the option cursor, ←/→ (h/l) drive the slider, Enter confirms,
- * Esc cancels, and the external-editor key opens the plan. PageUp/PageDown and
- * g/G scroll the plan body.
+ * When the terminal is wide enough and the plan has ≥2 headings, a Contents
+ * sidebar appears: it tracks the scrolled section with an accent "glow", and —
+ * when focused — lets the operator jump between sections, delete a section
+ * (with undo), and annotate sections with feedback that feeds the Refine loop.
+ *
+ * Focus regions (`toc`/`body`/`actions`) cycle with Tab/Shift+Tab; arrows move
+ * within the focused region and step left into the sidebar. The default focus is
+ * `actions`, so the muscle memory of the old single-target overlay carries over:
+ * ↑/↓ select options, Enter confirms, ←/→ drives the slider when there is no
+ * sidebar, g/G + PgUp/PgDn scroll, and the external-editor key opens the plan.
  */
-import { type Component, Markdown, type MarkdownTheme, matchesKey, ScrollView } from "@oh-my-pi/pi-tui";
+import {
+	type Component,
+	Ellipsis,
+	Input,
+	Markdown,
+	type MarkdownTheme,
+	matchesKey,
+	ScrollView,
+	truncateToWidth,
+	visibleWidth,
+} from "@oh-my-pi/pi-tui";
 import { getMarkdownTheme, theme } from "../theme/theme";
 import {
 	matchesAppExternalEditor,
 	matchesSelectCancel,
 	matchesSelectDown,
-	matchesSelectPageDown,
-	matchesSelectPageUp,
 	matchesSelectUp,
 } from "../utils/keybinding-matchers";
 import type { HookSelectorSlider } from "./hook-selector";
-import { bottomBorder, divider, row, topBorder } from "./overlay-box";
+import {
+	bottomBorder,
+	divider,
+	dividerSplit,
+	fit,
+	row,
+	splitBodyWidth,
+	splitRow,
+	topBorder,
+	topBorderSplit,
+} from "./overlay-box";
+import { joinPlanSections, parsePlanSections, sectionDeletionSpan } from "./plan-toc";
 import { renderSegmentTrack } from "./segment-track";
 
 /** Title shown in the overlay's top border. */
 const OVERLAY_TITLE = "Plan Review";
 /** Minimum plan-body rows kept visible even on short terminals. */
 const MIN_BODY_ROWS = 3;
+/** Sidebar gates: enough headings, a wide terminal, and a usable body column. */
+const SIDEBAR_MIN_HEADINGS = 2;
+const SIDEBAR_MIN_TOTAL_WIDTH = 64;
+const SIDEBAR_MIN_BODY_WIDTH = 40;
+
+type Focus = "toc" | "body" | "actions";
+
+interface OverlaySection {
+	level: number;
+	title: string;
+	raw: string;
+	md: Markdown;
+	annotations: string[];
+}
+
+/** Undo snapshot: the joined plan text plus annotations aligned by section. */
+interface UndoEntry {
+	text: string;
+	annotations: string[][];
+}
 
 export interface PlanReviewOverlayCallbacks {
 	/** Invoked with the chosen option label (never a disabled one). */
@@ -38,6 +81,10 @@ export interface PlanReviewOverlayCallbacks {
 	onCancel: () => void;
 	/** Invoked when the external-editor key is pressed (overlay stays open). */
 	onExternalEditor?: () => void;
+	/** Invoked with the new full plan text after an in-overlay delete/undo. */
+	onPlanEdited?: (content: string) => void;
+	/** Invoked with the Refine feedback markdown whenever annotations change. */
+	onFeedbackChange?: (feedback: string) => void;
 }
 
 export interface PlanReviewOverlayOptions {
@@ -46,46 +93,64 @@ export interface PlanReviewOverlayOptions {
 	options: string[];
 	/** Indices into `options` that render dimmed and cannot be selected. */
 	disabledIndices?: number[];
-	/** Footer hint line; falls back to a generic nav hint when omitted. */
+	/** Trailing footer hint (cancel hint); the overlay prepends dynamic help. */
 	helpText?: string;
 	/** Initially highlighted option index. */
 	initialIndex?: number;
 	/** Optional model-tier slider rendered between the plan body and options. */
 	slider?: HookSelectorSlider;
+	/** Display label for the external-editor key, surfaced in the footer help. */
+	externalEditorLabel?: string;
 }
 
-/** Default footer hint when the caller supplies none. */
-const DEFAULT_HELP = "up/down select  enter confirm  pgup/pgdn scroll  esc cancel";
+/** Default trailing footer hint when the caller supplies none. */
+const DEFAULT_HELP_SUFFIX = "esc cancel";
 
 export class PlanReviewOverlay implements Component {
-	#md: Markdown;
 	#mdTheme: MarkdownTheme;
 	#scrollView: ScrollView;
+	#sections: OverlaySection[] = [];
+	#toc: number[] = [];
+	/** Shallowest level among ToC entries, used to flatten indentation. */
+	#tocBaseLevel = 1;
+	#sectionOffsets: number[] = [];
+	#undo: UndoEntry[] = [];
+
 	#options: string[];
 	#disabled: Set<number>;
-	#helpText: string;
+	#helpSuffix: string;
+	#externalEditorLabel: string | undefined;
 	#promptTitle: string | undefined;
 	#selectedIndex: number;
 	#slider: HookSelectorSlider | undefined;
 	#sliderIndex: number;
 
+	#focus: Focus = "actions";
+	#tocCursor = 0;
+	#sidebarShown = false;
+	#pendingScrollToToc = false;
+
+	#annotating = false;
+	#input: Input;
+
 	constructor(
 		planContent: string,
 		options: PlanReviewOverlayOptions,
 		private readonly callbacks: PlanReviewOverlayCallbacks,
 	) {
 		this.#mdTheme = getMarkdownTheme();
-		this.#md = new Markdown(planContent, 1, 0, this.#mdTheme);
 		this.#scrollView = new ScrollView([], {
 			height: MIN_BODY_ROWS,
 			scrollbar: "auto",
+			ellipsis: Ellipsis.Omit,
 			theme: { track: t => theme.fg("dim", t), thumb: t => theme.fg("accent", t) },
 		});
 		this.#options = options.options;
 		this.#disabled = new Set(
 			(options.disabledIndices ?? []).filter(i => Number.isInteger(i) && i >= 0 && i < this.#options.length),
 		);
-		this.#helpText = options.helpText ?? DEFAULT_HELP;
+		this.#helpSuffix = options.helpText ?? DEFAULT_HELP_SUFFIX;
+		this.#externalEditorLabel = options.externalEditorLabel;
 		this.#promptTitle = options.promptTitle;
 		this.#selectedIndex = this.#coerceIndex(options.initialIndex ?? 0);
 		if (options.slider && options.slider.segments.length > 0) {
@@ -94,17 +159,54 @@ export class PlanReviewOverlay implements Component {
 		} else {
 			this.#sliderIndex = 0;
 		}
+		this.#input = new Input();
+		this.#input.setUseTerminalCursor(false);
+		this.#input.onSubmit = value => this.#submitAnnotation(value);
+		this.#input.onEscape = () => this.#exitAnnotate();
+		this.#setSections(planContent);
 	}
 
 	invalidate(): void {
-		this.#md.invalidate();
+		for (const section of this.#sections) section.md.invalidate();
 	}
 
 	/** Swap the displayed plan (e.g. after an external-editor round-trip) and
-	 *  reset the scroll position so the operator starts at the top. */
+	 *  reset scroll/focus so the operator starts at the top. Does not emit
+	 *  `onPlanEdited` (the editor round-trip already persisted the file). */
 	setPlanContent(planContent: string): void {
-		this.#md.setText(planContent);
+		this.#setSections(planContent);
 		this.#scrollView.scrollToTop();
+		this.#tocCursor = 0;
+		this.#recomputeFeedback();
+	}
+
+	#setSections(planContent: string): void {
+		this.#sections = parsePlanSections(planContent).map(section => ({
+			level: section.level,
+			title: section.title,
+			raw: section.raw,
+			md: new Markdown(section.raw, 1, 0, this.#mdTheme),
+			annotations: [] as string[],
+		}));
+		this.#rebuildToc();
+		this.#tocCursor = Math.min(this.#tocCursor, Math.max(0, this.#toc.length - 1));
+	}
+
+	#rebuildToc(): void {
+		const headings: number[] = [];
+		for (let i = 0; i < this.#sections.length; i++) {
+			if (this.#sections[i]!.level >= 1) headings.push(i);
+		}
+		// Drop the plan's title from the ToC: a single shallowest heading at the
+		// top of the document is the plan name itself ("we know it's the plan"),
+		// so listing it adds noise. Plans with several top-level sections keep
+		// them all.
+		let minLevel = Number.POSITIVE_INFINITY;
+		for (const i of headings) minLevel = Math.min(minLevel, this.#sections[i]!.level);
+		const topLevel = headings.filter(i => this.#sections[i]!.level === minLevel);
+		const titleIndex = topLevel.length === 1 && headings[0] === topLevel[0] ? topLevel[0] : -1;
+		this.#toc = headings.filter(i => i !== titleIndex);
+		this.#tocBaseLevel = this.#toc.length > 0 ? Math.min(...this.#toc.map(i => this.#sections[i]!.level)) : 1;
 	}
 
 	/** Clamp `index` to range, then walk to the nearest enabled option so the
@@ -119,6 +221,12 @@ export class PlanReviewOverlay implements Component {
 		return clamped;
 	}
 
+	/** First enabled option index (or -1 when none), used to detect the "top". */
+	#firstEnabledIndex(): number {
+		for (let i = 0; i < this.#options.length; i++) if (!this.#disabled.has(i)) return i;
+		return -1;
+	}
+
 	/** Move the option cursor by `delta`, skipping disabled rows, stopping at the
 	 *  list edge. */
 	#moveSelection(delta: number): void {
@@ -136,6 +244,7 @@ export class PlanReviewOverlay implements Component {
 		}
 	}
 
+	/** Step the slider by `delta`, clamped to its edges (narrow-terminal mode). */
 	#moveSlider(delta: number): void {
 		const slider = this.#slider;
 		if (!slider) return;
@@ -145,35 +254,269 @@ export class PlanReviewOverlay implements Component {
 		slider.onChange?.(next);
 	}
 
+	#confirmSelection(): void {
+		const index = this.#selectedIndex;
+		if (index >= 0 && index < this.#options.length && !this.#disabled.has(index)) {
+			this.callbacks.onPick(this.#options[index]!);
+		}
+	}
+
 	handleInput(keyData: string): void {
+		if (this.#annotating) {
+			this.#input.handleInput(keyData);
+			return;
+		}
 		if (matchesSelectCancel(keyData)) {
 			this.callbacks.onCancel();
 			return;
 		}
-		if (matchesSelectUp(keyData) || keyData === "k") {
-			this.#moveSelection(-1);
-		} else if (matchesSelectDown(keyData) || keyData === "j") {
-			this.#moveSelection(1);
-		} else if (matchesKey(keyData, "left") || (this.#slider && keyData === "h")) {
-			this.#moveSlider(-1);
-		} else if (matchesKey(keyData, "right") || (this.#slider && keyData === "l")) {
-			this.#moveSlider(1);
-		} else if (matchesKey(keyData, "enter") || matchesKey(keyData, "return") || keyData === "\n") {
-			const index = this.#selectedIndex;
-			if (index >= 0 && index < this.#options.length && !this.#disabled.has(index)) {
-				this.callbacks.onPick(this.#options[index]!);
-			}
-		} else if (matchesSelectPageUp(keyData) || matchesKey(keyData, "pageUp")) {
-			this.#scrollView.page(-1);
-		} else if (matchesSelectPageDown(keyData) || matchesKey(keyData, "pageDown")) {
-			this.#scrollView.page(1);
-		} else if (keyData === "g") {
-			this.#scrollView.scrollToTop();
-		} else if (keyData === "G") {
-			this.#scrollView.scrollToBottom();
-		} else if (this.callbacks.onExternalEditor && matchesAppExternalEditor(keyData)) {
+		if (this.callbacks.onExternalEditor && matchesAppExternalEditor(keyData)) {
 			this.callbacks.onExternalEditor();
+			return;
 		}
+		if (matchesKey(keyData, "tab") || keyData === "\t") {
+			this.#cycleRegion(1);
+			return;
+		}
+		if (matchesKey(keyData, "shift+tab") || keyData === "\x1b[Z") {
+			this.#cycleRegion(-1);
+			return;
+		}
+		switch (this.#focus) {
+			case "actions":
+				this.#handleActions(keyData);
+				return;
+			case "body":
+				this.#handleBody(keyData);
+				return;
+			case "toc":
+				this.#handleToc(keyData);
+				return;
+		}
+	}
+
+	#cycleRegion(direction: number): void {
+		// Sidebar is skipped from the cycle when it is not shown.
+		const regions: Focus[] = this.#sidebarShown ? ["toc", "body", "actions"] : ["body", "actions"];
+		const current = regions.indexOf(this.#focus);
+		const base = current < 0 ? regions.length - 1 : current;
+		this.#setFocus(regions[(base + direction + regions.length) % regions.length]!);
+	}
+
+	#setFocus(focus: Focus): void {
+		this.#focus = focus;
+		if (focus === "toc") this.#tocCursor = this.#deriveTocCursorFromScroll();
+	}
+
+	#handleActions(data: string): void {
+		// Left/right always drive the slider. The sidebar sits beside the body
+		// (above this row), not the slider, so stealing left for it would strand
+		// the operator unable to step the model tier back — reach the ToC via Tab.
+		const isLeft = matchesKey(data, "left") || (this.#slider !== undefined && data === "h");
+		const isRight = matchesKey(data, "right") || (this.#slider !== undefined && data === "l");
+		if (isLeft) {
+			this.#moveSlider(-1);
+			return;
+		}
+		if (isRight) {
+			this.#moveSlider(1);
+			return;
+		}
+		if (matchesSelectUp(data) || data === "k") {
+			if (this.#selectedIndex === this.#firstEnabledIndex()) this.#setFocus("body");
+			else this.#moveSelection(-1);
+			return;
+		}
+		if (matchesSelectDown(data) || data === "j") {
+			this.#moveSelection(1);
+			return;
+		}
+		if (matchesKey(data, "enter") || matchesKey(data, "return") || data === "\n") {
+			this.#confirmSelection();
+			return;
+		}
+		this.#handleBodyScroll(data);
+	}
+
+	#handleBody(data: string): void {
+		if (matchesKey(data, "left") || data === "h") {
+			if (this.#sidebarShown) this.#setFocus("toc");
+			return;
+		}
+		if (
+			matchesKey(data, "right") ||
+			data === "l" ||
+			matchesKey(data, "enter") ||
+			matchesKey(data, "return") ||
+			data === "\n"
+		) {
+			this.#setFocus("actions");
+			return;
+		}
+		// Vertical nav flows between regions at the edges: scrolling off the bottom
+		// drops into the actions ("next step"); scrolling off the top steps back up
+		// to the ToC.
+		if (matchesSelectUp(data) || data === "k") {
+			if (this.#scrollView.getScrollOffset() <= 0 && this.#sidebarShown) this.#setFocus("toc");
+			else this.#scrollView.scroll(-1);
+			return;
+		}
+		if (matchesSelectDown(data) || data === "j") {
+			if (this.#scrollView.getScrollOffset() >= this.#scrollView.getMaxScrollOffset()) this.#setFocus("actions");
+			else this.#scrollView.scroll(1);
+			return;
+		}
+		this.#handleBodyScroll(data);
+	}
+
+	/**
+	 * Shared scroll dispatch for body + actions focus. Delegates standard keys
+	 * (Arrows, Shift+Arrow fast-scroll, PgUp/PgDn, Home/End) to the ScrollView,
+	 * then adds the vim g/G jumps. Plain Arrow/k/j are consumed by the callers
+	 * before this runs, so here it only ever sees the paging/fast keys.
+	 */
+	#handleBodyScroll(data: string): void {
+		if (this.#scrollView.handleScrollKey(data)) return;
+		if (data === "g") this.#scrollView.scrollToTop();
+		else if (data === "G") this.#scrollView.scrollToBottom();
+	}
+
+	#handleToc(data: string): void {
+		if (matchesSelectUp(data) || data === "k") {
+			this.#moveTocCursor(-1);
+			return;
+		}
+		if (matchesSelectDown(data) || data === "j") {
+			// Past the last section, fall through to the actions ("next step").
+			if (this.#tocCursor >= this.#toc.length - 1) this.#setFocus("actions");
+			else this.#moveTocCursor(1);
+			return;
+		}
+		if (
+			matchesKey(data, "right") ||
+			data === "l" ||
+			matchesKey(data, "enter") ||
+			matchesKey(data, "return") ||
+			data === "\n"
+		) {
+			this.#setFocus("body");
+			return;
+		}
+		if (data === "d" || matchesKey(data, "delete")) {
+			this.#deleteSelectedSection();
+			return;
+		}
+		if (data === "a") {
+			this.#startAnnotate();
+			return;
+		}
+		if (data === "u") {
+			this.#undoLast();
+			return;
+		}
+	}
+
+	#moveTocCursor(delta: number): void {
+		if (this.#toc.length === 0) return;
+		const next = Math.max(0, Math.min(this.#toc.length - 1, this.#tocCursor + delta));
+		if (next === this.#tocCursor) return;
+		this.#tocCursor = next;
+		this.#scrubBodyToToc();
+	}
+
+	/** Scroll the body so the selected ToC section's heading sits at the top. */
+	#scrubBodyToToc(): void {
+		const sectionIndex = this.#toc[this.#tocCursor];
+		if (sectionIndex === undefined) return;
+		const offset = this.#sectionOffsets[sectionIndex];
+		if (offset !== undefined) this.#scrollView.setScrollOffset(offset);
+	}
+
+	/** Greatest ToC position whose section starts at or above the scroll offset. */
+	#deriveTocCursorFromScroll(): number {
+		if (this.#toc.length === 0) return 0;
+		const scrollOffset = this.#scrollView.getScrollOffset();
+		let current = 0;
+		for (let i = 0; i < this.#sections.length; i++) {
+			if ((this.#sectionOffsets[i] ?? 0) <= scrollOffset) current = i;
+			else break;
+		}
+		let pos = 0;
+		for (let p = 0; p < this.#toc.length; p++) {
+			if (this.#toc[p]! <= current) pos = p;
+			else break;
+		}
+		return pos;
+	}
+
+	#pushUndo(): void {
+		this.#undo.push({
+			text: joinPlanSections(this.#sections),
+			annotations: this.#sections.map(section => [...section.annotations]),
+		});
+	}
+
+	#deleteSelectedSection(): void {
+		const sectionIndex = this.#toc[this.#tocCursor];
+		if (sectionIndex === undefined) return;
+		const span = sectionDeletionSpan(this.#sections, sectionIndex);
+		if (span.length === 0) return;
+		this.#pushUndo();
+		for (let i = span.length - 1; i >= 0; i--) this.#sections.splice(span[i]!, 1);
+		this.#rebuildToc();
+		this.#tocCursor = Math.min(this.#tocCursor, Math.max(0, this.#toc.length - 1));
+		this.#pendingScrollToToc = true;
+		this.callbacks.onPlanEdited?.(joinPlanSections(this.#sections));
+		this.#recomputeFeedback();
+	}
+
+	#undoLast(): void {
+		const entry = this.#undo.pop();
+		if (!entry) return;
+		this.#setSections(entry.text);
+		for (let i = 0; i < this.#sections.length; i++) {
+			this.#sections[i]!.annotations = entry.annotations[i] ? [...entry.annotations[i]!] : [];
+		}
+		this.#tocCursor = Math.min(this.#tocCursor, Math.max(0, this.#toc.length - 1));
+		this.#pendingScrollToToc = true;
+		this.callbacks.onPlanEdited?.(joinPlanSections(this.#sections));
+		this.#recomputeFeedback();
+	}
+
+	#startAnnotate(): void {
+		if (this.#toc[this.#tocCursor] === undefined) return;
+		this.#annotating = true;
+		this.#input.setValue("");
+	}
+
+	#submitAnnotation(value: string): void {
+		this.#annotating = false;
+		const note = value.trim();
+		const sectionIndex = this.#toc[this.#tocCursor];
+		if (note && sectionIndex !== undefined) {
+			this.#pushUndo();
+			this.#sections[sectionIndex]!.annotations.push(note);
+			this.#recomputeFeedback();
+		}
+		this.#input.setValue("");
+	}
+
+	#exitAnnotate(): void {
+		this.#annotating = false;
+		this.#input.setValue("");
+	}
+
+	#recomputeFeedback(): void {
+		const annotated = this.#sections.filter(section => section.level >= 1 && section.annotations.length > 0);
+		let feedback = "";
+		if (annotated.length > 0) {
+			feedback = "Refinement feedback on the plan:\n";
+			for (const section of annotated) {
+				feedback += `\n## ${section.title}\n`;
+				for (const note of section.annotations) feedback += `- ${note}\n`;
+			}
+		}
+		this.callbacks.onFeedbackChange?.(feedback);
 	}
 
 	#renderSliderLines(): string[] {
@@ -191,47 +534,173 @@ export class PlanReviewOverlay implements Component {
 	}
 
 	#renderOptionLines(): string[] {
+		const active = this.#focus === "actions";
 		return this.#options.map((label, i) => {
-			const isSelected = i === this.#selectedIndex;
+			const selected = i === this.#selectedIndex;
 			const isDisabled = this.#disabled.has(i);
-			const cursor = isSelected ? theme.fg("accent", `${theme.nav.cursor} `) : "  ";
+			// The cursor marks the selected option; it dims when actions are not the
+			// focused region so the active region's highlight stays unambiguous.
+			const cursor = selected ? theme.fg(active ? "accent" : "dim", `${theme.nav.cursor} `) : "  ";
 			const text = isDisabled
 				? theme.fg("dim", label)
-				: isSelected
+				: selected && active
 					? theme.bold(theme.fg("accent", label))
 					: theme.fg("text", label);
 			return cursor + text;
 		});
 	}
 
+	#buildHelp(): string {
+		const sep = " · ";
+		const parts: string[] = [];
+		switch (this.#focus) {
+			case "actions":
+				parts.push("↑↓ select", "⏎ confirm");
+				if (this.#slider) parts.push("◂▸ model");
+				break;
+			case "toc":
+				parts.push("↑↓ section", "⏎ open", "a annotate", "d delete", "u undo");
+				break;
+			case "body":
+				parts.push("↑↓ scroll", "⇧ faster", "pgup/pgdn", "g/G ends");
+				break;
+		}
+		parts.push("tab regions");
+		if (this.#externalEditorLabel && this.#focus !== "toc") parts.push(`${this.#externalEditorLabel} editor`);
+		parts.push(this.#helpSuffix);
+		return parts.join(sep);
+	}
+
+	/** Build the concatenated body lines and record each section's start row. */
+	#buildBody(bodyContentWidth: number): string[] {
+		const lines: string[] = [];
+		const offsets: number[] = new Array(this.#sections.length);
+		for (let i = 0; i < this.#sections.length; i++) {
+			const section = this.#sections[i]!;
+			offsets[i] = lines.length;
+			const rendered = section.md.render(bodyContentWidth);
+			if (section.level >= 1 && section.annotations.length > 0 && rendered.length > 0) {
+				lines.push(rendered[0]!);
+				for (const note of section.annotations) {
+					lines.push(`${theme.fg("warning", "▎ ")}${theme.fg("dim", "note: ")}${theme.fg("accent", note)}`);
+				}
+				for (let k = 1; k < rendered.length; k++) lines.push(rendered[k]!);
+			} else {
+				for (const line of rendered) lines.push(line);
+			}
+		}
+		this.#sectionOffsets = offsets;
+		return lines;
+	}
+
+	#sidebarWidthFor(width: number): number {
+		return Math.max(18, Math.min(30, Math.round(width * 0.24)));
+	}
+
+	#sidebarVisible(width: number): boolean {
+		if (this.#toc.length < SIDEBAR_MIN_HEADINGS) return false;
+		if (width < SIDEBAR_MIN_TOTAL_WIDTH) return false;
+		return splitBodyWidth(width, this.#sidebarWidthFor(width)) >= SIDEBAR_MIN_BODY_WIDTH;
+	}
+
+	#renderSidebarLines(regionRows: number, sidebarWidth: number): string[] {
+		// No "Contents" label and no plan-title entry: the box title already says
+		// "Plan Review", so the sidebar is just the bare list of sections, VS
+		// Code-style. Window the entries around the cursor.
+		const lines: string[] = [];
+		const slots = Math.max(0, regionRows);
+		const total = this.#toc.length;
+		let start = 0;
+		if (total > slots) {
+			start = Math.max(0, Math.min(this.#tocCursor - Math.floor(slots / 2), total - slots));
+		}
+		for (let r = 0; r < slots; r++) {
+			const p = start + r;
+			lines.push(p < total ? this.#renderTocEntry(p, sidebarWidth) : "");
+		}
+		return lines;
+	}
+
+	#renderTocEntry(p: number, width: number): string {
+		const section = this.#sections[this.#toc[p]!]!;
+		const highlighted = p === this.#tocCursor;
+		const selected = highlighted && this.#focus === "toc";
+		const glow = highlighted && this.#focus !== "toc";
+		// Compact, VS Code-like rows: a single-column gutter, one space of indent
+		// per nesting level, then the title and an annotation marker.
+		const indent = " ".repeat(Math.max(0, section.level - this.#tocBaseLevel));
+		const ann = section.annotations.length > 0 ? " ✎" : "";
+		const avail = Math.max(0, width - 1 - indent.length - visibleWidth(ann));
+		const title = truncateToWidth(section.title || "(untitled)", avail, Ellipsis.Unicode);
+		const body = indent + title + ann;
+		// Single-column gutter glyph: a cursor `›` on the focused selection, an
+		// accent bar `▎` on the current scrolled section, otherwise blank. The
+		// glyph keeps the cursor legible even where the selection background is
+		// subtle; the focused row also gets the full-row highlight.
+		const gutter = selected ? "›" : glow ? "▎" : " ";
+		const line = gutter + body;
+		if (selected) return theme.bg("selectedBg", theme.bold(fit(line, width)));
+		if (glow) return theme.fg("accent", line);
+		return theme.fg("muted", line);
+	}
+
+	#renderFooterLines(innerWidth: number): string[] {
+		if (this.#annotating) {
+			const section = this.#sections[this.#toc[this.#tocCursor]!];
+			const title = section?.title ?? "";
+			const caption = `${theme.fg("dim", "Annotate")} ${theme.fg("accent", `‹${title}›`)}`;
+			return [caption, this.#input.render(innerWidth)[0] ?? ""];
+		}
+		return [theme.fg("dim", this.#buildHelp())];
+	}
+
 	render(width: number): string[] {
 		const termHeight = process.stdout.rows || 40;
+		const sidebarShown = this.#sidebarVisible(width);
+		this.#sidebarShown = sidebarShown;
+		const sidebarWidth = sidebarShown ? this.#sidebarWidthFor(width) : 0;
 		const innerWidth = Math.max(1, width - 4);
+		const bodyContentWidth = sidebarShown ? splitBodyWidth(width, sidebarWidth) : innerWidth;
 
-		const planLines = this.#md.render(innerWidth);
 		const sliderLines = this.#renderSliderLines();
 		const optionLines = this.#renderOptionLines();
 		const promptLines = this.#promptTitle ? [theme.bold(theme.fg("accent", this.#promptTitle))] : [];
+		const footerLines = this.#renderFooterLines(innerWidth);
 
-		// Chrome rows around the scrollable body: top border, divider, prompt,
-		// slider, options, divider, footer, bottom border.
-		const chrome = 5 + promptLines.length + sliderLines.length + optionLines.length;
-		const viewport = Math.max(MIN_BODY_ROWS, termHeight - chrome);
+		// Chrome rows: top border, two dividers, bottom border, plus the
+		// prompt/slider/option/footer rows between them.
+		const chrome = 4 + promptLines.length + sliderLines.length + optionLines.length + footerLines.length;
+		const regionRows = Math.max(MIN_BODY_ROWS, termHeight - chrome);
 
-		this.#scrollView.setLines(planLines);
-		this.#scrollView.setHeight(viewport);
-		const body = this.#scrollView.render(innerWidth);
+		const bodyLines = this.#buildBody(bodyContentWidth);
+		this.#scrollView.setLines(bodyLines);
+		this.#scrollView.setHeight(regionRows);
+		if (this.#pendingScrollToToc) {
+			this.#pendingScrollToToc = false;
+			this.#scrubBodyToToc();
+		}
+		if (this.#focus !== "toc") this.#tocCursor = this.#deriveTocCursorFromScroll();
+		const body = this.#scrollView.render(bodyContentWidth);
 
-		return [
-			topBorder(width, OVERLAY_TITLE),
-			...body.map(line => row(line, width)),
-			divider(width),
-			...promptLines.map(line => row(line, width)),
-			...sliderLines.map(line => row(line, width)),
-			...optionLines.map(line => row(line, width)),
-			divider(width),
-			row(theme.fg("dim", this.#helpText), width),
-			bottomBorder(width),
-		];
+		const out: string[] = [];
+		if (sidebarShown) {
+			const sidebar = this.#renderSidebarLines(regionRows, sidebarWidth);
+			out.push(topBorderSplit(width, OVERLAY_TITLE, sidebarWidth));
+			for (let i = 0; i < regionRows; i++) {
+				out.push(splitRow(sidebar[i] ?? "", body[i] ?? "", width, sidebarWidth));
+			}
+			out.push(dividerSplit(width, sidebarWidth));
+		} else {
+			out.push(topBorder(width, OVERLAY_TITLE));
+			for (const line of body) out.push(row(line, width));
+			out.push(divider(width));
+		}
+		for (const line of promptLines) out.push(row(line, width));
+		for (const line of sliderLines) out.push(row(line, width));
+		for (const line of optionLines) out.push(row(line, width));
+		out.push(divider(width));
+		for (const line of footerLines) out.push(row(line, width));
+		out.push(bottomBorder(width));
+		return out;
 	}
 }
diff --git a/packages/coding-agent/src/modes/components/plan-toc.ts b/packages/coding-agent/src/modes/components/plan-toc.ts
new file mode 100644
index 000000000..03ab43c0c
--- /dev/null
+++ b/packages/coding-agent/src/modes/components/plan-toc.ts
@@ -0,0 +1,138 @@
+/**
+ * Pure heading/section parser for the plan-review overlay. It splits a plan's
+ * markdown into a flat list of sections — a leading preamble (text before the
+ * first heading) followed by one entry per ATX heading — preserving the exact
+ * source bytes of each section so the overlay can render, reorder-free delete,
+ * and round-trip the document without a full markdown re-render.
+ *
+ * No TUI dependencies: this module is unit-tested in isolation.
+ */
+
+/** ATX heading: 1-6 `#`, required whitespace, a title, optional closing `#`s. */
+const HEADING_RE = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+/** Opening/closing code fence run (``` or ~~~), allowing up to 3 lead spaces. */
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+
+export interface PlanSection {
+	/** `0` = preamble (no heading, no ToC entry); `1..6` = heading depth. */
+	level: number;
+	/** Plain-text heading label with inline markdown lightly stripped. */
+	title: string;
+	/** Exact source slice for this section, including its trailing newline(s). */
+	raw: string;
+}
+
+/**
+ * Collapse inline markdown emphasis/link/code syntax to readable text. This is
+ * a deliberately light strip (not a full markdown render) just so ToC entries
+ * read cleanly — `**Goal** & [docs](x)` becomes `Goal & docs`.
+ */
+export function stripInlineMarkdown(text: string): string {
+	let out = text;
+	// Images first (so the link pass below does not eat the `(url)`), then links.
+	out = out.replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1");
+	out = out.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+	out = out.replace(/\[([^\]]*)\]\[[^\]]*\]/g, "$1");
+	// Autolinks `<https://…>` keep their URL as the readable text.
+	out = out.replace(/<([^>\s]+)>/g, "$1");
+	// Inline code, then bold/italic/strikethrough emphasis runs.
+	out = out.replace(/`([^`]+)`/g, "$1");
+	out = out.replace(/(\*\*|__)(.+?)\1/g, "$2");
+	out = out.replace(/(\*|_)(.+?)\1/g, "$2");
+	out = out.replace(/~~(.+?)~~/g, "$1");
+	return out.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Split `text` into preamble + heading sections. `#` characters inside fenced
+ * code blocks are never treated as headings. Concatenating every section's
+ * `raw` reproduces the original text exactly.
+ */
+export function parsePlanSections(text: string): PlanSection[] {
+	const lines = text.split("\n");
+	// Character offset of each line start so section `raw` can slice the source.
+	const offsets: number[] = new Array(lines.length);
+	let cursor = 0;
+	for (let i = 0; i < lines.length; i++) {
+		offsets[i] = cursor;
+		cursor += lines[i]!.length + 1; // +1 for the "\n" join separator
+	}
+
+	// Heading line indices (start of each heading section), with metadata.
+	const heads: { line: number; level: number; title: string }[] = [];
+	let fenceChar: string | null = null;
+	let fenceLen = 0;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!;
+		const fence = FENCE_RE.exec(line);
+		if (fenceChar === null) {
+			if (fence) {
+				fenceChar = fence[1]![0]!;
+				fenceLen = fence[1]!.length;
+			}
+			// Opening-fence lines are body, not headings.
+			if (fence) continue;
+		} else {
+			// Inside a fence: only a matching-or-longer run of the same char closes.
+			if (fence && fence[1]![0] === fenceChar && fence[1]!.length >= fenceLen && fence[2]!.trim() === "") {
+				fenceChar = null;
+				fenceLen = 0;
+			}
+			continue;
+		}
+		const heading = HEADING_RE.exec(line);
+		if (heading) {
+			heads.push({ line: i, level: heading[1]!.length, title: stripInlineMarkdown(heading[2]!) });
+		}
+	}
+
+	const sections: PlanSection[] = [];
+	const sliceRaw = (startLine: number, endLine: number): string => {
+		const startOffset = offsets[startLine]!;
+		const endOffset = endLine < lines.length ? offsets[endLine]! : text.length;
+		return text.slice(startOffset, endOffset);
+	};
+
+	// Preamble: everything before the first heading (only when non-empty).
+	const firstHeadLine = heads.length > 0 ? heads[0]!.line : lines.length;
+	if (firstHeadLine > 0) {
+		const raw = sliceRaw(0, firstHeadLine);
+		if (raw.length > 0) sections.push({ level: 0, title: "", raw });
+	}
+
+	for (let h = 0; h < heads.length; h++) {
+		const head = heads[h]!;
+		const endLine = h + 1 < heads.length ? heads[h + 1]!.line : lines.length;
+		sections.push({ level: head.level, title: head.title, raw: sliceRaw(head.line, endLine) });
+	}
+
+	return sections;
+}
+
+/**
+ * Concatenate every section's `raw` back into a single document and guarantee a
+ * single trailing newline. Inverse of {@link parsePlanSections} for any input
+ * that already ends with a newline.
+ */
+export function joinPlanSections(sections: readonly PlanSection[]): string {
+	let joined = "";
+	for (const section of sections) joined += section.raw;
+	if (joined.length === 0) return "";
+	return joined.endsWith("\n") ? joined : `${joined}\n`;
+}
+
+/**
+ * Indices to remove when deleting `sections[index]`: the heading itself plus
+ * every following section nested deeper than it (its sub-headings). The
+ * preamble (level 0) is never a deletion target and yields an empty span.
+ */
+export function sectionDeletionSpan(sections: readonly PlanSection[], index: number): number[] {
+	const target = sections[index];
+	if (!target || target.level === 0) return [];
+	const span = [index];
+	for (let j = index + 1; j < sections.length; j++) {
+		if (sections[j]!.level > target.level) span.push(j);
+		else break;
+	}
+	return span;
+}
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index c596e9df2..d831e9ba8 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -1689,6 +1689,8 @@ export class InteractiveMode implements InteractiveModeContext {
 			helpText?: string;
 			disabledIndices?: number[];
 			onExternalEditor?: () => void;
+			onPlanEdited?: (content: string) => void;
+			onFeedbackChange?: (feedback: string) => void;
 			initialIndex?: number;
 		},
 		extra?: { slider?: HookSelectorSlider },
@@ -1712,11 +1714,14 @@ export class InteractiveMode implements InteractiveModeContext {
 				helpText: dialogOptions?.helpText,
 				initialIndex: dialogOptions?.initialIndex,
 				slider: extra?.slider,
+				externalEditorLabel: this.keybindings.getDisplayString("app.editor.external") || undefined,
 			},
 			{
 				onPick: choice => finish(choice),
 				onCancel: () => finish(undefined),
 				onExternalEditor: dialogOptions?.onExternalEditor,
+				onPlanEdited: dialogOptions?.onPlanEdited,
+				onFeedbackChange: dialogOptions?.onFeedbackChange,
 			},
 		);
 		this.#planReviewOverlay = overlay;
@@ -1725,6 +1730,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			width: "100%",
 			maxHeight: "100%",
 			margin: 0,
+			fullscreen: true,
 		});
 		this.ui.setFocus(overlay);
 		this.ui.requestRender();
@@ -1756,14 +1762,6 @@ export class InteractiveMode implements InteractiveModeContext {
 		}
 	}
 
-	#getPlanReviewHelpText(): string {
-		const externalEditorKey = this.keybindings.getDisplayString("app.editor.external");
-		if (!externalEditorKey) {
-			return "up/down select  enter confirm  pgup/pgdn scroll  esc cancel";
-		}
-		return `up/down select  enter confirm  pgup/pgdn scroll  ${externalEditorKey.toLowerCase()} open in editor  esc cancel`;
-	}
-
 	#getPlanApprovalContextUsage(): ContextUsage | undefined {
 		const executionModel = this.#planModePreviousModelState?.model ?? this.session.model;
 		const contextWindow = executionModel?.contextWindow;
@@ -2280,7 +2278,14 @@ export class InteractiveMode implements InteractiveModeContext {
 						},
 					}
 				: undefined;
-		const helpText = slider ? `${this.#getPlanReviewHelpText()}  ◂/▸ model` : this.#getPlanReviewHelpText();
+		// The overlay now owns the dynamic, focus-aware help line; the caller only
+		// supplies the trailing cancel hint.
+		const helpText = "esc cancel";
+		// In-overlay edits (section deletes/undo) and section annotations. Deletes
+		// update `editedContent` (and mirror to disk); annotations build `feedback`
+		// that the Refine branch re-prompts the model with.
+		let editedContent: string | undefined;
+		let feedback = "";
 
 		const choice = await this.showPlanReview(
 			planContent,
@@ -2289,6 +2294,13 @@ export class InteractiveMode implements InteractiveModeContext {
 			{
 				helpText,
 				onExternalEditor: () => void this.#openPlanInExternalEditor(planFilePath),
+				onPlanEdited: content => {
+					editedContent = content;
+					void Bun.write(this.#resolvePlanFilePath(planFilePath), content);
+				},
+				onFeedbackChange: value => {
+					feedback = value;
+				},
 				disabledIndices: keepContextDisabled ? [PLAN_KEEP_CONTEXT_OPTION_INDEX] : undefined,
 			},
 			{ slider },
@@ -2297,7 +2309,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		if (choice === "Approve and execute" || choice === "Approve and compact context" || choice === keepContextLabel) {
 			const finalPlanFilePath = details.finalPlanFilePath || planFilePath;
 			try {
-				const latestPlanContent = await this.#readPlanFile(planFilePath);
+				// Prefer in-overlay edits (already in memory) over a disk re-read; the
+				// `onPlanEdited` write is fire-and-forget, so reading the file here could
+				// race ahead of it.
+				const latestPlanContent = editedContent ?? (await this.#readPlanFile(planFilePath));
 				if (!latestPlanContent) {
 					this.showError(`Plan file not found at ${planFilePath}`);
 					return;
@@ -2328,6 +2343,16 @@ export class InteractiveMode implements InteractiveModeContext {
 			}
 			return;
 		}
+
+		if (choice === "Refine plan") {
+			// Section annotations entered in the overlay become a refinement prompt
+			// re-submitted to the model. With no annotations, fall back to today's
+			// behavior: close the overlay and let the operator type their own.
+			if (feedback.trim() && this.onInputCallback) {
+				this.onInputCallback(this.startPendingSubmission({ text: feedback }));
+			}
+			return;
+		}
 	}
 
 	/**
diff --git a/packages/coding-agent/test/interactive-mode-plan-review.test.ts b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
index 8c270905d..7867b3538 100644
--- a/packages/coding-agent/test/interactive-mode-plan-review.test.ts
+++ b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
@@ -146,6 +146,101 @@ describe("InteractiveMode plan review rendering", () => {
 		expect(review.mock.calls[1]?.[0]).not.toContain("First plan");
 	});
 
+	it("re-prompts the model with annotation feedback when Refine is chosen", async () => {
+		const planFilePath = "local://PLAN.md";
+		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
+			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
+			getSessionId: () => session.sessionManager.getSessionId(),
+		});
+		await Bun.write(resolvedPlanPath, "# Plan\n\nbody");
+
+		mode.planModeEnabled = true;
+		mode.planModePlanFilePath = planFilePath;
+		const feedback = "Refinement feedback on the plan:\n\n## Goal\n- needs detail\n";
+		// The overlay reports annotation feedback through onFeedbackChange before the
+		// operator picks "Refine plan".
+		vi.spyOn(mode, "showPlanReview").mockImplementation(async (_plan, _title, _options, dialogOptions) => {
+			dialogOptions?.onFeedbackChange?.(feedback);
+			return "Refine plan";
+		});
+		const startSpy = vi
+			.spyOn(mode, "startPendingSubmission")
+			.mockReturnValue({ text: feedback, cancelled: false, started: false });
+		const onInput = vi.fn();
+		mode.onInputCallback = onInput;
+
+		await mode.handlePlanApproval({
+			planFilePath,
+			planExists: true,
+			title: "PLAN",
+			finalPlanFilePath: "local://PLAN.md",
+		});
+
+		expect(startSpy).toHaveBeenCalledWith(expect.objectContaining({ text: expect.stringContaining("needs detail") }));
+		expect(onInput).toHaveBeenCalledTimes(1);
+	});
+
+	it("Refine with no annotations does not re-prompt the model", async () => {
+		const planFilePath = "local://PLAN.md";
+		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
+			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
+			getSessionId: () => session.sessionManager.getSessionId(),
+		});
+		await Bun.write(resolvedPlanPath, "# Plan\n\nbody");
+
+		mode.planModeEnabled = true;
+		mode.planModePlanFilePath = planFilePath;
+		vi.spyOn(mode, "showPlanReview").mockResolvedValue("Refine plan");
+		const startSpy = vi.spyOn(mode, "startPendingSubmission");
+		const onInput = vi.fn();
+		mode.onInputCallback = onInput;
+
+		await mode.handlePlanApproval({
+			planFilePath,
+			planExists: true,
+			title: "PLAN",
+			finalPlanFilePath: "local://PLAN.md",
+		});
+
+		expect(startSpy).not.toHaveBeenCalled();
+		expect(onInput).not.toHaveBeenCalled();
+	});
+
+	it("approves with in-overlay edits and mirrors them to the plan file", async () => {
+		const planFilePath = "local://PLAN.md";
+		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
+			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
+			getSessionId: () => session.sessionManager.getSessionId(),
+		});
+		await Bun.write(resolvedPlanPath, "# Plan\n\noriginal body\n");
+
+		mode.planModeEnabled = true;
+		mode.planModePlanFilePath = planFilePath;
+		const edited = "# Plan\n\nedited body\n";
+		vi.spyOn(mode, "showPlanReview").mockImplementation(async (_plan, _title, _options, dialogOptions) => {
+			dialogOptions?.onPlanEdited?.(edited);
+			return "Approve and execute";
+		});
+		vi.spyOn(mode, "handleClearCommand").mockResolvedValue();
+		const promptSpy = vi.spyOn(session, "prompt").mockResolvedValue(undefined as never);
+
+		await mode.handlePlanApproval({
+			planFilePath,
+			planExists: true,
+			title: "PLAN",
+			finalPlanFilePath: "local://PLAN.md",
+		});
+
+		// The synthetic plan-approved prompt carries the in-overlay edit, not the
+		// stale on-disk content (preferring editedContent avoids the write race).
+		const call = promptSpy.mock.calls.find(isPlanApprovedCall);
+		expect(call).toBeDefined();
+		expect(call?.[0] as string).toContain("edited body");
+		expect(call?.[0] as string).not.toContain("original body");
+		// onPlanEdited mirrored the edit to the plan file.
+		expect(await Bun.file(resolvedPlanPath).text()).toContain("edited body");
+	});
+
 	it("offers approve-and-keep-context as a distinct plan approval path", async () => {
 		const planFilePath = "local://PLAN.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
diff --git a/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts b/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts
index 49c2cba61..25728a7d7 100644
--- a/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts
+++ b/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts
@@ -11,6 +11,8 @@ const DOWN = "\x1b[B";
 const LEFT = "\x1b[D";
 const RIGHT = "\x1b[C";
 const ENTER = "\r";
+const TAB = "\t";
+const SHIFT_DOWN = "\x1b[1;2B";
 const CANCEL = "\x07"; // ctrl+g, remapped to tui.select.cancel below
 
 let darkTheme = await getThemeByName("dark");
@@ -192,4 +194,201 @@ describe("PlanReviewOverlay", () => {
 		expect(out).toContain("brand new body");
 		expect(out).not.toContain("para 199");
 	});
+
+	// Plan with ≥2 headings + nesting, wide enough for the sidebar at width 80.
+	const SECTION_PLAN =
+		"# Overview\n\nintro body\n\n## Goal\n\ngoal body\n\n## Steps\n\nstep body\n\n# Risks\n\nrisk body\n";
+	it("renders no per-line ellipsis in the plan body", () => {
+		const overlay = new PlanReviewOverlay(
+			"# Plan\n\nshort line one\n\nshort line two",
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		const body = render(overlay)
+			.split("\n")
+			.filter(line => line.includes("short line"));
+		expect(body.length).toBeGreaterThan(0);
+		for (const line of body) expect(line).not.toContain("…");
+	});
+
+	it("shows a header-less section sidebar and cycles focus regions with Tab", () => {
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		const out = render(overlay);
+		// Two-column split chrome (┬ joins the title rule over the divider) and the
+		// bare section list — no "Contents" label.
+		expect(out).toContain("┬");
+		expect(out).not.toContain("Contents");
+		expect(out).toContain("Overview");
+		// Tab into the ToC region surfaces its focus-specific help.
+		overlay.handleInput(TAB);
+		const tocFocused = render(overlay);
+		expect(tocFocused).toContain("a annotate");
+		expect(tocFocused).toContain("d delete");
+	});
+
+	it("omits the single plan-title heading from the ToC", () => {
+		// One shallow H1 title + two H2 sections: the title is redundant in the ToC.
+		const overlay = new PlanReviewOverlay(
+			"# Plan: build the thing\n\nintro\n\n## Design\n\nd\n\n## Rollout\n\nr\n",
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		const sidebar = render(overlay)
+			.split("\n")
+			.map(line => line.split("│")[1] ?? "")
+			.join("\n");
+		expect(sidebar).toContain("Design");
+		expect(sidebar).toContain("Rollout");
+		expect(sidebar).not.toContain("build the thing");
+	});
+
+	it("flows past the end of a region into the actions on Down", () => {
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		render(overlay);
+		overlay.handleInput(TAB); // -> toc, first section
+		// Walk to the last ToC entry, then one more Down drops into the actions.
+		for (let i = 0; i < 10; i++) overlay.handleInput(DOWN);
+		const out = render(overlay);
+		// Actions focus restores the option cursor highlight + actions help.
+		expect(out).toContain("⏎ confirm");
+		expect(out).not.toContain("a annotate");
+	});
+
+	it("scrolls the body exactly one line per keystroke in body focus", () => {
+		// Tall enough to overflow any test viewport, so the body genuinely scrolls.
+		const rows = Array.from({ length: 400 }, (_, i) => `L${String(i).padStart(3, "0")}`).join("\n");
+		const overlay = new PlanReviewOverlay(
+			`# Plan\n\n\`\`\`\n${rows}\n\`\`\`\n`,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		const visibleRows = (): string[] =>
+			render(overlay)
+				.split("\n")
+				.map(line => line.match(/L\d\d\d/)?.[0])
+				.filter((m): m is string => m !== undefined);
+		render(overlay); // first render loads the body lines into the ScrollView
+		overlay.handleInput(TAB); // actions -> body (no sidebar with a single heading)
+		// Scroll well past the heading/fence so the window is pure code rows.
+		for (let i = 0; i < 12; i++) overlay.handleInput(DOWN);
+		const before = visibleRows();
+		overlay.handleInput(DOWN);
+		const after = visibleRows();
+		// One-line scroll: the window advances by exactly one row.
+		expect(after[0]).toBe(before[1]);
+	});
+
+	it("jumps the body to a section when the ToC cursor moves", () => {
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		render(overlay);
+		overlay.handleInput(TAB); // -> toc (Overview)
+		overlay.handleInput(DOWN); // -> Goal, scrubbing the body to it
+		const body = render(overlay).split("\n").slice(1, 5).join(" ");
+		expect(body).toContain("Goal");
+	});
+
+	it("deletes the selected section and restores it with undo", () => {
+		const onPlanEdited = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn(), onPlanEdited },
+		);
+		render(overlay);
+		overlay.handleInput(TAB); // -> toc (Overview)
+		overlay.handleInput(DOWN); // -> Goal
+		overlay.handleInput("d");
+		expect(onPlanEdited).toHaveBeenCalled();
+		const edited = onPlanEdited.mock.calls.at(-1)?.[0] as string;
+		expect(edited).not.toContain("## Goal");
+		expect(edited).toContain("## Steps");
+		expect(render(overlay)).not.toContain("goal body");
+
+		overlay.handleInput("u");
+		const restored = render(overlay);
+		expect(restored).toContain("Goal");
+		expect(restored).toContain("goal body");
+	});
+
+	it("annotates a section and emits feedback for the Refine loop", () => {
+		const onFeedbackChange = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn(), onFeedbackChange },
+		);
+		render(overlay);
+		overlay.handleInput(TAB); // -> toc (Overview)
+		overlay.handleInput("a"); // annotate Overview
+		for (const ch of "needs detail") overlay.handleInput(ch);
+		overlay.handleInput(ENTER); // submit
+		const out = render(overlay);
+		expect(out).toContain("needs detail"); // callout in the body
+		expect(out).toContain("✎"); // marker in the sidebar
+		expect(onFeedbackChange).toHaveBeenCalled();
+		const feedback = onFeedbackChange.mock.calls.at(-1)?.[0] as string;
+		expect(feedback).toContain("Overview");
+		expect(feedback).toContain("needs detail");
+	});
+
+	it("drives the slider with both arrows even when a sidebar is present", () => {
+		const changes: number[] = [];
+		const slider: HookSelectorSlider = {
+			caption: "continue with",
+			index: 0,
+			segments: [{ label: "default" }, { label: "slow", detail: "opus" }],
+			onChange: index => changes.push(index),
+		};
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS, slider },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		render(overlay); // establish the sidebar
+		// The sidebar sits beside the body, not the slider, so left must still step
+		// the tier back instead of being stolen to focus the ToC.
+		overlay.handleInput(RIGHT); // 0 -> 1
+		overlay.handleInput(LEFT); // 1 -> 0
+		expect(changes).toEqual([1, 0]);
+		// Focus stayed on the actions region (left did not jump to the ToC).
+		expect(render(overlay)).not.toContain("a annotate");
+	});
+
+	it("fast-scrolls the body with Shift+Arrow", () => {
+		const rows = Array.from({ length: 400 }, (_, i) => `L${String(i).padStart(3, "0")}`).join("\n");
+		const overlay = new PlanReviewOverlay(
+			`# Plan\n\n\`\`\`\n${rows}\n\`\`\`\n`,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		const firstRow = (): number =>
+			Number(
+				(
+					render(overlay)
+						.split("\n")
+						.map(line => line.match(/L\d\d\d/)?.[0])
+						.find((m): m is string => m !== undefined) ?? "L000"
+				).slice(1),
+			);
+		render(overlay); // first render loads the body lines into the ScrollView
+		overlay.handleInput(TAB); // -> body
+		// Scroll into the pure-code region so the leading heading rows don't skew
+		// the absolute row math, then compare a single step to a Shift step.
+		for (let i = 0; i < 10; i++) overlay.handleInput(DOWN);
+		const base = firstRow();
+		overlay.handleInput(SHIFT_DOWN); // Shift+Down — fastScrollLines (5) at once
+		expect(firstRow() - base).toBe(5);
+	});
 });
diff --git a/packages/coding-agent/test/modes/components/plan-toc.test.ts b/packages/coding-agent/test/modes/components/plan-toc.test.ts
new file mode 100644
index 000000000..16bb5b461
--- /dev/null
+++ b/packages/coding-agent/test/modes/components/plan-toc.test.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from "bun:test";
+import {
+	joinPlanSections,
+	type PlanSection,
+	parsePlanSections,
+	sectionDeletionSpan,
+	stripInlineMarkdown,
+} from "@oh-my-pi/pi-coding-agent/modes/components/plan-toc";
+
+const titles = (sections: readonly PlanSection[]): string[] => sections.map(s => s.title);
+const levels = (sections: readonly PlanSection[]): number[] => sections.map(s => s.level);
+
+describe("parsePlanSections", () => {
+	it("splits a preamble and one section per ATX heading, tracking depth", () => {
+		const sections = parsePlanSections("intro\n\n# Overview\n\nbody\n\n## Goal\n\ngoal\n\n# Risks\n\nrisk\n");
+		expect(levels(sections)).toEqual([0, 1, 2, 1]);
+		expect(titles(sections)).toEqual(["", "Overview", "Goal", "Risks"]);
+		// Preamble is the only level-0 section; it carries no title.
+		expect(sections[0]!.raw).toBe("intro\n\n");
+	});
+
+	it("emits no preamble section when the document opens with a heading", () => {
+		const sections = parsePlanSections("# Top\n\nbody\n");
+		expect(levels(sections)).toEqual([1]);
+		expect(sections[0]!.title).toBe("Top");
+	});
+
+	it("does not treat '#' inside fenced code blocks as a heading", () => {
+		const sections = parsePlanSections("# Real\n\n```\n# not a heading\n```\n\n~~~\n## also not\n~~~\n");
+		expect(levels(sections)).toEqual([1]);
+		expect(titles(sections)).toEqual(["Real"]);
+	});
+
+	it("requires whitespace after the hashes, so '#tag' is body text", () => {
+		const sections = parsePlanSections("#tag is not a heading\nmore body\n");
+		expect(levels(sections)).toEqual([0]);
+	});
+
+	it("strips inline markdown and closing hashes from titles", () => {
+		const sections = parsePlanSections("## **Goal** & [docs](http://x) ##\n\nbody\n");
+		expect(sections[0]!.title).toBe("Goal & docs");
+	});
+});
+
+describe("joinPlanSections", () => {
+	it("round-trips a newline-terminated document", () => {
+		const text = "intro\n\n# A\n\nbody a\n\n## A1\n\nnested\n\n# B\n\nbody b\n";
+		expect(joinPlanSections(parsePlanSections(text))).toBe(text);
+	});
+
+	it("guarantees a single trailing newline when the source lacks one", () => {
+		expect(joinPlanSections(parsePlanSections("# A\n\nbody"))).toBe("# A\n\nbody\n");
+	});
+
+	it("returns an empty string for an empty document", () => {
+		expect(joinPlanSections(parsePlanSections(""))).toBe("");
+	});
+});
+
+describe("sectionDeletionSpan", () => {
+	const sections = parsePlanSections("intro\n\n# A\n\na\n\n## A1\n\na1\n\n## A2\n\na2\n\n# B\n\nb\n");
+	// Indices: 0 preamble, 1 A(L1), 2 A1(L2), 3 A2(L2), 4 B(L1)
+
+	it("removes a heading together with its deeper-nested children", () => {
+		expect(sectionDeletionSpan(sections, 1)).toEqual([1, 2, 3]);
+	});
+
+	it("removes only a leaf section", () => {
+		expect(sectionDeletionSpan(sections, 2)).toEqual([2]);
+	});
+
+	it("never targets the preamble", () => {
+		expect(sectionDeletionSpan(sections, 0)).toEqual([]);
+	});
+
+	it("joining the surviving sections drops the deleted subtree", () => {
+		const span = new Set(sectionDeletionSpan(sections, 1));
+		const survivors = sections.filter((_, i) => !span.has(i));
+		const result = joinPlanSections(survivors);
+		expect(result).toContain("# B");
+		expect(result).not.toContain("# A");
+		expect(result).not.toContain("## A1");
+	});
+});
+
+describe("stripInlineMarkdown", () => {
+	it("collapses emphasis, code, links, and whitespace to readable text", () => {
+		expect(stripInlineMarkdown("**bold** _it_ `code` [t](u)")).toBe("bold it code t");
+		expect(stripInlineMarkdown("a   b\tc")).toBe("a b c");
+	});
+});
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 8183b6b00..307befe93 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -12,6 +12,7 @@
 - Added `Loader.dispose()` to stop the loader animation timer when the component is disposed
 - Added a `ScrollView` `ellipsis` option (defaults to `Ellipsis.Unicode`) so callers that pre-wrap content to width can pass `Ellipsis.Omit` and suppress the stray per-line `…` that lands on trailing padding.
 - Added `ScrollView.handleScrollKey()` plus a `fastScrollLines` option so every scroll view gets shared navigation keys, including Shift+Arrow to scroll faster.
+- Added `OverlayOptions.fullscreen`: while the topmost visible overlay sets it, the engine borrows the terminal's alternate screen buffer for the overlay's lifetime and paints only the modal there — no ED3, no transcript re-commit — so the transcript stays untouched on the normal screen and is not scrollable behind the modal.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index eda1f4854..6e7c4a13d 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -306,6 +306,17 @@ export interface OverlayOptions {
 	 * Called each render cycle with current terminal dimensions.
 	 */
 	visible?: (termWidth: number, termHeight: number) => boolean;
+
+	// === Fullscreen ===
+	/**
+	 * Borrow the terminal's alternate screen buffer for this overlay's lifetime
+	 * (vim/less idiom). While the topmost visible overlay sets this, the engine
+	 * paints only the modal on the alt screen and emits no ED3 / scrollback
+	 * bytes, so the transcript on the normal screen stays untouched and is not
+	 * scrollable behind the modal. Defaults off — all other overlays are
+	 * unchanged and still draw over the transcript on the normal screen.
+	 */
+	fullscreen?: boolean;
 }
 
 /**
@@ -498,6 +509,16 @@ export class TUI extends Container {
 	#resizeEventPending = false;
 	#stopped = false;
 
+	// Transient alternate-screen state for a fullscreen overlay. While active, the
+	// engine paints only the modal on the alt buffer and leaves every
+	// normal-screen accounting field (#previousLines, #viewportTopRow, …)
+	// untouched, so exiting reconciles cleanly against the terminal-restored
+	// normal screen. #altPreviousLines is the last alt frame, for repaint-skip.
+	#altActive = false;
+	#altPreviousLines: string[] = [];
+	#altEnterWidth = 0;
+	#altEnterHeight = 0;
+
 	// Overlay stack for modal components rendered on top of base content
 	overlayStack: {
 		component: Component;
@@ -953,6 +974,13 @@ export class TUI extends Container {
 	}
 
 	stop(): void {
+		// Leave the alt buffer first so the teardown cursor math below runs against
+		// the restored normal screen (which #previousLines still describes).
+		if (this.#altActive) {
+			this.terminal.write("\x1b[?1049l");
+			this.#altActive = false;
+			this.#altPreviousLines = [];
+		}
 		if (TERMINAL.imageProtocol === ImageProtocol.Kitty) {
 			for (const id of this.#imageBudget.takeAllTransmittedIds()) {
 				this.terminal.write(encodeKittyDeleteImage(id));
@@ -1506,6 +1534,36 @@ export class TUI extends Container {
 		// fit results stay valid across the compose pass and every emitter re-fit.
 		this.#fitLineCache.clear();
 
+		// Fullscreen alt-screen short-circuit. While the topmost visible overlay
+		// requests it, borrow the terminal's alternate buffer (saved/restored by
+		// the terminal around 1049h/1049l) and paint only the modal there. This
+		// touches no normal-screen accounting field, so the transcript on the
+		// normal screen stays untouched and unscrollable behind the modal, and
+		// exiting reconciles cleanly against the terminal-restored screen.
+		const wantAlt = this.#wantsAltScreen();
+		if (wantAlt && !this.#altActive) {
+			this.terminal.write("\x1b[?1049h");
+			this.terminal.hideCursor();
+			this.#altActive = true;
+			this.#altPreviousLines = [];
+			this.#altEnterWidth = width;
+			this.#altEnterHeight = height;
+		} else if (!wantAlt && this.#altActive) {
+			this.terminal.write("\x1b[?1049l");
+			this.#altActive = false;
+			this.#altPreviousLines = [];
+			// A resize while on the alt buffer reflowed the terminal's saved normal
+			// screen; it no longer matches #previousLines, so force the geometry
+			// rebuild path instead of a stale diff.
+			if (width !== this.#altEnterWidth || height !== this.#altEnterHeight) {
+				this.#resizeEventPending = true;
+			}
+		}
+		if (this.#altActive) {
+			this.#renderAltFrame(width, height);
+			return;
+		}
+
 		// 1. Compose the frame. Bracket the transcript render so the image budget
 		// observes every inline image in display order (overlays carry none).
 		this.#imageBudget.beginPass();
@@ -2613,6 +2671,61 @@ export class TUI extends Container {
 		this.#commit(lines, width, height, viewportTop, toRow);
 	}
 
+	/** Topmost visible overlay requests the alternate-screen buffer. */
+	#wantsAltScreen(): boolean {
+		for (let i = this.overlayStack.length - 1; i >= 0; i--) {
+			const entry = this.overlayStack[i]!;
+			if (!this.#isOverlayVisible(entry)) continue;
+			return entry.options?.fullscreen === true;
+		}
+		return false;
+	}
+
+	/**
+	 * Compose and paint a single fullscreen overlay frame on the alt buffer.
+	 * Cursor markers are stripped (the modal draws its own in-band caret and
+	 * keeps the hardware cursor hidden), and only the modal is composited over a
+	 * blank base — the transcript is never touched while the alt buffer is up.
+	 */
+	#renderAltFrame(width: number, height: number): void {
+		const base: string[] = new Array(Math.max(0, height)).fill("");
+		let lines = this.#compositeOverlays(base, width, height);
+		this.#extractCursorPosition(lines, height);
+		lines = this.#fitLinesToWidth(this.#applyLineResets(lines), width);
+		this.#emitAltFrame(lines, width, height);
+	}
+
+	/**
+	 * Full per-row viewport rewrite on the alt buffer. Emits only sync-output
+	 * brackets, a cursor home, and per-row rewrites — never ED3, append-tail, or
+	 * any native-scrollback byte, so it is fully isolated from the planner and
+	 * #commit. The hardware cursor stays hidden (it is never re-shown here).
+	 */
+	#emitAltFrame(lines: string[], width: number, height: number): void {
+		const fitted: string[] = new Array(height);
+		for (let r = 0; r < height; r++) fitted[r] = this.#fitLineToWidth(lines[r] ?? "", width);
+		// Skip an identical repaint (the modal is mostly static between keystrokes).
+		if (this.#altPreviousLines.length === height) {
+			let same = true;
+			for (let r = 0; r < height; r++) {
+				if (fitted[r] !== this.#altPreviousLines[r]) {
+					same = false;
+					break;
+				}
+			}
+			if (same) return;
+		}
+		let buffer = `${this.#paintBeginSequence}\x1b[H`;
+		for (let r = 0; r < height; r++) {
+			if (r > 0) buffer += "\r\n";
+			buffer += this.#lineRewriteSequence(fitted[r], width);
+		}
+		buffer += this.#paintEndSequence;
+		this.terminal.write(buffer);
+		this.#altPreviousLines = fitted;
+		this.#fullRedrawCount += 1;
+	}
+
 	/**
 	 * Foreground-stream live-region paint for ED3-risk terminals with an
 	 * unobservable viewport. Commits the newly-sealed chunk to native scrollback
diff --git a/packages/tui/test/render-regressions.test.ts b/packages/tui/test/render-regressions.test.ts
index dcb6a06b8..d94e77f69 100644
--- a/packages/tui/test/render-regressions.test.ts
+++ b/packages/tui/test/render-regressions.test.ts
@@ -3209,6 +3209,79 @@ describe("TUI terminal-state regressions", () => {
 		});
 	});
 
+	describe("fullscreen overlay alt-screen", () => {
+		it("enters the alt buffer on show, leaves it on hide, and emits no ED3 while modal", async () => {
+			const term = new VirtualTerminal(40, 8, 200);
+			const writes = captureWrites(term);
+			const tui = new TUI(term);
+			tui.addChild(new MutableLinesComponent(rows("base-", 8)));
+
+			try {
+				tui.start();
+				await settle(term);
+
+				const showFrom = writes.length;
+				const handle = tui.showOverlay(new MutableLinesComponent(["MODAL-0", "MODAL-1"]), {
+					anchor: "bottom-center",
+					width: "100%",
+					maxHeight: "100%",
+					margin: 0,
+					fullscreen: true,
+				});
+				await settle(term);
+
+				const modalWrites = writes.slice(showFrom).join("");
+				// Borrowed the alternate screen buffer …
+				expect(modalWrites).toContain("\x1b[?1049h");
+				// … and never erased scrollback (ED3) or otherwise touched the transcript.
+				expect(modalWrites).not.toContain("\x1b[3J");
+				expect(visible(term).some(line => line.includes("MODAL-0"))).toBeTrue();
+
+				const hideFrom = writes.length;
+				handle.hide();
+				await settle(term);
+
+				expect(writes.slice(hideFrom).join("")).toContain("\x1b[?1049l");
+				// Transcript is back on the normal screen after leaving the alt buffer.
+				expect(visible(term).some(line => line.includes("base-"))).toBeTrue();
+				expect(visible(term).some(line => line.includes("MODAL-0"))).toBeFalse();
+			} finally {
+				tui.stop();
+			}
+		});
+
+		it("leaves native scrollback untouched across the modal lifetime", async () => {
+			const term = new VirtualTerminal(40, 6, 200);
+			const tui = new TUI(term);
+			// Base transcript overflows the viewport, so rows land in scrollback.
+			tui.addChild(new MutableLinesComponent(rows("base-", 24)));
+
+			try {
+				tui.start();
+				await settle(term);
+				const scrollbackBefore = term.getScrollBuffer().map(line => line.trimEnd());
+
+				const handle = tui.showOverlay(new MutableLinesComponent(["MODAL"]), {
+					anchor: "bottom-center",
+					width: "100%",
+					maxHeight: "100%",
+					margin: 0,
+					fullscreen: true,
+				});
+				await settle(term);
+				handle.hide();
+				await settle(term);
+
+				// The modal borrowed/returned the alt buffer without rewriting the
+				// normal screen's scrollback — the transcript a reader scrolled up to
+				// see is identical before and after.
+				expect(term.getScrollBuffer().map(line => line.trimEnd())).toEqual(scrollbackBefore);
+			} finally {
+				tui.stop();
+			}
+		});
+	});
+
 	describe("stress scenarios", () => {
 		it("rapid content mutations converge to final expected screen", async () => {
 			const term = new VirtualTerminal(30, 8);

From c10eb5e50e7ee2af564740895ff3b9557eac6b5d Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 04:39:06 +0200
Subject: [PATCH 086/181] feat(coding-agent): added resolver-based auth retries
 to image and search tools

- Routed image-gen, inspect-image, and web search providers through `withAuth`.
- Used `reuseInitialApiKey`/`createAuthStorageResolver` for force-refresh and rotate retries.
- Attached HTTP status to thrown errors so the retry classifier detects retryable failures.
---
 packages/ai/CHANGELOG.md                      |   1 +
 packages/ai/src/auth-storage.ts               |  55 ++--
 packages/coding-agent/CHANGELOG.md            |   4 +-
 .../src/auto-thinking/classifier.ts           |   4 +-
 .../src/commit/model-selection.ts             |   8 +-
 .../src/config/api-key-resolver.ts            |  43 +--
 .../coding-agent/src/config/model-registry.ts |  11 +
 packages/coding-agent/src/eval/llm-bridge.ts  |   4 +-
 packages/coding-agent/src/memories/index.ts   |   6 +-
 packages/coding-agent/src/mnemopi/backend.ts  |   4 +-
 packages/coding-agent/src/tools/image-gen.ts  | 253 +++++++++++-------
 .../coding-agent/src/tools/inspect-image.ts   |   9 +-
 .../src/utils/commit-message-generator.ts     |   4 +-
 .../coding-agent/src/utils/title-generator.ts |   4 +-
 .../src/web/search/providers/anthropic.ts     |  44 +--
 .../src/web/search/providers/exa.ts           |  14 +-
 .../src/web/search/providers/kimi.ts          |  45 ++--
 .../src/web/search/providers/parallel.ts      |  59 ++--
 .../src/web/search/providers/synthetic.ts     |  14 +-
 .../src/web/search/providers/tavily.ts        |  17 +-
 .../src/web/search/providers/zai.ts           |  14 +-
 ...mmit-model-selection-role-thinking.test.ts |   3 +-
 .../coding-agent/test/title-generator.test.ts |   3 +
 .../coding-agent/test/tools/image-gen.test.ts |   4 +
 .../test/tools/inspect-image.test.ts          |   3 +
 .../test/tools/search-renderer.test.ts        |   4 +-
 .../test/tools/web-search-parallel.test.ts    |   6 +
 .../test/tools/web-search-tavily.test.ts      |   6 +
 28 files changed, 377 insertions(+), 269 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 57b37854b..3062ec17d 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -10,6 +10,7 @@
 - Added `ApiKeyResolver` and `ApiKey` auth helpers, including `isApiKeyResolver`, `isAuthRetryableError`, `resolveApiKeyOnce`, and `withAuth`, and exported them from the package root
 - Added support for a function-valued `apiKey` in `SimpleStreamOptions` so a single stream request can refresh or rotate credentials during retry
 - Added `forceRefresh` credential option to `AuthStorage.getApiKey` and `rotateSessionCredential` support for session-level credential rotation after auth failures
+- Added `AuthStorage.resolver(provider, options)` method that builds an `ApiKeyResolver` implementing the a/b/c auth-retry policy directly on the storage instance
 
 ### Changed
 
diff --git a/packages/ai/src/auth-storage.ts b/packages/ai/src/auth-storage.ts
index e4c80bd39..b76c2bbd6 100644
--- a/packages/ai/src/auth-storage.ts
+++ b/packages/ai/src/auth-storage.ts
@@ -590,36 +590,6 @@ export interface InvalidateCredentialMatchingOptions {
 	sessionId?: string;
 }
 
-/**
- * Build an {@link ApiKeyResolver} backed directly by an {@link AuthStorage},
- * implementing the central a/b/c auth-retry policy for consumers that hold an
- * AuthStorage rather than a higher-level registry (e.g. web-search providers):
- *
- * - initial (`error: undefined`) → resolve the session credential.
- * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential.
- * - step (c) `lastChance` → rotate to a sibling credential, then re-resolve.
- */
-export function createAuthStorageResolver(
-	storage: Pick<AuthStorage, "getApiKey" | "rotateSessionCredential">,
-	provider: string,
-	options?: { sessionId?: string; baseUrl?: string; modelId?: string },
-): ApiKeyResolver {
-	const { sessionId, baseUrl, modelId } = options ?? {};
-	return async ({ lastChance, error, signal }) => {
-		if (error === undefined) {
-			return storage.getApiKey(provider, sessionId, { baseUrl, modelId, signal });
-		}
-		if (lastChance) {
-			// Rotate to a sibling credential on an account constraint. No
-			// retry-after handling here — `markUsageLimitReached` owns the block
-			// duration and the outer retry layer owns the no-sibling wait.
-			await storage.rotateSessionCredential(provider, sessionId, { error, signal });
-			return storage.getApiKey(provider, sessionId, { baseUrl, modelId, signal });
-		}
-		return storage.getApiKey(provider, sessionId, { baseUrl, modelId, forceRefresh: true, signal });
-	};
-}
-
 function isAbortSignalOption(
 	value: InvalidateCredentialMatchingOptions | AbortSignal | undefined,
 ): value is AbortSignal {
@@ -3787,6 +3757,31 @@ export class AuthStorage {
 		return hasSibling;
 	}
 
+	/**
+	 * Build an {@link ApiKeyResolver} backed by this storage, implementing the
+	 * central a/b/c auth-retry policy:
+	 *
+	 * - initial (`error: undefined`) → resolve the session credential.
+	 * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential.
+	 * - step (c) `lastChance` → rotate to a sibling credential, then re-resolve.
+	 *
+	 * Used by web-search providers and other consumers that hold an AuthStorage
+	 * directly (no ModelRegistry in scope).
+	 */
+	resolver(provider: string, options?: { sessionId?: string; baseUrl?: string; modelId?: string }): ApiKeyResolver {
+		const { sessionId, baseUrl, modelId } = options ?? {};
+		return async ({ lastChance, error, signal }) => {
+			if (error === undefined) {
+				return this.getApiKey(provider, sessionId, { baseUrl, modelId, signal });
+			}
+			if (lastChance) {
+				await this.rotateSessionCredential(provider, sessionId, { error, signal });
+				return this.getApiKey(provider, sessionId, { baseUrl, modelId, signal });
+			}
+			return this.getApiKey(provider, sessionId, { baseUrl, modelId, forceRefresh: true, signal });
+		};
+	}
+
 	// ─── Auth Broker integration ────────────────────────────────────────────
 
 	/**
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 83325513c..b6cb7ca6e 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -9,7 +9,9 @@
 
 ### Changed
 
-- Changed non-agent API operations (title and commit-message generation) to use session-aware API key resolution with refresh-first auth retries, refreshing the active credential before rotating to another account
+- Changed non-agent API operations (title and commit-message generation, image generation, web search, eval `llm()`, auto-thinking classifier, memory consolidation) to use session-aware API key resolution with auth retries via `registry.resolver()` / `authStorage.resolver()`, refreshing the active credential before rotating to another account
+- Changed image generation to wrap every provider fetch branch in `withAuth`, so 401 / usage-limit errors trigger credential force-refresh and rotation for authStorage-backed providers (OpenAI-hosted, antigravity, xai-oauth) while env-only providers (openrouter, gemini) stay single-attempt
+- Changed web-search providers using `authStorage.getApiKey` (anthropic, exa, tavily, parallel, synthetic, zai, kimi) to wrap HTTP calls in `withAuth` for automatic credential rotation on 401 / usage-limit errors
 - Changed the directory grouping for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics from a single flat `# dir/` heading per immediate directory to a multi-level tree that folds the common path prefix into one heading. Previously every group repeated the full directory path — so results rooted outside cwd printed the absolute prefix (e.g. `/Users/me/proj/`) on every heading and nested directories were never collapsed. Now a single-child directory chain folds into one heading (`# packages/pkg/src/`, including an absolute root for out-of-cwd results), subdirectories nest one `#` deeper (`## nested/` → `### child.ts`), and each directory's own files are listed before its subdirectories. TUI hyperlink reconstruction tracks the nested directory stack across the whole output so file and code-frame links keep resolving to the correct absolute paths.
 - Changed the plan-mode approval surface from an inline transcript block plus a separate bottom selector into a single fullscreen overlay (like `/copy`) and overhauled its navigation. The overlay now renders the plan per-section through `ScrollView` (line-level ↑/↓ scroll, Shift+↑/↓ to scroll faster, PgUp/PgDn, g/G) with no stray per-line `…`, and — when the terminal is wide enough and the plan has ≥2 headings — shows a compact VS Code-style Contents sidebar (the redundant plan-title heading is omitted). Focus moves between regions with Tab/Shift+Tab (and flows at the edges: Down past the last section or the bottom of the body drops into the approval options; Up steps back), while the sidebar glows to track the scrolled section. The sidebar can fast-jump between sections, delete a section (with `u` undo), and annotate sections with feedback (`a`) that is submitted back to the model when the operator picks "Refine plan"; ←/→ always drive the model-tier slider, Enter confirms, the external-editor key opens the plan, and Esc cancels. The overlay borrows the terminal's alternate screen buffer for its lifetime (`fullscreen` overlay), so the transcript stays put on the normal screen instead of bleeding through scrollback behind the modal.
 - Changed the interactive controllers (command, MCP, selector, extension-UI, event), debug panels, and the status/error/warning helpers to render chat output through `ctx.present(...)` instead of appending to `chatContainer` and calling `ui.requestRender()` directly; transcript rebuilds dispose live blocks via `ctx.resetTranscript()` so animated blocks' timers stop on reset.
diff --git a/packages/coding-agent/src/auto-thinking/classifier.ts b/packages/coding-agent/src/auto-thinking/classifier.ts
index fc029123a..ccae82f73 100644
--- a/packages/coding-agent/src/auto-thinking/classifier.ts
+++ b/packages/coding-agent/src/auto-thinking/classifier.ts
@@ -15,7 +15,7 @@
  */
 import { type AssistantMessage, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
-import { reuseInitialApiKey } from "../config/api-key-resolver";
+
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -83,7 +83,7 @@ async function classifyOnline(input: string, deps: ClassifyDifficultyDeps): Prom
 			messages: [{ role: "user", content: input, timestamp: Date.now() }],
 		},
 		{
-			apiKey: reuseInitialApiKey(apiKey, deps.registry, model.provider, {
+			apiKey: deps.registry.resolver(model.provider, {
 				sessionId: deps.sessionId,
 				baseUrl: model.baseUrl,
 			}),
diff --git a/packages/coding-agent/src/commit/model-selection.ts b/packages/coding-agent/src/commit/model-selection.ts
index 00fadcc15..135bb6be7 100644
--- a/packages/coding-agent/src/commit/model-selection.ts
+++ b/packages/coding-agent/src/commit/model-selection.ts
@@ -1,6 +1,6 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Api, ApiKey, Model } from "@oh-my-pi/pi-ai";
-import { type ApiKeyResolverRegistry, reuseInitialApiKey } from "../config/api-key-resolver";
+import type { ApiKeyResolverRegistry } from "../config/api-key-resolver";
 import { MODEL_ROLE_IDS } from "../config/model-registry";
 import {
 	type ModelLookupRegistry,
@@ -47,7 +47,7 @@ export async function resolvePrimaryModel(
 	}
 	return {
 		model,
-		apiKey: reuseInitialApiKey(apiKey, modelRegistry, model.provider, { baseUrl: model.baseUrl }),
+		apiKey: modelRegistry.resolver(model.provider, { baseUrl: model.baseUrl }),
 		thinkingLevel: resolved?.thinkingLevel,
 	};
 }
@@ -65,7 +65,7 @@ export async function resolveSmolModel(
 		if (apiKey) {
 			return {
 				model: resolvedSmol.model,
-				apiKey: reuseInitialApiKey(apiKey, modelRegistry, resolvedSmol.model.provider, {
+				apiKey: modelRegistry.resolver(resolvedSmol.model.provider, {
 					baseUrl: resolvedSmol.model.baseUrl,
 				}),
 				thinkingLevel: resolvedSmol.thinkingLevel,
@@ -81,7 +81,7 @@ export async function resolveSmolModel(
 		if (apiKey) {
 			return {
 				model: candidate,
-				apiKey: reuseInitialApiKey(apiKey, modelRegistry, candidate.provider, { baseUrl: candidate.baseUrl }),
+				apiKey: modelRegistry.resolver(candidate.provider, { baseUrl: candidate.baseUrl }),
 			};
 		}
 	}
diff --git a/packages/coding-agent/src/config/api-key-resolver.ts b/packages/coding-agent/src/config/api-key-resolver.ts
index fa039aa49..5204c5496 100644
--- a/packages/coding-agent/src/config/api-key-resolver.ts
+++ b/packages/coding-agent/src/config/api-key-resolver.ts
@@ -19,25 +19,23 @@ export interface ApiKeyResolverRegistry {
 		options?: { baseUrl?: string; forceRefresh?: boolean; signal?: AbortSignal },
 	): Promise<string | undefined>;
 	authStorage: Pick<AuthStorage, "rotateSessionCredential">;
+	/**
+	 * Build an {@link ApiKeyResolver} implementing the central a/b/c auth-retry
+	 * policy: initial → resolve; step (b) → force-refresh same account; step (c)
+	 * → rotate to a sibling credential, then re-resolve.
+	 *
+	 * The resolver is stateless (safe to reuse across requests). Callers that
+	 * need the initial key for a guard can call `resolveApiKeyOnce(resolver)`.
+	 */
+	resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;
 }
 
 /**
- * Build an {@link ApiKeyResolver} backed by the model registry's auth storage,
- * implementing the central a/b/c auth-retry policy for every non-agent network
- * consumer (utility completions, image generation, web search):
- *
- * - initial (`error: undefined`) → resolve the session credential (cheap; may
- *   return a locally-cached not-yet-expired token).
- * - step (b) `!lastChance` → force-refresh the SAME session-sticky credential
- *   (a peer/broker may have rotated its token out from under our cached copy).
- * - step (c) `lastChance` → rotate to a sibling credential (usage-limit block
- *   vs credential invalidation, by error class), then re-resolve.
- *
- * Stateless: nothing is captured beyond the registry/provider/options, so the
- * same resolver is safe to reuse across attempts and requests.
+ * Default implementation of {@link ApiKeyResolverRegistry.resolver}.
+ * Also usable standalone for structural registries that don't carry the method.
  */
 export function createApiKeyResolver(
-	registry: ApiKeyResolverRegistry,
+	registry: Pick<ApiKeyResolverRegistry, "getApiKeyForProvider" | "authStorage">,
 	provider: string,
 	options: ApiKeyResolverOptions = {},
 ): ApiKeyResolver {
@@ -58,20 +56,3 @@ export function createApiKeyResolver(
 		return registry.getApiKeyForProvider(provider, sessionId, { baseUrl, forceRefresh: true, signal });
 	};
 }
-
-/**
- * Wrap an already-resolved `initialKey` in an {@link ApiKeyResolver}: the
- * initial step returns that key verbatim (so a caller that resolved it eagerly
- * — e.g. to preserve a metadata / guard ordering, or to short-circuit when no
- * credential exists — does not pay for a second resolve), while retry steps
- * fall through to {@link createApiKeyResolver}'s force-refresh / rotate policy.
- */
-export function reuseInitialApiKey(
-	initialKey: string | undefined,
-	registry: ApiKeyResolverRegistry,
-	provider: string,
-	options: ApiKeyResolverOptions = {},
-): ApiKeyResolver {
-	const retry = createApiKeyResolver(registry, provider, options);
-	return ctx => (ctx.error === undefined ? initialKey : retry(ctx));
-}
diff --git a/packages/coding-agent/src/config/model-registry.ts b/packages/coding-agent/src/config/model-registry.ts
index 01b21eb04..6b0a86a23 100644
--- a/packages/coding-agent/src/config/model-registry.ts
+++ b/packages/coding-agent/src/config/model-registry.ts
@@ -95,12 +95,14 @@ const STARTUP_MODEL_CACHE_PROVIDER_IDS: readonly string[] = [
 	...SPECIAL_MODEL_MANAGER_PROVIDER_IDS,
 ];
 
+import type { ApiKeyResolver } from "@oh-my-pi/pi-ai";
 import { registerOAuthProvider, unregisterOAuthProviders } from "@oh-my-pi/pi-ai/utils/oauth";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/utils/oauth/types";
 import { isRecord, logger } from "@oh-my-pi/pi-utils";
 import { parseModelString, resolveProviderModelReference } from "../config/model-resolver";
 import { isValidThemeColor, type ThemeColor } from "../modes/theme/theme";
 import type { AuthStorage, OAuthCredential } from "../session/auth-storage";
+import { type ApiKeyResolverOptions, createApiKeyResolver } from "./api-key-resolver";
 import { type ConfigError, ConfigFile } from "./config-file";
 import {
 	buildCanonicalModelIndex,
@@ -2385,6 +2387,15 @@ export class ModelRegistry {
 		});
 	}
 
+	/**
+	 * Build an {@link ApiKeyResolver} for this provider, implementing the
+	 * central a/b/c auth-retry policy. Callers that need the initial key for
+	 * a guard can call `resolveApiKeyOnce(resolver)`.
+	 */
+	resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver {
+		return createApiKeyResolver(this, provider, options);
+	}
+
 	async #peekApiKeyForProvider(provider: string): Promise<string | undefined> {
 		if (this.#keylessProviders.has(provider) && !this.authStorage.hasAuth(provider)) {
 			return kNoAuth;
diff --git a/packages/coding-agent/src/eval/llm-bridge.ts b/packages/coding-agent/src/eval/llm-bridge.ts
index 484290352..1f37dc2c9 100644
--- a/packages/coding-agent/src/eval/llm-bridge.ts
+++ b/packages/coding-agent/src/eval/llm-bridge.ts
@@ -15,7 +15,7 @@ import { instrumentedCompleteSimple, resolveTelemetry } from "@oh-my-pi/pi-agent
 import { type Api, Effort, getSupportedEfforts, type Model, type Tool } from "@oh-my-pi/pi-ai";
 import * as z from "zod/v4";
 import { extractTextContent, extractToolCall, parseJsonPayload } from "../commit/utils";
-import { reuseInitialApiKey } from "../config/api-key-resolver";
+
 import { expandRoleAlias, formatModelString, resolveModelFromString } from "../config/model-resolver";
 import type { ToolSession } from "../tools";
 import { ToolError } from "../tools/tool-errors";
@@ -145,7 +145,7 @@ export async function runEvalLlm(args: unknown, options: EvalLlmBridgeOptions):
 				tools,
 			},
 			{
-				apiKey: reuseInitialApiKey(apiKey, registry, model.provider, {
+				apiKey: registry.resolver(model.provider, {
 					sessionId: options.session.getSessionId?.() ?? undefined,
 					baseUrl: model.baseUrl,
 				}),
diff --git a/packages/coding-agent/src/memories/index.ts b/packages/coding-agent/src/memories/index.ts
index 5ddafbba6..38205c5e2 100644
--- a/packages/coding-agent/src/memories/index.ts
+++ b/packages/coding-agent/src/memories/index.ts
@@ -5,7 +5,7 @@ import * as path from "node:path";
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import { type ApiKey, clampThinkingLevelForModel, completeSimple, Effort, type Model } from "@oh-my-pi/pi-ai";
 import { getAgentDbPath, getMemoriesDir, logger, parseJsonlLenient, prompt } from "@oh-my-pi/pi-utils";
-import { reuseInitialApiKey } from "../config/api-key-resolver";
+
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveModelRoleValue } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -272,7 +272,7 @@ async function runPhase1(options: {
 			const result = await runStage1Job({
 				claim,
 				model: phase1Model,
-				apiKey: reuseInitialApiKey(phase1ApiKey, modelRegistry, phase1Model.provider, {
+				apiKey: modelRegistry.resolver(phase1Model.provider, {
 					sessionId: session.sessionId,
 					baseUrl: phase1Model.baseUrl,
 				}),
@@ -432,7 +432,7 @@ async function runPhase2(options: {
 			const consolidated = await runConsolidationModel({
 				memoryRoot,
 				model: phase2Model,
-				apiKey: reuseInitialApiKey(phase2ApiKey, modelRegistry, phase2Model.provider, {
+				apiKey: modelRegistry.resolver(phase2Model.provider, {
 					sessionId: session.sessionId,
 					baseUrl: phase2Model.baseUrl,
 				}),
diff --git a/packages/coding-agent/src/mnemopi/backend.ts b/packages/coding-agent/src/mnemopi/backend.ts
index 9af906894..7eb6d531d 100644
--- a/packages/coding-agent/src/mnemopi/backend.ts
+++ b/packages/coding-agent/src/mnemopi/backend.ts
@@ -5,7 +5,7 @@ import { Mnemopi } from "@oh-my-pi/pi-mnemopi";
 import { BankManager } from "@oh-my-pi/pi-mnemopi/core";
 import { type DiagnosticSummary, inspectDatabase } from "@oh-my-pi/pi-mnemopi/diagnose";
 import { logger } from "@oh-my-pi/pi-utils";
-import { reuseInitialApiKey } from "../config/api-key-resolver";
+
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { MemoryBackend, MemoryBackendStartOptions } from "../memory-backend/types";
@@ -335,7 +335,7 @@ async function resolveMnemopiProviderOptions(
 						messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
 					},
 					{
-						apiKey: reuseInitialApiKey(apiKey, modelRegistry, model.provider, {
+						apiKey: modelRegistry.resolver(model.provider, {
 							sessionId,
 							baseUrl: model.baseUrl,
 						}),
diff --git a/packages/coding-agent/src/tools/image-gen.ts b/packages/coding-agent/src/tools/image-gen.ts
index 521fb94e6..ee90c5ca0 100644
--- a/packages/coding-agent/src/tools/image-gen.ts
+++ b/packages/coding-agent/src/tools/image-gen.ts
@@ -1,6 +1,6 @@
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAntigravityUserAgent, getEnvApiKey, type Model } from "@oh-my-pi/pi-ai";
+import { type ApiKey, getAntigravityUserAgent, getEnvApiKey, type Model, withAuth } from "@oh-my-pi/pi-ai";
 import {
 	CODEX_BASE_URL,
 	getCodexAccountId,
@@ -20,6 +20,7 @@ import {
 } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import packageJson from "../../package.json" with { type: "json" };
+
 import { isAuthenticated, type ModelRegistry } from "../config/model-registry";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import { ohMyPiXAIUserAgent, resolveXAIHttpCredentials } from "../lib/xai-http";
@@ -864,7 +865,10 @@ async function generateOpenAIHostedImage(
 
 	if (!response.ok) {
 		const errorText = await response.text();
-		throw new Error(`OpenAI image request failed (${response.status}): ${getOpenAIResponseErrorMessage(errorText)}`);
+		throw Object.assign(
+			new Error(`OpenAI image request failed (${response.status}): ${getOpenAIResponseErrorMessage(errorText)}`),
+			{ status: response.status },
+		);
 	}
 
 	const contentType = response.headers.get("content-type") ?? "";
@@ -1037,13 +1041,16 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 					throw new Error("Missing active GPT model for OpenAI image generation");
 				}
 
-				const parsed = await generateOpenAIHostedImage(
-					apiKey.apiKey,
-					apiKey.model,
-					params,
-					resolvedImages,
-					requestSignal,
+				const hostedModel = apiKey.model;
+				const hostedKey: ApiKey = ctx.modelRegistry.resolver(hostedModel.provider, {
 					sessionId,
+					baseUrl: hostedModel.baseUrl,
+				});
+
+				const parsed = await withAuth(
+					hostedKey,
+					key => generateOpenAIHostedImage(key, hostedModel, params, resolvedImages, requestSignal, sessionId),
+					{ signal: requestSignal },
 				);
 
 				if (parsed.images.length === 0) {
@@ -1088,38 +1095,57 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 				}
 
 				const prompt = assemblePrompt(params);
-				const requestBody = buildAntigravityRequest(
-					prompt,
-					model,
-					apiKey.projectId,
-					params.aspect_ratio,
-					params.image_size,
-					resolvedImages,
-				);
-
-				const response = await fetch(`${ANTIGRAVITY_ENDPOINT}/v1internal:streamGenerateContent?alt=sse`, {
-					method: "POST",
-					headers: {
-						Authorization: `Bearer ${apiKey.apiKey}`,
-						"Content-Type": "application/json",
-						Accept: "text/event-stream",
-						"User-Agent": getAntigravityUserAgent(),
-					},
-					body: JSON.stringify(requestBody),
-					signal: requestSignal,
+				const antigravityKey: ApiKey = ctx.modelRegistry.resolver("google-antigravity", {
+					sessionId,
 				});
 
-				if (!response.ok) {
-					const errorText = await response.text();
-					let message = errorText;
-					try {
-						const parsed = JSON.parse(errorText) as { error?: { message?: string } };
-						message = parsed.error?.message ?? message;
-					} catch {
-						// Keep raw text.
-					}
-					throw new Error(`Antigravity image request failed (${response.status}): ${message}`);
-				}
+				const response = await withAuth(
+					antigravityKey,
+					async key => {
+						// On a retry the resolver yields the raw stored credential JSON
+						// ({ token, projectId }); the initial seed is the already-parsed
+						// access token. Tolerate both, falling back to the seed projectId.
+						const rotated = parseAntigravityCredentials(key);
+						const bearer = rotated?.accessToken ?? key;
+						const projectId = rotated?.projectId ?? apiKey.projectId!;
+						const requestBody = buildAntigravityRequest(
+							prompt,
+							model,
+							projectId,
+							params.aspect_ratio,
+							params.image_size,
+							resolvedImages,
+						);
+
+						const resp = await fetch(`${ANTIGRAVITY_ENDPOINT}/v1internal:streamGenerateContent?alt=sse`, {
+							method: "POST",
+							headers: {
+								Authorization: `Bearer ${bearer}`,
+								"Content-Type": "application/json",
+								Accept: "text/event-stream",
+								"User-Agent": getAntigravityUserAgent(),
+							},
+							body: JSON.stringify(requestBody),
+							signal: requestSignal,
+						});
+
+						if (!resp.ok) {
+							const errorText = await resp.text();
+							let message = errorText;
+							try {
+								const parsedErr = JSON.parse(errorText) as { error?: { message?: string } };
+								message = parsedErr.error?.message ?? message;
+							} catch {
+								// Keep raw text.
+							}
+							throw Object.assign(new Error(`Antigravity image request failed (${resp.status}): ${message}`), {
+								status: resp.status,
+							});
+						}
+						return resp;
+					},
+					{ signal: requestSignal },
+				);
 
 				const parsed = await parseAntigravitySseForImage(response, requestSignal);
 				const responseText = parsed.text.length > 0 ? parsed.text.join(" ") : undefined;
@@ -1191,28 +1217,41 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 					: xaiBaseBody;
 				const xaiEndpoint = isEdit ? "/images/edits" : "/images/generations";
 
-				const xaiResponse = await fetch(`${xaiCreds.baseURL}${xaiEndpoint}`, {
-					method: "POST",
-					headers: {
-						Authorization: `Bearer ${xaiCreds.apiKey}`,
-						"Content-Type": "application/json",
-						"User-Agent": ohMyPiXAIUserAgent(),
-					},
-					body: JSON.stringify(xaiBody),
-					signal: requestSignal,
+				const xaiKey: ApiKey = ctx.modelRegistry.resolver(xaiCreds.provider, {
+					sessionId,
+					baseUrl: xaiCreds.baseURL,
 				});
 
-				const xaiRawText = await xaiResponse.text();
-				if (!xaiResponse.ok) {
-					let message = xaiRawText;
-					try {
-						const parsedErr = JSON.parse(xaiRawText) as { error?: { message?: string } };
-						message = parsedErr.error?.message ?? message;
-					} catch {
-						// Keep raw text.
-					}
-					throw new Error(`xAI image request failed (${xaiResponse.status}): ${message}`);
-				}
+				const xaiRawText = await withAuth(
+					xaiKey,
+					async key => {
+						const resp = await fetch(`${xaiCreds.baseURL}${xaiEndpoint}`, {
+							method: "POST",
+							headers: {
+								Authorization: `Bearer ${key}`,
+								"Content-Type": "application/json",
+								"User-Agent": ohMyPiXAIUserAgent(),
+							},
+							body: JSON.stringify(xaiBody),
+							signal: requestSignal,
+						});
+						const rawText = await resp.text();
+						if (!resp.ok) {
+							let message = rawText;
+							try {
+								const parsedErr = JSON.parse(rawText) as { error?: { message?: string } };
+								message = parsedErr.error?.message ?? message;
+							} catch {
+								// Keep raw text.
+							}
+							throw Object.assign(new Error(`xAI image request failed (${resp.status}): ${message}`), {
+								status: resp.status,
+							});
+						}
+						return rawText;
+					},
+					{ signal: requestSignal },
+				);
 
 				const xaiData = JSON.parse(xaiRawText) as {
 					data?: Array<{ b64_json?: string; url?: string }>;
@@ -1269,30 +1308,34 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 					messages: [{ role: "user" as const, content: contentParts }],
 				};
 
-				const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
-					method: "POST",
-					headers: {
-						"Content-Type": "application/json",
-						Authorization: `Bearer ${apiKey.apiKey}`,
-						"HTTP-Referer": "https://omp.sh/",
-						"X-OpenRouter-Title": "Oh-My-Pi",
-						"X-OpenRouter-Categories": "cli-agent",
-					},
-					body: JSON.stringify(requestBody),
-					signal: requestSignal,
-				});
-
-				const rawText = await response.text();
-				if (!response.ok) {
-					let message = rawText;
-					try {
-						const parsed = JSON.parse(rawText) as { error?: { message?: string } };
-						message = parsed.error?.message ?? message;
-					} catch {
-						// Keep raw text.
+				const rawText = await withAuth(apiKey.apiKey, async key => {
+					const resp = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+						method: "POST",
+						headers: {
+							"Content-Type": "application/json",
+							Authorization: `Bearer ${key}`,
+							"HTTP-Referer": "https://omp.sh/",
+							"X-OpenRouter-Title": "Oh-My-Pi",
+							"X-OpenRouter-Categories": "cli-agent",
+						},
+						body: JSON.stringify(requestBody),
+						signal: requestSignal,
+					});
+					const text = await resp.text();
+					if (!resp.ok) {
+						let message = text;
+						try {
+							const parsed = JSON.parse(text) as { error?: { message?: string } };
+							message = parsed.error?.message ?? message;
+						} catch {
+							// Keep raw text.
+						}
+						throw Object.assign(new Error(`OpenRouter image request failed (${resp.status}): ${message}`), {
+							status: resp.status,
+						});
 					}
-					throw new Error(`OpenRouter image request failed (${response.status}): ${message}`);
-				}
+					return text;
+				});
 
 				const data = JSON.parse(rawText) as OpenRouterResponse;
 				const message = data.choices?.[0]?.message;
@@ -1360,30 +1403,34 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 				generationConfig,
 			};
 
-			const response = await fetch(
-				`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`,
-				{
-					method: "POST",
-					headers: {
-						"Content-Type": "application/json",
-						"x-goog-api-key": apiKey.apiKey,
+			const rawText = await withAuth(apiKey.apiKey, async key => {
+				const resp = await fetch(
+					`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`,
+					{
+						method: "POST",
+						headers: {
+							"Content-Type": "application/json",
+							"x-goog-api-key": key,
+						},
+						body: JSON.stringify(requestBody),
+						signal: requestSignal,
 					},
-					body: JSON.stringify(requestBody),
-					signal: requestSignal,
-				},
-			);
-
-			const rawText = await response.text();
-			if (!response.ok) {
-				let message = rawText;
-				try {
-					const parsed = JSON.parse(rawText) as { error?: { message?: string } };
-					message = parsed.error?.message ?? message;
-				} catch {
-					// Keep raw text.
+				);
+				const text = await resp.text();
+				if (!resp.ok) {
+					let message = text;
+					try {
+						const parsed = JSON.parse(text) as { error?: { message?: string } };
+						message = parsed.error?.message ?? message;
+					} catch {
+						// Keep raw text.
+					}
+					throw Object.assign(new Error(`Gemini image request failed (${resp.status}): ${message}`), {
+						status: resp.status,
+					});
 				}
-				throw new Error(`Gemini image request failed (${response.status}): ${message}`);
-			}
+				return text;
+			});
 
 			const data = JSON.parse(rawText) as GeminiGenerateContentResponse;
 			const responseParts = combineParts(data);
diff --git a/packages/coding-agent/src/tools/inspect-image.ts b/packages/coding-agent/src/tools/inspect-image.ts
index 3759e5ed1..e7db9fc3c 100644
--- a/packages/coding-agent/src/tools/inspect-image.ts
+++ b/packages/coding-agent/src/tools/inspect-image.ts
@@ -4,6 +4,7 @@ import { type Api, completeSimple, type Model } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import { extractTextContent } from "../commit/utils";
+
 import { expandRoleAlias, resolveModelFromString } from "../config/model-resolver";
 import inspectImageDescription from "../prompts/tools/inspect-image.md" with { type: "text" };
 import inspectImageSystemPromptTemplate from "../prompts/tools/inspect-image-system.md" with { type: "text" };
@@ -136,7 +137,13 @@ export class InspectImageTool implements AgentTool<typeof inspectImageSchema, In
 					},
 				],
 			},
-			{ apiKey, signal },
+			{
+				apiKey: modelRegistry.resolver(model.provider, {
+					sessionId: this.session.getSessionId?.() ?? undefined,
+					baseUrl: model.baseUrl,
+				}),
+				signal,
+			},
 			{ telemetry, oneshotKind: "inspect_image", completeImpl: this.completeImageRequest },
 		);
 
diff --git a/packages/coding-agent/src/utils/commit-message-generator.ts b/packages/coding-agent/src/utils/commit-message-generator.ts
index 3e95d51a5..7346895c2 100644
--- a/packages/coding-agent/src/utils/commit-message-generator.ts
+++ b/packages/coding-agent/src/utils/commit-message-generator.ts
@@ -6,7 +6,7 @@ import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Api, Model } from "@oh-my-pi/pi-ai";
 import { completeSimple } from "@oh-my-pi/pi-ai";
 import { logger, prompt } from "@oh-my-pi/pi-utils";
-import { reuseInitialApiKey } from "../config/api-key-resolver";
+
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveModelRoleValue } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -112,7 +112,7 @@ export async function generateCommitMessage(
 					messages: [{ role: "user", content: userMessage, timestamp: Date.now() }],
 				},
 				{
-					apiKey: reuseInitialApiKey(apiKey, registry, candidate.model.provider, {
+					apiKey: registry.resolver(candidate.model.provider, {
 						sessionId,
 						baseUrl: candidate.model.baseUrl,
 					}),
diff --git a/packages/coding-agent/src/utils/title-generator.ts b/packages/coding-agent/src/utils/title-generator.ts
index cf71609e8..4761c5e60 100644
--- a/packages/coding-agent/src/utils/title-generator.ts
+++ b/packages/coding-agent/src/utils/title-generator.ts
@@ -6,7 +6,7 @@ import * as path from "node:path";
 import { type Api, type AssistantMessage, completeSimple, type Model, type Tool } from "@oh-my-pi/pi-ai";
 import { logger, prompt } from "@oh-my-pi/pi-utils";
 import type { ModelRegistry } from "../config/model-registry";
-import { reuseInitialApiKey } from "../config/api-key-resolver";
+
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
 import titleSystemPrompt from "../prompts/system/title-system.md" with { type: "text" };
@@ -239,7 +239,7 @@ export async function generateTitleOnline(
 				tools: [setTitleTool],
 			},
 			{
-				apiKey: reuseInitialApiKey(apiKey, registry, model.provider, { sessionId, baseUrl: model.baseUrl }),
+				apiKey: registry.resolver(model.provider, { sessionId, baseUrl: model.baseUrl }),
 				maxTokens,
 				disableReasoning: true,
 				toolChoice: { type: "tool", name: SET_TITLE_TOOL_NAME },
diff --git a/packages/coding-agent/src/web/search/providers/anthropic.ts b/packages/coding-agent/src/web/search/providers/anthropic.ts
index 07a2df740..5a62bb5d8 100644
--- a/packages/coding-agent/src/web/search/providers/anthropic.ts
+++ b/packages/coding-agent/src/web/search/providers/anthropic.ts
@@ -7,12 +7,14 @@
 import {
 	type AnthropicAuthConfig,
 	type AnthropicSystemBlock,
+	type ApiKey,
 	type AuthStorage,
 	buildAnthropicAuthConfig,
 	buildAnthropicSearchHeaders,
 	buildAnthropicSystemBlocks,
 	buildAnthropicUrl,
 	stripClaudeToolPrefix,
+	withAuth,
 } from "@oh-my-pi/pi-ai";
 import { $env } from "@oh-my-pi/pi-utils";
 import type {
@@ -247,18 +249,13 @@ export async function searchAnthropic(
 ): Promise<SearchResponse> {
 	const searchApiKey = $env.ANTHROPIC_SEARCH_API_KEY;
 	const searchBaseUrl = $env.ANTHROPIC_SEARCH_BASE_URL;
-	let auth: AnthropicAuthConfig | undefined;
+	const keyOrResolver: ApiKey | undefined = searchApiKey
+		? searchApiKey
+		: "authStorage" in params
+			? params.authStorage.resolver("anthropic", { sessionId: params.sessionId })
+			: undefined;
 
-	if (searchApiKey) {
-		auth = buildAnthropicAuthConfig(searchApiKey, searchBaseUrl);
-	} else if ("authStorage" in params) {
-		const apiKey = await params.authStorage.getApiKey("anthropic", params.sessionId, {
-			signal: params.signal,
-		});
-		if (apiKey) auth = buildAnthropicAuthConfig(apiKey, searchBaseUrl);
-	}
-
-	if (!auth) {
+	if (!keyOrResolver) {
 		throw new Error(
 			"No Anthropic credentials found. Set ANTHROPIC_SEARCH_API_KEY or ANTHROPIC_API_KEY, or configure Anthropic OAuth.",
 		);
@@ -267,14 +264,23 @@ export async function searchAnthropic(
 	const model = getModel();
 	const systemPrompt = "authStorage" in params ? params.systemPrompt : params.system_prompt;
 	const maxTokens = "authStorage" in params ? params.maxOutputTokens : params.max_tokens;
-	const response = await callSearch(
-		auth,
-		model,
-		params.query,
-		systemPrompt,
-		maxTokens,
-		params.temperature,
-		params.signal,
+	const response = await withAuth(
+		keyOrResolver,
+		key =>
+			callSearch(
+				buildAnthropicAuthConfig(key, searchBaseUrl),
+				model,
+				params.query,
+				systemPrompt,
+				maxTokens,
+				params.temperature,
+				params.signal,
+			),
+		{
+			signal: params.signal,
+			missingKeyMessage:
+				"No Anthropic credentials found. Set ANTHROPIC_SEARCH_API_KEY or ANTHROPIC_API_KEY, or configure Anthropic OAuth.",
+		},
 	);
 
 	const result = parseResponse(response);
diff --git a/packages/coding-agent/src/web/search/providers/exa.ts b/packages/coding-agent/src/web/search/providers/exa.ts
index bbca2a5b7..7c0642cbd 100644
--- a/packages/coding-agent/src/web/search/providers/exa.ts
+++ b/packages/coding-agent/src/web/search/providers/exa.ts
@@ -6,7 +6,7 @@
  * Requests per-result summaries via `contents.summary` and synthesizes
  * them into a combined `answer` string on the SearchResponse.
  */
-import { type AuthStorage, getEnvApiKey } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type AuthStorage, getEnvApiKey, withAuth } from "@oh-my-pi/pi-ai";
 import { settings } from "../../../config/settings";
 import { callExaTool, findApiKey, isSearchResponse } from "../../../exa/mcp-client";
 
@@ -228,11 +228,19 @@ async function callExaMcpSearch(params: ExaSearchParams): Promise<ExaSearchRespo
 
 /** Execute Exa web search */
 export async function searchExa(params: ExaSearchParams): Promise<SearchResponse> {
+	// AuthStorage-backed key takes precedence (existing behavior); probe it once
+	// so the env-key and keyless-MCP fallbacks below stay intact, then drive the
+	// authStorage path through the central force-refresh/rotate retry policy.
 	const storedKey = params.authStorage
 		? await params.authStorage.getApiKey("exa", params.sessionId, { signal: params.signal })
 		: undefined;
-	const apiKey = storedKey ?? getEnvApiKey("exa");
-	const response = apiKey ? await callExaSearch(apiKey, params) : await callExaMcpSearch(params);
+	const keyOrResolver: ApiKey | undefined =
+		storedKey && params.authStorage
+			? params.authStorage.resolver("exa", { sessionId: params.sessionId })
+			: getEnvApiKey("exa");
+	const response = keyOrResolver
+		? await withAuth(keyOrResolver, key => callExaSearch(key, params), { signal: params.signal })
+		: await callExaMcpSearch(params);
 
 	// Convert to unified SearchResponse
 	const sources: SearchSource[] = [];
diff --git a/packages/coding-agent/src/web/search/providers/kimi.ts b/packages/coding-agent/src/web/search/providers/kimi.ts
index 2bc8d53b1..08401dbe6 100644
--- a/packages/coding-agent/src/web/search/providers/kimi.ts
+++ b/packages/coding-agent/src/web/search/providers/kimi.ts
@@ -4,7 +4,7 @@
  * Uses Moonshot Kimi Code search API to retrieve web results.
  * Endpoint: POST https://api.kimi.com/coding/v1/search
  */
-import type { AuthStorage } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type AuthStorage, withAuth } from "@oh-my-pi/pi-ai";
 import { $env } from "@oh-my-pi/pi-utils";
 
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
@@ -54,20 +54,26 @@ function resolveBaseUrl(): string {
 	return asTrimmed($env.MOONSHOT_SEARCH_BASE_URL) ?? asTrimmed($env.KIMI_SEARCH_BASE_URL) ?? KIMI_SEARCH_URL;
 }
 
-/** Find Kimi search credentials from environment or AuthStorage. */
-async function findApiKey(
+/**
+ * Resolve the Kimi search credential. Highest precedence is the static env key;
+ * otherwise an AuthStorage-backed resolver for whichever stored provider id
+ * holds a key (`moonshot` first, then `kimi-code`), so a stale token triggers
+ * the central force-refresh / sibling-rotate retry. Returns `undefined` when
+ * neither is configured.
+ */
+async function resolveKey(
 	authStorage: AuthStorage,
 	sessionId: string | undefined,
 	signal: AbortSignal | undefined,
-): Promise<string | null> {
+): Promise<ApiKey | undefined> {
 	const envKey = asTrimmed($env.MOONSHOT_SEARCH_API_KEY) ?? asTrimmed($env.KIMI_SEARCH_API_KEY);
 	if (envKey) return envKey;
 
-	return (
-		(await authStorage.getApiKey("moonshot", sessionId, { signal })) ??
-		(await authStorage.getApiKey("kimi-code", sessionId, { signal })) ??
-		null
-	);
+	for (const provider of ["moonshot", "kimi-code"] as const) {
+		const stored = await authStorage.getApiKey(provider, sessionId, { signal });
+		if (stored) return authStorage.resolver(provider, { sessionId });
+	}
+	return undefined;
 }
 
 async function callKimiSearch(
@@ -108,20 +114,25 @@ async function callKimiSearch(
 
 /** Execute Kimi web search. */
 export async function searchKimi(params: KimiSearchParams): Promise<SearchResponse> {
-	const apiKey = await findApiKey(params.authStorage, params.sessionId, params.signal);
-	if (!apiKey) {
+	const keyOrResolver = await resolveKey(params.authStorage, params.sessionId, params.signal);
+	if (!keyOrResolver) {
 		throw new Error(
 			"Kimi search credentials not found. Set MOONSHOT_SEARCH_API_KEY, KIMI_SEARCH_API_KEY, MOONSHOT_API_KEY, or login with 'omp /login moonshot'.",
 		);
 	}
 
 	const limit = clampNumResults(params.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
-	const { response, requestId } = await callKimiSearch(apiKey, {
-		query: params.query,
-		limit,
-		includeContent: params.include_content ?? false,
-		signal: params.signal,
-	});
+	const { response, requestId } = await withAuth(
+		keyOrResolver,
+		key =>
+			callKimiSearch(key, {
+				query: params.query,
+				limit,
+				includeContent: params.include_content ?? false,
+				signal: params.signal,
+			}),
+		{ signal: params.signal },
+	);
 	const sources: SearchSource[] = [];
 
 	for (const result of response.search_results ?? []) {
diff --git a/packages/coding-agent/src/web/search/providers/parallel.ts b/packages/coding-agent/src/web/search/providers/parallel.ts
index 19f1b8164..876ef4a8c 100644
--- a/packages/coding-agent/src/web/search/providers/parallel.ts
+++ b/packages/coding-agent/src/web/search/providers/parallel.ts
@@ -1,4 +1,4 @@
-import { type AuthStorage, getEnvApiKey } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type AuthStorage, getEnvApiKey, withAuth } from "@oh-my-pi/pi-ai";
 import type { SearchResponse } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import { ParallelApiError, type ParallelSearchResult, type ParallelSearchSource } from "../../parallel";
@@ -123,30 +123,41 @@ async function searchWithAuthStorage(
 		);
 	}
 
-	const response = await fetch(PARALLEL_SEARCH_URL, {
-		method: "POST",
-		headers: {
-			Accept: "application/json",
-			"Content-Type": "application/json",
-			"x-api-key": apiKey,
-			"parallel-beta": PARALLEL_BETA_HEADER,
-		},
-		body: JSON.stringify({
-			objective,
-			search_queries: queries,
-			mode: "fast",
-			excerpts: {
-				max_chars_per_result: 10_000,
-			},
-		}),
-		signal: withHardTimeout(params.signal),
-	});
-	if (!response.ok) {
-		throw parseParallelErrorResponse(response.status, await response.text());
-	}
+	// Drive the (already-present) credential through the central force-refresh /
+	// sibling-rotate retry policy. The `ParallelApiError` thrown below carries a
+	// `statusCode`, which `withAuth`'s default classifier reads to detect a
+	// retryable 401 / usage-limit.
+	const keyOrResolver: ApiKey = authStorage.resolver("parallel", { sessionId });
+	return withAuth(
+		keyOrResolver,
+		async key => {
+			const response = await fetch(PARALLEL_SEARCH_URL, {
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+					"x-api-key": key,
+					"parallel-beta": PARALLEL_BETA_HEADER,
+				},
+				body: JSON.stringify({
+					objective,
+					search_queries: queries,
+					mode: "fast",
+					excerpts: {
+						max_chars_per_result: 10_000,
+					},
+				}),
+				signal: withHardTimeout(params.signal),
+			});
+			if (!response.ok) {
+				throw parseParallelErrorResponse(response.status, await response.text());
+			}
 
-	const payload: unknown = await response.json();
-	return parseSearchPayload(payload);
+			const payload: unknown = await response.json();
+			return parseSearchPayload(payload);
+		},
+		{ signal: params.signal },
+	);
 }
 
 export async function searchParallel(
diff --git a/packages/coding-agent/src/web/search/providers/synthetic.ts b/packages/coding-agent/src/web/search/providers/synthetic.ts
index c531a9a65..12d4a6ca1 100644
--- a/packages/coding-agent/src/web/search/providers/synthetic.ts
+++ b/packages/coding-agent/src/web/search/providers/synthetic.ts
@@ -5,7 +5,7 @@
  * Endpoint: POST https://api.synthetic.new/v2/search
  */
 
-import { type AuthStorage, getEnvApiKey } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type AuthStorage, getEnvApiKey, withAuth } from "@oh-my-pi/pi-ai";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import type { SearchParams } from "./base";
@@ -66,12 +66,14 @@ async function callSyntheticSearch(
 
 /** Execute Synthetic web search. */
 export async function searchSynthetic(params: SearchParams): Promise<SearchResponse> {
-	const apiKey = await findApiKey(params.authStorage, params.sessionId, params.signal);
-	if (!apiKey) {
-		throw new Error("Synthetic credentials not found. Set SYNTHETIC_API_KEY or login with 'omp /login synthetic'.");
-	}
+	const keyOrResolver: ApiKey = params.authStorage.resolver("synthetic", {
+		sessionId: params.sessionId,
+	});
 
-	const data = await callSyntheticSearch(apiKey, params.query, params.signal);
+	const data = await withAuth(keyOrResolver, key => callSyntheticSearch(key, params.query, params.signal), {
+		signal: params.signal,
+		missingKeyMessage: "Synthetic credentials not found. Set SYNTHETIC_API_KEY or login with 'omp /login synthetic'.",
+	});
 	const sources: SearchSource[] = [];
 
 	for (const result of data.results ?? []) {
diff --git a/packages/coding-agent/src/web/search/providers/tavily.ts b/packages/coding-agent/src/web/search/providers/tavily.ts
index a32a27856..9b5e0a9f3 100644
--- a/packages/coding-agent/src/web/search/providers/tavily.ts
+++ b/packages/coding-agent/src/web/search/providers/tavily.ts
@@ -4,7 +4,7 @@
  * Uses Tavily's agent-focused search API to return structured results with an
  * optional synthesized answer.
  */
-import { type AuthStorage, getEnvApiKey } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type AuthStorage, getEnvApiKey, withAuth } from "@oh-my-pi/pi-ai";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import { clampNumResults, dateToAgeSeconds } from "../utils";
@@ -127,15 +127,16 @@ export async function searchTavily(params: SearchParams): Promise<SearchResponse
 		recency: params.recency,
 		signal: params.signal,
 	};
-	const apiKey = await findApiKey(params.authStorage, params.sessionId, params.signal);
-	if (!apiKey) {
-		throw new Error(
-			'Tavily credentials not found. Set TAVILY_API_KEY or configure an API key for provider "tavily".',
-		);
-	}
+	const keyOrResolver: ApiKey = params.authStorage.resolver("tavily", {
+		sessionId: params.sessionId,
+	});
 
 	const numResults = clampNumResults(tavilyParams.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
-	const response = await callTavilySearch(apiKey, tavilyParams);
+	const response = await withAuth(keyOrResolver, key => callTavilySearch(key, tavilyParams), {
+		signal: params.signal,
+		missingKeyMessage:
+			'Tavily credentials not found. Set TAVILY_API_KEY or configure an API key for provider "tavily".',
+	});
 	const sources: SearchSource[] = [];
 
 	for (const result of response.results ?? []) {
diff --git a/packages/coding-agent/src/web/search/providers/zai.ts b/packages/coding-agent/src/web/search/providers/zai.ts
index 4795038b8..2f39ff682 100644
--- a/packages/coding-agent/src/web/search/providers/zai.ts
+++ b/packages/coding-agent/src/web/search/providers/zai.ts
@@ -4,7 +4,7 @@
  * Calls Z.AI's remote MCP server (`webSearchPrime`) and adapts results into
  * the unified SearchResponse shape used by the web search tool.
  */
-import { type AuthStorage, getEnvApiKey } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type AuthStorage, getEnvApiKey, withAuth } from "@oh-my-pi/pi-ai";
 import { asRecord, asString } from "../../../web/scrapers/utils";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
@@ -278,12 +278,14 @@ function toSources(results: ZaiSearchResult[]): SearchSource[] {
 
 /** Execute Z.AI web search via remote MCP endpoint. */
 export async function searchZai(params: ZaiSearchParams): Promise<SearchResponse> {
-	const apiKey = await findApiKey(params.authStorage, params.sessionId, params.signal);
-	if (!apiKey) {
-		throw new Error("Z.AI credentials not found. Set ZAI_API_KEY or login with 'omp /login zai'.");
-	}
+	const keyOrResolver: ApiKey = params.authStorage.resolver("zai", {
+		sessionId: params.sessionId,
+	});
 
-	const rawResult = await callZaiSearch(apiKey, params);
+	const rawResult = await withAuth(keyOrResolver, key => callZaiSearch(key, params), {
+		signal: params.signal,
+		missingKeyMessage: "Z.AI credentials not found. Set ZAI_API_KEY or login with 'omp /login zai'.",
+	});
 	const payload = parseSearchPayload(rawResult);
 	let sources = toSources(payload.results);
 
diff --git a/packages/coding-agent/test/commit-model-selection-role-thinking.test.ts b/packages/coding-agent/test/commit-model-selection-role-thinking.test.ts
index 71d8134ec..f5cffc8f5 100644
--- a/packages/coding-agent/test/commit-model-selection-role-thinking.test.ts
+++ b/packages/coding-agent/test/commit-model-selection-role-thinking.test.ts
@@ -39,7 +39,8 @@ describe("commit role thinking selection", () => {
 			getAvailable: () => [defaultModel, commitModel],
 			getApiKey: async () => "test-key",
 			getApiKeyForProvider: async () => "test-key",
-			authStorage: { rotateSessionCredential: async () => false },
+			authStorage: { rotateSessionCredential: async () => false as const },
+			resolver: () => async () => "test-key",
 		};
 
 		const primary = await resolvePrimaryModel(undefined, settings, registry);
diff --git a/packages/coding-agent/test/title-generator.test.ts b/packages/coding-agent/test/title-generator.test.ts
index dc1a6b4a4..46069a57f 100644
--- a/packages/coding-agent/test/title-generator.test.ts
+++ b/packages/coding-agent/test/title-generator.test.ts
@@ -29,6 +29,9 @@ function createRegistry(model: Model<Api>) {
 	return {
 		getAvailable: () => [model],
 		getApiKey: async () => "test-key",
+		getApiKeyForProvider: async () => "test-key",
+		authStorage: { rotateSessionCredential: async () => false },
+		resolver: () => async () => "test-key",
 	} as never;
 }
 
diff --git a/packages/coding-agent/test/tools/image-gen.test.ts b/packages/coding-agent/test/tools/image-gen.test.ts
index 74b5182db..2ecdaa8bc 100644
--- a/packages/coding-agent/test/tools/image-gen.test.ts
+++ b/packages/coding-agent/test/tools/image-gen.test.ts
@@ -62,6 +62,8 @@ describe("imageGenTool", () => {
 			modelRegistry: {
 				getApiKey: async () => "test-openai-key",
 				getApiKeyForProvider: async () => undefined,
+				authStorage: { rotateSessionCredential: async () => false },
+				resolver: () => async () => "test-openai-key",
 			} as unknown as ModelRegistry,
 			model,
 			isIdle: () => true,
@@ -126,7 +128,9 @@ describe("imageGenTool", () => {
 				getAll: () => [],
 				authStorage: {
 					hasNonEnvCredential: (provider: string) => provider === "xai-oauth",
+					rotateSessionCredential: async () => false,
 				},
+				resolver: () => async () => "test-xai-token",
 			} as unknown as ModelRegistry,
 			model: undefined,
 			isIdle: () => true,
diff --git a/packages/coding-agent/test/tools/inspect-image.test.ts b/packages/coding-agent/test/tools/inspect-image.test.ts
index fe27a38cb..8345c1865 100644
--- a/packages/coding-agent/test/tools/inspect-image.test.ts
+++ b/packages/coding-agent/test/tools/inspect-image.test.ts
@@ -68,6 +68,9 @@ function createSession(
 		modelRegistry: {
 			getAvailable: () => availableModels,
 			getApiKey: async () => apiKey,
+			getApiKeyForProvider: async () => apiKey,
+			authStorage: { rotateSessionCredential: async () => false },
+			resolver: () => async () => apiKey,
 		} as unknown as NonNullable<ToolSession["modelRegistry"]>,
 	};
 }
diff --git a/packages/coding-agent/test/tools/search-renderer.test.ts b/packages/coding-agent/test/tools/search-renderer.test.ts
index 13f1c7f32..38d04c0ec 100644
--- a/packages/coding-agent/test/tools/search-renderer.test.ts
+++ b/packages/coding-agent/test/tools/search-renderer.test.ts
@@ -52,7 +52,7 @@ describe("searchToolRenderer", () => {
 			},
 		);
 		const renderedLines = sanitizeText(collapsed.render(200).join("\n")).split("\n");
-		const bodyLines = renderedLines.slice(1);
+		const bodyLines = renderedLines.slice(1, -1);
 
 		expect(renderedLines[0]).toContain("truncated");
 		expect(bodyLines).toHaveLength(6);
@@ -93,7 +93,7 @@ describe("searchToolRenderer", () => {
 			{ pattern: "Flag" },
 		);
 		const renderedLines = sanitizeText(collapsed.render(240).join("\n")).split("\n");
-		const bodyLines = renderedLines.slice(1);
+		const bodyLines = renderedLines.slice(1, -1);
 
 		expect(bodyLines).toHaveLength(6);
 		expect(bodyLines.some(line => line.includes("const firstFlag = true;"))).toBe(true);
diff --git a/packages/coding-agent/test/tools/web-search-parallel.test.ts b/packages/coding-agent/test/tools/web-search-parallel.test.ts
index 2fa5f6d55..1886417cb 100644
--- a/packages/coding-agent/test/tools/web-search-parallel.test.ts
+++ b/packages/coding-agent/test/tools/web-search-parallel.test.ts
@@ -30,6 +30,12 @@ describe("Parallel web search", () => {
 		hasAuth() {
 			return Boolean(process.env.PARALLEL_API_KEY);
 		},
+		resolver(_provider: string) {
+			return async () => process.env.PARALLEL_API_KEY ?? undefined;
+		},
+		async rotateSessionCredential() {
+			return false;
+		},
 	} as unknown as AuthStorage;
 
 	let capturedRequestBody: unknown;
diff --git a/packages/coding-agent/test/tools/web-search-tavily.test.ts b/packages/coding-agent/test/tools/web-search-tavily.test.ts
index a260179c7..bea6429f1 100644
--- a/packages/coding-agent/test/tools/web-search-tavily.test.ts
+++ b/packages/coding-agent/test/tools/web-search-tavily.test.ts
@@ -21,6 +21,12 @@ describe("Tavily web search provider", () => {
 		hasAuth() {
 			return Boolean(process.env.TAVILY_API_KEY);
 		},
+		resolver(_provider: string) {
+			return async () => process.env.TAVILY_API_KEY ?? undefined;
+		},
+		async rotateSessionCredential() {
+			return false;
+		},
 	} as unknown as AuthStorage;
 
 	function makeParams(query: string) {

From 9a8bf1c81cdac37aa8a6554d0da043a1d9596f86 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 04:53:59 +0200
Subject: [PATCH 087/181] feat(coding-agent): added mouse interactions and
 preserved deleted headings in plan reviews

- Added SGR mouse input handling for wheel and click actions, mapped to option, ToC, and body targets.
- Added deleted-heading state to undo snapshots so removed titles persist and restore correctly.
- Updated the plan-mode active prompt to require decision-complete, implementation-ready plans.
- Enabled mouse tracking for fullscreen overlays and asserted mouse-on/off sequences in tests.
---
 .../modes/components/plan-review-overlay.ts   | 119 +++++++++++++++--
 .../src/prompts/system/plan-mode-active.md    | 123 ++++++++++--------
 .../components/plan-review-overlay.test.ts    |  53 ++++++++
 packages/tui/CHANGELOG.md                     |   2 +-
 packages/tui/src/tui.ts                       |  11 +-
 packages/tui/test/render-regressions.test.ts  |   9 +-
 6 files changed, 242 insertions(+), 75 deletions(-)

diff --git a/packages/coding-agent/src/modes/components/plan-review-overlay.ts b/packages/coding-agent/src/modes/components/plan-review-overlay.ts
index e3f7d6292..ef74ae7ea 100644
--- a/packages/coding-agent/src/modes/components/plan-review-overlay.ts
+++ b/packages/coding-agent/src/modes/components/plan-review-overlay.ts
@@ -68,10 +68,12 @@ interface OverlaySection {
 	annotations: string[];
 }
 
-/** Undo snapshot: the joined plan text plus annotations aligned by section. */
+/** Undo snapshot: joined plan text, annotations aligned by section, and the
+ *  accumulated deleted-section feedback at the time of the snapshot. */
 interface UndoEntry {
 	text: string;
 	annotations: string[][];
+	deleted: string[];
 }
 
 export interface PlanReviewOverlayCallbacks {
@@ -115,6 +117,8 @@ export class PlanReviewOverlay implements Component {
 	#tocBaseLevel = 1;
 	#sectionOffsets: number[] = [];
 	#undo: UndoEntry[] = [];
+	/** Titles of sections deleted in the overlay, surfaced as Refine feedback. */
+	#deleted: string[] = [];
 
 	#options: string[];
 	#disabled: Set<number>;
@@ -130,6 +134,14 @@ export class PlanReviewOverlay implements Component {
 	#sidebarShown = false;
 	#pendingScrollToToc = false;
 
+	// Click hit-testing, rebuilt every render. Keys are 0-based rendered-line
+	// indices (== screen rows, since the fullscreen overlay paints from row 0).
+	#optionClickRows = new Map<number, number>();
+	#tocClickRows = new Map<number, number>();
+	#bodyClickRows = new Set<number>();
+	/** 1-based column at/under which a region-row click targets the sidebar. */
+	#sidebarClickMaxCol = 0;
+
 	#annotating = false;
 	#input: Input;
 
@@ -177,6 +189,9 @@ export class PlanReviewOverlay implements Component {
 		this.#setSections(planContent);
 		this.#scrollView.scrollToTop();
 		this.#tocCursor = 0;
+		// A wholesale external-editor swap supersedes prior in-overlay deletions.
+		this.#deleted = [];
+		this.#undo = [];
 		this.#recomputeFeedback();
 	}
 
@@ -262,6 +277,7 @@ export class PlanReviewOverlay implements Component {
 	}
 
 	handleInput(keyData: string): void {
+		if (keyData.startsWith("\x1b[<") && this.#handleMouse(keyData)) return;
 		if (this.#annotating) {
 			this.#input.handleInput(keyData);
 			return;
@@ -295,6 +311,50 @@ export class PlanReviewOverlay implements Component {
 		}
 	}
 
+	/**
+	 * Hit-test an SGR mouse report (`\x1b[<b;x;yM/m`) against the click maps the
+	 * last render recorded. Returns true when consumed. The fullscreen overlay
+	 * paints from screen row 0, so a 1-based mouse row maps directly to the
+	 * rendered-line index. Wheel scrolls the body; a left click on an option
+	 * activates it (select + confirm), on a ToC row jumps to that section, and on
+	 * the body column focuses the body.
+	 */
+	#handleMouse(data: string): boolean {
+		const match = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(data);
+		if (!match) return false;
+		const button = Number(match[1]);
+		const x = Number(match[2]);
+		const row = Number(match[3]) - 1;
+		if (button & 64) {
+			// Scroll wheel: low bit selects direction (64 up, 65 down).
+			this.#scrollView.scroll(button & 1 ? 3 : -3);
+			return true;
+		}
+		if (match[4] !== "M") return true; // release
+		if (button & 32) return true; // motion/drag
+		if ((button & 3) !== 0) return true; // not the left button
+		const optionIndex = this.#optionClickRows.get(row);
+		if (optionIndex !== undefined) {
+			if (!this.#disabled.has(optionIndex)) {
+				this.#focus = "actions";
+				this.#selectedIndex = optionIndex;
+				this.#confirmSelection();
+			}
+			return true;
+		}
+		const tocPos = this.#tocClickRows.get(row);
+		if (tocPos !== undefined && x <= this.#sidebarClickMaxCol) {
+			this.#focus = "toc";
+			this.#tocCursor = tocPos;
+			this.#scrubBodyToToc();
+			return true;
+		}
+		if (this.#bodyClickRows.has(row)) {
+			this.#setFocus("body");
+		}
+		return true;
+	}
+
 	#cycleRegion(direction: number): void {
 		// Sidebar is skipped from the cycle when it is not shown.
 		const regions: Focus[] = this.#sidebarShown ? ["toc", "body", "actions"] : ["body", "actions"];
@@ -453,6 +513,7 @@ export class PlanReviewOverlay implements Component {
 		this.#undo.push({
 			text: joinPlanSections(this.#sections),
 			annotations: this.#sections.map(section => [...section.annotations]),
+			deleted: [...this.#deleted],
 		});
 	}
 
@@ -462,6 +523,12 @@ export class PlanReviewOverlay implements Component {
 		const span = sectionDeletionSpan(this.#sections, sectionIndex);
 		if (span.length === 0) return;
 		this.#pushUndo();
+		// Record the removed headings so the Refine feedback can ask the model to
+		// drop them, then splice from the bottom up so earlier indices stay valid.
+		for (const i of span) {
+			const section = this.#sections[i]!;
+			if (section.level >= 1 && section.title) this.#deleted.push(section.title);
+		}
 		for (let i = span.length - 1; i >= 0; i--) this.#sections.splice(span[i]!, 1);
 		this.#rebuildToc();
 		this.#tocCursor = Math.min(this.#tocCursor, Math.max(0, this.#toc.length - 1));
@@ -477,6 +544,7 @@ export class PlanReviewOverlay implements Component {
 		for (let i = 0; i < this.#sections.length; i++) {
 			this.#sections[i]!.annotations = entry.annotations[i] ? [...entry.annotations[i]!] : [];
 		}
+		this.#deleted = [...entry.deleted];
 		this.#tocCursor = Math.min(this.#tocCursor, Math.max(0, this.#toc.length - 1));
 		this.#pendingScrollToToc = true;
 		this.callbacks.onPlanEdited?.(joinPlanSections(this.#sections));
@@ -508,13 +576,18 @@ export class PlanReviewOverlay implements Component {
 
 	#recomputeFeedback(): void {
 		const annotated = this.#sections.filter(section => section.level >= 1 && section.annotations.length > 0);
-		let feedback = "";
-		if (annotated.length > 0) {
-			feedback = "Refinement feedback on the plan:\n";
-			for (const section of annotated) {
-				feedback += `\n## ${section.title}\n`;
-				for (const note of section.annotations) feedback += `- ${note}\n`;
-			}
+		if (annotated.length === 0 && this.#deleted.length === 0) {
+			this.callbacks.onFeedbackChange?.("");
+			return;
+		}
+		let feedback = "Refinement feedback on the plan:\n";
+		if (this.#deleted.length > 0) {
+			feedback += "\nRemove these sections:\n";
+			for (const title of this.#deleted) feedback += `- ${title}\n`;
+		}
+		for (const section of annotated) {
+			feedback += `\n## ${section.title}\n`;
+			for (const note of section.annotations) feedback += `- ${note}\n`;
 		}
 		this.callbacks.onFeedbackChange?.(feedback);
 	}
@@ -603,11 +676,16 @@ export class PlanReviewOverlay implements Component {
 		return splitBodyWidth(width, this.#sidebarWidthFor(width)) >= SIDEBAR_MIN_BODY_WIDTH;
 	}
 
-	#renderSidebarLines(regionRows: number, sidebarWidth: number): string[] {
+	/** Sidebar lines plus, per row, the ToC position shown there (for clicks). */
+	#renderSidebarLines(
+		regionRows: number,
+		sidebarWidth: number,
+	): { lines: string[]; posForRow: (number | undefined)[] } {
 		// No "Contents" label and no plan-title entry: the box title already says
 		// "Plan Review", so the sidebar is just the bare list of sections, VS
 		// Code-style. Window the entries around the cursor.
 		const lines: string[] = [];
+		const posForRow: (number | undefined)[] = [];
 		const slots = Math.max(0, regionRows);
 		const total = this.#toc.length;
 		let start = 0;
@@ -617,8 +695,9 @@ export class PlanReviewOverlay implements Component {
 		for (let r = 0; r < slots; r++) {
 			const p = start + r;
 			lines.push(p < total ? this.#renderTocEntry(p, sidebarWidth) : "");
+			posForRow.push(p < total ? p : undefined);
 		}
-		return lines;
+		return { lines, posForRow };
 	}
 
 	#renderTocEntry(p: number, width: number): string {
@@ -682,22 +761,36 @@ export class PlanReviewOverlay implements Component {
 		if (this.#focus !== "toc") this.#tocCursor = this.#deriveTocCursorFromScroll();
 		const body = this.#scrollView.render(bodyContentWidth);
 
+		this.#optionClickRows.clear();
+		this.#tocClickRows.clear();
+		this.#bodyClickRows.clear();
+		this.#sidebarClickMaxCol = sidebarShown ? sidebarWidth + 3 : 0;
+
 		const out: string[] = [];
 		if (sidebarShown) {
-			const sidebar = this.#renderSidebarLines(regionRows, sidebarWidth);
+			const { lines: sidebar, posForRow } = this.#renderSidebarLines(regionRows, sidebarWidth);
 			out.push(topBorderSplit(width, OVERLAY_TITLE, sidebarWidth));
 			for (let i = 0; i < regionRows; i++) {
+				const pos = posForRow[i];
+				if (pos !== undefined) this.#tocClickRows.set(out.length, pos);
+				this.#bodyClickRows.add(out.length);
 				out.push(splitRow(sidebar[i] ?? "", body[i] ?? "", width, sidebarWidth));
 			}
 			out.push(dividerSplit(width, sidebarWidth));
 		} else {
 			out.push(topBorder(width, OVERLAY_TITLE));
-			for (const line of body) out.push(row(line, width));
+			for (const line of body) {
+				this.#bodyClickRows.add(out.length);
+				out.push(row(line, width));
+			}
 			out.push(divider(width));
 		}
 		for (const line of promptLines) out.push(row(line, width));
 		for (const line of sliderLines) out.push(row(line, width));
-		for (const line of optionLines) out.push(row(line, width));
+		for (let i = 0; i < optionLines.length; i++) {
+			this.#optionClickRows.set(out.length, i);
+			out.push(row(optionLines[i]!, width));
+		}
 		out.push(divider(width));
 		for (const line of footerLines) out.push(row(line, width));
 		out.push(bottomBorder(width));
diff --git a/packages/coding-agent/src/prompts/system/plan-mode-active.md b/packages/coding-agent/src/prompts/system/plan-mode-active.md
index 8c692604b..f6ee4a794 100644
--- a/packages/coding-agent/src/prompts/system/plan-mode-active.md
+++ b/packages/coding-agent/src/prompts/system/plan-mode-active.md
@@ -11,6 +11,10 @@ To implement: call `resolve` with `action: "apply"`, a `reason`, and `extra: { t
 You NEVER ask the user to exit plan mode for you; you MUST call `resolve` yourself.
 </critical>
 
+## Objective
+
+A plan is **decision-complete**: another engineer or agent can execute it end-to-end without making a single design decision. Optimize every choice for that. Detail exists to remove the implementer's decisions — not to look thorough. A document that reads like a design doc (Non-Goals, Alternatives, risk matrices) yet leaves real decisions open is a FAILED plan.
+
 ## Plan File
 
 {{#if planExists}}
@@ -19,98 +23,103 @@ Plan file exists at `{{planFilePath}}`; you MUST read and update it incrementall
 You MUST create a plan at `{{planFilePath}}`.
 {{/if}}
 
-You MUST use `{{editToolName}}` for incremental updates; use `{{writeToolName}}` only for create/full replace.
+You MUST use `{{editToolName}}` for incremental updates; use `{{writeToolName}}` only for create/full replace. You MUST update the plan as you learn — you NEVER batch all writing to the end.
 
-<caution>
-The approval selector includes:
-- **Approve and execute**: starts execution in fresh context (session cleared).
-- **Approve and compact context**: distills the plan-mode discussion into a summary, then starts execution in this session.
-- **Approve and keep context**: starts execution in this session, preserving exploration history.
+## Resolving Unknowns
 
-You MUST still make the plan file self-contained: include requirements, decisions, key findings, and remaining todos.
-</caution>
+You MUST eliminate unknowns by discovering facts, not by asking. Before asking the user anything, perform at least one targeted exploration pass.
+
+Two kinds of unknowns, treated differently:
+- **Discoverable facts** — repo/system truth: file locations, current behavior, existing patterns, types, configs. You MUST explore first (`find`, `search`, `read`, parallel explore subagents). You NEVER ask what the codebase can answer (e.g. "where is this defined?"). Ask only when several plausible candidates remain or a required identifier is genuinely absent — and then present the candidates with a recommendation.
+- **Preferences and tradeoffs** — intent, UX, scope boundaries, performance-vs-simplicity: not derivable from code. You MUST surface these early via `{{askToolName}}` with 2–4 mutually exclusive options and a recommended default. If left unanswered, proceed with the default and record it under Assumptions.
+
+Every question MUST materially change the plan, confirm a load-bearing assumption, or choose between real tradeoffs. You MUST batch questions. You NEVER ask filler questions or offer obviously-wrong options.
 
 {{#if reentry}}
 ## Re-entry
 
 <procedure>
-1. Read existing plan
-2. Evaluate request against it
+1. Read the existing plan.
+2. Evaluate the new request against it.
 3. Decide:
-   - **Different task** → Overwrite plan
-   - **Same task, continuing** → Update and clean outdated sections
-4. Call `resolve` with `action: "apply"` and `extra: { title }` when complete
+   - **Different task** → overwrite the plan.
+   - **Same task, continuing** → update and delete outdated sections.
+4. Call `resolve` with `action: "apply"` and `extra: { title }` when complete.
 </procedure>
 {{/if}}
 
 {{#if iterative}}
-## Iterative Planning
+## Workflow — Iterative
 
 <procedure>
 ### 1. Explore
-You MUST use `find`, `search`, `read` to understand the codebase.
+You MUST use `find`, `search`, `read` to ground yourself in the actual code. Hunt for existing functions, utilities, and conventions to reuse before proposing anything new.
 
 ### 2. Interview
-You MUST use `{{askToolName}}` to clarify:
-- Ambiguous requirements
-- Technical decisions and tradeoffs
-- Preferences: UI/UX, performance, edge cases
+You MUST use `{{askToolName}}` to resolve preferences and tradeoffs (see Resolving Unknowns). Batch questions; never ask what exploration answers.
 
-You MUST batch questions. You NEVER ask what you can answer by exploring.
-
-### 3. Update Incrementally
-You MUST use `{{editToolName}}` to update plan file as you learn; NEVER wait until end.
+### 3. Update incrementally
+You MUST use `{{editToolName}}` to revise the plan file as you learn.
 
 ### 4. Calibrate
-- Large unspecified task → multiple interview rounds
-- Smaller task → fewer or no questions
+- Large, unspecified task → multiple interview rounds.
+- Small, well-specified task → few or no questions.
 </procedure>
-
-<caution>
-### Plan Structure
-
-You MUST use clear markdown headers; include:
-- Recommended approach (not alternatives)
-- Paths of critical files to modify
-- Verification: how to test end-to-end
-
-The plan MUST be scannable yet detailed enough to execute.
-</caution>
-
 {{else}}
-## Planning Workflow
+## Workflow — Parallel
 
 <procedure>
-### Phase 1: Understand
-You MUST focus on the request and associated code. You SHOULD launch parallel explore agents when scope spans multiple areas.
+### Phase 1 — Understand
+You MUST focus on the request and the code behind it. You SHOULD launch parallel `explore` subagents (via `task`) when scope spans multiple areas — give each a distinct focus (existing implementations, related components, test patterns). Actively hunt for reusable functions, utilities, and conventions; avoid proposing new code when a suitable implementation already exists.
 
-### Phase 2: Design
-You MUST draft an approach based on exploration. You MUST consider trade-offs briefly, then choose.
+### Phase 2 — Design
+You MUST draft an approach from your exploration, weigh trade-offs briefly, then commit to one. For large or cross-cutting changes you MAY spawn a planning/critique subagent to pressure-test the approach before you commit.
 
-### Phase 3: Review
-You MUST read critical files. You MUST verify plan matches original request. You SHOULD use `{{askToolName}}` to clarify remaining questions.
+### Phase 3 — Review
+You MUST read the critical files you intend to touch to confirm the approach holds against the real code. You MUST verify the plan still matches the original request. You SHOULD use `{{askToolName}}` to close remaining preference questions.
 
-### Phase 4: Update Plan
-You MUST update `{{planFilePath}}` (`{{editToolName}}` for changes, `{{writeToolName}}` only if creating from scratch):
-- Recommended approach only
-- Paths of critical files to modify
-- Verification section
+### Phase 4 — Write the plan
+You MUST write `{{planFilePath}}` per **The Plan** below.
 </procedure>
-
-<caution>
-You MUST ask questions throughout. You NEVER make large assumptions about user intent.
-</caution>
 {{/if}}
 
+## The Plan
+
+The plan MUST be self-contained: approval may clear or compact this conversation, so the file alone must carry everything needed to execute.
+
+<caution>
+Write 3–5 short, scannable markdown sections. The usual shape:
+- **Context** — why this change: the problem or need, what prompted it, the intended outcome. 2–4 sentences.
+- **Approach** — the recommended approach only. Group bullets by subsystem or behavior, NOT file-by-file. Name existing functions/utilities to reuse, with their paths. Describe a repeated pattern once with a few representative paths — you NEVER enumerate every file or line.
+- **Critical files** — the ≤5 files that disambiguate non-obvious changes, each with a one-line reason. Skip files whose change is already obvious from the Approach.
+- **Verification** — how to test end-to-end: exact commands, tests to run or add, manual steps.
+- **Assumptions** — only the decisions you made that the user might want to override.
+
+Prefer the minimum detail needed for safe implementation, not exhaustive coverage. Compress related changes into high-signal bullets; omit branch-by-branch logic, restated invariants, and lists of unaffected behavior. Behavior-level descriptions beat symbol-by-symbol removal lists.
+</caution>
+
 <directives>
-- You MUST use `{{askToolName}}` only for clarifying requirements or choosing approaches
+- You NEVER include sections that decide nothing: Non-Goals, Out of Scope, Alternatives Considered, Risks/Mitigations boilerplate, Future Work. Omit them entirely.
+- You NEVER invent schema, validation, precedence, or fallback policy the request did not establish, unless it is required to prevent a concrete implementation mistake.
+- You NEVER present alternatives in the final plan — choose. Record a discarded option only when it is a live tradeoff the user should confirm, and put it under Assumptions.
 </directives>
 
+<caution>
+The approval selector offers:
+- **Approve and execute** — execution starts in fresh context (session cleared).
+- **Approve and compact context** — distills this discussion into a summary, then executes in this session.
+- **Approve and keep context** — executes in this session, preserving exploration history.
+
+All three rely on the plan file being self-contained.
+</caution>
+
 <critical>
+You MUST use `{{askToolName}}` only to clarify requirements or choose between approaches.
+
 Your turn ends ONLY by:
 1. Using `{{askToolName}}` to gather information, OR
-2. Calling `resolve` with `action: "apply"`, `reason`, and `extra: { title: "<PLAN_TITLE>" }` when ready — this triggers user approval, then implementation with full tool access
+2. Calling `resolve` with `action: "apply"`, `reason`, and `extra: { title: "<PLAN_TITLE>" }` when ready — this triggers user approval, then implementation with full tool access.
 
-You NEVER ask plan approval via text or `{{askToolName}}`; you MUST use `resolve`.
-You MUST keep going until complete.
+You NEVER ask for plan approval via text or `{{askToolName}}`; you MUST use `resolve`.
+You MUST keep going until the plan is decision-complete.
 </critical>
diff --git a/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts b/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts
index 25728a7d7..7bfea1265 100644
--- a/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts
+++ b/packages/coding-agent/test/modes/components/plan-review-overlay.test.ts
@@ -343,6 +343,59 @@ describe("PlanReviewOverlay", () => {
 		expect(feedback).toContain("needs detail");
 	});
 
+	// Click a rendered row. The fullscreen overlay paints from screen row 0, so a
+	// 1-based SGR mouse row equals the rendered-line index + 1.
+	const clickRow = (overlay: PlanReviewOverlay, needle: string, col = 4): boolean => {
+		const lines = overlay.render(80);
+		const row = lines.findIndex(line => stripVTControlCharacters(line).includes(needle));
+		if (row < 0) return false;
+		overlay.handleInput(`\x1b[<0;${col};${row + 1}M`);
+		return true;
+	};
+
+	it("activates an approval option on click", () => {
+		const onPick = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick, onCancel: vi.fn() },
+		);
+		render(overlay);
+		expect(clickRow(overlay, "Refine plan", 10)).toBe(true);
+		expect(onPick).toHaveBeenCalledWith("Refine plan");
+	});
+
+	it("selects a ToC section on click and scrubs the body to it", () => {
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn() },
+		);
+		render(overlay);
+		// Click the "Steps" entry in the sidebar column.
+		expect(clickRow(overlay, "Steps", 4)).toBe(true);
+		const out = render(overlay);
+		expect(out).toContain("a annotate"); // ToC focus
+		// The body scrubbed to the clicked section.
+		expect(out.split("\n").slice(1, 5).join(" ")).toContain("Steps");
+	});
+
+	it("includes deleted sections in the refinement feedback", () => {
+		const onFeedbackChange = vi.fn();
+		const overlay = new PlanReviewOverlay(
+			SECTION_PLAN,
+			{ promptTitle: "next", options: APPROVAL_OPTIONS },
+			{ onPick: vi.fn(), onCancel: vi.fn(), onPlanEdited: vi.fn(), onFeedbackChange },
+		);
+		render(overlay);
+		overlay.handleInput(TAB); // -> toc (Overview)
+		overlay.handleInput(DOWN); // -> Goal
+		overlay.handleInput("d"); // delete Goal
+		const feedback = onFeedbackChange.mock.calls.at(-1)?.[0] as string;
+		expect(feedback).toContain("Remove these sections:");
+		expect(feedback).toContain("Goal");
+	});
+
 	it("drives the slider with both arrows even when a sidebar is present", () => {
 		const changes: number[] = [];
 		const slider: HookSelectorSlider = {
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 307befe93..74e23d959 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -12,7 +12,7 @@
 - Added `Loader.dispose()` to stop the loader animation timer when the component is disposed
 - Added a `ScrollView` `ellipsis` option (defaults to `Ellipsis.Unicode`) so callers that pre-wrap content to width can pass `Ellipsis.Omit` and suppress the stray per-line `…` that lands on trailing padding.
 - Added `ScrollView.handleScrollKey()` plus a `fastScrollLines` option so every scroll view gets shared navigation keys, including Shift+Arrow to scroll faster.
-- Added `OverlayOptions.fullscreen`: while the topmost visible overlay sets it, the engine borrows the terminal's alternate screen buffer for the overlay's lifetime and paints only the modal there — no ED3, no transcript re-commit — so the transcript stays untouched on the normal screen and is not scrollable behind the modal.
+- Added `OverlayOptions.fullscreen`: while the topmost visible overlay sets it, the engine borrows the terminal's alternate screen buffer for the overlay's lifetime and paints only the modal there — no ED3, no transcript re-commit — so the transcript stays untouched on the normal screen and is not scrollable behind the modal. Mouse tracking (`?1000h`/`?1006h`) is enabled for the modal's lifetime and disabled on exit, so the rest of the app keeps the terminal's native text selection.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 6e7c4a13d..95f997f70 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -68,6 +68,11 @@ const CURSOR_BEGIN = `${HIDE_CURSOR}${SYNC_OUTPUT_BEGIN}`;
 const CURSOR_BEGIN_NO_SYNC = HIDE_CURSOR;
 const CURSOR_END = SYNC_OUTPUT_END;
 const CURSOR_END_NO_SYNC = "";
+// Mouse reporting (normal click tracking + SGR extended coordinates), enabled
+// only for the lifetime of a fullscreen overlay so the rest of the app keeps the
+// terminal's native text selection.
+const MOUSE_TRACKING_ON = "\x1b[?1000h\x1b[?1006h";
+const MOUSE_TRACKING_OFF = "\x1b[?1006l\x1b[?1000l";
 
 type InputListenerResult = { consume?: boolean; data?: string } | undefined;
 type InputListener = (data: string) => InputListenerResult;
@@ -977,7 +982,7 @@ export class TUI extends Container {
 		// Leave the alt buffer first so the teardown cursor math below runs against
 		// the restored normal screen (which #previousLines still describes).
 		if (this.#altActive) {
-			this.terminal.write("\x1b[?1049l");
+			this.terminal.write(`${MOUSE_TRACKING_OFF}\x1b[?1049l`);
 			this.#altActive = false;
 			this.#altPreviousLines = [];
 		}
@@ -1542,14 +1547,14 @@ export class TUI extends Container {
 		// exiting reconciles cleanly against the terminal-restored screen.
 		const wantAlt = this.#wantsAltScreen();
 		if (wantAlt && !this.#altActive) {
-			this.terminal.write("\x1b[?1049h");
+			this.terminal.write(`\x1b[?1049h${MOUSE_TRACKING_ON}`);
 			this.terminal.hideCursor();
 			this.#altActive = true;
 			this.#altPreviousLines = [];
 			this.#altEnterWidth = width;
 			this.#altEnterHeight = height;
 		} else if (!wantAlt && this.#altActive) {
-			this.terminal.write("\x1b[?1049l");
+			this.terminal.write(`${MOUSE_TRACKING_OFF}\x1b[?1049l`);
 			this.#altActive = false;
 			this.#altPreviousLines = [];
 			// A resize while on the alt buffer reflowed the terminal's saved normal
diff --git a/packages/tui/test/render-regressions.test.ts b/packages/tui/test/render-regressions.test.ts
index d94e77f69..13fd93365 100644
--- a/packages/tui/test/render-regressions.test.ts
+++ b/packages/tui/test/render-regressions.test.ts
@@ -3233,6 +3233,9 @@ describe("TUI terminal-state regressions", () => {
 				const modalWrites = writes.slice(showFrom).join("");
 				// Borrowed the alternate screen buffer …
 				expect(modalWrites).toContain("\x1b[?1049h");
+				// … enabled mouse tracking for click/scroll support …
+				expect(modalWrites).toContain("\x1b[?1000h");
+				expect(modalWrites).toContain("\x1b[?1006h");
 				// … and never erased scrollback (ED3) or otherwise touched the transcript.
 				expect(modalWrites).not.toContain("\x1b[3J");
 				expect(visible(term).some(line => line.includes("MODAL-0"))).toBeTrue();
@@ -3241,7 +3244,11 @@ describe("TUI terminal-state regressions", () => {
 				handle.hide();
 				await settle(term);
 
-				expect(writes.slice(hideFrom).join("")).toContain("\x1b[?1049l");
+				const hideWrites = writes.slice(hideFrom).join("");
+				expect(hideWrites).toContain("\x1b[?1049l");
+				// Mouse tracking is disabled again so the rest of the app keeps native
+				// terminal selection.
+				expect(hideWrites).toContain("\x1b[?1000l");
 				// Transcript is back on the normal screen after leaving the alt buffer.
 				expect(visible(term).some(line => line.includes("base-"))).toBeTrue();
 				expect(visible(term).some(line => line.includes("MODAL-0"))).toBeFalse();

From 174552936856a62b49a16bd1ae2882ef0d96e596 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 02:59:02 +0000
Subject: [PATCH 088/181] fix(debug): accept directory programs for dlv and
 auto-select dlv mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The debug tool ran validateLaunchProgram before adapter selection and
rejected any directory program with `launch program resolves to a
directory`, while dlv's default `mode=debug` requires a Go package
path (a directory or .go source file). Every Go-module launch failed:
passing the module dir was rejected outright, and passing the compiled
binary failed at dlv with `not a valid go module`.

- Add `acceptsDirectoryProgram` to DapAdapterConfig/DapResolvedAdapter
  and flag dlv in dap/defaults.json.
- In DebugTool.execute(launch), resolve the adapter first, then call
  validateLaunchProgram with the resolved adapter — the directory
  rejection only fires when the adapter does not advertise the flag.
- Add resolveLaunchOverrides in dap/config.ts: for dlv, derive `mode`
  from the program shape (directory or .go file → debug; other file
  → exec). Plumbed through DapLaunchSessionOptions.extraLaunchArguments
  and spread between adapter.launchDefaults and the hard-coded launch
  fields in session.ts.
- Refresh tests: cover the no-dir-support adapter rejection, dlv on a
  package directory keeping mode=debug, and dlv on a binary switching
  to mode=exec.

Fixes #2020
---
 packages/coding-agent/CHANGELOG.md            |   4 +
 packages/coding-agent/src/dap/config.ts       |  32 +++++
 packages/coding-agent/src/dap/defaults.json   |   1 +
 packages/coding-agent/src/dap/session.ts      |   1 +
 packages/coding-agent/src/dap/types.ts        |  10 ++
 packages/coding-agent/src/tools/debug.ts      |  26 +++-
 .../test/debug/dap-launch-failures.test.ts    | 123 +++++++++++++++---
 7 files changed, 175 insertions(+), 22 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 5246c39e0..c97003469 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed `debug` tool refusing every `dlv` launch on Go modules. The launch handler ran `validateLaunchProgram` before adapter selection and rejected any directory program with `launch program resolves to a directory`, while dlv's default `mode=debug` requires a Go package path (a directory or `.go` source file). Adapter resolution now precedes validation, the rejection only fires when the resolved adapter does not advertise `acceptsDirectoryProgram` (set on `dlv` in `dap/defaults.json`), and dlv's `mode` is derived from the program shape — directories and `.go` files launch as `mode=debug`, other files as `mode=exec` — so `omp` can debug both Go packages and pre-built binaries ([#2020](https://github.com/can1357/oh-my-pi/issues/2020)).
+
 ## [15.10.0] - 2026-06-06
 
 ### Breaking Changes
diff --git a/packages/coding-agent/src/dap/config.ts b/packages/coding-agent/src/dap/config.ts
index 271a38fc6..93d35573f 100644
--- a/packages/coding-agent/src/dap/config.ts
+++ b/packages/coding-agent/src/dap/config.ts
@@ -27,6 +27,7 @@ function normalizeAdapterConfig(config: unknown): DapAdapterConfig | null {
 		rootMarkers: normalizeStringArray(config.rootMarkers),
 		launchDefaults: normalizeObject(config.launchDefaults),
 		attachDefaults: normalizeObject(config.attachDefaults),
+		acceptsDirectoryProgram: config.acceptsDirectoryProgram === true,
 		...(connectMode ? { connectMode } : {}),
 	};
 }
@@ -64,6 +65,7 @@ export function resolveAdapter(adapterName: string, cwd: string): DapResolvedAda
 		launchDefaults: config.launchDefaults ?? {},
 		attachDefaults: config.attachDefaults ?? {},
 		connectMode: config.connectMode ?? "stdio",
+		acceptsDirectoryProgram: config.acceptsDirectoryProgram === true,
 	};
 }
 
@@ -148,3 +150,33 @@ export function selectAttachAdapter(cwd: string, adapterName?: string, port?: nu
 	}
 	return available[0] ?? null;
 }
+
+/** How the launch `program` resolves on disk. `"missing"` is reserved for
+ *  programs the adapter creates on demand (rare); we treat them like files. */
+export type LaunchProgramKind = "file" | "directory" | "missing";
+
+/** Compute adapter-specific launch arguments that depend on the resolved
+ *  program. Returned values are spread over `adapter.launchDefaults` so they
+ *  take precedence over the static defaults but can still be overridden by
+ *  the fields `DapSessionManager.launch` sets explicitly (program, cwd, args).
+ *
+ *  Currently scoped to dlv, where `mode` selects how the program path is
+ *  interpreted: directories and `.go` source files debug as a Go package
+ *  (`mode=debug`), anything else is treated as a compiled binary (`mode=exec`).
+ */
+export function resolveLaunchOverrides(
+	adapter: DapResolvedAdapter,
+	program: string,
+	programKind: LaunchProgramKind,
+): Record<string, unknown> {
+	if (adapter.name === "dlv") {
+		const extension = path.extname(program).toLowerCase();
+		if (programKind === "directory" || extension === ".go") {
+			return { mode: "debug" };
+		}
+		if (programKind === "file") {
+			return { mode: "exec" };
+		}
+	}
+	return {};
+}
diff --git a/packages/coding-agent/src/dap/defaults.json b/packages/coding-agent/src/dap/defaults.json
index dd3725236..5ea74ef25 100644
--- a/packages/coding-agent/src/dap/defaults.json
+++ b/packages/coding-agent/src/dap/defaults.json
@@ -65,6 +65,7 @@
 		"languages": ["go"],
 		"fileTypes": [".go"],
 		"rootMarkers": ["go.mod", "go.sum"],
+		"acceptsDirectoryProgram": true,
 		"launchDefaults": {
 			"request": "launch",
 			"mode": "debug",
diff --git a/packages/coding-agent/src/dap/session.ts b/packages/coding-agent/src/dap/session.ts
index 0dc66c63b..57be0afc1 100644
--- a/packages/coding-agent/src/dap/session.ts
+++ b/packages/coding-agent/src/dap/session.ts
@@ -259,6 +259,7 @@ export class DapSessionManager {
 			session.needsConfigurationDone = session.capabilities.supportsConfigurationDoneRequest === true;
 			const launchArguments: DapLaunchArguments = {
 				...options.adapter.launchDefaults,
+				...(options.extraLaunchArguments ?? {}),
 				program: options.program,
 				cwd: options.cwd,
 				args: options.args,
diff --git a/packages/coding-agent/src/dap/types.ts b/packages/coding-agent/src/dap/types.ts
index eb4659de9..542e9088c 100644
--- a/packages/coding-agent/src/dap/types.ts
+++ b/packages/coding-agent/src/dap/types.ts
@@ -488,6 +488,10 @@ export interface DapAdapterConfig {
 	 *  On Linux, connects via a unix domain socket.
 	 *  On macOS, the adapter dials into a local TCP listener (--client-addr). */
 	connectMode?: "stdio" | "socket";
+	/** When true, the adapter accepts a directory as the launch `program`
+	 *  (e.g. dlv treats it as a Go package path). When false/undefined, the
+	 *  debug tool rejects directory programs upfront. */
+	acceptsDirectoryProgram?: boolean;
 }
 
 export interface DapResolvedAdapter {
@@ -501,6 +505,7 @@ export interface DapResolvedAdapter {
 	launchDefaults: Record<string, unknown>;
 	attachDefaults: Record<string, unknown>;
 	connectMode: "stdio" | "socket";
+	acceptsDirectoryProgram: boolean;
 }
 
 export interface DapBreakpointRecord {
@@ -589,6 +594,11 @@ export interface DapLaunchSessionOptions {
 	program: string;
 	args?: string[];
 	cwd: string;
+	/** Per-launch overrides merged over `adapter.launchDefaults`. Used to
+	 *  inject adapter-specific values that depend on the resolved program
+	 *  (e.g. dlv's `mode` switches between `debug` and `exec` based on
+	 *  whether `program` is a Go package path or a compiled binary). */
+	extraLaunchArguments?: Record<string, unknown>;
 }
 
 export interface DapAttachSessionOptions {
diff --git a/packages/coding-agent/src/tools/debug.ts b/packages/coding-agent/src/tools/debug.ts
index 70606ba4c..caf54efe6 100644
--- a/packages/coding-agent/src/tools/debug.ts
+++ b/packages/coding-agent/src/tools/debug.ts
@@ -22,6 +22,7 @@ import {
 	type DapFunctionBreakpointRecord,
 	type DapInstructionBreakpointRecord,
 	type DapModule,
+	type DapResolvedAdapter,
 	type DapScope,
 	type DapSessionSummary,
 	type DapSource,
@@ -30,6 +31,8 @@ import {
 	type DapVariable,
 	dapSessionManager,
 	getAvailableAdapters,
+	type LaunchProgramKind,
+	resolveLaunchOverrides,
 	selectAttachAdapter,
 	selectLaunchAdapter,
 } from "../dap";
@@ -489,16 +492,23 @@ function getConfiguredAdapters(cwd: string): string {
 	const adapters = getAvailableAdapters(cwd).map(adapter => adapter.name);
 	return adapters.length > 0 ? adapters.join(", ") : "none";
 }
-async function validateLaunchProgram(program: string, cwd: string): Promise<void> {
-	let isDirectory: boolean;
+
+async function classifyLaunchProgram(program: string): Promise<LaunchProgramKind> {
 	try {
-		isDirectory = (await fs.stat(program)).isDirectory();
+		return (await fs.stat(program)).isDirectory() ? "directory" : "file";
 	} catch (error) {
-		if (isEnoent(error)) return;
+		if (isEnoent(error)) return "missing";
 		throw error;
 	}
-	if (!isDirectory) return;
+}
 
+function validateLaunchProgram(
+	program: string,
+	cwd: string,
+	programKind: LaunchProgramKind,
+	adapter: DapResolvedAdapter,
+): void {
+	if (programKind !== "directory" || adapter.acceptsDirectoryProgram) return;
 	const displayPath = formatPathRelativeToCwd(program, cwd, { trailingSlash: true });
 	throw new ToolError(
 		`launch program resolves to a directory: ${displayPath}. Pass an executable file path, or for Python use adapter "debugpy" with program set to the .py file.`,
@@ -676,7 +686,7 @@ export class DebugTool implements AgentTool<typeof debugSchema, DebugToolDetails
 				}
 				const commandCwd = params.cwd ? resolveToCwd(params.cwd, this.session.cwd) : this.session.cwd;
 				const program = resolveToCwd(params.program, commandCwd);
-				await validateLaunchProgram(program, commandCwd);
+				const programKind = await classifyLaunchProgram(program);
 				const adapter = selectLaunchAdapter(program, commandCwd, params.adapter);
 				if (!adapter) {
 					if (params.adapter === "debugpy") {
@@ -686,8 +696,10 @@ export class DebugTool implements AgentTool<typeof debugSchema, DebugToolDetails
 						`No debugger adapter available. Installed adapters: ${getConfiguredAdapters(commandCwd)}`,
 					);
 				}
+				validateLaunchProgram(program, commandCwd, programKind, adapter);
+				const extraLaunchArguments = resolveLaunchOverrides(adapter, program, programKind);
 				const snapshot = await dapSessionManager.launch(
-					{ adapter, program, args: params.args, cwd: commandCwd },
+					{ adapter, program, args: params.args, cwd: commandCwd, extraLaunchArguments },
 					combinedSignal,
 					timeoutSec * 1000,
 				);
diff --git a/packages/coding-agent/test/debug/dap-launch-failures.test.ts b/packages/coding-agent/test/debug/dap-launch-failures.test.ts
index 004332d59..75471cb5d 100644
--- a/packages/coding-agent/test/debug/dap-launch-failures.test.ts
+++ b/packages/coding-agent/test/debug/dap-launch-failures.test.ts
@@ -20,6 +20,7 @@ const TEST_ADAPTER: DapResolvedAdapter = {
 	launchDefaults: {},
 	attachDefaults: {},
 	connectMode: "stdio",
+	acceptsDirectoryProgram: false,
 };
 
 const DELAYED_UNIX_SOCKET_ADAPTER = `
@@ -338,24 +339,116 @@ describe("DAP launch failure handling", () => {
 });
 
 describe("DebugTool launch validation", () => {
-	it("rejects directory-valued launch programs before adapter selection", async () => {
-		const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-program-"));
+	it("rejects directory programs when the selected adapter cannot debug a directory", async () => {
+		const dapModule = await import("../../src/dap");
+		const launchSpy = spyOn(dapModule, "selectLaunchAdapter").mockReturnValue(TEST_ADAPTER);
 		try {
-			await fs.mkdir(path.join(cwd, "python"));
-			const session: ToolSession = {
-				cwd,
-				hasUI: false,
-				getSessionFile: () => null,
-				getSessionSpawns: () => "*",
-				settings: Settings.isolated({ "debug.enabled": true }),
-			};
-			const tool = new DebugTool(session);
+			const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-program-"));
+			try {
+				await fs.mkdir(path.join(cwd, "python"));
+				const session: ToolSession = {
+					cwd,
+					hasUI: false,
+					getSessionFile: () => null,
+					getSessionSpawns: () => "*",
+					settings: Settings.isolated({ "debug.enabled": true }),
+				};
+				const tool = new DebugTool(session);
 
-			await expect(tool.execute("call", { action: "launch", program: "python" })).rejects.toThrow(
-				/launch program resolves to a directory.*python/,
-			);
+				await expect(tool.execute("call", { action: "launch", program: "python" })).rejects.toThrow(
+					/launch program resolves to a directory.*python/,
+				);
+			} finally {
+				await fs.rm(cwd, { recursive: true, force: true });
+			}
 		} finally {
-			await fs.rm(cwd, { recursive: true, force: true });
+			launchSpy.mockRestore();
+		}
+	});
+
+	it("allows directory programs when the selected adapter accepts them (dlv on a Go package)", async () => {
+		const dapModule = await import("../../src/dap");
+		const dlvAdapter: DapResolvedAdapter = {
+			...TEST_ADAPTER,
+			name: "dlv",
+			command: "dlv",
+			resolvedCommand: "dlv",
+			launchDefaults: { request: "launch", mode: "debug", stopOnEntry: true },
+			acceptsDirectoryProgram: true,
+		};
+		const launchSpy = spyOn(dapModule, "selectLaunchAdapter").mockReturnValue(dlvAdapter);
+		const sessionLaunchSpy = spyOn(dapModule.dapSessionManager, "launch").mockImplementation(async opts => {
+			throw Object.assign(new Error("captured launch"), { capturedOptions: opts });
+		});
+		try {
+			const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-dlv-dir-"));
+			try {
+				await fs.mkdir(path.join(cwd, "cmd"));
+				const session: ToolSession = {
+					cwd,
+					hasUI: false,
+					getSessionFile: () => null,
+					getSessionSpawns: () => "*",
+					settings: Settings.isolated({ "debug.enabled": true }),
+				};
+				const tool = new DebugTool(session);
+
+				// Validation must pass and propagate to dapSessionManager.launch; we
+				// stop the actual spawn there and inspect the launch arguments.
+				await expect(tool.execute("call", { action: "launch", program: "cmd", adapter: "dlv" })).rejects.toThrow(
+					/captured launch/,
+				);
+				expect(sessionLaunchSpy).toHaveBeenCalledTimes(1);
+				const [opts] = sessionLaunchSpy.mock.calls[0]!;
+				expect(opts.extraLaunchArguments).toEqual({ mode: "debug" });
+				expect(opts.program).toBe(path.join(cwd, "cmd"));
+			} finally {
+				await fs.rm(cwd, { recursive: true, force: true });
+			}
+		} finally {
+			sessionLaunchSpy.mockRestore();
+			launchSpy.mockRestore();
+		}
+	});
+
+	it("dlv launch with a compiled binary switches mode from debug to exec", async () => {
+		const dapModule = await import("../../src/dap");
+		const dlvAdapter: DapResolvedAdapter = {
+			...TEST_ADAPTER,
+			name: "dlv",
+			command: "dlv",
+			resolvedCommand: "dlv",
+			launchDefaults: { request: "launch", mode: "debug", stopOnEntry: true },
+			acceptsDirectoryProgram: true,
+		};
+		const launchSpy = spyOn(dapModule, "selectLaunchAdapter").mockReturnValue(dlvAdapter);
+		const sessionLaunchSpy = spyOn(dapModule.dapSessionManager, "launch").mockImplementation(async opts => {
+			throw Object.assign(new Error("captured launch"), { capturedOptions: opts });
+		});
+		try {
+			const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-dlv-exec-"));
+			try {
+				await fs.writeFile(path.join(cwd, "hello"), "#!/usr/bin/env sh\necho hi\n");
+				const session: ToolSession = {
+					cwd,
+					hasUI: false,
+					getSessionFile: () => null,
+					getSessionSpawns: () => "*",
+					settings: Settings.isolated({ "debug.enabled": true }),
+				};
+				const tool = new DebugTool(session);
+
+				await expect(tool.execute("call", { action: "launch", program: "hello", adapter: "dlv" })).rejects.toThrow(
+					/captured launch/,
+				);
+				const [opts] = sessionLaunchSpy.mock.calls[0]!;
+				expect(opts.extraLaunchArguments).toEqual({ mode: "exec" });
+			} finally {
+				await fs.rm(cwd, { recursive: true, force: true });
+			}
+		} finally {
+			sessionLaunchSpy.mockRestore();
+			launchSpy.mockRestore();
 		}
 	});
 

From 8c25f7d4aa31ee192ff78aed823d520ff3278e45 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 03:03:57 +0000
Subject: [PATCH 089/181] fix(debug): prefer dlv for go directory launches

Prefer directory-capable adapters when selecting a launch adapter for a
resolved directory program. This keeps Go package directories on dlv in
mixed projects that also expose native-debugger root markers such as a
Makefile, instead of selecting gdb/lldb-dap first and rejecting the
directory during validation.

Added a regression test covering a Go module with both go.mod and
Makefile plus local dlv/gdb adapter shims.

Fixes #2020
---
 packages/coding-agent/CHANGELOG.md            |  2 +-
 packages/coding-agent/src/dap/config.ts       | 11 +++++-
 packages/coding-agent/src/tools/debug.ts      |  2 +-
 .../test/debug/dap-launch-failures.test.ts    | 37 +++++++++++++++++++
 4 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index c97003469..1586f79c2 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Fixed
 
-- Fixed `debug` tool refusing every `dlv` launch on Go modules. The launch handler ran `validateLaunchProgram` before adapter selection and rejected any directory program with `launch program resolves to a directory`, while dlv's default `mode=debug` requires a Go package path (a directory or `.go` source file). Adapter resolution now precedes validation, the rejection only fires when the resolved adapter does not advertise `acceptsDirectoryProgram` (set on `dlv` in `dap/defaults.json`), and dlv's `mode` is derived from the program shape — directories and `.go` files launch as `mode=debug`, other files as `mode=exec` — so `omp` can debug both Go packages and pre-built binaries ([#2020](https://github.com/can1357/oh-my-pi/issues/2020)).
+- Fixed `debug` tool refusing every `dlv` launch on Go modules. The launch handler ran `validateLaunchProgram` before adapter selection and rejected any directory program with `launch program resolves to a directory`, while dlv's default `mode=debug` requires a Go package path (a directory or `.go` source file). Adapter resolution now precedes validation, directory programs prefer adapters that advertise `acceptsDirectoryProgram` before falling back to native extensionless debuggers, the rejection only fires when the resolved adapter does not advertise that flag (set on `dlv` in `dap/defaults.json`), and dlv's `mode` is derived from the program shape — directories and `.go` files launch as `mode=debug`, other files as `mode=exec` — so `omp` can debug both Go packages and pre-built binaries ([#2020](https://github.com/can1357/oh-my-pi/issues/2020)).
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/coding-agent/src/dap/config.ts b/packages/coding-agent/src/dap/config.ts
index 93d35573f..31f870b91 100644
--- a/packages/coding-agent/src/dap/config.ts
+++ b/packages/coding-agent/src/dap/config.ts
@@ -126,12 +126,19 @@ function sortAdaptersForLaunch(program: string, cwd: string, adapters: DapResolv
 	return rootAware.map(entry => entry.adapter);
 }
 
-export function selectLaunchAdapter(program: string, cwd: string, adapterName?: string): DapResolvedAdapter | null {
+export function selectLaunchAdapter(
+	program: string,
+	cwd: string,
+	adapterName?: string,
+	programKind: LaunchProgramKind = "file",
+): DapResolvedAdapter | null {
 	if (adapterName) {
 		return resolveAdapter(adapterName, cwd);
 	}
 	const matches = getMatchingAdapters(program, cwd);
-	const sorted = sortAdaptersForLaunch(program, cwd, matches);
+	const candidates =
+		programKind === "directory" ? matches.filter(adapter => adapter.acceptsDirectoryProgram) : matches;
+	const sorted = sortAdaptersForLaunch(program, cwd, candidates.length > 0 ? candidates : matches);
 	return sorted[0] ?? null;
 }
 
diff --git a/packages/coding-agent/src/tools/debug.ts b/packages/coding-agent/src/tools/debug.ts
index caf54efe6..61a009d2c 100644
--- a/packages/coding-agent/src/tools/debug.ts
+++ b/packages/coding-agent/src/tools/debug.ts
@@ -687,7 +687,7 @@ export class DebugTool implements AgentTool<typeof debugSchema, DebugToolDetails
 				const commandCwd = params.cwd ? resolveToCwd(params.cwd, this.session.cwd) : this.session.cwd;
 				const program = resolveToCwd(params.program, commandCwd);
 				const programKind = await classifyLaunchProgram(program);
-				const adapter = selectLaunchAdapter(program, commandCwd, params.adapter);
+				const adapter = selectLaunchAdapter(program, commandCwd, params.adapter, programKind);
 				if (!adapter) {
 					if (params.adapter === "debugpy") {
 						throw new ToolError("adapter 'debugpy' is not available: python not found in PATH");
diff --git a/packages/coding-agent/test/debug/dap-launch-failures.test.ts b/packages/coding-agent/test/debug/dap-launch-failures.test.ts
index 75471cb5d..666e005b8 100644
--- a/packages/coding-agent/test/debug/dap-launch-failures.test.ts
+++ b/packages/coding-agent/test/debug/dap-launch-failures.test.ts
@@ -411,6 +411,43 @@ describe("DebugTool launch validation", () => {
 		}
 	});
 
+	it("prefers directory-capable dlv over native adapters for extensionless Go package directories", async () => {
+		const dapModule = await import("../../src/dap");
+		const sessionLaunchSpy = spyOn(dapModule.dapSessionManager, "launch").mockImplementation(async opts => {
+			throw Object.assign(new Error("captured launch"), { capturedOptions: opts });
+		});
+		try {
+			const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-dlv-mixed-roots-"));
+			try {
+				await fs.writeFile(path.join(cwd, "go.mod"), "module hello\n\ngo 1.22\n");
+				await fs.writeFile(path.join(cwd, "Makefile"), "all:\n\tgo build ./...\n");
+				await fs.mkdir(path.join(cwd, "bin"));
+				await fs.writeFile(path.join(cwd, "bin", "dlv"), "");
+				await fs.writeFile(path.join(cwd, "bin", "gdb"), "");
+				await fs.mkdir(path.join(cwd, "cmd", "hello"), { recursive: true });
+				const session: ToolSession = {
+					cwd,
+					hasUI: false,
+					getSessionFile: () => null,
+					getSessionSpawns: () => "*",
+					settings: Settings.isolated({ "debug.enabled": true }),
+				};
+				const tool = new DebugTool(session);
+
+				await expect(tool.execute("call", { action: "launch", program: "cmd/hello" })).rejects.toThrow(
+					/captured launch/,
+				);
+				const [opts] = sessionLaunchSpy.mock.calls[0]!;
+				expect(opts.adapter.name).toBe("dlv");
+				expect(opts.extraLaunchArguments).toEqual({ mode: "debug" });
+			} finally {
+				await fs.rm(cwd, { recursive: true, force: true });
+			}
+		} finally {
+			sessionLaunchSpy.mockRestore();
+		}
+	});
+
 	it("dlv launch with a compiled binary switches mode from debug to exec", async () => {
 		const dapModule = await import("../../src/dap");
 		const dlvAdapter: DapResolvedAdapter = {

From d710b91d96f9a9996e8efee286c54964fbd30ea7 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 03:05:20 +0000
Subject: [PATCH 090/181] test(debug): hoist dap module import to top of test
 file

The repo bans inline imports. Replace per-test `await import("../../src/dap")`
calls with a single top-level `import * as dapModule from "../../src/dap"`
and reuse the namespace for every spy in this file.

Fixes #2020
---
 .../coding-agent/test/debug/dap-launch-failures.test.ts   | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/packages/coding-agent/test/debug/dap-launch-failures.test.ts b/packages/coding-agent/test/debug/dap-launch-failures.test.ts
index 666e005b8..9d5802860 100644
--- a/packages/coding-agent/test/debug/dap-launch-failures.test.ts
+++ b/packages/coding-agent/test/debug/dap-launch-failures.test.ts
@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { Settings } from "../../src/config/settings";
+import * as dapModule from "../../src/dap";
 import { DapClient } from "../../src/dap/client";
 import { DapSessionManager } from "../../src/dap/session";
 import type { DapCapabilities, DapClientState, DapEventMessage, DapResolvedAdapter } from "../../src/dap/types";
@@ -340,7 +341,6 @@ describe("DAP launch failure handling", () => {
 
 describe("DebugTool launch validation", () => {
 	it("rejects directory programs when the selected adapter cannot debug a directory", async () => {
-		const dapModule = await import("../../src/dap");
 		const launchSpy = spyOn(dapModule, "selectLaunchAdapter").mockReturnValue(TEST_ADAPTER);
 		try {
 			const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-program-"));
@@ -367,7 +367,6 @@ describe("DebugTool launch validation", () => {
 	});
 
 	it("allows directory programs when the selected adapter accepts them (dlv on a Go package)", async () => {
-		const dapModule = await import("../../src/dap");
 		const dlvAdapter: DapResolvedAdapter = {
 			...TEST_ADAPTER,
 			name: "dlv",
@@ -412,7 +411,6 @@ describe("DebugTool launch validation", () => {
 	});
 
 	it("prefers directory-capable dlv over native adapters for extensionless Go package directories", async () => {
-		const dapModule = await import("../../src/dap");
 		const sessionLaunchSpy = spyOn(dapModule.dapSessionManager, "launch").mockImplementation(async opts => {
 			throw Object.assign(new Error("captured launch"), { capturedOptions: opts });
 		});
@@ -449,7 +447,6 @@ describe("DebugTool launch validation", () => {
 	});
 
 	it("dlv launch with a compiled binary switches mode from debug to exec", async () => {
-		const dapModule = await import("../../src/dap");
 		const dlvAdapter: DapResolvedAdapter = {
 			...TEST_ADAPTER,
 			name: "dlv",
@@ -490,7 +487,6 @@ describe("DebugTool launch validation", () => {
 	});
 
 	it("throws targeted 'python not found in PATH' when adapter:'debugpy' is unresolvable for launch", async () => {
-		const dapModule = await import("../../src/dap");
 		const launchSpy = spyOn(dapModule, "selectLaunchAdapter").mockReturnValue(null);
 		try {
 			const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-debugpy-"));
@@ -517,7 +513,6 @@ describe("DebugTool launch validation", () => {
 	});
 
 	it("throws targeted 'python not found in PATH' when adapter:'debugpy' is unresolvable for attach", async () => {
-		const dapModule = await import("../../src/dap");
 		const attachSpy = spyOn(dapModule, "selectAttachAdapter").mockReturnValue(null);
 		try {
 			const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-debugpy-attach-"));
@@ -543,7 +538,6 @@ describe("DebugTool launch validation", () => {
 	});
 
 	it("falls back to the generic 'No debugger adapter' error when adapter is unspecified", async () => {
-		const dapModule = await import("../../src/dap");
 		const launchSpy = spyOn(dapModule, "selectLaunchAdapter").mockReturnValue(null);
 		try {
 			const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "omp-debug-noadapter-"));

From 66583b414be0676bdd73b0576f4d9cb54260fd0e Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:08:44 +0200
Subject: [PATCH 091/181] fix(tui): allowed checkpoint replay when
 submit-scroll pins viewport to tail

- Added terminal detection for submit-key actions that pin the viewport to tail, and added a test override for that capability.
- Converted TERMINAL into a clone-based RuntimeTerminal so mutable capability fields can be updated directly by runtime setters.
- Updated checkpoint replay gating to allow ED3 rebuild when viewport position is unprobeable but submit-pin behavior is reported true.
---
 packages/tui/src/terminal-capabilities.ts | 158 +++++++++++++++-------
 packages/tui/src/tui.ts                   |  13 +-
 2 files changed, 117 insertions(+), 54 deletions(-)

diff --git a/packages/tui/src/terminal-capabilities.ts b/packages/tui/src/terminal-capabilities.ts
index dfea3bd4a..de9d6665f 100644
--- a/packages/tui/src/terminal-capabilities.ts
+++ b/packages/tui/src/terminal-capabilities.ts
@@ -39,6 +39,25 @@ export class TerminalInfo {
 		public readonly textSizing: boolean = false,
 	) {}
 
+	/**
+	 * Whether a prompt-submit keystroke scrolls this host to its tail, so the
+	 * native-scrollback reconciliation checkpoint may ED3-rebuild even when the
+	 * viewport position is unprobeable. Assigned by the TERMINAL builder from
+	 * {@link detectSubmitPinsViewportToTail}; readonly but tests opt in via the
+	 * {@link setTerminalSubmitPinsViewportToTail} mutable-cast setter.
+	 */
+	readonly submitPinsViewportToTail: boolean = false;
+
+	/**
+	 * Mutable clone for the {@link TERMINAL} singleton: copies every field and
+	 * keeps the prototype methods, so the builder and runtime setters flip
+	 * runtime-resolved {@link RuntimeTerminal} capabilities in place instead of
+	 * reconstructing positional constructor args.
+	 */
+	clone(): RuntimeTerminal {
+		return Object.assign(Object.create(TerminalInfo.prototype), this) as RuntimeTerminal;
+	}
+
 	isImageLine(line: string): boolean {
 		if (!this.imageProtocol) return false;
 		if (this.imageProtocol === ImageProtocol.Sixel) {
@@ -185,6 +204,58 @@ export function detectTerminalEagerEraseScrollbackRisk(
 	return true;
 }
 
+/**
+ * Whether a prompt-submit keystroke scrolls this terminal to its tail, making the
+ * native-scrollback reconciliation checkpoint (`refreshNativeScrollbackIfDirty`)
+ * safe to ED3-rebuild even when the viewport position cannot be probed.
+ *
+ * True only for recognized genuine *local* terminals where typing into the prompt
+ * brings the host viewport to the bottom. False — the checkpoint keeps deferring
+ * until a positive at-tail probe — for hosts whose scrollback a keystroke does not
+ * move: Windows consoles/ConPTY, Windows Terminal (incl. WSL), SSH, multiplexers,
+ * and unrecognized profiles. This is the per-terminal counterpart to the blanket
+ * block from #1610/#1682/#1746: those hosts genuinely cannot treat a submit as
+ * proof of at-tail, but genuine local terminals can.
+ */
+export function detectSubmitPinsViewportToTail(
+	env: NodeJS.ProcessEnv = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (env.PI_TUI_ED3_SAFE === "1") return true;
+	if (platform === "win32") return false;
+	if (env.WT_SESSION) return false;
+	if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY) return false;
+	const term = env.TERM?.toLowerCase() ?? "";
+	if (env.TMUX || env.STY || env.ZELLIJ || term.startsWith("tmux") || term.startsWith("screen")) {
+		return false;
+	}
+	if (
+		env.WEZTERM_PANE ||
+		env.KITTY_WINDOW_ID ||
+		env.GHOSTTY_RESOURCES_DIR ||
+		env.ALACRITTY_WINDOW_ID ||
+		env.ITERM_SESSION_ID ||
+		env.VTE_VERSION
+	) {
+		return true;
+	}
+	switch (env.TERM_PROGRAM?.toLowerCase() ?? "") {
+		case "alacritty":
+		case "apple_terminal":
+		case "ghostty":
+		case "gnome-terminal":
+		case "iterm.app":
+		case "kgx":
+		case "kitty":
+		case "ptyxis":
+		case "wezterm":
+		case "xfce4-terminal":
+			return true;
+		default:
+			return false;
+	}
+}
+
 /**
  * Resolve an explicit user override for DEC 2026 synchronized output. Returns
  * `false` for an opt-out, `true` for a force-on, or `null` when the user has
@@ -350,54 +421,38 @@ export const TERMINAL_ID: TerminalId = (() => {
 	return "base";
 })();
 
-/** Clone a {@link TerminalInfo} with selected fields overridden, preserving the rest. */
-function withTerminalOverrides(
-	base: TerminalInfo,
-	overrides: {
-		imageProtocol?: ImageProtocol | null;
-		hyperlinks?: boolean;
-		eagerEraseScrollbackRisk?: boolean;
-		deccara?: boolean;
-		supportsScreenToScrollback?: boolean;
-	},
-): TerminalInfo {
-	return new TerminalInfo(
-		base.id,
-		overrides.imageProtocol !== undefined ? overrides.imageProtocol : base.imageProtocol,
-		base.trueColor,
-		overrides.hyperlinks !== undefined ? overrides.hyperlinks : base.hyperlinks,
-		base.notifyProtocol,
-		overrides.eagerEraseScrollbackRisk !== undefined
-			? overrides.eagerEraseScrollbackRisk
-			: base.eagerEraseScrollbackRisk,
-		overrides.deccara !== undefined ? overrides.deccara : base.deccara,
-		overrides.supportsScreenToScrollback !== undefined
-			? overrides.supportsScreenToScrollback
-			: base.supportsScreenToScrollback,
-	);
+/**
+ * The process-wide {@link TERMINAL} singleton: a {@link TerminalInfo} whose
+ * post-construction capabilities — the image protocol and the probe-driven
+ * flags — are writable, so the runtime setters and tests mutate them directly
+ * instead of through an unsound cast. Every other field stays readonly.
+ */
+export interface RuntimeTerminal extends TerminalInfo {
+	imageProtocol: ImageProtocol | null;
+	hyperlinks: boolean;
+	eagerEraseScrollbackRisk: boolean;
+	deccara: boolean;
+	supportsScreenToScrollback: boolean;
+	textSizing: boolean;
+	submitPinsViewportToTail: boolean;
 }
 
-export const TERMINAL = (() => {
-	let resolved = getTerminalInfo(TERMINAL_ID);
-	const eagerEraseScrollbackRisk = detectTerminalEagerEraseScrollbackRisk(Bun.env, process.platform);
-	if (resolved.eagerEraseScrollbackRisk !== eagerEraseScrollbackRisk) {
-		resolved = withTerminalOverrides(resolved, { eagerEraseScrollbackRisk });
-	}
+export const TERMINAL: RuntimeTerminal = (() => {
+	const resolved = getTerminalInfo(TERMINAL_ID).clone();
+	resolved.eagerEraseScrollbackRisk = detectTerminalEagerEraseScrollbackRisk(Bun.env, process.platform);
 
 	const forcedImageProtocol = getForcedImageProtocol();
 	if (forcedImageProtocol !== undefined) {
-		resolved = withTerminalOverrides(resolved, { imageProtocol: forcedImageProtocol });
+		resolved.imageProtocol = forcedImageProtocol;
 	} else if (!resolved.imageProtocol) {
 		const fallbackImageProtocol = getFallbackImageProtocol(resolved.id);
-		if (fallbackImageProtocol) {
-			resolved = withTerminalOverrides(resolved, { imageProtocol: fallbackImageProtocol });
-		}
+		if (fallbackImageProtocol) resolved.imageProtocol = fallbackImageProtocol;
 	}
 	// tmux and screen multiplexers do not reliably forward OSC 8 hyperlinks
 	// to the outer terminal, so force them off regardless of detected terminal.
 	const term = Bun.env.TERM?.toLowerCase() ?? "";
 	if (resolved.hyperlinks && (Bun.env.TMUX || term.startsWith("tmux") || term.startsWith("screen"))) {
-		resolved = withTerminalOverrides(resolved, { hyperlinks: false });
+		resolved.hyperlinks = false;
 	}
 	// DECCARA rectangular-SGR background fills. The static per-terminal capability
 	// lives on KNOWN_TERMINALS; here we fold in runtime context — multiplexer and
@@ -405,10 +460,13 @@ export const TERMINAL = (() => {
 	// off inside the test runtime so the xterm.js-backed virtual terminal (which
 	// ignores DECCARA) exercises the padded-string fallback. Integration tests opt
 	// in explicitly through setTerminalDeccara.
-	const deccara = detectRectangularSgrSupport(resolved.id, Bun.env) && !isBunTestRuntime();
-	if (resolved.deccara !== deccara) {
-		resolved = withTerminalOverrides(resolved, { deccara });
-	}
+	resolved.deccara = detectRectangularSgrSupport(resolved.id, Bun.env) && !isBunTestRuntime();
+	// A genuine local terminal scrolls to its tail on the submit keystroke, so the
+	// reconciliation checkpoint may ED3-rebuild on an unprobeable viewport there.
+	// Forced off under the test runtime (like deccara) so checkpoint tests stay
+	// deterministic and opt in through setTerminalSubmitPinsViewportToTail.
+	resolved.submitPinsViewportToTail =
+		detectSubmitPinsViewportToTail(Bun.env, process.platform) && !isBunTestRuntime();
 	return resolved;
 })();
 
@@ -418,18 +476,11 @@ export const TERMINAL = (() => {
 // glyphs, which is the "ASCII artifact + laggy scrolling" reported in #1877.
 setKittyGraphics({ unicodePlaceholders: detectKittyUnicodePlaceholdersSupport(TERMINAL.id, Bun.env) });
 
-type MutableTerminalInfo = {
-	imageProtocol: ImageProtocol | null;
-	deccara: boolean;
-	supportsScreenToScrollback: boolean;
-	textSizing: boolean;
-};
-
 /**
  * Override terminal image protocol at runtime after capability probes complete.
  */
 export function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): void {
-	(TERMINAL as unknown as MutableTerminalInfo).imageProtocol = imageProtocol;
+	TERMINAL.imageProtocol = imageProtocol;
 }
 
 /**
@@ -438,12 +489,17 @@ export function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): v
  * resolved once at import and force-disabled under the test runtime.
  */
 export function setTerminalDeccara(enabled: boolean): void {
-	(TERMINAL as unknown as MutableTerminalInfo).deccara = enabled;
+	TERMINAL.deccara = enabled;
 }
 
 /** Override screen-to-scrollback clear support for targeted renderer tests. */
 export function setTerminalScreenToScrollback(enabled: boolean): void {
-	(TERMINAL as unknown as MutableTerminalInfo).supportsScreenToScrollback = enabled;
+	TERMINAL.supportsScreenToScrollback = enabled;
+}
+
+/** Override submit-pins-viewport-to-tail for checkpoint reconciliation tests. */
+export function setTerminalSubmitPinsViewportToTail(enabled: boolean): void {
+	TERMINAL.submitPinsViewportToTail = enabled;
 }
 
 /**
@@ -452,7 +508,7 @@ export function setTerminalScreenToScrollback(enabled: boolean): void {
  * capability); tests flip it directly to exercise the scaled-heading path.
  */
 export function setTerminalTextSizing(enabled: boolean): void {
-	(TERMINAL as unknown as MutableTerminalInfo).textSizing = enabled;
+	TERMINAL.textSizing = enabled;
 }
 
 export function getTerminalInfo(terminalId: TerminalId): TerminalInfo {
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 95f997f70..3d8441564 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -1036,9 +1036,16 @@ export class TUI extends Container {
 			return false;
 		}
 		const nativeViewportAtBottom = this.#readNativeViewportAtBottom();
-		if (!this.#canReplayNativeScrollbackAtCheckpoint(nativeViewportAtBottom)) {
-			return false;
-		}
+		// The checkpoint fires at a prompt submit — a bottom-pinning user action. On a
+		// genuine local terminal the submit keystroke scrolls the host to its tail, so
+		// an unprobeable viewport is safely at-bottom and the ED3 replay will not yank
+		// a scrolled reader (the same explicit-user-action reasoning the resize rebuild
+		// uses). Hosts whose scrollback a keystroke does not move — Windows
+		// console/Terminal, SSH, multiplexers, unknown profiles — stay gated on a
+		// positive at-tail probe (#1610/#1682/#1746); a known-scrolled viewport always
+		// defers regardless of terminal.
+		if (nativeViewportAtBottom === false) return false;
+		if (nativeViewportAtBottom === undefined && !TERMINAL.submitPinsViewportToTail) return false;
 		this.#prepareForcedRender(true, false);
 		this.#renderRequested = false;
 		this.#lastRenderAt = this.#renderScheduler.now();

From d18cc3c7173bd3a9461175cbb82b12b1de287f9e Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:13:58 +0200
Subject: [PATCH 092/181] test(tests): extended auth-retry and read-link tests
 for updated checks

- Added a read-link probe test that renders text and image paths with active hyperlinks.
- Updated ai auth retry tests for revised static-key validation and rotation behavior.
---
 packages/ai/test/auth-retry.test.ts           |  6 +-
 .../auth-storage-force-refresh-rotate.test.ts |  4 +-
 packages/ai/test/stream-auth-retry.test.ts    |  2 +-
 .../test/tools/read-link-probe.test.ts        | 65 +++++++++++++++++++
 4 files changed, 70 insertions(+), 7 deletions(-)
 create mode 100644 packages/coding-agent/test/tools/read-link-probe.test.ts

diff --git a/packages/ai/test/auth-retry.test.ts b/packages/ai/test/auth-retry.test.ts
index 67609177f..d992a33c1 100644
--- a/packages/ai/test/auth-retry.test.ts
+++ b/packages/ai/test/auth-retry.test.ts
@@ -71,9 +71,9 @@ describe("withAuth", () => {
 	});
 
 	it("throws when a static key is missing", async () => {
-		await expect(
-			withAuth(undefined, async () => "never", { missingKeyMessage: "no key for foo" }),
-		).rejects.toThrow("no key for foo");
+		await expect(withAuth(undefined, async () => "never", { missingKeyMessage: "no key for foo" })).rejects.toThrow(
+			"no key for foo",
+		);
 	});
 
 	it("refreshes the same account, then switches, in order", async () => {
diff --git a/packages/ai/test/auth-storage-force-refresh-rotate.test.ts b/packages/ai/test/auth-storage-force-refresh-rotate.test.ts
index 24bc9d33b..fc7d0bb01 100644
--- a/packages/ai/test/auth-storage-force-refresh-rotate.test.ts
+++ b/packages/ai/test/auth-storage-force-refresh-rotate.test.ts
@@ -155,9 +155,7 @@ describe("AuthStorage forceRefresh + rotateSessionCredential", () => {
 	test("rotateSessionCredential returns false when the session has no sticky credential", async () => {
 		if (!authStorage) throw new Error("test setup failed");
 		registerProvider();
-		await authStorage.set(PROVIDER, [
-			{ type: "oauth", access: "acc-A", refresh: "ref-A", expires: farExpiry() },
-		]);
+		await authStorage.set(PROVIDER, [{ type: "oauth", access: "acc-A", refresh: "ref-A", expires: farExpiry() }]);
 
 		// Never resolved a key for this session → nothing to rotate away from.
 		expect(await authStorage.rotateSessionCredential(PROVIDER, "untouched", { error: authError() })).toBe(false);
diff --git a/packages/ai/test/stream-auth-retry.test.ts b/packages/ai/test/stream-auth-retry.test.ts
index 3511ed7fc..7192cb8c8 100644
--- a/packages/ai/test/stream-auth-retry.test.ts
+++ b/packages/ai/test/stream-auth-retry.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "bun:test";
-import { registerCustomApi, unregisterCustomApis } from "@oh-my-pi/pi-ai";
 import type { ApiKeyResolveContext } from "@oh-my-pi/pi-ai";
+import { registerCustomApi, unregisterCustomApis } from "@oh-my-pi/pi-ai";
 import { streamSimple } from "@oh-my-pi/pi-ai/stream";
 import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions, Usage } from "@oh-my-pi/pi-ai/types";
 import { AssistantMessageEventStream } from "@oh-my-pi/pi-ai/utils/event-stream";
diff --git a/packages/coding-agent/test/tools/read-link-probe.test.ts b/packages/coding-agent/test/tools/read-link-probe.test.ts
new file mode 100644
index 000000000..6b4bc2847
--- /dev/null
+++ b/packages/coding-agent/test/tools/read-link-probe.test.ts
@@ -0,0 +1,65 @@
+import { describe, it } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { resetSettingsForTest, Settings, settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import type { ToolSession } from "@oh-my-pi/pi-coding-agent/tools";
+import { ReadTool } from "@oh-my-pi/pi-coding-agent/tools/read";
+import { getThemeByName, initTheme } from "../../src/modes/theme/theme";
+import { readToolRenderer } from "../../src/tools/read";
+
+const TINY_PNG_BASE64 =
+	"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==";
+
+function extractLinkUris(text: string): string[] {
+	return [...text.matchAll(/\x1b\]8;[^;]*;([^\x1b]+)\x1b\\/g)].map(match => match[1]!);
+}
+
+function createTestToolSession(cwd: string): ToolSession {
+	return {
+		cwd,
+		hasUI: false,
+		getSessionFile: () => null,
+		getSessionSpawns: () => "*",
+		settings: Settings.isolated(),
+	};
+}
+
+describe("probe real read render", () => {
+	it("text and image link emission", async () => {
+		await initTheme();
+		resetSettingsForTest();
+		await Settings.init({ inMemory: true });
+		settings.override("tui.hyperlinks", "always");
+		const theme = await getThemeByName("dark");
+
+		const testDir = fs.mkdtempSync(path.join(os.tmpdir(), "probe-"));
+		const textPath = path.join(testDir, "v4-task.txt");
+		fs.writeFileSync(textPath, "hello world\nsecond line\n");
+		const imgPath = path.join(testDir, "v4-task.png");
+		fs.writeFileSync(imgPath, Buffer.from(TINY_PNG_BASE64, "base64"));
+
+		const tool = new ReadTool(createTestToolSession(testDir));
+		const textRes = await tool.execute("t", { path: textPath });
+		const imgRes = await tool.execute("i", { path: imgPath });
+
+		const textComp = readToolRenderer.renderResult(
+			{ content: textRes.content, details: textRes.details, isError: textRes.isError },
+			{ expanded: false, isPartial: false },
+			theme!,
+			{ path: textPath },
+		);
+		const imgComp = readToolRenderer.renderResult(
+			{ content: imgRes.content, details: imgRes.details, isError: imgRes.isError },
+			{ expanded: false, isPartial: false },
+			theme!,
+			{ path: imgPath },
+		);
+		console.log("TEXT URIS:", JSON.stringify(extractLinkUris(textComp.render(200).join("\n"))));
+		console.log("IMAGE URIS:", JSON.stringify(extractLinkUris(imgComp.render(200).join("\n"))));
+
+		settings.clearOverride("tui.hyperlinks");
+		resetSettingsForTest();
+		fs.rmSync(testDir, { recursive: true, force: true });
+	});
+});

From 1ebe2c74844f78da9e7dfb8a9d84e4a6c6dbe2b6 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:13:58 +0200
Subject: [PATCH 093/181] feat(packages/tui-and-shared-tooling-primitives):
 added TUI terminal support

- Made `Component.invalidate` optional in `packages/tui/src/tui.ts` and callsites.
- Added `iconOverride` support to status-line rendering in `status-line.ts`.
- Added `borderColor` and `framedBlock()` primitives in `output-block.ts` for framed output styling.
- Adjusted `renderOutputBlock()` to draw a continuous border when no header text is present.
- Added terminal checkpoint-reconciliation tests in `submit-checkpoint-reconcile.test.ts` for pinned-tail behavior.
---
 docs/tui.md                                   |   2 +-
 .../src/modes/setup-wizard/wizard-overlay.ts  |   2 +-
 packages/coding-agent/src/tui/output-block.ts |  34 ++++-
 packages/coding-agent/src/tui/status-line.ts  |   6 +-
 packages/tui/CHANGELOG.md                     |   4 +
 packages/tui/src/terminal-capabilities.ts     |   3 +-
 packages/tui/src/tui.ts                       |   4 +-
 .../test/submit-checkpoint-reconcile.test.ts  | 117 ++++++++++++++++++
 8 files changed, 160 insertions(+), 12 deletions(-)
 create mode 100644 packages/tui/test/submit-checkpoint-reconcile.test.ts

diff --git a/docs/tui.md b/docs/tui.md
index a62b5f0fe..cba829fbe 100644
--- a/docs/tui.md
+++ b/docs/tui.md
@@ -28,7 +28,7 @@ export interface Component {
   render(width: number): string[];
   handleInput?(data: string): void;
   wantsKeyRelease?: boolean;
-  invalidate(): void;
+  invalidate?(): void;
 }
 ```
 
diff --git a/packages/coding-agent/src/modes/setup-wizard/wizard-overlay.ts b/packages/coding-agent/src/modes/setup-wizard/wizard-overlay.ts
index 72176a870..0d39020de 100644
--- a/packages/coding-agent/src/modes/setup-wizard/wizard-overlay.ts
+++ b/packages/coding-agent/src/modes/setup-wizard/wizard-overlay.ts
@@ -82,7 +82,7 @@ export class SetupWizardComponent implements Component {
 	}
 
 	invalidate(): void {
-		this.#activeScene?.invalidate();
+		this.#activeScene?.invalidate?.();
 	}
 
 	handleInput(data: string): void {
diff --git a/packages/coding-agent/src/tui/output-block.ts b/packages/coding-agent/src/tui/output-block.ts
index 0176d7bdb..1ed78cb89 100644
--- a/packages/coding-agent/src/tui/output-block.ts
+++ b/packages/coding-agent/src/tui/output-block.ts
@@ -3,7 +3,7 @@
  */
 import type { Component } from "@oh-my-pi/pi-tui";
 import { ImageProtocol, padding, TERMINAL, visibleWidth, wrapTextWithAnsi } from "@oh-my-pi/pi-tui";
-import type { Theme } from "../modes/theme/theme";
+import type { Theme, ThemeColor } from "../modes/theme/theme";
 import { getSixelLineMask } from "../utils/sixel";
 import type { State } from "./types";
 import type { RenderCache } from "./utils";
@@ -18,6 +18,9 @@ export interface OutputBlockOptions {
 	applyBg?: boolean;
 	/** Animate the border with a sweeping dark segment (pending/running state). */
 	animate?: boolean;
+	/** Override the state-derived border color. Used for muted "legacy" tool
+	 * frames that should not visually compete with framed-output tools. */
+	borderColor?: ThemeColor;
 }
 
 const FRAMED_BLOCK_COMPONENT = Symbol("framedBlockComponent");
@@ -99,14 +102,15 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 	const cap = h.repeat(3);
 	const lineWidth = Math.max(0, width);
 	// Border colors: running/pending use accent, success uses dim (gray), error/warning keep their colors
-	const borderColor: "error" | "warning" | "accent" | "dim" =
-		state === "error"
+	const borderColor: ThemeColor =
+		options.borderColor ??
+		(state === "error"
 			? "error"
 			: state === "warning"
 				? "warning"
 				: state === "running" || state === "pending"
 					? "accent"
-					: "dim";
+					: "dim");
 	const border = (text: string) => theme.fg(borderColor, text);
 	const bgFn = (() => {
 		if (!state || !applyBg) return undefined;
@@ -202,7 +206,12 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 		const rightGlyph = row.rightChar;
 		if (lineWidth <= 0) return border(leftGlyphs) + border(rightGlyph);
 		const labelText = [row.label, row.meta].filter(Boolean).join(theme.sep.dot);
-		const rawLabel = labelText ? ` ${labelText} ` : " ";
+		if (!labelText) {
+			// No header: draw a clean, continuous top/separator bar (no 1-col gap).
+			const fillCount = Math.max(0, lineWidth - visibleWidth(leftGlyphs) - visibleWidth(rightGlyph));
+			return `${border(leftGlyphs)}${border(h.repeat(fillCount))}${border(rightGlyph)}`;
+		}
+		const rawLabel = ` ${labelText} `;
 		const leftWidth = visibleWidth(leftGlyphs);
 		const rightWidth = visibleWidth(rightGlyph);
 		const maxLabelWidth = Math.max(0, lineWidth - leftWidth - rightWidth);
@@ -272,6 +281,7 @@ export class CachedOutputBlock {
 		h.optional(options.header);
 		h.optional(options.headerMeta);
 		h.optional(options.state);
+		h.optional(options.borderColor);
 		h.bool(options.applyBg ?? true);
 		h.bool(options.animate ?? false);
 		if (options.animate) h.u32(borderShimmerTick());
@@ -286,3 +296,17 @@ export class CachedOutputBlock {
 		return h.digest();
 	}
 }
+
+/**
+ * Build a self-framing tool component backed by a cached output block. The
+ * `build` callback returns the block options for a given width; the cache
+ * dedupes re-renders. Pass `borderColor: "borderMuted"` for the dim "legacy"
+ * look that does not compete with the state-colored framed tools.
+ */
+export function framedBlock(theme: Theme, build: (width: number) => OutputBlockOptions): Component {
+	const block = new CachedOutputBlock();
+	return {
+		render: (width: number): string[] => block.render(build(width), theme),
+		invalidate: () => block.invalidate(),
+	};
+}
diff --git a/packages/coding-agent/src/tui/status-line.ts b/packages/coding-agent/src/tui/status-line.ts
index 043b78e41..0a227a28b 100644
--- a/packages/coding-agent/src/tui/status-line.ts
+++ b/packages/coding-agent/src/tui/status-line.ts
@@ -7,6 +7,9 @@ import { formatStatusIcon } from "../tools/render-utils";
 
 export interface StatusLineOptions {
 	icon?: ToolUIStatus;
+	/** Pre-rendered glyph that replaces the status icon (e.g. a magnifier for
+	 * search-family tools). Takes precedence over `icon`. */
+	iconOverride?: string;
 	spinnerFrame?: number;
 	title: string;
 	titleColor?: ThemeColor;
@@ -27,7 +30,8 @@ function flattenForHeader(text: string): string {
 }
 
 export function renderStatusLine(options: StatusLineOptions, theme: Theme): string {
-	const icon = options.icon ? formatStatusIcon(options.icon, theme, options.spinnerFrame) : "";
+	const icon =
+		options.iconOverride ?? (options.icon ? formatStatusIcon(options.icon, theme, options.spinnerFrame) : "");
 	const titleColor = options.titleColor ?? "accent";
 	const title = theme.fg(titleColor, flattenForHeader(options.title));
 	let line = icon ? `${icon} ${title}` : title;
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 74e23d959..475340401 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -14,6 +14,10 @@
 - Added `ScrollView.handleScrollKey()` plus a `fastScrollLines` option so every scroll view gets shared navigation keys, including Shift+Arrow to scroll faster.
 - Added `OverlayOptions.fullscreen`: while the topmost visible overlay sets it, the engine borrows the terminal's alternate screen buffer for the overlay's lifetime and paints only the modal there — no ED3, no transcript re-commit — so the transcript stays untouched on the normal screen and is not scrollable behind the modal. Mouse tracking (`?1000h`/`?1006h`) is enabled for the modal's lifetime and disabled on exit, so the rest of the app keeps the terminal's native text selection.
 
+### Changed
+
+- Made `Component.invalidate()` optional so leaf components without render caches no longer need no-op invalidation hooks.
+
 ## [15.10.0] - 2026-06-06
 
 ### Changed
diff --git a/packages/tui/src/terminal-capabilities.ts b/packages/tui/src/terminal-capabilities.ts
index de9d6665f..599fa81fb 100644
--- a/packages/tui/src/terminal-capabilities.ts
+++ b/packages/tui/src/terminal-capabilities.ts
@@ -465,8 +465,7 @@ export const TERMINAL: RuntimeTerminal = (() => {
 	// reconciliation checkpoint may ED3-rebuild on an unprobeable viewport there.
 	// Forced off under the test runtime (like deccara) so checkpoint tests stay
 	// deterministic and opt in through setTerminalSubmitPinsViewportToTail.
-	resolved.submitPinsViewportToTail =
-		detectSubmitPinsViewportToTail(Bun.env, process.platform) && !isBunTestRuntime();
+	resolved.submitPinsViewportToTail = detectSubmitPinsViewportToTail(Bun.env, process.platform) && !isBunTestRuntime();
 	return resolved;
 })();
 
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 3d8441564..a2e18d20e 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -129,10 +129,10 @@ export interface Component {
 	wantsKeyRelease?: boolean;
 
 	/**
-	 * Invalidate any cached rendering state.
+	 * Optional hook to invalidate any cached rendering state.
 	 * Called when theme changes or when component needs to re-render from scratch.
 	 */
-	invalidate(): void;
+	invalidate?(): void;
 
 	/**
 	 * Optional teardown. Called when the component is permanently removed from
diff --git a/packages/tui/test/submit-checkpoint-reconcile.test.ts b/packages/tui/test/submit-checkpoint-reconcile.test.ts
new file mode 100644
index 000000000..7c10e1ef9
--- /dev/null
+++ b/packages/tui/test/submit-checkpoint-reconcile.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, it } from "bun:test";
+import { type Component, setTerminalSubmitPinsViewportToTail, TERMINAL, TUI } from "@oh-my-pi/pi-tui";
+import { VirtualTerminal } from "./virtual-terminal";
+
+// The prompt-submit reconciliation checkpoint (`refreshNativeScrollbackIfDirty`)
+// must ED3-rebuild deferred-dirty native scrollback on genuine local terminals,
+// where the submit keystroke pins the host to its tail, even though their viewport
+// position is unprobeable (ghostty/kitty/iTerm report `undefined`). Without this,
+// every offscreen shrink/edit that defers during streaming leaves stale rows above
+// the viewport that never clear until Ctrl+L or a resize. Hosts that cannot prove
+// at-tail (Windows console/Terminal, SSH, multiplexers — modeled here by
+// submitPinsViewportToTail=false) keep deferring so a scrolled reader is never
+// yanked by ED3 (#1610/#1682/#1746).
+
+class LineList implements Component {
+	#lines: string[];
+	constructor(lines: string[]) {
+		this.#lines = [...lines];
+	}
+	invalidate(): void {}
+	render(width: number): string[] {
+		return this.#lines.map(line => line.slice(0, width));
+	}
+	setLines(lines: string[]): void {
+		this.#lines = [...lines];
+	}
+}
+
+async function settle(term: VirtualTerminal): Promise<void> {
+	const tick = Promise.withResolvers<void>();
+	process.nextTick(tick.resolve);
+	await tick.promise;
+	await Bun.sleep(20);
+	await term.flush();
+}
+
+function capture(term: VirtualTerminal): string[] {
+	const writes: string[] = [];
+	const realWrite = term.write.bind(term);
+	(term as unknown as { write: (s: string) => void }).write = (data: string) => {
+		writes.push(data);
+		realWrite(data);
+	};
+	return writes;
+}
+
+function overrideProbe(term: VirtualTerminal, answer: boolean | undefined): void {
+	(term as unknown as { isNativeViewportAtBottom: () => boolean | undefined }).isNativeViewportAtBottom = () => answer;
+}
+
+const eraseScrollbackCount = (writes: string[]): number => (writes.join("").match(/\x1b\[3J/g) ?? []).length;
+
+interface CheckpointResult {
+	deferredErases: number;
+	reconciled: boolean;
+	checkpointErases: number;
+	viewport: string[];
+}
+
+// Drive an ED3-risk terminal with an unprobeable viewport through an eager-stream
+// offscreen shrink (which defers, marking native scrollback dirty without erasing)
+// and then the prompt-submit checkpoint, returning what each step emitted.
+async function deferThenCheckpoint(submitPinsViewportToTail: boolean): Promise<CheckpointResult> {
+	const savedRisk = TERMINAL.eagerEraseScrollbackRisk;
+	const savedPins = TERMINAL.submitPinsViewportToTail;
+	// RuntimeTerminal exposes these as writable — no cast needed.
+	TERMINAL.eagerEraseScrollbackRisk = true;
+	setTerminalSubmitPinsViewportToTail(submitPinsViewportToTail);
+	const term = new VirtualTerminal(80, 12);
+	overrideProbe(term, undefined);
+	const tui = new TUI(term);
+	const component = new LineList(Array.from({ length: 60 }, (_value, index) => `init-${index}`));
+	tui.addChild(component);
+	try {
+		tui.start();
+		await settle(term);
+		const writes = capture(term);
+		tui.setEagerNativeScrollbackRebuild(true);
+
+		// Offscreen shrink: repaints the visible window in place and marks native
+		// scrollback dirty instead of erasing (the deferral that strands stale rows).
+		component.setLines(Array.from({ length: 4 }, (_value, index) => `done-${index}`));
+		tui.requestRender();
+		await settle(term);
+		const deferredErases = eraseScrollbackCount(writes);
+
+		const reconciled = tui.refreshNativeScrollbackIfDirty();
+		await settle(term);
+		return {
+			deferredErases,
+			reconciled,
+			checkpointErases: eraseScrollbackCount(writes),
+			viewport: term.getViewport().map(line => line.trim()),
+		};
+	} finally {
+		tui.stop();
+		TERMINAL.eagerEraseScrollbackRisk = savedRisk;
+		setTerminalSubmitPinsViewportToTail(savedPins);
+	}
+}
+
+describe("submit-checkpoint native scrollback reconciliation", () => {
+	it("reconciles deferred scrollback at the checkpoint when submit pins the host to its tail", async () => {
+		const result = await deferThenCheckpoint(true);
+		expect(result.deferredErases).toBe(0);
+		expect(result.reconciled).toBe(true);
+		expect(result.checkpointErases).toBeGreaterThan(0);
+		expect(result.viewport).toContain("done-3");
+	});
+
+	it("keeps deferring at the checkpoint when the host cannot prove at-tail", async () => {
+		const result = await deferThenCheckpoint(false);
+		expect(result.deferredErases).toBe(0);
+		expect(result.reconciled).toBe(false);
+		expect(result.checkpointErases).toBe(0);
+	});
+});

From 28c3e2a9868226a8b7f8424e85997f3dec9f1027 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:13:58 +0200
Subject: [PATCH 094/181] feat(task-rendering): added unified call/result task
 rendering

- Enabled call/result merging by setting mergeCallAndResult on TaskTool.
- Reworked task item lines into bullet lists and removed tree-style prefixes.
- Rendered task calls as framed blocks with isolated headers and pending status metadata.
- Changed result previews to hide task titles and `Tasks` headings when a result is present.
---
 packages/coding-agent/src/task/index.ts       |   4 +
 packages/coding-agent/src/task/render.ts      | 299 ++++++++++--------
 .../test/task/render-call.test.ts             |  20 +-
 3 files changed, 173 insertions(+), 150 deletions(-)

diff --git a/packages/coding-agent/src/task/index.ts b/packages/coding-agent/src/task/index.ts
index fe3f6f626..befea661d 100644
--- a/packages/coding-agent/src/task/index.ts
+++ b/packages/coding-agent/src/task/index.ts
@@ -275,6 +275,10 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 	readonly strict = true;
 	readonly loadMode = "discoverable";
 	readonly renderResult = renderResult;
+	// Suppress the streaming call preview once a (partial or final) result exists
+	// so the task renders as ONE block that transitions in place — not a pending
+	// call frame stacked above the result frame. Mirrors `taskToolRenderer`.
+	readonly mergeCallAndResult = true;
 	readonly #discoveredAgents: AgentDefinition[];
 	readonly #blockedAgent: string | undefined;
 
diff --git a/packages/coding-agent/src/task/render.ts b/packages/coding-agent/src/task/render.ts
index f6cc1fc0e..03cc9649d 100644
--- a/packages/coding-agent/src/task/render.ts
+++ b/packages/coding-agent/src/task/render.ts
@@ -18,6 +18,7 @@ import {
 	formatMoreItems,
 	formatStatusIcon,
 	replaceTabs,
+	type ToolUIStatus,
 	truncateToWidth,
 } from "../tools/render-utils";
 import {
@@ -28,7 +29,7 @@ import {
 	type ReportFindingDetails,
 	type SubmitReviewDetails,
 } from "../tools/review";
-import { Ellipsis, Hasher, type RenderCache, renderStatusLine } from "../tui";
+import { framedBlock, renderStatusLine } from "../tui";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
 import type { AgentProgress, SingleResult, TaskItem, TaskParams, TaskToolDetails } from "./types";
 
@@ -506,28 +507,20 @@ function formatOutputInline(data: unknown, theme: Theme, maxWidth = 80): string
  * preview. The args stream in token by token, so the array grows over time and
  * trailing entries may be partially parsed — every field access is defensive.
  */
-function renderTaskItemLines(
-	tasks: TaskItem[] | undefined,
-	contPrefix: string,
-	expanded: boolean,
-	theme: Theme,
-): string[] {
+function renderTaskItemLines(tasks: TaskItem[] | undefined, expanded: boolean, theme: Theme): string[] {
 	const items = tasks ?? [];
 	if (items.length === 0) return [];
 
-	const branch = theme.fg("dim", theme.tree.branch);
-	const last = theme.fg("dim", theme.tree.last);
+	const bullet = theme.fg("dim", "•");
 	const cap = expanded ? items.length : Math.min(items.length, 12);
 	const truncated = cap < items.length;
 
 	const lines: string[] = [];
 	for (let i = 0; i < cap; i++) {
 		const task = items[i] as Partial<TaskItem> | undefined;
-		const isLastLine = !truncated && i === items.length - 1;
-		const connector = isLastLine ? last : branch;
 		const rawId = task?.id?.trim();
 		const idLabel = rawId ? formatTaskId(rawId) : `#${i + 1}`;
-		let line = `${contPrefix}${connector} ${theme.fg("accent", theme.bold(idLabel))}`;
+		let line = `${bullet} ${theme.fg("accent", theme.bold(idLabel))}`;
 		const desc = task?.description?.trim();
 		if (desc) {
 			line += `: ${theme.fg("muted", truncateToWidth(replaceTabs(desc), 64))}`;
@@ -535,7 +528,7 @@ function renderTaskItemLines(
 		lines.push(line);
 	}
 	if (truncated) {
-		lines.push(`${contPrefix}${last} ${theme.fg("dim", formatMoreItems(items.length - cap, "agent"))}`);
+		lines.push(`${bullet} ${theme.fg("dim", formatMoreItems(items.length - cap, "agent"))}`);
 	}
 	return lines;
 }
@@ -548,44 +541,39 @@ export function renderCall(
 	options: RenderResultOptions & { renderContext?: { hasResult?: boolean } },
 	theme: Theme,
 ): Component {
-	const lines: string[] = [];
-	lines.push(renderStatusLine({ icon: "pending", title: "Task", description: args.agent }, theme));
-
-	const context = (args.context ?? "").trim();
-	const hasContext = context.length > 0;
-	const branch = theme.fg("dim", theme.tree.branch);
-	const last = theme.fg("dim", theme.tree.last);
-	const vertical = theme.fg("dim", theme.tree.vertical);
 	const showIsolated = "isolated" in args && args.isolated === true;
-	const taskCount = args.tasks?.length ?? 0;
+	const header = renderStatusLine({ icon: "pending", title: "Task", description: args.agent }, theme);
+	return framedBlock(theme, width => {
+		const context = (args.context ?? "").trim();
+		const taskCount = args.tasks?.length ?? 0;
+		const sections: Array<{ label?: string; lines: string[] }> = [];
 
-	if (hasContext) {
-		lines.push(` ${branch} ${theme.fg("dim", "Context")}`);
-		const contextLines = context.split("\n").map(line => {
-			const content = line ? theme.fg("muted", replaceTabs(line)) : "";
-			return ` ${vertical}  ${content}`;
-		});
-		lines.push(...contextLines);
-	}
+		if (context) {
+			sections.push({
+				lines: context.split("\n").map(line => (line ? theme.fg("muted", replaceTabs(line)) : "")),
+			});
+		}
 
-	// `Tasks` is the last child unless the isolation flag follows it.
-	const tasksIsLast = !showIsolated;
-	const tasksPrefix = tasksIsLast ? last : branch;
-	lines.push(` ${tasksPrefix} ${theme.fg("dim", "Tasks")} ${theme.fg("muted", `(${taskCount})`)}`);
-	const tasksContPrefix = tasksIsLast ? "    " : ` ${vertical}  `;
-	// The per-task preview list only exists to surface dispatched agents while
-	// the call args stream in. Once a result snapshot exists, `renderResult`
-	// draws the same agents as progress/result lines (id + description), so
-	// emitting the preview here would render every task twice.
-	if (!options.renderContext?.hasResult) {
-		lines.push(...renderTaskItemLines(args.tasks, tasksContPrefix, options.expanded, theme));
-	}
+		// The per-task preview list only exists to surface dispatched agents while
+		// the call args stream in. Once a result snapshot exists, `renderResult`
+		// draws the same agents as progress/result lines, so showing the Tasks
+		// section here would just repeat the count the result frame already shows.
+		if (!options.renderContext?.hasResult) {
+			sections.push({
+				label: `Tasks (${taskCount})`,
+				lines: renderTaskItemLines(args.tasks, options.expanded, theme),
+			});
+		}
 
-	if (showIsolated) {
-		lines.push(` ${last} ${theme.fg("dim", "Isolated")}: ${theme.fg("muted", "true")}`);
-	}
-
-	return new Text(lines.join("\n"), 0, 0);
+		return {
+			header,
+			headerMeta: showIsolated ? "isolated" : undefined,
+			sections,
+			state: "pending",
+			borderColor: "borderMuted",
+			width,
+		};
+	});
 }
 
 /**
@@ -593,14 +581,13 @@ export function renderCall(
  */
 function renderAgentProgress(
 	progress: AgentProgress,
-	isLast: boolean,
+	prefix: string,
+	continuePrefix: string,
 	expanded: boolean,
 	theme: Theme,
 	spinnerFrame?: number,
 ): string[] {
 	const lines: string[] = [];
-	const prefix = isLast ? theme.fg("dim", theme.tree.last) : theme.fg("dim", theme.tree.branch);
-	const continuePrefix = isLast ? "   " : `${theme.fg("dim", theme.tree.vertical)}  `;
 
 	const icon = getStatusIcon(progress.status, theme, spinnerFrame);
 	const iconColor =
@@ -614,7 +601,7 @@ function renderAgentProgress(
 	const description = progress.description?.trim();
 	const displayId = formatTaskId(progress.id);
 	const titlePart = description ? `${theme.bold(displayId)}: ${description}` : displayId;
-	let statusLine = `${prefix} ${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)}`;
+	let statusLine = `${prefix ? `${prefix} ` : ""}${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)}`;
 
 	// Show retry-blocked badge so the parent immediately sees that a child
 	// is sleeping on a provider 429, not silently progressing. Wins over the
@@ -867,10 +854,14 @@ function renderFindings(
 /**
  * Render final result for a single agent.
  */
-function renderAgentResult(result: SingleResult, isLast: boolean, expanded: boolean, theme: Theme): string[] {
+function renderAgentResult(
+	result: SingleResult,
+	prefix: string,
+	continuePrefix: string,
+	expanded: boolean,
+	theme: Theme,
+): string[] {
 	const lines: string[] = [];
-	const prefix = isLast ? theme.fg("dim", theme.tree.last) : theme.fg("dim", theme.tree.branch);
-	const continuePrefix = isLast ? "   " : `${theme.fg("dim", theme.tree.vertical)}  `;
 
 	const { warning: missingCompleteWarning, rest: outputWithoutWarning } = extractMissingYieldWarning(result.output);
 	const aborted = result.aborted ?? false;
@@ -899,7 +890,7 @@ function renderAgentResult(result: SingleResult, isLast: boolean, expanded: bool
 	const description = result.description?.trim();
 	const displayId = formatTaskId(result.id);
 	const titlePart = description ? `${theme.bold(displayId)}: ${description}` : displayId;
-	let statusLine = `${prefix} ${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)} ${formatBadge(
+	let statusLine = `${prefix ? `${prefix} ` : ""}${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)} ${formatBadge(
 		statusText,
 		iconColor,
 		theme,
@@ -1049,95 +1040,112 @@ export function renderResult(
 
 	if (!details) {
 		const text = result.content.find(c => c.type === "text")?.text || "";
-		return new Text(theme.fg("dim", truncateToWidth(text, 100)), 0, 0);
+		const header = renderStatusLine({ icon: "success", title: "Task" }, theme);
+		return framedBlock(theme, width => ({
+			header,
+			sections: text ? [{ lines: [theme.fg("dim", truncateToWidth(text, width))] }] : [],
+			state: "success",
+			borderColor: "borderMuted",
+			width,
+		}));
 	}
 
-	let cached: RenderCache | undefined;
+	const hasResults = Boolean(details.results && details.results.length > 0);
+	const aborted = hasResults && details.results.some(r => r.aborted);
+	const failed = hasResults && details.results.some(r => !r.aborted && r.exitCode !== 0);
+	const mergeFailed = hasResults && details.results.some(r => !r.aborted && r.exitCode === 0 && Boolean(r.error));
+	const isError = aborted || failed;
+	const agentCount = hasResults ? details.results.length : (details.progress?.length ?? 0);
+	const icon: ToolUIStatus = options.isPartial ? "running" : isError ? "error" : mergeFailed ? "warning" : "success";
+	const header = renderStatusLine(
+		{
+			icon,
+			spinnerFrame: options.spinnerFrame,
+			title: "Task",
+			meta: agentCount > 0 ? [`${agentCount} ${agentCount === 1 ? "agent" : "agents"}`] : undefined,
+		},
+		theme,
+	);
 
-	return {
-		render(width) {
-			const { expanded, isPartial, spinnerFrame } = options;
-			const key = new Hasher()
-				.bool(expanded)
-				.bool(isPartial)
-				.u32(spinnerFrame ?? 0)
-				.u32(width)
-				.digest();
-			if (cached?.key === key) return cached.lines;
+	return framedBlock(theme, width => {
+		const { expanded, isPartial, spinnerFrame } = options;
+		const lines: string[] = [];
 
-			const lines: string[] = [];
+		const shouldRenderProgress =
+			Boolean(details.progress && details.progress.length > 0) && (isPartial || details.results.length === 0);
+		if (shouldRenderProgress && details.progress) {
+			details.progress.forEach(progress => {
+				lines.push(...renderAgentProgress(progress, "", "  ", expanded, theme, spinnerFrame));
+			});
+		} else if (details.results && details.results.length > 0) {
+			details.results.forEach(res => {
+				lines.push(...renderAgentResult(res, "", "  ", expanded, theme));
+			});
 
-			const shouldRenderProgress =
-				Boolean(details.progress && details.progress.length > 0) && (isPartial || details.results.length === 0);
-			if (shouldRenderProgress && details.progress) {
-				details.progress.forEach((progress, i) => {
-					const isLast = i === details.progress!.length - 1;
-					lines.push(...renderAgentProgress(progress, isLast, expanded, theme, spinnerFrame));
-				});
-			} else if (details.results && details.results.length > 0) {
-				details.results.forEach((res, i) => {
-					const isLast = i === details.results.length - 1;
-					lines.push(...renderAgentResult(res, isLast, expanded, theme));
-				});
-
-				const abortedCount = details.results.filter(r => r.aborted).length;
-				const mergeFailedCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && r.error).length;
-				const successCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && !r.error).length;
-				const failCount = details.results.length - successCount - mergeFailedCount - abortedCount;
-				let summary = `${theme.fg("dim", "Total:")} `;
-				if (abortedCount > 0) {
-					summary += theme.fg("error", `${abortedCount} aborted`);
-					if (successCount > 0 || mergeFailedCount > 0 || failCount > 0) summary += theme.sep.dot;
-				}
-				if (successCount > 0) {
-					summary += theme.fg("success", `${successCount} succeeded`);
-					if (mergeFailedCount > 0 || failCount > 0) summary += theme.sep.dot;
-				}
-				if (mergeFailedCount > 0) {
-					summary += theme.fg("warning", `${mergeFailedCount} merge failed`);
-					if (failCount > 0) summary += theme.sep.dot;
-				}
-				if (failCount > 0) {
-					summary += theme.fg("error", `${failCount} failed`);
-				}
-				summary += `${theme.sep.dot}${theme.fg("dim", formatDuration(details.totalDurationMs))}`;
-				lines.push(summary);
+			const abortedCount = details.results.filter(r => r.aborted).length;
+			const mergeFailedCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && r.error).length;
+			const successCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && !r.error).length;
+			const failCount = details.results.length - successCount - mergeFailedCount - abortedCount;
+			let summary = `${theme.fg("dim", "Total:")} `;
+			if (abortedCount > 0) {
+				summary += theme.fg("error", `${abortedCount} aborted`);
+				if (successCount > 0 || mergeFailedCount > 0 || failCount > 0) summary += theme.sep.dot;
 			}
-
-			if (lines.length === 0) {
-				const text = fallbackText.trim() ? fallbackText : "No results";
-				const result = [theme.fg("dim", truncateToWidth(text, width))];
-				cached = { key, lines: result };
-				return result;
+			if (successCount > 0) {
+				summary += theme.fg("success", `${successCount} succeeded`);
+				if (mergeFailedCount > 0 || failCount > 0) summary += theme.sep.dot;
 			}
-
-			if (fallbackText.trim()) {
-				const summaryLines = fallbackText.split("\n");
-				const markerIndex = summaryLines.findIndex(
-					line =>
-						line.includes("<system-notification>") ||
-						line.startsWith("Applied patches:") ||
-						line.startsWith("No changes to apply."),
-				);
-				if (markerIndex >= 0) {
-					const extra = summaryLines.slice(markerIndex);
-					for (const line of extra) {
-						if (!line.trim()) continue;
-						lines.push(theme.fg("dim", line));
-					}
-				}
+			if (mergeFailedCount > 0) {
+				summary += theme.fg("warning", `${mergeFailedCount} merge failed`);
+				if (failCount > 0) summary += theme.sep.dot;
 			}
+			if (failCount > 0) {
+				summary += theme.fg("error", `${failCount} failed`);
+			}
+			summary += `${theme.sep.dot}${theme.fg("dim", formatDuration(details.totalDurationMs))}`;
+			lines.push(summary);
+		}
 
-			const indented = lines.map(line =>
-				line.length > 0 ? truncateToWidth(`   ${line}`, width, Ellipsis.Omit) : "",
+		const state = isPartial ? "running" : isError ? "error" : mergeFailed ? "warning" : "success";
+		const borderColor = isError ? "error" : "borderMuted";
+
+		if (lines.length === 0) {
+			const text = fallbackText.trim() ? fallbackText : "No results";
+			return {
+				header,
+				sections: [{ lines: [theme.fg("dim", truncateToWidth(text, width))] }],
+				state,
+				borderColor,
+				width,
+			};
+		}
+
+		if (fallbackText.trim()) {
+			const summaryLines = fallbackText.split("\n");
+			const markerIndex = summaryLines.findIndex(
+				line =>
+					line.includes("<system-notification>") ||
+					line.startsWith("Applied patches:") ||
+					line.startsWith("No changes to apply."),
 			);
-			cached = { key, lines: indented };
-			return indented;
-		},
-		invalidate() {
-			cached = undefined;
-		},
-	};
+			if (markerIndex >= 0) {
+				const extra = summaryLines.slice(markerIndex);
+				for (const line of extra) {
+					if (!line.trim()) continue;
+					lines.push(theme.fg("dim", line));
+				}
+			}
+		}
+
+		while (lines.length > 0 && lines[0].trim() === "") lines.shift();
+		return {
+			header,
+			sections: lines.length > 0 ? [{ lines }] : [],
+			state,
+			borderColor,
+			width,
+		};
+	});
 }
 
 function isTaskToolDetails(value: unknown): value is TaskToolDetails {
@@ -1149,13 +1157,23 @@ function isTaskToolDetails(value: unknown): value is TaskToolDetails {
 	);
 }
 
+// Nested subagent snapshots sit one or more levels below the frame border, so
+// they keep tree guides to convey depth (the parent prepends its own continue
+// prefix). Only the top-level agent list drops guides (the frame is its box).
+function nestedMarkers(isLast: boolean, theme: Theme): { prefix: string; continuePrefix: string } {
+	return {
+		prefix: isLast ? theme.fg("dim", theme.tree.last) : theme.fg("dim", theme.tree.branch),
+		continuePrefix: isLast ? "   " : `${theme.fg("dim", theme.tree.vertical)}  `,
+	};
+}
+
 function renderNestedTaskResults(detailsList: TaskToolDetails[], expanded: boolean, theme: Theme): string[] {
 	const lines: string[] = [];
 	for (const details of detailsList) {
 		if (!details.results || details.results.length === 0) continue;
 		details.results.forEach((result, index) => {
-			const isLast = index === details.results.length - 1;
-			lines.push(...renderAgentResult(result, isLast, expanded, theme));
+			const { prefix, continuePrefix } = nestedMarkers(index === details.results.length - 1, theme);
+			lines.push(...renderAgentResult(result, prefix, continuePrefix, expanded, theme));
 		});
 	}
 	return lines;
@@ -1177,16 +1195,16 @@ function renderNestedTaskTree(
 		const hasResults = Boolean(details.results && details.results.length > 0);
 		if (hasResults) {
 			details.results.forEach((result, index) => {
-				const isLast = index === details.results.length - 1;
-				lines.push(...renderAgentResult(result, isLast, expanded, theme));
+				const { prefix, continuePrefix } = nestedMarkers(index === details.results.length - 1, theme);
+				lines.push(...renderAgentResult(result, prefix, continuePrefix, expanded, theme));
 			});
 			continue;
 		}
 		const inflight = details.progress;
 		if (inflight && inflight.length > 0) {
 			inflight.forEach((prog, index) => {
-				const isLast = index === inflight.length - 1;
-				lines.push(...renderAgentProgress(prog, isLast, expanded, theme, spinnerFrame));
+				const { prefix, continuePrefix } = nestedMarkers(index === inflight.length - 1, theme);
+				lines.push(...renderAgentProgress(prog, prefix, continuePrefix, expanded, theme, spinnerFrame));
 			});
 		}
 	}
@@ -1207,4 +1225,5 @@ subprocessToolRegistry.register<TaskToolDetails>("task", {
 export const taskToolRenderer = {
 	renderCall,
 	renderResult,
+	mergeCallAndResult: true,
 };
diff --git a/packages/coding-agent/test/task/render-call.test.ts b/packages/coding-agent/test/task/render-call.test.ts
index 35393e19c..c7652a5df 100644
--- a/packages/coding-agent/test/task/render-call.test.ts
+++ b/packages/coding-agent/test/task/render-call.test.ts
@@ -84,7 +84,7 @@ describe("task renderer: streaming call preview", () => {
 		expect(expanded).not.toContain("more agents");
 	});
 
-	it("keeps the isolation flag as the final child after the task list", () => {
+	it("surfaces the isolation flag in the header bar", () => {
 		const args: TaskParams = {
 			agent: "task",
 			isolated: true,
@@ -94,15 +94,16 @@ describe("task renderer: streaming call preview", () => {
 		const lines = out.split("\n");
 
 		expect(out).toContain("Only");
-		expect(out).toContain("Isolated");
-		// Isolation flag is rendered last, after every task entry.
-		expect(lines.at(-1)).toContain("Isolated");
+		// Isolation is surfaced as header meta in the frame's top bar (first line),
+		// not as a trailing child row under the task list.
+		expect(lines[0]).toContain("isolated");
 	});
 
-	// Once the tool produces a result, `renderResult` draws each agent as a
-	// progress/result line. The call preview must drop its own per-agent list
-	// so the non-streaming path doesn't render every task twice.
-	it("suppresses the per-task preview list once a result snapshot exists", () => {
+	// Once the tool produces a result, the container suppresses the call entirely
+	// via `mergeCallAndResult` and `renderResult` draws each agent. As a safety
+	// net, `renderCall` also drops its duplicate per-task preview when a result
+	// snapshot is present, so the two never stack.
+	it("drops the per-task preview list once a result snapshot exists", () => {
 		const args: TaskParams = {
 			agent: "reviewer",
 			tasks: [
@@ -117,9 +118,8 @@ describe("task renderer: streaming call preview", () => {
 		);
 		const out = Bun.stripANSI(component.render(160).join("\n"));
 
-		// Header stays as a section label, but the duplicated agent rows are gone.
-		expect(out).toContain("Tasks (2)");
 		expect(out).not.toContain("Audit the auth module");
 		expect(out).not.toContain("Audit the db layer");
+		expect(out).not.toContain("Tasks (");
 	});
 });

From eedf9bc6a878b07e4ccba158e5a1140689389bf9 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:13:58 +0200
Subject: [PATCH 095/181] feat(search-tooling): added search-tool icon lists
 with framed output

- Added `icon.search` to theme symbol maps and used it for Search, Find, AST Grep, and BM25 success headers.
- Reworked `searchToolBm25Renderer` results into framed bullet lists with expand-item hints.
- Updated renderer tests to match the new search-tool output contract.
---
 .../coding-agent/src/modes/theme/theme.ts     |  4 ++
 packages/coding-agent/src/tools/ast-grep.ts   |  9 ++-
 packages/coding-agent/src/tools/find.ts       |  6 +-
 .../src/tools/search-tool-bm25.ts             | 59 +++++++++++--------
 packages/coding-agent/src/tools/search.ts     | 16 ++++-
 .../test/tools/search-renderer.test.ts        |  4 +-
 6 files changed, 68 insertions(+), 30 deletions(-)

diff --git a/packages/coding-agent/src/modes/theme/theme.ts b/packages/coding-agent/src/modes/theme/theme.ts
index 5be8f207e..963bade66 100644
--- a/packages/coding-agent/src/modes/theme/theme.ts
+++ b/packages/coding-agent/src/modes/theme/theme.ts
@@ -95,6 +95,7 @@ export type SymbolKey =
 	| "icon.pause"
 	| "icon.loop"
 	| "icon.folder"
+	| "icon.search"
 	| "icon.scratchFolder"
 	| "icon.file"
 	| "icon.git"
@@ -264,6 +265,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.pause": "⏸",
 	"icon.loop": "↻",
 	"icon.folder": "📁",
+	"icon.search": "🔍",
 	"icon.scratchFolder": "🗑",
 	"icon.file": "📄",
 	"icon.git": "⎇",
@@ -488,6 +490,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.loop": "\uf021",
 	// pick:  | alt:  
 	"icon.folder": "\uf115",
+	"icon.search": "\uf002",
 	// pick:  | alt:
 	"icon.scratchFolder": "\uf014",
 	// pick:  | alt:  
@@ -701,6 +704,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.pause": "||",
 	"icon.loop": "loop",
 	"icon.folder": "[D]",
+	"icon.search": "[/]",
 	"icon.scratchFolder": "[T]",
 	"icon.file": "[F]",
 	"icon.git": "git:",
diff --git a/packages/coding-agent/src/tools/ast-grep.ts b/packages/coding-agent/src/tools/ast-grep.ts
index 7bf277148..9f2124240 100644
--- a/packages/coding-agent/src/tools/ast-grep.ts
+++ b/packages/coding-agent/src/tools/ast-grep.ts
@@ -380,7 +380,14 @@ export const astGrepToolRenderer = {
 		if (limitReached) meta.push(uiTheme.fg("warning", "limit reached"));
 		const description = args?.pat;
 		const header = renderStatusLine(
-			{ icon: limitReached ? "warning" : "success", title: "AST Grep", description, meta },
+			{
+				...(limitReached
+					? { icon: "warning" as const }
+					: { iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")) }),
+				title: "AST Grep",
+				description,
+				meta,
+			},
 			uiTheme,
 		);
 
diff --git a/packages/coding-agent/src/tools/find.ts b/packages/coding-agent/src/tools/find.ts
index 4fd0583f9..26b6cb50c 100644
--- a/packages/coding-agent/src/tools/find.ts
+++ b/packages/coding-agent/src/tools/find.ts
@@ -470,7 +470,7 @@ export const findToolRenderer = {
 			const lines = textContent.split("\n").filter(l => l.trim());
 			const header = renderStatusLine(
 				{
-					icon: "success",
+					iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")),
 					title: "Find",
 					description: formatFindRenderPaths(args?.paths),
 					meta: [formatCount("file", lines.length)],
@@ -519,7 +519,9 @@ export const findToolRenderer = {
 		if (truncated) meta.push(uiTheme.fg("warning", "truncated"));
 		const header = renderStatusLine(
 			{
-				icon: truncated ? "warning" : "success",
+				...(truncated
+					? { icon: "warning" as const }
+					: { iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")) }),
 				title: "Find",
 				description: formatFindRenderPaths(args?.paths),
 				meta,
diff --git a/packages/coding-agent/src/tools/search-tool-bm25.ts b/packages/coding-agent/src/tools/search-tool-bm25.ts
index f16c6fab8..45d942eaf 100644
--- a/packages/coding-agent/src/tools/search-tool-bm25.ts
+++ b/packages/coding-agent/src/tools/search-tool-bm25.ts
@@ -16,9 +16,9 @@ import {
 	searchDiscoverableTools,
 	summarizeDiscoverableTools,
 } from "../tool-discovery/tool-index";
-import { renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
+import { framedBlock, renderStatusLine, truncateToWidth } from "../tui";
 import type { ToolSession } from ".";
-import { formatCount, replaceTabs, TRUNCATE_LENGTHS } from "./render-utils";
+import { formatCount, formatExpandHint, formatMoreItems, replaceTabs, TRUNCATE_LENGTHS } from "./render-utils";
 import { ToolError } from "./tool-errors";
 
 const DEFAULT_LIMIT = 8;
@@ -171,6 +171,25 @@ function renderMatchLines(match: SearchToolBm25Match, theme: Theme): string[] {
 	return lines;
 }
 
+function renderMatchBullets(tools: SearchToolBm25Match[], expanded: boolean, theme: Theme): string[] {
+	const shown = expanded ? tools.length : Math.min(tools.length, COLLAPSED_MATCH_LIMIT);
+	const bullet = theme.fg("dim", theme.format.bullet);
+	const lines: string[] = [];
+	for (let i = 0; i < shown; i++) {
+		const itemLines = renderMatchLines(tools[i]!, theme);
+		lines.push(`${bullet} ${itemLines[0]}`);
+		for (let j = 1; j < itemLines.length; j++) {
+			lines.push(`  ${itemLines[j]}`);
+		}
+	}
+	const remaining = tools.length - shown;
+	if (remaining > 0) {
+		const hint = formatExpandHint(theme, expanded, true);
+		lines.push(`${theme.fg("muted", formatMoreItems(remaining, "tool"))}${hint ? ` ${hint}` : ""}`);
+	}
+	return lines;
+}
+
 function renderFallbackResult(text: string, theme: Theme): Component {
 	const header = renderStatusLine({ icon: "warning", title: TOOL_DISCOVERY_TITLE }, theme);
 	const bodyLines = (text || "Tool discovery completed")
@@ -271,14 +290,11 @@ export const searchToolBm25Renderer = {
 	renderCall(args: SearchToolBm25Params, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const query = typeof args.query === "string" ? replaceTabs(args.query.trim()) : "";
 		const meta = args.limit ? [`limit:${args.limit}`] : [];
-		return new Text(
-			renderStatusLine(
-				{ icon: "pending", title: TOOL_DISCOVERY_TITLE, description: query || "(empty query)", meta },
-				uiTheme,
-			),
-			0,
-			0,
+		const header = renderStatusLine(
+			{ icon: "pending", title: TOOL_DISCOVERY_TITLE, description: query || "(empty query)", meta },
+			uiTheme,
 		);
+		return new Text(header, 0, 0);
 	},
 
 	renderResult(
@@ -305,7 +321,9 @@ export const searchToolBm25Renderer = {
 		const safeQuery = replaceTabs(details.query);
 		const header = renderStatusLine(
 			{
-				icon: details.tools.length > 0 ? "success" : "warning",
+				...(details.tools.length > 0
+					? { iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")) }
+					: { icon: "warning" as const }),
 				title: TOOL_DISCOVERY_TITLE,
 				description: truncateToWidth(safeQuery, MATCH_LABEL_LEN),
 				meta,
@@ -318,19 +336,14 @@ export const searchToolBm25Renderer = {
 			return new Text(`${header}\n${uiTheme.fg("muted", emptyMessage)}`, 0, 0);
 		}
 
-		const lines = [header];
-		const treeLines = renderTreeList(
-			{
-				items: details.tools,
-				expanded: options.expanded,
-				maxCollapsed: COLLAPSED_MATCH_LIMIT,
-				itemType: "tool",
-				renderItem: match => renderMatchLines(match, uiTheme),
-			},
-			uiTheme,
-		);
-		lines.push(...treeLines);
-		return new Text(lines.join("\n"), 0, 0);
+		return framedBlock(uiTheme, width => ({
+			header,
+			sections: [{ lines: renderMatchBullets(details.tools, options.expanded ?? false, uiTheme) }],
+			state: "success",
+			borderColor: "borderMuted",
+			applyBg: false,
+			width,
+		}));
 	},
 
 	mergeCallAndResult: true,
diff --git a/packages/coding-agent/src/tools/search.ts b/packages/coding-agent/src/tools/search.ts
index 0c3a76ff2..56d99ada8 100644
--- a/packages/coding-agent/src/tools/search.ts
+++ b/packages/coding-agent/src/tools/search.ts
@@ -1365,7 +1365,12 @@ export const searchToolRenderer = {
 			const lines = textContent.split("\n").filter(line => line.trim() !== "");
 			const description = args?.pattern ?? undefined;
 			const header = renderStatusLine(
-				{ icon: "success", title: "Search", description, meta: [formatCount("item", lines.length)] },
+				{
+					iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")),
+					title: "Search",
+					description,
+					meta: [formatCount("item", lines.length)],
+				},
 				uiTheme,
 			);
 			return createCachedComponent(
@@ -1419,7 +1424,14 @@ export const searchToolRenderer = {
 		if (truncated) meta.push(uiTheme.fg("warning", "truncated"));
 		const description = args?.pattern ?? undefined;
 		const header = renderStatusLine(
-			{ icon: truncated ? "warning" : "success", title: "Search", description, meta },
+			{
+				...(truncated
+					? { icon: "warning" as const }
+					: { iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")) }),
+				title: "Search",
+				description,
+				meta,
+			},
 			uiTheme,
 		);
 
diff --git a/packages/coding-agent/test/tools/search-renderer.test.ts b/packages/coding-agent/test/tools/search-renderer.test.ts
index 38d04c0ec..13f1c7f32 100644
--- a/packages/coding-agent/test/tools/search-renderer.test.ts
+++ b/packages/coding-agent/test/tools/search-renderer.test.ts
@@ -52,7 +52,7 @@ describe("searchToolRenderer", () => {
 			},
 		);
 		const renderedLines = sanitizeText(collapsed.render(200).join("\n")).split("\n");
-		const bodyLines = renderedLines.slice(1, -1);
+		const bodyLines = renderedLines.slice(1);
 
 		expect(renderedLines[0]).toContain("truncated");
 		expect(bodyLines).toHaveLength(6);
@@ -93,7 +93,7 @@ describe("searchToolRenderer", () => {
 			{ pattern: "Flag" },
 		);
 		const renderedLines = sanitizeText(collapsed.render(240).join("\n")).split("\n");
-		const bodyLines = renderedLines.slice(1, -1);
+		const bodyLines = renderedLines.slice(1);
 
 		expect(bodyLines).toHaveLength(6);
 		expect(bodyLines.some(line => line.includes("const firstFlag = true;"))).toBe(true);

From 8c62c77e00ebc8b8f1c455f5b5901ffdbe876c07 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:13:58 +0200
Subject: [PATCH 096/181] refactor(packages/coding-agent): restructured tool
 and execution rendering

- Unified edit, ask, ast-edit, todo, write, and inspect outputs using framedBlock.
- Wrapped failure and warning cases in framed blocks with clearer status states.
- Standardized frame body rendering by trimming blank lines and clipping content width.
- Simplified tool execution layout by removing dynamic padding and background helpers.
---
 packages/coding-agent/CHANGELOG.md            |   7 +-
 packages/coding-agent/src/edit/renderer.ts    | 135 ++++----
 .../coding-agent/src/goals/tools/goal-tool.ts |  62 ++--
 .../src/modes/components/tool-execution.ts    |  87 ++----
 packages/coding-agent/src/tools/ask.ts        | 289 ++++++++----------
 packages/coding-agent/src/tools/ast-edit.ts   | 107 +++++--
 .../coding-agent/src/tools/gh-renderer.ts     | 121 +++++---
 .../src/tools/inspect-image-renderer.ts       | 108 ++++---
 packages/coding-agent/src/tools/job.ts        |   7 +-
 .../coding-agent/src/tools/memory-render.ts   |   5 +-
 packages/coding-agent/src/tools/todo.ts       | 111 +++----
 packages/coding-agent/src/tools/write.ts      | 115 +++----
 12 files changed, 592 insertions(+), 562 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index b6cb7ca6e..406659da4 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 - Added `/fresh` to rotate the provider-facing session id and clear in-memory provider stream/cache state without changing the local session file.
 - Added a `ChatBlock` transcript primitive (`modes/components/chat-block.ts`) and a single `ctx.present(...)` sink (with `ctx.resetTranscript()`) so chat output is mounted in one place instead of the repeated `chatContainer.addChild(...)` + `ui.requestRender()` pattern scattered across controllers. `ChatBlock` carries a React/Svelte-style lifecycle — `onMount` starts effects, `onCleanup` registers teardown, `finish()` self-completes (stops timers and freezes the block at its final content), and `dispose()`/`resetTranscript()` tears everything down — so animated blocks own their own resources instead of leaking `setInterval`/`requestRender` bookkeeping into callers. The MCP "Connecting…" spinner is now such a block.
+- Added a `framedBlock` output-block helper (`tui/output-block.ts`) plus a `borderColor` override and `applyBg: false` (no background fill) on output blocks, a `renderStatusLine` `iconOverride`, and an `icon.search` (magnifier) theme symbol — so tool renderers can draw self-contained muted-outline frames and search-family tools can show a magnifier instead of a checkmark.
 
 ### Changed
 
@@ -13,8 +14,10 @@
 - Changed image generation to wrap every provider fetch branch in `withAuth`, so 401 / usage-limit errors trigger credential force-refresh and rotation for authStorage-backed providers (OpenAI-hosted, antigravity, xai-oauth) while env-only providers (openrouter, gemini) stay single-attempt
 - Changed web-search providers using `authStorage.getApiKey` (anthropic, exa, tavily, parallel, synthetic, zai, kimi) to wrap HTTP calls in `withAuth` for automatic credential rotation on 401 / usage-limit errors
 - Changed the directory grouping for `find`, `search`, `ast_grep`, `ast_edit`, and `lsp` diagnostics from a single flat `# dir/` heading per immediate directory to a multi-level tree that folds the common path prefix into one heading. Previously every group repeated the full directory path — so results rooted outside cwd printed the absolute prefix (e.g. `/Users/me/proj/`) on every heading and nested directories were never collapsed. Now a single-child directory chain folds into one heading (`# packages/pkg/src/`, including an absolute root for out-of-cwd results), subdirectories nest one `#` deeper (`## nested/` → `### child.ts`), and each directory's own files are listed before its subdirectories. TUI hyperlink reconstruction tracks the nested directory stack across the whole output so file and code-frame links keep resolving to the correct absolute paths.
-- Changed the plan-mode approval surface from an inline transcript block plus a separate bottom selector into a single fullscreen overlay (like `/copy`) and overhauled its navigation. The overlay now renders the plan per-section through `ScrollView` (line-level ↑/↓ scroll, Shift+↑/↓ to scroll faster, PgUp/PgDn, g/G) with no stray per-line `…`, and — when the terminal is wide enough and the plan has ≥2 headings — shows a compact VS Code-style Contents sidebar (the redundant plan-title heading is omitted). Focus moves between regions with Tab/Shift+Tab (and flows at the edges: Down past the last section or the bottom of the body drops into the approval options; Up steps back), while the sidebar glows to track the scrolled section. The sidebar can fast-jump between sections, delete a section (with `u` undo), and annotate sections with feedback (`a`) that is submitted back to the model when the operator picks "Refine plan"; ←/→ always drive the model-tier slider, Enter confirms, the external-editor key opens the plan, and Esc cancels. The overlay borrows the terminal's alternate screen buffer for its lifetime (`fullscreen` overlay), so the transcript stays put on the normal screen instead of bleeding through scrollback behind the modal.
+- Changed the plan-mode approval surface from an inline transcript block plus a separate bottom selector into a single fullscreen overlay (like `/copy`) and overhauled its navigation. The overlay now renders the plan per-section through `ScrollView` (line-level ↑/↓ scroll, Shift+↑/↓ to scroll faster, PgUp/PgDn, g/G) with no stray per-line `…`, and — when the terminal is wide enough and the plan has ≥2 headings — shows a compact VS Code-style section sidebar (the redundant plan-title heading and any "Contents" label are omitted). Focus moves between regions with Tab/Shift+Tab (and flows at the edges: Down past the last section or the bottom of the body drops into the approval options; Up steps back), while the sidebar glows to track the scrolled section. The sidebar can fast-jump between sections, delete a section (with `u` undo), and annotate sections with feedback (`a`); deletions and annotations are collected into refinement feedback that is submitted back to the model when the operator picks "Refine plan". Mouse works too: clicking an approval option activates it, clicking a sidebar section jumps to it, and the wheel scrolls the plan. ←/→ always drive the model-tier slider, Enter confirms, the external-editor key opens the plan, and Esc cancels. The overlay borrows the terminal's alternate screen buffer for its lifetime (`fullscreen` overlay), so the transcript stays put on the normal screen instead of bleeding through scrollback behind the modal.
 - Changed the interactive controllers (command, MCP, selector, extension-UI, event), debug panels, and the status/error/warning helpers to render chat output through `ctx.present(...)` instead of appending to `chatContainer` and calling `ui.requestRender()` directly; transcript rebuilds dispose live blocks via `ctx.resetTranscript()` so animated blocks' timers stop on reset.
+- Changed tool-execution block rendering so the container (`ToolExecutionComponent`) is a transparent passthrough — it no longer inserts a top/bottom blank line, adds left/right padding, or paints a state-colored background behind tool output. Tools with substantial body now self-frame with a muted outline and the tool title in the frame's top bar (`edit`/`apply_patch`, `write`, `ask`, `todo`, `github`, `goal`, `inspect_image`, `search_tool_bm25`, `task`), matching the already-framed `bash`/`read`/`eval`/`debug`/`web_search`/`lsp` blocks, while streaming/in-progress and trivial results collapse to a clean status line. The search-family list tools (`find`, `search`, `ast_grep`) and `job` render frameless/minimal; `find`/`search`/`ast_grep` show a magnifier on success instead of a checkmark, and `job` drops its `Job:` label prefix (the per-job rows are self-describing). The `search_tool_bm25`, `github`, and `inspect_image` frames draw with no background fill, and `inspect_image`'s label was shortened to `Inspect`.
+- Changed the plan-mode active prompt (`prompts/system/plan-mode-active.md`) to make plans decision-complete and cut filler. Added an Objective framing ("another engineer can execute end-to-end without making a single design decision"), a shared "Resolving Unknowns" section (explore discoverable facts before asking; reserve `ask` for non-derivable preferences/tradeoffs with 2–4 options + a recommended default), and a single shared "The Plan" structure (Context / Approach grouped by behavior not file-by-file / ≤5 Critical files / Verification / Assumptions) that replaces the per-branch structure guidance previously duplicated across the iterative and parallel workflows. Added explicit prohibitions on sections that decide nothing (Non-Goals, Out of Scope, Alternatives Considered, Risks/Mitigations boilerplate, Future Work), on enumerating every file/line, and on inventing schema/validation/precedence policy the request never established.
 
 ### Fixed
 
@@ -27,6 +30,8 @@
 - Fixed inconsistent vertical spacing between transcript blocks: some blocks (tool results from `search`/`find` and other renderer-backed tools) rendered with a doubled gap (a leading `Spacer` plus the content box's own `paddingY`), while others (the grouped `read` card, file-mention lists, IRC cards) rendered with no gap at all. Vertical spacing is now owned entirely by the chat renderer: `TranscriptContainer` strips each block's plain-blank top/bottom edges and inserts exactly one blank line between consecutive blocks, so every block is separated by a single consistent gap regardless of which component produced it. Individual components (assistant/user/tool/read-group/bash/eval/skill/custom/hook/compaction/branch/todo-reminder/plan-review messages) no longer emit their own leading `Spacer`/`paddingY` for separation, and multi-row groups (IRC cards, file-mention lists, completed-job batches, and the bordered command/`/changelog`/`/context`/version/OAuth/debug panels) are wrapped as single `TranscriptBlock` children so the renderer spaces them as one unit. Background-colored box padding is preserved as block-internal design.
 - Fixed `resolve` with `action: "discard"` surfacing a hard `isError` "No pending action to resolve" failure to the model when the agent asked to cancel a staged action (e.g. an `ast_edit` preview) but nothing was pending. A discard is a request to reach the "no staged change" end-state, which already holds in that case, so it is now honored as a successful cancellation (`"Nothing to discard; no pending action remains."` with `details.action: "discard"`) instead of an error. `action: "apply"` with no pending action still errors.
 - Fixed the collapsed tool-output expand hint rendering double brackets (e.g. `((Ctrl+O for more))`) — the `EXPAND_HINT` text already carried its own parentheses and then `formatExpandHint` wrapped it again with the theme's bracket glyphs. The hint now resolves the key actually bound to `app.tools.expand` at render time and reads `⟨<key>: Expand⟩` (e.g. `⟨Ctrl+O: Expand⟩`), so a single bracket pair surrounds it and a user remap of the expand keybinding is reflected instead of a hard-coded `Ctrl+O`.
+- Fixed the `edit`/`apply_patch` tool dropping its outlined frame while streaming/in-progress (only the final result was framed); the in-progress diff preview now renders inside the same muted frame as the completed result.
+- Fixed the `todo` and `job` tools rendering a success icon and success styling on a failed/error result; error results now show the error icon and a red frame border.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/coding-agent/src/edit/renderer.ts b/packages/coding-agent/src/edit/renderer.ts
index 4a51f9740..6f880249a 100644
--- a/packages/coding-agent/src/edit/renderer.ts
+++ b/packages/coding-agent/src/edit/renderer.ts
@@ -4,7 +4,7 @@
 
 import { HL_FILE_PREFIX, HL_FILE_SUFFIX } from "@oh-my-pi/hashline";
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Text, visibleWidth, wrapTextWithAnsi } from "@oh-my-pi/pi-tui";
+import { visibleWidth, wrapTextWithAnsi } from "@oh-my-pi/pi-tui";
 import { sanitizeText } from "@oh-my-pi/pi-utils";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { FileDiagnosticsResult } from "../lsp";
@@ -16,7 +16,6 @@ import {
 	formatDiffStats,
 	formatExpandHint,
 	formatStatusIcon,
-	formatTitle,
 	getDiffStats,
 	getLspBatchRequest,
 	type LspBatchRequest,
@@ -25,7 +24,7 @@ import {
 	shortenPath,
 	truncateDiffByHunk,
 } from "../tools/render-utils";
-import { fileHyperlink, Hasher, type RenderCache, renderStatusLine, truncateToWidth } from "../tui";
+import { fileHyperlink, framedBlock, Hasher, type RenderCache, renderStatusLine, truncateToWidth } from "../tui";
 import type { EditMode } from "../utils/edit-mode";
 import type { DiffError, DiffResult } from "./diff";
 import { type ApplyPatchEntry, expandApplyPatchToEntries, expandApplyPatchToPreviewEntries } from "./modes/apply-patch";
@@ -459,23 +458,30 @@ export const editToolRenderer = {
 		const rename = editArgs.rename || firstEdit?.rename || firstEdit?.move || firstApplyPatchEntry?.rename;
 		const op = editArgs.op || firstEdit?.op || firstApplyPatchEntry?.op;
 		const { description } = formatEditDescription(rawPath, uiTheme, { rename });
-		const spinner =
-			options?.spinnerFrame !== undefined ? formatStatusIcon("running", uiTheme, options.spinnerFrame) : "";
-		let text = `${formatTitle(getOperationTitle(op), uiTheme)} ${spinner ? `${spinner} ` : ""}${description}`;
-		// Show file count hint for multi-file edits
 		let fileCount = hashlineInputSummary?.entries.length ?? applyPatchSummary?.entries.length ?? 0;
 		if (Array.isArray(editArgs.edits)) {
 			fileCount = countEditFiles(editArgs.edits);
 		}
-		if (fileCount > 1) {
-			text += uiTheme.fg("dim", ` (+${fileCount - 1} more)`);
-		}
-		text += getCallPreview(editArgs, rawPath, uiTheme, renderContext, options.expanded);
-		if (applyPatchSummary?.error) {
-			text += `\n\n${uiTheme.fg("error", truncateToWidth(replaceTabs(applyPatchSummary.error, rawPath), CALL_TEXT_PREVIEW_WIDTH))}`;
-		}
-
-		return new Text(text, 0, 0);
+		return framedBlock(uiTheme, width => {
+			let header = renderStatusLine(
+				{ icon: "pending", spinnerFrame: options?.spinnerFrame, title: getOperationTitle(op), description },
+				uiTheme,
+			);
+			if (fileCount > 1) header += uiTheme.fg("dim", ` (+${fileCount - 1} more)`);
+			let body = getCallPreview(editArgs, rawPath, uiTheme, renderContext, options.expanded);
+			if (applyPatchSummary?.error) {
+				body += `\n${uiTheme.fg("error", truncateToWidth(replaceTabs(applyPatchSummary.error, rawPath), Math.max(1, width - 3)))}`;
+			}
+			const bodyLines = body ? body.split("\n") : [];
+			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
+			return {
+				header,
+				sections: bodyLines.length > 0 ? [{ lines: bodyLines }] : [],
+				state: applyPatchSummary?.error ? "error" : "pending",
+				borderColor: applyPatchSummary?.error ? "error" : "borderMuted",
+				width,
+			};
+		});
 	},
 
 	renderResult(
@@ -525,65 +531,54 @@ function renderSingleFileResult(
 			(result.content?.find(c => c.type === "text")?.text ?? "")
 		: "";
 
-	let cached: RenderCache | undefined;
+	return framedBlock(uiTheme, width => {
+		const { expanded, renderContext } = options;
+		const editDiffPreview = renderContext?.editDiffPreview;
+		const renderDiffFn = renderContext?.renderDiff ?? ((t: string) => t);
 
-	return {
-		render(width) {
-			const { expanded, renderContext } = options;
-			const editDiffPreview = renderContext?.editDiffPreview;
-			const renderDiffFn = renderContext?.renderDiff ?? ((t: string) => t);
-			const key = new Hasher().bool(expanded).u32(width).digest();
-			if (cached?.key === key) return cached.lines;
+		const firstChangedLine =
+			(editDiffPreview && "firstChangedLine" in editDiffPreview ? editDiffPreview.firstChangedLine : undefined) ||
+			(details && !isError ? details.firstChangedLine : undefined);
+		const { description } = formatEditDescription(rawPath, uiTheme, { rename, firstChangedLine });
 
-			const firstChangedLine =
-				(editDiffPreview && "firstChangedLine" in editDiffPreview ? editDiffPreview.firstChangedLine : undefined) ||
-				(details && !isError ? details.firstChangedLine : undefined);
-			const { description } = formatEditDescription(rawPath, uiTheme, { rename, firstChangedLine });
+		// Change stats ride inline on the header bar next to the path.
+		const previewDiff = editDiffPreview && !("error" in editDiffPreview) ? editDiffPreview.diff : undefined;
+		const headerDiff = isError ? undefined : details?.diff || previewDiff;
+		const statsSuffix = headerDiff ? formatDiffStatsSuffix(headerDiff, uiTheme) : "";
+		const header =
+			renderStatusLine({ icon: isError ? "error" : "success", title: getOperationTitle(op), description }, uiTheme) +
+			statsSuffix;
 
-			// Change stats ride inline on the header next to the path rather than a separate row.
-			const previewDiff = editDiffPreview && !("error" in editDiffPreview) ? editDiffPreview.diff : undefined;
-			const headerDiff = isError ? undefined : details?.diff || previewDiff;
-			const statsSuffix = headerDiff ? formatDiffStatsSuffix(headerDiff, uiTheme) : "";
-
-			const header = renderStatusLine(
-				{
-					icon: isError ? "error" : "success",
-					title: getOperationTitle(op),
-					description,
-				},
-				uiTheme,
+		let body = "";
+		if (isError) {
+			if (errorText) body = uiTheme.fg("error", replaceTabs(errorText, rawPath));
+		} else if (details?.diff) {
+			body = renderDiffSection(details.diff, rawPath, expanded, uiTheme, renderDiffFn);
+		} else if (editDiffPreview) {
+			if ("error" in editDiffPreview) body = uiTheme.fg("error", replaceTabs(editDiffPreview.error, rawPath));
+			else if (editDiffPreview.diff)
+				body = renderDiffSection(editDiffPreview.diff, rawPath, expanded, uiTheme, renderDiffFn);
+		}
+		if (details?.diagnostics) {
+			body += formatDiagnostics(details.diagnostics, expanded, uiTheme, (fp: string) =>
+				uiTheme.getLangIcon(getLanguageFromPath(fp)),
 			);
-			let text = header + statsSuffix;
+		}
 
-			if (isError) {
-				if (errorText) {
-					text += `\n\n${uiTheme.fg("error", replaceTabs(errorText, rawPath))}`;
-				}
-			} else if (details?.diff) {
-				text += renderDiffSection(details.diff, rawPath, expanded, uiTheme, renderDiffFn);
-			} else if (editDiffPreview) {
-				if ("error" in editDiffPreview) {
-					text += `\n\n${uiTheme.fg("error", replaceTabs(editDiffPreview.error, rawPath))}`;
-				} else if (editDiffPreview.diff) {
-					text += renderDiffSection(editDiffPreview.diff, rawPath, expanded, uiTheme, renderDiffFn);
-				}
-			}
+		// Diff lines self-wrap with a continuation gutter; pre-wrap to the frame's
+		// inner width so renderOutputBlock's generic wrap is a no-op.
+		const innerWidth = Math.max(1, width - 3);
+		const bodyLines = body.length > 0 ? body.split("\n").flatMap(line => wrapEditRendererLine(line, innerWidth)) : [];
+		while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
 
-			if (details?.diagnostics) {
-				text += formatDiagnostics(details.diagnostics, expanded, uiTheme, (fp: string) =>
-					uiTheme.getLangIcon(getLanguageFromPath(fp)),
-				);
-			}
-
-			const lines =
-				width > 0 ? text.split("\n").flatMap(line => wrapEditRendererLine(line, width)) : text.split("\n");
-			cached = { key, lines };
-			return lines;
-		},
-		invalidate() {
-			cached = undefined;
-		},
-	};
+		return {
+			header,
+			sections: bodyLines.length > 0 ? [{ lines: bodyLines }] : [],
+			state: isError ? "error" : options.isPartial ? "pending" : "success",
+			borderColor: isError ? "error" : "borderMuted",
+			width,
+		};
+	});
 }
 
 function renderMultiFileResult(
@@ -638,7 +633,7 @@ function renderMultiFileResult(
 		},
 		invalidate() {
 			cached = undefined;
-			for (const c of fileComponents) c.invalidate();
+			for (const c of fileComponents) c.invalidate?.();
 		},
 	};
 }
diff --git a/packages/coding-agent/src/goals/tools/goal-tool.ts b/packages/coding-agent/src/goals/tools/goal-tool.ts
index 539597945..94b9545bf 100644
--- a/packages/coding-agent/src/goals/tools/goal-tool.ts
+++ b/packages/coding-agent/src/goals/tools/goal-tool.ts
@@ -10,7 +10,7 @@ import { formatDuration } from "../../slash-commands/helpers/format";
 import type { ToolSession } from "../../tools";
 import { formatErrorDetail, TRUNCATE_LENGTHS } from "../../tools/render-utils";
 import { ToolError } from "../../tools/tool-errors";
-import { renderStatusLine, truncateToWidth } from "../../tui";
+import { framedBlock, renderStatusLine, truncateToWidth } from "../../tui";
 import { completionBudgetReport, remainingTokens } from "../runtime";
 import type { Goal, GoalStatus, GoalToolDetails } from "../state";
 
@@ -173,8 +173,7 @@ export const goalToolRenderer = {
 		if (args.op === "create" && args.token_budget !== undefined) {
 			meta.push(`budget ${formatNumber(args.token_budget)}`);
 		}
-		const text = renderStatusLine({ icon: "pending", title: "Goal", description, meta }, uiTheme);
-		return new Text(text, 0, 0);
+		return new Text(renderStatusLine({ icon: "pending", title: "Goal", description, meta }, uiTheme), 0, 0);
 	},
 
 	renderResult(
@@ -190,51 +189,62 @@ export const goalToolRenderer = {
 
 		if (result.isError) {
 			const header = renderStatusLine({ icon: "error", title: "Goal", description }, uiTheme);
-			const body = formatErrorDetail(fallbackText || "Goal tool failed", uiTheme);
-			return new Text([header, body].join("\n"), 0, 0);
+			return framedBlock(uiTheme, width => ({
+				header,
+				sections: [{ lines: formatErrorDetail(fallbackText || "Goal tool failed", uiTheme).split("\n") }],
+				state: "error",
+				borderColor: "error",
+				width,
+			}));
 		}
 
 		const goal = details?.goal ?? null;
 		if (!goal) {
-			const header = renderStatusLine({ icon: "warning", title: "Goal", description }, uiTheme);
-			const body = uiTheme.fg("muted", "No active goal.");
-			return new Text([header, body].join("\n"), 0, 0);
+			return new Text(
+				renderStatusLine({ icon: "warning", title: "Goal", description, meta: ["no active goal"] }, uiTheme),
+				0,
+				0,
+			);
 		}
 
-		const lines: string[] = [];
-		lines.push(
-			renderStatusLine(
-				{
-					icon: "success",
-					title: "Goal",
-					description,
-					badge: { label: goal.status, color: goalBadgeColor(goal.status) },
-				},
-				uiTheme,
-			),
+		const header = renderStatusLine(
+			{
+				icon: "success",
+				title: "Goal",
+				description,
+				badge: { label: goal.status, color: goalBadgeColor(goal.status) },
+			},
+			uiTheme,
 		);
 
+		const lines: string[] = [];
 		const objectiveText = truncateToWidth(goal.objective.trim(), TRUNCATE_LENGTHS.LONG);
-		lines.push(`  ${uiTheme.italic(uiTheme.fg("muted", `"${objectiveText}"`))}`);
+		lines.push(uiTheme.italic(uiTheme.fg("muted", `"${objectiveText}"`)));
 
 		const used = formatNumber(goal.tokensUsed);
 		const tokensLine =
 			goal.tokenBudget !== undefined
 				? `${used} / ${formatNumber(goal.tokenBudget)} tokens (${formatNumber(Math.max(0, goal.tokenBudget - goal.tokensUsed))} left)`
 				: `${used} tokens`;
-		lines.push(`  ${uiTheme.fg("dim", tokensLine)}`);
-
+		const metaParts = [tokensLine];
 		if (goal.timeUsedSeconds > 0) {
-			lines.push(`  ${uiTheme.fg("dim", `${formatDuration(goal.timeUsedSeconds * 1000)} elapsed`)}`);
+			metaParts.push(`${formatDuration(goal.timeUsedSeconds * 1000)} elapsed`);
 		}
+		lines.push(uiTheme.fg("dim", metaParts.join(" · ")));
 
 		const report = details?.completionBudgetReport;
+		const sections: Array<{ label?: string; lines: string[] }> = [{ lines }];
 		if (report) {
-			lines.push("");
-			lines.push(uiTheme.italic(uiTheme.fg("muted", report)));
+			sections.push({ label: "Report", lines: report.split("\n").map(line => uiTheme.fg("muted", line)) });
 		}
 
-		return new Text(lines.join("\n"), 0, 0);
+		return framedBlock(uiTheme, width => ({
+			header,
+			sections,
+			state: "success",
+			borderColor: "borderMuted",
+			width,
+		}));
 	},
 
 	mergeCallAndResult: true,
diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index 3365526ef..dae47fe2c 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -33,30 +33,10 @@ import {
 import { formatExpandHint, replaceTabs, resolveImageOptions, truncateToWidth } from "../../tools/render-utils";
 import { type ToolRenderer, toolRenderers } from "../../tools/renderers";
 import { TODO_STRIKE_TOTAL_FRAMES } from "../../tools/todo";
-import { isFramedBlockComponent, renderStatusLine } from "../../tui";
+import { renderStatusLine } from "../../tui";
 import { sanitizeWithOptionalSixelPassthrough } from "../../utils/sixel";
 import { renderDiff } from "./diff";
 
-function ensureInvalidate(component: unknown): Component {
-	const c = component as { render: Component["render"]; invalidate?: () => void };
-	if (!c.invalidate) {
-		c.invalidate = () => {};
-	}
-	return c as Component;
-}
-
-function addBoxChild(box: Box, component: unknown): boolean {
-	const child = ensureInvalidate(component);
-	box.addChild(child);
-	return isFramedBlockComponent(child);
-}
-
-function setBoxPaddingForFramedBlock(box: Box, hasFramedBlock: boolean): void {
-	const padding = hasFramedBlock ? 0 : 1;
-	box.setPaddingX(padding);
-	box.setPaddingY(padding);
-}
-
 /**
  * Drop trailing removal/hunk-header lines that appear in a streaming diff
  * before the matching `+added` lines have arrived. Without this, a partial
@@ -247,8 +227,8 @@ export class ToolExecutionComponent extends Container {
 
 		// Always create both - contentBox for custom tools/bash/tools with renderers, contentText for other built-ins.
 		// paddingY is 0: the transcript owns inter-block spacing (see TranscriptContainer).
-		this.#contentBox = new Box(1, 0, (text: string) => theme.bg("toolPendingBg", text));
-		this.#contentText = new Text("", 1, 0, (text: string) => theme.bg("toolPendingBg", text));
+		this.#contentBox = new Box(0, 0);
+		this.#contentText = new Text("", 1, 0);
 
 		// Use Box for custom tools or built-in tools that have renderers
 		const hasRenderer = toolName in toolRenderers;
@@ -606,13 +586,6 @@ export class ToolExecutionComponent extends Container {
 	}
 
 	#updateDisplay(): void {
-		// Set background based on state
-		const bgFn = this.#isPartial
-			? (text: string) => theme.bg("toolPendingBg", text)
-			: this.#result?.isError
-				? (text: string) => theme.bg("toolErrorBg", text)
-				: (text: string) => theme.bg("toolSuccessBg", text);
-
 		// Sync shared mutable render state for component closures
 		this.#renderState.expanded = this.#expanded;
 		this.#renderState.isPartial = this.#isPartial;
@@ -623,10 +596,8 @@ export class ToolExecutionComponent extends Container {
 			const tool = this.#tool;
 			const mergeCallAndResult = Boolean((tool as { mergeCallAndResult?: boolean }).mergeCallAndResult);
 			// Custom tools use Box for flexible component rendering
-			const inline = Boolean((tool as { inline?: boolean }).inline);
-			this.#contentBox.setBgFn(inline ? undefined : bgFn);
+			this.#contentBox.setBgFn(undefined);
 			this.#contentBox.clear();
-			let contentBoxHasFramedBlock = false;
 			// Mirror the built-in renderer branch so custom renderers (notably the
 			// task tool, whose live instance routes through here) receive the same
 			// render context — e.g. the `hasResult` flag that suppresses the task
@@ -642,18 +613,15 @@ export class ToolExecutionComponent extends Container {
 				if (tool.renderCall) {
 					try {
 						const callComponent = tool.renderCall(this.#getCallArgsForRender(), this.#renderState, theme);
-						if (callComponent) {
-							contentBoxHasFramedBlock =
-								addBoxChild(this.#contentBox, callComponent) || contentBoxHasFramedBlock;
-						}
+						if (callComponent) this.#contentBox.addChild(callComponent as Component);
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 						// Fall back to default on error
-						addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
+						this.#contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 					}
 				} else {
 					// No custom renderCall, show tool name
-					addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
+					this.#contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 				}
 			}
 
@@ -676,25 +644,22 @@ export class ToolExecutionComponent extends Container {
 						theme,
 						this.#args,
 					);
-					if (resultComponent) {
-						contentBoxHasFramedBlock = addBoxChild(this.#contentBox, resultComponent) || contentBoxHasFramedBlock;
-					}
+					if (resultComponent) this.#contentBox.addChild(resultComponent);
 				} catch (err) {
 					logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 					// Fall back to showing raw output on error
 					const output = this.#getTextOutput();
 					if (output) {
-						addBoxChild(this.#contentBox, new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
+						this.#contentBox.addChild(new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
 					}
 				}
 			} else if (this.#result) {
 				// Has result but no custom renderResult
 				const output = this.#getTextOutput();
 				if (output) {
-					addBoxChild(this.#contentBox, new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
+					this.#contentBox.addChild(new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
 				}
 			}
-			setBoxPaddingForFramedBlock(this.#contentBox, contentBoxHasFramedBlock);
 		} else if (this.#toolName in toolRenderers) {
 			// Built-in tools with renderers
 			const renderer = toolRenderers[this.#toolName];
@@ -713,7 +678,6 @@ export class ToolExecutionComponent extends Container {
 				// Multi-file: render each file as its own Box (identical to separate tool calls)
 				this.#contentBox.setBgFn(undefined);
 				this.#contentBox.clear();
-				this.#contentBox.setPaddingX(1);
 
 				const renderContext = this.#buildRenderContext();
 				this.#renderState.renderContext = renderContext;
@@ -725,20 +689,14 @@ export class ToolExecutionComponent extends Container {
 						this.#multiFileBoxes.push(spacer);
 						this.addChild(spacer);
 					}
-					const fileBgFn = fileResult.isError
-						? (text: string) => theme.bg("toolErrorBg", text)
-						: (text: string) => theme.bg("toolSuccessBg", text);
-					const fileBox = new Box(1, 1, fileBgFn);
+					const fileBox = new Box(0, 0);
 					try {
 						const resultComponent = renderer.renderResult(
 							{ content: [], details: fileResult, isError: fileResult.isError },
 							this.#renderState,
 							theme,
 						);
-						if (resultComponent) {
-							const fileBoxHasFramedBlock = addBoxChild(fileBox, resultComponent);
-							setBoxPaddingForFramedBlock(fileBox, fileBoxHasFramedBlock);
-						}
+						if (resultComponent) fileBox.addChild(resultComponent);
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 					}
@@ -755,7 +713,7 @@ export class ToolExecutionComponent extends Container {
 					const pendingSpacer = new Spacer(1);
 					this.#multiFileBoxes.push(pendingSpacer);
 					this.addChild(pendingSpacer);
-					const pendingBox = new Box(1, 1, (text: string) => theme.bg("toolPendingBg", text));
+					const pendingBox = new Box(0, 0);
 					const pendingText = renderStatusLine(
 						{
 							icon: "pending",
@@ -771,9 +729,8 @@ export class ToolExecutionComponent extends Container {
 			} else {
 				// Single-file or no result: standard rendering
 				// Inline renderers skip background styling
-				this.#contentBox.setBgFn(renderer.inline ? undefined : bgFn);
+				this.#contentBox.setBgFn(undefined);
 				this.#contentBox.clear();
-				let contentBoxHasFramedBlock = false;
 
 				const renderContext = this.#buildRenderContext();
 				this.#renderState.renderContext = renderContext;
@@ -783,14 +740,11 @@ export class ToolExecutionComponent extends Container {
 					// Render call component
 					try {
 						const callComponent = renderer.renderCall(this.#getCallArgsForRender(), this.#renderState, theme);
-						if (callComponent) {
-							contentBoxHasFramedBlock =
-								addBoxChild(this.#contentBox, callComponent) || contentBoxHasFramedBlock;
-						}
+						if (callComponent) this.#contentBox.addChild(callComponent);
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 						// Fall back to default on error
-						addBoxChild(this.#contentBox, new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
+						this.#contentBox.addChild(new Text(theme.fg("toolTitle", theme.bold(this.#toolLabel)), 0, 0));
 					}
 				}
 
@@ -807,24 +761,19 @@ export class ToolExecutionComponent extends Container {
 							theme,
 							this.#getCallArgsForRender(),
 						);
-						if (resultComponent) {
-							contentBoxHasFramedBlock =
-								addBoxChild(this.#contentBox, resultComponent) || contentBoxHasFramedBlock;
-						}
+						if (resultComponent) this.#contentBox.addChild(resultComponent);
 					} catch (err) {
 						logger.warn("Tool renderer failed", { tool: this.#toolName, error: String(err) });
 						// Fall back to showing raw output on error
 						const output = this.#getTextOutput();
 						if (output) {
-							addBoxChild(this.#contentBox, new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
+							this.#contentBox.addChild(new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
 						}
 					}
 				}
-				setBoxPaddingForFramedBlock(this.#contentBox, contentBoxHasFramedBlock);
 			}
 		} else {
 			// Other built-in tools: use Text directly with caching
-			this.#contentText.setCustomBgFn(bgFn);
 			this.#contentText.setText(this.#formatToolExecution());
 		}
 
diff --git a/packages/coding-agent/src/tools/ask.ts b/packages/coding-agent/src/tools/ask.ts
index edf7371c3..5ff09d52d 100644
--- a/packages/coding-agent/src/tools/ask.ts
+++ b/packages/coding-agent/src/tools/ask.ts
@@ -16,22 +16,14 @@
  */
 
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import {
-	type Component,
-	Container,
-	Markdown,
-	type MarkdownTheme,
-	renderInlineMarkdown,
-	TERMINAL,
-	Text,
-} from "@oh-my-pi/pi-tui";
+import { type Component, Markdown, type MarkdownTheme, renderInlineMarkdown, TERMINAL, Text } from "@oh-my-pi/pi-tui";
 import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { ExtensionUISelectItem } from "../extensibility/extensions";
 import { getMarkdownTheme, type Theme, theme } from "../modes/theme/theme";
 import askDescription from "../prompts/tools/ask.md" with { type: "text" };
-import { renderStatusLine } from "../tui";
+import { framedBlock, renderStatusLine } from "../tui";
 import type { ToolSession } from ".";
 import { formatErrorMessage, formatMeta, formatTitle } from "./render-utils";
 import { ToolAbortError } from "./tool-errors";
@@ -626,23 +618,14 @@ interface AskRenderArgs {
 	}>;
 }
 
-/** Render custom input as a single block with continuation lines (not one entry per line) */
-function renderCustomInput(
-	uiTheme: Theme,
-	prefix: string,
-	customInput: string,
-	isLastEntry: boolean,
-	includeLeadingNewline = true,
-): string {
+/** Render a custom free-text answer as a status line plus indented continuation rows. */
+function renderCustomInputLines(uiTheme: Theme, customInput: string): string[] {
 	const lines = customInput.split("\n");
-	const branch = isLastEntry ? uiTheme.tree.last : uiTheme.tree.branch;
-	const firstLine = lines[0] ?? "";
-	let text = `${includeLeadingNewline ? "\n" : ""}${prefix}${uiTheme.fg("dim", branch)} ${uiTheme.styledSymbol("status.success", "success")} ${uiTheme.fg("toolOutput", firstLine)}`;
-	const continuationIndent = isLastEntry ? "   " : `${uiTheme.fg("dim", uiTheme.tree.vertical)}  `;
-	for (let i = 1; i < lines.length; i++) {
-		text += `\n${prefix}${continuationIndent}   ${uiTheme.fg("toolOutput", lines[i])}`;
-	}
-	return text;
+	const out: string[] = [
+		` ${uiTheme.styledSymbol("status.success", "success")} ${uiTheme.fg("toolOutput", lines[0] ?? "")}`,
+	];
+	for (let i = 1; i < lines.length; i++) out.push(`   ${uiTheme.fg("toolOutput", lines[i])}`);
+	return out;
 }
 
 /**
@@ -654,25 +637,38 @@ function optionMarker(uiTheme: Theme, multi: boolean | undefined, selected: bool
 	return selected ? uiTheme.radio.selected : uiTheme.radio.unselected;
 }
 
-/**
- * Render the answered option list for a question: every offered option with its
- * selection marker filled in, plus any custom free-text answer. This keeps the
- * result visually identical to the question form (`renderCall`) so the answer
- * reads in place rather than as a detached summary block.
- *
- * `linePrefix` is the indent that precedes each entry's tree branch — a single
- * leading space for top-level (single-question) entries, or the question's
- * vertical continuation for nested (multi-question) entries.
- */
-function renderAnswerOptions(
+/** Render the offered options for a question form as flat marker bullets (no tree guides). */
+function renderQuestionOptionLines(
+	uiTheme: Theme,
+	mdTheme: MarkdownTheme,
+	options: AskRenderOption[],
+	multi: boolean | undefined,
+): string[] {
+	const out: string[] = [];
+	for (const opt of options) {
+		const optLabel = renderInlineMarkdown(opt.label, mdTheme, t => uiTheme.fg("muted", t));
+		out.push(` ${uiTheme.fg("dim", optionMarker(uiTheme, multi, false))} ${optLabel}`);
+		if (opt.description?.trim()) {
+			const description = renderInlineMarkdown(opt.description.trim(), mdTheme, t => uiTheme.fg("dim", t));
+			out.push(`   ${uiTheme.fg("dim", "↳")} ${description}`);
+		}
+	}
+	return out;
+}
+
+/**
+ * Render the answered option list for a question: every offered option with its
+ * selection marker filled in, plus any custom free-text answer. Flat marker
+ * bullets — the frame is the container, so no tree guides are drawn.
+ */
+function renderAnswerOptionLines(
 	uiTheme: Theme,
 	mdTheme: MarkdownTheme,
-	linePrefix: string,
 	options: string[] | undefined,
 	selectedOptions: string[] | undefined,
 	multi: boolean | undefined,
 	customInput: string | undefined,
-): string {
+): string[] {
 	const selected = new Set(selectedOptions ?? []);
 	// Prefer the full recorded option set; fall back to the selected labels when
 	// details omit the options array.
@@ -680,26 +676,21 @@ function renderAnswerOptions(
 
 	// Nothing was chosen (and no custom answer) → a lone cancelled marker.
 	if (selected.size === 0 && customInput === undefined) {
-		return `${linePrefix}${uiTheme.fg("dim", uiTheme.tree.last)} ${uiTheme.styledSymbol("status.warning", "warning")} ${uiTheme.fg("warning", "Cancelled")}`;
+		return [` ${uiTheme.styledSymbol("status.warning", "warning")} ${uiTheme.fg("warning", "Cancelled")}`];
 	}
 
-	let text = "";
-	for (let i = 0; i < list.length; i++) {
-		const label = list[i];
+	const out: string[] = [];
+	for (const label of list) {
 		const isSelected = selected.has(label);
-		const isLastEntry = i === list.length - 1 && customInput === undefined;
-		const branch = isLastEntry ? uiTheme.tree.last : uiTheme.tree.branch;
 		const marker = optionMarker(uiTheme, multi, isSelected);
 		const markerStyled = isSelected ? uiTheme.fg("success", marker) : uiTheme.fg("dim", marker);
 		const labelStyled = renderInlineMarkdown(label, mdTheme, t =>
 			isSelected ? uiTheme.fg("toolOutput", t) : uiTheme.fg("muted", t),
 		);
-		text += `${text ? "\n" : ""}${linePrefix}${uiTheme.fg("dim", branch)} ${markerStyled} ${labelStyled}`;
+		out.push(` ${markerStyled} ${labelStyled}`);
 	}
-	if (customInput !== undefined) {
-		text += renderCustomInput(uiTheme, linePrefix, customInput, true, text.length > 0);
-	}
-	return text;
+	if (customInput !== undefined) out.push(...renderCustomInputLines(uiTheme, customInput));
+	return out;
 }
 
 export const askToolRenderer = {
@@ -708,80 +699,58 @@ export const askToolRenderer = {
 		const label = formatTitle("Ask", uiTheme);
 		const mdTheme = getMarkdownTheme();
 		const accentStyle = { color: (t: string) => uiTheme.fg("accent", t) };
+		const md = (text: string, width: number) =>
+			new Markdown(text, 1, 0, mdTheme, accentStyle).render(Math.max(1, width - 3 + 1));
 
-		// Multi-part questions
+		// Multi-part questions: one divider-labelled section per question.
 		if (args.questions && args.questions.length > 0) {
-			const container = new Container();
-			container.addChild(new Text(`${label} ${uiTheme.fg("muted", `${args.questions.length} questions`)}`, 0, 0));
-
-			for (let i = 0; i < args.questions.length; i++) {
-				const q = args.questions[i];
-				const isLastQ = i === args.questions.length - 1;
-				const qBranch = isLastQ ? uiTheme.tree.last : uiTheme.tree.branch;
-				const continuation = isLastQ ? " " : uiTheme.tree.vertical;
-
-				const meta: string[] = [];
-				if (q.multi) meta.push("multi");
-				if (q.options?.length) meta.push(`options:${q.options.length}`);
-				const metaStr = meta.length > 0 ? uiTheme.fg("dim", ` · ${meta.join(" · ")}`) : "";
-
-				container.addChild(
-					new Text(` ${uiTheme.fg("dim", qBranch)} ${uiTheme.fg("dim", `[${q.id}]`)}${metaStr}`, 0, 0),
-				);
-				container.addChild(new Markdown(q.question, 3, 0, mdTheme, accentStyle));
-
-				if (q.options?.length) {
-					let optText = "";
-					for (let j = 0; j < q.options.length; j++) {
-						const opt = q.options[j];
-						const isLastOpt = j === q.options.length - 1;
-						const optBranch = isLastOpt ? uiTheme.tree.last : uiTheme.tree.branch;
-						const optLabel = renderInlineMarkdown(opt.label, mdTheme, t => uiTheme.fg("muted", t));
-						optText += `\n ${uiTheme.fg("dim", continuation)}   ${uiTheme.fg("dim", optBranch)} ${uiTheme.fg("dim", optionMarker(uiTheme, q.multi, false))} ${optLabel}`;
-						if (opt.description?.trim()) {
-							const optContinuation = isLastOpt ? " " : uiTheme.tree.vertical;
-							const description = renderInlineMarkdown(opt.description.trim(), mdTheme, t =>
-								uiTheme.fg("dim", t),
-							);
-							optText += `\n ${uiTheme.fg("dim", continuation)}   ${uiTheme.fg("dim", optContinuation)}   ${uiTheme.fg("dim", "↳")} ${description}`;
-						}
-					}
-					container.addChild(new Text(optText, 0, 0));
-				}
-			}
-			return container;
+			const questions = args.questions;
+			const header = `${label} ${uiTheme.fg("muted", `${questions.length} questions`)}`;
+			return framedBlock(uiTheme, width => {
+				const sections = questions.map(q => {
+					const meta: string[] = [];
+					if (q.multi) meta.push("multi");
+					if (q.options?.length) meta.push(`options:${q.options.length}`);
+					const metaStr = meta.length > 0 ? uiTheme.fg("dim", ` · ${meta.join(" · ")}`) : "";
+					const lines = md(q.question, width);
+					if (q.options?.length) lines.push(...renderQuestionOptionLines(uiTheme, mdTheme, q.options, q.multi));
+					return { label: `${uiTheme.fg("dim", `[${q.id}]`)}${metaStr}`, lines };
+				});
+				return { header, sections, state: "pending", borderColor: "borderMuted", width };
+			});
 		}
 
 		// Single question
 		if (!args.question) {
-			return new Text(formatErrorMessage("No question provided", uiTheme), 0, 0);
+			const errorLine = formatErrorMessage("No question provided", uiTheme);
+			return framedBlock(uiTheme, width => ({
+				header: errorLine,
+				sections: [],
+				state: "error",
+				borderColor: "error",
+				width,
+			}));
 		}
 
-		const container = new Container();
+		const question = args.question;
 		const meta: string[] = [];
 		if (args.multi) meta.push("multi");
 		if (args.options?.length) meta.push(`options:${args.options.length}`);
-		container.addChild(new Text(`${label}${formatMeta(meta, uiTheme)}`, 0, 0));
-		container.addChild(new Markdown(args.question, 1, 0, mdTheme, accentStyle));
-
-		if (args.options?.length) {
-			let optText = "";
-			for (let i = 0; i < args.options.length; i++) {
-				const opt = args.options[i];
-				const isLast = i === args.options.length - 1;
-				const branch = isLast ? uiTheme.tree.last : uiTheme.tree.branch;
-				const optLabel = renderInlineMarkdown(opt.label, mdTheme, t => uiTheme.fg("muted", t));
-				optText += `\n ${uiTheme.fg("dim", branch)} ${uiTheme.fg("dim", optionMarker(uiTheme, args.multi, false))} ${optLabel}`;
-				if (opt.description?.trim()) {
-					const continuation = isLast ? " " : uiTheme.tree.vertical;
-					const description = renderInlineMarkdown(opt.description.trim(), mdTheme, t => uiTheme.fg("dim", t));
-					optText += `\n ${uiTheme.fg("dim", continuation)}   ${uiTheme.fg("dim", "↳")} ${description}`;
-				}
-			}
-			container.addChild(new Text(optText, 0, 0));
-		}
-
-		return container;
+		const header = `${label}${formatMeta(meta, uiTheme)}`;
+		const questionOptions = args.options;
+		const multi = args.multi;
+		return framedBlock(uiTheme, width => {
+			const bodyLines = md(question, width);
+			if (questionOptions?.length)
+				bodyLines.push(...renderQuestionOptionLines(uiTheme, mdTheme, questionOptions, multi));
+			return {
+				header,
+				sections: bodyLines.length > 0 ? [{ lines: bodyLines }] : [],
+				state: "pending",
+				borderColor: "borderMuted",
+				width,
+			};
+		});
 	},
 
 	renderResult(
@@ -792,56 +761,47 @@ export const askToolRenderer = {
 		const { details } = result;
 		const mdTheme = getMarkdownTheme();
 		const accentStyle = { color: (t: string) => uiTheme.fg("accent", t) };
+		const md = (text: string, width: number) =>
+			new Markdown(text, 1, 0, mdTheme, accentStyle).render(Math.max(1, width - 3 + 1));
 
 		if (!details) {
 			const txt = result.content[0];
 			const fallback = txt?.type === "text" && txt.text ? txt.text : "";
 			const header = renderStatusLine({ icon: "warning", title: "Ask" }, uiTheme);
-			return new Text(`${header}\n${uiTheme.fg("dim", fallback)}`, 0, 0);
+			const body = fallback ? `\n${uiTheme.fg("dim", fallback)}` : "";
+			return new Text(`${header}${body}`, 0, 0);
 		}
 
-		// Multi-part results
+		// Multi-part results: one divider-labelled section per question.
 		if (details.results && details.results.length > 0) {
-			const hasAnySelection = details.results.some(
+			const results = details.results;
+			const hasAnySelection = results.some(
 				r => r.customInput !== undefined || (r.selectedOptions && r.selectedOptions.length > 0),
 			);
 			const header = renderStatusLine(
 				{
 					icon: hasAnySelection ? "success" : "warning",
 					title: "Ask",
-					meta: [`${details.results.length} questions`],
+					meta: [`${results.length} questions`],
 				},
 				uiTheme,
 			);
-			const container = new Container();
-			container.addChild(new Text(header, 0, 0));
-
-			for (let i = 0; i < details.results.length; i++) {
-				const r = details.results[i];
-				const isLastQuestion = i === details.results.length - 1;
-				const qBranch = isLastQuestion ? uiTheme.tree.last : uiTheme.tree.branch;
-				const continuation = isLastQuestion ? " " : uiTheme.tree.vertical;
-				const linePrefix = ` ${uiTheme.fg("dim", continuation)}   `;
-
-				container.addChild(new Text(` ${uiTheme.fg("dim", qBranch)} ${uiTheme.fg("dim", `[${r.id}]`)}`, 0, 0));
-				container.addChild(new Markdown(r.question, 3, 0, mdTheme, accentStyle));
-				container.addChild(
-					new Text(
-						renderAnswerOptions(
-							uiTheme,
-							mdTheme,
-							linePrefix,
-							r.options,
-							r.selectedOptions,
-							r.multi,
-							r.customInput,
-						),
-						0,
-						0,
-					),
-				);
-			}
-			return container;
+			return framedBlock(uiTheme, width => {
+				const sections = results.map(r => {
+					const lines = md(r.question, width);
+					lines.push(
+						...renderAnswerOptionLines(uiTheme, mdTheme, r.options, r.selectedOptions, r.multi, r.customInput),
+					);
+					return { label: uiTheme.fg("dim", `[${r.id}]`), lines };
+				});
+				return {
+					header,
+					sections,
+					state: hasAnySelection ? "success" : "warning",
+					borderColor: "borderMuted",
+					width,
+				};
+			});
 		}
 
 		// Single question result
@@ -851,29 +811,24 @@ export const askToolRenderer = {
 			return new Text(fallback, 0, 0);
 		}
 
+		const question = details.question;
 		const hasSelection =
 			details.customInput !== undefined || (details.selectedOptions && details.selectedOptions.length > 0);
 		const header = renderStatusLine({ icon: hasSelection ? "success" : "warning", title: "Ask" }, uiTheme);
-		const container = new Container();
-		container.addChild(new Text(header, 0, 0));
-		container.addChild(new Markdown(details.question, 1, 0, mdTheme, accentStyle));
-
-		container.addChild(
-			new Text(
-				renderAnswerOptions(
-					uiTheme,
-					mdTheme,
-					" ",
-					details.options,
-					details.selectedOptions,
-					details.multi,
-					details.customInput,
-				),
-				0,
-				0,
-			),
-		);
-
-		return container;
+		const dOptions = details.options;
+		const dSelected = details.selectedOptions;
+		const dMulti = details.multi;
+		const dCustom = details.customInput;
+		return framedBlock(uiTheme, width => {
+			const bodyLines = md(question, width);
+			bodyLines.push(...renderAnswerOptionLines(uiTheme, mdTheme, dOptions, dSelected, dMulti, dCustom));
+			return {
+				header,
+				sections: bodyLines.length > 0 ? [{ lines: bodyLines }] : [],
+				state: hasSelection ? "success" : "warning",
+				borderColor: "borderMuted",
+				width,
+			};
+		});
 	},
 };
diff --git a/packages/coding-agent/src/tools/ast-edit.ts b/packages/coding-agent/src/tools/ast-edit.ts
index 8cf2df79c..c9f8bd530 100644
--- a/packages/coding-agent/src/tools/ast-edit.ts
+++ b/packages/coding-agent/src/tools/ast-edit.ts
@@ -3,7 +3,7 @@ import { formatHashlineHeader } from "@oh-my-pi/hashline";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import { type AstReplaceChange, type AstReplaceFileChange, astEdit } from "@oh-my-pi/pi-natives";
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Text } from "@oh-my-pi/pi-tui";
+import { replaceTabs, Text } from "@oh-my-pi/pi-tui";
 import { $envpos, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import { getFileSnapshotStore } from "../edit/file-snapshot-store";
@@ -11,7 +11,7 @@ import { normalizeToLF } from "../edit/normalize";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import astEditDescription from "../prompts/tools/ast-edit.md" with { type: "text" };
-import { Ellipsis, fileHyperlink, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
+import { Ellipsis, fileHyperlink, framedBlock, renderStatusLine, truncateToWidth } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
 import { truncateForPrompt } from "./approval";
@@ -22,11 +22,10 @@ import { isInternalUrlPath, resolveToolSearchScope } from "./path-utils";
 import {
 	appendParseErrorsBulletList,
 	capParseErrors,
-	createCachedComponent,
 	formatCodeFrameLine,
 	formatCount,
-	formatEmptyMessage,
-	formatErrorMessage,
+	formatErrorDetail,
+	formatMoreItems,
 	formatParseErrors,
 	formatParseErrorsCountLabel,
 	PREVIEW_LIMITS,
@@ -463,6 +462,32 @@ interface AstEditRenderArgs {
 
 const COLLAPSED_CHANGE_LIMIT = PREVIEW_LIMITS.COLLAPSED_LINES * 2;
 
+/**
+ * Flatten pre-styled change groups into frame body lines. Groups are separated
+ * by a blank line and carry no tree guides — the frame border is the container,
+ * so nested `├─ │` gutters would just be noise. Collapsed mode always shows at
+ * least the first group, then fills up to `budget` lines before summarizing the
+ * rest as `… N more changes`.
+ */
+function buildChangeBody(groups: string[][], expanded: boolean, budget: number, theme: Theme): string[] {
+	const lines: string[] = [];
+	let shown = 0;
+	for (let i = 0; i < groups.length; i++) {
+		const group = groups[i]!;
+		const separator = shown > 0 ? 1 : 0;
+		const remainingAfter = groups.length - (i + 1);
+		const reserved = !expanded && remainingAfter > 0 ? 1 : 0;
+		// Always emit the first group; budget only gates subsequent ones.
+		if (!expanded && shown > 0 && lines.length + separator + group.length + reserved > budget) break;
+		if (separator) lines.push("");
+		lines.push(...group);
+		shown++;
+	}
+	const remaining = groups.length - shown;
+	if (!expanded && remaining > 0) lines.push(theme.fg("muted", formatMoreItems(remaining, "change")));
+	return lines;
+}
+
 export const astEditToolRenderer = {
 	inline: true,
 	renderCall(args: AstEditRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
@@ -472,8 +497,9 @@ export const astEditToolRenderer = {
 		if (rewriteCount > 1) meta.push(`${rewriteCount} rewrites`);
 
 		const description = rewriteCount === 1 ? args.ops?.[0]?.pat : rewriteCount ? `${rewriteCount} rewrites` : "?";
-		const text = renderStatusLine({ icon: "pending", title: "AST Edit", description, meta }, uiTheme);
-		return new Text(text, 0, 0);
+		const header = renderStatusLine({ icon: "pending", title: "AST Edit", description, meta }, uiTheme);
+		// Pending call has no body yet — a lone status line is sleeker than an empty frame.
+		return new Text(header, 0, 0);
 	},
 
 	renderResult(
@@ -486,7 +512,14 @@ export const astEditToolRenderer = {
 
 		if (result.isError) {
 			const errorText = result.content?.find(c => c.type === "text")?.text || "Unknown error";
-			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
+			const header = renderStatusLine({ icon: "error", title: "AST Edit" }, uiTheme);
+			return framedBlock(uiTheme, width => ({
+				header,
+				sections: [{ lines: formatErrorDetail(errorText, uiTheme).split("\n") }],
+				state: "error",
+				borderColor: "error",
+				width,
+			}));
 		}
 
 		const totalReplacements = details?.totalReplacements ?? 0;
@@ -501,9 +534,18 @@ export const astEditToolRenderer = {
 			if (details?.scopePath) meta.push(`in ${details.scopePath}`);
 			if (filesSearched > 0) meta.push(`searched ${filesSearched}`);
 			const header = renderStatusLine({ icon: "warning", title: "AST Edit", description, meta }, uiTheme);
-			const lines = [header, formatEmptyMessage("No replacements made", uiTheme)];
-			appendParseErrorsBulletList(lines, details?.parseErrors, uiTheme, details?.parseErrorsTotal);
-			return new Text(lines.join("\n"), 0, 0);
+			// The "0 replacements" count already rides on the status line; only parse
+			// errors are worth a body, so frame solely when there are some.
+			const bodyLines: string[] = [];
+			appendParseErrorsBulletList(bodyLines, details?.parseErrors, uiTheme, details?.parseErrorsTotal);
+			if (bodyLines.length === 0) return new Text(header, 0, 0);
+			return framedBlock(uiTheme, width => ({
+				header,
+				sections: [{ lines: bodyLines }],
+				state: "warning",
+				borderColor: "borderMuted",
+				width,
+			}));
 		}
 
 		const summaryParts = [formatCount("replacement", totalReplacements), formatCount("file", filesTouched)];
@@ -521,17 +563,20 @@ export const astEditToolRenderer = {
 		const contexts = classifyGroupedLines(allLines, details?.searchPath);
 		const styledLines = allLines.map((line, index) => {
 			const ctx = contexts[index]!;
+			// Swap the inner code-frame gutter `│` for a space so it does not nest a
+			// second vertical bar inside the frame border.
+			const display = replaceTabs(line.replace("│", " "));
 			if (ctx.kind === "dir") {
-				const styled = uiTheme.fg("accent", line);
+				const styled = uiTheme.fg("accent", display);
 				return ctx.headerPath ? fileHyperlink(ctx.headerPath, styled) : styled;
 			}
 			if (ctx.kind === "file") {
-				const styled = uiTheme.fg(ctx.depth === 1 ? "accent" : "dim", line);
+				const styled = uiTheme.fg(ctx.depth === 1 ? "accent" : "dim", display);
 				return ctx.headerPath ? fileHyperlink(ctx.headerPath, styled) : styled;
 			}
-			if (line.startsWith("+")) return uiTheme.fg("toolDiffAdded", line);
-			if (line.startsWith("-")) return uiTheme.fg("toolDiffRemoved", line);
-			return uiTheme.fg("toolOutput", line);
+			if (display.startsWith("+")) return uiTheme.fg("toolDiffAdded", display);
+			if (display.startsWith("-")) return uiTheme.fg("toolDiffRemoved", display);
+			return uiTheme.fg("toolOutput", display);
 		});
 		const changeGroups = groupLineIndicesByBlank(allLines)
 			.filter(indices => {
@@ -555,23 +600,19 @@ export const astEditToolRenderer = {
 				uiTheme.fg("warning", formatParseErrorsCountLabel(details.parseErrors, details.parseErrorsTotal)),
 			);
 		}
-		return createCachedComponent(
-			() => options.expanded,
-			width => {
-				const changeLines = renderTreeList(
-					{
-						items: changeGroups,
-						expanded: options.expanded,
-						maxCollapsed: changeGroups.length,
-						maxCollapsedLines: COLLAPSED_CHANGE_LIMIT,
-						itemType: "change",
-						renderItem: group => group,
-					},
-					uiTheme,
-				);
-				return [header, ...changeLines, ...extraLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
-			},
-		);
+		return framedBlock(uiTheme, width => {
+			const changeLines = buildChangeBody(changeGroups, Boolean(options.expanded), COLLAPSED_CHANGE_LIMIT, uiTheme);
+			const innerWidth = Math.max(1, width - 3);
+			const bodyLines = [...changeLines, ...extraLines].map(l => truncateToWidth(l, innerWidth, Ellipsis.Omit));
+			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
+			return {
+				header,
+				sections: bodyLines.length > 0 ? [{ lines: bodyLines }] : [],
+				state: options.isPartial ? "pending" : "success",
+				borderColor: "borderMuted",
+				width,
+			};
+		});
 	},
 	mergeCallAndResult: true,
 };
diff --git a/packages/coding-agent/src/tools/gh-renderer.ts b/packages/coding-agent/src/tools/gh-renderer.ts
index cb01261ea..d34d8d9f0 100644
--- a/packages/coding-agent/src/tools/gh-renderer.ts
+++ b/packages/coding-agent/src/tools/gh-renderer.ts
@@ -1,7 +1,7 @@
-import { type Component, padding, Text, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui";
+import { type Component, padding, Text, visibleWidth } from "@oh-my-pi/pi-tui";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme, ThemeColor } from "../modes/theme/theme";
-import { renderStatusLine } from "../tui";
+import { framedBlock, renderStatusLine } from "../tui";
 import type {
 	GhRunWatchFailedLogDetails,
 	GhRunWatchJobDetails,
@@ -239,7 +239,7 @@ function renderFailedLogs(
 		return [];
 	}
 
-	const lines = ["", theme.fg("error", "failed logs")];
+	const lines: string[] = [];
 	for (const entry of failedLogs) {
 		const context = entry.workflowName ? `${entry.workflowName}  #${entry.runId}` : `run #${entry.runId}`;
 		lines.push(
@@ -268,36 +268,45 @@ function renderFailedLogs(
 	return lines;
 }
 
-function buildWatchLines(
+function buildWatchSections(
 	watch: GhRunWatchViewDetails,
 	theme: Theme,
 	options: RenderResultOptions,
 	width: number,
-): string[] {
-	const lines = [theme.fg("muted", getWatchHeader(watch))];
+): Array<{ label?: string; lines: string[] }> {
+	const main: string[] = [];
 
 	if (watch.note) {
-		lines.push(theme.fg("dim", replaceTabs(watch.note)));
+		main.push(theme.fg("dim", replaceTabs(watch.note)));
 	}
 
 	if (watch.mode === "run" && watch.run) {
-		lines.push(...renderRunBlock(watch.run, width, theme));
+		main.push(...renderRunBlock(watch.run, width, theme));
 	} else if (watch.mode === "commit") {
 		const runs = watch.runs ?? [];
 		if (runs.length === 0) {
-			lines.push(theme.fg("dim", "waiting for workflow runs..."));
+			main.push(theme.fg("dim", "waiting for workflow runs..."));
 		} else {
 			runs.forEach((run, index) => {
 				if (index > 0) {
-					lines.push("");
+					main.push("");
 				}
-				lines.push(...renderRunBlock(run, width, theme));
+				main.push(...renderRunBlock(run, width, theme));
 			});
 		}
 	}
 
-	lines.push(...renderFailedLogs(watch.failedLogs ?? [], width, theme, options.expanded));
-	return lines;
+	const sections: Array<{ label?: string; lines: string[] }> = [];
+	if (main.length > 0) {
+		sections.push({ lines: main });
+	}
+
+	const failed = renderFailedLogs(watch.failedLogs ?? [], width, theme, options.expanded);
+	if (failed.length > 0) {
+		sections.push({ label: "failed logs", lines: failed });
+	}
+
+	return sections;
 }
 
 function extractText(content: Array<{ type: string; text?: string }>): string {
@@ -335,29 +344,44 @@ function renderFallbackComponent(
 	}
 
 	const allLines = replaceTabs(text).split("\n");
+	while (allLines.length > 0 && allLines[0].trim() === "") allLines.shift();
+	while (allLines.length > 0 && allLines[allLines.length - 1].trim() === "") allLines.pop();
 
-	return {
-		render(width: number): string[] {
-			const lineWidth = Math.max(24, width || FALLBACK_WIDTH);
-			const expanded = options.expanded;
-			const limit = expanded ? allLines.length : Math.min(allLines.length, PREVIEW_LIMITS.OUTPUT_EXPANDED);
-			const visible = allLines.slice(0, limit);
-			const remaining = allLines.length - visible.length;
+	// Trivial one-line *success* result: a clean status line beats an almost-empty box.
+	// Errors always frame so the message reads as a structured block, never a raw red wrap.
+	if (allLines.length <= 1 && !isError) {
+		const body = allLines[0];
+		if (!body) return new Text(header, 0, 0);
+		const colored = isError ? theme.fg("error", body) : theme.fg("toolOutput", body);
+		return new Text(`${header}\n${colored}`, 0, 0);
+	}
 
-			const out: string[] = [header];
-			for (const line of visible) {
-				const colored = isError ? theme.fg("error", line) : theme.fg("toolOutput", line);
-				out.push(truncateVisualWidth(colored, lineWidth));
-			}
-			if (!expanded && remaining > 0) {
-				const hint = formatExpandHint(theme, expanded, true);
-				const more = `${formatMoreItems(remaining, "line")}${hint ? ` ${hint}` : ""}`;
-				out.push(theme.fg("dim", more));
-			}
-			return out.map(line => truncateToWidth(line, lineWidth));
-		},
-		invalidate() {},
-	};
+	return framedBlock(theme, width => {
+		const lineWidth = Math.max(1, (width || FALLBACK_WIDTH) - 3);
+		const expanded = options.expanded;
+		const limit = expanded ? allLines.length : Math.min(allLines.length, PREVIEW_LIMITS.OUTPUT_EXPANDED);
+		const visible = allLines.slice(0, limit);
+		const remaining = allLines.length - visible.length;
+
+		const out: string[] = [];
+		for (const line of visible) {
+			const colored = isError ? theme.fg("error", line) : theme.fg("toolOutput", line);
+			out.push(truncateVisualWidth(colored, lineWidth));
+		}
+		if (!expanded && remaining > 0) {
+			const hint = formatExpandHint(theme, expanded, true);
+			const more = `${formatMoreItems(remaining, "line")}${hint ? ` ${hint}` : ""}`;
+			out.push(theme.fg("dim", more));
+		}
+		return {
+			header,
+			sections: out.length > 0 ? [{ lines: out }] : [],
+			state: isError ? "error" : "success",
+			borderColor: isError ? "error" : "borderMuted",
+			applyBg: false,
+			width,
+		};
+	});
 }
 
 function renderWatchCall(args: GithubToolRenderArgs, options: RenderResultOptions, theme: Theme): Component {
@@ -380,7 +404,7 @@ function renderWatchCall(args: GithubToolRenderArgs, options: RenderResultOption
 	}
 
 	const header = `${icon} ${titleText}  ${metaText}`;
-	const wait = theme.fg("dim", "  waiting for workflow data...");
+	const wait = theme.fg("dim", "waiting for workflow data...");
 	return new Text(`${header}\n${wait}`, 0, 0);
 }
 
@@ -412,13 +436,28 @@ export const githubToolRenderer = {
 	): Component {
 		const watch = result.details?.watch;
 		if (watch) {
-			return {
-				render(width: number): string[] {
-					const lineWidth = Math.max(24, width || FALLBACK_WIDTH);
-					return buildWatchLines(watch, uiTheme, options, lineWidth).map(line => truncateToWidth(line, lineWidth));
+			const isError = result.isError === true;
+			const header = renderStatusLine(
+				{
+					icon: isError ? "error" : "success",
+					title: "GitHub Run Watch",
+					titleColor: isError ? "error" : "accent",
+					meta: [getWatchHeader(watch)],
 				},
-				invalidate() {},
-			};
+				uiTheme,
+			);
+			return framedBlock(uiTheme, width => {
+				const innerWidth = Math.max(1, (width || FALLBACK_WIDTH) - 3);
+				const sections = buildWatchSections(watch, uiTheme, options, innerWidth);
+				return {
+					header,
+					sections,
+					state: isError ? "error" : "success",
+					borderColor: isError ? "error" : "borderMuted",
+					applyBg: false,
+					width,
+				};
+			});
 		}
 
 		return renderFallbackComponent(result, options, uiTheme, args ?? {});
diff --git a/packages/coding-agent/src/tools/inspect-image-renderer.ts b/packages/coding-agent/src/tools/inspect-image-renderer.ts
index 75a80e0ea..604a04d52 100644
--- a/packages/coding-agent/src/tools/inspect-image-renderer.ts
+++ b/packages/coding-agent/src/tools/inspect-image-renderer.ts
@@ -2,8 +2,8 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
-import { renderStatusLine } from "../tui";
-import { formatExpandHint, replaceTabs, shortenPath, truncateToWidth } from "./render-utils";
+import { framedBlock, renderStatusLine } from "../tui";
+import { formatErrorDetail, formatExpandHint, replaceTabs, shortenPath, truncateToWidth } from "./render-utils";
 
 interface InspectImageRenderArgs {
 	path?: string;
@@ -27,17 +27,21 @@ const INSPECT_OUTPUT_COLLAPSED_LINES = 4;
 const INSPECT_OUTPUT_EXPANDED_LINES = 16;
 const INSPECT_OUTPUT_LINE_WIDTH = 120;
 
+function questionLine(question: string, uiTheme: Theme): string {
+	return `${uiTheme.fg("dim", "Question:")} ${uiTheme.fg("accent", truncateToWidth(replaceTabs(question), INSPECT_QUESTION_PREVIEW_WIDTH))}`;
+}
+
 export const inspectImageToolRenderer = {
 	renderCall(args: InspectImageRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const rawPath = args.path ?? "";
 		const pathDisplay = rawPath ? shortenPath(rawPath) : "…";
-		const header = renderStatusLine({ icon: "pending", title: "Inspect Image", description: pathDisplay }, uiTheme);
+		const header = renderStatusLine({ icon: "pending", title: "Inspect", description: pathDisplay }, uiTheme);
 		const question = args.question?.trim();
-		if (!question) {
-			return new Text(header, 0, 0);
-		}
-		const questionLine = ` ${uiTheme.fg("dim", uiTheme.tree.last)} ${uiTheme.fg("dim", "Question:")} ${uiTheme.fg("accent", truncateToWidth(replaceTabs(question), INSPECT_QUESTION_PREVIEW_WIDTH))}`;
-		return new Text(`${header}\n${questionLine}`, 0, 0);
+		// Call is at most a status line plus a one-line question — too small to box.
+		// The container renders a lone Text cleanly with no chrome.
+		if (!question) return new Text(header, 0, 0);
+		const tree = ` ${uiTheme.fg("dim", uiTheme.tree.last)} ${questionLine(question, uiTheme)}`;
+		return new Text(`${header}\n${tree}`, 0, 0);
 	},
 
 	renderResult(
@@ -49,55 +53,73 @@ export const inspectImageToolRenderer = {
 		const details = result.details;
 		const rawPath = details?.imagePath ?? args?.path ?? "";
 		const pathDisplay = rawPath ? shortenPath(rawPath) : "image";
-		const metaParts: string[] = [];
-		if (details?.model) metaParts.push(details.model);
-		if (details?.mimeType) metaParts.push(details.mimeType);
 		const header = renderStatusLine(
 			{
 				icon: result.isError ? "error" : "success",
-				title: "Inspect Image",
+				title: "Inspect",
 				description: pathDisplay,
 			},
 			uiTheme,
 		);
 
-		const lines: string[] = [header];
 		const question = args?.question?.trim();
-		if (question) {
-			lines.push(
-				` ${uiTheme.fg("dim", uiTheme.tree.branch)} ${uiTheme.fg("dim", "Question:")} ${uiTheme.fg("accent", truncateToWidth(replaceTabs(question), INSPECT_QUESTION_PREVIEW_WIDTH))}`,
-			);
-		}
-
 		const outputText = result.content.find(content => content.type === "text")?.text?.trimEnd() ?? "";
+
+		if (result.isError) {
+			return framedBlock(uiTheme, width => {
+				const bodyLines: string[] = [];
+				if (question) bodyLines.push(questionLine(question, uiTheme));
+				bodyLines.push(formatErrorDetail(outputText || "inspection failed", uiTheme));
+				return {
+					header,
+					sections: [{ lines: bodyLines }],
+					state: "error",
+					borderColor: "error",
+					applyBg: false,
+					width,
+				};
+			});
+		}
+
+		const metaParts: string[] = [];
+		if (details?.model) metaParts.push(details.model);
+		if (details?.mimeType) metaParts.push(details.mimeType);
+		const metaLine = metaParts.length > 0 ? uiTheme.fg("dim", metaParts.join(" · ")) : "";
+
+		// No answer text: nothing worth boxing — keep it to a clean status line
+		// (plus a trailing meta line, when present).
 		if (!outputText) {
-			lines.push(uiTheme.fg("dim", "(no output)"));
-			if (metaParts.length > 0) {
-				lines.push("");
-				lines.push(uiTheme.fg("dim", metaParts.join(" · ")));
+			return new Text(metaLine ? `${header}\n${metaLine}` : header, 0, 0);
+		}
+
+		return framedBlock(uiTheme, width => {
+			const bodyLines: string[] = [];
+			if (question) {
+				bodyLines.push(questionLine(question, uiTheme));
+				bodyLines.push("");
 			}
-			return new Text(lines.join("\n"), 0, 0);
-		}
 
-		lines.push("");
-		const outputLines = replaceTabs(outputText).split("\n");
-		const maxLines = options.expanded ? INSPECT_OUTPUT_EXPANDED_LINES : INSPECT_OUTPUT_COLLAPSED_LINES;
-		for (const line of outputLines.slice(0, maxLines)) {
-			lines.push(uiTheme.fg("toolOutput", truncateToWidth(line, INSPECT_OUTPUT_LINE_WIDTH)));
-		}
+			const outputLines = replaceTabs(outputText).split("\n");
+			const maxLines = options.expanded ? INSPECT_OUTPUT_EXPANDED_LINES : INSPECT_OUTPUT_COLLAPSED_LINES;
+			for (const line of outputLines.slice(0, maxLines)) {
+				bodyLines.push(uiTheme.fg("toolOutput", truncateToWidth(line, INSPECT_OUTPUT_LINE_WIDTH)));
+			}
+			if (outputLines.length > maxLines) {
+				const remaining = outputLines.length - maxLines;
+				const hint = formatExpandHint(uiTheme, options.expanded, true);
+				bodyLines.push(`${uiTheme.fg("dim", `… ${remaining} more lines`)}${hint ? ` ${hint}` : ""}`);
+			}
 
-		if (outputLines.length > maxLines) {
-			const remaining = outputLines.length - maxLines;
-			const hint = formatExpandHint(uiTheme, options.expanded, true);
-			lines.push(`${uiTheme.fg("dim", `… ${remaining} more lines`)}${hint ? ` ${hint}` : ""}`);
-		}
-
-		if (metaParts.length > 0) {
-			lines.push("");
-			lines.push(uiTheme.fg("dim", metaParts.join(" · ")));
-		}
-
-		return new Text(lines.join("\n"), 0, 0);
+			return {
+				header,
+				headerMeta: metaLine || undefined,
+				sections: [{ lines: bodyLines }],
+				state: "success",
+				borderColor: "borderMuted",
+				applyBg: false,
+				width,
+			};
+		});
 	},
 	mergeCallAndResult: true,
 };
diff --git a/packages/coding-agent/src/tools/job.ts b/packages/coding-agent/src/tools/job.ts
index 18defb3f7..c0f326d5d 100644
--- a/packages/coding-agent/src/tools/job.ts
+++ b/packages/coding-agent/src/tools/job.ts
@@ -396,7 +396,7 @@ export const jobToolRenderer = {
 	inline: true,
 
 	renderCall(args: JobRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
-		const text = renderStatusLine({ icon: "pending", title: "Job", description: describeTarget(args) }, uiTheme);
+		const text = renderStatusLine({ icon: "pending", title: describeTarget(args) || "Job" }, uiTheme);
 		return new Text(text, 0, 0);
 	},
 
@@ -410,7 +410,7 @@ export const jobToolRenderer = {
 
 		if (jobs.length === 0) {
 			const fallback = result.content?.find(c => c.type === "text")?.text || "No jobs to process";
-			const header = renderStatusLine({ icon: "warning", title: "Job", description: describeTarget(args) }, uiTheme);
+			const header = renderStatusLine({ icon: "warning", title: describeTarget(args) || "Job" }, uiTheme);
 			return new Text([header, formatEmptyMessage(fallback, uiTheme)].join("\n"), 0, 0);
 		}
 
@@ -433,8 +433,7 @@ export const jobToolRenderer = {
 			{
 				icon: headerIcon,
 				spinnerFrame: counts.running > 0 ? options.spinnerFrame : undefined,
-				title: "Job",
-				description,
+				title: description,
 				meta,
 			},
 			uiTheme,
diff --git a/packages/coding-agent/src/tools/memory-render.ts b/packages/coding-agent/src/tools/memory-render.ts
index 79e7da17a..2430eef6c 100644
--- a/packages/coding-agent/src/tools/memory-render.ts
+++ b/packages/coding-agent/src/tools/memory-render.ts
@@ -4,7 +4,10 @@
  *
  * These keep the transcript terse — one status line plus, for `retain`, one
  * `Remember: …` line per stored item — instead of the generic JSON arg tree,
- * which exploded multi-line memory blobs into an unreadable wall.
+ * which exploded multi-line memory blobs into an unreadable wall. The tool
+ * container is a transparent passthrough, so these renderers stay frameless:
+ * a status line with a couple of dim bullets reads far cleaner than boxing a
+ * one-line memory note.
  */
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
diff --git a/packages/coding-agent/src/tools/todo.ts b/packages/coding-agent/src/tools/todo.ts
index f61d4b419..cbadac62b 100644
--- a/packages/coding-agent/src/tools/todo.ts
+++ b/packages/coding-agent/src/tools/todo.ts
@@ -9,8 +9,8 @@ import type { Theme } from "../modes/theme/theme";
 import todoDescription from "../prompts/tools/todo.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
 import type { SessionEntry } from "../session/session-manager";
-import { renderStatusLine, renderTreeList } from "../tui";
-import { PREVIEW_LIMITS } from "./render-utils";
+import { framedBlock, renderStatusLine } from "../tui";
+import { formatErrorDetail, formatMoreItems, PREVIEW_LIMITS } from "./render-utils";
 
 // =============================================================================
 // Types
@@ -755,19 +755,17 @@ function formatTodoLine(
 	}
 }
 
-function renderNoteAttachments(phases: TodoPhase[], uiTheme: Theme): string[] {
+function renderNoteAttachments(phases: TodoPhase[], uiTheme: Theme, indent: string): string[] {
 	const lines: string[] = [];
 	for (const phase of phases) {
 		for (const task of phase.tasks) {
 			if (task.status !== "in_progress" || !task.notes || task.notes.length === 0) continue;
-			const bar = uiTheme.fg("dim", uiTheme.tree.vertical);
-			const title = uiTheme.fg("dim", chalk.italic(`§ notes — ${task.content}`));
 			lines.push("");
-			lines.push(`  ${title}`);
+			lines.push(`${indent}${uiTheme.fg("dim", chalk.italic(`§ notes — ${task.content}`))}`);
 			for (let j = 0; j < task.notes.length; j++) {
-				if (j > 0) lines.push(`  ${bar}`);
+				if (j > 0) lines.push("");
 				for (const noteLine of task.notes[j].split("\n")) {
-					lines.push(`  ${bar} ${uiTheme.fg("dim", noteLine)}`);
+					lines.push(`${indent}  ${uiTheme.fg("dim", noteLine)}`);
 				}
 			}
 		}
@@ -776,7 +774,7 @@ function renderNoteAttachments(phases: TodoPhase[], uiTheme: Theme): string[] {
 }
 
 export const todoToolRenderer = {
-	renderCall(args: TodoRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
+	renderCall(args: TodoRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
 		// `args` here is the raw partially-parsed JSON from the streaming
 		// tool-call delta and may not satisfy `TodoRenderArgs` at runtime:
 		// `parseStreamingJson` can hand back `{ ops: "[" }` mid-delta, or
@@ -797,16 +795,33 @@ export const todoToolRenderer = {
 						}
 						return parts.join(" ");
 					});
-		const text = renderStatusLine({ icon: "pending", title: "Todo", meta: ops }, uiTheme);
-		return new Text(text, 0, 0);
+		// No body worth boxing while the call streams — a lone status line reads
+		// cleaner than an empty frame. The container renders it without chrome.
+		const header = renderStatusLine(
+			{ icon: "pending", spinnerFrame: options?.spinnerFrame, title: "Todo", meta: ops },
+			uiTheme,
+		);
+		return new Text(header, 0, 0);
 	},
 
 	renderResult(
-		result: { content: Array<{ type: string; text?: string }>; details?: TodoToolDetails },
+		result: { content: Array<{ type: string; text?: string }>; details?: TodoToolDetails; isError?: boolean },
 		options: RenderResultOptions,
 		uiTheme: Theme,
 		_args?: TodoRenderArgs,
 	): Component {
+		if (result.isError) {
+			const errorText = result.content?.find(content => content.type === "text")?.text ?? "Todo operation failed";
+			const header = renderStatusLine({ icon: "error", title: "Todo" }, uiTheme);
+			return framedBlock(uiTheme, width => ({
+				header,
+				sections: [{ lines: formatErrorDetail(errorText, uiTheme).split("\n") }],
+				state: "error",
+				borderColor: "error",
+				width,
+			}));
+		}
+
 		const phases = (result.details?.phases ?? []).filter(phase => phase.tasks.length > 0);
 		const completedTasks = result.details?.completedTasks ?? [];
 		const completionKeysByPhase = new Map<string, Set<string>>();
@@ -822,48 +837,42 @@ export const todoToolRenderer = {
 		const header = renderStatusLine({ icon: "success", title: "Todo", meta: [`${allTasks.length} tasks`] }, uiTheme);
 		if (allTasks.length === 0) {
 			const fallback = result.content?.find(content => content.type === "text")?.text ?? "No todos";
-			return new Text(`${header}\n${uiTheme.fg("dim", fallback)}`, 0, 0);
+			return new Text(`${header}\n  ${uiTheme.fg("dim", fallback)}`, 0, 0);
 		}
 
-		let cachedKey: string | undefined;
-		let cachedLines: string[] | undefined;
-		return {
-			invalidate(): void {
-				cachedKey = undefined;
-				cachedLines = undefined;
-			},
-			render(width: number): string[] {
-				const { expanded, spinnerFrame } = options;
-				const key = `${expanded ? 1 : 0}:${spinnerFrame ?? -1}:${width}`;
-				if (cachedKey === key && cachedLines) return cachedLines;
-
-				const lines: string[] = [header];
-				for (let p = 0; p < phases.length; p++) {
-					const phase = phases[p];
-					if (phases.length > 1) {
-						lines.push(uiTheme.fg("accent", chalk.bold(`  ${formatPhaseDisplayName(phase.name, p + 1)}`)));
-					}
-					const completionKeys = completionKeysByPhase.get(phase.name) ?? EMPTY_COMPLETION_KEYS;
-					const treeLines = renderTreeList(
-						{
-							items: phase.tasks,
-							expanded,
-							maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
-							itemType: "todo",
-							renderItem: todo => formatTodoLine(todo, uiTheme, "", completionKeys, spinnerFrame),
-						},
-						uiTheme,
-					);
-					for (const line of treeLines) {
-						lines.push(`  ${line}`);
-					}
+		return framedBlock(uiTheme, width => {
+			const { expanded, spinnerFrame } = options;
+			const multiPhase = phases.length > 1;
+			const indent = multiPhase ? "  " : "";
+			const bodyLines: string[] = [];
+			for (let p = 0; p < phases.length; p++) {
+				const phase = phases[p];
+				if (multiPhase) {
+					if (p > 0) bodyLines.push("");
+					bodyLines.push(uiTheme.fg("accent", chalk.bold(formatPhaseDisplayName(phase.name, p + 1))));
 				}
-				lines.push(...renderNoteAttachments(phases, uiTheme));
-				cachedKey = key;
-				cachedLines = lines;
-				return lines;
-			},
-		};
+				const completionKeys = completionKeysByPhase.get(phase.name) ?? EMPTY_COMPLETION_KEYS;
+				const maxItems = expanded
+					? phase.tasks.length
+					: Math.min(phase.tasks.length, PREVIEW_LIMITS.COLLAPSED_ITEMS);
+				for (let i = 0; i < maxItems; i++) {
+					bodyLines.push(`${indent}${formatTodoLine(phase.tasks[i], uiTheme, "", completionKeys, spinnerFrame)}`);
+				}
+				const remaining = phase.tasks.length - maxItems;
+				if (!expanded && remaining > 0) {
+					bodyLines.push(`${indent}${uiTheme.fg("muted", formatMoreItems(remaining, "todo"))}`);
+				}
+			}
+			bodyLines.push(...renderNoteAttachments(phases, uiTheme, indent));
+			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
+			return {
+				header,
+				sections: bodyLines.length > 0 ? [{ lines: bodyLines }] : [],
+				state: options.isPartial ? "pending" : "success",
+				borderColor: "borderMuted",
+				width,
+			};
+		});
 	},
 	mergeCallAndResult: true,
 };
diff --git a/packages/coding-agent/src/tools/write.ts b/packages/coding-agent/src/tools/write.ts
index fc3946fc0..e39e75533 100644
--- a/packages/coding-agent/src/tools/write.ts
+++ b/packages/coding-agent/src/tools/write.ts
@@ -5,7 +5,6 @@ import * as path from "node:path";
 import { formatHashlineHeader, stripHashlinePrefixes } from "@oh-my-pi/hashline";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Text } from "@oh-my-pi/pi-tui";
 import { isEnoent, isRecord, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 
@@ -19,7 +18,7 @@ import { getDiagnosticsLedger } from "../lsp/diagnostics-ledger";
 import { getLanguageFromPath, highlightCode, type Theme } from "../modes/theme/theme";
 import writeDescription from "../prompts/tools/write.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
-import { Ellipsis, Hasher, type RenderCache, renderStatusLine, truncateToWidth } from "../tui";
+import { framedBlock, renderStatusLine } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { truncateForPrompt } from "./approval";
 import { parseArchivePathCandidates } from "./archive-reader";
@@ -40,8 +39,6 @@ import {
 	formatErrorDetail,
 	formatExpandHint,
 	formatMoreItems,
-	formatStatusIcon,
-	formatTitle,
 	getLspBatchRequest,
 	replaceTabs,
 	shortenPath,
@@ -961,9 +958,9 @@ function formatStreamingContent(
 	}
 	for (let i = 0; i < highlighted.length; i++) {
 		const lineNum = startIndex + i + 1;
-		const gutter = uiTheme.fg("dim", `${String(lineNum).padStart(lineNumberWidth, " ")}│`);
+		const gutter = uiTheme.fg("dim", `${String(lineNum).padStart(lineNumberWidth, " ")} `);
 		const body = replaceTabs(highlighted[i] ?? "");
-		text += ` ${gutter}${body}\n`;
+		text += `${gutter}${body}\n`;
 	}
 	text += uiTheme.fg("dim", `… (streaming)`);
 	return text;
@@ -987,9 +984,9 @@ function renderContentPreview(
 	let text = "\n\n";
 	for (let i = 0; i < highlighted.length; i++) {
 		const lineNum = i + 1;
-		const gutter = uiTheme.fg("dim", `${String(lineNum).padStart(lineNumberWidth, " ")}│`);
+		const gutter = uiTheme.fg("dim", `${String(lineNum).padStart(lineNumberWidth, " ")} `);
 		const body = replaceTabs(highlighted[i] ?? "");
-		text += ` ${gutter}${body}\n`;
+		text += `${gutter}${body}\n`;
 	}
 	if (!expanded && hidden > 0) {
 		const hint = formatExpandHint(uiTheme, expanded, hidden > 0);
@@ -1006,19 +1003,29 @@ export const writeToolRenderer = {
 		const lang = getLanguageFromPath(rawPath) ?? "text";
 		const langIcon = uiTheme.fg("muted", uiTheme.getLangIcon(lang));
 		const pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
-		const spinner =
-			options?.spinnerFrame !== undefined ? formatStatusIcon("running", uiTheme, options.spinnerFrame) : "";
-
-		let text = `${formatTitle("Write", uiTheme)} ${spinner ? `${spinner} ` : ""}${langIcon} ${pathDisplay}`;
-
-		if (!args.content) {
-			return new Text(text, 0, 0);
-		}
-
-		// Show streaming preview of content — bounded tail while collapsed, full on Ctrl+O.
-		text += formatStreamingContent(args.content, Boolean(options?.expanded), lang, uiTheme);
-
-		return new Text(text, 0, 0);
+		const header = renderStatusLine(
+			{
+				icon: "pending",
+				spinnerFrame: options?.spinnerFrame,
+				title: "Write",
+				description: `${langIcon} ${pathDisplay}`,
+			},
+			uiTheme,
+		);
+		return framedBlock(uiTheme, width => {
+			const body = args.content
+				? formatStreamingContent(args.content, Boolean(options?.expanded), lang, uiTheme)
+				: "";
+			const bodyLines = body ? body.split("\n") : [];
+			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
+			return {
+				header,
+				sections: bodyLines.length > 0 ? [{ lines: bodyLines }] : [],
+				state: "pending",
+				borderColor: "borderMuted",
+				width,
+			};
+		});
 	},
 
 	// Only the expanded (Ctrl+O) preview is append-only: it renders the whole
@@ -1047,19 +1054,24 @@ export const writeToolRenderer = {
 
 		if (result.isError) {
 			const errorText = result.content?.find(c => c.type === "text")?.text ?? "";
-			const errorHeader = renderStatusLine(
+			const header = renderStatusLine(
 				{ icon: "error", title: "Write", description: `${langIcon} ${pathDisplay}` },
 				uiTheme,
 			);
-			return new Text(`${errorHeader}\n${formatErrorDetail(errorText, uiTheme)}`, 0, 0);
+			return framedBlock(uiTheme, width => ({
+				header,
+				sections: [{ lines: formatErrorDetail(errorText, uiTheme).split("\n") }],
+				state: "error",
+				borderColor: "error",
+				width,
+			}));
 		}
+
 		const lineCount = countLines(fileContent);
 		const lineSuffix = formatLineCountSuffix(lineCount, uiTheme);
 		const execSuffix = result.details?.madeExecutable
 			? `${uiTheme.fg("dim", " · ")}${uiTheme.fg("success", "made executable!")}`
 			: "";
-
-		// Build header with status icon
 		const header = renderStatusLine(
 			{
 				icon: "success",
@@ -1070,38 +1082,29 @@ export const writeToolRenderer = {
 		);
 		const diagnostics = result.details?.diagnostics;
 
-		let cached: RenderCache | undefined;
-
-		return {
-			render(width: number) {
-				const { expanded } = options;
-				const key = new Hasher().bool(expanded).u32(width).digest();
-				if (cached?.key === key) return cached.lines;
-
-				let text = header;
-				text += renderContentPreview(fileContent, expanded, lang, uiTheme);
-
-				if (diagnostics) {
-					const diagText = formatDiagnostics(diagnostics, expanded, uiTheme, fp =>
-						uiTheme.getLangIcon(getLanguageFromPath(fp)),
-					);
-					if (diagText.trim()) {
-						const diagLines = diagText.split("\n");
-						const firstNonEmpty = diagLines.findIndex(line => line.trim());
-						if (firstNonEmpty >= 0) {
-							text += `\n${diagLines.slice(firstNonEmpty).join("\n")}`;
-						}
-					}
+		return framedBlock(uiTheme, width => {
+			const { expanded } = options;
+			let body = renderContentPreview(fileContent, expanded, lang, uiTheme);
+			if (diagnostics) {
+				const diagText = formatDiagnostics(diagnostics, expanded, uiTheme, fp =>
+					uiTheme.getLangIcon(getLanguageFromPath(fp)),
+				);
+				if (diagText.trim()) {
+					const diagLines = diagText.split("\n");
+					const firstNonEmpty = diagLines.findIndex(line => line.trim());
+					if (firstNonEmpty >= 0) body += `\n${diagLines.slice(firstNonEmpty).join("\n")}`;
 				}
-
-				const lines = text.split("\n").map(l => truncateToWidth(l, width, Ellipsis.Omit));
-				cached = { key, lines };
-				return lines;
-			},
-			invalidate() {
-				cached = undefined;
-			},
-		};
+			}
+			const bodyLines = body.split("\n");
+			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
+			return {
+				header,
+				sections: bodyLines.length > 0 ? [{ lines: bodyLines }] : [],
+				state: "success",
+				borderColor: "borderMuted",
+				width,
+			};
+		});
 	},
 	mergeCallAndResult: true,
 };

From 52f7defeabf0b0450b3500a401cf1ecba6cef88b Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:36:14 +0200
Subject: [PATCH 097/181] fix(coding-agent-tools): fixed OSC8 links to use
 resolved file paths from session context

- Fixed edit/read/search/ast-edit/ast-grep outputs to resolve OSC8 links from session cwd.
- Fixed grouped-file output classification to honor headerBase and fileScope for parent path resolution.
- Fixed read and write renderers to use resolved source/resolved paths as hyperlink targets.
---
 packages/coding-agent/CHANGELOG.md            |   1 +
 packages/coding-agent/src/edit/renderer.ts    |  16 +-
 .../src/modes/utils/ui-helpers.ts             |  14 --
 packages/coding-agent/src/tools/ast-edit.ts   |   6 +-
 packages/coding-agent/src/tools/ast-grep.ts   |   6 +-
 .../src/tools/grouped-file-output.ts          |  19 +-
 packages/coding-agent/src/tools/read.ts       |  26 ++-
 packages/coding-agent/src/tools/search.ts     |  21 +-
 packages/coding-agent/src/tools/write.ts      |  30 ++-
 .../test/tools/read-link-probe.test.ts        |  65 -------
 .../test/tools/tool-output-hyperlinks.test.ts | 182 ++++++++++++++++++
 11 files changed, 280 insertions(+), 106 deletions(-)
 delete mode 100644 packages/coding-agent/test/tools/read-link-probe.test.ts
 create mode 100644 packages/coding-agent/test/tools/tool-output-hyperlinks.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 377ac3606..f859113b1 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -21,6 +21,7 @@
 
 ### Fixed
 
+- Fixed tool-output file paths not being clickable OSC 8 `file://` hyperlinks in several renderers. `read` titles for plain text and image files (the common case) emitted no link at all because the renderer only linked when a `resolvedPath` was recorded — which the ordinary file/image read paths never set, keeping the absolute path only in `meta.source`; the renderer now falls back to that source path. `write` headers were never wrapped in a hyperlink and now link to the absolute path written (file, archive entry, SQLite, and conflict resolutions). `edit`/`apply_patch` headers wrapped the model-supplied (often cwd-relative) argument path, producing a root-anchored `file:///rel/path` URI; they now link the absolute `details.path` instead. Finally, `search`, `ast_grep`, and `ast_edit` produced doubled link targets (`/proj/src/src/file.ts`) for searches scoped to a subdirectory, because the renderer resolved the cwd-relative display paths against the scope directory rather than cwd — the scoped-search base is now the session cwd (with the scoped file's absolute path still seeding single-file body lines).
 - Fixed `omp dry-balance --bench` to recover from 401 token failures by re-minting the failing OAuth credential in place before switching accounts
 - Fixed the bash tool corrupting commands that embed multi-byte UTF-8 (e.g. `✓`/`×` inside a `grep -E` pattern) ahead of a trailing `| head`/`| tail`. The `bash.stripTrailingHeadTail` rewrite cut at char-offset positions reported by `brush-parser` while slicing the command by byte offset, so the trailing-pipe strip landed mid-pattern and dropped the closing quote — turning `… |✓|×|XCTAssert" | tail -80` into `… |✓|×-80` and making execution fail with `pi-natives:command: unterminated double quote`. Fixed in `pi_shell::fixup` (`@oh-my-pi/pi-natives`).
 - Fixed `omp dry-balance --bench` to recover from 401 token failures by re-minting the failing OAuth credential in place before switching accounts
diff --git a/packages/coding-agent/src/edit/renderer.ts b/packages/coding-agent/src/edit/renderer.ts
index 6f880249a..0ad9cb82d 100644
--- a/packages/coding-agent/src/edit/renderer.ts
+++ b/packages/coding-agent/src/edit/renderer.ts
@@ -185,10 +185,14 @@ function getOperationTitle(op: Operation | undefined): string {
 function formatEditPathDisplay(
 	rawPath: string,
 	uiTheme: Theme,
-	options?: { rename?: string; firstChangedLine?: number },
+	options?: { rename?: string; firstChangedLine?: number; linkPath?: string; renameLinkPath?: string },
 ): string {
+	// `rawPath`/`rename` are shown (cwd-relative) but the OSC 8 link targets the
+	// absolute path when known — a relative `rawPath` would yield a `file:///rel`
+	// URI that resolves against filesystem root instead of cwd.
+	const linkTarget = options?.linkPath || rawPath;
 	let pathDisplay = rawPath
-		? fileHyperlink(rawPath, uiTheme.fg("accent", shortenPath(rawPath)))
+		? fileHyperlink(linkTarget, uiTheme.fg("accent", shortenPath(rawPath)))
 		: uiTheme.fg("toolOutput", "…");
 
 	if (options?.firstChangedLine) {
@@ -196,7 +200,8 @@ function formatEditPathDisplay(
 	}
 
 	if (options?.rename) {
-		pathDisplay += ` ${uiTheme.fg("dim", "→")} ${fileHyperlink(options.rename, uiTheme.fg("accent", shortenPath(options.rename)))}`;
+		const renameTarget = options.renameLinkPath || options.rename;
+		pathDisplay += ` ${uiTheme.fg("dim", "→")} ${fileHyperlink(renameTarget, uiTheme.fg("accent", shortenPath(options.rename)))}`;
 	}
 
 	return pathDisplay;
@@ -205,7 +210,7 @@ function formatEditPathDisplay(
 function formatEditDescription(
 	rawPath: string,
 	uiTheme: Theme,
-	options?: { rename?: string; firstChangedLine?: number },
+	options?: { rename?: string; firstChangedLine?: number; linkPath?: string; renameLinkPath?: string },
 ): { language: string; description: string } {
 	const language = getLanguageFromPath(rawPath) ?? "text";
 	const icon = uiTheme.fg("muted", uiTheme.getLangIcon(language));
@@ -539,7 +544,8 @@ function renderSingleFileResult(
 		const firstChangedLine =
 			(editDiffPreview && "firstChangedLine" in editDiffPreview ? editDiffPreview.firstChangedLine : undefined) ||
 			(details && !isError ? details.firstChangedLine : undefined);
-		const { description } = formatEditDescription(rawPath, uiTheme, { rename, firstChangedLine });
+		const linkPath = details && "path" in details ? details.path : undefined;
+		const { description } = formatEditDescription(rawPath, uiTheme, { rename, firstChangedLine, linkPath });
 
 		// Change stats ride inline on the header bar next to the path.
 		const previewDiff = editDiffPreview && !("error" in editDiffPreview) ? editDiffPreview.diff : undefined;
diff --git a/packages/coding-agent/src/modes/utils/ui-helpers.ts b/packages/coding-agent/src/modes/utils/ui-helpers.ts
index 140a43d4b..ba8f8069c 100644
--- a/packages/coding-agent/src/modes/utils/ui-helpers.ts
+++ b/packages/coding-agent/src/modes/utils/ui-helpers.ts
@@ -74,9 +74,6 @@ export class UiHelpers {
 	 * we update the previous status line instead of appending new ones to avoid log spam.
 	 */
 	showStatus(message: string, options?: { dim?: boolean }): void {
-		if (this.ctx.isBackgrounded) {
-			return;
-		}
 		const children = this.ctx.chatContainer.children;
 		const last = children.length > 0 ? children[children.length - 1] : undefined;
 		const secondLast = children.length > 1 ? children[children.length - 2] : undefined;
@@ -534,9 +531,6 @@ export class UiHelpers {
 	}
 
 	clearEditor(): void {
-		if (this.ctx.isBackgrounded) {
-			return;
-		}
 		this.ctx.editor.setText("");
 		this.ctx.pendingImages = [];
 		this.ctx.pendingImageLinks = [];
@@ -545,18 +539,10 @@ export class UiHelpers {
 	}
 
 	showError(errorMessage: string): void {
-		if (this.ctx.isBackgrounded) {
-			process.stderr.write(`Error: ${errorMessage}\n`);
-			return;
-		}
 		this.ctx.present([new Spacer(1), new Text(theme.fg("error", `Error: ${errorMessage}`), 1, 0)]);
 	}
 
 	showWarning(warningMessage: string): void {
-		if (this.ctx.isBackgrounded) {
-			process.stderr.write(`Warning: ${warningMessage}\n`);
-			return;
-		}
 		this.ctx.present([new Spacer(1), new Text(theme.fg("warning", `Warning: ${warningMessage}`), 1, 0)]);
 	}
 
diff --git a/packages/coding-agent/src/tools/ast-edit.ts b/packages/coding-agent/src/tools/ast-edit.ts
index c9f8bd530..eac7b6e92 100644
--- a/packages/coding-agent/src/tools/ast-edit.ts
+++ b/packages/coding-agent/src/tools/ast-edit.ts
@@ -159,6 +159,9 @@ export interface AstEditToolDetails {
 	/** Absolute base directory used during the edit. Used by the renderer to resolve
 	 * display-relative paths to absolute paths for OSC 8 hyperlinks. */
 	searchPath?: string;
+	/** Session cwd at edit time. Display header paths are cwd-relative, so the
+	 * renderer resolves them against this; `searchPath` is the scope target. */
+	cwd?: string;
 }
 
 export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolDetails> {
@@ -272,6 +275,7 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 				...(cappedParseErrors.length > 0 ? { parseErrors: cappedParseErrors, parseErrorsTotal } : {}),
 				scopePath,
 				searchPath: resolvedSearchPath,
+				cwd: this.session.cwd,
 				files: fileList,
 				fileReplacements: [],
 			};
@@ -560,7 +564,7 @@ export const astEditToolRenderer = {
 		const allLines = textContent.split("\n");
 		// Resolve hyperlinks over the whole output so nested directory headers
 		// reconstruct across the blank-line groups the tree list collapses by.
-		const contexts = classifyGroupedLines(allLines, details?.searchPath);
+		const contexts = classifyGroupedLines(allLines, details?.cwd ?? details?.searchPath, details?.searchPath);
 		const styledLines = allLines.map((line, index) => {
 			const ctx = contexts[index]!;
 			// Swap the inner code-frame gutter `│` for a space so it does not nest a
diff --git a/packages/coding-agent/src/tools/ast-grep.ts b/packages/coding-agent/src/tools/ast-grep.ts
index 9f2124240..364397035 100644
--- a/packages/coding-agent/src/tools/ast-grep.ts
+++ b/packages/coding-agent/src/tools/ast-grep.ts
@@ -117,6 +117,9 @@ export interface AstGrepToolDetails {
 	/** Absolute base directory used during search. Used by the renderer to resolve
 	 * display-relative paths to absolute paths for OSC 8 hyperlinks. */
 	searchPath?: string;
+	/** Session cwd at search time. Display header/match paths are cwd-relative, so
+	 * the renderer resolves them against this; `searchPath` is the scope target. */
+	cwd?: string;
 }
 
 export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolDetails> {
@@ -206,6 +209,7 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 				...(cappedParseErrors.length > 0 ? { parseErrors: cappedParseErrors, parseErrorsTotal } : {}),
 				scopePath,
 				searchPath: resolvedSearchPath,
+				cwd: this.session.cwd,
 				files: fileList,
 				fileMatches: [],
 			};
@@ -395,7 +399,7 @@ export const astGrepToolRenderer = {
 		const allLines = textContent.split("\n");
 		// Resolve hyperlinks over the whole output so nested directory headers
 		// reconstruct across the blank-line groups the tree list collapses by.
-		const contexts = classifyGroupedLines(allLines, details?.searchPath);
+		const contexts = classifyGroupedLines(allLines, details?.cwd ?? details?.searchPath, details?.searchPath);
 		const styledLines = allLines.map((line, index) => {
 			const ctx = contexts[index]!;
 			if (ctx.kind === "dir") {
diff --git a/packages/coding-agent/src/tools/grouped-file-output.ts b/packages/coding-agent/src/tools/grouped-file-output.ts
index 174c0772a..3027693a1 100644
--- a/packages/coding-agent/src/tools/grouped-file-output.ts
+++ b/packages/coding-agent/src/tools/grouped-file-output.ts
@@ -237,12 +237,23 @@ function resolveGroupedPath(parent: string | undefined, name: string): string |
  * each header and body line can be linked back to its absolute filesystem path.
  * Reconstruction is stack-based (not per-blank-group) so nested directory headers
  * resolve correctly across the whole output.
+ *
+ * `headerBase` is the directory the displayed (folded) header paths are relative
+ * to — for grep/ast tools that is the session cwd, since display paths are
+ * formatted relative to cwd regardless of the (sub)directory the search was
+ * scoped to. `fileScope` is the initial owning file for body lines that appear
+ * before any header (single-file scopes have no `#` headers); it defaults to
+ * `headerBase` and should be passed the scoped file's absolute path.
  */
-export function classifyGroupedLines(lines: readonly string[], searchBase: string | undefined): GroupedLineContext[] {
+export function classifyGroupedLines(
+	lines: readonly string[],
+	headerBase: string | undefined,
+	fileScope: string | undefined = headerBase,
+): GroupedLineContext[] {
 	const result: GroupedLineContext[] = [];
 	const dirAtDepth = new Map<number, string>();
-	// Body lines before any header (single-file scopes) link to the search root.
-	let currentFile = searchBase;
+	// Body lines before any header (single-file scopes) link to the scoped file.
+	let currentFile = fileScope;
 
 	const clearDeeper = (depth: number) => {
 		for (const key of dirAtDepth.keys()) {
@@ -264,7 +275,7 @@ export function classifyGroupedLines(lines: readonly string[], searchBase: strin
 			result.push({ kind: "file", depth, isUrl: true });
 			continue;
 		}
-		const parent = depth > 1 ? dirAtDepth.get(depth - 1) : searchBase;
+		const parent = depth > 1 ? dirAtDepth.get(depth - 1) : headerBase;
 		if (rest.endsWith("/")) {
 			const name = rest.slice(0, -1).replace(HEADER_SUFFIX_RE, "");
 			const abs = resolveGroupedPath(parent, name);
diff --git a/packages/coding-agent/src/tools/read.ts b/packages/coding-agent/src/tools/read.ts
index 0ab70e42a..48df2758b 100644
--- a/packages/coding-agent/src/tools/read.ts
+++ b/packages/coding-agent/src/tools/read.ts
@@ -2337,10 +2337,20 @@ function firstReadSelectorLine(sel: string | undefined): number | undefined {
 	}
 }
 
+/** Absolute fs path the read result actually resolved to, used as the OSC 8 link
+ * target when the structured `resolvedPath` isn't set (the common plain-file and
+ * image reads only record the path in `meta.source`). URL/internal sources are
+ * not fs paths, so only `type: "path"` qualifies. */
+function readSourceFsPath(details: ReadToolDetails | undefined): string | undefined {
+	const source = details?.meta?.source;
+	return source?.type === "path" ? source.value : undefined;
+}
+
 function formatReadPathLink(
 	rawPath: string,
 	options: {
 		resolvedPath?: string;
+		sourcePath?: string;
 		suffixResolution?: { from: string; to: string };
 		offset?: number;
 		fallbackLabel?: string;
@@ -2352,7 +2362,7 @@ function formatReadPathLink(
 	const plainDisplayPath = options.suffixResolution
 		? shortenPath(options.suffixResolution.to)
 		: shortenPath(basePath || options.resolvedPath || options.fallbackLabel || rawPath);
-	const target = options.resolvedPath ?? tryResolveInternalUrlSync(basePath);
+	const target = options.resolvedPath ?? options.sourcePath ?? tryResolveInternalUrlSync(basePath);
 	const line = firstReadSelectorLine(split.sel) ?? options.offset;
 	const linkOptions = line !== undefined ? { line } : undefined;
 	const displayPath = target ? fileHyperlink(target, plainDisplayPath, linkOptions) : plainDisplayPath;
@@ -2403,7 +2413,9 @@ export const readToolRenderer = {
 			const rawErrorText = result.content?.find(c => c.type === "text")?.text ?? "";
 			const errorText = (rawErrorText || "Unknown error").replace(/^Error:\s*/, "");
 			const rawPath = args?.file_path || args?.path || "";
-			const filePath = formatReadPathLink(rawPath, { offset: args?.offset }) || shortenPath(rawPath);
+			const filePath =
+				formatReadPathLink(rawPath, { offset: args?.offset, sourcePath: readSourceFsPath(result.details) }) ||
+				shortenPath(rawPath);
 			let title = filePath ? `Read ${filePath}` : "Read";
 			if (args?.offset !== undefined || args?.limit !== undefined) {
 				const startLine = args.offset ?? 1;
@@ -2454,6 +2466,7 @@ export const readToolRenderer = {
 			const suffix = details?.suffixResolution;
 			const displayPath = formatReadPathLink(rawPath, {
 				resolvedPath: details?.resolvedPath,
+				sourcePath: readSourceFsPath(details),
 				suffixResolution: suffix,
 				fallbackLabel: "image",
 			});
@@ -2486,12 +2499,13 @@ export const readToolRenderer = {
 		}
 
 		const suffix = details?.suffixResolution;
-		// resolvedPath is the absolute fs path for fs-backed reads (regular files plus
-		// local:// / memory:// / skill:// / artifact:// resources). Fall back to a sync
-		// resolver for fs-backed internal URLs so the title is clickable even before the
-		// result lands or if the handler didn't populate resolvedPath.
+		// resolvedPath is the absolute fs path when a read resolved/corrected the
+		// input (suffix match, internal URL, archive/sqlite/notebook); plain file
+		// reads only record the absolute path in meta.source, so fall back to that
+		// (and then to a sync internal-URL resolver) to keep the title clickable.
 		const displayPath = formatReadPathLink(rawPath, {
 			resolvedPath: details?.resolvedPath,
+			sourcePath: readSourceFsPath(details),
 			suffixResolution: suffix,
 			offset: args?.offset,
 		});
diff --git a/packages/coding-agent/src/tools/search.ts b/packages/coding-agent/src/tools/search.ts
index 56d99ada8..b5e4431ce 100644
--- a/packages/coding-agent/src/tools/search.ts
+++ b/packages/coding-agent/src/tools/search.ts
@@ -621,6 +621,10 @@ export interface SearchToolDetails {
 	/** Absolute base directory used during search. Used by the renderer to resolve
 	 * display-relative paths to absolute paths for OSC 8 hyperlinks. */
 	searchPath?: string;
+	/** Session cwd at search time. The renderer resolves the display-relative
+	 * (cwd-relative) header/match paths against this for OSC 8 hyperlinks;
+	 * `searchPath` is the scope label target, not the display-path base. */
+	cwd?: string;
 	/** User-supplied paths whose base directory was missing on disk. The tool
 	 * skipped these and continued with the surviving entries; surfaced as a
 	 * non-fatal warning in the renderer and in the model-facing text. */
@@ -1003,6 +1007,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 					const details: SearchToolDetails = {
 						scopePath,
 						searchPath,
+						cwd: this.session.cwd,
 						matchCount: 0,
 						fileCount: 0,
 						files: [],
@@ -1129,6 +1134,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 				const details: SearchToolDetails = {
 					scopePath,
 					searchPath,
+					cwd: this.session.cwd,
 					matchCount: selectedMatches.length,
 					fileCount: fileList.length,
 					files: fileList,
@@ -1215,10 +1221,11 @@ const URL_HEADER_PREFIX_RE = /^#+\s+/;
 
 function renderSearchDisplayLines(
 	lines: readonly string[],
-	searchBase: string | undefined,
+	headerBase: string | undefined,
+	fileScope: string | undefined,
 	uiTheme: Theme,
 ): RenderedSearchLine[] {
-	const contexts = classifyGroupedLines(lines, searchBase);
+	const contexts = classifyGroupedLines(lines, headerBase, fileScope);
 	// `classifyGroupedLines` can't resolve internal URLs (TUI-only), so track the
 	// resolved URL target here and use it for the body lines that follow.
 	let urlFile: string | undefined;
@@ -1439,7 +1446,15 @@ export const searchToolRenderer = {
 		const allLines = textContent.split("\n");
 		// Resolve hyperlinks once over the whole output so a nested directory stack
 		// reconstructs correctly across blank-line group boundaries.
-		const renderedLines = renderSearchDisplayLines(allLines, details?.searchPath, uiTheme);
+		// Header/match display paths are cwd-relative, so resolve them against cwd
+		// (falling back to searchPath for legacy results that predate `cwd`); the
+		// scoped file's absolute path seeds body lines in single-file searches.
+		const renderedLines = renderSearchDisplayLines(
+			allLines,
+			details?.cwd ?? details?.searchPath,
+			details?.searchPath,
+			uiTheme,
+		);
 		const matchGroups = groupLineIndicesByBlank(allLines).map(indices => indices.map(i => renderedLines[i]!));
 
 		const extraLines: string[] = [];
diff --git a/packages/coding-agent/src/tools/write.ts b/packages/coding-agent/src/tools/write.ts
index e39e75533..2a401d8af 100644
--- a/packages/coding-agent/src/tools/write.ts
+++ b/packages/coding-agent/src/tools/write.ts
@@ -18,7 +18,7 @@ import { getDiagnosticsLedger } from "../lsp/diagnostics-ledger";
 import { getLanguageFromPath, highlightCode, type Theme } from "../modes/theme/theme";
 import writeDescription from "../prompts/tools/write.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
-import { framedBlock, renderStatusLine } from "../tui";
+import { fileHyperlink, framedBlock, renderStatusLine } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { truncateForPrompt } from "./approval";
 import { parseArchivePathCandidates } from "./archive-reader";
@@ -77,6 +77,9 @@ export interface WriteToolDetails {
 	meta?: OutputMeta;
 	/** Set when the file was auto-chmod'd because content begins with a `#!` shebang. */
 	madeExecutable?: boolean;
+	/** Absolute filesystem path the write resolved to. Used by the renderer to wrap
+	 * the (possibly cwd-relative) header path in an OSC 8 `file://` hyperlink. */
+	resolvedPath?: string;
 }
 
 /**
@@ -416,7 +419,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 		}`;
 		return {
 			content: [{ type: "text", text: `Successfully wrote ${content.length} bytes to ${outputPath}` }],
-			details: {},
+			details: { resolvedPath: resolvedArchivePath.absolutePath },
 		};
 	}
 
@@ -532,7 +535,10 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			}
 
 			invalidateFsScanAfterWrite(resolvedSqlitePath.absolutePath);
-			return toolResult<WriteToolDetails>({}).text(resultText).sourcePath(resolvedSqlitePath.absolutePath).done();
+			return toolResult<WriteToolDetails>({ resolvedPath: resolvedSqlitePath.absolutePath })
+				.text(resultText)
+				.sourcePath(resolvedSqlitePath.absolutePath)
+				.done();
 		} catch (error) {
 			if (isEnoent(error)) {
 				throw new ToolError(`SQLite database '${displayPath}' not found`);
@@ -593,12 +599,13 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 		if (!diagnostics) {
 			return {
 				content: [{ type: "text", text: resultText }],
-				details: {},
+				details: { resolvedPath: absolutePath },
 			};
 		}
 		return {
 			content: [{ type: "text", text: resultText }],
 			details: {
+				resolvedPath: absolutePath,
 				diagnostics,
 				meta: outputMeta()
 					.diagnostics(diagnostics.summary, diagnostics.messages ?? [])
@@ -871,7 +878,10 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				if (stripped) {
 					resultText += `\nNote: auto-stripped hashline display prefixes from content before writing.`;
 				}
-				return { content: [{ type: "text", text: resultText }], details: {} };
+				return {
+					content: [{ type: "text", text: resultText }],
+					details: { resolvedPath: absolutePath },
+				};
 			}
 
 			const diagnostics = await this.#writethrough(absolutePath, cleanContent, signal, undefined, batchRequest);
@@ -888,13 +898,14 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			if (!diagnostics) {
 				return {
 					content: [{ type: "text", text: resultText }],
-					details: { madeExecutable: madeExecutable || undefined },
+					details: { resolvedPath: absolutePath, madeExecutable: madeExecutable || undefined },
 				};
 			}
 
 			return {
 				content: [{ type: "text", text: resultText }],
 				details: {
+					resolvedPath: absolutePath,
 					diagnostics,
 					madeExecutable: madeExecutable || undefined,
 					meta: outputMeta()
@@ -1050,7 +1061,12 @@ export const writeToolRenderer = {
 		const fileContent = args?.content || "";
 		const lang = getLanguageFromPath(rawPath);
 		const langIcon = uiTheme.fg("muted", uiTheme.getLangIcon(lang));
-		const pathDisplay = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
+		// The header shows the cwd-relative path but links to the absolute path the
+		// write resolved to (args.path may be relative, which would yield a broken
+		// `file://` URI). Falls back to plain text when the result lacks a path.
+		const linkTarget = result.details?.resolvedPath;
+		const styledPath = filePath ? uiTheme.fg("accent", filePath) : uiTheme.fg("toolOutput", "…");
+		const pathDisplay = filePath && linkTarget ? fileHyperlink(linkTarget, styledPath) : styledPath;
 
 		if (result.isError) {
 			const errorText = result.content?.find(c => c.type === "text")?.text ?? "";
diff --git a/packages/coding-agent/test/tools/read-link-probe.test.ts b/packages/coding-agent/test/tools/read-link-probe.test.ts
deleted file mode 100644
index 6b4bc2847..000000000
--- a/packages/coding-agent/test/tools/read-link-probe.test.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import { describe, it } from "bun:test";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { resetSettingsForTest, Settings, settings } from "@oh-my-pi/pi-coding-agent/config/settings";
-import type { ToolSession } from "@oh-my-pi/pi-coding-agent/tools";
-import { ReadTool } from "@oh-my-pi/pi-coding-agent/tools/read";
-import { getThemeByName, initTheme } from "../../src/modes/theme/theme";
-import { readToolRenderer } from "../../src/tools/read";
-
-const TINY_PNG_BASE64 =
-	"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==";
-
-function extractLinkUris(text: string): string[] {
-	return [...text.matchAll(/\x1b\]8;[^;]*;([^\x1b]+)\x1b\\/g)].map(match => match[1]!);
-}
-
-function createTestToolSession(cwd: string): ToolSession {
-	return {
-		cwd,
-		hasUI: false,
-		getSessionFile: () => null,
-		getSessionSpawns: () => "*",
-		settings: Settings.isolated(),
-	};
-}
-
-describe("probe real read render", () => {
-	it("text and image link emission", async () => {
-		await initTheme();
-		resetSettingsForTest();
-		await Settings.init({ inMemory: true });
-		settings.override("tui.hyperlinks", "always");
-		const theme = await getThemeByName("dark");
-
-		const testDir = fs.mkdtempSync(path.join(os.tmpdir(), "probe-"));
-		const textPath = path.join(testDir, "v4-task.txt");
-		fs.writeFileSync(textPath, "hello world\nsecond line\n");
-		const imgPath = path.join(testDir, "v4-task.png");
-		fs.writeFileSync(imgPath, Buffer.from(TINY_PNG_BASE64, "base64"));
-
-		const tool = new ReadTool(createTestToolSession(testDir));
-		const textRes = await tool.execute("t", { path: textPath });
-		const imgRes = await tool.execute("i", { path: imgPath });
-
-		const textComp = readToolRenderer.renderResult(
-			{ content: textRes.content, details: textRes.details, isError: textRes.isError },
-			{ expanded: false, isPartial: false },
-			theme!,
-			{ path: textPath },
-		);
-		const imgComp = readToolRenderer.renderResult(
-			{ content: imgRes.content, details: imgRes.details, isError: imgRes.isError },
-			{ expanded: false, isPartial: false },
-			theme!,
-			{ path: imgPath },
-		);
-		console.log("TEXT URIS:", JSON.stringify(extractLinkUris(textComp.render(200).join("\n"))));
-		console.log("IMAGE URIS:", JSON.stringify(extractLinkUris(imgComp.render(200).join("\n"))));
-
-		settings.clearOverride("tui.hyperlinks");
-		resetSettingsForTest();
-		fs.rmSync(testDir, { recursive: true, force: true });
-	});
-});
diff --git a/packages/coding-agent/test/tools/tool-output-hyperlinks.test.ts b/packages/coding-agent/test/tools/tool-output-hyperlinks.test.ts
new file mode 100644
index 000000000..c631385f9
--- /dev/null
+++ b/packages/coding-agent/test/tools/tool-output-hyperlinks.test.ts
@@ -0,0 +1,182 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { resetSettingsForTest, Settings, settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import type { ToolSession } from "@oh-my-pi/pi-coding-agent/tools";
+import { astGrepToolRenderer } from "@oh-my-pi/pi-coding-agent/tools/ast-grep";
+import { ReadTool, readToolRenderer } from "@oh-my-pi/pi-coding-agent/tools/read";
+import { searchToolRenderer } from "@oh-my-pi/pi-coding-agent/tools/search";
+import { WriteTool, writeToolRenderer } from "@oh-my-pi/pi-coding-agent/tools/write";
+import { editToolRenderer } from "@oh-my-pi/pi-coding-agent/edit/renderer";
+import { getThemeByName, initTheme } from "../../src/modes/theme/theme";
+
+// 1x1 PNG so the read tool takes its image branch.
+const TINY_PNG_BASE64 =
+	"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==";
+
+function extractLinkUris(text: string): string[] {
+	return [...text.matchAll(/\x1b\]8;[^;]*;([^\x1b]+)\x1b\\/g)].map(match => match[1]!);
+}
+
+function createTestToolSession(cwd: string): ToolSession {
+	return {
+		cwd,
+		hasUI: false,
+		getSessionFile: () => null,
+		getSessionSpawns: () => "*",
+		settings: Settings.isolated(),
+	};
+}
+
+beforeAll(async () => {
+	await initTheme(false);
+	resetSettingsForTest();
+	await Settings.init({ inMemory: true });
+});
+
+afterEach(() => {
+	settings.clearOverride("tui.hyperlinks");
+});
+
+afterAll(() => {
+	resetSettingsForTest();
+});
+
+describe("tool output OSC 8 file:// hyperlinks", () => {
+	it("links plain text and image read titles to the resolved filesystem path", async () => {
+		settings.override("tui.hyperlinks", "always");
+		const theme = (await getThemeByName("dark"))!;
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "omp-link-read-"));
+		try {
+			const textPath = path.join(dir, "task.txt");
+			fs.writeFileSync(textPath, "hello\nworld\n");
+			const imgPath = path.join(dir, "task.png");
+			fs.writeFileSync(imgPath, Buffer.from(TINY_PNG_BASE64, "base64"));
+
+			const tool = new ReadTool(createTestToolSession(dir));
+			const textRes = await tool.execute("t", { path: textPath });
+			const imgRes = await tool.execute("i", { path: imgPath });
+
+			const textRender = readToolRenderer
+				.renderResult(
+					{ content: textRes.content, details: textRes.details, isError: textRes.isError },
+					{ expanded: false, isPartial: false },
+					theme,
+					{ path: textPath },
+				)
+				.render(200)
+				.join("\n");
+			const imgRender = readToolRenderer
+				.renderResult(
+					{ content: imgRes.content, details: imgRes.details, isError: imgRes.isError },
+					{ expanded: false, isPartial: false },
+					theme,
+					{ path: imgPath },
+				)
+				.render(200)
+				.join("\n");
+
+			expect(extractLinkUris(textRender)).toContain(`file://${textPath}`);
+			expect(extractLinkUris(imgRender)).toContain(`file://${imgPath}`);
+		} finally {
+			fs.rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("links the write header to the absolute path it wrote", async () => {
+		settings.override("tui.hyperlinks", "always");
+		const theme = (await getThemeByName("dark"))!;
+		const dir = fs.mkdtempSync(path.join(os.tmpdir(), "omp-link-write-"));
+		try {
+			const filePath = path.join(dir, "out.ts");
+			const tool = new WriteTool(createTestToolSession(dir));
+			const res = await tool.execute("w", { path: filePath, content: "export const x = 1;\n" });
+			const rendered = writeToolRenderer
+				.renderResult(
+					{ content: res.content, details: res.details, isError: res.isError },
+					{ expanded: false, isPartial: false },
+					theme,
+					{ path: filePath },
+				)
+				.render(200)
+				.join("\n");
+			expect(extractLinkUris(rendered)).toContain(`file://${filePath}`);
+		} finally {
+			fs.rmSync(dir, { recursive: true, force: true });
+		}
+	});
+
+	it("resolves scoped search links against cwd, not the (sub)scope path", async () => {
+		settings.override("tui.hyperlinks", "always");
+		const theme = (await getThemeByName("dark"))!;
+		// Scoped search: scope dir (`searchPath`) is below cwd, and the grouped
+		// display paths are cwd-relative. Resolving against searchPath would double
+		// the `src` prefix (`/proj/src/src/...`).
+		const result = {
+			content: [{ type: "text", text: "" }],
+			details: {
+				matchCount: 1,
+				fileCount: 1,
+				cwd: "/tmp/omp-project",
+				searchPath: "/tmp/omp-project/src",
+				scopePath: "src",
+				displayContent: ["# src/", "## interactive-mode.ts#abcd", "*12│const needle = true;"].join("\n"),
+			},
+		};
+		const rendered = searchToolRenderer
+			.renderResult(result as never, { expanded: true, isPartial: false }, theme, { pattern: "needle" })
+			.render(240)
+			.join("\n");
+		const uris = extractLinkUris(rendered);
+		expect(uris).toContain("file:///tmp/omp-project/src/interactive-mode.ts");
+		expect(uris).toContain("file:///tmp/omp-project/src/interactive-mode.ts?line=12");
+		expect(uris.some(uri => uri.includes("/src/src/"))).toBe(false);
+	});
+
+	it("resolves scoped ast-grep links against cwd, not the (sub)scope path", async () => {
+		settings.override("tui.hyperlinks", "always");
+		const theme = (await getThemeByName("dark"))!;
+		const result = {
+			content: [{ type: "text", text: "" }],
+			details: {
+				matchCount: 1,
+				fileCount: 1,
+				filesSearched: 1,
+				limitReached: false,
+				cwd: "/tmp/omp-project",
+				searchPath: "/tmp/omp-project/src",
+				scopePath: "src",
+				displayContent: ["# src/", "## interactive-mode.ts", "  *12│const needle = true;"].join("\n"),
+			},
+		};
+		const rendered = astGrepToolRenderer
+			.renderResult(result as never, { expanded: true, isPartial: false }, theme, { pat: "needle" })
+			.render(240)
+			.join("\n");
+		const uris = extractLinkUris(rendered);
+		expect(uris).toContain("file:///tmp/omp-project/src/interactive-mode.ts");
+		expect(uris.some(uri => uri.includes("/src/src/"))).toBe(false);
+	});
+
+	it("links the edit header to the absolute details.path even when the arg path is relative", async () => {
+		settings.override("tui.hyperlinks", "always");
+		const theme = (await getThemeByName("dark"))!;
+		const rendered = editToolRenderer
+			.renderResult(
+				{
+					content: [{ type: "text", text: "Updated src/a.ts" }],
+					details: { diff: "+1|// x", op: "update", path: "/tmp/omp-project/src/a.ts" },
+				},
+				{ expanded: false, isPartial: false, renderContext: { editMode: "hashline" } },
+				theme,
+				{ path: "src/a.ts" },
+			)
+			.render(200)
+			.join("\n");
+		const uris = extractLinkUris(rendered);
+		expect(uris).toContain("file:///tmp/omp-project/src/a.ts");
+		// A relative arg path must not leak into a root-anchored `file:///src/a.ts`.
+		expect(uris).not.toContain("file:///src/a.ts");
+	});
+});

From 741558a6d477db404e4a6086a1e40288833d2988 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:30:53 +0200
Subject: [PATCH 098/181] feat(coding-agent): removed background mode command
 and runtime plumbing

- Removed the built-in `background` (`bg`) slash command and its `handleBackgroundCommand` path from the interactive flow.
- Deleted background event subscription and shutdown handling by removing `handleBackgroundEvent` from the event, input, and interactive controllers.
- Simplified `InteractiveModeContext` by dropping background-only fields and helpers such as `isBackgrounded`, background UI context creation, and background event callbacks.
---
 docs/tui-runtime-internals.md                 | 12 ----
 packages/coding-agent/CHANGELOG.md            |  5 ++
 packages/coding-agent/src/cli/gallery-cli.ts  |  5 +-
 .../src/cli/gallery-fixtures/misc.ts          | 29 +++++++++
 .../src/modes/controllers/event-controller.ts | 12 ----
 .../controllers/extension-ui-controller.ts    | 65 +------------------
 .../src/modes/controllers/input-controller.ts | 65 +------------------
 .../src/modes/interactive-mode.ts             | 14 ----
 packages/coding-agent/src/modes/types.ts      |  8 +--
 .../src/slash-commands/builtin-registry.ts    |  9 ---
 .../coding-agent/src/slash-commands/types.ts  | 10 ++-
 .../test/input-controller-skill-queue.test.ts |  1 -
 .../test/interactive-mode-status.test.ts      |  3 -
 packages/coding-agent/test/loop-limit.test.ts |  1 -
 .../event-controller-abort-guard.test.ts      | 24 ++-----
 .../event-controller-idle-compaction.test.ts  |  1 -
 .../event-controller-tool-render-mode.test.ts |  2 +-
 .../test/slash-commands/btw.test.ts           |  1 -
 .../test/slash-commands/force.test.ts         |  1 -
 .../test/slash-commands/fresh.test.ts         |  1 -
 .../test/slash-commands/login.test.ts         |  3 +-
 .../test/slash-commands/omfg.test.ts          |  1 -
 .../test/slash-commands/plan-history.test.ts  |  4 +-
 .../test/slash-commands/retry.test.ts         |  1 -
 .../test/slash-commands/session.test.ts       |  1 -
 .../test/slash-commands/shake.test.ts         |  1 -
 .../test/slash-commands/switch.test.ts        |  3 -
 27 files changed, 56 insertions(+), 227 deletions(-)

diff --git a/docs/tui-runtime-internals.md b/docs/tui-runtime-internals.md
index 20beca245..79df9186d 100644
--- a/docs/tui-runtime-internals.md
+++ b/docs/tui-runtime-internals.md
@@ -199,18 +199,6 @@ Escape exits inactive mode by clearing editor text and restoring border color; w
 2. Stops TUI before suspend.
 3. Sends `SIGTSTP` to process group.
 
-### Background mode (`/background` or `/bg`)
-
-`handleBackgroundCommand()`:
-
-- Rejects when idle.
-- Switches tool UI context to non-interactive (`hasUI=false`) so interactive UI tools fail fast.
-- Stops loaders/status line and unsubscribes foreground event handler.
-- Subscribes background event handler (primarily waits for `agent_end`).
-- Stops TUI and sends `SIGTSTP` (POSIX job control path).
-
-On `agent_end` in background with no queued work, controller sends completion notification and shuts down.
-
 ## Cancellation paths
 
 Primary cancellation inputs:
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index f859113b1..5f61b9cac 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -18,6 +18,7 @@
 - Changed the interactive controllers (command, MCP, selector, extension-UI, event), debug panels, and the status/error/warning helpers to render chat output through `ctx.present(...)` instead of appending to `chatContainer` and calling `ui.requestRender()` directly; transcript rebuilds dispose live blocks via `ctx.resetTranscript()` so animated blocks' timers stop on reset.
 - Changed tool-execution block rendering so the container (`ToolExecutionComponent`) is a transparent passthrough — it no longer inserts a top/bottom blank line, adds left/right padding, or paints a state-colored background behind tool output. Tools with substantial body now self-frame with a muted outline and the tool title in the frame's top bar (`edit`/`apply_patch`, `write`, `ask`, `todo`, `github`, `goal`, `inspect_image`, `search_tool_bm25`, `task`), matching the already-framed `bash`/`read`/`eval`/`debug`/`web_search`/`lsp` blocks, while streaming/in-progress and trivial results collapse to a clean status line. The search-family list tools (`find`, `search`, `ast_grep`) and `job` render frameless/minimal; `find`/`search`/`ast_grep` show a magnifier on success instead of a checkmark, and `job` drops its `Job:` label prefix (the per-job rows are self-describing). The `search_tool_bm25`, `github`, and `inspect_image` frames draw with no background fill, and `inspect_image`'s label was shortened to `Inspect`.
 - Changed the plan-mode active prompt (`prompts/system/plan-mode-active.md`) to make plans decision-complete and cut filler. Added an Objective framing ("another engineer can execute end-to-end without making a single design decision"), a shared "Resolving Unknowns" section (explore discoverable facts before asking; reserve `ask` for non-derivable preferences/tradeoffs with 2–4 options + a recommended default), and a single shared "The Plan" structure (Context / Approach grouped by behavior not file-by-file / ≤5 Critical files / Verification / Assumptions) that replaces the per-branch structure guidance previously duplicated across the iterative and parallel workflows. Added explicit prohibitions on sections that decide nothing (Non-Goals, Out of Scope, Alternatives Considered, Risks/Mitigations boilerplate, Future Work), on enumerating every file/line, and on inventing schema/validation/precedence policy the request never established.
+- Changed completion notifications (`completion.notify`) to fire whenever the agent yields its turn, including in the foreground. The `agent_end` notification was previously gated behind background mode (`isBackgrounded`), so an ordinary foreground turn never emitted one; the gate is gone and the desktop toast now fires on every normal turn completion (still skipped for aborted/error turns and when `completion.notify` is `off`).
 
 ### Fixed
 
@@ -38,6 +39,10 @@
 
 - Fixed `debug` tool refusing every `dlv` launch on Go modules. The launch handler ran `validateLaunchProgram` before adapter selection and rejected any directory program with `launch program resolves to a directory`, while dlv's default `mode=debug` requires a Go package path (a directory or `.go` source file). Adapter resolution now precedes validation, directory programs prefer adapters that advertise `acceptsDirectoryProgram` before falling back to native extensionless debuggers, the rejection only fires when the resolved adapter does not advertise that flag (set on `dlv` in `dap/defaults.json`), and dlv's `mode` is derived from the program shape — directories and `.go` files launch as `mode=debug`, other files as `mode=exec` — so `omp` can debug both Go packages and pre-built binaries ([#2020](https://github.com/can1357/oh-my-pi/issues/2020)).
 
+### Removed
+
+- Removed the `/background` (and `/bg`) slash command and the background-mode subsystem it was the sole entry point for — `InteractiveMode.isBackgrounded`, `createBackgroundUiContext`, `handleBackgroundEvent`, and every `isBackgrounded` guard across the input/event/extension-UI controllers and UI helpers. The command suspended the whole process group via `SIGTSTP` (a leftover testing shortcut) instead of detaching the running agent, which is not the expected workflow — use terminal panes or a multiplexer instead.
+
 ## [15.10.0] - 2026-06-06
 
 ### Breaking Changes
diff --git a/packages/coding-agent/src/cli/gallery-cli.ts b/packages/coding-agent/src/cli/gallery-cli.ts
index 7f52ec956..b145f04f7 100644
--- a/packages/coding-agent/src/cli/gallery-cli.ts
+++ b/packages/coding-agent/src/cli/gallery-cli.ts
@@ -196,7 +196,10 @@ export async function runGalleryCommand(args: GalleryCommandArgs): Promise<void>
 	const expanded = args.expanded ?? false;
 	const states = args.states && args.states.length > 0 ? args.states : [...GALLERY_STATES];
 
-	const allNames = Object.keys(toolRenderers).sort();
+	// Renderer-registry tools plus fixture-only tools (no dedicated renderer,
+	// e.g. `report_tool_issue` / custom extension tools) so the gallery covers
+	// the generic fallback + custom-tool branches too.
+	const allNames = Array.from(new Set([...Object.keys(toolRenderers), ...Object.keys(galleryFixtures)])).sort();
 	const names = args.tool ? allNames.filter(name => name === args.tool) : allNames;
 	if (args.tool && names.length === 0) {
 		process.stdout.write(`Unknown tool '${args.tool}'. Known tools: ${allNames.join(", ")}\n`);
diff --git a/packages/coding-agent/src/cli/gallery-fixtures/misc.ts b/packages/coding-agent/src/cli/gallery-fixtures/misc.ts
index 80200a749..4860d01f2 100644
--- a/packages/coding-agent/src/cli/gallery-fixtures/misc.ts
+++ b/packages/coding-agent/src/cli/gallery-fixtures/misc.ts
@@ -218,4 +218,33 @@ export const miscFixtures: Record<string, GalleryFixture> = {
 			},
 		},
 	},
+
+	// Built-in tool with no dedicated renderer — exercises the generic fallback
+	// (`#formatToolExecution`) path so its padded, state-tinted block is QA'd.
+	report_tool_issue: {
+		label: "Report Tool Issue",
+		streamingArgs: { tool: "lsp" },
+		args: {
+			tool: "lsp",
+			report: "Rename returned no edit for an exported symbol that has 12 references",
+		},
+		result: { content: [{ type: "text", text: "Noted, thanks!" }] },
+		errorResult: {
+			content: [{ type: "text", text: "Could not record the report: issue tracker unreachable" }],
+			isError: true,
+		},
+	},
+
+	// Stand-in for a custom/extension tool that ships no renderer — same generic
+	// fallback path most MCP/extension tools take.
+	custom: {
+		label: "Custom Tool",
+		streamingArgs: { query: "weather" },
+		args: { query: "weather in Tokyo", units: "metric" },
+		result: { content: [{ type: "text", text: "Tokyo: 22°C, partly cloudy, humidity 64%." }] },
+		errorResult: {
+			content: [{ type: "text", text: "Upstream provider returned 503 Service Unavailable" }],
+			isError: true,
+		},
+	},
 };
diff --git a/packages/coding-agent/src/modes/controllers/event-controller.ts b/packages/coding-agent/src/modes/controllers/event-controller.ts
index bdaeab4ec..3f48c6fe5 100644
--- a/packages/coding-agent/src/modes/controllers/event-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/event-controller.ts
@@ -888,7 +888,6 @@ export class EventController {
 	}
 
 	sendCompletionNotification(): void {
-		if (this.ctx.isBackgrounded === false) return;
 		const notify = settings.get("completion.notify");
 		if (notify === "off") return;
 
@@ -907,15 +906,4 @@ export class EventController {
 			actions: "focus",
 		});
 	}
-
-	async handleBackgroundEvent(event: AgentSessionEvent): Promise<void> {
-		if (event.type !== "agent_end") {
-			return;
-		}
-		if (this.ctx.session.queuedMessageCount > 0 || this.ctx.session.isStreaming) {
-			return;
-		}
-		this.sendCompletionNotification();
-		await this.ctx.shutdown();
-	}
 }
diff --git a/packages/coding-agent/src/modes/controllers/extension-ui-controller.ts b/packages/coding-agent/src/modes/controllers/extension-ui-controller.ts
index 8f09b645b..31d6e7cc0 100644
--- a/packages/coding-agent/src/modes/controllers/extension-ui-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/extension-ui-controller.ts
@@ -1,6 +1,5 @@
 import type { Component, OverlayHandle, TUI } from "@oh-my-pi/pi-tui";
 import { Container, Spacer, Text } from "@oh-my-pi/pi-tui";
-import { logger } from "@oh-my-pi/pi-utils";
 import { KeybindingsManager } from "../../config/keybindings";
 import type {
 	CompactOptions,
@@ -326,10 +325,6 @@ export class ExtensionUiController {
 					.then(() => this.#applyCustomMessageDisplay(wasStreaming, message.display))
 					.catch((err: unknown) => {
 						const errorText = `Extension sendMessage failed: ${err instanceof Error ? err.message : String(err)}`;
-						if (this.ctx.isBackgrounded) {
-							logger.error(errorText);
-							return;
-						}
 						this.ctx.showError(errorText);
 					});
 			},
@@ -374,9 +369,6 @@ export class ExtensionUiController {
 			getContextUsage: () => this.ctx.session.getContextUsage(),
 			waitForIdle: () => this.ctx.session.agent.waitForIdle(),
 			reload: async () => {
-				if (this.ctx.isBackgrounded) {
-					return;
-				}
 				await this.ctx.session.reload();
 				this.ctx.chatContainer.clear();
 				this.ctx.renderInitialMessages(undefined, { clearTerminalHistory: true });
@@ -384,9 +376,6 @@ export class ExtensionUiController {
 				this.ctx.showStatus("Reloaded session");
 			},
 			newSession: async options => {
-				if (this.ctx.isBackgrounded) {
-					return { cancelled: true };
-				}
 				// Stop any loading animation
 				if (this.ctx.loadingAnimation) {
 					this.ctx.loadingAnimation.stop();
@@ -425,9 +414,6 @@ export class ExtensionUiController {
 				return { cancelled: false };
 			},
 			branch: async entryId => {
-				if (this.ctx.isBackgrounded) {
-					return { cancelled: true };
-				}
 				const result = await this.ctx.session.branch(entryId);
 				if (result.cancelled) {
 					return { cancelled: true };
@@ -443,9 +429,6 @@ export class ExtensionUiController {
 				return { cancelled: false };
 			},
 			navigateTree: async (targetId, options) => {
-				if (this.ctx.isBackgrounded) {
-					return { cancelled: true };
-				}
 				const result = await this.ctx.session.navigateTree(targetId, { summarize: options?.summarize });
 				if (result.cancelled) {
 					return { cancelled: true };
@@ -464,9 +447,6 @@ export class ExtensionUiController {
 			},
 			compact: async instructionsOrOptions => this.#handleInteractiveCompact(instructionsOrOptions),
 			switchSession: async sessionPath => {
-				if (this.ctx.isBackgrounded) {
-					return { cancelled: true };
-				}
 				this.clearHookWidgets();
 				const result = await this.ctx.session.switchSession(sessionPath);
 				if (!result) {
@@ -482,36 +462,6 @@ export class ExtensionUiController {
 		extensionRunner.initialize(actions, contextActions, commandActions, uiContext);
 	}
 
-	createBackgroundUiContext(): ExtensionUIContext {
-		return {
-			select: async (_title: string, _options: ExtensionUISelectItem[], _dialogOptions) => undefined,
-			confirm: async (_title: string, _message: string, _dialogOptions) => false,
-			input: async (_title: string, _placeholder?: string, _dialogOptions?: unknown) => undefined,
-			notify: () => {},
-			onTerminalInput: () => () => {},
-			setStatus: () => {},
-			setWorkingMessage: () => {},
-			setWidget: () => {},
-			setTitle: () => {},
-			custom: async () => undefined as never,
-			setEditorText: () => {},
-			pasteToEditor: () => {},
-			getEditorText: () => "",
-			editor: async () => undefined,
-			get theme() {
-				return theme;
-			},
-			getAllThemes: () => Promise.resolve([]),
-			getTheme: () => Promise.resolve(undefined),
-			setTheme: () => Promise.resolve({ success: false, error: "Background mode" }),
-			setFooter: () => {},
-			setHeader: () => {},
-			setEditorComponent: () => {},
-			getToolsExpanded: () => false,
-			setToolsExpanded: () => {},
-		};
-	}
-
 	/**
 	 * Emit session event to all extension tools.
 	 */
@@ -531,7 +481,7 @@ export class ExtensionUiController {
 						ui: uiContext,
 						getContextUsage: () => this.ctx.session.getContextUsage(),
 						compact: instructionsOrOptions => this.#compactSession(instructionsOrOptions),
-						hasUI: !this.ctx.isBackgrounded,
+						hasUI: true,
 						cwd: this.ctx.sessionManager.getCwd(),
 						sessionManager: this.ctx.session.sessionManager,
 						modelRegistry: this.ctx.session.modelRegistry,
@@ -557,10 +507,6 @@ export class ExtensionUiController {
 	 * Show a tool error in the chat.
 	 */
 	showToolError(toolName: string, error: string): void {
-		if (this.ctx.isBackgrounded) {
-			logger.error(`Tool "${toolName}" error: ${error}`);
-			return;
-		}
 		const errorText = new Text(theme.fg("error", `Tool "${toolName}" error: ${error}`), 1, 0);
 		this.ctx.present(errorText);
 	}
@@ -569,9 +515,6 @@ export class ExtensionUiController {
 	 * Set hook status text in the footer.
 	 */
 	setHookStatus(key: string, text: string | undefined): void {
-		if (this.ctx.isBackgrounded) {
-			return;
-		}
 		this.ctx.statusLine.setHookStatus(key, text);
 		this.ctx.ui.requestRender();
 	}
@@ -862,10 +805,6 @@ export class ExtensionUiController {
 		this.ctx.present(errorText);
 	}
 	async #handleInteractiveCompact(instructionsOrOptions: string | CompactOptions | undefined): Promise<void> {
-		if (this.ctx.isBackgrounded) {
-			await this.#compactSession(instructionsOrOptions);
-			return;
-		}
 		await this.ctx.executeCompaction(instructionsOrOptions, false);
 	}
 
@@ -890,7 +829,7 @@ export class ExtensionUiController {
 	#applyCustomMessageDisplay(wasStreaming: boolean, shouldDisplay: boolean | undefined): void {
 		// For non-streaming cases with display=true, update UI
 		// (streaming cases update via message_end event)
-		if (!this.ctx.isBackgrounded && !wasStreaming && shouldDisplay) {
+		if (!wasStreaming && shouldDisplay) {
 			this.ctx.rebuildChatFromMessages();
 		}
 	}
diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index 253998228..b8ac1c891 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -9,7 +9,6 @@ import { expandEmoticons } from "../../modes/emoji-autocomplete";
 import { materializeImageReferenceLinks } from "../../modes/image-references";
 import { createPromptActionAutocompleteProvider } from "../../modes/prompt-action-autocomplete";
 import type { InteractiveModeContext } from "../../modes/types";
-import type { AgentSessionEvent } from "../../session/agent-session";
 import { SKILL_PROMPT_MESSAGE_TYPE, type SkillPromptDetails } from "../../session/messages";
 import { executeBuiltinSlashCommand } from "../../slash-commands/builtin-registry";
 import { isTinyTitleLocalModelKey } from "../../tiny/models";
@@ -41,7 +40,7 @@ export class InputController {
 	constructor(private ctx: InteractiveModeContext) {}
 
 	#showTinyTitleDownloadProgress(modelKey: string): void {
-		if (!isTinyTitleLocalModelKey(modelKey) || this.ctx.isBackgrounded) return;
+		if (!isTinyTitleLocalModelKey(modelKey)) return;
 		const component = new TinyTitleDownloadProgressComponent(modelKey);
 		let added = false;
 		let disposed = false;
@@ -291,7 +290,6 @@ export class InputController {
 			// Handle built-in slash commands
 			const slashResult = await executeBuiltinSlashCommand(text, {
 				ctx: this.ctx,
-				handleBackgroundCommand: () => this.handleBackgroundCommand(),
 			});
 			if (slashResult === true) {
 				return;
@@ -615,67 +613,6 @@ export class InputController {
 		return allQueued.length;
 	}
 
-	handleBackgroundCommand(): void {
-		if (this.ctx.isBackgrounded) {
-			this.ctx.showStatus("Background mode already enabled");
-			return;
-		}
-		if (!this.ctx.session.isStreaming && this.ctx.session.queuedMessageCount === 0) {
-			this.ctx.showWarning("Agent is idle; nothing to background");
-			return;
-		}
-		if (this.ctx.hasActiveBtw()) {
-			this.ctx.handleBtwEscape();
-		}
-		if (this.ctx.hasActiveOmfg()) {
-			this.ctx.handleOmfgEscape();
-		}
-
-		this.ctx.isBackgrounded = true;
-		const backgroundUiContext = this.ctx.createBackgroundUiContext();
-
-		// Background mode disables interactive UI so tools like ask fail fast.
-		this.ctx.setToolUIContext(backgroundUiContext, false);
-		this.ctx.initializeHookRunner(backgroundUiContext, false);
-
-		if (this.ctx.loadingAnimation) {
-			this.ctx.loadingAnimation.stop();
-			this.ctx.loadingAnimation = undefined;
-		}
-		if (this.ctx.autoCompactionLoader) {
-			this.ctx.autoCompactionLoader.stop();
-			this.ctx.autoCompactionLoader = undefined;
-		}
-		if (this.ctx.retryLoader) {
-			this.ctx.retryLoader.stop();
-			this.ctx.retryLoader = undefined;
-		}
-		this.ctx.statusContainer.clear();
-		this.ctx.statusLine.dispose();
-
-		if (this.ctx.unsubscribe) {
-			this.ctx.unsubscribe();
-		}
-		this.ctx.unsubscribe = this.ctx.session.subscribe(async (event: AgentSessionEvent) => {
-			await this.ctx.handleBackgroundEvent(event);
-		});
-
-		// Backgrounding keeps the current process to preserve in-flight agent state.
-		if (this.ctx.isInitialized) {
-			this.ctx.ui.stop();
-			this.ctx.isInitialized = false;
-		}
-
-		process.stdout.write("Background mode enabled. Run `bg` to continue in background.\n");
-
-		if (process.platform === "win32" || !process.stdout.isTTY) {
-			process.stdout.write("Backgrounding requires POSIX job control; continuing in foreground.\n");
-			return;
-		}
-
-		process.kill(0, "SIGTSTP");
-	}
-
 	async handleImagePaste(): Promise<boolean> {
 		try {
 			const image = await readImageFromClipboard();
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index d831e9ba8..ee6840bfe 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -275,7 +275,6 @@ export class InteractiveMode implements InteractiveModeContext {
 	statusLine: StatusLineComponent;
 
 	isInitialized = false;
-	isBackgrounded = false;
 	isBashMode = false;
 	toolOutputExpanded = false;
 	todoExpanded = false;
@@ -2506,9 +2505,6 @@ export class InteractiveMode implements InteractiveModeContext {
 	initializeHookRunner(uiContext: ExtensionUIContext, hasUI: boolean): void {
 		this.#extensionUiController.initializeHookRunner(uiContext, hasUI);
 	}
-	createBackgroundUiContext(): ExtensionUIContext {
-		return this.#extensionUiController.createBackgroundUiContext();
-	}
 
 	setEditorComponent(
 		factory: ((tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => CustomEditor) | undefined,
@@ -2550,11 +2546,6 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.ui.requestRender();
 	}
 
-	// Event handling
-	async handleBackgroundEvent(event: AgentSessionEvent): Promise<void> {
-		await this.#eventController.handleBackgroundEvent(event);
-	}
-
 	// UI helpers
 	present(content: Component | readonly Component[]): void {
 		if (Array.isArray(content)) {
@@ -2594,7 +2585,6 @@ export class InteractiveMode implements InteractiveModeContext {
 	}
 
 	showPinnedError(message: string): void {
-		if (this.isBackgrounded) return;
 		this.errorBannerContainer.clear();
 		this.errorBannerContainer.addChild(new ErrorBannerComponent(message));
 		this.ui.requestRender();
@@ -3070,10 +3060,6 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#inputController.handleDequeue();
 	}
 
-	handleBackgroundCommand(): void {
-		this.#inputController.handleBackgroundCommand();
-	}
-
 	handleImagePaste(): Promise<boolean> {
 		return this.#inputController.handleImagePaste();
 	}
diff --git a/packages/coding-agent/src/modes/types.ts b/packages/coding-agent/src/modes/types.ts
index f5c09625c..8eb4c4b3b 100644
--- a/packages/coding-agent/src/modes/types.ts
+++ b/packages/coding-agent/src/modes/types.ts
@@ -14,7 +14,7 @@ import type {
 import type { CompactOptions } from "../extensibility/extensions/types";
 import type { MCPManager } from "../mcp";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
-import type { AgentSession, AgentSessionEvent } from "../session/agent-session";
+import type { AgentSession } from "../session/agent-session";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext, SessionManager } from "../session/session-manager";
 import type { ShakeMode } from "../session/shake-types";
@@ -95,7 +95,6 @@ export interface InteractiveModeContext {
 
 	// State
 	isInitialized: boolean;
-	isBackgrounded: boolean;
 	isBashMode: boolean;
 	toolOutputExpanded: boolean;
 	todoExpanded: boolean;
@@ -149,14 +148,10 @@ export interface InteractiveModeContext {
 	// Extension UI integration
 	setToolUIContext(uiContext: ExtensionUIContext, hasUI: boolean): void;
 	initializeHookRunner(uiContext: ExtensionUIContext, hasUI: boolean): void;
-	createBackgroundUiContext(): ExtensionUIContext;
 	setEditorComponent(
 		factory: ((tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => CustomEditor) | undefined,
 	): void;
 
-	// Event handling
-	handleBackgroundEvent(event: AgentSessionEvent): Promise<void>;
-
 	// UI helpers
 	/**
 	 * Mount transcript content and repaint once. The single sink for "show this in
@@ -293,7 +288,6 @@ export interface InteractiveModeContext {
 	handleCtrlD(): void;
 	handleCtrlZ(): void;
 	handleDequeue(): void;
-	handleBackgroundCommand(): void;
 	handleImagePaste(): Promise<boolean>;
 	handleBtwCommand(question: string): Promise<void>;
 	hasActiveBtw(): boolean;
diff --git a/packages/coding-agent/src/slash-commands/builtin-registry.ts b/packages/coding-agent/src/slash-commands/builtin-registry.ts
index 57ecac800..af224fc18 100644
--- a/packages/coding-agent/src/slash-commands/builtin-registry.ts
+++ b/packages/coding-agent/src/slash-commands/builtin-registry.ts
@@ -915,15 +915,6 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
-	{
-		name: "background",
-		aliases: ["bg"],
-		description: "Detach UI and continue running in background",
-		handleTui: (_command, runtime) => {
-			runtime.ctx.editor.setText("");
-			runtime.handleBackgroundCommand();
-		},
-	},
 	{
 		name: "debug",
 		description: "Open debug tools selector",
diff --git a/packages/coding-agent/src/slash-commands/types.ts b/packages/coding-agent/src/slash-commands/types.ts
index 6725815ba..15412739a 100644
--- a/packages/coding-agent/src/slash-commands/types.ts
+++ b/packages/coding-agent/src/slash-commands/types.ts
@@ -71,15 +71,13 @@ export interface SlashCommandRuntime {
 
 /**
  * Runtime visible to TUI-only handlers (`handleTui`). Carries the interactive
- * mode context plus the background-detach hook. Intentionally narrower than
- * `SlashCommandRuntime` so existing callers can keep building it from just
- * `{ ctx, handleBackgroundCommand }`; when the TUI dispatcher needs to invoke
- * a `handle` (no `handleTui` override), it synthesizes a `SlashCommandRuntime`
- * from `ctx`.
+ * mode context. Intentionally narrower than `SlashCommandRuntime` so existing
+ * callers can keep building it from just `{ ctx }`; when the TUI dispatcher
+ * needs to invoke a `handle` (no `handleTui` override), it synthesizes a
+ * `SlashCommandRuntime` from `ctx`.
  */
 export interface TuiSlashCommandRuntime {
 	ctx: InteractiveModeContext;
-	handleBackgroundCommand: () => void;
 }
 
 /** Unified slash-command spec consumed by both TUI and ACP dispatchers. */
diff --git a/packages/coding-agent/test/input-controller-skill-queue.test.ts b/packages/coding-agent/test/input-controller-skill-queue.test.ts
index 0128b09cd..93dbba9ef 100644
--- a/packages/coding-agent/test/input-controller-skill-queue.test.ts
+++ b/packages/coding-agent/test/input-controller-skill-queue.test.ts
@@ -95,7 +95,6 @@ function createStubInputControllerContext(opts: { skillCommands: Map<string, str
 		isPythonMode: false,
 		pendingImages: [],
 		pendingImageLinks: [],
-		isBackgrounded: false,
 		loopModeEnabled: false,
 		compactionQueuedMessages: [],
 		locallySubmittedUserSignatures: new Set<string>(),
diff --git a/packages/coding-agent/test/interactive-mode-status.test.ts b/packages/coding-agent/test/interactive-mode-status.test.ts
index aae1a575a..f32f13587 100644
--- a/packages/coding-agent/test/interactive-mode-status.test.ts
+++ b/packages/coding-agent/test/interactive-mode-status.test.ts
@@ -30,7 +30,6 @@ function createInitialRenderHarness(): { ctx: InteractiveModeContext; helpers: U
 			for (const item of items) ctx.chatContainer.addChild(item);
 			ctx.ui.requestRender();
 		},
-		isBackgrounded: false,
 		sessionManager: {
 			buildSessionContext: () => buildSessionContext([]),
 			getEntries: () => [],
@@ -69,7 +68,6 @@ describe("InteractiveMode.showStatus", () => {
 				for (const item of items) ctx.chatContainer.addChild(item);
 				ctx.ui.requestRender();
 			},
-			isBackgrounded: false,
 			lastStatusSpacer: undefined,
 			lastStatusText: undefined,
 		} as unknown as InteractiveModeContext;
@@ -95,7 +93,6 @@ describe("InteractiveMode.showStatus", () => {
 				for (const item of items) ctx.chatContainer.addChild(item);
 				ctx.ui.requestRender();
 			},
-			isBackgrounded: false,
 			lastStatusSpacer: undefined,
 			lastStatusText: undefined,
 		} as unknown as InteractiveModeContext;
diff --git a/packages/coding-agent/test/loop-limit.test.ts b/packages/coding-agent/test/loop-limit.test.ts
index ff2033c19..9e660785c 100644
--- a/packages/coding-agent/test/loop-limit.test.ts
+++ b/packages/coding-agent/test/loop-limit.test.ts
@@ -16,7 +16,6 @@ describe("/loop slash command", () => {
 				handleLoopCommand,
 				editor: { setText: vi.fn() },
 			},
-			handleBackgroundCommand: vi.fn(),
 		} as unknown as BuiltinSlashCommandRuntime;
 		const result = await executeBuiltinSlashCommand("/loop 10min", runtime);
 
diff --git a/packages/coding-agent/test/modes/controllers/event-controller-abort-guard.test.ts b/packages/coding-agent/test/modes/controllers/event-controller-abort-guard.test.ts
index b35db298f..e25eab0a4 100644
--- a/packages/coding-agent/test/modes/controllers/event-controller-abort-guard.test.ts
+++ b/packages/coding-agent/test/modes/controllers/event-controller-abort-guard.test.ts
@@ -2,12 +2,12 @@
  * Regression test for the abort-guard on `EventController.sendCompletionNotification`.
  *
  * Bug: a user Ctrl+C on the `ask` tool selector throws `ToolAbortError`,
- * the turn ends with `stopReason === "aborted"`, and `handleBackgroundEvent`
- * fires `sendCompletionNotification()` unconditionally. The pre-fix code
- * then produced a misleading "Task complete" desktop toast for a turn that
- * never actually completed. The fix mirrors the `stopReason !== "aborted"`
- * pattern already used by `#currentContextTokens`, `#handleMessageEnd`, and
- * the retry / TTSR / compaction skip paths in `agent-session.ts`.
+ * the turn ends with `stopReason === "aborted"`, and `#handleAgentEnd`
+ * fires `sendCompletionNotification()`. Without a guard this produced a
+ * misleading "Task complete" desktop toast for a turn that never actually
+ * completed. The fix mirrors the `stopReason !== "aborted"` pattern already
+ * used by `#currentContextTokens`, `#handleMessageEnd`, and the
+ * retry / TTSR / compaction skip paths in `agent-session.ts`.
  */
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
 import * as fs from "node:fs";
@@ -49,8 +49,6 @@ function makeAssistantMessage(stopReason: StopReason): AssistantMessage {
 
 function makeContext(lastMessage: AssistantMessage | undefined): InteractiveModeContext {
 	return {
-		// sendCompletionNotification only fires when backgrounded.
-		isBackgrounded: true,
 		sessionManager: {
 			getSessionName: () => "test-session",
 		},
@@ -96,16 +94,6 @@ describe("EventController.sendCompletionNotification — abort guard", () => {
 		expect(spy).toHaveBeenCalledTimes(1);
 	});
 
-	it("honors the existing isBackgrounded gate (no notification when foreground)", () => {
-		const spy = vi.spyOn(TERMINAL, "sendNotification").mockImplementation(() => {});
-		settings.override("completion.notify", "on");
-		const ctx = makeContext(makeAssistantMessage("stop"));
-		(ctx as unknown as { isBackgrounded: boolean }).isBackgrounded = false;
-		const controller = new EventController(ctx);
-		controller.sendCompletionNotification();
-		expect(spy).toHaveBeenCalledTimes(0);
-	});
-
 	it("honors the existing completion.notify=off gate", () => {
 		const spy = vi.spyOn(TERMINAL, "sendNotification").mockImplementation(() => {});
 		settings.override("completion.notify", "off");
diff --git a/packages/coding-agent/test/modes/controllers/event-controller-idle-compaction.test.ts b/packages/coding-agent/test/modes/controllers/event-controller-idle-compaction.test.ts
index 48f4e51b1..39b37e38c 100644
--- a/packages/coding-agent/test/modes/controllers/event-controller-idle-compaction.test.ts
+++ b/packages/coding-agent/test/modes/controllers/event-controller-idle-compaction.test.ts
@@ -48,7 +48,6 @@ describe("EventController idle compaction teardown", () => {
 		const runIdleCompaction = vi.fn();
 		const context = {
 			isInitialized: true,
-			isBackgrounded: false,
 			loadingAnimation: undefined,
 			streamingComponent: undefined,
 			streamingMessage: undefined,
diff --git a/packages/coding-agent/test/modes/controllers/event-controller-tool-render-mode.test.ts b/packages/coding-agent/test/modes/controllers/event-controller-tool-render-mode.test.ts
index 34a320451..ec9e0d444 100644
--- a/packages/coding-agent/test/modes/controllers/event-controller-tool-render-mode.test.ts
+++ b/packages/coding-agent/test/modes/controllers/event-controller-tool-render-mode.test.ts
@@ -11,7 +11,6 @@ function createContext() {
 	const chatContainer = { addChild: vi.fn(), removeChild: vi.fn() };
 	const ctx = {
 		isInitialized: true,
-		isBackgrounded: false,
 		statusLine: { invalidate: vi.fn() },
 		updateEditorTopBorder: vi.fn(),
 		pendingTools,
@@ -19,6 +18,7 @@ function createContext() {
 		hideThinkingBlock: false,
 		editor: { getText: vi.fn(() => "") },
 		flushPendingModelSwitch: vi.fn(),
+		sessionManager: { getSessionName: () => undefined },
 		session: {
 			agent: { state: { messages: [] } },
 			isCompacting: false,
diff --git a/packages/coding-agent/test/slash-commands/btw.test.ts b/packages/coding-agent/test/slash-commands/btw.test.ts
index 1638229df..1349fa895 100644
--- a/packages/coding-agent/test/slash-commands/btw.test.ts
+++ b/packages/coding-agent/test/slash-commands/btw.test.ts
@@ -13,7 +13,6 @@ function createRuntime() {
 				editor: { setText } as unknown as InteractiveModeContext["editor"],
 				handleBtwCommand,
 			} as unknown as InteractiveModeContext,
-			handleBackgroundCommand: () => {},
 		},
 	};
 }
diff --git a/packages/coding-agent/test/slash-commands/force.test.ts b/packages/coding-agent/test/slash-commands/force.test.ts
index 28ce73f31..3c47db41b 100644
--- a/packages/coding-agent/test/slash-commands/force.test.ts
+++ b/packages/coding-agent/test/slash-commands/force.test.ts
@@ -20,7 +20,6 @@ function createRuntimeHarness(overrides?: { setForcedToolChoice?: (toolName: str
 	return {
 		runtime: {
 			ctx,
-			handleBackgroundCommand: () => {},
 		},
 		setForcedToolChoice,
 		setText,
diff --git a/packages/coding-agent/test/slash-commands/fresh.test.ts b/packages/coding-agent/test/slash-commands/fresh.test.ts
index d20af962b..270c8fbd6 100644
--- a/packages/coding-agent/test/slash-commands/fresh.test.ts
+++ b/packages/coding-agent/test/slash-commands/fresh.test.ts
@@ -12,7 +12,6 @@ function createRuntimeHarness(handleFreshCommand: InteractiveModeContext["handle
 				editor: { setText } as unknown as InteractiveModeContext["editor"],
 				handleFreshCommand,
 			} as InteractiveModeContext,
-			handleBackgroundCommand: () => {},
 		},
 	};
 }
diff --git a/packages/coding-agent/test/slash-commands/login.test.ts b/packages/coding-agent/test/slash-commands/login.test.ts
index 083dc0503..7ad589d72 100644
--- a/packages/coding-agent/test/slash-commands/login.test.ts
+++ b/packages/coding-agent/test/slash-commands/login.test.ts
@@ -4,7 +4,7 @@ import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/typ
 import { executeBuiltinSlashCommand } from "@oh-my-pi/pi-coding-agent/slash-commands/builtin-registry";
 
 type RuntimeHarness = {
-	runtime: { ctx: InteractiveModeContext; handleBackgroundCommand: () => void };
+	runtime: { ctx: InteractiveModeContext };
 	getStatus: () => string | undefined;
 	getWarning: () => string | undefined;
 	getSelectorMode: () => "login" | "logout" | undefined;
@@ -36,7 +36,6 @@ const createRuntimeHarness = (manualInput: OAuthManualInputManager): RuntimeHarn
 	return {
 		runtime: {
 			ctx,
-			handleBackgroundCommand: () => {},
 		},
 		getStatus: () => statusMessage,
 		getWarning: () => warningMessage,
diff --git a/packages/coding-agent/test/slash-commands/omfg.test.ts b/packages/coding-agent/test/slash-commands/omfg.test.ts
index 82cbec560..a95bc41f2 100644
--- a/packages/coding-agent/test/slash-commands/omfg.test.ts
+++ b/packages/coding-agent/test/slash-commands/omfg.test.ts
@@ -13,7 +13,6 @@ function createRuntime() {
 				editor: { setText } as unknown as InteractiveModeContext["editor"],
 				handleOmfgCommand,
 			} as unknown as InteractiveModeContext,
-			handleBackgroundCommand: () => {},
 		},
 	};
 }
diff --git a/packages/coding-agent/test/slash-commands/plan-history.test.ts b/packages/coding-agent/test/slash-commands/plan-history.test.ts
index e4b1dab0c..656be0978 100644
--- a/packages/coding-agent/test/slash-commands/plan-history.test.ts
+++ b/packages/coding-agent/test/slash-commands/plan-history.test.ts
@@ -30,7 +30,7 @@ function createPlanHarness(opts: { planModeEnabled: boolean; confirmExit: boolea
 	} as unknown as InteractiveModeContext;
 
 	return {
-		runtime: { ctx, handleBackgroundCommand: () => {} },
+		runtime: { ctx },
 		state,
 		addToHistory,
 		setText,
@@ -53,7 +53,7 @@ function createGoalHarness(opts: { goalModeEnabled: boolean; dropOnCall: boolean
 	} as unknown as InteractiveModeContext;
 
 	return {
-		runtime: { ctx, handleBackgroundCommand: () => {} },
+		runtime: { ctx },
 		state,
 		addToHistory,
 		setText,
diff --git a/packages/coding-agent/test/slash-commands/retry.test.ts b/packages/coding-agent/test/slash-commands/retry.test.ts
index 899031519..bc7486407 100644
--- a/packages/coding-agent/test/slash-commands/retry.test.ts
+++ b/packages/coding-agent/test/slash-commands/retry.test.ts
@@ -16,7 +16,6 @@ function createRuntime(didRetry: boolean) {
 				editor: { setText } as unknown as InteractiveModeContext["editor"],
 				showStatus,
 			} as unknown as InteractiveModeContext,
-			handleBackgroundCommand: () => {},
 		},
 	};
 }
diff --git a/packages/coding-agent/test/slash-commands/session.test.ts b/packages/coding-agent/test/slash-commands/session.test.ts
index d4662c28a..86c6821d4 100644
--- a/packages/coding-agent/test/slash-commands/session.test.ts
+++ b/packages/coding-agent/test/slash-commands/session.test.ts
@@ -28,7 +28,6 @@ function createRuntimeHarness(options?: {
 				handleSessionCommand,
 				handleSessionDeleteCommand,
 			} as InteractiveModeContext,
-			handleBackgroundCommand: () => {},
 		},
 	};
 }
diff --git a/packages/coding-agent/test/slash-commands/shake.test.ts b/packages/coding-agent/test/slash-commands/shake.test.ts
index 9edc3beb1..e7b606256 100644
--- a/packages/coding-agent/test/slash-commands/shake.test.ts
+++ b/packages/coding-agent/test/slash-commands/shake.test.ts
@@ -31,7 +31,6 @@ function tuiRuntime() {
 			handleShakeCommand,
 			showWarning,
 		} as unknown as InteractiveModeContext,
-		handleBackgroundCommand: vi.fn(),
 	};
 	return { handleShakeCommand, setText, showWarning, runtime };
 }
diff --git a/packages/coding-agent/test/slash-commands/switch.test.ts b/packages/coding-agent/test/slash-commands/switch.test.ts
index d3d4f5aae..15d0c896e 100644
--- a/packages/coding-agent/test/slash-commands/switch.test.ts
+++ b/packages/coding-agent/test/slash-commands/switch.test.ts
@@ -5,7 +5,6 @@ import { executeBuiltinSlashCommand } from "@oh-my-pi/pi-coding-agent/slash-comm
 function createRuntime() {
 	const showModelSelector = vi.fn();
 	const setText = vi.fn();
-	const handleBackgroundCommand = vi.fn();
 	return {
 		showModelSelector,
 		setText,
@@ -13,9 +12,7 @@ function createRuntime() {
 			ctx: {
 				editor: { setText } as unknown as InteractiveModeContext["editor"],
 				showModelSelector,
-				handleBackgroundCommand,
 			} as unknown as InteractiveModeContext,
-			handleBackgroundCommand,
 		},
 	};
 }

From 6e554d8ab87856d1ba0cd3cdbb4ea5d6a1d522e0 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 05:53:00 +0200
Subject: [PATCH 099/181] ux(coding-agent): refined tool-execution block
 framing and state background

- Adjusted tool-execution rendering to apply state-based background tinting and spacing for non-framed outputs.
- Detected framed block children and skipped extra padding and tinting so those custom renderers stay flush.
- Wrapped framed output with markFramedBlockComponent so self-framed blocks are recognized by the renderer.
---
 .../src/modes/components/tool-execution.ts    | 23 +++++++++++++++----
 packages/coding-agent/src/tui/output-block.ts |  7 ++++--
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index dae47fe2c..99061c569 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -33,7 +33,7 @@ import {
 import { formatExpandHint, replaceTabs, resolveImageOptions, truncateToWidth } from "../../tools/render-utils";
 import { type ToolRenderer, toolRenderers } from "../../tools/renderers";
 import { TODO_STRIKE_TOTAL_FRAMES } from "../../tools/todo";
-import { renderStatusLine } from "../../tui";
+import { isFramedBlockComponent, renderStatusLine } from "../../tui";
 import { sanitizeWithOptionalSixelPassthrough } from "../../utils/sixel";
 import { renderDiff } from "./diff";
 
@@ -226,9 +226,12 @@ export class ToolExecutionComponent extends Container {
 		this.#args = args;
 
 		// Always create both - contentBox for custom tools/bash/tools with renderers, contentText for other built-ins.
-		// paddingY is 0: the transcript owns inter-block spacing (see TranscriptContainer).
-		this.#contentBox = new Box(0, 0);
-		this.#contentText = new Text("", 1, 0);
+		// paddingY is 1 so background-tinted blocks (custom/extension tools and the
+		// generic fallback) get top/bottom breathing room. TranscriptContainer
+		// strips PLAIN-blank edges, so framed/minimal blocks (no bg set) drop these
+		// lines and keep their tight spacing — only tinted lines survive.
+		this.#contentBox = new Box(0, 1);
+		this.#contentText = new Text("", 1, 1);
 
 		// Use Box for custom tools or built-in tools that have renderers
 		const hasRenderer = toolName in toolRenderers;
@@ -591,6 +594,12 @@ export class ToolExecutionComponent extends Container {
 		this.#renderState.isPartial = this.#isPartial;
 		this.#renderState.spinnerFrame = this.#spinnerFrame;
 
+		// Non-self-framing tools (custom/extension renderers and the generic
+		// fallback) get a padded, state-tinted block — built-ins that draw their
+		// own frame opt out below via the framed-component mark.
+		const stateBgKey = this.#isPartial ? "toolPendingBg" : this.#result?.isError ? "toolErrorBg" : "toolSuccessBg";
+		const stateBgFn = (t: string) => theme.bg(stateBgKey, t);
+
 		// Check for custom tool rendering
 		if (this.#tool && (this.#tool.renderCall || this.#tool.renderResult)) {
 			const tool = this.#tool;
@@ -660,6 +669,11 @@ export class ToolExecutionComponent extends Container {
 					this.#contentBox.addChild(new Text(theme.fg("toolOutput", replaceTabs(output)), 0, 0));
 				}
 			}
+			// Custom tools that draw their own frame (task) render flush; plain
+			// extension renderers get the padded, state-tinted block back.
+			const customFramed = this.#contentBox.children.some(isFramedBlockComponent);
+			this.#contentBox.setPaddingX(customFramed ? 0 : 1);
+			this.#contentBox.setBgFn(customFramed ? undefined : stateBgFn);
 		} else if (this.#toolName in toolRenderers) {
 			// Built-in tools with renderers
 			const renderer = toolRenderers[this.#toolName];
@@ -774,6 +788,7 @@ export class ToolExecutionComponent extends Container {
 			}
 		} else {
 			// Other built-in tools: use Text directly with caching
+			this.#contentText.setCustomBgFn(stateBgFn);
 			this.#contentText.setText(this.#formatToolExecution());
 		}
 
diff --git a/packages/coding-agent/src/tui/output-block.ts b/packages/coding-agent/src/tui/output-block.ts
index 1ed78cb89..5d1c1f0a3 100644
--- a/packages/coding-agent/src/tui/output-block.ts
+++ b/packages/coding-agent/src/tui/output-block.ts
@@ -305,8 +305,11 @@ export class CachedOutputBlock {
  */
 export function framedBlock(theme: Theme, build: (width: number) => OutputBlockOptions): Component {
 	const block = new CachedOutputBlock();
-	return {
+	// Marked so the tool-execution container treats it as self-framing (renders
+	// flush, no extra padding/background) the same way `markFramedBlockComponent`
+	// blocks are treated.
+	return markFramedBlockComponent({
 		render: (width: number): string[] => block.render(build(width), theme),
 		invalidate: () => block.invalidate(),
-	};
+	});
 }

From d9f09a07b7b022d689687de29bb5a412fb32aa15 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:01:25 +0200
Subject: [PATCH 100/181] fix(tui): prevented committed-prefix duplication on
 viewport repaint

- Clamped repaint anchor to min(firstChanged, scrollbackHighWater) so byte-identical committed rows are not re-painted into the active grid.
- Added submitPinsViewportToTail capability to reconcile native scrollback at submit on unprobeable local terminals.
- Renamed allowUnknownViewportMutation to allowUnknownViewportTransientRepaint to clarify it never authorizes a settled transcript commit.
---
 packages/tui/CHANGELOG.md                     |  7 ++
 packages/tui/src/tui.ts                       | 59 +++++++++------
 .../viewport-repaint-no-duplicate.test.ts     | 75 +++++++++++++++++++
 3 files changed, 119 insertions(+), 22 deletions(-)
 create mode 100644 packages/tui/test/viewport-repaint-no-duplicate.test.ts

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 475340401..038704ff8 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -4,6 +4,7 @@
 ### Breaking Changes
 
 - Removed Kitty temp-file image transmission, its startup support probe, the `PI_KITTY_IMAGE_TRANSMISSION` override, and the temp-file helper exports. Kitty/Ghostty image payloads now stay on in-band base64 before placeholder/direct placement, avoiding blank first renders from temp-file load races.
+- Renamed `RenderRequestOptions.allowUnknownViewportMutation` → `allowUnknownViewportTransientRepaint`. The option only permits a transient live-viewport repaint (autocomplete/IME/focused-editor chrome) on hosts that cannot report viewport position; it never authorizes a settled transcript commit. The old name implied any offscreen mutation was safe to push into native scrollback, which led callers to emit duplicate transcript copies.
 
 ### Added
 
@@ -13,10 +14,16 @@
 - Added a `ScrollView` `ellipsis` option (defaults to `Ellipsis.Unicode`) so callers that pre-wrap content to width can pass `Ellipsis.Omit` and suppress the stray per-line `…` that lands on trailing padding.
 - Added `ScrollView.handleScrollKey()` plus a `fastScrollLines` option so every scroll view gets shared navigation keys, including Shift+Arrow to scroll faster.
 - Added `OverlayOptions.fullscreen`: while the topmost visible overlay sets it, the engine borrows the terminal's alternate screen buffer for the overlay's lifetime and paints only the modal there — no ED3, no transcript re-commit — so the transcript stays untouched on the normal screen and is not scrollable behind the modal. Mouse tracking (`?1000h`/`?1006h`) is enabled for the modal's lifetime and disabled on exit, so the rest of the app keeps the terminal's native text selection.
+- Added the `submitPinsViewportToTail` terminal capability and `detectSubmitPinsViewportToTail()`: genuine local terminals where a submit keystroke scrolls the host to its tail reconcile deferred native scrollback at the prompt-submit checkpoint even when the viewport position is unprobeable (Ghostty/kitty/iTerm/WezTerm/Alacritty). Restores the pre-regression submit reconciliation without re-enabling it for Windows Terminal/ConPTY, SSH, or multiplexers, where a submit is not proof the host is at the tail.
 
 ### Changed
 
 - Made `Component.invalidate()` optional so leaf components without render caches no longer need no-op invalidation hooks.
+- `TERMINAL` is now a `RuntimeTerminal` whose post-construction capabilities (image protocol and the probe-driven flags) are writable, replacing the `as unknown as MutableTerminalInfo` cast pattern and the positional `withTerminalOverrides` rebuild with a prototype-preserving `clone()`.
+
+### Fixed
+
+- Fixed the transcript — or a re-appearing prior view such as the welcome screen — duplicating itself on terminals without a scroll-position oracle (Ghostty/kitty/iTerm/WezTerm) when a foreground tool completes by rewriting a partly-committed block, or when the transcript is reset. A non-destructive viewport repaint no longer re-paints rows that are byte-identical to what is already committed to native scrollback into the active grid; the repaint anchor is clamped to the committed-and-unchanged prefix (`min(firstChanged, scrollbackHighWater)`).
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index a2e18d20e..b90cd61d9 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -197,15 +197,14 @@ export interface RenderRequestOptions {
 	/** Clear terminal scrollback for intentional transcript replacement. */
 	clearScrollback?: boolean;
 	/**
-	 * Bypass the unknown-Windows-viewport deferral for this render so the
-	 * caller's intentional live UI mutation reaches the terminal even when
-	 * `Terminal#isNativeViewportAtBottom()` cannot answer.
+	 * Allow a transient live-viewport repaint when the terminal cannot report
+	 * whether its native viewport is at the tail.
 	 *
-	 * Use only for renders driven by direct user interaction (autocomplete
-	 * updates, IME, etc.). Any background/offscreen transcript change that
-	 * coalesces into the same frame WILL also bypass the deferral and reach
-	 * native scrollback — that is the trade-off, and the reason ordinary
-	 * `requestRender()` calls must continue to omit this flag.
+	 * This is **not** a settled transcript commit and must not be used for tool
+	 * completion, session replay, or other background/offscreen rewrites. On
+	 * ED3-risk terminals it may deliberately choose a viewport repaint/deferred
+	 * shrink without clearing native scrollback so autocomplete, IME, and focused
+	 * editor chrome stay responsive without yanking a scrolled reader.
 	 */
 	allowUnknownViewportMutation?: boolean;
 }
@@ -1046,7 +1045,7 @@ export class TUI extends Container {
 		// defers regardless of terminal.
 		if (nativeViewportAtBottom === false) return false;
 		if (nativeViewportAtBottom === undefined && !TERMINAL.submitPinsViewportToTail) return false;
-		this.#prepareForcedRender(true, false);
+		this.#prepareForcedRender(true);
 		this.#renderRequested = false;
 		this.#lastRenderAt = this.#renderScheduler.now();
 		this.#doRender();
@@ -1070,7 +1069,7 @@ export class TUI extends Container {
 	resetDisplay(): void {
 		if (this.#stopped) return;
 		this.invalidate();
-		this.#prepareForcedRender(!isMultiplexerSession(), true);
+		this.#prepareForcedRender(!isMultiplexerSession());
 		this.#resizeEventPending = true;
 		this.#renderRequested = false;
 		this.#lastRenderAt = this.#renderScheduler.now();
@@ -1081,7 +1080,7 @@ export class TUI extends Container {
 		const allowUnknownViewportMutation = options?.allowUnknownViewportMutation === true;
 		this.#allowUnknownViewportMutationOnNextRender ||= allowUnknownViewportMutation;
 		if (force) {
-			this.#prepareForcedRender(options?.clearScrollback === true, allowUnknownViewportMutation);
+			this.#prepareForcedRender(options?.clearScrollback === true);
 			this.#renderRequested = true;
 			this.#renderScheduler.scheduleImmediate(() => {
 				if (this.#stopped || !this.#renderRequested) {
@@ -1098,7 +1097,7 @@ export class TUI extends Container {
 		this.#renderScheduler.scheduleImmediate(() => this.#scheduleRender());
 	}
 
-	#prepareForcedRender(clearScrollback: boolean, _allowUnknownViewportMutation: boolean): void {
+	#prepareForcedRender(clearScrollback: boolean): void {
 		const geometryChanged =
 			(this.#previousWidth > 0 && this.#previousWidth !== this.terminal.columns) ||
 			(this.#previousHeight > 0 && this.#previousHeight !== this.terminal.rows);
@@ -2352,15 +2351,14 @@ export class TUI extends Container {
 	 * the native viewport) is safe to emit *during ordinary rendering*. POSIX
 	 * terminals cannot report whether the user has scrolled up
 	 * (`isNativeViewportAtBottom()` is `undefined`), so an unknown position is
-	 * treated as unsafe: defer to a non-destructive viewport repaint and keep
-	 * scrollback dirty until a later render has a positive at-tail proof. A prompt
-	 * submit is no longer treated as proof for unobservable host scrollback.
-	 * this, every offscreen transcript edit while streaming wiped scrollback and
-	 * yanked a scrolled-up reader out of their current context.
-	 * `allowUnknownViewportMutation` (autocomplete/IME) opts directly
-	 * user-driven POSIX frames back into the rebuild. Native Windows and Windows
-	 * Terminal still cannot trust an unknown probe during live rendering — ConPTY
-	 * may be fronting host scrollback we cannot observe — so they keep deferring.
+	 * treated as unsafe by default: defer to a non-destructive viewport repaint and
+	 * keep scrollback dirty until a later checkpoint/positive at-tail proof.
+	 *
+	 * `allowUnknownViewportMutation` is the narrow exception for direct
+	 * input chrome (autocomplete/IME/editor wrapping): those frames may repaint or,
+	 * on non-Windows hosts, rebuild live UI while the user action pins the prompt
+	 * to the tail. Settled transcript commits should not use this flag; they must
+	 * request an explicit clear+replay instead.
 	 */
 	#canRebuildNativeScrollbackLive(
 		nativeViewportAtBottom: boolean | undefined,
@@ -2640,7 +2638,24 @@ export class TUI extends Container {
 		cursorPos: { row: number; col: number } | null,
 	): void {
 		this.#fullRedrawCount += 1;
-		const viewportTop = Math.max(0, lines.length - height);
+		const naturalViewportTop = Math.max(0, lines.length - height);
+		// Anti-duplication clamp. Never repaint rows that are byte-identical to what
+		// is already committed to native scrollback above the viewport — a second
+		// copy in the active grid duplicates them once the user scrolls up (the
+		// "transcript stacked on itself" / home-screen-reappears bug). The committed
+		// prefix is `#scrollbackHighWater` rows; the new frame still matches it up to
+		// the first changed row, so the genuinely committed-AND-unchanged prefix is
+		// `min(firstChanged, #scrollbackHighWater)`. Anchor at/below that. When the
+		// change starts inside the committed region (content diverged at/above it,
+		// e.g. a tool rewrite or a full transcript reset) the bound collapses and we
+		// paint the bottom-anchored live tail as before (#previousLines is still the
+		// pre-commit frame here, so this prefix diff is against the old frame).
+		let firstChanged = 0;
+		const commonLen = Math.min(lines.length, this.#previousLines.length);
+		while (firstChanged < commonLen && lines[firstChanged] === this.#previousLines[firstChanged]) {
+			firstChanged++;
+		}
+		const viewportTop = Math.max(naturalViewportTop, Math.min(firstChanged, this.#scrollbackHighWater));
 		// Each visible screen row, bottom-anchored, blank past content.
 		const visible: string[] = new Array(height);
 		for (let screenRow = 0; screenRow < height; screenRow++) {
diff --git a/packages/tui/test/viewport-repaint-no-duplicate.test.ts b/packages/tui/test/viewport-repaint-no-duplicate.test.ts
new file mode 100644
index 000000000..c89f63e69
--- /dev/null
+++ b/packages/tui/test/viewport-repaint-no-duplicate.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from "bun:test";
+import { type Component, TERMINAL, TUI } from "@oh-my-pi/pi-tui";
+import { VirtualTerminal } from "./virtual-terminal";
+
+// A non-destructive viewport repaint (the path foreground-tool completion takes on
+// ED3-risk terminals with an unprobeable viewport) must never re-paint rows that
+// are byte-identical to what is already committed to native scrollback above the
+// viewport. Doing so stacks a second copy of the committed prefix into the active
+// grid — the "transcript on top of itself" / header-reappears duplication the user
+// hit. The renderer clamps the repaint anchor to the committed-and-unchanged
+// prefix (`min(firstChanged, #scrollbackHighWater)`).
+
+class LineList implements Component {
+	#lines: string[];
+	constructor(lines: string[]) {
+		this.#lines = [...lines];
+	}
+	invalidate(): void {}
+	render(width: number): string[] {
+		return this.#lines.map(line => line.slice(0, width));
+	}
+	setLines(lines: string[]): void {
+		this.#lines = [...lines];
+	}
+}
+
+async function settle(term: VirtualTerminal): Promise<void> {
+	const tick = Promise.withResolvers<void>();
+	process.nextTick(tick.resolve);
+	await tick.promise;
+	await Bun.sleep(20);
+	await term.flush();
+}
+
+function overrideProbe(term: VirtualTerminal, answer: boolean | undefined): void {
+	(term as unknown as { isNativeViewportAtBottom: () => boolean | undefined }).isNativeViewportAtBottom = () => answer;
+}
+
+const count = (lines: string[], needle: string): number => lines.filter(line => line.includes(needle)).length;
+
+describe("viewport repaint committed-prefix clamp", () => {
+	it("does not duplicate a committed header when the live block collapses", async () => {
+		const savedRisk = TERMINAL.eagerEraseScrollbackRisk;
+		TERMINAL.eagerEraseScrollbackRisk = true;
+		const term = new VirtualTerminal(40, 10);
+		overrideProbe(term, undefined);
+		const tui = new TUI(term);
+		// Row 0 is a stable header that scrolls into native scrollback; the rest is a
+		// live block (a tall streaming tool preview).
+		const tall = ["PINNED-HEADER", ...Array.from({ length: 24 }, (_v, i) => `live-${i}`)];
+		const component = new LineList(tall);
+		tui.addChild(component);
+		try {
+			tui.start();
+			await settle(term);
+			// Foreground streaming is active; the tool then completes, collapsing the
+			// live block to a short settled result while the header stays unchanged.
+			tui.setEagerNativeScrollbackRebuild(true);
+			component.setLines(["PINNED-HEADER", ...Array.from({ length: 7 }, (_v, i) => `settled-${i}`)]);
+			tui.requestRender();
+			await settle(term);
+
+			const scrollback = term.getScrollBuffer();
+			const viewport = term.getViewport();
+			const combined = [...scrollback, ...viewport];
+			// The committed header exists exactly once across saved history + viewport.
+			expect(count(combined, "PINNED-HEADER")).toBe(1);
+			// The settled result is visible.
+			expect(count(viewport, "settled-6")).toBe(1);
+		} finally {
+			tui.stop();
+			TERMINAL.eagerEraseScrollbackRisk = savedRisk;
+		}
+	});
+});

From 136106ba4ff9da1aff0c520ee4a906a7e2ee57c3 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:06:42 +0200
Subject: [PATCH 101/181] fix(coding-agent): kept task context visible after
 first progress snapshot

- Rendered shared `# Goal`/`# Constraints` brief in result frame via buildContextSection helper.
- Undid per-field double-encoding so brief reads cleanly from raw result args.
- Removed header spinner since per-agent body lines already animate.
- Wrapped run summary in bracket glyphs to match bash tool footer.
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 packages/coding-agent/src/task/render.ts      | 70 +++++++++-------
 .../test/task/render-nested-live.test.ts      | 80 ++++++++++++++++++-
 3 files changed, 121 insertions(+), 30 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 5f61b9cac..fea8d08ae 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -19,6 +19,7 @@
 - Changed tool-execution block rendering so the container (`ToolExecutionComponent`) is a transparent passthrough — it no longer inserts a top/bottom blank line, adds left/right padding, or paints a state-colored background behind tool output. Tools with substantial body now self-frame with a muted outline and the tool title in the frame's top bar (`edit`/`apply_patch`, `write`, `ask`, `todo`, `github`, `goal`, `inspect_image`, `search_tool_bm25`, `task`), matching the already-framed `bash`/`read`/`eval`/`debug`/`web_search`/`lsp` blocks, while streaming/in-progress and trivial results collapse to a clean status line. The search-family list tools (`find`, `search`, `ast_grep`) and `job` render frameless/minimal; `find`/`search`/`ast_grep` show a magnifier on success instead of a checkmark, and `job` drops its `Job:` label prefix (the per-job rows are self-describing). The `search_tool_bm25`, `github`, and `inspect_image` frames draw with no background fill, and `inspect_image`'s label was shortened to `Inspect`.
 - Changed the plan-mode active prompt (`prompts/system/plan-mode-active.md`) to make plans decision-complete and cut filler. Added an Objective framing ("another engineer can execute end-to-end without making a single design decision"), a shared "Resolving Unknowns" section (explore discoverable facts before asking; reserve `ask` for non-derivable preferences/tradeoffs with 2–4 options + a recommended default), and a single shared "The Plan" structure (Context / Approach grouped by behavior not file-by-file / ≤5 Critical files / Verification / Assumptions) that replaces the per-branch structure guidance previously duplicated across the iterative and parallel workflows. Added explicit prohibitions on sections that decide nothing (Non-Goals, Out of Scope, Alternatives Considered, Risks/Mitigations boilerplate, Future Work), on enumerating every file/line, and on inventing schema/validation/precedence policy the request never established.
 - Changed completion notifications (`completion.notify`) to fire whenever the agent yields its turn, including in the foreground. The `agent_end` notification was previously gated behind background mode (`isBackgrounded`), so an ordinary foreground turn never emitted one; the gate is gone and the desktop toast now fires on every normal turn completion (still skipped for aborted/error turns and when `completion.notify` is `off`).
+- Changed the in-progress `task` tool block to keep the shared `context` brief (`# Goal` / `# Constraints` background) visible after the first progress snapshot arrives, instead of dropping it the moment the streaming call view was replaced by the result frame, and to stop animating a spinner/clock next to the `Task` frame header while running — the per-agent body lines already carry their own running spinner, so the header now shows a static state icon (matching the completed/failed header icons). The context is rendered through a shared `buildContextSection` helper that also undoes per-field double-encoding, so the brief reads cleanly in the result frame even though `renderResult` receives the raw (un-repaired) tool args.
 
 ### Fixed
 
diff --git a/packages/coding-agent/src/task/render.ts b/packages/coding-agent/src/task/render.ts
index 03cc9649d..6cbb357b9 100644
--- a/packages/coding-agent/src/task/render.ts
+++ b/packages/coding-agent/src/task/render.ts
@@ -30,6 +30,7 @@ import {
 	type SubmitReviewDetails,
 } from "../tools/review";
 import { framedBlock, renderStatusLine } from "../tui";
+import { repairDoubleEncodedJsonString } from "./repair-args";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
 import type { AgentProgress, SingleResult, TaskItem, TaskParams, TaskToolDetails } from "./types";
 
@@ -533,6 +534,21 @@ function renderTaskItemLines(tasks: TaskItem[] | undefined, expanded: boolean, t
 	return lines;
 }
 
+/**
+ * Build the shared-context section (the `# Goal / # Constraints` background
+ * passed to every subagent). Rendered in both the streaming call preview and
+ * the merged result frame so the brief stays visible for the whole task
+ * lifecycle — not just until the first progress snapshot replaces the call view.
+ */
+function buildContextSection(args: TaskParams | undefined, theme: Theme): { lines: string[] } | undefined {
+	// `renderResult` receives the raw tool args (unlike `renderCall`, which is
+	// fed through `repairTaskParams`), so undo any per-field double-encoding here
+	// too. The repair is idempotent on already-clean text.
+	const context = repairDoubleEncodedJsonString(args?.context ?? "").trim();
+	if (!context) return undefined;
+	return { lines: context.split("\n").map(line => (line ? theme.fg("muted", replaceTabs(line)) : "")) };
+}
+
 /**
  * Render the tool call arguments.
  */
@@ -544,15 +560,11 @@ export function renderCall(
 	const showIsolated = "isolated" in args && args.isolated === true;
 	const header = renderStatusLine({ icon: "pending", title: "Task", description: args.agent }, theme);
 	return framedBlock(theme, width => {
-		const context = (args.context ?? "").trim();
 		const taskCount = args.tasks?.length ?? 0;
 		const sections: Array<{ label?: string; lines: string[] }> = [];
 
-		if (context) {
-			sections.push({
-				lines: context.split("\n").map(line => (line ? theme.fg("muted", replaceTabs(line)) : "")),
-			});
-		}
+		const contextSection = buildContextSection(args, theme);
+		if (contextSection) sections.push(contextSection);
 
 		// The per-task preview list only exists to surface dispatched agents while
 		// the call args stream in. Once a result snapshot exists, `renderResult`
@@ -1034,16 +1046,21 @@ export function renderResult(
 	result: { content: Array<{ type: string; text?: string }>; details?: TaskToolDetails },
 	options: RenderResultOptions,
 	theme: Theme,
+	args?: TaskParams,
 ): Component {
 	const fallbackText = result.content.find(c => c.type === "text")?.text ?? "";
 	const details = result.details;
+	const contextSection = buildContextSection(args, theme);
 
 	if (!details) {
 		const text = result.content.find(c => c.type === "text")?.text || "";
 		const header = renderStatusLine({ icon: "success", title: "Task" }, theme);
 		return framedBlock(theme, width => ({
 			header,
-			sections: text ? [{ lines: [theme.fg("dim", truncateToWidth(text, width))] }] : [],
+			sections: [
+				...(contextSection ? [contextSection] : []),
+				...(text ? [{ lines: [theme.fg("dim", truncateToWidth(text, width))] }] : []),
+			],
 			state: "success",
 			borderColor: "borderMuted",
 			width,
@@ -1060,7 +1077,6 @@ export function renderResult(
 	const header = renderStatusLine(
 		{
 			icon,
-			spinnerFrame: options.spinnerFrame,
 			title: "Task",
 			meta: agentCount > 0 ? [`${agentCount} ${agentCount === 1 ? "agent" : "agents"}`] : undefined,
 		},
@@ -1086,24 +1102,19 @@ export function renderResult(
 			const mergeFailedCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && r.error).length;
 			const successCount = details.results.filter(r => !r.aborted && r.exitCode === 0 && !r.error).length;
 			const failCount = details.results.length - successCount - mergeFailedCount - abortedCount;
-			let summary = `${theme.fg("dim", "Total:")} `;
-			if (abortedCount > 0) {
-				summary += theme.fg("error", `${abortedCount} aborted`);
-				if (successCount > 0 || mergeFailedCount > 0 || failCount > 0) summary += theme.sep.dot;
-			}
-			if (successCount > 0) {
-				summary += theme.fg("success", `${successCount} succeeded`);
-				if (mergeFailedCount > 0 || failCount > 0) summary += theme.sep.dot;
-			}
-			if (mergeFailedCount > 0) {
-				summary += theme.fg("warning", `${mergeFailedCount} merge failed`);
-				if (failCount > 0) summary += theme.sep.dot;
-			}
-			if (failCount > 0) {
-				summary += theme.fg("error", `${failCount} failed`);
-			}
-			summary += `${theme.sep.dot}${theme.fg("dim", formatDuration(details.totalDurationMs))}`;
-			lines.push(summary);
+			const summaryParts: string[] = [];
+			if (abortedCount > 0) summaryParts.push(theme.fg("error", `${abortedCount} aborted`));
+			if (successCount > 0) summaryParts.push(theme.fg("success", `${successCount} succeeded`));
+			if (mergeFailedCount > 0) summaryParts.push(theme.fg("warning", `${mergeFailedCount} merge failed`));
+			if (failCount > 0) summaryParts.push(theme.fg("error", `${failCount} failed`));
+			summaryParts.push(theme.fg("dim", formatDuration(details.totalDurationMs)));
+			// Wrap the run summary in the theme's bracket glyphs (dim chrome, colored
+			// counts) to match the bash tool's `[Wall: … | Exit: …]` footer.
+			lines.push(
+				theme.fg("dim", theme.format.bracketLeft) +
+					summaryParts.join(theme.fg("dim", theme.sep.dot)) +
+					theme.fg("dim", theme.format.bracketRight),
+			);
 		}
 
 		const state = isPartial ? "running" : isError ? "error" : mergeFailed ? "warning" : "success";
@@ -1113,7 +1124,10 @@ export function renderResult(
 			const text = fallbackText.trim() ? fallbackText : "No results";
 			return {
 				header,
-				sections: [{ lines: [theme.fg("dim", truncateToWidth(text, width))] }],
+				sections: [
+					...(contextSection ? [contextSection] : []),
+					{ lines: [theme.fg("dim", truncateToWidth(text, width))] },
+				],
 				state,
 				borderColor,
 				width,
@@ -1140,7 +1154,7 @@ export function renderResult(
 		while (lines.length > 0 && lines[0].trim() === "") lines.shift();
 		return {
 			header,
-			sections: lines.length > 0 ? [{ lines }] : [],
+			sections: [...(contextSection ? [contextSection] : []), ...(lines.length > 0 ? [{ lines }] : [])],
 			state,
 			borderColor,
 			width,
diff --git a/packages/coding-agent/test/task/render-nested-live.test.ts b/packages/coding-agent/test/task/render-nested-live.test.ts
index fac5e4431..4042fb5d8 100644
--- a/packages/coding-agent/test/task/render-nested-live.test.ts
+++ b/packages/coding-agent/test/task/render-nested-live.test.ts
@@ -1,9 +1,9 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
 import { resetSettingsForTest, Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import { getThemeByName, setThemeInstance } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
-import type { AgentProgress, SingleResult, TaskToolDetails } from "@oh-my-pi/pi-coding-agent/task";
+import type { AgentProgress, SingleResult, TaskParams, TaskToolDetails } from "@oh-my-pi/pi-coding-agent/task";
 import { taskToolRenderer } from "@oh-my-pi/pi-coding-agent/task/render";
-import { formatNumber } from "@oh-my-pi/pi-utils";
+import { formatDuration, formatNumber } from "@oh-my-pi/pi-utils";
 
 describe("task renderer: nested live rendering", () => {
 	beforeAll(async () => {
@@ -204,4 +204,80 @@ describe("task renderer: nested live rendering", () => {
 		expect(text).not.toContain("ctx");
 		expect(text).not.toContain("Σ");
 	});
+
+	it("keeps the shared context visible while the task is in progress", async () => {
+		const theme = (await getThemeByName("dark"))!;
+		const details: TaskToolDetails = {
+			projectAgentsDir: null,
+			results: [],
+			totalDurationMs: 0,
+			progress: [makeRunningProgress({ id: "Probe", description: "Investigate padding" })],
+		};
+		const args = {
+			agent: "task",
+			context: "# Goal\nHarden the auth stack before the cut.",
+			tasks: [],
+		} as unknown as TaskParams;
+		const component = taskToolRenderer.renderResult(
+			{ content: [{ type: "text", text: "Running 1 agents..." }], details },
+			{ expanded: false, isPartial: true, spinnerFrame: 0 },
+			theme,
+			args,
+		);
+		const text = Bun.stripANSI(component.render(160).join("\n"));
+		// The brief no longer vanishes the moment the first progress snapshot
+		// replaces the streaming call view.
+		expect(text).toContain("# Goal");
+		expect(text).toContain("Harden the auth stack before the cut.");
+	});
+
+	it("renders a static result header while the body keeps the progress spinner", async () => {
+		const theme = (await getThemeByName("dark"))!;
+		const details: TaskToolDetails = {
+			projectAgentsDir: null,
+			results: [],
+			totalDurationMs: 0,
+			progress: [makeRunningProgress({ id: "Probe", description: "Investigate padding" })],
+		};
+		const renderFrame = (frame: number): string[] => {
+			const component = taskToolRenderer.renderResult(
+				{ content: [{ type: "text", text: "Running 1 agents..." }], details },
+				{ expanded: false, isPartial: true, spinnerFrame: frame },
+				theme,
+			);
+			return Bun.stripANSI(component.render(160).join("\n")).split("\n");
+		};
+		const f0 = renderFrame(0);
+		const f1 = renderFrame(1);
+		const header0 = f0.find(l => l.includes("Task"))!;
+		const header1 = f1.find(l => l.includes("Task"))!;
+		const body0 = f0.find(l => l.includes("Probe"))!;
+		const body1 = f1.find(l => l.includes("Probe"))!;
+		// Header is static across spinner frames — no clock ticking beside "Task".
+		expect(header0).toBe(header1);
+		// The per-agent body line still advances its spinner, conveying progress.
+		expect(body0).not.toBe(body1);
+	});
+
+	it("wraps the completed run summary in bracket glyphs, dropping the Total: label", async () => {
+		const theme = (await getThemeByName("dark"))!;
+		const ok = makeCompletedSubResult("Alpha", "did the thing");
+		const bad: SingleResult = { ...makeCompletedSubResult("Beta", "blew up"), exitCode: 1, error: "boom" };
+		const details: TaskToolDetails = {
+			projectAgentsDir: null,
+			results: [ok, bad],
+			totalDurationMs: 39_400,
+		};
+		const component = taskToolRenderer.renderResult(
+			{ content: [{ type: "text", text: "2 agents completed" }], details },
+			{ expanded: false, isPartial: false },
+			theme,
+		);
+		const text = Bun.stripANSI(component.render(160).join("\n"));
+		// Bash-style bracketed footer: dim bracket chrome wrapping colored counts,
+		// with no "Total:" prefix between the bracket and the first count.
+		const expected = `${theme.format.bracketLeft}1 succeeded${theme.sep.dot}1 failed${theme.sep.dot}${formatDuration(39_400)}${theme.format.bracketRight}`;
+		expect(text).toContain(expected);
+		expect(text).not.toContain("Total:");
+	});
 });

From a78f4c67662295438c7d16d7d3f7682aca2316c4 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:14:04 +0200
Subject: [PATCH 102/181] feat(coding-agent): enabled abort reasons to
 propagate and surface through streaming messages

- Added optional `reason` parameters to `Agent.abort` and `AgentSession.abort` APIs.
- Passed abort reasons through interrupt flows into underlying agent cancellation.
- Replaced hard-coded abort text with `resolveAbortLabel` for streaming and replayed messages.
- Fell back to generic `Request was aborted` text when no abort reason was provided.
---
 packages/agent/CHANGELOG.md                   |  1 +
 packages/agent/src/agent-loop.ts              | 45 +++++++++++++++++--
 packages/agent/src/agent.ts                   | 12 +++--
 packages/agent/test/agent-loop.test.ts        | 29 ++++++++++++
 packages/coding-agent/CHANGELOG.md            |  1 +
 .../src/modes/components/assistant-message.ts |  7 +--
 .../src/modes/controllers/event-controller.ts | 20 ++++-----
 .../src/modes/controllers/input-controller.ts | 12 ++---
 .../src/modes/utils/ui-helpers.ts             |  8 +---
 .../coding-agent/src/session/agent-session.ts |  9 +++-
 packages/coding-agent/src/session/messages.ts | 26 +++++++++++
 .../event-controller-abort-render.test.ts     | 31 ++++++++++---
 .../test/input-controller-escape.test.ts      |  4 ++
 .../test/interactive-mode-plan-review.test.ts | 29 ++++++++----
 .../components/transcript-container.test.ts   |  5 ++-
 15 files changed, 184 insertions(+), 55 deletions(-)

diff --git a/packages/agent/CHANGELOG.md b/packages/agent/CHANGELOG.md
index 4d4594e25..7739d05ed 100644
--- a/packages/agent/CHANGELOG.md
+++ b/packages/agent/CHANGELOG.md
@@ -8,6 +8,7 @@
 ### Changed
 
 - Enabled streaming API calls to re-resolve credentials through the `getApiKey` callback when retries occur after authentication-related errors
+- `Agent.abort(reason?)` now forwards `reason` to the underlying `AbortController`, and the synthesized aborted assistant message carries that reason on `errorMessage` (string or non-`AbortError` `Error` message) instead of always defaulting to `"Request was aborted"`. Bare `abort()` is unchanged.
 
 ### Fixed
 
diff --git a/packages/agent/src/agent-loop.ts b/packages/agent/src/agent-loop.ts
index 17ae599c2..c4bddb3cd 100644
--- a/packages/agent/src/agent-loop.ts
+++ b/packages/agent/src/agent-loop.ts
@@ -853,7 +853,14 @@ async function streamAssistantResponse(
 			let detachAbortListener: (() => void) | undefined;
 			if (requestSignal) {
 				if (requestSignal.aborted) {
-					const aborted = emitAbortedAssistantMessage(partialMessage, addedPartial, context, config, stream);
+					const aborted = emitAbortedAssistantMessage(
+						partialMessage,
+						addedPartial,
+						context,
+						config,
+						stream,
+						requestSignal,
+					);
 					await finishChat(aborted);
 					return aborted;
 				}
@@ -875,7 +882,14 @@ async function streamAssistantResponse(
 								if (capped) return capped;
 							}
 							responseIterator.return?.()?.catch(() => {});
-							const aborted = emitAbortedAssistantMessage(partialMessage, addedPartial, context, config, stream);
+							const aborted = emitAbortedAssistantMessage(
+								partialMessage,
+								addedPartial,
+								context,
+								config,
+								stream,
+								requestSignal,
+							);
 							await finishChat(aborted);
 							return aborted;
 						}
@@ -888,7 +902,14 @@ async function streamAssistantResponse(
 							const capped = await finishCappedAssistantMessage();
 							if (capped) return capped;
 						}
-						const aborted = emitAbortedAssistantMessage(partialMessage, addedPartial, context, config, stream);
+						const aborted = emitAbortedAssistantMessage(
+							partialMessage,
+							addedPartial,
+							context,
+							config,
+							stream,
+							requestSignal,
+						);
 						await finishChat(aborted);
 						return aborted;
 					}
@@ -996,14 +1017,30 @@ async function streamAssistantResponse(
 	}
 }
 
+/** Resolve the human-readable reason an abort carried. A caller that aborts via
+ *  `AbortController.abort(reason)` with a string or a non-`AbortError` `Error`
+ *  (e.g. the coding agent's user-interrupt label) gets that text surfaced on the
+ *  synthesized assistant message's `errorMessage`; a bare `abort()` (whose
+ *  `signal.reason` is the default `AbortError` `DOMException`) falls back to the
+ *  generic sentinel that downstream renderers treat as "no specific reason". */
+export function abortReasonText(signal: AbortSignal | undefined): string {
+	const reason = signal?.reason;
+	if (typeof reason === "string" && reason.trim().length > 0) return reason;
+	if (reason instanceof Error && reason.name !== "AbortError" && reason.message.trim().length > 0) {
+		return reason.message;
+	}
+	return "Request was aborted";
+}
+
 function emitAbortedAssistantMessage(
 	partialMessage: AssistantMessage | null,
 	addedPartial: boolean,
 	context: AgentContext,
 	config: AgentLoopConfig,
 	stream: EventStream<AgentEvent, AgentMessage[]>,
+	requestSignal: AbortSignal | undefined,
 ): AssistantMessage {
-	const errorMessage = "Request was aborted";
+	const errorMessage = abortReasonText(requestSignal);
 	const abortedMessage: AssistantMessage = partialMessage
 		? { ...partialMessage, stopReason: "aborted", errorMessage }
 		: {
diff --git a/packages/agent/src/agent.ts b/packages/agent/src/agent.ts
index 5def74e6e..50f69d0c7 100644
--- a/packages/agent/src/agent.ts
+++ b/packages/agent/src/agent.ts
@@ -22,7 +22,7 @@ import {
 	type ToolChoice,
 	type ToolResultMessage,
 } from "@oh-my-pi/pi-ai";
-import { agentLoop, agentLoopContinue } from "./agent-loop";
+import { abortReasonText, agentLoop, agentLoopContinue } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type {
@@ -769,8 +769,8 @@ export class Agent {
 		this.#state.messages.length = 0;
 	}
 
-	abort() {
-		this.#abortController?.abort();
+	abort(reason?: unknown) {
+		this.#abortController?.abort(reason);
 	}
 
 	waitForIdle(): Promise<void> {
@@ -1054,8 +1054,12 @@ export class Agent {
 				}
 			}
 		} catch (err) {
-			const errorMessage = err instanceof Error ? err.message : String(err);
 			const stoppedForAbort = this.#abortController?.signal.aborted === true;
+			const errorMessage = stoppedForAbort
+				? abortReasonText(this.#abortController?.signal)
+				: err instanceof Error
+					? err.message
+					: String(err);
 			const shouldEmitVisibleOutputBlockedError = !stoppedForAbort && isAnthropicOutputBlockedError(errorMessage);
 			const assistantPartial = partial?.role === "assistant" ? partial : undefined;
 			const hadAssistantStart = assistantPartial !== undefined;
diff --git a/packages/agent/test/agent-loop.test.ts b/packages/agent/test/agent-loop.test.ts
index d0913c609..55a9ac7a8 100644
--- a/packages/agent/test/agent-loop.test.ts
+++ b/packages/agent/test/agent-loop.test.ts
@@ -157,6 +157,35 @@ describe("agentLoop with AgentMessage", () => {
 		expect(events.map(event => event.type)).toContain("agent_end");
 	});
 
+	it("surfaces a custom abort reason on the synthesized aborted message", async () => {
+		const context: AgentContext = {
+			systemPrompt: ["You are helpful."],
+			messages: [],
+			tools: [],
+		};
+		const mock = createMockModel();
+		const config: AgentLoopConfig = { model: mock.model, convertToLlm: identityConverter, maxToolCallsPerTurn: 8 };
+		const controller = new AbortController();
+		const streamFn = () => new AssistantMessageEventStream();
+
+		const stream = agentLoop([createUserMessage("Hello")], context, config, controller.signal, streamFn);
+		// Abort with a reason (as the coding agent does for a user Esc interrupt).
+		queueMicrotask(() => controller.abort("Interrupted by user"));
+
+		for await (const _event of stream) {
+			// drain
+		}
+
+		const messages = await stream.result();
+		const finalMessage = messages[messages.length - 1];
+		expect(finalMessage.role).toBe("assistant");
+		if (finalMessage.role !== "assistant") throw new Error("Expected assistant message");
+		expect(finalMessage.stopReason).toBe("aborted");
+		// The reason rides AbortController.abort(reason) onto the message verbatim,
+		// instead of the generic "Request was aborted" default.
+		expect(finalMessage.errorMessage).toBe("Interrupted by user");
+	});
+
 	it("should handle custom message types via convertToLlm", async () => {
 		// Create a custom message type
 		interface CustomNotification {
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index fea8d08ae..59ae91115 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -20,6 +20,7 @@
 - Changed the plan-mode active prompt (`prompts/system/plan-mode-active.md`) to make plans decision-complete and cut filler. Added an Objective framing ("another engineer can execute end-to-end without making a single design decision"), a shared "Resolving Unknowns" section (explore discoverable facts before asking; reserve `ask` for non-derivable preferences/tradeoffs with 2–4 options + a recommended default), and a single shared "The Plan" structure (Context / Approach grouped by behavior not file-by-file / ≤5 Critical files / Verification / Assumptions) that replaces the per-branch structure guidance previously duplicated across the iterative and parallel workflows. Added explicit prohibitions on sections that decide nothing (Non-Goals, Out of Scope, Alternatives Considered, Risks/Mitigations boilerplate, Future Work), on enumerating every file/line, and on inventing schema/validation/precedence policy the request never established.
 - Changed completion notifications (`completion.notify`) to fire whenever the agent yields its turn, including in the foreground. The `agent_end` notification was previously gated behind background mode (`isBackgrounded`), so an ordinary foreground turn never emitted one; the gate is gone and the desktop toast now fires on every normal turn completion (still skipped for aborted/error turns and when `completion.notify` is `off`).
 - Changed the in-progress `task` tool block to keep the shared `context` brief (`# Goal` / `# Constraints` background) visible after the first progress snapshot arrives, instead of dropping it the moment the streaming call view was replaced by the result frame, and to stop animating a spinner/clock next to the `Task` frame header while running — the per-agent body lines already carry their own running spinner, so the header now shows a static state icon (matching the completed/failed header icons). The context is rendered through a shared `buildContextSection` helper that also undoes per-field double-encoding, so the brief reads cleanly in the result frame even though `renderResult` receives the raw (un-repaired) tool args.
+- Changed the label shown when you press Esc to interrupt a streaming turn from the ambiguous `Operation aborted` to `Interrupted by user`, so a deliberate user interrupt no longer reads like an internal failure. The Esc handler threads the reason through `AgentSession.abort({ reason })` → `Agent.abort(reason)` so it rides the `AbortController` onto the aborted assistant message's `errorMessage` and renders verbatim on both the live and replay paths; aborts that carry no reason still fall back to the retry-aware `Operation aborted` generic. The transcript label resolution is centralized in `resolveAbortLabel` (`session/messages.ts`).
 
 ### Fixed
 
diff --git a/packages/coding-agent/src/modes/components/assistant-message.ts b/packages/coding-agent/src/modes/components/assistant-message.ts
index fb9995201..5fac18c12 100644
--- a/packages/coding-agent/src/modes/components/assistant-message.ts
+++ b/packages/coding-agent/src/modes/components/assistant-message.ts
@@ -4,7 +4,7 @@ import { formatNumber } from "@oh-my-pi/pi-utils";
 import { settings } from "../../config/settings";
 import type { AssistantThinkingRenderer } from "../../extensibility/extensions/types";
 import { getMarkdownTheme, theme } from "../../modes/theme/theme";
-import { isSilentAbort } from "../../session/messages";
+import { isSilentAbort, resolveAbortLabel } from "../../session/messages";
 import { resolveImageOptions } from "../../tools/render-utils";
 
 /**
@@ -253,10 +253,7 @@ export class AssistantMessageComponent extends Container {
 		const hasToolCalls = message.content.some(c => c.type === "toolCall");
 		if (!hasToolCalls) {
 			if (message.stopReason === "aborted" && !isSilentAbort(message.errorMessage)) {
-				const abortMessage =
-					message.errorMessage && message.errorMessage !== "Request was aborted"
-						? message.errorMessage
-						: "Operation aborted";
+				const abortMessage = resolveAbortLabel(message.errorMessage);
 				if (hasVisibleContent) {
 					this.#contentContainer.addChild(new Spacer(1));
 				} else {
diff --git a/packages/coding-agent/src/modes/controllers/event-controller.ts b/packages/coding-agent/src/modes/controllers/event-controller.ts
index 3f48c6fe5..06190ae38 100644
--- a/packages/coding-agent/src/modes/controllers/event-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/event-controller.ts
@@ -17,7 +17,7 @@ import { getSymbolTheme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext, TodoPhase } from "../../modes/types";
 import type { PlanApprovalDetails } from "../../plan-mode/approved-plan";
 import type { AgentSessionEvent } from "../../session/agent-session";
-import { isSilentAbort, readPendingDisplayTag } from "../../session/messages";
+import { isSilentAbort, readPendingDisplayTag, resolveAbortLabel } from "../../session/messages";
 import type { ResolveToolDetails } from "../../tools/resolve";
 import { interruptHint } from "../shared";
 
@@ -459,16 +459,14 @@ export class EventController {
 			const silentlyAborted = aborted && isSilentAbort(this.ctx.streamingMessage.errorMessage);
 			const ttsrSilenced = aborted && this.ctx.session.isTtsrAbortPending;
 			if (aborted && !silentlyAborted && !ttsrSilenced) {
-				// Real user-cancel / network / provider abort: surface the standard
-				// operator-facing label. AgentSession.#handleAgentEvent already stamped
-				// SILENT_ABORT_MARKER for the plan-compact transition before this
-				// controller ran, so reaching this branch implies the abort was NOT a
-				// silent internal transition.
-				const retryAttempt = this.ctx.session.retryAttempt;
-				errorMessage =
-					retryAttempt > 0
-						? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
-						: "Operation aborted";
+				// Resolve the operator-facing label: a user-interrupt (Esc) abort
+				// carries USER_INTERRUPT_LABEL on errorMessage (threaded through the
+				// AbortController), which is preserved verbatim; any other abort with
+				// no threaded reason falls back to the retry-aware generic label.
+				// AgentSession.#handleAgentEvent already stamped SILENT_ABORT_MARKER for
+				// the plan-compact transition before this controller ran, so reaching
+				// this branch implies the abort was NOT a silent internal transition.
+				errorMessage = resolveAbortLabel(this.ctx.streamingMessage.errorMessage, this.ctx.session.retryAttempt);
 				this.ctx.streamingMessage.errorMessage = errorMessage;
 			}
 			if (silentlyAborted || ttsrSilenced) {
diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index b8ac1c891..70b166eea 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -9,7 +9,7 @@ import { expandEmoticons } from "../../modes/emoji-autocomplete";
 import { materializeImageReferenceLinks } from "../../modes/image-references";
 import { createPromptActionAutocompleteProvider } from "../../modes/prompt-action-autocomplete";
 import type { InteractiveModeContext } from "../../modes/types";
-import { SKILL_PROMPT_MESSAGE_TYPE, type SkillPromptDetails } from "../../session/messages";
+import { SKILL_PROMPT_MESSAGE_TYPE, type SkillPromptDetails, USER_INTERRUPT_LABEL } from "../../session/messages";
 import { executeBuiltinSlashCommand } from "../../slash-commands/builtin-registry";
 import { isTinyTitleLocalModelKey } from "../../tiny/models";
 import { isLowSignalTitleInput } from "../../tiny/text";
@@ -90,7 +90,7 @@ export class InputController {
 			if (this.ctx.loopModeEnabled) {
 				this.ctx.pauseLoop();
 				if (this.ctx.session.isStreaming) {
-					void this.ctx.session.abort();
+					void this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 				} else {
 					this.ctx.cancelPendingSubmission();
 				}
@@ -120,7 +120,7 @@ export class InputController {
 				this.ctx.isPythonMode = false;
 				this.ctx.updateEditorBorderColor();
 			} else if (this.ctx.session.isStreaming) {
-				void this.ctx.session.abort();
+				void this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 			} else if (!this.ctx.editor.getText().trim()) {
 				// Double-interrupt with empty editor triggers /tree, /branch, or nothing based on setting
 				const action = settings.get("doubleEscapeAction");
@@ -242,7 +242,7 @@ export class InputController {
 			// Empty submit while streaming with queued messages: flush queues immediately
 			if (!text && this.ctx.session.isStreaming && this.ctx.session.queuedMessageCount > 0) {
 				// Abort current stream and let queued messages be processed
-				await this.ctx.session.abort();
+				await this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 				return;
 			}
 
@@ -598,7 +598,7 @@ export class InputController {
 		if (allQueued.length === 0) {
 			this.ctx.updatePendingMessagesDisplay();
 			if (options?.abort) {
-				this.ctx.session.abort();
+				this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 			}
 			return 0;
 		}
@@ -608,7 +608,7 @@ export class InputController {
 		this.ctx.editor.setText(combinedText);
 		this.ctx.updatePendingMessagesDisplay();
 		if (options?.abort) {
-			this.ctx.session.abort();
+			this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 		}
 		return allQueued.length;
 	}
diff --git a/packages/coding-agent/src/modes/utils/ui-helpers.ts b/packages/coding-agent/src/modes/utils/ui-helpers.ts
index ba8f8069c..5b663c5e9 100644
--- a/packages/coding-agent/src/modes/utils/ui-helpers.ts
+++ b/packages/coding-agent/src/modes/utils/ui-helpers.ts
@@ -25,6 +25,7 @@ import type { CompactionQueuedMessage, InteractiveModeContext } from "../../mode
 import {
 	type CustomMessage,
 	isSilentAbort,
+	resolveAbortLabel,
 	SKILL_PROMPT_MESSAGE_TYPE,
 	type SkillPromptDetails,
 } from "../../session/messages";
@@ -341,12 +342,7 @@ export class UiHelpers {
 					!isAbortedSilently && (message.stopReason === "aborted" || message.stopReason === "error");
 				const errorMessage = hasErrorStop
 					? message.stopReason === "aborted"
-						? (() => {
-								const retryAttempt = this.ctx.session.retryAttempt;
-								return retryAttempt > 0
-									? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
-									: "Operation aborted";
-							})()
+						? resolveAbortLabel(message.errorMessage, this.ctx.session.retryAttempt)
 						: message.errorMessage || "Error"
 					: null;
 
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index dd14bd898..792a7ea4b 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -5119,8 +5119,13 @@ export class AgentSession {
 
 	/**
 	 * Abort current operation and wait for agent to become idle.
+	 *
+	 * `reason` (e.g. `USER_INTERRUPT_LABEL`) rides the agent's `AbortController`
+	 * and surfaces verbatim on the aborted assistant message's `errorMessage`, so
+	 * the transcript can distinguish a deliberate user interrupt from an opaque
+	 * abort. Omit it for internal/lifecycle aborts.
 	 */
-	async abort(options?: { goalReason?: "interrupted" | "internal" }): Promise<void> {
+	async abort(options?: { goalReason?: "interrupted" | "internal"; reason?: string }): Promise<void> {
 		this.abortRetry();
 		this.#promptGeneration++;
 		this.#scheduledHiddenNextTurnGeneration = undefined;
@@ -5129,7 +5134,7 @@ export class AgentSession {
 		this.abortBash();
 		this.abortEval();
 		const postPromptDrain = this.#cancelPostPromptTasks();
-		this.agent.abort();
+		this.agent.abort(options?.reason);
 		await postPromptDrain;
 		await this.agent.waitForIdle();
 		await this.#goalRuntime.onTaskAborted({ reason: options?.goalReason ?? "interrupted" });
diff --git a/packages/coding-agent/src/session/messages.ts b/packages/coding-agent/src/session/messages.ts
index 65b6d5de7..c3a1a0484 100644
--- a/packages/coding-agent/src/session/messages.ts
+++ b/packages/coding-agent/src/session/messages.ts
@@ -70,6 +70,32 @@ export function isSilentAbort(errorMessage: string | undefined): boolean {
 	return errorMessage === SILENT_ABORT_MARKER;
 }
 
+/** Reason threaded through `AbortController.abort(reason)` when the user aborts
+ *  the turn with Esc (see `AgentSession.abort`). The agent surfaces it verbatim
+ *  on the aborted assistant message's `errorMessage`, so the transcript reads as
+ *  a deliberate user interrupt instead of an opaque failure. */
+export const USER_INTERRUPT_LABEL = "Interrupted by user";
+
+/** Sentinel `errorMessage` the agent stamps on any abort that carried no custom
+ *  reason (bare `abort()`). Renderers treat it as "no specific reason given". */
+const GENERIC_ABORT_SENTINEL = "Request was aborted";
+
+/** Resolve the operator-facing label for an aborted assistant turn. A custom
+ *  abort reason (e.g. `USER_INTERRUPT_LABEL`) threaded onto `errorMessage` is
+ *  shown verbatim; aborts with no threaded reason fall back to the retry-aware
+ *  generic label. Centralizes the live-stream (`EventController`), replay
+ *  (`ui-helpers`), and component (`AssistantMessageComponent`) render paths so
+ *  they stay in lockstep. */
+export function resolveAbortLabel(errorMessage: string | undefined, retryAttempt = 0): string {
+	if (errorMessage && errorMessage !== GENERIC_ABORT_SENTINEL && !isSilentAbort(errorMessage)) {
+		return errorMessage;
+	}
+	if (retryAttempt > 0) {
+		return `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`;
+	}
+	return "Operation aborted";
+}
+
 /** Extract the optional `__pendingDisplayTag` field from a CustomMessage's
  *  `details` blob. Safe over `unknown`; returns undefined when the field is
  *  absent or non-string. */
diff --git a/packages/coding-agent/test/event-controller-abort-render.test.ts b/packages/coding-agent/test/event-controller-abort-render.test.ts
index 3449925fe..f032e0033 100644
--- a/packages/coding-agent/test/event-controller-abort-render.test.ts
+++ b/packages/coding-agent/test/event-controller-abort-render.test.ts
@@ -7,9 +7,11 @@
  *   C1  errorMessage = SILENT_ABORT_MARKER + aborted
  *       → `updateContent` receives a message with `stopReason: "stop"`;
  *         `errorMessage` is NOT overwritten.
- *   C2  errorMessage = undefined + aborted + no TTSR flag
- *       → `streamingMessage.errorMessage` is set to "Operation aborted";
- *         `updateContent` receives the original message ref.
+ *   C2  errorMessage = undefined (no threaded reason) + aborted + no TTSR flag
+ *       → `streamingMessage.errorMessage` is set to the generic "Operation
+ *         aborted"; `updateContent` receives the original message ref.
+ *   C2b errorMessage = USER_INTERRUPT_LABEL (threaded via AbortController) + aborted
+ *       → the threaded reason is preserved verbatim, NOT replaced by the generic.
  *   C3  isTtsrAbortPending = true + aborted
  *       → `updateContent` receives a message with `stopReason: "stop"`;
  *         `errorMessage` is NOT set (TTSR existing behavior unchanged).
@@ -19,7 +21,7 @@ import type { AssistantMessage } from "@oh-my-pi/pi-ai";
 import { EventController } from "@oh-my-pi/pi-coding-agent/modes/controllers/event-controller";
 import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/types";
 import type { AgentSessionEvent } from "@oh-my-pi/pi-coding-agent/session/agent-session";
-import { SILENT_ABORT_MARKER } from "@oh-my-pi/pi-coding-agent/session/messages";
+import { SILENT_ABORT_MARKER, USER_INTERRUPT_LABEL } from "@oh-my-pi/pi-coding-agent/session/messages";
 
 function makeAssistantMessage(overrides: Partial<AssistantMessage> = {}): AssistantMessage {
 	return {
@@ -103,7 +105,7 @@ describe("EventController #handleMessageEnd abort labeling", () => {
 		expect(ctx.streamingMessage).toBeUndefined();
 	});
 
-	it("C2: errorMessage undefined + aborted + no TTSR -> errorMessage='Operation aborted', updateContent receives original ref", async () => {
+	it("C2: errorMessage undefined (no threaded reason) + aborted + no TTSR -> errorMessage='Operation aborted', updateContent receives original ref", async () => {
 		const message = makeAssistantMessage({ stopReason: "aborted", errorMessage: undefined });
 		const { controller, streamingComponent } = createFixture({
 			streamingMessage: message,
@@ -112,7 +114,7 @@ describe("EventController #handleMessageEnd abort labeling", () => {
 
 		await controller.handleEvent({ type: "message_end", message });
 
-		// Operator-facing label was stamped in-place on the streaming message ref.
+		// No threaded reason -> generic operator-facing label stamped in-place.
 		expect(message.errorMessage).toBe("Operation aborted");
 
 		// `updateContent` saw the original streaming message ref (no `{...streamingMessage, stopReason:"stop"}` spread).
@@ -123,6 +125,23 @@ describe("EventController #handleMessageEnd abort labeling", () => {
 		expect(arg.errorMessage).toBe("Operation aborted");
 	});
 
+	it("C2b: threaded user-interrupt reason on aborted message is preserved, not replaced by the generic label", async () => {
+		const message = makeAssistantMessage({ stopReason: "aborted", errorMessage: USER_INTERRUPT_LABEL });
+		const { controller, streamingComponent } = createFixture({
+			streamingMessage: message,
+			isTtsrAbortPending: false,
+		});
+
+		await controller.handleEvent({ type: "message_end", message });
+
+		// The Esc-interrupt reason rode the AbortController onto errorMessage; the
+		// controller must surface it verbatim instead of overwriting with "Operation aborted".
+		expect(message.errorMessage).toBe(USER_INTERRUPT_LABEL);
+		const arg = streamingComponent.updateContent.mock.calls[0]![0] as AssistantMessage;
+		expect(arg.errorMessage).toBe(USER_INTERRUPT_LABEL);
+		expect(arg.stopReason).toBe("aborted");
+	});
+
 	it("C3: isTtsrAbortPending=true + aborted -> updateContent stopReason='stop', errorMessage NOT set", async () => {
 		const message = makeAssistantMessage({ stopReason: "aborted", errorMessage: undefined });
 		const { controller, streamingComponent } = createFixture({
diff --git a/packages/coding-agent/test/input-controller-escape.test.ts b/packages/coding-agent/test/input-controller-escape.test.ts
index 0ca5d36bb..001ff60ff 100644
--- a/packages/coding-agent/test/input-controller-escape.test.ts
+++ b/packages/coding-agent/test/input-controller-escape.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it, type Mock, vi } from "bun:test";
 import { InputController } from "@oh-my-pi/pi-coding-agent/modes/controllers/input-controller";
 import type { InteractiveModeContext, SubmittedUserInput } from "@oh-my-pi/pi-coding-agent/modes/types";
+import { USER_INTERRUPT_LABEL } from "@oh-my-pi/pi-coding-agent/session/messages";
 
 type Spy = Mock<(...args: unknown[]) => unknown>;
 type StartPendingSubmissionSpy = Mock<InteractiveModeContext["startPendingSubmission"]>;
@@ -245,6 +246,9 @@ describe("InputController escape behavior", () => {
 		expect(spies.cancelPendingSubmission).toHaveBeenCalledTimes(1);
 		expect(spies.clearQueue).toHaveBeenCalledTimes(1);
 		expect(spies.abort).toHaveBeenCalledTimes(1);
+		// The Esc interrupt threads a user-facing reason so the aborted turn and its
+		// synthetic tool results read as a deliberate interrupt, not "Request was aborted".
+		expect(spies.abort).toHaveBeenCalledWith({ reason: USER_INTERRUPT_LABEL });
 	});
 
 	it("prefers aborting bash before aborting an overlapping stream", () => {
diff --git a/packages/coding-agent/test/interactive-mode-plan-review.test.ts b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
index 7867b3538..195ef9778 100644
--- a/packages/coding-agent/test/interactive-mode-plan-review.test.ts
+++ b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
@@ -6,7 +6,7 @@ import { resetSettingsForTest, Settings } from "@oh-my-pi/pi-coding-agent/config
 import { resolveLocalUrlToPath } from "@oh-my-pi/pi-coding-agent/internal-urls";
 import { AssistantMessageComponent } from "@oh-my-pi/pi-coding-agent/modes/components/assistant-message";
 import { initTheme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
-import { SILENT_ABORT_MARKER } from "@oh-my-pi/pi-coding-agent/session/messages";
+import { SILENT_ABORT_MARKER, USER_INTERRUPT_LABEL } from "@oh-my-pi/pi-coding-agent/session/messages";
 import { formatNumber, TempDir } from "@oh-my-pi/pi-utils";
 import { ModelRegistry } from "../src/config/model-registry";
 import type { HookSelectorSlider } from "../src/modes/components/hook-selector";
@@ -893,9 +893,10 @@ describe("InteractiveMode plan review rendering", () => {
 	// ==========================================================================
 	// Phase 6 — D layer: replay-side render branches in AssistantMessageComponent.
 	//
-	// D1 asserts that the persisted `SILENT_ABORT_MARKER` suppresses the red
-	// "Operation aborted" line. D2 is the over-suppression regression guard —
-	// an aborted message with NO marker must still render the line.
+	// D1 asserts that the persisted `SILENT_ABORT_MARKER` suppresses the red abort
+	// line. D2 is the over-suppression regression guard — an aborted message with
+	// NO marker still renders the generic label. D3 covers a threaded interrupt
+	// reason rendering verbatim.
 	// ==========================================================================
 
 	function renderAssistant(message: AssistantMessage, width = 120): string {
@@ -925,20 +926,30 @@ describe("InteractiveMode plan review rendering", () => {
 		};
 	}
 
-	it("D1: Replay of an assistant message with SILENT_ABORT_MARKER + aborted: rendered component contains no /Operation aborted/", () => {
+	it("D1: Replay of an assistant message with SILENT_ABORT_MARKER + aborted: rendered component contains no abort line", () => {
 		const message = buildAbortedAssistantMessage({ errorMessage: SILENT_ABORT_MARKER });
 		const rendered = renderAssistant(message);
-		expect(rendered).not.toMatch(/Operation aborted/);
+		expect(rendered).not.toContain("Operation aborted");
+		expect(rendered).not.toContain(USER_INTERRUPT_LABEL);
 		// The marker itself MUST NOT leak into rendered output either.
 		expect(rendered).not.toContain(SILENT_ABORT_MARKER);
 	});
 
-	it("D2: Replay of an aborted message with no marker + empty content: rendered component DOES contain 'Operation aborted'", () => {
+	it("D2: Replay of an aborted message with no threaded reason + empty content: rendered component DOES contain the generic label", () => {
 		// Over-suppression regression guard: silent path is opt-in via the
-		// persisted marker. A user-cancel abort with no marker and no content
-		// still surfaces the standard label.
+		// persisted marker. An abort with no marker and no threaded reason still
+		// surfaces the generic operator-facing label.
 		const message = buildAbortedAssistantMessage({ content: [], errorMessage: undefined });
 		const rendered = renderAssistant(message);
 		expect(rendered).toContain("Operation aborted");
 	});
+
+	it("D3: Replay of an aborted message carrying a user-interrupt reason renders it verbatim", () => {
+		// The Esc-interrupt reason persisted on errorMessage must render as-is,
+		// not collapse into the generic label.
+		const message = buildAbortedAssistantMessage({ content: [], errorMessage: USER_INTERRUPT_LABEL });
+		const rendered = renderAssistant(message);
+		expect(rendered).toContain(USER_INTERRUPT_LABEL);
+		expect(rendered).not.toContain("Operation aborted");
+	});
 });
diff --git a/packages/coding-agent/test/modes/components/transcript-container.test.ts b/packages/coding-agent/test/modes/components/transcript-container.test.ts
index 19db5f80e..c97cbd5a5 100644
--- a/packages/coding-agent/test/modes/components/transcript-container.test.ts
+++ b/packages/coding-agent/test/modes/components/transcript-container.test.ts
@@ -6,6 +6,7 @@ import { resetSettingsForTest, Settings } from "../../../src/config/settings";
 import { AssistantMessageComponent } from "../../../src/modes/components/assistant-message";
 import { TranscriptContainer } from "../../../src/modes/components/transcript-container";
 import { initTheme } from "../../../src/modes/theme/theme";
+import { USER_INTERRUPT_LABEL } from "../../../src/session/messages";
 
 // Models a transcript block that re-lays-out (tool preview collapsing, assistant
 // message finalizing, late async result) after it has scrolled past the live
@@ -270,14 +271,14 @@ describe("TranscriptContainer", () => {
 			makeAssistantMessage({
 				content: [{ type: "text", text: "The config file write went through despite the interruption." }],
 				stopReason: "aborted",
-				errorMessage: "Operation aborted",
+				errorMessage: USER_INTERRUPT_LABEL,
 			}),
 		);
 		assistant.markTranscriptBlockFinalized();
 
 		const rendered = plain(container.render(80));
 		expect(rendered).toContain("The config file write went through despite the interruption.");
-		expect(rendered).toContain("Operation aborted");
+		expect(rendered).toContain(USER_INTERRUPT_LABEL);
 		expect(rendered).toContain("Copied raw SSE stream");
 		expect(container.getNativeScrollbackLiveRegionStart()).not.toBe(0);
 	});

From 705c937c56a2329933572fd3b5e810faabc360b5 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:24:07 +0200
Subject: [PATCH 103/181] fix(tui): fixed visibleWidth parity and OSC66 width
 metadata behavior

- Fixed `visibleWidth` parity with native width using `Bun.stringWidth` ANSI stripping.
- Fixed tab and OSC66 width parsing with `s=`/`w=` metadata handling.
- Added ASCII and long-string fast paths in `visibleWidth` for faster width checks.
- Consolidated visible-width regression coverage by replacing removed IME/Arabic/Jamo tests with `visible-width.test.ts`.
---
 packages/coding-agent/CHANGELOG.md           |   2 +-
 packages/tui/CHANGELOG.md                    |   3 +
 packages/tui/bench/width.ts                  |   2 +-
 packages/tui/src/utils.ts                    | 151 +++++++++++--------
 packages/tui/test/ime-jamo-cursor.test.ts    | 109 -------------
 packages/tui/test/issue-643-repro.test.ts    | 122 ---------------
 packages/tui/test/text-utils.test.ts         |   3 -
 packages/tui/test/visible-width-jamo.test.ts | 146 ------------------
 packages/tui/test/visible-width.test.ts      |  77 ++++++++++
 9 files changed, 174 insertions(+), 441 deletions(-)
 delete mode 100644 packages/tui/test/ime-jamo-cursor.test.ts
 delete mode 100644 packages/tui/test/issue-643-repro.test.ts
 delete mode 100644 packages/tui/test/visible-width-jamo.test.ts
 create mode 100644 packages/tui/test/visible-width.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 59ae91115..7c664e057 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -20,7 +20,7 @@
 - Changed the plan-mode active prompt (`prompts/system/plan-mode-active.md`) to make plans decision-complete and cut filler. Added an Objective framing ("another engineer can execute end-to-end without making a single design decision"), a shared "Resolving Unknowns" section (explore discoverable facts before asking; reserve `ask` for non-derivable preferences/tradeoffs with 2–4 options + a recommended default), and a single shared "The Plan" structure (Context / Approach grouped by behavior not file-by-file / ≤5 Critical files / Verification / Assumptions) that replaces the per-branch structure guidance previously duplicated across the iterative and parallel workflows. Added explicit prohibitions on sections that decide nothing (Non-Goals, Out of Scope, Alternatives Considered, Risks/Mitigations boilerplate, Future Work), on enumerating every file/line, and on inventing schema/validation/precedence policy the request never established.
 - Changed completion notifications (`completion.notify`) to fire whenever the agent yields its turn, including in the foreground. The `agent_end` notification was previously gated behind background mode (`isBackgrounded`), so an ordinary foreground turn never emitted one; the gate is gone and the desktop toast now fires on every normal turn completion (still skipped for aborted/error turns and when `completion.notify` is `off`).
 - Changed the in-progress `task` tool block to keep the shared `context` brief (`# Goal` / `# Constraints` background) visible after the first progress snapshot arrives, instead of dropping it the moment the streaming call view was replaced by the result frame, and to stop animating a spinner/clock next to the `Task` frame header while running — the per-agent body lines already carry their own running spinner, so the header now shows a static state icon (matching the completed/failed header icons). The context is rendered through a shared `buildContextSection` helper that also undoes per-field double-encoding, so the brief reads cleanly in the result frame even though `renderResult` receives the raw (un-repaired) tool args.
-- Changed the label shown when you press Esc to interrupt a streaming turn from the ambiguous `Operation aborted` to `Interrupted by user`, so a deliberate user interrupt no longer reads like an internal failure. The Esc handler threads the reason through `AgentSession.abort({ reason })` → `Agent.abort(reason)` so it rides the `AbortController` onto the aborted assistant message's `errorMessage` and renders verbatim on both the live and replay paths; aborts that carry no reason still fall back to the retry-aware `Operation aborted` generic. The transcript label resolution is centralized in `resolveAbortLabel` (`session/messages.ts`).
+- Changed the messaging shown when you press Esc to interrupt a streaming turn from the ambiguous `Operation aborted` / `Tool execution was aborted: Request was aborted` to `Interrupted by user`, so a deliberate user interrupt no longer reads like an internal failure. Every Esc/flush interrupt path (`onEscape` while streaming, the queued-message restore-and-abort path, and the empty-submit queue flush) threads the reason through `AgentSession.abort({ reason })` → `Agent.abort(reason)` so it rides the `AbortController` onto the aborted assistant message's `errorMessage`; the turn label renders it verbatim on both the live and replay paths, and the synthetic placeholder results paired with in-flight tool calls now read `Tool execution was aborted: Interrupted by user`. Aborts that carry no reason still fall back to the retry-aware `Operation aborted` generic. Transcript label resolution is centralized in `resolveAbortLabel` (`session/messages.ts`).
 
 ### Fixed
 
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 038704ff8..eb1cbd501 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Changelog
 
 ## [Unreleased]
+
 ### Breaking Changes
 
 - Removed Kitty temp-file image transmission, its startup support probe, the `PI_KITTY_IMAGE_TRANSMISSION` override, and the temp-file helper exports. Kitty/Ghostty image payloads now stay on in-band base64 before placeholder/direct placement, avoiding blank first renders from temp-file load races.
@@ -23,6 +24,8 @@
 
 ### Fixed
 
+- Fixed `visibleWidth()` so terminal column measurements for ANSI and OSC text now match the native truncation/wrapping helpers, including OSC 66 text-sizing spans being counted at their scaled payload width
+- Fixed cursor, padding, and line-fit behavior when strings contain tabs or OSC escapes by aligning `visibleWidth()` with the native text-width model
 - Fixed the transcript — or a re-appearing prior view such as the welcome screen — duplicating itself on terminals without a scroll-position oracle (Ghostty/kitty/iTerm/WezTerm) when a foreground tool completes by rewriting a partly-committed block, or when the transcript is reset. A non-destructive viewport repaint no longer re-paints rows that are byte-identical to what is already committed to native scrollback into the active grid; the repaint anchor is clamped to the committed-and-unchanged prefix (`min(firstChanged, scrollbackHighWater)`).
 
 ## [15.10.0] - 2026-06-06
diff --git a/packages/tui/bench/width.ts b/packages/tui/bench/width.ts
index 9f8820b38..63e45d230 100644
--- a/packages/tui/bench/width.ts
+++ b/packages/tui/bench/width.ts
@@ -5,7 +5,7 @@
  */
 import { visibleWidth as nativeVisibleWidth } from "@oh-my-pi/pi-natives";
 import { getDefaultTabWidth } from "@oh-my-pi/pi-utils";
-import { visibleWidthRaw as hybridVisibleWidth, replaceTabs } from "../src/utils";
+import { visibleWidth as hybridVisibleWidth, replaceTabs } from "../src/utils";
 
 const ITERATIONS = 10_000;
 const WARMUP = 500;
diff --git a/packages/tui/src/utils.ts b/packages/tui/src/utils.ts
index 058a0ff62..47a6e484b 100644
--- a/packages/tui/src/utils.ts
+++ b/packages/tui/src/utils.ts
@@ -4,7 +4,6 @@ import {
 	extractSegments as nativeExtractSegments,
 	sliceWithWidth as nativeSliceWithWidth,
 	truncateToWidth as nativeTruncateToWidth,
-	visibleWidth as nativeVisibleWidth,
 	wrapTextWithAnsi as nativeWrapTextWithAnsi,
 	type SliceResult,
 } from "@oh-my-pi/pi-natives";
@@ -145,44 +144,6 @@ export function padding(n: number): string {
 // Grapheme segmenter (shared instance)
 const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 
-const EXTENDED_PICTOGRAPHIC_REGEX = /\p{Extended_Pictographic}/u;
-
-// Matches CSI (`\x1b[…`) and OSC (`\x1b]…` terminated by BEL/ST) escape
-// sequences. Mirrors the standard ansi-regex coverage so visible-span
-// segmentation lines up with the native ANSI scanner.
-const ANSI_ESCAPE_REGEX =
-	/[\u001b\u009b][[\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\d/#&.:=?%@~_]+)*|[a-zA-Z\d]+(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
-
-function pictographicSpanWidth(span: string): number {
-	let width = 0;
-	for (const { segment } of segmenter.segment(span)) {
-		width += EXTENDED_PICTOGRAPHIC_REGEX.test(segment) ? 2 : nativeVisibleWidth(segment, getDefaultTabWidth());
-	}
-	return width;
-}
-
-// Width fallback for strings that mix ANSI styling with ZWJ pictographic
-// emoji. `Intl.Segmenter` would split an escape sequence into individual
-// graphemes, so the native scanner (which only skips ANSI when handed the
-// complete sequence) double-counts the printable SGR bytes. Excise the ANSI
-// spans first — they contribute zero cells — and apply the pictographic
-// grapheme override only to the visible spans, then sum.
-function visibleWidthByGrapheme(str: string): number {
-	let width = 0;
-	let lastIndex = 0;
-	ANSI_ESCAPE_REGEX.lastIndex = 0;
-	for (let match = ANSI_ESCAPE_REGEX.exec(str); match !== null; match = ANSI_ESCAPE_REGEX.exec(str)) {
-		if (match.index > lastIndex) {
-			width += pictographicSpanWidth(str.slice(lastIndex, match.index));
-		}
-		lastIndex = ANSI_ESCAPE_REGEX.lastIndex;
-	}
-	if (lastIndex < str.length) {
-		width += lastIndex === 0 ? pictographicSpanWidth(str) : pictographicSpanWidth(str.slice(lastIndex));
-	}
-	return width;
-}
-
 /**
  * Get the shared grapheme segmenter instance.
  */
@@ -190,32 +151,104 @@ export function getSegmenter(): Intl.Segmenter {
 	return segmenter;
 }
 
-export function visibleWidthRaw(str: string): number {
-	if (!str) {
-		return 0;
-	}
+// Kitty OSC 66 text-sizing spans: `\x1b]66;<meta>;<payload>` terminated by BEL
+// or ST. `Bun.stringWidth` strips the whole span (payload included) to zero
+// cells, but the payload is visible and scales by the `s=` factor, so each is
+// added back so width matches the native truncate/slice/wrap helpers.
+const OSC66_SPAN_REGEX = /\x1b\]66;([^;]*);([\s\S]*?)(?:\x07|\x1b\\)/g;
+const OSC66_PREFIX = "\x1b]66;";
+const ESC = "\x1b";
+const TAB = "\t";
+const LONG_WIDTH_FAST_PATH_MIN = 128;
 
-	// Fast path: printable ASCII has one cell per code unit. Defer every
-	// control/non-ASCII case (tabs, ANSI/OSC, combining marks, CJK) to the
-	// native text engine so all width/slice/wrap helpers share one Unicode
-	// model instead of mixing Bun.stringWidth quirks with Rust truncation.
-	for (let i = 0; i < str.length; i++) {
-		const code = str.charCodeAt(i);
-		if (code < 0x20 || code > 0x7e) {
-			const tabWidth = getDefaultTabWidth();
-			if (str.includes("\x1b]66;")) return nativeVisibleWidth(str, tabWidth);
-			return str.includes("\u200d") ? visibleWidthByGrapheme(str) : nativeVisibleWidth(str, tabWidth);
-		}
-	}
-	return str.length;
-}
+// Pin Bun.stringWidth semantics to the native width engine and guard against Bun
+// default drift: strip ANSI/OSC (don't count escape bytes) and treat
+// ambiguous-width East Asian chars as narrow (1 cell), matching `unicode-width`'s
+// non-CJK tables that back truncate/slice/wrap. Hoisted so no per-call alloc.
+const STRING_WIDTH_OPTS = { countAnsiEscapeCodes: false, ambiguousIsNarrow: true } as const;
 
 /**
- * Calculate the visible width of a string in terminal columns.
+ * Visible width of a string in terminal columns, excluding ANSI/OSC escapes.
+ *
+ * `Bun.stringWidth` does the heavy lifting (UAX#11 width tables + ANSI/OSC
+ * stripping); this adds the two corrections it omits — tabs (expanded to
+ * `tabWidth` cells) and OSC 66 text-sizing payloads (scaled by `s=`).
  */
 export function visibleWidth(str: string): number {
 	if (!str) return 0;
-	return visibleWidthRaw(str);
+
+	// Long non-escape text is faster through Bun's native scanner than through
+	// a JS printable-ASCII prepass. Escape-bearing strings stay on the scanner
+	// below so CSI/OSC-heavy render output can still bail out at the first ESC.
+	if (str.length >= LONG_WIDTH_FAST_PATH_MIN && !str.includes(ESC)) {
+		let width = Bun.stringWidth(str, STRING_WIDTH_OPTS);
+		let tabCount = 0;
+		for (let tabIndex = str.indexOf(TAB); tabIndex !== -1; tabIndex = str.indexOf(TAB, tabIndex + 1)) {
+			tabCount++;
+		}
+		if (tabCount > 0) width += tabCount * getDefaultTabWidth();
+		return width;
+	}
+
+	let tabCount = 0;
+	let i = 0;
+	for (; i < str.length; i++) {
+		const code = str.charCodeAt(i);
+		if (code < 0x20 || code > 0x7e) {
+			if (code === 0x09) {
+				tabCount++;
+				continue;
+			}
+			break;
+		}
+	}
+	if (i === str.length) {
+		return tabCount === 0 ? str.length : str.length + tabCount * (getDefaultTabWidth() - 1);
+	}
+
+	if (tabCount === 0) {
+		let tabIndex = str.indexOf(TAB, i + 1);
+		if (tabIndex !== -1) {
+			tabCount = 1;
+			for (tabIndex = str.indexOf(TAB, tabIndex + 1); tabIndex !== -1; tabIndex = str.indexOf(TAB, tabIndex + 1)) {
+				tabCount++;
+			}
+		}
+	} else {
+		for (let tabIndex = str.indexOf(TAB, i + 1); tabIndex !== -1; tabIndex = str.indexOf(TAB, tabIndex + 1)) {
+			tabCount++;
+		}
+	}
+
+	// `Bun.stringWidth` is a JSC builtin (no per-call N-API number box, unlike
+	// the native scanner that traps under Bun 1.3.x GC/N-API load). It strips
+	// CSI/OSC to zero cells and shares the native engine's UAX#11 width tables.
+	let width = Bun.stringWidth(str, STRING_WIDTH_OPTS);
+	if (tabCount > 0) width += tabCount * getDefaultTabWidth();
+
+	// OSC 66: add back each stripped span as `scale * (explicit w ?? payload
+	// width)`. Matched rather than replaced to avoid reallocating the string.
+	if (str.includes(OSC66_PREFIX, i)) {
+		OSC66_SPAN_REGEX.lastIndex = 0;
+		for (let m = OSC66_SPAN_REGEX.exec(str); m !== null; m = OSC66_SPAN_REGEX.exec(str)) {
+			let scale = 1;
+			let explicit: number | undefined;
+			for (const part of m[1].split(":")) {
+				// metadata keys are single chars, e.g. `s=2`, `w=5`
+				if (part.indexOf("=") !== 1) continue;
+				const value = Number.parseInt(part.slice(2), 10);
+				if (!Number.isFinite(value)) continue;
+				if (part[0] === "s") {
+					if (value >= 1 && value <= 7) scale = value;
+				} else if (part[0] === "w" && value > 0) {
+					explicit = value;
+				}
+			}
+			width += scale * (explicit ?? Bun.stringWidth(m[2], STRING_WIDTH_OPTS));
+		}
+	}
+
+	return width;
 }
 
 const THAI_LAO_AM_REGEX = /[\u0e33\u0eb3]/;
diff --git a/packages/tui/test/ime-jamo-cursor.test.ts b/packages/tui/test/ime-jamo-cursor.test.ts
deleted file mode 100644
index 665fa8aae..000000000
--- a/packages/tui/test/ime-jamo-cursor.test.ts
+++ /dev/null
@@ -1,109 +0,0 @@
-/**
- * Regression guard for Korean IME cursor positioning in the Input
- * component.
- *
- * Background: macOS Korean IME (2-bul keyboard) emits Hangul Compatibility
- * Jamo (U+3131..U+318E) during composition. Before commit 79e3170c6 the
- * Input.render() computed `cursorCols = visibleWidth(value.slice(0,
- * cursorIndex))` and `Bun.stringWidth` returned 2 for each jamo (per UAX
- * #11 EAW=W), while every macOS terminal renders them as 1 cell.
- *
- * The user-visible bug was a GROWING horizontal gap between the typed
- * jamo and the IME candidate window — every additional jamo doubled the
- * offset because `cursorCols` was N×2 instead of N×1. With 14 jamo typed,
- * the gap was ~14 cells.
- *
- * After the JS-side width correction, `cursorCols` is N×1. The Rust
- * `pi-natives` `sliceWithWidth` still treats jamo as 2 cells (binary
- * package; follow-up), so the cursor marker placement in `Input.render()`
- * has a residual ≤1-cell-per-jamo offset — but the user-visible "growing
- * gap" is gone because the JS-side `cursorCols` no longer doubles.
- *
- * What this test guards:
- *   - The cursor column for a value containing N jamo is **bounded above
- *     by `PROMPT_WIDTH + N`** (the correct cell count after the fix).
- *     Before the fix it would have been ~`PROMPT_WIDTH + 2N`, which is
- *     what the test catches.
- *   - Pure-ASCII and Hangul-syllable baselines are unchanged.
- *
- * What this test does NOT guard:
- *   - The Rust-side `sliceWithWidth` jamo discrepancy. Tracked as a
- *     follow-up; will tighten this test once the Rust crate is rebuilt.
- */
-import { describe, expect, it } from "bun:test";
-import { CURSOR_MARKER } from "@oh-my-pi/pi-tui";
-import { Input } from "@oh-my-pi/pi-tui/components/input";
-import { visibleWidth } from "@oh-my-pi/pi-tui/utils";
-
-/**
- * Drive `text` through `Input.handleInput()` one Unicode code point at a
- * time (mirrors what the IME does — one code point per emitted sequence),
- * then return the visual column where the hardware cursor marker lands
- * in the rendered output.
- */
-function cursorColAfterTyping(text: string, width = 80): number {
-	const input = new Input();
-	(input as unknown as { focused: boolean }).focused = true;
-	for (const char of text) {
-		input.handleInput(char);
-	}
-	const [line] = input.render(width);
-	const markerIdx = line.indexOf(CURSOR_MARKER);
-	if (markerIdx < 0) {
-		throw new Error(`CURSOR_MARKER not found in rendered line: ${JSON.stringify(line)}`);
-	}
-	return visibleWidth(line.slice(0, markerIdx));
-}
-
-const PROMPT_WIDTH = 2; // "> "
-
-// The jamo-cursor regression (PR #1410 / origin issue) only applies on
-// macOS, where terminals render Hangul Compatibility Jamo as 1 cell while
-// UAX#11 (and `Bun.stringWidth`) report 2. Off-darwin both the terminal and
-// the width helper agree on 2, so the doubling regression cannot occur.
-const IS_DARWIN = process.platform === "darwin";
-
-describe("Input cursor column does not grow at 2× per jamo", () => {
-	it("ASCII baseline: cursor lands exactly after the typed text", () => {
-		expect(cursorColAfterTyping("hello")).toBe(PROMPT_WIDTH + 5);
-	});
-
-	it("Hangul syllables: cursor lands exactly after typed text (2 cells each)", () => {
-		expect(cursorColAfterTyping("안녕")).toBe(PROMPT_WIDTH + 4);
-	});
-
-	it.skipIf(!IS_DARWIN)("single jamo: cursor column is at most `PROMPT_WIDTH + 1`", () => {
-		// Before fix: PROMPT_WIDTH + 2 = 4. After fix: ≤ 3.
-		expect(cursorColAfterTyping("ㅁ")).toBeLessThanOrEqual(PROMPT_WIDTH + 1);
-	});
-
-	it.skipIf(!IS_DARWIN)("8 consecutive jamo: cursor column is at most `PROMPT_WIDTH + 8`", () => {
-		// Before fix: PROMPT_WIDTH + 16 = 18. After fix: ≤ 10.
-		expect(cursorColAfterTyping("ㅁㄴㅁㄴㅇㅂㄴㅂ")).toBeLessThanOrEqual(PROMPT_WIDTH + 8);
-	});
-
-	it.skipIf(!IS_DARWIN)("20 consecutive jamo: cursor column is at most `PROMPT_WIDTH + 20`", () => {
-		// Before fix: PROMPT_WIDTH + 40 = 42 (catastrophic gap). After fix: ≤ 22.
-		const jamo = "ㅁㄴㄷㅂㅈㅎㅋㅌㄱㄹ".repeat(2);
-		expect(cursorColAfterTyping(jamo)).toBeLessThanOrEqual(PROMPT_WIDTH + 20);
-	});
-
-	it.skipIf(!IS_DARWIN)("cursor column grows by ≤1 per typed jamo (not 2)", () => {
-		// The regression: each typed jamo would advance cursor by 2 columns
-		// instead of 1, doubling the offset every keystroke. Assert the
-		// per-step delta never exceeds 1.
-		const input = new Input();
-		(input as unknown as { focused: boolean }).focused = true;
-		const jamo = "ㅁㄴㅇㅂㅈㅎㅋㅌㄷㄹ";
-		let prevCol = PROMPT_WIDTH;
-		for (let i = 0; i < jamo.length; i++) {
-			input.handleInput(jamo[i]);
-			const [line] = input.render(80);
-			const markerIdx = line.indexOf(CURSOR_MARKER);
-			const col = visibleWidth(line.slice(0, markerIdx));
-			const delta = col - prevCol;
-			expect(delta).toBeLessThanOrEqual(1);
-			prevCol = col;
-		}
-	});
-});
diff --git a/packages/tui/test/issue-643-repro.test.ts b/packages/tui/test/issue-643-repro.test.ts
deleted file mode 100644
index 1c125fd86..000000000
--- a/packages/tui/test/issue-643-repro.test.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { type Component, TUI, visibleWidth } from "@oh-my-pi/pi-tui";
-import { VirtualTerminal } from "./virtual-terminal";
-
-// Regression test for https://github.com/can1357/oh-my-pi/issues/643
-//
-// Arabic text with tashkeel (nonspacing diacritics, Unicode category Mn) was
-// over-measured: each mark counted as 1 column instead of 0. A line of Quranic
-// text with N marks therefore reported a width N columns larger than what the
-// terminal actually renders, and the renderer crashed with "Rendered line
-// exceeds terminal width" (13.19.0) once enough marks accumulated.
-//
-// Root cause: `Bun.stringWidth` counts Mn marks as 1 column (still true as of
-// Bun 1.3.x). The fix routes every non-ASCII line through the native width
-// engine (Rust `unicode-width`), which measures nonspacing marks as 0 — in
-// agreement with xterm.js (BMP_COMBINING tables) and real terminals.
-//
-// The contract defended here: tashkeel marks contribute zero columns, so a
-// marked-up line whose letter width exactly equals the terminal width renders
-// unclipped on a single row. Over-measurement would either truncate trailing
-// letters (today's fitting behavior) or crash (the original report).
-
-// Tashkeel samples from the issue, with their correct letter-cell widths.
-const TASHKEEL_SAMPLES: ReadonlyArray<readonly [text: string, width: number]> = [
-	["بِسْمِ", 3], // 3 letters + 3 marks
-	["سَابِقُوا", 6], // 6 letters + 3 marks
-	["فَتَبَيَّنُوا", 7], // 7 letters + 5 marks (incl. shadda)
-];
-
-class RawLinesComponent implements Component {
-	#lines: string[];
-
-	constructor(lines: string[]) {
-		this.#lines = [...lines];
-	}
-
-	setLines(lines: string[]): void {
-		this.#lines = [...lines];
-	}
-
-	invalidate(): void {}
-
-	render(): string[] {
-		return [...this.#lines];
-	}
-}
-
-async function settle(term: VirtualTerminal): Promise<void> {
-	const nextTick = Promise.withResolvers<void>();
-	process.nextTick(nextTick.resolve);
-	await nextTick.promise;
-	await Bun.sleep(20);
-	await term.flush();
-}
-
-describe("issue #643: Arabic tashkeel width measurement", () => {
-	it("measures nonspacing tashkeel marks as zero columns", () => {
-		for (const [text, width] of TASHKEEL_SAMPLES) {
-			expect(visibleWidth(text)).toBe(width);
-		}
-		// Mixed ASCII + tashkeel stays on the non-ASCII measurement path.
-		expect(visibleWidth(`ayah: ${TASHKEEL_SAMPLES[1][0]}`)).toBe(6 + TASHKEEL_SAMPLES[1][1]);
-	});
-
-	it("renders a full-width tashkeel line unclipped on a single terminal row", async () => {
-		// "quran: " (7 cells) + 6-cell word = 13 cells — an exact fit at width 13.
-		// The original bug measured the word as 9 (6 letters + 3 marks), making the
-		// line appear 3 columns too wide, so the renderer's width fitting would
-		// truncate real trailing letters before writing.
-		const word = TASHKEEL_SAMPLES[1][0];
-		const line = `quran: ${word}`;
-		const width = 13;
-		expect(visibleWidth(line)).toBe(width);
-
-		const term = new VirtualTerminal(width, 6);
-		const tui = new TUI(term);
-		const component = new RawLinesComponent(["header", line, "tail"]);
-		tui.addChild(component);
-
-		try {
-			tui.start();
-			await settle(term);
-
-			const viewport = term.getViewport().map(row => row.trimEnd());
-			// The full marked-up text survives the round trip: no truncation by the
-			// renderer, no clipping or wrapping by the terminal.
-			expect(viewport[1]).toBe(line);
-			expect(viewport[0]).toBe("header");
-			expect(viewport[2]).toBe("tail");
-			// Exactly one terminal row per logical row — the marks did not push the
-			// line across the right margin.
-			expect(term.getScrollBuffer().length).toBe(6);
-		} finally {
-			tui.stop();
-		}
-	});
-
-	it("keeps row accounting exact when tashkeel rows scroll into native history", async () => {
-		const word = TASHKEEL_SAMPLES[2][0];
-		const width = 24;
-		const height = 5;
-		const term = new VirtualTerminal(width, height);
-		const tui = new TUI(term);
-		const tashkeelRows = Array.from({ length: 8 }, (_v, i) => `ayah-${i} ${word}`);
-		const component = new RawLinesComponent(tashkeelRows);
-		tui.addChild(component);
-
-		try {
-			tui.start();
-			await settle(term);
-
-			// 8 content rows at height 5 → 3 rows pushed into scrollback.
-			const buffer = term.getScrollBuffer().map(row => row.trimEnd());
-			expect(buffer.length).toBe(tashkeelRows.length);
-			for (let i = 0; i < tashkeelRows.length; i++) {
-				expect(buffer[i]).toBe(tashkeelRows[i]);
-			}
-		} finally {
-			tui.stop();
-		}
-	});
-});
diff --git a/packages/tui/test/text-utils.test.ts b/packages/tui/test/text-utils.test.ts
index e118afde2..3f7c820e1 100644
--- a/packages/tui/test/text-utils.test.ts
+++ b/packages/tui/test/text-utils.test.ts
@@ -17,9 +17,6 @@ describe("text utils", () => {
 		expect(visibleWidth("a\tb")).toBe(1 + 3 + 1);
 	});
 
-	it("treats Arabic combining marks as zero-width", () => {
-		expect(visibleWidth("بَسِمَ")).toBe(3);
-	});
 	it("ignores OSC hyperlinks in visible width", () => {
 		const text = "\x1b]8;;https://example.com\x07link\x1b]8;;\x07";
 		expect(visibleWidth(text)).toBe(4);
diff --git a/packages/tui/test/visible-width-jamo.test.ts b/packages/tui/test/visible-width-jamo.test.ts
deleted file mode 100644
index 818a544f1..000000000
--- a/packages/tui/test/visible-width-jamo.test.ts
+++ /dev/null
@@ -1,146 +0,0 @@
-/**
- * Regression guard for the Hangul Compatibility Jamo width correction in
- * `visibleWidthRaw`.
- *
- * `Bun.stringWidth` (and the underlying UAX#11 EAW tables) classify Hangul
- * Compatibility Jamo (U+3131..U+318E) as Wide (2 cells), but every macOS
- * terminal we ship to (Ghostty, Terminal.app, iTerm2) actually renders them
- * as a single cell. Without the correction, `#extractCursorPosition` doubles
- * the column count for every jamo emitted by a Korean IME during
- * composition, displacing the hardware cursor (and therefore the IME
- * candidate window) `N_jamo` cells past the actual glyph.
- *
- * Hangul Syllables (U+AC00..U+D7A3, e.g. `안`) are correctly 2 cells in both
- * Bun and the terminal — make sure the fix did NOT regress that. The
- * Halfwidth Hangul block (U+FFA0..U+FFDC) is already classified as Narrow
- * by Bun, so it does not appear in the correction and the test below is a
- * regression sanity check.
- */
-import { describe, expect, it } from "bun:test";
-import { Ellipsis, sliceWithWidth, truncateToWidth, visibleWidth } from "@oh-my-pi/pi-tui/utils";
-
-// The macOS-only correction (see PR #1410) keeps jamo at 1 cell on darwin;
-// every other platform follows UAX#11 and reports 2 cells per jamo.
-const JAMO_CELLS = process.platform === "darwin" ? 1 : 2;
-
-describe("visibleWidth — Hangul Compatibility Jamo correction", () => {
-	it("single compatibility jamo is 1 cell on darwin, 2 elsewhere", () => {
-		// U+3141 HANGUL LETTER MIEUM
-		expect(visibleWidth("ㅁ")).toBe(JAMO_CELLS);
-		// U+3134 HANGUL LETTER NIEUN
-		expect(visibleWidth("ㄴ")).toBe(JAMO_CELLS);
-		// U+3147 HANGUL LETTER IEUNG
-		expect(visibleWidth("ㅇ")).toBe(JAMO_CELLS);
-		// U+3142 HANGUL LETTER PIEUP
-		expect(visibleWidth("ㅂ")).toBe(JAMO_CELLS);
-		// U+3148 HANGUL LETTER JIEUJ
-		expect(visibleWidth("ㅈ")).toBe(JAMO_CELLS);
-	});
-
-	it("range edges U+3131 and U+318E follow platform width", () => {
-		// U+3131 HANGUL LETTER KIYEOK — first jamo in the block
-		expect(visibleWidth("\u3131")).toBe(JAMO_CELLS);
-		// U+318E HANGUL LETTER ARAEAE — last jamo in the block
-		expect(visibleWidth("\u318e")).toBe(JAMO_CELLS);
-	});
-
-	it("U+3164 HANGUL FILLER (inside the corrected range) follows platform width", () => {
-		// Often emitted by IME for empty-syllable placeholders. The filler is the
-		// one code point in the block that UAX#11 / `unicode-width` classify as
-		// zero-width, so off-darwin it measures 0 cells. On darwin the blanket
-		// jamo correction (U+3131..U+318E → 1) forces it to a single cell.
-		const fillerCells = process.platform === "darwin" ? 1 : 0;
-		expect(visibleWidth("\u3164")).toBe(fillerCells);
-	});
-
-	it("combining marks on compatibility jamo keep the platform base width", () => {
-		// Combining marks add no cells. The native scanner must keep
-		// UnicodeWidthStr's sequence rules, then apply the same local jamo
-		// correction used for standalone code points.
-		expect(visibleWidth("\u3141\u0301")).toBe(JAMO_CELLS);
-		const fillerCells = process.platform === "darwin" ? 1 : 0;
-		expect(visibleWidth("\u3164\u0301")).toBe(fillerCells);
-	});
-
-	it("string of 8 consecutive jamo is 8 cells on darwin, 16 elsewhere", () => {
-		// Matches the user-typed sequence in the v2 screen recording —
-		// before the macOS fix this returned 16 and produced an 8-cell gap.
-		expect(visibleWidth("ㅁㄴㅁㄴㅇㅂㄴㅂ")).toBe(8 * JAMO_CELLS);
-	});
-
-	it("Hangul Syllables (U+AC00..U+D7A3) stay at 2 cells", () => {
-		// `안` U+C548 — composed syllable, must remain 2 cells
-		expect(visibleWidth("안")).toBe(2);
-		// `녕` U+B155 — composed syllable
-		expect(visibleWidth("녕")).toBe(2);
-		// Whole word: 안녕 = 4 cells
-		expect(visibleWidth("안녕")).toBe(4);
-		// First & last in the block, for boundary coverage
-		expect(visibleWidth("\uac00")).toBe(2); // 가
-		expect(visibleWidth("\ud7a3")).toBe(2); // 힣
-	});
-
-	it("mixed ASCII + syllable + jamo strings add correctly", () => {
-		// a (1) + 안 (2) + ㅂ (J) + b (1) = 4 + J
-		expect(visibleWidth("a안ㅂb")).toBe(4 + JAMO_CELLS);
-		// 11 ASCII letters + 1 syllable + 4 jamo = 11 + 2 + 4*J
-		expect(visibleWidth("hello world안ㅁㄴㅇㅂ")).toBe(11 + 2 + 4 * JAMO_CELLS);
-	});
-
-	it("does not regress ASCII fast path or empty input", () => {
-		expect(visibleWidth("")).toBe(0);
-		expect(visibleWidth("hello")).toBe(5);
-		expect(visibleWidth("a")).toBe(1);
-		// Tab character (ASCII 0x09) inside the fast path expands to >2
-		expect(visibleWidth("a\tb")).toBeGreaterThan(2);
-	});
-
-	it("does not change width for other CJK characters", () => {
-		// Chinese: 漢字 (each 2 cells)
-		expect(visibleWidth("漢字")).toBe(4);
-		// Japanese hiragana: あい (each 2 cells)
-		expect(visibleWidth("あい")).toBe(4);
-		// Japanese katakana: アイ (each 2 cells)
-		expect(visibleWidth("アイ")).toBe(4);
-	});
-
-	it("Halfwidth Hangul block is unaffected (already Narrow in Bun)", () => {
-		// U+FFA1 HALFWIDTH HANGUL LETTER KIYEOK — Bun reports 1, untouched.
-		expect(visibleWidth("\uffa1")).toBe(1);
-		// U+FFDC HALFWIDTH HANGUL LETTER I
-		expect(visibleWidth("\uffdc")).toBe(1);
-	});
-});
-
-describe("native text helpers — Hangul Compatibility Jamo correction", () => {
-	// These exercise the Rust-side `char_width_corrected` wrapper in
-	// crates/pi-natives/src/text.rs. They will fail until the native
-	// binding is rebuilt (`bun run build:native`); CI rebuilds natives so
-	// they pass there. Mirrors the TS-side range U+3131..=U+318E.
-
-	it("sliceWithWidth treats jamo per platform width", () => {
-		// 8 jamo at JAMO_CELLS cells each must fit fully within the
-		// platform's natural cell count.
-		const input = "ㅁ".repeat(8);
-		const { text, width } = sliceWithWidth(input, 0, 8 * JAMO_CELLS, true);
-		expect(text).toBe(input);
-		expect(width).toBe(8 * JAMO_CELLS);
-	});
-
-	it("truncateToWidth keeps 8 jamo within their platform budget", () => {
-		// On darwin (1 cell/jamo) 8 jamo fit in 8 cells; off-darwin they need 16.
-		const result = truncateToWidth("ㅁ".repeat(20), 8 * JAMO_CELLS, Ellipsis.Omit);
-		// Strip any trailing pad to count jamo content.
-		const jamo = result.replaceAll(/[^\u3131-\u318E]/g, "");
-		expect(jamo.length).toBe(8);
-	});
-
-	it("native and TS visibleWidth agree on a jamo run", () => {
-		// Cross-layer parity guard: without the native fix, the TS path
-		// (Bun.stringWidth + manual correction) and the native path
-		// (unicode_width) disagreed by a factor of 2.
-		const input = "ㅁㄴㅇㅂㅈㄷㄱㅅ";
-		expect(visibleWidth(input)).toBe(8 * JAMO_CELLS);
-		expect(sliceWithWidth(input, 0, 8 * JAMO_CELLS, true).width).toBe(8 * JAMO_CELLS);
-	});
-});
diff --git a/packages/tui/test/visible-width.test.ts b/packages/tui/test/visible-width.test.ts
new file mode 100644
index 000000000..d1bfd8faa
--- /dev/null
+++ b/packages/tui/test/visible-width.test.ts
@@ -0,0 +1,77 @@
+/**
+ * `visibleWidth` measures terminal column width via `Bun.stringWidth` (a JSC
+ * builtin) instead of the native scanner, to keep the render loop off the
+ * N-API number-boxing path that traps under Bun 1.3.x GC pressure.
+ *
+ * Correctness contract: the result MUST equal the native engine's width for the
+ * same input, because `truncateToWidth` / `sliceWithWidth` / `wrapTextWithAnsi`
+ * cut text using that native model — any divergence makes padding / cursor math
+ * (`width - visibleWidth(...)`) drift. This guards the two corrections layered
+ * on top of `Bun.stringWidth` (tabs, OSC 66 scaling) and catches silent
+ * `Bun.stringWidth` width-table drift across Bun upgrades.
+ */
+import { describe, expect, it } from "bun:test";
+import { visibleWidth as nativeVisibleWidth } from "@oh-my-pi/pi-natives";
+import { getDefaultTabWidth, visibleWidth } from "@oh-my-pi/pi-tui/utils";
+
+const ESC = "\x1b";
+const ST = "\x1b\\";
+const BEL = "\x07";
+const TAB = getDefaultTabWidth();
+
+describe("visibleWidth — parity with the native width engine", () => {
+	const corpus: [string, string][] = [
+		["empty", ""],
+		["ascii", "Pending run: passed"],
+		["styled", `${ESC}[31mred${ESC}[0m text`],
+		["styled-truecolor", `${ESC}[38;2;1;2;3mx${ESC}[0m`],
+		["nested-sgr", `${ESC}[1m${ESC}[31mbold${ESC}[0m${ESC}[0m`],
+		["osc8-st", `${ESC}]8;;https://x.com${ST}link${ESC}]8;;${ST}`],
+		["osc8-bel", `${ESC}]8;;u${BEL}t${ESC}]8;;${BEL}`],
+		["cjk", "日本語のテキスト"],
+		["cjk-mixed", "abc中文def"],
+		["hangul-syllables", "안녕하세요"],
+		["styled-cjk", `${ESC}[1m漢字${ESC}[0m`],
+		["emoji", "👍 done"],
+		["emoji-zwj", "👨‍👩‍👧‍👦"],
+		["emoji-flag", "🇯🇵"],
+		["styled-zwj", `${ESC}[31m👨‍👩‍👧‍👦${ESC}[0m`],
+		["variation-selector", "▶️"],
+		["combining", "e\u0301"],
+		["ambiguous", "§±×→①②③"],
+		["box-drawing", "─│┌┐└┘"],
+		["fullwidth", "１２３"],
+		["halfwidth-kana", "ｱｲｳ"],
+		["rtl-arabic", "مرحبا"],
+		["thai", "สวัสดี"],
+		["tabs", "name\tvalue\tstatus"],
+		["leading-tabs", "\t\tindented"],
+		["osc66-scale", `${ESC}]66;s=2;big${ST}`],
+		["osc66-explicit-w", `${ESC}]66;w=5;Hi${BEL}`],
+		["osc66-scale-and-w", `${ESC}]66;s=3:w=4;X${ST}`],
+		["osc66-cjk", `${ESC}]66;s=2;日本${ST}`],
+		["osc66-inline", `pre ${ESC}]66;s=2;AB${ST} post`],
+		["osc66-multi", `${ESC}]66;s=2;A${ST} ${ESC}]66;s=3;B${ST}`],
+		["osc66-with-tabs", `\t${ESC}]66;s=2;X${ST}\t`],
+	];
+	for (const [name, input] of corpus) {
+		it(name, () => {
+			expect(visibleWidth(input)).toBe(nativeVisibleWidth(input, TAB));
+		});
+	}
+
+	it("strips ANSI (styled text measures as its plain content)", () => {
+		expect(visibleWidth(`${ESC}[31mhello${ESC}[0m`)).toBe(5);
+	});
+
+	it("expands each tab to the configured tab width", () => {
+		expect(visibleWidth("a\tb")).toBe(2 + TAB);
+		expect(visibleWidth("\t\t")).toBe(2 * TAB);
+	});
+
+	it("scales OSC 66 text-sizing payloads by `s=`", () => {
+		expect(visibleWidth(`${ESC}]66;s=2;big${ST}`)).toBe(6); // 2 * width("big")
+		expect(visibleWidth(`${ESC}]66;w=5;Hi${BEL}`)).toBe(5); // explicit width, scale 1
+		expect(visibleWidth(`${ESC}]66;s=3:w=4;X${ST}`)).toBe(12); // 3 * 4
+	});
+});

From 021b62186513ea7b823f21b167f30a77a80af877 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:26:49 +0200
Subject: [PATCH 104/181] perf(tui): removed per-frame line-fit cache from tui
 render path

- Removed the per-frame `#fitLineCache` in `TUI` rendering to avoid rope-string hashing during repaints.
- Deleted `packages/tui/bench/width.ts`, retiring an obsolete visibleWidth benchmark script.
---
 packages/tui/CHANGELOG.md   |   1 +
 packages/tui/bench/width.ts | 182 ------------------------------------
 packages/tui/src/tui.ts     |  31 +-----
 3 files changed, 5 insertions(+), 209 deletions(-)
 delete mode 100644 packages/tui/bench/width.ts

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index eb1cbd501..16fef49df 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -24,6 +24,7 @@
 
 ### Fixed
 
+- Removed the per-frame line-fit `Map` cache from the render timer path to avoid forcing JSC rope-string hashing during scheduled viewport repaints.
 - Fixed `visibleWidth()` so terminal column measurements for ANSI and OSC text now match the native truncation/wrapping helpers, including OSC 66 text-sizing spans being counted at their scaled payload width
 - Fixed cursor, padding, and line-fit behavior when strings contain tabs or OSC escapes by aligning `visibleWidth()` with the native text-width model
 - Fixed the transcript — or a re-appearing prior view such as the welcome screen — duplicating itself on terminals without a scroll-position oracle (Ghostty/kitty/iTerm/WezTerm) when a foreground tool completes by rewriting a partly-committed block, or when the transcript is reset. A non-destructive viewport repaint no longer re-paints rows that are byte-identical to what is already committed to native scrollback into the active grid; the repaint anchor is clamped to the committed-and-unchanged prefix (`min(firstChanged, scrollbackHighWater)`).
diff --git a/packages/tui/bench/width.ts b/packages/tui/bench/width.ts
deleted file mode 100644
index 63e45d230..000000000
--- a/packages/tui/bench/width.ts
+++ /dev/null
@@ -1,182 +0,0 @@
-/**
- * Benchmark: native visibleWidth vs Bun.stringWidth vs hybrid implementation
- *
- * Run: bun packages/tui/bench/visible-width.ts
- */
-import { visibleWidth as nativeVisibleWidth } from "@oh-my-pi/pi-natives";
-import { getDefaultTabWidth } from "@oh-my-pi/pi-utils";
-import { visibleWidth as hybridVisibleWidth, replaceTabs } from "../src/utils";
-
-const ITERATIONS = 10_000;
-const WARMUP = 500;
-
-// Test cases covering different scenarios
-const samples = {
-	// Pure ASCII - different lengths
-	ascii_short: "hello",
-	ascii_medium: "hello world this is a plain ASCII string with some words",
-	ascii_long: "a".repeat(500),
-
-	// ANSI escape codes
-	ansi_simple: "\x1b[31mred\x1b[0m",
-	ansi_complex: "\x1b[31mred text\x1b[0m and \x1b[4munderlined content\x1b[24m with more \x1b[1;33;44mstyles\x1b[0m",
-	ansi_nested: "\x1b[1m\x1b[31m\x1b[4mbold red underline\x1b[0m normal \x1b[32mgreen\x1b[0m",
-
-	// OSC 8 hyperlinks
-	links: "prefix \x1b]8;;https://example.com\x07link text\x1b]8;;\x07 suffix",
-	links_multiple:
-		"Click \x1b]8;;https://a.com\x07here\x1b]8;;\x07 or \x1b]8;;https://b.com\x07there\x1b]8;;\x07 for info",
-
-	// Wide characters (CJK)
-	cjk_short: "日本語",
-	cjk_medium: "日本語のテキストとemoji",
-	cjk_long: "日本語のテキストと中文字符和한국어문자混合在一起形成很长的字符串",
-
-	// Emoji
-	emoji_simple: "👋🌍",
-	emoji_complex: "Hello 👨‍👩‍👧‍👦 family! 🚀✨🎉 Let's go! 🇺🇸🏳️‍🌈",
-	emoji_zwj: "👨‍💻👩‍🔬👨‍👩‍👧‍👦", // ZWJ sequences
-
-	// Mixed content
-	mixed_short: "Hello 世界 🌍",
-	mixed_medium: "\x1b[32mStatus:\x1b[0m 成功 ✓ (took 42ms)",
-	mixed_long:
-		"\x1b[1;34m[INFO]\x1b[0m Processing 日本語テキスト with emoji 🚀 and \x1b]8;;https://example.com\x07links\x1b]8;;\x07 完了",
-
-	// Edge cases
-	tabs: "col1\tcol2\tcol3\tcol4",
-	empty: "",
-	newlines: "line1\nline2\nline3",
-	control_chars: "text\x00with\x01control\x02chars",
-};
-
-// Bun.stringWidth with ANSI stripping (what hybrid uses for short strings)
-function bunStringWidth(str: string): number {
-	if (!str) return 0;
-	return Bun.stringWidth(replaceTabs(str));
-}
-
-interface BenchResult {
-	name: string;
-	totalMs: number;
-	perOpUs: number;
-}
-
-function bench(name: string, fn: () => void): BenchResult {
-	// Warmup
-	for (let i = 0; i < WARMUP; i++) fn();
-
-	const start = Bun.nanoseconds();
-	for (let i = 0; i < ITERATIONS; i++) {
-		fn();
-	}
-	const totalMs = (Bun.nanoseconds() - start) / 1e6;
-	const perOpUs = (totalMs / ITERATIONS) * 1000;
-
-	return { name, totalMs, perOpUs };
-}
-
-function formatResult(r: BenchResult, baseline?: BenchResult): string {
-	const perOp = r.perOpUs.toFixed(3);
-	if (baseline && baseline !== r) {
-		const ratio = r.perOpUs / baseline.perOpUs;
-		const indicator = ratio < 1 ? "faster" : "slower";
-		return `${r.name.padEnd(20)} ${r.totalMs.toFixed(2).padStart(8)}ms  ${perOp.padStart(8)}µs/op  ${ratio.toFixed(2)}x ${indicator}`;
-	}
-	return `${r.name.padEnd(20)} ${r.totalMs.toFixed(2).padStart(8)}ms  ${perOp.padStart(8)}µs/op  (baseline)`;
-}
-
-console.log(`\n${"=".repeat(80)}`);
-console.log(`visibleWidth benchmark: ${ITERATIONS.toLocaleString()} iterations, ${WARMUP} warmup`);
-console.log(`${"=".repeat(80)}\n`);
-
-for (const [sampleName, sample] of Object.entries(samples)) {
-	console.log(`\n--- ${sampleName} (len=${sample.length}) ---`);
-	if (sample.length > 0 && sample.length < 80) {
-		// Show sample for short strings (escape non-printable)
-		const display = sample.replace(/\x1b/g, "\\e").replace(/\x07/g, "\\a");
-		console.log(`    "${display}"`);
-	}
-
-	const results: BenchResult[] = [];
-
-	const tabW = getDefaultTabWidth();
-	results.push(
-		bench("native", () => {
-			nativeVisibleWidth(sample, tabW);
-		}),
-	);
-
-	results.push(
-		bench("bun+strip", () => {
-			bunStringWidth(sample);
-		}),
-	);
-
-	results.push(
-		bench("hybrid", () => {
-			hybridVisibleWidth(sample);
-		}),
-	);
-
-	// Find fastest as baseline
-	const baseline = results.reduce((a, b) => (a.perOpUs < b.perOpUs ? a : b));
-
-	console.log();
-	for (const r of results) {
-		console.log(`  ${formatResult(r, baseline)}`);
-	}
-
-	// Verify correctness
-	const nativeResult = nativeVisibleWidth(sample, tabW);
-	const bunResult = bunStringWidth(sample);
-	const hybridResult = hybridVisibleWidth(sample);
-
-	if (nativeResult !== hybridResult) {
-		console.log(`  ⚠️  MISMATCH: native=${nativeResult}, hybrid=${hybridResult}`);
-	}
-	if (bunResult !== hybridResult && !sample.includes("\x00")) {
-		// Control chars can differ
-		console.log(`  ⚠️  MISMATCH: bun=${bunResult}, hybrid=${hybridResult}`);
-	}
-}
-
-console.log(`\n${"=".repeat(80)}`);
-console.log("Summary");
-console.log(`${"=".repeat(80)}\n`);
-
-// Aggregate by category
-const categories = {
-	ascii: ["ascii_short", "ascii_medium", "ascii_long"],
-	ansi: ["ansi_simple", "ansi_complex", "ansi_nested"],
-	links: ["links", "links_multiple"],
-	cjk: ["cjk_short", "cjk_medium", "cjk_long"],
-	emoji: ["emoji_simple", "emoji_complex", "emoji_zwj"],
-	mixed: ["mixed_short", "mixed_medium", "mixed_long"],
-};
-
-const benchTabW = getDefaultTabWidth();
-
-for (const [category, sampleNames] of Object.entries(categories)) {
-	const categoryResults = { native: 0, bun: 0, hybrid: 0 };
-
-	for (const name of sampleNames) {
-		const sample = samples[name as keyof typeof samples];
-
-		const nativeTime = bench("", () => nativeVisibleWidth(sample, benchTabW)).perOpUs;
-		const bunTime = bench("", () => bunStringWidth(sample)).perOpUs;
-		const hybridTime = bench("", () => hybridVisibleWidth(sample)).perOpUs;
-
-		categoryResults.native += nativeTime;
-		categoryResults.bun += bunTime;
-		categoryResults.hybrid += hybridTime;
-	}
-
-	const fastest = Math.min(categoryResults.native, categoryResults.bun, categoryResults.hybrid);
-	const winner =
-		fastest === categoryResults.native ? "native" : fastest === categoryResults.bun ? "bun+strip" : "hybrid";
-
-	console.log(
-		`${category.padEnd(10)} native: ${categoryResults.native.toFixed(1)}µs  bun: ${categoryResults.bun.toFixed(1)}µs  hybrid: ${categoryResults.hybrid.toFixed(1)}µs  → ${winner} wins`,
-	);
-}
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index b90cd61d9..91a5a1b44 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -433,11 +433,6 @@ type RenderIntent =
 export class TUI extends Container {
 	terminal: Terminal;
 	#previousLines: string[] = [];
-	// Per-frame cache of #fitLineToWidth results. Cleared at the top of every
-	// #doRender (where the frame width is fixed), so it only ever holds entries
-	// for one width. Eliminates the duplicate fit work between the compose pass
-	// and the emitters, plus repeated fits of identical blank padding rows.
-	#fitLineCache = new Map<string, string>();
 	#previousWidth = 0;
 	#previousHeight = 0;
 	#focusedComponent: Component | null = null;
@@ -1541,9 +1536,6 @@ export class TUI extends Container {
 		if (this.#stopped) return;
 		const width = this.terminal.columns;
 		const height = this.terminal.rows;
-		// Reset the per-frame fit memo: width is fixed for this frame, so cached
-		// fit results stay valid across the compose pass and every emitter re-fit.
-		this.#fitLineCache.clear();
 
 		// Fullscreen alt-screen short-circuit. While the topmost visible overlay
 		// requests it, borrow the terminal's alternate buffer (saved/restored by
@@ -2457,25 +2449,10 @@ export class TUI extends Container {
 	}
 
 	#fitLineToWidth(line: string, width: number): string {
-		// Frame-scoped memo: #doRender clears this each frame after reading the
-		// terminal width, so within a frame `width` is constant and this map is
-		// keyed by line alone. The compose/fit pass (#fitLinesToWidth) and every
-		// emitter re-fit the same lines (and many repeated blank rows); the result
-		// is pure for a fixed width, so caching it is byte-identical and skips the
-		// redundant native visibleWidth/truncate work.
-		const cached = this.#fitLineCache.get(line);
-		if (cached !== undefined) return cached;
-		let result: string;
-		if (TERMINAL.isImageLine(line)) {
-			result = line;
-		} else if (visibleWidth(line) <= width) {
-			result = line;
-		} else {
-			const truncated = truncateToWidth(line, width, Ellipsis.Omit);
-			result = truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
-		}
-		this.#fitLineCache.set(line, result);
-		return result;
+		if (TERMINAL.isImageLine(line)) return line;
+		if (visibleWidth(line) <= width) return line;
+		const truncated = truncateToWidth(line, width, Ellipsis.Omit);
+		return truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
 	}
 
 	#lineRewriteSequence(line: string, width: number): string {

From f88cf724f3eadd263025f27db0a2a0bf50fe4fc9 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:29:41 +0200
Subject: [PATCH 105/181] refactor(coding-agent/tools): restructured todo task
 list rendering via shared tree helper

- Replaced the inline todo-phase preview loop in todoToolRenderer with renderTreeList.
- Kept task output generation delegated through formatTodoLine while passing expanded state and preview limits to the shared helper.
---
 packages/coding-agent/src/tools/todo.ts | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/packages/coding-agent/src/tools/todo.ts b/packages/coding-agent/src/tools/todo.ts
index cbadac62b..5022627d9 100644
--- a/packages/coding-agent/src/tools/todo.ts
+++ b/packages/coding-agent/src/tools/todo.ts
@@ -9,8 +9,8 @@ import type { Theme } from "../modes/theme/theme";
 import todoDescription from "../prompts/tools/todo.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
 import type { SessionEntry } from "../session/session-manager";
-import { framedBlock, renderStatusLine } from "../tui";
-import { formatErrorDetail, formatMoreItems, PREVIEW_LIMITS } from "./render-utils";
+import { framedBlock, renderStatusLine, renderTreeList } from "../tui";
+import { formatErrorDetail, PREVIEW_LIMITS } from "./render-utils";
 
 // =============================================================================
 // Types
@@ -852,15 +852,18 @@ export const todoToolRenderer = {
 					bodyLines.push(uiTheme.fg("accent", chalk.bold(formatPhaseDisplayName(phase.name, p + 1))));
 				}
 				const completionKeys = completionKeysByPhase.get(phase.name) ?? EMPTY_COMPLETION_KEYS;
-				const maxItems = expanded
-					? phase.tasks.length
-					: Math.min(phase.tasks.length, PREVIEW_LIMITS.COLLAPSED_ITEMS);
-				for (let i = 0; i < maxItems; i++) {
-					bodyLines.push(`${indent}${formatTodoLine(phase.tasks[i], uiTheme, "", completionKeys, spinnerFrame)}`);
-				}
-				const remaining = phase.tasks.length - maxItems;
-				if (!expanded && remaining > 0) {
-					bodyLines.push(`${indent}${uiTheme.fg("muted", formatMoreItems(remaining, "todo"))}`);
+				const treeLines = renderTreeList(
+					{
+						items: phase.tasks,
+						expanded,
+						maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
+						itemType: "todo",
+						renderItem: todo => formatTodoLine(todo, uiTheme, "", completionKeys, spinnerFrame),
+					},
+					uiTheme,
+				);
+				for (const line of treeLines) {
+					bodyLines.push(`${indent}${line}`);
 				}
 			}
 			bodyLines.push(...renderNoteAttachments(phases, uiTheme, indent));

From 6adf98fd1037b88127bd2ae98338a146377c6d7f Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:40:27 +0200
Subject: [PATCH 106/181] feat(coding-agent): added OSC5522 enhanced paste
 support for local image and text inserts

- Added OSC5522 parsing and a payload controller that prefers image MIME and reassembles chunks.
- Added bracketed image-path detection and `onPasteImagePath` callback wiring in the editor.
- Added local image-path paste insertion with fallback to text paste on image-size errors.
- Added `Editor.pasteText()` and OSC5522 disable sequencing on terminal cleanup.
---
 docs/keybindings.md                           |   2 +
 packages/coding-agent/CHANGELOG.md            |  17 +-
 .../src/modes/components/custom-editor.ts     |  23 ++
 .../src/modes/controllers/input-controller.ts | 157 +++++++++-----
 .../coding-agent/src/utils/enhanced-paste.ts  | 202 ++++++++++++++++++
 .../test/custom-editor-keybindings.test.ts    |  19 +-
 .../test/utils/enhanced-paste.test.ts         | 109 ++++++++++
 packages/tui/CHANGELOG.md                     |   4 +-
 packages/tui/src/components/editor.ts         |   5 +
 packages/tui/src/terminal.ts                  |   2 +
 packages/tui/src/tui.ts                       |  16 ++
 packages/tui/test/start-listener.test.ts      |  24 +++
 packages/tui/test/virtual-terminal.ts         |   2 +-
 13 files changed, 520 insertions(+), 62 deletions(-)
 create mode 100644 packages/coding-agent/src/utils/enhanced-paste.ts
 create mode 100644 packages/coding-agent/test/utils/enhanced-paste.test.ts
 create mode 100644 packages/tui/test/start-listener.test.ts

diff --git a/docs/keybindings.md b/docs/keybindings.md
index 9fa872698..dfc881bbe 100644
--- a/docs/keybindings.md
+++ b/docs/keybindings.md
@@ -44,4 +44,6 @@ app.stt.toggle: []
 
 On Windows Terminal, `Ctrl+V` may be handled by the terminal paste command before `omp` sees it; use the `Alt+V` fallback when clipboard image paste appears to do nothing. Windows Terminal also swallows `Ctrl+Enter`, so the follow-up shortcut also binds `Ctrl+Q` — the same chord GitHub Copilot CLI uses. If your existing `keybindings.yml` already assigns `Ctrl+Q` to another action, that user remap wins and follow-up keeps `Ctrl+Enter` unless you explicitly bind `app.message.followUp`.
 
+Terminals that implement OSC 5522 enhanced paste can send clipboard MIME data directly to `omp`; image pastes are attached as `[Image #N]`, while text/plain paste events keep normal paste behavior. When OSC 5522 is unavailable, bracketed paste still handles text, and a pasted single image-file path is loaded as an image when the file is readable from the `omp` host.
+
 Older unqualified action names are migrated when `keybindings.yml` is loaded, but new docs and new configs should use the namespaced action IDs above. Existing `keybindings.json` files are still accepted and migrated to `keybindings.yml`; `keybindings.yaml` is also accepted.
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 7c664e057..1632c86fe 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,15 +1,18 @@
 # Changelog
 
 ## [Unreleased]
-
 ### Added
 
+- Added OSC 5522 enhanced paste handling in `InputController`, so terminal clipboard events are decoded as image or text payloads and inserted without passing raw paste sequences to the editor
+- Added bracketed image-path paste support in `CustomEditor` so a single pasted image file path (PNG/JPEG/GIF/WEBP) is loaded from disk and inserted as an image candidate
+- Added direct support for `Image #N` insertion from pasted local image paths by routing successful image-path pastes through the same image normalization and resize flow as clipboard image pastes
 - Added `/fresh` to rotate the provider-facing session id and clear in-memory provider stream/cache state without changing the local session file.
 - Added a `ChatBlock` transcript primitive (`modes/components/chat-block.ts`) and a single `ctx.present(...)` sink (with `ctx.resetTranscript()`) so chat output is mounted in one place instead of the repeated `chatContainer.addChild(...)` + `ui.requestRender()` pattern scattered across controllers. `ChatBlock` carries a React/Svelte-style lifecycle — `onMount` starts effects, `onCleanup` registers teardown, `finish()` self-completes (stops timers and freezes the block at its final content), and `dispose()`/`resetTranscript()` tears everything down — so animated blocks own their own resources instead of leaking `setInterval`/`requestRender` bookkeeping into callers. The MCP "Connecting…" spinner is now such a block.
 - Added a `framedBlock` output-block helper (`tui/output-block.ts`) plus a `borderColor` override and `applyBg: false` (no background fill) on output blocks, a `renderStatusLine` `iconOverride`, and an `icon.search` (magnifier) theme symbol — so tool renderers can draw self-contained muted-outline frames and search-family tools can show a magnifier instead of a checkmark.
 
 ### Changed
 
+- Changed the `todo` tool result renderer to stop redrawing every phase's full task list on each update: when a multi-phase list is rendered collapsed (the default, not manually expanded), only phases the latest update touched — the phase holding the in_progress task, any phase with a just-completed task, and phases named by the ops that ran (`init` counts as touching all) — render their tasks; untouched phases collapse to a one-line `N. Name  done/total` summary. When call args are unavailable (e.g. transcript rebuilds) it falls back to the in_progress/completed-transition signals, and the manual expand toggle still shows every task. Also dropped the blank separator line previously inserted between phases.
 - Changed non-agent API operations (title and commit-message generation, image generation, web search, eval `llm()`, auto-thinking classifier, memory consolidation) to use session-aware API key resolution with auth retries via `registry.resolver()` / `authStorage.resolver()`, refreshing the active credential before rotating to another account
 - Changed image generation to wrap every provider fetch branch in `withAuth`, so 401 / usage-limit errors trigger credential force-refresh and rotation for authStorage-backed providers (OpenAI-hosted, antigravity, xai-oauth) while env-only providers (openrouter, gemini) stay single-attempt
 - Changed web-search providers using `authStorage.getApiKey` (anthropic, exa, tavily, parallel, synthetic, zai, kimi) to wrap HTTP calls in `withAuth` for automatic credential rotation on 401 / usage-limit errors
@@ -22,8 +25,13 @@
 - Changed the in-progress `task` tool block to keep the shared `context` brief (`# Goal` / `# Constraints` background) visible after the first progress snapshot arrives, instead of dropping it the moment the streaming call view was replaced by the result frame, and to stop animating a spinner/clock next to the `Task` frame header while running — the per-agent body lines already carry their own running spinner, so the header now shows a static state icon (matching the completed/failed header icons). The context is rendered through a shared `buildContextSection` helper that also undoes per-field double-encoding, so the brief reads cleanly in the result frame even though `renderResult` receives the raw (un-repaired) tool args.
 - Changed the messaging shown when you press Esc to interrupt a streaming turn from the ambiguous `Operation aborted` / `Tool execution was aborted: Request was aborted` to `Interrupted by user`, so a deliberate user interrupt no longer reads like an internal failure. Every Esc/flush interrupt path (`onEscape` while streaming, the queued-message restore-and-abort path, and the empty-submit queue flush) threads the reason through `AgentSession.abort({ reason })` → `Agent.abort(reason)` so it rides the `AbortController` onto the aborted assistant message's `errorMessage`; the turn label renders it verbatim on both the live and replay paths, and the synthetic placeholder results paired with in-flight tool calls now read `Tool execution was aborted: Interrupted by user`. Aborts that carry no reason still fall back to the retry-aware `Operation aborted` generic. Transcript label resolution is centralized in `resolveAbortLabel` (`session/messages.ts`).
 
+### Removed
+
+- Removed the `/background` (and `/bg`) slash command and the background-mode subsystem it was the sole entry point for — `InteractiveMode.isBackgrounded`, `createBackgroundUiContext`, `handleBackgroundEvent`, and every `isBackgrounded` guard across the input/event/extension-UI controllers and UI helpers. The command suspended the whole process group via `SIGTSTP` (a leftover testing shortcut) instead of detaching the running agent, which is not the expected workflow — use terminal panes or a multiplexer instead.
+
 ### Fixed
 
+- Fixed pasted image-file paths that cannot be loaded to fall back to normal text paste with status feedback instead of disappearing.
 - Fixed tool-output file paths not being clickable OSC 8 `file://` hyperlinks in several renderers. `read` titles for plain text and image files (the common case) emitted no link at all because the renderer only linked when a `resolvedPath` was recorded — which the ordinary file/image read paths never set, keeping the absolute path only in `meta.source`; the renderer now falls back to that source path. `write` headers were never wrapped in a hyperlink and now link to the absolute path written (file, archive entry, SQLite, and conflict resolutions). `edit`/`apply_patch` headers wrapped the model-supplied (often cwd-relative) argument path, producing a root-anchored `file:///rel/path` URI; they now link the absolute `details.path` instead. Finally, `search`, `ast_grep`, and `ast_edit` produced doubled link targets (`/proj/src/src/file.ts`) for searches scoped to a subdirectory, because the renderer resolved the cwd-relative display paths against the scope directory rather than cwd — the scoped-search base is now the session cwd (with the scoped file's absolute path still seeding single-file body lines).
 - Fixed `omp dry-balance --bench` to recover from 401 token failures by re-minting the failing OAuth credential in place before switching accounts
 - Fixed the bash tool corrupting commands that embed multi-byte UTF-8 (e.g. `✓`/`×` inside a `grep -E` pattern) ahead of a trailing `| head`/`| tail`. The `bash.stripTrailingHeadTail` rewrite cut at char-offset positions reported by `brush-parser` while slicing the command by byte offset, so the trailing-pipe strip landed mid-pattern and dropped the closing quote — turning `… |✓|×|XCTAssert" | tail -80` into `… |✓|×-80` and making execution fail with `pi-natives:command: unterminated double quote`. Fixed in `pi_shell::fixup` (`@oh-my-pi/pi-natives`).
@@ -36,15 +44,8 @@
 - Fixed the collapsed tool-output expand hint rendering double brackets (e.g. `((Ctrl+O for more))`) — the `EXPAND_HINT` text already carried its own parentheses and then `formatExpandHint` wrapped it again with the theme's bracket glyphs. The hint now resolves the key actually bound to `app.tools.expand` at render time and reads `⟨<key>: Expand⟩` (e.g. `⟨Ctrl+O: Expand⟩`), so a single bracket pair surrounds it and a user remap of the expand keybinding is reflected instead of a hard-coded `Ctrl+O`.
 - Fixed the `edit`/`apply_patch` tool dropping its outlined frame while streaming/in-progress (only the final result was framed); the in-progress diff preview now renders inside the same muted frame as the completed result.
 - Fixed the `todo` and `job` tools rendering a success icon and success styling on a failed/error result; error results now show the error icon and a red frame border.
-
-### Fixed
-
 - Fixed `debug` tool refusing every `dlv` launch on Go modules. The launch handler ran `validateLaunchProgram` before adapter selection and rejected any directory program with `launch program resolves to a directory`, while dlv's default `mode=debug` requires a Go package path (a directory or `.go` source file). Adapter resolution now precedes validation, directory programs prefer adapters that advertise `acceptsDirectoryProgram` before falling back to native extensionless debuggers, the rejection only fires when the resolved adapter does not advertise that flag (set on `dlv` in `dap/defaults.json`), and dlv's `mode` is derived from the program shape — directories and `.go` files launch as `mode=debug`, other files as `mode=exec` — so `omp` can debug both Go packages and pre-built binaries ([#2020](https://github.com/can1357/oh-my-pi/issues/2020)).
 
-### Removed
-
-- Removed the `/background` (and `/bg`) slash command and the background-mode subsystem it was the sole entry point for — `InteractiveMode.isBackgrounded`, `createBackgroundUiContext`, `handleBackgroundEvent`, and every `isBackgrounded` guard across the input/event/extension-UI controllers and UI helpers. The command suspended the whole process group via `SIGTSTP` (a leftover testing shortcut) instead of detaching the running agent, which is not the expected workflow — use terminal panes or a multiplexer instead.
-
 ## [15.10.0] - 2026-06-06
 
 ### Breaking Changes
diff --git a/packages/coding-agent/src/modes/components/custom-editor.ts b/packages/coding-agent/src/modes/components/custom-editor.ts
index aaf0511a9..835ea4ec3 100644
--- a/packages/coding-agent/src/modes/components/custom-editor.ts
+++ b/packages/coding-agent/src/modes/components/custom-editor.ts
@@ -47,6 +47,21 @@ const DEFAULT_ACTION_KEYS: Record<ConfigurableEditorAction, KeyId[]> = {
 	"app.clipboard.copyPrompt": ["alt+shift+c"],
 };
 
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+const BRACKETED_IMAGE_PATH_REGEX = /\.(?:png|jpe?g|gif|webp)$/i;
+
+export function extractBracketedImagePastePath(data: string): string | undefined {
+	if (!data.startsWith(BRACKETED_PASTE_START)) return undefined;
+	const endIndex = data.indexOf(BRACKETED_PASTE_END, BRACKETED_PASTE_START.length);
+	if (endIndex === -1 || endIndex + BRACKETED_PASTE_END.length !== data.length) return undefined;
+
+	const pasted = data.slice(BRACKETED_PASTE_START.length, endIndex).trim();
+	if (!pasted || /[\r\n]/.test(pasted)) return undefined;
+	if (!BRACKETED_IMAGE_PATH_REGEX.test(pasted)) return undefined;
+	return pasted;
+}
+
 /**
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */
@@ -82,6 +97,8 @@ export class CustomEditor extends Editor {
 	onCopyPrompt?: () => void;
 	/** Called when the configured image-paste shortcut is pressed. */
 	onPasteImage?: () => Promise<boolean>;
+	/** Called when a bracketed paste contains exactly one image-file path. */
+	onPasteImagePath?: (path: string) => void;
 	/** Called when the configured raw text-paste shortcut is pressed. */
 	onPasteTextRaw?: () => void;
 	/** Called when the configured dequeue shortcut is pressed. */
@@ -137,6 +154,12 @@ export class CustomEditor extends Editor {
 			return;
 		}
 
+		const pastedImagePath = extractBracketedImagePastePath(data);
+		if (pastedImagePath && this.onPasteImagePath) {
+			this.onPasteImagePath(pastedImagePath);
+			return;
+		}
+
 		// Intercept configured image paste (async - fires and handles result)
 		if (this.#matchesAction(data, "app.clipboard.pasteImage") && this.onPasteImage) {
 			void this.onPasteImage();
diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index 70b166eea..a16f52467 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -1,4 +1,5 @@
 import * as fs from "node:fs/promises";
+import type { ImageContent } from "@oh-my-pi/pi-ai";
 import type { AutocompleteProvider, SlashCommand } from "@oh-my-pi/pi-tui";
 import { $env, logger, sanitizeText } from "@oh-my-pi/pi-utils";
 import { getRoleInfo } from "../../config/model-registry";
@@ -17,7 +18,8 @@ import { tinyTitleClient } from "../../tiny/title-client";
 import type { TinyTitleProgressEvent } from "../../tiny/title-protocol";
 import { copyToClipboard, readImageFromClipboard, readTextFromClipboard } from "../../utils/clipboard";
 import { getEditorCommand, openInEditor } from "../../utils/external-editor";
-import { ensureSupportedImageInput } from "../../utils/image-loading";
+import { EnhancedPasteController } from "../../utils/enhanced-paste";
+import { ensureSupportedImageInput, ImageInputTooLargeError, loadImageInput } from "../../utils/image-loading";
 import { resizeImage } from "../../utils/image-resize";
 import { generateSessionTitle, setSessionTerminalTitle } from "../../utils/title-generator";
 
@@ -39,6 +41,8 @@ const TINY_TITLE_PROGRESS_REVEAL_DELAY_MS = 1_000;
 export class InputController {
 	constructor(private ctx: InteractiveModeContext) {}
 
+	#enhancedPaste?: EnhancedPasteController;
+
 	#showTinyTitleDownloadProgress(modelKey: string): void {
 		if (!isTinyTitleLocalModelKey(modelKey)) return;
 		const component = new TinyTitleDownloadProgressComponent(modelKey);
@@ -175,6 +179,7 @@ export class InputController {
 			this.ctx.keybindings.getKeys("app.clipboard.pasteImage"),
 		);
 		this.ctx.editor.onPasteImage = () => this.handleImagePaste();
+		this.ctx.editor.onPasteImagePath = path => void this.handleImagePathPaste(path);
 		this.ctx.editor.setActionKeys(
 			"app.clipboard.pasteTextRaw",
 			this.ctx.keybindings.getKeys("app.clipboard.pasteTextRaw"),
@@ -222,6 +227,8 @@ export class InputController {
 			this.ctx.editor.setCustomKeyHandler(key, () => this.ctx.showSessionObserver());
 		}
 
+		this.#setupEnhancedPaste();
+
 		this.ctx.editor.onChange = (text: string) => {
 			const wasBashMode = this.ctx.isBashMode;
 			const wasPythonMode = this.ctx.isPythonMode;
@@ -234,6 +241,24 @@ export class InputController {
 		};
 	}
 
+	#setupEnhancedPaste(): void {
+		if (this.#enhancedPaste) return;
+
+		this.#enhancedPaste = new EnhancedPasteController({
+			write: data => this.ctx.ui.terminal.write(data),
+			pasteText: text => {
+				this.ctx.editor.pasteText(text);
+				this.ctx.ui.requestRender(false, { allowUnknownViewportMutation: true });
+			},
+			pasteImage: async image => {
+				await this.#normalizeAndInsertPastedImage(image, `Unsupported pasted image format: ${image.mimeType}`);
+			},
+			showStatus: message => this.ctx.showStatus(message),
+		});
+		this.ctx.ui.addInputListener(data => (this.#enhancedPaste?.handleInput(data) ? { consume: true } : undefined));
+		this.ctx.ui.addStartListener(() => this.#enhancedPaste?.enable());
+	}
+
 	setupEditorSubmitHandler(): void {
 		this.ctx.editor.onSubmit = async (text: string) => {
 			text = text.trim();
@@ -613,62 +638,92 @@ export class InputController {
 		return allQueued.length;
 	}
 
-	async handleImagePaste(): Promise<boolean> {
-		try {
-			const image = await readImageFromClipboard();
-			if (image) {
-				const base64Data = image.data.toBase64();
-				let imageData = await ensureSupportedImageInput({
-					type: "image",
-					data: base64Data,
-					mimeType: image.mimeType,
-				});
-				if (!imageData) {
-					this.ctx.showStatus(`Unsupported clipboard image format: ${image.mimeType}`);
-					return false;
-				}
-				if (settings.get("images.autoResize")) {
-					try {
-						const resized = await resizeImage({
-							type: "image",
-							data: imageData.data,
-							mimeType: imageData.mimeType,
-						});
-						imageData = { type: "image", data: resized.data, mimeType: resized.mimeType };
-					} catch {
-						// Keep the normalized image when resize fails.
-					}
-				}
+	async #insertPendingImage(imageData: ImageContent): Promise<void> {
+		const imageLink = (
+			await materializeImageReferenceLinks(
+				[
+					{
+						type: "image",
+						data: imageData.data,
+						mimeType: imageData.mimeType,
+					},
+				],
+				this.ctx.sessionManager.putBlob.bind(this.ctx.sessionManager),
+			)
+		)?.[0];
+		this.ctx.pendingImages.push({
+			type: "image",
+			data: imageData.data,
+			mimeType: imageData.mimeType,
+		});
+		this.ctx.pendingImageLinks.push(imageLink);
+		this.ctx.editor.imageLinks = this.ctx.pendingImageLinks;
+		const imageNum = this.ctx.pendingImages.length;
+		this.ctx.editor.insertText(`[Image #${imageNum}] `);
+		this.ctx.ui.requestRender(false, { allowUnknownViewportMutation: true });
+	}
 
-				const imageLink = (
-					await materializeImageReferenceLinks(
-						[
-							{
-								type: "image",
-								data: imageData.data,
-								mimeType: imageData.mimeType,
-							},
-						],
-						this.ctx.sessionManager.putBlob.bind(this.ctx.sessionManager),
-					)
-				)?.[0];
-				this.ctx.pendingImages.push({
+	async #normalizeAndInsertPastedImage(image: ImageContent, unsupportedMessage: string): Promise<boolean> {
+		let imageData = await ensureSupportedImageInput(image);
+		if (!imageData) {
+			this.ctx.showStatus(unsupportedMessage);
+			return false;
+		}
+		if (settings.get("images.autoResize")) {
+			try {
+				const resized = await resizeImage({
 					type: "image",
 					data: imageData.data,
 					mimeType: imageData.mimeType,
 				});
-				this.ctx.pendingImageLinks.push(imageLink);
-				this.ctx.editor.imageLinks = this.ctx.pendingImageLinks;
-				// Insert placeholder at cursor like Claude does
-				const imageNum = this.ctx.pendingImages.length;
-				const placeholder = `[Image #${imageNum}]`;
-				this.ctx.editor.insertText(`${placeholder} `);
-				this.ctx.ui.requestRender();
-				return true;
+				imageData = { type: "image", data: resized.data, mimeType: resized.mimeType };
+			} catch {
+				// Keep the normalized image when resize fails.
 			}
-			// No image in clipboard - show hint
-			this.ctx.showStatus("No image in clipboard (use terminal paste for text)");
-			return false;
+		}
+		await this.#insertPendingImage(imageData);
+		return true;
+	}
+
+	async handleImagePathPaste(path: string): Promise<void> {
+		try {
+			const image = await loadImageInput({
+				path,
+				cwd: this.ctx.sessionManager.getCwd(),
+				autoResize: false,
+			});
+			if (!image) {
+				this.ctx.editor.pasteText(path);
+				this.ctx.ui.requestRender(false, { allowUnknownViewportMutation: true });
+				this.ctx.showStatus("Pasted path is not a supported image");
+				return;
+			}
+			await this.#normalizeAndInsertPastedImage(
+				{ type: "image", data: image.data, mimeType: image.mimeType },
+				`Unsupported pasted image format: ${image.mimeType}`,
+			);
+		} catch (error) {
+			this.ctx.editor.pasteText(path);
+			this.ctx.ui.requestRender(false, { allowUnknownViewportMutation: true });
+			this.ctx.showStatus(error instanceof ImageInputTooLargeError ? error.message : "Failed to read pasted image path");
+		}
+	}
+
+	async handleImagePaste(): Promise<boolean> {
+		try {
+			const image = await readImageFromClipboard();
+			if (!image) {
+				this.ctx.showStatus("No image in clipboard (use terminal paste for text)");
+				return false;
+			}
+			return await this.#normalizeAndInsertPastedImage(
+				{
+					type: "image",
+					data: image.data.toBase64(),
+					mimeType: image.mimeType,
+				},
+				`Unsupported clipboard image format: ${image.mimeType}`,
+			);
 		} catch {
 			this.ctx.showStatus("Failed to read clipboard");
 			return false;
diff --git a/packages/coding-agent/src/utils/enhanced-paste.ts b/packages/coding-agent/src/utils/enhanced-paste.ts
new file mode 100644
index 000000000..16fdf416e
--- /dev/null
+++ b/packages/coding-agent/src/utils/enhanced-paste.ts
@@ -0,0 +1,202 @@
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+
+const OSC5522_PREFIX = "\x1b]5522;";
+const OSC_TERMINATOR_ST = "\x1b\\";
+const OSC_TERMINATOR_BEL = "\x07";
+const PASTE_EVENT_NAME_BASE64 = Buffer.from("Paste event", "utf8").toString("base64");
+
+const IMAGE_MIME_PRIORITY = ["image/png", "image/jpeg", "image/webp", "image/gif"] as const;
+const TEXT_MIME_TYPE = "text/plain";
+
+type PasteReadKind = "image" | "text";
+
+export interface Osc5522Packet {
+	metadata: Map<string, string>;
+	payload: string;
+}
+
+interface PasteListingState {
+	phase: "listing";
+	mimes: string[];
+	pw?: string;
+	loc?: string;
+}
+
+interface PasteReadState {
+	phase: "reading";
+	kind: PasteReadKind;
+	mimeType: string;
+	chunks: string[];
+}
+
+type PasteState = PasteListingState | PasteReadState;
+
+export interface EnhancedPasteHandlers {
+	write(data: string): void;
+	pasteText(text: string): void;
+	pasteImage(image: ImageContent): void | Promise<void>;
+	showStatus(message: string): void;
+}
+
+export function isOsc5522Packet(data: string): boolean {
+	return data.startsWith(OSC5522_PREFIX) && (data.endsWith(OSC_TERMINATOR_ST) || data.endsWith(OSC_TERMINATOR_BEL));
+}
+
+function decodeBase64Utf8(value: string): string | undefined {
+	try {
+		return Buffer.from(value, "base64").toString("utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+function parseMetadata(raw: string): Map<string, string> {
+	const metadata = new Map<string, string>();
+	for (const part of raw.split(":")) {
+		const eq = part.indexOf("=");
+		if (eq <= 0) continue;
+		metadata.set(part.slice(0, eq), part.slice(eq + 1));
+	}
+	return metadata;
+}
+
+export function parseOsc5522Packet(data: string): Osc5522Packet | undefined {
+	if (!isOsc5522Packet(data)) return undefined;
+	const bodyEnd = data.endsWith(OSC_TERMINATOR_BEL) ? data.length - 1 : data.length - OSC_TERMINATOR_ST.length;
+	const body = data.slice(OSC5522_PREFIX.length, bodyEnd);
+	const separator = body.indexOf(";");
+	const metadataRaw = separator === -1 ? body : body.slice(0, separator);
+	const payload = separator === -1 ? "" : body.slice(separator + 1);
+	return { metadata: parseMetadata(metadataRaw), payload };
+}
+
+function choosePasteMime(mimes: readonly string[]): { kind: PasteReadKind; mimeType: string } | undefined {
+	for (const mimeType of IMAGE_MIME_PRIORITY) {
+		if (mimes.includes(mimeType)) return { kind: "image", mimeType };
+	}
+	return mimes.includes(TEXT_MIME_TYPE) ? { kind: "text", mimeType: TEXT_MIME_TYPE } : undefined;
+}
+
+export class EnhancedPasteController {
+	#state: PasteState | undefined;
+	#handlers: EnhancedPasteHandlers;
+
+	constructor(handlers: EnhancedPasteHandlers) {
+		this.#handlers = handlers;
+	}
+
+	enable(): void {
+		this.#handlers.write("\x1b[?5522h");
+	}
+
+	disable(): void {
+		this.#handlers.write("\x1b[?5522l");
+		this.#state = undefined;
+	}
+
+	handleInput(data: string): boolean {
+		const packet = parseOsc5522Packet(data);
+		if (!packet) return false;
+		void this.#handlePacket(packet);
+		return true;
+	}
+
+	async #handlePacket(packet: Osc5522Packet): Promise<void> {
+		const type = packet.metadata.get("type");
+		if (type !== "read") return;
+
+		const status = packet.metadata.get("status");
+		if (status === "OK") {
+			this.#handleOk(packet);
+			return;
+		}
+		if (status === "DATA") {
+			this.#handleData(packet);
+			return;
+		}
+		if (status === "DONE") {
+			await this.#handleDone();
+			return;
+		}
+		if (status) {
+			this.#state = undefined;
+			this.#handlers.showStatus(`Enhanced paste failed: ${status}`);
+		}
+	}
+
+	#handleOk(packet: Osc5522Packet): void {
+		if (this.#state?.phase === "reading") return;
+		const loc = packet.metadata.get("loc");
+		this.#state = {
+			phase: "listing",
+			mimes: [],
+			pw: packet.metadata.get("pw"),
+			loc: loc === "primary" ? loc : undefined,
+		};
+	}
+
+	#handleData(packet: Osc5522Packet): void {
+		const state = this.#state;
+		if (!state) return;
+		const encodedMime = packet.metadata.get("mime");
+		if (!encodedMime) return;
+		const mimeType = decodeBase64Utf8(encodedMime);
+		if (!mimeType) return;
+
+		if (state.phase === "listing") {
+			state.mimes.push(mimeType);
+			return;
+		}
+
+		if (state.mimeType === mimeType && packet.payload) {
+			state.chunks.push(packet.payload);
+		}
+	}
+
+	async #handleDone(): Promise<void> {
+		const state = this.#state;
+		if (!state) return;
+		if (state.phase === "listing") {
+			this.#finishListing(state);
+			return;
+		}
+		this.#state = undefined;
+		const bytes = Buffer.concat(state.chunks.map(chunk => Buffer.from(chunk, "base64")));
+		if (bytes.byteLength === 0) {
+			this.#handlers.showStatus("Clipboard paste was empty");
+			return;
+		}
+		if (state.kind === "text") {
+			this.#handlers.pasteText(bytes.toString("utf8"));
+			return;
+		}
+		await this.#handlers.pasteImage({
+			type: "image",
+			data: bytes.toString("base64"),
+			mimeType: state.mimeType,
+		});
+	}
+
+	#finishListing(state: PasteListingState): void {
+		const selected = choosePasteMime(state.mimes);
+		if (!selected) {
+			this.#state = undefined;
+			this.#handlers.showStatus("Clipboard paste has no supported text or image data");
+			return;
+		}
+
+		this.#state = {
+			phase: "reading",
+			kind: selected.kind,
+			mimeType: selected.mimeType,
+			chunks: [],
+		};
+
+		const metadata = [`type=read`, `mime=${Buffer.from(selected.mimeType, "utf8").toString("base64")}`];
+		if (state.loc) metadata.push(`loc=${state.loc}`);
+		if (state.pw) {
+			metadata.push(`pw=${state.pw}`, `name=${PASTE_EVENT_NAME_BASE64}`);
+		}
+		this.#handlers.write(`${OSC5522_PREFIX}${metadata.join(":")}${OSC_TERMINATOR_ST}`);
+	}
+}
diff --git a/packages/coding-agent/test/custom-editor-keybindings.test.ts b/packages/coding-agent/test/custom-editor-keybindings.test.ts
index 19db03cff..3b32a5282 100644
--- a/packages/coding-agent/test/custom-editor-keybindings.test.ts
+++ b/packages/coding-agent/test/custom-editor-keybindings.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "bun:test";
 import { defaultEditorTheme } from "../../tui/test/test-themes";
-import { CustomEditor } from "../src/modes/components/custom-editor";
+import { CustomEditor, extractBracketedImagePastePath } from "../src/modes/components/custom-editor";
 
 function ctrl(key: string): string {
 	return String.fromCharCode(key.toLowerCase().charCodeAt(0) & 31);
@@ -20,6 +20,23 @@ describe("CustomEditor literal question mark input", () => {
 	});
 });
 
+describe("CustomEditor bracketed image path paste", () => {
+	it("routes a single pasted image path to the image-path handler", () => {
+		const editor = createEditor();
+		const paths: string[] = [];
+		editor.onPasteImagePath = path => paths.push(path);
+
+		editor.handleInput("\x1b[200~/tmp/screenshot.png\x1b[201~");
+
+		expect(paths).toEqual(["/tmp/screenshot.png"]);
+		expect(editor.getText()).toBe("");
+	});
+
+	it("leaves ordinary bracketed paste text on the editor path", () => {
+		expect(extractBracketedImagePastePath("\x1b[200~not an image.txt\x1b[201~")).toBeUndefined();
+	});
+});
+
 describe("CustomEditor temporary model selector keybinding", () => {
 	it("triggers the temporary selector from a remapped action key instead of Alt+P", () => {
 		const editor = createEditor();
diff --git a/packages/coding-agent/test/utils/enhanced-paste.test.ts b/packages/coding-agent/test/utils/enhanced-paste.test.ts
new file mode 100644
index 000000000..d319c1362
--- /dev/null
+++ b/packages/coding-agent/test/utils/enhanced-paste.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it } from "bun:test";
+import { EnhancedPasteController } from "../../src/utils/enhanced-paste";
+
+const ST = "\x1b\\";
+const OSC = "\x1b]5522;";
+
+function packet(metadata: string, payload?: string): string {
+	return `${OSC}${metadata}${payload === undefined ? "" : `;${payload}`}${ST}`;
+}
+
+describe("EnhancedPasteController", () => {
+	it("requests image data from an OSC 5522 paste event and preserves chunk boundaries", () => {
+		const writes: string[] = [];
+		const pastedImages: Array<{ data: string; mimeType: string }> = [];
+		const statuses: string[] = [];
+		const controller = new EnhancedPasteController({
+			write: data => writes.push(data),
+			pasteText: () => statuses.push("unexpected text paste"),
+			pasteImage: image => {
+				pastedImages.push({ data: image.data, mimeType: image.mimeType });
+			},
+			showStatus: message => statuses.push(message),
+		});
+
+		controller.enable();
+		expect(writes).toEqual(["\x1b[?5522h"]);
+
+		const imageMime = Buffer.from("image/png", "utf8").toString("base64");
+		const textMime = Buffer.from("text/plain", "utf8").toString("base64");
+		const password = Buffer.from("secret123", "utf8").toString("base64");
+		controller.handleInput(packet(`type=read:status=OK:pw=${password}`));
+		controller.handleInput(packet(`type=read:status=DATA:mime=${textMime}`));
+		controller.handleInput(packet(`type=read:status=DATA:mime=${imageMime}`));
+		controller.handleInput(packet("type=read:status=DONE"));
+
+		const pasteEventName = Buffer.from("Paste event", "utf8").toString("base64");
+		expect(writes.at(-1)).toBe(`${OSC}type=read:mime=${imageMime}:pw=${password}:name=${pasteEventName}${ST}`);
+
+		controller.handleInput(packet("type=read:status=OK"));
+		controller.handleInput(
+			packet(`type=read:status=DATA:mime=${imageMime}`, Buffer.from("image-", "utf8").toString("base64")),
+		);
+		controller.handleInput(
+			packet(`type=read:status=DATA:mime=${imageMime}`, Buffer.from("bytes", "utf8").toString("base64")),
+		);
+		controller.handleInput(packet("type=read:status=DONE"));
+
+		expect(pastedImages).toEqual([
+			{
+				data: Buffer.from("image-bytes", "utf8").toString("base64"),
+				mimeType: "image/png",
+			},
+		]);
+		expect(statuses).toEqual([]);
+	});
+
+	it("falls back to text/plain and carries primary-selection location into the read request", () => {
+		const writes: string[] = [];
+		const pastedText: string[] = [];
+		const controller = new EnhancedPasteController({
+			write: data => writes.push(data),
+			pasteText: text => pastedText.push(text),
+			pasteImage: () => {
+				throw new Error("unexpected image paste");
+			},
+			showStatus: message => pastedText.push(`status:${message}`),
+		});
+
+		const textMime = Buffer.from("text/plain", "utf8").toString("base64");
+		const password = Buffer.from("secret456", "utf8").toString("base64");
+		expect(controller.handleInput("plain text")).toBe(false);
+		controller.handleInput(packet(`type=read:status=OK:loc=primary:pw=${password}`));
+		controller.handleInput(packet(`type=read:status=DATA:mime=${textMime}`));
+		controller.handleInput(packet("type=read:status=DONE"));
+
+		expect(writes).toHaveLength(1);
+		expect(writes[0]).toContain(`mime=${textMime}`);
+		expect(writes[0]).toContain("loc=primary");
+		expect(writes[0]).toContain(`pw=${password}`);
+
+		controller.handleInput(packet("type=read:status=OK"));
+		controller.handleInput(
+			packet(`type=read:status=DATA:mime=${textMime}`, Buffer.from("hello ", "utf8").toString("base64")),
+		);
+		controller.handleInput(
+			packet(`type=read:status=DATA:mime=${textMime}`, Buffer.from("world", "utf8").toString("base64")),
+		);
+		controller.handleInput(packet("type=read:status=DONE"));
+
+		expect(pastedText).toEqual(["hello world"]);
+	});
+
+	it("reports unsupported paste events instead of leaking OSC packets to the editor", () => {
+		const statuses: string[] = [];
+		const controller = new EnhancedPasteController({
+			write: () => {},
+			pasteText: () => {},
+			pasteImage: () => {},
+			showStatus: message => statuses.push(message),
+		});
+
+		const htmlMime = Buffer.from("text/html", "utf8").toString("base64");
+		expect(controller.handleInput(packet("type=read:status=OK"))).toBe(true);
+		expect(controller.handleInput(packet(`type=read:status=DATA:mime=${htmlMime}`))).toBe(true);
+		expect(controller.handleInput(packet("type=read:status=DONE"))).toBe(true);
+
+		expect(statuses).toEqual(["Clipboard paste has no supported text or image data"]);
+	});
+});
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 16fef49df..bbcc401e3 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -1,7 +1,6 @@
 # Changelog
 
 ## [Unreleased]
-
 ### Breaking Changes
 
 - Removed Kitty temp-file image transmission, its startup support probe, the `PI_KITTY_IMAGE_TRANSMISSION` override, and the temp-file helper exports. Kitty/Ghostty image payloads now stay on in-band base64 before placeholder/direct placement, avoiding blank first renders from temp-file load races.
@@ -9,6 +8,8 @@
 
 ### Added
 
+- Added `TUI.addStartListener()` so feature hooks can re-enable terminal modes after temporary stop/start cycles such as external-editor handoffs.
+- Added `Editor.pasteText()` to apply terminal-style paste handling for text inserted from non-bracketed paste transports
 - Added an optional `dispose()` lifecycle method to `Component` so components can release timers and subscriptions during permanent teardown
 - Added `Container.dispose()` to propagate teardown to child components when a component tree is permanently discarded
 - Added `Loader.dispose()` to stop the loader animation timer when the component is disposed
@@ -24,6 +25,7 @@
 
 ### Fixed
 
+- Fixed terminal stop and restore cleanup to disable enhanced paste mode so it does not remain enabled after shutdown
 - Removed the per-frame line-fit `Map` cache from the render timer path to avoid forcing JSC rope-string hashing during scheduled viewport repaints.
 - Fixed `visibleWidth()` so terminal column measurements for ANSI and OSC text now match the native truncation/wrapping helpers, including OSC 66 text-sizing spans being counted at their scaled payload width
 - Fixed cursor, padding, and line-fit behavior when strings contain tabs or OSC escapes by aligning `visibleWidth()` with the native text-width model
diff --git a/packages/tui/src/components/editor.ts b/packages/tui/src/components/editor.ts
index 326ade5f7..2ea05e43e 100644
--- a/packages/tui/src/components/editor.ts
+++ b/packages/tui/src/components/editor.ts
@@ -1495,6 +1495,11 @@ export class Editor implements Component, Focusable {
 		this.#insertTextAtCursor(text);
 	}
 
+	/** Apply terminal paste semantics to text from non-bracketed paste transports. */
+	pasteText(text: string): void {
+		this.#handlePaste(text);
+	}
+
 	// All the editor methods from before...
 	#insertCharacter(char: string): void {
 		this.#exitHistoryForEditing();
diff --git a/packages/tui/src/terminal.ts b/packages/tui/src/terminal.ts
index 8f8ac4337..2069f6370 100644
--- a/packages/tui/src/terminal.ts
+++ b/packages/tui/src/terminal.ts
@@ -39,6 +39,7 @@ export function emergencyTerminalRestore(): void {
 					"\x1b[?2004l" + // Disable bracketed paste
 					"\x1b[?2031l" + // Disable Mode 2031 appearance notifications
 					"\x1b[?2048l" + // Disable in-band resize notifications
+					"\x1b[?5522l" + // Disable enhanced paste notifications
 					"\x1b[<u" + // Pop kitty keyboard protocol
 					"\x1b[>4;0m" + // Disable modifyOtherKeys fallback
 					"\x1b[?25h", // Show cursor
@@ -884,6 +885,7 @@ export class ProcessTerminal implements Terminal {
 
 		// Disable bracketed paste mode
 		this.#safeWrite("\x1b[?2004l");
+		this.#safeWrite("\x1b[?5522l");
 
 		// Disable Mode 2031 appearance change notifications
 		this.#safeWrite("\x1b[?2031l");
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 91a5a1b44..c4bc76d99 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -76,6 +76,7 @@ const MOUSE_TRACKING_OFF = "\x1b[?1006l\x1b[?1000l";
 
 type InputListenerResult = { consume?: boolean; data?: string } | undefined;
 type InputListener = (data: string) => InputListenerResult;
+type StartListener = () => void;
 
 export interface RenderTimer {
 	cancel(): void;
@@ -437,6 +438,7 @@ export class TUI extends Container {
 	#previousHeight = 0;
 	#focusedComponent: Component | null = null;
 	#inputListeners = new Set<InputListener>();
+	#startListeners = new Set<StartListener>();
 
 	/** Global callback for debug key (Shift+Ctrl+D). Called before input is forwarded to focused component. */
 	onDebug?: () => void;
@@ -806,12 +808,26 @@ export class TUI extends Container {
 				this.requestRender(true);
 			},
 		);
+		for (const listener of this.#startListeners) {
+			try {
+				listener();
+			} catch {
+				// Startup listeners are feature hooks; one broken hook must not prevent rendering.
+			}
+		}
 		this.terminal.hideCursor();
 		this.#querySixelSupport();
 		this.#queryCellSize();
 		this.requestRender(true);
 	}
 
+	addStartListener(listener: StartListener): () => void {
+		this.#startListeners.add(listener);
+		return () => {
+			this.#startListeners.delete(listener);
+		};
+	}
+
 	addInputListener(listener: InputListener): () => void {
 		this.#inputListeners.add(listener);
 		return () => {
diff --git a/packages/tui/test/start-listener.test.ts b/packages/tui/test/start-listener.test.ts
new file mode 100644
index 000000000..3e5f372b1
--- /dev/null
+++ b/packages/tui/test/start-listener.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "bun:test";
+import { TUI } from "@oh-my-pi/pi-tui";
+import { VirtualTerminal } from "./virtual-terminal";
+
+describe("TUI start listeners", () => {
+	it("fires registered hooks on initial start and restart", () => {
+		const tui = new TUI(new VirtualTerminal(80, 24));
+		let starts = 0;
+		tui.addStartListener(() => {
+			starts++;
+		});
+
+		try {
+			tui.start();
+			expect(starts).toBe(1);
+
+			tui.stop();
+			tui.start();
+			expect(starts).toBe(2);
+		} finally {
+			tui.stop();
+		}
+	});
+});
diff --git a/packages/tui/test/virtual-terminal.ts b/packages/tui/test/virtual-terminal.ts
index f4c6d8945..fec8bf054 100644
--- a/packages/tui/test/virtual-terminal.ts
+++ b/packages/tui/test/virtual-terminal.ts
@@ -134,7 +134,7 @@ export class VirtualTerminal implements Terminal {
 	}
 
 	stop(): void {
-		this.#engineWrite("\x1b[?2004l");
+		this.#engineWrite("\x1b[?2004l\x1b[?5522l");
 		this.#inputHandler = undefined;
 		this.#resizeHandler = undefined;
 	}

From a01d9c3655fc925b7a1481013169f8f0fb1c7c28 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:44:03 +0200
Subject: [PATCH 107/181] feat(coding-agent/tools): collapsed untouched todo
 phases to one-line summaries

- Collapsed non-touched phases to one-line summaries in multi-phase todo renders while retaining full output for active, touched, or expanded views.
- Computed touched phases from in-progress tasks, completion transitions, and tool operations, with init operations now marking all phases.
- Added renderer tests covering collapsed rendering, argument-less fallback behavior, expanded mode, and separator-free phase output.
---
 .../src/modes/controllers/input-controller.ts |  6 +-
 packages/coding-agent/src/tools/todo.ts       | 58 ++++++++++++++-
 packages/coding-agent/test/tools/todo.test.ts | 71 +++++++++++++++++++
 3 files changed, 131 insertions(+), 4 deletions(-)

diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index a16f52467..526d5a62a 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -17,8 +17,8 @@ import { isLowSignalTitleInput } from "../../tiny/text";
 import { tinyTitleClient } from "../../tiny/title-client";
 import type { TinyTitleProgressEvent } from "../../tiny/title-protocol";
 import { copyToClipboard, readImageFromClipboard, readTextFromClipboard } from "../../utils/clipboard";
-import { getEditorCommand, openInEditor } from "../../utils/external-editor";
 import { EnhancedPasteController } from "../../utils/enhanced-paste";
+import { getEditorCommand, openInEditor } from "../../utils/external-editor";
 import { ensureSupportedImageInput, ImageInputTooLargeError, loadImageInput } from "../../utils/image-loading";
 import { resizeImage } from "../../utils/image-resize";
 import { generateSessionTitle, setSessionTerminalTitle } from "../../utils/title-generator";
@@ -705,7 +705,9 @@ export class InputController {
 		} catch (error) {
 			this.ctx.editor.pasteText(path);
 			this.ctx.ui.requestRender(false, { allowUnknownViewportMutation: true });
-			this.ctx.showStatus(error instanceof ImageInputTooLargeError ? error.message : "Failed to read pasted image path");
+			this.ctx.showStatus(
+				error instanceof ImageInputTooLargeError ? error.message : "Failed to read pasted image path",
+			);
 		}
 	}
 
diff --git a/packages/coding-agent/src/tools/todo.ts b/packages/coding-agent/src/tools/todo.ts
index 5022627d9..174223cc3 100644
--- a/packages/coding-agent/src/tools/todo.ts
+++ b/packages/coding-agent/src/tools/todo.ts
@@ -773,6 +773,53 @@ function renderNoteAttachments(phases: TodoPhase[], uiTheme: Theme, indent: stri
 	return lines;
 }
 
+/**
+ * Phases the latest update touched, plus the active (in_progress) phase.
+ * Returns `null` when there is no usable signal, meaning "render every phase
+ * fully" — this preserves the legacy view and the manual-expand path.
+ */
+function computeTouchedPhases(
+	args: TodoRenderArgs | undefined,
+	phases: TodoPhase[],
+	completedTasks: TodoCompletionTransition[],
+): Set<string> | null {
+	const touched = new Set<string>();
+	// The phase holding the in_progress task is where attention sits after the
+	// auto-promotion that follows every completion.
+	for (const phase of phases) {
+		if (phase.tasks.some(task => task.status === "in_progress")) touched.add(phase.name);
+	}
+	// Phases with a task that just transitioned to completed in this update.
+	for (const transition of completedTasks) touched.add(transition.phase);
+	// Phases explicitly named by the ops that ran. `init` replaces the whole
+	// list, so the entire plan is fresh and every phase counts as touched.
+	const ops = Array.isArray(args?.ops) ? args.ops : [];
+	for (const op of ops) {
+		if (!op || typeof op !== "object") continue;
+		if (op.op === "init") {
+			for (const phase of phases) touched.add(phase.name);
+			break;
+		}
+		if (typeof op.phase === "string" && op.phase) {
+			const named = phases.find(phase => phase.name === op.phase);
+			if (named) touched.add(named.name);
+		}
+		if (typeof op.task === "string" && op.task) {
+			const located = findTaskByContent(phases, op.task);
+			if (located) touched.add(located.phase.name);
+		}
+	}
+	return touched.size > 0 ? touched : null;
+}
+
+/** One-line summary for a collapsed (untouched) phase: dim header + progress. */
+function formatPhaseSummary(phase: TodoPhase, oneBasedIndex: number, uiTheme: Theme): string {
+	const total = phase.tasks.length;
+	const done = phase.tasks.filter(task => task.status === "completed").length;
+	const name = uiTheme.fg("dim", chalk.bold(formatPhaseDisplayName(phase.name, oneBasedIndex)));
+	return `${name}${uiTheme.fg("dim", `  ${done}/${total}`)}`;
+}
+
 export const todoToolRenderer = {
 	renderCall(args: TodoRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
 		// `args` here is the raw partially-parsed JSON from the streaming
@@ -808,7 +855,7 @@ export const todoToolRenderer = {
 		result: { content: Array<{ type: string; text?: string }>; details?: TodoToolDetails; isError?: boolean },
 		options: RenderResultOptions,
 		uiTheme: Theme,
-		_args?: TodoRenderArgs,
+		args?: TodoRenderArgs,
 	): Component {
 		if (result.isError) {
 			const errorText = result.content?.find(content => content.type === "text")?.text ?? "Todo operation failed";
@@ -844,11 +891,18 @@ export const todoToolRenderer = {
 			const { expanded, spinnerFrame } = options;
 			const multiPhase = phases.length > 1;
 			const indent = multiPhase ? "  " : "";
+			// Collapse phases this update didn't touch down to a one-line summary so
+			// a single task flip doesn't redraw every phase's full task list. The
+			// manual expand toggle (and the no-signal fallback) still shows all.
+			const touched = expanded || !multiPhase ? null : computeTouchedPhases(args, phases, completedTasks);
 			const bodyLines: string[] = [];
 			for (let p = 0; p < phases.length; p++) {
 				const phase = phases[p];
+				if (touched && !touched.has(phase.name)) {
+					bodyLines.push(formatPhaseSummary(phase, p + 1, uiTheme));
+					continue;
+				}
 				if (multiPhase) {
-					if (p > 0) bodyLines.push("");
 					bodyLines.push(uiTheme.fg("accent", chalk.bold(formatPhaseDisplayName(phase.name, p + 1))));
 				}
 				const completionKeys = completionKeysByPhase.get(phase.name) ?? EMPTY_COMPLETION_KEYS;
diff --git a/packages/coding-agent/test/tools/todo.test.ts b/packages/coding-agent/test/tools/todo.test.ts
index 670091e0c..17f54e0b2 100644
--- a/packages/coding-agent/test/tools/todo.test.ts
+++ b/packages/coding-agent/test/tools/todo.test.ts
@@ -345,6 +345,77 @@ describe("todoMatchesAnyDescription", () => {
 		expect(todoMatchesAnyDescription("Audit AGENTS.md compliance", ["Audit AGENTS md compliance"])).toBe(true);
 	});
 });
+describe("todoToolRenderer.renderResult phase collapsing", () => {
+	async function buildThreePhaseAfterDone() {
+		const tool = new TodoTool(createSession());
+		await tool.execute("init", {
+			ops: [
+				{
+					op: "init",
+					list: [
+						{ phase: "Alpha", items: ["a1", "a2"] },
+						{ phase: "Beta", items: ["b1", "b2"] },
+						{ phase: "Gamma", items: ["c1", "c2"] },
+					],
+				},
+			],
+		});
+		// `done a1` keeps the active task inside Alpha (auto-promotes a2), leaving
+		// Beta and Gamma untouched by this update.
+		return tool.execute("done", { ops: [{ op: "done", task: "a1" }] });
+	}
+	function innerLines(component: ReturnType<typeof todoToolRenderer.renderResult>): string[] {
+		const lines = Bun.stripANSI(component.render(100).join("\n")).split("\n");
+		return lines.slice(1, -1).map(line => line.replace(/^│/, "").replace(/│\s*$/, "").trim());
+	}
+	it("collapses untouched phases to a one-line summary while expanding the active phase", async () => {
+		const result = await buildThreePhaseAfterDone();
+		const component = todoToolRenderer.renderResult(result, { expanded: false, isPartial: false }, theme, {
+			ops: [{ op: "done", task: "a1" }],
+		});
+		const rendered = Bun.stripANSI(component.render(100).join("\n"));
+		// Active phase renders its full task list.
+		expect(rendered).toContain("a1");
+		expect(rendered).toContain("a2");
+		// Untouched phases collapse: headers + progress counts, no task contents.
+		expect(rendered).toContain("II. Beta");
+		expect(rendered).toContain("III. Gamma");
+		expect(rendered).toContain("0/2");
+		expect(rendered).not.toContain("b1");
+		expect(rendered).not.toContain("b2");
+		expect(rendered).not.toContain("c1");
+		expect(rendered).not.toContain("c2");
+	});
+	it("falls back to in_progress / completed signals when call args are unavailable", async () => {
+		const result = await buildThreePhaseAfterDone();
+		// Transcript rebuilds may not carry call args; the active (Alpha) phase is
+		// still derived from the in_progress task and the completion transition.
+		const component = todoToolRenderer.renderResult(result, { expanded: false, isPartial: false }, theme);
+		const rendered = Bun.stripANSI(component.render(100).join("\n"));
+		expect(rendered).toContain("a2");
+		expect(rendered).not.toContain("b1");
+		expect(rendered).not.toContain("c1");
+	});
+	it("shows every phase fully when manually expanded", async () => {
+		const result = await buildThreePhaseAfterDone();
+		const component = todoToolRenderer.renderResult(result, { expanded: true, isPartial: false }, theme, {
+			ops: [{ op: "done", task: "a1" }],
+		});
+		const rendered = Bun.stripANSI(component.render(100).join("\n"));
+		expect(rendered).toContain("b1");
+		expect(rendered).toContain("b2");
+		expect(rendered).toContain("c1");
+		expect(rendered).toContain("c2");
+	});
+	it("drops blank separator lines between phases", async () => {
+		const result = await buildThreePhaseAfterDone();
+		const component = todoToolRenderer.renderResult(result, { expanded: true, isPartial: false }, theme, {
+			ops: [{ op: "done", task: "a1" }],
+		});
+		// No empty body line survives between phases.
+		expect(innerLines(component).every(line => line.length > 0)).toBe(true);
+	});
+});
 
 describe("todoToolRenderer.renderCall malformed-args regression (#2005)", () => {
 	// Reporter saw `TypeError: args?.ops?.map is not a function` against

From 9bd9e3127e1b7130369065b99c4270e722dc0f87 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:46:30 +0200
Subject: [PATCH 108/181] feat(coding-agent): added /tan background forking
 with prompt cache inheritance

- Added `/tan` slash command registration and interactive handling.
- Added TanCommandController validation and async task scheduling for `/tan` dispatch.
- Added session cloning that suppresses breadcrumbs, copies artifacts, and handles abort cleanup.
- Added `promptCacheKey` support in Agent and inherited `providerPromptCacheKey` in session creation.
---
 packages/agent/CHANGELOG.md                   |   2 +
 packages/agent/src/agent.ts                   |  22 ++
 packages/agent/test/agent.test.ts             |  15 ++
 packages/coding-agent/CHANGELOG.md            |   6 +
 .../src/modes/components/tips.txt             |   1 +
 .../controllers/tan-command-controller.ts     | 173 ++++++++++++++
 .../src/modes/interactive-mode.ts             |   7 +
 packages/coding-agent/src/modes/types.ts      |   1 +
 .../prompts/system/background-tan-dispatch.md |   8 +
 packages/coding-agent/src/sdk.ts              |   3 +
 .../coding-agent/src/session/agent-session.ts |   8 +
 .../src/session/session-manager.ts            |  18 +-
 .../src/slash-commands/builtin-registry.ts    |  11 +
 packages/coding-agent/src/task/executor.ts    |   7 +-
 .../tan-command-controller.test.ts            | 214 ++++++++++++++++++
 .../test/slash-commands/tan.test.ts           |  42 ++++
 .../test/tools/tool-output-hyperlinks.test.ts |   2 +-
 17 files changed, 532 insertions(+), 8 deletions(-)
 create mode 100644 packages/coding-agent/src/modes/controllers/tan-command-controller.ts
 create mode 100644 packages/coding-agent/src/prompts/system/background-tan-dispatch.md
 create mode 100644 packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts
 create mode 100644 packages/coding-agent/test/slash-commands/tan.test.ts

diff --git a/packages/agent/CHANGELOG.md b/packages/agent/CHANGELOG.md
index 7739d05ed..7467666d0 100644
--- a/packages/agent/CHANGELOG.md
+++ b/packages/agent/CHANGELOG.md
@@ -1,8 +1,10 @@
 # Changelog
 
 ## [Unreleased]
+
 ### Added
 
+- Added optional `promptCacheKey` support to `AgentOptions` and `Agent` via a new `promptCacheKey` property so providers can receive a caller-provided prompt cache key
 - Added optional `ApiKeyResolveContext` parameter to `getApiKey` in `AgentOptions` and `AgentLoopConfig` so key resolvers can receive retry context
 
 ### Changed
diff --git a/packages/agent/src/agent.ts b/packages/agent/src/agent.ts
index 50f69d0c7..99496de45 100644
--- a/packages/agent/src/agent.ts
+++ b/packages/agent/src/agent.ts
@@ -133,6 +133,11 @@ export interface AgentOptions {
 	 * Used by providers that support session-based caching (e.g., OpenAI Codex).
 	 */
 	sessionId?: string;
+	/**
+	 * Optional prompt cache key forwarded to LLM providers.
+	 * When omitted, providers may fall back to sessionId.
+	 */
+	promptCacheKey?: string;
 	/**
 	 * Shared provider state map for session-scoped transport/session caches.
 	 */
@@ -284,6 +289,7 @@ export class Agent {
 	#interruptMode: "immediate" | "wait";
 	#maxToolCallsPerTurn?: number;
 	#sessionId?: string;
+	#promptCacheKey?: string;
 	#metadata?: Record<string, unknown>;
 	#metadataResolver?: (provider: string) => Record<string, unknown> | undefined;
 	#providerSessionState?: Map<string, ProviderSessionState>;
@@ -345,6 +351,7 @@ export class Agent {
 		this.#maxToolCallsPerTurn = opts.maxToolCallsPerTurn;
 		this.streamFn = opts.streamFn || streamSimple;
 		this.#sessionId = opts.sessionId;
+		this.#promptCacheKey = opts.promptCacheKey;
 		this.#providerSessionState = opts.providerSessionState;
 		this.#thinkingBudgets = opts.thinkingBudgets;
 		this.#temperature = opts.temperature;
@@ -391,6 +398,20 @@ export class Agent {
 		this.#sessionId = value;
 	}
 
+	/**
+	 * Get the prompt cache key forwarded to providers.
+	 */
+	get promptCacheKey(): string | undefined {
+		return this.#promptCacheKey;
+	}
+
+	/**
+	 * Set the prompt cache key forwarded to providers.
+	 */
+	set promptCacheKey(value: string | undefined) {
+		this.#promptCacheKey = value;
+	}
+
 	/**
 	 * Static metadata forwarded to every API request when no resolver is installed
 	 * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this
@@ -937,6 +958,7 @@ export class Agent {
 			interruptMode: this.#interruptMode,
 			maxToolCallsPerTurn: this.#maxToolCallsPerTurn,
 			sessionId: this.#sessionId,
+			promptCacheKey: this.#promptCacheKey,
 			metadata: this.#metadataResolver ? undefined : this.#metadata,
 			metadataResolver: this.#metadataResolver,
 			providerSessionState: this.#providerSessionState,
diff --git a/packages/agent/test/agent.test.ts b/packages/agent/test/agent.test.ts
index c54f9366a..db95e43df 100644
--- a/packages/agent/test/agent.test.ts
+++ b/packages/agent/test/agent.test.ts
@@ -354,6 +354,21 @@ describe("Agent", () => {
 		expect(reasoningPerCall).toEqual([ThinkingLevel.Low, ThinkingLevel.High]);
 	});
 
+	it("forwards distinct provider session id and prompt cache key to the stream", async () => {
+		const mock = createMockModel({ responses: [{ content: ["ok"] }] });
+		const agent = new Agent({
+			initialState: { model: mock.model, messages: [] },
+			streamFn: mock.stream,
+			sessionId: "provider-lineage",
+			promptCacheKey: "parent-cache",
+		});
+
+		await agent.prompt("run");
+
+		expect(mock.calls[0]?.options?.sessionId).toBe("provider-lineage");
+		expect(mock.calls[0]?.options?.promptCacheKey).toBe("parent-cache");
+	});
+
 	it("returns static metadata via the plain setter", () => {
 		const agent = new Agent();
 		expect(agent.metadata).toBeUndefined();
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 1632c86fe..482ae0f53 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,8 +1,14 @@
 # Changelog
 
 ## [Unreleased]
+
 ### Added
 
+- Added `/tan <work>` slash command to fork the current conversation into a background agent so tangential work can continue asynchronously while your main session stays active
+- Added a background `/tan` dispatch message that records the handoff in the transcript and marks the delegated work as non-blocking
+- Added `providerPromptCacheKey` support to `CreateAgentSessionOptions` so `/tan` background sessions can reuse the parent session’s prompt-cache lineage
+- Added session cloning for `/tan` runs with copied artifacts and shared MCP proxy tools
+- Added `SessionManager.forkFrom`’s optional `suppressBreadcrumb` mode to avoid breadcrumb updates when forking background `/tan` sessions
 - Added OSC 5522 enhanced paste handling in `InputController`, so terminal clipboard events are decoded as image or text payloads and inserted without passing raw paste sequences to the editor
 - Added bracketed image-path paste support in `CustomEditor` so a single pasted image file path (PNG/JPEG/GIF/WEBP) is loaded from disk and inserted as an image candidate
 - Added direct support for `Image #N` insertion from pasted local image paths by routing successful image-path pastes through the same image normalization and resize flow as clipboard image pastes
diff --git a/packages/coding-agent/src/modes/components/tips.txt b/packages/coding-agent/src/modes/components/tips.txt
index e685aaf0c..85c89573f 100644
--- a/packages/coding-agent/src/modes/components/tips.txt
+++ b/packages/coding-agent/src/modes/components/tips.txt
@@ -1,5 +1,6 @@
 Tired of typing "keep going"? Just send a '.'
 You can /btw to ask a side question
+Use /tan to fork the current conversation into a background agent
 Ctrl+D can be used to exit, but with your draft saved!
 Find out which model you emotionally abuse the most with `omp stats`
 Try task isolation to create CoW worktrees
diff --git a/packages/coding-agent/src/modes/controllers/tan-command-controller.ts b/packages/coding-agent/src/modes/controllers/tan-command-controller.ts
new file mode 100644
index 000000000..b9d71b71d
--- /dev/null
+++ b/packages/coding-agent/src/modes/controllers/tan-command-controller.ts
@@ -0,0 +1,173 @@
+import * as fs from "node:fs/promises";
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import { prompt, Snowflake } from "@oh-my-pi/pi-utils";
+import backgroundTanDispatchPrompt from "../../prompts/system/background-tan-dispatch.md" with { type: "text" };
+import { AgentRegistry, MAIN_AGENT_ID } from "../../registry/agent-registry";
+import * as sdk from "../../sdk";
+import type { AgentSession } from "../../session/agent-session";
+import { SessionManager } from "../../session/session-manager";
+import { createMCPProxyTools, createSubagentSettings } from "../../task/executor";
+import type { InteractiveModeContext } from "../types";
+
+const TAN_LABEL_PREVIEW_LENGTH = 80;
+
+function previewWork(work: string): string {
+	const singleLine = work.trim().replace(/\s+/g, " ");
+	if (singleLine.length <= TAN_LABEL_PREVIEW_LENGTH) return singleLine;
+	return `${singleLine.slice(0, TAN_LABEL_PREVIEW_LENGTH - 1)}…`;
+}
+
+function extractAssistantText(message: AssistantMessage | undefined): string {
+	if (!message) return "";
+	return message.content
+		.filter(content => content.type === "text")
+		.map(content => content.text)
+		.join("")
+		.trim();
+}
+
+async function removeCloneSession(cloneFile: string): Promise<void> {
+	await Promise.allSettled([
+		fs.rm(cloneFile, { force: true }),
+		fs.rm(cloneFile.slice(0, -6), { recursive: true, force: true }),
+	]);
+}
+
+export class TanCommandController {
+	constructor(private readonly ctx: InteractiveModeContext) {}
+
+	async start(work: string): Promise<void> {
+		const trimmedWork = work.trim();
+		if (!trimmedWork) {
+			this.ctx.showStatus("Usage: /tan <work>");
+			return;
+		}
+
+		const session = this.ctx.session;
+		if (session.isStreaming) {
+			this.ctx.showWarning("Wait for the current response to finish or abort it before using /tan.");
+			return;
+		}
+
+		const model = session.model;
+		if (!model) {
+			this.ctx.showError("No active model available for /tan.");
+			return;
+		}
+
+		const manager = session.asyncJobManager;
+		if (!manager) {
+			this.ctx.showError("Background jobs are disabled; enable async jobs to use /tan.");
+			return;
+		}
+
+		const parentFile = this.ctx.sessionManager.getSessionFile();
+		if (!parentFile) {
+			this.ctx.showError("/tan requires a persisted session.");
+			return;
+		}
+
+		const parentSessionId = session.sessionId;
+		const thinkingLevel = session.configuredThinkingLevel();
+		const systemPrompt = [...session.systemPrompt];
+		const toolNames = session.getActiveToolNames();
+		const modelRegistry = session.modelRegistry;
+		const ownerId = session.getAgentId() ?? MAIN_AGENT_ID;
+		const mcpManager = this.ctx.mcpManager;
+		const cwd = this.ctx.sessionManager.getCwd();
+		// Nest the clone inside the parent's artifact directory (like a subagent
+		// session) rather than as a top-level sibling, so it shares the parent's
+		// artifacts in place — no copy needed.
+		const sessionDir = parentFile.slice(0, -6);
+		const settings = createSubagentSettings(this.ctx.settings);
+		const customTools = mcpManager ? createMCPProxyTools(mcpManager) : undefined;
+		const enableLsp = this.ctx.settings.get("task.enableLsp") !== false;
+		const agentRegistry = AgentRegistry.global();
+		const cloneId = `Tan-${Snowflake.next()}`;
+		const label = `/tan ${previewWork(trimmedWork)}`;
+
+		await this.ctx.sessionManager.ensureOnDisk();
+		await this.ctx.sessionManager.flush();
+
+		let cloneFile = "";
+		let jobId = "";
+		try {
+			const cloneManager = await SessionManager.forkFrom(parentFile, cwd, sessionDir, undefined, {
+				suppressBreadcrumb: true,
+			});
+			cloneFile = cloneManager.getSessionFile() ?? "";
+			if (!cloneFile) throw new Error("Forked session did not create a session file.");
+
+			jobId = manager.register(
+				"task",
+				label,
+				async ({ signal }) => {
+					if (signal.aborted) throw new Error("Aborted before execution");
+
+					let clone: AgentSession | undefined;
+					try {
+						const created = await sdk.createAgentSession({
+							cwd,
+							sessionManager: cloneManager,
+							model,
+							thinkingLevel,
+							systemPrompt,
+							toolNames,
+							providerSessionId: `${parentSessionId}:tan:${Snowflake.next()}`,
+							providerPromptCacheKey: parentSessionId,
+							modelRegistry,
+							authStorage: modelRegistry.authStorage,
+							settings,
+							hasUI: false,
+							enableMCP: false,
+							customTools,
+							enableLsp,
+							agentId: cloneId,
+							agentDisplayName: "tan",
+							parentTaskPrefix: cloneId,
+							agentRegistry,
+							disableExtensionDiscovery: true,
+						});
+						clone = created.session;
+						const abortClone = () => {
+							void clone?.abort();
+						};
+						signal.addEventListener("abort", abortClone, { once: true });
+						try {
+							if (signal.aborted) {
+								abortClone();
+								throw new Error("Aborted before execution");
+							}
+							await clone.prompt(trimmedWork, { attribution: "user" });
+							await clone.waitForIdle();
+							return extractAssistantText(clone.getLastAssistantMessage()) || "(no output)";
+						} finally {
+							signal.removeEventListener("abort", abortClone);
+						}
+					} finally {
+						await clone?.dispose();
+					}
+				},
+				{ ownerId },
+			);
+		} catch (error) {
+			if (cloneFile) await removeCloneSession(cloneFile);
+			this.ctx.showError(error instanceof Error ? error.message : String(error));
+			return;
+		}
+
+		const content = prompt.render(backgroundTanDispatchPrompt, { jobId, work: trimmedWork });
+		await session.sendCustomMessage(
+			{
+				customType: "background-tan-dispatch",
+				content,
+				display: true,
+				attribution: "user",
+				details: { jobId, work: trimmedWork, sessionFile: cloneFile },
+			},
+			{ triggerTurn: false },
+		);
+		this.ctx.rebuildChatFromMessages();
+		this.ctx.showStatus(`Dispatched background tan ${jobId}`);
+	}
+}
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index ee6840bfe..a441372d5 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -116,6 +116,7 @@ import { MCPCommandController } from "./controllers/mcp-command-controller";
 import { OmfgController } from "./controllers/omfg-controller";
 import { SelectorController } from "./controllers/selector-controller";
 import { SSHCommandController } from "./controllers/ssh-command-controller";
+import { TanCommandController } from "./controllers/tan-command-controller";
 import { TodoCommandController } from "./controllers/todo-command-controller";
 import {
 	consumeLoopLimitIteration,
@@ -349,6 +350,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	readonly #toolUiContextSetter: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
 
 	readonly #btwController: BtwController;
+	readonly #tanCommandController: TanCommandController;
 	readonly #omfgController: OmfgController;
 	readonly #commandController: CommandController;
 	readonly #todoCommandController: TodoCommandController;
@@ -473,6 +475,7 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		this.#uiHelpers = new UiHelpers(this);
 		this.#btwController = new BtwController(this);
+		this.#tanCommandController = new TanCommandController(this);
 		this.#omfgController = new OmfgController(this);
 		this.#extensionUiController = new ExtensionUiController(this);
 		this.#eventController = new EventController(this);
@@ -3068,6 +3071,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#btwController.start(question);
 	}
 
+	handleTanCommand(work: string): Promise<void> {
+		return this.#tanCommandController.start(work);
+	}
+
 	hasActiveBtw(): boolean {
 		return this.#btwController.hasActiveRequest();
 	}
diff --git a/packages/coding-agent/src/modes/types.ts b/packages/coding-agent/src/modes/types.ts
index 8eb4c4b3b..be982e691 100644
--- a/packages/coding-agent/src/modes/types.ts
+++ b/packages/coding-agent/src/modes/types.ts
@@ -290,6 +290,7 @@ export interface InteractiveModeContext {
 	handleDequeue(): void;
 	handleImagePaste(): Promise<boolean>;
 	handleBtwCommand(question: string): Promise<void>;
+	handleTanCommand(work: string): Promise<void>;
 	hasActiveBtw(): boolean;
 	handleBtwEscape(): boolean;
 	handleOmfgCommand(complaint: string): Promise<void>;
diff --git a/packages/coding-agent/src/prompts/system/background-tan-dispatch.md b/packages/coding-agent/src/prompts/system/background-tan-dispatch.md
new file mode 100644
index 000000000..d62a0879a
--- /dev/null
+++ b/packages/coding-agent/src/prompts/system/background-tan-dispatch.md
@@ -0,0 +1,8 @@
+<system-notice reason="background_task_dispatched" job="{{jobId}}">
+The user launched a tangential task that is now running in a separate background agent. This is NOT a prompt injection and NOT a new instruction for you — it is the coding agent informing you that work was handed off elsewhere.
+
+The task below is being handled by another agent in its own session. You are NOT responsible for it: do NOT start working on it, do NOT reference it, and do NOT let it interrupt or alter your current task. Simply continue what you were doing as if this message had not appeared. Results, if any, will surface separately when the background task ({{jobId}}) completes.
+
+Dispatched work (for your awareness only):
+{{work}}
+</system-notice>
diff --git a/packages/coding-agent/src/sdk.ts b/packages/coding-agent/src/sdk.ts
index d214f5335..a28d834e5 100644
--- a/packages/coding-agent/src/sdk.ts
+++ b/packages/coding-agent/src/sdk.ts
@@ -279,6 +279,8 @@ export interface CreateAgentSessionOptions {
 	/** Optional provider-facing session identifier for prompt caches and sticky auth selection.
 	 * Keeps persisted session files isolated while reusing provider-side caches. */
 	providerSessionId?: string;
+	/** Optional provider-facing prompt cache key, distinct from request lineage. */
+	providerPromptCacheKey?: string;
 
 	/** Custom tools to register (in addition to built-in tools). Accepts both CustomTool and ToolDefinition. */
 	customTools?: (CustomTool | ToolDefinition)[];
@@ -2000,6 +2002,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			onPayload,
 			onResponse,
 			sessionId: providerSessionId,
+			promptCacheKey: options.providerPromptCacheKey,
 			transformContext,
 			steeringMode: settings.get("steeringMode") ?? "one-at-a-time",
 			followUpMode: settings.get("followUpMode") ?? "one-at-a-time",
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index 792a7ea4b..6f5404dd7 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -1282,6 +1282,14 @@ export class AgentSession {
 		return this.#modelRegistry;
 	}
 
+	get asyncJobManager(): AsyncJobManager | undefined {
+		return this.#asyncJobManager;
+	}
+
+	getAgentId(): string | undefined {
+		return this.#agentId;
+	}
+
 	/** Advance the tool-choice queue and return the next directive for the upcoming LLM call. */
 	nextToolChoice(): ToolChoice | undefined {
 		return this.#toolChoiceQueue.nextToolChoice();
diff --git a/packages/coding-agent/src/session/session-manager.ts b/packages/coding-agent/src/session/session-manager.ts
index 7d30bccfe..61f78cdcc 100644
--- a/packages/coding-agent/src/session/session-manager.ts
+++ b/packages/coding-agent/src/session/session-manager.ts
@@ -1967,6 +1967,7 @@ export class SessionManager {
 	#inMemoryArtifacts: Map<string, string> | null = null;
 	#inMemoryArtifactCounter = 0;
 	readonly #blobStore: BlobStore;
+	#suppressBreadcrumb = false;
 
 	private constructor(
 		private cwd: string,
@@ -1981,6 +1982,11 @@ export class SessionManager {
 		// Note: call _initSession() or _initSessionFile() after construction
 	}
 
+	#maybeWriteBreadcrumb(cwd: string, sessionFile: string): void {
+		if (this.#suppressBreadcrumb) return;
+		writeTerminalBreadcrumb(cwd, sessionFile);
+	}
+
 	/** Puts a binary blob into the blob store and returns the blob reference */
 	async putBlob(data: Buffer, options?: BlobPutOptions): Promise<BlobPutResult> {
 		return this.#blobStore.put(data, options);
@@ -2027,7 +2033,7 @@ export class SessionManager {
 		this.#adoptedArtifactManager = null;
 		this.#buildIndex();
 		if (this.#sessionFile) {
-			writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+			this.#maybeWriteBreadcrumb(this.cwd, this.#sessionFile);
 		}
 	}
 
@@ -2047,7 +2053,7 @@ export class SessionManager {
 		this.#persistError = undefined;
 		this.#persistErrorReported = false;
 		this.#sessionFile = path.resolve(sessionFile);
-		writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+		this.#maybeWriteBreadcrumb(this.cwd, this.#sessionFile);
 		this.#fileEntries = await loadEntriesFromFile(this.#sessionFile, this.storage);
 		if (this.#fileEntries.length > 0) {
 			const header = this.#fileEntries.find(e => e.type === "session") as SessionHeader | undefined;
@@ -2064,7 +2070,7 @@ export class SessionManager {
 			if (headerCwd && headerCwd !== this.cwd) {
 				this.cwd = headerCwd;
 				this.sessionDir = path.resolve(this.#sessionFile, "..");
-				writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+				this.#maybeWriteBreadcrumb(this.cwd, this.#sessionFile);
 			}
 
 			this.#needsFullRewriteOnNextPersist = migrateToCurrentVersion(this.#fileEntries);
@@ -2245,7 +2251,7 @@ export class SessionManager {
 
 		// Update terminal breadcrumb
 		if (this.#sessionFile) {
-			writeTerminalBreadcrumb(resolvedCwd, this.#sessionFile);
+			this.#maybeWriteBreadcrumb(resolvedCwd, this.#sessionFile);
 		}
 	}
 
@@ -2280,7 +2286,7 @@ export class SessionManager {
 		if (this.persist) {
 			const fileTimestamp = timestamp.replace(/[:.]/g, "-");
 			this.#sessionFile = path.join(this.getSessionDir(), `${fileTimestamp}_${this.#sessionId}.jsonl`);
-			writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
+			this.#maybeWriteBreadcrumb(this.cwd, this.#sessionFile);
 		}
 		return this.#sessionFile;
 	}
@@ -3429,9 +3435,11 @@ export class SessionManager {
 		cwd: string,
 		sessionDir?: string,
 		storage: SessionStorage = new FileSessionStorage(),
+		options?: { suppressBreadcrumb?: boolean },
 	): Promise<SessionManager> {
 		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
 		const manager = new SessionManager(cwd, dir, true, storage);
+		manager.#suppressBreadcrumb = options?.suppressBreadcrumb === true;
 		const forkEntries = structuredClone(await loadEntriesFromFile(sourcePath, storage)) as FileEntry[];
 		migrateToCurrentVersion(forkEntries);
 		await resolveBlobRefsInEntries(forkEntries, manager.#blobStore);
diff --git a/packages/coding-agent/src/slash-commands/builtin-registry.ts b/packages/coding-agent/src/slash-commands/builtin-registry.ts
index af224fc18..ea564bde5 100644
--- a/packages/coding-agent/src/slash-commands/builtin-registry.ts
+++ b/packages/coding-agent/src/slash-commands/builtin-registry.ts
@@ -893,6 +893,17 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			await runtime.ctx.handleBtwCommand(question);
 		},
 	},
+	{
+		name: "tan",
+		description: "Run a full background agent on tangential work",
+		inlineHint: "<work>",
+		allowArgs: true,
+		handleTui: async (command, runtime) => {
+			const work = command.text.slice(`/${command.name}`.length).trim();
+			runtime.ctx.editor.setText("");
+			await runtime.ctx.handleTanCommand(work);
+		},
+	},
 	{
 		name: "omfg",
 		description: "Forge a TTSR rule from a complaint to stop a recurring behavior",
diff --git a/packages/coding-agent/src/task/executor.ts b/packages/coding-agent/src/task/executor.ts
index 254a2dc5e..6f47ab87a 100644
--- a/packages/coding-agent/src/task/executor.ts
+++ b/packages/coding-agent/src/task/executor.ts
@@ -488,7 +488,7 @@ function getUsageTokens(usage: unknown): number {
 /**
  * Create proxy tools that reuse the parent's MCP connections.
  */
-function createMCPProxyTools(mcpManager: MCPManager): CustomTool[] {
+export function createMCPProxyTools(mcpManager: MCPManager): CustomTool[] {
 	return mcpManager.getTools().map(tool => {
 		const mcpTool = tool as { mcpToolName?: string; mcpServerName?: string };
 		return {
@@ -538,7 +538,10 @@ function createMCPProxyTools(mcpManager: MCPManager): CustomTool[] {
 	});
 }
 
-function createSubagentSettings(baseSettings: Settings, overrides?: Partial<Record<SettingPath, unknown>>): Settings {
+export function createSubagentSettings(
+	baseSettings: Settings,
+	overrides?: Partial<Record<SettingPath, unknown>>,
+): Settings {
 	const snapshot: Partial<Record<SettingPath, unknown>> = {};
 	for (const key of Object.keys(SETTINGS_SCHEMA) as SettingPath[]) {
 		snapshot[key] = baseSettings.get(key);
diff --git a/packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts b/packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts
new file mode 100644
index 000000000..c41ad482c
--- /dev/null
+++ b/packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts
@@ -0,0 +1,214 @@
+import { afterEach, describe, expect, it, vi } from "bun:test";
+import * as path from "node:path";
+import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
+import type { AsyncJobRegisterOptions } from "@oh-my-pi/pi-coding-agent/async/job-manager";
+import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import { TanCommandController } from "@oh-my-pi/pi-coding-agent/modes/controllers/tan-command-controller";
+import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/types";
+import { MAIN_AGENT_ID } from "@oh-my-pi/pi-coding-agent/registry/agent-registry";
+import type { CreateAgentSessionOptions, CreateAgentSessionResult } from "@oh-my-pi/pi-coding-agent/sdk";
+import * as sdkModule from "@oh-my-pi/pi-coding-agent/sdk";
+import { SessionManager } from "@oh-my-pi/pi-coding-agent/session/session-manager";
+import { TempDir } from "@oh-my-pi/pi-utils";
+
+interface CapturedJobRunContext {
+	jobId: string;
+	signal: AbortSignal;
+	reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
+}
+
+type CapturedJobRun = (ctx: CapturedJobRunContext) => Promise<string>;
+
+const model = { provider: "anthropic", id: "claude-sonnet-4-5" } as Model;
+
+function assistantText(text: string): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [{ type: "text", text }],
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+	};
+}
+
+function createContext(overrides?: {
+	isStreaming?: boolean;
+	model?: Model;
+	agentId?: string;
+	register?: (run: CapturedJobRun, options?: AsyncJobRegisterOptions) => string;
+}) {
+	const tempDir = TempDir.createSync("@omp-tan-controller-");
+	const parentFile = path.join(tempDir.path(), "parent.jsonl");
+	// The clone nests inside the parent's artifact directory, like a subagent.
+	const cloneFile = path.join(parentFile.slice(0, -6), "clone.jsonl");
+	let capturedRun: CapturedJobRun | undefined;
+	let capturedOptions: AsyncJobRegisterOptions | undefined;
+	const sequence: string[] = [];
+	const register = vi.fn(
+		(_type: "bash" | "task", _label: string, run: CapturedJobRun, options?: AsyncJobRegisterOptions): string => {
+			sequence.push("register");
+			capturedRun = run;
+			capturedOptions = options;
+			return overrides?.register ? overrides.register(run, options) : "job-123";
+		},
+	);
+	const session = {
+		isStreaming: overrides?.isStreaming ?? false,
+		model: overrides?.model ?? model,
+		asyncJobManager: { register },
+		sessionId: "parent-session",
+		configuredThinkingLevel: vi.fn(() => undefined),
+		systemPrompt: ["system prompt"],
+		getActiveToolNames: vi.fn(() => ["read", "bash"]),
+		modelRegistry: { authStorage: { marker: "auth" } },
+		getAgentId: vi.fn(() => overrides?.agentId),
+		sendCustomMessage: vi.fn(async () => {
+			sequence.push("sendCustomMessage");
+		}),
+	} as unknown as InteractiveModeContext["session"];
+	const sessionManager = {
+		getSessionFile: vi.fn(() => parentFile),
+		getCwd: vi.fn(() => tempDir.path()),
+		getSessionDir: vi.fn(() => tempDir.path()),
+		ensureOnDisk: vi.fn(async () => {}),
+		flush: vi.fn(async () => {}),
+	} as unknown as InteractiveModeContext["sessionManager"];
+	const cloneManager = {
+		getSessionFile: vi.fn(() => cloneFile),
+	} as unknown as SessionManager;
+	const ctx = {
+		session,
+		sessionManager,
+		settings: Settings.isolated({ "task.enableLsp": true }),
+		showStatus: vi.fn(),
+		showWarning: vi.fn(),
+		showError: vi.fn(),
+		rebuildChatFromMessages: vi.fn(),
+	} as unknown as InteractiveModeContext;
+	return {
+		tempDir,
+		parentFile,
+		cloneFile,
+		cloneManager,
+		ctx,
+		register,
+		sequence,
+		get capturedRun() {
+			return capturedRun;
+		},
+		get capturedOptions() {
+			return capturedOptions;
+		},
+	};
+}
+
+describe("TanCommandController", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("rejects empty work before forking", async () => {
+		const harness = createContext();
+		const forkSpy = vi.spyOn(SessionManager, "forkFrom").mockResolvedValue(harness.cloneManager);
+		const controller = new TanCommandController(harness.ctx);
+
+		await controller.start("   ");
+
+		expect(forkSpy).not.toHaveBeenCalled();
+		expect(harness.ctx.showStatus).toHaveBeenCalledWith("Usage: /tan <work>");
+	});
+
+	it("rejects while the parent session is streaming", async () => {
+		const harness = createContext({ isStreaming: true });
+		const forkSpy = vi.spyOn(SessionManager, "forkFrom").mockResolvedValue(harness.cloneManager);
+		const controller = new TanCommandController(harness.ctx);
+
+		await controller.start("check something");
+
+		expect(forkSpy).not.toHaveBeenCalled();
+		expect(harness.ctx.showWarning).toHaveBeenCalled();
+	});
+
+	it("forks with breadcrumb suppression, registers under Main, and dispatches after receiving the job id", async () => {
+		const harness = createContext();
+		const forkSpy = vi.spyOn(SessionManager, "forkFrom").mockResolvedValue(harness.cloneManager);
+		const controller = new TanCommandController(harness.ctx);
+
+		await controller.start("write the release note");
+
+		expect(forkSpy).toHaveBeenCalledWith(
+			harness.parentFile,
+			harness.tempDir.path(),
+			harness.parentFile.slice(0, -6),
+			undefined,
+			{ suppressBreadcrumb: true },
+		);
+		expect(harness.register).toHaveBeenCalledWith("task", "/tan write the release note", expect.any(Function), {
+			ownerId: MAIN_AGENT_ID,
+		});
+		expect(harness.capturedOptions?.ownerId).toBe(MAIN_AGENT_ID);
+		expect(harness.sequence).toEqual(["register", "sendCustomMessage"]);
+		expect(harness.ctx.session.sendCustomMessage).toHaveBeenCalledWith(
+			expect.objectContaining({
+				customType: "background-tan-dispatch",
+				details: { jobId: "job-123", work: "write the release note", sessionFile: harness.cloneFile },
+			}),
+			{ triggerTurn: false },
+		);
+		expect(harness.ctx.rebuildChatFromMessages).toHaveBeenCalled();
+		expect(harness.ctx.showStatus).toHaveBeenCalledWith("Dispatched background tan job-123");
+	});
+
+	it("aborts the cloned agent when the background job signal aborts", async () => {
+		const harness = createContext({ agentId: MAIN_AGENT_ID });
+		vi.spyOn(SessionManager, "forkFrom").mockResolvedValue(harness.cloneManager);
+		const promptStarted = Promise.withResolvers<void>();
+		const abortObserved = Promise.withResolvers<void>();
+		const clone = {
+			prompt: vi.fn(async () => {
+				promptStarted.resolve();
+				await abortObserved.promise;
+			}),
+			waitForIdle: vi.fn(async () => {}),
+			getLastAssistantMessage: vi.fn(() => assistantText("finished")),
+			abort: vi.fn(() => {
+				abortObserved.resolve();
+			}),
+			dispose: vi.fn(async () => {}),
+		};
+		const createAgentSessionSpy = vi
+			.spyOn(sdkModule, "createAgentSession")
+			.mockResolvedValue({ session: clone } as unknown as CreateAgentSessionResult);
+		const controller = new TanCommandController(harness.ctx);
+		await controller.start("follow the tangent");
+		const capturedRun = harness.capturedRun;
+		expect(capturedRun).toBeDefined();
+		if (!capturedRun) throw new Error("run function was not captured");
+		const abortController = new AbortController();
+
+		const resultPromise = capturedRun({
+			jobId: "job-123",
+			signal: abortController.signal,
+			reportProgress: async () => {},
+		});
+		await promptStarted.promise;
+		abortController.abort();
+		const result = await resultPromise;
+
+		expect(result).toBe("finished");
+		expect(clone.abort).toHaveBeenCalled();
+		expect(clone.dispose).toHaveBeenCalled();
+		expect(createAgentSessionSpy.mock.calls[0]?.[0]).toEqual(
+			expect.objectContaining<CreateAgentSessionOptions>({
+				providerPromptCacheKey: "parent-session",
+				parentTaskPrefix: expect.stringMatching(/^Tan-/) as unknown as string,
+				agentDisplayName: "tan",
+			}),
+		);
+	});
+});
diff --git a/packages/coding-agent/test/slash-commands/tan.test.ts b/packages/coding-agent/test/slash-commands/tan.test.ts
new file mode 100644
index 000000000..348978db4
--- /dev/null
+++ b/packages/coding-agent/test/slash-commands/tan.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "bun:test";
+import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/types";
+import { executeBuiltinSlashCommand } from "@oh-my-pi/pi-coding-agent/slash-commands/builtin-registry";
+
+function createRuntime() {
+	const handleTanCommand = vi.fn(async () => {});
+	const setText = vi.fn();
+	return {
+		handleTanCommand,
+		setText,
+		runtime: {
+			ctx: {
+				editor: { setText } as unknown as InteractiveModeContext["editor"],
+				handleTanCommand,
+			} as unknown as InteractiveModeContext,
+		},
+	};
+}
+
+describe("/tan slash command", () => {
+	it("routes the full work item through the tan handler", async () => {
+		const harness = createRuntime();
+
+		const handled = await executeBuiltinSlashCommand("/tan add a changelog note", harness.runtime);
+
+		expect(handled).toBe(true);
+		expect(harness.setText).toHaveBeenCalledWith("");
+		expect(harness.handleTanCommand).toHaveBeenCalledWith("add a changelog note");
+	});
+
+	it("preserves the raw multi-word suffix after /tan", async () => {
+		const harness = createRuntime();
+
+		const handled = await executeBuiltinSlashCommand(
+			"/tan    investigate why prompt cache reuse matters here",
+			harness.runtime,
+		);
+
+		expect(handled).toBe(true);
+		expect(harness.handleTanCommand).toHaveBeenCalledWith("investigate why prompt cache reuse matters here");
+	});
+});
diff --git a/packages/coding-agent/test/tools/tool-output-hyperlinks.test.ts b/packages/coding-agent/test/tools/tool-output-hyperlinks.test.ts
index c631385f9..e7da44dfc 100644
--- a/packages/coding-agent/test/tools/tool-output-hyperlinks.test.ts
+++ b/packages/coding-agent/test/tools/tool-output-hyperlinks.test.ts
@@ -3,12 +3,12 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resetSettingsForTest, Settings, settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import { editToolRenderer } from "@oh-my-pi/pi-coding-agent/edit/renderer";
 import type { ToolSession } from "@oh-my-pi/pi-coding-agent/tools";
 import { astGrepToolRenderer } from "@oh-my-pi/pi-coding-agent/tools/ast-grep";
 import { ReadTool, readToolRenderer } from "@oh-my-pi/pi-coding-agent/tools/read";
 import { searchToolRenderer } from "@oh-my-pi/pi-coding-agent/tools/search";
 import { WriteTool, writeToolRenderer } from "@oh-my-pi/pi-coding-agent/tools/write";
-import { editToolRenderer } from "@oh-my-pi/pi-coding-agent/edit/renderer";
 import { getThemeByName, initTheme } from "../../src/modes/theme/theme";
 
 // 1x1 PNG so the read tool takes its image branch.

From cbd7c201055518e0da4df30fc8d70edd12702bbc Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:55:52 +0200
Subject: [PATCH 109/181] feat(coding-agent/tools): added binary routing for
 notebook, sqlite, and archive payloads

- Added archive format sniffing to identify ZIP, TAR, and TAR.GZ from file bytes.
- Added MIME/extension and header-based routing for notebook, sqlite, and archive payloads.
- Added archive entry rendering with slash-terminated dirs and size suffixes.
- Added tests for archive, sqlite, notebook, and fallback binary dispatch scenarios.
---
 .../coding-agent/src/tools/archive-reader.ts  |  64 ++++
 packages/coding-agent/src/tools/fetch.ts      | 304 +++++++++++++++++-
 packages/coding-agent/src/tools/read.ts       |  13 +-
 .../coding-agent/src/tools/sqlite-reader.ts   |  21 +-
 .../test/tools/fetch-binary-dispatch.test.ts  | 217 +++++++++++++
 5 files changed, 590 insertions(+), 29 deletions(-)
 create mode 100644 packages/coding-agent/test/tools/fetch-binary-dispatch.test.ts

diff --git a/packages/coding-agent/src/tools/archive-reader.ts b/packages/coding-agent/src/tools/archive-reader.ts
index 11b09b0ad..cdcd8ae63 100644
--- a/packages/coding-agent/src/tools/archive-reader.ts
+++ b/packages/coding-agent/src/tools/archive-reader.ts
@@ -1,5 +1,9 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
 import { inflateSync, strFromU8 } from "fflate";
 
+import { formatBytes } from "./render-utils";
 import { ToolError } from "./tool-errors";
 
 export type ArchiveFormat = "zip" | "tar" | "tar.gz";
@@ -123,11 +127,21 @@ function getArchiveFormatFromPath(filePath: string): ArchiveFormat | undefined {
 	return undefined;
 }
 
+export function formatArchiveEntryLines(entries: readonly ArchiveDirectoryEntry[]): string[] {
+	return entries.map(entry => {
+		if (entry.isDirectory) return `${entry.name}/`;
+
+		const sizeSuffix = entry.size > 0 ? ` (${formatBytes(entry.size)})` : "";
+		return `${entry.name}${sizeSuffix}`;
+	});
+}
+
 const ZIP_LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
 const ZIP_CENTRAL_DIRECTORY_HEADER_SIGNATURE = 0x02014b50;
 const ZIP64_EOCD_SIGNATURE = 0x06064b50;
 const ZIP64_EOCD_LOCATOR_SIGNATURE = 0x07064b50;
 const ZIP_EOCD_SIGNATURE = 0x06054b50;
+const ZIP_DATA_DESCRIPTOR_SIGNATURE = 0x08074b50;
 const ZIP_EOCD_MIN_LENGTH = 22;
 const ZIP_EOCD_MAX_COMMENT_LENGTH = 0xffff;
 const ZIP64_EOCD_LOCATOR_LENGTH = 20;
@@ -167,6 +181,37 @@ function readUInt32LE(bytes: Uint8Array, offset: number): number {
 	return (bytes[offset]! | (bytes[offset + 1]! << 8) | (bytes[offset + 2]! << 16) | (bytes[offset + 3]! << 24)) >>> 0;
 }
 
+function bytesMatchAscii(bytes: Uint8Array, offset: number, value: string): boolean {
+	if (bytes.byteLength < offset + value.length) return false;
+	for (let index = 0; index < value.length; index++) {
+		if (bytes[offset + index] !== value.charCodeAt(index)) return false;
+	}
+	return true;
+}
+
+export function sniffArchiveFormat(bytes: Uint8Array): ArchiveFormat | undefined {
+	if (bytes.byteLength >= 4) {
+		const signature = readUInt32LE(bytes, 0);
+		if (
+			signature === ZIP_LOCAL_FILE_HEADER_SIGNATURE ||
+			signature === ZIP_EOCD_SIGNATURE ||
+			signature === ZIP_DATA_DESCRIPTOR_SIGNATURE
+		) {
+			return "zip";
+		}
+	}
+
+	if (bytes.byteLength >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b) {
+		return "tar.gz";
+	}
+
+	if (bytesMatchAscii(bytes, 257, "ustar")) {
+		return "tar";
+	}
+
+	return undefined;
+}
+
 function readUInt64LEAsNumber(bytes: Uint8Array, offset: number): number {
 	const value = readUInt32LE(bytes, offset) + readUInt32LE(bytes, offset + 4) * ZIP_UINT32_RANGE;
 	if (!Number.isSafeInteger(value)) {
@@ -627,3 +672,22 @@ export async function openArchive(filePath: string): Promise<ArchiveReader> {
 		format === "zip" ? await readZipEntries(filePath) : await readTarEntries(await Bun.file(filePath).bytes());
 	return new ArchiveReader(format, entries);
 }
+
+export async function listArchiveRoot(
+	bytes: Uint8Array,
+	format: ArchiveFormat,
+	opts: { limit?: number } = {},
+): Promise<string> {
+	const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-archive-"));
+	const tempPath = path.join(tempDir, `payload.${format}`);
+	try {
+		await Bun.write(tempPath, bytes);
+		const archive = await openArchive(tempPath);
+		const entries = archive.listDirectory("");
+		const limitedEntries = opts.limit !== undefined && opts.limit > 0 ? entries.slice(0, opts.limit) : entries;
+		const lines = formatArchiveEntryLines(limitedEntries);
+		return lines.length > 0 ? lines.join("\n") : "(empty archive directory)";
+	} finally {
+		await fs.rm(tempDir, { recursive: true, force: true });
+	}
+}
diff --git a/packages/coding-agent/src/tools/fetch.ts b/packages/coding-agent/src/tools/fetch.ts
index 4e2dcbecf..4d16ced81 100644
--- a/packages/coding-agent/src/tools/fetch.ts
+++ b/packages/coding-agent/src/tools/fetch.ts
@@ -1,4 +1,6 @@
+import { Database } from "bun:sqlite";
 import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
@@ -8,6 +10,7 @@ import { $which, ptree, truncate } from "@oh-my-pi/pi-utils";
 import { parseHTML } from "linkedom";
 import { LRUCache } from "lru-cache/raw";
 import type { Settings } from "../config/settings";
+import { readEditableNotebookText } from "../edit/notebook";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme, theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
@@ -22,10 +25,12 @@ import { specialHandlers } from "../web/scrapers";
 import type { RenderResult } from "../web/scrapers/types";
 import { finalizeOutput, loadPage, looksLikeHtml, MAX_OUTPUT_CHARS } from "../web/scrapers/types";
 import { convertWithMarkit, fetchBinary } from "../web/scrapers/utils";
+import { type ArchiveFormat, listArchiveRoot, sniffArchiveFormat } from "./archive-reader";
 import { applyListLimit } from "./list-limit";
 import { formatStyledArtifactReference, type OutputMeta } from "./output-meta";
 import { type LineRange, parseLineRanges } from "./path-utils";
-import { formatExpandHint, getDomain, replaceTabs } from "./render-utils";
+import { formatBytes, formatExpandHint, getDomain, replaceTabs } from "./render-utils";
+import { listTables, looksLikeSqlite, renderTableList } from "./sqlite-reader";
 import { ToolAbortError, ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 import { clampTimeout } from "./tool-timeouts";
@@ -46,8 +51,6 @@ const CONVERTIBLE_MIMES = new Set([
 	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
 	"application/rtf",
 	"application/epub+zip",
-	"application/x-ipynb+json",
-	"application/zip",
 	"image/png",
 	"image/jpeg",
 	"image/gif",
@@ -67,7 +70,6 @@ const CONVERTIBLE_EXTENSIONS = new Set([
 	".xlsx",
 	".rtf",
 	".epub",
-	".ipynb",
 	".png",
 	".jpg",
 	".jpeg",
@@ -78,6 +80,27 @@ const CONVERTIBLE_EXTENSIONS = new Set([
 	".ogg",
 ]);
 
+const NOTEBOOK_MIMES = new Set(["application/x-ipynb+json"]);
+const NOTEBOOK_EXTENSIONS = new Set([".ipynb"]);
+
+const SQLITE_MIMES = new Set([
+	"application/vnd.sqlite3",
+	"application/x-sqlite3",
+	"application/sqlite3",
+	"application/sqlite",
+]);
+const SQLITE_EXTENSIONS = new Set([".sqlite", ".sqlite3", ".db", ".db3"]);
+
+const ARCHIVE_MIMES = new Set([
+	"application/zip",
+	"application/x-zip-compressed",
+	"application/x-tar",
+	"application/tar",
+	"application/gzip",
+	"application/x-gzip",
+]);
+const ARCHIVE_EXTENSIONS = new Set([".zip", ".tar", ".tar.gz", ".tgz", ".gz"]);
+
 const IMAGE_MIME_BY_EXTENSION = new Map<string, string>([
 	[".png", "image/png"],
 	[".jpg", "image/jpeg"],
@@ -261,6 +284,12 @@ function normalizeMime(contentType: string): string {
 	return contentType.split(";")[0].trim().toLowerCase();
 }
 
+function getFilenameExtensionHint(filename: string): string {
+	const lower = filename.toLowerCase();
+	if (lower.endsWith(".tar.gz")) return ".tar.gz";
+	return path.extname(filename).toLowerCase();
+}
+
 /**
  * Get extension from URL or Content-Disposition
  */
@@ -269,7 +298,7 @@ function getExtensionHint(url: string, contentDisposition?: string): string {
 	if (contentDisposition) {
 		const match = contentDisposition.match(/filename[*]?=["']?([^"';\n]+)/i);
 		if (match) {
-			const ext = path.extname(match[1]).toLowerCase();
+			const ext = getFilenameExtensionHint(match[1]);
 			if (ext) return ext;
 		}
 	}
@@ -277,7 +306,7 @@ function getExtensionHint(url: string, contentDisposition?: string): string {
 	// Fall back to URL path
 	try {
 		const pathname = new URL(url).pathname;
-		const ext = path.extname(pathname).toLowerCase();
+		const ext = getFilenameExtensionHint(pathname);
 		if (ext) return ext;
 	} catch {}
 
@@ -738,6 +767,254 @@ type FetchRenderResult = RenderResult & {
 	image?: FetchImagePayload;
 };
 
+const BINARY_SAMPLE_CHARS = 4096;
+const URL_ARCHIVE_LIST_LIMIT = 500;
+const URL_SQLITE_LIST_LIMIT = 500;
+
+function sampleLooksBinary(text: string): boolean {
+	const limit = Math.min(text.length, BINARY_SAMPLE_CHARS);
+	if (limit === 0) return false;
+
+	let replacementCount = 0;
+	for (let index = 0; index < limit; index++) {
+		const code = text.charCodeAt(index);
+		if (code === 0) return true;
+		if (code === 0xfffd) replacementCount++;
+	}
+
+	return replacementCount >= 3 && replacementCount / limit > 0.01;
+}
+
+function isNotebookHint(mime: string, extensionHint: string): boolean {
+	return NOTEBOOK_MIMES.has(mime) || NOTEBOOK_EXTENSIONS.has(extensionHint);
+}
+
+function isSqliteHint(mime: string, extensionHint: string): boolean {
+	return SQLITE_MIMES.has(mime) || SQLITE_EXTENSIONS.has(extensionHint);
+}
+
+function isArchiveHint(mime: string, extensionHint: string): boolean {
+	return ARCHIVE_MIMES.has(mime) || ARCHIVE_EXTENSIONS.has(extensionHint);
+}
+
+function getArchiveFormatHint(mime: string, extensionHint: string): ArchiveFormat | undefined {
+	if (extensionHint === ".zip" || mime === "application/zip" || mime === "application/x-zip-compressed") {
+		return "zip";
+	}
+	if (extensionHint === ".tar" || mime === "application/x-tar" || mime === "application/tar") {
+		return "tar";
+	}
+	if (
+		extensionHint === ".tar.gz" ||
+		extensionHint === ".tgz" ||
+		extensionHint === ".gz" ||
+		mime === "application/gzip" ||
+		mime === "application/x-gzip"
+	) {
+		return "tar.gz";
+	}
+	return undefined;
+}
+
+function formatErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function binaryContentType(mime: string): string {
+	return mime || "application/octet-stream";
+}
+
+function buildBinaryNotice(finalUrl: string, mime: string, byteLength?: number): string {
+	const size = byteLength === undefined ? "unknown size" : formatBytes(byteLength);
+	return `[Binary content: ${binaryContentType(mime)}, ${size}] ${finalUrl}`;
+}
+
+function buildBinaryPayloadResult(
+	url: string,
+	finalUrl: string,
+	mime: string,
+	method: string,
+	content: string,
+	fetchedAt: string,
+	notes: string[],
+): FetchRenderResult {
+	const output = finalizeOutput(content);
+	return {
+		url,
+		finalUrl,
+		contentType: binaryContentType(mime),
+		method,
+		content: output.content,
+		fetchedAt,
+		truncated: output.truncated,
+		notes,
+	};
+}
+
+async function withTempBinaryFile<T>(
+	prefix: string,
+	extension: string,
+	bytes: Uint8Array,
+	readTempFile: (tempPath: string) => Promise<T>,
+): Promise<T> {
+	const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), prefix));
+	const tempPath = path.join(tempDir, `payload${extension}`);
+	try {
+		await Bun.write(tempPath, bytes);
+		return await readTempFile(tempPath);
+	} finally {
+		await fs.rm(tempDir, { recursive: true, force: true });
+	}
+}
+
+async function renderNotebookPayload(bytes: Uint8Array, displayUrl: string): Promise<string> {
+	return withTempBinaryFile("omp-url-notebook-", ".ipynb", bytes, tempPath =>
+		readEditableNotebookText(tempPath, displayUrl),
+	);
+}
+
+async function renderSqlitePayload(bytes: Uint8Array): Promise<string> {
+	return withTempBinaryFile("omp-url-sqlite-", ".sqlite", bytes, async tempPath => {
+		let db: Database | null = null;
+		try {
+			db = new Database(tempPath, { readonly: true, strict: true });
+			db.run("PRAGMA busy_timeout = 3000");
+			const listLimit = applyListLimit(listTables(db), { limit: URL_SQLITE_LIST_LIMIT });
+			return renderTableList(listLimit.items);
+		} finally {
+			db?.close();
+		}
+	});
+}
+
+async function tryRenderBinaryPayload(
+	url: string,
+	finalUrl: string,
+	mime: string,
+	extHint: string,
+	rawContent: string,
+	timeout: number,
+	signal: AbortSignal | undefined,
+	fetchedAt: string,
+	notes: readonly string[],
+): Promise<FetchRenderResult | null> {
+	const hasNotebookHint = isNotebookHint(mime, extHint);
+	const hasSqliteHint = isSqliteHint(mime, extHint);
+	const hasArchiveHint = isArchiveHint(mime, extHint);
+	const rawLooksBinary = sampleLooksBinary(rawContent);
+	if (!hasNotebookHint && !hasSqliteHint && !hasArchiveHint && !rawLooksBinary) {
+		return null;
+	}
+
+	const resultNotes = [...notes];
+	const binary = await fetchBinary(finalUrl, timeout, signal);
+	if (!binary.ok) {
+		resultNotes.push(binary.error ? `Binary fetch failed: ${binary.error}` : "Binary fetch failed");
+		return buildBinaryPayloadResult(
+			url,
+			finalUrl,
+			mime,
+			"binary",
+			buildBinaryNotice(finalUrl, mime),
+			fetchedAt,
+			resultNotes,
+		);
+	}
+
+	const binaryExtHint = getExtensionHint(finalUrl, binary.contentDisposition) || extHint;
+	if (isNotebookHint(mime, binaryExtHint)) {
+		try {
+			return buildBinaryPayloadResult(
+				url,
+				finalUrl,
+				mime,
+				"notebook",
+				await renderNotebookPayload(binary.buffer, finalUrl),
+				fetchedAt,
+				resultNotes,
+			);
+		} catch (error) {
+			resultNotes.push(`Notebook rendering failed: ${formatErrorMessage(error)}`);
+			return buildBinaryPayloadResult(
+				url,
+				finalUrl,
+				mime,
+				"binary",
+				buildBinaryNotice(finalUrl, mime, binary.buffer.byteLength),
+				fetchedAt,
+				resultNotes,
+			);
+		}
+	}
+
+	if (isSqliteHint(mime, binaryExtHint) || looksLikeSqlite(binary.buffer)) {
+		try {
+			return buildBinaryPayloadResult(
+				url,
+				finalUrl,
+				mime,
+				"sqlite",
+				await renderSqlitePayload(binary.buffer),
+				fetchedAt,
+				resultNotes,
+			);
+		} catch (error) {
+			resultNotes.push(`SQLite rendering failed: ${formatErrorMessage(error)}`);
+			return buildBinaryPayloadResult(
+				url,
+				finalUrl,
+				mime,
+				"binary",
+				buildBinaryNotice(finalUrl, mime, binary.buffer.byteLength),
+				fetchedAt,
+				resultNotes,
+			);
+		}
+	}
+
+	const hintedArchiveFormat = getArchiveFormatHint(mime, binaryExtHint);
+	const shouldArchiveSniff = hintedArchiveFormat !== undefined || !isConvertible(mime, binaryExtHint);
+	const archiveFormat = hintedArchiveFormat ?? (shouldArchiveSniff ? sniffArchiveFormat(binary.buffer) : undefined);
+	if (archiveFormat) {
+		try {
+			return buildBinaryPayloadResult(
+				url,
+				finalUrl,
+				mime,
+				"archive",
+				await listArchiveRoot(binary.buffer, archiveFormat, { limit: URL_ARCHIVE_LIST_LIMIT }),
+				fetchedAt,
+				resultNotes,
+			);
+		} catch (error) {
+			resultNotes.push(`Archive rendering failed: ${formatErrorMessage(error)}`);
+			return buildBinaryPayloadResult(
+				url,
+				finalUrl,
+				mime,
+				"binary",
+				buildBinaryNotice(finalUrl, mime, binary.buffer.byteLength),
+				fetchedAt,
+				resultNotes,
+			);
+		}
+	}
+
+	if (rawLooksBinary) {
+		return buildBinaryPayloadResult(
+			url,
+			finalUrl,
+			mime,
+			"binary",
+			buildBinaryNotice(finalUrl, mime, binary.buffer.byteLength),
+			fetchedAt,
+			resultNotes,
+		);
+	}
+
+	return null;
+}
+
 // =============================================================================
 // Unified Special Handler Dispatch
 // =============================================================================
@@ -984,6 +1261,19 @@ async function renderUrl(
 		}
 	}
 
+	const binaryPayloadResult = await tryRenderBinaryPayload(
+		url,
+		finalUrl,
+		mime,
+		extHint,
+		rawContent,
+		timeout,
+		signal,
+		fetchedAt,
+		notes,
+	);
+	if (binaryPayloadResult) return binaryPayloadResult;
+
 	// Step 4: Handle non-HTML text content
 	const isHtml = mime.includes("html") || mime.includes("xhtml");
 	const isJson = mime.includes("json");
@@ -992,7 +1282,7 @@ async function renderUrl(
 	const isFeed = mime.includes("rss") || mime.includes("atom") || mime.includes("feed");
 
 	// Raw mode skips every text-shaping branch below (JSON pretty-print, feed-to-markdown,
-	// HTML extraction) and returns the response body verbatim. The image/markit branches
+	// HTML extraction) and returns the response body verbatim. Binary-oriented branches
 	// above already ran because raw isn't useful for binary payloads.
 	if (raw) {
 		const output = finalizeOutput(rawContent);
diff --git a/packages/coding-agent/src/tools/read.ts b/packages/coding-agent/src/tools/read.ts
index 48df2758b..020ac82b4 100644
--- a/packages/coding-agent/src/tools/read.ts
+++ b/packages/coding-agent/src/tools/read.ts
@@ -34,7 +34,7 @@ import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { ImageInputTooLargeError, loadImageInput, MAX_IMAGE_INPUT_BYTES } from "../utils/image-loading";
 import { convertFileWithMarkit } from "../utils/markit";
 import { buildDirectoryTree, type DirectoryTree } from "../workspace-tree";
-import { type ArchiveReader, openArchive, parseArchivePathCandidates } from "./archive-reader";
+import { type ArchiveReader, formatArchiveEntryLines, openArchive, parseArchivePathCandidates } from "./archive-reader";
 import {
 	type ConflictEntry,
 	type ConflictScope,
@@ -1154,17 +1154,10 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		const limitedEntries = listLimit.items;
 		const limitMeta = listLimit.meta;
 
-		const results: string[] = [];
-		for (const entry of limitedEntries) {
+		for (let index = 0; index < limitedEntries.length; index++) {
 			throwIfAborted(signal);
-			if (entry.isDirectory) {
-				results.push(`${entry.name}/`);
-				continue;
-			}
-
-			const sizeSuffix = entry.size > 0 ? ` (${formatBytes(entry.size)})` : "";
-			results.push(`${entry.name}${sizeSuffix}`);
 		}
+		const results = formatArchiveEntryLines(limitedEntries);
 
 		const output = results.length > 0 ? results.join("\n") : "(empty archive directory)";
 		const text = prependSuffixResolutionNotice(output, details.suffixResolution);
diff --git a/packages/coding-agent/src/tools/sqlite-reader.ts b/packages/coding-agent/src/tools/sqlite-reader.ts
index 37948a48d..710c7fa66 100644
--- a/packages/coding-agent/src/tools/sqlite-reader.ts
+++ b/packages/coding-agent/src/tools/sqlite-reader.ts
@@ -5,6 +5,14 @@ import { ToolError } from "./tool-errors";
 const SQLITE_MAGIC = new Uint8Array([
 	0x53, 0x51, 0x4c, 0x69, 0x74, 0x65, 0x20, 0x66, 0x6f, 0x72, 0x6d, 0x61, 0x74, 0x20, 0x33, 0x00,
 ]);
+
+export function looksLikeSqlite(bytes: Uint8Array): boolean {
+	if (bytes.byteLength < SQLITE_MAGIC.byteLength) return false;
+	for (const [index, byte] of SQLITE_MAGIC.entries()) {
+		if (bytes[index] !== byte) return false;
+	}
+	return true;
+}
 const SQLITE_PATH_PATTERN = /\.(?:sqlite3?|db3?)(?=(?::|\?|$))/gi;
 const DEFAULT_QUERY_LIMIT = 20;
 const DEFAULT_SCHEMA_SAMPLE_LIMIT = 5;
@@ -443,18 +451,7 @@ export function parseSqlitePathCandidates(filePath: string): SqlitePathCandidate
 
 export async function isSqliteFile(absolutePath: string): Promise<boolean> {
 	try {
-		const bytes = await Bun.file(absolutePath).slice(0, SQLITE_MAGIC.byteLength).bytes();
-		if (bytes.length !== SQLITE_MAGIC.byteLength) {
-			return false;
-		}
-
-		for (const [index, byte] of SQLITE_MAGIC.entries()) {
-			if (bytes[index] !== byte) {
-				return false;
-			}
-		}
-
-		return true;
+		return looksLikeSqlite(await Bun.file(absolutePath).slice(0, SQLITE_MAGIC.byteLength).bytes());
 	} catch {
 		return false;
 	}
diff --git a/packages/coding-agent/test/tools/fetch-binary-dispatch.test.ts b/packages/coding-agent/test/tools/fetch-binary-dispatch.test.ts
new file mode 100644
index 000000000..cab602c17
--- /dev/null
+++ b/packages/coding-agent/test/tools/fetch-binary-dispatch.test.ts
@@ -0,0 +1,217 @@
+import { Database } from "bun:sqlite";
+import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
+import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import type { ToolSession } from "@oh-my-pi/pi-coding-agent/tools";
+import { ReadTool } from "@oh-my-pi/pi-coding-agent/tools/read";
+import * as scrapers from "@oh-my-pi/pi-coding-agent/web/scrapers/types";
+import * as scraperUtils from "@oh-my-pi/pi-coding-agent/web/scrapers/utils";
+import { Snowflake } from "@oh-my-pi/pi-utils";
+import { zipSync } from "fflate";
+
+function makeSession(testDir: string): ToolSession {
+	const sessionFile = path.join(testDir, "session.jsonl");
+	const artifactsDir = sessionFile.slice(0, -6);
+	let nextArtifactId = 0;
+	return {
+		cwd: testDir,
+		hasUI: false,
+		getSessionFile: () => sessionFile,
+		getArtifactsDir: () => artifactsDir,
+		getSessionSpawns: () => null,
+		allocateOutputArtifact: async toolType => {
+			const id = String(nextArtifactId++);
+			return { id, path: path.join(artifactsDir, `${id}.${toolType}.log`) };
+		},
+		settings: Settings.isolated({ "fetch.enabled": true }),
+	};
+}
+
+function stubUrlBytes(bytes: Uint8Array, contentType: string, contentDisposition?: string) {
+	const decoded = Buffer.from(bytes).toString("utf-8");
+	vi.spyOn(scrapers, "loadPage").mockImplementation(async requestedUrl => ({
+		ok: true,
+		status: 200,
+		finalUrl: requestedUrl,
+		contentType,
+		content: decoded,
+	}));
+	return vi.spyOn(scraperUtils, "fetchBinary").mockImplementation(async () => ({
+		ok: true,
+		buffer: bytes,
+		contentDisposition,
+	}));
+}
+
+function stubUrlText(body: string, contentType: string) {
+	vi.spyOn(scrapers, "loadPage").mockImplementation(async requestedUrl => ({
+		ok: true,
+		status: 200,
+		finalUrl: requestedUrl,
+		contentType,
+		content: body,
+	}));
+	return vi.spyOn(scraperUtils, "fetchBinary").mockImplementation(async () => {
+		throw new Error("unexpected binary fetch");
+	});
+}
+
+function textOutput(result: { content: Array<TextContent | ImageContent> }): string {
+	return result.content
+		.filter((content): content is TextContent => content.type === "text")
+		.map(content => content.text)
+		.join("\n");
+}
+
+async function createSqliteFixtureBytes(testDir: string): Promise<Uint8Array> {
+	const dbPath = path.join(testDir, `url-fixture-${Snowflake.next()}.sqlite`);
+	const db = new Database(dbPath);
+	try {
+		db.exec(`
+			CREATE TABLE notes (id INTEGER PRIMARY KEY, title TEXT NOT NULL);
+			INSERT INTO notes (title) VALUES ('alpha'), ('beta');
+		`);
+	} finally {
+		db.close();
+	}
+	return Bun.file(dbPath).bytes();
+}
+
+function createNotebookFixtureBytes(): Uint8Array {
+	return Buffer.from(
+		JSON.stringify({
+			cells: [
+				{ cell_type: "markdown", metadata: {}, source: ["# Remote notebook\n", "Rendered as editable cells"] },
+				{ cell_type: "code", execution_count: null, metadata: {}, outputs: [], source: ["answer = 42\n"] },
+			],
+			metadata: {},
+			nbformat: 4,
+			nbformat_minor: 5,
+		}),
+	);
+}
+
+function uniqueUrl(name: string, extension: string): string {
+	return `https://example.com/${name}-${Snowflake.next()}${extension}`;
+}
+
+describe("read URL binary dispatch", () => {
+	let testDir: string;
+
+	beforeEach(() => {
+		testDir = path.join(os.tmpdir(), `fetch-binary-dispatch-${Snowflake.next()}`);
+		fs.mkdirSync(testDir, { recursive: true });
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+		fs.rmSync(testDir, { recursive: true, force: true });
+	});
+
+	it("lists a remote zip instead of dumping decoded bytes", async () => {
+		const zipBytes = zipSync({
+			"root.txt": Buffer.from("root file\n"),
+			"nested/data.txt": Buffer.from("nested file\n"),
+		});
+		const url = uniqueUrl("archive", ".zip");
+		stubUrlBytes(zipBytes, "application/octet-stream");
+
+		const tool = new ReadTool(makeSession(testDir));
+		const result = await tool.execute("read-url-zip", { path: url });
+		const text = textOutput(result);
+
+		expect(result.details?.method).toBe("archive");
+		expect(text).toContain("Method: archive");
+		expect(text).toContain("root.txt");
+		expect(text).toContain("nested/");
+		expect(text).not.toContain("PK\u0003\u0004");
+		expect(text).not.toContain("�");
+	});
+
+	it("returns a metadata notice when a hinted binary refetch fails", async () => {
+		const url = uniqueUrl("oversized", ".zip");
+		vi.spyOn(scrapers, "loadPage").mockImplementation(async requestedUrl => ({
+			ok: true,
+			status: 200,
+			finalUrl: requestedUrl,
+			contentType: "application/octet-stream",
+			content: "PK\u0003\u0004\u0000\u0001",
+		}));
+		vi.spyOn(scraperUtils, "fetchBinary").mockResolvedValue({
+			ok: false,
+			error: "content-length 52428801 exceeds 52428800",
+		});
+
+		const tool = new ReadTool(makeSession(testDir));
+		const result = await tool.execute("read-url-zip-too-large", { path: url });
+		const text = textOutput(result);
+
+		expect(result.details?.method).toBe("binary");
+		expect(result.details?.notes).toContain("Binary fetch failed: content-length 52428801 exceeds 52428800");
+		expect(text).toContain("[Binary content: application/octet-stream");
+		expect(text).not.toContain("PK\u0003\u0004");
+	});
+
+	it("renders a remote sqlite database through the sqlite reader", async () => {
+		const sqliteBytes = await createSqliteFixtureBytes(testDir);
+		const url = uniqueUrl("data", ".db");
+		stubUrlBytes(sqliteBytes, "application/octet-stream");
+
+		const tool = new ReadTool(makeSession(testDir));
+		const result = await tool.execute("read-url-sqlite", { path: url });
+		const text = textOutput(result);
+
+		expect(result.details?.method).toBe("sqlite");
+		expect(text).toContain("Method: sqlite");
+		expect(text).toContain("notes (2 rows)");
+	});
+
+	it("renders a remote notebook as editable cells", async () => {
+		const notebookBytes = createNotebookFixtureBytes();
+		const url = uniqueUrl("notebook", ".ipynb");
+		stubUrlBytes(notebookBytes, "application/octet-stream");
+
+		const tool = new ReadTool(makeSession(testDir));
+		const result = await tool.execute("read-url-notebook", { path: url });
+		const text = textOutput(result);
+
+		expect(result.details?.method).toBe("notebook");
+		expect(text).toContain("Method: notebook");
+		expect(text).toContain("# %% [markdown] cell:0");
+		expect(text).toContain("# %% [code] cell:1");
+		expect(text).toContain("answer = 42");
+	});
+
+	it("returns a metadata notice for unrenderable binary bytes", async () => {
+		const binaryBytes = new Uint8Array([0, 1, 2, 3, 255, 254, 253, 0, 7, 8]);
+		const url = uniqueUrl("payload", ".bin");
+		stubUrlBytes(binaryBytes, "application/octet-stream");
+
+		const tool = new ReadTool(makeSession(testDir));
+		const result = await tool.execute("read-url-binary", { path: url });
+		const text = textOutput(result);
+
+		expect(result.details?.method).toBe("binary");
+		expect(text).toContain("Method: binary");
+		expect(text).toContain("[Binary content: application/octet-stream");
+		expect(text).not.toContain("\u0000");
+		expect(text).not.toContain("�");
+	});
+
+	it("leaves valid UTF-8 octet-stream payloads on the text path", async () => {
+		const url = uniqueUrl("plain", ".txt");
+		const fetchBinarySpy = stubUrlText("plain UTF-8 text\nsecond line", "application/octet-stream");
+
+		const tool = new ReadTool(makeSession(testDir));
+		const result = await tool.execute("read-url-text-octet", { path: url });
+		const text = textOutput(result);
+
+		expect(result.details?.method).toBe("raw");
+		expect(text).toContain("plain UTF-8 text");
+		expect(text).toContain("second line");
+		expect(fetchBinarySpy).not.toHaveBeenCalled();
+	});
+});

From 5ff5d966bab0c702072badc43f04f70ac8c8f673 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:56:09 +0200
Subject: [PATCH 110/181] test(coding-agent/session): added tests for
 SessionManager fork behavior and controller fixtures

- Added a new SessionManager.forkFrom test confirming terminal breadcrumb suppression while cloning source session history under a new parent session.
- Updated TanCommandController test fixtures with required assistant message API, provider, model, and completion metadata.
---
 .../tan-command-controller.test.ts            |  9 +-
 .../test/session/session-manager-fork.test.ts | 87 +++++++++++++++++++
 2 files changed, 94 insertions(+), 2 deletions(-)
 create mode 100644 packages/coding-agent/test/session/session-manager-fork.test.ts

diff --git a/packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts b/packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts
index c41ad482c..ee41a1887 100644
--- a/packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts
+++ b/packages/coding-agent/test/modes/controllers/tan-command-controller.test.ts
@@ -6,7 +6,7 @@ import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import { TanCommandController } from "@oh-my-pi/pi-coding-agent/modes/controllers/tan-command-controller";
 import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/types";
 import { MAIN_AGENT_ID } from "@oh-my-pi/pi-coding-agent/registry/agent-registry";
-import type { CreateAgentSessionOptions, CreateAgentSessionResult } from "@oh-my-pi/pi-coding-agent/sdk";
+import type { CreateAgentSessionResult } from "@oh-my-pi/pi-coding-agent/sdk";
 import * as sdkModule from "@oh-my-pi/pi-coding-agent/sdk";
 import { SessionManager } from "@oh-my-pi/pi-coding-agent/session/session-manager";
 import { TempDir } from "@oh-my-pi/pi-utils";
@@ -25,6 +25,9 @@ function assistantText(text: string): AssistantMessage {
 	return {
 		role: "assistant",
 		content: [{ type: "text", text }],
+		api: "anthropic-messages",
+		provider: model.provider,
+		model: model.id,
 		usage: {
 			input: 0,
 			output: 0,
@@ -33,6 +36,8 @@ function assistantText(text: string): AssistantMessage {
 			totalTokens: 0,
 			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 		},
+		stopReason: "stop",
+		timestamp: 0,
 	};
 }
 
@@ -204,7 +209,7 @@ describe("TanCommandController", () => {
 		expect(clone.abort).toHaveBeenCalled();
 		expect(clone.dispose).toHaveBeenCalled();
 		expect(createAgentSessionSpy.mock.calls[0]?.[0]).toEqual(
-			expect.objectContaining<CreateAgentSessionOptions>({
+			expect.objectContaining({
 				providerPromptCacheKey: "parent-session",
 				parentTaskPrefix: expect.stringMatching(/^Tan-/) as unknown as string,
 				agentDisplayName: "tan",
diff --git a/packages/coding-agent/test/session/session-manager-fork.test.ts b/packages/coding-agent/test/session/session-manager-fork.test.ts
new file mode 100644
index 000000000..a7cf5b5c2
--- /dev/null
+++ b/packages/coding-agent/test/session/session-manager-fork.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+	CURRENT_SESSION_VERSION,
+	type SessionHeader,
+	SessionManager,
+} from "@oh-my-pi/pi-coding-agent/session/session-manager";
+import { getTerminalId } from "@oh-my-pi/pi-tui";
+import { getAgentDir, getTerminalSessionsDir, setAgentDir, TempDir } from "@oh-my-pi/pi-utils";
+
+interface JsonlMessageEntry {
+	type: "message";
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+	message: {
+		role: "user";
+		content: string;
+		timestamp: number;
+	};
+}
+
+describe("SessionManager.forkFrom", () => {
+	it("suppresses terminal breadcrumbs while preserving source history under a new parented session", async () => {
+		using tempDir = TempDir.createSync("@omp-session-fork-");
+		const previousAgentDir = getAgentDir();
+		const previousTermSessionId = process.env.TERM_SESSION_ID;
+		setAgentDir(path.join(tempDir.path(), "agent"));
+		process.env.TERM_SESSION_ID = "omp-fork-test";
+		try {
+			const cwd = path.join(tempDir.path(), "project");
+			const sessionDir = path.join(tempDir.path(), "sessions");
+			await fs.mkdir(sessionDir, { recursive: true });
+			const sourceFile = path.join(sessionDir, "source.jsonl");
+			const timestamp = new Date().toISOString();
+			const sourceHeader: SessionHeader = {
+				type: "session",
+				version: CURRENT_SESSION_VERSION,
+				id: "source-session",
+				timestamp,
+				cwd,
+			};
+			const sourceMessage: JsonlMessageEntry = {
+				type: "message",
+				id: "message-1",
+				parentId: null,
+				timestamp,
+				message: { role: "user", content: "hello", timestamp: Date.now() },
+			};
+			const sourceText = `${JSON.stringify(sourceHeader)}\n${JSON.stringify(sourceMessage)}\n`;
+			await Bun.write(sourceFile, sourceText);
+
+			const terminalId = getTerminalId();
+			expect(terminalId).toBeString();
+			const breadcrumbFile = path.join(getTerminalSessionsDir(), terminalId ?? "missing");
+			await fs.rm(breadcrumbFile, { force: true });
+
+			const forked = await SessionManager.forkFrom(sourceFile, cwd, sessionDir, undefined, {
+				suppressBreadcrumb: true,
+			});
+			await Bun.sleep(10);
+			const cloneFile = forked.getSessionFile();
+			expect(cloneFile).toBeString();
+			if (!cloneFile) throw new Error("expected forked session file");
+
+			expect(await Bun.file(sourceFile).text()).toBe(sourceText);
+			expect(await Bun.file(breadcrumbFile).exists()).toBe(false);
+			expect(cloneFile).not.toBe(sourceFile);
+
+			const lines = (await Bun.file(cloneFile).text()).trim().split("\n");
+			const cloneHeader = JSON.parse(lines[0] ?? "{}") as SessionHeader;
+			const cloneMessage = JSON.parse(lines[1] ?? "{}") as JsonlMessageEntry;
+			expect(cloneHeader.id).not.toBe(sourceHeader.id);
+			expect(cloneHeader.parentSession).toBe(sourceHeader.id);
+			expect(cloneHeader.cwd).toBe(cwd);
+			expect(cloneMessage.message.content).toBe("hello");
+		} finally {
+			if (previousTermSessionId === undefined) {
+				delete process.env.TERM_SESSION_ID;
+			} else {
+				process.env.TERM_SESSION_ID = previousTermSessionId;
+			}
+			setAgentDir(previousAgentDir);
+		}
+	});
+});

From 793251fa2e4074ab90898286c62e6aa6ec984f11 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:56:16 +0200
Subject: [PATCH 111/181] fix(coding-agent): labeled TTSR-aborted tool
 placeholders with matched rule names

- Passed a formatted TTSR match message into the agent abort call when streaming is interrupted by TTSR rules.
- Added a `#formatTtsrAbortReason` helper to include matched rule names in the abort reason.
- Added a concurrent-session test confirming aborted tool results mention the matched TTSR rule instead of `Request was aborted`.
---
 packages/coding-agent/CHANGELOG.md            |   2 +
 .../coding-agent/src/session/agent-session.ts |   8 +-
 .../test/agent-session-concurrent.test.ts     | 106 ++++++++++++++++++
 3 files changed, 115 insertions(+), 1 deletion(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 482ae0f53..7677b33f0 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -37,6 +37,8 @@
 
 ### Fixed
 
+- Fixed TTSR stream interrupts to pass the matched rule name through the abort reason, so aborted in-flight tool placeholders say why they were stopped instead of `Request was aborted`.
+- Fixed URL reads for binary/special payloads to reuse local readers: remote archives list their root entries, SQLite databases show their table overview, notebooks render as editable cells, and unrenderable binary returns a metadata notice instead of decoded byte garbage.
 - Fixed pasted image-file paths that cannot be loaded to fall back to normal text paste with status feedback instead of disappearing.
 - Fixed tool-output file paths not being clickable OSC 8 `file://` hyperlinks in several renderers. `read` titles for plain text and image files (the common case) emitted no link at all because the renderer only linked when a `resolvedPath` was recorded — which the ordinary file/image read paths never set, keeping the absolute path only in `meta.source`; the renderer now falls back to that source path. `write` headers were never wrapped in a hyperlink and now link to the absolute path written (file, archive entry, SQLite, and conflict resolutions). `edit`/`apply_patch` headers wrapped the model-supplied (often cwd-relative) argument path, producing a root-anchored `file:///rel/path` URI; they now link the absolute `details.path` instead. Finally, `search`, `ast_grep`, and `ast_edit` produced doubled link targets (`/proj/src/src/file.ts`) for searches scoped to a subdirectory, because the renderer resolved the cwd-relative display paths against the scope directory rather than cwd — the scoped-search base is now the session cwd (with the scoped file's absolute path still seeding single-file body lines).
 - Fixed `omp dry-balance --bench` to recover from 401 token failures by re-minting the failing OAuth credential in place before switching accounts
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index 6f5404dd7..db59785f4 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -1696,7 +1696,7 @@ export class AgentSession {
 							// Abort the stream immediately — do not gate on extension callbacks
 							this.#ttsrAbortPending = true;
 							this.#ensureTtsrResumePromise();
-							this.agent.abort();
+							this.agent.abort(this.#formatTtsrAbortReason(matches));
 							// Notify extensions (fire-and-forget, does not block abort)
 							this.#emitSessionEvent({ type: "ttsr_triggered", rules: matches }).catch(() => {});
 							// Schedule retry after a short delay
@@ -2177,6 +2177,12 @@ export class AgentSession {
 		}
 	}
 
+	#formatTtsrAbortReason(rules: Rule[]): string {
+		const label = rules.length === 1 ? "rule" : "rules";
+		const ruleNames = rules.map(rule => rule.name).join(", ");
+		return `TTSR matched ${label}: ${ruleNames}`;
+	}
+
 	/** Get TTSR injection payload and clear pending injections. */
 	#getTtsrInjectionContent(): { content: string; rules: Rule[] } | undefined {
 		if (this.#pendingTtsrInjections.length === 0) return undefined;
diff --git a/packages/coding-agent/test/agent-session-concurrent.test.ts b/packages/coding-agent/test/agent-session-concurrent.test.ts
index a5298263a..9ba2bed27 100644
--- a/packages/coding-agent/test/agent-session-concurrent.test.ts
+++ b/packages/coding-agent/test/agent-session-concurrent.test.ts
@@ -749,6 +749,112 @@ describe("AgentSession TTSR resume gate", () => {
 		expect(session.isStreaming).toBe(false);
 	});
 
+	it("labels aborted tool placeholders with the TTSR rule reason", async () => {
+		collapseSchedulerSettleDelays();
+		const model = getBundledModel("anthropic", "claude-sonnet-4-5")!;
+		let streamCallCount = 0;
+
+		const ttsrManager = new TtsrManager({
+			enabled: true,
+			contextMode: "discard",
+			interruptMode: "always",
+			repeatMode: "once",
+			repeatGap: 10,
+		});
+		ttsrManager.addRule(testRule);
+
+		const toolCallContent: ToolCall = {
+			type: "toolCall",
+			id: "call_ttsr_abort_reason",
+			name: "mock_edit",
+			arguments: { snippet: "let val = result.unwrap(" },
+		};
+
+		const makeToolCallMsg = (stopReason: "toolUse" | "aborted" = "toolUse"): AssistantMessage => ({
+			role: "assistant",
+			content: [toolCallContent],
+			api: "anthropic-messages",
+			provider: "anthropic",
+			model: "mock",
+			usage: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason,
+			timestamp: Date.now(),
+		});
+
+		const agent = new Agent({
+			getApiKey: () => "test-key",
+			initialState: { model, systemPrompt: ["Test"], tools: [] },
+			streamFn: (_model, _context, options) => {
+				streamCallCount++;
+				const stream = new AssistantMessageEventStream();
+				const signal = options?.signal;
+				if (streamCallCount === 1) {
+					queueMicrotask(() => {
+						const partial = makeToolCallMsg();
+						if (signal) {
+							signal.addEventListener(
+								"abort",
+								() => {
+									stream.push({
+										type: "error",
+										reason: "aborted",
+										error: makeToolCallMsg("aborted"),
+									});
+								},
+								{ once: true },
+							);
+						}
+						stream.push({ type: "start", partial });
+						stream.push({ type: "toolcall_start", contentIndex: 0, partial });
+						stream.push({
+							type: "toolcall_delta",
+							contentIndex: 0,
+							delta: 'let val = result.unwrap("oops")',
+							partial,
+						});
+					});
+				} else {
+					pushContinuationStream(stream, () => {});
+				}
+				return stream;
+			},
+		});
+
+		const sessionManager = SessionManager.inMemory();
+		const settings = Settings.isolated();
+		const authStorage = await AuthStorage.create(path.join(tempDir, "testauth-abort-reason.db"));
+		authStorages.push(authStorage);
+		const modelRegistry = new ModelRegistry(authStorage, path.join(tempDir, "models.yml"));
+		authStorage.setRuntimeApiKey("anthropic", "test-key");
+		session = new AgentSession({ agent, sessionManager, settings, modelRegistry, ttsrManager });
+
+		await session.prompt("Write some Rust code");
+
+		const toolResult = sessionManager
+			.getEntries()
+			.find(
+				entry =>
+					entry.type === "message" &&
+					entry.message.role === "toolResult" &&
+					entry.message.toolCallId === toolCallContent.id,
+			);
+		expect(toolResult?.type).toBe("message");
+		const text =
+			toolResult?.type === "message" && toolResult.message.role === "toolResult"
+				? (toolResult.message.content.find((part): part is { type: "text"; text: string } => part.type === "text")
+						?.text ?? "")
+				: "";
+		expect(text).toContain("Tool execution was aborted: TTSR matched rule: no-unwrap");
+		expect(text).not.toContain("Request was aborted");
+	});
+
 	it("relativizes the rule file path in the TTSR interrupt injection (no absolute leak)", async () => {
 		collapseSchedulerSettleDelays();
 		const model = getBundledModel("anthropic", "claude-sonnet-4-5")!;

From 9d245eea60078146b79ccb699d351cd997965430 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 06:59:01 +0200
Subject: [PATCH 112/181] fix(coding-agent): adjusted edit output padding to
 remove inherited left gutter space

- Added a configurable `contentPaddingLeft` option to `renderOutputBlock` with normalized defaults.
- Updated edit renderer output blocks to disable inherited left padding and align inner-width wrapping.
- Added coverage for completed edit gutter rendering to confirm no leading space and correct frame width.
---
 packages/coding-agent/src/edit/renderer.ts    |  9 +++++---
 packages/coding-agent/src/tui/output-block.ts | 13 +++++++++--
 .../test/tools/edit-renderer.test.ts          | 23 ++++++++++++++++++-
 3 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/packages/coding-agent/src/edit/renderer.ts b/packages/coding-agent/src/edit/renderer.ts
index 0ad9cb82d..6bedb5947 100644
--- a/packages/coding-agent/src/edit/renderer.ts
+++ b/packages/coding-agent/src/edit/renderer.ts
@@ -475,7 +475,7 @@ export const editToolRenderer = {
 			if (fileCount > 1) header += uiTheme.fg("dim", ` (+${fileCount - 1} more)`);
 			let body = getCallPreview(editArgs, rawPath, uiTheme, renderContext, options.expanded);
 			if (applyPatchSummary?.error) {
-				body += `\n${uiTheme.fg("error", truncateToWidth(replaceTabs(applyPatchSummary.error, rawPath), Math.max(1, width - 3)))}`;
+				body += `\n${uiTheme.fg("error", truncateToWidth(replaceTabs(applyPatchSummary.error, rawPath), Math.max(1, width - 2)))}`;
 			}
 			const bodyLines = body ? body.split("\n") : [];
 			while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
@@ -485,6 +485,7 @@ export const editToolRenderer = {
 				state: applyPatchSummary?.error ? "error" : "pending",
 				borderColor: applyPatchSummary?.error ? "error" : "borderMuted",
 				width,
+				contentPaddingLeft: 0,
 			};
 		});
 	},
@@ -572,8 +573,9 @@ function renderSingleFileResult(
 		}
 
 		// Diff lines self-wrap with a continuation gutter; pre-wrap to the frame's
-		// inner width so renderOutputBlock's generic wrap is a no-op.
-		const innerWidth = Math.max(1, width - 3);
+		// inner width so renderOutputBlock's generic wrap is a no-op. Edit frames
+		// use a flush left border because code-frame gutters already provide padding.
+		const innerWidth = Math.max(1, width - 2);
 		const bodyLines = body.length > 0 ? body.split("\n").flatMap(line => wrapEditRendererLine(line, innerWidth)) : [];
 		while (bodyLines.length > 0 && bodyLines[0].trim() === "") bodyLines.shift();
 
@@ -583,6 +585,7 @@ function renderSingleFileResult(
 			state: isError ? "error" : options.isPartial ? "pending" : "success",
 			borderColor: isError ? "error" : "borderMuted",
 			width,
+			contentPaddingLeft: 0,
 		};
 	});
 }
diff --git a/packages/coding-agent/src/tui/output-block.ts b/packages/coding-agent/src/tui/output-block.ts
index 5d1c1f0a3..24cba9eb5 100644
--- a/packages/coding-agent/src/tui/output-block.ts
+++ b/packages/coding-agent/src/tui/output-block.ts
@@ -16,6 +16,7 @@ export interface OutputBlockOptions {
 	sections?: Array<{ label?: string; lines: string[] }>;
 	width: number;
 	applyBg?: boolean;
+	contentPaddingLeft?: number;
 	/** Animate the border with a sweeping dark segment (pending/running state). */
 	animate?: boolean;
 	/** Override the state-derived border color. Used for muted "legacy" tool
@@ -95,6 +96,11 @@ type BlockRow =
 	| { kind: "content"; inner: string }
 	| { kind: "sixel"; raw: string };
 
+function normalizeContentPaddingLeft(value: number | undefined): number {
+	if (value === undefined || !Number.isFinite(value)) return 1;
+	return Math.max(0, Math.floor(value));
+}
+
 export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[] {
 	const { header, headerMeta, state, sections = [], width, applyBg = true } = options;
 	const h = theme.boxSharp.horizontal;
@@ -125,7 +131,9 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 		};
 	})();
 
-	const contentWidth = Math.max(0, lineWidth - visibleWidth(`${v} `) - visibleWidth(v));
+	const contentPaddingLeft = normalizeContentPaddingLeft(options.contentPaddingLeft);
+	const contentWidth = Math.max(0, lineWidth - visibleWidth(v) - contentPaddingLeft - visibleWidth(v));
+	const contentLeftPadding = contentPaddingLeft > 0 ? padding(contentPaddingLeft) : "";
 
 	// ── Layout pass: collect row descriptors so the border perimeter length is
 	// known before the moving segment is positioned. ──
@@ -234,7 +242,7 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 		return `${leftStr}${fillStr}${rightStr}`;
 	};
 
-	const renderContent = (inner: string): string => `${border(`${v} `)}${inner}${border(v)}`;
+	const renderContent = (inner: string): string => `${border(v)}${contentLeftPadding}${inner}${border(v)}`;
 
 	const lines: string[] = [];
 	for (let r = 0; r < H; r++) {
@@ -278,6 +286,7 @@ export class CachedOutputBlock {
 	#buildKey(options: OutputBlockOptions): bigint {
 		const h = new Hasher();
 		h.u32(options.width);
+		h.u32(normalizeContentPaddingLeft(options.contentPaddingLeft));
 		h.optional(options.header);
 		h.optional(options.headerMeta);
 		h.optional(options.state);
diff --git a/packages/coding-agent/test/tools/edit-renderer.test.ts b/packages/coding-agent/test/tools/edit-renderer.test.ts
index 20370c582..01e8abd97 100644
--- a/packages/coding-agent/test/tools/edit-renderer.test.ts
+++ b/packages/coding-agent/test/tools/edit-renderer.test.ts
@@ -8,7 +8,7 @@ import { resetSettingsForTest, Settings } from "@oh-my-pi/pi-coding-agent/config
 import { editToolRenderer } from "@oh-my-pi/pi-coding-agent/edit/renderer";
 import { ToolExecutionComponent } from "@oh-my-pi/pi-coding-agent/modes/components/tool-execution";
 import * as themeModule from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
-import { Text, type TUI } from "@oh-my-pi/pi-tui";
+import { Text, type TUI, visibleWidth } from "@oh-my-pi/pi-tui";
 
 beforeAll(async () => {
 	resetSettingsForTest();
@@ -329,4 +329,25 @@ describe("editToolRenderer", () => {
 		expect(lines[1]).toContain("115│ ctx");
 		expect(lines.filter(line => line.includes("hunk"))).toHaveLength(1);
 	});
+
+	it("renders completed edit gutters without inherited frame padding", async () => {
+		const uiTheme = await getUiTheme();
+		const component = editToolRenderer.renderResult(
+			{
+				content: [{ type: "text", text: "Updated demo.ts" }],
+				details: {
+					diff: "+1│const renamedIdentifier = computeValueFromSomeVeryLongInputName();",
+					op: "update",
+				},
+			},
+			{ expanded: false, isPartial: false, renderContext: { editMode: "hashline" } },
+			uiTheme,
+			{ file_path: "demo.ts" },
+		);
+
+		const lines = component.render(48).map(line => Bun.stripANSI(line));
+		expect(lines.every(line => visibleWidth(line) === 48)).toBe(true);
+		expect(lines[1]).toStartWith("│+1│");
+		expect(lines[1]).not.toStartWith("│ +1│");
+	});
 });

From ddd8c86209a362efbe58423c8f6f16be36885947 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:07:44 +0200
Subject: [PATCH 113/181] ux(coding-agent): added separator support for
 unlabeled output sections

- Extended `OutputBlock` section metadata with an optional `separator` flag and included it in cache hashing.
- Updated output block rendering to emit an unlabeled section divider when the separator flag is enabled.
- Marked task and result render paths to request separators for non-context content sections to improve output clarity.
---
 packages/coding-agent/src/task/render.ts          | 14 ++++++++------
 packages/coding-agent/src/tui/output-block.ts     | 15 +++++++++++++--
 .../coding-agent/test/task/render-call.test.ts    |  7 ++++---
 3 files changed, 25 insertions(+), 11 deletions(-)

diff --git a/packages/coding-agent/src/task/render.ts b/packages/coding-agent/src/task/render.ts
index 6cbb357b9..e5e20373e 100644
--- a/packages/coding-agent/src/task/render.ts
+++ b/packages/coding-agent/src/task/render.ts
@@ -560,8 +560,7 @@ export function renderCall(
 	const showIsolated = "isolated" in args && args.isolated === true;
 	const header = renderStatusLine({ icon: "pending", title: "Task", description: args.agent }, theme);
 	return framedBlock(theme, width => {
-		const taskCount = args.tasks?.length ?? 0;
-		const sections: Array<{ label?: string; lines: string[] }> = [];
+		const sections: Array<{ label?: string; lines: string[]; separator?: boolean }> = [];
 
 		const contextSection = buildContextSection(args, theme);
 		if (contextSection) sections.push(contextSection);
@@ -572,7 +571,7 @@ export function renderCall(
 		// section here would just repeat the count the result frame already shows.
 		if (!options.renderContext?.hasResult) {
 			sections.push({
-				label: `Tasks (${taskCount})`,
+				separator: true,
 				lines: renderTaskItemLines(args.tasks, options.expanded, theme),
 			});
 		}
@@ -1059,7 +1058,7 @@ export function renderResult(
 			header,
 			sections: [
 				...(contextSection ? [contextSection] : []),
-				...(text ? [{ lines: [theme.fg("dim", truncateToWidth(text, width))] }] : []),
+				...(text ? [{ separator: true, lines: [theme.fg("dim", truncateToWidth(text, width))] }] : []),
 			],
 			state: "success",
 			borderColor: "borderMuted",
@@ -1126,7 +1125,7 @@ export function renderResult(
 				header,
 				sections: [
 					...(contextSection ? [contextSection] : []),
-					{ lines: [theme.fg("dim", truncateToWidth(text, width))] },
+					{ separator: true, lines: [theme.fg("dim", truncateToWidth(text, width))] },
 				],
 				state,
 				borderColor,
@@ -1154,7 +1153,10 @@ export function renderResult(
 		while (lines.length > 0 && lines[0].trim() === "") lines.shift();
 		return {
 			header,
-			sections: [...(contextSection ? [contextSection] : []), ...(lines.length > 0 ? [{ lines }] : [])],
+			sections: [
+				...(contextSection ? [contextSection] : []),
+				...(lines.length > 0 ? [{ separator: true, lines }] : []),
+			],
 			state,
 			borderColor,
 			width,
diff --git a/packages/coding-agent/src/tui/output-block.ts b/packages/coding-agent/src/tui/output-block.ts
index 24cba9eb5..848d92969 100644
--- a/packages/coding-agent/src/tui/output-block.ts
+++ b/packages/coding-agent/src/tui/output-block.ts
@@ -13,7 +13,7 @@ export interface OutputBlockOptions {
 	header?: string;
 	headerMeta?: string;
 	state?: State;
-	sections?: Array<{ label?: string; lines: string[] }>;
+	sections?: Array<{ label?: string; lines: string[]; separator?: boolean }>;
 	width: number;
 	applyBg?: boolean;
 	contentPaddingLeft?: number;
@@ -147,7 +147,11 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 	});
 
 	const normalizedSections = sections.length > 0 ? sections : [{ lines: [] as string[] }];
-	for (const section of normalizedSections) {
+	for (let sectionIndex = 0; sectionIndex < normalizedSections.length; sectionIndex++) {
+		const section = normalizedSections[sectionIndex]!;
+		// A labeled section always draws its titled separator bar. A label-less
+		// section can still request a plain divider via `separator`, but only
+		// between sections — leading with one would just double the header bar.
 		if (section.label) {
 			rows.push({
 				kind: "bar",
@@ -155,6 +159,12 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 				rightChar: theme.boxSharp.teeLeft,
 				label: section.label,
 			});
+		} else if (section.separator && sectionIndex > 0) {
+			rows.push({
+				kind: "bar",
+				leftChar: theme.boxSharp.teeRight,
+				rightChar: theme.boxSharp.teeLeft,
+			});
 		}
 		const allLines = section.lines.flatMap(l => l.split("\n"));
 		const sixelLineMask = TERMINAL.imageProtocol === ImageProtocol.Sixel ? getSixelLineMask(allLines) : undefined;
@@ -297,6 +307,7 @@ export class CachedOutputBlock {
 		if (options.sections) {
 			for (const s of options.sections) {
 				h.optional(s.label);
+				h.bool(s.separator ?? false);
 				for (const line of s.lines) {
 					h.str(line);
 				}
diff --git a/packages/coding-agent/test/task/render-call.test.ts b/packages/coding-agent/test/task/render-call.test.ts
index c7652a5df..7a83ddf2f 100644
--- a/packages/coding-agent/test/task/render-call.test.ts
+++ b/packages/coding-agent/test/task/render-call.test.ts
@@ -41,8 +41,9 @@ describe("task renderer: streaming call preview", () => {
 		expect(out).toContain("Audit the auth module");
 		expect(out).toContain("ReviewDb");
 		expect(out).toContain("Audit the db layer");
-		// Count is kept as a compact header, but the old flat "N agents" line is gone.
-		expect(out).toContain("Tasks (2)");
+		// The per-task list stands on its own — neither the redundant "Tasks (N)"
+		// section label nor the old flat "N agents" line is drawn.
+		expect(out).not.toContain("Tasks (");
 		expect(out).not.toContain("2 agents");
 	});
 
@@ -61,7 +62,7 @@ describe("task renderer: streaming call preview", () => {
 		expect(out).toContain("Second");
 		// Missing-id slot falls back to a positional placeholder rather than crashing.
 		expect(out).toContain("#3");
-		expect(out).toContain("Tasks (3)");
+		expect(out).not.toContain("Tasks (");
 	});
 
 	it("caps the collapsed list and reports the overflow as agents", () => {

From 0f043d4c29e3dc2be3f6540016328fc77580d94c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:16:13 +0200
Subject: [PATCH 114/181] fix(coding-agent): preserved approved plan paths
 during plan apply resolution

- Replaced approved-plan renaming with `resolveApprovedPlan` resolution and state/slug lookup.
- Updated ACP and interactive apply flows to propagate canonical `planFilePath` instead of renamed paths.
- Added local plan fallback lookup by mtime for unresolved slugs after plan approval.
- Restricted plan-mode writes to `local://` plan artifacts and simplified path handling.
---
 packages/coding-agent/CHANGELOG.md            |   4 +-
 .../coding-agent/src/modes/acp/acp-agent.ts   |  59 +++++----
 .../src/modes/interactive-mode.ts             |  66 +++++-----
 .../src/plan-mode/approved-plan.ts            | 115 +++++++++++-------
 .../src/plan-mode/plan-protection.ts          |   8 +-
 .../src/prompts/system/plan-mode-active.md    |  10 +-
 .../src/prompts/system/plan-mode-approved.md  |   2 +-
 .../coding-agent/src/tools/plan-mode-guard.ts |  60 ++++-----
 packages/coding-agent/test/acp-agent.test.ts  |  17 +--
 .../test/interactive-mode-plan-review.test.ts |  51 ++------
 .../test/plan-mode/approved-plan.test.ts      |  90 ++++++++------
 .../test/tools/plan-mode-guard-local.test.ts  |  96 ++++++---------
 12 files changed, 278 insertions(+), 300 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 7677b33f0..dd972f99f 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,7 +1,6 @@
 # Changelog
 
 ## [Unreleased]
-
 ### Added
 
 - Added `/tan <work>` slash command to fork the current conversation into a background agent so tangential work can continue asynchronously while your main session stays active
@@ -18,6 +17,8 @@
 
 ### Changed
 
+- Changed plan-mode approval to keep the drafted `local://<slug>-plan.md` file at its original name as the canonical plan path, so approved plans are no longer renamed when leaving plan mode
+- Changed plan-mode write enforcement so only `local://` artifact files are writable during planning, blocking working-tree edits and allowing scratch or draft plan files in the local artifact area
 - Changed the `todo` tool result renderer to stop redrawing every phase's full task list on each update: when a multi-phase list is rendered collapsed (the default, not manually expanded), only phases the latest update touched — the phase holding the in_progress task, any phase with a just-completed task, and phases named by the ops that ran (`init` counts as touching all) — render their tasks; untouched phases collapse to a one-line `N. Name  done/total` summary. When call args are unavailable (e.g. transcript rebuilds) it falls back to the in_progress/completed-transition signals, and the manual expand toggle still shows every task. Also dropped the blank separator line previously inserted between phases.
 - Changed non-agent API operations (title and commit-message generation, image generation, web search, eval `llm()`, auto-thinking classifier, memory consolidation) to use session-aware API key resolution with auth retries via `registry.resolver()` / `authStorage.resolver()`, refreshing the active credential before rotating to another account
 - Changed image generation to wrap every provider fetch branch in `withAuth`, so 401 / usage-limit errors trigger credential force-refresh and rotation for authStorage-backed providers (OpenAI-hosted, antigravity, xai-oauth) while env-only providers (openrouter, gemini) stay single-attempt
@@ -37,6 +38,7 @@
 
 ### Fixed
 
+- Fixed plan approval resolution so `resolve` with `action: "apply"` can still find the plan file when `extra.title` is missing or stale by falling back to the current plan path and most-recent local plan artifacts
 - Fixed TTSR stream interrupts to pass the matched rule name through the abort reason, so aborted in-flight tool placeholders say why they were stopped instead of `Request was aborted`.
 - Fixed URL reads for binary/special payloads to reuse local readers: remote archives list their root entries, SQLite databases show their table overview, notebooks render as editable cells, and unrenderable binary returns a metadata notice instead of decoded byte garbage.
 - Fixed pasted image-file paths that cannot be loaded to fall back to normal text paste with status feedback instead of disappearing.
diff --git a/packages/coding-agent/src/modes/acp/acp-agent.ts b/packages/coding-agent/src/modes/acp/acp-agent.ts
index 4bd991d51..efa8bc99c 100644
--- a/packages/coding-agent/src/modes/acp/acp-agent.ts
+++ b/packages/coding-agent/src/modes/acp/acp-agent.ts
@@ -1,3 +1,4 @@
+import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import {
 	type Agent,
@@ -62,7 +63,7 @@ import { MCPManager } from "../../mcp/manager";
 import type { MCPServerConfig } from "../../mcp/types";
 import { loadAllExtensions } from "../../modes/components/extensions/state-manager";
 import { theme } from "../../modes/theme/theme";
-import { type PlanApprovalDetails, renameApprovedPlanFile, resolvePlanTitle } from "../../plan-mode/approved-plan";
+import { type PlanApprovalDetails, resolveApprovedPlan } from "../../plan-mode/approved-plan";
 import type { AgentSession, AgentSessionEvent } from "../../session/agent-session";
 import { isSilentAbort, SKILL_PROMPT_MESSAGE_TYPE } from "../../session/messages";
 import {
@@ -1425,24 +1426,16 @@ export class AcpAgent implements Agent {
 				if (!state?.enabled) {
 					throw new ToolError("Plan mode is not active.");
 				}
-				const planFilePath = state.planFilePath;
-				const planContent = await this.#readAcpPlanFile(session, planFilePath);
-				if (planContent === null) {
-					throw new ToolError(
-						`Plan file not found at ${planFilePath}. Write the finalized plan to ${planFilePath} before requesting approval.`,
-					);
-				}
-				const normalized = resolvePlanTitle({
+				const { planFilePath, planContent, title } = await resolveApprovedPlan({
 					suppliedTitle: extra?.title,
-					planContent,
-					planFilePath,
+					statePlanFilePath: state.planFilePath,
+					readPlan: url => this.#readAcpPlanFile(session, url),
+					listPlanFiles: () => this.#listAcpLocalPlanFiles(session),
 				});
-				const finalPlanFilePath = `local://${normalized.fileName}`;
-				const approved = await this.#requestAcpPlanApprovalChoice(session.sessionId, normalized.title, planContent);
+				const approved = await this.#requestAcpPlanApprovalChoice(session.sessionId, title, planContent);
 				const details: PlanApprovalDetails = {
 					planFilePath,
-					finalPlanFilePath,
-					title: normalized.title,
+					title,
 					planExists: true,
 				};
 				if (!approved) {
@@ -1458,16 +1451,10 @@ export class AcpAgent implements Agent {
 						details,
 					};
 				}
-				// Approved. Rename plan to its titled filename, set the plan
-				// reference so the next turn injects the plan content as
-				// context, then exit plan mode so the agent regains full tools.
-				await renameApprovedPlanFile({
-					planFilePath,
-					finalPlanFilePath,
-					getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
-					getSessionId: () => session.sessionManager.getSessionId(),
-				});
-				session.setPlanReferencePath(finalPlanFilePath);
+				// Approved. Set the plan reference so the next turn injects the plan
+				// content as context (the file keeps its agent-chosen name — no
+				// rename), then exit plan mode so the agent regains full tools.
+				session.setPlanReferencePath(planFilePath);
 				session.setStandingResolveHandler?.(null);
 				session.setPlanModeState(undefined);
 				try {
@@ -1486,7 +1473,7 @@ export class AcpAgent implements Agent {
 					content: [
 						{
 							type: "text" as const,
-							text: `Plan approved at ${finalPlanFilePath}. Plan mode exited; proceed with the implementation.`,
+							text: `Plan approved at ${planFilePath}. Plan mode exited; proceed with the implementation.`,
 						},
 					],
 					details,
@@ -1518,6 +1505,26 @@ export class AcpAgent implements Agent {
 		}
 	}
 
+	/** `local://` URLs of plan files in the session-local root, newest first —
+	 *  the `resolveApprovedPlan` fallback for a dropped `extra.title`. */
+	async #listAcpLocalPlanFiles(session: AgentSession): Promise<string[]> {
+		const localRoot = this.#resolveAcpPlanFilePath(session, "local://");
+		try {
+			const entries = await fs.readdir(localRoot, { withFileTypes: true });
+			const plans = await Promise.all(
+				entries
+					.filter(entry => entry.isFile() && /plan\.md$/i.test(entry.name))
+					.map(async entry => {
+						const stat = await fs.stat(path.join(localRoot, entry.name)).catch(() => null);
+						return { url: `local://${entry.name}`, mtime: stat?.mtimeMs ?? 0 };
+					}),
+			);
+			return plans.sort((a, b) => b.mtime - a.mtime).map(plan => plan.url);
+		} catch {
+			return [];
+		}
+	}
+
 	/**
 	 * Ask the ACP client to confirm plan approval. Returns `true` only on an
 	 * explicit `APPROVE_OPTION` selection. Refine, dismissal (`undefined`), or
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index a441372d5..f5f96f342 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -65,12 +65,7 @@ import { BUILTIN_SLASH_COMMANDS, loadSlashCommands } from "../extensibility/slas
 import type { Goal, GoalModeState } from "../goals/state";
 import { resolveLocalUrlToPath } from "../internal-urls";
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "../lsp/startup-events";
-import {
-	humanizePlanTitle,
-	type PlanApprovalDetails,
-	renameApprovedPlanFile,
-	resolvePlanTitle,
-} from "../plan-mode/approved-plan";
+import { humanizePlanTitle, type PlanApprovalDetails, resolveApprovedPlan } from "../plan-mode/approved-plan";
 import planModeApprovedPrompt from "../prompts/system/plan-mode-approved.md" with { type: "text" };
 import planModeCompactInstructionsPrompt from "../prompts/system/plan-mode-compact-instructions.md" with {
 	type: "text",
@@ -1528,22 +1523,15 @@ export class InteractiveMode implements InteractiveModeContext {
 				if (!state?.enabled) {
 					throw new ToolError("Plan mode is not active.");
 				}
-				const planFilePath = state.planFilePath;
-				const planContent = await this.#readPlanFile(planFilePath);
-				if (planContent === null) {
-					throw new ToolError(
-						`Plan file not found at ${planFilePath}. Write the finalized plan to ${planFilePath} before requesting approval.`,
-					);
-				}
-				const normalized = resolvePlanTitle({
+				const { planFilePath, title } = await resolveApprovedPlan({
 					suppliedTitle: extra?.title,
-					planContent,
-					planFilePath,
+					statePlanFilePath: state.planFilePath,
+					readPlan: url => this.#readPlanFile(url),
+					listPlanFiles: () => this.#listLocalPlanFiles(),
 				});
 				const details: PlanApprovalDetails = {
 					planFilePath,
-					finalPlanFilePath: `local://${normalized.fileName}`,
-					title: normalized.title,
+					title,
 					planExists: true,
 				};
 				return {
@@ -1683,6 +1671,27 @@ export class InteractiveMode implements InteractiveModeContext {
 		}
 	}
 
+	/** `local://` URLs of plan files in the session-local root, newest first.
+	 *  A fallback for `resolveApprovedPlan` when the agent dropped `extra.title`,
+	 *  so the plan it wrote is still found by scanning recent `*-plan.md` files. */
+	async #listLocalPlanFiles(): Promise<string[]> {
+		const localRoot = this.#resolvePlanFilePath("local://");
+		try {
+			const entries = await fs.readdir(localRoot, { withFileTypes: true });
+			const plans = await Promise.all(
+				entries
+					.filter(entry => entry.isFile() && /plan\.md$/i.test(entry.name))
+					.map(async name => {
+						const stat = await fs.stat(path.join(localRoot, name.name)).catch(() => null);
+						return { url: `local://${name.name}`, mtime: stat?.mtimeMs ?? 0 };
+					}),
+			);
+			return plans.sort((a, b) => b.mtime - a.mtime).map(plan => plan.url);
+		} catch {
+			return [];
+		}
+	}
+
 	showPlanReview(
 		planContent: string,
 		title: string,
@@ -1854,19 +1863,12 @@ export class InteractiveMode implements InteractiveModeContext {
 		planContent: string,
 		options: {
 			planFilePath: string;
-			finalPlanFilePath: string;
 			title: string;
 			preserveContext?: boolean;
 			compactBeforeExecute?: boolean;
 			executionModel?: ResolvedRoleModel;
 		},
 	): Promise<void> {
-		await renameApprovedPlanFile({
-			planFilePath: options.planFilePath,
-			finalPlanFilePath: options.finalPlanFilePath,
-			getArtifactsDir: () => this.sessionManager.getArtifactsDir(),
-			getSessionId: () => this.sessionManager.getSessionId(),
-		});
 		const previousTools = this.#planModePreviousTools ?? this.session.getActiveToolNames();
 
 		// Mark the pending abort caused by the plan-mode → compaction transition as
@@ -1885,8 +1887,8 @@ export class InteractiveMode implements InteractiveModeContext {
 			if (!options.preserveContext) {
 				await this.handleClearCommand();
 				// The new session has a fresh local:// root — persist the approved plan there
-				// so `local://<title>.md` resolves correctly in the execution session.
-				const newLocalPath = resolveLocalUrlToPath(options.finalPlanFilePath, {
+				// so `local://<slug>-plan.md` resolves correctly in the execution session.
+				const newLocalPath = resolveLocalUrlToPath(options.planFilePath, {
 					getArtifactsDir: () => this.sessionManager.getArtifactsDir(),
 					getSessionId: () => this.sessionManager.getSessionId(),
 				});
@@ -1900,7 +1902,7 @@ export class InteractiveMode implements InteractiveModeContext {
 				// Cancellation skips the synthetic-prompt dispatch (operator's explicit
 				// abort is honored); failure proceeds best-effort — approval intent stands.
 				const compactionPrompt = prompt.render(planModeCompactInstructionsPrompt, {
-					planFilePath: options.finalPlanFilePath,
+					planFilePath: options.planFilePath,
 				});
 				// Pin the plan reference path BEFORE compaction so any user messages
 				// queued during the compaction await (which `handleCompactCommand`
@@ -1908,7 +1910,7 @@ export class InteractiveMode implements InteractiveModeContext {
 				// approved plan in `#buildPlanReferenceMessage`. Reassignment after
 				// the try/finally is idempotent and kept for the !compactBeforeExecute
 				// branch.
-				this.session.setPlanReferencePath(options.finalPlanFilePath);
+				this.session.setPlanReferencePath(options.planFilePath);
 				compactOutcome = await this.handleCompactCommand(compactionPrompt);
 			}
 		} finally {
@@ -1924,7 +1926,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		if (previousTools.length > 0) {
 			await this.session.setActiveToolsByName(previousTools);
 		}
-		this.session.setPlanReferencePath(options.finalPlanFilePath);
+		this.session.setPlanReferencePath(options.planFilePath);
 
 		if (compactOutcome === "cancelled") {
 			// Explicit abort: honor it. `executeCompaction` already surfaced
@@ -1961,7 +1963,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.session.markPlanReferenceSent();
 		const planModePrompt = prompt.render(planModeApprovedPrompt, {
 			planContent,
-			finalPlanFilePath: options.finalPlanFilePath,
+			planFilePath: options.planFilePath,
 			contextPreserved: options.preserveContext === true,
 		});
 		await this.session.prompt(planModePrompt, { synthetic: true });
@@ -2309,7 +2311,6 @@ export class InteractiveMode implements InteractiveModeContext {
 		);
 
 		if (choice === "Approve and execute" || choice === "Approve and compact context" || choice === keepContextLabel) {
-			const finalPlanFilePath = details.finalPlanFilePath || planFilePath;
 			try {
 				// Prefer in-overlay edits (already in memory) over a disk re-read; the
 				// `onPlanEdited` write is fire-and-forget, so reading the file here could
@@ -2332,7 +2333,6 @@ export class InteractiveMode implements InteractiveModeContext {
 					cycle && selectedTierIndex !== cycle.currentIndex ? cycle.models[selectedTierIndex] : undefined;
 				await this.#approvePlan(latestPlanContent, {
 					planFilePath,
-					finalPlanFilePath,
 					title: details.title,
 					preserveContext: choice !== "Approve and execute",
 					compactBeforeExecute: choice === "Approve and compact context",
diff --git a/packages/coding-agent/src/plan-mode/approved-plan.ts b/packages/coding-agent/src/plan-mode/approved-plan.ts
index dc259e8dc..120fd4212 100644
--- a/packages/coding-agent/src/plan-mode/approved-plan.ts
+++ b/packages/coding-agent/src/plan-mode/approved-plan.ts
@@ -1,15 +1,12 @@
-import * as fs from "node:fs/promises";
-import { isEnoent } from "@oh-my-pi/pi-utils";
-import { resolveLocalUrlToPath } from "../internal-urls";
-import { normalizeLocalScheme } from "../tools/path-utils";
 import { ToolError } from "../tools/tool-errors";
 
 /** Shape forwarded from the plan-mode resolve handler to InteractiveMode's
  *  approval popup. Populated by the standing handler that the resolve tool
- *  dispatches to when the agent submits `resolve { action: "apply" }`. */
+ *  dispatches to when the agent submits `resolve { action: "apply" }`.
+ *  `planFilePath` is the agent-chosen `local://<slug>-plan.md` artifact — it is
+ *  never renamed on approval, so links to it stay valid for the session. */
 export interface PlanApprovalDetails {
 	planFilePath: string;
-	finalPlanFilePath: string;
 	title: string;
 	planExists: boolean;
 }
@@ -110,54 +107,80 @@ export function humanizePlanTitle(title: string): string {
 	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
 }
 
-interface RenameApprovedPlanFileOptions {
+/** The `local://` URL a plan slug maps to. The agent writes the plan here and
+ *  passes the slug to `resolve`; the file is never renamed, so this URL — and
+ *  any hyperlink to it — stays valid for the life of the session. */
+export function planFileUrlForSlug(slug: string): string {
+	return `local://${slug}-plan.md`;
+}
+
+/** Derive a `<slug>` from an agent-supplied `extra.title`, or `undefined` when
+ *  the title is missing/non-string/unsanitizable. A trailing `-plan` is stripped
+ *  so a supplied "auth-plan" maps to `auth-plan.md`, not `auth-plan-plan.md`. */
+function planSlugFromSupplied(suppliedTitle: unknown): string | undefined {
+	if (typeof suppliedTitle !== "string" || !suppliedTitle.trim()) return undefined;
+	try {
+		const { title } = normalizePlanTitle(suppliedTitle);
+		const slug = title.replace(/-plan$/i, "");
+		return slug || title;
+	} catch {
+		return undefined;
+	}
+}
+
+export interface ResolveApprovedPlanInput {
+	/** The agent's `extra.title` from the `resolve` call, if any. */
+	suppliedTitle?: unknown;
+	/** The plan path recorded in plan-mode state (the entry default or a prior plan). */
+	statePlanFilePath: string;
+	/** Read a plan `local://` URL, returning null when the file does not exist. */
+	readPlan: (planUrl: string) => Promise<string | null>;
+	/** Optional fallback: list candidate plan `local://` URLs (newest first) so a
+	 *  plan whose name can't be reconstructed (e.g. a dropped `extra.title`) is
+	 *  still found. */
+	listPlanFiles?: () => Promise<string[]>;
+}
+
+export interface ResolvedApprovedPlan {
 	planFilePath: string;
-	finalPlanFilePath: string;
-	getArtifactsDir: () => string | null;
-	getSessionId: () => string | null;
+	planContent: string;
+	title: string;
 }
 
-function assertLocalUrl(path: string, label: "source" | "destination"): void {
-	if (!path.startsWith("local:/") && !path.startsWith("local://")) {
-		throw new Error(`Approved plan ${label} path must use local: scheme with / or // (received ${path}).`);
-	}
-}
-
-export async function renameApprovedPlanFile(options: RenameApprovedPlanFileOptions): Promise<void> {
-	const { planFilePath, finalPlanFilePath, getArtifactsDir, getSessionId } = options;
-	assertLocalUrl(planFilePath, "source");
-	assertLocalUrl(finalPlanFilePath, "destination");
-
-	const resolveOptions = {
-		getArtifactsDir: () => getArtifactsDir(),
-		getSessionId: () => getSessionId(),
+/** Locate the plan file the agent wrote and finalize its title — without
+ *  renaming anything. Tries, in order: the slug derived from `extra.title`
+ *  (`local://<slug>-plan.md`), the plan path from plan-mode state, then a scan
+ *  of recent plan files. Throws a `ToolError` guiding the agent when none exist. */
+export async function resolveApprovedPlan(input: ResolveApprovedPlanInput): Promise<ResolvedApprovedPlan> {
+	const ordered: string[] = [];
+	const consider = (url: string | undefined): void => {
+		if (url && !ordered.includes(url)) ordered.push(url);
 	};
-	const resolvedSource = resolveLocalUrlToPath(normalizeLocalScheme(planFilePath), resolveOptions);
-	const resolvedDestination = resolveLocalUrlToPath(normalizeLocalScheme(finalPlanFilePath), resolveOptions);
 
-	if (resolvedSource === resolvedDestination) {
-		return;
+	const slug = planSlugFromSupplied(input.suppliedTitle);
+	consider(slug ? planFileUrlForSlug(slug) : undefined);
+	consider(input.statePlanFilePath);
+
+	for (const url of ordered) {
+		const content = await input.readPlan(url);
+		if (content !== null) return finalizeApprovedPlan(url, content, input.suppliedTitle);
 	}
 
-	try {
-		const destinationStat = await fs.stat(resolvedDestination);
-		if (destinationStat.isFile()) {
-			throw new Error(
-				`Plan destination already exists at ${finalPlanFilePath}. Choose a different title and submit the plan for approval again.`,
-			);
-		}
-		throw new Error(`Plan destination exists but is not a file: ${finalPlanFilePath}`);
-	} catch (error) {
-		if (!isEnoent(error)) {
-			throw error;
+	if (input.listPlanFiles) {
+		for (const url of await input.listPlanFiles()) {
+			if (ordered.includes(url)) continue;
+			const content = await input.readPlan(url);
+			if (content !== null) return finalizeApprovedPlan(url, content, input.suppliedTitle);
 		}
 	}
 
-	try {
-		await fs.rename(resolvedSource, resolvedDestination);
-	} catch (error) {
-		throw new Error(
-			`Failed to rename approved plan from ${planFilePath} to ${finalPlanFilePath}: ${error instanceof Error ? error.message : String(error)}`,
-		);
-	}
+	const target = ordered[0] ?? input.statePlanFilePath;
+	throw new ToolError(
+		`Plan file not found at ${target}. Write the finalized plan to ${target} before requesting approval.`,
+	);
+}
+
+function finalizeApprovedPlan(planFilePath: string, planContent: string, suppliedTitle: unknown): ResolvedApprovedPlan {
+	const { title } = resolvePlanTitle({ suppliedTitle, planContent, planFilePath });
+	return { planFilePath, planContent, title };
 }
diff --git a/packages/coding-agent/src/plan-mode/plan-protection.ts b/packages/coding-agent/src/plan-mode/plan-protection.ts
index ed01621b9..4c20ff1dd 100644
--- a/packages/coding-agent/src/plan-mode/plan-protection.ts
+++ b/packages/coding-agent/src/plan-mode/plan-protection.ts
@@ -16,11 +16,11 @@ function readTargetsPlan(readPath: string, planTarget: string): boolean {
  * Build a compaction protection matcher that keeps `read` results for the active
  * plan file intact through prune/shake — the plan analog of skill-read
  * protection. Matches both the canonical `local://PLAN.md` alias and the
- * session's current plan reference path (e.g. a titled `local://<title>.md`), so
- * the plan survives compaction whether the agent reads it by alias or by title.
+ * session's current plan reference path (the agent-chosen `local://<slug>-plan.md`),
+ * so the plan survives compaction whether the agent reads it by alias or by name.
  *
- * `getPlanReferencePath` is evaluated at match time so a mid-session retitle
- * (plan approval renames `PLAN.md` → `<title>.md`) is honored immediately.
+ * `getPlanReferencePath` is evaluated at match time so the plan path set on
+ * approval is honored immediately.
  */
 export function createPlanReadMatcher(getPlanReferencePath: () => string): (context: ProtectedToolContext) => boolean {
 	return (context: ProtectedToolContext) => {
diff --git a/packages/coding-agent/src/prompts/system/plan-mode-active.md b/packages/coding-agent/src/prompts/system/plan-mode-active.md
index f6ee4a794..d17313137 100644
--- a/packages/coding-agent/src/prompts/system/plan-mode-active.md
+++ b/packages/coding-agent/src/prompts/system/plan-mode-active.md
@@ -6,7 +6,7 @@ You NEVER:
 - Run state-changing commands (git commit, npm install, etc.)
 - Make any system changes
 
-To implement: call `resolve` with `action: "apply"`, a `reason`, and `extra: { title: "<PLAN_TITLE>" }` → user approves an execution option → full write access is restored. `<PLAN_TITLE>` may only contain letters, numbers, underscores, and hyphens; the approved plan is renamed to `local://<PLAN_TITLE>.md`.
+To implement: call `resolve` with `action: "apply"`, a `reason`, and `extra: { title: "<slug>" }` where `<slug>` matches your `local://<slug>-plan.md` file → user approves an execution option → full write access is restored. `<slug>` may only contain letters, numbers, underscores, and hyphens. The plan file is never renamed, so its name is yours to choose.
 
 You NEVER ask the user to exit plan mode for you; you MUST call `resolve` yourself.
 </critical>
@@ -18,9 +18,9 @@ A plan is **decision-complete**: another engineer or agent can execute it end-to
 ## Plan File
 
 {{#if planExists}}
-Plan file exists at `{{planFilePath}}`; you MUST read and update it incrementally.
+Plan file exists at `{{planFilePath}}`; you MUST read and update it incrementally. If this request is a different task, write a fresh `local://<slug>-plan.md` instead and leave the old plan in place.
 {{else}}
-You MUST create a plan at `{{planFilePath}}`.
+Choose a short kebab-case `<slug>` that names this task (letters, numbers, hyphens) and write the plan to `local://<slug>-plan.md` — e.g. `local://auth-token-refresh-plan.md`. You MUST pass that same `<slug>` as `title` when you call `resolve`.
 {{/if}}
 
 You MUST use `{{editToolName}}` for incremental updates; use `{{writeToolName}}` only for create/full replace. You MUST update the plan as you learn — you NEVER batch all writing to the end.
@@ -79,7 +79,7 @@ You MUST draft an approach from your exploration, weigh trade-offs briefly, then
 You MUST read the critical files you intend to touch to confirm the approach holds against the real code. You MUST verify the plan still matches the original request. You SHOULD use `{{askToolName}}` to close remaining preference questions.
 
 ### Phase 4 — Write the plan
-You MUST write `{{planFilePath}}` per **The Plan** below.
+You MUST write the plan file (see **Plan File** above) per **The Plan** below.
 </procedure>
 {{/if}}
 
@@ -118,7 +118,7 @@ You MUST use `{{askToolName}}` only to clarify requirements or choose between ap
 
 Your turn ends ONLY by:
 1. Using `{{askToolName}}` to gather information, OR
-2. Calling `resolve` with `action: "apply"`, `reason`, and `extra: { title: "<PLAN_TITLE>" }` when ready — this triggers user approval, then implementation with full tool access.
+2. Calling `resolve` with `action: "apply"`, `reason`, and `extra: { title: "<slug>" }` (the slug of your `local://<slug>-plan.md`) when ready — this triggers user approval, then implementation with full tool access.
 
 You NEVER ask for plan approval via text or `{{askToolName}}`; you MUST use `resolve`.
 You MUST keep going until the plan is decision-complete.
diff --git a/packages/coding-agent/src/prompts/system/plan-mode-approved.md b/packages/coding-agent/src/prompts/system/plan-mode-approved.md
index 970e36a09..7b8b0df5f 100644
--- a/packages/coding-agent/src/prompts/system/plan-mode-approved.md
+++ b/packages/coding-agent/src/prompts/system/plan-mode-approved.md
@@ -16,7 +16,7 @@ The plan path is for subagent handoff only. You already have the plan; NEVER rea
 
 The full plan is injected below. You MUST execute it now:
 
-<plan path="{{finalPlanFilePath}}">
+<plan path="{{planFilePath}}">
 {{planContent}}
 </plan>
 
diff --git a/packages/coding-agent/src/tools/plan-mode-guard.ts b/packages/coding-agent/src/tools/plan-mode-guard.ts
index 5212a2906..c27fe2fea 100644
--- a/packages/coding-agent/src/tools/plan-mode-guard.ts
+++ b/packages/coding-agent/src/tools/plan-mode-guard.ts
@@ -1,4 +1,3 @@
-import * as path from "node:path";
 import { resolveLocalUrlToPath, resolveVaultUrlToPath } from "../internal-urls";
 import type { ToolSession } from ".";
 import { normalizeLocalScheme, resolveToCwd } from "./path-utils";
@@ -6,10 +5,19 @@ import { ToolError } from "./tool-errors";
 
 const VAULT_SCHEME_PREFIX = "vault:";
 const LOCAL_SCHEME_PREFIX = "local:";
-const PLAN_ALIAS_FILE = "PLAN.md";
-const LOCAL_PLAN_ALIAS = "local://PLAN.md";
 
-function resolveRawPath(session: ToolSession, targetPath: string): string {
+/** True when `targetPath` addresses the session-local artifact sandbox
+ *  (`local://…`). Those files are not part of the working tree, so plan mode
+ *  treats them as freely writable scratch/plan space. */
+function targetsLocalSandbox(targetPath: string): boolean {
+	return normalizeLocalScheme(targetPath).startsWith(LOCAL_SCHEME_PREFIX);
+}
+
+/**
+ * Resolve a write/edit target to its absolute filesystem path, honoring the
+ * `local://` and `vault://` schemes. Plain paths resolve against the session cwd.
+ */
+export function resolvePlanPath(session: ToolSession, targetPath: string): string {
 	const normalized = normalizeLocalScheme(targetPath);
 	if (normalized.startsWith(LOCAL_SCHEME_PREFIX)) {
 		return resolveLocalUrlToPath(normalized, {
@@ -25,37 +33,12 @@ function resolveRawPath(session: ToolSession, targetPath: string): string {
 	return resolveToCwd(normalized, session.cwd);
 }
 
-function isPlanAliasTarget(session: ToolSession, targetPath: string, resolved: string): boolean {
-	const normalized = normalizeLocalScheme(targetPath);
-	if (normalized === LOCAL_PLAN_ALIAS) return true;
-	return resolved === resolveToCwd(PLAN_ALIAS_FILE, session.cwd);
-}
-
 /**
- * Resolve a write/edit target to its absolute filesystem path.
- *
- * In plan mode, transparently redirects `PLAN.md` aliases and targets whose
- * basename matches the plan file's basename to the canonical plan file
- * location at `state.planFilePath`. This lets `write` and `edit` accept the
- * habitual plan filename after approval even when the active artifact has a
- * titled path such as `local://APPROVED.md`.
- *
- * Outside plan mode (or when the basename does not match) this is a no-op.
+ * Plan mode keeps the working tree read-only while letting the agent draft its
+ * plan. Writes and edits to the `local://` artifact sandbox are allowed (that is
+ * where the plan and any scratch notes live); anything that would touch the
+ * working tree — or rename/delete a file — is rejected.
  */
-export function resolvePlanPath(session: ToolSession, targetPath: string): string {
-	const resolved = resolveRawPath(session, targetPath);
-
-	const state = session.getPlanModeState?.();
-	if (!state?.enabled) return resolved;
-
-	const planResolved = resolveRawPath(session, state.planFilePath);
-	if (resolved === planResolved) return resolved;
-	if (isPlanAliasTarget(session, targetPath, resolved)) return planResolved;
-	if (path.basename(resolved) !== path.basename(planResolved)) return resolved;
-
-	return planResolved;
-}
-
 export function enforcePlanModeWrite(
 	session: ToolSession,
 	targetPath: string,
@@ -64,9 +47,6 @@ export function enforcePlanModeWrite(
 	const state = session.getPlanModeState?.();
 	if (!state?.enabled) return;
 
-	const resolvedTarget = resolvePlanPath(session, targetPath);
-	const resolvedPlan = resolvePlanPath(session, state.planFilePath);
-
 	if (options?.move) {
 		throw new ToolError("Plan mode: renaming files is not allowed.");
 	}
@@ -75,7 +55,9 @@ export function enforcePlanModeWrite(
 		throw new ToolError("Plan mode: deleting files is not allowed.");
 	}
 
-	if (resolvedTarget !== resolvedPlan) {
-		throw new ToolError(`Plan mode: only the plan file may be modified (${state.planFilePath}).`);
-	}
+	if (targetsLocalSandbox(targetPath)) return;
+
+	throw new ToolError(
+		"Plan mode: the working tree is read-only. Write your plan to a local://<slug>-plan.md file instead.",
+	);
 }
diff --git a/packages/coding-agent/test/acp-agent.test.ts b/packages/coding-agent/test/acp-agent.test.ts
index 4a22fff8b..597c3c643 100644
--- a/packages/coding-agent/test/acp-agent.test.ts
+++ b/packages/coding-agent/test/acp-agent.test.ts
@@ -615,7 +615,7 @@ describe("ACP agent", () => {
 		await Bun.sleep(0);
 	});
 
-	it("plan-approval standing handler renames the plan and exits plan mode on apply", async () => {
+	it("plan-approval standing handler approves the agent-named plan and exits plan mode on apply", async () => {
 		const harness = await createHarness();
 		Settings.instance.set("plan.enabled", true);
 
@@ -625,7 +625,9 @@ describe("ACP agent", () => {
 
 		const artifactsDir = session.sessionManager.getArtifactsDir();
 		expect(artifactsDir).not.toBeNull();
-		const planPath = path.join(artifactsDir!, "local", "PLAN.md");
+		// The agent writes to its chosen `local://<slug>-plan.md` and resolves with
+		// the matching slug — the file is never renamed.
+		const planPath = path.join(artifactsDir!, "local", "words-counter-plan.md");
 		await Bun.write(planPath, "# Words Counter\n\nFile contents.");
 
 		const updatesBefore = harness.updates.length;
@@ -636,21 +638,20 @@ describe("ACP agent", () => {
 			extra: { title: "words-counter" },
 		})) as {
 			content: Array<{ type: string; text: string }>;
-			details: { sourceToolName: string; sourceResultDetails: { finalPlanFilePath: string; title: string } };
+			details: { sourceToolName: string; sourceResultDetails: { planFilePath: string; title: string } };
 		};
 
 		// Plan-approval payload is shaped for `event-controller` / ACP renderers.
 		expect(result.details.sourceToolName).toBe("plan_approval");
 		expect(result.details.sourceResultDetails.title).toBe("words-counter");
-		expect(result.details.sourceResultDetails.finalPlanFilePath).toBe("local://words-counter.md");
+		expect(result.details.sourceResultDetails.planFilePath).toBe("local://words-counter-plan.md");
 		expect(result.content[0]?.text).toMatch(/Plan approved/);
-		// Plan file is renamed and the source path no longer exists.
-		expect(await Bun.file(path.join(artifactsDir!, "local", "words-counter.md")).exists()).toBe(true);
-		expect(await Bun.file(planPath).exists()).toBe(false);
+		// Plan file keeps its agent-chosen name — no rename.
+		expect(await Bun.file(planPath).exists()).toBe(true);
 		// Mode + handler are cleared; the agent regains write tools next turn.
 		expect(session.planModeState).toBeUndefined();
 		expect(session.standingResolveHandler).toBeUndefined();
-		expect(session.planReferencePath).toBe("local://words-counter.md");
+		expect(session.planReferencePath).toBe("local://words-counter-plan.md");
 		const approvalUpdates = harness.updates.slice(updatesBefore);
 		// Mode-change notifications reached the client so Zed's UI and config
 		// selector both reflect the approval-driven exit.
diff --git a/packages/coding-agent/test/interactive-mode-plan-review.test.ts b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
index 195ef9778..30086e8e3 100644
--- a/packages/coding-agent/test/interactive-mode-plan-review.test.ts
+++ b/packages/coding-agent/test/interactive-mode-plan-review.test.ts
@@ -127,7 +127,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://PLAN.md",
 		});
 
 		expect(review.mock.calls[0]?.[0]).toContain("First plan");
@@ -138,7 +137,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://PLAN.md",
 		});
 
 		// Each approval shows the current plan in the overlay, not a stale one.
@@ -173,7 +171,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://PLAN.md",
 		});
 
 		expect(startSpy).toHaveBeenCalledWith(expect.objectContaining({ text: expect.stringContaining("needs detail") }));
@@ -199,7 +196,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://PLAN.md",
 		});
 
 		expect(startSpy).not.toHaveBeenCalled();
@@ -228,7 +224,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://PLAN.md",
 		});
 
 		// The synthetic plan-approved prompt carries the in-overlay edit, not the
@@ -258,7 +253,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://APPROVED.md",
 		});
 
 		expect(selector).toHaveBeenCalledWith(
@@ -336,7 +330,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://APPROVED.md",
 		});
 
 		expect(contextSpy).toHaveBeenCalledWith({ contextWindow: executionModel.contextWindow });
@@ -365,7 +358,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://APPROVED.md",
 		});
 
 		expect(selector.mock.calls[0]?.[3]).toEqual(
@@ -392,7 +384,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://APPROVED.md",
 		});
 
 		expect(selector.mock.calls[0]?.[3]).toEqual(
@@ -420,7 +411,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath: "local://APPROVED.md",
 		});
 
 		expect(selector).toHaveBeenCalledWith(
@@ -434,12 +424,11 @@ describe("InteractiveMode plan review rendering", () => {
 
 	it("approves a plan without clearing the session when keeping context", async () => {
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
 		});
-		const resolvedFinalPlanPath = resolveLocalUrlToPath(finalPlanFilePath, {
+		const resolvedFinalPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
 		});
@@ -456,7 +445,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 
 		expect(clear).not.toHaveBeenCalled();
@@ -468,7 +456,6 @@ describe("InteractiveMode plan review rendering", () => {
 
 	it("keeps the existing approve-and-execute path clearing the session", async () => {
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -485,7 +472,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 
 		expect(clear).toHaveBeenCalledTimes(1);
@@ -513,7 +499,6 @@ describe("InteractiveMode plan review rendering", () => {
 		session.settings.setModelRole("plan", "anthropic/claude-sonnet-4-5");
 
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -547,7 +532,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 
 		expect(observedSegments).toEqual(["default", "slow"]);
@@ -558,7 +542,6 @@ describe("InteractiveMode plan review rendering", () => {
 
 	it("re-enters plan mode on the approved titled artifact after approve-and-execute", async () => {
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -575,23 +558,21 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "APPROVED",
-			finalPlanFilePath,
 		});
 
 		expect(mode.planModeEnabled).toBe(false);
-		expect(session.getPlanReferencePath()).toBe(finalPlanFilePath);
+		expect(session.getPlanReferencePath()).toBe(planFilePath);
 
 		await mode.handlePlanModeCommand();
 		expect(session.getPlanModeState()).toMatchObject({
 			enabled: true,
-			planFilePath: finalPlanFilePath,
+			planFilePath,
 			reentry: true,
 		});
 	});
 
 	it("Approve and compact context: ok outcome dispatches plan-approved after compaction", async () => {
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -609,14 +590,13 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 
 		// Compaction was run with the rendered planning-specific custom instruction.
 		expect(compactSpy).toHaveBeenCalledTimes(1);
 		const [compactInstruction] = compactSpy.mock.calls[0]!;
 		expect(typeof compactInstruction).toBe("string");
-		expect(compactInstruction as string).toContain(finalPlanFilePath);
+		expect(compactInstruction as string).toContain(planFilePath);
 
 		// Plan-approved synthetic prompt was dispatched.
 		const planApprovedIdx = promptSpy.mock.calls.findIndex(isPlanApprovedCall);
@@ -634,7 +614,6 @@ describe("InteractiveMode plan review rendering", () => {
 		// CompactionOutcome boundary; the underlying executeCompaction → sentinel
 		// classification path is producer-layer and not under T3's contract.)
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -654,7 +633,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 
 		// Operator was told the dispatch was deferred.
@@ -663,7 +641,7 @@ describe("InteractiveMode plan review rendering", () => {
 		);
 		// Plan reference path was recorded so the session knows about the approved
 		// plan at its final destination …
-		expect(setPlanRefSpy).toHaveBeenCalledWith(finalPlanFilePath);
+		expect(setPlanRefSpy).toHaveBeenCalledWith(planFilePath);
 		// … but markPlanReferenceSent was NOT called, so the next operator turn
 		// will inject the reference fresh via #buildPlanReferenceMessage. This is
 		// the load-bearing assertion that the cancel path leaves the executor
@@ -677,7 +655,6 @@ describe("InteractiveMode plan review rendering", () => {
 		// Mock `handleCompactCommand` to surface the "failed" outcome directly.
 		// Failure → approval intent stands → synthetic dispatch fires.
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -695,7 +672,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 
 		// Plan-approved synthetic prompt WAS dispatched despite the failure.
@@ -710,7 +686,6 @@ describe("InteractiveMode plan review rendering", () => {
 		// hit #buildPlanReferenceMessage with the stale plan-mode path. Pin it
 		// before the compaction await.
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -725,7 +700,7 @@ describe("InteractiveMode plan review rendering", () => {
 		const setPlanRefSpy = vi.spyOn(session, "setPlanReferencePath");
 		let planRefSetWhenCompactionRan = false;
 		vi.spyOn(mode, "handleCompactCommand").mockImplementation(async () => {
-			planRefSetWhenCompactionRan = setPlanRefSpy.mock.calls.some(call => call[0] === finalPlanFilePath);
+			planRefSetWhenCompactionRan = setPlanRefSpy.mock.calls.some(call => call[0] === planFilePath);
 			return "ok";
 		});
 
@@ -733,7 +708,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 
 		// The contract: by the time handleCompactCommand runs (and flushes the
@@ -763,7 +737,6 @@ describe("InteractiveMode plan review rendering", () => {
 		throwError?: Error,
 	): Promise<void> {
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -784,7 +757,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 	}
 
@@ -822,7 +794,6 @@ describe("InteractiveMode plan review rendering", () => {
 
 	it("B5: Approve and execute (no compact) → markPlanCompactAbortPending never called; flag stays false", async () => {
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -838,7 +809,6 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "PLAN",
-			finalPlanFilePath,
 		});
 
 		expect(markSpy).not.toHaveBeenCalled();
@@ -847,7 +817,6 @@ describe("InteractiveMode plan review rendering", () => {
 
 	it("re-enters plan mode on the approved titled artifact after approval", async () => {
 		const planFilePath = "local://PLAN.md";
-		const finalPlanFilePath = "local://APPROVED.md";
 		const resolvedPlanPath = resolveLocalUrlToPath(planFilePath, {
 			getArtifactsDir: () => session.sessionManager.getArtifactsDir(),
 			getSessionId: () => session.sessionManager.getSessionId(),
@@ -866,24 +835,22 @@ describe("InteractiveMode plan review rendering", () => {
 			planFilePath,
 			planExists: true,
 			title: "APPROVED",
-			finalPlanFilePath,
 		});
 
 		expect(mode.planModeEnabled).toBe(false);
-		expect(session.getPlanReferencePath()).toBe(finalPlanFilePath);
+		expect(session.getPlanReferencePath()).toBe(planFilePath);
 
 		await mode.handlePlanModeCommand();
 		expect(session.getPlanModeState()).toMatchObject({
 			enabled: true,
-			planFilePath: finalPlanFilePath,
+			planFilePath,
 			reentry: true,
 		});
 
 		await mode.handlePlanApproval({
-			planFilePath: finalPlanFilePath,
+			planFilePath,
 			planExists: true,
 			title: "APPROVED",
-			finalPlanFilePath,
 		});
 
 		expect(selector).toHaveBeenCalledTimes(2);
diff --git a/packages/coding-agent/test/plan-mode/approved-plan.test.ts b/packages/coding-agent/test/plan-mode/approved-plan.test.ts
index 6b1d1d98b..1c454d292 100644
--- a/packages/coding-agent/test/plan-mode/approved-plan.test.ts
+++ b/packages/coding-agent/test/plan-mode/approved-plan.test.ts
@@ -1,53 +1,71 @@
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
+import { describe, expect, it } from "bun:test";
 import {
 	humanizePlanTitle,
 	normalizePlanTitle,
-	renameApprovedPlanFile,
+	planFileUrlForSlug,
+	resolveApprovedPlan,
 	resolvePlanTitle,
 } from "@oh-my-pi/pi-coding-agent/plan-mode/approved-plan";
 
-describe("renameApprovedPlanFile", () => {
-	let tmpDir: string;
-	let artifactsDir: string;
-
-	beforeEach(async () => {
-		tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "approved-plan-"));
-		artifactsDir = path.join(tmpDir, "artifacts");
-		await fs.mkdir(path.join(artifactsDir, "local"), { recursive: true });
+describe("planFileUrlForSlug", () => {
+	it("maps a slug to its local plan URL", () => {
+		expect(planFileUrlForSlug("auth-refactor")).toBe("local://auth-refactor-plan.md");
 	});
+});
 
-	afterEach(async () => {
-		await fs.rm(tmpDir, { recursive: true, force: true });
-	});
-
-	function options(planFilePath: string, finalPlanFilePath: string) {
-		return {
-			planFilePath,
-			finalPlanFilePath,
-			getArtifactsDir: () => artifactsDir,
-			getSessionId: () => "session-z",
-		};
+describe("resolveApprovedPlan", () => {
+	/** A `readPlan` backed by an in-memory map of `local://` URL → content. */
+	function reader(files: Record<string, string>) {
+		return async (url: string) => (url in files ? files[url] : null);
 	}
 
-	it("fails with actionable error when destination already exists", async () => {
-		await Bun.write(path.join(artifactsDir, "local", "PLAN.md"), "draft");
-		await Bun.write(path.join(artifactsDir, "local", "WP_MIGRATION_PLAN.md"), "existing");
-
-		await expect(renameApprovedPlanFile(options("local://PLAN.md", "local://WP_MIGRATION_PLAN.md"))).rejects.toThrow(
-			"Plan destination already exists at local://WP_MIGRATION_PLAN.md",
-		);
+	it("locates the plan from the supplied title's slug — no rename", async () => {
+		const result = await resolveApprovedPlan({
+			suppliedTitle: "auth-refactor",
+			statePlanFilePath: "local://PLAN.md",
+			readPlan: reader({ "local://auth-refactor-plan.md": "# Auth refactor\n\nbody" }),
+		});
+		expect(result.planFilePath).toBe("local://auth-refactor-plan.md");
+		expect(result.planContent).toContain("body");
+		expect(result.title).toBe("auth-refactor");
 	});
 
-	it("renames PLAN.md to titled artifact path", async () => {
-		await Bun.write(path.join(artifactsDir, "local", "PLAN.md"), "draft body");
+	it("strips a trailing -plan from the supplied title before reconstructing the file", async () => {
+		const result = await resolveApprovedPlan({
+			suppliedTitle: "auth-plan",
+			statePlanFilePath: "local://PLAN.md",
+			readPlan: reader({ "local://auth-plan.md": "# Auth\n\nbody" }),
+		});
+		expect(result.planFilePath).toBe("local://auth-plan.md");
+	});
 
-		await renameApprovedPlanFile(options("local://PLAN.md", "local://WP_MIGRATION_PLAN.md"));
+	it("falls back to the plan-mode state path when the slug file is absent", async () => {
+		const result = await resolveApprovedPlan({
+			suppliedTitle: "mismatch",
+			statePlanFilePath: "local://existing-plan.md",
+			readPlan: reader({ "local://existing-plan.md": "# Existing\n\nbody" }),
+		});
+		expect(result.planFilePath).toBe("local://existing-plan.md");
+	});
 
-		expect(await Bun.file(path.join(artifactsDir, "local", "WP_MIGRATION_PLAN.md")).text()).toBe("draft body");
-		await expect(fs.stat(path.join(artifactsDir, "local", "PLAN.md"))).rejects.toThrow();
+	it("scans listed plan files when the title was dropped and state path is empty", async () => {
+		const result = await resolveApprovedPlan({
+			suppliedTitle: undefined,
+			statePlanFilePath: "local://PLAN.md",
+			readPlan: reader({ "local://discovered-plan.md": "# Discovered\n\nbody" }),
+			listPlanFiles: async () => ["local://discovered-plan.md"],
+		});
+		expect(result.planFilePath).toBe("local://discovered-plan.md");
+	});
+
+	it("throws an actionable error when no plan file exists", async () => {
+		await expect(
+			resolveApprovedPlan({
+				suppliedTitle: "ghost",
+				statePlanFilePath: "local://PLAN.md",
+				readPlan: reader({}),
+			}),
+		).rejects.toThrow("Plan file not found at local://ghost-plan.md");
 	});
 });
 
diff --git a/packages/coding-agent/test/tools/plan-mode-guard-local.test.ts b/packages/coding-agent/test/tools/plan-mode-guard-local.test.ts
index 070abe496..6ac46329e 100644
--- a/packages/coding-agent/test/tools/plan-mode-guard-local.test.ts
+++ b/packages/coding-agent/test/tools/plan-mode-guard-local.test.ts
@@ -43,72 +43,50 @@ describe("resolvePlanPath local:// support", () => {
 	});
 });
 
-describe("resolvePlanPath plan-mode redirect", () => {
-	const planMode: PlanModeState = { enabled: true, planFilePath: "local://PLAN.md" };
-	const approvedPlanMode: PlanModeState = { enabled: true, planFilePath: "local://APPROVED.md" };
+describe("resolvePlanPath resolves literally (no plan-mode redirect)", () => {
+	const planMode: PlanModeState = { enabled: true, planFilePath: "local://some-plan.md" };
 
-	it("redirects bare PLAN.md to the session plan path when plan mode is active", () => {
-		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", planMode });
-		expect(resolvePlanPath(session, "PLAN.md")).toBe(path.join("/tmp/agent-artifacts", "local", "PLAN.md"));
-	});
-
-	it("redirects ./PLAN.md and absolute cwd-PLAN.md alike", () => {
+	it("resolves a bare path against cwd regardless of plan mode", () => {
 		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", cwd: "/repo", planMode });
-		const expected = path.join("/tmp/agent-artifacts", "local", "PLAN.md");
-		expect(resolvePlanPath(session, "./PLAN.md")).toBe(expected);
-		expect(resolvePlanPath(session, "/repo/PLAN.md")).toBe(expected);
-	});
-
-	it("does not redirect when plan mode is disabled", () => {
-		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", cwd: "/repo" });
 		expect(resolvePlanPath(session, "PLAN.md")).toBe(path.join("/repo", "PLAN.md"));
-	});
-
-	it("does not redirect paths whose basename differs from the plan basename", () => {
-		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", cwd: "/repo", planMode });
 		expect(resolvePlanPath(session, "src/foo.ts")).toBe(path.join("/repo", "src/foo.ts"));
 	});
 
-	it("leaves an explicit local://PLAN.md unchanged", () => {
+	it("resolves a local:// plan file to the session local root", () => {
 		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", planMode });
-		expect(resolvePlanPath(session, "local://PLAN.md")).toBe(path.join("/tmp/agent-artifacts", "local", "PLAN.md"));
-	});
-
-	it("redirects PLAN.md aliases to the active titled plan artifact", () => {
-		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", cwd: "/repo", planMode: approvedPlanMode });
-		const expected = path.join("/tmp/agent-artifacts", "local", "APPROVED.md");
-		expect(resolvePlanPath(session, "PLAN.md")).toBe(expected);
-		expect(resolvePlanPath(session, "./PLAN.md")).toBe(expected);
-		expect(resolvePlanPath(session, "/repo/PLAN.md")).toBe(expected);
-		expect(resolvePlanPath(session, "local://PLAN.md")).toBe(expected);
-	});
-});
-
-describe("enforcePlanModeWrite plan-mode redirect", () => {
-	const planMode: PlanModeState = { enabled: true, planFilePath: "local://PLAN.md" };
-	const approvedPlanMode: PlanModeState = { enabled: true, planFilePath: "local://APPROVED.md" };
-
-	it("accepts bare PLAN.md as a write to the plan file", () => {
-		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", planMode });
-		expect(() => enforcePlanModeWrite(session, "PLAN.md", { op: "update" })).not.toThrow();
-	});
-
-	it("still rejects non-plan paths in plan mode", () => {
-		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", planMode });
-		expect(() => enforcePlanModeWrite(session, "src/foo.ts", { op: "update" })).toThrow(
-			/only the plan file may be modified/,
-		);
-	});
-
-	it("accepts bare PLAN.md as a write to a titled active plan file", () => {
-		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", planMode: approvedPlanMode });
-		expect(() => enforcePlanModeWrite(session, "PLAN.md", { op: "update" })).not.toThrow();
-	});
-
-	it("rejects deletes of PLAN.md even when basename matches", () => {
-		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", planMode });
-		expect(() => enforcePlanModeWrite(session, "PLAN.md", { op: "delete" })).toThrow(
-			/Plan mode: deleting files is not allowed/,
+		expect(resolvePlanPath(session, "local://some-plan.md")).toBe(
+			path.join("/tmp/agent-artifacts", "local", "some-plan.md"),
 		);
 	});
 });
+
+describe("enforcePlanModeWrite (working tree read-only, local:// sandbox writable)", () => {
+	const planMode: PlanModeState = { enabled: true, planFilePath: "local://some-plan.md" };
+
+	it("accepts writes to any local:// file", () => {
+		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", planMode });
+		expect(() => enforcePlanModeWrite(session, "local://auth-refactor-plan.md", { op: "create" })).not.toThrow();
+		expect(() => enforcePlanModeWrite(session, "local://scratch/notes.md", { op: "update" })).not.toThrow();
+	});
+
+	it("rejects writes to the working tree", () => {
+		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", cwd: "/repo", planMode });
+		expect(() => enforcePlanModeWrite(session, "src/foo.ts", { op: "update" })).toThrow(/working tree is read-only/);
+		expect(() => enforcePlanModeWrite(session, "PLAN.md", { op: "create" })).toThrow(/working tree is read-only/);
+	});
+
+	it("rejects deletes and renames outright", () => {
+		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", planMode });
+		expect(() => enforcePlanModeWrite(session, "local://some-plan.md", { op: "delete" })).toThrow(
+			/deleting files is not allowed/,
+		);
+		expect(() => enforcePlanModeWrite(session, "local://some-plan.md", { move: "local://renamed.md" })).toThrow(
+			/renaming files is not allowed/,
+		);
+	});
+
+	it("is a no-op when plan mode is disabled", () => {
+		const session = makeSession({ artifactsDir: "/tmp/agent-artifacts", cwd: "/repo" });
+		expect(() => enforcePlanModeWrite(session, "src/foo.ts", { op: "update" })).not.toThrow();
+	});
+});

From 1a9d898b8afff47c936ccf6e17e6482a03cb7107 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:18:02 +0200
Subject: [PATCH 115/181] feat(coding-agent): added immediate steering flush on
 empty streaming submit

- Updated InputController streaming submit handling to interrupt and resume when queued steering exists, refreshing the pending-message UI and render.
- Added AgentSession.interruptAndFlushQueuedMessages to abort active work and continue processing queued messages immediately.
- Added tests for queued steering interruption in both agent-session concurrency and input-controller keybinding flows.
---
 .../src/modes/controllers/input-controller.ts | 21 ++++--
 .../coding-agent/src/session/agent-session.ts | 13 ++++
 .../test/agent-session-concurrent.test.ts     | 73 +++++++++++++++++++
 .../test/input-controller-keybindings.test.ts | 46 +++++++++++-
 packages/tui/src/tui.ts                       |  6 +-
 5 files changed, 152 insertions(+), 7 deletions(-)

diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index 526d5a62a..da83ea41b 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -264,11 +264,22 @@ export class InputController {
 			text = text.trim();
 			if ((!isSettingsInitialized() || settings.get("emojiAutocomplete")) && text) text = expandEmoticons(text);
 
-			// Empty submit while streaming with queued messages: flush queues immediately
-			if (!text && this.ctx.session.isStreaming && this.ctx.session.queuedMessageCount > 0) {
-				// Abort current stream and let queued messages be processed
-				await this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
-				return;
+			// Empty submit while streaming with queued steering: interrupt now and
+			// immediately resume so the visible `Steer:` entry is sent without
+			// waiting for the current tool/model boundary.
+			if (!text && this.ctx.session.isStreaming) {
+				const queuedMessages = this.ctx.session.getQueuedMessages();
+				if (queuedMessages.steering.length > 0) {
+					await this.ctx.session.interruptAndFlushQueuedMessages({ reason: USER_INTERRUPT_LABEL });
+					this.ctx.updatePendingMessagesDisplay();
+					this.ctx.ui.requestRender();
+					return;
+				}
+				if (this.ctx.session.queuedMessageCount > 0) {
+					// Preserve the existing empty-submit flush for non-steer queues.
+					await this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
+					return;
+				}
 			}
 
 			if (!text) return;
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index db59785f4..a12b466f8 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -5165,6 +5165,19 @@ export class AgentSession {
 		}
 	}
 
+	/**
+	 * Abort active work, then immediately resume the agent so queued steer/follow-up
+	 * messages drain instead of waiting for another natural turn boundary.
+	 */
+	async interruptAndFlushQueuedMessages(options?: { reason?: string }): Promise<void> {
+		if (!this.agent.hasQueuedMessages()) return;
+		await this.abort({ reason: options?.reason });
+		if (!this.agent.hasQueuedMessages()) return;
+		if (this.isCompacting || this.isGeneratingHandoff) return;
+		await this.#maybeRestoreRetryFallbackPrimary();
+		await this.agent.continue();
+	}
+
 	/**
 	 * Start a new session, optionally with initial messages and parent tracking.
 	 * Clears all messages and starts a new session.
diff --git a/packages/coding-agent/test/agent-session-concurrent.test.ts b/packages/coding-agent/test/agent-session-concurrent.test.ts
index 9ba2bed27..9160918af 100644
--- a/packages/coding-agent/test/agent-session-concurrent.test.ts
+++ b/packages/coding-agent/test/agent-session-concurrent.test.ts
@@ -153,6 +153,79 @@ describe("AgentSession concurrent prompt guard", () => {
 		await firstPrompt.catch(() => {});
 	});
 
+	it("interrupts active work and immediately sends queued steering messages", async () => {
+		const model = getBundledModel("anthropic", "claude-sonnet-4-5")!;
+		const callMessages: Message[][] = [];
+
+		const agent = new Agent({
+			getApiKey: () => "test-key",
+			initialState: {
+				model,
+				systemPrompt: ["Test"],
+				tools: [],
+			},
+			convertToLlm,
+			streamFn: (_model, context, options) => {
+				const callIndex = callMessages.length;
+				callMessages.push([...context.messages]);
+				const stream = new AssistantMessageEventStream();
+				queueMicrotask(() => {
+					stream.push({ type: "start", partial: createAssistantMessage("") });
+					if (callIndex > 0) {
+						stream.push({ type: "done", reason: "stop", message: createAssistantMessage("Handled steer") });
+					}
+				});
+				options?.signal?.addEventListener(
+					"abort",
+					() => {
+						stream.push({
+							type: "error",
+							reason: "aborted",
+							error: createAssistantMessage("Interrupted"),
+						});
+					},
+					{ once: true },
+				);
+				return stream;
+			},
+		});
+
+		const sessionManager = SessionManager.inMemory();
+		const settings = Settings.isolated();
+		const authStorage = await AuthStorage.create(path.join(tempDir, "testauth-interrupt-flush.db"));
+		authStorages.push(authStorage);
+		const modelRegistry = new ModelRegistry(authStorage, path.join(tempDir, "models-interrupt-flush.yml"));
+		authStorage.setRuntimeApiKey("anthropic", "test-key");
+
+		session = new AgentSession({
+			agent,
+			sessionManager,
+			settings,
+			modelRegistry,
+		});
+
+		const firstPrompt = session.prompt("First message").catch(() => {});
+		await waitFor(() => session.isStreaming && callMessages.length === 1);
+
+		await session.steer("Send this now");
+		expect(session.getQueuedMessages().steering).toEqual(["Send this now"]);
+
+		await session.interruptAndFlushQueuedMessages({ reason: "Interrupted by user" });
+		await firstPrompt;
+
+		expect(callMessages).toHaveLength(2);
+		expect(
+			callMessages[1]?.some(message => {
+				if (typeof message.content === "string") {
+					return message.content.includes("Send this now");
+				}
+
+				return message.content.some(content => content.type === "text" && content.text.includes("Send this now"));
+			}),
+		).toBe(true);
+		expect(session.getQueuedMessages()).toEqual({ steering: [], followUp: [] });
+	});
+
 	it("should allow followUp() while streaming", async () => {
 		await createSession();
 
diff --git a/packages/coding-agent/test/input-controller-keybindings.test.ts b/packages/coding-agent/test/input-controller-keybindings.test.ts
index 93142eed3..7c773da8f 100644
--- a/packages/coding-agent/test/input-controller-keybindings.test.ts
+++ b/packages/coding-agent/test/input-controller-keybindings.test.ts
@@ -21,12 +21,14 @@ type FakeEditor = {
 	onExternalEditor?: () => void;
 	onDequeue?: () => void;
 	onChange?: (text: string) => void;
+	onSubmit?: (text: string) => Promise<void>;
 	setText(text: string): void;
 	getText(): string;
 	addToHistory(text: string): void;
 	setActionKeys(action: string, keys: string[]): void;
 	setCustomKeyHandler(key: string, handler: () => void): void;
 	clearCustomKeyHandlers(): void;
+	pasteText(text: string): void;
 };
 
 async function createContext() {
@@ -46,7 +48,14 @@ async function createContext() {
 	});
 	const resetDisplay = vi.fn();
 	const showModelSelector = vi.fn();
+	const requestRender = vi.fn();
+	const addInputListener = vi.fn();
+	const addStartListener = vi.fn();
+	const terminalWrite = vi.fn();
 	const prompt = vi.fn(async () => {});
+	const abort = vi.fn(async () => {});
+	const interruptAndFlushQueuedMessages = vi.fn(async () => {});
+	const getQueuedMessages = vi.fn(() => ({ steering: [] as string[], followUp: [] as string[] }));
 	const updatePendingMessagesDisplay = vi.fn();
 	const editor: FakeEditor = {
 		setText(text: string) {
@@ -56,13 +65,22 @@ async function createContext() {
 			return editorText;
 		},
 		addToHistory: vi.fn(),
+		pasteText(text: string) {
+			editorText += text;
+		},
 		setActionKeys,
 		setCustomKeyHandler,
 		clearCustomKeyHandlers,
 	};
 	const ctx = {
 		editor: editor as unknown as InteractiveModeContext["editor"],
-		ui: { requestRender: vi.fn(), resetDisplay } as unknown as InteractiveModeContext["ui"],
+		ui: {
+			requestRender,
+			resetDisplay,
+			addInputListener,
+			addStartListener,
+			terminal: { write: terminalWrite },
+		} as unknown as InteractiveModeContext["ui"],
 		loadingAnimation: undefined,
 		autoCompactionLoader: undefined,
 		retryLoader: undefined,
@@ -76,6 +94,10 @@ async function createContext() {
 			isEvalRunning: false,
 			extensionRunner: undefined,
 			prompt,
+			queuedMessageCount: 0,
+			getQueuedMessages,
+			abort,
+			interruptAndFlushQueuedMessages,
 		} as unknown as InteractiveModeContext["session"],
 		keybindings: {
 			getKeys(action: string) {
@@ -138,6 +160,10 @@ async function createContext() {
 			showModelSelector,
 			prompt,
 			updatePendingMessagesDisplay,
+			requestRender,
+			abort,
+			interruptAndFlushQueuedMessages,
+			getQueuedMessages,
 			resetDisplay,
 		},
 	};
@@ -167,6 +193,24 @@ describe("InputController keybinding setup", () => {
 		expect(spies.resetDisplay).toHaveBeenCalledTimes(1);
 	});
 
+	it("empty Enter interrupts and sends a queued steering message", async () => {
+		const { InputController, ctx, editor, spies } = await createContext();
+		const session = ctx.session as unknown as { isStreaming: boolean; queuedMessageCount: number };
+		session.isStreaming = true;
+		session.queuedMessageCount = 1;
+		spies.getQueuedMessages.mockReturnValue({ steering: ["Send this now"], followUp: [] });
+		const controller = new InputController(ctx);
+
+		controller.setupEditorSubmitHandler();
+		await editor.onSubmit?.("");
+
+		expect(spies.interruptAndFlushQueuedMessages).toHaveBeenCalledWith({ reason: "Interrupted by user" });
+		expect(spies.abort).not.toHaveBeenCalled();
+		expect(spies.updatePendingMessagesDisplay).toHaveBeenCalledTimes(1);
+		expect(spies.requestRender).toHaveBeenCalledTimes(1);
+		expect(spies.prompt).not.toHaveBeenCalled();
+	});
+
 	it("marks streaming follow-up submissions as local", async () => {
 		const { InputController, ctx, editor, spies } = await createContext();
 		const session = ctx.session as unknown as { isStreaming: boolean };
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index c4bc76d99..53b673c14 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -3098,7 +3098,11 @@ export class TUI extends Container {
 						: intent.kind === "deferredTailRepaint"
 							? `${intent.kind}(row=${intent.row})`
 							: intent.kind;
-		const msg = `[${new Date().toISOString()}] render: ${detail} (prev=${this.#previousLines.length}, new=${newLength}, height=${height})\n`;
+		const state =
+			`shw=${this.#scrollbackHighWater}, max=${this.#maxLinesRendered}, vpTop=${this.#viewportTopRow}, ` +
+			`dirty=${this.#nativeScrollbackDirty}, eager=${this.#eagerNativeScrollbackRebuild}, ` +
+			`lrStart=${this.#nativeScrollbackLiveRegionStart}, commitSafeEnd=${this.#nativeScrollbackCommitSafeEnd}`;
+		const msg = `[${new Date().toISOString()}] render: ${detail} (prev=${this.#previousLines.length}, new=${newLength}, height=${height}, ${state})\n`;
 		fs.appendFileSync(getDebugLogPath(), msg);
 	}
 

From 13ca95382d17537c255ec19796d7bc4671baac38 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:23:50 +0200
Subject: [PATCH 116/181] fix(coding-agent): recolored search tool icons to
 accent

- Switched find, search, ast_grep, and bm25 magnifier glyphs from success green to accent so the icon matches the tool title color.
---
 packages/coding-agent/CHANGELOG.md                  | 1 +
 packages/coding-agent/src/tools/ast-grep.ts         | 2 +-
 packages/coding-agent/src/tools/find.ts             | 4 ++--
 packages/coding-agent/src/tools/search-tool-bm25.ts | 2 +-
 packages/coding-agent/src/tools/search.ts           | 4 ++--
 5 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index dd972f99f..7aa63de66 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -39,6 +39,7 @@
 ### Fixed
 
 - Fixed plan approval resolution so `resolve` with `action: "apply"` can still find the plan file when `extra.title` is missing or stale by falling back to the current plan path and most-recent local plan artifacts
+- Fixed the search-family tool magnifier glyph (`find`, `search`, `ast_grep`, `search_tool_bm25`) to use the `accent` title color instead of `success` green, so the icon matches the tool title in the status header instead of standing out
 - Fixed TTSR stream interrupts to pass the matched rule name through the abort reason, so aborted in-flight tool placeholders say why they were stopped instead of `Request was aborted`.
 - Fixed URL reads for binary/special payloads to reuse local readers: remote archives list their root entries, SQLite databases show their table overview, notebooks render as editable cells, and unrenderable binary returns a metadata notice instead of decoded byte garbage.
 - Fixed pasted image-file paths that cannot be loaded to fall back to normal text paste with status feedback instead of disappearing.
diff --git a/packages/coding-agent/src/tools/ast-grep.ts b/packages/coding-agent/src/tools/ast-grep.ts
index 364397035..3935915d4 100644
--- a/packages/coding-agent/src/tools/ast-grep.ts
+++ b/packages/coding-agent/src/tools/ast-grep.ts
@@ -387,7 +387,7 @@ export const astGrepToolRenderer = {
 			{
 				...(limitReached
 					? { icon: "warning" as const }
-					: { iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")) }),
+					: { iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")) }),
 				title: "AST Grep",
 				description,
 				meta,
diff --git a/packages/coding-agent/src/tools/find.ts b/packages/coding-agent/src/tools/find.ts
index 26b6cb50c..134263d94 100644
--- a/packages/coding-agent/src/tools/find.ts
+++ b/packages/coding-agent/src/tools/find.ts
@@ -470,7 +470,7 @@ export const findToolRenderer = {
 			const lines = textContent.split("\n").filter(l => l.trim());
 			const header = renderStatusLine(
 				{
-					iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")),
+					iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")),
 					title: "Find",
 					description: formatFindRenderPaths(args?.paths),
 					meta: [formatCount("file", lines.length)],
@@ -521,7 +521,7 @@ export const findToolRenderer = {
 			{
 				...(truncated
 					? { icon: "warning" as const }
-					: { iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")) }),
+					: { iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")) }),
 				title: "Find",
 				description: formatFindRenderPaths(args?.paths),
 				meta,
diff --git a/packages/coding-agent/src/tools/search-tool-bm25.ts b/packages/coding-agent/src/tools/search-tool-bm25.ts
index 45d942eaf..466b5e02a 100644
--- a/packages/coding-agent/src/tools/search-tool-bm25.ts
+++ b/packages/coding-agent/src/tools/search-tool-bm25.ts
@@ -322,7 +322,7 @@ export const searchToolBm25Renderer = {
 		const header = renderStatusLine(
 			{
 				...(details.tools.length > 0
-					? { iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")) }
+					? { iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")) }
 					: { icon: "warning" as const }),
 				title: TOOL_DISCOVERY_TITLE,
 				description: truncateToWidth(safeQuery, MATCH_LABEL_LEN),
diff --git a/packages/coding-agent/src/tools/search.ts b/packages/coding-agent/src/tools/search.ts
index b5e4431ce..6820901ab 100644
--- a/packages/coding-agent/src/tools/search.ts
+++ b/packages/coding-agent/src/tools/search.ts
@@ -1373,7 +1373,7 @@ export const searchToolRenderer = {
 			const description = args?.pattern ?? undefined;
 			const header = renderStatusLine(
 				{
-					iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")),
+					iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")),
 					title: "Search",
 					description,
 					meta: [formatCount("item", lines.length)],
@@ -1434,7 +1434,7 @@ export const searchToolRenderer = {
 			{
 				...(truncated
 					? { icon: "warning" as const }
-					: { iconOverride: uiTheme.fg("success", uiTheme.symbol("icon.search")) }),
+					: { iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")) }),
 				title: "Search",
 				description,
 				meta,

From 4a3984eb0a3413cd68adbc6577bb433846584d25 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:33:43 +0200
Subject: [PATCH 117/181] fix(coding-agent/tools): fixed Markdown cache
 contamination from mutable render arrays

- Marked Markdown cached lines as readonly snapshots and returned copied arrays from `render()`.
- Stored fresh snapshot arrays in both L1 and L2 caches so callers appending rows cannot mutate shared cached Markdown output.
- Added an AskTool test that renders calls and results twice to verify repeated renders remain stable and do not duplicate option labels.
---
 packages/coding-agent/test/tools/ask.test.ts | 51 ++++++++++++++++++++
 packages/tui/CHANGELOG.md                    |  1 +
 packages/tui/src/components/markdown.ts      | 26 +++++-----
 3 files changed, 66 insertions(+), 12 deletions(-)

diff --git a/packages/coding-agent/test/tools/ask.test.ts b/packages/coding-agent/test/tools/ask.test.ts
index e189676d6..560839b5e 100644
--- a/packages/coding-agent/test/tools/ask.test.ts
+++ b/packages/coding-agent/test/tools/ask.test.ts
@@ -1153,6 +1153,57 @@ describe("AskTool option markers", () => {
 		expect(text).not.toContain(theme!.radio.unselected);
 	});
 
+	it("keeps option rows stable across repeated renders", async () => {
+		const theme = await getThemeByName("dark");
+		expect(theme).toBeDefined();
+		const options = [
+			{ label: "TypeScript" },
+			{ label: "Rust" },
+			{ label: "Python" },
+			{ label: "Go" },
+			{ label: "C" },
+			{ label: "C++" },
+			{ label: "Zig" },
+			{ label: "Java" },
+			{ label: "Swift" },
+			{ label: "Haskell" },
+		];
+		const renderedCall = askToolRenderer.renderCall(
+			{ questions: [{ id: "fav_lang", question: "Which programming language?", options }] },
+			{ expanded: true, isPartial: true },
+			theme!,
+		);
+
+		const firstCall = stripAnsi(renderedCall.render(120).join("\n"));
+		const secondCall = stripAnsi(renderedCall.render(120).join("\n"));
+		expect(secondCall).toBe(firstCall);
+		expect(secondCall.match(/TypeScript/g)?.length).toBe(1);
+		expect(secondCall.match(/Haskell/g)?.length).toBe(1);
+
+		const renderedResult = askToolRenderer.renderResult(
+			{
+				content: [{ type: "text", text: "" }],
+				details: {
+					results: [
+						{
+							id: "fav_lang",
+							question: "Which programming language?",
+							options: options.map(option => option.label),
+							multi: false,
+							selectedOptions: ["Python"],
+						},
+					],
+				},
+			},
+			{ expanded: true, isPartial: false },
+			theme!,
+		);
+		const firstResult = stripAnsi(renderedResult.render(120).join("\n"));
+		const secondResult = stripAnsi(renderedResult.render(120).join("\n"));
+		expect(secondResult).toBe(firstResult);
+		expect(secondResult.match(/TypeScript/g)?.length).toBe(1);
+		expect(secondResult.match(/Haskell/g)?.length).toBe(1);
+	});
 	it("renders single-choice result selection with a filled radio marker", async () => {
 		const theme = await getThemeByName("dark");
 		expect(theme).toBeDefined();
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index bbcc401e3..e005f97ed 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -25,6 +25,7 @@
 
 ### Fixed
 
+- Fixed `Markdown.render()` cache hits returning the cache's mutable backing array, which let callers that append extra rows corrupt cached Markdown and duplicate those rows on every redraw.
 - Fixed terminal stop and restore cleanup to disable enhanced paste mode so it does not remain enabled after shutdown
 - Removed the per-frame line-fit `Map` cache from the render timer path to avoid forcing JSC rope-string hashing during scheduled viewport repaints.
 - Fixed `visibleWidth()` so terminal column measurements for ANSI and OSC text now match the native truncation/wrapping helpers, including OSC 66 text-sizing spans being counted at their scaled payload width
diff --git a/packages/tui/src/components/markdown.ts b/packages/tui/src/components/markdown.ts
index c4fbc8772..db96fd2ed 100644
--- a/packages/tui/src/components/markdown.ts
+++ b/packages/tui/src/components/markdown.ts
@@ -58,7 +58,8 @@ markdownParser.setOptions({
 // (Rust FFI) work for content/layout combinations already seen this session.
 
 const RENDER_CACHE_MAX = 256; // sane cap: ~256 distinct message × width combos
-const renderCache = new LRUCache<string, string[]>({ max: RENDER_CACHE_MAX });
+const EMPTY_RENDER_LINES: readonly string[] = [];
+const renderCache = new LRUCache<string, readonly string[]>({ max: RENDER_CACHE_MAX });
 
 /** Drop all L2 cache entries. Call on theme change to prevent stale styled output. */
 export function clearRenderCache(): void {
@@ -288,10 +289,11 @@ export class Markdown implements Component {
 	/** Number of spaces used to indent code block content. */
 	#codeBlockIndent: number;
 
-	// Cache for rendered output
+	// Cache for rendered output. Cached arrays are internal snapshots; render()
+	// returns caller-owned arrays because several renderers append surrounding rows.
 	#cachedText?: string;
 	#cachedWidth?: number;
-	#cachedLines?: string[];
+	#cachedLines?: readonly string[];
 
 	constructor(
 		text: string,
@@ -324,7 +326,7 @@ export class Markdown implements Component {
 		// L1: per-instance cache — fastest path for repeated renders of the same
 		// instance at the same width (e.g. resize debounce, repeated redraws).
 		if (this.#cachedLines && this.#cachedText === this.#text && this.#cachedWidth === width) {
-			return this.#cachedLines;
+			return this.#cachedLines.slice();
 		}
 
 		// Calculate available width for content (subtract horizontal padding)
@@ -332,12 +334,10 @@ export class Markdown implements Component {
 
 		// Don't render anything if there's no actual text
 		if (!this.#text || this.#text.trim() === "") {
-			const result: string[] = [];
-			// Update per-instance cache
 			this.#cachedText = this.#text;
 			this.#cachedWidth = width;
-			this.#cachedLines = result;
-			return result;
+			this.#cachedLines = EMPTY_RENDER_LINES;
+			return [];
 		}
 
 		// Replace tabs with 3 spaces for consistent rendering
@@ -364,7 +364,7 @@ export class Markdown implements Component {
 			this.#cachedText = this.#text;
 			this.#cachedWidth = width;
 			this.#cachedLines = cached;
-			return cached;
+			return cached.slice();
 		}
 
 		// Parse markdown to HTML-like tokens
@@ -445,14 +445,16 @@ export class Markdown implements Component {
 		const rawResult = [...emptyLines, ...contentLines, ...emptyLines];
 		const result = rawResult.length > 0 ? rawResult : [""];
 
-		// Update L1 per-instance cache
+		// Update caches with a private snapshot. The returned array remains owned by
+		// the caller, so push/splice by tool renderers cannot poison future redraws.
+		const cachedLines = result.slice();
 		this.#cachedText = this.#text;
 		this.#cachedWidth = width;
-		this.#cachedLines = result;
+		this.#cachedLines = cachedLines;
 
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
-		renderCache.set(cacheKey, result);
+		renderCache.set(cacheKey, cachedLines);
 
 		return result;
 	}

From 4080202911893d10db129af1a627e1a33f4e586b Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:33:53 +0200
Subject: [PATCH 118/181] fix(agent): prevented event-loop stalls during
 oneshot LLM completions

- Added `EventLoopKeepalive` in `instrumentedCompleteSimple` to keep the event loop alive during oneshot completion calls.
- This prevented long-lived completion promises from freezing host spinners in Bun by keeping timer servicing active.
---
 packages/agent/CHANGELOG.md        |  1 +
 packages/agent/src/telemetry.ts    |  8 ++++++++
 packages/tui/test/markdown.test.ts | 25 ++++++++++++++++++++++++-
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/packages/agent/CHANGELOG.md b/packages/agent/CHANGELOG.md
index 7467666d0..821fa9775 100644
--- a/packages/agent/CHANGELOG.md
+++ b/packages/agent/CHANGELOG.md
@@ -16,6 +16,7 @@
 
 - Fixed handling of short-lived API keys so that expired tokens are retried with a refreshed value during 401/usage-limit failures
 - Ensured fallback API key resolution uses the initially configured static `apiKey` when `getApiKey` is present
+- Wrapped oneshot LLM completions (`instrumentedCompleteSimple`: handoff, compaction/branch summaries) in an `EventLoopKeepalive`. These run outside the agent `#runLoop`, so without the keepalive Bun's event loop stopped servicing timers while parked on the completion promise — freezing host spinners (e.g. the `/handoff` loader) until an unrelated terminal resize poked the loop into rendering again.
 
 ## [15.9.5] - 2026-06-05
 
diff --git a/packages/agent/src/telemetry.ts b/packages/agent/src/telemetry.ts
index 5cd99a135..8655ccb6c 100644
--- a/packages/agent/src/telemetry.ts
+++ b/packages/agent/src/telemetry.ts
@@ -50,6 +50,7 @@ import {
 } from "@opentelemetry/api";
 import { AgentRunCollector, type AgentRunCoverage, type AgentRunSummary, type ToolStatus } from "./run-collector";
 import type { AgentTool } from "./types";
+import { EventLoopKeepalive } from "./utils/yield";
 
 /** Default tracer name. Override via {@link AgentTelemetryConfig.tracerName}. */
 export const DEFAULT_TRACER_NAME = "@oh-my-pi/pi-agent-core";
@@ -1629,6 +1630,13 @@ export async function instrumentedCompleteSimple<TApi extends Api>(
 	options: SimpleStreamOptions,
 	span: InstrumentedChatSpanOptions,
 ): Promise<AssistantMessage> {
+	// Oneshot LLM calls (handoff, compaction/branch summaries) run outside the
+	// agent `#runLoop`, which is where the EventLoopKeepalive normally lives.
+	// Without it, Bun's JSC loop stops servicing timers while parked on the
+	// long-lived completion promise, freezing any host spinner (e.g. the
+	// `/handoff` Loader) until an unrelated I/O event (a terminal resize)
+	// pokes the loop. Keep the loop healthy for the duration of the call.
+	using _keepalive = new EventLoopKeepalive();
 	const { telemetry, parent, oneshotKind } = span;
 	const stepNumber = span.stepNumber ?? -1;
 	const reasoning = options.reasoning;
diff --git a/packages/tui/test/markdown.test.ts b/packages/tui/test/markdown.test.ts
index fcba22a74..3d403bdb2 100644
--- a/packages/tui/test/markdown.test.ts
+++ b/packages/tui/test/markdown.test.ts
@@ -1,7 +1,7 @@
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "bun:test";
 import { stripVTControlCharacters } from "node:util";
 import { Chalk } from "chalk";
-import { Markdown, renderInlineMarkdown } from "../src/components/markdown.js";
+import { clearRenderCache, Markdown, renderInlineMarkdown } from "../src/components/markdown.js";
 import { setTerminalTextSizing, TERMINAL } from "../src/terminal-capabilities.js";
 import { type Component, TUI } from "../src/tui.js";
 import { visibleWidth } from "../src/utils.js";
@@ -1240,6 +1240,29 @@ describe("Module-level LRU render cache", () => {
 		// Output must be byte-identical — cache is transparent to callers.
 		expect(lines2).toEqual(lines1);
 	});
+
+	it("returns caller-owned arrays from L1 and L2 cache hits", () => {
+		clearRenderCache();
+		const text = "Cache mutability sentinel";
+		const width = 80;
+		const markdown = new Markdown(text, 0, 0, defaultMarkdownTheme);
+
+		const first = markdown.render(width);
+		const expected = [...first];
+		first.push("mutated first render");
+
+		const l1Hit = markdown.render(width);
+		expect(l1Hit).toEqual(expected);
+		l1Hit.push("mutated L1 hit");
+		expect(markdown.render(width)).toEqual(expected);
+
+		const l2Markdown = new Markdown(text, 0, 0, defaultMarkdownTheme);
+		const l2Hit = l2Markdown.render(width);
+		expect(l2Hit).toEqual(expected);
+		l2Hit.push("mutated L2 hit");
+		expect(l2Markdown.render(width)).toEqual(expected);
+		expect(new Markdown(text, 0, 0, defaultMarkdownTheme).render(width)).toEqual(expected);
+	});
 });
 
 describe("OSC 66 text-sizing headings", () => {

From e78352abc7304277061d1397f549d1ab65d30e42 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:36:08 +0200
Subject: [PATCH 119/181] fix(tui): fixed live viewport anchoring during
 repaint updates

- Replaced the repaint viewport clamp with strict bottom anchoring at lines.length - height.
- Removed the anti-duplication clamping path that could persist off-tail #viewportTopRow values between frames.
- Kept native scrollback cleanup to the existing dirty checkpoint mechanism for stale committed prefixes.
---
 packages/tui/src/tui.ts | 38 ++++++++++++++++++++------------------
 1 file changed, 20 insertions(+), 18 deletions(-)

diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 53b673c14..1deb1ec50 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -2631,24 +2631,26 @@ export class TUI extends Container {
 		cursorPos: { row: number; col: number } | null,
 	): void {
 		this.#fullRedrawCount += 1;
-		const naturalViewportTop = Math.max(0, lines.length - height);
-		// Anti-duplication clamp. Never repaint rows that are byte-identical to what
-		// is already committed to native scrollback above the viewport — a second
-		// copy in the active grid duplicates them once the user scrolls up (the
-		// "transcript stacked on itself" / home-screen-reappears bug). The committed
-		// prefix is `#scrollbackHighWater` rows; the new frame still matches it up to
-		// the first changed row, so the genuinely committed-AND-unchanged prefix is
-		// `min(firstChanged, #scrollbackHighWater)`. Anchor at/below that. When the
-		// change starts inside the committed region (content diverged at/above it,
-		// e.g. a tool rewrite or a full transcript reset) the bound collapses and we
-		// paint the bottom-anchored live tail as before (#previousLines is still the
-		// pre-commit frame here, so this prefix diff is against the old frame).
-		let firstChanged = 0;
-		const commonLen = Math.min(lines.length, this.#previousLines.length);
-		while (firstChanged < commonLen && lines[firstChanged] === this.#previousLines[firstChanged]) {
-			firstChanged++;
-		}
-		const viewportTop = Math.max(naturalViewportTop, Math.min(firstChanged, this.#scrollbackHighWater));
+		// A viewport repaint is a strictly in-place rewrite of the live window: it
+		// homes to the screen top and writes exactly `height` rows, so it must stay
+		// bottom-anchored at `lines.length - height`. Anchoring anywhere else pushes
+		// the live tail off the screen bottom (blank rows below the content) AND — far
+		// worse — persists the off-tail anchor into `#viewportTopRow` via `#commit`.
+		// A later frame then reads that inflated `prevViewportTop`, mis-classifies an
+		// ordinary tail change as an offscreen edit (`diff.firstChanged <
+		// prevViewportTop`), and re-routes into an append/scroll path that re-commits
+		// the same frame into native scrollback every tick — the self-driven "options
+		// drawn again and again" spam.
+		//
+		// This repaint cannot un-commit rows already in native scrollback (no safe ED3
+		// on ED3-risk hosts), so a shrink that re-exposes a committed prefix leaves a
+		// stale copy above the viewport. That is the accepted deferred state: the live
+		// window stays correct here, `#nativeScrollbackDirty` stays set, and the next
+		// at-tail checkpoint (`refreshNativeScrollbackIfDirty`) reconciles history with
+		// a clean clear+replay. Hiding the live tail to paper over the stale history —
+		// the previous "anti-duplication clamp" — traded a transient, off-screen
+		// history artifact for a broken live viewport, which is the worse defect.
+		const viewportTop = Math.max(0, lines.length - height);
 		// Each visible screen row, bottom-anchored, blank past content.
 		const visible: string[] = new Array(height);
 		for (let screenRow = 0; screenRow < height; screenRow++) {

From c8217a1325834607895ed95c31f84a9740929646 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:37:20 +0200
Subject: [PATCH 120/181] test(tui): added Markdown.render cache mutation
 regression tests

- Added tests confirming `Markdown.render` returns caller-owned lines so per-instance mutations do not change the next render output.
- Added coverage that mutating one instance's render output cannot leak injected lines into another instance via shared cache reuse.
- Added a repeated mutate-then-render test to ensure no line accumulation across multiple render cycles.
---
 packages/tui/test/markdown.test.ts | 40 ++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/packages/tui/test/markdown.test.ts b/packages/tui/test/markdown.test.ts
index 3d403bdb2..0bd139fd2 100644
--- a/packages/tui/test/markdown.test.ts
+++ b/packages/tui/test/markdown.test.ts
@@ -1331,3 +1331,43 @@ describe("OSC 66 text-sizing headings", () => {
 		expect(lines.some(line => stripVTControlCharacters(line).includes("Sub"))).toBe(true);
 	});
 });
+
+describe("Markdown.render cache ownership", () => {
+	// Regression: the ask tool renderer did `md(question).push(...optionLines)`,
+	// mutating Markdown's cached array in place. render() handed out the live L1
+	// (per-instance) and L2 (module-level, shared across instances) cache arrays,
+	// so every redraw re-pushed onto the same growing array (+N lines/frame). That
+	// inflated the chat block unboundedly and cascaded into native-scrollback
+	// duplication. render() must return a caller-owned copy so push/splice can
+	// never poison the cache or a future render.
+	afterEach(() => clearRenderCache());
+
+	it("does not let a caller's mutation grow the next render (per-instance cache)", () => {
+		const md = new Markdown("Question text", 1, 0, defaultMarkdownTheme);
+		const baseline = md.render(40).length;
+		md.render(40).push("INJECTED-A", "INJECTED-B");
+		const after = md.render(40);
+		expect(after.length).toBe(baseline);
+		expect(after.some(line => line.includes("INJECTED"))).toBe(false);
+	});
+
+	it("does not let one instance's mutation leak into another via the shared L2 cache", () => {
+		const a = new Markdown("Shared markdown body", 1, 0, defaultMarkdownTheme);
+		const b = new Markdown("Shared markdown body", 1, 0, defaultMarkdownTheme);
+		const baseline = b.render(40).length;
+		// `a` populates L2; mutating its result must not corrupt the entry `b` reads.
+		a.render(40).push("LEAKED-1", "LEAKED-2", "LEAKED-3");
+		const fromB = b.render(40);
+		expect(fromB.length).toBe(baseline);
+		expect(fromB.some(line => line.includes("LEAKED"))).toBe(false);
+	});
+
+	it("stays stable across many mutate-then-render cycles (no accumulation)", () => {
+		const md = new Markdown("Pick one", 1, 0, defaultMarkdownTheme);
+		const baseline = md.render(40).length;
+		for (let i = 0; i < 25; i++) {
+			md.render(40).push(`OPT-${i}`);
+		}
+		expect(md.render(40).length).toBe(baseline);
+	});
+});

From becc44ccefdbcb4c4a27fd497be3ff84c324c6ad Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:42:39 +0200
Subject: [PATCH 121/181] fix(tui): fixed startup scrollback clearing and ED3
 streaming replay duplication

- Added a clear-initial-terminal-history flag to interactive mode initialization and passed it from cold-launch startup.
- Extended TUI.start to accept clearScrollback and clear native scrollback on initial full paint for non-multiplexer sessions.
- Preserved ED3 streaming scrollback accounting during capped streaming frames and added tests to prevent committed prefix duplication across terminal history rewrites.
---
 packages/coding-agent/CHANGELOG.md            |  1 +
 packages/coding-agent/src/main.ts             | 16 ++--
 .../src/modes/interactive-mode.ts             |  5 +-
 packages/coding-agent/src/modes/types.ts      |  1 +
 packages/tui/CHANGELOG.md                     |  2 +
 packages/tui/src/tui.ts                       | 29 +++++--
 packages/tui/test/overlay-scroll.test.ts      | 31 +++++++-
 .../test/streaming-scrollback-defer.test.ts   | 42 +++++++++++
 .../viewport-repaint-no-duplicate.test.ts     | 75 -------------------
 9 files changed, 109 insertions(+), 93 deletions(-)
 delete mode 100644 packages/tui/test/viewport-repaint-no-duplicate.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 7aa63de66..f7b945046 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -38,6 +38,7 @@
 
 ### Fixed
 
+- Fixed cold `omp` launch to clear native terminal history on the first paint, avoiding a once-per-launch duplicate welcome/transcript copy before the normal session replay.
 - Fixed plan approval resolution so `resolve` with `action: "apply"` can still find the plan file when `extra.title` is missing or stale by falling back to the current plan path and most-recent local plan artifacts
 - Fixed the search-family tool magnifier glyph (`find`, `search`, `ast_grep`, `search_tool_bm25`) to use the `accent` title color instead of `success` green, so the icon matches the tool title in the status header instead of standing out
 - Fixed TTSR stream interrupts to pass the matched rule name through the abort reason, so aborted in-flight tool placeholders say why they were stopped instead of `Request was aborted`.
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index a0f7fa1a0..8d4d30b46 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -278,7 +278,10 @@ async function runInteractiveMode(
 			})
 		: [];
 
-	await mode.init({ suppressWelcomeIntro: resuming || setupScenes.length > 0 });
+	await mode.init({
+		suppressWelcomeIntro: resuming || setupScenes.length > 0,
+		clearInitialTerminalHistory: true,
+	});
 
 	if (setupWizard && setupScenes.length > 0) {
 		await setupWizard.runSetupWizard(mode, setupScenes);
@@ -295,12 +298,11 @@ async function runInteractiveMode(
 		})
 		.catch(() => {});
 
-	// Cold-launch cleanup: wipe the terminal scrollback before painting the
-	// resumed/new transcript. The TUI's initial paint deliberately preserves
-	// native scrollback (prior shell content), but on `omp`/`omp -c` that leaves
-	// the previous run's welcome + transcript stacked above the fresh one. Every
-	// in-process session load already clears via `clearTerminalHistory`; the cold
-	// launch is the lone path that did not.
+	// Cold-launch cleanup: the first paint already clears native history, and this
+	// replay replaces the welcome/startup frame with the resumed/new transcript.
+	// Every in-process session load also uses `clearTerminalHistory`; cold launch
+	// follows the same clean-cutover path instead of preserving a previous run's
+	// transcript above the fresh one.
 	mode.renderInitialMessages(undefined, { preserveExistingChat: true, clearTerminalHistory: true });
 
 	for (const notify of notifs) {
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index f5f96f342..56b763d28 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -600,8 +600,9 @@ export class InteractiveMode implements InteractiveModeContext {
 		// Load initial todos
 		await this.#loadTodoList();
 
-		// Start the UI
-		this.ui.start();
+		// Start the UI. Cold `omp` launch opts into clearing on the first paint so
+		// the initial welcome frame does not append over the previous run's scrollback.
+		this.ui.start({ clearScrollback: options.clearInitialTerminalHistory === true });
 		pushTerminalTitle();
 		setSessionTerminalTitle(this.sessionManager.getSessionName(), this.sessionManager.getCwd());
 		this.updateEditorBorderColor();
diff --git a/packages/coding-agent/src/modes/types.ts b/packages/coding-agent/src/modes/types.ts
index be982e691..59fdce436 100644
--- a/packages/coding-agent/src/modes/types.ts
+++ b/packages/coding-agent/src/modes/types.ts
@@ -63,6 +63,7 @@ export type TodoPhase = {
 
 export interface InteractiveModeInitOptions {
 	suppressWelcomeIntro?: boolean;
+	clearInitialTerminalHistory?: boolean;
 }
 
 export type InteractiveSelectorDialogOptions = ExtensionUIDialogOptions & Pick<HookSelectorOptions, "disabledIndices">;
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index e005f97ed..bce34b5b8 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -26,6 +26,8 @@
 ### Fixed
 
 - Fixed `Markdown.render()` cache hits returning the cache's mutable backing array, which let callers that append extra rows corrupt cached Markdown and duplicate those rows on every redraw.
+- Fixed first-paint full replays for callers that intentionally replace terminal history by allowing `TUI.start({ clearScrollback: true })`, so they do not briefly append an entire initial frame before the first clean replay.
+- Fixed ED3-risk streaming cap accounting to preserve the native scrollback high-water mark for rows that were already physically committed before transient frames were viewport-capped.
 - Fixed terminal stop and restore cleanup to disable enhanced paste mode so it does not remain enabled after shutdown
 - Removed the per-frame line-fit `Map` cache from the render timer path to avoid forcing JSC rope-string hashing during scheduled viewport repaints.
 - Fixed `visibleWidth()` so terminal column measurements for ANSI and OSC text now match the native truncation/wrapping helpers, including OSC 66 text-sizing spans being counted at their scaled payload width
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 1deb1ec50..a2184580b 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -92,6 +92,11 @@ export interface TUIOptions {
 	renderScheduler?: RenderScheduler;
 }
 
+export interface TUIStartOptions {
+	/** Clear saved native scrollback before the first paint. */
+	clearScrollback?: boolean;
+}
+
 const DEFAULT_RENDER_SCHEDULER: RenderScheduler = {
 	now: () => performance.now(),
 	scheduleImmediate: callback => {
@@ -785,7 +790,7 @@ export class TUI extends Container {
 		for (const overlay of this.overlayStack) overlay.component.invalidate?.();
 	}
 
-	start(): void {
+	start(options?: TUIStartOptions): void {
 		this.#stopped = false;
 		// A DECRQM report for mode 2026 is authoritative: enable synchronized
 		// output when the terminal reports support (upgrading conservatively
@@ -818,7 +823,7 @@ export class TUI extends Container {
 		this.terminal.hideCursor();
 		this.#querySixelSupport();
 		this.#queryCellSize();
-		this.requestRender(true);
+		this.requestRender(true, { clearScrollback: options?.clearScrollback === true });
 	}
 
 	addStartListener(listener: StartListener): () => void {
@@ -1701,9 +1706,13 @@ export class TUI extends Container {
 				// multiplexer needs — and the `liveRegionPinned` planner above
 				// keeps the actively-mutating live tail out of pane history while
 				// committing only the sealed prefix (issue #1974).
+				// Do not lower #scrollbackHighWater here. The viewport repaint below
+				// avoids committing new transient rows, but rows committed by earlier
+				// full/diff paints are still physically present in native scrollback and
+				// must remain in the shrink/de-dup accounting until an ED3 checkpoint
+				// clears them.
 				this.#markNativeScrollbackDirty();
 				this.#streamingHighWater = Math.max(this.#streamingHighWater, lines.length);
-				this.#scrollbackHighWater = 0;
 				lines = lines.slice(-height);
 				intent = { kind: "viewportRepaint" };
 			} else {
@@ -1756,7 +1765,13 @@ export class TUI extends Container {
 						this.#nativeScrollbackCommitSafeEnd,
 					);
 				} else {
-					this.#emitFullPaint(lines, width, height, cursorPos, { clearViewport: true, clearScrollback: false });
+					// Start from a clean terminal: clear native scrollback too (off a
+					// multiplexer, where ED3 is a no-op and would only duplicate the pane
+					// history). Prior shell content is intentionally not preserved.
+					this.#emitFullPaint(lines, width, height, cursorPos, {
+						clearViewport: true,
+						clearScrollback: !isMultiplexerSession(),
+					});
 				}
 				this.#hasEverRendered = true;
 				return;
@@ -1870,9 +1885,9 @@ export class TUI extends Container {
 		// that waits for the user's first keystroke.
 		if (this.#clearScrollbackOnNextRender) return { kind: "sessionReplace" };
 
-		// Initial paint after start(): scrollback must keep its prior shell
-		// content, but the viewport must be cleared so stale rows do not bleed
-		// into the new UI.
+		// Initial paint after start(): clear the viewport AND prior shell scrollback
+		// so the session starts from a clean terminal. (We intentionally do not
+		// preserve pre-omp shell history — see the `initial` emit below.)
 		if (!this.#hasEverRendered) return { kind: "initial" };
 
 		const forceViewportRepaint = this.#forceViewportRepaintOnNextRender;
diff --git a/packages/tui/test/overlay-scroll.test.ts b/packages/tui/test/overlay-scroll.test.ts
index dfdd5d7dc..0f362f58d 100644
--- a/packages/tui/test/overlay-scroll.test.ts
+++ b/packages/tui/test/overlay-scroll.test.ts
@@ -131,7 +131,7 @@ describe("TUI overlays", () => {
 		expect(term.getScrollBuffer().length).toBeLessThan(200);
 	});
 
-	it("clears stale viewport content on launch without clearing shell scrollback", async () => {
+	it("clears stale viewport content on launch", async () => {
 		const term = new VirtualTerminal(40, 4);
 		term.write("shell-0\r\nshell-1\r\nshell-2\r\nshell-3\r\nshell-4\r\n");
 		await flushRender(term);
@@ -143,7 +143,34 @@ describe("TUI overlays", () => {
 			await flushRender(term);
 
 			expect(term.getViewport().join("\n").includes("shell-")).toBeFalsy();
-			expect(term.getScrollBuffer().join("\n").includes("shell-0")).toBeTruthy();
+		} finally {
+			tui.stop();
+		}
+	});
+
+	it("can clear saved native scrollback on the first paint", async () => {
+		const term = new VirtualTerminal(40, 4);
+		term.write("shell-0\r\nshell-1\r\nshell-2\r\nshell-3\r\nshell-4\r\n");
+		await flushRender(term);
+		const writes: string[] = [];
+		const realWrite = term.write.bind(term);
+		(term as unknown as { write: (s: string) => void }).write = (data: string) => {
+			writes.push(data);
+			realWrite(data);
+		};
+
+		const tui = new TUI(term);
+		tui.addChild(new MutableContentComponent(buildRows(8)));
+		try {
+			tui.start({ clearScrollback: true });
+			await flushRender(term);
+
+			const output = writes.join("");
+			const scrollback = term.getScrollBuffer().join("\n");
+			expect(output).toContain("\x1b[3J");
+			expect(scrollback.includes("shell-")).toBeFalsy();
+			expect(scrollback.includes("row-0")).toBeTruthy();
+			expect(scrollback.includes("row-7")).toBeTruthy();
 		} finally {
 			tui.stop();
 		}
diff --git a/packages/tui/test/streaming-scrollback-defer.test.ts b/packages/tui/test/streaming-scrollback-defer.test.ts
index 84919cd63..18e74269b 100644
--- a/packages/tui/test/streaming-scrollback-defer.test.ts
+++ b/packages/tui/test/streaming-scrollback-defer.test.ts
@@ -372,6 +372,48 @@ describe("streaming scrollback defer", () => {
 		});
 	});
 
+	it("keeps committed prefix accounting after a capped streaming frame", async () => {
+		if (process.platform === "win32") return;
+		await withTerminalRisk(true, async () => {
+			const term = new VirtualTerminal(24, 4);
+			overrideProbe(term, undefined);
+			const tui = new TUI(term);
+			const sealed = new LineList(rows("base-", 12));
+
+			try {
+				tui.addChild(sealed);
+				tui.start();
+				await settle(term);
+
+				const writes = capture(term);
+				tui.setEagerNativeScrollbackRebuild(true);
+
+				// No live-region marker yet: ED3-risk streaming caps this transient
+				// frame to the viewport. The already-committed base-0..base-7 rows
+				// remain physically in native scrollback and must stay accounted.
+				sealed.setLines([...rows("base-", 12), ...rows("transient-", 30)]);
+				tui.requestRender();
+				await settle(term);
+
+				expect(eraseScrollbackCount(writes)).toBe(0);
+
+				// A later frame introduces a live region after the same sealed prefix.
+				// If the cap zeroed the high-water mark, liveRegionPinned would append
+				// base-0..base-11 again, duplicating base-0..base-7 in native history.
+				const live = new LiveLineList(rows("live-", 20));
+				sealed.setLines(rows("base-", 12));
+				tui.addChild(live);
+				tui.requestRender();
+				await settle(term);
+
+				expect(eraseScrollbackCount(writes)).toBe(0);
+				expect(term.getScrollBuffer().filter(line => line.startsWith("base-"))).toEqual(rows("base-", 12));
+			} finally {
+				tui.stop();
+			}
+		});
+	});
+
 	it("erases mis-wrapped native scrollback on resize even mid-stream on ED3-risk terminals", async () => {
 		if (process.platform === "win32") return;
 		await withTerminalRisk(true, async () => {
diff --git a/packages/tui/test/viewport-repaint-no-duplicate.test.ts b/packages/tui/test/viewport-repaint-no-duplicate.test.ts
deleted file mode 100644
index c89f63e69..000000000
--- a/packages/tui/test/viewport-repaint-no-duplicate.test.ts
+++ /dev/null
@@ -1,75 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { type Component, TERMINAL, TUI } from "@oh-my-pi/pi-tui";
-import { VirtualTerminal } from "./virtual-terminal";
-
-// A non-destructive viewport repaint (the path foreground-tool completion takes on
-// ED3-risk terminals with an unprobeable viewport) must never re-paint rows that
-// are byte-identical to what is already committed to native scrollback above the
-// viewport. Doing so stacks a second copy of the committed prefix into the active
-// grid — the "transcript on top of itself" / header-reappears duplication the user
-// hit. The renderer clamps the repaint anchor to the committed-and-unchanged
-// prefix (`min(firstChanged, #scrollbackHighWater)`).
-
-class LineList implements Component {
-	#lines: string[];
-	constructor(lines: string[]) {
-		this.#lines = [...lines];
-	}
-	invalidate(): void {}
-	render(width: number): string[] {
-		return this.#lines.map(line => line.slice(0, width));
-	}
-	setLines(lines: string[]): void {
-		this.#lines = [...lines];
-	}
-}
-
-async function settle(term: VirtualTerminal): Promise<void> {
-	const tick = Promise.withResolvers<void>();
-	process.nextTick(tick.resolve);
-	await tick.promise;
-	await Bun.sleep(20);
-	await term.flush();
-}
-
-function overrideProbe(term: VirtualTerminal, answer: boolean | undefined): void {
-	(term as unknown as { isNativeViewportAtBottom: () => boolean | undefined }).isNativeViewportAtBottom = () => answer;
-}
-
-const count = (lines: string[], needle: string): number => lines.filter(line => line.includes(needle)).length;
-
-describe("viewport repaint committed-prefix clamp", () => {
-	it("does not duplicate a committed header when the live block collapses", async () => {
-		const savedRisk = TERMINAL.eagerEraseScrollbackRisk;
-		TERMINAL.eagerEraseScrollbackRisk = true;
-		const term = new VirtualTerminal(40, 10);
-		overrideProbe(term, undefined);
-		const tui = new TUI(term);
-		// Row 0 is a stable header that scrolls into native scrollback; the rest is a
-		// live block (a tall streaming tool preview).
-		const tall = ["PINNED-HEADER", ...Array.from({ length: 24 }, (_v, i) => `live-${i}`)];
-		const component = new LineList(tall);
-		tui.addChild(component);
-		try {
-			tui.start();
-			await settle(term);
-			// Foreground streaming is active; the tool then completes, collapsing the
-			// live block to a short settled result while the header stays unchanged.
-			tui.setEagerNativeScrollbackRebuild(true);
-			component.setLines(["PINNED-HEADER", ...Array.from({ length: 7 }, (_v, i) => `settled-${i}`)]);
-			tui.requestRender();
-			await settle(term);
-
-			const scrollback = term.getScrollBuffer();
-			const viewport = term.getViewport();
-			const combined = [...scrollback, ...viewport];
-			// The committed header exists exactly once across saved history + viewport.
-			expect(count(combined, "PINNED-HEADER")).toBe(1);
-			// The settled result is visible.
-			expect(count(viewport, "settled-6")).toBe(1);
-		} finally {
-			tui.stop();
-			TERMINAL.eagerEraseScrollbackRisk = savedRisk;
-		}
-	});
-});

From 76af35dcd69e6aa823f7cb3657600628e519999b Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:54:50 +0200
Subject: [PATCH 122/181] fix(tui): preserved TUI initial scrollback unless
 clear was requested

- Updated the initial render intent to carry a `clearScrollback` flag.
- Adjusted first-frame rendering logic to preserve existing scrollback by default and clear only when requested.
- Added `resolver` stubs to coding-agent and web-search test registries for interface compatibility.
---
 .../src/eval/__tests__/llm-bridge.test.ts     |  1 +
 .../test/input-controller-escape.test.ts      |  2 +-
 .../coding-agent/test/issue-846-repro.test.ts |  2 ++
 .../test/memories-runtime.test.ts             |  1 +
 .../role-thinking-helper-propagation.test.ts  |  2 ++
 .../test/tiny-title-generator.test.ts         |  1 +
 .../test/web/search/abort-and-timeout.test.ts |  1 +
 .../test/web/search/tavily.test.ts            |  1 +
 packages/tui/src/tui.ts                       | 25 ++++++++-----------
 9 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts b/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
index 7ae317358..bcd3fc444 100644
--- a/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
+++ b/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
@@ -57,6 +57,7 @@ function makeSession(opts: SessionOptions = {}): ToolSession {
 	const modelRegistry = {
 		getAvailable: () => opts.available ?? [SMOL, DEFAULT, SLOW],
 		getApiKey: async () => (opts.apiKey === undefined ? "test-key" : opts.apiKey),
+		resolver: vi.fn(() => async () => (opts.apiKey === undefined ? "test-key" : opts.apiKey)),
 	} as unknown as ModelRegistry;
 	return {
 		settings,
diff --git a/packages/coding-agent/test/input-controller-escape.test.ts b/packages/coding-agent/test/input-controller-escape.test.ts
index 001ff60ff..b04750571 100644
--- a/packages/coding-agent/test/input-controller-escape.test.ts
+++ b/packages/coding-agent/test/input-controller-escape.test.ts
@@ -113,7 +113,7 @@ function createContext(): {
 
 	ctx = {
 		editor: editor as unknown as InteractiveModeContext["editor"],
-		ui: { requestRender } as unknown as InteractiveModeContext["ui"],
+		ui: { requestRender, addInputListener: vi.fn(), addStartListener: vi.fn() } as unknown as InteractiveModeContext["ui"],
 		loadingAnimation: undefined,
 		autoCompactionLoader: undefined,
 		retryLoader: undefined,
diff --git a/packages/coding-agent/test/issue-846-repro.test.ts b/packages/coding-agent/test/issue-846-repro.test.ts
index 13b3e1362..a1762a8d5 100644
--- a/packages/coding-agent/test/issue-846-repro.test.ts
+++ b/packages/coding-agent/test/issue-846-repro.test.ts
@@ -37,6 +37,7 @@ interface ModelRegistryLike {
 	find: (...args: unknown[]) => Model;
 	getAll: () => Model[];
 	getApiKey: (...args: unknown[]) => Promise<string>;
+	resolver: (...args: unknown[]) => () => Promise<string>;
 }
 
 const createdDirs = new Set<string>();
@@ -62,6 +63,7 @@ function createModelRegistry(model: Model): ModelRegistryLike {
 		find: vi.fn(() => model),
 		getAll: vi.fn(() => [model]),
 		getApiKey: vi.fn(async () => "test-api-key"),
+		resolver: vi.fn(() => async () => "test-api-key"),
 	};
 }
 
diff --git a/packages/coding-agent/test/memories-runtime.test.ts b/packages/coding-agent/test/memories-runtime.test.ts
index 394daebbb..ba2429d73 100644
--- a/packages/coding-agent/test/memories-runtime.test.ts
+++ b/packages/coding-agent/test/memories-runtime.test.ts
@@ -46,6 +46,7 @@ function createModelRegistry(model: Model): any {
 		find: vi.fn(() => model),
 		getAll: vi.fn(() => [model]),
 		getApiKey: vi.fn(async () => "test-api-key"),
+		resolver: vi.fn(() => async () => "test-api-key"),
 	};
 }
 
diff --git a/packages/coding-agent/test/role-thinking-helper-propagation.test.ts b/packages/coding-agent/test/role-thinking-helper-propagation.test.ts
index 37e4b7b54..f094340bc 100644
--- a/packages/coding-agent/test/role-thinking-helper-propagation.test.ts
+++ b/packages/coding-agent/test/role-thinking-helper-propagation.test.ts
@@ -43,6 +43,7 @@ describe("role thinking helper propagation", () => {
 		const registry = {
 			getAvailable: () => [model],
 			getApiKey: async () => "test-key",
+			resolver: vi.fn(() => async () => "test-key"),
 		};
 		const completeSimpleMock = vi.spyOn(ai, "completeSimple").mockResolvedValue({
 			stopReason: "end_turn",
@@ -66,6 +67,7 @@ describe("role thinking helper propagation", () => {
 		const registry = {
 			getAvailable: () => [model],
 			getApiKey: async () => "test-key",
+			resolver: vi.fn(() => async () => "test-key"),
 		};
 		const completeSimpleMock = vi.spyOn(ai, "completeSimple").mockResolvedValue({
 			stopReason: "end_turn",
diff --git a/packages/coding-agent/test/tiny-title-generator.test.ts b/packages/coding-agent/test/tiny-title-generator.test.ts
index c744ca940..c6ce8c636 100644
--- a/packages/coding-agent/test/tiny-title-generator.test.ts
+++ b/packages/coding-agent/test/tiny-title-generator.test.ts
@@ -48,6 +48,7 @@ function createRegistry(model: Model<Api>) {
 	return {
 		getAvailable: () => [model],
 		getApiKey: async () => "test-key",
+		resolver: vi.fn(() => async () => "test-key"),
 	} as never;
 }
 
diff --git a/packages/coding-agent/test/web/search/abort-and-timeout.test.ts b/packages/coding-agent/test/web/search/abort-and-timeout.test.ts
index 9a347d196..2e82e4d27 100644
--- a/packages/coding-agent/test/web/search/abort-and-timeout.test.ts
+++ b/packages/coding-agent/test/web/search/abort-and-timeout.test.ts
@@ -123,6 +123,7 @@ describe("Anthropic provider hard-timeout wiring", () => {
 			systemPrompt: "",
 			authStorage: {
 				getApiKey: async () => "sk-fallback",
+				resolver: vi.fn(() => async () => "sk-fallback"),
 			} as unknown as AuthStorage,
 		});
 
diff --git a/packages/coding-agent/test/web/search/tavily.test.ts b/packages/coding-agent/test/web/search/tavily.test.ts
index 689a0a495..8eb7d2e7a 100644
--- a/packages/coding-agent/test/web/search/tavily.test.ts
+++ b/packages/coding-agent/test/web/search/tavily.test.ts
@@ -57,6 +57,7 @@ describe("Tavily searchTavily request shape (integration)", () => {
 		async getApiKey() {
 			return process.env.TAVILY_API_KEY ?? undefined;
 		},
+		resolver: vi.fn(() => async () => process.env.TAVILY_API_KEY ?? undefined),
 		hasAuth() {
 			return Boolean(process.env.TAVILY_API_KEY);
 		},
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index a2184580b..a2c9834c5 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -421,7 +421,7 @@ export class Container implements Component {
  */
 type RenderIntent =
 	| { kind: "noop" }
-	| { kind: "initial" }
+	| { kind: "initial"; clearScrollback: boolean }
 	| { kind: "sessionReplace" }
 	| { kind: "historyRebuild" }
 	| { kind: "overlayRebuild" }
@@ -1750,6 +1750,7 @@ export class TUI extends Container {
 				if (
 					this.#eagerNativeScrollbackRebuild &&
 					eagerEraseScrollbackRisk &&
+					!intent.clearScrollback &&
 					!allowUnknownViewportMutation &&
 					liveRegionStart !== undefined &&
 					liveRegionStart < lines.length &&
@@ -1765,14 +1766,12 @@ export class TUI extends Container {
 						this.#nativeScrollbackCommitSafeEnd,
 					);
 				} else {
-					// Start from a clean terminal: clear native scrollback too (off a
-					// multiplexer, where ED3 is a no-op and would only duplicate the pane
-					// history). Prior shell content is intentionally not preserved.
 					this.#emitFullPaint(lines, width, height, cursorPos, {
 						clearViewport: true,
-						clearScrollback: !isMultiplexerSession(),
+						clearScrollback: intent.clearScrollback && !isMultiplexerSession(),
 					});
 				}
+				this.#clearScrollbackOnNextRender = false;
 				this.#hasEverRendered = true;
 				return;
 			}
@@ -1878,17 +1877,13 @@ export class TUI extends Container {
 		liveRegionStart: number | undefined,
 		commitSafeEnd: number | undefined,
 	): RenderIntent {
-		// A forced scrollback wipe can be queued before start()'s initial paint runs
-		// (cold `omp --resume` does this while replacing the welcome frame with the
-		// restored transcript). Honor it before the normal initial-preserve path so
-		// the first committed frame is the clean session replay, not a deferred wipe
-		// that waits for the user's first keystroke.
-		if (this.#clearScrollbackOnNextRender) return { kind: "sessionReplace" };
+		// Initial paint after start(): preserve prior shell scrollback by default,
+		// but honor callers that are replacing terminal history before any frame is
+		// committed. This keeps the first visible commit clean instead of appending
+		// a tall transcript once and wiping on the next render.
+		if (!this.#hasEverRendered) return { kind: "initial", clearScrollback: this.#clearScrollbackOnNextRender };
 
-		// Initial paint after start(): clear the viewport AND prior shell scrollback
-		// so the session starts from a clean terminal. (We intentionally do not
-		// preserve pre-omp shell history — see the `initial` emit below.)
-		if (!this.#hasEverRendered) return { kind: "initial" };
+		if (this.#clearScrollbackOnNextRender) return { kind: "sessionReplace" };
 
 		const forceViewportRepaint = this.#forceViewportRepaintOnNextRender;
 		const eagerEraseScrollbackRisk = this.#hasEagerEraseScrollbackRisk();

From 0914379f494e536c536a008375a47f0101c26bb8 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 07:55:01 +0200
Subject: [PATCH 123/181] fix(coding-agent): rendered shared task context as
 markdown and froze async block borders

- Updated task call and result rendering to process shared context with the Markdown renderer, so context sections are now displayed with proper Markdown formatting.
- Stopped shimmer animation on pending bash/eval/task blocks once async state is `running`, preventing the committed frame from freezing a transient dark border segment.
- Adjusted rule path display to fall back to a root-relative path when cwd-relative resolution is unavailable.
---
 packages/coding-agent/CHANGELOG.md            |  2 +
 .../src/eval/__tests__/llm-bridge.test.ts     |  4 +-
 .../src/modes/components/tool-execution.ts    | 14 ++++--
 .../coding-agent/src/session/agent-session.ts |  7 ++-
 packages/coding-agent/src/task/render.ts      | 36 ++++++++++----
 packages/coding-agent/src/tools/bash.ts       |  6 ++-
 .../test/agent-session-retry-cap.test.ts      | 15 ++++--
 .../test/task/render-call.test.ts             | 48 ++++++++++++++++++-
 .../test/tools/bash-sixel-render.test.ts      | 34 ++++++++++++-
 .../test/tools/inspect-image.test.ts          |  4 +-
 .../test/tools/read-renderer.test.ts          |  6 +--
 11 files changed, 147 insertions(+), 29 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index f7b945046..17ac573fe 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -38,6 +38,8 @@
 
 ### Fixed
 
+- Fixed the `task` tool shared-context brief rendering raw Markdown headings (`# Goal`, `# Constraints`) inside framed call/result blocks instead of using the normal Markdown renderer.
+- Fixed the animated pending border on `bash`/`eval` blocks leaving a frozen dark "bar" segment behind after a backgrounded command finalized through the async update path. Once a command is auto-backgrounded (`details.async.state === "running"`) the block stays "partial" in the TUI until the async job-manager delivers the final result, but it also gets committed to native scrollback — so a mid-sweep shimmer frame baked a stray darkened border segment into the committed copy. The border now stops animating (and the 60fps redraw loop stops) the moment a block enters the backgrounded state, so the committed frame is a clean static border.
 - Fixed cold `omp` launch to clear native terminal history on the first paint, avoiding a once-per-launch duplicate welcome/transcript copy before the normal session replay.
 - Fixed plan approval resolution so `resolve` with `action: "apply"` can still find the plan file when `extra.title` is missing or stale by falling back to the current plan path and most-recent local plan artifacts
 - Fixed the search-family tool magnifier glyph (`find`, `search`, `ast_grep`, `search_tool_bm25`) to use the `accent` title color instead of `success` green, so the icon matches the tool title in the status header instead of standing out
diff --git a/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts b/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
index bcd3fc444..c8d724e8d 100644
--- a/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
+++ b/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
@@ -57,7 +57,7 @@ function makeSession(opts: SessionOptions = {}): ToolSession {
 	const modelRegistry = {
 		getAvailable: () => opts.available ?? [SMOL, DEFAULT, SLOW],
 		getApiKey: async () => (opts.apiKey === undefined ? "test-key" : opts.apiKey),
-		resolver: vi.fn(() => async () => (opts.apiKey === undefined ? "test-key" : opts.apiKey)),
+		resolver: () => async () => (opts.apiKey === undefined ? "test-key" : opts.apiKey),
 	} as unknown as ModelRegistry;
 	return {
 		settings,
@@ -301,6 +301,7 @@ describe("llm() through eval runtimes", () => {
 			sessionId,
 			sessionFile,
 			toolSession: makeSession(),
+			kernelMode: "per-call",
 		});
 
 		expect(result.exitCode).toBe(0);
@@ -320,6 +321,7 @@ describe("llm() through eval runtimes", () => {
 			sessionId,
 			sessionFile,
 			toolSession: makeSession(),
+			kernelMode: "per-call",
 		});
 
 		expect(result.exitCode).toBe(0);
diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index 99061c569..e2d481db2 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -421,13 +421,19 @@ export class ToolExecutionComponent extends Container {
 	#updateSpinnerAnimation(): void {
 		// Spinner for: task tool with partial result, or edit/write while args streaming
 		const isStreamingArgs = !this.#argsComplete && (isEditLikeToolName(this.#toolName) || this.#toolName === "write");
-		const isBackgroundAsyncTask =
-			this.#toolName === "task" &&
+		const isBackgroundAsyncRunning =
 			(this.#result?.details as { async?: { state?: string } } | undefined)?.async?.state === "running";
+		const isBackgroundAsyncTask = this.#toolName === "task" && isBackgroundAsyncRunning;
 		const isPartialTask = this.#isPartial && this.#toolName === "task" && !isBackgroundAsyncTask;
-		// Sweep the border of bash/eval execution blocks while they're pending.
+		// Sweep the border of bash/eval execution blocks while they're pending — but
+		// not once they've been backgrounded: a backgrounded job's block gets
+		// committed to scrollback and finalizes later via the async update path, so a
+		// mid-sweep frame would freeze a stray dark "bar" segment into the border.
 		const isPendingExecBlock =
-			this.#isPartial && shimmerEnabled() && (this.#toolName === "bash" || this.#toolName === "eval");
+			this.#isPartial &&
+			shimmerEnabled() &&
+			(this.#toolName === "bash" || this.#toolName === "eval") &&
+			!isBackgroundAsyncRunning;
 		const needsSpinner = isStreamingArgs || isPartialTask || isPendingExecBlock;
 		if (needsSpinner && !this.#spinnerInterval) {
 			this.#lastSpinnerAdvanceAt = performance.now();
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index a12b466f8..311b7eb77 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -2206,13 +2206,18 @@ export class AgentSession {
 	 * project, `~`-relative when it lives under home, else the raw path.
 	 */
 	#displayRulePath(rulePath: string): string {
-		const cwdRel = relativePathWithinRoot(this.sessionManager.getCwd(), rulePath);
+		const cwdRel = relativePathWithinRoot(this.sessionManager.getCwd(), rulePath) ?? this.#displayPathWithinRoot(this.sessionManager.getCwd(), rulePath);
 		if (cwdRel) return cwdRel;
 		const homeRel = relativePathWithinRoot(os.homedir(), rulePath);
 		if (homeRel) return `~/${homeRel}`;
 		return rulePath;
 	}
 
+	#displayPathWithinRoot(root: string, candidate: string): string | null {
+		const relative = path.relative(path.resolve(root), path.resolve(candidate));
+		return relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : null;
+	}
+
 	#addPendingTtsrInjections(rules: Rule[]): void {
 		const seen = new Set(this.#pendingTtsrInjections.map(rule => rule.name));
 		for (const rule of rules) {
diff --git a/packages/coding-agent/src/task/render.ts b/packages/coding-agent/src/task/render.ts
index e5e20373e..0975c66ea 100644
--- a/packages/coding-agent/src/task/render.ts
+++ b/packages/coding-agent/src/task/render.ts
@@ -6,12 +6,12 @@
  */
 import path from "node:path";
 import type { Component } from "@oh-my-pi/pi-tui";
-import { Container, Text } from "@oh-my-pi/pi-tui";
+import { Container, Markdown, Text } from "@oh-my-pi/pi-tui";
 import { formatNumber } from "@oh-my-pi/pi-utils";
 import { settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { formatContextUsage } from "../modes/components/status-line/context-thresholds";
-import type { Theme } from "../modes/theme/theme";
+import { getMarkdownTheme, type Theme } from "../modes/theme/theme";
 import {
 	formatBadge,
 	formatDuration,
@@ -540,13 +540,29 @@ function renderTaskItemLines(tasks: TaskItem[] | undefined, expanded: boolean, t
  * the merged result frame so the brief stays visible for the whole task
  * lifecycle — not just until the first progress snapshot replaces the call view.
  */
-function buildContextSection(args: TaskParams | undefined, theme: Theme): { lines: string[] } | undefined {
+type TaskRenderSection = { lines: string[] };
+type ContextSectionRenderer = (width: number) => TaskRenderSection;
+
+// Default output-block layout is: left border + one-cell content inset + right
+// border. Render markdown at that inner width so the output block does not need
+// to rewrap already-rendered context lines.
+const CONTEXT_FRAME_INSET = 3;
+
+function contextMarkdownWidth(frameWidth: number): number {
+	return Math.max(1, frameWidth - CONTEXT_FRAME_INSET);
+}
+
+function createContextSectionRenderer(args: TaskParams | undefined, theme: Theme): ContextSectionRenderer | undefined {
 	// `renderResult` receives the raw tool args (unlike `renderCall`, which is
 	// fed through `repairTaskParams`), so undo any per-field double-encoding here
 	// too. The repair is idempotent on already-clean text.
 	const context = repairDoubleEncodedJsonString(args?.context ?? "").trim();
 	if (!context) return undefined;
-	return { lines: context.split("\n").map(line => (line ? theme.fg("muted", replaceTabs(line)) : "")) };
+
+	const markdown = new Markdown(context, 0, 0, getMarkdownTheme(), {
+		color: text => theme.fg("muted", text),
+	});
+	return width => ({ lines: markdown.render(contextMarkdownWidth(width)) });
 }
 
 /**
@@ -559,11 +575,11 @@ export function renderCall(
 ): Component {
 	const showIsolated = "isolated" in args && args.isolated === true;
 	const header = renderStatusLine({ icon: "pending", title: "Task", description: args.agent }, theme);
+	const contextSectionRenderer = createContextSectionRenderer(args, theme);
 	return framedBlock(theme, width => {
 		const sections: Array<{ label?: string; lines: string[]; separator?: boolean }> = [];
 
-		const contextSection = buildContextSection(args, theme);
-		if (contextSection) sections.push(contextSection);
+		if (contextSectionRenderer) sections.push(contextSectionRenderer(width));
 
 		// The per-task preview list only exists to surface dispatched agents while
 		// the call args stream in. Once a result snapshot exists, `renderResult`
@@ -1049,7 +1065,7 @@ export function renderResult(
 ): Component {
 	const fallbackText = result.content.find(c => c.type === "text")?.text ?? "";
 	const details = result.details;
-	const contextSection = buildContextSection(args, theme);
+	const contextSectionRenderer = createContextSectionRenderer(args, theme);
 
 	if (!details) {
 		const text = result.content.find(c => c.type === "text")?.text || "";
@@ -1057,7 +1073,7 @@ export function renderResult(
 		return framedBlock(theme, width => ({
 			header,
 			sections: [
-				...(contextSection ? [contextSection] : []),
+				...(contextSectionRenderer ? [contextSectionRenderer(width)] : []),
 				...(text ? [{ separator: true, lines: [theme.fg("dim", truncateToWidth(text, width))] }] : []),
 			],
 			state: "success",
@@ -1124,7 +1140,7 @@ export function renderResult(
 			return {
 				header,
 				sections: [
-					...(contextSection ? [contextSection] : []),
+					...(contextSectionRenderer ? [contextSectionRenderer(width)] : []),
 					{ separator: true, lines: [theme.fg("dim", truncateToWidth(text, width))] },
 				],
 				state,
@@ -1154,7 +1170,7 @@ export function renderResult(
 		return {
 			header,
 			sections: [
-				...(contextSection ? [contextSection] : []),
+				...(contextSectionRenderer ? [contextSectionRenderer(width)] : []),
 				...(lines.length > 0 ? [{ separator: true, lines }] : []),
 			],
 			state,
diff --git a/packages/coding-agent/src/tools/bash.ts b/packages/coding-agent/src/tools/bash.ts
index 369a2c59f..36c03155c 100644
--- a/packages/coding-agent/src/tools/bash.ts
+++ b/packages/coding-agent/src/tools/bash.ts
@@ -1215,7 +1215,11 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 								{ label: uiTheme.fg("toolTitle", "Output"), lines: outputLines },
 							],
 							width,
-							animate: options.isPartial && shimmerEnabled(),
+							// Don't animate once the command has been backgrounded: the block
+							// gets committed to scrollback and finalizes later via the async
+							// update path, so a mid-sweep frame would freeze a stray dark
+							// border segment.
+							animate: options.isPartial && shimmerEnabled() && details?.async?.state !== "running",
 						},
 						uiTheme,
 					);
diff --git a/packages/coding-agent/test/agent-session-retry-cap.test.ts b/packages/coding-agent/test/agent-session-retry-cap.test.ts
index f5d4921b1..4c6f433d3 100644
--- a/packages/coding-agent/test/agent-session-retry-cap.test.ts
+++ b/packages/coding-agent/test/agent-session-retry-cap.test.ts
@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
 import * as path from "node:path";
 import { scheduler } from "node:timers/promises";
 import { Agent } from "@oh-my-pi/pi-agent-core";
-import { type AssistantMessage, getBundledModel } from "@oh-my-pi/pi-ai";
+import { type ApiKeyResolveContext, type AssistantMessage, getBundledModel } from "@oh-my-pi/pi-ai";
 import { createMockModel } from "@oh-my-pi/pi-ai/providers/mock";
 import { ModelRegistry } from "@oh-my-pi/pi-coding-agent/config/model-registry";
 import { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
@@ -22,6 +22,14 @@ function lastAssistant(session: AgentSession): AssistantMessage {
 	return message as AssistantMessage;
 }
 
+function resolveInitialApiKey(apiKey: string | ((ctx: ApiKeyResolveContext) => string | Promise<string | undefined> | undefined) | undefined): string {
+	const resolved = typeof apiKey === "function" ? apiKey({ lastChance: false, error: undefined }) : apiKey;
+	if (typeof resolved !== "string") {
+		throw new Error("Expected API key to be resolved before streaming");
+	}
+	return resolved;
+}
+
 /**
  * Contract: when the provider asks us to wait longer than `retry.maxDelayMs`
  * and we have no credential/model fallback to switch to, the auto-retry
@@ -155,10 +163,7 @@ describe("AgentSession retry delay cap", () => {
 				messages: [],
 			},
 			streamFn: (requestedModel, context, options) => {
-				const apiKey = options?.apiKey;
-				if (typeof apiKey !== "string") {
-					throw new Error("Expected API key to be resolved before streaming");
-				}
+				const apiKey = resolveInitialApiKey(options?.apiKey);
 				requestedKeys.push(apiKey);
 				if (requestedKeys.length === 1) {
 					mock.push({ throw: rateLimitError });
diff --git a/packages/coding-agent/test/task/render-call.test.ts b/packages/coding-agent/test/task/render-call.test.ts
index 7a83ddf2f..4ea12d880 100644
--- a/packages/coding-agent/test/task/render-call.test.ts
+++ b/packages/coding-agent/test/task/render-call.test.ts
@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, describe, expect, it } from "bun:test";
 import { resetSettingsForTest, Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import { getThemeByName, setThemeInstance, type Theme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
-import type { TaskParams } from "@oh-my-pi/pi-coding-agent/task";
+import type { TaskParams, TaskToolDetails } from "@oh-my-pi/pi-coding-agent/task";
 import { taskToolRenderer } from "@oh-my-pi/pi-coding-agent/task/render";
 
 describe("task renderer: streaming call preview", () => {
@@ -25,6 +25,35 @@ describe("task renderer: streaming call preview", () => {
 		return Bun.stripANSI(component.render(160).join("\n"));
 	}
 
+	function renderCompleted(args: TaskParams): string {
+		const details: TaskToolDetails = {
+			projectAgentsDir: null,
+			totalDurationMs: 12,
+			results: [
+				{
+					index: 0,
+					id: "Only",
+					agent: args.agent,
+					agentSource: "bundled",
+					task: "Render the shared context",
+					exitCode: 0,
+					output: "Done.",
+					stderr: "",
+					truncated: false,
+					durationMs: 12,
+					tokens: 1,
+				},
+			],
+		};
+		const component = taskToolRenderer.renderResult(
+			{ content: [{ type: "text", text: "1 agent completed." }], details },
+			{ expanded: false, isPartial: false },
+			theme,
+			args,
+		);
+		return Bun.stripANSI(component.render(160).join("\n"));
+	}
+
 	// The preview must surface each agent's id + ui description so the user can
 	// see which agents are being dispatched, not a bare "N agents" count.
 	it("lists each task's id and description instead of only a count", () => {
@@ -100,6 +129,23 @@ describe("task renderer: streaming call preview", () => {
 		expect(lines[0]).toContain("isolated");
 	});
 
+	it("renders shared context as markdown in call and result frames", () => {
+		const args: TaskParams = {
+			agent: "task",
+			context: ["# Goal", "Fix **rendering**.", "", "# Constraints", "- Keep `task` visible"].join("\n"),
+			tasks: [{ id: "Only", description: "Single task", assignment: "..." }],
+		};
+
+		for (const out of [render(args), renderCompleted(args)]) {
+			expect(out).toContain("Goal");
+			expect(out).toContain("Fix rendering.");
+			expect(out).toContain("Constraints");
+			expect(out).toContain("Keep task visible");
+			expect(out).not.toContain("# Goal");
+			expect(out).not.toContain("# Constraints");
+		}
+	});
+
 	// Once the tool produces a result, the container suppresses the call entirely
 	// via `mergeCallAndResult` and `renderResult` draws each agent. As a safety
 	// net, `renderCall` also drops its duplicate per-task preview when a result
diff --git a/packages/coding-agent/test/tools/bash-sixel-render.test.ts b/packages/coding-agent/test/tools/bash-sixel-render.test.ts
index 90e47d5cb..5e0f60a13 100644
--- a/packages/coding-agent/test/tools/bash-sixel-render.test.ts
+++ b/packages/coding-agent/test/tools/bash-sixel-render.test.ts
@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "bun:test";
+import { afterEach, describe, expect, it, vi } from "bun:test";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { RenderResultOptions } from "@oh-my-pi/pi-agent-core";
@@ -234,4 +234,36 @@ describe("bashToolRenderer", () => {
 			expect(rendered[idx]).toMatch(/\u001b\[38;(?:2|5);/);
 		}
 	});
+
+	it("keeps a backgrounded command's border static while a foreground one still shimmers", async () => {
+		const theme = await getThemeByName("dark");
+		expect(theme).toBeDefined();
+		const uiTheme = theme!;
+		// Render a still-partial bash result at two wall-clock instants a quarter of
+		// a shimmer cycle apart. The animated bottom-edge segment lives at the far
+		// left at t=0 and near center at t=750ms, so an animating border yields
+		// different bytes across the two frames while a static one is identical.
+		const renderAt = (details: Record<string, unknown>, now: number): string => {
+			const spy = vi.spyOn(Date, "now").mockReturnValue(now);
+			try {
+				const component = bashToolRenderer.renderResult(
+					{ content: [{ type: "text", text: "Background job bg_1 started: sleep 30" }], details, isError: false },
+					{ expanded: false, isPartial: true },
+					uiTheme,
+					{ command: "sleep 30" },
+				);
+				return component.render(60).join("\n");
+			} finally {
+				spy.mockRestore();
+			}
+		};
+
+		// Backgrounded (finalizes later via the async update path): no shimmer, so
+		// the committed frame can't freeze a stray dark "bar" into the border.
+		const backgrounded = { async: { state: "running", jobId: "bg_1", type: "bash" } };
+		expect(renderAt(backgrounded, 0)).toBe(renderAt(backgrounded, 750));
+
+		// Foreground pending: the border still sweeps, so frames differ over time.
+		expect(renderAt({}, 0)).not.toBe(renderAt({}, 750));
+	});
 });
diff --git a/packages/coding-agent/test/tools/inspect-image.test.ts b/packages/coding-agent/test/tools/inspect-image.test.ts
index 8345c1865..8365ce9c2 100644
--- a/packages/coding-agent/test/tools/inspect-image.test.ts
+++ b/packages/coding-agent/test/tools/inspect-image.test.ts
@@ -173,7 +173,7 @@ describe("InspectImageTool", () => {
 			uiTheme,
 		);
 		const callOutput = sanitizeText(callComponent.render(100).join("\n"));
-		expect(callOutput).toContain("Inspect Image");
+		expect(callOutput).toContain("Inspect");
 		expect(callOutput).toContain("Question:");
 		expect(callOutput).toContain("What error text is visible?");
 
@@ -191,7 +191,7 @@ describe("InspectImageTool", () => {
 			{ path: "/tmp/screenshot.png", question: "What error text is visible?" },
 		);
 		const resultOutput = sanitizeText(resultComponent.render(100).join("\n"));
-		expect(resultOutput).toContain("Inspect Image");
+		expect(resultOutput).toContain("Inspect");
 		expect(resultOutput).toContain("image/png");
 		expect(resultOutput).toContain("Question:");
 		expect(resultOutput).toContain("What error text is visible?");
diff --git a/packages/coding-agent/test/tools/read-renderer.test.ts b/packages/coding-agent/test/tools/read-renderer.test.ts
index 7bebce4f6..0c7991235 100644
--- a/packages/coding-agent/test/tools/read-renderer.test.ts
+++ b/packages/coding-agent/test/tools/read-renderer.test.ts
@@ -79,7 +79,7 @@ describe("readToolRenderer hyperlinks", () => {
 });
 
 describe("read ToolExecutionComponent framing", () => {
-	it("does not add vertical padding around framed read results", () => {
+	it("renders framed read results inside the standard tool container padding", () => {
 		const uiStub = { requestRender() {} } as unknown as TUI;
 		const component = new ToolExecutionComponent("read", { path: "src/example.ts" }, {}, undefined, uiStub);
 		component.updateResult(
@@ -102,9 +102,9 @@ describe("read ToolExecutionComponent framing", () => {
 				(line, index) => index > topBorderIndex && line.includes(activeTheme.boxSharp.bottomLeft),
 			);
 
-			expect(topBorderIndex).toBe(0);
+			expect(topBorderIndex).toBeGreaterThanOrEqual(0);
 			expect(lines[topBorderIndex + 1]).toContain("export const x = 1;");
-			expect(bottomBorderIndex).toBe(lines.length - 1);
+			expect(bottomBorderIndex).toBeGreaterThan(topBorderIndex);
 		} finally {
 			component.stopAnimation();
 		}

From 5f9df0e27b42803c73fa5b43fdda5109ea4e1891 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:05:30 +0200
Subject: [PATCH 124/181] chore: bumped models

---
 packages/ai/src/models.json | 432 +++++++++++++++++++++++++++++++++---
 1 file changed, 402 insertions(+), 30 deletions(-)

diff --git a/packages/ai/src/models.json b/packages/ai/src/models.json
index e98a047fc..d3cd30bf1 100644
--- a/packages/ai/src/models.json
+++ b/packages/ai/src/models.json
@@ -1932,6 +1932,75 @@
 				"maxLevel": "high"
 			}
 		},
+		"openai.gpt-5.4": {
+			"id": "openai.gpt-5.4",
+			"name": "GPT-5.4",
+			"api": "bedrock-converse-stream",
+			"provider": "amazon-bedrock",
+			"baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
+			"reasoning": true,
+			"input": [
+				"text",
+				"image"
+			],
+			"cost": {
+				"input": 2.75,
+				"output": 16.5,
+				"cacheRead": 0.275,
+				"cacheWrite": 0
+			},
+			"contextWindow": 272000,
+			"maxTokens": 128000,
+			"thinking": {
+				"mode": "budget",
+				"minLevel": "low",
+				"maxLevel": "xhigh"
+			}
+		},
+		"openai.gpt-5.5": {
+			"id": "openai.gpt-5.5",
+			"name": "GPT-5.5",
+			"api": "bedrock-converse-stream",
+			"provider": "amazon-bedrock",
+			"baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
+			"reasoning": true,
+			"input": [
+				"text",
+				"image"
+			],
+			"cost": {
+				"input": 5.5,
+				"output": 33,
+				"cacheRead": 0.55,
+				"cacheWrite": 0
+			},
+			"contextWindow": 272000,
+			"maxTokens": 128000,
+			"thinking": {
+				"mode": "budget",
+				"minLevel": "low",
+				"maxLevel": "xhigh"
+			}
+		},
+		"openai.gpt-oss-120b": {
+			"id": "openai.gpt-oss-120b",
+			"name": "gpt-oss-120b",
+			"api": "bedrock-converse-stream",
+			"provider": "amazon-bedrock",
+			"baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0.15,
+				"output": 0.6,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 128000,
+			"maxTokens": 16384
+		},
 		"openai.gpt-oss-120b-1:0": {
 			"id": "openai.gpt-oss-120b-1:0",
 			"name": "gpt-oss-120b",
@@ -1951,6 +2020,25 @@
 			"contextWindow": 128000,
 			"maxTokens": 16384
 		},
+		"openai.gpt-oss-20b": {
+			"id": "openai.gpt-oss-20b",
+			"name": "gpt-oss-20b",
+			"api": "bedrock-converse-stream",
+			"provider": "amazon-bedrock",
+			"baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0.07,
+				"output": 0.3,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 128000,
+			"maxTokens": 16384
+		},
 		"openai.gpt-oss-20b-1:0": {
 			"id": "openai.gpt-oss-20b-1:0",
 			"name": "gpt-oss-20b",
@@ -5364,11 +5452,6 @@
 				},
 				"maxTokensField": "max_tokens",
 				"supportsToolChoice": false,
-				"extraBody": {
-					"thinking": {
-						"type": "enabled"
-					}
-				},
 				"reasoningContentField": "reasoning_content",
 				"requiresReasoningContentForToolCalls": true,
 				"requiresAssistantContentForToolCalls": true
@@ -11197,7 +11280,7 @@
 		},
 		"deepseek/deepseek-r1-distill-llama-70b": {
 			"id": "deepseek/deepseek-r1-distill-llama-70b",
-			"name": "DeepSeek: R1 Distill Llama 70B",
+			"name": "DeepSeek: R1 Distill Llama 70B (retires Jun 11)",
 			"api": "openai-completions",
 			"provider": "kilo",
 			"baseUrl": "https://api.kilo.ai/api/gateway",
@@ -12648,7 +12731,7 @@
 		},
 		"meta-llama/llama-3-70b-instruct": {
 			"id": "meta-llama/llama-3-70b-instruct",
-			"name": "Meta: Llama 3 70B Instruct",
+			"name": "Meta: Llama 3 70B Instruct (retires Jun 19)",
 			"api": "openai-completions",
 			"provider": "kilo",
 			"baseUrl": "https://api.kilo.ai/api/gateway",
@@ -13187,6 +13270,25 @@
 		},
 		"minimax/minimax-m3": {
 			"id": "minimax/minimax-m3",
+			"name": "MiniMax: MiniMax M3 (new)",
+			"api": "openai-completions",
+			"provider": "kilo",
+			"baseUrl": "https://api.kilo.ai/api/gateway",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888
+		},
+		"minimax/minimax-m3:discounted": {
+			"id": "minimax/minimax-m3:discounted",
 			"name": "MiniMax: MiniMax M3 (50% off through 2026-06-07)",
 			"api": "openai-completions",
 			"provider": "kilo",
@@ -14262,6 +14364,63 @@
 			"contextWindow": 222222,
 			"maxTokens": 8888
 		},
+		"nvidia/nemotron-3-ultra-550b-a55b": {
+			"id": "nvidia/nemotron-3-ultra-550b-a55b",
+			"name": "NVIDIA: Nemotron 3 Ultra",
+			"api": "openai-completions",
+			"provider": "kilo",
+			"baseUrl": "https://api.kilo.ai/api/gateway",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888
+		},
+		"nvidia/nemotron-3-ultra-550b-a55b:free": {
+			"id": "nvidia/nemotron-3-ultra-550b-a55b:free",
+			"name": "NVIDIA: Nemotron 3 Ultra (free)",
+			"api": "openai-completions",
+			"provider": "kilo",
+			"baseUrl": "https://api.kilo.ai/api/gateway",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888
+		},
+		"nvidia/nemotron-3.5-content-safety:free": {
+			"id": "nvidia/nemotron-3.5-content-safety:free",
+			"name": "NVIDIA: Nemotron 3.5 Content Safety (free)",
+			"api": "openai-completions",
+			"provider": "kilo",
+			"baseUrl": "https://api.kilo.ai/api/gateway",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888
+		},
 		"nvidia/nemotron-nano-12b-v2-vl": {
 			"id": "nvidia/nemotron-nano-12b-v2-vl",
 			"name": "NVIDIA: Nemotron Nano 12B 2 VL",
@@ -14283,7 +14442,7 @@
 		},
 		"nvidia/nemotron-nano-9b-v2": {
 			"id": "nvidia/nemotron-nano-9b-v2",
-			"name": "NVIDIA: Nemotron Nano 9B V2",
+			"name": "NVIDIA: Nemotron Nano 9B V2 (retires Jun 11)",
 			"api": "openai-completions",
 			"provider": "kilo",
 			"baseUrl": "https://api.kilo.ai/api/gateway",
@@ -16371,7 +16530,7 @@
 		},
 		"qwen/qwen3-30b-a3b": {
 			"id": "qwen/qwen3-30b-a3b",
-			"name": "Qwen: Qwen3 30B A3B (retires Jun 5)",
+			"name": "Qwen: Qwen3 30B A3B",
 			"api": "openai-completions",
 			"provider": "kilo",
 			"baseUrl": "https://api.kilo.ai/api/gateway",
@@ -19993,24 +20152,19 @@
 			"api": "openai-completions",
 			"provider": "mistral",
 			"baseUrl": "https://api.mistral.ai/v1",
-			"reasoning": true,
+			"reasoning": false,
 			"input": [
 				"text",
 				"image"
 			],
 			"cost": {
-				"input": 1.5,
-				"output": 7.5,
+				"input": 0.4,
+				"output": 2,
 				"cacheRead": 0,
 				"cacheWrite": 0
 			},
 			"contextWindow": 262144,
-			"maxTokens": 262144,
-			"thinking": {
-				"mode": "effort",
-				"minLevel": "minimal",
-				"maxLevel": "xhigh"
-			}
+			"maxTokens": 262144
 		},
 		"mistral-nemo": {
 			"id": "mistral-nemo",
@@ -25743,6 +25897,82 @@
 			"contextWindow": 222222,
 			"maxTokens": 8888
 		},
+		"linkup-research-high": {
+			"id": "linkup-research-high",
+			"name": "linkup-research-high",
+			"api": "openai-completions",
+			"provider": "nanogpt",
+			"baseUrl": "https://nano-gpt.com/api/v1",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888
+		},
+		"linkup-research-low": {
+			"id": "linkup-research-low",
+			"name": "linkup-research-low",
+			"api": "openai-completions",
+			"provider": "nanogpt",
+			"baseUrl": "https://nano-gpt.com/api/v1",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888
+		},
+		"linkup-research-medium": {
+			"id": "linkup-research-medium",
+			"name": "linkup-research-medium",
+			"api": "openai-completions",
+			"provider": "nanogpt",
+			"baseUrl": "https://nano-gpt.com/api/v1",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888
+		},
+		"linkup-research-xhigh": {
+			"id": "linkup-research-xhigh",
+			"name": "linkup-research-xhigh",
+			"api": "openai-completions",
+			"provider": "nanogpt",
+			"baseUrl": "https://nano-gpt.com/api/v1",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888
+		},
 		"liquid/lfm-2-24b-a2b": {
 			"id": "liquid/lfm-2-24b-a2b",
 			"name": "liquid/lfm-2-24b-a2b",
@@ -28343,6 +28573,30 @@
 				"maxLevel": "xhigh"
 			}
 		},
+		"nvidia/nemotron-3-ultra-550b-a55b": {
+			"id": "nvidia/nemotron-3-ultra-550b-a55b",
+			"name": "nvidia/nemotron-3-ultra-550b-a55b",
+			"api": "openai-completions",
+			"provider": "nanogpt",
+			"baseUrl": "https://nano-gpt.com/api/v1",
+			"reasoning": true,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888,
+			"thinking": {
+				"mode": "effort",
+				"minLevel": "minimal",
+				"maxLevel": "xhigh"
+			}
+		},
 		"nvidia/nvidia-nemotron-nano-9b-v2": {
 			"id": "nvidia/nvidia-nemotron-nano-9b-v2",
 			"name": "nvidia-nemotron-nano-9b-v2",
@@ -38214,7 +38468,7 @@
 				"cacheRead": 0.05,
 				"cacheWrite": 0.625
 			},
-			"contextWindow": 262144,
+			"contextWindow": 1000000,
 			"maxTokens": 65536,
 			"thinking": {
 				"mode": "effort",
@@ -38263,7 +38517,7 @@
 				"cacheRead": 0.04,
 				"cacheWrite": 0.5
 			},
-			"contextWindow": 262144,
+			"contextWindow": 1000000,
 			"maxTokens": 65536,
 			"thinking": {
 				"mode": "budget",
@@ -39625,6 +39879,30 @@
 				"maxLevel": "xhigh"
 			}
 		},
+		"nemotron-3-ultra-free": {
+			"id": "nemotron-3-ultra-free",
+			"name": "Nemotron 3 Ultra Free",
+			"api": "openai-completions",
+			"provider": "opencode-zen",
+			"baseUrl": "https://opencode.ai/zen/v1",
+			"reasoning": true,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 1000000,
+			"maxTokens": 128000,
+			"thinking": {
+				"mode": "effort",
+				"minLevel": "minimal",
+				"maxLevel": "xhigh"
+			}
+		},
 		"qwen3.5-plus": {
 			"id": "qwen3.5-plus",
 			"name": "Qwen3.5 Plus",
@@ -41767,12 +42045,12 @@
 			],
 			"cost": {
 				"input": 0.12,
-				"output": 0.37,
-				"cacheRead": 0.019999999499999997,
+				"output": 0.36,
+				"cacheRead": 0.09,
 				"cacheWrite": 0
 			},
 			"contextWindow": 262144,
-			"maxTokens": 16384,
+			"maxTokens": 8192,
 			"thinking": {
 				"mode": "effort",
 				"minLevel": "minimal",
@@ -42135,7 +42413,7 @@
 			],
 			"cost": {
 				"input": 0.02,
-				"output": 0.049999999999999996,
+				"output": 0.03,
 				"cacheRead": 0,
 				"cacheWrite": 0
 			},
@@ -42360,7 +42638,7 @@
 				"cacheWrite": 0
 			},
 			"contextWindow": 204800,
-			"maxTokens": 131072,
+			"maxTokens": 196608,
 			"thinking": {
 				"mode": "effort",
 				"minLevel": "minimal",
@@ -43295,6 +43573,54 @@
 				"maxLevel": "high"
 			}
 		},
+		"nvidia/nemotron-3-ultra-550b-a55b": {
+			"id": "nvidia/nemotron-3-ultra-550b-a55b",
+			"name": "NVIDIA: Nemotron 3 Ultra",
+			"api": "openai-completions",
+			"provider": "openrouter",
+			"baseUrl": "https://openrouter.ai/api/v1",
+			"reasoning": true,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0.5,
+				"output": 2.5,
+				"cacheRead": 0.15,
+				"cacheWrite": 0
+			},
+			"contextWindow": 1000000,
+			"maxTokens": 16384,
+			"thinking": {
+				"mode": "effort",
+				"minLevel": "minimal",
+				"maxLevel": "high"
+			}
+		},
+		"nvidia/nemotron-3-ultra-550b-a55b:free": {
+			"id": "nvidia/nemotron-3-ultra-550b-a55b:free",
+			"name": "NVIDIA: Nemotron 3 Ultra (free)",
+			"api": "openai-completions",
+			"provider": "openrouter",
+			"baseUrl": "https://openrouter.ai/api/v1",
+			"reasoning": true,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 1000000,
+			"maxTokens": 65536,
+			"thinking": {
+				"mode": "effort",
+				"minLevel": "minimal",
+				"maxLevel": "high"
+			}
+		},
 		"nvidia/nemotron-nano-12b-v2-vl:free": {
 			"id": "nvidia/nemotron-nano-12b-v2-vl:free",
 			"name": "NVIDIA: Nemotron Nano 12B 2 VL (free)",
@@ -45244,7 +45570,7 @@
 				"cacheWrite": 0
 			},
 			"contextWindow": 131072,
-			"maxTokens": 20000,
+			"maxTokens": 16384,
 			"thinking": {
 				"mode": "effort",
 				"minLevel": "minimal",
@@ -46000,13 +46326,13 @@
 				"image"
 			],
 			"cost": {
-				"input": 0.29,
-				"output": 3.1999999999999997,
+				"input": 0.28900000000000003,
+				"output": 2.4,
 				"cacheRead": 0.15,
 				"cacheWrite": 0
 			},
 			"contextWindow": 262144,
-			"maxTokens": 262140,
+			"maxTokens": 131072,
 			"thinking": {
 				"mode": "effort",
 				"minLevel": "minimal",
@@ -49634,6 +49960,28 @@
 				"supportsUsageInStreaming": false
 			}
 		},
+		"nvidia-nemotron-3-ultra-550b-a55b": {
+			"id": "nvidia-nemotron-3-ultra-550b-a55b",
+			"name": "nvidia-nemotron-3-ultra-550b-a55b",
+			"api": "openai-completions",
+			"provider": "venice",
+			"baseUrl": "https://api.venice.ai/api/v1",
+			"reasoning": false,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0,
+				"output": 0,
+				"cacheRead": 0,
+				"cacheWrite": 0
+			},
+			"contextWindow": 222222,
+			"maxTokens": 8888,
+			"compat": {
+				"supportsUsageInStreaming": false
+			}
+		},
 		"nvidia-nemotron-cascade-2-30b-a3b": {
 			"id": "nvidia-nemotron-cascade-2-30b-a3b",
 			"name": "nvidia-nemotron-cascade-2-30b-a3b",
@@ -52853,6 +53201,30 @@
 				"maxLevel": "xhigh"
 			}
 		},
+		"nvidia/nemotron-3-ultra-550b-a55b": {
+			"id": "nvidia/nemotron-3-ultra-550b-a55b",
+			"name": "Nemotron 3 Ultra",
+			"api": "anthropic-messages",
+			"provider": "vercel-ai-gateway",
+			"baseUrl": "https://ai-gateway.vercel.sh",
+			"reasoning": true,
+			"input": [
+				"text"
+			],
+			"cost": {
+				"input": 0.6,
+				"output": 2.4,
+				"cacheRead": 0.12,
+				"cacheWrite": 0
+			},
+			"contextWindow": 1000000,
+			"maxTokens": 65000,
+			"thinking": {
+				"mode": "budget",
+				"minLevel": "minimal",
+				"maxLevel": "xhigh"
+			}
+		},
 		"nvidia/nemotron-nano-12b-v2-vl": {
 			"id": "nvidia/nemotron-nano-12b-v2-vl",
 			"name": "Nvidia Nemotron Nano 12B V2 VL",
@@ -57962,7 +58334,7 @@
 			"cost": {
 				"input": 0.5,
 				"output": 1.5,
-				"cacheRead": 0,
+				"cacheRead": 0.05,
 				"cacheWrite": 0
 			},
 			"contextWindow": 256000,

From b57899d3eb185d3d6920f19c469f7e4a0f4cde5b Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:05:51 +0200
Subject: [PATCH 125/181] fix(ai): stripped Fireworks DeepSeek thinking toggle
 when reasoning effort is set

- Added stripFireworksDeepSeekThinkingToggle to strip DeepSeek V4 `thinking` metadata before model compatibility is used.
- Applied the stripping helper in Fireworks model mapping and generation so produced models exclude the incompatible flag.
- Updated completion param construction to remove `thinking` when `reasoning_effort` is sent and added a regression test for Fireworks DeepSeek V4.
---
 packages/ai/scripts/generate-models.ts        | 14 ++++++++++
 .../ai/src/provider-models/openai-compat.ts   | 28 ++++++++++++++++++-
 .../ai/src/providers/openai-completions.ts    |  5 ++++
 packages/ai/test/issue-1207-repro.test.ts     | 13 +++++++++
 4 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/packages/ai/scripts/generate-models.ts b/packages/ai/scripts/generate-models.ts
index 6431ade6d..af2cc8566 100644
--- a/packages/ai/scripts/generate-models.ts
+++ b/packages/ai/scripts/generate-models.ts
@@ -30,6 +30,7 @@ import {
 	buildXaiOAuthStaticSeed,
 	clampFireworksKimiMaxTokens,
 	isFireworksKimiK2ModelId,
+	stripFireworksDeepSeekThinkingToggle,
 	MODELS_DEV_PROVIDER_DESCRIPTORS,
 	mapModelsDevToModels,
 	UNK_CONTEXT_WINDOW,
@@ -243,6 +244,18 @@ function applyFireworksKimiMaxTokensCap(models: readonly Model[]): Model[] {
 	});
 }
 
+/**
+ * Fireworks' DeepSeek V4 endpoint accepts the user's effort through
+ * `reasoning_effort` and rejects the DeepSeek-native binary `thinking` toggle
+ * when both are present. Strip stale reference metadata from generated fallbacks.
+ */
+function applyFireworksDeepSeekReasoningShape(models: readonly Model[]): Model[] {
+	return models.map(model => {
+		if (model.provider !== "fireworks" || model.api !== "openai-completions") return model;
+		return stripFireworksDeepSeekThinkingToggle(model, model.id);
+	});
+}
+
 const ANTIGRAVITY_ENDPOINT = "https://daily-cloudcode-pa.sandbox.googleapis.com";
 
 async function getOAuthAccessFromStorage(provider: OAuthProvider): Promise<OAuthAccess | null> {
@@ -416,6 +429,7 @@ async function generateModels() {
 	allModels = applyPremiumMultiplierOverrides(allModels);
 	allModels = applyCodexPricingFallback(allModels);
 	allModels = applyFireworksKimiMaxTokensCap(allModels);
+	allModels = applyFireworksDeepSeekReasoningShape(allModels);
 	applyGeneratedModelPolicies(allModels);
 	linkOpenAIPromotionTargets(allModels);
 
diff --git a/packages/ai/src/provider-models/openai-compat.ts b/packages/ai/src/provider-models/openai-compat.ts
index 545662fa4..c529fb135 100644
--- a/packages/ai/src/provider-models/openai-compat.ts
+++ b/packages/ai/src/provider-models/openai-compat.ts
@@ -971,6 +971,29 @@ export function clampFireworksKimiMaxTokens(modelId: string, candidate: number):
 	return isFireworksKimiK2ModelId(modelId) ? Math.min(candidate, FIREWORKS_KIMI_MAX_TOKENS) : candidate;
 }
 
+/**
+ * Fireworks DeepSeek V4 accepts effort via `reasoning_effort` but rejects the
+ * DeepSeek-native binary `thinking` toggle when both are present.
+ */
+export function stripFireworksDeepSeekThinkingToggle(
+	model: Model<"openai-completions">,
+	publicModelId: string,
+): Model<"openai-completions"> {
+	if (!publicModelId.startsWith("deepseek-v4")) return model;
+	const compat = model.compat;
+	if (!compat?.extraBody || !("thinking" in compat.extraBody)) return model;
+
+	const extraBody = { ...compat.extraBody };
+	delete extraBody.thinking;
+	if (Object.keys(extraBody).length > 0) {
+		return { ...model, compat: { ...compat, extraBody } };
+	}
+
+	const nextCompat = { ...compat };
+	delete nextCompat.extraBody;
+	return { ...model, compat: nextCompat };
+}
+
 export interface FireworksModelManagerConfig {
 	apiKey?: string;
 	baseUrl?: string;
@@ -1040,7 +1063,10 @@ export function fireworksModelManagerOptions(
 					mapModel: (entry, defaults) => {
 						const publicModelId = toFireworksPublicModelId(defaults.id);
 						const reference = modelsDevReferences.get(publicModelId) ?? bundledReferences(publicModelId);
-						const model = mapWithBundledReference(entry, defaults, reference);
+						const model = stripFireworksDeepSeekThinkingToggle(
+							mapWithBundledReference(entry, defaults, reference),
+							publicModelId,
+						);
 						return {
 							...model,
 							id: publicModelId,
diff --git a/packages/ai/src/providers/openai-completions.ts b/packages/ai/src/providers/openai-completions.ts
index 67cae1e4a..e58e4b8fd 100644
--- a/packages/ai/src/providers/openai-completions.ts
+++ b/packages/ai/src/providers/openai-completions.ts
@@ -1345,6 +1345,11 @@ function buildParams(
 
 	if (compat.extraBody) {
 		Object.assign(params, compat.extraBody);
+		if (model.provider === "fireworks" && params.reasoning_effort !== undefined) {
+			// Fireworks rejects simultaneous DeepSeek-style `thinking` toggles and
+			// OpenAI-style `reasoning_effort`; the effort field carries the user's level.
+			delete params.thinking;
+		}
 	}
 
 	return { params, toolStrictMode };
diff --git a/packages/ai/test/issue-1207-repro.test.ts b/packages/ai/test/issue-1207-repro.test.ts
index 85e31868d..d71c91b3d 100644
--- a/packages/ai/test/issue-1207-repro.test.ts
+++ b/packages/ai/test/issue-1207-repro.test.ts
@@ -91,6 +91,19 @@ describe("issue #1207 — DeepSeek V4 keeps reasoning with tools", () => {
 		expect(body.max_completion_tokens).toBeUndefined();
 	});
 
+	it("does not mix Fireworks DeepSeek effort with the native thinking toggle", async () => {
+		const model = getBundledModel("fireworks", "deepseek-v4-pro") as Model<"openai-completions">;
+		const compat = resolveOpenAICompat(model);
+		const body = await capturePayload(model);
+
+		expect(compat.extraBody).toBeUndefined();
+		expect(body.tools).toBeDefined();
+		expect(body.tool_choice).toBeUndefined();
+		expect(body.reasoning_effort).toBe("high");
+		expect(body.thinking).toBeUndefined();
+		expect(body.max_tokens).toBe(123);
+	});
+
 	it("preserves OpenRouter reasoning when tool_choice auto is present", async () => {
 		const model = getBundledModel("openrouter", "deepseek/deepseek-v4-flash") as Model<"openai-completions">;
 		const compat = detectOpenAICompat(model);

From 20487d8cb6217f0e82ec501c366c64408716313f Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:11:38 +0200
Subject: [PATCH 126/181] chore: fix stale tests

---
 packages/ai/scripts/generate-models.ts        |   2 +-
 .../src/eval/__tests__/llm-bridge.test.ts     | 122 +++++++++++++-----
 .../coding-agent/src/session/agent-session.ts |   4 +-
 .../test/agent-session-retry-cap.test.ts      |   4 +-
 .../test/input-controller-escape.test.ts      |   6 +-
 .../test/task/render-nested-live.test.ts      |   2 +-
 6 files changed, 102 insertions(+), 38 deletions(-)

diff --git a/packages/ai/scripts/generate-models.ts b/packages/ai/scripts/generate-models.ts
index af2cc8566..497fb7c25 100644
--- a/packages/ai/scripts/generate-models.ts
+++ b/packages/ai/scripts/generate-models.ts
@@ -30,9 +30,9 @@ import {
 	buildXaiOAuthStaticSeed,
 	clampFireworksKimiMaxTokens,
 	isFireworksKimiK2ModelId,
-	stripFireworksDeepSeekThinkingToggle,
 	MODELS_DEV_PROVIDER_DESCRIPTORS,
 	mapModelsDevToModels,
+	stripFireworksDeepSeekThinkingToggle,
 	UNK_CONTEXT_WINDOW,
 	UNK_MAX_TOKENS,
 } from "../src/provider-models/openai-compat";
diff --git a/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts b/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
index c8d724e8d..67260c8f2 100644
--- a/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
+++ b/packages/coding-agent/src/eval/__tests__/llm-bridge.test.ts
@@ -4,6 +4,7 @@ import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
 import * as ai from "@oh-my-pi/pi-ai";
 import { Effort } from "@oh-my-pi/pi-ai";
 import { TempDir } from "@oh-my-pi/pi-utils";
+import { $ } from "bun";
 import type { ModelRegistry } from "../../config/model-registry";
 import { Settings } from "../../config/settings";
 import type { ToolSession } from "../../tools";
@@ -13,7 +14,7 @@ import { IdleTimeout } from "../idle-timeout";
 import { disposeAllVmContexts } from "../js/context-manager";
 import { executeJs } from "../js/executor";
 import { runEvalLlm } from "../llm-bridge";
-import { disposeAllKernelSessions, executePython } from "../py/executor";
+import { disposeAllKernelSessions, type PythonResult } from "../py/executor";
 
 function makeModel(provider: string, id: string, extra: Partial<Model<Api>> = {}): Model<Api> {
 	return {
@@ -97,6 +98,77 @@ function assistant(opts: {
 	};
 }
 
+async function runPythonLlmInSubprocess(options: { structured: boolean; tempDir: TempDir }): Promise<PythonResult> {
+	const repoRoot = path.resolve(import.meta.dir, "../../../..");
+	const scriptPath = path.join(options.tempDir.path(), "run-python-llm.ts");
+	const resultPath = path.join(options.tempDir.path(), "python-llm-result.json");
+	const aiPath = path.resolve(import.meta.dir, "../../../../ai/src/index.ts");
+	const executorPath = path.resolve(import.meta.dir, "../py/executor.ts");
+	const settingsPath = path.resolve(import.meta.dir, "../../config/settings.ts");
+	const code = options.structured
+		? 'import json\nprint(json.dumps(llm("hi", schema={"type": "object"})))'
+		: 'print(llm("hi", model="smol"))';
+	const responseContent = options.structured
+		? '[{ type: "toolCall", id: "tc-1", name: "respond", arguments: { ok: true } }]'
+		: '[{ type: "text", text: "hello from python" }]';
+	await Bun.write(
+		scriptPath,
+		`
+import { vi } from "bun:test";
+import * as ai from ${JSON.stringify(aiPath)};
+import { executePython } from ${JSON.stringify(executorPath)};
+import { Settings } from ${JSON.stringify(settingsPath)};
+
+const SMOL = {
+	id: "smol",
+	name: "smol",
+	api: "openai-responses",
+	provider: "p",
+	baseUrl: "https://example.test/v1",
+	reasoning: false,
+	input: ["text"],
+	cost: { input: 1, output: 1, cacheRead: 0, cacheWrite: 1 },
+	contextWindow: 128000,
+	maxTokens: 4096,
+};
+const settings = Settings.isolated({ "async.enabled": false, "task.isolation.mode": "none" });
+settings.setModelRole("smol", "p/smol");
+settings.setModelRole("slow", "p/slow");
+const session = {
+	settings,
+	modelRegistry: {
+		getAvailable: () => [SMOL],
+		getApiKey: async () => "test-key",
+		resolver: () => async () => "test-key",
+	},
+	getActiveModelString: () => "p/smol",
+};
+vi.spyOn(ai, "completeSimple").mockResolvedValue({
+	role: "assistant",
+	api: "openai-responses",
+	provider: "p",
+	model: "smol",
+	stopReason: "stop",
+	content: ${responseContent},
+});
+const result = await executePython(${JSON.stringify(code)}, {
+	cwd: ${JSON.stringify(options.tempDir.path())},
+	sessionId: ${JSON.stringify(`py-llm:${options.structured ? "struct" : "plain"}`)},
+	sessionFile: ${JSON.stringify(path.join(options.tempDir.path(), "session.jsonl"))},
+	toolSession: session,
+	kernelMode: "per-call",
+});
+await Bun.write(${JSON.stringify(resultPath)}, JSON.stringify(result));
+process.exit(0);
+`,
+	);
+	const child = await $`bun ${scriptPath}`.cwd(repoRoot).quiet().nothrow();
+	const stdout = child.stdout.toString();
+	const stderr = child.stderr.toString();
+	if (child.exitCode !== 0) throw new Error(stderr || stdout || `Python llm subprocess exited with ${child.exitCode}`);
+	return (await Bun.file(resultPath).json()) as PythonResult;
+}
+
 describe("runEvalLlm", () => {
 	afterEach(() => {
 		vi.restoreAllMocks();
@@ -291,40 +363,24 @@ describe("llm() through eval runtimes", () => {
 	});
 
 	it("exposes llm() in the Python runtime", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-llm-py-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-llm:${crypto.randomUUID()}`;
-		vi.spyOn(ai, "completeSimple").mockResolvedValue(assistant({ text: "hello from python" }));
-
-		const result = await executePython('print(llm("hi", model="smol"))', {
-			cwd: tempDir.path(),
-			sessionId,
-			sessionFile,
-			toolSession: makeSession(),
-			kernelMode: "per-call",
-		});
-
-		expect(result.exitCode).toBe(0);
-		expect(result.output.trim()).toBe("hello from python");
+		const tempDir = TempDir.createSync("@omp-eval-llm-py-");
+		try {
+			const result = await runPythonLlmInSubprocess({ structured: false, tempDir });
+			expect(result.exitCode).toBe(0);
+			expect(result.output.trim()).toBe("hello from python");
+		} finally {
+			tempDir.removeSync();
+		}
 	});
 
 	it("parses structured llm() output in the Python runtime", async () => {
-		using tempDir = TempDir.createSync("@omp-eval-llm-py-struct-");
-		const sessionFile = path.join(tempDir.path(), "session.jsonl");
-		const sessionId = `py-llm-struct:${crypto.randomUUID()}`;
-		vi.spyOn(ai, "completeSimple").mockResolvedValue(
-			assistant({ toolCall: { name: "respond", arguments: { ok: true } } }),
-		);
-
-		const result = await executePython('import json\nprint(json.dumps(llm("hi", schema={"type": "object"})))', {
-			cwd: tempDir.path(),
-			sessionId,
-			sessionFile,
-			toolSession: makeSession(),
-			kernelMode: "per-call",
-		});
-
-		expect(result.exitCode).toBe(0);
-		expect(JSON.parse(result.output.trim())).toEqual({ ok: true });
+		const tempDir = TempDir.createSync("@omp-eval-llm-py-struct-");
+		try {
+			const result = await runPythonLlmInSubprocess({ structured: true, tempDir });
+			expect(result.exitCode).toBe(0);
+			expect(JSON.parse(result.output.trim())).toEqual({ ok: true });
+		} finally {
+			tempDir.removeSync();
+		}
 	});
 });
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index 311b7eb77..b53734c6f 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -2206,7 +2206,9 @@ export class AgentSession {
 	 * project, `~`-relative when it lives under home, else the raw path.
 	 */
 	#displayRulePath(rulePath: string): string {
-		const cwdRel = relativePathWithinRoot(this.sessionManager.getCwd(), rulePath) ?? this.#displayPathWithinRoot(this.sessionManager.getCwd(), rulePath);
+		const cwdRel =
+			relativePathWithinRoot(this.sessionManager.getCwd(), rulePath) ??
+			this.#displayPathWithinRoot(this.sessionManager.getCwd(), rulePath);
 		if (cwdRel) return cwdRel;
 		const homeRel = relativePathWithinRoot(os.homedir(), rulePath);
 		if (homeRel) return `~/${homeRel}`;
diff --git a/packages/coding-agent/test/agent-session-retry-cap.test.ts b/packages/coding-agent/test/agent-session-retry-cap.test.ts
index 4c6f433d3..f7b04d26c 100644
--- a/packages/coding-agent/test/agent-session-retry-cap.test.ts
+++ b/packages/coding-agent/test/agent-session-retry-cap.test.ts
@@ -22,7 +22,9 @@ function lastAssistant(session: AgentSession): AssistantMessage {
 	return message as AssistantMessage;
 }
 
-function resolveInitialApiKey(apiKey: string | ((ctx: ApiKeyResolveContext) => string | Promise<string | undefined> | undefined) | undefined): string {
+function resolveInitialApiKey(
+	apiKey: string | ((ctx: ApiKeyResolveContext) => string | Promise<string | undefined> | undefined) | undefined,
+): string {
 	const resolved = typeof apiKey === "function" ? apiKey({ lastChance: false, error: undefined }) : apiKey;
 	if (typeof resolved !== "string") {
 		throw new Error("Expected API key to be resolved before streaming");
diff --git a/packages/coding-agent/test/input-controller-escape.test.ts b/packages/coding-agent/test/input-controller-escape.test.ts
index b04750571..f458d9568 100644
--- a/packages/coding-agent/test/input-controller-escape.test.ts
+++ b/packages/coding-agent/test/input-controller-escape.test.ts
@@ -113,7 +113,11 @@ function createContext(): {
 
 	ctx = {
 		editor: editor as unknown as InteractiveModeContext["editor"],
-		ui: { requestRender, addInputListener: vi.fn(), addStartListener: vi.fn() } as unknown as InteractiveModeContext["ui"],
+		ui: {
+			requestRender,
+			addInputListener: vi.fn(),
+			addStartListener: vi.fn(),
+		} as unknown as InteractiveModeContext["ui"],
 		loadingAnimation: undefined,
 		autoCompactionLoader: undefined,
 		retryLoader: undefined,
diff --git a/packages/coding-agent/test/task/render-nested-live.test.ts b/packages/coding-agent/test/task/render-nested-live.test.ts
index 4042fb5d8..f232fbada 100644
--- a/packages/coding-agent/test/task/render-nested-live.test.ts
+++ b/packages/coding-agent/test/task/render-nested-live.test.ts
@@ -227,7 +227,7 @@ describe("task renderer: nested live rendering", () => {
 		const text = Bun.stripANSI(component.render(160).join("\n"));
 		// The brief no longer vanishes the moment the first progress snapshot
 		// replaces the streaming call view.
-		expect(text).toContain("# Goal");
+		expect(text).toContain("Goal");
 		expect(text).toContain("Harden the auth stack before the cut.");
 	});
 

From 87a5ae77a198a4278217d2cc14335b550c067b49 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:15:50 +0200
Subject: [PATCH 127/181] fix(ai/utils): skipped persisting HTTP 400 raw dumps
 during Bun test runtime

- Updated `appendRawHttpRequestDumpFor400` to skip execution in the Bun test runtime.
- Imported `isBunTestRuntime` and used it to avoid writing 400 raw request dumps to `~/.omp/logs/http-400-requests` when tests use mocked fetch responses.
- Documented the test-runtime persistence fix in the package changelog.
---
 packages/ai/CHANGELOG.md                | 1 +
 packages/ai/src/utils/http-inspector.ts | 6 ++++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 3062ec17d..1a7a921ba 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -20,6 +20,7 @@
 
 - Fixed streaming auth retries to handle `401` and usage-limit errors before replay-unsafe content is emitted, including failures surfaced only via `errorStatus`
 - Fixed streaming retries to buffer and suppress partial `start` events from failed auth attempts so only clean retried events are delivered
+- Fixed the HTTP 400 raw-request dumper (`appendRawHttpRequestDumpFor400`) littering the real `~/.omp/logs/http-400-requests` directory during tests. Provider suites exercise the 400 error path with mocked `fetch` responses, which the dumper could not distinguish from genuine failures; it now skips persistence under the Bun test runner (`isBunTestRuntime()`).
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/ai/src/utils/http-inspector.ts b/packages/ai/src/utils/http-inspector.ts
index 31a6ccb06..df738c3d8 100644
--- a/packages/ai/src/utils/http-inspector.ts
+++ b/packages/ai/src/utils/http-inspector.ts
@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { extractHttpStatusFromError, getLogsDir } from "@oh-my-pi/pi-utils";
+import { extractHttpStatusFromError, getLogsDir, isBunTestRuntime } from "@oh-my-pi/pi-utils";
 import { isCopilotTransientModelError } from "./retry.js";
 import { formatErrorMessageWithRetryAfter } from "./retry-after.js";
 
@@ -31,7 +31,9 @@ export async function appendRawHttpRequestDumpFor400(
 	error: unknown,
 	dump: RawHttpRequestDump | undefined,
 ): Promise<string> {
-	if (!dump || extractHttpStatusFromError(error) !== 400) {
+	// Never persist dumps under the test runner: providers exercise the 400 path
+	// with mocked fetch responses, which would otherwise litter the real ~/.omp logs.
+	if (!dump || isBunTestRuntime() || extractHttpStatusFromError(error) !== 400) {
 		return message;
 	}
 

From 0d6913e926dbc674b9dcadeb06b2095fffd890a7 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 06:31:30 +0000
Subject: [PATCH 128/181] fix(ai): coerced singleton array arguments

Wrapped non-string singleton values when an array field is expected so malformed Anthropic-compatible tool calls can validate instead of looping on errors.

Fixes #2026
---
 docs/models.md                                |  6 +--
 packages/ai/CHANGELOG.md                      |  1 +
 packages/ai/src/utils/validation.ts           |  9 ++--
 .../ai/test/tool-argument-coercion.test.ts    | 53 +++++++++++++++++++
 4 files changed, 62 insertions(+), 7 deletions(-)

diff --git a/docs/models.md b/docs/models.md
index daa9e7a2a..a1ca6d89f 100644
--- a/docs/models.md
+++ b/docs/models.md
@@ -557,9 +557,9 @@ For `anthropic-messages` models the runtime uses a separate `AnthropicCompat` sh
 
 ### Strict tool schemas (`disableStrictTools`)
 
-Anthropic's API supports a `strict` field on tool definitions that forces the model to always follow the provided schema exactly. This is enabled by default for all `anthropic-messages` providers because it guarantees schema conformance in agentic systems.
+Anthropic's API supports a `strict` field on tool definitions that forces the model to always follow the provided schema exactly. OMP enables it by default for a small allowlist of high-frequency built-in `anthropic-messages` tools (`bash`, `python`, `edit`, and `find`) whose schemas fit Anthropic's strict grammar limits; other tools still send normalized schemas but omit `strict`.
 
-Third-party providers that front the Anthropic API (AWS Bedrock, Azure, self-hosted proxies) do not always implement this field and will reject requests that include it. Set `disableStrictTools: true` at the provider level to opt out:
+Third-party providers that front the Anthropic API (AWS Bedrock, Azure, self-hosted proxies) do not always implement this field and will reject requests that include it. Set `disableStrictTools: true` at the provider level to opt out of strict mode for the allowlisted tools:
 
 ```yaml
 providers:
@@ -581,7 +581,7 @@ providers:
           cacheWrite: 3.75
 ```
 
-`disableStrictTools` is a provider-level flag that applies to all models in the provider.
+`disableStrictTools` is a provider-level flag that applies to all models in the provider. It disables the Anthropic `strict` marker only for tools that OMP would otherwise mark strict; it does not change runtime tool argument validation. OMP can automatically retry without strict tools after Anthropic reports a strict-grammar-too-large error before the first streamed token, but proxies that reject the `strict` field for other reasons should set this flag explicitly.
 
 Tool schemas going on the wire are normalized by the unified flow in
 `packages/ai/src/utils/schema/normalize.ts` (Google/CCA/MCP dispatchers
diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 3062ec17d..ab079f2e9 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -19,6 +19,7 @@
 ### Fixed
 
 - Fixed streaming auth retries to handle `401` and usage-limit errors before replay-unsafe content is emitted, including failures surfaced only via `errorStatus`
+- Fixed tool argument validation to coerce singleton non-string values into arrays when the schema expects an array, preventing Anthropic-compatible models that emit `todo.ops` as an object from getting stuck in repeated validation-error loops. ([#2026](https://github.com/can1357/oh-my-pi/issues/2026))
 - Fixed streaming retries to buffer and suppress partial `start` events from failed auth attempts so only clean retried events are delivered
 
 ## [15.10.0] - 2026-06-06
diff --git a/packages/ai/src/utils/validation.ts b/packages/ai/src/utils/validation.ts
index 7f82626ec..ead27b5c5 100644
--- a/packages/ai/src/utils/validation.ts
+++ b/packages/ai/src/utils/validation.ts
@@ -836,12 +836,13 @@ function coerceArgsFromIssues(args: unknown, issues: FlatIssue[]): { value: unkn
 		if (issue.expectedTypes.length === 0) continue;
 
 		const currentValue = getValueAtPointer(nextArgs, issue.instancePath);
-		if (typeof currentValue !== "string") continue;
-
-		const result = tryParseJsonForTypes(currentValue, issue.expectedTypes);
+		const result =
+			typeof currentValue === "string"
+				? tryParseJsonForTypes(currentValue, issue.expectedTypes)
+				: { value: currentValue, changed: false };
 		const coercedValue = result.changed
 			? result.value
-			: issue.expectedTypes.includes("array")
+			: issue.expectedTypes.includes("array") && currentValue !== undefined && !Array.isArray(currentValue)
 				? [currentValue]
 				: undefined;
 		if (coercedValue === undefined) continue;
diff --git a/packages/ai/test/tool-argument-coercion.test.ts b/packages/ai/test/tool-argument-coercion.test.ts
index 224159d5b..8fc123e5b 100644
--- a/packages/ai/test/tool-argument-coercion.test.ts
+++ b/packages/ai/test/tool-argument-coercion.test.ts
@@ -78,6 +78,59 @@ describe("Tool argument coercion", () => {
 		expect(result.paths).toEqual(["src/**/*.ts"]);
 	});
 
+	it("wraps a singleton object in an array when schema expects object array", () => {
+		const tool: Tool = {
+			name: "todo_like",
+			description: "",
+			parameters: z.object({
+				ops: z.array(
+					z.object({
+						op: z.literal("init"),
+						list: z.array(
+							z.object({
+								phase: z.string(),
+								items: z.array(z.string()),
+							}),
+						),
+					}),
+				),
+			}),
+		};
+
+		const result = validateToolArguments(tool, {
+			type: "toolCall",
+			id: "call-singleton-object-array",
+			name: "todo_like",
+			arguments: {
+				ops: {
+					op: "init",
+					list: [{ phase: "Repro", items: ["capture"] }],
+				},
+			},
+		});
+
+		expect(result).toEqual({
+			ops: [{ op: "init", list: [{ phase: "Repro", items: ["capture"] }] }],
+		});
+	});
+
+	it("wraps a singleton number in an array when schema expects number array", () => {
+		const tool: Tool = {
+			name: "numeric_list",
+			description: "",
+			parameters: z.object({ values: z.array(z.number()) }),
+		};
+
+		const result = validateToolArguments(tool, {
+			type: "toolCall",
+			id: "call-singleton-number-array",
+			name: "numeric_list",
+			arguments: { values: 7 },
+		});
+
+		expect(result).toEqual({ values: [7] });
+	});
+
 	it("parses JSON objects in string values when schema expects object", () => {
 		const tool: Tool = {
 			name: "t4",

From bb2a0a0e795e2ef0dd2fba2173693adab012471c Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 06:36:36 +0000
Subject: [PATCH 129/181] fix(ai): preserved union tool argument shape

Skipped singleton array wrapping for expectations that come only from failed Zod union branches so other branch coercions can succeed first.

Fixes #2026
---
 packages/ai/src/utils/validation.ts           | 24 +++++++++++++------
 .../ai/test/tool-argument-coercion.test.ts    | 18 ++++++++++++++
 2 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/packages/ai/src/utils/validation.ts b/packages/ai/src/utils/validation.ts
index ead27b5c5..f87e34406 100644
--- a/packages/ai/src/utils/validation.ts
+++ b/packages/ai/src/utils/validation.ts
@@ -724,6 +724,7 @@ interface FlatIssue {
 	keyword: "type" | "unrecognized" | "other";
 	instancePath: string;
 	expectedTypes: string[];
+	unionBranch: boolean;
 }
 
 /**
@@ -759,12 +760,12 @@ function mapZodExpectedToJsonSchemaType(expected: unknown): string | null {
  */
 function flattenIssues(issues: ReadonlyArray<ZodIssue>): FlatIssue[] {
 	const out: FlatIssue[] = [];
-	const walk = (issue: ZodIssue, prefix: ReadonlyArray<PropertyKey>): void => {
+	const walk = (issue: ZodIssue, prefix: ReadonlyArray<PropertyKey>, unionBranch: boolean): void => {
 		const fullPath = prefix.length === 0 ? issue.path : [...prefix, ...issue.path];
 		if (issue.code === "invalid_type") {
 			const mapped = mapZodExpectedToJsonSchemaType((issue as { expected?: unknown }).expected);
 			if (mapped) {
-				out.push({ keyword: "type", instancePath: pathToPointer(fullPath), expectedTypes: [mapped] });
+				out.push({ keyword: "type", instancePath: pathToPointer(fullPath), expectedTypes: [mapped], unionBranch });
 				return;
 			}
 		}
@@ -775,6 +776,7 @@ function flattenIssues(issues: ReadonlyArray<ZodIssue>): FlatIssue[] {
 					keyword: "unrecognized",
 					instancePath: pathToPointer([...fullPath, key]),
 					expectedTypes: [],
+					unionBranch,
 				});
 			}
 			return;
@@ -784,15 +786,15 @@ function flattenIssues(issues: ReadonlyArray<ZodIssue>): FlatIssue[] {
 			if (inner) {
 				for (const branch of inner) {
 					for (const child of branch) {
-						walk(child, fullPath);
+						walk(child, fullPath, true);
 					}
 				}
 			}
 			return;
 		}
-		out.push({ keyword: "other", instancePath: pathToPointer(fullPath), expectedTypes: [] });
+		out.push({ keyword: "other", instancePath: pathToPointer(fullPath), expectedTypes: [], unionBranch });
 	};
-	for (const issue of issues) walk(issue, []);
+	for (const issue of issues) walk(issue, [], false);
 	return out;
 }
 
@@ -801,7 +803,9 @@ function flattenIssues(issues: ReadonlyArray<ZodIssue>): FlatIssue[] {
  *
  * Two kinds of repair are applied:
  *  - **type**: when a value is a JSON-encoded string and the schema wants
- *    something else, parse it and substitute the parsed value.
+ *    something else, parse it and substitute the parsed value. When a
+ *    non-union schema wants an array but receives a singleton value, wrap that
+ *    value in a one-element array.
  *  - **unrecognized**: when a strict object received an extra key (Zod's
  *    `unrecognized_keys` or JSON Schema's `additionalProperties: false`),
  *    drop that key so re-validation succeeds. This effectively coerces every
@@ -811,6 +815,7 @@ function flattenIssues(issues: ReadonlyArray<ZodIssue>): FlatIssue[] {
  * The function is safe and conservative:
  *   - Only processes "type" and "unrecognized" issues
  *   - Only attempts JSON coercion on string values
+ *   - Only wraps singleton array values for non-union type expectations
  *   - Only accepts parsed results that match the expected type
  *   - Clones the args object before mutation (copy-on-write)
  */
@@ -842,7 +847,10 @@ function coerceArgsFromIssues(args: unknown, issues: FlatIssue[]): { value: unkn
 				: { value: currentValue, changed: false };
 		const coercedValue = result.changed
 			? result.value
-			: issue.expectedTypes.includes("array") && currentValue !== undefined && !Array.isArray(currentValue)
+			: issue.expectedTypes.includes("array") &&
+					!issue.unionBranch &&
+					currentValue !== undefined &&
+					!Array.isArray(currentValue)
 				? [currentValue]
 				: undefined;
 		if (coercedValue === undefined) continue;
@@ -911,12 +919,14 @@ function flattenJsonSchemaIssues(issues: ReadonlyArray<JsonSchemaValidationIssue
 				keyword: "unrecognized",
 				instancePath: pathToPointer(issue.path),
 				expectedTypes: [],
+				unionBranch: false,
 			};
 		}
 		return {
 			keyword: issue.keyword === "type" ? "type" : "other",
 			instancePath: pathToPointer(issue.path),
 			expectedTypes: issue.expectedTypes ?? [],
+			unionBranch: false,
 		};
 	});
 }
diff --git a/packages/ai/test/tool-argument-coercion.test.ts b/packages/ai/test/tool-argument-coercion.test.ts
index 8fc123e5b..7e7e13cf3 100644
--- a/packages/ai/test/tool-argument-coercion.test.ts
+++ b/packages/ai/test/tool-argument-coercion.test.ts
@@ -131,6 +131,24 @@ describe("Tool argument coercion", () => {
 		expect(result).toEqual({ values: [7] });
 	});
 
+	it("does not wrap singleton values for array expectations from failed union branches", () => {
+		const entry = z.object({ id: z.number() });
+		const tool: Tool = {
+			name: "union_shape",
+			description: "",
+			parameters: z.union([z.array(entry), entry]),
+		};
+
+		const result = validateToolArguments(tool, {
+			type: "toolCall",
+			id: "call-union-shape",
+			name: "union_shape",
+			arguments: { id: "1" },
+		});
+
+		expect(result).toEqual({ id: 1 });
+	});
+
 	it("parses JSON objects in string values when schema expects object", () => {
 		const tool: Tool = {
 			name: "t4",

From 9d80a7d5c6cff059ab138886110c93e0721e39d0 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:42:51 +0200
Subject: [PATCH 130/181] perf(packages/tui): optimized tui core by skipping
 redundant work paths

- Added animated message-color gating so loader timers run at 30fps only when needed.
- Added no-op checks in loader and text updates to skip work for unchanged values.
- Optimized key matching by canonicalizing key IDs and precomputing alias sets.
- Added prepared-line caching and bounded terminal/width scans to reduce repaint overhead.
---
 packages/tui/CHANGELOG.md                 |   8 +
 packages/tui/src/components/loader.ts     |  39 ++--
 packages/tui/src/components/text.ts       |   3 +
 packages/tui/src/keybindings.ts           |  60 ++++--
 packages/tui/src/terminal-capabilities.ts |  31 +++-
 packages/tui/src/tui.ts                   | 213 ++++++++++++++++------
 packages/tui/src/utils.ts                 |   3 +-
 7 files changed, 265 insertions(+), 92 deletions(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index bce34b5b8..9ba2fa761 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -20,11 +20,19 @@
 
 ### Changed
 
+- Changed static `Loader` messages to repaint only at the spinner's 80 ms cadence; time-dependent message colorizers can opt into 16 ms redraws with `animated: true`.
+- Changed keybinding matching to precompute canonical key sets so each input sequence is parsed once per binding check instead of once per candidate key.
 - Made `Component.invalidate()` optional so leaf components without render caches no longer need no-op invalidation hooks.
 - `TERMINAL` is now a `RuntimeTerminal` whose post-construction capabilities (image protocol and the probe-driven flags) are writable, replacing the `as unknown as MutableTerminalInfo` cast pattern and the positional `withTerminalOverrides` rebuild with a prototype-preserving `clone()`.
 
 ### Fixed
 
+- Fixed `Loader` text updates to skip identical messages and preserve the rendered `Text` cache instead of invalidating it every timer tick.
+
+- Fixed fullscreen overlay alt-frame rendering to reuse the current line-preparation path instead of calling removed fitting helpers.
+- Reduced TUI render-path line fitting by deferring overlay base-frame fitting until an overlay rebuild and by reusing already-fitted lines in emitters.
+- Reduced live-region pinned repaint output by diffing unchanged viewport rows when no sealed rows are being committed to native scrollback.
+- Optimized terminal image-line detection and Thai/Lao AM normalization checks to avoid hot-path regex scans and substring allocations.
 - Fixed `Markdown.render()` cache hits returning the cache's mutable backing array, which let callers that append extra rows corrupt cached Markdown and duplicate those rows on every redraw.
 - Fixed first-paint full replays for callers that intentionally replace terminal history by allowing `TUI.start({ clearScrollback: true })`, so they do not briefly append an entire initial frame before the first clean replay.
 - Fixed ED3-risk streaming cap accounting to preserve the native scrollback high-water mark for rows that were already physically committed before transient frames were viewport-capped.
diff --git a/packages/tui/src/components/loader.ts b/packages/tui/src/components/loader.ts
index 5f0393a77..1ae5cf4ed 100644
--- a/packages/tui/src/components/loader.ts
+++ b/packages/tui/src/components/loader.ts
@@ -3,21 +3,20 @@ import { sliceByColumn, visibleWidth } from "../utils";
 import { Text } from "./text";
 
 /**
- * Loader component that drives display refresh at ~60fps so callers whose
- * message colorizer is time-dependent (e.g. shimmer/KITT) animate smoothly.
+ * Loader component. Spinner frames advance at `SPINNER_ADVANCE_MS`.
  *
- * Two cadences are interleaved on a single timer:
- *   - **Render tick** (every `RENDER_INTERVAL_MS`) → asks the TUI to redraw.
- *     The TUI already throttles at 16ms (`MIN_RENDER_INTERVAL_MS`), so this
- *     is the natural upper bound; static messageColorFns produce identical
- *     output and the differ drops the no-op redraw at ~zero cost.
- *   - **Spinner advance** (every `SPINNER_ADVANCE_MS`) → bumps the spinner
- *     frame index. Decoupled from the render cadence so the spinner keeps
- *     its classic ~12.5fps step pace regardless of shimmer state.
+ * Message colorizers that are time-dependent can opt into 30fps redraws by
+ * setting `animated` to `true` on the function object.
  */
-const RENDER_INTERVAL_MS = 16;
+const RENDER_INTERVAL_MS = 1000 / 30;
 const SPINNER_ADVANCE_MS = 80;
 
+type ColorFn = (str: string) => string;
+
+export type LoaderMessageColorFn = ColorFn & {
+	readonly animated?: true;
+};
+
 export class Loader extends Text {
 	#frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 	#currentFrame = 0;
@@ -27,8 +26,8 @@ export class Loader extends Text {
 
 	constructor(
 		ui: TUI,
-		private spinnerColorFn: (str: string) => string,
-		private messageColorFn: (str: string) => string,
+		private spinnerColorFn: ColorFn,
+		private messageColorFn: LoaderMessageColorFn,
 		private message: string = "Loading...",
 		spinnerFrames?: string[],
 	) {
@@ -54,14 +53,17 @@ export class Loader extends Text {
 	start() {
 		this.#lastSpinnerTick = performance.now();
 		this.#updateDisplay();
+		const intervalMs = this.messageColorFn.animated === true ? RENDER_INTERVAL_MS : SPINNER_ADVANCE_MS;
 		this.#intervalId = setInterval(() => {
 			const now = performance.now();
-			if (now - this.#lastSpinnerTick >= SPINNER_ADVANCE_MS) {
-				this.#currentFrame = (this.#currentFrame + 1) % this.#frames.length;
-				this.#lastSpinnerTick = now;
+			const elapsed = now - this.#lastSpinnerTick;
+			if (elapsed >= SPINNER_ADVANCE_MS) {
+				const steps = Math.floor(elapsed / SPINNER_ADVANCE_MS);
+				this.#currentFrame = (this.#currentFrame + steps) % this.#frames.length;
+				this.#lastSpinnerTick += steps * SPINNER_ADVANCE_MS;
 			}
 			this.#updateDisplay();
-		}, RENDER_INTERVAL_MS);
+		}, intervalMs);
 	}
 
 	stop() {
@@ -77,6 +79,9 @@ export class Loader extends Text {
 	}
 
 	setMessage(message: string) {
+		if (message === this.message) {
+			return;
+		}
 		this.message = message;
 		this.#updateDisplay();
 	}
diff --git a/packages/tui/src/components/text.ts b/packages/tui/src/components/text.ts
index b41145a53..c90c32f7b 100644
--- a/packages/tui/src/components/text.ts
+++ b/packages/tui/src/components/text.ts
@@ -27,6 +27,9 @@ export class Text implements Component {
 	}
 
 	setText(text: string): void {
+		if (text === this.#text) {
+			return;
+		}
 		this.#text = text;
 		this.#cachedText = undefined;
 		this.#cachedWidth = undefined;
diff --git a/packages/tui/src/keybindings.ts b/packages/tui/src/keybindings.ts
index 134965c42..1e097bad8 100644
--- a/packages/tui/src/keybindings.ts
+++ b/packages/tui/src/keybindings.ts
@@ -1,4 +1,4 @@
-import { type KeyId, matchesKey, parseKey } from "./keys";
+import { type KeyId, parseKey } from "./keys";
 
 /**
  * Global keybinding registry.
@@ -164,6 +164,44 @@ const SHIFTED_SYMBOL_KEYS = new Set<string>([
 	"~",
 ]);
 
+const MODIFIER_ORDER = ["ctrl", "shift", "alt", "super"] as const;
+
+function canonicalKeyId(key: string): string {
+	let remaining = key.toLowerCase();
+	const modifiers: string[] = [];
+	let foundModifier = true;
+
+	while (foundModifier) {
+		foundModifier = false;
+		for (const modifier of MODIFIER_ORDER) {
+			const prefix = `${modifier}+`;
+			if (remaining.startsWith(prefix)) {
+				modifiers.push(modifier);
+				remaining = remaining.slice(prefix.length);
+				foundModifier = true;
+				break;
+			}
+		}
+	}
+	const base = remaining === "esc" ? "escape" : remaining === "return" ? "enter" : remaining;
+
+	if (modifiers.length === 0) return base;
+	modifiers.sort(
+		(left, right) =>
+			MODIFIER_ORDER.indexOf(left as (typeof MODIFIER_ORDER)[number]) -
+			MODIFIER_ORDER.indexOf(right as (typeof MODIFIER_ORDER)[number]),
+	);
+	return `${modifiers.join("+")}+${base}`;
+}
+
+function addKeyAliases(keys: Set<string>, key: KeyId): void {
+	const canonical = canonicalKeyId(key);
+	keys.add(canonical);
+	if (SHIFTED_SYMBOL_KEYS.has(canonical)) {
+		keys.add(`shift+${canonical}`);
+	}
+}
+
 const normalizeKeyId = (key: KeyId): KeyId => key.toLowerCase() as KeyId;
 
 function normalizeKeys(keys: KeyId | KeyId[] | undefined): KeyId[] {
@@ -185,6 +223,7 @@ export class KeybindingsManager {
 	#definitions: KeybindingDefinitions;
 	#userBindings: KeybindingsConfig;
 	#keysById = new Map<Keybinding, KeyId[]>();
+	#matchKeysById = new Map<Keybinding, Set<string>>();
 	#conflicts: KeybindingConflict[] = [];
 
 	constructor(definitions: KeybindingDefinitions, userBindings: KeybindingsConfig = {}) {
@@ -195,6 +234,7 @@ export class KeybindingsManager {
 
 	#rebuild(): void {
 		this.#keysById.clear();
+		this.#matchKeysById.clear();
 		this.#conflicts = [];
 
 		const userClaims = new Map<KeyId, Set<Keybinding>>();
@@ -217,21 +257,19 @@ export class KeybindingsManager {
 			const userKeys = this.#userBindings[id];
 			const keys = userKeys === undefined ? normalizeKeys(definition.defaultKeys) : normalizeKeys(userKeys);
 			this.#keysById.set(id as Keybinding, keys);
+			const matchKeys = new Set<string>();
+			for (const key of keys) {
+				addKeyAliases(matchKeys, key);
+			}
+			this.#matchKeysById.set(id as Keybinding, matchKeys);
 		}
 	}
 
 	matches(data: string, keybinding: Keybinding): boolean {
-		const keys = this.#keysById.get(keybinding) ?? [];
-		for (const key of keys) {
-			if (matchesKey(data, key)) return true;
-		}
-
-		// Handle shifted symbol keys (e.g., shift+- produces _ on US layout)
 		const parsed = parseKey(data);
-		if (!parsed?.startsWith("shift+")) return false;
-		const keyName = parsed.slice("shift+".length);
-		if (!SHIFTED_SYMBOL_KEYS.has(keyName)) return false;
-		return keys.includes(keyName as KeyId);
+		if (parsed === undefined) return false;
+		const matchKeys = this.#matchKeysById.get(keybinding);
+		return matchKeys?.has(canonicalKeyId(parsed)) ?? false;
 	}
 
 	getKeys(keybinding: Keybinding): KeyId[] {
diff --git a/packages/tui/src/terminal-capabilities.ts b/packages/tui/src/terminal-capabilities.ts
index 599fa81fb..6b429d7cc 100644
--- a/packages/tui/src/terminal-capabilities.ts
+++ b/packages/tui/src/terminal-capabilities.ts
@@ -23,7 +23,31 @@ export enum NotifyProtocol {
 
 export type TerminalId = "kitty" | "ghostty" | "wezterm" | "iterm2" | "vscode" | "alacritty" | "base" | "trueColor";
 
-const SIXEL_DCS_START_REGEX = /\x1bP(?:[0-9;]*)q/u;
+function hasNeedleBefore(line: string, needle: string, limit: number): boolean {
+	const index = line.indexOf(needle);
+	return index !== -1 && index + needle.length <= limit;
+}
+
+function hasSixelDcsStart(line: string): boolean {
+	const limit = Math.min(line.length, 128);
+	let from = 0;
+	for (;;) {
+		const start = line.indexOf("\x1bP", from);
+		if (start === -1 || start + 3 > limit) return false;
+		let i = start + 2;
+		while (i < limit) {
+			const code = line.charCodeAt(i);
+			if ((code >= 0x30 && code <= 0x39) || code === 0x3b) {
+				i++;
+				continue;
+			}
+			break;
+		}
+		if (i < limit && line.charCodeAt(i) === 0x71) return true;
+		from = start + 2;
+	}
+}
+
 /** Terminal capability details used for rendering and protocol selection. */
 export class TerminalInfo {
 	constructor(
@@ -61,10 +85,9 @@ export class TerminalInfo {
 	isImageLine(line: string): boolean {
 		if (!this.imageProtocol) return false;
 		if (this.imageProtocol === ImageProtocol.Sixel) {
-			return SIXEL_DCS_START_REGEX.test(line.slice(0, 128));
+			return hasSixelDcsStart(line);
 		}
-		const head = line.slice(0, 64);
-		return head.includes(this.imageProtocol) || head.includes(KITTY_PLACEHOLDER);
+		return hasNeedleBefore(line, this.imageProtocol, 64) || hasNeedleBefore(line, KITTY_PLACEHOLDER, 64);
 	}
 
 	formatNotification(message: string | TerminalNotification): string {
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index a2c9834c5..9fa0129cc 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -39,10 +39,10 @@ import {
 
 const SEGMENT_RESET = "\x1b[0m";
 /**
- * Per-line terminator written at the end of every non-image line. Closes both
+ * Per-line terminator written after every non-image content row. It closes both
  * SGR state and any in-flight OSC 8 hyperlink so styles/links cannot bleed
- * across lines in scrollback. Applied by {@link TUI.#applyLineResets} before
- * diffing so `#previousLines` mirrors what was actually written.
+ * across lines in scrollback. Kept out of the diff/width cache because reset
+ * bytes are deterministic write framing, not content.
  */
 const LINE_TERMINATOR = "\x1b[0m\x1b]8;;\x07";
 const ERASE_LINE = "\x1b[2K";
@@ -433,6 +433,12 @@ type RenderIntent =
 	| { kind: "shrink" }
 	| { kind: "diff"; firstChanged: number; lastChanged: number; appendedLines: boolean };
 
+interface PreparedLine {
+	raw: string;
+	width: number;
+	line: string;
+}
+
 /**
  * TUI - Main class for managing terminal UI with differential rendering
  */
@@ -451,7 +457,7 @@ export class TUI extends Container {
 	#renderTimer: RenderTimer | undefined;
 	#renderScheduler: RenderScheduler;
 	#lastRenderAt = 0;
-	static readonly #MIN_RENDER_INTERVAL_MS = 16;
+	static readonly #MIN_RENDER_INTERVAL_MS = 1000 / 30;
 	#cursorRow = 0; // Logical cursor row (end of rendered content)
 	#hardwareCursorRow = 0; // Actual terminal cursor row (may differ due to IME positioning)
 	#viewportTopRow = 0; // Content row currently mapped to screen row 0
@@ -525,6 +531,11 @@ export class TUI extends Container {
 	#altEnterWidth = 0;
 	#altEnterHeight = 0;
 
+	// Last-frame line preparation cache. Entries store normalized, width-fitted
+	// content rows without the per-line terminal terminator; terminators are
+	// appended only at write time so width checks stay on content, not reset bytes.
+	#preparedLineCache: PreparedLine[] = [];
+
 	// Overlay stack for modal components rendered on top of base content
 	overlayStack: {
 		component: Component;
@@ -808,7 +819,7 @@ export class TUI extends Container {
 				// Repaint immediately rather than via the throttled path: a resize must
 				// clear and replay at the fresh geometry before the terminal's reflow
 				// settles into a state a throttled frame would race. Forced render skips
-				// the 16ms coalescing window, matching resetDisplay()'s prompt repaint.
+				// the 30fps coalescing window, matching resetDisplay()'s prompt repaint.
 				this.#resizeEventPending = true;
 				this.requestRender(true);
 			},
@@ -1528,24 +1539,9 @@ export class TUI extends Container {
 		return cursor;
 	}
 
-	/**
-	 * Append the per-line terminator ({@link LINE_TERMINATOR}) to every
-	 * non-image line and normalize for terminal rendering. Mutates the input
-	 * array in place so downstream diffing/storage sees exactly the bytes
-	 * written to the terminal — without this, the diff cache disagrees with
-	 * emitted output and OSC 8 hyperlink state can leak across lines.
-	 */
-	#applyLineResets(lines: string[]): string[] {
-		for (let i = 0; i < lines.length; i++) {
-			const line = lines[i];
-			if (TERMINAL.isImageLine(line)) continue;
-			const normalized = normalizeTerminalOutput(line);
-			// Only close OSC 8 hyperlinks when the line actually opened one;
-			// emitting `\x1b]8;;\x07` on every line just feeds the terminal's OSC
-			// parser for no reason (measurable cost in xterm.js parse loop).
-			lines[i] = normalized + (normalized.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
-		}
-		return lines;
+	#terminalLine(line: string): string {
+		if (TERMINAL.isImageLine(line)) return line;
+		return line + (line.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
 	}
 
 	/**
@@ -1608,11 +1604,7 @@ export class TUI extends Container {
 		const overlayVisibilityReduced = this.#overlayVisibilityReduced(visibleOverlayComponents);
 		let lines = visibleOverlayComponents.length > 0 ? this.#compositeOverlays(baseLines, width, height) : baseLines;
 		const cursorPos = this.#extractCursorPosition(lines, height);
-		lines = this.#fitLinesToWidth(this.#applyLineResets(lines), width);
-		if (lines !== baseLines) {
-			this.#extractCursorPosition(baseLines, height);
-			baseLines = this.#fitLinesToWidth(this.#applyLineResets(baseLines), width);
-		}
+		lines = this.#prepareLines(lines, width, true);
 
 		// 2. Capture transition + pre-render state before any emitter runs.
 		const prevViewportTop = this.#viewportTopRow;
@@ -1793,6 +1785,8 @@ export class TUI extends Container {
 				return;
 			case "overlayRebuild":
 				this.#clearNativeScrollbackDirty();
+				this.#extractCursorPosition(baseLines, height);
+				baseLines = this.#prepareLines(baseLines, width, false);
 				this.#emitFullPaint(baseLines, width, height, null, {
 					clearViewport: true,
 					clearScrollback: !isMultiplexerSession(),
@@ -1814,7 +1808,7 @@ export class TUI extends Container {
 				return;
 			case "viewportRepaint":
 				if (intent.appendFrom !== undefined) {
-					this.#emitAppendTail(lines, intent.appendFrom, height, width, prevViewportTop, prevHardwareCursorRow);
+					this.#emitAppendTail(lines, intent.appendFrom, height, prevViewportTop, prevHardwareCursorRow);
 				}
 				this.#emitViewportRepaint(lines, width, height, cursorPos);
 				return;
@@ -2460,31 +2454,98 @@ export class TUI extends Container {
 		if (lines.length >= paddedLength) return lines;
 		return [...lines, ...new Array<string>(paddedLength - lines.length).fill("")];
 	}
-	/**
-	 * Truncate a line to the visible viewport width. Image lines are left
-	 * alone, narrow lines pass through unchanged. Truncation re-appends the
-	 * per-line terminator so SGR/OSC 8 state does not leak across rows when
-	 * `truncateToWidth` drops the trailing bytes appended by
-	 * {@link #applyLineResets}.
-	 */
-	#fitLinesToWidth(lines: string[], width: number): string[] {
+	#prepareLines(lines: string[], width: number, useCache: boolean): string[] {
+		const prepared: string[] = new Array(lines.length);
+		const previous = useCache ? this.#preparedLineCache : [];
+		const nextCache: PreparedLine[] | undefined = useCache ? new Array(lines.length) : undefined;
 		for (let i = 0; i < lines.length; i++) {
-			lines[i] = this.#fitLineToWidth(lines[i], width);
+			const raw = lines[i]!;
+			const cached = previous[i];
+			if (cached && cached.raw === raw && cached.width === width) {
+				prepared[i] = cached.line;
+				if (nextCache) nextCache[i] = cached;
+				continue;
+			}
+			const entry = this.#prepareLine(raw, width);
+			prepared[i] = entry.line;
+			if (nextCache) nextCache[i] = entry;
 		}
-		return lines;
+		if (nextCache) this.#preparedLineCache = nextCache;
+		return prepared;
 	}
 
-	#fitLineToWidth(line: string, width: number): string {
-		if (TERMINAL.isImageLine(line)) return line;
-		if (visibleWidth(line) <= width) return line;
-		const truncated = truncateToWidth(line, width, Ellipsis.Omit);
-		return truncated + (truncated.includes("\x1b]8;") ? LINE_TERMINATOR : SEGMENT_RESET);
+	#prepareLine(raw: string, width: number): PreparedLine {
+		if (TERMINAL.isImageLine(raw)) {
+			return { raw, width, line: raw };
+		}
+		const normalized = normalizeTerminalOutput(raw);
+		const asciiWidth = this.#ansiAsciiLineWidth(normalized, width);
+		if ((asciiWidth ?? visibleWidth(normalized)) <= width) {
+			return { raw, width, line: normalized };
+		}
+		const line = truncateToWidth(normalized, width, Ellipsis.Omit);
+		return { raw, width, line };
+	}
+
+	#ansiAsciiLineWidth(line: string, maxWidth: number): number | undefined {
+		let col = 0;
+		for (let i = 0; i < line.length; ) {
+			const code = line.charCodeAt(i);
+			if (code === 0x1b) {
+				const next = line.charCodeAt(i + 1);
+				if (next === 0x5b) {
+					let j = i + 2;
+					while (j < line.length) {
+						const final = line.charCodeAt(j);
+						if (final >= 0x40 && final <= 0x7e) break;
+						j++;
+					}
+					if (j >= line.length) return undefined;
+					i = j + 1;
+					continue;
+				}
+				if (next === 0x5d) {
+					// OSC 66 text-sizing spans carry visible payload inside the OSC.
+					// Fall back to visibleWidth() so scaled cells stay exact.
+					if (
+						line.charCodeAt(i + 2) === 0x36 &&
+						line.charCodeAt(i + 3) === 0x36 &&
+						line.charCodeAt(i + 4) === 0x3b
+					) {
+						return undefined;
+					}
+					let j = i + 2;
+					while (j < line.length) {
+						const osc = line.charCodeAt(j);
+						if (osc === 0x07) {
+							i = j + 1;
+							break;
+						}
+						if (osc === 0x1b && line.charCodeAt(j + 1) === 0x5c) {
+							i = j + 2;
+							break;
+						}
+						j++;
+					}
+					if (j >= line.length) return undefined;
+					continue;
+				}
+				return undefined;
+			}
+			if (code < 0x20 || code > 0x7e) return undefined;
+			col++;
+			if (col > maxWidth) return col;
+			i++;
+		}
+		return col;
 	}
 
 	#lineRewriteSequence(line: string, width: number): string {
-		const fitted = this.#fitLineToWidth(line, width);
-		if (TERMINAL.isImageLine(fitted)) return ERASE_LINE + fitted;
-		return visibleWidth(fitted) >= width ? fitted : fitted + ERASE_TO_END_OF_LINE;
+		if (TERMINAL.isImageLine(line)) return ERASE_LINE + line;
+		const terminalLine = this.#terminalLine(line);
+		const asciiWidth = this.#ansiAsciiLineWidth(line, width);
+		const lineWidth = asciiWidth ?? visibleWidth(line);
+		return lineWidth >= width ? terminalLine : terminalLine + ERASE_TO_END_OF_LINE;
 	}
 
 	/**
@@ -2550,7 +2611,7 @@ export class TUI extends Container {
 		if (this.#deccaraFillsEnabled() && visibleStart < lines.length) {
 			const visible: string[] = new Array(lines.length - visibleStart);
 			for (let k = 0; k < visible.length; k++) {
-				visible[k] = this.#fitLineToWidth(lines[visibleStart + k], width);
+				visible[k] = lines[visibleStart + k] ?? "";
 			}
 			const plan = planDeccaraFills(visible, width);
 			visibleTexts = plan.texts;
@@ -2558,8 +2619,9 @@ export class TUI extends Container {
 		}
 		for (let i = 0; i < lines.length; i++) {
 			if (i > 0) buffer += "\r\n";
-			buffer +=
-				visibleTexts && i >= visibleStart ? visibleTexts[i - visibleStart] : this.#fitLineToWidth(lines[i], width);
+			buffer += this.#terminalLine(
+				visibleTexts && i >= visibleStart ? visibleTexts[i - visibleStart] : (lines[i] ?? ""),
+			);
 		}
 		buffer += fillSequence;
 		const finalRow = Math.max(0, lines.length - 1);
@@ -2608,12 +2670,12 @@ export class TUI extends Container {
 		let wroteLine = false;
 		for (let i = 0; i < appendTo; i++) {
 			if (wroteLine) buffer += "\r\n";
-			buffer += this.#fitLineToWidth(lines[i] ?? "", width);
+			buffer += this.#terminalLine(lines[i] ?? "");
 			wroteLine = true;
 		}
 		for (let screenRow = 0; screenRow < height; screenRow++) {
 			if (wroteLine) buffer += "\r\n";
-			buffer += this.#fitLineToWidth(lines[viewportTop + screenRow] ?? "", width);
+			buffer += this.#terminalLine(lines[viewportTop + screenRow] ?? "");
 			wroteLine = true;
 		}
 
@@ -2664,7 +2726,7 @@ export class TUI extends Container {
 		// Each visible screen row, bottom-anchored, blank past content.
 		const visible: string[] = new Array(height);
 		for (let screenRow = 0; screenRow < height; screenRow++) {
-			visible[screenRow] = this.#fitLineToWidth(lines[viewportTop + screenRow] ?? "", width);
+			visible[screenRow] = lines[viewportTop + screenRow] ?? "";
 		}
 		const { texts, sequence } = this.#deccaraFillsEnabled()
 			? planDeccaraFills(visible, width)
@@ -2723,7 +2785,7 @@ export class TUI extends Container {
 		const base: string[] = new Array(Math.max(0, height)).fill("");
 		let lines = this.#compositeOverlays(base, width, height);
 		this.#extractCursorPosition(lines, height);
-		lines = this.#fitLinesToWidth(this.#applyLineResets(lines), width);
+		lines = this.#prepareLines(lines, width, false);
 		this.#emitAltFrame(lines, width, height);
 	}
 
@@ -2735,7 +2797,7 @@ export class TUI extends Container {
 	 */
 	#emitAltFrame(lines: string[], width: number, height: number): void {
 		const fitted: string[] = new Array(height);
-		for (let r = 0; r < height; r++) fitted[r] = this.#fitLineToWidth(lines[r] ?? "", width);
+		for (let r = 0; r < height; r++) fitted[r] = lines[r] ?? "";
 		// Skip an identical repaint (the modal is mostly static between keystrokes).
 		if (this.#altPreviousLines.length === height) {
 			let same = true;
@@ -2787,6 +2849,42 @@ export class TUI extends Container {
 		const boundedAppendTo = Math.max(0, Math.min(appendTo, naturalViewportTop, lines.length));
 		const boundedAppendFrom = Math.max(0, Math.min(appendFrom, boundedAppendTo));
 
+		if (boundedAppendFrom === boundedAppendTo) {
+			let firstChangedScreenRow = -1;
+			let lastChangedScreenRow = -1;
+			for (let screenRow = 0; screenRow < height; screenRow++) {
+				const nextLine = lines[viewportTop + screenRow] ?? "";
+				const previousLine = this.#previousLines[prevViewportTop + screenRow] ?? "";
+				if (nextLine === previousLine) continue;
+				if (firstChangedScreenRow === -1) firstChangedScreenRow = screenRow;
+				lastChangedScreenRow = screenRow;
+			}
+
+			let buffer = this.#paintBeginSequence;
+			let cursorFromRow = prevHardwareCursorRow;
+			if (firstChangedScreenRow !== -1) {
+				const clampedCursor = Math.min(prevHardwareCursorRow, prevViewportTop + height - 1);
+				const currentScreenRow = Math.max(0, Math.min(height - 1, clampedCursor - prevViewportTop));
+				const rowDelta = firstChangedScreenRow - currentScreenRow;
+				if (rowDelta > 0) buffer += `\x1b[${rowDelta}B`;
+				else if (rowDelta < 0) buffer += `\x1b[${-rowDelta}A`;
+				buffer += "\r";
+				for (let screenRow = firstChangedScreenRow; screenRow <= lastChangedScreenRow; screenRow++) {
+					if (screenRow > firstChangedScreenRow) buffer += "\r\n";
+					buffer += this.#lineRewriteSequence(lines[viewportTop + screenRow] ?? "", width);
+				}
+				cursorFromRow = viewportTop + lastChangedScreenRow;
+			}
+			const { seq, toRow } = this.#cursorControlSequence(cursorPos, lines.length, cursorFromRow);
+			buffer += seq;
+			buffer += this.#paintEndSequence;
+			this.terminal.write(buffer);
+
+			this.#maxLinesRendered = Math.max(lines.length, viewportTop + height);
+			this.#commit(lines, width, height, viewportTop, toRow);
+			return;
+		}
+
 		// Position at the top visible row with a relative move. Terminals clamp the
 		// hardware cursor to the viewport on resize, so clamp our tracking to match
 		// before computing the delta (mirrors #emitDiff).
@@ -2839,7 +2937,6 @@ export class TUI extends Container {
 		lines: string[],
 		start: number,
 		height: number,
-		width: number,
 		prevViewportTop: number,
 		prevHardwareCursorRow: number,
 	): void {
@@ -2854,7 +2951,7 @@ export class TUI extends Container {
 		if (moveToBottom > 0) buffer += `\x1b[${moveToBottom}B`;
 		for (let i = start; i < lines.length; i++) {
 			buffer += "\r\n";
-			buffer += this.#fitLineToWidth(lines[i], width);
+			buffer += this.#terminalLine(lines[i] ?? "");
 		}
 		buffer += this.#paintEndSequence;
 		this.terminal.write(buffer);
@@ -3039,7 +3136,7 @@ export class TUI extends Container {
 		) {
 			const slice: string[] = new Array(renderEnd - fillStart + 1);
 			for (let i = fillStart; i <= renderEnd; i++) {
-				slice[i - fillStart] = this.#fitLineToWidth(lines[i], width);
+				slice[i - fillStart] = lines[i] ?? "";
 			}
 			const plan = planDeccaraFills(slice, width, fillStart - fillViewportTop);
 			fillTexts = plan.texts;
diff --git a/packages/tui/src/utils.ts b/packages/tui/src/utils.ts
index 47a6e484b..243741dd3 100644
--- a/packages/tui/src/utils.ts
+++ b/packages/tui/src/utils.ts
@@ -251,7 +251,6 @@ export function visibleWidth(str: string): number {
 	return width;
 }
 
-const THAI_LAO_AM_REGEX = /[\u0e33\u0eb3]/;
 const THAI_LAO_AM_GLOBAL_REGEX = /[\u0e33\u0eb3]/g;
 
 /**
@@ -261,7 +260,7 @@ const THAI_LAO_AM_GLOBAL_REGEX = /[\u0e33\u0eb3]/g;
  * width but avoid stale-cell artifacts in terminal renderers.
  */
 export function normalizeTerminalOutput(str: string): string {
-	if (!THAI_LAO_AM_REGEX.test(str)) return str;
+	if (str.indexOf("\u0e33") === -1 && str.indexOf("\u0eb3") === -1) return str;
 	return str.replace(THAI_LAO_AM_GLOBAL_REGEX, char => (char === "\u0e33" ? "\u0e4d\u0e32" : "\u0ecd\u0eb2"));
 }
 

From 9b98dafe4eb85a397bb4f73b73d3e1c3f7ede28f Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:42:51 +0200
Subject: [PATCH 131/181] test(packages/tui): updated tui test timing for 30fps
 render cadence

- Updated settle helpers in repro tests to wait 40ms before terminal flush.
- Raised process-terminal-render-harness SETTLE_MS to 67ms for 30fps timing.
- Updated render-throttle mocks to advance mock time by 40ms per frame.
- Added Loader component cadence test for 30fps animated repaint timing.
- Added render-regressions check that non-force renders are scheduled at ~33ms.
---
 packages/tui/test/deccara.test.ts             |  2 +-
 packages/tui/test/issue-1610-repro.test.ts    |  2 +-
 packages/tui/test/issue-1635-repro.test.ts    |  2 +-
 packages/tui/test/issue-1682-repro.test.ts    |  2 +-
 packages/tui/test/issue-1746-repro.test.ts    |  2 +-
 packages/tui/test/issue-1962-repro.test.ts    |  2 +-
 packages/tui/test/issue-1974-repro.test.ts    |  2 +-
 packages/tui/test/loader.test.ts              | 22 +++++++++++--
 .../test/process-terminal-render-harness.ts   |  4 +--
 packages/tui/test/render-regressions.test.ts  | 31 +++++++++++++++----
 .../test/slash-autocomplete-viewport.test.ts  |  9 +++---
 packages/tui/test/virtual-terminal.ts         |  4 +--
 12 files changed, 60 insertions(+), 24 deletions(-)

diff --git a/packages/tui/test/deccara.test.ts b/packages/tui/test/deccara.test.ts
index f1d0329f2..b95bb1b23 100644
--- a/packages/tui/test/deccara.test.ts
+++ b/packages/tui/test/deccara.test.ts
@@ -49,7 +49,7 @@ async function settle(term: VirtualTerminal): Promise<void> {
 	const nextTick = Promise.withResolvers<void>();
 	process.nextTick(nextTick.resolve);
 	await nextTick.promise;
-	await Bun.sleep(1);
+	await Bun.sleep(40);
 	await term.flush();
 }
 
diff --git a/packages/tui/test/issue-1610-repro.test.ts b/packages/tui/test/issue-1610-repro.test.ts
index a73b3bf23..5a7b38ad2 100644
--- a/packages/tui/test/issue-1610-repro.test.ts
+++ b/packages/tui/test/issue-1610-repro.test.ts
@@ -36,7 +36,7 @@ async function settle(term: VirtualTerminal): Promise<void> {
 	const nextTick = Promise.withResolvers<void>();
 	process.nextTick(nextTick.resolve);
 	await nextTick.promise;
-	await Bun.sleep(20);
+	await Bun.sleep(40);
 	await term.flush();
 }
 
diff --git a/packages/tui/test/issue-1635-repro.test.ts b/packages/tui/test/issue-1635-repro.test.ts
index d455fc9de..ef196d2d7 100644
--- a/packages/tui/test/issue-1635-repro.test.ts
+++ b/packages/tui/test/issue-1635-repro.test.ts
@@ -49,7 +49,7 @@ async function settle(term: VirtualTerminal): Promise<void> {
 	const nextTick = Promise.withResolvers<void>();
 	process.nextTick(nextTick.resolve);
 	await nextTick.promise;
-	await Bun.sleep(20);
+	await Bun.sleep(40);
 	await term.flush();
 }
 
diff --git a/packages/tui/test/issue-1682-repro.test.ts b/packages/tui/test/issue-1682-repro.test.ts
index 5615f1f59..84780790d 100644
--- a/packages/tui/test/issue-1682-repro.test.ts
+++ b/packages/tui/test/issue-1682-repro.test.ts
@@ -55,7 +55,7 @@ async function settle(term: VirtualTerminal): Promise<void> {
 	const nextTick = Promise.withResolvers<void>();
 	process.nextTick(nextTick.resolve);
 	await nextTick.promise;
-	await Bun.sleep(20);
+	await Bun.sleep(40);
 	await term.flush();
 }
 
diff --git a/packages/tui/test/issue-1746-repro.test.ts b/packages/tui/test/issue-1746-repro.test.ts
index b6a412e9e..8616f172f 100644
--- a/packages/tui/test/issue-1746-repro.test.ts
+++ b/packages/tui/test/issue-1746-repro.test.ts
@@ -49,7 +49,7 @@ async function settle(term: VirtualTerminal): Promise<void> {
 	const nextTick = Promise.withResolvers<void>();
 	process.nextTick(nextTick.resolve);
 	await nextTick.promise;
-	await Bun.sleep(20);
+	await Bun.sleep(40);
 	await term.flush();
 }
 
diff --git a/packages/tui/test/issue-1962-repro.test.ts b/packages/tui/test/issue-1962-repro.test.ts
index 08085a258..bbceb4ca4 100644
--- a/packages/tui/test/issue-1962-repro.test.ts
+++ b/packages/tui/test/issue-1962-repro.test.ts
@@ -53,7 +53,7 @@ async function settle(term: VirtualTerminal): Promise<void> {
 	const nextTick = Promise.withResolvers<void>();
 	process.nextTick(nextTick.resolve);
 	await nextTick.promise;
-	await Bun.sleep(20);
+	await Bun.sleep(40);
 	await term.flush();
 }
 
diff --git a/packages/tui/test/issue-1974-repro.test.ts b/packages/tui/test/issue-1974-repro.test.ts
index 9511d3f4e..915d93814 100644
--- a/packages/tui/test/issue-1974-repro.test.ts
+++ b/packages/tui/test/issue-1974-repro.test.ts
@@ -74,7 +74,7 @@ async function settle(term: VirtualTerminal): Promise<void> {
 	const nextTick = Promise.withResolvers<void>();
 	process.nextTick(nextTick.resolve);
 	await nextTick.promise;
-	await Bun.sleep(20);
+	await Bun.sleep(40);
 	await term.flush();
 }
 
diff --git a/packages/tui/test/loader.test.ts b/packages/tui/test/loader.test.ts
index 7081d68ca..20fc98851 100644
--- a/packages/tui/test/loader.test.ts
+++ b/packages/tui/test/loader.test.ts
@@ -1,10 +1,15 @@
-import { describe, expect, it, spyOn } from "bun:test";
+import { afterEach, describe, expect, it, spyOn, vi } from "bun:test";
 import { TUI } from "@oh-my-pi/pi-tui";
-import { Loader } from "@oh-my-pi/pi-tui/components/loader";
+import { Loader, type LoaderMessageColorFn } from "@oh-my-pi/pi-tui/components/loader";
 import { visibleWidth } from "@oh-my-pi/pi-tui/utils";
 import { VirtualTerminal } from "./virtual-terminal";
 
 describe("Loader component", () => {
+	afterEach(() => {
+		vi.useRealTimers();
+		vi.restoreAllMocks();
+	});
+
 	it("clamps rendered lines to terminal width", async () => {
 		const term = new VirtualTerminal(1, 4);
 		const tui = new TUI(term);
@@ -29,6 +34,19 @@ describe("Loader component", () => {
 		tui.stop();
 	});
 
+	it("keeps spinner cadence when animated messages repaint at 30fps", () => {
+		vi.useFakeTimers();
+		const ui = { requestRender: vi.fn() } as unknown as TUI;
+		const colorMessage = ((text: string) => text) as LoaderMessageColorFn & { animated: true };
+		colorMessage.animated = true;
+		const loader = new Loader(ui, text => text, colorMessage, "Checking", ["0", "1", "2", "3"]);
+
+		vi.advanceTimersByTime(170);
+
+		expect(loader.render(20).join("\n")).toContain("2 Checking");
+		loader.stop();
+	});
+
 	it("dispose() stops the animation so no further renders are scheduled", async () => {
 		const term = new VirtualTerminal(20, 4);
 		const tui = new TUI(term);
diff --git a/packages/tui/test/process-terminal-render-harness.ts b/packages/tui/test/process-terminal-render-harness.ts
index 56803f77a..15c2ab91a 100644
--- a/packages/tui/test/process-terminal-render-harness.ts
+++ b/packages/tui/test/process-terminal-render-harness.ts
@@ -13,10 +13,10 @@ const PRISTINE: Array<[NodeJS.Process["stdin"] | NodeJS.Process["stdout"], strin
 	[process.stdout, "rows", Object.getOwnPropertyDescriptor(process.stdout, "rows")],
 ];
 
-// One frame interval is 16ms (TUI.#MIN_RENDER_INTERVAL_MS); two frames of
+// One frame interval is ~33ms (TUI.#MIN_RENDER_INTERVAL_MS); two frames of
 // headroom keeps the scheduler-driven paint deterministic without slowing the
 // suite materially.
-const SETTLE_MS = 32;
+const SETTLE_MS = 67;
 
 /**
  * A root component that records the width it is asked to render at. The renderer
diff --git a/packages/tui/test/render-regressions.test.ts b/packages/tui/test/render-regressions.test.ts
index 13fd93365..79e6385f7 100644
--- a/packages/tui/test/render-regressions.test.ts
+++ b/packages/tui/test/render-regressions.test.ts
@@ -213,12 +213,12 @@ async function withTerminalRisk<T>(risk: boolean, run: () => T | Promise<T>): Pr
 
 describe("TUI terminal-state regressions", () => {
 	let monotonicNow = 0;
-	// Keep TUI's 16ms render throttle deterministic without sleeping a real frame per render.
+	// Keep TUI's ~33ms render throttle deterministic without sleeping a real frame per render.
 
 	beforeEach(() => {
 		monotonicNow = 0;
 		vi.spyOn(performance, "now").mockImplementation(() => {
-			monotonicNow += 20;
+			monotonicNow += 40;
 			return monotonicNow;
 		});
 	});
@@ -227,6 +227,25 @@ describe("TUI terminal-state regressions", () => {
 		vi.restoreAllMocks();
 	});
 
+	it("coalesces non-force render requests to 30fps", () => {
+		const delays: number[] = [];
+		const renderScheduler = {
+			now: () => 0,
+			scheduleImmediate: (callback: () => void) => callback(),
+			scheduleRender: (_callback: () => void, delayMs: number) => {
+				delays.push(delayMs);
+				return { cancel: () => {} };
+			},
+		};
+		const tui = new TUI(new VirtualTerminal(20, 4), true, { renderScheduler });
+
+		tui.requestRender();
+
+		expect(delays).toHaveLength(1);
+		expect(delays[0]!).toBeCloseTo(1000 / 30, 5);
+		tui.stop();
+	});
+
 	describe("cursor + differential stability", () => {
 		it("keeps stable output across repeated no-op renders", async () => {
 			const term = new VirtualTerminal(40, 10);
@@ -1119,7 +1138,7 @@ describe("TUI terminal-state regressions", () => {
 
 		it("keeps appended rows contiguous when a height grow coincides with new content", async () => {
 			// A terminal resize fires requestRender(), and streamed content fires
-			// its own requestRender(); the 16ms throttle coalesces them into a
+			// its own requestRender(); the ~33ms throttle coalesces them into a
 			// single frame that is both taller and longer. The diff/append-tail
 			// emitters position scrolled rows against the previous viewport top and
 			// hardware cursor row, both invalidated by the reflow — so the appended
@@ -1474,7 +1493,7 @@ describe("TUI terminal-state regressions", () => {
 						await settle(term);
 
 						// SIGWINCH (height shrink) and a streamed token arrive inside the
-						// same 16ms frame budget. The TUI's own resize handler schedules a
+						// same ~33ms frame budget. The TUI's own resize handler schedules a
 						// non-forced render; the append rides along.
 						lines.push("line-40 streamed");
 						component.setLines(lines);
@@ -4181,7 +4200,7 @@ describe("foreground-tool streaming on ED3-risk terminals", () => {
 				];
 				component.setLines(frameB);
 				tui.requestRender();
-				await settle(term);
+				await term.waitForRender();
 				expect(visible(term)).toEqual(["chip-1", "chip-2", "chip-3", "loader", "todos", "editor"]);
 
 				// Frame C: a visible chip collapses (a shrink whose first change lands in
@@ -4207,7 +4226,7 @@ describe("foreground-tool streaming on ED3-risk terminals", () => {
 				];
 				component.setLines(frameC);
 				tui.requestRender();
-				await settle(term);
+				await term.waitForRender();
 				expect(visible(term)).toEqual(["chip-0", "chip-1", "chip-2", "loader", "todos", "editor"]);
 			} finally {
 				tui.stop();
diff --git a/packages/tui/test/slash-autocomplete-viewport.test.ts b/packages/tui/test/slash-autocomplete-viewport.test.ts
index f558724fd..71d4e1b9c 100644
--- a/packages/tui/test/slash-autocomplete-viewport.test.ts
+++ b/packages/tui/test/slash-autocomplete-viewport.test.ts
@@ -49,11 +49,10 @@ async function settle(term: VirtualTerminal): Promise<void> {
 	await new Promise<void>(resolve => process.nextTick(resolve));
 	// Each keystroke arms Editor's autocomplete debounce (100ms) before the
 	// provider is re-queried, and the resulting onAutocompleteUpdate render is
-	// throttled by the TUI's MIN_RENDER_INTERVAL_MS (16ms). 120ms left only a
-	// ~4ms margin once the debounce fires, which macOS setTimeout jitter
-	// reliably overran — the stale (unfiltered) menu was still being painted at
-	// capture time, pushing the live editor row out of a 6-row viewport
-	// (issue #1979). Stay well above 100+16ms so the post-debounce render lands
+	// throttled by the TUI's MIN_RENDER_INTERVAL_MS (~33ms). 120ms no longer
+	// covers debounce plus render jitter, so capture could still see the stale
+	// (unfiltered) menu and push the live editor row out of a 6-row viewport
+	// (issue #1979). Stay well above 100+33ms so the post-debounce render lands
 	// before getViewport() runs.
 	await Bun.sleep(250);
 	await term.flush();
diff --git a/packages/tui/test/virtual-terminal.ts b/packages/tui/test/virtual-terminal.ts
index fec8bf054..b356d980a 100644
--- a/packages/tui/test/virtual-terminal.ts
+++ b/packages/tui/test/virtual-terminal.ts
@@ -219,12 +219,12 @@ export class VirtualTerminal implements Terminal {
 
 	// --- Test-only helpers ---------------------------------------------------
 
-	/** Wait for TUI's throttled render pipeline to settle (matches the 16ms frame budget). */
+	/** Wait for TUI's throttled render pipeline to settle (matches the ~33ms frame budget). */
 	async waitForRender(): Promise<void> {
 		const nextTick = Promise.withResolvers<void>();
 		process.nextTick(nextTick.resolve);
 		await nextTick.promise;
-		await Bun.sleep(20);
+		await Bun.sleep(40);
 		await this.flush();
 	}
 

From 1b2373425baae68f1eb8f0d84328f99e90c357a8 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:42:51 +0200
Subject: [PATCH 132/181] feat(packages/coding-agent): set 30fps stream and
 stabilized read groups

- Reduced shimmer-driven UI animations and borders to a 30fps cadence.
- Collapsed consecutive read tool calls into one finalized transcript block.
- Tracked visible assistant content to finalize and reset read groups correctly.
- Updated running task rows to static bullet markers with shimmer-only subagent labels.
---
 docs/theme.md                                 |  2 +-
 packages/coding-agent/CHANGELOG.md            |  6 +++
 packages/coding-agent/src/config/settings.ts  | 22 ++++++++++-
 .../src/modes/components/read-tool-group.ts   | 16 ++++++++
 .../src/modes/components/tool-execution.ts    | 37 ++++++++++++-------
 .../src/modes/controllers/event-controller.ts | 25 +++++++++----
 .../src/modes/interactive-mode.ts             |  9 ++++-
 .../src/modes/theme/theme-schema.json         |  2 +-
 .../coding-agent/src/modes/theme/theme.ts     |  8 ++--
 .../src/modes/utils/ui-helpers.ts             | 15 +++++++-
 packages/coding-agent/src/task/render.ts      | 18 ++++++++-
 packages/coding-agent/src/tui/output-block.ts |  8 ++--
 12 files changed, 130 insertions(+), 38 deletions(-)

diff --git a/docs/theme.md b/docs/theme.md
index 738ab3b5b..36be98c4e 100644
--- a/docs/theme.md
+++ b/docs/theme.md
@@ -85,7 +85,7 @@ If omitted, export code derives defaults from resolved theme colors.
 
 - `symbols.preset` sets a theme-level default symbol set.
 - `symbols.overrides` can override individual `SymbolKey` values.
-- `symbols.spinnerFrames` overrides the loading spinner frames. Accepts either a flat `string[]` (applied to both spinner types) or an object `{ "status"?: string[], "activity"?: string[] }` to override each type independently. Any type not specified falls back to the symbol preset's default frames. `status` drives the ~12.5fps spinner used by loaders and tool-execution indicators; `activity` drives the ~60fps spinner used by markdown progress bars and similar high-frequency UI.
+- `symbols.spinnerFrames` overrides the loading spinner frames. Accepts either a flat `string[]` (applied to both spinner types) or an object `{ "status"?: string[], "activity"?: string[] }` to override each type independently. Any type not specified falls back to the symbol preset's default frames. `status` drives the ~12.5fps spinner used by loaders and tool-execution indicators; `activity` drives the ~30fps spinner used by markdown progress bars and similar high-frequency UI.
 
 Runtime precedence:
 
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 17ac573fe..9c89f2648 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -17,6 +17,9 @@
 
 ### Changed
 
+- Changed shimmer-driven TUI animations (working text, pending bash/eval borders, and theme activity-spinner documentation) to render at 30fps instead of 60fps.
+- Changed running `task` tool agent rows to use a static `•` marker and shimmer only the subagent name, leaving descriptions, stats, and nested tool detail text solid while removing the rotating status glyph from those rows.
+- Changed settings singleton method access to reuse bound methods for the active instance instead of allocating a new bound function on every `settings.get` lookup.
 - Changed plan-mode approval to keep the drafted `local://<slug>-plan.md` file at its original name as the canonical plan path, so approved plans are no longer renamed when leaving plan mode
 - Changed plan-mode write enforcement so only `local://` artifact files are writable during planning, blocking working-tree edits and allowing scratch or draft plan files in the local artifact area
 - Changed the `todo` tool result renderer to stop redrawing every phase's full task list on each update: when a multi-phase list is rendered collapsed (the default, not manually expanded), only phases the latest update touched — the phase holding the in_progress task, any phase with a just-completed task, and phases named by the ops that ran (`init` counts as touching all) — render their tasks; untouched phases collapse to a one-line `N. Name  done/total` summary. When call args are unavailable (e.g. transcript rebuilds) it falls back to the in_progress/completed-transition signals, and the manual expand toggle still shows every task. Also dropped the blank separator line previously inserted between phases.
@@ -38,6 +41,9 @@
 
 ### Fixed
 
+- Fixed the working-status shimmer to opt into the loader's 30fps animated-message repaint path while keeping both the status spinner and pending bash/eval tool spinners on their normal 80 ms glyph cadence.
+- Fixed consecutive `read` tool calls failing to collapse into a single grouped block when a reasoning model emits one read per completion (`[thinking, read]`). The read group was reset on every assistant `message_start`, so each read rendered as its own one-entry `Read …` line; now a read run accretes across completions and is broken only by a rendered non-empty text/thinking block, a non-read tool, or a user/IRC message — matching the transcript-rebuild path. `ReadToolGroupComponent` now reports its live/finalized state so the growing `Read (N)` header repaints correctly on native-scrollback (risk) terminals.
+
 - Fixed the `task` tool shared-context brief rendering raw Markdown headings (`# Goal`, `# Constraints`) inside framed call/result blocks instead of using the normal Markdown renderer.
 - Fixed the animated pending border on `bash`/`eval` blocks leaving a frozen dark "bar" segment behind after a backgrounded command finalized through the async update path. Once a command is auto-backgrounded (`details.async.state === "running"`) the block stays "partial" in the TUI until the async job-manager delivers the final result, but it also gets committed to native scrollback — so a mid-sweep shimmer frame baked a stray darkened border segment into the committed copy. The border now stops animating (and the 60fps redraw loop stops) the moment a block enters the backgrounded state, so the committed frame is a clean static border.
 - Fixed cold `omp` launch to clear native terminal history on the first paint, avoiding a once-per-launch duplicate welcome/transcript copy before the normal session replay.
diff --git a/packages/coding-agent/src/config/settings.ts b/packages/coding-agent/src/config/settings.ts
index 432519460..6f51f703d 100644
--- a/packages/coding-agent/src/config/settings.ts
+++ b/packages/coding-agent/src/config/settings.ts
@@ -240,11 +240,13 @@ export class Settings {
 		return promise.then(
 			instance => {
 				globalInstance = instance;
+				clearBoundSettingsMethods();
 				globalInstancePromise = Promise.resolve(instance);
 				return instance;
 			},
 			error => {
 				globalInstance = null;
+				clearBoundSettingsMethods();
 				throw error;
 			},
 		);
@@ -978,6 +980,13 @@ export function onHindsightScopeChanged(cb: () => void): () => void {
 
 let globalInstance: Settings | null = null;
 let globalInstancePromise: Promise<Settings> | null = null;
+let boundSettingsInstance: Settings | null = null;
+let boundSettingsMethods = new Map<PropertyKey, unknown>();
+
+function clearBoundSettingsMethods(): void {
+	boundSettingsInstance = null;
+	boundSettingsMethods = new Map<PropertyKey, unknown>();
+}
 
 export function isSettingsInitialized(): boolean {
 	return globalInstance !== null;
@@ -990,6 +999,7 @@ export function isSettingsInitialized(): boolean {
 export function resetSettingsForTest(): void {
 	globalInstance = null;
 	globalInstancePromise = null;
+	clearBoundSettingsMethods();
 }
 
 /**
@@ -1001,9 +1011,17 @@ export const settings = new Proxy({} as Settings, {
 		if (!globalInstance) {
 			throw new Error("Settings not initialized. Call Settings.init() first.");
 		}
-		const value = (globalInstance as unknown as Record<string | symbol, unknown>)[prop];
+		if (boundSettingsInstance !== globalInstance) {
+			clearBoundSettingsMethods();
+			boundSettingsInstance = globalInstance;
+		}
+		const value = (globalInstance as unknown as Record<PropertyKey, unknown>)[prop];
 		if (typeof value === "function") {
-			return value.bind(globalInstance);
+			const cached = boundSettingsMethods.get(prop);
+			if (cached) return cached;
+			const bound = value.bind(globalInstance);
+			boundSettingsMethods.set(prop, bound);
+			return bound;
 		}
 		return value;
 	},
diff --git a/packages/coding-agent/src/modes/components/read-tool-group.ts b/packages/coding-agent/src/modes/components/read-tool-group.ts
index fc686ed75..5952b0b12 100644
--- a/packages/coding-agent/src/modes/components/read-tool-group.ts
+++ b/packages/coding-agent/src/modes/components/read-tool-group.ts
@@ -81,6 +81,14 @@ export class ReadToolGroupComponent extends Container implements ToolExecutionHa
 	#text: Text;
 	#expanded = false;
 	#showContentPreview: boolean;
+	// A read group accretes entries across multiple assistant completions for as
+	// long as the run of reads is uninterrupted. While it is the active group it
+	// must stay in the transcript's repaintable live region — its header line
+	// re-layouts from `Read <path>` to `Read (N)` + tree as entries arrive, so a
+	// frozen snapshot taken on a risk terminal would strand the single-entry form
+	// (see TranscriptContainer / NativeScrollbackLiveRegion). The controller calls
+	// `finalize()` once the run breaks so the block can commit to native scrollback.
+	#finalized = false;
 
 	constructor(options: ReadToolGroupOptions = {}) {
 		super();
@@ -90,6 +98,14 @@ export class ReadToolGroupComponent extends Container implements ToolExecutionHa
 		this.#updateDisplay();
 	}
 
+	isTranscriptBlockFinalized(): boolean {
+		return this.#finalized;
+	}
+
+	finalize(): void {
+		this.#finalized = true;
+	}
+
 	updateArgs(args: ReadRenderArgs, toolCallId?: string): void {
 		if (!toolCallId) return;
 		const basePath = args.file_path || args.path || "";
diff --git a/packages/coding-agent/src/modes/components/tool-execution.ts b/packages/coding-agent/src/modes/components/tool-execution.ts
index e2d481db2..aee73cc06 100644
--- a/packages/coding-agent/src/modes/components/tool-execution.ts
+++ b/packages/coding-agent/src/modes/components/tool-execution.ts
@@ -133,12 +133,12 @@ export interface ToolExecutionHandle {
 	setExpanded(expanded: boolean): void;
 }
 
-/** Drive pending-tool redraws at ~60fps so the animated border sweep is smooth.
- * The TUI already throttles at its 16ms `MIN_RENDER_INTERVAL_MS`, so this is the
- * natural upper bound and static frames diff to a no-op redraw at ~zero cost. */
-const SPINNER_RENDER_INTERVAL_MS = 16;
+/** Drive pending-tool redraws at 30fps so the animated border sweep stays
+ * smooth without spending twice the frame budget. The TUI throttles at the same
+ * cadence, and static frames diff to a no-op redraw at ~zero cost. */
+const SPINNER_RENDER_INTERVAL_MS = 1000 / 30;
 /** Advance the spinner glyph at its classic ~12.5fps step, decoupled from the
- * 60fps render cadence (mirrors `Loader`). */
+ * render cadence (mirrors `Loader`). */
 const SPINNER_GLYPH_ADVANCE_MS = 80;
 
 // Stable per-instance counter so each tool execution's inline images get a
@@ -436,17 +436,28 @@ export class ToolExecutionComponent extends Container {
 			!isBackgroundAsyncRunning;
 		const needsSpinner = isStreamingArgs || isPartialTask || isPendingExecBlock;
 		if (needsSpinner && !this.#spinnerInterval) {
-			this.#lastSpinnerAdvanceAt = performance.now();
+			const now = performance.now();
+			const frameCount = theme.spinnerFrames.length;
+			this.#lastSpinnerAdvanceAt = now;
+			if (frameCount > 0 && this.#spinnerFrame === undefined) {
+				this.#spinnerFrame = 0;
+				this.#renderState.spinnerFrame = 0;
+			}
 			this.#spinnerInterval = setInterval(() => {
 				const now = performance.now();
 				const frameCount = theme.spinnerFrames.length;
-				// Redraw at ~60fps for a smooth border sweep, but only step the spinner
-				// glyph at its classic ~12.5fps cadence. The TUI throttles renders at
-				// 16ms and the differ drops no-op redraws, so the extra ticks are free.
-				if (frameCount > 0 && now - this.#lastSpinnerAdvanceAt >= SPINNER_GLYPH_ADVANCE_MS) {
-					this.#spinnerFrame = ((this.#spinnerFrame ?? -1) + 1) % frameCount;
-					this.#renderState.spinnerFrame = this.#spinnerFrame;
-					this.#lastSpinnerAdvanceAt = now;
+				// Redraw at 30fps for a smooth border sweep, but keep the spinner
+				// glyph phase-locked to its classic ~12.5fps cadence. Advancing the
+				// anchor by elapsed frames instead of resetting to `now` avoids the
+				// 30fps timer quantizing the glyph down to one step every three ticks.
+				if (frameCount > 0) {
+					const elapsed = now - this.#lastSpinnerAdvanceAt;
+					if (elapsed >= SPINNER_GLYPH_ADVANCE_MS) {
+						const steps = Math.floor(elapsed / SPINNER_GLYPH_ADVANCE_MS);
+						this.#spinnerFrame = ((this.#spinnerFrame ?? 0) + steps) % frameCount;
+						this.#renderState.spinnerFrame = this.#spinnerFrame;
+						this.#lastSpinnerAdvanceAt += steps * SPINNER_GLYPH_ADVANCE_MS;
+					}
 				}
 				this.#ui.requestRender();
 			}, SPINNER_RENDER_INTERVAL_MS);
diff --git a/packages/coding-agent/src/modes/controllers/event-controller.ts b/packages/coding-agent/src/modes/controllers/event-controller.ts
index 06190ae38..084ee4d29 100644
--- a/packages/coding-agent/src/modes/controllers/event-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/event-controller.ts
@@ -44,7 +44,13 @@ type AgentSessionEventHandlers = {
 
 export class EventController {
 	#lastReadGroup: ReadToolGroupComponent | undefined = undefined;
-	#lastThinkingCount = 0;
+	// Count of visible assistant content blocks (rendered non-empty text/thinking)
+	// already seen in the current streaming message. A newly appearing one breaks
+	// the read run: the rendered reasoning/answer is a visual separator, so reads
+	// after it start a fresh group. Empty/absent thinking — common when a model
+	// emits one read per completion — does not break it, so a run of consecutive
+	// reads collapses into one group even across completion boundaries.
+	#lastVisibleBlockCount = 0;
 	#renderedCustomMessages = new Set<string>();
 	#lastIntent: string | undefined = undefined;
 	#backgroundToolCallIds = new Set<string>();
@@ -103,6 +109,7 @@ export class EventController {
 	}
 
 	#resetReadGroup(): void {
+		this.#lastReadGroup?.finalize();
 		this.#lastReadGroup = undefined;
 	}
 
@@ -208,6 +215,7 @@ export class EventController {
 		this.#lastIntent = undefined;
 		this.#readToolCallArgs.clear();
 		this.#readToolCallAssistantComponents.clear();
+		this.#resetReadGroup();
 		this.#assistantMessageStreaming = false;
 		this.#lastAssistantComponent = undefined;
 		// Restore the previous turn's inline error in the transcript before dropping
@@ -298,9 +306,8 @@ export class EventController {
 			this.ctx.addMessageToChat(event.message);
 			this.ctx.ui.requestRender();
 		} else if (event.message.role === "assistant") {
-			this.#lastThinkingCount = 0;
 			this.#assistantMessageStreaming = true;
-			this.#resetReadGroup();
+			this.#lastVisibleBlockCount = 0;
 			this.ctx.streamingComponent = new AssistantMessageComponent(
 				undefined,
 				this.ctx.hideThinkingBlock,
@@ -356,14 +363,15 @@ export class EventController {
 			this.ctx.streamingMessage = event.message;
 			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage);
 
-			const thinkingCount = this.ctx.streamingMessage.content.filter(
-				content => content.type === "thinking" && content.thinking.trim(),
+			const visibleBlockCount = this.ctx.streamingMessage.content.filter(
+				content =>
+					(content.type === "text" && content.text.trim().length > 0) ||
+					(content.type === "thinking" && content.thinking.trim().length > 0),
 			).length;
-			if (thinkingCount > this.#lastThinkingCount) {
+			if (visibleBlockCount > this.#lastVisibleBlockCount) {
 				this.#resetReadGroup();
-				this.#lastThinkingCount = thinkingCount;
+				this.#lastVisibleBlockCount = visibleBlockCount;
 			}
-
 			for (const content of this.ctx.streamingMessage.content) {
 				if (content.type !== "toolCall") continue;
 				if (content.name === "read") {
@@ -685,6 +693,7 @@ export class EventController {
 		);
 		this.#readToolCallArgs.clear();
 		this.#readToolCallAssistantComponents.clear();
+		this.#resetReadGroup();
 		this.#lastAssistantComponent = undefined;
 		this.ctx.ui.requestRender();
 		this.#scheduleIdleCompaction();
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index 56b763d28..0b0e42641 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -20,7 +20,7 @@ import {
 	modelsAreEqual,
 	type UsageReport,
 } from "@oh-my-pi/pi-ai";
-import type { Component, EditorTheme, OverlayHandle, SlashCommand } from "@oh-my-pi/pi-tui";
+import type { Component, EditorTheme, LoaderMessageColorFn, OverlayHandle, SlashCommand } from "@oh-my-pi/pi-tui";
 import {
 	Container,
 	clearRenderCache,
@@ -2659,13 +2659,18 @@ export class InteractiveMode implements InteractiveModeContext {
 	ensureLoadingAnimation(): void {
 		if (!this.loadingAnimation) {
 			this.statusContainer.clear();
+			const messageColorFn = ((message: string) =>
+				renderWorkingMessage(message, this.#getWorkingMessageAccent())) as LoaderMessageColorFn & {
+				animated: true;
+			};
+			messageColorFn.animated = true;
 			this.loadingAnimation = new Loader(
 				this.ui,
 				spinner => {
 					const accent = this.#getWorkingMessageAccent();
 					return accent ? `${accent.main}${spinner}\x1b[39m` : theme.fg("accent", spinner);
 				},
-				message => renderWorkingMessage(message, this.#getWorkingMessageAccent()),
+				messageColorFn,
 				this.#defaultWorkingMessage,
 				getSymbolTheme().spinnerFrames,
 			);
diff --git a/packages/coding-agent/src/modes/theme/theme-schema.json b/packages/coding-agent/src/modes/theme/theme-schema.json
index e401ca0c1..3fd9972b4 100644
--- a/packages/coding-agent/src/modes/theme/theme-schema.json
+++ b/packages/coding-agent/src/modes/theme/theme-schema.json
@@ -406,7 +406,7 @@
 					}
 				},
 				"spinnerFrames": {
-					"description": "Override the spinner frames. Use a flat array to set both `status` and `activity`, or an object to override each independently. Frames are advanced ~12.5fps for status spinners and ~60fps for activity spinners.",
+					"description": "Override the spinner frames. Use a flat array to set both `status` and `activity`, or an object to override each independently. Frames are advanced ~12.5fps for status spinners and ~30fps for activity spinners.",
 					"oneOf": [
 						{
 							"type": "array",
diff --git a/packages/coding-agent/src/modes/theme/theme.ts b/packages/coding-agent/src/modes/theme/theme.ts
index 963bade66..ed0d46d24 100644
--- a/packages/coding-agent/src/modes/theme/theme.ts
+++ b/packages/coding-agent/src/modes/theme/theme.ts
@@ -2443,10 +2443,10 @@ function getHighlightColors(t: Theme): NativeHighlightColors {
  * switch (which always reassigns `theme`) must invalidate every entry.
  *
  * Why this exists: animated tool blocks (eval/bash) repaint their box on every
- * ~16ms border-shimmer frame, and markdown re-lexes on every streamed delta.
- * Without memoization each frame re-tokenizes an unchanged code body through the
- * Rust FFI — ~26ms for 100 lines, ~40ms for 150 — overrunning the 16ms frame
- * budget and starving the spinner/render timers (the "TUI freeze").
+ * ~33ms border-shimmer frame, and markdown re-lexes on every streamed delta.
+ * Without memoization each frame can re-tokenize an unchanged code body through
+ * the Rust FFI — ~26ms for 100 lines, ~40ms for 150 — consuming or overrunning
+ * the 33ms frame budget and starving the spinner/render timers (the "TUI freeze").
  */
 const HIGHLIGHT_CACHE_MAX = 256;
 const highlightCache = new LRUCache<string, string>({ max: HIGHLIGHT_CACHE_MAX });
diff --git a/packages/coding-agent/src/modes/utils/ui-helpers.ts b/packages/coding-agent/src/modes/utils/ui-helpers.ts
index 5b663c5e9..fdf6b2876 100644
--- a/packages/coding-agent/src/modes/utils/ui-helpers.ts
+++ b/packages/coding-agent/src/modes/utils/ui-helpers.ts
@@ -336,7 +336,15 @@ export class UiHelpers {
 				if (assistantComponent) {
 					assistantComponent.setUsageInfo(message.usage);
 				}
-				readGroup = null;
+				const hasVisibleAssistantContent = message.content.some(
+					content =>
+						(content.type === "text" && content.text.trim().length > 0) ||
+						(content.type === "thinking" && content.thinking.trim().length > 0),
+				);
+				if (hasVisibleAssistantContent) {
+					readGroup?.finalize();
+					readGroup = null;
+				}
 				const isAbortedSilently = message.stopReason === "aborted" && isSilentAbort(message.errorMessage);
 				const hasErrorStop =
 					!isAbortedSilently && (message.stopReason === "aborted" || message.stopReason === "error");
@@ -384,6 +392,7 @@ export class UiHelpers {
 						continue;
 					}
 
+					readGroup?.finalize();
 					readGroup = null;
 					const tool = this.ctx.session.getToolByName(content.name);
 					const renderArgs =
@@ -471,6 +480,10 @@ export class UiHelpers {
 			}
 		}
 
+		// The trailing read run has no following break to close it; finalize so the
+		// rebuilt group commits to native scrollback like every other historical block.
+		readGroup?.finalize();
+
 		// Render deferred messages (compaction summaries) at the bottom so they're visible
 		for (const message of deferredMessages) {
 			this.ctx.addMessageToChat(message, options);
diff --git a/packages/coding-agent/src/task/render.ts b/packages/coding-agent/src/task/render.ts
index 0975c66ea..1bb94527f 100644
--- a/packages/coding-agent/src/task/render.ts
+++ b/packages/coding-agent/src/task/render.ts
@@ -11,6 +11,7 @@ import { formatNumber } from "@oh-my-pi/pi-utils";
 import { settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { formatContextUsage } from "../modes/components/status-line/context-thresholds";
+import { shimmerEnabled, shimmerText } from "../modes/theme/shimmer";
 import { getMarkdownTheme, type Theme } from "../modes/theme/theme";
 import {
 	formatBadge,
@@ -628,11 +629,24 @@ function renderAgentProgress(
 	const description = progress.description?.trim();
 	const displayId = formatTaskId(progress.id);
 	const titlePart = description ? `${theme.bold(displayId)}: ${description}` : displayId;
-	let statusLine = `${prefix ? `${prefix} ` : ""}${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)}`;
+	const indent = prefix ? `${prefix} ` : "";
+	let statusLine: string;
+	if (progress.status === "running") {
+		const bullet = theme.fg("accent", "•");
+		const name = shimmerEnabled()
+			? shimmerText(displayId, theme)
+			: theme.fg("accent", description ? theme.bold(displayId) : displayId);
+		statusLine = `${indent}${bullet} ${name}`;
+		if (description) {
+			statusLine += theme.fg("accent", `: ${description}`);
+		}
+	} else {
+		statusLine = `${indent}${theme.fg(iconColor, icon)} ${theme.fg("accent", titlePart)}`;
+	}
 
 	// Show retry-blocked badge so the parent immediately sees that a child
 	// is sleeping on a provider 429, not silently progressing. Wins over the
-	// generic running spinner because "we're waiting on a quota window" is
+	// generic running marker because "we're waiting on a quota window" is
 	// the operationally meaningful state.
 	if (progress.retryState && progress.status === "running") {
 		statusLine += ` ${formatBadge("retrying", "warning", theme)}`;
diff --git a/packages/coding-agent/src/tui/output-block.ts b/packages/coding-agent/src/tui/output-block.ts
index 848d92969..d80344f68 100644
--- a/packages/coding-agent/src/tui/output-block.ts
+++ b/packages/coding-agent/src/tui/output-block.ts
@@ -37,7 +37,7 @@ export function isFramedBlockComponent(component: Component): boolean {
 	return (component as FramedBlockComponent)[FRAMED_BLOCK_COMPONENT] === true;
 }
 
-const BORDER_SHIMMER_TICK_MS = 16;
+const BORDER_SHIMMER_TICK_MS = 1000 / 30;
 /** Duration of one full left↔right↔left bounce of the bottom-edge segment, in
  * ms. Position is derived from the wall clock against this fixed cycle so a
  * resize only nudges the segment proportionally instead of teleporting it. */
@@ -46,9 +46,9 @@ const BORDER_BOUNCE_MS = 3000;
 const BORDER_SEGMENT_LEN = 8;
 
 /**
- * Monotonic frame counter for animated borders, quantized to the TUI's ~16ms
- * render cap so the cache key advances once per ~60fps frame — fine enough for a
- * smooth segment sweep, coarse enough to coalesce multiple render passes that
+ * Monotonic frame counter for animated borders, quantized to the TUI's ~30fps
+ * render cap so the cache key advances once per animation frame — fine enough
+ * for a smooth segment sweep, coarse enough to coalesce multiple render passes
  * land inside the same frame.
  */
 export function borderShimmerTick(): number {

From f3257c3cf151520e5ac418d0c0183fc6e7f7214c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:42:51 +0200
Subject: [PATCH 133/181] test(packages/coding-agent): added tests for read
 grouping task shimmer

- Added regression coverage for EventController to collapse single-read completions into one read group.
- Added assertions that visible reasoning breaks grouping and finalizes the prior read block.
- Added nested-live task rendering test for static task header while the task body shimmers.
- Added task-progress rendering tests for shimmered task-name rows and spinner-disabled fallback.
- Added a ToolExecutionComponent timing test validating bash spinnerFrame increments on 30fps cadence.
---
 .../event-controller-read-grouping.test.ts    | 147 ++++++++++++++++++
 .../test/streaming-preview-height.test.ts     |   2 +-
 .../test/task/render-nested-live.test.ts      |  34 ++--
 .../test/task/task-progress-render.test.ts    | 100 ++++++++++++
 .../test/tool-execution-args.test.ts          |  28 +++-
 5 files changed, 296 insertions(+), 15 deletions(-)
 create mode 100644 packages/coding-agent/test/modes/controllers/event-controller-read-grouping.test.ts
 create mode 100644 packages/coding-agent/test/task/task-progress-render.test.ts

diff --git a/packages/coding-agent/test/modes/controllers/event-controller-read-grouping.test.ts b/packages/coding-agent/test/modes/controllers/event-controller-read-grouping.test.ts
new file mode 100644
index 000000000..a815d5e69
--- /dev/null
+++ b/packages/coding-agent/test/modes/controllers/event-controller-read-grouping.test.ts
@@ -0,0 +1,147 @@
+/**
+ * Read-group accretion across assistant completions.
+ *
+ * Reasoning models (and codex-style providers) frequently emit one `read` per
+ * completion as `[thinking?, toolCall]` rather than batching parallel calls.
+ * The transcript should still collapse an uninterrupted run of those reads into
+ * a single {@link ReadToolGroupComponent}; a completion that renders visible
+ * content (non-empty text/thinking) is the only thing that breaks the run, so a
+ * fresh group starts after it.
+ *
+ * Regression: every completion used to reset the active group at `message_start`,
+ * so consecutive single-read completions never grouped (each rendered as its own
+ * one-entry block).
+ */
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import { resetSettingsForTest, Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import { ReadToolGroupComponent } from "@oh-my-pi/pi-coding-agent/modes/components/read-tool-group";
+import { EventController } from "@oh-my-pi/pi-coding-agent/modes/controllers/event-controller";
+import { initTheme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
+import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/types";
+import type { AgentSessionEvent } from "@oh-my-pi/pi-coding-agent/session/agent-session";
+import { Container } from "@oh-my-pi/pi-tui";
+
+beforeAll(async () => {
+	await initTheme(false, undefined, undefined, "dark", "light");
+});
+
+beforeEach(async () => {
+	resetSettingsForTest();
+	await Settings.init({ inMemory: true });
+});
+
+afterEach(() => {
+	resetSettingsForTest();
+	vi.restoreAllMocks();
+});
+
+type Block = AssistantMessage["content"][number];
+
+function read(path: string): Block {
+	return { type: "toolCall", id: `read-${path}`, name: "read", arguments: { path } } as Block;
+}
+
+function thinking(text: string): Block {
+	return { type: "thinking", thinking: text } as Block;
+}
+
+function assistantMessage(content: Block[]): AssistantMessage {
+	return {
+		role: "assistant",
+		content,
+		api: "openai-codex-responses",
+		provider: "openai-codex",
+		model: "gpt-5.5",
+		stopReason: "toolUse",
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		timestamp: Date.now(),
+	};
+}
+
+function createFixture() {
+	const chatContainer = new Container();
+	const ctx = {
+		isInitialized: true,
+		init: vi.fn(async () => {}),
+		statusLine: { invalidate: vi.fn() },
+		updateEditorTopBorder: vi.fn(),
+		ui: { requestRender: vi.fn(), setEagerNativeScrollbackRebuild: vi.fn(), imageBudget: undefined },
+		chatContainer,
+		pendingTools: new Map(),
+		settings: { get: () => false },
+		toolOutputExpanded: false,
+		hideThinkingBlock: false,
+		setWorkingMessage: vi.fn(),
+		session: { getToolByName: () => undefined, extensionRunner: undefined },
+	} as unknown as InteractiveModeContext;
+	return { controller: new EventController(ctx), chatContainer };
+}
+
+/** Drive one assistant completion: message_start then a single full message_update. */
+async function streamCompletion(controller: EventController, content: Block[]): Promise<void> {
+	const message = assistantMessage(content);
+	await controller.handleEvent({ type: "message_start", message } as AgentSessionEvent);
+	await controller.handleEvent({ type: "message_update", message } as AgentSessionEvent);
+}
+
+function readGroups(chatContainer: Container): ReadToolGroupComponent[] {
+	return chatContainer.children.filter((c): c is ReadToolGroupComponent => c instanceof ReadToolGroupComponent);
+}
+
+function header(group: ReadToolGroupComponent): string {
+	return Bun.stripANSI(group.render(120).join("\n")).split("\n")[0] ?? "";
+}
+
+describe("EventController read-group accretion", () => {
+	it("collapses a run of single-read completions into one group (mixed/empty thinking)", async () => {
+		const { controller, chatContainer } = createFixture();
+
+		// Mirrors the reported session: first read carries reasoning, the rest have
+		// empty or absent thinking. None of them should break the run.
+		await streamCompletion(controller, [thinking("Considering performance optimizations"), read("a.ts:180-250")]);
+		await streamCompletion(controller, [thinking(""), read("a.ts:1-120")]);
+		await streamCompletion(controller, [read("b.ts:1-220")]);
+		await streamCompletion(controller, [read("b.ts:450-535")]);
+
+		const groups = readGroups(chatContainer);
+		expect(groups.length).toBe(1);
+		expect(header(groups[0]!)).toContain("Read (4)");
+	});
+
+	it("starts a new group after a completion that renders visible reasoning", async () => {
+		const { controller, chatContainer } = createFixture();
+
+		await streamCompletion(controller, [read("a.ts:1-50")]);
+		await streamCompletion(controller, [read("a.ts:51-100")]);
+		// Visible reasoning is a separator: the next reads form a distinct group.
+		await streamCompletion(controller, [thinking("Now let me check the other files"), read("c.ts:1-40")]);
+		await streamCompletion(controller, [read("c.ts:41-80")]);
+
+		const groups = readGroups(chatContainer);
+		expect(groups.length).toBe(2);
+		expect(header(groups[0]!)).toContain("Read (2)");
+		expect(header(groups[1]!)).toContain("Read (2)");
+	});
+
+	it("keeps the active group repaintable until it is finalized", async () => {
+		const { controller, chatContainer } = createFixture();
+
+		await streamCompletion(controller, [read("a.ts:1-50")]);
+		const [group] = readGroups(chatContainer);
+		// While it is the active run the block must stay in the live region so its
+		// header can re-layout from `Read <path>` to `Read (N)` on risk terminals.
+		expect(group!.isTranscriptBlockFinalized()).toBe(false);
+
+		// A visible-reasoning completion breaks the run and finalizes the prior group.
+		await streamCompletion(controller, [thinking("done exploring"), read("b.ts:1-50")]);
+		expect(group!.isTranscriptBlockFinalized()).toBe(true);
+	});
+});
diff --git a/packages/coding-agent/test/streaming-preview-height.test.ts b/packages/coding-agent/test/streaming-preview-height.test.ts
index b5c2d3f08..86807a5ba 100644
--- a/packages/coding-agent/test/streaming-preview-height.test.ts
+++ b/packages/coding-agent/test/streaming-preview-height.test.ts
@@ -119,7 +119,7 @@ describe("streaming edit preview height (stable, full tail window)", () => {
 			tmpDir,
 		);
 		// Await the actual diff recompute rather than racing the spinner's render
-		// ticks. The streaming spinner calls requestRender every ~16ms, so on a
+		// ticks. The streaming spinner calls requestRender every ~33ms, so on a
 		// slow box a tick — not the (file-read + whole-file Myers) compute — would
 		// resolve the wait and let us sample a stale, mid-abort preview. That is the
 		// CI flake that collapsed Math.min(...steady) to 4. whenPreviewSettled()
diff --git a/packages/coding-agent/test/task/render-nested-live.test.ts b/packages/coding-agent/test/task/render-nested-live.test.ts
index f232fbada..422ce07e1 100644
--- a/packages/coding-agent/test/task/render-nested-live.test.ts
+++ b/packages/coding-agent/test/task/render-nested-live.test.ts
@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "bun:test";
 import { resetSettingsForTest, Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import { getThemeByName, setThemeInstance } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
 import type { AgentProgress, SingleResult, TaskParams, TaskToolDetails } from "@oh-my-pi/pi-coding-agent/task";
@@ -14,6 +14,10 @@ describe("task renderer: nested live rendering", () => {
 		setThemeInstance(theme!);
 	});
 
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
 	afterAll(() => {
 		resetSettingsForTest();
 	});
@@ -231,7 +235,7 @@ describe("task renderer: nested live rendering", () => {
 		expect(text).toContain("Harden the auth stack before the cut.");
 	});
 
-	it("renders a static result header while the body keeps the progress spinner", async () => {
+	it("renders a static result header while the body shimmers the running task name", async () => {
 		const theme = (await getThemeByName("dark"))!;
 		const details: TaskToolDetails = {
 			projectAgentsDir: null,
@@ -239,24 +243,28 @@ describe("task renderer: nested live rendering", () => {
 			totalDurationMs: 0,
 			progress: [makeRunningProgress({ id: "Probe", description: "Investigate padding" })],
 		};
-		const renderFrame = (frame: number): string[] => {
+		let now = 0;
+		vi.spyOn(Date, "now").mockImplementation(() => now);
+		const renderAt = (timeMs: number): string[] => {
+			now = timeMs;
 			const component = taskToolRenderer.renderResult(
 				{ content: [{ type: "text", text: "Running 1 agents..." }], details },
-				{ expanded: false, isPartial: true, spinnerFrame: frame },
+				{ expanded: false, isPartial: true, spinnerFrame: 0 },
 				theme,
 			);
-			return Bun.stripANSI(component.render(160).join("\n")).split("\n");
+			return component.render(160).join("\n").split("\n");
 		};
-		const f0 = renderFrame(0);
-		const f1 = renderFrame(1);
-		const header0 = f0.find(l => l.includes("Task"))!;
-		const header1 = f1.find(l => l.includes("Task"))!;
-		const body0 = f0.find(l => l.includes("Probe"))!;
-		const body1 = f1.find(l => l.includes("Probe"))!;
-		// Header is static across spinner frames — no clock ticking beside "Task".
+		const f0 = renderAt(0);
+		const f1 = renderAt(700);
+		const header0 = f0.find(l => Bun.stripANSI(l).includes("Task"))!;
+		const header1 = f1.find(l => Bun.stripANSI(l).includes("Task"))!;
+		const body0 = f0.find(l => Bun.stripANSI(l).includes("Probe"))!;
+		const body1 = f1.find(l => Bun.stripANSI(l).includes("Probe"))!;
+		// Header is static — no clock ticking beside "Task".
 		expect(header0).toBe(header1);
-		// The per-agent body line still advances its spinner, conveying progress.
+		// The per-agent body line still animates via the shimmered task name.
 		expect(body0).not.toBe(body1);
+		expect(Bun.stripANSI(body1)).toContain("• Probe: Investigate padding");
 	});
 
 	it("wraps the completed run summary in bracket glyphs, dropping the Total: label", async () => {
diff --git a/packages/coding-agent/test/task/task-progress-render.test.ts b/packages/coding-agent/test/task/task-progress-render.test.ts
new file mode 100644
index 000000000..2a217d19a
--- /dev/null
+++ b/packages/coding-agent/test/task/task-progress-render.test.ts
@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import type { RenderResultOptions } from "@oh-my-pi/pi-agent-core";
+import { resetSettingsForTest, Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import { getThemeByName } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
+import { taskToolRenderer } from "@oh-my-pi/pi-coding-agent/task/render";
+import type { AgentProgress, TaskToolDetails } from "@oh-my-pi/pi-coding-agent/task/types";
+
+function runningProgress(overrides: Partial<AgentProgress> = {}): AgentProgress {
+	return {
+		index: 0,
+		id: "KeySettingsHotPaths",
+		agent: "task",
+		agentSource: "bundled",
+		status: "running",
+		task: "investigate hot paths",
+		recentTools: [],
+		recentOutput: [],
+		toolCount: 0,
+		tokens: 0,
+		cost: 0,
+		durationMs: 0,
+		...overrides,
+	};
+}
+
+function detailsFor(progress: AgentProgress): TaskToolDetails {
+	return { projectAgentsDir: null, results: [], totalDurationMs: 0, progress: [progress] };
+}
+
+function findRow(component: { render: (w: number) => string[] }, needle: string): string {
+	const row = component
+		.render(120)
+		.join("\n")
+		.split("\n")
+		.find(line => Bun.stripANSI(line).includes(needle));
+	expect(row).toBeDefined();
+	return row!;
+}
+
+describe("task progress rendering", () => {
+	beforeEach(async () => {
+		resetSettingsForTest();
+		await Settings.init({ inMemory: true });
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+		resetSettingsForTest();
+	});
+	it("uses a static bullet and shimmers only the running subagent name", async () => {
+		const theme = (await getThemeByName("dark"))!;
+		expect(theme).toBeDefined();
+		// Pin the sweep so the shimmer crest deterministically lands on the name.
+		vi.spyOn(Date, "now").mockReturnValue(683);
+		const options: RenderResultOptions = { expanded: false, isPartial: true, spinnerFrame: 0 };
+		const progress = runningProgress({ id: "CountPackages", description: "List workspace packages" });
+
+		const rawRow = findRow(
+			taskToolRenderer.renderResult(
+				{ content: [{ type: "text", text: "" }], details: detailsFor(progress) },
+				options,
+				theme,
+			),
+			"CountPackages",
+		);
+		const strippedRow = Bun.stripANSI(rawRow);
+
+		expect(strippedRow).toContain("• CountPackages: List workspace packages");
+		expect(strippedRow).not.toContain(theme.status.running);
+		expect(strippedRow).not.toContain(theme.getSpinnerFrames("status")[0]);
+		// Bold crest only comes from the shimmer palette; the description remains
+		// one solid, non-shimmered run.
+		expect(rawRow).toContain("\x1b[1m");
+		const descriptionIndex = rawRow.indexOf(": List workspace packages");
+		expect(descriptionIndex).toBeGreaterThan(0);
+		expect(rawRow.slice(descriptionIndex)).not.toContain("\x1b[1m");
+	});
+
+	it("keeps the bullet replacement when shimmer is disabled", async () => {
+		const theme = (await getThemeByName("dark"))!;
+		resetSettingsForTest();
+		await Settings.init({ inMemory: true, overrides: { "display.shimmer": "disabled" } });
+		const options: RenderResultOptions = { expanded: false, isPartial: true, spinnerFrame: 0 };
+
+		const strippedRow = Bun.stripANSI(
+			findRow(
+				taskToolRenderer.renderResult(
+					{ content: [{ type: "text", text: "" }], details: detailsFor(runningProgress()) },
+					options,
+					theme,
+				),
+				"KeySettingsHotPaths",
+			),
+		);
+
+		expect(strippedRow).toContain("• KeySettingsHotPaths");
+		expect(strippedRow).not.toContain(theme.status.running);
+		expect(strippedRow).not.toContain(theme.getSpinnerFrames("status")[0]);
+	});
+});
diff --git a/packages/coding-agent/test/tool-execution-args.test.ts b/packages/coding-agent/test/tool-execution-args.test.ts
index 9388e8a4a..1a4a66dc1 100644
--- a/packages/coding-agent/test/tool-execution-args.test.ts
+++ b/packages/coding-agent/test/tool-execution-args.test.ts
@@ -1,12 +1,14 @@
 import { afterEach, describe, expect, it, vi } from "bun:test";
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import { initTheme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
-import type { TUI } from "@oh-my-pi/pi-tui";
+import { Text, type TUI } from "@oh-my-pi/pi-tui";
 import { ToolExecutionComponent } from "../src/modes/components/tool-execution";
 
 describe("ToolExecutionComponent.updateArgs (F8 — no clone, ref-eq fast path)", () => {
 	let initialized = false;
 
 	afterEach(() => {
+		vi.useRealTimers();
 		vi.restoreAllMocks();
 	});
 
@@ -31,4 +33,28 @@ describe("ToolExecutionComponent.updateArgs (F8 — no clone, ref-eq fast path)"
 
 		expect(cloneSpy).not.toHaveBeenCalled();
 	});
+	it("keeps bash spinner cadence when the shimmer border repaints at 30fps", async () => {
+		if (!initialized) {
+			await initTheme();
+			initialized = true;
+		}
+		vi.useFakeTimers();
+		let renderState: { spinnerFrame?: number } | undefined;
+		const uiStub = { requestRender: vi.fn() } as unknown as TUI;
+		const tool = {
+			label: "Bash",
+			renderCall: (_args: unknown, options: { spinnerFrame?: number }) => {
+				renderState = options;
+				return new Text("", 0, 0);
+			},
+			execute: async () => ({ content: [] }),
+		} as unknown as AgentTool;
+		const component = new ToolExecutionComponent("bash", { command: "echo ok" }, {}, tool, uiStub);
+
+		component.setArgsComplete();
+		vi.advanceTimersByTime(170);
+
+		expect(renderState?.spinnerFrame).toBe(2);
+		component.stopAnimation();
+	});
 });

From 9cd18839415e43adfa95e0536700934dae253e15 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 06:43:47 +0000
Subject: [PATCH 134/181] fix(ai): tagged json schema union branch issues

Marked JSON Schema validation issues that come from a failed anyOf/oneOf branch and threaded the marker through the coercion bridge so the singleton-array wrap mirrors the Zod branch guard.

Fixes #2026
---
 .../src/utils/schema/json-schema-validator.ts | 12 ++++-
 packages/ai/src/utils/validation.ts           |  5 +-
 .../ai/test/tool-argument-coercion.test.ts    | 46 +++++++++++++++++++
 3 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/packages/ai/src/utils/schema/json-schema-validator.ts b/packages/ai/src/utils/schema/json-schema-validator.ts
index 93a69cf15..fa8c82157 100644
--- a/packages/ai/src/utils/schema/json-schema-validator.ts
+++ b/packages/ai/src/utils/schema/json-schema-validator.ts
@@ -20,6 +20,14 @@ export interface JsonSchemaValidationIssue {
 	message: string;
 	expectedTypes?: string[];
 	keyword?: string;
+	/**
+	 * Marks issues that originate inside a failed `anyOf` / `oneOf` branch.
+	 * Consumers such as the tool-argument coercion layer use this to avoid
+	 * applying type repairs (e.g. singleton-array wrapping) that would be
+	 * authoritative outside of a combinator but are only one candidate
+	 * branch's expectation here.
+	 */
+	fromUnionBranch?: boolean;
 }
 
 export interface JsonSchemaValidationResult {
@@ -242,7 +250,9 @@ function validateSchemaNode(
 		const branchValid = keyword === "anyOf" ? matches > 0 : matches === 1;
 		if (!branchValid) {
 			if (matches === 0 && firstIssues && firstIssues.length > 0) {
-				issues.push(...firstIssues);
+				for (const branchIssue of firstIssues) {
+					issues.push({ ...branchIssue, fromUnionBranch: true });
+				}
 			} else {
 				pushIssue(
 					issues,
diff --git a/packages/ai/src/utils/validation.ts b/packages/ai/src/utils/validation.ts
index f87e34406..e39e7d188 100644
--- a/packages/ai/src/utils/validation.ts
+++ b/packages/ai/src/utils/validation.ts
@@ -914,19 +914,20 @@ function preserveUnknownRootFields(input: unknown, parsed: unknown): unknown {
 
 function flattenJsonSchemaIssues(issues: ReadonlyArray<JsonSchemaValidationIssue>): FlatIssue[] {
 	return issues.map(issue => {
+		const unionBranch = issue.fromUnionBranch === true;
 		if (issue.keyword === "additionalProperties") {
 			return {
 				keyword: "unrecognized",
 				instancePath: pathToPointer(issue.path),
 				expectedTypes: [],
-				unionBranch: false,
+				unionBranch,
 			};
 		}
 		return {
 			keyword: issue.keyword === "type" ? "type" : "other",
 			instancePath: pathToPointer(issue.path),
 			expectedTypes: issue.expectedTypes ?? [],
-			unionBranch: false,
+			unionBranch,
 		};
 	});
 }
diff --git a/packages/ai/test/tool-argument-coercion.test.ts b/packages/ai/test/tool-argument-coercion.test.ts
index 7e7e13cf3..586ae2942 100644
--- a/packages/ai/test/tool-argument-coercion.test.ts
+++ b/packages/ai/test/tool-argument-coercion.test.ts
@@ -149,6 +149,52 @@ describe("Tool argument coercion", () => {
 		expect(result).toEqual({ id: 1 });
 	});
 
+	it("does not wrap singleton values for JSON Schema anyOf array branches", () => {
+		const tool: Tool = {
+			name: "json_schema_union",
+			description: "",
+			parameters: {
+				type: "object",
+				properties: {
+					target: {
+						anyOf: [
+							{
+								type: "array",
+								items: {
+									type: "object",
+									properties: { a: { type: "boolean" } },
+									required: ["a"],
+									additionalProperties: false,
+								},
+							},
+							{
+								type: "object",
+								properties: { a: { type: "boolean" } },
+								required: ["a"],
+								additionalProperties: false,
+							},
+						],
+					},
+				},
+				required: ["target"],
+				additionalProperties: false,
+			},
+		};
+
+		// The bug would silently coerce `{ a: "true" }` into `[{ a: true }]` by
+		// wrapping the object to satisfy the failed `anyOf` array branch and
+		// then coercing the inner string into a boolean. Branch tracking keeps
+		// the wrap from firing so the wrong shape never makes it through.
+		expect(() =>
+			validateToolArguments(tool, {
+				type: "toolCall",
+				id: "call-jsonschema-union",
+				name: "json_schema_union",
+				arguments: { target: { a: "true" } },
+			}),
+		).toThrow("Validation failed");
+	});
+
 	it("parses JSON objects in string values when schema expects object", () => {
 		const tool: Tool = {
 			name: "t4",

From f8fa44c327dd937d16df672c0709453d28eed83c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:42:51 +0200
Subject: [PATCH 135/181] fix(packages/ai): resolved Anthropic tool-call
 parallel-use suppression

- Removed Opus-specific `tool_choice.disable_parallel_tool_use` injection for Anthropic tool calls.
- Removed the obsolete `disablesParallelToolUse` helper from model capability checks.
---
 packages/ai/CHANGELOG.md               |  6 ++++--
 packages/ai/src/model-thinking.ts      | 12 ------------
 packages/ai/src/providers/anthropic.ts | 16 ----------------
 3 files changed, 4 insertions(+), 30 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 1a7a921ba..4a0353f5c 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -1,6 +1,7 @@
 # Changelog
 
 ## [Unreleased]
+
 ### Breaking Changes
 
 - Removed the `onAuthError` option from stream request options and shifted auth retry handling to resolver-based `apiKey` behavior, requiring callers using custom auth-retry hooks to migrate
@@ -21,6 +22,8 @@
 - Fixed streaming auth retries to handle `401` and usage-limit errors before replay-unsafe content is emitted, including failures surfaced only via `errorStatus`
 - Fixed streaming retries to buffer and suppress partial `start` events from failed auth attempts so only clean retried events are delivered
 - Fixed the HTTP 400 raw-request dumper (`appendRawHttpRequestDumpFor400`) littering the real `~/.omp/logs/http-400-requests` directory during tests. Provider suites exercise the 400 error path with mocked `fetch` responses, which the dumper could not distinguish from genuine failures; it now skips persistence under the Bun test runner (`isBunTestRuntime()`).
+- Fixed Anthropic Opus requests unnecessarily forcing `tool_choice.disable_parallel_tool_use`, allowing Claude Opus to use the provider's default parallel tool-calling behavior again.
+- Fixed parallel `function_call` items losing arguments against llama.cpp's OpenAI Responses endpoint (`/v1/responses`), where every call but the last finalized with `{}` and the agent rejected them with `path: Invalid input: expected string, received undefined`. llama.cpp's `to_json_oaicompat_resp` emits `output_item.added` with only `item.call_id` (no `item.id`, no `output_index`) while the matching `function_call_arguments.delta` carries `item_id: "fc_<call_id>"`. `processResponsesStream` now registers function-call and custom-tool-call items under `item.call_id` as a secondary lookup key (alongside `item.id`/`output_index`) so identifier-deviant hosts route deltas and done events to the right block. ([#2015](https://github.com/can1357/oh-my-pi/issues/2015))
 
 ## [15.10.0] - 2026-06-06
 
@@ -37,7 +40,6 @@
 - Fixed Cloud Code Assist (Antigravity / Gemini CLI) rejecting the `github` tool with HTTP 400 when the `pr` parameter schema contained `anyOf: [string, array]`. The CCA mixed-type combiner collapse picked the first non-null type (`string`) but indiscriminately copied type-specific keys from variant branches — `items` from the array variant leaked onto the string-typed result, producing `{type: "string", items: {...}}` which Google's API rejects as invalid. The collapse now filters merged variant fields against the winning type's allowed key set. ([#2002](https://github.com/can1357/oh-my-pi/pull/2002))
 - Fixed OpenAI Responses-family providers (Codex, OpenAI Responses, Azure Responses) rejecting requests with `400 No tool output found for function call …` after the user branched/navigated the session tree to a node that ends on a tool call (the tool-result child is dropped from the reconstructed history) or after a turn was aborted/crashed between the call streaming and its result persisting. The converters now synthesize a placeholder `function_call_output`/`custom_tool_call_output` immediately after any unpaired `function_call`/`custom_tool_call`, symmetric to the existing orphan-output repair, so the model still sees the call and can recover instead of the whole request 400ing.
 - Fixed Anthropic-compatible reasoning endpoints losing prior-turn reasoning on continuation requests when they emit unsigned `thinking` blocks. `convertAnthropicMessages` treated unknown endpoints as signature-enforcing and demoted unsigned reasoning to `type: "text"`, which destabilized tool-call argument serialization on the next turn — the upstream symptom behind the `args?.ops?.map is not a function` crash reported against the `todo` tool. Official `api.anthropic.com` keeps the conservative text fallback; non-official `anthropic-messages` reasoning models now replay unsigned reasoning as native `type: "thinking"` ([#2005](https://github.com/can1357/oh-my-pi/issues/2005)).
-- Fixed parallel `function_call` items losing arguments against llama.cpp's OpenAI Responses endpoint (`/v1/responses`), where every call but the last finalized with `{}` and the agent rejected them with `path: Invalid input: expected string, received undefined`. llama.cpp's `to_json_oaicompat_resp` emits `output_item.added` with only `item.call_id` (no `item.id`, no `output_index`) while the matching `function_call_arguments.delta` carries `item_id: "fc_<call_id>"`. `processResponsesStream` now registers function-call and custom-tool-call items under `item.call_id` as a secondary lookup key (alongside `item.id`/`output_index`) so identifier-deviant hosts route deltas and done events to the right block. ([#2015](https://github.com/can1357/oh-my-pi/issues/2015))
 
 ## [15.9.67] - 2026-06-06
 
@@ -3001,4 +3003,4 @@ _Dedicated to Peter's shoulder ([@steipete](https://twitter.com/steipete))_
 
 ## [0.9.4] - 2025-11-26
 
-Initial release with multi-provider LLM support.
\ No newline at end of file
+Initial release with multi-provider LLM support.
diff --git a/packages/ai/src/model-thinking.ts b/packages/ai/src/model-thinking.ts
index 7c963bdbe..3758c6d6c 100644
--- a/packages/ai/src/model-thinking.ts
+++ b/packages/ai/src/model-thinking.ts
@@ -363,18 +363,6 @@ export function supportsMidConversationSystemMessages(modelId: string): boolean
 	return parsed.kind === "opus" && semverGte(parsed.version, "4.8");
 }
 
-/**
- * Claude Opus 4.8 must emit at most one tool call per turn: the Anthropic
- * Messages provider sends `tool_choice.disable_parallel_tool_use = true` for
- * this model. Scoped to exactly 4.8 — earlier and later Opus versions keep
- * Anthropic's default parallel tool-calling.
- */
-export function disablesParallelToolUse(modelId: string): boolean {
-	const parsed = parseAnthropicModel(getCanonicalModelId(modelId));
-	if (!parsed) return false;
-	return parsed.kind === "opus" && semverEqual(parsed.version, "4.8");
-}
-
 function anthropicModelHasRealXHighEffort<TApi extends Api>(model: ApiModel<TApi>): boolean {
 	if (model.api !== "anthropic-messages") return false;
 	const parsedModel = parseKnownModel(model.id);
diff --git a/packages/ai/src/providers/anthropic.ts b/packages/ai/src/providers/anthropic.ts
index f96477f4c..c8e9f3c35 100644
--- a/packages/ai/src/providers/anthropic.ts
+++ b/packages/ai/src/providers/anthropic.ts
@@ -13,7 +13,6 @@ import {
 	readSseEvents,
 } from "@oh-my-pi/pi-utils";
 import {
-	disablesParallelToolUse,
 	hasOpus47ApiRestrictions,
 	mapEffortToAnthropicAdaptiveEffort,
 	supportsMidConversationSystemMessages,
@@ -2371,21 +2370,6 @@ function buildParams(
 		}
 	}
 
-	// Claude Opus 4.8 must emit at most one tool call per turn. Force
-	// `disable_parallel_tool_use` onto the outgoing tool_choice (synthesizing an
-	// `auto` choice when none is set). Gated on tools being present: Anthropic
-	// rejects `tool_choice` without `tools`, and parallelism is moot otherwise.
-	// `none` rejects the field, so leave it untouched. A fresh object is built
-	// rather than mutated so the caller's `options.toolChoice` is never aliased.
-	if (disablesParallelToolUse(model.id) && params.tools && params.tools.length > 0) {
-		const current = params.tool_choice;
-		if (!current) {
-			params.tool_choice = { type: "auto", disable_parallel_tool_use: true };
-		} else if (current.type !== "none") {
-			params.tool_choice = { ...current, disable_parallel_tool_use: true };
-		}
-	}
-
 	const shouldInjectClaudeCodeInstruction = isOAuthToken && !model.id.startsWith("claude-3-5-haiku");
 	const firstUserMessageText = shouldInjectClaudeCodeInstruction
 		? extractClaudeCodeFirstUserMessageText(context.messages)

From 8543dcaee45575c7d12c84d94eaed741ba00048e Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:49:12 +0200
Subject: [PATCH 136/181] fix(tui): fixed uppercase Shift preservation for
 printable keybindings

- Updated key canonicalization in keybinding parsing to parse modifiers case-insensitively and infer `shift` from printable uppercase keys.
- Added regression tests for `shift+a` matching uppercase `A` and for cursor anchoring during no-append live repaint scenarios.
- Recorded the uppercase Shift keybinding fix in the package changelog entry.
---
 packages/tui/CHANGELOG.md                  |  1 +
 packages/tui/src/keybindings.ts            | 30 ++++++++++--
 packages/tui/test/issue-1974-repro.test.ts | 57 +++++++++++++++++++++-
 packages/tui/test/keybindings.test.ts      |  9 ++++
 4 files changed, 91 insertions(+), 6 deletions(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 9ba2fa761..73a47f90f 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -32,6 +32,7 @@
 - Fixed fullscreen overlay alt-frame rendering to reuse the current line-preparation path instead of calling removed fitting helpers.
 - Reduced TUI render-path line fitting by deferring overlay base-frame fitting until an overlay rebuild and by reusing already-fitted lines in emitters.
 - Reduced live-region pinned repaint output by diffing unchanged viewport rows when no sealed rows are being committed to native scrollback.
+- Fixed keybinding matching so printable uppercase input preserves `Shift` for bindings such as `shift+a`.
 - Optimized terminal image-line detection and Thai/Lao AM normalization checks to avoid hot-path regex scans and substring allocations.
 - Fixed `Markdown.render()` cache hits returning the cache's mutable backing array, which let callers that append extra rows corrupt cached Markdown and duplicate those rows on every redraw.
 - Fixed first-paint full replays for callers that intentionally replace terminal history by allowing `TUI.start({ clearScrollback: true })`, so they do not briefly append an entire initial frame before the first clean replay.
diff --git a/packages/tui/src/keybindings.ts b/packages/tui/src/keybindings.ts
index 1e097bad8..e03954f09 100644
--- a/packages/tui/src/keybindings.ts
+++ b/packages/tui/src/keybindings.ts
@@ -166,24 +166,44 @@ const SHIFTED_SYMBOL_KEYS = new Set<string>([
 
 const MODIFIER_ORDER = ["ctrl", "shift", "alt", "super"] as const;
 
+function startsWithModifier(key: string, offset: number, modifier: string): boolean {
+	if (key.length <= offset + modifier.length || key.charCodeAt(offset + modifier.length) !== 43) return false;
+	for (let i = 0; i < modifier.length; i++) {
+		const actual = key.charCodeAt(offset + i);
+		const expected = modifier.charCodeAt(i);
+		if (actual !== expected && actual !== expected - 32) return false;
+	}
+	return true;
+}
+
+function isAsciiUppercaseLetter(key: string): boolean {
+	if (key.length !== 1) return false;
+	const code = key.charCodeAt(0);
+	return code >= 65 && code <= 90;
+}
+
 function canonicalKeyId(key: string): string {
-	let remaining = key.toLowerCase();
+	let offset = 0;
 	const modifiers: string[] = [];
 	let foundModifier = true;
 
 	while (foundModifier) {
 		foundModifier = false;
 		for (const modifier of MODIFIER_ORDER) {
-			const prefix = `${modifier}+`;
-			if (remaining.startsWith(prefix)) {
+			if (startsWithModifier(key, offset, modifier)) {
 				modifiers.push(modifier);
-				remaining = remaining.slice(prefix.length);
+				offset += modifier.length + 1;
 				foundModifier = true;
 				break;
 			}
 		}
 	}
-	const base = remaining === "esc" ? "escape" : remaining === "return" ? "enter" : remaining;
+	const rawBase = key.slice(offset);
+	const lowerBase = rawBase.toLowerCase();
+	const base = lowerBase === "esc" ? "escape" : lowerBase === "return" ? "enter" : lowerBase;
+	if (isAsciiUppercaseLetter(rawBase) && !modifiers.includes("shift")) {
+		modifiers.push("shift");
+	}
 
 	if (modifiers.length === 0) return base;
 	modifiers.sort(
diff --git a/packages/tui/test/issue-1974-repro.test.ts b/packages/tui/test/issue-1974-repro.test.ts
index 915d93814..43aea302b 100644
--- a/packages/tui/test/issue-1974-repro.test.ts
+++ b/packages/tui/test/issue-1974-repro.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { type Component, type NativeScrollbackLiveRegion, TERMINAL, TUI } from "@oh-my-pi/pi-tui";
+import { type Component, CURSOR_MARKER, type NativeScrollbackLiveRegion, TERMINAL, TUI } from "@oh-my-pi/pi-tui";
 import { VirtualTerminal } from "./virtual-terminal";
 
 // Regression test for https://github.com/can1357/oh-my-pi/issues/1974
@@ -70,6 +70,28 @@ class StreamingLiveRegion implements Component, NativeScrollbackLiveRegion {
 	}
 }
 
+class VolatileLiveRegion implements Component, NativeScrollbackLiveRegion {
+	#lines: string[];
+
+	constructor(lines: string[]) {
+		this.#lines = [...lines];
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		return this.#lines.map(line => line.slice(0, width));
+	}
+
+	setLines(lines: string[]): void {
+		this.#lines = [...lines];
+	}
+
+	getNativeScrollbackLiveRegionStart(): number | undefined {
+		return 0;
+	}
+}
+
 async function settle(term: VirtualTerminal): Promise<void> {
 	const nextTick = Promise.withResolvers<void>();
 	process.nextTick(nextTick.resolve);
@@ -304,4 +326,37 @@ describe("issue #1974: tmux scrollback rendering", () => {
 			});
 		});
 	});
+
+	it("keeps the cursor anchored when a no-append live repaint shifts the viewport", async () => {
+		if (process.platform === "win32") return;
+
+		await withTerminalRisk(true, async () => {
+			const term = new VirtualTerminal(20, 5, 1_000);
+			overrideProbe(term, undefined);
+			const tui = new TUI(term, true);
+			const stream = new VolatileLiveRegion([]);
+			tui.addChild(stream);
+
+			try {
+				tui.start();
+				tui.setEagerNativeScrollbackRebuild(true);
+				await settle(term);
+
+				stream.setLines(["same", "same", "same", `same${CURSOR_MARKER}`, "same"]);
+				tui.requestRender();
+				await settle(term);
+				expect(term.getCursor()).toEqual({ row: 3, col: 4 });
+
+				stream.setLines(["same", "same", "same", "same", `same${CURSOR_MARKER}`, "same"]);
+				tui.requestRender();
+				await settle(term);
+
+				expect(strip(term.getViewport())).toEqual(["same", "same", "same", "same", "same"]);
+				expect(term.getCursor()).toEqual({ row: 3, col: 4 });
+			} finally {
+				tui.stop();
+				await term.flush();
+			}
+		});
+	});
 });
diff --git a/packages/tui/test/keybindings.test.ts b/packages/tui/test/keybindings.test.ts
index a6d616c06..10a3d93b8 100644
--- a/packages/tui/test/keybindings.test.ts
+++ b/packages/tui/test/keybindings.test.ts
@@ -20,6 +20,15 @@ describe("KeybindingsManager", () => {
 		expect(keybindings.getKeys("tui.editor.cursorUp")).toEqual(["up"]);
 	});
 
+	it("preserves Shift when matching printable uppercase letters", () => {
+		const keybindings = new KeybindingsManager(TUI_KEYBINDINGS, {
+			"tui.input.copy": "shift+a",
+		});
+
+		expect(keybindings.matches("A", "tui.input.copy")).toBe(true);
+		expect(keybindings.matches("a", "tui.input.copy")).toBe(false);
+	});
+
 	it("still reports direct user binding conflicts without evicting defaults", () => {
 		const keybindings = new KeybindingsManager(TUI_KEYBINDINGS, {
 			"tui.input.submit": "ctrl+x",

From 64e71e16fe558481e28df8e7a68bd354aafddd94 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 06:50:06 +0000
Subject: [PATCH 137/181] fix(ai): scoped union branch tagging to combinator
 path

Only mark Zod and JSON Schema validation issues as union-branch when their own path matches the combinator's path so nested array fields inside a tag-selected branch keep their singleton-wrap repair.

Fixes #2026
---
 .../src/utils/schema/json-schema-validator.ts | 10 +++-
 packages/ai/src/utils/validation.ts           |  6 +-
 .../ai/test/tool-argument-coercion.test.ts    | 55 +++++++++++++++++++
 3 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/packages/ai/src/utils/schema/json-schema-validator.ts b/packages/ai/src/utils/schema/json-schema-validator.ts
index fa8c82157..79a93052e 100644
--- a/packages/ai/src/utils/schema/json-schema-validator.ts
+++ b/packages/ai/src/utils/schema/json-schema-validator.ts
@@ -250,8 +250,16 @@ function validateSchemaNode(
 		const branchValid = keyword === "anyOf" ? matches > 0 : matches === 1;
 		if (!branchValid) {
 			if (matches === 0 && firstIssues && firstIssues.length > 0) {
+				// Only tag issues that sit at the combinator's own path as
+				// union-branch; deeper issues describe a specific field within
+				// the failed branch and should remain individually repairable.
+				const unionDepth = path.length;
 				for (const branchIssue of firstIssues) {
-					issues.push({ ...branchIssue, fromUnionBranch: true });
+					if (branchIssue.path.length === unionDepth) {
+						issues.push({ ...branchIssue, fromUnionBranch: true });
+					} else {
+						issues.push(branchIssue);
+					}
 				}
 			} else {
 				pushIssue(
diff --git a/packages/ai/src/utils/validation.ts b/packages/ai/src/utils/validation.ts
index e39e7d188..506c72978 100644
--- a/packages/ai/src/utils/validation.ts
+++ b/packages/ai/src/utils/validation.ts
@@ -784,9 +784,13 @@ function flattenIssues(issues: ReadonlyArray<ZodIssue>): FlatIssue[] {
 		if (issue.code === "invalid_union") {
 			const inner = (issue as unknown as { errors?: ReadonlyArray<ReadonlyArray<ZodIssue>> }).errors;
 			if (inner) {
+				// A union-branch issue only competes with a sibling branch when it
+				// sits at the union node's own path. Issues whose own path is
+				// non-empty live on a deeper field that an already-identified
+				// branch owns, so the singleton-array repair should still apply.
 				for (const branch of inner) {
 					for (const child of branch) {
-						walk(child, fullPath, true);
+						walk(child, fullPath, child.path.length === 0);
 					}
 				}
 			}
diff --git a/packages/ai/test/tool-argument-coercion.test.ts b/packages/ai/test/tool-argument-coercion.test.ts
index 586ae2942..e0ca64378 100644
--- a/packages/ai/test/tool-argument-coercion.test.ts
+++ b/packages/ai/test/tool-argument-coercion.test.ts
@@ -195,6 +195,61 @@ describe("Tool argument coercion", () => {
 		).toThrow("Validation failed");
 	});
 
+	it("still wraps nested array fields inside a tag-selected Zod union branch", () => {
+		const tool: Tool = {
+			name: "tagged_union",
+			description: "",
+			parameters: z.union([
+				z.object({ type: z.literal("indices"), indices: z.array(z.number()) }),
+				z.object({ type: z.literal("all") }),
+			]),
+		};
+
+		const result = validateToolArguments(tool, {
+			type: "toolCall",
+			id: "call-tagged-union",
+			name: "tagged_union",
+			arguments: { type: "indices", indices: 1 },
+		});
+
+		expect(result).toEqual({ type: "indices", indices: [1] });
+	});
+
+	it("still wraps nested array fields inside a tag-selected JSON Schema anyOf branch", () => {
+		const tool: Tool = {
+			name: "tagged_json_union",
+			description: "",
+			parameters: {
+				anyOf: [
+					{
+						type: "object",
+						properties: {
+							type: { const: "indices" },
+							indices: { type: "array", items: { type: "number" } },
+						},
+						required: ["type", "indices"],
+						additionalProperties: false,
+					},
+					{
+						type: "object",
+						properties: { type: { const: "all" } },
+						required: ["type"],
+						additionalProperties: false,
+					},
+				],
+			},
+		};
+
+		const result = validateToolArguments(tool, {
+			type: "toolCall",
+			id: "call-tagged-json-union",
+			name: "tagged_json_union",
+			arguments: { type: "indices", indices: 1 },
+		});
+
+		expect(result).toEqual({ type: "indices", indices: [1] });
+	});
+
 	it("parses JSON objects in string values when schema expects object", () => {
 		const tool: Tool = {
 			name: "t4",

From a40f01c1e9ce35651de7dfbe70ecfd83f36c660c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:50:14 +0200
Subject: [PATCH 138/181] fix(tui): fixed no-append live-region repaints during
 viewport shifts

- Constrained the no-append repaint optimization to execute only when the logical viewport position was unchanged.
- Documented the live-region pinned repaint cursor re-anchoring fix in the TUI changelog entry.
---
 packages/tui/CHANGELOG.md | 1 +
 packages/tui/src/tui.ts   | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 73a47f90f..485d298ad 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -32,6 +32,7 @@
 - Fixed fullscreen overlay alt-frame rendering to reuse the current line-preparation path instead of calling removed fitting helpers.
 - Reduced TUI render-path line fitting by deferring overlay base-frame fitting until an overlay rebuild and by reusing already-fitted lines in emitters.
 - Reduced live-region pinned repaint output by diffing unchanged viewport rows when no sealed rows are being committed to native scrollback.
+- Fixed no-append live-region pinned repaints to re-anchor the hardware cursor when the logical viewport shifts.
 - Fixed keybinding matching so printable uppercase input preserves `Shift` for bindings such as `shift+a`.
 - Optimized terminal image-line detection and Thai/Lao AM normalization checks to avoid hot-path regex scans and substring allocations.
 - Fixed `Markdown.render()` cache hits returning the cache's mutable backing array, which let callers that append extra rows corrupt cached Markdown and duplicate those rows on every redraw.
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 9fa0129cc..e71ee6818 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -2849,7 +2849,7 @@ export class TUI extends Container {
 		const boundedAppendTo = Math.max(0, Math.min(appendTo, naturalViewportTop, lines.length));
 		const boundedAppendFrom = Math.max(0, Math.min(appendFrom, boundedAppendTo));
 
-		if (boundedAppendFrom === boundedAppendTo) {
+		if (boundedAppendFrom === boundedAppendTo && viewportTop === prevViewportTop) {
 			let firstChangedScreenRow = -1;
 			let lastChangedScreenRow = -1;
 			for (let screenRow = 0; screenRow < height; screenRow++) {

From b65851d5043d8ec3092b0d34b8670cdb47c58fde Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 08:53:01 +0200
Subject: [PATCH 139/181] feat(coding-agent): enabled smooth streaming reveal
 mode with 30 FPS and new setting

- Added `display.smoothStreaming` to settings schema.
- Updated streaming-reveal behavior to produce smooth 30 FPS reveals.
- Updated event-controller flow to support smooth streaming reveal mode.
- Expanded streaming-reveal tests for the new smooth streaming behavior.
---
 packages/coding-agent/CHANGELOG.md            |   4 +-
 .../src/config/settings-schema.ts             |  10 +
 .../src/modes/controllers/event-controller.ts |  14 +-
 .../src/modes/controllers/streaming-reveal.ts | 212 +++++++++++++++++
 .../test/streaming-reveal.test.ts             | 223 ++++++++++++++++++
 5 files changed, 460 insertions(+), 3 deletions(-)
 create mode 100644 packages/coding-agent/src/modes/controllers/streaming-reveal.ts
 create mode 100644 packages/coding-agent/test/streaming-reveal.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 9c89f2648..2b3f50441 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -1,8 +1,10 @@
 # Changelog
 
 ## [Unreleased]
+
 ### Added
 
+- Added `display.smoothStreaming` setting (default `true`) to let users enable or disable smooth assistant-stream text reveal
 - Added `/tan <work>` slash command to fork the current conversation into a background agent so tangential work can continue asynchronously while your main session stays active
 - Added a background `/tan` dispatch message that records the handoff in the transcript and marks the delegated work as non-blocking
 - Added `providerPromptCacheKey` support to `CreateAgentSessionOptions` so `/tan` background sessions can reuse the parent session’s prompt-cache lineage
@@ -17,6 +19,7 @@
 
 ### Changed
 
+- Changed assistant streaming output to reveal text incrementally at 30 FPS with grapheme-safe adaptive catch-up, instead of replacing the whole message chunk-by-chunk
 - Changed shimmer-driven TUI animations (working text, pending bash/eval borders, and theme activity-spinner documentation) to render at 30fps instead of 60fps.
 - Changed running `task` tool agent rows to use a static `•` marker and shimmer only the subagent name, leaving descriptions, stats, and nested tool detail text solid while removing the rotating status glyph from those rows.
 - Changed settings singleton method access to reuse bound methods for the active instance instead of allocating a new bound function on every `settings.get` lookup.
@@ -43,7 +46,6 @@
 
 - Fixed the working-status shimmer to opt into the loader's 30fps animated-message repaint path while keeping both the status spinner and pending bash/eval tool spinners on their normal 80 ms glyph cadence.
 - Fixed consecutive `read` tool calls failing to collapse into a single grouped block when a reasoning model emits one read per completion (`[thinking, read]`). The read group was reset on every assistant `message_start`, so each read rendered as its own one-entry `Read …` line; now a read run accretes across completions and is broken only by a rendered non-empty text/thinking block, a non-read tool, or a user/IRC message — matching the transcript-rebuild path. `ReadToolGroupComponent` now reports its live/finalized state so the growing `Read (N)` header repaints correctly on native-scrollback (risk) terminals.
-
 - Fixed the `task` tool shared-context brief rendering raw Markdown headings (`# Goal`, `# Constraints`) inside framed call/result blocks instead of using the normal Markdown renderer.
 - Fixed the animated pending border on `bash`/`eval` blocks leaving a frozen dark "bar" segment behind after a backgrounded command finalized through the async update path. Once a command is auto-backgrounded (`details.async.state === "running"`) the block stays "partial" in the TUI until the async job-manager delivers the final result, but it also gets committed to native scrollback — so a mid-sweep shimmer frame baked a stray darkened border segment into the committed copy. The border now stops animating (and the 60fps redraw loop stops) the moment a block enters the backgrounded state, so the committed frame is a clean static border.
 - Fixed cold `omp` launch to clear native terminal history on the first paint, avoiding a once-per-launch duplicate welcome/transcript copy before the normal session replay.
diff --git a/packages/coding-agent/src/config/settings-schema.ts b/packages/coding-agent/src/config/settings-schema.ts
index 96c8575b4..664488632 100644
--- a/packages/coding-agent/src/config/settings-schema.ts
+++ b/packages/coding-agent/src/config/settings-schema.ts
@@ -660,6 +660,16 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"display.smoothStreaming": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "appearance",
+			label: "Smooth Streaming",
+			description: "Reveal assistant text smoothly while streamed chunks arrive",
+		},
+	},
+
 	"display.showTokenUsage": {
 		type: "boolean",
 		default: false,
diff --git a/packages/coding-agent/src/modes/controllers/event-controller.ts b/packages/coding-agent/src/modes/controllers/event-controller.ts
index 084ee4d29..d1f1e8e28 100644
--- a/packages/coding-agent/src/modes/controllers/event-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/event-controller.ts
@@ -20,6 +20,7 @@ import type { AgentSessionEvent } from "../../session/agent-session";
 import { isSilentAbort, readPendingDisplayTag, resolveAbortLabel } from "../../session/messages";
 import type { ResolveToolDetails } from "../../tools/resolve";
 import { interruptHint } from "../shared";
+import { StreamingRevealController } from "./streaming-reveal";
 
 type AgentSessionEventKind = AgentSessionEvent["type"];
 
@@ -66,9 +67,15 @@ export class EventController {
 	#pinnedErrorComponent: AssistantMessageComponent | undefined = undefined;
 	#idleCompactionTimer?: NodeJS.Timeout;
 	#ircExpiryTimers = new Map<string, NodeJS.Timeout>();
+	#streamingReveal: StreamingRevealController;
 	#handlers: AgentSessionEventHandlers;
 
 	constructor(private ctx: InteractiveModeContext) {
+		this.#streamingReveal = new StreamingRevealController({
+			getSmoothStreaming: () => this.ctx.settings.get("display.smoothStreaming"),
+			getHideThinkingBlock: () => this.ctx.hideThinkingBlock,
+			requestRender: () => this.ctx.ui.requestRender(),
+		});
 		this.#handlers = {
 			agent_start: e => this.#handleAgentStart(e),
 			agent_end: e => this.#handleAgentEnd(e),
@@ -101,6 +108,7 @@ export class EventController {
 	}
 
 	dispose(): void {
+		this.#streamingReveal.stop();
 		this.#cancelIdleCompaction();
 		for (const timer of this.#ircExpiryTimers.values()) {
 			clearTimeout(timer);
@@ -317,7 +325,7 @@ export class EventController {
 			);
 			this.ctx.streamingMessage = event.message;
 			this.ctx.chatContainer.addChild(this.ctx.streamingComponent);
-			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage);
+			this.#streamingReveal.begin(this.ctx.streamingComponent, this.ctx.streamingMessage);
 			this.ctx.ui.requestRender();
 		}
 	}
@@ -361,7 +369,7 @@ export class EventController {
 	async #handleMessageUpdate(event: Extract<AgentSessionEvent, { type: "message_update" }>): Promise<void> {
 		if (this.ctx.streamingComponent && event.message.role === "assistant") {
 			this.ctx.streamingMessage = event.message;
-			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage);
+			this.#streamingReveal.setTarget(this.ctx.streamingMessage);
 
 			const visibleBlockCount = this.ctx.streamingMessage.content.filter(
 				content =>
@@ -462,6 +470,7 @@ export class EventController {
 		}
 		if (this.ctx.streamingComponent && event.message.role === "assistant") {
 			this.ctx.streamingMessage = event.message;
+			this.#streamingReveal.stop();
 			let errorMessage: string | undefined;
 			const aborted = this.ctx.streamingMessage.stopReason === "aborted";
 			const silentlyAborted = aborted && isSilentAbort(this.ctx.streamingMessage.errorMessage);
@@ -667,6 +676,7 @@ export class EventController {
 	async #handleAgentEnd(_event: Extract<AgentSessionEvent, { type: "agent_end" }>): Promise<void> {
 		this.#agentTurnActive = false;
 		this.#assistantMessageStreaming = false;
+		this.#streamingReveal.stop();
 		if (this.ctx.loadingAnimation) {
 			this.ctx.loadingAnimation.stop();
 			this.ctx.loadingAnimation = undefined;
diff --git a/packages/coding-agent/src/modes/controllers/streaming-reveal.ts b/packages/coding-agent/src/modes/controllers/streaming-reveal.ts
new file mode 100644
index 000000000..1e4edccbf
--- /dev/null
+++ b/packages/coding-agent/src/modes/controllers/streaming-reveal.ts
@@ -0,0 +1,212 @@
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import { getSegmenter } from "@oh-my-pi/pi-tui";
+import type { AssistantMessageComponent } from "../components/assistant-message";
+
+export const STREAMING_REVEAL_FRAME_MS = 1000 / 30;
+export const MIN_STEP = 3;
+export const CATCHUP_FRAMES = 8;
+
+type AssistantContentBlock = AssistantMessage["content"][number];
+type StreamingRevealComponent = Pick<AssistantMessageComponent, "updateContent">;
+
+type StreamingRevealControllerOptions = {
+	getSmoothStreaming(): boolean;
+	getHideThinkingBlock(): boolean;
+	requestRender(): void;
+};
+
+function countGraphemes(text: string): number {
+	let count = 0;
+	for (const _segment of getSegmenter().segment(text)) {
+		count += 1;
+	}
+	return count;
+}
+
+function sliceGraphemes(text: string, units: number): string {
+	if (units <= 0 || text.length === 0) return "";
+	let count = 0;
+	for (const { index, segment } of getSegmenter().segment(text)) {
+		count += 1;
+		if (count >= units) {
+			const end = index + segment.length;
+			return end >= text.length ? text : text.slice(0, end);
+		}
+	}
+	return text;
+}
+
+export function visibleUnits(message: AssistantMessage, hideThinking: boolean): number {
+	let total = 0;
+	for (const block of message.content) {
+		if (block.type === "text") {
+			total += countGraphemes(block.text);
+		} else if (block.type === "thinking" && !hideThinking) {
+			total += countGraphemes(block.thinking);
+		}
+	}
+	return total;
+}
+
+function revealTextBlock(
+	block: Extract<AssistantContentBlock, { type: "text" }>,
+	remaining: number,
+): AssistantContentBlock {
+	if (remaining <= 0) return block.text.length === 0 ? block : { ...block, text: "" };
+	const units = countGraphemes(block.text);
+	if (remaining >= units) return block;
+	return { ...block, text: sliceGraphemes(block.text, remaining) };
+}
+
+function revealThinkingBlock(
+	block: Extract<AssistantContentBlock, { type: "thinking" }>,
+	remaining: number,
+): AssistantContentBlock {
+	if (remaining <= 0) return block.thinking.length === 0 ? block : { ...block, thinking: "" };
+	const units = countGraphemes(block.thinking);
+	if (remaining >= units) return block;
+	return { ...block, thinking: sliceGraphemes(block.thinking, remaining) };
+}
+
+export function buildDisplayMessage(
+	target: AssistantMessage,
+	revealed: number,
+	hideThinking: boolean,
+): AssistantMessage {
+	let remaining = Math.max(0, Math.floor(revealed));
+	const content: AssistantContentBlock[] = [];
+	for (const block of target.content) {
+		if (block.type === "text") {
+			content.push(revealTextBlock(block, remaining));
+			remaining = Math.max(0, remaining - countGraphemes(block.text));
+		} else if (block.type === "thinking" && !hideThinking) {
+			content.push(revealThinkingBlock(block, remaining));
+			remaining = Math.max(0, remaining - countGraphemes(block.thinking));
+		} else {
+			content.push(block);
+		}
+	}
+	return { ...target, content };
+}
+
+export function nextStep(backlog: number): number {
+	return Math.max(MIN_STEP, Math.ceil(Math.max(0, backlog) / CATCHUP_FRAMES));
+}
+
+export class StreamingRevealController {
+	readonly #getSmoothStreaming: () => boolean;
+	readonly #getHideThinkingBlock: () => boolean;
+	readonly #requestRender: () => void;
+	#target: AssistantMessage | undefined;
+	#component: StreamingRevealComponent | undefined;
+	#timer: NodeJS.Timeout | undefined;
+	#revealed = 0;
+	#hideThinkingBlock = false;
+	#smoothStreaming = true;
+
+	constructor(options: StreamingRevealControllerOptions) {
+		this.#getSmoothStreaming = options.getSmoothStreaming;
+		this.#getHideThinkingBlock = options.getHideThinkingBlock;
+		this.#requestRender = options.requestRender;
+	}
+
+	begin(component: StreamingRevealComponent, message: AssistantMessage): void {
+		this.stop();
+		this.#component = component;
+		this.#target = message;
+		this.#revealed = 0;
+		this.#hideThinkingBlock = this.#getHideThinkingBlock();
+		this.#smoothStreaming = this.#getSmoothStreaming();
+		if (!this.#smoothStreaming) {
+			component.updateContent(message);
+			return;
+		}
+		const total = visibleUnits(message, this.#hideThinkingBlock);
+		if (message.content.some(block => block.type === "toolCall")) {
+			// A tool call is a transcript-order boundary: finish any leading
+			// assistant text before EventController renders the separate tool card.
+			this.#revealed = total;
+			component.updateContent(buildDisplayMessage(message, this.#revealed, this.#hideThinkingBlock));
+			return;
+		}
+		this.#renderCurrent();
+		this.#syncTimer(total);
+	}
+
+	setTarget(message: AssistantMessage): void {
+		this.#target = message;
+		if (!this.#component) return;
+		if (!this.#smoothStreaming) {
+			this.#component.updateContent(message);
+			return;
+		}
+		const total = visibleUnits(message, this.#hideThinkingBlock);
+		if (message.content.some(block => block.type === "toolCall")) {
+			// A tool call is a transcript-order boundary: finish any leading
+			// assistant text before EventController renders the separate tool card.
+			this.#revealed = total;
+			this.#stopTimer();
+			this.#component.updateContent(buildDisplayMessage(message, this.#revealed, this.#hideThinkingBlock));
+			return;
+		}
+		if (this.#revealed > total) {
+			this.#revealed = total;
+		}
+		this.#renderCurrent();
+		this.#syncTimer(total);
+	}
+
+	stop(): void {
+		this.#stopTimer();
+		this.#target = undefined;
+		this.#component = undefined;
+		this.#revealed = 0;
+	}
+
+	#renderCurrent(): void {
+		if (!this.#target || !this.#component) return;
+		this.#component.updateContent(buildDisplayMessage(this.#target, this.#revealed, this.#hideThinkingBlock));
+	}
+
+	#syncTimer(total = this.#target ? visibleUnits(this.#target, this.#hideThinkingBlock) : 0): void {
+		if (!this.#target || !this.#component || this.#revealed >= total) {
+			this.#stopTimer();
+			return;
+		}
+		this.#startTimer();
+	}
+
+	#startTimer(): void {
+		if (this.#timer) return;
+		this.#timer = setInterval(() => {
+			this.#tick();
+		}, STREAMING_REVEAL_FRAME_MS);
+		this.#timer.unref?.();
+	}
+
+	#stopTimer(): void {
+		if (!this.#timer) return;
+		clearInterval(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#tick(): void {
+		const target = this.#target;
+		const component = this.#component;
+		if (!target || !component) {
+			this.stop();
+			return;
+		}
+		const total = visibleUnits(target, this.#hideThinkingBlock);
+		if (this.#revealed >= total) {
+			this.#stopTimer();
+			return;
+		}
+		this.#revealed = Math.min(total, this.#revealed + nextStep(total - this.#revealed));
+		component.updateContent(buildDisplayMessage(target, this.#revealed, this.#hideThinkingBlock));
+		this.#requestRender();
+		if (this.#revealed >= total) {
+			this.#stopTimer();
+		}
+	}
+}
diff --git a/packages/coding-agent/test/streaming-reveal.test.ts b/packages/coding-agent/test/streaming-reveal.test.ts
new file mode 100644
index 000000000..0c727ad91
--- /dev/null
+++ b/packages/coding-agent/test/streaming-reveal.test.ts
@@ -0,0 +1,223 @@
+import { afterEach, describe, expect, it, vi } from "bun:test";
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import {
+	buildDisplayMessage,
+	CATCHUP_FRAMES,
+	MIN_STEP,
+	nextStep,
+	STREAMING_REVEAL_FRAME_MS,
+	StreamingRevealController,
+	visibleUnits,
+} from "@oh-my-pi/pi-coding-agent/modes/controllers/streaming-reveal";
+
+function makeUsage(): AssistantMessage["usage"] {
+	return {
+		input: 0,
+		output: 0,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: 0,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+}
+
+function makeMessage(content: AssistantMessage["content"]): AssistantMessage {
+	return {
+		role: "assistant",
+		content,
+		api: "anthropic-messages",
+		provider: "anthropic",
+		model: "mock",
+		usage: makeUsage(),
+		stopReason: "stop",
+		timestamp: 0,
+	};
+}
+
+function textAt(message: AssistantMessage, index: number): string {
+	const block = message.content[index];
+	if (block?.type !== "text") {
+		throw new Error(`Expected text block at index ${index}`);
+	}
+	return block.text;
+}
+
+function thinkingAt(message: AssistantMessage, index: number): string {
+	const block = message.content[index];
+	if (block?.type !== "thinking") {
+		throw new Error(`Expected thinking block at index ${index}`);
+	}
+	return block.thinking;
+}
+
+class RecordingComponent {
+	messages: AssistantMessage[] = [];
+
+	updateContent(message: AssistantMessage): void {
+		this.messages.push(message);
+	}
+}
+
+function latestMessage(component: RecordingComponent): AssistantMessage {
+	const message = component.messages.at(-1);
+	if (!message) {
+		throw new Error("Expected at least one rendered message");
+	}
+	return message;
+}
+
+function makeController(options: { smooth?: boolean; hideThinking?: boolean; requestRender?: () => void } = {}) {
+	const component = new RecordingComponent();
+	const controller = new StreamingRevealController({
+		getSmoothStreaming: () => options.smooth ?? true,
+		getHideThinkingBlock: () => options.hideThinking ?? false,
+		requestRender: options.requestRender ?? (() => {}),
+	});
+	return { component, controller };
+}
+
+describe("streaming reveal", () => {
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it("slices at grapheme boundaries without mutating the target message", () => {
+		const familyEmoji = "👨‍👩‍👧‍👦";
+		const target = makeMessage([{ type: "text", text: `${familyEmoji}B` }]);
+
+		expect(visibleUnits(target, false)).toBe(2);
+		const display = buildDisplayMessage(target, 1, false);
+
+		expect(textAt(display, 0)).toBe(familyEmoji);
+		expect(textAt(target, 0)).toBe(`${familyEmoji}B`);
+	});
+
+	it("excludes hidden thinking from the reveal budget and passes it through", () => {
+		const thinkingBlock = { type: "thinking" as const, thinking: "thought" };
+		const target = makeMessage([thinkingBlock, { type: "text", text: "answer" }]);
+
+		expect(visibleUnits(target, true)).toBe("answer".length);
+		const display = buildDisplayMessage(target, 1, true);
+
+		expect(display.content[0]).toBe(thinkingBlock);
+		expect(thinkingAt(display, 0)).toBe("thought");
+		expect(textAt(display, 1)).toBe("a");
+	});
+
+	it("smooths thinking content when thinking is shown", () => {
+		const target = makeMessage([
+			{ type: "thinking", thinking: "thought" },
+			{ type: "text", text: "answer" },
+		]);
+
+		expect(visibleUnits(target, false)).toBe("thoughtanswer".length);
+		const display = buildDisplayMessage(target, 3, false);
+
+		expect(thinkingAt(display, 0)).toBe("tho");
+		expect(textAt(display, 1)).toBe("");
+	});
+
+	it("uses an adaptive catchup step with the configured floor", () => {
+		const largeBacklog = CATCHUP_FRAMES * 101;
+		const step = nextStep(largeBacklog);
+
+		expect(step).toBe(101);
+		expect(step * CATCHUP_FRAMES).toBeGreaterThanOrEqual(largeBacklog);
+		expect(nextStep(1)).toBe(MIN_STEP);
+		expect(nextStep(MIN_STEP * CATCHUP_FRAMES)).toBe(MIN_STEP);
+	});
+
+	it("reveals cumulative targets to the exact final text with monotonic prefixes", () => {
+		vi.useFakeTimers();
+		const { component, controller } = makeController();
+		const first = makeMessage([{ type: "text", text: "Hello" }]);
+		const second = makeMessage([{ type: "text", text: "Hello world" }]);
+
+		controller.begin(component, makeMessage([{ type: "text", text: "" }]));
+		controller.setTarget(first);
+		for (let i = 0; i < 4; i++) {
+			vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS);
+		}
+		controller.setTarget(second);
+		for (let i = 0; i < 4; i++) {
+			vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS);
+		}
+
+		const renderedTexts = component.messages.map(message => textAt(message, 0));
+		expect(renderedTexts.at(-1)).toBe("Hello world");
+		for (let i = 1; i < renderedTexts.length; i++) {
+			expect(renderedTexts[i].length).toBeGreaterThanOrEqual(renderedTexts[i - 1].length);
+			expect("Hello world".startsWith(renderedTexts[i])).toBe(true);
+		}
+	});
+
+	it("renders full targets immediately when smoothing is disabled", () => {
+		vi.useFakeTimers();
+		const requestRender = vi.fn();
+		const { component, controller } = makeController({ smooth: false, requestRender });
+
+		controller.begin(component, makeMessage([{ type: "text", text: "chunk" }]));
+		controller.setTarget(makeMessage([{ type: "text", text: "chunky" }]));
+		const updates = component.messages.length;
+		vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS * 10);
+
+		expect(textAt(latestMessage(component), 0)).toBe("chunky");
+		expect(component.messages).toHaveLength(updates);
+		expect(requestRender).not.toHaveBeenCalled();
+	});
+
+	it("ticks increasing prefixes at the render cadence", () => {
+		vi.useFakeTimers();
+		const requestRender = vi.fn();
+		const { component, controller } = makeController({ requestRender });
+
+		controller.begin(component, makeMessage([{ type: "text", text: "" }]));
+		controller.setTarget(makeMessage([{ type: "text", text: "abcdefghi" }]));
+
+		vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS);
+		expect(textAt(latestMessage(component), 0)).toBe("abc");
+		vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS);
+		expect(textAt(latestMessage(component), 0)).toBe("abcdef");
+		expect(requestRender).toHaveBeenCalledTimes(2);
+	});
+
+	it("stop halts pending ticker updates", () => {
+		vi.useFakeTimers();
+		const { component, controller } = makeController();
+
+		controller.begin(component, makeMessage([{ type: "text", text: "" }]));
+		controller.setTarget(makeMessage([{ type: "text", text: "abcdefghi" }]));
+		vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS);
+		controller.stop();
+		const updates = component.messages.length;
+		const lastText = textAt(latestMessage(component), 0);
+		vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS * 10);
+
+		expect(component.messages).toHaveLength(updates);
+		expect(textAt(latestMessage(component), 0)).toBe(lastText);
+	});
+
+	it("snaps to full text when a tool call arrives", () => {
+		vi.useFakeTimers();
+		const requestRender = vi.fn();
+		const { component, controller } = makeController({ requestRender });
+
+		controller.begin(component, makeMessage([{ type: "text", text: "" }]));
+		controller.setTarget(makeMessage([{ type: "text", text: "abcdefghi" }]));
+		vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS);
+		expect(textAt(latestMessage(component), 0)).toBe("abc");
+
+		controller.setTarget(
+			makeMessage([
+				{ type: "text", text: "abcdefghi" },
+				{ type: "toolCall", id: "call-1", name: "read", arguments: { path: "README.md" } },
+			]),
+		);
+		const updates = component.messages.length;
+		vi.advanceTimersByTime(STREAMING_REVEAL_FRAME_MS * 10);
+
+		expect(textAt(latestMessage(component), 0)).toBe("abcdefghi");
+		expect(component.messages).toHaveLength(updates);
+		expect(requestRender).toHaveBeenCalledTimes(1);
+	});
+});

From 3c1a31062ce6a2d747c54617aa82e06c82cd6fcd Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 09:02:04 +0200
Subject: [PATCH 140/181] ux(coding-agent): refined tool renderers with padded
 status headers

- Updated read-group rendering to use the enabled success mark and omitted duplicate success marks on child files in grouped reads.
- Adjusted find and search renderers to apply tool-title coloring, search icons, and padded layout via createCachedComponent.
- Added tests covering read-group success marking and padded find/search renderer output.
---
 packages/coding-agent/CHANGELOG.md            |  4 ++
 .../src/modes/components/read-tool-group.ts   |  6 +--
 packages/coding-agent/src/tools/find.ts       | 38 ++++++++++++++-----
 .../coding-agent/src/tools/render-utils.ts    | 11 ++++--
 packages/coding-agent/src/tools/search.ts     | 26 ++++++++-----
 .../coding-agent/test/read-tool-group.test.ts | 36 ++++++++++++++++++
 .../test/tools/find-renderer.test.ts          | 28 ++++++++++++++
 .../test/tools/search-renderer.test.ts        | 23 +++++++++++
 8 files changed, 146 insertions(+), 26 deletions(-)
 create mode 100644 packages/coding-agent/test/tools/find-renderer.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 2b3f50441..1c72c0d51 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -19,6 +19,8 @@
 
 ### Changed
 
+- Changed grouped `read` output to use a white filled-circle mark for the group/single-read success state and omit duplicate per-file success marks inside multi-read groups.
+
 - Changed assistant streaming output to reveal text incrementally at 30 FPS with grapheme-safe adaptive catch-up, instead of replacing the whole message chunk-by-chunk
 - Changed shimmer-driven TUI animations (working text, pending bash/eval borders, and theme activity-spinner documentation) to render at 30fps instead of 60fps.
 - Changed running `task` tool agent rows to use a static `•` marker and shimmer only the subagent name, leaving descriptions, stats, and nested tool detail text solid while removing the rotating status glyph from those rows.
@@ -44,6 +46,8 @@
 
 ### Fixed
 
+- Fixed inline `find` and `search` result blocks to align with grouped `read` output and render their success headers with the normal tool-title color instead of accent blue.
+
 - Fixed the working-status shimmer to opt into the loader's 30fps animated-message repaint path while keeping both the status spinner and pending bash/eval tool spinners on their normal 80 ms glyph cadence.
 - Fixed consecutive `read` tool calls failing to collapse into a single grouped block when a reasoning model emits one read per completion (`[thinking, read]`). The read group was reset on every assistant `message_start`, so each read rendered as its own one-entry `Read …` line; now a read run accretes across completions and is broken only by a rendered non-empty text/thinking block, a non-read tool, or a user/IRC message — matching the transcript-rebuild path. `ReadToolGroupComponent` now reports its live/finalized state so the growing `Read (N)` header repaints correctly on native-scrollback (risk) terminals.
 - Fixed the `task` tool shared-context brief rendering raw Markdown headings (`# Goal`, `# Constraints`) inside framed call/result blocks instead of using the normal Markdown renderer.
diff --git a/packages/coding-agent/src/modes/components/read-tool-group.ts b/packages/coding-agent/src/modes/components/read-tool-group.ts
index 5952b0b12..1af94f4ba 100644
--- a/packages/coding-agent/src/modes/components/read-tool-group.ts
+++ b/packages/coding-agent/src/modes/components/read-tool-group.ts
@@ -197,9 +197,9 @@ export class ReadToolGroupComponent extends Container implements ToolExecutionHa
 		const total = entriesWithoutPreview.length;
 		for (const [index, entry] of entriesWithoutPreview.entries()) {
 			const connector = index === total - 1 ? theme.tree.last : theme.tree.branch;
-			const statusSymbol = this.#formatStatus(entry.status);
+			const statusPrefix = entry.status === "success" ? "" : `${this.#formatStatus(entry.status)} `;
 			const pathDisplay = this.#formatPath(entry);
-			lines.push(`   ${theme.fg("dim", connector)} ${statusSymbol} ${pathDisplay}`.trimEnd());
+			lines.push(`   ${theme.fg("dim", connector)} ${statusPrefix}${pathDisplay}`.trimEnd());
 		}
 
 		this.#text.setText(lines.join("\n"));
@@ -270,7 +270,7 @@ export class ReadToolGroupComponent extends Container implements ToolExecutionHa
 
 	#formatStatus(status: ReadEntry["status"]): string {
 		if (status === "success") {
-			return theme.fg("success", theme.status.success);
+			return theme.fg("text", theme.status.enabled);
 		}
 		if (status === "warning") {
 			return theme.fg("warning", theme.status.warning);
diff --git a/packages/coding-agent/src/tools/find.ts b/packages/coding-agent/src/tools/find.ts
index 134263d94..8854a297a 100644
--- a/packages/coding-agent/src/tools/find.ts
+++ b/packages/coding-agent/src/tools/find.ts
@@ -428,6 +428,10 @@ function formatFindRenderPaths(paths: FindRenderArgs["paths"]): string | undefin
 
 const COLLAPSED_LIST_LIMIT = PREVIEW_LIMITS.COLLAPSED_ITEMS;
 
+function findStatusIcon(uiTheme: Theme): string {
+	return uiTheme.fg("toolTitle", uiTheme.symbol("icon.search"));
+}
+
 export const findToolRenderer = {
 	inline: true,
 	renderCall(args: FindRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
@@ -435,10 +439,16 @@ export const findToolRenderer = {
 		if (args.limit !== undefined) meta.push(`limit:${args.limit}`);
 
 		const text = renderStatusLine(
-			{ icon: "pending", title: "Find", description: formatFindRenderPaths(args.paths) || "*", meta },
+			{
+				icon: "pending",
+				title: "Find",
+				titleColor: "toolTitle",
+				description: formatFindRenderPaths(args.paths) || "*",
+				meta,
+			},
 			uiTheme,
 		);
-		return new Text(text, 0, 0);
+		return new Text(text, 1, 0);
 	},
 
 	renderResult(
@@ -451,7 +461,7 @@ export const findToolRenderer = {
 
 		if (result.isError || details?.error) {
 			const errorText = details?.error || result.content?.find(c => c.type === "text")?.text || "Unknown error";
-			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
+			return new Text(formatErrorMessage(errorText, uiTheme), 1, 0);
 		}
 
 		const hasDetailedData = details?.fileCount !== undefined;
@@ -464,14 +474,15 @@ export const findToolRenderer = {
 				textContent.includes("No files found") ||
 				textContent.trim() === ""
 			) {
-				return new Text(formatEmptyMessage("No files found", uiTheme), 0, 0);
+				return new Text(formatEmptyMessage("No files found", uiTheme), 1, 0);
 			}
 
 			const lines = textContent.split("\n").filter(l => l.trim());
 			const header = renderStatusLine(
 				{
-					iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")),
+					iconOverride: findStatusIcon(uiTheme),
 					title: "Find",
+					titleColor: "toolTitle",
 					description: formatFindRenderPaths(args?.paths),
 					meta: [formatCount("file", lines.length)],
 				},
@@ -492,6 +503,7 @@ export const findToolRenderer = {
 					);
 					return [header, ...listLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
 				},
+				{ paddingX: 1 },
 			);
 		}
 
@@ -507,22 +519,27 @@ export const findToolRenderer = {
 
 		if (fileCount === 0) {
 			const header = renderStatusLine(
-				{ icon: "warning", title: "Find", description: formatFindRenderPaths(args?.paths), meta: ["0 files"] },
+				{
+					icon: "warning",
+					title: "Find",
+					titleColor: "toolTitle",
+					description: formatFindRenderPaths(args?.paths),
+					meta: ["0 files"],
+				},
 				uiTheme,
 			);
 			const lines = [header, formatEmptyMessage("No files found", uiTheme)];
 			if (missingNote) lines.push(missingNote);
-			return new Text(lines.join("\n"), 0, 0);
+			return new Text(lines.join("\n"), 1, 0);
 		}
 		const meta: string[] = [formatCount("file", fileCount)];
 		if (details?.scopePath) meta.push(`in ${details.scopePath}`);
 		if (truncated) meta.push(uiTheme.fg("warning", "truncated"));
 		const header = renderStatusLine(
 			{
-				...(truncated
-					? { icon: "warning" as const }
-					: { iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")) }),
+				...(truncated ? { icon: "warning" as const } : { iconOverride: findStatusIcon(uiTheme) }),
 				title: "Find",
+				titleColor: "toolTitle",
 				description: formatFindRenderPaths(args?.paths),
 				meta,
 			},
@@ -561,6 +578,7 @@ export const findToolRenderer = {
 				);
 				return [header, ...fileLines, ...extraLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
 			},
+			{ paddingX: 1 },
 		);
 	},
 	mergeCallAndResult: true,
diff --git a/packages/coding-agent/src/tools/render-utils.ts b/packages/coding-agent/src/tools/render-utils.ts
index 3830242d8..7179670c4 100644
--- a/packages/coding-agent/src/tools/render-utils.ts
+++ b/packages/coding-agent/src/tools/render-utils.ts
@@ -753,6 +753,7 @@ export function capParseErrors(
 export function createCachedComponent(
 	getExpanded: () => boolean,
 	compute: (width: number, expanded: boolean) => string[],
+	options: { paddingX?: number } = {},
 ): Component {
 	let cached: { key: bigint; lines: string[] } | undefined;
 	return {
@@ -760,9 +761,13 @@ export function createCachedComponent(
 			const expanded = getExpanded();
 			const key = new Hasher().bool(expanded).u32(width).digest();
 			if (cached?.key === key) return cached.lines;
-			const lines = compute(width, expanded);
-			cached = { key, lines };
-			return lines;
+			const paddingX = Math.max(0, options.paddingX ?? 0);
+			const innerWidth = Math.max(1, width - paddingX * 2);
+			const lines = compute(innerWidth, expanded);
+			const pad = paddingX === 0 ? "" : " ".repeat(paddingX);
+			const paddedLines = paddingX === 0 ? lines : lines.map(line => `${pad}${line}${pad}`);
+			cached = { key, lines: paddedLines };
+			return paddedLines;
 		},
 		invalidate() {
 			cached = undefined;
diff --git a/packages/coding-agent/src/tools/search.ts b/packages/coding-agent/src/tools/search.ts
index 6820901ab..0215ff88f 100644
--- a/packages/coding-agent/src/tools/search.ts
+++ b/packages/coding-agent/src/tools/search.ts
@@ -1332,6 +1332,10 @@ function renderBudgetedSearchGroups(
 	return lines;
 }
 
+function searchStatusIcon(uiTheme: Theme): string {
+	return uiTheme.fg("toolTitle", uiTheme.symbol("icon.search"));
+}
+
 export const searchToolRenderer = {
 	inline: true,
 	renderCall(args: SearchRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
@@ -1343,10 +1347,10 @@ export const searchToolRenderer = {
 		if (args.skip !== undefined && args.skip > 0) meta.push(`skip:${args.skip}`);
 
 		const text = renderStatusLine(
-			{ icon: "pending", title: "Search", description: args.pattern || "?", meta },
+			{ icon: "pending", title: "Search", titleColor: "toolTitle", description: args.pattern || "?", meta },
 			uiTheme,
 		);
-		return new Text(text, 0, 0);
+		return new Text(text, 1, 0);
 	},
 
 	renderResult(
@@ -1359,7 +1363,7 @@ export const searchToolRenderer = {
 
 		if (result.isError || details?.error) {
 			const errorText = details?.error || result.content?.find(c => c.type === "text")?.text || "Unknown error";
-			return new Text(formatErrorMessage(errorText, uiTheme), 0, 0);
+			return new Text(formatErrorMessage(errorText, uiTheme), 1, 0);
 		}
 
 		const hasDetailedData = details?.matchCount !== undefined || details?.fileCount !== undefined;
@@ -1367,14 +1371,15 @@ export const searchToolRenderer = {
 		if (!hasDetailedData) {
 			const textContent = result.details?.displayContent ?? result.content?.find(c => c.type === "text")?.text;
 			if (!textContent || textContent === "No matches found") {
-				return new Text(formatEmptyMessage("No matches found", uiTheme), 0, 0);
+				return new Text(formatEmptyMessage("No matches found", uiTheme), 1, 0);
 			}
 			const lines = textContent.split("\n").filter(line => line.trim() !== "");
 			const description = args?.pattern ?? undefined;
 			const header = renderStatusLine(
 				{
-					iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")),
+					iconOverride: searchStatusIcon(uiTheme),
 					title: "Search",
+					titleColor: "toolTitle",
 					description,
 					meta: [formatCount("item", lines.length)],
 				},
@@ -1396,6 +1401,7 @@ export const searchToolRenderer = {
 					);
 					return [header, ...listLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
 				},
+				{ paddingX: 1 },
 			);
 		}
 
@@ -1416,12 +1422,12 @@ export const searchToolRenderer = {
 			const scopeMeta = searchScopeMeta(details);
 			if (scopeMeta) meta.push(scopeMeta);
 			const header = renderStatusLine(
-				{ icon: "warning", title: "Search", description: args?.pattern, meta },
+				{ icon: "warning", title: "Search", titleColor: "toolTitle", description: args?.pattern, meta },
 				uiTheme,
 			);
 			const lines = [header, formatEmptyMessage("No matches found", uiTheme)];
 			if (missingNote) lines.push(missingNote);
-			return new Text(lines.join("\n"), 0, 0);
+			return new Text(lines.join("\n"), 1, 0);
 		}
 
 		const summaryParts = [formatCount("match", matchCount), formatCount("file", fileCount)];
@@ -1432,10 +1438,9 @@ export const searchToolRenderer = {
 		const description = args?.pattern ?? undefined;
 		const header = renderStatusLine(
 			{
-				...(truncated
-					? { icon: "warning" as const }
-					: { iconOverride: uiTheme.fg("accent", uiTheme.symbol("icon.search")) }),
+				...(truncated ? { icon: "warning" as const } : { iconOverride: searchStatusIcon(uiTheme) }),
 				title: "Search",
+				titleColor: "toolTitle",
 				description,
 				meta,
 			},
@@ -1470,6 +1475,7 @@ export const searchToolRenderer = {
 				const matchLines = renderBudgetedSearchGroups(matchGroups, budget, matchCount, uiTheme, !options.expanded);
 				return [header, ...matchLines, ...extraLines].map(l => truncateToWidth(l, width, Ellipsis.Omit));
 			},
+			{ paddingX: 1 },
 		);
 	},
 	mergeCallAndResult: true,
diff --git a/packages/coding-agent/test/read-tool-group.test.ts b/packages/coding-agent/test/read-tool-group.test.ts
index 38884ccee..2ae827823 100644
--- a/packages/coding-agent/test/read-tool-group.test.ts
+++ b/packages/coding-agent/test/read-tool-group.test.ts
@@ -32,6 +32,42 @@ describe("ReadToolGroupComponent", () => {
 		expect(rendered.toLowerCase()).not.toContain("ctrl+o");
 	});
 
+	it("uses the read-specific success mark for completed reads", () => {
+		const component = new ReadToolGroupComponent();
+		component.updateArgs({ path: "/tmp/example.ts" }, "read-success");
+		component.updateResult(
+			{
+				content: [{ type: "text", text: "line 1" }],
+			},
+			false,
+			"read-success",
+		);
+
+		const rendered = component.render(120).join("\n");
+		const plain = Bun.stripANSI(rendered);
+
+		expect(plain).toContain(themeModule.theme.status.enabled);
+		expect(plain).not.toContain(themeModule.theme.status.success);
+		expect(rendered).toContain(themeModule.theme.fg("text", themeModule.theme.status.enabled));
+		expect(rendered).not.toContain(themeModule.theme.fg("success", themeModule.theme.status.enabled));
+	});
+
+	it("omits duplicate success marks from multi-read child rows", () => {
+		const component = new ReadToolGroupComponent();
+		component.updateArgs({ path: "/tmp/one.ts" }, "read-one");
+		component.updateArgs({ path: "/tmp/two.ts" }, "read-two");
+		component.updateResult({ content: [{ type: "text", text: "one" }] }, false, "read-one");
+		component.updateResult({ content: [{ type: "text", text: "two" }] }, false, "read-two");
+
+		const plain = Bun.stripANSI(component.render(120).join("\n"));
+
+		expect(plain).toContain("Read (2)");
+		expect(plain).toContain(`${themeModule.theme.tree.branch} /tmp/one.ts`);
+		expect(plain).toContain(`${themeModule.theme.tree.last} /tmp/two.ts`);
+		expect(plain).not.toContain(`${themeModule.theme.tree.branch} ${themeModule.theme.status.enabled}`);
+		expect(plain).not.toContain(`${themeModule.theme.tree.last} ${themeModule.theme.status.enabled}`);
+	});
+
 	it("renders warning previews with warning styling instead of success styling", () => {
 		const component = new ReadToolGroupComponent({ showContentPreview: true });
 		component.updateArgs({ path: "/tmp/example.ts" }, "read-1");
diff --git a/packages/coding-agent/test/tools/find-renderer.test.ts b/packages/coding-agent/test/tools/find-renderer.test.ts
new file mode 100644
index 000000000..c0b960b92
--- /dev/null
+++ b/packages/coding-agent/test/tools/find-renderer.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "bun:test";
+import { sanitizeText } from "@oh-my-pi/pi-utils";
+import { getThemeByName } from "../../src/modes/theme/theme";
+import { findToolRenderer } from "../../src/tools/find";
+
+describe("findToolRenderer", () => {
+	it("indents inline find output and avoids accent-colored success headers", async () => {
+		const theme = await getThemeByName("dark");
+		expect(theme).toBeDefined();
+		const uiTheme = theme!;
+		const result = {
+			content: [{ type: "text", text: "" }],
+			details: {
+				fileCount: 2,
+				files: ["src/a.ts", "src/b.ts"],
+			},
+		};
+
+		const renderedLines = findToolRenderer
+			.renderResult(result as never, { expanded: true, isPartial: false }, uiTheme, { paths: "src/**/*.ts" })
+			.render(240);
+		const plainLines = sanitizeText(renderedLines.join("\n")).split("\n");
+
+		expect(plainLines.every(line => line.startsWith(" "))).toBe(true);
+		expect(renderedLines[0]).not.toContain(uiTheme.fg("accent", uiTheme.symbol("icon.search")));
+		expect(renderedLines[0]).not.toContain(uiTheme.fg("accent", "Find"));
+	});
+});
diff --git a/packages/coding-agent/test/tools/search-renderer.test.ts b/packages/coding-agent/test/tools/search-renderer.test.ts
index 13f1c7f32..502de64de 100644
--- a/packages/coding-agent/test/tools/search-renderer.test.ts
+++ b/packages/coding-agent/test/tools/search-renderer.test.ts
@@ -22,6 +22,29 @@ afterAll(() => {
 });
 
 describe("searchToolRenderer", () => {
+	it("indents inline search output and avoids accent-colored success headers", async () => {
+		const theme = await getThemeByName("dark");
+		expect(theme).toBeDefined();
+		const uiTheme = theme!;
+		const result = {
+			content: [{ type: "text", text: "" }],
+			details: {
+				matchCount: 1,
+				fileCount: 1,
+				displayContent: ["# src/", "## file.ts#abcd", "*12│const needle = true;"].join("\n"),
+			},
+		};
+
+		const renderedLines = searchToolRenderer
+			.renderResult(result as never, { expanded: true, isPartial: false }, uiTheme, { pattern: "needle" })
+			.render(240);
+		const plainLines = sanitizeText(renderedLines.join("\n")).split("\n");
+
+		expect(plainLines.every(line => line.startsWith(" "))).toBe(true);
+		expect(renderedLines[0]).not.toContain(uiTheme.fg("accent", uiTheme.symbol("icon.search")));
+		expect(renderedLines[0]).not.toContain(uiTheme.fg("accent", "Search"));
+	});
+
 	it("keeps truncation status in the header without a bottom notice", async () => {
 		const theme = await getThemeByName("dark");
 		expect(theme).toBeDefined();

From 5c60772f386b9f266f0f76c6d85a89b860a11d16 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 09:12:12 +0200
Subject: [PATCH 141/181] ux(coding-agent/tools): folded raw output artifact
 notices into the bash status footer

- Added a `showHeader` option to shell rendering and suppressed the bash frame title bar by default.
- Parsed trailing raw-output artifact notices and folded their IDs into status footer metadata instead of command output.
---
 packages/coding-agent/CHANGELOG.md            |  2 +
 packages/coding-agent/src/tools/bash.ts       | 50 +++++++++++++++++--
 .../event-controller-tool-render-mode.test.ts |  1 +
 .../test/tools/bash-sixel-render.test.ts      | 29 +++++++++--
 4 files changed, 74 insertions(+), 8 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 1c72c0d51..44ba07e69 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -19,6 +19,8 @@
 
 ### Changed
 
+- Changed the bash tool frame to use a plain top rule instead of repeating "Bash" in the title bar, and folded minimizer raw-output artifact links into the status footer as `Artifact: <id>`.
+
 - Changed grouped `read` output to use a white filled-circle mark for the group/single-read success state and omit duplicate per-file success marks inside multi-read groups.
 
 - Changed assistant streaming output to reveal text incrementally at 30 FPS with grapheme-safe adaptive catch-up, instead of replacing the whole message chunk-by-chunk
diff --git a/packages/coding-agent/src/tools/bash.ts b/packages/coding-agent/src/tools/bash.ts
index 36c03155c..0238695a8 100644
--- a/packages/coding-agent/src/tools/bash.ts
+++ b/packages/coding-agent/src/tools/bash.ts
@@ -287,6 +287,35 @@ function formatExitCodeNotice(exitCode: number): string {
 	return `Command exited with code ${exitCode}`;
 }
 
+const RAW_OUTPUT_ARTIFACT_PREFIX = "[raw output: artifact://";
+const RAW_OUTPUT_ARTIFACT_SUFFIX = "]";
+
+function stripRawOutputArtifactNotice(text: string): { text: string; artifactId?: string } {
+	const trimmed = text.trimEnd();
+	const lineStart = trimmed.lastIndexOf("\n");
+	const candidateStart = lineStart === -1 ? 0 : lineStart + 1;
+	if (
+		!trimmed.startsWith(RAW_OUTPUT_ARTIFACT_PREFIX, candidateStart) ||
+		!trimmed.endsWith(RAW_OUTPUT_ARTIFACT_SUFFIX)
+	) {
+		return { text };
+	}
+
+	const idStart = candidateStart + RAW_OUTPUT_ARTIFACT_PREFIX.length;
+	const idEnd = trimmed.length - RAW_OUTPUT_ARTIFACT_SUFFIX.length;
+	if (idStart === idEnd) return { text };
+	for (let i = idStart; i < idEnd; i++) {
+		const code = trimmed.charCodeAt(i);
+		if (code < 48 || code > 57) return { text };
+	}
+
+	const artifactId = trimmed.slice(idStart, idEnd);
+	return {
+		text: trimmed.slice(0, lineStart === -1 ? 0 : lineStart).trimEnd(),
+		artifactId,
+	};
+}
+
 /**
  * Strip the trailing occurrence of `notice` (plus a single surrounding newline
  * on each side) so the TUI can echo the value via a styled footer label
@@ -1028,6 +1057,7 @@ export interface ShellRendererConfig<TArgs> {
 	resolveCommand?: (args: TArgs | undefined) => string | undefined;
 	resolveCwd?: (args: TArgs | undefined) => string | undefined;
 	resolveEnv?: (args: TArgs | undefined) => Record<string, string> | undefined;
+	showHeader?: boolean;
 }
 
 function getPartialJson<TArgs>(args: TArgs | undefined): string | undefined {
@@ -1079,9 +1109,11 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 	return {
 		renderCall(args: TArgs, options: RenderResultOptions, uiTheme: Theme): Component {
 			const renderArgs = toBashRenderArgs(args, config);
-			const title = config.resolveTitle(args, options);
 			const cmdLines = formatBashCommandLines(renderArgs, uiTheme);
-			const header = renderStatusLine({ icon: "pending", title }, uiTheme);
+			const header =
+				config.showHeader === false
+					? undefined
+					: renderStatusLine({ icon: "pending", title: config.resolveTitle(args, options) }, uiTheme);
 			const outputBlock = new CachedOutputBlock();
 			return markFramedBlockComponent({
 				render: (width: number): string[] =>
@@ -1115,8 +1147,10 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 			const cmdLines = args ? formatBashCommandLines(renderArgs, uiTheme) : undefined;
 			const isError = result.isError === true;
 			const icon = options.isPartial ? "pending" : isError ? "error" : "success";
-			const title = config.resolveTitle(args, options);
-			const header = renderStatusLine({ icon, title }, uiTheme);
+			const header =
+				config.showHeader === false
+					? undefined
+					: renderStatusLine({ icon, title: config.resolveTitle(args, options) }, uiTheme);
 			const details = result.details;
 			const outputBlock = new CachedOutputBlock();
 
@@ -1133,7 +1167,9 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					const rawOutput = renderContext?.output ?? result.content?.find(c => c.type === "text")?.text ?? "";
 					const strippedOutput = stripOutputNotice(rawOutput, details?.meta);
 					const withoutExit = stripExitCodeNotice(strippedOutput, details?.exitCode);
-					const output = stripWallTimeNotice(withoutExit, details?.wallTimeMs);
+					const withoutWall = stripWallTimeNotice(withoutExit, details?.wallTimeMs);
+					const rawOutputArtifact = stripRawOutputArtifactNotice(withoutWall);
+					const output = rawOutputArtifact.text;
 					const displayOutput = output.trimEnd();
 					const showingFullOutput = expanded && renderContext?.isFullOutput === true;
 
@@ -1152,6 +1188,9 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 								: `Timeout: ${timeoutSeconds}s`,
 						);
 					}
+					if (rawOutputArtifact.artifactId) {
+						statsParts.push(`Artifact: ${rawOutputArtifact.artifactId}`);
+					}
 					if (isError && typeof details?.exitCode === "number") {
 						statsParts.push(`Exit: ${details.exitCode}`);
 					}
@@ -1239,4 +1278,5 @@ export const bashToolRenderer = createShellRenderer<BashRenderArgs>({
 	resolveCommand: args => args?.command,
 	resolveCwd: args => args?.cwd,
 	resolveEnv: args => args?.env,
+	showHeader: false,
 });
diff --git a/packages/coding-agent/test/modes/controllers/event-controller-tool-render-mode.test.ts b/packages/coding-agent/test/modes/controllers/event-controller-tool-render-mode.test.ts
index ec9e0d444..c63eb3d82 100644
--- a/packages/coding-agent/test/modes/controllers/event-controller-tool-render-mode.test.ts
+++ b/packages/coding-agent/test/modes/controllers/event-controller-tool-render-mode.test.ts
@@ -11,6 +11,7 @@ function createContext() {
 	const chatContainer = { addChild: vi.fn(), removeChild: vi.fn() };
 	const ctx = {
 		isInitialized: true,
+		settings: { get: () => false },
 		statusLine: { invalidate: vi.fn() },
 		updateEditorTopBorder: vi.fn(),
 		pendingTools,
diff --git a/packages/coding-agent/test/tools/bash-sixel-render.test.ts b/packages/coding-agent/test/tools/bash-sixel-render.test.ts
index 5e0f60a13..28db6c233 100644
--- a/packages/coding-agent/test/tools/bash-sixel-render.test.ts
+++ b/packages/coding-agent/test/tools/bash-sixel-render.test.ts
@@ -83,9 +83,9 @@ describe("bashToolRenderer", () => {
 		expect(lines.length).toBeGreaterThanOrEqual(3);
 		const header = lines[0]!;
 		const body = lines.slice(1, -1).join("\n");
-		// The header carries the title only; the command lives inside the framed body
-		// (not inline on the status line as the old one-liner preview rendered it).
-		expect(header).toContain("Bash");
+		// Bash commands already carry a `$` prompt in the body, so the frame header
+		// stays a plain rule instead of repeating "Bash" in the title bar.
+		expect(header).not.toContain("Bash");
 		expect(header).not.toContain("sleep 30");
 		expect(body).toContain("$ sleep 30");
 	});
@@ -126,6 +126,29 @@ describe("bashToolRenderer", () => {
 		// only place wall time is shown so users don't read it twice.
 		expect(rendered).not.toContain("Wall time: 1.23 seconds");
 	});
+
+	it("folds raw output artifact notices into the status footer", async () => {
+		const theme = await getThemeByName("dark");
+		expect(theme).toBeDefined();
+		const uiTheme = theme!;
+		const component = bashToolRenderer.renderResult(
+			{
+				content: [{ type: "text", text: "filtered\n[raw output: artifact://13]\n\nWall time: 0.08 seconds" }],
+				details: { timeoutSeconds: 300, wallTimeMs: 80 },
+				isError: false,
+			},
+			{ expanded: false, isPartial: false },
+			uiTheme,
+			{ command: "bun run check:types" },
+		);
+		const rendered = sanitizeText(component.render(120).join("\n"));
+		expect(rendered).toContain("filtered");
+		expect(rendered).toContain("Wall: 0.08s");
+		expect(rendered).toContain("Timeout: 300s");
+		expect(rendered).toContain("Artifact: 13");
+		expect(rendered).not.toContain("[raw output: artifact://13]");
+		expect(rendered).not.toContain("artifact://13");
+	});
 	it("renders the exit status in the footer and strips the textual exit notice for failed commands", async () => {
 		const theme = await getThemeByName("dark");
 		expect(theme).toBeDefined();

From 493c67aa6aa713142ac9fbd0322d54a898365f24 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 09:15:36 +0200
Subject: [PATCH 142/181] test(tui): adjusted TUI test timings for consistent
 render-throttle flushes

- Increased `Bun.sleep` delays in TUI tests from short frame intervals to 40ms.
- Adjusted mocked `performance.now` tick advances from 20ms to 40ms so render throttling sees full frame gaps.
- Modified the streaming scrollback settle helper to yield a `nextTick` before sleeping, then flush.
---
 packages/tui/test/deccara-grid-parity.test.ts | 470 ------------------
 packages/tui/test/image-budget.test.ts        |   6 +-
 packages/tui/test/overlay-scroll.test.ts      |   2 +-
 .../test/streaming-scrollback-defer.test.ts   |   5 +-
 4 files changed, 9 insertions(+), 474 deletions(-)
 delete mode 100644 packages/tui/test/deccara-grid-parity.test.ts

diff --git a/packages/tui/test/deccara-grid-parity.test.ts b/packages/tui/test/deccara-grid-parity.test.ts
deleted file mode 100644
index 9eb7ca28b..000000000
--- a/packages/tui/test/deccara-grid-parity.test.ts
+++ /dev/null
@@ -1,470 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
-import { performance } from "node:perf_hooks";
-import { applyBackgroundToLine, type Component, setTerminalDeccara, TERMINAL, TUI } from "@oh-my-pi/pi-tui";
-import { VirtualTerminal } from "./virtual-terminal";
-
-const BG_OPEN = "\x1b[48;2;10;20;30m";
-
-class PanelComponent implements Component {
-	#rows: string[];
-	#bg: boolean[];
-	constructor(rows: string[], bg: boolean[]) {
-		this.#rows = [...rows];
-		this.#bg = [...bg];
-	}
-	set(rows: string[], bg: boolean[]): void {
-		this.#rows = [...rows];
-		this.#bg = [...bg];
-	}
-	invalidate(): void {}
-	render(width: number): string[] {
-		return this.#rows.map((row, i) =>
-			this.#bg[i] ? applyBackgroundToLine(row, width, t => `${BG_OPEN}${t}\x1b[49m`) : row,
-		);
-	}
-}
-
-async function settle(term: VirtualTerminal): Promise<void> {
-	const t = Promise.withResolvers<void>();
-	process.nextTick(t.resolve);
-	await t.promise;
-	await Bun.sleep(1);
-	await term.flush();
-}
-
-// ---- Minimal DECCARA-aware grid simulator -------------------------------
-// Tracks per-cell background only (the optimizer's whole job). Background is a
-// normalized SGR param string, or "" for default. Implements the escape subset
-// the renderer emits, including DECSACE rect-mode + DECCARA $r rectangle fills,
-// with background-color-erase (bce) semantics on ED/EL/scroll.
-function normBg(prev: string, params: string): string {
-	if (params.length === 0) return "";
-	const t = params.split(";");
-	let r = prev;
-	for (let i = 0; i < t.length; i++) {
-		const n = t[i].length === 0 ? 0 : Number(t[i]);
-		if (!Number.isInteger(n)) return r; // ignore unknowns
-		if (n === 0 || n === 49) r = "";
-		else if ((n >= 40 && n <= 47) || (n >= 100 && n <= 107)) r = t[i];
-		else if (n === 48) {
-			if (t[i + 1] === "5") {
-				r = `48;5;${t[i + 2]}`;
-				i += 2;
-			} else if (t[i + 1] === "2") {
-				r = `48;2;${t[i + 2]};${t[i + 3]};${t[i + 4]}`;
-				i += 4;
-			}
-		} else if (n === 38) {
-			if (t[i + 1] === "5") i += 2;
-			else if (t[i + 1] === "2") i += 4;
-		}
-	}
-	return r;
-}
-
-class Grid {
-	w: number;
-	h: number;
-	bg: string[][];
-	row = 0;
-	col = 0;
-	curBg = "";
-	wrapPending = false;
-	constructor(w: number, h: number) {
-		this.w = w;
-		this.h = h;
-		this.bg = Array.from({ length: h }, () => new Array(w).fill(""));
-	}
-	#scrollUp(): void {
-		this.bg.shift();
-		this.bg.push(new Array(this.w).fill(this.curBg));
-	}
-	#nl(): void {
-		this.wrapPending = false;
-		if (this.row >= this.h - 1) this.#scrollUp();
-		else this.row++;
-	}
-	#put(): void {
-		if (this.wrapPending) {
-			this.col = 0;
-			this.#nl();
-		}
-		if (this.col < this.w) this.bg[this.row][this.col] = this.curBg;
-		if (this.col >= this.w - 1) this.wrapPending = true;
-		else this.col++;
-	}
-	#erase(r: number, c0: number, c1: number): void {
-		for (let c = c0; c <= c1 && c < this.w; c++) this.bg[r][c] = this.curBg;
-	}
-	write(s: string): void {
-		let i = 0;
-		while (i < s.length) {
-			const code = s.charCodeAt(i);
-			if (code === 0x1b) {
-				const n = s[i + 1];
-				if (n === "[") {
-					let j = i + 2;
-					while (j < s.length && !(s.charCodeAt(j) >= 0x40 && s.charCodeAt(j) <= 0x7e)) j++;
-					const fin = s[j];
-					// Strip trailing intermediates (0x20-0x2f), e.g. '$' in DECCARA ($r)
-					// and '*' in DECSACE (*x), so the param list is clean.
-					let bodyEnd = j;
-					while (bodyEnd > i + 2 && s.charCodeAt(bodyEnd - 1) >= 0x20 && s.charCodeAt(bodyEnd - 1) <= 0x2f)
-						bodyEnd--;
-					const inter = s.slice(bodyEnd, j);
-					const body = s.slice(i + 2, bodyEnd);
-					this.#csi(body, inter + fin);
-					i = j + 1;
-					continue;
-				}
-				if (n === "]") {
-					// OSC ... BEL or ST
-					let j = i + 2;
-					while (j < s.length && s.charCodeAt(j) !== 0x07 && !(s[j] === "\x1b" && s[j + 1] === "\\")) j++;
-					i = s.charCodeAt(j) === 0x07 ? j + 1 : j + 2;
-					continue;
-				}
-				if (n === "P" || n === "X" || n === "^" || n === "_") {
-					let j = i + 2;
-					while (j < s.length && !(s[j] === "\x1b" && s[j + 1] === "\\")) j++;
-					i = j + 2;
-					continue;
-				}
-				i += 2;
-				continue;
-			}
-			if (code === 0x0d) {
-				this.col = 0;
-				this.wrapPending = false;
-				i++;
-				continue;
-			}
-			if (code === 0x0a) {
-				this.#nl();
-				i++;
-				continue;
-			}
-			// printable
-			this.#put();
-			i++;
-		}
-	}
-	#csi(body: string, fin: string): void {
-		const ps = body.startsWith("?") ? body.slice(1) : body;
-		const args = ps.split(";");
-		const a0 = args[0]?.length ? Number(args[0]) : undefined;
-		switch (fin) {
-			case "m":
-				this.curBg = normBg(this.curBg, body);
-				return;
-			case "H":
-			case "f": {
-				const r = (args[0]?.length ? Number(args[0]) : 1) - 1;
-				const c = (args[1]?.length ? Number(args[1]) : 1) - 1;
-				this.row = Math.max(0, Math.min(this.h - 1, r));
-				this.col = Math.max(0, Math.min(this.w - 1, c));
-				this.wrapPending = false;
-				return;
-			}
-			case "A":
-				this.row = Math.max(0, this.row - (a0 ?? 1));
-				this.wrapPending = false;
-				return;
-			case "B":
-				this.row = Math.min(this.h - 1, this.row + (a0 ?? 1));
-				this.wrapPending = false;
-				return;
-			case "C":
-				this.col = Math.min(this.w - 1, this.col + (a0 ?? 1));
-				this.wrapPending = false;
-				return;
-			case "D":
-				this.col = Math.max(0, this.col - (a0 ?? 1));
-				this.wrapPending = false;
-				return;
-			case "G":
-				this.col = Math.max(0, Math.min(this.w - 1, (a0 ?? 1) - 1));
-				this.wrapPending = false;
-				return;
-			case "K": {
-				const mode = a0 ?? 0;
-				if (mode === 0) this.#erase(this.row, this.col, this.w - 1);
-				else if (mode === 1) this.#erase(this.row, 0, this.col);
-				else this.#erase(this.row, 0, this.w - 1);
-				return;
-			}
-			case "J": {
-				const mode = a0 ?? 0;
-				if (mode === 2 || mode === 3 || mode === 22) {
-					for (let r = 0; r < this.h; r++) this.#erase(r, 0, this.w - 1);
-				} else if (mode === 0) {
-					this.#erase(this.row, this.col, this.w - 1);
-					for (let r = this.row + 1; r < this.h; r++) this.#erase(r, 0, this.w - 1);
-				} else if (mode === 1) {
-					for (let r = 0; r < this.row; r++) this.#erase(r, 0, this.w - 1);
-					this.#erase(this.row, 0, this.col);
-				}
-				return;
-			}
-			case "*x":
-				return; // DECSACE extent: renderer always wraps $r in rect mode
-			case "$r": {
-				// DECCARA: Pt;Pl;Pb;Pr; <sgr...>
-				const top = (args[0]?.length ? Number(args[0]) : 1) - 1;
-				const left = (args[1]?.length ? Number(args[1]) : 1) - 1;
-				const bot = (args[2]?.length ? Number(args[2]) : this.h) - 1;
-				const right = (args[3]?.length ? Number(args[3]) : this.w) - 1;
-				const sgr = args.slice(4).join(";");
-				for (let r = Math.max(0, top); r <= Math.min(this.h - 1, bot); r++) {
-					for (let c = Math.max(0, left); c <= Math.min(this.w - 1, right); c++) {
-						this.bg[r][c] = normBg(this.bg[r][c], sgr);
-					}
-				}
-				return;
-			}
-			default:
-				return; // ignore h/l/t/etc.
-		}
-	}
-	dump(): string {
-		return this.bg.map(r => r.map(c => (c === "" ? "." : "#")).join("")).join("\n");
-	}
-}
-
-function captureBytes(term: VirtualTerminal): string[] {
-	const writes: string[] = [];
-	const real = term.write.bind(term);
-	vi.spyOn(term, "write").mockImplementation((d: string) => {
-		writes.push(d);
-		real(d);
-	});
-	return writes;
-}
-
-describe("DECCARA visible-fill parity (simulated grid)", () => {
-	beforeEach(() => {
-		let m = 0;
-		vi.spyOn(performance, "now").mockImplementation(() => {
-			m += 20;
-			return m;
-		});
-	});
-	afterEach(() => {
-		vi.restoreAllMocks();
-	});
-
-	async function runScenario(
-		deccara: boolean,
-		w: number,
-		h: number,
-		frames: { rows: string[]; bg: boolean[] }[],
-	): Promise<Grid> {
-		const saved = TERMINAL.deccara;
-		setTerminalDeccara(deccara);
-		const term = new VirtualTerminal(w, h);
-		const tui = new TUI(term);
-		const panel = new PanelComponent(frames[0].rows, frames[0].bg);
-		tui.addChild(panel);
-		const grid = new Grid(w, h);
-		const bytes = captureBytes(term);
-		try {
-			tui.start();
-			await settle(term);
-			for (let f = 1; f < frames.length; f++) {
-				panel.set(frames[f].rows, frames[f].bg);
-				tui.requestRender();
-				await settle(term);
-			}
-			for (const b of bytes) grid.write(b);
-			return grid;
-		} finally {
-			tui.stop();
-			setTerminalDeccara(saved);
-		}
-	}
-
-	const scenarios: { name: string; w: number; h: number; frames: { rows: string[]; bg: boolean[] }[] }[] = [
-		{
-			// Regression: a diff that grows the buffer past the viewport scrolls the
-			// terminal, so the rewritten rows settle one row higher than where they
-			// were first painted. The absolute DECCARA rectangles must follow the
-			// post-scroll rows (and the row scrolled into history must keep its full
-			// background padding). Pre-fix, the bg fills landed one row too low.
-			name: "diff grows past viewport, scrolling a bg fill row (regression)",
-			w: 20,
-			h: 4,
-			frames: [
-				{ rows: ["x", "y"], bg: [false, false] },
-				{ rows: ["X", "y", "z", "", ""], bg: [false, false, false, true, true] },
-			],
-		},
-		{
-			name: "short content + 2-row input box, then spinner diff",
-			w: 40,
-			h: 12,
-			frames: [
-				{
-					rows: ["Hi! What can I help you with today?", "", "can you ping google", "", "", "", "Working"],
-					bg: [false, false, false, false, true, true, false],
-				},
-				{
-					rows: ["Hi! What can I help you with today?", "", "can you ping google", "", "", "", "Working."],
-					bg: [false, false, false, false, true, true, false],
-				},
-			],
-		},
-		{
-			name: "blank panel filling viewport",
-			w: 40,
-			h: 8,
-			frames: [{ rows: ["", "", "", ""], bg: [true, true, true, true] }],
-		},
-		{
-			name: "content taller than viewport (scroll)",
-			w: 40,
-			h: 8,
-			frames: [
-				{
-					rows: Array.from({ length: 12 }, (_, i) => (i % 2 === 0 ? "" : `line ${i}`)),
-					bg: Array.from({ length: 12 }, () => true),
-				},
-			],
-		},
-		{
-			name: "in-place single-row change among bg rows",
-			w: 40,
-			h: 8,
-			frames: [
-				{ rows: ["AAA", "BBB", "CCC", "DDD"], bg: [true, true, true, true] },
-				{ rows: ["AAA", "BBB", "XXX", "DDD"], bg: [true, true, true, true] },
-			],
-		},
-		{
-			name: "streaming insert above input box (content < height)",
-			w: 40,
-			h: 14,
-			frames: [
-				{
-					rows: ["msg one", "", "can you ping google", "", "", "", "Working"],
-					bg: [false, false, false, false, true, true, false],
-				},
-				{
-					rows: ["msg one", "", "can you ping google", "", "Pinging", "", "", "", "Working"],
-					bg: [false, false, false, false, false, false, true, true, false],
-				},
-				{
-					rows: ["msg one", "", "can you ping google", "", "Pinging google", "now", "", "", "", "Working."],
-					bg: [false, false, false, false, false, false, false, true, true, false],
-				},
-				{
-					rows: ["msg one", "", "can you ping google", "", "Pinging google", "now done", "", "", "", "Working.."],
-					bg: [false, false, false, false, false, false, false, true, true, false],
-				},
-			],
-		},
-		{
-			name: "streaming insert above input box (content > height, scroll)",
-			w: 40,
-			h: 8,
-			frames: [
-				{ rows: ["a", "b", "c", "d", "", "", "stat"], bg: [false, false, false, false, true, true, false] },
-				{
-					rows: ["a", "b", "c", "d", "e", "", "", "stat"],
-					bg: [false, false, false, false, false, true, true, false],
-				},
-				{
-					rows: ["a", "b", "c", "d", "e", "f", "", "", "stat"],
-					bg: [false, false, false, false, false, false, true, true, false],
-				},
-				{
-					rows: ["a", "b", "c", "d", "e", "f", "g", "", "", "stat"],
-					bg: [false, false, false, false, false, false, false, true, true, false],
-				},
-			],
-		},
-		{
-			name: "full-viewport frame, in-place multi-row diff incl bg box",
-			w: 40,
-			h: 6,
-			frames: [
-				{ rows: ["top", "mid", "", "", "stat"], bg: [false, false, true, true, false] },
-				{ rows: ["top", "CHANGED", "", "", "stat2"], bg: [false, false, true, true, false] },
-			],
-		},
-		{
-			name: "shrink frame: assistant block collapses",
-			w: 40,
-			h: 12,
-			frames: [
-				{
-					rows: ["q", "", "aaaa", "bbbb", "cccc", "", "", "stat"],
-					bg: [false, false, false, false, false, true, true, false],
-				},
-				{ rows: ["q", "", "done", "", "", "stat"], bg: [false, false, false, true, true, false] },
-			],
-		},
-	];
-
-	for (const sc of scenarios) {
-		it(`matches padded fallback: ${sc.name}`, async () => {
-			const off = await runScenario(false, sc.w, sc.h, sc.frames);
-			const on = await runScenario(true, sc.w, sc.h, sc.frames);
-			if (off.dump() !== on.dump()) {
-				const offL = off.dump().split("\n");
-				const onL = on.dump().split("\n");
-				const diff = offL
-					.map((l, i) => (l === onL[i] ? null : `row ${i}:\n  off ${l}\n  on  ${onL[i]}`))
-					.filter(Boolean)
-					.join("\n");
-				throw new Error(`bg grid diverged for "${sc.name}":\n${diff}`);
-			}
-			expect(on.dump()).toBe(off.dump());
-		});
-	}
-
-	it("fuzz: random multi-frame sequences match the padded fallback", async () => {
-		const words = ["", "", "ok", "ping", "google", "running cmd", "x", "hello world here", "a longer content line"];
-		const failures: string[] = [];
-		let totalTrials = 0;
-		for (const startSeed of [0x12345678, 0x0badf00d, 0x7fffff00]) {
-			// Deterministic LCG so a failure is reproducible from the seed.
-			let seed = startSeed;
-			const rnd = () => {
-				seed = (seed * 1103515245 + 12345) & 0x7fffffff;
-				return seed / 0x7fffffff;
-			};
-			const pick = <T>(arr: T[]): T => arr[Math.floor(rnd() * arr.length)];
-			const makeFrame = (w: number) => {
-				const n = 1 + Math.floor(rnd() * 16);
-				const rows: string[] = [];
-				const bg: boolean[] = [];
-				for (let i = 0; i < n; i++) {
-					let r = pick(words);
-					if (r.length > w) r = r.slice(0, w);
-					rows.push(r);
-					bg.push(rnd() < 0.5);
-				}
-				return { rows, bg };
-			};
-			for (let trial = 0; trial < 100; trial++) {
-				totalTrials++;
-				const w = 16 + Math.floor(rnd() * 40);
-				const h = 3 + Math.floor(rnd() * 12);
-				const frameCount = 1 + Math.floor(rnd() * 6);
-				const frames = Array.from({ length: frameCount }, () => makeFrame(w));
-				const off = await runScenario(false, w, h, frames);
-				const on = await runScenario(true, w, h, frames);
-				if (off.dump() !== on.dump()) {
-					failures.push(
-						`seed ${startSeed.toString(16)} trial ${trial} (w=${w},h=${h}):\n${JSON.stringify(frames)}\n--- off\n${off.dump()}\n--- on\n${on.dump()}`,
-					);
-					if (failures.length >= 3) break;
-				}
-			}
-			if (failures.length >= 3) break;
-		}
-		if (failures.length > 0) {
-			throw new Error(`DECCARA fuzz divergences (${totalTrials} trials):\n${failures.join("\n\n")}`);
-		}
-	}, 60000);
-});
diff --git a/packages/tui/test/image-budget.test.ts b/packages/tui/test/image-budget.test.ts
index 608f9d6a4..57504afd6 100644
--- a/packages/tui/test/image-budget.test.ts
+++ b/packages/tui/test/image-budget.test.ts
@@ -331,8 +331,10 @@ describe("TUI inline-image budget", () => {
 		setCellDimensions({ widthPx: 10, heightPx: 10 });
 		terminal.imageProtocol = ImageProtocol.Kitty;
 		monotonicNow = 0;
+		// Advance one full 30fps frame (>1000/30ms) per tick so the render
+		// throttle computes a zero delay and every requestRender flushes inline.
 		vi.spyOn(performance, "now").mockImplementation(() => {
-			monotonicNow += 20;
+			monotonicNow += 40;
 			return monotonicNow;
 		});
 	});
@@ -348,7 +350,7 @@ describe("TUI inline-image budget", () => {
 			const tick = Promise.withResolvers<void>();
 			process.nextTick(tick.resolve);
 			await tick.promise;
-			await Bun.sleep(1);
+			await Bun.sleep(40);
 			await term.flush();
 		}
 	}
diff --git a/packages/tui/test/overlay-scroll.test.ts b/packages/tui/test/overlay-scroll.test.ts
index 0f362f58d..af85a123e 100644
--- a/packages/tui/test/overlay-scroll.test.ts
+++ b/packages/tui/test/overlay-scroll.test.ts
@@ -106,7 +106,7 @@ async function withEnv(name: string, value: string, run: () => Promise<void>): P
 
 async function flushRender(term: VirtualTerminal): Promise<void> {
 	await new Promise<void>(resolve => process.nextTick(resolve));
-	await Bun.sleep(17);
+	await Bun.sleep(40);
 	await term.flush();
 }
 
diff --git a/packages/tui/test/streaming-scrollback-defer.test.ts b/packages/tui/test/streaming-scrollback-defer.test.ts
index 18e74269b..e1723c57d 100644
--- a/packages/tui/test/streaming-scrollback-defer.test.ts
+++ b/packages/tui/test/streaming-scrollback-defer.test.ts
@@ -39,7 +39,10 @@ class AppendOnlyLiveLineList extends LiveLineList {
 }
 
 async function settle(term: VirtualTerminal): Promise<void> {
-	await Bun.sleep(20);
+	const nextTick = Promise.withResolvers<void>();
+	process.nextTick(nextTick.resolve);
+	await nextTick.promise;
+	await Bun.sleep(40);
 	await term.flush();
 }
 

From 84573a0d1a66f536518e37bd41413557aeae75a4 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 09:18:25 +0200
Subject: [PATCH 143/181] chore: bump version to 15.10.1

---
 Cargo.lock                            |  8 ++---
 Cargo.toml                            |  2 +-
 bun.lock                              | 46 ++++++++++++---------------
 crates/pi-natives/src/lib.rs          |  2 +-
 package.json                          | 18 +++++------
 packages/agent/CHANGELOG.md           |  2 ++
 packages/agent/package.json           |  2 +-
 packages/ai/CHANGELOG.md              |  2 ++
 packages/ai/package.json              |  2 +-
 packages/coding-agent/CHANGELOG.md    |  2 ++
 packages/coding-agent/package.json    |  2 +-
 packages/hashline/package.json        |  2 +-
 packages/mnemopi/package.json         |  2 +-
 packages/natives/CHANGELOG.md         |  2 ++
 packages/natives/native/index.d.ts    |  2 +-
 packages/natives/native/index.js      |  2 +-
 packages/natives/package.json         |  2 +-
 packages/stats/package.json           |  2 +-
 packages/swarm-extension/package.json |  2 +-
 packages/tui/CHANGELOG.md             |  2 ++
 packages/tui/package.json             |  2 +-
 packages/utils/package.json           |  2 +-
 22 files changed, 58 insertions(+), 52 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index dd2b7e74c..a2f4c89f2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2331,7 +2331,7 @@ dependencies = [
 
 [[package]]
 name = "pi-ast"
-version = "15.10.0"
+version = "15.10.1"
 dependencies = [
  "anyhow",
  "ast-grep-core",
@@ -2399,7 +2399,7 @@ dependencies = [
 
 [[package]]
 name = "pi-iso"
-version = "15.10.0"
+version = "15.10.1"
 dependencies = [
  "async-trait",
  "libc",
@@ -2411,7 +2411,7 @@ dependencies = [
 
 [[package]]
 name = "pi-natives"
-version = "15.10.0"
+version = "15.10.1"
 dependencies = [
  "anyhow",
  "arboard",
@@ -2457,7 +2457,7 @@ dependencies = [
 
 [[package]]
 name = "pi-shell"
-version = "15.10.0"
+version = "15.10.1"
 dependencies = [
  "anyhow",
  "brush-builtins",
diff --git a/Cargo.toml b/Cargo.toml
index 816514245..f6301942c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ exclude = ["crates/brush-core-vendored", "crates/brush-builtins-vendored"]
 resolver = "3"
 
 [workspace.package]
-version = "15.10.0"
+version = "15.10.1"
 edition = "2024"
 license = "MIT"
 authors = ["Can Boluk"]
diff --git a/bun.lock b/bun.lock
index 95153a04e..3cff53436 100644
--- a/bun.lock
+++ b/bun.lock
@@ -15,7 +15,7 @@
     },
     "packages/agent": {
       "name": "@oh-my-pi/pi-agent-core",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "dependencies": {
         "@oh-my-pi/pi-ai": "catalog:",
         "@oh-my-pi/pi-natives": "catalog:",
@@ -30,7 +30,7 @@
     },
     "packages/ai": {
       "name": "@oh-my-pi/pi-ai",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "dependencies": {
         "@bufbuild/protobuf": "catalog:",
         "@oh-my-pi/pi-utils": "catalog:",
@@ -44,7 +44,7 @@
     },
     "packages/coding-agent": {
       "name": "@oh-my-pi/pi-coding-agent",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "bin": {
         "omp": "src/cli.ts",
       },
@@ -90,7 +90,7 @@
     },
     "packages/hashline": {
       "name": "@oh-my-pi/hashline",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "dependencies": {
         "diff": "catalog:",
         "lru-cache": "catalog:",
@@ -101,7 +101,7 @@
     },
     "packages/mnemopi": {
       "name": "@oh-my-pi/pi-mnemopi",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "bin": {
         "mnemopi": "src/cli.ts",
       },
@@ -118,7 +118,7 @@
     },
     "packages/natives": {
       "name": "@oh-my-pi/pi-natives",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "devDependencies": {
         "@napi-rs/cli": "catalog:",
         "@types/bun": "catalog:",
@@ -126,7 +126,7 @@
     },
     "packages/stats": {
       "name": "@oh-my-pi/omp-stats",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "bin": {
         "omp-stats": "./src/index.ts",
       },
@@ -151,7 +151,7 @@
     },
     "packages/swarm-extension": {
       "name": "@oh-my-pi/swarm-extension",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "bin": {
         "omp-swarm": "src/cli.ts",
       },
@@ -167,7 +167,7 @@
     },
     "packages/tui": {
       "name": "@oh-my-pi/pi-tui",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "dependencies": {
         "@oh-my-pi/pi-natives": "catalog:",
         "@oh-my-pi/pi-utils": "catalog:",
@@ -208,7 +208,7 @@
     },
     "packages/utils": {
       "name": "@oh-my-pi/pi-utils",
-      "version": "15.10.0",
+      "version": "15.10.1",
       "dependencies": {
         "@oh-my-pi/pi-natives": "catalog:",
         "beautiful-mermaid": "catalog:",
@@ -248,15 +248,15 @@
     "@huggingface/transformers": "^4.2.0",
     "@mozilla/readability": "^0.6.0",
     "@napi-rs/cli": "3.7.0",
-    "@oh-my-pi/hashline": "15.10.0",
-    "@oh-my-pi/omp-stats": "15.10.0",
-    "@oh-my-pi/pi-agent-core": "15.10.0",
-    "@oh-my-pi/pi-ai": "15.10.0",
-    "@oh-my-pi/pi-coding-agent": "15.10.0",
-    "@oh-my-pi/pi-mnemopi": "15.10.0",
-    "@oh-my-pi/pi-natives": "15.10.0",
-    "@oh-my-pi/pi-tui": "15.10.0",
-    "@oh-my-pi/pi-utils": "15.10.0",
+    "@oh-my-pi/hashline": "15.10.1",
+    "@oh-my-pi/omp-stats": "15.10.1",
+    "@oh-my-pi/pi-agent-core": "15.10.1",
+    "@oh-my-pi/pi-ai": "15.10.1",
+    "@oh-my-pi/pi-coding-agent": "15.10.1",
+    "@oh-my-pi/pi-mnemopi": "15.10.1",
+    "@oh-my-pi/pi-natives": "15.10.1",
+    "@oh-my-pi/pi-tui": "15.10.1",
+    "@oh-my-pi/pi-utils": "15.10.1",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/context-async-hooks": "^2.7.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",
@@ -1159,7 +1159,7 @@
 
     "onnxruntime-web": ["onnxruntime-web@1.26.0-dev.20260416-b7804b056c", "", { "dependencies": { "flatbuffers": "^25.1.24", "guid-typescript": "^1.0.9", "long": "^5.2.3", "onnxruntime-common": "1.24.0-dev.20251116-b39e144322", "platform": "^1.3.6", "protobufjs": "^7.2.4" } }, "sha512-MD6Ss4GSpQBo6zqoJzyT9LRbKYs7x/JVN23FT24EcEvlqF4VuzPOeH6X38orZPKHQDbprn7K+SBpu0/mj2CQiw=="],
 
-    "openai": ["openai@6.39.1", "", { "peerDependencies": { "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["ws", "zod"], "bin": { "openai": "bin/cli" } }, "sha512-z3dO9fEWOXBzlXynVb/xZ/tujzUjFWQWn3C0n0mw6Vo0zJTbEkaN4b2cLWjhJ6haJQx8LlREoafHRl+Gu/Hl+A=="],
+    "openai": ["openai@6.42.0", "", { "peerDependencies": { "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["ws", "zod"] }, "sha512-1WFEt/uXMXOLhYRNkgJWo08Y2YNvNwpVU72K7ibrWgWpNOXd4VojXLbe6SQ4bLiUQ3Y8jz4IiyVkylJCL1DtZg=="],
 
     "option": ["option@0.2.4", "", {}, "sha512-pkEqbDyl8ou5cpq+VsnQbe/WlEy5qS7xPzMS1U55OCG9KPvwFD46zDbxQIj3egJSFc3D+XhYOPUzz49zQAVy7A=="],
 
@@ -1259,7 +1259,7 @@
 
     "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
 
-    "string_decoder": ["string_decoder@1.3.0", "", { "dependencies": { "safe-buffer": "~5.2.0" } }, "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA=="],
+    "string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
 
     "strip-ansi": ["strip-ansi@7.2.0", "", { "dependencies": { "ansi-regex": "^6.2.2" } }, "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w=="],
 
@@ -1413,8 +1413,6 @@
 
     "string-width/strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
 
-    "string_decoder/safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
-
     "wrap-ansi/string-width": ["string-width@8.2.1", "", { "dependencies": { "get-east-asian-width": "^1.5.0", "strip-ansi": "^7.1.2" } }, "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA=="],
 
     "xml2js/xmlbuilder": ["xmlbuilder@11.0.1", "", {}, "sha512-fDlsI/kFEx7gLvbecc0/ohLG50fugQp8ryHzMTuW9vSa1GJ0XYWKnhsUx7oie3G98+r56aTQIUB4kht42R3JvA=="],
@@ -1429,8 +1427,6 @@
 
     "fastembed/onnxruntime-node/tar": ["tar@7.5.16", "", { "dependencies": { "@isaacs/fs-minipass": "^4.0.0", "chownr": "^3.0.0", "minipass": "^7.1.2", "minizlib": "^3.1.0", "yallist": "^5.0.0" } }, "sha512-56adEpPMouktRlBLXiaYFFzZ/3+JXa8P9n7WbR+ibIjtviN55mEaOkiysCnPnWm+7kkui1Dn8J9l+g6zV8731w=="],
 
-    "jszip/readable-stream/string_decoder": ["string_decoder@1.1.1", "", { "dependencies": { "safe-buffer": "~5.1.0" } }, "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg=="],
-
     "log-update/slice-ansi/is-fullwidth-code-point": ["is-fullwidth-code-point@5.1.0", "", { "dependencies": { "get-east-asian-width": "^1.3.1" } }, "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ=="],
 
     "log-update/wrap-ansi/string-width": ["string-width@7.2.0", "", { "dependencies": { "emoji-regex": "^10.3.0", "get-east-asian-width": "^1.0.0", "strip-ansi": "^7.1.0" } }, "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ=="],
diff --git a/crates/pi-natives/src/lib.rs b/crates/pi-natives/src/lib.rs
index 9315e6d6d..6b9c17c74 100644
--- a/crates/pi-natives/src/lib.rs
+++ b/crates/pi-natives/src/lib.rs
@@ -68,5 +68,5 @@ use napi_derive::napi;
 /// MUST stay in sync with `VERSION_SENTINEL_EXPORT` in
 /// `packages/natives/native/index.js` (which derives the name from
 /// `package.json#version`).
-#[napi(js_name = "__piNativesV15_10_0")]
+#[napi(js_name = "__piNativesV15_10_1")]
 pub const fn pi_natives_version_sentinel() {}
diff --git a/package.json b/package.json
index bed3a457c..435a43242 100644
--- a/package.json
+++ b/package.json
@@ -20,15 +20,15 @@
       "@huggingface/transformers": "^4.2.0",
       "@mozilla/readability": "^0.6.0",
       "@napi-rs/cli": "3.7.0",
-      "@oh-my-pi/hashline": "15.10.0",
-      "@oh-my-pi/omp-stats": "15.10.0",
-      "@oh-my-pi/pi-agent-core": "15.10.0",
-      "@oh-my-pi/pi-ai": "15.10.0",
-      "@oh-my-pi/pi-coding-agent": "15.10.0",
-      "@oh-my-pi/pi-mnemopi": "15.10.0",
-      "@oh-my-pi/pi-natives": "15.10.0",
-      "@oh-my-pi/pi-tui": "15.10.0",
-      "@oh-my-pi/pi-utils": "15.10.0",
+      "@oh-my-pi/hashline": "15.10.1",
+      "@oh-my-pi/omp-stats": "15.10.1",
+      "@oh-my-pi/pi-agent-core": "15.10.1",
+      "@oh-my-pi/pi-ai": "15.10.1",
+      "@oh-my-pi/pi-coding-agent": "15.10.1",
+      "@oh-my-pi/pi-mnemopi": "15.10.1",
+      "@oh-my-pi/pi-natives": "15.10.1",
+      "@oh-my-pi/pi-tui": "15.10.1",
+      "@oh-my-pi/pi-utils": "15.10.1",
       "@opentelemetry/api": "^1.9.1",
       "@opentelemetry/context-async-hooks": "^2.7.1",
       "@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",
diff --git a/packages/agent/CHANGELOG.md b/packages/agent/CHANGELOG.md
index 821fa9775..5e4dd0b4f 100644
--- a/packages/agent/CHANGELOG.md
+++ b/packages/agent/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.10.1] - 2026-06-07
+
 ### Added
 
 - Added optional `promptCacheKey` support to `AgentOptions` and `Agent` via a new `promptCacheKey` property so providers can receive a caller-provided prompt cache key
diff --git a/packages/agent/package.json b/packages/agent/package.json
index 840bc95e2..6d256bd40 100644
--- a/packages/agent/package.json
+++ b/packages/agent/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index d1d10eceb..d62e002fe 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.10.1] - 2026-06-07
+
 ### Breaking Changes
 
 - Removed the `onAuthError` option from stream request options and shifted auth retry handling to resolver-based `apiKey` behavior, requiring callers using custom auth-retry hooks to migrate
diff --git a/packages/ai/package.json b/packages/ai/package.json
index 2e02371fa..7a108d2e6 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 44ba07e69..0243ed841 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.10.1] - 2026-06-07
+
 ### Added
 
 - Added `display.smoothStreaming` setting (default `true`) to let users enable or disable smooth assistant-stream text reveal
diff --git a/packages/coding-agent/package.json b/packages/coding-agent/package.json
index e86222fba..68682aa71 100644
--- a/packages/coding-agent/package.json
+++ b/packages/coding-agent/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/hashline/package.json b/packages/hashline/package.json
index 3b4b99e55..cf4a8dd30 100644
--- a/packages/hashline/package.json
+++ b/packages/hashline/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/mnemopi/package.json b/packages/mnemopi/package.json
index db14552f5..594c2c9ca 100644
--- a/packages/mnemopi/package.json
+++ b/packages/mnemopi/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-mnemopi",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Local SQLite memory engine for Oh My Pi agents",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/natives/CHANGELOG.md b/packages/natives/CHANGELOG.md
index 1add39043..c89da28eb 100644
--- a/packages/natives/CHANGELOG.md
+++ b/packages/natives/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [15.10.1] - 2026-06-07
+
 ### Fixed
 
 - Fixed `applyBashFixups` corrupting commands that contain multi-byte UTF-8 before a trailing `| head`/`| tail` (or `2>&1`). `brush-parser` reports source positions as Unicode-scalar (char) offsets, but `pi_shell::fixup` sliced the command `&str` by those numbers as if they were byte offsets, so each multi-byte char (e.g. `✓`/`×` in a `grep -E` pattern) shifted the cut earlier and left a mangled command — e.g. `… |✓|×|XCTAssert" | tail -80` became `… |✓|×-80`, orphaning the closing quote and making the shell reject the whole pipeline with `unterminated double quote`. Positions are now translated to byte offsets before slicing.
diff --git a/packages/natives/native/index.d.ts b/packages/natives/native/index.d.ts
index 827c49936..8451d0d8a 100644
--- a/packages/natives/native/index.d.ts
+++ b/packages/natives/native/index.d.ts
@@ -136,7 +136,7 @@ export declare class Shell {
  * `packages/natives/native/index.js` (which derives the name from
  * `package.json#version`).
  */
-export declare function __piNativesV15_10_0(): void
+export declare function __piNativesV15_10_1(): void
 
 /**
  * Apply conservative pre-execution rewrites to a bash command.
diff --git a/packages/natives/native/index.js b/packages/natives/native/index.js
index b662239fa..e2a302227 100644
--- a/packages/natives/native/index.js
+++ b/packages/natives/native/index.js
@@ -23,7 +23,7 @@ export const PtySession = nativeBindings.PtySession;
 export const Shell = nativeBindings.Shell;
 
 // functions
-export const __piNativesV15_10_0 = nativeBindings.__piNativesV15_10_0;
+export const __piNativesV15_10_1 = nativeBindings.__piNativesV15_10_1;
 export const applyBashFixups = nativeBindings.applyBashFixups;
 export const astEdit = nativeBindings.astEdit;
 export const astGrep = nativeBindings.astGrep;
diff --git a/packages/natives/package.json b/packages/natives/package.json
index 4076f4d0a..cc76acb89 100644
--- a/packages/natives/package.json
+++ b/packages/natives/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@oh-my-pi/pi-natives",
-  "version": "15.10.0",
+  "version": "15.10.1",
   "description": "Native Rust bindings for grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
   "type": "module",
   "homepage": "https://omp.sh",
diff --git a/packages/stats/package.json b/packages/stats/package.json
index 501113c72..d44baa743 100644
--- a/packages/stats/package.json
+++ b/packages/stats/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/omp-stats",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Local observability dashboard for pi AI usage statistics",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/swarm-extension/package.json b/packages/swarm-extension/package.json
index 1008d156c..ade71b483 100644
--- a/packages/swarm-extension/package.json
+++ b/packages/swarm-extension/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/swarm-extension",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Swarm orchestration extension for omp",
 	"homepage": "https://omp.sh",
 	"author": "Derek Rynd",
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 485d298ad..56903eddc 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -1,6 +1,8 @@
 # Changelog
 
 ## [Unreleased]
+
+## [15.10.1] - 2026-06-07
 ### Breaking Changes
 
 - Removed Kitty temp-file image transmission, its startup support probe, the `PI_KITTY_IMAGE_TRANSMISSION` override, and the temp-file helper exports. Kitty/Ghostty image payloads now stay on in-band base64 before placeholder/direct placement, avoiding blank first renders from temp-file load races.
diff --git a/packages/tui/package.json b/packages/tui/package.json
index bbf0da634..76fa4fa1b 100644
--- a/packages/tui/package.json
+++ b/packages/tui/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
diff --git a/packages/utils/package.json b/packages/utils/package.json
index fafae9827..1368e3552 100644
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "15.10.0",
+	"version": "15.10.1",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",

From b6d422ff6577e879ff24d6bd1eaec0d68721775a Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Sun, 7 Jun 2026 09:34:20 +0200
Subject: [PATCH 144/181] fix(ai): memoized PI_REQ_DEBUG response-log close to
 avoid truncated body on cancel

---
 packages/ai/CHANGELOG.md               |  1 +
 packages/ai/src/utils/request-debug.ts | 19 ++++++++++++-------
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index d62e002fe..344d76b9a 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -27,6 +27,7 @@
 - Fixed the HTTP 400 raw-request dumper (`appendRawHttpRequestDumpFor400`) littering the real `~/.omp/logs/http-400-requests` directory during tests. Provider suites exercise the 400 error path with mocked `fetch` responses, which the dumper could not distinguish from genuine failures; it now skips persistence under the Bun test runner (`isBunTestRuntime()`).
 - Fixed Anthropic Opus requests unnecessarily forcing `tool_choice.disable_parallel_tool_use`, allowing Claude Opus to use the provider's default parallel tool-calling behavior again.
 - Fixed parallel `function_call` items losing arguments against llama.cpp's OpenAI Responses endpoint (`/v1/responses`), where every call but the last finalized with `{}` and the agent rejected them with `path: Invalid input: expected string, received undefined`. llama.cpp's `to_json_oaicompat_resp` emits `output_item.added` with only `item.call_id` (no `item.id`, no `output_index`) while the matching `function_call_arguments.delta` carries `item_id: "fc_<call_id>"`. `processResponsesStream` now registers function-call and custom-tool-call items under `item.call_id` as a secondary lookup key (alongside `item.id`/`output_index`) so identifier-deviant hosts route deltas and done events to the right block. ([#2015](https://github.com/can1357/oh-my-pi/issues/2015))
+- Fixed `PI_REQ_DEBUG` response recording truncating the captured body when a streamed response was cancelled mid-flight. The response tee in `wrapResponse` could call `FileRequestDebugResponseLog.close()` from both the `cancel` callback and the resumed `pull` (which observes `done` once the source reader is cancelled); the second caller saw the handle already nulled and returned before the first caller's pending write flushed, so the `.res.log` lost the already-buffered chunk. `close()` now memoizes its flush-and-close promise so every caller awaits the same completion.
 
 ## [15.10.0] - 2026-06-06
 
diff --git a/packages/ai/src/utils/request-debug.ts b/packages/ai/src/utils/request-debug.ts
index 193f51be6..daa6831c4 100644
--- a/packages/ai/src/utils/request-debug.ts
+++ b/packages/ai/src/utils/request-debug.ts
@@ -170,6 +170,7 @@ class FileRequestDebugSession implements RequestDebugSession {
 class FileRequestDebugResponseLog implements RequestDebugResponseLog {
 	#handle: fs.FileHandle | undefined;
 	#pending: Promise<void> = Promise.resolve();
+	#closed: Promise<void> | undefined;
 
 	constructor(handle: fs.FileHandle) {
 		this.#handle = handle;
@@ -184,15 +185,19 @@ class FileRequestDebugResponseLog implements RequestDebugResponseLog {
 		});
 	}
 
-	async close(): Promise<void> {
+	close(): Promise<void> {
+		if (this.#closed) return this.#closed;
 		const handle = this.#handle;
-		if (!handle) return;
+		if (!handle) return Promise.resolve();
 		this.#handle = undefined;
-		try {
-			await this.#pending;
-		} finally {
-			await handle.close();
-		}
+		this.#closed = (async () => {
+			try {
+				await this.#pending;
+			} finally {
+				await handle.close();
+			}
+		})();
+		return this.#closed;
 	}
 }
 

From 1c2e22068af4ebbb82eadca79ba20a5db0f43f3c Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 08:49:15 +0000
Subject: [PATCH 145/181] fix(tui): chunked oversized writes on Windows ConPTY
 so viewport tracks the cursor

Windows ConPTY ties viewport tracking to per-WriteFile boundaries: when a
single process.stdout.write exceeds ~32-64 KB, the pseudo-console stops
following the cursor and the host UI's scroll position stays parked at
wherever the write began. Full paints (resume, history rebuild, large
permission dialogs) showed only the first screenful until Alt+Tab forced
the host to re-query the cursor; the bytes always landed in scrollback.

ProcessTerminal#safeWrite now routes win32 writes through a new
chunkForConPTY helper that splits oversized buffers into <=8 KiB pieces
at \n boundaries, keeping every WriteFile well below the threshold and
escape sequences intact (TUI paints separate rows with \r\n, so a line
break almost always exists in range). Non-win32 platforms keep the
single-write fast path.

Fixes #2034
---
 packages/tui/CHANGELOG.md                  |   4 +
 packages/tui/src/terminal.ts               |  66 +++++++-
 packages/tui/test/issue-2034-repro.test.ts | 173 +++++++++++++++++++++
 3 files changed, 242 insertions(+), 1 deletion(-)
 create mode 100644 packages/tui/test/issue-2034-repro.test.ts

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 56903eddc..ed1709c60 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed Windows ConPTY hosts (Windows Terminal, Tabby, Hyper, VS Code) parking the viewport at the top of a full paint after a `/resume` or any long-session repaint. `ProcessTerminal#safeWrite` now splits oversized writes into ≤ 8 KiB pieces at line boundaries on `win32` so each underlying `WriteFile` stays below the ~32 KiB threshold where ConPTY stops tracking the cursor; the data was always delivered, but the host UI's scroll position would not follow until any focus event forced a re-query. ([#2034](https://github.com/can1357/oh-my-pi/issues/2034))
+
 ## [15.10.1] - 2026-06-07
 ### Breaking Changes
 
diff --git a/packages/tui/src/terminal.ts b/packages/tui/src/terminal.ts
index 2069f6370..6c04f0805 100644
--- a/packages/tui/src/terminal.ts
+++ b/packages/tui/src/terminal.ts
@@ -9,6 +9,58 @@ const TERMINAL_PROGRESS_KEEPALIVE_MS = 1000;
 const TERMINAL_PROGRESS_ACTIVE_SEQUENCE = "\x1b]9;4;3\x07";
 const TERMINAL_PROGRESS_CLEAR_SEQUENCE = "\x1b]9;4;0;\x07";
 
+/**
+ * Maximum bytes per `process.stdout.write` call on Windows.
+ *
+ * Windows ConPTY ties viewport tracking to per-`WriteFile` boundaries: when a
+ * single write exceeds ~32-64 KB, the pseudo-console stops following the
+ * cursor and the host UI's viewport stays parked at whatever scroll position
+ * the write started from. The visible symptom is that a full-paint of a long
+ * session (resume, history rebuild, large permission dialog) shows only the
+ * first ~30 lines until any focus event forces the host to re-query the
+ * cursor. The data is delivered correctly — it's purely a viewport-sync bug.
+ *
+ * 8 KiB is well below the 32 KiB threshold reported on Windows Terminal and
+ * leaves headroom for the other ConPTY hosts (Tabby, Hyper, VS Code) where
+ * the exact limit is undocumented. The cost is a handful of extra syscalls
+ * per full paint — invisible compared to the cost of the paint itself.
+ */
+const MAX_CONPTY_WRITE_CHUNK = 8 * 1024;
+
+/**
+ * Split `data` into chunks no larger than `maxChunkSize`, preferring a line
+ * boundary (`\n`) as the cut point so escape sequences (which never contain
+ * `\n`) stay intact. The TUI's full-paint buffers are line-structured
+ * (`buffer += "\r\n"` between rows), so a newline almost always exists within
+ * the window. The fallback for a buffer with no newline in range is a hard
+ * cut at `maxChunkSize`: the ConPTY viewport bug from a single oversized
+ * write is strictly worse than a one-frame escape-sequence glitch on a buffer
+ * the renderer effectively never produces.
+ *
+ * Exported for unit testing of the chunking contract; `#safeWrite` is the
+ * sole production caller.
+ */
+export function chunkForConPTY(data: string, maxChunkSize: number = MAX_CONPTY_WRITE_CHUNK): string[] {
+	if (data.length <= maxChunkSize) return [data];
+	const chunks: string[] = [];
+	let pos = 0;
+	while (pos < data.length) {
+		const remaining = data.length - pos;
+		if (remaining <= maxChunkSize) {
+			chunks.push(data.slice(pos));
+			break;
+		}
+		const windowEnd = pos + maxChunkSize;
+		// Prefer the last newline inside the window so escape sequences stay
+		// intact within their chunk; hard-cut at `windowEnd` otherwise.
+		const nl = data.lastIndexOf("\n", windowEnd - 1);
+		const cut = nl >= pos ? nl + 1 : windowEnd;
+		chunks.push(data.slice(pos, cut));
+		pos = cut;
+	}
+	return chunks;
+}
+
 /**
  * Minimal terminal interface for TUI
  */
@@ -978,7 +1030,19 @@ export class ProcessTerminal implements Terminal {
 		// files). They serve no purpose there and would surface as visible noise.
 		if (!process.stdout.isTTY) return;
 		try {
-			process.stdout.write(data);
+			// Windows ConPTY drops viewport tracking when a single write exceeds
+			// ~32-64 KB: the host UI's scroll position stays parked at wherever
+			// the write began, even though every byte landed in scrollback. Split
+			// large paints into newline-aligned chunks so each underlying
+			// `WriteFile` stays well below the threshold. Non-win32 PTYs do not
+			// share the bug, so they keep the single-write fast path. See #2034.
+			if (process.platform === "win32" && data.length > MAX_CONPTY_WRITE_CHUNK) {
+				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK)) {
+					process.stdout.write(chunk);
+				}
+			} else {
+				process.stdout.write(data);
+			}
 		} catch (err) {
 			// Any write failure means terminal is dead - no recovery possible
 			this.#dead = true;
diff --git a/packages/tui/test/issue-2034-repro.test.ts b/packages/tui/test/issue-2034-repro.test.ts
new file mode 100644
index 000000000..e928d73a4
--- /dev/null
+++ b/packages/tui/test/issue-2034-repro.test.ts
@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import { chunkForConPTY, ProcessTerminal } from "@oh-my-pi/pi-tui/terminal";
+
+// Regression test for https://github.com/can1357/oh-my-pi/issues/2034
+//
+// Windows ConPTY ties viewport tracking to per-`WriteFile` boundaries: when
+// a single `process.stdout.write` exceeds ~32-64 KB, the pseudo-console
+// stops following the cursor and the host UI's scroll position stays parked
+// at wherever the write began. The data lands in scrollback — Alt+Tab forces
+// the host to re-query the cursor and the viewport jumps to the bottom —
+// but until then the user sees only the first screenful of a long session
+// or resume payload.
+//
+// Fix: `ProcessTerminal#safeWrite` chunks oversized writes into ≤ 8 KiB
+// pieces on `process.platform === "win32"`. Non-win32 PTYs do not share the
+// bug and keep the single-write fast path.
+
+const ESC = "\x1b";
+
+function buildFullPaint(lines: number, lineLength: number): string {
+	// Mirrors the shape of `TUI#emitFullPaint`'s buffer: a clear-screen prefix,
+	// rows terminated with `\r\n` and a per-line SGR reset, and a cursor/end
+	// sequence trailer. The exact bytes do not matter for the chunker — only
+	// that escapes are present and the buffer crosses the ConPTY threshold.
+	let buf = `${ESC}[2J${ESC}[H${ESC}[3J`;
+	for (let i = 0; i < lines; i++) {
+		if (i > 0) buf += "\r\n";
+		const content = `${ESC}[38;5;${i % 256}mrow-${i.toString().padStart(4, "0")}: ${"x".repeat(lineLength)}${ESC}[0m`;
+		buf += content;
+	}
+	buf += `${ESC}[H${ESC}[?25h`;
+	return buf;
+}
+
+describe("issue #2034: chunk large terminal writes on Windows ConPTY", () => {
+	describe("chunkForConPTY()", () => {
+		it("returns the original buffer untouched when under the chunk size", () => {
+			const data = "small payload";
+			expect(chunkForConPTY(data, 1024)).toEqual([data]);
+		});
+
+		it("splits a large multi-line buffer into pieces no larger than the chunk size", () => {
+			const data = buildFullPaint(2000, 60);
+			const max = 8 * 1024;
+			expect(data.length).toBeGreaterThan(max);
+
+			const chunks = chunkForConPTY(data, max);
+
+			expect(chunks.length).toBeGreaterThan(1);
+			for (const chunk of chunks) {
+				expect(chunk.length).toBeLessThanOrEqual(max);
+			}
+		});
+
+		it("preserves the full payload across chunks (no data loss or reordering)", () => {
+			const data = buildFullPaint(500, 120);
+			const chunks = chunkForConPTY(data, 4 * 1024);
+			expect(chunks.join("")).toBe(data);
+		});
+
+		it("splits at newline boundaries so escape sequences are never sliced apart", () => {
+			// Every row is bracketed by SGR escapes. If the chunker cut inside a
+			// chunk's escape sequence, the trailing chunk would not start with
+			// either an escape or the post-newline state — instead it would
+			// start with a stray CSI byte (`[`, digits, `m`).
+			const data = buildFullPaint(400, 80);
+			const chunks = chunkForConPTY(data, 4 * 1024);
+			// Exclude the head chunk (starts with the clear-screen prefix).
+			for (const chunk of chunks.slice(1)) {
+				// Every subsequent chunk begins on a fresh line: either the new
+				// line's first byte is the SGR escape, the row's plaintext
+				// prefix, or — for the trailing tail — the cursor sequence.
+				const firstByte = chunk.charCodeAt(0);
+				const startsWithEsc = chunk.startsWith(ESC);
+				const startsWithRowText = chunk.startsWith("row-");
+				expect(startsWithEsc || startsWithRowText).toBe(true);
+				if (!startsWithEsc) {
+					// Plain-text starts cannot be control characters that would
+					// indicate a sliced escape (CSI `[`, digits, or `m`).
+					expect(firstByte).toBeGreaterThanOrEqual(0x20);
+				}
+			}
+		});
+
+		it("makes forward progress on a single line longer than the chunk size", () => {
+			// Pathological case: one very long line with no embedded `\n`. The
+			// chunker must not loop, and the joined chunks must equal the input.
+			const giantLine = "a".repeat(20_000);
+			const data = `${giantLine}\nshort\n`;
+			const chunks = chunkForConPTY(data, 4 * 1024);
+			expect(chunks.length).toBeGreaterThanOrEqual(2);
+			expect(chunks.join("")).toBe(data);
+		});
+
+		it("falls back to a raw split when the buffer contains no newlines", () => {
+			const data = "x".repeat(20_000);
+			const chunks = chunkForConPTY(data, 4 * 1024);
+			expect(chunks.join("")).toBe(data);
+			expect(chunks.length).toBeGreaterThan(1);
+			// Every chunk except possibly the tail is exactly the chunk size.
+			for (const chunk of chunks.slice(0, -1)) {
+				expect(chunk.length).toBe(4 * 1024);
+			}
+		});
+	});
+
+	describe("ProcessTerminal#write on win32", () => {
+		const stdinIsTtyDescriptor = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
+		const stdoutIsTtyDescriptor = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
+		const platformDescriptor = Object.getOwnPropertyDescriptor(process, "platform");
+
+		beforeEach(() => {
+			Object.defineProperty(process.stdin, "isTTY", { value: true, configurable: true });
+			Object.defineProperty(process.stdout, "isTTY", { value: true, configurable: true });
+		});
+
+		afterEach(() => {
+			vi.restoreAllMocks();
+			if (platformDescriptor) Object.defineProperty(process, "platform", platformDescriptor);
+			if (stdinIsTtyDescriptor) Object.defineProperty(process.stdin, "isTTY", stdinIsTtyDescriptor);
+			else Reflect.deleteProperty(process.stdin, "isTTY");
+			if (stdoutIsTtyDescriptor) Object.defineProperty(process.stdout, "isTTY", stdoutIsTtyDescriptor);
+			else Reflect.deleteProperty(process.stdout, "isTTY");
+		});
+
+		function captureStdoutWrites(): string[] {
+			const writes: string[] = [];
+			vi.spyOn(process.stdout, "write").mockImplementation(chunk => {
+				writes.push(typeof chunk === "string" ? chunk : chunk.toString());
+				return true;
+			});
+			return writes;
+		}
+
+		it("splits >8 KiB writes into chunks on win32 so ConPTY can track the viewport", () => {
+			Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+			const writes = captureStdoutWrites();
+			const terminal = new ProcessTerminal();
+			const payload = buildFullPaint(2000, 60);
+
+			terminal.write(payload);
+
+			const conptyChunks = writes.filter(w => w.length > 0);
+			expect(conptyChunks.length).toBeGreaterThan(1);
+			for (const chunk of conptyChunks) {
+				expect(chunk.length).toBeLessThanOrEqual(8 * 1024);
+			}
+			expect(conptyChunks.join("")).toBe(payload);
+		});
+
+		it("keeps the single-write fast path on non-win32 platforms", () => {
+			Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+			const writes = captureStdoutWrites();
+			const terminal = new ProcessTerminal();
+			const payload = buildFullPaint(2000, 60);
+
+			terminal.write(payload);
+
+			expect(writes).toEqual([payload]);
+		});
+
+		it("does not chunk small writes on win32", () => {
+			Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+			const writes = captureStdoutWrites();
+			const terminal = new ProcessTerminal();
+			const payload = `${ESC}[H${ESC}[K`;
+
+			terminal.write(payload);
+
+			expect(writes).toEqual([payload]);
+		});
+	});
+});

From 271b9ed62059dcd2bcbfe601e41c29460c4cf095 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 08:54:07 +0000
Subject: [PATCH 146/181] fix(tui): extended ConPTY chunking gate to WSL

WSL processes report process.platform === 'linux', but their stdout still
funnels through wslhost into the same Windows ConPTY pipe, so the >32 KB
viewport-tracking regression reproduces there as well. The gate now fires
whenever process.platform === 'win32' OR isWindowsSubsystemForLinux()
detects WSL_DISTRO_NAME/WSL_INTEROP. Genuine POSIX terminals keep the
single-write fast path.

Added a WSL-specific test alongside the existing win32 / clean-linux
cases to lock the broader gate.

Fixes #2034
---
 packages/tui/CHANGELOG.md                  |  2 +-
 packages/tui/src/terminal.ts               | 10 +++++--
 packages/tui/test/issue-2034-repro.test.ts | 34 ++++++++++++++++++++--
 3 files changed, 40 insertions(+), 6 deletions(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index ed1709c60..43d1599f9 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Fixed
 
-- Fixed Windows ConPTY hosts (Windows Terminal, Tabby, Hyper, VS Code) parking the viewport at the top of a full paint after a `/resume` or any long-session repaint. `ProcessTerminal#safeWrite` now splits oversized writes into ≤ 8 KiB pieces at line boundaries on `win32` so each underlying `WriteFile` stays below the ~32 KiB threshold where ConPTY stops tracking the cursor; the data was always delivered, but the host UI's scroll position would not follow until any focus event forced a re-query. ([#2034](https://github.com/can1357/oh-my-pi/issues/2034))
+- Fixed Windows ConPTY hosts (Windows Terminal, Tabby, Hyper, VS Code) parking the viewport at the top of a full paint after a `/resume` or any long-session repaint. `ProcessTerminal#safeWrite` now splits oversized writes into ≤ 8 KiB pieces at line boundaries on `win32` and inside WSL (where stdout still crosses ConPTY at the `wslhost` boundary) so each underlying `WriteFile` stays below the ~32 KiB threshold where ConPTY stops tracking the cursor; the data was always delivered, but the host UI's scroll position would not follow until any focus event forced a re-query. ([#2034](https://github.com/can1357/oh-my-pi/issues/2034))
 
 ## [15.10.1] - 2026-06-07
 ### Breaking Changes
diff --git a/packages/tui/src/terminal.ts b/packages/tui/src/terminal.ts
index 6c04f0805..90a74803b 100644
--- a/packages/tui/src/terminal.ts
+++ b/packages/tui/src/terminal.ts
@@ -1034,9 +1034,13 @@ export class ProcessTerminal implements Terminal {
 			// ~32-64 KB: the host UI's scroll position stays parked at wherever
 			// the write began, even though every byte landed in scrollback. Split
 			// large paints into newline-aligned chunks so each underlying
-			// `WriteFile` stays well below the threshold. Non-win32 PTYs do not
-			// share the bug, so they keep the single-write fast path. See #2034.
-			if (process.platform === "win32" && data.length > MAX_CONPTY_WRITE_CHUNK) {
+			// `WriteFile` stays well below the threshold. The gate also covers
+			// WSL — `process.platform === "linux"` there, but stdout still
+			// crosses into ConPTY at the `wslhost` boundary, so the same per-
+			// WriteFile cap applies. Non-ConPTY PTYs keep the single-write fast
+			// path. See #2034.
+			const conptyHosted = process.platform === "win32" || isWindowsSubsystemForLinux();
+			if (conptyHosted && data.length > MAX_CONPTY_WRITE_CHUNK) {
 				for (const chunk of chunkForConPTY(data, MAX_CONPTY_WRITE_CHUNK)) {
 					process.stdout.write(chunk);
 				}
diff --git a/packages/tui/test/issue-2034-repro.test.ts b/packages/tui/test/issue-2034-repro.test.ts
index e928d73a4..1391fe6ea 100644
--- a/packages/tui/test/issue-2034-repro.test.ts
+++ b/packages/tui/test/issue-2034-repro.test.ts
@@ -104,14 +104,24 @@ describe("issue #2034: chunk large terminal writes on Windows ConPTY", () => {
 		});
 	});
 
-	describe("ProcessTerminal#write on win32", () => {
+	describe("ProcessTerminal#write platform gate", () => {
 		const stdinIsTtyDescriptor = Object.getOwnPropertyDescriptor(process.stdin, "isTTY");
 		const stdoutIsTtyDescriptor = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
 		const platformDescriptor = Object.getOwnPropertyDescriptor(process, "platform");
+		const originalWslDistro = Bun.env.WSL_DISTRO_NAME;
+		const originalWslInterop = Bun.env.WSL_INTEROP;
+
+		function setEnv(key: string, value: string | undefined): void {
+			if (value === undefined) delete Bun.env[key];
+			else Bun.env[key] = value;
+		}
 
 		beforeEach(() => {
 			Object.defineProperty(process.stdin, "isTTY", { value: true, configurable: true });
 			Object.defineProperty(process.stdout, "isTTY", { value: true, configurable: true });
+			// Clear WSL markers by default; tests opt in.
+			setEnv("WSL_DISTRO_NAME", undefined);
+			setEnv("WSL_INTEROP", undefined);
 		});
 
 		afterEach(() => {
@@ -121,6 +131,8 @@ describe("issue #2034: chunk large terminal writes on Windows ConPTY", () => {
 			else Reflect.deleteProperty(process.stdin, "isTTY");
 			if (stdoutIsTtyDescriptor) Object.defineProperty(process.stdout, "isTTY", stdoutIsTtyDescriptor);
 			else Reflect.deleteProperty(process.stdout, "isTTY");
+			setEnv("WSL_DISTRO_NAME", originalWslDistro);
+			setEnv("WSL_INTEROP", originalWslInterop);
 		});
 
 		function captureStdoutWrites(): string[] {
@@ -148,7 +160,25 @@ describe("issue #2034: chunk large terminal writes on Windows ConPTY", () => {
 			expect(conptyChunks.join("")).toBe(payload);
 		});
 
-		it("keeps the single-write fast path on non-win32 platforms", () => {
+		it("splits >8 KiB writes inside WSL because stdout still crosses ConPTY at wslhost", () => {
+			Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+			setEnv("WSL_DISTRO_NAME", "Ubuntu");
+			setEnv("WSL_INTEROP", "/run/WSL/123_interop");
+			const writes = captureStdoutWrites();
+			const terminal = new ProcessTerminal();
+			const payload = buildFullPaint(2000, 60);
+
+			terminal.write(payload);
+
+			const conptyChunks = writes.filter(w => w.length > 0);
+			expect(conptyChunks.length).toBeGreaterThan(1);
+			for (const chunk of conptyChunks) {
+				expect(chunk.length).toBeLessThanOrEqual(8 * 1024);
+			}
+			expect(conptyChunks.join("")).toBe(payload);
+		});
+
+		it("keeps the single-write fast path on non-ConPTY platforms (clean linux, darwin)", () => {
 			Object.defineProperty(process, "platform", { value: "linux", configurable: true });
 			const writes = captureStdoutWrites();
 			const terminal = new ProcessTerminal();

From df5abffe24d8c184c50f0cad2286e092f88116c6 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 09:13:37 +0000
Subject: [PATCH 147/181] fix(coding-agent): guard ctrl+z handler against
 missing SIGTSTP

handleCtrlZ called process.kill(0, "SIGTSTP") unconditionally; on
Windows the runtime rejects the signal name with TypeError, which
propagated out of the TUI input dispatcher and crashed the agent
with an [Uncaught Exception]. Even on POSIX the call could fail
(sandboxes that block sending to pid=0, runtime-reserved signals),
and a thrown error after we already stopped the TUI and registered
a one-shot SIGCONT listener left the UI stranded with a leaked
handler that would fire on the next unrelated continue and try to
re-start() an already-running TUI.

Branch on process.platform first so Windows shows a status notice
and never calls process.kill, and wrap the POSIX kill in try/catch
that removes the SIGCONT listener and re-starts the TUI on failure.

Fixes #2036
---
 packages/coding-agent/CHANGELOG.md            |   4 +
 .../src/modes/controllers/input-controller.ts |  39 +++++-
 .../test/input-controller-suspend.test.ts     | 128 ++++++++++++++++++
 3 files changed, 165 insertions(+), 6 deletions(-)
 create mode 100644 packages/coding-agent/test/input-controller-suspend.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0243ed841..abe213a68 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed Ctrl+Z crashing the agent on Windows with `TypeError: Unknown signal: SIGTSTP`. `InputController.handleCtrlZ` called `process.kill(0, "SIGTSTP")` unconditionally, but `SIGTSTP` is POSIX job-control and Bun/Node on Windows rejects the signal name from the JS side; the throw propagated out of the TUI input dispatcher as an uncaught exception. The handler now no-ops with a "Suspend (Ctrl+Z) is not supported on this platform" status on Windows, and on POSIX wraps `process.kill` in a try/catch that detaches the registered SIGCONT resume hook and re-`start()`s the TUI on failure so a rejected signal can never leave the UI stranded with a leaked listener ([#2036](https://github.com/can1357/oh-my-pi/issues/2036)).
+
 ## [15.10.1] - 2026-06-07
 
 ### Added
diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index da83ea41b..d00c66d86 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -499,17 +499,44 @@ export class InputController {
 	}
 
 	handleCtrlZ(): void {
-		// Set up handler to restore TUI when resumed
-		process.once("SIGCONT", () => {
+		// SIGTSTP is POSIX job-control: Windows has no equivalent and
+		// `process.kill(_, "SIGTSTP")` throws `TypeError: Unknown signal:
+		// SIGTSTP` there, taking the whole agent down via an uncaught
+		// exception (issue #2036). No-op on platforms that cannot suspend.
+		if (process.platform === "win32") {
+			this.ctx.showStatus("Suspend (Ctrl+Z) is not supported on this platform");
+			return;
+		}
+
+		// Capture the listener so we can detach it if the signal never
+		// fires; otherwise a failed suspend would leave a stale SIGCONT
+		// handler that fires on the next unrelated continue and tries to
+		// re-`start()` an already-running TUI.
+		const onResume = (): void => {
 			this.ctx.ui.start();
 			this.ctx.ui.requestRender(true);
-		});
+		};
+		process.once("SIGCONT", onResume);
 
-		// Stop the TUI (restore terminal to normal mode)
+		// Stop the TUI (restore terminal to normal mode) before sending the
+		// signal so the parent shell sees a sane terminal state.
 		this.ctx.ui.stop();
 
-		// Send SIGTSTP to process group (pid=0 means all processes in group)
-		process.kill(0, "SIGTSTP");
+		try {
+			// pid=0 → entire foreground process group; the shell receives
+			// SIGTSTP and parks the job.
+			process.kill(0, "SIGTSTP");
+		} catch (err) {
+			// Either the runtime refused the signal or the kernel rejected
+			// it (some sandboxes block sending to pid=0). Tear the resume
+			// hook down and bring the TUI back so the user is not stranded
+			// on a frozen prompt.
+			process.removeListener("SIGCONT", onResume);
+			this.ctx.ui.start();
+			this.ctx.ui.requestRender(true);
+			const reason = err instanceof Error ? err.message : String(err);
+			this.ctx.showError(`Failed to suspend: ${reason}`);
+		}
 	}
 
 	handleDequeue(): void {
diff --git a/packages/coding-agent/test/input-controller-suspend.test.ts b/packages/coding-agent/test/input-controller-suspend.test.ts
new file mode 100644
index 000000000..73945e9c9
--- /dev/null
+++ b/packages/coding-agent/test/input-controller-suspend.test.ts
@@ -0,0 +1,128 @@
+import { afterEach, describe, expect, it, type Mock, vi } from "bun:test";
+import { InputController } from "../src/modes/controllers/input-controller";
+import type { InteractiveModeContext } from "../src/modes/types";
+
+interface SuspendCtx {
+	ctx: InteractiveModeContext;
+	ui: {
+		start: Mock<() => void>;
+		stop: Mock<() => void>;
+		requestRender: Mock<(force?: boolean) => void>;
+	};
+	showStatus: Mock<(message: string) => void>;
+	showError: Mock<(message: string) => void>;
+}
+
+function createCtx(): SuspendCtx {
+	const ui = {
+		start: vi.fn(),
+		stop: vi.fn(),
+		requestRender: vi.fn(),
+	};
+	const showStatus = vi.fn();
+	const showError = vi.fn();
+	const ctx = {
+		ui: ui as unknown as InteractiveModeContext["ui"],
+		showStatus,
+		showError,
+	} as unknown as InteractiveModeContext;
+	return { ctx, ui, showStatus, showError };
+}
+
+const originalPlatform = process.platform;
+
+function setPlatform(value: NodeJS.Platform): void {
+	Object.defineProperty(process, "platform", { value, configurable: true, writable: true });
+}
+
+afterEach(() => {
+	Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true, writable: true });
+	vi.restoreAllMocks();
+	// Drop any SIGCONT listener a passing test left behind so a later test
+	// (or the next file) doesn't get spurious callbacks.
+	process.removeAllListeners("SIGCONT");
+});
+
+describe("InputController.handleCtrlZ", () => {
+	it("no-ops on Windows so the unsupported SIGTSTP signal can't crash the process (#2036)", () => {
+		setPlatform("win32");
+		const killSpy = vi.spyOn(process, "kill").mockImplementation(() => {
+			throw new Error("process.kill must not be called on win32");
+		});
+		const onceSpy = vi.spyOn(process, "once");
+		const { ctx, ui, showStatus, showError } = createCtx();
+
+		const controller = new InputController(ctx);
+		expect(() => controller.handleCtrlZ()).not.toThrow();
+
+		expect(killSpy).not.toHaveBeenCalled();
+		expect(onceSpy).not.toHaveBeenCalledWith("SIGCONT", expect.anything());
+		expect(ui.stop).not.toHaveBeenCalled();
+		expect(ui.start).not.toHaveBeenCalled();
+		expect(showStatus).toHaveBeenCalledTimes(1);
+		expect(showStatus.mock.calls[0]?.[0]).toMatch(/not supported/i);
+		expect(showError).not.toHaveBeenCalled();
+	});
+
+	it("sends SIGTSTP to the process group and registers a SIGCONT resume hook on POSIX", () => {
+		setPlatform("linux");
+		const killSpy = vi.spyOn(process, "kill").mockImplementation(() => true);
+		const onceSpy = vi.spyOn(process, "once");
+		const { ctx, ui, showError } = createCtx();
+
+		const controller = new InputController(ctx);
+		controller.handleCtrlZ();
+
+		// Resume hook registered BEFORE the signal is sent so a same-tick
+		// SIGCONT delivery can't race past us.
+		expect(onceSpy).toHaveBeenCalledWith("SIGCONT", expect.any(Function));
+		const sigcontOrder = onceSpy.mock.invocationCallOrder[0] ?? Infinity;
+		const stopOrder = ui.stop.mock.invocationCallOrder[0] ?? Infinity;
+		const killOrder = killSpy.mock.invocationCallOrder[0] ?? Infinity;
+		expect(sigcontOrder).toBeLessThan(stopOrder);
+		expect(stopOrder).toBeLessThan(killOrder);
+
+		expect(killSpy).toHaveBeenCalledTimes(1);
+		expect(killSpy).toHaveBeenCalledWith(0, "SIGTSTP");
+		expect(ui.start).not.toHaveBeenCalled();
+		expect(showError).not.toHaveBeenCalled();
+
+		// Simulating the kernel-delivered SIGCONT drives the TUI back up.
+		const resume = onceSpy.mock.calls.find(([sig]) => sig === "SIGCONT")?.[1] as (() => void) | undefined;
+		expect(resume).toBeDefined();
+		resume?.();
+		expect(ui.start).toHaveBeenCalledTimes(1);
+		expect(ui.requestRender).toHaveBeenCalledWith(true);
+	});
+
+	it("restores the TUI and drops the SIGCONT listener when process.kill rejects the signal", () => {
+		setPlatform("linux");
+		const killSpy = vi.spyOn(process, "kill").mockImplementation(() => {
+			throw new Error("Unknown signal: SIGTSTP");
+		});
+		const onceSpy = vi.spyOn(process, "once");
+		const removeSpy = vi.spyOn(process, "removeListener");
+		const { ctx, ui, showError, showStatus } = createCtx();
+
+		const controller = new InputController(ctx);
+		// Critical contract: the failure must not bubble up to the caller —
+		// otherwise the TUI's stdin reader (which invoked us) crashes the
+		// whole process via `[Uncaught Exception]`.
+		expect(() => controller.handleCtrlZ()).not.toThrow();
+
+		// The exact listener we registered for SIGCONT is the one we
+		// remove; otherwise a leaked handler would fire on the next
+		// unrelated continue and re-`start()` an already-running TUI.
+		const registered = onceSpy.mock.calls.find(([sig]) => sig === "SIGCONT")?.[1];
+		expect(registered).toBeDefined();
+		expect(removeSpy).toHaveBeenCalledWith("SIGCONT", registered);
+
+		expect(killSpy).toHaveBeenCalledTimes(1);
+		expect(ui.stop).toHaveBeenCalledTimes(1);
+		expect(ui.start).toHaveBeenCalledTimes(1);
+		expect(ui.requestRender).toHaveBeenCalledWith(true);
+		expect(showError).toHaveBeenCalledTimes(1);
+		expect(showError.mock.calls[0]?.[0]).toMatch(/Failed to suspend/);
+		expect(showStatus).not.toHaveBeenCalled();
+	});
+});

From f31b060e150ee7d4cbfcd13e55e4e48c8b4a349e Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 09:24:20 +0000
Subject: [PATCH 148/181] fix(tui): applied follow-up slash commands

Route follow-up shortcut submissions through the builtin slash-command dispatcher before queueing them as deferred prompts.

Added regression coverage for /goal set submitted through InputController.handleFollowUp while a stream is active.

Fixes #2038
---
 packages/coding-agent/CHANGELOG.md            |  4 ++++
 .../src/modes/controllers/input-controller.ts | 12 +++++++++-
 .../test/input-controller-skill-queue.test.ts | 22 ++++++++++++++++++-
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0243ed841..7a3932802 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed follow-up shortcut submission of builtin slash commands so `/goal set ...` applies goal mode instead of queueing as plain text.
+
 ## [15.10.1] - 2026-06-07
 
 ### Added
diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index da83ea41b..d1e0ef6ad 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -589,7 +589,7 @@ export class InputController {
 
 	/** Send editor text as a follow-up message (queued behind current stream). */
 	async handleFollowUp(): Promise<void> {
-		const text = this.ctx.editor.getText().trim();
+		let text = this.ctx.editor.getText().trim();
 		if (!text) return;
 
 		// Compaction first: while compacting, free text gets queued via
@@ -603,6 +603,16 @@ export class InputController {
 			return;
 		}
 
+		const slashResult = await executeBuiltinSlashCommand(text, {
+			ctx: this.ctx,
+		});
+		if (slashResult === true) {
+			return;
+		}
+		if (typeof slashResult === "string") {
+			text = slashResult;
+		}
+
 		// Skill commands invoke through the custom-message path regardless of
 		// which keybinding submitted them. Enter routes them as `steer`;
 		// Ctrl+Enter (this handler) routes them as `followUp`.
diff --git a/packages/coding-agent/test/input-controller-skill-queue.test.ts b/packages/coding-agent/test/input-controller-skill-queue.test.ts
index 93dbba9ef..36154cc31 100644
--- a/packages/coding-agent/test/input-controller-skill-queue.test.ts
+++ b/packages/coding-agent/test/input-controller-skill-queue.test.ts
@@ -71,6 +71,8 @@ function createStubInputControllerContext(opts: { skillCommands: Map<string, str
 	// Annotate parameters so `mock.calls[N]` is typed as a tuple (not `[]`) and
 	// `message` carries required skill prompt details for assertion below.
 	const promptCustomMessage = vi.fn(async (_message: { details: SkillPromptDetails }, _options?: unknown) => {});
+	const prompt = vi.fn(async (_text: string, _options?: unknown) => {});
+	const handleGoalModeCommand = vi.fn(async (_rest?: string) => {});
 	const updatePendingMessagesDisplay = vi.fn();
 	const requestRender = vi.fn();
 	const showError = vi.fn();
@@ -86,9 +88,12 @@ function createStubInputControllerContext(opts: { skillCommands: Map<string, str
 			isEvalRunning: false,
 			extensionRunner: undefined,
 			enqueueCustomMessageDisplay,
+			prompt,
 			promptCustomMessage,
 		},
 		showError,
+		handleGoalModeCommand,
+		goalModeEnabled: false,
 		updatePendingMessagesDisplay,
 		// Defaults that InputController touches on submit but don't matter here.
 		isBashMode: false,
@@ -101,7 +106,7 @@ function createStubInputControllerContext(opts: { skillCommands: Map<string, str
 		withLocalSubmission: async (_text: string, fn: () => unknown) => fn(),
 	} as unknown as InteractiveModeContext;
 
-	return { ctx, editor, enqueueCustomMessageDisplay, promptCustomMessage };
+	return { ctx, editor, enqueueCustomMessageDisplay, prompt, promptCustomMessage, handleGoalModeCommand };
 }
 
 describe("InputController #invokeSkillCommand (E1-E3)", () => {
@@ -166,6 +171,21 @@ describe("InputController #invokeSkillCommand (E1-E3)", () => {
 		expect(messageArg.details.__pendingDisplayTag).toBe("sk-test-0");
 	});
 
+	it("E2b: streaming follow-up applies builtin slash commands instead of queueing them", async () => {
+		const { ctx, editor, prompt, handleGoalModeCommand } = createStubInputControllerContext({
+			skillCommands,
+			isStreaming: true,
+		});
+
+		const controller = new InputController(ctx);
+		editor.setText("/goal set Ship the release");
+		await controller.handleFollowUp();
+
+		expect(handleGoalModeCommand).toHaveBeenCalledWith("set Ship the release");
+		expect(prompt).not.toHaveBeenCalled();
+		expect(editor.getText()).toBe("");
+	});
+
 	it("E3: not streaming -> enqueueCustomMessageDisplay NOT called and tag absent", async () => {
 		const { ctx, editor, enqueueCustomMessageDisplay, promptCustomMessage } = createStubInputControllerContext({
 			skillCommands,

From d5183a14f9b4a5655a94169a41c162027041d43b Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 10:41:31 +0000
Subject: [PATCH 149/181] fix(tui): honored kitty reply when DA1 sentinel
 arrives first

The kitty keyboard progressive-enhancement probe sends `CSI ? u CSI c`
and used the DA1 reply as a fallback sentinel: if no kitty reply arrived
the modifyOtherKeys fallback was engaged. The kitty handler then refused
to enable kitty whenever modifyOtherKeysActive was already true, which
silently dropped the reply on terminals that answer DA1 before CSI ? u
(Superset / xterm-on-Electron). The protocol never enabled, so
Shift+Enter was delivered as a bare \r and the input box submitted.

Make the kitty reply authoritative regardless of ordering: drop the
`!modifyOtherKeysActive` guard, and if the premature DA1 already engaged
the modifyOtherKeys fallback, send `CSI > 4 ; 0 m` to disable it before
pushing the kitty stack frame. Kitty is strictly preferred (per the
existing #3259-fallback comment), so this is a clean cutover.

Add a regression test that drives a real ProcessTerminal through the
existing render harness across three orderings: kitty-then-DA1 (control),
DA1-then-kitty (#2042 regression), and DA1-only (modifyOtherKeys
fallback stays).

Fixes #2042
---
 packages/tui/CHANGELOG.md                     |  4 ++
 packages/tui/src/terminal.ts                  | 11 ++-
 .../test/kitty-keyboard-da1-ordering.test.ts  | 69 +++++++++++++++++++
 3 files changed, 83 insertions(+), 1 deletion(-)
 create mode 100644 packages/tui/test/kitty-keyboard-da1-ordering.test.ts

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 56903eddc..b871a7aa9 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed the kitty keyboard progressive-enhancement probe to honor the `CSI ? <flags> u` reply even when the terminal answers the DA1 sentinel first. Previously the kitty reply was discarded once the DA1-driven `modifyOtherKeys` fallback engaged, so terminals like Superset/xterm-on-Electron stayed on the fallback and delivered Shift+Enter as a bare `\r` ([#2042](https://github.com/can1357/oh-my-pi/issues/2042)).
+
 ## [15.10.1] - 2026-06-07
 ### Breaking Changes
 
diff --git a/packages/tui/src/terminal.ts b/packages/tui/src/terminal.ts
index 2069f6370..5dd0314f0 100644
--- a/packages/tui/src/terminal.ts
+++ b/packages/tui/src/terminal.ts
@@ -504,11 +504,20 @@ export class ProcessTerminal implements Terminal {
 			}
 
 			const match = sequence.match(kittyResponsePattern);
-			if (match && !this.#modifyOtherKeysActive) {
+			if (match) {
 				if (this.#modifyOtherKeysTimeout) {
 					clearTimeout(this.#modifyOtherKeysTimeout);
 					this.#modifyOtherKeysTimeout = undefined;
 				}
+				// A DA1 sentinel that beat the kitty reply may have already
+				// engaged the modifyOtherKeys fallback (terminals such as
+				// Superset/xterm-on-Electron answer DA1 before `\x1b[?u`).
+				// Kitty is strictly preferred — undo the fallback so the two
+				// modes do not stack. See #2042.
+				if (this.#modifyOtherKeysActive) {
+					this.#safeWrite("\x1b[>4;0m");
+					this.#modifyOtherKeysActive = false;
+				}
 				// Any reply to `\x1b[?u` means the terminal speaks the kitty keyboard
 				// protocol. The reported flag value is the *current* stack-top — fresh
 				// terminals report 0 — so support is implied by the reply itself, not by
diff --git a/packages/tui/test/kitty-keyboard-da1-ordering.test.ts b/packages/tui/test/kitty-keyboard-da1-ordering.test.ts
new file mode 100644
index 000000000..0baf01f3c
--- /dev/null
+++ b/packages/tui/test/kitty-keyboard-da1-ordering.test.ts
@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+	createProcessTerminalRenderHarness,
+	type ProcessTerminalRenderHarness,
+} from "./process-terminal-render-harness";
+
+// Progressive-enhancement probe ordering contract. omp sends `CSI ? u \\ CSI c`
+// at startup: the kitty reply (`CSI ? <flags> u`) authoritatively says the
+// terminal speaks the kitty keyboard protocol; the DA1 reply (`CSI ? ... c`)
+// is only a sentinel that guarantees a reply even from terminals that ignore
+// `CSI ? u`. Some terminals (Superset / xterm-on-Electron) answer DA1 first;
+// the kitty reply must still be honored regardless of ordering.
+describe("ProcessTerminal kitty keyboard progressive-enhancement ordering", () => {
+	let harness: ProcessTerminalRenderHarness | undefined;
+
+	afterEach(() => {
+		harness?.dispose();
+		harness = undefined;
+	});
+
+	it("enables kitty when the kitty reply arrives before the DA1 sentinel", async () => {
+		harness = createProcessTerminalRenderHarness(100, 30);
+		await harness.settle();
+		expect(harness.writes.join("")).toContain("\x1b[?u\x1b[c");
+		harness.writes.length = 0;
+
+		await harness.feed("\x1b[?0u", "\x1b[?1;2c");
+
+		const out = harness.writes.join("");
+		expect(harness.terminal.kittyProtocolActive).toBe(true);
+		expect(out).toContain("\x1b[>1u");
+		expect(out).not.toContain("\x1b[>4;2m");
+	});
+
+	it("enables kitty when the DA1 sentinel arrives before the kitty reply (#2042)", async () => {
+		harness = createProcessTerminalRenderHarness(100, 30);
+		await harness.settle();
+		harness.writes.length = 0;
+
+		// Superset/Electron-xterm answers DA1 before `CSI ? u`. The kitty reply
+		// must override the premature modifyOtherKeys fallback.
+		await harness.feed("\x1b[?1;2c", "\x1b[?0u");
+
+		const out = harness.writes.join("");
+		expect(harness.terminal.kittyProtocolActive).toBe(true);
+		expect(out).toContain("\x1b[>1u");
+		const enableIdx = out.indexOf("\x1b[>4;2m");
+		const disableIdx = out.indexOf("\x1b[>4;0m");
+		const kittyIdx = out.indexOf("\x1b[>1u");
+		expect(enableIdx).toBeGreaterThanOrEqual(0);
+		expect(disableIdx).toBeGreaterThan(enableIdx);
+		expect(kittyIdx).toBeGreaterThan(enableIdx);
+	});
+
+	it("keeps the modifyOtherKeys fallback when only DA1 ever replies", async () => {
+		harness = createProcessTerminalRenderHarness(100, 30);
+		await harness.settle();
+		harness.writes.length = 0;
+
+		// Terminals that ignore `CSI ? u` answer DA1 only — modifyOtherKeys is
+		// the right answer there.
+		await harness.feed("\x1b[?1;2c");
+
+		const out = harness.writes.join("");
+		expect(harness.terminal.kittyProtocolActive).toBe(false);
+		expect(out).toContain("\x1b[>4;2m");
+		expect(out).not.toContain("\x1b[>1u");
+	});
+});

From c3c4c2749dd24a10c403f5921ec0e3c8c6038a9d Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 11:14:02 +0000
Subject: [PATCH 150/181] fix(tui): bounded oversized render rows

Bounded the raw row span passed into TUI line fitting so ANSI-heavy subagent output cannot grow terminal write buffers independently of viewport width.

Added issue #2045 regression coverage for pathological zero-width ANSI rows.

Fixes #2045
---
 packages/tui/CHANGELOG.md                  |  4 ++
 packages/tui/src/tui.ts                    | 19 ++++-
 packages/tui/test/issue-2045-repro.test.ts | 83 ++++++++++++++++++++++
 3 files changed, 105 insertions(+), 1 deletion(-)
 create mode 100644 packages/tui/test/issue-2045-repro.test.ts

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 56903eddc..d0f709ad0 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Bounded TUI line fitting for oversized raw rows so ANSI-heavy subagent output cannot grow render buffers independently of the viewport ([#2045](https://github.com/can1357/oh-my-pi/issues/2045)).
+
 ## [15.10.1] - 2026-06-07
 ### Breaking Changes
 
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index e71ee6818..0d6fe6aee 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -47,6 +47,12 @@ const SEGMENT_RESET = "\x1b[0m";
 const LINE_TERMINATOR = "\x1b[0m\x1b]8;;\x07";
 const ERASE_LINE = "\x1b[2K";
 const ERASE_TO_END_OF_LINE = "\x1b[K";
+// Bound the raw code-unit span handed to native width/truncation. A terminal
+// row can only display `width` cells, so oversized component rows should not
+// force proportional JS/native copies while deciding what the viewport shows.
+const LINE_FIT_MIN_SOURCE_CODE_UNITS = 4096;
+const LINE_FIT_MAX_SOURCE_CODE_UNITS = 65536;
+const LINE_FIT_SOURCE_WIDTH_MULTIPLIER = 64;
 // Hide the hardware cursor before each paint/move write. Ghostty-style bar
 // cursors can otherwise leave visual afterimages while the TUI repaints the
 // row under a visible cursor. Paint writes also disable terminal autowrap:
@@ -2478,7 +2484,8 @@ export class TUI extends Container {
 		if (TERMINAL.isImageLine(raw)) {
 			return { raw, width, line: raw };
 		}
-		const normalized = normalizeTerminalOutput(raw);
+		const source = this.#lineFitSource(raw, width);
+		const normalized = normalizeTerminalOutput(source);
 		const asciiWidth = this.#ansiAsciiLineWidth(normalized, width);
 		if ((asciiWidth ?? visibleWidth(normalized)) <= width) {
 			return { raw, width, line: normalized };
@@ -2487,6 +2494,16 @@ export class TUI extends Container {
 		return { raw, width, line };
 	}
 
+	#lineFitSource(raw: string, width: number): string {
+		const safeWidth = Number.isFinite(width) ? Math.max(1, Math.trunc(width)) : 1;
+		const maxSourceLength = Math.min(
+			LINE_FIT_MAX_SOURCE_CODE_UNITS,
+			Math.max(LINE_FIT_MIN_SOURCE_CODE_UNITS, safeWidth * LINE_FIT_SOURCE_WIDTH_MULTIPLIER),
+		);
+		if (raw.length <= maxSourceLength) return raw;
+		return raw.slice(0, maxSourceLength) + SEGMENT_RESET;
+	}
+
 	#ansiAsciiLineWidth(line: string, maxWidth: number): number | undefined {
 		let col = 0;
 		for (let i = 0; i < line.length; ) {
diff --git a/packages/tui/test/issue-2045-repro.test.ts b/packages/tui/test/issue-2045-repro.test.ts
new file mode 100644
index 000000000..bf44eefcf
--- /dev/null
+++ b/packages/tui/test/issue-2045-repro.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from "bun:test";
+import { type Component, TUI } from "@oh-my-pi/pi-tui";
+import type { Terminal, TerminalAppearance } from "@oh-my-pi/pi-tui/terminal";
+
+class CaptureTerminal implements Terminal {
+	writes: string[] = [];
+	#columns: number;
+	#rows: number;
+
+	constructor(columns = 80, rows = 4) {
+		this.#columns = columns;
+		this.#rows = rows;
+	}
+
+	get columns(): number {
+		return this.#columns;
+	}
+
+	get rows(): number {
+		return this.#rows;
+	}
+
+	get kittyProtocolActive(): boolean {
+		return false;
+	}
+
+	get appearance(): TerminalAppearance | undefined {
+		return undefined;
+	}
+
+	start(): void {}
+	stop(): void {}
+	async drainInput(): Promise<void> {}
+	write(data: string): void {
+		this.writes.push(data);
+	}
+	moveBy(): void {}
+	hideCursor(): void {}
+	showCursor(): void {}
+	clearLine(): void {}
+	clearFromCursor(): void {}
+	clearScreen(): void {}
+	setTitle(): void {}
+	setProgress(): void {}
+	onAppearanceChange(): void {}
+}
+
+class RawLinesComponent implements Component {
+	#lines: string[];
+
+	constructor(lines: string[]) {
+		this.#lines = lines;
+	}
+
+	invalidate(): void {}
+
+	render(): string[] {
+		return this.#lines;
+	}
+}
+
+async function settle(): Promise<void> {
+	await Bun.sleep(0);
+}
+
+describe("issue #2045: renderer bounds oversized rows", () => {
+	it("clips pathological zero-width ANSI rows before building terminal writes", async () => {
+		const term = new CaptureTerminal(80, 4);
+		const tui = new TUI(term);
+		const line = `${"\x1b[31m".repeat(20_000)}payload`;
+
+		tui.addChild(new RawLinesComponent([line]));
+		try {
+			tui.start();
+			await settle();
+		} finally {
+			tui.stop();
+		}
+
+		const renderedBytes = term.writes.join("").length;
+		expect(renderedBytes).toBeLessThan(12_000);
+	});
+});

From ee7e1e3ae33cb3cd4e733ff75d25544047f0ebb2 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 11:14:29 +0000
Subject: [PATCH 151/181] fix(tui): preserved tmux viewport on offscreen shrink

Skipped repainting tmux panes when an offscreen shrink leaves the visible tail unchanged, and added regression coverage for the no-content-bytes contract.

Fixes #2046
---
 packages/tui/CHANGELOG.md                    |  2 ++
 packages/tui/src/tui.ts                      | 15 ++++++++-
 packages/tui/test/render-regressions.test.ts | 34 ++++++++++++++++++++
 3 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 56903eddc..3274aa894 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -29,6 +29,8 @@
 
 ### Fixed
 
+- Fixed tmux offscreen-shrink frames to skip repainting when the visible tail is unchanged, avoiding intermittent blank/refresh flashes in pane terminals ([#2046](https://github.com/can1357/oh-my-pi/issues/2046)).
+
 - Fixed `Loader` text updates to skip identical messages and preserve the rendered `Text` cache instead of invalidating it every timer tick.
 
 - Fixed fullscreen overlay alt-frame rendering to reuse the current line-preparation path instead of calling removed fitting helpers.
diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index e71ee6818..68dfc9d8e 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -2049,7 +2049,9 @@ export class TUI extends Container {
 			newLines.length < this.#previousLines.length &&
 			naturalViewportTop !== prevViewportTop
 		) {
-			return { kind: "viewportRepaint" };
+			return this.#bottomAnchoredViewportUnchanged(newLines, height)
+				? { kind: "deferredMutation" }
+				: { kind: "viewportRepaint" };
 		}
 
 		// Direct-input shrink can also move the natural viewport upward even when
@@ -2437,6 +2439,17 @@ export class TUI extends Container {
 		return { kind: "liveRegionPinned", appendFrom, appendTo, renderViewportTop };
 	}
 
+	#bottomAnchoredViewportUnchanged(newLines: string[], height: number): boolean {
+		const previousViewportTop = Math.max(0, this.#previousLines.length - height);
+		const newViewportTop = Math.max(0, newLines.length - height);
+		for (let row = 0; row < height; row++) {
+			if ((newLines[newViewportTop + row] ?? "") !== (this.#previousLines[previousViewportTop + row] ?? "")) {
+				return false;
+			}
+		}
+		return true;
+	}
+
 	#planDeferredTailRepaint(newLines: string[], prevViewportTop: number, height: number): RenderIntent {
 		const row = prevViewportTop + height - 1;
 		if (row < 0 || row >= this.#previousLines.length || newLines.length !== this.#previousLines.length) {
diff --git a/packages/tui/test/render-regressions.test.ts b/packages/tui/test/render-regressions.test.ts
index 79e6385f7..29ff72ace 100644
--- a/packages/tui/test/render-regressions.test.ts
+++ b/packages/tui/test/render-regressions.test.ts
@@ -1469,6 +1469,40 @@ describe("TUI terminal-state regressions", () => {
 			});
 		});
 
+		it("tmux: offscreen shrink preserving the visible tail emits no repaint bytes", async () => {
+			await withEnvPatch({ TMUX: "1", STY: undefined, ZELLIJ: undefined }, async () => {
+				const term = new UnknownViewportTerminal(40, 4, 10_000);
+				const tui = new TUI(term);
+				const component = new MutableLinesComponent([
+					"old-0",
+					"remove-me",
+					"old-2",
+					"old-3",
+					"tail-0",
+					"tail-1",
+					"tail-2",
+					"tail-3",
+				]);
+				tui.addChild(component);
+
+				try {
+					tui.start();
+					await settle(term);
+					expect(visible(term)).toEqual(["tail-0", "tail-1", "tail-2", "tail-3"]);
+
+					const writes = captureWrites(term);
+					component.setLines(["old-0", "old-2", "old-3", "tail-0", "tail-1", "tail-2", "tail-3"]);
+					tui.requestRender();
+					await settle(term);
+
+					expect(visible(term)).toEqual(["tail-0", "tail-1", "tail-2", "tail-3"]);
+					expect(writes).toEqual([]);
+				} finally {
+					tui.stop();
+				}
+			});
+		});
+
 		// Root cause family: the dirty/replay machinery assumes native scrollback
 		// can be cleared and rebuilt, which is never true inside a multiplexer —
 		// tmux owns pane history, reflows it on resize itself, and a "replay" can

From 2b29fef9efe1a63dbee29f5a4e9cadcdcb706bc0 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 11:18:56 +0000
Subject: [PATCH 152/181] docs(tui): moved #2046 changelog entry under
 Unreleased

---
 packages/tui/CHANGELOG.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 3274aa894..b53b77b51 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed tmux offscreen-shrink frames to skip repainting when the visible tail is unchanged, avoiding intermittent blank/refresh flashes in pane terminals ([#2046](https://github.com/can1357/oh-my-pi/issues/2046)).
+
 ## [15.10.1] - 2026-06-07
 ### Breaking Changes
 
@@ -29,8 +33,6 @@
 
 ### Fixed
 
-- Fixed tmux offscreen-shrink frames to skip repainting when the visible tail is unchanged, avoiding intermittent blank/refresh flashes in pane terminals ([#2046](https://github.com/can1357/oh-my-pi/issues/2046)).
-
 - Fixed `Loader` text updates to skip identical messages and preserve the rendered `Text` cache instead of invalidating it every timer tick.
 
 - Fixed fullscreen overlay alt-frame rendering to reuse the current line-preparation path instead of calling removed fitting helpers.

From d78e29e17ada7ce6f04c69f5097389cc2512a30b Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 11:20:41 +0000
Subject: [PATCH 153/181] fix(tui): preserved text after long ansi prefixes

Scanned oversized render rows by ANSI sequence so bounded line fitting skips leading zero-width control spans without dropping subsequent visible cells.

Extended issue #2045 regression coverage to assert visible text survives long SGR and OSC hyperlink prefixes.
---
 packages/tui/src/tui.ts                    | 50 +++++++++++++++++++++-
 packages/tui/test/issue-2045-repro.test.ts | 25 +++++++++--
 2 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index 0d6fe6aee..d6104e2e5 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -2501,7 +2501,55 @@ export class TUI extends Container {
 			Math.max(LINE_FIT_MIN_SOURCE_CODE_UNITS, safeWidth * LINE_FIT_SOURCE_WIDTH_MULTIPLIER),
 		);
 		if (raw.length <= maxSourceLength) return raw;
-		return raw.slice(0, maxSourceLength) + SEGMENT_RESET;
+
+		const chunks: string[] = [];
+		let emitted = 0;
+		for (let i = 0; i < raw.length && emitted < maxSourceLength; ) {
+			if (raw.charCodeAt(i) === 0x1b) {
+				const end = this.#ansiSequenceEnd(raw, i);
+				if (end === -1) break;
+				const sequenceLength = end - i;
+				if (emitted > 0 && sequenceLength <= maxSourceLength - emitted) {
+					chunks.push(raw.slice(i, end));
+					emitted += sequenceLength;
+				}
+				i = end;
+				continue;
+			}
+
+			const start = i;
+			const end = Math.min(raw.length, start + maxSourceLength - emitted);
+			while (i < end && raw.charCodeAt(i) !== 0x1b) i++;
+			if (i === start) break;
+			chunks.push(raw.slice(start, i));
+			emitted += i - start;
+		}
+
+		return chunks.join("") + SEGMENT_RESET;
+	}
+
+	#ansiSequenceEnd(line: string, start: number): number {
+		const next = line.charCodeAt(start + 1);
+		if (next === 0x5b) {
+			let i = start + 2;
+			while (i < line.length) {
+				const final = line.charCodeAt(i);
+				if (final >= 0x40 && final <= 0x7e) return i + 1;
+				i++;
+			}
+			return -1;
+		}
+		if (next === 0x5d) {
+			let i = start + 2;
+			while (i < line.length) {
+				const osc = line.charCodeAt(i);
+				if (osc === 0x07) return i + 1;
+				if (osc === 0x1b && line.charCodeAt(i + 1) === 0x5c) return i + 2;
+				i++;
+			}
+			return -1;
+		}
+		return start + 2 <= line.length ? start + 2 : -1;
 	}
 
 	#ansiAsciiLineWidth(line: string, maxWidth: number): number | undefined {
diff --git a/packages/tui/test/issue-2045-repro.test.ts b/packages/tui/test/issue-2045-repro.test.ts
index bf44eefcf..04cf54912 100644
--- a/packages/tui/test/issue-2045-repro.test.ts
+++ b/packages/tui/test/issue-2045-repro.test.ts
@@ -64,7 +64,7 @@ async function settle(): Promise<void> {
 }
 
 describe("issue #2045: renderer bounds oversized rows", () => {
-	it("clips pathological zero-width ANSI rows before building terminal writes", async () => {
+	it("preserves visible text after pathological zero-width ANSI prefixes", async () => {
 		const term = new CaptureTerminal(80, 4);
 		const tui = new TUI(term);
 		const line = `${"\x1b[31m".repeat(20_000)}payload`;
@@ -77,7 +77,26 @@ describe("issue #2045: renderer bounds oversized rows", () => {
 			tui.stop();
 		}
 
-		const renderedBytes = term.writes.join("").length;
-		expect(renderedBytes).toBeLessThan(12_000);
+		const rendered = term.writes.join("");
+		expect(rendered).toContain("payload");
+		expect(rendered.length).toBeLessThan(12_000);
+	});
+
+	it("preserves visible text after oversized OSC hyperlink prefixes", async () => {
+		const term = new CaptureTerminal(80, 4);
+		const tui = new TUI(term);
+		const line = `\x1b]8;;https://example.com/${"a".repeat(70_000)}\x07link-label\x1b]8;;\x07`;
+
+		tui.addChild(new RawLinesComponent([line]));
+		try {
+			tui.start();
+			await settle();
+		} finally {
+			tui.stop();
+		}
+
+		const rendered = term.writes.join("");
+		expect(rendered).toContain("link-label");
+		expect(rendered.length).toBeLessThan(12_000);
 	});
 });

From 4053fadf71949e2a65825b66f39cd49839f742c2 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 11:26:09 +0000
Subject: [PATCH 154/181] fix(tui): preserved osc66 spans in bounded fitting

Detected OSC 66 text-sizing sequences in the bounded line fitter and included them whole so payloads (e.g. Markdown headings) are not skipped as zero-width.

Added a regression assertion that OSC 66 visible cells survive the bound when the row begins with the sized span.
---
 packages/tui/src/tui.ts                    | 21 +++++++++++++++++++++
 packages/tui/test/issue-2045-repro.test.ts | 18 ++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/packages/tui/src/tui.ts b/packages/tui/src/tui.ts
index d6104e2e5..71055e653 100644
--- a/packages/tui/src/tui.ts
+++ b/packages/tui/src/tui.ts
@@ -2509,6 +2509,16 @@ export class TUI extends Container {
 				const end = this.#ansiSequenceEnd(raw, i);
 				if (end === -1) break;
 				const sequenceLength = end - i;
+				if (this.#ansiSequenceHasVisiblePayload(raw, i)) {
+					// OSC 66 text-sizing spans carry their visible cells inside the
+					// OSC payload. Always include the whole sequence — splitting it
+					// would corrupt the terminator — and let the next loop iteration
+					// terminate on the budget overflow.
+					chunks.push(raw.slice(i, end));
+					emitted += sequenceLength;
+					i = end;
+					continue;
+				}
 				if (emitted > 0 && sequenceLength <= maxSourceLength - emitted) {
 					chunks.push(raw.slice(i, end));
 					emitted += sequenceLength;
@@ -2552,6 +2562,17 @@ export class TUI extends Container {
 		return start + 2 <= line.length ? start + 2 : -1;
 	}
 
+	#ansiSequenceHasVisiblePayload(line: string, start: number): boolean {
+		// OSC 66 (`\x1b]66;META;TEXT\x1b\\`) carries its visible cells inside the
+		// payload, mirroring the special case in {@link #ansiAsciiLineWidth}.
+		return (
+			line.charCodeAt(start + 1) === 0x5d &&
+			line.charCodeAt(start + 2) === 0x36 &&
+			line.charCodeAt(start + 3) === 0x36 &&
+			line.charCodeAt(start + 4) === 0x3b
+		);
+	}
+
 	#ansiAsciiLineWidth(line: string, maxWidth: number): number | undefined {
 		let col = 0;
 		for (let i = 0; i < line.length; ) {
diff --git a/packages/tui/test/issue-2045-repro.test.ts b/packages/tui/test/issue-2045-repro.test.ts
index 04cf54912..1b839ae4a 100644
--- a/packages/tui/test/issue-2045-repro.test.ts
+++ b/packages/tui/test/issue-2045-repro.test.ts
@@ -99,4 +99,22 @@ describe("issue #2045: renderer bounds oversized rows", () => {
 		expect(rendered).toContain("link-label");
 		expect(rendered.length).toBeLessThan(12_000);
 	});
+
+	it("preserves OSC 66 text-sizing payloads at the start of long rows", async () => {
+		const term = new CaptureTerminal(80, 4);
+		const tui = new TUI(term);
+		const visibleText = "H".repeat(70);
+		const line = `\x1b]66;s=1;${visibleText}\x1b\\${"\x1b[31m".repeat(20_000)}`;
+
+		tui.addChild(new RawLinesComponent([line]));
+		try {
+			tui.start();
+			await settle();
+		} finally {
+			tui.stop();
+		}
+
+		const rendered = term.writes.join("");
+		expect(rendered).toContain(visibleText);
+	});
 });

From 10fd51425bc679b2bd2390dd67fa731ab4875275 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 11:37:13 +0000
Subject: [PATCH 155/181] fix(ai): parsed minimax think tags across providers

Promoted MiniMax model/provider detection into stream markup healing so OpenCode Zen MiniMax streams use the existing thinking-tag parser instead of exposing raw tags.

Added a regression test for OpenCode Zen minimax-m3 chunks split across <think> boundaries.

Fixes #2049
---
 .../ai/src/providers/openai-completions.ts    |  5 +--
 .../ai/src/utils/stream-markup-healing.ts     |  7 +++-
 .../ai/test/stream-markup-healing.test.ts     | 34 +++++++++++++++++++
 3 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/packages/ai/src/providers/openai-completions.ts b/packages/ai/src/providers/openai-completions.ts
index e58e4b8fd..4816e492b 100644
--- a/packages/ai/src/providers/openai-completions.ts
+++ b/packages/ai/src/providers/openai-completions.ts
@@ -537,7 +537,6 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 			}
 			stream.push({ type: "start", partial: output });
 
-			const parseMiniMaxThinkTags = model.provider === "minimax-code" || model.provider === "minimax-code-cn";
 			// Some OpenAI-compatible DeepSeek hosts (including NVIDIA NIM and DeepSeek's
 			// native API) leak chat-template tool-call markers in `delta.content` even
 			// though tool calls are also surfaced structurally. Strip the leaked markers
@@ -678,9 +677,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				}
 			};
 
-			const streamMarkupHealingPattern = getStreamMarkupHealingPattern(model.provider, model.id, {
-				parseThinkingTags: parseMiniMaxThinkTags,
-			});
+			const streamMarkupHealingPattern = getStreamMarkupHealingPattern(model.provider, model.id);
 			const streamMarkupHealing = streamMarkupHealingPattern
 				? new StreamMarkupHealing({ pattern: streamMarkupHealingPattern })
 				: undefined;
diff --git a/packages/ai/src/utils/stream-markup-healing.ts b/packages/ai/src/utils/stream-markup-healing.ts
index 6cb1c6531..7114b9019 100644
--- a/packages/ai/src/utils/stream-markup-healing.ts
+++ b/packages/ai/src/utils/stream-markup-healing.ts
@@ -600,12 +600,17 @@ export function modelMayLeakDsmlToolCalls(provider: string, modelId: string): bo
 	);
 }
 
+/** Cheap model/provider gate for MiniMax plain thinking tag leaks. */
+export function modelMayLeakThinkingTags(provider: string, modelId: string): boolean {
+	return /minimax/i.test(provider) || /minimax/i.test(modelId);
+}
+
 export function getStreamMarkupHealingPattern(
 	provider: string,
 	modelId: string,
 	options?: { readonly parseThinkingTags?: boolean },
 ): StreamMarkupHealingPattern | undefined {
-	if (options?.parseThinkingTags) return "thinking";
+	if (options?.parseThinkingTags || modelMayLeakThinkingTags(provider, modelId)) return "thinking";
 	if (modelMayLeakKimiToolCalls(provider, modelId)) return "kimi";
 	if (modelMayLeakDsmlToolCalls(provider, modelId)) return "dsml";
 	return undefined;
diff --git a/packages/ai/test/stream-markup-healing.test.ts b/packages/ai/test/stream-markup-healing.test.ts
index 935eb9481..79b6b74b5 100644
--- a/packages/ai/test/stream-markup-healing.test.ts
+++ b/packages/ai/test/stream-markup-healing.test.ts
@@ -148,6 +148,7 @@ describe("StreamMarkupHealing pattern selection", () => {
 		expect(getStreamMarkupHealingPattern("minimax-code", "MiniMax-M2.5", { parseThinkingTags: true })).toBe(
 			"thinking",
 		);
+		expect(getStreamMarkupHealingPattern("opencode-zen", "minimax-m3")).toBe("thinking");
 		expect(getStreamMarkupHealingPattern("nanogpt", "deepseek/deepseek-v4-pro")).toBe("dsml");
 		expect(getStreamMarkupHealingPattern("ollama-cloud", "gpt-oss:120b")).toBeUndefined();
 		expect(getStreamMarkupHealingPattern("openai", "deepseek-v4-pro")).toBeUndefined();
@@ -582,6 +583,39 @@ describe("Ollama provider DSML envelope healing", () => {
 	});
 });
 
+describe("OpenAI completions MiniMax thinking healing", () => {
+	it("parses OpenCode Zen MiniMax think tags into a thinking block", async () => {
+		const model: Model<"openai-completions"> = {
+			id: "minimax-m3",
+			name: "MiniMax M3",
+			api: "openai-completions",
+			provider: "opencode-zen",
+			baseUrl: "https://opencode.ai/zen/v1",
+			reasoning: true,
+			input: ["text"],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: 200_000,
+			maxTokens: 8_192,
+		};
+		global.fetch = mockFetch([
+			chunk(model.id, { content: "visible <thin" }),
+			chunk(model.id, { content: "k>hidden reasoning</think" }),
+			chunk(model.id, { content: ">" }),
+			chunk(model.id, { content: " answer" }),
+			chunk(model.id, {}, "stop"),
+			"[DONE]",
+		]);
+
+		const result = await streamOpenAICompletions(model, baseContext(), { apiKey: "test-key" }).result();
+
+		expect(result.content).toEqual([
+			{ type: "text", text: "visible " },
+			{ type: "thinking", thinking: "hidden reasoning", thinkingSignature: undefined },
+			{ type: "text", text: " answer" },
+		]);
+	});
+});
+
 describe("OpenAI completions provider DSML envelope healing", () => {
 	it("heals the envelope into a structured tool call and suppresses leaked text", async () => {
 		const model: Model<"openai-completions"> = {

From be71d53842e7c7273288d4308eaa6ffdcc5ffe0f Mon Sep 17 00:00:00 2001
From: DarkPhilosophy <19309990+DarkPhilosophy@users.noreply.github.com>
Date: Sun, 7 Jun 2026 15:08:47 +0300
Subject: [PATCH 156/181] fix(coding-agent): optimize orphaned tool-use stop
 guard

---
 packages/coding-agent/CHANGELOG.md            |  4 ++
 .../coding-agent/src/session/agent-session.ts | 42 +++++++++++--------
 2 files changed, 28 insertions(+), 18 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0243ed841..321d5264a 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed Anthropic empty `toolUse` stops without tool calls corrupting session history by retrying them and removing orphaned turns even at the retry cap.
+
 ## [15.10.1] - 2026-06-07
 
 ### Added
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index f4558c2fd..deb63f71a 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -283,6 +283,11 @@ export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
 export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
 
 const EMPTY_STOP_MAX_RETRIES = 3;
+const NON_WHITESPACE_RE = /\S/;
+
+function hasNonWhitespace(value: string): boolean {
+	return NON_WHITESPACE_RE.test(value);
+}
 
 export interface AsyncJobSnapshot {
 	running: AsyncJobSnapshotItem[];
@@ -6558,25 +6563,26 @@ export class AgentSession {
 	}
 
 	#isEmptyAssistantStop(assistantMessage: AssistantMessage): boolean {
-		const { stopReason } = assistantMessage;
-		if (stopReason !== "stop" && stopReason !== "toolUse") return false;
-
-		// Single pass over content; the three flags cover every emptiness rule below.
-		let hasText = false;
-		let hasThinking = false;
-		let hasToolCall = false;
-		for (const content of assistantMessage.content) {
-			if (content.type === "text") hasText ||= content.text.trim().length > 0;
-			else if (content.type === "thinking") hasThinking ||= content.thinking.trim().length > 0;
-			else if (content.type === "toolCall") hasToolCall = true;
+		switch (assistantMessage.stopReason) {
+			case "stop":
+				for (const content of assistantMessage.content) {
+					if (content.type === "toolCall") return false;
+					if (content.type === "text" && hasNonWhitespace(content.text)) return false;
+					if (content.type === "thinking" && hasNonWhitespace(content.thinking)) return false;
+				}
+				return true;
+			case "toolUse":
+				// An orphaned toolUse stop (no tool_use block) corrupts Anthropic history:
+				// a later tool_result has nothing to anchor to. Thinking alone cannot anchor
+				// a tool_result, so it does not rescue a toolUse stop here.
+				for (const content of assistantMessage.content) {
+					if (content.type === "toolCall") return false;
+					if (content.type === "text" && hasNonWhitespace(content.text)) return false;
+				}
+				return true;
+			default:
+				return false;
 		}
-
-		// An orphaned toolUse stop (no tool_use block) corrupts Anthropic history:
-		// a later tool_result has nothing to anchor to. Thinking alone cannot anchor
-		// a tool_result, so it does not rescue a toolUse stop here.
-		if (stopReason === "toolUse") return !hasText && !hasToolCall;
-		// A plain stop is empty only when it carries no usable content at all.
-		return !hasText && !hasThinking && !hasToolCall;
 	}
 
 	#emptyStopRetryReminder(): string {

From 43477234e2eb93f80ea6f0f27e8a200552c92ef8 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 12:10:52 +0000
Subject: [PATCH 157/181] fix(tui): handle kitty osc 5522 dot-listing paste
 responses

Kitty implements the OSC 5522 "list available MIME types" reply by
sending one DATA packet whose `mime` field decodes to the literal `.`
and whose payload carries the available types as a whitespace-separated
list (see `fulfill_read_request` in kovidgoyal/kitty:kitty/clipboard.py
when the requested MIME is `TARGETS_MIME = '.'`). The 5522-mode
ancillary spec (rockorager.dev/misc/bracketed-paste-mime) instead
encodes each available type as its own DATA packet with an empty
payload.

The TUI's EnhancedPasteController only honored the ancillary form. When
Kitty delivered the dot-listing form for a plain-text paste, the parser
pushed `.` into the candidate list, `choosePasteMime(["."])` matched
nothing, and the editor surfaced "Clipboard paste has no supported text
or image data" instead of inserting the text.

Decode the payload as a UTF-8 whitespace-separated MIME list when the
DATA packet's mime is the dot sentinel, then fall through to the
existing per-type behavior. Add two regression tests covering the
single-type and multi-type Kitty payload shapes.

Fixes #2051
---
 packages/coding-agent/CHANGELOG.md            |  4 ++
 .../coding-agent/src/utils/enhanced-paste.ts  | 20 ++++++
 .../test/utils/enhanced-paste.test.ts         | 71 +++++++++++++++++++
 3 files changed, 95 insertions(+)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0243ed841..018c3d42f 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed Kitty OSC 5522 paste rejecting plain text as "no supported text or image data": the listing parser now decodes the `mime="."` DATA payload (whitespace-separated MIME list) Kitty actually sends, in addition to the per-type DATA packets described by the ancillary 5522-mode spec ([#2051](https://github.com/can1357/oh-my-pi/issues/2051))
+
 ## [15.10.1] - 2026-06-07
 
 ### Added
diff --git a/packages/coding-agent/src/utils/enhanced-paste.ts b/packages/coding-agent/src/utils/enhanced-paste.ts
index 16fdf416e..3a3e2a564 100644
--- a/packages/coding-agent/src/utils/enhanced-paste.ts
+++ b/packages/coding-agent/src/utils/enhanced-paste.ts
@@ -7,6 +7,8 @@ const PASTE_EVENT_NAME_BASE64 = Buffer.from("Paste event", "utf8").toString("bas
 
 const IMAGE_MIME_PRIORITY = ["image/png", "image/jpeg", "image/webp", "image/gif"] as const;
 const TEXT_MIME_TYPE = "text/plain";
+/** Kitty's "give me the list of available MIME types" sentinel — see `TARGETS_MIME` in `kitty/clipboard.py`. */
+const MIME_LISTING_TARGET = ".";
 
 type PasteReadKind = "image" | "text";
 
@@ -144,6 +146,24 @@ export class EnhancedPasteController {
 		if (!mimeType) return;
 
 		if (state.phase === "listing") {
+			// Kitty (as of writing) implements the "list available MIME types"
+			// response shape by sending a single DATA packet with `mime="."` and
+			// the available types packed into the payload as a whitespace-
+			// separated list (see `fulfill_read_request` in
+			// kovidgoyal/kitty:kitty/clipboard.py). The 5522-mode ancillary
+			// spec instead encodes each type as its own DATA packet with an
+			// empty payload. Support both — fall through to the per-packet
+			// form when the dot sentinel has no payload, or when the packet
+			// already names a concrete MIME type.
+			if (mimeType === MIME_LISTING_TARGET) {
+				if (!packet.payload) return;
+				const listing = decodeBase64Utf8(packet.payload);
+				if (!listing) return;
+				for (const candidate of listing.split(/\s+/)) {
+					if (candidate && candidate !== MIME_LISTING_TARGET) state.mimes.push(candidate);
+				}
+				return;
+			}
 			state.mimes.push(mimeType);
 			return;
 		}
diff --git a/packages/coding-agent/test/utils/enhanced-paste.test.ts b/packages/coding-agent/test/utils/enhanced-paste.test.ts
index d319c1362..f1d71d76d 100644
--- a/packages/coding-agent/test/utils/enhanced-paste.test.ts
+++ b/packages/coding-agent/test/utils/enhanced-paste.test.ts
@@ -106,4 +106,75 @@ describe("EnhancedPasteController", () => {
 
 		expect(statuses).toEqual(["Clipboard paste has no supported text or image data"]);
 	});
+
+	it("decodes Kitty's dot-listing DATA payload to discover plain-text and request it", () => {
+		const writes: string[] = [];
+		const pastedText: string[] = [];
+		const controller = new EnhancedPasteController({
+			write: data => writes.push(data),
+			pasteText: text => pastedText.push(text),
+			pasteImage: () => {
+				throw new Error("unexpected image paste");
+			},
+			showStatus: message => pastedText.push(`status:${message}`),
+		});
+
+		const dot = Buffer.from(".", "utf8").toString("base64");
+		const textMime = Buffer.from("text/plain", "utf8").toString("base64");
+		const password = Buffer.from("secret-token-123", "utf8").toString("base64");
+		const pasteEventName = Buffer.from("Paste event", "utf8").toString("base64");
+
+		// Kitty bundles the available MIME types into a single DATA packet
+		// whose `mime` field is the literal `.` and whose payload carries a
+		// whitespace-separated, base64-encoded list (e.g. "text/plain\n").
+		controller.handleInput(packet(`type=read:status=OK:pw=${password}`));
+		controller.handleInput(
+			packet(
+				`type=read:status=DATA:mime=${dot}:pw=${password}`,
+				Buffer.from("text/plain\n", "utf8").toString("base64"),
+			),
+		);
+		controller.handleInput(packet(`type=read:status=DONE:pw=${password}`));
+
+		expect(writes.at(-1)).toBe(
+			`${OSC}type=read:mime=${textMime}:pw=${password}:name=${pasteEventName}${ST}`,
+		);
+
+		controller.handleInput(packet("type=read:status=OK"));
+		controller.handleInput(
+			packet(`type=read:status=DATA:mime=${textMime}`, Buffer.from("hello", "utf8").toString("base64")),
+		);
+		controller.handleInput(
+			packet(`type=read:status=DATA:mime=${textMime}`, Buffer.from(" world", "utf8").toString("base64")),
+		);
+		controller.handleInput(packet("type=read:status=DONE"));
+
+		expect(pastedText).toEqual(["hello world"]);
+	});
+
+	it("prefers images when Kitty's dot-listing payload advertises multiple MIME types", () => {
+		const writes: string[] = [];
+		const controller = new EnhancedPasteController({
+			write: data => writes.push(data),
+			pasteText: () => {
+				throw new Error("unexpected text paste");
+			},
+			pasteImage: () => {},
+			showStatus: () => {},
+		});
+
+		const dot = Buffer.from(".", "utf8").toString("base64");
+		const imageMime = Buffer.from("image/png", "utf8").toString("base64");
+
+		controller.handleInput(packet("type=read:status=OK"));
+		controller.handleInput(
+			packet(
+				`type=read:status=DATA:mime=${dot}`,
+				Buffer.from("text/plain image/png text/html\n", "utf8").toString("base64"),
+			),
+		);
+		controller.handleInput(packet("type=read:status=DONE"));
+
+		expect(writes.at(-1)).toContain(`mime=${imageMime}`);
+	});
 });

From 29ca22e9c7602a9e16003dcc45ab1e0a555e163b Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 12:34:33 +0000
Subject: [PATCH 158/181] fix(ai): deduplicated replayed tool call ids

Added a transform pass that rewrites repeated tool call ids and the immediately paired tool result so provider replay keeps a one-result-per-call contract. Covered missing-result synthesis and generated-id collision regressions.\n\nFixes #2055
---
 packages/ai/CHANGELOG.md                      |   1 +
 .../ai/src/providers/transform-messages.ts    | 273 +++++++++++-------
 .../ai/test/duplicate-tool-results.test.ts    |  97 +++++++
 3 files changed, 264 insertions(+), 107 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 344d76b9a..cdff682db 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -21,6 +21,7 @@
 
 ### Fixed
 
+- Fixed duplicate upstream `tool_call_id` values collapsing distinct tool calls during message transformation, preserving one call/result pairing per emitted tool call before provider replay. ([#2055](https://github.com/can1357/oh-my-pi/issues/2055))
 - Fixed streaming auth retries to handle `401` and usage-limit errors before replay-unsafe content is emitted, including failures surfaced only via `errorStatus`
 - Fixed tool argument validation to coerce singleton non-string values into arrays when the schema expects an array, preventing Anthropic-compatible models that emit `todo.ops` as an object from getting stuck in repeated validation-error loops. ([#2026](https://github.com/can1357/oh-my-pi/issues/2026))
 - Fixed streaming retries to buffer and suppress partial `start` events from failed auth attempts so only clean retried events are delivered
diff --git a/packages/ai/src/providers/transform-messages.ts b/packages/ai/src/providers/transform-messages.ts
index 7959f7828..dc2691467 100644
--- a/packages/ai/src/providers/transform-messages.ts
+++ b/packages/ai/src/providers/transform-messages.ts
@@ -17,6 +17,61 @@ const enum ToolCallStatus {
 	Aborted = 2,
 }
 
+type PendingToolResultRewrite = { originalId: string; replacementId: string } | undefined;
+
+function deduplicateToolCallIds(messages: Message[]): Message[] {
+	const seenToolCallIds = new Map<string, number>();
+	let pendingToolResultRewrites: PendingToolResultRewrite[] = [];
+	let pendingToolResultRewriteIndex = 0;
+
+	return messages.map(msg => {
+		if (msg.role === "toolResult") {
+			const rewrite = pendingToolResultRewrites[pendingToolResultRewriteIndex];
+			pendingToolResultRewriteIndex += 1;
+			if (pendingToolResultRewriteIndex >= pendingToolResultRewrites.length) {
+				pendingToolResultRewrites = [];
+				pendingToolResultRewriteIndex = 0;
+			}
+			if (rewrite && msg.toolCallId === rewrite.originalId) return { ...msg, toolCallId: rewrite.replacementId };
+			return msg;
+		}
+
+		pendingToolResultRewrites = [];
+		pendingToolResultRewriteIndex = 0;
+		if (msg.role !== "assistant") return msg;
+
+		let contentChanged = false;
+		const nextToolResultRewrites: PendingToolResultRewrite[] = [];
+		const content = msg.content.map(block => {
+			if (block.type !== "toolCall") return block;
+
+			const previousCount = seenToolCallIds.get(block.id) ?? 0;
+			if (previousCount === 0) {
+				seenToolCallIds.set(block.id, 1);
+				nextToolResultRewrites.push(undefined);
+				return block;
+			}
+
+			let duplicateIndex = previousCount;
+			let replacementId = `${block.id}_dup${duplicateIndex}`;
+			while (seenToolCallIds.has(replacementId)) {
+				duplicateIndex += 1;
+				replacementId = `${block.id}_dup${duplicateIndex}`;
+			}
+			seenToolCallIds.set(block.id, duplicateIndex + 1);
+			seenToolCallIds.set(replacementId, 1);
+			nextToolResultRewrites.push({ originalId: block.id, replacementId });
+			contentChanged = true;
+			return { ...block, id: replacementId };
+		});
+
+		if (!contentChanged) return msg;
+		pendingToolResultRewrites = nextToolResultRewrites;
+		pendingToolResultRewriteIndex = 0;
+		return { ...msg, content };
+	});
+}
+
 function shouldDropTruncatedThinkingOnlyAssistant(msg: AssistantMessage): boolean {
 	const isTruncatedStop = msg.stopReason === "length" || msg.stopReason === "error" || msg.stopReason === "aborted";
 	return isTruncatedStop && !msg.content.some(block => block.type === "toolCall" || block.type === "text");
@@ -52,116 +107,120 @@ export function transformMessages<TApi extends Api>(
 
 	const latestSurvivingAssistantIndex = getLatestSurvivingAssistantIndex(messages);
 	// First pass: transform messages (thinking blocks, tool call ID normalization)
-	const transformed = messages.map((msg, index) => {
-		// User and developer messages pass through unchanged
-		if (msg.role === "user" || msg.role === "developer") {
-			return msg;
-		}
+	const transformed = deduplicateToolCallIds(
+		messages.map((msg, index) => {
+			// User and developer messages pass through unchanged
+			if (msg.role === "user" || msg.role === "developer") {
+				return msg;
+			}
 
-		// Handle toolResult messages - normalize toolCallId if we have a mapping
-		if (msg.role === "toolResult") {
-			const normalizedId = toolCallIdMap.get(msg.toolCallId);
-			if (normalizedId && normalizedId !== msg.toolCallId) {
-				return { ...msg, toolCallId: normalizedId };
+			// Handle toolResult messages - normalize toolCallId if we have a mapping
+			if (msg.role === "toolResult") {
+				const normalizedId = toolCallIdMap.get(msg.toolCallId);
+				if (normalizedId && normalizedId !== msg.toolCallId) {
+					return { ...msg, toolCallId: normalizedId };
+				}
+				return msg;
+			}
+
+			// Assistant messages need transformation check
+			if (msg.role === "assistant") {
+				const assistantMsg = msg as AssistantMessage;
+				const isSameModel =
+					assistantMsg.provider === model.provider &&
+					assistantMsg.api === model.api &&
+					assistantMsg.model === model.id;
+
+				const mustPreserveLatestAnthropicThinking =
+					index === latestSurvivingAssistantIndex &&
+					model.api === "anthropic-messages" &&
+					assistantMsg.api === "anthropic-messages";
+				// Aborted/errored messages may have partially-streamed thinking signatures.
+				// A partial signature is invalid and will be rejected by the API, so we must
+				// strip signatures from thinking blocks in these messages.
+				//
+				// Abandoned tool-use turns get the same treatment once they are no longer
+				// the latest assistant message. When a turn carries toolCall blocks but did
+				// NOT request tool execution (stopReason !== "toolUse" — e.g.
+				// adaptive-thinking Opus emitting tool calls and then ending the turn on
+				// `end_turn`/`stop`), the agent loop pairs those calls with placeholder
+				// tool_results to keep the tool_use/tool_result contract valid. Historical
+				// abandoned turns cannot safely replay their end_turn-bound signatures in
+				// that continuation, so stripping downgrades them to plain text downstream.
+				// Latest abandoned turns are exempt because Anthropic requires thinking
+				// blocks from its most recent response to remain byte-for-byte unmodified.
+				const invalidStopReason = assistantMsg.stopReason === "aborted" || assistantMsg.stopReason === "error";
+				const abandonedToolUse =
+					!invalidStopReason &&
+					assistantMsg.stopReason !== "toolUse" &&
+					assistantMsg.content.some(b => b.type === "toolCall");
+				const hasInvalidSignatures = invalidStopReason || abandonedToolUse;
+
+				const transformedContent = assistantMsg.content.flatMap(block => {
+					if (block.type === "thinking") {
+						// Strip untrustworthy signatures so the encoder can downgrade to text.
+						const sanitized =
+							hasInvalidSignatures && block.thinkingSignature
+								? { ...block, thinkingSignature: undefined }
+								: block;
+						if (mustPreserveLatestAnthropicThinking) return abandonedToolUse ? block : sanitized;
+						// For same model: keep thinking blocks with signatures (needed for replay)
+						// even if the thinking text is empty (OpenAI encrypted reasoning)
+						if (isSameModel && sanitized.thinkingSignature) return sanitized;
+						// Skip empty thinking blocks, convert others to plain text
+						if (!sanitized.thinking || sanitized.thinking.trim() === "") return [];
+						if (isSameModel) return sanitized;
+						return {
+							type: "text" as const,
+							text: sanitized.thinking,
+						};
+					}
+
+					if (block.type === "redactedThinking") {
+						if (mustPreserveLatestAnthropicThinking) return block;
+						if (isSameModel) return block;
+						return [];
+					}
+
+					if (block.type === "text") {
+						if (isSameModel) return block;
+						return {
+							type: "text" as const,
+							text: block.text,
+						};
+					}
+
+					if (block.type === "toolCall") {
+						const toolCall = block as ToolCall;
+						let normalizedToolCall: ToolCall = toolCall;
+
+						if (!isSameModel && toolCall.thoughtSignature) {
+							normalizedToolCall = { ...toolCall };
+							delete (normalizedToolCall as { thoughtSignature?: string }).thoughtSignature;
+						}
+
+						if (!isSameModel && normalizeToolCallId) {
+							const normalizedId = normalizeToolCallId(toolCall.id, model, assistantMsg);
+							if (normalizedId !== toolCall.id) {
+								toolCallIdMap.set(toolCall.id, normalizedId);
+								normalizedToolCall = { ...normalizedToolCall, id: normalizedId };
+							}
+						}
+
+						return normalizedToolCall;
+					}
+
+					return block;
+				});
+
+				return {
+					...assistantMsg,
+					content: transformedContent,
+				};
 			}
 			return msg;
-		}
-
-		// Assistant messages need transformation check
-		if (msg.role === "assistant") {
-			const assistantMsg = msg as AssistantMessage;
-			const isSameModel =
-				assistantMsg.provider === model.provider &&
-				assistantMsg.api === model.api &&
-				assistantMsg.model === model.id;
-
-			const mustPreserveLatestAnthropicThinking =
-				index === latestSurvivingAssistantIndex &&
-				model.api === "anthropic-messages" &&
-				assistantMsg.api === "anthropic-messages";
-			// Aborted/errored messages may have partially-streamed thinking signatures.
-			// A partial signature is invalid and will be rejected by the API, so we must
-			// strip signatures from thinking blocks in these messages.
-			//
-			// Abandoned tool-use turns get the same treatment once they are no longer
-			// the latest assistant message. When a turn carries toolCall blocks but did
-			// NOT request tool execution (stopReason !== "toolUse" — e.g.
-			// adaptive-thinking Opus emitting tool calls and then ending the turn on
-			// `end_turn`/`stop`), the agent loop pairs those calls with placeholder
-			// tool_results to keep the tool_use/tool_result contract valid. Historical
-			// abandoned turns cannot safely replay their end_turn-bound signatures in
-			// that continuation, so stripping downgrades them to plain text downstream.
-			// Latest abandoned turns are exempt because Anthropic requires thinking
-			// blocks from its most recent response to remain byte-for-byte unmodified.
-			const invalidStopReason = assistantMsg.stopReason === "aborted" || assistantMsg.stopReason === "error";
-			const abandonedToolUse =
-				!invalidStopReason &&
-				assistantMsg.stopReason !== "toolUse" &&
-				assistantMsg.content.some(b => b.type === "toolCall");
-			const hasInvalidSignatures = invalidStopReason || abandonedToolUse;
-
-			const transformedContent = assistantMsg.content.flatMap(block => {
-				if (block.type === "thinking") {
-					// Strip untrustworthy signatures so the encoder can downgrade to text.
-					const sanitized =
-						hasInvalidSignatures && block.thinkingSignature ? { ...block, thinkingSignature: undefined } : block;
-					if (mustPreserveLatestAnthropicThinking) return abandonedToolUse ? block : sanitized;
-					// For same model: keep thinking blocks with signatures (needed for replay)
-					// even if the thinking text is empty (OpenAI encrypted reasoning)
-					if (isSameModel && sanitized.thinkingSignature) return sanitized;
-					// Skip empty thinking blocks, convert others to plain text
-					if (!sanitized.thinking || sanitized.thinking.trim() === "") return [];
-					if (isSameModel) return sanitized;
-					return {
-						type: "text" as const,
-						text: sanitized.thinking,
-					};
-				}
-
-				if (block.type === "redactedThinking") {
-					if (mustPreserveLatestAnthropicThinking) return block;
-					if (isSameModel) return block;
-					return [];
-				}
-
-				if (block.type === "text") {
-					if (isSameModel) return block;
-					return {
-						type: "text" as const,
-						text: block.text,
-					};
-				}
-
-				if (block.type === "toolCall") {
-					const toolCall = block as ToolCall;
-					let normalizedToolCall: ToolCall = toolCall;
-
-					if (!isSameModel && toolCall.thoughtSignature) {
-						normalizedToolCall = { ...toolCall };
-						delete (normalizedToolCall as { thoughtSignature?: string }).thoughtSignature;
-					}
-
-					if (!isSameModel && normalizeToolCallId) {
-						const normalizedId = normalizeToolCallId(toolCall.id, model, assistantMsg);
-						if (normalizedId !== toolCall.id) {
-							toolCallIdMap.set(toolCall.id, normalizedId);
-							normalizedToolCall = { ...normalizedToolCall, id: normalizedId };
-						}
-					}
-
-					return normalizedToolCall;
-				}
-
-				return block;
-			});
-
-			return {
-				...assistantMsg,
-				content: transformedContent,
-			};
-		}
-		return msg;
-	});
+		}),
+	);
 	const realToolResultsById = new Map<string, ToolResultMessage>();
 	for (const msg of transformed) {
 		if (msg.role === "toolResult" && !realToolResultsById.has(msg.toolCallId)) {
diff --git a/packages/ai/test/duplicate-tool-results.test.ts b/packages/ai/test/duplicate-tool-results.test.ts
index 1be33d66b..2c196d9c7 100644
--- a/packages/ai/test/duplicate-tool-results.test.ts
+++ b/packages/ai/test/duplicate-tool-results.test.ts
@@ -32,6 +32,43 @@ describe("Duplicate Tool Results Regression", () => {
 		reasoning: true,
 	};
 
+	const makeEvalAssistantMessage = (id: string, timestamp: number): AssistantMessage => ({
+		role: "assistant",
+		content: [{ type: "toolCall", id, name: "eval", arguments: {} }],
+		api: "anthropic-messages",
+		provider: "anthropic",
+		model: "claude-3-5-sonnet-20241022",
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason: "toolUse",
+		timestamp,
+	});
+
+	const makeEvalToolResult = (id: string, text: string, timestamp: number): ToolResultMessage => ({
+		role: "toolResult",
+		toolCallId: id,
+		toolName: "eval",
+		content: [{ type: "text", text }],
+		isError: false,
+		timestamp,
+	});
+
+	const getAssistantToolIds = (messages: Message[]): string[] =>
+		messages.flatMap(message =>
+			message.role === "assistant"
+				? message.content.filter((block): block is ToolCall => block.type === "toolCall").map(block => block.id)
+				: [],
+		);
+
+	const getToolResults = (messages: Message[]): ToolResultMessage[] =>
+		messages.filter((message): message is ToolResultMessage => message.role === "toolResult");
+
 	it("should not duplicate tool results for errored messages when results already exist", () => {
 		const toolCallId = "toolu_019xqMTvqWZiTDy8XxmjxrTo";
 
@@ -316,6 +353,66 @@ describe("Duplicate Tool Results Regression", () => {
 		expect(result2.length).toBe(1);
 		expect(result3.length).toBe(1);
 	});
+
+	it("deduplicates repeated tool call ids and preserves call/result pairing", () => {
+		const duplicateId = "functions.eval:301";
+		const distinctId = "functions.eval:302";
+
+		const messages: Message[] = [
+			makeEvalAssistantMessage(duplicateId, 1),
+			makeEvalToolResult(duplicateId, "first", 2),
+			makeEvalAssistantMessage(duplicateId, 3),
+			makeEvalToolResult(duplicateId, "second", 4),
+			makeEvalAssistantMessage(duplicateId, 5),
+			makeEvalAssistantMessage(distinctId, 6),
+			makeEvalToolResult(distinctId, "third", 7),
+		];
+
+		const transformed = transformMessages(messages, model);
+		const assistantToolIds = getAssistantToolIds(transformed);
+		const toolResults = getToolResults(transformed);
+
+		expect(assistantToolIds).toEqual([duplicateId, `${duplicateId}_dup1`, `${duplicateId}_dup2`, distinctId]);
+		expect(toolResults.map(result => result.toolCallId)).toEqual([
+			duplicateId,
+			`${duplicateId}_dup1`,
+			`${duplicateId}_dup2`,
+			distinctId,
+		]);
+		expect(toolResults.find(result => result.toolCallId === `${duplicateId}_dup1`)?.content).toEqual([
+			{ type: "text", text: "second" },
+		]);
+		expect(toolResults.find(result => result.toolCallId === `${duplicateId}_dup2`)?.content).toEqual([
+			{ type: "text", text: "No result provided" },
+		]);
+	});
+
+	it("deduplicates repeated ids without colliding with existing generated-looking ids", () => {
+		const duplicateId = "functions.eval:301";
+		const generatedLookingId = `${duplicateId}_dup1`;
+		const messages: Message[] = [
+			makeEvalAssistantMessage(duplicateId, 1),
+			makeEvalToolResult(duplicateId, "first", 2),
+			makeEvalAssistantMessage(generatedLookingId, 3),
+			makeEvalToolResult(generatedLookingId, "already-used", 4),
+			makeEvalAssistantMessage(duplicateId, 5),
+			makeEvalToolResult(duplicateId, "second", 6),
+		];
+
+		const transformed = transformMessages(messages, model);
+		const assistantToolIds = getAssistantToolIds(transformed);
+		const toolResults = getToolResults(transformed);
+
+		expect(assistantToolIds).toEqual([duplicateId, generatedLookingId, `${duplicateId}_dup2`]);
+		expect(toolResults.map(result => result.toolCallId)).toEqual([
+			duplicateId,
+			generatedLookingId,
+			`${duplicateId}_dup2`,
+		]);
+		expect(toolResults.find(result => result.toolCallId === `${duplicateId}_dup2`)?.content).toEqual([
+			{ type: "text", text: "second" },
+		]);
+	});
 });
 
 /**

From 56240e527d7aec96a8de53b44ddcd205d7bd2171 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 12:36:58 +0000
Subject: [PATCH 159/181] fix(agent): retried generic upstream gateway failures

Classified generic upstream gateway failures as transient so configured session auto-retry starts when auth-gateway surfaces upstream_error: Upstream request failed. Added a focused AgentSession regression covering the retry event and recovery path.\n\nFixes #2056
---
 packages/coding-agent/CHANGELOG.md            |  2 +
 .../coding-agent/src/session/agent-session.ts |  7 ++-
 .../test/agent-session-retry-cap.test.ts      | 56 +++++++++++++++++++
 3 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0243ed841..cf6b9ecde 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -50,6 +50,8 @@
 
 ### Fixed
 
+- Fixed session auto-retry for generic `upstream_error: Upstream request failed` gateway failures.
+
 - Fixed inline `find` and `search` result blocks to align with grouped `read` output and render their success headers with the normal tool-title color instead of accent blue.
 
 - Fixed the working-status shimmer to opt into the loader's 30fps animated-message repaint path while keeping both the status spinner and pending bash/eval tool spinners on their normal 80 ms glyph cadence.
diff --git a/packages/coding-agent/src/session/agent-session.ts b/packages/coding-agent/src/session/agent-session.ts
index b53734c6f..62c443541 100644
--- a/packages/coding-agent/src/session/agent-session.ts
+++ b/packages/coding-agent/src/session/agent-session.ts
@@ -7874,11 +7874,12 @@ export class AgentSession {
 	#isTransientTransportErrorMessage(errorMessage: string): boolean {
 		// Match: overloaded_error, provider returned error, rate limit, 429, 500, 502, 503, 504,
 		// service unavailable, provider-suggested retry, network/connection/socket errors, fetch failed,
-		// terminated, retry delay exceeded, Bun HTTP/2 stream resets (RST_STREAM / REFUSED_STREAM /
-		// ENHANCE_YOUR_CALM, surfaced verbatim from src/http/h2_client/dispatch.zig)
+		// gateway upstream failures, terminated, retry delay exceeded, Bun HTTP/2 stream resets
+		// (RST_STREAM / REFUSED_STREAM / ENHANCE_YOUR_CALM, surfaced verbatim from
+		// src/http/h2_client/dispatch.zig)
 		return (
 			isUnexpectedSocketCloseMessage(errorMessage) ||
-			/overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|retry your request|network.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall|no error details in response|HTTP2(?:StreamReset|RefusedStream|EnhanceYourCalm)/i.test(
+			/overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|retry your request|network.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|upstream.?request.?failed|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall|no error details in response|HTTP2(?:StreamReset|RefusedStream|EnhanceYourCalm)/i.test(
 				errorMessage,
 			)
 		);
diff --git a/packages/coding-agent/test/agent-session-retry-cap.test.ts b/packages/coding-agent/test/agent-session-retry-cap.test.ts
index f7b04d26c..465b80e13 100644
--- a/packages/coding-agent/test/agent-session-retry-cap.test.ts
+++ b/packages/coding-agent/test/agent-session-retry-cap.test.ts
@@ -336,4 +336,60 @@ describe("AgentSession retry delay cap", () => {
 		const last = lastAssistant(session);
 		expect(last.stopReason).toBe("stop");
 	});
+	it("retries generic upstream_error gateway failures", async () => {
+		const model = getBundledModel("anthropic", "claude-sonnet-4-5");
+		if (!model) {
+			throw new Error("Expected bundled Anthropic test model to exist");
+		}
+
+		const mock = createMockModel({
+			responses: [
+				{ throw: "upstream_error: Upstream request failed" },
+				{ content: ["recovered after generic gateway upstream error"] },
+			],
+		});
+		const agent = new Agent({
+			getApiKey: provider => `${provider}-test-key`,
+			initialState: {
+				model,
+				systemPrompt: ["Test"],
+				tools: [],
+				messages: [],
+			},
+			streamFn: mock.stream,
+		});
+
+		const settings = Settings.isolated({
+			"compaction.enabled": false,
+			"retry.baseDelayMs": 5,
+			"retry.maxDelayMs": 5_000,
+			"retry.maxRetries": 1,
+		});
+		settings.setModelRole("default", `${model.provider}/${model.id}`);
+
+		session = new AgentSession({
+			agent,
+			sessionManager: SessionManager.inMemory(),
+			settings,
+			modelRegistry,
+		});
+
+		vi.spyOn(scheduler, "wait").mockResolvedValue(undefined);
+		const retryStartEvents: AutoRetryStartEvent[] = [];
+		const retryEndEvents: AutoRetryEndEvent[] = [];
+		session.subscribe(event => {
+			if (event.type === "auto_retry_start") retryStartEvents.push(event);
+			if (event.type === "auto_retry_end") retryEndEvents.push(event);
+		});
+
+		await session.prompt("Trigger generic upstream_error");
+		await session.waitForIdle();
+
+		expect(retryStartEvents).toHaveLength(1);
+		expect(retryEndEvents).toHaveLength(1);
+		expect(retryEndEvents[0]).toMatchObject({ success: true, attempt: 1 });
+		const last = lastAssistant(session);
+		expect(last.stopReason).toBe("stop");
+		expect(last.content).toContainEqual({ type: "text", text: "recovered after generic gateway upstream error" });
+	});
 });

From f04cca885eeb62904470ac6fbe0ae56f1166e7dc Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 12:38:35 +0000
Subject: [PATCH 160/181] fix(ai): preserved delayed duplicate tool outputs

Kept duplicate tool-call result rewrites pending by original id across user/developer gaps so delayed real outputs are paired with the rewritten call instead of being dropped.\n\nFixes #2055
---
 .../ai/src/providers/transform-messages.ts    | 36 ++++++++++---------
 .../ai/test/duplicate-tool-results.test.ts    | 21 +++++++++++
 2 files changed, 40 insertions(+), 17 deletions(-)

diff --git a/packages/ai/src/providers/transform-messages.ts b/packages/ai/src/providers/transform-messages.ts
index dc2691467..5c9b56f07 100644
--- a/packages/ai/src/providers/transform-messages.ts
+++ b/packages/ai/src/providers/transform-messages.ts
@@ -17,38 +17,42 @@ const enum ToolCallStatus {
 	Aborted = 2,
 }
 
-type PendingToolResultRewrite = { originalId: string; replacementId: string } | undefined;
+type PendingToolResultRewrite = { replacementId: string } | undefined;
 
 function deduplicateToolCallIds(messages: Message[]): Message[] {
 	const seenToolCallIds = new Map<string, number>();
-	let pendingToolResultRewrites: PendingToolResultRewrite[] = [];
-	let pendingToolResultRewriteIndex = 0;
+	const pendingToolResultRewrites = new Map<string, PendingToolResultRewrite[]>();
 
 	return messages.map(msg => {
 		if (msg.role === "toolResult") {
-			const rewrite = pendingToolResultRewrites[pendingToolResultRewriteIndex];
-			pendingToolResultRewriteIndex += 1;
-			if (pendingToolResultRewriteIndex >= pendingToolResultRewrites.length) {
-				pendingToolResultRewrites = [];
-				pendingToolResultRewriteIndex = 0;
-			}
-			if (rewrite && msg.toolCallId === rewrite.originalId) return { ...msg, toolCallId: rewrite.replacementId };
+			const rewrites = pendingToolResultRewrites.get(msg.toolCallId);
+			if (!rewrites || rewrites.length === 0) return msg;
+
+			const rewrite = rewrites.shift();
+			if (rewrites.length === 0) pendingToolResultRewrites.delete(msg.toolCallId);
+			if (rewrite) return { ...msg, toolCallId: rewrite.replacementId };
 			return msg;
 		}
 
-		pendingToolResultRewrites = [];
-		pendingToolResultRewriteIndex = 0;
 		if (msg.role !== "assistant") return msg;
 
+		const enqueueToolResultRewrite = (id: string, rewrite: PendingToolResultRewrite): void => {
+			const rewrites = pendingToolResultRewrites.get(id);
+			if (rewrites) {
+				rewrites.push(rewrite);
+				return;
+			}
+			pendingToolResultRewrites.set(id, [rewrite]);
+		};
+
 		let contentChanged = false;
-		const nextToolResultRewrites: PendingToolResultRewrite[] = [];
 		const content = msg.content.map(block => {
 			if (block.type !== "toolCall") return block;
 
 			const previousCount = seenToolCallIds.get(block.id) ?? 0;
 			if (previousCount === 0) {
 				seenToolCallIds.set(block.id, 1);
-				nextToolResultRewrites.push(undefined);
+				enqueueToolResultRewrite(block.id, undefined);
 				return block;
 			}
 
@@ -60,14 +64,12 @@ function deduplicateToolCallIds(messages: Message[]): Message[] {
 			}
 			seenToolCallIds.set(block.id, duplicateIndex + 1);
 			seenToolCallIds.set(replacementId, 1);
-			nextToolResultRewrites.push({ originalId: block.id, replacementId });
+			enqueueToolResultRewrite(block.id, { replacementId });
 			contentChanged = true;
 			return { ...block, id: replacementId };
 		});
 
 		if (!contentChanged) return msg;
-		pendingToolResultRewrites = nextToolResultRewrites;
-		pendingToolResultRewriteIndex = 0;
 		return { ...msg, content };
 	});
 }
diff --git a/packages/ai/test/duplicate-tool-results.test.ts b/packages/ai/test/duplicate-tool-results.test.ts
index 2c196d9c7..9507c624e 100644
--- a/packages/ai/test/duplicate-tool-results.test.ts
+++ b/packages/ai/test/duplicate-tool-results.test.ts
@@ -413,6 +413,27 @@ describe("Duplicate Tool Results Regression", () => {
 			{ type: "text", text: "second" },
 		]);
 	});
+
+	it("preserves delayed duplicate tool results across message gaps", () => {
+		const duplicateId = "functions.eval:301";
+		const developerMessage: DeveloperMessage = { role: "developer", content: "handoff summary", timestamp: 4 };
+		const messages: Message[] = [
+			makeEvalAssistantMessage(duplicateId, 1),
+			makeEvalToolResult(duplicateId, "first", 2),
+			makeEvalAssistantMessage(duplicateId, 3),
+			developerMessage,
+			makeEvalToolResult(duplicateId, "second", 5),
+		];
+
+		const transformed = transformMessages(messages, model);
+		const toolResults = getToolResults(transformed);
+
+		expect(getAssistantToolIds(transformed)).toEqual([duplicateId, `${duplicateId}_dup1`]);
+		expect(toolResults.map(result => result.toolCallId)).toEqual([duplicateId, `${duplicateId}_dup1`]);
+		expect(toolResults.find(result => result.toolCallId === `${duplicateId}_dup1`)?.content).toEqual([
+			{ type: "text", text: "second" },
+		]);
+	});
 });
 
 /**

From ce69ec0e92a57b70cc71ed7f17846d07d351b9b0 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 12:45:31 +0000
Subject: [PATCH 161/181] fix(ai): scoped duplicate tool rewrites to live call
 window

Dropped carried-over pending tool-result rewrites the first time a new assistant turn re-emits the same upstream id, so the later real result pairs with the latest call instead of being stolen by an orphan _dup id.\n\nFixes #2055
---
 .../ai/src/providers/transform-messages.ts    | 16 ++++++++++
 .../ai/test/duplicate-tool-results.test.ts    | 29 +++++++++++++++++++
 2 files changed, 45 insertions(+)

diff --git a/packages/ai/src/providers/transform-messages.ts b/packages/ai/src/providers/transform-messages.ts
index 5c9b56f07..6ae6a2225 100644
--- a/packages/ai/src/providers/transform-messages.ts
+++ b/packages/ai/src/providers/transform-messages.ts
@@ -45,10 +45,26 @@ function deduplicateToolCallIds(messages: Message[]): Message[] {
 			pendingToolResultRewrites.set(id, [rewrite]);
 		};
 
+		// Ids this turn has already touched; used to scope the "drop carried-over
+		// pending rewrites" semantics to the FIRST occurrence per turn so multiple
+		// blocks of the same id within one turn still accumulate as duplicates.
+		const idsTouchedInTurn = new Set<string>();
 		let contentChanged = false;
 		const content = msg.content.map(block => {
 			if (block.type !== "toolCall") return block;
 
+			// Drop any pending rewrites carried over from a prior assistant turn
+			// for this id on its first appearance this turn. When a later turn
+			// re-emits the same id, the older duplicate call's expected result
+			// never landed in time — the second pass synthesizes
+			// "No result provided" for it, and the upcoming real result(id) must
+			// route to one of THIS turn's calls. Without this guard the older
+			// `_dup` id would steal the next result.
+			if (!idsTouchedInTurn.has(block.id)) {
+				pendingToolResultRewrites.delete(block.id);
+				idsTouchedInTurn.add(block.id);
+			}
+
 			const previousCount = seenToolCallIds.get(block.id) ?? 0;
 			if (previousCount === 0) {
 				seenToolCallIds.set(block.id, 1);
diff --git a/packages/ai/test/duplicate-tool-results.test.ts b/packages/ai/test/duplicate-tool-results.test.ts
index 9507c624e..bac919989 100644
--- a/packages/ai/test/duplicate-tool-results.test.ts
+++ b/packages/ai/test/duplicate-tool-results.test.ts
@@ -434,6 +434,35 @@ describe("Duplicate Tool Results Regression", () => {
 			{ type: "text", text: "second" },
 		]);
 	});
+
+	it("routes the late result to the most recent duplicate call when a new turn re-emits the id across a gap", () => {
+		const duplicateId = "functions.eval:301";
+		const developerMessage: DeveloperMessage = { role: "developer", content: "handoff summary", timestamp: 4 };
+		const messages: Message[] = [
+			makeEvalAssistantMessage(duplicateId, 1),
+			makeEvalToolResult(duplicateId, "first", 2),
+			makeEvalAssistantMessage(duplicateId, 3),
+			developerMessage,
+			makeEvalAssistantMessage(duplicateId, 5),
+			makeEvalToolResult(duplicateId, "second", 6),
+		];
+
+		const transformed = transformMessages(messages, model);
+		const toolResults = getToolResults(transformed);
+
+		expect(getAssistantToolIds(transformed)).toEqual([duplicateId, `${duplicateId}_dup1`, `${duplicateId}_dup2`]);
+		expect(toolResults.map(result => result.toolCallId)).toEqual([
+			duplicateId,
+			`${duplicateId}_dup1`,
+			`${duplicateId}_dup2`,
+		]);
+		expect(toolResults.find(result => result.toolCallId === `${duplicateId}_dup1`)?.content).toEqual([
+			{ type: "text", text: "No result provided" },
+		]);
+		expect(toolResults.find(result => result.toolCallId === `${duplicateId}_dup2`)?.content).toEqual([
+			{ type: "text", text: "second" },
+		]);
+	});
 });
 
 /**

From 1823597c5b56de480b518677736405ae450fb6a8 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 12:51:16 +0000
Subject: [PATCH 162/181] fix(ai): capped duplicate tool id rewrites at 64
 chars

Truncated the original-id prefix when minting _dupN replacements so post-normalization ids never grow past the 64-char Anthropic/Google/Codex ceiling, preserving the suffix that keeps the rewrite unique.\n\nFixes #2055
---
 .../ai/src/providers/transform-messages.ts    | 21 ++++++++++++--
 .../ai/test/duplicate-tool-results.test.ts    | 28 +++++++++++++++++++
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/packages/ai/src/providers/transform-messages.ts b/packages/ai/src/providers/transform-messages.ts
index 6ae6a2225..096b454e7 100644
--- a/packages/ai/src/providers/transform-messages.ts
+++ b/packages/ai/src/providers/transform-messages.ts
@@ -17,6 +17,23 @@ const enum ToolCallStatus {
 	Aborted = 2,
 }
 
+/**
+ * Maximum tool-call id length the strictest replay provider accepts.
+ *
+ * Anthropic requires `^[a-zA-Z0-9_-]+$` with a 64-char cap; Google and Codex
+ * `normalizeToolCallId` implementations cap individual id segments to the same
+ * 64-char ceiling. Replacement ids minted here flow back through
+ * `convertAnthropicMessages` (and friends) unchanged, so the `_dupN` suffix
+ * MUST not push a normalized id past this bound.
+ */
+const MAX_TOOL_CALL_ID_LENGTH = 64;
+
+function appendDuplicateSuffix(originalId: string, suffix: string): string {
+	if (originalId.length + suffix.length <= MAX_TOOL_CALL_ID_LENGTH) return `${originalId}${suffix}`;
+	const prefixBudget = Math.max(0, MAX_TOOL_CALL_ID_LENGTH - suffix.length);
+	return `${originalId.slice(0, prefixBudget)}${suffix}`;
+}
+
 type PendingToolResultRewrite = { replacementId: string } | undefined;
 
 function deduplicateToolCallIds(messages: Message[]): Message[] {
@@ -73,10 +90,10 @@ function deduplicateToolCallIds(messages: Message[]): Message[] {
 			}
 
 			let duplicateIndex = previousCount;
-			let replacementId = `${block.id}_dup${duplicateIndex}`;
+			let replacementId = appendDuplicateSuffix(block.id, `_dup${duplicateIndex}`);
 			while (seenToolCallIds.has(replacementId)) {
 				duplicateIndex += 1;
-				replacementId = `${block.id}_dup${duplicateIndex}`;
+				replacementId = appendDuplicateSuffix(block.id, `_dup${duplicateIndex}`);
 			}
 			seenToolCallIds.set(block.id, duplicateIndex + 1);
 			seenToolCallIds.set(replacementId, 1);
diff --git a/packages/ai/test/duplicate-tool-results.test.ts b/packages/ai/test/duplicate-tool-results.test.ts
index bac919989..46f34ee2c 100644
--- a/packages/ai/test/duplicate-tool-results.test.ts
+++ b/packages/ai/test/duplicate-tool-results.test.ts
@@ -463,6 +463,34 @@ describe("Duplicate Tool Results Regression", () => {
 			{ type: "text", text: "second" },
 		]);
 	});
+
+	it("keeps duplicate-id rewrites within the 64-char tool-call id limit", () => {
+		const baseId = `toolu_${"a".repeat(58)}`;
+		expect(baseId.length).toBe(64);
+		const messages: Message[] = [
+			makeEvalAssistantMessage(baseId, 1),
+			makeEvalToolResult(baseId, "first", 2),
+			makeEvalAssistantMessage(baseId, 3),
+			makeEvalToolResult(baseId, "second", 4),
+		];
+
+		const transformed = transformMessages(messages, model);
+		const assistantToolIds = getAssistantToolIds(transformed);
+		const toolResults = getToolResults(transformed);
+
+		expect(assistantToolIds).toHaveLength(2);
+		for (const id of assistantToolIds) {
+			expect(id.length).toBeLessThanOrEqual(64);
+			expect(id).toMatch(/^[A-Za-z0-9_-]+$/);
+		}
+		const rewrittenId = assistantToolIds[1];
+		expect(rewrittenId).not.toBe(baseId);
+		expect(rewrittenId.endsWith("_dup1")).toBe(true);
+		expect(toolResults.map(result => result.toolCallId)).toEqual([baseId, rewrittenId]);
+		expect(toolResults.find(result => result.toolCallId === rewrittenId)?.content).toEqual([
+			{ type: "text", text: "second" },
+		]);
+	});
 });
 
 /**

From 66ae45f6f564dbef6930df7ade9f287dc0ab0026 Mon Sep 17 00:00:00 2001
From: Marek Schmidt <marks73@gmail.com>
Date: Sun, 7 Jun 2026 13:07:12 +0000
Subject: [PATCH 163/181] fix(ai): support impersonated service account ADC for
 vertex

---
 packages/ai/src/providers/google-auth.ts | 43 +++++++++++++++++++++---
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/packages/ai/src/providers/google-auth.ts b/packages/ai/src/providers/google-auth.ts
index a8004508f..499ab5957 100644
--- a/packages/ai/src/providers/google-auth.ts
+++ b/packages/ai/src/providers/google-auth.ts
@@ -42,7 +42,13 @@ interface AuthorizedUserCredentials {
 	refresh_token: string;
 }
 
-type AdcFileCredentials = ServiceAccountCredentials | AuthorizedUserCredentials;
+interface ImpersonatedServiceAccountCredentials {
+	type: "impersonated_service_account";
+	service_account_impersonation_url: string;
+	source_credentials: AuthorizedUserCredentials | ServiceAccountCredentials;
+}
+
+type AdcFileCredentials = ServiceAccountCredentials | AuthorizedUserCredentials | ImpersonatedServiceAccountCredentials;
 
 interface TokenResponse {
 	access_token: string;
@@ -196,10 +202,37 @@ async function resolveAccessTokenUncached(
 ): Promise<{ source: string; token: TokenResponse }> {
 	const adc = await loadAdcCredentials();
 	if (adc) {
-		const token =
-			adc.creds.type === "service_account"
-				? await exchangeJwtForToken(adc.creds, signal, fetchImpl)
-				: await exchangeRefreshToken(adc.creds, signal, fetchImpl);
+		const creds = adc.creds;
+		let token: TokenResponse;
+
+		if (creds.type === "impersonated_service_account") {
+			const sourceToken =
+				creds.source_credentials.type === "service_account"
+					? await exchangeJwtForToken(creds.source_credentials, signal, fetchImpl)
+					: await exchangeRefreshToken(creds.source_credentials, signal, fetchImpl);
+
+			const response = await fetchImpl(creds.service_account_impersonation_url, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${sourceToken.access_token}`,
+				},
+				body: JSON.stringify({ delegates: [], scope: [CLOUD_PLATFORM_SCOPE], lifetime: "3600s" }),
+				signal,
+			});
+			if (!response.ok) {
+				const detail = await response.text().catch(() => "");
+				throw new Error(`Google Impersonation token exchange failed (${response.status}): ${detail}`);
+			}
+			const data = (await response.json()) as { accessToken: string; expireTime: string };
+			const expiresIn = Math.max(0, Math.floor((new Date(data.expireTime).getTime() - Date.now()) / 1000));
+			token = { access_token: data.accessToken, expires_in: expiresIn, token_type: "Bearer" };
+		} else {
+			token =
+				creds.type === "service_account"
+					? await exchangeJwtForToken(creds, signal, fetchImpl)
+					: await exchangeRefreshToken(creds, signal, fetchImpl);
+		}
 		return { source: adc.source, token };
 	}
 	const metadata = await fetchMetadataToken(signal, fetchImpl);

From 29730eb643da418833c103b392cb86c2498d8bf0 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 12:11:58 +0000
Subject: [PATCH 164/181] fix(tui): handle kitty osc 5522 dot-listing paste
 responses

Kitty implements OSC 5522 paste-event listings by sending one DATA
packet whose mime field decodes to the literal dot sentinel and whose
payload carries the available types as a whitespace-separated list. The
TUI previously only honored the ancillary per-type DATA-packet form, so
plain-text Kitty pastes were rejected as unsupported.

Decode the dot-listing payload during the listing phase and keep the
per-type packet path as a fallback. Also emit the follow-up OSC 5522 read
request using the Kitty protocol shape: the selected MIME list belongs in
the request payload, not in mime metadata. Sending it as metadata makes
Kitty parse an empty requested MIME list and returns no clipboard bytes,
which surfaces as an empty paste.

Add regression coverage for Kitty's text-only and multi-type listings,
and assert the payload-form read requests for default and primary
selection paste events.

Fixes #2051
---
 packages/coding-agent/src/utils/enhanced-paste.ts  |  5 +++--
 .../coding-agent/test/utils/enhanced-paste.test.ts | 14 +++++---------
 2 files changed, 8 insertions(+), 11 deletions(-)

diff --git a/packages/coding-agent/src/utils/enhanced-paste.ts b/packages/coding-agent/src/utils/enhanced-paste.ts
index 3a3e2a564..83ec35bb6 100644
--- a/packages/coding-agent/src/utils/enhanced-paste.ts
+++ b/packages/coding-agent/src/utils/enhanced-paste.ts
@@ -212,11 +212,12 @@ export class EnhancedPasteController {
 			chunks: [],
 		};
 
-		const metadata = [`type=read`, `mime=${Buffer.from(selected.mimeType, "utf8").toString("base64")}`];
+		const encodedMime = Buffer.from(selected.mimeType, "utf8").toString("base64");
+		const metadata = ["type=read"];
 		if (state.loc) metadata.push(`loc=${state.loc}`);
 		if (state.pw) {
 			metadata.push(`pw=${state.pw}`, `name=${PASTE_EVENT_NAME_BASE64}`);
 		}
-		this.#handlers.write(`${OSC5522_PREFIX}${metadata.join(":")}${OSC_TERMINATOR_ST}`);
+		this.#handlers.write(`${OSC5522_PREFIX}${metadata.join(":")};${encodedMime}${OSC_TERMINATOR_ST}`);
 	}
 }
diff --git a/packages/coding-agent/test/utils/enhanced-paste.test.ts b/packages/coding-agent/test/utils/enhanced-paste.test.ts
index f1d71d76d..5f026c92e 100644
--- a/packages/coding-agent/test/utils/enhanced-paste.test.ts
+++ b/packages/coding-agent/test/utils/enhanced-paste.test.ts
@@ -34,7 +34,7 @@ describe("EnhancedPasteController", () => {
 		controller.handleInput(packet("type=read:status=DONE"));
 
 		const pasteEventName = Buffer.from("Paste event", "utf8").toString("base64");
-		expect(writes.at(-1)).toBe(`${OSC}type=read:mime=${imageMime}:pw=${password}:name=${pasteEventName}${ST}`);
+		expect(writes.at(-1)).toBe(`${OSC}type=read:pw=${password}:name=${pasteEventName};${imageMime}${ST}`);
 
 		controller.handleInput(packet("type=read:status=OK"));
 		controller.handleInput(
@@ -68,15 +68,13 @@ describe("EnhancedPasteController", () => {
 
 		const textMime = Buffer.from("text/plain", "utf8").toString("base64");
 		const password = Buffer.from("secret456", "utf8").toString("base64");
+		const pasteEventName = Buffer.from("Paste event", "utf8").toString("base64");
 		expect(controller.handleInput("plain text")).toBe(false);
 		controller.handleInput(packet(`type=read:status=OK:loc=primary:pw=${password}`));
 		controller.handleInput(packet(`type=read:status=DATA:mime=${textMime}`));
 		controller.handleInput(packet("type=read:status=DONE"));
 
-		expect(writes).toHaveLength(1);
-		expect(writes[0]).toContain(`mime=${textMime}`);
-		expect(writes[0]).toContain("loc=primary");
-		expect(writes[0]).toContain(`pw=${password}`);
+		expect(writes).toEqual([`${OSC}type=read:loc=primary:pw=${password}:name=${pasteEventName};${textMime}${ST}`]);
 
 		controller.handleInput(packet("type=read:status=OK"));
 		controller.handleInput(
@@ -136,9 +134,7 @@ describe("EnhancedPasteController", () => {
 		);
 		controller.handleInput(packet(`type=read:status=DONE:pw=${password}`));
 
-		expect(writes.at(-1)).toBe(
-			`${OSC}type=read:mime=${textMime}:pw=${password}:name=${pasteEventName}${ST}`,
-		);
+		expect(writes.at(-1)).toBe(`${OSC}type=read:pw=${password}:name=${pasteEventName};${textMime}${ST}`);
 
 		controller.handleInput(packet("type=read:status=OK"));
 		controller.handleInput(
@@ -175,6 +171,6 @@ describe("EnhancedPasteController", () => {
 		);
 		controller.handleInput(packet("type=read:status=DONE"));
 
-		expect(writes.at(-1)).toContain(`mime=${imageMime}`);
+		expect(writes.at(-1)).toBe(`${OSC}type=read;${imageMime}${ST}`);
 	});
 });

From be0bd63023331a1f4ceec2932a520ad1d9968abf Mon Sep 17 00:00:00 2001
From: Marek Schmidt <marks73@gmail.com>
Date: Sun, 7 Jun 2026 13:44:50 +0000
Subject: [PATCH 165/181] fix(ai): reconstruct IAM URL, add test coverage,
 update changelog

---
 packages/ai/CHANGELOG.md                      |  5 +++
 .../providers/__tests__/google-auth.test.ts   | 41 +++++++++++++++++++
 packages/ai/src/providers/google-auth.ts      | 15 ++++++-
 3 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 packages/ai/src/providers/__tests__/google-auth.test.ts

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index 344d76b9a..a8963617e 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -1,3 +1,8 @@
+## [Unreleased]
+
+### Added
+
+- Added support for `impersonated_service_account` Application Default Credentials (ADC) in Vertex AI to enable chained impersonation without failing via 401 `invalid_client`.
 # Changelog
 
 ## [Unreleased]
diff --git a/packages/ai/src/providers/__tests__/google-auth.test.ts b/packages/ai/src/providers/__tests__/google-auth.test.ts
new file mode 100644
index 000000000..e6f1aea53
--- /dev/null
+++ b/packages/ai/src/providers/__tests__/google-auth.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it, mock } from "bun:test";
+import { getVertexAccessToken, __resetVertexTokenCache } from "../google-auth";
+
+describe("getVertexAccessToken", () => {
+	it("should exchange impersonated ADC correctly", async () => {
+		__resetVertexTokenCache();
+		Bun.env.GOOGLE_APPLICATION_CREDENTIALS = "/tmp/mock-impersonated-adc.json";
+		
+		await Bun.write("/tmp/mock-impersonated-adc.json", JSON.stringify({
+			type: "impersonated_service_account",
+			service_account_impersonation_url: "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken",
+			source_credentials: {
+				type: "authorized_user",
+				client_id: "client-id",
+				client_secret: "client-secret",
+				refresh_token: "refresh-token"
+			},
+			delegates: ["delegate1"]
+		}));
+
+		let fetchCalls: any[] = [];
+		const mockFetch = mock(async (url: string, opts: any) => {
+			fetchCalls.push({ url, opts });
+			if (url.includes("oauth2.googleapis.com/token")) {
+				return { ok: true, json: async () => ({ access_token: "source-token", expires_in: 3600 }) };
+			}
+			if (url.includes("iamcredentials.googleapis.com")) {
+				return { ok: true, json: async () => ({ accessToken: "impersonated-token", expireTime: new Date(Date.now() + 3600000).toISOString() }) };
+			}
+			return { ok: false };
+		}) as any;
+
+		const token = await getVertexAccessToken({ fetch: mockFetch });
+		expect(token).toBe("impersonated-token");
+		expect(fetchCalls.length).toBe(2);
+		expect(fetchCalls[0].url).toContain("oauth2.googleapis.com");
+		expect(fetchCalls[1].url).toBe("https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken");
+		expect(fetchCalls[1].opts.headers.Authorization).toBe("Bearer source-token");
+		expect(JSON.parse(fetchCalls[1].opts.body).delegates).toEqual(["delegate1"]);
+	});
+});
diff --git a/packages/ai/src/providers/google-auth.ts b/packages/ai/src/providers/google-auth.ts
index 499ab5957..39a81922c 100644
--- a/packages/ai/src/providers/google-auth.ts
+++ b/packages/ai/src/providers/google-auth.ts
@@ -46,6 +46,7 @@ interface ImpersonatedServiceAccountCredentials {
 	type: "impersonated_service_account";
 	service_account_impersonation_url: string;
 	source_credentials: AuthorizedUserCredentials | ServiceAccountCredentials;
+	delegates?: string[];
 }
 
 type AdcFileCredentials = ServiceAccountCredentials | AuthorizedUserCredentials | ImpersonatedServiceAccountCredentials;
@@ -206,18 +207,28 @@ async function resolveAccessTokenUncached(
 		let token: TokenResponse;
 
 		if (creds.type === "impersonated_service_account") {
+			const targetPrincipalMatch = /(?<target>[^/]+):(generateAccessToken|generateIdToken)$/.exec(
+				creds.service_account_impersonation_url,
+			);
+			const targetPrincipal = targetPrincipalMatch?.groups?.target;
+			if (!targetPrincipal) {
+				throw new RangeError(
+					`Cannot extract target principal from ${creds.service_account_impersonation_url}`,
+				);
+			}
+
 			const sourceToken =
 				creds.source_credentials.type === "service_account"
 					? await exchangeJwtForToken(creds.source_credentials, signal, fetchImpl)
 					: await exchangeRefreshToken(creds.source_credentials, signal, fetchImpl);
 
-			const response = await fetchImpl(creds.service_account_impersonation_url, {
+			const response = await fetchImpl(`https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${targetPrincipal}:generateAccessToken`, {
 				method: "POST",
 				headers: {
 					"Content-Type": "application/json",
 					Authorization: `Bearer ${sourceToken.access_token}`,
 				},
-				body: JSON.stringify({ delegates: [], scope: [CLOUD_PLATFORM_SCOPE], lifetime: "3600s" }),
+				body: JSON.stringify({ delegates: creds.delegates ?? [], scope: [CLOUD_PLATFORM_SCOPE], lifetime: "3600s" }),
 				signal,
 			});
 			if (!response.ok) {

From 9c870ec106ec3992c61d97f66e1e766406a8e4dc Mon Sep 17 00:00:00 2001
From: Marek Schmidt <marks73@gmail.com>
Date: Sun, 7 Jun 2026 13:50:25 +0000
Subject: [PATCH 166/181] fix(ai): updated changelog

---
 packages/ai/CHANGELOG.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/ai/CHANGELOG.md b/packages/ai/CHANGELOG.md
index a8963617e..04d37ccac 100644
--- a/packages/ai/CHANGELOG.md
+++ b/packages/ai/CHANGELOG.md
@@ -1,11 +1,10 @@
+# Changelog
 ## [Unreleased]
 
 ### Added
 
 - Added support for `impersonated_service_account` Application Default Credentials (ADC) in Vertex AI to enable chained impersonation without failing via 401 `invalid_client`.
-# Changelog
 
-## [Unreleased]
 
 ## [15.10.1] - 2026-06-07
 

From 83c8105be60bf49daf11b5bfcd4de97f5f6e2ecd Mon Sep 17 00:00:00 2001
From: Guts <sepehrrazmyar@gmail.com>
Date: Sun, 7 Jun 2026 15:42:35 +0200
Subject: [PATCH 167/181] fix(mcp): declare approval tier for MCP tools to
 prevent hangs in non-yolo mode

MCPTool and DeferredMCPTool now declare approval = 'write' instead of
implicitly defaulting to 'exec'. Without this, the approval system
requires user confirmation for every MCP tool call in non-yolo modes,
but the confirmation prompt never renders in the TUI while streaming,
causing the agent to hang indefinitely.

Also propagate the approval property through customToolToDefinition()
in sdk.ts, which was silently dropping it during CustomTool ->
ToolDefinition conversion.
---
 packages/coding-agent/CHANGELOG.md                    |  4 ++++
 .../src/extensibility/extensions/types.ts             | 11 ++++++++++-
 packages/coding-agent/src/mcp/tool-bridge.ts          |  2 ++
 packages/coding-agent/src/sdk.ts                      |  1 +
 4 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0243ed841..ff32bd8db 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed MCP tools hanging in non-yolo modes by declaring `approval = "write"` on `MCPTool` and `DeferredMCPTool`, and propagating the `approval` property through `customToolToDefinition()` in `sdk.ts`
+
 ## [15.10.1] - 2026-06-07
 
 ### Added
diff --git a/packages/coding-agent/src/extensibility/extensions/types.ts b/packages/coding-agent/src/extensibility/extensions/types.ts
index beeae8e39..17b78e334 100644
--- a/packages/coding-agent/src/extensibility/extensions/types.ts
+++ b/packages/coding-agent/src/extensibility/extensions/types.ts
@@ -7,7 +7,13 @@
  * - Register commands, keyboard shortcuts, and CLI flags
  * - Interact with the user via UI primitives
  */
-import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type {
+	AgentMessage,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ThinkingLevel,
+	ToolApproval,
+} from "@oh-my-pi/pi-agent-core";
 import type { CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
 import type {
 	Api,
@@ -392,6 +398,9 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
 	defaultInactive?: boolean;
 	/** If true, tool may stage deferred changes that require explicit resolve/discard. */
 	deferrable?: boolean;
+	/** Tool approval tier. Defaults to `"exec"` when omitted.
+	 *  `"read"`: read-only operations. `"write"`: mutations. `"exec"`: code execution. */
+	approval?: ToolApproval;
 	/** MCP server name for discovery/search metadata when this tool fronts an MCP server. */
 	mcpServerName?: string;
 	/** Original MCP tool name for discovery/search metadata. */
diff --git a/packages/coding-agent/src/mcp/tool-bridge.ts b/packages/coding-agent/src/mcp/tool-bridge.ts
index 1b396ad4b..4063d8153 100644
--- a/packages/coding-agent/src/mcp/tool-bridge.ts
+++ b/packages/coding-agent/src/mcp/tool-bridge.ts
@@ -220,6 +220,7 @@ export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
 	readonly mcpToolName: string;
 	/** Server name */
 	readonly mcpServerName: string;
+	readonly approval = "write" as const;
 	/** Render completed MCP calls with the result header replacing the pending call header. */
 	readonly mergeCallAndResult = true;
 
@@ -305,6 +306,7 @@ export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
 	readonly mcpToolName: string;
 	/** Server name */
 	readonly mcpServerName: string;
+	readonly approval = "write" as const;
 	/** Render completed MCP calls with the result header replacing the pending call header. */
 	readonly mergeCallAndResult = true;
 
diff --git a/packages/coding-agent/src/sdk.ts b/packages/coding-agent/src/sdk.ts
index a28d834e5..748a8e651 100644
--- a/packages/coding-agent/src/sdk.ts
+++ b/packages/coding-agent/src/sdk.ts
@@ -709,6 +709,7 @@ function customToolToDefinition(tool: CustomTool): ToolDefinition {
 		parameters: tool.parameters,
 		hidden: tool.hidden,
 		deferrable: tool.deferrable,
+		approval: tool.approval,
 		mcpServerName: tool.mcpServerName,
 		mcpToolName: tool.mcpToolName,
 		execute: (toolCallId, params, signal, onUpdate, ctx) =>

From e796a7db4d07887ad34a20a748819c263af6ab28 Mon Sep 17 00:00:00 2001
From: Guts <sepehrrazmyar@gmail.com>
Date: Sun, 7 Jun 2026 16:42:19 +0200
Subject: [PATCH 168/181] test(approval): add regression tests for MCP tool
 approval tier

---
 packages/coding-agent/test/tools/approval.test.ts | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/packages/coding-agent/test/tools/approval.test.ts b/packages/coding-agent/test/tools/approval.test.ts
index 04761a543..11f64bc01 100644
--- a/packages/coding-agent/test/tools/approval.test.ts
+++ b/packages/coding-agent/test/tools/approval.test.ts
@@ -115,6 +115,17 @@ describe("MCP fallback and prompt formatting", () => {
 		expect(resolveApproval(subject, {}, "yolo")).toMatchObject({ policy: "allow", tier: "exec" });
 	});
 
+	it("allows MCP tools with write approval in write mode", () => {
+		const subject = tool("mcp__server__safe", "write");
+		expect(resolveApproval(subject, {}, "write")).toMatchObject({ policy: "allow", tier: "write" });
+		expect(resolveApproval(subject, {}, "yolo")).toMatchObject({ policy: "allow", tier: "write" });
+	});
+
+	it("prompts for MCP tools with write approval in always-ask mode", () => {
+		const subject = tool("mcp__server__safe", "write");
+		expect(resolveApproval(subject, {}, "always-ask")).toMatchObject({ policy: "prompt", tier: "write" });
+	});
+
 	it("formats MCP origin, reason, and per-tool details", () => {
 		const subject = tool("mcp__server__dangerous", undefined, () => ["Path: /tmp/out", "Content:\nhello"]);
 		expect(formatApprovalPrompt(subject, {}, "Needs confirmation").split("\n")).toEqual([

From 72e11ca5e905984dc74b97fb981fccd82fdcbd1d Mon Sep 17 00:00:00 2001
From: Guts <sepehrrazmyar@gmail.com>
Date: Sun, 7 Jun 2026 16:58:25 +0200
Subject: [PATCH 169/181] fix(sdk): bind dynamic approval callbacks to original
 tool instance

---
 packages/coding-agent/src/sdk.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/coding-agent/src/sdk.ts b/packages/coding-agent/src/sdk.ts
index 748a8e651..992396621 100644
--- a/packages/coding-agent/src/sdk.ts
+++ b/packages/coding-agent/src/sdk.ts
@@ -709,7 +709,7 @@ function customToolToDefinition(tool: CustomTool): ToolDefinition {
 		parameters: tool.parameters,
 		hidden: tool.hidden,
 		deferrable: tool.deferrable,
-		approval: tool.approval,
+		approval: typeof tool.approval === "function" ? tool.approval.bind(tool) : tool.approval,
 		mcpServerName: tool.mcpServerName,
 		mcpToolName: tool.mcpToolName,
 		execute: (toolCallId, params, signal, onUpdate, ctx) =>

From 5bfad210a66569b261c5c0dc298fdd653e188d8f Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 16:17:29 +0000
Subject: [PATCH 170/181] fix(tui): recognized Ghostty's super+alt+backspace as
 word delete

Ghostty on macOS reports Option+Backspace as kitty modifier 11
(wire) = 10 (mask) = super(8) | alt(2). The native key matcher only
recognised shift/ctrl/alt, so:

- format_kitty_key in crates/pi-natives/src/keys.rs rejected any
  sequence whose effective modifier had bits beyond shift/ctrl/alt
  set; parseKey returned undefined for \x1b[127;11u.
- parse_key_id recognised only those three modifiers, so even an
  explicit 'super+alt+backspace' degraded to 'alt+backspace' and
  could not match an actual super+alt encoded press.
- The editor's matchesKey(data, 'alt+backspace') branch was never
  reached and Option+Backspace either no-op'd or fell through to
  single-character delete.

Added a MOD_SUPER constant, taught parse_key_id, format_with_mods,
and format_kitty_key about the super bit, added super+alt+backspace
(and super+alt+delete / super+alt+d) to tui.editor.deleteWord*
defaults, and broadened the editor's direct matchesKey calls to
accept the super+alt variants. Existing alt+backspace / alt+d /
alt+delete paths are untouched, so the legacy ESC+DEL workaround
keeps working too.

Added Rust unit tests for the super modifier (positive and
negative for hyper/meta sequences we still drop) and TS
regressions in keys.test.ts and editor.test.ts that exercise
\x1b[127;11u end-to-end.

Fixes #2064
---
 crates/pi-natives/src/keys.rs         | 44 +++++++++++++++++++++++++--
 packages/natives/CHANGELOG.md         |  4 +++
 packages/tui/CHANGELOG.md             |  4 +++
 packages/tui/src/components/editor.ts | 14 ++++++---
 packages/tui/src/keybindings.ts       |  4 +--
 packages/tui/test/editor.test.ts      | 11 +++++++
 packages/tui/test/keys.test.ts        | 17 ++++++++++-
 7 files changed, 89 insertions(+), 9 deletions(-)

diff --git a/crates/pi-natives/src/keys.rs b/crates/pi-natives/src/keys.rs
index ccdb9a935..d132d70e8 100644
--- a/crates/pi-natives/src/keys.rs
+++ b/crates/pi-natives/src/keys.rs
@@ -70,6 +70,7 @@ const CP_KP_EQUALS: i32 = 57415;
 const MOD_SHIFT: u32 = 1;
 const MOD_ALT: u32 = 2;
 const MOD_CTRL: u32 = 4;
+const MOD_SUPER: u32 = 8;
 const MOD_NUM_LOCK: u32 = 128;
 
 /// Event types from Kitty keyboard protocol (flag 2).
@@ -457,6 +458,10 @@ fn parse_key_id(key_id: &str) -> Option<ParsedKeyId<'_>> {
 				modifier |= MOD_SHIFT;
 				continue;
 			},
+			b's' | b'S' if p.eq_ignore_ascii_case("super") => {
+				modifier |= MOD_SUPER;
+				continue;
+			},
 			b'a' | b'A' if p.eq_ignore_ascii_case("alt") => {
 				modifier |= MOD_ALT;
 				continue;
@@ -1378,7 +1383,7 @@ fn parse_functional(bytes: &[u8]) -> Option<ParsedKittySequence> {
 
 fn format_kitty_key(parsed: &ParsedKittySequence) -> Option<Cow<'static, str>> {
 	let effective_mod = parsed.modifier & !LOCK_MASK;
-	if effective_mod & !(MOD_SHIFT | MOD_CTRL | MOD_ALT) != 0 {
+	if effective_mod & !(MOD_SHIFT | MOD_CTRL | MOD_ALT | MOD_SUPER) != 0 {
 		return None;
 	}
 	let effective_codepoint =
@@ -1480,6 +1485,9 @@ fn format_with_mods(mods: u32, key_name: &str) -> String {
 	if mods & MOD_ALT != 0 {
 		result.push_str("alt+");
 	}
+	if mods & MOD_SUPER != 0 {
+		result.push_str("super+");
+	}
 	result.push_str(key_name);
 	result
 }
@@ -1585,7 +1593,11 @@ mod tests {
 
 	#[test]
 	fn parse_key_ignores_kitty_sequences_with_unsupported_modifiers() {
-		assert_eq!(parse_key_inner(b"\x1b[99;9u", true).as_deref(), None);
+		// Hyper (16) and meta (32) are kitty modifier bits we do not surface
+		// because nothing in the editor binds them. Wire mod 17 = mask 16 = hyper.
+		assert_eq!(parse_key_inner(b"\x1b[99;17u", true).as_deref(), None);
+		// Wire mod 33 = mask 32 = meta.
+		assert_eq!(parse_key_inner(b"\x1b[99;33u", true).as_deref(), None);
 	}
 
 	#[test]
@@ -1675,4 +1687,32 @@ mod tests {
 		assert!(matches_key_inner(b"\x1b[109;7u", "ctrl+alt+m", true));
 		assert!(matches_key_inner(b"\x1b[27;7;109~", "ctrl+alt+m", false));
 	}
+
+	#[test]
+	fn super_alt_backspace_matches_ghostty_default() {
+		// Issue #2064: Ghostty on macOS reports Option+Backspace as kitty
+		// modifier 11 (wire) = 10 (mask) = super(8)|alt(2). Before super
+		// support landed, the matcher rejected this entirely.
+		assert!(matches_key_inner(b"\x1b[127;11u", "super+alt+backspace", true));
+		assert!(matches_key_inner(b"\x1b[127;11u", "alt+super+backspace", true));
+		assert_eq!(parse_key_inner(b"\x1b[127;11u", true).as_deref(), Some("alt+super+backspace"));
+		// Plain alt+backspace must still NOT match — the modifier really is super|alt.
+		assert!(!matches_key_inner(b"\x1b[127;11u", "alt+backspace", true));
+		// And plain backspace (mod 0) must still not match a super+alt-modified press.
+		assert!(!matches_key_inner(b"\x1b[127;11u", "backspace", true));
+		// Release events stay ignored: super+alt+backspace release must not match a press.
+		assert!(!matches_key_inner(b"\x1b[127;11:3u", "super+alt+backspace", true));
+		assert_eq!(parse_key_inner(b"\x1b[127;11:3u", true).as_deref(), None);
+	}
+
+	#[test]
+	fn super_modifier_parses_for_arbitrary_keys() {
+		// Cmd+letter on macOS under kitty flag=1+: super(8)+'a'(97) → wire mod 9.
+		assert!(matches_key_inner(b"\x1b[97;9u", "super+a", true));
+		assert_eq!(parse_key_inner(b"\x1b[97;9u", true).as_deref(), Some("super+a"));
+		// Cmd+Shift+letter: super(8)|shift(1) = 9 mask, wire 10.
+		assert!(matches_key_inner(b"\x1b[97;10u", "super+shift+a", true));
+		assert!(matches_key_inner(b"\x1b[97;10u", "shift+super+a", true));
+		assert_eq!(parse_key_inner(b"\x1b[97;10u", true).as_deref(), Some("shift+super+a"));
+	}
 }
diff --git a/packages/natives/CHANGELOG.md b/packages/natives/CHANGELOG.md
index c89da28eb..c2335e74e 100644
--- a/packages/natives/CHANGELOG.md
+++ b/packages/natives/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added the `super` modifier to `matchesKey` / `parseKey` / `parseKittySequence`. Key identifiers may now include `super+` (anywhere in the modifier prefix), and Kitty CSI-u sequences whose modifier mask contains the super bit (8) — e.g. Ghostty's macOS Option+Backspace `ESC [127;11u` — are now recognised instead of dropped ([#2064](https://github.com/can1357/oh-my-pi/issues/2064)).
+
 ## [15.10.1] - 2026-06-07
 
 ### Fixed
diff --git a/packages/tui/CHANGELOG.md b/packages/tui/CHANGELOG.md
index 56903eddc..f5be769ec 100644
--- a/packages/tui/CHANGELOG.md
+++ b/packages/tui/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added `super` modifier support to native key parsing/matching and bound `super+alt+backspace` / `super+alt+delete` (and `super+alt+d`) into the word-delete defaults so Ghostty's default macOS Option+Backspace wire (`ESC [127;11u` — kitty modifier 11 = super|alt) deletes a word instead of falling through to single-char delete ([#2064](https://github.com/can1357/oh-my-pi/issues/2064)).
+
 ## [15.10.1] - 2026-06-07
 ### Breaking Changes
 
diff --git a/packages/tui/src/components/editor.ts b/packages/tui/src/components/editor.ts
index 2ea05e43e..e252a1ea0 100644
--- a/packages/tui/src/components/editor.ts
+++ b/packages/tui/src/components/editor.ts
@@ -1109,12 +1109,18 @@ export class Editor implements Component, Focusable {
 		else if (matchesKey(data, "ctrl+w")) {
 			this.#deleteWordBackwards();
 		}
-		// Option/Alt+Backspace - Delete word backwards
-		else if (matchesKey(data, "alt+backspace")) {
+		// Option/Alt+Backspace - Delete word backwards.
+		// Ghostty on macOS reports Option+Backspace as super+alt (kitty mod 11) — see #2064.
+		else if (matchesKey(data, "alt+backspace") || matchesKey(data, "super+alt+backspace")) {
 			this.#deleteWordBackwards();
 		}
-		// Option/Alt+D - Delete word forwards
-		else if (matchesKey(data, "alt+d") || matchesKey(data, "alt+delete")) {
+		// Option/Alt+D and Option+Delete - Delete word forwards. Same Ghostty quirk applies.
+		else if (
+			matchesKey(data, "alt+d") ||
+			matchesKey(data, "alt+delete") ||
+			matchesKey(data, "super+alt+d") ||
+			matchesKey(data, "super+alt+delete")
+		) {
 			this.#deleteWordForwards();
 		}
 		// Ctrl+Y - Yank from kill ring
diff --git a/packages/tui/src/keybindings.ts b/packages/tui/src/keybindings.ts
index e03954f09..876b77c5a 100644
--- a/packages/tui/src/keybindings.ts
+++ b/packages/tui/src/keybindings.ts
@@ -100,11 +100,11 @@ export const TUI_KEYBINDINGS = {
 		description: "Delete character forward",
 	},
 	"tui.editor.deleteWordBackward": {
-		defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace"],
+		defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace", "super+alt+backspace"],
 		description: "Delete word backward",
 	},
 	"tui.editor.deleteWordForward": {
-		defaultKeys: ["alt+delete", "alt+d"],
+		defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"],
 		description: "Delete word forward",
 	},
 	"tui.editor.deleteToLineStart": {
diff --git a/packages/tui/test/editor.test.ts b/packages/tui/test/editor.test.ts
index 640eb9601..7a1506974 100644
--- a/packages/tui/test/editor.test.ts
+++ b/packages/tui/test/editor.test.ts
@@ -3,6 +3,7 @@ import { stripVTControlCharacters } from "node:util";
 import { CURSOR_MARKER } from "@oh-my-pi/pi-tui";
 import { CombinedAutocompleteProvider } from "@oh-my-pi/pi-tui/autocomplete";
 import { Editor } from "@oh-my-pi/pi-tui/components/editor";
+import { setKittyProtocolActive } from "@oh-my-pi/pi-tui/keys";
 import { visibleWidth } from "@oh-my-pi/pi-tui/utils";
 import { setDefaultTabWidth } from "@oh-my-pi/pi-utils";
 import { KeybindingsManager, setKeybindings, TUI_KEYBINDINGS } from "../src/keybindings";
@@ -616,6 +617,16 @@ describe("Editor component", () => {
 			editor.setText("foo bar");
 			editor.handleInput("\x1b\x7f"); // Alt+Backspace (legacy)
 			expect(editor.getText()).toBe("foo ");
+
+			// Issue #2064: Ghostty on macOS reports Option+Backspace as `ESC [127;11u`
+			// (kitty modifier 11 wire = super(8)|alt(2)). Without super support the
+			// editor used to ignore this entirely and the previous word survived.
+			setKittyProtocolActive(true);
+			editor.setText("foo bar");
+			editor.handleInput("\x1b[F"); // End — park cursor at EOL
+			editor.handleInput("\x1b[127;11u"); // Ghostty Option+Backspace
+			expect(editor.getText()).toBe("foo ");
+			setKittyProtocolActive(false);
 		});
 
 		it("navigates words correctly with Ctrl+Left/Right", () => {
diff --git a/packages/tui/test/keys.test.ts b/packages/tui/test/keys.test.ts
index 48943e754..3645ee31e 100644
--- a/packages/tui/test/keys.test.ts
+++ b/packages/tui/test/keys.test.ts
@@ -77,6 +77,19 @@ describe("matchesKey", () => {
 		expect(matchesKey("\x1b[57400;133u", "1")).toBe(false);
 		setKittyProtocolActive(false);
 	});
+
+	it("recognises super+alt+backspace from Ghostty's default Option+Backspace wire (#2064)", () => {
+		setKittyProtocolActive(true);
+		// Modifier 11 (wire) = 10 (mask) = super(8)|alt(2). Ghostty's keyboard
+		// inspector on macOS reports `ESC [127;11u` for Option+Backspace without
+		// any user-defined keybind.
+		expect(matchesKey("\x1b[127;11u", "super+alt+backspace")).toBe(true);
+		expect(matchesKey("\x1b[127;11u", "alt+super+backspace")).toBe(true);
+		// Plain alt+backspace must NOT consume this — the modifier truly is super|alt.
+		expect(matchesKey("\x1b[127;11u", "alt+backspace")).toBe(false);
+		expect(matchesKey("\x1b[127;11u", "backspace")).toBe(false);
+		setKittyProtocolActive(false);
+	});
 });
 
 describe("parseKey", () => {
@@ -132,7 +145,9 @@ describe("parseKey", () => {
 
 	it("ignores Kitty sequences with unsupported modifiers", () => {
 		setKittyProtocolActive(true);
-		expect(parseKey("\x1b[99;9u")).toBeUndefined();
+		// Hyper (16) and meta (32) bits aren't surfaced because nothing binds them.
+		expect(parseKey("\x1b[99;17u")).toBeUndefined(); // hyper-only
+		expect(parseKey("\x1b[99;33u")).toBeUndefined(); // meta-only
 		setKittyProtocolActive(false);
 	});
 });

From a58f0bcbebfb9a46480951cd45eecf5e0acab85f Mon Sep 17 00:00:00 2001
From: DarkPhilosophy <19309990+DarkPhilosophy@users.noreply.github.com>
Date: Sun, 7 Jun 2026 20:46:44 +0300
Subject: [PATCH 171/181] fix(coding-agent): parse launch cwd flag

---
 packages/coding-agent/CHANGELOG.md             |  4 ++++
 packages/coding-agent/src/cli/args.ts          |  2 ++
 packages/coding-agent/src/commands/launch.ts   |  3 +++
 .../coding-agent/test/cli-cwd-flag.test.ts     | 18 ++++++++++++++++++
 4 files changed, 27 insertions(+)
 create mode 100644 packages/coding-agent/test/cli-cwd-flag.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0243ed841..c374cc647 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed the `--cwd` launch flag so it is parsed and can override the startup directory instead of always falling back to the current process directory or home auto-switch target.
+
 ## [15.10.1] - 2026-06-07
 
 ### Added
diff --git a/packages/coding-agent/src/cli/args.ts b/packages/coding-agent/src/cli/args.ts
index 707d87c54..feec309ba 100644
--- a/packages/coding-agent/src/cli/args.ts
+++ b/packages/coding-agent/src/cli/args.ts
@@ -109,6 +109,8 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 			result.version = true;
 		} else if (arg === "--allow-home") {
 			result.allowHome = true;
+		} else if (arg === "--cwd" && i + 1 < args.length) {
+			result.cwd = args[++i];
 		} else if (arg === "--mode" && i + 1 < args.length) {
 			const mode = args[++i];
 			if (mode === "text" || mode === "json" || mode === "rpc" || mode === "acp" || mode === "rpc-ui") {
diff --git a/packages/coding-agent/src/commands/launch.ts b/packages/coding-agent/src/commands/launch.ts
index d26dc543a..a3cc59719 100644
--- a/packages/coding-agent/src/commands/launch.ts
+++ b/packages/coding-agent/src/commands/launch.ts
@@ -49,6 +49,9 @@ export default class Index extends Command {
 		"allow-home": Flags.boolean({
 			description: "Allow starting in ~ without auto-switching to a temp dir",
 		}),
+		cwd: Flags.string({
+			description: "Directory to start in (overrides the launch cwd)",
+		}),
 		mode: Flags.string({
 			description: "Output mode: text (default), json, rpc, or rpc-ui",
 			options: ["text", "json", "rpc", "acp", "rpc-ui"],
diff --git a/packages/coding-agent/test/cli-cwd-flag.test.ts b/packages/coding-agent/test/cli-cwd-flag.test.ts
new file mode 100644
index 000000000..b2c9c2147
--- /dev/null
+++ b/packages/coding-agent/test/cli-cwd-flag.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from "bun:test";
+import { parseArgs } from "../src/cli/args";
+
+describe("parseArgs — --cwd flag", () => {
+	it("parses --cwd with a space-separated directory", () => {
+		const result = parseArgs(["--cwd", "/work/project", "hello"]);
+
+		expect(result.cwd).toBe("/work/project");
+		expect(result.messages).toEqual(["hello"]);
+	});
+
+	it("parses --cwd=value without leaking the value into messages", () => {
+		const result = parseArgs(["--cwd=/work/project", "hello"]);
+
+		expect(result.cwd).toBe("/work/project");
+		expect(result.messages).toEqual(["hello"]);
+	});
+});

From 5f7db975609c99e8841a9aa85b2f277a2f63ebee Mon Sep 17 00:00:00 2001
From: DarkPhilosophy <19309990+DarkPhilosophy@users.noreply.github.com>
Date: Sun, 7 Jun 2026 21:06:02 +0300
Subject: [PATCH 172/181] fix(coding-agent): apply cwd before startup discovery

---
 packages/coding-agent/src/main.ts             | 10 +++++++-
 .../coding-agent/test/cli-cwd-flag.test.ts    | 25 ++++++++++++++++++-
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index 8d4d30b46..491ed2c37 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -530,6 +530,14 @@ async function maybeAutoChdir(parsed: Args): Promise<void> {
 	}
 }
 
+export async function applyStartupCwd(parsed: Args): Promise<void> {
+	if (parsed.cwd) {
+		setProjectDir(parsed.cwd);
+		return;
+	}
+	await maybeAutoChdir(parsed);
+}
+
 /** Discover SYSTEM.md file if no CLI system prompt was provided */
 function discoverSystemPromptFile(): string | undefined {
 	// Check project-local first (.omp/SYSTEM.md, .pi/SYSTEM.md legacy)
@@ -745,7 +753,7 @@ export async function runRootCommand(
 	await logger.time("initTheme:initial", initTheme);
 
 	const parsedArgs = parsed;
-	await logger.time("maybeAutoChdir", maybeAutoChdir, parsedArgs);
+	await logger.time("applyStartupCwd", applyStartupCwd, parsedArgs);
 
 	const notifs: (InteractiveModeNotify | null)[] = [];
 
diff --git a/packages/coding-agent/test/cli-cwd-flag.test.ts b/packages/coding-agent/test/cli-cwd-flag.test.ts
index b2c9c2147..7949ec5dc 100644
--- a/packages/coding-agent/test/cli-cwd-flag.test.ts
+++ b/packages/coding-agent/test/cli-cwd-flag.test.ts
@@ -1,6 +1,16 @@
-import { describe, expect, it } from "bun:test";
+import { afterEach, describe, expect, it } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getProjectDir, setProjectDir } from "@oh-my-pi/pi-utils";
 import { parseArgs } from "../src/cli/args";
+import { applyStartupCwd } from "../src/main";
 
+const originalProjectDir = getProjectDir();
+
+afterEach(() => {
+	setProjectDir(originalProjectDir);
+});
 describe("parseArgs — --cwd flag", () => {
 	it("parses --cwd with a space-separated directory", () => {
 		const result = parseArgs(["--cwd", "/work/project", "hello"]);
@@ -15,4 +25,17 @@ describe("parseArgs — --cwd flag", () => {
 		expect(result.cwd).toBe("/work/project");
 		expect(result.messages).toEqual(["hello"]);
 	});
+
+	it("applies --cwd before session lookup callers read the project directory", async () => {
+		const launchDir = fs.mkdtempSync(path.join(os.tmpdir(), "omp-cwd-launch-"));
+		const targetDir = fs.mkdtempSync(path.join(os.tmpdir(), "omp-cwd-target-"));
+		setProjectDir(launchDir);
+
+		const parsed = parseArgs(["--cwd", targetDir, "--continue"]);
+		await applyStartupCwd(parsed);
+
+		expect(parsed.continue).toBe(true);
+		expect(getProjectDir()).toBe(targetDir);
+		expect(process.cwd()).toBe(targetDir);
+	});
 });

From 60dde9d33f26b7b1d9a07f0163409f6ef6475850 Mon Sep 17 00:00:00 2001
From: DarkPhilosophy <19309990+DarkPhilosophy@users.noreply.github.com>
Date: Sun, 7 Jun 2026 21:12:17 +0300
Subject: [PATCH 173/181] fix(coding-agent): isolate startup cwd helper

---
 packages/coding-agent/src/cli/startup-cwd.ts  | 63 +++++++++++++++++++
 packages/coding-agent/src/main.ts             | 61 +-----------------
 .../coding-agent/test/cli-cwd-flag.test.ts    |  2 +-
 3 files changed, 65 insertions(+), 61 deletions(-)
 create mode 100644 packages/coding-agent/src/cli/startup-cwd.ts

diff --git a/packages/coding-agent/src/cli/startup-cwd.ts b/packages/coding-agent/src/cli/startup-cwd.ts
new file mode 100644
index 000000000..afabff095
--- /dev/null
+++ b/packages/coding-agent/src/cli/startup-cwd.ts
@@ -0,0 +1,63 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getProjectDir, normalizePathForComparison, setProjectDir } from "@oh-my-pi/pi-utils";
+import type { Args } from "./args";
+
+async function maybeAutoChdir(parsed: Args): Promise<void> {
+	if (parsed.allowHome || parsed.cwd) {
+		return;
+	}
+
+	const home = os.homedir();
+	if (!home) {
+		return;
+	}
+
+	const normalizePath = normalizePathForComparison;
+
+	const cwd = normalizePath(getProjectDir());
+	const normalizedHome = normalizePath(home);
+	if (cwd !== normalizedHome) {
+		return;
+	}
+
+	const isDirectory = async (p: string) => {
+		try {
+			const s = await fs.stat(p);
+			return s.isDirectory();
+		} catch {
+			return false;
+		}
+	};
+
+	const candidates = [path.join(home, "tmp"), "/tmp", "/var/tmp"];
+	for (const candidate of candidates) {
+		try {
+			if (!(await isDirectory(candidate))) {
+				continue;
+			}
+			setProjectDir(candidate);
+			return;
+		} catch {
+			// Try next candidate.
+		}
+	}
+
+	try {
+		const fallback = os.tmpdir();
+		if (fallback && normalizePath(fallback) !== cwd && (await isDirectory(fallback))) {
+			setProjectDir(fallback);
+		}
+	} catch {
+		// Ignore fallback errors.
+	}
+}
+
+export async function applyStartupCwd(parsed: Args): Promise<void> {
+	if (parsed.cwd) {
+		setProjectDir(parsed.cwd);
+		return;
+	}
+	await maybeAutoChdir(parsed);
+}
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index 491ed2c37..64d033fb4 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -5,9 +5,7 @@
  * createAgentSession() options. The SDK does the heavy lifting.
  */
 
-import * as fs from "node:fs/promises";
 import * as os from "node:os";
-import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
 import { EventLoopKeepalive } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
@@ -28,6 +26,7 @@ import { processFileArguments } from "./cli/file-processor";
 import { buildInitialMessage } from "./cli/initial-message";
 import { runListModelsCommand } from "./cli/list-models";
 import { selectSession } from "./cli/session-picker";
+import { applyStartupCwd } from "./cli/startup-cwd";
 import { findConfigFile } from "./config";
 import { ModelRegistry, ModelsConfigFile } from "./config/model-registry";
 import { resolveCliModel, resolveModelRoleValue, resolveModelScope, type ScopedModel } from "./config/model-resolver";
@@ -480,64 +479,6 @@ export async function createSessionManager(
 	return undefined;
 }
 
-async function maybeAutoChdir(parsed: Args): Promise<void> {
-	if (parsed.allowHome || parsed.cwd) {
-		return;
-	}
-
-	const home = os.homedir();
-	if (!home) {
-		return;
-	}
-
-	const normalizePath = normalizePathForComparison;
-
-	const cwd = normalizePath(getProjectDir());
-	const normalizedHome = normalizePath(home);
-	if (cwd !== normalizedHome) {
-		return;
-	}
-
-	const isDirectory = async (p: string) => {
-		try {
-			const s = await fs.stat(p);
-			return s.isDirectory();
-		} catch {
-			return false;
-		}
-	};
-
-	const candidates = [path.join(home, "tmp"), "/tmp", "/var/tmp"];
-	for (const candidate of candidates) {
-		try {
-			if (!(await isDirectory(candidate))) {
-				continue;
-			}
-			setProjectDir(candidate);
-			return;
-		} catch {
-			// Try next candidate.
-		}
-	}
-
-	try {
-		const fallback = os.tmpdir();
-		if (fallback && normalizePath(fallback) !== cwd && (await isDirectory(fallback))) {
-			setProjectDir(fallback);
-		}
-	} catch {
-		// Ignore fallback errors.
-	}
-}
-
-export async function applyStartupCwd(parsed: Args): Promise<void> {
-	if (parsed.cwd) {
-		setProjectDir(parsed.cwd);
-		return;
-	}
-	await maybeAutoChdir(parsed);
-}
-
 /** Discover SYSTEM.md file if no CLI system prompt was provided */
 function discoverSystemPromptFile(): string | undefined {
 	// Check project-local first (.omp/SYSTEM.md, .pi/SYSTEM.md legacy)
diff --git a/packages/coding-agent/test/cli-cwd-flag.test.ts b/packages/coding-agent/test/cli-cwd-flag.test.ts
index 7949ec5dc..973d61a4c 100644
--- a/packages/coding-agent/test/cli-cwd-flag.test.ts
+++ b/packages/coding-agent/test/cli-cwd-flag.test.ts
@@ -4,7 +4,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { getProjectDir, setProjectDir } from "@oh-my-pi/pi-utils";
 import { parseArgs } from "../src/cli/args";
-import { applyStartupCwd } from "../src/main";
+import { applyStartupCwd } from "../src/cli/startup-cwd";
 
 const originalProjectDir = getProjectDir();
 

From dd8b50649a5c3db197514ba1c8b4a7658bcbbbc9 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 21:07:43 +0000
Subject: [PATCH 174/181] fix(coding-agent): suppressed reviewer findings
 injection when schema rejects it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`finalizeSubprocessOutput` always spliced collected `report_finding`
entries onto a top-level `findings` array regardless of the active output
schema. A caller-supplied schema with `additionalProperties: false` and
no `findings` property would accept the raw payload in-tool (via the
`yield` validator, which only sees the pre-injection data) but then fail
post-mortem validation — emitting `schema_violation: findings: must not
be present` and propagating as a fatal `RuntimeError` through
`agent-bridge.ts` and the eval Python/JS preludes, collapsing the entire
workflow cell along with any prior successful subagent work.

`normalizeCompleteData` now takes the resolved validator and only
performs the injection when the augmented candidate validates. When the
schema rejects it, the raw payload is returned instead — which the in-
tool yield validator already accepted, so the lockstep guarantee
documented at the top of `output-schema-validator.ts` is honored.
Findings remain visible via the agent progress stream and JSONL
artifact, so no information is dropped when injection is suppressed.

Both finalize call paths (yield-success and no-yield fallback) now share
the single validator build instead of constructing it twice, and the
yield-path schema_violation branch is now reached only via the
explicit malformed-schema check, never via spurious findings rejection.

Fixes #2070
---
 packages/coding-agent/CHANGELOG.md            |   4 +
 packages/coding-agent/src/task/executor.ts    |  49 +++--
 .../coding-agent/test/tools/review.test.ts    | 167 ++++++++++++++++++
 3 files changed, 205 insertions(+), 15 deletions(-)

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 0243ed841..b66fce1cb 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Fixed reviewer-style subagent yields crashing the calling eval cell when a caller-supplied output schema declares `additionalProperties: false` without a `findings` property. `normalizeCompleteData` now consults the active validator before splicing collected `report_finding` entries onto the yielded payload, so injection is suppressed when the schema would reject it — keeping the executor's post-mortem validation in lockstep with the in-tool `yield` validation that already accepted the same raw payload ([#2070](https://github.com/can1357/oh-my-pi/issues/2070))
+
 ## [15.10.1] - 2026-06-07
 
 ### Added
diff --git a/packages/coding-agent/src/task/executor.ts b/packages/coding-agent/src/task/executor.ts
index 6f47ab87a..f197f534e 100644
--- a/packages/coding-agent/src/task/executor.ts
+++ b/packages/coding-agent/src/task/executor.ts
@@ -34,7 +34,7 @@ import { SessionManager } from "../session/session-manager";
 import { truncateTail } from "../session/streaming-output";
 import type { ContextFileEntry } from "../tools";
 import { normalizeSchema } from "../tools/jtd-to-json-schema";
-import { buildOutputValidator, summarizeValidationFailure } from "../tools/output-schema-validator";
+import { buildOutputValidator, type OutputValidator, summarizeValidationFailure } from "../tools/output-schema-validator";
 
 import { type ReportFindingDetails, toReviewFinding } from "../tools/review";
 import { ToolAbortError } from "../tools/tool-errors";
@@ -256,21 +256,40 @@ function extractCompletionData(parsed: unknown): unknown {
 	return parsed;
 }
 
-function normalizeCompleteData(data: unknown, reportFindings?: ReviewFinding[]): unknown {
-	let normalized = parseStringifiedJson(data ?? null);
+/**
+ * Resolve the final yielded payload, optionally splicing collected
+ * `report_finding` entries into a top-level `findings` array.
+ *
+ * Injection is suppressed when an active validator would reject the augmented
+ * payload (e.g. a caller-supplied schema with `additionalProperties: false`
+ * that does not declare `findings`). That keeps the in-tool yield validator
+ * (which only sees the raw, pre-injection data) in lockstep with this
+ * post-mortem validator — honoring the "accepted in-tool ⇒ accepted
+ * post-mortem" guarantee documented in `output-schema-validator.ts`. The
+ * dropped findings are still preserved verbatim in the agent's progress
+ * stream and JSONL artifact, so no information is lost when injection is
+ * suppressed.
+ */
+function normalizeCompleteData(
+	data: unknown,
+	reportFindings: ReviewFinding[] | undefined,
+	validator: OutputValidator | undefined,
+): unknown {
+	const normalized = parseStringifiedJson(data ?? null);
 	if (
-		Array.isArray(reportFindings) &&
-		reportFindings.length > 0 &&
-		normalized &&
-		typeof normalized === "object" &&
-		!Array.isArray(normalized)
+		!Array.isArray(reportFindings) ||
+		reportFindings.length === 0 ||
+		!normalized ||
+		typeof normalized !== "object" ||
+		Array.isArray(normalized)
 	) {
-		const record = normalized as Record<string, unknown>;
-		if (!("findings" in record)) {
-			normalized = { ...record, findings: reportFindings };
-		}
+		return normalized;
 	}
-	return normalized;
+	const record = normalized as Record<string, unknown>;
+	if ("findings" in record) return normalized;
+	const injected = { ...record, findings: reportFindings };
+	if (validator && !validator.validate(injected).success) return normalized;
+	return injected;
 }
 
 function resolveFallbackCompletion(rawOutput: string, outputSchema: unknown): { data: unknown } | null {
@@ -360,13 +379,13 @@ export function finalizeSubprocessOutput(args: FinalizeSubprocessOutputArgs): Fi
 			if (submitData === null || submitData === undefined) {
 				rawOutput = rawOutput ? `${SUBAGENT_WARNING_NULL_YIELD}\n\n${rawOutput}` : SUBAGENT_WARNING_NULL_YIELD;
 			} else {
-				const completeData = normalizeCompleteData(submitData, reportFindings);
 				const { validator, error: schemaError } = buildOutputValidator(outputSchema);
 				if (schemaError) {
 					rawOutput = `{"error":"schema_violation","message":"invalid output schema: ${schemaError.replace(/"/g, '\\"')}"}`;
 					stderr = `schema_violation: invalid output schema: ${schemaError}`;
 					exitCode = 1;
 				} else {
+					const completeData = normalizeCompleteData(submitData, reportFindings, validator);
 					const result = validator?.validate(completeData) ?? { success: true as const };
 					if (!result.success) {
 						const summary = summarizeValidationFailure(result, completeData, validator?.requiredFields ?? []);
@@ -393,8 +412,8 @@ export function finalizeSubprocessOutput(args: FinalizeSubprocessOutputArgs): Fi
 		const hasOutputSchema = normalizedSchema !== undefined && !schemaError;
 		const fallback = allowFallback ? resolveFallbackCompletion(rawOutput, outputSchema) : null;
 		if (fallback) {
-			const completeData = normalizeCompleteData(fallback.data, reportFindings);
 			const { validator } = buildOutputValidator(outputSchema);
+			const completeData = normalizeCompleteData(fallback.data, reportFindings, validator);
 			const result = validator?.validate(completeData) ?? { success: true as const };
 			if (!result.success) {
 				const summary = summarizeValidationFailure(result, completeData, validator?.requiredFields ?? []);
diff --git a/packages/coding-agent/test/tools/review.test.ts b/packages/coding-agent/test/tools/review.test.ts
index 989eec31c..c25ac9754 100644
--- a/packages/coding-agent/test/tools/review.test.ts
+++ b/packages/coding-agent/test/tools/review.test.ts
@@ -132,3 +132,170 @@ describe("toReviewFinding", () => {
 		expect(parsed.findings[0].priority).toBe(2);
 	});
 });
+
+describe("findings injection respects active output schema", () => {
+	const finding = toReviewFinding({
+		title: "[P0] Example finding",
+		body: "Details",
+		priority: "P0",
+		confidence: 0.95,
+		file_path: "/tmp/example.ts",
+		line_start: 10,
+		line_end: 12,
+	});
+
+	// Reproduces #2070: a caller-supplied JSON Schema with
+	// `additionalProperties: false` and no `findings` property is silently
+	// rejected post-mortem after the in-tool yield accepted it, because the
+	// executor auto-injects `findings` from `report_finding`. The injection
+	// must respect the active schema so that "accepted in-tool ⇒ accepted
+	// post-mortem" is honored.
+	it("suppresses findings injection when the schema forbids additional properties", () => {
+		const callerSchema = {
+			type: "object",
+			additionalProperties: false,
+			required: ["verdict", "acceptance_summary"],
+			properties: {
+				verdict: { enum: ["accept", "needs-work", "honest-stop"] },
+				acceptance_summary: { type: "string" },
+			},
+		};
+		const data = { verdict: "accept", acceptance_summary: "All good." };
+
+		const result = finalizeSubprocessOutput({
+			rawOutput: "",
+			exitCode: 0,
+			stderr: "",
+			doneAborted: false,
+			signalAborted: false,
+			yieldItems: [{ status: "success", data }],
+			reportFindings: [finding],
+			outputSchema: callerSchema,
+		});
+
+		expect(result.exitCode).toBe(0);
+		expect(result.stderr).toBe("");
+		const parsed = JSON.parse(result.rawOutput) as Record<string, unknown>;
+		expect(parsed).toEqual(data);
+		expect("findings" in parsed).toBe(false);
+	});
+
+	it("still injects findings when the schema declares them (bundled reviewer JTD)", () => {
+		// Mirrors the bundled reviewer agent's output: findings live under
+		// `optionalProperties`, so injection must continue to flow through.
+		const reviewerSchema = {
+			properties: {
+				overall_correctness: { enum: ["correct", "incorrect"] },
+				explanation: { type: "string" },
+				confidence: { type: "number" },
+			},
+			optionalProperties: {
+				findings: {
+					elements: {
+						properties: {
+							title: { type: "string" },
+							body: { type: "string" },
+							priority: { type: "number" },
+							confidence: { type: "number" },
+							file_path: { type: "string" },
+							line_start: { type: "number" },
+							line_end: { type: "number" },
+						},
+					},
+				},
+			},
+		};
+		const data = {
+			overall_correctness: "incorrect",
+			explanation: "Found one bug",
+			confidence: 0.9,
+		};
+
+		const result = finalizeSubprocessOutput({
+			rawOutput: "",
+			exitCode: 0,
+			stderr: "",
+			doneAborted: false,
+			signalAborted: false,
+			yieldItems: [{ status: "success", data }],
+			reportFindings: [finding],
+			outputSchema: reviewerSchema,
+		});
+
+		expect(result.exitCode).toBe(0);
+		expect(result.stderr).toBe("");
+		const parsed = JSON.parse(result.rawOutput) as { findings: Array<{ priority: number }> };
+		expect(parsed.findings).toHaveLength(1);
+		expect(parsed.findings[0].priority).toBe(0);
+	});
+
+	it("still injects findings when no schema is declared (legacy free-form)", () => {
+		const data = { note: "freeform" };
+
+		const result = finalizeSubprocessOutput({
+			rawOutput: "",
+			exitCode: 0,
+			stderr: "",
+			doneAborted: false,
+			signalAborted: false,
+			yieldItems: [{ status: "success", data }],
+			reportFindings: [finding],
+			outputSchema: undefined,
+		});
+
+		expect(result.exitCode).toBe(0);
+		const parsed = JSON.parse(result.rawOutput) as { findings?: unknown[] };
+		expect(parsed.findings).toHaveLength(1);
+	});
+
+	it("still injects findings when additionalProperties is open", () => {
+		const openSchema = {
+			type: "object",
+			required: ["verdict"],
+			properties: { verdict: { type: "string" } },
+		};
+		const data = { verdict: "accept" };
+
+		const result = finalizeSubprocessOutput({
+			rawOutput: "",
+			exitCode: 0,
+			stderr: "",
+			doneAborted: false,
+			signalAborted: false,
+			yieldItems: [{ status: "success", data }],
+			reportFindings: [finding],
+			outputSchema: openSchema,
+		});
+
+		expect(result.exitCode).toBe(0);
+		const parsed = JSON.parse(result.rawOutput) as { findings?: unknown[]; verdict: string };
+		expect(parsed.verdict).toBe("accept");
+		expect(parsed.findings).toHaveLength(1);
+	});
+
+	it("suppresses injection on the fallback (no-yield) path when the schema forbids it", () => {
+		const callerSchema = {
+			type: "object",
+			additionalProperties: false,
+			required: ["verdict"],
+			properties: { verdict: { type: "string" } },
+		};
+		const rawJson = JSON.stringify({ data: { verdict: "accept" } });
+
+		const result = finalizeSubprocessOutput({
+			rawOutput: rawJson,
+			exitCode: 0,
+			stderr: "",
+			doneAborted: false,
+			signalAborted: false,
+			yieldItems: undefined,
+			reportFindings: [finding],
+			outputSchema: callerSchema,
+		});
+
+		expect(result.exitCode).toBe(0);
+		expect(result.stderr).toBe("");
+		const parsed = JSON.parse(result.rawOutput) as Record<string, unknown>;
+		expect(parsed).toEqual({ verdict: "accept" });
+	});
+});

From 0f243f4505fef0e74fb2100932f0968d1bd6fdcc Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Sun, 7 Jun 2026 21:07:48 +0000
Subject: [PATCH 175/181] style: bun run fix

---
 packages/coding-agent/src/task/executor.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/coding-agent/src/task/executor.ts b/packages/coding-agent/src/task/executor.ts
index f197f534e..f6450f2f6 100644
--- a/packages/coding-agent/src/task/executor.ts
+++ b/packages/coding-agent/src/task/executor.ts
@@ -34,7 +34,11 @@ import { SessionManager } from "../session/session-manager";
 import { truncateTail } from "../session/streaming-output";
 import type { ContextFileEntry } from "../tools";
 import { normalizeSchema } from "../tools/jtd-to-json-schema";
-import { buildOutputValidator, type OutputValidator, summarizeValidationFailure } from "../tools/output-schema-validator";
+import {
+	buildOutputValidator,
+	type OutputValidator,
+	summarizeValidationFailure,
+} from "../tools/output-schema-validator";
 
 import { type ReportFindingDetails, toReviewFinding } from "../tools/review";
 import { ToolAbortError } from "../tools/tool-errors";

From 7ffec148638aad2ea5bddb295e369c9dbc8af7d9 Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Mon, 8 Jun 2026 00:32:47 +0200
Subject: [PATCH 176/181] ci: force JavaScript actions to run on Node 24

---
 .github/workflows/ci.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 09245ef0a..fad426fb6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -16,6 +16,9 @@ concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: true
 
+env:
+   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
    # scripts/release.ts pushes the version-bump commit and its `v*` tag
    # atomically (`git push --atomic origin main refs/tags/v*`), so a release

From 5ddae194b4f303000102f38038b6c7a7880a8e7c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Mon, 8 Jun 2026 00:33:42 +0200
Subject: [PATCH 177/181] test(ai): cover impersonated_service_account ADC
 Vertex auth flow

Add unit and E2E coverage for the impersonated_service_account ADC path:
RS256 JWT-signed service_account sources, IAM URL reconstruction, delegate
forwarding, and end-to-end routing so the impersonated token (not the
source token) authorizes the Vertex request. Reflow google-auth.ts to match.
---
 .../providers/__tests__/google-auth.test.ts   | 171 ++++++++++++++----
 packages/ai/src/providers/google-auth.ts      |  27 +--
 packages/ai/test/stream.test.ts               | 132 ++++++++++++++
 3 files changed, 285 insertions(+), 45 deletions(-)

diff --git a/packages/ai/src/providers/__tests__/google-auth.test.ts b/packages/ai/src/providers/__tests__/google-auth.test.ts
index e6f1aea53..8b72ffcc4 100644
--- a/packages/ai/src/providers/__tests__/google-auth.test.ts
+++ b/packages/ai/src/providers/__tests__/google-auth.test.ts
@@ -1,41 +1,144 @@
-import { describe, expect, it, mock } from "bun:test";
-import { getVertexAccessToken, __resetVertexTokenCache } from "../google-auth";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { Buffer } from "node:buffer";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { FetchImpl } from "../../types";
+import { __resetVertexTokenCache, getVertexAccessToken } from "../google-auth";
 
-describe("getVertexAccessToken", () => {
-	it("should exchange impersonated ADC correctly", async () => {
+const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+
+/** Generate a real RS256 private key so signJwtRs256 / pemToPkcs8 run for real. */
+async function generateServiceAccountPem(): Promise<string> {
+	const keyPair = (await globalThis.crypto.subtle.generateKey(
+		{ name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" },
+		true,
+		["sign", "verify"],
+	)) as CryptoKeyPair;
+	const pkcs8 = new Uint8Array(await globalThis.crypto.subtle.exportKey("pkcs8", keyPair.privateKey));
+	const body = (
+		Buffer.from(pkcs8)
+			.toString("base64")
+			.match(/.{1,64}/g) ?? []
+	).join("\n");
+	return `-----BEGIN PRIVATE KEY-----\n${body}\n-----END PRIVATE KEY-----\n`;
+}
+
+function urlOf(input: string | URL | Request): string {
+	if (typeof input === "string") return input;
+	if (input instanceof URL) return input.toString();
+	return input.url;
+}
+
+describe("getVertexAccessToken impersonated_service_account ADC", () => {
+	let tmpDir: string;
+	let originalGac: string | undefined;
+
+	beforeEach(async () => {
 		__resetVertexTokenCache();
-		Bun.env.GOOGLE_APPLICATION_CREDENTIALS = "/tmp/mock-impersonated-adc.json";
-		
-		await Bun.write("/tmp/mock-impersonated-adc.json", JSON.stringify({
-			type: "impersonated_service_account",
-			service_account_impersonation_url: "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken",
-			source_credentials: {
-				type: "authorized_user",
-				client_id: "client-id",
-				client_secret: "client-secret",
-				refresh_token: "refresh-token"
-			},
-			delegates: ["delegate1"]
-		}));
+		originalGac = Bun.env.GOOGLE_APPLICATION_CREDENTIALS;
+		tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-vertex-adc-"));
+	});
 
-		let fetchCalls: any[] = [];
-		const mockFetch = mock(async (url: string, opts: any) => {
-			fetchCalls.push({ url, opts });
-			if (url.includes("oauth2.googleapis.com/token")) {
-				return { ok: true, json: async () => ({ access_token: "source-token", expires_in: 3600 }) };
-			}
-			if (url.includes("iamcredentials.googleapis.com")) {
-				return { ok: true, json: async () => ({ accessToken: "impersonated-token", expireTime: new Date(Date.now() + 3600000).toISOString() }) };
-			}
-			return { ok: false };
-		}) as any;
+	afterEach(async () => {
+		__resetVertexTokenCache();
+		if (originalGac === undefined) delete Bun.env.GOOGLE_APPLICATION_CREDENTIALS;
+		else Bun.env.GOOGLE_APPLICATION_CREDENTIALS = originalGac;
+		await fs.rm(tmpDir, { recursive: true, force: true });
+	});
 
-		const token = await getVertexAccessToken({ fetch: mockFetch });
+	it("rejects a malformed service_account_impersonation_url before any network call", async () => {
+		const adcPath = path.join(tmpDir, "impersonated-bad-url.json");
+		await Bun.write(
+			adcPath,
+			JSON.stringify({
+				type: "impersonated_service_account",
+				// Missing the trailing ":generateAccessToken" the principal parser requires.
+				service_account_impersonation_url:
+					"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com",
+				source_credentials: {
+					type: "authorized_user",
+					client_id: "client-id",
+					client_secret: "client-secret",
+					refresh_token: "refresh-token",
+				},
+			}),
+		);
+		Bun.env.GOOGLE_APPLICATION_CREDENTIALS = adcPath;
+
+		const calls: string[] = [];
+		const fetchImpl: FetchImpl = async input => {
+			calls.push(urlOf(input));
+			return new Response("{}");
+		};
+
+		// The principal is parsed before the source exchange, so a bad URL must fail
+		// up front rather than after burning a source-token round trip.
+		await expect(getVertexAccessToken({ fetch: fetchImpl })).rejects.toBeInstanceOf(RangeError);
+		expect(calls).toEqual([]);
+	});
+
+	it("signs an RS256 JWT for a service_account source and reconstructs the IAM URL", async () => {
+		const pem = await generateServiceAccountPem();
+		const adcPath = path.join(tmpDir, "impersonated-sa.json");
+		await Bun.write(
+			adcPath,
+			JSON.stringify({
+				type: "impersonated_service_account",
+				// Non-canonical project segment proves the request URL is rebuilt, not echoed.
+				service_account_impersonation_url:
+					"https://iamcredentials.googleapis.com/v1/projects/explicit-proj/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken",
+				source_credentials: {
+					type: "service_account",
+					client_email: "source@project.iam.gserviceaccount.com",
+					private_key: pem,
+					private_key_id: "key-1",
+				},
+				// delegates intentionally omitted — the IAM body must default to [].
+			}),
+		);
+		Bun.env.GOOGLE_APPLICATION_CREDENTIALS = adcPath;
+
+		const calls: { url: string; init?: RequestInit }[] = [];
+		const fetchImpl: FetchImpl = async (input, init) => {
+			const url = urlOf(input);
+			calls.push({ url, init });
+			if (url === "https://oauth2.googleapis.com/token") {
+				return new Response(JSON.stringify({ access_token: "sa-source-token", expires_in: 3600 }));
+			}
+			if (url.startsWith("https://iamcredentials.googleapis.com/")) {
+				return new Response(
+					JSON.stringify({
+						accessToken: "impersonated-token",
+						expireTime: new Date(Date.now() + 3_600_000).toISOString(),
+					}),
+				);
+			}
+			return new Response("unexpected", { status: 404 });
+		};
+
+		const token = await getVertexAccessToken({ fetch: fetchImpl });
 		expect(token).toBe("impersonated-token");
-		expect(fetchCalls.length).toBe(2);
-		expect(fetchCalls[0].url).toContain("oauth2.googleapis.com");
-		expect(fetchCalls[1].url).toBe("https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken");
-		expect(fetchCalls[1].opts.headers.Authorization).toBe("Bearer source-token");
-		expect(JSON.parse(fetchCalls[1].opts.body).delegates).toEqual(["delegate1"]);
+
+		// Source JWT exchange happens first, then the impersonation exchange.
+		expect(calls.map(c => c.url)).toEqual([
+			"https://oauth2.googleapis.com/token",
+			"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken",
+		]);
+
+		// Source credential is exchanged via a signed JWT bearer assertion, not a refresh grant.
+		const sourceBody = new URLSearchParams(String(calls[0].init?.body));
+		expect(sourceBody.get("grant_type")).toBe(JWT_BEARER_GRANT);
+		expect((sourceBody.get("assertion") ?? "").split(".")).toHaveLength(3);
+
+		// The IAM call carries the source-derived bearer token and defaults delegates to [].
+		const iamHeaders = calls[1].init?.headers as Record<string, string>;
+		expect(iamHeaders.Authorization).toBe("Bearer sa-source-token");
+		expect(JSON.parse(String(calls[1].init?.body))).toEqual({
+			delegates: [],
+			scope: [CLOUD_PLATFORM_SCOPE],
+			lifetime: "3600s",
+		});
 	});
 });
diff --git a/packages/ai/src/providers/google-auth.ts b/packages/ai/src/providers/google-auth.ts
index 39a81922c..0af7ddea8 100644
--- a/packages/ai/src/providers/google-auth.ts
+++ b/packages/ai/src/providers/google-auth.ts
@@ -212,9 +212,7 @@ async function resolveAccessTokenUncached(
 			);
 			const targetPrincipal = targetPrincipalMatch?.groups?.target;
 			if (!targetPrincipal) {
-				throw new RangeError(
-					`Cannot extract target principal from ${creds.service_account_impersonation_url}`,
-				);
+				throw new RangeError(`Cannot extract target principal from ${creds.service_account_impersonation_url}`);
 			}
 
 			const sourceToken =
@@ -222,15 +220,22 @@ async function resolveAccessTokenUncached(
 					? await exchangeJwtForToken(creds.source_credentials, signal, fetchImpl)
 					: await exchangeRefreshToken(creds.source_credentials, signal, fetchImpl);
 
-			const response = await fetchImpl(`https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${targetPrincipal}:generateAccessToken`, {
-				method: "POST",
-				headers: {
-					"Content-Type": "application/json",
-					Authorization: `Bearer ${sourceToken.access_token}`,
+			const response = await fetchImpl(
+				`https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${targetPrincipal}:generateAccessToken`,
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						Authorization: `Bearer ${sourceToken.access_token}`,
+					},
+					body: JSON.stringify({
+						delegates: creds.delegates ?? [],
+						scope: [CLOUD_PLATFORM_SCOPE],
+						lifetime: "3600s",
+					}),
+					signal,
 				},
-				body: JSON.stringify({ delegates: creds.delegates ?? [], scope: [CLOUD_PLATFORM_SCOPE], lifetime: "3600s" }),
-				signal,
-			});
+			);
 			if (!response.ok) {
 				const detail = await response.text().catch(() => "");
 				throw new Error(`Google Impersonation token exchange failed (${response.status}): ${detail}`);
diff --git a/packages/ai/test/stream.test.ts b/packages/ai/test/stream.test.ts
index aaf0c6070..3d5325d42 100644
--- a/packages/ai/test/stream.test.ts
+++ b/packages/ai/test/stream.test.ts
@@ -652,6 +652,138 @@ describe("Generate E2E Tests", () => {
 				else Bun.env.GOOGLE_APPLICATION_CREDENTIALS = originalGac;
 			}
 		});
+
+		it("routes impersonated_service_account ADC through IAM to the Vertex request", async () => {
+			const originalProject = Bun.env.GOOGLE_CLOUD_PROJECT;
+			const originalGcpProject = Bun.env.GCP_PROJECT;
+			const originalGcloudProject = Bun.env.GCLOUD_PROJECT;
+			const originalVertexLocation = Bun.env.GOOGLE_VERTEX_LOCATION;
+			const originalCloudLocation = Bun.env.GOOGLE_CLOUD_LOCATION;
+			const originalLocation = Bun.env.VERTEX_LOCATION;
+			const originalApiKey = Bun.env.GOOGLE_CLOUD_API_KEY;
+			const originalGac = Bun.env.GOOGLE_APPLICATION_CREDENTIALS;
+			const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "omp-vertex-impersonation-"));
+			const adcPath = path.join(tmpDir, "impersonated-adc.json");
+			await Bun.write(
+				adcPath,
+				JSON.stringify({
+					type: "impersonated_service_account",
+					service_account_impersonation_url:
+						"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken",
+					source_credentials: {
+						type: "authorized_user",
+						client_id: "client-id",
+						client_secret: "client-secret",
+						refresh_token: "refresh-token",
+					},
+					delegates: ["projects/-/serviceAccounts/delegate@project.iam.gserviceaccount.com"],
+				}),
+			);
+			const model: Model<"anthropic-messages"> = {
+				id: "claude-sonnet-4@20250514",
+				name: "Claude Sonnet 4",
+				api: "anthropic-messages",
+				provider: "google-vertex",
+				baseUrl:
+					"https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/anthropic/models/claude-sonnet-4@20250514:streamRawPredict",
+				reasoning: true,
+				input: ["text", "image"],
+				cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+				contextWindow: 200_000,
+				maxTokens: 64_000,
+			};
+			const callOrder: string[] = [];
+			let iamRequest: { url: string; authorization: string | null; body: unknown } | undefined;
+			const captured = Promise.withResolvers<{ url: string; authorization: string | null }>();
+
+			try {
+				__resetVertexTokenCache();
+				Bun.env.GOOGLE_CLOUD_PROJECT = "vertex-project";
+				Bun.env.GOOGLE_VERTEX_LOCATION = "global";
+				delete Bun.env.GCP_PROJECT;
+				delete Bun.env.GCLOUD_PROJECT;
+				delete Bun.env.GOOGLE_CLOUD_LOCATION;
+				delete Bun.env.VERTEX_LOCATION;
+				delete Bun.env.GOOGLE_CLOUD_API_KEY;
+				Bun.env.GOOGLE_APPLICATION_CREDENTIALS = adcPath;
+
+				const events = stream(
+					model,
+					{ messages: [{ role: "user", content: "Hello", timestamp: Date.now() }] },
+					{
+						apiKey: "<authenticated>",
+						fetch: async (input, init) => {
+							const url = input instanceof Request ? input.url : input.toString();
+							const headers = input instanceof Request ? input.headers : new Headers(init?.headers);
+							if (url === "https://oauth2.googleapis.com/token") {
+								callOrder.push("source");
+								return new Response(JSON.stringify({ access_token: "source-token", expires_in: 3600 }));
+							}
+							if (url.startsWith("https://iamcredentials.googleapis.com/")) {
+								callOrder.push("iam");
+								const bodyText =
+									input instanceof Request ? await input.clone().text() : String(init?.body ?? "");
+								iamRequest = { url, authorization: headers.get("authorization"), body: JSON.parse(bodyText) };
+								return new Response(
+									JSON.stringify({
+										accessToken: "impersonated-token",
+										expireTime: new Date(Date.now() + 3_600_000).toISOString(),
+									}),
+								);
+							}
+							callOrder.push("vertex");
+							captured.resolve({ url, authorization: headers.get("authorization") });
+							return new Response(JSON.stringify({ error: { message: "stop after capture" } }), { status: 400 });
+						},
+					},
+				);
+
+				for await (const _event of events) {
+				}
+
+				const request = await captured.promise;
+
+				// Source refresh, then IAM generateAccessToken, then the actual Vertex call.
+				expect(callOrder).toEqual(["source", "iam", "vertex"]);
+
+				// IAM exchange is authorized by the freshly minted source token, posts the
+				// reconstructed canonical URL, and forwards the configured delegates verbatim.
+				expect(iamRequest?.url).toBe(
+					"https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/target@project.iam.gserviceaccount.com:generateAccessToken",
+				);
+				expect(iamRequest?.authorization).toBe("Bearer source-token");
+				expect(iamRequest?.body).toEqual({
+					delegates: ["projects/-/serviceAccounts/delegate@project.iam.gserviceaccount.com"],
+					scope: ["https://www.googleapis.com/auth/cloud-platform"],
+					lifetime: "3600s",
+				});
+
+				// The impersonated token (not the source token) authorizes the Vertex request.
+				expect(request.url).toBe(
+					"https://aiplatform.googleapis.com/v1/projects/vertex-project/locations/global/publishers/anthropic/models/claude-sonnet-4@20250514:streamRawPredict",
+				);
+				expect(request.authorization).toBe("Bearer impersonated-token");
+			} finally {
+				__resetVertexTokenCache();
+				await fs.rm(tmpDir, { recursive: true, force: true });
+				if (originalProject === undefined) delete Bun.env.GOOGLE_CLOUD_PROJECT;
+				else Bun.env.GOOGLE_CLOUD_PROJECT = originalProject;
+				if (originalGcpProject === undefined) delete Bun.env.GCP_PROJECT;
+				else Bun.env.GCP_PROJECT = originalGcpProject;
+				if (originalGcloudProject === undefined) delete Bun.env.GCLOUD_PROJECT;
+				else Bun.env.GCLOUD_PROJECT = originalGcloudProject;
+				if (originalVertexLocation === undefined) delete Bun.env.GOOGLE_VERTEX_LOCATION;
+				else Bun.env.GOOGLE_VERTEX_LOCATION = originalVertexLocation;
+				if (originalCloudLocation === undefined) delete Bun.env.GOOGLE_CLOUD_LOCATION;
+				else Bun.env.GOOGLE_CLOUD_LOCATION = originalCloudLocation;
+				if (originalLocation === undefined) delete Bun.env.VERTEX_LOCATION;
+				else Bun.env.VERTEX_LOCATION = originalLocation;
+				if (originalApiKey === undefined) delete Bun.env.GOOGLE_CLOUD_API_KEY;
+				else Bun.env.GOOGLE_CLOUD_API_KEY = originalApiKey;
+				if (originalGac === undefined) delete Bun.env.GOOGLE_APPLICATION_CREDENTIALS;
+				else Bun.env.GOOGLE_APPLICATION_CREDENTIALS = originalGac;
+			}
+		});
 	});
 
 	describe("Google Vertex Provider (gemini-3-flash-preview)", () => {

From cfa9a2d53e6bfa9ba05ac95cceaef3b0c4ebd1b5 Mon Sep 17 00:00:00 2001
From: bling <291592093+blingdivinity@users.noreply.github.com>
Date: Sun, 7 Jun 2026 11:34:46 -0400
Subject: [PATCH 178/181] fix(coding-agent): resume sessions after a worktree
 move/rename

When a session's working directory is moved or renamed (e.g. `git worktree
move`), the session file stays under the old cwd-encoded bucket while the new
directory is empty. Resuming was lossy:

- `--continue` rejected the terminal breadcrumb purely on cwd mismatch and then
  found nothing in the new bucket, silently starting a fresh empty session.
- cross-project `--resume <id>` only offered to *fork* (duplicate) the session
  into the new directory, forcing manual id selection and leaving a stale copy.

Detect relocation via the strong, low-false-positive signal "recorded cwd no
longer exists on disk" and re-root in place with the existing `moveTo()`:

- `continueRecent` re-roots the terminal's last session into the current
  directory when its recorded cwd is gone and the new location has no sessions
  of its own (otherwise behavior is unchanged). `readTerminalBreadcrumb` is
  refactored into `readTerminalBreadcrumbEntry` returning the raw cwd +
  session file so callers can interpret a cwd mismatch.
- cross-project `--resume <id>` offers "Move (re-root)" instead of fork when the
  source directory is gone; a still-existing different project still forks.

Tests: continue-relocation (re-root on move, no-hijack on plain cd, prefer
local recent) and cross-project move-vs-fork routing.
---
 ...ion-operations-export-share-fork-resume.md |  22 +-
 packages/coding-agent/CHANGELOG.md            |   4 +
 packages/coding-agent/src/main.ts             |  42 +++-
 .../src/session/session-manager.ts            | 100 ++++++--
 .../test/main-cross-project-resume.test.ts    |  84 +++++--
 .../continue-relocation.test.ts               | 233 ++++++++++++++++++
 6 files changed, 433 insertions(+), 52 deletions(-)
 create mode 100644 packages/coding-agent/test/session-manager/continue-relocation.test.ts

diff --git a/docs/session-operations-export-share-fork-resume.md b/docs/session-operations-export-share-fork-resume.md
index 0d6de4f70..a82ef075d 100644
--- a/docs/session-operations-export-share-fork-resume.md
+++ b/docs/session-operations-export-share-fork-resume.md
@@ -24,8 +24,8 @@ This document describes operator-visible behavior for session export/share/fork/
 | `--fork <id\|path>`                     | CLI startup               | Yes after session creation            | Creates a new session fork from the selected source into current cwd/session dir   | None                                                            |
 | `/resume`                               | Interactive slash command | Yes (active in-memory state replaced) | Switches to selected existing session file                                         | None                                                            |
 | `--resume`                              | CLI startup picker        | Yes after session creation            | Opens selected existing session file                                               | None                                                            |
-| `--resume <id\|path>`                   | CLI startup               | Yes after session creation            | Opens existing session; global cross-project match can fork into current project   | None                                                            |
-| `--continue`                            | CLI startup               | Yes after session creation            | Opens terminal breadcrumb or most-recent session; creates new one if none exists   | None                                                            |
+| `--resume <id\|path>`                   | CLI startup               | Yes after session creation            | Opens existing session; global cross-project match re-roots (moved dir) or forks into current project   | None                                                            |
+| `--continue`                            | CLI startup               | Yes after session creation            | Opens terminal breadcrumb (re-roots it if its dir was moved) or most-recent session; creates new one if none exists   | None                                                            |
 
 ## Export and dump
 
@@ -215,19 +215,23 @@ Notes:
 
 Cross-project id match behavior:
 
-- If matched session cwd differs from current cwd, CLI asks:
-  - `Session found in different project ... Fork into current directory? [y/N]`
-- On yes: `SessionManager.forkFrom(match.path, cwd, sessionDir)` creates a new local forked file.
-- On no/non-TTY default: command errors.
+- If matched session cwd differs from current cwd, behavior depends on whether the matched session's recorded directory still exists:
+  - **Directory gone (moved/renamed, e.g. `git worktree move`)**: CLI asks `Session's directory no longer exists (...). Move (re-root) it into the current directory? [Y/n]`.
+    - On yes (default): `SessionManager.open(match.path)` then `manager.moveTo(cwd)` re-roots the existing session into the current directory (no duplicate file).
+    - On no: command cancels (returns no session). On non-TTY: command errors.
+  - **Directory still exists (genuinely different project)**: CLI asks `Session found in different project ... Fork into current directory? [y/N]`.
+    - On yes: `SessionManager.forkFrom(match.path, cwd, sessionDir)` creates a new local forked file.
+    - On no: command cancels. On non-TTY: command errors.
 
 ## CLI `--continue`
 
 `SessionManager.continueRecent(cwd, sessionDir)`:
 
 1. Resolves session dir for current cwd.
-2. Reads terminal-scoped breadcrumb first.
-3. Falls back to most recently modified session file.
-4. Opens found session; if none exists, creates new session.
+2. Reads the terminal-scoped breadcrumb.
+3. If the breadcrumb points at a session recorded under a different cwd whose directory no longer exists (moved/renamed) **and** the current directory has no sessions of its own, re-roots that session into the current directory via `moveTo` instead of starting fresh.
+4. Otherwise, if the breadcrumb's cwd matches the current cwd, uses the breadcrumb session; else falls back to the most recently modified session file.
+5. Opens the found session; if none exists, creates a new session.
 
 This is startup-only behavior; there is no interactive `/continue` slash command.
 
diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index 8b29b5f31..a56a615d5 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -17,6 +17,10 @@
 
 - Fixed MCP tools hanging in non-yolo modes by declaring `approval = "write"` on `MCPTool` and `DeferredMCPTool`, and propagating the `approval` property through `customToolToDefinition()` in `sdk.ts`
 
+### Fixed
+
+- Fixed session resumption after a working directory is moved/renamed (e.g. `git worktree move`): `--continue` now re-roots the terminal's last session into the new directory when its original directory no longer exists, instead of silently starting a fresh empty session; cross-project `--resume <id>` offers to move (re-root) the session rather than only forking a duplicate copy when the source directory is gone
+
 ## [15.10.1] - 2026-06-07
 
 ### Added
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index 8d4d30b46..507c59e70 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -5,6 +5,7 @@
  * createAgentSession() options. The SDK does the heavy lifting.
  */
 
+import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -344,11 +345,11 @@ async function runInteractiveMode(
 	}
 }
 
-type ForkSessionPromptResult = "accepted" | "declined" | "unavailable";
+type SessionPromptResult = "accepted" | "declined" | "unavailable";
 
-type ForkSessionPrompt = (session: SessionInfo) => Promise<ForkSessionPromptResult>;
+type SessionPrompt = (session: SessionInfo) => Promise<SessionPromptResult>;
 
-async function promptForkSession(session: SessionInfo): Promise<ForkSessionPromptResult> {
+async function promptForkSession(session: SessionInfo): Promise<SessionPromptResult> {
 	if (!process.stdin.isTTY) {
 		return "unavailable";
 	}
@@ -362,6 +363,20 @@ async function promptForkSession(session: SessionInfo): Promise<ForkSessionPromp
 	}
 }
 
+async function promptMoveSession(session: SessionInfo): Promise<SessionPromptResult> {
+	if (!process.stdin.isTTY) {
+		return "unavailable";
+	}
+	const message = `Session's directory no longer exists (${session.cwd}). Move (re-root) it into the current directory? [Y/n] `;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		const answer = (await rl.question(message)).trim().toLowerCase();
+		return answer === "" || answer === "y" || answer === "yes" ? "accepted" : "declined";
+	} finally {
+		rl.close();
+	}
+}
+
 async function getChangelogForDisplay(parsed: Args): Promise<string | undefined> {
 	if (parsed.continue || parsed.resume) {
 		return undefined;
@@ -407,7 +422,8 @@ export async function createSessionManager(
 	parsed: Args,
 	cwd: string,
 	activeSettings: Settings = settings,
-	askToForkSession: ForkSessionPrompt = promptForkSession,
+	askToForkSession: SessionPrompt = promptForkSession,
+	askToMoveSession: SessionPrompt = promptMoveSession,
 ): Promise<SessionManager | undefined> {
 	if (parsed.fork) {
 		if (parsed.noSession) {
@@ -440,6 +456,24 @@ export async function createSessionManager(
 			const normalizedCwd = normalizePathForComparison(cwd);
 			const normalizedMatchCwd = normalizePathForComparison(match.session.cwd || cwd);
 			if (normalizedCwd !== normalizedMatchCwd) {
+				// If the session's recorded directory no longer exists, it was almost
+				// certainly moved/renamed (e.g. `git worktree move`). Re-root the existing
+				// session here instead of forking a duplicate copy.
+				const sourceCwd = match.session.cwd;
+				if (sourceCwd && !fsSync.existsSync(sourceCwd)) {
+					const movePromptResult = await askToMoveSession(match.session);
+					if (movePromptResult === "unavailable") {
+						throw new Error(
+							`Session "${sessionArg}" belongs to a directory that no longer exists (${sourceCwd}); run interactively to move it into the current project.`,
+						);
+					}
+					if (movePromptResult === "declined") {
+						return undefined;
+					}
+					const manager = await SessionManager.open(match.session.path, parsed.sessionDir);
+					await manager.moveTo(cwd, parsed.sessionDir);
+					return manager;
+				}
 				const forkPromptResult = await askToForkSession(match.session);
 				if (forkPromptResult === "unavailable") {
 					throw new Error(
diff --git a/packages/coding-agent/src/session/session-manager.ts b/packages/coding-agent/src/session/session-manager.ts
index 61f78cdcc..58f5a71bb 100644
--- a/packages/coding-agent/src/session/session-manager.ts
+++ b/packages/coding-agent/src/session/session-manager.ts
@@ -845,11 +845,18 @@ function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void {
 	Bun.write(breadcrumbFile, content).catch(() => {});
 }
 
+interface TerminalBreadcrumb {
+	cwd: string;
+	sessionFile: string;
+}
+
 /**
- * Read the terminal breadcrumb for the current terminal, scoped to a cwd.
- * Returns the session file path if it exists and matches the cwd, null otherwise.
+ * Read the raw terminal breadcrumb for the current terminal.
+ * Returns the recorded cwd + session file (verified to exist) regardless of
+ * whether the recorded cwd still matches the current one. Callers decide how
+ * to interpret a cwd mismatch (e.g. a moved/renamed worktree).
  */
-async function readTerminalBreadcrumb(cwd: string): Promise<string | null> {
+async function readTerminalBreadcrumbEntry(): Promise<TerminalBreadcrumb | null> {
 	const terminalId = getTerminalId();
 	if (!terminalId) return null;
 
@@ -862,12 +869,9 @@ async function readTerminalBreadcrumb(cwd: string): Promise<string | null> {
 		const breadcrumbCwd = lines[0];
 		const sessionFile = lines[1];
 
-		// Only return if cwd matches (user might have cd'd)
-		if (path.resolve(breadcrumbCwd) !== path.resolve(cwd)) return null;
-
 		// Verify the session file still exists
 		const stat = fs.statSync(sessionFile, { throwIfNoEntry: false });
-		if (stat?.isFile()) return sessionFile;
+		if (stat?.isFile()) return { cwd: breadcrumbCwd, sessionFile };
 	} catch (err) {
 		if (!isEnoent(err)) logger.debug("Terminal breadcrumb read failed", { err });
 		// Breadcrumb doesn't exist or is corrupt — fall through
@@ -2163,19 +2167,24 @@ export class SessionManager {
 	/**
 	 * Move the session to a new working directory.
 	 * Moves session files and artifacts on disk, updates all internal references,
-	 * and rewrites the session header with the new cwd.
+	 * and rewrites the session header with the new cwd. When provided,
+	 * `targetSessionDir` is used instead of deriving the default directory for
+	 * the new cwd (for `--continue --session-dir` / `--resume --session-dir`).
 	 */
-	async moveTo(newCwd: string): Promise<void> {
+	async moveTo(newCwd: string, targetSessionDir?: string): Promise<void> {
 		const resolvedCwd = path.resolve(newCwd);
-		if (resolvedCwd === this.cwd) return;
+		if (resolvedCwd === this.cwd && (!targetSessionDir || path.resolve(targetSessionDir) === this.sessionDir)) return;
 
 		const managedSessionsRoot = resolveManagedSessionRoot(this.sessionDir, this.cwd);
-		const newSessionDir = managedSessionsRoot
-			? computeDefaultSessionDir(resolvedCwd, this.storage, managedSessionsRoot)
-			: computeDefaultSessionDir(resolvedCwd, this.storage);
+		const newSessionDir = targetSessionDir
+			? path.resolve(targetSessionDir)
+			: managedSessionsRoot
+				? computeDefaultSessionDir(resolvedCwd, this.storage, managedSessionsRoot)
+				: computeDefaultSessionDir(resolvedCwd, this.storage);
 		let hadSessionFile = false;
 
 		if (this.persist && this.#sessionFile) {
+			this.storage.ensureDirSync(newSessionDir);
 			// Close the persist writer before moving files
 			await this.#closePersistWriter();
 			this.#persistChain = Promise.resolve();
@@ -2186,25 +2195,29 @@ export class SessionManager {
 			const newSessionFile = path.join(newSessionDir, path.basename(oldSessionFile));
 			const oldArtifactDir = oldSessionFile.slice(0, -6); // strip .jsonl
 			const newArtifactDir = newSessionFile.slice(0, -6);
+			const sameSessionFile = path.resolve(oldSessionFile) === path.resolve(newSessionFile);
+			const sameArtifactDir = path.resolve(oldArtifactDir) === path.resolve(newArtifactDir);
 			hadSessionFile = this.storage.existsSync(oldSessionFile);
 			let movedSessionFile = false;
 			let movedArtifactDir = false;
 
 			try {
 				// Guard: session file may not exist yet (no assistant messages persisted)
-				if (hadSessionFile) {
+				if (hadSessionFile && !sameSessionFile) {
 					await fs.promises.rename(oldSessionFile, newSessionFile);
 					movedSessionFile = true;
 				}
 
-				try {
-					const stat = await fs.promises.stat(oldArtifactDir);
-					if (stat.isDirectory()) {
-						await fs.promises.rename(oldArtifactDir, newArtifactDir);
-						movedArtifactDir = true;
+				if (!sameArtifactDir) {
+					try {
+						const stat = await fs.promises.stat(oldArtifactDir);
+						if (stat.isDirectory()) {
+							await fs.promises.rename(oldArtifactDir, newArtifactDir);
+							movedArtifactDir = true;
+						}
+					} catch (err) {
+						if (!isEnoent(err)) throw err;
 					}
-				} catch (err) {
-					if (!isEnoent(err)) throw err;
 				}
 			} catch (err) {
 				if (movedArtifactDir) {
@@ -3491,8 +3504,49 @@ export class SessionManager {
 	): Promise<SessionManager> {
 		const dir = sessionDir ?? SessionManager.getDefaultSessionDir(cwd, undefined, storage);
 		// Prefer terminal-scoped breadcrumb (handles concurrent sessions correctly)
-		const terminalSession = await readTerminalBreadcrumb(cwd);
-		const mostRecent = terminalSession ?? (await findMostRecentSession(dir, storage));
+		const breadcrumb = await readTerminalBreadcrumbEntry();
+		const breadcrumbCwd = breadcrumb ? path.resolve(breadcrumb.cwd) : undefined;
+		const resolvedCwd = path.resolve(cwd);
+		let mostRecent: string | null | undefined;
+		if (breadcrumb && breadcrumbCwd !== resolvedCwd) {
+			// The terminal's last session was started in a different cwd. If that cwd no
+			// longer exists (e.g. `git worktree move`/dir rename) and the new location has
+			// no sessions of its own, re-root the session here instead of silently starting
+			// fresh — otherwise the relocated session would be unreachable via --continue.
+			// When an explicit sessionDir is reused across the move, the stale breadcrumb
+			// file itself may be the most recent entry there; don't count it as a
+			// current-directory session. If that shared dir also contains an older session
+			// that already belongs to the current cwd, prefer that local session instead
+			// of re-rooting the stale breadcrumb over it.
+			const resolvedBreadcrumbCwd = breadcrumbCwd ?? path.resolve(breadcrumb.cwd);
+			mostRecent = await findMostRecentSession(dir, storage);
+			const sourceCwdGone = !fs.existsSync(resolvedBreadcrumbCwd);
+			const breadcrumbSessionFile = path.resolve(breadcrumb.sessionFile);
+			const mostRecentIsBreadcrumb =
+				mostRecent !== null && mostRecent !== undefined && path.resolve(mostRecent) === breadcrumbSessionFile;
+			let hasCurrentCwdSession = false;
+			if (sourceCwdGone && mostRecentIsBreadcrumb) {
+				const currentCwdSession = (await SessionManager.list(cwd, dir, storage)).find(
+					session =>
+						path.resolve(session.path) !== breadcrumbSessionFile &&
+						session.cwd !== undefined &&
+						path.resolve(session.cwd) === resolvedCwd,
+				);
+				if (currentCwdSession) {
+					mostRecent = currentCwdSession.path;
+					hasCurrentCwdSession = true;
+				}
+			}
+			const relocated = sourceCwdGone && (mostRecent === null || (mostRecentIsBreadcrumb && !hasCurrentCwdSession));
+			if (relocated) {
+				process.stderr.write(`Re-rooting moved session from ${resolvedBreadcrumbCwd} to ${resolvedCwd}.\n`);
+				const manager = await SessionManager.open(breadcrumb.sessionFile, undefined, storage);
+				await manager.moveTo(cwd, sessionDir);
+				return manager;
+			}
+		}
+		const terminalSession = breadcrumb && breadcrumbCwd === resolvedCwd ? breadcrumb.sessionFile : null;
+		if (mostRecent === undefined) mostRecent = terminalSession ?? (await findMostRecentSession(dir, storage));
 		const manager = new SessionManager(cwd, dir, true, storage);
 		if (mostRecent) {
 			await manager.#initSessionFile(mostRecent);
diff --git a/packages/coding-agent/test/main-cross-project-resume.test.ts b/packages/coding-agent/test/main-cross-project-resume.test.ts
index 02348fc4d..6688ca44c 100644
--- a/packages/coding-agent/test/main-cross-project-resume.test.ts
+++ b/packages/coding-agent/test/main-cross-project-resume.test.ts
@@ -2,8 +2,16 @@
  * Regression: declining the cross-project fork prompt during `--resume <id>`
  * must exit cleanly, while non-interactive resume still fails instead of
  * silently succeeding. See #1668.
+ *
+ * Also covers the moved/renamed-worktree path: when the matched session's
+ * recorded directory no longer exists, `--resume <id>` offers to *move*
+ * (re-root) the session rather than fork a duplicate.
  */
-import { afterEach, describe, expect, it, vi } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it, vi } from "bun:test";
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
 import type { Args } from "@oh-my-pi/pi-coding-agent/cli/args";
 import type { Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
 import { createSessionManager } from "@oh-my-pi/pi-coding-agent/main";
@@ -37,20 +45,27 @@ function buildGlobalMatch(cwd: string): { session: SessionInfo; scope: "global"
 	};
 }
 
+const stubSettings = { get: () => undefined } as unknown as Settings;
+
 describe("createSessionManager — cross-project --resume cancellation (#1668)", () => {
-	afterEach(() => {
+	// An existing directory so the match is treated as a genuinely different
+	// project (fork path), not a moved/renamed worktree (move path).
+	let existingProject: string;
+
+	beforeEach(async () => {
+		existingProject = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-xproj-"));
+	});
+
+	afterEach(async () => {
 		vi.restoreAllMocks();
+		await fsp.rm(existingProject, { recursive: true, force: true });
 	});
 
 	it("returns undefined when an interactive user declines the fork prompt instead of throwing", async () => {
-		const sessionCwd = "/some/other/project";
-		vi.spyOn(sessionManagerModule, "resolveResumableSession").mockResolvedValue(buildGlobalMatch(sessionCwd));
-
-		const args = buildArgs("019e84ed");
-		const stubSettings = { get: () => undefined } as unknown as Settings;
+		vi.spyOn(sessionManagerModule, "resolveResumableSession").mockResolvedValue(buildGlobalMatch(existingProject));
 
 		const result = await createSessionManager(
-			args,
+			buildArgs("019e84ed"),
 			"/current/project",
 			stubSettings,
 			async () => "declined" as const,
@@ -61,15 +76,52 @@ describe("createSessionManager — cross-project --resume cancellation (#1668)",
 
 	it("throws when the cross-project fork prompt is unavailable in non-interactive mode", async () => {
 		expect(process.stdin.isTTY).toBeFalsy();
+		vi.spyOn(sessionManagerModule, "resolveResumableSession").mockResolvedValue(buildGlobalMatch(existingProject));
 
-		const sessionCwd = "/some/other/project";
-		vi.spyOn(sessionManagerModule, "resolveResumableSession").mockResolvedValue(buildGlobalMatch(sessionCwd));
-
-		const args = buildArgs("019e84ed");
-		const stubSettings = { get: () => undefined } as unknown as Settings;
-
-		await expect(createSessionManager(args, "/current/project", stubSettings)).rejects.toThrow(
-			'Session "019e84ed" is in another project (/some/other/project); run interactively to fork it into the current project.',
+		await expect(createSessionManager(buildArgs("019e84ed"), "/current/project", stubSettings)).rejects.toThrow(
+			`Session "019e84ed" is in another project (${existingProject}); run interactively to fork it into the current project.`,
+		);
+	});
+});
+
+describe("createSessionManager — cross-project --resume relocation (moved worktree)", () => {
+	let missingRoot: string;
+	let missingProject: string;
+
+	beforeEach(async () => {
+		missingRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-moved-xproj-"));
+		missingProject = path.join(missingRoot, "worktree-gone");
+	});
+
+	afterEach(async () => {
+		vi.restoreAllMocks();
+		await fsp.rm(missingRoot, { recursive: true, force: true });
+	});
+
+	it("offers move (not fork) and returns undefined when the user declines", async () => {
+		vi.spyOn(sessionManagerModule, "resolveResumableSession").mockResolvedValue(buildGlobalMatch(missingProject));
+		expect(fs.existsSync(missingProject)).toBe(false);
+
+		const forkPrompt = vi.fn(async () => "accepted" as const);
+		const result = await createSessionManager(
+			buildArgs("019e84ed"),
+			"/current/project",
+			stubSettings,
+			forkPrompt,
+			async () => "declined" as const,
+		);
+
+		expect(result).toBeUndefined();
+		// The fork prompt must NOT be used for a relocated (gone-dir) session.
+		expect(forkPrompt).not.toHaveBeenCalled();
+	});
+
+	it("throws the move-specific error when unavailable in non-interactive mode", async () => {
+		expect(process.stdin.isTTY).toBeFalsy();
+		vi.spyOn(sessionManagerModule, "resolveResumableSession").mockResolvedValue(buildGlobalMatch(missingProject));
+
+		await expect(createSessionManager(buildArgs("019e84ed"), "/current/project", stubSettings)).rejects.toThrow(
+			`Session "019e84ed" belongs to a directory that no longer exists (${missingProject}); run interactively to move it into the current project.`,
 		);
 	});
 });
diff --git a/packages/coding-agent/test/session-manager/continue-relocation.test.ts b/packages/coding-agent/test/session-manager/continue-relocation.test.ts
new file mode 100644
index 000000000..681802f78
--- /dev/null
+++ b/packages/coding-agent/test/session-manager/continue-relocation.test.ts
@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	loadEntriesFromFile,
+	type SessionHeader,
+	SessionManager,
+} from "@oh-my-pi/pi-coding-agent/session/session-manager";
+import { getTerminalId } from "@oh-my-pi/pi-tui";
+import { getConfigRootDir, getTerminalSessionsDir, setAgentDir } from "@oh-my-pi/pi-utils";
+
+import { makeAssistantMessage } from "./helpers";
+
+function getHeader(entries: unknown[]): SessionHeader | undefined {
+	return entries.find(
+		(e): e is SessionHeader =>
+			typeof e === "object" && e !== null && "type" in e && (e as { type: unknown }).type === "session",
+	);
+}
+
+function writeBreadcrumb(cwd: string, sessionFile: string): string {
+	const terminalId = getTerminalId();
+	if (!terminalId) throw new Error("Expected a terminal id for breadcrumb test");
+	const dir = getTerminalSessionsDir();
+	fs.mkdirSync(dir, { recursive: true });
+	const file = path.join(dir, terminalId);
+	fs.writeFileSync(file, `${cwd}\n${sessionFile}\n`);
+	return file;
+}
+
+describe("SessionManager.continueRecent relocation", () => {
+	let testAgentDir: string;
+	let cwdA: string;
+	let cwdB: string;
+	const originalAgentDir = process.env.PI_CODING_AGENT_DIR;
+	const originalTmuxPane = process.env.TMUX_PANE;
+	const fallbackAgentDir = path.join(getConfigRootDir(), "agent");
+
+	beforeEach(async () => {
+		// Force a deterministic, non-TTY terminal id so breadcrumb read/write is stable.
+		process.env.TMUX_PANE = "%relocation-test";
+		testAgentDir = await fsp.mkdtemp(path.join(os.tmpdir(), "omp-reloc-test-"));
+		setAgentDir(testAgentDir);
+		cwdA = path.join(testAgentDir, "worktree-old");
+		cwdB = path.join(testAgentDir, "worktree-new");
+		fs.mkdirSync(cwdA, { recursive: true });
+		fs.mkdirSync(cwdB, { recursive: true });
+	});
+
+	afterEach(async () => {
+		if (originalTmuxPane === undefined) delete process.env.TMUX_PANE;
+		else process.env.TMUX_PANE = originalTmuxPane;
+		if (originalAgentDir) {
+			setAgentDir(originalAgentDir);
+		} else {
+			setAgentDir(fallbackAgentDir);
+			delete process.env.PI_CODING_AGENT_DIR;
+		}
+		await fsp.rm(testAgentDir, { recursive: true, force: true });
+	});
+
+	it("re-roots the terminal's session when its directory was moved/renamed", async () => {
+		const session = SessionManager.create(cwdA);
+		session.appendMessage({ role: "user", content: "before move", timestamp: 1 });
+		session.appendMessage(makeAssistantMessage());
+		await session.flush();
+		const oldFile = session.getSessionFile();
+		if (!oldFile) throw new Error("Expected persisted session file");
+		await session.close();
+
+		// Breadcrumb points at the old session, recorded under the old cwd.
+		writeBreadcrumb(cwdA, oldFile);
+		// Simulate `git worktree move`: the old directory no longer exists.
+		await fsp.rm(cwdA, { recursive: true, force: true });
+
+		const resumed = await SessionManager.continueRecent(cwdB);
+		try {
+			// The relocated session is adopted, not discarded for a fresh one.
+			expect(resumed.getCwd()).toBe(path.resolve(cwdB));
+			const newFile = resumed.getSessionFile();
+			if (!newFile) throw new Error("Expected re-rooted session file");
+			expect(newFile).not.toBe(oldFile);
+			expect(fs.existsSync(oldFile)).toBe(false);
+
+			const entries = await loadEntriesFromFile(newFile);
+			expect(getHeader(entries)?.cwd).toBe(path.resolve(cwdB));
+			const userMessages = entries.filter(e => e.type === "message" && e.message.role === "user");
+			expect(userMessages).toHaveLength(1);
+		} finally {
+			await resumed.close();
+		}
+	});
+
+	it("does not hijack the session when the recorded directory still exists (plain cd)", async () => {
+		const session = SessionManager.create(cwdA);
+		session.appendMessage({ role: "user", content: "other project", timestamp: 1 });
+		session.appendMessage(makeAssistantMessage());
+		await session.flush();
+		const oldFile = session.getSessionFile();
+		if (!oldFile) throw new Error("Expected persisted session file");
+		await session.close();
+
+		// Breadcrumb from a still-existing different project; user just cd'd elsewhere.
+		writeBreadcrumb(cwdA, oldFile);
+
+		const resumed = await SessionManager.continueRecent(cwdB);
+		try {
+			// Old project's session is left untouched; a fresh session starts in cwdB.
+			expect(fs.existsSync(oldFile)).toBe(true);
+			expect(resumed.getSessionFile()).not.toBe(oldFile);
+			expect(resumed.getEntries()).toHaveLength(0);
+		} finally {
+			await resumed.close();
+		}
+	});
+
+	it("does not re-root when the new directory already has its own sessions", async () => {
+		const moved = SessionManager.create(cwdA);
+		moved.appendMessage({ role: "user", content: "moved", timestamp: 1 });
+		moved.appendMessage(makeAssistantMessage());
+		await moved.flush();
+		const movedFile = moved.getSessionFile();
+		if (!movedFile) throw new Error("Expected persisted session file");
+		await moved.close();
+
+		// cwdB already owns a local session.
+		const local = SessionManager.create(cwdB);
+		local.appendMessage({ role: "user", content: "local", timestamp: 2 });
+		local.appendMessage(makeAssistantMessage());
+		await local.flush();
+		const localFile = local.getSessionFile();
+		if (!localFile) throw new Error("Expected persisted local session file");
+		await local.close();
+
+		writeBreadcrumb(cwdA, movedFile);
+		await fsp.rm(cwdA, { recursive: true, force: true });
+
+		const resumed = await SessionManager.continueRecent(cwdB);
+		try {
+			// Prefer cwdB's own recent session over re-rooting the moved one.
+			expect(resumed.getSessionFile()).toBe(localFile);
+			expect(fs.existsSync(movedFile)).toBe(true);
+		} finally {
+			await resumed.close();
+		}
+	});
+
+	it("moves a relocated breadcrumb session into an explicit sessionDir", async () => {
+		const session = SessionManager.create(cwdA);
+		session.appendMessage({ role: "user", content: "explicit dir", timestamp: 1 });
+		session.appendMessage(makeAssistantMessage());
+		await session.flush();
+		const oldFile = session.getSessionFile();
+		if (!oldFile) throw new Error("Expected persisted session file");
+		await session.close();
+
+		const explicitSessionDir = path.join(testAgentDir, "custom-sessions");
+		writeBreadcrumb(cwdA, oldFile);
+		await fsp.rm(cwdA, { recursive: true, force: true });
+
+		const resumed = await SessionManager.continueRecent(cwdB, explicitSessionDir);
+		try {
+			const newFile = resumed.getSessionFile();
+			if (!newFile) throw new Error("Expected re-rooted session file");
+			expect(path.dirname(newFile)).toBe(path.resolve(explicitSessionDir));
+			expect(fs.existsSync(oldFile)).toBe(false);
+			expect(getHeader(await loadEntriesFromFile(newFile))?.cwd).toBe(path.resolve(cwdB));
+		} finally {
+			await resumed.close();
+		}
+	});
+
+	it("re-roots when the stale breadcrumb file is already in the explicit sessionDir", async () => {
+		const explicitSessionDir = path.join(testAgentDir, "shared-custom-sessions");
+		const session = SessionManager.create(cwdA, explicitSessionDir);
+		session.appendMessage({ role: "user", content: "same explicit dir", timestamp: 1 });
+		session.appendMessage(makeAssistantMessage());
+		await session.flush();
+		const oldFile = session.getSessionFile();
+		if (!oldFile) throw new Error("Expected persisted session file");
+		expect(path.dirname(oldFile)).toBe(path.resolve(explicitSessionDir));
+		await session.close();
+
+		writeBreadcrumb(cwdA, oldFile);
+		await fsp.rm(cwdA, { recursive: true, force: true });
+
+		const resumed = await SessionManager.continueRecent(cwdB, explicitSessionDir);
+		try {
+			const newFile = resumed.getSessionFile();
+			if (!newFile) throw new Error("Expected re-rooted session file");
+			expect(newFile).toBe(oldFile);
+			expect(resumed.getCwd()).toBe(path.resolve(cwdB));
+			expect(getHeader(await loadEntriesFromFile(newFile))?.cwd).toBe(path.resolve(cwdB));
+		} finally {
+			await resumed.close();
+		}
+	});
+
+	it("prefers an existing current-cwd session in a shared explicit sessionDir", async () => {
+		const explicitSessionDir = path.join(testAgentDir, "shared-current-sessions");
+		const local = SessionManager.create(cwdB, explicitSessionDir);
+		local.appendMessage({ role: "user", content: "local current cwd", timestamp: 1 });
+		local.appendMessage(makeAssistantMessage());
+		await local.flush();
+		const localFile = local.getSessionFile();
+		if (!localFile) throw new Error("Expected persisted local session file");
+		await local.close();
+
+		// Ensure the stale moved session is newer than the local current-cwd session.
+		await new Promise(resolve => setTimeout(resolve, 20));
+		const moved = SessionManager.create(cwdA, explicitSessionDir);
+		moved.appendMessage({ role: "user", content: "newer stale moved cwd", timestamp: 2 });
+		moved.appendMessage(makeAssistantMessage());
+		await moved.flush();
+		const movedFile = moved.getSessionFile();
+		if (!movedFile) throw new Error("Expected persisted moved session file");
+		await moved.close();
+
+		writeBreadcrumb(cwdA, movedFile);
+		await fsp.rm(cwdA, { recursive: true, force: true });
+
+		const resumed = await SessionManager.continueRecent(cwdB, explicitSessionDir);
+		try {
+			expect(resumed.getSessionFile()).toBe(localFile);
+			expect(resumed.getCwd()).toBe(path.resolve(cwdB));
+			expect(fs.existsSync(movedFile)).toBe(true);
+		} finally {
+			await resumed.close();
+		}
+	});
+});

From bad1e2acd6d419204b433a132e734c89e151470a Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Mon, 8 Jun 2026 00:42:23 +0200
Subject: [PATCH 179/181] fix: restricted GitHub Copilot auth to
 COPILOT_GITHUB_TOKEN

- Changed the `github-copilot` service provider to resolve credentials only from `COPILOT_GITHUB_TOKEN`.
- Updated CLI extra help text to document `COPILOT_GITHUB_TOKEN` as the GitHub Copilot environment variable.
- Reworded environment variable docs to reflect the revised Copilot/GitHub token usage and order.
---
 docs/environment-variables.md         | 12 ++++++------
 packages/ai/src/stream.ts             |  3 +--
 packages/coding-agent/src/cli/args.ts |  2 +-
 3 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/environment-variables.md b/docs/environment-variables.md
index 60b1da7aa..7d2bc9b75 100644
--- a/docs/environment-variables.md
+++ b/docs/environment-variables.md
@@ -81,13 +81,13 @@ These are consumed via `getEnvApiKey()` (`packages/ai/src/stream.ts`) unless not
 | `WAFER_SERVERLESS_API_KEY`      | Wafer Serverless auth                            | Using `wafer-serverless` provider                              | Pay-as-you-go Wafer SKU; validated against `https://pass.wafer.ai/v1/models`                        |
 | `GITLAB_TOKEN`                  | GitLab Duo auth                                  | Using `gitlab-duo` provider                                    |                                                                                                     |
 
-### GitHub/Copilot token chains
+### GitHub/Copilot tokens
 
-| Variable               | Used for                                         | Chain                                                |
-| ---------------------- | ------------------------------------------------ | ---------------------------------------------------- |
-| `COPILOT_GITHUB_TOKEN` | GitHub Copilot provider auth                     | `COPILOT_GITHUB_TOKEN` → `GH_TOKEN` → `GITHUB_TOKEN` |
-| `GH_TOKEN`             | Copilot fallback; GitHub API auth in web scraper | In web scraper: `GITHUB_TOKEN` → `GH_TOKEN`          |
-| `GITHUB_TOKEN`         | Copilot fallback; GitHub API auth in web scraper | In web scraper: checked before `GH_TOKEN`            |
+| Variable               | Used for                                         | Notes                                      |
+| ---------------------- | ------------------------------------------------ | ------------------------------------------ |
+| `COPILOT_GITHUB_TOKEN` | GitHub Copilot provider auth                     | Generic GitHub tokens are not used here    |
+| `GH_TOKEN`             | GitHub API auth in web scraper                   | Web scraper fallback after `GITHUB_TOKEN`  |
+| `GITHUB_TOKEN`         | GitHub API auth in web scraper                   | Web scraper checks this before `GH_TOKEN`  |
 
 ### Auth broker / auth gateway (remote credential vault)
 
diff --git a/packages/ai/src/stream.ts b/packages/ai/src/stream.ts
index f592dcd89..f44c0a5b4 100644
--- a/packages/ai/src/stream.ts
+++ b/packages/ai/src/stream.ts
@@ -209,8 +209,7 @@ const serviceProviderMap: Record<string, KeyResolver> = {
 	tavily: "TAVILY_API_KEY",
 	parallel: "PARALLEL_API_KEY",
 	kagi: "KAGI_API_KEY",
-	// GitHub Copilot uses GitHub personal access token
-	"github-copilot": () => $pickenv("COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"),
+	"github-copilot": "COPILOT_GITHUB_TOKEN",
 	// Foundry mode optionally switches Anthropic auth to enterprise gateway credentials.
 	anthropic: () =>
 		isFoundryEnabled()
diff --git a/packages/coding-agent/src/cli/args.ts b/packages/coding-agent/src/cli/args.ts
index 707d87c54..f81c24563 100644
--- a/packages/coding-agent/src/cli/args.ts
+++ b/packages/coding-agent/src/cli/args.ts
@@ -258,7 +258,7 @@ export function getExtraHelpText(): string {
   NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
   OPENAI_API_KEY             - OpenAI GPT models
   GEMINI_API_KEY             - Google Gemini models
-  GITHUB_TOKEN               - GitHub Copilot (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
+  COPILOT_GITHUB_TOKEN      - GitHub Copilot
 
   ${chalk.dim("# Additional LLM Providers")}
   AZURE_OPENAI_API_KEY       - Azure OpenAI models

From ba4abb7e2f8863e2aef1a8ab25d9d032c1fe2f1c Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Mon, 8 Jun 2026 00:47:39 +0200
Subject: [PATCH 180/181] fix(coding-agent): excluded cwd-less legacy sessions
 from relocation guard

- Guard now skips sessions with empty cwd, not just undefined.
- Prevents path.resolve("") collision from hijacking a moved session.
---
 .../src/session/session-manager.ts            |  4 +-
 .../continue-relocation.test.ts               | 54 +++++++++++++++++++
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/packages/coding-agent/src/session/session-manager.ts b/packages/coding-agent/src/session/session-manager.ts
index 58f5a71bb..8ad4a4d95 100644
--- a/packages/coding-agent/src/session/session-manager.ts
+++ b/packages/coding-agent/src/session/session-manager.ts
@@ -3518,7 +3518,7 @@ export class SessionManager {
 			// current-directory session. If that shared dir also contains an older session
 			// that already belongs to the current cwd, prefer that local session instead
 			// of re-rooting the stale breadcrumb over it.
-			const resolvedBreadcrumbCwd = breadcrumbCwd ?? path.resolve(breadcrumb.cwd);
+			const resolvedBreadcrumbCwd = path.resolve(breadcrumb.cwd);
 			mostRecent = await findMostRecentSession(dir, storage);
 			const sourceCwdGone = !fs.existsSync(resolvedBreadcrumbCwd);
 			const breadcrumbSessionFile = path.resolve(breadcrumb.sessionFile);
@@ -3529,7 +3529,7 @@ export class SessionManager {
 				const currentCwdSession = (await SessionManager.list(cwd, dir, storage)).find(
 					session =>
 						path.resolve(session.path) !== breadcrumbSessionFile &&
-						session.cwd !== undefined &&
+						session.cwd &&
 						path.resolve(session.cwd) === resolvedCwd,
 				);
 				if (currentCwdSession) {
diff --git a/packages/coding-agent/test/session-manager/continue-relocation.test.ts b/packages/coding-agent/test/session-manager/continue-relocation.test.ts
index 681802f78..751c16bd3 100644
--- a/packages/coding-agent/test/session-manager/continue-relocation.test.ts
+++ b/packages/coding-agent/test/session-manager/continue-relocation.test.ts
@@ -30,6 +30,17 @@ function writeBreadcrumb(cwd: string, sessionFile: string): string {
 	return file;
 }
 
+function stripHeaderCwd(file: string): void {
+	const lines = fs.readFileSync(file, "utf8").split("\n");
+	const rewritten = lines.map(line => {
+		if (!line.trim()) return line;
+		const obj = JSON.parse(line) as { type?: string; cwd?: unknown };
+		if (obj.type === "session") delete obj.cwd;
+		return JSON.stringify(obj);
+	});
+	fs.writeFileSync(file, rewritten.join("\n"));
+}
+
 describe("SessionManager.continueRecent relocation", () => {
 	let testAgentDir: string;
 	let cwdA: string;
@@ -230,4 +241,47 @@ describe("SessionManager.continueRecent relocation", () => {
 			await resumed.close();
 		}
 	});
+
+	it("re-roots past a cwd-less legacy session in a shared explicit sessionDir", async () => {
+		// Regression: SessionInfo.cwd is "" for sessions whose header has no cwd, and
+		// path.resolve("") === process.cwd(). A guard that only excluded `undefined`
+		// treated such a legacy session as "belongs to the current cwd" whenever
+		// --continue ran from process.cwd(), hijacking the moved session. Resume must
+		// be invoked with process.cwd() to reproduce the path.resolve("") collision.
+		const explicitSessionDir = path.join(testAgentDir, "shared-legacy-sessions");
+		const currentCwd = process.cwd();
+
+		// Older session with no recorded cwd (header cwd stripped → "" on load).
+		const legacy = SessionManager.create(cwdB, explicitSessionDir);
+		legacy.appendMessage({ role: "user", content: "legacy cwd-less", timestamp: 1 });
+		legacy.appendMessage(makeAssistantMessage());
+		await legacy.flush();
+		const legacyFile = legacy.getSessionFile();
+		if (!legacyFile) throw new Error("Expected persisted legacy session file");
+		await legacy.close();
+		stripHeaderCwd(legacyFile);
+
+		// Newer moved session, recorded under the now-missing worktree cwd.
+		await new Promise(resolve => setTimeout(resolve, 20));
+		const moved = SessionManager.create(cwdA, explicitSessionDir);
+		moved.appendMessage({ role: "user", content: "newer moved cwd", timestamp: 2 });
+		moved.appendMessage(makeAssistantMessage());
+		await moved.flush();
+		const movedFile = moved.getSessionFile();
+		if (!movedFile) throw new Error("Expected persisted moved session file");
+		await moved.close();
+
+		writeBreadcrumb(cwdA, movedFile);
+		await fsp.rm(cwdA, { recursive: true, force: true });
+
+		const resumed = await SessionManager.continueRecent(currentCwd, explicitSessionDir);
+		try {
+			// The moved session is re-rooted; the cwd-less legacy session is not hijacked.
+			expect(resumed.getSessionFile()).toBe(movedFile);
+			expect(resumed.getCwd()).toBe(path.resolve(currentCwd));
+			expect(fs.existsSync(legacyFile)).toBe(true);
+		} finally {
+			await resumed.close();
+		}
+	});
 });

From 181419b65baca245b3b0b2a7a20914a8ea65f04b Mon Sep 17 00:00:00 2001
From: can1357 <me@can.ac>
Date: Mon, 8 Jun 2026 00:53:43 +0200
Subject: [PATCH 181/181] fix(coding-agent/modes): fixed Esc interrupt
 acknowledgement to update loader immediately

- Added an interrupt state in EventController to switch the working label to `Interrupting...` and suspend intent-driven updates until the turn resets.
- Called `notifyInterrupting()` from streaming-interrupt paths in InputController and exposed it on InteractiveModeContext so Esc acknowledgement shows immediately while tools tear down.
- Added tests to verify loader acknowledgement, freeze of late intent updates during interruption, and label updates resuming on the next agent start.
---
 packages/coding-agent/CHANGELOG.md            |   1 +
 .../src/modes/controllers/event-controller.ts |  26 ++++
 .../src/modes/controllers/input-controller.ts |   2 +
 .../src/modes/interactive-mode.ts             |   4 +
 packages/coding-agent/src/modes/types.ts      |   3 +
 .../test/input-controller-escape.test.ts      |   1 +
 .../event-controller-interrupt.test.ts        | 124 ++++++++++++++++++
 7 files changed, 161 insertions(+)
 create mode 100644 packages/coding-agent/test/modes/controllers/event-controller-interrupt.test.ts

diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md
index d3f1b5f18..8a62c2743 100644
--- a/packages/coding-agent/CHANGELOG.md
+++ b/packages/coding-agent/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## [Unreleased]
 ### Fixed
 
+- Fixed the working spinner appearing to ignore Esc for 2-3 seconds when an interrupt lands mid-tool. Esc fires the abort synchronously, but the agent loop only stops the loader at `agent_end`, which it cannot reach until every in-flight tool settles in `executeToolCalls`' `await Promise.allSettled(...)` — and process/subagent/kernel-owning tools tear down gracefully (SIGTERM, 2-3s grace, SIGKILL), so the loader kept showing the unchanged "Working…/<intent>" line and read as a dropped keypress. The loader now switches to "Interrupting…" the instant Esc requests the abort and freezes intent-driven label updates until the turn unwinds (`EventController.notifyInterrupting`), so the interrupt is acknowledged immediately even while teardown completes.
 - Fixed a flaky JS eval worker startup that intermittently failed unrelated CI runs. The worker-ready wait reused Bun's 5s default per-test timeout as its floor, so a slow cold-start under `--isolate` + high concurrency was aborted mid-init; terminating a still-initializing Bun worker is the documented SIGILL/SIGTRAP crash trigger, which took down the whole test file. Worker init now floors at a fixed 15s infrastructure budget (independent of, and still dominated by, a larger per-cell `timeout`), and the JS eval test suites set a 20s file-local timeout so cold starts complete instead of being torn down.
 - Fixed reviewer-style subagent yields crashing the calling eval cell when a caller-supplied output schema declares `additionalProperties: false` without a `findings` property. `normalizeCompleteData` now consults the active validator before splicing collected `report_finding` entries onto the yielded payload, so injection is suppressed when the schema would reject it — keeping the executor's post-mortem validation in lockstep with the in-tool `yield` validation that already accepted the same raw payload ([#2070](https://github.com/can1357/oh-my-pi/issues/2070))
 - Fixed Anthropic empty `toolUse` stops without tool calls corrupting session history by retrying them and removing orphaned turns even at the retry cap.
diff --git a/packages/coding-agent/src/modes/controllers/event-controller.ts b/packages/coding-agent/src/modes/controllers/event-controller.ts
index d1f1e8e28..97e571d0e 100644
--- a/packages/coding-agent/src/modes/controllers/event-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/event-controller.ts
@@ -26,6 +26,16 @@ type AgentSessionEventKind = AgentSessionEvent["type"];
 
 const IRC_MESSAGE_VISIBLE_TTL_MS = 10_000;
 
+/**
+ * Loader label shown the instant a user interrupt (Esc) is requested, kept until
+ * the agent turn fully unwinds. Esc fires the abort synchronously, but the loop
+ * only stops the spinner at `agent_end`, which it cannot reach until every
+ * in-flight tool settles its abort in `executeToolCalls` (`Promise.allSettled`).
+ * Swapping the steady "Working…" for this acknowledges the keypress instead of
+ * reading as an ignored Esc for the seconds a slow tool takes to tear down.
+ */
+export const INTERRUPTING_WORKING_MESSAGE = "Interrupting…";
+
 // Events that change foreground streaming state, or that reset a turn. The TUI
 // eager native-scrollback rebuild mode is recomputed only on these so unrelated
 // IRC/notices/status refreshes do not toggle scrollback replay policy.
@@ -57,6 +67,7 @@ export class EventController {
 	#backgroundToolCallIds = new Set<string>();
 	#assistantMessageStreaming = false;
 	#agentTurnActive = false;
+	#interrupting = false;
 	#readToolCallArgs = new Map<string, Record<string, unknown>>();
 	#readToolCallAssistantComponents = new Map<string, AssistantMessageComponent>();
 	#lastAssistantComponent: AssistantMessageComponent | undefined = undefined;
@@ -167,6 +178,7 @@ export class EventController {
 		return true;
 	}
 	#updateWorkingMessageFromIntent(intent: unknown): void {
+		if (this.#interrupting) return;
 		// Streamed JSON can deliver non-string `_i` (object, number, boolean) before
 		// schema validation; `?.` only guards null/undefined, so guard the type too.
 		if (typeof intent !== "string") return;
@@ -176,6 +188,19 @@ export class EventController {
 		this.ctx.setWorkingMessage(`${trimmed}${interruptHint()}`);
 	}
 
+	/**
+	 * Acknowledge a user interrupt (Esc) immediately: switch the loader to
+	 * `INTERRUPTING_WORKING_MESSAGE` and freeze intent-driven working-message
+	 * updates for the rest of the turn so a late `tool_execution_start` intent
+	 * cannot repaint a "Working…/<intent>" line over the acknowledgment. Reset at
+	 * the next `agent_start`. No-op outside an active turn or if already set.
+	 */
+	notifyInterrupting(): void {
+		if (!this.#agentTurnActive || this.#interrupting) return;
+		this.#interrupting = true;
+		this.ctx.setWorkingMessage(INTERRUPTING_WORKING_MESSAGE);
+	}
+
 	subscribeToAgent(): void {
 		this.ctx.unsubscribe = this.ctx.session.subscribe(async (event: AgentSessionEvent) => {
 			await this.handleEvent(event);
@@ -220,6 +245,7 @@ export class EventController {
 
 	async #handleAgentStart(_event: Extract<AgentSessionEvent, { type: "agent_start" }>): Promise<void> {
 		this.#agentTurnActive = true;
+		this.#interrupting = false;
 		this.#lastIntent = undefined;
 		this.#readToolCallArgs.clear();
 		this.#readToolCallAssistantComponents.clear();
diff --git a/packages/coding-agent/src/modes/controllers/input-controller.ts b/packages/coding-agent/src/modes/controllers/input-controller.ts
index c2df60aa4..6ae1c42b6 100644
--- a/packages/coding-agent/src/modes/controllers/input-controller.ts
+++ b/packages/coding-agent/src/modes/controllers/input-controller.ts
@@ -94,6 +94,7 @@ export class InputController {
 			if (this.ctx.loopModeEnabled) {
 				this.ctx.pauseLoop();
 				if (this.ctx.session.isStreaming) {
+					this.ctx.notifyInterrupting();
 					void this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 				} else {
 					this.ctx.cancelPendingSubmission();
@@ -124,6 +125,7 @@ export class InputController {
 				this.ctx.isPythonMode = false;
 				this.ctx.updateEditorBorderColor();
 			} else if (this.ctx.session.isStreaming) {
+				this.ctx.notifyInterrupting();
 				void this.ctx.session.abort({ reason: USER_INTERRUPT_LABEL });
 			} else if (!this.ctx.editor.getText().trim()) {
 				// Double-interrupt with empty editor triggers /tree, /branch, or nothing based on setting
diff --git a/packages/coding-agent/src/modes/interactive-mode.ts b/packages/coding-agent/src/modes/interactive-mode.ts
index 0b0e42641..2c7edd6f5 100644
--- a/packages/coding-agent/src/modes/interactive-mode.ts
+++ b/packages/coding-agent/src/modes/interactive-mode.ts
@@ -2707,6 +2707,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.setWorkingMessage(message);
 	}
 
+	notifyInterrupting(): void {
+		this.#eventController.notifyInterrupting();
+	}
+
 	showNewVersionNotification(newVersion: string): void {
 		this.#uiHelpers.showNewVersionNotification(newVersion);
 	}
diff --git a/packages/coding-agent/src/modes/types.ts b/packages/coding-agent/src/modes/types.ts
index 59fdce436..7848bd95b 100644
--- a/packages/coding-agent/src/modes/types.ts
+++ b/packages/coding-agent/src/modes/types.ts
@@ -182,6 +182,9 @@ export interface InteractiveModeContext {
 	flushPendingModelSwitch(): Promise<void>;
 	setWorkingMessage(message?: string): void;
 	applyPendingWorkingMessage(): void;
+	/** Acknowledge a user interrupt (Esc) by switching the loader to an
+	 *  "Interrupting…" label until the agent turn unwinds. */
+	notifyInterrupting(): void;
 	ensureLoadingAnimation(): void;
 	startPendingSubmission(input: {
 		text: string;
diff --git a/packages/coding-agent/test/input-controller-escape.test.ts b/packages/coding-agent/test/input-controller-escape.test.ts
index f458d9568..eebe70619 100644
--- a/packages/coding-agent/test/input-controller-escape.test.ts
+++ b/packages/coding-agent/test/input-controller-escape.test.ts
@@ -154,6 +154,7 @@ function createContext(): {
 		addMessageToChat,
 		cancelPendingSubmission,
 		ensureLoadingAnimation,
+		notifyInterrupting: vi.fn(),
 		finishPendingSubmission: vi.fn(),
 		flushPendingBashComponents: vi.fn(),
 		markPendingSubmissionStarted: vi.fn(() => true),
diff --git a/packages/coding-agent/test/modes/controllers/event-controller-interrupt.test.ts b/packages/coding-agent/test/modes/controllers/event-controller-interrupt.test.ts
new file mode 100644
index 000000000..88adf8539
--- /dev/null
+++ b/packages/coding-agent/test/modes/controllers/event-controller-interrupt.test.ts
@@ -0,0 +1,124 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "bun:test";
+import { resetSettingsForTest, Settings } from "@oh-my-pi/pi-coding-agent/config/settings";
+import {
+	EventController,
+	INTERRUPTING_WORKING_MESSAGE,
+} from "@oh-my-pi/pi-coding-agent/modes/controllers/event-controller";
+import { initTheme } from "@oh-my-pi/pi-coding-agent/modes/theme/theme";
+import type { InteractiveModeContext } from "@oh-my-pi/pi-coding-agent/modes/types";
+import type { AgentSessionEvent } from "@oh-my-pi/pi-coding-agent/session/agent-session";
+
+function createContext() {
+	const setWorkingMessage = vi.fn();
+	const pendingTools = new Map<string, unknown>();
+	const ctx = {
+		isInitialized: true,
+		settings: { get: () => false },
+		statusLine: { invalidate: vi.fn() },
+		updateEditorTopBorder: vi.fn(),
+		pendingTools,
+		hideThinkingBlock: false,
+		setWorkingMessage,
+		clearPinnedError: vi.fn(),
+		ensureLoadingAnimation: vi.fn(),
+		ui: { setEagerNativeScrollbackRebuild: vi.fn(), requestRender: vi.fn() },
+		session: { getToolByName: () => undefined },
+	} as unknown as InteractiveModeContext;
+	return { ctx, pendingTools, setWorkingMessage };
+}
+
+const AGENT_START = { type: "agent_start" } as unknown as AgentSessionEvent;
+
+/** A `tool_execution_start` whose toolCallId is pre-seeded into `pendingTools`,
+ *  so the handler only runs the intent->working-message path and skips component
+ *  construction (which needs far heavier mocks). */
+function toolStartWithIntent(toolCallId: string, intent: string): AgentSessionEvent {
+	return {
+		type: "tool_execution_start",
+		toolCallId,
+		toolName: "search",
+		args: {},
+		intent,
+	} as unknown as AgentSessionEvent;
+}
+
+describe("EventController user interrupt acknowledgement", () => {
+	beforeAll(async () => {
+		await initTheme(false);
+	});
+
+	beforeEach(async () => {
+		resetSettingsForTest();
+		await Settings.init({ inMemory: true });
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+		resetSettingsForTest();
+	});
+
+	it("swaps the loader to the interrupting label once a turn is active", async () => {
+		const { ctx, setWorkingMessage } = createContext();
+		const controller = new EventController(ctx);
+		await controller.handleEvent(AGENT_START);
+
+		controller.notifyInterrupting();
+
+		expect(setWorkingMessage).toHaveBeenCalledWith(INTERRUPTING_WORKING_MESSAGE);
+	});
+
+	it("freezes intent-driven working-message updates while interrupting", async () => {
+		const { ctx, pendingTools, setWorkingMessage } = createContext();
+		const controller = new EventController(ctx);
+		await controller.handleEvent(AGENT_START);
+		controller.notifyInterrupting();
+		setWorkingMessage.mockClear();
+
+		// A tool whose args already started streaming before the abort still emits a
+		// late tool_execution_start; without the freeze its intent would repaint the
+		// loader over the "Interrupting…" acknowledgement.
+		pendingTools.set("late-call", {});
+		await controller.handleEvent(toolStartWithIntent("late-call", "Reticulating splines"));
+
+		expect(setWorkingMessage).not.toHaveBeenCalled();
+	});
+
+	it("lets intent updates drive the loader when not interrupting", async () => {
+		const { ctx, pendingTools, setWorkingMessage } = createContext();
+		const controller = new EventController(ctx);
+		await controller.handleEvent(AGENT_START);
+		setWorkingMessage.mockClear();
+
+		pendingTools.set("call-1", {});
+		await controller.handleEvent(toolStartWithIntent("call-1", "Searching files"));
+
+		expect(setWorkingMessage).toHaveBeenCalledTimes(1);
+		expect(setWorkingMessage.mock.calls[0]?.[0]).toContain("Searching files");
+	});
+
+	it("clears the interrupt freeze at the next agent_start", async () => {
+		const { ctx, pendingTools, setWorkingMessage } = createContext();
+		const controller = new EventController(ctx);
+		await controller.handleEvent(AGENT_START);
+		controller.notifyInterrupting();
+
+		// New turn: the freeze must lift so the next turn's intents render again.
+		await controller.handleEvent(AGENT_START);
+		setWorkingMessage.mockClear();
+
+		pendingTools.set("call-2", {});
+		await controller.handleEvent(toolStartWithIntent("call-2", "Editing module"));
+
+		expect(setWorkingMessage).toHaveBeenCalledTimes(1);
+		expect(setWorkingMessage.mock.calls[0]?.[0]).toContain("Editing module");
+	});
+
+	it("is a no-op before any turn starts", () => {
+		const { ctx, setWorkingMessage } = createContext();
+		const controller = new EventController(ctx);
+
+		controller.notifyInterrupting();
+
+		expect(setWorkingMessage).not.toHaveBeenCalled();
+	});
+});