@ferris1225/pi-subagents 4.1.5 → 4.1.6

package/README.md

@@ -380,16 +380,26 @@ worktree finalization to the same one-time lifecycle owner. `stop-all` interrupt
 every lane holder before waiting for finalization, avoiding self-deadlock when an
 isolated apply is queued behind shared work.
 
+Every control operation is bounded: park, stop, resume, and fork never wait
+indefinitely on a generation that is still settling (for example an isolated
+apply queued behind the managed repository lane). Stop proceeds after a bounded
+deadline once it owns the lifecycle, a still-running integration continues in the
+background, and a durable recovery record is persisted pointing at the retained
+worktree/patch so stopped work is never lost.
+
 ## Results and live status
 
 The active TUI widget shows standalone runs normally and projects each managed
-workflow as a compact timeline plus its current internal child:
+workflow as a compact timeline plus its current internal child. Every row leads
+with its stable run id — the handle for `subagent_control`, `subagent_status`,
+and `subagent_stop`:
 
 ```text
-◆ worker workflow · src/cache.ts                         · 42s
+◆ #12 worker workflow · src/cache.ts · wt:a91f3c              · 42s
   ✓ implement ─ ● review ─ ○ docs
-  └ ● reviewer · final review · claude-sonnet-4-5/high · 10s
+  └ ● #15 reviewer · final review · claude-sonnet-4-5/high · 10s
       git diff
+○ #23 worker · queued · redirect to ripgrep crates · 5m02s
 ```
 
 Success is green, the active stage uses the accent color and bold text, pending
@@ -398,6 +408,15 @@ error. Fix paths show their budget (`fix 1/2`, `re-review 1/2`). The timeline
 contains only stages that ran or are currently planned; `DOCUMENTATION: CLEAN`
 removes pending docs instead of pretending that stage ran.
 
+Worktree-isolated runs carry a group badge on the row that owns the worktree:
+`wt:<id>` while active, `wt:<id> applying` while the settled patch is being
+applied to the original checkout, then `applied`/`clean`, or `retained` when
+integration failed. The short id changes when a resumed generation creates a
+continuation worktree, so a group boundary change is visible at a glance.
+Nested stage rows inherit the group through the tree instead of repeating the
+badge. Queued rows say `queued` and omit model/thinking — the route is
+re-resolved when the run actually starts.
+
 A managed root keeps its original top-level role and workflow-wide elapsed time,
 but omits model/thinking because several model stages own it. The active nested
 row shows the current role, relation, selected/fallback model, thinking, stage
@@ -436,6 +455,12 @@ session. Searches, reads, reasoning, and edits already completed are preserved.
 Ordinary tool and test failures remain task failures and do not trigger a model
 handoff.
 
+Model changes apply immediately to work that has not started: a run still
+waiting for a concurrency slot re-resolves its route when it actually starts,
+and managed workflow stages (fix rounds, re-reviews, the conditional documenter)
+re-read the config before each stage launches. Only an already-running child
+keeps the model it started with.
+
 Thinking defaults to **Auto**. pi-subagents starts from the role's preference and
 chooses only a level the effective model actually supports. A fallback re-checks
 the level for the main model. `documenter` deliberately ships with the same fast,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.1.5",
+  "version": "4.1.6",
   "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

package/src/dispatch.ts

@@ -208,7 +208,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				if (!run) return; // already finished — stay idempotent
 				if (opts?.silent || !runtime.sessionActive) return;
 				const icon = status === "done" ? "✓" : "✗";
