@zhuxixi/pi-agent-board 0.5.0 → 0.5.2

package/docs/superpowers/specs/2026-09-03-detach-gate-glyph-fallback-design.md

@@ -0,0 +1,99 @@
+# SPEC：#69 tier-2 字形兜底收紧 —— fallback 路径下 ← 恒可逃生
+
+- Issue: zhuxixi/pi-agent-board#69
+- 基线: main @ 9a61dd5（含 PR #71 editor_state 门禁）
+- 状态: 已批准（方案 B，2026-09-03）
+- 调研依据: `~/.claude/github-issue-driven/zhuxixi/pi-agent-board/issue-69/research/`（R1 代码影响面 / R2 KB / R3 PR 上下文），结论已评论回 issue
+
+## 1. 背景与根因（已实锤，不再重复调试）
+
+`←` detach 门禁三层结构（#71 后）：
+
+```
+handleInput(←)
+  └─ connected? ── no ──→ 无条件逃生（#48，不动）
+       └─ yes → resolveEditorEmpty(editorEmpty, heuristic)
+                  ├─ editorEmpty ≠ null → 权威子进程状态（#71，不动）
+                  └─ editorEmpty = null → 启发式 childInputLooksEmpty()
+                        ├─ tier-1: 反色假光标锚点（不动）
+                        ├─ tier-2: 字形兜底 ← ★ 本次唯一改动点 ★
+                        └─ 兜底: return true 逃生
+```
+
+**根因**：fallback 模式（子会话无 editor-state reporter：旧版 pi 无 `ctx.ui.getEditorText`、扩展未加载、socket 未建立）下，真实 attach buffer 常零反色 cell → tier-1 落空 → tier-2 自底向上扫到 `isProbablyPiInputLine` 命中的聊天区 markdown 表格行（`│ … │`）或引用行（`> …`）→ `isProbablyEmptyPiInputLine` 判非空 → return false → `←` 被转发给子进程，用户被困。已在 main(9a61dd5) 上以 smoke 场景 K 复现（零反色 + `│ Issue #778 │ open │` + `> quote` + editorEmpty=null → didDetach=false）。
+
+## 2. 修复设计
+
+### 2.1 tier-2 行为决策表（唯一行为变化面）
+
+| tier-2 扫到的行（自底向上首个 glyph 行） | 现行为 | 新行为 | 理由 |
+|---|---|---|---|
+| 空 glyph 行（`> `、`› `、`┃  `） | true（detach） | true（不变） | 编辑器为空 |
+| 内容 glyph 行（`│ table │`、`> quote`、真草稿 `> draft`） | **false（gated，#69 bug）** | **true（detach）** | fallback 下无法区分表格/引用/草稿；可退出性优先 |
+| 无 glyph 行 / 扫不到 | true | true（不变） | 既有逃生 |
+
+**收紧后 tier-2 语义恒为 true**（内容行跳过 + 扫不到逃生）——fallback 恒放行，这是有意取舍：草稿保护的可靠路径已由 #71 editor_state 承担；fallback 模式下误判代价不对称（误 detach = 意外退视图、草稿不丢、重新 attach 即回；误 gate = 用户被困）。与 #42/#48「视图必须始终可退出」哲学同向。
+
+### 2.2 改动点（两案行为完全等价，纯代码形态选择）
+
+**方案 B（推荐，与维护者在 #69 评论中已本地验证的实现一致）**：
+
+```ts
+// src/ui/pty-attach.ts  childInputLooksEmpty() tier-2 循环
+for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
+    const line = active.getLine(y)?.translateToString(true) ?? "";
+    // Only an EMPTY glyph line proves an empty editor. Content glyph lines
+    // (markdown table rows `│ … │`, quotes `> …`, or a real draft in a
+    // no-fake-cursor Pi variant) cannot be told apart, and trapping the
+    // user is worse than a spurious detach (issue #69) — skip and keep
+    // scanning; the loop-end escape stays authoritative.
+    if (isProbablyPiInputLine(line) && isProbablyEmptyPiInputLine(line)) return true;
+}
+return true;
+```
+
+- 保留扫描骨架：为中期方案（按 pi TUI dock 结构：底部 `─` 分隔线与 footer 间定位编辑器行，可恢复 fallback 草稿保护）留结构；注释固化取舍理由。
+- `isProbablyPiInputLine` 继续有生产调用点，不需要删除。
+
+**方案 A（备选）**：直接删循环 `return true` + 注释。语义/测试与 B 完全一致，diff 更小，但丢掉骨架与意图表达。
+
+### 2.3 数据流与组件契约
+
+- 无新组件、无协议消息、无公共 API 变化；`resolveEditorEmpty`、tier-1、editor_state 链路（reporter → runner broadcast → attach 缓存 → hello 重置）一概不动。
+- 唯一触碰的生产文件：`src/ui/pty-attach.ts`（tier-2 循环体）。
+- 触发窗口说明：收紧只影响 editorEmpty=null 的降级判定（reporter 缺席）；reporter 活跃时 `resolveEditorEmpty` 短路，主路径零变化。
+
+## 3. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | #69 真实场景放行：零反色 + 聊天区 `│` 表格行/`>` 引用行 + editorEmpty=null + connected=true → `←` detach | 自动化验证（integration：detach-gate smoke，经 `test/pty-attach-detach-gate.test.mjs` 驱动） | `npm test`；新增 smoke key `leftDetachesOnTableRowsWithoutFakeCursor` | 新 key 断言 true，全量测试通过 |
+| A2 | 有意回归被钉住：内容 glyph 行（真草稿形态 `> draft`）+ 零反色 + editorEmpty=null → `←` detach（fallback 草稿保护失效是有意取舍，防止未来被"顺手修"）。**与既有 smoke B 互为对照**：同为草稿形态，B 带 inverse 走 tier-1 → gated，A2 零反色走 fallback → detach——两种判定不矛盾，正是本取舍的教科书示例（smoke 场景注释中须写明此对照） | 自动化验证（integration：同上） | 新增 smoke key `leftDetachesOnContentGlyphFallback` | 新 key 断言 true |
+| A3 | 既有行为零回归：B（tier-1 草稿 gate）、J（hello null 重置）、空 glyph 行 detach、editor_state 系列（H/J 全部 key）、ctrl+] 透传、断线逃生等 | 自动化验证（integration + unit 全量） | `npm test`（基线 437；新 smoke key 是既有 test 块内的新断言，node:test 计数不变） | 全量 437 全绿，既有 key 结果不变 |
+| A4 | 类型/静态约束 | 自动化验证（static/build） | `npm run typecheck` | 0 错误（CI Node 22/24 等价覆盖） |
+| U1 | 真实仪表盘复测 #69 场景：attach 一个聊天区含 markdown 表格输出的 warm 会话，输入框空时按 `←` | 用户实测 | 在运行副本 `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board` 里 `git fetch && git checkout <PR 分支>`（#67 实测已验证的本地加载法），重启 pi 后打开 dashboard → attach → 空输入按 `←`；测完 checkout 回 main 并重启 | 回到 dashboard，不被困（可执行时机：实现完成、PR 分支推送后、合并前） |
+| U2 | 主路径草稿保护不受影响：reporter 活跃会话输入草稿后按 `←` | 用户实测 | 同 U1 环境，attach 后输入草稿，按 `←` | 光标在草稿内左移，不 detach（复测 #67 U3 同款；可执行时机同 U1） |
+
+**用户实测不可自动化的原因（U1/U2）**：真实 dashboard attach 涉及宿主 pi TUI 差分渲染 + pty-runner + editor-state reporter socket 的全链路，headless harness 用内存 xterm 无法复现真实终端渲染与扩展加载，只能人测。注意：实测需重启 pi，当前开发会话所在的 pi 实例会中断——在另一个终端/pi 实例里执行。
+
+## 4. 可测性拆分设计（自动化项）
+
+- **纯函数层（不变）**：`isProbablyEmptyPiInputLine` / `isProbablyPiInputLine` / `resolveEditorEmpty` 已在 `test/pty-input.test.mjs` 有 unit 钉语义；本次不改其行为，不新增纯函数——收紧后 tier-2 决策恒为 true，为常量行为建纯函数无判别价值，强行抽取只会产生恒真断言的空转测试。
+- **组件决策层（改动面）**：`childInputLooksEmpty()` 本身无副作用（只读 xterm buffer + 纯判定），判别性（detach vs forward）落在组件级 smoke harness（`test-support/detach-gate-smoke.ts`，经 `test/pty-attach-detach-gate.test.mjs` 以子进程运行并断言全部 key）——沿用 #42/#48/#66/#68 的既有测试边界，不引入新测试形态。
+- **测试边界总结**：unit 钉 helper 语义（A3 覆盖）→ integration smoke 钉组件门禁决策（A1/A2/A3）→ static/typecheck 钉类型（A4）。A1/A2 ↔ smoke 新场景；A3 ↔ smoke 既有 key + unit 全量；A4 ↔ typecheck。双向可追溯。
+- **smoke 惯例**：在线 gate 场景必须显式 pin `connected=true`（B 段既有惯例；不 pin 时断线逃生语义会抢跑，测不到在线门禁）；新场景 K1（A1）/K2（A2）同样遵守。
+
+## 5. 非目标
+
+- ❌ 中期 dock 结构锚点（底部 `─` 分隔线与 footer 间定位编辑器行）——未来若要恢复 fallback 草稿保护再立项
+- ❌ 触碰 tier-1 反色锚点、editor_state 链路（#71 成果）
+- ❌ 删除渲染启发式整体（继续作为 #71 的 fallback 层存在）
+- ❌ 方案 A 下的 `isProbablyPiInputLine` 去留不在本 spec 讨论（选 B 则无此问题）
+- ❌ 不改 README：line 96/195 的 `←` 行为描述以受支持主路径（reporter 活跃）为准，fallback 降级细节属实现层，由 A2 钉住——此为明确决定，防止未来被当成文档漂移
+
+## 6. 风险与降级
+
+- 风险 1：fallback 下真草稿按 `←` 变为 detach（有意回归，A2 钉住；草稿不丢，重新 attach 即回）。
+- 风险 2：`←` 在 attach 初建窗口（hello 尚未带回 editorEmpty、reporter 首推未达）若子进程恰有草稿，会 detach——窗口极短且后果同上，接受。
+- 无运行时降级路径需求：本改动本身就是降级路径的加固；不合并时现状是「fallback 可被困」（更差）。
+- **post-merge 生效**：运行副本 `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board`（当前停在 0.5.1 / fac9e91，连 #66 都没有）需 `git pull`（或 `pi update`）并重启 pi 后才带本修复——人工部署步骤，不在自动化环内。

