@ferris1225/pi-subagents 4.1.4 → 4.1.6

package/src/prompt.ts

@@ -29,14 +29,7 @@ export function buildDelegationDirective(
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
 	];
-	const reviewedWriterNames = [
-		...codeWriterNames,
-		...(hasDocumenter ? ["documenter"] : []),
-	];
-	const automaticWriterRoute = [
-		...(hasReviewer ? ["reviewer"] : []),
-		...(hasDocumenter ? ["documenter"] : []),
-	].join(" → ");
+	const reviewedWriterNames = [...codeWriterNames];
 	const namedWorktreeTargets = [
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
@@ -47,34 +40,43 @@ export function buildDelegationDirective(
 		: namedWorktreeTargets.length === 1
 			? `${namedWorktreeTargets[0]} or another`
 			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
+	const managedWriterWorkflowRule = reviewedWriterNames.length === 0
+		? undefined
+		: hasReviewer && hasDocumenter
+			? `Successful top-level ${reviewedWriterNames.join("/")} runs continue through the enabled reviewer gate. Only REVIEW_PASS can authorize documenter, which runs for DOCUMENTATION: NEEDED or a missing marker; the workflow delivers once. Never duplicate stages.`
+			: hasReviewer
+				? `Successful top-level ${reviewedWriterNames.join("/")} runs continue through the enabled reviewer gate and then deliver once; never duplicate the gate.`
+				: hasDocumenter
+					? `With reviewer disabled, successful top-level ${reviewedWriterNames.join("/")} runs use documenter as the conservative final fallback and then deliver once; never duplicate the fallback.`
+					: undefined;
 
 	const dispatchRules = [
-		"Handle simple work inline with direct tools: one-line lookups, known-target reads/edits, and quick questions do not justify a child process.",
+		"Keep small, known-target work in the main thread with direct tools: lookups and focused reads/edits do not justify a child context.",
 		...(hasExplorer
 			? [
-				"Use `explorer` proactively when reconnaissance becomes broad or crosses files: mapping unfamiliar code, tracing symbols/dependencies, or answering multi-file location/reference questions. Treat its output only as a retrieval index; re-read load-bearing files before edits or decisions about deletion, security, compatibility, persistence, or dynamic reachability. Use a stronger model/specialist for complex dynamic, concurrent, migration, or security-sensitive analysis.",
+				"Use `explorer` proactively only for broad or cross-file reconnaissance: mapping unfamiliar code, tracing symbols/dependencies, or finding multi-file references. It is a lightweight retrieval index, never an automatic gate. Re-read load-bearing files before edits or high-risk decisions. Use a stronger model/specialist for dynamic, concurrent, migration, or security analysis.",
 			]
 			: []),
 		...(hasWorker
-			? ["Use `worker` for a self-contained implementation, fix, refactor, or test task whose separate context pays for itself."]
+			? ["Use `worker` for a self-contained implementation, fix, refactor, or test whose separate context pays for itself—not a small known-target edit."]
 			: []),
 		...(hasCleaner
 			? [
-				`Use \`cleaner\` only for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance. Once dispatched, it applies every safe proven in-scope cut without item-by-item approval; zero edits is valid only if none is proved. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+				`Use \`cleaner\` only as the separate evidence-first entry for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance; never substitute it for \`worker\`. It applies every safe proven in-scope cut without item-by-item approval. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
 			]
 			: []),
 		...(hasDocumenter
 			? [
-				`Use \`documenter\` directly for explicit whole-codebase maintenance or standalone documentation work.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already auto-sync the actual diff once after the review gate; never dispatch a duplicate.` : ""} Zero edits is valid and broad mode is never inferred. It changes docs/comments only and never runtime behavior, versions, or release state.`,
+				`Use \`documenter\` directly only for explicit whole-codebase maintenance or standalone documentation/comment work; a top-level documenter delivers directly without an automatic reviewer.${codeWriterNames.length > 0 ? ` ${codeWriterNames.join("/")} must sync existing docs they directly affect; runtime runs documenter only after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback—never dispatch a duplicate.` : ""} It never changes runtime behavior, versions, or release state.`,
 			]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for read-only assessments or an explicit gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get a fresh read-only reviewer gate.` : ""} Advisory output has no VERDICT: it stays read-only and does not authorize follow-up edits.`,
+				`Use \`reviewer\` for read-only assessments or a gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get one fresh read-only reviewer gate, independent of the writer.` : ""} Advisory output has no VERDICT and cannot authorize follow-up edits${hasDocumenter ? "; gates classify docs separately for the enabled documenter." : "."}`,
 			]
 			: []),
-		"Brief every child with the complete goal, exact paths, constraints, and expected output. It has no memory of this conversation.",
-		"Children are leaf processes without delegation tools. Do not ask them to spawn sub-agents; use `subagent_control fork` on a parked/settled retained thread for an independent continuation.",
+		"Brief each child with the complete goal, exact paths, constraints, and expected output; it has no conversation memory.",
+		"Children are leaf processes without delegation tools; use `subagent_control fork` on a parked/settled thread for an independent continuation.",
 		...(hasMultiple
 			? [
 				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",
@@ -86,24 +88,20 @@ export function buildDelegationDirective(
 	];
 
 	const handoffRules = [
-		"Dispatch returns immediately and ends this turn. Never sleep, poll, or call `subagent_wait` to hold the turn; results arrive as messages that automatically resume the main agent, even mid-turn.",
-		"Use `subagent_wait` with explicit `timeoutMs` only when the user specifically asks you to remain in-turn and wait. Its default lookup is non-blocking.",
-		"A result is already shown to the user. Do not restate, paraphrase, or re-summarize it; add only your conclusion or next action, often one line.",
+		"Dispatch ends this turn; results resume the main agent, even mid-turn. Never sleep, poll, or call `subagent_wait` to hold the turn.",
+		"Use `subagent_wait` with explicit `timeoutMs` only when the user asks to wait in-turn; its default lookup is non-blocking.",
+		"Results are already shown. Do not restate, paraphrase, or re-summarize them; add only your conclusion or next action.",
 		"A delivered result does not mean siblings are finished. Before declaring the overall task done, use `subagent_status` to confirm that no runs remain active.",
 	];
 
 	const verificationRules = [
 		"Never report an unrun check as passed; identify unavailable checks and pre-existing failures honestly.",
-		...(automaticWriterRoute && reviewedWriterNames.length > 0
-			? [
-				`Successful top-level write roles automatically continue through enabled downstream roles (${automaticWriterRoute}) to one final delivery; never duplicate stages.`,
-			]
-			: []),
+		...(managedWriterWorkflowRule ? [managedWriterWorkflowRule] : []),
 		...(hasReviewer
 			? [
 				...(hasDocumenter
 					? [
-						`A direct REVIEW_PASS is final for code: runtime runs the final documentation sync once and delivers. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps auto-fix; maxFixRounds limits worker fixes only, not the final documentation sync." : "cannot start fixes while worker/fix rounds are disabled."}`,
+						`A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps bounded worker/reviewer auto-fix, with docs considered only after its terminal REVIEW_PASS." : "cannot start fixes while worker/fix rounds are disabled."}`,
 					]
 					: []),
 				"Resolve every gate finding; do not bypass the configured auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and cannot trigger writes.",