-				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
+				ctx.ui.notify(`${icon} #${run.id} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
 			};
 
 			// Live sub-agent activity → concise one-line status ("thinking",
@@ -315,7 +315,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const resolveLiveAgentTools = (candidate: AgentConfig): AgentConfig =>
 					resolveAgentTools({ ...candidate, tools: discoveredAgent.tools }, runtime.getActiveTools());
 				const agent = resolveLiveAgentTools(discoveredAgent);
-				const resolvedRoute = resolveDispatchModelRoute(agent, request.config, request.ctx);
+				// Workflow policy (fix-round caps, agents) stays fixed for the chain,
+				// but model/thinking routes are re-read per stage so config edits
+				// apply to stages that have not launched yet.
+				const stageConfig = await loadConfig(runtime.configPath).catch(() => request.config);
+				const resolvedRoute = resolveDispatchModelRoute(agent, stageConfig, request.ctx);
 				const route = request.isolation === "worktree"
 					? { ...resolvedRoute, agent: withWorktreeSystemPrompt(resolvedRoute.agent) }
 					: resolvedRoute;
@@ -323,6 +327,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const runId = monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, {
 					...meta,
 					isolation: request.isolation,
+					...(request.worktreeId ? { worktreeId: request.worktreeId } : {}),
 				});
 				const onLive = makeLiveHandler(runId);
 				try {
@@ -339,7 +344,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							signal: request.signal,
 							onLive,
 							makeDetails: makeDetails("single", true),
-							idleTimeoutMs: request.config.idleTimeoutSec * 1000,
+							idleTimeoutMs: stageConfig.idleTimeoutSec * 1000,
 						},
 						route.mainFallbackRef,
 					);

package/src/monitor.ts

@@ -34,13 +34,18 @@ export function isRunActiveStatus(status: RunStatus): boolean {
 	return status === "queued" || status === "running" || status === "steering" || status === "interrupting";
 }
 
+/** Durable integration projection of a worktree-isolated run: pending before
+ * settlement, finalizing while the patch is applied/cleaned up, then the
+ * terminal WorktreeFinalizationStatus. */
+export type RunIntegrationStatus = "pending" | "finalizing" | WorktreeFinalizationStatus;
+
 export interface RunView {
 	id: number;
 	agent: string;
 	task: string;
 	/** Short content label derived from the task (paths/symbols), shown next to
 	 * the agent name so concurrent same-agent runs are told apart by what they
-	 * are doing, not just their run id. */
+	 * are doing, not just by their run id. */
 	label?: string;
 	model?: string;
 	/** Selected model ref when the run handed off to current main. */
@@ -48,7 +53,10 @@ export interface RunView {
 	/** Effective thinking strength this run was launched with (frontmatter/config/global). */
 	thinking?: string;
 	isolation?: IsolationMode;
-	integrationStatus?: "pending" | WorktreeFinalizationStatus;
+	integrationStatus?: RunIntegrationStatus;
+	/** Short worktree-group identity (mkdtemp suffix) shared by every run inside
+	 * one isolated worktree; changes when a continuation worktree is created. */
+	worktreeId?: string;
 	forkedFromRunId?: number;
 	forkChildRunIds?: number[];
 	status: RunStatus;
@@ -85,6 +93,7 @@ export interface RunChainMeta {
 	relationLabel?: string;
 	parentRunId?: number;
 	isolation?: IsolationMode;
+	worktreeId?: string;
 	forkedFromRunId?: number;
 	continuationKind?: ContinuationKind;
 }
@@ -458,7 +467,7 @@ export class MonitorStore {
 			...(meta?.groupId ? { groupId: meta.groupId } : {}),
 			...(meta?.relationLabel ? { relationLabel: meta.relationLabel } : {}),
 			...(meta?.parentRunId !== undefined ? { parentRunId: meta.parentRunId } : {}),
-			...(meta?.isolation ? { isolation: meta.isolation, integrationStatus: meta.isolation === "worktree" ? "pending" : undefined } : {}),
+			...(meta?.isolation ? { isolation: meta.isolation, integrationStatus: meta.isolation === "worktree" ? "pending" : undefined, ...(meta.worktreeId ? { worktreeId: meta.worktreeId } : {}) } : {}),
 			...(meta?.forkedFromRunId !== undefined ? { forkedFromRunId: meta.forkedFromRunId } : {}),
 			...(meta?.continuationKind ? { continuationKind: meta.continuationKind } : {}),
 		});
@@ -559,11 +568,17 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	setIsolation(id: number, isolation: IsolationMode, integrationStatus?: "pending" | WorktreeFinalizationStatus): void {
+	setIsolation(
+		id: number,
+		isolation: IsolationMode,
+		integrationStatus?: RunIntegrationStatus,
+		worktreeId?: string,
+	): void {
 		const run = this.find(id);
 		if (!run) return;
 		run.isolation = isolation;
 		run.integrationStatus = integrationStatus;
+		if (worktreeId) run.worktreeId = worktreeId;
 		this.notify();
 	}
 
@@ -608,7 +623,7 @@ export class MonitorStore {
 		model?: string,
 		thinking?: string,
 		isolation?: IsolationMode,
-		meta?: { elapsedMs?: number; continuationKind?: ContinuationKind },
+		meta?: { elapsedMs?: number; continuationKind?: ContinuationKind; worktreeId?: string },
 	): void {
 		const run = this.find(id);
 		if (!run) {
@@ -619,7 +634,13 @@ export class MonitorStore {
 				label: runLabel(task),
 				model,
 				thinking,
-				...(isolation ? { isolation, integrationStatus: isolation === "worktree" ? "pending" as const : undefined } : {}),
+				...(isolation
+					? {
+						isolation,
+						integrationStatus: isolation === "worktree" ? "pending" as const : undefined,
+						...(isolation === "worktree" && meta?.worktreeId ? { worktreeId: meta.worktreeId } : {}),
+					}
+					: {}),
 				status: "queued",
 				usage: emptyUsage(),
 				elapsedMs: meta?.elapsedMs ?? 0,
@@ -635,6 +656,8 @@ export class MonitorStore {
 		run.thinking = thinking;
 		if (isolation) run.isolation = isolation;
 		run.integrationStatus = isolation === "worktree" ? "pending" : undefined;
+		if (isolation === "worktree" && meta?.worktreeId) run.worktreeId = meta.worktreeId;
+		else if (isolation !== "worktree") run.worktreeId = undefined;
 		run.status = "queued";
 		run.usage = emptyUsage();
 		run.activity = undefined;

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

@@ -67,6 +67,7 @@ import {
 } from "./spawn.ts";
 import {
 	createWorktreeIsolation,
+	worktreeGroupId,
 	type IsolationMode,
 	type WorktreeFinalization,
 	type WorktreeIsolation,
@@ -75,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.";
 
@@ -148,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;
 }
@@ -294,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
@@ -310,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 } : {}),
 		});
@@ -329,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);
 		}
@@ -426,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";
@@ -565,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 ||
@@ -631,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,
@@ -811,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.`);
 				}
