@phi-code-admin/phi-code 0.83.0 → 0.84.1

package/extensions/phi/todo/state/selectors.ts

@@ -0,0 +1,107 @@
+import type { Task, TaskStatus } from "../tool/types.js";
+import type { TaskState } from "./state.js";
+
+/** Tasks excluding deleted tombstones — the canonical "what's visible". */
+export function selectVisibleTasks(state: TaskState): readonly Task[] {
+	return state.tasks.filter((t) => t.status !== "deleted");
+}
+
+/**
+ * Group visible tasks by status. Iteration order at the call site uses
+ * (`completed`, `inProgress`, `pending`) to match the `/todos` header part
+ * order pinned by `todo.command.test.ts`.
+ */
+export interface TasksByStatus {
+	pending: readonly Task[];
+	inProgress: readonly Task[];
+	completed: readonly Task[];
+}
+export function selectTasksByStatus(state: TaskState): TasksByStatus {
+	const visible = selectVisibleTasks(state);
+	return {
+		pending: visible.filter((t) => t.status === "pending"),
+		inProgress: visible.filter((t) => t.status === "in_progress"),
+		completed: visible.filter((t) => t.status === "completed"),
+	};
+}
+
+/** Total counts for the overlay heading (`Todos (n/m)`) and `/todos` header. */
+export interface TodoCounts {
+	total: number;
+	pending: number;
+	inProgress: number;
+	completed: number;
+}
+export function selectTodoCounts(state: TaskState): TodoCounts {
+	const groups = selectTasksByStatus(state);
+	return {
+		total: groups.pending.length + groups.inProgress.length + groups.completed.length,
+		pending: groups.pending.length,
+		inProgress: groups.inProgress.length,
+		completed: groups.completed.length,
+	};
+}
+
+/**
+ * Whether any visible task carries a `blockedBy` reference. The overlay uses
+ * this to gate the `#id` prefix on per-task rows — without at least one
+ * `⛓ #N` suffix, the per-row id has no anchor.
+ */
+export function selectShowTaskIds(state: TaskState): boolean {
+	return selectVisibleTasks(state).some((t) => t.blockedBy && t.blockedBy.length > 0);
+}
+
+/**
+ * Resolve a task's subject by id from the live state for renderCall's
+ * accent label. `undefined` when the id is unknown — caller falls back to
+ * `#id` plain rendering.
+ */
+export function selectTaskSubjectById(state: TaskState, id: number): string | undefined {
+	return state.tasks.find((t) => t.id === id)?.subject;
+}
+
+/**
+ * Overlay layout decision. Encapsulates the "drop completed first, then
+ * truncate non-completed tail" rule pre-refactor lived in
+ * `todo-overlay.ts:144-188`. `budget` is the body-slot count (caller passes
+ * `MAX_WIDGET_LINES - 1` to reserve the heading row); on overflow the
+ * selector reserves one more slot internally for the summary row. Returns
+ * the visible task slice plus the overflow summary parts.
+ */
+export interface OverlayLayout {
+	visible: readonly Task[];
+	hiddenCompleted: number;
+	truncatedTail: number;
+}
+export function selectOverlayLayout(state: TaskState, budget: number): OverlayLayout {
+	const all = selectVisibleTasks(state);
+	if (all.length <= budget) {
+		return { visible: all, hiddenCompleted: 0, truncatedTail: 0 };
+	}
+	const innerBudget = budget - 1;
+	const nonCompleted = all.filter((t) => t.status !== "completed");
+	const totalCompleted = all.length - nonCompleted.length;
+	if (nonCompleted.length <= innerBudget) {
+		const kept = new Set<Task>(nonCompleted);
+		for (const t of all) {
+			if (kept.size >= innerBudget) break;
+			if (t.status === "completed") kept.add(t);
+		}
+		const visible = all.filter((t) => kept.has(t));
+		const shownCompleted = visible.filter((t) => t.status === "completed").length;
+		return { visible, hiddenCompleted: totalCompleted - shownCompleted, truncatedTail: 0 };
+	}
+	const visible = nonCompleted.slice(0, innerBudget);
+	const truncatedTail = nonCompleted.length - innerBudget;
+	return { visible, hiddenCompleted: totalCompleted, truncatedTail };
+}
+
+/**
+ * Helper: whether any visible task is `pending` or `in_progress`. The overlay
+ * uses this to pick the heading icon (`accent`+`●` vs `dim`+`○`).
+ */
+export function selectHasActive(state: TaskState): boolean {
+	return selectVisibleTasks(state).some((t) => t.status === "in_progress" || t.status === "pending");
+}
+
+export const ACTIVE_STATUSES: ReadonlySet<TaskStatus> = new Set(["pending", "in_progress"]);

