@ferris1225/pi-subagents 4.1.13 → 4.1.16

package/src/format.ts

@@ -1,167 +1,179 @@
-/**
- * Pure formatting/result helpers shared by the subagent tool and the lookup
- * tools (subagent_wait/status): usage rendering, completion blocks, synthetic
- * result constructors, and run-id matching.
- */
-
-import type { AgentConfig } from "./agents.ts";
-import { formatTaskSummary } from "./monitor.ts";
-import { emptyUsage } from "./rpc-run.ts";
-import {
-	getResultOutput,
-	isFailedResult,
-	truncateResultOutput,
-	writeResultArtifact,
-	type SingleResult,
-	type UsageStats,
-} from "./spawn.ts";
-
-export function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
-	return {
-		agent: agent.name,
-		task,
-		exitCode: -1,
-		messages: [],
-		stderr: "",
-		usage: emptyUsage(),
-		model: agent.model,
-		...(thinking ? { thinking } : {}),
-	};
-}
-
-export function failedStartResult(agentName: string, task: string, errorMessage: string): SingleResult {
-	return {
-		agent: agentName,
-		task,
-		exitCode: 1,
-		messages: [],
-		stderr: errorMessage,
-		usage: emptyUsage(),
-		errorMessage,
-		dispatchFailed: true,
-	};
-}
-
-/** Failed result for a background task that crashed with an exception (spawn
- * infra, delivery API, ...) instead of returning a normal result. */
-export function dispatchFailedResult(agent: AgentConfig, task: string, error: unknown, thinking?: string): SingleResult {
-	const errorMessage = error instanceof Error ? error.message : String(error);
-	return {
-		...queuedResult(agent, task, thinking),
-		exitCode: 1,
-		stderr: errorMessage,
-		stopReason: "error",
-		errorMessage,
-		dispatchFailed: true,
-	};
-}
-
-function formatTokens(count: number): string {
-	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
-	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
-	return String(count);
-}
-
-export function formatUsage(usage: UsageStats): string {
-	const parts: string[] = [];
-	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
-	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
-	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
-	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
-	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
-	return parts.join(" ");
-}
-
-export interface CompletionFormatOptions {
-	/** Include individual failed-tool errors. Reserved for explicit status lookup. */
-	failedToolDetails?: boolean;
-}
-
-export function formatCompletionBlock(
-	result: SingleResult,
-	maxResultLines: number,
-	cwd?: string,
-	options: CompletionFormatOptions = {},
-): string {
-	const failed = isFailedResult(result);
-	const failedTools = result.failedTools ?? [];
-	const status = failed
-		? "failed"
-		: options.failedToolDetails && failedTools.length > 0
-			? `completed with ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}`
-			: "completed";
-	const usage = formatUsage(result.usage);
-	const output = getResultOutput(result);
-	const { text, truncated } = truncateResultOutput(output, maxResultLines);
-	const fallbackNote = result.modelFallbackFrom
-		? ` (selected model ${result.modelFallbackFrom} failed → main ${result.model ?? "dynamic default"})`
-		: "";
-	const startupRetryNote = result.startupRetries
-		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
-		: "";
-	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
-	if (result.isolation === "worktree") {
-		const isolation =
-			result.integrationStatus === "integrated"
-				? "worktree · changes integrated into the original working tree"
-				: result.integrationStatus === "no_changes"
-					? "worktree · no changes; temporary worktree removed"
-					: result.integrationStatus === "retained"
-						? result.integrationApplied
-							? "worktree · changes applied, but cleanup failed; recovery artifacts retained"
-							: "worktree · integration failed; recovery artifacts retained"
-						: "worktree · isolated";
-		lines.push(`Isolation: ${isolation}`);
-		if (result.integrationWorktreePath) lines.push(`Retained worktree: ${result.integrationWorktreePath}`);
-		if (result.integrationPatchPath) lines.push(`Retained patch: ${result.integrationPatchPath}`);
-		if (result.integrationError) lines.push(`Integration error: ${result.integrationError}`);
-		lines.push("");
-	}
-	lines.push(text);
-	// Failed-tool diagnostics are deliberate opt-in via subagent_status: agents
-	// report their own verification in the output above, and a transient failed
-	// call (no-match grep, rejected edit) is noise in an automatic delivery.
-	if (options.failedToolDetails && failedTools.length > 0) {
-		lines.push(
-			"",
-			`⚠ ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}:`,
-			...failedTools.map((tool) => `- ${tool.toolName}: ${tool.error.trim() || "(no output)"}`),
-		);
-	}
-	if (truncated) {
-		// The full text lives on disk so the main agent can read it on demand.
-		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent, result.projectCwd ?? cwd)})`);
-	}
-	return lines.join("\n");
-}
-
-/** Instruction appended to a model-level failure: the sub-agent's provider never
- * produced usable output (or the run stalled), so the task is handed back to the
- * main window instead of being left as a dead failure. When the run preserved a
- * session with earlier work (and the run id is known), steer the main agent to
- * RESUME it in-context once a model is available, instead of re-dispatching
- * fresh (which would re-scan everything). */
-export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: number }): string {
-	const retry = result.modelFallbackFrom ? ", and the current main model also failed" : "";
-	const detail = result.errorMessage?.trim();
-	const cause = detail
-		? `its model/provider call failed (${detail})`
-		: "its model was unavailable or failed (or the run stalled)";
-	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
-	const recovery = sessionPreserved
-		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
-		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
-	return `The sub-agent could not complete this task: ${cause}${retry}.${recovery}`;
-}
-
-/** Resolve a run-id request to actual ids: an exact numeric match always wins
- * (so "1" never fans out to 10, 11, …); only when no exact match exists does a
- * prefix match run, as a convenience for partial ids. Keeps single-digit lookups
- * from returning — or, for subagent_stop, acting on — a whole prefix family. */
-export function matchRunIds(ids: number[], requested: string): number[] {
-	const exact = ids.filter((id) => String(id) === requested);
-	if (exact.length > 0) return exact;
-	return ids.filter((id) => String(id).startsWith(requested));
-}
+/**
+ * Pure formatting/result helpers shared by the subagent tool and the lookup
+ * tools (subagent_wait/status): usage rendering, completion blocks, synthetic
+ * result constructors, and run-id matching.
+ */
+
+import type { AgentConfig } from "./agents.ts";
+import { formatTaskSummary } from "./monitor.ts";
+import { emptyUsage } from "./rpc-run.ts";
+import {
+	getResultOutput,
+	isFailedResult,
+	truncateResultOutput,
+	writeResultArtifact,
+	type SingleResult,
+	type UsageStats,
+} from "./spawn.ts";
+
+export function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
+	return {
+		agent: agent.name,
+		task,
+		exitCode: -1,
+		messages: [],
+		stderr: "",
+		usage: emptyUsage(),
+		model: agent.model,
+		...(thinking ? { thinking } : {}),
+	};
+}
+
+export function failedStartResult(agentName: string, task: string, errorMessage: string): SingleResult {
+	return {
+		agent: agentName,
+		task,
+		exitCode: 1,
+		messages: [],
+		stderr: errorMessage,
+		usage: emptyUsage(),
+		errorMessage,
+		dispatchFailed: true,
+	};
+}
+
+/** Failed result for a background task that crashed with an exception (spawn
+ * infra, delivery API, ...) instead of returning a normal result. */
+export function dispatchFailedResult(agent: AgentConfig, task: string, error: unknown, thinking?: string): SingleResult {
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	return {
+		...queuedResult(agent, task, thinking),
+		exitCode: 1,
+		stderr: errorMessage,
+		stopReason: "error",
+		errorMessage,
+		dispatchFailed: true,
+	};
+}
+
+function formatTokens(count: number): string {
+	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+	return String(count);
+}
+
+export function formatUsage(usage: UsageStats): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	return parts.join(" ");
+}
+
+export interface CompletionFormatOptions {
+	/** Include individual failed-tool errors. Reserved for explicit status lookup. */
+	failedToolDetails?: boolean;
+	/** Project-scoped directory the full result is written to when the output
+	 * is truncated: <projectRoot>/results. */
+	resultRoot?: string;
+}
+
+export function formatCompletionBlock(
+	result: SingleResult,
+	maxResultLines: number,
+	options: CompletionFormatOptions = {},
+): string {
+	const failed = isFailedResult(result);
+	const failedTools = result.failedTools ?? [];
+	const status = failed
+		? "failed"
+		: options.failedToolDetails && failedTools.length > 0
+			? `completed with ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}`
+			: "completed";
+	const usage = formatUsage(result.usage);
+	const output = getResultOutput(result);
+	const { text, truncated } = truncateResultOutput(output, maxResultLines);const fallbackNote = result.modelFallbackFrom
+		? ` (selected model ${result.modelFallbackFrom} failed → main ${result.model ?? "dynamic default"})`
+		: "";
+	const startupRetryNote = result.startupRetries
+		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
+		: "";
+	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
+	if (result.isolation === "worktree") {
+		const isolation =
+			result.integrationStatus === "integrated"
+				? "worktree · changes integrated into the original working tree"
+				: result.integrationStatus === "no_changes"
+					? "worktree · no changes; temporary worktree removed"
+					: result.integrationStatus === "retained"
+						? result.integrationApplied
+							? "worktree · changes applied, but cleanup failed; recovery artifacts retained"
+							: "worktree · integration failed; recovery artifacts retained"
+						: "worktree · isolated";
+		lines.push(`Isolation: ${isolation}`);
+		if (result.integrationWorktreePath) lines.push(`Retained worktree: ${result.integrationWorktreePath}`);
+		if (result.integrationPatchPath) lines.push(`Retained patch: ${result.integrationPatchPath}`);
+		if (result.integrationError) lines.push(`Integration error: ${result.integrationError}`);
+		lines.push("");
+	}
+	lines.push(text);
+	// Failed-tool diagnostics are deliberate opt-in via subagent_status: agents
+	// report their own verification in the output above, and a transient failed
+	// call (no-match grep, rejected edit) is noise in an automatic delivery.
+	if (options.failedToolDetails && failedTools.length > 0) {
+		lines.push(
+			"",
+			`⚠ ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}:`,
+			...failedTools.map((tool) => `- ${tool.toolName}: ${tool.error.trim() || "(no output)"}`),
+		);
+	}
+	if (truncated) {
+		// The full text lives on disk so the main agent can read it on demand.
+		const artifact = options.resultRoot
+			? writeResultArtifact(output, result.agent, options.resultRoot)
+			: "(result root unavailable)";
+		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${artifact})`);
+	}
+	return lines.join("\n");
+}
+
+/** Instruction appended to a model-level failure: the sub-agent's provider never
+ * produced usable output (or the run stalled), so the task is handed back to the
+ * main window instead of being left as a dead failure. When the run preserved a
+ * session with earlier work (and the run id is known), steer the main agent to
+ * RESUME it in-context once a model is available, instead of re-dispatching
+ * fresh (which would re-scan everything). */
+export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: number }): string {
+	const retry = result.modelFallbackFrom ? ", and the current main model also failed" : "";
+	const detail = result.errorMessage?.trim();
+	const cause = detail
+		? `its model/provider call failed (${detail})`
+		: "its model was unavailable or failed (or the run stalled)";
+	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
+	const recovery = sessionPreserved
+		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
+		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
+	return `The sub-agent could not complete this task: ${cause}${retry}.${recovery}`;
+}
+
+/** Instruction appended whenever a failing gate verdict is delivered: the
+ * findings return to the main agent, which owns the fix decision — the runtime
+ * never auto-fixes. Stating it at this exact decision point keeps the main
+ * agent from relaying the findings to the user and stopping. */
+export function reviewFailFollowUpNote(): string {
+	return "This gate failed and the findings are yours to resolve now: fix them inline or dispatch a worker briefed with these fix instructions, then re-verify the change. Ask the user only before a genuinely destructive or scope-changing fix; do not deliver while a finding stands.";
+}
+
+/** Resolve a run-id request to actual ids: an exact numeric match always wins
+ * (so "1" never fans out to 10, 11, …); only when no exact match exists does a
+ * prefix match run, as a convenience for partial ids. Keeps single-digit lookups
+ * from returning — or, for subagent_stop, acting on — a whole prefix family. */
+export function matchRunIds(ids: number[], requested: string): number[] {
+	const exact = ids.filter((id) => String(id) === requested);
+	if (exact.length > 0) return exact;
+	return ids.filter((id) => String(id).startsWith(requested));
+}

