@zhuxixi/pi-agent-board 0.3.0

package/docs/superpowers/plans/2026-08-16-attach-double-cursor-jiggle-retry.md

@@ -0,0 +1,499 @@
+# Attach Double-Cursor Jiggle Retry 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:** Add jiggle retry logic that re-sends resize jiggle with backoff until a full-clear sequence (`\x1b[2J`) is detected in the PTY output, fixing the double-cursor desync on cold-start/streaming attach.
+
+**Architecture:** Pure state machine in `src/core/pty-attach-jiggle-retry.mjs` handles all retry logic (clear detection, backoff scheduling, stop conditions). The UI component `src/ui/pty-attach.ts` acts as glue — feeding socket data to the state machine and managing the retry timer.
+
+**Tech Stack:** TypeScript (ESM), Node.js `node:test`, `@xterm/headless`
+
+## Global Constraints
+
+- Pure logic must be dependency-free (no socket, no xterm, no timers) — testable in isolation
+- Use `node:test` + `node:assert/strict` for tests (existing project pattern)
+- Commit messages in English, conventional format (`feat:`/`fix:`/`test:`)
+- Worktree: `/home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry`
+- Don't touch `main` branch — all work on `issue-2-attach-double-cursor-jiggle-retry`
+
+---
+
+### Task 1: Pure Logic — Jiggle Retry State Machine
+
+**Files:**
+- Create: `src/core/pty-attach-jiggle-retry.mjs`
+- Test: `test/pty-attach-jiggle-retry.test.mjs`
+
+**Interfaces:**
+- Consumes: nothing (standalone module)
+- Produces:
+  - `BACKOFF_MS: readonly number[]` — `[120, 500, 1500, 3000]`
+  - `MAX_RETRIES: number` — `4`
+  - `createJiggleRetryState(): JiggleRetryState`
+  - `feedOutput(state, data, carry): { state, carry, clearFound }`
+  - `nextRetryDelay(state): number | null`
+  - `advanceRetry(state): JiggleRetryState`
+  - `stopRetry(state): JiggleRetryState`
+  - `hasFullClearSequence(data: string): boolean`
+
+- [ ] **Step 1: Write the failing tests**
+
+```javascript
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	BACKOFF_MS,
+	MAX_RETRIES,
+	createJiggleRetryState,
+	feedOutput,
+	nextRetryDelay,
+	advanceRetry,
+	stopRetry,
+	hasFullClearSequence,
+} from "../src/core/pty-attach-jiggle-retry.mjs";
+
+// --- hasFullClearSequence ---
+
+test("detects \\x1b[2J in plain data", () => {
+	assert.equal(hasFullClearSequence("hello\x1b[2Jworld"), true);
+});
+
+test("detects \\x1b[2J at start", () => {
+	assert.equal(hasFullClearSequence("\x1b[2J"), true);
+});
+
+test("detects \\x1b[2J followed by \\x1b[H", () => {
+	assert.equal(hasFullClearSequence("\x1b[2J\x1b[H"), true);
+});
+
+test("rejects data without \\x1b[2J", () => {
+	assert.equal(hasFullClearSequence("hello world"), false);
+});
+
+test("rejects \\x1b[3J (scrollback clear, not full clear)", () => {
+	assert.equal(hasFullClearSequence("\x1b[3J"), false);
+});
+
+test("rejects partial escape \\x1b[2 (no J)", () => {
+	assert.equal(hasFullClearSequence("\x1b[2"), false);
+});
+
+// --- createJiggleRetryState ---
+
+test("initial state is fresh", () => {
+	const s = createJiggleRetryState();
+	assert.equal(s.retryIndex, 0);
+	assert.equal(s.clearDetected, false);
+	assert.equal(s.stopped, false);
+});
+
+// --- feedOutput ---
+
+test("feedOutput detects clear sequence", () => {
+	const s = createJiggleRetryState();
+	const r = feedOutput(s, "some output \x1b[2J more", "");
+	assert.equal(r.clearFound, true);
+	assert.equal(r.state.clearDetected, true);
+});
+
+test("feedOutput returns clearFound=false when no clear", () => {
+	const s = createJiggleRetryState();
+	const r = feedOutput(s, "normal output", "");
+	assert.equal(r.clearFound, false);
+	assert.equal(r.state.clearDetected, false);
+});
+
+test("feedOutput handles cross-chunk split: \\x1b[ + 2J", () => {
+	const s = createJiggleRetryState();
+	const r1 = feedOutput(s, "data\x1b[", "");
+	assert.equal(r1.clearFound, false);
+	assert.equal(r1.carry, "\x1b[");
+	const r2 = feedOutput(r1.state, "2Jrest", r1.carry);
+	assert.equal(r2.clearFound, true);
+});
+
+test("feedOutput handles cross-chunk split: \\x1b + [2J", () => {
+	const s = createJiggleRetryState();
+	const r1 = feedOutput(s, "data\x1b", "");
+	assert.equal(r1.clearFound, false);
+	assert.equal(r1.carry, "\x1b");
+	const r2 = feedOutput(r1.state, "[2Jrest", r1.carry);
+	assert.equal(r2.clearFound, true);
+});
+
+test("feedOutput clears carry after successful detection", () => {
+	const s = createJiggleRetryState();
+	const r1 = feedOutput(s, "data\x1b[", "");
+	const r2 = feedOutput(r1.state, "2Jrest", r1.carry);
+	assert.equal(r2.carry, "");
+});
+
+test("feedOutput keeps carry for non-matching partial", () => {
+	const s = createJiggleRetryState();
+	const r = feedOutput(s, "data\x1b[3", "");
+	assert.equal(r.clearFound, false);
+	assert.ok(r.carry.length > 0);
+});
+
+// --- nextRetryDelay ---
+
+test("nextRetryDelay returns BACKOFF_MS in order", () => {
+	let s = createJiggleRetryState();
+	for (let i = 0; i < MAX_RETRIES; i++) {
+		assert.equal(nextRetryDelay(s), BACKOFF_MS[i]);
+		s = advanceRetry(s);
+	}
+});
+
+test("nextRetryDelay returns null after MAX_RETRIES", () => {
+	let s = createJiggleRetryState();
+	for (let i = 0; i < MAX_RETRIES; i++) s = advanceRetry(s);
+	assert.equal(nextRetryDelay(s), null);
+});
+
+test("nextRetryDelay returns null when clearDetected", () => {
+	const s = createJiggleRetryState();
+	const r = feedOutput(s, "\x1b[2J", "");
+	assert.equal(nextRetryDelay(r.state), null);
+});
+
+test("nextRetryDelay returns null when stopped", () => {
+	const s = stopRetry(createJiggleRetryState());
+	assert.equal(nextRetryDelay(s), null);
+});
+
+// --- advanceRetry ---
+
+test("advanceRetry increments retryIndex", () => {
+	const s0 = createJiggleRetryState();
+	const s1 = advanceRetry(s0);
+	assert.equal(s1.retryIndex, 1);
+	const s2 = advanceRetry(s1);
+	assert.equal(s2.retryIndex, 2);
+});
+
+// --- stopRetry ---
+
+test("stopRetry sets stopped=true", () => {
+	const s = stopRetry(createJiggleRetryState());
+	assert.equal(s.stopped, true);
+});
+
+// --- Immutability ---
+
+test("feedOutput does not mutate original state", () => {
+	const s = createJiggleRetryState();
+	feedOutput(s, "\x1b[2J", "");
+	assert.equal(s.clearDetected, false);
+});
+
+test("advanceRetry does not mutate original state", () => {
+	const s = createJiggleRetryState();
+	advanceRetry(s);
+	assert.equal(s.retryIndex, 0);
+});
+
+test("stopRetry does not mutate original state", () => {
+	const s = createJiggleRetryState();
+	stopRetry(s);
+	assert.equal(s.stopped, false);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+node --test test/pty-attach-jiggle-retry.test.mjs
+```
+
+Expected: FAIL — module not found
+
+- [ ] **Step 3: Implement the state machine**
+
+```javascript
+/** Pure logic for attach jiggle-retry: detect full-clear, schedule backoff retries. */
+
+export const BACKOFF_MS = Object.freeze([120, 500, 1500, 3000]);
+export const MAX_RETRIES = BACKOFF_MS.length;
+
+const FULL_CLEAR = "\x1b[2J";
+/** Carry enough bytes to catch a split escape sequence at chunk boundary. */
+const CARRY_LEN = FULL_CLEAR.length - 1; // 3 bytes: \x1b, \x1b[, \x1b[2
+
+/**
+ * @typedef {Object} JiggleRetryState
+ * @property {number} retryIndex - Current retry round (0 = initial, not yet retried).
+ * @property {boolean} clearDetected - Whether a full-clear sequence was seen.
+ * @property {boolean} stopped - Whether the retry chain has been stopped.
+ */
+
+/** Create initial retry state. */
+export function createJiggleRetryState() {
+	return { retryIndex: 0, clearDetected: false, stopped: false };
+}
+
+/**
+ * Feed PTY output data into the state machine.
+ * Returns new state, updated carry buffer, and whether a clear was found.
+ * @param {JiggleRetryState} state
+ * @param {string} data - New output data chunk.
+ * @param {string} carry - Leftover partial escape sequence from previous chunk.
+ * @returns {{ state: JiggleRetryState, carry: string, clearFound: boolean }}
+ */
+export function feedOutput(state, data, carry) {
+	const combined = carry + data;
+	const clearFound = hasFullClearSequence(combined);
+	const newCarry = clearFound ? "" : tailCarry(combined);
+	const newState = clearFound
+		? { ...state, clearDetected: true }
+		: state;
+	return { state: newState, carry: newCarry, clearFound };
+}
+
+/**
+ * Get the delay before the next retry, or null if no more retries.
+ * @param {JiggleRetryState} state
+ * @returns {number | null}
+ */
+export function nextRetryDelay(state) {
+	if (state.stopped || state.clearDetected) return null;
+	if (state.retryIndex >= MAX_RETRIES) return null;
+	return BACKOFF_MS[state.retryIndex];
+}
+
+/**
+ * Advance to the next retry round.
+ * @param {JiggleRetryState} state
+ * @returns {JiggleRetryState}
+ */
+export function advanceRetry(state) {
+	return { ...state, retryIndex: state.retryIndex + 1 };
+}
+
+/**
+ * Stop the retry chain (attach settled, component closed, etc.).
+ * @param {JiggleRetryState} state
+ * @returns {JiggleRetryState}
+ */
+export function stopRetry(state) {
+	return { ...state, stopped: true };
+}
+
+/**
+ * Check if data contains the full-clear escape sequence.
+ * @param {string} data
+ * @returns {boolean}
+ */
+export function hasFullClearSequence(data) {
+	return data.includes(FULL_CLEAR);
+}
+
+/** Extract the tail carry for cross-chunk boundary detection. */
+function tailCarry(data) {
+	// We only need to carry up to CARRY_LEN bytes to catch a split \x1b[2J.
+	const tail = data.slice(-CARRY_LEN);
+	// Find the last \x1b in the tail — everything before it can't be part of
+	// a split escape sequence.
+	const escIdx = tail.lastIndexOf("\x1b");
+	return escIdx >= 0 ? tail.slice(escIdx) : "";
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+node --test test/pty-attach-jiggle-retry.test.mjs
+```
+
+Expected: All 18 tests PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+git add src/core/pty-attach-jiggle-retry.mjs test/pty-attach-jiggle-retry.test.mjs
+git commit -m "feat: add jiggle retry state machine with clear-sequence detection"
+```
+
+---
+
+### Task 2: Integrate Retry Chain into PtyAttachComponent
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts`
+
+**Interfaces:**
+- Consumes: `createJiggleRetryState`, `feedOutput`, `nextRetryDelay`, `advanceRetry`, `stopRetry`, `BACKOFF_MS` from `src/core/pty-attach-jiggle-retry.mjs`
+- Produces: no new exports — internal behavior change only
+
+- [ ] **Step 1: Add import and new private fields**
+
+In `src/ui/pty-attach.ts`, add to the imports at top:
+```typescript
+import {
+	createJiggleRetryState,
+	feedOutput as feedJiggleRetry,
+	nextRetryDelay,
+	advanceRetry,
+	stopRetry,
+} from "../core/pty-attach-jiggle-retry.mjs";
+```
+
+Add new private fields to the class (after existing fields, near `forcedRedrawAfterLiveOutput`):
+```typescript
+// Jiggle retry chain: re-send resize jiggle until we see a full-clear sequence
+// in the PTY output, proving the child pi-tui did a fullRender and the replay
+// garbage has been flushed. Replaces the one-shot forceChildRedrawAfterLiveOutput.
+private jiggleRetryState = createJiggleRetryState();
+private jiggleRetryTimer: ReturnType<typeof setTimeout> | null = null;
+private clearCarry = "";
+```
+
+- [ ] **Step 2: Add new private methods**
+
+Add these methods to the class (near `forceChildRedraw`):
+
+```typescript
+/** Start the jiggle retry chain after initial jiggle. */
+private startJiggleRetry(): void {
+	this.jiggleRetryState = createJiggleRetryState();
+	this.clearCarry = "";
+	this.scheduleNextJiggleRetry();
+}
+
+/** Check socket output for full-clear sequence; cancel retry if found. */
+private checkClearSequence(data: string): void {
+	const result = feedJiggleRetry(this.jiggleRetryState, data, this.clearCarry);
+	this.jiggleRetryState = result.state;
+	this.clearCarry = result.carry;
+	if (result.clearFound) this.cancelJiggleRetry();
+}
+
+/** Schedule the next jiggle retry with backoff. */
+private scheduleNextJiggleRetry(): void {
+	const delay = nextRetryDelay(this.jiggleRetryState);
+	if (delay === null) return;
+	this.jiggleRetryTimer = setTimeout(() => {
+		this.jiggleRetryTimer = null;
+		if (this.closed || !this.connected) return;
+		this.forceChildRedraw();
+		this.jiggleRetryState = advanceRetry(this.jiggleRetryState);
+		this.scheduleNextJiggleRetry();
+	}, delay);
+	this.jiggleRetryTimer.unref?.();
+}
+
+/** Cancel the jiggle retry chain. */
+private cancelJiggleRetry(): void {
+	if (this.jiggleRetryTimer) {
+		clearTimeout(this.jiggleRetryTimer);
+		this.jiggleRetryTimer = null;
+	}
+	this.jiggleRetryState = stopRetry(this.jiggleRetryState);
+}
+```
+
+- [ ] **Step 3: Wire into connect() — start retry after initial jiggle**
+
+In `connect()`, after `this.forceChildRedraw()` (around line 309), add:
+```typescript
+this.startJiggleRetry();
+```
+
+- [ ] **Step 4: Wire into onSocketData() — check for clear sequence**
+
+In `onSocketData()`, inside the `msg.type === "output"` branch, after `this.pushOutput(msg.data, ...)`, replace the `this.forceChildRedrawAfterLiveOutput()` call with:
+```typescript
+this.checkClearSequence(msg.data);
+```
+
+- [ ] **Step 5: finishAttachTransition() — do NOT cancel retry (updated post-review)**
+
+**Update (final review, commit 806bf3e):** the retry chain intentionally survives the settle transition. Originally this step wired `cancelJiggleRetry()` into `finishAttachTransition()`, but review found that kills the chain at ~410ms in the silent cold-start case — the exact failure mode this feature fixes — leaving only retry 1 reachable. The chain now self-terminates on: clear detected / max retries / close(). Post-settle jiggles only fire when the child consumed all earlier jiggles (screen already stale), trading a brief full-render flicker for self-healing.
+
+- [ ] **Step 6: Wire into close() — cancel retry**
+
+In `close()`, add (alongside other cleanup):
+```typescript
+this.cancelJiggleRetry();
+```
+
+- [ ] **Step 7: Remove old one-shot logic**
+
+Delete the `forcedRedrawAfterLiveOutput` field declaration.
+
+Delete the `forceChildRedrawAfterLiveOutput()` method entirely.
+
+Delete the `liveRedrawTimer` field declaration.
+
+In `close()`, remove `this.liveRedrawTimer` cleanup if present (it was cleaned by `clearRedrawTimer()` which also clears `liveRedrawTimer` — verify and clean up).
+
+- [ ] **Step 8: Verify TypeScript compiles**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+npx tsc --noEmit
+```
+
+Expected: No errors
+
+- [ ] **Step 9: Run all existing tests**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+node --test test/*.test.mjs
+```
+
+Expected: All tests PASS (no regressions)
+
+- [ ] **Step 10: Commit**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+git add src/ui/pty-attach.ts
+git commit -m "feat: integrate jiggle retry chain into attach component"
+```
+
+---
+
+### Task 3: Final Verification — Full Test Suite + Lint
+
+**Files:**
+- No new files; verification only
+
+- [ ] **Step 1: Run full test suite**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+node --test test/*.test.mjs
+```
+
+Expected: All PASS
+
+- [ ] **Step 2: TypeScript check**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+npx tsc --noEmit
+```
+
+Expected: No errors
+
+- [ ] **Step 3: Check for lint issues**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+npx biome check src/core/pty-attach-jiggle-retry.mjs src/ui/pty-attach.ts test/pty-attach-jiggle-retry.test.mjs 2>&1 || true
+```
+
+Expected: No new issues (fix if any)
+
+- [ ] **Step 4: Final commit (if any fixes needed)**
+
+```bash
+cd /home/elling/git-repo/github/pi-agent-board/.claude/worktrees/issue-2-attach-double-cursor-jiggle-retry
+git add -p  # stage only relevant fixes
+git commit -m "fix: address lint/type issues from final verification"
+```