pi-dag-workflow 0.0.0-stage → 0.7.0

package/src/todos/domain/owner.ts

@@ -0,0 +1,109 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { truncateToWidth } from '@earendil-works/pi-tui';
+import { chinese, type Translator } from '../../shared/i18n.ts';
+import { clean, notify } from '../../shared/terminal.ts';
+import type { AgentView } from '../../shared/agent-view.ts';
+import type { ClearScope, Todo, WorkflowState } from '../../shared/task-types.ts';
+import { latestBoundJobs, taskFilterStatus } from '../../shared/ui/filter.ts';
+import { configPaths } from '../../shared/config.ts';
+import { PresetStore, resetClosure } from './presets.ts';
+import { appendTodoRecord } from '../io/records.ts';
+import { STATE_TYPE, applyTodo, clearTodoRecords, emptyState, newlyReady, restoreState, validateState, validateTodoFields } from "./state.ts";
+import type { TodoParams } from "../../shared/task-schema.ts";
+
+interface Hooks {
+  msg?: Translator;
+  api(): ExtensionAPI;
+  branch(ctx: ExtensionContext): ReturnType<ExtensionContext['sessionManager']['getBranch']>;
+  plan(): { enabled: boolean; tools: string[] };
+  jobs(): readonly AgentView[];
+  paint(ctx: ExtensionContext): void;
+  saved(ctx: ExtensionContext): void;
+  changed(ids?: readonly number[]): void;
+  assertMutation(params: TodoParams): void;
+  afterMutation(params: TodoParams, before: WorkflowState): void;
+  cleanupProtection(tasks: readonly Todo[]): ReadonlySet<number>;
+  cleanupRecords(scope: ClearScope, before: readonly Todo[], after: readonly Todo[]): number;
+}
+
+export function createTodosOwner(hooks: Hooks) {
+  const msg = hooks.msg ?? chinese;
+  let tasks = emptyState(), error: string | undefined, epoch = 0;
+  let legacyPlanFields: { plan?: unknown; planTools?: unknown } = {};
+  const presets = new PresetStore({ path: configPaths().preset });
+  let presetList = presets.list();
+  const state = (): WorkflowState => ({ ...tasks, tasks: error ? [] : tasks.tasks, plan: hooks.plan().enabled, planTools: hooks.plan().tools });
+  function commit(next: WorkflowState, ctx: ExtensionContext, source: 'tool' | 'command' = 'command') {
+    if (error) throw new Error(msg`状态恢复失败，不能修改：${error}`);
+    if (next.tasks === tasks.tasks && next.nextId === tasks.nextId && next.visible === tasks.visible && next.view === tasks.view && next.treeStyle === tasks.treeStyle && next.filter === tasks.filter) return;
+    const changed = next.tasks !== tasks.tasks, before = tasks;
+    appendTodoRecord(hooks.api(), STATE_TYPE, { ...next, plan: legacyPlanFields.plan ?? false, planTools: legacyPlanFields.planTools ?? [] });
+    tasks = { ...next, plan: false, planTools: [] };
+    if (source === 'command' && changed) {
+      const previous = new Map(before.tasks.map(task => [task.id, task]));
+      hooks.changed([...new Set([...next.tasks.filter(task => previous.get(task.id) !== task).map(task => task.id), ...before.tasks.filter(task => !next.tasks.some(item => item.id === task.id)).map(task => task.id)])]);
+    }
+    hooks.paint(ctx); hooks.saved(ctx);
+  }
+  function restore(ctx: ExtensionContext) {
+    epoch++; legacyPlanFields = {};
+    try {
+      const branch = hooks.branch(ctx);
+      const saved = branch.findLast(item => item.type === 'custom' && item.customType === STATE_TYPE);
+      const legacy = saved?.type === 'custom' ? structuredClone(saved.data as WorkflowState) : restoreState(branch, msg);
+      legacyPlanFields = { plan: legacy?.plan, planTools: legacy?.planTools };
+      const value = { ...legacy, plan: false, planTools: [] };
+      validateState(value, msg); tasks = value; error = undefined;
+    } catch (cause) { tasks = emptyState(); error = String(cause); notify(ctx, msg`工作流状态恢复失败：${error}。保留原记录，修改已禁用；/todos clear 可明确重置。`, 'error'); }
+  }
+  async function refreshPresets() { await presets.load(); presetList = presets.list(); }
+  async function restorePresets(ctx: ExtensionContext) {
+    const own = epoch;
+    try { await refreshPresets(); if (own === epoch) hooks.paint(ctx); }
+    catch (cause) { if (own === epoch) notify(ctx, msg`Task 片段（preset）配置无效：${String(cause)}`, 'error'); }
+  }
+  function mutate(params: TodoParams, ctx: ExtensionContext, source: 'tool' | 'command' = 'tool') {
+    if (error && !['list', 'get', 'status', 'presets'].includes(params.action)) throw new Error(msg`状态恢复失败，不能修改：${error}`);
+    if (params.action === 'clear') {
+      validateTodoFields(params, msg);
+      const before = state(), scope = params.scope ?? 'all', latest = latestBoundJobs(hooks.jobs());
+      const outcomes = new Map(before.tasks.filter(task => task.status !== 'deleted').map(task => [task.id, taskFilterStatus(task, latest.get(task.id))]));
+      const result = clearTodoRecords(before, scope, hooks.cleanupProtection(before.tasks), outcomes, msg);
+      commit(result.state, ctx, source);
+      const removed = hooks.cleanupRecords(scope, before.tasks, tasks.tasks);
+      return { ...result, text: `${result.text}\n${msg`已清理 ${removed} 个已结束子 Agent 记录；运行及待交付／核验记录保留`}` };
+    }
+    if (params.action !== 'batch') hooks.assertMutation(params);
+    const before = state(), result = applyTodo(before, params, msg, presets);
+    if (['list', 'get', 'status', 'presets'].includes(params.action)) return result;
+    if (result.operations) for (const operation of result.operations) hooks.assertMutation(operation);
+    const ready = newlyReady(before, result.state); commit(result.state, ctx, source);
+    if (result.operations) {
+      const updates = new Map<number, TodoParams>();
+      for (const operation of result.operations) if (operation.action === 'update' && operation.id !== undefined) { const previous = updates.get(operation.id); updates.set(operation.id, { ...previous, ...operation, addBlockedBy: [...previous?.addBlockedBy ?? [], ...operation.addBlockedBy ?? []], removeBlockedBy: [...previous?.removeBlockedBy ?? [], ...operation.removeBlockedBy ?? []] }); }
+      for (const operation of updates.values()) hooks.afterMutation(operation, before);
+    } else hooks.afterMutation(params, before);
+    if (ready.length) {
+      const names = ready.slice(0, 5).map(task => `#${task.id} ${truncateToWidth(clean(task.subject), 24)}`).join('、');
+      result.text += `\n${msg`前置已完成，可开始：${names}${ready.length > 5 ? msg` 等 ${ready.length} 项` : ''}`}`;
+    }
+    return result;
+  }
+  return {
+    state, commit, restore, mutate, refreshPresets, restorePresets,
+    validateDispatch(before: WorkflowState, id: number) { applyTodo(before, { action: 'update', id, status: 'in_progress' }, msg); },
+    resetTasks(params: TodoParams) { return resetClosure(state().tasks, params.preset ?? '', params.step, params.run); },
+    presets: () => presetList,
+    protected: () => !!error,
+    error: () => error,
+    reset(ctx: ExtensionContext) { error = undefined; commit(emptyState(), ctx); },
+    invalidate() { epoch++; },
+    shutdown() { epoch++; tasks = emptyState(); error = undefined; },
+    previewClear(scope: ClearScope) {
+      const current = state(), latest = latestBoundJobs(hooks.jobs());
+      const outcomes = new Map(current.tasks.filter(task => task.status !== 'deleted').map(task => [task.id, taskFilterStatus(task, latest.get(task.id))]));
+      const preview = clearTodoRecords(current, scope, hooks.cleanupProtection(current.tasks), outcomes, msg);
+      return `${msg`预计清理 ${preview.removedIds.length} 项，保留 ${preview.keptIds.length} 项`}\n${msg('运行、待交付、待核验和依赖必需记录保留；不修改文件、Goal或对话历史。')}`;
+    },
+  };
+}

