@ferris1225/pi-subagents 4.1.23 → 4.1.24

package/README.md

@@ -236,7 +236,9 @@ chain) renders as a tree: the parent line carries the workflow-wide token/cost
 totals and total elapsed, and every stage gets its own `├`/`└`-connected row
 with its own model, token flow, and elapsed — settled stages keep the
 telemetry frozen at settlement, the live stage shows its child's model and
-current activity:
+current activity. A live run renders two lines: what it is — agent, task,
+token flow, cost, provider/model, elapsed — and, dim under the label column,
+what it is doing right now:
 
 ```text
 ●    pi        subagent Implement the login redirect fix · openai/gpt-5/max · 12m06s
@@ -245,7 +247,8 @@ current activity:
   ├ ! review · ↑0.9k ↓6.0k R38.0k W0.9k $0.3300 · openai/gpt-5 · 1m12s
   ├ ● review fix — edit src/auth.ts · ↑0.2k ↓3.0k R12.0k $0.1200 · openai/gpt-5/medium · 41s
   └ ○ re-review
-● #15 explorer  src/models.ts — grep fallback · ↑1.2k ↓8.4k R31.0k W1.1k $0.0900 · openai/gpt-5-mini/low · 3m07s
+● #15 explorer  src/models.ts · ↑1.2k ↓8.4k R31.0k W1.1k $0.0900 · openai/gpt-5-mini · 3m07s
+                ↳ grep fallback
 ○ #23 worker    src/config.ts · repo lane
 ○ #24 worker ↻  tests/config.test.ts · queued · 5m02s
 ```
