pi-ui-extend 0.1.1

package/external/pi-tools-suite/src/terminal-bell/index.ts

@@ -0,0 +1,309 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+
+const BELL = "\x07";
+const DEFAULT_IDLE_DELAY_MS = 250;
+const IDLE_RETRY_DELAY_MS = 100;
+const MAX_IDLE_RETRIES = 40;
+const SUBAGENTS_LIVE_COUNT_EVENT = "pi-tools-suite:async-subagents:live-count";
+const DEFAULT_NOTIFICATION_TITLE = "Pi";
+const DEFAULT_NOTIFICATION_MESSAGE = "Session stopped";
+const DEFAULT_ASK_USER_NOTIFICATION_MESSAGE = "Waiting for your answer";
+const DEFAULT_MAC_SOUND = "Glass";
+
+const TERM_PROGRAM_BUNDLE_IDS: Record<string, string> = {
+	Apple_Terminal: "com.apple.Terminal",
+	iTerm: "com.googlecode.iterm2",
+	"iTerm.app": "com.googlecode.iterm2",
+	WezTerm: "com.github.wez.wezterm",
+	WarpTerminal: "dev.warp.Warp-Stable",
+	ghostty: "com.mitchellh.ghostty",
+	Ghostty: "com.mitchellh.ghostty",
+	kitty: "net.kovidgoyal.kitty",
+	Alacritty: "org.alacritty",
+	vscode: "com.microsoft.VSCode",
+	"vscode-insiders": "com.microsoft.VSCodeInsiders",
+	zed: "dev.zed.Zed",
+};
+
+type Timer = ReturnType<typeof setTimeout>;
+
+type SubagentsLiveCountEvent = {
+	count?: unknown;
+};
+
+function parseDelayMs(value: string | undefined): number {
+	if (value === undefined || value.trim() === "") return DEFAULT_IDLE_DELAY_MS;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_IDLE_DELAY_MS;
+}
+
+function isTruthyEnv(value: string | undefined): boolean {
+	if (value === undefined) return false;
+	return ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+
+function extensionDisabled(): boolean {
+	return isTruthyEnv(process.env.HEADLESS) || isTruthyEnv(process.env.PI_TERMINAL_BELL_DISABLED);
+}
+
+function canRingTerminal(): boolean {
+	if (process.env.PI_TERMINAL_BELL === "0") return false;
+	if (process.env.PI_TERMINAL_BELL_FORCE === "1") return true;
+	return Boolean(process.stdout.isTTY || process.stderr.isTTY);
+}
+
+function writeBell(): void {
+	const stream = process.stdout.isTTY || !process.stderr.isTTY ? process.stdout : process.stderr;
+	stream.write(BELL);
+}
+
+function soundEnabled(ctx: ExtensionContext): boolean {
+	if (process.env.PI_TERMINAL_BELL_SOUND === "0") return false;
+	if (process.env.PI_TERMINAL_BELL_SOUND === "1") return true;
+	return ctx.hasUI === true;
+}
+
+function notificationsEnabled(ctx: ExtensionContext): boolean {
+	if (process.env.PI_TERMINAL_BELL_NOTIFY === "0") return false;
+	if (process.env.PI_TERMINAL_BELL_NOTIFY === "1") return true;
+	return ctx.hasUI === true;
+}
+
+function appleScriptString(value: string): string {
+	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function shellSingleQuote(value: string): string {
+	return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function spawnDetached(command: string, args: string[]): void {
+	try {
+		const child = spawn(command, args, { detached: true, stdio: "ignore" });
+		child.on("error", () => {});
+		child.unref();
+	} catch {
+		// Best-effort user attention signal. Missing notification backends should not
+		// affect the agent loop or suppress the terminal bell.
+	}
+}
+
+function findExecutable(command: string): string | undefined {
+	if (command.includes("/")) return existsSync(command) ? command : undefined;
+	for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+		if (!dir) continue;
+		const candidate = join(dir, command);
+		if (existsSync(candidate)) return candidate;
+	}
+	return undefined;
+}
+
+function resolveMacSoundPath(sound: string): string {
+	if (isAbsolute(sound)) return sound;
+	const fileName = sound.endsWith(".aiff") ? sound : `${sound}.aiff`;
+	return `/System/Library/Sounds/${fileName}`;
+}
+
+function detectMacActivationBundleId(): string | undefined {
+	const explicit = process.env.PI_TERMINAL_BELL_NOTIFY_ACTIVATE;
+	if (explicit === "0" || explicit === "false") return undefined;
+	if (explicit && explicit.trim() !== "") return explicit.trim();
+
+	// GUI apps that launch shells on macOS commonly export their own bundle id.
+	// This catches Terminal.app, iTerm2, Zed's terminal, VS Code terminals, etc.
+	const inheritedBundleId = process.env.__CFBundleIdentifier;
+	if (inheritedBundleId && inheritedBundleId.trim() !== "") return inheritedBundleId.trim();
+
+	const termProgram = process.env.TERM_PROGRAM;
+	if (!termProgram) return undefined;
+	return TERM_PROGRAM_BUNDLE_IDS[termProgram];
+}
+
+function playAttentionSound(ctx: ExtensionContext): void {
+	if (!soundEnabled(ctx)) return;
+	if (process.platform !== "darwin") return;
+	const sound = process.env.PI_TERMINAL_BELL_SOUND && process.env.PI_TERMINAL_BELL_SOUND !== "1"
+		? process.env.PI_TERMINAL_BELL_SOUND
+		: DEFAULT_MAC_SOUND;
+	const soundPath = resolveMacSoundPath(sound);
+	if (!existsSync(soundPath)) return;
+	spawnDetached("/usr/bin/afplay", [soundPath]);
+}
+
+function notifySessionStopped(
+	ctx: ExtensionContext,
+	macActivationBundleId: string | undefined,
+	message = process.env.PI_TERMINAL_BELL_NOTIFY_MESSAGE ?? DEFAULT_NOTIFICATION_MESSAGE,
+): void {
+	if (!notificationsEnabled(ctx)) return;
+	const title = process.env.PI_TERMINAL_BELL_NOTIFY_TITLE ?? DEFAULT_NOTIFICATION_TITLE;
+
+	if (process.platform === "darwin") {
+		const terminalNotifier = findExecutable(process.env.PI_TERMINAL_BELL_NOTIFIER ?? "terminal-notifier");
+		if (terminalNotifier) {
+			const args = ["-title", title, "-message", message];
+			const activate = macActivationBundleId;
+			if (activate) {
+				args.push("-activate", activate);
+				args.push("-execute", `/usr/bin/open -b ${shellSingleQuote(activate)}`);
+
+				// Do not pass -sender by default. On recent macOS versions it can make the
+				// notification look like it came from the target app, but then clicking the
+				// “Show” button may be handled as that app's own notification instead of
+				// terminal-notifier's -activate/-execute action.
+				if (process.env.PI_TERMINAL_BELL_NOTIFY_SENDER === "1") {
+					args.push("-sender", activate);
+				}
+			}
+			spawnDetached(terminalNotifier, args);
+			return;
+		}
+
+		// Bare osascript notifications are sent by Script Editor/osascript on macOS;
+		// clicking them can open Script Editor's file picker. Keep that backend opt-in
+		// and prefer terminal-notifier for clickable system notifications.
+		if (process.env.PI_TERMINAL_BELL_NOTIFY_OSASCRIPT !== "1") return;
+		spawnDetached("/usr/bin/osascript", [
+			"-e",
+			`display notification ${appleScriptString(message)} with title ${appleScriptString(title)}`,
+		]);
+		return;
+	}
+
+	if (process.platform === "linux") {
+		spawnDetached("notify-send", [title, message]);
+	}
+}
+
+const ASK_USER_TOOL_NAMES = new Set(["ask_user", "ask_user_question", "question"]);
+
+function isAskUserToolName(toolName: string): boolean {
+	return ASK_USER_TOOL_NAMES.has(toolName);
+}
+
+function isSubagentsWaitTool(toolName: string, args: unknown): boolean {
+	if (toolName === "async_subagents_wait") return true;
+	if (toolName !== "subagents") return false;
+	if (!args || typeof args !== "object") return false;
+	const action = (args as { action?: unknown }).action;
+	return typeof action === "string" && action.trim().toLowerCase() === "wait";
+}
+
+function normalizeLiveCount(event: SubagentsLiveCountEvent): number | undefined {
+	if (typeof event.count !== "number" || !Number.isFinite(event.count)) return undefined;
+	return Math.max(0, Math.floor(event.count));
+}
+
+export default function terminalBell(pi: ExtensionAPI) {
+	if (extensionDisabled()) return;
+
+	let timer: Timer | undefined;
+	let lastCtx: ExtensionContext | undefined;
+	let deferredUntilSubagentsFinish = false;
+	let liveSubagentCount = 0;
+	const activeSubagentWaitToolCallIds = new Set<string>();
+	const notifiedAskUserToolCallIds = new Set<string>();
+	const idleDelayMs = parseDelayMs(process.env.PI_TERMINAL_BELL_DELAY_MS);
+	const macActivationBundleId = process.platform === "darwin" ? detectMacActivationBundleId() : undefined;
+
+	function clearTimer(): void {
+		if (!timer) return;
+		clearTimeout(timer);
+		timer = undefined;
+	}
+
+	function hasSubagentWork(): boolean {
+		return liveSubagentCount > 0 || activeSubagentWaitToolCallIds.size > 0;
+	}
+
+	function notifyAttention(ctx: ExtensionContext, message?: string): void {
+		if (canRingTerminal()) writeBell();
+		playAttentionSound(ctx);
+		notifySessionStopped(ctx, macActivationBundleId, message);
+	}
+
+	function attemptBell(ctx: ExtensionContext, attempt: number): void {
+		timer = undefined;
+
+		if (!ctx.isIdle()) {
+			if (attempt < MAX_IDLE_RETRIES) scheduleBell(ctx, IDLE_RETRY_DELAY_MS, attempt + 1);
+			return;
+		}
+
+		if (ctx.hasPendingMessages()) return;
+
+		if (hasSubagentWork()) {
+			deferredUntilSubagentsFinish = true;
+			return;
+		}
+
+		deferredUntilSubagentsFinish = false;
+		notifyAttention(ctx);
+	}
+
+	function scheduleBell(ctx: ExtensionContext, delayMs = idleDelayMs, attempt = 0): void {
+		lastCtx = ctx;
+		clearTimer();
+		timer = setTimeout(() => attemptBell(ctx, attempt), delayMs);
+		timer.unref?.();
+	}
+
+	function notifyAskUserWaiting(toolCallId: string, ctx: ExtensionContext): void {
+		if (notifiedAskUserToolCallIds.has(toolCallId)) return;
+		notifiedAskUserToolCallIds.add(toolCallId);
+		notifyAttention(ctx, process.env.PI_TERMINAL_BELL_ASK_USER_NOTIFY_MESSAGE ?? DEFAULT_ASK_USER_NOTIFICATION_MESSAGE);
+	}
+
+	pi.events.on(SUBAGENTS_LIVE_COUNT_EVENT, (data: unknown) => {
+		const event = data && typeof data === "object" ? data as SubagentsLiveCountEvent : {};
+		const count = normalizeLiveCount(event);
+		if (count === undefined) return;
+		liveSubagentCount = count;
+		if (count === 0 && deferredUntilSubagentsFinish && lastCtx) {
+			scheduleBell(lastCtx);
+		}
+	});
+
+	pi.on("agent_start", async () => {
+		clearTimer();
+		deferredUntilSubagentsFinish = false;
+		activeSubagentWaitToolCallIds.clear();
+		notifiedAskUserToolCallIds.clear();
+	});
+
+	pi.on("tool_execution_start", async (event, ctx) => {
+		if (isSubagentsWaitTool(event.toolName, event.args)) {
+			activeSubagentWaitToolCallIds.add(event.toolCallId);
+		}
+		if (isAskUserToolName(event.toolName)) {
+			notifyAskUserWaiting(event.toolCallId, ctx);
+		}
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (isAskUserToolName(event.toolName)) {
+			notifyAskUserWaiting(event.toolCallId, ctx);
+		}
+	});
+
+	pi.on("tool_execution_end", async (event) => {
+		activeSubagentWaitToolCallIds.delete(event.toolCallId);
+		notifiedAskUserToolCallIds.delete(event.toolCallId);
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		scheduleBell(ctx);
+	});
+
+	pi.on("session_shutdown", async () => {
+		clearTimer();
+		lastCtx = undefined;
+		deferredUntilSubagentsFinish = false;
+		liveSubagentCount = 0;
+		activeSubagentWaitToolCallIds.clear();
+		notifiedAskUserToolCallIds.clear();
+	});
+}

package/external/pi-tools-suite/src/todo/index.ts

@@ -0,0 +1,201 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { autoClearCompletedTodos } from "./state/auto-clear.js";
+import { loadPersistedPlan, syncPersistedPlan } from "./state/persistence.js";
+import { replayFromBranch } from "./state/replay.js";
+import { ACTIVE_STATUSES, selectVisibleTasks } from "./state/selectors.js";
+import { getState, replaceState } from "./state/store.js";
+import { publishTodoState, registerTodosCommand, registerTodoTool } from "./todo.js";
+
+const TODO_NUDGE_LIMIT = 8;
+const TODO_NUDGE_INITIAL_DELAY_MS = 5_000;
+const TODO_NUDGE_IDLE_RETRY_DELAY_MS = 100;
+const TODO_NUDGE_MAX_IDLE_ATTEMPTS = 40;
+const ASK_USER_TOOL_NAMES = new Set(["ask_user", "ask_user_question", "question"]);
+
+function isAskUserToolName(toolName: string): boolean {
+	return ASK_USER_TOOL_NAMES.has(toolName);
+}
+
+function getUnfinishedTodoNudge(): { signature: string; message: string } | undefined {
+	const unfinished = selectVisibleTasks(getState()).filter((task) => ACTIVE_STATUSES.has(task.status));
+	if (unfinished.length === 0) return undefined;
+
+	const signature = JSON.stringify(
+		unfinished.map((task) => ({
+			id: task.id,
+			status: task.status,
+			subject: task.subject,
+			activeForm: task.activeForm,
+			blockedBy: task.blockedBy ?? [],
+		})),
+	);
+	const shown = unfinished.slice(0, TODO_NUDGE_LIMIT);
+	const hidden = unfinished.length - shown.length;
+	const lines = shown.map((task) => {
+		const activeForm = task.activeForm ? ` — ${task.activeForm}` : "";
+		const blockedBy = task.blockedBy && task.blockedBy.length > 0 ? ` (blocked by #${task.blockedBy.join(", #")})` : "";
+		return `- #${task.id} [${task.status}] ${task.subject}${activeForm}${blockedBy}`;
+	});
+	if (hidden > 0) lines.push(`- …and ${hidden} more unfinished todo item${hidden === 1 ? "" : "s"}.`);
+
+	return {
+		signature,
+		message: [
+			"Todo auto-nudge: unfinished todo items remain after your last response.",
+			"Continue working on them now. Pick exactly one pending/in_progress item, mark it in_progress if needed, make concrete progress, and update or complete todos immediately as work changes.",
+			"If the user added/removed/canceled requirements or changed goal/scope/priority/approach, or if discovered facts make the current plan stale/incomplete/impossible, synchronize todos first: update still-relevant items, defer/delete obsolete ones, add new tasks, and adjust blockers/order.",
+			"If progress is waiting on user-supplied data, clarification, or a decision, defer the affected plan/todos before your final response instead of leaving them pending/in_progress, so auto-nudge stops until the user replies.",
+			"For non-user blockers, leave the current item in_progress and create/update a blocker task instead of stopping.",
+			"",
+			...lines,
+		].join("\n"),
+	};
+}
+
+function getPersistedPlanPrompt(path: string): string | undefined {
+	const unfinished = selectVisibleTasks(getState()).filter((task) => task.status !== "completed");
+	if (unfinished.length === 0) return undefined;
+	const lines = unfinished.slice(0, TODO_NUDGE_LIMIT).map((task) => {
+		const activeForm = task.activeForm ? ` — ${task.activeForm}` : "";
+		const priority = task.priority ? ` (${task.priority})` : "";
+		const blockedBy = task.blockedBy?.length ? ` (blocked by #${task.blockedBy.join(", #")})` : "";
+		return `- #${task.id} [${task.status}]${priority} ${task.subject}${activeForm}${blockedBy}`;
+	});
+	if (unfinished.length > TODO_NUDGE_LIMIT) lines.push(`- …and ${unfinished.length - TODO_NUDGE_LIMIT} more unfinished todo item(s).`);
+	return [
+		`Persisted todo plan loaded from ${path}.`,
+		"Ask the user which item(s) to continue before implementing. Offer a compact choice list based on these active tasks; do not dump the full plan unless asked.",
+		"After the user chooses a scope, run /todos scope <id...> so out-of-scope active tasks become deferred and stop triggering auto-nudges.",
+		"Before resuming implementation, synchronize the loaded plan if the user's current goal/scope/requirements changed or discovered facts make it stale/incomplete: update still-relevant items, defer/delete obsolete ones, add new tasks, and adjust blockers/order.",
+		"Use /todos persist off (or clear) when the plan should be discarded; when all visible tasks are completed, persistence will be disabled and the plan file removed automatically.",
+		"",
+		...lines,
+	].join("\n");
+}
+
+function emitPersistedPlanPrompt(pi: ExtensionAPI, ctx: ExtensionContext, prompt: string): void {
+	if (ctx.hasUI) {
+		pi.sendUserMessage(prompt);
+		return;
+	}
+	console.log(prompt);
+}
+
+export default function (pi: ExtensionAPI) {
+	let lastNudgedSignature: string | undefined;
+	let nudgeTimer: ReturnType<typeof setTimeout> | undefined;
+	const pendingAskUserToolCallIds = new Set<string>();
+
+	function clearNudgeTimer(): void {
+		if (!nudgeTimer) return;
+		clearTimeout(nudgeTimer);
+		nudgeTimer = undefined;
+	}
+
+	function scheduleTodoNudge(ctx: ExtensionContext, attempt = 0): void {
+		clearNudgeTimer();
+		const delayMs = attempt === 0 ? TODO_NUDGE_INITIAL_DELAY_MS : TODO_NUDGE_IDLE_RETRY_DELAY_MS;
+		nudgeTimer = setTimeout(() => {
+			nudgeTimer = undefined;
+			try {
+				if (!ctx.isIdle()) {
+					if (attempt < TODO_NUDGE_MAX_IDLE_ATTEMPTS) scheduleTodoNudge(ctx, attempt + 1);
+					return;
+				}
+				if (ctx.hasPendingMessages()) return;
+
+				const nudge = getUnfinishedTodoNudge();
+				if (!nudge) {
+					lastNudgedSignature = undefined;
+					return;
+				}
+
+				// Avoid an infinite self-nudge loop when the previous nudge did not change
+				// the pending/in_progress todo snapshot.
+				if (nudge.signature === lastNudgedSignature) return;
+				lastNudgedSignature = nudge.signature;
+
+				// agent_end fires before Pi is fully back in idle dispatch. Sending as a
+				// normal user message on the next idle tick reliably starts a fresh turn;
+				// queueing followUp from inside agent_end can be too late to be drained.
+				pi.sendUserMessage(nudge.message);
+			} catch (err) {
+				console.warn(`rpiv-todo: failed to auto-nudge unfinished todos — ${(err as Error).message}`);
+			}
+		}, delayMs);
+	}
+
+	registerTodoTool(pi, {
+		afterCommit: (state, ctx) => {
+			try {
+				const sync = syncPersistedPlan(ctx.cwd, state);
+				if (sync?.completed) console.log(`rpiv-todo: completed persisted plan and removed ${sync.path}`);
+			} catch (err) {
+				console.warn(`rpiv-todo: failed to sync persisted plan — ${(err as Error).message}`);
+			}
+		},
+	});
+	registerTodosCommand(pi);
+
+	pi.on("session_start", async (_event, ctx) => {
+		const persisted = loadPersistedPlan(ctx.cwd);
+		const loaded = autoClearCompletedTodos(persisted?.state ?? replayFromBranch(ctx));
+		replaceState(loaded.state);
+		publishTodoState(pi as any, ctx);
+		if (persisted && loaded.cleared) syncPersistedPlan(ctx.cwd, loaded.state);
+		lastNudgedSignature = undefined;
+		if (persisted) {
+			const prompt = getPersistedPlanPrompt(persisted.path);
+			if (prompt) {
+				emitPersistedPlanPrompt(pi, ctx, prompt);
+				lastNudgedSignature = getUnfinishedTodoNudge()?.signature;
+			}
+		}
+	});
+
+	pi.on("session_compact", async (_event, ctx) => {
+		replaceState(autoClearCompletedTodos(loadPersistedPlan(ctx.cwd)?.state ?? replayFromBranch(ctx)).state);
+		publishTodoState(pi as any, ctx);
+		lastNudgedSignature = undefined;
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		replaceState(autoClearCompletedTodos(loadPersistedPlan(ctx.cwd)?.state ?? replayFromBranch(ctx)).state);
+		publishTodoState(pi as any, ctx);
+		lastNudgedSignature = undefined;
+	});
+
+	pi.on("session_shutdown", async () => {
+		clearNudgeTimer();
+	});
+
+	// Reads getTodos() at render time; do NOT call replayFromBranch here
+	// (branch is stale — message_end runs after tool_execution_end).
+	pi.on("tool_execution_start", async (event) => {
+		if (!isAskUserToolName(event.toolName)) return;
+		pendingAskUserToolCallIds.add(event.toolCallId);
+		clearNudgeTimer();
+	});
+
+	pi.on("tool_execution_end", async (event) => {
+		if (isAskUserToolName(event.toolName)) pendingAskUserToolCallIds.delete(event.toolCallId);
+	});
+
+	pi.on("agent_start", async () => {
+		pendingAskUserToolCallIds.clear();
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		if (pendingAskUserToolCallIds.size > 0) {
+			clearNudgeTimer();
+			return;
+		}
+
+		const nudge = getUnfinishedTodoNudge();
+		if (!nudge) {
+			lastNudgedSignature = undefined;
+			return;
+		}
+		scheduleTodoNudge(ctx);
+	});
+}

package/external/pi-tools-suite/src/todo/state/auto-clear.ts

@@ -0,0 +1,13 @@
+import { EMPTY_STATE, type TaskState } from "./state.js";
+
+export const AUTO_CLEAR_COMPLETED_MESSAGE = "All todos completed; cleared automatically.";
+
+export function shouldAutoClearCompletedTodos(state: TaskState): boolean {
+	const visible = state.tasks.filter((task) => task.status !== "deleted");
+	return visible.length > 0 && visible.every((task) => task.status === "completed");
+}
+
+export function autoClearCompletedTodos(state: TaskState): { state: TaskState; cleared: boolean; count: number } {
+	if (!shouldAutoClearCompletedTodos(state)) return { state, cleared: false, count: 0 };
+	return { state: { ...EMPTY_STATE, tasks: [] }, cleared: true, count: state.tasks.length };
+}

package/external/pi-tools-suite/src/todo/state/invariants.ts

@@ -0,0 +1,21 @@
+import type { TaskStatus } from "../tool/types.js";
+
+/**
+ * Allowed forward transitions per source status. `completed` is one-way to
+ * `deleted` (never back to `in_progress`); `deleted` is terminal.
+ *
+ * Idempotent same→same is checked separately in `isTransitionValid` so this
+ * table only enumerates actual transitions.
+ */
+export const VALID_TRANSITIONS: Record<TaskStatus, ReadonlySet<TaskStatus>> = {
+	pending: new Set(["in_progress", "deferred", "completed", "deleted"]),
+	in_progress: new Set(["pending", "deferred", "completed", "deleted"]),
+	deferred: new Set(["pending", "in_progress", "completed", "deleted"]),
+	completed: new Set(["deleted"]),
+	deleted: new Set(),
+};
+
+export function isTransitionValid(from: TaskStatus, to: TaskStatus): boolean {
+	if (from === to) return true;
+	return VALID_TRANSITIONS[from].has(to);
+}

package/external/pi-tools-suite/src/todo/state/persistence.ts

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Task } from "../tool/types.js";
+import { EMPTY_STATE, type TaskState } from "./state.js";
+
+export const TODO_PLAN_RELATIVE_PATH = join(".pi", "todo-plan.json");
+
+interface PersistedTodoPlan {
+	version: 1;
+	enabled: true;
+	updatedAt: string;
+	nextId: number;
+	tasks: Task[];
+}
+
+export interface PersistedPlanLoadResult {
+	path: string;
+	state: TaskState;
+}
+
+function cloneTask(task: Task): Task {
+	return {
+		...task,
+		blockedBy: task.blockedBy ? [...task.blockedBy] : undefined,
+		tags: task.tags ? [...task.tags] : undefined,
+		metadata: task.metadata ? { ...task.metadata } : undefined,
+	};
+}
+
+function normalizeCwd(cwd: string | undefined): string {
+	return cwd && cwd.trim() ? cwd : process.cwd();
+}
+
+export function getTodoPlanPath(cwd: string | undefined): string {
+	return join(normalizeCwd(cwd), TODO_PLAN_RELATIVE_PATH);
+}
+
+export function isPersistenceEnabled(cwd: string | undefined): boolean {
+	return existsSync(getTodoPlanPath(cwd));
+}
+
+export function loadPersistedPlan(cwd: string | undefined): PersistedPlanLoadResult | undefined {
+	const path = getTodoPlanPath(cwd);
+	if (!existsSync(path)) return undefined;
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<PersistedTodoPlan>;
+		if (raw.version !== 1 || raw.enabled !== true || !Array.isArray(raw.tasks)) return undefined;
+		return {
+			path,
+			state: {
+				tasks: raw.tasks.map(cloneTask),
+				nextId: typeof raw.nextId === "number" && Number.isFinite(raw.nextId) ? raw.nextId : EMPTY_STATE.nextId,
+			},
+		};
+	} catch (err) {
+		console.warn(`rpiv-todo: failed to load persisted plan from ${path} — ${(err as Error).message}`);
+		return undefined;
+	}
+}
+
+export function savePersistedPlan(cwd: string | undefined, state: TaskState): string {
+	const path = getTodoPlanPath(cwd);
+	mkdirSync(dirname(path), { recursive: true });
+	const payload: PersistedTodoPlan = {
+		version: 1,
+		enabled: true,
+		updatedAt: new Date().toISOString(),
+		nextId: state.nextId,
+		tasks: state.tasks.map(cloneTask),
+	};
+	const tmpPath = `${path}.${process.pid}.tmp`;
+	writeFileSync(tmpPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+	renameSync(tmpPath, path);
+	return path;
+}
+
+export function disablePersistence(cwd: string | undefined): string {
+	const path = getTodoPlanPath(cwd);
+	rmSync(path, { force: true });
+	return path;
+}
+
+export function isPlanComplete(state: TaskState): boolean {
+	const visible = state.tasks.filter((task) => task.status !== "deleted");
+	return visible.length === 0 || visible.every((task) => task.status === "completed");
+}
+
+export function syncPersistedPlan(cwd: string | undefined, state: TaskState): { path: string; completed: boolean } | undefined {
+	if (!isPersistenceEnabled(cwd)) return undefined;
+	if (isPlanComplete(state)) {
+		return { path: disablePersistence(cwd), completed: true };
+	}
+	return { path: savePersistedPlan(cwd, state), completed: false };
+}

package/external/pi-tools-suite/src/todo/state/replay.ts

@@ -0,0 +1,38 @@
+import type { TaskDetails } from "../tool/types.js";
+import { EMPTY_STATE, type TaskState } from "./state.js";
+
+/**
+ * Discriminator for `details` envelopes that match the persisted `TaskDetails`
+ * shape. Defensive — branch entries from older or corrupt sessions are
+ * skipped silently.
+ */
+export function isTaskDetails(value: unknown): value is TaskDetails {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	return Array.isArray(v.tasks) && typeof v.nextId === "number";
+}
+
+/**
+ * Walk the current branch in chronological order; the LAST `toolResult` whose
+ * `toolName === "todo"` and whose `details` shape matches `TaskDetails` wins
+ * (last-write-wins). When no matching entry exists, returns `EMPTY_STATE`.
+ *
+ * Pure of module state — `index.ts` writes the returned snapshot into the
+ * store after this returns. The function explicitly does NOT touch the store
+ * cell.
+ */
+export function replayFromBranch(ctx: { sessionManager: { getBranch(): Iterable<unknown> } }): TaskState {
+	let result: TaskState = { tasks: [...EMPTY_STATE.tasks], nextId: EMPTY_STATE.nextId };
+	for (const entry of ctx.sessionManager.getBranch()) {
+		const e = entry as { type?: string; message?: { role?: string; toolName?: string; details?: unknown } };
+		if (e.type !== "message") continue;
+		const msg = e.message;
+		if (!msg || msg.role !== "toolResult" || msg.toolName !== "todo") continue;
+		if (!isTaskDetails(msg.details)) continue;
+		result = {
+			tasks: msg.details.tasks.map((t) => ({ ...t })),
+			nextId: msg.details.nextId,
+		};
+	}
+	return result;
+}