pi-better-btw-plus 1.0.2 → 1.1.1

package/README.md

@@ -32,7 +32,7 @@ You're in the middle of a longer task and want to ask something small without de
 Everything in [`@yceachan/pi-better-btw`](https://www.npmjs.com/package/@yceachan/pi-better-btw) is here, plus:
 
 - **Right-click copy & paste** — drag-select chat text and right-click to copy (Windows Terminal muscle memory); right-click inside the input editor pastes the system clipboard through the editor's own normalization and `[paste #N …]` markers for large pastes. No more hotkey-only copying.
-- **Fork model switching (`Alt+M`)** — pick any authenticated model for the side chat without rebuilding the fork; fork-local only (ADR 0002), thinking level auto-clamped to the new model's capabilities.
+- **Fork model switching (`Ctrl+L`)** — pick any authenticated model for the side chat without rebuilding the fork; fork-local only (ADR 0002), thinking level auto-clamped to the new model's capabilities.
 - **Turn-level auto-retry** — shares the main session's `settings.retry` budget: transient provider errors back off and retry with a live countdown; `Esc` cancels.
 - **Feature kill switches** — the layered config's `features` block turns any of the above off (`rightClickCopyPaste` / `modelSwitch` / `retry`), plus `readOnlyExtensionAllowlistExclude` to drop bundled allowlist defaults.
 
@@ -54,7 +54,7 @@ See [Feat](#feat) for the full feature set.
 
 - `TUI scroll, select, copy`: subscribes to mouse/hotkey events in the TUI overlay for scrolling, text selection, and `Ctrl+C` copy.
 
-- `Readonly/Edit Mode`: read-only by default to answer btw questions; if you want the agent to make small edits along the way, `Ctrl+T` switches to edit mode.
+- `Readonly/Edit Mode`: read-only by default to answer btw questions; if you want the agent to make small edits along the way, `Alt+T` switches to edit mode.
 
   - ToolAllowList: bundle + config.json custom
 
@@ -72,13 +72,13 @@ Press `Esc` to close it. Reopen with `/btw` or `Alt+W` to continue where you lef
 | Shortcut | Action |
 | -------- | ------ |
 | `Alt+W` | Open (when closed) / background (when visible) / restore (when hidden) |
-| `Ctrl+T` | Toggle read-only / edit mode |
+| `Alt+T` | Toggle read-only / edit mode |
 | `Alt+R` | Re-fork from the latest main context |
 | `Alt+N` | Start an empty conversation |
 | `Alt+E` | Export the transcript to `$CWD/.agents/eval/pi-better-btw-<timestamp>.md` |
-| `Alt+M` | Open the fork model picker (scoped + authenticated models; `↑/↓` select, `Enter` confirm, `Esc` cancel) |
+| `Ctrl+L` | Open the fork model picker (scoped + authenticated models; `↑/↓` select, `Enter` confirm, `Esc` cancel) |
 
-In Read-only Mode (default), the read-only lane is **enforced**: attempting an out-of-lane tool call is hard-blocked with a prompt injection; a second violation escalates the wording and aborts the turn (a `🚧 lane blocked` status line). Executed-but-failed read-only calls are re-grounded by an `afterToolCall` note. Edit mode (`Ctrl+T`) is unaffected.
+In Read-only Mode (default), the read-only lane is **enforced**: attempting an out-of-lane tool call is hard-blocked with a prompt injection; a second violation escalates the wording and aborts the turn (a `🚧 lane blocked` status line). Executed-but-failed read-only calls are re-grounded by an `afterToolCall` note. Edit mode (`Alt+T`) is unaffected.
 
 **Peek at the main agent** — the `peek_main` tool reads recent activity from the main session.
 
@@ -98,7 +98,7 @@ What changed since I opened this side chat?
 **Right-click paste in the input box** — right-click inside the editor pastes the system clipboard at the cursor through the editor's built-in paste entry: line endings/tabs are normalized (`\r`→`\n`, `\t`→4 spaces), large pastes (>10 lines or >1000 chars) collapse to a `[paste #N +X lines]` / `[paste #N X chars]` marker that expands back to full text on submit, and the paste is a single undo step. When the clipboard can't be read (platform channel + OSC 52 fallback both unavailable) or holds no text, a one-line hint appears and the editor is left untouched.
 
 **Transcript export** — `Alt+E` dumps the btw history (forked context, framing block, conversation, in-flight stream) to `$CWD/.agents/eval/pi-better-btw-<timestamp>.md` as a markdown diagnostic artifact, useful for debugging feature work.
-**Fork model switching** — `Alt+M` opens a model picker inside the overlay (`↑/↓` move, `Enter` confirm, `Esc` cancel). It lists the session's scoped models first (`--models` / `enabledModels`), falling back to the available catalogue, and only shows models with configured auth. Confirming swaps the fork agent's runtime model — the next turn uses it without rebuilding the fork — and clamps the thinking level to the new model's capabilities (no-reasoning models go to `off`). The choice is fork-local (ADR 0002): the main session's model is never touched. It survives backgrounding (`Alt+W`) and resets on `Alt+R`/`Alt+N`/`Esc` close. The header shows the current fork model; opening is rejected while streaming.
+**Fork model switching** — `Ctrl+L` opens a model picker inside the overlay (`↑/↓` move, `Enter` confirm, `Esc` cancel). It lists the session's scoped models first (`--models` / `enabledModels`), falling back to the available catalogue, and only shows models with configured auth. Confirming swaps the fork agent's runtime model — the next turn uses it without rebuilding the fork — and clamps the thinking level to the new model's capabilities (no-reasoning models go to `off`). The choice is fork-local (ADR 0002): the main session's model is never touched. It survives backgrounding (`Alt+W`) and resets on `Alt+R`/`Alt+N`/`Esc` close. The header shows the current fork model; opening is rejected while streaming.
 **Auto-retry (turn-level)** — reads pi's `settings.retry` budget (`enabled` / `maxRetries` / `baseDelayMs`, same defaults as the main session). Transient provider errors (overloaded / rate limit / 5xx) auto-retry with exponential backoff — the status area shows `Retrying (n/m) in Xs…` with a live countdown — and the failed assistant message is stripped before the retry so it never re-enters the next request. Context overflow and aborts never retry. `Esc` during the backoff cancels the wait and surfaces the last error as the final result; budget exhaustion does the same. With `enabled: false` (e.g. local-model debugging) errors surface immediately with zero overhead.
 
 
@@ -112,14 +112,16 @@ What changed since I opened this side chat?
 | `Alt+R` | Re-fork from latest main context |
 | `Alt+N` | Start empty conversation |
 | `Alt+E` | Export the btw chat history to `$CWD/.agents/eval/pi-better-btw-<timestamp>.md` |
-| `Alt+M` | Open the fork model picker (`↑/↓` select, `Enter` confirm, `Esc` cancel) |
-| `Ctrl+T` | Toggle read-only / edit mode |
+| `Ctrl+L` | Open the fork model picker (`↑/↓` select, `Enter` confirm, `Esc` cancel) |
+| `Alt+T` | Toggle read-only / edit mode |
 | `PgUp` / `PgDn` | Scroll history by a page |
 | `Shift+↑` / `Shift+↓` | Scroll by a few lines |
 | Mouse wheel | Scroll when the pointer is over the chat |
 | Mouse drag | Select text in the chat area (inverse-video highlight); no copy on release |
 | Double-click | Select the whole rendered line |
 | `Ctrl+C` / `Ctrl+Shift+C` | Copy the active mouse selection (the selection is kept until you click elsewhere, so repeated presses re-copy) |
+| `Ctrl+X` | Copy the last assistant message |
+| `Ctrl+V` / `Alt+V` | Paste the system clipboard at the cursor (same normalization + `[paste #N …]` markers as right-click paste) |
 | Mouse right-click (chat area) | Copy the retained mouse selection (fires on release, keeps the highlight) |
 | Mouse right-click (input editor) | Paste the system clipboard at the cursor (editor normalization + `[paste #N …]` markers for large pastes) |
 ## Command Reference
@@ -161,7 +163,7 @@ Keys:
   | Switch | Behavior when `false` |
   |--------|------------------------|
   | `rightClickCopyPaste` | right-click copy (chat) / paste (editor) is inert — the hotkeys still work |
-  | `modelSwitch` | `Alt+M` does nothing |
+  | `modelSwitch` | `Ctrl+L` does nothing |
   | `retry` | fork turns run a single attempt with zero backoff, even if pi's `settings.retry` is enabled |
 
 Example (user or project layer):
@@ -215,8 +217,8 @@ Structure:
 │   ├── side-chat-mouse.ts    # minimal SGR mouse parsing
 │   ├── clipboard-read.ts    # platform clipboard read (win32 / darwin / linux + OSC 52 fallback)
 │   ├── retry.ts             # turn-level retry: classifyRetryable + runWithRetry
-│   ├── shortcuts.ts         # hotkey bindings (Alt+W / Ctrl+T)
-│   ├── model-switch.ts       # Alt+M fork model picker: list building + thinking clamp
+│   ├── shortcuts.ts         # hotkey bindings (Alt+W / Alt+T)
+│   ├── model-switch.ts       # Ctrl+L fork model picker: list building + thinking clamp
 │   ├── side-chat-export.ts   # Alt+E transcript export
 │   ├── tool-wrapper.ts       # write-path overlap warnings
 │   └── file-activity-tracker.ts

package/README.zh-CN.md

@@ -32,7 +32,7 @@ pi install npm:pi-better-btw-plus
 [`@yceachan/pi-better-btw`](https://www.npmjs.com/package/@yceachan/pi-better-btw) 的全部功能都在，另新增：
 
 - **右键复制与粘贴** —— 聊天区拖选后右键复制（延续 Windows Terminal 肌肉记忆）；输入框右键从系统剪贴板粘贴，走编辑器内置归一化与大段 `[paste #N …]` 折叠标记。不再是 hotkey-only。
-- **Fork 模型切换（`Alt+M`）** —— 侧聊内选择任意已认证模型，无需重建 fork；仅作用于 fork 本身（ADR 0002），thinking level 按新模型能力自动钳制。
+- **Fork 模型切换（`Ctrl+L`）** —— 侧聊内选择任意已认证模型，无需重建 fork；仅作用于 fork 本身（ADR 0002），thinking level 按新模型能力自动钳制。
 - **Turn 级自动重试** —— 与主会话共用 `settings.retry` 预算：瞬时 provider 错误指数退避重试，带实时倒计时；`Esc` 取消。
 - **功能开关** —— 分层配置的 `features` 块可关闭以上任意功能（`rightClickCopyPaste` / `modelSwitch` / `retry`），另有 `readOnlyExtensionAllowlistExclude` 移除内置 allowlist 默认项。
 
@@ -54,7 +54,7 @@ pi install npm:pi-better-btw-plus
 
 - `TUI scroll,select,copy` ：在TUI-overlay 自订阅鼠标/hotkey事件，实现滚屏 ，text选中 ， Ctrl +C 复制功能
 
-- `Readonly/Edit Mode` : 默认只读来回应btw question，如果你希望Agent顺手做些小修改，Ctrl + t To Edit Mode.
+- `Readonly/Edit Mode` : 默认只读来回应btw question，如果你希望Agent顺手做些小修改，Alt + T To Edit Mode.
 
   - ToolAllowList : bundle + config.json custom
 
@@ -74,13 +74,13 @@ pi install npm:pi-better-btw-plus
 | 快捷键 | 作用 |
 | ------ | ---- |
 | `Alt+W` | 打开（关闭时）/ 后台化（显示时）/ 恢复（隐藏时） |
-| `Ctrl+T` | 切换只读 / 编辑模式 |
+| `Alt+T` | 切换只读 / 编辑模式 |
 | `Alt+R` | 从最新主线上下文重新 fork |
 | `Alt+N` | 开始空白对话 |
 | `Alt+E` | 导出对话记录到 `$CWD/.agents/eval/pi-better-btw-<timestamp>.md` |
-| `Alt+M` | 打开 fork 模型选择器（scoped + 已认证模型；`↑/↓` 选择，`Enter` 确认，`Esc` 取消） |
+| `Ctrl+L` | 打开 fork 模型选择器（scoped + 已认证模型；`↑/↓` 选择，`Enter` 确认，`Esc` 取消） |
 
-在Readonly Mode(default),只读车道是**强制的**：越权调用工具会被硬阻断并注入prompt；第二次违规会升级措辞并中止该轮，提示（`🚧 lane blocked` 状态行）。已执行但失败的只读调用会被 `afterToolCall` 备注再次归位。编辑模式（`Ctrl+T`）不受影响。
+在Readonly Mode(default),只读车道是**强制的**：越权调用工具会被硬阻断并注入prompt；第二次违规会升级措辞并中止该轮，提示（`🚧 lane blocked` 状态行）。已执行但失败的只读调用会被 `afterToolCall` 备注再次归位。编辑模式（`Alt+T`）不受影响。
 
 **窥视主线 agent** —— `peek_main` 工具读取主线会话的近期活动。
 
@@ -101,7 +101,7 @@ What changed since I opened this side chat?
 
 **对话导出** —— `Alt+E` 把 btw 历史（fork 上下文、framing 块、对话、流式中内容）导出为 `$CWD/.agents/eval/pi-better-btw-<timestamp>.md` 的 markdown 诊断产物，便于调试功能开发。
 
-**Fork 模型切换** —— `Alt+M` 在浮层内打开模型选择器（`↑/↓` 移动，`Enter` 确认，`Esc` 取消）。列表优先展示会话作用域模型（`--models` / `enabledModels`），为空时回退可用模型目录，且只显示已配置认证的模型。确认后直接替换 fork agent 的运行时模型——下一 turn 生效，无需重建 fork——并按新模型能力钳制 thinking level（无 reasoning 的模型钳制为 `off`）。选择为 fork 局部状态（ADR 0002）：主会话模型不受影响。后台化（`Alt+W`）保留选择；`Alt+R` / `Alt+N` / `Esc` 关闭后随实例重置。头部显示当前 fork 模型；流式期间拒绝打开。
+**Fork 模型切换** —— `Ctrl+L` 在浮层内打开模型选择器（`↑/↓` 移动，`Enter` 确认，`Esc` 取消）。列表优先展示会话作用域模型（`--models` / `enabledModels`），为空时回退可用模型目录，且只显示已配置认证的模型。确认后直接替换 fork agent 的运行时模型——下一 turn 生效，无需重建 fork——并按新模型能力钳制 thinking level（无 reasoning 的模型钳制为 `off`）。选择为 fork 局部状态（ADR 0002）：主会话模型不受影响。后台化（`Alt+W`）保留选择；`Alt+R` / `Alt+N` / `Esc` 关闭后随实例重置。头部显示当前 fork 模型；流式期间拒绝打开。
 
 ## 快捷键
 
@@ -113,14 +113,16 @@ What changed since I opened this side chat?
 | `Alt+R` | 从最新主线上下文重新 fork |
 | `Alt+N` | 开始空白对话 |
 | `Alt+E` | 导出 btw 对话历史到 `$CWD/.agents/eval/pi-better-btw-<timestamp>.md` |
-| `Alt+M` | 打开 fork 模型选择器（`↑/↓` 选择，`Enter` 确认，`Esc` 取消） |
-| `Ctrl+T` | 切换只读 / 编辑模式 |
+| `Ctrl+L` | 打开 fork 模型选择器（`↑/↓` 选择，`Enter` 确认，`Esc` 取消） |
+| `Alt+T` | 切换只读 / 编辑模式 |
 | `PgUp` / `PgDn` | 整页滚动历史 |
 | `Shift+↑` / `Shift+↓` | 按行滚动 |
 | 鼠标滚轮 | 指针位于聊天区域时滚动 |
 | 鼠标拖拽 | 选择聊天文本（反色高亮）；松开不自动复制 |
 | 双击 | 选择整行 |
 | `Ctrl+C` / `Ctrl+Shift+C` | 复制当前鼠标选择（选择保留到下次点击，可重复复制） |
+| `Ctrl+X` | 复制最后一条 assistant 消息 |
+| `Ctrl+V` / `Alt+V` | 把系统剪贴板粘贴到光标处（归一化 + `[paste #N …]` 标记，同右键粘贴） |
 | 鼠标右键（聊天区） | 复制保留的鼠标选择（松开时触发，保持高亮） |
 | 鼠标右键（输入框） | 把系统剪贴板粘贴到光标处（编辑器归一化 + 大段 `[paste #N …]` 标记） |
 ## 命令参考
@@ -162,7 +164,7 @@ pi-better-btw 从三个位置按优先级递增读取 `config.json` —— 每
   | 开关 | 为 `false` 时的行为 |
   | ---- | ---- |
   | `rightClickCopyPaste` | 右键复制（聊天区）/ 粘贴（输入框）失效——快捷键不受影响 |
-  | `modelSwitch` | `Alt+M` 无反应 |
+  | `modelSwitch` | `Ctrl+L` 无反应 |
   | `retry` | fork 每轮只跑一次尝试、零退避，即使 pi 的 `settings.retry` 开启 |
 
 示例（用户或项目层）：
@@ -216,8 +218,8 @@ btw 上下文保留主线的 system prompt 于 system 槽位，并逐字注入 f
 │   ├── side-chat-mouse.ts    # 最小 SGR 鼠标解析
 │   ├── clipboard-read.ts    # 平台剪贴板读取（win32 / darwin / linux + OSC 52 兜底）
 │   ├── retry.ts             # turn 级重试引擎：classifyRetryable + runWithRetry
-│   ├── model-switch.ts      # Alt+M fork 模型选择器：列表构建 + thinking 钳制
-│   ├── shortcuts.ts         # 快捷键绑定（Alt+W / Ctrl+T）
+│   ├── model-switch.ts      # Ctrl+L fork 模型选择器：列表构建 + thinking 钳制
+│   ├── shortcuts.ts         # 快捷键绑定（Alt+W / Alt+T）
 │   ├── side-chat-export.ts   # Alt+E 对话导出
 │   ├── tool-wrapper.ts       # 写路径重叠警告
 │   └── file-activity-tracker.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-btw-plus",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "pi extension: /btw side-chat overlay — maintained fork of @yceachan/pi-better-btw (+ right-click copy/paste, fork model switch, turn-level retry)",
   "type": "module",
   "keywords": [

package/prompts/lane-preamble.md

@@ -1 +1 @@
-You are in the read-only lane: only read/grep/find/ls, allowlisted tools and peek_main are available here. You cannot write files, edit, or execute commands — that is the main lane's job. If a write is genuinely needed, tell the user to switch to edit mode (Ctrl+T) or ask the main agent.
+You are in the read-only lane: only read/grep/find/ls, allowlisted tools and peek_main are available here. You cannot write files, edit, or execute commands — that is the main lane's job. If a write is genuinely needed, tell the user to switch to edit mode (Alt+T) or ask the main agent.

package/prompts/lane-reminder-base.md

@@ -1 +1 @@
-🚧 Lane blocked: `{{tool}}` is not available in this side chat. You are the btw side chat — a quick-question lane parallel to the main agent; the main line is the main agent's job. Answer the latest user message only, with read-only tools (read/grep/find/ls + allowlisted tools). If a write is genuinely needed, tell the user to switch to edit mode (Ctrl+T).
+🚧 Lane blocked: `{{tool}}` is not available in this side chat. You are the btw side chat — a quick-question lane parallel to the main agent; the main line is the main agent's job. Answer the latest user message only, with read-only tools (read/grep/find/ls + allowlisted tools). If a write is genuinely needed, tell the user to switch to edit mode (Alt+T).

package/srcs/clipboard-read.ts

@@ -4,10 +4,13 @@
  *
  * The write side is pi's own `copyToClipboard` (public export); the read side
  * is self-built because `readClipboardText` is not re-exported from the
- * package entry. Each platform maps to a primary channel:
+ * package entry. The PRIMARY channel mirrors pi's own `readClipboardText` (the
+ * `@mariozechner/clipboard` native addon); the remaining channels — PowerShell
+ * `Get-Clipboard -Raw` (win32), `pbpaste` (darwin), and an OSC 52 query — are
+ * extension-only fallbacks pi's read side does not have:
  *
- *   - win32  → native addon `getText` (pi's own clipboard read), then
- *     PowerShell `Get-Clipboard -Raw`, then an OSC 52 query;
+ *   - win32  → native addon `getText`, then PowerShell `Get-Clipboard -Raw`,
+ *     then an OSC 52 query;
  *   - darwin → native addon `getText`, then `pbpaste`, then OSC 52 query;
  *   - linux  → OSC 52 query (`\x1b]52;c;?\x07`, read the reply).
  *
@@ -124,11 +127,11 @@ export interface CommandChannelOptions {
 }
 
 /**
- * PowerShell channel: `powershell.exe -NoProfile -Command "Get-Clipboard
- * -Raw"`, mirroring pi's clipboard-image PowerShell channel family. The
- * `-Raw` flag preserves the exact text (no extra newline), and the output
- * encoding is pinned to UTF-8 because the text travels over the console
- * pipe (pi's image reader sidesteps this by writing a temp file).
+ * PowerShell read fallback (extension-only; pi's readClipboardText has no
+ * PowerShell channel): `powershell.exe -NoProfile -Command "Get-Clipboard
+ * -Raw"`. The `-Raw` flag preserves the exact text (no extra newline), and the
+ * output encoding is pinned to UTF-8 because the text travels over the console
+ * pipe.
  */
 const PS_GET_CLIPBOARD_SCRIPT =
   "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; Get-Clipboard -Raw";
@@ -244,11 +247,11 @@ export function makeNativeChannel(
 }
 
 /**
- * PowerShell channel: `powershell.exe -NoProfile -Command "Get-Clipboard
- * -Raw"`, mirroring pi's clipboard-image PowerShell channel family. The
- * `-Raw` flag preserves the exact text (no extra newline), and the output
- * encoding is pinned to UTF-8 because the text travels over the console
- * pipe (pi's image reader sidesteps this by writing a temp file).
+ * PowerShell read fallback (extension-only; pi's readClipboardText has no
+ * PowerShell channel): `powershell.exe -NoProfile -Command "Get-Clipboard
+ * -Raw"`. The `-Raw` flag preserves the exact text (no extra newline), and the
+ * output encoding is pinned to UTF-8 because the text travels over the console
+ * pipe.
  */
 export function makePowerShellChannel(
   options: CommandChannelOptions = {},

package/srcs/config.ts

@@ -1,7 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { PromptPackManifest } from "./prompt-pack.ts";
+import type { ProviderRetrySettings } from "./provider-retry.ts";
 import type { RetryPolicy } from "./retry.ts";
 /**
  * Layered config resolution for pi-better-btw.
@@ -36,7 +38,7 @@ import type { RetryPolicy } from "./retry.ts";
 export interface SideChatFeatures {
   /** Right-click copy (chat selection) / paste (editor). Default: true. */
   rightClickCopyPaste: boolean;
-  /** Alt+M fork model picker. Default: true. */
+  /** Ctrl+L fork model picker. Default: true. */
   modelSwitch: boolean;
   /** Turn-level auto-retry of transient provider errors. Default: true. */
   retry: boolean;
@@ -65,13 +67,15 @@ export const USER_CONFIG_DIR = join(homedir(), ".pi", "agent", CONFIG_SUBDIR);
 export const AGENT_CONFIG_DIR = join(homedir(), ".pi", "agent");
 
 /**
- * Read pi's `settings.retry` budget (D8). The fork shares pi's settings files
- * rather than re-declaring them: global <agentConfigDir>/settings.json merged
- * with project <cwd>/.pi/settings.json (project wins per key, mirroring pi's
- * deepMergeSettings), then the `retry` block is extracted with pi's defaults
- * (settingsManager.getRetrySettings: enabled=true, maxRetries=3,
- * baseDelayMs=2000). Invalid/absent files contribute nothing; a present-but-
- * unreadable file warns instead of failing the fork.
+ * Read pi's `settings.retry` budget (D8) via pi's own `SettingsManager` —
+ * file reading, deep merge (project wins per key), legacy migration
+ * (`retry.maxDelayMs` → `retry.provider.maxRetryDelayMs`) and the canonical
+ * defaults (enabled=true, maxRetries=3, baseDelayMs=2000) all come from pi; no
+ * hand-rolled duplicate. The `retry.provider` block (spec #20 D4: timeoutMs /
+ * maxRetries / maxRetryDelayMs) is forwarded only when a provider block is
+ * actually configured, and only number keys; it is consumed solely by the
+ * overlay's stream assembly, never by the turn loop. A present-but-unreadable
+ * settings file warns and contributes nothing (pi's own fallback).
  */
 export interface LoadRetryPolicyOptions {
   /** Agent config dir holding pi's global settings.json (~/.pi/agent). */
@@ -85,53 +89,44 @@ function isPlainRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Deep merge like pi's deepMergeSettings: nested plain objects merge, arrays/others replace. */
-function deepMergeSettings(
-  base: Record<string, unknown>,
-  overrides: Record<string, unknown>,
-): Record<string, unknown> {
-  const result = { ...base };
-  for (const [key, value] of Object.entries(overrides)) {
-    const baseValue = result[key];
-    result[key] =
-      isPlainRecord(baseValue) && isPlainRecord(value)
-        ? deepMergeSettings(baseValue, value)
-        : value;
-  }
-  return result;
-}
-
-function readSettingsFile(
-  path: string,
-  onWarning?: (message: string) => void,
-): Record<string, unknown> {
-  try {
-    const raw: unknown = JSON.parse(readFileSync(path, "utf-8"));
-    return isPlainRecord(raw) ? raw : {};
-  } catch {
-    if (existsSync(path) && onWarning) {
-      onWarning(`pi-better-btw: ignoring invalid settings ${path}`);
-    }
-    return {};
-  }
-}
 
 export function loadRetryPolicy(options: LoadRetryPolicyOptions = {}): RetryPolicy {
   const agentConfigDir = options.agentConfigDir ?? AGENT_CONFIG_DIR;
-  const merged = deepMergeSettings(
-    readSettingsFile(join(agentConfigDir, "settings.json"), options.onWarning),
-    options.cwd
-      ? readSettingsFile(join(options.cwd, ".pi", "settings.json"), options.onWarning)
-      : {},
-  );
-  const retry = isPlainRecord(merged.retry) ? merged.retry : {};
+  const settings = SettingsManager.create(options.cwd ?? process.cwd(), agentConfigDir, {
+    projectTrusted: true,
+  });
+  // Surface load errors (invalid JSON etc.) through the caller's warning hook,
+  // mirroring the old loader's present-but-unreadable → warn behavior.
+  for (const err of settings.drainErrors()) {
+    options.onWarning?.(`pi-better-btw: ignoring invalid settings (${err.scope})`);
+  }
+  const retry = settings.getRetrySettings();
+  // Provider block (spec #20): forward only number keys from an actually
+  // configured `retry.provider`. getProviderRetrySettings() defaults
+  // maxRetryDelayMs to 60000 even when no block exists, so configured-ness is
+  // detected from the (already-migrated) per-scope settings; an absent block
+  // keeps `provider` undefined so the overlay's stream assembly stays identity
+  // (D3: unconfigured users keep the bare streamSimple, zero overhead).
+  const providerRetry = settings.getProviderRetrySettings();
+  const providerConfigured = [
+    settings.getGlobalSettings(),
+    settings.getProjectSettings(),
+  ].some((scope) => isPlainRecord(scope.retry) && isPlainRecord(scope.retry.provider));
+  const providerBlock: ProviderRetrySettings = {};
+  if (providerConfigured) {
+    // Number filter kept (vs. blindly forwarding getProviderRetrySettings) to
+    // keep the D3 identity contract stable: non-number keys never reach
+    // injectProviderRetry, and an unconfigured provider stays undefined.
+    if (typeof providerRetry.timeoutMs === "number") providerBlock.timeoutMs = providerRetry.timeoutMs;
+    if (typeof providerRetry.maxRetries === "number") providerBlock.maxRetries = providerRetry.maxRetries;
+    if (typeof providerRetry.maxRetryDelayMs === "number")
+      providerBlock.maxRetryDelayMs = providerRetry.maxRetryDelayMs;
+  }
   return {
-    enabled:
-      typeof retry.enabled === "boolean" ? retry.enabled : true,
-    maxRetries:
-      typeof retry.maxRetries === "number" ? retry.maxRetries : 3,
-    baseDelayMs:
-      typeof retry.baseDelayMs === "number" ? retry.baseDelayMs : 2000,
+    enabled: retry.enabled,
+    maxRetries: retry.maxRetries,
+    baseDelayMs: retry.baseDelayMs,
+    ...(Object.keys(providerBlock).length > 0 ? { provider: providerBlock } : {}),
   };
 }