@zhuxixi/pi-agent-board 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuxixi/pi-agent-board",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agent-board dashboard for Pi: dispatch, monitor, peek/reply, and attach to background Pi sessions.",
   "type": "module",
   "main": "./index.ts",

package/runner/job-runner.mjs

@@ -13,14 +13,14 @@ import { fileURLToPath } from "node:url";
 import { appendLine, readJson } from "../src/core/atomic.mjs";
 import { createRunStatus, finalizeRun, projectViewState, reduceEvent } from "../src/core/events.mjs";
 import { encodePromptForCliArg } from "../src/core/prompt-transport.mjs";
-import { applyAutoStateToStatus, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState } from "../src/core/auto-state.mjs";
+import { applyAutoStateToStatus, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualCompletion } from "../src/core/auto-state.mjs";
 import { appendDiagnostic } from "../src/core/diagnostics.mjs";
 import { emptyEvidenceSnapshot, finalizeEvidence, reduceEvidence, summarizeEvidence, writeEvidence, writeRunEvidence } from "../src/core/evidence.mjs";
 import { claimNextFollowUp, completeFollowUp, releaseFollowUp } from "../src/core/follow-up-queue.mjs";
 import { newRunId } from "../src/core/ids.mjs";
 import { launchRun } from "../src/core/launch.mjs";
 import * as P from "../src/core/paths.mjs";
-import { readState, writeState, writeStatus } from "../src/core/store.mjs";
+import { readState, readStatus, writeState, writeStatus } from "../src/core/store.mjs";
 import { readSteering, recordPlanReady } from "../src/core/steering.mjs";
 import { buildApprovePlanPrompt, buildPlanChangesPrompt, buildPlanRequestPrompt } from "../src/core/steering-prompts.mjs";
 
@@ -102,6 +102,19 @@ function main() {
 		dirty = false;
 	};
 
