@ilikexiaoni/pi-task-list 0.4.0 → 0.4.2

package/extensions/task-list.ts

@@ -1,68 +1,88 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { matchesKey, Text, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import { matchesKey, Text, truncateToWidth, type TUI, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
+  MAX_FIELD_LENGTH,
+  MAX_LIST_ITEMS,
+  MAX_SUBJECT_LENGTH,
   TASK_PRIORITIES,
   TASK_STATUSES,
   applyTaskAction,
   cloneState,
+  createTaskOperation,
   filterTasks,
+  isPersistedTaskState,
   isTaskReady,
   normalizeState,
   priorityLabel,
   statusLabel,
+  sanitizeTaskText,
   summarizeState,
   type Task,
   type TaskAction,
   type TaskCommand,
+  type TaskOperation,
   type TaskPriority,
   type TaskState,
   type TaskStatus,
+  type TaskSummary,
 } from "../lib/task-list-core.ts";
+import { restoreTaskListState, TASK_LIST_STATE_ENTRY_TYPE } from "../lib/task-list-persistence.ts";
 
 const TOOL_NAME = "task_list";
 const WIDGET_KEY = "task-list-widget";
 const STATUS_KEY = "task-list-status";
+const MAX_MODEL_OUTPUT_LENGTH = 12_000;
+const MAX_DETAIL_LINES = 1_200;
+const RPC_WIDGET_WIDTH = 80;
 
 interface TaskListDetails {
+  schemaVersion?: 2;
   action: TaskAction;
-  state: TaskState;
+  operation?: TaskOperation;
+  summary?: TaskSummary;
+  /** Full state written by releases before operation-based persistence. */
+  state?: unknown;
   changedIds: number[];
   visibleTasks: Task[];
   selectedTask?: Task;
   message: string;
 }
 
+const boundedString = (maxLength: number, description?: string) => Type.String({ maxLength, description });
+const taskTextList = (description?: string) => Type.Array(boundedString(MAX_FIELD_LENGTH), { maxItems: MAX_LIST_ITEMS, description });
+const taskIdList = (description?: string) => Type.Array(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }), { maxItems: MAX_LIST_ITEMS, description });
+
 const TaskListParams = Type.Object({
   action: StringEnum(["create", "update", "list", "get", "clear"] as const),
-  id: Type.Optional(Type.Number({ minimum: 1, description: "目标任务 ID" })),
-  subject: Type.Optional(Type.String({ description: "任务标题；create 必填" })),
-  description: Type.Optional(Type.String({ description: "任务背景和范围" })),
-  activeForm: Type.Optional(Type.String({ description: "进行中时显示的动作短语" })),
-  acceptanceCriteria: Type.Optional(Type.Array(Type.String(), { maxItems: 50, description: "可验收的完成条件" })),
-  evidence: Type.Optional(Type.Array(Type.String(), { maxItems: 50, description: "已取得的证据；可替换现有证据" })),
-  addEvidence: Type.Optional(Type.Array(Type.String(), { maxItems: 50, description: "追加证据" })),
+  id: Type.Optional(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: "目标任务 ID" })),
+  subject: Type.Optional(boundedString(MAX_SUBJECT_LENGTH, "任务标题；create 必填")),
+  description: Type.Optional(boundedString(MAX_FIELD_LENGTH, "任务背景和范围")),
+  activeForm: Type.Optional(boundedString(MAX_SUBJECT_LENGTH, "进行中时显示的动作短语")),
+  acceptanceCriteria: Type.Optional(taskTextList("可验收的完成条件")),
+  evidence: Type.Optional(taskTextList("已取得的证据；可替换现有证据")),
+  addEvidence: Type.Optional(taskTextList("追加证据")),
   status: Type.Optional(StringEnum(TASK_STATUSES)),
   priority: Type.Optional(StringEnum(TASK_PRIORITIES)),
