@ferris1225/pi-subagents 4.3.5 → 4.3.7

package/src/lifecycle/runtime.ts

@@ -107,7 +107,7 @@ export interface SubagentRuntime {
 	 * one-time session-start notice. */
 	restoredRunIds: number[];
 	restoredNotified: boolean;
-	/** Deliver a batch of completion messages as a waking follow-up. */
+	/** Deliver a batch at the next safe parent turn boundary and wake an idle parent. */
 	sendCompletionGroup: (items: CompletionMessageItem[]) => void;
 	/** Claim the sole delivery route before a generation can settle. */
 	claimRunDelivery: (runId: number, route: "background" | "await") => void;
@@ -189,10 +189,10 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 				content: formatCompletionMessage(items) + formatActiveRunsFooter(active),
 				display: true,
 			};
-			// Follow-ups never interrupt an active parent lane. triggerTurn wakes an
-			// idle parent immediately, while a streaming parent receives the result
-			// only after its current tool/assistant lane settles.
-			pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
+			// Steer delivers after the current assistant turn's tool calls and before
+			// the next model call. A follow-up would wait for the whole parent run to
+			// settle, allowing completions and stop results to arrive after its final reply.
+			pi.sendMessage(message, { deliverAs: "steer", triggerTurn: true });
 		},
 		claimRunDelivery: (runId, route) => {
 			runDeliveries.set(runId, { route, immediate: false });

package/src/lifecycle/thread-lifecycle.ts

@@ -27,11 +27,12 @@ import {
 	queuedResult,
 } from "../presentation/format.ts";
 import { monitor } from "../presentation/monitor.ts";
-import { findDuplicateActiveDispatch } from "../delegation/prompt.ts";
+import { findDuplicateDispatch } from "../delegation/prompt.ts";
 import { persistRecoveryRecords, recoveryRecordFromFinalization } from "../isolation/recovery.ts";
 import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts";
 import { forkRetainedSession } from "../execution/session-fork.ts";
 import {
+	buildAppendedObjectivePrompt,
 	buildResumePrompt,
 	getProjectRoot,
 	RpcRunControl,
@@ -135,12 +136,21 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 
 		const originalCwd = resolve(cwd ?? runCtx.cwd);
 		if (!existingThread) {
-			const duplicate = findDuplicateActiveDispatch(runtime.threads.values(), task, originalCwd);
-			if (duplicate) {
+			const duplicate = findDuplicateDispatch(runtime.threads.values(), task, originalCwd);
+			if (duplicate?.kind === "active") {
 				return failedStartResult(
 					agentName,
 					task,
-					`Duplicate active dispatch matches run #${duplicate.id} (${duplicate.agentName}). Use that logical thread instead; resume #${duplicate.id} when it is eligible.`,
+					`Duplicate active dispatch matches run #${duplicate.source.id} (${duplicate.source.agentName}). Use that logical thread instead; resume #${duplicate.source.id} when it is eligible.`,
+				);
+			}
+			if (duplicate?.kind === "settled") {
+				// The same brief on the same tree would re-buy work whose result main
+				// already holds; the retained session continues it for a fraction.
+				return failedStartResult(
+					agentName,
+					task,
+					`Run #${duplicate.source.id} (${duplicate.source.agentName}) already ${duplicate.source.state} this exact brief and kept its context; its result was delivered. Resume #${duplicate.source.id} with an appended objective instead of paying for a second run, or restate the brief with what changed.`,
 				);
 			}
 		}
@@ -333,9 +343,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 								? {
 									sessionId: priorSessionId,
 									sessionDir: priorSessionDir,
-									stdinText: seed?.prompt ?? (appendedObjectiveOnResume
-										? task
-										: buildResumePrompt(priorTask ?? task, "the retained thread was resumed")),
+									stdinText: appendedObjectiveOnResume
+										? buildAppendedObjectivePrompt(priorTask ?? task, task)
+										: buildResumePrompt(priorTask ?? task, "the retained thread was resumed"),
 								}
 								: {}),
 						},
@@ -375,17 +385,19 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 
 				const lifecycleInterrupted = (): boolean =>
 					thread.lifecycleOperation === "stop" ||
+					thread.lifecycleOperation === "park" ||
 					thread.state === "stopped";
-				// Destructive stop owns publication once it has synchronously claimed
-				// the lifecycle. Leave the partial result/session on the thread; the
-				// stop path waits for this queue task, finalizes isolation, and emits
-				// exactly one aborted result.
-				if (thread.lifecycleOperation === "stop") return;
+				// Destructive stop and park own publication once they have
+				// synchronously claimed the lifecycle. Leave the partial result/session
+				// on the thread; stop waits for this queue task, finalizes isolation,
+				// and emits exactly one aborted result, while park records the
+				// checkpoint and answers through its own tool result.
+				if (lifecycleInterrupted()) return;
 
 				// A shutdown can win in the microtask gap after the child RPC
 				// settles. Never replace the stable top-level session with an
 				// aborted partial.
-				if (backgroundSignal.aborted || lifecycleInterrupted() || !runtime.sessionActive) return;
+				if (backgroundSignal.aborted || !runtime.sessionActive) return;
 
 				if (thread.retireOnSettle) runtime.retireThreadSession(thread);
 				// Claim terminal settlement synchronously before the first slow await.
@@ -471,9 +483,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			() => {
 				if (runtime.threads.get(runId)?.generation !== generation) return;
 				// A destructive stop owns publication and may still be finalizing an
-				// isolated worktree. Do not expose a terminal monitor state before
-				// that owner records the aborted result.
-				if (thread.lifecycleOperation === "stop") return;
+				// isolated worktree; a park owns the checkpoint. Do not expose a
+				// terminal monitor state before that owner records its outcome.
+				if (thread.lifecycleOperation === "stop" || thread.lifecycleOperation === "park") return;
 				runtime.runControllers.delete(runId);
 				thread.queueController = undefined;
 				thread.state = "stopped";
@@ -487,9 +499,10 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			async (error) => {
 				if (runtime.threads.get(runId)?.generation !== generation) return;
 				// Queue-level crashes use the same settlement reservation as ordinary
-				// results. A concurrent destructive stop may supersede it while slow
-				// worktree finalization is running, in which case stop publishes once.
-				if (thread.lifecycleOperation === "stop") return;
+				// results. A concurrent destructive stop or park may supersede it while
+				// slow worktree finalization is running, in which case that owner
+				// publishes once.
+				if (thread.lifecycleOperation === "stop" || thread.lifecycleOperation === "park") return;
 				const settlementVersion = ++thread.lifecycleVersion;
 				thread.lifecycleOperation = "settle";
 				const ownsSettlement = (): boolean =>

package/src/lifecycle/thread-restore.ts

@@ -24,6 +24,7 @@ import {
 	type SingleResult,
 } from "../execution/spawn.ts";
 import { isProcessAlive, killProcessTree, sweepProjectDurableDirs, sweepProjectTempDirs } from "../isolation/temp-hygiene.ts";
+import { readRecoveryRecords, referencedRecoveryPaths } from "../isolation/recovery.ts";
 import {
 	isPathInside,
 	restoreWorktreeIsolation,
@@ -225,9 +226,11 @@ export function bootstrapDurableState(runtime: SubagentRuntime): Promise<void> {
 		try {
 			// Sessions and worktrees outlive their process on purpose, so only
 			// ownership separates state a live pi still resumes from state a crash
-			// abandoned. Parked work is claimed by the manifest and always kept.
+			// abandoned. Valid thread and recovery records always keep their paths.
 			const records = await readThreadRecords(runtime.configPath);
+			const recoveryRecords = await readRecoveryRecords(runtime.configPath);
 			const referenced = [...referencedDurablePaths(records)];
+			referenced.push(...await referencedRecoveryPaths(runtime.configPath, recoveryRecords));
 			sweepProjectDurableDirs(projectRoots, {
 				keep: (path) => referenced.some((claimed) => isPathInside(path, claimed)),
 			});

package/src/lifecycle/thread-shared.ts

@@ -184,7 +184,6 @@ export interface DispatchEnvironment {
 export interface SessionSeed {
 	sessionId?: string;
 	sessionDir?: string;
-	prompt?: string;
 	worktree?: WorktreeIsolation;
 }
 

package/src/lifecycle/tools.ts

@@ -1,9 +1,10 @@
 /**
- * Thread controls around the subagent runtime: subagent_control (resume) and
- * destructive subagent_stop. There is no status/poll tool — completions carry
- * each result (with an on-disk artifact when truncated) and wake the main
- * model, so waiting is never a tool call; the only in-turn block is `wait:
- * true` on a dispatch, for one-shot parents that exit at end of turn.
+ * Thread controls around the subagent runtime: subagent_control
+ * (steer/resume/park) and destructive subagent_stop. There is no status/poll
+ * tool — completions carry each result (with an on-disk artifact when
+ * truncated) and wake the main model, so waiting is never a tool call; the only
+ * in-turn block is `wait: true` on a dispatch, for one-shot parents that exit
+ * at end of turn.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -15,10 +16,10 @@ import { DEFAULT_MAX_RESULT_LINES, loadConfig } from "../configuration/config.ts
 import { removeThreadRecord } from "./durable.ts";
 import { formatCompletionBlock, matchRunIds } from "../presentation/format.ts";
 import { emptyUsage } from "../execution/rpc-control.ts";
-import { formatTaskSummary, monitor } from "../presentation/monitor.ts";
+import { formatTaskSummary, formatUsageCompact, monitor } from "../presentation/monitor.ts";
 import { persistRecoveryRecords, recoveryRecordFromFinalization } from "../isolation/recovery.ts";
 import type { SubagentRuntime, SubagentThread } from "./runtime.ts";
-import { CONTROL_QUIESCE_TIMEOUT_MS, projectResultsRoot, quiesced } from "./thread-shared.ts";
+import { CONTROL_QUIESCE_TIMEOUT_MS, persistThreadCheckpoint, projectResultsRoot, quiesced } from "./thread-shared.ts";
 import { getResultOutput, type SingleResult } from "../execution/spawn.ts";
 import type { WorktreeFinalization } from "../isolation/worktree.ts";
 
@@ -34,19 +35,24 @@ function renderFirstLine(result: { content?: unknown }, label: string, theme: an
 
 export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	const SubagentControlParams = Type.Object({
-		action: StringEnum(["resume"] as const, {
-			description: "Control operation for the logical sub-agent thread.",
+		action: StringEnum(["steer", "resume", "park"] as const, {
+			description:
+				"steer: send guidance to the running attempt (a settled or parked thread continues with it); resume: continue a parked or settled thread; park: pause a running thread at a stable checkpoint, keeping its session and worktree for a later resume.",
 		}),
 		id: Type.Integer({ minimum: 1, description: "Stable run id shown by subagent dispatch output." }),
 		objective: Type.Optional(
-			Type.String({ description: "Optional appended objective for resume. Omit to continue the current retained objective." }),
+			Type.String({ description: "Guidance for steer (required and nonblank), or an optional appended objective for resume. Ignored by park." }),
 		),
 	});
 
+	/** A thread that a steer can continue instead of reject: it is not live, but
+	 * its retained session can absorb the guidance as an appended objective. */
+	type ContinuableState = "completed" | "failed" | "parked";
+
 	pi.registerTool({
 		name: "subagent_control",
 		label: "Subagent Control",
-		description: "Resume a parked or settled child thread by run id, reusing its retained session when available. An optional objective is appended to its current goal.",
+		description: "Steer a running child with additional guidance (continuing it if it has settled or is parked), resume a parked/settled thread, or park a running thread at a stable checkpoint, by stable run id.",
 		parameters: SubagentControlParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -61,31 +67,152 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 				const trimmed = value?.trim();
 				return trimmed ? trimmed : undefined;
 			};
+			const textResult = (text: string) => ({ content: [{ type: "text" as const, text }], details: {} });
+			/** Why the thread has no steerable/parkable running RPC attempt right now. */
+			const inactiveReason = (): string | undefined => {
+				// Park drives the control through `stopped` before it records the
+				// checkpoint, so the operation is named ahead of the transient state.
+				if (thread.lifecycleOperation === "park") return "parking";
+				if (thread.lifecycleOperation === "stop" || thread.state === "stopped") return "stopped";
+				if (thread.lifecycleOperation === "resume") return "resuming";
+				if (thread.lifecycleOperation === "settle" || thread.state === "completed" || thread.state === "failed") {
+					return `settled (${thread.state})`;
+				}
+				if (thread.state === "queued" || thread.state === "resuming") {
+					const phase = thread.control.getPhase();
+					return phase === "starting" || phase === "retrying" ? phase : thread.state;
+				}
+				return thread.state === "running" ? undefined : thread.state;
+			};
+			const resumeThread = async (
+				objective: string | undefined,
+				continuedFrom?: ContinuableState,
+			) => {
+				if (thread.retired) {
+					return textResult(`Run #${thread.id} was retired by subagent_stop and has no resumable session.`);
+				}
+				if (
+					thread.state !== "parked" &&
+					thread.state !== "completed" &&
+					thread.state !== "failed"
+				) {
+					return textResult(`Run #${thread.id} is ${thread.state}; it must be parked or settled before resume.`);
+				}
+				const requestedObjective = objective === undefined ? undefined : nonBlank(objective);
+				if (objective !== undefined && !requestedObjective) {
+					return textResult("resume objective must be non-blank when provided.");
+				}
+				const hadRetainedSession = Boolean(thread.sessionId && thread.sessionDir);
+				const pending = await thread.resume(requestedObjective, ctx);
+				if (pending.exitCode !== -1) return textResult(getResultOutput(pending));
+				const currentObjective = formatTaskSummary(requestedObjective ?? thread.task, 80, false);
+				const mode = requestedObjective
+					? `appended objective: ${currentObjective}`
+					: `continuing current objective: ${currentObjective}`;
+				const context = hadRetainedSession ? "retained context reused" : "no prior child context";
+				const prefix = continuedFrom
+					? `Run #${thread.id} was already ${continuedFrom} before steering; resumed the same thread`
+					: `Resumed run #${thread.id}`;
+				return textResult(`${prefix}: ${mode}; ${context}.`);
+			};
+			/** Steering guidance for a thread that is no longer live continues the
+			 * same thread with that guidance instead of being dropped, so the
+			 * evidence is never re-bought by a second dispatch. */
+			const continueSteer = async (objective: string) => {
+				const continuable = (): ContinuableState | undefined =>
+					thread.state === "completed" || thread.state === "failed" || thread.state === "parked"
+						? thread.state
+						: undefined;
+				if (thread.lifecycleOperation === "settle" || (!continuable() && thread.control.getPhase() === "settled")) {
+					if (!(await quiesced(thread.generationCompletion))) return undefined;
+				}
+				const state = continuable();
+				if (!state || thread.lifecycleOperation) return undefined;
+				return resumeThread(objective, state);
+			};
 
 			try {
 				switch (params.action) {
+					case "steer": {
+						const objective = nonBlank(params.objective);
+						if (!objective) {
+							return textResult("steer objective must be non-blank.");
+						}
+						if (thread.retired) {
+							return textResult(`Run #${thread.id} was retired by subagent_stop and cannot be steered.`);
+						}
+						const continued = await continueSteer(objective);
+						if (continued) return continued;
+						const unavailable = inactiveReason();
+						if (unavailable) {
+							return textResult(`Run #${thread.id} is ${unavailable}; only an active running RPC attempt can be steered. No guidance was sent.`);
+						}
+						const steered = await thread.control.steer(objective);
+						if (!steered.accepted) {
+							const resumed = await continueSteer(objective);
+							if (resumed) return resumed;
+							if (steered.reason === "no-active-attempt") {
+								return textResult(`Run #${thread.id} is marked running but has no active RPC attempt; no guidance was sent.`);
+							}
+							return textResult(`Run #${thread.id} is ${steered.phase}; only an active running RPC attempt can be steered. No guidance was sent.`);
+						}
+						return textResult(`Steered run #${thread.id} with additional in-scope guidance; its original objective is unchanged.`);
+					}
 					case "resume": {
+						return resumeThread(params.objective);
+					}
+					case "park": {
 						if (thread.retired) {
-							return { content: [{ type: "text", text: `Run #${thread.id} was retired by subagent_stop and has no resumable session.` }], details: {} };
+							return textResult(`Run #${thread.id} was retired by subagent_stop and cannot be parked.`);
 						}
-						if (!(["parked", "completed", "failed"] as const).includes(thread.state as any)) {
-							return { content: [{ type: "text", text: `Run #${thread.id} is ${thread.state}; it must be parked or settled before resume.` }], details: {} };
+						const unavailable = inactiveReason();
+						if (unavailable) {
+							return textResult(`Run #${thread.id} is ${unavailable}; only an active running RPC attempt can be parked. Use subagent_stop to discard a run that has not started.`);
 						}
-						const objective = params.objective === undefined ? undefined : nonBlank(params.objective);
-						if (params.objective !== undefined && !objective) {
-							return { content: [{ type: "text", text: "resume objective must be non-blank when provided." }], details: {} };
+						if (!thread.sessionId || !thread.sessionDir) {
+							return textResult(`Run #${thread.id} has no retained session yet; steer it or let it settle instead.`);
 						}
-						const hadRetainedSession = Boolean(thread.sessionId && thread.sessionDir);
-						const pending = await thread.resume(objective, ctx);
-						if (pending.exitCode !== -1) {
-							return { content: [{ type: "text", text: getResultOutput(pending) }], details: {} };
+						// Park interrupts the child at its next safe point but keeps the
+						// session and worktree, so the thread returns to `parked`, not to a
+						// failure. Claim synchronously like stop; the generation body sees
+						// the claim and leaves publication to this path.
+						const parkVersion = ++thread.lifecycleVersion;
+						thread.lifecycleOperation = "park";
+						const generation = thread.generation;
+						const controller = thread.queueController;
+						const completion = thread.generationCompletion;
+						const ownsPark = (): boolean =>
+							runtime.threads.get(thread.id) === thread &&
+							thread.generation === generation &&
+							thread.lifecycleVersion === parkVersion &&
+							thread.lifecycleOperation === "park" &&
+							!thread.retired;
+						try {
+							await quiesced(thread.control.stop("Parked by subagent_control at a stable checkpoint.").catch(() => undefined));
+							if (!(await quiesced(completion))) runtime.backgroundQueue.cancel(controller);
+							if (!ownsPark()) {
+								return textResult(`Run #${thread.id} changed while it was being parked; no checkpoint was recorded by this call.`);
+							}
+							if (runtime.runControllers.get(thread.id) === controller) runtime.runControllers.delete(thread.id);
+							if (thread.queueController === controller) thread.queueController = undefined;
+							thread.state = "parked";
+							monitor.setStatus(thread.id, "parked");
+							thread.elapsedMs = monitor.getElapsedMs(thread.id) ?? thread.elapsedMs;
+							persistThreadCheckpoint(runtime, thread, "parked");
+							const run = monitor.findRun(thread.id);
+							const usage = run ? formatUsageCompact(run.usage) : "";
+							if (runtime.sessionActive) {
+								ctx.ui.notify(`■ #${thread.id} ${run ? monitor.summarize(run) : thread.agentName} · parked`, "info");
+							}
+							const retained = thread.isolation === "worktree" ? "session and worktree" : "session";
+							return textResult(
+								`Parked run #${thread.id} (${thread.agentName}) at a stable checkpoint${usage ? ` after ${usage}` : ""}. Its retained ${retained} continue on subagent_control resume (optionally with an appended objective) or on steer; subagent_stop discards them.`,
+							);
+						} finally {
+							if (thread.lifecycleVersion === parkVersion && thread.lifecycleOperation === "park") {
+								thread.lifecycleOperation = undefined;
+							}
 						}
-						const currentObjective = formatTaskSummary(objective ?? thread.task, 80, false);
-						const mode = objective
-							? `appended objective: ${currentObjective}`
-							: `continuing current objective: ${currentObjective}`;
-						const context = hadRetainedSession ? "retained context reused" : "no prior child context";
-						return { content: [{ type: "text", text: `Resumed run #${thread.id}: ${mode}; ${context}.` }], details: {} };
 					}
 				}
 			} catch (error) {