@ferris1225/pi-subagents 4.1.6 → 4.1.8

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
@@ -204,10 +207,10 @@ subagent({
 });
 ```
 
-Independent tasks run up to `maxConcurrency` (default `4`). One parallel call may
-contain at most that many tasks and is rejected if it exceeds the limit. Accepted
-background work from separate calls waits in the shared queue when all slots are
-busy.
+Independent tasks run up to a fixed limit of `4` concurrent sub-agent processes.
+One parallel call may contain at most that many tasks and is rejected if it
+exceeds the limit. Accepted background work from separate calls waits in the
+shared queue when all slots are busy.
 
 ### Run an independent quality gate
 
@@ -225,20 +228,26 @@ 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.
 
-`maxFixRounds` limits worker fix attempts only. The post-writer review gate still
-runs when it is `0`, and only a terminal `REVIEW_PASS` can decide whether docs
+The loop is fixed at two worker fix rounds (each fix is re-reviewed); disabling
+the `worker` agent is the way to turn fixes off. The post-writer review gate still
+runs regardless, and only a terminal `REVIEW_PASS` can decide whether docs
 sync is needed. Generic audits and read-only reviews are advisory: they omit
 `VERDICT` and documentation machine markers, remain read-only, and never trigger
 edits.
@@ -495,8 +504,8 @@ subagent({
 
 ## Configuration
 
-The wizard covers enabled agents, per-agent models and thinking, concurrency,
-auto-fix rounds, and the idle timeout:
+The wizard covers enabled agents, per-agent models and thinking, and the idle
+timeout:
 
 ```text
 /subagents-setup
@@ -526,8 +535,6 @@ Configuration is stored at `~/.pi/agent/pi-subagents.json` and follows
   "maxResultLines": 80,
   "proactiveInjection": true,
   "agentScope": "user",
