@bastani/atomic 0.9.5-alpha.8 → 0.9.5

package/dist/builtin/subagents/src/extension/prompt-guidance.ts

@@ -1,13 +1,10 @@
 export const DEFAULT_PROMPT_GUIDANCE: string[] = [
-	`**Subagent Orchestration**:
-  - To avoid draining your context window, prefer to use subagents for complex tasks all non-trivial operations should be delegated to subagents.
-  - You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the \`aws\` CLI, using the \`gh\` CLI, digging through logs to \`bash\` subagents.
-  - You should use separate subagents for separate tasks, and you may launch them in parallel, but do not delegate multiple tasks that are likely to have significant overlap to separate subagents.
-  - Sometimes subagents will take a long time. DO NOT attempt to do the job yourself while waiting for the subagent to respond Instead, use the time to plan out your next steps.
-  - **Debugging**: When a user asks about debugging, spawn a debugger subagent first.
-    - Do not attempt to debug or analyze code yourself without first consulting the debugger subagent.
-    - Explain the debugger's insights to the user clearly and concisely.
-    - Once the user confirms, implement the necessary code changes based on those insights.
-    - If the user has follow-up questions, spawn additional debugger and research subagents as needed.`,
+	`**Subagent orchestration**: Use subagents selectively for bounded specialist delegation while the parent remains in control.
+  - Keep interactive, exploratory, conceptual, and conversation-led work inline when direct discussion and user steering are more useful than delegation.
+  - Use a single subagent for a focused specialty, a chain for a bounded sequential handoff, or parallel tasks for independent work. Multiple steps, files, tests, validation, or parallelism alone do not require a workflow.
+  - Delegate noisy or context-heavy command investigation when isolation helps, but run concise commands inline when that is simpler. Do not split work with substantial overlap across independent subagents.
+  - Use async/background execution selectively for genuinely long-running or independently useful delegated work. Foreground execution is appropriate when the parent needs the result before proceeding; do not duplicate a delegated job while waiting.
+  - For clearly delegated, well-defined autonomous jobs that are likely long-running/background-oriented or materially need durable stages, checkpoints, resumability, human input, gates, retries, or bounded loops, prefer an appropriate workflow rather than stretching subagent orchestration into an ad hoc workflow.
+  - Debug conceptual questions or exploratory analysis inline when appropriate. Use the debugger subagent for actual failures that need reproduction, root-cause diagnosis, and a validated fix; additional debugger or research delegates are optional when they add a distinct useful angle.`,
 ];
 

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

@@ -3,7 +3,7 @@
  */
 
 import { Type } from "typebox";
