@tt-a1i/openpi 0.6.0 → 0.7.0

package/extensions/subagents/index.ts

@@ -57,6 +57,7 @@ import {
 } from "../shared/below-editor-navigation.ts";
 import {
   effectiveChildToolAllowlist,
+  inheritedChildToolAllowlist,
   resolveStandaloneChildProjectTrust,
 } from "../shared/child-session.ts";
 import { formatContextUtilization } from "../shared/context-utilization.ts";
@@ -144,6 +145,7 @@ import { createSubagentResultDelivery } from "./src/result-delivery.ts";
 import {
   createSubagentRuntime,
   runTool,
+  SubagentToolInterruptedError,
   type SubagentRuntime,
 } from "./src/runtime.ts";
 import { openSubagentPicker, openSubagentTakeover } from "./src/ui/takeover.ts";
@@ -886,6 +888,7 @@ export default function (
       if (
         planning &&
         agentType &&
+        !agentType.planningCompatible &&
         !planModeAllowsDeclaredTools(declaredChildTools)
       ) {
         throw new Error(
@@ -934,7 +937,10 @@ export default function (
       const requestedChildTools = planning
         ? planModeChildTools(declaredChildTools)
         : declaredChildTools;
-      const childTools = effectiveChildToolAllowlist(requestedChildTools);
+      const childTools = inheritedChildToolAllowlist(
+        pi.getActiveTools(),
+        requestedChildTools,
+      );
       // Read at spawn time so `/openpi-setup` changes affect the next child
       // without reloading this extension. Undefined preserves parent-model
       // inheritance in the backend.
@@ -980,11 +986,22 @@ export default function (
           interruptMessage: "Subagent spawn aborted.",
         });
       } catch (error) {
-        // The session scope owns reclamation, but it never opened, so this
-        // worktree would otherwise be orphaned on disk.
+        // Known startup failures can reclaim their empty checkout. Interrupted
+        // startup must preserve it while asynchronous acquisition may continue.
         if (worktree) {
           const spawnError =
             error instanceof Error ? error.message : String(error);
+          // Cancelling Effect acquisition does not prove an asynchronous
+          // factory or extension hook has quiesced. It may still use this cwd.
+          if (
+            signal?.aborted ||
+            error instanceof SubagentToolInterruptedError
+          ) {
+            throw new Error(
+              `${spawnError}; startup quiescence is unknown; checkout preserved at ${worktree.path} (branch ${worktree.branch})`,
+              { cause: error },
+            );
+          }
           let cleanupWarning: string | undefined;
           let cleanupError: unknown;
           try {

package/extensions/subagents/src/agent-types.ts

@@ -92,6 +92,8 @@ export interface AgentType {
   readonly description: string;
   /** Omitted = the child keeps the normal tool set. Present = allowlist. */
   readonly tools?: readonly string[];
+  /** Only built-in investigator definitions carry this planning compatibility. */
+  readonly planningCompatible?: boolean;
   /** "provider/model-id" or a bare id; resolved by the pi backend. */
   readonly model?: string;
   readonly reasoningEffort?: ReasoningEffort;
@@ -121,9 +123,9 @@ export const READ_ONLY_AGENT_TOOLS = [
 export const BUILT_IN_AGENT_TYPES: readonly AgentType[] = [
   {
     name: "explorer",
+    planningCompatible: true,
     description:
       "Read-only codebase exploration. Usually use moderate reasoning, increasing it for harder tasks.",
-    tools: READ_ONLY_AGENT_TOOLS,
     body: "Explore the codebase read-only. Trace the real flow, inspect related callers, and report concise evidence with file paths and line references.",
     source: "built-in:explorer",
   },
@@ -131,36 +133,22 @@ export const BUILT_IN_AGENT_TYPES: readonly AgentType[] = [
     name: "implementer",
     description:
       "Focused implementation with repository checks. Usually use medium-high reasoning, adjusted for scope, risk, and task difficulty.",
-    tools: [
-      "read",
-      "bash",
-      "edit",
-      "write",
-      "grep",
-      "find",
-      "ls",
-      "fd",
-      "rg",
-      "git_show",
-      "git_diff",
-      "git_log",
-    ],
     body: "Implement the requested change carefully. Trace the affected flow first, make the smallest correct edit, and run relevant checks before reporting results.",
     source: "built-in:implementer",
   },
   {
     name: "reviewer",
+    planningCompatible: true,
     description:
       "Read-only review for correctness, safety, and regressions. Usually use high reasoning, adjusted for task difficulty.",
-    tools: READ_ONLY_AGENT_TOOLS,
     body: "Review the requested code or change read-only. Identify concrete correctness, security, and regression risks with evidence; do not modify files.",
     source: "built-in:reviewer",
   },
   {
     name: "advisor",
+    planningCompatible: true,
     description:
       "Deep read-only analysis and technical advice. Usually use high reasoning, adjusted for task difficulty.",
-    tools: READ_ONLY_AGENT_TOOLS,
     body: "Analyze the problem deeply without modifying files. Explain the relevant tradeoffs, risks, and recommended next step using repository evidence.",
     source: "built-in:advisor",
   },

package/extensions/subagents/src/backends/pi.ts

@@ -25,6 +25,7 @@ import {
 import type { Cause, Scope } from "effect";
 import { Effect, Queue, Stream } from "effect";
 import { resolveAgentModel } from "../agent-types.ts";
+import { toolPreview } from "./tool-preview.ts";
 import type {
   SubagentBackend,
   SubagentCleanupReceipt,
@@ -118,27 +119,6 @@ function safeJson(value: unknown): string | undefined {
   }
 }
 
-/** First non-empty line of a tool result-ish value (v1 liveToolPreview). */
-function toolPreview(value: unknown): string | undefined {
-  if (typeof value === "string") {
-    return value
-      .split("\n")
-      .find((line) => line.trim())
-      ?.trim();
-  }
-  if (!value || typeof value !== "object") return undefined;
-  const content = (value as { content?: unknown }).content;
-  if (!Array.isArray(content)) return undefined;
-  for (const part of content) {
-    if (!part || typeof part !== "object") continue;
-    const record = part as { type?: unknown; text?: unknown };
-    if (record.type !== "text" || typeof record.text !== "string") continue;
-    const firstLine = record.text.split("\n").find((line) => line.trim());
-    if (firstLine) return firstLine.trim();
-  }
-  return undefined;
-}
-
 function assistantParts(msg: AssistantMessage): TranscriptPart[] {
   const parts: TranscriptPart[] = [];
   for (const part of msg.content) {
@@ -215,42 +195,70 @@ const makePiSession = (
             capturedStructured = encodeStructuredResult(value);
           });
 
+    // Own the session before asynchronous startup. Interruption can happen
+    // before the normal backend finalizer has been installed.
+    let acquiringSession: AgentSession | undefined;
+    let startupOwned = true;
+    const cleanupStartup = () =>
+      acquiringSession
+        ? shutdownAndDisposeChildSession(acquiringSession, {
+            abort: true,
+            timeoutMs: options.shutdownTimeoutMs,
+          })
+        : Promise.resolve();
+    yield* Effect.addFinalizer(() =>
+      Effect.promise(async () => {
+        if (startupOwned) await cleanupStartup();
+      }),
+    );
+
     const session = yield* Effect.tryPromise({
-      try: async () => {
-        const appendSystemPrompt = [
-          ...(task.appendSystemPrompt ?? []),
-          ...(structuredOutputTool
-            ? [STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION]
-            : []),
-        ];
-        const { loader, settingsManager } = await createChildResources({
-          cwd: task.cwd,
-          projectTrusted: task.parent.projectTrusted,
-          ...(appendSystemPrompt.length > 0 ? { appendSystemPrompt } : {}),
-        });
-        const { session } = await (
-          options.sessionFactory ?? createAgentSession
-        )({
-          cwd: task.cwd,
-          sessionManager: SessionManager.create(task.cwd),
-          settingsManager,
-          resourceLoader: loader,
-          model,
-          thinkingLevel,
-          ...(structuredOutputTool
-            ? { customTools: [structuredOutputTool] }
-            : {}),
-          ...childToolPolicy(
-            childToolsWithStructuredOutput(
-              task.tools,
-              structuredOutputTool !== undefined,
-            ),
-          ),
-        });
-        // Start child extension session hooks/resources in headless mode.
-        // A rejection here would otherwise leak the freshly created session:
-        // the scope finalizer that owns cleanup is only registered later.
+      try: async (signal) => {
+        const checkCancelled = () => {
+          if (signal.aborted)
+            throw signal.reason ?? new Error("Subagent startup cancelled");
+        };
+        const onCancelled = () => {
+          void cleanupStartup().catch(() => {});
+        };
+        signal.addEventListener("abort", onCancelled, { once: true });
         try {
+          checkCancelled();
+          const appendSystemPrompt = [
+            ...(task.appendSystemPrompt ?? []),
+            ...(structuredOutputTool
+              ? [STRUCTURED_OUTPUT_SYSTEM_INSTRUCTION]
+              : []),
+          ];
+          const { loader, settingsManager } = await createChildResources({
+            cwd: task.cwd,
+            projectTrusted: task.parent.projectTrusted,
+            ...(appendSystemPrompt.length > 0 ? { appendSystemPrompt } : {}),
+          });
+          checkCancelled();
+          const { session } = await (
+            options.sessionFactory ?? createAgentSession
+          )({
+            cwd: task.cwd,
+            sessionManager: SessionManager.create(task.cwd),
+            settingsManager,
+            resourceLoader: loader,
+            model,
+            thinkingLevel,
+            ...(structuredOutputTool
+              ? { customTools: [structuredOutputTool] }
+              : {}),
+            ...childToolPolicy(
+              childToolsWithStructuredOutput(
+                task.tools,
+                structuredOutputTool !== undefined,
+              ),
+            ),
+          });
+          acquiringSession = session;
+          checkCancelled();
+          // Never start extension binding for a factory that completed after
+          // cancellation. Already-running hooks retain bounded cleanup ownership.
           await bindChildSessionExtensions(
             session,
             childToolsWithStructuredOutput(
@@ -258,13 +266,14 @@ const makePiSession = (
               structuredOutputTool !== undefined,
             ),
           );
+          checkCancelled();
+          return session;
         } catch (error) {
-          await shutdownAndDisposeChildSession(session, {
-            timeoutMs: options.shutdownTimeoutMs,
-          });
+          await cleanupStartup();
           throw error;
+        } finally {
+          signal.removeEventListener("abort", onCancelled);
         }
-        return session;
       },
       catch: (error) => new SpawnError({ message: boundedError(error) }),
     });
@@ -650,6 +659,8 @@ const makePiSession = (
       }),
     );
 
+    startupOwned = false;
+
     /** Start a fresh run (v1 manager.run): fire-and-forget, errors -> events. */
     const startRun = (text: string) => {
       if (state.activePrompt) {

package/extensions/subagents/src/backends/tool-preview.ts

@@ -0,0 +1,29 @@
+// Match the manager's existing transcript text limit; canonical Pi tool results
+// remain intact. Only the normalized event's single-line preview is bounded.
+const TOOL_PREVIEW_MAX_LENGTH = 64 * 1_024;
+
+function firstMeaningfulLine(text: string) {
+  // Search only until the first non-whitespace character. Unlike splitting the
+  // entire log, this preserves blank-line behavior without visiting its tail.
+  const start = text.search(/\S/);
+  if (start < 0) return undefined;
+  const prefix = text.slice(start, start + TOOL_PREVIEW_MAX_LENGTH);
+  const newline = prefix.indexOf("\n");
+  return (newline < 0 ? prefix : prefix.slice(0, newline)).trimEnd();
+}
+
+/** First meaningful line of a tool result, without splitting accumulated logs. */
+export function toolPreview(value: unknown) {
+  if (typeof value === "string") return firstMeaningfulLine(value);
+  if (!value || typeof value !== "object") return undefined;
+  const content = (value as { content?: unknown }).content;
+  if (!Array.isArray(content)) return undefined;
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    const record = part as { type?: unknown; text?: unknown };
+    if (record.type !== "text" || typeof record.text !== "string") continue;
+    const firstLine = firstMeaningfulLine(record.text);
+    if (firstLine) return firstLine;
+  }
+  return undefined;
+}

package/extensions/subagents/src/manager.ts

@@ -10,10 +10,8 @@
  * imperative TUI components (which render synchronously) can read snapshots
  * and issue fire-and-forget commands without touching the Effect runtime.
  *
- * Every run is guarded by a first-response watchdog: a provider that accepts
- * the request but never emits its first assistant event is settled as a
- * failure (releasing its concurrency slot) instead of hanging forever,
- * mirroring the workflow runner's watchdog.
+ * Pi owns provider transport timeouts and retries. This manager owns explicit
+ * cancellation, settlement, and bounded cleanup, not model-output deadlines.
  */
 
 import {
@@ -60,13 +58,6 @@ export const MAX_TRACKED = 64;
 const STOP_TIMEOUT_MS = 5_000;
 /** Session abort/shutdown (5s) plus bounded direct-worktree cleanup (4s). */
 const ENTRY_CLOSE_TIMEOUT_MS = 10_000;
-/**
- * First-response watchdog: a run whose provider accepts the request but
- * never emits an assistant event is settled as a failure so it cannot
- * occupy a concurrency slot forever. Matches the workflow runner's
- * MODEL_PROGRESS_TIMEOUT_MS (extensions/workflows/runner.ts).
- */
-export const FIRST_RESPONSE_TIMEOUT_MS = 45_000;
 const ERROR_TEXT_MAX_LENGTH = 4_096;
 const TRANSCRIPT_TEXT_MAX_LENGTH = 64 * 1_024;
 const LIVE_ASSISTANT_MAX_LENGTH = 128 * 1_024;
@@ -77,10 +68,6 @@ function bounded(text: string) {
   return text.slice(0, ERROR_TEXT_MAX_LENGTH);
 }
 
-function formatWatchdogTimeout(ms: number) {
-  return ms % 1_000 === 0 ? `${ms / 1_000} seconds` : `${ms} ms`;
-}
-
 function boundedTranscriptText(text: string) {
   return text.slice(0, TRANSCRIPT_TEXT_MAX_LENGTH);
 }
@@ -133,8 +120,6 @@ interface Entry {
   scope: Scope.Closeable;
   pump?: Fiber.Fiber<void>;
   liveToolMap: Map<string, LiveToolState>;
-  /** First-response watchdog timer for the active (or just-armed) run. */
-  watchdogTimer?: ReturnType<typeof setTimeout>;
   /** Idle restart dispatched but RunStarted not folded yet; counts as running
    * so concurrent restarts cannot race past the cap. */
   restarting?: boolean;
@@ -214,8 +199,6 @@ export class SubagentManager extends Context.Service<
 
 const makeManager = (config: SubagentManagerConfig = {}) =>
   Effect.gen(function* () {
-    const firstResponseTimeoutMs =
-      config.firstResponseTimeoutMs ?? FIRST_RESPONSE_TIMEOUT_MS;
     const registry = yield* BackendRegistry;
     // Detached forker for sync contexts (read-model commands, pruning) that
     // preserves the manager's services instead of using the global runtime.
@@ -344,7 +327,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
     };
 
     const settle = (entry: Entry, outcome: RunOutcome) => {
-      clearWatchdog(entry);
       const s = entry.snapshot;
       const wasRestarting = entry.restarting === true;
       entry.restarting = false;
@@ -403,44 +385,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
       pruneSettled();
     };
 
-    /** Stop the first-response watchdog (first response arrived / run settled). */
-    const clearWatchdog = (entry: Entry) => {
-      if (entry.watchdogTimer !== undefined) {
-        clearTimeout(entry.watchdogTimer);
-        entry.watchdogTimer = undefined;
-      }
-    };
-
-    /** Settle a run whose provider never emitted a first assistant response. */
-    const watchdogExpired = (entry: Entry) => {
-      entry.watchdogTimer = undefined;
-      if (!isBusy(entry)) return;
-      const model = entry.snapshot.meta.modelLabel;
-      settle(entry, {
-        _tag: "Failed",
-        errorText: `Agent received no assistant response event${model ? ` for ${model}` : ""} within ${formatWatchdogTimeout(firstResponseTimeoutMs)}; the provider request may be stalled. Retry the subagent.`,
-      });
-      // The stalled session cannot be trusted to abort cooperatively; dispose
-      // it like the abort-deadline path so it cannot revive into a zombie run.
-      const fiber = runDetached(
-        closeEntryScope(entry).pipe(
-          Effect.timeout(ENTRY_CLOSE_TIMEOUT_MS),
-          Effect.ignore,
-        ),
-      );
-      cleanups.add(fiber);
-      fiber.addObserver(() => cleanups.delete(fiber));
-    };
-
-    /** Arm the first-response watchdog for the entry's current run. */
-    const armWatchdog = (entry: Entry) => {
-      clearWatchdog(entry);
-      entry.watchdogTimer = setTimeout(
-        () => watchdogExpired(entry),
-        firstResponseTimeoutMs,
-      );
-    };
-
     const foldEvent = (entry: Entry, event: SubagentEvent) => {
       const s = entry.snapshot;
       switch (event._tag) {
@@ -451,7 +395,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           s.settledAt = undefined;
           s.errorText = undefined;
           s.structuredResult = undefined;
-          armWatchdog(entry);
           break;
         case "RunSettled":
           settle(entry, event.outcome);
@@ -463,7 +406,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           });
           break;
         case "AssistantDelta": {
-          clearWatchdog(entry);
           const live = s.liveAssistant ?? { text: "", thinking: "" };
           s.liveAssistant =
             event.kind === "text"
@@ -482,7 +424,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           break;
         }
         case "AssistantMessage":
-          clearWatchdog(entry);
           appendTranscript(s, {
             kind: "assistant",
             parts: event.parts.map((part) =>
@@ -628,9 +569,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
             liveToolMap: new Map(),
           };
           entries.set(id, entry);
-          // The run is live from the caller's perspective before RunStarted
-          // reaches the pump; guard that window too.
-          armWatchdog(entry);
 
           // Pump: fold the event stream into the snapshot. Tied to the entry
           // scope, so closing the scope stops it. If the stream ends while the
@@ -781,10 +719,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
           // both pass the check in that window. Cleared by RunStarted/settle,
           // or here when the backend rejects the send.
           entry.restarting = true;
-          // A backend that accepts the send but never starts the run would
-          // hold the slot forever; guard the restart window the same way the
-          // spawn path guards its pre-RunStarted window.
-          armWatchdog(entry);
           return entry.session.send(text).pipe(
             Effect.onError(() =>
               Effect.sync(() => {
@@ -800,7 +734,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
     const disposeAll = Effect.gen(function* () {
       disposed = true;
       const all = [...entries.values()];
-      for (const entry of all) clearWatchdog(entry);
       entries.clear();
       yield* Effect.forEach(
         all,
@@ -878,8 +811,6 @@ const makeManager = (config: SubagentManagerConfig = {}) =>
   });
 
 export interface SubagentManagerConfig {
-  /** Test-only override for the first-response watchdog timeout. */
-  firstResponseTimeoutMs?: number;
   /** Session-branch high-water marks restored by the extension host. */
   initialModelCounter?: number;
   initialBtwCounter?: number;

package/extensions/subagents/src/prompt.ts

@@ -141,11 +141,11 @@ export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
 /** Model-facing schema descriptions for subagent_spawn task and execution options. */
 export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
   prompt:
-    "Task prompt for the subagent. Must be self-contained: include all needed context, file paths, and what to report back.",
+    "Self-contained task: include needed context, file paths, and expected report.",
   name: "Short human-readable name shown in listings and the UI",
   harness: 'Optional; "pi" is the only harness and the default.',
   workingDir:
-    "Trusted child working directory; defaults to the current directory",
+    "Child cwd, absolute or relative to parent. Target project trust is checked separately.",
   isolation:
     'Use "worktree" for concurrent writers and tell the child to commit. See the Subagents Skill for lifecycle details.',
   model:

package/extensions/subagents/src/runtime.ts

@@ -45,6 +45,9 @@ export function createSubagentRuntime(config: SubagentManagerConfig = {}) {
 
 export type SubagentRuntime = ReturnType<typeof createSubagentRuntime>;
 
+/** Canonical interruption, distinct from a known startup failure. */
+export class SubagentToolInterruptedError extends Error {}
+
 /**
  * Run an effect from an async tool handler. Typed failures and defects are
  * converted to thrown Errors (what pi's tool contract expects); interruption
@@ -60,9 +63,13 @@ export async function runTool<A, E>(
     options.signal ? { signal: options.signal } : undefined,
   );
   if (Exit.isSuccess(exit)) return exit.value;
-  if (Cause.hasInterruptsOnly(exit.cause)) {
-    throw new Error(options.interruptMessage ?? "Operation was aborted.");
-  }
   const [first] = Cause.prettyErrors(exit.cause);
+  if (Cause.hasInterrupts(exit.cause)) {
+    const interrupted = options.interruptMessage ?? "Operation was aborted.";
+    const detail = Cause.hasInterruptsOnly(exit.cause)
+      ? ""
+      : ` ${first?.message ?? Cause.pretty(exit.cause)}`;
+    throw new SubagentToolInterruptedError(`${interrupted}${detail}`);
+  }
   throw new Error(first?.message ?? Cause.pretty(exit.cause));
 }

package/extensions/web/index.ts

@@ -10,12 +10,23 @@ import {
   PI_CODING_AGENT_ENTRY_ENV,
   resolvePiCodingAgentEntry,
 } from "../../web/host/pi-coding-agent-entry.ts";
+import { TerminalTextSanitizer } from "../shared/terminal-text.ts";
 
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000;
+const WEB_ERROR_TAIL_MAX_BYTES = 8 * 1024;
+
+interface WebProcessErrorStream {
+  on(event: "data", listener: (chunk: Buffer | string) => void): this;
+  removeListener(
+    event: "data",
+    listener: (chunk: Buffer | string) => void,
+  ): this;
+}
 
 export interface WebProcess {
   readonly exitCode: number | null;
   readonly signalCode: NodeJS.Signals | null;
+  readonly stderr: WebProcessErrorStream | null;
   once(event: "error", listener: (error: Error) => void): this;
   once(
     event: "close",
@@ -28,7 +39,7 @@ interface SpawnWebOptions {
   cwd: string;
   env: NodeJS.ProcessEnv;
   shell: false;
-  stdio: "inherit";
+  stdio: ["inherit", "inherit", "pipe"];
 }
 
 function webProcessEnvironment(
@@ -51,6 +62,7 @@ function webProcessEnvironment(
 export interface WebCommandDependencies {
   entrypoint: string;
   spawn(command: string, args: string[], options: SpawnWebOptions): WebProcess;
+  writeStderr(chunk: Buffer | string): void;
   clearTerminal(): void;
   holdParentSigint(): () => void;
   resolvePiCodingAgentEntry(): string | undefined;
@@ -58,7 +70,12 @@ export interface WebCommandDependencies {
 }
 
 type WebExit =
-  | { kind: "close"; code: number | null; signal: NodeJS.Signals | null }
+  | {
+      kind: "close";
+      code: number | null;
+      signal: NodeJS.Signals | null;
+      errorDetail?: string;
+    }
   | { kind: "error"; error: Error };
 
 interface ActiveWebProcess {
@@ -71,6 +88,9 @@ const defaultDependencies: WebCommandDependencies = {
   spawn(command, args, options) {
     return nodeSpawn(command, args, options);
   },
+  writeStderr(chunk) {
+    process.stderr.write(chunk);
+  },
   clearTerminal() {
     process.stdout.write("\u001b[2J\u001b[H");
   },
@@ -91,6 +111,31 @@ function delay(milliseconds: number) {
   });
 }
 
+function boundedUtf8Tail(text: string, maxBytes: number) {
+  let bytes = 0;
+  let start = text.length;
+  for (const character of Array.from(text).reverse()) {
+    const characterBytes = Buffer.byteLength(character, "utf8");
+    if (bytes + characterBytes > maxBytes) break;
+    bytes += characterBytes;
+    start -= character.length;
+  }
+  return text.slice(start);
+}
+
+function actionableWebError(stderr: string) {
+  const lines = stderr
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const newestFirst = [...lines].reverse();
+  return (
+    newestFirst.find((line) =>
+      line.includes("Failed to start OpenPI Web Workbench:"),
+    ) ?? newestFirst.find((line) => /^(?:Error|Failed):/u.test(line))
+  );
+}
+
 async function stopWebProcess(active: ActiveWebProcess, timeoutMs: number) {
   if (active.child.exitCode !== null || active.child.signalCode !== null)
     return;
@@ -116,15 +161,26 @@ function runWebInForeground(
   return ctx.ui.custom<WebExit>((tui, _theme, _keybindings, done) => {
     let finished = false;
     let tuiStopped = false;
+    let stderrTail = "";
+    let childStderr: WebProcessErrorStream | null | undefined;
     let resolveClosed = () => {};
     const closed = new Promise<void>((resolve) => {
       resolveClosed = resolve;
     });
     const releaseParentSigint = dependencies.holdParentSigint();
+    const sanitizer = new TerminalTextSanitizer();
+    const captureStderr = (chunk: Buffer | string) => {
+      dependencies.writeStderr(chunk);
+      stderrTail = boundedUtf8Tail(
+        `${stderrTail}${sanitizer.push(String(chunk))}`,
+        WEB_ERROR_TAIL_MAX_BYTES,
+      );
+    };
 
     const finish = (result: WebExit) => {
       if (finished) return;
       finished = true;
+      childStderr?.removeListener("data", captureStderr);
       releaseParentSigint();
       setActive(undefined);
       resolveClosed();
@@ -147,13 +203,20 @@ function runWebInForeground(
           cwd: childCwd,
           env: webProcessEnvironment(childCwd, piCodingAgentEntry),
           shell: false,
-          stdio: "inherit",
+          stdio: ["inherit", "inherit", "pipe"],
         },
       );
+      childStderr = child.stderr;
+      childStderr?.on("data", captureStderr);
       setActive({ child, closed });
       child.once("error", (error) => finish({ kind: "error", error }));
       child.once("close", (code, signal) =>
-        finish({ kind: "close", code, signal }),
+        finish({
+          kind: "close",
+          code,
+          signal,
+          errorDetail: actionableWebError(stderrTail),
+        }),
       );
     } catch (error) {
       finish({
@@ -242,7 +305,8 @@ export default function web(
         }
         if (result.code !== 0) {
           ctx.ui.notify(
-            `OpenPI Web Workbench exited with code ${result.code ?? "unknown"}.`,
+            result.errorDetail ??
+              `OpenPI Web Workbench exited with code ${result.code ?? "unknown"}.`,
             "error",
           );
           return;