pi-subagents 0.65.1 → 0.67.0

package/src/inspectors/actions.ts

@@ -0,0 +1,148 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { readMissionBinding } from "../missions/lifecycle.ts";
+import { listMissions, missionRecordPath, resolveMissionStoreLocation } from "../missions/store.ts";
+import type { MissionStoreConfig } from "../missions/types.ts";
+import { resolveAuthorityDecision, type AuthorityPolicyConfig } from "../policy/authority.ts";
+import { DIRS, type Details, type SubagentState } from "../shared/types.ts";
+import { readStatus } from "../shared/utils.ts";
+import { resolveSubagentRunId } from "../runs/background/run-id-resolver.ts";
+import { resolveNodeExecutable } from "../shared/node-executable.ts";
+import { encodeSessionRoots } from "./session-roots-codec.ts";
+import { formatShellCommand } from "./shell-command.ts";
+import type { InspectorAction, InspectorContext, InspectorLaunch, InspectorParams, InspectorPlugin, InspectorTarget } from "./types.ts";
+
+export { INSPECTOR_ACTIONS } from "./types.ts";
+export type { InspectorAction, InspectorParams, InspectorPlugin } from "./types.ts";
+
+function result(text: string, isError = false): AgentToolResult<Details> {
+	const response: AgentToolResult<Details> = {
+		content: [{ type: "text", text }],
+		details: { mode: "management", results: [] },
+	};
+	if (isError) response.isError = true;
+	return response;
+}
+
+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 trustedDir(dir: string, deps: InspectorDispatcherDeps): boolean {
+	try {
+		if (fs.lstatSync(dir).isSymbolicLink() || !fs.statSync(dir).isDirectory()) return false;
+		const real = fs.realpathSync(dir);
+		if ([...(deps.state?.asyncJobs.values() ?? []), ...(deps.state?.fleetJobs?.values() ?? [])].some((job) => {
+			try {
+				return fs.realpathSync(job.asyncDir) === real;
+			} catch {
+				return false;
+			}
+		})) return true;
+		const root = deps.asyncDirRoot ?? DIRS.async;
+		return fs.existsSync(root) && pathWithin(root, dir) && pathWithin(fs.realpathSync(root), real);
+	} catch { return false; }
+}
+function resolveTarget(params: InspectorParams, deps: InspectorDispatcherDeps): InspectorTarget | { error: string } {
+	const requested = params.id ?? params.runId;
+	let runId: string;
+	let asyncDir: string;
+	if (params.dir) {
+		asyncDir = path.resolve(params.dir);
+		if (!trustedDir(asyncDir, deps)) return { error: `Async run directory '${asyncDir}' is outside trusted run roots.` };
+		const status = readStatus(asyncDir);
+		if (!status) return { error: `No async run status found in '${asyncDir}'.` };
+		if (requested && requested !== status.runId && !status.runId.startsWith(requested)) return { error: `Run '${requested}' does not match status run '${status.runId}'.` };
+		runId = status.runId;
+	} else {
+		if (!requested) return { error: "Inspector actions require id or dir." };
+		try {
+			const found = resolveSubagentRunId(requested, { state: deps.state, asyncDirRoot: deps.asyncDirRoot ?? DIRS.async, resultsDir: deps.resultsDir ?? DIRS.results });
+			if (!found) return { error: `No subagent run found for '${requested}'.` };
+			if (found.kind !== "async" || !found.location.asyncDir) return { error: `Run '${found.id}' is not an inspectable async run with lifecycle artifacts.` };
+			runId = found.id;
+			asyncDir = found.location.asyncDir;
+		} catch (cause) {
+			return { error: cause instanceof Error ? cause.message : String(cause) };
+		}
+	}
+	const status = readStatus(asyncDir);
+	if (!status) return { error: `No lifecycle status exists for async run '${runId}'.` };
+	if (params.index !== undefined && (params.index < 0 || params.index >= (status.steps?.length ?? 0))) return { error: `Async run '${runId}' has ${status.steps?.length ?? 0} children. Index ${params.index} is out of range.` };
+	const target: InspectorTarget = { runId, asyncDir, status: { cwd: status.cwd, state: status.state, steps: status.steps } };
+	if (params.index !== undefined) target.index = params.index;
+	return target;
+}
+function missionFor(target: InspectorTarget, deps: InspectorDispatcherDeps): { id: string; path: string } | undefined {
+	try {
+		const binding = readMissionBinding(target.asyncDir);
+		if (binding) return { id: binding.missionId, path: missionRecordPath(binding.location, binding.missionId) };
+		const location = resolveMissionStoreLocation(deps.missions ? { projectRoot: deps.cwd, config: deps.missions } : { projectRoot: deps.cwd });
+		const mission = listMissions(location).records.find((record) => record.runs.some((run) => run.runId === target.runId));
+		return mission ? { id: mission.id, path: missionRecordPath(location, mission.id) } : undefined;
+	} catch {
+		return undefined;
+	}
+}
+function launchFor(target: InspectorTarget, deps: InspectorDispatcherDeps): InspectorLaunch {
+	const mission = missionFor(target, deps);
+	const runnerPath = deps.runnerPath ?? fileURLToPath(new URL("../../inspector-runner.mjs", import.meta.url));
+	const job = deps.state?.asyncJobs.get(target.runId) ?? deps.state?.fleetJobs?.get(target.runId);
+	const sessionRoots = [...new Set([...(deps.sessionRoots ?? deps.state?.trustedSessionRoots ?? []), ...(job?.sessionRoot ? [job.sessionRoot] : [])])];
+	const allowSteer = resolveAuthorityDecision({ action: "steerRun", policy: deps.authorityPolicy }) === "auto";
+	const allowStop = resolveAuthorityDecision({ action: "stopRun", policy: deps.authorityPolicy }) === "auto";
+	const argv = [runnerPath, "--async-dir", target.asyncDir, "--run-id", target.runId, "--allow-steer", String(allowSteer), "--allow-stop", String(allowStop), "--session-roots", encodeSessionRoots(sessionRoots)];
+	if (target.index !== undefined) argv.push("--index", String(target.index));
+	if (mission) argv.push("--mission-path", mission.path);
+	const executable = resolveNodeExecutable();
+	const launch: InspectorLaunch = { executable, argv, displayCommand: formatShellCommand(executable, argv), allowSteer, allowStop, sessionRoots };
+	if (mission) launch.mission = mission;
+	return launch;
+}
+
+export interface InspectorDispatcherDeps {
+	state?: SubagentState;
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	missions?: MissionStoreConfig;
+	authorityPolicy?: AuthorityPolicyConfig;
+	sessionRoots?: string[];
+	cwd: string;
+	signal?: AbortSignal;
+	now?: () => Date;
+	runnerPath?: string;
+	env?: NodeJS.ProcessEnv;
+	plugins?: readonly InspectorPlugin[];
+}
+export async function handleInspectorAction(action: InspectorAction, params: InspectorParams, deps: InspectorDispatcherDeps): Promise<AgentToolResult<Details>> {
+	const target = resolveTarget(params, deps);
+	if ("error" in target) return result(target.error, true);
+	const context: InspectorContext = {
+		cwd: deps.cwd,
+		signal: deps.signal,
+		env: deps.env ?? process.env,
+		target,
+	};
+	if (deps.now) context.now = deps.now;
+	if (action === "inspector.command") return result(launchFor(target, deps).displayCommand);
+	const plugins = deps.plugins ?? [];
+	if (action === "inspector.open") {
+		for (const plugin of plugins) {
+			if (await plugin.available(context)) return plugin.open(context, launchFor(target, deps), params);
+		}
+		return result("No inspector plugin is available. Start a supported inspector host, or use inspector.command for a standalone command.", true);
+	}
+	const owner = plugins.find((plugin) => plugin.owns(context));
+	if (!owner) return result(`No inspector plugin owns this binding for async run ${target.runId}.`);
+	if (action === "inspector.status") {
+		return owner.status
+			? owner.status(context)
+			: result(`Inspector plugin '${owner.name}' does not support status for async run ${target.runId}.`, true);
+	}
+	return owner.close
+		? owner.close(context)
+		: result(`Inspector plugin '${owner.name}' does not support close for async run ${target.runId}.`, true);
+}