package/extensions/phi/todo/state/state-reducer.ts

@@ -0,0 +1,187 @@
+import type { Task, TaskAction, TaskMutationParams, TaskStatus } from "../tool/types.js";
+import { isTransitionValid } from "./invariants.js";
+import type { TaskState } from "./state.js";
+import { detectCycle } from "./task-graph.js";
+
+/**
+ * Reducer outcome. Closed tagged union — adding a new action requires extending
+ * this union AND the response-envelope's `formatContent` switch (compiler-
+ * enforced exhaustive). Mirrors the `Effect` pattern in
+ * `packages/rpiv-ask-user-question/state/state-reducer.ts:14-30`.
+ *
+ * `error` carries the message in-band so callers can pattern-match on
+ * `op.kind === "error"` without a side-channel boolean.
+ */
+export type Op =
+	| { kind: "create"; taskId: number }
+	| { kind: "update"; id: number; fromStatus: TaskStatus; toStatus: TaskStatus }
+	| { kind: "delete"; id: number; subject: string }
+	| { kind: "list"; statusFilter?: TaskStatus; includeDeleted: boolean }
+	| { kind: "get"; task: Task }
+	| { kind: "clear"; count: number }
+	| { kind: "error"; message: string };
+
+export interface ApplyResult {
+	state: TaskState;
+	op: Op;
+}
+
+function errorResult(state: TaskState, message: string): ApplyResult {
+	return { state, op: { kind: "error", message } };
+}
+
+/**
+ * Pure reducer: (state, action, params) → (state, op). Mirrors the
+ * `applyTaskMutation` of pre-refactor `todo.ts` minus content/details
+ * formatting; the response envelope (`tool/response-envelope.ts`) owns
+ * formatting, the store (`state/store.ts`) owns commit.
+ *
+ * Validation is in-line: structural guards (`subject required`, `id required`,
+ * `at least one mutable field`) plus state-aware checks (transition legality,
+ * dangling/deleted blockedBy, self-block, cycles). Decision: validation stays
+ * in-reducer — see Plan §Decisions §Decision 2.
+ */
+export function applyTaskMutation(state: TaskState, action: TaskAction, params: TaskMutationParams): ApplyResult {
+	switch (action) {
+		case "create": {
+			if (!params.subject?.trim()) {
+				return errorResult(state, "subject required for create");
+			}
+			if (params.blockedBy?.length) {
+				for (const dep of params.blockedBy) {
+					const depTask = state.tasks.find((t) => t.id === dep);
+					if (!depTask) return errorResult(state, `blockedBy: #${dep} not found`);
+					if (depTask.status === "deleted") return errorResult(state, `blockedBy: #${dep} is deleted`);
+				}
+			}
+			const newTask: Task = {
+				id: state.nextId,
+				subject: params.subject,
+				status: "pending",
+			};
+			if (params.description) newTask.description = params.description;
+			if (params.activeForm) newTask.activeForm = params.activeForm;
+			if (params.blockedBy?.length) newTask.blockedBy = [...params.blockedBy];
+			if (params.owner) newTask.owner = params.owner;
+			if (params.metadata) newTask.metadata = { ...params.metadata };
+
+			const newTasks = [...state.tasks, newTask];
+			return {
+				state: { tasks: newTasks, nextId: state.nextId + 1 },
+				op: { kind: "create", taskId: newTask.id },
+			};
+		}
+
+		case "update": {
+			if (params.id === undefined) return errorResult(state, "id required for update");
+			const idx = state.tasks.findIndex((t) => t.id === params.id);
+			if (idx === -1) return errorResult(state, `#${params.id} not found`);
+			const current = state.tasks[idx];
+
+			const hasMutation =
+				params.subject !== undefined ||
+				params.description !== undefined ||
+				params.activeForm !== undefined ||
+				params.status !== undefined ||
+				params.owner !== undefined ||
+				params.metadata !== undefined ||
+				(params.addBlockedBy && params.addBlockedBy.length > 0) ||
+				(params.removeBlockedBy && params.removeBlockedBy.length > 0);
+			if (!hasMutation) return errorResult(state, "update requires at least one mutable field");
+
+			let newStatus = current.status;
+			if (params.status !== undefined) {
+				if (!isTransitionValid(current.status, params.status)) {
+					return errorResult(state, `illegal transition ${current.status} → ${params.status}`);
+				}
+				newStatus = params.status;
+			}
+
+			let newBlockedBy = current.blockedBy ? [...current.blockedBy] : [];
+			if (params.removeBlockedBy?.length) {
+				const toRemove = new Set(params.removeBlockedBy);
+				newBlockedBy = newBlockedBy.filter((dep) => !toRemove.has(dep));
+			}
+			if (params.addBlockedBy?.length) {
+				for (const dep of params.addBlockedBy) {
+					if (dep === current.id) return errorResult(state, `cannot block #${current.id} on itself`);
+					const depTask = state.tasks.find((t) => t.id === dep);
+					if (!depTask) return errorResult(state, `addBlockedBy: #${dep} not found`);
+					if (depTask.status === "deleted") return errorResult(state, `addBlockedBy: #${dep} is deleted`);
+					if (!newBlockedBy.includes(dep)) newBlockedBy.push(dep);
+				}
+				if (detectCycle(state.tasks, current.id, newBlockedBy)) {
+					return errorResult(state, "addBlockedBy would create a cycle in the blockedBy graph");
+				}
+			}
+
+			let newMetadata = current.metadata;
+			if (params.metadata !== undefined) {
+				const merged: Record<string, unknown> = { ...(current.metadata ?? {}) };
+				for (const [k, v] of Object.entries(params.metadata)) {
+					if (v === null) delete merged[k];
+					else merged[k] = v;
+				}
+				newMetadata = Object.keys(merged).length ? merged : undefined;
+			}
+
+			const updated: Task = { ...current, status: newStatus };
+			if (params.subject !== undefined) updated.subject = params.subject;
+			if (params.description !== undefined) updated.description = params.description;
+			if (params.activeForm !== undefined) updated.activeForm = params.activeForm;
+			if (params.owner !== undefined) updated.owner = params.owner;
+			if (newBlockedBy.length) updated.blockedBy = newBlockedBy;
+			else delete updated.blockedBy;
+			if (newMetadata === undefined) delete updated.metadata;
+			else updated.metadata = newMetadata;
+
+			const newTasks = [...state.tasks];
+			newTasks[idx] = updated;
+			return {
+				state: { tasks: newTasks, nextId: state.nextId },
+				op: { kind: "update", id: updated.id, fromStatus: current.status, toStatus: newStatus },
+			};
+		}
+
+		case "list": {
+			return {
+				state,
+				op: {
+					kind: "list",
+					includeDeleted: params.includeDeleted === true,
+					...(params.status !== undefined ? { statusFilter: params.status } : {}),
+				},
+			};
+		}
+
+		case "get": {
+			if (params.id === undefined) return errorResult(state, "id required for get");
+			const task = state.tasks.find((t) => t.id === params.id);
+			if (!task) return errorResult(state, `#${params.id} not found`);
+			return { state, op: { kind: "get", task } };
+		}
+
+		case "delete": {
+			if (params.id === undefined) return errorResult(state, "id required for delete");
+			const idx = state.tasks.findIndex((t) => t.id === params.id);
+			if (idx === -1) return errorResult(state, `#${params.id} not found`);
+			const current = state.tasks[idx];
+			if (current.status === "deleted") return errorResult(state, `#${current.id} is already deleted`);
+			const updated: Task = { ...current, status: "deleted" };
+			const newTasks = [...state.tasks];
+			newTasks[idx] = updated;
+			return {
+				state: { tasks: newTasks, nextId: state.nextId },
+				op: { kind: "delete", id: updated.id, subject: updated.subject },
+			};
+		}
+
+		case "clear": {
+			const count = state.tasks.length;
+			return {
+				state: { tasks: [], nextId: 1 },
+				op: { kind: "clear", count },
+			};
+		}
+	}
+}

