pi-subagents 0.23.0 → 0.23.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [0.23.1] - 2026-05-02
+
+### Added
+- Persist async per-child session metadata and remember recent foreground child session metadata so `resume` can revive multi-child async runs and foreground children by index.
+
+### Fixed
+- Keep foreground children alive when they call `contact_supervisor` for a blocking decision by treating it as intercom coordination during parent detach, matching the generic `intercom` handoff path.
+- Pause foreground parallel and chain flows when a child detaches for intercom coordination instead of counting the child as a successful completed result and continuing the workflow, and suppress grouped completion receipts for detached chains.
+- Tighten resume/revive safety by rejecting pending async children, detached foreground children that may still be live, ambiguous foreground/async id prefixes, and exact invalid resume matches that would otherwise be masked by a prefix match in the other namespace.
+- Preserve child session metadata in stale-run repaired results and avoid advertising revive from top-level-only or missing child session files.
+- Stop builtin `reviewer` runs from writing progress by default, clarify that review-only/no-edit instructions win over progress-writing or artifact-writing instructions, and suppress automatic progress injection for explicit no-edit tasks even when chain templates use `{task}`.
+- Treat parsed provider errors as failed foreground and async subagent attempts even when the child process exits successfully, and baseline saved output files per fallback attempt.
+- Preserve output-file read and inspect errors instead of silently overwriting or falling back when a changed saved-output path cannot be read.
+- Show each active async widget row's lifecycle status (`running`, `complete`, `failed`, or `paused`) alongside activity and usage stats.
+- Start new direct, slash, prompt-template, foreground, and async subagent launches in compact view while keeping `Ctrl+O` available for live detail.
+- Label top-level async parallel completion notifications as parallel runs instead of leaking the internal chain-shaped runner plan.
+
 ## [0.23.0] - 2026-05-02
 
 ### Fixed

package/README.md

@@ -225,7 +225,7 @@ Ask oracle to review this plan. If it sees a decision I need to make, have it as
 
 The child can use one dedicated coordination tool:
 
-- `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for blocking decisions or clarification, and `reason: "progress_update"` for short non-blocking updates when a discovery changes the plan.
+- `contact_supervisor`: the child contacts the parent/supervisor session that delegated the task. Use `reason: "need_decision"` for blocking decisions or clarification, and `reason: "progress_update"` for short non-blocking updates when a discovery changes the plan. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions; no-edit wins.
 
 Child-side routine completion handoffs are still not expected. With the intercom bridge active, parent-side `pi-subagents` sends grouped completion results through `pi-intercom`: one grouped message per foreground parent `subagent` run and one per completed async result file. Acknowledged foreground delivery returns a compact receipt with artifact/session paths; if unacknowledged, the normal full output is preserved. Grouped messages include child intercom targets and full child summaries.
 
@@ -780,11 +780,12 @@ Status and control actions:
 subagent({ action: "status" })
 subagent({ action: "status", id: "<run-id>" })
 subagent({ action: "interrupt", id: "<run-id>" })
-subagent({ action: "resume", id: "<async-run-id>", message: "follow-up question" })
+subagent({ action: "resume", id: "<run-id>", message: "follow-up question" })
+subagent({ action: "resume", id: "<run-id>", index: 1, message: "follow-up for child 2" })
 subagent({ action: "doctor" })
 ```
 
-`resume` sends the follow-up directly when the async child is still reachable over intercom. After completion, it starts a new async child from the stored single-child session file.
+`resume` sends the follow-up directly when an async child is still reachable over intercom. After completion, it revives the child by starting a new async child from the stored child session file. Multi-child async runs and remembered foreground single, parallel, or chain runs can be revived by passing `index` to choose the child. Revive starts a new child process from the old session context; it does not restart the same OS process, and it requires the chosen child to have a persisted `.jsonl` session file.
 
 ## Worktree isolation
 

package/agents/reviewer.md

@@ -7,7 +7,6 @@ systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
 defaultReads: plan.md, progress.md
-defaultProgress: true
 ---
 
 You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
@@ -59,9 +58,10 @@ Review a PR or issue by understanding the context, then verifying:
 - Prefer small corrective edits over broad rewrites.
 - If everything looks good, say so plainly.
 - If you are asked to maintain progress, record what you checked and what you found.
