@maxiaochao/pi-toolkit 0.10.20 → 0.10.22

package/packages/herdr-subagents/src/run-state.ts

@@ -0,0 +1,120 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isProcessAlive } from "./ownership.ts";
+import { readRunRecord, type RunRecord } from "./records.ts";
+import { writeJsonAtomic } from "./state.ts";
+
+interface LockOwner {
+	token: string;
+	processId: number;
+	createdAt: string;
+}
+
+export interface DirectoryLock {
+	directory: string;
+	token: string;
+	release(): Promise<void>;
+}
+
+const INITIALIZATION_STALE_MS = 30_000;
+const delay = (milliseconds: number, signal?: AbortSignal) => new Promise<void>((resolve, reject) => {
+	const onAbort = () => { clearTimeout(timer); reject(signal?.reason ?? new Error("Lock wait aborted.")); };
+	const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(); }, milliseconds);
+	if (signal?.aborted) onAbort();
+	else signal?.addEventListener("abort", onAbort, { once: true });
+});
+
+async function readOwner(directory: string): Promise<LockOwner | undefined> {
+	try {
+		const value = JSON.parse(await readFile(join(directory, "owner.json"), "utf8")) as Partial<LockOwner>;
+		if (typeof value.token === "string" && Number.isInteger(value.processId)) return { ...value, createdAt: typeof value.createdAt === "string" ? value.createdAt : new Date(0).toISOString() } as LockOwner;
+	} catch { /* An invalid/legacy lock is handled only after its initialization lease expires. */ }
+	return undefined;
+}
+
+async function reclaimIfStale(directory: string): Promise<boolean> {
+	const owner = await readOwner(directory);
+	if (owner && isProcessAlive(owner.processId)) return false;
+	let identity;
+	try { identity = await lstat(directory); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return true; throw error; }
+	// A missing owner is an explicit initialization state. Atomic publication below does
+	// not create it, but retain a lease for old/crashed lock directories.
+	if (!owner && Date.now() - identity.mtimeMs < INITIALIZATION_STALE_MS) return false;
+	const stale = `${directory}.stale-${randomUUID()}`;
+	// Revalidate both ownership and directory identity immediately before reclamation.
+	const latestOwner = await readOwner(directory);
+	if (latestOwner && isProcessAlive(latestOwner.processId)) return false;
+	let latestIdentity;
+	try { latestIdentity = await lstat(directory); }
+	catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return true; throw error; }
+	if (latestIdentity.dev !== identity.dev || latestIdentity.ino !== identity.ino) return true;
+	try { await rename(directory, stale); }
+	catch (error) {
+		if (["ENOENT", "ENOTEMPTY", "EEXIST"].includes(String((error as NodeJS.ErrnoException).code))) return true;
+		throw error;
+	}
+	await rm(stale, { recursive: true, force: true });
+	return true;
+}
+
+export async function acquireDirectoryLock(directory: string, options: { wait: boolean; signal?: AbortSignal; contentionMessage?: string; beforePublish?: () => void | Promise<void> }): Promise<DirectoryLock> {
+	const token = randomUUID();
+	const owner: LockOwner = { token, processId: process.pid, createdAt: new Date().toISOString() };
+	for (;;) {
+		const prepared = `${directory}.initializing-${token}`;
+		await mkdir(prepared, { mode: 0o700 });
+		try {
+			await writeJsonAtomic(join(prepared, "owner.json"), owner);
+			await options.beforePublish?.();
+			try { await rename(prepared, directory); }
+			catch (error) {
+				if (!["EEXIST", "ENOTEMPTY"].includes(String((error as NodeJS.ErrnoException).code))) throw error;
+				await rm(prepared, { recursive: true, force: true });
+				if (await reclaimIfStale(directory)) continue;
+				if (!options.wait) throw new Error(options.contentionMessage ?? `Lock is already held: ${directory}`);
+				await delay(10, options.signal);
+				continue;
+			}
+			return {
+				directory,
+				token,
+				async release() {
+					if ((await readOwner(directory))?.token !== token) return;
+					const released = `${directory}.released-${token}`;
+					try { await rename(directory, released); }
+					catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; throw error; }
+					// Delete only the detached inode; a contender may safely publish the next
+					// generation at the canonical path immediately after the rename.
+					await rm(released, { recursive: true, force: true });
+				}, 
+			};
+		} catch (error) {
+			await rm(prepared, { recursive: true, force: true });
+			throw error;
+		}
+	}
+}
+
+/** Only the holder of this lock may start a run's queued tasks. */
+export function queueLockPath(runDirectory: string): string { return join(runDirectory, ".queue.lock"); }
+
+/** Replaces a long-lived in-memory copy with the record observed under the lock, including removals. */
+export function adoptRecord<T extends object>(target: T, latest: T): T {
+	const mutable = target as unknown as Record<string, unknown>;
+	for (const key of Object.keys(mutable)) if (!(key in latest)) delete mutable[key];
+	return Object.assign(target, latest);
+}
+
+export async function withRunStateLock<T>(runFile: string, signal: AbortSignal | undefined, mutate: (run: RunRecord) => T | Promise<T>): Promise<T> {
+	const lock = await acquireDirectoryLock(join(dirname(runFile), ".state.lock"), { wait: true, signal });
+	try {
+		const run = await readRunRecord(runFile);
+		const result = await mutate(run);
+		await writeJsonAtomic(runFile, run);
+		return result;
+	} finally {
+		await lock.release();
+	}
+}

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