@@ -911,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,
@@ -938,7 +1009,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 								}
 								: {}),
 						},
-						route.mainFallbackRef,
+						activeRoute.mainFallbackRef,
 					);
 				} catch (error) {
 					const errorMessage = error instanceof Error ? error.message : String(error);
@@ -1013,6 +1084,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 						executionCwd: thread.executionCwd,
 						projectCwd: originalCwd,
 						isolation,
+						...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
 						signal: backgroundSignal,
 						ctx: runCtx,
 						config: runConfig,

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: {},
 			};

package/src/widget.ts

@@ -39,6 +39,26 @@ function formatContinuationTask(label: string, task: string, width: number): str
 	return summary ? `${label}${separator}${summary}` : label;
 }
 
+/** Worktree-group badge shown on the row that owns the isolated worktree: the
+ * short group identity plus its integration state, so a workflow visibly moves
+ * through applying → applied (or retained) and a continuation worktree (new
+ * identity) is distinguishable from the original one. */
+function worktreeBadge(run: RunView): string {
+	const id = run.worktreeId ?? "?";
+	switch (run.integrationStatus) {
+		case "finalizing":
+			return `wt:${id} applying`;
+		case "integrated":
+			return `wt:${id} applied`;
+		case "no_changes":
+			return `wt:${id} clean`;
+		case "retained":
+			return `wt:${id} retained`;
+		default:
+			return `wt:${id}`;
+	}
+}
+
 /** One compact primary line per genuinely active run, plus an optional indented
  * activity line. The primary line reserves stage model/thinking when present and
  * elapsed width before truncating the task. Settled and parked threads never
@@ -49,6 +69,7 @@ function runPrimaryLine(
 	width: number,
 	now: number,
 	prefix: string,
+	isGroupOwner: boolean,
 ): string {
 	const dim = (text: string): string => theme.fg("dim", text);
 	const icon = run.managedWorkflow && run.status === "running"
@@ -56,18 +77,24 @@ function runPrimaryLine(
 		: statusIcon(run.status, theme);
 	const displayName = run.managedWorkflow ? `${run.agent} workflow` : run.agent;
 	const name = theme.fg("accent", theme.bold(displayName));
-	const identity = `${prefix}${icon} ${name}`;
+	// The stable run id is the handle for subagent_control/subagent_status; a
+	// queued run has not started, which must be visible at a glance. Its model
+	// is omitted too: the route is re-resolved when the run actually starts.
+	const queued = run.status === "queued";
+	const queuedTag = queued ? ` ${dim("· queued")}` : "";
+	const identity = `${prefix}${icon} #${run.id} ${name}${queuedTag}`;
 	const elapsed = formatElapsed(run, now);
 	// Render only the resolved model id plus thinking level. Provider auth and
 	// other configuration never enter monitor state or this line.
 	const modelId = run.model?.split("/").at(-1);
-	const modelSource = run.managedWorkflow
+	const modelSource = run.managedWorkflow || queued
 		? ""
 		: formatTaskSummary(
 			modelId ? `${modelId}${run.thinking ? `/${run.thinking}` : ""}` : run.thinking ? `thinking:${run.thinking}` : "",
 			64,
 			false,
 		);
+	const badge = isGroupOwner && run.isolation === "worktree" ? worktreeBadge(run) : "";
 	// A chain child shows its role in the chain plus a task-derived label; the
 	// templated fix brief itself would only repeat the parent review's content.
 	const continuation = run.parentRunId === undefined
@@ -81,7 +108,7 @@ function runPrimaryLine(
 	const taskDesiredSource = [continuation, taskSource]
 		.filter((part): part is string => Boolean(part))
 		.join(" · ");
-	const primaryPartCount = 2 + (modelSource ? 1 : 0) + (elapsed ? 1 : 0);
+	const primaryPartCount = 2 + (modelSource ? 1 : 0) + (badge ? 1 : 0) + (elapsed ? 1 : 0);
 	const contentWidth = Math.max(
 		0,
 		width -
@@ -130,6 +157,7 @@ function runPrimaryLine(
 		identity,
 		task ? dim(task) : undefined,
 		modelThinking ? dim(modelThinking) : undefined,
+		badge ? dim(badge) : undefined,
 	].filter((part): part is string => Boolean(part)).join(" · ");
 	return compactLine(primaryLeft, elapsed ? dim(`· ${elapsed}`) : "", width);
 }
@@ -211,7 +239,9 @@ export function formatActiveRunLines(
 	const lines: string[] = [];
 	for (const root of roots) {
 		const children = childrenOf.get(root.id) ?? [];
-		lines.push(runPrimaryLine(root, theme, width, now, ""));
+		// Roots (including orphaned chain children whose parent row is gone) own
+		// their worktree group; nested children inherit the group via the tree.
+		lines.push(runPrimaryLine(root, theme, width, now, "", true));
 		const hasTimeline = Boolean(root.managedWorkflow && root.workflowStages?.length);
 		const timeline = hasTimeline ? workflowTimelineLine(root, theme, width) : undefined;
 		if (timeline) lines.push(timeline);
@@ -222,7 +252,7 @@ export function formatActiveRunLines(
 		}
 		children.forEach((child, index) => {
 			const connector = index === children.length - 1 ? "└ " : "├ ";
-			lines.push(runPrimaryLine(child, theme, width, now, theme.fg("dim", `  ${connector}`)));
+			lines.push(runPrimaryLine(child, theme, width, now, theme.fg("dim", `  ${connector}`), false));
 			lines.push(...runActivityLine(child, theme, width, "      "));
 		});
 	}

package/src/worktree.ts

@@ -16,6 +16,18 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 
 export type IsolationMode = "shared" | "worktree";
 
+const WORKTREE_TEMP_DIR_PREFIX = "pi-subagent-worktree-";
+
+/** Short stable identity of one isolated worktree group (the mkdtemp suffix).
+ * Continuation/fork generations create a fresh worktree, so the identity
+ * visibly changes when the group's filesystem boundary changes. */
+export function worktreeGroupId(worktree: Pick<WorktreeIsolation, "tempDir">): string {
+	const base = worktree.tempDir.split(/[\\/]/).filter(Boolean).pop() ?? worktree.tempDir;
+	return base.startsWith(WORKTREE_TEMP_DIR_PREFIX)
+		? base.slice(WORKTREE_TEMP_DIR_PREFIX.length)
+		: base;
+}
+
 export interface CommandRunOptions {
 	cwd: string;
 	input?: Buffer;