pi-subagents 0.81.0 → 0.82.0

package/src/runs/shared/rex-pane-host.js

@@ -0,0 +1,327 @@
+import { createHash } from "node:crypto";
+import * as path from "node:path";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { remoteShellCommand, sshMachineAccess } from "./herdr-connection.js";
+import { localMachineAccess } from "./local-machine-access.js";
+import { getPiSpawnCommand } from "./pi-spawn.js";
+import { createPlacedRuntimeDir, PLACED_MANIFEST_READ_SCRIPT, PlacedRunOwner, removePlacedRuntimeDir } from "./placed-run-owner.js";
+import { withHerdrPaneAllocationLock } from "./placement-host.js";
+import { isRexLocalMachine, REX_BUNDLE_BIN, REX_CALL_TIMEOUT_MS, REX_EXIT_GONE, REX_EXIT_UNREACHABLE, REX_MAX_OUTPUT, resolveRexBinary, rexCommandEnv, rexGlobalArgs } from "./rex-machine.js";
+const REX_CLOSE_POLLS = 20, REX_CLOSE_POLL_MS = 50;
+/** On a Rex SSH machine, placed tabs open in the one session with this label. */
+export const REX_SSH_SESSION_LABEL = "subagents";
+const sessionInspection = Compile(Type.Object({ session_id: Type.String() }));
+const sessionList = Compile(Type.Object({ sessions: Type.Array(Type.Object({ session_id: Type.String(), label: Type.Optional(Type.String()) })) }));
+const createdWindow = Compile(Type.Object({ window_id: Type.String(), block_ids: Type.Tuple([Type.String()]) }));
+const sessionWindows = Compile(Type.Object({ windows: Type.Array(Type.Object({ window_id: Type.String(), label: Type.Optional(Type.String()), layers: Type.Array(Type.Object({ blocks: Type.Array(Type.Object({ block_id: Type.String() })) })) })) }));
+const blockProcess = Compile(Type.Object({ foreground: Type.Object({ pid: Type.Integer() }) }));
+const bridgeManifestPid = Compile(Type.Object({ pid: Type.Integer() }));
+/** Rex runtime directories go under /tmp: the bridge socket path inside a macOS TMPDIR exceeds the unix socket path limit. */
+function rexAccess() { return localMachineAccess({ env: { ...rexCommandEnv(), TMPDIR: "/tmp" } }); }
+/** The same /tmp rule on the remote, whatever TMPDIR its SSH session has. */
+function rexSshAccess(machine, access = sshMachineAccess(machine)) { return { ...access, shellCommand: (script, args) => remoteShellCommand(`TMPDIR=/tmp; export TMPDIR; ${script}`, args) }; }
+function asRexMachine(machine) { if (machine.provider !== "rex")
+    throw new Error("The Rex pane host only places runs on Rex machines."); return machine; }
+/** Runs one rex command on the pane machine with --autostart=false, the recorded server, and no inherited Rex selectors; exit 4 always throws. */
+async function runRex(endpoint, args, what) {
+    const result = await endpoint.access.runAsync(endpoint.access.shellCommand('exec /usr/bin/env -u REX_SESSION -u REX_BLOCK -u REX_SERVER "$@"', [endpoint.bin, ...rexGlobalArgs(endpoint.server), ...args]), { timeout: REX_CALL_TIMEOUT_MS, maxBuffer: REX_MAX_OUTPUT });
+    if (result.error)
+        throw new Error(`Rex ${what} failed: ${result.error.message}`, { cause: result.error });
+    if (result.status === REX_EXIT_UNREACHABLE)
+        throw new Error(`The Rex server is unreachable (rex ${what} exited 4); the placed pane's state is unknown.`);
+    if (result.status === null)
+        throw new Error(`Rex ${what} did not finish; the placed pane's state is unknown.`);
+    return { ...result, status: result.status };
+}
+function requireRexSuccess(result, what) {
+    if (result.status === REX_EXIT_GONE)
+        throw new Error(`Rex ${what} failed because its target no longer exists (exit 3): ${result.stderr.trim().slice(0, 512)}`);
+    if (result.status !== 0)
+        throw new Error(`Rex ${what} exited with code ${result.status}: ${result.stderr.trim().slice(0, 512)}`);
+}
+/** Parses rex's JSON output against its schema; undefined when the shape does not match. */
+function parseRexJson(text, validator, what) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Rex ${what} returned malformed JSON.`);
+    }
+    return validator.Check(value) ? value : undefined;
+}
+/** One remote lookup, matching resolveRexBinary: `$REX_BIN_DIR/rex`, then `rex` on PATH, then the Rex server bundle under the remote home. */
+async function resolveRemoteRexBinary(access, machine) {
+    const script = `for c in "\${REX_BIN_DIR:+$REX_BIN_DIR/rex}" "$(command -v rex 2>/dev/null)" "$HOME/${REX_BUNDLE_BIN}"; do if [ -n "$c" ] && [ -f "$c" ] && [ -x "$c" ]; then printf '%s\\n' "$c"; exit 0; fi; done; exit 1`;
+    const found = await access.runAsync(access.shellCommand(script), { timeout: REX_CALL_TIMEOUT_MS, maxBuffer: 64 * 1024 });
+    if (found.error)
+        throw new Error(`Could not look for the Rex CLI on ${machine.id}: ${found.error.message}`, { cause: found.error });
+    const bin = found.stdout.trim();
+    if (found.status !== 0 || !path.posix.isAbsolute(bin) || bin.includes("\n"))
+        throw new Error(`The Rex CLI was not found on ${machine.id}. Install Rex there or put rex on its PATH.`);
+    return bin;
+}
+/** The pane's cwd as the remote Pi will report it: `~` expanded and symlinks resolved. Rex does not expand `~` itself. */
+async function resolveRemoteCwd(access, machine) {
+    const script = `case "$1" in "~") d=$HOME;; "~/"*) d=$HOME/\${1#"~/"};; *) d=$1;; esac; cd -P -- "$d" 2>/dev/null && pwd -P`;
+    const resolved = await access.runAsync(access.shellCommand(script, [machine.cwd]), { timeout: REX_CALL_TIMEOUT_MS, maxBuffer: 64 * 1024 });
+    if (resolved.error)
+        throw new Error(`Could not check ${machine.cwd} on ${machine.id}: ${resolved.error.message}`, { cause: resolved.error });
+    const cwd = resolved.stdout.trim();
+    if (resolved.status !== 0 || !path.posix.isAbsolute(cwd) || cwd.includes("\n"))
+        throw new Error(`Nothing at ${machine.cwd} on ${machine.id}. Clone the repo there first; pi-subagents never clones, pulls, or checks out on a machine.`);
+    return cwd;
+}
+/** The remote Pi as a Rex tab's login environment finds it. */
+async function resolveRemotePi(access, machine) {
+    const found = await access.runAsync(access.shellCommand(`exec "\${SHELL:-/bin/sh}" -lc 'command -v pi'`), { timeout: REX_CALL_TIMEOUT_MS, maxBuffer: 64 * 1024 });
+    if (found.error)
+        throw new Error(`Could not look for Pi on ${machine.id}: ${found.error.message}`, { cause: found.error });
+    const pi = found.stdout.trim().split("\n").at(-1)?.trim() ?? "";
+    if (found.status !== 0 || !path.posix.isAbsolute(pi))
+        throw new Error(`Pi was not found on ${machine.id}: its login shell has no pi on PATH. Install Pi there.`);
+    return pi;
+}
+async function labeledSessions(endpoint) {
+    const listed = await runRex(endpoint, ["ls", "--json"], "ls");
+    requireRexSuccess(listed, "ls");
+    const parsed = parseRexJson(listed.stdout, sessionList, "ls");
+    if (!parsed)
+        throw new Error("Rex ls did not list the server's sessions.");
+    return parsed.sessions.filter((session) => session.label === REX_SSH_SESSION_LABEL).map((session) => session.session_id);
+}
+/**
+ * The session labeled `subagents` on the SSH machine, created when there is none. Rex allows duplicate labels, so two or
+ * more fail closed, also after creating one. Only launch calls this; reconnect and cleanup use the recorded session id.
+ */
+async function subagentsSession(endpoint, machine) {
+    return withHerdrPaneAllocationLock(JSON.stringify(["rex-session", machine.target, REX_SSH_SESSION_LABEL]), async () => {
+        let sessions = await labeledSessions(endpoint);
+        if (sessions.length === 0) {
+            requireRexSuccess(await runRex(endpoint, ["new", REX_SSH_SESSION_LABEL, "--json"], "new"), "new");
+            sessions = await labeledSessions(endpoint);
+        }
+        const [session] = sessions;
+        if (sessions.length > 1)
+            throw new Error(`Rex on ${machine.id} has ${sessions.length} sessions labeled ${REX_SSH_SESSION_LABEL}; close or rename the extras so placed runs have one session to open in.`);
+        if (!session)
+            throw new Error(`Rex on ${machine.id} did not list the ${REX_SSH_SESSION_LABEL} session it just created.`);
+        return session;
+    });
+}
+/** 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 async function connectRex(machine, options = {}) {
+    const rex = asRexMachine(machine);
+    let endpoint;
+    if (isRexLocalMachine(rex)) {
+        endpoint = { access: options.access ?? rexAccess(), bin: options.bin ?? resolveRexBinary(), session: rex.session };
+        if (rex.server)
+            endpoint.server = rex.server;
+    }
+    else {
+        if (!options.session)
+            throw new Error(`Rex machine '${rex.id}' has no recorded session; a placed run never picks one by label after launch.`);
+        const access = options.access ?? rexSshAccess(rex);
+        endpoint = { access, bin: options.bin ?? await resolveRemoteRexBinary(access, rex), session: options.session };
+    }
+    const inspected = await runRex(endpoint, ["session", "inspect", endpoint.session, "--json"], "session inspect");
+    if (inspected.status === REX_EXIT_GONE)
+        throw new Error(`Rex session ${endpoint.session} no longer exists on the Rex server.`);
+    requireRexSuccess(inspected, "session inspect");
+    if (parseRexJson(inspected.stdout, sessionInspection, "session inspect")?.session_id !== endpoint.session)
+        throw new Error("Rex session identity changed: the server reported a different session id.");
+    return { ...endpoint, ...endpoint.access.openSockets() };
+}
+async function inspectBlock(connection, blockId) {
+    const inspected = await runRex(connection, ["block", "inspect", "-s", connection.session, blockId], "block inspect");
+    if (inspected.status === REX_EXIT_GONE)
+        return "gone";
+    requireRexSuccess(inspected, "block inspect");
+    return "present";
+}
+/** Ownership is the never-reused block id in the recorded session. The block counts as closed only once `block inspect` exits 3. */
+export async function closeOwnedRexPane(connection, owned) {
+    if (owned.workspaceId !== connection.session)
+        throw new Error("Refusing Rex cleanup: the owned pane belongs to a different Rex session.");
+    if (await inspectBlock(connection, owned.paneId) === "gone")
+        return;
+    const closed = await runRex(connection, ["block", "close", "-s", connection.session, owned.paneId], "block close");
+    if (closed.status !== REX_EXIT_GONE)
+        requireRexSuccess(closed, "block close");
+    for (let poll = 0; poll < REX_CLOSE_POLLS; poll++) {
+        if (await inspectBlock(connection, owned.paneId) === "gone")
+            return;
+        await new Promise((resolve) => setTimeout(resolve, REX_CLOSE_POLL_MS));
+    }
+    throw new Error(`Rex block ${owned.paneId} still exists after close; refusing to report the placed pane closed.`);
+}
+function reconcileRexPlacedRun(identity, candidate, proveEvidence) {
+    if (!candidate.present)
+        return { ok: false, reason: "Owned Rex block is gone." };
+    if (candidate.foregroundPid === undefined || candidate.foregroundPid !== candidate.bridgePid)
+        return { ok: false, reason: "The owned Rex block's foreground process is not the placed Pi." };
+    const proof = proveEvidence();
+    if (!proof.ok)
+        return proof;
+    return { ok: true, state: "unknown", paneId: identity.paneId, cursor: proof.cursor };
+}
+async function readBridgePid(connection, runtimeDir) {
+    const manifest = await connection.access.runAsync(connection.access.shellCommand(PLACED_MANIFEST_READ_SCRIPT, [runtimeDir]), { timeout: 5_000, maxBuffer: 64 * 1024 });
+    if (manifest.status !== 0)
+        return undefined;
+    return parseRexJson(manifest.stdout, bridgeManifestPid, "bridge manifest")?.pid;
+}
+/**
+ * `window new` failed, timed out, or printed something unreadable, so the server may still have opened this run's window.
+ * Find it by the run's tab label in the recorded session and close its blocks with the same close-then-prove-gone rule.
+ */
+async function closeUntrackedRexWindow(connection, label, failure) {
+    try {
+        const inspected = await runRex(connection, ["session", "inspect", connection.session, "--json"], "session inspect");
+        if (inspected.status === REX_EXIT_GONE)
+            throw failure;
+        requireRexSuccess(inspected, "session inspect");
+        const windows = parseRexJson(inspected.stdout, sessionWindows, "session inspect")?.windows.filter((window) => window.label === label);
+        if (!windows)
+            throw new Error("Rex session inspect did not list the session's windows.");
+        if (windows.length > 1)
+            throw new Error(`The Rex session has ${windows.length} windows labeled ${label}; refusing to guess which one this run opened.`);
+        for (const window of windows)
+            for (const layer of window.layers)
+                for (const block of layer.blocks)
+                    await closeOwnedRexPane(connection, { workspaceId: connection.session, tabId: window.window_id, paneId: block.block_id });
+    }
+    catch (cleanupError) {
+        if (cleanupError === failure)
+            throw failure;
+        throw new AggregateError([failure, cleanupError], `Rex window new failed, and the window labeled ${label} that it may have opened could not be closed.`, { cause: failure });
+    }
+    throw failure;
+}
+/** Opens the run's background window; on any failure, closes the window the server may have opened before rethrowing. */
+async function openRexWindow(connection, label, cwd, argv) {
+    try {
+        const created = await runRex(connection, ["window", "new", "-s", connection.session, label, "-c", cwd, "--focus=false", "--json", "--", ...argv], "window new");
+        requireRexSuccess(created, "window new");
+        const window = parseRexJson(created.stdout, createdWindow, "window new");
+        if (!window)
+            throw new Error(`Rex window new did not return exactly one block: ${created.stdout.trim().slice(0, 512)}`);
+        return window;
+    }
+    catch (error) {
+        return closeUntrackedRexWindow(connection, label, error instanceof Error ? error : new Error(String(error)));
+    }
+}
+/**
+ * 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 const rexPaneHost = {
+    connect: connectRex,
+    sessionOf(connection) { return connection.session; },
+    async launch(connection, machine, runId, _runtimeDir, request, onPane) {
+        if (request.kind !== "pi")
+            throw new Error("Rex supports native Pi children only.");
+        const environment = Object.entries(request.environment ?? {});
+        if (environment.some(([name]) => !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)))
+            throw new Error("Rex launch environment names must be shell variable names.");
+        const rex = asRexMachine(machine);
+        let pi;
+        if (isRexLocalMachine(rex)) {
+            pi = getPiSpawnCommand(request.args);
+            if (!path.isAbsolute(pi.command))
+                throw new Error("Rex placement needs an absolute Pi executable; set PI_SUBAGENT_PI_BINARY to the Pi binary path.");
+        }
+        else
+            pi = { command: await resolveRemotePi(connection.access, rex), args: request.args };
+        const window = await openRexWindow(connection, `subagent-${runId.slice(-8)}`, rex.cwd, ["/usr/bin/env", ...environment.map(([name, value]) => `${name}=${value}`), pi.command, ...pi.args]);
+        const owned = { workspaceId: connection.session, tabId: window.window_id, paneId: window.block_ids[0] };
+        await onPane(owned);
+        return { owned, terminalId: owned.paneId };
+    },
+    async prompt(connection, identity, text) {
+        requireRexSuccess(await runRex(connection, ["send", "-s", connection.session, "-b", identity.paneId, "--", text], "send"), "send");
+        requireRexSuccess(await runRex(connection, ["send-key", "-s", connection.session, "-b", identity.paneId, "enter"], "send-key"), "send-key");
+    },
+    async subscribe() { return () => { }; },
+    paneEvent() { return undefined; },
+    async panes(connection, identity) {
+        const processInfo = await runRex(connection, ["block", "call", "-s", connection.session, "-b", identity.paneId, "process"], "block process");
+        if (processInfo.status === REX_EXIT_GONE)
+            return { present: false };
+        requireRexSuccess(processInfo, "block process");
+        const candidate = { present: true };
+        const foregroundPid = parseRexJson(processInfo.stdout, blockProcess, "block process")?.foreground.pid;
+        if (foregroundPid !== undefined)
+            candidate.foregroundPid = foregroundPid;
+        const bridgePid = await readBridgePid(connection, identity.runtimeDir);
+        if (bridgePid !== undefined)
+            candidate.bridgePid = bridgePid;
+        return candidate;
+    },
+    reconcile: reconcileRexPlacedRun,
+    closeOwnedPane: closeOwnedRexPane,
+};
+function runtimeDirPresent(access, runtimeDir) {
+    const result = access.run(access.shellCommand('test -e "$1" || test -L "$1"', [runtimeDir]), { timeout: 10_000, maxBuffer: 4096 });
+    if (result.error)
+        throw new Error(`Could not check the owned runtime directory: ${result.error.message}`, { cause: result.error });
+    return result.status === 0;
+}
+/** A closed local Pi removes its own runtime directory on shutdown, so already-removed counts as removed. */
+function removeRexRuntimeDir(access, runtimeDir) {
+    if (!runtimeDirPresent(access, runtimeDir))
+        return;
+    try {
+        removePlacedRuntimeDir(access, runtimeDir);
+    }
+    catch (error) {
+        if (runtimeDirPresent(access, runtimeDir))
+            throw error;
+    }
+}
+/** The placed-run owner bound to Rex and the pane machine's access. */
+export class RexPlacedRunOwner extends PlacedRunOwner {
+    constructor(machine, runId, runtimeDir, connection, access, host) { super(machine, runId, runtimeDir, connection, host, access, () => removeRexRuntimeDir(access, runtimeDir)); }
+    /** A Rex SSH owner's machine carries the resolved remote cwd, and its host reconnects only to the session recorded here. */
+    static async create(machine, runId, options = {}) {
+        // A short hash names the directory, so /tmp/pi-subagents-herdr-<hash>-XXXXXXXX/bridge.sock (57 bytes) fits the 103-byte macOS socket path limit for any run id.
+        const hash = createHash("sha256").update(runId).digest("hex").slice(0, 12);
+        if (isRexLocalMachine(machine)) {
+            const access = rexAccess(), runtimeDir = await createPlacedRuntimeDir(access, hash);
+            try {
+                return new RexPlacedRunOwner(machine, runId, runtimeDir, await connectRex(machine, { access }), access, rexPaneHost);
+            }
+            catch (error) {
+                try {
+                    removeRexRuntimeDir(access, runtimeDir);
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], "Rex owner creation failed and runtime cleanup also failed.", { cause: error });
+                }
+                throw error;
+            }
+        }
+        const access = rexSshAccess(machine, options.sshAccess), bin = await resolveRemoteRexBinary(access, machine);
+        const placed = { ...machine, cwd: await resolveRemoteCwd(access, machine) };
+        const session = await subagentsSession({ access, bin }, placed);
+        const host = { ...rexPaneHost, connect: (target) => connectRex(target, { access, bin, session }) };
+        const runtimeDir = await createPlacedRuntimeDir(access, hash);
+        try {
+            return new RexPlacedRunOwner(placed, runId, runtimeDir, await host.connect(placed), access, host);
+        }
+        catch (error) {
+            try {
+                removeRexRuntimeDir(access, runtimeDir);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "Rex owner creation failed and runtime cleanup also failed.", { cause: error });
+            }
+            throw error;
+        }
+    }
+}

