@ferris1225/pi-subagents 4.2.13 → 4.3.1

package/src/agents.ts

@@ -15,7 +15,7 @@ import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "no
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import { THINKING_LEVEL_VALUES, type AgentScope, type ThinkingLevel } from "./config.ts";
+import { type AgentScope } from "./config.ts";
 import type { IsolationMode } from "./worktree.ts";
 
 export type AgentSource = "builtin" | "user" | "project";
@@ -26,8 +26,6 @@ export interface AgentConfig {
 	tools?: string[];
 	/** Model ref this run was routed to; filled in by dispatch, never declared by the agent file. */
 	model?: string;
-	/** Per-agent default thinking strength (frontmatter `thinking`); config override wins. */
-	thinking?: ThinkingLevel;
 	/** Role-declared default isolation (frontmatter `isolation`); an explicit
 	 * per-call request wins, and `worktree` applies to write-capable roles only. */
 	isolation?: IsolationMode;
@@ -41,7 +39,7 @@ const SHELL_TOOL_NAMES = new Set(["bash", "powershell"]);
  * Only used to break a tie when the parent has both enabled — a parent running a
  * single shell is followed as configured, whatever it is. */
 const NATIVE_SHELL_TOOL = process.platform === "win32" ? "powershell" : "bash";
-const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
+const READ_ONLY_TOOL_NAMES = new Set(["read", "grep", "find", "ls"]);
 export const SUBAGENT_TOOL_NAMES = [
 	"subagent",
 	"subagent_control",
@@ -50,21 +48,26 @@ export const SUBAGENT_TOOL_NAMES = [
 const SUBAGENT_TOOL_NAME_SET = new Set<string>(SUBAGENT_TOOL_NAMES);
 
 /** Resolve every child against the parent's live tool selection. Roles without
- * an allowlist inherit the complete active set. Explicit lists keep only their
- * declared Pi built-ins, adapt an existing shell slot, and gain active extension/
- * SDK tools. pi-subagents controls are always removed so children stay leaves.
+ * an allowlist inherit the complete active set. Explicit lists are strict: they
+ * keep only declared tools that are active in the parent, with shell adaptation.
+ * Active extension/SDK tools are never added implicitly. pi-subagents controls
+ * are always removed so children stay leaves.
  *
  * A declared shell is one slot, so it resolves to one shell: the parent's, and
  * the host-native one when the parent runs both. A child never inherits a shell
- * the parent does not have — Pi's `--tools` allowlist overrides the child's own
- * `defaultTools` setting, so naming a shell the user disabled would hand it a
- * terminal they deliberately turned off. */
+ * the parent does not have. */
 export function resolveAgentTools(
 	agent: AgentConfig,
 	activeToolNames: readonly string[],
 ): AgentConfig {
 	const active = [...new Set(activeToolNames)].filter((tool) => !SUBAGENT_TOOL_NAME_SET.has(tool));
-	if (!agent.tools) return { ...agent, tools: active };
+	if (!agent.tools) {
+		return { ...agent, tools: agent.name === "scout" ? active.filter((tool) => READ_ONLY_TOOL_NAMES.has(tool)) : active };
+	}
+	const declaredTools = agent.name === "scout"
+		? agent.tools.filter((tool) => READ_ONLY_TOOL_NAMES.has(tool))
+		: agent.tools;
+	const activeSet = new Set(active);
 
 	const parentShellTools = active.filter((tool) => SHELL_TOOL_NAMES.has(tool));
 	const activeShellTools = parentShellTools.length > 1 && parentShellTools.includes(NATIVE_SHELL_TOOL)
@@ -72,32 +75,30 @@ export function resolveAgentTools(
 		: parentShellTools;
 	const tools: string[] = [];
 	let shellAdapted = false;
-	for (const tool of agent.tools) {
+	for (const tool of declaredTools) {
+		if (SUBAGENT_TOOL_NAME_SET.has(tool)) continue;
 		if (SHELL_TOOL_NAMES.has(tool)) {
 			if (!shellAdapted) tools.push(...activeShellTools);
 			shellAdapted = true;
-		} else if (PI_BUILTIN_TOOL_NAMES.has(tool) && !tools.includes(tool)) {
+		} else if (activeSet.has(tool) && !tools.includes(tool)) {
 			tools.push(tool);
 		}
 	}
-	for (const tool of active) {
-		if (PI_BUILTIN_TOOL_NAMES.has(tool) || tools.includes(tool)) continue;
-		tools.push(tool);
-	}
 	return { ...agent, tools };
 }
 
 /** Filesystem-write capability used by worktree admission and repository-lane
- * safety. Built-in read-only role names remain read-only even when overridden;
- * an omitted tool list inherits the parent's active set, so it counts as
- * write-capable unless the parent itself is read-only. */
+ * safety. Scout is a hard read-only boundary even with a project override.
+ * Omitted allowlists inherit arbitrary active tools and are therefore mutable.
+ * For explicit allowlists, only the canonical retrieval tools are proven
+ * read-only; shells and unknown custom tools are conservatively mutable. */
 export function isWriteCapableAgent(
 	agent: Pick<AgentConfig, "name" | "tools">,
 ): boolean {
-	if (agent.name === "explorer") return false;
-	if (agent.name === "executor") return true;
+	if (agent.name === "scout") return false;
+	if (agent.name === "artisan" || agent.name === "steward") return true;
 	if (!agent.tools) return true;
-	return agent.tools.includes("edit") || agent.tools.includes("write");
+	return agent.tools.some((tool) => !READ_ONLY_TOOL_NAMES.has(tool));
 }
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -145,10 +146,6 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			?.split(",")
 			.map((t) => t.trim())
 			.filter(Boolean);
-		const rawThinking = str(frontmatter.thinking)?.trim();
-		const thinking = (THINKING_LEVEL_VALUES as readonly string[]).includes(rawThinking ?? "")
-			? (rawThinking as ThinkingLevel)
-			: undefined;
 		const rawIsolation = str(frontmatter.isolation)?.trim();
 		const isolation = rawIsolation === "worktree" || rawIsolation === "shared"
 			? (rawIsolation as IsolationMode)
@@ -158,7 +155,6 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			name,
 			description,
 			tools: tools && tools.length > 0 ? tools : undefined,
-			...(thinking ? { thinking } : {}),
 			...(isolation ? { isolation } : {}),
 			systemPrompt: body,
 			source,

package/src/announcements.ts

@@ -1,21 +1,16 @@
-/** Session-start recovery, stale-config migration, and progress-surface installation. */
+/** Session-start recovery, stale-model cleanup, and progress-surface installation. */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { existsSync } from "node:fs";
-import { loadConfig, saveConfig } from "./config.ts";
+import { FIRST_RUN_SETUP_HINT, loadConfig, saveConfig } from "./config.ts";
 import { availableModelsInScope, filterUnavailableModelOverrides } from "./models.ts";
-import { announceRecoveryRecords } from "./recovery.ts";
+import { announceRecoveryRecords, relocateRecoveryManifest } from "./recovery.ts";
 import type { SubagentRuntime } from "./runtime.ts";
 import { installActiveRunsStatus } from "./status.ts";
 import { installActiveRunsWidget } from "./widget.ts";
 
-/**
- * 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(
+/** Drop unavailable model overrides back to dynamic main-model routing. */
+async function removeUnavailableAgentModels(
 	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } } & Parameters<typeof availableModelsInScope>[0],
 	runtime: SubagentRuntime,
 ): Promise<void> {
@@ -32,22 +27,20 @@ async function migrateUnavailableAgentModels(
 			"warning",
 		);
 	} catch {
-		/* migration failures are non-fatal */
+		/* stale-model cleanup is non-fatal */
 	}
 }
 
 export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	pi.on("session_start", async (_event, ctx) => {
 		if (!existsSync(runtime.configPath)) {
-			ctx.ui.notify(
-				"pi-subagents: no configuration yet — run /subagents-setup to pick agents, models, and thinking strengths. Defaults (all built-in agents on the main model) apply until then.",
-				"info",
-			);
+			ctx.ui.notify(`pi-subagents: ${FIRST_RUN_SETUP_HINT}`, "info");
 		}
+		await relocateRecoveryManifest(runtime.configPath);
 		await announceRecoveryRecords(runtime.configPath, ctx);
-		await migrateUnavailableAgentModels(ctx, runtime);
-		// Restore starts at extension load and session_start fires right behind
-		// it, so without this the notice reports whatever the race left behind.
+		await removeUnavailableAgentModels(ctx, runtime);
+		// Bootstrap also runs on session_start; wait so this notice sees restored
+		// threads instead of racing an empty list.
 		await runtime.durableRestore;
 		if (!runtime.restoredNotified && runtime.restoredRunIds.length > 0) {
 			runtime.restoredNotified = true;

package/src/background.ts

@@ -14,6 +14,7 @@ import { cpus } from "node:os";
 export type BackgroundTask = (signal: AbortSignal, controller: AbortController) => Promise<void>;
 
 interface PendingTask {
+	kind: "task";
 	task: BackgroundTask;
 	controller: AbortController;
 	complete: () => void;
@@ -29,6 +30,14 @@ interface PendingTask {
 	onError?: (error: unknown) => void | Promise<void>;
 }
 
+interface PendingAcquire {
+	kind: "acquire";
+	controller: AbortController;
+	resolve: (acquired: boolean) => void;
+}
+
+type PendingEntry = PendingTask | PendingAcquire;
+
 /** How many sub-agent processes may run at once, derived from the host instead
  * of being fixed: children wait on model I/O far more than on CPU, so the pool
  * scales with cores while the bounds keep tiny machines usable and huge ones
@@ -40,7 +49,7 @@ export function resolveSubagentConcurrency(cpuCount: number = cpus().length): nu
 
 export class BackgroundTaskQueue {
 	private concurrency: number;
-	private readonly pending: PendingTask[] = [];
+	private readonly pending: PendingEntry[] = [];
 	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. */
@@ -67,7 +76,7 @@ export class BackgroundTaskQueue {
 			return controller;
 		}
 
-		this.pending.push({ task, controller, complete, onCancelled, onError });
+		this.pending.push({ kind: "task", task, controller, complete, onCancelled, onError });
 		this.drain();
 		return controller;
 	}
@@ -88,7 +97,7 @@ export class BackgroundTaskQueue {
 
 	/** Tasks still waiting for a free slot (never started). */
 	get pendingCount(): number {
-		return this.pending.length;
+		return this.pending.filter((entry) => entry.kind === "task").length;
 	}
 
 	/** Tasks currently holding a slot. Suspended tasks (lane waits, managed
@@ -114,6 +123,19 @@ export class BackgroundTaskQueue {
 		this.drain();
 	}
 
+	/** Reacquire a released process slot before a suspended task starts another
+	 * child process. Reacquisitions share FIFO order with not-yet-started tasks,
+	 * so lane waiters cannot bypass work already queued for the pool. */
+	acquire(controller: AbortController | undefined): Promise<boolean> {
+		if (!controller || this.stopped || controller.signal.aborted) return Promise.resolve(false);
+		if (this.active.has(controller)) return Promise.resolve(true);
+		if (!this.suspended.has(controller)) return Promise.resolve(false);
+		return new Promise<boolean>((resolve) => {
+			this.pending.push({ kind: "acquire", controller, resolve });
+			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. */
@@ -123,8 +145,13 @@ export class BackgroundTaskQueue {
 		const index = this.pending.findIndex((entry) => entry.controller === controller);
 		if (index !== -1) {
 			const [entry] = this.pending.splice(index, 1);
-			this.runCancelled(entry.onCancelled);
-			entry.complete();
+			if (entry.kind === "task") {
+				this.runCancelled(entry.onCancelled);
+				entry.complete();
+			} else {
+				this.suspended.delete(controller);
+				entry.resolve(false);
+			}
 			this.drain();
 			this.resolveIdleWaiters();
 		}
@@ -143,8 +170,13 @@ export class BackgroundTaskQueue {
 
 		for (const entry of this.pending.splice(0)) {
 			entry.controller.abort();
-			this.runCancelled(entry.onCancelled);
-			entry.complete();
+			if (entry.kind === "task") {
+				this.runCancelled(entry.onCancelled);
+				entry.complete();
+			} else {
+				this.suspended.delete(entry.controller);
+				entry.resolve(false);
+			}
 		}
 		for (const controller of this.active) controller.abort();
 		for (const controller of this.suspended) controller.abort();
@@ -170,8 +202,23 @@ export class BackgroundTaskQueue {
 				return;
 			}
 			if (entry.controller.signal.aborted) {
-				this.runCancelled(entry.onCancelled);
-				entry.complete();
+				if (entry.kind === "task") {
+					this.runCancelled(entry.onCancelled);
+					entry.complete();
+				} else {
+					this.suspended.delete(entry.controller);
+					entry.resolve(false);
+				}
+				continue;
+			}
+
+			if (entry.kind === "acquire") {
+				if (!this.suspended.delete(entry.controller)) {
+					entry.resolve(false);
+					continue;
+				}
+				this.active.add(entry.controller);
+				entry.resolve(true);
 				continue;
 			}
 

package/src/completion.ts

@@ -98,7 +98,6 @@ export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>)
 export interface CompletionMessageItem {
 	agent: string;
 	block: string;
-	triggerTurn: boolean;
 	/** Final usage of the underlying run (or chain); aggregated into the group totals. */
 	usage?: UsageStats;
 }
@@ -115,11 +114,6 @@ export function formatCompletionMessage(items: readonly CompletionMessageItem[])
 	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}${footer}`;
 }
 
-/** A grouped completion wakes the main agent when any member requires a turn. */
-export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
-	return items.some((item) => item.triggerTurn);
-}
-
 /** Minimal shape of an active run, for the "others still running" footer. Kept
  * decoupled from the monitor's RunView so this stays a pure, easily tested
  * formatter; the caller maps its live runs into this shape. */

package/src/config.ts

@@ -13,14 +13,7 @@ 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", "executor"] as const;
-
-/** Built-in agent names this package no longer ships. Loading an older config
- * prunes them from every record so the setup wizard, dispatch catalog, and
- * model-routing table never surface dead roles. Custom names stay untouched —
- * except one that reuses a removed built-in name, which this cleanup cannot
- * distinguish and deliberately treats as retired. */
-export const REMOVED_BUILTIN_AGENT_NAMES = ["worker", "cleaner", "documenter", "synthesizer", "reviewer"] as const;
+export const BUILTIN_AGENT_NAMES = ["scout", "artisan", "steward"] as const;
 
 /** Agents enabled out of the box on a fresh install. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = [...BUILTIN_AGENT_NAMES];
@@ -31,7 +24,49 @@ export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 /** 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];
-export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "high";
+export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium";
+
+/** Role-owned default reasoning strength. A `/subagents-setup` override wins;
+ * there is no per-call or frontmatter thinking. */
+export function roleThinkingLevel(agentName: string): ThinkingLevel {
+	switch (agentName) {
+		case "scout":
+			return "low";
+		case "artisan":
+			return "high";
+		case "steward":
+			return "medium";
+		default:
+			return DEFAULT_THINKING_LEVEL;
+	}
+}
+
+/** Short responsibility line shown next to each built-in in setup lists. */
+export interface AgentProfile {
+	/** A few words for picker rows. */
+	summary: string;
+	/** What this role owns, for first-run copy and the configure step. */
+	remark: string;
+}
+
+export const AGENT_PROFILES: Record<(typeof BUILTIN_AGENT_NAMES)[number], AgentProfile> = {
+	scout: {
+		summary: "read-only recon",
+		remark: "Broad or unknown reconnaissance. Returns decisive citations as leads, never proof.",
+	},
+	artisan: {
+		summary: "implement / fix",
+		remark: "Owns implementation, code refactors, and directly affected tests/docs; a disproved defect means zero edits.",
+	},
+	steward: {
+		summary: "pre-commit finish",
+		remark: "Cleans a completed broad or multi-writer diff and synchronizes cross-cutting docs/comments without changing behavior.",
+	},
+};
+
+export function agentProfile(name: string): AgentProfile | undefined {
+	return (AGENT_PROFILES as Record<string, AgentProfile | undefined>)[name];
+}
 
 /** How many lines of a sub-agent result the completion message may carry.
  * Default: 40 — wide fan-outs multiply completion blocks, so deliveries stay
@@ -54,14 +89,10 @@ export const IDLE_TIMEOUT_SEC_LIMIT = 600;
 export interface SubagentsConfig {
 	/** Agent names that are discoverable and injected. Fresh-install default: every built-in agent. */
 	enabledAgents: string[];
-	/** Built-in names this config has already surfaced. A shipped agent outside
-	 * this set is new in an upgrade: loadConfig enables it instead of leaving it
-	 * dark behind a stale allow-list. Bookkeeping only — maintained automatically,
-	 * and it is what keeps an explicit disable from being undone. */
-	knownAgents: string[];
 	/** Per-agent model override, keyed by agent name, as "provider/model-id". */
 	agentModels: Record<string, string>;
-	/** Optional per-agent thinking preference. Runtime clamps it to the effective model's supported levels. */
+	/** Optional per-agent thinking override from `/subagents-setup`. Missing =
+	 * the role default from `roleThinkingLevel`. */
 	agentThinkingLevels: Record<string, ThinkingLevel>;
 	/**
 	 * Max lines of a sub-agent result carried in the completion message. Longer
@@ -81,7 +112,6 @@ export interface SubagentsConfig {
 
 export const DEFAULT_CONFIG: SubagentsConfig = {
 	enabledAgents: [...DEFAULT_ENABLED_AGENTS],
-	knownAgents: [...BUILTIN_AGENT_NAMES],
 	agentModels: {},
 	agentThinkingLevels: {},
 	maxResultLines: DEFAULT_MAX_RESULT_LINES,
@@ -89,6 +119,12 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 	idleTimeoutSec: DEFAULT_IDLE_TIMEOUT_SEC,
 };
 
+export const FIRST_RUN_SETUP_HINT =
+	"Run /subagents-setup to choose enabled roles and pick their models. " +
+	"Keep orchestration on the strongest main model; prefer an efficient model for scout and steward. " +
+	"Scout handles clustered broad reconnaissance, artisan implements with affected tests/docs, " +
+	"and steward finishes completed broad or multi-writer changes before commit.";
+
 export function getConfigPath(agentDir: string = getAgentDir()): string {
 	return join(agentDir, CONFIG_FILE_NAME);
 }
@@ -130,20 +166,6 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
 	}
 
-	// Known-agent bookkeeping starts empty for a parsed record (not the fresh
-	// default) so loadConfig can still tell which shipped agents this config
-	// has never seen. Every enabled name was necessarily surfaced.
-	config.knownAgents = [];
-	if (Array.isArray(raw.knownAgents)) {
-		const names = raw.knownAgents.filter(
-			(name): name is string => typeof name === "string" && name.trim().length > 0,
-		);
-		config.knownAgents = [...new Set(names.map((name) => name.trim()))];
-	}
-	for (const name of config.enabledAgents) {
-		if (!config.knownAgents.includes(name)) config.knownAgents.push(name);
-	}
-
 	if (isRecord(raw.agentModels)) {
 		for (const [rawKey, value] of Object.entries(raw.agentModels)) {
 			const key = rawKey.trim();
@@ -190,63 +212,10 @@ function defaultConfig(): SubagentsConfig {
 	};
 }
 
-/**
- * Drop every removed built-in role from an already-normalized config: enabled
- * and known lists, plus per-agent model and thinking routes. The schema-upgrade
- * persistence in loadConfig writes the pruned shape back to disk.
- */
-function pruneRemovedBuiltins(config: SubagentsConfig): SubagentsConfig {
-	const removed = new Set<string>(REMOVED_BUILTIN_AGENT_NAMES);
-	const filter = (names: readonly string[]): string[] => names.filter((name) => !removed.has(name));
-	const agentModels = { ...config.agentModels };
-	const agentThinkingLevels = { ...config.agentThinkingLevels };
-	for (const name of REMOVED_BUILTIN_AGENT_NAMES) {
-		delete agentModels[name];
-		delete agentThinkingLevels[name];
-	}
-	return {
-		...config,
-		enabledAgents: filter(config.enabledAgents),
-		knownAgents: filter(config.knownAgents),
-		agentModels,
-		agentThinkingLevels,
-	};
-}
-
-/**
- * A shipped agent the config has never recorded is new in this release; the
- * stale allow-list must not keep it dark. Enable it and adopt explorer's
- * configured model and thinking level, so an upgrade surfaces the new role on
- * the fast light-task lane instead of silently spending the main model.
- */
-function adoptNewBuiltins(config: SubagentsConfig): SubagentsConfig {
-	const known = new Set(config.knownAgents);
-	const fresh = BUILTIN_AGENT_NAMES.filter((name) => !known.has(name));
-	if (fresh.length === 0) return config;
-	const agentModels = { ...config.agentModels };
-	const agentThinkingLevels = { ...config.agentThinkingLevels };
-	for (const name of fresh) {
-		if (!agentModels[name] && config.agentModels.explorer) agentModels[name] = config.agentModels.explorer;
-		if (!agentThinkingLevels[name] && config.agentThinkingLevels.explorer) {
-			agentThinkingLevels[name] = config.agentThinkingLevels.explorer;
-		}
-	}
-	return {
-		...config,
-		enabledAgents: [...config.enabledAgents, ...fresh],
-		knownAgents: [...known, ...fresh],
-		agentModels,
-		agentThinkingLevels,
-	};
-}
-
 /**
  * Load config. A missing file is a normal state and yields the defaults (not an error).
  * A corrupt file also falls back to defaults rather than throwing, so startup never breaks.
- * A file from an older version (missing newer keys or holding extra keys) is
- * normalized and persisted back, so the on-disk config stays current. Built-in
- * agents the file has never seen are adopted: enabled with explorer's route.
- * Built-in roles this package retired are pruned from every record.
+ * Valid fields are normalized and unknown fields are omitted when the config is saved.
  */
 export async function loadConfig(configPath: string = getConfigPath()): Promise<SubagentsConfig> {
 	let text: string;
@@ -264,13 +233,9 @@ export async function loadConfig(configPath: string = getConfigPath()): Promise<
 		return defaultConfig();
 	}
 
-	// Adopt newly shipped roles first so the prune below works on the final
-	// catalog, then drop roles this package stopped shipping and persist the
-	// cleaned shape back to disk.
-	const config = pruneRemovedBuiltins(adoptNewBuiltins(normalizeConfig(parsed)));
+	const config = normalizeConfig(parsed);
 
-	// Schema upgrade: persist the normalized shape when the file gained fields
-	// (new version) or dropped invalid ones.
+	// Persist the canonical shape when invalid or unknown fields were omitted.
 	if (JSON.stringify(config) !== JSON.stringify(parsed)) {
 		try {
 			await saveConfig(config, configPath);