@zhuxixi/pi-agent-board 0.7.0 → 0.9.0

package/src/ui/pty-attach.ts

@@ -5,12 +5,13 @@ 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, detectCursorDesync, 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 { extractOscQuerySequences, toColorSchemeReport } from "../core/terminal-query-sequences.mjs";
 import { clampInt, parseMouseInputChunk, resolveWheelLines, scrollViewportTop, selectionDragScrollLines } from "../core/pty-scroll.mjs";
 
 export type PtyAttachResult = { action: "detached" } | { action: "closed"; exitCode?: number | null };
@@ -40,6 +41,13 @@ 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
@@ -66,6 +74,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;
@@ -77,6 +88,7 @@ interface XtermLike {
 		};
 	};
 	_core?: {
+		coreService?: { isCursorHidden?: boolean };
 		_oscLinkService?: {
 			getLinkData?: (id: number) => { uri?: string } | undefined;
 			_dataByLinkId?: Map<number, { data?: { uri?: string } }>;
@@ -142,8 +154,24 @@ 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 oscQueryCarry = "";
 	private readonly connectStartedAt = Date.now();
 	// Set once the first socket connect succeeds; drives the reconnect give-up
 	// policy (short window after a live session dies, long window during cold
@@ -175,7 +203,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
@@ -187,6 +216,10 @@ export class PtyAttachComponent implements Component {
 	private attaching = true;
 	private attachSettleTimer: ReturnType<typeof setTimeout> | null = null;
 	private attachHardTimeout: ReturnType<typeof setTimeout> | null = null;
+	// Issue #128 D2: unsubscriber for the color-scheme bridge registered at
+	// attach settle; nulled on every terminal path so the TUI never keeps a
+	// listener pointing at a dead attach surface.
+	private colorSchemeBridgeUnsubscribe: (() => void) | null = null;
 	private gracefulSocketCloseTimer: ReturnType<typeof setTimeout> | null = null;
 	// Force a single full-clear on the first paint so the prior session/dashboard can't
 	// ghost behind this overlay; every later paint uses the TUI's coalesced, throttled,
@@ -260,6 +293,18 @@ export class PtyAttachComponent implements Component {
 			this.send({ type: "input", data });
 			return;
 		}
+		if (matchesKey(data, "ctrl+\\")) {
+			// Unconditional, terminal-independent escape (issue #126): 0x1c is a
+			// single raw ASCII byte every terminal forwards unchanged in raw
+			// mode — no modifier-encoding dependency like Ctrl+Left (macOS
+			// Terminal.app never emits it, WezTerm consumes it for tab
+			// switching). Only caveat (documented in README): layouts where
+			// `\` sits on AltGr may never produce this byte; the escape ladder
+			// still covers those. matchesKey also covers the kitty CSI-u and
+			// modifyOtherKeys encodings of the same chord.
+			this.detach();
+			return;
+		}
 		if (matchesKey(data, Key.ctrl("left"))) {
 			// Explicit detach chord (issue #89): single ← is gated on editor state
 			// (it doubles as cursor-left inside a non-empty draft), so a user with
@@ -275,7 +320,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;
 			}
@@ -305,7 +358,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} · opens links · drag selects+copies · Ctrl+←/Ctrl+\\ detach`);
 		return [clip(header, width), ...body.map((l) => clipTerminalLine(l, width)), this.theme.fg("dim", "─".repeat(width))];
 	}
 
@@ -321,7 +374,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+←/Ctrl+\\ to detach"), width));
 		while (out.length < height) out.push("");
 		return out.slice(0, height);
 	}
@@ -344,60 +397,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
@@ -424,7 +432,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();
@@ -440,6 +459,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();
@@ -455,6 +479,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;
@@ -558,6 +586,56 @@ export class PtyAttachComponent implements Component {
 		// buffer, instead of diffing banner lines into buffer lines.
 		this.scheduleRender(true);
 		this.startDesyncProbe();
+		// Issue #128: the settle transition is the single point where `attaching`
+		// flips false (never re-armed), so both hooks run at most once per attach.
+		this.attachColorSchemeBridge();
+		this.replayBackgroundQuery();
+	}
+
+	/** Issue #128 D2: the local pi-tui consumes the child's color-scheme
+	 * traffic (996 queries / 2031 notifications forwarded by D1) — reports
+	 * never reach the child. onTerminalColorSchemeChange fires from that same
+	 * consumption point, so the bridge repackages each event as a 997 report
+	 * on the child pty, where the child's pi-tui parser consumes it. Once per
+	 * attach (settle is single-shot + explicit guard); kill switch skips it. */
+	private attachColorSchemeBridge(): void {
+		if (process.env.AGENT_BOARD_FORWARD_TERMINAL_QUERIES === "0") return;
+		if (this.colorSchemeBridgeUnsubscribe) return;
+		try {
+			this.colorSchemeBridgeUnsubscribe = this.tui.onTerminalColorSchemeChange((scheme) => {
+				const data = toColorSchemeReport(scheme);
+				if (data) this.send({ type: "input", data });
+			});
+		} catch {
+			/* best-effort: an unbridgeable TUI keeps pre-#128 behavior */
+		}
+	}
+
+	/** Called on every terminal path (close() covers detach/dispose; the exit
+	 * branch calls done() without close(), so it unsubscribes explicitly). */
+	private detachColorSchemeBridge(): void {
+		const unsubscribe = this.colorSchemeBridgeUnsubscribe;
+		this.colorSchemeBridgeUnsubscribe = null;
+		if (!unsubscribe) return;
+		try {
+			unsubscribe();
+		} catch {
+			/* best-effort: a stale listener must not block teardown */
+		}
+	}
+
+	/** Issue #128 D3: the child probed OSC 11 at spawn, before any attach
+	 * client existed, so its background-color answer was lost. Re-ask the REAL
+	 * terminal once now; the reply travels back through the existing input
+	 * passthrough (handleInput fallback) to the child. Silent on failure — a
+	 * missing answer keeps the pre-#128 fallback theme. */
+	private replayBackgroundQuery(): void {
+		if (process.env.AGENT_BOARD_FORWARD_TERMINAL_QUERIES === "0") return;
+		try {
+			this.tui.terminal.write("\x1b]11;?\x07");
+		} catch {
+			/* best-effort: enhancement, never critical */
+		}
 	}
 
 	private startDesyncProbe(): void {
@@ -586,6 +664,13 @@ export class PtyAttachComponent implements Component {
 	 */
 	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
@@ -606,6 +691,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);
@@ -973,7 +1089,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());
 	}
 
@@ -1045,6 +1167,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);
@@ -1057,6 +1185,10 @@ export class PtyAttachComponent implements Component {
 					this.editorEmpty = typeof msg.empty === "boolean" ? msg.empty : null;
 				} else if (msg.type === "exit") {
 					this.status = "host exited";
+					// The exit path calls done() directly (host disposes later);
+					// drop the #128 bridge now so A7 symmetry doesn't depend on
+					// the host honoring dispose().
+					this.detachColorSchemeBridge();
 					this.done({ action: "closed", exitCode: msg.exitCode ?? null });
 				} else if (msg.type === "error") this.status = `error: ${msg.message ?? "host error"}`;
 				if (shouldScheduleAttachRenderForMessage(msg.type)) needsRender = true;
@@ -1067,6 +1199,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") {
@@ -1079,6 +1300,15 @@ export class PtyAttachComponent implements Component {
 			this.passthroughCarry = carry;
 			toWrite.push(...sequences);
 		}
+		if (process.env.AGENT_BOARD_FORWARD_TERMINAL_QUERIES !== "0") {
+			// Issue #128 D1: forward the child's terminal capability queries
+			// (OSC 11 background probe, 2031 scheme-notify switch) to the real
+			// terminal; set-forms and kitty/DA negotiation stay excluded (see
+			// extractOscQuerySequences).
+			const { sequences, carry } = extractOscQuerySequences(this.oscQueryCarry + data);
+			this.oscQueryCarry = carry;
+			toWrite.push(...sequences);
+		}
 		for (const seq of toWrite) {
 			try {
 				this.tui.terminal.write(seq);
@@ -1088,6 +1318,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 {
@@ -1147,8 +1386,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 };
@@ -1163,6 +1403,8 @@ export class PtyAttachComponent implements Component {
 		}
 		this.closed = true;
 		this.imeCoalesceUninstall?.();
+		this.detachColorSchemeBridge();
+		this.attachClient.close();
 		this.jiggleRetry.restoreAndStop();
 		this.disableMouseScroll();
 		this.clearMouseRefreshTimers();
@@ -1280,12 +1522,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++) {
@@ -1294,9 +1538,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 "";
 	}
 
@@ -1313,24 +1556,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;
-}