@@ -2,7 +2,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { loadQueuedRuns } from "./queued-runs.ts";
 import { isSettledRunStatus, readReport, readRunRecord, readTaskRecord, type RunStatus, type TaskStatus } from "./records.ts";
-import { findRunDirectory } from "./run-locator.ts";
+import { findRunDirectory, resolveRunIdReference } from "./run-locator.ts";
 
 export interface RunStatusTask {
 	order: number;
@@ -70,9 +70,14 @@ async function loadDurableStatus(cwd: string, runId: string): Promise<RunStatusS
 }
 
 export async function getSubagentRunStatus(cwd: string, runId: string): Promise<RunStatusSnapshot | undefined> {
+	const queuedRuns = await loadQueuedRuns(cwd);
 	const durable = await loadDurableStatus(cwd, runId);
-	if (durable) return durable;
-	const queued = (await loadQueuedRuns(cwd)).find((candidate) => candidate.runId === runId);
+	if (durable) {
+		resolveRunIdReference(runId, [durable.runId, ...queuedRuns.map((candidate) => candidate.runId)]);
+		return durable;
+	}
+	const queuedId = resolveRunIdReference(runId, queuedRuns.map((candidate) => candidate.runId));
+	const queued = queuedRuns.find((candidate) => candidate.runId === queuedId);
 	if (!queued) return undefined;
 	return {
 		runId: queued.runId,

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

@@ -1,6 +1,6 @@
 import type { HerdrAutomation } from "./herdr.ts";
-import { readRunRecord, type RunRecord } from "./records.ts";
-import { writeJsonAtomic } from "./state.ts";
+import { type RunRecord } from "./records.ts";
+import { adoptRecord, withRunStateLock } from "./run-state.ts";
 
 function isMissingTabError(error: unknown): boolean {
 	const detail = error instanceof Error ? `${error.message}\n${(error as { stderr?: unknown }).stderr ?? ""}` : String(error);
@@ -18,17 +18,16 @@ export async function cleanupRunTab(options: {
 	errorPrefix?: string;
 }): Promise<{ deferred: boolean }> {
 	const mergeLatest = async (update: (run: RunRecord) => void | Promise<void>, requirePending = false, clearPending = true) => {
-		const latest = await readRunRecord(options.runFile);
-		if (requirePending && !latest.cleanupPendingTabIds?.includes(options.tabId)) return;
-		if (clearPending) {
-			latest.cleanupPendingTabIds = latest.cleanupPendingTabIds?.filter((tabId) => tabId !== options.tabId);
-			if (!latest.cleanupPendingTabIds?.length) delete latest.cleanupPendingTabIds;
-		}
-		await update(latest);
-		await writeJsonAtomic(options.runFile, latest);
-		const mutableRecord = options.runRecord as unknown as Record<string, unknown>;
-		for (const key of Object.keys(mutableRecord)) if (!(key in latest)) delete mutableRecord[key];
-		Object.assign(options.runRecord, latest);
+		const latest = await withRunStateLock(options.runFile, options.signal, async (run) => {
+			if (requirePending && !run.cleanupPendingTabIds?.includes(options.tabId)) return run;
+			if (clearPending) {
+				run.cleanupPendingTabIds = run.cleanupPendingTabIds?.filter((tabId) => tabId !== options.tabId);
+				if (!run.cleanupPendingTabIds?.length) delete run.cleanupPendingTabIds;
+			}
+			await update(run);
+			return run;
+		});
+		adoptRecord(options.runRecord, latest);
 	};
 	const reportFailure = async (error: unknown, requirePending = false) => {
 		const detail = error instanceof Error ? error.message : String(error);
@@ -51,9 +50,10 @@ export async function cleanupRunTab(options: {
 			return { deferred: false };
 		}
 		if (await options.herdr.isTabFocused(options.tabId, options.signal)) {
-			const latest = await readRunRecord(options.runFile);
-			latest.cleanupPendingTabIds = [...new Set([...(latest.cleanupPendingTabIds ?? []), options.tabId])];
-			await writeJsonAtomic(options.runFile, latest);
+			const latest = await withRunStateLock(options.runFile, options.signal, (run) => {
+				run.cleanupPendingTabIds = [...new Set([...(run.cleanupPendingTabIds ?? []), options.tabId])];
+				return run;
+			});
 			Object.assign(options.runRecord, latest);
 			void options.herdr.waitForTabUnfocused(options.tabId, options.signal)
 				.then(() => options.herdr.closeTab(options.tabId, options.signal))

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

@@ -1,6 +1,5 @@
 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";
 import { respondToBlockedTask } from "./blocking.ts";
 import { cleanSubagentRun, historyText, listSubagentHistory, resumeHistoricalTask } from "./history.ts";
@@ -31,9 +30,7 @@ export interface HerdrSubagentsControlToolParams {
 export interface HerdrSubagentsToolParams {
 	action?: "list" | "status" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	prompt?: string;
-	agent?: string;
 	label?: string;
-	model?: string;
 	tasks?: HerdrSubagentsTaskParams[];
 	concurrency?: number;
 	background?: boolean;
@@ -57,13 +54,6 @@ export interface HerdrSubagentsToolDependencies {
 	cancelRun?: (runId: string) => Promise<{ cancelled: boolean; queued?: boolean; cleanupErrors?: string[] }>;
 }
 
-export type HerdrSubagentsDetails = HerdrSubagentsResult & {
-	agent: string;
-	description: string;
-	prompt: string;
-	personaPath: string;
-};
-
 export type HerdrSubagentsBatchDetails = BatchResult & { prompts: string[] };
 
 type ToolResponse = {
@@ -91,14 +81,6 @@ export function listText(discovery: SubagentConfiguration): string {
 	return lines.join("\n");
 }
 
-function summaryText(result: HerdrSubagentsResult): string {
-	if (result.ok) return result.output;
-	const lines = [result.summary];
-	if (result.errorMessage) lines.push(`Error: ${result.errorMessage}`);
-	if (result.recordDirectory) lines.push(`Task record: ${result.recordDirectory}`);
-	return lines.join("\n");
-}
-
 interface ToolExecutionContext {
 	params: HerdrSubagentsToolParams;
 	signal?: AbortSignal;
@@ -131,17 +113,20 @@ const actionHandlers = {
 	},
 	async cleanup({ params, ctx }: ToolExecutionContext) {
 		try {
-			const cleaned = await cleanSubagentRun(ctx.cwd, params.runId as string);
-			const text = cleaned ? `Removed Subagent run ${params.runId}.` : `Unknown Subagent run '${params.runId}'.`;
-			return { content: [{ type: "text", text }], details: { action: "cleanup", runId: params.runId, cleaned }, ...(cleaned ? {} : { isError: true }) };
+			const requestedRunId = params.runId as string;
+			const runId = (await getSubagentRunStatus(ctx.cwd, requestedRunId))?.runId ?? requestedRunId;
+			const cleaned = await cleanSubagentRun(ctx.cwd, runId);
+			const text = cleaned ? `Removed Subagent run ${runId}.` : `Unknown Subagent run '${requestedRunId}'.`;
+			return { content: [{ type: "text", text }], details: { action: "cleanup", runId, cleaned }, ...(cleaned ? {} : { isError: true }) };
 		} catch (error) {
 			const text = error instanceof Error ? error.message : String(error);
 			return errorResponse(text, { action: "cleanup", runId: params.runId, cleaned: false });
 		}
 	},
 	async cancel({ params, ctx, dependencies }: ToolExecutionContext) {
-		const runId = (params.runId as string).trim();
+		const requestedRunId = (params.runId as string).trim();
 		try {
+			const runId = (await getSubagentRunStatus(ctx.cwd, requestedRunId))?.runId ?? requestedRunId;
 			let result: { cancelled: boolean; queued?: boolean; cleanupErrors?: string[] };
 			if (dependencies.cancelRun) result = await dependencies.cancelRun(runId);
 			else {
@@ -159,7 +144,7 @@ const actionHandlers = {
 			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 });
+			return errorResponse(error instanceof Error ? error.message : String(error), { action: "cancel", runId: requestedRunId, cancelled: false });
 		}
 	},
 	async resume({ params, signal, onUpdate, ctx, dependencies, discovery }: ToolExecutionContext) {
@@ -176,14 +161,15 @@ const actionHandlers = {
 	async respond({ params, signal, onUpdate, ctx, dependencies }: ToolExecutionContext) {
 		try {
 			const result = await respondToBlockedTask(ctx.cwd, (params.runId as string).trim(), (params.answer as string).trim(), {
-				herdr: dependencies.herdr, taskNumber: params.task, signal, owner: dependencies.owner,
+				herdr: dependencies.herdr, taskNumber: params.task as number, signal, owner: dependencies.owner,
 				onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: partial }),
 				onStalled: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, stalled: true } }),
 				onWarning: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, warning: text } }),
 				onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, cleanupError: text } }),
 			});
-			const text = [result.summary, ...(result.question ? [`Question: ${result.question}`] : []), ...result.documents.map((document) => `${document.description}: ${document.path}`)].join("\n");
-			return { content: [{ type: "text", text }], details: result, ...(result.status === "failed" || result.status === "partial" || result.status === "cancelled" ? { isError: true } : {}) };
+			const blockedControl = result.status === "blocked" ? { allowedActions: ["respond", "cancel"] as const } : {};
+			const text = [result.summary, ...(result.question ? [`Question: ${result.question}`] : []), ...(result.status === "blocked" ? [`Run ID: ${result.runId}`, `Answer with herdr_subagents_control({ action: "respond", runId: "${result.runId}", answer: "..." }) or cancel this run.`] : []), ...result.documents.map((document) => `${document.description}: ${document.path}`)].join("\n");
+			return { content: [{ type: "text", text }], details: { ...result, ...blockedControl }, ...(result.status === "failed" || result.status === "partial" || result.status === "cancelled" ? { isError: true } : {}) };
 		} catch (error) { return errorResponse(error instanceof Error ? error.message : String(error)); }
 	},
 	async list({ discovery }: ToolExecutionContext) {
@@ -215,9 +201,10 @@ async function executeBatch({ params, signal, onUpdate, ctx, dependencies, disco
 			onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: { ...partial, prompts: tasks.map((task) => task.prompt) } }),
 		});
 		const lines = [result.summary, ...result.tasks.map((task) => `- ${task.name}: ${task.status} — ${task.summary}`)];
+		if (result.status === "blocked") lines.push("", `Run ID: ${result.runId}`, `Answer with herdr_subagents_control({ action: "respond", runId: "${result.runId}", answer: "..." }) or cancel this run before starting another foreground run.`);
 		if (result.documents.length) lines.push("", "Documents:", ...result.documents.map((document) => `- ${document.description}: ${document.path}`));
 		const isError = result.status === "failed" || result.status === "partial" || result.status === "cancelled";
-		return { content: [{ type: "text", text: lines.join("\n") }], details: { ...result, prompts: tasks.map((task) => task.prompt) }, ...(isError ? { isError: true } : {}) };
+		return { content: [{ type: "text", text: lines.join("\n") }], details: { ...result, prompts: tasks.map((task) => task.prompt), ...(result.status === "blocked" ? { allowedActions: ["respond", "cancel"] } : {}) }, ...(isError ? { isError: true } : {}) };
 	} catch (error) {
 		const text = error instanceof Error ? error.message : String(error);
 		const diagnostic = error as { recordDirectory?: string; runId?: string };
@@ -225,37 +212,6 @@ async function executeBatch({ params, signal, onUpdate, ctx, dependencies, disco
 	}
 }
 
-async function executeSingle({ params, signal, onUpdate, ctx, dependencies, discovery }: ToolExecutionContext): Promise<ToolResponse> {
-	const prompt = params.prompt as string;
-	const selectedName = params.agent?.trim() || "worker";
-	const persona = discovery.personas.find((agent) => agent.name === selectedName);
-	if (!persona) return errorResponse(`Unknown persona '${selectedName}'.\n\n${listText(discovery)}`);
-	const explicitModel = params.model?.trim();
-	const selectedModel = explicitModel || persona.model || modelId(ctx);
-	const selectedThinking = persona.thinking ?? (!explicitModel && persona.modelSource === "parent session" ? ctx.thinkingLevel : undefined);
-	const details = (result: HerdrSubagentsResult): HerdrSubagentsDetails => ({ ...result, agent: persona.name, description: persona.description, prompt, personaPath: persona.filePath });
-	const result = await runHerdrSubagents(prompt, {
-		agent: persona.name,
-		label: params.label,
-		...(selectedModel ? { model: selectedModel } : {}),
-		...(selectedThinking ? { thinking: selectedThinking } : {}),
-		...(persona.tools ? { tools: persona.tools } : {}),
-		skills: persona.skills,
-		access: persona.access,
-		owner: dependencies.owner,
-		systemPrompt: persona.systemPrompt,
-		cwd: ctx.cwd,
-		signal,
-		herdr: dependencies.herdr,
-		stalledWarningSeconds: discovery.settings.stalledWarningSeconds,
-		onStalled: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { status: "running", stalled: true } }),
-		onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { status: "warning", cleanupError: text } }),
-		onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: details(partial) }),
-	});
-	const isError = result.status === "failed" || result.status === "cancelled";
-	return { content: [{ type: "text", text: summaryText(result) }], details: details(result), ...(isError ? { isError: true } : {}) };
-}
-
 export async function executeHerdrSubagents(
 	params: HerdrSubagentsRunParams | HerdrSubagentsToolParams,
 	signal: AbortSignal | undefined,
@@ -264,10 +220,6 @@ export async function executeHerdrSubagents(
 	dependencies: HerdrSubagentsToolDependencies,
 ): Promise<ToolResponse> {
 	if (params.action) return executeHerdrSubagentsControl(params as HerdrSubagentsControlToolParams, signal, onUpdate, ctx, dependencies);
-	if (params.prompt && !params.tasks) {
-		const discovery = loadSubagentConfiguration(ctx.cwd, dependencies.agentsDirectory, modelId(ctx), dependencies.configurationPaths);
-		return executeSingle({ params, signal, onUpdate, ctx, dependencies, discovery });
-	}
 	const runParams = params as HerdrSubagentsRunParams;
 	const validationError = validateRunParams(runParams);
 	if (validationError) return { content: [{ type: "text", text: validationError }], details: { errorMessage: validationError }, isError: true };

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

@@ -21,7 +21,7 @@ export function validateControlParams(params: HerdrSubagentsControlToolParams):
 	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 === "status" || 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 === "respond" && (!params.runId?.trim() || !params.answer?.trim() || !params.task)) return "runId, answer, and task 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

@@ -240,6 +240,81 @@ async function verifyForegroundFailureHandoff() {
 		await successPromise;
 
 		const backgroundGate = deferred<void>();
+		const queuedCancellationRoot = join(cwd, "queued-cancellation");
+		mkdirSync(queuedCancellationRoot, { recursive: true });
+		const activeGate = deferred<void>();
+		let queuedCancellationCalls = 0;
+		const queuedCancellation = harness(async (_params, _signal, _onUpdate, _ctx, dependencies) => {
+			queuedCancellationCalls += 1;
+			await activeGate.promise;
+			return { content: [{ type: "text", text: "done" }], details: { runId: dependencies.runId, label: "active", status: "completed", summary: "done", documents: [], tasks: [], activity: [], effectiveConcurrency: 1, requestedConcurrency: 1 } };
+		});
+		await startHarness(queuedCancellation, queuedCancellationRoot);
+		const activeBackground = await queuedCancellation.tool?.execute("active", { background: true, tasks: [{ name: "active", prompt: "wait" }] }, undefined, undefined, { cwd: queuedCancellationRoot, ui: queuedCancellation.ui });
+		await waitUntil(() => queuedCancellationCalls === 1, "active background run did not start");
+		const queuedCaller = new AbortController();
+		const queuedForeground = queuedCancellation.tool?.execute("queued", { tasks: [{ name: "queued", prompt: "later" }] }, queuedCaller.signal, undefined, { cwd: queuedCancellationRoot, ui: queuedCancellation.ui });
+		await new Promise<void>((resolve) => setImmediate(resolve));
+		queuedCaller.abort(new Error("foreground tool call cancelled"));
+		const queuedCancellationError = await Promise.race([
+			queuedForeground.then(() => "resolved", (error: Error) => error.message),
+			new Promise<string>((_, reject) => setTimeout(() => reject(new Error("queued foreground call ignored cancellation")), 100)),
+		]);
+		if (queuedCancellationError !== "foreground tool call cancelled" || queuedCancellationCalls !== 1) throw new Error("extension did not remove a cancelled foreground run from the dispatcher queue");
+		const activeNotification = queuedCancellation.waitForMessage((message) => message.details?.runId === activeBackground.details.runId);
+		activeGate.resolve();
+		await activeNotification;
+
+		const blockedOwnerRoot = join(cwd, "blocked-owner");
+		mkdirSync(blockedOwnerRoot, { recursive: true });
+		let blockedOwnerCalls = 0;
+		let blockedOwnerRunId = "";
+		let blockedSuccessorStarted = false;
+		const becomeRetained = deferred<void>();
+		const blockedOwner = harness(async (params, _signal, _onUpdate, _ctx, dependencies) => {
+			if (params.action === "respond") {
+				return { content: [{ type: "text", text: "answered" }], details: { runId: blockedOwnerRunId, label: "blocked owner", status: "completed", summary: "answered", documents: [], tasks: [], activity: [], effectiveConcurrency: 1, requestedConcurrency: 1 } };
+			}
+			blockedOwnerCalls += 1;
+			if (blockedOwnerCalls > 1) {
+				blockedSuccessorStarted = true;
+				return { content: [{ type: "text", text: "successor done" }], details: { runId: dependencies.runId, label: "successor", status: "completed", summary: "done", documents: [], tasks: [], activity: [], effectiveConcurrency: 1, requestedConcurrency: 1 } };
+			}
+			blockedOwnerRunId = dependencies.runId;
+			if (blockedOwnerCalls === 1) await becomeRetained.promise;
+			return {
+				content: [{ type: "text", text: "waiting for input" }],
+				details: {
+					runId: dependencies.runId, label: "blocked owner", status: "blocked", summary: "waiting for input", question: "Continue?", documents: [],
+					tasks: [blockedTask], activity: [{ index: 1, name: blockedTask.name, status: "blocked" }], effectiveConcurrency: 1, requestedConcurrency: 1,
+				},
+			};
+		});
+		await startHarness(blockedOwner, blockedOwnerRoot);
+		const ownerPromise = blockedOwner.tool?.execute("blocked-owner", { tasks: [{ name: blockedTask.name, prompt: "block" }] }, undefined, undefined, { cwd: blockedOwnerRoot, ui: blockedOwner.ui });
+		await waitUntil(() => blockedOwnerCalls === 1, "blocked owner did not start");
+		const queuedBeforeBlocked = blockedOwner.tool?.execute("queued-before-blocked", { tasks: [{ name: "queued", prompt: "later" }] }, undefined, undefined, { cwd: blockedOwnerRoot, ui: blockedOwner.ui });
+		await new Promise<void>((resolve) => setImmediate(resolve));
+		becomeRetained.resolve();
+		const ownerResult = await ownerPromise;
+		const retainedForeground = await Promise.race([
+			queuedBeforeBlocked,
+			new Promise((_, reject) => setTimeout(() => reject(new Error("foreground run queued before blocked transition remained stuck")), 100)),
+		]);
+		if (!retainedForeground.isError || retainedForeground.details?.blockingRunId !== ownerResult.details.runId || blockedOwnerCalls !== 1) throw new Error("blocked transition did not reject an already-queued foreground run");
+		const blockedForeground = await Promise.race([
+			blockedOwner.tool?.execute("blocked-successor", { tasks: [{ name: "successor", prompt: "later" }] }, undefined, undefined, { cwd: blockedOwnerRoot, ui: blockedOwner.ui }),
+			new Promise((_, reject) => setTimeout(() => reject(new Error("foreground run waited behind a blocked dispatcher owner")), 100)),
+		]);
+		if (!blockedForeground.isError || blockedForeground.details?.blockingRunId !== ownerResult.details.runId || !blockedForeground.content?.[0]?.text.includes(ownerResult.details.runId)) {
+			throw new Error("foreground run blocked by dispatcher omitted the blocking run ID");
+		}
+		const queuedBehindBlocked = await blockedOwner.tool?.execute("blocked-background", { background: true, tasks: [{ name: "background", prompt: "later" }] }, undefined, undefined, { cwd: blockedOwnerRoot, ui: blockedOwner.ui });
+		if (queuedBehindBlocked.details?.status !== "queued" || blockedOwnerCalls !== 1) throw new Error("background run did not remain queued behind the blocked dispatcher owner");
+		await blockedOwner.controlTool?.execute("respond-prefix", { action: "respond", runId: ownerResult.details.runId.slice(0, 8), task: 1, answer: "continue" }, undefined, undefined, { cwd: blockedOwnerRoot, ui: blockedOwner.ui });
+		await waitUntil(() => blockedSuccessorStarted, "responding through a run ID prefix did not release the blocked dispatcher owner");
+		await blockedOwner.handlers.get("session_shutdown")?.({}, { cwd: blockedOwnerRoot, ui: blockedOwner.ui });
+
 		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 } };
