pi-subagents 0.49.0 → 0.51.0

package/src/tui/fleet.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { getMarkdownTheme, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type MarkdownTheme } from "@earendil-works/pi-tui";
+import { snapshotExternalRuns, type ExternalRun } from "../api/external-runs.ts";
 import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
 import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../shared/formatters.ts";
 import { DIRS, type AsyncJobState, type Details, type FleetKeybindingAction, type FleetKeybindingsConfig, type ForegroundChildControl, type ForegroundResumeChild, type ForegroundResumeRun, type ForegroundRunControl, type SubagentState } from "../shared/types.ts";
@@ -13,13 +14,16 @@ import { listAsyncRuns, type AsyncRunSummary } from "../runs/background/async-st
 import { steerAsyncRun } from "../runs/foreground/async-steering-action.ts";
 import type { SteerDeliveryMode } from "../runs/background/control-channel.ts";
 import { stopAsyncRun } from "../runs/foreground/async-stop-action.ts";
+import { resolveWorkflowForegroundSteeringTarget, steerWorkflowForegroundTarget } from "../runs/foreground/workflow-foreground-steering.ts";
 import { contextModeBadge, contextModeLabel } from "../runs/shared/context-mode.ts";
 import { FLEET_STATUS_WIDGET_KEY } from "./fleet-status.ts";
 import { readFleetTranscript, renderFleetTranscript, type FleetTranscript } from "./fleet-transcript.ts";
 import { handleHerdrInspectorAction } from "../inspectors/herdr/actions.ts";
+import type { HerdrClient } from "../inspectors/herdr/client.ts";
 import { getLivePromptAudit, type LivePromptAudit, type PromptAuditView } from "../runs/foreground/prompt-audit.ts";
 
 const REFRESH_MS = 750;
+const MIN_REFRESH_MS = 250;
 const MAX_RECENT_ASYNC_RUNS = 20;
 const MAX_FLEET_HISTORY_CANDIDATES = 100;
 const TRANSCRIPT_LINES = 200;
