@maxiaochao/pi-toolkit 0.10.3 → 0.10.5

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 2026-10-08 - v0.10.5
+
+- bundle herdr-subagents v0.4.2: add Alt+P and /parent controls to return from child Agents
+## 2026-10-08 - v0.10.4
+
+- bundle herdr-subagents v0.4.1: targeted cancellation, live token polling, and idempotent tab cleanup
+
 ## 2026-10-08 - v0.10.3
 
 - bundle herdr-subagents v0.4.0: add the live compact Fleet footer with authoritative metrics and refreshed media

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "Personal pi coding agent toolkit: execution plans, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2026-10-08 - v0.4.2
+
+- add Alt+P and /parent controls to return from child Agents
+- Add `/parent` and `Alt+P` inside child Agents to return focus to the exact parent Agent pane, with a visible child footer hint.
+
+## 2026-10-08 - v0.4.1
+
+- targeted cancellation, live token polling, and idempotent tab cleanup
+- Add `cancel` control for one active or queued run while leaving unrelated runs untouched.
+- Refresh live Fleet token totals every second as well as on file events.
+- Treat already-missing tabs as successful cleanup and emit one warning per real cleanup failure.
+
 ## 2026-10-08 - v0.4.0
 
 - add the live compact Fleet footer with authoritative metrics and refreshed media

package/packages/herdr-subagents/README.md

@@ -72,9 +72,11 @@ A child missing required information reports `needs-input` with an exact questio
 herdr_subagents_control({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
 ```
 
-While a batch is active, a compact Fleet monitor stays below the editor. Its divider/title row summarizes the run, and each task row shows a hollow or filled status circle, the real persona and task name, status, live active duration, and cumulative child Pi token usage in one compact shared metrics column after the longest row rather than at the terminal edge. Running work uses Pi's warning/yellow semantic color and completed work uses success/green. Token totals use the child session's persisted assistant, tool-result, standalone usage, compaction, and branch-summary usage; they are never estimated. Queued tasks show neither fabricated time nor tokens. The monitor follows Pi theme semantics, truncates by visible terminal columns, and updates session usage from file events while one lightweight repaint timer advances running durations.
+Cancel one active or queued run with `herdr_subagents_control({ action: "cancel", runId: "<run-id>" })`. Cancellation aborts its live child prompts, archives active or queued tasks as cancelled, closes its run tab, and leaves unrelated runs alone.
 
-With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback.
+While a batch is active, a compact Fleet monitor stays below the editor. Its divider/title row summarizes the run, and each task row shows a hollow or filled status circle, the real persona and task name, status, live active duration, and cumulative child Pi token usage in one compact shared metrics column after the longest row rather than at the terminal edge. Running work uses Pi's warning/yellow semantic color and completed work uses success/green. Token totals use the child session's persisted assistant, tool-result, standalone usage, compaction, and branch-summary usage; they are never estimated. Queued tasks show neither fabricated time nor tokens. The monitor follows Pi theme semantics, truncates by visible terminal columns, and refreshes session usage from both file events and the running one-second timer.
+
+With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback. Inside every child Agent, press `Alt+P` or run `/parent` to return to the exact parent Agent pane; the shortcut is also shown in the child footer.
 
 ## History
 
@@ -84,7 +86,7 @@ Continue a saved conversation in a new Herdr tab with `herdr_subagents_control({
 
 Read-only tasks start FIFO up to the configured concurrency limit. A pane is created only when its task starts, belongs exclusively to that task, and is never reused. Completed panes remain inspectable while another task in the batch is unsettled. Results remain in input order, and one failed task does not cancel its siblings. Any batch containing a write-capable persona is forced to concurrency one.
 
-The widget shows one row per queued, running, blocked, failed, or completed task. Answering a blocked task or resuming saved history refreshes authoritative persona, timing, session, status, and pane projections as work advances. Active duration accumulates only while the task is running, excluding time spent queued or waiting for an answer. Completed rows remain selectable until the whole batch settles. `/herdr-subagents active` shows the same compact state. Native labels stay short: `SA · <batch>` for the tab and `<order> · <task>` for each pane. When all tasks settle, the tab closes immediately if unfocused or after the user leaves it; a deferred close failure is persisted and shown as a warning.
+The widget shows one row per queued, running, blocked, failed, or completed task. Answering a blocked task or resuming saved history refreshes authoritative persona, timing, session, status, and pane projections as work advances. Active duration accumulates only while the task is running, excluding time spent queued or waiting for an answer. Completed rows remain selectable until the whole batch settles. `/herdr-subagents active` shows the same compact state. Native labels stay short: `SA · <batch>` for the tab and `<order> · <task>` for each pane. When all tasks settle, the tab closes immediately if unfocused or after the user leaves it; a deferred close failure is persisted and shown as a warning. An already-missing tab is treated as successfully cleaned, so retries are idempotent.
 
 Foreground calls block until all children report completion, failure, or a request for input. Every child is started with Herdr's Agent lifecycle as a normal Pi TUI and prompted with wait semantics; no print-mode command or completion marker is injected into the pane.
 

package/packages/herdr-subagents/TESTING.md

@@ -16,12 +16,12 @@
 - Force write-capable batches to serial execution while allowing bounded read-only parallelism.
 - Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
 - Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
-- Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, child `/parent` and `Alt+P` return controls, and stable display while another background run queues.
 - Verify Fleet divider/row formatting, warning/yellow running indicators, success/green completed indicators, persona and task projections, cumulative active duration across blocking/resume, exact Pi usage aggregation from assistant messages, tool results, standalone usage, compaction, and branch summaries, malformed/truncated JSONL tolerance, queued metric omission, and visible-column bounds at narrow widths.
-- Verify live token updates are file-event driven, elapsed repainting exists only while work runs, and widget disposal closes watchers and timers.
-- Verify blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
+- Verify live token updates are file-event driven and polled on each running one-second tick, elapsed repainting exists only while work runs, and widget disposal closes watchers and timers.
+- Verify selected active/queued run cancellation, blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, idempotent missing-tab cleanup, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
 - Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
 
 ## Latest baseline
 
-All 159 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.
+All 169 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.

package/packages/herdr-subagents/extensions/herdr-subagents.ts

@@ -160,6 +160,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	const dispatcher = new RunDispatcher();
 	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget, dependencies.fleetWidgetRuntime);
 	const runControllers = new Map<string, AbortController>();
+	const runPromises = new Map<string, Promise<unknown>>();
 	const inFlight = new Set<Promise<unknown>>();
 	let sessionController = new AbortController();
 	let ownerSessionId: string | undefined;
@@ -228,8 +229,9 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 				}
 				return result;
 			});