package/src/inspectors/ghostty/actions.ts

@@ -0,0 +1,74 @@
+import { execFile, type ExecFileOptionsWithStringEncoding } from "node:child_process";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Details } from "../../shared/types.ts";
+import type { InspectorContext, InspectorLaunch, InspectorParams } from "../types.ts";
+
+/** Static Ghostty 1.3 AppleScript; dynamic values arrive as `on run argv` arguments. */
+export const GHOSTTY_APPLESCRIPT = `on run argv
+  set launchCommand to item 1 of argv
+  set launchCwd to item 2 of argv
+  set shouldFocus to item 3 of argv
+  tell application "Ghostty"
+    set sourceWindow to front window
+    set sourceTab to selected tab of sourceWindow
+    set sourceTerminal to focused terminal of sourceTab
+    set surfaceConfiguration to new surface configuration
+    set initial working directory of surfaceConfiguration to launchCwd
+    set command of surfaceConfiguration to launchCommand
+    set newTerminal to split sourceTerminal direction right with configuration surfaceConfiguration
+    if shouldFocus is "true" then
+      focus newTerminal
+    else
+      focus sourceTerminal
+    end if
+    return id of newTerminal
+  end tell
+end run`;
+
+export type GhosttyRunner = (args: readonly string[], options: ExecFileOptionsWithStringEncoding) => Promise<{ stdout: string; stderr: string }>;
+
+function defaultRunner(args: readonly string[], options: ExecFileOptionsWithStringEncoding): Promise<{ stdout: string; stderr: string }> {
+	return new Promise((resolve, reject) => {
+		execFile("/usr/bin/osascript", [...args], options, (error, stdout, stderr) => {
+			if (error) {
+				const failure = error instanceof Error ? error : new Error(String(error));
+				reject(failure);
+				return;
+			}
+			resolve({ stdout, stderr });
+		});
+	});
+}
+
+function result(text: string, isError = false): AgentToolResult<Details> {
+	const response: AgentToolResult<Details> = {
+		content: [{ type: "text", text }],
+		details: { mode: "management", results: [] },
+	};
+	if (isError) response.isError = true;
+	return response;
+}
+
+const failureHint = "Ghostty inspector requires Ghostty 1.3+ and Automation permission for osascript.";
+
+export async function openGhosttyInspector(
+	context: InspectorContext,
+	launch: InspectorLaunch,
+	params: InspectorParams,
+	runner: GhosttyRunner = defaultRunner,
+): Promise<AgentToolResult<Details>> {
+	try {
+		const output = await runner(["-e", GHOSTTY_APPLESCRIPT, "--", launch.displayCommand, context.target.status.cwd ?? context.cwd, params.focus === true ? "true" : "false"], {
+			signal: context.signal,
+			timeout: 15_000,
+			encoding: "utf8",
+			maxBuffer: 64 * 1024,
+		});
+		const id = output.stdout.trim();
+		if (!id) return result(`Ghostty inspector error: Ghostty returned an empty terminal id. ${failureHint}`, true);
+		return result(`Opened read-only Ghostty inspector terminal ${id} for async run ${context.target.runId}. Status and close are unavailable because this plugin writes no binding.`);
+	} catch (cause) {
+		const message = cause instanceof Error ? cause.message : String(cause);
+		return result(`Ghostty inspector error: ${message}. ${failureHint}`, true);
+	}
+}