@@ -77,6 +81,7 @@ export type FleetItem = (
 	| { key: string; kind: "foreground-active"; runId: string; index?: number; agent: string; state: "running"; updatedAt: number; control: ForegroundRunControl; activeChild?: ForegroundChildControl }
 	| { key: string; kind: "foreground-recent"; runId: string; index: number; agent: string; state: ForegroundResumeChild["status"]; updatedAt: number; run: ForegroundResumeRun; child: ForegroundResumeChild }
 	| { key: string; kind: "async"; runId: string; index?: number; agent: string; state: string; updatedAt: number; run: AsyncRunSummary; step?: AsyncStep }
+	| { key: string; kind: "external"; runId: string; agent: string; state: ExternalRun["state"]; updatedAt: number; run: ExternalRun }
 ) & { description?: string };
 
 export interface FleetSnapshot {
@@ -105,6 +110,7 @@ export interface FleetViewOptions {
 	fleetKeybindings?: FleetKeybindingsConfig;
 	actions?: FleetActionHandlers;
 	copyText?: (text: string) => Promise<void> | void;
+	herdrClient?: HerdrClient;
 }
 
 function belongsToCurrentSession(sessionId: string | undefined, currentSessionId: string | null): boolean {
@@ -186,8 +192,26 @@ export function collectFleetSnapshot(
 ): FleetSnapshot {
 	const items: FleetItem[] = [];
 	const activeForegroundIds = new Set<string>();
+	const trackedJobs = state.fleetJobs ?? state.asyncJobs;
+	const workflowParentIds = new Set([...trackedJobs.values()]
+		.filter((job) => job.mode === "workflow" && belongsToCurrentSession(job.sessionId, state.currentSessionId))
+		.map((job) => job.asyncId));
+	const workflowForegroundChildCounts = new Map<string, number>();
+	const liveWorkflowForegroundControls = new Set<ForegroundRunControl>();
+	for (const control of state.foregroundControls.values()) {
+		const activeChildCount = control.activeChildren?.size ?? 0;
+		if (!control.parentWorkflowRunId
+			|| !workflowParentIds.has(control.parentWorkflowRunId)
+			|| !belongsToCurrentSession(control.sessionId, state.currentSessionId)
+			|| !control.workflowSteeringDir
+			|| activeChildCount === 0) continue;
+		liveWorkflowForegroundControls.add(control);
+		workflowForegroundChildCounts.set(control.parentWorkflowRunId, (workflowForegroundChildCounts.get(control.parentWorkflowRunId) ?? 0) + activeChildCount);
+	}
 	for (const control of [...state.foregroundControls.values()].sort((left, right) => right.updatedAt - left.updatedAt)) {
 		activeForegroundIds.add(control.runId);
+		if (control.parentWorkflowRunId && workflowParentIds.has(control.parentWorkflowRunId)
+			&& ((workflowForegroundChildCounts.get(control.parentWorkflowRunId) ?? 0) <= 1 || !liveWorkflowForegroundControls.has(control))) continue;
 		if (control.activeChildren) {
 			for (const child of [...control.activeChildren.values()].sort((left, right) => left.index - right.index)) {
 				items.push({
@@ -222,7 +246,7 @@ export function collectFleetSnapshot(
 	try {
 		let runs: AsyncRunSummary[];
 		const descriptions = new Map<string, string>();
-		const tracked = [...(state.fleetJobs ?? state.asyncJobs).values()]
+		const tracked = [...trackedJobs.values()]
 			.filter((job) => belongsToCurrentSession(job.sessionId, state.currentSessionId));
 		const byUpdate = (left: AsyncJobState, right: AsyncJobState) => (right.updatedAt ?? right.startedAt ?? 0) - (left.updatedAt ?? left.startedAt ?? 0);
 		const active = tracked.filter((job) => job.status === "queued" || job.status === "running").sort(byUpdate);
@@ -255,6 +279,26 @@ export function collectFleetSnapshot(
 		error = cause instanceof Error ? cause.message : String(cause);
 	}
 
+	if (state.currentSessionId) {
+		try {
+			for (const run of snapshotExternalRuns(state.currentSessionId, { ignoreMalformed: true, onMalformedRecord: (message) => console.warn(`[pi-subagents] Removed ${message}`) })) {
+				items.push({
+					key: `external:${run.id}`,
+					kind: "external",
+					runId: run.id,
+					agent: run.label,
+					state: run.state,
+					updatedAt: run.updatedAt ?? run.endedAt ?? run.startedAt,
+					run,
+					...(run.currentAction ? { description: run.currentAction } : {}),
+				});
+			}
+		} catch (cause) {
+			const message = `Failed to inspect external jobs: ${cause instanceof Error ? cause.message : String(cause)}`;
+			error = error ? `${error}; ${message}` : message;
+		}
+	}
+
 	const recentForeground = [...(state.foregroundRuns?.values() ?? [])]
 		.filter((run) => belongsToCurrentSession(run.sessionId, state.currentSessionId) && !activeForegroundIds.has(run.runId))
 		.sort((left, right) => right.updatedAt - left.updatedAt);
@@ -276,6 +320,27 @@ export function collectFleetSnapshot(
 	return { items, ...(error ? { error } : {}) };
 }
 
+function visibleWorkflowParentKeyForForegroundKey(state: SubagentState, key: string, items: FleetItem[]): string | undefined {
+	for (const control of state.foregroundControls.values()) {
+		if (!control.parentWorkflowRunId) continue;
+		let matches = false;
+		if (control.activeChildren) {
+			for (const child of control.activeChildren.values()) {
+				if (`foreground-active:${control.runId}:${child.index}` === key) {
+					matches = true;
+					break;
+				}
+			}
+		} else {
+			matches = `foreground-active:${control.runId}:${control.currentIndex ?? 0}` === key;
+		}
+		if (!matches) continue;
+		const parentKey = `async:${control.parentWorkflowRunId}`;
+		return items.some((item) => item.key === parentKey) ? parentKey : undefined;
+	}
+	return undefined;
+}
+
 function statusGlyph(item: FleetItem, theme: Theme): string {
 	if (item.state === "running") return theme.fg("accent", "●");
 	if (item.state === "queued" || item.state === "pending") return theme.fg("muted", "◦");
@@ -424,10 +489,20 @@ function foregroundRecentDetail(item: Extract<FleetItem, { kind: "foreground-rec
 	return lines.filter((line): line is string => line !== undefined);
 }
 
-function asyncDetail(item: Extract<FleetItem, { kind: "async" }>): string[] {
+function externalElapsedEnd(run: ExternalRun): number {
+	const terminal = run.state !== "queued" && run.state !== "running";
+	return terminal ? (run.endedAt ?? run.updatedAt ?? Date.now()) : Date.now();
+}
+
+function asyncDetail(item: Extract<FleetItem, { kind: "async" }>, state: SubagentState): string[] {
 	const status = readStatus(item.run.asyncDir);
 	if (status) {
-		return formatAsyncRunTranscript(status, item.run.asyncDir, { index: item.index, lines: TRANSCRIPT_LINES }).split("\n");
+		const trackedJob = state.fleetJobs?.get(item.runId) ?? state.asyncJobs.get(item.runId);
+		return formatAsyncRunTranscript(status, item.run.asyncDir, {
+			index: item.index,
+			lines: TRANSCRIPT_LINES,
+			sessionRoots: uniquePaths([...(state.trustedSessionRoots ?? []), trackedJob?.sessionRoot]),
+		}).split("\n");
 	}
 	const outputPath = item.index !== undefined ? path.join(item.run.asyncDir, `output-${item.index}.log`) : undefined;
 	return [
@@ -444,13 +519,36 @@ function asyncDetail(item: Extract<FleetItem, { kind: "async" }>): string[] {
 	].filter((line): line is string => line !== undefined);
 }
 
+function externalDetail(item: Extract<FleetItem, { kind: "external" }>): string[] {
+	return [
+		`Run: ${item.runId}`,
+		"Source: external · display-only",
+		`Owner: ${item.run.source}`,
+		`State: ${item.state}`,
+		`Started: ${new Date(item.run.startedAt).toISOString()}`,
+		item.run.updatedAt !== undefined ? `Updated: ${new Date(item.run.updatedAt).toISOString()}` : undefined,
+		item.run.endedAt !== undefined ? `Ended: ${new Date(item.run.endedAt).toISOString()}` : undefined,
+		`Elapsed: ${formatDuration(Math.max(0, externalElapsedEnd(item.run) - item.run.startedAt))}`,
+		item.run.currentAction ? `Current action: ${item.run.currentAction}` : undefined,
+		item.run.reportPath ? `Report path: ${item.run.reportPath}` : undefined,
+		item.run.transcriptPath ? `Transcript path: ${item.run.transcriptPath}` : undefined,
+		"",
+		"Preview",
+		item.run.preview ?? "(no preview supplied)",
+		"",
+		"The owning extension controls execution, persistence, cancellation, and results.",
+	].filter((line): line is string => line !== undefined);
+}
+
 function detailLines(item: FleetItem | undefined, error: string | undefined, state: SubagentState): string[] {
-	if (!item) return [error ? `Fleet scan failed: ${error}` : "No current-session foreground or recent async children.", "", "New runs appear here automatically while this inspector remains open."];
+	if (!item) return [error ? `Fleet scan failed: ${error}` : "No current-session Fleet jobs.", "", "New jobs appear here automatically while this inspector remains open."];
 	const lines = item.kind === "foreground-active"
 		? foregroundActiveDetail(item, state)
 		: item.kind === "foreground-recent"
 			? foregroundRecentDetail(item, state)
-			: asyncDetail(item);
+			: item.kind === "external"
+				? externalDetail(item)
+				: asyncDetail(item, state);
 	if (error) lines.unshift(`Fleet scan warning: ${error}`, "");
 	return lines;
 }
@@ -478,6 +576,7 @@ function fleetArtifactsRoot(state: SubagentState, cwd: string): string {
 }
 
 function transcriptTarget(item: FleetItem, state: SubagentState): { path: string; trustedRoots: string[] } | undefined {
+	if (item.kind === "external") return undefined;
 	if (item.kind === "foreground-active") {
 		const artifactsRoot = fleetArtifactsRoot(state, item.control.cwd ?? state.baseCwd);
 		return {
@@ -522,10 +621,12 @@ function itemContext(item: FleetItem): string | undefined {
 }
 
 function itemMode(item: FleetItem): string {
+	if (item.kind === "external") return "display-only";
 	return item.kind === "foreground-active" ? item.control.mode : item.run.mode;
 }
 
 function itemSource(item: FleetItem): string {
+	if (item.kind === "external") return `external · ${item.run.source}`;
 	if (item.kind === "async") return "background";
 	return item.kind === "foreground-active" ? "foreground · live" : "foreground · recent";
 }
@@ -545,6 +646,8 @@ function itemStats(item: FleetItem): string[] {
 		model = formatModelThinking(item.child.model, item.child.thinking) || undefined;
 		tokens = item.child.tokens;
 		tools = item.child.toolCount;
+	} else if (item.kind === "external") {
+		durationMs = Math.max(0, externalElapsedEnd(item.run) - item.run.startedAt);
 	} else {
 		model = formatModelThinking(item.step?.model, item.step?.thinking) || undefined;
 		tokens = item.step?.tokens?.total ?? (item.index === undefined ? item.run.totalTokens?.total : undefined);
@@ -564,7 +667,7 @@ function itemStats(item: FleetItem): string[] {
 function structuredHeader(item: FleetItem, width: number, theme: Theme, conversationState: string, promptSummary?: string): string[] {
 	const lines: string[] = [];
 	lines.push(rightAligned(` ${statusGlyph(item, theme)} ${theme.bold(item.agent)}`, theme.fg("dim", item.state), width));
-	const child = item.index !== undefined ? ` · child ${item.index + 1}` : "";
+	const child = "index" in item && item.index !== undefined ? ` · child ${item.index + 1}` : "";
 	const context = itemContext(item);
 	const identity = `${itemSource(item)} · ${item.runId.slice(0, 8)}${child} · ${itemMode(item)}${context ? ` ${context}` : ""}`;
 	lines.push(`  ${theme.fg("dim", identity)}`);
@@ -629,7 +732,8 @@ export class SubagentFleetComponent implements Component {
 	private actionBusy = false;
 	private transcriptCache: FleetTranscriptCache | undefined;
 	private disposed = false;
-	private readonly timer: ReturnType<typeof setInterval>;
+	private refreshTimer: ReturnType<typeof setTimeout> | undefined;
+	private readonly refreshMs: number;
 	private readonly tui: FleetTui;
 	private readonly theme: Theme;
 	private readonly markdownTheme: MarkdownTheme;
@@ -652,20 +756,41 @@ export class SubagentFleetComponent implements Component {
 		this.done = done;
 		this.options = options;
 		this.keybindings = resolveFleetKeybindings(options.fleetKeybindings);
+		this.refreshMs = Math.max(MIN_REFRESH_MS, options.refreshMs ?? REFRESH_MS);
 		this.selectedKey = options.initialKey;
 		this.refresh();
-		this.timer = setInterval(() => {
+		this.scheduleRefresh();
+	}
+
+	private scheduleRefresh(): void {
+		if (this.disposed || this.refreshTimer) return;
+		this.refreshTimer = setTimeout(() => {
+			this.refreshTimer = undefined;
 			if (this.disposed) return;
-			this.invalidate();
-			this.tui.requestRender();
-		}, options.refreshMs ?? REFRESH_MS);
-		this.timer.unref?.();
+			try {
+				this.invalidate();
+				this.tui.requestRender();
+			} finally {
+				this.scheduleRefresh();
+			}
+		}, this.refreshMs);
+		this.refreshTimer.unref?.();
+	}
+
+	private stopRefresh(): void {
+		this.disposed = true;
+		if (this.refreshTimer) clearTimeout(this.refreshTimer);
+		this.refreshTimer = undefined;
 	}
 
 	private refresh(): void {
 		const previousKey = this.snapshot.items[this.selected]?.key ?? this.selectedKey;
 		this.snapshot = collectFleetSnapshot(this.state, this.options);
-		const preserved = previousKey ? this.snapshot.items.findIndex((item) => item.key === previousKey) : -1;
+		let preserved = previousKey ? this.snapshot.items.findIndex((item) => item.key === previousKey) : -1;
+		if (preserved < 0 && previousKey) {
+			const parentKey = visibleWorkflowParentKeyForForegroundKey(this.state, previousKey, this.snapshot.items);
+			if (parentKey) preserved = this.snapshot.items.findIndex((item) => item.key === parentKey);
+		}
 		this.selected = preserved >= 0 ? preserved : Math.min(this.selected, Math.max(0, this.snapshot.items.length - 1));
 		this.selectedKey = this.snapshot.items[this.selected]?.key;
 	}
@@ -725,14 +850,28 @@ export class SubagentFleetComponent implements Component {
 	private selectedAsyncAction(): { item: Extract<FleetItem, { kind: "async" }> } | { reason: string } {
 		const item = this.snapshot.items[this.selected];
 		if (!item) return { reason: "No child is selected." };
+		if (item.kind === "external") return { reason: "External jobs are display-only and remain controlled by their owning extension." };
 		if (item.kind !== "async") return { reason: "Fleet controls are available for current-session top-level async runs only." };
 		if (!isActionableAsyncState(item.run.state) || !isActionableAsyncState(item.state)) return { reason: `Selected child is ${item.state}; controls require a running or queued async child.` };
 		return { item };
 	}
 
+	private selectedSteerAction(): { runId: string; asyncDir: string; index?: number } | { reason: string } {
+		const item = this.snapshot.items[this.selected];
+		if (item?.kind === "foreground-active" && item.control.parentWorkflowRunId) {
+			const parent = this.state.asyncJobs.get(item.control.parentWorkflowRunId) ?? this.state.fleetJobs?.get(item.control.parentWorkflowRunId);
+			if (!parent || !isActionableAsyncState(parent.status)) return { reason: "The parent workflow is no longer available for steering." };
+			return { runId: item.runId, asyncDir: parent.asyncDir, ...(item.index !== undefined ? { index: item.index } : {}) };
+		}
+		const target = this.selectedAsyncAction();
+		if ("reason" in target) return target;
+		return { runId: target.item.runId, asyncDir: target.item.run.asyncDir, ...(target.item.index !== undefined ? { index: target.item.index } : {}) };
+	}
+
 	private selectedHerdrInspectAction(): { runId: string; asyncDir: string; index?: number } | { reason: string } {
 		const item = this.snapshot.items[this.selected];
 		if (!item) return { reason: "No child is selected." };
+		if (item.kind === "external") return { reason: "External jobs are display-only and have no Herdr controls." };
 		if (item.kind === "async") {
 			if (!isActionableAsyncState(item.run.state) || !isActionableAsyncState(item.state)) return { reason: `Selected child is ${item.state}; controls require a running or queued async child.` };
 			return { runId: item.runId, asyncDir: item.run.asyncDir, ...(item.index !== undefined ? { index: item.index } : {}) };
@@ -886,12 +1025,12 @@ export class SubagentFleetComponent implements Component {
 					this.setActionNotice({ text: "Steer message cannot be empty.", isError: true });
 					return;
 				}
-				const target = this.selectedAsyncAction();
+				const target = this.selectedSteerAction();
 				if ("reason" in target || !this.options.actions) {
 					this.setActionNotice({ text: "reason" in target ? target.reason : "Fleet controls are unavailable in this context.", isError: true });
 					return;
 				}
-				this.runAction(() => this.options.actions!.steer({ runId: target.item.runId, asyncDir: target.item.run.asyncDir, ...(target.item.index !== undefined ? { index: target.item.index } : {}), message, mode: this.steerMode }));
+				this.runAction(() => this.options.actions!.steer({ ...target, message, mode: this.steerMode }));
 				return;
 			}
 			if (matchesKey(data, "tab") || data === "\t") {
@@ -928,6 +1067,7 @@ export class SubagentFleetComponent implements Component {
 			return;
 		}
 		if (matchesFleetAction(data, this.keybindings, "close")) {
+			this.stopRefresh();
 			this.done(undefined);
 			return;
 		}
@@ -958,7 +1098,7 @@ export class SubagentFleetComponent implements Component {
 			return;
 		}
 		if (matchesFleetAction(data, this.keybindings, "steer")) {
-			const target = this.selectedAsyncAction();
+			const target = this.selectedSteerAction();
 			if ("reason" in target || !this.options.actions) this.setActionNotice({ text: "reason" in target ? target.reason : "Fleet controls are unavailable in this context.", isError: true });
 			else {
 				this.actionNotice = undefined;
@@ -1117,7 +1257,9 @@ export class SubagentFleetComponent implements Component {
 		];
 		const lines = [this.theme.fg("border", `╭${"─".repeat(innerWidth)}╮`)];
 		const selected = this.snapshot.items[this.selected];
-		const title = ` ${this.theme.bold("Subagent fleet inspector")} ${this.theme.fg("dim", "· live controls")}`;
+		const title = selected?.kind === "external"
+			? ` ${this.theme.bold("Fleet inspector")} ${this.theme.fg("dim", "· external display-only")}`
+			: ` ${this.theme.bold("Subagent fleet inspector")} ${this.theme.fg("dim", "· live controls")}`;
 		const selectedStatus = selected
 			? `${statusGlyph(selected, this.theme)} ${selected.agent} · ${selected.state} `
 			: this.theme.fg("dim", "no children ");
@@ -1136,7 +1278,9 @@ export class SubagentFleetComponent implements Component {
 		const position = this.snapshot.items.length ? `${this.selected + 1}/${this.snapshot.items.length}` : "0/0";
 		const footer = this.promptAuditOpen
 			? ` j/k child · 1/2/3 view · g redo with guidance · c copy · Esc close Prompt Audit · ${position}`
-			: ` ${bindingLabel(this.keybindings, "selectUp")}/${bindingLabel(this.keybindings, "selectDown")} agent · p Prompt Audit · ${bindingLabel(this.keybindings, "inspect")} Herdr · ${bindingLabel(this.keybindings, "steer")} steer · ${bindingLabel(this.keybindings, "stop")} stop · ${bindingLabel(this.keybindings, "toggleTools")} tools · ${bindingLabel(this.keybindings, "refresh")} refresh · ${bindingLabel(this.keybindings, "close")} close · ${position}`;
+			: selected?.kind === "external"
+				? ` ${bindingLabel(this.keybindings, "selectUp")}/${bindingLabel(this.keybindings, "selectDown")} job · display-only · ${bindingLabel(this.keybindings, "refresh")} refresh · ${bindingLabel(this.keybindings, "close")} close · ${position}`
+				: ` ${bindingLabel(this.keybindings, "selectUp")}/${bindingLabel(this.keybindings, "selectDown")} agent · p Prompt Audit · ${bindingLabel(this.keybindings, "inspect")} Herdr · ${bindingLabel(this.keybindings, "steer")} steer · ${bindingLabel(this.keybindings, "stop")} stop · ${bindingLabel(this.keybindings, "toggleTools")} tools · ${bindingLabel(this.keybindings, "refresh")} refresh · ${bindingLabel(this.keybindings, "close")} close · ${position}`;
 		lines.push(this.theme.fg("border", "│") + fit(this.theme.fg("dim", footer), innerWidth) + this.theme.fg("border", "│"));
 		lines.push(this.theme.fg("border", `╰${"─".repeat(innerWidth)}╯`));
 		return lines.map((line) => truncateToWidth(line, width));
@@ -1148,8 +1292,7 @@ export class SubagentFleetComponent implements Component {
 	}
 
 	dispose(): void {
-		this.disposed = true;
-		clearInterval(this.timer);
+		this.stopRefresh();
 	}
 }
 
@@ -1164,23 +1307,38 @@ export async function openSubagentFleet(ctx: ExtensionContext, state: SubagentSt
 		await copyToClipboard(text);
 	});
 	const actions = options.actions ?? {
-		steer: async (input: { runId: string; asyncDir: string; index?: number; message: string; mode: SteerDeliveryMode }) => firstToolResultText(await steerAsyncRun({
-			state,
-			runId: input.runId,
-			...(input.index !== undefined ? { index: input.index } : {}),
-			message: input.message,
-			mode: input.mode,
-			location: { asyncDir: input.asyncDir, resolvedId: input.runId } as Parameters<typeof steerAsyncRun>[0]["location"],
-		}), `Failed to steer async run ${input.runId}.`),
+		steer: async (input: { runId: string; asyncDir: string; index?: number; message: string; mode: SteerDeliveryMode }) => {
+			const status = readStatus(input.asyncDir);
+			const liveWorkflowRunId = status?.mode === "workflow" && state.workflowControllers?.has(status.runId || input.runId)
+				? status.runId || input.runId
+				: undefined;
+			if (liveWorkflowRunId) {
+				const route = state.foregroundControls.get(input.runId)?.parentWorkflowRunId === liveWorkflowRunId
+					? resolveWorkflowForegroundSteeringTarget({ state, childRunId: input.runId, asyncDirRoot: options.asyncDirRoot ?? DIRS.async })
+					: resolveWorkflowForegroundSteeringTarget({ state, workflowRunId: liveWorkflowRunId, asyncDirRoot: options.asyncDirRoot ?? DIRS.async });
+				if (!route.ok) return { text: route.message, isError: true };
+				return firstToolResultText(await steerWorkflowForegroundTarget({ target: route.target, message: input.message, mode: input.mode, ...(input.index !== undefined ? { index: input.index } : {}) }), `Failed to steer foreground run ${input.runId}.`);
+			}
+			return firstToolResultText(await steerAsyncRun({
+				state,
+				runId: input.runId,
+				...(input.index !== undefined ? { index: input.index } : {}),
+				message: input.message,
+				mode: input.mode,
+				location: { asyncDir: input.asyncDir, resolvedId: input.runId } as Parameters<typeof steerAsyncRun>[0]["location"],
+			}), `Failed to steer async run ${input.runId}.`);
+		},
 		stop: (input: { runId: string; asyncDir: string; index?: number }) => firstToolResultText(stopAsyncRun(state, input.runId, undefined, { asyncDir: input.asyncDir, resolvedId: input.runId }), `Failed to stop async run ${input.runId}.`),
 		inspect: async (input: { runId: string; asyncDir: string; index?: number }) => firstToolResultText(await handleHerdrInspectorAction("inspector.open", {
 			id: input.runId,
 			dir: input.asyncDir,
+			focus: true,
 			...(input.index !== undefined ? { index: input.index } : {}),
 		}, {
 			state,
 			sessionRoots: state.trustedSessionRoots,
 			cwd: state.baseCwd,
+			...(options.herdrClient ? { client: options.herdrClient } : {}),
 			...(state.authorityPolicy ? { authorityPolicy: state.authorityPolicy } : {}),
 			...(state.missionStoreConfig ? { missions: state.missionStoreConfig } : {}),
 		}), `Failed to open Herdr inspector for async run ${input.runId}.`),

package/src/tui/render.ts

@@ -28,6 +28,7 @@ import { formatNestedAggregate } from "../runs/shared/nested-render.ts";
 import { aggregateStepStatus, formatActivityLabel, formatAgentRunningLabel, formatParallelOutcome } from "../shared/status-format.ts";
 import { contextModeBadge, contextModePrefix } from "../runs/shared/context-mode.ts";
 import { buildWorkflowChatProgressRows, type WorkflowChatProgressRow } from "../workflows/chat-progress.ts";
+import { encodeAsyncStatusSnapshotWidget } from "../runs/background/async-status-snapshot.ts";
 
 type Theme = ExtensionContext["ui"]["theme"];
 
@@ -71,6 +72,22 @@ function liveDetailHintText(): string {
 	return `Press ${liveDetailKeyText()} for live detail`;
 }
 
+function foregroundSingleHintText(shortcut?: string): string {
+	if (!shortcut) return liveDetailHintText();
+	const label = shortcut
+		.split("+")
+		.map((part) => {
+			const normalized = part.trim().toLowerCase();
+			if (normalized === "ctrl") return "Ctrl";
+			if (normalized === "alt") return "Alt";
+			if (normalized === "shift") return "Shift";
+			if (normalized === "super") return "Super";
+			return normalized.length === 1 ? normalized.toUpperCase() : part.trim();
+		})
+		.join("+");
+	return `${liveDetailHintText()} · ${label} to run in background`;
+}
+
 function getTermWidth(): number {
 	return process.stdout.columns || 120;
 }
@@ -341,7 +358,7 @@ function visibleWorkflowRows(rows: WorkflowChatProgressRow[]): { rows: WorkflowC
 		selected.add(row.key);
 	};
 	for (const row of [...rows].reverse()) {
-		if (row.state === "failed") add(row);
+		if (row.state === "failed" || row.state === "detached") add(row);
 	}
 	for (const row of [...rows].reverse()) add(row);
 	return {
@@ -1585,10 +1602,21 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 		return;
 	}
 	if (!ctx.hasUI) return;
+	if ((ctx as { mode?: string }).mode === "rpc") {
+		ctx.ui.setWidget(WIDGET_KEY, encodeAsyncStatusSnapshotWidget(jobs));
+		return;
+	}
 	ctx.ui.setWidget(WIDGET_KEY, buildWidgetComponent(jobs, ctx.ui.getToolsExpanded?.() ?? false));
 }
 
-function renderSingleCompact(d: Details, r: Details["results"][number], theme: Theme, layout: MainWindowRenderLayout, frame?: number): Component {
+function renderSingleCompact(
+	d: Details,
+	r: Details["results"][number],
+	theme: Theme,
+	layout: MainWindowRenderLayout,
+	frame?: number,
+	foregroundDetachShortcut?: string,
+): Component {
 	const output = r.truncation?.text || getSingleResultOutput(r);
 	const progress = r.progress || r.progressSummary;
 	const isRunning = isResultRunning(r);
@@ -1613,7 +1641,7 @@ function renderSingleCompact(d: Details, r: Details["results"][number], theme: T
 		for (const nestedLine of formatNestedWidgetLines(r.children, theme, width, false, progressSnapshotNow)) {
 			c.addChild(new Text(truncLine(`${detailIndent}${nestedLine}`, width), 0, 0));
 		}
-		c.addChild(new Text(truncLine(theme.fg("accent", `${detailIndent}${liveDetailHintText()}`), width), 0, 0));
+		c.addChild(new Text(truncLine(theme.fg("accent", `${detailIndent}${foregroundSingleHintText(foregroundDetachShortcut)}`), width), 0, 0));
 		if (r.artifactPaths) c.addChild(new Text(truncLine(theme.fg("dim", `${detailIndent}output: ${shortenPath(r.artifactPaths.outputPath)}`), width), 0, 0));
 		return c;
 	}
@@ -1635,7 +1663,7 @@ function renderSingleCompact(d: Details, r: Details["results"][number], theme: T
 function workflowRowGlyph(row: WorkflowChatProgressRow, theme: Theme, frame?: number): string {
 	if (row.state === "running") return theme.fg("accent", runningGlyph(frame));
 	if (row.state === "complete") return theme.fg("success", "✓");
-	if (row.state === "stopped") return theme.fg("warning", "■");
+	if (row.state === "detached" || row.state === "stopped") return theme.fg("warning", "■");
 	return theme.fg("error", "✗");
 }
 
@@ -1643,12 +1671,13 @@ function workflowRowStateLabel(row: WorkflowChatProgressRow, theme: Theme): stri
 	const label = (row.state === "complete" ? "complete" : row.state).padEnd(8);
 	if (row.state === "running") return theme.fg("accent", label);
 	if (row.state === "complete") return theme.fg("success", label);
-	if (row.state === "stopped") return theme.fg("warning", label);
+	if (row.state === "detached" || row.state === "stopped") return theme.fg("warning", label);
 	return theme.fg("error", label);
 }
 
-function workflowOverallState(rows: WorkflowChatProgressRow[], hasTerminalValue: boolean, isError?: boolean): "running" | "complete" | "failed" {
+function workflowOverallState(rows: WorkflowChatProgressRow[], hasTerminalValue: boolean, isError?: boolean): "running" | "complete" | "failed" | "paused" {
 	if (isError || rows.some((row) => row.state === "failed")) return "failed";
+	if (rows.some((row) => row.state === "detached")) return "paused";
 	if ((rows.length > 0 && rows.every((row) => row.state === "complete")) || hasTerminalValue) return "complete";
 	return "running";
 }
@@ -1657,7 +1686,7 @@ function renderWorkflowChatProgress(d: Details, result: AgentToolResult<Details>
 	const workflow = d.workflow;
 	const rows = workflow ? buildWorkflowChatProgressRows(workflow.trace) : [];
 	const state = workflowOverallState(rows, workflow?.value !== undefined, result.isError);
-	const glyph = state === "running" ? theme.fg("accent", runningGlyph(frame)) : state === "complete" ? theme.fg("success", "✓") : theme.fg("error", "✗");
+	const glyph = state === "running" ? theme.fg("accent", runningGlyph(frame)) : state === "complete" ? theme.fg("success", "✓") : state === "paused" ? theme.fg("warning", "■") : theme.fg("error", "✗");
 	const width = getTermWidth() - 4;
 	const runId = d.runId ? d.runId.slice(0, 12) : "workflow";
 	const repoLabel = d.chatProgress?.repoLabel ?? (d.chatProgress?.repoRelation === "same" ? "same repo" : "other repo");
@@ -1678,7 +1707,7 @@ function renderWorkflowChatProgress(d: Details, result: AgentToolResult<Details>
 		const label = row.label && row.label !== row.key ? ` ${oneLine(row.label)}` : "";
 		const duration = row.durationMs !== undefined ? ` ${theme.fg("dim", `· ${formatDuration(row.durationMs)}`)}` : "";
 		const run = row.runId ? ` ${theme.fg("dim", `[${row.runId.slice(0, 8)}]`)}` : "";
-		const error = row.error ? ` ${theme.fg("error", `· ${compactWorkflowError(row.error)}`)}` : "";
+		const error = row.error ? ` ${theme.fg(row.state === "detached" ? "warning" : "error", `· ${compactWorkflowError(row.error)}`)}` : "";
 		c.addChild(new Text(truncLine(`${rowIndent}${workflowRowGlyph(row, theme, frame)} ${status} ${theme.bold(row.key)}${label}${run}${duration}${error}`, width), 0, 0));
 	}
 	if (workflow?.emits.length) c.addChild(new Text(truncLine(theme.fg("dim", `${rowIndent}Emits  ${workflow.emits.length}`), width), 0, 0));
@@ -1844,6 +1873,7 @@ export function renderSubagentResult(
 	theme: Theme,
 	frame?: number,
 	rendererConfig?: MainWindowRendererConfig,
+	foregroundDetachShortcut?: string,
 ): Component {
 	const layout = resolveMainWindowRenderLayout(rendererConfig);
 	const compact = (component: Component): Component => capCompactMainWindowResult(component, layout, theme, !options.expanded);
@@ -1877,8 +1907,9 @@ export function renderSubagentResult(
 
 	if (d.mode === "single" && d.results.length === 1) {
 		const r = d.results[0];
+		const detachableShortcut = d.asyncId || d.background ? undefined : foregroundDetachShortcut;
 		if (!r) return compact(renderMultiCompact(d, theme, layout, frame));
-		if (!expanded) return compact(renderSingleCompact(d, r, theme, layout, frame));
+		if (!expanded) return compact(renderSingleCompact(d, r, theme, layout, frame, detachableShortcut));
 		const isRunning = isResultRunning(r);
 		const contextBadge = contextModeBadge(theme, r.context ?? d.context);
 		const output = r.truncation?.text || getSingleResultOutput(r);
@@ -1918,7 +1949,7 @@ export function renderSubagentResult(
 			if (liveStatusLine) {
 				c.addChild(new Text(fit(theme.fg("accent", liveStatusLine)), 0, 0));
 			}
-			c.addChild(new Text(fit(theme.fg("accent", liveDetailHintText())), 0, 0));
+			c.addChild(new Text(fit(theme.fg("accent", foregroundSingleHintText(detachableShortcut))), 0, 0));
 			if (r.artifactPaths) {
 				c.addChild(new Text(fit(theme.fg("dim", `Artifacts: ${shortenPath(r.artifactPaths.outputPath)}`)), 0, 0));
 			}

package/src/workflows/chat-progress.ts

@@ -90,13 +90,13 @@ export function resolveWorkflowChatProgress(input: ResolveWorkflowChatProgressIn
 	else mode = requestedMode;
 
 	if (mode === "live-card" && !sameRepo) return { error: "chatProgress: 'live-card' is only available for workflowScript runs in the same Git repository." };
-	if (mode === "live-card" && input.background) return { error: "chatProgress: 'live-card' requires a watched foreground workflow; pass async:false." };
+	if (mode === "live-card" && input.background) return { error: "chatProgress: 'live-card' is unavailable for async workflowScript. Async workflows have no inline live card; omit chatProgress or use auto/off. Use async:false only when the parent must block." };
 	return { projection: { mode, repoRelation, ...(repoLabel ? { repoLabel } : {}) } };
 }
 
 export interface WorkflowChatProgressRow {
 	key: string;
-	state: "running" | "complete" | "failed" | "stopped";
+	state: "running" | "complete" | "failed" | "detached" | "stopped";
 	label?: string;
 	phase?: string;
 	runId?: string;
@@ -127,9 +127,11 @@ export function buildWorkflowChatProgressRows(trace: NonNullable<Details["workfl
 			? "complete"
 			: entry.state === "failed"
 				? "failed"
-				: entry.state === "stopped"
-					? "stopped"
-					: "running";
+				: entry.state === "detached"
+					? "detached"
+					: entry.state === "stopped"
+						? "stopped"
+						: "running";
 		const label = cleanLabel(entry.label);
 		const phase = cleanLabel(entry.phase);
 		if (label) next.label = label;