@maxiaochao/pi-toolkit 0.10.2 → 0.10.4

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";
@@ -138,17 +140,20 @@ function latestRunDirectory() {
 try {
 	check("run validation accepts one or more tasks", validateRunParams({ tasks: [{ name: "one", prompt: "do it" }], concurrency: 2, background: true }) === undefined);
 	check("control validation accepts supported calls", [
-		{ action: "list" }, { action: "history" }, { action: "cleanup", runId: "run" },
+		{ action: "list" }, { action: "history" }, { action: "cancel", runId: "run" }, { action: "cleanup", runId: "run" },
 		{ action: "respond", runId: "run", answer: "yes", task: 1 },
 		{ action: "resume", runId: "run", task: 1, prompt: "continue" },
 	].every((params) => validateControlParams(params) === undefined));
-	check("all supported actions have shared validation and rendering metadata", ["list", "history", "cleanup", "respond", "resume"].every((action) => action in HERDR_ACTIONS));
+	check("all supported actions have shared validation and rendering metadata", ["list", "history", "cancel", "cleanup", "respond", "resume"].every((action) => action in HERDR_ACTIONS));
 	check("split validation rejects missing tasks and invalid control fields", [
 		validateRunParams({ tasks: [] }),
 		validateControlParams({ action: "list", prompt: "not allowed" }),
 		validateControlParams({ action: "respond", runId: "run" }),
 		validateControlParams({ action: "resume", runId: "run", task: 1 }),
 	].every((message) => typeof message === "string" && message.length > 0));
+	let cancelledRunId;
+	const cancelControl = await executeHerdrSubagents({ action: "cancel", runId: "active-run" }, undefined, undefined, { cwd: root }, { agentsDirectory: join(process.cwd(), "agents"), cancelRun: async (runId) => { cancelledRunId = runId; return { cancelled: true }; } });
+	check("cancel control targets the selected active or queued run", !cancelControl.isError && cancelledRunId === "active-run" && cancelControl.details.cancelled === true);
 	const fleet = new FleetSelection();
 	const fleetBatch = { label: "reviews", activity: [
 		{ index: 0, name: "one", status: "completed", paneId: "p1" },
@@ -160,7 +165,143 @@ 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"));
+	liveTokens = 126;
+	for (const callback of [...runtimeIntervals.values()]) callback();
+	for (const callback of [...runtimeTimeouts.values()]) callback();
+	runtimeTimeouts.clear();
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	check("Fleet widget refreshes token usage on every running one-second tick", liveWidget.render(80)[1].includes("126 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 +329,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];
@@ -297,18 +439,25 @@ try {
 	check("batch is FIFO with a dedicated pane per task", batchPrompts.join(",") === "one slow,two,three FAIL,four" && new Set(batchStarts.map((request) => request.paneId)).size === 4);
 	check("failed sibling does not cancel batch", batch.isError && batchDetails.status === "partial" && batchDetails.tasks.map((task) => task.name).join(",") === "one,two,three,four" && batchDetails.tasks[2].status === "failed" && batchDetails.tasks[3].status === "completed");
 	const batchCleanupHerdr = fakeHerdr("close-failed");
-	const batchCleanup = await executeHerdrSubagents({ tasks: [{ name: "cleanup", prompt: "cleanup", agent: "explorer" }] }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: batchCleanupHerdr });
+	const batchCleanupUpdates = [];
+	const batchCleanup = await executeHerdrSubagents({ tasks: [{ name: "cleanup", prompt: "cleanup", agent: "explorer" }] }, undefined, (update) => batchCleanupUpdates.push(update), { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: batchCleanupHerdr });
 	const batchCleanupRecord = JSON.parse(readFileSync(join(batchCleanup.details.recordDirectory, "run.json"), "utf8"));
-	check("batch cleanup failure is persisted and surfaced", batchCleanup.isError && batchCleanup.content[0].text.includes("cleanup failed") && batchCleanupRecord.status === "failed" && batchCleanupRecord.cleanupError.includes("tab still busy"));
+	check("batch cleanup failure is persisted and surfaced once", batchCleanup.isError && batchCleanup.content[0].text.includes("cleanup failed") && batchCleanupRecord.status === "failed" && batchCleanupRecord.cleanupError.includes("tab still busy") && batchCleanupUpdates.filter((update) => update.content[0]?.text.includes("cleanup failed")).length === 1);
 	const cleanupProbeHerdr = fakeHerdr();
 	cleanupProbeHerdr.isTabFocused = async () => { throw new Error("tab lookup failed"); };
 	const cleanupProbe = await executeHerdrSubagents({ tasks: [{ name: "cleanup-probe", prompt: "cleanup probe", agent: "explorer" }] }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: cleanupProbeHerdr });
 	const cleanupProbeRecord = JSON.parse(readFileSync(join(cleanupProbe.details.recordDirectory, "run.json"), "utf8"));
 	check("cleanup focus-probe failure is persisted and surfaced", cleanupProbe.isError && cleanupProbe.content[0].text.includes("tab lookup failed") && cleanupProbeRecord.status === "failed" && cleanupProbeRecord.cleanupError === "tab lookup failed");
+	const missingTabHerdr = fakeHerdr();
+	missingTabHerdr.isTabFocused = async () => { throw new Error('{"error":{"code":"tab_not_found","message":"tab w1:t2 not found"}}'); };
+	const missingTabCleanup = await executeHerdrSubagents({ tasks: [{ name: "already-closed", prompt: "already closed", agent: "explorer" }] }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: missingTabHerdr });
+	const missingTabRecord = JSON.parse(readFileSync(join(missingTabCleanup.details.recordDirectory, "run.json"), "utf8"));
+	check("already-missing tab is successful idempotent cleanup", !missingTabCleanup.isError && missingTabRecord.status === "completed" && !missingTabRecord.cleanupPendingTabIds && !missingTabRecord.cleanupError);
 	const activeUpdate = batchUpdates.find((update) => update.activity?.some((task) => task.status === "running"));
 	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);
@@ -417,6 +566,13 @@ try {
 	check("dispatcher starts next queued run automatically", starts.join(",") === "run-one,run-two" && dispatcher.snapshot().activeRunId === "run-two");
 	releaseSecond();
 	check("dispatcher settles queued run", await second === "two");
+	const cancellingDispatcher = new RunDispatcher();
+	cancellingDispatcher.pause();
+	const removedQueued = cancellingDispatcher.submit("remove-me", async () => "unexpected").catch((error) => error.message);
+	const keptQueued = cancellingDispatcher.submit("keep-me", async () => "kept");
+	check("dispatcher cancels only the selected queued run", cancellingDispatcher.cancelQueuedRun("remove-me", new Error("cancelled by user")) && await removedQueued === "cancelled by user" && cancellingDispatcher.snapshot().queuedRunIds.join(",") === "keep-me");
+	cancellingDispatcher.resume();
+	check("dispatcher still executes uncancelled queued siblings", await keptQueued === "kept");
 	const retainedDispatcher = new RunDispatcher();
 	const retainedStarts = [];
 	const retainedFirst = retainedDispatcher.submit("blocked-run", async () => { retainedStarts.push("blocked-run"); retainedDispatcher.retain("blocked-run"); return "blocked"; });
@@ -548,9 +704,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 +776,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 +834,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 独立加载。发布前必须重新运行上述三步；跳过的检查不算通过。