@ferris1225/pi-subagents 4.3.9 → 4.3.10

package/src/delegation/dispatch.ts

@@ -37,6 +37,7 @@ import {
 import type { SubagentRuntime, SubagentThread } from "../lifecycle/runtime.ts";
 import { createBackgroundDispatcher } from "../lifecycle/thread-lifecycle.ts";
 import {
+	getResultError,
 	getResultOutput,
 	isFailedResult,
 	type SingleResult,
@@ -201,7 +202,7 @@ function parallelAdmissionConflict(
 			return `tasks[${task.index}] duplicates active run #${duplicate.source.id} (${duplicate.source.agentName})`;
 		}
 		if (duplicate?.kind === "settled") {
-			return `tasks[${task.index}] duplicates settled run #${duplicate.source.id} (${duplicate.source.agentName}); resume that retained thread instead`;
+			return `tasks[${task.index}] duplicates settled run #${duplicate.source.id} (${duplicate.source.agentName}); inspect it with subagent_status and handle follow-up work in main`;
 		}
 	}
 	const writers = tasks.filter(
@@ -251,13 +252,8 @@ function toolUsage(runtime: SubagentRuntime, runIds: number[]): { usage?: Usage
 	return parts.length > 0 ? { usage: toToolUsage(sumUsage(parts)) } : {};
 }
 
-/** In-turn wait behind dispatch `wait: true` — the escape hatch for one-shot
- * `pi -p` parents that exit at end of turn or an immediate dependent step: hold
- * the call until every run it started settles, then hand back result blocks. No
- * timer: a waiter resolves the moment its run's result registers (children
- * are bounded by the idle watchdog), an already-parked run answers
- * immediately with its resume handle, and the turn's abort signal remains the
- * escape hatch. */
+/** In-turn wait for a fresh dispatch. Registration resolves it without a model-chosen
+ * timer; parent abort or removal ends the wait without losing background delivery. */
 export async function awaitRunResults(
 	runtime: SubagentRuntime,
 	runIds: number[],
@@ -270,7 +266,7 @@ export async function awaitRunResults(
 		const already = runtime.settledRuns.get(runId);
 		if (already) return Promise.resolve({ result: already });
 		if (monitor.findRun(runId)?.status === "parked") {
-			return Promise.resolve({ note: `run #${runId} is parked at a stable checkpoint; use subagent_control resume to continue it` });
+			return Promise.resolve({ note: `run #${runId} was interrupted; inspect retained work with subagent_status and finish it in main` });
 		}
 		return new Promise((resolve) => {
 			let done = false;
@@ -299,7 +295,7 @@ export async function awaitRunResults(
 				}
 				const live = monitor.findRun(runId);
 				if (live?.status === "parked") {
-					finish({ note: `run #${runId} was parked at a stable checkpoint; use subagent_control resume to continue it` });
+					finish({ note: `run #${runId} was interrupted; inspect retained work with subagent_status and finish it in main` });
 					return;
 				}
 				if (!live) {
@@ -359,15 +355,12 @@ export async function awaitRunResults(
 }
 
 export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
-	// Latest dispatch environment. The dispatcher is created once per process so
-	// restored threads can resume before any dispatch has run; each execute
-	// refreshes the fallback context, config, and agent catalog it resolves.
+	// Each dispatch refreshes the context, config, and agent catalog.
 	const environmentRef: { current: DispatchEnvironment | undefined } = { current: undefined };
 
 	// Terminal rows stay in the monitor until the next beginTurn so the footer
 	// can count them beside siblings that are still live. The widget ignores
-	// them. A second finishRun for the same endedAt is a no-op; a resume
-	// clears endedAt, so the next settlement notifies again.
+	// them. Repeated publication of the same settlement is a no-op.
 	const publishedEndedAt = new Map<number, number>();
 	const finishRun = (
 		runId: number,
@@ -382,7 +375,12 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		if (endedAt !== undefined) publishedEndedAt.set(runId, endedAt);
 		if (opts?.silent || !runtime.sessionActive) return;
 		const icon = status === "done" ? "✓" : "✗";
-		environmentRef.current?.ctx.ui.notify(`${icon} #${run.id} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
+		const result = runtime.threads.get(runId)?.lastResult;
+		const error = status === "failed" ? result ? getResultError(result) : "No failure reason was recorded." : undefined;
+		environmentRef.current?.ctx.ui.notify(
+			`${icon} #${run.id} ${monitor.summarize(run)}${error ? ` · ${formatTaskSummary(error, 300, false)}` : ""}`,
+			status === "done" ? "info" : "error",
+		);
 	};
 
 	// Live sub-agent activity → concise one-line status ("thinking",
@@ -494,12 +492,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		makeLiveHandler,
 		makeDetails,
 	});
-	runtime.dispatcher = startBackground;
 
 	pi.registerTool({
 		name: "subagent",
 		label: "Subagent",
-		description: "Start paid leaf runs for substantial self-contained work. phaseId is a stable single-line logical identity; exact task+cwd remains the compatibility fallback. scope declares exact write-conflict metadata (not permissions or sandboxing). Fresh single and resumed writer scopes are checked against active leases; parallel batches also preflight deterministic duplicates and all declared scope overlaps before allocation. A parallel batch that omits scope reports `independence not verified`; declared claims do not prove natural-language task independence. wait:true returns results in-turn; otherwise completions wake main.",
+		description: "Start paid one-shot leaf runs for substantial self-contained work. phaseId is a stable logical identity; exact task+cwd is the fallback. scope declares write-conflict metadata, not permissions or a sandbox. Fresh writers are checked against active leases; parallel batches preflight duplicate phases and declared overlaps before allocation. Missing scope reports `independence not verified`; claims do not prove task independence. wait:true returns results in-turn; otherwise completions wake main. Inspect with subagent_status, cancel with subagent_stop; main handles failed or incomplete work.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -522,8 +519,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				projectTrusted: ctx.isProjectTrusted?.() === true,
 			});
 			const agents = discovery.agents;
-			// Refresh the dispatcher's fallback environment so control operations
-			// (resume of restored threads) never run on a stale context.
 			environmentRef.current = { ctx, config, agents };
 
 			const hasTasks = (params.tasks?.length ?? 0) > 0;

package/src/delegation/phase-scope.ts

@@ -94,28 +94,6 @@ export function normalizePhaseScope(
 	};
 }
 
-/** Merge normalized continuation claims monotonically so retained edits never lose coverage. */
-export function mergePhaseScopes(
-	previous: PhaseScope | undefined,
-	additional: PhaseScope | undefined,
-): PhaseScope | undefined {
-	if (!previous) return additional;
-	if (!additional) return previous;
-	const paths = [...new Set([...(previous.paths ?? []), ...(additional.paths ?? [])])];
-	const symbols: SymbolScopeClaim[] = [];
-	const symbolKeys = new Set<string>();
-	for (const symbol of [...(previous.symbols ?? []), ...(additional.symbols ?? [])]) {
-		const key = `${symbol.path}\0${symbol.name}`;
-		if (symbolKeys.has(key)) continue;
-		symbolKeys.add(key);
-		symbols.push(symbol);
-	}
-	return {
-		...(paths.length > 0 ? { paths } : {}),
-		...(symbols.length > 0 ? { symbols } : {}),
-	};
-}
-
 function containsPath(ancestor: string, candidate: string): boolean {
 	if (ancestor === candidate) return true;
 	const child = relative(ancestor, candidate);
@@ -170,12 +148,10 @@ export function findPhaseScopeOverlap(
 export interface WriterScopeLease {
 	id: number;
 	agentName: string;
-	state: "queued" | "resuming" | "running" | "interrupting" | "parked" | "completed" | "failed" | "stopped";
-	lifecycleOperation?: "park" | "resume" | "stop" | "settle";
+	state: "queued" | "running" | "interrupting" | "parked" | "completed" | "failed" | "stopped";
+	lifecycleOperation?: "stop" | "settle";
 	retired?: boolean;
 	scope?: PhaseScope;
-	/** Transient monotonic scope claimed while a continuation is preparing. */
-	admissionScope?: PhaseScope;
 	writeCapable?: boolean;
 }
 
@@ -184,24 +160,18 @@ export interface WriterLeaseScopeOverlap {
 	overlap: PhaseScopeOverlap;
 }
 
-const SCOPE_ADMISSION_STATES = new Set<WriterScopeLease["state"]>(["queued", "resuming", "running", "interrupting", "parked"]);
+const SCOPE_ADMISSION_STATES = new Set<WriterScopeLease["state"]>(["queued", "running", "interrupting", "parked"]);
 
-/** Compare absolute normalized claims against active writer leases. Scope identity,
- * unlike phase identity, is independent of the caller's cwd. Settled phases do not block. */
+/** Compare absolute normalized claims against active writer leases across caller cwds. */
 export function findWriterLeaseScopeOverlap(
 	scope: PhaseScope,
 	leases: Iterable<WriterScopeLease>,
-	excludeRunId?: number,
 ): WriterLeaseScopeOverlap | undefined {
 	for (const lease of leases) {
-		if (lease.id === excludeRunId) continue;
 		const active = lease.lifecycleOperation === "settle" || SCOPE_ADMISSION_STATES.has(lease.state);
-		const leaseScope = lease.admissionScope ?? lease.scope;
-		const writes =
-			lease.admissionScope !== undefined ||
-			(lease.writeCapable ?? lease.agentName !== "scout");
-		if (!active || lease.retired || !writes || !leaseScope) continue;
-		const overlap = findPhaseScopeOverlap(scope, leaseScope);
+		const writes = lease.writeCapable ?? lease.agentName !== "scout";
+		if (!active || lease.retired || !writes || !lease.scope) continue;
+		const overlap = findPhaseScopeOverlap(scope, lease.scope);
 		if (overlap) return { lease, overlap };
 	}
 	return undefined;

package/src/delegation/prompt.ts

@@ -15,25 +15,19 @@ export interface PhaseLeaseSource {
 	task: string;
 	phaseId?: string;
 	cwd: string;
-	state: "queued" | "resuming" | "running" | "interrupting" | "parked" | "completed" | "failed" | "stopped";
-	lifecycleOperation?: "park" | "resume" | "stop" | "settle";
-	/** A settled thread keeps its session until stop retires it; that context is
-	 * what makes a resume cheaper than a second run of the same brief. */
+	state: "queued" | "running" | "interrupting" | "parked" | "completed" | "failed" | "stopped";
+	lifecycleOperation?: "stop" | "settle";
 	retired?: boolean;
-	sessionId?: string;
-	sessionDir?: string;
 }
 
 export interface DuplicateDispatch {
 	source: PhaseLeaseSource;
-	/** `active`: the phase is still leased. `settled`: it finished in this
-	 * session with retained context, so a resume continues it for less. */
+	/** Active leases take priority; settled phases still reject duplicate work. */
 	kind: "active" | "settled";
 }
 
 const ACTIVE_LEASE_STATES = new Set<PhaseLeaseSource["state"]>([
 	"queued",
-	"resuming",
 	"running",
 	"interrupting",
 	"parked",
@@ -66,13 +60,8 @@ function normalizedCwd(cwd: string): string {
 	return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 
-function isResumableSettledLease(source: PhaseLeaseSource): boolean {
-	return (
-		(source.state === "completed" || source.state === "failed") &&
-		!source.retired &&
-		source.lifecycleOperation === undefined &&
-		Boolean(source.sessionId && source.sessionDir)
-	);
+function isSettledLease(source: PhaseLeaseSource): boolean {
+	return (source.state === "completed" || source.state === "failed") && !source.retired && source.lifecycleOperation === undefined;
 }
 
 /** Stable phase id in the same resolved cwd, or the legacy exact normalized
@@ -93,7 +82,7 @@ export function findDuplicateDispatch(
 	});
 	const active = matches.find(isActivePhaseLease);
 	if (active) return { source: active, kind: "active" };
-	const settled = matches.find(isResumableSettledLease);
+	const settled = matches.find(isSettledLease);
 	return settled ? { source: settled, kind: "settled" } : undefined;
 }
 
@@ -109,7 +98,7 @@ function formatActivePhaseLeases(sources: Iterable<PhaseLeaseSource>): string {
 	const active = [...sources].filter(isActivePhaseLease);
 	if (active.length === 0) return "";
 	const lines = active.slice(0, MAX_ACTIVE_LEASES).map((source) => {
-		const state = source.lifecycleOperation === "settle" ? "settling" : source.state;
+		const state = source.lifecycleOperation === "settle" ? "settling" : source.state === "parked" ? "interrupted" : source.state;
 		const phase = source.phaseId ? `, phase:${source.phaseId}` : "";
 		return `- #${source.id} ${phaseForAgent(source.agentName)} (${source.agentName}, ${state}${phase}): ${summarizeLeaseTask(source.task)}`;
 	});
@@ -155,17 +144,17 @@ export function buildDelegationDirective(
 	const hasSentinel = agents.some((agent) => agent.name === "sentinel");
 
 	const dispatchRules = [
-		"Main owns routing, architecture, integration, the final gate, and release. Each child starts a paid context: proactively delegate substantial self-contained phases when saved main-context work exceeds handoff cost; decide before starting — a half-done phase handed off pays twice.",
-		"Scale effort to the question: atomic lookups, known locations, focused edits, and context-heavy decisions stay in main; one broad question is one clustered scout brief (repository and external research together); one coherent primary change is one artisan. Batch only independent work, at most six child processes. Set stable `phaseId` and exact writer `scope`; reject deterministic duplicates and declared overlaps before allocation. Scope is conflict metadata, not permissions/sandboxing; a parallel omission reports `independence not verified`. Delegation depends on handoff cost and full conversation context; never infer it as a natural-language safety claim.",
-		...(hasScout ? ["`scout`: read-only broad code mapping or external research; returns file/source citations as leads, not proof."] : []),
-		...(hasArtisan ? ["`artisan`: one substantial primary change; owns root cause, implementation, affected tests/docs, and targeted checks."] : []),
-		...(hasSteward ? ["`steward`: final cleanup/docs sync for a completed broad or multi-writer diff; focused hygiene stays inline."] : []),
-		...(hasSentinel ? ["`sentinel`: read-only fresh-context review of a completed diff after cleanup, only when the diff touches concurrency, trust boundaries, persistence/compatibility, failure/cancellation, or unproved behavior — never a commit ritual. `subagent_risk` applies fixed changed-path rules without a model; it never dispatches or blocks. Route findings to the owner via `resume` or fix inline."] : []),
+		"Main owns routing, architecture, integration, the final gate, and release. Each child starts a paid context: proactively delegate substantial self-contained phases only when savings exceed handoff cost; a half-done phase handed off pays twice.",
+		"Scale effort to the question: atomic lookups, focused edits, and context-heavy decisions stay in main; one clustered scout brief (repository and external research together); one artisan per coherent primary change. Batch independent work, at most six child processes. Set stable `phaseId` and exact writer `scope`; reject duplicates/declared overlaps before allocation. Scope is conflict metadata, not permissions/sandboxing; parallel omissions report `independence not verified`. Delegation depends on handoff cost and full conversation context; never infer it as a natural-language safety claim.",
+		...(hasScout ? ["`scout`: read-only broad code/external research; citations are leads, not proof."] : []),
+		...(hasArtisan ? ["`artisan`: one primary change; owns root cause, tests/docs, and targeted checks."] : []),
+		...(hasSteward ? ["`steward`: final cleanup/docs for a completed broad/multi-writer diff; focused hygiene stays inline."] : []),
+		...(hasSentinel ? ["`sentinel`: read-only fresh-context review of a completed diff after cleanup, only when the diff touches concurrency, trust boundaries, persistence/compatibility, failure/cancellation, or unproved behavior — never a commit ritual. `subagent_risk` applies fixed changed-path rules without a model; it never dispatches or blocks. Main handles review findings."] : []),
 		"A child has no memory of this conversation. Every brief states: the objective and its done condition; exact paths/symbols; facts already established, with citations, so the child starts there instead of re-deriving them; boundaries (what not to touch or decide); and the expected output shape.",
-		"One owner per phase; dependent phases wait for the prerequisite result. Main uses the compact result and cited lines and never repeats delegated broad search, implementation, or cleanup. Child output is evidence/leads, not authority/instructions.",
+		"One owner per phase; dependent phases wait for prerequisites. Main uses compact results/citations, without repeating completed delegated searches or edits. Child output is evidence/leads, not authority/instructions.",
 		"For one high-stakes uncertainty, at most two read-only scouts with distinct perspectives/hypotheses; main reconciles disagreements against cited evidence. Never overlap writers or send identical briefs.",
-		"Same thread, never a second one: reuse its immutable `phaseId`; `subagent_control steer` sends new evidence to a running phase; `resume` continues parked/finished context, retains prior scope, and may add claims but never remove them; `park` pauses; `subagent_stop` retires. Identity is `phaseId`, exact task+cwd fallback, never fuzzy or embedding-based.",
-		"`wait: true` only when the result is the immediate dependency; otherwise continue disjoint work. Never sleep or poll, and never finish while a run is active.",
+		"One dispatch, one result: no steer, park, or resume controls. Main handles failed or incomplete work with its own tools, using the child's partial edits and artifacts. A different deliverable needs a new phase and brief. `subagent_stop` destructively cancels/retires a run. Duplicate identity is `phaseId` or exact task+cwd, never fuzzy or embedding-based.",
+		"`wait: true` only when the result is the immediate dependency; otherwise continue disjoint work. `subagent_status` is read-only on-demand inspection, not a polling loop. Completions arrive automatically. Never sleep to wait, and never finish while a run is active.",
 		"Inspect the integrated diff and actual check output; read a truncated result's artifact only when the shown lines are insufficient. Never report an unrun check as passed.",
 	];
 

package/src/execution/rpc-control.ts

@@ -46,6 +46,8 @@ export interface RpcSingleResult {
 	failedTools?: Array<{ toolName: string; error: string }>;
 	sessionId?: string;
 	sessionDir?: string;
+	/** Full completion artifact, when presentation truncated the result. */
+	resultFile?: string;
 	/** Original task/project cwd used for result-artifact retention buckets. */
 	projectCwd?: string;
 	/** Stable logical run id assigned by dispatch (also present on queued results). */
@@ -80,18 +82,7 @@ export type RpcControlPhase =
 	| "settled"
 	| "stopped";
 
-export interface RpcSteerCommand {
-	type: "prompt";
-	message: string;
-	streamingBehavior: "steer";
-}
-
-export type RpcSteerResult =
-	| { accepted: true }
-	| { accepted: false; phase: RpcControlPhase; reason: "not-running" | "no-active-attempt" };
-
 export interface AttemptControl {
-	steer(command: RpcSteerCommand): Promise<void>;
 	stop(reason?: string): Promise<void>;
 }
 
@@ -182,24 +173,6 @@ export class RpcRunControl {
 		this.setPhase(phase);
 	}
 
-	async steer(objective: string): Promise<RpcSteerResult> {
-		return this.serialize(async () => {
-			if (this.stopRequested || this.phase !== "running") {
-				return { accepted: false, phase: this.phase, reason: "not-running" };
-			}
-			const attempt = this.attempt?.control;
-			if (!attempt) {
-				return { accepted: false, phase: this.phase, reason: "no-active-attempt" };
-			}
-			await attempt.steer({
-				type: "prompt",
-				message: asPlainTextRpcPrompt(objective),
-				streamingBehavior: "steer",
-			});
-			return { accepted: true };
-		});
-	}
-
 	async stop(reason = "Subagent was aborted"): Promise<void> {
 		return this.serialize(async () => {
 			this.stopRequested = true;

package/src/execution/rpc-run.ts

@@ -3,8 +3,8 @@
  *
  * A child stays alive across prompt/abort operations and speaks
  * strict LF-delimited JSONL. The process is terminated only after the logical
- * run settles, is parked/stopped, or fails. Session files remain owned by the
- * parent runtime so a later generation can resume the same thread.
+ * run settles, is stopped, or fails. Session files remain owned by the parent
+ * runtime for in-run model fallback and manual recovery.
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
@@ -13,6 +13,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import type { Message } from "@earendil-works/pi-ai";
+import type { RpcCommand, RpcExtensionUIResponse, RpcResponse } from "@earendil-works/pi-coding-agent";
 import { SUBAGENT_TOOL_NAMES, type AgentConfig } from "../delegation/agents.ts";
 import type { ThinkingLevel } from "../configuration/config.ts";
 import { writeTempOwnerMarker } from "../isolation/temp-hygiene.ts";
@@ -36,8 +37,6 @@ export const RPC_COMMAND_TIMEOUT_MS = 30_000;
 /** clear_queue is stop-path hygiene ahead of the abort: give it its own short
  * budget so a hung response cannot eat into the abort-settle window. */
 const RPC_CLEAR_QUEUE_TIMEOUT_MS = 2_000;
-/** Keep logical stop responsive when a steering ACK is lost. */
-const RPC_STEER_ACK_TIMEOUT_MS = 2_000;
 /** Time allowed for the child to boot and answer get_state. */
 export const RPC_READY_TIMEOUT_MS = 60_000;
 export const RPC_ABORT_SETTLE_TIMEOUT_MS = 5_000;
@@ -197,15 +196,6 @@ async function writePromptToTempFile(
 	}
 }
 
-interface RpcResponse {
-	id?: string;
-	type: "response";
-	command: string;
-	success: boolean;
-	error?: string;
-	data?: unknown;
-}
-
 interface RpcSessionUsage {
 	input: number;
 	output: number;
@@ -435,7 +425,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	const readyTimeoutMs = options.rpcReadyTimeoutMs ?? RPC_READY_TIMEOUT_MS;
 	const commandTimeoutMs = options.rpcCommandTimeoutMs ?? RPC_COMMAND_TIMEOUT_MS;
 
-	const writeLine = (value: object): Promise<void> =>
+	const writeLine = (value: RpcCommand | RpcExtensionUIResponse): Promise<void> =>
 		new Promise((resolve, reject) => {
 			if (!proc.stdin || proc.stdin.destroyed || !proc.stdin.writable) {
 				reject(new Error("Subagent RPC stdin is not writable."));
@@ -449,7 +439,10 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			});
 		});
 
-	const send = async <T extends { type: string }>(command: T, timeoutMs = commandTimeoutMs): Promise<RpcResponse> => {
+	const send = async <T extends RpcCommand>(
+		command: T,
+		timeoutMs = commandTimeoutMs,
+	): Promise<Extract<RpcResponse, { command: T["type"]; success: true }>> => {
 		if (finished || closed) throw new Error("Subagent RPC process is no longer active.");
 		const id = `req_${++requestId}`;
 		const payload = { ...command, id };
@@ -471,7 +464,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			if (!response.success) {
 				throw new RpcCommandRejectedError(response.error || `RPC ${response.command} failed.`);
 			}
-			return response;
+			return response as Extract<RpcResponse, { command: T["type"]; success: true }>;
 		});
 	};
 
@@ -501,9 +494,8 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	const abortAcceptedPrompt = async (): Promise<boolean> => {
 		const acceptance = await initialPrompt.promise;
 		if (!acceptance.accepted) return false;
-		// Pi continues queued steering/follow-up messages after an abort. Drop
-		// them first so a stopped run — or a later resume of its retained
-		// thread — cannot be revived by stale queue entries. Best-effort: an
+		// Pi continues queued messages after an abort. Drop them first so stale
+		// queue entries cannot revive a stopped run. Best-effort: an
 		// older child rejects the command and a hung child falls through to
 		// the bounded abort below.
 		try {
@@ -529,9 +521,6 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	};
 
 	const attemptControl: AttemptControl = {
-		async steer(command): Promise<void> {
-			await send(command, RPC_STEER_ACK_TIMEOUT_MS);
-		},
 		async stop(reason = "Subagent was aborted"): Promise<void> {
 			if (finished) {
 				if (!closed) await processClosed.promise;
@@ -693,8 +682,8 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 					result.usage.contextTokens = usage.totalTokens || 0;
 				}
 				if (!result.model && (message as any).model) result.model = (message as any).model;
-				if ((message as any).stopReason) result.stopReason = (message as any).stopReason;
-				if ((message as any).errorMessage) result.errorMessage = (message as any).errorMessage;
+				result.stopReason = message.stopReason;
+				result.errorMessage = message.errorMessage;
 			}
 			emit({ kind: "usage", usage: { ...result.usage }, model: result.model });
 		}
@@ -747,25 +736,35 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 		finish();
 	});
 
-	proc.once("close", (code) => {
+	proc.once("close", (code, exitSignal) => {
 		closed = true;
-		resolveInitialPrompt(false, new Error(`Subagent RPC process exited before the initial prompt was accepted (code=${code ?? "signal"}).`));
+		const disposition = exitSignal ? `signal=${exitSignal}` : `code=${code}`;
+		resolveInitialPrompt(false, new Error(`Subagent RPC process exited before the initial prompt was accepted (${disposition}).`));
 		if (forceKillTimer) clearTimeout(forceKillTimer);
 		stdoutBuffer += stdoutDecoder.end();
 		result.stderr += stderrDecoder.end();
 		if (stdoutBuffer.length > 0) processLine(stdoutBuffer);
 		const exitError = new Error(
-			`Subagent RPC process exited before settling (code=${code ?? "signal"}).${result.stderr ? ` ${result.stderr.trim()}` : ""}`,
+			`Subagent RPC process exited before settling (${disposition}).${result.stderr ? ` ${result.stderr.trim()}` : ""}`,
 		);
 		rejectPending(exitError);
 		if (abortSettlement) {
 			abortSettlement.reject(exitError);
 			abortSettlement = undefined;
 		}
-		if (!finished) {
+		if (!finished && !usageSettlementStarted) {
+			const silentStartupExit = !result.rpcPromptDispatched && !result.rpcActivity
+				&& result.messages.length === 0 && !result.stderr.trim() && !result.errorMessage?.trim();
 			result.exitCode = code === 0 ? 1 : (code ?? 1);
-			result.stopReason ??= signal?.aborted ? "aborted" : "error";
-			if (signal?.aborted) result.errorMessage ??= "Subagent was aborted";
+			result.stopReason = signal?.aborted ? "aborted" : "error";
+			if (signal?.aborted) {
+				result.errorMessage ||= "Subagent was aborted";
+			} else {
+				result.errorMessage = result.errorMessage?.trim()
+					? `${result.errorMessage}\n${exitError.message}` : exitError.message;
+				if (silentStartupExit) result.rpcStartupFailed = true;
+				else result.dispatchFailed = true;
+			}
 			finish();
 		}
 		processClosed.resolve();

package/src/execution/spawn.ts

@@ -290,7 +290,7 @@ export function isRetryableStartupFailure(result: SingleResult, durationMs: numb
 }
 
 export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
-	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or dispatch fewer sub-agents at once.`;
+	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no model, tool, output, or usage activity. Main handles this phase; inspect launch diagnostics instead of redispatching it.`;
 }
 
 export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {
@@ -334,20 +334,26 @@ async function waitForControlledRetry(
 	return !signal?.aborted && !control?.isStopRequested();
 }
 
+/** Runtime/assistant diagnostics, never an inference from individual failed tools. */
+export function getResultError(result: SingleResult): string | undefined {
+	if (result.exitCode === -1 || !isFailedResult(result)) return undefined;
+	return result.errorMessage?.trim()
+		|| lastAssistantMessage(result.messages)?.errorMessage?.trim()
+		|| result.stderr.trim()
+		|| (result.stopReason === "aborted"
+			? "Subagent was aborted."
+			: `Subagent failed (exit code ${result.exitCode}${result.stopReason ? `, stop reason ${result.stopReason}` : ""}); no failure reason was recorded.`);
+}
+
 export function getResultOutput(result: SingleResult): string {
-	if (isFailedResult(result)) {
-		const error = result.errorMessage || result.stderr;
-		const partial = getFinalOutput(result.messages);
-		if (error && partial) return `${error}\n\n--- Partial output ---\n${partial}`;
-		return error || partial || "(no output)";
-	}
-	return getFinalOutput(result.messages) || "(no output)";
+	const error = getResultError(result);
+	const output = getFinalOutput(result.messages);
+	if (error && output) return `${error}\n\n--- Partial output ---\n${output}`;
+	return error || output || "(no output)";
 }
 
-/** Continuation rules shared by every resume flavor. The workspace clause is
- * what keeps a retained context from becoming a liability: a parked or settled
- * thread may return after main integrated sibling worktrees or edited the tree
- * itself, so a file read in an earlier generation is not proof of its content. */
+/** Model handoff preserves useful history, but main or siblings may have edited
+ * the workspace since the selected model last read it. */
 const RESUME_CONTINUATION_RULES =
 	"Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Do not redo searches, reads, or edits that already succeeded. The workspace may have changed while this thread was inactive: before editing a file, re-read it unless you read it during this continuation. Finish with the result-only handoff your role requires.";
 
@@ -355,12 +361,6 @@ export function buildResumePrompt(task: string, reason: string): string {
 	return `You are resuming an earlier sub-agent session after ${reason}. ${RESUME_CONTINUATION_RULES} Current objective: ${task}. Pick up exactly where you left off and finish it. Continue now.`;
 }
 
-/** A resume with an appended objective continues the same thread: the new
- * objective is guidance layered on retained context, not a restart. */
-export function buildAppendedObjectivePrompt(previousTask: string, objective: string): string {
-	return `You are continuing an earlier sub-agent session with an appended objective from the parent. ${RESUME_CONTINUATION_RULES} Previous objective: ${previousTask}. Appended objective: ${objective}. Complete the appended objective on top of the work already done, without restarting from scratch. Continue now.`;
-}
-
 /** Create a fresh private session directory under the given root. The owner
  * marker is what lets a later load tell a session this process still owns from
  * one a crash abandoned. */
@@ -553,10 +553,11 @@ export async function runSingleAgentWithMainFallback(
 			}
 			const delay = startupDelays[attempt];
 			if (delay === undefined) {
-				lastResult.errorMessage = formatStartupRetryExhaustedError(
+				const reason = getResultError(lastResult);
+				lastResult.errorMessage = [formatStartupRetryExhaustedError(
 					lastResult.model ?? opts.agent.model ?? "default",
 					attempt + 1,
-				);
+				), reason].filter(Boolean).join("\n");
 				lastResult.stopReason ??= "error";
 				lastResult.dispatchFailed = true;
 				return lastResult;

package/src/isolation/temp-hygiene.ts

@@ -5,17 +5,15 @@
  * Two classes live there and both are swept the same way. Transient per-run
  * files (child prompt copies, the no-retry policy extension) sit in `tmp/`;
  * retained child sessions and isolated worktrees sit in `sessions/` and
- * `worktrees/`, where they must outlive the process that made them so a reload
- * can resume from them. Every mkdtemp directory gets an owner marker with the
+ * `worktrees/`, where they must outlive the process that made them for manual
+ * recovery after reload. Every mkdtemp directory gets an owner marker with the
  * creating pid. At extension load, directories whose owner is dead are removed;
  * unmarked leftovers fall back to an age cap.
  *
- * Ownership is what makes this safe for the durable class. A retained session
- * that no manifest record claims — a settled thread still resumable in the
- * session that produced it — belongs to a live owner and survives; the same
- * directory left behind by a crash does not. Callers sweeping durable roots
- * additionally pass the paths their thread and recovery manifests still reference,
- * so parked and retained work is never removed even if its owner is long gone.
+ * Ownership keeps a live parent's retained sessions and worktrees intact even
+ * when no manifest record claims them. Callers sweeping durable roots additionally
+ * pass the paths their thread and recovery manifests still reference, so interrupted
+ * and retained work survives even when its owner is gone.
  *
  * A live sibling pi instance never loses its directories: `kill(pid, 0)` only
  * reports "no such process" when the pid genuinely does not exist, so a live
@@ -36,7 +34,7 @@ export const TEMP_OWNER_FILE_NAME = "owner.json";
 const TEMP_DIR_PREFIXES = ["pi-subagents-"] as const;
 
 /** Durable directories created under `<project>/sessions` and
- * `<project>/worktrees`: retained child sessions (including resume forks) and
+ * `<project>/worktrees`: retained child sessions and
  * isolated worktree groups. */
 const DURABLE_DIR_PREFIXES = ["pi-subagent-session-", "pi-subagent-worktree-"] as const;