@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/src/runs/shared/herdr-placed-run.ts

@@ -0,0 +1,263 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as net from "node:net";
+import * as path from "node:path";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import packageJson from "../../../package.json" with { type: "json" };
+import type { HerdrMachineReference, HerdrRemoteGitStatus } from "../../shared/types.ts";
+import type { ChildSession, ChildSessionEvent, ChildSessionFactory, ChildSessionLaunch } from "./child-session.ts";
+import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
+import { connectHerdrMachine, remoteShellCommand, runHerdrRemoteCommand, runHerdrRemoteCommandAsync, type HerdrForwardedConnection, type HerdrRpcClient } from "./herdr-connection.ts";
+import { encodeHerdrPiFrame, HERDR_PI_MODE_ENV, HERDR_PI_PROTOCOL, HERDR_PI_RUN_ENV, HERDR_PI_RUNTIME_DIR_ENV, HerdrPiFrameDecoder, validateHerdrPiRunId, type HerdrPiFrame } from "./herdr-pi-protocol.ts";
+import { getAgentDir } from "../../shared/utils.ts";
+
+export interface HerdrRunIdentity { runId: string; machineId: string; target: string; session: string | null; workspaceId: string; tabId: string; paneId: string; terminalId: string; agentName: string; nativeSessionId: string; cwd: string; runtimeDir: string }
+export interface HerdrRunSnapshot { connection: "connected" | "unknown" | "closed"; state: "ready" | "working" | "blocked" | "settled" | "unknown"; identity?: HerdrRunIdentity; revision: number }
+export interface HerdrReconnectCandidate { endpoint: { session: string | null; protocol: number; version: string }; agents: Array<{ terminal_id?: string; pane_id?: string; agent_status?: string }>; bridge: { runId?: string; nativeSessionId?: string; packageVersion?: string; protocol?: number; evidenceCursor?: number; evidenceFloor?: number } }
+
+function herdrRunState(status: unknown, fallback: HerdrRunSnapshot["state"] = "unknown"): HerdrRunSnapshot["state"] {
+	return status === "working" ? "working" : status === "blocked" ? "blocked" : status === "idle" || status === "done" ? "settled" : status === "unknown" ? "unknown" : fallback;
+}
+
+export function herdrStatusSubscriptions(paneId: string): unknown[] {
+	return [{ type: "pane.agent_status_changed", pane_id: paneId }, { type: "pane.closed" }, { type: "pane.moved" }];
+}
+
+export function reconcileHerdrPlacedRun(identity: HerdrRunIdentity, candidate: HerdrReconnectCandidate, proveEvidence: () => { ok: true; cursor: number } | { ok: false; reason: string }): { ok: true; state: HerdrRunSnapshot["state"]; paneId: string; cursor: number } | { ok: false; reason: string } {
+	if (candidate.endpoint.session !== identity.session) return { ok: false, reason: "Herdr session changed during reconnect." }; const matches = candidate.agents.filter((agent) => agent.terminal_id === identity.terminalId); if (matches.length !== 1 || typeof matches[0]!.pane_id !== "string") return { ok: false, reason: matches.length ? "Terminal identity is ambiguous." : "Owned terminal is missing." }; const proof = proveEvidence(); if (!proof.ok) return proof; return { ok: true, state: herdrRunState(matches[0]!.agent_status), paneId: matches[0]!.pane_id!, cursor: proof.cursor };
+}
+
+export function reconcileHerdrReconnect(identity: HerdrRunIdentity, candidate: HerdrReconnectCandidate, lastEvidenceCursor: number): { ok: true; state: HerdrRunSnapshot["state"]; paneId: string; cursor: number } | { ok: false; reason: string } {
+	return reconcileHerdrPlacedRun(identity, candidate, () => { const bridge = candidate.bridge; if (bridge.runId !== identity.runId || bridge.nativeSessionId !== identity.nativeSessionId || bridge.packageVersion !== packageJson.version || bridge.protocol !== HERDR_PI_PROTOCOL) return { ok: false, reason: "Bridge run, package, protocol, or native session identity changed." }; if (typeof bridge.evidenceCursor !== "number" || typeof bridge.evidenceFloor !== "number" || bridge.evidenceCursor < lastEvidenceCursor || bridge.evidenceFloor > lastEvidenceCursor + 1) return { ok: false, reason: "Bridge evidence has a gap after reconnect." }; return { ok: true, cursor: bridge.evidenceCursor }; });
+}
+
+export async function boundedHerdrReconnect(identity: HerdrRunIdentity, lastEvidenceCursor: number, attempt: (number: number) => Promise<HerdrReconnectCandidate>, options: { attempts?: number; deadlineMs?: number; disposed?: () => boolean } = {}) {
+	const deadline = Date.now() + (options.deadlineMs ?? 15_000); let last = "Reconnect did not run.";
+	for (let number = 1; number <= (options.attempts ?? 3) && Date.now() < deadline; number++) {
+		if (options.disposed?.()) return { ok: false as const, reason: "Reconnect was disposed." };
+		try { const result = reconcileHerdrReconnect(identity, await attempt(number), lastEvidenceCursor); if (result.ok) return result; last = result.reason; } catch (error) { last = error instanceof Error ? error.message : String(error); }
+		await new Promise((resolve) => setTimeout(resolve, Math.min(number * 100, Math.max(0, deadline - Date.now()))));
+	}
+	return { ok: false as const, reason: last };
+}
+
+function safeRunId(value: string | undefined): string { const prefix = value?.replace(/[^A-Za-z0-9_-]/gu, "_").slice(0, 48) ?? "run"; return validateHerdrPiRunId(`${prefix}_${randomBytes(8).toString("hex")}`); }
+function idOf(value: unknown, key: string): string { const found = value && typeof value === "object" ? (value as Record<string, unknown>)[key] : undefined; if (typeof found !== "string" || !found) throw new Error(`Herdr did not return ${key}.`); return found; }
+function list(value: unknown, key: string): unknown[] { if (Array.isArray(value)) return value; const found = value && typeof value === "object" ? (value as Record<string, unknown>)[key] : undefined; return Array.isArray(found) ? found : []; }
+function tagged(value: unknown, type: string, key: string): Record<string, unknown> { if (!value || typeof value !== "object" || (value as Record<string, unknown>).type !== type || !(key in (value as Record<string, unknown>)) || typeof (value as Record<string, unknown>)[key] !== "object") throw new Error(`Herdr returned an invalid ${type} envelope.`); return (value as Record<string, Record<string, unknown>>)[key]!; }
+export function parseHerdrCreated(value: unknown, type: "workspace_created" | "tab_created"): { workspaceId?: string; tabId: string; paneId: string } { const envelope = value as Record<string, unknown>; if (envelope?.type !== type) throw new Error(`Herdr returned an invalid ${type} envelope.`); const tab = envelope.tab as Record<string, unknown>; const pane = envelope.root_pane as Record<string, unknown>; return { ...(type === "workspace_created" ? { workspaceId: idOf(envelope.workspace, "workspace_id") } : {}), tabId: idOf(tab, "tab_id"), paneId: idOf(pane, "pane_id") }; }
+export function parseHerdrAgent(value: unknown, type: "agent_started" | "agent_info" | "agent_prompted") { return tagged(value, type, "agent"); }
+export function parseHerdrSessionSnapshot(value: unknown): Record<string, unknown> { return tagged(value, "session_snapshot", "snapshot"); }
+export function ownsHerdrPane(agent: Record<string, unknown>, terminalId: string, paneId: string): boolean { return agent.terminal_id === terminalId && agent.pane_id === paneId; }
+function snapshotAgents(snapshot: Record<string, unknown>): Array<{ terminal_id?: string; pane_id?: string; agent_status?: string }> { return list(snapshot, "agents").filter((agent): agent is Record<string, unknown> => Boolean(agent && typeof agent === "object")).map((agent) => ({ terminal_id: typeof agent.terminal_id === "string" ? agent.terminal_id : undefined, pane_id: typeof agent.pane_id === "string" ? agent.pane_id : undefined, agent_status: typeof agent.agent_status === "string" ? agent.agent_status : undefined })); }
+
+export const HERDR_MAX_OWNED_PANES = 20;
+const HERDR_ALLOCATION_LOCK_TIMEOUT_MS = 10_000, HERDR_ALLOCATION_LOCK_POLL_MS = 25;
+export function herdrPaneAllocationKey(target: string, session: string | null, cwd: string): string { return JSON.stringify([target, session, cwd]); }
+function assertPrivateDir(directory: string): void { const stat = fs.lstatSync(directory); if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o700 || (typeof process.getuid === "function" && stat.uid !== process.getuid())) throw new Error("Herdr allocation path is not a mode-0700 agent-private owned directory."); }
+function ensurePrivateChild(parent: string, name: string): string { const directory = path.join(parent, name); try { fs.mkdirSync(directory, { mode: 0o700 }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; } assertPrivateDir(directory); return directory; }
+function allocationLockRoot(): string { const agentDir = getAgentDir(); fs.mkdirSync(agentDir, { recursive: true, mode: 0o700 }); assertPrivateDir(agentDir); const packageDir = ensurePrivateChild(agentDir, "pi-subagents"); return ensurePrivateChild(packageDir, "herdr-allocation-locks"); }
+function livePid(pid: number): boolean { try { process.kill(pid, 0); return true; } catch (error) { return (error as NodeJS.ErrnoException).code === "EPERM"; } }
+interface AllocationOwner { pid: number; token: string; dev: number; ino: number }
+function readAllocationOwner(ownerPath: string): AllocationOwner { const descriptor = fs.openSync(ownerPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0)); try { const stat = fs.fstatSync(descriptor); if (!stat.isFile() || (stat.mode & 0o777) !== 0o600 || (typeof process.getuid === "function" && stat.uid !== process.getuid())) throw new Error("Herdr allocation lock owner record is unsafe."); const value = JSON.parse(fs.readFileSync(descriptor, "utf8")) as { pid?: unknown; token?: unknown }; if (typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0 || typeof value.token !== "string" || !/^[a-f0-9]{32}$/u.test(value.token)) throw new Error("Herdr allocation lock owner record is malformed."); return { pid: value.pid, token: value.token, dev: stat.dev, ino: stat.ino }; } finally { fs.closeSync(descriptor); } }
+function sameOwner(left: AllocationOwner, right: AllocationOwner): boolean { return left.token === right.token && left.dev === right.dev && left.ino === right.ino; }
+export async function withHerdrPaneAllocationLock<T>(key: string, action: () => Promise<T>, options: { timeoutMs?: number; pollMs?: number } = {}): Promise<T> {
+	const root = allocationLockRoot(), digest = createHash("sha256").update(key).digest("hex"), lockPath = path.join(root, `${digest}.lock`), recoveryPath = path.join(root, `${digest}.recovery`), token = randomBytes(16).toString("hex"), tempPath = path.join(root, `.${digest}.${token}.tmp`), deadline = Date.now() + (options.timeoutMs ?? HERDR_ALLOCATION_LOCK_TIMEOUT_MS); let published: AllocationOwner | undefined;
+	try {
+		fs.writeFileSync(tempPath, JSON.stringify({ pid: process.pid, token, createdAt: Date.now() }), { mode: 0o600, flag: "wx" }); const tempOwner = readAllocationOwner(tempPath);
+		for (;;) {
+			let recovering = false; try { readAllocationOwner(recoveryPath); recovering = true; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+			if (!recovering) {
+				let linked = false;
+				try {
+					fs.linkSync(tempPath, lockPath); linked = true;
+					try { readAllocationOwner(recoveryPath); const current = readAllocationOwner(lockPath); if (!sameOwner(current, tempOwner)) throw new Error("Herdr allocation lock changed during publication."); fs.unlinkSync(lockPath); }
+					catch (recoveryError) { if ((recoveryError as NodeJS.ErrnoException).code !== "ENOENT") throw recoveryError; published = readAllocationOwner(lockPath); if (!sameOwner(published, tempOwner)) throw new Error("Herdr allocation lock publication identity changed."); break; }
+				} catch (publishError) { if (linked) { try { const current = readAllocationOwner(lockPath); if (sameOwner(current, tempOwner)) fs.unlinkSync(lockPath); } catch {} } if ((publishError as NodeJS.ErrnoException).code !== "EEXIST" && (publishError as NodeJS.ErrnoException).code !== "ENOENT") throw publishError; }
+			}
+			if (published) break;
+			try { const current = readAllocationOwner(lockPath); if (!livePid(current.pid)) { let claimed = false; try { fs.linkSync(lockPath, recoveryPath); claimed = true; const recovery = readAllocationOwner(recoveryPath), latest = readAllocationOwner(lockPath); if (!sameOwner(recovery, current) || !sameOwner(latest, current)) throw new Error("Herdr stale lock identity changed during recovery."); fs.unlinkSync(lockPath); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST" && (error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } finally { if (claimed) fs.unlinkSync(recoveryPath); } if (claimed) continue; } } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+			if (Date.now() >= deadline) throw new Error("Timed out waiting for the Herdr pane allocation lock."); await new Promise((resolve) => setTimeout(resolve, options.pollMs ?? HERDR_ALLOCATION_LOCK_POLL_MS));
+		}
+		fs.unlinkSync(tempPath);
+		let value: T | undefined, actionError: unknown, releaseError: unknown, actionFailed = false, releaseFailed = false; try { value = await action(); } catch (error) { actionFailed = true; actionError = error; }
+		try { const current = readAllocationOwner(lockPath); if (!published || !sameOwner(current, published)) throw new Error("Herdr pane allocation lock ownership changed before release."); fs.unlinkSync(lockPath); } catch (error) { releaseFailed = true; releaseError = error; }
+		if (actionFailed && releaseFailed) throw new AggregateError([actionError, releaseError], "Herdr pane allocation action and release both failed.", { cause: actionError }); if (actionFailed) throw actionError; if (releaseFailed) throw releaseError; return value as T;
+	} finally { try { fs.unlinkSync(tempPath); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } }
+}
+
+export function serializeHerdrPiLaunch(launch: ChildSessionLaunch): { args: string[]; resources: { agent: string; skills?: string[]; toolCeiling?: string[]; reads?: string[] | false } } {
+	if (launch.storage.kind === "file") throw new Error("Pane-native remote Pi does not support fork, resume, or revival; use fresh context.");
+	if (launch.extensionPaths.length || launch.requiredExtensions?.length) throw new Error("Pane-native remote Pi cannot transfer local extension paths; install/configure pi-subagents on the remote machine.");
+	if (launch.processEnv && Object.values(launch.processEnv).some((value) => value !== undefined && value !== "__none__")) throw new Error("Pane-native remote Pi cannot transfer local bindings, MCP selections, or process environment.");
+	if (launch.runtime.nestedRoute || launch.runtime.fanoutChild || launch.runtime.depth > 1) throw new Error("Nested delegation from a pane-native remote Pi is not supported.");
+	if (launch.excludeTools?.length || launch.runtime.permissions || launch.runtime.toolBudget || launch.runtime.requiredExtensions || launch.runtime.requiredTools?.length || launch.runtime.mcpDirectTools?.length) throw new Error("Pane-native remote Pi cannot yet represent exclusions, permission rules, tool budgets, MCP direct tools, or required-tool/extension contracts; remove machine placement.");
+	const resources = launch.remoteResources;
+	if (!resources || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(resources.agent) || resources.skills?.some((name) => !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(name)) || resources.toolCeiling?.some((name) => !/^[A-Za-z0-9_-]{1,64}$/u.test(name)) || (resources.reads !== undefined && resources.reads !== false && resources.reads.some((read) => typeof read !== "string" || Buffer.byteLength(read) > 4096))) throw new Error("Pane-native remote resources require bounded logical agent, skill, tool, and read names.");
+	const args: string[] = [];
+	if (launch.noSkills) args.push("--no-skills", "--no-prompt-templates");
+	if (launch.noContextFiles) args.push("--no-context-files");
+	if (launch.model) args.push("--model", launch.model);
+	return { args, resources: { agent: resources.agent, ...(resources.skills ? { skills: [...resources.skills] } : {}), ...(resources.toolCeiling ? { toolCeiling: [...resources.toolCeiling] } : {}), ...(resources.reads !== undefined ? { reads: resources.reads === false ? false : [...resources.reads] } : {}) } };
+}
+
+export async function provisionHerdrPane(client: HerdrRpcClient, cwd: string, runId: string, runtimeDir: string, environment?: Record<string, string>, allocationKey = cwd): Promise<{ workspaceId: string; tabId: string; paneId: string }> {
+	return withHerdrPaneAllocationLock(allocationKey, async () => {
+		const snapshot = parseHerdrSessionSnapshot(await client.call("session.snapshot")); const panes = list(snapshot, "panes").filter((item): item is Record<string, unknown> => Boolean(item && typeof item === "object")), workspaces = list(snapshot, "workspaces").filter((item): item is Record<string, unknown> => Boolean(item && typeof item === "object"));
+		const ownedLabel = `pi-subagents-${createHash("sha256").update(cwd).digest("hex").slice(0, 10)}`, owned = workspaces.filter((item) => item.label === ownedLabel); if (owned.length > 1) throw new Error("Herdr deterministic owned workspace identity is ambiguous.");
+		const cwdWorkspaceIds = new Set(panes.filter((item) => item.cwd === cwd || item.foreground_cwd === cwd).map((item) => item.workspace_id).filter((id): id is string => typeof id === "string")), cwdWorkspaces = workspaces.filter((item) => typeof item.workspace_id === "string" && cwdWorkspaceIds.has(item.workspace_id));
+		const selected = owned[0] ?? (cwdWorkspaces.length === 1 ? cwdWorkspaces[0] : undefined), selectedId = selected ? idOf(selected, "workspace_id") : undefined, actual = selectedId ? panes.filter((pane) => pane.workspace_id === selectedId).length : 0;
+		if (actual >= HERDR_MAX_OWNED_PANES) throw new Error(`Herdr workspace pane limit of ${HERDR_MAX_OWNED_PANES} is reached; close an existing pane before launching another placed run.`);
+		const env = environment ?? { [HERDR_PI_MODE_ENV]: "1", [HERDR_PI_RUN_ENV]: runId, [HERDR_PI_RUNTIME_DIR_ENV]: runtimeDir };
+		if (selectedId) { const tab = parseHerdrCreated(await client.call("tab.create", { workspace_id: selectedId, cwd, label: `subagent-${runId.slice(-8)}`, env, focus: false }), "tab_created"); return { workspaceId: selectedId, tabId: tab.tabId, paneId: tab.paneId }; }
+		const workspace = parseHerdrCreated(await client.call("workspace.create", { cwd, label: ownedLabel, env, focus: false }), "workspace_created"); return { workspaceId: workspace.workspaceId!, tabId: workspace.tabId, paneId: workspace.paneId };
+	});
+}
+
+
+export async function discoverBridgeManifest(machine: HerdrMachineReference, runId: string, runtimeDir: string, options: { sshBin?: string; env?: NodeJS.ProcessEnv } = {}): Promise<{ socketPath: string; nativeSessionId: string; packageVersion: string; protocol: number }> {
+	const script = `p="$1/manifest.json"; test -f "$p" && test ! -L "$p" && cat "$p"`;
+	for (let attempt = 0; attempt < 100; attempt++) {
+		const result = await runHerdrRemoteCommandAsync(machine, remoteShellCommand(script, [runtimeDir]), { ...options, timeout: 5_000, maxBuffer: 64 * 1024 });
+		if (result.error) throw new Error(`Remote bridge manifest discovery failed: ${result.error.message}`, { cause: result.error });
+		if (result.status === 0 && result.stdout.trim()) {
+			let value: unknown; try { value = JSON.parse(result.stdout) as unknown; } catch { throw new Error("Remote bridge manifest is malformed."); }
+			const p = value as Record<string, unknown>;
+			if (p.runId !== runId || typeof p.socketPath !== "string" || path.posix.dirname(p.socketPath) !== runtimeDir || typeof p.nativeSessionId !== "string" || typeof p.packageVersion !== "string" || typeof p.protocol !== "number") throw new Error("Remote bridge manifest identity is incomplete or outside its owned runtime directory.");
+			return p as unknown as { socketPath: string; nativeSessionId: string; packageVersion: string; protocol: number };
+		}
+		await new Promise((resolve) => setTimeout(resolve, 50));
+	}
+	throw new Error("The remote Pi did not expose the packaged pi-subagents bridge. Install/configure the same package version as an ambient Pi extension on the saved machine.");
+}
+
+export async function createRemoteRuntimeDir(machine: HerdrMachineReference, runId: string, options: { sshBin?: string; env?: NodeJS.ProcessEnv } = {}): Promise<string> { const result = await runHerdrRemoteCommandAsync(machine, remoteShellCommand("umask 077; mktemp -d \"${TMPDIR:-/tmp}/pi-subagents-herdr-$1-XXXXXXXX\"", [runId]), { ...options, timeout: 10_000, maxBuffer: 4096 }); if (result.error) throw new Error(`Could not provision a run-private remote bridge runtime directory: ${result.error.message}`, { cause: result.error }); const value = result.stdout.trim(); if (result.status !== 0 || !path.posix.isAbsolute(value) || value.includes("\n")) throw new Error("Could not provision a run-private remote bridge runtime directory."); return value; }
+export function removeRemoteRuntimeDir(machine: HerdrMachineReference, runtimeDir: string, options: { sshBin?: string; env?: NodeJS.ProcessEnv } = {}): void { const result = runHerdrRemoteCommand(machine, remoteShellCommand("p=$1; case \"${p##*/}\" in pi-subagents-herdr-*) test -d \"$p\" && test ! -L \"$p\" && rm -rf -- \"$p\";; *) exit 64;; esac", [runtimeDir]), { ...options, timeout: 10_000, maxBuffer: 4096 }); if (result.status !== 0 || result.stdout) throw new Error(`Could not remove the exact owned remote runtime directory: ${String(result.stderr).slice(0, 512)}`); }
+
+/** The single private owner for allocation shared by every pane-native backend projection. */
+export class HerdrPlacedRunOwner {
+	readonly machine: HerdrMachineReference; readonly runId: string; readonly runtimeDir: string; connection: HerdrForwardedConnection;
+	owned?: { workspaceId: string; tabId: string; paneId: string }; terminalId?: string; agentName?: string; startedArgv?: string[]; identity?: HerdrRunIdentity; #unsubscribe = () => {}; #snapshot: HerdrRunSnapshot = { connection: "connected", state: "ready", revision: 0 }; #cleanupPromise?: Promise<void>; readonly #removeRuntime: () => void;
+	private constructor(machine: HerdrMachineReference, runId: string, runtimeDir: string, connection: HerdrForwardedConnection, removeRuntime: () => void = () => removeRemoteRuntimeDir(machine, runtimeDir)) { this.machine = machine; this.runId = runId; this.runtimeDir = runtimeDir; this.connection = connection; this.#removeRuntime = removeRuntime; }
+	static async create(machine: HerdrMachineReference, runId: string, beforePane?: (owner: HerdrPlacedRunOwner) => void | Promise<void>): Promise<HerdrPlacedRunOwner> { const runtimeDir = await createRemoteRuntimeDir(machine, runId); let connection: HerdrForwardedConnection | undefined; try { connection = await connectHerdrMachine(machine); const owner = new HerdrPlacedRunOwner(machine, runId, runtimeDir, connection); await beforePane?.(owner); return owner; } catch (error) { const cleanupErrors: unknown[] = []; try { await connection?.close(); } catch (cleanupError) { cleanupErrors.push(cleanupError); } try { removeRemoteRuntimeDir(machine, runtimeDir); } catch (cleanupError) { cleanupErrors.push(cleanupError); } if (cleanupErrors.length) throw new AggregateError([error, ...cleanupErrors], "Herdr owner creation failed and cleanup also failed.", { cause: error }); throw error; } }
+	observeEvent(event: unknown): void { const data = event && typeof event === "object" ? (event as { data?: Record<string, unknown> }).data : undefined; if (data && (!this.terminalId || data.terminal_id === this.terminalId || data.pane_id === this.owned?.paneId)) this.#snapshot = { ...this.#snapshot, revision: this.#snapshot.revision + 1, state: herdrRunState(data.agent_status, this.#snapshot.state) }; }
+	markConnectionUnknown(observed: HerdrForwardedConnection): boolean { if (this.connection !== observed) return false; this.#snapshot = { ...this.#snapshot, connection: "unknown", state: "unknown", revision: this.#snapshot.revision + 1 }; return true; }
+	statusSubscriptions(paneId = this.owned?.paneId): unknown[] { if (!paneId) throw new Error("Herdr status subscription requires a provisioned pane."); return herdrStatusSubscriptions(paneId); }
+	async subscribe(listener: (event: unknown) => void, disconnected: (error: Error) => void): Promise<void> { const observed = this.connection; let adopted = false, candidateLost: Error | undefined; const unsubscribe = await observed.client.subscribe(this.statusSubscriptions(), (event) => { this.observeEvent(event); listener(event); }, (error) => { if (!adopted) { candidateLost ??= error; return; } if (!this.markConnectionUnknown(observed)) return; disconnected(error); }); if (candidateLost) { unsubscribe(); throw candidateLost; } this.#unsubscribe = unsubscribe; adopted = true; }
+	async provision(environment?: Record<string, string>): Promise<{ workspaceId: string; tabId: string; paneId: string }> { this.owned = await provisionHerdrPane(this.connection.client, this.machine.cwd, this.runId, this.runtimeDir, environment, herdrPaneAllocationKey(this.machine.target, this.connection.endpoint.session, this.machine.cwd)); return this.owned; }
+	async start(kind: "pi" | "claude" | "cursor" | "codex", name: string, args: string[], options: { timeoutMs?: number; pollMs?: number; clock?: { now(): number; wait(ms: number): Promise<void> } } = {}): Promise<{ terminalId: string; paneId: string; argv: string[] }> {
+		if (!this.owned) throw new Error("Herdr placement owner has not provisioned its pane."); const clock = options.clock ?? { now: () => Date.now(), wait: (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)) }, deadline = clock.now() + (options.timeoutMs ?? 5_000), pollMs = options.pollMs ?? 50;
+		let response: unknown;
+		for (;;) {
+			try { response = await this.connection.client.call("agent.start", { name, kind, pane_id: this.owned.paneId, args, timeout_ms: 45_000 }, 60_000); break; }
+			catch (error) {
+				if (!(error instanceof Error) || !error.message.includes("is not an available shell")) throw error;
+				const pane = tagged(await this.connection.client.call("pane.get", { pane_id: this.owned.paneId }), "pane_info", "pane"); if (pane.pane_id !== this.owned.paneId || pane.workspace_id !== this.owned.workspaceId || pane.tab_id !== this.owned.tabId) throw new Error("Herdr startup pane identity changed after a transient start rejection.", { cause: error }); if (pane.agent != null || pane.agent_session != null) throw new Error("Herdr startup pane became occupied after a transient start rejection.", { cause: error }); if (clock.now() >= deadline) throw new Error("Herdr owned pane remained unavailable until the startup deadline.", { cause: error }); await clock.wait(Math.min(pollMs, deadline - clock.now()));
+			}
+		}
+		const started = parseHerdrAgent(response, "agent_started"), argv = [kind, ...args], terminalId = idOf(started, "terminal_id"), paneId = idOf(started, "pane_id"); if (paneId !== this.owned.paneId) throw new Error("Herdr started the native agent in an unexpected pane."); this.agentName = name; this.terminalId = terminalId; this.startedArgv = argv; return { terminalId, paneId, argv };
+	}
+	journal(identity: HerdrRunIdentity): void { this.identity = identity; this.#snapshot = { ...this.#snapshot, identity }; const journalDir = path.join(getAgentDir(), "pi-subagents", "herdr-run-journal"); fs.mkdirSync(journalDir, { recursive: true, mode: 0o700 }); fs.writeFileSync(path.join(journalDir, `${this.runId}.json`), JSON.stringify({ version: 1, identity, state: "ready", updatedAt: Date.now() }), { mode: 0o600, flag: "wx" }); }
+	get snapshot(): HerdrRunSnapshot { return this.#snapshot; }
+	runRemote(command: string, options: { timeout?: number; maxBuffer?: number } = {}) { return runHerdrRemoteCommand(this.machine, command, options); }
+	async replaceConnection(input: { connection: HerdrForwardedConnection; unsubscribe: () => void; paneId: string; state: HerdrRunSnapshot["state"] }): Promise<void> { const oldConnection = this.connection, oldUnsubscribe = this.#unsubscribe; this.connection = input.connection; this.#unsubscribe = input.unsubscribe; if (this.identity) this.identity = { ...this.identity, paneId: input.paneId }; this.#snapshot = { connection: "connected", state: input.state, identity: this.identity, revision: this.#snapshot.revision + 1 }; oldUnsubscribe(); await oldConnection.close(); }
+	cleanup(closeStartedPane = true): Promise<void> { return this.#cleanupPromise ??= this.#performCleanup(closeStartedPane); }
+	async #performCleanup(closeStartedPane: boolean): Promise<void> { let failure: unknown; try { if (closeStartedPane && this.owned) { let closed = false; if (this.terminalId && this.agentName) { const current = parseHerdrAgent(await this.connection.client.call<Record<string, unknown>>("agent.get", { target: this.agentName }), "agent_info"); if (ownsHerdrPane(current, this.terminalId, this.owned.paneId)) { await this.connection.client.call("pane.close", { pane_id: this.owned.paneId }); closed = true; } } if (!closed) { const snapshot = parseHerdrSessionSnapshot(await this.connection.client.call<Record<string, unknown>>("session.snapshot")); const occupants = snapshotAgents(snapshot).filter((agent) => agent.pane_id === this.owned!.paneId); if (occupants.length !== 0) throw new Error("Refusing cleanup because startup pane ownership is uncertain."); await this.connection.client.call("pane.close", { pane_id: this.owned.paneId }); } } } catch (error) { failure = error; } try { this.#unsubscribe(); await this.connection.close(); this.#removeRuntime(); } catch (error) { failure ??= error; } this.#snapshot = { ...this.#snapshot, connection: "closed", revision: this.#snapshot.revision + 1 }; if (failure) throw failure; }
+}
+
+export class BridgeChannel {
+	readonly socket: net.Socket; readonly decoder = new HerdrPiFrameDecoder(); readonly listeners = new Set<(frame: HerdrPiFrame) => void>(); readonly waiters = new Map<string, { resolve(frame: HerdrPiFrame): void; reject(error: Error): void }>(); readonly runId: string; readonly frames: HerdrPiFrame[] = [];
+	readonly failure: Promise<never>; #rejectFailure!: (error: Error) => void; #failed = false;
+	constructor(socketPath: string, runId: string) { this.runId = runId; this.failure = new Promise<never>((_resolve, reject) => { this.#rejectFailure = reject; }); this.failure.catch(() => {}); this.socket = net.createConnection(socketPath); this.socket.on("data", (chunk: Buffer) => { try { for (const frame of this.decoder.push(chunk)) { if (frame.runId !== runId) throw new Error("Bridge run identity mismatch."); this.frames.push(frame); if (this.frames.length > 1024) throw new Error("Bridge replay queue exceeded its bound."); const key = typeof frame.requestId === "string" ? `${frame.type}:${frame.requestId}` : ""; const waiter = this.waiters.get(key); if (waiter) { this.waiters.delete(key); waiter.resolve(frame); } for (const listener of this.listeners) listener(frame); } } catch (error) { this.fail(error as Error); } }); this.socket.on("error", (error) => this.fail(error)); this.socket.on("close", () => { if (!this.#failed) this.fail(new Error("Remote Pi bridge connection was lost; task state is unknown.")); }); }
+	fail(error: Error) { if (this.#failed) return; this.#failed = true; this.#rejectFailure(error); for (const waiter of this.waiters.values()) waiter.reject(error); this.waiters.clear(); }
+	get failed() { return this.#failed; }
+	wait(type: string, requestId: string): Promise<HerdrPiFrame> { return new Promise((resolve, reject) => this.waiters.set(`${type}:${requestId}`, { resolve, reject })); }
+	configure(resources: { agent: string; skills?: string[]; toolCeiling?: string[]; reads?: string[] | false }) { const requestId = `cfg_${randomBytes(6).toString("hex")}`; const waiting = this.wait("configured", requestId); this.socket.write(encodeHerdrPiFrame({ protocol: HERDR_PI_PROTOCOL, runId: this.runId, type: "configure", requestId, resources })); return waiting; }
+	supervisorDelivered(requestId: string) { this.socket.write(encodeHerdrPiFrame({ protocol: HERDR_PI_PROTOCOL, runId: this.runId, type: "supervisor-delivered", requestId })); }
+	prepare(requestId: string, operation: string, text?: string, supervisorId?: string) { const waiting = this.wait("prepared", requestId); this.socket.write(encodeHerdrPiFrame({ protocol: HERDR_PI_PROTOCOL, runId: this.runId, type: "prepare", requestId, operation, ...(text !== undefined ? { text } : {}), ...(supervisorId ? { supervisorId } : {}) })); return waiting; }
+	close() { this.socket.destroy(); }
+}
+
+function waitForReadyBridgeFrame(bridge: BridgeChannel, timeoutMs: number, timeoutMessage: string, configured = false): Promise<HerdrPiFrame> {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+		const listener = (frame: HerdrPiFrame) => {
+			if (frame.type !== "ready" || configured && frame.configured !== true) return;
+			clearTimeout(timer);
+			bridge.listeners.delete(listener);
+			resolve(frame);
+		};
+		bridge.listeners.add(listener);
+	});
+}
+
+export class HerdrPiSession implements ChildSession {
+	readonly #listeners = new Set<(event: ChildSessionEvent) => void>(); #messages: AgentMessage[] = []; #sequence = 0; #disposed = false; #aborted = false; #initialGit?: HerdrRemoteGitStatus; #finalGit?: HerdrRemoteGitStatus;
+	readonly #operations = new Map<string, { resolve(): void; reject(error: Error): void; accepted: boolean; settled: boolean }>();
+	#snapshot: HerdrRunSnapshot; bridgeForward: { close(): Promise<void> }; bridge: BridgeChannel; readonly requestedTools: string[] | undefined; readonly model: string | undefined; #evidenceCursor = 0; #reconnecting?: Promise<void>; #reconnectFactory?: () => Promise<void>; #reconnectFailure?: Error;
+	#replyTimer?: NodeJS.Timeout; readonly supervisorDir: string | undefined; readonly runtime: ChildRuntimeConfig; readonly owner: HerdrPlacedRunOwner;
+	constructor(owner: HerdrPlacedRunOwner, bridgeForward: { close(): Promise<void> }, bridge: BridgeChannel, requestedTools: string[] | undefined, model: string | undefined, runtime: ChildRuntimeConfig, initialGit?: HerdrRemoteGitStatus) { this.owner = owner; this.bridgeForward = bridgeForward; this.bridge = bridge; this.requestedTools = requestedTools; this.model = model; this.runtime = runtime; this.supervisorDir = runtime.supervisorChannelDir; this.#snapshot = { connection: "connected", state: "ready", identity: owner.identity, revision: 0 }; this.#initialGit = initialGit; bridge.listeners.add((frame) => this.#frame(frame)); if (this.supervisorDir) { this.#replyTimer = setInterval(() => { const replies = path.join(this.supervisorDir!, "replies"); for (const name of fs.existsSync(replies) ? fs.readdirSync(replies) : []) { const file = path.join(replies, name); try { const value = JSON.parse(fs.readFileSync(file, "utf8")) as { message?: unknown; requestId?: unknown }; if (typeof value.message === "string" && typeof value.requestId === "string") void this.#operation("supervisor-reply", value.message, value.requestId).then(() => fs.rmSync(file, { force: true })); } catch {} } }, 50); this.#replyTimer.unref?.(); } }
+	get identity(): HerdrRunIdentity { return this.owner.identity!; } set identity(value: HerdrRunIdentity) { this.owner.identity = value; }
+	get connection(): HerdrForwardedConnection { return this.owner.connection; } set connection(value: HerdrForwardedConnection) { this.owner.connection = value; }
+	armReconnect(factory: () => Promise<void>) { this.#reconnectFactory = factory; const observed = this.bridge; observed.failure.catch(() => { if (this.bridge === observed) void this.reconnect(); }); }
+	get evidenceCursor() { return this.#evidenceCursor; }
+	async reconnect() { if (this.#disposed || !this.#reconnectFactory || this.#reconnectFailure) return; this.#snapshot = { ...this.#snapshot, connection: "unknown", state: "unknown", revision: this.#snapshot.revision + 1 }; this.#reconnecting ??= this.#reconnectFactory().catch((error) => { const unknown = this.#reconnectFailure = new Error(`Remote Pi reconciliation failed; task state is unknown: ${error instanceof Error ? error.message : String(error)}`); for (const operation of this.#operations.values()) if (!operation.settled) { operation.settled = true; operation.reject(unknown); } }).finally(() => { this.#reconnecting = undefined; }); await this.#reconnecting; }
+	async replaceTransport(input: { connection: HerdrForwardedConnection; bridgeForward: { close(): Promise<void> }; bridge: BridgeChannel; unsubscribe: () => void; paneId: string; cursor: number; state: HerdrRunSnapshot["state"] }) { if (this.#disposed) { input.unsubscribe(); input.bridge.close(); await input.bridgeForward.close(); await input.connection.close(); return; } const old = { bridgeForward: this.bridgeForward, bridge: this.bridge }; this.bridgeForward = input.bridgeForward; this.bridge = input.bridge; this.identity = { ...this.identity, paneId: input.paneId }; this.#reconnectFailure = undefined; for (const frame of input.bridge.frames) if (typeof frame.cursor === "number" && frame.cursor > this.#evidenceCursor) this.#frame(frame); input.bridge.listeners.add((frame) => this.#frame(frame)); for (const operation of this.#operations.values()) if (!operation.accepted && !operation.settled) { operation.settled = true; operation.reject(new Error("Remote operation was not accepted before transport loss; task state is unknown.")); } this.#evidenceCursor = Math.max(this.#evidenceCursor, input.cursor); this.#snapshot = { connection: "connected", state: input.state, identity: this.identity, revision: this.#snapshot.revision + 1 }; const ownerReplacement = this.owner.replaceConnection({ connection: input.connection, unsubscribe: input.unsubscribe, paneId: input.paneId, state: input.state }); old.bridge.close(); await old.bridgeForward.close(); await ownerReplacement; if (this.#disposed) { await this.owner.cleanup(this.#aborted); return; } this.armReconnect(this.#reconnectFactory!); }
+	observeHerdr(value: unknown) { const data = value && typeof value === "object" ? (value as { data?: Record<string, unknown> }).data : undefined; if (!data || (data.terminal_id !== this.identity.terminalId && data.pane_id !== this.identity.paneId)) return; this.#snapshot = { ...this.#snapshot, revision: this.#snapshot.revision + 1, state: herdrRunState(data.agent_status, this.#snapshot.state) }; }
+	#frame(frame: HerdrPiFrame) { if (typeof frame.cursor === "number") { if (frame.cursor <= this.#evidenceCursor) return; this.#evidenceCursor = frame.cursor; } if (frame.nativeSessionId !== this.identity.nativeSessionId) { this.bridge.fail(new Error("Remote Pi native session identity changed.")); void this.connection.close(); return; } if (frame.type === "accepted" && typeof frame.requestId === "string") { const operation = this.#operations.get(frame.requestId); if (operation) operation.accepted = true; } if (frame.type === "supervisor-request" && this.supervisorDir && typeof frame.requestId === "string") this.#relaySupervisor(frame); if (frame.type === "event" && frame.event && typeof frame.event === "object") { const event = frame.event as ChildSessionEvent; const message = event.message as AgentMessage | undefined; if (event.type === "message_end" && message) this.#messages.push(message); for (const listener of this.#listeners) listener(event); } if (frame.type === "settled" && typeof frame.requestId === "string") { if (frame.finalAssistant && typeof frame.finalAssistant === "object") { const message = frame.finalAssistant as AgentMessage; if (!this.#messages.includes(message)) this.#messages.push(message); } if (frame.finalGit && typeof frame.finalGit === "object") this.#finalGit = frame.finalGit as HerdrRemoteGitStatus; const operation = this.#operations.get(frame.requestId); if (operation && !operation.settled) { operation.accepted = true; operation.settled = true; frame.idle === true && frame.pending === false ? operation.resolve() : operation.reject(new Error("Remote Pi did not settle with an empty native queue.")); } for (const listener of this.#listeners) listener({ type: "agent_settled" }); } }
+	#relaySupervisor(frame: HerdrPiFrame) { if (!this.supervisorDir || typeof frame.requestId !== "string") return; const reason = frame.reason; if (reason !== "need_decision" && reason !== "interview_request" && reason !== "progress_update") return; const createdAt = Date.now(); const file = path.join(this.supervisorDir, "requests", `${path.basename(frame.requestId)}.json`); const request = { type: "subagent.supervisor.request", id: frame.requestId, createdAt, ...(reason !== "progress_update" ? { expiresAt: createdAt + 10 * 60_000 } : {}), reason, message: typeof frame.message === "string" ? frame.message : "", ...(frame.interview && typeof frame.interview === "object" ? { interview: frame.interview } : {}), expectsReply: reason !== "progress_update", runId: this.runtime.runId ?? this.identity.runId, agent: this.runtime.agent ?? "remote", childIndex: this.runtime.childIndex ?? 0, orchestratorSessionId: this.runtime.orchestratorSessionId }; try { fs.writeFileSync(file, JSON.stringify(request), { mode: 0o600, flag: "wx" }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; const existing = JSON.parse(fs.readFileSync(file, "utf8")) as { id?: unknown; reason?: unknown }; if (existing.id !== frame.requestId || existing.reason !== reason) throw new Error("Supervisor relay identity changed during replay."); } if (reason === "progress_update") this.bridge.supervisorDelivered(frame.requestId); }
+	async #operation(operation: string, text?: string, supervisorId?: string): Promise<void> { const requestId = `${++this.#sequence}_${randomBytes(5).toString("hex")}`; let completion: Promise<void> = Promise.resolve(); if (operation === "prompt") completion = new Promise<void>((resolve, reject) => this.#operations.set(requestId, { resolve, reject, accepted: false, settled: false })); try { await Promise.race([this.bridge.prepare(requestId, operation, text, supervisorId), this.bridge.failure]); await this.connection.client.call("agent.prompt", { target: this.identity.agentName, text: `/pi-subagents-bridge ${requestId}` }); await completion; } catch (error) { if (operation === "prompt" && this.bridge.failed) { await this.reconnect(); await completion; return; } const pending = this.#operations.get(requestId); if (pending) pending.settled = true; throw error; } finally { if (operation === "prompt") this.#operations.delete(requestId); } }
+	subscribe(listener: (event: ChildSessionEvent) => void) { this.#listeners.add(listener); return () => this.#listeners.delete(listener); }
+	prompt(text: string) { return this.#operation("prompt", text); } steer(text: string) { return this.#operation("steer", text); } followUp(text: string) { return this.#operation("follow-up", text); } async abort() { this.#aborted = true; await this.#operation("abort"); }
+	async dispose() { if (this.#disposed) return; this.#disposed = true; if (this.#replyTimer) clearInterval(this.#replyTimer); this.bridge.close(); await this.bridgeForward.close(); await this.owner.cleanup(this.#aborted); this.#snapshot = { ...this.#snapshot, connection: "closed" }; }
+	get messages() { return this.#messages; } get sessionFile() { return undefined; } get sessionId() { return this.identity.nativeSessionId; } get modelId() { return this.model; }
+	get machineEvidence() { return { machineId: this.identity.machineId, ...(this.#initialGit ? { initial: this.#initialGit } : {}), ...(this.#finalGit ? { final: this.#finalGit } : {}) }; }
+	get placementSnapshot() { return this.owner.snapshot; }
+}
+
+export async function reconnectHerdrPiSession(session: HerdrPiSession, launch: ChildSessionLaunch, dependencies: { connect?: typeof connectHerdrMachine; discoverManifest?: typeof discoverBridgeManifest; createBridge?: (socketPath: string, runId: string) => BridgeChannel } = {}): Promise<void> {
+	const connect = dependencies.connect ?? connectHerdrMachine, discoverManifest = dependencies.discoverManifest ?? discoverBridgeManifest, createBridge = dependencies.createBridge ?? ((socketPath: string, runId: string) => new BridgeChannel(socketPath, runId));
+	let validated: { connection: HerdrForwardedConnection; unsubscribe: () => void; bridgeForward: { socketPath: string; close(): Promise<void> }; bridge: BridgeChannel; candidate: { adopted: boolean; lost?: Error } } | undefined;
+	const result = await boundedHerdrReconnect(session.identity, session.evidenceCursor, async () => {
+		const connection = await connect(launch.machine!); let unsubscribe = () => {}; let bridgeForward: { socketPath: string; close(): Promise<void> } | undefined; let bridge: BridgeChannel | undefined; const generation: { adopted: boolean; lost?: Error } = { adopted: false };
+		try {
+			const snapshot = parseHerdrSessionSnapshot(await connection.client.call<Record<string, unknown>>("session.snapshot"));
+			const agents = snapshotAgents(snapshot);
+			const manifest = await discoverManifest(launch.machine!, session.identity.runId, session.identity.runtimeDir); bridgeForward = await connection.forwardRemoteSocket(manifest.socketPath, "bridge-reconnect"); bridge = createBridge(bridgeForward.socketPath, session.identity.runId);
+			const ready = await waitForReadyBridgeFrame(bridge, 8_000, "Reconnected bridge handshake timed out.", true);
+			const candidate: HerdrReconnectCandidate = { endpoint: connection.endpoint, agents, bridge: { runId: ready.runId, nativeSessionId: ready.nativeSessionId as string | undefined, packageVersion: ready.packageVersion as string | undefined, protocol: ready.protocol, evidenceCursor: ready.evidenceCursor as number | undefined, evidenceFloor: ready.evidenceFloor as number | undefined } };
+			const check = reconcileHerdrReconnect(session.identity, candidate, session.evidenceCursor); if (!check.ok) throw new Error(check.reason);
+			unsubscribe = await connection.client.subscribe(herdrStatusSubscriptions(check.paneId), (event) => { session.owner.observeEvent(event); session.observeHerdr(event); }, (error) => { if (!generation.adopted) { generation.lost ??= error; return; } session.owner.markConnectionUnknown(connection); void session.reconnect(); });
+			if (generation.lost) throw generation.lost; validated = { connection, unsubscribe, bridgeForward, bridge, candidate: generation }; return candidate;
+		} catch (error) { unsubscribe(); bridge?.close(); await bridgeForward?.close(); await connection.close(); throw error; }
+	}, { attempts: 3, deadlineMs: 15_000, disposed: () => (session.placementSnapshot as HerdrRunSnapshot).connection === "closed" });
+	if (!result.ok) throw new Error(`Pane-native reconnect remains unknown: ${result.reason}`);
+	if (!validated) throw new Error("Pane-native reconnect produced no validated transport.");
+	if (validated.candidate.lost) { validated.unsubscribe(); validated.bridge.close(); await validated.bridgeForward.close(); await validated.connection.close(); throw validated.candidate.lost; }
+	validated.candidate.adopted = true;
+	await session.replaceTransport({ ...validated, paneId: result.paneId, cursor: result.cursor, state: result.state });
+}
+
+export async function createHerdrPiSession(launch: ChildSessionLaunch): Promise<ChildSession> {
+	if (!launch.machine) throw new Error("Pane-native Pi launch requires a saved machine.");
+	const policy = serializeHerdrPiLaunch(launch); const runId = safeRunId(launch.runtime.runId); const owner = await HerdrPlacedRunOwner.create(launch.machine, runId); const runtimeDir = owner.runtimeDir, connection = owner.connection; let owned: { workspaceId: string; tabId: string; paneId: string } | undefined; let agentName: string | undefined; let observeHerdr: ((event: unknown) => void) | undefined;
+	try {
+		let reconnectSession: HerdrPiSession | undefined; owned = await owner.provision(); await owner.subscribe((event) => observeHerdr?.(event), () => void reconnectSession?.reconnect());
+		agentName = `pi-${runId.slice(-20)}`; const { terminalId } = await owner.start("pi", agentName, policy.args);
+		const manifest = await discoverBridgeManifest(launch.machine, runId, runtimeDir); if (manifest.protocol !== HERDR_PI_PROTOCOL || manifest.packageVersion !== packageJson.version) throw new Error(`Remote pi-subagents bridge version mismatch (remote ${manifest.packageVersion}, local ${packageJson.version}).`);
+		const bridgeForward = await connection.forwardRemoteSocket(manifest.socketPath, "bridge"); const bridge = new BridgeChannel(bridgeForward.socketPath, runId);
+		const ready = await waitForReadyBridgeFrame(bridge, 15_000, "Remote Pi bridge handshake timed out.");
+		if (ready.packageVersion !== packageJson.version || ready.nativeSessionId !== manifest.nativeSessionId || ready.cwd !== launch.machine.cwd) throw new Error("Remote Pi bridge handshake identity mismatch.");
+		const configured = await Promise.race([bridge.configure(policy.resources), bridge.failure]);
+		if (configured.nativeSessionId !== manifest.nativeSessionId || configured.agent !== policy.resources.agent) throw new Error("Remote Pi resource resolution identity mismatch.");
+		if (!Array.isArray(configured.tools) || (policy.resources.toolCeiling && (configured.tools as unknown[]).some((tool) => !policy.resources.toolCeiling!.includes(String(tool))))) throw new Error("Remote Pi active-tool ceiling acknowledgement mismatch.");
+		if (launch.model && configured.model !== launch.model.split(":")[0]) throw new Error(`Remote Pi model '${launch.model}' did not resolve to the requested provider/model.`);
+		const identity: HerdrRunIdentity = { runId, machineId: launch.machine.id, target: launch.machine.target, session: connection.endpoint.session, workspaceId: owned.workspaceId, tabId: owned.tabId, paneId: owned.paneId, terminalId, agentName, nativeSessionId: manifest.nativeSessionId, cwd: launch.machine.cwd, runtimeDir };
+		owner.journal(identity);
+		const session = new HerdrPiSession(owner, bridgeForward, bridge, (configured.tools as string[] | undefined), typeof ready.model === "string" ? ready.model : undefined, launch.runtime, ready.initialGit as HerdrRemoteGitStatus | undefined); reconnectSession = session; observeHerdr = (event) => session.observeHerdr(event); session.armReconnect(() => reconnectHerdrPiSession(session, launch)); return session;
+	} catch (error) { await owner.cleanup(); throw error; }
+}
+
+export function createPlacementAwareChildSessionFactory(local: ChildSessionFactory, createRemote: (launch: ChildSessionLaunch) => Promise<ChildSession> = createHerdrPiSession): ChildSessionFactory {
+	const remote = new Set<ChildSession>(); return { async create(launch) { if (!launch.machine) return local.create(launch); serializeHerdrPiLaunch(launch); const child = await createRemote(launch); remote.add(child); return child; }, async dispose() { await Promise.allSettled([...remote].map((child) => child.dispose())); remote.clear(); await local.dispose(); } };
+}

package/dist/extensions/pi-subagents/src/runs/shared/mcp-config-sources.ts

@@ -3,6 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { findConfiguredProjectRoot } from "../../agents/agents.ts";
 import { getAgentDir, getConfigDirName, getProjectConfigDir } from "../../shared/utils.ts";
+import type { McpToolPrefix } from "./mcp-direct-tool-grant.ts";
 
 const PACKAGE_CONFIG_ROOT = "npm";
 const PACKAGE_GIT_ROOT = "git";
@@ -32,11 +33,14 @@ export interface McpServerDefinition {
 	exposeResources?: boolean;
 	includeTools?: string[];
 	excludeTools?: string[];
+	/** Per-server override of the global `settings.toolPrefix`, matching the adapter. */
+	toolPrefix?: McpToolPrefix;
 	protocolVersion?: string;
 	directTools?: boolean | string[];
 	httpTransport?: string;
 	pluginDataDir?: string;
 	literalEnv?: boolean;
+	inheritEnv?: boolean;
 }
 
 export function isMcpServerDefinition(value: unknown): value is McpServerDefinition {
@@ -50,7 +54,7 @@ export function isMcpServerDefinition(value: unknown): value is McpServerDefinit
 	for (const field of ["env", "headers"] as const) {
 		if (value[field] !== undefined && !isStringRecord(value[field])) return false;
 	}
-	for (const field of ["exposeResources", "literalEnv"] as const) {
+	for (const field of ["exposeResources", "literalEnv", "inheritEnv"] as const) {
 		if (value[field] !== undefined && typeof value[field] !== "boolean") return false;
 	}
 	if (value.requestHeadersCommand !== undefined && !isRequestHeadersCommand(value.requestHeadersCommand)) return false;
@@ -419,4 +423,4 @@ function readJson(filePath: string): unknown | undefined {
 	} catch (error) {
 		throw new Error(`Invalid JSON in '${filePath}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 	}
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -67,6 +67,17 @@ export interface McpRuntimeSnapshotHost {
 	events: {
 		emit(event: string, request: McpRuntimeSnapshotRequest): void;
 	};
+	getAllTools?(): readonly McpHostToolInfo[];
+	getCommands?(): readonly { name: string; sourceInfo: { path: string } }[];
+	/** Pi 0.99: servers extensions added with `pi.registerMcpServer()`. */
+	getMcpServers?(): readonly { name: string }[];
+}
+
+/** A `pi.getAllTools()` entry; `exposure` and `namespace` exist only from Pi 0.99. */
+export interface McpHostToolInfo {
+	name: string;
+	exposure?: string;
+	namespace?: { name: string };
 }
 
 interface CachedTool {
@@ -96,6 +107,8 @@ export interface McpDirectToolResolution {
 	/** Normal loaded config plus the selected runtime server definitions. */
 	mcpConfig?: McpConfig;
 	runtimeServerNames?: string[];
+	/** Set when the selectors were resolved against Pi's built-in MCP instead of pi-mcp-adapter. */
+	builtin?: true;
 }
 
 export function resolveMcpDirectToolResolution(
@@ -106,6 +119,9 @@ export function resolveMcpDirectToolResolution(
 ): McpDirectToolResolution {
 	const selectors = normalizeMcpDirectToolSelectors(mcpDirectTools);
 	if (selectors.length === 0) return { selections: [], unresolvedSelectors: [] };
+	if (usesBuiltinMcp(runtimeSnapshotHost)) {
+		return resolveBuiltinMcpSelections(selectors, runtimeSnapshotHost.getAllTools?.() ?? []);
+	}
 
 	const config = configOverride ?? loadMcpConfig(cwd);
 	const { servers: selectedServers, tools: selectedTools } = parseMcpDirectToolSelectors(selectors);
@@ -146,6 +162,78 @@ export function resolveMcpDirectToolSelections(
 	return resolveMcpDirectToolResolution(mcpDirectTools, cwd, runtimeSnapshotHost).selections;
 }
 
+/**
+ * pi-mcp-adapter keeps priority whenever it is loaded. 2.x registers /mcp, so Pi does not load its
+ * built-in MCP. 3.x always registers /mcp-adapter and leaves /mcp to the built-in MCP.
+ */
+function usesBuiltinMcp(host: McpRuntimeSnapshotHost | undefined): host is McpRuntimeSnapshotHost {
+	const commands = host?.getCommands?.() ?? [];
+	return commands.find((command) => command.name === "mcp")?.sourceInfo.path === "builtin:mcp"
+		&& !commands.some((command) => /^mcp-adapter(?::\d+)?$/.test(command.name));
+}
+
+/**
+ * Pi names built-in MCP tools `mcp__<server>__<tool>` with everything but `[A-Za-z0-9_]` replaced
+ * by `_`, in the namespace `mcp__<server>` with `-` replaced by `_`. Selectors name the raw tool;
+ * the server part may be the configured name or its `-`→`_` form, since Pi refuses two servers
+ * whose names differ only in `-` and `_`. An overlong name, or one an earlier tool already took (`a_b`
+ * before `a.b`), gets a suffix hashed from the raw server and tool (Pi's `createMcpToolName`), so
+ * that suffixed name identifies the tool, and only the configured server name selects it. The
+ * unsuffixed name may belong to another raw tool; the
+ * child checks each granted tool's raw identity before it exposes the tool.
+ */
+function resolveBuiltinMcpSelections(selectors: string[], tools: readonly McpHostToolInfo[]): McpDirectToolResolution {
+	const selections: ResolvedMcpDirectToolSelection[] = [];
+	const unresolvedSelectors: string[] = [];
+	for (const selector of selectors) {
+		const slash = selector.indexOf("/");
+		const server = slash === -1 ? selector : selector.slice(0, slash);
+		const inServer = tools.filter((tool) => tool.namespace?.name === `mcp__${server.replace(/-/g, "_")}`);
+		const toolName = slash === -1 ? undefined : builtinMcpToolNames(server, selector.slice(slash + 1)).find((name) => inServer.some((tool) => tool.name === name));
+		const matches = inServer.filter((tool) => tool.exposure !== "hidden" && (slash === -1 || tool.name === toolName));
+		if (matches.length === 0) unresolvedSelectors.push(selector);
+		for (const tool of matches) {
+			if (!selections.some((selection) => selection.name === tool.name)) selections.push({ name: tool.name, selector });
+		}
+	}
+	return { selections, unresolvedSelectors, builtin: true };
+}
+
+/** The names Pi's `createMcpToolName` can give a raw tool, the hash-suffixed one first. */
+function builtinMcpToolNames(server: string, tool: string): string[] {
+	const name = `mcp__${server}__${tool}`.replace(/[^A-Za-z0-9_]/g, "_");
+	const hash = createHash("sha256").update(`${server}\0${tool}`).digest("hex").slice(0, 8);
+	const suffixed = `${name.slice(0, 64 - hash.length - 1)}_${hash}`;
+	return name.length <= 64 ? [suffixed, name] : [suffixed];
+}
+
+export function formatUnresolvedBuiltinMcpSelectors(agentName: string | undefined, selectors: readonly string[]): string {
+	const subject = agentName ? `Agent '${agentName}'` : "Subagent";
+	return `${subject} selects MCP tools that Pi's built-in MCP does not offer: ${selectors.map((selector) => `mcp:${selector}`).join(", ")}. The server may be missing, disconnected, still connecting, or its tools hidden; check /mcp.`;
+}
+
+/**
+ * Selected servers that only an extension registered, which a child without ambient extensions
+ * never has. A server of the same name in an `mcp.json` the child reads takes precedence; like Pi,
+ * the project file is read only when the project is trusted.
+ */
+export function extensionOnlyMcpServers(selections: readonly ResolvedMcpDirectToolSelection[], host: McpRuntimeSnapshotHost, cwd: string, projectTrusted: boolean): string[] {
+	const registered = new Set(host.getMcpServers?.().map(({ name }) => name));
+	const servers = [...new Set(selections.map(({ selector }) => selector.split("/")[0]!))].filter((server) => registered.has(server));
+	if (servers.length === 0) return [];
+	const files = [path.join(getAgentDir(), "mcp.json"), ...(projectTrusted ? [path.join(cwd, ".selesai", "mcp.json")] : [])];
+	const configured = new Set(files.flatMap((file) => {
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+		} catch {
+			return [];
+		}
+		return isRecord(parsed) && isRecord(parsed.mcpServers) ? Object.keys(parsed.mcpServers) : [];
+	}));
+	return servers.filter((server) => !configured.has(server));
+}
+
 function loadMetadataCache(): MetadataCache | null {
 	const cachePath = path.join(getAgentDir(), "mcp-cache.json");
 	let parsed: unknown;
@@ -262,15 +350,17 @@ function loadMcpConfig(cwd: string): McpConfig {
 }
 
 function getConfigPaths(projectRoot: string): string[] {
-	const piGlobalPath = path.join(getAgentDir(), "mcp.json");
-	const projectPath = path.resolve(projectRoot, ".mcp.json");
-	const projectPiPath = path.resolve(getProjectConfigDir(projectRoot), "mcp.json");
-	const sources: string[] = [];
-	if (GENERIC_GLOBAL_CONFIG_PATH !== piGlobalPath) sources.push(GENERIC_GLOBAL_CONFIG_PATH);
-	sources.push(piGlobalPath);
-	if (projectPath !== piGlobalPath) sources.push(projectPath);
-	if (projectPiPath !== piGlobalPath && projectPiPath !== projectPath) sources.push(projectPiPath);
-	return sources;
+	const agentDir = getAgentDir();
+	const projectDir = getProjectConfigDir(projectRoot);
+	// pi-mcp-adapter 3.x reads mcp-adapter.json. Pi's own mcp.json files belong to
+	// Pi's built-in MCP support, so servers there are never adapter-registered.
+	const candidates = [
+		GENERIC_GLOBAL_CONFIG_PATH,
+		path.join(agentDir, "mcp-adapter.json"),
+		path.resolve(projectRoot, ".mcp.json"),
+		path.join(projectDir, "mcp-adapter.json"),
+	];
+	return [...new Set(candidates)];
 }
 
 function readConfig(configPath: string): McpConfig | null {
@@ -301,7 +391,7 @@ function parseServerEntries(value: unknown): Record<string, ServerEntry> {
 
 function parseSettings(value: unknown): McpConfig["settings"] | undefined {
 	if (!isRecord(value)) return undefined;
-	const toolPrefix = value.toolPrefix === "server" || value.toolPrefix === "short" || value.toolPrefix === "none" ? value.toolPrefix : undefined;
+	const toolPrefix = value.toolPrefix === "server" || value.toolPrefix === "short" || value.toolPrefix === "none" || value.toolPrefix === "mcp" ? value.toolPrefix : undefined;
 	const directTools = typeof value.directTools === "boolean" ? value.directTools : undefined;
 	const settings: NonNullable<McpConfig["settings"]> = {
 		...(toolPrefix ? { toolPrefix } : {}),
@@ -381,11 +471,16 @@ function isServerCacheValid(entry: ServerCacheEntry | undefined, definition: Ser
 }
 
 export function computeMcpServerHash(definition: ServerEntry): string {
+	// Aligned with pi-mcp-adapter's computeServerHash; since 3.1.0 stdio hashes include
+	// inheritEnv/literalEnv. A mismatch leaves that server's cached direct-tool selectors unresolved.
+	const isStdio = definition.command !== undefined;
+	const literalEnv = isStdio && definition.literalEnv === true;
 	const identity: Record<string, unknown> = {
-		command: definition.command,
+		command: resolveConfigPath(definition.command),
 		args: definition.args,
 		socket: resolveConfigPath(definition.socket),
-		env: interpolateEnvRecord(definition.env),
+		env: literalEnv ? definition.env : interpolateEnvRecord(definition.env),
+		...(isStdio ? { inheritEnv: definition.inheritEnv !== false, literalEnv } : {}),
 		cwd: resolveConfigPath(definition.cwd),
 		url: resolveServerUrl(definition),
 		headers: interpolateEnvRecord(definition.headers),
@@ -481,4 +576,4 @@ function stableStringify(value: unknown): string {
 	if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
 	const obj = value as Record<string, unknown>;
 	return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`).join(",")}}`;
-}
+}

package/dist/extensions/pi-subagents/src/runs/shared/mcp-direct-tool-grant.ts

@@ -1,11 +1,13 @@
 const BUILTIN_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
 
-export type McpToolPrefix = "server" | "none" | "short";
+export type McpToolPrefix = "server" | "none" | "short" | "mcp";
 
 export interface McpGrantServerFacts {
 	readonly exposeResources?: boolean;
 	readonly includeTools?: readonly unknown[];
 	readonly excludeTools?: readonly unknown[];
+	/** Per-server prefix override, matching the adapter's `ServerEntry.toolPrefix`. */
+	readonly toolPrefix?: unknown;
 }
 
 export interface McpGrantToolMetadata {
@@ -73,7 +75,6 @@ export function planMcpDirectToolGrant(input: McpDirectToolGrantInput): McpDirec
 	const { servers: selectedServers, tools: selectedTools } = parseMcpDirectToolSelectors(selectors);
 	const selections: ResolvedMcpDirectToolSelection[] = [];
 	const seenNames = new Set<string>();
-	const prefix = normalizeMcpToolPrefix(input.toolPrefix);
 
 	for (const [serverName, server] of Object.entries(input.servers)) {
 		const metadata = input.metadata[serverName];
@@ -83,6 +84,7 @@ export function planMcpDirectToolGrant(input: McpDirectToolGrantInput): McpDirec
 			? true
 			: selectedTools.get(serverName);
 		if (!toolFilter) continue;
+		const prefix = normalizeMcpToolPrefix(server.toolPrefix ?? input.toolPrefix);
 
 		for (const tool of Array.isArray(metadata.tools) ? metadata.tools : []) {
 			if (typeof tool?.name !== "string" || !tool.name) continue;
@@ -116,7 +118,7 @@ export function planMcpDirectToolGrant(input: McpDirectToolGrantInput): McpDirec
 }
 
 export function normalizeMcpToolPrefix(value: unknown): McpToolPrefix {
-	return value === "none" || value === "short" || value === "server" ? value : "server";
+	return value === "none" || value === "short" || value === "mcp" || value === "server" ? value : "server";
 }
 
 export function formatUnresolvedMcpDirectToolSelectors(selectors: readonly string[]): string {
@@ -125,13 +127,26 @@ export function formatUnresolvedMcpDirectToolSelectors(selectors: readonly strin
 
 function getServerPrefix(serverName: string, mode: McpToolPrefix): string {
 	if (mode === "none") return "";
-	if (mode === "short") return serverName.replace(/-?mcp$/i, "") || "mcp";
-	return serverName;
+	if (mode === "short") return sanitizeServerPrefix(serverName.replace(/-?mcp$/i, "")) || "mcp";
+	if (mode === "mcp") return `mcp__${sanitizeServerPrefix(serverName)}`;
+	return sanitizeServerPrefix(serverName);
+}
+
+/** Adapter parity: characters outside [A-Za-z0-9_-] become `_<code point in hex>_`. */
+function sanitizeServerPrefix(serverName: string): string {
+	return Array.from(serverName, (char) => /^[A-Za-z0-9_-]$/.test(char) ? char : `_${char.codePointAt(0)!.toString(16)}_`).join("");
 }
 
 function formatToolName(toolName: string, serverName: string, prefix: McpToolPrefix): string {
 	const serverPrefix = getServerPrefix(serverName, prefix);
-	return serverPrefix ? `${serverPrefix}_${toolName}` : toolName;
+	const sanitized = toolName.replace(/\./g, "_");
+	// Some servers prefix their tool names with the server name (codegraph ->
+	// codegraph_explore). pi-mcp-adapter registers such a name unchanged, so
+	// keep the two sides in agreement instead of demanding codegraph_codegraph_explore.
+	if (serverPrefix && sanitized.startsWith(`${serverPrefix}_`) && sanitized.length > serverPrefix.length + 1) {
+		return sanitized;
+	}
+	return serverPrefix ? `${serverPrefix}_${sanitized}` : sanitized;
 }
 
 function isToolAllowed(
@@ -153,6 +168,7 @@ function toolNameCandidates(toolName: string, serverName: string, prefix: McpToo
 		formatToolName(toolName, serverName, prefix),
 		formatToolName(toolName, serverName, "server"),
 		formatToolName(toolName, serverName, "short"),
+		formatToolName(toolName, serverName, "mcp"),
 		formatToolName(toolName, serverName, "none"),
 	]);
 }
@@ -191,4 +207,4 @@ function resourceNameToToolName(name: string): string {
 		.toLowerCase();
 	if (!result || /^\d/.test(result)) result = `resource${result ? `_${result}` : ""}`;
 	return result;
-}
+}