@ferris1225/pi-subagents 4.1.5 → 4.1.7

package/README.md

@@ -119,7 +119,10 @@ The runtime deliberately keeps delegation conservative:
 - `worker` and `cleaner` remain distinct write-capable entry roles. Each updates
   existing README/docs/examples/comments directly affected by its change. After
   success, one enabled independent `reviewer` gate runs, with the existing bounded
-  worker ↔ reviewer fix loop for `REVIEW_FAIL`.
+  worker ↔ reviewer fix loop for `REVIEW_FAIL`. Every gate finding carries a
+  concrete fix instruction; the worker implements those instructions or ships a
+  sounder fix with an explicit pushback, and re-review judges the resulting code —
+  only open findings and defects the fix itself introduced can continue the loop.
 - When `documenter` is enabled, every managed reviewer gate is asked for a
   standalone `DOCUMENTATION: CLEAN` or `DOCUMENTATION: NEEDED` line. Only
   `REVIEW_PASS` can authorize the final sync: NEEDED includes
@@ -225,14 +228,19 @@ immediately, while NEEDED (or a missing marker on that passing gate) runs one
 final docs sync. A failure uses the bounded loop:
 
 ```text
-reviewer → worker fixes every open finding → reviewer checks again → …
+reviewer → worker applies each fix instruction (or rebuts with a sounder fix)
+         → reviewer re-reviews the result → …
                                           REVIEW_PASS ─┬─ CLEAN → deliver
                                                        └─ NEEDED/missing → documenter
 ```
 
 Each step gets a fresh model context. The chain shares the same code state and
 passes every full reviewer and worker report forward; it does not reuse one
-context window. Internal children bypass top-level lifecycle policy, so they
+context window. Re-review converges instead of re-auditing: it rules on every
+previous finding once, judges the code as it now stands (a sound worker fix
+counts even when it deviates from the instruction), and adds new findings only
+for defects the fix round's own edits introduced or exposed — issues unrelated
+to those edits belong to a fresh gate, not to the loop. Internal children bypass top-level lifecycle policy, so they
 cannot recursively start another chain. Gate reviewers keep documentation drift
 out of the code verdict while `documenter` is enabled by recording it under
 `## Documentation notes`; with documenter disabled, drift is a normal finding.
@@ -380,16 +388,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 +416,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 +463,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/agents/reviewer.md

@@ -43,7 +43,7 @@ You are a senior, adversarial code reviewer. Find genuine defects and risks rath
 - Return only the review result. Do not repeat the task brief, summarize the implementation, narrate inspection/tool chronology, or explain a root cause when no finding depends on it. Omit transient tool failures that were recovered; report only unresolved coverage gaps.
 - Stay independent of `worker`, `cleaner`, and `documenter`; fix nothing yourself. When a final documenter is available, documentation drift is not a code-gate finding: record it in a short `## Documentation notes` section and carry it forward on re-review. When documenter is disabled, drift is a normal gate finding.
 - Every gate (never an advisory review) must classify documentation on its own standalone machine line. Emit `DOCUMENTATION: NEEDED` and include `## Documentation notes` when a sync is needed; otherwise emit `DOCUMENTATION: CLEAN`. Runtime treats a missing marker conservatively as NEEDED. Do not emit this marker for advisory output.
-- In a gate, every code/test finding enters auto-fix, with no severity tiers. A direct REVIEW_PASS is final for code: CLEAN delivers directly, while NEEDED/missing runs one conditional documentation sync without reopening the gate. On re-review, rule on each open finding once, concretely adjudicate worker rejections, add only defects the fix introduced or exposed, and never re-open a verified resolution.
+- In a gate, every code/test finding enters auto-fix, with no severity tiers, and every gate finding must end with a concrete fix instruction — what to change, where, and how to verify the fix — because a worker implements exactly those instructions unless it can justify a sounder fix and push back. A direct REVIEW_PASS is final for code: CLEAN delivers directly, while NEEDED/missing runs one conditional documentation sync without reopening the gate. On re-review, judge the code as it now stands: a finding is resolved when the pending diff fixes it soundly, whether or not the worker followed your instruction. Rule on each open finding once, concretely adjudicate worker pushback, add only defects the fix introduced or exposed — never issues unrelated to this round's edits — and never re-open a verified resolution.
 - Advisory findings never enter auto-fix; the caller decides whether to authorize later implementation or cleanup.
 
 ## Output
