@ferris1225/pi-subagents 4.0.0 → 4.0.1

package/README.md

@@ -11,13 +11,15 @@ Focused background delegation for [pi](https://pi.dev): `explorer` / `worker` /
 results back to the main agent automatically. Install it, and the main model
 starts using it on its own — no prompt engineering, no babysitting.
 
-## 4.0.0 — consistent agent names and direct cleanup
+## 4.0.1 — automatic explorer config migration
 
 Version 4 renames the built-in reconnaissance role from `explore` to `explorer`
-and deliberately removes the old alias. Existing explicit configuration must use
-the new key. `cleaner` is now apply-only: explicit cleanup intent authorizes it to
-prove and perform every safe in-scope cut, while generic or read-only assessments
-go to `reviewer` without triggering auto-fix.
+without retaining a runtime alias. Version 4.0.1 automatically migrates the old
+name in `enabledAgents`, `agentModels`, and `agentThinkingLevels`, then persists
+the normalized configuration; an already configured `explorer` value wins a
+conflict. `cleaner` is apply-only: explicit cleanup intent authorizes it to prove
+and perform every safe in-scope cut, while generic or read-only assessments go to
+`reviewer` without triggering auto-fix.
 
 The main delegation directive is now the single authoritative routing policy;
 duplicated tool guidelines were removed to cut the default parent injection by
@@ -418,13 +420,14 @@ Config loading normalizes schema fields and removes invalid or obsolete keys,
 including `agentBackupModels`, global `thinkingLevel`, `maxParallelTasks`, and
 `maxSubagentDepth`. Per-agent thinking preferences remain capability-clamped.
 
-The built-in reconnaissance role is now `explorer`. There is deliberately no
-`explore` alias and no automatic key migration. Existing configurations must change
-that role name in `enabledAgents`, `agentModels`, and `agentThinkingLevels` (or run
-`/subagents-setup`). Configured non-empty names are otherwise preserved, so a stale
-name is not silently rewritten. A pre-existing explicit `enabledAgents` list is
-also still preserved without appending `cleaner`; configs without cleaner receive
-the existing one-time setup notice.
+The built-in reconnaissance role is now `explorer`, with no runtime `explore`
+alias. Config loading automatically renames the old key in `enabledAgents`,
+`agentModels`, and `agentThinkingLevels`, deduplicates an old/new pair, and persists
+the normalized file. When both model or thinking keys are valid, the explicit
+`explorer` value wins. Other configured non-empty names are preserved. A
+pre-existing explicit `enabledAgents` list is also still preserved without
+appending `cleaner`; configs without cleaner receive the existing one-time setup
+notice.
 
 ## Agent discovery and overrides
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "Controllable background sub-agent threads for pi: specialized roles, capability-aware thinking, direct main-model fallback, auto-fix chains, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -25,6 +25,13 @@ export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explorer", "worker",
 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";
+
+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];
@@ -156,25 +163,48 @@ 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 (disables all agents); otherwise keep valid names.
-		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
+		// 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())))];
 	}
 
 	if (isRecord(raw.agentModels)) {
-		for (const [key, value] of Object.entries(raw.agentModels)) {
-			if (isModelReference(value)) config.agentModels[key.trim()] = value.trim();
+		const entries = Object.entries(raw.agentModels);
+		// A valid explicit new key wins regardless of JSON property order.
+		for (const [rawKey, value] of entries) {
+			const key = rawKey.trim();
+			if (key !== LEGACY_EXPLORER_NAME && 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)) {
-		for (const [key, value] of Object.entries(raw.agentThinkingLevels)) {
+		const entries = Object.entries(raw.agentThinkingLevels);
+		for (const [rawKey, value] of entries) {
+			const key = rawKey.trim();
 			if (
+				key !== LEGACY_EXPLORER_NAME &&
 				typeof value === "string" &&
 				(THINKING_LEVEL_VALUES as readonly string[]).includes(value)
 			) {
-				config.agentThinkingLevels[key.trim()] = value as ThinkingLevel;
+				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") {