@ferris1225/pi-subagents 4.1.7 → 4.1.9

package/agents/worker.md

@@ -7,38 +7,20 @@ thinking: high
 # balance quality against cost. No `tools` field => inherits all tools (full capability).
 ---
 
-You are a worker agent with full capabilities, operating in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
+You are a worker agent with full capabilities in an isolated context window. You own a delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
 
-## Standard operating procedure
-Work in phases. Do not skip planning or verification.
+## Procedure
+1. **Context.** Read the brief fully. Read referenced files before editing, and referenced images (screenshots, mockups, designs) too — the model receives them as attachments when it supports vision. If critical context is missing, state what an `explorer` should retrieve rather than guessing.
+2. **Plan.** Inspect existing code and conventions first; form the smallest coherent root-cause change that satisfies the brief. Prefer the design that deletes complexity rather than rearranges it — if a simpler structure (fewer branches, modes, or layers) achieves the goal, take it, and decompose rather than push a file toward ~1000 lines. For a large task, note files to touch, order, and risks before editing. No unrelated refactors or standalone documentation work unless the brief asks.
+3. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize existing README/docs, examples, and comments directly affected by your change; do not defer obvious drift to another role.
+4. **Verify.** Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
+5. **Handoff.** Return only the concrete outcome. Do not repeat the task brief, plan, root-cause investigation, or tool chronology. Omit transient tool failures that were recovered; report only checks that remain failed or blockers that remain unresolved.
 
-### Phase 1 — Context
-Read the brief fully. If it references files, read them before editing. If it references images (screenshots, mockups, designs), `read` them too — the model receives them as attachments when it supports vision. If critical context is clearly missing, state what an `explorer` should retrieve rather than guessing.
-
-### Phase 2 — Plan
-Inspect existing code and conventions first. Form the smallest coherent root-cause change that satisfies the brief. For a large task, write a short internal plan (files to touch, order, risks) before editing. Do not refactor unrelated code or start broad/standalone documentation work unless the brief asks.
-
-### Phase 3 — Implement
-Make the change. Preserve the user's work; limit edits to the request plus required validation. Follow the project's existing error handling, naming, and style. Synchronize any existing README/docs, examples, API comments, docstrings, and explanatory comments directly affected by your change; do not defer obvious drift to another role.
-
-### Phase 4 — Verify
-Run the project's format/build/tests when they exist (e.g. `tsc --noEmit`, the test runner). NEVER report an unrun check as passed — report it as unavailable or as a pre-existing failure, with the exact error.
-
-### Phase 5 — Handoff
-Return only the concrete outcome so the caller can verify it and, if needed, hand it to a `reviewer`. Do not repeat the task brief, plan, root-cause investigation, or tool chronology. Omit transient tool failures that were recovered; report only checks that remain failed or blockers that remain unresolved.
-
-## Release boundary
-Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate, any conditional final documentation sync, and every release action—even when repository instructions normally automate release after green checks.
-
-## Collaboration
-- 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.
+## Boundaries
+- Never commit, push, publish, tag, release, or bump a package version. The parent workflow owns the independent review gate, the conditional final documentation sync, and every release action — even when repository instructions normally automate release after green checks.
+- Children are leaf processes: you cannot dispatch sub-agents. When the brief needs broad discovery, state what an `explorer` should retrieve; do not guess.
+- In an auto-fix round, apply the reviewer's fix instructions: implement each when it is sound; when it is wrong, out of scope, or a sounder fix exists, ship 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.
+- Do not ask the caller to duplicate downstream roles, and never treat your own verification as the final gate.
 
 ## Output format
 ## Completed
@@ -48,9 +30,8 @@ What was done, in a few lines.
 ## Verification
 Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
 ## Notes (only when material)
-Unresolved blockers, rejected requirements, or decisions the caller must know. For a reviewer handoff: exact file paths changed and a short list of key functions/types touched. Omit the section when there is nothing actionable to add.
+Unresolved blockers, rejected requirements, or decisions the caller must know. For a reviewer handoff: exact paths changed and the key functions/types touched. Omit the section when there is nothing actionable to add.
 
 Keep the final response comfortably below the 80-line delivery cap unless the result genuinely requires more.
 
