@bastani/atomic 0.9.5-alpha.8 → 0.9.5-alpha.9

package/dist/builtin/mcp/startup-warmup.ts

@@ -0,0 +1,98 @@
+import type { McpExtensionState } from "./state.ts";
+import { getMissingConfiguredDirectToolServers } from "./direct-tools.ts";
+import { loadMetadataCache } from "./metadata-cache.ts";
+import { buildToolMetadata } from "./tool-metadata.ts";
+import { parallelLimit } from "./utils.ts";
+import { logger } from "./logger.ts";
+import { updateMetadataCache, updateStatusBar } from "./init.ts";
+
+export interface McpStartupWarmupOptions {
+  shouldContinue?: () => boolean;
+  onDirectToolsChanged?: () => void | Promise<void>;
+  onSettled?: () => void;
+}
+
+export interface McpStartupWarmupHandle {
+  readonly promise: Promise<void>;
+  cancel(): void;
+}
+
+function deferToMacrotask(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+export function scheduleMcpStartupWarmup(
+  state: McpExtensionState,
+  options: McpStartupWarmupOptions = {},
+): McpStartupWarmupHandle {
+  let cancelled = false;
+  const shouldContinue = (): boolean => !cancelled && (options.shouldContinue?.() ?? true);
+
+  const promise = (async () => {
+    await deferToMacrotask();
+    if (!shouldContinue()) return;
+
+    const envDirect = process.env.MCP_DIRECT_TOOLS;
+    if (envDirect === "__none__") return;
+
+    const envDirectTools = envDirect?.split(",").map((item) => item.trim()).filter(Boolean);
+    const missingCacheServers = getMissingConfiguredDirectToolServers(state.config, loadMetadataCache(), envDirectTools)
+      .filter((name) => state.manager.getConnection(name)?.status !== "connected");
+    if (missingCacheServers.length === 0) return;
+
+    const prefix = state.config.settings?.toolPrefix ?? "server";
+    const results = await parallelLimit(missingCacheServers, 10, async (name) => {
+      if (!shouldContinue()) return { name, ok: false };
+      const definition = state.config.mcpServers[name];
+      if (!definition) return { name, ok: false };
+      try {
+        const connection = await state.manager.connect(name, definition);
+        if (!shouldContinue()) {
+          if (state.manager.getConnection(name) === connection) {
+            await state.manager.close(name);
+          }
+          return { name, ok: false };
+        }
+        if (connection.status === "needs-auth") return { name, ok: false };
+        const { metadata } = buildToolMetadata(connection.tools, connection.resources, definition, name, prefix);
+        state.toolMetadata.set(name, metadata);
+        updateMetadataCache(state, name);
+        return { name, ok: true };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.debug(`MCP: background direct-tools warmup failed for ${name}: ${message}`);
+        return { name, ok: false };
+      }
+    });
+
+    if (!shouldContinue()) return;
+    const warmed = results.filter((result) => result.ok).map((result) => result.name);
+    if (warmed.length === 0) return;
+    updateStatusBar(state);
+    if (!shouldContinue()) return;
+    await options.onDirectToolsChanged?.();
+    if (!shouldContinue()) return;
+    if (state.ui) {
+      state.ui.notify(`MCP: direct tools for ${warmed.join(", ")} are now available`, "info");
+    }
+  })()
+    .catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.debug(`MCP: background startup warmup failed: ${message}`);
+    })
+    .finally(() => {
+      try {
+        options.onSettled?.();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.debug(`MCP: background startup warmup settled callback failed: ${message}`);
+      }
+    });
+
+  return {
+    promise,
+    cancel() {
+      cancelled = true;
+    },
+  };
+}

package/dist/builtin/mcp/tool-result-renderer.ts

@@ -1,7 +1,7 @@
-import type { AgentToolResult, ToolRenderResultOptions } from "@bastani/atomic";
+import { keyText, type AgentToolResult, type ToolRenderResultOptions } from "@bastani/atomic";
 import { Text } from "@earendil-works/pi-tui";
 