-import { MAX_SUBAGENT_NESTING_DEPTH, SUBAGENT_ACTIONS } from "../shared/types.ts";
+import { MAX_PARALLEL_TASKS, MAX_SUBAGENT_NESTING_DEPTH, SUBAGENT_ACTIONS } from "../shared/types.ts";
 
 const SkillOverride = Type.Unsafe({
 	anyOf: [
@@ -35,12 +35,25 @@ const ReadsOverride = Type.Unsafe({
 	description: "Files to read before running (array of filenames), or false to disable",
 });
 
+const RootReadsOverride = Type.Unsafe({
+	anyOf: [
+		{ type: "array", items: { type: "string" } },
+		{ type: "boolean", enum: [false] },
+	],
+	description: "Files for a single agent to read before running, or false to disable. Relative paths resolve against the effective child cwd.",
+});
+
 const JsonSchemaObject = Type.Unsafe({
 	type: "object",
 	additionalProperties: true,
 	description: "Plain JSON Schema object for structured output.",
 });
 
+const MaxOutputSchema = Type.Object({
+	bytes: Type.Optional(Type.Number()),
+	lines: Type.Optional(Type.Number()),
+}, { additionalProperties: false });
+
 const TaskItem = Type.Object({
 	agent: Type.String(), 
 	task: Type.String(), 
@@ -185,7 +198,10 @@ export const SubagentParams = Type.Object({
 		],
 		description: `Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth (integer >= 0, clamped to ${MAX_SUBAGENT_NESTING_DEPTH}). Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON.`
 	})),
-	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]" })),
+	tasks: Type.Optional(Type.Array(TaskItem, {
+		maxItems: MAX_PARALLEL_TASKS,
+		description: `PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]. Maximum ${MAX_PARALLEL_TASKS} tasks after count expansion.`,
+	})),
 	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),
 	worktree: Type.Optional(Type.Boolean({
 		description: "Create isolated git worktrees for each parallel task. " +
@@ -201,14 +217,13 @@ export const SubagentParams = Type.Object({
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),
+	maxOutput: Type.Optional(MaxOutputSchema),
 	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
 	includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
 	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
 	sessionDir: Type.Optional(
 		Type.String({ description: "Directory to store session logs (default: temp; enables sessions even if share=false)" }),
 	),
-	// Clarification TUI
-	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution. Explicit clarify: true keeps the run foreground for the clarify UI; omitted clarify can still run in the background when async: true is set." })),
 	control: Type.Optional(ControlOverrides),
 	// Solo agent overrides
 	output: Type.Optional(Type.Unsafe({
@@ -219,6 +234,8 @@ export const SubagentParams = Type.Object({
 		description: "Output file for single agent (string), or false to disable. Relative paths resolve against cwd.",
 	})),
 	outputMode: Type.Optional(OutputModeOverride),
+	reads: Type.Optional(RootReadsOverride),
+	progress: Type.Optional(Type.Boolean({ description: "Enable run-scoped progress.md tracking for a single agent under isolated artifact storage, without writing progress.md into the child cwd. This controls the child-maintained file; includeProgress separately controls whether detailed runtime telemetry is returned." })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
-});
+}, { additionalProperties: false });

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/extension/tool-description.ts

@@ -0,0 +1,29 @@
+import { APP_NAME } from "@bastani/atomic";
+
+export const SUBAGENT_TOOL_DESCRIPTION = `Delegate bounded specialist work to subagents or manage agent definitions while the parent remains in control.
+EXECUTION (use exactly ONE mode):
+• Execution calls always start non-interactively.
+• Before executing, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled.
+• SINGLE: { agent, task?, progress? } - one focused task; progress:true maintains a run-scoped progress.md under isolated artifact storage without writing it into the child cwd (separate from includeProgress, which only returns runtime telemetry); omit task for self-contained agents
+• CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - bounded sequential pipeline with optional parallel fan-out
+• PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - independent concurrent tasks (worktree: isolate each task in a git worktree)
+• Optional context: { context: "fresh" | "fork" } (default: if any requested agent has defaultContext: "fork", the whole invocation uses fork; otherwise "fresh"; inspect agent defaults via { action: "list" })
+• async:true is selective for genuinely long-running/background work; foreground is appropriate when the parent needs the result before proceeding
+CHAIN TEMPLATE VARIABLES (use in task strings):
+• {task} - The original task/request from the user
+• {previous} - Text response from the previous step (empty for first step)
+• {chain_dir} - Shared directory for chain files (e.g., <tmpdir>/${APP_NAME}-subagents-<scope>/chain-runs/abc123/)
+Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", task:"Plan based on {previous}"}] }
+MANAGEMENT (use action field, omit agent/task/chain/tasks):
+• { action: "list" } - discover executable agents/chains
+• { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
+• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
+• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
+• { action: "delete", agent: "code-analysis.custom-agent" }
+• Use chainName for chain operations; packaged chains also use dotted runtime names
+CONTROL:
+• { action: "status", id: "..." } - inspect an async/background run by id or prefix
+• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
+• { action: "resume", id: "...", message: "...", index?: 0 } - follow up with a live async child or revive a completed async/foreground child from its session
+DIAGNOSTICS:
+• { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`;

package/dist/builtin/subagents/src/intercom/intercom-bridge.ts

@@ -2,7 +2,8 @@ import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getProjectConfigDirs } from "@bastani/atomic";
+import { fileURLToPath } from "node:url";
+import { APP_NAME, getProjectConfigDirs, getEnvValue } from "@bastani/atomic";
 import type { AgentConfig } from "../agents/agents.ts";
 import type { ExtensionConfig, IntercomBridgeConfig, IntercomBridgeMode } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
@@ -12,11 +13,16 @@ const PI_INTERCOM_PACKAGE_NAME = "pi-intercom";
 function defaultAgentDir(): string {
 	return getAgentDir();
 }
+const INTERCOM_SESSION_ID_ENV = `${APP_NAME.toUpperCase()}_INTERCOM_SESSION_ID`;
 
 function defaultIntercomExtensionDir(agentDir = defaultAgentDir()): string {
 	return path.join(agentDir, "extensions", PI_INTERCOM_PACKAGE_NAME);
 }
 
+function bundledIntercomExtensionDir(): string {
+	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "intercom");
+}
+
 function defaultIntercomConfigPath(agentDir = defaultAgentDir()): string {
 	return path.join(agentDir, "intercom", "config.json");
 }
@@ -72,6 +78,8 @@ interface ResolveIntercomBridgeInput {
 }
 
 export function resolveIntercomSessionTarget(sessionName: string | undefined, sessionId: string): string {
+	const connectedIntercomSessionId = getEnvValue(INTERCOM_SESSION_ID_ENV)?.trim();
+	if (connectedIntercomSessionId) return connectedIntercomSessionId;
 	const trimmedName = sessionName?.trim();
 	if (trimmedName) return trimmedName;
 	const normalizedSessionId = sessionId.startsWith("session-") ? sessionId.slice("session-".length) : sessionId;
@@ -231,7 +239,10 @@ function configuredPiIntercomPackageDir(input: ResolveIntercomBridgeInput, agent
 }
 
 function resolveIntercomExtensionDir(input: ResolveIntercomBridgeInput, agentDir: string): string {
-	const legacyDir = path.resolve(input.extensionDir ?? defaultIntercomExtensionDir(agentDir));
+	if (input.extensionDir) return path.resolve(input.extensionDir);
+	const bundledDir = bundledIntercomExtensionDir();
+	if (packageHasPiExtension(bundledDir)) return bundledDir;
+	const legacyDir = path.resolve(defaultIntercomExtensionDir(agentDir));
 	if (fs.existsSync(legacyDir)) return legacyDir;
 	return configuredPiIntercomPackageDir(input, agentDir) ?? legacyDir;
 }

package/dist/builtin/subagents/src/intercom/result-intercom.ts

@@ -167,7 +167,7 @@ function formatNestedResultLines(children: PublicNestedRunSummary[] | undefined)
 	return lines;
 }
 
-interface GroupedResultIntercomMessageInput {
+export interface GroupedResultIntercomMessageInput {
 	to: string;
 	runId: string;
 	mode: SubagentRunMode;
@@ -276,7 +276,7 @@ export function buildSubagentResultIntercomPayload(input: GroupedResultIntercomM
 export async function deliverSubagentResultIntercomEvent(
 	events: IntercomEventBus,
 	payload: SubagentResultIntercomPayload,
-	timeoutMs = 500,
+	timeoutMs: number | false = 500,
 ): Promise<boolean> {
 	return deliverSubagentIntercomMessageEvent(events, payload.to, payload.message, timeoutMs, payload as unknown as Record<string, unknown>);
 }
@@ -285,7 +285,7 @@ export async function deliverSubagentIntercomMessageEvent(
 	events: IntercomEventBus,
 	to: string,
 	message: string,
-	timeoutMs = 500,
+	timeoutMs: number | false = 500,
 	extra: Record<string, unknown> = {},
 ): Promise<boolean> {
 	if (typeof events.on !== "function" || typeof events.emit !== "function") return false;
@@ -307,7 +307,7 @@ export async function deliverSubagentIntercomMessageEvent(
 			if (delivery.requestId !== requestId) return;
 			finish(delivery.delivered === true);
 		});
-		timer = setTimeout(() => finish(false), timeoutMs);
+		if (timeoutMs !== false) timer = setTimeout(() => finish(false), timeoutMs);
 		try {
 			events.emit(SUBAGENT_RESULT_INTERCOM_EVENT, { ...extra, to, message, requestId });
 		} catch {

package/dist/builtin/subagents/src/runs/background/async-event-journal.ts

@@ -0,0 +1,106 @@
+import * as fs from "node:fs";
+import type { DrainableSource, JsonlWriteStream } from "../../shared/jsonl-writer.ts";
+import { acquireEventWriter } from "../../shared/event-jsonl-writer.ts";
+
+const DEFAULT_TELEMETRY_BYTES = 512 * 1024;
+const CAPPED_CHILD_EVENT_TYPES = new Set([
+	"message_update", "tool_execution_update", "subagent.child.stdout", "subagent.child.stderr",
+]);
+
+interface ChildEventJournalContext {
+	runId: string;
+	stepIndex?: number;
+	agent: string;
+}
+
+interface ChildEventJournalDeps {
+	maxTelemetryBytes?: number;
+	createWriteStream?: (filePath: string) => JsonlWriteStream;
+	now?: () => number;
+}
+
+export interface ChildEventJournal {
+	append(event: Record<string, unknown>): void;
+	close(): Promise<void>;
+}
+
+function withoutKey(record: Record<string, unknown>, key: string): Record<string, unknown> {
+	const { [key]: _removed, ...rest } = record;
+	return rest;
+}
+
+/** Remove cumulative streaming snapshots while retaining compact delta metadata. */
+export function sanitizeChildEvent(event: Record<string, unknown>): Record<string, unknown> {
+	let sanitized = event;
+	if (event.type === "message_update") {
+		sanitized = withoutKey(event, "message");
+		const assistantEvent = sanitized.assistantMessageEvent;
+		if (assistantEvent && typeof assistantEvent === "object" && !Array.isArray(assistantEvent)) {
+			let compactEvent = withoutKey(withoutKey(assistantEvent as Record<string, unknown>, "partial"), "message");
+			if (!("delta" in compactEvent)) {
+				compactEvent = withoutKey(withoutKey(compactEvent, "content"), "toolCall");
+			}
+			sanitized = { ...sanitized, assistantMessageEvent: compactEvent };
+		}
+	}
+	if (event.type === "message_start") sanitized = withoutKey(sanitized, "message");
+	if (event.type === "tool_execution_update") sanitized = withoutKey(sanitized, "partialResult");
+	if (event.type === "turn_end") sanitized = withoutKey(sanitized, "message");
+	if (event.type === "agent_end") sanitized = withoutKey(sanitized, "messages");
+	return sanitized;
+}
+
+export function createChildEventJournal(
+	filePath: string | undefined,
+	source: DrainableSource,
+	context: ChildEventJournalContext,
+	deps: ChildEventJournalDeps = {},
+): ChildEventJournal {
+	if (!filePath) return { append() {}, async close() {} };
+	const createStream = deps.createWriteStream ?? ((target: string) => fs.createWriteStream(target, { flags: "a" }));
+	const writer = acquireEventWriter(filePath, source, createStream);
+	if (!writer) return { append() {}, async close() {} };
+	const maxTelemetryBytes = deps.maxTelemetryBytes ?? DEFAULT_TELEMETRY_BYTES;
+	const now = deps.now ?? Date.now;
+	let closed = false;
+	let closePromise: Promise<void> | undefined;
+	const write = (record: Record<string, unknown>): void => writer.writeLine(JSON.stringify(record));
+
+	const enrich = (event: Record<string, unknown>): Record<string, unknown> => ({
+		...event,
+		subagentSource: "child",
+		subagentRunId: context.runId,
+		subagentStepIndex: context.stepIndex,
+		subagentAgent: context.agent,
+		observedAt: now(),
+	});
+
+	return {
+		append(event) {
+			if (closed) return;
+			const sanitized = sanitizeChildEvent(event);
+			const record = enrich(sanitized);
+			const lineBytes = Buffer.byteLength(`${JSON.stringify(record)}\n`, "utf-8");
+			const assistantEvent = event.type === "message_update" && event.assistantMessageEvent
+				&& typeof event.assistantMessageEvent === "object" && !Array.isArray(event.assistantMessageEvent)
+				? event.assistantMessageEvent as Record<string, unknown>
+				: undefined;
+			const nestedTerminal = assistantEvent?.type === "done" || assistantEvent?.type === "error";
+			const capped = !nestedTerminal && typeof event.type === "string" && CAPPED_CHILD_EVENT_TYPES.has(event.type);
+			if (capped && !writer.reserveTelemetry(lineBytes, maxTelemetryBytes)) {
+				if (writer.claimTruncationMarker()) {
+					write(enrich({ type: "subagent.child.telemetry_truncated", maxTelemetryBytes }));
+				}
+				return;
+			}
+			write(record);
+		},
+		close() {
+			if (!closePromise) {
+				closed = true;
+				closePromise = writer.close();
+			}
+			return closePromise;
+		},
+	};
+}

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";
 
@@ -59,10 +59,11 @@ const jitiCliPath = resolveJitiCliPath();
 
 export function formatAsyncStartedMessage(headline: string): string {
 	return [
-		headline,
+		`Launched: ${headline}`,
+		"Completion pending; Pi will deliver the result when the detached run finishes.",
 		"",
 		"The async run is detached. Do not run sleep timers or polling loops just to wait for it.",
-		"If you have independent work, continue that work. If you have nothing else to do until the async result arrives, end your turn now; Pi will deliver the completion when the run finishes.",
+		"If you have independent work, continue that work. If you have nothing else to do until the async result arrives, end your turn now.",
 		"Use subagent({ action: \"status\", id: \"...\" }) when you need the current status/result, or to inspect a blocked/stale run. Do not poll just to wait.",
 	].join("\n");
 }
@@ -85,33 +86,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/async-execution-single.ts

@@ -4,6 +4,7 @@ import { getEnvValue } from "@bastani/atomic";
 import { buildSkillInjection, resolveSkillsWithFallback } from "../../agents/skills.ts";
 import { getSubagentCodexFastModeSettings, resolveSubagentCodexFastModeScope, resolveSubagentModelFastModeMetadata } from "../../shared/fast-mode.ts";
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
+import { injectSingleProgressInstruction, writeInitialProgressFile } from "../../shared/settings.ts";
 import { ASYNC_DIR, RESULTS_DIR, SUBAGENT_ASYNC_STARTED_EVENT, resolveChildMaxSubagentDepth } from "../../shared/types.ts";
 import { resolveChildCwd } from "../../shared/utils.ts";
 import { applyThinkingSuffix, SUBAGENT_INTERCOM_SESSION_NAME_ENV } from "../shared/pi-args.ts";
@@ -16,7 +17,7 @@ import {
 	formatAsyncStartedMessage,
 	formatAsyncStartError,
 	piPackageRoot,
-	spawnRunner,
+	spawnRunner as defaultSpawnRunner,
 } from "./async-execution-common.ts";
 import type { AsyncExecutionResult, AsyncSingleParams, AsyncSpawnResult } from "./async-execution-types.ts";
 
@@ -46,6 +47,7 @@ export function executeAsyncSingle(
 		controlIntercomTarget,
 		childIntercomTarget,
 		nestedRoute,
+		spawnRunner = defaultSpawnRunner,
 	} = params;
 	const task = params.task ?? "";
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
@@ -81,7 +83,16 @@ export function executeAsyncSingle(
 	const outputMode = params.outputMode ?? "inline";
 	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
 	if (validationError) return formatAsyncStartError("single", validationError);
-	const taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
+	let taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
+	// Keep each child's progress contract outside its cwd and isolated by run;
+	// artifacts-disabled async runs use their already run-owned async directory.
+	if (params.progress) {
+		const progressDir = artifactConfig.enabled && artifactsDir
+			? path.join(artifactsDir, "progress", id)
+			: path.join(asyncDir, "progress");
+		writeInitialProgressFile(progressDir);
+		taskWithOutputInstruction = injectSingleProgressInstruction(taskWithOutputInstruction, progressDir);
+	}
 	const model = applyThinkingSuffix(
 		resolveModelCandidate(params.modelOverride ?? agentConfig.model, availableModels, ctx.currentModelProvider),
 		agentConfig.thinking,

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

@@ -61,6 +61,7 @@ export interface AsyncSingleParams {
 	skills?: string[];
 	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
+	progress?: boolean;
 	modelOverride?: string;
 	availableModels?: AvailableModelInfo[];
 	knownModelProviders?: string[];
@@ -72,6 +73,8 @@ export interface AsyncSingleParams {
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
 	nestedRoute?: NestedRouteInfo;
+	/** Internal launch seam used by focused runtime tests. */
+	spawnRunner?: (config: object, suffix: string, cwd: string) => AsyncSpawnResult;
 }
 
 export interface AsyncExecutionResult {

package/dist/builtin/subagents/src/runs/background/async-job-tracker.ts

@@ -97,7 +97,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 	const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
 	const resultsDir = options.resultsDir ?? RESULTS_DIR;
 	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
-		renderWidget(ctx, jobs);
+		renderWidget(ctx, jobs, pi);
 	};
 	const cancelCleanup = (asyncId: string) => {
 		const existingTimer = state.cleanupTimers.get(asyncId);