pi-subagents 0.81.0 → 0.82.1

package/src/runs/shared/orca-progress-tabs.d.ts

@@ -19,7 +19,6 @@ export interface OrcaProgressTab {
     finish(status: "completed" | "failed" | "stopped", sessionFile?: string): Promise<void>;
 }
 export declare function resolveOrcaCommand(env?: NodeJS.ProcessEnv): string | undefined;
-export declare function resolvePiSessionId(sessionFile: string | undefined): string | undefined;
 export declare function createOrcaProgressTab(input: {
     cwd: string;
     runId: string;

package/src/runs/shared/orca-progress-tabs.js

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { resolveNodeExecutable } from "../../shared/node-executable.js";
 import { getProjectSubagentsDir } from "../../shared/artifacts.js";
+import { resolvePiSessionId } from "../../shared/session-identity.js";
 import { TEMP_ROOT_DIR } from "../../shared/types.js";
 import { extractTextFromContent, extractToolArgsPreview, getAgentDir } from "../../shared/utils.js";
 const ORCA_CREATE_TIMEOUT_MS = 20_000;
@@ -257,30 +258,6 @@ function reserveTabSequence(root, cwd) {
         }
     });
 }
-export function resolvePiSessionId(sessionFile) {
-    if (!sessionFile)
-        return undefined;
-    try {
-        const fd = fs.openSync(sessionFile, "r");
-        try {
-            const buffer = Buffer.alloc(16 * 1024);
-            const bytes = fs.readSync(fd, buffer, 0, buffer.length, 0);
-            const line = buffer.toString("utf-8", 0, bytes).split("\n", 1)[0];
-            if (!line)
-                return undefined;
-            const header = JSON.parse(line);
-            if (header.type === "session" && typeof header.id === "string" && /^[A-Za-z0-9-]{8,}$/.test(header.id))
-                return header.id;
-            return undefined;
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-    }
-    catch {
-        return undefined;
-    }
-}
 function scheduleCleanup(nodeExecutable, paths) {
     try {
         const watchdog = spawn(nodeExecutable, ["-e", ORCA_CLEANUP_WATCHDOG_SCRIPT, String(CLEANUP_DELAY_MS), ...paths], {

package/src/runs/shared/parallel-utils.d.ts

@@ -12,7 +12,7 @@ export interface RunnerSubagentStep {
     task: string;
     runner?: ResolvedRunnerConfig;
     /** Herdr saved machine this external-cli step runs on; `cwd` is then the directory on that machine. */
-    machine?: import("../../shared/types.ts").HerdrMachineReference;
+    machine?: import("../../shared/types.ts").PlacementMachineReference;
     remoteReads?: string[] | false;
     machineEnv?: Record<string, string>;
     externalJobFollowUp?: {

package/src/runs/shared/placed-run-owner.d.ts

@@ -0,0 +1,49 @@
+import type { PlacementMachineReference } from "../../shared/types.ts";
+import type { HerdrRunIdentity, HerdrRunSnapshot } from "./herdr-placed-run.ts";
+import type { PlacementCommandOptions, PlacementLaunchRequest, PlacementMachineAccess, PlacementOwnedPane, PlacementPaneHost, PlacementSockets, PlacementStartOptions } from "./placement-host.ts";
+export interface PlacedBridgeManifest {
+    socketPath: string;
+    nativeSessionId: string;
+    packageVersion: string;
+    protocol: number;
+}
+/** Prints `$1/manifest.json` when it is a regular file, never through a symlink. */
+export declare const PLACED_MANIFEST_READ_SCRIPT = "p=\"$1/manifest.json\"; test -f \"$p\" && test ! -L \"$p\" && cat \"$p\"";
+export declare function discoverPlacedBridgeManifest(access: PlacementMachineAccess, runId: string, runtimeDir: string, missing?: string): Promise<PlacedBridgeManifest>;
+export declare function createPlacedRuntimeDir(access: PlacementMachineAccess, runId: string): Promise<string>;
+export declare function removePlacedRuntimeDir(access: PlacementMachineAccess, runtimeDir: string): void;
+/** The single private owner for allocation shared by every pane-native backend projection. */
+export declare class PlacedRunOwner<C extends PlacementSockets, M extends PlacementMachineReference = PlacementMachineReference> {
+    #private;
+    readonly machine: M;
+    readonly runId: string;
+    readonly runtimeDir: string;
+    connection: C;
+    readonly host: PlacementPaneHost<C>;
+    readonly access: PlacementMachineAccess;
+    owned?: PlacementOwnedPane;
+    terminalId?: string;
+    agentName?: string;
+    startedArgv?: string[];
+    identity?: HerdrRunIdentity;
+    protected constructor(machine: M, runId: string, runtimeDir: string, connection: C, host: PlacementPaneHost<C>, access: PlacementMachineAccess, removeRuntime?: () => void);
+    observeEvent(event: unknown): void;
+    markConnectionUnknown(observed: C): boolean;
+    subscribe(listener: (event: unknown) => void, disconnected: (error: Error) => void): Promise<void>;
+    /** Create the owned pane and start the agent in one host step; onPane runs once the pane exists and before the agent starts. */
+    launch(request: PlacementLaunchRequest, onPane: (owned: PlacementOwnedPane) => Promise<void>, options?: PlacementStartOptions): Promise<{
+        owned: PlacementOwnedPane;
+        terminalId: string;
+        argv: string[];
+    }>;
+    journal(identity: HerdrRunIdentity): void;
+    get snapshot(): HerdrRunSnapshot;
+    runRemote(command: string, options?: PlacementCommandOptions): import("./placement-host.ts").PlacementCommandResult;
+    replaceConnection(input: {
+        connection: C;
+        unsubscribe: () => void;
+        paneId: string;
+        state: HerdrRunSnapshot["state"];
+    }): Promise<void>;
+    cleanup(closeStartedPane?: boolean): Promise<void>;
+}

package/src/runs/shared/placed-run-owner.js

@@ -0,0 +1,93 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "../../shared/utils.js";
+/** Prints `$1/manifest.json` when it is a regular file, never through a symlink. */
+export const PLACED_MANIFEST_READ_SCRIPT = 'p="$1/manifest.json"; test -f "$p" && test ! -L "$p" && cat "$p"';
+export async function discoverPlacedBridgeManifest(access, runId, runtimeDir, missing = "The placed Pi's pi-subagents bridge manifest is not in its runtime directory; the Pi may have exited.") {
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const result = await access.runAsync(access.shellCommand(PLACED_MANIFEST_READ_SCRIPT, [runtimeDir]), { 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;
+            try {
+                value = JSON.parse(result.stdout);
+            }
+            catch {
+                throw new Error("Remote bridge manifest is malformed.");
+            }
+            const p = value;
+            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 { socketPath: p.socketPath, nativeSessionId: p.nativeSessionId, packageVersion: p.packageVersion, protocol: p.protocol };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    throw new Error(missing);
+}
+export async function createPlacedRuntimeDir(access, runId) { const result = await access.runAsync(access.shellCommand("umask 077; mktemp -d \"${TMPDIR:-/tmp}/pi-subagents-herdr-$1-XXXXXXXX\"", [runId]), { 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 removePlacedRuntimeDir(access, runtimeDir) { const result = access.run(access.shellCommand("p=$1; case \"${p##*/}\" in pi-subagents-herdr-*) test -d \"$p\" && test ! -L \"$p\" && rm -rf -- \"$p\";; *) exit 64;; esac", [runtimeDir]), { 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 PlacedRunOwner {
+    machine;
+    runId;
+    runtimeDir;
+    connection;
+    host;
+    access;
+    owned;
+    terminalId;
+    agentName;
+    startedArgv;
+    identity;
+    #unsubscribe = () => { };
+    #snapshot = { connection: "connected", state: "ready", revision: 0 };
+    #cleanupPromise;
+    #removeRuntime;
+    constructor(machine, runId, runtimeDir, connection, host, access, removeRuntime = () => removePlacedRuntimeDir(access, runtimeDir)) { this.machine = machine; this.runId = runId; this.runtimeDir = runtimeDir; this.connection = connection; this.#removeRuntime = removeRuntime; this.host = host; this.access = access; }
+    observeEvent(event) { const data = this.host.paneEvent(event, this.#snapshot.state); if (data && (!this.terminalId || data.terminalId === this.terminalId || data.paneId === this.owned?.paneId))
+        this.#snapshot = { ...this.#snapshot, revision: this.#snapshot.revision + 1, state: data.state }; }
+    markConnectionUnknown(observed) { if (this.connection !== observed)
+        return false; this.#snapshot = { ...this.#snapshot, connection: "unknown", state: "unknown", revision: this.#snapshot.revision + 1 }; return true; }
+    async subscribe(listener, disconnected) { const observed = this.connection, paneId = this.owned?.paneId; let adopted = false, candidateLost; if (!paneId)
+        throw new Error("Herdr status subscription requires a provisioned pane."); const unsubscribe = await this.host.subscribe(observed, paneId, (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; }
+    /** Create the owned pane and start the agent in one host step; onPane runs once the pane exists and before the agent starts. */
+    async launch(request, onPane, options = {}) {
+        const { owned, terminalId } = await this.host.launch(this.connection, this.machine, this.runId, this.runtimeDir, request, async (pane) => { this.owned = pane; await onPane(pane); }, options), argv = [request.kind, ...request.args];
+        this.agentName = request.name;
+        this.terminalId = terminalId;
+        this.startedArgv = argv;
+        return { owned, terminalId, argv };
+    }
+    journal(identity) { 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() { return this.#snapshot; }
+    runRemote(command, options = {}) { return this.access.run(command, options); }
+    async replaceConnection(input) { 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) { return this.#cleanupPromise ??= this.#performCleanup(closeStartedPane); }
+    async #performCleanup(closeStartedPane) { let failure; try {
+        if (closeStartedPane && this.owned)
+            await this.host.closeOwnedPane(this.connection, this.owned, this.terminalId, this.agentName);
+    }
+    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; }
+}

package/src/runs/shared/placement-host.d.ts

@@ -0,0 +1,99 @@
+import type { PlacementMachineReference } from "../../shared/types.ts";
+import type { HerdrRunIdentity } from "./herdr-placed-run.ts";
+export type PlacementRunState = "ready" | "working" | "blocked" | "settled" | "unknown";
+export type PlacementAgentKind = "pi" | "claude" | "cursor" | "codex";
+export interface PlacementOwnedPane {
+    workspaceId: string;
+    tabId: string;
+    paneId: string;
+}
+export interface PlacementBridgeIdentity {
+    runId?: string;
+    nativeSessionId?: string;
+    packageVersion?: string;
+    protocol?: number;
+    evidenceCursor?: number;
+    evidenceFloor?: number;
+}
+export type PlacementEvidenceProof = {
+    ok: true;
+    cursor: number;
+} | {
+    ok: false;
+    reason: string;
+};
+export type PlacementReconnectCheck = {
+    ok: true;
+    state: PlacementRunState;
+    paneId: string;
+    cursor: number;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface PlacementStartOptions {
+    timeoutMs?: number;
+    pollMs?: number;
+    clock?: {
+        now(): number;
+        wait(ms: number): Promise<void>;
+    };
+}
+/** What to start in a new pane; the pane is created in the machine's cwd with this environment. */
+export interface PlacementLaunchRequest {
+    kind: PlacementAgentKind;
+    name: string;
+    args: string[];
+    environment?: Record<string, string>;
+}
+export interface PlacementCommandOptions {
+    timeout?: number;
+    maxBuffer?: number;
+}
+export interface PlacementCommandResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+export interface PlacementSocketForward {
+    socketPath: string;
+    close(): Promise<void>;
+}
+/** Unix sockets on the pane machine made reachable from the parent; close() ends every forward opened through it. */
+export interface PlacementSockets {
+    forwardRemoteSocket(remotePath: string, name: string): Promise<PlacementSocketForward>;
+    close(): Promise<void>;
+}
+/** Runs commands on, and reaches unix sockets on, the machine that hosts the pane: over SSH (`sshMachineAccess`) or directly (`localMachineAccess`). */
+export interface PlacementMachineAccess {
+    shellCommand(script: string, args?: string[]): string;
+    run(command: string, options?: PlacementCommandOptions): PlacementCommandResult;
+    runAsync(command: string, options?: PlacementCommandOptions): Promise<PlacementCommandResult>;
+    openSockets(): PlacementSockets;
+}
+/** Every pane operation a placed native run and its owner need. The connection carries the host's socket forwarding; P is the host's reconnect view of its panes. */
+export interface PlacementPaneHost<C extends PlacementSockets = PlacementSockets, P extends object = object> {
+    connect(machine: PlacementMachineReference): Promise<C>;
+    sessionOf(connection: C): string | null;
+    /** Create the pane and start the agent in it; call onPane after the pane exists and before the agent starts. */
+    launch(connection: C, machine: PlacementMachineReference, runId: string, runtimeDir: string, request: PlacementLaunchRequest, onPane: (owned: PlacementOwnedPane) => Promise<void>, options?: PlacementStartOptions): Promise<{
+        owned: PlacementOwnedPane;
+        terminalId: string;
+    }>;
+    prompt(connection: C, identity: HerdrRunIdentity, text: string): Promise<void>;
+    subscribe(connection: C, 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: C, identity: HerdrRunIdentity): Promise<P>;
+    reconcile(identity: HerdrRunIdentity, panes: P, proveEvidence: () => PlacementEvidenceProof): PlacementReconnectCheck;
+    closeOwnedPane(connection: C, owned: PlacementOwnedPane, terminalId: string | undefined, agentName: string | undefined): Promise<void>;
+}
+export declare function herdrPaneAllocationKey(target: string, session: string | null, cwd: string): string;
+export declare function withHerdrPaneAllocationLock<T>(key: string, action: () => Promise<T>, options?: {
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<T>;

package/src/runs/shared/placement-host.js

@@ -0,0 +1,157 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "../../shared/utils.js";
+const HERDR_ALLOCATION_LOCK_TIMEOUT_MS = 10_000, HERDR_ALLOCATION_LOCK_POLL_MS = 25;
+export function herdrPaneAllocationKey(target, session, cwd) { return JSON.stringify([target, session, cwd]); }
+function assertPrivateDir(directory) { 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, name) { const directory = path.join(parent, name); try {
+    fs.mkdirSync(directory, { mode: 0o700 });
+}
+catch (error) {
+    if (error.code !== "EEXIST")
+        throw error;
+} assertPrivateDir(directory); return directory; }
+function allocationLockRoot() { 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) { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (error) {
+    return error.code === "EPERM";
+} }
+function readAllocationOwner(ownerPath) { 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"));
+    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, right) { return left.token === right.token && left.dev === right.dev && left.ino === right.ino; }
+export async function withHerdrPaneAllocationLock(key, action, options = {}) {
+    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;
+    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.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.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.code !== "EEXIST" && publishError.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.code !== "EEXIST" && error.code !== "ENOENT")
+                            throw error;
+                    }
+                    finally {
+                        if (claimed)
+                            fs.unlinkSync(recoveryPath);
+                    }
+                    if (claimed)
+                        continue;
+                }
+            }
+            catch (error) {
+                if (error.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, actionError, releaseError, 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;
+    }
+    finally {
+        try {
+            fs.unlinkSync(tempPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { PlacementMachineReference, RexLocalMachineReference } from "../../shared/types.ts";
+/** `machine: "local"` is reserved: this machine, in a Rex pane of the parent's own Rex session. It never consults the Herdr catalog. */
+export declare const REX_LOCAL_MACHINE = "local";
+/** Rex CLI exit codes: 3 means the target is gone, 4 means the server is unreachable (state unknown, never "gone"). */
+export declare const REX_EXIT_GONE = 3, REX_EXIT_UNREACHABLE = 4;
+/** A `local` child edits this machine's disk; every other placed child edits the remote one. */
+export declare function isRexLocalMachine(machine: PlacementMachineReference | undefined): machine is RexLocalMachineReference;
+/** The Rex server bundle's CLI, relative to the home directory. */
+export declare const REX_BUNDLE_BIN = "Library/Application Support/com.superlogical.rex/RexServer/Versions/Current/Rex Server.app/Contents/MacOS/rex";
+export declare const REX_CALL_TIMEOUT_MS = 15000, REX_MAX_OUTPUT: number;
+/** Global rex flags: never start a server, and use the recorded one when there is one. */
+export declare function rexGlobalArgs(server: string | undefined): string[];
+/** `$REX_BIN_DIR/rex`, then `rex` on PATH, then the Rex server bundle. */
+export declare function resolveRexBinary(env?: NodeJS.ProcessEnv): string;
+/** Every Rex selector comes from the recorded machine reference, never from the calling process's own Rex pane variables. */
+export declare function rexCommandEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Resolves `machine: "local"` in the parent: records its Rex session (confirmed by the server) and server address, and the real
+ * launch directory. `stepCwd` is absolute, `~`, or relative to the parent's launch directory `cwd`.
+ */
+export declare function resolveRexLocalPlacement(input: {
+    cwd: string;
+    stepCwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): RexLocalMachineReference;

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

@@ -0,0 +1,83 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** `machine: "local"` is reserved: this machine, in a Rex pane of the parent's own Rex session. It never consults the Herdr catalog. */
+export const REX_LOCAL_MACHINE = "local";
+/** Rex CLI exit codes: 3 means the target is gone, 4 means the server is unreachable (state unknown, never "gone"). */
+export const REX_EXIT_GONE = 3, REX_EXIT_UNREACHABLE = 4;
+/** A `local` child edits this machine's disk; every other placed child edits the remote one. */
+export function isRexLocalMachine(machine) { return machine?.provider === "rex" && !("target" in machine); }
+/** The Rex server bundle's CLI, relative to the home directory. */
+export const REX_BUNDLE_BIN = "Library/Application Support/com.superlogical.rex/RexServer/Versions/Current/Rex Server.app/Contents/MacOS/rex";
+export const REX_CALL_TIMEOUT_MS = 15_000, REX_MAX_OUTPUT = 1024 * 1024;
+/** Global rex flags: never start a server, and use the recorded one when there is one. */
+export function rexGlobalArgs(server) { return server ? ["--autostart=false", "-S", server] : ["--autostart=false"]; }
+function executable(file) { try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+}
+catch {
+    return false;
+} }
+/** `$REX_BIN_DIR/rex`, then `rex` on PATH, then the Rex server bundle. */
+export function resolveRexBinary(env = process.env) {
+    const fromDir = env.REX_BIN_DIR ? [path.join(env.REX_BIN_DIR, "rex")] : [];
+    const fromPath = (env.PATH ?? "").split(path.delimiter).filter((dir) => path.isAbsolute(dir)).map((dir) => path.join(dir, "rex"));
+    const found = [...fromDir, ...fromPath, path.join(os.homedir(), REX_BUNDLE_BIN)].find(executable);
+    if (!found)
+        throw new Error("The Rex CLI was not found: set REX_BIN_DIR, put rex on PATH, or install Rex.");
+    return found;
+}
+/** Every Rex selector comes from the recorded machine reference, never from the calling process's own Rex pane variables. */
+export function rexCommandEnv(source = process.env) {
+    const { REX_SESSION: _session, REX_BLOCK: _block, REX_SERVER: _server, ...env } = source;
+    return env;
+}
+function sessionConfirmed(stdout, session) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return parsed?.session_id === session;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves `machine: "local"` in the parent: records its Rex session (confirmed by the server) and server address, and the real
+ * launch directory. `stepCwd` is absolute, `~`, or relative to the parent's launch directory `cwd`.
+ */
+export function resolveRexLocalPlacement(input) {
+    if (process.platform === "win32")
+        throw new Error("Machine 'local' runs the child in a Rex pane, which is not supported on Windows.");
+    const env = input.env ?? process.env, session = env.REX_SESSION?.trim(), server = env.REX_SERVER?.trim();
+    if (!session)
+        throw new Error("Machine 'local' opens the child in a new tab of this Rex session, but this Pi is not running inside Rex (REX_SESSION is not set).");
+    const result = spawnSync(resolveRexBinary(env), [...rexGlobalArgs(server), "session", "inspect", session, "--json"], { encoding: "utf8", env: rexCommandEnv(env), timeout: REX_CALL_TIMEOUT_MS, maxBuffer: REX_MAX_OUTPUT, windowsHide: true });
+    if (result.error)
+        throw new Error(`Could not ask Rex about this session: ${result.error.message}`, { cause: result.error });
+    if (result.status === REX_EXIT_GONE)
+        throw new Error(`Machine 'local' needs this Pi's Rex session, but the Rex server does not know session ${session}.`);
+    if (result.status === REX_EXIT_UNREACHABLE)
+        throw new Error("Machine 'local' needs the Rex server, but it is unreachable.");
+    if (result.status !== 0)
+        throw new Error(`rex session inspect exited with code ${result.status}: ${(result.stderr || result.stdout).trim().slice(0, 512)}`);
+    if (!sessionConfirmed(result.stdout, session))
+        throw new Error(`The Rex server did not confirm session ${session}.`);
+    const stepCwd = input.stepCwd?.trim();
+    const home = stepCwd === "~" || stepCwd?.startsWith("~/") ? path.join(os.homedir(), stepCwd.slice(1)) : undefined;
+    const requested = home ?? (stepCwd ? path.resolve(input.cwd, stepCwd) : input.cwd);
+    let cwd;
+    try {
+        cwd = fs.realpathSync(requested);
+    }
+    catch (error) {
+        throw new Error(`Machine 'local' cwd does not exist: ${requested}.`, { cause: error });
+    }
+    if (!fs.statSync(cwd).isDirectory())
+        throw new Error(`Machine 'local' cwd is not a directory: ${requested}.`);
+    const machine = { provider: "rex", id: REX_LOCAL_MACHINE, session, cwd };
+    if (server)
+        machine.server = server;
+    return machine;
+}

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

@@ -0,0 +1,62 @@
+import type { PlacementMachineReference, RexMachineReference } from "../../shared/types.ts";
+import type { HerdrRunIdentity } from "./herdr-placed-run.ts";
+import { PlacedRunOwner } from "./placed-run-owner.ts";
+import { type PlacementEvidenceProof, type PlacementMachineAccess, type PlacementOwnedPane, type PlacementReconnectCheck, type PlacementSockets } from "./placement-host.ts";
+/** On a Rex SSH machine, placed tabs open in the one session with this label. */
+export declare const REX_SSH_SESSION_LABEL = "subagents";
+interface RexEndpoint {
+    access: PlacementMachineAccess;
+    bin: string;
+    session: string;
+    server?: string;
+}
+export interface RexConnection extends RexEndpoint, PlacementSockets {
+}
+export interface RexPaneCandidate {
+    present: boolean;
+    foregroundPid?: number;
+    bridgePid?: number;
+}
+/** The server must confirm the recorded session; a missing session fails closed. A Rex SSH machine's session is the one recorded at launch. */
+export declare function connectRex(machine: PlacementMachineReference, options?: {
+    bin?: string;
+    access?: PlacementMachineAccess;
+    session?: string;
+}): Promise<RexConnection>;
+/** Ownership is the never-reused block id in the recorded session. The block counts as closed only once `block inspect` exits 3. */
+export declare function closeOwnedRexPane(connection: RexConnection, owned: PlacementOwnedPane): Promise<void>;
+declare function reconcileRexPlacedRun(identity: HerdrRunIdentity, candidate: RexPaneCandidate, proveEvidence: () => PlacementEvidenceProof): PlacementReconnectCheck;
+/**
+ * Rex pane host: rex CLI calls on this machine, always with an explicit session. A local child opens as a background
+ * window in the parent's session; a Rex SSH child in the remote `subagents` session, with every rex call run over SSH.
+ * Pi starts through the login shell's environment (as Rex starts any window) with the bridge variables set by
+ * /usr/bin/env. There is no status subscription: a dead Pi closes the bridge socket (directly, or through the SSH
+ * forward), and the reconnect that follows checks the block with `rex block call process` and fails closed.
+ */
+export declare const rexPaneHost: {
+    connect: typeof connectRex;
+    sessionOf(connection: RexConnection): string;
+    launch(connection: RexConnection, machine: PlacementMachineReference, runId: string, _runtimeDir: string, request: import("./placement-host.ts").PlacementLaunchRequest, onPane: (owned: PlacementOwnedPane) => Promise<void>): Promise<{
+        owned: {
+            workspaceId: string;
+            tabId: string;
+            paneId: string;
+        };
+        terminalId: string;
+    }>;
+    prompt(connection: RexConnection, identity: HerdrRunIdentity, text: string): Promise<void>;
+    subscribe(): Promise<() => void>;
+    paneEvent(): undefined;
+    panes(connection: RexConnection, identity: HerdrRunIdentity): Promise<RexPaneCandidate>;
+    reconcile: typeof reconcileRexPlacedRun;
+    closeOwnedPane: typeof closeOwnedRexPane;
+};
+/** The placed-run owner bound to Rex and the pane machine's access. */
+export declare class RexPlacedRunOwner extends PlacedRunOwner<RexConnection, RexMachineReference> {
+    private constructor();
+    /** A Rex SSH owner's machine carries the resolved remote cwd, and its host reconnects only to the session recorded here. */
+    static create(machine: RexMachineReference, runId: string, options?: {
+        sshAccess?: PlacementMachineAccess;
+    }): Promise<RexPlacedRunOwner>;
+}
+export {};