pi-subagents 0.67.0 → 0.69.0

package/src/runs/shared/child-tool-plan.ts

@@ -22,6 +22,7 @@ import {
 import { THINKING_LEVELS } from "../../shared/model-info.ts";
 import { getAgentDir } from "../../shared/utils.ts";
 import type { PermissionRules } from "./permissions.ts";
+import { snapshotRequiredChildExtensions, type RequiredChildExtensionSnapshot } from "../../shared/required-child-extensions.ts";
 import {
 	capabilityCeilingAgentRestrictionSources,
 	intersectSubagentCapabilityCeilings,
@@ -33,18 +34,18 @@ import {
 const MAX_LAUNCH_RESOLVED_EXTENSION_IDS = 32;
 const PROMPT_RUNTIME_EXTENSION_PATH = path.join(
 	path.dirname(fileURLToPath(import.meta.url)),
-	"subagent-prompt-runtime.ts",
+	`subagent-prompt-runtime${path.extname(fileURLToPath(import.meta.url))}`,
 );
 const FANOUT_CHILD_EXTENSION_PATH = path.join(
 	path.dirname(fileURLToPath(import.meta.url)),
 	"..",
 	"..",
 	"extension",
-	"fanout-child.ts",
+	`fanout-child${path.extname(fileURLToPath(import.meta.url))}`,
 );
 const FAST_MODE_EXTENSION_PATH = path.join(
 	path.dirname(fileURLToPath(import.meta.url)),
-	"fast-mode-extension.ts",
+	`fast-mode-extension${path.extname(fileURLToPath(import.meta.url))}`,
 );
 const SUBAGENT_RUNTIME_EXTENSION_PATHS = new Set([
 	PROMPT_RUNTIME_EXTENSION_PATH,
@@ -64,8 +65,6 @@ const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
 const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
 const REPOSITORY_INSPECTION_TOOLS = new Set(["read", "grep", "find", "ls", "bash", "powershell"]);
 const REVIEW_OR_SCOUT_AGENT_PATTERN = /\b(?:reviewer|scout)\b/i;
-// These providers come from child hooks, not the host's builtin tool registry.
-const NATIVE_COORDINATION_TOOL_NAMES = new Set(["subagent", "contact_supervisor", "subagent_supervisor"]);
 
 export function isReviewOrScoutLaneAgent(agentName: string | undefined): boolean {
 	return typeof agentName === "string" && REVIEW_OR_SCOUT_AGENT_PATTERN.test(agentName);
@@ -149,9 +148,9 @@ function stripThinkingSuffix(model: string): string {
 		: model;
 }
 
-function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fast" | "model" | "modelCandidates" | "agentName">): string[] {
+function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fast" | "model" | "agentName">): string[] {
 	if (!input.fast) return [];
-	const candidates = (input.modelCandidates?.length ? input.modelCandidates : input.model ? [input.model] : [])
+	const candidates = (input.model ? [input.model] : [])
 		.map(stripThinkingSuffix);
 	if (candidates.length === 0) {
 		throw new Error(`fast mode requires an explicit supported native OpenAI-Codex model${input.agentName ? ` for agent '${input.agentName}'` : ""}.`);
@@ -169,6 +168,7 @@ export interface ResolvePiLaunchToolPlanInput {
 	allowNestedSubagents?: boolean;
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
+	requiredExtensions?: RequiredChildExtensionSnapshot;
 	mcpDirectTools?: string[];
 	cwd?: string;
 	requireReadTool?: boolean;
@@ -181,19 +181,19 @@ export interface ResolvePiLaunchToolPlanInput {
 		  };
 	fast?: boolean;
 	model?: string;
-	modelCandidates?: readonly string[];
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
 	agentName?: string;
 	permissionRules?: PermissionRules;
 	runtimeSnapshotHost?: McpRuntimeSnapshotHost;
 	/**
-	 * When provided, child tool plans intersect declared builtin tools with
-	 * this set. Tools the agent declares but the host does not provide are
+	 * When provided, child tool plans intersect known Pi core tool slots with
+	 * this set. Core tools the agent declares but the host does not provide are
 	 * omitted with a non-fatal warning (tracked in `unavailableHostBuiltins`).
 	 * Review/scout lanes fail closed when a requested, still-permitted
 	 * repository inspection tool is among those host omissions. Intentionally
 	 * empty or ceiling-restricted allowlists are not a minimum-tool contract.
+	 * Non-core names remain allowed and are validated in the child's registry.
 	 */
 	hostAvailableBuiltins?: readonly string[];
 }
@@ -214,6 +214,7 @@ export interface PiLaunchToolPlan {
 	fanoutAuthorized: boolean;
 	runtimeExtensions: string[];
 	configuredExtensions: string[];
+	requiredExtensions: RequiredChildExtensionSnapshot;
 	extensionArgs: string[];
 	disableAmbientExtensions: boolean;
 	capabilityAudit?: SubagentCapabilityAudit;
@@ -258,6 +259,7 @@ export function projectLaunchResolvedChildExtensions(
 		PiLaunchToolPlan,
 		| "runtimeExtensions"
 		| "configuredExtensions"
+		| "requiredExtensions"
 		| "extensionArgs"
 		| "disableAmbientExtensions"
 	>,
@@ -271,10 +273,12 @@ export function projectLaunchResolvedChildExtensions(
 		disableAmbientExtensions: toolPlan.disableAmbientExtensions,
 		runtime: runtime.ids,
 		configured: configured.ids,
+		required: toolPlan.requiredExtensions.map(({ id }) => id),
 		effective: effective.ids,
 		omitted: {
 			runtime: runtime.omitted,
 			configured: configured.omitted,
+			required: 0,
 			effective: effective.omitted,
 		},
 	};
@@ -339,7 +343,8 @@ export function resolvePermissionSystemExtension(): string | undefined {
 /**
  * Extract the names of builtin tools the host provides. Use this to pass
  * `hostAvailableBuiltins` to `resolvePiLaunchToolPlan` so child tool plans
- * intersect declared agent tools with what the host actually supports.
+ * intersect known core slots with what the host actually supports. Wrapped
+ * core slots count regardless of source; host-specific builtins count too.
  *
  * Returns `undefined` when builtin tool discovery fails or yields nothing,
  * so callers skip the intersection (fail-safe to allowing all declared tools).
@@ -352,7 +357,7 @@ export function getHostBuiltinToolNames(pi: Pick<ExtensionAPI, "getAllTools">):
 			.getAllTools()
 			.filter((tool) => {
 				const source = (tool.sourceInfo as { source?: string } | undefined)?.source;
-				return source === "builtin" || (source === "auto" && PI_BUILTIN_TOOL_NAMES.has(tool.name));
+				return source === "builtin" || PI_BUILTIN_TOOL_NAMES.has(tool.name);
 			})
 			.map((tool) => tool.name);
 		return builtins.length > 0 ? builtins : undefined;
@@ -368,6 +373,10 @@ export function resolvePiLaunchToolPlan(
 		input.capabilityCeiling,
 		input.inheritedCapabilityCeiling,
 	);
+	const requiredExtensions = snapshotRequiredChildExtensions(input.requiredExtensions ?? []);
+	if (requiredExtensions.length > 0 && capabilityCeiling?.denyExtensions) {
+		throw new Error(`Capability ceiling from ${capabilityCeiling.sources.join(", ") || "unknown source"} denies extensions but this host requires: ${requiredExtensions.map(({ id }) => id).join(", ")}.`);
+	}
 	const allowedToolSet =
 		capabilityCeiling?.allowedTools === undefined
 			? undefined
@@ -405,10 +414,10 @@ export function resolvePiLaunchToolPlan(
 					: requestedBuiltinTools
 				).filter((tool) => !allowedToolSet || allowedToolSet.has(tool));
 	const declaredBuiltinTools = hostAvailableSet
-		? ceilingFilteredBuiltinTools.filter((tool) => hostAvailableSet.has(tool) || NATIVE_COORDINATION_TOOL_NAMES.has(tool))
+		? ceilingFilteredBuiltinTools.filter((tool) => !PI_BUILTIN_TOOL_NAMES.has(tool) || hostAvailableSet.has(tool))
 		: ceilingFilteredBuiltinTools;
 	const unavailableHostBuiltins = hostAvailableSet
-		? ceilingFilteredBuiltinTools.filter((tool) => !hostAvailableSet.has(tool) && !NATIVE_COORDINATION_TOOL_NAMES.has(tool))
+		? ceilingFilteredBuiltinTools.filter((tool) => PI_BUILTIN_TOOL_NAMES.has(tool) && !hostAvailableSet.has(tool))
 		: [];
 	const excludeTools = [...new Set((input.excludeTools ?? []).map((tool) => tool.trim()).filter(Boolean))];
 	const excludedToolSet = new Set(excludeTools);
@@ -483,7 +492,7 @@ export function resolvePiLaunchToolPlan(
 			? resolvePermissionSystemExtension()
 			: undefined;
 	if (input.fast && capabilityCeiling?.denyExtensions) throw new Error("fast mode requires a child runtime extension, but this launch denies extensions.");
-	const fastModeExtensions = resolveFastModeExtension({ fast: input.fast, model: input.model, modelCandidates: input.modelCandidates, agentName: input.agentName });
+	const fastModeExtensions = resolveFastModeExtension({ fast: input.fast, model: input.model, agentName: input.agentName });
 	const runtimeExtensions = [
 		PROMPT_RUNTIME_EXTENSION_PATH,
 		...fastModeExtensions,
@@ -510,7 +519,7 @@ export function resolvePiLaunchToolPlan(
 				...(input.extensions ?? []),
 				...(input.subagentOnlyExtensions ?? []),
 			];
-	const extensionArgs = disableAmbientExtensions
+	const ordinaryExtensionArgs = disableAmbientExtensions
 		? [...new Set([...runtimeExtensions, ...configuredExtensions])]
 		: [
 				...new Set([
@@ -519,6 +528,8 @@ export function resolvePiLaunchToolPlan(
 					...(input.subagentOnlyExtensions ?? []),
 				]),
 			];
+	// Host-required paths have final precedence and cannot be removed by agent defaults or overrides.
+	const extensionArgs = [...new Set([...ordinaryExtensionArgs, ...requiredExtensions.map(({ path }) => path)])];
 	const requestedToolNames =
 		input.tools !== undefined
 			? [
@@ -610,6 +621,7 @@ export function resolvePiLaunchToolPlan(
 		fanoutAuthorized,
 		runtimeExtensions,
 		configuredExtensions,
+		requiredExtensions,
 		extensionArgs,
 		disableAmbientExtensions,
 		warnings,

package/src/runs/shared/dynamic-fanout.ts

@@ -46,12 +46,12 @@ const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency
 const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "sessionFiles", "thinkingOverrides"]);
 const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
 const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
-const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "machine", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
 	...DYNAMIC_PARALLEL_KEYS,
 	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
 	"structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
-	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
+	"systemPromptMode", "thinking", "requestedModel", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "requiredExtensions", "launchResolvedExtensions", "requestedCwd", "machineEnv",
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
 

package/src/runs/shared/external-cli-contract.ts

@@ -2,7 +2,9 @@ import type {
 	ExternalCliReceiptMetadata,
 	ExternalCliCapabilityNarrowing,
 	ExternalCliRunnerStatus,
+	ExternalCliMachineStatus,
 	ExternalProcessStatus,
+	HerdrMachineReference,
 } from "../../shared/types.ts";
 
 const UNSUPPORTED = {
@@ -80,6 +82,7 @@ export function resolveExternalCliRunnerStatus(input: {
 	args?: string[];
 	promptDelivery?: "stdin";
 	capabilities?: ExternalCliCapabilityNarrowing;
+	machine?: HerdrMachineReference;
 }): ExternalCliRunnerStatus {
 	const codexExec = input.adapter === "codex-exec";
 	const codexExecWriter = input.adapter === "codex-exec-writer";
@@ -101,6 +104,7 @@ export function resolveExternalCliRunnerStatus(input: {
 		...(claudeCodeWriter ? { safety: { access: "workspace-write" as const, authentication: "existing-cli-required" as const, permissionMode: "acceptEdits" as const, tools: "Read,Write,Edit,Glob,Grep" as const, mcp: "empty-strict" as const, settingSources: "user" as const, userSettingsTrust: "required" as const, sessionPersistence: false as const } } : {}),
 		...(cursorAgent ? { safety: { access: "read-only" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "ask" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
 		...(cursorAgentWriter ? { safety: { access: "workspace-write" as const, authentication: "cursor-api-key-or-existing-login" as const, mode: "print" as const, sandbox: "enabled" as const, workspaceTrust: "existing-required" as const, sessionReuse: false as const } } : {}),
+		...(input.machine ? { machine: input.machine } : {}),
 		capabilities: {
 			stop: true,
 			steer: false,
@@ -124,6 +128,9 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		? input.args
 		: undefined;
 	const promptDelivery = input.promptDelivery === "stdin" ? "stdin" : undefined;
+	const machine = input.machine && typeof input.machine === "object" && !Array.isArray(input.machine)
+		? input.machine as HerdrMachineReference
+		: undefined;
 	const adapterId = input.adapter && typeof input.adapter === "object" && !Array.isArray(input.adapter)
 		? (input.adapter as Record<string, unknown>).id
 		: undefined;
@@ -131,6 +138,7 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		return {
 			type: "external-cli",
 			command: input.command,
+			...(machine ? { machine } : {}),
 			args: args ?? [],
 			promptDelivery: "prompt-file",
 			adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" },
@@ -140,7 +148,7 @@ export function normalizeExternalCliRunnerStatus(value: unknown): ExternalCliRun
 		};
 	}
 	const adapter = isCodeOwnedExternalCliAdapterId(adapterId) ? adapterId : undefined;
-	return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}) });
+	return resolveExternalCliRunnerStatus({ ...(adapter ? { adapter } : {}), command: input.command, ...(args ? { args } : {}), ...(promptDelivery ? { promptDelivery } : {}), ...(machine ? { machine } : {}) });
 }
 
 export function externalCliReceiptMetadata(input: {
@@ -149,9 +157,11 @@ export function externalCliReceiptMetadata(input: {
 	outputReference?: string;
 }): ExternalCliReceiptMetadata {
 	const { runner } = input;
+	const machine: ExternalCliMachineStatus | undefined = input.externalProcess?.machine ?? runner.machine;
 	return {
 		adapter: { ...runner.adapter },
 		capabilities: { ...runner.capabilities },
+		...(machine ? { machine: { ...machine, ...(machine.remoteGit ? { remoteGit: { ...machine.remoteGit } } : {}) } } : {}),
 		...(runner.safety ? { safety: { ...runner.safety } } : {}),
 		...(input.externalProcess ? {
 			outputArtifacts: {

package/src/runs/shared/external-cli-preflight.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 
 const MAX_PROBE_OUTPUT_BYTES = 256 * 1024;
 const MAX_PROBE_TIMEOUT_MS = 5_000;
+const MAX_REMOTE_PROBE_TIMEOUT_MS = 15_000;
 const MAX_CACHE_ENTRIES = 64;
 const MAX_AVAILABILITY_REASON_LENGTH = 256;
 
@@ -16,6 +17,8 @@ export interface ExternalCliPreflightSpec {
 	evidenceArgs?: readonly string[];
 	evidenceLabel?: string;
 	probeTimeoutMs?: number;
+	/** Remote probes include SSH handshakes; values may only narrow the code-owned remote ceiling. */
+	remote?: boolean;
 	validate?: (result: ExternalCliPreflightResult) => void;
 }
 
@@ -90,7 +93,7 @@ function narrowPositiveInteger(value: number | undefined, ceiling: number, label
 }
 
 function specKey(spec: ExternalCliPreflightSpec): string {
-	return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs]);
+	return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs, spec.remote === true]);
 }
 
 export function preflightExternalCli(command: string, spec: ExternalCliPreflightSpec, env: NodeJS.ProcessEnv, cwd?: string): ExternalCliPreflightResult {
@@ -99,7 +102,8 @@ export function preflightExternalCli(command: string, spec: ExternalCliPreflight
 	const lookupKey = JSON.stringify([binaryPath, binaryMtimeMs, specKey(spec)]);
 	const cachedKey = lookup.get(lookupKey);
 	const cached = cachedKey ? cache.get(cachedKey) : undefined;
-	const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, MAX_PROBE_TIMEOUT_MS, "probeTimeoutMs");
+	const ceiling = spec.remote === true ? MAX_REMOTE_PROBE_TIMEOUT_MS : MAX_PROBE_TIMEOUT_MS;
+	const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, ceiling, "probeTimeoutMs");
 	const base = cached ?? {
 		binaryPath,
 		binaryMtimeMs,

package/src/runs/shared/herdr-connection.ts

@@ -0,0 +1,134 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { HerdrMachineReference } from "../../shared/types.ts";
+
+const MAX_DISCOVERY_BYTES = 256 * 1024;
+const MAX_RPC_BYTES = 4 * 1024 * 1024;
+const SUBSCRIPTION_ACK_TIMEOUT_MS = 15_000;
+export const HERDR_REMOTE_PATH = "$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+export const HERDR_SSH_BASE = ["-T", "-o", "BatchMode=yes", "-o", "NumberOfPasswordPrompts=0", "-o", "StrictHostKeyChecking=yes", "-o", "ConnectTimeout=10", "-o", "ConnectionAttempts=1", "-o", "ForwardAgent=no", "-o", "ExitOnForwardFailure=yes", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=4", "-o", "SendEnv=-*", "-o", "SetEnv=PI_SUBAGENTS_SSH_GUARD="] as const;
+export function hardenedSshEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv { return { PATH: process.platform === "win32" ? source.PATH : "/usr/bin:/bin:/usr/sbin:/sbin", ...(source.SystemRoot ? { SystemRoot: source.SystemRoot } : {}), ...(source.WINDIR ? { WINDIR: source.WINDIR } : {}) }; }
+export function herdrSshArgs(source: NodeJS.ProcessEnv = process.env): string[] { return [...HERDR_SSH_BASE, ...(source.SSH_AUTH_SOCK ? ["-o", `IdentityAgent=${source.SSH_AUTH_SOCK}`] : [])]; }
+
+export interface HerdrEndpoint { socket: string; session: string | null; version: string; protocol: number; compatible: boolean; running: boolean }
+export interface HerdrRpcClient {
+	call<T>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+	subscribe(subscriptions: unknown[], listener: (event: unknown) => void, onDisconnect?: (error: Error) => void): Promise<() => void>;
+}
+export class HerdrRpcError extends Error {
+	readonly code?: string; readonly requestId: string;
+	constructor(message: string, requestId: string, code?: string) { super(message); this.name = "HerdrRpcError"; this.requestId = requestId; this.code = code; }
+}
+export class HerdrTransportError extends Error { constructor(message: string, options?: ErrorOptions) { super(message, options); this.name = "HerdrTransportError"; } }
+export interface HerdrForwardedConnection { endpoint: HerdrEndpoint; socketPath: string; client: HerdrRpcClient; forwardRemoteSocket(remotePath: string, name: string): Promise<{ socketPath: string; close(): Promise<void> }>; close(): Promise<void> }
+export function decodeHerdrJsonLine(line: Buffer): unknown { try { return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line)) as unknown; } catch { throw new Error("Herdr emitted malformed JSON or UTF-8."); } }
+
+export function shellQuoteRemote(value: string): string { return `'${value.replaceAll("'", "'\\''")}'`; }
+export function remoteShellCommand(script: string, args: string[] = []): string { return `sh -c ${shellQuoteRemote(`PATH="${HERDR_REMOTE_PATH}"; export PATH; ${script}`)} sh${args.map((arg) => ` ${shellQuoteRemote(arg)}`).join("")}`; }
+function canonicalHerdrSession(session: string | null | undefined): string | null { return session && session !== "default" ? session : null; }
+function sshEnvCommand(session: string | undefined, command: string): string { const selected = canonicalHerdrSession(session), assignment = selected ? ` HERDR_SESSION=${shellQuoteRemote(selected)}` : ""; return `/usr/bin/env -u HERDR_SOCKET_PATH -u HERDR_SESSION${assignment} ${remoteShellCommand(command)}`; }
+
+export function runHerdrRemoteCommand(machine: HerdrMachineReference, command: string, options: { sshBin?: string; env?: NodeJS.ProcessEnv; timeout?: number; maxBuffer?: number } = {}) { return spawnSync(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { encoding: "utf8", env: hardenedSshEnv(options.env), timeout: options.timeout ?? 15_000, maxBuffer: options.maxBuffer ?? MAX_DISCOVERY_BYTES, windowsHide: true }); }
+
+export function runHerdrRemoteCommandAsync(machine: HerdrMachineReference, command: string, options: { sshBin?: string; env?: NodeJS.ProcessEnv; timeout?: number; maxBuffer?: number } = {}): Promise<{ status: number | null; stdout: string; stderr: string; error?: Error }> {
+	return new Promise((resolve) => {
+		const child = spawn(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { env: hardenedSshEnv(options.env), stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+		const stdout: Buffer[] = [], stderr: Buffer[] = [], maxBuffer = options.maxBuffer ?? MAX_DISCOVERY_BYTES; let stdoutBytes = 0, stderrBytes = 0, error: Error | undefined, settled = false, escalation: NodeJS.Timeout | undefined;
+		const finish = (status: number | null, spawnError = error) => { if (settled) return; settled = true; clearTimeout(timer); if (escalation) clearTimeout(escalation); resolve({ status, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), ...(spawnError ? { error: spawnError } : {}) }); };
+		const terminate = () => { child.kill("SIGTERM"); escalation ??= setTimeout(() => { if (!settled) { child.kill("SIGKILL"); finish(child.exitCode ?? null); } }, 1_000); escalation.unref?.(); };
+		const collect = (target: Buffer[], stream: "stdout" | "stderr") => (chunk: Buffer) => { const bytes = stream === "stdout" ? (stdoutBytes += chunk.byteLength) : (stderrBytes += chunk.byteLength); if (bytes > maxBuffer) { error ??= new Error(`${stream} maxBuffer length exceeded`); terminate(); } else target.push(chunk); };
+		child.stdout.on("data", collect(stdout, "stdout")); child.stderr.on("data", collect(stderr, "stderr"));
+		child.once("error", (spawnError) => finish(null, spawnError));
+		child.once("close", (status) => finish(status));
+		const timer = setTimeout(terminate, options.timeout ?? 15_000); timer.unref?.();
+	});
+}
+
+export function parseHerdrEndpoint(value: string, expectedSession?: string): HerdrEndpoint {
+	let parsed: unknown;
+	try { parsed = JSON.parse(value) as unknown; } catch { throw new Error("Remote Herdr endpoint discovery returned malformed JSON."); }
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Remote Herdr endpoint discovery returned no endpoint.");
+	const p = parsed as Record<string, unknown>;
+	if (typeof p.socket !== "string" || !path.posix.isAbsolute(p.socket) || typeof p.version !== "string" || typeof p.protocol !== "number") throw new Error("Remote Herdr endpoint discovery returned incomplete identity.");
+	const session = canonicalHerdrSession(typeof p.session === "string" ? p.session : null), expected = canonicalHerdrSession(expectedSession);
+	if (expected !== session) throw new Error(`Remote Herdr session identity mismatch: expected ${expected ?? "default"}, received ${session ?? "default"}.`);
+	if (p.running !== true || p.compatible !== true || p.endpoint_compatible === false) throw new Error("The selected remote Herdr session is stopped or incompatible.");
+	return { socket: p.socket, session, version: p.version, protocol: p.protocol, compatible: true, running: true };
+}
+
+export async function discoverHerdrEndpoint(machine: HerdrMachineReference, options: { sshBin?: string; env?: NodeJS.ProcessEnv } = {}): Promise<HerdrEndpoint> {
+	const discovery = 'herdr_path=$(command -v herdr) || exit 127; case "$herdr_path" in /*/herdr) ;; *) exit 126;; esac; exec "$herdr_path" status server --json';
+	const result = await runHerdrRemoteCommandAsync(machine, sshEnvCommand(machine.session, discovery), { ...options, timeout: 15_000, maxBuffer: MAX_DISCOVERY_BYTES });
+	if (result.error) throw new Error(`Remote Herdr discovery failed: ${result.error.message}`);
+	if (result.status !== 0) throw new Error(`Remote Herdr discovery failed with code ${result.status}: ${(result.stderr || result.stdout).trim()}`);
+	return parseHerdrEndpoint(result.stdout, machine.session);
+}
+
+export class SocketRpcClient implements HerdrRpcClient {
+	readonly #socketPath: string;
+	readonly #subscriptionAckTimeoutMs: number;
+	#next = 0;
+	constructor(socketPath: string, subscriptionAckTimeoutMs = SUBSCRIPTION_ACK_TIMEOUT_MS) { this.#socketPath = socketPath; this.#subscriptionAckTimeoutMs = subscriptionAckTimeoutMs; }
+	call<T>(method: string, params: Record<string, unknown> = {}, timeoutMs = 15_000): Promise<T> {
+		return new Promise((resolve, reject) => {
+			const socket = net.createConnection(this.#socketPath); let bytes = 0; let data = Buffer.alloc(0); let finished = false; const id = String(++this.#next);
+			const timer = setTimeout(() => finish(new HerdrTransportError(`Herdr RPC '${method}' timed out.`)), timeoutMs); timer.unref?.();
+			const finish = (error?: Error, value?: T) => { if (finished) return; finished = true; clearTimeout(timer); socket.destroy(); error ? reject(error) : resolve(value as T); };
+			socket.on("connect", () => socket.write(`${JSON.stringify({ id, method, params })}\n`));
+			socket.on("data", (chunk: Buffer) => {
+				bytes += chunk.byteLength; if (bytes > MAX_RPC_BYTES) { finish(new Error("Herdr RPC response exceeded its byte bound.")); return; }
+				data = Buffer.concat([data, chunk]); const newline = data.indexOf(10); if (newline < 0) return;
+				let frame: unknown; try { frame = decodeHerdrJsonLine(data.subarray(0, newline)); } catch { finish(new Error("Herdr RPC returned malformed JSON or UTF-8.")); return; }
+				const record = frame as { id?: unknown; result?: T; error?: { message?: unknown; code?: unknown } };
+				if (record.id !== id) { finish(new Error("Herdr RPC response identity mismatch.")); return; }
+				if (record.error) finish(new HerdrRpcError(String(record.error.message ?? "Herdr RPC failed."), id, typeof record.error.code === "string" ? record.error.code : undefined)); else finish(undefined, record.result);
+			});
+			socket.on("error", (error) => finish(new HerdrTransportError(error.message, { cause: error })));
+			socket.on("close", () => finish(new HerdrTransportError(`Herdr RPC '${method}' ended before a response.`)));
+		});
+	}
+	async subscribe(subscriptions: unknown[], listener: (event: unknown) => void, onDisconnect?: (error: Error) => void): Promise<() => void> {
+		const socket = net.createConnection(this.#socketPath); const id = String(++this.#next); let buffer = Buffer.alloc(0), bytes = 0, acknowledged = false, intentional = false, notified = false, settled = false;
+		let resolveAck!: () => void, rejectAck!: (error: Error) => void;
+		const acknowledgement = new Promise<void>((resolve, reject) => { resolveAck = resolve; rejectAck = reject; });
+		const failHandshake = (error: Error) => { if (settled) return; settled = true; clearTimeout(timer); socket.destroy(); rejectAck(error); };
+		const disconnect = (error: Error) => { if (intentional || notified) return; notified = true; if (!acknowledged) failHandshake(error); else onDisconnect?.(error); };
+		const timer = setTimeout(() => failHandshake(new Error("Herdr subscription acknowledgement timed out.")), this.#subscriptionAckTimeoutMs); timer.unref?.();
+		socket.on("data", (chunk: Buffer) => { bytes += chunk.byteLength; if (bytes > (acknowledged ? MAX_RPC_BYTES * 32 : MAX_RPC_BYTES)) { disconnect(new Error("Herdr subscription exceeded its byte bound.")); socket.destroy(); return; } buffer = Buffer.concat([buffer, chunk]); for (;;) { const i = buffer.indexOf(10); if (i < 0) break; const line = buffer.subarray(0, i); buffer = buffer.subarray(i + 1); let value: unknown; try { value = decodeHerdrJsonLine(line); } catch { disconnect(new Error("Herdr subscription emitted malformed JSON or UTF-8.")); socket.destroy(); return; } const record = value as { id?: unknown; result?: { type?: unknown }; error?: { message?: unknown; code?: unknown } }; if (!acknowledged) { if (record.id === id) { if (record.error) { failHandshake(new HerdrRpcError(String(record.error.message ?? "Herdr subscription failed."), id, typeof record.error.code === "string" ? record.error.code : undefined)); return; } if (record.result?.type !== "subscription_started") { failHandshake(new Error("Herdr subscription returned an invalid acknowledgement.")); return; } acknowledged = true; settled = true; clearTimeout(timer); resolveAck(); continue; } if (record.id === "" && record.error && record.error.code === "invalid_request") { failHandshake(new HerdrRpcError(String(record.error.message ?? "Herdr subscription request was invalid."), "", "invalid_request")); return; } failHandshake(new Error("Herdr subscription emitted an event before acknowledgement.")); return; } if (record.error) { disconnect(new HerdrRpcError(String(record.error.message ?? "Herdr subscription failed."), typeof record.id === "string" ? record.id : "", typeof record.error.code === "string" ? record.error.code : undefined)); socket.destroy(); return; } listener(value); } });
+		socket.on("error", (error) => disconnect(error));
+		socket.on("close", () => disconnect(new Error("Herdr subscription connection was lost.")));
+		socket.on("connect", () => socket.write(`${JSON.stringify({ id, method: "events.subscribe", params: { subscriptions } })}\n`));
+		await acknowledgement;
+		return () => { intentional = true; clearTimeout(timer); socket.destroy(); };
+	}
+}
+
+async function waitForSocket(socketPath: string, child: ChildProcess): Promise<void> {
+	for (let attempt = 0; attempt < 100; attempt++) {
+		if (child.exitCode !== null) throw new Error(`SSH StreamLocal forwarding exited with code ${child.exitCode}.`);
+		try { const stat = fs.lstatSync(socketPath); if (stat.isSocket()) { fs.chmodSync(socketPath, 0o600); return; } } catch {}
+		await new Promise((resolve) => setTimeout(resolve, 25));
+	}
+	throw new Error("SSH StreamLocal forwarding did not create its local socket.");
+}
+async function terminateChild(child: ChildProcess): Promise<void> { const wait = (ms: number) => child.exitCode !== null || child.signalCode !== null ? Promise.resolve() : Promise.race([new Promise<void>((resolve) => child.once("exit", () => resolve())), new Promise<void>((resolve) => setTimeout(resolve, ms))]); if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM"); await wait(1_000); if (child.exitCode === null && child.signalCode === null) { child.kill("SIGKILL"); await wait(1_000); } }
+
+export async function connectHerdrMachine(machine: HerdrMachineReference, options: { sshBin?: string; env?: NodeJS.ProcessEnv } = {}): Promise<HerdrForwardedConnection> {
+	if (process.platform === "win32") throw new Error("Pane-native Herdr placement requires OpenSSH StreamLocal forwarding and is not supported on Windows.");
+	const endpoint = await discoverHerdrEndpoint(machine, options);
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-herdr-")); fs.chmodSync(dir, 0o700);
+	const children = new Set<ChildProcess>();
+	const forward = async (remotePath: string, name: string) => {
+		if (!path.posix.isAbsolute(remotePath)) throw new Error("Remote socket path must be absolute.");
+		const local = path.join(dir, `${name}.sock`);
+		const child = spawn(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), "-N", "-o", "StreamLocalBindUnlink=yes", "-L", `${local}:${remotePath}`, machine.target], { env: hardenedSshEnv(options.env), stdio: "ignore", windowsHide: true }); children.add(child);
+		const stop = async () => { await terminateChild(child); children.delete(child); try { fs.rmSync(local, { force: true }); } catch {} };
+		try { await waitForSocket(local, child); } catch (error) { await stop(); throw error; }
+		return { socketPath: local, close: stop };
+	};
+	const primary = await forward(endpoint.socket, "herdr").catch((error) => { fs.rmSync(dir, { recursive: true, force: true }); throw error; });
+	return { endpoint, socketPath: primary.socketPath, client: new SocketRpcClient(primary.socketPath), forwardRemoteSocket: forward, close: async () => { await Promise.all([...children].map(terminateChild)); children.clear(); fs.rmSync(dir, { recursive: true, force: true }); } };
+}