package/package.json

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

package/runner/pty-runner.mjs

@@ -60,12 +60,21 @@ function main() {
 	let childPid = null;
 	let child = null;
 	let exitCode = null;
-	let stopping = false;
+	let shutdownStarted = false;
+	let shutdownExitCode = null;
+	let childExited = false;
+	let resolveChildExit;
+	const childExitPromise = new Promise((resolve) => {
+		resolveChildExit = resolve;
+	});
 	// Set when the uncaughtException crash handler finalizes the host. Guards
 	// child.onExit against clobbering the persisted "failed" state with an
 	// "exited" update (the handler kills the child, so its exit callback fires
 	// inside the 50ms flush window — CR round-1, issue #48).
 	let crashed = false;
+	/** Authoritative child editor emptiness, pushed by the child Pi extension
+	 * (issue #68). null = unknown (extension missing / not yet reported). */
+	let editorEmpty = null;
 	/** @type {import("../src/core/types.mjs").HostStatus} */
 	let host = {
 		version: 1,
@@ -182,25 +191,30 @@ function main() {
 		broadcast({ type: "output", data });
 	});
 	child.onExit((code) => {
+		childExited = true;
+		resolveChildExit?.();
 		exitCode = code ?? 0;
 		// After a crash the handler already persisted "failed" and broadcast
 		// exit; this callback must not overwrite that state.
 		if (!crashed) {
-			update({ state: stopping ? "exited" : "exited", endedAt: Date.now(), exitCode, childPid: null });
+			update({ state: "exited", endedAt: Date.now(), exitCode, childPid: null });
+			editorEmpty = null;
+			broadcast({ type: "editor_state", empty: null });
 			broadcast({ type: "exit", exitCode });
 		}
-		setTimeout(() => process.exit(exitCode ?? 0), 50).unref?.();
+		if (!shutdownStarted) setTimeout(() => process.exit(exitCode ?? 0), 50).unref?.();
 	});
 	child.onError((err) => {
 		update({ state: "failed", endedAt: Date.now(), exitCode: 1, error: err instanceof Error ? err.message : String(err) });
 		broadcast({ type: "error", message: host.error || "child error" });
-		setTimeout(() => process.exit(1), 50).unref?.();
+		void shutdown(1);
 	});
 
-	const server = createServer((socket) => {
+	let server;
+	server = createServer((socket) => {
 		clients.add(socket);
 		update({ attachedEver: true });
-		socket.write(JSON.stringify({ type: "hello", status: host }) + "\n");
+		socket.write(JSON.stringify({ type: "hello", status: host, editorEmpty }) + "\n");
 		let buffer = "";
 		socket.on("data", (chunk) => {
 			buffer += chunk.toString("utf8");
@@ -219,8 +233,7 @@ function main() {
 	});
 	server.on("error", (err) => {
 		update({ state: "failed", endedAt: Date.now(), error: err instanceof Error ? err.message : String(err), exitCode: 1 });
-		killChild(child, childPid, "SIGTERM");
-		process.exit(1);
+		void shutdown(1);
 	});
 	server.listen(socketPath, () => update({ socketPath, state: "alive" }));
 
@@ -230,7 +243,7 @@ function main() {
 		try { msg = JSON.parse(line); } catch { return send(socket, { type: "error", message: "invalid json" }); }
 		switch (msg.type) {
 			case "hello":
-				send(socket, { type: "hello", status: host });
+				send(socket, { type: "hello", status: host, editorEmpty });
 				break;
 			case "input":
 				if (typeof msg.data === "string") child.write(msg.data);
@@ -246,7 +259,6 @@ function main() {
 				child.write("\x1b");
 				break;
 			case "terminate": {
-				stopping = true;
 				killChild(child, childPid, "SIGTERM");
 				setTimeout(() => killChild(child, childPid, "SIGKILL"), 4000).unref?.();
 				break;
@@ -257,6 +269,11 @@ function main() {
 			case "get_status":
 				send(socket, { type: "status", status: host });
 				break;
+			case "editor_state": {
+				editorEmpty = typeof msg.empty === "boolean" ? msg.empty : null;
+				broadcast({ type: "editor_state", empty: editorEmpty });
+				break;
+			}
 		}
 	}
 
@@ -265,15 +282,45 @@ function main() {
 	}, HEARTBEAT_MS);
 	heartbeat.unref?.();
 
-	const shutdown = () => {
-		stopping = true;
-		try { server.close(); } catch {}
+	function waitForChildExit(timeoutMs) {
+		if (childExited) return Promise.resolve(true);
+		return new Promise((resolve) => {
+			let settled = false;
+			let timer;
+			const finish = (exited) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				resolve(exited);
+			};
+			timer = setTimeout(() => finish(false), timeoutMs);
+			childExitPromise.then(() => finish(true));
+		});
+	}
+
+	async function shutdown(requestedExitCode = null) {
+		if (requestedExitCode !== null) shutdownExitCode = requestedExitCode;
+		if (shutdownStarted) return;
+		shutdownStarted = true;
+		try { server?.close(); } catch {}
 		try { if (existsSync(socketPath)) unlinkSync(socketPath); } catch {}
+		for (const client of clients) {
+			try { client.end(); } catch {}
+		}
 		killChild(child, childPid, "SIGTERM");
-		setTimeout(() => process.exit(0), 100).unref?.();
-	};
-	process.on("SIGTERM", shutdown);
-	process.on("SIGINT", shutdown);
+		if (!(await waitForChildExit(4000)) && !childExited) {
+			killChild(child, childPid, "SIGKILL");
+			if (!(await waitForChildExit(1000)) && !childExited) {
+				// The child abstraction has no portable liveness probe. Exit only
+				// after the escalation window so normal children are always awaited;
+				// an unkillable platform child is left to the OS.
+				process.exit(1);
+			}
+		}
+		process.exit(shutdownExitCode ?? exitCode ?? 0);
+	}
+	process.on("SIGTERM", () => { void shutdown(); });
+	process.on("SIGINT", () => { void shutdown(); });
 }
 
 function spawnInteractive(command, args, opts) {

package/src/core/code-refs-store.mjs

@@ -141,6 +141,9 @@ function currentBranch(cwd) {
 			encoding: "utf8",
 			stdio: ["ignore", "pipe", "ignore"],
 			timeout: 2000,
+			// Windows: no console window when spawned from a console-less worker
+			// (issue #49 follow-up — these git spawns created visible WT windows).
+			windowsHide: true,
 		});
 		branch = out.trim() || null;
 	} catch {

package/src/core/editor-state-reporter.mjs

@@ -0,0 +1,102 @@
+/** Child-Pi editor-state reporter (issue #68): polls the child Pi's editor text
+ * and pushes `{type:"editor_state", empty}` over the control socket whenever the
+ * text changes, so the attach surface can gate ← on the authoritative state
+ * instead of render heuristics. Dependency-injected for unit testing. */
+
+/** @typedef {{ write(jsonLine: string): void; on?(event: "close" | "error", fn: () => void): void }} SocketLike */
+
+const defaultScheduler = {
+	interval(fn, ms) { const h = setInterval(fn, ms); h.unref?.(); return h; },
+	timeout(fn, ms) { const h = setTimeout(fn, ms); h.unref?.(); return h; },
+	clear(handle) { clearInterval(handle); clearTimeout(handle); },
+};
+
+export function createEditorStateReporter({ getEditorText, connect, intervalMs = 100, scheduler = defaultScheduler }) {
+	let started = false;
+	let stopped = false;
+	let socket = null;
+	let pollTimer = null;
+	let reconnectTimer = null;
+	let backoffMs = 1000;
+	let lastText = null;
+
+	function send(json) {
+		if (!socket) return;
+		try {
+			socket.write(JSON.stringify(json) + "\n");
+		} catch {
+			teardownSocket();
+			scheduleReconnect();
+		}
+	}
+
+	function teardownSocket() {
+		if (pollTimer !== null) { scheduler.clear(pollTimer); pollTimer = null; }
+		const s = socket;
+		socket = null;
+		try { s?.destroy?.(); } catch { /* already torn down */ }
+		try { s?.removeAllListeners?.(); } catch { /* already torn down */ }
+	}
+
+	function poll() {
+		if (stopped || !socket) return;
+		let text;
+		try {
+			text = getEditorText();
+		} catch {
+			return;
+		}
+		text = typeof text === "string" ? text : "";
+		if (text !== lastText) {
+			lastText = text;
+			send({ type: "editor_state", empty: text.length === 0 });
+		}
+	}
+
+	function startPolling() {
+		if (pollTimer !== null) return;
+		lastText = null; // force a first report after (re)connect
+		pollTimer = scheduler.interval(poll, intervalMs);
+	}
+
+	function scheduleReconnect() {
+		if (stopped) return;
+		teardownSocket();
+		reconnectTimer = scheduler.timeout(tryConnect, backoffMs);
+		backoffMs = Math.min(backoffMs * 2, 5000);
+	}
+
+	function tryConnect() {
+		reconnectTimer = null;
+		if (stopped) return;
+		let s;
+		try {
+			s = connect();
+		} catch {
+			scheduleReconnect();
+			return;
+		}
+		socket = s;
+		s?.resume?.();
+		s?.unref?.();
+		s?.on?.("data", () => {}); // consume and discard broadcast traffic
+		s?.on?.("connect", () => { if (socket === s) { backoffMs = 1000; startPolling(); } });
+		s?.on?.("close", () => { if (socket === s) scheduleReconnect(); });
+		s?.on?.("error", () => { if (socket === s) scheduleReconnect(); });
+	}
+
+	function start() {
+		if (started) return;
+		started = true;
+		stopped = false;
+		tryConnect();
+	}
+
+	function stop() {
+		stopped = true;
+		if (reconnectTimer !== null) { scheduler.clear(reconnectTimer); reconnectTimer = null; }
+		teardownSocket();
+	}
+
+	return { start, stop };
+}

package/src/core/launch.mjs

@@ -33,6 +33,9 @@ export function launchRun(root, config, opts) {
 		detached: true,
 		stdio: "ignore",
 		env: process.env,
+		// Windows: detached children get their own console window unless
+		// suppressed (CREATE_NO_WINDOW; no-op on POSIX) — issue #49.
+		windowsHide: true,
 	});
 	child.unref();
 
@@ -61,6 +64,7 @@ export function launchHost(root, config, opts) {
 		detached: true,
 		stdio: "ignore",
 		env: process.env,
+		windowsHide: true,
 	});
 	child.unref();
 
@@ -85,6 +89,7 @@ export function launchTitle(root, config, opts) {
 		detached: true,
 		stdio: "ignore",
 		env: process.env,
+		windowsHide: true,
 	});
 	child.unref();
 
@@ -109,6 +114,7 @@ export function launchAutoState(root, config, opts) {
 		detached: true,
 		stdio: "ignore",
 		env: process.env,
+		windowsHide: true,
 	});
 	child.unref();
 

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

@@ -2,10 +2,12 @@
  * Injectable orchestration for the attach shrink-and-hold jiggle protocol.
  *
  * 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
+ * shrink-and-hold protocol: on connect we resize the child PTY to a safe
+ * alternate size and KEEP it there until the child's own rendering proves it
+ * observed the size change (a full clear, \x1b[2J, which pi-tui emits from
+ * fullRender(true) whenever widthChanged fires). At normal sizes the alternate
+ * size is one column/row smaller; near the minimum it changes only a safe
+ * dimension, and at 20x5 no jiggle is attempted. 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
@@ -27,10 +29,19 @@
  *   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).
+ *   G6 post-restore verify (issue #42): the frameStart fast path restores the
+ *      hold on the FIRST frame, which may predate the shrink — if the restore
+ *      then collapses both resizes into a net-zero change at the child, the
+ *      child renders nothing and never clears. While a frame has been seen
+ *      and no clear followed, each backoff tick re-arms the shrink (which
+ *      lands alone and cannot collapse), bounded by the same retry budget.
  *
  * 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.
+ * is restored within 6s — still better than the pre-#10 behavior. At the
+ * minimum supported PTY size (20x5), jiggle is disabled because the runner's
+ * clamp leaves no valid alternate size.
  */
+import { resizeJiggleSize } from "./pty-scroll.mjs";
 import {
 	advanceRetry,
 	createJiggleRetryState,
@@ -41,6 +52,13 @@ import {
 
 /** Restore the held (shrunk) child PTY when no TUI frame arrives this long. */
 const NO_FRAME_RESTORE_MS = 6000;
+/**
+ * Grace window after the frameStart fast-path restore before the chain may
+ * re-poke (issue #42). A healthy child proves the restore landed with a
+ * fullRender clear within a few hundred ms even on large screens; without the
+ * grace a slow-but-healthy clear would trigger a pointless re-shrink flicker.
+ */
+const POST_RESTORE_VERIFY_MS = 900;
 
 /**
  * @typedef {Object} JiggleRetryControllerDeps
@@ -64,6 +82,8 @@ export function createJiggleRetryController(deps) {
 	/** @type {[number, number]} */
 	let originalCols = 0;
 	let originalRows = 0;
+	/** The safe alternate size used while a jiggle hold is active, or null when unsupported. */
+	let holdSize = null;
 	/** @type {unknown | null} */
 	let chainTimer = null;
 	/** @type {unknown | null} */
@@ -98,10 +118,31 @@ export function createJiggleRetryController(deps) {
 	}
 
 	/**
-	 * 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.
+	 * One chain tick: advance the backoff budget, then re-arm the hold if the
+	 * child has a renderer (a TUI frame was seen) but no clear ever proved the
+	 * last size delta landed and the hold is currently inactive (issue #42:
+	 * the frameStart fast-path restore can race the shrink into a net-zero
+	 * size change at the child — its throttled renderer reads back the
+	 * original size and stays silent forever — so a clear-less restore must
+	 * be followed by a fresh shrink, which lands alone and cannot collapse).
+	 * Children that never rendered a frame (shells, cold boots) keep the old
+	 * pure-countdown behavior and are handled by G1/G2 only.
 	 */
+	function tickChain() {
+		chainTimer = null;
+		state = advanceRetry(state);
+		ensureHold();
+		if (state.clearDetected || state.stopped) return;
+		scheduleNextRetry();
+	}
+
+	function ensureHold() {
+		if (!tuiFrameSeen || held || state.clearDetected || state.stopped || !holdSize) return;
+		sendResize(holdSize.cols, holdSize.rows);
+		held = true;
+		restored = false;
+	}
+
 	function scheduleNextRetry() {
 		const delay = nextRetryDelay(state);
 		if (delay === null) {
@@ -109,11 +150,7 @@ export function createJiggleRetryController(deps) {
 			restoreIfHeld(); // G2
 			return;
 		}
-		chainTimer = setTimeoutFn(() => {
-			chainTimer = null;
-			state = advanceRetry(state);
-			scheduleNextRetry();
-		}, delay);
+		chainTimer = setTimeoutFn(tickChain, delay);
 	}
 
 	function armG1() {
@@ -142,8 +179,18 @@ export function createJiggleRetryController(deps) {
 		tuiFrameSeen = false;
 		originalCols = cols;
 		originalRows = rows;
+		holdSize = resizeJiggleSize(cols, rows);
 		sendResize(cols, rows);
-		sendResize(cols - 1, rows - 1);
+		if (!holdSize) {
+			// The runner clamps below 20x5, so a smaller request would be a
+			// net-zero resize and cannot trigger a redraw. Leave the child at the
+			// requested original size and disable this attach's jiggle chain.
+			state = stopRetry(state);
+			held = false;
+			restored = true;
+			return;
+		}
+		sendResize(holdSize.cols, holdSize.rows);
 		held = true;
 		restored = false;
 		armG1();
@@ -176,14 +223,20 @@ export function createJiggleRetryController(deps) {
 			clearG1Timer();
 			if (held) {
 				restoreIfHeld(); // fast path: child is rendering, width delta now lands
+				// …unless that frame was in flight BEFORE the shrink and the restore
+				// collapses both into a net-zero change at the child (issue #42).
+				// Restart the chain on the post-restore grace window: no clear within
+				// POST_RESTORE_VERIFY_MS → tickChain re-arms the hold (ensureHold).
+				clearChainTimer();
+				chainTimer = setTimeoutFn(tickChain, POST_RESTORE_VERIFY_MS);
 			} 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;
+				if (holdSize) sendResize(holdSize.cols, holdSize.rows);
+				held = holdSize !== null;
 				restored = false;
 			}
 		}
@@ -212,6 +265,7 @@ export function createJiggleRetryController(deps) {
 		restored = false;
 		originalCols = cols;
 		originalRows = rows;
+		holdSize = null;
 		state = stopRetry(state);
 	}
 
@@ -220,6 +274,6 @@ export function createJiggleRetryController(deps) {
 		feed,
 		restoreAndStop,
 		notifyExternalResize,
-		getState: () => ({ ...state, held, tuiFrameSeen, originalCols, originalRows }),
+		getState: () => ({ ...state, held, tuiFrameSeen, originalCols, originalRows, holdSize }),
 	};
 }

package/src/core/pty-input.mjs

@@ -13,3 +13,35 @@ export function isProbablyEmptyPiInputLine(line) {
 	const content = withoutRightPadding.replace(/^[\s\u00a0›>┃│|┆╎╏:]+/u, "");
 	return content.length === 0;
 }
+
+/** Glyphs Pi uses to render editor prompt / continuation lines (`>` main prompt,
+ * `›`/`┃`/`│` and variants in older releases). Must stay in sync with the
+ * trim charset of isProbablyEmptyPiInputLine below. */
+const PROMPT_GLYPHS = "›>┃│|┆╎╏:";
+
+/**
+ * Whether the given terminal line looks like a Pi editor input line: leading
+ * whitespace followed by a prompt/continuation glyph. The attach surface uses
+ * this to locate the editor line inside the buffer instead of trusting the
+ * terminal cursor, which wanders onto output/working lines while Pi streams
+ * (issue #66).
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function isProbablyPiInputLine(line) {
+	const withoutLeftPadding = String(line || "").replace(/^[\s\u00a0]+/u, "");
+	return withoutLeftPadding.length > 0 && PROMPT_GLYPHS.includes(withoutLeftPadding[0]);
+}
+
+/**
+ * Resolve the ← detach gate's emptiness signal: when the child Pi pushes its
+ * authoritative editor state (boolean), it wins; when it is unknown (null/
+ * undefined — child extension missing or socket never connected), fall back
+ * to the render heuristic.
+ * @param {boolean | null | undefined} editorEmpty
+ * @param {boolean} heuristic
+ * @returns {boolean}
+ */
+export function resolveEditorEmpty(editorEmpty, heuristic) {
+	return editorEmpty === null || editorEmpty === undefined ? heuristic : editorEmpty;
+}

package/src/core/pty-scroll.mjs

@@ -141,9 +141,10 @@ export function selectionDragScrollLines(row, bodyHeight) {
 }
 
 /**
- * Return a one-frame alternate PTY size that will force a hosted TUI to receive a
- * SIGWINCH/redraw before restoring the real size. This mirrors the user-visible
- * terminal zoom workaround without leaving the child at the wrong dimensions.
+ * Return a safe temporary PTY size for an attach jiggle hold. The attach controller
+ * keeps the child at this size until a clear or guard restores the original size;
+ * near the minimum supported dimensions, only one safe dimension is changed, and
+ * at 20x5 there is no valid alternate size.
  */
 export function resizeJiggleSize(cols, rows) {
 	const c = Math.max(1, Math.floor(cols));

package/src/core/repo.mjs

@@ -12,6 +12,7 @@ export function gitRepoRoot(cwd) {
 		const out = execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
 			encoding: "utf8",
 			stdio: ["ignore", "pipe", "ignore"],
+			windowsHide: true,
 		});
 		const root = out.trim();
 		return root || null;
@@ -40,6 +41,7 @@ export function isDirty(repoRoot) {
 		const out = execFileSync("git", ["-C", repoRoot, "status", "--porcelain"], {
 			encoding: "utf8",
 			stdio: ["ignore", "pipe", "ignore"],
+			windowsHide: true,
 		});
 		return out.trim().length > 0;
 	} catch {
@@ -70,6 +72,7 @@ export function gitRemoteUrl(repoRoot) {
 			encoding: "utf8",
 			stdio: ["ignore", "pipe", "ignore"],
 			timeout: 2000,
+			windowsHide: true,
 		});
 		url = out.trim() || null;
 	} catch {

package/src/core/worktree.mjs

@@ -15,6 +15,7 @@ function git(repoRoot, args) {
 		const stdout = execFileSync("git", ["-C", repoRoot, ...args], {
 			encoding: "utf8",
 			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
 		});
 		return { ok: true, stdout: stdout.trim(), error: null };
 	} catch (err) {