package/extensions/phi/todo/state/state.ts

@@ -0,0 +1,18 @@
+import type { Task } from "../tool/types.js";
+
+/**
+ * Canonical state for the todo tool. Single source of truth — both the reducer
+ * (`state/state-reducer.ts`) and the live store cell (`state/store.ts`) read
+ * this shape. Replay (`state/replay.ts`) returns a fresh `TaskState`; the
+ * lifecycle handlers in `index.ts` write it via `replaceState`.
+ *
+ * The shape is intentionally minimal — no derived caches or runtime cells.
+ * Selectors in `state/selectors.ts` are pure of `TaskState` and own all
+ * derivations (visible/grouped/counted/etc).
+ */
+export interface TaskState {
+	tasks: Task[];
+	nextId: number;
+}
+
+export const EMPTY_STATE: TaskState = { tasks: [], nextId: 1 };

package/extensions/phi/todo/state/store.ts

@@ -0,0 +1,54 @@
+import type { Task } from "../tool/types.js";
+import { EMPTY_STATE, type TaskState } from "./state.js";
+
+/**
+ * Module-level live state cell. Pre-refactor this lived as bare `tasks` /
+ * `nextId` consts in `todo.ts`; centralizing here keeps the store as the
+ * single mutation seam and lets the reducer remain pure.
+ */
+let state: TaskState = { tasks: [...EMPTY_STATE.tasks], nextId: EMPTY_STATE.nextId };
+
+/**
+ * Live tasks accessor. Returned `readonly Task[]` so callers (overlay render
+ * hook, `/todos` command, `renderCall` subject lookup) cannot mutate the live
+ * cell. Consumers must not cast back.
+ */
+export function getTodos(): readonly Task[] {
+	return state.tasks;
+}
+
+export function getNextId(): number {
+	return state.nextId;
+}
+
+/** Snapshot accessor used by reducer callers to pass canonical state in. */
+export function getState(): TaskState {
+	return state;
+}
+
+/**
+ * Replay seam. Lifecycle handlers in `index.ts` call this on
+ * `session_start` / `session_compact` / `session_tree` after
+ * `replayFromBranch` decodes the latest snapshot.
+ */
+export function replaceState(next: TaskState): void {
+	state = next;
+}
+
+/**
+ * Post-reducer commit seam. Tool execute() calls this with the reducer's
+ * `state` output to publish the new canonical state to live readers (overlay,
+ * `/todos`, renderCall).
+ */
+export function commitState(next: TaskState): void {
+	state = next;
+}
+
+/**
+ * Test-setup reset. Wired into the global `test/setup.ts` `beforeEach` via
+ * the existing `__resetState` import path. Name preserved verbatim — see
+ * Plan §Decisions §Decision 7.
+ */
+export function __resetState(): void {
+	state = { tasks: [...EMPTY_STATE.tasks], nextId: EMPTY_STATE.nextId };
+}