@@ -305,6 +308,7 @@ strength per agent. Everything else is config-file only, stored at
 ```json
 {
   "enabledAgents": ["explorer", "worker", "cleaner", "documenter", "synthesizer", "reviewer"],
+  "knownAgents": ["explorer", "worker", "cleaner", "documenter", "synthesizer", "reviewer"],
   "agentModels": { "explorer": "anthropic/claude-haiku-4-5" },
   "agentThinkingLevels": { "reviewer": "high" },
   "notifyOnReviewPass": false,
@@ -317,6 +321,7 @@ strength per agent. Everything else is config-file only, stored at
 | Field                 | Meaning                                                                           |
 | --------------------- | --------------------------------------------------------------------------------- |
 | `enabledAgents`       | Agents available for discovery and delegation. `[]` disables all.                 |
+| `knownAgents`         | Built-ins this config has seen; automatic bookkeeping — never edit it.            |
 | `agentModels`         | Optional `provider/model-id` per agent; missing = current main model.             |
 | `agentThinkingLevels` | Optional manual level per agent; missing = Auto.                                  |
 | `notifyOnReviewPass`  | Deliver a standalone passing gate without waking the main agent. Default `false`. |
@@ -331,6 +336,13 @@ start, model overrides pi no longer reports are removed with a one-time notice.
 pi's own session compaction fails mid-thread, a notice surfaces the error and the
 automatic retry instead of failing quietly.
 
+Agents shipped by a newer package version turn themselves on at the next
+session: a built-in the config has never seen is adopted into `enabledAgents`
+and follows explorer's configured model and thinking level — the fast lane
+these light roles need — while an agent you disabled stays disabled
+(`knownAgents` is what tells the two cases apart). Enabling a role in
+`/subagents-setup` adopts the same explorer route.
+
 ## Custom agents
 
 Built-ins ship with the package. Add or replace them with Markdown files:

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "@ferris1225/pi-subagents",
-  "version": "4.1.23",
-  "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",
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "pi-package",
-    "pi-extension",
-    "subagent",
-    "sub-agent",
-    "delegation",
-    "code-cleanup",
-    "dead-code"
-  ],
-  "files": [
-    "src",
-    "agents",
-    "README.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": [
-      "./src/index.ts"
-    ]
-  },
-  "scripts": {
-    "check": "tsc --noEmit",
-    "test": "vitest run tests",
-    "prepack": "npm run check && npm test"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.84.4",
-    "@earendil-works/pi-ai": ">=0.84.4",
-    "@earendil-works/pi-coding-agent": ">=0.84.4",
-    "@earendil-works/pi-tui": ">=0.84.4",
-    "typebox": "*"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.84.4",
-    "@earendil-works/pi-ai": "^0.84.4",
-    "@earendil-works/pi-coding-agent": "^0.84.4",
-    "@earendil-works/pi-tui": "^0.84.4",
-    "@types/node": "^22.10.0",
-    "typebox": "^1.3.9",
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.0"
-  },
-  "engines": {
-    "node": ">=22.19.0"
-  }
-}
+{
+  "name": "@ferris1225/pi-subagents",
+  "version": "4.1.24",
+  "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",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "subagent",
+    "sub-agent",
+    "delegation",
+    "code-cleanup",
+    "dead-code"
+  ],
+  "files": [
+    "src",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run tests",
+    "prepack": "npm run check && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": ">=0.84.4",
+    "@earendil-works/pi-ai": ">=0.84.4",
+    "@earendil-works/pi-coding-agent": ">=0.84.4",
+    "@earendil-works/pi-tui": ">=0.84.4",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.84.4",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^22.10.0",
+    "typebox": "^1.3.9",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/src/config.ts

@@ -47,6 +47,11 @@ 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. */
@@ -74,6 +79,7 @@ export interface SubagentsConfig {
 
 export const DEFAULT_CONFIG: SubagentsConfig = {
 	enabledAgents: [...DEFAULT_ENABLED_AGENTS],
+	knownAgents: [...BUILTIN_AGENT_NAMES],
 	agentModels: {},
 	agentThinkingLevels: {},
 	notifyOnReviewPass: false,
@@ -123,6 +129,20 @@ 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();
@@ -173,11 +193,39 @@ function defaultConfig(): SubagentsConfig {
 	};
 }
 
+/**
+ * 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.
+ * 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.
  */
 export async function loadConfig(configPath: string = getConfigPath()): Promise<SubagentsConfig> {
 	let text: string;
@@ -195,7 +243,7 @@ export async function loadConfig(configPath: string = getConfigPath()): Promise<
 		return defaultConfig();
 	}
 
-	const config = normalizeConfig(parsed);
+	const config = adoptNewBuiltins(normalizeConfig(parsed));
 
 	// Schema upgrade: persist the normalized shape when the file gained fields
 	// (new version) or dropped invalid ones.

package/src/monitor.ts

@@ -299,6 +299,17 @@ export function runLabel(task: string): string {
 		: `${takeGraphemes(chars, RUN_LABEL_MAX - 1)}${TASK_SUMMARY_ELLIPSIS}`;
 }
 
+/** Narrow an already-extracted run label to a smaller budget, keeping its
+ * tail: runLabel tail-weights path fragments because the filename is the
+ * recognisable part, and a second squeeze must not trade that tail away.
+ * Grapheme-safe. */
+export function shrinkRunLabel(text: string, maxWidth: number): string {
+	if (maxWidth <= 0) return "";
+	if (visibleWidth(text) <= maxWidth) return text;
+	const chars = [...graphemeSegmenter.segment(text)].map((s) => s.segment);
+	return `${TASK_SUMMARY_ELLIPSIS}${tailGraphemes(chars, maxWidth - 1)}`;
+}
+
 function formatTokens(count: number): string {
 	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
 	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;

package/src/recovery.ts

@@ -1,145 +1,145 @@
-/** Durable handoff for worktree integration/cleanup failures across sessions. */
-
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { stripVTControlCharacters } from "node:util";
-import type { WorktreeFinalization } from "./worktree.ts";
-
-export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
-const RECOVERY_MANIFEST_VERSION = 1;
-
-export interface RecoveryRecord {
-	runId: number;
-	createdAt: number;
-	integrated: boolean;
-	worktreePath?: string;
-	patchPath?: string;
-	error?: string;
-}
-
-interface RecoveryManifest {
-	version: number;
-	records: RecoveryRecord[];
-}
-
-export function getRecoveryManifestPath(configPath: string): string {
-	return join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
-}
-
-function normalizeRecord(value: unknown): RecoveryRecord | undefined {
-	if (!value || typeof value !== "object") return undefined;
-	const raw = value as Record<string, unknown>;
-	if (typeof raw.runId !== "number" || !Number.isInteger(raw.runId) || raw.runId < 1) return undefined;
-	if (typeof raw.createdAt !== "number" || !Number.isFinite(raw.createdAt)) return undefined;
-	return {
-		runId: raw.runId,
-		createdAt: raw.createdAt,
-		integrated: raw.integrated === true,
-		...(typeof raw.worktreePath === "string" && raw.worktreePath ? { worktreePath: raw.worktreePath } : {}),
-		...(typeof raw.patchPath === "string" && raw.patchPath ? { patchPath: raw.patchPath } : {}),
-		...(typeof raw.error === "string" && raw.error ? { error: raw.error } : {}),
-	};
-}
-
-export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
-	try {
-		const parsed = JSON.parse(await readFile(getRecoveryManifestPath(configPath), "utf8")) as {
-			records?: unknown;
-		};
-		if (!Array.isArray(parsed.records)) return [];
-		return parsed.records.flatMap((record) => {
-			const normalized = normalizeRecord(record);
-			return normalized ? [normalized] : [];
-		});
-	} catch {
-		return [];
-	}
-}
-
-function recoveryKey(record: RecoveryRecord): string {
-	return `${record.runId}\0${record.worktreePath ?? ""}\0${record.patchPath ?? ""}\0${record.error ?? ""}`;
-}
-
-async function writeManifest(path: string, records: readonly RecoveryRecord[]): Promise<void> {
-	if (records.length === 0) {
-		await rm(path, { force: true });
-		return;
-	}
-	await mkdir(dirname(path), { recursive: true });
-	const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-	try {
-		const manifest: RecoveryManifest = {
-			version: RECOVERY_MANIFEST_VERSION,
-			records: [...records],
-		};
-		await writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-		await rename(temporaryPath, path);
-	} finally {
-		await rm(temporaryPath, { force: true }).catch(() => undefined);
-	}
-}
-
-/** Merge retained artifacts into the durable manifest. */
-export async function persistRecoveryRecords(
-	configPath: string,
-	records: readonly RecoveryRecord[],
-): Promise<void> {
-	if (records.length === 0) return;
-	const path = getRecoveryManifestPath(configPath);
-	await withFileMutationQueue(path, async () => {
-		const merged = new Map<string, RecoveryRecord>();
-		for (const record of await readRecoveryRecords(configPath)) merged.set(recoveryKey(record), record);
-		for (const record of records) merged.set(recoveryKey(record), record);
-		await writeManifest(path, [...merged.values()]);
-	});
-}
-
-export function recoveryRecordFromFinalization(
-	runId: number,
-	finalization: WorktreeFinalization,
-	now = Date.now(),
-): RecoveryRecord {
-	return {
-		runId,
-		createdAt: now,
-		integrated: finalization.integrated,
-		...(finalization.worktreePath ? { worktreePath: finalization.worktreePath } : {}),
-		...(finalization.patchPath ? { patchPath: finalization.patchPath } : {}),
-		...(finalization.error ? { error: finalization.error } : {}),
-	};
-}
-
-/** Show retained recovery paths on every later session start until the user
- * removes the artifacts. Stale records are pruned automatically. */
-export async function announceRecoveryRecords(
-	configPath: string,
-	ctx: {
-		hasUI?: boolean;
-		ui: { notify(message: string, kind: "info" | "warning" | "error"): void };
-	},
-): Promise<void> {
-	if (ctx.hasUI === false) return;
-	const records = await readRecoveryRecords(configPath);
-	if (records.length === 0) return;
-	const live = records.filter((record) =>
-		(record.worktreePath ? existsSync(record.worktreePath) : false) ||
-		(record.patchPath ? existsSync(record.patchPath) : false),
-	);
-	if (live.length !== records.length) {
-		const path = getRecoveryManifestPath(configPath);
-		await withFileMutationQueue(path, () => writeManifest(path, live)).catch(() => undefined);
-	}
-	for (const record of live) {
-		const paths = [
-			record.worktreePath ? `worktree ${stripVTControlCharacters(record.worktreePath)}` : undefined,
-			record.patchPath ? `patch ${stripVTControlCharacters(record.patchPath)}` : undefined,
-		].filter(Boolean).join(" · ");
-		const reason = record.error ? ` · ${stripVTControlCharacters(record.error)}` : "";
-		ctx.ui.notify(
-			`pi-subagents recovery for run #${record.runId}: ${record.integrated ? "changes were applied but cleanup failed" : "integration failed"}${paths ? ` · retained ${paths}` : ""}${reason}`,
-			"error",
-		);
-	}
-}
+/** Durable handoff for worktree integration/cleanup failures across sessions. */
+
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import type { WorktreeFinalization } from "./worktree.ts";
+
+export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
+const RECOVERY_MANIFEST_VERSION = 1;
+
+export interface RecoveryRecord {
+	runId: number;
+	createdAt: number;
+	integrated: boolean;
+	worktreePath?: string;
+	patchPath?: string;
+	error?: string;
+}
+
+interface RecoveryManifest {
+	version: number;
+	records: RecoveryRecord[];
+}
+
+export function getRecoveryManifestPath(configPath: string): string {
+	return join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
+}
+
+function normalizeRecord(value: unknown): RecoveryRecord | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (typeof raw.runId !== "number" || !Number.isInteger(raw.runId) || raw.runId < 1) return undefined;
+	if (typeof raw.createdAt !== "number" || !Number.isFinite(raw.createdAt)) return undefined;
+	return {
+		runId: raw.runId,
+		createdAt: raw.createdAt,
+		integrated: raw.integrated === true,
+		...(typeof raw.worktreePath === "string" && raw.worktreePath ? { worktreePath: raw.worktreePath } : {}),
+		...(typeof raw.patchPath === "string" && raw.patchPath ? { patchPath: raw.patchPath } : {}),
+		...(typeof raw.error === "string" && raw.error ? { error: raw.error } : {}),
+	};
+}
+
+export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
+	try {
+		const parsed = JSON.parse(await readFile(getRecoveryManifestPath(configPath), "utf8")) as {
+			records?: unknown;
+		};
+		if (!Array.isArray(parsed.records)) return [];
+		return parsed.records.flatMap((record) => {
+			const normalized = normalizeRecord(record);
+			return normalized ? [normalized] : [];
+		});
+	} catch {
+		return [];
+	}
+}
+
+function recoveryKey(record: RecoveryRecord): string {
+	return `${record.runId}\0${record.worktreePath ?? ""}\0${record.patchPath ?? ""}\0${record.error ?? ""}`;
+}
+
+async function writeManifest(path: string, records: readonly RecoveryRecord[]): Promise<void> {
+	if (records.length === 0) {
+		await rm(path, { force: true });
+		return;
+	}
+	await mkdir(dirname(path), { recursive: true });
+	const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		const manifest: RecoveryManifest = {
+			version: RECOVERY_MANIFEST_VERSION,
+			records: [...records],
+		};
+		await writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+		await rename(temporaryPath, path);
+	} finally {
+		await rm(temporaryPath, { force: true }).catch(() => undefined);
+	}
+}
+
+/** Merge retained artifacts into the durable manifest. */
+export async function persistRecoveryRecords(
+	configPath: string,
+	records: readonly RecoveryRecord[],
+): Promise<void> {
+	if (records.length === 0) return;
+	const path = getRecoveryManifestPath(configPath);
+	await withFileMutationQueue(path, async () => {
+		const merged = new Map<string, RecoveryRecord>();
+		for (const record of await readRecoveryRecords(configPath)) merged.set(recoveryKey(record), record);
+		for (const record of records) merged.set(recoveryKey(record), record);
+		await writeManifest(path, [...merged.values()]);
+	});
+}
+
+export function recoveryRecordFromFinalization(
+	runId: number,
+	finalization: WorktreeFinalization,
+	now = Date.now(),
+): RecoveryRecord {
+	return {
+		runId,
+		createdAt: now,
+		integrated: finalization.integrated,
+		...(finalization.worktreePath ? { worktreePath: finalization.worktreePath } : {}),
+		...(finalization.patchPath ? { patchPath: finalization.patchPath } : {}),
+		...(finalization.error ? { error: finalization.error } : {}),
+	};
+}
+
+/** Show retained recovery paths on every later session start until the user
+ * removes the artifacts. Stale records are pruned automatically. */
+export async function announceRecoveryRecords(
+	configPath: string,
+	ctx: {
+		hasUI?: boolean;
+		ui: { notify(message: string, kind: "info" | "warning" | "error"): void };
+	},
+): Promise<void> {
+	if (ctx.hasUI === false) return;
+	const records = await readRecoveryRecords(configPath);
+	if (records.length === 0) return;
+	const live = records.filter((record) =>
+		(record.worktreePath ? existsSync(record.worktreePath) : false) ||
+		(record.patchPath ? existsSync(record.patchPath) : false),
+	);
+	if (live.length !== records.length) {
+		const path = getRecoveryManifestPath(configPath);
+		await withFileMutationQueue(path, () => writeManifest(path, live)).catch(() => undefined);
+	}
+	for (const record of live) {
+		const paths = [
+			record.worktreePath ? `worktree ${stripVTControlCharacters(record.worktreePath)}` : undefined,
+			record.patchPath ? `patch ${stripVTControlCharacters(record.patchPath)}` : undefined,
+		].filter(Boolean).join(" · ");
+		const reason = record.error ? ` · ${stripVTControlCharacters(record.error)}` : "";
+		ctx.ui.notify(
+			`pi-subagents recovery for run #${record.runId}: ${record.integrated ? "changes were applied but cleanup failed" : "integration failed"}${paths ? ` · retained ${paths}` : ""}${reason}`,
+			"error",
+		);
+	}
+}