@zhuxixi/pi-agent-board 0.6.2 → 0.8.0

package/src/core/foreground-preview-cache.mjs

@@ -0,0 +1,117 @@
+/**
+ * Process-local read-your-writes cache for foreground state projections
+ * (issue #113).
+ *
+ * Foreground turns are mirrored into state.json through the detached View
+ * State Coordinator: `message_end` sets `latestAssistantPreview` /
+ * `lastAgentActivityAt` and fires a fire-and-forget `sync_foreground` command;
+ * the coordinator journals + fsyncs before materializing the file. The next
+ * event (`agent_end`, ~7ms later) rebuilds its in-memory status from the
+ * still-stale state.json, derives the "Needs instructions" fallback summary and
+ * overwrites the fresher projection that was still in flight.
+ *
+ * This cache restores read-your-writes for the two fields whose legitimate
+ * transitions are "empty → non-empty" and "old non-empty → new non-empty",
+ * keyed on `lastAgentActivityAt` as the freshness signal (message_end stamps
+ * it with `now`):
+ *
+ * - `remember` keeps the strictly-freshest projection: an entry whose
+ *   timestamp is older than the stored one never degrades it (the stale
+ *   agent_end rebuild must not clobber a newer in-flight message_end value);
+ *   an older or timestampless projection only fills gaps.
+ * - `backfill` adopts BOTH cached fields when the cached timestamp is strictly
+ *   newer than the rebuilt status's (including a timestampless/legacy
+ *   rebuild) — the disk snapshot is stale. Otherwise it fills only empty
+ *   fields: the materialized file stays authoritative when it is newer or
+ *   equally aged, so a value another writer persisted is never resurrected
+ *   over by an older cached one.
+ *
+ * Module-level by necessity: `serviceFor()` creates a new service instance per
+ * call (src/index.ts), so a per-instance cache would be discarded between
+ * events.
+ */
+
+/** @typedef {{ latestAssistantPreview: string, lastAgentActivityAt: number|null }} KnownForegroundFields */
+
+/**
+ * @returns {{
+ *   remember: (viewId: string, projection: { latestAssistantPreview?: unknown, lastAgentActivityAt?: unknown }) => void,
+ *   backfill: (viewId: string, status: { latestAssistantPreview?: unknown, lastAgentActivityAt?: unknown }) => boolean,
+ *   forget: (viewId: string) => boolean,
+ *   clear: () => void,
+ *   size: () => number,
+ * }}
+ */
+export function createForegroundPreviewCache() {
+	/** @type {Map<string, KnownForegroundFields>} */
+	const known = new Map();
+
+	function remember(viewId, projection) {
+		if (!viewId || !projection) return;
+		const preview = projection.latestAssistantPreview;
+		const activityAt = projection.lastAgentActivityAt;
+		const hasPreview = typeof preview === "string" && preview.length > 0;
+		const hasActivity = activityAt != null;
+		if (!hasPreview && !hasActivity) return;
+		const entry = known.get(viewId) ?? { latestAssistantPreview: "", lastAgentActivityAt: null };
+		const isNewer = hasActivity && (entry.lastAgentActivityAt == null || activityAt > entry.lastAgentActivityAt);
+		if (isNewer) {
+			// A strictly fresher projection wins wholesale; an empty preview still
+			// never overwrites a known non-empty one.
+			if (hasPreview) entry.latestAssistantPreview = preview;
+			entry.lastAgentActivityAt = activityAt;
+		} else {
+			// Older or timestampless: gap-fill only, never degrade the entry.
+			if (hasPreview && !entry.latestAssistantPreview) entry.latestAssistantPreview = preview;
+			if (hasActivity && entry.lastAgentActivityAt == null) entry.lastAgentActivityAt = activityAt;
+		}
+		known.set(viewId, entry);
+	}
+
+	function backfill(viewId, status) {
+		if (!viewId || !status) return false;
+		const entry = known.get(viewId);
+		if (!entry) return false;
+		const statusAt = status.lastAgentActivityAt ?? null;
+		let changed = false;
+		if (entry.lastAgentActivityAt != null && (statusAt == null || entry.lastAgentActivityAt > statusAt)) {
+			// The disk rebuild is a stale snapshot (or a timestampless legacy row):
+			// the freshest value this process projected wins wholesale.
+			if (entry.latestAssistantPreview && status.latestAssistantPreview !== entry.latestAssistantPreview) {
+				status.latestAssistantPreview = entry.latestAssistantPreview;
+				changed = true;
+			}
+			if (statusAt !== entry.lastAgentActivityAt) {
+				status.lastAgentActivityAt = entry.lastAgentActivityAt;
+				changed = true;
+			}
+			return changed;
+		}
+		if (entry.latestAssistantPreview && !status.latestAssistantPreview) {
+			status.latestAssistantPreview = entry.latestAssistantPreview;
+			changed = true;
+		}
+		if (entry.lastAgentActivityAt != null && statusAt == null) {
+			status.lastAgentActivityAt = entry.lastAgentActivityAt;
+			changed = true;
+		}
+		return changed;
+	}
+
+	function forget(viewId) {
+		return known.delete(viewId);
+	}
+
+	function clear() {
+		known.clear();
+	}
+
+	function size() {
+		return known.size;
+	}
+
+	return { remember, backfill, forget, clear, size };
+}
+
+/** Shared cache used by the runtime service (module-level: see module doc). */
+export const foregroundPreviewCache = createForegroundPreviewCache();