-  blockedBy: Type.Optional(Type.Array(Type.Number({ minimum: 1 }), { maxItems: 50, description: "硬依赖任务 ID" })),
-  addBlockedBy: Type.Optional(Type.Array(Type.Number({ minimum: 1 }), { maxItems: 50 })),
-  removeBlockedBy: Type.Optional(Type.Array(Type.Number({ minimum: 1 }), { maxItems: 50 })),
-  blockReason: Type.Optional(Type.String({ description: "阻塞原因；空字符串可清除" })),
-  tags: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
-  addTags: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
-  removeTags: Type.Optional(Type.Array(Type.String(), { maxItems: 50 })),
-  owner: Type.Optional(Type.String({ description: "负责人或执行单元" })),
-  completionNote: Type.Optional(Type.String({ description: "完成结论或验收说明" })),
-  note: Type.Optional(Type.String({ description: "追加一条进度记录" })),
-  query: Type.Optional(Type.String({ description: "list 的标题、描述、标签搜索词" })),
+  blockedBy: Type.Optional(taskIdList("硬依赖任务 ID")),
+  addBlockedBy: Type.Optional(taskIdList()),
+  removeBlockedBy: Type.Optional(taskIdList()),
+  blockReason: Type.Optional(boundedString(MAX_FIELD_LENGTH, "阻塞原因；空字符串可清除")),
+  tags: Type.Optional(taskTextList()),
+  addTags: Type.Optional(taskTextList()),
+  removeTags: Type.Optional(taskTextList()),
+  owner: Type.Optional(boundedString(200, "负责人或执行单元")),
+  completionNote: Type.Optional(boundedString(MAX_FIELD_LENGTH, "完成结论或验收说明")),
+  note: Type.Optional(boundedString(MAX_FIELD_LENGTH, "追加一条进度记录")),
+  query: Type.Optional(boundedString(MAX_FIELD_LENGTH, "list 的标题、描述、标签搜索词")),
   includeCancelled: Type.Optional(Type.Boolean()),
   scope: Type.Optional(StringEnum(["finished", "all"] as const)),
   confirm: Type.Optional(Type.Boolean({ description: "clear 的显式确认" })),
 });
 
 function compact(value: string, max = 76): string {
-  const text = value.replace(/\s+/g, " ").trim();
+  const text = sanitizeTaskText(value);
   return text.length > max ? `${text.slice(0, Math.max(1, max - 3))}...` : text;
 }
 
@@ -70,43 +90,49 @@ function priorityToken(priority: TaskPriority): string {
   return priority === "high" ? "H" : priority === "medium" ? "M" : "L";
 }
 