@@ -272,10 +347,10 @@ async function verifyPublicUiWiring() {
 		const responding = harness(async () => ({ content: [{ type: "text", text: "needs input" }], details: blockedDetails }));
 		await startHarness(responding, cwd);
 		if (!responding.tool) throw new Error("herdr_subagents was not registered for UI wiring test");
-		const renderedBlocked = responding.tool.renderResult({ content: [{ type: "text", text: "needs input" }], details: { agent: "explorer", status: "blocked", ok: false, summary: "Need input.", documents: [] } }, { isPartial: false }, { fg: (_color: string, text: string) => text, bold: (text: string) => text }).render(100).join("\n");
-		if (!renderedBlocked.includes("blocked") || renderedBlocked.includes("failed")) throw new Error("single-task blocked result did not render its authoritative status");
+		const renderedBlocked = responding.tool.renderResult({ content: [{ type: "text", text: "needs input" }], details: { label: "reviews", status: "blocked", effectiveConcurrency: 1, tasks: [{ index: 1, name: "second", status: "blocked", summary: "Need input." }] } }, { isPartial: false }, { fg: (_color: string, text: string) => text, bold: (text: string) => text }).render(100).join("\n");
+		if (!renderedBlocked.includes("blocked") || renderedBlocked.includes("failed")) throw new Error("blocked result did not render its authoritative status");
 		if (!responding.controlTool) throw new Error("herdr_subagents_control was not registered for UI wiring test");
-		await responding.controlTool.execute("call", { action: "respond", runId: "blocked-run", answer: "main" }, undefined, undefined, { cwd, ui: responding.ui });
+		await responding.controlTool.execute("call", { action: "respond", runId: "blocked-run", task: 2, answer: "main" }, undefined, undefined, { cwd, ui: responding.ui });
 		if (!responding.renderedLines.some((line) => line.includes("second") && line.includes("blocked"))) throw new Error("blocked response did not refresh Fleet rows");
 		if (!responding.terminalInput?.("\u001b[B")?.consume || !responding.terminalInput?.("\u001b[B")?.consume || !responding.terminalInput?.("\r")?.consume) throw new Error("Fleet terminal input was not consumed while selecting");
 		await new Promise((resolve) => setTimeout(resolve, 0));