From df5fa1e633800cb7492eaaab45f43cf0a00fab66 Mon Sep 17 00:00:00 2001
From: Justin Giancola <justin.giancola@gmail.com>
Date: Mon, 6 Jul 2026 12:31:43 -0400
Subject: [PATCH 1/3] feat(cmux): guarded launch scripts + async launch
 verify/retry loop

Launch commands typed into a freshly split pane race against the pane
shell's own startup: direnv/devenv/zsh init can flush the tty input queue
and silently discard the typeahead (repro'd 100% in a devenv repo with the
default 500ms delay). A fixed post-split delay can never be reliable.

Instead, verify and retry:

- sendLongCommand() now writes launch scripts with an idempotency guard as
  the first executable lines: the script exits if '<script>.started' exists
  and creates the marker before running the command. Resending the
  'bash <script>' line is therefore always a safe no-op once started.
- New runLaunchVerifyLoop(): after the initial send, polls for the marker
  on a backoff schedule (2s, 4s, 8s, 15s, 30s + 2s grace) and resends the
  launch line while the marker is absent. Bounded retries; abortable via
  AbortSignal (respects the /reload cleanup pattern); all state is
  per-spawn so N concurrent launches stay independent.
- tmux belt-and-suspenders: before resending, check
  '#{pane_current_command}' and skip the resend unless the pane is sitting
  at an idle shell (prevents typing into the subagent's TUI editor or a
  user-started program). Other backends use the marker check only.
- Verification is opt-in via options.verify with an onResult callback
  reporting verified / failed (marker-missing | surface-gone) / aborted.

Part of the subagent spawn race fix (TODO-4b7117b7).
---
 pi-extension/subagents/cmux.ts | 233 +++++++++++++++++++++++++++++++--
 1 file changed, 224 insertions(+), 9 deletions(-)

diff --git a/pi-extension/subagents/cmux.ts b/pi-extension/subagents/cmux.ts
index d0312fdf..a6dc268a 100644
--- a/pi-extension/subagents/cmux.ts
+++ b/pi-extension/subagents/cmux.ts
@@ -1063,6 +1063,194 @@ export function sendEscape(surface: string): void {
   zellijActionSync(["write", "27"], surface);
 }
 
