@maxiaochao/pi-toolkit 0.10.7 → 0.10.8

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 2026-10-09 - v0.10.8
+
+- bundle worktree v0.2.0: add current-session worktree switching for users, Agents, and SDK Harnesses
+- Improve Scheduler with clear-all controls and a visible above-editor row for every active schedule, separate from the below-editor Herdr Fleet.
+- Bundle the Worktree Extension with `/worktree start`, the `enter_worktree` Agent Tool, and the structured Harness workspace-switch protocol.
+- Add the idempotent `pi-worktree prepare --json` machine interface so the CLI remains the single implementation for worktree creation and reuse.
+
 ## 2026-10-09 - v0.10.7
 
 - bundle scheduler v0.1.0: add session-scoped interval prompts with Agent and user controls

package/README.md

@@ -35,7 +35,7 @@ Restart Pi after updating. The `todo` tool and widget will no longer load. `pi u
 | [pi-codex-edit](packages/codex-edit/README.md) | Codex-harness `apply_patch` routing for selected GPT models | `pi install npm:@maxiaochao/pi-codex-edit` | `pi update npm:@maxiaochao/pi-codex-edit` |
 | [pi-herdr-subagents](packages/herdr-subagents/README.md) | Interactive Herdr Pi Agents with bounded concurrency, direct navigation, and recovery | `pi install npm:@maxiaochao/pi-herdr-subagents` | `pi update npm:@maxiaochao/pi-herdr-subagents` |
 | [pi-scheduler](packages/scheduler/README.md) | Session-scoped interval prompts with Agent and `/schedule` controls | `pi install npm:@maxiaochao/pi-scheduler` | `pi update npm:@maxiaochao/pi-scheduler` |
-| [pi-worktree](packages/worktree/README.md) | Worktree CLI, completion, installer, and agent skill | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` |
+| [pi-worktree](packages/worktree/README.md) | Worktree CLI, current-session switching Extension, and agent skill | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` |
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.7",
+  "version": "0.10.8",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
@@ -34,7 +34,8 @@
       "./extensions/btw/index.ts",
       "./packages/codex-edit/extensions/codex-edit.ts",
       "./packages/herdr-subagents/extensions/herdr-subagents.ts",
-      "./packages/scheduler/extensions/scheduler.ts"
+      "./packages/scheduler/extensions/scheduler.ts",
+      "./packages/worktree/extensions/worktree.ts"
     ],
     "skills": [
       "./skills",
@@ -58,7 +59,7 @@
   },
   "scripts": {
     "test": "node tests/package-layout.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/scheduler test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
-    "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts && pi -ne -e ./packages/scheduler/extensions/scheduler.ts",
+    "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts && pi -ne -e ./packages/scheduler/extensions/scheduler.ts && pi -ne -e ./packages/worktree/extensions/worktree.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,10 @@
+## Unreleased
+
+- Return a foreground concurrent batch as soon as one task fails, keep surviving siblings running under durable background ownership, and send exactly one final follow-up after the whole batch settles.
+- Release the dispatcher slot at foreground failure handoff so later batches start immediately, while detached work remains cancellable, participates in shutdown, and cannot clear a newer active run when it settles.
+- Preserve full-batch waiting for successful foreground runs and the immediate-return behavior of explicit background runs.
+- Join every started batch worker before resolving its run promise, including when another worker's final state persistence fails.
+
 ## 2026-10-09 - v0.4.3
 
 - add per-run status, neutral analyst persona, and tool-agnostic Agent Team protocol

package/packages/herdr-subagents/README.md

@@ -64,7 +64,9 @@ herdr_subagents({
 })
 ```
 
-`tasks` is always a non-empty array: one item is a single task and multiple items form a batch. Set `background: true` for either form to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
+`tasks` is always a non-empty array: one item is a single task and multiple items form a batch. Set `background: true` for either form to return a stable run ID immediately while the queue continues. The dispatcher starts batches FIFO, with one batch holding its active slot at a time; a failed foreground handoff releases that slot as described below. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
+
+A foreground concurrent batch normally waits for the whole batch. If any task fails while siblings are still running, the call immediately returns the stable `runId` and that failure's details, then durably continues the same batch in the background without cancelling its siblings. The handed-off batch releases its dispatcher slot immediately, so a later submission can start while its surviving tasks are still running. The detached batch remains cancellable and is still joined during session shutdown. Its final aggregate is delivered exactly once through the same follow-up notification used by an explicit background run.
 
 Background work normally relies on that terminal notification. When the user asks for progress or the parent must confirm a review gate before continuing, query only that run's compact snapshot:
 
@@ -96,7 +98,7 @@ Read-only tasks start FIFO up to the configured concurrency limit. A pane is cre
 
 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.
+Foreground calls wait until all children report completion or a request for input when no task fails. On the first task failure, they return early as described above while the surviving children continue. 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.
 
 ## Reports and records
 

package/packages/herdr-subagents/TESTING.md

@@ -12,6 +12,11 @@
 
 - Resolve package, global, and project personas and validate frontmatter/configuration, including the neutral read-only `analyst` persona.
 - Run foreground tasks and FIFO bounded-concurrency batches through an injectable Herdr boundary.