-type McpToolResultDetails = Record<string, unknown> & { error?: unknown };
+export type McpToolResultDetails = Record<string, unknown> & { error?: unknown };
 type McpToolContentBlock = AgentToolResult<McpToolResultDetails>["content"][number];
 
 interface RenderTheme {
@@ -58,7 +58,7 @@ export function renderMcpToolResult(
     .map((line) => line === "…" ? theme.fg("muted", line) : theme.fg("toolOutput", line))
     .join("\n");
   const hint = display.truncated && !options.expanded
-    ? `\n${theme.fg("muted", "(CTRL+O Expand)")}`
+    ? `\n${theme.fg("muted", `(${keyText("app.tools.expand")} Expand)`)}`
     : "";
 
   return new Text(`${output}${hint}`, 0, 0);

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.9.5-alpha.9] - 2026-07-09
+
+### Changed
+
+- Improved subagent extension startup by deferring old-run cleanup scans, result watcher startup, and existing-result priming to macrotasks while preserving immediate `subagent` tool and slash-command registration.
+
+### Fixed
+
+- Fixed background async result watching on Windows to use Atomic's safe watcher path strategy and fall back to polling when native `fs.watch` would receive an unsafe or non-canonical watcher path.
+- Fixed async/background subagent status visibility while the fullscreen workflow graph is active by publishing the live async summary through the shared status surface in addition to the below-editor widget.
+- Fixed foreground and background subagent startup diagnostics so missing or invalid child `cwd` values are reported as working-directory problems before spawn, while runtime spawn failures include the attempted command and cwd instead of ambiguous `ENOENT` output.
+
 ## [0.9.5-alpha.8] - 2026-07-08
 
 ### Fixed

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.5-alpha.8",
+  "version": "0.9.5-alpha.9",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/subagents/src/extension/index.ts

@@ -7,21 +7,18 @@ import { APP_NAME, getEnvValue } from "@bastani/atomic";
 import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@bastani/atomic";
 import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
 import { discoverAgents } from "../agents/agents.ts";
-import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
+import { getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
-import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { advanceResultPulseFrame, renderLiveSubagentResult, renderSubagentResult, stopResultAnimations, stopWidgetAnimation, type SubagentResultRenderState } from "../tui/render.ts";
 import { SubagentParams } from "./schemas.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
-import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
 import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template-bridge.ts";
 import { registerSlashSubagentBridge } from "../slash/slash-bridge.ts";
 import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
 import { inspectSubagentStatus } from "../runs/background/run-status.ts";
 import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/background/notify.ts";
-import { cleanupOldNestedRuntimeDirs } from "../runs/shared/nested-events.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import registerFanoutChildSubagentExtension from "./fanout-child.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
@@ -29,6 +26,7 @@ import { loadConfig } from "./config.ts";
 import { DEFAULT_PROMPT_GUIDANCE } from "./prompt-guidance.ts";
 import { type Details, type SubagentState, ASYNC_DIR, DEFAULT_ARTIFACT_CONFIG, RESULTS_DIR, SLASH_RESULT_TYPE, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_ASYNC_STARTED_EVENT, SUBAGENT_CONTROL_EVENT, WIDGET_KEY } from "../shared/types.ts";
 import { clearPendingForegroundControlNotices, formatSubagentControlNotice, handleSubagentControlNotice, SUBAGENT_CONTROL_MESSAGE_TYPE, type SubagentControlMessageDetails } from "./control-notices.ts";
+import { createSubagentStartupMaintenance } from "./startup-maintenance.ts";
 export { loadConfig } from "./config.ts";
 function getSubagentSessionRoot(parentSessionFile: string | null): string {
 	if (parentSessionFile) {
@@ -171,12 +169,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	}
 	ensureAccessibleDir(RESULTS_DIR);
 	ensureAccessibleDir(ASYNC_DIR);
-	cleanupOldChainDirs();
 	const config = loadConfig();
 	const asyncByDefault = config.asyncByDefault === true;
 	const tempArtifactsDir = getArtifactsDir(null);
-	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
-	cleanupOldNestedRuntimeDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
 	const state: SubagentState = {
 		baseCwd: "",
 		currentSessionId: null,
@@ -197,16 +192,16 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			clear: () => {},
 		},
 	};
-	const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
-		pi,
-		state,
-		RESULTS_DIR,
-		10 * 60 * 1000,
-	);
-	startResultWatcher();
-	primeExistingResults();
+	const maintenance = createSubagentStartupMaintenance(pi, state, {
+		resultsDir: RESULTS_DIR,
+		artifactCleanupDays: DEFAULT_ARTIFACT_CONFIG.cleanupDays,
+		resultTtlMs: 10 * 60 * 1000,
+	});
+	maintenance.scheduleStartupCleanup();
+	maintenance.startResultWatcherDeferred();
+	maintenance.primeExistingResultsDeferred();
 	const runtimeCleanup = () => {
-		stopResultWatcher();
+		maintenance.stop();
 		stopWidgetAnimation();
 		stopResultAnimations();
 		clearPendingForegroundControlNotices(state);
@@ -430,13 +425,7 @@ DIAGNOSTICS:
 		if (state.asyncJobs.size > 0) ensurePoller();
 	});
 	const cleanupSessionArtifacts = (ctx: ExtensionContext) => {
-		try {
-			const sessionFile = ctx.sessionManager.getSessionFile();
-			if (sessionFile) {
-				cleanupOldArtifacts(getArtifactsDir(sessionFile), DEFAULT_ARTIFACT_CONFIG.cleanupDays);
-			}
-		} catch {
-		}
+		maintenance.cleanupSessionArtifactsDeferred(ctx);
 	};
 	const resetSessionState = (ctx: ExtensionContext) => {
 		state.baseCwd = ctx.cwd;
@@ -447,7 +436,7 @@ DIAGNOSTICS:
 		resetJobs(ctx);
 		hydrateActiveJobs(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
-		primeExistingResults();
+		maintenance.primeExistingResultsDeferred();
 	};
 	pi.on("session_start", (_event, ctx) => {
 		resetSessionState(ctx);
@@ -462,7 +451,7 @@ DIAGNOSTICS:
 		if (globalStore[eventUnsubscribeStoreKey] === eventUnsubscribes) {
 			delete globalStore[eventUnsubscribeStoreKey];
 		}
-		stopResultWatcher();
+		maintenance.stop();
 		stopWidgetAnimation();
 		stopResultAnimations();
 		if (state.poller) clearInterval(state.poller);

package/dist/builtin/subagents/src/extension/startup-maintenance.ts

@@ -0,0 +1,89 @@
+import type { ExtensionAPI, ExtensionContext } from "@bastani/atomic";
+import type { SubagentState } from "../shared/types.ts";
+import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
+import { cleanupOldChainDirs } from "../shared/settings.ts";
+import { cleanupOldNestedRuntimeDirs } from "../runs/shared/nested-events.ts";
+import { createResultWatcher } from "../runs/background/result-watcher.ts";
+
+export interface SubagentStartupMaintenance {
+  scheduleStartupCleanup(): void;
+  startResultWatcherDeferred(): void;
+  primeExistingResultsDeferred(): void;
+  cleanupSessionArtifactsDeferred(ctx: ExtensionContext): void;
+  stop(): void;
+}
+
+function scheduleMacrotask(task: () => void): () => void {
+  let cancelled = false;
+  const handle = setImmediate(() => {
+    if (!cancelled) task();
+  });
+  handle.unref?.();
+  return () => {
+    cancelled = true;
+    clearImmediate(handle);
+  };
+}
+
+function swallowCleanup(task: () => void): void {
+  try {
+    task();
+  } catch {
+  }
+}
+
+export function createSubagentStartupMaintenance(
+  pi: ExtensionAPI,
+  state: SubagentState,
+  options: {
+    resultsDir: string;
+    artifactCleanupDays: number;
+    resultTtlMs: number;
+  },
+): SubagentStartupMaintenance {
+  const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
+    pi,
+    state,
+    options.resultsDir,
+    options.resultTtlMs,
+  );
+  const cancelTasks = new Set<() => void>();
+  const schedule = (task: () => void): void => {
+    const cancel = scheduleMacrotask(() => {
+      cancelTasks.delete(cancel);
+      task();
+    });
+    cancelTasks.add(cancel);
+  };
+
+  return {
+    scheduleStartupCleanup() {
+      schedule(() => {
+        swallowCleanup(cleanupOldChainDirs);
+        swallowCleanup(() => cleanupAllArtifactDirs(options.artifactCleanupDays));
+        swallowCleanup(() => cleanupOldNestedRuntimeDirs(options.artifactCleanupDays));
+      });
+    },
+    startResultWatcherDeferred() {
+      schedule(startResultWatcher);
+    },
+    primeExistingResultsDeferred() {
+      schedule(primeExistingResults);
+    },
+    cleanupSessionArtifactsDeferred(ctx) {
+      let sessionFile: string | null | undefined;
+      try {
+        sessionFile = ctx.sessionManager.getSessionFile();
+      } catch {
+        return;
+      }
+      if (!sessionFile) return;
+      schedule(() => swallowCleanup(() => cleanupOldArtifacts(getArtifactsDir(sessionFile), options.artifactCleanupDays)));
+    },
+    stop() {
+      for (const cancel of cancelTasks) cancel();
+      cancelTasks.clear();
+      stopResultWatcher();
+    },
+  };
+}

package/dist/builtin/subagents/src/runs/background/async-execution-common.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { APP_NAME } from "@bastani/atomic";
-import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
+import { formatPiSpawnError, resolvePiPackageRoot, validatePiSpawnCwd } from "../shared/pi-spawn.ts";
 import { getAsyncConfigPath, TEMP_ROOT_DIR, type SubagentRunMode } from "../../shared/types.ts";
 import type { AsyncExecutionResult, AsyncSpawnResult } from "./async-execution-types.ts";
 
@@ -85,33 +85,38 @@ export function writeAsyncRunnerConfig(cfg: object, suffix: string): string {
 }
 
 export function spawnRunner(cfg: object, suffix: string, cwd: string): AsyncSpawnResult {
+	const cwdValidation = validatePiSpawnCwd(cwd);
+	if (!cwdValidation.ok) return { error: cwdValidation.error };
+
 	if (!jitiCliPath) {
 		return { error: "upstream jiti for TypeScript execution could not be found; ensure package dependencies are installed" };
 	}
 
-	try {
-		const cwdStats = fs.statSync(cwd);
-		if (!cwdStats.isDirectory()) {
-			return { error: `cwd is not a directory: ${cwd}` };
-		}
-	} catch {
-		return { error: `cwd does not exist: ${cwd}` };
-	}
-
 	const cfgPath = writeAsyncRunnerConfig(cfg, suffix);
 	const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
 
-	const proc = spawn(process.execPath, [jitiCliPath, runner, cfgPath], {
-		cwd,
-		detached: true,
-		stdio: "ignore",
-		windowsHide: true,
-	});
+	const spawnSpec = { command: process.execPath, args: [jitiCliPath, runner, cfgPath] };
+	let proc: ReturnType<typeof spawn>;
+	try {
+		proc = spawn(spawnSpec.command, spawnSpec.args, {
+			cwd,
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true,
+		});
+	} catch (error) {
+		const spawnError = error instanceof Error ? error : new Error(String(error));
+		return { error: formatPiSpawnError(spawnError, spawnSpec, cwd) };
+	}
 	proc.on("error", (error) => {
-		console.error(`[${APP_NAME}-subagents] async spawn failed: ${error.message}`);
+		console.error(`[${APP_NAME}-subagents] async spawn failed: ${formatPiSpawnError(error, spawnSpec, cwd)}`);
 	});
 	if (typeof proc.pid !== "number") {
-		return { error: `async runner did not produce a pid for cwd: ${cwd}` };
+		const noPidError = Object.assign(
+			new Error(`spawn ${spawnSpec.command} failed before assigning a pid`),
+			fs.existsSync(spawnSpec.command) ? {} : { code: "ENOENT" },
+		);
+		return { error: formatPiSpawnError(noPidError, spawnSpec, cwd) };
 	}
 	proc.unref();
 	return { pid: proc.pid };

package/dist/builtin/subagents/src/runs/background/result-watcher.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { isSafeFsWatchPathError, watchWithErrorHandler } from "@bastani/atomic";
 import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.ts";
 import { createFileCoalescer } from "../../shared/file-coalescer.ts";
 import {
@@ -21,7 +22,9 @@ import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-
 const WATCHER_RESTART_DELAY_MS = 3000;
 const POLL_INTERVAL_MS = 3000;
 
-type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "watch">;
+type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "watch"> & {
+	realpathSync?: typeof fs.realpathSync;
+};
 
 type ResultWatcherTimers = {
 	setTimeout: typeof setTimeout;
@@ -30,9 +33,12 @@ type ResultWatcherTimers = {
 	clearInterval: typeof clearInterval;
 };
 
+type ResultWatcherSafeWatch = typeof watchWithErrorHandler;
+
 type ResultWatcherDeps = {
 	fs?: ResultWatcherFs;
 	timers?: ResultWatcherTimers;
+	safeWatch?: ResultWatcherSafeWatch;
 };
 
 type ResultFileChild = {
@@ -88,7 +94,7 @@ function isNotFoundError(error: unknown): boolean {
 
 function shouldFallBackToPolling(error: unknown): boolean {
 	const code = getErrorCode(error);
-	return code === "EMFILE" || code === "ENOSPC";
+	return code === "EMFILE" || code === "ENOSPC" || isSafeFsWatchPathError(error);
 }
 
 export function createResultWatcher(
@@ -104,6 +110,7 @@ export function createResultWatcher(
 } {
 	const fsApi = deps.fs ?? fs;
 	const timers = deps.timers ?? { setTimeout, clearTimeout, setInterval, clearInterval };
+	const safeWatch = deps.safeWatch ?? watchWithErrorHandler;
 
 	const handleResult = async (file: string) => {
 		const resultPath = path.join(resultsDir, file);
@@ -264,13 +271,7 @@ export function createResultWatcher(
 			state.watcherRestartTimer = null;
 		}
 		try {
-			state.watcher = fsApi.watch(resultsDir, (ev, file) => {
-				if (ev !== "rename" || !file) return;
-				const fileName = file.toString();
-				if (!fileName.endsWith(".json")) return;
-				state.resultFileCoalescer.schedule(fileName);
-			});
-			state.watcher.on("error", (error) => {
+			const handleWatcherError = (error: Error) => {
 				if (shouldFallBackToPolling(error)) {
 					startPollingFallback(error);
 					return;
@@ -279,8 +280,17 @@ export function createResultWatcher(
 				state.watcher?.close();
 				state.watcher = null;
 				scheduleRestart();
+			};
+			state.watcher = safeWatch(resultsDir, (ev, file) => {
+				if (ev !== "rename" || !file) return;
+				const fileName = file.toString();
+				if (!fileName.endsWith(".json")) return;
+				state.resultFileCoalescer.schedule(fileName);
+			}, handleWatcherError, {
+				watch: fsApi.watch,
+				realpathSyncNative: fsApi.realpathSync?.native,
 			});
-			state.watcher.unref?.();
+			state.watcher?.unref?.();
 		} catch (error) {
 			if (shouldFallBackToPolling(error)) {
 				startPollingFallback(error);

package/dist/builtin/subagents/src/runs/background/subagent-runner-streaming.ts

@@ -5,7 +5,7 @@ import { appendJsonl } from "../../shared/artifacts.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { detectSubagentError, extractTextFromContent, extractToolArgsPreview, getFinalOutput } from "../../shared/utils.ts";
 import { getSubagentDepthEnv } from "../../shared/types.ts";
-import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
+import { formatPiSpawnError, getPiSpawnCommand, validatePiSpawnCwd } from "../shared/pi-spawn.ts";
 import {
 	assistantStopReason,
 	isAssistantFailureStopReason,
@@ -29,6 +29,17 @@ export function runPiStreaming(
 	registerInterrupt?: (interrupt: (() => void) | undefined) => void,
 	onChildEvent?: (event: ChildEvent) => void,
 ): Promise<RunPiStreamingResult> {
+	const cwdValidation = validatePiSpawnCwd(cwd);
+	if (!cwdValidation.ok) {
+		return Promise.resolve({
+			stderr: "",
+			exitCode: 1,
+			messages: [],
+			usage: emptyUsage(),
+			error: cwdValidation.error,
+			finalOutput: "",
+		});
+	}
 	return new Promise((resolve) => {
 		const outputStream = fs.createWriteStream(outputFile, { flags: "w" });
 		const spawnEnv = {
@@ -273,8 +284,7 @@ export function runPiStreaming(
 			attemptWatchdog.clear();
 			outputStream.end();
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
-			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			const finalError = error ?? assistantError ?? spawnErrorMessage;
+			const finalError = error ?? assistantError ?? formatPiSpawnError(spawnError, spawnSpec, cwd);
 			resolve({
 				stderr,
 				exitCode: 1,

package/dist/builtin/subagents/src/runs/foreground/execution-attempt.ts

@@ -14,7 +14,7 @@ import { extractTextFromContent, extractToolArgsPreview, getFinalOutput } from "
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
-import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
+import { formatPiSpawnError, getPiSpawnCommand, validatePiSpawnCwd } from "../shared/pi-spawn.ts";
 import { assistantStopReason, isAssistantFailureStopReason, shouldStartSubagentFinalDrain } from "../shared/final-drain.ts";
 import { modelFailureMessage } from "../shared/model-fallback.ts";
 import { createAttemptWatchdog } from "../shared/attempt-watchdog.ts";
@@ -124,6 +124,14 @@ export async function runSingleAttempt(
 			workflowStageSubagentGuard: options.workflowStageSubagentGuard,
 		}),
 	};
+	const cwdValidation = validatePiSpawnCwd(runCwd);
+	if (!cwdValidation.ok) {
+		cleanupTempDir(tempDir);
+		result.error = cwdValidation.error;
+		return finalizeSingleAttempt({
+			result, progress, exitCode: 1, interruptedByControl, allControlEvents: controlRuntime.allControlEvents, options, shared, startTime,
+		});
+	}
 	const exitCode = await new Promise<number>((resolve) => {
 		const spawnSpec = getPiSpawnCommand(args);
 		const proc = spawn(spawnSpec.command, spawnSpec.args, {
@@ -418,7 +426,7 @@ export async function runSingleAttempt(
 			attemptWatchdog.clear();
 			void jsonlWriter.close().catch(() => undefined);
 			cleanupTempDir(tempDir);
-			if (!result.error) result.error = error instanceof Error ? error.message : String(error);
+			if (!result.error) result.error = formatPiSpawnError(error, spawnSpec, runCwd);
 			finish(1);
 		});
 

package/dist/builtin/subagents/src/runs/shared/pi-spawn.ts

@@ -42,9 +42,36 @@ export interface PiSpawnDeps {
 	resolvePackageJson?: () => string;
 	resolvePackageEntry?: () => string;
 	piPackageRoot?: string;
+	statSync?: (filePath: string) => fs.Stats;
 }
 
-interface PiSpawnCommand {
+export type PiSpawnCwdValidationResult = { ok: true } | { ok: false; error: string };
+
+export function validatePiSpawnCwd(cwd: string, deps: PiSpawnDeps = {}): PiSpawnCwdValidationResult {
+	const statSync = deps.statSync ?? fs.statSync;
+	try {
+		const cwdStats = statSync(cwd);
+		if (!cwdStats.isDirectory()) return { ok: false, error: `cwd is not a directory: ${cwd}` };
+		return { ok: true };
+	} catch (error) {
+		const fsError = error as NodeJS.ErrnoException;
+		if (fsError.code === "ENOENT") return { ok: false, error: `cwd does not exist: ${cwd}` };
+		if (fsError.code === "ENOTDIR") return { ok: false, error: `cwd path contains a non-directory component: ${cwd}` };
+		const details = fsError.message ? ` (${fsError.message})` : "";
+		return { ok: false, error: `cwd is not accessible: ${cwd}${details}` };
+	}
+}
+
+export function formatPiSpawnError(error: Error, spawnSpec: PiSpawnCommand, cwd: string): string {
+	const spawnError = error as NodeJS.ErrnoException;
+	const message = error.message || String(error);
+	if (spawnError.code === "ENOENT") {
+		return `failed to spawn subagent runtime '${spawnSpec.command}' from cwd '${cwd}': runtime executable was not found or could not be launched (${message})`;
+	}
+	return `failed to spawn subagent runtime '${spawnSpec.command}' from cwd '${cwd}': ${message}`;
+}
+
+export interface PiSpawnCommand {
 	command: string;
 	args: string[];
 }

package/dist/builtin/subagents/src/tui/render-widget.ts

@@ -137,6 +137,28 @@ function getWidgetOwnerKey(ctx: ExtensionContext): string {
 	return `${sessionOwner}|cwd:${cwdOwner}`;
 }
 
+function widgetStatusText(jobs: AsyncJobState[]): string | undefined {
+	if (jobs.length === 0) return undefined;
+	const counts = new Map<string, number>();
+	for (const job of jobs) counts.set(job.status, (counts.get(job.status) ?? 0) + 1);
+	const ordered = ["running", "queued", "complete", "failed", "paused"];
+	const parts = ordered
+		.map((status) => {
+			const count = counts.get(status) ?? 0;
+			return count > 0 ? `${count} ${status}` : undefined;
+		})
+		.filter((part): part is string => part !== undefined);
+	return `Async agents: ${parts.join(", ")}`;
+}
+
+function setWidgetStatus(ctx: ExtensionContext, jobs: AsyncJobState[]): void {
+	try {
+		ctx.ui.setStatus?.(WIDGET_KEY, widgetStatusText(jobs));
+	} catch {
+		// Status mirroring must never prevent the primary widget render path.
+	}
+}
+
 function requestWidgetRender(ctx: ExtensionContext): void {
 	(ctx as RenderRequestingContext).ui.requestRender?.();
 }
@@ -150,6 +172,11 @@ function unmountWidgetBestEffort(ctx: ExtensionContext | undefined): void {
 		// reload/session rebinding, but local state still needs to move on so the
 		// next status update can mount cleanly on the active UI context.
 	}
+	try {
+		ctx.ui.setStatus?.(WIDGET_KEY, undefined);
+	} catch {
+		// Status mirroring cleanup must never block primary widget teardown.
+	}
 }
 
 function widgetSnapshotKey(jobs: AsyncJobState[]): string {
@@ -253,6 +280,7 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 			// host session disposal owns cross-owner empty-session teardown.
 			return;
 		}
+		if (ctx.hasUI) setWidgetStatus(ctx, []);
 		stopWidgetAnimation();
 		return;
 	}
@@ -271,6 +299,7 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 		mountedWidgetOwnerKey = undefined;
 		widgetMounted = false;
 	}
+	setWidgetStatus(ctx, jobs);
 	if (!widgetMounted) {
 		// belowEditor keeps the live async widget pinned to the bottom viewport,
 		// matching the workflow companion widget's placement (#1109). The pulse frame

package/dist/builtin/web-access/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/web-access",
-  "version": "0.9.5-alpha.8",
+  "version": "0.9.5-alpha.9",
   "private": true,
   "description": "Atomic extension for web search, URL fetching, GitHub repo cloning, PDF/video extraction. Fork of: https://github.com/nicobailon/pi-web-access",
   "contributors": [