-  "maxConcurrency": 4,
-  "maxFixRounds": 2,
   "idleTimeoutSec": 90
 }
 ```
@@ -541,16 +548,15 @@ Configuration is stored at `~/.pi/agent/pi-subagents.json` and follows
 | `maxResultLines` | Lines kept in a completion message before the full result moves to a temporary artifact. Default `80`. |
 | `proactiveInjection` | Teach the main model when and how to delegate. Default `true`. |
 | `agentScope` | Discover `user`, `project`, or `both` agent directories. Default `user`. |
-| `maxConcurrency` | Running process limit and maximum tasks in one parallel call, from `1` to `16`. Default `4`. |
-| `maxFixRounds` | Maximum worker fixes after `REVIEW_FAIL`; each fix is re-reviewed. After terminal `REVIEW_PASS`, docs sync runs only for `DOCUMENTATION: NEEDED` or a missing marker. `0` disables fixes but not the post-writer gate or conditional/reviewer-disabled docs behavior. Default `2`. |
 | `idleTimeoutSec` | Seconds without RPC output before termination. `0` disables the watchdog. Default `90`. |
 
-Invalid values fall back safely. Older configs are normalized automatically. The
-former built-in name `explore` migrates to `explorer`, and pre-cleaner non-empty
-agent lists receive `cleaner` once. Existing non-empty configs also receive
-`documenter` once, inserted before `reviewer`, with any configured `explorer`
-model and thinking copied across. Fresh installs do not enable `documenter`
-until the user selects it. Later deliberate disables are respected.
+Invalid values fall back safely. Keys from older versions (including the former
+`maxConcurrency` and `maxFixRounds` tuning options, now fixed at `4` concurrent
+processes and `2` fix rounds) are dropped automatically and the normalized
+shape is saved back. At session start, per-agent model overrides that Pi no
+longer reports as available are removed with a one-time notice; those agents
+fall back to the current main model until you re-pick them in
+`/subagents-setup`.
 
 ## Custom and overridden agents
 

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.6",
+  "version": "4.1.8",
   "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/announcements.ts

@@ -1,82 +1,37 @@
-/** Session-start recovery and one-time feature announcements. */
+/** Session-start recovery, stale-config migration, and widget installation. */
 
-import { stat } from "node:fs/promises";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-	CLEANER_AUTO_ENABLED_FEATURE,
-	CLEANER_INHERITED_FEATURE,
-	DOCUMENTER_AUTO_ENABLED_FEATURE,
-	DOCUMENTER_INHERITED_FEATURE,
-	loadConfig,
-	saveConfig,
-} from "./config.ts";
+import { loadConfig, saveConfig } from "./config.ts";
+import { availableModelsInScope, filterUnavailableModelOverrides } from "./models.ts";
 import { announceRecoveryRecords } from "./recovery.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import { pruneResultArtifacts } from "./spawn.ts";
 import { installActiveRunsWidget } from "./widget.ts";
 
-const ANNOUNCEMENTS: Array<{
-	key: string;
-	condition: (config: Awaited<ReturnType<typeof loadConfig>>) => boolean;
-	message: (config: Awaited<ReturnType<typeof loadConfig>>) => string;
-}> = [
-	{
-		// Fires once after the load-time upgrade injected cleaner into an older
-		// config (the injection stamp only exists in that case). The extra
-		// enabledAgents check keeps the notice silent when the user already
-		// disabled cleaner (e.g. via full setup) before it could fire.
-		key: "cleanerAutoEnabledNotice",
-		condition: (config) =>
-			config.announcedFeatures.includes(CLEANER_AUTO_ENABLED_FEATURE) &&
-			config.enabledAgents.includes("cleaner"),
-		// The inheritance clause matches reality: its stamp is only set when the
-		// upgrade actually copied reviewer model/thinking settings.
-		message: (config) =>
-			config.announcedFeatures.includes(CLEANER_INHERITED_FEATURE)
-				? "pi-subagents: the built-in cleaner agent was enabled by default and inherited your reviewer model/thinking settings. Run /subagents-setup to adjust or disable it."
-				: "pi-subagents: the built-in cleaner agent was enabled by default. Run /subagents-setup to adjust or disable it.",
-	},
-	{
-		key: "documenterAutoEnabledNotice",
-		condition: (config) =>
-			config.announcedFeatures.includes(DOCUMENTER_AUTO_ENABLED_FEATURE) &&
-			config.enabledAgents.includes("documenter"),
-		message: (config) =>
-			config.announcedFeatures.includes(DOCUMENTER_INHERITED_FEATURE)
-				? "pi-subagents: the new documenter agent was enabled for your existing config and inherited your explorer model/thinking settings. It synchronizes comments and README/docs before commit; run /subagents-setup to adjust or disable it."
-				: "pi-subagents: the new documenter agent was enabled for your existing config. It synchronizes comments and README/docs before commit; run /subagents-setup to adjust or disable it.",
-	},
-];
-
-async function announceNewFeatures(
-	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } },
+/**
+ * One-time-per-stale-override migration: keep agent model selections Pi still
+ * reports as available, drop the rest back to dynamic main-model routing, and
+ * tell the user what was removed. Saving the cleaned config is what makes it
+ * one-time — the dropped refs no longer exist to re-trigger the notice.
+ */
+async function migrateUnavailableAgentModels(
+	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } } & Parameters<typeof availableModelsInScope>[0],
 	runtime: SubagentRuntime,
 ): Promise<void> {
 	try {
-		let configExists = true;
-		try {
-			await stat(runtime.configPath);
-		} catch {
-			configExists = false;
-		}
-		if (!configExists) return;
-
 		const config = await loadConfig(runtime.configPath);
-		const pending = ANNOUNCEMENTS.filter(
-			(announcement) =>
-				announcement.condition(config) && !config.announcedFeatures.includes(announcement.key),
-		);
-		if (pending.length === 0) return;
-		await saveConfig(
-			{
-				...config,
-				announcedFeatures: [...config.announcedFeatures, ...pending.map((announcement) => announcement.key)],
-			},
-			runtime.configPath,
+		const overrides = Object.entries(config.agentModels);
+		if (overrides.length === 0) return;
+		const { kept, dropped } = filterUnavailableModelOverrides(config.agentModels, availableModelsInScope(ctx));
+		if (dropped.length === 0) return;
+		await saveConfig({ ...config, agentModels: kept }, runtime.configPath);
+		const list = dropped.map(({ agent, ref }) => `${agent}: ${ref}`).join(", ");
+		ctx.ui.notify(
+			`pi-subagents: removed stale agent model overrides that are no longer available (${list}). Those agents now follow the current main model; run /subagents-setup to re-pick.`,
+			"warning",
 		);
-		for (const announcement of pending) ctx.ui.notify(announcement.message(config), "info");
 	} catch {
-		/* announcement failures are non-fatal */
+		/* migration failures are non-fatal */
 	}
 }
 
@@ -84,8 +39,8 @@ export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime
 	pi.on("session_start", async (_event, ctx) => {
 		pruneResultArtifacts();
 		await announceRecoveryRecords(runtime.configPath, ctx);
+		await migrateUnavailableAgentModels(ctx, runtime);
 		if (ctx.mode !== "tui") return;
 		installActiveRunsWidget(ctx);
-		await announceNewFeatures(ctx, runtime);
 	});
 }

package/src/background.ts

@@ -27,6 +27,11 @@ interface PendingTask {
 	onError?: (error: unknown) => void | Promise<void>;
 }
 
+/** How many sub-agent processes may run at once, and how many tasks one
+ * parallel `subagent` call may contain. Fixed by design: the queue sheds load
+ * by waiting, so the knob bought nothing worth its maintenance. */
+export const MAX_CONCURRENT_SUBAGENTS = 4;
+
 export class BackgroundTaskQueue {
 	private concurrency: number;
 	private readonly pending: PendingTask[] = [];
@@ -39,16 +44,6 @@ export class BackgroundTaskQueue {
 		this.concurrency = Math.max(1, concurrency);
 	}
 
-	/**
-	 * Update the concurrency limit (e.g. after a config change). Raising it
-	 * immediately starts more queued work; lowering it takes effect as running
-	 * tasks finish — already-running tasks are never interrupted.
-	 */
-	setConcurrency(concurrency: number): void {
-		this.concurrency = Math.max(1, concurrency);
-		this.drain();
-	}
-
 	enqueue(task: BackgroundTask, onCancelled?: () => void, onError?: (error: unknown) => void | Promise<void>): AbortController {
 		const controller = new AbortController();
 		let complete!: () => void;

package/src/config.ts

@@ -4,57 +4,23 @@
  * Config lives at <agentDir>/pi-subagents.json (agentDir defaults to ~/.pi/agent
  * and honors PI_CODING_AGENT_DIR). Parsing is defensive: invalid fields fall back
  * to defaults instead of throwing, so a hand-edited or partially-written file can
- * never break the extension at runtime.
- *
- * Schema upgrades happen transparently on load: a config written by an older
- * version (missing newer keys or containing invalid
- * values) is normalized and persisted back with the new fields filled in.
+ * never break the extension at runtime. Unknown keys from older versions are
+ * dropped and the normalized shape persisted back on load.
  */
 
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
 export const BUILTIN_AGENT_NAMES = ["explorer", "worker", "cleaner", "documenter", "reviewer"] as const;
 
-/** Agents enabled out of the box on a fresh install. Documenter remains an
- * explicit setup choice; existing non-empty configs receive it via migration. */
+/** Agents enabled out of the box on a fresh install. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explorer", "worker", "cleaner", "reviewer"];
 
 export const AGENT_SCOPE_VALUES = ["user", "project", "both"] as const;
 export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 
-const LEGACY_EXPLORER_NAME = "explore";
-const EXPLORER_NAME = "explorer";
-const CLEANER_NAME = "cleaner";
-const DOCUMENTER_NAME = "documenter";
-const REVIEWER_NAME = "reviewer";
-
-/**
- * Stamps recorded in `announcedFeatures` by the one-time upgrade that defaults
- * cleaner on for configs written before it shipped. The first marks a config as
- * processed, so a later deliberate disable is not undone; the second records
- * that cleaner was actually injected, so session start can tell the user once;
- * the third records that reviewer model/thinking settings were actually copied,
- * so that notice never claims an inheritance that did not happen.
- */
-export const CLEANER_DEFAULTED_FEATURE = "cleanerDefaulted";
-export const CLEANER_AUTO_ENABLED_FEATURE = "cleanerAutoEnabled";
-export const CLEANER_INHERITED_FEATURE = "cleanerInheritedReviewer";
-
-/** One-time upgrade stamps for the pre-commit documenter role. Existing
- * non-empty configs gain it before reviewer and inherit explorer routing; fresh
- * installs keep it off until setup explicitly enables it. */
-export const DOCUMENTER_DEFAULTED_FEATURE = "documenterDefaulted";
-export const DOCUMENTER_AUTO_ENABLED_FEATURE = "documenterAutoEnabled";
-export const DOCUMENTER_INHERITED_FEATURE = "documenterInheritedExplorer";
-
-function migrateAgentName(name: string): string {
-	return name === LEGACY_EXPLORER_NAME ? EXPLORER_NAME : name;
-}
-
 /** Thinking levels accepted by pi's `--thinking` option. */
 export const THINKING_LEVEL_VALUES = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevel = (typeof THINKING_LEVEL_VALUES)[number];
@@ -67,20 +33,6 @@ export const MAX_RESULT_LINES_LIMIT = 2000;
 
 const CONFIG_FILE_NAME = "pi-subagents.json";
 
-/** How many sub-agent processes may run at once, and how many tasks one parallel `subagent` call may contain. Default: 4. */
-export const DEFAULT_MAX_CONCURRENCY = 4;
-/** Upper bound accepted for maxConcurrency (defensive clamp). */
-export const MAX_CONCURRENCY_LIMIT = 16;
-/**
- * Maximum worker fixes after REVIEW_FAIL. Each fix is followed by a reviewer
- * re-review; this cap does not suppress the post-writer review gate or its
- * conditional/reviewer-disabled documentation fallback. 0 disables fixes.
- * Default: 2.
- */
-export const DEFAULT_MAX_FIX_ROUNDS = 2;
-/** Upper bound accepted for maxFixRounds (defensive clamp). 0 disables the loop. */
-export const MAX_FIX_ROUNDS_LIMIT = 5;
-
 /**
  * Default idle timeout in seconds: a sub-agent whose stdout (JSON event stream)
  * goes silent for this long is terminated; a selected model then hands the
@@ -112,27 +64,12 @@ export interface SubagentsConfig {
 	proactiveInjection: boolean;
 	/** Which agent directories to discover from. Default: "user". */
 	agentScope: AgentScope;
-	/** Max sub-agent processes running at once (extra work queues) and the max tasks
-	 * one parallel `subagent` call may contain. Default: 4. */
-	maxConcurrency: number;
-	/**
-	 * Maximum worker fixes after REVIEW_FAIL. Every fix receives the full review,
-	 * then a re-review runs; any documentation sync selected after the terminal
-	 * healthy review does not consume this budget. 0 disables fixes. Default: 2.
-	 */
-	maxFixRounds: number;
 	/**
 	 * Idle timeout in seconds: a sub-agent whose stdout (JSON event stream) goes
 	 * silent for this long is terminated; a configured agent model then hands
 	 * off to the current main model. 0 disables the idle watchdog. Default: 90.
 	 */
 	idleTimeoutSec: number;
-	/**
-	 * One-time feature announcements already shown to the user, plus schema
-	 * upgrade stamps (e.g. the cleaner default-enable upgrade). Persisted so
-	 * notices and migrations never repeat.
-	 */
-	announcedFeatures: string[];
 }
 
 export const DEFAULT_CONFIG: SubagentsConfig = {
@@ -143,10 +80,7 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 	maxResultLines: DEFAULT_MAX_RESULT_LINES,
 	proactiveInjection: true,
 	agentScope: "user",
-	maxConcurrency: DEFAULT_MAX_CONCURRENCY,
-	maxFixRounds: DEFAULT_MAX_FIX_ROUNDS,
 	idleTimeoutSec: DEFAULT_IDLE_TIMEOUT_SEC,
-	announcedFeatures: [],
 };
 
 export function getConfigPath(agentDir: string = getAgentDir()): string {
@@ -186,48 +120,30 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		const names = raw.enabledAgents.filter(
 			(name): name is string => typeof name === "string" && name.trim().length > 0,
 		);
-		// An explicitly empty array is honored. Rename the former built-in key and
-		// deduplicate when a config already contains both spellings.
-		config.enabledAgents = [...new Set(names.map((name) => migrateAgentName(name.trim())))];
+		// An explicitly empty array is honored; duplicates collapse.
+		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
 	}
 
 	if (isRecord(raw.agentModels)) {
-		const entries = Object.entries(raw.agentModels);
-		// A valid explicit new key wins regardless of JSON property order.
-		for (const [rawKey, value] of entries) {
+		for (const [rawKey, value] of Object.entries(raw.agentModels)) {
 			const key = rawKey.trim();
-			if (key !== LEGACY_EXPLORER_NAME && isModelReference(value)) {
+			if (key !== "" && isModelReference(value)) {
 				config.agentModels[key] = value.trim();
 			}
 		}
-		if (!Object.hasOwn(config.agentModels, EXPLORER_NAME)) {
-			const legacy = entries.find(([key, value]) =>
-				key.trim() === LEGACY_EXPLORER_NAME && isModelReference(value)
-			);
-			if (legacy && isModelReference(legacy[1])) config.agentModels[EXPLORER_NAME] = legacy[1].trim();
-		}
 	}
 
 	if (isRecord(raw.agentThinkingLevels)) {
-		const entries = Object.entries(raw.agentThinkingLevels);
-		for (const [rawKey, value] of entries) {
+		for (const [rawKey, value] of Object.entries(raw.agentThinkingLevels)) {
 			const key = rawKey.trim();
 			if (
-				key !== LEGACY_EXPLORER_NAME &&
+				key !== "" &&
 				typeof value === "string" &&
 				(THINKING_LEVEL_VALUES as readonly string[]).includes(value)
 			) {
 				config.agentThinkingLevels[key] = value as ThinkingLevel;
 			}
 		}
-		if (!Object.hasOwn(config.agentThinkingLevels, EXPLORER_NAME)) {
-			const legacy = entries.find(([key, value]) =>
-				key.trim() === LEGACY_EXPLORER_NAME &&
-				typeof value === "string" &&
-				(THINKING_LEVEL_VALUES as readonly string[]).includes(value)
-			);
-			if (legacy) config.agentThinkingLevels[EXPLORER_NAME] = legacy[1] as ThinkingLevel;
-		}
 	}
 
 	if (typeof raw.notifyOnReviewPass === "boolean") {
@@ -245,75 +161,11 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.agentScope = raw.agentScope;
 	}
 
-	const maxConcurrency = clampCount(raw.maxConcurrency, MAX_CONCURRENCY_LIMIT);
-	if (maxConcurrency !== undefined) config.maxConcurrency = maxConcurrency;
-
-	// 0 disables worker fixes, not the independent post-writer review gate or
-	// conditional/reviewer-disabled documentation fallback.
-	if (typeof raw.maxFixRounds === "number" && Number.isFinite(raw.maxFixRounds)) {
-		config.maxFixRounds = Math.max(0, Math.min(MAX_FIX_ROUNDS_LIMIT, Math.round(raw.maxFixRounds)));
-	}
-
 	// 0 disables the idle watchdog; otherwise clamp to [0, upper].
 	if (typeof raw.idleTimeoutSec === "number" && Number.isFinite(raw.idleTimeoutSec)) {
 		config.idleTimeoutSec = Math.max(0, Math.min(IDLE_TIMEOUT_SEC_LIMIT, Math.round(raw.idleTimeoutSec)));
 	}
 
-	if (Array.isArray(raw.announcedFeatures)) {
-		config.announcedFeatures = raw.announcedFeatures.filter(
-			(feature): feature is string => typeof feature === "string" && feature.trim().length > 0,
-		);
-	}
-
-	// One-time upgrade for configs written before cleaner shipped: a non-empty
-	// explicit enabledAgents list gets cleaner defaulted on (inserted before
-	// reviewer, matching the fresh-install order) and inherits the reviewer's
-	// configured model and thinking level — its closest peer. The stamps make
-	// the upgrade idempotent and keep a later deliberate disable from being undone.
-	if (!config.announcedFeatures.includes(CLEANER_DEFAULTED_FEATURE)) {
-		config.announcedFeatures.push(CLEANER_DEFAULTED_FEATURE);
-		if (config.enabledAgents.length > 0 && !config.enabledAgents.includes(CLEANER_NAME)) {
-			const reviewerIndex = config.enabledAgents.indexOf(REVIEWER_NAME);
-			config.enabledAgents.splice(reviewerIndex === -1 ? config.enabledAgents.length : reviewerIndex, 0, CLEANER_NAME);
-			config.announcedFeatures.push(CLEANER_AUTO_ENABLED_FEATURE);
-			let inherited = false;
-			if (!config.agentModels[CLEANER_NAME] && config.agentModels[REVIEWER_NAME]) {
-				config.agentModels[CLEANER_NAME] = config.agentModels[REVIEWER_NAME];
-				inherited = true;
-			}
-			if (!config.agentThinkingLevels[CLEANER_NAME] && config.agentThinkingLevels[REVIEWER_NAME]) {
-				config.agentThinkingLevels[CLEANER_NAME] = config.agentThinkingLevels[REVIEWER_NAME];
-				inherited = true;
-			}
-			// An old explicit list may have no reviewer overrides to copy; only the
-			// copied case is stamped so the one-time notice stays accurate.
-			if (inherited) config.announcedFeatures.push(CLEANER_INHERITED_FEATURE);
-		}
-	}
-
-	if (!config.announcedFeatures.includes(DOCUMENTER_DEFAULTED_FEATURE)) {
-		config.announcedFeatures.push(DOCUMENTER_DEFAULTED_FEATURE);
-		if (config.enabledAgents.length > 0 && !config.enabledAgents.includes(DOCUMENTER_NAME)) {
-			const reviewerIndex = config.enabledAgents.indexOf(REVIEWER_NAME);
-			config.enabledAgents.splice(
-				reviewerIndex === -1 ? config.enabledAgents.length : reviewerIndex,
-				0,
-				DOCUMENTER_NAME,
-			);
-			config.announcedFeatures.push(DOCUMENTER_AUTO_ENABLED_FEATURE);
-			let inherited = false;
-			if (!config.agentModels[DOCUMENTER_NAME] && config.agentModels[EXPLORER_NAME]) {
-				config.agentModels[DOCUMENTER_NAME] = config.agentModels[EXPLORER_NAME];
-				inherited = true;
-			}
-			if (!config.agentThinkingLevels[DOCUMENTER_NAME] && config.agentThinkingLevels[EXPLORER_NAME]) {
-				config.agentThinkingLevels[DOCUMENTER_NAME] = config.agentThinkingLevels[EXPLORER_NAME];
-				inherited = true;
-			}
-			if (inherited) config.announcedFeatures.push(DOCUMENTER_INHERITED_FEATURE);
-		}
-	}
-
 	return config;
 }
 
@@ -323,7 +175,6 @@ function defaultConfig(): SubagentsConfig {
 		enabledAgents: [...DEFAULT_CONFIG.enabledAgents],
 		agentModels: {},
 		agentThinkingLevels: {},
-		announcedFeatures: [],
 	};
 }
 
@@ -364,18 +215,6 @@ export async function loadConfig(configPath: string = getConfigPath()): Promise<
 	return config;
 }
 
-/**
- * Synchronous load for the extension's init-time decisions (e.g. the recursion
- * guard). Runs before any async context is available; never migrates or saves.
- */
-export function loadConfigSync(configPath: string = getConfigPath()): SubagentsConfig {
-	try {
-		return normalizeConfig(JSON.parse(readFileSync(configPath, "utf8")));
-	} catch {
-		return defaultConfig();
-	}
-}
-
 /**
  * Save config atomically (temp file + rename) serialized through pi's per-file
  * mutation queue so concurrent writers cannot interleave.

package/src/dispatch.ts

@@ -15,6 +15,7 @@ import { realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { Type } from "typebox";
 import { discoverAgents, resolveAgentTools, type AgentConfig } from "./agents.ts";
+import { MAX_CONCURRENT_SUBAGENTS } from "./background.ts";
 import { loadConfig } from "./config.ts";
 import { formatUsage, queuedResult } from "./format.ts";
 import {
@@ -23,6 +24,7 @@ import {
 	buildFixTaskBrief,
 	buildReReviewBrief,
 	documentationDisposition,
+	MAX_FIX_ROUNDS,
 	type ChainStep,
 	type ManagedWorkflowOutcome,
 } from "./fixloop.ts";
@@ -193,8 +195,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		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.
-			runtime.backgroundQueue.setConcurrency(config.maxConcurrency);
 
 			// Finished runs leave the active monitor immediately. Their final findings
 			// are sent as a custom message that starts a follow-up turn.
@@ -493,19 +493,19 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				): Promise<{ lastReview?: SingleResult; lastWorker?: SingleResult }> => {
 					let lastReviewer = triggeringReviewer;
 					const outcome: { lastReview?: SingleResult; lastWorker?: SingleResult } = {};
-					for (let round = 1; round <= request.config.maxFixRounds; round++) {
+					for (let round = 1; round <= MAX_FIX_ROUNDS; round++) {
 						if (!canContinue()) break;
-						const fixRelation = `fix ${round}/${request.config.maxFixRounds}`;
+						const fixRelation = `fix ${round}/${MAX_FIX_ROUNDS}`;
 						const workerResult = await launchStep(
 							"worker",
-							buildFixTaskBrief(lastReviewer, round, request.config.maxFixRounds),
+							buildFixTaskBrief(lastReviewer, round, MAX_FIX_ROUNDS),
 							`fix round ${round}`,
 							{ timelineRelation: fixRelation, childRelation: fixRelation },
 						);
 						if (isFailedResult(workerResult) || !canContinue()) break;
 						outcome.lastWorker = workerResult;
 
-						const reReviewRelation = `re-review ${round}/${request.config.maxFixRounds}`;
+						const reReviewRelation = `re-review ${round}/${MAX_FIX_ROUNDS}`;
 						const reviewResult = await launchStep(
 							"reviewer",
 							buildReReviewBrief(lastReviewer, round, workerResult, {
@@ -586,8 +586,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							!isFailedResult(gateReview) &&
 							canContinue() &&
 							reviewVerdict(getResultOutput(gateReview)) === "fail" &&
-							enabled("worker") &&
-							request.config.maxFixRounds > 0
+							enabled("worker")
 						) {
 							fixOutcome = await runFixRounds(gateReview);
 						}
@@ -620,12 +619,12 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			// Sub-agents intentionally detach from the foreground turn. This makes the
 			// editor available immediately; completion messages later wake the main agent.
 			if (params.tasks && params.tasks.length > 0) {
-				if (params.tasks.length > config.maxConcurrency) {
+				if (params.tasks.length > MAX_CONCURRENT_SUBAGENTS) {
 					return {
 						content: [
 							{
 								type: "text",
-								text: `Too many parallel tasks (${params.tasks.length}). Max is ${config.maxConcurrency} (configurable via /subagents-setup).`,
+								text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_CONCURRENT_SUBAGENTS}.`,
 							},
 						],
 						details: makeDetails("parallel", true)([]),

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.
@@ -14,7 +18,13 @@
 import { isWriteCapableAgent, type AgentConfig } from "./agents.ts";
 import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
 import { formatUsageCompact, sumUsage } from "./monitor.ts";
