@zhuxixi/pi-agent-board 0.6.2 → 0.7.0

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

@@ -60,6 +60,11 @@ const NO_FRAME_RESTORE_MS = 6000;
  */
 const POST_RESTORE_VERIFY_MS = 900;
 
+/** Lifetime cap on runtime desync heals (issue #11): a persistent misdiagnosis
+ * must not flicker the screen forever; after this many attempts the backstop
+ * stays quiet until the controller is recreated. Consumed on heal() entry. */
+const HEAL_MAX_PER_LIFETIME = 5;
+
 /**
  * @typedef {Object} JiggleRetryControllerDeps
  * @property {(cols: number, rows: number) => void} sendResize - Resize the child PTY.
@@ -88,6 +93,8 @@ export function createJiggleRetryController(deps) {
 	let chainTimer = null;
 	/** @type {unknown | null} */
 	let g1Timer = null;
+	/** Runtime heals spent (issue #11); never reset by start()/restoreAndStop(). */
+	let healCount = 0;
 
 	function clearChainTimer() {
 		if (chainTimer === null) return;
@@ -199,7 +206,10 @@ export function createJiggleRetryController(deps) {
 
 	/**
 	 * 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
+	 * appear in one chunk — but frame cognition is still learned from that
+	 * chunk: a clear only proves the child redraws, not that it isn't a TUI
+	 * (screen-log replay bundles historical frames with clears, issue #11).
+	 * 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
@@ -212,14 +222,18 @@ export function createJiggleRetryController(deps) {
 		const result = feedOutput(state, data, carry);
 		state = result.state;
 		carry = result.carry;
+		// Learn frame cognition unconditionally, BEFORE the clear branch: a
+		// clear-wins chunk must not swallow it (issue #11), and only the FIRST
+		// frame ever seen drives the re-arm/fast-path logic below.
+		const firstFrame = result.frameStartFound && !tuiFrameSeen;
+		if (result.frameStartFound) tuiFrameSeen = true;
 		if (result.clearFound) {
 			clearAllTimers();
 			restoreIfHeld();
 			state = stopRetry({ ...state, clearDetected: true });
 			return;
 		}
-		if (result.frameStartFound && !tuiFrameSeen) {
-			tuiFrameSeen = true;
+		if (firstFrame) {
 			clearG1Timer();
 			if (held) {
 				restoreIfHeld(); // fast path: child is rendering, width delta now lands
@@ -242,6 +256,44 @@ export function createJiggleRetryController(deps) {
 		}
 	}
 
+	/**
+	 * Runtime desync backstop (issue #11): re-arm the shrink-and-hold protocol
+	 * mid-session. Unlike start(), tuiFrameSeen is preserved (the child has
+	 * rendered), G1 is not armed (frames are flowing), and the budget is
+	 * lifetime-capped so a misdiagnosis cannot flicker the screen forever.
+	 * Consumes one budget slot on entry, including the tiny-terminal give-up.
+	 * @param {number} cols
+	 * @param {number} rows
+	 * @returns {boolean} true when a heal hold was armed.
+	 */
+	function heal(cols, rows) {
+		if (healCount >= HEAL_MAX_PER_LIFETIME) return false;
+		healCount++;
+		clearAllTimers();
+		if (held) {
+			// Unwind any live hold (e.g. a previous clear-less heal) first.
+			sendResize(originalCols, originalRows);
+			restored = true;
+			held = false;
+		}
+		state = createJiggleRetryState();
+		carry = "";
+		originalCols = cols;
+		originalRows = rows;
+		holdSize = resizeJiggleSize(cols, rows);
+		if (!holdSize) {
+			state = stopRetry(state);
+			held = false;
+			restored = true;
+			return false;
+		}
+		sendResize(holdSize.cols, holdSize.rows);
+		held = true;
+		restored = false;
+		scheduleNextRetry(); // G2 backoff re-shrinks while a renderer is seen but no clear follows
+		return true;
+	}
+
 	/**
 	 * 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).
@@ -272,8 +324,9 @@ export function createJiggleRetryController(deps) {
 	return {
 		start,
 		feed,
+		heal,
 		restoreAndStop,
 		notifyExternalResize,
-		getState: () => ({ ...state, held, tuiFrameSeen, originalCols, originalRows, holdSize }),
+		getState: () => ({ ...state, held, tuiFrameSeen, originalCols, originalRows, holdSize, healCount }),
 	};
 }

package/src/core/pty-attach-render.mjs

@@ -70,3 +70,33 @@ export function createAttachOutputRenderScheduler(requestRender, delayMs = ATTAC
 		},
 	};
 }
+
+/**
+ * Classify the PTY cursor's alignment for runtime desync detection (issue #11).
+ *
+ * Healthy idle pi: the child pi-tui parks the hardware cursor on the editor
+ * marker, whose cell is the inverse-video "fake cursor" — so the cursor cell
+ * itself is inverse. A desynced buffer leaves the cursor parked elsewhere
+ * (typically where the last differential write ended), on a non-inverse cell.
+ * Width-0 cells are CJK continuation cells and out-of-range columns sit past
+ * the line's cells; in both cases the meaningful attribute lives on the
+ * preceding cell, so we look left. Returns:
+ *   "aligned"    — cursor resolves to an inverse cell (healthy);
+ *   "misaligned" — cursor resolves to a non-inverse cell (candidate desync;
+ *                  callers gate this with an output-quietness window);
+ *   "unknown"    — no cursor (scrolled out of the projected viewport) or no
+ *                  buffer line (defensive); never treat these as desync.
+ */
+export function detectCursorDesync(buf, cursor) {
+	if (!cursor) return "unknown";
+	const line = buf.getLine(cursor.row);
+	if (!line) return "unknown";
+	let x = cursor.col;
+	let cell = line.getCell(x);
+	while ((!cell || cell.getWidth() === 0) && x > 0) {
+		x--;
+		cell = line.getCell(x);
+	}
+	if (!cell) return "misaligned";
+	return cell.isInverse() ? "aligned" : "misaligned";
+}