mitsupi 1.0.0 → 1.0.2

package/pi-extensions/todos.ts

@@ -0,0 +1,1651 @@
+/**
+ * Todo storage settings are kept in <todo-dir>/settings.json.
+ *
+ * Defaults:
+ * {
+ *   "gc": true,   // delete closed todos older than gcDays on startup
+ *   "gcDays": 7   // age threshold for GC (days since created_at)
+ * }
+ */
+import { DynamicBorder, getMarkdownTheme, keyHint, type ExtensionAPI, type ExtensionContext, type Theme } from "@mariozechner/pi-coding-agent";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import crypto from "node:crypto";
+import {
+	Container,
+	type Focusable,
+	Input,
+	Key,
+	Markdown,
+	SelectList,
+	Spacer,
+	type SelectItem,
+	Text,
+	TUI,
+	fuzzyMatch,
+	getEditorKeybindings,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+} from "@mariozechner/pi-tui";
+
+const TODO_DIR_NAME = ".pi/todos";
+const TODO_PATH_ENV = "PI_ISSUE_PATH";
+const TODO_SETTINGS_NAME = "settings.json";
+const TODO_ID_PREFIX = "TODO-";
+const DEFAULT_TODO_SETTINGS = {
+	gc: true,
+	gcDays: 7,
+};
+const LOCK_TTL_MS = 30 * 60 * 1000;
+
+interface TodoFrontMatter {
+	id: string;
+	title: string;
+	tags: string[];
+	status: string;
+	created_at: string;
+}
+
+interface TodoRecord extends TodoFrontMatter {
+	body: string;
+}
+
+interface LockInfo {
+	id: string;
+	pid: number;
+	session?: string | null;
+	created_at: string;
+}
+
+interface TodoSettings {
+	gc: boolean;
+	gcDays: number;
+}
+
+const TodoParams = Type.Object({
+	action: StringEnum(["list", "list-all", "get", "create", "update", "append", "delete"] as const),
+	id: Type.Optional(
+		Type.String({ description: "Todo id (TODO-<hex> or raw hex filename)" }),
+	),
+	title: Type.Optional(Type.String({ description: "Short summary shown in lists" })),
+	status: Type.Optional(Type.String({ description: "Todo status" })),
+	tags: Type.Optional(Type.Array(Type.String({ description: "Todo tag" }))),
+	body: Type.Optional(
+		Type.String({ description: "Long-form details (markdown). Update replaces; append adds." }),
+	),
+});
+
+type TodoAction = "list" | "list-all" | "get" | "create" | "update" | "append" | "delete";
+
+type TodoOverlayAction = "work" | "refine" | "close" | "reopen" | "delete" | "cancel" | "actions";
+
+type TodoMenuAction = TodoOverlayAction | "copy-path" | "close-dialog" | "view";
+
+type TodoToolDetails =
+	| { action: "list" | "list-all"; todos: TodoFrontMatter[]; error?: string }
+	| { action: "get" | "create" | "update" | "append" | "delete"; todo: TodoRecord; error?: string };
+
+function formatTodoId(id: string): string {
+	return `${TODO_ID_PREFIX}${id}`;
+}
+
+function normalizeTodoId(id: string): string {
+	let trimmed = id.trim();
+	if (trimmed.startsWith("#")) {
+		trimmed = trimmed.slice(1);
+	}
+	if (trimmed.toUpperCase().startsWith(TODO_ID_PREFIX)) {
+		trimmed = trimmed.slice(TODO_ID_PREFIX.length);
+	}
+	return trimmed;
+}
+
+function displayTodoId(id: string): string {
+	return formatTodoId(normalizeTodoId(id));
+}
+
+function isTodoClosed(status: string): boolean {
+	return ["closed", "done"].includes(status.toLowerCase());
+}
+
+function sortTodos(todos: TodoFrontMatter[]): TodoFrontMatter[] {
+	return [...todos].sort((a, b) => {
+		const aClosed = isTodoClosed(a.status);
+		const bClosed = isTodoClosed(b.status);
+		if (aClosed !== bClosed) return aClosed ? 1 : -1;
+		return (a.created_at || "").localeCompare(b.created_at || "");
+	});
+}
+
+function buildTodoSearchText(todo: TodoFrontMatter): string {
+	const tags = todo.tags.join(" ");
+	return `${formatTodoId(todo.id)} ${todo.id} ${todo.title} ${tags} ${todo.status}`.trim();
+}
+
+function filterTodos(todos: TodoFrontMatter[], query: string): TodoFrontMatter[] {
+	const trimmed = query.trim();
+	if (!trimmed) return todos;
+
+	const tokens = trimmed
+		.split(/\s+/)
+		.map((token) => token.trim())
+		.filter(Boolean);
+
+	if (tokens.length === 0) return todos;
+
+	const matches: Array<{ todo: TodoFrontMatter; score: number }> = [];
+	for (const todo of todos) {
+		const text = buildTodoSearchText(todo);
+		let totalScore = 0;
+		let matched = true;
+		for (const token of tokens) {
+			const result = fuzzyMatch(token, text);
+			if (!result.matches) {
+				matched = false;
+				break;
+			}
+			totalScore += result.score;
+		}
+		if (matched) {
+			matches.push({ todo, score: totalScore });
+		}
+	}
+
+	return matches
+		.sort((a, b) => {
+			const aClosed = isTodoClosed(a.todo.status);
+			const bClosed = isTodoClosed(b.todo.status);
+			if (aClosed !== bClosed) return aClosed ? 1 : -1;
+			return a.score - b.score;
+		})
+		.map((match) => match.todo);
+}
+
+class TodoSelectorComponent extends Container implements Focusable {
+	private searchInput: Input;
+	private listContainer: Container;
+	private allTodos: TodoFrontMatter[];
+	private filteredTodos: TodoFrontMatter[];
+	private selectedIndex = 0;
+	private onSelectCallback: (todo: TodoFrontMatter) => void;
+	private onCancelCallback: () => void;
+	private tui: TUI;
+	private theme: Theme;
+	private headerText: Text;
+	private hintText: Text;
+
+	private _focused = false;
+	get focused(): boolean {
+		return this._focused;
+	}
+	set focused(value: boolean) {
+		this._focused = value;
+		this.searchInput.focused = value;
+	}
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		todos: TodoFrontMatter[],
+		onSelect: (todo: TodoFrontMatter) => void,
+		onCancel: () => void,
+		initialSearchInput?: string,
+		private onQuickAction?: (todo: TodoFrontMatter, action: "work" | "refine") => void,
+	) {
+		super();
+		this.tui = tui;
+		this.theme = theme;
+		this.allTodos = todos;
+		this.filteredTodos = todos;
+		this.onSelectCallback = onSelect;
+		this.onCancelCallback = onCancel;
+
+		this.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+		this.addChild(new Spacer(1));
+
+		this.headerText = new Text("", 1, 0);
+		this.addChild(this.headerText);
+		this.addChild(new Spacer(1));
+
+		this.searchInput = new Input();
+		if (initialSearchInput) {
+			this.searchInput.setValue(initialSearchInput);
+		}
+		this.searchInput.onSubmit = () => {
+			const selected = this.filteredTodos[this.selectedIndex];
+			if (selected) this.onSelectCallback(selected);
+		};
+		this.addChild(this.searchInput);
+
+		this.addChild(new Spacer(1));
+		this.listContainer = new Container();
+		this.addChild(this.listContainer);
+
+		this.addChild(new Spacer(1));
+		this.hintText = new Text("", 1, 0);
+		this.addChild(this.hintText);
+		this.addChild(new Spacer(1));
+		this.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+		this.updateHeader();
+		this.updateHints();
+		this.applyFilter(this.searchInput.getValue());
+	}
+
+	setTodos(todos: TodoFrontMatter[]): void {
+		this.allTodos = todos;
+		this.updateHeader();
+		this.applyFilter(this.searchInput.getValue());
+		this.tui.requestRender();
+	}
+
+	getSearchValue(): string {
+		return this.searchInput.getValue();
+	}
+
+	private updateHeader(): void {
+		const openCount = this.allTodos.filter((todo) => !isTodoClosed(todo.status)).length;
+		const closedCount = this.allTodos.length - openCount;
+		const title = `Todos (${openCount} open, ${closedCount} closed)`;
+		this.headerText.setText(this.theme.fg("accent", this.theme.bold(title)));
+	}
+
+	private updateHints(): void {
+		this.hintText.setText(
+			this.theme.fg(
+				"dim",
+				"Type to search • ↑↓ select • Enter actions • Ctrl+Shift+W work • Ctrl+Shift+R refine • Esc close",
+			),
+		);
+	}
+
+	private applyFilter(query: string): void {
+		this.filteredTodos = filterTodos(this.allTodos, query);
+		this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, this.filteredTodos.length - 1));
+		this.updateList();
+	}
+
+	private updateList(): void {
+		this.listContainer.clear();
+
+		if (this.filteredTodos.length === 0) {
+			this.listContainer.addChild(new Text(this.theme.fg("muted", "  No matching todos"), 0, 0));
+			return;
+		}
+
+		const maxVisible = 10;
+		const startIndex = Math.max(
+			0,
+			Math.min(this.selectedIndex - Math.floor(maxVisible / 2), this.filteredTodos.length - maxVisible),
+		);
+		const endIndex = Math.min(startIndex + maxVisible, this.filteredTodos.length);
+
+		for (let i = startIndex; i < endIndex; i += 1) {
+			const todo = this.filteredTodos[i];
+			if (!todo) continue;
+			const isSelected = i === this.selectedIndex;
+			const closed = isTodoClosed(todo.status);
+			const prefix = isSelected ? this.theme.fg("accent", "→ ") : "  ";
+			const titleColor = isSelected ? "accent" : closed ? "dim" : "text";
+			const statusColor = closed ? "dim" : "success";
+			const tagText = todo.tags.length ? ` [${todo.tags.join(", ")}]` : "";
+			const line =
+				prefix +
+				this.theme.fg("accent", formatTodoId(todo.id)) +
+				" " +
+				this.theme.fg(titleColor, todo.title || "(untitled)") +
+				this.theme.fg("muted", tagText) +
+				" " +
+				this.theme.fg(statusColor, `(${todo.status || "open"})`);
+			this.listContainer.addChild(new Text(line, 0, 0));
+		}
+
+		if (startIndex > 0 || endIndex < this.filteredTodos.length) {
+			const scrollInfo = this.theme.fg(
+				"dim",
+				`  (${this.selectedIndex + 1}/${this.filteredTodos.length})`,
+			);
+			this.listContainer.addChild(new Text(scrollInfo, 0, 0));
+		}
+	}
+
+	handleInput(keyData: string): void {
+		const kb = getEditorKeybindings();
+		if (kb.matches(keyData, "selectUp")) {
+			if (this.filteredTodos.length === 0) return;
+			this.selectedIndex = this.selectedIndex === 0 ? this.filteredTodos.length - 1 : this.selectedIndex - 1;
+			this.updateList();
+			return;
+		}
+		if (kb.matches(keyData, "selectDown")) {
+			if (this.filteredTodos.length === 0) return;
+			this.selectedIndex = this.selectedIndex === this.filteredTodos.length - 1 ? 0 : this.selectedIndex + 1;
+			this.updateList();
+			return;
+		}
+		if (kb.matches(keyData, "selectConfirm")) {
+			const selected = this.filteredTodos[this.selectedIndex];
+			if (selected) this.onSelectCallback(selected);
+			return;
+		}
+		if (kb.matches(keyData, "selectCancel")) {
+			this.onCancelCallback();
+			return;
+		}
+		if (matchesKey(keyData, Key.ctrlShift("r"))) {
+			const selected = this.filteredTodos[this.selectedIndex];
+			if (selected && this.onQuickAction) this.onQuickAction(selected, "refine");
+			return;
+		}
+		if (matchesKey(keyData, Key.ctrlShift("w"))) {
+			const selected = this.filteredTodos[this.selectedIndex];
+			if (selected && this.onQuickAction) this.onQuickAction(selected, "work");
+			return;
+		}
+		this.searchInput.handleInput(keyData);
+		this.applyFilter(this.searchInput.getValue());
+	}
+
+	override invalidate(): void {
+		super.invalidate();
+		this.updateHeader();
+		this.updateHints();
+		this.updateList();
+	}
+}
+
+class TodoDetailOverlayComponent {
+	private todo: TodoRecord;
+	private theme: Theme;
+	private tui: TUI;
+	private markdown: Markdown;
+	private scrollOffset = 0;
+	private viewHeight = 0;
+	private totalLines = 0;
+	private onAction: (action: TodoOverlayAction) => void;
+
+	constructor(tui: TUI, theme: Theme, todo: TodoRecord, onAction: (action: TodoOverlayAction) => void) {
+		this.tui = tui;
+		this.theme = theme;
+		this.todo = todo;
+		this.onAction = onAction;
+		this.markdown = new Markdown(this.getMarkdownText(), 1, 0, getMarkdownTheme());
+	}
+
+	private getMarkdownText(): string {
+		const body = this.todo.body?.trim();
+		return body ? body : "_No details yet._";
+	}
+
+	handleInput(keyData: string): void {
+		const kb = getEditorKeybindings();
+		if (kb.matches(keyData, "selectCancel")) {
+			this.onAction("cancel");
+			return;
+		}
+		if (kb.matches(keyData, "selectUp")) {
+			this.scrollBy(-1);
+			return;
+		}
+		if (kb.matches(keyData, "selectDown")) {
+			this.scrollBy(1);
+			return;
+		}
+		if (kb.matches(keyData, "selectPageUp")) {
+			this.scrollBy(-this.viewHeight || -1);
+			return;
+		}
+		if (kb.matches(keyData, "selectPageDown")) {
+			this.scrollBy(this.viewHeight || 1);
+			return;
+		}
+		if (keyData === "r" || keyData === "R") {
+			this.onAction("refine");
+			return;
+		}
+		if (keyData === "c" || keyData === "C") {
+			this.onAction("close");
+			return;
+		}
+		if (keyData === "o" || keyData === "O") {
+			this.onAction("reopen");
+			return;
+		}
+		if (keyData === "w" || keyData === "W") {
+			this.onAction("work");
+			return;
+		}
+		if (keyData === "a" || keyData === "A") {
+			this.onAction("actions");
+			return;
+		}
+		if (keyData === "d" || keyData === "D") {
+			this.onAction("delete");
+			return;
+		}
+	}
+
+	render(width: number): string[] {
+		const maxHeight = this.getMaxHeight();
+		const headerLines = 3;
+		const footerLines = 3;
+		const borderLines = 2;
+		const innerWidth = Math.max(10, width - 2);
+		const contentHeight = Math.max(1, maxHeight - headerLines - footerLines - borderLines);
+
+		const markdownLines = this.markdown.render(innerWidth);
+		this.totalLines = markdownLines.length;
+		this.viewHeight = contentHeight;
+		const maxScroll = Math.max(0, this.totalLines - contentHeight);
+		this.scrollOffset = Math.max(0, Math.min(this.scrollOffset, maxScroll));
+
+		const visibleLines = markdownLines.slice(this.scrollOffset, this.scrollOffset + contentHeight);
+		const lines: string[] = [];
+
+		lines.push(this.buildTitleLine(innerWidth));
+		lines.push(this.buildMetaLine(innerWidth));
+		lines.push("");
+
+		for (const line of visibleLines) {
+			lines.push(truncateToWidth(line, innerWidth));
+		}
+		while (lines.length < headerLines + contentHeight) {
+			lines.push("");
+		}
+
+		lines.push("");
+		lines.push(this.buildActionLine(innerWidth));
+
+		const borderColor = (text: string) => this.theme.fg("borderMuted", text);
+		const top = borderColor(`┌${"─".repeat(innerWidth)}┐`);
+		const bottom = borderColor(`└${"─".repeat(innerWidth)}┘`);
+		const framedLines = lines.map((line) => {
+			const truncated = truncateToWidth(line, innerWidth);
+			const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+			return borderColor("│") + truncated + " ".repeat(padding) + borderColor("│");
+		});
+
+		return [top, ...framedLines, bottom].map((line) => truncateToWidth(line, width));
+	}
+
+	invalidate(): void {
+		this.markdown = new Markdown(this.getMarkdownText(), 1, 0, getMarkdownTheme());
+	}
+
+	private getMaxHeight(): number {
+		const rows = this.tui.terminal.rows || 24;
+		return Math.max(10, Math.floor(rows * 0.8));
+	}
+
+	private buildTitleLine(width: number): string {
+		const titleText = this.todo.title
+			? ` ${this.todo.title} `
+			: ` Todo ${formatTodoId(this.todo.id)} `;
+		const titleWidth = visibleWidth(titleText);
+		if (titleWidth >= width) {
+			return truncateToWidth(this.theme.fg("accent", titleText.trim()), width);
+		}
+		const leftWidth = Math.max(0, Math.floor((width - titleWidth) / 2));
+		const rightWidth = Math.max(0, width - titleWidth - leftWidth);
+		return (
+			this.theme.fg("borderMuted", "─".repeat(leftWidth)) +
+			this.theme.fg("accent", titleText) +
+			this.theme.fg("borderMuted", "─".repeat(rightWidth))
+		);
+	}
+
+	private buildMetaLine(width: number): string {
+		const status = this.todo.status || "open";
+		const statusColor = isTodoClosed(status) ? "dim" : "success";
+		const tagText = this.todo.tags.length ? this.todo.tags.join(", ") : "no tags";
+		const line =
+			this.theme.fg("accent", formatTodoId(this.todo.id)) +
+			this.theme.fg("muted", " • ") +
+			this.theme.fg(statusColor, status) +
+			this.theme.fg("muted", " • ") +
+			this.theme.fg("muted", tagText);
+		return truncateToWidth(line, width);
+	}
+
+	private buildActionLine(width: number): string {
+		const closed = isTodoClosed(this.todo.status);
+		const refine = this.theme.fg("accent", "r") + this.theme.fg("muted", " refine task");
+		const work = this.theme.fg("accent", "w") + this.theme.fg("muted", " work on todo");
+		const close = this.theme.fg("accent", "c") + this.theme.fg("muted", " close task");
+		const reopen = this.theme.fg("accent", "o") + this.theme.fg("muted", " reopen task");
+		const statusAction = closed ? reopen : close;
+		const actions = this.theme.fg("accent", "a") + this.theme.fg("muted", " actions");
+		const del = this.theme.fg("error", "d") + this.theme.fg("muted", " delete todo");
+		const back = this.theme.fg("dim", "esc back");
+		const pieces = [work, refine, statusAction, actions, del, back];
+
+		let line = pieces.join(this.theme.fg("muted", " • "));
+		if (this.totalLines > this.viewHeight) {
+			const start = Math.min(this.totalLines, this.scrollOffset + 1);
+			const end = Math.min(this.totalLines, this.scrollOffset + this.viewHeight);
+			const scrollInfo = this.theme.fg("dim", ` ${start}-${end}/${this.totalLines}`);
+			line += scrollInfo;
+		}
+
+		return truncateToWidth(line, width);
+	}
+
+	private scrollBy(delta: number): void {
+		const maxScroll = Math.max(0, this.totalLines - this.viewHeight);
+		this.scrollOffset = Math.max(0, Math.min(this.scrollOffset + delta, maxScroll));
+	}
+}
+
+function getTodosDir(cwd: string): string {
+	const overridePath = process.env[TODO_PATH_ENV];
+	if (overridePath && overridePath.trim()) {
+		return path.resolve(cwd, overridePath.trim());
+	}
+	return path.resolve(cwd, TODO_DIR_NAME);
+}
+
+function getTodoSettingsPath(todosDir: string): string {
+	return path.join(todosDir, TODO_SETTINGS_NAME);
+}
+
+function normalizeTodoSettings(raw: Partial<TodoSettings>): TodoSettings {
+	const gc = raw.gc ?? DEFAULT_TODO_SETTINGS.gc;
+	const gcDays = Number.isFinite(raw.gcDays) ? raw.gcDays : DEFAULT_TODO_SETTINGS.gcDays;
+	return {
+		gc: Boolean(gc),
+		gcDays: Math.max(0, Math.floor(gcDays)),
+	};
+}
+
+async function readTodoSettings(todosDir: string): Promise<TodoSettings> {
+	const settingsPath = getTodoSettingsPath(todosDir);
+	let data: Partial<TodoSettings> = {};
+	let shouldWrite = false;
+
+	try {
+		const raw = await fs.readFile(settingsPath, "utf8");
+		data = JSON.parse(raw) as Partial<TodoSettings>;
+	} catch {
+		shouldWrite = true;
+	}
+
+	const normalized = normalizeTodoSettings(data);
+	if (
+		shouldWrite ||
+		data.gc === undefined ||
+		data.gcDays === undefined ||
+		!Number.isFinite(data.gcDays)
+	) {
+		await fs.writeFile(settingsPath, JSON.stringify(normalized, null, 2) + "\n", "utf8");
+	}
+
+	return normalized;
+}
+
+async function garbageCollectTodos(todosDir: string, settings: TodoSettings): Promise<void> {
+	if (!settings.gc) return;
+
+	let entries: string[] = [];
+	try {
+		entries = await fs.readdir(todosDir);
+	} catch {
+		return;
+	}
+
+	const cutoff = Date.now() - settings.gcDays * 24 * 60 * 60 * 1000;
+	await Promise.all(
+		entries
+			.filter((entry) => entry.endsWith(".md"))
+			.map(async (entry) => {
+				const id = entry.slice(0, -3);
+				const filePath = path.join(todosDir, entry);
+				try {
+					const content = await fs.readFile(filePath, "utf8");
+					const { frontMatter } = splitFrontMatter(content);
+					const parsed = parseFrontMatter(frontMatter, id);
+					if (!isTodoClosed(parsed.status)) return;
+					const createdAt = Date.parse(parsed.created_at);
+					if (!Number.isFinite(createdAt)) return;
+					if (createdAt < cutoff) {
+						await fs.unlink(filePath);
+					}
+				} catch {
+					// ignore unreadable todo
+				}
+			}),
+	);
+}
+
+function getTodoPath(todosDir: string, id: string): string {
+	return path.join(todosDir, `${id}.md`);
+}
+
+function getLockPath(todosDir: string, id: string): string {
+	return path.join(todosDir, `${id}.lock`);
+}
+
+function stripQuotes(value: string): string {
+	const trimmed = value.trim();
+	if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+		return trimmed.slice(1, -1);
+	}
+	return trimmed;
+}
+
+function parseTagsInline(value: string): string[] {
+	const inner = value.trim().slice(1, -1);
+	if (!inner.trim()) return [];
+	return inner
+		.split(",")
+		.map((item) => stripQuotes(item))
+		.map((item) => item.trim())
+		.filter(Boolean);
+}
+
+function parseFrontMatter(text: string, idFallback: string): TodoFrontMatter {
+	const data: TodoFrontMatter = {
+		id: idFallback,
+		title: "",
+		tags: [],
+		status: "open",
+		created_at: "",
+	};
+
+	let currentKey: string | null = null;
+	for (const rawLine of text.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line) continue;
+
+		const listMatch = currentKey === "tags" ? line.match(/^-\s*(.+)$/) : null;
+		if (listMatch) {
+			data.tags.push(stripQuotes(listMatch[1]));
+			continue;
+		}
+
+		const match = line.match(/^(?<key>[a-zA-Z0-9_]+):\s*(?<value>.*)$/);
+		if (!match?.groups) continue;
+
+		const key = match.groups.key;
+		const value = match.groups.value ?? "";
+		currentKey = null;
+
+		if (key === "tags") {
+			if (!value) {
+				currentKey = "tags";
+				continue;
+			}
+			if (value.startsWith("[") && value.endsWith("]")) {
+				data.tags = parseTagsInline(value);
+				continue;
+			}
+			data.tags = [stripQuotes(value)].filter(Boolean);
+			continue;
+		}
+
+		switch (key) {
+			case "id":
+				data.id = stripQuotes(value) || data.id;
+				break;
+			case "title":
+				data.title = stripQuotes(value);
+				break;
+			case "status":
+				data.status = stripQuotes(value) || data.status;
+				break;
+			case "created_at":
+				data.created_at = stripQuotes(value);
+				break;
+			default:
+				break;
+		}
+	}
+
+	return data;
+}
+
+function splitFrontMatter(content: string): { frontMatter: string; body: string } {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+	if (!match) {
+		return { frontMatter: "", body: content };
+	}
+	const frontMatter = match[1] ?? "";
+	const body = content.slice(match[0].length);
+	return { frontMatter, body };
+}
+
+function parseTodoContent(content: string, idFallback: string): TodoRecord {
+	const { frontMatter, body } = splitFrontMatter(content);
+	const parsed = parseFrontMatter(frontMatter, idFallback);
+	return {
+		id: idFallback,
+		title: parsed.title,
+		tags: parsed.tags ?? [],
+		status: parsed.status,
+		created_at: parsed.created_at,
+		body: body ?? "",
+	};
+}
+
+function escapeYaml(value: string): string {
+	return value.replace(/\\/g, "\\\\").replace(/\"/g, "\\\"");
+}
+
+function serializeTodo(todo: TodoRecord): string {
+	const tags = todo.tags ?? [];
+	const lines = [
+		"---",
+		`id: \"${escapeYaml(todo.id)}\"`,
+		`title: \"${escapeYaml(todo.title)}\"`,
+		"tags:",
+		...tags.map((tag) => `  - \"${escapeYaml(tag)}\"`),
+		`status: \"${escapeYaml(todo.status)}\"`,
+		`created_at: \"${escapeYaml(todo.created_at)}\"`,
+		"---",
+		"",
+	];
+
+	const body = todo.body ?? "";
+	const trimmedBody = body.replace(/^\n+/, "").replace(/\s+$/, "");
+	return `${lines.join("\n")}${trimmedBody ? `${trimmedBody}\n` : ""}`;
+}
+
+async function ensureTodosDir(todosDir: string) {
+	await fs.mkdir(todosDir, { recursive: true });
+}
+
+async function readTodoFile(filePath: string, idFallback: string): Promise<TodoRecord> {
+	const content = await fs.readFile(filePath, "utf8");
+	return parseTodoContent(content, idFallback);
+}
+
+async function writeTodoFile(filePath: string, todo: TodoRecord) {
+	await fs.writeFile(filePath, serializeTodo(todo), "utf8");
+}
+
+async function generateTodoId(todosDir: string): Promise<string> {
+	for (let attempt = 0; attempt < 10; attempt += 1) {
+		const id = crypto.randomBytes(4).toString("hex");
+		const todoPath = getTodoPath(todosDir, id);
+		if (!existsSync(todoPath)) return id;
+	}
+	throw new Error("Failed to generate unique todo id");
+}
+
+async function readLockInfo(lockPath: string): Promise<LockInfo | null> {
+	try {
+		const raw = await fs.readFile(lockPath, "utf8");
+		return JSON.parse(raw) as LockInfo;
+	} catch {
+		return null;
+	}
+}
+
+async function acquireLock(
+	todosDir: string,
+	id: string,
+	ctx: ExtensionContext,
+): Promise<(() => Promise<void>) | { error: string }> {
+	const lockPath = getLockPath(todosDir, id);
+	const now = Date.now();
+	const session = ctx.sessionManager.getSessionFile();
+
+	for (let attempt = 0; attempt < 2; attempt += 1) {
+		try {
+			const handle = await fs.open(lockPath, "wx");
+			const info: LockInfo = {
+				id,
+				pid: process.pid,
+				session,
+				created_at: new Date(now).toISOString(),
+			};
+			await handle.writeFile(JSON.stringify(info, null, 2), "utf8");
+			await handle.close();
+			return async () => {
+				try {
+					await fs.unlink(lockPath);
+				} catch {
+					// ignore
+				}
+			};
+		} catch (error: any) {
+			if (error?.code !== "EEXIST") {
+				return { error: `Failed to acquire lock: ${error?.message ?? "unknown error"}` };
+			}
+			const stats = await fs.stat(lockPath).catch(() => null);
+			const lockAge = stats ? now - stats.mtimeMs : LOCK_TTL_MS + 1;
+			if (lockAge <= LOCK_TTL_MS) {
+				const info = await readLockInfo(lockPath);
+				const owner = info?.session ? ` (session ${info.session})` : "";
+				return { error: `Todo ${displayTodoId(id)} is locked${owner}. Try again later.` };
+			}
+			if (!ctx.hasUI) {
+				return { error: `Todo ${displayTodoId(id)} lock is stale; rerun in interactive mode to steal it.` };
+			}
+			const ok = await ctx.ui.confirm(
+				"Todo locked",
+				`Todo ${displayTodoId(id)} appears locked. Steal the lock?`,
+			);
+			if (!ok) {
+				return { error: `Todo ${displayTodoId(id)} remains locked.` };
+			}
+			await fs.unlink(lockPath).catch(() => undefined);
+		}
+	}
+
+	return { error: `Failed to acquire lock for todo ${displayTodoId(id)}.` };
+}
+
+async function withTodoLock<T>(
+	todosDir: string,
+	id: string,
+	ctx: ExtensionContext,
+	fn: () => Promise<T>,
+): Promise<T | { error: string }> {
+	const lock = await acquireLock(todosDir, id, ctx);
+	if (typeof lock === "object" && "error" in lock) return lock;
+	try {
+		return await fn();
+	} finally {
+		await lock();
+	}
+}
+
+async function listTodos(todosDir: string): Promise<TodoFrontMatter[]> {
+	let entries: string[] = [];
+	try {
+		entries = await fs.readdir(todosDir);
+	} catch {
+		return [];
+	}
+
+	const todos: TodoFrontMatter[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".md")) continue;
+		const id = entry.slice(0, -3);
+		const filePath = path.join(todosDir, entry);
+		try {
+			const content = await fs.readFile(filePath, "utf8");
+			const { frontMatter } = splitFrontMatter(content);
+			const parsed = parseFrontMatter(frontMatter, id);
+			todos.push({
+				id,
+				title: parsed.title,
+				tags: parsed.tags ?? [],
+				status: parsed.status,
+				created_at: parsed.created_at,
+			});
+		} catch {
+			// ignore unreadable todo
+		}
+	}
+
+	return sortTodos(todos);
+}
+
+function listTodosSync(todosDir: string): TodoFrontMatter[] {
+	let entries: string[] = [];
+	try {
+		entries = readdirSync(todosDir);
+	} catch {
+		return [];
+	}
+
+	const todos: TodoFrontMatter[] = [];
+	for (const entry of entries) {
+		if (!entry.endsWith(".md")) continue;
+		const id = entry.slice(0, -3);
+		const filePath = path.join(todosDir, entry);
+		try {
+			const content = readFileSync(filePath, "utf8");
+			const { frontMatter } = splitFrontMatter(content);
+			const parsed = parseFrontMatter(frontMatter, id);
+			todos.push({
+				id,
+				title: parsed.title,
+				tags: parsed.tags ?? [],
+				status: parsed.status,
+				created_at: parsed.created_at,
+			});
+		} catch {
+			// ignore
+		}
+	}
+
+	return sortTodos(todos);
+}
+
+function getTodoTitle(todo: TodoFrontMatter): string {
+	return todo.title || "(untitled)";
+}
+
+function getTodoStatus(todo: TodoFrontMatter): string {
+	return todo.status || "open";
+}
+
+function formatTodoHeading(todo: TodoFrontMatter): string {
+	const tagText = todo.tags.length ? ` [${todo.tags.join(", ")}]` : "";
+	return `${formatTodoId(todo.id)} ${getTodoTitle(todo)}${tagText}`;
+}
+
+function buildRefinePrompt(todoId: string, title: string): string {
+	return (
+		`let's refine task ${formatTodoId(todoId)} "${title}": ` +
+		"Please rewrite the todo body with a thorough, structured description so an engineer or agent can work without extra investigation. " +
+		"Include: Context, Goals, Scope/Non-scope, Checklist, Acceptance Criteria, and Risks/Open questions.\n\n"
+	);
+}
+
+function splitTodosByStatus(todos: TodoFrontMatter[]): { openTodos: TodoFrontMatter[]; closedTodos: TodoFrontMatter[] } {
+	const openTodos: TodoFrontMatter[] = [];
+	const closedTodos: TodoFrontMatter[] = [];
+	for (const todo of todos) {
+		if (isTodoClosed(getTodoStatus(todo))) {
+			closedTodos.push(todo);
+		} else {
+			openTodos.push(todo);
+		}
+	}
+	return { openTodos, closedTodos };
+}
+
+function formatTodoList(todos: TodoFrontMatter[]): string {
+	if (!todos.length) return "No todos.";
+
+	const { openTodos } = splitTodosByStatus(todos);
+	const lines: string[] = [];
+	const pushSection = (label: string, sectionTodos: TodoFrontMatter[]) => {
+		lines.push(`${label} (${sectionTodos.length}):`);
+		if (!sectionTodos.length) {
+			lines.push("  none");
+			return;
+		}
+		for (const todo of sectionTodos) {
+			lines.push(`  ${formatTodoHeading(todo)}`);
+		}
+	};
+
+	pushSection("Open todos", openTodos);
+	return lines.join("\n");
+}
+
+function serializeTodoForAgent(todo: TodoRecord): string {
+	const payload = { ...todo, id: formatTodoId(todo.id) };
+	return JSON.stringify(payload, null, 2);
+}
+
+function serializeTodoListForAgent(todos: TodoFrontMatter[]): string {
+	const { openTodos, closedTodos } = splitTodosByStatus(todos);
+	const mapTodo = (todo: TodoFrontMatter) => ({ ...todo, id: formatTodoId(todo.id) });
+	return JSON.stringify(
+		{
+			open: openTodos.map(mapTodo),
+			closed: closedTodos.map(mapTodo),
+		},
+		null,
+		2,
+	);
+}
+
+function renderTodoHeading(theme: Theme, todo: TodoFrontMatter): string {
+	const closed = isTodoClosed(getTodoStatus(todo));
+	const titleColor = closed ? "dim" : "text";
+	const tagText = todo.tags.length ? theme.fg("dim", ` [${todo.tags.join(", ")}]`) : "";
+	return (
+		theme.fg("accent", formatTodoId(todo.id)) +
+		" " +
+		theme.fg(titleColor, getTodoTitle(todo)) +
+		tagText
+	);
+}
+
+function renderTodoList(theme: Theme, todos: TodoFrontMatter[], expanded: boolean): string {
+	if (!todos.length) return theme.fg("dim", "No todos");
+
+	const { openTodos, closedTodos } = splitTodosByStatus(todos);
+	const lines: string[] = [];
+	const pushSection = (label: string, sectionTodos: TodoFrontMatter[]) => {
+		lines.push(theme.fg("muted", `${label} (${sectionTodos.length})`));
+		if (!sectionTodos.length) {
+			lines.push(theme.fg("dim", "  none"));
+			return;
+		}
+		const maxItems = expanded ? sectionTodos.length : Math.min(sectionTodos.length, 3);
+		for (let i = 0; i < maxItems; i++) {
+			lines.push(`  ${renderTodoHeading(theme, sectionTodos[i])}`);
+		}
+		if (!expanded && sectionTodos.length > maxItems) {
+			lines.push(theme.fg("dim", `  ... ${sectionTodos.length - maxItems} more`));
+		}
+	};
+
+	pushSection("Open todos", openTodos);
+	if (expanded && closedTodos.length) {
+		lines.push("");
+		pushSection("Closed todos", closedTodos);
+	}
+	return lines.join("\n");
+}
+
+function renderTodoDetail(theme: Theme, todo: TodoRecord, expanded: boolean): string {
+	const summary = renderTodoHeading(theme, todo);
+	if (!expanded) return summary;
+
+	const tags = todo.tags.length ? todo.tags.join(", ") : "none";
+	const createdAt = todo.created_at || "unknown";
+	const bodyText = todo.body?.trim() ? todo.body.trim() : "No details yet.";
+	const bodyLines = bodyText.split("\n");
+
+	const lines = [
+		summary,
+		theme.fg("muted", `Status: ${getTodoStatus(todo)}`),
+		theme.fg("muted", `Tags: ${tags}`),
+		theme.fg("muted", `Created: ${createdAt}`),
+		"",
+		theme.fg("muted", "Body:"),
+		...bodyLines.map((line) => theme.fg("text", `  ${line}`)),
+	];
+
+	return lines.join("\n");
+}
+
+function appendExpandHint(theme: Theme, text: string): string {
+	return `${text}\n${theme.fg("dim", `(${keyHint("expandTools", "to expand")})`)}`;
+}
+
+async function ensureTodoExists(filePath: string, id: string): Promise<TodoRecord | null> {
+	if (!existsSync(filePath)) return null;
+	return readTodoFile(filePath, id);
+}
+
+async function appendTodoBody(filePath: string, todo: TodoRecord, text: string): Promise<TodoRecord> {
+	const spacer = todo.body.trim().length ? "\n\n" : "";
+	todo.body = `${todo.body.replace(/\s+$/, "")}${spacer}${text.trim()}\n`;
+	await writeTodoFile(filePath, todo);
+	return todo;
+}
+
+async function updateTodoStatus(
+	todosDir: string,
+	id: string,
+	status: string,
+	ctx: ExtensionContext,
+): Promise<TodoRecord | { error: string }> {
+	const normalizedId = normalizeTodoId(id);
+	const filePath = getTodoPath(todosDir, normalizedId);
+	if (!existsSync(filePath)) {
+		return { error: `Todo ${displayTodoId(id)} not found` };
+	}
+
+	const result = await withTodoLock(todosDir, normalizedId, ctx, async () => {
+		const existing = await ensureTodoExists(filePath, normalizedId);
+		if (!existing) return { error: `Todo ${displayTodoId(id)} not found` } as const;
+		existing.status = status;
+		await writeTodoFile(filePath, existing);
+		return existing;
+	});
+
+	if (typeof result === "object" && "error" in result) {
+		return { error: result.error };
+	}
+
+	return result;
+}
+
+async function deleteTodo(
+	todosDir: string,
+	id: string,
+	ctx: ExtensionContext,
+): Promise<TodoRecord | { error: string }> {
+	const normalizedId = normalizeTodoId(id);
+	const filePath = getTodoPath(todosDir, normalizedId);
+	if (!existsSync(filePath)) {
+		return { error: `Todo ${displayTodoId(id)} not found` };
+	}
+
+	const result = await withTodoLock(todosDir, normalizedId, ctx, async () => {
+		const existing = await ensureTodoExists(filePath, normalizedId);
+		if (!existing) return { error: `Todo ${displayTodoId(id)} not found` } as const;
+		await fs.unlink(filePath);
+		return existing;
+	});
+
+	if (typeof result === "object" && "error" in result) {
+		return { error: result.error };
+	}
+
+	return result;
+}
+
+export default function todosExtension(pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		const todosDir = getTodosDir(ctx.cwd);
+		await ensureTodosDir(todosDir);
+		const settings = await readTodoSettings(todosDir);
+		await garbageCollectTodos(todosDir, settings);
+	});
+
+	pi.registerTool({
+		name: "todo",
+		label: "Todo",
+		description:
+			"Manage file-based todos in .pi/todos (list, list-all, get, create, update, append, delete). " +
+			"Title is the short summary; body is long-form markdown notes (update replaces, append adds). " +
+			"Todo ids are shown as TODO-<hex>; id parameters accept TODO-<hex> or the raw hex filename. " +
+			"Close todos when the work is done. Set PI_ISSUE_PATH to override the todo directory.",
+		parameters: TodoParams,
+
+		async execute(_toolCallId, params, _onUpdate, ctx) {
+			const todosDir = getTodosDir(ctx.cwd);
+			const action: TodoAction = params.action;
+
+			switch (action) {
+				case "list": {
+					const todos = await listTodos(todosDir);
+					const { openTodos } = splitTodosByStatus(todos);
+					return {
+						content: [{ type: "text", text: serializeTodoListForAgent(openTodos) }],
+						details: { action: "list", todos: openTodos },
+					};
+				}
+
+				case "list-all": {
+					const todos = await listTodos(todosDir);
+					return {
+						content: [{ type: "text", text: serializeTodoListForAgent(todos) }],
+						details: { action: "list-all", todos },
+					};
+				}
+
+				case "get": {
+					if (!params.id) {
+						return {
+							content: [{ type: "text", text: "Error: id required" }],
+							details: { action: "get", error: "id required" },
+						};
+					}
+					const normalizedId = normalizeTodoId(params.id);
+					const displayId = displayTodoId(params.id);
+					const filePath = getTodoPath(todosDir, normalizedId);
+					const todo = await ensureTodoExists(filePath, normalizedId);
+					if (!todo) {
+						return {
+							content: [{ type: "text", text: `Todo ${displayId} not found` }],
+							details: { action: "get", error: "not found" },
+						};
+					}
+					return {
+						content: [{ type: "text", text: serializeTodoForAgent(todo) }],
+						details: { action: "get", todo },
+					};
+				}
+
+				case "create": {
+					if (!params.title) {
+						return {
+							content: [{ type: "text", text: "Error: title required" }],
+							details: { action: "create", error: "title required" },
+						};
+					}
+					await ensureTodosDir(todosDir);
+					const id = await generateTodoId(todosDir);
+					const filePath = getTodoPath(todosDir, id);
+					const todo: TodoRecord = {
+						id,
+						title: params.title,
+						tags: params.tags ?? [],
+						status: params.status ?? "open",
+						created_at: new Date().toISOString(),
+						body: params.body ?? "",
+					};
+
+					const result = await withTodoLock(todosDir, id, ctx, async () => {
+						await writeTodoFile(filePath, todo);
+						return todo;
+					});
+
+					if (typeof result === "object" && "error" in result) {
+						return {
+							content: [{ type: "text", text: result.error }],
+							details: { action: "create", error: result.error },
+						};
+					}
+
+					return {
+						content: [{ type: "text", text: serializeTodoForAgent(todo) }],
+						details: { action: "create", todo },
+					};
+				}
+
+				case "update": {
+					if (!params.id) {
+						return {
+							content: [{ type: "text", text: "Error: id required" }],
+							details: { action: "update", error: "id required" },
+						};
+					}
+					const normalizedId = normalizeTodoId(params.id);
+					const displayId = displayTodoId(params.id);
+					const filePath = getTodoPath(todosDir, normalizedId);
+					if (!existsSync(filePath)) {
+						return {
+							content: [{ type: "text", text: `Todo ${displayId} not found` }],
+							details: { action: "update", error: "not found" },
+						};
+					}
+					const result = await withTodoLock(todosDir, normalizedId, ctx, async () => {
+						const existing = await ensureTodoExists(filePath, normalizedId);
+						if (!existing) return { error: `Todo ${displayId} not found` } as const;
+
+						existing.id = normalizedId;
+						if (params.title !== undefined) existing.title = params.title;
+						if (params.status !== undefined) existing.status = params.status;
+						if (params.tags !== undefined) existing.tags = params.tags;
+						if (params.body !== undefined) existing.body = params.body;
+						if (!existing.created_at) existing.created_at = new Date().toISOString();
+
+						await writeTodoFile(filePath, existing);
+						return existing;
+					});
+
+					if (typeof result === "object" && "error" in result) {
+						return {
+							content: [{ type: "text", text: result.error }],
+							details: { action: "update", error: result.error },
+						};
+					}
+
+					const updatedTodo = result as TodoRecord;
+					return {
+						content: [{ type: "text", text: serializeTodoForAgent(updatedTodo) }],
+						details: { action: "update", todo: updatedTodo },
+					};
+				}
+
+				case "append": {
+					if (!params.id) {
+						return {
+							content: [{ type: "text", text: "Error: id required" }],
+							details: { action: "append", error: "id required" },
+						};
+					}
+					const normalizedId = normalizeTodoId(params.id);
+					const displayId = displayTodoId(params.id);
+					const filePath = getTodoPath(todosDir, normalizedId);
+					if (!existsSync(filePath)) {
+						return {
+							content: [{ type: "text", text: `Todo ${displayId} not found` }],
+							details: { action: "append", error: "not found" },
+						};
+					}
+					const result = await withTodoLock(todosDir, normalizedId, ctx, async () => {
+						const existing = await ensureTodoExists(filePath, normalizedId);
+						if (!existing) return { error: `Todo ${displayId} not found` } as const;
+						if (!params.body || !params.body.trim()) {
+							return existing;
+						}
+						const updated = await appendTodoBody(filePath, existing, params.body);
+						return updated;
+					});
+
+					if (typeof result === "object" && "error" in result) {
+						return {
+							content: [{ type: "text", text: result.error }],
+							details: { action: "append", error: result.error },
+						};
+					}
+
+					const updatedTodo = result as TodoRecord;
+					return {
+						content: [{ type: "text", text: serializeTodoForAgent(updatedTodo) }],
+						details: { action: "append", todo: updatedTodo },
+					};
+				}
+
+				case "delete": {
+					if (!params.id) {
+						return {
+							content: [{ type: "text", text: "Error: id required" }],
+							details: { action: "delete", error: "id required" },
+						};
+					}
+
+					const normalizedId = normalizeTodoId(params.id);
+					const result = await deleteTodo(todosDir, normalizedId, ctx);
+					if (typeof result === "object" && "error" in result) {
+						return {
+							content: [{ type: "text", text: result.error }],
+							details: { action: "delete", error: result.error },
+						};
+					}
+
+					return {
+						content: [{ type: "text", text: serializeTodoForAgent(result as TodoRecord) }],
+						details: { action: "delete", todo: result as TodoRecord },
+					};
+				}
+			}
+		},
+
+
+		renderCall(args, theme) {
+			const action = typeof args.action === "string" ? args.action : "";
+			const id = typeof args.id === "string" ? args.id : "";
+			const normalizedId = id ? normalizeTodoId(id) : "";
+			const title = typeof args.title === "string" ? args.title : "";
+			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", action);
+			if (normalizedId) {
+				text += " " + theme.fg("accent", formatTodoId(normalizedId));
+			}
+			if (title) {
+				text += " " + theme.fg("dim", `"${title}"`);
+			}
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded, isPartial }, theme) {
+			const details = result.details as TodoToolDetails | undefined;
+			if (isPartial) {
+				return new Text(theme.fg("warning", "Processing..."), 0, 0);
+			}
+			if (!details) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+
+			if (details.error) {
+				return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+			}
+
+			if (details.action === "list" || details.action === "list-all") {
+				let text = renderTodoList(theme, details.todos, expanded);
+				if (!expanded) {
+					const { closedTodos } = splitTodosByStatus(details.todos);
+					if (closedTodos.length) {
+						text = appendExpandHint(theme, text);
+					}
+				}
+				return new Text(text, 0, 0);
+			}
+
+			if (!details.todo) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+
+			let text = renderTodoDetail(theme, details.todo, expanded);
+			const actionLabel =
+				details.action === "create"
+					? "Created"
+					: details.action === "update"
+						? "Updated"
+						: details.action === "append"
+							? "Appended to"
+							: details.action === "delete"
+								? "Deleted"
+								: null;
+			if (actionLabel) {
+				const lines = text.split("\n");
+				lines[0] = theme.fg("success", "✓ ") + theme.fg("muted", `${actionLabel} `) + lines[0];
+				text = lines.join("\n");
+			}
+			if (!expanded) {
+				text = appendExpandHint(theme, text);
+			}
+			return new Text(text, 0, 0);
+		},
+	});
+
+	pi.registerCommand("todos", {
+		description: "List todos from .pi/todos",
+		getArgumentCompletions: (argumentPrefix: string) => {
+			const todos = listTodosSync(getTodosDir(process.cwd()));
+			if (!todos.length) return null;
+			const matches = filterTodos(todos, argumentPrefix);
+			if (!matches.length) return null;
+			return matches.map((todo) => {
+				const title = todo.title || "(untitled)";
+				const tags = todo.tags.length ? ` • ${todo.tags.join(", ")}` : "";
+				return {
+					value: title,
+					label: `${formatTodoId(todo.id)} ${title}`,
+					description: `${todo.status || "open"}${tags}`,
+				};
+			});
+		},
+		handler: async (args, ctx) => {
+			const todosDir = getTodosDir(ctx.cwd);
+			const todos = await listTodos(todosDir);
+			const searchTerm = (args ?? "").trim();
+
+			if (!ctx.hasUI) {
+				const text = formatTodoList(todos);
+				console.log(text);
+				return;
+			}
+
+			let nextPrompt: string | null = null;
+			let rootTui: TUI | null = null;
+			await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+				rootTui = tui;
+				let selector: TodoSelectorComponent | null = null;
+
+				const addTodoPathToPrompt = (todoId: string) => {
+					const filePath = getTodoPath(todosDir, todoId);
+					const relativePath = path.relative(ctx.cwd, filePath);
+					const displayPath =
+						relativePath && !relativePath.startsWith("..") ? relativePath : filePath;
+					const mention = `@${displayPath}`;
+					const current = ctx.ui.getEditorText();
+					const separator = current && !current.endsWith(" ") ? " " : "";
+					ctx.ui.setEditorText(`${current}${separator}${mention}`);
+					ctx.ui.notify(`Added ${mention} to prompt`, "info");
+				};
+
+				const resolveTodoRecord = async (todo: TodoFrontMatter): Promise<TodoRecord | null> => {
+					const filePath = getTodoPath(todosDir, todo.id);
+					const record = await ensureTodoExists(filePath, todo.id);
+					if (!record) {
+						ctx.ui.notify(`Todo ${formatTodoId(todo.id)} not found`, "error");
+						return null;
+					}
+					return record;
+				};
+
+				const openTodoOverlay = async (record: TodoRecord) => {
+					const action = await ctx.ui.custom<TodoOverlayAction>(
+						(overlayTui, overlayTheme, _overlayKb, overlayDone) =>
+							new TodoDetailOverlayComponent(overlayTui, overlayTheme, record, overlayDone),
+						{
+							overlay: true,
+							overlayOptions: { width: "80%", maxHeight: "80%", anchor: "center" },
+						},
+					);
+
+					if (!action || action === "cancel") return;
+					if (action === "actions") {
+						await showActionMenu(record);
+						return;
+					}
+					await applyTodoAction(record, action);
+				};
+
+				const applyTodoAction = async (record: TodoRecord, action: TodoMenuAction) => {
+					if (action === "cancel") return;
+					if (action === "close-dialog") {
+						done();
+						return;
+					}
+					if (action === "refine") {
+						const title = record.title || "(untitled)";
+						nextPrompt = buildRefinePrompt(record.id, title);
+						done();
+						return;
+					}
+					if (action === "work") {
+						const title = record.title || "(untitled)";
+						nextPrompt = `work on todo ${formatTodoId(record.id)} "${title}"`;
+						done();
+						return;
+					}
+					if (action === "view") {
+						await openTodoOverlay(record);
+						return;
+					}
+					if (action === "copy-path") {
+						addTodoPathToPrompt(record.id);
+						return;
+					}
+
+					if (action === "delete") {
+						const ok = await ctx.ui.confirm(
+							"Delete todo",
+							`Delete todo ${formatTodoId(record.id)}? This cannot be undone.`,
+						);
+						if (!ok) {
+							return;
+						}
+						const result = await deleteTodo(todosDir, record.id, ctx);
+						if ("error" in result) {
+							ctx.ui.notify(result.error, "error");
+							return;
+						}
+						const updatedTodos = await listTodos(todosDir);
+						selector?.setTodos(updatedTodos);
+						ctx.ui.notify(`Deleted todo ${formatTodoId(record.id)}`, "info");
+						return;
+					}
+
+					const nextStatus = action === "close" ? "closed" : "open";
+					const result = await updateTodoStatus(todosDir, record.id, nextStatus, ctx);
+					if ("error" in result) {
+						ctx.ui.notify(result.error, "error");
+						return;
+					}
+
+					const updatedTodos = await listTodos(todosDir);
+					selector?.setTodos(updatedTodos);
+					ctx.ui.notify(
+						`${action === "close" ? "Closed" : "Reopened"} todo ${formatTodoId(record.id)}`,
+						"info",
+					);
+				};
+
+				const showActionMenu = async (todo: TodoFrontMatter | TodoRecord) => {
+					const record = "body" in todo ? todo : await resolveTodoRecord(todo);
+					if (!record) return;
+					const options: SelectItem[] = [
+						{ value: "view", label: "view", description: "View todo" },
+						{ value: "work", label: "work", description: "Work on todo" },
+						{ value: "refine", label: "refine", description: "Refine task" },
+						{ value: "close", label: "close", description: "Close todo" },
+						{ value: "reopen", label: "reopen", description: "Reopen todo" },
+						{ value: "copy-path", label: "copy", description: "Copy todo path into prompt" },
+						{ value: "delete", label: "delete", description: "Delete todo" },
+					];
+					const title = record.title || "(untitled)";
+					const selection = await ctx.ui.custom<TodoMenuAction | null>(
+						(overlayTui, overlayTheme, _overlayKb, overlayDone) => {
+							const container = new Container();
+							container.addChild(
+								new Text(
+									overlayTheme.fg(
+										"accent",
+										overlayTheme.bold(`Actions for ${formatTodoId(record.id)} "${title}"`),
+									),
+								),
+							);
+							container.addChild(new Spacer(1));
+
+							const selectList = new SelectList(options, options.length, {
+								selectedPrefix: (text) => overlayTheme.fg("accent", text),
+								selectedText: (text) => overlayTheme.fg("accent", text),
+								description: (text) => overlayTheme.fg("muted", text),
+								scrollInfo: (text) => overlayTheme.fg("dim", text),
+								noMatch: (text) => overlayTheme.fg("warning", text),
+							});
+
+							selectList.onSelect = (item) => overlayDone(item.value as TodoMenuAction);
+							selectList.onCancel = () => overlayDone(null);
+
+							container.addChild(selectList);
+							container.addChild(new Spacer(1));
+							container.addChild(
+								new Text(overlayTheme.fg("dim", "Press enter to confirm or esc to cancel")),
+							);
+
+							return {
+								render(width: number) {
+									const innerWidth = Math.max(10, width - 2);
+									const contentLines = container.render(innerWidth);
+									const borderColor = (text: string) => overlayTheme.fg("accent", text);
+									const top = borderColor(`┌${"─".repeat(innerWidth)}┐`);
+									const bottom = borderColor(`└${"─".repeat(innerWidth)}┘`);
+									const framed = contentLines.map((line) => {
+										const truncated = truncateToWidth(line, innerWidth);
+										const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+										return (
+											borderColor("│") + truncated + " ".repeat(padding) + borderColor("│")
+										);
+									});
+									return [top, ...framed, bottom].map((line) => truncateToWidth(line, width));
+								},
+								invalidate() {
+									container.invalidate();
+								},
+								handleInput(data: string) {
+									selectList.handleInput(data);
+									overlayTui.requestRender();
+								},
+							};
+						},
+						{
+							overlay: true,
+							overlayOptions: { width: "70%", maxHeight: "60%", anchor: "center" },
+						},
+					);
+
+					if (!selection) {
+						tui.requestRender();
+						return;
+					}
+					await applyTodoAction(record, selection);
+				};
+
+				const handleSelect = async (todo: TodoFrontMatter) => {
+					await showActionMenu(todo);
+				};
+
+				selector = new TodoSelectorComponent(
+					tui,
+					theme,
+					todos,
+					(todo) => {
+						void handleSelect(todo);
+					},
+					() => done(),
+					searchTerm || undefined,
+					(todo, action) => {
+						const title = todo.title || "(untitled)";
+						nextPrompt =
+							action === "refine"
+								? buildRefinePrompt(todo.id, title)
+								: `work on todo ${formatTodoId(todo.id)} "${title}"`;
+						done();
+					},
+				);
+
+				return selector;
+			});
+
+			if (nextPrompt) {
+				ctx.ui.setEditorText(nextPrompt);
+				rootTui?.requestRender();
+			}
+		},
+	});
+
+}