-import type { SubagentsConfig } from "./config.ts";
+
+/**
+ * Worker fixes allowed after REVIEW_FAIL. Each fix is followed by a reviewer
+ * re-review; this cap does not suppress the post-writer review gate or its
+ * conditional/reviewer-disabled documentation fallback.
+ */
+export const MAX_FIX_ROUNDS = 2;
 
 /**
  * Whether a completed result should trigger the auto-fix loop instead of being
@@ -23,8 +33,7 @@ import type { SubagentsConfig } from "./config.ts";
  * normally. Loop-internal re-review results never reach this path (they are
  * awaited inside the loop, not delivered through the completion flow).
  */
-export function shouldTriggerFixLoop(result: SingleResult, config: SubagentsConfig): boolean {
-	if (config.maxFixRounds <= 0) return false;
+export function shouldTriggerFixLoop(result: SingleResult): boolean {
 	if (result.agent !== "reviewer") return false;
 	if (isFailedResult(result)) return false;
 	// A dispatch crash (spawn infra, delivery API, ...) is never a real review
@@ -93,8 +102,8 @@ export function canStartManagedWorkflow(
 	if (isWriteCapableAgent(agent)) return true;
 	if (agent.name === "reviewer") {
 		// Hold a stable diff snapshot against every discoverable writer even when
-		// this review is advisory or maxFixRounds=0. Classification happens only
-		// after the read-only child returns, too late to acquire the lane safely.
+		// this review is advisory. Classification happens only after the read-only
+		// child returns, too late to acquire the lane safely.
 		return availability.writer;
 	}
 	return false;
@@ -104,7 +113,6 @@ export function canStartManagedWorkflow(
  * machine verdict is advisory and cannot start any write-capable child. */
 export function getManagedWorkflowPlan(
 	result: SingleResult,
-	config: SubagentsConfig,
 	availability: WorkflowAgentAvailability,
 ): ManagedWorkflowPlan | undefined {
 	if (result.parked || result.dispatchFailed || isFailedResult(result)) return undefined;
@@ -131,7 +139,7 @@ export function getManagedWorkflowPlan(
 	) {
 		return { kind: "review-pass-sync", initialRelation: "pre-documentation review" };
 	}
-	if (verdict === "fail" && availability.worker && shouldTriggerFixLoop(result, config)) {
+	if (verdict === "fail" && availability.worker && shouldTriggerFixLoop(result)) {
 		return { kind: "auto-fix", initialRelation: "initial review" };
 	}
 	return undefined;
@@ -139,8 +147,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 +162,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 +315,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 +334,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 +356,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/index.ts

@@ -86,7 +86,7 @@ export default function (pi: ExtensionAPI): void {
 			enabledNames: config.enabledAgents,
 			projectTrusted: ctx.isProjectTrusted?.() === true,
 		});
-		const directive = buildDelegationDirective(agents, { maxFixRounds: config.maxFixRounds });
+		const directive = buildDelegationDirective(agents);
 		if (!directive) return undefined;
 		return { systemPrompt: `${event.systemPrompt}\n${directive}` };
 	});

package/src/models.ts

@@ -86,6 +86,22 @@ export function findModelByRef(
 	return normalized ? models.find((model) => modelRef(model) === normalized) : undefined;
 }
 
+/** Split persisted agent model overrides into the ones Pi still reports as
+ * available and the stale ones. Stale refs are dropped at session start (with
+ * a user notice) so the config never carries models that can no longer run. */
+export function filterUnavailableModelOverrides(
+	agentModels: Record<string, string>,
+	models: readonly Model<Api>[],
+): { kept: Record<string, string>; dropped: Array<{ agent: string; ref: string }> } {
+	const kept: Record<string, string> = {};
+	const dropped: Array<{ agent: string; ref: string }> = [];
+	for (const [agent, ref] of Object.entries(agentModels)) {
+		if (findModelByRef(models, ref)) kept[agent] = ref;
+		else dropped.push({ agent, ref });
+	}
+	return { kept, dropped };
+}
+
 /**
  * Resolve one agent's runtime route:
  *

package/src/prompt.ts

@@ -13,7 +13,6 @@ function bullets(lines: readonly string[]): string {
 
 export function buildDelegationDirective(
 	agents: AgentConfig[],
-	options: { maxFixRounds?: number } = {},
 ): string {
 	if (agents.length === 0) return "";
 
@@ -24,7 +23,7 @@ export function buildDelegationDirective(
 	const hasDocumenter = agents.some((agent) => agent.name === "documenter");
 	const hasReviewer = agents.some((agent) => agent.name === "reviewer");
 	const hasMultiple = agents.length > 1;
-	const autoFixEnabled = hasWorker && (options.maxFixRounds ?? 1) > 0;
+	const autoFixEnabled = hasWorker;
 	const codeWriterNames = [
 		...(hasWorker ? ["worker"] : []),
 		...(hasCleaner ? ["cleaner"] : []),
@@ -101,10 +100,10 @@ export function buildDelegationDirective(
 			? [
 				...(hasDocumenter
 					? [
-						`A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps bounded worker/reviewer auto-fix, with docs considered only after its terminal REVIEW_PASS." : "cannot start fixes while worker/fix rounds are disabled."}`,
+						`A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps bounded worker/reviewer auto-fix, with docs considered only after its terminal REVIEW_PASS." : "cannot start fixes while worker is disabled."}`,
 					]
 					: []),
-				"Resolve every gate finding; do not bypass the configured auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and cannot trigger writes.",
+				"Resolve every gate finding; do not bypass the auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and 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.",
 			]
 			: []),

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 } from "./background.ts";
+import { BackgroundTaskQueue, MAX_CONCURRENT_SUBAGENTS } from "./background.ts";
 import {
 	completionGroupTriggersTurn,
 	createCompletionBatcher,
@@ -19,7 +19,7 @@ import {
 	type CompletionBatcher,
 	type CompletionMessageItem,
 } from "./completion.ts";
-import { loadConfigSync, type ThinkingLevel } from "./config.ts";
+import { type ThinkingLevel } from "./config.ts";
 import { isRunActiveStatus, monitor } from "./monitor.ts";
 import {
 	persistRecoveryRecords,
@@ -124,10 +124,7 @@ export interface SubagentRuntime {
 }
 
 export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRuntime {
-	// Init-time decisions need the config synchronously; the full (migrating)
-	// async load runs per tool call.
-	const initialConfig = loadConfigSync(configPath);
-	const backgroundQueue = new BackgroundTaskQueue(initialConfig.maxConcurrency);
+	const backgroundQueue = new BackgroundTaskQueue(MAX_CONCURRENT_SUBAGENTS);
 
 	const runtime: SubagentRuntime = {
 		configPath,

package/src/setup.ts

@@ -13,13 +13,9 @@ import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
 	AGENT_SCOPE_VALUES,
 	BUILTIN_AGENT_NAMES,
-	CLEANER_DEFAULTED_FEATURE,
-	DOCUMENTER_DEFAULTED_FEATURE,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
 	DEFAULT_IDLE_TIMEOUT_SEC,
-	DEFAULT_MAX_CONCURRENCY,
-	DEFAULT_MAX_FIX_ROUNDS,
 	DEFAULT_THINKING_LEVEL,
 	type AgentScope,
 	type SubagentsConfig,
@@ -243,8 +239,6 @@ async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Pr
 	return choice.startsWith("On");
 }
 
-const CONCURRENCY_STEPS = [1, 2, 3, 4, 6, 8, 12, 16];
-const FIX_ROUNDS_STEPS = [0, 1, 2, 3, 5];
 const IDLE_TIMEOUT_STEPS = [0, 30, 60, 90, 120, 180, 300, 600];
 
 async function pickCount(
@@ -299,22 +293,6 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 	if (injection === undefined) return false;
 	const scope = await pickScope(ctx, base.agentScope);
 	if (scope === undefined) return false;
-	const maxConcurrency = await pickCount(
-		ctx,
-		"Max sub-agents running at once?",
-		CONCURRENCY_STEPS,
-		base.maxConcurrency,
-		DEFAULT_MAX_CONCURRENCY,
-	);
-	if (maxConcurrency === undefined) return false;
-	const maxFixRounds = await pickCount(
-		ctx,
-		"Reviewer worker-fix rounds? (0 = no automatic fixes)",
-		FIX_ROUNDS_STEPS,
-		base.maxFixRounds,
-		DEFAULT_MAX_FIX_ROUNDS,
-	);
-	if (maxFixRounds === undefined) return false;
 	const idleTimeoutSec = await pickCount(
 		ctx,
 		"Idle timeout in seconds? (0 = disabled)",
@@ -333,16 +311,7 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		maxResultLines: base.maxResultLines,
 		proactiveInjection: injection,
 		agentScope: scope,
-		maxConcurrency,
-		maxFixRounds,
 		idleTimeoutSec,
-		// Full setup is an explicit decision point: mark role-enable migrations as
-		// processed so the user's saved selection is kept as-is.
-		announcedFeatures: [...new Set([
-			...base.announcedFeatures,
-			CLEANER_DEFAULTED_FEATURE,
-			DOCUMENTER_DEFAULTED_FEATURE,
-		])],
 	};
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured with Auto thinking. Saved to ${configPath}`, "info");
@@ -357,8 +326,6 @@ async function updateRuntimeSetting(
 		const choice = await ctx.ui.select("Runtime setting", [
 			"Proactive injection",
 			"Agent scope",
-			"Max concurrency",
-			"Reviewer worker-fix rounds",
 			"Idle timeout",
 		]);
 		if (choice === undefined) return undefined;
@@ -371,14 +338,6 @@ async function updateRuntimeSetting(
 			const value = await pickScope(ctx, config.agentScope);
 			if (value === undefined) continue;
 			next.agentScope = value;
-		} else if (choice.startsWith("Max concurrency")) {
-			const value = await pickCount(ctx, "Max sub-agents running at once?", CONCURRENCY_STEPS, config.maxConcurrency, DEFAULT_MAX_CONCURRENCY);
-			if (value === undefined) continue;
-			next.maxConcurrency = value;
-		} else if (choice.startsWith("Reviewer")) {
-			const value = await pickCount(ctx, "Reviewer worker-fix rounds?", FIX_ROUNDS_STEPS, config.maxFixRounds, DEFAULT_MAX_FIX_ROUNDS);
-			if (value === undefined) continue;
-			next.maxFixRounds = value;
 		} else {
 			const value = await pickCount(ctx, "Idle timeout in seconds?", IDLE_TIMEOUT_STEPS, config.idleTimeoutSec, DEFAULT_IDLE_TIMEOUT_SEC);
 			if (value === undefined) continue;

package/src/spawn.ts

@@ -272,7 +272,7 @@ export function isRetryableStartupFailure(result: SingleResult, durationMs: numb
 }
 
 export function formatStartupRetryExhaustedError(model: string, attempts: number): string {
-	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or temporarily lower maxConcurrency in /subagents-setup.`;
+	return `Subagent failed to start after ${attempts} attempt${attempts === 1 ? "" : "s"} on ${model}: the child failed before its initial RPC prompt was dispatched and produced no model, tool, output, or usage activity. This is typically a concurrent pi startup race (several sub-agents starting at once). Retry the dispatch, or dispatch fewer sub-agents at once.`;
 }
 
 export async function waitForStartupRetry(delayMs: number, signal?: AbortSignal): Promise<boolean> {

package/src/thread-lifecycle.ts

@@ -720,7 +720,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				if (!ownsResumeReservation(thread, reservation)) {
 					throw new Error(`Run #${runId} changed while resume configuration was loading.`);
 				}
-				runtime.backgroundQueue.setConcurrency(currentConfig.maxConcurrency);
 				const currentAgents = discoverAgents(currentCtx.cwd, {
 					scope: currentConfig.agentScope,
 					enabledNames: currentConfig.enabledAgents,
@@ -888,7 +887,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				if (!ownsFork()) throw new Error(`Run #${runId} changed while its retained session was being forked.`);
 				const currentConfig = await loadConfig(runtime.configPath);
 				if (!ownsFork()) throw new Error(`Run #${runId} changed while fork configuration was loading.`);
-				runtime.backgroundQueue.setConcurrency(currentConfig.maxConcurrency);
 				const currentAgents = discoverAgents(currentCtx.cwd, {
 					scope: currentConfig.agentScope,
 					enabledNames: currentConfig.enabledAgents,
@@ -971,7 +969,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				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) }
@@ -1064,7 +1061,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 
 				if (thread.retireOnSettle) runtime.retireThreadSession(thread);
 				let workflowOutcome: ManagedWorkflowOutcome | undefined;
-				const workflowPlan = getManagedWorkflowPlan(result, runConfig, workflowAvailability);
+				const workflowPlan = getManagedWorkflowPlan(result, workflowAvailability);
 				if (workflowPlan && runtime.sessionActive) {
 					thread.state = "running";
 					// The stable parent row now represents workflow ownership, not whichever