package/extensions/phi/todo/state/task-graph.ts

@@ -0,0 +1,57 @@
+import type { Task } from "../tool/types.js";
+
+/**
+ * Detect whether merging `newBlockedBy` into `taskId`'s `blockedBy` set would
+ * introduce a cycle in the dependency graph.
+ *
+ * Pure of any module state; takes the existing `taskList` and the proposed
+ * additions explicitly so the reducer can ask "would this update cycle?"
+ * without mutating state first.
+ */
+export function detectCycle(taskList: readonly Task[], taskId: number, newBlockedBy: readonly number[]): boolean {
+	const edges = new Map<number, number[]>();
+	for (const t of taskList) {
+		if (t.id === taskId) {
+			const merged = new Set([...(t.blockedBy ?? []), ...newBlockedBy]);
+			edges.set(t.id, [...merged]);
+		} else {
+			edges.set(t.id, t.blockedBy ? [...t.blockedBy] : []);
+		}
+	}
+
+	const visiting = new Set<number>();
+	const visited = new Set<number>();
+	const hasCycleFrom = (node: number): boolean => {
+		if (visiting.has(node)) return true;
+		if (visited.has(node)) return false;
+		visiting.add(node);
+		for (const nb of edges.get(node) ?? []) {
+			if (hasCycleFrom(nb)) return true;
+		}
+		visiting.delete(node);
+		visited.add(node);
+		return false;
+	};
+
+	for (const node of edges.keys()) {
+		if (hasCycleFrom(node)) return true;
+	}
+	return false;
+}
+
+/**
+ * Build the inverse adjacency map: for each task `T`, which other tasks list
+ * `T` in their `blockedBy`. Consumed by `selectShowTaskIds` (overlay gating)
+ * and the `get` action's "blocks: #x, #y" suffix line.
+ */
+export function deriveBlocks(taskList: readonly Task[]): Map<number, number[]> {
+	const blocks = new Map<number, number[]>();
+	for (const t of taskList) {
+		for (const dep of t.blockedBy ?? []) {
+			const arr = blocks.get(dep) ?? [];
+			arr.push(t.id);
+			blocks.set(dep, arr);
+		}
+	}
+	return blocks;
+}

