@zhuxixi/pi-agent-board 0.3.0

package/src/core/pty-support.mjs

@@ -0,0 +1,327 @@
+/**
+ * Shared node-pty support helpers:
+ * - best-effort self-heal for macOS spawn-helper permissions
+ * - user-facing diagnosis for common PTY startup failures
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, statSync } from "node:fs";
+
+/** @param {import("node:module").Require} requireForPty */
+export function resolveNodePtyPackageRoot(requireForPty) {
+	try {
+		const pkg = requireForPty.resolve("node-pty/package.json");
+		return pkg.slice(0, -"package.json".length);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * @param {import("node:module").Require} requireForPty
+ * @param {string} [platform]
+ * @param {string} [arch]
+ */
+export function nodePtySpawnHelperPaths(requireForPty, platform = process.platform, arch = process.arch) {
+	const root = resolveNodePtyPackageRoot(requireForPty);
+	if (!root) return [];
+	return [`${root}prebuilds/${platform}-${arch}/spawn-helper`, `${root}build/Release/spawn-helper`];
+}
+
+/**
+ * Best-effort chmod for node-pty's spawn-helper. This specifically heals the macOS/npm
+ * packaging issue where the helper lands as 0644 instead of 0755.
+ *
+ * Important: this must never create a false PTY failure for an already-working install.
+ * If the helper already has an execute bit, leave it alone. If chmod itself fails because
+ * the install directory is read-only, swallow that and let the real node-pty probe decide.
+ * @param {import("node:module").Require} requireForPty
+ * @param {string} [platform]
+ * @param {string} [arch]
+ * @returns {string[]} touched helper paths
+ */
+export function ensureNodePtySpawnHelperExecutable(requireForPty, platform = process.platform, arch = process.arch) {
+	const touched = [];
+	for (const helper of nodePtySpawnHelperPaths(requireForPty, platform, arch)) {
+		if (!existsSync(helper)) continue;
+		try {
+			if (Boolean(statSync(helper).mode & 0o111)) continue;
+		} catch {
+			continue;
+		}
+		try {
+			chmodSync(helper, 0o755);
+			touched.push(helper);
+		} catch {
+			/* best effort: a read-only install should not disable PTY if the helper already works */
+		}
+	}
+	return touched;
+}
+
+const RESOLVE_HELPER_COMMAND =
+	`helper=$(node -p "const path=require('path'); const pkg=require.resolve('node-pty/package.json'); path.join(path.dirname(pkg),'prebuilds',process.platform+'-'+process.arch,'spawn-helper')")`;
+const VERIFY_COMMAND =
+	`node -e "const p=require('node-pty').spawn('/bin/echo',['ok'],{name:'xterm-256color',cols:20,rows:5,cwd:process.cwd(),env:process.env}); console.log('node-pty OK'); p.kill()"`;
+const TEMP_WORKAROUND = "AGENT_BOARD_DISABLE_PTY=1 pi /agent-board";
+
+/** @param {string} value */
+function shellQuote(value) {
+	return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+/** @param {string|null|undefined} helperPath @param {string} [label] */
+function helperPathSteps(helperPath, label = "Detected helper path") {
+	if (!helperPath) return ["Resolve the helper path:", RESOLVE_HELPER_COMMAND];
+	return [`${label}:`, helperPath];
+}
+
+/** @param {string|null|undefined} helperPath */
+function chmodHelperCommand(helperPath) {
+	return helperPath ? `chmod +x ${shellQuote(helperPath)}` : `chmod +x "$helper"`;
+}
+
+/** @param {string|null|undefined} helperPath */
+function quarantineHelperCommand(helperPath) {
+	return helperPath ? `xattr -dr com.apple.quarantine ${shellQuote(helperPath)}` : `xattr -dr com.apple.quarantine "$helper"`;
+}
+
+/** @param {string|null|undefined} helperPath */
+function quarantineHelperCommandBestEffort(helperPath) {
+	return helperPath
+		? `xattr -dr com.apple.quarantine ${shellQuote(helperPath)} 2>/dev/null || true`
+		: `xattr -dr com.apple.quarantine "$helper" 2>/dev/null || true`;
+}
+
+/**
+ * @typedef {Object} PtyProbe
+ * @property {string|null} helperPath
+ * @property {boolean|null} helperExists
+ * @property {boolean|null} helperExecutable
+ * @property {boolean|null} helperQuarantined
+ */
+
+/**
+ * @typedef {Object} PtyIssue
+ * @property {string} id
+ * @property {string} title
+ * @property {string} statusLabel
+ * @property {string} summary
+ * @property {string} fixHint
+ * @property {string[]} steps
+ * @property {string} rawReason
+ */
+
+/**
+ * Inspect the installed node-pty helper on disk so we can separate "missing exec bit"
+ * from "quarantined by Gatekeeper" from "helper missing altogether".
+ * @param {import("node:module").Require} requireForPty
+ * @param {string} [platform]
+ * @param {string} [arch]
+ * @returns {PtyProbe}
+ */
+export function probeNodePtyEnvironment(requireForPty, platform = process.platform, arch = process.arch) {
+	const candidates = nodePtySpawnHelperPaths(requireForPty, platform, arch);
+	const helperPath = candidates.find((p) => existsSync(p)) ?? candidates[0] ?? null;
+	if (!helperPath) {
+		return { helperPath: null, helperExists: null, helperExecutable: null, helperQuarantined: null };
+	}
+	const helperExists = existsSync(helperPath);
+	let helperExecutable = null;
+	let helperQuarantined = null;
+	if (helperExists) {
+		try {
+			helperExecutable = Boolean(statSync(helperPath).mode & 0o111);
+		} catch {
+			helperExecutable = null;
+		}
+		if (platform === "darwin") {
+			try {
+				const res = spawnSync("xattr", ["-p", "com.apple.quarantine", helperPath], { encoding: "utf8" });
+				helperQuarantined = res.status === 0 && Boolean(res.stdout?.trim());
+			} catch {
+				helperQuarantined = null;
+			}
+		}
+	}
+	return { helperPath, helperExists, helperExecutable, helperQuarantined };
+}
+
+/** @param {string|null|undefined} reason */
+function cleanReason(reason) {
+	return String(reason || "").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Turn a raw node-pty startup failure into a user-facing explanation + fix steps.
+ * @param {string|null|undefined} reason
+ * @param {{ platform?: string, arch?: string, probe?: PtyProbe|null }} [opts]
+ * @returns {PtyIssue}
+ */
+export function diagnoseNodePtyFailure(reason, opts = {}) {
+	const platform = opts.platform ?? process.platform;
+	const arch = opts.arch ?? process.arch;
+	const probe = opts.probe ?? null;
+	const helperPath = probe?.helperPath ?? null;
+	const rawReason = cleanReason(reason) || "unknown error";
+
+	if (/AGENT_BOARD_DISABLE_PTY=1|AGENT_VIEW_DISABLE_PTY=1/.test(rawReason)) {
+		return {
+			id: "disabled-env",
+			title: "PTY disabled by environment",
+			statusLabel: "disabled by env",
+			summary: "Live PTY is disabled because AGENT_BOARD_DISABLE_PTY=1 is set.",
+			fixHint: "Unset AGENT_BOARD_DISABLE_PTY and retry Agent Board.",
+			steps: ["Unset the env override.", "Retry /agent-board or attach again."],
+			rawReason,
+		};
+	}
+
+	if (/Cannot find module ['\"]node-pty['\"]|Cannot find package ['\"]node-pty['\"]|ERR_MODULE_NOT_FOUND/i.test(rawReason)) {
+		return {
+			id: "missing-module",
+			title: "node-pty dependency missing",
+			statusLabel: "node-pty missing",
+			summary: "Live PTY is disabled because the node-pty dependency is missing.",
+			fixHint: "Reinstall the package so production dependencies are present.",
+			steps: [
+				"For a local checkout, run: npm install",
+				"For an installed package, reinstall agent-board so node-pty is present.",
+				`Temporary workaround: ${TEMP_WORKAROUND}`,
+			],
+			rawReason,
+		};
+	}
+
+	if (/(Could not locate the bindings file|No native build was found|Cannot find module ['\"].*pty\.node['\"]|No prebuilds found)/i.test(rawReason)) {
+		return {
+			id: "native-missing",
+			title: "node-pty native binary missing",
+			statusLabel: "native binary missing",
+			summary: "Live PTY is disabled because node-pty is installed but its native binary is missing for this runtime.",
+			fixHint: `Reinstall or rebuild node-pty under the same Node version and architecture (${platform}-${arch}) that Pi is using.`,
+			steps: [
+				`Confirm runtime: node -p \"process.version + ' ' + process.platform + ' ' + process.arch\"`,
+				"Reinstall dependencies or rebuild native modules under that same runtime.",
+				"For source installs, run npm rebuild node-pty (or npm install) in the package directory.",
+				`Temporary workaround: ${TEMP_WORKAROUND}`,
+			],
+			rawReason,
+		};
+	}
+
+	if (
+		platform === "darwin" &&
+		/(posix_spawnp failed|spawn-helper|permission denied|operation not permitted|eacces|eperm)/i.test(rawReason)
+	) {
+		if (probe?.helperExists === false) {
+			return {
+				id: "macos-spawn-helper-missing",
+				title: "node-pty helper missing",
+				statusLabel: "spawn-helper missing",
+				summary: "Live PTY is disabled because node-pty's macOS spawn-helper file is missing.",
+				fixHint: "Reinstall the package so the darwin helper is restored.",
+				steps: [
+					...helperPathSteps(helperPath, "Expected helper path"),
+					"Reinstall agent-board or run npm install again so node-pty's darwin prebuilds are present.",
+					`Temporary workaround: ${TEMP_WORKAROUND}`,
+				],
+				rawReason,
+			};
+		}
+		if (probe?.helperExecutable === false) {
+			return {
+				id: "macos-spawn-helper-mode",
+				title: "spawn-helper is not executable",
+				statusLabel: "spawn-helper not executable",
+				summary: "Live PTY is disabled because node-pty's spawn-helper does not have execute permission.",
+				fixHint: "Run chmod +x on spawn-helper.",
+				steps: [
+					...helperPathSteps(helperPath),
+					"Grant execute permission:",
+					chmodHelperCommand(helperPath),
+					"Validate node-pty after the fix:",
+					VERIFY_COMMAND,
+					`Temporary workaround: ${TEMP_WORKAROUND}`,
+				],
+				rawReason,
+			};
+		}
+		if (probe?.helperQuarantined) {
+			return {
+				id: "macos-spawn-helper-quarantine",
+				title: "spawn-helper is quarantined",
+				statusLabel: "spawn-helper quarantined",
+				summary: "Live PTY is disabled because macOS Gatekeeper quarantined node-pty's spawn-helper.",
+				fixHint: "Clear the quarantine xattr from spawn-helper.",
+				steps: [
+					...helperPathSteps(helperPath),
+					"Remove the quarantine attribute:",
+					quarantineHelperCommand(helperPath),
+					"Validate node-pty after the fix:",
+					VERIFY_COMMAND,
+					`Temporary workaround: ${TEMP_WORKAROUND}`,
+				],
+				rawReason,
+			};
+		}
+		return {
+			id: "macos-spawn-helper",
+			title: "macOS blocked spawn-helper",
+			statusLabel: "spawn-helper blocked",
+			summary: "Live PTY is disabled because macOS could not execute node-pty's spawn-helper.",
+			fixHint: "Run chmod +x on spawn-helper and clear quarantine if needed.",
+			steps: [
+				...helperPathSteps(helperPath),
+				"Fix permissions and quarantine:",
+				chmodHelperCommand(helperPath),
+				quarantineHelperCommandBestEffort(helperPath),
+				"Validate node-pty after the fix:",
+				VERIFY_COMMAND,
+				`Temporary workaround: ${TEMP_WORKAROUND}`,
+			],
+			rawReason,
+		};
+	}
+
+	if (
+		/(NODE_MODULE_VERSION|module version mismatch|module did not self-register|dlopen\(|mach-o|wrong architecture|incompatible architecture|no suitable image|invalid elf|symbol not found)/i.test(
+			rawReason,
+		)
+	) {
+		return {
+			id: "native-mismatch",
+			title: "node-pty native binary mismatch",
+			statusLabel: "native binary mismatch",
+			summary: "Live PTY is disabled because node-pty's native binary does not match this Node or CPU architecture.",
+			fixHint: `Reinstall node-pty under the same Node version and architecture (${platform}-${arch}) that Pi is using.`,
+			steps: [
+				`Confirm runtime: node -p \"process.version + ' ' + process.platform + ' ' + process.arch\"`,
+				"Reinstall dependencies under that same runtime.",
+				"Avoid mixing Rosetta x64 and native arm64 installs on macOS.",
+				`Temporary workaround: ${TEMP_WORKAROUND}`,
+			],
+			rawReason,
+		};
+	}
+
+	return {
+		id: "generic",
+		title: "node-pty startup probe failed",
+		statusLabel: "startup probe failed",
+		summary: "Live PTY is disabled because node-pty failed its startup probe.",
+		fixHint: "Inspect the raw error, reinstall node-pty, or temporarily disable PTY.",
+		steps: [
+			"Inspect the raw reason below for the underlying system error.",
+			"Reinstall the package dependencies if the problem persists.",
+			`Temporary workaround: ${TEMP_WORKAROUND}`,
+		],
+		rawReason,
+	};
+}
+
+/** @param {{ ok: boolean, reason?: string|null, issue?: PtyIssue|null }} support */
+export function nodePtyFallbackMessage(support) {
+	if (support.ok) return undefined;
+	const issue = support.issue ?? diagnoseNodePtyFailure(support.reason ?? null);
+	return `${issue.summary} Fix: ${issue.fixHint} Press ! for exact steps.`;
+}

package/src/core/repo.mjs

@@ -0,0 +1,47 @@
+/** Git repository identity. Pure node (shells out to `git`); returns null off-repo. */
+import { execFileSync } from "node:child_process";
+
+/**
+ * Resolve the git repo root containing `cwd`, or null if not in a repo.
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+export function gitRepoRoot(cwd) {
+	try {
+		const out = execFileSync("git", ["-C", cwd, "rev-parse", "--show-toplevel"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+		const root = out.trim();
+		return root || null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Whether two directories resolve to the same git repo root.
+ * @param {string|null} rootA
+ * @param {string|null} rootB
+ * @returns {boolean}
+ */
+export function sameRepo(rootA, rootB) {
+	return Boolean(rootA && rootB && rootA === rootB);
+}
+
+/**
+ * Whether the repo has uncommitted changes (dirty). Best-effort; false on error/off-repo.
+ * @param {string} repoRoot
+ * @returns {boolean}
+ */
+export function isDirty(repoRoot) {
+	try {
+		const out = execFileSync("git", ["-C", repoRoot, "status", "--porcelain"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+		return out.trim().length > 0;
+	} catch {
+		return false;
+	}
+}

package/src/core/rows.mjs

@@ -0,0 +1,290 @@
+/**
+ * Pure dashboard logic: turn store Rows into display view-models, group them by
+ * semantic state, and filter them. No pi-tui / theme coupling (the dashboard component
+ * applies colors); everything here is unit-tested.
+ */
+import { normalizeGenericStatusText } from "./derive.mjs";
+import { baseName, relativeTime } from "./heuristics.mjs";
+import { GROUP_LABELS, GROUP_ORDER, SEMANTIC_STATES } from "./types.mjs";
+
+/** @typedef {import("./store.mjs").Row} Row */
+/** @typedef {import("./types.mjs").SemanticState} SemanticState */
+
+/**
+ * @typedef {Object} RowView
+ * @property {string} id
+ * @property {string} name
+ * @property {string} summary
+ * @property {string} age
+ * @property {string} place
+ * @property {string} folderKey
+ * @property {string} folderName
+ * @property {string} folderPath
+ * @property {boolean} pinned
+ * @property {SemanticState} state
+ * @property {boolean} alive
+ * @property {boolean} hostAlive
+ * @property {boolean} needsInput
+ * @property {boolean} hasError
+ * @property {boolean} worktree
+ * @property {boolean} unread
+ * @property {boolean} reviewReady
+ * @property {number} evidenceErrorCount
+ * @property {boolean} diagnosticStalled
+ * @property {number} diagnosticErrorCount
+ * @property {number} followUpCount
+ * @property {string|null} followUpPreview
+ * @property {string} steeringState
+ * @property {number} lastActivityAt
+ */
+
+/** @param {Row} row @returns {SemanticState} */
+export function rowState(row) {
+	return row.state?.semanticState ?? "queued";
+}
+
+/**
+ * State glyph (plain unicode; the dashboard colors it via theme).
+ * @param {SemanticState} state
+ * @param {boolean} alive
+ * @param {boolean} [hostAlive]
+ * @param {boolean} [unread]
+ * @returns {string}
+ */
+export function stateGlyph(state, alive, hostAlive = false, unread = false) {
+	switch (state) {
+		case "needs_input":
+			return unread ? "◆" : "◇";
+		case "working":
+			return alive ? (unread ? "◉" : "●") : (unread ? "◕" : "◐");
+		case "queued":
+			return hostAlive ? (unread ? "◍" : "◌") : (unread ? "◎" : "○");
+		case "completed":
+			return hostAlive ? (unread ? "◍" : "◌") : (unread ? "✔" : "✓");
+		case "failed":
+			return unread ? "✖" : "✗";
+		case "idle":
+			return unread ? "●" : "·";
+		case "stopped":
+			return unread ? "■" : "▪";
+		default:
+			return "?";
+	}
+}
+
+/**
+ * Theme color name appropriate for a state (consumed by the dashboard).
+ * @param {SemanticState} state
+ * @returns {string}
+ */
+export function stateColor(state) {
+	switch (state) {
+		case "needs_input":
+			return "warning";
+		case "working":
+			return "accent";
+		case "queued":
+			return "muted";
+		case "completed":
+			return "success";
+		case "failed":
+			return "error";
+		case "idle":
+			return "dim";
+		case "stopped":
+			return "muted";
+		default:
+			return "text";
+	}
+}
+
+/**
+ * @param {Row} row
+ * @param {number} now
+ * @returns {RowView}
+ */
+export function rowView(row, now) {
+	const state = rowState(row);
+	const summary = oneLine(normalizeGenericStatusText(state, row.state?.summary));
+	const lastActivityAt = row.state?.lastActivityAt ?? row.meta.updatedAt ?? row.meta.createdAt;
+	const worktree = row.meta.worktreeMode === "worktree";
+	const folderPath = row.meta.repoCwd || row.meta.cwd;
+	const folderName = baseName(folderPath) + (worktree ? "⌥" : "");
+	const folderKey = normalizeFolderKey(folderPath);
+	const place = folderName;
+	const lastVisitedAt = row.state?.lastVisitedAt ?? null;
+	const lastAgentActivityAt = row.state?.lastAgentActivityAt ?? null;
+	return {
+		id: row.meta.id,
+		name: row.meta.name,
+		summary,
+		age: relativeTime(lastActivityAt, now),
+		place,
+		folderKey,
+		folderName,
+		folderPath,
+		pinned: Boolean(row.meta.pinned),
+		state,
+		alive: Boolean(row.alive),
+		hostAlive: Boolean(row.hostAlive),
+		needsInput: state === "needs_input",
+		hasError: state === "failed",
+		worktree,
+		unread: lastAgentActivityAt !== null && (lastVisitedAt === null || lastAgentActivityAt > lastVisitedAt),
+		reviewReady: Boolean(row.state?.review?.ready),
+		evidenceErrorCount: row.state?.review?.errorCount ?? 0,
+		diagnosticStalled: Boolean(row.state?.diagnostics?.stalled),
+		diagnosticErrorCount: row.state?.diagnostics?.errorCount ?? 0,
+		followUpCount: row.state?.followUps?.queuedCount ?? 0,
+		followUpPreview: row.state?.followUps?.lastQueuedPreview ?? null,
+		steeringState: row.state?.steering?.status ?? "none",
+		lastActivityAt,
+	};
+}
+
+/** @param {string} text */
+function oneLine(text) {
+	return String(text || "").replace(/\s+/g, " ").trim() || "—";
+}
+
+/**
+ * Group rows by semantic state in GROUP_ORDER. Within a group: pinned first, then most
+ * recently active first. Empty groups are omitted.
+ * @param {Row[]} rows
+ * @param {number} now
+ * @returns {Array<{ state: SemanticState, label: string, rows: RowView[] }>}
+ */
+export function groupRows(rows, now) {
+	const views = rows.map((r) => rowView(r, now));
+	/** @type {Array<{state: SemanticState, label: string, rows: RowView[]}>} */
+	const groups = [];
+	for (const state of GROUP_ORDER) {
+		const inGroup = sortRowViews(views.filter((v) => v.state === state));
+		if (inGroup.length > 0) groups.push({ state, label: GROUP_LABELS[state], rows: inGroup });
+	}
+	return groups;
+}
+
+/**
+ * Group rows first by semantic state, then by repo/folder within that state.
+ * `showFolders` is true only when a stage spans more than one folder, so a stage backed by
+ * 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 }> }>}
+ */
+export function groupRowsByFolder(rows, now) {
+	const views = rows.map((r) => rowView(r, now));
+	const groups = [];
+	for (const state of GROUP_ORDER) {
+		const inState = views.filter((v) => v.state === state);
+		if (inState.length === 0) continue;
+		const byFolder = new Map();
+		for (const view of inState) {
+			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 });
+		}
+		const folders = [...byFolder.values()].map((folder) => {
+			folder.rows = sortRowViews(folder.rows);
+			folder.lastActivityAt = Math.max(...folder.rows.map((r) => r.lastActivityAt));
+			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));
+		const showFolders = folders.length > 1;
+		groups.push({ state, label: GROUP_LABELS[state], rowCount: inState.length, showFolders, folders });
+	}
+	return groups;
+}
+
+/** @param {RowView[]} views */
+function sortRowViews(views) {
+	return views.sort((a, b) => Number(b.pinned) - Number(a.pinned) || b.lastActivityAt - a.lastActivityAt);
+}
+
+/** @param {string} path */
+function normalizeFolderKey(path) {
+	return String(path || "").replace(/\\/g, "/").replace(/\/+$/, "") || "/";
+}
+
+/**
+ * Parse a filter query into a state filter + free-text terms.
+ * Supports `s:<state>` (state prefix) and bare words (AND substring match).
+ * @param {string} query
+ * @returns {{ states: SemanticState[], terms: string[], reviewReady: boolean, diagStalled: boolean, evidenceError: boolean, queued: boolean, steering: string|null }}
+ */
+export function parseFilter(query) {
+	/** @type {Set<SemanticState>} */
+	const states = new Set();
+	/** @type {string[]} */
+	const terms = [];
+	let reviewReady = false;
+	let diagStalled = false;
+	let evidenceError = false;
+	let queued = false;
+	let steering = null;
+	for (const tok of String(query || "").trim().split(/\s+/).filter(Boolean)) {
+		const m = /^s:(.+)$/i.exec(tok);
+		if (m) {
+			const want = normalizeStateToken(m[1]);
+			for (const s of SEMANTIC_STATES) {
+				const aliases = [s, GROUP_LABELS[s]];
+				if (aliases.some((alias) => matchesStateToken(alias, want))) states.add(s);
+			}
+		} else if (/^review:ready$/i.test(tok)) {
+			reviewReady = true;
+		} else if (/^diag:stalled$/i.test(tok)) {
+			diagStalled = true;
+		} else if (/^evidence:error$/i.test(tok)) {
+			evidenceError = true;
+		} else if (/^queued:(true|yes|1)$/i.test(tok)) {
+			queued = true;
+		} else if (/^steer:/i.test(tok)) {
+			steering = normalizeStateToken(tok.replace(/^steer:/i, ""));
+		} else {
+			terms.push(tok.toLowerCase());
+		}
+	}
+	return { states: [...states], terms, reviewReady, diagStalled, evidenceError, queued, steering };
+}
+
+/** @param {string} value */
+function normalizeStateToken(value) {
+	return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+/** @param {string} alias @param {string} want */
+function matchesStateToken(alias, want) {
+	const normalized = normalizeStateToken(alias);
+	return normalized === want || normalized.startsWith(want);
+}
+
+/** @param {string} query @returns {boolean} whether the text is a filter expression. */
+export function isFilterQuery(query) {
+	return /(^|\s)(s:|review:|diag:|evidence:|queued:|steer:)/i.test(query || "");
+}
+
+/**
+ * Filter rows by a query string.
+ * @param {Row[]} rows
+ * @param {string} query
+ * @returns {Row[]}
+ */
+export function filterRows(rows, query) {
+	const { states, terms, reviewReady, diagStalled, evidenceError, queued, steering } = parseFilter(query);
+	if (states.length === 0 && terms.length === 0 && !reviewReady && !diagStalled && !evidenceError && !queued && !steering) return rows;
+	return rows.filter((row) => {
+		if (states.length > 0 && !states.includes(rowState(row))) return false;
+		if (reviewReady && !row.state?.review?.ready) return false;
+		if (diagStalled && !row.state?.diagnostics?.stalled) return false;
+		if (evidenceError && (row.state?.review?.errorCount ?? 0) <= 0) return false;
+		if (queued && (row.state?.followUps?.queuedCount ?? 0) <= 0) return false;
+		if (steering && normalizeStateToken(row.state?.steering?.status ?? "none") !== steering) return false;
+		if (terms.length === 0) return true;
+		const hay = [row.meta.name, row.state?.summary ?? "", row.meta.repoCwd, row.meta.cwd]
+			.join(" ")
+			.toLowerCase();
+		return terms.every((t) => hay.includes(t));
+	});
+}