package/src/shared/completion-owner.d.ts

@@ -1,2 +1,7 @@
+/**
+ * The completion owner of a result whose own owner process is dead: whichever session owns the run
+ * delivers it. Delivery consumes the result.
+ */
+export declare const OWNING_SESSION_COMPLETION_OWNER = "owning-session";
 /** Stable for one parent Pi process across extension reloads. */
 export declare function currentCompletionOwnerId(): string;

package/src/shared/completion-owner.js

@@ -1,5 +1,10 @@
 import { randomUUID } from "node:crypto";
 const COMPLETION_OWNER_KEY = Symbol.for("pi-subagents.completion-owner-id");
+/**
+ * The completion owner of a result whose own owner process is dead: whichever session owns the run
+ * delivers it. Delivery consumes the result.
+ */
+export const OWNING_SESSION_COMPLETION_OWNER = "owning-session";
 /** Stable for one parent Pi process across extension reloads. */
 export function currentCompletionOwnerId() {
     const runtime = globalThis;

package/src/shared/session-identity.d.ts

@@ -3,4 +3,6 @@ interface SessionIdentityManager {
     getSessionId(): string | null | undefined;
 }
 export declare function resolveCurrentSessionId(sessionManager: SessionIdentityManager): string;
+/** The id in a Pi session file's header, which `pi --session <id>` resolves; only ids that need no shell quoting. */
+export declare function resolvePiSessionId(sessionFile: string | undefined): string | undefined;
 export {};

package/src/shared/session-identity.js

@@ -1,6 +1,32 @@
+import * as fs from "node:fs";
 export function resolveCurrentSessionId(sessionManager) {
     const sessionId = sessionManager.getSessionFile() ?? sessionManager.getSessionId();
     if (!sessionId)
         throw new Error("Current session identity is unavailable.");
     return sessionId;
 }
+/** The id in a Pi session file's header, which `pi --session <id>` resolves; only ids that need no shell quoting. */
+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;
+    }
+}