+- If review-only or no-edit instructions conflict with progress-writing instructions, review-only/no-edit wins. Do not write `progress.md`; mention the conflict in your final review only if it matters.
 
 ## Supervisor coordination
-If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
+If runtime bridge instructions identify a safe supervisor target and you are blocked or need a decision, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing; no-edit wins. Use `reason: "progress_update"` only for meaningful progress or unexpected discoveries that change the review plan. Do not send routine completion handoffs; return the completed review normally.
 
 Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target. If no safe target is discoverable, do not guess.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/skills/pi-subagents/SKILL.md

@@ -105,7 +105,7 @@ Use this at the start of non-trivial work. Launch `scout` for local context and
 
 ### Parallel cleanup technique
 
-Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` tasks with `output: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
+Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Review-only/no-edit beats progress-writing or artifact-writing instructions. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
 
 ## Builtin Agents
 
@@ -290,6 +290,21 @@ const run = subagent({
 
 Inspect async runs with `subagent({ action: "status", id: "..." })`, `subagent({ action: "status" })` for active runs, or the `/subagents-status` slash command.
 
+Use `resume` for follow-up work after a delegated run:
+
+```typescript
+subagent({ action: "resume", id: "run-id", message: "Follow up on this point." })
+subagent({ action: "resume", id: "run-id", index: 1, message: "Continue reviewer 2." })
+```
+
+Resume behavior:
+- If an async child is still running and reachable, `resume` sends the follow-up to that live child over intercom.
+- If an async child has completed, `resume` revives it by starting a new async child from the persisted child session file.
+- Multi-child async runs require `index` unless only one running child is selectable.
+- Completed foreground single, parallel, and chain runs can also be revived by `index` while their run metadata remains in extension state.
+- Revive starts a new child process from the old session context; it does not restart the same OS process.
+- If the chosen child has no persisted `.jsonl` session file, resume fails and reports that directly.
+
 Use diagnostics when setup or child startup looks wrong:
 
 ```typescript
@@ -409,6 +424,8 @@ Use `contact_supervisor` with `reason: "need_decision"` when:
 - a child needs clarification instead of guessing
 - an approval, product, API, or scope choice is required before continuing safely
 
+Do not use `contact_supervisor` just to resolve review-only/no-edit versus progress-writing or artifact-writing instructions. No-edit wins, and the child should return review findings without touching files.
+
 Use `contact_supervisor` with `reason: "progress_update"` when:
 - a child is explicitly asked for progress
 - a meaningful discovery changes the plan

package/src/extension/index.ts

@@ -24,7 +24,7 @@ import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { renderWidget, renderSubagentResult, stopResultAnimations, stopWidgetAnimation, syncResultAnimation } from "../tui/render.ts";
 import { SubagentParams } from "./schemas.ts";
-import { createSubagentExecutor } from "../runs/foreground/subagent-executor.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";
@@ -245,6 +245,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		baseCwd: process.cwd(),
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
 		pendingForegroundControlNotices: new Map(),
@@ -336,11 +337,16 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		return new SubagentControlNoticeComponent({ ...details, noticeText: formatSubagentControlNotice(details, content) }, theme);
 	});
 
+	const executeSubagentCollapsed = (id: string, params: SubagentParamsLike, signal: AbortSignal, onUpdate: ((result: AgentToolResult<Details>) => void) | undefined, ctx: ExtensionContext) => {
+		if (ctx.hasUI) ctx.ui.setToolsExpanded(false);
+		return executor.execute(id, params, signal, onUpdate, ctx);
+	};
+
 	const slashBridge = registerSlashSubagentBridge({
 		events: pi.events,
 		getContext: () => state.lastUiContext,
 		execute: (id, params, signal, onUpdate, ctx) =>
-			executor.execute(id, params, signal, onUpdate, ctx),
+			executeSubagentCollapsed(id, params, signal, onUpdate, ctx),
 	});
 
 	const promptTemplateBridge = registerPromptTemplateDelegationBridge({
@@ -348,7 +354,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		getContext: () => state.lastUiContext,
 		execute: async (requestId, request, signal, ctx, onUpdate) => {
 			if (request.tasks && request.tasks.length > 0) {
-				return executor.execute(
+				return executeSubagentCollapsed(
 					requestId,
 					{
 						tasks: request.tasks,
@@ -363,7 +369,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 					ctx,
 				);
 			}
-			return executor.execute(
+			return executeSubagentCollapsed(
 				requestId,
 				{
 					agent: request.agent,
@@ -419,14 +425,14 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 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: "..." } - follow up with a live async child or revive a completed single-child async run from its session
+• { 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`,
 		parameters: SubagentParams,
 
 		execute(id, params, signal, onUpdate, ctx) {
-			return executor.execute(id, params, signal, onUpdate, ctx);
+			return executeSubagentCollapsed(id, params, signal, onUpdate, ctx);
 		},
 
 		renderCall(args, theme) {

package/src/extension/schemas.ts

@@ -116,7 +116,7 @@ export const SubagentParams = Type.Object({
 		description: "Async run directory for action='status' or action='resume'."
 	})),
 	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child index for actions that target a specific child." })),
-	message: Type.Optional(Type.String({ description: "Follow-up message for action='resume'." })),
+	message: Type.Optional(Type.String({ description: "Follow-up message for action='resume'. Use index to choose a child from multi-child runs." })),
 	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
 	chainName: Type.Optional(Type.String({
 		description: "Chain name for get/update/delete management actions"

package/src/intercom/intercom-bridge.ts

@@ -31,6 +31,7 @@ const DEFAULT_INTERCOM_BRIDGE_TEMPLATE = `The inherited thread is reference-only
 Use contact_supervisor first. It resolves the supervisor session "{orchestratorTarget}" and run metadata automatically.
 - Need a decision, blocked, approval, or product/API/scope ambiguity: contact_supervisor({ reason: "need_decision", message: "<question>" })
 - After contact_supervisor with reason "need_decision", stay alive and continue only after the reply arrives. Do not finish your final response with a choose-one question.
+- Do not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions. Review-only/no-edit wins; leave files unchanged and mention the conflict in your final result only if it matters.
 - Meaningful progress or unexpected discoveries that change the plan: contact_supervisor({ reason: "progress_update", message: "UPDATE: <summary>" })
 - Generic intercom is lower-level plumbing/fallback only: intercom({ action: "ask", to: "{orchestratorTarget}", message: "<question>" })
 
@@ -116,7 +117,9 @@ function intercomConfigStatus(configPath: string): { enabled: boolean; error?: u
 function readJsonBestEffort(filePath: string): unknown {
 	try {
 		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-	} catch {
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
+		if (code !== "ENOENT") console.warn(`Failed to read JSON from '${filePath}'.`, error);
 		return null;
 	}
 }

package/src/intercom/result-intercom.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
 import {
 	type Details,
 	type IntercomEventBus,
@@ -76,11 +77,15 @@ function asyncResumeGuidance(input: {
 	asyncId?: string;
 }): string | undefined {
 	if (input.source !== "async" || !input.asyncId) return undefined;
-	if (input.children.length === 1 && typeof input.children[0]?.sessionPath === "string") {
+	const resumable = input.children.filter((child) => typeof child.sessionPath === "string" && fs.existsSync(child.sessionPath));
+	if (input.children.length === 1 && resumable.length === 1) {
 		return `Revive: subagent({ action: "resume", id: "${input.asyncId}", message: "..." })`;
 	}
-	if (input.children.length > 1) return "Resume: unsupported for multi-child async runs until per-child session files are persisted.";
-	return "Resume: unavailable; no single child session file was persisted.";
+	if (resumable.length > 0) {
+		const firstIndex = resumable[0]?.index ?? input.children.indexOf(resumable[0]!);
+		return `Revive child: subagent({ action: "resume", id: "${input.asyncId}", index: ${firstIndex}, message: "..." })`;
+	}
+	return "Resume: unavailable; no child session file was persisted.";
 }
 
 function formatSubagentResultIntercomMessage(input: {

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

@@ -12,7 +12,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { applyThinkingSuffix } from "../shared/pi-args.ts";
 import { injectSingleOutputInstruction, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
-import { buildChainInstructions, isParallelStep, resolveStepBehavior, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
+import { buildChainInstructions, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../../agents/skills.ts";
@@ -65,6 +65,7 @@ interface AsyncExecutionContext {
 
 interface AsyncChainParams {
 	chain: ChainStep[];
+	task?: string;
 	resultMode?: Exclude<SubagentRunMode, "single">;
 	agents: AgentConfig[];
 	ctx: AsyncExecutionContext;
@@ -213,6 +214,10 @@ export function executeAsyncChain(
 	const chainSkills = params.chainSkills ?? [];
 	const availableModels = params.availableModels;
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
+	const firstStep = chain[0];
+	const originalTask = params.task ?? (firstStep
+		? (isParallelStep(firstStep) ? firstStep.parallel[0]?.task : (firstStep as SequentialStep).task)
+		: undefined);
 
 	for (const s of chain) {
 		const stepAgents = isParallelStep(s)
@@ -257,7 +262,7 @@ export function executeAsyncChain(
 		const a = agents.find((x) => x.name === s.agent)!;
 		const stepCwd = resolveChildCwd(runnerCwd, s.cwd);
 		const instructionCwd = behaviorCwd ?? stepCwd;
-		const behavior = resolvedBehavior ?? resolveStepBehavior(a, buildStepOverrides(s), chainSkills);
+		const behavior = suppressProgressForReadOnlyTask(resolvedBehavior ?? resolveStepBehavior(a, buildStepOverrides(s), chainSkills), s.task, originalTask);
 		const skillNames = behavior.skills === false ? [] : behavior.skills;
 		const { resolved: resolvedSkills, missing: missingSkills } = resolveSkillsWithFallback(skillNames, stepCwd, ctx.cwd);
 		if (missingSkills.includes("pi-subagents")) throw new UnavailableSubagentSkillError(UNAVAILABLE_SUBAGENT_SKILL_ERROR);
@@ -314,7 +319,7 @@ export function executeAsyncChain(
 			if (isParallelStep(s)) {
 				const parallelBehaviors = s.parallel.map((task) => {
 					const agent = agents.find((candidate) => candidate.name === task.agent)!;
-					return resolveStepBehavior(agent, buildStepOverrides(task), chainSkills);
+					return suppressProgressForReadOnlyTask(resolveStepBehavior(agent, buildStepOverrides(task), chainSkills), task.task, originalTask);
 				});
 				const progressPrecreated = parallelBehaviors.some((behavior) => behavior.progress);
 				if (progressPrecreated) {
@@ -436,7 +441,7 @@ export function executeAsyncChain(
 
 	return {
 		content: [{ type: "text", text: formatAsyncStartedMessage(`Async ${resultMode}: ${chainDesc} [${id}]`) }],
-		details: { mode: resultMode, results: [], asyncId: id, asyncDir },
+		details: { mode: resultMode, runId: id, results: [], asyncId: id, asyncDir },
 	};
 }
 
@@ -568,6 +573,6 @@ export function executeAsyncSingle(
 
 	return {
 		content: [{ type: "text", text: formatAsyncStartedMessage(`Async: ${agent} [${id}]`) }],
-		details: { mode: "single", results: [], asyncId: id, asyncDir },
+		details: { mode: "single", runId: id, results: [], asyncId: id, asyncDir },
 	};
 }

package/src/runs/background/async-resume.ts

@@ -39,7 +39,7 @@ interface AsyncResultFile {
 	success?: boolean;
 	cwd?: string;
 	sessionFile?: string;
-	results?: Array<{ agent?: string; success?: boolean; intercomTarget?: string }>;
+	results?: Array<{ agent?: string; success?: boolean; sessionFile?: string; intercomTarget?: string }>;
 }
 
 export interface AsyncRunLocation {
@@ -59,10 +59,10 @@ function ensureObject(value: unknown, source: string): Record<string, unknown> {
 	return value as Record<string, unknown>;
 }
 
-function validateOptionalString(value: Record<string, unknown>, field: string, source: string): string | undefined {
+function validateOptionalString(value: Record<string, unknown>, field: string, source: string, displayField = field): string | undefined {
 	const fieldValue = value[field];
 	if (fieldValue === undefined) return undefined;
-	if (typeof fieldValue !== "string") throw new Error(`Invalid async result file '${source}': ${field} must be a string.`);
+	if (typeof fieldValue !== "string") throw new Error(`Invalid async result file '${source}': ${displayField} must be a string.`);
 	return fieldValue;
 }
 
@@ -74,11 +74,12 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
 		if (!Array.isArray(resultsValue)) throw new Error(`Invalid async result file '${resultPath}': results must be an array.`);
 		results = resultsValue.map((entry, index) => {
 			const child = ensureObject(entry, `${resultPath} results[${index}]`);
-			const agent = validateOptionalString(child, "agent", `${resultPath} results[${index}]`);
-			const intercomTarget = validateOptionalString(child, "intercomTarget", `${resultPath} results[${index}]`);
+			const agent = validateOptionalString(child, "agent", resultPath, `results[${index}].agent`);
+			const sessionFile = validateOptionalString(child, "sessionFile", resultPath, `results[${index}].sessionFile`);
+			const intercomTarget = validateOptionalString(child, "intercomTarget", resultPath, `results[${index}].intercomTarget`);
 			const success = child.success;
 			if (success !== undefined && typeof success !== "boolean") throw new Error(`Invalid async result file '${resultPath}': results[${index}].success must be a boolean.`);
-			return { agent, intercomTarget, ...(typeof success === "boolean" ? { success } : {}) };
+			return { agent, sessionFile, intercomTarget, ...(typeof success === "boolean" ? { success } : {}) };
 		});
 	}
 	const success = data.success;
@@ -210,6 +211,7 @@ function validateStatusForResume(status: AsyncStatus | null, source: string): vo
 		status.steps.forEach((step, index) => {
 			if (!step || typeof step !== "object" || Array.isArray(step)) throw new Error(`Invalid async status '${source}': steps[${index}] must be an object.`);
 			if (typeof step.agent !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);
+			if (step.sessionFile !== undefined && typeof step.sessionFile !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].sessionFile must be a string.`);
 		});
 	}
 }
