@zhushanwen/pi-todo 0.9.0 → 0.9.2

package/README.md

@@ -37,7 +37,7 @@ pi install npm:@zhushanwen/pi-todo
 
 ### 错误处理约定
 
-handler 失败**直接 `throw new Error()`**，不返回错误成功模式（见 CLAUDE.md「Tool 设计」）。常见错误：
+handler 失败**直接 `throw new Error()`**，不返回错误成功模式（见 docs/extensions/extension-conventions.md「Tool 设计」）。常见错误：
 
 | 触发 | 错误信息 |
 |------|---------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "AI-driven todo list for Pi — stateful task management with session persistence and /todos command.",
   "type": "module",
   "main": "src/index.ts",
@@ -29,7 +29,7 @@
     "vitest": "^4.1.8"
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.9.0",
+    "@xyz-agent/extension-protocol": "0.11.0",
     "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "peerDependencies": {

package/src/__tests__/render.test.ts

@@ -1,8 +1,9 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
 import { describe, expect, it } from "vitest";
 
 import type { Todo, TodoDetails } from "../model";
-import { renderTodoResult } from "../render";
+import { renderDualColumn, renderTodoResult } from "../render";
 
 // ── mock theme（fg 直通，便于断言纯文本）────────────
 
@@ -100,3 +101,53 @@ describe("renderTodoResult", () => {
 		expect(renderedText(result)).toContain("Done");
 	});
 });
+
+// ── renderDualColumn 列宽行为锁定 ──────────────────────
+// 锁定 D14 替换前的列宽补齐/截断可见输出（ext-simplify 裁决零行为变化）：
+// 截断形态是「前缀 + 6 个点」（内层省略号 + 外层省略号的旧组合）——这是锁定旧行为，不是认可该形态。
+
+describe("renderDualColumn column fitting", () => {
+	const longTodos: Todo[] = [
+		{ id: 1, text: "x".repeat(30), status: "pending" },
+		{ id: 2, text: "y".repeat(30), status: "pending" },
+	];
+
+	it("超宽列文本截断为 前缀+6点，两列均恰好列宽", () => {
+		const termWidth = 27; // colWidth = floor((27 - 2 - 3) / 2) = 11
+		const lines = renderDualColumn(longTodos, mockTheme, termWidth, "  ");
+		expect(lines).toHaveLength(1);
+		const row = stripTerminalSequences(lines[0]);
+		expect(visibleWidth(row)).toBe(11 + 3 + 11);
+		const divIdx = row.indexOf("│");
+		// divider（" │ "）的前后空格不属于列内容，trim 后再断言
+		const left = row.slice(0, divIdx).trimEnd();
+		const right = row.slice(divIdx + 1).trimStart();
+		// 两列均以 6 个点收尾（前缀+6点旧形态）
+		expect(left.endsWith("......")).toBe(true);
+		expect(right.endsWith("......")).toBe(true);
+		// 点前的前缀可见宽恰为 colWidth - 6
+		expect(visibleWidth(left.slice(0, left.length - 6))).toBe(11 - 6);
+	});
+
+	it("列内文本未超宽时不产生省略号，补齐到列宽", () => {
+		const shortTodos: Todo[] = [
+			{ id: 1, text: "ab", status: "pending" },
+			{ id: 2, text: "cd", status: "pending" },
+		];
+		const lines = renderDualColumn(shortTodos, mockTheme, 27, "  ");
+		const row = stripTerminalSequences(lines[0]);
+		expect(visibleWidth(row)).toBe(11 + 3 + 11);
+		expect(row).not.toContain(".");
+		expect(row).toContain("#1 ab");
+		expect(row).toContain("#2 cd");
+	});
+
+	it("colWidth <= 3 时超宽列退化为省略号截片", () => {
+		const termWidth = 11; // colWidth = floor((11 - 2 - 3) / 2) = 3
+		const lines = renderDualColumn(longTodos, mockTheme, termWidth, "  ");
+		const row = stripTerminalSequences(lines[0]);
+		expect(visibleWidth(row)).toBe(3 + 3 + 3);
+		const divIdx = row.indexOf("│");
+		expect(row.slice(0, divIdx).trimEnd()).toBe("...");
+	});
+});

package/src/__tests__/steer.test.ts

