@maxiaochao/pi-toolkit 0.10.2 → 0.10.3

package/packages/herdr-subagents/src/history.ts

@@ -8,7 +8,7 @@ import { cleanupRunTab } from "./tab-cleanup.ts";
 import type { OwnerIdentity } from "./ownership.ts";
 import { ownerRecord } from "./ownership.ts";
 import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
-import { applyReport, applyTaskStatus, isActiveStatus, readReport, readRunRecord, readTaskRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type RunStatus, type TaskRecord, type TaskStatus } from "./records.ts";
+import { applyReport, applyTaskStatus, isActiveStatus, projectTaskActivity, readReport, readRunRecord, readTaskRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type RunStatus, type TaskActivity, type TaskRecord, type TaskStatus } from "./records.ts";
 import { continuationSystemPrompt } from "./protocol.ts";
 import { isAbortError } from "./errors.ts";
 import { findRunDirectory } from "./run-locator.ts";
@@ -96,9 +96,10 @@ export async function cleanSubagentRun(cwd: string, runId: string): Promise<bool
 	return true;
 }
 
-export interface ResumeHistoricalTaskOptions { herdr?: HerdrAutomation; signal?: AbortSignal; owner?: OwnerIdentity; onCleanupError?: (message: string) => void; stalledWarningSeconds?: number; onStalled?: (message: string) => void; }
+export interface ResumeHistoricalTaskOptions { herdr?: HerdrAutomation; signal?: AbortSignal; owner?: OwnerIdentity; onCleanupError?: (message: string) => void; stalledWarningSeconds?: number; onStalled?: (message: string) => void; onUpdate?: (result: ResumeHistoricalTaskResult) => void; }
+export interface ResumeHistoricalTaskResult { runId: string; label: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string; activity: TaskActivity[]; }
 
-export async function resumeHistoricalTask(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions = {}): Promise<{ runId: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string }> {
+export async function resumeHistoricalTask(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions = {}): Promise<ResumeHistoricalTaskResult> {
 	const runDirectory = await findRunDirectory(join(cwd, ".pi", "herdr-subagents", "runs"), runId);
 	if (!runDirectory) throw new Error(`Unknown Subagent run '${runId}'.`);
 	const lockDirectory = join(runDirectory, ".resume.lock");
@@ -111,7 +112,7 @@ export async function resumeHistoricalTask(cwd: string, runId: string, taskNumbe
 	finally { await rmdir(lockDirectory); }
 }
 
-async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions): Promise<{ runId: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string }> {
+async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions): Promise<ResumeHistoricalTaskResult> {
 	const herdr = options.herdr ?? new CliHerdrAutomation();
 	const { signal, onCleanupError } = options;
 	const run = (await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId);
@@ -158,6 +159,8 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 				writeJsonAtomic(turnFile, { attempt, prompt, status: "running", sessionFile: historical.sessionFile, tabId: tab.tabId, paneId: tab.paneId, agentName, startedAt: new Date().toISOString() }),
 				writeJsonAtomic(activeRunFile, activeRunRecord),
 			]);
+			const runningActivity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
+			options.onUpdate?.({ runId, label: run.label, status: "running", summary: `${historical.name} is continuing.`, documents: [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile, activity: runningActivity });
 			report = (await promptLiveAgent({ herdr, task: { ...task, id: historical.id, sessionFile: historical.sessionFile }, paneId: tab.paneId, prompt, systemPromptFile: followupPrompt, agentName, signal, stalledWarningMs: options.stalledWarningSeconds ? options.stalledWarningSeconds * 1000 : undefined, onStalled: () => options.onStalled?.(`${historical.name} appears stalled; it is still running.`) })).report;
 			status = applyReport(task, report);
 		} catch (error) {
@@ -182,7 +185,8 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 		if (status !== "blocked") {
 			await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError, failureStatus: "failed" });
 		}
-		return { runId, status, summary: report.summary, documents: report.documents ?? [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile };
+		const activity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
+		return { runId, label: run.label, status, summary: report.summary, documents: report.documents ?? [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile, activity };
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		const completedAt = new Date().toISOString();
@@ -204,6 +208,8 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 			writeJsonAtomic(turnFile, { attempt, prompt, status, summary: report.summary, documents: report.documents, error: message, sessionFile: historical.sessionFile, ...(tab ? { tabId: tab.tabId, paneId: tab.paneId } : {}), completedAt }),
 			writeJsonAtomic(join(run.recordDirectory, "run.json"), runRecord),
 		]);
+		const activity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
+		options.onUpdate?.({ runId, label: run.label, status, summary: report.summary, documents: report.documents, tabId: tab?.tabId ?? "", paneId: tab?.paneId ?? "", sessionFile: historical.sessionFile, activity });
 		if (tab) await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError, failureStatus: "failed" });
 		throw error;
 	}