package/src/todos/domain/presets.ts

@@ -0,0 +1,192 @@
+import { readPresetData } from '../io/records.ts';
+import type { Todo } from "../../shared/task-types.ts";
+
+/**
+ * A reusable task fragment for workflows that repeat. Definitions live in one user-level file;
+ * instantiating one appends real Todos tagged with `metadata.preset`/`run`/`key`, so a fragment
+ * can be reopened later without touching the rest of the list.
+ */
+interface PresetStep {
+  key: string;
+  subject: string;
+  description?: string;
+  activeForm?: string;
+  owner?: string;
+  after?: string[];
+}
+export interface Preset { name: string; description?: string; skill?: string; steps: PresetStep[] }
+interface PresetOptions { path?: string }
+interface ExpandedPreset { name: string; skill?: string; run: number; tasks: Todo[]; ids: Map<string, number> }
+
+const MAX_PRESETS = 64;
+const MAX_STEPS = 32;
+const NAME = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,47}$/;
+const KEY = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected a preset configuration object");
+  return value as Record<string, unknown>;
+}
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): void {
+  const unknown = Object.keys(value).find((key) => !keys.includes(key));
+  if (unknown) throw new Error(`Unknown preset field: ${unknown}`);
+}
+function text(value: unknown, field: string, max: number, pattern?: RegExp): string {
+  if (typeof value !== "string") throw new Error(`Invalid preset ${field}`);
+  const clean = value.replace(/[\r\n\t]/g, " ").replace(/[\p{Cc}\p{Cf}]/gu, "").trim();
+  if (!clean || clean.length > max || (pattern && !pattern.test(clean))) throw new Error(`Invalid preset ${field}`);
+  return clean;
+}
+
+/** In-memory presets, reloaded from disk before every use so edits apply without a restart. */
+export class PresetStore {
+  private presets = new Map<string, Preset>();
+  private readonly options: PresetOptions;
+  constructor(options: PresetOptions = {}) { this.options = options; }
+  private step(value: unknown, seen: Set<string>): PresetStep {
+    const record = object(value);
+    exactKeys(record, ["key", "subject", "description", "activeForm", "owner", "after"]);
+    const key = text(record.key, "step key", 32, KEY);
+    if (seen.has(key)) throw new Error(`Duplicate preset step key: ${key}`);
+    seen.add(key);
+    const after = record.after === undefined ? undefined : (Array.isArray(record.after) ? record.after.map((item) => text(item, "step dependency", 32, KEY)) : (() => { throw new Error("Invalid preset step dependencies"); })());
+    return {
+      key,
+      subject: text(record.subject, "step subject", 200),
+      ...(record.description === undefined ? {} : { description: text(record.description, "step description", 400) }),
+      ...(record.activeForm === undefined ? {} : { activeForm: text(record.activeForm, "step activeForm", 200) }),
+      ...(record.owner === undefined ? {} : { owner: text(record.owner, "step owner", 48, NAME) }),
+      ...(after && after.length ? { after } : {}),
+    };
+  }
+  private preset(value: unknown): Preset {
+    const record = object(value);
+    exactKeys(record, ["name", "description", "skill", "steps"]);
+    const name = text(record.name, "name", 48, NAME);
+    if (!Array.isArray(record.steps) || !record.steps.length || record.steps.length > MAX_STEPS) throw new Error(`Preset ${name} needs 1-${MAX_STEPS} steps`);
+    const seen = new Set<string>();
+    const steps = record.steps.map((item) => this.step(item, seen));
+    for (const step of steps) for (const dependency of step.after ?? []) {
+      if (dependency === step.key) throw new Error(`Preset ${name}: step ${step.key} depends on itself`);
+      if (!seen.has(dependency)) throw new Error(`Preset ${name}: step ${step.key} depends on unknown key ${dependency}`);
+    }
+    // Any order the definition uses must be resolvable: reject cycles before they reach a session.
+    const order = new Map(steps.map((step) => [step.key, step.after ?? []]));
+    const done = new Set<string>();
+    while (done.size < order.size) {
+      const ready = [...order.keys()].filter((key) => !done.has(key) && (order.get(key) ?? []).every((dependency) => done.has(dependency)));
+      if (!ready.length) throw new Error(`Preset ${name} has a dependency cycle`);
+      for (const key of ready) done.add(key);
+    }
+    return {
+      name,
+      ...(record.description === undefined ? {} : { description: text(record.description, "description", 200) }),
+      ...(record.skill === undefined ? {} : { skill: text(record.skill, "skill", 64, NAME) }),
+      steps,
+    };
+  }
+  get(name: string): Preset | undefined { const preset = this.presets.get(name); return preset ? structuredClone(preset) : undefined; }
+  list(): Preset[] { return structuredClone([...this.presets.values()]); }
+  /** Replace the loaded set from the configuration file; a missing file means no presets. */
+  async load(): Promise<void> {
+    if (!this.options.path) { this.presets.clear(); return; }
+    let data: unknown;
+    try { data = await readPresetData(this.options.path); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") { this.presets.clear(); return; } throw error; }
+    const config = object(data);
+    exactKeys(config, ["presets"]);
+    if (!Array.isArray(config.presets) || config.presets.length > MAX_PRESETS) throw new Error(`presets must contain at most ${MAX_PRESETS} presets`);
+    const validated = config.presets.map((item) => this.preset(item));
+    if (new Set(validated.map((preset) => preset.name)).size !== validated.length) throw new Error("Duplicate preset name");
+    this.presets = new Map(validated.map((preset) => [preset.name, preset]));
+  }
+}
+
+const PLACEHOLDER = /\{([a-zA-Z0-9_]+)\}/g;
+
+/** Fill `{name}` placeholders from the caller's variables; a missing value is an error, never a guess. */
+export function fill(text: string, vars: Readonly<Record<string, string>> | undefined, where: string): string {
+  return text.replace(PLACEHOLDER, (_match, name: string) => {
+    const value = vars && Object.hasOwn(vars, name) ? vars[name] : undefined;
+    if (typeof value !== "string") throw new Error(`${where} needs a value for {${name}}`);
+    return value;
+  });
+}
+
+/** The next run number for a preset: instances never reuse ids, so runs only ever grow. */
+function validRun(task: Todo, name: string): number | undefined {
+  const run = task.metadata?.run;
+  return task.metadata?.preset === name && typeof run === "number" && Number.isSafeInteger(run) && run > 0 ? run : undefined;
+}
+export function nextRun(tasks: readonly Todo[], name: string): number {
+  const next = tasks.reduce((max, task) => Math.max(max, validRun(task, name) ?? 0), 0) + 1;
+  if (!Number.isSafeInteger(next)) throw new Error("Preset run counter exhausted");
+  return next;
+}
+
+/** Turn a definition into concrete Todos; dependencies resolve to the ids this run creates. */
+export function expand(preset: Preset, run: number, startId: number, vars?: Readonly<Record<string, string>>): ExpandedPreset {
+  const ids = new Map<string, number>();
+  const created: Todo[] = [];
+  if (!Number.isSafeInteger(startId + preset.steps.length)) throw new Error("Todo id counter exhausted");
+  // Resolve the complete run first: acyclic definitions may refer to a later-listed step.
+  for (const [index, step] of preset.steps.entries()) ids.set(step.key, startId + index);
+  for (const step of preset.steps) {
+    const id = ids.get(step.key)!;
+    created.push({
+      id,
+      subject: fill(step.subject, vars, `preset ${preset.name} step ${step.key}`),
+      status: "pending",
+      blockedBy: (step.after ?? []).map((key) => {
+        const dependency = ids.get(key);
+        if (dependency === undefined) throw new Error(`preset ${preset.name} step ${step.key} depends on unknown key ${key}`);
+        return dependency;
+      }),
+      ...(step.description === undefined ? {} : { description: fill(step.description, vars, `preset ${preset.name} step ${step.key}`) }),
+      ...(step.activeForm === undefined ? {} : { activeForm: step.activeForm }),
+      ...(step.owner === undefined ? {} : { owner: step.owner }),
+      metadata: { preset: preset.name, run, key: step.key, step: created.length + 1 },
+    });
+  }
+  return { name: preset.name, ...(preset.skill === undefined ? {} : { skill: preset.skill }), run, tasks: created, ids };
+}
+
+/** One instantiated fragment on the current list, newest run first. */
+export function instances(tasks: readonly Todo[], name: string, run?: number): number[] {
+  const newest = tasks.reduce((max, task) => Math.max(max, validRun(task, name) ?? 0), 0);
+  if (!newest) return [];
+  const wanted = run ?? newest;
+  return tasks.filter((task) => task.status !== "deleted" && validRun(task, name) === wanted).map((task) => task.id);
+}
+
+/**
+ * Ids a reset has to reopen: the requested step (or the whole instance) plus every task that
+ * depends on it, so a reopened step can never leave a finished successor behind.
+ */
+export function resetClosure(tasks: readonly Todo[], name: string, step?: string, run?: number): number[] {
+  const target = new Set(instances(tasks, name, run));
+  if (!target.size) return [];
+  if (step !== undefined) {
+    const start = tasks.find((task) => target.has(task.id) && task.metadata?.key === step);
+    if (!start) return [];
+    target.clear(); target.add(start.id);
+  }
+  // Both whole-run and single-step resets include live external successors. Deleted rows stay
+  // deleted. A successor adjacency map makes the closure linear even for reverse-listed chains.
+  const successors = new Map<number, number[]>();
+  for (const task of tasks) {
+    if (task.status === "deleted") continue;
+    for (const id of task.blockedBy) {
+      const children = successors.get(id) ?? [];
+      children.push(task.id); successors.set(id, children);
+    }
+  }
+  const queue = [...target];
+  for (let index = 0; index < queue.length; index++) {
+    for (const id of successors.get(queue[index]!) ?? []) {
+      if (target.has(id)) continue;
+      target.add(id); queue.push(id);
+    }
+  }
+  return tasks.filter((task) => target.has(task.id)).map((task) => task.id);
+}

package/src/todos/domain/state.ts

@@ -0,0 +1,287 @@
+import type { TodoParams, TodoBatchOperation } from '../../shared/task-schema.ts';
+import { TODO_FILTERS, type TodoStatus, type ClearScope, type Todo, type WorkflowState } from "../../shared/task-types.ts";
+import { translatedTaskStatusLabels as translatedStatusLabel, WORKFLOW_STATE_TYPE } from '../../shared/state-types.ts';
+import { dagStructure, reuseDagStructure } from "../../shared/dag/cache.ts";
+import { newRedundantEdges } from "../../shared/dag/graph.ts";
+import { chinese, type Translator } from "../../shared/i18n.ts";
+import { expand, nextRun, resetClosure, type Preset, type PresetStore } from "./presets.ts";
+import { planTaskCleanup } from './cleanup.ts';
+
+export const STATE_TYPE = WORKFLOW_STATE_TYPE;
+interface TodoPage { total: number; count: number; limit: number; afterId: number; nextAfterId?: number; next?: TodoParams }
+interface TodoRelations { blocks: number[]; unmetPrerequisites: number[] }
+/** One bounded read-only answer: current mode plus per-status counts. Deleted is listed separately. */
+interface TodoStatusSummary { mode: 'normal' | 'plan'; total: number; counts: Record<Exclude<TodoStatus, 'deleted'>, number>; deleted: number }
+export interface TodoResult { state: WorkflowState; text: string; tasks?: Todo[]; page?: TodoPage; relations?: TodoRelations; removedIds?: number[]; refs?: Record<string, number>; operations?: TodoParams[]; presets?: { name: string; description?: string; steps: number }[]; preset?: Preset; status?: TodoStatusSummary }
+export const emptyState = (): WorkflowState => ({ version: 1, tasks: [], nextId: 1, plan: false, planTools: [], visible: true, view: "list", treeStyle: "paths" });
+
+const fields: Record<string, readonly string[]> = {
+  create: ["subject", "description", "activeForm", "owner", "metadata", "blockedBy", "status"],
+  update: ["id", "subject", "description", "activeForm", "owner", "metadata", "status", "addBlockedBy", "removeBlockedBy"],
+  list: ["status", "includeDeleted", "limit", "afterId", "ready"], get: ["id"], delete: ["id"], clear: ['scope'],
+  apply: ["preset", "vars"], reset: ["preset", "run", "step"], presets: ["preset"], status: [],
+  batch: ['operations'],
+};
+const transitions: Record<TodoStatus, readonly TodoStatus[]> = {
+  pending: ["pending", "in_progress", "completed", "failed", "cancelled", "deleted"],
+  in_progress: ["pending", "in_progress", "completed", "failed", "cancelled", "deleted"],
+  failed: ["pending", "in_progress", "completed", "failed", "cancelled", "deleted"],
+  cancelled: ["pending", "in_progress", "completed", "failed", "cancelled", "deleted"],
+  completed: ["completed", "deleted"], deleted: ["deleted"],
+};
+export function todoRef(todo: Todo): string {
+  return `#${todo.id}${todo.blockedBy.length ? `<-${todo.blockedBy.map((id) => `#${id}`).join(",")}` : ""}`;
+}
+export const statusLabel: Record<TodoStatus, string> = translatedStatusLabel(chinese);
+const textFields = ["subject", "description", "activeForm", "owner"] as const;
+
+function validateTask(task: Todo, msg: Translator = chinese): void {
+  if (!task || typeof task.subject !== "string" || !task.subject.trim() || Array.from(task.subject).length > 60) throw new Error(msg("标题需为 1–60 个字符；详细指示请写 description"));
+  for (const field of textFields) {
+    const value = task[field];
+    if (value !== undefined && (typeof value !== "string" || Buffer.byteLength(value) > 8192)) throw new Error(msg`${field} 需为不超过 8 KiB 的文本`);
+  }
+  if (!Object.hasOwn(transitions, task.status)) throw new Error(msg("未知任务状态"));
+  if (!Array.isArray(task.blockedBy) || task.blockedBy.some((id) => !Number.isSafeInteger(id) || id < 1)) throw new Error(msg("依赖需为有效任务编号"));
+  if (task.metadata !== undefined) {
+    if (!task.metadata || typeof task.metadata !== "object" || Array.isArray(task.metadata) || Buffer.byteLength(JSON.stringify(task.metadata)) > 8192) throw new Error(msg("metadata 需为不超过 8 KiB 的 JSON 对象"));
+  }
+}
+export function validateState(state: WorkflowState, msg: Translator = chinese): void {
+  if (!state || state.version !== 1 || !Array.isArray(state.tasks) || !Number.isSafeInteger(state.nextId) || state.nextId < 1) throw new Error(msg("不支持或损坏的工作流状态"));
+  if (typeof state.plan !== "boolean" || typeof state.visible !== "boolean" || !["list", "dag"].includes(state.view)) throw new Error(msg("损坏的模式／视图状态"));
+  if (state.treeStyle !== undefined && !["paths", "flat"].includes(state.treeStyle)) throw new Error(msg("损坏的任务树样式"));
+  if (state.filter !== undefined && !TODO_FILTERS.includes(state.filter)) throw new Error(msg('损坏的任务过滤器'));
+  if (!Array.isArray(state.planTools) || state.planTools.some((name) => typeof name !== "string" || !/^[\w-]+$/.test(name))) throw new Error(msg("损坏的 Plan 工具列表"));
+  for (const task of state.tasks) {
+    validateTask(task, msg);
+    if (task.id >= state.nextId) throw new Error(msg("任务计数器不能复用已有编号"));
+  }
+  dagStructure(state.tasks);
+}
+
+/** The scope as the user named it; the enum key never reaches a message. */
+const scopeText = (scope: ClearScope, msg: Translator): string => scope === 'completed' ? msg('已完成记录') : scope === 'closed' ? msg('已完成／失败／取消记录') : msg('全部可清理记录');
+
+/** Pure task cleanup. The runtime coordinator supplies job protections/outcomes and prunes jobs. */
+export function clearTodoRecords(state: WorkflowState, scope: ClearScope = 'all', protectedIds: ReadonlySet<number> = new Set(), outcomes?: ReadonlyMap<number, string>, msg: Translator = chinese) {
+  const result = planTaskCleanup(state.tasks, scope, protectedIds, outcomes);
+  if (!result.removedIds.length) return { state, text: msg`没有可清理任务；保留 ${result.keptIds.length} 项（运行／待核验／依赖必需）`, ...result };
+  const next = { ...state, tasks: result.tasks };
+  validateState(next, msg);
+  return { state: next, text: msg`已清理 ${result.removedIds.length} 项（${scopeText(scope, msg)}）；保留 ${result.keptIds.length} 项，编号不复用`, ...result };
+}
+
+/** Read-only summary from the canonical list; it never adds persisted state or renumbers tasks. */
+function todoStatusSummary(state: WorkflowState): TodoStatusSummary {
+  const counts: Record<Exclude<TodoStatus, 'deleted'>, number> = { pending: 0, in_progress: 0, completed: 0, failed: 0, cancelled: 0 };
+  let deleted = 0;
+  for (const task of state.tasks) if (task.status === 'deleted') deleted++; else counts[task.status]++;
+  return { mode: state.plan ? 'plan' : 'normal', total: state.tasks.length - deleted, counts, deleted };
+}
+
+export function validateTodoFields(params: TodoParams, msg: Translator = chinese): void {
+  const allowed = fields[params.action];
+  if (!allowed) throw new Error(msg("未知 Task 操作"));
+  for (const key of Object.keys(params)) if (key !== "action" && !allowed.includes(key)) throw new Error(msg`${params.action} 不接受字段 ${key}`);
+}
+
+/** A definition change must not add an edge that an unfinished path already implies. */
+function guardRedundancy(before: WorkflowState, after: WorkflowState, msg: Translator = chinese): void {
+  if (before.tasks === after.tasks) return;
+  const redundant = newRedundantEdges(before.tasks, after.tasks);
+  if (!redundant.length) return;
+  const shown = redundant.slice(0, 3).map((edge) => `#${edge.to}<-#${edge.from}（已有 #${[edge.from, ...edge.via, edge.to].join(' -> #')}）`).join('；');
+  throw new Error(msg`冗余依赖：${shown}；blockedBy 只放不可缺少的前置产物（排期、同文件、祖先履历不算），本次写入已拒绝`);
+}
+
+/** Atomic pure mutation: errors never modify the current state. */
+export function applyTodo(state: WorkflowState, params: TodoParams, msg: Translator = chinese, presets?: PresetStore): TodoResult {
+  validateTodoFields(params, msg);
+  // Batch judges the whole final definition once: an intermediate triangle is not a write.
+  if (params.action === 'batch') return applyBatch(state, params.operations, msg);
+  const result = applyDefinition(state, params, msg, presets);
+  guardRedundancy(state, result.state, msg);
+  return result;
+}
+
+function applyDefinition(state: WorkflowState, params: TodoParams, msg: Translator = chinese, presets?: PresetStore): TodoResult {
+  if (params.action === 'status') { const status = todoStatusSummary(state); return { state, status, text: JSON.stringify(status, null, 2) }; }
+  if (params.action === 'presets') {
+    // Read-only discovery: compact directory summaries, or one full definition.
+    if (params.preset !== undefined) {
+      const preset = presets?.get(params.preset);
+      if (!preset) throw new Error(msg`未找到片段 ${params.preset}`);
+      return { state, preset, text: JSON.stringify(preset, null, 2) };
+    }
+    const directory = presets?.list().map((item) => ({ name: item.name, ...(item.description ? { description: item.description } : {}), steps: item.steps.length })) ?? [];
+    return { state, presets: directory, text: directory.length ? JSON.stringify(directory, null, 2) : msg('未配置 Task 片段：在 ~/.pi/agent/pi-dag-workflow/pi-dag-workflow-preset.json 里定义') };
+  }
+  if (params.action === "apply" || params.action === "reset") {
+    const name = params.preset ?? "";
+    if (!presets || !name) throw new Error(msg("apply/reset 需要 preset，且需配置片段文件"));
+    if (params.action === "apply") {
+      const preset = presets.get(name);
+      if (!preset) throw new Error(msg`未找到片段 ${name}`);
+      const { tasks: created, ids } = expand(preset, nextRun(state.tasks, name), state.nextId, params.vars);
+      for (const task of created) validateTask(task, msg);
+      const tasks = [...state.tasks, ...created];
+      if (!reuseDagStructure(state.tasks, tasks)) dagStructure(tasks);
+      const map = [...ids].map(([key, id]) => `${key}=#${id}`).join(", ");
+      const hint = preset.skill ? msg`；执行前建议加载 skill：${preset.skill}` : "";
+      return { state: { ...state, tasks, nextId: state.nextId + created.length }, tasks: created, text: msg`已创建片段 ${name} 第 ${nextRun(state.tasks, name)} 轮（${created.length} 项）：${map}${hint}` };
+    }
+    const ids = resetClosure(state.tasks, name, params.step, params.run);
+    if (!ids.length) throw new Error(params.step ? msg`片段 ${name} 中没有步骤 ${params.step}` : msg`没有可重置的片段 ${name}`);
+    const reopened = new Set(ids);
+    const tasks = state.tasks.map((task) => {
+      if (!reopened.has(task.id)) return task;
+      const { activeForm: _dropped, ...rest } = task;
+      return { ...rest, status: "pending" as const };
+    });
+    if (!reuseDagStructure(state.tasks, tasks)) dagStructure(tasks);
+    return { state: { ...state, tasks }, tasks: tasks.filter((task) => reopened.has(task.id)), text: msg`已重置片段 ${name} 的 ${ids.length} 项为待执行：${ids.map((id) => `#${id}`).join(", ")}` };
+  }
+  if (params.action === "list") {
+    const limit = params.limit ?? 50; const afterId = params.afterId ?? 0;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200 || !Number.isSafeInteger(afterId) || afterId < 0) throw new Error(msg('分页参数无效：limit 为 1–200，afterId 为非负整数'));
+    if (params.ready && params.status !== undefined && params.status !== 'pending') throw new Error(msg('ready 只支持 pending 任务'));
+    const statuses = params.ready ? new Map(state.tasks.map((task) => [task.id, task.status])) : undefined;
+    const matched = state.tasks.filter((task) => (params.includeDeleted || task.status !== "deleted") && (!params.status || task.status === params.status) && (!statuses || task.status === 'pending' && task.blockedBy.every((id) => statuses.get(id) === 'completed'))).sort((a, b) => a.id - b.id);
+    const remaining = matched.filter((task) => task.id > afterId);
+    const tasks = remaining.slice(0, limit);
+    const page: TodoPage = { total: matched.length, count: tasks.length, limit, afterId, ...(remaining.length > limit ? { nextAfterId: tasks.at(-1)!.id } : {}) };
+    if (page.nextAfterId !== undefined) page.next = { action: 'list', afterId: page.nextAfterId, limit, ...(params.status ? { status: params.status } : {}), ...(params.includeDeleted ? { includeDeleted: true } : {}), ...(params.ready ? { ready: true } : {}) };
+    const header = msg`本页 ${tasks.length} / 共 ${matched.length} 项`;
+    const text = tasks.length ? `${header}\n${tasks.map((task) => `${todoRef(task)} [${translatedStatusLabel(msg)[task.status]}] ${task.subject}`).join("\n")}` : `${header}\n${msg('暂无任务')}`;
+    return { state, tasks, page, text: page.next ? `${text}\n${msg`继续读取：${JSON.stringify(page.next)}`}` : text };
+  }
+  const current = params.id === undefined ? undefined : state.tasks.find((task) => task.id === params.id);
+  if (["get", "update", "delete"].includes(params.action) && !current) throw new Error(msg`找不到任务 #${params.id ?? "?"}`);
+  if (params.action === "get") {
+    const status = new Map(state.tasks.map((task) => [task.id, task.status]));
+    const relations = { blocks: state.tasks.filter((task) => task.status !== 'deleted' && task.blockedBy.includes(current!.id)).map((task) => task.id).sort((a, b) => a - b), unmetPrerequisites: current!.blockedBy.filter((id) => status.get(id) !== 'completed') };
+    return { state, tasks: [current!], relations, text: JSON.stringify({ ...current, ...relations }, null, 2) };
+  }
+  if (state.plan && params.status && ["in_progress", "completed"].includes(params.status)) throw new Error(msg("Plan 只允许整理任务，不允许开始或完成；先 /plan off"));
+  if (params.action === "clear") return clearTodoRecords(state, params.scope ?? 'all', new Set(), undefined, msg);
+  let task: Todo;
+  if (params.action === "create") {
+    if (!params.subject?.trim()) throw new Error(msg("create 需要 subject"));
+    if (!Number.isSafeInteger(state.nextId + 1)) throw new Error(msg("任务计数器不能复用已有编号"));
+    if (params.status !== undefined && !['pending', 'in_progress'].includes(params.status)) throw new Error(msg('create 的 status 只支持 pending 或 in_progress；核验完成后用 update 设置 completed'));
+    task = { id: state.nextId, subject: params.subject.trim(), status: params.status ?? "pending", blockedBy: [...new Set(params.blockedBy ?? [])] };
+  } else {
+    task = { ...current!, blockedBy: [...current!.blockedBy] };
+    if (task.status === "deleted") throw new Error(msg`任务 #${task.id} 已删除`);
+    if (params.action === "delete") task.status = "deleted";
+    if (params.action === "update") {
+      if (Object.keys(params).every((key) => key === "action" || key === "id")) throw new Error(msg("update 需要至少一个修改字段"));
+      if (params.status) {
+        if (!transitions[task.status].includes(params.status)) throw new Error(msg`不允许 ${task.status} → ${params.status}；返工请新建任务`);
+        task.status = params.status;
+      }
+      const removed = new Set(params.removeBlockedBy ?? []);
+      task.blockedBy = [...new Set([...task.blockedBy, ...params.addBlockedBy ?? []])].filter((id) => !removed.has(id));
+    }
+  }
+  for (const field of textFields) if (params[field] !== undefined) task[field] = params[field]!;
+  if (params.metadata !== undefined) {
+    const merged = new Map(Object.entries(task.metadata ?? {}));
+    for (const [key, value] of Object.entries(params.metadata)) value === null ? merged.delete(key) : merged.set(key, value);
+    if (merged.size) task.metadata = structuredClone(Object.fromEntries(merged)); else delete task.metadata;
+  }
+  validateTask(task, msg);
+  const tasks = params.action === "create" ? [...state.tasks, task] : state.tasks.map((item) => item.id === task.id ? task : item);
+  const next = { ...state, tasks, nextId: state.nextId + (params.action === "create" ? 1 : 0) };
+  if (!reuseDagStructure(state.tasks, tasks)) dagStructure(tasks); // delete safety, dangling dependencies, cycles
+  if (["in_progress", "completed"].includes(task.status)) {
+    const order = dagStructure(tasks).order;
+    const unfinished = task.blockedBy.filter((id) => tasks[order.get(id)!]?.status !== "completed");
+    // A prerequisite that no longer exists can never complete: name the fix instead of listing it as pending.
+    const gone = unfinished.filter((id) => { const value = tasks[order.get(id)!]; return !value || value.status === "deleted"; });
+    if (gone.length) throw new Error(msg`前置任务已删除或不存在：${gone.map((id) => `#${id}`).join(",")}；这条依赖无法满足，用 removeBlockedBy 去掉它，或重建 #${task.id}`);
+    if (unfinished.length) throw new Error(msg`前置未完成：${unfinished.map((id) => `#${id}`).join(",")}；不能开始或完成 #${task.id}`);
+  }
+  if (JSON.stringify(task) === JSON.stringify(current)) return { state, tasks: [current!], text: msg`#${task.id} 无变化` };
+  return { state: next, tasks: [task], text: msg`${params.action === "create" ? msg("已创建") : msg("已更新")} #${task.id}：${task.subject} [${translatedStatusLabel(msg)[task.status]}]` };
+}
+
+/** Resolve a small sequential transaction in memory; the coordinator commits only its final state. */
+function applyBatch(state: WorkflowState, operations: TodoBatchOperation[] | undefined, msg: Translator): TodoResult {
+  if (!Array.isArray(operations) || !operations.length || operations.length > 50) throw new Error(msg('batch 需要 1–50 个定义操作'));
+  let draft = state;
+  const refs = new Map<string, number>(); const resolved: TodoParams[] = []; const touched = new Set<number>();
+  const resolve = (value: number | string): number => {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value > 0) return value;
+    if (typeof value !== 'string' || !/^@[A-Za-z][A-Za-z0-9_-]{0,31}$/.test(value) || !refs.has(value.slice(1))) throw new Error(msg`未知 batch 引用：${String(value)}`);
+    return refs.get(value.slice(1))!;
+  };
+  for (const [index, operation] of operations.entries()) {
+    try {
+      if (!operation || !['create', 'update'].includes(operation.action)) throw new Error(msg('batch 仅支持 create pending 和 update 定义'));
+      const allowed = operation.action === 'create' ? [...fields.create!, 'ref'] : fields.update!.filter((key) => key !== 'status' && key !== 'owner');
+      for (const key of Object.keys(operation)) if (key !== 'action' && !allowed.includes(key)) throw new Error(msg`batch ${operation.action} 不接受字段 ${key}`);
+      if (operation.status !== undefined && operation.status !== 'pending') throw new Error(msg('batch 仅支持 create pending 和 update 定义'));
+      if (operation.ref !== undefined && (!/^[A-Za-z][A-Za-z0-9_-]{0,31}$/.test(operation.ref) || refs.has(operation.ref))) throw new Error(msg`无效或重复 batch ref：${operation.ref}`);
+      const { ref, ...input } = operation;
+      const concrete: TodoParams = { ...input, ...(input.id === undefined ? {} : { id: resolve(input.id) }), ...Object.fromEntries(['blockedBy', 'addBlockedBy', 'removeBlockedBy'].filter((key) => input[key as keyof typeof input] !== undefined).map((key) => {
+        const values = input[key as 'blockedBy' | 'addBlockedBy' | 'removeBlockedBy'];
+        if (!Array.isArray(values)) throw new Error(msg('依赖需为有效任务编号'));
+        return [key, values.map(resolve)];
+      })) } as TodoParams;
+      const result = applyDefinition(draft, concrete, msg);
+      const id = concrete.action === 'create' ? result.tasks![0]!.id : concrete.id!;
+      if (ref !== undefined) refs.set(ref, id);
+      touched.add(id); resolved.push(concrete); draft = result.state;
+    } catch (cause) { throw new Error(msg`batch 第 ${index + 1} 项失败：${cause instanceof Error ? cause.message : String(cause)}`); }
+  }
+  // Reversible definition edits that return to the original values are a real no-op.
+  const before = new Map(state.tasks.map((task) => [task.id, task]));
+  const tasks = draft.tasks.map((task) => touched.has(task.id) && JSON.stringify(task) === JSON.stringify(before.get(task.id)) ? before.get(task.id)! : task);
+  if (draft.nextId === state.nextId && tasks.every((task, index) => task === state.tasks[index])) draft = state;
+  else if (tasks.some((task, index) => task !== draft.tasks[index])) draft = { ...draft, tasks };
+  guardRedundancy(state, draft, msg);
+  return { state: draft, tasks: draft.tasks.filter((task) => touched.has(task.id)), refs: Object.fromEntries(refs), operations: resolved, text: msg`已原子处理 ${operations.length} 个定义操作：${[...touched].map((id) => `#${id}`).join(', ')}${refs.size ? `\n${JSON.stringify(Object.fromEntries(refs))}` : ''}` };
+}
+
+/**
+ * Only walk the active branch; never replay abandoned branches or model summaries.
+ * A list left by rpiv-todo (same tool name, same result shape) is read only when this
+ * plugin has no snapshot of its own on the branch, so an existing session keeps its tasks.
+ */
+/**
+ * Pending tasks that were blocked before the change and are ready after it. Used for the
+ * "prerequisites are done" hint; it never starts anything on its own.
+ */
+export function newlyReady(before: WorkflowState, after: WorkflowState): Todo[] {
+  if (before.tasks === after.tasks) return [];
+  const was = new Map(before.tasks.map((task) => [task.id, task.status]));
+  if (!after.tasks.some((task) => task.status === "completed" && was.get(task.id) !== "completed")) return [];
+  const now = new Map(after.tasks.map((task) => [task.id, task.status]));
+  return after.tasks.filter((task) => task.status === "pending" && task.blockedBy.length > 0 && task.blockedBy.every((id) => now.get(id) === "completed") && !task.blockedBy.every((id) => was.get(id) === "completed"));
+}
+
+export function restoreState(branch: readonly { type: string; customType?: string; data?: unknown; message?: unknown }[], msg: Translator = chinese): WorkflowState {
+  let rpiv: unknown;
+  for (let index = branch.length - 1; index >= 0; index--) {
+    const entry = branch[index]!;
+    if (entry.type === "custom" && entry.customType === STATE_TYPE) {
+      const state = structuredClone(entry.data) as WorkflowState;
+      validateState(state, msg);
+      return state;
+    }
+    if (rpiv === undefined && entry.type === "message" && entry.message && typeof entry.message === "object") {
+      const message = entry.message as { role?: string; toolName?: string; details?: { version?: number; tasks?: unknown; nextId?: unknown } };
+      const details = message.details;
+      if (message.role === "toolResult" && message.toolName === "todo" && details && (details.version === undefined || details.version === 1) && Array.isArray(details.tasks) && Number.isSafeInteger(details.nextId)) rpiv = details;
+    }
+  }
+  if (rpiv) {
+    const data = structuredClone(rpiv) as { tasks: Todo[]; nextId: number };
+    const state = { ...emptyState(), tasks: data.tasks.map((task) => ({ ...task, blockedBy: task.blockedBy ?? [] })), nextId: data.nextId };
+    // Another plugin's data must never break session restore: keep it only when it validates.
+    try { validateState(state, msg); return state; } catch { return emptyState(); }
+  }
+  return emptyState();
+}

package/src/todos/index.ts

@@ -0,0 +1,15 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { connectFeature } from '../workflow/commands/connect.ts';
+import type { createTodosOwner } from './domain/owner.ts';
+import type { registerTodos } from './commands/register.ts';
+
+export default async function (pi: ExtensionAPI): Promise<void> { await connectFeature(pi, 'todos'); }
+
+export async function attachTodos(pi: ExtensionAPI, hooks: Omit<Parameters<typeof createTodosOwner>[0], 'changed'> & Pick<Parameters<typeof registerTodos>[1], 'show' | 'userPrompt' | 'retryStatus' | 'panel' | 'spawn'>) {
+  const [{ createTodosOwner }, { registerCheckpoints }, { registerTodos }] = await Promise.all([import('./domain/owner.ts'), import('./commands/checkpoints.ts'), import('./commands/register.ts')]);
+  let checkpoints: ReturnType<typeof registerCheckpoints>;
+  const owner = createTodosOwner({ ...hooks, changed: ids => checkpoints.changed(ids) });
+  checkpoints = registerCheckpoints(pi, { state: owner.state, jobs: hooks.jobs, protected: owner.protected, branch: hooks.branch });
+  registerTodos(pi, { ...hooks, state: owner.state, mutate: owner.mutate, commit: owner.commit, reset: owner.reset, protected: owner.protected, presets: owner.presets, refreshPresets: owner.refreshPresets, previewClear: owner.previewClear });
+  return { ...owner, checkpoints };
+}

package/src/todos/io/records.ts

@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { readConfigText } from '../../shared/config-file.ts';
+
+export function sendCheckpoint(pi: ExtensionAPI, message: Parameters<ExtensionAPI['sendMessage']>[0]): void { pi.sendMessage(message, { triggerTurn: false }); }
+export function appendTodoRecord(pi: ExtensionAPI, type: string, data: unknown): void { pi.appendEntry(type, data); }
+export async function readPresetData(path: string): Promise<unknown> {
+  return JSON.parse(await readConfigText(path, 65536, 'Preset configuration exceeds 64 KiB')) as unknown;
+}

package/src/ui/index.ts

@@ -0,0 +1,4 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+/** Compatibility for saved Pi path filters. UI no longer activates a feature or controller. */
+export default function (_pi: ExtensionAPI): void {}