@@ -68,13 +68,13 @@ describe("handleCompletionSteer", () => {
 describe("handleAutoClear", () => {
 	it("does not handle when not all completed, and resets anchor", () => {
 		const s = makeState([{ id: 1, text: "a", status: "pending" }], { allCompletedAtCount: 3 });
-		expect(handleAutoClear(s)).toEqual({ handled: false, cleared: false });
+		expect(handleAutoClear(s)).toBe(false);
 		expect(s.allCompletedAtCount).toBeNull();
 	});
 
 	it("anchors on first all-completed round without clearing", () => {
 		const s = makeState([{ id: 1, text: "a", status: "completed" }], { userMessageCount: 5 });
-		expect(handleAutoClear(s)).toEqual({ handled: true, cleared: false });
+		expect(handleAutoClear(s)).toBe(false);
 		expect(s.allCompletedAtCount).toBe(5);
 		expect(s.todos).toHaveLength(1);
 	});
@@ -83,14 +83,14 @@ describe("handleAutoClear", () => {
 		const s = makeState([{ id: 1, text: "a", status: "completed" }], {
 			userMessageCount: 5, allCompletedAtCount: 4,
 		});
-		expect(handleAutoClear(s)).toEqual({ handled: true, cleared: false });
+		expect(handleAutoClear(s)).toBe(false);
 	});
 
 	it("clears and resets flags after delay elapses", () => {
 		const s = makeState([{ id: 1, text: "a", status: "completed" }], {
 			userMessageCount: 6, allCompletedAtCount: 4, completionSteered: true,
 		});
-		expect(handleAutoClear(s)).toEqual({ handled: true, cleared: true });
+		expect(handleAutoClear(s)).toBe(true);
 		expect(s.todos).toEqual([]);
 		expect(s.nextId).toBe(1);
 		expect(s.allCompletedAtCount).toBeNull();
@@ -229,10 +229,10 @@ describe("reconstructState", () => {
 describe("agent_end short-circuit order", () => {
 	it("completion steer fires before auto-clear (completion does not short-circuit)", () => {
 		const s = makeState([{ id: 1, text: "a", status: "completed" }], { userMessageCount: 5 });
-		// 模拟 agent_end: handleCompletionSteer(不短路) → handleAutoClear(短路)
+		// 模拟 agent_end: handleCompletionSteer(不短路) → handleAutoClear
 		expect(handleCompletionSteer(s)).toBe(true);
 		expect(s.pendingSteerMessage).toContain("交付质量");
-		expect(handleAutoClear(s)).toEqual({ handled: true, cleared: false });
+		expect(handleAutoClear(s)).toBe(false);
 		expect(s.allCompletedAtCount).toBe(5);
 	});
 
@@ -243,7 +243,7 @@ describe("agent_end short-circuit order", () => {
 			completionSteered: true, pendingSteerMessage: "<queued>",
 		});
 		expect(handleCompletionSteer(s)).toBe(false); // 已 steered，不重复
-		expect(handleAutoClear(s).cleared).toBe(true);
+		expect(handleAutoClear(s)).toBe(true);
 		expect(s.todos).toEqual([]);
 		// pendingSteerMessage 仍保留，由下一 turn before_agent_start 消费（此时 todos 已空）
 		expect(s.pendingSteerMessage).toBe("<queued>");

package/src/__tests__/todo.test.ts

@@ -198,7 +198,6 @@ describe("todo update batch", () => {
 			{ id: 3, status: "completed", text: "C done" },
 		]);
 
-		expect(result.error).toBeUndefined();
 		expect(result.updatedTodos).toHaveLength(3);
 		expect(result.updatedTodos[0].status).toBe("completed");
 		expect(result.updatedTodos[0].text).toBe("A");
@@ -211,7 +210,6 @@ describe("todo update batch", () => {
 	it("TC6: trims text on apply（批量路径）", () => {
 		const todos: Todo[] = [{ id: 1, text: "A", status: "pending" }];
 		const result = updateTodos(todos, [{ id: 1, text: "  B updated  " }]);
-		expect(result.error).toBeUndefined();
 		expect(result.updatedTodos[0].text).toBe("B updated");
 	});
 
@@ -222,30 +220,33 @@ describe("todo update batch", () => {
 
 	it("should reject duplicate ids in updates[]", () => {
 		const todos: Todo[] = [{ id: 1, text: "A", status: "pending" }];
-		const result = updateTodos(todos, [
-			{ id: 1, status: "completed" },
-			{ id: 1, status: "pending" },
-		]);
-		expect(result.error).toBe("duplicate ids in updates");
-		expect(result.updatedTodos).toEqual(todos);
+		expect(() =>
+			updateTodos(todos, [
+				{ id: 1, status: "completed" },
+				{ id: 1, status: "pending" },
+			]),
+		).toThrow("duplicate ids in updates");
 	});
 
 	it("should reject non-existent ids", () => {
 		const todos: Todo[] = [{ id: 1, text: "A", status: "pending" }];
-		const result = updateTodos(todos, [{ id: 999, status: "pending" }]);
-		expect(result.error).toBe("id 999 not found");
+		expect(() => updateTodos(todos, [{ id: 999, status: "pending" }])).toThrow(
+			"Todo #999 not found",
+		);
 	});
 
 	it("should reject updates[] item missing both status and text", () => {
 		const todos: Todo[] = [{ id: 1, text: "A", status: "pending" }];
-		const result = updateTodos(todos, [{ id: 1 }]);
-		expect(result.error).toContain("neither status nor text");
+		expect(() => updateTodos(todos, [{ id: 1 }])).toThrow(
+			"update item for id 1 has neither status nor text",
+		);
 	});
 
 	it("should reject invalid status values", () => {
 		const todos: Todo[] = [{ id: 1, text: "A", status: "pending" }];
-		const result = updateTodos(todos, [{ id: 1, status: "banana" }]);
-		expect(result.error).toContain("invalid status");
+		expect(() => updateTodos(todos, [{ id: 1, status: "banana" }])).toThrow(
+			"invalid status 'banana' for update item id 1",
+		);
 	});
 });
 
@@ -312,14 +313,12 @@ describe("completed without interception", () => {
 	it("should allow in_progress → completed directly", () => {
 		const todos: Todo[] = [{ id: 1, text: "simple", status: "in_progress" }];
 		const result = updateTodos(todos, [{ id: 1, status: "completed" }]);
-		expect(result.error).toBeUndefined();
 		expect(result.updatedTodos[0].status).toBe("completed");
 	});
 
 	it("should allow pending → completed directly", () => {
 		const todos: Todo[] = [{ id: 1, text: "skip", status: "pending" }];
 		const result = updateTodos(todos, [{ id: 1, status: "completed" }]);
-		expect(result.error).toBeUndefined();
 		expect(result.updatedTodos[0].status).toBe("completed");
 	});
 
@@ -332,7 +331,6 @@ describe("completed without interception", () => {
 			{ id: 1, status: "completed" },
 			{ id: 2, status: "completed" },
 		]);
-		expect(result.error).toBeUndefined();
 		expect(result.updatedTodos[0].status).toBe("completed");
 		expect(result.updatedTodos[1].status).toBe("completed");
 	});

package/src/__tests__/tool-rpc.test.ts

@@ -203,7 +203,7 @@ describe("refreshDisplay — GUI widget 推送（setup 传真实实现）", () =
 		const [, value] = setWidget.mock.calls[0]!;
 		expect(value!.length).toBeGreaterThan(0);
 		for (const line of value!) {
-			// isGuiCapable 外层判定生效：TUI 行不含 GUI marker 编码
+			// setWidgetDual 模式分派生效（守卫单点在 protocol helper）：TUI 行不含 GUI marker 编码
 			expect(line.startsWith(GUI_WIDGET_MARKER)).toBe(false);
 		}
 	});

package/src/component.ts

@@ -5,7 +5,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 
-import type { Todo } from "./model";
+import { todoProgress, type Todo } from "./model";
 import { FALLBACK_TERM_WIDTH, renderDualColumn } from "./render";
 
 const HEADER_PREFIX_DASHES = 3;
@@ -50,8 +50,7 @@ export class TodoListComponent {
 		if (this.todos.length === 0) {
 			lines.push(truncateToWidth(`${indent}${th.fg("dim", "No todos yet. Ask the agent to add some!")}`, termWidth));
 		} else {
-			const completed = this.todos.filter((t) => t.status === "completed").length;
-			const total = this.todos.length;
+			const { completed, total } = todoProgress(this.todos);
 			lines.push(truncateToWidth(`${indent}${th.fg("muted", `${completed}/${total} completed`)}`, termWidth));
 			lines.push("");
 

package/src/handlers.ts

@@ -10,6 +10,7 @@ import {
 	migrateTodo,
 	type TodoDetails,
 } from "./model";
+import { renderStatusText } from "./render";
 import type { TodoSessionState } from "./state";
 
 const logger = getLogger("todo");
@@ -94,11 +95,12 @@ export function reconstructState(state: TodoSessionState, ctx: ExtensionContext)
 
 // ── agent_end 子函数 ────────────────────────────────
 
-export function handleAutoClear(state: TodoSessionState): { handled: boolean; cleared: boolean } {
+/** 返回是否已清空（false 含三种形态：未全完成 / 本轮刚锚定 / 延迟未到——调用方均无需刷新） */
+export function handleAutoClear(state: TodoSessionState): boolean {
 	const allCompleted = state.todos.every((t) => t.status === "completed");
 	if (!allCompleted) {
 		state.allCompletedAtCount = null;
-		return { handled: false, cleared: false };
+		return false;
 	}
 	if (state.allCompletedAtCount === null) {
 		state.allCompletedAtCount = state.userMessageCount;
@@ -108,9 +110,9 @@ export function handleAutoClear(state: TodoSessionState): { handled: boolean; cl
 		state.nextId = 1;
 		state.allCompletedAtCount = null;
 		state.completionSteered = false;
-		return { handled: true, cleared: true };
+		return true;
 	}
-	return { handled: true, cleared: false };
+	return false;
 }
 
 export function handleCompletionSteer(state: TodoSessionState): boolean {
@@ -147,7 +149,8 @@ export function registerTodoEventHandlers(
 		try {
 			const pendingTodos = state.todos.filter(isPending);
 			if (pendingTodos.length > 0) {
-				ctx.ui.setStatus("todo", `📋 ${pendingTodos.length} pending`);
+				// 文案与 refreshDisplay 共用 renderStatusText（N/M 口径），避免同一 status 槽两种格式交替
+				ctx.ui.setStatus("todo", renderStatusText(state.todos, ctx.ui.theme));
 			}
 			// 优先级 1: agent_end 设置的延迟 steer
 			if (state.pendingSteerMessage) {
@@ -170,12 +173,8 @@ export function registerTodoEventHandlers(
 			// 全部 completed → 总检查 steer（仅一次）
 			handleCompletionSteer(state);
 
-			// auto-clear（全部完成后延迟清理）
-			const ac = handleAutoClear(state);
-			if (ac.handled) {
-				if (ac.cleared) refreshDisplay(ctx);
-				return;
-			}
+			// auto-clear（全部完成后延迟清理；已清空才需要刷新显示）
+			if (handleAutoClear(state)) refreshDisplay(ctx);
 		} catch (e) {
 			// best-effort：agent_end 事件处理器出错不阻断会话主流程，仅记录调试日志
 			logger.debug("agent_end error", { error: String(e) });

package/src/index.ts

@@ -16,15 +16,16 @@
  * - commands.ts: /todos 命令注册
  * - index.ts（本文件）: 工厂入口（创建 state + 注册 tool/command/event + makeRefreshDisplay）
  *
- * 错误处理：handler 失败直接 throw（见 CLAUDE.md「Tool 设计」），不返回错误成功模式。
- * model 层纯函数返回 Result 对象（合法），dispatcher 拿到 error 时 throw。
+ * 错误处理：包内单一 throw 协议——handler 与 model 层纯函数（addTodos / updateTodos）
+ * 校验失败均直接 throw（见 docs/extensions/extension-conventions.md「Tool 设计」），
+ * 不返回错误成功模式。
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { guiSetWidget, isGuiCapable, type GuiContext } from "@xyz-agent/extension-protocol";
+import { setWidgetDual, type GuiContext } from "@xyz-agent/extension-protocol";
 
 import { registerTodosCommand } from "./commands";
-import { registerTodoEventHandlers } from "./handlers";
+import { registerTodoEventHandlers, type RefreshDisplayFn } from "./handlers";
 import { buildGui } from "./model";
 import { renderStatusText, renderWidgetLines } from "./render";
 import { createTodoSessionState, type TodoSessionState } from "./state";
@@ -38,28 +39,23 @@ import { registerTodoTool } from "./tool";
  * 类型断言根因：pi 的 ExtensionContext.ui.custom 是泛型方法（返回 Promise<T>），
  * 与 GuiContext.ui.custom 的具体返回类型静态不兼容，传参需断言收窄；
  * mode/hasUI/ui.setWidget 形状一致（ExtensionMode 与 GuiContext.mode union 完全
- * 相同），单层直接断言可过 tsc（guiSetWidget/isGuiCapable 不读 custom），
- * 与 goal adapters/ports.ts setGuiWidget 同款。
+ * 相同），单层直接断言可过 tsc（setWidgetDual 只读 mode 与 ui.setWidget，
+ * 不读 custom）。
  *
- * isGuiCapable 外层判定不可省略：guiSetWidget 内部无 isGui 守卫
- * （extension-protocol helpers.ts 仅查 ctx.ui?.setWidget 存在性），
- * TUI 模式误调会把 marker 编码行推给原生 widget 造成乱码。
+ * 推送/清屏 × GUI/TUI 模式分派由 protocol setWidgetDual 单点内化
+ * （守卫单点化说明见 extension-protocol helpers.ts，本文件不再自持 isGui 判定）。
  */
-export function makeRefreshDisplay(state: TodoSessionState): (ctx: ExtensionContext) => void {
+export function makeRefreshDisplay(state: TodoSessionState): RefreshDisplayFn {
 	return function refreshDisplay(ctx: ExtensionContext): void {
 		const statusText = renderStatusText(state.todos, ctx.ui.theme);
 		ctx.ui.setStatus("todo", statusText || undefined);
-		const isGui = isGuiCapable(ctx as GuiContext);
 		if (state.todos.length === 0) {
-			if (isGui) {
-				guiSetWidget(ctx as GuiContext, "todo", undefined);
-			} else {
-				ctx.ui.setWidget("todo", undefined);
-			}
-		} else if (isGui) {
-			guiSetWidget(ctx as GuiContext, "todo", buildGui(state.todos));
+			setWidgetDual(ctx as GuiContext, "todo", undefined);
 		} else {
-			ctx.ui.setWidget("todo", renderWidgetLines(state.todos, ctx.ui.theme));
+			setWidgetDual(ctx as GuiContext, "todo", {
+				gui: buildGui(state.todos),
+				text: renderWidgetLines(state.todos, ctx.ui.theme),
+			});
 		}
 	};
 }

package/src/model.ts

@@ -27,7 +27,7 @@ export interface TodoDetails {
 
 export const VALID_STATUSES = ["pending", "in_progress", "completed"] as const;
 
-export type ValidStatus = (typeof VALID_STATUSES)[number];
+type ValidStatus = (typeof VALID_STATUSES)[number];
 
 // ── 迁移/兼容 ───────────────────────────────────────
 
@@ -70,6 +70,14 @@ export function migrateTodo(raw: unknown): Todo {
 
 // ── GUI 渲染辅助 ─────────────────────────────────────
 
+/** completed 计数单一来源：buildGui / renderStatusText / renderWidgetLines / component 四个消费点共用口径 */
+export function todoProgress(todos: Todo[]): { completed: number; total: number } {
+	return {
+		completed: todos.filter((t) => t.status === "completed").length,
+		total: todos.length,
+	};
+}
+
 /**
  * 把 todos 组装为 GuiRenderResult（v1.1 meta head 架构，对齐 extension-protocol@0.3.0）。
  *
@@ -85,8 +93,7 @@ export function migrateTodo(raw: unknown): Todo {
  *   completed    → done（success + label 弱化）
  */
 export function buildGui(todos: Todo[]): GuiRenderResult {
-	const total = todos.length;
-	const completed = todos.filter((t) => t.status === "completed").length;
+	const { completed, total } = todoProgress(todos);
 	const inProgress = todos.filter((t) => t.status === "in_progress").length;
 
 	const status: WidgetMeta["status"] =
@@ -118,7 +125,7 @@ export function buildGui(todos: Todo[]): GuiRenderResult {
 /** 建议的单 session todo 数上限（软约束：超限提醒，不硬拒绝） */
 export const RECOMMENDED_MAX_TODOS = 10;
 
-export interface AddResult {
+interface AddResult {
 	newTodos: Todo[];
 	newNextId: number;
 	resultText: string;
@@ -186,12 +193,17 @@ export function addTodos(
 
 // ── Update 逻辑 ──────────────────────────────────────
 
-export interface UpdateResult {
+/** updateTodos 成功返回形状；校验失败直接 throw（包内单一错误协议）。 */
+interface UpdateResult {
 	updatedTodos: Todo[];
-	error?: string;
-	resultText?: string;
+	resultText: string;
 }
 
+/**
+ * 批量更新 todo。校验失败（重复 id / id 不存在 / 无 status 无 text / 非法 status）
+ * 直接 throw——与 addTodos / handler 同一 throw 协议，文案不带 "Error: " 前缀
+ * （错误形态由 pi 工具错误通道表达）；throw 发生在任何突变之前，state 保持不变。
+ */
 export function updateTodos(
 	currentTodos: Todo[],
 	updates: Array<{ id: number; status?: string; text?: string }>,
@@ -205,34 +217,18 @@ export function updateTodos(
 
 	const ids = updates.map((u) => u.id);
 	if (new Set(ids).size !== ids.length) {
-		return {
-			updatedTodos: currentTodos,
-			error: "duplicate ids in updates",
-			resultText: "Error: duplicate ids in updates",
-		};
+		throw new Error("duplicate ids in updates");
 	}
 	for (const u of updates) {
 		const todo = currentTodos.find((t) => t.id === u.id);
 		if (!todo) {
-			return {
-				updatedTodos: currentTodos,
-				error: `id ${u.id} not found`,
-				resultText: `Error: Todo #${u.id} not found`,
-			};
+			throw new Error(`Todo #${u.id} not found`);
 		}
 		if (!u.status && !u.text) {
-			return {
-				updatedTodos: currentTodos,
-				error: `update item for id ${u.id} has neither status nor text`,
-				resultText: `Error: update item for id ${u.id} has neither status nor text`,
-			};
+			throw new Error(`update item for id ${u.id} has neither status nor text`);
 		}
 		if (u.status && !VALID_STATUSES.includes(u.status as (typeof VALID_STATUSES)[number])) {
-			return {
-				updatedTodos: currentTodos,
-				error: `invalid status: ${u.status}`,
-				resultText: `Error: invalid status '${u.status}' for update item id ${u.id}`,
-			};
+			throw new Error(`invalid status '${u.status}' for update item id ${u.id}`);
 		}
 	}
 

package/src/render.ts

@@ -2,10 +2,11 @@
  * Todo 渲染函数 — 状态栏、widget（双列）、tool result 渲染。
  */
 
-import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import {
+	todoProgress,
 	type Todo,
 	type TodoDetails,
 } from "./model";
@@ -24,25 +25,15 @@ const SINGLE_COLUMN_BUDGET = WIDGET_MAX_LINES - 1;
 
 /** 垂直分割线视觉宽度（" │ "） */
 const DIVIDER_VISUAL_WIDTH = 3;
-const ELLIPSIS_MIN_WIDTH = 3;
-
-/** 截断或补齐到精确视觉宽度，截断时追加 "..." */
-function fixedWidth(text: string, width: number): string {
-	const len = visibleWidth(text);
-	if (len <= width) {
-		return text + " ".repeat(width - len);
-	}
-	if (width <= ELLIPSIS_MIN_WIDTH) return "...".slice(0, width);
-	return truncateToWidth(text, width - ELLIPSIS_MIN_WIDTH) + "...";
-}
+/** 省略号视觉宽度（"..."） */
+const ELLIPSIS_WIDTH = 3;
 
 // ── 状态栏 ────────────────────────────────────────────
 
 export function renderStatusText(todoList: Todo[], th: Theme): string {
 	if (todoList.length === 0) return "";
 
-	const completed = todoList.filter((t) => t.status === "completed").length;
-	const total = todoList.length;
+	const { completed, total } = todoProgress(todoList);
 
 	if (completed === total) {
 		return th.fg("success", `\u2713 ${completed}/${total}`);
@@ -52,8 +43,9 @@ export function renderStatusText(todoList: Todo[], th: Theme): string {
 
 // ── Widget 双列渲染 ──────────────────────────────────
 
-/** 渲染单条 todo 的 widget 行（不含缩进），供 component.ts 复用 */
-function renderWidgetItem(t: Todo, th: Theme): string {
+/** 渲染单条 todo 的 widget 行（不含缩进），供 component.ts 复用。
+ * textColor = 非完成态文本颜色（widget 用 "text"，tool result 列表用 "muted"——历史差异显式保留，未做视觉统一）。 */
+function renderWidgetItem(t: Todo, th: Theme, textColor: ThemeColor = "text"): string {
 	const mark =
 		t.status === "completed"
 			? th.fg("success", "\u2713")
@@ -61,7 +53,7 @@ function renderWidgetItem(t: Todo, th: Theme): string {
 				? th.fg("warning", "\u25cf")
 				: th.fg("dim", "\u25cb"); // pending
 	const id = th.fg("accent", `#${t.id}`);
-	const text = t.status === "completed" ? th.fg("dim", t.text) : th.fg("text", t.text);
+	const text = t.status === "completed" ? th.fg("dim", t.text) : th.fg(textColor, t.text);
 	return `${mark} ${id} ${text}`;
 }
 
@@ -91,11 +83,22 @@ export function renderDualColumn(
 	const lines: string[] = [];
 	const half = Math.ceil(todos.length / COLUMN_COUNT);
 	const divider = " " + th.fg("borderMuted", "\u2502") + " ";
+	// 补齐/截断到列宽：可见输出与 D14 替换前的列宽逻辑逐字符一致（裁决零行为变化）——
+	// 截断列保持「前缀+6点」旧形态，不可简化为单调用 truncateToWidth(text, colWidth, "...", true)
+	// （会改为前缀+3点）；行为由 __tests__/render.test.ts 锁定。colWidth <= ELLIPSIS_WIDTH 走 pi-tui
+	// clipped-ellipsis 路径，可见一致（ANSI reset 包裹差异不影响渲染）。负列宽（病态窄终端）pi-tui 对
+	// maxWidth<=0 恒空串，无法复现旧 slice 负索引语义，保留原特判。
+	const fit = (text: string): string =>
+		colWidth < 0
+			? "...".slice(0, colWidth)
+			: visibleWidth(text) <= colWidth || colWidth <= ELLIPSIS_WIDTH
+				? truncateToWidth(text, colWidth, "...", true)
+				: truncateToWidth(text, colWidth - ELLIPSIS_WIDTH) + "...";
 	for (let row = 0; row < half; row++) {
-		const left = fixedWidth(indent + renderWidgetItem(todos[row], th), colWidth);
+		const left = fit(indent + renderWidgetItem(todos[row], th));
 		const rightIdx = row + half;
 		const right = rightIdx < todos.length
-			? fixedWidth(renderWidgetItem(todos[rightIdx], th), colWidth)
+			? fit(renderWidgetItem(todos[rightIdx], th))
 			: " ".repeat(colWidth);
 		lines.push(left + divider + right);
 	}
@@ -112,8 +115,7 @@ export function renderWidgetLines(
 
 	const width = termWidth ?? (process.stdout.columns || FALLBACK_TERM_WIDTH);
 	const lines: string[] = [];
-	const completed = todoList.filter((t) => t.status === "completed").length;
-	const total = todoList.length;
+	const { completed, total } = todoProgress(todoList);
 
 	lines.push(th.fg("accent", "\u2611") + th.fg("muted", ` ${completed}/${total}`));
 
@@ -141,15 +143,7 @@ function buildTodoListText(todoList: Todo[], options: { expanded: boolean }, the
 	let listText = theme.fg("muted", `${todoList.length} todos:`);
 	const display = options.expanded ? todoList : todoList.slice(0, MAX_COLLAPSED_ITEMS);
 	for (const t of display) {
-		const status = t.status;
-		const mark =
-			status === "completed"
-				? theme.fg("success", "\u2713")
-				: status === "in_progress"
-					? theme.fg("warning", "\u25cf")
-					: theme.fg("dim", "\u25cb"); // pending
-		const itemText = status === "completed" ? theme.fg("dim", t.text) : theme.fg("muted", t.text);
-		listText += `\n${mark} ${theme.fg("accent", `#${t.id}`)} ${itemText}`;
+		listText += `\n${renderWidgetItem(t, theme, "muted")}`;
 	}
 	if (!options.expanded && todoList.length > MAX_COLLAPSED_ITEMS) {
 		listText += `\n${theme.fg("dim", `... ${todoList.length - MAX_COLLAPSED_ITEMS} more`)}`;
@@ -160,12 +154,7 @@ function buildTodoListText(todoList: Todo[], options: { expanded: boolean }, the
 // ── Tool renderResult handler ────────────────────────
 
 import { Text } from "@earendil-works/pi-tui";
-
-/** content[0] 提取 text（缺失/非 text 类型 → 空串） */
-function firstContentText(r: { content: Array<{ type: string; text?: string }> }): string {
-	const text = r.content[0];
-	return text?.type === "text" ? (text.text ?? "") : "";
-}
+import { firstContentText } from "@xyz-agent/extension-protocol";
 
 export function renderTodoResult(result: unknown, options: { expanded: boolean }, theme: Theme): Text {
 	const r = result as { content: Array<{ type: string; text?: string }>; details?: unknown };

package/src/tool.ts

@@ -23,6 +23,7 @@ import {
 	VALID_STATUSES,
 } from "./model";
 import { renderTodoResult } from "./render";
+import type { RefreshDisplayFn } from "./handlers";
 import type { TodoSessionState } from "./state";
 
 // ── TodoParams schema（扁平 Type.Object，OpenAI 兼容）──────────
@@ -64,10 +65,10 @@ export const TodoParams = Type.Object(
 export type TodoParamsT = Static<typeof TodoParams>;
 
 // ── 4 个 action handler ──────────────────────────────
-// 错误处理约定（见 CLAUDE.md「Tool 设计」）：handler 失败直接 throw，
-// 不返回「错误成功模式」。model 层纯函数（updateTodos）返回 Result 对象（合法），
-// 由 dispatcher 在拿到 error 时 throw，把友好文案交给 Pi 框架展示。
-// addTodos 的校验失败直接 throw（C1：不再静默 filter）。
+// 错误处理约定（见 docs/extensions/extension-conventions.md「Tool 设计」）：
+// 包内单一 throw 协议——handler 与 model 层纯函数（addTodos / updateTodos）
+// 校验失败均直接 throw，把文案交给 Pi 框架以工具错误展示，不返回「错误成功模式」，
+// handler 也不做 error→throw 翻译。
 
 /** list action — 返回完整格式化列表 */
 function handleList(state: TodoSessionState): string {
@@ -107,9 +108,8 @@ export function handleAdd(state: TodoSessionState, params: TodoParamsT): string
 /** update action: batch — 失败抛错 */
 function handleBatchUpdate(state: TodoSessionState, params: TodoParamsT): string {
 	const r = updateTodos(state.todos, params.updates ?? []);
-	if (r.error) throw new Error(r.resultText);
 	state.todos = r.updatedTodos;
-	return r.resultText!;
+	return r.resultText;
 }
 
 /** update action: single — 失败抛错 */
@@ -186,7 +186,7 @@ function executeTodoAction(
 	params: TodoParamsT,
 	state: TodoSessionState,
 	ctx: ExtensionContext,
-	refreshDisplay: (ctx: ExtensionContext) => void,
+	refreshDisplay: RefreshDisplayFn,
 ): {
 	content: Array<{ type: "text"; text: string }>;
 	details: TodoDetails;
@@ -213,11 +213,10 @@ function executeTodoAction(
 
 	refreshDisplay(ctx);
 
-	// content 组装（T3）：突变附带完整列表；list 已含列表
+	// content 组装（T3）：突变附带完整列表（复用 handleList 的空列表兜底）；list 已含列表
 	let contentText: string;
 	if (isMutation) {
-		const listText = state.todos.length > 0 ? formatTodoList(state.todos) : "No todos";
-		contentText = `${resultText}\n${listText}`;
+		contentText = `${resultText}\n${handleList(state)}`;
 	} else {
 		contentText = resultText;
 	}
@@ -240,7 +239,7 @@ function executeTodoAction(
 export function registerTodoTool(
 	pi: ExtensionAPI,
 	state: TodoSessionState,
-	refreshDisplay: (ctx: ExtensionContext) => void,
+	refreshDisplay: RefreshDisplayFn,
 ): void {
 	pi.registerTool({
 		name: "todo",