package/src/core/host-protocol.mjs

@@ -0,0 +1,24 @@
+/** Control-socket client identity helpers (issue #103).
+ *
+ * Client ids travel in the `hello` handshake. The runner uses them to keep
+ * bookkeeping-only connections out of `attachedClients` / `attachedEver`:
+ * the attach resolver's probes are read-only, and the hosted child's
+ * editor-state reporter is a resident connection — counting either would pin
+ * every host against warm-host reclaim (issue #75 / #103 §C).
+ */
+
+/** Read-only endpoint probe (attach resolver); never counts as attached. */
+export const CLIENT_ID_PROBE = "probe";
+/** Resident editor-state reporter inside a hosted child; never counts as attached. */
+export const CLIENT_ID_EDITOR_REPORTER = "editor-reporter";
+
+/**
+ * @param {{ type?: string, clientId?: string } | null | undefined} msg
+ * @returns {"probe" | "editor-reporter" | "client"}
+ */
+export function classifyClientHello(msg) {
+	const clientId = msg && typeof msg.clientId === "string" ? msg.clientId : "";
+	if (clientId === CLIENT_ID_PROBE) return "probe";
+	if (clientId === CLIENT_ID_EDITOR_REPORTER) return "editor-reporter";
+	return "client";
+}

package/src/core/launch.mjs

@@ -120,3 +120,18 @@ export function launchAutoState(root, config, opts) {
 
 	return { pid: child.pid ?? null, configPath };
 }
+
+/**
+ * Launch the detached view-state coordinator for a board root (issue #91, spec
+ * D3). No config file: the coordinator takes the root as its only argument.
+ * Idempotent by lease — a second instance loses the coordinator lease and
+ * exits silently, so callers may spawn freely on probe failure.
+ * @param {string} root
+ * @param {{ runnerScript: string, node?: string }} opts
+ * @returns {{ pid: number|null }}
+ */
+export function launchCoordinator(root, opts) {
+	const node = opts.node ?? resolveNode();
+	const child = spawnDetached(node, [opts.runnerScript, root], root);
+	return { pid: child.pid ?? null };
+}

package/src/core/locks.mjs

@@ -143,6 +143,12 @@ function releaseLock(lockPath, fs) {
 const defaultLeaseFs = Object.freeze({ ...defaultLocksFs, renameSync });
 /** Max stale-reclaim → republish rounds inside a single acquire attempt. */
 const MAX_LEASE_RECLAIM_ATTEMPTS = 3;
+/**
+ * Age past which an identity-less lock is treated as an orphan candidate.
+ * Host-meta holds are millisecond-scale critical sections, so no legitimate
+ * holder reaches this (issue #112).
+ */
+const ORPHAN_LEASE_AGE_MS = 5 * 60_000;
 
 /**
  * A token-fenced lease over the view-lock directory. Every operation re-reads
@@ -189,6 +195,23 @@ export function tryAcquireOwnedViewLock(root, viewId, name, opts = {}) {
 	return { acquired: true, lease: attempt };
 }
 
+/**
+ * Whether a publish-rename failure means "the lock path already exists"
+ * (contention) rather than a genuine filesystem error.
+ *
+ * POSIX reports EEXIST/ENOTEMPTY when renaming a directory onto an existing
+ * one; Windows reports EPERM (errno -4048) for the same situation — this op's
+ * platform equivalent of EEXIST (issue #114: a crashed owner's lease could
+ * never be reclaimed because EPERM was rethrown before reclaimOrBlock).
+ * Routing a genuine permission error here stays safe: reclaimability is still
+ * decided solely by `classifyLeaseOwner`, so it resolves `blocked`/`busy`.
+ * @param {string|undefined|null} code
+ * @returns {boolean}
+ */
+export function isPublishConflictCode(code) {
+	return code === "EEXIST" || code === "ENOTEMPTY" || code === "EPERM";
+}
+
 /**
  * Single-shot acquire round: publish a complete candidate lock (owner.json
  * written BEFORE the lock path exists) via atomic rename, and on contention
@@ -219,9 +242,9 @@ function attemptAcquireLease(lockPath, opts) {
 			return makeLease(lockPath, token, fs, now);
 		} catch (err) {
 			try { fs.rmSync(candidate, { recursive: true, force: true }); } catch { /* best effort */ }
