@ferris1225/pi-subagents 1.0.0 → 2.0.0

package/src/dispatch.ts

@@ -1,12 +1,11 @@
 /**
- * The `subagent` tool: dispatches explore/worker/reviewer agents as isolated pi
+ * The `subagent` tool: dispatches explore/worker/cleaner/reviewer agents as isolated pi
  * child processes, single or parallel. Owns the dispatch pipeline: config load,
- * per-agent model-pool resolution, per-run status tracking, the auto-fix chain
+ * per-agent selected→main model routing, per-run status tracking, the auto-fix chain
  * (REVIEW_FAIL → worker → re-review), and completion delivery.
  *
- * Vision: a task flagged `vision: true` uses the configured vision model as an
- * explicit primary, then the agent's configured backup and the current
- * main-window model. Stale refs remain in the pool and fail normally at runtime.
+ * Vision: a task flagged `vision: true` uses the configured vision model, then
+ * hands directly to the current main-window model on model/provider failure.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -21,7 +20,12 @@ import {
 	completionTriggersTurn,
 	type CompletionMessageItem,
 } from "./completion.ts";
-import { loadConfig, type SubagentsConfig } from "./config.ts";
+import {
+	DEFAULT_THINKING_LEVEL,
+	loadConfig,
+	type SubagentsConfig,
+	type ThinkingLevel,
+} from "./config.ts";
 import {
 	dispatchFailedResult,
 	failedStartResult,
@@ -35,10 +39,16 @@ import {
 	buildReReviewBrief,
 	formatChainSummary,
 	shouldTriggerFixLoop,
-	summarizeChainResult,
 	type ChainStep,
 } from "./fixloop.ts";
-import { currentModelRef, resolveAgentModelPool } from "./models.ts";
+import {
+	availableModelsInScope,
+	currentModelRef,
+	findModelByRef,
+	modelRef,
+	resolveAgentModelRoute,
+	resolveThinkingLevel,
+} from "./models.ts";
 import {
 	formatTaskSummary,
 	formatToolActivity,
@@ -50,19 +60,17 @@ import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts"
 import { persistRecoveryRecords, recoveryRecordFromFinalization } from "./recovery.ts";
 import { forkRetainedSession } from "./session-fork.ts";
 import {
-	buildFallbackResumeReason,
 	buildResumePrompt,
 	RpcRunControl,
 	getResultOutput,
 	isFailedResult,
 	isModelLevelFailure,
 	reviewVerdict,
-	runSingleAgentWithModelFallback,
+	runSingleAgentWithMainFallback,
 	type SingleResult,
 	type SubagentDetails,
 	type SubagentLiveEvent,
 } from "./spawn.ts";
-import { trajectoryStore, summarizeToolArgs } from "./trajectory.ts";
 import {
 	createWorktreeIsolation,
 	resolveWorktreeTarget,
@@ -74,13 +82,9 @@ import {
 const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
 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.";
-export const WORKTREE_ISOLATION_INSTRUCTIONS =
+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.";
 
-export function buildWorktreeTaskPrompt(task: string): string {
-	return `${WORKTREE_ISOLATION_INSTRUCTIONS}\n\nTask: ${task}`;
-}
-
 function withWorktreeSystemPrompt(agent: AgentConfig): AgentConfig {
 	return {
 		...agent,
@@ -92,14 +96,13 @@ interface DispatchEnvironment {
 	ctx: ExtensionContext;
 	config: SubagentsConfig;
 	agents: AgentConfig[];
-	sessionRef?: string;
 }
 
 const VISION_DESCRIPTION =
-	"Set true when the task may require viewing images (screenshots, mockups, designs) — the configured vision model becomes primary, followed by the agent backup and current main-window model";
+	"Set true when the task may require viewing images (screenshots, mockups, designs) — the configured vision model is used first, then model-level failures hand directly to the current main-window model";
 
 const ISOLATION_DESCRIPTION =
-	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents only)";
+	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents, including worker and cleaner, only)";
 
 const IsolationSchema = Type.Optional(
 	StringEnum(["shared", "worktree"] as const, { description: ISOLATION_DESCRIPTION }),
@@ -181,21 +184,39 @@ function serializeAutoFixChain(
 	};
 }
 
-function resolveDispatchModelPool(
+interface DispatchModelRoute {
+	agent: AgentConfig;
+	mainFallbackRef?: string;
+	thinkingLevel: ThinkingLevel;
+	thinkingLevelForModel: (ref?: string) => ThinkingLevel;
+}
+
+function resolveDispatchModelRoute(
 	agent: AgentConfig,
 	config: SubagentsConfig,
-	mainRef: string | undefined,
+	ctx: ExtensionContext,
 	vision: boolean,
-): { agent: AgentConfig; fallbackModelRefs: string[] } {
-	const pool = resolveAgentModelPool({
-		primaryRef: vision ? config.visionModel : config.agentModels[agent.name],
-		backupRef: config.agentBackupModels[agent.name],
+): DispatchModelRoute {
+	const availableModels = availableModelsInScope(ctx);
+	const mainRef = currentModelRef(ctx);
+	const route = resolveAgentModelRoute({
+		selectedRef: vision ? config.visionModel : config.agentModels[agent.name],
 		mainRef,
 		declaredDefaultRef: agent.model,
+		availableRefs: availableModels.map(modelRef),
 	});
+	const preferred = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? DEFAULT_THINKING_LEVEL;
+	const thinkingLevelForModel = (ref?: string): ThinkingLevel => {
+		const model = ref === mainRef && ctx.model
+			? ctx.model
+			: findModelByRef(availableModels, ref);
+		return resolveThinkingLevel(model, preferred);
+	};
 	return {
-		agent: { ...agent, model: pool.primaryRef },
-		fallbackModelRefs: pool.fallbackModelRefs,
+		agent: { ...agent, model: route.primaryRef },
+		mainFallbackRef: route.mainFallbackRef,
+		thinkingLevel: thinkingLevelForModel(route.primaryRef),
+		thinkingLevelForModel,
 	};
 }
 
@@ -205,33 +226,36 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		label: "Subagent",
 		description: [
 			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
-			"Agents: explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
+			"Built-in roles (only configured enabled agents can dispatch): explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), cleaner (explicit evidence-first cleanup, full/write tools), reviewer (adversarial pre-commit gate, read-only).",
+			"When cleaner is enabled, route explicit cleanup intent in any language (for example dead code, redundancy, simplification, or over-engineering), including a requested periodic cleanup pass. Audit/find/inspect/report is read-only evidence, while explicit remove/clean/simplify/refactor permits verified edits. Generic code review goes to reviewer. Never route cleaner by PR count or as the pre-commit gate; reviewer reviews its edits.",
 			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
-			"Isolation: single tasks default to shared; parallel worker tasks default to detached Git worktrees unless isolation: shared is explicit. explore/reviewer cannot use worktree isolation.",
+			"Isolation: single tasks default to shared; parallel worker tasks default to detached Git worktrees unless isolation: shared is explicit. Cleaner is write-capable and can opt into worktree isolation; explore/reviewer cannot use it.",
 			"Use subagent_control to steer, retarget, park, resume, or fork a thread by its stable run id.",
 			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
 			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
 			"Results arrive as wake-up messages automatically — you do NOT need to wait. If you must get a result in-turn, subagent_wait is a non-blocking lookup by default (pass timeoutMs to block).",
-			"Vision: set vision: true when the task may require viewing images (screenshots, mockups, design files — e.g. frontend work) — the configured vision model is primary, followed by that agent's backup and the current main-window model.",
+			"Vision: set vision: true when the task may require viewing images (screenshots, mockups, design files — e.g. frontend work) — the configured vision model is used first, then model-level failures hand directly to the current main-window model.",
 		].join(" "),
 		promptSnippet:
-			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
+			"Start background subagents: explore (read-only search), worker (implement), cleaner (explicit evidence-first cleanup), reviewer (pre-commit review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
 		promptGuidelines: [
-			"Delegate only when an isolated context genuinely pays: broad exploration, a self-contained implementation, or a review gate. Handle simple lookups and one-line edits inline with direct tools — never spawn a sub-agent for them.",
+			"Delegate only when an isolated context genuinely pays: broad exploration, a self-contained implementation, explicit evidence-first cleanup, or a review gate. Handle simple lookups and one-line edits inline with direct tools — never spawn a sub-agent for them.",
 			"Use subagent with agent 'explore' for broad or open-ended code search before large changes; a targeted 'where is X' is a direct grep/read.",
+			"Treat explore output as a retrieval index, not authority: re-read load-bearing files before editing or deciding deletion, security, compatibility, persistence, or dynamic reachability. The cheapest model can cost more through rework on complex dynamic, concurrent, migration, or security-sensitive code; choose a stronger model or specialist there.",
 			"Use subagent with agent 'worker' for a self-contained implementation task worth a separate context; it plans internally.",
-			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
+			"When cleaner is enabled, use subagent with agent 'cleaner' only for explicit cleanup intent in any language (for example dead code, redundancy, simplification, or over-engineering) or a requested periodic cleanup pass. Audit/find/inspect/report means read-only ranked evidence; apply only for explicit remove/clean/simplify/refactor wording. Generic code review goes to reviewer. Never trigger cleaner from PR count or as a pre-commit gate; send non-trivial cleaner edits to reviewer.",
+			"Use subagent with agent 'reviewer' for the fresh read-only gate before reporting non-trivial work done or committing, including after cleaner edits.",
 			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
 			"Run independent tasks in parallel by passing a tasks array to subagent; parallel worker items default to isolation: worktree so their edits are integrated independently. Pass isolation: shared only when workers intentionally need the caller's live uncommitted tree.",
-			"Use isolation: worktree only for worker/write-capable agents and only inside a Git repository with a committed HEAD; setup or integration failures never silently fall back to shared.",
+			"Use isolation: worktree only for worker, cleaner, or another write-capable agent and only inside a Git repository with a committed HEAD; parallel worker tasks default to worktree, while cleaner must opt in. Setup or integration failures never silently fall back to shared.",
 			"NEVER sleep or poll, and do NOT call subagent_wait to hold the turn — subagent ends the turn immediately and the result arrives as a message that wakes you automatically (even mid-turn). Ending your turn is the default and the only correct way to wait.",
 			"If you must keep the turn for a result, call subagent_wait with an explicit timeoutMs (non-blocking by default) — never bash sleep/timeout to wait for a sub-agent.",
-			"When a delegated task may require viewing images (frontend screenshots, mockups, design comparisons), pass vision: true and give the sub-agent the exact image paths — it reads them with its read tool. The configured vision model becomes primary; model-level failures continue through the agent's backup pool and current main-window model.",
+			"When a delegated task may require viewing images (frontend screenshots, mockups, design comparisons), pass vision: true and give the sub-agent the exact image paths — it reads them with its read tool. The configured vision model is used first; model-level failures hand directly to the current main-window model.",
 			"When a sub-agent result arrives it is already shown to the user — do NOT restate, paraphrase, or summarize it; reply with only your own conclusion or next action (often just one line), since duplicating the result wastes tokens for nothing.",
 		],
 		parameters: SubagentParams,
 
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			monitor.beginTurn();
 			const config = await loadConfig(runtime.configPath);
 			// Pick up concurrency changes from /subagents-setup without a restart.
@@ -242,29 +266,25 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			const finishRun = (
 				runId: number,
 				status: "done" | "failed",
-				opts?: { silent?: boolean; retain?: boolean },
+				opts?: { silent?: boolean },
 			): void => {
 				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
-				const run = opts?.retain ? monitor.findRun(runId) : monitor.removeRun(runId);
+				const run = monitor.removeRun(runId);
 				if (!run) return; // already finished — stay idempotent
-				if (opts?.retain) monitor.setRetained(runId, true);
 				if (opts?.silent || !runtime.sessionActive) return;
 				const icon = status === "done" ? "✓" : "✗";
 				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
 			};
 
 			// Live sub-agent activity → concise one-line status ("thinking",
-			// "read src/index.ts", ...), never a raw args blob. In parallel, every
-			// live event is appended to the thread's append-only trajectory (status,
-			// model-candidate changes, usage, tool starts/ends with a redacted
-			// args summary). The live handler only updates monitor state; finishing
-			// (removeRun + notify) is
-			// owned by the queue task / launchInLoop. That keeps a startup retry —
+			// "read src/index.ts", ...), never a raw args blob. The live handler
+			// only updates monitor state; finishing (removeRun + notify) is owned
+			// by the queue task / launchInLoop. That keeps a startup retry —
 			// which fires a transient "failed" status before relaunching — from
 			// ripping the row out early, and lets the queue task decide between
 			// delivering a reviewer's result and starting an auto-fix chain.
 			const makeLiveHandler =
-				(runId: number, threadId?: number, generation?: number) =>
+				(runId: number, generation?: number) =>
 				(e: SubagentLiveEvent): void => {
 					if (generation !== undefined && runtime.threads.get(runId)?.generation !== generation) return;
 					switch (e.kind) {
@@ -277,6 +297,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							break;
 						case "model":
 							monitor.setModel(runId, e.model, e.fallbackFrom);
+							monitor.setThinking(runId, e.thinking);
 							break;
 						case "usage":
 							monitor.setUsage(runId, e.usage, e.model);
@@ -295,31 +316,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							monitor.setActivity(runId, "responding");
 							break;
 					}
-					if (threadId !== undefined) {
-						const trajectory = trajectoryStore.get(threadId).trajectory;
-						switch (e.kind) {
-								case "status":
-									trajectory.append({ kind: "status", status: e.status });
-									break;
-								case "model":
-									trajectory.append({ kind: "candidate", model: e.model, fallbackFrom: e.fallbackFrom });
-									break;
-								case "usage":
-									trajectory.append({ kind: "usage", usage: { ...e.usage }, model: e.model });
-									break;
-								case "tool_start":
-									trajectory.append({
-										kind: "tool_start",
-										tool: e.toolName,
-										toolCallId: e.toolCallId,
-										summary: summarizeToolArgs(e.args),
-									});
-									break;
-								case "tool_end":
-									trajectory.append({ kind: "tool_end", tool: e.toolName, toolCallId: e.toolCallId, isError: e.isError });
-									break;
-							}
-					}
 				};
 
 			const discovery = discoverAgents(ctx.cwd, {
@@ -327,7 +323,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				enabledNames: config.enabledAgents,
 				projectTrusted: ctx.isProjectTrusted?.() === true,
 			});
-			const sessionRef = currentModelRef(ctx);
 			const agents = discovery.agents;
 
 			const hasTasks = (params.tasks?.length ?? 0) > 0;
@@ -391,70 +386,48 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			): Promise<{ runId?: number; result: SingleResult }> => {
 				const agent = agents.find((candidate) => candidate.name === agentName);
 				if (!agent) return { result: failedStartResult(agentName, task, `Unknown agent: "${agentName}".`) };
-				// Vision chains keep the vision override as each round's primary while
-				// retaining that worker/reviewer's own configured backup pool.
-				const pool = resolveDispatchModelPool(agent, config, sessionRef, vision);
-				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
-				const runId = monitor.addRun(agent.name, task, pool.agent.model, thinkingLevel, meta);
-				// Chain rounds keep their own lifecycle trajectory.
-				const chainState = trajectoryStore.get(runId);
-				chainState.trajectory.append({
-					kind: "dispatch",
-					agent: agent.name,
-					task,
-					model: pool.agent.model,
-					thinking: thinkingLevel,
-					pool: pool.fallbackModelRefs,
-					vision,
-					isolation: "shared",
-					originalCwd: executionCwd,
-					isolationCwd: executionCwd,
-				});
-				const onLive = makeLiveHandler(runId, runId);
+				// Vision chains use the vision override first; every model-level failure
+				// hands directly to the current main model with re-clamped thinking.
+				const route = resolveDispatchModelRoute(agent, config, ctx, vision);
+				const thinkingLevel = route.thinkingLevel;
+				const runId = monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, meta);
+				const onLive = makeLiveHandler(runId);
 				try {
-					const result = await runSingleAgentWithModelFallback(
+					const result = await runSingleAgentWithMainFallback(
 						{
 							defaultCwd: executionCwd,
 							cwd: executionCwd,
-							agent: pool.agent,
+							agent: route.agent,
 							agentName,
 							task,
 							thinkingLevel,
+							thinkingLevelForModel: route.thinkingLevelForModel,
 							signal,
 							onLive,
 							makeDetails: makeDetails("single", true),
 							idleTimeoutMs: config.idleTimeoutSec * 1000,
 						},
-						pool.fallbackModelRefs,
+						route.mainFallbackRef,
 					);
 					result.runId = runId;
+					result.projectCwd = executionCwd;
 					result.isolation = "shared";
-					result.originalCwd = executionCwd;
-					result.isolationCwd = executionCwd;
 					runtime.retainSession(result);
 					monitor.setModel(runId, result.model, result.modelFallbackFrom);
-					chainState.trajectory.append({
-						kind: "settled",
-						status: isFailedResult(result) ? "failed" : "done",
-						model: result.model,
-					});
-					// Keep the finished round in status state while the chain is
-					// still running, with a one-line summary of what it did; the whole
-					// group is dropped when the chain resolves (see removeChainGroup).
-					monitor.setSummary(runId, summarizeChainResult(result));
-					finishRun(runId, isFailedResult(result) ? "failed" : "done", { retain: true });
+					monitor.setThinking(runId, result.thinking);
+					// The parent row represents the chain. Internal rounds leave live
+					// status as soon as they settle; their reports remain addressable by id.
+					finishRun(runId, isFailedResult(result) ? "failed" : "done", { silent: true });
 					runtime.registerRunResult(runId, result);
 					return { runId, result };
 				} catch (error) {
-					finishRun(runId, "failed", { retain: true });
-					chainState.trajectory.append({ kind: "settled", status: "failed", model: pool.agent.model });
+					finishRun(runId, "failed", { silent: true });
 					const errorMessage = error instanceof Error ? error.message : String(error);
 					const crashed: SingleResult = {
-						...queuedResult(pool.agent, task, thinkingLevel),
+						...queuedResult(route.agent, task, thinkingLevel),
 						runId,
+						projectCwd: executionCwd,
 						isolation: "shared",
-						originalCwd: executionCwd,
-						isolationCwd: executionCwd,
 						exitCode: 1,
 						stderr: errorMessage,
 						stopReason: signal.aborted ? "aborted" : "error",
@@ -473,7 +446,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			 * Failures short-circuit: a crashed worker skips its re-review and delivers.
 			 * The triggering reviewer stays in monitor state until the chain resolves.
 			 */