+// ── Launch verification ──
+//
+// Typing the launch line into a freshly created pane races against the pane
+// shell's own startup (direnv/devenv/zsh init can flush the tty input queue,
+// silently discarding the typed command). A fixed post-split delay can never
+// be reliable, so launches are verified and retried instead:
+//
+//   1. The launch script begins with an idempotency guard: it creates a
+//      `<script>.started` marker before running the real command, and exits
+//      immediately if the marker already exists. Resending `bash '<script>'`
+//      is therefore always safe — duplicate executions are no-ops.
+//   2. After the initial send, an async verify loop polls for the marker on a
+//      backoff schedule and resends the launch line while it is absent.
+//
+// See https://github.com/HazAT/pi-interactive-subagents — subagent spawn race.
+
+/** Backoff schedule (ms between marker checks) for the launch verify loop. */
+export const DEFAULT_LAUNCH_VERIFY_SCHEDULE_MS = [2000, 4000, 8000, 15000, 30000];
+
+/** Extra wait after the last resend before declaring the launch failed. */
+const LAUNCH_VERIFY_FINAL_GRACE_MS = 2000;
+
+export interface LaunchVerifyResult {
+  status: "verified" | "failed" | "aborted";
+  /** Number of times the launch line was resent (not counting the initial send). */
+  resends: number;
+  elapsedMs: number;
+  /** Set when status is "failed". */
+  reason?: "marker-missing" | "surface-gone";
+}
+
+export interface LaunchVerifyHooks {
+  /** Whether the `<script>.started` marker exists (launch script began executing). */
+  markerExists: () => boolean;
+  /** Resend the launch line. Should throw if the surface is gone. */
+  resend: () => void;
+  /**
+   * Optional pre-resend check. Return false to skip resending this round
+   * (e.g. the pane is no longer an idle shell, so typing into it would land
+   * in some other program's input). The loop keeps polling either way.
+   */
+  shouldResend?: () => boolean;
+  /** Injectable sleep for tests. Resolves false when aborted. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<boolean>;
+}
+
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve(false);
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve(true);
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      resolve(false);
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Path of the idempotency marker created by a guarded launch script. */
+export function launchMarkerPath(scriptPath: string): string {
+  return `${scriptPath}.started`;
+}
+
+/**
+ * Build the guarded launch script content for sendLongCommand.
+ * The guard lines must be the first executable lines so that resending
+ * `bash '<script>'` is always a no-op once the script has started.
+ */
+export function buildLaunchScript(
+  command: string,
+  options: { scriptPath: string; scriptPreamble?: string },
+): string {
+  const marker = shellEscape(launchMarkerPath(options.scriptPath));
+  const scriptParts = ["#!/bin/bash"];
+  if (options?.scriptPreamble) {
+    scriptParts.push(options.scriptPreamble.trimEnd());
+  }
+  scriptParts.push(
+    "# Idempotency guard: resending `bash <script>` is a no-op once started.",
+    `[ -e ${marker} ] && exit 0`,
+    `: > ${marker}`,
+  );
+  scriptParts.push(command);
+  return scriptParts.join("\n") + "\n";
+}
+
+/** Foreground commands that indicate the pane is sitting at an idle shell. */
+const IDLE_SHELL_COMMANDS = new Set([
+  "bash",
+  "zsh",
+  "fish",
+  "sh",
+  "dash",
+  "ksh",
+  "tcsh",
+  "csh",
+  "nu",
+  "pwsh",
+]);
+
+/**
+ * Whether a tmux `#{pane_current_command}` value looks like an idle shell
+ * that is safe to type a launch line into.
+ */
+export function isIdleShellCommand(command: string): boolean {
+  const name = basename(command.trim()).replace(/^-/, "").toLowerCase();
+  return IDLE_SHELL_COMMANDS.has(name);
+}
+
+/**
+ * tmux-only belt-and-suspenders: only resend while the pane's foreground
+ * process is an idle shell. If it is anything else (the subagent's TUI, a
+ * program the user started, shell init children), typing would be misdirected.
+ * If the pane is gone the check returns true so the resend attempt surfaces
+ * the error and ends the loop with "surface-gone".
+ */
+function tmuxPaneIdleShellCheck(surface: string): () => boolean {
+  return () => {
+    try {
+      const current = execFileSync(
+        "tmux",
+        ["display-message", "-p", "-t", surface, "#{pane_current_command}"],
+        { encoding: "utf8" },
+      ).trim();
+      return isIdleShellCommand(current);
+    } catch {
+      return true;
+    }
+  };
+}
+
+/**
+ * Poll for the launch marker on a backoff schedule, resending the launch line
+ * while it is absent. All state is local to this call — safe under N
+ * concurrent launches (each has its own script + marker path).
+ */
+export async function runLaunchVerifyLoop(
+  hooks: LaunchVerifyHooks,
+  options?: { signal?: AbortSignal; scheduleMs?: number[]; finalGraceMs?: number },
+): Promise<LaunchVerifyResult> {
+  const schedule = options?.scheduleMs ?? DEFAULT_LAUNCH_VERIFY_SCHEDULE_MS;
+  const sleep = hooks.sleep ?? abortableSleep;
+  const signal = options?.signal;
+  const start = Date.now();
+  let resends = 0;
+
+  const finish = (
+    status: LaunchVerifyResult["status"],
+    reason?: LaunchVerifyResult["reason"],
+  ): LaunchVerifyResult => ({
+    status,
+    resends,
+    elapsedMs: Date.now() - start,
+    ...(reason ? { reason } : {}),
+  });
+
+  for (const delayMs of schedule) {
+    if (!(await sleep(delayMs, signal)) || signal?.aborted) return finish("aborted");
+    if (hooks.markerExists()) return finish("verified");
+    if (hooks.shouldResend && !hooks.shouldResend()) continue;
+    try {
+      hooks.resend();
+      resends += 1;
+    } catch {
+      return finish("failed", "surface-gone");
+    }
+  }
+
+  // Give the last resend a moment to execute before declaring failure.
+  if (!(await sleep(options?.finalGraceMs ?? LAUNCH_VERIFY_FINAL_GRACE_MS, signal)) || signal?.aborted) {
+    return finish("aborted");
+  }
+  if (hooks.markerExists()) return finish("verified");
+  return finish("failed", "marker-missing");
+}
+
+export interface SendLongCommandVerifyOptions {
+  /** Abort the verify loop (e.g. on /reload or session shutdown). */
+  signal?: AbortSignal;
+  /** Override the backoff schedule (ms). Mainly for tests. */
+  scheduleMs?: number[];
+  /** Called exactly once with the final verification outcome. */
+  onResult?: (result: LaunchVerifyResult) => void;
+}
+
 /**
  * Send a long command to a pane by writing it to a script file first.
  * This avoids terminal line-wrapping issues that break commands exceeding the
@@ -1072,12 +1260,22 @@ export function sendEscape(surface: string): void {
  * stable path (for example under session artifacts) so the exact invocation is
  * preserved for debugging.
  *
+ * The script carries an idempotency guard (see buildLaunchScript), so the
+ * launch line can be resent safely. When `options.verify` is provided, an
+ * async fire-and-forget verify loop polls for the `<script>.started` marker
+ * and resends the launch line until it appears (or retries are exhausted),
+ * reporting the outcome via `verify.onResult`.
+ *
  * Returns the script path.
  */
 export function sendLongCommand(
   surface: string,
   command: string,
-  options?: { scriptPath?: string; scriptPreamble?: string },
+  options?: {
+    scriptPath?: string;
+    scriptPreamble?: string;
+    verify?: SendLongCommandVerifyOptions;
+  },
 ): string {
   const scriptPath =
     options?.scriptPath ??
@@ -1088,16 +1286,33 @@ export function sendLongCommand(
     );
   mkdirSync(dirname(scriptPath), { recursive: true });
 
-  const scriptParts = ["#!/bin/bash"];
-  if (options?.scriptPreamble) {
-    scriptParts.push(options.scriptPreamble.trimEnd());
+  writeFileSync(
+    scriptPath,
+    buildLaunchScript(command, { scriptPath, scriptPreamble: options?.scriptPreamble }),
+    { mode: 0o755 },
+  );
+
+  const launchLine = `bash ${shellEscape(scriptPath)}`;
+  sendCommand(surface, launchLine);
+
+  const verify = options?.verify;
+  if (verify) {
+    const backend = getMuxBackend();
+    const markerPath = launchMarkerPath(scriptPath);
+    void runLaunchVerifyLoop(
+      {
+        markerExists: () => existsSync(markerPath),
+        resend: () => sendCommand(surface, launchLine),
+        shouldResend: backend === "tmux" ? tmuxPaneIdleShellCheck(surface) : undefined,
+      },
+      { signal: verify.signal, scheduleMs: verify.scheduleMs },
+    )
+      .then((result) => verify.onResult?.(result))
+      .catch(() => {
+        // The verify loop never rejects by design; guard against onResult throwing.
+      });
   }
-  scriptParts.push(command);
 
-  writeFileSync(scriptPath, scriptParts.join("\n") + "\n", {
-    mode: 0o755,
-  });
-  sendCommand(surface, `bash ${shellEscape(scriptPath)}`);
   return scriptPath;
 }
 

From 3c84bca76a519fd914e9a47b6001412d51110808 Mon Sep 17 00:00:00 2001
From: Justin Giancola <justin.giancola@gmail.com>
Date: Mon, 6 Jul 2026 12:33:46 -0400
Subject: [PATCH 2/3] feat(subagents): truthful launch-failed state instead of
 eternal stall

A swallowed launch previously registered the subagent as running forever:
the child-side activity reporting (#35) means a never-started child can
never report anything, so the parent emitted 'stalled 1m' steer messages
indefinitely while an orphan idle shell sat in the pane.

Wire the launch verify loop (previous commit) into all three launch sites
(pi path, claude path, subagent_resume):

- Each sendLongCommand() now runs the verify/retry loop, abortable via the
  module-level /reload abort signal, with a per-spawn onResult callback
  (no shared state across concurrent spawns).
- On retry exhaustion, handleLaunchVerifyResult() records launchFailure on
  the running entry and aborts its watcher. watchSubagent() converts that
  into a launch-failure result delivered through the existing subagent
  result steer path: exit code 1, error 'launch-failed', and a summary
  stating the shell never executed the launch command (N resends over Ss)
  with remediation hints (surface id + backend, launch script path, manual
  'bash <script>' retry line).
- The entry is removed from runningSubagents, so the widget entry and
  stall notifications stop; the pane is intentionally NOT closed so the
  orphan shell can be inspected post-mortem.
- subagent_resume result handling no longer overrides a launch-failure
  summary with 'exited without new output' from the untouched session.
- Launch failure of claude-backed subagents omits the never-created pi
  session file from the result to avoid a misleading resume hint.

Closes TODO-02b64f40 (subagent spawn race fix).
---
 pi-extension/subagents/index.ts | 176 ++++++++++++++++++++++++++------
 1 file changed, 142 insertions(+), 34 deletions(-)

diff --git a/pi-extension/subagents/index.ts b/pi-extension/subagents/index.ts
index cff79bb6..025acb65 100644
--- a/pi-extension/subagents/index.ts
+++ b/pi-extension/subagents/index.ts
@@ -27,6 +27,7 @@ import {
   renameCurrentTab,
   renameWorkspace,
   readScreen,
+  type LaunchVerifyResult,
 } from "./cmux.ts";
 
 import {
@@ -486,6 +487,18 @@ interface RunningSubagent {
   abortController?: AbortController;
   cli?: string;
   sentinelFile?: string;
+  /** Set when the launch verify loop confirmed the launch script started. */
+  launchVerified?: boolean;
+  /**
+   * Set when the launch verify loop exhausted its retries: the launch script
+   * never started (or the pane vanished). The watcher turns this into a
+   * truthful launch-failure result instead of "cancelled"/eternal "stalled".
+   */
+  launchFailure?: {
+    resends: number;
+    elapsedMs: number;
+    reason: "marker-missing" | "surface-gone";
+  };
   statusState: SubagentStatusState;
   /**
    * When true, status transitions (stalled/recovered) do not wake the parent
@@ -499,6 +512,66 @@ interface RunningSubagent {
 /** All currently running subagents, keyed by id. */
 const runningSubagents = new Map<string, RunningSubagent>();
 
+/**
+ * Handle the outcome of the launch verify loop (see cmux.ts).
+ *
+ * On failure, records the launch failure on the running entry and aborts its
+ * watcher; watchSubagent() then delivers a truthful launch-failure result via
+ * the existing subagent result path (steer message), removes the entry (so
+ * stall pings stop) and keeps the pane open for post-mortem.
+ */
+function handleLaunchVerifyResult(running: RunningSubagent, result: LaunchVerifyResult): void {
+  // The subagent may have finished or been cancelled already, or a stale loop
+  // may report after /reload cleanup — only act on live entries.
+  if (!runningSubagents.has(running.id)) return;
+
+  if (result.status === "verified") {
+    running.launchVerified = true;
+    return;
+  }
+  if (result.status !== "failed") return;
+
+  running.launchFailure = {
+    resends: result.resends,
+    elapsedMs: result.elapsedMs,
+    reason: result.reason ?? "marker-missing",
+  };
+  running.abortController?.abort();
+}
+
+/** Human-readable summary for a launch failure, with remediation hints. */
+function formatLaunchFailureSummary(running: RunningSubagent): string {
+  const failure = running.launchFailure;
+  if (!failure) return "Failed to launch.";
+
+  const seconds = Math.max(1, Math.round(failure.elapsedMs / 1000));
+  const backend = getMuxBackend() ?? "mux";
+  const description =
+    failure.reason === "surface-gone"
+      ? "its terminal pane disappeared before the launch could be verified"
+      : `the shell in its pane never executed the launch command ` +
+        `(${failure.resends} resend${failure.resends === 1 ? "" : "s"} over ${seconds}s)`;
+
+  const lines = [
+    `Failed to launch: ${description}.`,
+    ``,
+    `Surface: ${running.surface} (${backend})`,
+    ...(running.launchScriptFile ? [`Launch script: ${running.launchScriptFile}`] : []),
+  ];
+
+  if (failure.reason !== "surface-gone") {
+    lines.push(``, `The pane was left open for post-mortem.`);
+    if (running.launchScriptFile) {
+      lines.push(
+        `To retry manually, run in that pane (or any shell):`,
+        `  bash ${shellEscape(running.launchScriptFile)}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
 // ── Widget management ──
 
 /** Latest ExtensionContext from session_start, used for widget updates. */
@@ -1028,15 +1101,6 @@ async function launchSubagent(
       .replace(/^-|-$/g, "") || "subagent"}-${id}.sh`;
     const launchScriptFile = join(artifactDir, "subagent-scripts", launchScriptName);
 
-    sendLongCommand(surface, command, {
-      scriptPath: launchScriptFile,
-      scriptPreamble: [
-        `# Claude Code subagent launch script for ${params.name}`,
-        `# Generated: ${new Date().toISOString()}`,
-        `# Surface: ${surface}`,
-      ].join("\n"),
-    });
-
     const running: RunningSubagent = {
       id,
       name: params.name,
@@ -1056,6 +1120,20 @@ async function launchSubagent(
     };
 
     runningSubagents.set(id, running);
+
+    sendLongCommand(surface, command, {
+      scriptPath: launchScriptFile,
+      scriptPreamble: [
+        `# Claude Code subagent launch script for ${params.name}`,
+        `# Generated: ${new Date().toISOString()}`,
+        `# Surface: ${surface}`,
+      ].join("\n"),
+      verify: {
+        signal: getModuleAbortSignal(),
+        onResult: (result) => handleLaunchVerifyResult(running, result),
+      },
+    });
+
     return running;
   }
 
@@ -1166,16 +1244,6 @@ async function launchSubagent(
     .replace(/-+/g, "-")
     .replace(/^-|-$/g, "") || "subagent"}-${id}.sh`;
   const launchScriptFile = join(artifactDir, "subagent-scripts", launchScriptName);
-  sendLongCommand(surface, command, {
-    scriptPath: launchScriptFile,
-    scriptPreamble: [
-      `# Subagent launch script for ${params.name}`,
-      `# Generated: ${new Date().toISOString()}`,
-      `# Session: ${subagentSessionFile}`,
-      `# Surface: ${surface}`,
-    ].join("\n"),
-  });
-
   const running: RunningSubagent = {
     id,
     name: params.name,
@@ -1194,6 +1262,21 @@ async function launchSubagent(
   };
 
   runningSubagents.set(id, running);
+
+  sendLongCommand(surface, command, {
+    scriptPath: launchScriptFile,
+    scriptPreamble: [
+      `# Subagent launch script for ${params.name}`,
+      `# Generated: ${new Date().toISOString()}`,
+      `# Session: ${subagentSessionFile}`,
+      `# Surface: ${surface}`,
+    ].join("\n"),
+    verify: {
+      signal: getModuleAbortSignal(),
+      onResult: (result) => handleLaunchVerifyResult(running, result),
+    },
+  });
+
   return running;
 }
 
@@ -1306,6 +1389,22 @@ async function watchSubagent(
       ping: result.ping,
     };
   } catch (err: any) {
+    if (running.launchFailure) {
+      // The launch never happened: report it truthfully via the normal result
+      // path, stop tracking (no widget entry, no more stall pings), and keep
+      // the pane open for post-mortem — do NOT close the surface.
+      runningSubagents.delete(running.id);
+      return {
+        name,
+        task,
+        summary: formatLaunchFailureSummary(running),
+        exitCode: 1,
+        elapsed: Math.floor((Date.now() - startTime) / 1000),
+        error: "launch-failed",
+        ...(running.cli === "claude" ? {} : { sessionFile }),
+      };
+    }
+
     try {
       closeSurface(surface);
     } catch {}
@@ -1826,17 +1925,6 @@ export default function subagentsExtension(pi: ExtensionAPI) {
             .replace(/-+/g, "-")
             .replace(/^-|-$/g, "") || "resume"}-resume-${Date.now()}.sh`,
         );
-        sendLongCommand(surface, command, {
-          scriptPath: launchScriptFile,
-          scriptPreamble: [
-            `# Subagent resume script for ${name}`,
-            `# Generated: ${new Date().toISOString()}`,
-            `# Session: ${params.sessionPath}`,
-            `# Surface: ${surface}`,
-            ...(resumeMsgFile ? [`# Resume message file: ${resumeMsgFile}`] : []),
-          ].join("\n"),
-        });
-
         // Register as a running subagent for widget tracking
         const running: RunningSubagent = {
           id,
@@ -1854,6 +1942,22 @@ export default function subagentsExtension(pi: ExtensionAPI) {
           }),
         };
         runningSubagents.set(id, running);
+
+        sendLongCommand(surface, command, {
+          scriptPath: launchScriptFile,
+          scriptPreamble: [
+            `# Subagent resume script for ${name}`,
+            `# Generated: ${new Date().toISOString()}`,
+            `# Session: ${params.sessionPath}`,
+            `# Surface: ${surface}`,
+            ...(resumeMsgFile ? [`# Resume message file: ${resumeMsgFile}`] : []),
+          ].join("\n"),
+          verify: {
+            signal: getModuleAbortSignal(),
+            onResult: (result) => handleLaunchVerifyResult(running, result),
+          },
+        });
+
         startWidgetRefresh();
         startStatusRefresh(pi);
 
@@ -1884,10 +1988,14 @@ export default function subagentsExtension(pi: ExtensionAPI) {
             }
 
             const allEntries = getNewEntries(params.sessionPath, entryCountBefore);
-            const summary = findLastAssistantMessage(allEntries) ??
-              (result.exitCode !== 0
-                ? `Resumed session exited with code ${result.exitCode}`
-                : "Resumed session exited without new output");
+            // Launch failures carry a truthful summary already — don't replace
+            // it with "exited without new output" from the untouched session.
+            const summary = result.error === "launch-failed"
+              ? result.summary
+              : findLastAssistantMessage(allEntries) ??
+                (result.exitCode !== 0
+                  ? `Resumed session exited with code ${result.exitCode}`
+                  : "Resumed session exited without new output");
             const presentation = resolveResultPresentation(
               { ...result, summary, sessionFile: params.sessionPath },
               name,

From b1d718b7912794c21035df8bbc7115c003359d1f Mon Sep 17 00:00:00 2001
From: Justin Giancola <justin.giancola@gmail.com>
Date: Mon, 6 Jul 2026 12:37:13 -0400
Subject: [PATCH 3/3] feat(subagents): expose surface id in tool result details
 + launch race tests

- subagent and subagent_resume immediate tool results now include the mux
  surface/pane id in details (launchScriptFile was already there), so
  orchestrators can inspect or take over the pane deliberately instead of
  guessing which pane belongs to which spawn.
- subagent_result steer details additionally carry error/surface/
  launchScriptFile when the result is a launch failure.
- Unit tests (17 new, npm test green at 131):
  - buildLaunchScript: guard check + marker creation ordered before the
    command, shell-escaped marker paths, preamble preserved
  - guarded script executed 3x via bash in a temp dir runs the command
    exactly once and leaves the .started marker
  - runLaunchVerifyLoop: no resend when marker present; resend-then-verify;
    bounded retries with marker-missing failure; shouldResend=false skips
    typing into non-idle panes; surface-gone on resend error; AbortSignal
    aborts cleanly; default schedule sanity
  - isIdleShellCommand accepts shells (zsh/-zsh/bash/fish path) and rejects
    node/pi/vim/claude
  - handleLaunchVerifyResult: records failure + aborts watcher, marks
    verified launches, ignores stale results for untracked entries
  - formatLaunchFailureSummary: truthful message with surface id, script
    path, manual 'bash <script>' retry hint; surface-gone variant

Also live-smoke-tested against a dedicated tmux session (race-debug-worker,
removed afterwards): an input-swallowing pane recovered via 2 resends
(verified @14s, command ran once); a pane stuck in 'cat' produced 0 resends
and a marker-missing failure (no typing into non-shell panes).

Closes TODO-5f79696d (subagent spawn race fix).
---
 pi-extension/subagents/index.ts |  18 ++
 test/test.ts                    | 312 +++++++++++++++++++++++++++++++-
 2 files changed, 329 insertions(+), 1 deletion(-)

diff --git a/pi-extension/subagents/index.ts b/pi-extension/subagents/index.ts
index 025acb65..0dd608c6 100644
--- a/pi-extension/subagents/index.ts
+++ b/pi-extension/subagents/index.ts
@@ -965,6 +965,8 @@ export const __test__ = {
   handleSubagentInterrupt,
   resolveResultPresentation,
   resolveResumeLaunchBehavior,
+  handleLaunchVerifyResult,
+  formatLaunchFailureSummary,
   runningSubagents,
 };
 
@@ -1572,6 +1574,13 @@ export default function subagentsExtension(pi: ExtensionAPI) {
                   exitCode: result.exitCode,
                   elapsed: result.elapsed,
                   sessionFile: result.sessionFile,
+                  ...(result.error === "launch-failed"
+                    ? {
+                        error: result.error,
+                        surface: running.surface,
+                        launchScriptFile: running.launchScriptFile,
+                      }
+                    : {}),
                   ...(result.claudeSessionId ? { claudeSessionId: result.claudeSessionId } : {}),
                 },
               },
@@ -1608,6 +1617,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
             name: params.name,
             task: params.task,
             agent: params.agent,
+            surface: running.surface,
             sessionFile: running.sessionFile,
             launchScriptFile: running.launchScriptFile,
             status: "started",
@@ -2012,6 +2022,13 @@ export default function subagentsExtension(pi: ExtensionAPI) {
                   exitCode: result.exitCode,
                   elapsed: result.elapsed,
                   sessionFile: params.sessionPath,
+                  ...(result.error === "launch-failed"
+                    ? {
+                        error: result.error,
+                        surface: running.surface,
+                        launchScriptFile: running.launchScriptFile,
+                      }
+                    : {}),
                 },
               },
               { triggerTurn: true, deliverAs: "steer" },
@@ -2035,6 +2052,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
           details: {
             id,
             name,
+            surface: running.surface,
             sessionPath: params.sessionPath,
             launchScriptFile,
             status: "started",
diff --git a/test/test.ts b/test/test.ts
index 98ed9fe1..642e8e9b 100644
--- a/test/test.ts
+++ b/test/test.ts
@@ -1,6 +1,7 @@
 import { describe, it, before, after } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, readFileSync, mkdirSync, rmSync } from "node:fs";
+import { mkdtempSync, writeFileSync, readFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -21,6 +22,12 @@ import {
   shellEscape,
   isCmuxAvailable,
   isWezTermAvailable,
+  buildLaunchScript,
+  launchMarkerPath,
+  runLaunchVerifyLoop,
+  isIdleShellCommand,
+  DEFAULT_LAUNCH_VERIFY_SCHEDULE_MS,
+  type LaunchVerifyResult,
   parseCmuxFocusedSnapshot,
   parseCmuxFocusedSnapshotFromJson,
   parseCmuxJson,
@@ -2195,3 +2202,306 @@ describe("cmux.ts", () => {
     });
   });
 });
