@ferris1225/pi-subagents 4.1.7 → 4.1.8

package/README.md

@@ -207,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
 
@@ -245,8 +245,9 @@ 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.
@@ -503,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
@@ -534,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
 }
 ```
@@ -549,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/package.json

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

@@ -18,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
@@ -27,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
@@ -97,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;
@@ -108,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;
@@ -135,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;

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