+- Simulate one fast failure beside a controlled slow success and verify the foreground call returns the stable run ID and failure before releasing the slow task, detaches caller cancellation without aborting that task, releases the dispatcher so the next batch starts before the slow task settles, removes durable queue state, and emits exactly one final follow-up.
+- Verify a detached dispatcher promise can settle normally after its successor starts without clearing or otherwise disturbing the successor's active slot, while blocked foreground runs retain their existing dispatcher ownership.
+- Let a detached run later block or be explicitly cancelled and verify the newer dispatcher owner remains intact and each detached run emits exactly one final notification.
+- Shut down the parent while a handed-off sibling is active and verify it is cancelled and joined, durable queue state is removed, and no stale follow-up is sent.
+- Verify all-success foreground batches still wait for every task and explicit `background: true` submissions still return immediately.
 - Verify all paths use interactive Agent start/prompt without print mode, shell injection, markers, or pane reuse.
 - Force write-capable batches to serial execution while allowing bounded read-only parallelism, including three concurrent `analyst` tasks with independent task-level models.
 - Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
@@ -25,4 +30,4 @@
 
 ## Latest baseline
 
-All 179 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 179 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases plus the extension-contract lifecycle simulations 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

@@ -195,9 +195,9 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerTool({
 		name: "herdr_subagents",
 		label: "Herdr Subagents",
-		description: "Run one or more ordered tasks in visible interactive Herdr Pi Agents. Use one tasks item for a single task. Independent read-only tasks may run concurrently; write-capable runs are serialized. Foreground calls block, while background calls return a run ID immediately. Complete results and Pi sessions stay in project-local records.",
+		description: "Run one or more ordered tasks in visible interactive Herdr Pi Agents. Use one tasks item for a single task. Independent read-only tasks may run concurrently; write-capable runs are serialized. Foreground calls wait for the batch unless a task fails, when the run continues in the background and returns its run ID immediately. Explicit background calls always return a run ID immediately. Complete results and Pi sessions stay in project-local records.",
 		promptSnippet: "Run focused work in visible Herdr subagents",
-		promptGuidelines: ["Call herdr_subagents_control with action=list once before the first execution. Submit an ordered tasks list; use one item for a single task and concurrency only for independent read-only tasks. Foreground calls block until the run settles; background calls return a run ID immediately."],
+		promptGuidelines: ["Call herdr_subagents_control with action=list once before the first execution. Submit an ordered tasks list; use one item for a single task and concurrency only for independent read-only tasks. Foreground calls wait for full success or blocking input, but return a run ID as soon as one task fails while surviving siblings continue in the background. Explicit background calls return a run ID immediately."],
 		parameters: HerdrSubagentsParams,
 		prepareArguments: normalizeHerdrSubagentsArguments,
 
@@ -205,35 +205,67 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 			const generation = sessionGeneration;
 			const runId = randomUUID();
 			const controller = new AbortController();
+			const foregroundController = new AbortController();
+			let foregroundAttached = !params.background;
+			const abortForeground = () => {
+				if (foregroundAttached && signal?.aborted) foregroundController.abort(signal.reason);
+			};
+			if (foregroundAttached) {
+				if (signal?.aborted) abortForeground();
+				else signal?.addEventListener("abort", abortForeground, { once: true });
+			}
 			runControllers.set(runId, controller);
-			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(!params.background && signal ? [signal] : [])]);
+			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(!params.background ? [foregroundController.signal] : [])]);
+			let resolveEarlyFailure: ((details: HerdrSubagentsBatchDetails) => void) | undefined;
+			const earlyFailure = new Promise<HerdrSubagentsBatchDetails>((resolve) => { resolveEarlyFailure = resolve; });
+			let failureObserved = false;
+			let runSettled = false;
 			const executeRun = async () => {
 				const result = await execute(params, runSignal, (update) => {
-				const details = update.details as HerdrSubagentsBatchDetails | undefined;
-				if (details?.activity) fleet.sync(details);
-				const updateText = update.content.find((item) => item.type === "text")?.text;
-				const updateDetails = update.details as { warning?: string };
-				if (updateDetails.warning || updateText?.includes("cleanup failed") || (params.background && updateText?.includes("appears stalled"))) ctx.ui.notify(updateDetails.warning ?? updateText ?? "Subagent warning", "warning");
-				if (!params.background) onUpdate?.(update);
+					const details = update.details as HerdrSubagentsBatchDetails | undefined;
+					if (details?.activity) fleet.sync(details);
+					const hasUnfinishedSibling = details?.activity?.some((task) => task.status === "queued" || task.status === "running");
+					if (!params.background && !failureObserved && details?.effectiveConcurrency > 1 && hasUnfinishedSibling && details.tasks?.some((task) => task.status === "failed")) {
+						failureObserved = true;
+						foregroundAttached = false;
+						signal?.removeEventListener("abort", abortForeground);
+						resolveEarlyFailure?.(details);
+					}
+					const updateText = update.content.find((item) => item.type === "text")?.text;
+					const updateDetails = update.details as { warning?: string };
+					if (updateDetails.warning || updateText?.includes("cleanup failed") || (!foregroundAttached && updateText?.includes("appears stalled"))) ctx.ui.notify(updateDetails.warning ?? updateText ?? "Subagent warning", "warning");
+					if (foregroundAttached) onUpdate?.(update);
 				}, ctx, { agentsDirectory: packageAgentsDir, owner: { sessionId: ownerSessionId, processId: process.pid }, runId });
 				fleet.sync(result.details);
 				return result;
 			};
 			if (params.background) await persistQueuedRun(ctx.cwd, runId, params, { sessionId: ownerSessionId, processId: process.pid });
 			const promise = dispatcher.submit(runId, async () => {
-				const result = await executeRun().finally(async () => { if (params.background) await removeQueuedRun(ctx.cwd, runId); });
-					const details = result.details as HerdrSubagentsBatchDetails;
-					fleet.setActive(details.status === "blocked" ? details : undefined);
-					if (fleet.active) {
-						dispatcher.retain(runId);
+				const result = await executeRun();
+				const details = result.details as HerdrSubagentsBatchDetails;
+				const ownsDispatcher = dispatcher.snapshot().activeRunId === runId;
+				if (ownsDispatcher) fleet.setActive(details.status === "blocked" ? details : undefined);
+				else if (details.status === "blocked") fleet.clearRun(runId);
+				if (ownsDispatcher && fleet.active) {
+					dispatcher.retain(runId);
 				}
 				return result;
 			});
 			runPromises.set(runId, promise);
 			inFlight.add(promise);
-			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(runId); runPromises.delete(runId); }).catch(() => undefined);
-			if (params.background) {
-				void promise.then((result) => {
+			void promise.finally(() => {
+				runSettled = true;
+				foregroundAttached = false;
+				signal?.removeEventListener("abort", abortForeground);
+				inFlight.delete(promise);
+				runControllers.delete(runId);
+				runPromises.delete(runId);
+			}).catch(() => undefined);
+			let backgroundLifecycleStarted = false;
+			const startBackgroundLifecycle = () => {
+				if (backgroundLifecycleStarted) return;
+				backgroundLifecycleStarted = true;
+				const lifecycle = promise.then((result) => {
 					if (generation !== sessionGeneration) return;
 					notifyRun(runId, result);
 					if (!fleet.active && !dispatcher.snapshot().activeRunId && dispatcher.snapshot().queuedRunIds.length === 0) fleet.render();
@@ -244,10 +276,42 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 						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" });
-				});
+				}).finally(() => removeQueuedRun(ctx.cwd, runId));
+				inFlight.add(lifecycle);
+				void lifecycle.finally(() => inFlight.delete(lifecycle)).catch(() => undefined);
+			};
+			if (params.background) {
+				startBackgroundLifecycle();
 				return { content: [{ type: "text" as const, text: `Subagent run queued: ${runId}` }], details: { runId, status: "queued", background: true } };
 			}
-			const result = await promise;
+			const foregroundOutcome = await Promise.race([
+				promise.then((result) => ({ kind: "settled" as const, result })),
+				earlyFailure.then((details) => ({ kind: "failed" as const, details })),
+			]);
+			if (foregroundOutcome.kind === "failed") {
+				try {
+					await persistQueuedRun(ctx.cwd, runId, params, { sessionId: ownerSessionId, processId: process.pid });
+				} catch (error) {
+					controller.abort(new Error("Could not persist failed foreground run for background continuation."));
+					await promise.catch(() => undefined);
+					await removeQueuedRun(ctx.cwd, runId).catch(() => undefined);
+					throw error;
+				}
+				if (runSettled) {
+					await removeQueuedRun(ctx.cwd, runId);
+					return promise;
+				}
+				dispatcher.detach(runId);
+				startBackgroundLifecycle();
+				const failedTask = foregroundOutcome.details.tasks.find((task) => task.status === "failed");
+				const failure = failedTask?.error ?? failedTask?.summary ?? "Unknown task failure.";
+				return {
+					content: [{ type: "text" as const, text: `Subagent run ${runId} continues in the background after ${failedTask?.name ?? "a task"} failed: ${failure}` }],
+					details: { ...foregroundOutcome.details, runId, background: true, earlyReturn: true, failedTask: failedTask ? { index: failedTask.index, name: failedTask.name, summary: failedTask.summary, ...(failedTask.error ? { error: failedTask.error } : {}) } : undefined },
+					isError: true,
+				};
+			}
+			const result = foregroundOutcome.result;
 			if (!fleet.active && !dispatcher.snapshot().activeRunId && dispatcher.snapshot().queuedRunIds.length === 0) fleet.resetSelection();
 			return result;
 		},

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

