@zhuxixi/pi-agent-board 0.4.0 → 0.4.2

package/docs/superpowers/specs/2026-08-22-question-tool-grouping-design.md

@@ -0,0 +1,114 @@
+# Spec: Recognize pi `question`/`questionnaire` tools as pending-question sources
+
+- **Issue**: zhuxixi/pi-agent-board#26
+- **Date**: 2026-08-22
+- **Status**: draft — awaiting user confirmation before implementation
+- **Type**: bug fix (event reducer + arg extraction), no data-model change
+
+## 1. Problem
+
+A pi session blocked on the built-in `question` (or `questionnaire`) tool shows a
+"Question" summary but stays in the **RUNNING** group instead of **NEEDS ANSWER**.
+
+Observed 2026-08-22 01:26 on view `view_e809b1a3a2` ("jfox moc密度PR审查与监控"):
+row summary "Question", `semanticState=working`, `pendingQuestions=[]`.
+
+## 2. Root cause
+
+The reducer only recognizes ONE question-tool name — `ask_questions`
+(`src/core/events.mjs` L83/L97). Pi's actual question tools are named
+`question` and `questionnaire` (user extensions:
+`~/.pi/agent/extensions/question.ts`, `questionnaire.ts`).
+
+When `tool_execution_start` arrives with `toolName: "question"`:
+1. Name check fails → `else if (pendingQuestions.length === 0)` branch runs →
+   `semanticState = "working"`, `currentTool.summary = toolSummary("question")` =
+   `capitalize("question")` = `"Question"` (heuristics.mjs default branch).
+2. `preservePendingQuestion` finds no pending question → no-op.
+3. Result: row grouped by `semanticState` = "working" → RUNNING, summary "Question".
+
+Correction to issue body: the "design gap B" claim (pending questions don't affect
+grouping) is **wrong** — `preservePendingQuestion` already sets
+`semanticState = "needs_input"` when `pendingQuestions` is non-empty. The ONLY gap is
+tool-name recognition (plus arg-shape extraction). See research/root-cause.md.
+
+## 3. Design
+
+All changes in `src/core/events.mjs` + tests. No store/schema/type changes.
+
+### 3.1 Question-tool name set
+
+```js
+const QUESTION_TOOL_NAMES = new Set(["ask_questions", "question", "questionnaire"]);
+```
+
+Replace both `name === "ask_questions"` checks (tool_execution_start L83,
+tool_execution_end L97) with `QUESTION_TOOL_NAMES.has(name)` /
+`QUESTION_TOOL_NAMES.has(event.toolName ?? "")`.
+
+Rationale: static set matches the existing hardcoded-name precedent; all three names
+are in the family of pi/agent question tools. A configurable list is deferred (4.2).
+
+### 3.2 `questionFromArgs` — support pi arg shapes
+
+Current: reads `args.questions[].question` (ask_questions shape).
+
+Extend to:
+
+| Tool | Args shape | Extract from |
+|---|---|---|
+| `ask_questions` | `{ questions: [{ question }] }` | `item.question` |
+| `question` (pi) | `{ question: string, options: [...] }` | `args.question` |
+| `questionnaire` (pi) | `{ questions: [{ prompt, options }] }` | `item.prompt`, fallback `item.question` |
+
+Priority in `questions[]` items: `item.question ?? item.prompt`. Keep the
+"Answer the pending question" fallback.
+
+### 3.3 Downstream flow (already correct — verify, don't change)
+
+- `tool_execution_start` (interactive, question tool): `upsertPendingQuestion` →
+  `preservePendingQuestion` → `semanticState = "needs_input"`, `currentTool = null`,
+  `question = first.question`. Row moves to NEEDS ANSWER group; summary shows the
+  question text (deriveSummary: needs_input + question).
+- `tool_execution_end` (interactive, question tool): `removePendingQuestion`,
+  `semanticState = "working"`, `question = null` — back to RUNNING after the answer.
+- Non-interactive (detached worker) path: `opts.interactive` gate unchanged →
+  question tools keep the old generic behavior (no pending-question tracking).
+
+### 3.4 Tests (`test/events.test.mjs`)
+
+Mirror the existing `ask_questions` coverage (L109-160):
+
+1. `tool_execution_start` with `toolName: "question"` (args `{ question: "Approve?" }`),
+   interactive → `pendingQuestions = [{ toolCallId, question: "Approve?" }]`,
+   `semanticState === "needs_input"`, `currentTool === null`, summary = question text.
+2. Same for `toolName: "questionnaire"` with args `{ questions: [{ prompt: "Pick scope" }] }`
+   → extracted question "Pick scope".
+3. `tool_execution_end` with `toolName: "question"` → pendingQuestions empty,
+   `semanticState === "working"`.
+4. Detached (no `interactive`) `question` start → unchanged legacy behavior
+   (`currentTool.name === "question"`, `pendingQuestions = []`).
+
+## 4. Non-goals / deferred
+
+1. No configurable question-tool list (env/config escape hatch). Add later only if a
+   harness with a different question-tool name appears. Keeping the set static avoids
+   new config surface.
+2. No changes to `finalizeRun`, `projectViewState`, `deriveSummary`, or grouping logic.
+3. Non-interactive path behavior unchanged.
+4. No i18n / label changes.
+
+## 5. Edge cases
+
+- Two concurrent question tool calls: keyed by `toolCallId`; first pending question wins
+  display. Unchanged from `ask_questions` behavior.
+- Non-TUI pi question tool returns an error result immediately → start/end pair clears
+  the pending question within the same cycle; transient needs_input is harmless.
+- `agent_start` / `input` events already clear `pendingQuestions` in the foreground
+  path (service.mjs L524-535) — no interaction.
+
+## 6. Verification
+
+- `npm run verify` (project gate) with the new events tests.
+- Manual: start a pi session under the board, have it call the `question` tool →
+  row shows the question text in NEEDS ANSWER group; answer it → row returns to RUNNING.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuxixi/pi-agent-board",
-  "version": "0.4.0",
+  "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/events.mjs