-function taskStateSummary(state: TaskState): string {
-  const summary = summarizeState(state);
+function taskSummaryText(summary: TaskSummary): string {
   return `${summary.completed}/${summary.total} 已完成 | ${summary.active} 进行中 | ${summary.blocked} 阻塞 | ${summary.ready} 可开始${summary.cancelled ? ` | ${summary.cancelled} 已取消` : ""}`;
 }
 
-function taskLine(task: Task, state: TaskState, detailed = false): string[] {
-  const lines = [`#${task.id} [${statusLabel(task.status)}] [${priorityLabel(task.priority)}] ${task.subject}`];
-  if (detailed && task.activeForm && task.activeForm !== task.subject) lines.push(`  当前动作：${task.activeForm}`);
-  if (detailed && task.description) lines.push(`  说明：${task.description}`);
+function taskStateSummary(state: TaskState, dependencyState: TaskState = state): string {
+  return taskSummaryText(summarizeState(state, dependencyState));
+}
+
+function taskLine(task: Task, state: TaskState, detailed = false, dependencyState: TaskState = state): string[] {
+  const lines = [`#${task.id} [${statusLabel(task.status)}] [${priorityLabel(task.priority)}] ${compact(task.subject, MAX_SUBJECT_LENGTH)}`];
+  if (detailed && task.activeForm && task.activeForm !== task.subject) lines.push(`  当前动作：${compact(task.activeForm, MAX_SUBJECT_LENGTH)}`);
+  if (detailed && task.description) lines.push(`  说明：${compact(task.description, MAX_FIELD_LENGTH)}`);
   if (task.acceptanceCriteria.length > 0) {
     lines.push(`  完成条件：${task.acceptanceCriteria.length} 项，证据 ${task.evidence.length} 项`);
-    if (detailed) task.acceptanceCriteria.forEach((item, index) => lines.push(`    ${index + 1}. ${item}`));
+    if (detailed) task.acceptanceCriteria.forEach((item, index) => lines.push(`    ${index + 1}. ${compact(item, MAX_FIELD_LENGTH)}`));
   }
-  if (task.evidence.length > 0 && detailed) task.evidence.forEach((item) => lines.push(`  证据：${item}`));
+  if (task.evidence.length > 0 && detailed) task.evidence.forEach((item) => lines.push(`  证据：${compact(item, MAX_FIELD_LENGTH)}`));
   if (task.blockedBy.length > 0) lines.push(`  依赖：${task.blockedBy.map((id) => `#${id}`).join(", ")}`);
-  if (task.status === "blocked" && task.blockReason) lines.push(`  阻塞原因：${task.blockReason}`);
-  if (task.owner) lines.push(`  负责人：${task.owner}`);
-  if (task.tags.length > 0) lines.push(`  标签：${task.tags.join(", ")}`);
-  if (task.completionNote && task.status === "completed") lines.push(`  完成说明：${task.completionNote}`);
+  if (task.status === "blocked" && task.blockReason) lines.push(`  阻塞原因：${compact(task.blockReason, MAX_FIELD_LENGTH)}`);
+  if (task.owner) lines.push(`  负责人：${compact(task.owner, 200)}`);
+  if (task.tags.length > 0) lines.push(`  标签：${task.tags.map((tag) => compact(tag, 120)).join(", ")}`);
+  if (task.completionNote && task.status === "completed") lines.push(`  完成说明：${compact(task.completionNote, MAX_FIELD_LENGTH)}`);
   if (detailed && task.notes.length > 0) {
-    for (const note of task.notes.slice(-3)) lines.push(`  记录${note.at ? ` [${note.at}]` : ""}：${note.text}`);
+    for (const note of task.notes.slice(-3)) lines.push(`  记录${note.at ? ` [${compact(note.at, 40)}]` : ""}：${compact(note.text, MAX_FIELD_LENGTH)}`);
   }
-  if (!detailed && task.status === "pending" && !isTaskReady(state, task)) lines.push("  等待依赖完成");
+  if (!detailed && task.status === "pending" && !isTaskReady(dependencyState, task)) lines.push("  等待依赖完成");
   return lines;
 }
 
-function formatForModel(result: Pick<ApplyResultLike, "action" | "message" | "visibleTasks" | "selectedTask" | "state">): string {
-  const lines = [result.message, taskStateSummary(result.state)];
+function formatForModel(result: Pick<ApplyResultLike, "action" | "message" | "visibleTasks" | "selectedTask" | "state" | "dependencyState">): string {
+  const lines = [result.message, taskStateSummary(result.state, result.dependencyState)];
   const tasks = result.action === "get" && result.selectedTask ? [result.selectedTask] : result.visibleTasks;
   if (tasks.length === 0) {
     lines.push("（没有符合条件的任务）");
   } else {
     const display = result.action === "list" ? tasks.slice(0, 50) : tasks.slice(0, 5);
-    for (const task of display) lines.push(...taskLine(task, result.state, result.action === "get"));
+    for (const task of display) lines.push(...taskLine(task, result.state, result.action === "get", result.dependencyState));
     if (display.length < tasks.length) lines.push(`... 还有 ${tasks.length - display.length} 个任务，请使用 list 的 query/status 分批查看`);
   }
-  return lines.join("\n");
+  const text = lines.join("\n");
+  return text.length <= MAX_MODEL_OUTPUT_LENGTH
+    ? text
+    : `${text.slice(0, MAX_MODEL_OUTPUT_LENGTH - 80)}\n... 输出已截断；请使用 task_list 的 get 或 list + query 分批查看。`;
 }
 
 interface ApplyResultLike {
@@ -115,6 +141,7 @@ interface ApplyResultLike {
   visibleTasks: Task[];
   selectedTask?: Task;
   state: TaskState;
+  dependencyState: TaskState;
 }
 
 interface CompactWidgetTask {
@@ -157,7 +184,6 @@ function preferredWidgetTask(current: Task | undefined, candidate: Task): Task {
 
 function compactWidgetModel(state: TaskState): CompactWidgetModel {
   const summary = summarizeState(state);
-  const statusById = new Map(state.tasks.map((task) => [task.id, task.status]));
   let active: Task | undefined;
   let blocked: Task | undefined;
   let ready: Task | undefined;
@@ -166,13 +192,7 @@ function compactWidgetModel(state: TaskState): CompactWidgetModel {
   for (const task of state.tasks) {
     if (task.status === "in_progress") active = preferredWidgetTask(active, task);
     if (task.status === "blocked") blocked = preferredWidgetTask(blocked, task);
-    if (task.status === "pending") {
-      const dependenciesResolved = task.blockedBy.every((id) => {
-        const status = statusById.get(id);
-        return status === undefined || status === "completed" || status === "cancelled";
-      });
-      if (dependenciesResolved) ready = preferredWidgetTask(ready, task);
-    }
+    if (task.status === "pending" && isTaskReady(state, task)) ready = preferredWidgetTask(ready, task);
     if (
       task.status === "completed" &&
       (!recent || task.updatedAt > recent.updatedAt || (task.updatedAt === recent.updatedAt && task.id > recent.id))
@@ -266,26 +286,6 @@ class CompactTaskWidget {
   }
 }
 
-function hasPersistedState(value: unknown): value is { state?: unknown; tasks?: unknown[] } {
-  return typeof value === "object" && value !== null && ("state" in value || "tasks" in value);
-}
-
-function restoreState(ctx: ExtensionContext): TaskState {
-  let restored: TaskState | undefined;
-  for (const entry of ctx.sessionManager.getBranch()) {
-    if (entry.type === "custom" && entry.customType === "task-list-state" && hasPersistedState(entry.data)) {
-      restored = normalizeState(entry.data.state ?? entry.data);
-      continue;
-    }
-    if (entry.type !== "message") continue;
-    const message = entry.message;
-    if (message.role !== "toolResult" || message.toolName !== TOOL_NAME) continue;
-    const details = message.details as Partial<TaskListDetails> | undefined;
-    if (details?.state) restored = normalizeState(details.state);
-  }
-  return restored ?? normalizeState(undefined);
-}
-
 function statusColor(theme: Theme, status: TaskStatus, text: string): string {
   switch (status) {
     case "completed":
@@ -302,80 +302,190 @@ function statusColor(theme: Theme, status: TaskStatus, text: string): string {
 }
 
 class TaskListComponent {
-  private readonly state: TaskState;
-  private readonly theme: Theme;
-  private readonly title: string;
   private cachedWidth?: number;
+  private cachedOffset?: number;
+  private cachedViewport?: number;
   private cachedLines?: string[];
-  private readonly onClose: () => void;
+  private contentWidth?: number;
+  private contentLinesCache?: string[];
+  private scrollTop = 0;
 
-  constructor(state: TaskState, theme: Theme, title: string, onClose: () => void) {
-    this.state = state;
-    this.theme = theme;
-    this.title = title;
-    this.onClose = onClose;
+  constructor(
+    private readonly state: TaskState,
+    private readonly theme: Theme,
+    private readonly title: string,
+    private readonly tui: TUI,
+    private readonly onClose: () => void,
+    private readonly dependencyState: TaskState = state,
+  ) {}
+
+  private viewportRows(): number {
+    const rows = this.tui.terminal?.rows;
+    if (typeof rows !== "number" || rows <= 0) return 24;
+    // Keep the detail view inside a stable modal viewport on both TUI modes.
+    return Math.max(6, Math.min(rows - 2, Math.floor(rows * 0.86)));
   }
 
-  handleInput(data: string): void {
-    if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) this.onClose();
+  private pageSize(): number {
+    // Reserve one line for the footer while remaining usable on tiny terminals.
+    return Math.max(1, this.viewportRows() - 1);
   }
 
-  render(width: number): string[] {
-    if (this.cachedWidth === width && this.cachedLines) return this.cachedLines;
+  private buildContent(width: number): string[] {
+    const safeWidth = Math.max(1, width);
+    if (this.contentWidth === safeWidth && this.contentLinesCache) return this.contentLinesCache;
+
     const lines: string[] = [];
-    const summary = summarizeState(this.state);
-    const header = this.theme.fg("borderMuted", "─".repeat(3)) + this.theme.fg("accent", ` ${this.title} `) + this.theme.fg("borderMuted", "─".repeat(Math.max(0, width - 12)));
-    lines.push("");
-    lines.push(truncateToWidth(header, width));
-    lines.push(truncateToWidth(`  ${taskStateSummary(this.state)}`, width));
-    lines.push("");
+    let truncated = false;
+    const add = (line: string): boolean => {
+      if (lines.length >= MAX_DETAIL_LINES - 1) {
+        truncated = true;
+        return false;
+      }
+      lines.push(truncateToWidth(line, safeWidth));
+      return true;
+    };
+    const display = (value: string, max = MAX_FIELD_LENGTH): string => compact(value, max);
+    const header =
+      this.theme.fg("borderMuted", "─".repeat(3)) +
+      this.theme.fg("accent", ` ${display(this.title, 120)} `) +
+      this.theme.fg("borderMuted", "─".repeat(Math.max(0, safeWidth - 12)));
+
+    add("");
+    add(header);
+    add(`  ${taskStateSummary(this.state, this.dependencyState)}`);
+    add("");
 
     const tasks = filterTasks(this.state, { includeCancelled: true });
     if (tasks.length === 0) {
-      lines.push(truncateToWidth(`  ${this.theme.fg("dim", "当前没有任务")}`, width));
+      add(`  ${this.theme.fg("dim", "当前没有任务")}`);
     } else {
       for (const task of tasks) {
         const mark = task.status === "completed" ? "[x]" : task.status === "cancelled" ? "[-]" : task.status === "blocked" ? "[!]" : task.status === "in_progress" ? "[>]" : "[ ]";
-        lines.push(truncateToWidth(`  ${statusColor(this.theme, task.status, mark)} ${this.theme.fg("accent", `#${task.id}`)} [${priorityLabel(task.priority)}] ${task.subject}`, width));
-        if (task.status === "in_progress") lines.push(truncateToWidth(`      动作：${task.activeForm}`, width));
-        if (task.description) lines.push(truncateToWidth(`      说明：${task.description}`, width));
+        if (!add(`  ${statusColor(this.theme, task.status, mark)} ${this.theme.fg("accent", `#${task.id}`)} [${priorityLabel(task.priority)}] ${display(task.subject, MAX_SUBJECT_LENGTH)}`)) break;
+        if (task.status === "in_progress" && !add(`      动作：${display(task.activeForm, MAX_SUBJECT_LENGTH)}`)) break;
+        if (task.description && !add(`      说明：${display(task.description)}`)) break;
         if (task.acceptanceCriteria.length > 0) {
-          lines.push(truncateToWidth(`      完成条件：${task.evidence.length}/${task.acceptanceCriteria.length} 项已有证据`, width));
+          if (!add(`      完成条件：${task.evidence.length}/${task.acceptanceCriteria.length} 项已有证据`)) break;
+          let stopped = false;
           for (const criterion of task.acceptanceCriteria) {
-            lines.push(truncateToWidth(`        - ${criterion}`, width));
+            if (!add(`        - ${display(criterion)}`)) {
+              stopped = true;
+              break;
+            }
           }
+          if (stopped) break;
         }
         if (task.evidence.length > 0) {
-          lines.push(truncateToWidth("      证据：", width));
-          for (const evidence of task.evidence) lines.push(truncateToWidth(`        - ${evidence}`, width));
+          if (!add("      证据：")) break;
+          let stopped = false;
+          for (const evidence of task.evidence) {
+            if (!add(`        - ${display(evidence)}`)) {
+              stopped = true;
+              break;
+            }
+          }
+          if (stopped) break;
         }
-        if (task.blockedBy.length > 0) lines.push(truncateToWidth(`      依赖：${task.blockedBy.map((id) => `#${id}`).join(", ")}`, width));
-        if (task.status === "blocked" && task.blockReason) lines.push(truncateToWidth(`      阻塞：${task.blockReason}`, width));
-        if (task.notes.length > 0) lines.push(truncateToWidth(`      最近记录：${task.notes.at(-1)?.text ?? ""}`, width));
-        if (task.status === "completed" && task.completionNote) lines.push(truncateToWidth(`      完成说明：${task.completionNote}`, width));
+        if (task.blockedBy.length > 0 && !add(`      依赖：${task.blockedBy.map((id) => `#${id}`).join(", ")}`)) break;
+        if (task.status === "blocked" && task.blockReason && !add(`      阻塞：${display(task.blockReason)}`)) break;
+        if (task.notes.length > 0 && !add(`      最近记录：${display(task.notes.at(-1)?.text ?? "")}`)) break;
+        if (task.status === "completed" && task.completionNote && !add(`      完成说明：${display(task.completionNote)}`)) break;
       }
     }
-    lines.push("");
-    lines.push(truncateToWidth(`  ${this.theme.fg("dim", "按 Escape 关闭")}`, width));
-    lines.push("");
-    this.cachedWidth = width;
-    this.cachedLines = lines;
+
+    if (truncated) {
+      add("  … 详情过长，已截断；请使用 /tasks #ID 或 task_list get 分批查看");
+    }
+    this.contentWidth = safeWidth;
+    this.contentLinesCache = lines;
     return lines;
   }
 
+  private maxScroll(width: number): number {
+    return Math.max(0, this.buildContent(width).length - this.pageSize());
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
+      this.onClose();
+      return;
+    }
+
+    const width = this.cachedWidth ?? this.tui.terminal?.columns ?? 80;
+    const page = Math.max(1, this.pageSize() - 1);
+    const maximum = this.maxScroll(width);
+    let next = this.scrollTop;
+    if (matchesKey(data, "up") || data === "k") next -= 1;
+    else if (matchesKey(data, "down") || data === "j") next += 1;
+    else if (matchesKey(data, "pageUp") || data === "u") next -= page;
+    else if (matchesKey(data, "pageDown") || data === "d" || data === " ") next += page;
+    else if (matchesKey(data, "home") || data === "g") next = 0;
+    else if (matchesKey(data, "end") || data === "G") next = maximum;
+    else return;
+
+    next = Math.max(0, Math.min(maximum, next));
+    if (next === this.scrollTop) return;
+    this.scrollTop = next;
+    this.invalidate();
+    this.tui.requestRender();
+  }
+
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+    // Pi's regular TUI intentionally leaves the wheel to the terminal scrollback.
+    // Only consume normalized wheel events in fullscreen, where the host enables mouse reporting.
+    if (this.tui.mode !== "fullscreen" || event.type !== "wheel" || !event.wheelDelta) return undefined;
+
+    const width = Math.max(1, event.width || this.cachedWidth || this.tui.terminal?.columns || 80);
+    const maximum = this.maxScroll(width);
+    const next = Math.max(0, Math.min(maximum, this.scrollTop + event.wheelDelta));
+    if (next === this.scrollTop) return { handled: true, focus: true, render: false };
+
+    this.scrollTop = next;
+    this.invalidate();
+    return { handled: true, focus: true, render: true };
+  }
+
+  render(width: number): string[] {
+    const safeWidth = Math.max(1, width);
+    const content = this.buildContent(safeWidth);
+    const viewport = this.pageSize();
+    const maximum = Math.max(0, content.length - viewport);
+    this.scrollTop = Math.max(0, Math.min(maximum, this.scrollTop));
+
+    if (this.cachedWidth === safeWidth && this.cachedViewport === viewport && this.cachedOffset === this.scrollTop && this.cachedLines) return this.cachedLines;
+
+    const visible = content.slice(this.scrollTop, this.scrollTop + viewport);
+    while (visible.length < viewport) visible.push("");
+    const position = content.length === 0 ? "0/0" : `${this.scrollTop + 1}-${Math.min(content.length, this.scrollTop + viewport)}/${content.length}`;
+    const navigation = this.tui.mode === "fullscreen"
+      ? "滚轮/↑↓/jk 滚动 · u/d/Space 翻页 · Home/End/g/G 跳转 · Esc 关闭"
+      : "↑↓/jk 滚动 · u/d/Space 翻页 · Home/End/g/G 跳转 · Esc 关闭（fullscreen 支持滚轮）";
+    visible.push(truncateToWidth(`  ${this.theme.fg("dim", `位置 ${position} · ${navigation}`)}`, safeWidth));
+
+    this.cachedWidth = safeWidth;
+    this.cachedOffset = this.scrollTop;
+    this.cachedViewport = viewport;
+    this.cachedLines = visible;
+    return visible;
+  }
+
   invalidate(): void {
     this.cachedWidth = undefined;
+    this.cachedOffset = undefined;
+    this.cachedViewport = undefined;
     this.cachedLines = undefined;
   }
 }
 
-function commandFilter(state: TaskState, args: string): { state: TaskState; title: string } {
+function commandFilter(state: TaskState, args: string): { state: TaskState; title: string; dependencyState: TaskState } {
+  const dependencyState = cloneState(state);
   const filter = args.trim();
-  if (!filter || filter.toLowerCase() === "all") return { state: cloneState(state), title: "Tasks" };
+  if (!filter || filter.toLowerCase() === "all") return { state: cloneState(state), title: "Tasks", dependencyState };
   const lower = filter.toLowerCase();
   if (/^#?\d+$/.test(lower)) {
     const id = Number(lower.replace(/^#/, ""));
-    return { state: { ...cloneState(state), tasks: state.tasks.filter((task) => task.id === id) }, title: `Task #${id}` };
+    return { state: { ...cloneState(state), tasks: state.tasks.filter((task) => task.id === id) }, title: `Task #${id}`, dependencyState };
   }
   const statusMap: Record<string, TaskStatus> = {
     active: "in_progress",
@@ -387,9 +497,9 @@ function commandFilter(state: TaskState, args: string): { state: TaskState; titl
     cancelled: "cancelled",
   };
   if (statusMap[lower]) {
-    return { state: { ...cloneState(state), tasks: filterTasks(state, { status: statusMap[lower], includeCancelled: true }) }, title: `Tasks: ${statusLabel(statusMap[lower])}` };
+    return { state: { ...cloneState(state), tasks: filterTasks(state, { status: statusMap[lower], includeCancelled: true }) }, title: `Tasks: ${statusLabel(statusMap[lower])}`, dependencyState };
   }
-  return { state: { ...cloneState(state), tasks: filterTasks(state, { query: filter, includeCancelled: true }) }, title: `Tasks: ${filter}` };
+  return { state: { ...cloneState(state), tasks: filterTasks(state, { query: filter, includeCancelled: true }) }, title: `Tasks: ${filter}`, dependencyState };
 }
 
 export default function taskListExtension(pi: ExtensionAPI) {
@@ -397,6 +507,7 @@ export default function taskListExtension(pi: ExtensionAPI) {
   let compactWidget: CompactTaskWidget | undefined;
   let rpcWidgetFingerprint: string | undefined;
   let lastStatusText: string | undefined;
+  let lastCheckpointRevision = -1;
 
   const refreshUi = (ctx: ExtensionContext): void => {
     if (!ctx.hasUI) return;
@@ -413,7 +524,9 @@ export default function taskListExtension(pi: ExtensionAPI) {
         });
       }
     } else if (rpcWidgetFingerprint !== fingerprint) {
-      ctx.ui.setWidget(WIDGET_KEY, compactWidgetLines(model, ctx.ui.theme, 96));
+      // RPC clients receive plain text; do not leak interactive ANSI styling into JSON events.
+      const lines = compactWidgetLines(model, ctx.ui.theme, RPC_WIDGET_WIDTH).map((line) => sanitizeTaskText(line));
+      ctx.ui.setWidget(WIDGET_KEY, lines);
       rpcWidgetFingerprint = fingerprint;
     }
 
@@ -435,15 +548,28 @@ export default function taskListExtension(pi: ExtensionAPI) {
   };
 
   const restoreAndRefresh = (ctx: ExtensionContext) => {
-    state = restoreState(ctx);
+    state = restoreTaskListState(ctx.sessionManager.getBranch());
     refreshUi(ctx);
   };
 
   pi.on("session_start", async (_event, ctx) => restoreAndRefresh(ctx));
   pi.on("session_tree", async (_event, ctx) => restoreAndRefresh(ctx));
-  pi.on("session_shutdown", async (_event, ctx) => clearUi(ctx));
-  pi.on("session_compact", async () => {
-    pi.appendEntry("task-list-state", { state: cloneState(state) });
+  // A session switch can be cancelled by another extension; keep the current state until shutdown is certain.
+  pi.on("session_shutdown", async (_event, ctx) => {
+    state = normalizeState(undefined);
+    clearUi(ctx);
+  });
+  pi.on("session_compact", async (_event, ctx) => {
+    if (typeof pi.appendEntry !== "function" || state.revision === lastCheckpointRevision) return;
+    try {
+      pi.appendEntry(TASK_LIST_STATE_ENTRY_TYPE, { version: 1, state: cloneState(state) });
+      lastCheckpointRevision = state.revision;
+    } catch (error) {
+      if (ctx.hasUI) {
+        const reason = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`任务 checkpoint 未写入：${reason}`, "warning");
+      }
+    }
   });
 
   pi.registerTool({
@@ -464,24 +590,35 @@ export default function taskListExtension(pi: ExtensionAPI) {
 
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       if (signal?.aborted) throw new Error("Task list operation cancelled");
-      const result = applyTaskAction(state, params as TaskCommand);
+      const command = params as TaskCommand;
+      const result = applyTaskAction(state, command);
       state = result.state;
-      if (result.mutated) {
-        pi.appendEntry("task-list-state", { state: cloneState(state) });
-      }
+      // Tool results retain a compact replayable mutation. The complete snapshot is
+      // checkpointed only after compaction, preventing a full state copy per turn.
+      const operation = result.mutated ? createTaskOperation(command, state.updatedAt) : undefined;
       refreshUi(ctx);
 
+      const copyTask = (task: Task): Task => ({
+        ...task,
+        acceptanceCriteria: [...task.acceptanceCriteria],
+        evidence: [...task.evidence],
+        blockedBy: [...task.blockedBy],
+        tags: [...task.tags],
+        notes: task.notes.map((note) => ({ ...note })),
+      });
       const details: TaskListDetails = {
+        schemaVersion: 2,
         action: result.action,
-        state: cloneState(state),
+        operation,
+        summary: summarizeState(state),
         changedIds: [...result.changedIds],
-        visibleTasks: result.visibleTasks.map((task) => ({ ...task, acceptanceCriteria: [...task.acceptanceCriteria], evidence: [...task.evidence], blockedBy: [...task.blockedBy], tags: [...task.tags], notes: task.notes.map((note) => ({ ...note })) })),
-        selectedTask: result.selectedTask,
+        visibleTasks: result.visibleTasks.map(copyTask),
+        selectedTask: result.selectedTask ? copyTask(result.selectedTask) : undefined,
         message: result.message,
       };
 
       return {
-        content: [{ type: "text", text: formatForModel(result) }],
+        content: [{ type: "text", text: formatForModel({ ...result, dependencyState: state }) }],
         details,
       };
     },
@@ -499,13 +636,18 @@ export default function taskListExtension(pi: ExtensionAPI) {
       const fallback = result.content.find((part) => part.type === "text");
       if (!details) return new Text(theme.fg(context.isError ? "error" : "muted", fallback?.type === "text" ? fallback.text : ""), 0, 0);
 
-      const lines = [theme.fg(context.isError ? "error" : "success", details.message), theme.fg("muted", taskStateSummary(details.state))];
+      const legacySummary = isPersistedTaskState(details.state) ? summarizeState(normalizeState(details.state)) : undefined;
+      const summary = details.summary ?? legacySummary;
+      const lines = [
+        theme.fg(context.isError ? "error" : "success", details.message),
+        theme.fg("muted", summary ? taskSummaryText(summary) : "任务状态摘要不可用"),
+      ];
       const tasks = details.action === "get" && details.selectedTask ? [details.selectedTask] : details.visibleTasks;
       const display = expanded ? tasks.slice(0, 20) : tasks.slice(0, 4);
       for (const task of display) {
         const mark = task.status === "completed" ? "✓" : task.status === "blocked" ? "!" : task.status === "in_progress" ? ">" : task.status === "cancelled" ? "-" : "○";
-        lines.push(`${statusColor(theme, task.status, mark)} ${theme.fg("accent", `#${task.id}`)} ${theme.fg(task.status === "completed" ? "dim" : "text", task.subject)} ${theme.fg("dim", `[${priorityLabel(task.priority)}]`)}`);
-        if (expanded && task.status === "blocked" && task.blockReason) lines.push(`  ${theme.fg("error", task.blockReason)}`);
+        lines.push(`${statusColor(theme, task.status, mark)} ${theme.fg("accent", `#${task.id}`)} ${theme.fg(task.status === "completed" ? "dim" : "text", compact(task.subject, MAX_SUBJECT_LENGTH))} ${theme.fg("dim", `[${priorityLabel(task.priority)}]`)}`);
+        if (expanded && task.status === "blocked" && task.blockReason) lines.push(`  ${theme.fg("error", compact(task.blockReason))}`);
         if (expanded && task.acceptanceCriteria.length > 0) lines.push(`  ${theme.fg("muted", `完成条件证据：${task.evidence.length}/${task.acceptanceCriteria.length}`)}`);
       }
       if (display.length < tasks.length) lines.push(theme.fg("dim", `... 还有 ${tasks.length - display.length} 个任务`));
@@ -518,10 +660,28 @@ export default function taskListExtension(pi: ExtensionAPI) {
     handler: async (args, ctx) => {
       const selected = commandFilter(state, args);
       if (ctx.mode !== "tui") {
-        ctx.ui.notify(formatForModel({ action: "list", message: selected.title, visibleTasks: selected.state.tasks, state: selected.state }), "info");
+        ctx.ui.notify(
+          formatForModel({ action: "list", message: selected.title, visibleTasks: selected.state.tasks, state: selected.state, dependencyState: selected.dependencyState }),
+          "info",
+        );
         return;
       }
-      await ctx.ui.custom<void>((_tui, theme, _keybindings, done) => new TaskListComponent(selected.state, theme, selected.title, () => done()));
+      await ctx.ui.custom<void>(
+        (tui, theme, _keybindings, done) => new TaskListComponent(selected.state, theme, selected.title, tui, () => done(), selected.dependencyState),
+        {
+          // A modal gives fullscreen mode a bounded hit target for normalized wheel events.
+          // Regular mode still uses keyboard navigation because Pi delegates its wheel to scrollback.
+          overlay: true,
+          overlayOptions: () => {
+            return {
+              width: "92%",
+              maxHeight: "86%",
+              anchor: "center",
+              margin: 1,
+            };
+          },
+        },
+      );
     },
   });
 }