-			/** Drop every monitor row belonging to an auto-fix chain; the retained
+			/** Drop any in-flight monitor row belonging to an auto-fix chain; the
 			 * parent is removed separately (it does not carry the groupId). */
 			const removeChainGroup = (groupId: string): void => {
 				for (const run of [...monitor.getRuns()]) {
@@ -514,10 +487,20 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				};
 				fixController = runtime.backgroundQueue.enqueue(
 					serializeAutoFixChain(executionCwd, async (signal) => {
+						if (!ownsParent()) return;
+						// The parent id belongs to the stable logical thread and will point at
+						// the chain outcome. Archive the triggering review under its own id so
+						// every id advertised by the chain summary resolves to that exact step.
+						const initialStepRunId = monitor.reserveRunId();
+						const initialStepResult: SingleResult = {
+							...initialReviewerResult,
+							runId: initialStepRunId,
+						};
+						runtime.registerRunResult(initialStepRunId, initialStepResult);
 						const chain: ChainStep[] = [
-							{ runId: parentRunId, result: initialReviewerResult, relation: "initial review" },
+							{ runId: initialStepRunId, result: initialStepResult, relation: "initial review" },
 						];
-						let lastReviewer = initialReviewerResult;
+						let lastReviewer = initialStepResult;
 						for (let round = 1; round <= config.maxFixRounds; round++) {
 							if (!runtime.sessionActive) break;
 							const fixBrief = buildFixTaskBrief(lastReviewer, round, config.maxFixRounds);
@@ -579,37 +562,34 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							return;
 						}
 						// Parking an auto-fix chain aborts its in-flight child but preserves the
-						// parent's retained checkpoint and suppresses an aborted chain delivery.
+						// parent's checkpoint and suppresses an aborted chain delivery.
 						if (controlledParent.state === "parked") {
 							clearOwnedController();
 							removeChainGroup(parentGroupId);
-							monitor.setRetained(parentRunId, false);
 							monitor.setStatus(parentRunId, "parked");
 							return;
 						}
-						// The chain is done (success, exhaustion, or abort): drop the retained
-						// parent row and its retained round rows, then deliver one condensed
+						// The chain is done (success, exhaustion, or abort): drop its monitor
+						// rows, then deliver one condensed
 						// summary. Register the parent's final state (the last chain result)
-						// before removal so subagent_wait can resolve it.
+						// before removal so subagent_wait can resolve it. Clone instead of
+						// mutating: the internal step remains addressable under its own run id.
 						const last = chain[chain.length - 1];
-						runtime.registerRunResult(parentRunId, last.result);
+						const parentResult: SingleResult = {
+							...last.result,
+							runId: parentRunId,
+						};
+						runtime.registerRunResult(parentRunId, parentResult);
 						removeChainGroup(parentGroupId);
 						monitor.removeRun(parentRunId);
-						runtime.retainSession(last.result);
+						runtime.retainSession(parentResult);
 						const parentThread = parentThreadAtStart;
+						parentThread.lastResult = parentResult;
 						parentThread.agentName = last.result.agent;
 						parentThread.task = last.result.task;
 						parentThread.sessionId = last.result.sessionId;
 						parentThread.sessionDir = last.result.sessionDir;
 						parentThread.state = isFailedResult(last.result) ? "failed" : "completed";
-						// The chain outcome settles the parent thread's trajectory: the
-						// last chain step is its final state.
-						const parentTrajectory = trajectoryStore.get(parentRunId);
-						parentTrajectory.trajectory.append({
-							kind: "settled",
-							status: parentThread.state === "failed" ? "failed" : "done",
-							model: last.result.model,
-						});
 						if (!runtime.sessionActive) {
 							clearOwnedController();
 							return;
@@ -642,7 +622,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						clearOwnedController();
 						removeChainGroup(parentGroupId);
 						if (controlledParent.state === "parked") {
-							monitor.setRetained(parentRunId, false);
 							monitor.setStatus(parentRunId, "parked");
 							return;
 						}
@@ -701,8 +680,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				worktree?: WorktreeIsolation;
 				forkedFromRunId?: number;
 				forkObjective?: string;
-				modelPool?: string[];
-				thinkingLevel?: SubagentThread["thinkingLevel"];
 			}
 
 			interface ResumeReservation {
@@ -758,12 +735,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const runCtx = environment?.ctx ?? ctx;
 				const runConfig = environment?.config ?? config;
 				const runAgents = environment?.agents ?? agents;
-				const runSessionRef = environment?.sessionRef ?? sessionRef;
 				const agent = runAgents.find((candidate) => candidate.name === agentName);
 				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 				if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
 					return {
-						...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to worker/write-capable agents.`),
+						...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as worker or cleaner.`),
 						isolation,
 					};
 				}
@@ -776,7 +752,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						return {
 							...failedStartResult(agentName, task, `Run #${existingThread?.id ?? "?"} has no active continuation worktree.`),
 							isolation,
-							originalCwd,
 							integrationStatus: worktree.state === "finalizing" ? "pending" : worktree.state,
 						};
 					}
@@ -787,65 +762,49 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							return {
 								...failedStartResult(agentName, task, error instanceof Error ? error.message : String(error)),
 								isolation,
-								originalCwd,
 							};
 						}
 					}
 				}
 				const executionCwd = worktree?.cwd ?? originalCwd;
