@zhuxixi/pi-agent-board 0.6.1 → 0.7.0

package/docs/superpowers/plans/2026-09-08-issue-11-attach-runtime-desync-heal.md

@@ -0,0 +1,917 @@
+# Attach Runtime Desync Detect + Heal Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Detect runtime cursor desync (attach-settled, mid-session) via a 2s probe that checks the PTY cursor cell's inverse attribute, and self-heal by re-arming the shrink-and-hold jiggle protocol with rate limiting and a lifetime budget (issue #11).
+
+**Architecture:** Three layers matching the existing codebase split: (1) pure classifier `detectCursorDesync()` in `src/core/pty-attach-render.mjs`; (2) protocol entry `heal()` on the existing jiggle controller in `src/core/pty-attach-jiggle-controller.mjs` reusing feed/clear detection and guards; (3) wiring in `src/ui/pty-attach.ts` — `lastOutputAt` timestamp, injectable `nowFn`, a `checkDesync()` method gated by 7 conditions, and a probe timer started at attach settle / stopped at close. Spec: `docs/superpowers/specs/2026-09-07-issue-11-attach-runtime-desync-heal-design.md`.
+
+**Tech Stack:** Node.js ESM (.mjs), TypeScript component compiled via `--experimental-transform-types`, `node:test` + `node:assert/strict`, `@xterm/headless` in smoke tests only.
+
+## Global Constraints
+
+- Parameter values (copy verbatim): `DESYNC_QUIET_MS = 1500`, `DESYNC_PROBE_INTERVAL_MS = 2000`, `HEAL_RATELIMIT_MS = 10000`, `HEAL_MAX_PER_LIFETIME = 5`.
+- healBudget is consumed on **entry** to `heal()` (including the tiny-terminal give-up path); `start()`/`restoreAndStop()` never reset it.
+- `heal()` preserves `tuiFrameSeen` and never arms G1; it must reuse `feed()`'s existing clear detection and the G3/G4/G5 guard behavior without changing `start()`'s semantics.
+- `checkDesync()` gates, in order: (1) `!attaching && !closed`, (2) `tuiFrameSeen`, (3) `detectCursorDesync(...) === "misaligned"`, (4) `now - lastOutputAt > DESYNC_QUIET_MS`, (5) chain idle (`state.stopped && !held`), (6) `now - lastHealAt > HEAL_RATELIMIT_MS`, (7) `this.connected`.
+- The probe is a self-contained timer (unref'd, cleared in `close()`), NOT hooked into the render path (render is event-driven and stops exactly when desync strikes).
+- `lastOutputAt` is recorded synchronously in `pushOutput()` before `term.write`, never inside its async callback.
+- Never commit to main; all work stays in this worktree branch. Commit messages use conventional commits. `git add` per-file, never `git add -A`.
+- Test commands: `node --test test/pty-attach-render.test.mjs`, `node --test test/pty-attach-jiggle-controller.test.mjs`, `node --test test/pty-attach-desync-heal.test.mjs`, `node --test test/pty-attach-desync-health-e2e.test.mjs`, full suite `npm test`.
+
+---
+
+### Task 1: `detectCursorDesync` pure classifier (A1)
+
+**Files:**
+- Modify: `src/core/pty-attach-render.mjs` (append after `projectPtyCursor`)
+- Test: `test/pty-attach-render.test.mjs` (append; add `detectCursorDesync` to the import list)
+
+**Interfaces:**
+- Consumes: the `{ row, col } | null` shape returned by the existing `projectPtyCursor(buf, start, height)` (same file).
+- Produces: `detectCursorDesync(buf: { getLine(row): { length: number; getCell(x): { isInverse(): boolean; getWidth(): number } | undefined } | undefined }, cursor: { row: number; col: number } | null): "aligned" | "misaligned" | "unknown"` — consumed by Task 3's `checkDesync()`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/pty-attach-render.test.mjs` (extend the existing import statement with `detectCursorDesync`):
+
+```js
+// --- issue #11: runtime desync classifier ---
+
+function fakeDesyncBuf(cells) {
+	// cells: array of { inverse: boolean, width: number } | null (null = no cell at x)
+	return {
+		getLine(row) {
+			if (row !== 0) return undefined;
+			return {
+				length: cells.length,
+				getCell(x) {
+					const c = cells[x];
+					if (!c) return undefined;
+					return { isInverse: () => c.inverse, getWidth: () => c.width };
+				},
+			};
+		},
+	};
+}
+
+test("detectCursorDesync: null cursor (viewport-scrolled) is unknown", () => {
+	assert.equal(detectCursorDesync(fakeDesyncBuf([]), null), "unknown");
+});
+
+test("detectCursorDesync: cursor on an inverse cell is aligned", () => {
+	const buf = fakeDesyncBuf([{ inverse: false, width: 1 }, { inverse: true, width: 1 }]);
+	assert.equal(detectCursorDesync(buf, { row: 0, col: 1 }), "aligned");
+});
+
+test("detectCursorDesync: cursor on a non-inverse cell is misaligned", () => {
+	const buf = fakeDesyncBuf([{ inverse: true, width: 1 }, { inverse: false, width: 1 }]);
+	assert.equal(detectCursorDesync(buf, { row: 0, col: 1 }), "misaligned");
+});
+
+test("detectCursorDesync: cursor past line end falls back to the last inverse cell (aligned)", () => {
+	const buf = fakeDesyncBuf([{ inverse: false, width: 1 }, { inverse: true, width: 1 }]);
+	assert.equal(detectCursorDesync(buf, { row: 0, col: 99 }), "aligned");
+});
+
+test("detectCursorDesync: cursor on a width-0 CJK continuation falls back to the leading wide cell", () => {
+	// "你" occupies cols 0-1: col 0 width 2 inverse, col 1 width 0 (continuation)
+	const buf = fakeDesyncBuf([{ inverse: true, width: 2 }, { inverse: false, width: 0 }, { inverse: false, width: 1 }]);
+	assert.equal(detectCursorDesync(buf, { row: 0, col: 1 }), "aligned");
+});
+
+test("detectCursorDesync: fully empty line (no cells, no inverse) is misaligned", () => {
+	const buf = fakeDesyncBuf([]);
+	assert.equal(detectCursorDesync(buf, { row: 0, col: 0 }), "misaligned");
+});
+
+test("detectCursorDesync: missing buffer line is unknown", () => {
+	assert.equal(detectCursorDesync(fakeDesyncBuf([{ inverse: true, width: 1 }]), { row: 5, col: 0 }), "unknown");
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-11-attach-runtime-desync-heal && node --test test/pty-attach-render.test.mjs`
+Expected: FAIL — `detectCursorDesync` is not exported (import error).
+
+- [ ] **Step 3: Write the implementation**
+
+Append to `src/core/pty-attach-render.mjs`:
+
+```js
+/**
+ * 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";
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `node --test test/pty-attach-render.test.mjs`
+Expected: PASS (all new + existing tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/pty-attach-render.mjs test/pty-attach-render.test.mjs
+git commit -m "feat: detectCursorDesync three-state classifier for runtime desync (issue #11)"
+```
+
+---
+
+### Task 2: controller `heal()` + lifetime budget (A2)
+
+**Files:**
+- Modify: `src/core/pty-attach-jiggle-controller.mjs` (add `HEAL_MAX_PER_LIFETIME` const, `healCount` state, `heal()` function; extend `getState()` and the returned API)
+- Test: `test/pty-attach-jiggle-controller.test.mjs` (append)
+
+**Interfaces:**
+- Consumes: existing `createJiggleRetryState`, `stopRetry`, `resizeJiggleSize`, `scheduleNextRetry`, `clearAllTimers`, `restoreIfHeld`, and module state (`held`, `restored`, `state`, `carry`, `tuiFrameSeen`, `originalCols/Rows`, `holdSize`).
+- Produces: `heal(cols: number, rows: number): boolean` — `true` when a heal hold was armed, `false` when the budget is exhausted or no valid hold size exists. `getState()` additionally exposes `healCount: number`. Consumed by Task 3's `checkDesync()`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/pty-attach-jiggle-controller.test.mjs`:
+
+```js
+// --- issue #11: runtime desync heal ---
+
+function frameSeenController() {
+	const { controller, scheduler, resizes } = makeController();
+	controller.start(170, 36);
+	controller.feed("\x1b[?2026h"); // first TUI frame → restore via fast path
+	controller.feed("\x1b[2J");     // clear → chain done, runtime idle state
+	return { controller, scheduler, resizes };
+}
+
+test("heal(): re-arms shrink-and-hold, preserves tuiFrameSeen, no G1", () => {
+	const { controller, scheduler, resizes } = frameSeenController();
+	resizes.length = 0;
+	assert.equal(controller.heal(170, 36), true);
+	assert.deepEqual(resizes, [[169, 35]], "heal sends exactly one shrink");
+	assert.equal(controller.getState().held, true);
+	assert.equal(controller.getState().tuiFrameSeen, true, "heal must NOT reset tuiFrameSeen");
+	assert.equal(scheduler.findByDelay(6000), null, "heal must NOT arm G1");
+	assert.ok(scheduler.delays().length > 0, "chain (G2 backoff) is scheduled");
+});
+
+test("heal() then feed clear → restore + stop", () => {
+	const { controller, resizes } = frameSeenController();
+	resizes.length = 0;
+	controller.heal(170, 36);
+	controller.feed("redraw\x1b[2J\x1b[Hframe");
+	assert.deepEqual(resizes.slice(-1), [[170, 36]], "clear restores original size");
+	assert.equal(controller.getState().held, false);
+	assert.equal(controller.getState().clearDetected, true);
+	assert.equal(controller.getState().stopped, true);
+});
+
+test("heal() budget: 5 attempts max per controller lifetime", () => {
+	const { controller, resizes } = frameSeenController();
+	resizes.length = 0;
+	for (let i = 0; i < 5; i++) {
+		assert.equal(controller.heal(170, 36), true, `heal #${i + 1} succeeds`);
+		// resolve each heal with a clear so the next one starts idle
+		controller.feed("\x1b[2J");
+	}
+	resizes.length = 0;
+	assert.equal(controller.heal(170, 36), false, "6th heal rejected");
+	assert.deepEqual(resizes, [], "no resize sent after budget exhausted");
+	assert.equal(controller.getState().healCount, 5);
+});
+
+test("heal() budget is NOT reset by start() or restoreAndStop()", () => {
+	const { controller } = frameSeenController();
+	controller.heal(170, 36);
+	controller.feed("\x1b[2J");
+	controller.start(170, 36);
+	controller.feed("\x1b[2J");
+	controller.restoreAndStop();
+	assert.equal(controller.getState().healCount, 1);
+});
+
+test("heal() consumes budget even on tiny terminals (no valid hold size)", () => {
+	const { controller } = frameSeenController();
+	assert.equal(controller.heal(20, 5), false, "tiny terminal cannot hold");
+	assert.equal(controller.getState().healCount, 1, "budget consumed on entry");
+});
+
+test("heal() hold is cancelled by G4 notifyExternalResize", () => {
+	const { controller, resizes } = frameSeenController();
+	resizes.length = 0;
+	controller.heal(170, 36);
+	controller.notifyExternalResize(200, 50);
+	assert.equal(controller.getState().held, false);
+	assert.equal(controller.getState().stopped, true);
+	// G4 adopts the new size as original: a later heal restores to the new size
+	assert.equal(controller.heal(200, 50), true);
+	controller.feed("\x1b[2J");
+	assert.deepEqual(resizes.filter(([c]) => c === 200).length >= 1, true, "restore tracks the adopted size");
+});
+
+test("heal() while a previous heal is held: restores the old hold first", () => {
+	const { controller, resizes } = frameSeenController();
+	resizes.length = 0;
+	controller.heal(170, 36);       // shrink #1
+	controller.heal(170, 36);       // shrink #2 — must restore #1 first (no clear between)
+	assert.deepEqual(resizes, [[169, 35], [170, 36], [169, 35]], "second heal unwinds the first hold before re-shrinking");
+	assert.equal(controller.getState().healCount, 2);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `node --test test/pty-attach-jiggle-controller.test.mjs`
+Expected: FAIL — `controller.heal is not a function`.
+
+- [ ] **Step 3: Write the implementation**
+
+In `src/core/pty-attach-jiggle-controller.mjs`:
+
+3a. Add next to `POST_RESTORE_VERIFY_MS`:
+
+```js
+/** 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;
+```
+
+3b. Add state next to `let g1Timer = null;`:
+
+```js
+/** Runtime heals spent (issue #11); never reset by start()/restoreAndStop(). */
+let healCount = 0;
+```
+
+3c. Add the method (place after `feed`, before `restoreAndStop`):
+
+```js
+	/**
+	 * 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;
+	}
+```
+
+3d. Extend `getState()` and the return object:
+
+```js
+		getState: () => ({ ...state, held, tuiFrameSeen, originalCols, originalRows, holdSize, healCount }),
+```
+
+and add `heal` to the returned API object (`return { start, feed, heal, restoreAndStop, notifyExternalResize, getState };`).
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `node --test test/pty-attach-jiggle-controller.test.mjs`
+Expected: PASS (all new + existing tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/pty-attach-jiggle-controller.mjs test/pty-attach-jiggle-controller.test.mjs
+git commit -m "feat: jiggle controller heal() runtime backstop with lifetime budget (issue #11)"
+```
+
+---
+
+### Task 3: component wiring — probe timer, `checkDesync()`, 7 gates (A3)
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (constants near `ATTACH_OUTPUT_RENDER_INTERVAL_MS` import; fields near `viewportTop` (~L152); `pushOutput` (~L1050); `finishAttachTransition` (~L514); `close()` (~L1100); import `detectCursorDesync`)
+- Create: `test-support/desync-heal-smoke.ts`
+- Create: `test/pty-attach-desync-heal.test.mjs`
+
+**Interfaces:**
+- Consumes: `detectCursorDesync` (Task 1), `controller.heal()` / `getState().healCount` (Task 2), existing `projectPtyCursor`, `bodyHeight()`, `bottomViewportTop()`, `clampViewportTop()`, `this.jiggleRetry`, `this.cols/rows`, `this.connected`, `this.attaching`, `this.send`.
+- Produces (runtime-injectable for tests, same pattern detach-gate-smoke already uses): fields `lastOutputAt: number`, `lastHealAt: number`, `nowFn: () => number`, plus private methods `checkDesync(): void`, `startDesyncProbe(): void`, `stopDesyncProbe(): void`. Smoke tests call `checkDesync()` and read `jiggleRetry.getState()` via `(attach as unknown as {...})` casts.
+
+- [ ] **Step 1: Write the failing smoke harness**
+
+Create `test-support/desync-heal-smoke.ts` (modeled on `detach-gate-smoke.ts` — real `PtyAttachComponent`, fake tui, runtime injection of private fields):
+
+```ts
+// Desync heal wiring harness (issue #11): construct PtyAttachComponent with a
+// fake TUI, drive it through Pi-like buffer states via the real socket-data
+// path (pushOutput + checkClearSequence), then verify the 7 gates of
+// checkDesync() and the end-to-end heal loop:
+//   H1. healthy idle (cursor parked on inverse fake cursor) → no heal.
+//   H2. desync (cursor parked elsewhere) + quiet window → exactly one heal
+//       (shrink sent); immediate re-check is rate-limited + chain-idle-gated.
+//   H3. pre-settle (attaching) → no heal.
+//   H4. no TUI frame (tuiFrameSeen false) → no heal.
+//   H5. cursor scrolled out of viewport → no heal.
+//   H6. recent output (within DESYNC_QUIET_MS) → no heal.
+//   H7. heal loop: child redraws with clear + cursor back on the fake cursor
+//       → restore + no further heal.
+// Timing/state facts the harness encodes (verified against the component and
+// controller source):
+//   - checkDesync gate 7 needs this.connected — injected true (no real socket).
+//   - The controller must sit in runtime-idle state (tuiFrameSeen=true from a
+//     2026h frame, then chain stopped by a detected \x1b[2J) — feed() learns
+//     the frame BEFORE the clear; once clearDetected it short-circuits, and
+//     within one chunk a clear wins over a frame start.
+//   - The projected window is bottom-anchored (bottomViewportTop), so frames
+//     sink 25 newlines first to land the cursor inside [start, start+height).
+// Run via `node --experimental-transform-types` (TS parameter properties).
+import { PtyAttachComponent } from "../src/ui/pty-attach.ts";
+
+const ESC = "\x1b";
+/** Leading clear: stops the controller chain (runtime-idle state). */
+const CLEAR = `${ESC}[2J${ESC}[H`;
+/** Push content + cursor to the buffer bottom so they land inside the
+ * bottom-anchored projection window (25 > 24-row viewport → 1 line scrollback). */
+const SINK = "\n".repeat(25);
+const tui = {
+	terminal: { rows: 24, cols: 80, columns: 80, write: () => {} },
+	requestRender: () => {},
+};
+const theme = { fg: (_c: string, t: string) => t, bold: (t: string) => t };
+const keybindings = {} as never;
+
+type Drivable = {
+	pushOutput: (data: string) => void;
+	checkClearSequence: (data: string) => void;
+	finishAttachTransition: () => void;
+	checkDesync: () => void;
+	attaching: boolean;
+	viewportTop: number | null;
+	jiggleRetry: { getState: () => { healCount: number; held: boolean; stopped: boolean; tuiFrameSeen: boolean }; feed: (data: string) => void };
+};
+
+function makeAttach() {
+	const attach = new PtyAttachComponent(
+		tui as never,
+		theme as never,
+		keybindings,
+		() => {},
+		{ socketPath: "/no/such/socket", title: "desync" },
+	);
+	const sent: Array<Record<string, unknown>> = [];
+	(attach as unknown as { send: (msg: Record<string, unknown>) => void }).send = (msg) => sent.push(msg);
+	// Gate 7 needs a live connection; the fake socketPath would never connect.
+	(attach as unknown as { connected: boolean }).connected = true;
+	// Injectable clock: start at t=1_000_000 so "unset" (0) timestamps always look stale.
+	const clock = { now: 1_000_000 };
+	(attach as unknown as { nowFn: () => number }).nowFn = () => clock.now;
+	return { attach: attach as unknown as Drivable, sent, clock };
+}
+
+async function write(attach: Drivable, data: string): Promise<void> {
+	// Mirror the real socket-data path (onSocketData → pushOutput + checkClearSequence):
+	// checkClearSequence feeds the jiggle controller (2026h frame detection,
+	// clear detection) — without it tuiFrameSeen stays false and gates have no teeth.
+	attach.pushOutput(data);
+	attach.checkClearSequence(data);
+	await new Promise((r) => setTimeout(r, 20));
+}
+
+/** Bring the controller to the real runtime-idle state: 2026h frame seen
+ * first (tuiFrameSeen=true), then a detected clear (chain stopped). */
+async function primeRuntime(attach: Drivable): Promise<void> {
+	await write(attach, `${ESC}[?2026h`);
+	await write(attach, CLEAR);
+}
+
+/** Healthy idle frame: bottom line carries the inverse fake cursor and the
+ * hardware cursor is parked ON it (CUP 24;10 == the inverse cell). */
+const healthyFrame = `${SINK}> editor \u4f60\u597d${ESC}[7m ${ESC}[0m${ESC}[24;7H${ESC}[7m ${ESC}[0m${ESC}[24;7H`;
+/** Desynced frame: same content, but the cursor ends parked on a PLAIN cell
+ * one row above the inverse fake cursor (where a garbled differential write
+ * left it). */
+const desyncFrame = `${SINK}> editor \u4f60\u597d${ESC}[7m ${ESC}[0m${ESC}[24;7H${ESC}[7m ${ESC}[0m${ESC}[23;5H`;
+/** Child response to a heal: fullRender-style clear + redraw + cursor parked
+ * back on the inverse fake cursor. */
+const healResponse = `${ESC}[?2026h${ESC}[2J${ESC}[H${SINK}> editor \u4f60\u597d${ESC}[7m ${ESC}[0m${ESC}[24;7H${ESC}[7m ${ESC}[0m${ESC}[24;7H${ESC}[?2026l`;
+
+async function main(): Promise<void> {
+	const out: Record<string, boolean> = {};
+
+	// H1: healthy idle — no heal
+	{
+		const { attach, sent, clock } = makeAttach();
+		await primeRuntime(attach);
+		await write(attach, healthyFrame);
+		attach.finishAttachTransition();
+		clock.now += 10_000; // all gates open — only gate 3 (aligned) can stop it
+		attach.checkDesync();
+		out.healthyIdleNoHeal = attach.jiggleRetry.getState().healCount === 0 && resizes(sent) === 0;
+	}
+
+	// H2: desync + quiet → exactly one heal; immediate re-check rate-limited + chain-idle-gated
+	{
+		const { attach, sent, clock } = makeAttach();
+		await primeRuntime(attach);
+		await write(attach, desyncFrame);
+		attach.finishAttachTransition();
+		clock.now += 10_000; // last output now older than DESYNC_QUIET_MS
+		attach.checkDesync();
+		const healed = attach.jiggleRetry.getState().healCount === 1 && resizes(sent) === 1;
+		attach.checkDesync(); // within 10s rate limit AND chain is active (held)
+		out.desyncHealsOnce = healed && attach.jiggleRetry.getState().healCount === 1 && resizes(sent) === 1;
+	}
+
+	// H3: pre-settle (attaching true) — no heal
+	{
+		const { attach, sent } = makeAttach();
+		await primeRuntime(attach);
+		await write(attach, desyncFrame);
+		// do NOT finishAttachTransition(); attaching is still true
+		attach.checkDesync();
+		out.preSettleNoHeal = attach.jiggleRetry.getState().healCount === 0 && resizes(sent) === 0;
+	}
+
+	// H4: no 2026h frame — no heal
+	{
+		const { attach, sent } = makeAttach();
+		// No primeRuntime (it would set tuiFrameSeen); chain is stopped via the
+		// clear so only gate 2 (no TUI frame) blocks the heal.
+		await write(attach, CLEAR + "plain shell output, no TUI frame");
+		attach.finishAttachTransition();
+		attach.checkDesync();
+		out.noFrameNoHeal = attach.jiggleRetry.getState().healCount === 0 && resizes(sent) === 0;
+	}
+
+	// H5: cursor scrolled out of the projected viewport — no heal
+	{
+		const { attach, sent, clock } = makeAttach();
+		await primeRuntime(attach);
+		// Establish scrollback well beyond the window (60 lines), leave the
+		// cursor on the bottom viewport row (absolute ≈ buf.length-1), then
+		// have the user scroll to the top: window [0,22) excludes the cursor.
+		let scroll = "";
+		for (let i = 0; i < 60; i++) scroll += `row ${i}\n`;
+		await write(attach, scroll + `${ESC}[24;5H`);
+		attach.finishAttachTransition();
+		(attach as unknown as { viewportTop: number | null }).viewportTop = 0; // user scrolled up
+		clock.now += 10_000; // all gates open — only the viewport (unknown) path can stop it
+		attach.checkDesync();
+		out.scrolledOutNoHeal = attach.jiggleRetry.getState().healCount === 0 && resizes(sent) === 0;
+	}
+
+	// H6: recent output (inside the quiet window) — no heal
+	{
+		const { attach, sent, clock } = makeAttach();
+		await primeRuntime(attach);
+		await write(attach, desyncFrame);
+		attach.finishAttachTransition();
+		clock.now += 100; // way less than DESYNC_QUIET_MS
+		attach.checkDesync();
+		out.recentOutputNoHeal = attach.jiggleRetry.getState().healCount === 0 && resizes(sent) === 0;
+	}
+
+	// H7: heal loop closes — child clears + parks cursor on the fake cursor again
+	{
+		const { attach, sent, clock } = makeAttach();
+		await primeRuntime(attach);
+		await write(attach, desyncFrame);
+		attach.finishAttachTransition();
+		clock.now += 10_000;
+		attach.checkDesync();
+		const shrinkSeen = attach.jiggleRetry.getState().healCount === 1;
+		// Child answers the shrink with a fullRender: clear + redraw + cursor on fake cursor.
+		await write(attach, healResponse);
+		const restored = attach.jiggleRetry.getState().held === false && attach.jiggleRetry.getState().stopped === true;
+		clock.now += 10_000; // next probe tick: aligned now, and budget intact
+		attach.checkDesync();
+		out.healLoopCloses = shrinkSeen && restored && attach.jiggleRetry.getState().healCount === 1 && resizes(sent) === 2; // heal shrink + controller restore
+	}
+
+	console.log(JSON.stringify(out));
+	const allOk = Object.values(out).every(Boolean);
+	if (!allOk) process.exitCode = 1;
+}
+
+void main();
+```
+
+- [ ] **Step 2: Write the failing wrapper test**
+
+Create `test/pty-attach-desync-heal.test.mjs` (same execFileSync pattern as `test/pty-attach-detach-gate.test.mjs`):
+
+```js
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import test from "node:test";
+
+const ROOT_DIR = fileURLToPath(new URL("../", import.meta.url));
+const SMOKE_SCRIPT = join(ROOT_DIR, "test-support", "desync-heal-smoke.ts");
+
+// Issue #11: runtime desync detect + rate-limited heal — component wiring gates.
+test("desync heal wiring: 7 gates + heal loop", () => {
+	const out = execFileSync(process.execPath, ["--experimental-transform-types", SMOKE_SCRIPT], {
+		encoding: "utf8",
+		timeout: 60_000,
+	});
+	const parsed = JSON.parse(out);
+	assert.equal(parsed.healthyIdleNoHeal, true, "H1 healthy idle must not heal");
+	assert.equal(parsed.desyncHealsOnce, true, "H2 desync must heal exactly once (rate limit + chain gate)");
+	assert.equal(parsed.preSettleNoHeal, true, "H3 pre-settle must not heal");
+	assert.equal(parsed.noFrameNoHeal, true, "H4 no TUI frame must not heal");
+	assert.equal(parsed.scrolledOutNoHeal, true, "H5 cursor out of viewport must not heal");
+	assert.equal(parsed.recentOutputNoHeal, true, "H6 recent output must not heal");
+	assert.equal(parsed.healLoopCloses, true, "H7 child clear must close the heal loop without a second heal");
+});
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `node --test test/pty-attach-desync-heal.test.mjs`
+Expected: FAIL — compile error (`checkDesync` / `nowFn` not on the component) or assertion failures.
+
+- [ ] **Step 4: Write the implementation**
+
+In `src/ui/pty-attach.ts`:
+
+4a. Extend the import from `../core/pty-attach-render.mjs` (~L10):
+
+```ts
+import { createAttachOutputRenderScheduler, detectCursorDesync, nextAttachRender, projectPtyCursor, shouldScheduleAttachRenderForMessage } from "../core/pty-attach-render.mjs";
+```
+
+4b. Add constants near the other module consts (search `GRACEFUL_SOCKET_CLOSE_MS` / `ATTACH_SETTLE_MS`):
+
+```ts
+/** 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;
+```
+
+4c. Add fields near `private viewportTop: number | null = null;` (~L152):
+
+```ts
+	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();
+```
+
+4d. In `pushOutput()` (~L1050), record the timestamp synchronously (add as the second statement, right after the `if (data.length === 0) return;` guard, BEFORE `term.write`):
+
+```ts
+		this.lastOutputAt = this.nowFn();
+```
+
+4e. In `finishAttachTransition()` (~L514), add at the end (after `this.scheduleRender(true);`):
+
+```ts
+		this.startDesyncProbe();
+```
+
+4f. Add the probe + check methods (place after `finishAttachTransition`):
+
+```ts
+	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), misaligned cursor,
+	 * output quiet, chain idle, heal rate limit. 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
+		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);
+	}
+```
+
+4g. In `close()` (~L1100, next to the `attachSettleTimer` cleanup), add:
+
+```ts
+		this.stopDesyncProbe();
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `node --test test/pty-attach-desync-heal.test.mjs && node --test test/pty-attach-detach-gate.test.mjs`
+Expected: PASS (new wiring test + existing detach-gate regression both green).
+
+- [ ] **Step 6: Run the full suite to catch regressions**
+
+Run: `npm test`
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/ui/pty-attach.ts test-support/desync-heal-smoke.ts test/pty-attach-desync-heal.test.mjs
+git commit -m "feat: wire runtime desync probe with 7 gates into attach component (issue #11)"
+```
+
+---
+
+### Task 4: healthy-session E2E — no false heal (A4)
+
+**Files:**
+- Create: `test-support/fake-idle-tui-pi.mjs` (idle healthy child: TUI frame with inverse fake cursor + cursor parked on it, then silent; resize → full clear + repaint, mirroring pi-tui's widthChanged → fullRender(true))
+- Create: `test-support/desync-health-e2e.ts` (real runner spawn + real `PtyAttachComponent` + fake tui; attach → settle → hold ≥3 probe ticks with the child idle → assert `healCount === 0`)
+- Test: `test/pty-attach-desync-health-e2e.test.mjs` (execFileSync wrapper)
+
+**Interfaces:**
+- Consumes: `atomicWriteJson` + `P.*` paths (same setup as `test/pty-attach-cold-start-e2e.test.mjs`'s `spawnRunner`), real `runner/pty-runner.mjs` protocol, `PtyAttachComponent` opts `{ socketPath, title }`.
+- Produces: standalone verification that a real runner + healthy idle TUI child never triggers a heal across the full attach lifecycle (spec A4).
+
+- [ ] **Step 1: Write the fake idle child**
+
+Create `test-support/fake-idle-tui-pi.mjs`:
+
+```js
+#!/usr/bin/env node
+/**
+ * Fake healthy IDLE pi for the desync-health E2E (issue #11).
+ *
+ * Boots fast (no artificial delay), renders exactly like a healthy pi-tui
+ * idle frame — an editor line whose cursor cell is INVERSE (the fake cursor)
+ * with the hardware cursor parked ON that cell — and then goes silent.
+ * Any resize away from the baseline triggers a fullRender-style clear +
+ * repaint (pi-tui widthChanged → fullRender(true)), re-parking the cursor.
+ * This is the child the desync probe must leave alone: aligned + quiet.
+ */
+const baseline = [process.stdout.columns, process.stdout.rows];
+
+function frame() {
+	// 2026h frame; editor line at row 2 col 5: inverse space = fake cursor;
+	// CUP to (2,5) parks the hardware cursor ON the inverse cell.
+	process.stdout.write(
+		"\x1b[?2026h\x1b[2J\x1b[Hready\n> editor line\x1b[2;5H\x1b[7m \x1b[0m\x1b[2;5H\x1b[?2026l",
+	);
+}
+
+process.stdout.on("resize", () => {
+	const c = process.stdout.columns;
+	const r = process.stdout.rows;
+	if (c === baseline[0] && r === baseline[1]) return;
+	baseline[0] = c;
+	baseline[1] = r;
+	frame();
+});
+
+frame();
+process.on("SIGTERM", () => process.exit(0));
+process.on("SIGINT", () => process.exit(0));
+```
+
+- [ ] **Step 2: Write the E2E harness**
+
+Create `test-support/desync-health-e2e.ts`:
+
+```ts
+// Healthy-session E2E (issue #11, spec A4): real runner + fake idle TUI child +
+// REAL PtyAttachComponent. The attach runs its full lifecycle (shrink-and-hold
+// protocol, settle, probe). With a healthy child (cursor parked on the inverse
+// fake cursor, then silent) the desync probe must never heal across ≥3 probe
+// ticks. Run via `node --experimental-transform-types`.
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { atomicWriteJson } from "../src/core/atomic.mjs";
+import * as P from "../src/core/paths.mjs";
+import { createView } from "../src/core/store.mjs";
+import { PtyAttachComponent } from "../src/ui/pty-attach.ts";
+
+const tui = {
+	terminal: { rows: 36, cols: 120, columns: 120, write: () => {} },
+	requestRender: () => {},
+};
+const theme = { fg: (_c: string, t: string) => t, bold: (t: string) => t };
+const keybindings = {} as never;
+
+async function main(): Promise<void> {
+	const root = mkdtempSync(join(tmpdir(), "desync-health-"));
+	const viewId = "e2ehealth";
+	let runner: ReturnType<typeof spawn> | null = null;
+	let attach: PtyAttachComponent | null = null;
+	try {
+		const meta = createView(root, { id: viewId, name: "health", cwd: process.cwd() });
+		atomicWriteJson(P.hostConfigPath(root, viewId), {
+			root,
+			viewId,
+			sessionFile: meta.sessionFile,
+			cwd: process.cwd(),
+			initialPrompt: null,
+			piCommand: process.execPath,
+			piArgsPrefix: [resolve("test-support/fake-idle-tui-pi.mjs")],
+			model: null,
+			tools: null,
+			env: {},
+			cols: 120,
+			rows: 36,
+		});
+		runner = spawn(process.execPath, [resolve("runner/pty-runner.mjs"), P.hostConfigPath(root, viewId)], {
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const socketPath = P.controlSocketPath(root, viewId);
+		// Wait for the runner to create its control socket (same wait as cold-start E2E).
+		const deadline = Date.now() + 10_000;
+		while (!existsSync(socketPath) && Date.now() < deadline) {
+			await new Promise((r) => setTimeout(r, 50));
+		}
+
+		attach = new PtyAttachComponent(
+			tui as never,
+			theme as never,
+			keybindings,
+			() => {},
+			{ socketPath, title: "health" },
+		);
+		void attach.render(120); // drive one render so resizeIfNeeded sends the initial size
+
+		// Settle + hold across ≥3 probe ticks (2s period) + quiet window (1.5s).
+		await new Promise((r) => setTimeout(r, 9_000));
+
+		const state = (attach as unknown as {
+			jiggleRetry: { getState: () => { healCount: number; held: boolean; stopped: boolean } };
+		}).jiggleRetry.getState();
+		const result = { healedNever: state.healCount === 0, chainDone: state.stopped === true, held: state.held === false };
+		console.log(JSON.stringify(result));
+		if (!Object.values(result).every(Boolean)) process.exitCode = 1;
+	} finally {
+		attach?.close();
+		runner?.kill("SIGTERM");
+		await new Promise((r) => setTimeout(r, 200));
+		rmSync(root, { recursive: true, force: true });
+	}
+	void createServer; // keep node:net import meaningful for parity with sibling harnesses
+	void once;
+}
+
+void main();
+```
+
+Note: `P.controlSocketPath(root, viewId)` and `P.hostConfigPath(root, viewId)` are the exact helpers `test/pty-attach-cold-start-e2e.test.mjs` waits on (verified against `src/core/paths.mjs` L68 / cold-start E2E usage); `createView` is exported from `src/core/store.mjs` L420.
+
+- [ ] **Step 3: Write the wrapper test**
+
+Create `test/pty-attach-desync-health-e2e.test.mjs`:
+
+```js
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import test from "node:test";
+
+const ROOT_DIR = fileURLToPath(new URL("../", import.meta.url));
+const E2E_SCRIPT = join(ROOT_DIR, "test-support", "desync-health-e2e.ts");
+
+// Issue #11 (A4): a real runner + healthy idle TUI child must never trigger a
+// runtime desync heal across the full attach lifecycle.
+test("desync health e2e: healthy idle session triggers no heal", () => {
+	const out = execFileSync(process.execPath, ["--experimental-transform-types", E2E_SCRIPT], {
+		encoding: "utf8",
+		timeout: 60_000,
+	});
+	const parsed = JSON.parse(out);
+	assert.equal(parsed.healedNever, true, "healCount must stay 0 on a healthy idle session");
+	assert.equal(parsed.chainDone, true, "attach chain must complete");
+	assert.equal(parsed.held, false || parsed.held === false, "no hold left armed");
+});
+```
+
+- [ ] **Step 4: Run the E2E to verify it fails-or-passes honestly**
+
+Run: `node --test test/pty-attach-desync-health-e2e.test.mjs`
+Expected: PASS. If it FAILS because the harness wiring (socket path helper names, runner protocol details) is off, fix the harness until it exercises the real attach lifecycle (observable via `chainDone: true`); if it fails because `healedNever` is false, the classifier/probe has a real false-positive — debug `detectCursorDesync` against the fake child's frame, not the harness.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test-support/fake-idle-tui-pi.mjs test-support/desync-health-e2e.ts test/pty-attach-desync-health-e2e.test.mjs
+git commit -m "test: healthy idle session never triggers desync heal (issue #11 A4)"
+```
+
+---
+
+### Task 5: full verification + spec acceptance sweep
+
+**Files:**
+- No new files; verification only.
+
+**Interfaces:**
+- Consumes: everything from Tasks 1-4.
+
+- [ ] **Step 1: Full test suite**
+
+Run: `cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-11-attach-runtime-desync-heal && npm test`
+Expected: PASS (568+ existing + 7 A1 + 7 A2 + 1 A3 + 1 A4 new tests).
+
+- [ ] **Step 2: TypeScript check (whatever the repo uses)**
+
+Run: `npm run verify 2>/dev/null || npx tsc --noEmit`
+Expected: clean (use `npm run verify` if defined in package.json scripts; otherwise tsc).
+
+- [ ] **Step 3: Spec acceptance sweep (fill the table into the PR description)**
+
+Check off each spec acceptance ID against actual evidence:
+- A1 → `node --test test/pty-attach-render.test.mjs` output (7 new cases)
+- A2 → `node --test test/pty-attach-jiggle-controller.test.mjs` output (7 new cases)
+- A3 → `node --test test/pty-attach-desync-heal.test.mjs` output (H1-H7)
+- A4 → `node --test test/pty-attach-desync-health-e2e.test.mjs` output
+- U1 → mark `pending (observational, post-merge)` — daily-use watching for spurious flicker; does not block merge per spec.
+
+- [ ] **Step 4: Commit any residual fixes**
+
+```bash
+git status --short
+# fix and git add <specific files> if anything surfaced; otherwise nothing to commit
+```