@maxiaochao/pi-toolkit 0.10.2 → 0.10.4

package/packages/todo/extensions/todo.ts

@@ -1,7 +1,8 @@
 /**
- * Session-scoped todo extension with branch-aware persistence.
+ * Branch-local execution-plan extension with tool-result snapshot persistence.
  *
- * Provides the `todo` tool, a compact active-work widget, and `/todos` current-plan view.
+ * The model sees only the current plan. The widget mirrors that plan, while
+ * `/todos` shows the complete history for the active conversation branch.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -12,11 +13,13 @@ import {
 	activeTodoRows,
 	applyTodoAction,
 	countTodoStatuses,
+	formatCurrentPlan,
 	normalizeTodo,
 	restoreTodoState,
 	type StoredTodo,
 	type Todo,
 	type TodoAction,
+	type TodoActionInput,
 	type TodoState,
 	type TodoStatus,
 } from "../src/todo-state.ts";
@@ -29,17 +32,16 @@ interface TodoDetails {
 }
 
 const TodoParams = Type.Object({
-	action: StringEnum(["list", "replace", "add", "update", "remove", "clear"] as const, {
-		description: "list current tasks; replace the plan; add one; update status; remove one; or clear all",
+	action: StringEnum(["plan", "add_step", "complete_current", "cancel_current", "list"] as const, {
+		description: "plan creates or replaces the current plan; add_step appends; complete_current or cancel_current advances one expected current step; list reads the current plan",
 	}),
 	items: Type.Optional(Type.Array(Type.String(), {
-		minItems: 1,
-		description: "Complete ordered task texts for replace",
+		description: "Ordered executable steps for plan; an empty array cancels all unfinished work",
 	})),
-	text: Type.Optional(Type.String({ description: "Task text for add" })),
-	id: Type.Optional(Type.Integer({ minimum: 1, description: "Task ID for update or remove" })),
-	status: Type.Optional(StringEnum(["todo", "doing", "done", "cancelled"] as const, {
-		description: "New status for update; optional initial status for add",
+	text: Type.Optional(Type.String({ description: "Step text for add_step" })),
+	expected_current_id: Type.Optional(Type.Integer({
+		minimum: 1,
+		description: "Stable ID of the sole current doing step; required by complete_current and cancel_current",
 	})),
 });
 
@@ -63,16 +65,17 @@ function themedStatus(theme: Theme, status: TodoStatus, text: string): string {
 	return theme.fg("dim", text);
 }
 
-function taskSummary(todos: Todo[]): string {
+function historySummary(todos: Todo[]): string {
 	const counts = countTodoStatuses(todos);
-	const active = counts.todo + counts.doing;
-	const parts = [`${active} active (${counts.doing} doing, ${counts.todo} queued)`];
-	if (counts.done > 0) parts.push(`${counts.done} done`);
-	if (counts.cancelled > 0) parts.push(`${counts.cancelled} cancelled`);
-	return parts.join(" · ");
+	return `${todos.length} steps · ${counts.done} done · ${counts.cancelled} cancelled · ${counts.doing + counts.todo} current`;
 }
 
-function renderTodoLine(theme: Theme, todo: Todo): string {
+function currentSummary(todos: Todo[]): string {
+	const rows = activeTodoRows(todos);
+	return `${rows.length} current step${rows.length === 1 ? "" : "s"}`;
+}
+
+function renderHistoryLine(theme: Theme, todo: Todo): string {
 	const icon = themedStatus(theme, todo.status, statusMarker(todo.status));
 	if (todo.status === "done" || todo.status === "cancelled") {
 		return `${icon} \x1b[9m${theme.fg("dim", `#${todo.id} ${todo.text}`)}\x1b[29m`;
@@ -80,20 +83,52 @@ function renderTodoLine(theme: Theme, todo: Todo): string {
 	return `${icon} ${theme.fg("accent", `#${todo.id}`)} ${theme.fg("text", todo.text)}`;
 }
 
-function renderActiveTodoLine(theme: Theme, todo: Todo, position: number): string {
+function renderCurrentLine(theme: Theme, todo: Todo, position: number): string {
 	const icon = themedStatus(theme, todo.status, statusMarker(todo.status));
 	return `${icon} ${theme.fg("accent", `${position}.`)} ${theme.fg("text", todo.text)}`;
 }
 
-class TodoListComponent {
+export class CurrentPlanWidget {
 	private cachedWidth?: number;
 	private cachedLines?: string[];
+	private readonly getTodos: () => Todo[];
+	private readonly theme: Theme;
+
+	constructor(getTodos: () => Todo[], theme: Theme) {
+		this.getTodos = getTodos;
+		this.theme = theme;
+	}
+
+	render(width: number): string[] {
+		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+		const todos = this.getTodos();
+		const rows = activeTodoRows(todos);
+		this.cachedLines = [
+			truncateToWidth(`${this.theme.fg("accent", "●")} ${this.theme.fg("muted", currentSummary(todos))}`, width),
+			...rows.map(({ position, todo }) => truncateToWidth(`  ${renderCurrentLine(this.theme, todo, position)}`, width)),
+		];
+		this.cachedWidth = width;
+		return this.cachedLines;
+	}
 
-	constructor(
-		private readonly todos: Todo[],
-		private readonly theme: Theme,
-		private readonly onClose: () => void,
-	) {}
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+}
+
+class TodoListComponent {
+	private cachedWidth?: number;
+	private cachedLines?: string[];
+	private readonly todos: Todo[];
+	private readonly theme: Theme;
+	private readonly onClose: () => void;
+
+	constructor(todos: Todo[], theme: Theme, onClose: () => void) {
+		this.todos = todos;
+		this.theme = theme;
+		this.onClose = onClose;
+	}
 
 	handleInput(data: string): void {
 		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) this.onClose();
@@ -104,20 +139,12 @@ class TodoListComponent {
 
 		const border = this.theme.fg("borderMuted", "-".repeat(Math.max(0, width - 10)));
 		const lines = ["", truncateToWidth(`${this.theme.fg("borderMuted", "---")}${this.theme.fg("accent", " Todos ")}${border}`, width), ""];
-
 		if (this.todos.length === 0) {
-			lines.push(truncateToWidth(`  ${this.theme.fg("dim", "No todos")}`, width));
+			lines.push(truncateToWidth(`  ${this.theme.fg("dim", "No todo history on this branch")}`, width));
 		} else {
-			lines.push(truncateToWidth(
-				`${this.theme.fg("accent", "●")} ${this.theme.fg("muted", taskSummary(this.todos))}`,
-				width,
-			));
-			lines.push("");
-			for (const todo of sortedTodos(this.todos)) {
-				lines.push(truncateToWidth(`  ${renderTodoLine(this.theme, todo)}`, width));
-			}
+			lines.push(truncateToWidth(`${this.theme.fg("accent", "●")} ${this.theme.fg("muted", historySummary(this.todos))}`, width), "");
+			for (const todo of sortedTodos(this.todos)) lines.push(truncateToWidth(`  ${renderHistoryLine(this.theme, todo)}`, width));
 		}
-
 		lines.push("", truncateToWidth(`  ${this.theme.fg("dim", "Press Escape to close")}`, width), "");
 		this.cachedWidth = width;
 		this.cachedLines = lines;
@@ -130,33 +157,45 @@ class TodoListComponent {
 	}
 }
 
+interface MountedWidget {
+	component: CurrentPlanWidget;
+	tui: { requestRender(): void };
+}
+
 export default function (pi: ExtensionAPI) {
 	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1") return;
 
 	let state: TodoState = { todos: [], nextId: 1 };
-
+	let mountedWidget: MountedWidget | undefined;
+	let actionQueue = Promise.resolve();
 	const snapshot = (): StoredTodo[] => state.todos.map((todo) => ({ ...todo }));
 
 	const refreshUI = (ctx: ExtensionContext) => {
 		if (!ctx.hasUI) return;
-		const visible = activeTodoRows(state.todos);
-		if (visible.length === 0) {
-			ctx.ui.setWidget(WIDGET_KEY, undefined);
+		const hasCurrentPlan = activeTodoRows(state.todos).length > 0;
+		if (!hasCurrentPlan) {
+			if (mountedWidget) {
+				mountedWidget.component.invalidate();
+				ctx.ui.setWidget(WIDGET_KEY, undefined);
+				mountedWidget.tui.requestRender();
+				mountedWidget = undefined;
+			}
 			return;
 		}
 
-		ctx.ui.setWidget(
-			WIDGET_KEY,
-			(_tui, theme) => ({
-				render(width: number): string[] {
-					return [
-						truncateToWidth(`${theme.fg("accent", "●")} ${theme.fg("muted", taskSummary(state.todos))}`, width),
-						...visible.map(({ position, todo }) => truncateToWidth(`  ${renderActiveTodoLine(theme, todo, position)}`, width)),
-					];
-				},
-				invalidate() {},
-			}),
-		);
+		if (mountedWidget) {
+			mountedWidget.component.invalidate();
+			mountedWidget.tui.requestRender();
+			return;
+		}
+
+		ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+			const component = new CurrentPlanWidget(() => state.todos, theme);
+			mountedWidget = { component, tui };
+			component.invalidate();
+			tui.requestRender();
+			return component;
+		});
 	};
 
 	const reconstructState = (ctx: ExtensionContext) => {
@@ -176,73 +215,64 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
 	pi.on("session_shutdown", async (_event, ctx) => {
 		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
+		mountedWidget = undefined;
 	});
 
 	pi.registerTool({
 		name: "todo",
 		label: "Todo",
-		description: "Track explicit checklists and non-trivial multi-step work. Replace the plan when instructions change. The tool keeps one task doing and advances automatically; mark obsolete work cancelled and verified work done.",
+		description: "Maintain a branch-local, user-visible CURRENT execution plan. Use plan only for explicit multi-step work, genuinely multi-stage work, or cross-model handoff—not simple one-step tasks. Preserve user intent and order. Complete only work actually done; blocked-but-needed work stays current. cancel_current means the current step is no longer needed while later steps remain valid; changed direction uses plan. Each completion/cancellation must name expected_current_id and advances exactly one step.",
 		parameters: TodoParams,
+		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const result = applyTodoAction(state, params);
-			state = { todos: result.todos, nextId: result.nextId };
-			const text = params.action === "list"
-				? state.todos.length
-					? sortedTodos(state.todos).map((todo) => `${statusMarker(todo.status)} #${todo.id} [${todo.status}] ${todo.text}`).join("\n")
-					: "No todos"
-				: result.message;
-
-			refreshUI(ctx);
-			return {
-				content: [{ type: "text" as const, text }],
-				details: {
-					action: params.action,
-					todos: snapshot(),
-					nextId: state.nextId,
-					...(result.error ? { error: result.error } : {}),
-				} as TodoDetails,
-			};
+			const run = actionQueue.then(() => {
+				const result = applyTodoAction(state, params as TodoActionInput);
+				state = { todos: result.todos, nextId: result.nextId };
+				refreshUI(ctx);
+				return {
+					content: [{
+						type: "text" as const,
+						text: result.error ? `Error: ${result.error}\n\n${formatCurrentPlan(state.todos)}` : formatCurrentPlan(state.todos),
+					}],
+					details: {
+						action: params.action,
+						todos: snapshot(),
+						nextId: state.nextId,
+						...(result.error ? { error: result.error } : {}),
+					} as TodoDetails,
+					...(result.error ? { isError: true } : {}),
+				};
+			});
+			actionQueue = run.then(() => undefined, () => undefined);
+			return run;
 		},
 
 		renderCall(args, theme) {
 			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", args.action);
-			if (args.items) text += ` ${theme.fg("dim", `${args.items.length} tasks`)}`;
+			if (args.items) text += ` ${theme.fg("dim", `${args.items.length} steps`)}`;
 			if (args.text) text += ` ${theme.fg("dim", `"${args.text}"`)}`;
-			if (args.id !== undefined) text += ` ${theme.fg("accent", `#${args.id}`)}`;
-			if (args.status) text += ` ${themedStatus(theme, args.status, args.status)}`;
+			if (args.expected_current_id !== undefined) text += ` ${theme.fg("accent", `#${args.expected_current_id}`)}`;
 			return new Text(text, 0, 0);
 		},
 
 		renderResult(result, _options, theme) {
-			const details = result.details as TodoDetails | undefined;
-			if (!details) {
-				const item = result.content[0];
-				return new Text(item?.type === "text" ? item.text : "", 0, 0);
-			}
-			if (details.error) return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
-
-			if (details.action === "list") {
-				const list = details.todos.map(normalizeTodo);
-				if (list.length === 0) return new Text(theme.fg("dim", "No todos"), 0, 0);
-				return new Text(sortedTodos(list).map((todo) => renderTodoLine(theme, todo)).join("\n"), 0, 0);
-			}
-
 			const item = result.content[0];
-			const message = item?.type === "text" ? item.text : "";
-			return new Text(theme.fg("success", "> ") + theme.fg("muted", message), 0, 0);
+			const text = item?.type === "text" ? item.text : "";
+			const details = result.details as TodoDetails | undefined;
+			return new Text(details?.error ? theme.fg("error", text) : theme.fg("muted", text), 0, 0);
 		},
 	});
 
 	pi.registerCommand("todos", {
-		description: "Show active and closed tasks in the current plan",
+		description: "Show full Todo history on the current branch",
 		handler: async (_args, ctx) => {
 			if (ctx.mode !== "tui") {
 				ctx.ui.notify("/todos requires interactive mode", "error");
 				return;
 			}
 			await ctx.ui.custom<void>((_tui, theme, _keybindings, done) =>
-				new TodoListComponent(state.todos, theme, () => done()),
+				new TodoListComponent(snapshot().map(normalizeTodo), theme, () => done()),
 			);
 		},
 	});

package/packages/todo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-todo",
   "version": "0.1.0",
-  "description": "Session checklist and todo lifecycle extension for Pi.",
+  "description": "Branch-local execution-plan lifecycle and history extension for Pi.",
   "type": "module",
   "keywords": ["pi-package", "pi-extension", "todo"],
   "files": ["extensions", "src", "docs", "README.md", "TESTING.md", "CHANGELOG.md"],
@@ -18,7 +18,7 @@
     "typebox": "*"
   },
   "scripts": {
-    "test": "node --experimental-strip-types tests/todo-state.mjs",
+    "test": "node --experimental-strip-types tests/todo-state.mjs && node --experimental-strip-types tests/todo-extension.mjs",
     "load-test": "pi -ne -e ./extensions/todo.ts"
   },
   "publishConfig": { "access": "public" }

package/packages/todo/src/todo-state.ts

@@ -1,5 +1,5 @@
 export type TodoStatus = "todo" | "doing" | "done" | "cancelled";
-export type TodoAction = "list" | "replace" | "add" | "update" | "remove" | "clear";
+export type TodoAction = "plan" | "add_step" | "complete_current" | "cancel_current" | "list";
 
 export interface Todo {
 	id: number;
@@ -26,10 +26,9 @@ export interface ActiveTodoRow {
 
 export interface TodoActionInput {
 	action: TodoAction;
-	text?: string;
 	items?: string[];
-	id?: number;
-	status?: TodoStatus;
+	text?: string;
+	expected_current_id?: number;
 }
 
 export interface TodoActionResult extends TodoState {
@@ -75,13 +74,26 @@ export function countTodoStatuses(todos: Todo[]): TodoCounts {
 }
 
 export function activeTodos(todos: Todo[]): Todo[] {
-	return todos.filter((todo) => todo.status === "doing" || todo.status === "todo");
+	return [
+		...todos.filter((todo) => todo.status === "doing"),
+		...todos.filter((todo) => todo.status === "todo"),
+	];
 }
 
 export function activeTodoRows(todos: Todo[]): ActiveTodoRow[] {
 	return activeTodos(todos).map((todo, index) => ({ position: index + 1, todo }));
 }
 
+export function currentTodo(todos: Todo[]): Todo | undefined {
+	return todos.find((todo) => todo.status === "doing");
+}
+
+export function formatCurrentPlan(todos: Todo[]): string {
+	const current = activeTodos(todos);
+	if (current.length === 0) return "CURRENT plan: none";
+	return ["CURRENT plan", ...current.map((todo) => `#${todo.id} [${todo.status}] ${todo.text}`)].join("\n");
+}
+
 function cloneState(state: TodoState): TodoState {
 	return { todos: state.todos.map((todo) => ({ ...todo })), nextId: state.nextId };
 }
@@ -95,8 +107,18 @@ function cleanText(text: string | undefined): string | undefined {
 	return cleaned ? cleaned : undefined;
 }
 
-function hasActiveDuplicate(todos: Todo[], text: string): boolean {
-	return todos.some((todo) => (todo.status === "todo" || todo.status === "doing") && todo.text === text);
+function closeCurrentAndAdvance(next: TodoState, expectedId: number | undefined, status: "done" | "cancelled"): TodoActionResult {
+	const current = next.todos.filter((todo) => todo.status === "doing");
+	if (expectedId === undefined) return fail(next, "expected_current_id is required");
+	if (current.length !== 1 || current[0].id !== expectedId) {
+		const actual = current.length === 1 ? `#${current[0].id}` : "none";
+		return fail(next, `expected current #${expectedId}, but current is ${actual}`);
+	}
+
+	current[0].status = status;
+	const following = next.todos.find((todo) => todo.status === "todo");
+	if (following) following.status = "doing";
+	return { ...next, message: `${status === "done" ? "Completed" : "Cancelled"} current step #${expectedId}` };
 }
 
 export function applyTodoAction(state: TodoState, input: TodoActionInput): TodoActionResult {
@@ -104,57 +126,34 @@ export function applyTodoAction(state: TodoState, input: TodoActionInput): TodoA
 
 	switch (input.action) {
 		case "list":
-			return { ...next, message: next.todos.length ? "Listed todos" : "No todos" };
+			return { ...next, message: "Listed current plan" };
 
-		case "replace": {
-			if (!input.items?.length) return fail(state, "items required for replace");
+		case "plan": {
+			if (!input.items) return fail(state, "items is required for plan");
 			const items = input.items.map(cleanText);
-			if (items.some((item) => item === undefined)) return fail(state, "replace items must not be empty");
+			if (items.some((item) => item === undefined)) return fail(state, "plan items must not be empty");
+			for (const todo of next.todos) {
+				if (todo.status === "doing" || todo.status === "todo") todo.status = "cancelled";
+			}
 			const texts = items as string[];
-			if (new Set(texts).size !== texts.length) return fail(state, "replace items must be unique");
-			const firstId = next.nextId;
-			next.todos = texts.map((text, index) => ({ id: firstId + index, text, status: index === 0 ? "doing" : "todo" }));
-			next.nextId += next.todos.length;
-			return { ...next, message: `Replaced plan with ${next.todos.length} tasks` };
+			for (const [index, text] of texts.entries()) {
+				next.todos.push({ id: next.nextId++, text, status: index === 0 ? "doing" : "todo" });
+			}
+			return { ...next, message: texts.length === 0 ? "Cancelled all unfinished work" : `Planned ${texts.length} steps` };
 		}
 
-		case "add": {
+		case "add_step": {
 			const text = cleanText(input.text);
-			if (!text) return fail(state, "text required for add");
-			if (hasActiveDuplicate(next.todos, text)) return fail(state, `active task already exists: ${text}`);
-			if (input.status === "doing") {
-				for (const todo of next.todos) if (todo.status === "doing") todo.status = "todo";
-			}
-			const todo: Todo = { id: next.nextId++, text, status: input.status ?? "todo" };
+			if (!text) return fail(state, "text is required for add_step");
+			const todo: Todo = { id: next.nextId++, text, status: currentTodo(next.todos) ? "todo" : "doing" };
 			next.todos.push(todo);
-			normalizeTodoFlow(next.todos);
-			return { ...next, message: `Added todo #${todo.id} [${todo.status}]: ${todo.text}` };
-		}
-
-		case "update": {
-			if (input.id === undefined || input.status === undefined) return fail(state, "id and status required for update");
-			const todo = next.todos.find((item) => item.id === input.id);
-			if (!todo) return fail(state, `#${input.id} not found`);
-			if (input.status === "doing") {
-				for (const item of next.todos) if (item.status === "doing") item.status = "todo";
-			}
-			todo.status = input.status;
-			normalizeTodoFlow(next.todos);
-			return { ...next, message: `Todo #${todo.id} is now ${todo.status}` };
+			return { ...next, message: `Added step #${todo.id}` };
 		}
 
-		case "remove": {
-			if (input.id === undefined) return fail(state, "id required for remove");
-			const index = next.todos.findIndex((item) => item.id === input.id);
-			if (index < 0) return fail(state, `#${input.id} not found`);
-			const [removed] = next.todos.splice(index, 1);
-			normalizeTodoFlow(next.todos);
-			return { ...next, message: `Removed todo #${removed.id}: ${removed.text}` };
-		}
+		case "complete_current":
+			return closeCurrentAndAdvance(next, input.expected_current_id, "done");
 
-		case "clear": {
-			const count = next.todos.length;
-			return { todos: [], nextId: 1, message: `Cleared ${count} todos` };
-		}
+		case "cancel_current":
+			return closeCurrentAndAdvance(next, input.expected_current_id, "cancelled");
 	}
 }

package/packages/todo/tests/todo-extension.mjs

@@ -0,0 +1,134 @@
+import assert from "node:assert/strict";
+import registerTodo from "../extensions/todo.ts";
+
+const theme = {
+	fg(_color, text) { return text; },
+	bold(text) { return text; },
+};
+
+function createHarness(branch = [], hasUI = true) {
+	const handlers = new Map();
+	const commands = new Map();
+	let tool;
+	let currentBranch = branch;
+	let widget;
+	let historyComponent;
+	let renderRequests = 0;
+	const tui = { requestRender() { renderRequests += 1; } };
+	const ui = {
+		setWidget(_key, value) {
+			if (value === undefined) {
+				widget = undefined;
+				return;
+			}
+			widget = value(tui, theme);
+		},
+		notify() {},
+		async custom(factory) {
+			historyComponent = factory(tui, theme, {}, () => {});
+		},
+	};
+	const pi = {
+		on(name, handler) { handlers.set(name, handler); },
+		registerTool(definition) { tool = definition; },
+		registerCommand(name, definition) { commands.set(name, definition); },
+	};
+	const childGuard = process.env.PI_HERDR_SUBAGENTS_CHILD;
+	delete process.env.PI_HERDR_SUBAGENTS_CHILD;
+	try {
+		registerTodo(pi);
+	} finally {
+		if (childGuard === undefined) delete process.env.PI_HERDR_SUBAGENTS_CHILD;
+		else process.env.PI_HERDR_SUBAGENTS_CHILD = childGuard;
+	}
+	const context = {
+		hasUI,
+		mode: hasUI ? "tui" : "print",
+		ui,
+		sessionManager: { getBranch: () => currentBranch },
+	};
+	return {
+		handlers,
+		commands,
+		context,
+		get tool() { return tool; },
+		get widget() { return widget; },
+		get historyComponent() { return historyComponent; },
+		get renderRequests() { return renderRequests; },
+		setBranch(value) { currentBranch = value; },
+	};
+}
+
+function toolResult(todos, nextId) {
+	return {
+		type: "message",
+		message: {
+			role: "toolResult",
+			toolName: "todo",
+			details: { action: "list", todos, nextId },
+		},
+	};
+}
+
+const branch = [toolResult([
+	{ id: 1, text: "Closed history", status: "done" },
+	{ id: 2, text: "Current work", status: "doing" },
+	{ id: 3, text: "Later work", status: "todo" },
+], 4)];
+const harness = createHarness(branch);
+await harness.handlers.get("session_start")({}, harness.context);
+assert.ok(harness.tool, "Todo tool is registered");
+assert.deepEqual(harness.tool.parameters.properties.action.enum, ["plan", "add_step", "complete_current", "cancel_current", "list"]);
+assert.equal(harness.renderRequests, 1, "mounting the widget explicitly requests a TUI render");
+const mountedWidget = harness.widget;
+const initialWidget = mountedWidget.render(100).join("\n");
+assert.match(initialWidget, /1\. Current work/);
+assert.match(initialWidget, /2\. Later work/);
+assert.doesNotMatch(initialWidget, /#2|#3|Closed history|done|cancelled/, "widget hides IDs and closed history");
+
+const completed = await harness.tool.execute("complete", {
+	action: "complete_current",
+	expected_current_id: 2,
+}, undefined, undefined, harness.context);
+assert.equal(harness.widget, mountedWidget, "live updates keep the mounted widget component");
+assert.ok(harness.renderRequests >= 2, "state change invalidates the widget and requests another render");
+const updatedWidget = mountedWidget.render(100).join("\n");
+assert.match(updatedWidget, /1\. Later work/);
+assert.doesNotMatch(updatedWidget, /Current work/, "mounted widget reads current state instead of a captured row snapshot");
+assert.equal(completed.content[0].text, "CURRENT plan\n#3 [doing] Later work");
+
+await harness.commands.get("todos").handler("", harness.context);
+const history = harness.historyComponent.render(100).join("\n");
+assert.match(history, /#1 Closed history/);
+assert.match(history, /#2 Current work/);
+assert.match(history, /#3 Later work/, "/todos alone exposes complete branch history");
+
+await harness.tool.execute("empty", { action: "plan", items: [] }, undefined, undefined, harness.context);
+assert.equal(harness.widget, undefined, "widget disappears when the current plan is done or cancelled");
+assert.ok(harness.renderRequests >= 3, "unmounting the widget requests a render");
+
+harness.setBranch([toolResult([
+	{ id: 10, text: "Selected branch only", status: "doing" },
+	{ id: 11, text: "Selected branch next", status: "todo" },
+], 12)]);
+await harness.handlers.get("session_tree")({}, harness.context);
+const branchList = await harness.tool.execute("branch-list", { action: "list" }, undefined, undefined, harness.context);
+assert.equal(branchList.content[0].text, "CURRENT plan\n#10 [doing] Selected branch only\n#11 [todo] Selected branch next");
+assert.doesNotMatch(branchList.content[0].text, /Closed history|Later work/, "tree navigation reconstructs only getBranch snapshots");
+
+const serialized = createHarness([], false);
+await serialized.handlers.get("session_start")({}, serialized.context);
+const [planned, firstCompletion, repeatedCompletion] = await Promise.all([
+	serialized.tool.execute("plan", { action: "plan", items: ["First", "Second", "Third"] }, undefined, undefined, serialized.context),
+	serialized.tool.execute("complete-one", { action: "complete_current", expected_current_id: 1 }, undefined, undefined, serialized.context),
+	serialized.tool.execute("complete-repeat", { action: "complete_current", expected_current_id: 1 }, undefined, undefined, serialized.context),
+]);
+assert.equal(planned.content[0].text, "CURRENT plan\n#1 [doing] First\n#2 [todo] Second\n#3 [todo] Third");
+assert.equal(firstCompletion.content[0].text, "CURRENT plan\n#2 [doing] Second\n#3 [todo] Third");
+assert.equal(repeatedCompletion.isError, true, "same-turn repeated completion fails after the first queued call advances");
+assert.match(repeatedCompletion.content[0].text, /expected current #1, but current is #2/);
+assert.match(repeatedCompletion.content[0].text, /#2 \[doing\] Second/);
+const afterConcurrentCalls = await serialized.tool.execute("list", { action: "list" }, undefined, undefined, serialized.context);
+assert.equal(afterConcurrentCalls.content[0].text, "CURRENT plan\n#2 [doing] Second\n#3 [todo] Third");
+
+console.log("Todo extension integration tests passed");