-			const code = err && err.code;
-			if (code !== "EEXIST" && code !== "ENOTEMPTY") throw err;
-			const verdict = reclaimOrBlock(lockPath, token, fs, isProcessDead);
+			const code = /** @type {NodeJS.ErrnoException|undefined} */ (err)?.code;
+			if (!isPublishConflictCode(code)) throw err;
+			const verdict = reclaimOrBlock(lockPath, token, fs, isProcessDead, now);
 			if (verdict !== true) return verdict;
 			// Reclaimed a dead owner's lock — retry the publish on the next round.
 		}
@@ -230,29 +253,60 @@ function attemptAcquireLease(lockPath, opts) {
 }
 
 /**
- * Decide whether an existing lock may be reclaimed. Only a lock whose
- * owner.json carries a usable identity (pid + startToken) AND whose pid is
- * provably dead is reclaimable; anything corrupt, unreadable, or live is
- * never deleted. Reclaim quarantines via rename first so a concurrent winner
- * can only ever delete the directory it itself renamed.
+ * Decide what to do with an inspected lease owner. Pure: the caller supplies
+ * `now` and a pid-liveness probe.
+ *
+ * A full identity (pid + startToken) reclaims exactly when its pid is dead.
+ * An identity-less owner — legacy short-hold locks, or platforms where
+ * startToken cannot be captured — is only reclaimable past `orphanAgeMs`
+ * with a provably dead top-level pid: fresh identity-less locks stay blocked,
+ * preserving the short-critical-section contract (issue #112).
+ * @param {any} owner parsed owner.json
+ * @param {number} now
+ * @param {(pid: number) => boolean} isProcessDead
+ * @param {{ orphanAgeMs?: number }} [opts]
+ * @returns {"reclaim" | "busy" | "blocked"}
+ */
+export function classifyLeaseOwner(owner, now, isProcessDead, opts = {}) {
+	if (!owner || typeof owner !== "object") return "blocked";
+	const ownPid = Number(owner?.identity?.pid ?? 0);
+	const hasIdentity = Number.isFinite(ownPid) && ownPid > 0 && typeof owner?.identity?.startToken === "string";
+	if (hasIdentity) {
+		if (!isProcessDead(ownPid)) return "busy";
+		// Quarantine-mode reclaim verifies by token that it renamed the lock it
+		// inspected — without one nothing may be deleted.
+		return typeof owner.token === "string" ? "reclaim" : "blocked";
+	}
+	const pid = Number(owner?.pid ?? 0);
+	if (!Number.isFinite(pid) || pid <= 0) return "blocked";
+	const orphanAgeMs = Number(opts.orphanAgeMs ?? ORPHAN_LEASE_AGE_MS);
+	if (!(Number(now) - Number(owner?.startedAt ?? 0) >= orphanAgeMs)) return "blocked";
+	if (!isProcessDead(pid)) return "busy";
+	return typeof owner.token === "string" ? "reclaim" : "blocked";
+}
+
+/**
+ * Decide whether an existing lock may be reclaimed. Verdicts come from the
+ * pure `classifyLeaseOwner`; reclaim itself quarantines via rename first so a
+ * concurrent winner can only ever delete the directory it itself renamed.
  * @param {string} lockPath
  * @param {string} token the caller's own token (names the quarantine dir)
  * @param {typeof defaultLeaseFs} fs
  * @param {(pid: number) => boolean} isProcessDead
+ * @param {() => number} now clock (matching the caller's candidate timestamps)
  * @returns {true | "busy" | "blocked"}
  */
