pi-subagents 0.76.0 → 0.77.0

package/src/runs/background/async-execution.js

@@ -18,12 +18,13 @@ import { applyThinkingSuffix, projectLaunchResolvedChildExtensions, resolvePiLau
 import { assertClaudeCodeModelScope, isClaudeCodeAdapterId, resolveClaudeCodeOverride } from "../shared/claude-code-adapter.js";
 import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.js";
 import { applyWatchdogLaunchRules, sendRuleViolationWarning } from "../../watchdog/rules.js";
-import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveExistingReadInstructionPaths, resolveExistingReadPaths, writeInitialProgressFile } from "../../shared/settings.js";
+import { buildChainInstructions, getStepAgents, isDynamicParallelStep, isParallelStep, resolveExistingReadInstructionPaths, resolveExistingReadPaths, writeInitialProgressFile } from "../../shared/settings.js";
 import { isDynamicRunnerGroup, isParallelGroup } from "../shared/parallel-utils.js";
 import { PI_CODING_AGENT_PACKAGE, resolveBunPiExecutable, resolveInstalledPiPackageRoot, resolvePiPackageRoot } from "../shared/pi-spawn.js";
 import { JITI_ALIAS_ENV, resolveHostPeerAliases } from "./runner-aliases.js";
 import { preflightLaunchCwd } from "../shared/launch-cwd.js";
 import { resolveNodeExecutable } from "../../shared/node-executable.js";
