@zhuxixi/pi-agent-board 0.3.0 → 0.4.0

package/src/core/rows.mjs

@@ -36,6 +36,7 @@ import { GROUP_LABELS, GROUP_ORDER, SEMANTIC_STATES } from "./types.mjs";
  * @property {string|null} followUpPreview
  * @property {string} steeringState
  * @property {number} lastActivityAt
+ * @property {number} createdAt
  */
 
 /** @param {Row} row @returns {SemanticState} */
@@ -139,6 +140,7 @@ export function rowView(row, now) {
 		followUpPreview: row.state?.followUps?.lastQueuedPreview ?? null,
 		steeringState: row.state?.steering?.status ?? "none",
 		lastActivityAt,
+		createdAt: row.meta.createdAt ?? 0,
 	};
 }
 
@@ -148,8 +150,9 @@ function oneLine(text) {
 }
 
 /**
- * Group rows by semantic state in GROUP_ORDER. Within a group: pinned first, then most
- * recently active first. Empty groups are omitted.
+ * Group rows by semantic state in GROUP_ORDER. Within a group: pinned first, then
+ * creation order (oldest first) — the order is stable and never reshuffles on activity.
+ * Empty groups are omitted.
  * @param {Row[]} rows
  * @param {number} now
  * @returns {Array<{ state: SemanticState, label: string, rows: RowView[] }>}
@@ -171,7 +174,7 @@ export function groupRows(rows, now) {
  * a single folder renders as a flat list (no redundant folder header).
  * @param {Row[]} rows
  * @param {number} now
- * @returns {Array<{ state: SemanticState, label: string, rowCount: number, showFolders: boolean, folders: Array<{ key: string, name: string, path: string, rows: RowView[], lastActivityAt: number, pinned: boolean }> }>}
+ * @returns {Array<{ state: SemanticState, label: string, rowCount: number, showFolders: boolean, folders: Array<{ key: string, name: string, path: string, rows: RowView[], createdAt: number, pinned: boolean }> }>}
  */
 export function groupRowsByFolder(rows, now) {
 	const views = rows.map((r) => rowView(r, now));
@@ -184,23 +187,35 @@ export function groupRowsByFolder(rows, now) {
 			const key = view.folderKey;
 			const existing = byFolder.get(key);
 			if (existing) existing.rows.push(view);
-			else byFolder.set(key, { key, name: view.folderName, path: view.folderPath, rows: [view], lastActivityAt: view.lastActivityAt, pinned: view.pinned });
+			else byFolder.set(key, { key, name: view.folderName, path: view.folderPath, rows: [view], createdAt: view.createdAt, pinned: view.pinned });
 		}
 		const folders = [...byFolder.values()].map((folder) => {
 			folder.rows = sortRowViews(folder.rows);
-			folder.lastActivityAt = Math.max(...folder.rows.map((r) => r.lastActivityAt));
+			// Folder creation time = its first-created row, so folders keep a stable,
+			// creation-ordered position and don't jump when any row inside gets busy.
+			folder.createdAt = Math.min(...folder.rows.map((r) => r.createdAt));
 			folder.pinned = folder.rows.some((r) => r.pinned);
 			return folder;
-		}).sort((a, b) => Number(b.pinned) - Number(a.pinned) || b.lastActivityAt - a.lastActivityAt || a.name.localeCompare(b.name));
+		}).sort((a, b) => Number(b.pinned) - Number(a.pinned) || a.createdAt - b.createdAt || a.name.localeCompare(b.name));
 		const showFolders = folders.length > 1;
 		groups.push({ state, label: GROUP_LABELS[state], rowCount: inState.length, showFolders, folders });
 	}
 	return groups;
 }
 
