pi-subagents 0.80.0 → 0.82.0

package/src/runs/shared/child-session.d.ts

@@ -2,7 +2,7 @@ import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
 import type { RequiredChildExtensionSnapshot } from "../../shared/required-child-extensions.ts";
-import type { HerdrMachineReference, HerdrRemoteGitStatus } from "../../shared/types.ts";
+import type { PlacementMachineReference, HerdrRemoteGitStatus } from "../../shared/types.ts";
 export interface ChildSessionEvent {
     type: string;
     [key: string]: unknown;
@@ -32,7 +32,7 @@ export type ChildSessionStorage = {
 export interface ChildSessionLaunch {
     cwd: string;
     /** Resolved pane-native placement. Local launches omit this field. */
-    machine?: HerdrMachineReference;
+    machine?: PlacementMachineReference;
     /** The launching session's project trust; undefined keeps Pi's default for hosts without trust. */
     projectTrusted?: boolean;
     /** Process-local provider source owned by the invoking foreground parent. */
@@ -107,6 +107,7 @@ export interface ChildSession {
     readonly virtualModelId?: string;
     readonly contextWindow?: number;
     readonly machineEvidence?: {
+        provider: PlacementMachineReference["provider"];
         machineId: string;
         initial?: HerdrRemoteGitStatus;
         final?: HerdrRemoteGitStatus;

package/src/runs/shared/child-session.js

@@ -76,6 +76,34 @@ function inheritParentProviders(modelRuntime, parentProviders, claimedProviderId
 }
 const CHILD_PROMPT_RUNTIME_EXTENSION_PATH = "<inline:pi-subagents:prompt-runtime>";
 const CHILD_PROMPT_BOUNDARY_EXTENSION_PATH = "<inline:pi-subagents:prompt-boundary>";
+/** Same class as UNICODE_SPACES in pi-coding-agent dist/utils/paths.js, which resolvePath(..., { normalizeUnicodeSpaces: true }) replaces with a space. */
+const PI_UNICODE_SPACES = new RegExp("[\\u00A0\\u2000-\\u200A\\u202F\\u205F\\u3000]", "g");
+function childExtensionFileIdentity(extensionPath) {
+    if (!path.isAbsolute(extensionPath))
+        return undefined;
+    try {
+        const stat = fs.statSync(extensionPath, { bigint: true });
+        return stat.isFile() ? `${stat.dev}:${stat.ino}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function createRequiredChildExtensionIdentity(requiredPaths) {
+    const aliases = new Map([...requiredPaths].map((extensionPath) => [extensionPath, childExtensionFileIdentity(extensionPath) ?? extensionPath]));
+    const identities = new Set(aliases.values());
+    return (extensionPath) => {
+        const known = aliases.get(extensionPath);
+        if (known !== undefined)
+            return known;
+        const identity = childExtensionFileIdentity(extensionPath);
+        if (identity === undefined || !identities.has(identity))
+            return undefined;
+        // Retain the alias even if the extension removes its file before reporting a failure.
+        aliases.set(extensionPath, identity);
+        return identity;
+    };
+}
 /** The prompt runtime filters parent-only context before ambient extensions inspect
  *  the child prompt, and the boundary hook appends the child boundary after every
  *  extension has added its prompt sections. Every other extension keeps its order. */
@@ -229,7 +257,7 @@ function missingBuiltinMcpTools(session, names) {
     const direct = new Set(session.getAllTools().filter((tool) => tool.exposure === "direct").map(({ name }) => name));
     return names.filter((name) => !active.has(name) || !direct.has(name));
 }
-function flushQueuedProviderRegistrations(loader, modelRuntime, onError, requiredPaths) {
+function flushQueuedProviderRegistrations(loader, modelRuntime, onError, isRequiredSource) {
     const claimedProviderIds = new Set();
     if (!("getExtensions" in loader) || typeof loader.getExtensions !== "function")
         return { claimedProviderIds, registered: false };
@@ -243,7 +271,7 @@ function flushQueuedProviderRegistrations(loader, modelRuntime, onError, require
         }
         catch (error) {
             onError?.({ extensionPath, event: "register_provider", error });
-            if (requiredPaths.has(extensionPath))
+            if (isRequiredSource(extensionPath))
                 throw new Error(`Required child extension provider registration failed for '${extensionPath}': ${error instanceof Error ? error.message : String(error)}`);
         }
     }
@@ -257,7 +285,7 @@ function flushQueuedProviderRegistrations(loader, modelRuntime, onError, require
         }
         catch (error) {
             onError?.({ extensionPath, event: "register_provider", error });
-            if (requiredPaths.has(extensionPath))
+            if (isRequiredSource(extensionPath))
                 throw new Error(`Required child extension provider registration failed for '${extensionPath}': ${error instanceof Error ? error.message : String(error)}`);
         }
     }
@@ -280,7 +308,7 @@ function flushQueuedProviderRegistrations(loader, modelRuntime, onError, require
         }
         catch (error) {
             onError?.({ extensionPath, event: "register_virtual_model", error });
-            if (requiredPaths.has(extensionPath))
+            if (isRequiredSource(extensionPath))
                 throw new Error(`Required child extension virtual model registration failed for '${extensionPath}': ${error instanceof Error ? error.message : String(error)}`);
         }
     }
@@ -394,6 +422,13 @@ export function createDefaultChildSessionFactory(options = {}) {
                             },
                         })) }]
                 : [];
+            const requiredPaths = new Set((launch.requiredExtensions ?? []).map(({ path }) => path));
+            const requiredExtensionIdentity = createRequiredChildExtensionIdentity(requiredPaths);
+            const resolvedExtensionPaths = new Map();
+            // Pi reports failures by source path, without resolvedPath. A source Pi never loaded is classified by the
+            // file it names, after Pi's Unicode-space normalization. A required extension that failed under an
+            // unmatched spelling is still rejected by the missing-identity check after loading.
+            const isRequiredSource = (extensionPath) => requiredPaths.size > 0 && requiredExtensionIdentity(resolvedExtensionPaths.get(extensionPath) ?? extensionPath.replace(PI_UNICODE_SPACES, " ")) !== undefined;
             const loader = new pi.DefaultResourceLoader({
                 cwd: launch.cwd,
                 agentDir,
@@ -435,16 +470,24 @@ export function createDefaultChildSessionFactory(options = {}) {
             };
             let inheritedProviders = new Set();
             const open = async () => {
-                const requiredPaths = new Set((launch.requiredExtensions ?? []).map(({ path }) => path));
                 applyProcessEnv(launch.processEnv);
                 if (!resetExtensionCacheOnReload(loader) && (launch.ambientExtensions || launch.extensionPaths.length))
                     launch.onExtensionError?.({ extensionPath: "<loader>", event: "load", error: new Error("pi's extension cache reset is unavailable; extensions loaded into this child share module state with other sessions in this process.") });
                 await loader.reload();
+                if (requiredPaths.size > 0)
+                    for (const extension of loader.getExtensions().extensions)
+                        resolvedExtensionPaths.set(extension.path, extension.resolvedPath);
                 const loadErrors = requiredPaths.size > 0
-                    ? loader.getExtensions().errors.filter(({ path }) => requiredPaths.has(path)) : [];
+                    ? loader.getExtensions().errors.filter(({ path }) => isRequiredSource(path)) : [];
                 if (loadErrors.length > 0)
                     throw new Error(`Required child extension failed to load: ${loadErrors.map(({ path, error }) => `${path}: ${error}`).join("; ")}`);
-                const queued = flushQueuedProviderRegistrations(loader, modelRuntime, launch.onExtensionError, requiredPaths);
+                const queued = flushQueuedProviderRegistrations(loader, modelRuntime, launch.onExtensionError, isRequiredSource);
+                if (requiredPaths.size > 0) {
+                    const loadedIdentities = new Set(loader.getExtensions().extensions.map(({ resolvedPath }) => requiredExtensionIdentity(resolvedPath)));
+                    const missing = [...requiredPaths].filter((extensionPath) => !loadedIdentities.has(requiredExtensionIdentity(extensionPath)));
+                    if (missing.length)
+                        throw new Error(`Required child extension failed to load: ${missing.join(", ")}`);
+                }
                 if (launch.parentProviderRegistry)
                     inheritedProviders = inheritParentProviders(modelRuntime, launch.parentProviderRegistry, queued.claimedProviderIds, launch.onExtensionError);
                 if (queued.registered || inheritedProviders.size > 0) {
@@ -496,7 +539,7 @@ export function createDefaultChildSessionFactory(options = {}) {
                     await session.bindExtensions({
                         mode: "print",
                         onError: (error) => {
-                            if (binding && requiredPaths.has(error.extensionPath))
+                            if (binding && isRequiredSource(error.extensionPath))
                                 requiredStartupErrors.push(`${error.extensionPath} (${error.event}): ${error.error}`);
                             launch.onExtensionError?.({ extensionPath: error.extensionPath, event: error.event, error: error.error });
                         },

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

@@ -65,6 +65,13 @@ export interface PiLaunchToolPlan {
  * runtime snapshot therefore cannot work and fails the launch.
  */
 export declare function formatRuntimeSnapshotMcpServersError(agentName: string | undefined, serverNames: readonly string[]): string;
+/**
+ * A child's `tools` list is a complete allowlist. Read as names, Pi's modifier
+ * entries would become required tools no child has, or mix with the names the
+ * plan adds into a list Pi rejects. The modifier rule is Pi's `isToolModifier`:
+ * a `+name` or `-name` entry edits Pi's default tool selection.
+ */
+export declare function assertNoToolModifierEntries(agentName: string | undefined, tools: readonly string[]): void;
 export declare function projectLaunchResolvedChildExtensions(toolPlan: Pick<PiLaunchToolPlan, "runtimeExtensions" | "configuredExtensions" | "requiredExtensions" | "extensionArgs" | "disableAmbientExtensions">): LaunchResolvedChildExtensions;
 /**
  * Resolve the permission-system extension entry point when installed.

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

@@ -100,6 +100,23 @@ export function formatRuntimeSnapshotMcpServersError(agentName, serverNames) {
     const subject = agentName ? `Agent '${agentName}'` : "Subagent";
     return `${subject} selects MCP tools from servers that exist only in pi-mcp-adapter's runtime snapshot (${serverNames.join(", ")}). MCP servers from the runtime snapshot cannot be provided to in-process children; MCP tools must come from an ambient adapter extension in a background child (\`async: true\`), so add the server to the adapter's configuration file instead.`;
 }
+/** Path-like entries load extensions instead of naming tools, so Pi never reads them as modifiers. */
+function isToolExtensionPath(entry) {
+    return entry.includes("/") || entry.endsWith(".ts") || entry.endsWith(".js");
+}
+/**
+ * A child's `tools` list is a complete allowlist. Read as names, Pi's modifier
+ * entries would become required tools no child has, or mix with the names the
+ * plan adds into a list Pi rejects. The modifier rule is Pi's `isToolModifier`:
+ * a `+name` or `-name` entry edits Pi's default tool selection.
+ */
+export function assertNoToolModifierEntries(agentName, tools) {
+    const entries = tools.filter((entry) => /^[+-]/u.test(entry) && !isToolExtensionPath(entry));
+    if (entries.length === 0)
+        return;
+    const subject = agentName ? `Agent '${agentName}'` : "Subagent";
+    throw new Error(`${subject} lists Pi tool modifier ${entries.length === 1 ? "entry" : "entries"} in \`tools\`: ${entries.join(", ")}. A child's \`tools\` list is the complete set of tools it gets, so +name and -name entries are not supported; name every tool the child needs, or omit \`tools\` and use \`excludeTools\` to drop one.`);
+}
 export function projectLaunchResolvedChildExtensions(toolPlan) {
     const runtime = boundedExtensionIdentifiers(toolPlan.runtimeExtensions);
     const configured = boundedExtensionIdentifiers(toolPlan.configuredExtensions);
@@ -178,7 +195,8 @@ export function resolvePiLaunchToolPlan(input) {
     const allowedToolSet = capabilityCeiling?.allowedTools === undefined
         ? undefined
         : new Set(capabilityCeiling.allowedTools);
-    const requestedBuiltinTools = input.tools?.filter((tool) => !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js"))) ?? [];
+    const requestedBuiltinTools = input.tools?.filter((tool) => !isToolExtensionPath(tool)) ?? [];
+    assertNoToolModifierEntries(input.agentName, input.tools ?? []);
     if (input.requireReadTool && allowedToolSet && !allowedToolSet.has("read")) {
         throw new Error(`Capability ceiling from ${capabilityCeiling?.sources.join(", ") || "unknown source"} excludes required tool 'read' for lazy skill loading.`);
     }
@@ -204,8 +222,7 @@ export function resolvePiLaunchToolPlan(input) {
     }
     const toolExtensionPaths = capabilityCeiling?.denyExtensions
         ? []
-        : (input.tools ?? []).filter((tool) => !requestedBuiltinTools.includes(tool) &&
-            (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")));
+        : (input.tools ?? []).filter(isToolExtensionPath);
     const mcpResolution = capabilityCeiling?.denyExtensions
         ? { selections: [], unresolvedSelectors: [] }
         : input.builtinMcpTools
@@ -318,9 +335,7 @@ export function resolvePiLaunchToolPlan(input) {
             removedExtensionCount: capabilityCeiling.denyExtensions
                 ? (input.extensions?.length ?? 0) +
                     (input.subagentOnlyExtensions?.length ?? 0) +
-                    (input.tools ?? []).filter((tool) => tool.includes("/") ||
-                        tool.endsWith(".ts") ||
-                        tool.endsWith(".js")).length
+                    (input.tools ?? []).filter(isToolExtensionPath).length
                 : 0,
             requestedMcpToolCount: input.mcpDirectTools?.length ?? 0,
             effectiveMcpTools,

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

@@ -1,4 +1,5 @@
 import type { HerdrMachineReference } from "../../shared/types.ts";
+import type { PlacementCommandResult, PlacementMachineAccess } from "./placement-host.ts";
 export declare const HERDR_REMOTE_PATH = "$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
 export declare const HERDR_SSH_BASE: readonly ["-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="];
 export declare function hardenedSshEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
@@ -33,26 +34,28 @@ export interface HerdrForwardedConnection {
     }>;
     close(): Promise<void>;
 }
+type SshTarget = Pick<HerdrMachineReference, "target">;
 export declare function decodeHerdrJsonLine(line: Buffer): unknown;
 export declare function shellQuoteRemote(value: string): string;
 export declare function remoteShellCommand(script: string, args?: string[]): string;
-export declare function runHerdrRemoteCommand(machine: HerdrMachineReference, command: string, options?: {
+export declare function runHerdrRemoteCommand(machine: SshTarget, command: string, options?: {
     sshBin?: string;
     env?: NodeJS.ProcessEnv;
     timeout?: number;
     maxBuffer?: number;
 }): import("child_process").SpawnSyncReturns<string>;
-export declare function runHerdrRemoteCommandAsync(machine: HerdrMachineReference, command: string, options?: {
+export declare function runHerdrRemoteCommandAsync(machine: SshTarget, command: string, options?: {
     sshBin?: string;
     env?: NodeJS.ProcessEnv;
     timeout?: number;
     maxBuffer?: number;
-}): Promise<{
-    status: number | null;
-    stdout: string;
-    stderr: string;
-    error?: Error;
-}>;
+}): Promise<PlacementCommandResult>;
+/** Spawns one process with bounded output and a SIGTERM-then-SIGKILL timeout; never rejects. */
+export declare function runBoundedCommand(file: string, args: string[], options: {
+    env: NodeJS.ProcessEnv;
+    timeout?: number;
+    maxBuffer?: number;
+}): Promise<PlacementCommandResult>;
 export declare function parseHerdrEndpoint(value: string, expectedSession?: string): HerdrEndpoint;
 export declare function discoverHerdrEndpoint(machine: HerdrMachineReference, options?: {
     sshBin?: string;
@@ -64,7 +67,13 @@ export declare class SocketRpcClient implements 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>;
 }
+/** SSH machine access: hardened ssh commands and StreamLocal forwards that share one private local directory per socket scope. */
+export declare function sshMachineAccess(machine: SshTarget, options?: {
+    sshBin?: string;
+    env?: NodeJS.ProcessEnv;
+}): PlacementMachineAccess;
 export declare function connectHerdrMachine(machine: HerdrMachineReference, options?: {
     sshBin?: string;
     env?: NodeJS.ProcessEnv;
 }): Promise<HerdrForwardedConnection>;
+export {};

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

@@ -30,8 +30,12 @@ function canonicalHerdrSession(session) { return session && session !== "default
 function sshEnvCommand(session, command) { 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, command, options = {}) { 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, command, options = {}) {
+    return runBoundedCommand(options.sshBin ?? "ssh", [...herdrSshArgs(options.env), machine.target, command], { env: hardenedSshEnv(options.env), timeout: options.timeout, maxBuffer: options.maxBuffer });
+}
+/** Spawns one process with bounded output and a SIGTERM-then-SIGKILL timeout; never rejects. */
+export function runBoundedCommand(file, args, options) {
     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 child = spawn(file, args, { env: options.env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
         const stdout = [], stderr = [], maxBuffer = options.maxBuffer ?? MAX_DISCOVERY_BYTES;
         let stdoutBytes = 0, stderrBytes = 0, error, settled = false, escalation;
         const finish = (status, spawnError = error) => { if (settled)
@@ -226,10 +230,7 @@ async function terminateChild(child) { const wait = (ms) => child.exitCode !== n
     child.kill("SIGKILL");
     await wait(1_000);
 } }
-export async function connectHerdrMachine(machine, options = {}) {
-    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);
+function openSshSockets(machine, options) {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-herdr-"));
     fs.chmodSync(dir, 0o700);
     const children = new Set();
@@ -252,6 +253,17 @@ export async function connectHerdrMachine(machine, options = {}) {
         }
         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 }); } };
+    return { forwardRemoteSocket: forward, close: async () => { await Promise.all([...children].map(terminateChild)); children.clear(); fs.rmSync(dir, { recursive: true, force: true }); } };
+}
+/** SSH machine access: hardened ssh commands and StreamLocal forwards that share one private local directory per socket scope. */
+export function sshMachineAccess(machine, options = {}) {
+    return { shellCommand: remoteShellCommand, run: (command, limits = {}) => runHerdrRemoteCommand(machine, command, { ...options, ...limits }), runAsync: (command, limits = {}) => runHerdrRemoteCommandAsync(machine, command, { ...options, ...limits }), openSockets: () => openSshSockets(machine, options) };
+}
+export async function connectHerdrMachine(machine, options = {}) {
+    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 sockets = sshMachineAccess(machine, options).openSockets();
+    const primary = await sockets.forwardRemoteSocket(endpoint.socket, "herdr").catch(async (error) => { await sockets.close(); throw error; });
+    return { endpoint, socketPath: primary.socketPath, client: new SocketRpcClient(primary.socketPath), forwardRemoteSocket: sockets.forwardRemoteSocket, close: sockets.close };
 }

package/src/runs/shared/herdr-external-adapters.d.ts

@@ -1,6 +1,7 @@
 import type { HerdrMachineReference, HerdrRemoteGitStatus } from "../../shared/types.ts";
 import { connectHerdrMachine, type HerdrForwardedConnection } from "./herdr-connection.ts";
-import { HerdrPlacedRunOwner, type HerdrReconnectCandidate, type HerdrRunIdentity } from "./herdr-placed-run.ts";
+import { HerdrPlacedRunOwner, type HerdrReconnectCandidate } from "./herdr-pane-host.ts";
+import type { HerdrRunIdentity } from "./herdr-placed-run.ts";
 export type HerdrExternalAdapterId = "claude-code" | "claude-code-writer" | "cursor-agent" | "cursor-agent-writer" | "codex-exec" | "codex-exec-writer";
 export type HerdrExternalKind = "claude" | "cursor" | "codex";
 export interface HerdrExternalCapabilities {
@@ -62,7 +63,7 @@ export interface HerdrExternalAdapter {
 }
 export declare function reconcileHerdrExternalRun(identity: HerdrRunIdentity, candidate: HerdrReconnectCandidate): {
     ok: true;
-    state: import("./herdr-placed-run.ts").HerdrRunSnapshot["state"];
+    state: import("./placement-host.ts").PlacementRunState;
     paneId: string;
     cursor: number;
 } | {

package/src/runs/shared/herdr-external-adapters.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import { connectHerdrMachine, HerdrRpcError, HerdrTransportError, remoteShellCommand, shellQuoteRemote } from "./herdr-connection.js";
-import { HerdrPlacedRunOwner, herdrStatusSubscriptions, ownsHerdrPane, parseHerdrAgent, reconcileHerdrPlacedRun } from "./herdr-placed-run.js";
+import { HerdrPlacedRunOwner, herdrStatusSubscriptions, ownsHerdrPane, parseHerdrAgent, reconcileHerdrPlacedRun } from "./herdr-pane-host.js";
 const CAPABILITIES = { stop: true, steer: false, resume: false, supervisor: "unsupported" };
 const MAX_EVIDENCE_BYTES = 4 * 1024 * 1024, MAX_OUTPUT_BYTES = 1024 * 1024, MAX_PREFLIGHT_BYTES = 64 * 1024, MAX_GIT_BYTES = 2048;
 const CODEX_OUTPUT_BYTES = 64 * 1024, EXTERNAL_STARTUP_TIMEOUT_MS = 45_000, EXTERNAL_STARTUP_BACKOFF_AFTER_MS = 15_000, EXTERNAL_STARTUP_SLOW_POLL_MS = 2_500, CODEX_STARTUP_GRACE_MS = 15_000, CODEX_QUIET_MS = 8_000, CODEX_POLL_MS = 1_000, CODEX_DEFAULT_TIMEOUT_MS = 30 * 60_000;

package/src/runs/shared/herdr-machine.d.ts

@@ -1,4 +1,4 @@
-import type { ExternalProcessStatus, HerdrMachineReference } from "../../shared/types.ts";
+import type { ExternalProcessStatus, HerdrMachineReference, PlacementMachineReference } from "../../shared/types.ts";
 import type { runExternalCli } from "./external-cli-runner.ts";
 export { shellQuoteRemote as shellQuote } from "./herdr-connection.ts";
 /** The local ssh process gets only what ssh itself needs; remote runs use the machine's own credentials. */
@@ -7,6 +7,10 @@ type RunExternalCliInput = Parameters<typeof runExternalCli>[0];
 interface MachineSettingsEntry {
     cwd?: string;
     env?: Record<string, string>;
+    /** User settings only: run this machine's children in Rex panes reached over SSH at `ssh`. */
+    rex?: {
+        ssh: string;
+    };
 }
 export interface ResolveHerdrMachinePlacementInput {
     /** Profile id or label as typed by the operator. */
@@ -22,8 +26,12 @@ export interface ResolveHerdrMachinePlacementInput {
     settings?: MachineSettingsEntry;
     herdrBin?: string;
 }
-export interface HerdrMachinePlacement {
+export interface HerdrMachinePlacement extends MachinePlacement {
     machine: HerdrMachineReference;
+}
+/** A resolved `machine` value: a Herdr saved machine, or the reserved `local` (a Rex pane on this machine). */
+export interface MachinePlacement {
+    machine: PlacementMachineReference;
     /** Opt-in `subagents.machines.<name>.env`, exported in front of the remote command. */
     env?: Record<string, string>;
 }
@@ -32,6 +40,8 @@ export interface PreparedHerdrMachineExternalCliRun {
     decorateProcess(process: ExternalProcessStatus): ExternalProcessStatus;
 }
 export declare function resolveHerdrMachinePlacement(input: ResolveHerdrMachinePlacementInput): HerdrMachinePlacement;
+/** `local` resolves to a Rex pane on this machine; a name with a `rex` entry in user settings to a Rex pane on that SSH host; any other value to a Herdr saved machine. */
+export declare function resolveMachinePlacement(input: ResolveHerdrMachinePlacementInput): MachinePlacement;
 export declare function formatHerdrMachineRunnerUnsupported(input: {
     machine?: string;
     agentName: string;

package/src/runs/shared/herdr-machine.js

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, getProjectConfigDir } from "../../shared/utils.js";
 import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS } from "./external-cli-contract.js";
+import { REX_LOCAL_MACHINE, resolveRexLocalPlacement } from "./rex-machine.js";
 export { shellQuoteRemote as shellQuote } from "./herdr-connection.js";
 /**
  * Herdr saved-machine placement for external CLI children.
@@ -149,18 +150,31 @@ function machineSettingsFrom(settings, keys, filePath) {
             throw new Error(`Subagent settings in '${filePath}' set 'machines.${key}.env'. Saved-machine runs use the remote Herdr/Pi environment; configure credentials and environment on '${key}' and remove the local env map.`);
         }
     }
+    if (record.rex !== undefined) {
+        const rex = record.rex, ssh = rex && typeof rex === "object" && !Array.isArray(rex) && Object.keys(rex).every((field) => field === "ssh") ? rex.ssh : undefined;
+        if (typeof ssh !== "string")
+            throw new Error(`Subagent settings in '${filePath}' have invalid 'machines.${key}.rex'; expected { "ssh": "<ssh target>" }.`);
+        entry.rex = { ssh: validateTarget(ssh, key) };
+    }
     return entry;
 }
-/** Project settings beat user settings, field by field; the entry may be keyed by label, id, or the typed selector. */
+/** Project settings beat user settings, field by field; the entry may be keyed by label, id, or the typed selector. Only user settings may name a Rex SSH host, so a cloned repo never chooses where a task runs. */
 function readMachineSettings(cwd, keys) {
     const userPath = path.join(getAgentDir(), "settings.json");
     const projectPath = path.join(getProjectConfigDir(findProjectRootForSettings(cwd)), "settings.json");
     const user = machineSettingsFrom(readJsonObject(userPath), keys, userPath);
     const project = projectPath === userPath ? undefined : machineSettingsFrom(readJsonObject(projectPath), keys, projectPath);
+    if (project?.rex)
+        throw new Error(`Project settings '${projectPath}' set a Rex SSH host in 'machines'. Move the rex entry to your user settings '${userPath}'; only user settings choose which host a task runs on.`);
     if (!user && !project)
         return undefined;
     return { ...user, ...project };
 }
+/** Whether user settings name `machine` as a Rex SSH host. */
+function userRexMachine(machine) {
+    const userPath = path.join(getAgentDir(), "settings.json");
+    return machineSettingsFrom(readJsonObject(userPath), [machine], userPath)?.rex !== undefined;
+}
 function findProjectRootForSettings(cwd) {
     let current = path.resolve(cwd);
     while (true) {
@@ -172,6 +186,15 @@ function findProjectRootForSettings(cwd) {
         current = parent;
     }
 }
+/** The child's cwd on a remote machine: an absolute launch cwd, or the launch cwd under the machine's configured root. */
+function remoteMachineCwd(stepCwd, root, name) {
+    const step = stepCwd?.trim();
+    if (step && isRemoteAbsolute(step))
+        return step;
+    if (!root)
+        throw new Error(`No root for ${name} in this repo. Set subagents.machines.${name}.cwd in .pi/settings.json or pass an absolute cwd on that machine.`);
+    return step ? path.posix.join(root, step) : root;
+}
 export function resolveHerdrMachinePlacement(input) {
     const requested = validateMachineName(input.machine);
     const catalog = input.catalogJson !== undefined
@@ -184,14 +207,7 @@ export function resolveHerdrMachinePlacement(input) {
     if (settings?.env && Object.keys(settings.env).length > 0) {
         throw new Error(`Saved-machine environment for '${name}' must be configured remotely. Remove machines.${name}.env and configure the remote Herdr/Pi session instead.`);
     }
-    const stepCwd = input.stepCwd?.trim();
-    let cwd;
-    if (stepCwd && isRemoteAbsolute(stepCwd))
-        cwd = stepCwd;
-    else if (settings?.cwd)
-        cwd = stepCwd ? path.posix.join(settings.cwd, stepCwd) : settings.cwd;
-    else
-        throw new Error(`No root for ${name} in this repo. Set subagents.machines.${name}.cwd in .pi/settings.json or pass an absolute cwd on that machine.`);
+    const cwd = remoteMachineCwd(input.stepCwd, settings?.cwd, name);
     return {
         machine: {
             provider: "herdr",
@@ -204,9 +220,39 @@ export function resolveHerdrMachinePlacement(input) {
         ...(settings?.env ? { env: settings.env } : {}),
     };
 }
+/** `local` resolves to a Rex pane on this machine; a name with a `rex` entry in user settings to a Rex pane on that SSH host; any other value to a Herdr saved machine. */
+export function resolveMachinePlacement(input) {
+    const requested = validateMachineName(input.machine);
+    const settings = input.settings ?? readMachineSettings(input.cwd, [requested]);
+    if (requested === REX_LOCAL_MACHINE) {
+        if (settings?.rex)
+            throw new Error("Machine 'local' is reserved for a Rex pane on this machine; give the Rex SSH host in subagents.machines.local.rex another name.");
+        return { machine: resolveRexLocalPlacement({ cwd: input.cwd, stepCwd: input.stepCwd, env: input.env }) };
+    }
+    if (settings?.rex)
+        return { machine: { provider: "rex", id: requested, target: settings.rex.ssh, cwd: validateRemoteCwd(remoteMachineCwd(input.stepCwd, settings.cwd, requested), requested) } };
+    return resolveHerdrMachinePlacement(input);
+}
 export function formatHerdrMachineRunnerUnsupported(input) {
     if (input.machine === undefined)
         return undefined;
+    const name = input.machine.trim();
+    let rex;
+    try {
+        rex = name === REX_LOCAL_MACHINE || userRexMachine(name);
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+    if (rex) {
+        if (input.runnerType !== undefined && input.runnerType !== "pi")
+            return `Agent '${input.agentName}' requested machine '${name}', but Rex supports native Pi children only. Remove the machine or use a native Pi agent.`;
+        if (input.worktree === true)
+            return `Agent '${input.agentName}' requested machine '${name}', but managed worktrees cannot be combined with machine placement.`;
+        if (process.platform === "win32")
+            return `Machine '${name}' runs the child in a Rex pane, which is not supported on Windows.`;
+        return undefined;
+    }
     if (input.runnerType !== undefined && input.runnerType !== "pi" && input.runnerType !== "external-cli") {
         return `Agent '${input.agentName}' requested machine '${input.machine}', but this runner cannot use pane-native Herdr placement. Use native Pi or a built-in Claude, Codex, or Cursor profile.`;
     }

package/src/runs/shared/herdr-pane-host.d.ts

@@ -0,0 +1,88 @@
+import type { HerdrMachineReference, PlacementMachineReference } from "../../shared/types.ts";
+import { type HerdrForwardedConnection, type HerdrRpcClient } from "./herdr-connection.ts";
+import type { HerdrRunIdentity } from "./herdr-placed-run.ts";
+import { PlacedRunOwner, type PlacedBridgeManifest } from "./placed-run-owner.ts";
+import { type PlacementAgentKind, type PlacementBridgeIdentity, type PlacementEvidenceProof, type PlacementOwnedPane, type PlacementReconnectCheck, type PlacementRunState, type PlacementStartOptions } from "./placement-host.ts";
+export interface HerdrPaneCandidate {
+    endpoint: {
+        session: string | null;
+        protocol: number;
+        version: string;
+    };
+    agents: Array<{
+        terminal_id?: string;
+        pane_id?: string;
+        agent_status?: string;
+    }>;
+}
+export interface HerdrReconnectCandidate extends HerdrPaneCandidate {
+    bridge: PlacementBridgeIdentity;
+}
+export declare function herdrStatusSubscriptions(paneId: string): unknown[];
+export declare function reconcileHerdrPlacedRun(identity: HerdrRunIdentity, candidate: HerdrPaneCandidate, proveEvidence: () => PlacementEvidenceProof): PlacementReconnectCheck;
+export declare function parseHerdrCreated(value: unknown, type: "workspace_created" | "tab_created"): {
+    workspaceId?: string;
+    tabId: string;
+    paneId: string;
+};
+export declare function parseHerdrAgent(value: unknown, type: "agent_started" | "agent_info" | "agent_prompted"): Record<string, unknown>;
+export declare function parseHerdrSessionSnapshot(value: unknown): Record<string, unknown>;
+export declare function ownsHerdrPane(agent: Record<string, unknown>, terminalId: string, paneId: string): boolean;
+export declare const HERDR_MAX_OWNED_PANES = 20;
+export declare function provisionHerdrPane(client: HerdrRpcClient, cwd: string, runId: string, runtimeDir: string, environment?: Record<string, string>, allocationKey?: string): Promise<{
+    workspaceId: string;
+    tabId: string;
+    paneId: string;
+}>;
+declare function closeOwnedHerdrPane(connection: HerdrForwardedConnection, owned: PlacementOwnedPane, terminalId: string | undefined, agentName: string | undefined): Promise<void>;
+/** Herdr pane host: Herdr RPC over the SSH-forwarded Herdr socket. Ownership is the Herdr terminal_id/pane_id pair; run state comes from agent_status. */
+export declare const herdrPaneHost: {
+    connect(machine: PlacementMachineReference): Promise<HerdrForwardedConnection>;
+    sessionOf(connection: HerdrForwardedConnection): string | null;
+    launch(connection: HerdrForwardedConnection, machine: PlacementMachineReference, runId: string, runtimeDir: string, request: import("./placement-host.ts").PlacementLaunchRequest, onPane: (owned: PlacementOwnedPane) => Promise<void>, options: PlacementStartOptions | undefined): Promise<{
+        owned: PlacementOwnedPane;
+        terminalId: string;
+    }>;
+    prompt(connection: HerdrForwardedConnection, identity: HerdrRunIdentity, text: string): Promise<void>;
+    subscribe(connection: HerdrForwardedConnection, paneId: string, listener: (event: unknown) => void, onDisconnect: (error: Error) => void): Promise<() => void>;
+    paneEvent(event: unknown, fallback: PlacementRunState): {
+        terminalId: unknown;
+        paneId: unknown;
+        state: PlacementRunState;
+    } | undefined;
+    panes(connection: HerdrForwardedConnection): Promise<{
+        endpoint: import("./herdr-connection.ts").HerdrEndpoint;
+        agents: {
+            terminal_id?: string;
+            pane_id?: string;
+            agent_status?: string;
+        }[];
+    }>;
+    reconcile: typeof reconcileHerdrPlacedRun;
+    closeOwnedPane: typeof closeOwnedHerdrPane;
+};
+/** SSH entry points for the host-neutral runtime-dir and manifest helpers. */
+export declare function discoverBridgeManifest(machine: HerdrMachineReference, runId: string, runtimeDir: string, options?: {
+    sshBin?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<PlacedBridgeManifest>;
+export declare function createRemoteRuntimeDir(machine: HerdrMachineReference, runId: string, options?: {
+    sshBin?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<string>;
+export declare function removeRemoteRuntimeDir(machine: HerdrMachineReference, runtimeDir: string, options?: {
+    sshBin?: string;
+    env?: NodeJS.ProcessEnv;
+}): void;
+/** The placed-run owner bound to Herdr and SSH access, plus the separate provision and start steps the external CLI adapters use. */
+export declare class HerdrPlacedRunOwner extends PlacedRunOwner<HerdrForwardedConnection, HerdrMachineReference> {
+    private constructor();
+    static create(machine: HerdrMachineReference, runId: string, beforePane?: (owner: HerdrPlacedRunOwner) => void | Promise<void>): Promise<HerdrPlacedRunOwner>;
+    provision(environment?: Record<string, string>): Promise<PlacementOwnedPane>;
+    start(kind: PlacementAgentKind, name: string, args: string[], options?: PlacementStartOptions): Promise<{
+        terminalId: string;
+        paneId: string;
+        argv: string[];
+    }>;
+}
+export {};