package/src/monitor.ts

@@ -759,11 +759,13 @@ export function statusIcon(status: RunStatus, theme: Theme): string {
 	}
 }
 
-/** User-facing status label used by tool/status rendering. */
+/** User-facing status label used by tool/status rendering. Queued runs say
+ * so: anything vaguer ("ready") reads like an unexplained cap and made models
+ * stop dispatching while slots were merely pacing. */
 export function statusLabel(status: RunStatus): string {
 	switch (status) {
 		case "queued":
-			return "ready";
+			return "queued";
 		case "running":
 			return "running";
 		case "interrupting":

package/src/prompt.ts

@@ -40,53 +40,40 @@ export function buildDelegationDirective(
 			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
 
 	const dispatchRules = [
-		"Route substantive work to sub-agents so your context stays lean for orchestration; inline only trivial work — a one-shot lookup, a single focused read/edit, or an answer already in context.",
+		`Delegate aggressively: child contexts are cheap, yours is scarce. Inline only trivial work — a one-shot lookup, a single focused edit, an answer already in context${hasWorker ? "; default every non-trivial implementation, fix, refactor, or test task to `worker`" : ""}.`,
 		...(hasExplorer
 			? [
-				"Use `explorer` for any broad or multi-file search; it is a retrieval index, never a gate — its findings are leads, not proof. Before acting on them yourself — editing inline, deleting, or deciding something load-bearing — re-read the files involved; a child you brief re-verifies them in its own context.",
+				"`explorer`: broad or multi-file search. Its findings are leads, never proof — re-read load-bearing files before acting yourself (a child you brief re-verifies). Split a broad question into several parallel explorers with disjoint scopes.",
 			]
 			: []),
-		...(hasWorker
-			? ["Use `worker` for a self-contained implementation, fix, refactor, or test whose separate context pays for itself."]
-			: []),
 		...(hasCleaner
-			? [
-				`Use \`cleaner\` only for user-authorized cleanup or deduplication; it applies every safe proven cut without item-by-item approval, and never runs as a pre-commit gate or by PR count.`,
-			]
+			? ["`cleaner`: only user-authorized cleanup or dedup; it applies every safe proven cut without per-item approval and is never a gate."]
 			: []),
 		...(hasDocumenter
-			? [
-				`Use \`documenter\` directly only for explicit standalone documentation work; a top-level documenter delivers without a gate.${codeWriterNames.length > 0 ? ` The runtime runs the final docs sync after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback; writers sync docs they directly affect — never dispatch a duplicate.` : ""}`,
-			]
+			? ["`documenter`: standalone docs/comment work, or syncing real drift a change left — writers already sync what they directly affect."]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for read-only assessments or gates.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already get one fresh gate and then deliver once.` : ""} Advisory output has no VERDICT and cannot authorize edits; dispatch your own re-verification with \`advisory: true\`.`,
+				`\`reviewer\`: read-only assessments and gates${codeWriterNames.length > 0 ? `; successful ${codeWriterNames.join("/")} runs get one fresh gate, and failing gates are fixed by the reviewer itself in bounded fix/re-review rounds that converge on the fixes (a still-failing gate returns to you)` : ""}. Advisory output has no VERDICT and cannot authorize edits.`,
 			]
 			: []),
-		"You own the fan-out breadth: every genuinely independent unit goes in one `tasks` array — there is no per-call cap, and extra tasks queue for the next free process slot. One child owns one coherent deliverable and its files; no two children share a file or re-answer the same question; dependent work starts only after its prerequisite delivers.",
-		"Brief each child with the complete goal, exact paths, constraints, and expected output; it has no conversation memory and cannot delegate. Continue a parked/settled thread with `subagent_control resume`.",
-		`Single tasks share the checkout${hasWorker ? "; parallel workers default to detached Git worktrees" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repo with committed HEAD; setup failure never silently falls back to shared.`,
-		"A configured child model/provider failure automatically continues the same retained session on the current main model; do not redispatch. Ordinary tool/task failures stay on the selected model.",
+		`Parallelize by default: map the todo list onto ONE \`tasks\` dispatch. One child owns one deliverable and its files; only genuinely dependent work waits for its prerequisite.`,
+		"Brief each child completely — goal, exact paths, constraints, expected output; it has no conversation memory and cannot delegate. Resume parked threads with `subagent_control resume`.",
+		`Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a repo with committed HEAD.`,
 	];
 
 	const handoffRules = [
-		"Dispatch ends this turn; each completion resumes the main agent automatically — never sleep, poll, or call `subagent_wait` to hold the turn.",
+		"Dispatch never blocks or ends your turn — keep working; each completion resumes you automatically. Never sleep, poll, or `subagent_wait` to hold the turn.",
 		"Results are already shown; add only your conclusion or next action, never a restatement.",
-		"Before declaring the overall task done, use `subagent_status` to confirm that no runs remain active.",
+		"Before declaring the overall task done, `subagent_status` must show no active runs.",
 	];
 
 	const verificationRules = [
-		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures honestly, and inspect actual changes before reporting completion.",
+		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures, and inspect actual changes before reporting completion.",
 		...(hasReviewer
 			? [
-				...(hasDocumenter
-					? [
-						"A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync.",
-					]
-					: []),
-				"A REVIEW_FAIL — direct or from a managed gate — returns the findings to you: resolve them yourself, inline or via a worker you brief, without waiting for the user; the runtime never auto-fixes. Ask only for genuinely destructive or scope-changing fixes. Advisory reports cannot trigger writes.",
-				"Use multi-model cross-review only when explicitly requested or for genuinely high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
+				"A REVIEW_FAIL from a gate you dispatched directly returns its findings to you: fix them inline or via a briefed worker without waiting for the user (ask only for genuinely destructive or scope-changing fixes), then re-verify ONCE. If the gate still fails, report the remaining findings and move on — never loop gate dispatches.",
+				"Multi-model cross-review only when explicitly requested or for high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
 			]
 			: []),
 		"Commit or push only when explicitly requested, applicable checks pass, and no review finding remains unresolved.",
@@ -95,7 +82,7 @@ export function buildDelegationDirective(
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-The \`subagent\` tool runs isolated leaf Pi child processes and context windows; each completion automatically resumes the main agent.
+\`subagent\` runs isolated leaf Pi child processes in the background; each completion resumes you.
 
 Agents:
 ${catalog}

package/src/runtime.ts

@@ -10,7 +10,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { rmSync } from "node:fs";
-import { BackgroundTaskQueue, MAX_CONCURRENT_SUBAGENTS } from "./background.ts";
+import { resolveSubagentConcurrency, BackgroundTaskQueue } from "./background.ts";
 import {
 	completionGroupTriggersTurn,
 	createCompletionBatcher,
@@ -20,7 +20,7 @@ import {
 	type CompletionMessageItem,
 } from "./completion.ts";
 import { type ThinkingLevel } from "./config.ts";
-import { threadRecordFromThread, upsertThreadRecord, type ThreadRecord } from "./durable.ts";
+import { removeThreadRecord, threadRecordFromThread, upsertThreadRecord, type ThreadRecord } from "./durable.ts";
 import { isRunActiveStatus, monitor } from "./monitor.ts";
 import type { RpcRunControl } from "./rpc-run.ts";
 import type { StartBackgroundInternal } from "./thread-lifecycle.ts";
@@ -50,8 +50,6 @@ export interface SubagentThread {
 	executionCwd: string;
 	thinkingLevel?: ThinkingLevel;
 	isolation: IsolationMode;
-	/** Report-only reviewer dispatch: verdicts never chain into a managed workflow. */
-	advisoryReview: boolean;
 	worktree?: WorktreeIsolation;
 	state: ThreadState;
 	control: RpcRunControl;
@@ -122,7 +120,7 @@ export interface SubagentRuntime {
 }
 
 export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRuntime {
-	const backgroundQueue = new BackgroundTaskQueue(MAX_CONCURRENT_SUBAGENTS);
+	const backgroundQueue = new BackgroundTaskQueue(resolveSubagentConcurrency());
 
 	const runtime: SubagentRuntime = {
 		configPath,
@@ -142,7 +140,7 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 			const active = monitor
 				.getRuns()
 				.filter((run) => isRunActiveStatus(run.status))
-				.map((run) => ({ id: run.id, agent: run.agent, label: run.label }));
+				.map((run) => ({ id: run.id, agent: run.agent, label: run.label, queued: run.status === "queued" }));
 			const message = {
 				customType: "subagent-result",
 				content: formatCompletionMessage(items) + formatActiveRunsFooter(active),
@@ -242,10 +240,14 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 				Promise.allSettled(preflights),
 				runtime.backgroundQueue.waitForIdle(),
 			]);
-			// Persist one record per non-retired thread, then keep exactly the
-			// artifacts those records reference. A thread whose settlement finished
-			// during the wait above already wrote its own terminal record; the
-			// lastResult-derived state below matches it.
+			// Only interrupted (parked) threads stay resumable across reloads:
+			// each keeps its durable record and retained artifacts. Settled
+			// threads drop their record — the manifest exists only while
+			// unfinished work needs it — and their sessions are deleted now. A
+			// thread whose settlement finished during the wait above already
+			// wrote (or removed) its own record; the lastResult-derived state
+			// below matches it.
+			const settledIds: number[] = [];
 			const records: ThreadRecord[] = [];
 			for (const thread of runtime.threads.values()) {
 				if (thread.retired) continue;
@@ -258,11 +260,13 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 				} else {
 					state = "parked";
 				}
-				records.push(threadRecordFromThread(thread, state));
+				if (state === "parked") records.push(threadRecordFromThread(thread, state));
+				else settledIds.push(thread.id);
 			}
-			await Promise.all(
-				records.map((record) => upsertThreadRecord(runtime.configPath, record).catch(() => undefined)),
-			);
+			await Promise.all([
+				...records.map((record) => upsertThreadRecord(runtime.configPath, record).catch(() => undefined)),
+				...settledIds.map((runId) => removeThreadRecord(runtime.configPath, runId).catch(() => undefined)),
+			]);
 			// Retained-failure recovery records are persisted by the finalization
 			// itself; shutdown only drops sessions no record claims anymore.
 			const referenced = new Set(

package/src/setup.ts

@@ -307,9 +307,9 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 					next.agentThinkingLevels.cleaner = config.agentThinkingLevels.reviewer;
 				}
 			}
-			// Documenter intentionally follows the faster explorer route. Fresh
-			// installs leave it unselected; enabling it later inherits any explorer
-			// overrides instead of silently choosing a stronger model.
+			// Documenter intentionally follows the faster explorer route. When it
+			// is re-enabled after being explicitly disabled, it inherits any
+			// explorer overrides instead of silently choosing a stronger model.
 			if (!config.enabledAgents.includes("documenter") && enabled.includes("documenter")) {
 				if (!next.agentModels.documenter && config.agentModels.explorer) {
 					next.agentModels.documenter = config.agentModels.explorer;