+			runPromises.set(runId, promise);
 			inFlight.add(promise);
-			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(runId); }).catch(() => undefined);
+			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(runId); runPromises.delete(runId); }).catch(() => undefined);
 			if (params.background) {
 				void promise.then((result) => {
 					if (generation !== sessionGeneration) return;
@@ -237,6 +239,10 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 					if (!fleet.active && !dispatcher.snapshot().activeRunId && dispatcher.snapshot().queuedRunIds.length === 0) fleet.render();
 				}).catch((error) => {
 					if (generation !== sessionGeneration) return;
+					if (controller.signal.aborted) {
+						pi.sendMessage({ customType: "herdr-subagents-run", content: `Subagent run ${runId} cancelled.`, display: true, details: { runId, status: "cancelled" } }, { triggerTurn: true, deliverAs: "followUp" });
+						return;
+					}
 					pi.sendMessage({ customType: "herdr-subagents-run", content: `Subagent run ${runId} failed: ${error instanceof Error ? error.message : String(error)}`, display: true, details: { runId, status: "failed" } }, { triggerTurn: true, deliverAs: "followUp" });
 				});
 				return { content: [{ type: "text" as const, text: `Subagent run queued: ${runId}` }], details: { runId, status: "queued", background: true } };
@@ -253,12 +259,12 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerTool({
 		name: "herdr_subagents_control",
 		label: "Herdr Subagents Control",
-		description: "Inspect Herdr personas and run history, answer a blocked task, resume a saved task, or remove a selected archived run. Use herdr_subagents to start new work.",
+		description: "Inspect Herdr personas and run history, cancel active or queued work, answer a blocked task, resume a saved task, or remove a selected archived run. Use herdr_subagents to start new work.",
 		promptSnippet: "Inspect and control Herdr subagent runs",
 		parameters: HerdrSubagentsControlParams,
 
 		async execute(_toolCallId, params: HerdrSubagentsControlToolParams, signal, onUpdate, ctx) {
-			const executionId = params.runId ?? randomUUID();
+			const executionId = randomUUID();
 			const controller = new AbortController();
 			runControllers.set(executionId, controller);
 			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(signal ? [signal] : [])]);
@@ -269,7 +275,34 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 				const updateDetails = update.details as { warning?: string };
 				if (updateDetails.warning || updateText?.includes("cleanup failed")) ctx.ui.notify(updateDetails.warning ?? updateText ?? "Subagent warning", "warning");
 				onUpdate?.(update);
-			}, ctx, { agentsDirectory: packageAgentsDir, owner: { sessionId: ownerSessionId, processId: process.pid } });
+			}, ctx, {
+				agentsDirectory: packageAgentsDir,
+				herdr,
+				owner: { sessionId: ownerSessionId, processId: process.pid },
+				cancelRun: async (runId) => {
+					const reason = new Error("Subagent run cancelled by user.");
+					const targetController = runControllers.get(runId);
+					targetController?.abort(reason);
+					if (dispatcher.cancelQueuedRun(runId, reason)) {
+						await cancelQueuedRuns(ctx.cwd, [runId], { reason: reason.message, owner: { sessionId: ownerSessionId, processId: process.pid } });
+						fleet.clearRun(runId);
+						return { cancelled: true, queued: true };
+					}
+					const activePromise = runPromises.get(runId);
+					if (activePromise) {
+						await activePromise.catch(() => undefined);
+						fleet.clearRun(runId);
+						dispatcher.release(runId);
+						return { cancelled: true };
+					}
+					const cancellation = await cancelActiveSubagentRuns(ctx.cwd, herdr, { reason: reason.message, owner: { sessionId: ownerSessionId, processId: process.pid }, runId });
+					if (cancellation.cancelledRuns) {
+						fleet.clearRun(runId);
+						dispatcher.release(runId);
+					}
+					return { cancelled: cancellation.cancelledRuns > 0, cleanupErrors: cancellation.cleanupErrors };
+				},
+			});
 			inFlight.add(promise);
 			const result = await promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); });
 			fleet.sync(result.details);