package/src/shared/types.d.ts

@@ -16,6 +16,8 @@ import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
 import type { WorkflowChildPermitContext } from "./workflow-child-permit.ts";
 import type { WatchdogWarningDetails } from "../watchdog/types.ts";
 import type { RequiredChildExtensionSnapshot } from "./required-child-extensions.ts";
+import type { RecordedPid } from "../runs/background/stale-run-reconciler.ts";
+import type { WorkflowStopCause } from "../workflows/workflow-stop-cause.ts";
 export interface MaxOutputConfig {
     bytes?: number;
     lines?: number;
@@ -1166,7 +1168,7 @@ export interface SingleResult {
     model?: string;
     /** Authoritative before/after Git evidence captured by a pane-native remote machine. */
     nativeMachine?: {
-        provider: "herdr";
+        provider: PlacementMachineReference["provider"];
         machineId: string;
         initialGit?: HerdrRemoteGitStatus;
         finalGit?: HerdrRemoteGitStatus;
@@ -1431,10 +1433,17 @@ export interface Details {
         argsDigest?: string;
         /** SHA-256 of the workflow script source (async workflows). */
         scriptDigest?: string;
-        /** Structured stop cause; set only when the owning extension runtime was replaced. */
-        stopCause?: "runtime-replaced";
-        /** Runtime-replaced workflow run whose finished children this run reused. */
+        /** Structured stop cause: `runtime-replaced` when the owning extension runtime was replaced; `owner-exited` when stale-run reconciliation found the owning Pi process dead. */
+        stopCause?: WorkflowStopCause;
+        /** Interrupted workflow run whose finished children this run reused. */
         reusedFrom?: string;
+        /** Owner-exited runs: the last time the dead Pi process updated the run (epoch ms), not the repair time. */
+        ownerExitedAt?: number;
+        /** Set on a run that resumes an interrupted one; `attempt` counts resumes that followed Pi exits. */
+        resumeOrigin?: {
+            sourceRunId: string;
+            attempt: number;
+        };
         resource?: WorkflowResourceProvenance;
         preflightWarnings?: string[];
         trace: Array<{
@@ -1450,7 +1459,7 @@ export interface Details {
             generatedLaneKey?: string;
             warning?: string;
             error?: string;
-            /** Came from a previous runtime-replaced run of the same script (and args, unless named by options.reuseFrom); this run launched nothing. */
+            /** Came from a previous runtime-replaced or owner-exited run of the same script (and args, unless named by options.reuseFrom); this run launched nothing. */
             reused?: boolean;
         }>;
         emits: unknown[];
@@ -1673,6 +1682,24 @@ export interface HerdrMachineReference {
     session?: string;
     cwd: string;
 }
+/** `machine: "local"`: a Rex pane in the parent's own Rex session on this machine. `session` is the Rex session id and `server` the Rex server address, both recorded in the parent at resolution time; `cwd` is the local launch directory. */
+export interface RexLocalMachineReference {
+    provider: "rex";
+    id: "local";
+    session: string;
+    server?: string;
+    cwd: string;
+}
+/** A Rex machine reached over SSH, named in user settings (`subagents.machines.<id>.rex.ssh`). The pane opens in that machine's Rex session labeled `subagents`, found or created at launch and recorded with the run; `cwd` is the directory on that machine. */
+export interface RexSshMachineReference {
+    provider: "rex";
+    id: string;
+    target: string;
+    cwd: string;
+}
+export type RexMachineReference = RexLocalMachineReference | RexSshMachineReference;
+/** Where a placed native Pi child runs. */
+export type PlacementMachineReference = HerdrMachineReference | RexMachineReference;
 export interface ExternalCliMachineStatus extends HerdrMachineReference {
     remoteGit?: HerdrRemoteGitStatus;
 }
@@ -1824,6 +1851,8 @@ export interface AsyncStatus {
     runId: string;
     /** Parent Pi process/window that owns local completion delivery. */
     completionOwnerId?: string;
+    /** The Pi process behind `completionOwnerId`; once it is dead, the session that owns the run delivers it. */
+    completionOwnerProcess?: RecordedPid;
     /** Host tool-call id retained when it differs from the internal run id. */
     toolCallId?: string;
     sessionId?: string;
@@ -1860,6 +1889,8 @@ export interface AsyncStatus {
     pid?: number;
     /** Linux PID namespace identity used to scope liveness probes. */
     pidNamespaceScope?: string;
+    /** Boot id of the machine when `pid` was recorded; a different current boot id proves the pid dead. */
+    bootId?: string;
     cwd?: string;
     /** User-configured launcher that wrapped the background runner (argv only, never environment). */
     launcher?: RunnerLauncher;
@@ -2135,6 +2166,10 @@ export interface ForegroundResumeRun {
     sessionId?: string;
     updatedAt: number;
     children: ForegroundResumeChild[];
+    /** Pi process running this run; only on records whose child is `running`. */
+    owner?: RecordedPid;
+    /** Workflow that launched this foreground child. */
+    parentWorkflowRunId?: string;
 }
 export interface ForegroundChildControl {
     index: number;
@@ -2318,6 +2353,8 @@ export interface SubagentState {
     workflowControllers?: Map<string, AbortController>;
     /** Live in-process workflow child stoppers keyed by parent workflow run id. */
     workflowChildStops?: Map<string, (childId: string, message?: string) => boolean>;
+    /** Background children awaited by a blocking workflow call: their parent cannot answer supervisor asks. */
+    blockingWorkflowChildren?: Set<string>;
 }
 export interface HerdrProjectPaneSnapshot {
     projectRoot: string;
@@ -2422,7 +2459,7 @@ export interface RunSyncOptions {
     context?: "fresh" | "fork";
     cwd?: string;
     /** Resolved pane-native saved-machine placement. */
-    machine?: HerdrMachineReference;
+    machine?: PlacementMachineReference;
     /** Explicit read override resolved by the remote ambient agent profile. */
     remoteReads?: string[] | false;
     /** Original cwd input retained for launch diagnostics. */
@@ -2583,6 +2620,8 @@ export interface ActiveAsyncCapacityConfig {
 }
 export interface ExtensionConfig {
     asyncByDefault?: boolean;
+    /** Relaunch this session's interrupted async workflows when the session is reopened or reloaded (default true). */
+    autoResume?: boolean;
     /** Set the context for launches that omit an explicit context. */
     defaultSubagentContext?: "fresh" | "fork";
     /** Configure how every resolved fork session is prepared before child spawn. */

package/src/tui/fleet.d.ts

@@ -46,6 +46,7 @@ export type FleetItem = ({
     updatedAt: number;
     run: AsyncRunSummary;
     step?: AsyncStep;
+    task?: string;
 } | {
     key: string;
     kind: "external";

package/src/tui/fleet.js

@@ -16,7 +16,9 @@ import { steerAsyncRun } from "../runs/foreground/async-steering-action.js";
 import { stopAsyncRun } from "../runs/foreground/async-stop-action.js";
 import { resolveWorkflowForegroundSteeringTarget, steerWorkflowForegroundTarget } from "../runs/foreground/workflow-foreground-steering.js";
 import { contextModeBadge, contextModeLabel } from "../runs/shared/context-mode.js";
+import { foregroundChildStateLabel } from "../runs/foreground/foreground-history.js";
 import { FLEET_STATUS_WIDGET_KEY, reportFleetWarning } from "./fleet-status.js";
+import { stepTaskSummary } from "./render.js";
 import { readFleetTranscript, renderFleetTranscript } from "./fleet-transcript.js";
 import { runningTone } from "./running-tone.js";
 import { childThinkingLevel } from "../shared/model-info.js";
@@ -110,18 +112,22 @@ function asyncItems(run, description) {
     if (run.steps.length === 0 || run.mode === "workflow") {
         return [{ key: `async:${run.id}`, kind: "async", runId: run.id, agent: run.mode, state: run.state, updatedAt, run, ...(description ? { description } : {}) }];
     }
-    return run.steps.map((step) => ({
-        key: `async:${run.id}:${step.index}`,
-        kind: "async",
-        runId: run.id,
-        index: step.index,
-        agent: step.label ? `${step.label} (${step.agent})` : step.agent,
-        state: step.status,
-        updatedAt: step.lastActivityAt ?? updatedAt,
-        run,
-        step,
-        ...(description ? { description } : {}),
-    }));
+    return run.steps.map((step) => {
+        const task = stepTaskSummary(step, step.agent);
+        return {
+            key: `async:${run.id}:${step.index}`,
+            kind: "async",
+            runId: run.id,
+            index: step.index,
+            agent: step.label ? `${step.label} (${step.agent})` : step.agent,
+            state: step.status,
+            updatedAt: step.lastActivityAt ?? updatedAt,
+            run,
+            step,
+            ...(task ? { task } : {}),
+            ...(description ? { description } : {}),
+        };
+    });
 }
 function orderFleetAsyncRuns(runs, terminalLimit, trackedJobs) {
     const updatedAt = (run) => run.lastUpdate ?? run.endedAt ?? run.startedAt;
@@ -445,7 +451,7 @@ function foregroundRecentDetail(item, state) {
     const lines = [
         `Run: ${item.runId}`,
         "Source: foreground",
-        `State: ${child.status}`,
+        `State: ${foregroundChildStateLabel(run, child)}`,
         `Mode: ${run.mode}`,
         `Child: ${child.index} (${child.agent})${contextModeLabel(child.context) ? ` ${contextModeLabel(child.context)}` : ""}`,
         modelThinking ? `Model: ${modelThinking}` : undefined,
@@ -1226,8 +1232,11 @@ export class SubagentFleetComponent {
             const item = this.snapshot.items[index];
             const marker = index === this.selected ? this.theme.fg("accent", "›") : " ";
             const context = item.kind === "async" ? contextModeBadge(this.theme, item.step?.context ?? item.run.context) : item.kind === "foreground-recent" ? contextModeBadge(this.theme, item.child.context) : "";
-            const agent = index === this.selected ? this.theme.bold(item.agent) : item.agent;
-            const identity = item.runId.slice(0, 8);
+            // A child's task tells rows of one run apart; the run id stays in the detail header.
+            const task = item.kind === "async" ? item.task : undefined;
+            const name = task && item.kind === "async" && item.step ? item.step.agent : item.agent;
+            const agent = index === this.selected ? this.theme.bold(name) : name;
+            const identity = task ?? item.runId.slice(0, 8);
             const left = `${marker} ${statusGlyph(item, this.theme)} ${agent}${context} ${this.theme.fg("dim", `· ${identity}`)}`;
             return rightAligned(left, this.theme.fg("dim", item.state), layout.roster.width);
         });

package/src/tui/render.d.ts

@@ -39,6 +39,12 @@ export interface AsyncLaneProjection {
 /** Project already-loaded async status facts into one bounded, render-only lane row. */
 export declare function projectAsyncLane(job: AsyncJobState, ...args: [selectedStep?: AsyncJobStep]): AsyncLaneProjection | undefined;
 export declare function widgetRenderKey(job: AsyncJobState, expanded?: boolean): string;
+/** A child's task in one line: its label and task, else its session name without the repeated agent name. */
+export declare function stepTaskSummary(step: {
+    description?: string;
+    label?: string;
+    sessionName?: string;
+}, agentName: string | undefined): string | undefined;
 /** Structural identity of the workflow rows that Fleet can cover. */
 export declare function inlineWorkflowRenderKey(job: AsyncJobState, children: AsyncJobState[]): string;
 /** Presentation-only coverage from the mounted inline Fleet roster, never configuration. */

package/src/tui/render.js

@@ -1104,14 +1104,14 @@ function shouldCollapseSingleChildDetails(job, step) {
         return isCompletedWidgetStepStatus(step.status);
     return false;
 }
-function singleChildTask(job, step) {
+/** A child's task in one line: its label and task, else its session name without the repeated agent name. */
+export function stepTaskSummary(step, agentName) {
     const task = compactTaskText(step.description, step.label);
     if (task)
         return task;
     const sessionName = step.sessionName?.trim();
     if (!sessionName)
         return undefined;
-    const agentName = singleChildAgentName(job, step);
     const sessionTask = stripRepeatedAgentPrefix(sessionName, agentName);
     return sessionTask === agentName ? undefined : compactTaskText(sessionTask);
 }
@@ -2223,7 +2223,7 @@ function foregroundStyleWidgetStepLines(job, theme, step, itemTitle, index, tota
     const lane = projectAsyncLane(job, step);
     if (lane)
         lines.push(...formatLaneProjectionLines(lane, theme, detailIndent));
-    const task = collapseDetails ? singleChildTask(job, step) : compactTaskText(step.description, step.label);
+    const task = collapseDetails ? stepTaskSummary(step, displayName) : compactTaskText(step.description, step.label);
     if (task)
         lines.push(`${detailIndent}${theme.fg("dim", `task: ${task}`)}`);
     const activity = widgetStepActivityLine(step, width, expanded, job.updatedAt);

package/src/tui/subagent-messages.js

@@ -183,6 +183,7 @@ const MESSAGE_VIEWS = new Map([
     ["subagent-wait-subscription", readsContent("result", (message) => waitSubscriptionHeadline(message.details))],
     ["subagent-incremental-child-notify", readsContent("result", workflowChildHeadline)],
     ["subagent-workflow-result-write-failed", readsContent("result", () => ["workflow result ", { status: "save failed" }])],
+    ["subagent-auto-resume", readsContent("result", () => ["workflow auto-resume ", { status: "failed" }])],
     [SUBAGENT_CONTROL_MESSAGE_TYPE, readsContent("attention", (message) => controlNoticeHeadline(message.details))],
     [SUBAGENT_STEERING_MESSAGE_TYPE, readsContent("attention", (message) => steeringNoticeHeadline(message.details))],
     [SUBAGENT_WATCHDOG_WARNING_TYPE, (message) => watchdogWarningView(message.details, contentText(message.content))],