@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,356 @@
+/**
+ * LEGACY FALLBACK (issue #91 phase 6 marking): the shrink-and-hold jiggle is
+ * kept only for pre-protocol runners and the AGENT_BOARD_TERMINAL_SNAPSHOT=0
+ * kill switch. It is NOT a success condition of the snapshot+subscribe
+ * protocol path — the protocol re-baselines the view from runner-owned
+ * snapshots (phase 4), and jiggle arming is skipped once the probe resolves
+ * to the protocol attach mode. Removal condition: the installed runner fleet
+ * is on the snapshot protocol baseline (wire-detectable via hello protocol
+ * fields).
+ *
+ * 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 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
+ * net-zero size change.
+ *
+ * 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).
+ *   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. 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,
+	feedOutput,
+	nextRetryDelay,
+	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;
+/**
+ * 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;
+
+/** 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.
+ * @property {(fn: () => void, ms: number) => unknown} setTimeoutFn - Timer factory.
+ * @property {(timer: unknown) => void} clearTimeoutFn - Timer canceller.
+ */
+
+/**
+ * @param {JiggleRetryControllerDeps} deps
+ */
+export function createJiggleRetryController(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;
+	/** 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} */
+	let g1Timer = null;
+	/** Runtime heals spent (issue #11); never reset by start()/restoreAndStop(). */
+	let healCount = 0;
+
+	function clearChainTimer() {
+		if (chainTimer === null) return;
+		clearTimeoutFn(chainTimer);
+		chainTimer = null;
+	}
+
+	function clearG1Timer() {
+		if (g1Timer === null) return;
+		clearTimeoutFn(g1Timer);
+		g1Timer = null;
+	}
+
+	function clearAllTimers() {
+		clearChainTimer();
+		clearG1Timer();
+	}
+
+	/**
+	 * 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;
+	}
+
+	/**
+	 * 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) {
+			state = stopRetry(state);
+			restoreIfHeld(); // G2
+			return;
+		}
+		chainTimer = setTimeoutFn(tickChain, delay);
+	}
+
+	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;
+		originalCols = cols;
+		originalRows = rows;
+		holdSize = resizeJiggleSize(cols, rows);
+		sendResize(cols, rows);
+		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();
+		scheduleNextRetry();
+	}
+
+	/**
+	 * Feed one socket output chunk. A clear wins over the re-arm when both
+	 * 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
+	 * (a live fullRender chunk bundles a frame start with its clear, 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
+	 * child still sees a width delta (F1 slow-boot probe).
+	 * Terminal chain states still learn frame cognition from later output
+	 * (issue #106) — cognition only; re-opening the protocol stays heal()'s job.
+	 * @param {string} data
+	 */
+	function feed(data) {
+		// Terminal chain states: a clear was seen (chain done) or the chain ended
+		// (G2/G3/G4). Output no longer drives the retry protocol — but frame
+		// cognition must still be learned from it (issue #106): a TUI whose first
+		// frame lands after the chain settled must still open the runtime desync
+		// backstop's gate 2 (issue #11), otherwise heal() stays unreachable for the
+		// rest of this connection. Cognition only — no timers, no resizes, and no
+		// retry-state change: re-opening the protocol is heal()'s job (rate-limited
+		// and lifetime-capped), not an output chunk's.
+		if (state.clearDetected || state.stopped) {
+			if (tuiFrameSeen) return; // latched already — nothing left to learn
+			const terminal = feedOutput(state, data, carry);
+			carry = terminal.carry; // keep cross-chunk marker detection intact
+			if (terminal.frameStartFound) tuiFrameSeen = true;
+			return;
+		}
+		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 (firstFrame) {
+			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.
+				if (holdSize) sendResize(holdSize.cols, holdSize.rows);
+				held = holdSize !== null;
+				restored = false;
+			}
+		}
+	}
+
+	/**
+	 * 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).
+	 */
+	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;
+		holdSize = null;
+		state = stopRetry(state);
+	}
+
+	return {
+		start,
+		feed,
+		heal,
+		restoreAndStop,
+		notifyExternalResize,
+		getState: () => ({ ...state, held, tuiFrameSeen, originalCols, originalRows, holdSize, healCount }),
+	};
+}