package/packages/herdr-subagents/src/records.ts

@@ -64,6 +64,8 @@ export interface TaskRecord {
 	systemPrompt?: string;
 	sessionFile?: string;
 	startedAt?: string;
+	activeStartedAt?: string;
+	elapsedMs?: number;
 	updatedAt?: string;
 	completedAt?: string;
 	tabId?: string;
@@ -76,6 +78,38 @@ export interface TaskRecord {
 	error?: string;
 }
 
+export interface TaskActivity {
+	index: number;
+	name: string;
+	status: TaskStatus;
+	agent: string;
+	prompt?: string;
+	paneId?: string;
+	sessionFile?: string;
+	startedAt?: string;
+	activeStartedAt?: string;
+	elapsedMs?: number;
+	completedAt?: string;
+	updatedAt?: string;
+}
+
+export function projectTaskActivity(task: TaskRecord, index = task.order - 1): TaskActivity {
+	return {
+		index,
+		name: String(task.name ?? task.agent ?? `Task ${index + 1}`),
+		status: task.status,
+		agent: String(task.agent ?? "worker"),
+		...(task.prompt ? { prompt: task.prompt } : {}),
+		...(task.paneId ? { paneId: task.paneId } : {}),
+		...(task.sessionFile ? { sessionFile: task.sessionFile } : {}),
+		...(task.startedAt ? { startedAt: task.startedAt } : {}),
+		...(task.activeStartedAt ? { activeStartedAt: task.activeStartedAt } : {}),
+		...(typeof task.elapsedMs === "number" ? { elapsedMs: task.elapsedMs } : {}),
+		...(task.completedAt ? { completedAt: task.completedAt } : {}),
+		...(task.updatedAt ? { updatedAt: task.updatedAt } : {}),
+	};
+}
+
 export interface TurnRecord {
 	attempt: number;
 	prompt?: string;
@@ -184,7 +218,25 @@ export function applyLifecycleStatus<T extends { status: string; question?: stri
 }
 
 export function applyTaskStatus<T extends TaskRecord | TurnRecord>(record: T, status: TaskStatus, options: { question?: string; error?: string; at?: string } = {}): T {
-	return applyLifecycleStatus(record, status, options);
+	const at = options.at ?? new Date().toISOString();
+	if ("order" in record) {
+		if (record.status === "running" && status !== "running") {
+			const activeStarted = Date.parse(record.activeStartedAt ?? record.startedAt ?? "");
+			const ended = Date.parse(at);
+			if (Number.isFinite(activeStarted) && Number.isFinite(ended) && ended >= activeStarted) record.elapsedMs = Math.max(0, Number(record.elapsedMs ?? 0)) + (ended - activeStarted);
+			delete record.activeStartedAt;
+		} else if (status === "running" && record.status !== "running") {
+			if (!(typeof record.elapsedMs === "number" && Number.isFinite(record.elapsedMs))) {
+				const frozenAt = record.status === "blocked" ? record.updatedAt : isSettledRunStatus(record.status) ? record.completedAt : undefined;
+				const started = Date.parse(record.startedAt ?? "");
+				const ended = Date.parse(frozenAt ?? "");
+				if (Number.isFinite(started) && Number.isFinite(ended) && ended >= started) record.elapsedMs = ended - started;
+			}
+			record.startedAt ??= at;
+			record.activeStartedAt = at;
+		}
+	}
+	return applyLifecycleStatus(record, status, { ...options, at });
 }
 
 export async function settleAttemptFailure<T extends TaskRecord | TurnRecord>(

package/packages/herdr-subagents/src/tool.ts

@@ -129,6 +129,7 @@ const actionHandlers = {
 		try {
 			const result = await resumeHistoricalTask(ctx.cwd, params.runId as string, params.task as number, (params.prompt as string).trim(), {
 				herdr: dependencies.herdr, signal, owner: dependencies.owner, stalledWarningSeconds: discovery.settings.stalledWarningSeconds,
+				onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: partial }),
 				onStalled: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "resume", runId: params.runId, stalled: true } }),
 				onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "resume", runId: params.runId, cleanupError: text } }),
 			});

package/packages/herdr-subagents/tests/run-tests.mjs

@@ -2,6 +2,7 @@ import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSyn
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { getEventListeners } from "node:events";
+import { visibleWidth } from "@earendil-works/pi-tui";
 import { discoverPackageAgents, parseAgentMarkdown } from "../src/personas.ts";
 import { loadSubagentConfiguration } from "../src/config.ts";
 import { runHerdrSubagents } from "../src/runner.ts";
@@ -14,10 +15,11 @@ import { cancelQueuedRuns, loadQueuedRuns, persistQueuedRun } from "../src/queue
 import { cancelActiveSubagentRuns, reconcileSubagentRuns } from "../src/reconcile.ts";
 import { continueQueuedRun } from "../src/continue-run.ts";
 import { CliHerdrAutomation } from "../src/herdr.ts";