-## Quality standards
-Root-cause fixes over patches. No unrelated churn. Honest verification — an unrun check is never a passed check.
+Root-cause fixes over patches; no unrelated churn; an unrun check is never a passed check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.1.7",
+  "version": "4.1.9",
   "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),
+		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",
 		);
-		if (pending.length === 0) return;
-		await saveConfig(
-			{
-				...config,
-				announcedFeatures: [...config.announcedFeatures, ...pending.map((announcement) => announcement.key)],
-			},
-			runtime.configPath,
-		);
-		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,16 @@ 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 (!runtime.restoredNotified && runtime.restoredRunIds.length > 0) {
+			runtime.restoredNotified = true;
+			const ids = runtime.restoredRunIds.map((id) => `#${id}`).join(", ");
+			ctx.ui.notify(
+				`pi-subagents: restored ${runtime.restoredRunIds.length} resumable thread${runtime.restoredRunIds.length === 1 ? "" : "s"} from the previous session (${ids}). subagent_status lists them; subagent_control resume continues one.`,
+				"info",
+			);
+		}
 		if (ctx.mode !== "tui") return;
 		installActiveRunsWidget(ctx);
-		await announceNewFeatures(ctx, runtime);
 	});
 }

package/src/background.ts

@@ -27,10 +27,21 @@ 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. Only manually
+ * dispatched top-level generations hold slots; runtime-initiated managed
+ * continuations (gate reviews, auto-fix rounds, documentation sync) suspend
+ * their task's slot so they never starve manual dispatches. */
+export const MAX_CONCURRENT_SUBAGENTS = 4;
+
 export class BackgroundTaskQueue {
 	private concurrency: number;
 	private readonly pending: PendingTask[] = [];
 	private readonly active = new Set<AbortController>();
+	/** Active tasks that no longer count toward the concurrency limit. They keep
+	 * every other guarantee: abortable, awaited by waitForTask/waitForIdle. */
+	private readonly suspended = new Set<AbortController>();
 	private readonly completions = new WeakMap<AbortController, Promise<void>>();
 	private readonly idleWaiters = new Set<() => void>();
 	private stopped = false;
@@ -39,16 +50,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;
@@ -76,6 +77,16 @@ export class BackgroundTaskQueue {
 		return this.completions.get(controller) ?? Promise.resolve();
 	}
 
+	/** Stop counting a running task toward the concurrency limit. Its body keeps
+	 * running under the same abort signal; completion still releases everything
+	 * waitForTask/waitForIdle promise. Frees a slot for queued work immediately. */
+	suspend(controller: AbortController | undefined): void {
+		if (!controller || this.stopped) return;
+		if (!this.active.delete(controller)) return;
+		this.suspended.add(controller);
+		this.drain();
+	}
+
 	/** Cancel one queued/running task. Queued entries are removed immediately;
 	 * active entries resolve waitForTask only after their body and error handler
 	 * have quiesced and the concurrency slot has been released. */
@@ -94,7 +105,7 @@ export class BackgroundTaskQueue {
 
 	/** Resolve once no queued or running task remains. */
 	waitForIdle(): Promise<void> {
-		if (this.pending.length === 0 && this.active.size === 0) return Promise.resolve();
+		if (this.pending.length === 0 && this.active.size === 0 && this.suspended.size === 0) return Promise.resolve();
 		return new Promise<void>((resolve) => this.idleWaiters.add(resolve));
 	}
 
@@ -109,6 +120,7 @@ export class BackgroundTaskQueue {
 			entry.complete();
 		}
 		for (const controller of this.active) controller.abort();
+		for (const controller of this.suspended) controller.abort();
 		this.resolveIdleWaiters();
 	}
 
@@ -150,6 +162,7 @@ export class BackgroundTaskQueue {
 				})
 				.finally(() => {
 					this.active.delete(entry.controller);
+					this.suspended.delete(entry.controller);
 					entry.complete();
 					this.drain();
 					this.resolveIdleWaiters();
@@ -158,7 +171,7 @@ export class BackgroundTaskQueue {
 	}
 
 	private resolveIdleWaiters(): void {
-		if (this.pending.length > 0 || this.active.size > 0) return;
+		if (this.pending.length > 0 || this.active.size > 0 || this.suspended.size > 0) return;
 		for (const resolve of this.idleWaiters) resolve();
 		this.idleWaiters.clear();
 	}

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.