pi-subagents 0.45.2 → 0.46.0

package/src/shared/prompt-resources.ts

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseFrontmatter } from "../agents/frontmatter.ts";
+import { getAgentDir, getProjectConfigDir } from "./utils.ts";
+
+const PROMPT_REF_PATTERN = /^(package|user|project):([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/;
+const PROMPT_VARIABLE_PATTERN = /\{\{(\w+)\}\}/g;
+
+type PromptVariable = string | number | boolean;
+
+export function getPromptDirectories(cwd: string) {
+	return {
+		package: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts"),
+		user: path.join(getAgentDir(), "prompts"),
+		project: path.join(getProjectConfigDir(cwd), "prompts"),
+	};
+}
+
+function promptVariables(vars: unknown): Record<string, PromptVariable> {
+	if (vars === undefined) return {};
+	if (!vars || typeof vars !== "object" || Array.isArray(vars)) throw new Error("prompts.render vars must be a plain object.");
+	const prototype = Object.getPrototypeOf(vars);
+	if (prototype !== null && prototype !== Object.prototype) throw new Error("prompts.render vars must be a plain object.");
+	for (const [name, value] of Object.entries(vars)) {
+		if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+			throw new Error(`prompts.render variable '${name}' must be a string, number, or boolean.`);
+		}
+	}
+	return vars as Record<string, PromptVariable>;
+}
+
+export function renderWorkflowPrompt(ref: string, vars: unknown, cwd: string): string {
+	const match = ref.match(PROMPT_REF_PATTERN);
+	if (!match) throw new Error("prompts.render ref must use package:<name>, user:<name>, or project:<name>.");
+	const scope = match[1] as keyof ReturnType<typeof getPromptDirectories>;
+	const name = match[2]!;
+	const filePath = path.join(getPromptDirectories(cwd)[scope], `${name}.md`);
+	let content: string;
+	try {
+		if (!fs.lstatSync(filePath).isFile()) throw new Error("not a regular file");
+		content = fs.readFileSync(filePath, "utf-8");
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Error(`Could not read prompt fragment '${ref}': ${detail}`);
+	}
+	const variables = promptVariables(vars);
+	return parseFrontmatter(content).body.trim().replace(PROMPT_VARIABLE_PATTERN, (placeholder, variable: string) => {
+		return Object.hasOwn(variables, variable) ? String(variables[variable]) : placeholder;
+	});
+}

package/src/shared/types.ts

@@ -969,6 +969,8 @@ export interface WaitCompletion {
 	mode?: string;
 	state?: string;
 	success?: boolean;
+	/** Versioned bounded output archive retained with the durable completion replay. */
+	archivePath?: string;
 	results?: WaitCompletionChild[];
 }
 
@@ -1045,6 +1047,7 @@ export interface Details {
 			operation: "run" | "status";
 			key: string;
 			state: "started" | "completed" | "failed" | "reused";
+			agent?: string;
 			runId?: string;
 			phase?: string;
 			label?: string;
@@ -1538,6 +1541,10 @@ export interface ForegroundChildControl {
 
 export interface ForegroundRunControl {
 	runId: string;
+	/** Workflow shell that owns this live foreground child, when applicable. */
+	parentWorkflowRunId?: string;
+	/** Stable workflow lane key for this live foreground child. */
+	workflowKey?: string;
 	/** Originating parent session; required for public fleet projection. */
 	sessionId?: string;
 	mode: SubagentRunMode;
@@ -1780,12 +1787,34 @@ export interface ScheduledRunsConfig {
 
 export type FleetViewPlacement = "aboveEditor" | "belowEditor";
 
+export const FLEET_KEYBINDING_ACTIONS = [
+	"close",
+	"scrollUp",
+	"scrollDown",
+	"selectUp",
+	"selectDown",
+	"selectFirst",
+	"selectLast",
+	"pageUp",
+	"pageDown",
+	"refresh",
+	"steer",
+	"inspect",
+	"stop",
+	"toggleTools",
+] as const;
+
+export type FleetKeybindingAction = typeof FLEET_KEYBINDING_ACTIONS[number];
+export type FleetKeybindingsConfig = Partial<Record<FleetKeybindingAction, string[]>>;
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	/** Show the Claude Code-style navigable fleet. Defaults to true. */
 	fleetView?: boolean;
 	/** Place the persistent FleetView above or below the editor. Defaults to belowEditor. */
 	fleetViewPlacement?: FleetViewPlacement;
+	/** Local keybindings for the full Fleet inspector. */
+	fleetKeybindings?: FleetKeybindingsConfig;
 	/** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
 	asyncWidget?: boolean;
 	/** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
@@ -1922,7 +1951,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
 export const POLL_INTERVAL_MS = 250;
 export const MAX_WIDGET_JOBS = 4;
 export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
-export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "append-step", "approve-checkpoint", "reject-checkpoint", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
+export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "append-step", "approve-checkpoint", "reject-checkpoint", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
 
 export const DEFAULT_FORK_PREAMBLE =
 	"You are a delegated subagent running from a fork of the parent session. " +

package/src/shared/utf8.ts

@@ -0,0 +1,11 @@
+export function decodeUtf8Tail(bytes: Buffer): string {
+	let start = 0;
+	while (start < bytes.length && (bytes[start]! & 0xc0) === 0x80) start += 1;
+	return bytes.subarray(start).toString("utf-8");
+}
+
+export function utf8Tail(value: string, maxBytes: number): { text: string; truncated: boolean } {
+	const bytes = Buffer.from(value, "utf-8");
+	if (bytes.length <= maxBytes) return { text: value, truncated: false };
+	return { text: decodeUtf8Tail(bytes.subarray(bytes.length - maxBytes)), truncated: true };
+}

package/src/slash/prompt-workflows.ts

@@ -1,10 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { parseFrontmatter } from "../agents/frontmatter.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
-import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+import { getPromptDirectories } from "../shared/prompt-resources.ts";
 
 interface PromptWorkflow {
 	name: string;
@@ -32,21 +31,9 @@ const RESERVED_COMMAND_NAMES = new Set([
 	"subagents-models",
 ]);
 
-function packagePromptsDir(): string {
-	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "prompts");
-}
-
-function promptDirs(cwd: string): string[] {
-	return [
-		packagePromptsDir(),
-		path.join(getAgentDir(), "prompts"),
-		path.join(getProjectConfigDir(cwd), "prompts"),
-	];
-}
-
 function readPromptFiles(cwd: string): string[] {
 	const files: string[] = [];
-	for (const dir of promptDirs(cwd)) {
+	for (const dir of Object.values(getPromptDirectories(cwd))) {
 		let entries: fs.Dirent[];
 		try {
 			entries = fs.readdirSync(dir, { withFileTypes: true });

package/src/slash/slash-commands.ts

@@ -22,6 +22,7 @@ import { SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
 import { registerPromptWorkflowCommands } from "./prompt-workflows.ts";
 import { openSubagentsAdmin } from "./subagents-admin.ts";
+import { SUBAGENT_GUIDE_TOPICS } from "../extension/subagent-guide.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
 import {
 	applySlashUpdate,
@@ -40,6 +41,7 @@ import {
 	SLASH_SUBAGENT_UPDATE_EVENT,
 	DIRS,
 	type Details,
+	type FleetKeybindingsConfig,
 	type JsonSchemaObject,
 	type SingleResult,
 	type SubagentState,
@@ -628,6 +630,7 @@ function slashRunWorkflowScript(key: string, child: Record<string, unknown>): st
 export function registerSlashCommands(
 	pi: ExtensionAPI,
 	state: SubagentState,
+	options: { fleetKeybindings?: FleetKeybindingsConfig } = {},
 ): void {
 	let fleetOpen = false;
 	const showFleet = async (ctx: ExtensionContext) => {
@@ -642,7 +645,7 @@ export function registerSlashCommands(
 		}
 		fleetOpen = true;
 		try {
-			await openSubagentFleet(ctx, state, { asyncDirRoot: DIRS.async, resultsDir: DIRS.results });
+			await openSubagentFleet(ctx, state, { asyncDirRoot: DIRS.async, resultsDir: DIRS.results, fleetKeybindings: options.fleetKeybindings });
 		} finally {
 			fleetOpen = false;
 		}
@@ -698,6 +701,21 @@ export function registerSlashCommands(
 		},
 	});
 
+	pi.registerCommand("subagents-guide", {
+		description: "Show a packaged subagents guide topic",
+		getArgumentCompletions: (prefix) => prefix.includes(" ") ? null : SUBAGENT_GUIDE_TOPICS
+			.filter((topic) => topic.startsWith(prefix))
+			.map((topic) => ({ value: topic, label: topic })),
+		handler: async (args, ctx) => {
+			const topic = args.trim();
+			if (topic.includes(" ")) {
+				ctx.ui.notify("Usage: /subagents-guide [topic]", "error");
+				return;
+			}
+			await runSlashSubagent(pi, ctx, { action: "guide", ...(topic ? { topic } : {}) });
+		},
+	});
+
 	pi.registerCommand("subagents-refine", {
 		description: "Generate a bounded project-local refinement overlay for one subagent",
 		getArgumentCompletions: makeAgentCompletions(state),

package/src/tui/fleet-status.ts

@@ -144,6 +144,12 @@ function isStaleExtensionContextError(error: unknown): boolean {
 			|| error.message.includes("Extension context no longer active"));
 }
 
+function foregroundDescription(control: { parentWorkflowRunId?: string; workflowKey?: string }, description: string | undefined): string | undefined {
+	if (!control.parentWorkflowRunId) return description;
+	const workflow = `workflow child: ${control.parentWorkflowRunId}${control.workflowKey ? ` (${control.workflowKey})` : ""}`;
+	return description ? `${workflow} · ${description}` : workflow;
+}
+
 export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntry[] {
 	const entries: FleetStatusEntry[] = [];
 	for (const control of state.foregroundControls.values()) {
@@ -154,7 +160,7 @@ export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntr
 					key: `foreground-active:${control.runId}:${child.index}`,
 					agent: child.agent,
 					...(modelThinking ? { modelThinking } : {}),
-					description: child.description,
+					description: foregroundDescription(control, child.description),
 					startedAt: child.startedAt,
 					tokens: child.tokens ?? 0,
 					state: "running",
@@ -170,7 +176,7 @@ export function collectFleetStatusEntries(state: SubagentState): FleetStatusEntr
 			key: `foreground-active:${control.runId}:${control.currentIndex ?? 0}`,
 			agent: control.currentAgent ?? control.mode,
 			...(modelThinking ? { modelThinking } : {}),
-			description: control.description,
+			description: foregroundDescription(control, control.description),
 			startedAt: control.startedAt,
 			tokens: control.tokens ?? 0,
 			state: "running",

package/src/tui/fleet.ts

@@ -2,10 +2,11 @@ import * as fs from "node:fs";
 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 { Key, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type MarkdownTheme } from "@earendil-works/pi-tui";
+import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type MarkdownTheme } from "@earendil-works/pi-tui";
 import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
 import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../shared/formatters.ts";
-import { DIRS, type AsyncJobState, type Details, type ForegroundChildControl, type ForegroundResumeChild, type ForegroundResumeRun, type ForegroundRunControl, type SubagentState } from "../shared/types.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";
+import { decodeUtf8Tail } from "../shared/utf8.ts";
 import { readStatus } from "../shared/utils.ts";
 import { formatAsyncRunTranscript } from "../runs/background/fleet-view.ts";
 import { listAsyncRuns, type AsyncRunSummary } from "../runs/background/async-status.ts";
@@ -21,6 +22,47 @@ const REFRESH_MS = 750;
 const MAX_RECENT_ASYNC_RUNS = 20;
 const MAX_FLEET_HISTORY_CANDIDATES = 100;
 const TRANSCRIPT_LINES = 200;
+const OUTPUT_TAIL_BYTES = 64 * 1024;
+
+export const DEFAULT_FLEET_KEYBINDINGS: Record<FleetKeybindingAction, string[]> = {
+	close: ["escape", "ctrl+c", "q"],
+	scrollUp: ["K"],
+	scrollDown: ["J"],
+	selectUp: ["up", "k"],
+	selectDown: ["down", "j"],
+	selectFirst: ["home"],
+	selectLast: ["end"],
+	pageUp: ["pageUp"],
+	pageDown: ["pageDown"],
+	refresh: ["r", "R"],
+	steer: ["s"],
+	inspect: ["H"],
+	stop: ["D"],
+	toggleTools: ["x", "X", "ctrl+o"],
+};
+
+type ResolvedFleetKeybindings = Record<FleetKeybindingAction, string[]>;
+
+export function resolveFleetKeybindings(config: FleetKeybindingsConfig | undefined): ResolvedFleetKeybindings {
+	return Object.fromEntries(
+		Object.entries(DEFAULT_FLEET_KEYBINDINGS).map(([action, defaults]) => [action, config?.[action as FleetKeybindingAction] ?? defaults]),
+	) as ResolvedFleetKeybindings;
+}
+
+function matchesFleetBinding(data: string, binding: string): boolean {
+	const key = /^[A-Z]$/.test(binding) ? `shift+${binding.toLowerCase()}` : binding;
+	return matchesKey(data, key as Parameters<typeof matchesKey>[1]);
+}
+
+function matchesFleetAction(data: string, bindings: ResolvedFleetKeybindings, action: FleetKeybindingAction): boolean {
+	return bindings[action].some((binding) => matchesFleetBinding(data, binding));
+}
+
+function bindingLabel(bindings: ResolvedFleetKeybindings, action: FleetKeybindingAction): string {
+	return bindings[action]
+		.map((binding) => binding === "up" ? "↑" : binding === "down" ? "↓" : binding === "escape" ? "Esc" : binding === "return" ? "Enter" : binding)
+		.join("/");
+}
 
 type Theme = ExtensionContext["ui"]["theme"];
 type FleetTui = {
@@ -57,6 +99,7 @@ export interface FleetViewOptions {
 	refreshMs?: number;
 	initialKey?: string;
 	markdownTheme?: MarkdownTheme;
+	fleetKeybindings?: FleetKeybindingsConfig;
 	actions?: FleetActionHandlers;
 }
 
@@ -246,6 +289,7 @@ function foregroundActiveDetail(item: Extract<FleetItem, { kind: "foreground-act
 		"Source: foreground",
 		`State: running`,
 		`Mode: ${control.mode}`,
+		control.parentWorkflowRunId ? `Workflow child of: ${control.parentWorkflowRunId}${control.workflowKey ? ` (${control.workflowKey})` : ""}` : undefined,
 		item.index !== undefined ? `Child: ${item.index} (${item.agent})` : `Agent: ${item.agent}`,
 		modelThinking ? `Model: ${modelThinking}` : undefined,
 		`Started: ${new Date(live.startedAt).toISOString()}`,
@@ -260,7 +304,59 @@ function foregroundActiveDetail(item: Extract<FleetItem, { kind: "foreground-act
 	return lines.filter((line): line is string => line !== undefined);
 }
 
-function foregroundRecentDetail(item: Extract<FleetItem, { kind: "foreground-recent" }>): string[] {
+function pathWithin(base: string, candidate: string): boolean {
+	const resolvedBase = path.resolve(base);
+	const resolvedCandidate = path.resolve(candidate);
+	return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
+}
+
+function trustedFileTail(filePath: string, trustedRoots: string[]): { text?: string; warning?: string; unavailable?: string } {
+	const resolvedPath = path.resolve(filePath);
+	if (trustedRoots.length === 0 || !trustedRoots.some((root) => pathWithin(root, resolvedPath))) return { warning: `output artifact is outside trusted roots: ${filePath}` };
+	let stat: fs.Stats;
+	try {
+		stat = fs.lstatSync(resolvedPath);
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return { unavailable: `output artifact unavailable: ${filePath}` };
+		return { warning: `output artifact could not be inspected: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	if (stat.isSymbolicLink()) return { warning: `output artifact refused a symlink: ${filePath}` };
+	if (!stat.isFile()) return { warning: `output artifact is not a file: ${filePath}` };
+	try {
+		const realPath = fs.realpathSync(resolvedPath);
+		const realRoots = trustedRoots.filter((root) => fs.existsSync(root)).map((root) => fs.realpathSync(root));
+		if (!realRoots.some((root) => pathWithin(root, realPath))) return { warning: `output artifact resolves outside trusted roots: ${filePath}` };
+		const fd = fs.openSync(realPath, "r");
+		try {
+			const bytes = Math.min(stat.size, OUTPUT_TAIL_BYTES);
+			const buffer = Buffer.alloc(bytes);
+			fs.readSync(fd, buffer, 0, bytes, stat.size - bytes);
+			return { text: decodeUtf8Tail(buffer) };
+		} finally {
+			fs.closeSync(fd);
+		}
+	} catch (error) {
+		return { warning: `output artifact could not be read: ${error instanceof Error ? error.message : String(error)}` };
+	}
+}
+
+function foregroundRecentOutputLines(item: Extract<FleetItem, { kind: "foreground-recent" }>, state: SubagentState): string[] {
+	const outputPath = item.child.artifactPaths?.outputPath ?? item.child.savedOutputPath;
+	const output = item.child.finalOutput
+		? { text: item.child.finalOutput }
+		: outputPath
+			? trustedFileTail(path.isAbsolute(outputPath) ? outputPath : path.resolve(item.run.cwd, outputPath), uniquePaths([
+				fleetArtifactsRoot(state, item.run.cwd),
+				fleetArtifactsRoot(state, state.baseCwd),
+			]))
+			: undefined;
+	if (output?.warning) return [`(${output.warning})`];
+	if (output?.unavailable) return [`(${output.unavailable})`];
+	const outputLines = (output?.text ?? "").split(/\r?\n/).filter((line) => line.trim()).slice(-TRANSCRIPT_LINES);
+	return outputLines.length ? outputLines : ["(no recovered output available)"];
+}
+
+function foregroundRecentDetail(item: Extract<FleetItem, { kind: "foreground-recent" }>, state: SubagentState): string[] {
 	const { child, run } = item;
 	const outputPath = child.artifactPaths?.outputPath ?? child.savedOutputPath;
 	const modelThinking = formatModelThinking(child.model, child.thinking);
@@ -281,8 +377,7 @@ function foregroundRecentDetail(item: Extract<FleetItem, { kind: "foreground-rec
 		"",
 		"Result transcript tail",
 	];
-	const outputLines = (child.finalOutput ?? "").split(/\r?\n/).filter((line) => line.trim()).slice(-TRANSCRIPT_LINES);
-	lines.push(...(outputLines.length ? outputLines : ["(no recovered output available)"]));
+	lines.push(...foregroundRecentOutputLines(item, state));
 	return lines.filter((line): line is string => line !== undefined);
 }
 
@@ -306,12 +401,12 @@ function asyncDetail(item: Extract<FleetItem, { kind: "async" }>): string[] {
 	].filter((line): line is string => line !== undefined);
 }
 
-function detailLines(item: FleetItem | undefined, error: string | undefined): string[] {
+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."];
 	const lines = item.kind === "foreground-active"
 		? foregroundActiveDetail(item)
 		: item.kind === "foreground-recent"
-			? foregroundRecentDetail(item)
+			? foregroundRecentDetail(item, state)
 			: asyncDetail(item);
 	if (error) lines.unshift(`Fleet scan warning: ${error}`, "");
 	return lines;
@@ -497,6 +592,7 @@ export class SubagentFleetComponent implements Component {
 	private readonly state: SubagentState;
 	private readonly done: (result: undefined) => void;
 	private readonly options: FleetViewOptions;
+	private readonly keybindings: ResolvedFleetKeybindings;
 
 	constructor(
 		tui: FleetTui,
@@ -511,6 +607,7 @@ export class SubagentFleetComponent implements Component {
 		this.state = state;
 		this.done = done;
 		this.options = options;
+		this.keybindings = resolveFleetKeybindings(options.fleetKeybindings);
 		this.selectedKey = options.initialKey;
 		this.refresh();
 		this.timer = setInterval(() => {
@@ -552,6 +649,19 @@ export class SubagentFleetComponent implements Component {
 		return { item };
 	}
 
+	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 === "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 } : {}) };
+		}
+		if (item.kind !== "foreground-active" || !item.control.parentWorkflowRunId) return { reason: "Fleet controls are available for current-session top-level async runs only." };
+		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 Herdr inspection." };
+		return { runId: parent.asyncId, asyncDir: parent.asyncDir };
+	}
+
 	private actionLines(): string[] {
 		const lines: string[] = [];
 		if (this.actionBusy) lines.push(this.theme.fg("accent", "Action pending..."));
@@ -657,25 +767,25 @@ export class SubagentFleetComponent implements Component {
 			}
 			return;
 		}
-		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || matchesKey(data, "q")) {
+		if (matchesFleetAction(data, this.keybindings, "close")) {
 			this.done(undefined);
 			return;
 		}
-		if (matchesKey(data, Key.shift("k"))) return this.scrollDetail(-1);
-		if (matchesKey(data, Key.shift("j"))) return this.scrollDetail(1);
-		if (matchesKey(data, "up") || matchesKey(data, "k")) return this.moveSelection(-1);
-		if (matchesKey(data, "down") || matchesKey(data, "j")) return this.moveSelection(1);
-		if (matchesKey(data, "home")) return this.moveSelection(-this.snapshot.items.length);
-		if (matchesKey(data, "end")) return this.moveSelection(this.snapshot.items.length);
-		if (matchesKey(data, "pageUp")) return this.scrollDetail(-this.detailViewportHeight);
-		if (matchesKey(data, "pageDown")) return this.scrollDetail(this.detailViewportHeight);
-		if (data.toLowerCase() === "r") {
+		if (matchesFleetAction(data, this.keybindings, "scrollUp")) return this.scrollDetail(-1);
+		if (matchesFleetAction(data, this.keybindings, "scrollDown")) return this.scrollDetail(1);
+		if (matchesFleetAction(data, this.keybindings, "selectUp")) return this.moveSelection(-1);
+		if (matchesFleetAction(data, this.keybindings, "selectDown")) return this.moveSelection(1);
+		if (matchesFleetAction(data, this.keybindings, "selectFirst")) return this.moveSelection(-this.snapshot.items.length);
+		if (matchesFleetAction(data, this.keybindings, "selectLast")) return this.moveSelection(this.snapshot.items.length);
+		if (matchesFleetAction(data, this.keybindings, "pageUp")) return this.scrollDetail(-this.detailViewportHeight);
+		if (matchesFleetAction(data, this.keybindings, "pageDown")) return this.scrollDetail(this.detailViewportHeight);
+		if (matchesFleetAction(data, this.keybindings, "refresh")) {
 			this.transcriptCache = undefined;
 			this.refresh();
 			this.tui.requestRender();
 			return;
 		}
-		if (data === "s") {
+		if (matchesFleetAction(data, this.keybindings, "steer")) {
 			const target = this.selectedAsyncAction();
 			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 {
@@ -687,13 +797,13 @@ export class SubagentFleetComponent implements Component {
 			}
 			return;
 		}
-		if (data === "H") {
-			const target = this.selectedAsyncAction();
+		if (matchesFleetAction(data, this.keybindings, "inspect")) {
+			const target = this.selectedHerdrInspectAction();
 			if ("reason" in target || !this.options.actions?.inspect) this.setActionNotice({ text: "reason" in target ? target.reason : "Herdr inspector controls are unavailable in this context.", isError: true });
-			else this.runAction(() => this.options.actions!.inspect!({ runId: target.item.runId, asyncDir: target.item.run.asyncDir, ...(target.item.index !== undefined ? { index: target.item.index } : {}) }));
+			else this.runAction(() => this.options.actions!.inspect!(target));
 			return;
 		}
-		if (data === "D") {
+		if (matchesFleetAction(data, this.keybindings, "stop")) {
 			const target = this.selectedAsyncAction();
 			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 {
@@ -705,7 +815,7 @@ export class SubagentFleetComponent implements Component {
 			}
 			return;
 		}
-		if (data.toLowerCase() === "x" || matchesKey(data, "ctrl+o")) {
+		if (matchesFleetAction(data, this.keybindings, "toggleTools")) {
 			this.expandedTools = !this.expandedTools;
 			this.transcriptCache = undefined;
 			this.tui.requestRender();
@@ -766,7 +876,7 @@ export class SubagentFleetComponent implements Component {
 			}
 		}
 
-		const raw = detailLines(selected, this.snapshot.error);
+		const raw = detailLines(selected, this.snapshot.error, this.state);
 		if (transcriptWarning) raw.unshift(`Transcript preview warning: ${transcriptWarning}`, "");
 		const lines: string[] = [];
 		for (const line of raw) {
@@ -823,7 +933,7 @@ export class SubagentFleetComponent implements Component {
 		}
 		lines.push(this.theme.fg("border", `├${"─".repeat(rosterWidth)}┴${"─".repeat(detailWidth)}┤`));
 		const position = this.snapshot.items.length ? `${this.selected + 1}/${this.snapshot.items.length}` : "0/0";
-		const footer = ` ↑↓/jk agent · H Herdr · s steer · D stop · x/Ctrl+O tools · r refresh · Esc close · ${position}`;
+		const footer = ` ${bindingLabel(this.keybindings, "selectUp")}/${bindingLabel(this.keybindings, "selectDown")} agent · ${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));