+
+describe("launch verification (cmux.ts)", () => {
+  describe("buildLaunchScript", () => {
+    it("places the idempotency guard before the command", () => {
+      const scriptPath = "/tmp/launch scripts/it's-a-launch.sh";
+      const marker = launchMarkerPath(scriptPath);
+      const content = buildLaunchScript("echo hello", {
+        scriptPath,
+        scriptPreamble: "# preamble line",
+      });
+
+      const lines = content.split("\n");
+      assert.equal(lines[0], "#!/bin/bash");
+      assert.ok(content.includes("# preamble line"));
+
+      const guardCheckIdx = lines.findIndex((l) => l.includes("] && exit 0"));
+      const markerCreateIdx = lines.findIndex((l) => l.startsWith(": > "));
+      const commandIdx = lines.findIndex((l) => l === "echo hello");
+      assert.ok(guardCheckIdx > 0, "guard check line present");
+      assert.ok(markerCreateIdx > guardCheckIdx, "marker created after the guard check");
+      assert.ok(commandIdx > markerCreateIdx, "command runs after marker creation");
+
+      // Marker path is shell-escaped (path contains a space and a quote).
+      assert.ok(lines[guardCheckIdx].includes(shellEscape(marker)));
+      assert.ok(lines[markerCreateIdx].includes(shellEscape(marker)));
+    });
+
+    it("derives the marker path from the script path", () => {
+      assert.equal(launchMarkerPath("/a/b/launch.sh"), "/a/b/launch.sh.started");
+    });
+  });
+
+  describe("guarded script execution", () => {
+    it("is a no-op when executed twice", () => {
+      withTempDir((dir) => {
+        const scriptPath = join(dir, "launch.sh");
+        const logPath = join(dir, "log.txt");
+        const content = buildLaunchScript(`echo ran >> ${shellEscape(logPath)}`, { scriptPath });
+        writeFileSync(scriptPath, content, { mode: 0o755 });
+
+        execFileSync("bash", [scriptPath]);
+        execFileSync("bash", [scriptPath]);
+        execFileSync("bash", [scriptPath]);
+
+        assert.ok(existsSync(launchMarkerPath(scriptPath)), "marker file created");
+        assert.equal(readFileSync(logPath, "utf8"), "ran\n", "command ran exactly once");
+      });
+    });
+  });
+
+  describe("runLaunchVerifyLoop", () => {
+    const instantSleep = async (_ms: number, signal?: AbortSignal) => !signal?.aborted;
+
+    it("does not resend when the marker is already present", async () => {
+      let resends = 0;
+      const result = await runLaunchVerifyLoop(
+        {
+          markerExists: () => true,
+          resend: () => {
+            resends += 1;
+          },
+          sleep: instantSleep,
+        },
+        { scheduleMs: [1, 1, 1] },
+      );
+
+      assert.equal(result.status, "verified");
+      assert.equal(result.resends, 0);
+      assert.equal(resends, 0);
+    });
+
+    it("resends while the marker is absent, then verifies", async () => {
+      let resends = 0;
+      let markerPresent = false;
+      const result = await runLaunchVerifyLoop(
+        {
+          markerExists: () => markerPresent,
+          resend: () => {
+            resends += 1;
+            // The resent launch line "executes" before the next check.
+            markerPresent = true;
+          },
+          sleep: instantSleep,
+        },
+        { scheduleMs: [1, 1, 1] },
+      );
+
+      assert.equal(result.status, "verified");
+      assert.equal(result.resends, 1);
+      assert.equal(resends, 1);
+    });
+
+    it("bounds retries and fails when the marker never appears", async () => {
+      let resends = 0;
+      const result = await runLaunchVerifyLoop(
+        {
+          markerExists: () => false,
+          resend: () => {
+            resends += 1;
+          },
+          sleep: instantSleep,
+        },
+        { scheduleMs: [1, 1, 1], finalGraceMs: 1 },
+      );
+
+      assert.equal(result.status, "failed");
+      assert.equal(result.reason, "marker-missing");
+      assert.equal(resends, 3, "one resend per schedule slot, no more");
+      assert.equal(result.resends, 3);
+    });
+
+    it("skips resends while shouldResend returns false (pane not an idle shell)", async () => {
+      let resends = 0;
+      const result = await runLaunchVerifyLoop(
+        {
+          markerExists: () => false,
+          resend: () => {
+            resends += 1;
+          },
+          shouldResend: () => false,
+          sleep: instantSleep,
+        },
+        { scheduleMs: [1, 1, 1], finalGraceMs: 1 },
+      );
+
+      assert.equal(result.status, "failed");
+      assert.equal(resends, 0, "never typed into a non-idle pane");
+      assert.equal(result.resends, 0);
+    });
+
+    it("fails with surface-gone when the resend throws", async () => {
+      const result = await runLaunchVerifyLoop(
+        {
+          markerExists: () => false,
+          resend: () => {
+            throw new Error("can't find pane: %99");
+          },
+          sleep: instantSleep,
+        },
+        { scheduleMs: [1, 1, 1] },
+      );
+
+      assert.equal(result.status, "failed");
+      assert.equal(result.reason, "surface-gone");
+      assert.equal(result.resends, 0);
+    });
+
+    it("aborts cleanly via AbortSignal", async () => {
+      const controller = new AbortController();
+      controller.abort();
+      let resends = 0;
+      const result = await runLaunchVerifyLoop(
+        {
+          markerExists: () => false,
+          resend: () => {
+            resends += 1;
+          },
+          sleep: instantSleep,
+        },
+        { scheduleMs: [1, 1, 1], signal: controller.signal },
+      );
+
+      assert.equal(result.status, "aborted");
+      assert.equal(resends, 0);
+    });
+
+    it("uses a bounded default schedule", () => {
+      assert.ok(DEFAULT_LAUNCH_VERIFY_SCHEDULE_MS.length >= 3);
+      assert.ok(DEFAULT_LAUNCH_VERIFY_SCHEDULE_MS.every((ms) => Number.isInteger(ms) && ms > 0));
+    });
+  });
+
+  describe("isIdleShellCommand", () => {
+    it("recognizes idle shells", () => {
+      assert.equal(isIdleShellCommand("zsh"), true);
+      assert.equal(isIdleShellCommand("-zsh"), true);
+      assert.equal(isIdleShellCommand("bash"), true);
+      assert.equal(isIdleShellCommand("/usr/local/bin/fish"), true);
+    });
+
+    it("rejects non-shell foreground commands", () => {
+      assert.equal(isIdleShellCommand("node"), false);
+      assert.equal(isIdleShellCommand("pi"), false);
+      assert.equal(isIdleShellCommand("vim"), false);
+      assert.equal(isIdleShellCommand("claude"), false);
+      assert.equal(isIdleShellCommand(""), false);
+    });
+  });
+});
+
+describe("launch failure handling (index.ts)", () => {
+  const testApi = (subagentsModule as any).__test__;
+
+  function makeRunning(overrides: Record<string, unknown> = {}) {
+    const startTime = Date.now();
+    return {
+      id: `launch-fail-${Math.random().toString(16).slice(2, 10)}`,
+      name: "Test",
+      task: "task",
+      surface: "%42",
+      startTime,
+      sessionFile: "/tmp/session.jsonl",
+      launchScriptFile: "/tmp/artifacts/launch.sh",
+      interactive: false,
+      statusState: createStatusState({ source: "pi", startTimeMs: startTime }),
+      ...overrides,
+    };
+  }
+
+  function withRunningEntry(overrides: Record<string, unknown>, run: (running: any) => void) {
+    const runningMap = testApi.runningSubagents as Map<string, any>;
+    const running = makeRunning(overrides);
+    runningMap.set(running.id, running);
+    try {
+      run(running);
+    } finally {
+      runningMap.delete(running.id);
+    }
+  }
+
+  it("records launch failure and aborts the watcher on failed verification", () => {
+    let aborted = false;
+    withRunningEntry(
+      { abortController: { abort: () => { aborted = true; }, signal: undefined } },
+      (running) => {
+        const result: LaunchVerifyResult = {
+          status: "failed",
+          resends: 4,
+          elapsedMs: 61000,
+          reason: "marker-missing",
+        };
+        testApi.handleLaunchVerifyResult(running, result);
+
+        assert.deepEqual(running.launchFailure, {
+          resends: 4,
+          elapsedMs: 61000,
+          reason: "marker-missing",
+        });
+        assert.equal(aborted, true, "watcher aborted so the failure is delivered");
+      },
+    );
+  });
+
+  it("marks verified launches without touching the watcher", () => {
+    let aborted = false;
+    withRunningEntry(
+      { abortController: { abort: () => { aborted = true; }, signal: undefined } },
+      (running) => {
+        testApi.handleLaunchVerifyResult(running, {
+          status: "verified",
+          resends: 1,
+          elapsedMs: 2000,
+        });
+
+        assert.equal(running.launchVerified, true);
+        assert.equal(running.launchFailure, undefined);
+        assert.equal(aborted, false);
+      },
+    );
+  });
+
+  it("ignores stale results for entries that are no longer tracked", () => {
+    let aborted = false;
+    const running = makeRunning({
+      abortController: { abort: () => { aborted = true; }, signal: undefined },
+    });
+    // Not added to runningSubagents — e.g. finished, cancelled, or /reload cleanup.
+    testApi.handleLaunchVerifyResult(running, {
+      status: "failed",
+      resends: 4,
+      elapsedMs: 61000,
+      reason: "marker-missing",
+    });
+
+    assert.equal(running.launchFailure, undefined);
+    assert.equal(aborted, false);
+  });
+
+  it("formats a truthful launch-failure summary with remediation hints", () => {
+    const running = makeRunning({
+      launchFailure: { resends: 4, elapsedMs: 61000, reason: "marker-missing" },
+    });
+    const summary = testApi.formatLaunchFailureSummary(running);
+
+    assert.ok(summary.includes("never executed the launch command"));
+    assert.ok(summary.includes("4 resends over 61s"));
+    assert.ok(summary.includes("%42"), "includes the surface id");
+    assert.ok(summary.includes("/tmp/artifacts/launch.sh"), "includes the launch script path");
+    assert.ok(summary.includes("pane was left open"));
+    assert.ok(summary.includes("bash '/tmp/artifacts/launch.sh'"), "manual retry line");
+  });
+
+  it("formats a surface-gone launch failure without pane remediation", () => {
+    const running = makeRunning({
+      launchFailure: { resends: 1, elapsedMs: 4000, reason: "surface-gone" },
+    });
+    const summary = testApi.formatLaunchFailureSummary(running);
+
+    assert.ok(summary.includes("pane disappeared"));
+    assert.ok(summary.includes("%42"));
+    assert.ok(!summary.includes("pane was left open"));
+  });
+});