package/src/inspectors/ghostty/plugin.ts

@@ -0,0 +1,17 @@
+import { openGhosttyInspector, type GhosttyRunner } from "./actions.ts";
+import type { InspectorPlugin } from "../types.ts";
+
+export interface GhosttyPluginDeps {
+	platform?: NodeJS.Platform;
+	runner?: GhosttyRunner;
+}
+
+export function createGhosttyInspectorPlugin(deps: GhosttyPluginDeps = {}): InspectorPlugin {
+	const platform = deps.platform ?? process.platform;
+	return {
+		name: "ghostty",
+		available: (context) => platform === "darwin" && context.env.TERM_PROGRAM?.toLowerCase() === "ghostty",
+		owns: () => false,
+		open: (context, launch, params) => openGhosttyInspector(context, launch, params, deps.runner),
+	};
+}

package/src/inspectors/herdr/actions.ts

@@ -1,22 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { readMissionBinding } from "../../missions/lifecycle.ts";
-import { listMissions, missionRecordPath, resolveMissionStoreLocation } from "../../missions/store.ts";
-import type { MissionStoreConfig } from "../../missions/types.ts";
-import { resolveAuthorityDecision, type AuthorityPolicyConfig } from "../../policy/authority.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { DIRS, type Details, type SubagentState } from "../../shared/types.ts";
-import { readStatus } from "../../shared/utils.ts";
-import { resolveSubagentRunId } from "../../runs/background/run-id-resolver.ts";
-import { resolveNodeExecutable } from "../../shared/node-executable.ts";
-import { createHerdrClient, detectHerdr, type HerdrClient, type HerdrErrorCode, type HerdrResult } from "./client.ts";
-import { encodeSessionRoots } from "./session-roots-codec.ts";
-import { formatShellCommand } from "./shell-command.ts";
-
-export const HERDR_INSPECTOR_ACTIONS = ["inspector.open", "inspector.status", "inspector.close"] as const;
-export type HerdrInspectorAction = typeof HERDR_INSPECTOR_ACTIONS[number];
+import type { Details } from "../../shared/types.ts";
+import type { InspectorContext, InspectorLaunch, InspectorParams, InspectorTarget } from "../types.ts";
+import { detectHerdr, type HerdrClient, type HerdrErrorCode, type HerdrResult } from "./client.ts";
 
 export interface HerdrInspectorBinding {
 	schemaVersion: 1;
@@ -33,203 +21,135 @@ export interface HerdrInspectorBinding {
 	command: string;
 }
 
-interface InspectorParams {
-	id?: string;
-	runId?: string;
-	dir?: string;
-	index?: number;
-	focus?: boolean;
-}
-
-interface InspectorDeps {
-	state?: SubagentState;
-	asyncDirRoot?: string;
-	resultsDir?: string;
-	client?: HerdrClient;
-	missions?: MissionStoreConfig;
-	authorityPolicy?: AuthorityPolicyConfig;
-	sessionRoots?: string[];
-	cwd: string;
-	signal?: AbortSignal;
-	now?: () => Date;
-	runnerPath?: string;
-}
-
-function result(text: string, isError = false): AgentToolResult<Details> {
-	return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}), details: { mode: "management", results: [] } };
-}
-
-function formatHerdrError(input: { code: HerdrErrorCode; message: string }): string {
-	return `Herdr inspector error (${input.code}): ${input.message}`;
-}
-
-function bindingPath(asyncDir: string, index?: number): string {
+export function bindingPath(asyncDir: string, index?: number): string {
 	return path.join(asyncDir, "inspectors", `herdr${index === undefined ? "" : `-${index}`}.json`);
 }
 
-function parseBinding(value: unknown): HerdrInspectorBinding | undefined {
+function parse(value: unknown): HerdrInspectorBinding | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const input = value as Partial<HerdrInspectorBinding>;
-	if (input.schemaVersion !== 1 || input.kind !== "herdr-inspector") return undefined;
-	if (typeof input.runId !== "string" || typeof input.asyncDir !== "string" || typeof input.paneId !== "string" || typeof input.openedAt !== "string" || typeof input.command !== "string") return undefined;
-	if (input.childIndex !== undefined && (!Number.isInteger(input.childIndex) || input.childIndex < 0)) return undefined;
-	return input as HerdrInspectorBinding;
+	const binding = value as Partial<HerdrInspectorBinding>;
+	if (binding.schemaVersion !== 1
+		|| binding.kind !== "herdr-inspector"
+		|| (binding.childIndex !== undefined && (!Number.isInteger(binding.childIndex) || binding.childIndex < 0))
+		|| typeof binding.runId !== "string"
+		|| typeof binding.asyncDir !== "string"
+		|| typeof binding.paneId !== "string"
+		|| typeof binding.openedAt !== "string"
+		|| typeof binding.command !== "string") return undefined;
+	return binding as HerdrInspectorBinding;
 }
 
 export function readHerdrInspectorBinding(asyncDir: string, index?: number): HerdrInspectorBinding | undefined {
-	try { return parseBinding(JSON.parse(fs.readFileSync(bindingPath(asyncDir, index), "utf-8"))); } catch { return undefined; }
-}
-
-function extractPaneId(value: unknown): string | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const record = value as Record<string, unknown>;
-	const pane = record.pane && typeof record.pane === "object" && !Array.isArray(record.pane) ? record.pane as Record<string, unknown> : record;
-	for (const key of ["pane_id", "paneId", "id"]) if (typeof pane[key] === "string") return pane[key];
-	return undefined;
-}
-
-function inspectorCommand(input: { runnerPath: string; asyncDir: string; runId: string; index?: number; missionPath?: string; allowSteer: boolean; allowStop: boolean; sessionRoots: string[] }): string {
-	const args = [input.runnerPath, "--async-dir", input.asyncDir, "--run-id", input.runId, "--allow-steer", String(input.allowSteer), "--allow-stop", String(input.allowStop), "--session-roots", encodeSessionRoots(input.sessionRoots)];
-	if (input.index !== undefined) args.push("--index", String(input.index));
-	if (input.missionPath) args.push("--mission-path", input.missionPath);
-	return formatShellCommand(resolveNodeExecutable(), args);
-}
-
-function missionForRun(asyncDir: string, cwd: string, config: MissionStoreConfig | undefined, runId: string): { id: string; path: string } | undefined {
 	try {
-		const binding = readMissionBinding(asyncDir);
-		if (binding) return { id: binding.missionId, path: missionRecordPath(binding.location, binding.missionId) };
-		const location = resolveMissionStoreLocation({ projectRoot: cwd, ...(config ? { config } : {}) });
-		const mission = listMissions(location).records.find((record) => record.runs.some((run) => run.runId === runId));
-		return mission ? { id: mission.id, path: missionRecordPath(location, mission.id) } : undefined;
+		return parse(JSON.parse(fs.readFileSync(bindingPath(asyncDir, index), "utf8")));
 	} catch {
 		return undefined;
 	}
 }
 