-import { fleetEditorHasFocus, FleetSelection, fleetLines } from "../src/fleet.ts";
+import { aggregateSessionTokens, fleetEditorHasFocus, FleetSelection, fleetLines, formatFleetDuration, formatFleetTokens } from "../src/fleet.ts";
+import { FleetController, FleetWidget } from "../src/fleet-controller.ts";
 import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "../src/validation.ts";
 import { resultPathForAttempt } from "../src/result-path.ts";
-import { isSettledRunStatus, readTaskRecord } from "../src/records.ts";
+import { applyTaskStatus, isSettledRunStatus, projectTaskActivity, readTaskRecord } from "../src/records.ts";
 import { RunPaneAllocator } from "../src/run-pane-allocator.ts";
 import { aggregateTaskStatus } from "../src/run-status.ts";
 import { isAbortError } from "../src/errors.ts";
@@ -160,7 +162,137 @@ try {
 	check("Fleet Escape exits selection", fleet.handle("\u001b[B", "", 2).consume && fleet.handle("\u001b", "", 2).consume && !fleet.isSelecting());
 	const enhancedFleet = new FleetSelection((data, key) => data === `enhanced-${key}`);
 	check("Fleet delegates enhanced keyboard decoding to Pi key matching", enhancedFleet.handle("enhanced-down", "", 2).consume && enhancedFleet.handle("enhanced-up", "", 2).consume && enhancedFleet.handle("enhanced-enter", "", 2).focusTask === 2);
+	const shrinkingFleet = new FleetSelection();
+	shrinkingFleet.handle("\u001b[B", "", 3);
+	shrinkingFleet.handle("\u001b[A", "", 3);
+	check("Fleet Enter focuses the row displayed after activity shrinks", shrinkingFleet.selectedIndex(2) === 1 && shrinkingFleet.handle("\r", "", 2).focusTask === 2);
 	check("Fleet ignores unknown focus, dialogs, and overlays", fleetEditorHasFocus(undefined, () => false) === false && fleetEditorHasFocus({ kind: "dialog" }, () => false) === false && fleetEditorHasFocus({ kind: "editor" }, () => true) === true);
+	const usage = (input, output, cacheRead, cacheWrite) => ({ input, output, cacheRead, cacheWrite, totalTokens: input + output + cacheRead + cacheWrite, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } });
+	const usageJsonl = [
+		{ type: "message", message: { role: "assistant", usage: usage(1, 2, 3, 4) } },
+		{ type: "usage", usage: usage(5, 6, 7, 8) },
+		{ type: "message", message: { role: "toolResult", usage: usage(9, 10, 11, 12) } },
+		{ type: "compaction", usage: usage(1, 1, 1, 1) },
+		{ type: "branch_summary", usage: usage(2, 2, 2, 2) },
+		{ type: "message", message: { role: "user", usage: usage(99, 99, 99, 99) } },
+	].map(JSON.stringify).join("\n");
+	check("Fleet aggregates every authoritative Pi usage-bearing entry", aggregateSessionTokens(usageJsonl) === 90);
+	check("Fleet ignores malformed and truncated JSONL while preserving valid usage", aggregateSessionTokens(`${usageJsonl.split("\n")[0]}\nnot-json\n{\"type\":\"message\",\"message\":`) === 10);
+	const elapsedStart = "2026-10-08T07:00:00.000Z";
+	check("Fleet elapsed formatting is live and blocked duration freezes", formatFleetDuration({ index: 0, name: "live", agent: "explorer", status: "running", startedAt: elapsedStart }, Date.parse(elapsedStart) + 65_000) === "1m 5s" && formatFleetDuration({ index: 0, name: "blocked", agent: "explorer", status: "blocked", startedAt: elapsedStart, updatedAt: "2026-10-08T07:00:05.000Z" }, Date.parse(elapsedStart) + 99_000) === "5s");
+	const timedTask = { id: "timed", runId: "run", order: 1, name: "timed", agent: "worker", status: "queued" };
+	applyTaskStatus(timedTask, "running", { at: elapsedStart });
+	applyTaskStatus(timedTask, "blocked", { at: "2026-10-08T07:00:05.000Z" });
+	applyTaskStatus(timedTask, "running", { at: "2026-10-08T07:01:00.000Z" });
+	check("Fleet duration accumulates active work without counting blocked wait", formatFleetDuration(projectTaskActivity(timedTask), Date.parse("2026-10-08T07:01:07.000Z")) === "12s");
+	const legacyTimedTask = { id: "legacy", runId: "run", order: 1, name: "legacy", agent: "worker", status: "blocked", startedAt: elapsedStart, updatedAt: "2026-10-08T07:00:05.000Z" };
+	applyTaskStatus(legacyTimedTask, "running", { at: "2026-10-08T07:01:00.000Z" });
+	check("Fleet timing migrates legacy blocked records without losing prior work", formatFleetDuration(projectTaskActivity(legacyTimedTask), Date.parse("2026-10-08T07:01:07.000Z")) === "12s");
+	const recoveredTimedTask = { id: "recovered", runId: "run", order: 1, name: "recovered", agent: "worker", status: "running", startedAt: elapsedStart };
+	applyTaskStatus(recoveredTimedTask, "cancelled", { at: "2026-10-08T07:00:09.000Z" });
+	check("Fleet timing settles legacy recovered-running records", formatFleetDuration(projectTaskActivity(recoveredTimedTask), Date.parse("2026-10-08T08:00:00.000Z")) === "9s");
+	check("Fleet formats true token totals without estimates", formatFleetTokens(999) === "999 tok" && formatFleetTokens(1_250) === "1.3k tok" && formatFleetTokens(12_400) === "12k tok");
+	const metricFleet = new FleetSelection();
+	const metricBatch = { label: "audit", activity: [
+		{ index: 0, name: "inspect auth", agent: "explorer", status: "running", startedAt: elapsedStart, sessionFile: "/tmp/live.jsonl" },
+		{ index: 1, name: "review patch", agent: "reviewer", status: "queued", sessionFile: "/tmp/queued.jsonl" },
+	] };
+	const metricLines = fleetLines(metricBatch, metricFleet, { width: 80, now: Date.parse(elapsedStart) + 65_000, metrics: new Map([[0, { tokens: 1_250 }], [1, { tokens: 999 }]]) });
+	check("Fleet rows show persona task status elapsed and right-aligned true usage", metricLines[1].includes("explorer") && metricLines[1].includes("inspect auth") && metricLines[1].includes("running") && metricLines[1].endsWith("1m 5s  1.3k tok"));
+	const compactLines = fleetLines({ label: "compact", activity: [
+		{ index: 0, name: "API", agent: "explorer", status: "running", startedAt: elapsedStart },
+		{ index: 1, name: "Recovery", agent: "explorer", status: "completed", startedAt: elapsedStart, completedAt: "2026-10-08T07:00:09.000Z" },
+	] }, new FleetSelection(), { width: 160, now: Date.parse(elapsedStart) + 21_000, metrics: new Map([[0, { tokens: 4_800 }], [1, { tokens: 900 }]]) });
+	check("wide Fleet rows align metrics without terminal-width whitespace", visibleWidth(compactLines[1]) < 80 && compactLines[1].indexOf("tok") === compactLines[2].indexOf("tok"));
+	const semanticColors = [];
+	fleetLines({ label: "colors", activity: [
+		{ index: 0, name: "doing", agent: "worker", status: "running" },
+		{ index: 1, name: "done", agent: "worker", status: "completed" },
+	] }, new FleetSelection(), { theme: { fg: (color, text) => { semanticColors.push([color, text]); return text; }, bold: (text) => text } });
+	check("Fleet uses warning yellow for running work and success green for completed work", semanticColors.some(([color, text]) => color === "warning" && text === "●") && semanticColors.some(([color, text]) => color === "success" && text === "●"));
+	check("queued Fleet rows fabricate neither duration nor usage", metricLines[2].includes("reviewer") && metricLines[2].includes("queued") && !metricLines[2].includes("tok") && !metricLines[2].match(/\d+[smh]/));
+	check("Fleet rendering fits narrow terminal widths", [1, 8, 16, 24].every((width) => fleetLines(metricBatch, metricFleet, { width, metrics: new Map([[0, { tokens: 1_250 }]]) }).every((line) => visibleWidth(line) <= width)));
+	let liveTokens = 42;
+	let nextRuntimeId = 1;
+	const runtimeIntervals = new Map();
+	const runtimeTimeouts = new Map();
+	const runtimeWatchers = [];
+	let clearedIntervals = 0;
+	const fleetRuntime = {
+		watchSession(path, onChange, onError) { const entry = { path, onChange, onError, closed: false }; runtimeWatchers.push(entry); return { close() { entry.closed = true; } }; },
+		setInterval(callback) { const id = nextRuntimeId++; runtimeIntervals.set(id, callback); return id; },
+		clearInterval(id) { if (runtimeIntervals.delete(id)) clearedIntervals += 1; },
+		setTimeout(callback) { const id = nextRuntimeId++; runtimeTimeouts.set(id, callback); return id; },
+		clearTimeout(id) { runtimeTimeouts.delete(id); },
+		async readTokens() { return liveTokens; },
+	};
+	let requestedFleetRenders = 0;
+	const liveWidgetBatch = { runId: "live", label: "live", status: "running", activity: [{ index: 0, name: "inspect", agent: "explorer", status: "running", startedAt: elapsedStart, activeStartedAt: elapsedStart, sessionFile: "/tmp/fleet-live/session.jsonl", paneId: "p1" }], prompts: [], tasks: [], documents: [], summary: "", ok: false, requestedConcurrency: 1, effectiveConcurrency: 1, recordDirectory: "/tmp/fleet-live" };
+	const liveWidget = new FleetWidget({ requestRender() { requestedFleetRenders += 1; } }, { fg: (_color, text) => text, bold: (text) => text }, liveWidgetBatch, new FleetSelection(), fleetRuntime);
+	for (const callback of [...runtimeTimeouts.values()]) callback();
+	runtimeTimeouts.clear();
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	check("Fleet widget reads usage on demand and uses one running repaint timer", liveWidget.render(80)[1].includes("42 tok") && runtimeWatchers.length === 1 && runtimeIntervals.size === 1 && requestedFleetRenders > 0);
+	liveTokens = 84;
+	runtimeWatchers[0].onChange();
+	for (const callback of [...runtimeTimeouts.values()]) callback();
+	runtimeTimeouts.clear();
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	check("Fleet widget refreshes token usage from file events", liveWidget.render(80)[1].includes("84 tok"));
+	liveWidget.update({ ...liveWidgetBatch, status: "blocked", activity: [{ ...liveWidgetBatch.activity[0], status: "blocked", updatedAt: "2026-10-08T07:00:05.000Z", activeStartedAt: undefined, elapsedMs: 5_000 }] });
+	check("Fleet widget stops elapsed repainting when work blocks", runtimeIntervals.size === 0 && clearedIntervals === 1);
+	liveWidget.dispose();
+	const watcherClosed = runtimeWatchers.every((watcher) => watcher.closed);
+	liveWidget.update(liveWidgetBatch);
+	check("Fleet widget disposal closes watchers and prevents timer restart", watcherClosed && runtimeIntervals.size === 0 && runtimeTimeouts.size === 0);
+	const makeFleetUi = () => {
+		let component;
+		let factoryInstalls = 0;
+		return {
+			ui: {
+				setWidget(_key, content) { component?.dispose?.(); component = undefined; if (typeof content === "function") { factoryInstalls += 1; component = content({ requestRender() {}, focusedComponent: undefined }, { fg: (_color, text) => text, bold: (text) => text }); } },
+				onTerminalInput() { return () => {}; },
+				getEditorText() { return ""; },
+			},
+			get component() { return component; },
+			get factoryInstalls() { return factoryInstalls; },
+		};
+	};
+	const firstFleetUi = makeFleetUi();
+	const secondFleetUi = makeFleetUi();
+	const fleetController = new FleetController({}, () => false, undefined, fleetRuntime);
+	fleetController.bind(firstFleetUi.ui, true);
+	fleetController.setActive(liveWidgetBatch);
+	const firstUiWidget = firstFleetUi.component;
+	fleetController.bind(secondFleetUi.ui, true);
+	fleetController.sync(liveWidgetBatch);
+	check("Fleet UI rebinding replaces the disposed widget in the new context", firstUiWidget !== secondFleetUi.component && secondFleetUi.factoryInstalls === 1);
+	fleetController.sync({ ...liveWidgetBatch, runId: "foreign", label: "foreign" });
+	check("foreign run updates do not replace the active Fleet owner", fleetController.active?.runId === "live" && secondFleetUi.factoryInstalls === 1);
+	const installsBeforeShutdown = secondFleetUi.factoryInstalls;
+	fleetController.shutdown();
+	fleetController.sync(liveWidgetBatch);
+	check("late updates after shutdown cannot recreate Fleet resources", secondFleetUi.factoryInstalls === installsBeforeShutdown && runtimeIntervals.size === 0 && !fleetController.active);
+	let resolveStaleTokens;
+	const staleTimeouts = new Map();
+	const staleWatchers = [];
+	let staleId = 1;
+	const staleRuntime = {
+		watchSession(path, onChange) { const watcher = { path, onChange, closed: false }; staleWatchers.push(watcher); return { close() { watcher.closed = true; } }; },
+		setInterval() { return staleId++; },
+		clearInterval() {},
+		setTimeout(callback) { const id = staleId++; staleTimeouts.set(id, callback); return id; },
+		clearTimeout(id) { staleTimeouts.delete(id); },
+		readTokens() { return new Promise((resolve) => { resolveStaleTokens = resolve; }); },
+	};
+	const staleWidget = new FleetWidget({ requestRender() {} }, { fg: (_color, text) => text, bold: (text) => text }, liveWidgetBatch, new FleetSelection(), staleRuntime);
+	for (const callback of [...staleTimeouts.values()]) callback();
+	staleTimeouts.clear();
+	staleWidget.update({ ...liveWidgetBatch, runId: "replacement", activity: [{ ...liveWidgetBatch.activity[0], sessionFile: "/tmp/fleet-replacement/session.jsonl" }] });
+	resolveStaleTokens(999);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	check("Fleet ignores stale token reads after session sources change", !staleWidget.render(80)[1].includes("999 tok"));
+	staleWidget.dispose();
 	let unknownStatusRejected = false;
 	try { aggregateTaskStatus(["unknown"]); } catch { unknownStatusRejected = true; }
 	check("task status aggregation rejects unknown states", unknownStatusRejected);