@@ -116,7 +114,7 @@ export function buildDelegationDirective(
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-The \`subagent\` tool starts specialized leaf agents in isolated Pi child processes and context windows. It returns immediately; completion messages automatically resume the main agent.
+The \`subagent\` tool starts isolated Pi child processes and context windows. Completions automatically resume the main agent.
 
 Available agents:
 ${catalog}

package/src/rpc-run.ts

@@ -788,8 +788,32 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				if (!closed) await processClosed.promise;
 				return;
 			}
-			const accepted = await abortAcceptedPrompt();
-			if (!accepted && !closed) await processClosed.promise;
+			// Bound the abort settlement exactly like stop: a child that never
+			// settles after abort must not hold the control operation forever.
+			let parkTimer: ReturnType<typeof setTimeout> | undefined;
+			let parkTimedOut = false;
+			const parkDeadline = new Promise<boolean>((resolve) => {
+				parkTimer = setTimeout(() => {
+					parkTimedOut = true;
+					resolve(false);
+				}, RPC_ABORT_SETTLE_TIMEOUT_MS);
+				if (typeof parkTimer.unref === "function") parkTimer.unref();
+			});
+			let accepted: boolean;
+			try {
+				accepted = await Promise.race([abortAcceptedPrompt(), parkDeadline]);
+			} catch {
+				/* a rejected abort still parks; termination below is the bounded fallback */
+				accepted = false;
+			} finally {
+				if (parkTimer) clearTimeout(parkTimer);
+			}
+			if (abortSettlement) {
+				const stable = abortSettlement;
+				abortSettlement = undefined;
+				stable.resolve();
+			}
+			if (!accepted && !parkTimedOut && !closed) await processClosed.promise;
 			if (finished && accepted) throw new Error("Thread exited while parking.");
 			markParked();
 			setAttemptPhase("parked");

package/src/thread-lifecycle.ts

@@ -1,7 +1,8 @@
 /**
  * Stable logical-thread generation lifecycle for background sub-agents.
  *
- * Dispatch owns workflow policy and internal role briefs; this module owns one
+ * Dispatch owns workflow policy, the live stage projection, and internal role
+ * briefs; this module owns one
  * stable parent generation end to end: managed-repository lane use,
  * worktree setup/finalization after downstream review, queue/process ownership,
  * retained-session resume/fork, and guarded one-time terminal publication.
@@ -66,6 +67,7 @@ import {
 } from "./spawn.ts";
 import {
 	createWorktreeIsolation,
+	worktreeGroupId,
 	type IsolationMode,
 	type WorktreeFinalization,
 	type WorktreeIsolation,
@@ -74,6 +76,24 @@ import {
 export const FORK_CONTINUATION_PROMPT =
 	"Continue from the retained context above. Review the prior work, then take the most useful next step toward completing the existing objective without repeating completed work.";
 
+/** Control operations must never wait forever on a settling generation: the
+ * queue task can legitimately spend minutes in worktree finalization (bounded
+ * per-Git-command timeouts) or wait behind the managed repository lane. After
+ * this deadline the control path owns the lifecycle synchronously and proceeds
+ * while the stuck tail settles silently in the background. */
+export const CONTROL_QUIESCE_TIMEOUT_MS = 20_000;
+
+/** Resolve true when the promise settles, or false after the bounded deadline. */
+export function quiesced(promise: Promise<unknown>, timeoutMs: number = CONTROL_QUIESCE_TIMEOUT_MS): Promise<boolean> {
+	return Promise.race([
+		promise.then(() => true, () => true),
+		new Promise<boolean>((resolve) => {
+			const timer = setTimeout(() => resolve(false), timeoutMs);
+			if (typeof timer.unref === "function") timer.unref();
+		}),
+	]);
+}
+
 const WORKTREE_ISOLATION_INSTRUCTIONS =
 	"You are running in a temporary detached Git worktree. Work only in the current cwd; do not create another worktree or manually copy/apply changes to the original checkout. The parent dispatcher will integrate your tracked, deleted, and untracked changes when this thread finally settles.";
 
@@ -88,6 +108,16 @@ export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
 	return isWriteCapableAgent(agent);
 }
 
+/** A direct reviewer otherwise cannot infer enabled-role availability from its
+ * isolated task. Managed internal gates receive the same contract in their
+ * generated briefs. Advisory reviews still emit neither machine marker. */
+function withEnabledDocumenterReviewContract(agent: AgentConfig): AgentConfig {
+	return {
+		...agent,
+		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\nRuntime workflow context: documenter is enabled. In gate reviews, documentation drift is non-gating: emit DOCUMENTATION: NEEDED with ## Documentation notes, or DOCUMENTATION: CLEAN when no sync is needed. Advisory reviews still emit neither VERDICT nor DOCUMENTATION markers.`.trim(),
+	};
+}
+
 interface DispatchEnvironment {
 	ctx: ExtensionContext;
 	config: SubagentsConfig;
@@ -137,6 +167,8 @@ export interface ManagedWorkflowRequest extends DispatchEnvironment {
 	executionCwd: string;
 	projectCwd: string;
 	isolation: IsolationMode;
+	/** Short identity of the isolated worktree shared by every workflow stage. */
+	worktreeId?: string;
 	signal: AbortSignal;
 	rememberLatest: (result: SingleResult) => void;
 }
@@ -249,7 +281,10 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		if (!discoveredAgent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 		const resolveLiveAgentTools = (candidate: AgentConfig): AgentConfig =>
 			resolveAgentTools({ ...candidate, tools: discoveredAgent.tools }, runtime.getActiveTools());
-		const agent = resolveLiveAgentTools(discoveredAgent);
+		const resolvedAgent = resolveLiveAgentTools(discoveredAgent);
+		const agent = agentName === "reviewer" && runAgents.some((candidate) => candidate.name === "documenter")
+			? withEnabledDocumenterReviewContract(resolvedAgent)
+			: resolvedAgent;
 		if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
 			return {
 				...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as worker, cleaner, or documenter.`),
@@ -280,6 +315,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			}
 		}
 		const executionCwd = worktree?.cwd ?? originalCwd;
+		const worktreeGroup = worktree ? worktreeGroupId(worktree) : undefined;
 		const resolvedRoute = resolveDispatchModelRoute(agent, runConfig, runCtx);
 		// Isolation is a persistent system-level invariant, not a one-shot task
 		// prefix: queued retargets, live retargets, resumes, and main-model
@@ -296,6 +332,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		}
 		const runId = existingThread?.id ?? monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, {
 			isolation,
+			...(worktreeGroup ? { worktreeId: worktreeGroup } : {}),
 			...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
 			...(seed?.continuationKind ? { continuationKind: seed.continuationKind } : {}),
 		});
@@ -315,6 +352,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			monitor.restartRun(runId, agent.name, task, route.agent.model, thinkingLevel, isolation, {
 				elapsedMs: existingThread.elapsedMs,
 				continuationKind: appendedObjectiveOnResume ? "resume-appended" : "resume-retained",
+				...(worktreeGroup ? { worktreeId: worktreeGroup } : {}),
 			});
 			runtime.settledRuns.delete(runId);
 		}
@@ -412,12 +450,20 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			// All normal, destructive-stop, and shutdown owners converge here. Cache
 			// the lane-protected apply itself so superseding lifecycle paths can project
 			// the same finalization onto their own result without acquiring twice.
-			generationFinalization ??= runInManagedRepositoryLane(
-				generationWorktree.originalRoot,
-				() => generationWorktree.finalize(),
-			);
+			if (!generationFinalization) {
+				monitor.setIsolation(
+					runId,
+					"worktree",
+					"finalizing",
+					worktreeGroupId(generationWorktree),
+				);
+				generationFinalization = runInManagedRepositoryLane(
+					generationWorktree.originalRoot,
+					() => generationWorktree.finalize(),
+				);
+			}
 			const finalization = await generationFinalization;
-			monitor.setIsolation(runId, "worktree", finalization.status);
+			monitor.setIsolation(runId, "worktree", finalization.status, worktreeGroupId(generationWorktree));
 			if (result) {
 				result.runId = runId;
 				result.isolation = "worktree";
@@ -551,7 +597,12 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					// control after that child settles, so cancel its queue owner explicitly.
 					if (phase === "settled") runtime.backgroundQueue.cancel(controller);
 				}
-				await completion;
+				// The settling tail may be blocked on worktree finalization or the
+				// managed repository lane. Park already owns the lifecycle, so proceed
+				// after a bounded wait and let the tail finish silently in the background.
+				if (!(await quiesced(completion))) {
+					runtime.backgroundQueue.cancel(controller);
+				}
 				if (
 					thread.generation !== generation ||
 					thread.lifecycleVersion !== version ||
@@ -617,7 +668,15 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			let continuationWorktree: WorktreeIsolation | undefined;
 			let clonedSession: Awaited<ReturnType<typeof forkRetainedSession>> | undefined;
 			try {
-				await thread.generationCompletion;
+				// Never wait forever on a previous generation that is still settling
+				// (e.g. blocked behind the managed repository lane in finalization).
+				if (!(await quiesced(thread.generationCompletion))) {
+					return failedStartResult(
+						thread.agentName,
+						thread.task,
+						`Run #${runId}'s previous generation is still settling; retry the resume shortly.`,
+					);
+				}
 				if (!ownsResumeReservation(thread, reservation)) {
 					return failedStartResult(
 						thread.agentName,
@@ -797,7 +856,15 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			let childWorktree: WorktreeIsolation | undefined;
 			let forkedSession: Awaited<ReturnType<typeof forkRetainedSession>> | undefined;
 			try {
-				await thread.generationCompletion;
+				// Same bounded preflight as resume: a still-settling source generation
+				// must not block the control operation forever.
+				if (!(await quiesced(thread.generationCompletion))) {
+					return failedStartResult(
+						thread.agentName,
+						thread.task,
+						`Run #${runId}'s previous generation is still settling; retry the fork shortly.`,
+					);
+				}
 				if (!ownsFork()) {
 					return failedStartResult(thread.agentName, thread.task, `Run #${runId} changed while fork was preparing; no child was started.`);
 				}
@@ -897,23 +964,41 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			isolation === "shared" && canStartManagedWorkflow(agent, workflowAvailability);
 		const runGeneration = async (backgroundSignal: AbortSignal): Promise<void> => {
 				if (runtime.threads.get(runId)?.generation !== generation) return;
+				// Model/thinking config may have changed while this generation sat
+				// queued behind the concurrency limit. Re-resolve the route at actual
+				// start so /subagents-setup edits apply to not-yet-started runs.
+				let activeRoute = route;
+				let activeIdleTimeoutMs = runConfig.idleTimeoutSec * 1000;
+				try {
+					const startConfig = await loadConfig(runtime.configPath);
+					runtime.backgroundQueue.setConcurrency(startConfig.maxConcurrency);
+					const resolvedStart = resolveDispatchModelRoute(agent, startConfig, runCtx);
+					activeRoute = isolation === "worktree"
+						? { ...resolvedStart, agent: withWorktreeSystemPrompt(resolvedStart.agent) }
+						: resolvedStart;
+					activeIdleTimeoutMs = startConfig.idleTimeoutSec * 1000;
+					monitor.setModel(runId, activeRoute.agent.model);
+					monitor.setThinking(runId, activeRoute.thinkingLevel);
+				} catch {
+					/* keep the dispatch-time route when fresh config is unavailable */
+				}
 				let result: SingleResult;
 				try {
 					result = await runSingleAgentWithMainFallback(
 						{
 							defaultCwd: executionCwd,
-							agent: route.agent,
+							agent: activeRoute.agent,
 							resolveAgentForAttempt: resolveLiveAgentTools,
 							agentName,
 							task,
 							cwd: executionCwd,
-							thinkingLevel,
-							thinkingLevelForModel: route.thinkingLevelForModel,
+							thinkingLevel: activeRoute.thinkingLevel,
+							thinkingLevelForModel: activeRoute.thinkingLevelForModel,
 							signal: backgroundSignal,
 							onLive,
 							control,
 							makeDetails: makeDetails("single", true),
-							idleTimeoutMs: runConfig.idleTimeoutSec * 1000,
+							idleTimeoutMs: activeIdleTimeoutMs,
 							...(priorSessionId && priorSessionDir
 								? {
 									sessionId: priorSessionId,
@@ -924,7 +1009,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 								}
 								: {}),
 						},
-						route.mainFallbackRef,
+						activeRoute.mainFallbackRef,
 					);
 				} catch (error) {
 					const errorMessage = error instanceof Error ? error.message : String(error);
@@ -999,6 +1084,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 						executionCwd: thread.executionCwd,
 						projectCwd: originalCwd,
 						isolation,
+						...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
 						signal: backgroundSignal,
 						ctx: runCtx,
 						config: runConfig,
@@ -1052,8 +1138,8 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 					!thread.retired;
 				try {
 					// For isolated writers this is deliberately after the managed reviewer
-					// and documentation stages: every child sees the same worktree, then one
-					// lifecycle owner integrates the complete writer+fixes+docs state exactly once.
+					// and any needed documentation stage: every child sees the same worktree,
+					// then one lifecycle owner integrates the complete settled state exactly once.
 					await thread.finalizeIsolation(generation, result);
 					if (!ownsSettlement()) return;
 					if (workflowOutcome && isolation === "worktree") {

package/src/tools.ts

@@ -7,6 +7,7 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { existsSync } from "node:fs";
 import { Type } from "typebox";
 import { DEFAULT_MAX_RESULT_LINES, loadConfig } from "./config.ts";
 import { formatCompletionBlock, formatUsage, matchRunIds } from "./format.ts";
@@ -19,8 +20,11 @@ import {
 	statusLabel,
 	type RunStatus,
 } from "./monitor.ts";
+import { persistRecoveryRecords, recoveryRecordFromFinalization } from "./recovery.ts";
 import type { SubagentRuntime, SubagentThread } from "./runtime.ts";
+import { CONTROL_QUIESCE_TIMEOUT_MS, quiesced } from "./thread-lifecycle.ts";
 import { getResultOutput, isFailedResult, type SingleResult } from "./spawn.ts";
+import type { WorktreeFinalization } from "./worktree.ts";
 
 /** In-turn result lookup. Dispatch already ended the turn and results arrive as
  * wake-up messages, so the default must NOT block: a settled run returns its
@@ -648,6 +652,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 
 			const stopped: string[] = [];
 			const retainedIntegration: string[] = [];
+			const pendingIntegration: string[] = [];
 			for (const [claimIndex, claim] of claimed.entries()) {
 				const {
 					runId,
@@ -663,8 +668,13 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 					stopVersion,
 					stopMessage,
 				} = claim;
-				await interruptionPromises[claimIndex];
-				await completion;
+				// Every wait here is bounded: the queue task can sit for minutes in
+				// worktree finalization or behind the managed repository lane, and an
+				// unkillable child can stall even the RPC-level stop. Stop owns the
+				// lifecycle synchronously, so a stuck tail settles silently after we
+				// proceed; none of its late paths can publish a second result.
+				await quiesced(interruptionPromises[claimIndex]);
+				if (!(await quiesced(completion))) runtime.backgroundQueue.cancel(controller);
 				if (runtime.runControllers.get(runId) === controller) runtime.runControllers.delete(runId);
 				if (thread.queueController === controller) thread.queueController = undefined;
 
@@ -703,8 +713,42 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 							runId,
 							isolation: thread.isolation,
 						};
-					const finalization = await thread.finalizeIsolation(generation, stoppedResult);
-					if (finalization?.status === "retained") retainedIntegration.push(`#${runId}`);
+					const worktree = thread.worktree;
+					let finalization: WorktreeFinalization | undefined;
+					try {
+						finalization = await Promise.race([
+							thread.finalizeIsolation(generation, stoppedResult),
+							new Promise<undefined>((resolve) => {
+								const timer = setTimeout(() => resolve(undefined), CONTROL_QUIESCE_TIMEOUT_MS);
+								if (typeof timer.unref === "function") timer.unref();
+							}),
+						]);
+					} catch {
+						/* an unexpected finalize rejection must not block the stop */
+					}
+					if (finalization === undefined) {
+						// Integration is still settling in the background. Point a
+						// durable recovery record at the artifacts so the isolated work
+						// stays findable even if the background tail later fails; a
+						// successful tail removes them and the record self-prunes.
+						if (thread.isolation === "worktree" && worktree) {
+							stoppedResult.integrationStatus = "pending";
+							stoppedResult.integrationWorktreePath = worktree.worktreePath;
+							await persistRecoveryRecords(runtime.configPath, [
+								recoveryRecordFromFinalization(runId, {
+									status: "retained",
+									integrated: false,
+									hadChanges: false,
+									...(existsSync(worktree.worktreePath) ? { worktreePath: worktree.worktreePath } : {}),
+									...(existsSync(worktree.patchPath) ? { patchPath: worktree.patchPath } : {}),
+									error: "subagent_stop timed out waiting for worktree integration; it continues in the background",
+								}),
+							]).catch(() => undefined);
+						}
+						pendingIntegration.push(`#${runId}`);
+					} else if (finalization.status === "retained") {
+						retainedIntegration.push(`#${runId}`);
+					}
 					runtime.registerRunResult(runId, stoppedResult);
 					thread.lastResult = stoppedResult;
 				}
@@ -730,7 +774,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 			return {
 				content: [{
 					type: "text",
-					text: `Stopped ${stopped.length} thread${stopped.length === 1 ? "" : "s"}: ${stopped.join(", ")}. Retained sessions were retired; worktree changes are integrated on settlement.${retainedIntegration.length > 0 ? ` Integration failed for ${retainedIntegration.join(", ")}; inspect its result for retained recovery paths.` : ""}`,
+					text: `Stopped ${stopped.length} thread${stopped.length === 1 ? "" : "s"}: ${stopped.join(", ")}. Retained sessions were retired; worktree changes are integrated on settlement.${retainedIntegration.length > 0 ? ` Integration failed for ${retainedIntegration.join(", ")}; inspect its result for retained recovery paths.` : ""}${pendingIntegration.length > 0 ? ` Integration is still settling in the background for ${pendingIntegration.join(", ")}; a recovery record was persisted in case it fails.` : ""}`,
 				}],
 				details: {},
 			};