@@ -64,7 +64,7 @@ For a gate review:
 ## Files Reviewed
 - path/to/file.ts
 ## Findings
-- file.ts:42 — concrete issue and why it breaks
+- file.ts:42 — concrete issue and why it breaks — Fix: the change to make and how to verify it
 (Write "None" when no finding remains.)
 ## Documentation notes
 - exact stale surface and required correction

package/agents/worker.md

@@ -34,6 +34,10 @@ Never commit, push, publish, tag, release, or bump a package version. The parent
 - You cannot dispatch sub-agents (children are leaf processes with no `subagent` tool). When the
   brief lacks context that needs broad code discovery, state concretely what an `explorer` should
   retrieve for the caller — do not guess.
+- In an auto-fix round, apply your own judgment to the reviewer's fix instructions: implement each
+  instruction when it is sound; when it is wrong, out of scope, or a sounder fix exists, implement
+  your fix and push back in your report — cite the finding, refute the instruction's reasoning,
+  and describe what you shipped instead. A deviation without reasoning will be re-opened.
 - The parent runtime automatically runs one enabled `reviewer` gate after a successful top-level worker and preserves the bounded worker/reviewer fix loop. A final `documenter` runs only when that terminal review reports documentation drift or omits its marker (or when reviewer is disabled). Report a complete handoff, but do not ask the caller to duplicate downstream roles. Never treat your own verification as the final gate.
 
 ## Output format

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.1.5",
+  "version": "4.1.7",
   "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/fixloop.ts

@@ -3,6 +3,10 @@
  *
  * Successful top-level worker/cleaner runs continue through an independent
  * code review gate; bounded worker → reviewer fix rounds close its findings.
+ * Gate findings carry concrete fix instructions that the worker implements
+ * unless it can justify a sounder fix and push back; re-review adjudicates on
+ * the resulting code (open findings plus fix-introduced defects only) so the
+ * rounds converge instead of re-auditing from scratch.
  * Reviewers classify documentation drift explicitly, so the low-cost final
  * documenter runs only when needed (or conservatively when an older/custom
  * reviewer omits the marker). Direct passing/failing gates use the same policy.