-				const resolvedPool = resolveDispatchModelPool(agent, runConfig, runSessionRef, vision);
-				const inheritedPool = seed?.modelPool?.filter((ref) => ref.trim().length > 0) ?? [];
-				const rawPool = inheritedPool.length > 0
-					? {
-						agent: { ...agent, model: inheritedPool[0] },
-						fallbackModelRefs: inheritedPool.slice(1),
-					}
-					: resolvedPool;
+				const resolvedRoute = resolveDispatchModelRoute(agent, runConfig, runCtx, vision);
 				// Isolation is a persistent system-level invariant, not a one-shot task
-				// prefix: queued retargets, live retargets, resumes, and model fallbacks
-				// all keep the same worktree boundary.
-				const pool = isolation === "worktree"
-					? { ...rawPool, agent: withWorktreeSystemPrompt(rawPool.agent) }
-					: rawPool;
-				const thinkingLevel = seed?.thinkingLevel ?? runConfig.agentThinkingLevels[agent.name] ?? agent.thinking ?? runConfig.thinkingLevel;
-				const modelPool = [pool.agent.model, ...pool.fallbackModelRefs].filter((ref): ref is string => Boolean(ref));
+				// prefix: queued retargets, live retargets, resumes, and main-model
+				// handoffs all keep the same worktree boundary.
+				const route = isolation === "worktree"
+					? { ...resolvedRoute, agent: withWorktreeSystemPrompt(resolvedRoute.agent) }
+					: resolvedRoute;
+				const thinkingLevel = route.thinkingLevel;
 				const priorTask = existingThread?.task;
 				const priorSessionId = seed?.sessionId ?? existingThread?.sessionId;
 				const priorSessionDir = seed?.sessionDir ?? existingThread?.sessionDir;
 				if (existingThread && resumeReservation && !ownsResumeReservation(existingThread, resumeReservation)) {
 					return failedStartResult(agentName, task, `Run #${existingThread.id} changed while resume was preparing; no new generation was started.`);
 				}
