@zhuxixi/pi-agent-board 0.10.0 → 0.10.2

package/docs/superpowers/specs/2026-10-09-issue-167-attach-middle-paste-design.md

@@ -0,0 +1,125 @@
+# Spec: #167 — middle-click paste in attach views under pi ≥1.0 fullscreen TUI
+
+Status: DRAFT (awaiting user approval — github-issue-driven step 4 gate)
+Issue: https://github.com/zhuxixi/pi-agent-board/issues/167
+Date: 2026-10-09
+
+## Problem (root cause, verified)
+
+pi ≥1.0 defaults to fullscreen TUI. `TuiAltScreen` parses and consumes all SGR mouse
+sequences itself; overlays receive mouse only through the normalized `handleMouse(event)`
+API. `PtyAttachComponent` implements only the legacy `handleInput(data)` path, so its
+middle-click paste (`pastePrimarySelection()`, commit a1c5f08) never runs in fullscreen.
+Regular mode (`pi --tui-mode regular`) is unaffected. Evidence: pi-tui 1.1.0
+`tui-alt-screen.js:520-526`, `tui.js:507-532`; research notes in
+`~/.claude/github-issue-driven/zhuxixi/pi-agent-board/issue-167/research/`.
+
+## Goal / non-goals
+
+**Goal**: middle-click inside the attach view pastes the X11 PRIMARY selection into the
+hosted session in fullscreen mode, with the same semantics and escape hatch as regular
+mode; regular mode behavior unchanged.
+
+**Non-goals** (explicitly deferred):
+- X11 PRIMARY *mirroring* of selections made in fullscreen (pi's own fullscreen selection
+  writes CLIPBOARD, not PRIMARY). Taking over left-button events would displace pi's
+  fullscreen selection — needs its own design (follow-up).
+- #169 (attach teardown disabling outer-terminal mouse reporting) — separate issue/PR.
+- Any wheel behavior change (today's defer-to-overlay fallback keeps working; we return
+  `undefined` for wheel).
+
+## Design
+
+### 1. Pure decision helper (new, `src/core/pty-scroll.mjs` — same module that owns
+`parseMouseInputChunk`)
+
+```js
+// Returns the attach-surface action for a normalized pi-tui mouse event.
+// "paste-primary": read X11 PRIMARY and forward as input (middle-click paste).
+// null: not ours — let the event fall through untouched (today's behavior).
+resolveAttachMouseAction(event, { nativePasteEnabled }) → "paste-primary" | null
+```
+
+Decision table (`event.type`, `event.button`, `nativePasteEnabled`):
+
+| type | button | nativePasteEnabled | result |
+| --- | --- | --- | --- |
+| press | middle | true | `"paste-primary"` |
+| press | middle | false | `null` (kill switch = today's silent drop) |
+| press/release/click | left/right/none | * | `null` (pi fullscreen selection & default behavior untouched) |
+| wheel | any | * | `null` (existing defer-to-`handleInput` path preserved) |
+| move/drag | any | * | `null` |
+
+`nativePasteEnabled` is computed once per call site from
+`process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0"` (same rule as `pastePrimarySelection`).
+
+### 2. Component wiring (`src/ui/pty-attach.ts`)
+
+```ts
+handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+	const action = resolveAttachMouseAction(event, {
+		nativePasteEnabled: process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0",
+	});
+	if (action === "paste-primary") {
+		this.clearPendingClick();
+		this.clearSelection();
+		this.pastePrimarySelection();
+		return { handled: true, render: false };
+	}
+	return undefined;
+}
+```
+
+- `{ handled: true }` stops propagation and suppresses alt-screen fallback for that
+  press; `render: false` because a successful paste repaints via child output (async)
+  and a failed one (no xclip) needs no repaint.
+- Legacy `handleInput` raw path stays exactly as is — regular mode and wheel keep working.
+- No changes to outer-terminal mouse-mode writes (`MOUSE_ENABLE`/`MOUSE_DISABLE`) — #169.
+
+### 3. devDependencies bump (enabling task)
+
+Bump `@earendil-works/pi-tui` and `@earendil-works/pi-coding-agent` devDeps 0.79.8 → 1.1.0
+(match the runtime the extension actually runs under). Gate: `npm run typecheck` +
+`npm run verify` green. If unrelated type breakage from 0.79.8→1.1.0 turns out to be large,
+fallback: keep 0.79.8 and declare local structural `TuiMouseEvent`/result types in the
+component — decision point recorded in the plan; the bump is the preferred path.
+
+## Acceptance matrix
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | 决策表：哪些归一化鼠标事件触发中键粘贴 | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs`（新增用例直接调 `resolveAttachMouseAction`，覆盖决策表全部行 + `AGENT_BOARD_ATTACH_NATIVE_PASTE=0`） | 新增用例全绿，且现有点击/滚轮用例不回归 |
+| A2 | 组件接线：`PtyAttachComponent.handleMouse` 中键 press → 读 PRIMARY → 作为 input 发往 attach socket；kill switch 时返回 undefined | 自动化验证（integration，组件级场景） | 新增 `test-support/pty-attach-mouse-scenario.ts`（仿 `pty-attach-protocol-scenario.ts`：fake tui + stub-`xclip` 目录 prepend PATH 打印 fixture 文本），由 `test/pty-attach-mouse.test.mjs` 以 `node --experimental-transform-types` 运行并断言 JSON 输出 | ① 中键 press 返回 `{handled:true}` 且 socket 收到 `{type:"input",data:fixture}`；② 同场景 legacy `handleInput` 注入 SGR 中键序列行为一致（regular 路径回归）；③ `AGENT_BOARD_ATTACH_NATIVE_PASTE=0` 时 `handleMouse` 返回 undefined 且无 input 发出 |
+| A3 | 类型与构建在 pi-tui 1.1.0 下成立 | 自动化验证（static/build） | `npm run typecheck`、`npm run verify`（含 pack:dry） | 全部通过，无 0.79.8→1.1.0 引入的未处理类型错误 |
+| A4 | 全部既有行为不回归 | 自动化验证（unit+integration，既有套件） | `npm test` / `npm run test:coverage` | 既有测试全绿，覆盖阈值不降 |
+| U1 | 真实终端里 fullscreen 中键粘贴生效 | 用户实测 | ① pi 1.1.0 fullscreen → `/agent-board` → attach；② 在别的 X11 应用选中一段文字；③ 在 attach 视图内中键 | 子 session 收到粘贴文本并有反应；同机 `pi --tui-mode regular` 行为不变；`AGENT_BOARD_ATTACH_NATIVE_PASTE=0` 后中键回到无反应 |
+
+## Testability split design (hard constraint for implementation)
+
+- **Pure core**: `resolveAttachMouseAction(event, {nativePasteEnabled})` — plain function,
+  no I/O, no env reads inside (env read at call site). Unit-tested decision table (A1).
+  Test boundary: `src/core/pty-scroll.mjs` exports; tests import only this.
+- **I/O shell**: `PtyAttachComponent.handleMouse` maps action → `pastePrimarySelection()`
+  (existing xclip spawn) + result object. Tested at component level (A2) through public
+  seams only: `handleMouse`/`handleInput` in, fake tui terminal writes + attach-socket
+  messages out, `xclip` stubbed via PATH. No test-only constructor options.
+- The pure function must not be re-coupled into the component (no inline decision logic).
+
+## Risks / notes
+
+- devDep bump may expose type breakage elsewhere (0.79.8 typings vs 1.1.0). Contained by
+  A3 as its own task; fallback documented above.
+- `AGENT_BOARD_ATTACH_MOUSE=0` does not disable the new path (it governs outer-terminal
+  mode writes only); in fullscreen the alt screen owns reporting regardless. Documented
+  here as intended.
+- Behavior when xclip is absent: unchanged silent no-op (existing contract), but the
+  event is still consumed (`handled:true`) — same as regular mode today.
+
+## Deliverables
+
+- `src/core/pty-scroll.mjs`: + `resolveAttachMouseAction`
+- `src/ui/pty-attach.ts`: + `handleMouse`
+- `package.json`: devDeps bump (pi-tui, pi-coding-agent → 1.1.0)
+- `test/pty-scroll.test.mjs`: decision-table cases
+- `test-support/pty-attach-mouse-scenario.ts` + `test/pty-attach-mouse.test.mjs`
+- CHANGELOG entry via release tooling at release time (not in this PR)

package/docs/superpowers/specs/2026-10-09-issue-169-fullscreen-mouse-ownership-design.md

@@ -0,0 +1,130 @@
+Drafted: zai-coding-cn/glm-5.3 (selected) · zai-coding-cn/glm-5.3 (physical) @ 2026-10-09T12:49:41Z
+
+# Spec: #169 — detaching from a PTY attach view kills outer-terminal mouse reporting for the rest of the fullscreen session
+
+Status: DRAFT (awaiting spec-cross-review, then user approval — github-issue-driven step 4 gates)
+Issue: https://github.com/zhuxixi/pi-agent-board/issues/169
+Repo state baseline: main @ `fee345c` (post-#171)
+
+## Problem (root cause, verified from source)
+
+In fullscreen mode (pi ≥1.0 default) `TuiAltScreen` owns outer-terminal mouse reporting:
+it writes the enable set `?1000h?1002h?1003h?1004h?1006h` exactly once in
+`beforeTerminalStart` (pi-tui 1.1.0 `tui-alt-screen.js:194`) and disables it only at
+`beforeTerminalStop` (:196-206); there is no re-assert path. `PtyAttachComponent` nonetheless
+manages the outer terminal's mouse mode itself — ctor writes
+`MOUSE_DISABLE`+`MOUSE_ENABLE` (downgrading `?1003h`/`?1004h`), and `close()` writes
+`MOUSE_DISABLE` unconditionally (src/ui/pty-attach.ts:278-280, :1524 via
+`disableMouseScroll` :882 — which, unlike `enableMouseScroll`, has no env guard). After
+the first detach, pi-tui still believes mouse is on but the terminal stopped sending
+events: fullscreen selection / copy-on-select / wheel / click regions are dead until pi
+restarts. In regular mode the same writes are correct (board is the sole mouse owner).
+
+Full evidence: `research/2026-10-09-fullscreen-mouse-ownership.md`,
+`research/2026-10-09-repo-state-and-testability.md` in this directory.
+
+## Goal / non-goals
+
+**Goal**: in fullscreen mode the attach component performs **zero** outer-terminal
+mouse-mode writes for its entire lifecycle (ctor, refresh timers, connect, resize,
+close) — `TuiAltScreen` owns the mode and its full `?1003h/?1004h` set survives
+attach AND detach. Regular-mode behavior (including the
+disable→enable→refresh pairing and the kill-switch semantics) is unchanged. Old pi
+runtimes without `tui.mode` keep today's (regular) behavior.
+
+**Non-goals**:
+- X11 PRIMARY mirroring of the fullscreen-native selection (deferred with #167).
+- Any pi-tui change or new re-assert API (unnecessary).
+- Wheel/scroll/selection behavior inside attach views (unchanged by design: deferred
+  wheel still reaches `handleInput`; clicks via `handleMouse` from #171).
+- #170 (reply guard), #168 (session resume) — unrelated paths.
+
+## Design
+
+### 1. Pure decision helper (new, `src/core/pty-scroll.mjs` — mouse helpers live here)
+
+```js
+/**
+ * Issue #169: whether the attach surface should manage the OUTER terminal's mouse
+ * mode. Only in regular TUI mode — in fullscreen, TuiAltScreen owns mouse reporting
+ * (asserted once at startup, never re-asserted), so any write from here can only
+ * downgrade or kill it. Old runtimes without tui.mode behave as regular.
+ * Pure: mode and the env-derived flag are resolved at the call site.
+ */
+shouldOwnOuterMouseMode(mode, mouseEnabled) → boolean   // mode !== "fullscreen" && mouseEnabled
+```
+
+### 2. Component gating (`src/ui/pty-attach.ts`)
+
+All outer-terminal mouse writes funnel through exactly two private methods —
+`enableMouseScroll()` (:852) and `disableMouseScroll()` (:882). Gate both:
+
+```ts
+private ownsOuterMouseMode(): boolean {
+	return shouldOwnOuterMouseMode(this.tui.mode, this.mouseScrollEnabled());
+}
+```
+
+- `enableMouseScroll()`: early-return `if (!this.ownsOuterMouseMode())` (replaces the
+  current `mouseScrollEnabled()` check; also gates the `XTSHIFTESCAPE_SELECT` write).
+- `disableMouseScroll()`: early-return `if (!this.ownsOuterMouseMode())` (new guard —
+  fixes both the fullscreen teardown kill and the flagged unguarded disable under
+  `AGENT_BOARD_ATTACH_MOUSE=0`).
+- `refreshMouseScrollMode()` keeps its `mouseScrollEnabled()` early-return (cheap) and
+  its timers call the now-gated `enableMouseScroll` — no other call-site changes
+  (ctor :278-280, connect :487, resize :1203, close :1524 all route through the two
+  choke points).
+- Comment on `ownsOuterMouseMode()` noting `tui.mode` is typed non-optional but may be
+  absent on old runtimes — strict inequality handles it.
+
+### Resulting behavior matrix
+
+| tui.mode | AGENT_BOARD_ATTACH_MOUSE | ctor/connect/resize writes | close() write | fullscreen session after detach |
+| --- | --- | --- | --- | --- |
+| fullscreen | any | none | none | mouse alive (BUG FIXED) |
+| regular / undefined (old runtime) | on (default) | today's pairing | MOUSE_DISABLE | n/a (unchanged) |
+| regular / undefined | off | none | none | n/a (also fixes unguarded-disable defect) |
+| fullscreen (host built with TuiAltScreenOptions.mouse: false) | n/a | none | none | consistent: host explicitly disabled mouse; nothing owns it — attach-view mouse features inert by host choice |
+
+## Acceptance matrix
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | 鼠标模式所有权决策表（mode × env 开关） | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs`（新增用例直接调 `shouldOwnOuterMouseMode`，覆盖 6 格：fullscreen×on/off、regular×on/off、undefined×on/off） | 新增用例全绿，现有点击/滚轮/中键用例不回归 |
+| A2 | fullscreen 全生命周期零外层鼠标写；regular 配对保留；kill switch 零写 | 自动化验证（integration，组件级场景） | 新增 `test-support/pty-attach-mouse-mode-scenario.ts`（fake tui 的 `terminal.write` 采集字节 + `mode` 可控 + 不可达 socketPath），由 `test/pty-attach-mouse-mode.test.mjs` 以 `node --experimental-transform-types` 运行断言 JSON 输出 | ① `mode:"fullscreen"`：ctor+250ms 刷新窗+close 全程 0 个 `?1000/?1002/?1003/?1004/?1006/XTSHIFTESCAPE` 写；② `mode:"regular"`：ctor 有 `MOUSE_ENABLE`、close 有 `MOUSE_DISABLE`；③ regular+`AGENT_BOARD_ATTACH_MOUSE=0`：全程 0 写（含 close）；④ 无 `mode` 字段的 fake tui 行为同 regular |
+| A3 | 类型与构建 | 自动化验证（static/build） | `npm run typecheck`、`npm run verify`（含 pack:dry） | 全部通过 |
+| A4 | 既有行为不回归（含 #171 中键粘贴场景） | 自动化验证（unit+integration，既有套件） | `npm test` / `npm run test:coverage` | 既有测试全绿，覆盖阈值不降 |
+| U1 | 真机：detach 后外层鼠标存活 | 用户实测 | ① pi ≥1.0 fullscreen → `/agent-board` → attach → detach（ctrl+\）；② dashboard 里拖选文字 → 应高亮且 copy-on-select 生效；③ 滚轮/点击区域正常；④ attach 中 pi 自身全屏选中/复制正常（`?1003h/?1004h` 不再被降级）；⑤ `pi --tui-mode regular` 下 attach→detach 行为与从前一致 | ①–⑤ 全部符合；修复前 ①③④ 在 detach 后失效 |
+
+## Testability split design (hard constraint for implementation)
+
+- **Pure core**: `shouldOwnOuterMouseMode(mode, mouseEnabled)` — plain function, no env
+  reads inside (both args resolved at the call site). Unit-tested decision table (A1).
+  Test boundary: `src/core/pty-scroll.mjs` exports; tests import only this.
+- **I/O shell**: `PtyAttachComponent.ownsOuterMouseMode()` reads `this.tui.mode` +
+  `this.mouseScrollEnabled()` and delegates to the pure helper; the two write methods
+  keep ALL terminal writes. Component-level tests (A2) drive only public seams
+  (constructor, time, `dispose()`) and observe `terminal.write` bytes of a fake tui —
+  no test-only constructor options, no reading private state.
+- The pure helper must not be re-inlined into the component; the two choke-point methods
+  must remain the only places that write mouse-mode/XTSHIFTESCAPE sequences.
+
+## Risks / notes
+
+- A2 uses an unreachable socketPath to keep the scenario runner-free; if the ctor's
+  connect-error path proves non-deterministic for the write-spy assertions, fall back to
+  the #171-style real-runner scenario asserting the same facts around a real
+  attach/detach (decision at plan time; record whichever is used).
+- Existing scenarios' fake tuis have no `mode` field → they stay on the regular path and
+  don't assert terminal bytes → unaffected by the gating.
+- `AGENT_BOARD_ATTACH_MOUSE` semantics in fullscreen become moot (no writes either way);
+  document in the behavior matrix rather than redefining the switch.
+
+## Deliverables
+
+- `src/core/pty-scroll.mjs`: + `shouldOwnOuterMouseMode`
+- `src/ui/pty-attach.ts`: + `ownsOuterMouseMode()` private method; guards in
+  `enableMouseScroll` / `disableMouseScroll`
+- `test/pty-scroll.test.mjs`: decision-table cases
+- `test-support/pty-attach-mouse-mode-scenario.ts` + `test/pty-attach-mouse-mode.test.mjs`
+- CHANGELOG entry via release tooling at release time (not in this PR)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zhuxixi/pi-agent-board",
-	"version": "0.10.0",
+	"version": "0.10.2",
 	"description": "Agent-board dashboard for Pi: dispatch, monitor, peek/reply, and attach to background Pi sessions.",
 	"type": "module",
 	"main": "./index.ts",
@@ -73,8 +73,8 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.79.8",
-		"@earendil-works/pi-tui": "0.79.8",
+		"@earendil-works/pi-coding-agent": "1.1.0",
+		"@earendil-works/pi-tui": "1.1.0",
 		"@types/node": "^25.9.1",
 		"c8": "^12.0.0",
 		"typescript": "^5.9.3"

package/src/commands/agent-board.ts

@@ -11,6 +11,7 @@ import { requestDashboardRender } from "../core/dashboard-render.mjs";
 import { createService } from "../runtime/service.mjs";
 import { planAttachPrelude, planAttachResolved } from "./attach-decision.mjs";
 import { screenLogPath } from "../core/paths.mjs";
+import { appendDiagnostic } from "../core/diagnostics.mjs";
 import { DashboardComponent, type DashboardResult } from "../ui/dashboard.js";
 import { PtyAttachComponent, type PtyAttachResult } from "../ui/pty-attach.js";
 
@@ -241,6 +242,16 @@ async function openPtyAttach(
 					socketPath,
 					screenLogPath: root ? screenLogPath(root, viewId) : undefined,
 					title: name,
+					onDiagnostic: root
+						? (event) => {
+								// Best effort, like every other diagnostics writer.
+								try {
+									appendDiagnostic(root, viewId, event as never);
+								} catch {
+									/* diagnostics must never break attach */
+								}
+							}
+						: undefined,
 				}),
 			{
 				overlay: true,

package/src/commands/attach-flow.ts

@@ -13,6 +13,7 @@ import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import { createService } from "../runtime/service.mjs";
 import { planAttachPrelude, planAttachResolved } from "./attach-decision.mjs";
 import { screenLogPath } from "../core/paths.mjs";
+import { appendDiagnostic } from "../core/diagnostics.mjs";
 import { PtyAttachComponent, type PtyAttachResult } from "../ui/pty-attach.js";
 import type { DashboardResult } from "../ui/dashboard.js";
 
@@ -39,6 +40,16 @@ export async function openPtyAttach(
 					socketPath,
 					screenLogPath: root ? screenLogPath(root, viewId) : undefined,
 					title: name,
+					onDiagnostic: root
+						? (event) => {
+								// Best effort, like every other diagnostics writer.
+								try {
+									appendDiagnostic(root, viewId, event as never);
+								} catch {
+									/* diagnostics must never break attach */
+								}
+							}
+						: undefined,
 				}),
 			{
 				overlay: true,

package/src/core/pty-scroll.mjs

@@ -94,6 +94,31 @@ export function parseMouseInputChunk(data) {
 	return events;
 }
 
+/**
+ * Issue #167: map a normalized pi-tui mouse event on the attach surface to an
+ * action. "paste-primary" = middle-click paste (read X11 PRIMARY, forward as
+ * input); null = not ours, the event falls through untouched (pi's fullscreen
+ * selection, the wheel defer path, and everything else keep working). Pure by
+ * contract: the env flag is resolved at the call site, never read here.
+ */
+export function resolveAttachMouseAction(event, { nativePasteEnabled }) {
+	if (!nativePasteEnabled) return null;
+	if (event.type === "press" && event.button === "middle") return "paste-primary";
+	return null;
+}
+
+/**
+ * Issue #169: whether the attach surface should manage the OUTER terminal's
+ * mouse mode. Only in regular TUI mode — in fullscreen, TuiAltScreen owns
+ * mouse reporting (asserted once at startup, never re-asserted), so any write
+ * from the attach surface can only downgrade or kill it. Old runtimes without
+ * tui.mode behave as regular. Pure: both arguments are resolved at the call
+ * site (mode from the TUI, the flag from the env-derived helper).
+ */
+export function shouldOwnOuterMouseMode(mode, mouseEnabled) {
+	return mode !== "fullscreen" && !!mouseEnabled;
+}
+
 /**
  * Return +1 for wheel-up (scroll back), -1 for wheel-down, 0 for non-wheel input.
  * Supports standard/passive SGR and X10/normal mouse encodings.

package/src/core/terminal-query-sequences.mjs

@@ -156,3 +156,84 @@ function toLinearChannel(channel) {
 	const value = channel / 255;
 	return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
 }
+
+// --- Attach settle scheme probe (issue #161) -------------------------------
+// pi-tui >= 0.99 renamed queryTerminalBackgroundColor -> queryTerminalColors.
+// This repo compiles against pi-tui 0.79.8 but the extension runs against the
+// host pi's pi-tui (peerDependencies "*"), so the probe feature-detects at
+// runtime. Local structural typedefs only — TerminalColors does not exist on
+// the 0.79.8 compile face and must not be imported.
+
+/** @typedef {{ r: number, g: number, b: number }} SettleRgb */
+/** @typedef {{ background?: SettleRgb, foreground?: SettleRgb, palette?: SettleRgb[] }} TerminalColorsLike */
+/** @typedef {{ queryTerminalColors?: (opts: { timeoutMs: number, onLateReply?: (colors: TerminalColorsLike) => void }) => Promise<TerminalColorsLike>, queryTerminalBackgroundColor?: (opts: { timeoutMs: number }) => Promise<SettleRgb|undefined> }} SettleProbeSurface */
+/** @typedef {{ rgb?: SettleRgb, anyColors: boolean }} SettleProbeResult */
+
+/**
+ * Issue #161: detect which terminal color query API a TUI surface exposes.
+ * Detection is pure; the returned adapter only calls the passed-in surface.
+ * @param {SettleProbeSurface} tuiLike
+ * @returns {{ api: "colors"|"background"|"none", invoke: (tui: SettleProbeSurface, timeoutMs: number, onLateReply?: (colors: TerminalColorsLike) => void) => Promise<SettleProbeResult> }}
+ */
+export function resolveProbeApi(tuiLike) {
+	if (tuiLike && typeof tuiLike.queryTerminalColors === "function") {
+		return {
+			api: "colors",
+			invoke: async (tui, timeoutMs, onLateReply) => {
+				const colors = await tui.queryTerminalColors({ timeoutMs, onLateReply });
+				return { rgb: backgroundRgbFromTerminalColors(colors), anyColors: hasAnyColor(colors) };
+			},
+		};
+	}
+	if (tuiLike && typeof tuiLike.queryTerminalBackgroundColor === "function") {
+		return {
+			api: "background",
+			invoke: async (tui, timeoutMs) => {
+				const rgb = await tui.queryTerminalBackgroundColor({ timeoutMs });
+				return { rgb, anyColors: rgb !== undefined };
+			},
+		};
+	}
+	return { api: "none", invoke: async () => ({ rgb: undefined, anyColors: false }) };
+}
+
+/** @param {TerminalColorsLike} colors @returns {SettleRgb|undefined} */
+export function backgroundRgbFromTerminalColors(colors) {
+	return colors && typeof colors === "object" ? colors.background : undefined;
+}
+
+/** @param {TerminalColorsLike} colors @returns {boolean} */
+function hasAnyColor(colors) {
+	if (!colors || typeof colors !== "object") return false;
+	if (colors.background !== undefined || colors.foreground !== undefined) return true;
+	return Array.isArray(colors.palette) && colors.palette.some((c) => c !== undefined);
+}
+
+const SETTLE_SCHEME_WARN_OUTCOMES = new Set(["timeout", "error", "no_background", "no_probe_api", "dropped_disconnected"]);
+
+/**
+ * Issue #161: build the DiagnosticEvent-compatible patch for the settle scheme
+ * flow. Field names MUST stay inside normalizeDiagnostic's whitelist
+ * (level/code/runId/source/message/details) — anything else is silently
+ * dropped. Warn only when delivery was expected but failed; routine outcomes
+ * (dedup, quick detach, kill switch) stay info so warningCount stays meaningful.
+ * @param {{ probeApi?: "colors"|"background"|"none", outcome: "reported"|"timeout"|"error"|"no_background"|"no_probe_api"|"dropped_closed"|"dropped_disconnected"|"duplicate_skipped"|"suppressed", report?: string, late?: boolean }} details
+ * @returns {{ source: string, level: "info"|"warn", code: string, message: string, details: { probeApi?: string, outcome: string, report?: string, late?: boolean } }}
+ */
+export function buildSettleSchemePatch(details) {
+	const parts = [details.outcome];
+	if (details.probeApi) parts.push(`via ${details.probeApi}`);
+	if (details.report) parts.push(details.report);
+	if (details.late) parts.push("late");
+	const patch = {
+		source: "attach",
+		level: SETTLE_SCHEME_WARN_OUTCOMES.has(details.outcome) ? "warn" : "info",
+		code: "attach_settle_scheme",
+		message: `attach settle scheme: ${parts.join(" ")}`,
+		details: { outcome: details.outcome },
+	};
+	if (details.probeApi !== undefined) patch.details.probeApi = details.probeApi;
+	if (details.report !== undefined) patch.details.report = details.report;
+	if (details.late !== undefined) patch.details.late = details.late;
+	return patch;
+}