@@ -188,6 +320,7 @@ try {
 	const createRequest = herdr.calls.find(([name]) => name === "createTab")[1];
 	const startRequest = herdr.calls.find(([name]) => name === "startAgent")[1];
 	check("named unfocused tab in parent workspace", createRequest.workspaceId === "w1" && createRequest.cwd === root && createRequest.label === "SA · auth-review" && createRequest.focus === false);
+	check("ordinary execution never steals pane focus", !herdr.calls.some(([name]) => name === "focusPane"));
 	check("child environment points at durable task", createRequest.env.PI_HERDR_SUBAGENTS_CHILD === "1" && createRequest.env.PI_HERDR_SUBAGENTS_TASK_DIR.includes(join(".pi", "herdr-subagents", "runs")));
 	check("persistent isolated child Pi", startRequest.kind === "pi" && startRequest.paneId === "w1:p2" && startRequest.args.includes("--session") && startRequest.args.includes("--no-extensions") && startRequest.args.includes("--extension") && startRequest.args.includes("--no-skills") && startRequest.args.includes("--model") && startRequest.args.includes("fake/model") && startRequest.args.includes("--tools") && startRequest.args.includes("read,grep,subagent_report"));
 	const promptRequest = herdr.calls.find(([name]) => name === "promptAgent")[1];
@@ -309,6 +442,7 @@ try {
 	const counts = activityCounts(activeUpdate);
 	const focusHerdr = fakeHerdr();
 	const runningTask = activeUpdate.activity.find((task) => task.status === "running");
+	check("activity projections expose true persona task timing and session sources", runningTask.agent === "explorer" && runningTask.name === "one" && runningTask.prompt === "one slow" && typeof runningTask.startedAt === "string" && runningTask.sessionFile.endsWith("session.jsonl"));
 	const focused = await focusActiveTask(activeUpdate, runningTask.index + 1, focusHerdr);
 	check("active progress exposes widget counts and exact pane navigation", counts.running > 0 && counts.queued > 0 && focused && focusHerdr.calls.at(-1)[0] === "focusPane" && focusHerdr.calls.at(-1)[1].paneId === runningTask.paneId);
 	const settledFocused = await focusActiveTask({ activity: [{ index: 0, name: "settled", status: "completed", paneId: "w1:p-settled" }] }, 1, focusHerdr);
@@ -548,9 +682,11 @@ try {
 	const stableHistory = history.find((run) => run.id === backgroundId);
 	check("history lists compact project-local runs and tasks", Boolean(stableHistory?.tasks.length) && historyText(history).includes("stable") && !historyText(history).includes("FULL stable"));
 	const historyHerdr = fakeHerdr();
-	const historicalResume = await executeHerdrSubagents({ action: "resume", runId: backgroundId, task: 1, prompt: "follow up" }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: historyHerdr });
+	const historicalUpdates = [];
+	const historicalResume = await executeHerdrSubagents({ action: "resume", runId: backgroundId, task: 1, prompt: "follow up" }, undefined, (update) => historicalUpdates.push(update.details), { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: historyHerdr });
 	const historyStartRequest = historyHerdr.calls.find(([name]) => name === "startAgent")[1];
 	check("historical resume preserves the saved Pi session and persona prompt", !historicalResume.isError && historyHerdr.calls[0][0] === "createTab" && historyStartRequest.args.includes(stableHistory.tasks[0].sessionFile) && historyStartRequest.args.includes(stableHistory.tasks[0].model) && historyStartRequest.args.some((value) => String(value).includes("subagent_report")) && existsSync(join(stableHistory.tasks[0].recordDirectory, "turns", "02.json")) && readFileSync(join(stableHistory.tasks[0].recordDirectory, "followup-system-prompt.md"), "utf8").includes("Investigate the assigned question without modifying files"));
+	check("historical resume streams authoritative Fleet activity", historicalUpdates.some((update) => update.status === "running" && update.activity?.[0]?.agent === "explorer" && update.activity[0].sessionFile === stableHistory.tasks[0].sessionFile));
 	const historicalTaskRecord = JSON.parse(readFileSync(join(stableHistory.tasks[0].recordDirectory, "task.json"), "utf8"));
 	const historicalTurnRecord = JSON.parse(readFileSync(join(stableHistory.tasks[0].recordDirectory, "turns", "02.json"), "utf8"));
 	check("historical task and turn retain their tab identity", historicalTaskRecord.tabId === historicalResume.details.tabId && historicalTurnRecord.tabId === historicalResume.details.tabId);
@@ -618,9 +754,11 @@ try {
 	check("historical pre-prompt failure replaces stale state and report", prePromptFailure.isError && prePromptFailedTask.status === "failed" && !("question" in prePromptFailedTask) && prePromptFailedTask.error.includes("historical startup failed") && prePromptFailedTask.completedAt !== "2000-01-01T00:00:00.000Z" && prePromptFailureReport.status === "failed" && prePromptFailureReport.error.includes("historical startup failed"));
 	check("historical resume releases the run lock after failure", !existsSync(join(stableHistory.recordDirectory, ".resume.lock")));
 	const postPromptFailureHerdr = fakeHerdr("post-fail");
-	const postPromptFailure = await executeHerdrSubagents({ action: "resume", runId: backgroundId, task: 1, prompt: "fails after submit" }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents"), herdr: postPromptFailureHerdr });
+	const postPromptFailureUpdates = [];
+	const postPromptFailure = await executeHerdrSubagents({ action: "resume", runId: backgroundId, task: 1, prompt: "fails after submit" }, undefined, (update) => postPromptFailureUpdates.push(update.details), { cwd: root }, { agentsDirectory: join(process.cwd(), "agents"), herdr: postPromptFailureHerdr });
 	const postPromptFailureReport = JSON.parse(readFileSync(join(stableHistory.tasks[0].recordDirectory, "report.json"), "utf8"));
 	check("historical post-prompt failure persists its authoritative report", postPromptFailure.isError && postPromptFailureReport.status === "failed" && postPromptFailureReport.error.includes("connection lost after prompt submission"));
+	check("historical resume failure emits terminal Fleet activity", postPromptFailureUpdates.some((update) => update.status === "running") && postPromptFailureUpdates.at(-1).status === "failed" && postPromptFailureUpdates.at(-1).activity.every((task) => task.status !== "running"));
 	const shutdownBlockedHerdr = fakeHerdr("blocked");
 	const shutdownBlocked = await executeHerdrSubagents({ tasks: [{ name: "blocked-at-shutdown", prompt: "need input", agent: "explorer" }] }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents"), herdr: shutdownBlockedHerdr });
 	await cancelActiveSubagentRuns(root, shutdownBlockedHerdr);
@@ -674,6 +812,7 @@ try {
 	const authoritativeReport = JSON.parse(readFileSync(join(authoritativeTaskDirectory, "report.json"), "utf8"));
 	check("valid persisted report remains authoritative after Herdr prompt transport failure", !authoritativeAfterPromptFailure.isError && authoritativeTask.status === "completed" && authoritativeReport.status === "completed" && authoritativeAfterPromptFailure.details.tasks[0].summary === authoritativeReport.summary);
 	check("production batch path never passes print mode", batchStarts.every((request) => !request.args.includes("--print")));
+	check("production batch path never steals pane focus", !batchHerdr.calls.some(([name]) => name === "focusPane"));
 
 	const atomicFile = join(root, "atomic.json");
 	await Promise.all(Array.from({ length: 12 }, (_, index) => writeJsonAtomic(atomicFile, { index, payload: "x".repeat(1000) })));

package/packages/todo/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- replace generic Todo CRUD with serialized execution-plan lifecycle commands, guarded single-step advancement, preserved replan history, canonical current-plan results, branch reconstruction tests, and a live rerendering current-plan widget
+
 ## 2026-09-30 - v0.1.0
 
 - 从 `@maxiaochao/pi-toolkit` 提取 todo 权威源码，支持主包捆绑和独立安装。

package/packages/todo/README.md

@@ -1,24 +1,24 @@
 # @maxiaochao/pi-todo
 
-Pi 的会话清单扩展，提供 `todo` 工具、自动推进的生命周期、活跃任务 widget 和 `/todos` 历史视图。
+Pi 的分支本地执行计划扩展，提供 `todo` 生命周期工具、只显示当前计划的 widget 和 `/todos` 完整历史视图。
 
 ![Todo 真实状态机运行截图](docs/screenshot.png)
 
 ## 为什么有这个包
 
-这是 pi-toolkit 自研的计划执行模块，用明确状态替代只存在于对话文本里的计划。它解决计划替换后旧任务残留、多个任务同时 doing、完成后不自动推进，以及 UI 序号与持久 ID 混用的问题。
+这是 pi-toolkit 自研的计划执行模块，用明确状态替代只存在于对话文本里的计划。Todo 是用户可见的后续工作顺序，不是隐藏推理、完成报告或通用任务管理器。它解决改向后历史丢失、并发调用误完成、多个步骤同时 doing、完成后不推进，以及 UI 序号与持久 ID 混用的问题。
 
 ## 演示
 
 ![Todo 生命周期演示](docs/demo.gif)
 
 ```text
-todo({ action: "replace", items: ["Inspect callers", "Implement", "Verify"] })
-todo({ action: "update", id: 1, status: "done" })
+todo({ action: "plan", items: ["Inspect callers", "Implement", "Verify"] })
+todo({ action: "complete_current", expected_current_id: 1 })
 /todos
 ```
 
-第一项完成后下一项自动进入 `doing`；`/todos` 同时展示活跃队列和关闭历史。
+第一项实际完成后，下一项自动进入 `doing`。工具结果和 widget 只展示 `CURRENT plan`；`/todos` 展示当前分支的全部完成、取消和未完成历史。
 
 ## 安装
 
@@ -47,10 +47,20 @@ pi update npm:@maxiaochao/pi-todo     # 更新独立子包
 
 ## 行为
 
-- `replace` 用新计划替换旧计划，并将未完成旧任务标记为取消。
-- `add`、`update`、`remove`、`clear` 管理任务。
-- 同一时间最多一个任务为 `doing`，完成后自动推进下一项。
-- widget 使用连续队列位置；持久记录保留稳定内部 ID。
+- `plan(items)` 创建或重新规划。非空计划取消并保留全部旧 `doing`/`todo` 历史，保留已关闭历史，使用新的单调递增 ID，并启动第一步。
+- `plan([])` 取消全部未完成工作，不留下当前计划；ID 不重置。
+- `add_step(text)` 只追加一步。`complete_current` 和 `cancel_current` 必须携带匹配唯一 `doing` 步骤的 `expected_current_id`，否则原子失败；每次调用只推进一步。
+- 调用共享可变状态并串行执行。同轮多个 sibling completion 不是支持的顺序机制。
+- `list` 与每个变更都向模型返回简洁、规范的 `CURRENT plan`，包含稳定内部 ID 和状态；只有 `/todos` 显示完整历史。
+- widget 从实时状态读取当前计划，使用连续显示位置、隐藏内部 ID 和关闭历史，并在计划结束时消失。
+
+## 使用准则
+
+- 只为明确的多步工作、确实分阶段的工作或跨模型交接创建计划；不要为简单单步任务创建计划。
+- 仅在工作实际完成后调用 `complete_current`。仍然需要但被阻塞的步骤保持当前状态。
+- `cancel_current` 表示当前步骤不再需要且后续计划仍有效；方向改变时使用 `plan`。
+- 保留用户给出的步骤意图和顺序，只在可执行性要求下拆分步骤。
+- 协议不提供任意更新、删除、清空、撤销、批量完成或 marker 文本解析。
 
 ## 开发与测试
 

package/packages/todo/TESTING.md

@@ -2,19 +2,21 @@
 
 ## 流程
 
-1. `npm --prefix packages/todo test`：运行纯状态机确定性测试。
+1. `npm --prefix packages/todo test`：运行状态机确定性测试和扩展/widget 集成测试。
 2. `npm --prefix packages/todo run load-test`：让 Pi 加载真实扩展入口。
 3. `npm pack ./packages/todo --dry-run`：确认发布文件完整。
 4. 确认由真实状态机输出生成的 `docs/screenshot.png` 和 `docs/demo.gif` 可打开且进入 tarball。
 
 ## 用例数据
 
-- 恢复旧格式记录并修复非法生命周期。
-- `replace` 取消旧的活跃任务并建立新队列。
-- 完成当前任务后自动推进下一项。
-- 删除、清空、非法 ID 和非法状态处理。
-- widget 队列位置连续，内部 ID 保持稳定。
+- 恢复旧格式记录、修复非法生命周期，并只从当前分支快照重建。
+- 非空 `plan` 保留关闭历史、取消旧未完成步骤并使用单调新 ID；`plan([])` 留下空当前计划。
+- `expected_current_id` 的 stale、重复和缺失调用原子失败；顺序完成与取消每次只推进一步。
+- `add_step` 只追加，步骤文本不作为 marker 或唯一键解释。
+- 并发发起的调用按提交顺序串行化，同轮重复 completion 不会跨越两个步骤。
+- 已挂载 widget 从实时状态重渲染、主动请求 TUI render、隐藏内部 ID 和关闭历史，并在计划结束时消失。
+- `/todos` 展示完整当前分支历史，而所有工具结果只返回规范 `CURRENT plan`。
 
 ## 最近验证结果
 
-迁移基线：状态机测试全部通过，扩展可由 Pi 独立加载。发布前必须重新运行上述三步；跳过的检查不算通过。
+迁移基线：状态机和扩展集成测试全部通过，扩展可由 Pi 独立加载。发布前必须重新运行上述三步；跳过的检查不算通过。