@zhuxixi/pi-agent-board 0.4.1 → 0.4.2

package/README.md

@@ -86,6 +86,7 @@ Useful environment variables:
 | `AGENT_BOARD_TITLE_MODEL=<model>` | Model for generated session titles. Defaults to `openai-codex/gpt-5.5`; use `off` to disable. |
 | `AGENT_BOARD_TITLE_THINKING_LEVEL=<level>` | Thinking level for title generation. Defaults to `low`; use `off` to omit it. |
 | `AGENT_BOARD_DISABLE_PTY=1` | Disable PTY attach mode. |
+| `AGENT_BOARD_IME_FIX=0` | Disable the IME cursor-rect coalescer (issue #28). The coalescer folds pi-tui's per-frame cursor-park writes into the frame's synchronized-output block so terminals report one stable IME cursor position per frame instead of two (candidate-window flicker in busy sessions). |
 | `AGENT_BOARD_FORCE_PTY=1` | Force PTY attach mode. |
 | `AGENT_BOARD_ATTACH_MOUSE=0` | Disable attach-view mouse handling and use terminal-native selection. |
 | `AGENT_BOARD_WHEEL_LINES=<1-50>` | Lines scrolled per mouse-wheel event in attach view. Defaults to `1`. |

package/docs/superpowers/plans/2026-08-22-jiggle-shrink-and-hold.md

@@ -0,0 +1,337 @@
+# Jiggle shrink-and-hold 协议改造 Implementation Plan（issue #25）
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 把 attach 的 jiggle 从"±1 脉冲对"改成"shrink-and-hold"协议——缩住直到见到全清，冷启动自愈 ≤3s，同时以 G1-G5 守卫保证不破坏任何现有功能。
+
+**Architecture:** 协议主体在 `pty-attach-jiggle-controller.mjs`（armed→held→restored 状态 + G1/G2 计时）；`pty-attach-jiggle-retry.mjs` 状态机不动（退避表仅作 G2 计时）；`pty-attach.ts` 替换 forceChildRedraw 胶水并接入 G3/G4/G5；E2E stub 改 hold 语义并新增 shell 兜底用例。
+
+**Tech Stack:** Node 24（node:test）、TypeScript（tsc --noEmit）、node-pty、@xterm/headless。
+
+## Global Constraints
+
+- 工作目录：`/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-25-jiggle-shrink-and-hold`（**禁碰主 checkout**）。
+- hold 尺寸 = (cols−1)×(rows−1)；restore = 原始尺寸；restore **幂等（只发一次）**。
+- G1 = start 后 6s 无 `\x1b[?2026h` → restore；G2 = 退避表走完（56.12s）无全清 → restore。
+- re-arm（首个 TUI 帧）→ **restore 原尺寸且不重排链**（无脉冲）。
+- G3：close 时 `restoreAndStop()`；G5：`start()` 前若 held 先 restore；G4：`notifyExternalResize(c,r)` 取消 hold/计时器并把 (c,r) 记为新原尺寸。
+- 删除 `JIGGLE_RESTORE_MS`（无脉冲对）。
+- 代码风格：tab 缩进、双引号、JSDoc、core 模块 .mjs；commit 用 conventional commits；`git add` 按文件。
+- Spec：`docs/superpowers/specs/2026-08-22-jiggle-shrink-and-hold-design.md`（已提交 b9b3aab）。
+
+---
+
+### Task 1: 控制器协议改造（hold 状态机 + G1/G2/G3/G4/G5）
+
+**Files:**
+- Modify: `src/core/pty-attach-jiggle-controller.mjs`
+- Test: `test/pty-attach-jiggle-controller.test.mjs`
+
+**Interfaces:**
+- Consumes: `pty-attach-jiggle-retry.mjs` 的 `createJiggleRetryState/nextRetryDelay/advanceRetry/stopRetry` 与 `feedOutput`（含 frameStartFound/clearFound）——**全部原样使用，不改**。
+- Produces（Task 2/3 依赖）:
+  - deps: `{ sendResize(cols, rows), setTimeoutFn, clearTimeoutFn }`（`sendJiggle`/`shouldFire` **删除**）
+  - 返回 `{ start(cols, rows), feed(data), restoreAndStop(), notifyExternalResize(cols, rows), getState() }`
+  - `getState()` → `{ held, clearDetected, stopped, tuiFrameSeen, originalCols, originalRows }`（retryIndex 可保留内部）
+
+**行为规格（精确）：**
+
+```js
+start(cols, rows):
+  1. 清全部计时器；若 held → sendResize(prevOriginalCols, prevOriginalRows)（G5，幂等标记复位）
+  2. originalCols/Rows = (cols, rows)
+  3. sendResize(cols, rows); sendResize(cols-1, rows-1); held = true; restored = false
+  4. tuiFrameSeen = false; clearDetected = false; stopped = false; state = createJiggleRetryState()
+  5. G1 计时器 = 6s：fire 时若 !tuiFrameSeen → restoreIfHeld()
+  6. 预算链照常排（nextRetryDelay/advanceRetry 循环），但回调 fire 时 **no-op**（不发脉冲、不 sendResize；仅推进计数）；delay 走完（null）→ stopRetry + restoreIfHeld()（G2）
+
+feed(data):
+  1. 若 clearDetected → return（沿用）
+  2. feedOutput 扫描（沿用）
+  3. clearFound → restoreIfHeld(); 停链（stopRetry+clearTimer）; clearDetected=true; 取消 G1
+  4. frameStartFound 且 !tuiFrameSeen → tuiFrameSeen=true; 取消 G1; **restoreIfHeld()**; 不重排链、不碰预算
+
+restoreIfHeld(): if (held && !restored) { sendResize(originalCols, originalRows); restored = true; held = false; }
+
+restoreAndStop(): 清全部计时器; restoreIfHeld(); state = stopRetry(state)
+
+notifyExternalResize(cols, rows):
+  清全部计时器; held = false; restored = false（hold 作废，G4）
+  originalCols/Rows = (cols, rows)
+  state = stopRetry(state)（链终止；本次 attach 语义已让位于真实 resize）
+```
+
+- [ ] **Step 1: 重写单测**（全量替换 test/pty-attach-jiggle-controller.test.mjs，fake scheduler 记录 sendResize 调用序列）：
+
+```js
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createJiggleRetryController } from "../src/core/pty-attach-jiggle-controller.mjs";
+
+function fakeScheduler() {
+	const timers = new Map();
+	let nextId = 1;
+	return {
+		timers,
+		setTimeoutFn(fn, ms) {
+			const id = nextId++;
+			timers.set(id, { fn, ms });
+			return id;
+		},
+		clearTimeoutFn(id) { timers.delete(id); },
+		fire(id) { const t = timers.get(id); assert.ok(t, "no such timer"); timers.delete(id); t.fn(); },
+		fireNext() { const first = timers.entries().next().value; assert.ok(first, "no pending timer"); this.fire(first[0]); },
+		delays() { return [...timers.values()].map((t) => t.ms); },
+		findByDelay(ms) { for (const [id, t] of timers) if (t.ms === ms) return id; return null; },
+	};
+}
+
+function makeController() {
+	const scheduler = fakeScheduler();
+	const resizes = [];
+	const controller = createJiggleRetryController({
+		sendResize: (c, r) => resizes.push([c, r]),
+		setTimeoutFn: scheduler.setTimeoutFn,
+		clearTimeoutFn: scheduler.clearTimeoutFn,
+	});
+	return { controller, scheduler, resizes };
+}
+
+test("start() arms hold: sends original then shrunk size, holds", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	assert.deepEqual(resizes, [[170, 36], [169, 35]]);
+	assert.equal(controller.getState().held, true);
+	assert.notEqual(scheduler.findByDelay(6000), null, "G1 timer armed"); // 6000 in delays
+	assert.ok(scheduler.delays().includes(6000), "G1 timer present");
+});
+
+test("feed with clear restores original size exactly once and stops", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	controller.feed("x\x1b[2J\x1b[Hy");
+	assert.deepEqual(resizes.slice(-1), [[170, 36]]);
+	assert.equal(controller.getState().clearDetected, true);
+	assert.equal(controller.getState().stopped, true);
+	assert.equal(controller.getState().held, false);
+	// 幂等：后续 feed 不再发
+	controller.feed("more\x1b[2J");
+	assert.equal(resizes.filter(([c]) => c === 170).length, 2); // start 的 + restore 的，无第三发
+});
+
+test("re-arm (first TUI frame) restores size and does NOT reschedule chain", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	const budgetBefore = scheduler.delays().length;
+	controller.feed("\x1b[?2026h first frame");
+	assert.deepEqual(resizes.slice(-1), [[170, 36]]);
+	assert.equal(controller.getState().tuiFrameSeen, true);
+	assert.equal(scheduler.delays().length, budgetBefore, "no new timers scheduled");
+	// G1 已取消
+	assert.equal(scheduler.findByDelay(6000), null);
+});
+
+test("G1: no TUI frame within 6s restores original size", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	const g1 = scheduler.findByDelay(6000);
+	assert.ok(g1);
+	scheduler.fire(g1);
+	assert.deepEqual(resizes.slice(-1), [[170, 36]]);
+	assert.equal(controller.getState().held, false);
+});
+
+test("G1 cancelled once a frame arrives (no double restore)", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	controller.feed("\x1b[?2026h frame");
+	const g1 = scheduler.findByDelay(6000);
+	assert.equal(g1, null);
+});
+
+test("G2: backoff budget exhausted without clear restores original size", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	controller.feed("\x1b[?2026h frame"); // re-arm restores, cancels G1
+	const before = resizes.length;
+	// 排干全部退避计时器（无脉冲 fire 均为推进）
+	for (let i = 0; i < 8; i++) scheduler.fireNext();
+	assert.equal(controller.getState().stopped, true);
+	// hold 已在 re-arm 时恢复，G2 无需再发（幂等）
+	assert.equal(resizes.length, before);
+});
+
+test("G2 without any frame: budget exhausted restores", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	const g1 = scheduler.findByDelay(6000);
+	scheduler.fireNext(); // 第一个退避计时器（120ms）推进，no-op
+	for (let i = 0; i < 7; i++) scheduler.fireNext();
+	assert.equal(controller.getState().stopped, true);
+	assert.deepEqual(resizes.slice(-1), [[170, 36]], "G2 restore fired");
+});
+
+test("restoreAndStop() restores then stops (G3)", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	controller.restoreAndStop();
+	assert.deepEqual(resizes.slice(-1), [[170, 36]]);
+	assert.equal(controller.getState().stopped, true);
+	assert.equal(scheduler.timers.size, 0);
+});
+
+test("start() after a held start restores previous hold first (G5)", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	controller.start(196, 39); // 新连接
+	assert.deepEqual(resizes.slice(0, 4), [[170, 36], [169, 35], [170, 36], [196, 39]]);
+	assert.deepEqual(resizes.slice(-1), [[195, 38]]);
+});
+
+test("notifyExternalResize cancels hold, adopts new size, stops chain (G4)", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	resizes.length = 0;
+	controller.notifyExternalResize(200, 50);
+	assert.equal(scheduler.timers.size, 0, "all timers cleared");
+	assert.equal(controller.getState().held, false);
+	assert.equal(controller.getState().stopped, true);
+	assert.equal(controller.getState().originalCols, 200);
+	// 再 feed clear 不再触发任何 restore
+	controller.feed("\x1b[2J");
+	assert.equal(resizes.length, 0);
+});
+
+test("full G1 window passes while frames keep arriving → held restored by G2 only", () => {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	controller.feed("\x1b[?2026h frame"); // restores once
+	const before = resizes.length;
+	// 无全清的持续输出
+	for (let i = 0; i < 8; i++) scheduler.fireNext();
+	assert.equal(resizes.length, before, "no extra resizes");
+	assert.equal(controller.getState().stopped, true);
+});
+```
+
+- [ ] **Step 2: 跑测试确认失败**（接口不匹配即失败）
+  Run: `node --test test/pty-attach-jiggle-controller.test.mjs` → FAIL
+
+- [ ] **Step 3: 实现控制器改造**（按上方行为规格重写 `src/core/pty-attach-jiggle-controller.mjs`；保留模块头注释并更新为 hold 协议描述；G1 常量 `NO_FRAME_RESTORE_MS = 6000`）
+
+- [ ] **Step 4: 跑测试确认通过** → PASS（此时 pty-attach.ts 尚未接线，typecheck 可能因 deps 变化报错——本任务只保证控制器单测绿；组件接线在 Task 2）
+
+- [ ] **Step 5: Commit**
+```bash
+git add src/core/pty-attach-jiggle-controller.mjs test/pty-attach-jiggle-controller.test.mjs
+git commit -m "feat: shrink-and-hold jiggle protocol with G1-G5 guards (issue #25)"
+```
+
+---
+
+### Task 2: 组件接线（forceChildRedraw → start；G3/G4/G5 接入）
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts`
+
+**Interfaces:**
+- Consumes: Task 1 的 `{ start(cols, rows), feed, restoreAndStop, notifyExternalResize, getState }`；deps `{ sendResize, setTimeoutFn, clearTimeoutFn }`。
+
+**精确改动：**
+1. 控制器字段初始化改为：
+```ts
+	private readonly jiggleRetry = createJiggleRetryController({
+		sendResize: (cols, rows) => this.sendResize(cols, rows),
+		setTimeoutFn: (fn, ms) => {
+			const t = setTimeout(fn, ms);
+			t.unref?.();
+			return t;
+		},
+		clearTimeoutFn: (t) => clearTimeout(t as ReturnType<typeof setTimeout>),
+	});
+```
+2. connect 处理器：删除 `this.forceChildRedraw()` 与其前独立 `this.sendResize()`（协议已在 start 内含 sendResize 原尺寸）；改为 `this.jiggleRetry.start(this.cols, this.rows);`
+3. `forceChildRedraw()` 方法整个删除；`JIGGLE_RESTORE_MS` 常量及其注释删除；`clearRedrawTimer()` 若仅被 forceChildRedraw/close 使用则一并删除（先 grep 确认无他引用；close() 中 `this.clearRedrawTimer()` 调用改为无操作或删除该行）。
+4. `resizeIfNeeded`：在 `this.term.resize(...)` 前插入 `this.jiggleRetry.notifyExternalResize(size.cols, size.rows);`（G4）——注意它必须在确认尺寸真的变化后调用（函数内 size 更新之后、sendResize 之前）。
+5. `close()`：`this.jiggleRetry.stop()` 改为 `this.jiggleRetry.restoreAndStop()`（G3）。
+6. `checkClearSequence` → `this.jiggleRetry.feed(data)` 不变。
+
+- [ ] **Step 1: 应用上述 6 处改动**
+- [ ] **Step 2: 验证**
+  Run: `npm run typecheck`（必须干净）；`node --test test/*.test.mjs`（除 E2E 外全绿；E2E 在 Task 3 重写）
+- [ ] **Step 3: Commit**
+```bash
+git add src/ui/pty-attach.ts
+git commit -m "feat: wire shrink-and-hold controller into attach component (issue #25)"
+```
+
+---
+
+### Task 3: E2E 重写（hold 语义）+ shell 兜底用例
+
+**Files:**
+- Modify: `test-support/fake-coldstart-tui-pi.mjs`
+- Test: `test/pty-attach-cold-start-e2e.test.mjs`（重写）
+
+**stub 新语义（精确）：**
+
+```js
+#!/usr/bin/env node
+// Fake cold-booting pi for the attach shrink-and-hold E2E (issue #25).
+// Boot noise first; after STUB_TUI_DELAY_MS "starts the TUI": installs the
+// resize listener and emits \x1b[?2026h-wrapped frames. Holds the protocol:
+// whenever the PTY size becomes (cols, rows) where cols/rows differ from the
+// size at TUI start (the hold's promised width delta), the running TUI
+// responds with a fullRender containing \x1b[2J — because pi-tui's
+// widthChanged path fires for ANY width change from its baseline.
+const delay = Number(process.env.STUB_TUI_DELAY_MS ?? 8000);
+process.stdout.write("boot: loading extensions...\n");
+let started = false;
+let baseline = null;
+function startTui() {
+	if (started) return;
+	started = true;
+	process.stdout.on("resize", () => {
+		const c = process.stdout.columns;
+		const r = process.stdout.rows;
+		if (baseline === null) baseline = [c, r]; // 首个见到的尺寸=基线
+		if (c === baseline[0] && r === baseline[1]) return; // 无变化不全清
+		baseline = [c, r]; // 全清后新基线
+		process.stdout.write(
+			`\x1b[?2026h\x1b[2J\x1b[H\x1b[3Jframe@${c}x${r}\x1b[?2026l`,
+		);
+	});
+	process.stdout.write("\x1b[?2004h\x1b[?25l");
+	frame();
+}
+function frame() { process.stdout.write("\x1b[?2026hstub: working...\x1b[?2026l"); }
+setTimeout(startTui, delay);
+setInterval(() => { if (started) frame(); }, 100);
+process.on("SIGTERM", () => process.exit(0));
+process.on("SIGINT", () => process.exit(0));
+```
+
+**E2E 用例 1（冷启动 ≤3s 自愈 + 终态原尺寸）**：runner + stub（delay 8000）+ 真控制器。connect 时仅 `controller.start(196, 39)`（不再手动 sendResize/jiggle——协议在 start 内）。喂全部 output 给 feed。断言：
+- 首个 `\x1b[2J` 到达时刻 − 首帧（tuiFrameSeen 翻转）时刻 ≤ **3000ms**（frameAt/clearAt 都取自 controller.getState() 翻转的采样点，沿用 #10 的采样法）
+- `getState().held === false` 且收到过 resize(196,39)（终态原尺寸；从 runner 侧回读 host.json cols/rows == 196/39 亦可作证）
+
+**E2E 用例 2（shell 型子进程 G1 兜底）**：piArgsPrefix 指向 `test-support/fake-pty-pi.mjs`（既有，无 2026h、无 resize 响应）。connect 后 `controller.start(120, 36)`；喂 output；**手动 fire G1**不可行（真计时器）——改为等真 6s：断言 8s 内收到 sendResize(120, 36)（G1 restore）。测试时长 ~8s 可接受。
+
+**E2E 用例 3（可选，若前两个已覆盖 G4 则略）**：略——G4 由单测覆盖，不在 E2E 层重复。
+
+- [ ] **Step 1: 重写 stub 与 E2E**（保留 node-pty skip 守卫、freshRoot/waitFor/send 约定）
+- [ ] **Step 2: 跑 E2E**
+  Run: `node --test test/pty-attach-cold-start-e2e.test.mjs` → 两用例 PASS（用例 1 ~10-12s；用例 2 ~8s）
+- [ ] **Step 3: Commit**
+```bash
+git add test-support/fake-coldstart-tui-pi.mjs test/pty-attach-cold-start-e2e.test.mjs
+git commit -m "test: hold-protocol E2E cold-start and shell-fallback cases (issue #25)"
+```
+
+---
+
+### Task 4: 全量验证 + spec 对照
+
+- [ ] **Step 1**: `npm run typecheck` 干净；`npm test` 全绿（含新 E2E）
+- [ ] **Step 2**: 对照 spec 验收 1/2/3/4：E2E ≤3s ✓；shell G1 兜底 ✓；8 风险面守卫测试映射清单（写进 commit 后的验证评论）✓
+- [ ] **Step 3**: `git status --short` 空；`git log --oneline main..HEAD` = 5 commits（spec+plan+3 任务）

package/docs/superpowers/specs/2026-08-22-jiggle-shrink-and-hold-design.md

@@ -0,0 +1,107 @@
+# Spec：attach jiggle 协议改造 — shrink-and-hold（issue #25）
+
+## 日期
+2026-08-22
+
+## 问题
+
+#10 修复后冷启动 attach 自愈延迟 10-25s（re-arm 生效但后续 ±1/200ms 脉冲对被启动风暴合并成净零尺寸变化，子端渲染时看不到宽度变化 → 不触发 fullRender 全清）。目标：冷启动 ≤3s 自愈，热 attach ≤300ms 不劣化，且不破坏任何现有功能。
+
+## 协议设计（核心状态机）
+
+**旧协议**：connect → shrink(−1) → [200ms] → restore → 每次重试重复脉冲对 → 见全清停。
+**新协议**：
+
+```
+connect:
+  1. sendResize(W×H)              # 原始尺寸（保持现有语义）
+  2. shrink 到 (W−1)×(H−1) 并 HOLD # "armed"：与子端基线之间存在待兑现的宽度差
+  3. 启动安全计时器（见"守卫 G1/G2"）
+
+子端输出处理（沿用 feed）:
+  - 见 \x1b[2J（全清）→ restore(W×H)，链停        # 子端渲染时读到窄宽 → fullRender → 我们恢复
+  - 见首个 \x1b[?2026h（re-arm）→ restore(W×H) 并停在那里
+      # 冷启动死锁解法：TUI 若在 shrink 后才启动，首帧把窄宽当基线；
+      # restore 让"正在渲染的子端"下一帧看到宽 1 列 → 必然 fullRender → 走上面的全清分支
+
+守卫:
+  G1 无帧兜底: connect 后 6s 内无任何 TUI 帧 → restore(W×H)（没有渲染器可触发，继续缩无意义）
+  G2 预算兜底: 全部退避预算（56.12s）走完无全清 → restore(W×H)（非 pi 子进程/死 session）
+  G3 close/detach: close() 时若 hold 生效 → 先 restore 再断（socket 尚可用）
+  G4 真实 resize: resizeIfNeeded(新宽) 进入时若 hold 生效 → 取消 hold 状态、按新尺寸 sendResize、
+     之后由下一次 attach 语义重启链（hold 的"原尺寸"取新值）
+  G5 reconnect: start() 重置前若 hold 生效 → 先 restore（socket 刚连上）
+```
+
+**为什么合并不再重要**：旧协议的净零来自"缩"与"恢复"互相抵消；新协议在见到全清前根本不存在"恢复"，任何一侧（外层 timer / 子端 SIGWINCH / 渲染节流）的合并最多推迟信号到达，不能消除"宽度与基线不同"这个事实。子端只要渲染任何一帧，全清必然发生。
+
+## 模块改动
+
+### 1. `src/core/pty-attach-jiggle-retry.mjs`（纯逻辑，微调）
+- 不变：退避表、`hasTuiFrameStart`/`hasFullClearSequence`、carry=7。
+- `JiggleRetryState` 增加 `held: boolean`（是否正缩着）与 `originalCols/originalRows`。由控制器维护，状态机保持零副作用。
+
+### 2. `src/core/pty-attach-jiggle-controller.mjs`（协议主体）
+- deps 增加：`sendResize(cols, rows)`（发送任意尺寸；sendJiggle 语义被 hold 协议取代，删除或保留为内部组合）。
+- `start()`：若前次 hold 生效 → 先 `sendResize(original)`（G5）；随后 `sendResize(W,H)`、`sendResize(W−1,H−1)` 置 `held=true`（armed）；启动 G1 计时器；预算链照常排（作 G2 计时用，重试回调在 hold 下为 no-op——不发脉冲）。
+- `feed()`：见全清 → `restoreIfHeld()` + 停链 + 置 clearDetected；见首帧（re-arm）→ `restoreIfHeld()`（G-rearm），**预算链不重置不重排**（hold 协议下 re-arm 后无需再脉冲；若全清一直不来，由 G1/G2 兜底）。G1 计时器见帧后取消。
+- `stop()`：restoreIfHeld 不在此做（组件 close 语义不同——见 G3，由组件在 socket 可用时显式调用 `restoreAndStop()`）。
+- 新增 API：`restoreAndStop()`（G3）、`notifyExternalResize(cols, rows)`（G4：取消 hold/计时器、更新 original、可选重启链）。
+- 计时器仍全部走注入的 setTimeoutFn/clearTimeoutFn，unref。
+
+### 3. `src/ui/pty-attach.ts`（薄胶水）
+- `forceChildRedraw` 语义替换：connect 处理器改调 `jiggleRetry.start()`（内含 armed shrink）；`JIGGLE_RESTORE_MS` 删除（无脉冲）。
+- `resizeIfNeeded`：尺寸变化时调 `jiggleRetry.notifyExternalResize(newCols, newRows)`，再照常 `term.resize + sendResize`。
+- `close()`：`jiggleRetry.restoreAndStop()`。
+- `checkClearSequence` → `jiggleRetry.feed(data)` 不变。
+
+### 4. 测试
+- 单测（controller）：armed 后见全清→restore+停；见首帧→restore 且不重排；G1 6s 无帧 restore；G2 预算耗尽 restore；close restoreAndStop；notifyExternalResize 取消 hold 并更新原尺寸；重复 start 先 restore 旧 hold；所有 restore 只发一次（幂等）。
+- E2E 重写（stub 语义改为 hold 协议）：
+  - 冷启动：stub 延迟 8s 启动 TUI；收到 shrink 不动作；**收到 restore(原尺寸) 且 TUI 已启动** → 发全清。断言全清 ≤3s 内到达（re-arm 后 ~一帧间隔），且 PTY 终态=原尺寸。
+  - shell 型子进程（永不发全清）：断言 G1 兜底 6s 后收到 restore(原尺寸)。
+  - （可选）hold 中途外部 resize：模拟 notifyExternalResize，断言不发旧尺寸。
+- 既有 208 测试适配（controller 单测大改、retry 状态机测试微调）。
+
+## 决策表
+
+| 决策点 | 选择 | 理由 |
+|---|---|---|
+| hold 的宽度 | cols−1 且 rows−1 | 沿用现有 jiggle 尺寸语义；宽高都变确保 heightChanged 路径也可触发 |
+| re-arm 后行为 | 只 restore，不再脉冲 | 子端已在渲染，restore 即待兑现差值；脉冲回归旧脆弱性 |
+| G1 时长 | 6s | > 最慢正常 boot 出首帧（实测 ~5.2s）+ 余量；< G2 预算 |
+| G2 | 退避表走完（56.12s） | 与 #10 验收窗口一致；hold 下重试回调 no-op，表仅作计时 |
+| restore 幂等 | 只发一次 | 防止 close/reconnect/兜底叠加多发 |
+| `JIGGLE_RESTORE_MS` | 删除 | 无脉冲对 |
+
+## 风险面 → 守卫映射（用户重点确认区）
+
+| # | 风险面 | 守卫 | 验证 |
+|---|---|---|---|
+| R1 | 非 pi 子进程/死 session | G1(6s)+G2(56s) restore | E2E shell stub |
+| R2 | detach/close 中途 | G3 close 先 restore | 单测 |
+| R3 | 真实 resize 打架 | G4 中断+取新值 | 单测 |
+| R4 | 子端窄 1 列渲染 | 瞬态，restore 全清重绘 | 人工+E2E 终态尺寸断言 |
+| R5 | 本地投影 1 列差 | 流内自洽，无影响 | 人工 |
+| R6 | reconnect 残留 | G5 start 先 restore | 单测 |
+| R7 | settle 后 UX | 无脉冲（频次低于现状） | 人工 |
+| R8 | 测试有效性 | stub 改 hold 语义+兜底用例 | E2E |
+
+## 降级
+
+- 若 pi-tui 改掉 `\x1b[?2026h`：re-arm 不触发，退化为 G1(6s) restore——**比 #10 修复前更好**（6s 内恢复正确尺寸，画面可能仍脏但不卡窄宽）。
+- 若全清信号消失：同上走 G1/G2，终态尺寸正确。
+
+## 非目标
+
+- 失同步渲染检测（#11 范围，若 hold 后仍有可见脏窗再评估）。
+- runner / pi-tui 侧改动。
+- screen.log 重放锚点问题。
+
+## 验收标准
+
+1. 冷启动 E2E：全清 ≤3s 到达且终态=原尺寸（旧协议同场景 >10s，反证有效）。
+2. shell stub E2E：G1 兜底 6s 后 restore 原尺寸。
+3. 8 个风险面守卫全部有单测/E2E 覆盖。
+4. 全套测试通过、typecheck 干净、CR 收敛。
+5. 人工实机：home 目录冷启动 attach ≤3s 自愈；热 attach 无可感知劣化。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuxixi/pi-agent-board",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Agent-board dashboard for Pi: dispatch, monitor, peek/reply, and attach to background Pi sessions.",
   "type": "module",
   "main": "./index.ts",

package/src/core/ime-cursor-coalesce.mjs

@@ -0,0 +1,193 @@
+/**
+ * IME cursor-rect flicker fix (issue #28).
+ *
+ * pi-tui's doRender() emits each frame as separate terminal.write() calls:
+ *
+ *   1. ESC[?2026h ...content... ESC[?2026l   (differential/full frame, sync block)
+ *   2. ESC[<n>A/B ESC[<col>G                  (positionHardwareCursor park write)
+ *   3. ESC[?25l                               (hideCursor - bypasses write())
+ *
+ * The park sequences sit OUTSIDE the synchronized-output block. Terminals that
+ * honor ?2026 (WezTerm et al.) present a frame and report the IME cursor
+ * rectangle at each ?2026l boundary, so every frame produces two cursor-rect
+ * reports at different positions (diff-write end vs parked input line) and the
+ * IME candidate window bounces at frame rate. E2E measured on WezTerm + fcitx5:
+ * ~20 position changes / 4s with the split writes, 0 with the park inside the
+ * block (see issue #28 for the full experiment).
+ *
+ * This module wraps a Terminal instance's write/hideCursor/showCursor at runtime
+ * and folds the out-of-block park/hide sequences back INSIDE the frame's sync
+ * block, re-emitting the frame as a single write. Content is byte-identical up
+ * to reordering of the trailing ?2026l; nothing is dropped or added.
+ *
+ * Safety properties (issue #28):
+ * - No match -> passthrough: any write that isn't a pure cursor-park/hide
+ *   sequence flushes the held frame unchanged first, preserving byte order.
+ * - The three writes happen inside one synchronous doRender() stack, so a
+ *   process.nextTick flush is enough to see them all; the added latency is
+ *   sub-millisecond.
+ * - Uninstall restores the original methods; a WeakMap makes overlapping
+ *   installs on the same terminal refcounted and idempotent.
+ * - Kill switch: AGENT_BOARD_IME_FIX=0 disables installation entirely.
+ *
+ * If pi-tui ever folds positionHardwareCursor into the sync block upstream,
+ * the "pure park sequence following a sync-end write" pattern stops matching
+ * and this wrapper degrades to a passthrough (one buffered write per frame,
+ * same bytes) - no behavior change.
+ */
+
+const ESC = String.fromCharCode(27);
+/** ESC[?2026l - end of a synchronized-output block. */
+const SYNC_END = ESC + "[?2026l";
+
+/**
+ * Cursor sequences positionHardwareCursor() emits after a frame: relative row
+ * moves (ESC[<n>A / ESC[<n>B, n optional) and an absolute column set
+ * (ESC[<col>G), plus the cursor visibility toggles (ESC[?25l/h). These are
+ * the ONLY sequences safe to fold into the block - anything else (line clears,
+ * absolute positioning, OSC/DCS queries, content) flushes the held frame.
+ */
+const PARK_SEQUENCE = new RegExp(
+	"^(?:" + ESC + "\\[\\d*[AB]|" + ESC + "\\[\\d+G|" + ESC + "\\[\\?25[hl])*$",
+);
+
+/** True when a write ends a synchronized-output block (pi-tui frame writes do). */
+export function endsWithSyncEnd(data) {
+	return typeof data === "string" && data.endsWith(SYNC_END);
+}
+
+/** True when data is exclusively cursor park/visibility sequences (see above). */
+export function isPureCursorParking(data) {
+	return typeof data === "string" && data.length > 0 && PARK_SEQUENCE.test(data);
+}
+
+/** Insert seq just before the trailing SYNC_END of a held frame write. */
+export function mergeIntoSyncBlock(held, seq) {
+	return held.slice(0, held.length - SYNC_END.length) + seq + SYNC_END;
+}
+
+/** terminal -> active wrapper, so overlapping installs share one wrapper. */
+const activeWrappers = new WeakMap();
+
+/**
+ * Each wrapTerminalWrites() call returns its own guarded handle: idempotent
+ * per handle, refcounted across handles — the patch is torn down only when
+ * the LAST caller uninstalls (CR round 1, issue-1).
+ */
+function refcountedUninstall(entry) {
+	let done = false;
+	return () => {
+		if (done) return;
+		done = true;
+		entry.refs -= 1;
+		if (entry.refs > 0) return;
+		entry.teardown();
+	};
+}
+
+/**
+ * Patch write/hideCursor/showCursor on a terminal instance so each frame's
+ * out-of-block park/hide sequences are folded into the frame's sync block and
+ * emitted as one write. Returns an uninstall function (idempotent, drops the
+ * patch when the last caller uninstalls).
+ */
+export function wrapTerminalWrites(terminal) {
+	if (!terminal || typeof terminal.write !== "function" || typeof terminal.hideCursor !== "function" || typeof terminal.showCursor !== "function") {
+		throw new Error("terminal must expose write/hideCursor/showCursor");
+	}
+	const existing = activeWrappers.get(terminal);
+	if (existing) {
+		existing.refs += 1;
+		return refcountedUninstall(existing);
+	}
+
+	const original = {
+		write: terminal.write.bind(terminal),
+		hideCursor: terminal.hideCursor.bind(terminal),
+		showCursor: terminal.showCursor.bind(terminal),
+	};
+	/** Frame write ending in SYNC_END, accumulating park/hide merges. */
+	let held = null;
+	let flushScheduled = false;
+
+	const flush = () => {
+		if (held === null) return;
+		const out = held;
+		held = null;
+		original.write(out);
+	};
+
+	const scheduleFlush = () => {
+		if (flushScheduled) return;
+		flushScheduled = true;
+		process.nextTick(() => {
+			flushScheduled = false;
+			flush();
+		});
+	};
+
+	/** Fold a park/hide seq into the held frame, or emit it standalone. */
+	const mergeOrEmit = (seq, directEmit) => {
+		if (held !== null) {
+			held = mergeIntoSyncBlock(held, seq);
+			return;
+		}
+		directEmit();
+	};
+
+	terminal.write = (data) => {
+		if (typeof data !== "string" || data.length === 0) {
+			flush();
+			original.write(data);
+			return;
+		}
+		if (held !== null) {
+			// Only a pure park/hide burst may join the held frame; anything
+			// else means this isn't a doRender park tail - flush unchanged.
+			if (isPureCursorParking(data)) {
+				held = mergeIntoSyncBlock(held, data);
+				return;
+			}
+			flush();
+		}
+		if (endsWithSyncEnd(data)) {
+			held = data;
+			scheduleFlush();
+			return;
+		}
+		original.write(data);
+	};
+
+	terminal.hideCursor = () => mergeOrEmit(ESC + "[?25l", original.hideCursor);
+	terminal.showCursor = () => mergeOrEmit(ESC + "[?25h", original.showCursor);
+
+	const entry = { refs: 1, teardown: null };
+	entry.teardown = () => {
+		flush();
+		terminal.write = original.write;
+		terminal.hideCursor = original.hideCursor;
+		terminal.showCursor = original.showCursor;
+		activeWrappers.delete(terminal);
+	};
+
+	activeWrappers.set(terminal, entry);
+	return refcountedUninstall(entry);
+}
+
+/**
+ * Install the coalescer on a TUI's terminal. Never throws: on any surprise
+ * (shape change upstream, kill switch) it returns null and behavior stays
+ * exactly as today.
+ */
+export function installImeCursorCoalesce(tui) {
+	if (process.env.AGENT_BOARD_IME_FIX === "0") return null;
+	try {
+		const terminal = tui && tui.terminal;
+		if (!terminal || typeof terminal.write !== "function" || typeof terminal.hideCursor !== "function" || typeof terminal.showCursor !== "function") {
+			return null;
+		}
+		return wrapTerminalWrites(terminal);
+	} catch {
+		return null;
+	}
+}

package/src/core/pty-attach-jiggle-controller.mjs

@@ -1,17 +1,35 @@
 /**
- * Injectable orchestration for the attach jiggle-retry chain.
+ * Injectable orchestration for the attach shrink-and-hold jiggle protocol.
  *
- * Owns the retry state machine, backoff timers, cross-chunk scanning, and the
- * one-shot re-arm on the child TUI's first frame (\x1b[?2026h). The attach
- * component (and the cold-start E2E) drive it through injected callbacks, so
- * the whole choreography is testable without a TUI or socket.
+ * Replaces the pulse-pair jiggle (shrink → 200ms → restore) with a
+ * shrink-and-hold protocol: on connect we resize the child PTY down one
+ * column/row and KEEP it there until the child's own rendering proves it
+ * observed the width change (a full clear, \x1b[2J, which pi-tui emits from
+ * fullRender(true) whenever widthChanged fires). Because there is no
+ * "restore" that can cancel the shrink before a clear is seen, event-loop
+ * coalescing on either side (outer dashboard timers or the child's
+ * SIGWINCH/render throttle) can no longer collapse a jiggle into a
+ * net-zero size change.
  *
- * Cold-start design (issue #10): the chain starts at socket connect, but a cold
- * child pi-tui installs its SIGWINCH listener only ~5s in — every early jiggle
- * is lost. When the first TUI frame arrives we re-arm once with a fresh budget,
- * so the next jiggle lands on a live TUI and its fullRender emits \x1b[2J,
- * which stops the chain. If pi-tui ever drops the 2026h sequence, this degrades
- * to the plain connect-time chain (still better than the old one-shot).
+ * Cold-start (issue #25): if the child TUI starts rendering AFTER we shrink,
+ * its first frame baselines at the shrunk size and never clears. The
+ * re-arm — the first \x1b[?2026h frame — therefore restores the original
+ * size: the now-rendering child sees a width different from its baseline
+ * and fullRenders. Guards:
+ *   G1 NO_FRAME_RESTORE_MS — no TUI frame within 6s → restore (no renderer
+ *      to trigger; continuing to hold has no purpose). If the TUI boots even
+ *      later, its first frame re-arms a fresh hold (F1 slow-boot probe), so
+ *      healing still fires the moment the child actually starts rendering.
+ *   G2 backoff budget exhausted without a clear → restore (non-pi children,
+ *      dead sessions).
+ *   G3 restoreAndStop() — component close/detach restores while the socket
+ *      is still usable.
+ *   G4 notifyExternalResize() — a real user resize cancels the hold and
+ *      adopts the new size.
+ *   G5 start() restores any previous hold before arming a new one (reconnect).
+ *
+ * If pi-tui ever drops the 2026h sequence, re-arm degrades to G1: the PTY
+ * is restored within 6s — still better than the pre-#10 behavior.
  */
 import {
 	advanceRetry,
@@ -21,92 +39,187 @@ import {
 	stopRetry,
 } from "./pty-attach-jiggle-retry.mjs";
 
+/** Restore the held (shrunk) child PTY when no TUI frame arrives this long. */
+const NO_FRAME_RESTORE_MS = 6000;
+
 /**
  * @typedef {Object} JiggleRetryControllerDeps
- * @property {() => void} sendJiggle - Fire one resize jiggle at the child.
+ * @property {(cols: number, rows: number) => void} sendResize - Resize the child PTY.
  * @property {(fn: () => void, ms: number) => unknown} setTimeoutFn - Timer factory.
  * @property {(timer: unknown) => void} clearTimeoutFn - Timer canceller.
- * @property {() => boolean} [shouldFire] - Guard on retry fire; false stops the chain without firing.
  */
 
 /**
  * @param {JiggleRetryControllerDeps} deps
  */
 export function createJiggleRetryController(deps) {
-	const { sendJiggle, setTimeoutFn, clearTimeoutFn, shouldFire } = deps;
+	const { sendResize, setTimeoutFn, clearTimeoutFn } = deps;
 	let state = createJiggleRetryState();
 	let carry = "";
 	let tuiFrameSeen = false;
+	/** True while the child PTY is parked at the shrunk size. */
+	let held = false;
+	/** True once the original size has been sent back (restore is one-shot). */
+	let restored = false;
+	/** @type {[number, number]} */
+	let originalCols = 0;
+	let originalRows = 0;
 	/** @type {unknown | null} */
-	let timer = null;
+	let chainTimer = null;
+	/** @type {unknown | null} */
+	let g1Timer = null;
+
+	function clearChainTimer() {
+		if (chainTimer === null) return;
+		clearTimeoutFn(chainTimer);
+		chainTimer = null;
+	}
+
+	function clearG1Timer() {
+		if (g1Timer === null) return;
+		clearTimeoutFn(g1Timer);
+		g1Timer = null;
+	}
 
-	function clearTimer() {
-		if (timer === null) return;
-		clearTimeoutFn(timer);
-		timer = null;
+	function clearAllTimers() {
+		clearChainTimer();
+		clearG1Timer();
 	}
 
-	function scheduleNext() {
+	/**
+	 * Restore the child PTY to the original size exactly once. No-op while
+	 * not held or after the restore already happened.
+	 */
+	function restoreIfHeld() {
+		if (!held || restored) return;
+		sendResize(originalCols, originalRows);
+		restored = true;
+		held = false;
+	}
+
+	/**
+	 * Backoff chain is a pure countdown under the hold protocol: firing a
+	 * retry schedules the next backoff (no pulse is sent — the shrink is
+	 * already held). When the budget runs out, G2 restores the size.
+	 */
+	function scheduleNextRetry() {
 		const delay = nextRetryDelay(state);
 		if (delay === null) {
 			state = stopRetry(state);
+			restoreIfHeld(); // G2
 			return;
 		}
-		timer = setTimeoutFn(() => {
-			timer = null;
-			if (shouldFire && !shouldFire()) {
-				state = stopRetry(state);
-				return;
-			}
-			sendJiggle();
+		chainTimer = setTimeoutFn(() => {
+			chainTimer = null;
 			state = advanceRetry(state);
-			scheduleNext();
+			scheduleNextRetry();
 		}, delay);
 	}
 
-	/** Reset everything (fresh connection) and schedule the first retry. */
-	function start() {
-		clearTimer();
+	function armG1() {
+		clearG1Timer();
+		g1Timer = setTimeoutFn(() => {
+			g1Timer = null;
+			if (!tuiFrameSeen) restoreIfHeld(); // G1
+		}, NO_FRAME_RESTORE_MS);
+	}
+
+	/**
+	 * Arm a fresh hold for a (re)connected attach at the given PTY size.
+	 * Restores any previous hold first (G5), then shrinks and holds.
+	 * @param {number} cols
+	 * @param {number} rows
+	 */
+	function start(cols, rows) {
+		clearAllTimers();
+		if (held) {
+			sendResize(originalCols, originalRows); // G5: unwind previous hold
+			restored = true;
+			held = false;
+		}
 		state = createJiggleRetryState();
 		carry = "";
 		tuiFrameSeen = false;
-		scheduleNext();
+		originalCols = cols;
+		originalRows = rows;
+		sendResize(cols, rows);
+		sendResize(cols - 1, rows - 1);
+		held = true;
+		restored = false;
+		armG1();
+		scheduleNextRetry();
 	}
 
 	/**
-	 * Feed one socket output chunk. Clear detection wins over re-arm when both
-	 * sequences appear in one chunk (a hot attach's first frame is often the
-	 * fullRender we were waiting for). Re-arm fires at most once per start().
+	 * Feed one socket output chunk. A clear wins over the re-arm when both
+	 * appear in one chunk. The first TUI frame restores the held size (the
+	 * child is now rendering and will fullRender on the width delta) and
+	 * does NOT reschedule the chain; if G1 already released the hold before
+	 * the TUI booted, the frame instead re-arms a fresh hold so the running
+	 * child still sees a width delta (F1 slow-boot probe).
 	 * @param {string} data
 	 */
 	function feed(data) {
 		if (state.clearDetected) return; // chain done; nothing left to detect
+		if (state.stopped) return; // chain ended (G2/G3/G4); output is inert
 		const result = feedOutput(state, data, carry);
 		state = result.state;
 		carry = result.carry;
 		if (result.clearFound) {
-			clearTimer();
+			clearAllTimers();
+			restoreIfHeld();
 			state = stopRetry({ ...state, clearDetected: true });
 			return;
 		}
-		if (result.frameStartFound && !tuiFrameSeen && !state.clearDetected) {
+		if (result.frameStartFound && !tuiFrameSeen) {
 			tuiFrameSeen = true;
-			clearTimer();
-			state = createJiggleRetryState();
-			scheduleNext();
+			clearG1Timer();
+			if (held) {
+				restoreIfHeld(); // fast path: child is rendering, width delta now lands
+			} else {
+				// Slow boot: G1 released the hold before the TUI came up, so the
+				// child baselined at the original size. Re-arm a fresh hold — its
+				// next frame then sees a width delta and fullRenders. Guards: the
+				// clear path (primary) and G2 budget exhaustion (chain still
+				// ticking). G1 is NOT re-armed: frames are now flowing.
+				sendResize(originalCols - 1, originalRows - 1);
+				held = true;
+				restored = false;
+			}
 		}
 	}
 
-	/** Stop the chain (component closed, etc.). */
-	function stop() {
-		clearTimer();
+	/**
+	 * Restore the held size (if any) and stop all chain activity. Used by the
+	 * component on close/detach while the socket is still usable (G3).
+	 */
+	function restoreAndStop() {
+		clearAllTimers();
+		restoreIfHeld();
+		state = stopRetry(state);
+	}
+
+	/**
+	 * A real user resize supersedes the hold protocol: cancel all timers,
+	 * mark the hold void, adopt the new size as the new original, and stop
+	 * the chain (G4).
+	 * @param {number} cols
+	 * @param {number} rows
+	 */
+	function notifyExternalResize(cols, rows) {
+		clearAllTimers();
+		held = false;
+		restored = false;
+		originalCols = cols;
+		originalRows = rows;
 		state = stopRetry(state);
 	}
 
 	return {
 		start,
 		feed,
-		stop,
-		getState: () => ({ ...state, tuiFrameSeen }),
+		restoreAndStop,
+		notifyExternalResize,
+		getState: () => ({ ...state, held, tuiFrameSeen, originalCols, originalRows }),
 	};
 }

package/src/ui/pty-attach.ts

@@ -8,6 +8,7 @@ import { CURSOR_MARKER, Key, matchesKey, truncateToWidth, visibleWidth } from "@
 import { isProbablyEmptyPiInputLine } from "../core/pty-input.mjs";
 import { findHttpUrlAtCells, findWordRangeAtCells } from "../core/pty-links.mjs";
 import { createAttachOutputRenderScheduler, nextAttachRender, projectPtyCursor, shouldScheduleAttachRenderForMessage } from "../core/pty-attach-render.mjs";
+import { installImeCursorCoalesce } from "../core/ime-cursor-coalesce.mjs";
 import { createJiggleRetryController } from "../core/pty-attach-jiggle-controller.mjs";
 import { clampInt, parseMouseInputChunk, resolveWheelLines, scrollViewportTop, selectionDragScrollLines } from "../core/pty-scroll.mjs";
 
@@ -47,11 +48,6 @@ const OSC52_MAX_BYTES = 1_000_000;
 const OSC52_CARRY_MAX_BYTES = OSC52_MAX_BYTES + 4096;
 const TERMINAL_PASSTHROUGH_MAX_BYTES = 5_000_000;
 const TERMINAL_PASSTHROUGH_CARRY_MAX_BYTES = TERMINAL_PASSTHROUGH_MAX_BYTES + 4096;
-/** Delay between the shrink and restore halves of a resize jiggle. 200ms keeps
- * the two SIGWINCHs apart well beyond pi-tui's 16ms render throttle, so a busy
- * (booting) child processes them as two separate renders instead of coalescing
- * the pair into a net-zero size change. */
-const JIGGLE_RESTORE_MS = 200;
 const KITTY_IMAGE_PREFIX = "\x1b_G";
 const ITERM2_FILE_PREFIX = "\x1b]1337;File=";
 
@@ -117,16 +113,16 @@ export class PtyAttachComponent implements Component {
 	private parserBuffer = "";
 	private retryTimer: ReturnType<typeof setTimeout> | null = null;
 	private loadingTimer: ReturnType<typeof setInterval> | null = null;
-	private redrawTimer: ReturnType<typeof setTimeout> | null = null;
 	private mouseRefreshTimers: Array<ReturnType<typeof setTimeout>> = [];
-	// Jiggle retry chain: re-send resize jiggle until we see a full-clear sequence
-	// in the PTY output, proving the child pi-tui did a fullRender and the replay
-	// garbage has been flushed. The controller re-arms once on the child TUI's
-	// first frame so cold-start attaches get a fresh budget exactly when the
-	// child can finally observe a resize (issue #10).
+	// Shrink-and-hold jiggle protocol (issue #25): on attach we resize the child to
+	// (cols-1, rows-1) and hold it there until the child emits a full clear
+	// (\x1b[2J) — any render the child makes while held sees a width delta and
+	// must fullRender, so boot-storm coalescing of ±1 pulses can no longer
+	// produce a net-zero change. The controller restores the original size on
+	// clear / first TUI frame (re-arm) / no-frame 6s guard / budget exhaustion /
+	// close / external resize (guards G1-G5, see controller module).
 	private readonly jiggleRetry = createJiggleRetryController({
-		sendJiggle: () => this.forceChildRedraw(),
-		shouldFire: () => !this.closed && this.connected,
+		sendResize: (cols, rows) => this.sendResize(cols, rows),
 		setTimeoutFn: (fn, ms) => {
 			const t = setTimeout(fn, ms);
 			t.unref?.();
@@ -170,6 +166,10 @@ export class PtyAttachComponent implements Component {
 	// into many small chunks; painting after each chunk would drive the outer TUI to its
 	// frame cap and expose intermediate frames (visible as flicker on a busy session).
 	private readonly outputRenderScheduler = createAttachOutputRenderScheduler(() => this.scheduleRender());
+	// Fold pi-tui's post-frame cursor-park writes back into the frame's sync block so the
+	// terminal reports one stable IME cursor rect per frame instead of two (issue #28).
+	// Never active when AGENT_BOARD_IME_FIX=0; no-op passthrough if pi-tui changes shape.
+	private readonly imeCoalesceUninstall: (() => void) | null;
 
 	constructor(
 		private readonly tui: TUI,
@@ -181,6 +181,9 @@ export class PtyAttachComponent implements Component {
 		const size = this.currentSize();
 		this.cols = size.cols;
 		this.rows = size.rows;
+		// Assigned in the body (not as a field initializer) so it runs after the `tui`
+		// parameter property is set regardless of the TS loader's field-init semantics.
+		this.imeCoalesceUninstall = installImeCursorCoalesce(this.tui);
 		this.term = new Terminal({ cols: this.cols, rows: this.rows, scrollback: 2000, allowProposedApi: true });
 		// Keep mouse reporting enabled by default so wheel scrolling and local drag-to-copy
 		// selection can coexist inside the attach surface. Set AGENT_BOARD_ATTACH_MOUSE=0
@@ -324,9 +327,7 @@ export class PtyAttachComponent implements Component {
 			this.connected = true;
 			this.status = "attached";
 			this.send({ type: "hello", clientId: `ui-${Date.now()}`, wantOutput: true });
-			this.sendResize();
-			this.forceChildRedraw();
-			this.jiggleRetry.start();
+			this.jiggleRetry.start(this.cols, this.rows);
 			this.enableMouseScroll();
 			this.scheduleRender();
 			this.startAttachSettle();
@@ -390,7 +391,7 @@ export class PtyAttachComponent implements Component {
 	/**
 	 * Attach transition lifecycle. Keep the loading banner up while the screen-log replay
 	 * and the initial resize-jiggle redraws settle, so the buffer doesn't visibly scroll or
-	 * flash through the viewport on attach. Each `forceChildRedraw` defers the settle
+	 * flash through the viewport on attach. Each output chunk defers the settle
 	 * window; a hard timeout guards against a session that never produces output.
 	 */
 	private startAttachSettle(): void {
@@ -435,13 +436,6 @@ export class PtyAttachComponent implements Component {
 		this.scheduleRender(true);
 	}
 
-	private clearRedrawTimer(): void {
-		if (this.redrawTimer) {
-			clearTimeout(this.redrawTimer);
-			this.redrawTimer = null;
-		}
-	}
-
 	private clearMouseRefreshTimers(): void {
 		for (const timer of this.mouseRefreshTimers) clearTimeout(timer);
 		this.mouseRefreshTimers = [];
@@ -784,6 +778,9 @@ export class PtyAttachComponent implements Component {
 		if (size.cols === this.cols && size.rows === this.rows) return;
 		this.cols = size.cols;
 		this.rows = size.rows;
+		// A real terminal resize supersedes the hold protocol: cancel any armed
+		// hold and adopt the new size as the baseline (guard G4, issue #25).
+		this.jiggleRetry.notifyExternalResize(size.cols, size.rows);
 		this.term.resize(this.cols, this.rows);
 		this.sendResize();
 		this.enableMouseScroll();
@@ -794,28 +791,6 @@ export class PtyAttachComponent implements Component {
 		this.clampViewportTop(this.bodyHeight());
 	}
 
-	private forceChildRedraw(): void {
-		this.clearRedrawTimer();
-		if (!this.connected) return;
-		const cols = this.cols;
-		const rows = this.rows;
-		const jiggle = localResizeJiggleSize(cols, rows);
-		if (!jiggle) return;
-		// A completed-session reattach often starts from an old screen.log recorded at
-		// a different terminal size. Real terminal zoom fixes that by causing SIGWINCH;
-		// do the same proactively so the child Pi redraws for the attach viewport.
-		this.sendResize(jiggle.cols, jiggle.rows);
-		this.deferAttachSettle();
-		this.redrawTimer = setTimeout(() => {
-			this.redrawTimer = null;
-			if (!this.closed && this.connected) {
-				this.sendResize(cols, rows);
-				this.deferAttachSettle();
-			}
-		}, JIGGLE_RESTORE_MS);
-		this.redrawTimer.unref?.();
-	}
-
 	/** Feed socket output into the jiggle retry controller (clear/frame detection). */
 	private checkClearSequence(data: string): void {
 		this.jiggleRetry.feed(data);
@@ -984,13 +959,13 @@ export class PtyAttachComponent implements Component {
 
 	private close(): void {
 		this.closed = true;
-		this.jiggleRetry.stop();
+		this.imeCoalesceUninstall?.();
+		this.jiggleRetry.restoreAndStop();
 		this.disableMouseScroll();
 		this.clearMouseRefreshTimers();
 		this.clearPendingClick();
 		this.clearSelectionAutoScroll();
 		this.clearRetry();
-		this.clearRedrawTimer();
 		this.stopLoadingTicker();
 		this.outputRenderScheduler.dispose();
 		if (this.attachSettleTimer) {
@@ -1009,13 +984,6 @@ export class PtyAttachComponent implements Component {
 	}
 }
 
-function localResizeJiggleSize(cols: number, rows: number): { cols: number; rows: number } | null {
-	if (cols > 21 && rows > 6) return { cols: cols - 1, rows: rows - 1 };
-	if (rows > 6) return { cols, rows: rows - 1 };
-	if (cols > 21) return { cols: cols - 1, rows };
-	return null;
-}
-
 function sameMousePoint(a: MousePoint, b: MousePoint): boolean {
 	return a.line === b.line && Math.abs(a.col - b.col) <= 1;
 }