@@ -139,8 +143,9 @@ export function getManagedWorkflowPlan(
 
 /**
  * Build the worker task brief for one fix round from a reviewer's findings.
- * The worker gets the full review text so it can address concrete file:line
- * issues, with instructions to fix every reported finding and self-verify.
+ * The worker gets the full review text — findings plus their fix instructions
+ * — and closes every finding either by implementing the instruction or by
+ * shipping a sounder fix with an explicit per-finding pushback.
  */
 export function buildFixTaskBrief(reviewerResult: SingleResult, round: number, maxRounds: number): string {
 	const review = getResultOutput(reviewerResult);
@@ -153,13 +158,15 @@ export function buildFixTaskBrief(reviewerResult: SingleResult, round: number, m
 		review,
 		`---`,
 		``,
-		`Fix EVERY finding in the reviewer's findings list — there is no severity triage; all of them get fixed.`,
-		`If a finding is factually wrong or clearly out of scope, say so explicitly instead of fixing it.`,
+		`Each finding in the reviewer's report carries a fix instruction. Close EVERY finding — there is no severity triage; all of them get fixed.`,
+		`You own the fix: when an instruction is factually wrong, clearly out of scope, or a sounder fix exists, implement YOUR fix instead,`,
+		`then push back explicitly per finding — cite it, refute the instruction's reasoning, and state what you shipped instead.`,
+		`A pushback without a working alternative or concrete reasoning will be re-opened.`,
 		`Do NOT refactor unrelated code beyond what the findings require.`,
 		`Synchronize any existing README/docs/examples/comments directly affected by your fixes; do not broaden into standalone documentation maintenance.`,
 		`Do NOT commit, push, publish, tag, or release; do not bump versions. The parent chain still owns re-review and any conditional final documentation sync.`,
 		`After editing, run the project's format/build/tests when they exist and report`,
-		`exactly what you changed (paths + short rationale) so a reviewer can verify.`,
+		`exactly what you changed (paths + short rationale) plus any pushback, so a reviewer can verify.`,
 		remaining > 0
 			? `A reviewer will re-review your changes automatically after you finish.`
 			: `This is the last auto-fix round; the workflow conditionally runs any needed final documentation sync and then delivers.`,
@@ -304,6 +311,8 @@ export function buildFinalReviewBrief(
 		``,
 		`Run \`git status\` and \`git diff\` and inspect the actual pending code; the report is context, not proof.`,
 		`Remain read-only. Verify correctness, regressions, and tests.`,
+		`Attach a concrete fix instruction to EVERY gate finding: what to change, where, and how to verify the fix.`,
+		`A worker will implement your instructions unless it can justify a sounder fix and push back, so make each instruction specific enough to act on.`,
 		...(options.documenterPending
 			? [
 				`A conditional documentation sync is available AFTER this gate, so documentation drift is not a code-gate finding.`,
@@ -321,10 +330,11 @@ export function buildFinalReviewBrief(
 
 /**
  * The re-review brief handed to the reviewer after a worker fix round. Includes
- * the prior review and worker report so the reviewer can adjudicate rejections
+ * the prior review and worker report so the reviewer can adjudicate pushback
  * instead of restating findings. The convergence contract keeps rounds from
- * ping-ponging: rule on the open findings once, add only defects this round's
- * edits introduced, never re-open a verified resolution.
+ * ping-ponging: judge the resulting code (not instruction obedience), rule on
+ * the open findings once, add only defects this round's edits introduced,
+ * never re-open a verified resolution.
  */
 export function buildReReviewBrief(
 	reviewerResult: SingleResult,
@@ -342,16 +352,17 @@ export function buildReReviewBrief(
 		review,
 		`---`,
 		``,
-		`The worker's report (what it changed, plus any finding it rejected as factually wrong or out of scope):`,
+		`The worker's report (what it changed, plus any pushback where it replaced your fix instruction with its own fix):`,
 		`---`,
 		workerReport,
 		`---`,
 		``,
-		`Rule on EVERY previous finding: resolved, or still open. A finding the worker rejected must be`,
-		`adjudicated ONCE — accept the rejection unless you can concretely refute the worker's reasoning;`,
-		`never simply restate the finding for another round.`,
-		`Run \`git diff\` to see what changed, then add NEW findings only when they are defects this round's`,
-		`edits introduced or exposed (or a load-bearing issue the earlier review genuinely missed).`,
+		`Rule on EVERY previous finding: resolved, or still open. Judge the code as it now stands — a finding is`,
+		`resolved when the pending diff fixes it soundly, whether or not the worker followed your fix instruction.`,
+		`A finding the worker pushed back on must be adjudicated ONCE — accept the worker's fix unless you can`,
+		`concretely refute its reasoning; never simply restate the finding for another round.`,
+		`Run \`git diff\` to see what changed, then add NEW findings only for defects this round's edits introduced or exposed.`,
+		`Re-review never opens findings unrelated to this round's edits; issues the earlier review missed belong to a fresh gate.`,
 		`Do NOT re-open a finding you verified as resolved.`,
 		...(options.documenterPending
 			? [

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;