@@ -176,7 +176,9 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 				if (results[index]?.status === "blocked") return;
 			}
 		};
-		await Promise.all(Array.from({ length: effectiveConcurrency }, worker));
+		const workers = await Promise.allSettled(Array.from({ length: effectiveConcurrency }, worker));
+		const rejectedWorker = workers.find((worker): worker is PromiseRejectedResult => worker.status === "rejected");
+		if (rejectedWorker) throw rejectedWorker.reason;
 		if (options.signal?.aborted) {
 			for (let index = 0; index < tasks.length; index += 1) {
 				if (activity[index].status !== "queued") continue;

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

@@ -37,6 +37,13 @@ export class RunDispatcher {
 		this.retainedRunId = id;
 		this.changed();
 	}
+	detach(id: string): boolean {
+		if (this.activeRunId !== id || this.retainedRunId === id) return false;
+		this.activeRunId = undefined;
+		this.changed();
+		void this.drain();
+		return true;
+	}
 	release(id: string): boolean {
 		if (this.activeRunId !== id || this.retainedRunId !== id) return false;
 		this.retainedRunId = undefined;
@@ -71,7 +78,7 @@ export class RunDispatcher {
 		try { run.resolve(await run.execute()); }
 		catch (error) { run.reject(error); }
 		finally {
-			if (this.retainedRunId !== run.id) {
+			if (this.activeRunId === run.id && this.retainedRunId !== run.id) {
 				this.activeRunId = undefined;
 				this.changed();
 				void this.drain();

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

@@ -16,6 +16,8 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 	const editor = { kind: "editor" };
 	const focusedPanes: string[] = [];
 	const notifications: Array<{ message: string; level?: string }> = [];
+	const messages: Array<{ message: any; options: any }> = [];
+	const messageWaiters: Array<{ predicate: (message: any) => boolean; resolve: () => void }> = [];
 	const ui = {
 		setWidget(_id: string, widget: unknown) {
 			widgetCalls += 1;
@@ -32,7 +34,13 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 			if (definition.name === "herdr_subagents_control") controlTool = definition;
 		},
 		registerCommand(name: string) { commands.push(name); },
-		sendMessage() {},
+		sendMessage(message: any, options: any) {
+			messages.push({ message, options });
+			for (const waiter of messageWaiters.splice(0)) {
+				if (waiter.predicate(message)) waiter.resolve();
+				else messageWaiters.push(waiter);
+			}
+		},
 	};
 	registerHerdrSubagents(pi as never, {
 		herdr: { async focusPane(paneId: string) { focusedPanes.push(paneId); } } as never,
@@ -51,6 +59,11 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 		get renderedLines() { return renderedLines; },
 		focusedPanes,
 		notifications,
+		messages,
+		waitForMessage(predicate: (message: any) => boolean) {
+			if (messages.some(({ message }) => predicate(message))) return Promise.resolve();
+			return new Promise<void>((resolve) => messageWaiters.push({ predicate, resolve }));
+		},
 		ui,
 	};
 }
@@ -64,6 +77,188 @@ async function startHarness(instance: ReturnType<typeof harness>, cwd: string) {
 	});
 }
 
+function deferred<T>() {
+	let resolve!: (value: T) => void;
+	const promise = new Promise<T>((settle) => { resolve = settle; });
+	return { promise, resolve };
+}
+
+async function waitUntil(predicate: () => boolean, message: string) {
+	for (let attempt = 0; attempt < 100; attempt += 1) {
+		if (predicate()) return;
+		await new Promise<void>((resolve) => setImmediate(resolve));
+	}
+	throw new Error(message);
+}
+
+async function verifyForegroundFailureHandoff() {
+	const cwd = mkdtempSync(join(tmpdir(), "herdr-early-failure-"));
+	try {
+		const slow = deferred<void>();
+		let slowSignal: AbortSignal | undefined;
+		let secondStarted = false;
+		let callCount = 0;
+		const caller = new AbortController();
+		const failedTask = { index: 0, name: "fast failure", status: "failed", summary: "failed quickly", error: "boom", documents: [], paneId: "w1:p1", recordDirectory: "task-1", sessionFile: "task-1/session.jsonl" };
+		const slowTask = { index: 1, name: "slow success", status: "completed", summary: "finished slowly", documents: [], paneId: "w1:p2", recordDirectory: "task-2", sessionFile: "task-2/session.jsonl" };
+		const instance = harness(async (_params, signal, onUpdate, _ctx, dependencies) => {
+			callCount += 1;
+			if (callCount > 1) {
+				secondStarted = true;
+				return { content: [{ type: "text", text: "second done" }], details: { runId: dependencies.runId, label: "second", status: "completed", summary: "done", documents: [], tasks: [], activity: [] } };
+			}
+			slowSignal = signal;
+			onUpdate?.({
+				content: [{ type: "text", text: "1/2 tasks settled." }],
+				details: { runId: dependencies.runId, label: "handoff", status: "running", summary: "1/2 tasks settled.", documents: [], tasks: [failedTask], activity: [{ index: 0, name: failedTask.name, status: "failed" }, { index: 1, name: slowTask.name, status: "running" }], effectiveConcurrency: 2, requestedConcurrency: 2 },
+			});
+			queueMicrotask(() => caller.abort(new Error("foreground tool call ended")));
+			await slow.promise;
+			return { content: [{ type: "text", text: "1/2 tasks completed; 1 failed." }], details: { runId: dependencies.runId, label: "handoff", status: "partial", summary: "1/2 tasks completed; 1 failed.", documents: [], tasks: [failedTask, slowTask], activity: [{ index: 0, name: failedTask.name, status: "failed" }, { index: 1, name: slowTask.name, status: "completed" }], effectiveConcurrency: 2, requestedConcurrency: 2 }, isError: true };
+		});
+		await startHarness(instance, cwd);
+		const foreground = instance.tool?.execute("handoff", { concurrency: 2, tasks: [{ name: failedTask.name, prompt: "fail" }, { name: slowTask.name, prompt: "wait" }] }, caller.signal, undefined, { cwd, ui: instance.ui });
+		const early = await Promise.race([foreground, new Promise((_, reject) => setTimeout(() => reject(new Error("foreground did not return after the first task failed")), 100))]);
+		if (!early.details?.runId || early.details?.earlyReturn !== true || early.details?.background !== true || early.details?.failedTask?.error !== "boom" || !early.content?.[0]?.text.includes("boom")) throw new Error("early foreground result omitted the run ID or failure details");
+		if (slowSignal?.aborted) throw new Error("early foreground handoff cancelled the still-running sibling");
+		const queuedAfterHandoff = readdirSync(join(cwd, ".pi", "herdr-subagents", "queue")).filter((name) => name.endsWith(".json"));
+		if (queuedAfterHandoff.length !== 1) throw new Error("early foreground handoff was not persisted as background work");
+		const second = instance.tool?.execute("second", { background: true, tasks: [{ name: "second", prompt: "later" }] }, undefined, undefined, { cwd, ui: instance.ui });
+		await second;
+		await waitUntil(() => secondStarted, "dispatcher did not start the next batch after the failed foreground batch detached");
+		if (slowSignal?.aborted) throw new Error("starting the next batch cancelled the detached slow sibling");
+		const handoffNotified = instance.waitForMessage((message) => message.details?.runId === early.details.runId);
+		slow.resolve();
+		await handoffNotified;
+		if (slowSignal?.aborted) throw new Error("detached slow sibling was cancelled before it finished");
+		const handoffMessages = instance.messages.filter(({ message }) => message.details?.runId === early.details.runId);
+		if (handoffMessages.length !== 1 || handoffMessages[0].options?.deliverAs !== "followUp") throw new Error("handed-off run did not send exactly one final follow-up");
+		await waitUntil(() => !readdirSync(join(cwd, ".pi", "herdr-subagents", "queue")).some((name) => name.startsWith(early.details.runId)), "settled handed-off run left its durable queue record behind");
+
+		const blockedRoot = join(cwd, "blocked-handoff");
+		mkdirSync(blockedRoot, { recursive: true });
+		const becomeBlocked = deferred<void>();
+		const finishSuccessor = deferred<void>();
+		let blockedCalls = 0;
+		let successorStarted = false;
+		let thirdStarted = false;
+		const blockedTask = { index: 1, name: "needs input", status: "blocked", summary: "waiting for an answer", question: "Continue?", documents: [], paneId: "w1:p2", recordDirectory: "task-2", sessionFile: "task-2/session.jsonl" };
+		const blockedHandoff = harness(async (_params, _signal, onUpdate, _ctx, dependencies) => {
+			blockedCalls += 1;
+			if (blockedCalls === 2) {
+				successorStarted = true;
+				await finishSuccessor.promise;
+				return { content: [{ type: "text", text: "successor done" }], details: { runId: dependencies.runId, label: "successor", status: "completed", summary: "done", documents: [], tasks: [], activity: [] } };
+			}
+			if (blockedCalls === 3) {
+				thirdStarted = true;
+				return { content: [{ type: "text", text: "third done" }], details: { runId: dependencies.runId, label: "third", status: "completed", summary: "done", documents: [], tasks: [], activity: [] } };
+			}
+			onUpdate?.({
+				content: [{ type: "text", text: "1/2 tasks settled." }],
+				details: { runId: dependencies.runId, label: "blocks later", status: "running", summary: "1/2 tasks settled.", documents: [], tasks: [failedTask], activity: [{ index: 0, name: failedTask.name, status: "failed" }, { index: 1, name: blockedTask.name, status: "running" }], effectiveConcurrency: 2, requestedConcurrency: 2 },
+			});
+			await becomeBlocked.promise;
+			return { content: [{ type: "text", text: "run blocked" }], details: { runId: dependencies.runId, label: "blocks later", status: "blocked", summary: "waiting for input", documents: [], tasks: [failedTask, blockedTask], activity: [{ index: 0, name: failedTask.name, status: "failed" }, { index: 1, name: blockedTask.name, status: "blocked" }], effectiveConcurrency: 2, requestedConcurrency: 2 } };
+		});
+		await startHarness(blockedHandoff, blockedRoot);
+		const blockedEarly = await blockedHandoff.tool?.execute("blocks-later", { concurrency: 2, tasks: [{ name: failedTask.name, prompt: "fail" }, { name: blockedTask.name, prompt: "block" }] }, undefined, undefined, { cwd: blockedRoot, ui: blockedHandoff.ui });
+		await blockedHandoff.tool?.execute("successor", { background: true, tasks: [{ name: "successor", prompt: "wait" }] }, undefined, undefined, { cwd: blockedRoot, ui: blockedHandoff.ui });
+		await waitUntil(() => successorStarted, "successor did not start while detached run was still active");
+		const blockedNotified = blockedHandoff.waitForMessage((message) => message.details?.runId === blockedEarly.details.runId);
+		becomeBlocked.resolve();
+		await blockedNotified;
+		await blockedHandoff.tool?.execute("third", { background: true, tasks: [{ name: "third", prompt: "later" }] }, undefined, undefined, { cwd: blockedRoot, ui: blockedHandoff.ui });
+		await new Promise<void>((resolve) => setImmediate(resolve));
+		if (thirdStarted) throw new Error("detached blocked settlement cleared the newer active dispatcher slot");
+		if (blockedHandoff.messages.filter(({ message }) => message.details?.runId === blockedEarly.details.runId).length !== 1) throw new Error("detached run that later blocked did not notify exactly once");
+		finishSuccessor.resolve();
+		await waitUntil(() => thirdStarted, "queued run did not start after the newer active run settled");
+
+		const cancelRoot = join(cwd, "cancel-handoff");
+		mkdirSync(cancelRoot, { recursive: true });
+		let detachedSignal: AbortSignal | undefined;
+		const cancelledHandoff = 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 } };
+			}
+			detachedSignal = signal;
+			onUpdate?.({
+				content: [{ type: "text", text: "1/2 tasks settled." }],
+				details: { runId: dependencies.runId, label: "cancel detached", status: "running", summary: "1/2 tasks settled.", documents: [], tasks: [failedTask], activity: [{ index: 0, name: failedTask.name, status: "failed" }, { index: 1, name: slowTask.name, status: "running" }], effectiveConcurrency: 2, requestedConcurrency: 2 },
+			});
+			await new Promise<void>((_resolve, reject) => {
+				if (signal.aborted) reject(signal.reason);
+				else signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+			});
+		});
+		await startHarness(cancelledHandoff, cancelRoot);
+		const cancelEarly = await cancelledHandoff.tool?.execute("cancel-detached", { concurrency: 2, tasks: [{ name: failedTask.name, prompt: "fail" }, { name: slowTask.name, prompt: "wait" }] }, undefined, undefined, { cwd: cancelRoot, ui: cancelledHandoff.ui });
+		const cancelledNotice = cancelledHandoff.waitForMessage((message) => message.details?.runId === cancelEarly.details.runId);
+		const cancelResult = await cancelledHandoff.controlTool?.execute("cancel", { action: "cancel", runId: cancelEarly.details.runId }, undefined, undefined, { cwd: cancelRoot, ui: cancelledHandoff.ui });
+		await cancelledNotice;
+		if (!detachedSignal?.aborted || cancelResult?.details?.cancelled !== true) throw new Error("cancel did not abort the detached handed-off run");
+		if (cancelledHandoff.messages.filter(({ message }) => message.details?.runId === cancelEarly.details.runId).length !== 1) throw new Error("cancelled detached run did not notify exactly once");
+
+		const shutdownRoot = join(cwd, "shutdown-handoff");
+		mkdirSync(shutdownRoot, { recursive: true });
+		let shutdownSignal: AbortSignal | undefined;
+		const shutdownHandoff = harness(async (_params, signal, onUpdate, _ctx, dependencies) => {
+			shutdownSignal = signal;
+			onUpdate?.({
+				content: [{ type: "text", text: "1/2 tasks settled." }],
+				details: { runId: dependencies.runId, label: "shutdown", status: "running", summary: "1/2 tasks settled.", documents: [], tasks: [failedTask], activity: [{ index: 0, name: failedTask.name, status: "failed" }, { index: 1, name: slowTask.name, status: "running" }], effectiveConcurrency: 2, requestedConcurrency: 2 },
+			});
+			await new Promise<void>((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+			return { content: [{ type: "text", text: "cancelled" }], details: { runId: dependencies.runId, label: "shutdown", status: "cancelled", summary: "cancelled", documents: [], tasks: [failedTask], activity: [{ index: 0, name: failedTask.name, status: "failed" }, { index: 1, name: slowTask.name, status: "cancelled" }], effectiveConcurrency: 2, requestedConcurrency: 2 }, isError: true };
+		});
+		await startHarness(shutdownHandoff, shutdownRoot);
+		const shutdownEarly = await shutdownHandoff.tool?.execute("shutdown", { concurrency: 2, tasks: [{ name: failedTask.name, prompt: "fail" }, { name: slowTask.name, prompt: "wait" }] }, undefined, undefined, { cwd: shutdownRoot, ui: shutdownHandoff.ui });
+		await Promise.race([
+			shutdownHandoff.handlers.get("session_shutdown")?.({}, { cwd: shutdownRoot, ui: shutdownHandoff.ui }),
+			new Promise((_, reject) => setTimeout(() => reject(new Error("session shutdown leaked a handed-off run")), 100)),
+		]);
+		if (!shutdownSignal?.aborted) throw new Error("session shutdown did not abort the active handed-off sibling");
+		if (shutdownHandoff.messages.some(({ message }) => message.details?.runId === shutdownEarly.details.runId)) throw new Error("handed-off run notified after its parent session shut down");
+		const shutdownQueue = join(shutdownRoot, ".pi", "herdr-subagents", "queue");
+		if (existsSync(shutdownQueue) && readdirSync(shutdownQueue).some((name) => name.endsWith(".json"))) throw new Error("session shutdown left a handed-off queue record behind");
+
+		const successGate = deferred<void>();
+		const successStarted = deferred<void>();
+		const allSuccess = harness(async (_params, _signal, _onUpdate, _ctx, dependencies) => {
+			successStarted.resolve();
+			await successGate.promise;
+			return { content: [{ type: "text", text: "all done" }], details: { runId: dependencies.runId, label: "success", status: "completed", summary: "2/2 tasks completed.", documents: [], tasks: [], activity: [], effectiveConcurrency: 2, requestedConcurrency: 2 } };
+		});
+		await startHarness(allSuccess, cwd);
+		let successSettled = false;
+		const successPromise = allSuccess.tool?.execute("success", { concurrency: 2, tasks: [{ name: "one", prompt: "one" }, { name: "two", prompt: "two" }] }, undefined, undefined, { cwd, ui: allSuccess.ui }).then((result: any) => { successSettled = true; return result; });
+		await successStarted.promise;
+		if (successSettled) throw new Error("all-success foreground batch returned before the full batch settled");
+		successGate.resolve();
+		await successPromise;
+
+		const backgroundGate = deferred<void>();
+		const explicitBackground = harness(async (_params, _signal, _onUpdate, _ctx, dependencies) => {
+			await backgroundGate.promise;
+			return { content: [{ type: "text", text: "background done" }], details: { runId: dependencies.runId, label: "background", status: "completed", summary: "done", documents: [], tasks: [], activity: [], effectiveConcurrency: 1, requestedConcurrency: 1 } };
+		});
+		await startHarness(explicitBackground, cwd);
+		const queued = await Promise.race([
+			explicitBackground.tool?.execute("background", { background: true, tasks: [{ name: "background", prompt: "wait" }] }, undefined, undefined, { cwd, ui: explicitBackground.ui }),
+			new Promise((_, reject) => setTimeout(() => reject(new Error("explicit background run stopped returning immediately")), 100)),
+		]);
+		if (queued.details?.background !== true || queued.details?.status !== "queued") throw new Error("explicit background result contract regressed");
+		const backgroundNotified = explicitBackground.waitForMessage((message) => message.details?.runId === queued.details.runId);
+		backgroundGate.resolve();
+		await backgroundNotified;
+		if (explicitBackground.messages.filter(({ message }) => message.details?.runId === queued.details.runId).length !== 1) throw new Error("explicit background run did not send one final follow-up");
+	} finally {
+		rmSync(cwd, { recursive: true, force: true });
+	}
+}
+
 async function verifyPublicUiWiring() {
 	const cwd = mkdtempSync(join(tmpdir(), "herdr-extension-contract-"));
 	try {
@@ -194,6 +389,7 @@ try {
 	if (child.tool || child.commands.length || child.handlers.size) throw new Error("Subagents registered inside a child Agent");
 	delete process.env.PI_HERDR_SUBAGENTS_CHILD;
 	await verifyPublicUiWiring();
+	await verifyForegroundFailureHandoff();
 } finally {
 	if (originalHerdrEnv === undefined) delete process.env.HERDR_ENV;
 	else process.env.HERDR_ENV = originalHerdrEnv;
@@ -255,7 +451,7 @@ export default function (_pi: ExtensionAPI) {
 	if (!controlActions?.includes("status")) throw new Error("herdr_subagents_control action enum must include status");
 	if (!/status/.test(controlSchema.properties.runId.description)) throw new Error("control runId description must document status");
 	if (!/Use status for one run/.test(controlTool.description)) throw new Error("control tool description must distinguish status from history");
-	if (!/Foreground calls block/.test(tool.description) || !/background calls return a run ID immediately/.test(tool.description)) {
+	if (!/Foreground calls wait/.test(tool.description) || !/Explicit background calls always 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

@@ -614,8 +614,33 @@ try {
 	const retainedFirst = retainedDispatcher.submit("blocked-run", async () => { retainedStarts.push("blocked-run"); retainedDispatcher.retain("blocked-run"); return "blocked"; });
 	const retainedSecond = retainedDispatcher.submit("queued-run", async () => { retainedStarts.push("queued-run"); return "completed"; });
 	check("blocked run retains dispatcher ownership after its call returns", await retainedFirst === "blocked" && retainedDispatcher.snapshot().activeRunId === "blocked-run" && retainedStarts.join(",") === "blocked-run" && retainedDispatcher.snapshot().queuedRunIds.join(",") === "queued-run");
+	check("dispatcher does not detach a retained blocked run", retainedDispatcher.detach("blocked-run") === false);
 	retainedDispatcher.release("blocked-run");
 	check("respond settlement releases dispatcher ownership to the queued run", await retainedSecond === "completed" && retainedStarts.join(",") === "blocked-run,queued-run");
+	const detachedDispatcher = new RunDispatcher();
+	let settleDetached;
+	let settleSuccessor;
+	let detachedSettled = false;
+	const detachedStarts = [];
+	const detachedFirst = detachedDispatcher.submit("detached-run", async () => {
+		detachedStarts.push("detached-run");
+		await new Promise((resolve) => { settleDetached = resolve; });
+		detachedSettled = true;
+		return "detached";
+	});
+	const afterDetached = detachedDispatcher.submit("after-detach", async () => {
+		detachedStarts.push("after-detach");
+		await new Promise((resolve) => { settleSuccessor = resolve; });
+		return "next";
+	});
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const detached = detachedDispatcher.detach("detached-run");
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	check("dispatcher detaches an unsettled active run and starts its successor", detached && !detachedSettled && detachedStarts.join(",") === "detached-run,after-detach" && detachedDispatcher.snapshot().activeRunId === "after-detach");
+	settleDetached();
+	check("detached run still resolves normally without disturbing its active successor", await detachedFirst === "detached" && detachedDispatcher.snapshot().activeRunId === "after-detach");
+	settleSuccessor();
+	check("successor settles normally after detached predecessor", await afterDetached === "next" && detachedDispatcher.snapshot().activeRunId === undefined);
 	const backgroundId = "stable-background-id";
 	const stableHerdr = fakeHerdr();
 	const stable = await executeHerdrSubagents({ tasks: [{ name: "stable", prompt: "stable", agent: "explorer" }] }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: stableHerdr, runId: backgroundId });

package/packages/scheduler/CHANGELOG.md

@@ -1,3 +1,8 @@
+## Unreleased
+
+- Add `clear` to the Agent tool and `/schedule clear` for stopping every active schedule.
+- Replace the compact footer status with an above-editor multi-line widget that shows one row per schedule and coexists with the below-editor Herdr Fleet.
+
 ## 2026-10-09 - v0.1.0
 
 - add session-scoped interval prompts with Agent and user controls

package/packages/scheduler/README.md

@@ -25,6 +25,7 @@ schedule({ action: "add", every: "5m", prompt: "Check CI; report completion or f
 schedule({ action: "list" })
 schedule({ action: "trigger", id: "schedule-1" })
 schedule({ action: "cancel", id: "schedule-1" })
+schedule({ action: "clear" })
 ```
 
 ## User command
@@ -34,9 +35,10 @@ schedule({ action: "cancel", id: "schedule-1" })
 /schedule list
 /schedule trigger schedule-1
 /schedule cancel schedule-1
+/schedule clear
 ```
 
-Manual trigger queues one prompt and does not move the regular next time. The TUI status line shows the active count and next trigger.
+Manual trigger queues one prompt and does not move the regular next time. A multi-line widget above the editor shows one row per active schedule with its ID, interval, next trigger, pending state, and prompt. Herdr Fleet remains below the editor, so the two live displays do not compete for the same area or overwrite each other.
 
 ## Semantics and limits
 
@@ -44,7 +46,7 @@ Manual trigger queues one prompt and does not move the regular next time. The TU
 - Prompts use Pi `followUp`: an active agent turn finishes before the scheduled prompt runs.
 - At most one prompt per schedule remains pending; missed intervals coalesce instead of flooding the queue.
 - Schedules live only in the current session and are cleared on new/resume/fork/reload/quit.
-- Cancel stops future timer events. Pi cannot selectively withdraw a prompt already in its follow-up queue.
+- Cancel stops one schedule; clear stops all active schedules. Pi cannot selectively withdraw a prompt already in its follow-up queue.
 - Timing is best-effort, not real-time. Recursive `setTimeout` uses absolute target times to avoid cumulative drift.
 - Calendar expressions, time zones, persistence, process monitoring, and script notifications are intentionally out of scope.
 

package/packages/scheduler/TESTING.md

@@ -8,7 +8,7 @@ npm --prefix packages/scheduler run load-test
 npm pack ./packages/scheduler --dry-run
 ```
 
-The deterministic core test uses a fake clock to verify duration parsing, absolute-time cadence, timed triggering, missed-tick coalescing, manual triggering, dropped-follow-up release, and cancellation. The extension test verifies tool/command parity, manual follow-up delivery, message-specific pending acknowledgement, settled-run fallback cleanup, TUI status, duplicate suppression, and shutdown timer cleanup.
+The deterministic core test uses a fake clock to verify duration parsing, absolute-time cadence, timed triggering, missed-tick coalescing, manual triggering, dropped-follow-up release, single cancellation, and clear-all timer cleanup. The extension test verifies tool/command parity, manual follow-up delivery, message-specific pending acknowledgement, settled-run fallback cleanup, the above-editor multi-line widget, coexistence with the below-editor Herdr Fleet, duplicate suppression, clear, and shutdown timer cleanup.
 
 For a manual TUI check, run Pi with `-e ./packages/scheduler/extensions/scheduler.ts`, create a short schedule, confirm the status line appears, and verify the prompt starts only after the current turn settles.