-function reclaimOrBlock(lockPath, token, fs, isProcessDead) {
+function reclaimOrBlock(lockPath, token, fs, isProcessDead, now) {
 	let owner;
 	try {
 		owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner.json"), "utf8"));
 	} catch {
 		return "blocked";
 	}
-	const pid = Number(owner?.identity?.pid ?? 0);
-	if (!Number.isFinite(pid) || pid <= 0 || typeof owner?.identity?.startToken !== "string") return "blocked";
-	if (!isProcessDead(pid)) return "busy";
-	const inspectedToken = typeof owner?.token === "string" ? owner.token : null;
-	if (inspectedToken === null) return "blocked";
+	const verdict = classifyLeaseOwner(owner, now(), isProcessDead);
+	if (verdict !== "reclaim") return verdict;
+	// classifyLeaseOwner only returns "reclaim" when owner.token is a string.
+	const inspectedToken = owner.token;
 	const quarantine = `${lockPath}.reclaim.${token}`;
 	try {
 		fs.renameSync(lockPath, quarantine);

package/src/core/paths.mjs

@@ -37,6 +37,10 @@ export const metaPath = (root, viewId) => path.join(viewDir(root, viewId), "meta
 export const statePath = (root, viewId) => path.join(viewDir(root, viewId), "state.json");
 /** @param {string} root @param {string} viewId */
 export const hostPath = (root, viewId) => path.join(viewDir(root, viewId), "host.json");
+/** Durable control-command journal for a view's host (issue #91 phase 5, spec
+ *  D4): one JSONL line per durable-command lifecycle transition
+ *  (accepted/applied). Sibling of host.json in the view dir. */
+export const controlJournalPath = (root, viewId) => path.join(viewDir(root, viewId), "control-journal.jsonl");
 /** @param {string} root @param {string} viewId */
 export const hostConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "host-config.json");
 /**
@@ -71,6 +75,21 @@ export function controlSocketPathFor(platform, root, viewId) {
 }
 /** @param {string} root @param {string} viewId */
 export const controlSocketPath = (root, viewId) => controlSocketPathFor(process.platform, root, viewId);
+/**
+ * Endpoint a hosted child's editor-state reporter should connect to.
+ *
+ * The runner knows which endpoint it actually bound and injects it into the
+ * child env as AGENT_BOARD_CONTROL_SOCKET (issue #103): since #70 the owned
+ * runner binds a per-instance address, while the reporter kept dialing the
+ * stable per-view one, so it never connected and the attach gate lost its
+ * authoritative editor state. The injected value wins; the stable address
+ * remains the fallback for legacy hosts and older runners that predate the key.
+ * @param {{ envSocketPath?: string | null, platform: "win32"|"linux"|"darwin", root: string, viewId: string }} args
+ */
+export function resolveControlEndpoint({ envSocketPath, platform, root, viewId }) {
+	const injected = typeof envSocketPath === "string" ? envSocketPath.trim() : "";
+	return injected.length > 0 ? injected : controlSocketPathFor(platform, root, viewId);
+}
 /**
  * Per-instance control endpoint. Each new host instance binds its own socket/pipe,
  * so a superseded runner can never unlink the current owner's endpoint (issue #70).
@@ -89,6 +108,35 @@ export function hostEndpointPathFor(platform, root, viewId, instanceId) {
 }
 /** @param {string} root @param {string} viewId */
 export const screenLogPath = (root, viewId) => path.join(viewDir(root, viewId), "screen.log");
+/**
+ * Well-known endpoint for the board-root View State Coordinator (issue #91, spec D3).
+ * Exactly one coordinator may own a root (token-fenced lease), so one stable path
+ * suffices; a stale POSIX socket left by a crashed coordinator is unlinked by the
+ * new lease owner before bind. win32 pipe names embed a 16-hex hash of the
+ * *normalized* root to stay under the 256-char limit and keep per-root isolation.
+ * @param {"win32"|"linux"|"darwin"} platform
+ * @param {string} root
+ */
+export function coordinatorEndpointPathFor(platform, root) {
+	if (platform === "win32") {
+		// Normalize before hashing: the pipe name must be invariant to the root's
+		// spelling (C:/x vs C:\x, trailing separators, dot segments). The lock path
+		// derived from the same root already is (via path.join); a mismatch yields
+		// "same lock, two pipes" — the panel probes a pipe nobody bound, spawns
+		// replacements that cannot take the held lease, and locks itself out
+		// (issue #124). resolve() is idempotent on canonical roots, so coordinators
+		// already deployed keep their pipe name and need no restart.
+		// win32 semantics are named explicitly rather than using the ambient
+		// path.resolve: this branch must emit the same pipe name on every host OS
+		// (on POSIX, ambient resolve treats `C:\x` as a relative path: no
+		// drive-letter or backslash-separator semantics), so platform-injected
+		// tests and CI behave identically everywhere.
+		const normalized = path.win32.resolve(root);
+		const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+		return `\\\\.\\pipe\\agent-board-coordinator-${hash}`;
+	}
+	return path.join(root, "coordinator.sock");
+}
 /** @param {string} root @param {string} viewId */
 export const hostPidPath = (root, viewId) => path.join(viewDir(root, viewId), "host-pid.json");
 /** @param {string} root @param {string} viewId */

package/src/core/pid.mjs

@@ -1,4 +1,5 @@
-/** Process liveness checks. */
+/** Process liveness checks and process identity capture. */
+import { readFileSync } from "node:fs";
 
 /**
  * Whether `pid` refers to a live process.
@@ -40,3 +41,33 @@ export function killProcess(pid, graceMs = 4000) {
 		}
 	}, graceMs).unref?.();
 }
+
+/**
+ * POSIX process start token — /proc/<pid>/stat field 22 (starttime), stable
+ * across exec(2). Distinguishes an owned-live pid from a reused one; null on
+ * failure or non-Linux platforms. Mirrors the runner's captureStartToken
+ * (issue #70); shared here for host-meta lease identity (issue #112).
+ * @param {number|null|undefined} pid
+ * @returns {string|null}
+ */
+export function captureStartToken(pid) {
+	if (process.platform !== "linux" || !pid) return null;
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		// comm (field 2) may contain spaces and parens — fields resume AFTER the
+		// last ')'. fields[0] is state (field 3) → starttime (field 22) is [19].
+		const afterComm = stat.slice(stat.lastIndexOf(")") + 1).trimStart();
+		return afterComm.split(/\s+/)[19] ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Launch-time identity for the current process, as stamped on host-meta
+ * acquisitions (issue #112).
+ * @returns {{pid: number, startToken: string|null}}
+ */
+export function currentProcessIdentity() {
+	return { pid: process.pid, startToken: captureStartToken(process.pid) };
+}

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

@@ -1,4 +1,13 @@
 /**
+ * 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
@@ -60,6 +69,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 +102,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,27 +215,49 @@ 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
+	 * (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) {
-		if (state.clearDetected) return; // chain done; nothing left to detect
-		if (state.stopped) return; // chain ended (G2/G3/G4); output is inert
+		// 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 (result.frameStartFound && !tuiFrameSeen) {
-			tuiFrameSeen = true;
+		if (firstFrame) {
 			clearG1Timer();
 			if (held) {
 				restoreIfHeld(); // fast path: child is rendering, width delta now lands
@@ -242,6 +280,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 +348,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-reconnect.mjs

@@ -31,13 +31,20 @@ export function evaluateAttachReconnect({ everConnected, disconnectedAt, connect
 }
 
 /**
- * Detach-key policy: while the socket is down a key can never reach the child,
- * so treat ← / ctrl+] as "leave the view" unconditionally; otherwise keep the
- * existing empty-input-line gate (issue #48 comment 1).
+ * 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} childInputLooksEmpty
+ * @param {boolean | null | undefined} editorEmpty
  * @returns {boolean}
  */
-export function shouldEscapeAttach(connected, childInputLooksEmpty) {
-	return !connected || childInputLooksEmpty;
+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;
 }

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

@@ -43,6 +43,26 @@ export function projectPtyCursor(buf, start, height) {
 	return { row, col: buf.cursorX };
 }
 
+/**
+ * Duck-typed read of the child terminal's DECTCEM visibility state.
+ *
+ * pi-tui hides the hardware cursor (ESC[?25l) on essentially every frame and
+ * still parks it for IME positioning, so the xterm cursor position outlives its
+ * visibility: it is a rendering byproduct, not a request to show a cursor. The
+ * attach projection must not resurrect that parked cell as a visible block, and
+ * must equally not hide a cursor the child wants shown (shells, vim,
+ * PI_HARDWARE_CURSOR=1). Only an explicit `true` from xterm's cursor service
+ * counts as hidden; anything unknown (renamed internals, another @xterm build)
+ * falls back to visible, which is the pre-#102 behavior.
+ */
+export function isPtyCursorHidden(term) {
+	try {
+		return term?._core?.coreService?.isCursorHidden === true;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * Coalesce PTY parser callbacks into a bounded stream of repaint requests.
  *
@@ -70,3 +90,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";
+}