@huseynsnmz/pi-board 0.15.3 → 0.16.0

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

@@ -1,499 +0,0 @@
-# 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"
-```