@@ -243,38 +245,62 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 	const resultSteps = result?.results ?? [];
 	const stepCount = statusSteps.length || resultSteps.length || (result?.agent ? 1 : 0);
 	const requestedIndex = params.index;
+	if (requestedIndex !== undefined && !Number.isInteger(requestedIndex)) throw new Error(`Async run '${runId}' index must be an integer.`);
+	const terminalStepStatuses = new Set(["complete", "completed", "failed", "paused"]);
 
 	if (state === "running") {
-		const running = statusSteps
-			.map((step, index) => ({ step, index }))
-			.filter(({ step }) => step.status === "running");
-		const selected = requestedIndex !== undefined
-			? running.find(({ index }) => index === requestedIndex)
-			: running.length === 1 ? running[0] : undefined;
-		if (!selected) {
-			throw new Error(`Async run '${runId}' has ${running.length} running children. Provide index to choose one.`);
+		if (requestedIndex !== undefined) {
+			if (requestedIndex < 0 || requestedIndex >= stepCount) throw new Error(`Async run '${runId}' has ${stepCount} children. Index ${requestedIndex} is out of range.`);
+			const selectedStep = statusSteps[requestedIndex];
+			if (selectedStep?.status === "running") {
+				return {
+					kind: "live",
+					runId,
+					asyncDir: location.asyncDir ?? undefined,
+					state,
+					agent: selectedStep.agent,
+					index: requestedIndex,
+					intercomTarget: resolveSubagentIntercomTarget(runId, selectedStep.agent, requestedIndex),
+					cwd: status?.cwd ?? result?.cwd,
+					sessionFile: selectedStep.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
+				};
+			}
+			if (selectedStep?.status === "pending") throw new Error(`Async run '${runId}' child ${requestedIndex} is pending and has not started yet. Wait for it to run or complete before resuming.`);
+			if (selectedStep && !terminalStepStatuses.has(selectedStep.status)) throw new Error(`Async run '${runId}' child ${requestedIndex} is ${selectedStep.status} and cannot be revived yet.`);
+		} else {
+			const running = statusSteps
+				.map((step, index) => ({ step, index }))
+				.filter(({ step }) => step.status === "running");
+			const selected = running.length === 1 ? running[0] : undefined;
+			if (!selected) {
+				throw new Error(`Async run '${runId}' has ${running.length} running children. Provide index to choose one.`);
+			}
+			return {
+				kind: "live",
+				runId,
+				asyncDir: location.asyncDir ?? undefined,
+				state,
+				agent: selected.step.agent,
+				index: selected.index,
+				intercomTarget: resolveSubagentIntercomTarget(runId, selected.step.agent, selected.index),
+				cwd: status?.cwd ?? result?.cwd,
+				sessionFile: selected.step.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
+			};
 		}
-		return {
-			kind: "live",
-			runId,
-			asyncDir: location.asyncDir ?? undefined,
-			state,
-			agent: selected.step.agent,
-			index: selected.index,
-			intercomTarget: resolveSubagentIntercomTarget(runId, selected.step.agent, selected.index),
-			cwd: status?.cwd ?? result?.cwd,
-			sessionFile: status?.sessionFile ?? result?.sessionFile,
-		};
 	}
 
-	if (stepCount !== 1) {
-		throw new Error(`Async run '${runId}' has ${stepCount} children. Resume currently supports single-child async runs because per-child session files are not persisted.`);
+	if (stepCount > 1 && requestedIndex === undefined) {
+		throw new Error(`Async run '${runId}' has ${stepCount} children. Provide index to choose one.`);
 	}
 	const index = requestedIndex ?? 0;
+	if (!Number.isInteger(index)) throw new Error(`Async run '${runId}' index must be an integer.`);
+	if (index < 0 || index >= stepCount) throw new Error(`Async run '${runId}' has ${stepCount} children. Index ${index} is out of range.`);
 	const agent = statusSteps[index]?.agent ?? resultSteps[index]?.agent ?? result?.agent;
 	if (!agent) throw new Error(`Could not determine child agent for async run '${runId}'.`);
-	const sessionFile = status?.sessionFile ?? result?.sessionFile;
-	if (!sessionFile) throw new Error(`Async run '${runId}' does not have a persisted child session file to resume from.`);
+	const sessionFile = statusSteps[index]?.sessionFile
+		?? resultSteps[index]?.sessionFile
+		?? (stepCount === 1 ? status?.sessionFile ?? result?.sessionFile : undefined);
+	if (!sessionFile) throw new Error(`Async run '${runId}' child ${index} does not have a persisted session file to resume from.`);
 	const resolvedSessionFile = validateResumeSessionFile(runId, sessionFile);
 
 	return {
@@ -292,9 +318,9 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 
 export function buildRevivedAsyncTask(target: AsyncResumeTarget, message: string): string {
 	return [
-		"You are reviving a completed async subagent conversation.",
+		"You are reviving a previous subagent conversation.",
 		"",
-		`Original async run: ${target.runId}`,
+		`Original run: ${target.runId}`,
 		`Original agent: ${target.agent}`,
 		target.sessionFile ? `Original session file: ${target.sessionFile}` : undefined,
 		"",

package/src/runs/background/result-watcher.ts

@@ -76,6 +76,7 @@ export function createResultWatcher(
 					output?: string;
 					error?: string;
 					success?: boolean;
+					sessionFile?: string;
 					artifactPaths?: { outputPath?: string };
 					intercomTarget?: string;
 				}>;
@@ -120,6 +121,7 @@ export function createResultWatcher(
 						const summary = result.success === false && result.error
 							? `${result.error}${hasRealOutput ? `\n\nOutput:\n${baseOutput}` : ""}`
 							: output;
+						const sessionPath = result.sessionFile ?? (childResults.length === 1 ? data.sessionFile : undefined);
 						return {
 							agent: result.agent ?? data.agent ?? `step-${index + 1}`,
 							status: resolveSubagentResultStatus({
@@ -129,7 +131,7 @@ export function createResultWatcher(
 							summary,
 							index,
 							artifactPath: result.artifactPaths?.outputPath,
-							sessionPath: data.sessionFile,
+							...(typeof sessionPath === "string" && fsApi.existsSync(sessionPath) ? { sessionPath } : {}),
 							intercomTarget: result.intercomTarget,
 						};
 					}),

package/src/runs/background/run-status.ts

@@ -28,8 +28,24 @@ function activityText(activityState: unknown, lastActivityAt: unknown): string |
 	return activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
 }
 
-function canShowRevive(stepCount: number, sessionFile: unknown): sessionFile is string {
-	return stepCount === 1 && typeof sessionFile === "string" && fs.existsSync(sessionFile);
+function hasExistingSessionFile(value: unknown): value is string {
+	return typeof value === "string" && fs.existsSync(value);
+}
+
+function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown }>, fallbackSessionFile?: unknown): string {
+	const knownChildren = children
+		.map((child, index) => ({ child, index }))
+		.filter(({ child }) => typeof child.agent === "string");
+	if (!runId || knownChildren.length === 0) return "Resume: unavailable; no child session file was persisted.";
+	const singleSessionFile = knownChildren[0]?.child.sessionFile ?? fallbackSessionFile;
+	if (children.length === 1 && knownChildren.length === 1 && hasExistingSessionFile(singleSessionFile)) {
+		return `Revive: subagent({ action: "resume", id: "${runId}", message: "..." })`;
+	}
+	const childWithSession = knownChildren.find(({ child }) => hasExistingSessionFile(child.sessionFile));
+	if (childWithSession) {
+		return `Revive child: subagent({ action: "resume", id: "${runId}", index: ${childWithSession.index}, message: "..." })`;
+	}
+	return "Resume: unavailable; no child session file was persisted.";
 }
 
 function stepLineLabel(status: AsyncStatus, index: number): string {
@@ -137,14 +153,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			}
 			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
 			if (status.state !== "running") {
-				const stepCount = status.steps?.length ?? 0;
-				if (canShowRevive(stepCount, status.sessionFile)) {
-					lines.push(`Revive: subagent({ action: "resume", id: "${status.runId}", message: "..." })`);
-				} else if (stepCount > 1) {
-					lines.push("Resume: unsupported for multi-child async runs until per-child session files are persisted.");
-				} else {
-					lines.push("Resume: unavailable; no single child session file was persisted.");
-				}
+				lines.push(formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile));
 			}
 			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
 			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
@@ -156,18 +165,12 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 	if (resultPath) {
 		try {
 			const raw = fs.readFileSync(resultPath, "utf-8");
-			const data = JSON.parse(raw) as { id?: string; runId?: string; agent?: string; success?: boolean; summary?: string; exitCode?: number; state?: string; sessionFile?: string; results?: Array<{ agent?: string }> };
+			const data = JSON.parse(raw) as { id?: string; runId?: string; agent?: string; success?: boolean; summary?: string; exitCode?: number; state?: string; sessionFile?: string; results?: Array<{ agent?: string; sessionFile?: string }> };
 			const status = data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
 			const runId = data.runId ?? data.id ?? resolvedId;
 			const lines = [`Run: ${runId}`, `State: ${status}`, `Result: ${resultPath}`];
-			const stepCount = Array.isArray(data.results) ? data.results.length : data.agent ? 1 : 0;
-			if (runId && canShowRevive(stepCount, data.sessionFile)) {
-				lines.push(`Revive: subagent({ action: "resume", id: "${runId}", message: "..." })`);
-			} else if (stepCount > 1) {
-				lines.push("Resume: unsupported for multi-child async runs until per-child session files are persisted.");
-			} else {
-				lines.push("Resume: unavailable; no single child session file was persisted.");
-			}
+			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
+			lines.push(formatResumeGuidance(runId, children, data.sessionFile));
 			if (data.summary) lines.push("", data.summary);
 			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
 		} catch (error) {

package/src/runs/background/stale-run-reconciler.ts

@@ -76,6 +76,7 @@ interface ResultChildOutcome {
 	agent?: string;
 	success?: boolean;
 	error?: string;
+	sessionFile?: string;
 	model?: string;
 	attemptedModels?: string[];
 	modelAttempts?: NonNullable<AsyncStatus["steps"]>[number]["modelAttempts"];
@@ -119,6 +120,7 @@ function terminalStatusFromResult(status: AsyncStatus, resultPath: string, now:
 			durationMs: step.startedAt !== undefined && step.durationMs === undefined ? Math.max(0, now - step.startedAt) : step.durationMs,
 			exitCode: step.exitCode ?? (state === "complete" || state === "paused" ? 0 : 1),
 			error: state === "failed" ? step.error ?? child?.error : step.error,
+			sessionFile: step.sessionFile ?? child?.sessionFile,
 			model: step.model ?? child?.model,
 			attemptedModels: step.attemptedModels ?? child?.attemptedModels,
 			modelAttempts: step.modelAttempts ?? child?.modelAttempts,
@@ -204,6 +206,7 @@ function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, r
 				model: step.model,
 				attemptedModels: step.attemptedModels,
 				modelAttempts: step.modelAttempts,
+				sessionFile: step.sessionFile,
 			})),
 			exitCode: 1,
 			timestamp: now,