@maxiaochao/pi-toolkit 0.10.1 → 0.10.3

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

@@ -4,11 +4,27 @@ import { runHerdrSubagents, type HerdrSubagentsResult } from "./runner.ts";
 import { runHerdrSubagentsBatch, type BatchResult, type BatchTask } from "./batch-runner.ts";
 import { respondToBlockedTask } from "./blocking.ts";
 import { cleanSubagentRun, historyText, listSubagentHistory, resumeHistoricalTask } from "./history.ts";
-import { HERDR_ACTIONS, validateToolParams } from "./validation.ts";
+import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "./validation.ts";
 import type { OwnerIdentity } from "./ownership.ts";
 
 export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
 
+export interface HerdrSubagentsRunParams {
+	tasks: HerdrSubagentsTaskParams[];
+	label?: string;
+	concurrency?: number;
+	background?: boolean;
+}
+
+export interface HerdrSubagentsControlToolParams {
+	action: "list" | "respond" | "history" | "resume" | "cleanup";
+	runId?: string;
+	answer?: string;
+	task?: number;
+	prompt?: string;
+}
+
+/** Internal superset used by shared execution helpers. */
 export interface HerdrSubagentsToolParams {
 	action?: "list" | "respond" | "history" | "resume" | "cleanup";
 	prompt?: string;
@@ -113,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 } }),
 			});