+	/**
+	 * Persist only if the user hasn't marked the row done manually since the last
+	 * persist. projectViewState() overwrites the row state unconditionally, so a
+	 * post-exit model pass must never persist its stale in-memory status over a
+	 * fresh manual completion.
+	 */
+	const persistUnlessManual = (force = false) => {
+		const latestView = readState(root, viewId);
+		if (isManualCompletion(latestView)) return false;
+		persist(force);
+		return true;
+	};
+
 	const scheduleFlush = () => {
 		if (flushTimer) {
 			dirty = true;
@@ -206,12 +219,12 @@ function main() {
 				if (changed) {
 					finalizeEvidence(evidence, status, Date.now());
 					status.evidenceSummary = summarizeEvidence(evidence);
-					persist(true);
+					persistUnlessManual(true);
 				}
 				return maybeModelSummary(config, status);
 			})
 			.then((changed) => {
-				if (changed) persist(true);
+				if (changed) persistUnlessManual(true);
 			})
 			.catch(() => {})
 			.finally(() => {
@@ -333,6 +346,13 @@ async function maybeModelAutoState(config, status, evidence) {
 		[...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model, prompt],
 		15000,
 	);
+	// Fresh read: the user may have marked the row done manually during the model
+	// call. completeView clears autoState in both state.json and status.json, so a
+	// manual completion is detectable here; applying the classification to the stale
+	// in-memory status would clobber the user's verdict.
+	const fresh = readStatus(config.root, config.viewId, config.runId);
+	if (!fresh || isManualCompletion(fresh)) return false;
+	Object.assign(status, fresh);
 	const classification = autoStateFromModelOrHeuristic(out, latest, { lastAgentActivityAt: status.lastAgentActivityAt ?? null });
 	const changed = applyAutoStateToStatus(status, classification, Date.now());
 	if (changed) {
@@ -366,6 +386,10 @@ async function maybeModelSummary(config, status) {
 		[...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model, prompt],
 		15000,
 	);
+	// The user may have marked the row done manually during the summary call.
+	// Updating the stale status and letting the caller persist would clobber the
+	// manual completion, so bail out before touching the in-memory status.
+	if (isManualCompletion(readState(config.root, config.viewId))) return false;
 	const text = out.trim().split("\n").slice(-1)[0]?.trim();
 	if (text) {
 		status.summary = text.replace(/^["']|["']$/g, "").slice(0, 80);

package/src/commands/agent-board.ts

@@ -88,6 +88,7 @@ export async function openDashboard(
 				};
 				const comp = new DashboardComponent(tui, theme as never, keybindings, wrappedDone, {
 					service,
+					root: service.getRoot(),
 					defaultCwd: ctx.cwd,
 					initialSelectedId: options.initialSelectedId,
 					availableModels,

package/src/core/auto-state.mjs

@@ -40,6 +40,18 @@ function isOff(value) {
 	return typeof value === "string" && /^(0|false|off|no)$/i.test(value.trim());
 }
 
+/**
+ * Whether automatic `done` classification is disabled.
+ * Default (env unset): disabled — completed is only ever set by the user.
+ * Set AGENT_BOARD_AUTO_STATE_NO_DONE to 0/false/off/no to restore auto-done.
+ * @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env]
+ */
+export function autoStateDoneDisabled(env = process.env) {
+	const raw = env.AGENT_BOARD_AUTO_STATE_NO_DONE;
+	if (typeof raw !== "string" || !raw.trim()) return true;
+	return !isOff(raw);
+}
+
 /** @param {AutoStateKind} kind @returns {SemanticState} */
 export function semanticStateForAutoKind(kind) {
 	switch (kind) {
@@ -55,22 +67,35 @@ export function semanticStateForAutoKind(kind) {
 /**
  * Prompt used by runners for the cheap classifier pass.
  * @param {string} latestAssistantText
+ * @param {NodeJS.ProcessEnv|Record<string,string|undefined>} [env]
  */
-export function buildAutoStatePrompt(latestAssistantText) {
+export function buildAutoStatePrompt(latestAssistantText, env = process.env) {
 	const text = truncate(String(latestAssistantText || "").trim(), 6000);
-	return `Classify the LAST assistant response for a coding-agent dashboard.\n\nChoose exactly one state:\n- needs_input: the assistant asks the user for a decision, clarification, approval, credentials, or is blocked waiting for the user.\n- in_progress: work is partial, next steps remain, verification is pending/failed, or the assistant says it will continue later.\n- done: the requested work is complete, final answer given, no user input required.\n\nReturn ONLY minified JSON with this shape:\n{"state":"needs_input|in_progress|done","confidence":"high|medium|low","reason":"short reason <=18 words","question":"user-facing question or null"}\n\nLast assistant response:\n${text}`;
+	const doneLine = autoStateDoneDisabled(env)
+		? ""
+		: "- done: the requested work is complete, final answer given, no user input required.\n";
+	const doneNote = autoStateDoneDisabled(env)
+		? "The user marks completed manually in the dashboard, so completion signals (done/completed/finished) must be classified as in_progress.\n"
+		: "";
+	const states = autoStateDoneDisabled(env) ? "needs_input|in_progress" : "needs_input|in_progress|done";
+	return `Classify the LAST assistant response for a coding-agent dashboard.\n\nChoose exactly one state:\n- needs_input: the assistant asks the user for a decision, clarification, approval, credentials, or is blocked waiting for the user.\n- in_progress: work is partial, next steps remain, verification is pending/failed, or the assistant says it will continue later.\n${doneLine}${doneNote}\nReturn ONLY minified JSON with this shape:\n{"state":"${states}","confidence":"high|medium|low","reason":"short reason <=18 words","question":"user-facing question or null"}\n\nLast assistant response:\n${text}`;
 }
 
 /**
  * Parse and normalize model JSON. Returns null if the response is unusable.
  * @param {string} raw
- * @param {{ latestAssistantText?: string, now?: number, lastAgentActivityAt?: number|null }} [opts]
+ * @param {{ latestAssistantText?: string, now?: number, lastAgentActivityAt?: number|null, env?: NodeJS.ProcessEnv|Record<string,string|undefined> }} [opts]
  */
 export function parseAutoStateModelOutput(raw, opts = {}) {
 	const obj = extractJsonObject(raw);
 	if (!obj) return null;
-	const kind = normalizeKind(obj.state ?? obj.kind ?? obj.status);
+	let kind = normalizeKind(obj.state ?? obj.kind ?? obj.status);
 	if (!kind) return null;
+	let downgraded = false;
+	if (kind === "done" && autoStateDoneDisabled(opts.env ?? process.env)) {
+		kind = "in_progress";
+		downgraded = true;
+	}
 	const confidence = normalizeConfidence(obj.confidence);
 	const latest = opts.latestAssistantText ?? "";
 	const nb = detectNeedsInput(latest);
@@ -78,7 +103,9 @@ export function parseAutoStateModelOutput(raw, opts = {}) {
 	return makeClassification(kind, {
 		source: "model",
 		confidence,
-		reason: cleanReason(obj.reason) || defaultReason(kind),
+		reason: downgraded
+			? "Model reported done but auto-done is disabled"
+			: cleanReason(obj.reason) || defaultReason(kind),
 		question,
 		now: opts.now,
 		lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
@@ -90,7 +117,7 @@ export function parseAutoStateModelOutput(raw, opts = {}) {
  * Conservative fallback classifier. It should be useful, but never clever enough to
  * overrule strong question/error signals.
  * @param {string} latestAssistantText
- * @param {{ now?: number, lastAgentActivityAt?: number|null }} [opts]
+ * @param {{ now?: number, lastAgentActivityAt?: number|null, env?: NodeJS.ProcessEnv|Record<string,string|undefined> }} [opts]
  */
 export function heuristicAutoState(latestAssistantText, opts = {}) {
 	const text = String(latestAssistantText || "").trim();
@@ -110,7 +137,8 @@ export function heuristicAutoState(latestAssistantText, opts = {}) {
 	const lower = text.toLowerCase();
 	const pending = hasPendingSignal(lower);
 	const done = hasDoneSignal(lower);
-	if (done && !pending) {
+	const env = opts.env ?? process.env;
+	if (done && !pending && !autoStateDoneDisabled(env)) {
 		return makeClassification("done", {
 			source: "heuristic",
 			confidence: hasStrongDoneSignal(lower) ? "high" : "medium",
@@ -120,6 +148,18 @@ export function heuristicAutoState(latestAssistantText, opts = {}) {
 			latestAssistantText: text,
 		});
 	}
+	if (done && !pending) {
+		// Auto-done disabled: completion signals stay out of the completed bucket;
+		// the user marks completed manually from the dashboard.
+		return makeClassification("in_progress", {
+			source: "heuristic",
+			confidence: hasStrongDoneSignal(lower) ? "medium" : "low",
+			reason: "Assistant reported completion but auto-done is disabled",
+			now: opts.now,
+			lastAgentActivityAt: opts.lastAgentActivityAt ?? null,
+			latestAssistantText: text,
+		});
+	}
 	if (pending) {
 		return makeClassification("in_progress", {
 			source: "heuristic",
@@ -150,6 +190,17 @@ export function autoStateFromModelOrHeuristic(modelOutput, latestAssistantText,
 	return parseAutoStateModelOutput(modelOutput, { latestAssistantText, ...opts }) ?? heuristicAutoState(latestAssistantText, opts);
 }
 
+/**
+ * Whether a row/status shows a manual completion. completeView clears autoState on
+ * both state.json and status.json when the user marks done, so `autoState == null`
+ * combined with `completed` is the manual-completion signal. Auto-classified
+ * completed rows keep autoState and stay refinable by a later model pass.
+ * @param {{ semanticState?: string, autoState?: unknown|null }|null|undefined} state
+ */
+export function isManualCompletion(state) {
+	return Boolean(state && state.semanticState === "completed" && state.autoState == null);
+}
+
 /**
  * Mutate a RunStatus with a classification. Returns true if state/metadata changed.
  * @param {import("./types.mjs").RunStatus} status
@@ -159,6 +210,8 @@ export function autoStateFromModelOrHeuristic(modelOutput, latestAssistantText,
 export function applyAutoStateToStatus(status, classification, now = Date.now()) {
 	if (!classification || status.processState === "alive") return false;
 	if (status.semanticState === "failed" || status.semanticState === "stopped") return false;
+	// Manual completions are user verdicts and must never be overwritten.
+	if (isManualCompletion(status)) return false;
 	const nextState = semanticStateForAutoKind(classification.kind);
 	const before = `${status.semanticState}|${status.question ?? ""}|${status.summary ?? ""}|${status.autoState?.source ?? ""}|${status.autoState?.textHash ?? ""}`;
 	status.semanticState = nextState;
@@ -182,6 +235,8 @@ export function applyAutoStateToStatus(status, classification, now = Date.now())
 export function applyAutoStateToViewState(state, classification, now = Date.now()) {
 	if (!classification || state.processState === "alive") return false;
 	if (state.semanticState === "failed" || state.semanticState === "stopped") return false;
+	// Manual completions are user verdicts and must never be overwritten.
+	if (isManualCompletion(state)) return false;
 	const nextState = semanticStateForAutoKind(classification.kind);
 	const before = `${state.semanticState}|${state.question ?? ""}|${state.summary ?? ""}|${state.autoState?.source ?? ""}|${state.autoState?.textHash ?? ""}`;
 	state.semanticState = nextState;

package/src/core/cwd-stats.mjs

@@ -0,0 +1,112 @@
+/**
+ * Persistent cwd usage stats for the launch dialog's directory favorites.
+ *
+ * Counts every successfully dispatched session per cwd, independent of the
+ * view lifecycle (deleting a view does not decrement). The dashboard reads
+ * the ranked list for the cwd picker's favorites mode. Pure node, no Pi imports.
+ */
+import { existsSync } from "node:fs";
+import * as os from "node:os";
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+import { readMeta, readRoster } from "./store.mjs";
+
+/**
+ * @typedef {Object} CwdStatsEntry
+ * @property {number} count
+ * @property {number} lastUsed  epoch ms, like meta.updatedAt
+ */
+
+/** @returns {{version: number, entries: Record<string, CwdStatsEntry>}} */
+function emptyStats() {
+	return { version: 1, entries: {} };
+}
+
+/** @param {string} root @returns {{version: number, entries: Record<string, CwdStatsEntry>}} */
+export function readCwdStats(root) {
+	const raw = readJson(P.cwdStatsPath(root), null);
+	if (!raw || typeof raw !== "object" || typeof raw.entries !== "object" || raw.entries === null) return emptyStats();
+	/** @type {Record<string, CwdStatsEntry>} */
+	const entries = {};
+	for (const [dir, entry] of Object.entries(raw.entries)) {
+		if (!entry || typeof entry.count !== "number") continue;
+		entries[dir] = {
+			count: Math.max(0, Math.floor(entry.count)),
+			lastUsed: typeof entry.lastUsed === "number" ? entry.lastUsed : 0,
+		};
+	}
+	return { version: 1, entries };
+}
+
+/**
+ * One-time seed: aggregate cwd counts from every roster view's meta.json.
+ * No-op when cwd-stats.json already exists.
+ * @param {string} root
+ */
+export function seedCwdStatsFromViews(root) {
+	if (existsSync(P.cwdStatsPath(root))) return;
+	/** @type {Record<string, CwdStatsEntry>} */
+	const entries = {};
+	for (const viewId of readRoster(root).views ?? []) {
+		const meta = readMeta(root, viewId);
+		const cwd = meta?.cwd;
+		if (!cwd) continue;
+		const lastUsed = typeof meta.updatedAt === "number" ? meta.updatedAt : Date.now();
+		const existing = entries[cwd];
+		if (existing) {
+			existing.count += 1;
+			existing.lastUsed = Math.max(existing.lastUsed, lastUsed);
+		} else {
+			entries[cwd] = { count: 1, lastUsed };
+		}
+	}
+	atomicWriteJson(P.cwdStatsPath(root), { version: 1, entries });
+}
+
+/**
+ * Seed when the stats file is missing; tolerate every failure (dashboard UX
+ * must never break because of stats bookkeeping).
+ * @param {string} root
+ */
+export function ensureCwdStatsSeeded(root) {
+	if (existsSync(P.cwdStatsPath(root))) return;
+	try {
+		seedCwdStatsFromViews(root);
+	} catch {
+		/* best effort */
+	}
+}
+
+/**
+ * Record one successful dispatch for `cwd`. Invalid dirs are ignored.
+ * @param {string} root @param {string} cwd
+ */
+export function recordCwdLaunch(root, cwd) {
+	if (!cwd || !existsSync(cwd)) return;
+	const stats = readCwdStats(root);
+	const existing = stats.entries[cwd] ?? { count: 0, lastUsed: 0 };
+	stats.entries[cwd] = { count: existing.count + 1, lastUsed: Date.now() };
+	atomicWriteJson(P.cwdStatsPath(root), stats);
+}
+
+/**
+ * Ranked candidates: count desc, then lastUsed desc; home appended at the
+ * end when absent so the user's home dir is always one keystroke away.
+ * @param {string} root @param {number=} limit
+ * @returns {Array<{path: string, count: number}>}
+ */
+export function rankedCwdCandidates(root, limit = 8) {
+	const stats = readCwdStats(root);
+	const rows = Object.entries(stats.entries).map(([dir, entry]) => ({
+		path: dir,
+		count: entry.count,
+		lastUsed: entry.lastUsed,
+	}));
+	rows.sort((a, b) => b.count - a.count || b.lastUsed - a.lastUsed);
+	const out = rows.slice(0, Math.max(1, limit)).map(({ path, count }) => ({ path, count }));
+	const home = os.homedir();
+	if (out.some((entry) => entry.path === home)) return out;
+	const homeRow = rows.find((entry) => entry.path === home);
+	out.push(homeRow ? { path: home, count: homeRow.count } : { path: home, count: 0 });
+	return out;
+}

package/src/core/derive.mjs

@@ -16,8 +16,8 @@ import { firstSentence, truncate } from "./heuristics.mjs";
 const GENERIC_STATUS_TEXT = {
 	queued: new Set(["Queued"]),
 	working: new Set(["Working", "Working…", "Running", "Running…"]),
-	needs_input: new Set(["Needs input"]),
-	idle: new Set(["Idle", "In Progress"]),
+	needs_input: new Set(["Needs input", "Needs answer"]),
+	idle: new Set(["Idle", "In Progress", "Needs instructions"]),
 	completed: new Set(["Completed", "Done"]),
 	failed: new Set(["Failed"]),
 	stopped: new Set(["Stopped"]),
@@ -50,9 +50,9 @@ export function fallbackStatusText(state) {
 		case "working":
 			return "Running…";
 		case "needs_input":
-			return "Needs input";
+			return "Needs answer";
 		case "idle":
-			return "In Progress";
+			return "Needs instructions";
 		case "completed":
 			return "Done";
 		case "failed":

package/src/core/events.mjs

@@ -122,14 +122,15 @@ export function reduceEvent(status, event, now, opts = {}) {
 				if (msg.errorMessage) status.error = msg.errorMessage;
 				else if (msg.stopReason === "stop") status.error = null;
 				const text = assistantText(msg);
+				let nb = { needsInput: false, question: null };
 				if (text) {
 					// Store the full latest text (truncated) so peek shows meaningful output;
 					// deriveSummary() condenses it to a first sentence for the row.
 					status.latestAssistantPreview = truncate(text, PREVIEW_MAX);
-					const nb = detectNeedsInput(text);
+					nb = detectNeedsInput(text);
 					status.question = nb.question;
 				}
-				status.semanticState = "working";
+				status.semanticState = nb.needsInput ? "needs_input" : "working";
 				preservePendingQuestion(status);
 				status.lastActivityAt = now;
 				status.lastAgentActivityAt = now;

package/src/core/launch-options.mjs

@@ -315,3 +315,50 @@ function existsDir(dir) {
 		return false;
 	}
 }
+
+/**
+ * Keep only candidates whose path is an existing directory.
+ * @param {CwdCandidate[]} candidates
+ * @returns {CwdCandidate[]}
+ */
+export function existingCwdCandidates(candidates) {
+	return candidates.filter((entry) => existsDir(entry.path));
+}
+
+/**
+ * @typedef {Object} CwdCandidate
+ * @property {string} path
+ * @property {number} count
+ */
+
+/**
+ * Filter ranked cwd candidates by case-insensitive substring match anywhere
+ * in the path (empty query keeps the full ranked list).
+ * @param {CwdCandidate[]} candidates
+ * @param {string} query
+ * @returns {CwdCandidate[]}
+ */
+export function filterCwdCandidates(candidates, query) {
+	const q = String(query ?? "").trim().toLowerCase();
+	if (!q) return candidates;
+	return candidates.filter((entry) => entry.path.toLowerCase().includes(q));
+}
+
+/**
+ * Decide cwd picker mode + suggestions for a query: favorites when the query
+ * is empty or matches ranked candidates, filesystem browse otherwise.
+ * @param {string} query
+ * @param {CwdCandidate[]} ranked
+ * @param {string} baseCwd
+ * @returns {{mode: "favorites"|"browse", suggestions: string[]}}
+ */
+export function nextCwdPickerState(query, ranked, baseCwd) {
+	if (!ranked || ranked.length === 0) {
+		return { mode: "browse", suggestions: listDirectorySuggestions(query, baseCwd) };
+	}
+	const matches = filterCwdCandidates(ranked, query);
+	if (String(query ?? "").trim() === "" || matches.length > 0) {
+		return { mode: "favorites", suggestions: matches.map((entry) => entry.path) };
+	}
+	return { mode: "browse", suggestions: listDirectorySuggestions(query, baseCwd) };
+}

package/src/core/paths.mjs

@@ -21,6 +21,8 @@ export const rosterPath = (root) => path.join(root, "roster.json");
 export const launchPrefsPath = (root) => path.join(root, "launch-prefs.json");
 /** @param {string} root */
 export const gcHistoryPath = (root) => path.join(root, "gc-history.jsonl");
+/** @param {string} root */
+export const cwdStatsPath = (root) => path.join(root, "cwd-stats.json");
 
 /** @param {string} root */
 export const viewsDir = (root) => path.join(root, "views");

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

@@ -0,0 +1,112 @@
+/**
+ * Injectable orchestration for the attach jiggle-retry chain.
+ *
+ * Owns the retry state machine, backoff timers, cross-chunk scanning, and the
+ * one-shot re-arm on the child TUI's first frame (\x1b[?2026h). The attach
+ * component (and the cold-start E2E) drive it through injected callbacks, so
+ * the whole choreography is testable without a TUI or socket.
+ *
+ * Cold-start design (issue #10): the chain starts at socket connect, but a cold
+ * child pi-tui installs its SIGWINCH listener only ~5s in — every early jiggle
+ * is lost. When the first TUI frame arrives we re-arm once with a fresh budget,
+ * so the next jiggle lands on a live TUI and its fullRender emits \x1b[2J,
+ * which stops the chain. If pi-tui ever drops the 2026h sequence, this degrades
+ * to the plain connect-time chain (still better than the old one-shot).
+ */
+import {
+	advanceRetry,
+	createJiggleRetryState,
+	feedOutput,
+	nextRetryDelay,
+	stopRetry,
+} from "./pty-attach-jiggle-retry.mjs";
+
+/**
+ * @typedef {Object} JiggleRetryControllerDeps
+ * @property {() => void} sendJiggle - Fire one resize jiggle at the child.
+ * @property {(fn: () => void, ms: number) => unknown} setTimeoutFn - Timer factory.
+ * @property {(timer: unknown) => void} clearTimeoutFn - Timer canceller.
+ * @property {() => boolean} [shouldFire] - Guard on retry fire; false stops the chain without firing.
+ */
+
+/**
+ * @param {JiggleRetryControllerDeps} deps
+ */
+export function createJiggleRetryController(deps) {
+	const { sendJiggle, setTimeoutFn, clearTimeoutFn, shouldFire } = deps;
+	let state = createJiggleRetryState();
+	let carry = "";
+	let tuiFrameSeen = false;
+	/** @type {unknown | null} */
+	let timer = null;
+
+	function clearTimer() {
+		if (timer === null) return;
+		clearTimeoutFn(timer);
+		timer = null;
+	}
+
+	function scheduleNext() {
+		const delay = nextRetryDelay(state);
+		if (delay === null) {
+			state = stopRetry(state);
+			return;
+		}
+		timer = setTimeoutFn(() => {
+			timer = null;
+			if (shouldFire && !shouldFire()) {
+				state = stopRetry(state);
+				return;
+			}
+			sendJiggle();
+			state = advanceRetry(state);
+			scheduleNext();
+		}, delay);
+	}
+
+	/** Reset everything (fresh connection) and schedule the first retry. */
+	function start() {
+		clearTimer();
+		state = createJiggleRetryState();
+		carry = "";
+		tuiFrameSeen = false;
+		scheduleNext();
+	}
+
+	/**
+	 * Feed one socket output chunk. Clear detection wins over re-arm when both
+	 * sequences appear in one chunk (a hot attach's first frame is often the
+	 * fullRender we were waiting for). Re-arm fires at most once per start().
+	 * @param {string} data
+	 */
+	function feed(data) {
+		if (state.clearDetected) return; // chain done; nothing left to detect
+		const result = feedOutput(state, data, carry);
+		state = result.state;
+		carry = result.carry;
+		if (result.clearFound) {
+			clearTimer();
+			state = stopRetry({ ...state, clearDetected: true });
+			return;
+		}
+		if (result.frameStartFound && !tuiFrameSeen && !state.clearDetected) {
+			tuiFrameSeen = true;
+			clearTimer();
+			state = createJiggleRetryState();
+			scheduleNext();
+		}
+	}
+
+	/** Stop the chain (component closed, etc.). */
+	function stop() {
+		clearTimer();
+		state = stopRetry(state);
+	}
+
+	return {
+		start,
+		feed,
+		stop,
+		getState: () => ({ ...state, tuiFrameSeen }),
+	};
+}

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

@@ -1,6 +1,6 @@
 /** Pure logic for attach jiggle-retry: detect full-clear, schedule backoff retries. */
 
-export const BACKOFF_MS = Object.freeze([120, 500, 1500, 3000]);
+export const BACKOFF_MS = Object.freeze([120, 500, 1500, 3000, 6000, 10000, 15000, 20000]);
 export const MAX_RETRIES = BACKOFF_MS.length;
 
 // Verified empirically in issue #2: a resize jiggle makes the child pi-tui run
@@ -10,8 +10,12 @@ export const MAX_RETRIES = BACKOFF_MS.length;
 // signal. If pi-tui ever changes fullRender to skip the clear, the detector
 // silently degrades to the old one-shot behavior after MAX_RETRIES.
 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
+// pi-tui begins every frame (including differential frames) with a synchronized
+// output start sequence; boot-time extension output never contains it, so the
+// first occurrence marks "child TUI has started rendering" (issue #10).
+const TUI_FRAME_START = "\x1b[?2026h";
+/** Carry enough bytes to catch either target sequence split at a chunk boundary. */
+const CARRY_LEN = TUI_FRAME_START.length - 1; // 7 bytes
 
 /**
  * @typedef {Object} JiggleRetryState
@@ -27,18 +31,22 @@ export function createJiggleRetryState() {
 
 /**
  * Feed PTY output data into the state machine.
- * Returns new state, updated carry buffer, and whether a clear was found.
+ * Returns new state, updated carry buffer, and which target sequences were 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 }}
+ * @returns {{ state: JiggleRetryState, carry: string, clearFound: boolean, frameStartFound: boolean }}
  */
 export function feedOutput(state, data, carry) {
 	const combined = carry + data;
 	const clearFound = hasFullClearSequence(combined);
-	const newCarry = clearFound ? "" : tailCarry(combined);
+	const frameStartFound = hasTuiFrameStart(combined);
+	// Always keep the tail carry: a clear hit stops the chain (carry irrelevant), and
+	// a frame-start hit must still preserve a trailing half-sequence so an immediately
+	// following clear split across the next chunk is not missed.
+	const newCarry = tailCarry(combined);
 	const newState = clearFound ? { ...state, clearDetected: true } : state;
-	return { state: newState, carry: newCarry, clearFound };
+	return { state: newState, carry: newCarry, clearFound, frameStartFound };
 }
 
 /**
@@ -79,12 +87,23 @@ export function hasFullClearSequence(data) {
 	return data.includes(FULL_CLEAR);
 }
 
+/**
+ * Check if data contains the TUI frame-start (synchronized output) sequence.
+ * pi-tui begins every frame with \x1b[?2026h; boot-time extension output never
+ * contains it, so the first occurrence marks "child TUI has started rendering".
+ * @param {string} data
+ * @returns {boolean}
+ */
+export function hasTuiFrameStart(data) {
+	return data.includes(TUI_FRAME_START);
+}
+
 /** 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.
+	// We only need to carry up to CARRY_LEN bytes to catch a split \x1b[2J or
+	// \x1b[?2026h. Find the last \x1b in the tail — everything before it can't be
+	// part of a split escape sequence.
 	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) : "";
 }

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

@@ -22,6 +22,27 @@ export function shouldScheduleAttachRenderForMessage(type) {
 
 export const ATTACH_OUTPUT_RENDER_INTERVAL_MS = 40;
 
+/**
+ * Resolve the PTY cursor to an ABSOLUTE buffer row for the projected window
+ * [start, start + height). xterm's buffer cursorY is relative to baseY (the child
+ * terminal's viewport top when scrolled to bottom), so the absolute row is
+ * baseY + cursorY. Returns null when the cursor is outside the projected window
+ * (e.g. the user scrolled up into history).
+ *
+ * The returned row must stay absolute: projection loops pass absolute buffer
+ * indices (buf.getLine(i) for i in [start, end)) and mouse selection points are
+ * absolute too. Returning a start-relative row only matches while start === 0;
+ * once scrollback exists the cursor cell never matches, which silently drops the
+ * visible PTY-cursor block AND the CURSOR_MARKER used to position the hardware
+ * cursor for IME candidate windows.
+ */
+export function projectPtyCursor(buf, start, height) {
+	if (typeof buf.cursorX !== "number" || typeof buf.cursorY !== "number" || buf.cursorX < 0 || buf.cursorY < 0) return null;
+	const row = buf.baseY + buf.cursorY;
+	if (row < start || row >= start + height) return null;
+	return { row, col: buf.cursorX };
+}
+
 /**
  * Coalesce PTY parser callbacks into a bounded stream of repaint requests.
  *