package/packages/board/src/core/pty-attach-jiggle-retry.mjs

@@ -0,0 +1,109 @@
+/** Pure logic for attach jiggle-retry: detect full-clear, schedule backoff retries. */
+
+export const BACKOFF_MS = Object.freeze([120, 500, 1500, 3000, 6000, 10000, 15000, 20000]);
+export const MAX_RETRIES = BACKOFF_MS.length;
+
+// Verified empirically in issue #2: a resize jiggle makes the child pi-tui run
+// fullRender(true), whose output begins with a full clear — a controlled test
+// against a live idle session received 2 clear sequences + ~920KB full repaint
+// per jiggle. So \x1b[2J in the socket output is a reliable "jiggle landed"
+// signal. If pi-tui ever changes fullRender to skip the clear, the detector
+// silently degrades to the old one-shot behavior after MAX_RETRIES.
+const FULL_CLEAR = "\x1b[2J";
+// pi-tui begins every frame (including differential frames) with a synchronized
+// output start sequence; boot-time extension output never contains it, so the
+// first occurrence marks "child TUI has started rendering" (issue #10).
+const TUI_FRAME_START = "\x1b[?2026h";
+/** Carry enough bytes to catch either target sequence split at a chunk boundary. */
+const CARRY_LEN = TUI_FRAME_START.length - 1; // 7 bytes
+
+/**
+ * @typedef {Object} JiggleRetryState
+ * @property {number} retryIndex - Current retry round (0 = initial, not yet retried).
+ * @property {boolean} clearDetected - Whether a full-clear sequence was seen.
+ * @property {boolean} stopped - Whether the retry chain has been stopped.
+ */
+
+/** Create initial retry state. */
+export function createJiggleRetryState() {
+	return { retryIndex: 0, clearDetected: false, stopped: false };
+}
+
+/**
+ * Feed PTY output data into the state machine.
+ * Returns new state, updated carry buffer, and which target sequences were found.
+ * @param {JiggleRetryState} state
+ * @param {string} data - New output data chunk.
+ * @param {string} carry - Leftover partial escape sequence from previous chunk.
+ * @returns {{ state: JiggleRetryState, carry: string, clearFound: boolean, frameStartFound: boolean }}
+ */
+export function feedOutput(state, data, carry) {
+	const combined = carry + data;
+	const clearFound = hasFullClearSequence(combined);
+	const frameStartFound = hasTuiFrameStart(combined);
+	// Always keep the tail carry: a clear hit stops the chain (carry irrelevant), and
+	// a frame-start hit must still preserve a trailing half-sequence so an immediately
+	// following clear split across the next chunk is not missed.
+	const newCarry = tailCarry(combined);
+	const newState = clearFound ? { ...state, clearDetected: true } : state;
+	return { state: newState, carry: newCarry, clearFound, frameStartFound };
+}
+
+/**
+ * Get the delay before the next retry, or null if no more retries.
+ * @param {JiggleRetryState} state
+ * @returns {number | null}
+ */
+export function nextRetryDelay(state) {
+	if (state.stopped || state.clearDetected) return null;
+	if (state.retryIndex >= MAX_RETRIES) return null;
+	return BACKOFF_MS[state.retryIndex];
+}
+
+/**
+ * Advance to the next retry round.
+ * @param {JiggleRetryState} state
+ * @returns {JiggleRetryState}
+ */
+export function advanceRetry(state) {
+	return { ...state, retryIndex: state.retryIndex + 1 };
+}
+
+/**
+ * Stop the retry chain (attach settled, component closed, etc.).
+ * @param {JiggleRetryState} state
+ * @returns {JiggleRetryState}
+ */
+export function stopRetry(state) {
+	return { ...state, stopped: true };
+}
+
+/**
+ * Check if data contains the full-clear escape sequence.
+ * @param {string} data
+ * @returns {boolean}
+ */
+export function hasFullClearSequence(data) {
+	return data.includes(FULL_CLEAR);
+}
+
+/**
+ * Check if data contains the TUI frame-start (synchronized output) sequence.
+ * pi-tui begins every frame with \x1b[?2026h; boot-time extension output never
+ * contains it, so the first occurrence marks "child TUI has started rendering".
+ * @param {string} data
+ * @returns {boolean}
+ */
+export function hasTuiFrameStart(data) {
+	return data.includes(TUI_FRAME_START);
+}
+
+/** Extract the tail carry for cross-chunk boundary detection. */
+function tailCarry(data) {
+	// We only need to carry up to CARRY_LEN bytes to catch a split \x1b[2J or
+	// \x1b[?2026h. Find the last \x1b in the tail — everything before it can't be
+	// part of a split escape sequence.
+	const tail = data.slice(-CARRY_LEN);
+	const escIdx = tail.lastIndexOf("\x1b");
+	return escIdx >= 0 ? tail.slice(escIdx) : "";
+}