-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 herdrSessionRoots(target: { runId: string }, deps: InspectorDeps): string[] {
-	const roots = deps.sessionRoots ?? deps.state?.trustedSessionRoots ?? [];
-	const job = deps.state?.asyncJobs.get(target.runId) ?? deps.state?.fleetJobs?.get(target.runId);
-	return [...new Set([...roots, ...(job?.sessionRoot ? [job.sessionRoot] : [])])];
-}
-
-function isTrustedAsyncDir(asyncDir: string, deps: InspectorDeps): boolean {
+/** Read a binding only when it belongs to the requested inspector target. */
+export function readHerdrInspectorBindingForTarget(target: InspectorTarget): HerdrInspectorBinding | undefined {
+	const binding = readHerdrInspectorBinding(target.asyncDir, target.index);
+	if (!binding || binding.runId !== target.runId || binding.childIndex !== target.index) return undefined;
 	try {
-		if (fs.lstatSync(asyncDir).isSymbolicLink() || !fs.statSync(asyncDir).isDirectory()) return false;
-		const realDir = fs.realpathSync(asyncDir);
-		const registered = [...(deps.state?.asyncJobs.values() ?? [])].some((job) => {
-			try { return fs.realpathSync(job.asyncDir) === realDir; } catch { return false; }
-		});
-		if (registered) return true;
-		const root = deps.asyncDirRoot ?? DIRS.async;
-		if (!fs.existsSync(root) || !pathWithin(root, asyncDir)) return false;
-		return pathWithin(fs.realpathSync(root), realDir);
+		if (fs.realpathSync(binding.asyncDir) !== fs.realpathSync(target.asyncDir)) return undefined;
 	} catch {
-		return false;
+		return undefined;
 	}
+	return binding;
 }
 
-function resolveAsyncTarget(params: InspectorParams, deps: InspectorDeps): { runId: string; asyncDir: string } | { error: string } {
-	const requestedId = params.id ?? params.runId;
-	if (params.dir) {
-		const asyncDir = path.resolve(params.dir);
-		if (!isTrustedAsyncDir(asyncDir, deps)) return { error: `Async run directory '${asyncDir}' is outside trusted run roots.` };
-		const status = readStatus(asyncDir);
-		if (!status) return { error: `No async run status found in '${asyncDir}'.` };
-		if (requestedId && requestedId !== status.runId && !status.runId.startsWith(requestedId)) return { error: `Run '${requestedId}' does not match status run '${status.runId}'.` };
-		return { runId: status.runId, asyncDir };
-	}
-	if (!requestedId) return { error: "Herdr inspector actions require id or dir." };
-	try {
-		const resolved = resolveSubagentRunId(requestedId, { state: deps.state, asyncDirRoot: deps.asyncDirRoot ?? DIRS.async, resultsDir: deps.resultsDir ?? DIRS.results });
-		if (!resolved) return { error: `No subagent run found for '${requestedId}'.` };
-		if (resolved.kind !== "async" || !resolved.location.asyncDir) return { error: `Run '${resolved.id}' is not an inspectable async run with lifecycle artifacts.` };
-		return { runId: resolved.id, asyncDir: resolved.location.asyncDir };
-	} catch (cause) {
-		return { error: cause instanceof Error ? cause.message : String(cause) };
-	}
+function result(text: string, isError = false): AgentToolResult<Details> {
+	return {
+		content: [{ type: "text", text }],
+		...(isError ? { isError: true } : {}),
+		details: { mode: "management", results: [] },
+	};
 }
 
-async function paneExists(client: HerdrClient, paneId: string, signal?: AbortSignal): Promise<HerdrResult<unknown>> {
-	return client.run(["pane", "get", paneId], { timeoutMs: 5_000, signal });
+function errorText(input: { code: HerdrErrorCode; message: string }): string {
+	return `Herdr inspector error (${input.code}): ${input.message}`;
 }
 
-export async function handleHerdrInspectorAction(action: HerdrInspectorAction, params: InspectorParams, deps: InspectorDeps): Promise<AgentToolResult<Details>> {
-	const target = resolveAsyncTarget(params, deps);
-	if ("error" in target) return result(target.error, true);
-	const status = readStatus(target.asyncDir);
-	if (!status) return result(`No lifecycle status exists for async run '${target.runId}'.`, true);
-	if (params.index !== undefined && (params.index < 0 || params.index >= (status.steps?.length ?? 0))) {
-		return result(`Async run '${target.runId}' has ${status.steps?.length ?? 0} children. Index ${params.index} is out of range.`, true);
-	}
-	const existing = readHerdrInspectorBinding(target.asyncDir, params.index);
-	const client = deps.client ?? createHerdrClient();
-
-	if (action === "inspector.status") {
-		if (!existing) return result(`No Herdr inspector binding exists for async run ${target.runId}${params.index === undefined ? "" : ` child ${params.index}`}.`);
-		const live = await paneExists(client, existing.paneId, deps.signal);
-		if (live.ok === false) return result(`${formatHerdrError(live.error)}\nBinding: ${bindingPath(target.asyncDir, params.index)}\nRun state remains authoritative: ${status.state}.`, true);
-		return result(`Herdr inspector ${existing.paneId} is open for async run ${target.runId}.\nRun state: ${status.state}\nBinding: ${bindingPath(target.asyncDir, params.index)}`);
+function paneId(value: unknown): string | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const pane = record.pane && typeof record.pane === "object" ? record.pane as Record<string, unknown> : record;
+	for (const key of ["pane_id", "paneId", "id"]) {
+		if (typeof pane[key] === "string") return pane[key];
 	}
+	return undefined;
+}
 
+async function pane(client: HerdrClient, id: string, signal?: AbortSignal): Promise<HerdrResult<unknown>> {
+	return client.run(["pane", "get", id], { timeoutMs: 5_000, signal });
+}
 
-	if (action === "inspector.close") {
-		if (!existing) return result(`No Herdr inspector binding exists for async run ${target.runId}.`);
-		const closed = await client.run(["pane", "close", existing.paneId], { timeoutMs: 10_000, signal: deps.signal });
-		if (closed.ok === false && closed.error.code !== "NOT_FOUND" && closed.error.code !== "PANE_GONE") return result(formatHerdrError(closed.error), true);
-		fs.rmSync(bindingPath(target.asyncDir, params.index), { force: true });
-		return result(`Closed Herdr inspector pane ${existing.paneId} for async run ${target.runId}. The subagent run was not stopped.`);
-	}
-
-	const detected = await detectHerdr(client, deps.signal);
-	if (detected.ok === false) return result(formatHerdrError(detected.error), true);
+export async function openHerdrInspector(
+	context: InspectorContext,
+	launch: InspectorLaunch,
+	params: InspectorParams,
+	client: HerdrClient,
+): Promise<AgentToolResult<Details>> {
+	const detected = await detectHerdr(client, context.signal);
+	if (!detected.ok) return result(errorText(detected.error), true);
+	const existing = readHerdrInspectorBindingForTarget(context.target);
 	if (existing) {
-		const live = await paneExists(client, existing.paneId, deps.signal);
-		if (live.ok) return result(`Herdr inspector pane ${existing.paneId} is already open for async run ${target.runId}.${params.focus ? " Herdr cannot refocus an arbitrary raw pane id; select it in the Herdr UI." : ""}`);
+		const current = await pane(client, existing.paneId, context.signal);
+		if (current.ok && paneId(current.data) === existing.paneId) {
+			return result(`Herdr inspector pane ${existing.paneId} is already open for async run ${context.target.runId}.${params.focus ? " Herdr cannot refocus an arbitrary raw pane id; select it in the Herdr UI." : ""}`);
+		}
 	}
-	const splitArgs = ["pane", "split", "--current", "--direction", "right", "--cwd", status.cwd ?? deps.cwd];
-	splitArgs.push(params.focus === true ? "--focus" : "--no-focus");
-	const split = await client.run(splitArgs, { timeoutMs: 15_000, signal: deps.signal });
-	if (split.ok === false) return result(formatHerdrError(split.error), true);
-	const paneId = extractPaneId(split.data);
-	if (!paneId) return result("Herdr inspector error (PANE_GONE): pane split returned no pane id.", true);
-	const mission = missionForRun(target.asyncDir, deps.cwd, deps.missions, target.runId);
-	const runnerPath = deps.runnerPath ?? fileURLToPath(new URL("../../../inspector-runner.mjs", import.meta.url));
-	const command = inspectorCommand({
-		runnerPath,
-		asyncDir: target.asyncDir,
-		runId: target.runId,
-		index: params.index,
-		missionPath: mission?.path,
-		allowSteer: resolveAuthorityDecision({ action: "steerRun", policy: deps.authorityPolicy }) === "auto",
-		allowStop: resolveAuthorityDecision({ action: "stopRun", policy: deps.authorityPolicy }) === "auto",
-		sessionRoots: herdrSessionRoots(target, deps),
-	});
-	const started = await client.run(["pane", "run", paneId, command], { timeoutMs: 15_000, signal: deps.signal });
-	if (started.ok === false) {
-		await client.run(["pane", "close", paneId], { timeoutMs: 5_000 });
-		return result(formatHerdrError(started.error), true);
+	const split = await client.run([
+		"pane", "split", "--current", "--direction", "right",
+		"--cwd", context.target.status.cwd ?? context.cwd,
+		params.focus === true ? "--focus" : "--no-focus",
+	], { timeoutMs: 15_000, signal: context.signal });
+	if (!split.ok) return result(errorText(split.error), true);
+	const id = paneId(split.data);
+	if (!id) return result("Herdr inspector error (PANE_GONE): pane split returned no pane id.", true);
+	const started = await client.run(["pane", "run", id, launch.displayCommand], { timeoutMs: 15_000, signal: context.signal });
+	if (!started.ok) {
+		await client.run(["pane", "close", id], { timeoutMs: 5_000 });
+		return result(errorText(started.error), true);
 	}
-	const now = (deps.now?.() ?? new Date()).toISOString();
+	const now = (context.now?.() ?? new Date()).toISOString();
 	const binding: HerdrInspectorBinding = {
 		schemaVersion: 1,
 		kind: "herdr-inspector",
-		runId: target.runId,
-		asyncDir: target.asyncDir,
-		...(params.index !== undefined ? { childIndex: params.index } : {}),
-		...(mission ? { missionId: mission.id, missionPath: mission.path } : {}),
-		paneId,
+		runId: context.target.runId,
+		asyncDir: context.target.asyncDir,
+		...(context.target.index === undefined ? {} : { childIndex: context.target.index }),
+		...(launch.mission ? { missionId: launch.mission.id, missionPath: launch.mission.path } : {}),
+		paneId: id,
 		openedAt: now,
 		...(params.focus === true ? { lastFocusedAt: now } : {}),
 		herdrVersion: detected.data.versionText,
-		command,
+		command: launch.displayCommand,
 	};
-	writeAtomicJson(bindingPath(target.asyncDir, params.index), binding);
-	return result(`Opened read-only Herdr inspector pane ${paneId} for async run ${target.runId}. Closing the pane does not stop the run.\nControls inside the pane: steer <message>, stop, status.`);
+	writeAtomicJson(bindingPath(context.target.asyncDir, context.target.index), binding);
+	return result(`Opened read-only Herdr inspector pane ${id} for async run ${context.target.runId}. Closing the pane does not stop the run.\nControls inside the pane: steer <message>, stop, status.`);
+}
+
+export async function statusHerdrInspector(context: InspectorContext, client: HerdrClient): Promise<AgentToolResult<Details>> {
+	const binding = readHerdrInspectorBindingForTarget(context.target);
+	if (!binding) {
+		return result(`No Herdr inspector binding exists for async run ${context.target.runId}${context.target.index === undefined ? "" : ` child ${context.target.index}`}.`);
+	}
+	const live = await pane(client, binding.paneId, context.signal);
+	if (!live.ok) {
+		return result(`${errorText(live.error)}\nBinding: ${bindingPath(context.target.asyncDir, context.target.index)}\nRun state remains authoritative: ${context.target.status.state}.`, true);
+	}
+	return result(`Herdr inspector ${binding.paneId} is open for async run ${context.target.runId}.\nRun state: ${context.target.status.state}\nBinding: ${bindingPath(context.target.asyncDir, context.target.index)}`);
+}
+
+export async function closeHerdrInspector(context: InspectorContext, client: HerdrClient): Promise<AgentToolResult<Details>> {
+	const binding = readHerdrInspectorBindingForTarget(context.target);
+	if (!binding) return result(`No Herdr inspector binding exists for async run ${context.target.runId}.`);
+	const closed = await client.run(["pane", "close", binding.paneId], { timeoutMs: 10_000, signal: context.signal });
+	if (!closed.ok && closed.error.code !== "NOT_FOUND" && closed.error.code !== "PANE_GONE") {
+		return result(errorText(closed.error), true);
+	}
+	fs.rmSync(bindingPath(context.target.asyncDir, context.target.index), { force: true });
+	return result(`Closed Herdr inspector pane ${binding.paneId} for async run ${context.target.runId}. The subagent run was not stopped.`);
 }

package/src/inspectors/herdr/plugin.ts

@@ -0,0 +1,20 @@
+import { createHerdrClient, type HerdrClient } from "./client.ts";
+import { closeHerdrInspector, openHerdrInspector, readHerdrInspectorBindingForTarget, statusHerdrInspector } from "./actions.ts";
+import type { InspectorPlugin } from "../types.ts";
+
+export interface HerdrPluginDeps {
+	client?: HerdrClient;
+}
+
+export function createHerdrInspectorPlugin(deps: HerdrPluginDeps = {}): InspectorPlugin {
+	const client = deps.client ?? createHerdrClient();
+	return {
+		name: "herdr",
+		available: async (context) => context.env.HERDR_ENV === "1"
+			&& Boolean(context.env.HERDR_PANE_ID?.trim()),
+		owns: (context) => readHerdrInspectorBindingForTarget(context.target) !== undefined,
+		open: (context, launch, params) => openHerdrInspector(context, launch, params, client),
+		status: (context) => statusHerdrInspector(context, client),
+		close: (context) => closeHerdrInspector(context, client),
+	};
+}

package/src/inspectors/herdr/project-panes.ts

@@ -7,7 +7,7 @@ import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import type { Details, HerdrProjectPaneSnapshot, SubagentState } from "../../shared/types.ts";
 import { createHerdrClient, detectHerdr, type HerdrClient, type HerdrErrorCode } from "./client.ts";
 import { focusHerdrPane, herdrPaneFocusTarget, herdrPaneRecord } from "./focus.ts";
-import { formatShellCommand } from "./shell-command.ts";
+import { formatShellCommand } from "../shell-command.ts";
 
 export const HERDR_PROJECT_PANE_ACTIONS = ["project.open", "project.status", "project.close"] as const;
 export type HerdrProjectPaneAction = typeof HERDR_PROJECT_PANE_ACTIONS[number];