@@ -17,6 +17,9 @@ import { assistantText, detectNeedsInput, toolPath, toolSummary, truncate } from
 
 const PREVIEW_MAX = 240;
 
+/** Tool names whose interactive execution blocks on a user answer. */
+const QUESTION_TOOL_NAMES = new Set(["ask_questions", "question", "questionnaire"]);
+
 /**
  * Build the initial status for a freshly-launched run.
  * @param {RunConfig} config
@@ -80,7 +83,7 @@ export function reduceEvent(status, event, now, opts = {}) {
 			const name = event.toolName ?? event.args?.name ?? "tool";
 			const args = event.args ?? {};
 			status.toolCount += 1;
-			if (opts.interactive && name === "ask_questions") {
+			if (opts.interactive && QUESTION_TOOL_NAMES.has(name)) {
 				upsertPendingQuestion(status, event.toolCallId, questionFromArgs(args));
 			} else if (pendingQuestions(status).length === 0) {
 				status.currentTool = { name, path: toolPath(args), summary: toolSummary(name, args) };
@@ -94,7 +97,7 @@ export function reduceEvent(status, event, now, opts = {}) {
 		}
 		case "tool_execution_end": {
 			if (event.isError) status.error = `Tool ${event.toolName ?? ""} failed`.trim();
-			if (opts.interactive && event.toolName === "ask_questions") removePendingQuestion(status, event.toolCallId);
+			if (opts.interactive && QUESTION_TOOL_NAMES.has(event.toolName ?? "")) removePendingQuestion(status, event.toolCallId);
 			status.currentTool = null;
 			status.semanticState = "working";
 			status.question = null;
@@ -227,8 +230,9 @@ function pendingQuestions(status) {
 }
 
 function questionFromArgs(args) {
+	if (typeof args?.question === "string" && args.question.trim()) return args.question.trim();
 	for (const item of Array.isArray(args?.questions) ? args.questions : []) {
-		const question = String(item?.question ?? "").trim();
+		const question = String(item?.question ?? item?.prompt ?? "").trim();
 		if (question) return question;
 	}
 	return "Answer the pending question";

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 }),
 	};
 }