package/extensions/phi/todo/todo-overlay.ts

@@ -0,0 +1,194 @@
+/**
+ * todo-overlay.ts — Persistent widget showing todo list above the editor.
+ *
+ * Lifecycle controller for Pi's `setWidget` contract: factory-form
+ * registration in widgetContainerAbove, register-once + requestRender()
+ * refresh, 12-line collapse-not-scroll (plus a trailing spacer row, so the
+ * widget renders up to 13 lines), auto-hide when empty.
+ *
+ * Reads live state via `getState()` at render time — NEVER `replayFromBranch`
+ * from `tool_execution_end` (branch is stale; `message_end` runs after).
+ */
+
+import type { ExtensionUIContext, Theme } from "phi-code";
+import { type TUI, truncateToWidth } from "phi-code-tui";
+import { formatStatusLabel, t } from "./state/i18n-bridge.js";
+import { selectHasActive, selectOverlayLayout, selectShowTaskIds, selectTodoCounts } from "./state/selectors.js";
+import { getState } from "./state/store.js";
+import { formatOverlayTaskLine } from "./view/format.js";
+
+const WIDGET_KEY = "rpiv-todos";
+// Budget for content rows (heading + tasks/summary). The rendered widget is
+// one line taller — withTrailingSpacer() appends a blank row below the panel.
+const MAX_WIDGET_LINES = 12;
+
+// English fallbacks for localized overlay chrome strings.
+const OVERLAY_HEADING = "Todos";
+const OVERLAY_MORE = "more";
+
+export class TodoOverlay {
+	private uiCtx: ExtensionUIContext | undefined;
+	private widgetRegistered = false;
+	private tui: TUI | undefined;
+	private completedTaskIdsPendingHide = new Set<number>();
+	private hiddenCompletedTaskIds = new Set<number>();
+	private lastNextId: number | undefined;
+
+	setUICtx(ctx: ExtensionUIContext): void {
+		// Identity-compare so repeat session_start handlers are idempotent;
+		// on identity change (/reload) invalidate so update() re-registers.
+		if (ctx !== this.uiCtx) {
+			this.uiCtx = ctx;
+			this.widgetRegistered = false;
+			this.tui = undefined;
+		}
+	}
+
+	update(): void {
+		if (!this.uiCtx) return;
+		const snapshot = this.getSnapshot();
+		const visible = this.selectOverlayTasks(snapshot);
+
+		if (visible.length === 0) {
+			if (this.widgetRegistered) {
+				this.uiCtx.setWidget(WIDGET_KEY, undefined);
+				this.widgetRegistered = false;
+				this.tui = undefined;
+			}
+			return;
+		}
+
+		if (!this.widgetRegistered) {
+			this.uiCtx.setWidget(
+				WIDGET_KEY,
+				(tui, theme) => {
+					this.tui = tui;
+					return {
+						render: (width: number) => this.renderWidget(theme, width),
+						invalidate: () => {
+							this.widgetRegistered = false;
+							this.tui = undefined;
+						},
+					};
+				},
+				{ placement: "aboveEditor" },
+			);
+			this.widgetRegistered = true;
+		} else {
+			this.tui?.requestRender();
+		}
+	}
+
+	resetCompletedDisplayState(): void {
+		this.completedTaskIdsPendingHide.clear();
+		this.hiddenCompletedTaskIds.clear();
+		this.lastNextId = undefined;
+	}
+
+	hideCompletedTasksFromPreviousTurn(): void {
+		if (this.completedTaskIdsPendingHide.size === 0) return;
+		for (const taskId of this.completedTaskIdsPendingHide) {
+			this.hiddenCompletedTaskIds.add(taskId);
+		}
+		this.completedTaskIdsPendingHide.clear();
+		this.tui?.requestRender();
+	}
+
+	private getSnapshot() {
+		const state = getState();
+		if (this.lastNextId !== undefined && state.nextId < this.lastNextId) {
+			this.resetCompletedDisplayState();
+		}
+		this.lastNextId = state.nextId;
+		const completedTaskIds = new Set(
+			state.tasks.filter((task) => task.status === "completed").map((task) => task.id),
+		);
+		for (const taskId of this.completedTaskIdsPendingHide) {
+			if (!completedTaskIds.has(taskId)) this.completedTaskIdsPendingHide.delete(taskId);
+		}
+		for (const taskId of this.hiddenCompletedTaskIds) {
+			if (!completedTaskIds.has(taskId)) this.hiddenCompletedTaskIds.delete(taskId);
+		}
+		return { tasks: [...state.tasks], nextId: state.nextId };
+	}
+
+	private selectOverlayTasks(snapshot: ReturnType<TodoOverlay["getSnapshot"]>) {
+		return snapshot.tasks.filter((task) => task.status !== "deleted" && !this.shouldHideCompletedTask(task));
+	}
+
+	private shouldHideCompletedTask(task: ReturnType<TodoOverlay["getSnapshot"]>["tasks"][number]): boolean {
+		return task.status === "completed" && this.hiddenCompletedTaskIds.has(task.id);
+	}
+
+	private renderWidget(theme: Theme, width: number): string[] {
+		const snapshot = this.getSnapshot();
+		const overlayTasks = this.selectOverlayTasks(snapshot);
+		if (overlayTasks.length === 0) return [];
+
+		const overlayState = { tasks: overlayTasks, nextId: snapshot.nextId };
+		const truncate = (line: string): string => truncateToWidth(line, width, "…");
+		const counts = selectTodoCounts(overlayState);
+		const hasActive = selectHasActive(overlayState);
+		const showIds = selectShowTaskIds(overlayState);
+
+		const headingColor = hasActive ? "accent" : "dim";
+		const headingIcon = hasActive ? "●" : "○";
+		const headingText = `${t("overlay.heading", OVERLAY_HEADING)} (${counts.completed}/${counts.total})`;
+		const heading = truncate(`${theme.fg(headingColor, headingIcon)} ${theme.fg(headingColor, headingText)}`);
+
+		const lines: string[] = [heading];
+		const layout = selectOverlayLayout(overlayState, MAX_WIDGET_LINES - 1);
+		for (const task of layout.visible) {
+			lines.push(truncate(`${theme.fg("dim", "├─")} ${formatOverlayTaskLine(task, theme, showIds)}`));
+		}
+
+		const newlyDisplayedCompletedTaskIds = overlayTasks
+			.filter(
+				(task) =>
+					task.status === "completed" &&
+					!this.completedTaskIdsPendingHide.has(task.id) &&
+					!this.hiddenCompletedTaskIds.has(task.id),
+			)
+			.map((task) => task.id);
+		for (const taskId of newlyDisplayedCompletedTaskIds) {
+			this.completedTaskIdsPendingHide.add(taskId);
+		}
+
+		if (layout.hiddenCompleted === 0 && layout.truncatedTail === 0) {
+			const last = lines.length - 1;
+			lines[last] = lines[last].replace("├─", "└─");
+			return this.withTrailingSpacer(lines);
+		}
+
+		const totalHidden = layout.hiddenCompleted + layout.truncatedTail;
+		const overflowParts: string[] = [];
+		if (layout.hiddenCompleted > 0) overflowParts.push(`${layout.hiddenCompleted} ${formatStatusLabel("completed")}`);
+		if (layout.truncatedTail > 0) overflowParts.push(`${layout.truncatedTail} ${formatStatusLabel("pending")}`);
+		const more = t("overlay.more", OVERLAY_MORE);
+		const summary =
+			overflowParts.length > 0 ? `+${totalHidden} ${more} (${overflowParts.join(", ")})` : `+${totalHidden} ${more}`;
+		lines.push(truncate(`${theme.fg("dim", "└─")} ${theme.fg("dim", summary)}`));
+		return this.withTrailingSpacer(lines);
+	}
+
+	/**
+	 * Append a trailing blank line so the overlay isn't flush against the
+	 * editor box. Pi's host adds a leading spacer above the widget but none
+	 * below, which leaves the last "└─" row (or the "+N more" summary) glued
+	 * to the input box. The empty string gives the "Todos" panel a little
+	 * breathing room.
+	 */
+	private withTrailingSpacer(lines: string[]): string[] {
+		if (lines.length === 0) return lines;
+		lines.push("");
+		return lines;
+	}
+
+	dispose(): void {
+		if (this.uiCtx) this.uiCtx.setWidget(WIDGET_KEY, undefined);
+		this.widgetRegistered = false;
+		this.tui = undefined;
+		this.uiCtx = undefined;
+		this.resetCompletedDisplayState();
+	}
+}