package/packages/board/src/core/pty-attach-reconnect.mjs

@@ -0,0 +1,61 @@
+/**
+ * Attach reconnect policy (issue #48). The pty-runner can die without sending
+ * an exit message (uncaught crash), which previously left the attach view in a
+ * 150 ms reconnect loop forever with no way out. Two regimes:
+ *  - ever connected: a crashed host is unrecoverable quickly — give up after a
+ *    short window and report "host exited";
+ *  - never connected: the host may still be cold-starting (service launches it
+ *    right before attach) — allow a long window before declaring it unreachable.
+ */
+import { resolveTestMs } from "./test-knobs.mjs";
+
+/** Give-up delay after a previously-established connection drops (ms). */
+export const ATTACH_RECONNECT_TIMEOUT_MS = 15_000;
+/** Give-up delay while waiting for the initial host connection (ms). */
+export const ATTACH_HOST_START_TIMEOUT_MS = 120_000;
+
+/**
+ * Dynamic reader for ATTACH_RECONNECT_TIMEOUT_MS (issue #95 F4): env set after
+ * module load must still reach the reconnect policy, so read per evaluation.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number}
+ */
+export function resolveAttachReconnectTimeoutMs(env = process.env) {
+	return resolveTestMs(env, "AGENT_BOARD_TEST_ATTACH_RECONNECT_TIMEOUT_MS", ATTACH_RECONNECT_TIMEOUT_MS);
+}
+
+/**
+ * @param {{ everConnected: boolean, disconnectedAt: number|null, connectStartedAt: number, now: number }} input
+ * @returns {{ giveUp: boolean, status: string | null }}
+ */
+export function evaluateAttachReconnect({ everConnected, disconnectedAt, connectStartedAt, now }) {
+	if (everConnected && disconnectedAt !== null) {
+		const elapsed = now - disconnectedAt;
+		return elapsed >= resolveAttachReconnectTimeoutMs()
+			? { giveUp: true, status: "host exited" }
+			: { giveUp: false, status: null };
+	}
+	const elapsed = now - connectStartedAt;
+	return elapsed >= ATTACH_HOST_START_TIMEOUT_MS
+		? { giveUp: true, status: "host not reachable" }
+		: { giveUp: false, status: null };
+}
+
+/**
+ * Detach-key policy (issue #91 Phase 6, spec §D1): while the socket is down a
+ * key can never reach the child, so treat ← as "leave the view"
+ * unconditionally; otherwise detach only when the pushed editorEmpty side
+ * channel is exactly true. false and null/undefined mean "forward" — the
+ * explicit conservative policy; callers pass `editorEmpty === true` so an
+ * unknown state can never arm the detach, and no terminal-buffer heuristic is
+ * consulted (the deleted terminal-buffer heuristic family — issues
+ * #42/#66/#69/#103 — stays deleted).
+ * @param {boolean} connected
+ * @param {boolean | null | undefined} editorEmpty
+ * @returns {boolean}
+ */
+export function shouldEscapeAttach(connected, editorEmpty) {
+	// Normalize to a strict boolean: a null/undefined editorEmpty (unknown)
+	// forwards — never escapes — and must not leak through the return value.
+	return !connected || editorEmpty === true;
+}