@zhuxixi/pi-agent-board 0.6.2 → 0.8.0

package/src/ui/pty-attach.ts

@@ -5,12 +5,12 @@ import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
 import { createConnection, type Socket } from "node:net";
 import type { Component, KeybindingsManager, TUI } from "@earendil-works/pi-tui";
 import { CURSOR_MARKER, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { isProbablyEmptyPiInputLine, isProbablyPiInputLine, resolveEditorEmpty } 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 { createAttachOutputRenderScheduler, detectCursorDesync, isPtyCursorHidden, nextAttachRender, projectPtyCursor, shouldScheduleAttachRenderForMessage } from "../core/pty-attach-render.mjs";
 import { evaluateAttachReconnect, shouldEscapeAttach } from "../core/pty-attach-reconnect.mjs";
 import { installImeCursorCoalesce } from "../core/ime-cursor-coalesce.mjs";
 import { createJiggleRetryController } from "../core/pty-attach-jiggle-controller.mjs";
+import { createTerminalAttachClient } from "../core/terminal-attach-client.mjs";
 import { clampInt, parseMouseInputChunk, resolveWheelLines, scrollViewportTop, selectionDragScrollLines } from "../core/pty-scroll.mjs";
 
 export type PtyAttachResult = { action: "detached" } | { action: "closed"; exitCode?: number | null };
@@ -40,8 +40,24 @@ const LOADING_TICK_MS = 120;
 const ATTACH_SETTLE_MS = 250;
 /** Hard cap on the attach transition so a silent session can't stall the banner. */
 const ATTACH_HARD_TIMEOUT_MS = 2500;
+/** Protocol-race guard for legacy jiggle arming (issue #91 phase 4): the
+ * undecided window must not pulse the child before the snapshot probe
+ * resolves — a resize-free attach is the protocol-mode contract. Invisible
+ * for legacy (the probe timeout decides at 1500ms ≫ 100ms) and the protocol
+ * answer (~ms) reliably beats it; a pathologically late snapshot merely costs
+ * one harmless shrink pulse that the protocol mode event unwinds. */
+const LEGACY_JIGGLE_ARM_DELAY_MS = 100;
 /** Give ordered detach packets time to flush before using destroy as a fallback. */
 const GRACEFUL_SOCKET_CLOSE_MS = 1000;
+/** Desync detection window: how long output must stay silent before a
+ * misaligned cursor counts as desync (issue #11). Streaming keeps the cursor
+ * on plain output cells legitimately; a healthy idle child re-parks it on the
+ * inverse fake-cursor cell on its last rendered frame. */
+const DESYNC_QUIET_MS = 1500;
+/** How often the post-settle probe runs checkDesync() (issue #11). */
+const DESYNC_PROBE_INTERVAL_MS = 2000;
+/** Minimum spacing between two runtime heals (issue #11). */
+const HEAL_RATELIMIT_MS = 10000;
 /** How many tail bytes of the screen log to replay on attach. Read from the file tail
  * (not the whole file) so multi-MB logs don't block startup; ~60KB covers the last
  * handful of screens, which is all a fresh attach needs. */
@@ -57,6 +73,9 @@ const ITERM2_FILE_PREFIX = "\x1b]1337;File=";
 interface XtermLike {
 	write(data: string, cb?: () => void): void;
 	resize(cols: number, rows: number): void;
+	// Full buffer wipe (@xterm/headless Terminal.reset): the attach client's
+	// "empty/resnapshot → UI resets its buffer" contract (phase 4, F3).
+	reset(): void;
 	buffer: {
 		active: {
 			baseY: number;
@@ -68,6 +87,7 @@ interface XtermLike {
 		};
 	};
 	_core?: {
+		coreService?: { isCursorHidden?: boolean };
 		_oscLinkService?: {
 			getLinkData?: (id: number) => { uri?: string } | undefined;
 			_dataByLinkId?: Map<number, { data?: { uri?: string } }>;
@@ -133,6 +153,21 @@ export class PtyAttachComponent implements Component {
 		},
 		clearTimeoutFn: (t) => clearTimeout(t as ReturnType<typeof setTimeout>),
 	});
+	// Snapshot+subscribe attach client (issue #91 phase 4, D2). Created ONCE —
+	// reconnects re-point send at the CURRENT socket (this.send routes through
+	// this.socket) and resume from the applied cursor; wiring shape per the
+	// verified reference in test/terminal-snapshot.integration.test.mjs
+	// (wireClient). AGENT_BOARD_TERMINAL_SNAPSHOT=0 forces the legacy path
+	// (escape hatch + deterministic legacy tests).
+	private readonly attachClient = createTerminalAttachClient({
+		send: (msg) => this.send(msg),
+		emit: (event, payload) => this.handleAttachEvent(event, payload),
+	});
+	/** Decided attach path: "undecided" until the probe resolves (snapshot
+	 * begin → protocol; probe timeout / version mismatch → legacy). Gates
+	 * jiggle arming and probe-vs-cursor reconnects. */
+	private attachMode: "undecided" | "protocol" | "legacy" = "undecided";
+	private jiggleStartTimer: ReturnType<typeof setTimeout> | null = null;
 	private osc52Carry = "";
 	private passthroughCarry = "";
 	private readonly connectStartedAt = Date.now();
@@ -150,6 +185,13 @@ export class PtyAttachComponent implements Component {
 	private rows = 24;
 	// Absolute buffer line shown at the top of the viewport. null means follow bottom.
 	private viewportTop: number | null = null;
+	// Runtime desync backstop state (issue #11): last socket-output timestamp,
+	// last heal timestamp, the probe timer, and an injectable clock for tests.
+	private lastOutputAt = 0;
+	private lastHealAt = 0;
+	private desyncProbeTimer: ReturnType<typeof setInterval> | null = null;
+	/** Injectable clock for desync gating (tests override this). */
+	private nowFn: () => number = () => Date.now();
 	private selection: MouseSelection | null = null;
 	private selectionDragging = false;
 	private selectionAutoScrollTimer: ReturnType<typeof setInterval> | null = null;
@@ -159,7 +201,8 @@ export class PtyAttachComponent implements Component {
 	private lastClickPoint: MousePoint | null = null;
 	private lastClickAt = 0;
 	/** Authoritative editor emptiness pushed by the child Pi extension via the
-	 * control socket (issue #68). null = unknown — fall back to the heuristic. */
+	 * control socket (issue #68). null = unknown — forward conservatively
+	 * (spec §D1); only true detaches. */
 	private editorEmpty: boolean | null = null;
 	// Whether any PTY output (live or replayed) has been shown yet. Until then we paint a
 	// loading banner instead of an empty buffer so a slow (cold) host start doesn't leave
@@ -259,7 +302,15 @@ export class PtyAttachComponent implements Component {
 			// escape unconditionally — the view must always be exitable, even
 			// after the host crashes mid-output (issue #48). Note: ctrl+] is NOT
 			// a detach key — it passes through to Pi (tui.editor.jumpForward).
-			if (shouldEscapeAttach(this.connected, resolveEditorEmpty(this.editorEmpty, this.childInputLooksEmpty()))) {
+			// Issue #91 Phase 6 (spec §D1): the gate reads ONLY the pushed
+			// editorEmpty side channel — true detaches; false and null (child
+			// extension missing, hello not yet arrived, old runner) forward via
+			// the explicit conservative policy. The old terminal-buffer
+			// heuristics are deleted for good: rendered bytes carry no
+			// input-buffer semantics, so that chain guessed at a fact it
+			// could not know (issues #42/#66/#69/#103). Escape without a pushed
+			// state is Ctrl+← (issue #89), never a buffer guess.
+			if (shouldEscapeAttach(this.connected, this.editorEmpty === true)) {
 				this.detach();
 				return;
 			}
@@ -289,7 +340,7 @@ export class PtyAttachComponent implements Component {
 		}
 		const header =
 			this.theme.fg("accent", this.theme.bold(` ${this.opts.title} `)) +
-			this.theme.fg("muted", `${this.status} · click opens links · dblclick/drag selects+copies · ←/Ctrl+← detach`);
+			this.theme.fg("muted", `${this.status} · click opens links · dblclick/drag selects+copies · Ctrl+← detach`);
 		return [clip(header, width), ...body.map((l) => clipTerminalLine(l, width)), this.theme.fg("dim", "─".repeat(width))];
 	}
 
@@ -305,7 +356,7 @@ export class PtyAttachComponent implements Component {
 		out.push(center(this.theme.fg("accent", this.theme.bold(title)), width));
 		out.push(center(this.theme.fg("muted", detail), width));
 		out.push("");
-		out.push(center(this.theme.fg("dim", "←/Ctrl+← to detach"), width));
+		out.push(center(this.theme.fg("dim", "Ctrl+← to detach"), width));
 		while (out.length < height) out.push("");
 		return out.slice(0, height);
 	}
@@ -328,60 +379,15 @@ export class PtyAttachComponent implements Component {
 		// the socket immediately after receiving detach, so sending detach first
 		// can drop the G3 restore resize (issue #42).
 		this.jiggleRetry.restoreAndStop();
-		this.send({ type: "detach" });
+		// Phase 5 (D4): enveloped detach (correlated applied ack) with legacy
+		// fallback; both reach the same runner detach handler.
+		if (!this.attachClient.sendControl("detach")) {
+			this.send({ type: "detach" });
+		}
 		this.close(true);
 		this.done({ action: "detached" });
 	}
 
-	/** Bottom-most line whose cells include an inverse-video cell — Pi renders
-	 * its editor cursor as an inverse "fake cursor" (`ESC[7m`), and the cell
-	 * persists in the buffer even while streaming differential frames skip
-	 * repainting the editor line. */
-	private findLastInverseCellLine(active: {
-		baseY: number;
-		length: number;
-		getLine(index: number): BufferLineLike | undefined;
-	}): number | null {
-		for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
-			const line = active.getLine(y);
-			if (!line) continue;
-			for (let x = 0; x < line.length; x++) {
-				if (line.getCell(x)?.isInverse()) return y;
-			}
-		}
-		return null;
-	}
-
-	private childInputLooksEmpty(): boolean {
-		if (!this.receivedOutput) return true;
-		const active = this.term.buffer.active;
-		// The terminal cursor is not a reliable anchor for the editor line:
-		// while Pi streams output (or right after attach) the cursor rests on
-		// working/output lines, never the input line, so a genuinely empty
-		// editor was misread as non-empty and ← stopped detaching (issue #66).
-		// Pi's editor line always carries an inverse-video fake-cursor cell,
-		// so anchor on that instead.
-		const fakeCursorLine = this.findLastInverseCellLine(active);
-		if (fakeCursorLine !== null) {
-			const line = active.getLine(fakeCursorLine)?.translateToString(true) ?? "";
-			return isProbablyEmptyPiInputLine(line);
-		}
-		// Fallback: Pi variants that render no fake cursor — look for an EMPTY
-		// prompt-glyph line. 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
-		// them and keep scanning; the loop-end escape below stays authoritative.
-		for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
-			const line = active.getLine(y)?.translateToString(true) ?? "";
-			if (isProbablyPiInputLine(line) && isProbablyEmptyPiInputLine(line)) return true;
-		}
-		// No editor line recoverable (e.g. a garbled replay buffer): treat the
-		// input as empty — ← is the only detach key left on the attach surface,
-		// so it must always escape rather than trap the user.
-		return true;
-	}
-
 	private connect(): void {
 		if (this.closed || this.connected || this.socket) return;
 		// On Windows the control socket is a named pipe — it never exists as a
@@ -408,7 +414,18 @@ export class PtyAttachComponent implements Component {
 			this.disconnectedAt = null;
 			this.status = "attached";
 			this.send({ type: "hello", clientId: `ui-${Date.now()}`, wantOutput: true });
-			this.jiggleRetry.start(this.cols, this.rows);
+			// Snapshot+subscribe attach (issue #91 phase 4): the first connect
+			// probes with subscribe_terminal (old runners stay silent → probe
+			// timeout → legacy); protocol reconnects resume from the applied
+			// cursor over the SAME client instance (ring replay is seamless;
+			// eviction/restart answers a fresh snapshot). hello stays UI-owned
+			// and precedes the client's subscribe (established ordering).
+			if (this.attachMode === "undecided") this.attachClient.start();
+			else if (this.attachMode === "protocol") this.attachClient.reconnect(this.attachClient.getLastSeq());
+			// The shrink-and-hold redraw protocol is a LEGACY-path correctness
+			// tool: snapshot mode owns screen correctness via canonical frames,
+			// so the jiggle never runs there (armLegacyJiggle guards the race).
+			this.armLegacyJiggle();
 			this.enableMouseScroll();
 			this.scheduleRender();
 			this.startAttachSettle();
@@ -424,6 +441,11 @@ export class PtyAttachComponent implements Component {
 			this.socket = null;
 			this.connected = false;
 			this.disconnectedAt ??= Date.now();
+			// A drop inside the probe window must not leave the absolute 1500ms
+			// deadline armed: firing during the dead window would permanently
+			// downgrade a protocol-capable runner to legacy (CR R1 advisory). The
+			// reconnect's start()/reconnect() re-arms on the new socket.
+			this.attachClient.onDisconnect();
 			if (!this.closed && this.status !== "host exited") {
 				this.status = "disconnected";
 				this.scheduleReconnect();
@@ -439,6 +461,10 @@ export class PtyAttachComponent implements Component {
 			}
 			this.socket = null;
 			this.connected = false;
+			// Notify before nulling: the close event that follows will hit the
+			// stale-socket guard (this.socket no longer matches) and must not be
+			// the only path that cancels the probe deadline (CR R1 advisory).
+			this.attachClient.onDisconnect();
 			try { socket.destroy(); } catch {}
 			this.disconnectedAt ??= Date.now();
 			if (this.closed) return;
@@ -541,6 +567,55 @@ export class PtyAttachComponent implements Component {
 		// Force a full clear so the loading banner is replaced atomically by the settled
 		// buffer, instead of diffing banner lines into buffer lines.
 		this.scheduleRender(true);
+		this.startDesyncProbe();
+	}
+
+	private startDesyncProbe(): void {
+		this.stopDesyncProbe();
+		// The probe is deliberately NOT hooked into the render path: rendering is
+		// event-driven (socket output / keypress / resize) and stops exactly when
+		// desync strikes (output goes quiet). A self-contained timer is the only
+		// way an idle desynced screen gets its self-heal without user action.
+		this.desyncProbeTimer = setInterval(() => this.checkDesync(), DESYNC_PROBE_INTERVAL_MS);
+		this.desyncProbeTimer.unref?.();
+	}
+
+	private stopDesyncProbe(): void {
+		if (this.desyncProbeTimer) {
+			clearInterval(this.desyncProbeTimer);
+			this.desyncProbeTimer = null;
+		}
+	}
+
+	/**
+	 * Runtime desync backstop (issue #11). Seven gates, cheapest first:
+	 * settled+connected, child is a TUI (frame seen), chain idle, output quiet,
+	 * heal rate limit, misaligned cursor. All pass → heal() re-arms
+	 * shrink-and-hold; the child's fullRender clear then restores the size
+	 * and repaints a consistent screen.
+	 */
+	private checkDesync(): void {
+		if (this.closed || this.attaching || !this.connected) return; // gates 1, 7
+		// Protocol mode owns screen correctness via canonical frames (issue #91
+		// phase 4, CR R1 advisory): a "misaligned cursor" there is frame content
+		// or a stale-frame transient that resync heals — a jiggle heal would fire
+		// resize pulses in a mode whose e2e pins zero resizes. The undecided
+		// window keeps legacy semantics on purpose: until the snapshot answer
+		// arrives the jiggle IS armed and the legacy fallthrough owns the screen.
+		if (this.attachMode === "protocol") return;
+		const chain = this.jiggleRetry.getState();
+		if (!chain.tuiFrameSeen) return; // gate 2: shell/vim children never heal
+		if (!chain.stopped || chain.held) return; // gate 5: attach/heal chain active
+		const now = this.nowFn();
+		if (now - this.lastOutputAt <= DESYNC_QUIET_MS) return; // gate 4: streaming
+		if (now - this.lastHealAt <= HEAL_RATELIMIT_MS) return; // gate 6: rate limit
+		const height = this.bodyHeight();
+		this.clampViewportTop(height);
+		const start = this.viewportTop ?? this.bottomViewportTop(height);
+		const buf = this.term.buffer.active;
+		if (detectCursorDesync(buf, projectPtyCursor(buf, start, height)) !== "misaligned") return; // gate 3
+		this.lastHealAt = now;
+		this.jiggleRetry.heal(this.cols, this.rows);
 	}
 
 	private clearMouseRefreshTimers(): void {
@@ -548,6 +623,37 @@ export class PtyAttachComponent implements Component {
 		this.mouseRefreshTimers = [];
 	}
 
+	/**
+	 * Legacy-path jiggle arming with a protocol-race guard (issue #91 phase 4).
+	 * Legacy decided immediately (env-forced) → start now; undecided → start
+	 * after the guard delay unless the snapshot answer wins (protocol). The
+	 * timer guard accepts ANY non-protocol mode, so a fast in-flight decision
+	 * (e.g. frame_version_mismatch landing ~1ms into the probe window) still
+	 * arms the chain — an early-decided legacy session must not end up
+	 * jiggle-less. start() re-arms idempotently, so a late duplicate is safe.
+	 */
+	private armLegacyJiggle(): void {
+		this.clearJiggleStartTimer();
+		if (this.attachMode === "protocol") return;
+		if (this.attachMode === "legacy") {
+			if (this.connected) this.jiggleRetry.start(this.cols, this.rows);
+			return;
+		}
+		this.jiggleStartTimer = setTimeout(() => {
+			this.jiggleStartTimer = null;
+			if (!this.closed && this.connected && this.attachMode !== "protocol") {
+				this.jiggleRetry.start(this.cols, this.rows);
+			}
+		}, LEGACY_JIGGLE_ARM_DELAY_MS);
+		this.jiggleStartTimer.unref?.();
+	}
+
+	private clearJiggleStartTimer(): void {
+		if (!this.jiggleStartTimer) return;
+		clearTimeout(this.jiggleStartTimer);
+		this.jiggleStartTimer = null;
+	}
+
 	private clearRetry(): void {
 		if (!this.retryTimer) return;
 		clearTimeout(this.retryTimer);
@@ -915,7 +1021,13 @@ export class PtyAttachComponent implements Component {
 	}
 
 	private sendResize(cols = this.cols, rows = this.rows): void {
-		this.send({ type: "resize", cols, rows });
+		// Phase 5 (D4): enveloped resize when the host has an instance fence
+		// (correlated applied/superseded acks; starting-window host_starting is
+		// retried client-side); legacy plain message otherwise. Both paths reach
+		// the same runner resize handler.
+		if (!this.attachClient.sendControl("resize", { cols, rows })) {
+			this.send({ type: "resize", cols, rows });
+		}
 		this.clampViewportTop(this.bodyHeight());
 	}
 
@@ -987,6 +1099,12 @@ export class PtyAttachComponent implements Component {
 			if (!line.trim()) continue;
 			try {
 				const msg = JSON.parse(line);
+				// Protocol-managed messages (snapshot windows, seq-checked live
+				// output, recovery) are consumed by the attach client and re-emitted
+				// through handleAttachEvent. UI-owned messages (hello/status/
+				// editor_state/exit/error) and pre-decision broadcast output return
+				// false and fall through to the legacy path below.
+				if (this.attachClient.handleMessage(msg)) continue;
 				if (msg.type === "output" && typeof msg.data === "string") {
 					this.pushOutput(msg.data, { forwardProtocols: true });
 					this.checkClearSequence(msg.data);
@@ -1009,6 +1127,95 @@ export class PtyAttachComponent implements Component {
 		if (needsRender) this.scheduleRender();
 	}
 
+	/**
+	 * Attach-client events (issue #91 phase 4). The client owns protocol
+	 * recovery (it resubscribes internally); the UI only switches paths and
+	 * hydrates frames.
+	 */
+	private handleAttachEvent(
+		event: "mode" | "snapshotBegin" | "snapshotReady" | "output" | "resubscribing" | "protocolError" | "cmdAck" | "reconciled" | "epochReset",
+		payload: any,
+	): void {
+		if (event === "mode") {
+			const prev = this.attachMode;
+			this.attachMode = payload as "protocol" | "legacy";
+			if (this.attachMode === "protocol") {
+				// Snapshot mode owns screen correctness: cancel any pending legacy
+				// jiggle arming and unwind anything already armed (restores a held
+				// resize; no-ops otherwise).
+				this.clearJiggleStartTimer();
+				this.jiggleRetry.restoreAndStop();
+			} else if (prev === "protocol") {
+				// Downgrade after a protocol session (recovery budget exhausted):
+				// re-arm the legacy screen-healing machinery. This must run whenever
+				// the socket is alive — not only during the attach transition. A
+				// post-settle downgrade that skipped start() left the chain stopped
+				// forever (restoreAndStop on the protocol side), so feed() early-
+				// returned and raw output could never heal a desynced screen.
+				this.clearJiggleStartTimer();
+				if (this.connected) this.jiggleRetry.start(this.cols, this.rows);
+			}
+			// Legacy decided during the undecided window: the race-guard timer
+			// already fired at 100ms (≪ the 1500ms probe timeout) — nothing to do.
+			return;
+		}
+		if (event === "snapshotBegin") {
+			// Protocol attach size-sync (CR R1 blocking): the legacy attach resized
+			// the child at every connect (jiggle start); subscribe_terminal carries
+			// no size, so without this the child keeps its host-creation geometry
+			// and full-screen TUI children lay out at a stale size. begin is
+			// authoritative for the runner's CURRENT size; the in-flight frame stays
+			// old-geometry either way, but resizing now starts the child's redraw at
+			// the true size sooner. Matched sizes send nothing (zero-resize
+			// contract for same-size attach stays intact).
+			const beginSize = (payload ?? {}) as { cols?: number; rows?: number };
+			if (
+				typeof beginSize.cols === "number" &&
+				typeof beginSize.rows === "number" &&
+				(beginSize.cols !== this.cols || beginSize.rows !== this.rows)
+			) {
+				this.sendResize();
+			}
+			return;
+		}
+		if (event === "snapshotReady") {
+			const snap = (payload ?? {}) as { frame?: string; empty?: boolean; resnapshot?: boolean };
+			// The synthesized frame is self-contained on dirty terminals (phase 3
+			// torture-proven: DECSTR + clear preamble wipes the constructor
+			// screen.log replay and any pre-probe broadcast bytes), so hydrating is
+			// a plain push: the write callback drives receivedOutput/settle/render
+			// exactly like the legacy replay path. No protocol forwarding — the
+			// frame is runner-synthesized grid content, not child passthrough
+			// sequences. Empty baselines (the COMMON initial attach state: the host
+			// publishes alive+childPid before the child's first output) carry no
+			// frame; the loading banner persists until the first live output.
+			// Empty/resnapshot answers ALWAYS wipe the local buffer, attaching or
+			// not: while attaching the banner hides it (zero visual cost), and the
+			// constructor's screen.log warm-start must not outlive the protocol
+			// answer — a gated reset let the dead session's tail render as a
+			// cold-start ghost once the banner lifted (final-review F1).
+			if (typeof snap.frame === "string") this.pushOutput(snap.frame);
+			else if (snap.empty || snap.resnapshot) this.term.reset();
+			return;
+		}
+		if (event === "output") {
+			// Live/replay protocol output: no jiggle clear-detection — that feed
+			// exists to cancel the shrink-and-hold chain, which never runs in
+			// protocol mode.
+			if (typeof payload === "string") this.pushOutput(payload, { forwardProtocols: true });
+			return;
+		}
+		// "resubscribing": recovery is client-internal (informational only).
+		// "protocolError": observability only — recovery is automatic until the
+		// legacy fallback, whose mode event the UI acts on above.
+		// "cmdAck"/"reconciled"/"epochReset" (phase 5): correlation/observability
+		// only — applied/superseded bookkeeping, reconcile baselines and the
+		// generation epoch rule live inside the client; the UI's behavioral
+		// surface (hydrate, mode switching, size-sync) is unchanged. host_starting
+		// resize retries are also client-internal (parity with the legacy runner-
+		// side cachedResize).
+	}
+
 	private forwardTerminalProtocols(data: string): void {
 		const toWrite: string[] = [];
 		if (process.env.AGENT_BOARD_FORWARD_OSC52 !== "0") {
@@ -1030,6 +1237,15 @@ export class PtyAttachComponent implements Component {
 		}
 	}
 
+	/** LEGACY FALLBACK (issue #91 phase 6 marking): the screen.log tail replay
+	 * is kept only for pre-protocol runners and the
+	 * AGENT_BOARD_TERMINAL_SNAPSHOT=0 kill switch. It is NOT a correctness
+	 * path of the snapshot+subscribe protocol — the protocol hydrates from
+	 * runner-owned snapshots and resumes from a sequence cursor (phase 4),
+	 * and this replay runs before the probe resolves. Removal condition: the
+	 * installed runner fleet is on the snapshot protocol baseline
+	 * (wire-detectable via hello protocol fields).
+	 */
 	private replayScreenLog(): void {
 		if (!this.opts.screenLogPath || !existsSync(this.opts.screenLogPath)) return;
 		try {
@@ -1060,6 +1276,9 @@ export class PtyAttachComponent implements Component {
 
 	private pushOutput(data: string, opts: { forwardProtocols?: boolean } = {}): void {
 		if (data.length === 0) return;
+		// Recorded synchronously BEFORE term.write (whose callback is async): the
+		// desync quiet-window must measure when output ARRIVED, not when parsing finished.
+		this.lastOutputAt = this.nowFn();
 		if (opts.forwardProtocols) this.forwardTerminalProtocols(data);
 		// @xterm/headless parses asynchronously; the buffer is only populated once this
 		// callback fires. Mark the buffer as ready (so the project path can paint it), but
@@ -1086,8 +1305,9 @@ export class PtyAttachComponent implements Component {
 		// the child terminal); cursorX may equal cols (one past the last cell). Only render
 		// it when it lands inside the projected viewport.
 		const cursor = projectPtyCursor(buf, start, height);
+		const cursorHidden = isPtyCursorHidden(this.term);
 		for (let i = start; i < end; i++) {
-			out.push(lineToAnsi(buf.getLine(i), reusable, this.term, i, selection, cursor));
+			out.push(lineToAnsi(buf.getLine(i), reusable, this.term, i, selection, cursor, cursorHidden));
 		}
 		if (out.length === 0) out.push("Waiting for PTY output…");
 		return { lines: out.slice(-height), cursor };
@@ -1102,6 +1322,7 @@ export class PtyAttachComponent implements Component {
 		}
 		this.closed = true;
 		this.imeCoalesceUninstall?.();
+		this.attachClient.close();
 		this.jiggleRetry.restoreAndStop();
 		this.disableMouseScroll();
 		this.clearMouseRefreshTimers();
@@ -1110,6 +1331,7 @@ export class PtyAttachComponent implements Component {
 		this.clearRetry();
 		this.stopLoadingTicker();
 		this.outputRenderScheduler.dispose();
+		this.stopDesyncProbe();
 		if (this.attachSettleTimer) {
 			clearTimeout(this.attachSettleTimer);
 			this.attachSettleTimer = null;
@@ -1218,12 +1440,14 @@ function lineToAnsi(
 	lineIndex: number,
 	selection: NormalizedSelection | null,
 	cursor: { row: number; col: number } | null,
+	cursorHidden = false,
 ): string {
 	const isCursorRow = cursor !== null && cursor.row === lineIndex;
 	let last = -1;
 	if (!line) {
-		// No buffer line: show the cursor as an inverse block at the start of the line.
-		if (isCursorRow && cursor!.col >= 0) return CURSOR_MARKER + "\x1b[7m \x1b[0m";
+		// No buffer line: keep the marker (IME positioning) and paint the inverse block
+		// only while the child reports a visible cursor.
+		if (isCursorRow && cursor!.col >= 0) return cursorHidden ? CURSOR_MARKER : CURSOR_MARKER + "\x1b[7m \x1b[0m";
 		return "";
 	}
 	for (let x = 0; x < line.length; x++) {
@@ -1232,9 +1456,8 @@ function lineToAnsi(
 		if (cell.getChars()) last = x;
 	}
 	if (last < 0) {
-		// Empty line: show the cursor as a full inverse block at the start of the line
-		// (or as an inverse space when it sits past the end of the content).
-		if (isCursorRow && cursor!.col >= 0) return CURSOR_MARKER + "\x1b[7m \x1b[0m";
+		// Empty line: same split as above.
+		if (isCursorRow && cursor!.col >= 0) return cursorHidden ? CURSOR_MARKER : CURSOR_MARKER + "\x1b[7m \x1b[0m";
 		return "";
 	}
 
@@ -1251,24 +1474,27 @@ function lineToAnsi(
 			prevUri = uri;
 		}
 		const selected = pointWithinSelection(lineIndex, x, selection);
-		// The PTY cursor renders as a solid inverse block so it stays visible even though
-		// the outer TUI hides the hardware cursor by default. The zero-width CURSOR_MARKER
-		// (stripped by the TUI) additionally positions the hardware cursor for IME and
-		// PI_HARDWARE_CURSOR=1 terminals; truncateToWidth keeps or drops it with the cell.
+		// Position and visibility are separate concerns: the zero-width CURSOR_MARKER
+		// (stripped by the TUI) always marks where the hardware cursor belongs for IME
+		// and PI_HARDWARE_CURSOR=1 terminals, while the solid inverse block is only
+		// painted when the child terminal itself reports the cursor as visible. pi-tui
+		// parks a hidden cursor at a diff-write byproduct position, so painting it
+		// unconditionally showed a ghost block (issue #102).
 		const isCursor = isCursorRow && x === cursor!.col;
 		if (isCursor) out += CURSOR_MARKER;
-		const key = attrKey(cell, selected, isCursor);
+		const paintCursor = isCursor && !cursorHidden;
+		const key = attrKey(cell, selected, paintCursor);
 		if (key !== prevAttr) {
-			out += attrsToAnsi(cell, selected, isCursor);
+			out += attrsToAnsi(cell, selected, paintCursor);
 			prevAttr = key;
 		}
 		out += cell.getChars() || " ";
 	}
 	if (prevUri) out += closeOsc8();
 	// Cursor past the end of the line content (cursorX == cols or beyond last cell):
-	// append an inverse space so the position is still visible.
+	// append an inverse space so a VISIBLE position shows, keeping the marker either way.
 	if (isCursorRow && cursor!.col > last) {
-		out += CURSOR_MARKER + "\x1b[7m \x1b[0m";
+		out += CURSOR_MARKER + (cursorHidden ? "" : "\x1b[7m \x1b[0m");
 	}
 	return out + "\x1b[0m";
 }

package/src/core/pty-input.mjs

@@ -1,47 +0,0 @@
-/** Helpers for deciding whether local attach shortcuts should be handled. */
-
-/**
- * Best-effort detection of Pi's empty prompt/input line from projected terminal text.
- * The attach surface must not steal editing keys (notably ←) while the child Pi editor
- * contains text. Pi renders empty editor lines with prompt/continuation glyphs such as
- * `›`, `┃`, or `│`; once user text is present, non-prompt content remains after this trim.
- * @param {string} line
- * @returns {boolean}
- */
-export function isProbablyEmptyPiInputLine(line) {
-	const withoutRightPadding = String(line || "").replace(/[\s\u00a0]+$/u, "");
-	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;
-}