package/packages/herdr-subagents/extensions/subagent-report.ts

@@ -4,6 +4,21 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { resultPathForAttempt } from "../src/result-path.ts";
+import { PARENT_PANE_ENV } from "../src/live-agent.ts";
+
+const RETURN_SHORTCUT = "alt+p";
+
+async function returnToParent(pi: ExtensionAPI, ctx: { ui: { notify(message: string, type?: "info" | "warning" | "error"): void } }): Promise<void> {
+	const parentPaneId = process.env[PARENT_PANE_ENV]?.trim();
+	if (!parentPaneId) {
+		ctx.ui.notify("Parent Agent pane is unavailable for this Subagent session.", "error");
+		return;
+	}
+	const result = await pi.exec("herdr", ["agent", "focus", parentPaneId]);
+	if (result.code !== 0) {
+		ctx.ui.notify(`Could not return to the parent Agent: ${result.stderr.trim() || result.stdout.trim() || `Herdr exited ${result.code}`}`, "error");
+	}
+}
 
 const ReportParams = Type.Object({
 	status: StringEnum(["completed", "needs-input", "failed"] as const, { description: "Current outcome for this task." }),
@@ -24,6 +39,17 @@ function writeAtomic(path: string, content: string): void {
 }
 
 export default function (pi: ExtensionAPI) {
+	pi.registerCommand("parent", {
+		description: "Return focus to the parent Agent pane",
+		async handler(_args, ctx) { await returnToParent(pi, ctx); },
+	});
+	pi.registerShortcut(RETURN_SHORTCUT, {
+		description: "Return to parent Agent",
+		async handler(ctx) { await returnToParent(pi, ctx); },
+	});
+	pi.on("session_start", async (_event, ctx) => {
+		if (process.env[PARENT_PANE_ENV]?.trim()) ctx.ui.setStatus("herdr-subagents-parent", `${RETURN_SHORTCUT} parent`);
+	});
 	pi.registerTool({
 		name: "subagent_report",
 		label: "Subagent Report",

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

package/packages/herdr-subagents/src/batch-runner.ts

@@ -190,7 +190,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 		const failed = settledResults.filter((result) => result.status === "failed").length;
 		const cancelled = options.signal?.aborted || activity.some((entry) => entry.status === "cancelled");
 		const status: BatchResult["status"] = cancelled ? "cancelled" : blocked || activity.some((entry) => entry.status === "queued") ? "blocked" : failed === 0 ? "completed" : failed === tasks.length ? "failed" : "partial";
-		const summary = status === "cancelled" ? "Subagent batch cancelled because the parent Pi session closed." : blocked ? `${blocked.name} needs input: ${blocked.question}` : failed ? `${tasks.length - failed}/${tasks.length} tasks completed; ${failed} failed.` : `${tasks.length}/${tasks.length} tasks completed.`;
+		const summary = status === "cancelled" ? "Subagent batch cancelled." : blocked ? `${blocked.name} needs input: ${blocked.question}` : failed ? `${tasks.length - failed}/${tasks.length} tasks completed; ${failed} failed.` : `${tasks.length}/${tasks.length} tasks completed.`;
 		applyRunStatus(runRecord, status, { question: blocked?.question });
 		await writeJsonAtomic(runFile, runRecord);
 		return { ok: status === "completed", status, runId, label: options.label, requestedConcurrency, effectiveConcurrency, tasks: settledResults, activity, summary, documents: settledResults.flatMap((result) => result.documents), recordDirectory: runDirectory, tabId };
@@ -205,7 +205,7 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 				await cleanupRunTab({
 					herdr, tabId, runFile, runRecord, signal: options.signal, failureStatus: "failed",
 					errorPrefix: "Task results settled, but Herdr tab cleanup failed",
-					onError: (message) => { emit("failed", message); options.onCleanupError?.(message); },
+					onError: (message) => options.onCleanupError?.(message),
 				});
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);

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

@@ -51,6 +51,14 @@ export class RunDispatcher {
 		this.changed();
 		return cancelled.map((run) => run.id);
 	}
+	cancelQueuedRun(id: string, reason: Error): boolean {
+		const index = this.queue.findIndex((run) => run.id === id);
+		if (index < 0) return false;
+		const [cancelled] = this.queue.splice(index, 1);
+		cancelled.reject(reason);
+		this.changed();
+		return true;
+	}
 
 	private changed(): void { this.onChange?.(this.snapshot()); }
 

package/packages/herdr-subagents/src/fleet-controller.ts

@@ -103,7 +103,10 @@ export class FleetWidget implements Component {
 			} catch { /* The next durable activity update can retry the watch. */ }
 		}
 		const hasRunning = this.batch.activity.some((task) => task.status === "running");
-		if (hasRunning && !this.elapsedTimer) this.elapsedTimer = this.runtime.setInterval(() => this.tui.requestRender(), 1_000);
+		if (hasRunning && !this.elapsedTimer) this.elapsedTimer = this.runtime.setInterval(() => {
+			this.tui.requestRender();
+			this.scheduleMetricsRefresh(0);
+		}, 1_000);
 		else if (!hasRunning && this.elapsedTimer) { this.runtime.clearInterval(this.elapsedTimer); this.elapsedTimer = undefined; }
 		this.scheduleMetricsRefresh(0);
 	}

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

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { appendFile, mkdir, readFile, rm, rmdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
-import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { childEnvironment, liveAgentName, promptLiveAgent } from "./live-agent.ts";
 import { writeJsonAtomic, writeTextAtomic } from "./state.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import type { OwnerIdentity } from "./ownership.ts";
@@ -144,7 +144,7 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 		let report: PersistedReport;
 		let status: "blocked" | "completed" | "failed";
 		try {
-			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: historical.recordDirectory };
+			const env = childEnvironment(historical.recordDirectory);
 			tab = await herdr.createTab({ workspaceId: process.env.HERDR_WORKSPACE_ID ?? "", cwd, label: `SA · ${run.label}`, env, focus: false, signal: options.signal });
 			const paneLabel = `${String(historical.order).padStart(2, "0")} · ${historical.name}`;
 			await herdr.renamePane(tab.paneId, paneLabel, options.signal);

package/packages/herdr-subagents/src/live-agent.ts

@@ -17,6 +17,17 @@ export interface LiveTaskRecord {
 	skills?: string[];
 }
 
+export const PARENT_PANE_ENV = "PI_HERDR_SUBAGENTS_PARENT_PANE_ID";
+
+export function childEnvironment(taskDirectory: string, environment: NodeJS.ProcessEnv = process.env): Record<string, string> {
+	const parentPaneId = environment.HERDR_PANE_ID?.trim();
+	return {
+		PI_HERDR_SUBAGENTS_CHILD: "1",
+		PI_HERDR_SUBAGENTS_TASK_DIR: taskDirectory,
+		...(parentPaneId ? { [PARENT_PANE_ENV]: parentPaneId } : {}),
+	};
+}
+
 export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): string[] {
 	const args = [
 		"--approve",

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

@@ -16,8 +16,8 @@ export const HerdrSubagentsParams = Type.Object({
 }, { additionalProperties: false });
 
 export const HerdrSubagentsControlParams = Type.Object({
-	action: StringEnum(["list", "respond", "history", "resume", "cleanup"] as const, { description: "Control operation to perform." }),
-	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, or cleanup." })),
+	action: StringEnum(["list", "respond", "history", "resume", "cancel", "cleanup"] as const, { description: "Control operation to perform." }),
+	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, cancel, or cleanup." })),
 	answer: Type.Optional(Type.String({ minLength: 1, description: "Answer sent to a blocked task when action is respond." })),
 	task: Type.Optional(Type.Integer({ minimum: 1, description: "One-based task number selected for respond or resume." })),
 	prompt: Type.Optional(Type.String({ minLength: 1, description: "Follow-up prompt used by resume." })),

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

@@ -23,7 +23,7 @@ async function closeRunTab(run: RunRecord, runFile: string, herdr: HerdrAutomati
 	}
 }
 
-export interface CancelActiveRunsOptions { reason?: string; owner?: OwnerIdentity; }
+export interface CancelActiveRunsOptions { reason?: string; owner?: OwnerIdentity; runId?: string; }
 
 export async function cancelActiveSubagentRuns(cwd: string, herdr: HerdrAutomation, options: CancelActiveRunsOptions = {}): Promise<CancellationResult> {
 	const reason = options.reason ?? "Parent Pi session closed.";
@@ -39,6 +39,7 @@ export async function cancelActiveSubagentRuns(cwd: string, herdr: HerdrAutomati
 			result.cleanupErrors.push(`Could not inspect Subagent run ${runFile}: ${error instanceof Error ? error.message : String(error)}`);
 			continue;
 		}
+		if (options.runId && run.id !== options.runId) continue;
 		if (!isActiveStatus(run.status)) continue;
 		if (options.owner?.sessionId && run.ownerSessionId !== options.owner.sessionId) continue;
 		const now = new Date().toISOString();

package/packages/herdr-subagents/src/run-pane-allocator.ts

@@ -3,6 +3,7 @@ import { writeJsonAtomic } from "./state.ts";
 import type { RunRecord } from "./records.ts";
 import { applyRunStatus } from "./run-status.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
+import { childEnvironment } from "./live-agent.ts";
 
 interface RunPaneAllocatorOptions {
 	herdr: HerdrAutomation;
@@ -31,7 +32,7 @@ export class RunPaneAllocator {
 		let paneId = "";
 		this.allocation = this.allocation.then(async () => {
 			const { herdr, run, runFile, signal } = this.options;
-			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: taskDirectory };
+			const env = childEnvironment(taskDirectory);
 			let anchorExists = Boolean(run.tabId && this.lastPaneId);
 			if (anchorExists && this.options.validateExistingPane) {
 				const survivingPaneIds: string[] = [];

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

@@ -3,7 +3,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
 import { ensureRuntimeIgnored } from "./history.ts";
-import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { childEnvironment, liveAgentName, promptLiveAgent } from "./live-agent.ts";
 import { writeJsonAtomic } from "./state.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import type { OwnerIdentity } from "./ownership.ts";
@@ -13,9 +13,6 @@ import { reportProtocolPrompt } from "./protocol.ts";
 import { applyRunStatus } from "./run-status.ts";
 import { isAbortError } from "./errors.ts";
 
-const CHILD_ENV = "PI_HERDR_SUBAGENTS_CHILD";
-const TASK_DIRECTORY_ENV = "PI_HERDR_SUBAGENTS_TASK_DIR";
-
 export type HerdrSubagentsDocument = PersistedDocument;
 export type HerdrSubagentsReport = PersistedReport;
 
@@ -168,10 +165,7 @@ export async function runHerdrSubagents(prompt: string, options: HerdrSubagentsO
 			workspaceId: process.env.HERDR_WORKSPACE_ID,
 			cwd,
 			label: `SA · ${label}`,
-			env: {
-				[CHILD_ENV]: "1",
-				[TASK_DIRECTORY_ENV]: taskDirectory,
-			},
+			env: childEnvironment(taskDirectory),
 			focus: false,
 			signal: options.signal,
 		});

package/packages/herdr-subagents/src/tab-cleanup.ts

@@ -2,6 +2,11 @@ import type { HerdrAutomation } from "./herdr.ts";
 import { readRunRecord, type RunRecord } from "./records.ts";
 import { writeJsonAtomic } from "./state.ts";
 
+function isMissingTabError(error: unknown): boolean {
+	const detail = error instanceof Error ? `${error.message}\n${(error as { stderr?: unknown }).stderr ?? ""}` : String(error);
+	return /tab[_ -]?not[_ -]?found|unknown tab/i.test(detail);
+}
+
 export async function cleanupRunTab(options: {
 	herdr: HerdrAutomation;
 	tabId: string;
@@ -52,17 +57,28 @@ export async function cleanupRunTab(options: {
 				.then(() => options.herdr.closeTab(options.tabId, options.signal))
 				.then(() => finishClosed(true))
 				.catch(async (error) => {
+					if (isMissingTabError(error)) { await finishClosed(true); return; }
 					if (!options.signal?.aborted) { await reportFailure(error, true); return; }
 					try {
 						await options.herdr.closeTab(options.tabId);
 						await finishClosed(true);
-					} catch (closeError) { await reportFailure(closeError, true); }
+					} catch (closeError) {
+						if (isMissingTabError(closeError)) { await finishClosed(true); return; }
+						await reportFailure(closeError, true);
+					}
 				});
 			return { deferred: true };
 		}
 		await options.herdr.closeTab(options.tabId, options.signal);
 		await finishClosed();
 	}
-	catch (error) { await reportFailure(error); throw error; }
+	catch (error) {
+		if (isMissingTabError(error)) {
+			await finishClosed();
+			return { deferred: false };
+		}
+		await reportFailure(error);
+		throw error;
+	}
 	return { deferred: false };
 }

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

@@ -1,4 +1,4 @@
-import type { HerdrAutomation } from "./herdr.ts";
+import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
 import { loadSubagentConfiguration, type ConfigurationPaths, type SubagentConfiguration } from "./config.ts";
 import { runHerdrSubagents, type HerdrSubagentsResult } from "./runner.ts";
 import { runHerdrSubagentsBatch, type BatchResult, type BatchTask } from "./batch-runner.ts";
@@ -6,6 +6,8 @@ import { respondToBlockedTask } from "./blocking.ts";
 import { cleanSubagentRun, historyText, listSubagentHistory, resumeHistoricalTask } from "./history.ts";
 import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "./validation.ts";
 import type { OwnerIdentity } from "./ownership.ts";
+import { cancelActiveSubagentRuns } from "./reconcile.ts";
+import { cancelQueuedRuns, loadQueuedRuns } from "./queued-runs.ts";
 
 export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
 
@@ -17,7 +19,7 @@ export interface HerdrSubagentsRunParams {
 }
 
 export interface HerdrSubagentsControlToolParams {
-	action: "list" | "respond" | "history" | "resume" | "cleanup";
+	action: "list" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	runId?: string;
 	answer?: string;
 	task?: number;
@@ -26,7 +28,7 @@ export interface HerdrSubagentsControlToolParams {
 
 /** Internal superset used by shared execution helpers. */
 export interface HerdrSubagentsToolParams {
-	action?: "list" | "respond" | "history" | "resume" | "cleanup";
+	action?: "list" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	prompt?: string;
 	agent?: string;
 	label?: string;
@@ -51,6 +53,7 @@ export interface HerdrSubagentsToolDependencies {
 	configurationPaths?: ConfigurationPaths;
 	owner?: OwnerIdentity;
 	runId?: string;
+	cancelRun?: (runId: string) => Promise<{ cancelled: boolean; queued?: boolean; cleanupErrors?: string[] }>;
 }
 
 export type HerdrSubagentsDetails = HerdrSubagentsResult & {
@@ -125,6 +128,29 @@ const actionHandlers = {
 			return errorResponse(text, { action: "cleanup", runId: params.runId, cleaned: false });
 		}
 	},
+	async cancel({ params, ctx, dependencies }: ToolExecutionContext) {
+		const runId = (params.runId as string).trim();
+		try {
+			let result: { cancelled: boolean; queued?: boolean; cleanupErrors?: string[] };
+			if (dependencies.cancelRun) result = await dependencies.cancelRun(runId);
+			else {
+				const reason = "Subagent run cancelled by user.";
+				const queued = (await loadQueuedRuns(ctx.cwd)).some((run) => run.runId === runId);
+				if (queued) {
+					await cancelQueuedRuns(ctx.cwd, [runId], { reason, owner: dependencies.owner });
+					result = { cancelled: true, queued: true };
+				} else {
+					const cancellation = await cancelActiveSubagentRuns(ctx.cwd, dependencies.herdr ?? new CliHerdrAutomation(), { reason, owner: dependencies.owner, runId });
+					result = { cancelled: cancellation.cancelledRuns > 0, cleanupErrors: cancellation.cleanupErrors };
+				}
+			}
+			const suffix = result.cleanupErrors?.length ? ` Cleanup warnings: ${result.cleanupErrors.join("; ")}` : "";
+			const text = result.cancelled ? `Cancelled Subagent run ${runId}.${suffix}` : `Subagent run '${runId}' is not active or queued.`;
+			return { content: [{ type: "text", text }], details: { action: "cancel", runId, ...result }, ...(result.cancelled ? {} : { isError: true }) };
+		} catch (error) {
+			return errorResponse(error instanceof Error ? error.message : String(error), { action: "cancel", runId, cancelled: false });
+		}
+	},
 	async resume({ params, signal, onUpdate, ctx, dependencies, discovery }: ToolExecutionContext) {
 		try {
 			const result = await resumeHistoricalTask(ctx.cwd, params.runId as string, params.task as number, (params.prompt as string).trim(), {

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

@@ -3,6 +3,7 @@ import type { HerdrSubagentsControlToolParams, HerdrSubagentsRunParams } from ".
 export const HERDR_ACTIONS = {
 	list: { allowed: ["action"], includeRunId: false },
 	history: { allowed: ["action"], includeRunId: false },
+	cancel: { allowed: ["action", "runId"], includeRunId: true },
 	cleanup: { allowed: ["action", "runId"], includeRunId: true },
 	respond: { allowed: ["action", "runId", "answer", "task"], includeRunId: true },
 	resume: { allowed: ["action", "runId", "task", "prompt"], includeRunId: true },
@@ -18,7 +19,7 @@ export function validateControlParams(params: HerdrSubagentsControlToolParams):
 	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 === "cancel" || params.action === "cleanup") && !params.runId?.trim()) return `runId is required for action '${params.action}'.`;
 	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

@@ -103,9 +103,23 @@ async function verifyPublicUiWiring() {
 		await background.tool.execute("second", { background: true, tasks: [{ name: "queued task", prompt: "two" }] }, undefined, undefined, { cwd, ui: background.ui });
 		if (background.widgetCalls !== activeWidgetCalls || !background.renderedLines.some((line) => line.includes("active task"))) throw new Error("queued background run replaced the active Fleet widget");
 		releaseFirst?.({ content: [{ type: "text", text: "done" }], details: { ...runningDetails, status: "completed" } });
-		await new Promise((resolve) => setTimeout(resolve, 10));
+			await new Promise((resolve) => setTimeout(resolve, 10));
+
+			let cancelledSignal: AbortSignal | undefined;
+			const cancellable = harness(async (params, signal, _onUpdate, _ctx, dependencies) => {
+				if (params.action === "cancel") {
+					const result = await dependencies.cancelRun(params.runId);
+					return { content: [{ type: "text", text: "cancelled" }], details: { action: "cancel", runId: params.runId, ...result } };
+				}
+				cancelledSignal = signal;
+				return await new Promise((_resolve, reject) => signal.addEventListener("abort", () => reject(signal.reason), { once: true }));
+			});
+			await startHarness(cancellable, cwd);
+			const cancellableRun = await cancellable.tool?.execute("cancellable", { background: true, tasks: [{ name: "cancel me", prompt: "wait" }] }, undefined, undefined, { cwd, ui: cancellable.ui });
+			const cancelled = await cancellable.controlTool?.execute("cancel", { action: "cancel", runId: cancellableRun.details.runId }, undefined, undefined, { cwd, ui: cancellable.ui });
+			if (!cancelledSignal?.aborted || cancelled?.details?.cancelled !== true) throw new Error("cancel control did not abort the selected live background run");
 
-		const rejectedCwd = join(cwd, "rejected-background");
+			const rejectedCwd = join(cwd, "rejected-background");
 		mkdirSync(rejectedCwd, { recursive: true });
 		const rejectedBackground = harness(async () => ({ content: [{ type: "text", text: "Unknown persona" }], details: { errorMessage: "Unknown persona" }, isError: true }));
 		await startHarness(rejectedBackground, rejectedCwd);

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

@@ -23,6 +23,7 @@ import { applyTaskStatus, isSettledRunStatus, projectTaskActivity, readTaskRecor
 import { RunPaneAllocator } from "../src/run-pane-allocator.ts";
 import { aggregateTaskStatus } from "../src/run-status.ts";
 import { isAbortError } from "../src/errors.ts";
+import registerSubagentReport from "../extensions/subagent-report.ts";
 
 let passed = 0;
 let failed = 0;
@@ -140,17 +141,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" },
@@ -239,6 +243,12 @@ try {
 	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();
@@ -304,7 +314,25 @@ try {
 	const outside = await runHerdrSubagents("hello", { cwd: root, herdr: unavailableHerdr });
 	check("Herdr is required", !outside.ok && outside.errorMessage?.includes("inside Herdr") && unavailableHerdr.calls.length === 0);
 
-	setEnv({ HERDR_ENV: "1", HERDR_WORKSPACE_ID: "w1", PI_HERDR_SUBAGENTS_PI_BINARY: "/definitely/missing/pi" });
+	setEnv({ HERDR_ENV: "1", HERDR_WORKSPACE_ID: "w1", HERDR_PANE_ID: "w1:p-parent", PI_HERDR_SUBAGENTS_PI_BINARY: "/definitely/missing/pi" });
+	const childCommands = new Map();
+	const childShortcuts = new Map();
+	const childEvents = new Map();
+	const childExecCalls = [];
+	const childStatuses = [];
+	registerSubagentReport({
+		registerTool() {},
+		registerCommand(name, options) { childCommands.set(name, options); },
+		registerShortcut(key, options) { childShortcuts.set(key, options); },
+		on(name, handler) { childEvents.set(name, handler); },
+		async exec(command, args) { childExecCalls.push([command, args]); return { stdout: "", stderr: "", code: 0, killed: false }; },
+	});
+	process.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID = "w1:p-parent";
+	const childContext = { ui: { notify() {}, setStatus(key, value) { childStatuses.push([key, value]); } } };
+	await childEvents.get("session_start")?.({}, childContext);
+	await childCommands.get("parent")?.handler("", childContext);
+	await childShortcuts.get("alt+p")?.handler(childContext);
+	check("child command and shortcut return to the exact parent Agent pane", childExecCalls.length === 2 && childExecCalls.every(([command, args]) => command === "herdr" && args.join(",") === "agent,focus,w1:p-parent") && childStatuses.some(([, value]) => value.includes("alt+p")));
 	const herdr = fakeHerdr();
 	const success = await runHerdrSubagents("Review authentication", {
 		cwd: root,
@@ -321,7 +349,7 @@ try {
 	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("child environment points at durable task and parent pane", createRequest.env.PI_HERDR_SUBAGENTS_CHILD === "1" && createRequest.env.PI_HERDR_SUBAGENTS_TASK_DIR.includes(join(".pi", "herdr-subagents", "runs")) && createRequest.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID === "w1:p-parent");
 	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];
 	check("prompt submitted through Herdr", promptRequest.prompt === "Review authentication" && promptRequest.target === startRequest.name);
@@ -430,14 +458,20 @@ 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();
@@ -551,6 +585,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"; });