-				const runId = existingThread?.id ?? monitor.addRun(agent.name, task, pool.agent.model, thinkingLevel, {
+				const runId = existingThread?.id ?? monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, {
 					isolation,
 					...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
 				});
 				const generation = (existingThread?.generation ?? 0) + 1;
 				const pending: SingleResult = {
-					...queuedResult(pool.agent, task, thinkingLevel),
+					...queuedResult(route.agent, task, thinkingLevel),
 					runId,
+					projectCwd: originalCwd,
 					isolation,
-					originalCwd,
-					isolationCwd: executionCwd,
 					...(isolation === "worktree" ? { integrationStatus: "pending" as const } : {}),
 					...(seed?.sessionId && seed.sessionDir
-						? { sessionId: seed.sessionId, sessionDir: seed.sessionDir, resumed: true }
+						? { sessionId: seed.sessionId, sessionDir: seed.sessionDir }
 						: {}),
 					...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
 				};
 				if (existingThread) {
-					monitor.restartRun(runId, agent.name, task, pool.agent.model, thinkingLevel, isolation);
+					monitor.restartRun(runId, agent.name, task, route.agent.model, thinkingLevel, isolation);
 					runtime.settledRuns.delete(runId);
 				}
 
 				let thread!: SubagentThread;
 				const control = new RpcRunControl(task, generation, (phase) => {
 					if (runtime.threads.get(runId)?.generation !== generation || phase === "settled") return;
-					// Orchestration transitions are part of the trajectory (retrying →
-					// retry event, park/stop → terminal control events).
-					const trajectory = trajectoryStore.get(runId).trajectory;
-					if (phase === "retrying") trajectory.append({ kind: "retry", reason: "retrying" });
-					else if (phase === "parked") trajectory.append({ kind: "park" });
-					else if (phase === "stopped") trajectory.append({ kind: "stop", reason: control.getStopMessage() });
 					const state: ThreadState =
 						phase === "queued" || phase === "starting"
 							? "queued"
@@ -866,45 +825,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					else if (state === "running") monitor.setStatus(runId, "running");
 				});
 
-				// Restart bumps the generation while preserving append-only history.
-				const trajectoryState = trajectoryStore.get(runId);
-				if (existingThread) {
-					trajectoryState.trajectory.restart();
-					trajectoryState.trajectory.append({
-						kind: "resume",
-						objective: newObjectiveOnResume ? task : undefined,
-					});
-				}
-				if (seed?.forkedFromRunId !== undefined) {
-					trajectoryState.trajectory.append({
-						kind: "fork",
-						sourceRunId: seed.forkedFromRunId,
-						childRunId: runId,
-						objective: seed.forkObjective,
-					});
-				}
-				trajectoryState.trajectory.append({
-					kind: "dispatch",
-					agent: agent.name,
-					task,
-					model: pool.agent.model,
-					thinking: thinkingLevel,
-					pool: pool.fallbackModelRefs,
-					vision,
-					resumed: existingThread !== undefined || seed !== undefined,
-					isolation,
-					originalCwd,
-					isolationCwd: executionCwd,
-				});
-				if (worktree && worktree !== previousWorktree) {
-					trajectoryState.trajectory.append({
-						kind: "worktree",
-						status: "created",
-						originalCwd,
-						isolationCwd: executionCwd,
-						worktreePath: worktree.worktreePath,
-					});
-				}
 
 				if (existingThread) {
 					thread = existingThread;
@@ -914,7 +834,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					thread.cwd = originalCwd;
 					thread.executionCwd = executionCwd;
 					thread.vision = vision;
-					thread.modelPool = modelPool;
 					thread.thinkingLevel = thinkingLevel;
 					thread.isolation = isolation;
 					thread.worktree = worktree;
@@ -939,7 +858,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						cwd: originalCwd,
 						executionCwd,
 						vision,
-						modelPool,
 						thinkingLevel,
 						isolation,
 						worktree,
@@ -963,7 +881,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				thread.notifyIsolationFailure = (finalization) => {
 					const paths = [finalization.worktreePath, finalization.patchPath].filter(Boolean).join(" · ");
 					runCtx.ui.notify(
-						`✗ worker worktree ${finalization.integrated ? "cleanup" : "integration"} failed${paths ? ` · retained ${paths}` : ""}: ${finalization.error ?? "unknown Git integration error"}`,
+						`✗ ${agent.name} worktree ${finalization.integrated ? "cleanup" : "integration"} failed${paths ? ` · retained ${paths}` : ""}: ${finalization.error ?? "unknown Git integration error"}`,
 						"error",
 					);
 				};
@@ -975,21 +893,9 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					if (thread.generation !== expectedGeneration) return undefined;
 					const finalization = await thread.worktree.finalize();
 					monitor.setIsolation(runId, "worktree", finalization.status);
-					trajectoryState.trajectory.append({
-						kind: "worktree",
-						status: finalization.status,
-						originalCwd: thread.cwd,
-						isolationCwd: thread.executionCwd,
-						worktreePath: finalization.worktreePath,
-						patchPath: finalization.patchPath,
-						integrated: finalization.integrated,
-						error: finalization.error,
-					});
 					if (result) {
 						result.runId = runId;
 						result.isolation = "worktree";
-						result.originalCwd = thread.cwd;
-						result.isolationCwd = thread.executionCwd;
 						result.integrationStatus = finalization.status;
 						result.integrationApplied = finalization.integrated;
 						result.integrationError = finalization.error;
@@ -1014,7 +920,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						}
 					}
 					if (finalization.status === "retained") {
-						runtime.retainWorktreeArtifacts(finalization);
 						if (!thread.isolationFailureNotified) {
 							thread.isolationFailureNotified = true;
 							try {
@@ -1048,13 +953,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const discardUnusedWorktree = async (candidate: WorktreeIsolation | undefined): Promise<void> => {
 					if (!candidate) return;
 					try {
-						if (candidate.discard) {
-							await candidate.discard();
-							return;
-						}
-						// Compatibility for externally supplied/test handles. Production handles
-						// expose discard(), so this fallback never integrates a seeded worktree.
-						if (candidate.state === "active") await candidate.finalize();
+						await candidate.discard();
 					} catch (error) {
 						const retainedPath = existsSync(candidate.worktreePath)
 							? candidate.worktreePath
@@ -1069,7 +968,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							...(existsSync(candidate.patchPath) ? { patchPath: candidate.patchPath } : {}),
 							error: `Discarding unused continuation failed: ${error instanceof Error ? error.message : String(error)}`,
 						};
-						runtime.retainWorktreeArtifacts(finalization);
 						await persistRecoveryRecords(runtime.configPath, [
 							recoveryRecordFromFinalization(runId, finalization),
 						]).catch(() => undefined);
@@ -1246,7 +1144,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 								ctx: currentCtx,
 								config: currentConfig,
 								agents: currentAgents,
-								sessionRef: currentModelRef(currentCtx),
 							},
 							seed,
 							reservation,
@@ -1409,7 +1306,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 								ctx: currentCtx,
 								config: currentConfig,
 								agents: currentAgents,
-								sessionRef: currentModelRef(currentCtx),
 							},
 							{
 								sessionId: forkedSession.sessionId,
@@ -1418,8 +1314,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 								worktree: childWorktree,
 								forkedFromRunId: runId,
 								forkObjective,
-								modelPool: [...thread.modelPool],
-								thinkingLevel: thread.thinkingLevel,
 							},
 						);
 						if (child.exitCode !== -1 || child.runId === undefined) {
@@ -1439,12 +1333,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						const childThread = runtime.threads.get(childRunId);
 						if (childThread) childThread.forkedFromRunId = runId;
 						monitor.setForkRelation(runId, childRunId);
-						trajectoryStore.get(runId).trajectory.append({
-							kind: "fork",
-							sourceRunId: runId,
-							childRunId,
-							objective: forkObjective,
-						});
 						const sourceResult = runtime.settledRuns.get(runId) ?? thread.lastResult;
 						if (sourceResult) sourceResult.forkChildRunIds = [...thread.forkChildRunIds];
 						return child;
@@ -1469,20 +1357,21 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					}
 				};
 
-				const onLive = makeLiveHandler(runId, runId, generation);
+				const onLive = makeLiveHandler(runId, generation);
 				const queueController = runtime.backgroundQueue.enqueue(
 					async (backgroundSignal) => {
 						if (runtime.threads.get(runId)?.generation !== generation) return;
 						let result: SingleResult;
 						try {
-							result = await runSingleAgentWithModelFallback(
+							result = await runSingleAgentWithMainFallback(
 								{
 									defaultCwd: executionCwd,
-									agent: pool.agent,
+									agent: route.agent,
 									agentName,
 									task,
 									cwd: executionCwd,
 									thinkingLevel,
+									thinkingLevelForModel: route.thinkingLevelForModel,
 									signal: backgroundSignal,
 									onLive,
 									control,
@@ -1494,11 +1383,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 											sessionDir: priorSessionDir,
 											stdinText: seed?.prompt ?? (newObjectiveOnResume
 												? task
-												: buildResumePrompt(priorTask ?? task, buildFallbackResumeReason())),
+												: buildResumePrompt(priorTask ?? task, "the retained thread was resumed")),
 										}
 										: {}),
 								},
-								pool.fallbackModelRefs,
+								route.mainFallbackRef,
 							);
 						} catch (error) {
 							const errorMessage = error instanceof Error ? error.message : String(error);
@@ -1517,9 +1406,8 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						// no monitor mutation, result registration, or completion delivery.
 						if (runtime.threads.get(runId)?.generation !== generation) return;
 						result.runId = runId;
+						result.projectCwd = originalCwd;
 						result.isolation = isolation;
-						result.originalCwd = originalCwd;
-						result.isolationCwd = executionCwd;
 						result.forkedFromRunId = thread.forkedFromRunId;
 						result.forkChildRunIds = [...thread.forkChildRunIds];
 						thread.queueController = undefined;
@@ -1530,6 +1418,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						thread.lastResult = result;
 						runtime.retainSession(result);
 						monitor.setModel(runId, result.model, result.modelFallbackFrom);
+						monitor.setThinking(runId, result.thinking);
 
 						// Destructive stop owns publication once it has synchronously claimed
 						// the lifecycle. Leave the partial result/session on the thread; the
@@ -1548,8 +1437,10 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						const wantsFixLoop = shouldTriggerFixLoop(result, runConfig);
 						if (wantsFixLoop && isolation === "shared" && runtime.sessionActive) {
 							thread.state = "running";
-							finishRun(runId, "done", { silent: true, retain: true });
-							monitor.setAnnotation(runId, "auto-fix chain running");
+							// The review being done does not mean the logical run is over:
+							// the same row now represents the chain until it resolves.
+							monitor.setStatus(runId, "running");
+							monitor.setActivity(runId, "auto-fix chain running");
 							startFixLoop(result, `fix-${runId}`, runId, thread.executionCwd, vision);
 							return;
 						}
@@ -1578,15 +1469,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							// Stamp the terminal monitor state before projecting it. This gives every
 							// path a fixed endedAt even when the row is removed immediately.
 							monitor.setStatus(runId, failed ? "failed" : "done");
-							trajectoryState.trajectory.append({
-								kind: "settled",
-								status: failed ? "failed" : "done",
-								model: result.model,
-								isolation,
-								...(result.integrationStatus && result.integrationStatus !== "pending"
-									? { integrationStatus: result.integrationStatus }
-									: {}),
-							});
 							if (!runtime.sessionActive || !ownsSettlement()) return;
 
 							const modelLevel = failed && isModelLevelFailure(result);
@@ -1596,8 +1478,8 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							const completion: CompletionMessageItem = {
 								agent: result.agent,
 								block: modelLevel
-									? `${formatCompletionBlock(result, runConfig.maxResultLines, runCtx.cwd)}\n\n${modelLevelTakeoverNote(result, { runId })}`
-									: formatCompletionBlock(result, runConfig.maxResultLines, runCtx.cwd),
+									? `${formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd)}\n\n${modelLevelTakeoverNote(result, { runId })}`
+									: formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd),
 								triggerTurn: completionTriggersTurn(result, runConfig.notifyOnReviewPass),
 							};
 							if (modelLevel) {
@@ -1618,8 +1500,8 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					() => {
 						if (runtime.threads.get(runId)?.generation !== generation) return;
 						// Queued park/stop owns publication and may still be finalizing an
-						// isolated worktree. Do not expose a terminal monitor/trajectory state
-						// before that owner records the checkpoint or aborted result.
+						// isolated worktree. Do not expose a terminal monitor state before
+						// that owner records the checkpoint or aborted result.
 						if (thread.lifecycleOperation === "park" || thread.lifecycleOperation === "stop") return;
 						runtime.runControllers.delete(runId);
 						thread.queueController = undefined;
@@ -1629,7 +1511,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						}
 						thread.state = "stopped";
 						monitor.setStatus(runId, "failed");
-						trajectoryState.trajectory.append({ kind: "settled", status: "stopped", model: monitor.findRun(runId)?.model, isolation });
 						if (!runtime.sessionActive) {
 							monitor.removeRun(runId);
 							return;
@@ -1652,26 +1533,15 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							!thread.retired;
 						try {
 							const crashed: SingleResult = {
-								...dispatchFailedResult(pool.agent, control.getObjective(), error, thinkingLevel),
+								...dispatchFailedResult(route.agent, control.getObjective(), error, thinkingLevel),
 								runId,
 								isolation,
-								originalCwd,
-								isolationCwd: executionCwd,
 								forkedFromRunId: thread.forkedFromRunId,
 							};
 							await thread.finalizeIsolation(generation, crashed);
 							if (!ownsSettlement()) return;
 							thread.state = "failed";
 							monitor.setStatus(runId, "failed");
-							trajectoryState.trajectory.append({
-								kind: "settled",
-								status: "failed",
-								model: crashed.model,
-								isolation,
-								...(crashed.integrationStatus && crashed.integrationStatus !== "pending"
-									? { integrationStatus: crashed.integrationStatus }
-									: {}),
-							});
 							finishRun(runId, "failed", { silent: true });
 							runtime.registerRunResult(runId, crashed);
 							runtime.runControllers.delete(runId);
@@ -1682,7 +1552,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 								runtime.sendCompletionGroup([
 									{
 										agent: agent.name,
-										block: formatCompletionBlock(crashed, runConfig.maxResultLines, runCtx.cwd),
+										block: formatCompletionBlock(crashed, runConfig.maxResultLines, crashed.projectCwd ?? originalCwd),
 										triggerTurn: true,
 									},
 								]);
@@ -1807,7 +1677,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const pending = r.exitCode === -1;
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
-				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (pool fallback from ${r.modelFallbackFrom})` : ""}`;
+				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (main after ${r.modelFallbackFrom} failed)` : ""}`;
 				const isolation = r.isolation === "worktree" ? ` · worktree ${r.integrationStatus ?? "active"}` : "";
 				const runId = r.runId === undefined ? "" : `${theme.fg("dim", `#${r.runId}`)} `;
 				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${runId}${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${isolation}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
@@ -1822,7 +1692,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				const pending = r.exitCode === -1;
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
-				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (pool fallback from ${r.modelFallbackFrom})` : ""}`;
+				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (main after ${r.modelFallbackFrom} failed)` : ""}`;
 				const isolation = r.isolation === "worktree" ? ` · worktree ${r.integrationStatus ?? "active"}` : "";
 				const runId = r.runId === undefined ? "" : `${theme.fg("dim", `#${r.runId}`)} `;
 				lines.push(`  ${icon} ${runId}${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${isolation}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);