pi-subagents 0.66.0 → 0.67.0

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];

package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts}

@@ -2,13 +2,13 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as readline from "node:readline";
 import { fileURLToPath } from "node:url";
-import { parseMissionRecord } from "../../missions/store.ts";
-import type { MissionRecord } from "../../missions/types.ts";
-import { requestAsyncSteer, requestAsyncStop } from "../../runs/background/control-channel.ts";
-import { formatAsyncRunTranscript } from "../../runs/background/fleet-view.ts";
-import { steeringReceipt } from "../../runs/background/steering.ts";
-import type { AsyncStatus } from "../../shared/types.ts";
-import { readStatus } from "../../shared/utils.ts";
+import { parseMissionRecord } from "../missions/store.ts";
+import type { MissionRecord } from "../missions/types.ts";
+import { requestAsyncSteer, requestAsyncStop } from "../runs/background/control-channel.ts";
+import { formatAsyncRunTranscript } from "../runs/background/fleet-view.ts";
+import { steeringReceipt } from "../runs/background/steering.ts";
+import type { AsyncStatus } from "../shared/types.ts";
+import { readStatus } from "../shared/utils.ts";
 import { decodeSessionRoots } from "./session-roots-codec.ts";
 
 export interface RunnerOptions {
@@ -31,7 +31,7 @@ export function formatInspectorDashboard(input: { status: AsyncStatus; asyncDir:
 	const { status, asyncDir, mission } = input;
 	const lines = [
 		`pi-subagents inspector for ${status.runId}`,
-		"This pane mirrors lifecycle artifacts; closing it does not stop the run.",
+		"This inspector mirrors lifecycle artifacts; closing it does not stop the run.",
 		"",
 	];
 	if (mission) {
@@ -43,7 +43,7 @@ export function formatInspectorDashboard(input: { status: AsyncStatus; asyncDir:
 	lines.push(formatAsyncRunTranscript(status, asyncDir, { index: input.index, lines: 60, sessionRoots: input.sessionRoots }));
 	const acceptsPlainGuidance = input.index !== undefined || status.mode === "single";
 	const controls = [input.allowSteer === false || !acceptsPlainGuidance ? undefined : "type guidance", input.allowSteer === false ? undefined : "steer <message>", input.allowStop === false ? undefined : "stop", "status"].filter(Boolean);
-	lines.push("", `Controls: ${controls.join(" | ")}`, "Supervisor replies remain in the parent Pi session (subagent_supervisor/intercom).");
+	lines.push("", `Controls: ${controls.join(" | ")}`, "Supervisor replies remain in the parent Pi session (subagent_supervisor/intercom); this inspector is read-only.");
 	return lines.join("\n");
 }
 
@@ -91,7 +91,7 @@ function queueInspectorSteer(options: RunnerOptions, status: AsyncStatus, messag
 	requestAsyncSteer(options.asyncDir, {
 		message,
 		...(targetIndex !== undefined ? { targetIndex } : { targetIndexes: runningIndexes }),
-		source: "herdr-inspector",
+		source: "inspector-runner",
 	});
 	return steeringReceipt(message, `Steering queued for run ${options.runId}.`);
 }
@@ -104,7 +104,7 @@ export function submitInspectorControl(options: RunnerOptions, line: string): st
 	if (command === "stop") {
 		if (options.allowStop === false) throw new Error("Authority policy does not allow stop from this inspector.");
 		if (isTerminal(status)) throw new Error(`Run '${options.runId}' is ${status.state} and cannot be stopped.`);
-		requestAsyncStop(options.asyncDir, { source: "herdr-inspector" });
+		requestAsyncStop(options.asyncDir, { source: "inspector-runner" });
 		return `Stop requested for run ${options.runId}.`;
 	}
 	if (command.startsWith("steer ")) {
@@ -147,7 +147,7 @@ export function runInspector(argv = process.argv.slice(2)): void {
 
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
 	try { runInspector(); } catch (cause) {
-		process.stderr.write(`Herdr inspector failed: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+		process.stderr.write(`Inspector failed: ${cause instanceof Error ? cause.message : String(cause)}\n`);
 		process.exitCode = 1;
 	}
 }

package/src/inspectors/plugins.ts

@@ -0,0 +1,8 @@
+import { createHerdrInspectorPlugin } from "./herdr/plugin.ts";
+import { createGhosttyInspectorPlugin } from "./ghostty/plugin.ts";
+import type { InspectorPlugin } from "./types.ts";
+
+/** Built-in inspector plugins, ordered by host preference. */
+export function createBuiltinInspectorPlugins(): readonly InspectorPlugin[] {
+	return [createHerdrInspectorPlugin(), createGhosttyInspectorPlugin()];
+}

package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts}

@@ -19,24 +19,13 @@ function parseStringArray(value: unknown): string[] | undefined {
 	return value;
 }
 
-/**
- * Decodes a `--session-roots` argument produced by {@link encodeSessionRoots}.
- * Falls back to parsing the value as raw JSON so any externally-launched
- * inspector runner (a cached copy, or a manual invocation) that still passes
- * the legacy unencoded form keeps working.
- */
+/** Decodes a `--session-roots` argument produced by {@link encodeSessionRoots}. */
 export function decodeSessionRoots(raw: string): string[] {
 	try {
 		const decoded = parseStringArray(JSON.parse(Buffer.from(raw, "base64").toString("utf-8")));
 		if (decoded) return decoded;
 	} catch {
-		// fall through to legacy raw-JSON parsing below
-	}
-	try {
-		const parsed = parseStringArray(JSON.parse(raw));
-		if (parsed) return parsed;
-	} catch {
-		// fall through to the shared error below
+		// Report one stable validation error below.
 	}
-	throw new Error("--session-roots must be a base64-encoded or raw JSON array of strings.");
+	throw new Error("--session-roots must be a base64-encoded JSON array of strings.");
 }

package/src/inspectors/types.ts

@@ -0,0 +1,51 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Details } from "../shared/types.ts";
+
+export const INSPECTOR_ACTIONS = ["inspector.open", "inspector.command", "inspector.status", "inspector.close"] as const;
+export type InspectorAction = typeof INSPECTOR_ACTIONS[number];
+
+export interface InspectorParams {
+	id?: string;
+	runId?: string;
+	dir?: string;
+	index?: number;
+	focus?: boolean;
+}
+
+export interface InspectorTarget {
+	runId: string;
+	asyncDir: string;
+	index?: number;
+	status: {
+		cwd?: string;
+		state: string;
+		steps?: unknown[];
+	};
+}
+
+export interface InspectorContext {
+	cwd: string;
+	signal?: AbortSignal;
+	env: NodeJS.ProcessEnv;
+	now?: () => Date;
+	target: InspectorTarget;
+}
+
+export interface InspectorLaunch {
+	executable: string;
+	argv: string[];
+	displayCommand: string;
+	mission?: { id: string; path: string };
+	allowSteer: boolean;
+	allowStop: boolean;
+	sessionRoots: string[];
+}
+
+export interface InspectorPlugin {
+	readonly name: string;
+	available(context: InspectorContext): Promise<boolean> | boolean;
+	owns(context: InspectorContext): boolean;
+	open(context: InspectorContext, launch: InspectorLaunch, params: InspectorParams): Promise<AgentToolResult<Details>>;
+	status?(context: InspectorContext): Promise<AgentToolResult<Details>>;
+	close?(context: InspectorContext): Promise<AgentToolResult<Details>>;
+}