-/** @param {RowView[]} views */
+/**
+ * Stable row order: pinned first, then creation order (oldest first), then id.
+ * Activity time deliberately does not participate, so rows never reshuffle while
+ * sessions are running.
+ * @param {RowView[]} views
+ */
 function sortRowViews(views) {
-	return views.sort((a, b) => Number(b.pinned) - Number(a.pinned) || b.lastActivityAt - a.lastActivityAt);
+	return views.sort(
+		(a, b) =>
+			Number(b.pinned) - Number(a.pinned) ||
+			a.createdAt - b.createdAt ||
+			a.id.localeCompare(b.id),
+	);
 }
 
 /** @param {string} path */

package/src/core/types.mjs

@@ -62,12 +62,12 @@ export const GROUP_ORDER = /** @type {const} */ ([
 
 /** Human labels for group headers. @type {Record<SemanticState,string>} */
 export const GROUP_LABELS = {
-	needs_input: "Needs input",
+	needs_input: "Needs answer",
 	working: "Running",
 	queued: "Queued",
 	failed: "Failed",
 	completed: "Done",
-	idle: "In Progress",
+	idle: "Needs instructions",
 	stopped: "Stopped",
 };
 

package/src/runtime/service.mjs

@@ -36,6 +36,7 @@ import {
 	writeLaunchPrefs,
 	writeMeta,
 	writeState,
+	writeStatus,
 } from "../core/store.mjs";
 import { diagnoseNodePtyFailure, ensureNodePtySpawnHelperExecutable, nodePtyFallbackMessage, probeNodePtyEnvironment } from "../core/pty-support.mjs";
 import { normalizeScreenLogMaxBytes, pruneScreenLogs } from "../core/screen-log-gc.mjs";
@@ -270,6 +271,15 @@ export function createService(opts) {
 		state.summary = completionSummary(state);
 		state.lastActivityAt = Date.now();
 		state.updatedAt = Date.now();
+		// Also clear autoState in the run status so in-flight model passes
+		// (job-runner / state-runner) see the manual completion and skip refinement.
+		if (state.currentRunId) {
+			const status = readStatus(root, viewId, state.currentRunId);
+			if (status) {
+				status.autoState = null;
+				writeStatus(root, status);
+			}
+		}
 		writeState(root, state);
 		return { ok: true };
 	}
@@ -753,6 +763,10 @@ export function createService(opts) {
 			return { ok: true, viewId: meta.id, reused: false };
 		},
 
+		getRoot() {
+			return root;
+		},
+
 		getLaunchPrefs() {
 			return readLaunchPrefs(root);
 		},
@@ -958,7 +972,7 @@ export function createService(opts) {
 						s.question = null;
 						s.pendingQuestions = [];
 						s.error = failed ? (s.error ?? row.host.error ?? "PTY host exited unexpectedly") : null;
-						s.summary = failed ? "Failed (PTY host exited)" : "In Progress";
+						s.summary = failed ? "Failed (PTY host exited)" : "Needs instructions";
 						s.updatedAt = now;
 						writeState(root, s);
 						appendDiagnostic(root, row.meta.id, { source: "service", level: failed ? "error" : "info", code: "host_reconciled", message: failed ? "PTY host exited before final event" : "PTY host finalized without final event", details: { hostState: row.host.state, exitCode: row.host.exitCode } });

package/src/ui/dashboard.ts

@@ -17,11 +17,14 @@ import {
 	canonicalModelRef,
 	clampThinkingLevel,
 	listDirectorySuggestions,
+	existingCwdCandidates,
+	nextCwdPickerState,
 	resolveDirectoryValue,
 	resolveLaunchContext,
 	supportedThinkingLevels,
 } from "../core/launch-options.mjs";
 import { createPrewarmScheduler } from "../core/prewarm-schedule.mjs";
+import { ensureCwdStatsSeeded, rankedCwdCandidates, recordCwdLaunch } from "../core/cwd-stats.mjs";
 import { filterRows, groupRowsByFolder, rowState, stateGlyph } from "../core/rows.mjs";
 import { loadSessionView } from "../core/session-view.mjs";
 import { GROUP_LABELS } from "../core/types.mjs";
@@ -81,6 +84,11 @@ interface InputNotice {
 	expiresAt: number;
 }
 
+interface CwdCandidate {
+	path: string;
+	count: number;
+}
+
 interface LaunchState {
 	fieldIndex: number;
 	picker: LaunchPicker;
@@ -89,6 +97,8 @@ interface LaunchState {
 	cwdQuery: string;
 	cwdSuggestions: string[];
 	cwdSuggestionIndex: number;
+	cwdRanked: CwdCandidate[];
+	cwdPickerMode: "favorites" | "browse";
 	choices: LaunchChoice[];
 	scopeSource: "scoped" | "all";
 	model: LaunchModel | null;
@@ -102,6 +112,7 @@ interface LaunchState {
 
 export interface DashboardDeps {
 	service: Service;
+	root: string;
 	defaultCwd: string;
 	availableModels: LaunchModel[];
 	currentModel: LaunchModel | null;
@@ -562,11 +573,24 @@ export class DashboardComponent implements Component {
 			launch.picker = null;
 			return;
 		}
+		if (launch.picker === "cwd" && matchesKey(data, Key.tab)) {
+			if (launch.cwdPickerMode === "favorites" && launch.cwdSuggestions.length > 0) {
+				const completed = launch.cwdSuggestions[launch.cwdSuggestionIndex] ?? launch.cwdSuggestions[0];
+				launch.cwdQuery = completed;
+				const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
+				launch.cwdPickerMode = state.mode;
+				launch.cwdSuggestions = state.suggestions;
+				launch.cwdSuggestionIndex = Math.max(0, state.suggestions.indexOf(completed));
+			}
+			return;
+		}
 		if (launch.picker === "cwd") {
 			const next = this.applyLaunchQueryInput(launch.cwdQuery, data);
 			if (next !== null) {
 				launch.cwdQuery = next;
-				launch.cwdSuggestions = listDirectorySuggestions(next, launch.cwd);
+				const state = nextCwdPickerState(next, launch.cwdRanked, launch.cwd);
+				launch.cwdPickerMode = state.mode;
+				launch.cwdSuggestions = state.suggestions;
 				launch.cwdSuggestionIndex = 0;
 			}
 			return;
@@ -611,6 +635,11 @@ export class DashboardComponent implements Component {
 		const prompt = this.input.trim();
 		if (!prompt) return this.toListMode();
 		const defaults = this.launchDefaults();
+		try {
+			ensureCwdStatsSeeded(this.deps.root);
+		} catch {
+			/* best effort: favorites degrade to browse mode */
+		}
 		this.launch = this.buildLaunchState(defaults.cwd, defaults.model, defaults.thinking);
 		this.mode = "launch";
 		this.inputNotice = null;
@@ -647,7 +676,6 @@ export class DashboardComponent implements Component {
 			thinkingOptions: ThinkingLevel[];
 			scopeSource: "scoped" | "all";
 		};
-		const initialBrowserCwd = homeLaunchRoot(cwd);
 		const modelFiltered = filterLaunchChoices(context.choices, "");
 		const modelIndex = Math.max(0, modelFiltered.findIndex((choice) => sameLaunchModel(choice.model, context.selectedModel)));
 		const thinkingOptions = supportedThinkingLevels(context.selectedModel) as ThinkingLevel[];
@@ -658,9 +686,11 @@ export class DashboardComponent implements Component {
 			picker: null,
 			action: "background",
 			cwd,
-			cwdQuery: initialBrowserCwd,
-			cwdSuggestions: listDirectorySuggestions(initialBrowserCwd, cwd),
+			cwdQuery: "",
+			cwdSuggestions: [],
 			cwdSuggestionIndex: 0,
+			cwdRanked: [],
+			cwdPickerMode: "browse",
 			choices: context.choices,
 			scopeSource: context.scopeSource,
 			model: context.selectedModel,
@@ -678,8 +708,16 @@ export class DashboardComponent implements Component {
 		if (!launch) return;
 		launch.picker = picker;
 		if (picker === "cwd") {
-			launch.cwdQuery = seed ?? launch.cwdQuery ?? homeLaunchRoot(launch.cwd);
-			launch.cwdSuggestions = listDirectorySuggestions(launch.cwdQuery, launch.cwd);
+			try {
+				ensureCwdStatsSeeded(this.deps.root);
+				launch.cwdRanked = existingCwdCandidates(rankedCwdCandidates(this.deps.root, 8));
+			} catch {
+				launch.cwdRanked = [];
+			}
+			launch.cwdQuery = seed ?? "";
+			const state = nextCwdPickerState(launch.cwdQuery, launch.cwdRanked, launch.cwd);
+			launch.cwdPickerMode = state.mode;
+			launch.cwdSuggestions = state.suggestions;
 			launch.cwdSuggestionIndex = 0;
 			return;
 		}
@@ -794,6 +832,11 @@ export class DashboardComponent implements Component {
 		if (!res.ok) this.notice(res.error ?? "Dispatch failed", "error");
 		else {
 			this.lastLaunchPrefs = { ...this.deps.service.getLaunchPrefs?.(), cwd: launchCwd, model: launchModel, thinkingLevel: launchThinking };
+			try {
+				recordCwdLaunch(this.deps.root, launchCwd);
+			} catch {
+				/* best effort: stats must never block dispatch */
+			}
 			try {
 				this.deps.service.saveLaunchPrefs?.(this.lastLaunchPrefs);
 			} catch {
@@ -923,7 +966,7 @@ export class DashboardComponent implements Component {
 			currentRunId: null,
 			semanticState: "idle",
 			processState: "exited",
-			summary: "In Progress",
+			summary: "Needs instructions",
 			lastActivityAt: Date.now(),
 			updatedAt: Date.now(),
 			needsInput: false,
@@ -1474,9 +1517,19 @@ export class DashboardComponent implements Component {
 		lines.push("");
 		if (launch.picker === "cwd") {
 			lines.push(t.fg("warning", `cwd› ${singleLineInput(launch.cwdQuery)}${cursor()}`));
-			lines.push(...this.renderLaunchSuggestions(inner, launch.cwdSuggestions, launch.cwdSuggestionIndex, (value) => displayPath(value)));
-			lines.push("");
-			lines.push(t.fg("dim", "type to filter folders · enter choose · esc back"));
+			if (launch.cwdPickerMode === "favorites") {
+				const counts = new Map(launch.cwdRanked.map((entry) => [entry.path, entry.count]));
+				lines.push(...this.renderLaunchSuggestions(inner, launch.cwdSuggestions, launch.cwdSuggestionIndex, (value) => {
+					const count = counts.get(value) ?? 0;
+					return `${displayPath(value)}${count > 0 ? `  ${count}×` : ""}`;
+				}));
+				lines.push("");
+				lines.push(t.fg("dim", "常用目录 · type to search · tab complete · enter choose · esc back"));
+			} else {
+				lines.push(...this.renderLaunchSuggestions(inner, launch.cwdSuggestions, launch.cwdSuggestionIndex, (value) => displayPath(value)));
+				lines.push("");
+				lines.push(t.fg("dim", "type to filter folders · enter choose · esc back"));
+			}
 		} else if (launch.picker === "model") {
 			lines.push(t.fg("warning", `model› ${singleLineInput(launch.modelQuery)}${cursor()}`));
 			lines.push(...this.renderLaunchSuggestions(inner, launch.modelFiltered, launch.modelIndex, (choice) => `${formatLaunchModel(choice.model)}${choice.thinkingLevel ? ` · ${choice.thinkingLevel}` : ""}`));
@@ -1662,10 +1715,6 @@ function stripBracketedPaste(data: string): string {
 	return data.replace(/\x1b\[200~|\x1b\[201~/g, "");
 }
 
-function homeLaunchRoot(fallback: string): string {
-	return process.env.HOME || process.env.USERPROFILE ? "~" : fallback;
-}
-
 function renderCenteredBox(lines: string[], width: number, height: number, theme: ThemeLike): string[] {
 	const innerWidth = Math.max(20, Math.min(width - 6, Math.max(...lines.map((line) => visibleWidth(line)), 20)));
 	const boxWidth = Math.min(width, innerWidth + 4);
@@ -1754,7 +1803,7 @@ function headerTextRows(
 function headerStageSummary(theme: ThemeLike, counts: HeaderCounts, filterQuery: string, compact: boolean): string {
 	const joiner = theme.fg("dim", " · ");
 	const parts = [
-		headerStagePart(theme, "needs_input", counts.needs, compact ? "awaiting" : "awaiting input"),
+		headerStagePart(theme, "needs_input", counts.needs, compact ? "answer" : "needs answer"),
 		headerStagePart(theme, "working", counts.working, "running"),
 		headerUnreadPart(theme, counts.unread),
 		headerStagePart(theme, "completed", counts.completed, "done"),

package/src/ui/pty-attach.ts

@@ -7,14 +7,8 @@ import type { Component, KeybindingsManager, TUI } from "@earendil-works/pi-tui"
 import { CURSOR_MARKER, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { isProbablyEmptyPiInputLine } from "../core/pty-input.mjs";
 import { findHttpUrlAtCells, findWordRangeAtCells } from "../core/pty-links.mjs";
-import { createAttachOutputRenderScheduler, nextAttachRender, shouldScheduleAttachRenderForMessage } from "../core/pty-attach-render.mjs";
-import {
-	createJiggleRetryState,
-	feedOutput as feedJiggleRetry,
-	nextRetryDelay,
-	advanceRetry,
-	stopRetry,
-} from "../core/pty-attach-jiggle-retry.mjs";
+import { createAttachOutputRenderScheduler, nextAttachRender, projectPtyCursor, shouldScheduleAttachRenderForMessage } from "../core/pty-attach-render.mjs";
+import { createJiggleRetryController } from "../core/pty-attach-jiggle-controller.mjs";
 import { clampInt, parseMouseInputChunk, resolveWheelLines, scrollViewportTop, selectionDragScrollLines } from "../core/pty-scroll.mjs";
 
 export type PtyAttachResult = { action: "detached" } | { action: "closed"; exitCode?: number | null };
@@ -53,6 +47,11 @@ const OSC52_MAX_BYTES = 1_000_000;
 const OSC52_CARRY_MAX_BYTES = OSC52_MAX_BYTES + 4096;
 const TERMINAL_PASSTHROUGH_MAX_BYTES = 5_000_000;
 const TERMINAL_PASSTHROUGH_CARRY_MAX_BYTES = TERMINAL_PASSTHROUGH_MAX_BYTES + 4096;
+/** Delay between the shrink and restore halves of a resize jiggle. 200ms keeps
+ * the two SIGWINCHs apart well beyond pi-tui's 16ms render throttle, so a busy
+ * (booting) child processes them as two separate renders instead of coalescing
+ * the pair into a net-zero size change. */
+const JIGGLE_RESTORE_MS = 200;
 const KITTY_IMAGE_PREFIX = "\x1b_G";
 const ITERM2_FILE_PREFIX = "\x1b]1337;File=";
 
@@ -122,10 +121,19 @@ export class PtyAttachComponent implements Component {
 	private mouseRefreshTimers: Array<ReturnType<typeof setTimeout>> = [];
 	// 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 = "";
+	// garbage has been flushed. The controller re-arms once on the child TUI's
+	// first frame so cold-start attaches get a fresh budget exactly when the
+	// child can finally observe a resize (issue #10).
+	private readonly jiggleRetry = createJiggleRetryController({
+		sendJiggle: () => this.forceChildRedraw(),
+		shouldFire: () => !this.closed && this.connected,
+		setTimeoutFn: (fn, ms) => {
+			const t = setTimeout(fn, ms);
+			t.unref?.();
+			return t;
+		},
+		clearTimeoutFn: (t) => clearTimeout(t as ReturnType<typeof setTimeout>),
+	});
 	private osc52Carry = "";
 	private passthroughCarry = "";
 	private readonly connectStartedAt = Date.now();
@@ -318,7 +326,7 @@ export class PtyAttachComponent implements Component {
 			this.send({ type: "hello", clientId: `ui-${Date.now()}`, wantOutput: true });
 			this.sendResize();
 			this.forceChildRedraw();
-			this.startJiggleRetry();
+			this.jiggleRetry.start();
 			this.enableMouseScroll();
 			this.scheduleRender();
 			this.startAttachSettle();
@@ -804,56 +812,13 @@ export class PtyAttachComponent implements Component {
 				this.sendResize(cols, rows);
 				this.deferAttachSettle();
 			}
-		}, 40);
+		}, JIGGLE_RESTORE_MS);
 		this.redrawTimer.unref?.();
 	}
 
-	/** Start the jiggle retry chain after initial jiggle. */
-	private startJiggleRetry(): void {
-		if (this.jiggleRetryTimer) {
-			clearTimeout(this.jiggleRetryTimer);
-			this.jiggleRetryTimer = null;
-		}
-		this.jiggleRetryState = createJiggleRetryState();
-		this.clearCarry = "";
-		this.scheduleNextJiggleRetry();
-	}
-
-	/** Check socket output for full-clear sequence; cancel retry if found. */
+	/** Feed socket output into the jiggle retry controller (clear/frame detection). */
 	private checkClearSequence(data: string): void {
-		if (this.jiggleRetryState.stopped) return;
-		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) {
-			// Chain exhausted (max retries) — mark stopped so checkClearSequence
-			// short-circuits on subsequent output chunks.
-			this.jiggleRetryState = stopRetry(this.jiggleRetryState);
-			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);
+		this.jiggleRetry.feed(data);
 	}
 
 	private tryScrollBy(linesUp: number): boolean {
@@ -1009,7 +974,7 @@ export class PtyAttachComponent implements Component {
 		// The PTY cursor: xterm buffer cursorY is relative to baseY (the viewport top of
 		// the child terminal); cursorX may equal cols (one past the last cell). Only render
 		// it when it lands inside the projected viewport.
-		const cursor = cursorInViewport(buf, start, height);
+		const cursor = projectPtyCursor(buf, start, height);
 		for (let i = start; i < end; i++) {
 			out.push(lineToAnsi(buf.getLine(i), reusable, this.term, i, selection, cursor));
 		}
@@ -1019,7 +984,7 @@ export class PtyAttachComponent implements Component {
 
 	private close(): void {
 		this.closed = true;
-		this.cancelJiggleRetry();
+		this.jiggleRetry.stop();
 		this.disableMouseScroll();
 		this.clearMouseRefreshTimers();
 		this.clearPendingClick();
@@ -1177,22 +1142,6 @@ function lineToAnsi(
 	return out + "\x1b[0m";
 }
 
-/**
- * Resolve the PTY cursor into viewport coordinates. xterm's buffer cursorY is relative
- * to baseY (the child terminal's viewport top); returns null when the cursor is outside
- * the projected window (e.g. the user scrolled up into history).
- */
-function cursorInViewport(
-	buf: XtermLike["buffer"]["active"],
-	start: number,
-	height: number,
-): { row: number; col: number } | null {
-	if (typeof buf.cursorX !== "number" || typeof buf.cursorY !== "number" || buf.cursorX < 0 || buf.cursorY < 0) return null;
-	const row = buf.baseY + buf.cursorY - start;
-	if (row < 0 || row >= height) return null;
-	return { row, col: buf.cursorX };
-}
-
 function attrKey(cell: BufferCellLike, selected = false, isCursor = false): string {
 	return [
 		selected ? 1 : 0,