@@ -201,17 +218,34 @@ async function executeSingle({ params, signal, onUpdate, ctx, dependencies, disc
 }
 
 export async function executeHerdrSubagents(
-	params: HerdrSubagentsToolParams,
+	params: HerdrSubagentsRunParams | HerdrSubagentsToolParams,
 	signal: AbortSignal | undefined,
 	onUpdate: ((response: ToolResponse) => void) | undefined,
 	ctx: HerdrSubagentsToolContext,
 	dependencies: HerdrSubagentsToolDependencies,
 ): Promise<ToolResponse> {
-	const validationError = validateToolParams(params);
+	if (params.action) return executeHerdrSubagentsControl(params as HerdrSubagentsControlToolParams, signal, onUpdate, ctx, dependencies);
+	if (params.prompt && !params.tasks) {
+		const discovery = loadSubagentConfiguration(ctx.cwd, dependencies.agentsDirectory, modelId(ctx), dependencies.configurationPaths);
+		return executeSingle({ params, signal, onUpdate, ctx, dependencies, discovery });
+	}
+	const runParams = params as HerdrSubagentsRunParams;
+	const validationError = validateRunParams(runParams);
 	if (validationError) return { content: [{ type: "text", text: validationError }], details: { errorMessage: validationError }, isError: true };
 	const discovery = loadSubagentConfiguration(ctx.cwd, dependencies.agentsDirectory, modelId(ctx), dependencies.configurationPaths);
-	const execution = { params, signal, onUpdate, ctx, dependencies, discovery };
-	if (params.action) return actionHandlers[params.action](execution);
+	const execution = { params: runParams, signal, onUpdate, ctx, dependencies, discovery };
+	return executeBatch(execution);
+}
 
-	return params.tasks ? executeBatch(execution) : executeSingle(execution);
+export async function executeHerdrSubagentsControl(
+	params: HerdrSubagentsControlToolParams,
+	signal: AbortSignal | undefined,
+	onUpdate: ((response: ToolResponse) => void) | undefined,
+	ctx: HerdrSubagentsToolContext,
+	dependencies: HerdrSubagentsToolDependencies,
+): Promise<ToolResponse> {
+	const validationError = validateControlParams(params);
+	if (validationError) return { content: [{ type: "text", text: validationError }], details: { errorMessage: validationError }, isError: true };
+	const discovery = loadSubagentConfiguration(ctx.cwd, dependencies.agentsDirectory, modelId(ctx), dependencies.configurationPaths);
+	return actionHandlers[params.action]({ params, signal, onUpdate, ctx, dependencies, discovery });
 }

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

@@ -1,6 +1,4 @@
-import type { HerdrSubagentsToolParams } from "./tool.ts";
-
-const executionFields = ["prompt", "agent", "label", "model", "tasks", "concurrency", "background"] as const;
+import type { HerdrSubagentsControlToolParams, HerdrSubagentsRunParams } from "./tool.ts";
 
 export const HERDR_ACTIONS = {
 	list: { allowed: ["action"], includeRunId: false },
@@ -8,31 +6,20 @@ export const HERDR_ACTIONS = {
 	cleanup: { allowed: ["action", "runId"], includeRunId: true },
 	respond: { allowed: ["action", "runId", "answer", "task"], includeRunId: true },
 	resume: { allowed: ["action", "runId", "task", "prompt"], includeRunId: true },
-} as const satisfies Record<string, { allowed: readonly (keyof HerdrSubagentsToolParams)[]; includeRunId: boolean }>;
+} as const satisfies Record<string, { allowed: readonly (keyof HerdrSubagentsControlToolParams)[]; includeRunId: boolean }>;
+
+export function validateRunParams(params: HerdrSubagentsRunParams): string | undefined {
+	if (!params.tasks?.length) return "Provide a non-empty tasks list.";
+	return undefined;
+}
 
-export function validateToolParams(params: HerdrSubagentsToolParams): string | undefined {
-	const present = (key: keyof HerdrSubagentsToolParams) => params[key] !== undefined;
-	const extraField = (allowed: readonly (keyof HerdrSubagentsToolParams)[]) => Object.keys(params).find((key) => !allowed.includes(key as keyof HerdrSubagentsToolParams));
-	if (params.action) {
-		const extra = extraField(HERDR_ACTIONS[params.action].allowed);
-		if (extra) return `Field '${extra}' is not valid with action '${params.action}'.`;
-		if (params.action === "cleanup" && !params.runId?.trim()) return "runId is required for action 'cleanup'.";
-		if (params.action === "respond" && (!params.runId?.trim() || !params.answer?.trim())) return "runId and answer are required for action 'respond'.";
-		if (params.action === "resume" && (!params.runId?.trim() || !params.task || !params.prompt?.trim())) return "runId, task, and prompt are required for action 'resume'.";
-		return undefined;
-	}
-	if (params.prompt && params.tasks) return "Provide either prompt or tasks, not both.";
-	if (params.prompt) {
-		const extra = extraField(["prompt", "agent", "label", "model"]);
-		if (extra) return `Field '${extra}' is not valid for single-task execution.`;
-		return undefined;
-	}
-	if (params.tasks) {
-		if (!params.tasks.length) return "tasks must contain at least one task.";
-		const extra = extraField(["tasks", "label", "concurrency", "background"]);
-		if (extra) return `Field '${extra}' is not valid for batch execution.`;
-		return undefined;
-	}
-	const supplied = executionFields.find((key) => present(key));
-	return supplied ? `Field '${supplied}' requires prompt or tasks.` : "Provide an action, prompt, or non-empty tasks list.";
+export function validateControlParams(params: HerdrSubagentsControlToolParams): string | undefined {
+	const allowed = HERDR_ACTIONS[params.action]?.allowed;
+	if (!allowed) return "Provide a valid control action.";
+	const extra = Object.keys(params).find((key) => !allowed.includes(key as keyof HerdrSubagentsControlToolParams));
+	if (extra) return `Field '${extra}' is not valid with action '${params.action}'.`;
+	if (params.action === "cleanup" && !params.runId?.trim()) return "runId is required for action 'cleanup'.";
+	if (params.action === "respond" && (!params.runId?.trim() || !params.answer?.trim())) return "runId and answer are required for action 'respond'.";
+	if (params.action === "resume" && (!params.runId?.trim() || !params.task || !params.prompt?.trim())) return "runId, task, and prompt are required for action 'resume'.";
+	return undefined;
 }

package/packages/herdr-subagents/tests/extension-contract.ts

@@ -9,6 +9,7 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 	const handlers = new Map<string, (...args: any[]) => any>();
 	const commands: string[] = [];
 	let tool: Record<string, any> | undefined;
+	let controlTool: Record<string, any> | undefined;
 	let terminalInput: ((data: string) => { consume?: boolean } | undefined) | undefined;
 	let widgetCalls = 0;
 	let renderedLines: string[] = [];
@@ -26,13 +27,17 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 	};
 	const pi = {
 		on(name: string, handler: (...args: any[]) => any) { handlers.set(name, handler); },
-		registerTool(definition: Record<string, any>) { tool = definition; },
+		registerTool(definition: Record<string, any>) {
+			if (definition.name === "herdr_subagents") tool = definition;
+			if (definition.name === "herdr_subagents_control") controlTool = definition;
+		},
 		registerCommand(name: string) { commands.push(name); },
 		sendMessage() {},
 	};
 	registerHerdrSubagents(pi as never, {
 		herdr: { async focusPane(paneId: string) { focusedPanes.push(paneId); } } as never,
 		execute: execute as never,
+		executeControl: execute as never,
 		isEditor: (value) => value === editor,
 		createFleetWidget(lines) { renderedLines = lines; return new Container(); },
 	});
@@ -40,6 +45,7 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 		handlers,
 		commands,
 		get tool() { return tool; },
+		get controlTool() { return controlTool; },
 		get terminalInput() { return terminalInput; },
 		get widgetCalls() { return widgetCalls; },
 		get renderedLines() { return renderedLines; },
@@ -73,7 +79,8 @@ async function verifyPublicUiWiring() {
 		if (!responding.tool) throw new Error("herdr_subagents was not registered for UI wiring test");
 		const renderedBlocked = responding.tool.renderResult({ content: [{ type: "text", text: "needs input" }], details: { agent: "explorer", status: "blocked", ok: false, summary: "Need input.", documents: [] } }, { isPartial: false }, { fg: (_color: string, text: string) => text, bold: (text: string) => text }).render(100).join("\n");
 		if (!renderedBlocked.includes("blocked") || renderedBlocked.includes("failed")) throw new Error("single-task blocked result did not render its authoritative status");
-		await responding.tool.execute("call", { action: "respond", runId: "blocked-run", answer: "main" }, undefined, undefined, { cwd, ui: responding.ui });
+		if (!responding.controlTool) throw new Error("herdr_subagents_control was not registered for UI wiring test");
+		await responding.controlTool.execute("call", { action: "respond", runId: "blocked-run", answer: "main" }, undefined, undefined, { cwd, ui: responding.ui });
 		if (!responding.renderedLines.some((line) => line.includes("second") && line.includes("blocked"))) throw new Error("blocked response did not refresh Fleet rows");
 		if (!responding.terminalInput?.("\u001b[B")?.consume || !responding.terminalInput?.("\u001b[B")?.consume || !responding.terminalInput?.("\r")?.consume) throw new Error("Fleet terminal input was not consumed while selecting");
 		await new Promise((resolve) => setTimeout(resolve, 0));
@@ -167,7 +174,7 @@ try {
 	if (inactiveHerdr.tool || inactiveHerdr.commands.length || inactiveHerdr.handlers.size) throw new Error("Subagents registered with HERDR_ENV=0");
 	process.env.HERDR_ENV = "1";
 	const inside = harness(async () => { throw new Error("unreachable"); });
-	if (!inside.tool || !inside.commands.includes("herdr-subagents") || !inside.handlers.has("session_start")) throw new Error("Subagents did not register inside Herdr");
+	if (!inside.tool || !inside.controlTool || !inside.commands.includes("herdr-subagents") || !inside.handlers.has("session_start")) throw new Error("Subagents did not register both tools inside Herdr");
 	process.env.PI_HERDR_SUBAGENTS_CHILD = "1";
 	const child = harness(async () => { throw new Error("unreachable"); });
 	if (child.tool || child.commands.length || child.handlers.size) throw new Error("Subagents registered inside a child Agent");
@@ -183,10 +190,10 @@ try {
 }
 
 export default function (_pi: ExtensionAPI) {
-	let tool: Record<string, any> | undefined;
+	const tools = new Map<string, Record<string, any>>();
 	const pi = {
 		on() {},
-		registerTool(definition: Record<string, any>) { tool = definition; },
+		registerTool(definition: Record<string, any>) { tools.set(definition.name, definition); },
 		registerCommand() {},
 		sendMessage() {},
 	};
@@ -207,19 +214,30 @@ export default function (_pi: ExtensionAPI) {
 		if (previousChild === undefined) delete process.env.PI_HERDR_SUBAGENTS_CHILD;
 		else process.env.PI_HERDR_SUBAGENTS_CHILD = previousChild;
 	}
-	if (!tool) throw new Error("herdr_subagents was not registered");
+	const tool = tools.get("herdr_subagents");
+	const controlTool = tools.get("herdr_subagents_control");
+	if (!tool || !controlTool) throw new Error("Herdr execution and control tools were not both registered");
 	const schema = tool.parameters as Record<string, any>;
 	if (schema.type !== "object" || schema.anyOf || schema.oneOf) throw new Error("herdr_subagents parameters must be one flat object schema");
-	const required = ["action", "runId", "answer", "task", "prompt", "agent", "label", "model", "tasks", "concurrency", "background"];
-	for (const name of required) {
+	for (const name of ["tasks", "label", "concurrency", "background"]) {
 		if (!schema.properties?.[name]) throw new Error(`schema is missing property '${name}'`);
 		if (!schema.properties[name].description) throw new Error(`schema property '${name}' has no description`);
 	}
+	if (!schema.required?.includes("tasks")) throw new Error("herdr_subagents tasks must be required");
+	const normalized = tool.prepareArguments?.({ prompt: "inspect", agent: "explorer", label: "probe", background: true });
+	if (normalized?.tasks?.length !== 1 || normalized.tasks[0].name !== "probe" || normalized.tasks[0].prompt !== "inspect" || normalized.tasks[0].agent !== "explorer" || normalized.background !== true) {
+		throw new Error("legacy single-task arguments were not normalized into a one-item background run");
+	}
 	for (const name of ["name", "prompt", "agent", "model"]) {
 		const property = schema.properties.tasks.items.properties[name];
 		if (!property?.description) throw new Error(`nested task property '${name}' has no description`);
 	}
-	if (!/Foreground calls block/.test(tool.description) || !/background batches return a run ID immediately/.test(tool.description)) {
+	const controlSchema = controlTool.parameters as Record<string, any>;
+	for (const name of ["action", "runId", "answer", "task", "prompt"]) {
+		if (!controlSchema.properties?.[name]?.description) throw new Error(`control schema property '${name}' is missing or undocumented`);
+	}
+	if (!controlSchema.required?.includes("action")) throw new Error("herdr_subagents_control action must be required");
+	if (!/Foreground calls block/.test(tool.description) || !/background calls return a run ID immediately/.test(tool.description)) {
 		throw new Error("tool description does not distinguish foreground and background execution");
 	}
 }

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 { HERDR_ACTIONS, validateToolParams } from "../src/validation.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";
@@ -136,22 +138,18 @@ function latestRunDirectory() {
 }
 
 try {
-	check("flat mode validation accepts supported calls", [
+	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: "respond", runId: "run", answer: "yes", task: 1 },
 		{ action: "resume", runId: "run", task: 1, prompt: "continue" },
-		{ prompt: "one task", agent: "worker", label: "one", model: "fake/model" },
-		{ tasks: [{ name: "one", prompt: "do it" }], concurrency: 2, background: true },
-	].every((params) => validateToolParams(params) === undefined));
+	].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("flat mode validation rejects ambiguous and extraneous fields", [
-		validateToolParams({ prompt: "one", tasks: [{ name: "two", prompt: "two" }] }),
-		validateToolParams({ action: "list", prompt: "not allowed" }),
-		validateToolParams({ action: "respond", runId: "run" }),
-		validateToolParams({ tasks: [{ name: "one", prompt: "one" }], agent: "worker" }),
-		validateToolParams({ prompt: "one", runId: "run" }),
-		validateToolParams({ prompt: "one", task: 1 }),
-		validateToolParams({ tasks: [{ name: "one", prompt: "one" }], answer: "extra" }),
+	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));
 	const fleet = new FleetSelection();
 	const fleetBatch = { label: "reviews", activity: [
@@ -164,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);
@@ -192,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];
@@ -313,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);
@@ -552,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("fake/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 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);
@@ -622,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);
@@ -678,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 独立加载。发布前必须重新运行上述三步；跳过的检查不算通过。