+import { resolveRuntimeModulePath } from "../../shared/runtime-module-path.js";
 import { backgroundProcessOptions } from "../shared/background-process-options.js";
 import { normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.js";
 import { PI_CODING_AGENT_PACKAGE_ROOT_ENV, PROMPT_REDACTED, resolveChildCwd } from "../../shared/utils.js";
@@ -51,6 +52,8 @@ import { finalizeProcessTerminal, initializeProcessTerminal, readProcessTerminal
 import { persistRunnerStartupFailure } from "./runner-startup-failure.js";
 import { statusStepDescription } from "./chain-append.js";
 import { currentPidNamespaceScope } from "./pid-namespace.js";
+import { checkPidLiveness } from "./stale-run-reconciler.js";
+import { lookupRunnerLauncher, resolveAgentRunnerLauncher, runnerLauncherPlacementError } from "../shared/runner-launcher.js";
 import { SUBAGENT_PROCESS_TERMINAL_EVENT } from "../../shared/types.js";
 import { assertAgentAllowedByCapabilityCeiling, intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling } from "../shared/capability-ceiling.js";
 import { resolveLaunchBinding } from "../../shared/launch-contract.js";
@@ -122,28 +125,29 @@ function resolveJitiCliPath() {
     return undefined;
 }
 const jitiCliPath = resolveJitiCliPath();
-const asyncRunnerSourcePath = path.join(path.dirname(fileURLToPath(import.meta.url)), `subagent-runner-bootstrap${path.extname(fileURLToPath(import.meta.url))}`);
-const sourceUnderNodeModules = asyncRunnerSourcePath.split(path.sep).some((segment) => segment.toLowerCase() === "node_modules");
+const asyncRunnerModuleDir = path.dirname(fileURLToPath(import.meta.url));
+// Resolved per launch: an in-place package update can swap a sibling's .ts for .js.
+function asyncRunnerSourcePath() {
+    return resolveRuntimeModulePath(asyncRunnerModuleDir, "subagent-runner-bootstrap");
+}
+function sourceUnderNodeModules() {
+    return asyncRunnerSourcePath().split(path.sep).some((segment) => segment.toLowerCase() === "node_modules");
+}
 function supportsNativeRunner(nodeExecutable) {
     return Boolean(process.features.typescript)
         && typeof nodeModule.registerHooks === "function"
         && nodeExecutable === process.execPath
-        && !sourceUnderNodeModules;
+        && !sourceUnderNodeModules();
 }
 export const DEFAULT_ASYNC_TIMEOUT_MS = 30 * 60 * 1000;
 export function formatAsyncStartedMessage(headline, interactive) {
     const guidance = interactive
         ? [
-            "The async run is detached and running in the background.",
-            "You are in an interactive session. Return control to the user now; Pi will wake you through the native completion notification when this subagent completes or needs attention. Do not run sleep/polling loops to wait for this async subagent; it does not need a wait call.",
-            "Use bg_wait only for provider, detached, or other background work that lacks a native completion notification.",
-            "If the current turn must receive results from work without a native notification before it ends, call blocking bg_wait(); ordinary async subagent runs do not need a wait call because their completion is delivered natively.",
-            "Otherwise, continue any independent work or return control to the user. Use subagent({ action: \"status\", id: \"...\" }) for a one-shot status/result or to inspect a blocked/stale run, never as a wait loop.",
+            "Detached. Return control now: native completion wakes you, so do not sleep, poll, or call bg_wait for it.",
+            "One-shot check: subagent({ action: \"status\", id: \"...\" }).",
         ]
         : [
-            "The async run is detached. Do not run sleep timers or polling loops just to wait for it.",
-            "This is a non-interactive run: Pi auto-drains current-session subagent work at agent_end so detached children are not abandoned. Use bg_wait only when this turn must receive provider, detached, or other background-work results that have no native completion notification.",
-            "Use subagent({ action: \"status\", id: \"...\" }) when you need a one-shot status/result or to inspect a blocked/stale run; do not poll in a loop.",
+            "Detached non-interactive run: Pi auto-drains current-session subagent work at agent_end. Do not run sleep timers or polling loops. Use bg_wait only for results this turn needs from work without native notification, and subagent({ action: \"status\", id: \"...\" }) for a one-shot check.",
         ];
     return [headline, "", ...guidance].join("\n");
 }
@@ -191,7 +195,7 @@ function readRunnerStartup(startupPath, expectedState, expectedToken) {
         if (typeof payload.token !== "string" || (expectedToken !== undefined && payload.token !== expectedToken)) {
             return { ok: false, error: `Async runner wrote an invalid ${expectedState} startup handshake: ${startupPath}`, startupDidNotProceed: true };
         }
-        return { ok: true, token: payload.token };
+        return { ok: true, token: payload.token, pid: payload.pid, pidNamespaceScope: payload.pidNamespaceScope };
     }
     catch (error) {
         return { ok: false, error: `Failed to read async runner startup handshake '${startupPath}': ${error instanceof Error ? error.message : String(error)}`, startupDidNotProceed: true };
@@ -276,7 +280,7 @@ function terminateRunnerBeforeProceed(pid) {
     }
     return !runnerIsAlive(pid);
 }
-async function terminateRunnerBeforeProceedAsync(proc, processClosed) {
+async function terminateRunnerBeforeProceedAsyncDefault(proc, processClosed) {
     for (const signal of ["SIGTERM", "SIGKILL"]) {
         if (proc.pid === undefined || !runnerIsAlive(proc.pid))
             return true;
@@ -293,9 +297,17 @@ async function terminateRunnerBeforeProceedAsync(proc, processClosed) {
     }
     return proc.pid === undefined || !runnerIsAlive(proc.pid);
 }
-async function completeRunnerStartupHandshake(startupPath, startupAckPath, startupConfirmPath, startupProceedPath, proc, processClosed, getObservedProcessExit, runnerProcessInstanceId, persistStartupFailure) {
+async function completeRunnerStartupHandshake(startupPath, startupAckPath, startupConfirmPath, startupProceedPath, proc, processClosed, getObservedProcessExit, runnerProcessInstanceId, persistStartupFailure, 
+// Behind a launcher the spawned pid is only the wrapper's: adopt the runner-reported pid and never signal the wrapper.
+launcherIdentity) {
+    const terminateRunnerBeforeProceedAsync = async (proc, processClosed) => launcherIdentity ? launcherIdentity.terminate() : terminateRunnerBeforeProceedAsyncDefault(proc, processClosed);
     try {
         const ready = await waitForRunnerStartup(startupPath, "ready", RUNNER_STARTUP_TIMEOUT_MS, undefined, processClosed);
+        const identityError = ready.ok && launcherIdentity ? launcherIdentity.adopt(ready.pid, ready.pidNamespaceScope) : undefined;
+        if (identityError) {
+            persistStartupFailure(identityError);
+            return { runnerProcessInstanceId, error: identityError, terminationObserved: await terminateRunnerBeforeProceedAsync(proc, processClosed), startupDidNotProceed: true };
+        }
         if (ready.ok === false) {
             persistStartupFailure(ready.error);
             const terminationObserved = await terminateRunnerBeforeProceedAsync(proc, processClosed);
@@ -401,13 +413,13 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
     const binaryHost = resolveBunPiExecutable();
     const nodeExecutable = resolveNodeExecutable();
     const nativeRunnerSupported = supportsNativeRunner(nodeExecutable);
-    const runner = asyncRunnerSourcePath;
+    const runner = asyncRunnerSourcePath();
     const runnerIsJavaScript = path.extname(runner) === ".js";
-    const bootstrap = path.join(path.dirname(runner), `binary-bootstrap${path.extname(fileURLToPath(import.meta.url))}`);
+    const bootstrap = resolveRuntimeModulePath(path.dirname(runner), "binary-bootstrap");
     if (binaryHost && !fs.existsSync(bootstrap))
         return { error: `Background runner bootstrap not found: ${bootstrap}` };
     if (!binaryHost && !runnerIsJavaScript && !nativeRunnerSupported && !jitiCliPath) {
-        return { error: sourceUnderNodeModules
+        return { error: sourceUnderNodeModules()
                 ? "Background runner source is installed under node_modules, so upstream jiti is required for TypeScript execution."
                 : "Background runner requires enabled native TypeScript with synchronous module hooks, or installed upstream jiti for TypeScript execution." };
     }
@@ -447,6 +459,30 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
         fs.rmSync(startupConfirmPath, { force: true });
     if (startupProceedPath)
         fs.rmSync(startupProceedPath, { force: true });
+    // A broker launcher may start the runner outside its own process, so the spawned pid is only the
+    // wrapper's. The runner reports its own identity before it is allowed to proceed.
+    const launcher = launchConfig.launcher;
+    const identityPath = launcher && launchBarrierToken && launchAsyncDir ? path.join(launchAsyncDir, "runner-startup.json") : undefined;
+    if (identityPath)
+        fs.rmSync(identityPath, { force: true });
+    let runnerIdentity;
+    // Wrapper exit is not runner exit, so only a reported runner in this namespace may be signalled.
+    const terminateBeforeProceed = (pid) => !launcher
+        ? terminateRunnerBeforeProceed(pid)
+        : runnerIdentity !== undefined && runnerIdentity.pidNamespaceScope === currentPidNamespaceScope() && terminateRunnerBeforeProceed(runnerIdentity.pid);
+    const adoptRunnerIdentity = (pid, pidNamespaceScope) => {
+        if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid < 1)
+            return `Async runner reported an invalid process identity in '${launchAsyncDir}'.`;
+        runnerIdentity = { pid, ...(typeof pidNamespaceScope === "string" ? { pidNamespaceScope } : {}) };
+        try {
+            const status = JSON.parse(fs.readFileSync(initialStatusPath, "utf-8"));
+            writePrivateAtomicJson(initialStatusPath, { ...status, pid, ...(runnerIdentity.pidNamespaceScope !== undefined ? { pidNamespaceScope: runnerIdentity.pidNamespaceScope } : {}) });
+            return undefined;
+        }
+        catch (error) {
+            return `Failed to record async runner identity: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    };
     const logPaths = resolveAsyncRunnerLogPaths(launchConfig);
     let stdoutFd;
     let stderrFd;
@@ -481,7 +517,8 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
             delete runnerEnv[SUBAGENT_PARENT_SESSION_ENV];
         else
             runnerEnv[SUBAGENT_PARENT_SESSION_ENV] = launchParentSessionId;
-        const proc = spawn(command, args, {
+        const [spawnCommand, ...spawnArgs] = launcher ? [...launcher.argv, command, ...args] : [command, ...args];
+        const proc = spawn(spawnCommand, spawnArgs, {
             cwd,
             ...backgroundProcessOptions(),
             stdio: ["ignore", stdoutFd ?? "ignore", stderrFd ?? "ignore"],
@@ -507,6 +544,18 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
                 const runId = launch.id;
                 if (typeof asyncDir !== "string" || typeof runId !== "string")
                     return;
+                if (launcher) {
+                    try {
+                        writePrivateAtomicJson(path.join(asyncDir, "launcher-close.json"), { version: 1, runId, runnerProcessInstanceId, closeObservedAt: Date.now(), exitCode, signal, ...(runnerIdentity ? { runnerPid: runnerIdentity.pid } : {}) });
+                    }
+                    catch {
+                        // Diagnostic only; process-terminal proof stays authoritative.
+                    }
+                    // The runner may outlive its wrapper; only a confirmed-dead runner in this pid namespace finalizes here,
+                    // otherwise status-pid reconciliation does it later.
+                    if (!runnerIdentity || runnerIdentity.pidNamespaceScope !== currentPidNamespaceScope() || checkPidLiveness(runnerIdentity.pid, process.kill, runnerIdentity.pidNamespaceScope !== undefined) !== "dead")
+                        return;
+                }
                 finalizeProcessTerminal(asyncDir, runId, {
                     processInstanceId: runnerProcessInstanceId,
                     closeObservedAt: Date.now(),
@@ -566,8 +615,7 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
         try {
             writePrivateAtomicJson(initialStatusPath, {
                 ...initialStatus,
-                pid: proc.pid,
-                pidNamespaceScope: currentPidNamespaceScope(),
+                ...(launcher ? {} : { pid: proc.pid, pidNamespaceScope: currentPidNamespaceScope() }),
                 processTerminal: { version: 1, state: "pending", runId: initialStatus.runId, runnerProcessInstanceId },
             });
             // Aggregate waits must see the launch before the runner's first status update.
@@ -577,7 +625,7 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
             const message = `Failed to persist initial async status: ${error instanceof Error ? error.message : String(error)}`;
             if (launchAsyncDir)
                 persistPreProceedStartupFailure(launchAsyncDir, launchRunId, runnerProcessInstanceId, launchSessionId, launchCompletionOwnerId, message);
-            const terminationObserved = terminateRunnerBeforeProceed(proc.pid);
+            const terminationObserved = terminateBeforeProceed(proc.pid);
             return { pid: proc.pid, runnerProcessInstanceId, error: message, terminationObserved, startupDidNotProceed: true };
         }
         try {
@@ -589,7 +637,7 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
             const message = `Failed to establish async runner lifecycle sidecar: ${error instanceof Error ? error.message : String(error)}`;
             if (launchAsyncDir)
                 persistPreProceedStartupFailure(launchAsyncDir, launchRunId, runnerProcessInstanceId, launchSessionId, launchCompletionOwnerId, message);
-            const terminationObserved = terminateRunnerBeforeProceed(proc.pid);
+            const terminationObserved = terminateBeforeProceed(proc.pid);
             return { pid: proc.pid, runnerProcessInstanceId, error: message, terminationObserved, startupDidNotProceed: true };
         }
         try {
@@ -599,9 +647,31 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
             const message = `Failed to establish async runner capacity ownership: ${error instanceof Error ? error.message : String(error)}`;
             if (launchAsyncDir)
                 persistPreProceedStartupFailure(launchAsyncDir, launchRunId, runnerProcessInstanceId, launchSessionId, launchCompletionOwnerId, message);
-            const terminationObserved = terminateRunnerBeforeProceed(proc.pid);
+            const terminationObserved = terminateBeforeProceed(proc.pid);
             return { pid: proc.pid, runnerProcessInstanceId, error: message, terminationObserved, startupDidNotProceed: true };
         }
+        if (identityPath && launchBarrierToken && startupProceedPath) {
+            proc.unref();
+            const fail = (message) => {
+                if (launchAsyncDir)
+                    persistPreProceedStartupFailure(launchAsyncDir, launchRunId, runnerProcessInstanceId, launchSessionId, launchCompletionOwnerId, message);
+                return { ...(runnerIdentity ? { pid: runnerIdentity.pid } : {}), runnerProcessInstanceId, error: message, terminationObserved: terminateBeforeProceed(proc.pid), startupDidNotProceed: true };
+            };
+            return waitForRunnerStartup(identityPath, "identified", RUNNER_STARTUP_TIMEOUT_MS, launchBarrierToken, processClosed).then((identified) => {
+                if (identified.ok === false)
+                    return fail(identified.error);
+                const identityError = adoptRunnerIdentity(identified.pid, identified.pidNamespaceScope);
+                if (identityError)
+                    return fail(identityError);
+                try {
+                    writeRunnerStartupControl(startupProceedPath, { action: "proceed", token: launchBarrierToken });
+                }
+                catch (error) {
+                    return fail(`Failed to authorize async runner startup: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                return { pid: identified.pid, runnerProcessInstanceId };
+            });
+        }
         if (launchBarrierToken && startupProceedPath) {
             try {
                 writeRunnerStartupControl(startupProceedPath, { action: "proceed", token: launchBarrierToken });
@@ -610,7 +680,7 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
                 const message = `Failed to authorize async runner startup: ${error instanceof Error ? error.message : String(error)}`;
                 if (launchAsyncDir)
                     persistPreProceedStartupFailure(launchAsyncDir, launchRunId, runnerProcessInstanceId, launchSessionId, launchCompletionOwnerId, message);
-                const terminationObserved = terminateRunnerBeforeProceed(proc.pid);
+                const terminationObserved = terminateBeforeProceed(proc.pid);
                 return { pid: proc.pid, runnerProcessInstanceId, error: message, terminationObserved, startupDidNotProceed: true };
             }
         }
@@ -620,7 +690,10 @@ function spawnRunner(cfg, suffix, cwd, initialStatus, initialStatusPath, launchP
                 if (launchAsyncDir)
                     persistPreProceedStartupFailure(launchAsyncDir, launchRunId, runnerProcessInstanceId, launchSessionId, launchCompletionOwnerId, message);
             };
-            return completeRunnerStartupHandshake(startupPath, startupAckPath, startupConfirmPath, startupProceedPath, proc, processClosed, () => observedProcessExit ?? (proc.exitCode !== null || proc.signalCode !== null ? { exitCode: proc.exitCode, signal: proc.signalCode } : undefined), runnerProcessInstanceId, persistStartupFailure);
+            const handshake = completeRunnerStartupHandshake(startupPath, startupAckPath, startupConfirmPath, startupProceedPath, proc, processClosed, () => observedProcessExit ?? (proc.exitCode !== null || proc.signalCode !== null ? { exitCode: proc.exitCode, signal: proc.signalCode } : undefined), runnerProcessInstanceId, persistStartupFailure, launcher ? { adopt: adoptRunnerIdentity, terminate: () => terminateBeforeProceed(proc.pid) } : undefined);
+            if (!launcher)
+                return handshake;
+            return handshake.then(({ pid: _wrapperPid, ...result }) => ({ ...result, ...(runnerIdentity ? { pid: runnerIdentity.pid } : {}) }));
         }
         return { pid: proc.pid, runnerProcessInstanceId };
     }
@@ -660,6 +733,14 @@ class AsyncStartValidationError extends Error {
 }
 export function buildAsyncRunnerSteps(id, params) {
     const { chain, agents, ctx, cwd, sessionFilesByFlatIndex, thinkingOverridesByFlatIndex, maxSubagentDepth, worktreeBaseDir, worktreeProvider, worktreeBranchPrefix, asyncDir, } = params;
+    // One runner hosts every new step, so they share one launcher or none. Covers initial chains and
+    // appends to a running runner; the attached root runs in its own runner.
+    const stepLaunchers = [...new Set(chain.flatMap(getStepAgents))].map((name) => ({ name, launcher: agents.find((agent) => agent.name === name)?.launcher }));
+    const launcherNames = new Set(stepLaunchers.map(({ launcher }) => launcher));
+    if (launcherNames.size > 1) {
+        return { error: `Every agent in one background runner must use the same launcher or none: ${stepLaunchers.map(({ name, launcher }) => `${name} (${launcher ?? "none"})`).join(", ")}.` };
+    }
+    const launcher = [...launcherNames][0];
     const launchParentSessionId = ctx.parentSessionId ?? ctx.currentSessionId;
     const outputBaseDir = params.outputBaseDir;
     const resultMode = params.resultMode ?? "chain";
@@ -742,6 +823,9 @@ export function buildAsyncRunnerSteps(id, params) {
         const machineUnsupported = formatHerdrMachineRunnerUnsupported({ machine: requestedMachine, agentName: a.name, runnerType: a.runner?.type, adapter: a.runner?.type === "external-cli" ? a.runner.adapter : undefined, worktree: s.worktree });
         if (machineUnsupported)
             throw new AsyncStartValidationError(machineUnsupported);
+        const launcherError = runnerLauncherPlacementError(a, requestedMachine);
+        if (launcherError)
+            throw new AsyncStartValidationError(launcherError);
         const registeredExtensions = resolveRequiredChildExtensions(ctx.parentSessionId ?? ctx.currentSessionId ?? undefined);
         try {
             assertRequiredChildExtensionsAdmitted([params.requiredExtensions, ctx.childRuntime?.requiredExtensions, registeredExtensions], { agent: a.name, runnerType: a.runner?.type, machine: requestedMachine });
@@ -917,6 +1001,7 @@ export function buildAsyncRunnerSteps(id, params) {
         }
         return {
             parentSessionId: launchParentSessionId,
+            ...(ctx.parentSessionFile ? { parentSessionFile: ctx.parentSessionFile } : {}),
             permissionRules,
             ...(params.capabilityCeiling ? { capabilityCeiling: params.capabilityCeiling } : {}),
             ...(runFanoutPath ? { runFanoutPath } : {}),
@@ -1092,6 +1177,7 @@ export function buildAsyncRunnerSteps(id, params) {
         const steps = params.attachRoot
             ? [{
                     parentSessionId: launchParentSessionId,
+                    ...(ctx.parentSessionFile ? { parentSessionFile: ctx.parentSessionFile } : {}),
                     agent: params.attachRoot.agent,
                     task: "",
                     label: params.attachRoot.label ?? `Attached root ${params.attachRoot.runId}`,
@@ -1122,7 +1208,7 @@ export function buildAsyncRunnerSteps(id, params) {
                 seen.set(task.outputPath, { index, agent: task.agent });
             }
         }
-        return { steps: steps, runnerCwd, workflowGraph, eventChain: graphChain, ...(originalTask !== undefined ? { originalTask } : {}) };
+        return { steps: steps, runnerCwd, workflowGraph, eventChain: graphChain, ...(originalTask !== undefined ? { originalTask } : {}), ...(launcher !== undefined ? { launcher } : {}) };
     }
     catch (error) {
         if (error instanceof UnavailableSubagentSkillError || error instanceof AsyncStartValidationError)
@@ -1141,6 +1227,11 @@ export function executeAsyncChain(id, params) {
     });
     if (acceptanceErrors.length > 0)
         return formatAsyncStartError(resultMode, acceptanceErrors.join(" "));
+    // Refuse an undefined launcher before the run directory exists and before step building can write progress files.
+    const undefinedLauncher = chain.flatMap(getStepAgents).map((name) => agents.find((agent) => agent.name === name)?.launcher)
+        .find((name) => name !== undefined && !lookupRunnerLauncher(ctx.runnerLaunchers, name));
+    if (undefinedLauncher !== undefined)
+        return formatAsyncStartError(resultMode, `Launcher '${undefinedLauncher}' used by this ${resultMode} is not defined in runnerLaunchers in the user subagent config.`);
     const capabilityCeiling = params.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
     const inheritedNestedRoute = inheritedNestedRouteOf(ctx.childRuntime);
     const nestedAddress = inheritedNestedRoute ? inheritedNestedParentAddressOf(ctx.childRuntime) : undefined;
@@ -1208,6 +1299,7 @@ export function executeAsyncChain(id, params) {
         return formatAsyncStartError(resultMode, built.error);
     }
     const { steps, runnerCwd, workflowGraph, eventChain } = built;
+    const launcher = built.launcher === undefined ? undefined : lookupRunnerLauncher(ctx.runnerLaunchers, built.launcher);
     const deadlineAt = params.timeoutMs !== undefined ? Date.now() + params.timeoutMs : undefined;
     const initialUsageBudget = usageBudgetState(params.usageBudget, undefined);
     let childTargetIndex = 0;
@@ -1250,9 +1342,9 @@ export function executeAsyncChain(id, params) {
         fs.rmSync(asyncDir, { recursive: true, force: true });
         return formatAsyncStartError(resultMode, `Failed to record required child extensions: ${error instanceof Error ? error.message : String(error)}`);
     }
-    let spawnResult = {};
+    let spawnResultOrPromise = {};
     try {
-        spawnResult = spawnRunner({
+        spawnResultOrPromise = spawnRunner({
             id,
             steps,
             resultPath: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : resultFilePath(DIRS.results, id),
@@ -1298,6 +1390,7 @@ export function executeAsyncChain(id, params) {
                 depth: nestedAddress.depth,
                 path: nestedAddress.path,
             } : undefined,
+            ...(launcher ? { launcher } : {}),
         }, id, runnerCwd, {
             lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
             runId: id,
@@ -1310,6 +1403,7 @@ export function executeAsyncChain(id, params) {
             currentStep: 0,
             chainStepCount: eventChain.length,
             ...(initialParallelGroups.length ? { parallelGroups: initialParallelGroups } : {}),
+            ...(launcher ? { launcher } : {}),
             steps: initialStatusSteps,
         }, path.join(asyncDir, "status.json"), launchParentSessionId, (proof) => emitProcessTerminalEvent(ctx, proof), (runnerProcessInstanceId) => params.activeAsyncCapacity?.markStarted(runnerProcessInstanceId));
     }
@@ -1318,127 +1412,131 @@ export function executeAsyncChain(id, params) {
         const message = error instanceof Error ? error.message : String(error);
         return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': ${message}`);
     }
-    if (spawnResult.error) {
-        if (spawnResult.startupDidNotProceed) {
-            if (!spawnResult.runnerProcessInstanceId || params.activeAsyncCapacity?.rollbackBeforeRunnerProceed(spawnResult.runnerProcessInstanceId) !== true)
+    // A launcher run's spawn resolves once the runner reports its identity.
+    const finishSpawnResult = (spawnResult) => {
+        if (spawnResult.error) {
+            if (spawnResult.startupDidNotProceed) {
+                if (!spawnResult.runnerProcessInstanceId || params.activeAsyncCapacity?.rollbackBeforeRunnerProceed(spawnResult.runnerProcessInstanceId) !== true)
+                    params.activeAsyncCapacity?.rollback();
+            }
+            else if (!spawnResult.pid || !spawnResult.runnerProcessInstanceId)
                 params.activeAsyncCapacity?.rollback();
+            else
+                params.activeAsyncCapacity?.markStarted(spawnResult.runnerProcessInstanceId);
+            return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': ${spawnResult.error}`);
         }
-        else if (!spawnResult.pid || !spawnResult.runnerProcessInstanceId)
+        if (!spawnResult.pid || !spawnResult.runnerProcessInstanceId) {
             params.activeAsyncCapacity?.rollback();
-        else
-            params.activeAsyncCapacity?.markStarted(spawnResult.runnerProcessInstanceId);
-        return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': ${spawnResult.error}`);
-    }
-    if (!spawnResult.pid || !spawnResult.runnerProcessInstanceId) {
-        params.activeAsyncCapacity?.rollback();
-        return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': runner identity unavailable`);
-    }
-    if (spawnResult.pid) {
-        const eventFirstStep = eventChain[0];
-        if (!eventFirstStep) {
-            return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': event chain has no steps`);
-        }
-        const firstAgents = isParallelStep(eventFirstStep)
-            ? eventFirstStep.parallel.map((t) => t.agent)
-            : isDynamicParallelStep(eventFirstStep)
-                ? [eventFirstStep.parallel.agent]
-                : [eventFirstStep.agent];
-        const firstTask = isParallelStep(eventFirstStep)
-            ? eventFirstStep.parallel[0]?.task
-            : isDynamicParallelStep(eventFirstStep)
-                ? eventFirstStep.parallel.task
-                : eventFirstStep.task;
-        const workflowGoal = params.goal ?? (params.task?.trim() || firstTask);
-        const parallelGroups = [];
-        const flatAgents = [];
-        let flatStepStart = 0;
-        for (let stepIndex = 0; stepIndex < eventChain.length; stepIndex++) {
-            const step = eventChain[stepIndex];
-            if (isParallelStep(step)) {
-                parallelGroups.push({ start: flatStepStart, count: step.parallel.length, stepIndex });
-                flatAgents.push(...step.parallel.map((task) => task.agent));
-                flatStepStart += step.parallel.length;
-            }
-            else if (isDynamicParallelStep(step)) {
-                parallelGroups.push({ start: flatStepStart, count: 1, stepIndex });
-                flatAgents.push(step.parallel.agent);
-                flatStepStart++;
+            return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': runner identity unavailable`);
+        }
+        if (spawnResult.pid) {
+            const eventFirstStep = eventChain[0];
+            if (!eventFirstStep) {
+                return formatAsyncStartError(resultMode, `Failed to start async ${resultMode} '${id}': event chain has no steps`);
             }
-            else {
-                flatAgents.push(step.agent);
-                flatStepStart++;
+            const firstAgents = isParallelStep(eventFirstStep)
+                ? eventFirstStep.parallel.map((t) => t.agent)
+                : isDynamicParallelStep(eventFirstStep)
+                    ? [eventFirstStep.parallel.agent]
+                    : [eventFirstStep.agent];
+            const firstTask = isParallelStep(eventFirstStep)
+                ? eventFirstStep.parallel[0]?.task
+                : isDynamicParallelStep(eventFirstStep)
+                    ? eventFirstStep.parallel.task
+                    : eventFirstStep.task;
+            const workflowGoal = params.goal ?? (params.task?.trim() || firstTask);
+            const parallelGroups = [];
+            const flatAgents = [];
+            let flatStepStart = 0;
+            for (let stepIndex = 0; stepIndex < eventChain.length; stepIndex++) {
+                const step = eventChain[stepIndex];
+                if (isParallelStep(step)) {
+                    parallelGroups.push({ start: flatStepStart, count: step.parallel.length, stepIndex });
+                    flatAgents.push(...step.parallel.map((task) => task.agent));
+                    flatStepStart += step.parallel.length;
+                }
+                else if (isDynamicParallelStep(step)) {
+                    parallelGroups.push({ start: flatStepStart, count: 1, stepIndex });
+                    flatAgents.push(step.parallel.agent);
+                    flatStepStart++;
+                }
+                else {
+                    flatAgents.push(step.agent);
+                    flatStepStart++;
+                }
             }
-        }
-        if (inheritedNestedRoute && nestedAddress) {
-            const now = Date.now();
-            try {
-                writeNestedEvent(inheritedNestedRoute, {
-                    type: "subagent.nested.started",
-                    ts: now,
-                    parentRunId: nestedAddress.parentRunId,
-                    parentStepIndex: nestedAddress.parentStepIndex,
-                    child: {
-                        id,
+            if (inheritedNestedRoute && nestedAddress) {
+                const now = Date.now();
+                try {
+                    writeNestedEvent(inheritedNestedRoute, {
+                        type: "subagent.nested.started",
+                        ts: now,
                         parentRunId: nestedAddress.parentRunId,
                         parentStepIndex: nestedAddress.parentStepIndex,
-                        depth: nestedAddress.depth,
-                        path: nestedAddress.path,
-                        asyncDir,
-                        pid: spawnResult.pid,
-                        ownerIntercomTarget: ctx.childRuntime?.intercomSessionName,
-                        leafIntercomTarget: childIntercomTargets?.[0],
-                        intercomTarget: childIntercomTargets?.[0],
-                        ownerState: "live",
-                        mode: resultMode,
-                        state: "running",
-                        agent: firstAgents[0],
-                        agents: flatAgents,
-                        chainStepCount: eventChain.length,
-                        parallelGroups,
-                        ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs, deadlineAt } : {}),
-                        startedAt: now,
-                        lastUpdate: now,
-                        ...(capabilityCeiling ? { capabilityCeiling } : {}),
-                    },
-                });
-            }
-            catch (error) {
-                console.error("Failed to emit nested async start event:", error);
+                        child: {
+                            id,
+                            parentRunId: nestedAddress.parentRunId,
+                            parentStepIndex: nestedAddress.parentStepIndex,
+                            depth: nestedAddress.depth,
+                            path: nestedAddress.path,
+                            asyncDir,
+                            pid: spawnResult.pid,
+                            ownerIntercomTarget: ctx.childRuntime?.intercomSessionName,
+                            leafIntercomTarget: childIntercomTargets?.[0],
+                            intercomTarget: childIntercomTargets?.[0],
+                            ownerState: "live",
+                            mode: resultMode,
+                            state: "running",
+                            agent: firstAgents[0],
+                            agents: flatAgents,
+                            chainStepCount: eventChain.length,
+                            parallelGroups,
+                            ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs, deadlineAt } : {}),
+                            startedAt: now,
+                            lastUpdate: now,
+                            ...(capabilityCeiling ? { capabilityCeiling } : {}),
+                        },
+                    });
+                }
+                catch (error) {
+                    console.error("Failed to emit nested async start event:", error);
+                }
             }
+            ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
+                lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+                id,
+                pid: spawnResult.pid,
+                sessionId: ctx.currentSessionId,
+                completionOwnerId: ctx.completionOwnerId ?? currentCompletionOwnerId(),
+                mode: resultMode,
+                agent: firstAgents[0],
+                agents: flatAgents,
+                task: firstTask?.trim() ? PROMPT_REDACTED : undefined,
+                goal: workflowGoal?.trim() ? PROMPT_REDACTED : undefined,
+                chain: eventChain.map((s) => isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : isDynamicParallelStep(s) ? `expand:${s.parallel.agent}` : s.agent),
+                chainStepCount: eventChain.length,
+                parallelGroups,
+                workflowGraph,
+                cwd: runnerCwd,
+                asyncDir,
+                ...(sessionRoot ? { sessionRoot } : {}),
+                ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs, deadlineAt } : {}),
+                ...(initialUsageBudget ? { usageBudget: initialUsageBudget } : {}),
+                ...(capabilityCeiling ? { capabilityCeiling } : {}),
+                ...(params.parentWorkflowRunId ? { parentWorkflowRunId: params.parentWorkflowRunId } : {}),
+                ...(params.workflowKey ? { workflowKey: params.workflowKey } : {}),
+                nestedRoute,
+            });
         }
-        ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
-            lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
-            id,
-            pid: spawnResult.pid,
-            sessionId: ctx.currentSessionId,
-            completionOwnerId: ctx.completionOwnerId ?? currentCompletionOwnerId(),
-            mode: resultMode,
-            agent: firstAgents[0],
-            agents: flatAgents,
-            task: firstTask?.trim() ? PROMPT_REDACTED : undefined,
-            goal: workflowGoal?.trim() ? PROMPT_REDACTED : undefined,
-            chain: eventChain.map((s) => isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : isDynamicParallelStep(s) ? `expand:${s.parallel.agent}` : s.agent),
-            chainStepCount: eventChain.length,
-            parallelGroups,
-            workflowGraph,
-            cwd: runnerCwd,
-            asyncDir,
-            ...(sessionRoot ? { sessionRoot } : {}),
-            ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs, deadlineAt } : {}),
-            ...(initialUsageBudget ? { usageBudget: initialUsageBudget } : {}),
-            ...(capabilityCeiling ? { capabilityCeiling } : {}),
-            ...(params.parentWorkflowRunId ? { parentWorkflowRunId: params.parentWorkflowRunId } : {}),
-            ...(params.workflowKey ? { workflowKey: params.workflowKey } : {}),
-            nestedRoute,
-        });
-    }
-    const chainDesc = chain
-        .map((s) => isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : isDynamicParallelStep(s) ? `expand:${s.parallel.agent}` : s.agent)
-        .join(" -> ");
-    return {
-        content: [{ type: "text", text: formatAsyncStartedMessage(`Async ${resultMode}: ${chainDesc} [${id}]`, ctx.interactive === true) }],
-        details: { mode: resultMode, runId: id, results: [], asyncId: id, asyncDir, workflowGraph, ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(params.parentWorkflowRunId ? { parentWorkflowRunId: params.parentWorkflowRunId } : {}), ...(params.workflowKey ? { workflowKey: params.workflowKey } : {}), ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs, deadlineAt } : {}), ...(params.toolBudget ? { toolBudget: params.toolBudget } : {}), ...(initialUsageBudget ? { usageBudget: initialUsageBudget } : {}) },
+        const chainDesc = chain
+            .map((s) => isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : isDynamicParallelStep(s) ? `expand:${s.parallel.agent}` : s.agent)
+            .join(" -> ");
+        return {
+            content: [{ type: "text", text: formatAsyncStartedMessage(`Async ${resultMode}: ${chainDesc} [${id}]`, ctx.interactive === true) }],
+            details: { mode: resultMode, runId: id, results: [], asyncId: id, asyncDir, workflowGraph, ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(params.parentWorkflowRunId ? { parentWorkflowRunId: params.parentWorkflowRunId } : {}), ...(params.workflowKey ? { workflowKey: params.workflowKey } : {}), ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs, deadlineAt } : {}), ...(params.toolBudget ? { toolBudget: params.toolBudget } : {}), ...(initialUsageBudget ? { usageBudget: initialUsageBudget } : {}) },
+        };
     };
+    return spawnResultOrPromise instanceof Promise ? spawnResultOrPromise.then(finishSpawnResult) : finishSpawnResult(spawnResultOrPromise);
 }
 /**
  * Execute a single agent asynchronously
@@ -1510,6 +1608,10 @@ export function executeAsyncSingle(id, params) {
     const machineUnsupported = formatHerdrMachineRunnerUnsupported({ machine: requestedMachine, agentName: agentConfig.name, runnerType: agentConfig.runner?.type, adapter: agentConfig.runner?.type === "external-cli" ? agentConfig.runner.adapter : undefined, worktree: params.worktree });
     if (machineUnsupported)
         return formatAsyncStartError("single", machineUnsupported);
+    const resolvedLauncher = resolveAgentRunnerLauncher(agentConfig, ctx.runnerLaunchers, requestedMachine);
+    if (resolvedLauncher.error)
+        return formatAsyncStartError("single", resolvedLauncher.error);
+    const launcher = resolvedLauncher.launcher;
     const registeredExtensions = resolveRequiredChildExtensions(ctx.parentSessionId ?? ctx.currentSessionId ?? undefined);
     try {
         assertRequiredChildExtensionsAdmitted([params.requiredExtensions, ctx.childRuntime?.requiredExtensions, registeredExtensions], { agent: agentConfig.name, runnerType: agentConfig.runner?.type, machine: requestedMachine });
@@ -1774,6 +1876,7 @@ export function executeAsyncSingle(id, params) {
         ...(params.context ? { context: params.context } : {}),
         ...(params.intercomBridge !== undefined ? { intercomBridge: params.intercomBridge } : {}),
         ...(params.baseRef !== undefined ? { baseRef: params.baseRef } : {}),
+        ...(launcher ? { launcher: launcher.name } : {}),
         ...(deadlineAt !== undefined ? { absoluteDeadlineAt: deadlineAt } : {}),
         ...(resolvedToolBudget.budget ? { initialToolBudget: resolvedToolBudget.budget } : {}),
         maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, recoveryAgentConfig.maxSubagentDepth),
@@ -1799,9 +1902,11 @@ export function executeAsyncSingle(id, params) {
     try {
         spawnResultOrPromise = spawnRunner({
             id,
+            ...(params.toolCallId ? { toolCallId: params.toolCallId } : {}),
             steps: [
                 {
                     parentSessionId: launchParentSessionId,
+                    ...(ctx.parentSessionFile ? { parentSessionFile: ctx.parentSessionFile } : {}),
                     permissionRules,
                     ...(capabilityCeiling ? { capabilityCeiling } : {}),
                     agent,
@@ -1904,6 +2009,7 @@ export function executeAsyncSingle(id, params) {
             ...(lane ? { lane } : {}),
             ...(params.revivalLease ? { revivalLease: params.revivalLease } : {}),
             nestedRoute: nestedRoute ?? inheritedNestedRoute,
+            ...(launcher ? { launcher } : {}),
             nestedSelf: inheritedNestedRoute && nestedAddress ? {
                 parentRunId: nestedAddress.parentRunId,
                 parentStepIndex: nestedAddress.parentStepIndex,
@@ -1916,12 +2022,14 @@ export function executeAsyncSingle(id, params) {
             ...(ctx.currentSessionId ? { sessionId: ctx.currentSessionId } : {}),
             ...(initialCompletionOwnerId ? { completionOwnerId: initialCompletionOwnerId } : {}),
             mode: "single",
+            ...(params.toolCallId ? { toolCallId: params.toolCallId } : {}),
             state: "running",
             startedAt: initialStatusAt,
             lastUpdate: initialStatusAt,
             currentStep: 0,
             chainStepCount: 1,
             ...(lane ? { lane } : {}),
+            ...(launcher ? { launcher } : {}),
             steps: [{ agent, status: "pending", ...(lane ? { lane } : {}), ...(model ? { model } : {}), ...(contextLimit !== undefined ? { contextLimit } : {}) }],
         }, path.join(asyncDir, "status.json"), launchParentSessionId, (proof) => emitProcessTerminalEvent(ctx, proof), (runnerProcessInstanceId) => params.activeAsyncCapacity?.markStarted(runnerProcessInstanceId), params.requestedCwd ?? runnerCwd);
     }
@@ -1990,6 +2098,7 @@ export function executeAsyncSingle(id, params) {
                 sessionId: ctx.currentSessionId,
                 completionOwnerId: ctx.completionOwnerId ?? currentCompletionOwnerId(),
                 mode: "single",
+                ...(params.toolCallId ? { toolCallId: params.toolCallId } : {}),
                 agent,
                 task: task?.trim() ? PROMPT_REDACTED : undefined,
                 goal: (params.goal ?? task).trim() ? PROMPT_REDACTED : undefined,
@@ -2008,7 +2117,7 @@ export function executeAsyncSingle(id, params) {
         }
         return {
             content: [{ type: "text", text: formatAsyncStartedMessage(`Async: ${agent} [${id}]`, ctx.interactive === true) }],
-            details: { mode: "single", runId: id, results: [], asyncId: id, asyncDir, launchContractDigest, launchResolvedExtensions, ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(params.context ? { context: params.context } : {}), ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt } : {}), ...(params.toolBudget ? { toolBudget: resolvedToolBudget.budget ?? params.toolBudget } : {}), ...(initialUsageBudget ? { usageBudget: initialUsageBudget } : {}) },
+            details: { mode: "single", runId: id, ...(params.toolCallId ? { toolCallId: params.toolCallId } : {}), results: [], asyncId: id, asyncDir, launchContractDigest, launchResolvedExtensions, ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(params.context ? { context: params.context } : {}), ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt } : {}), ...(params.toolBudget ? { toolBudget: resolvedToolBudget.budget ?? params.toolBudget } : {}), ...(initialUsageBudget ? { usageBudget: initialUsageBudget } : {}) },
         };
     };
     return spawnResultOrPromise instanceof Promise ? spawnResultOrPromise.then(finishSpawnResult) : finishSpawnResult(spawnResultOrPromise);