@juicesharp/rpiv-pi 0.12.2 → 0.12.4

package/extensions/subagent-widget/agent-catalog.test.ts

@@ -0,0 +1,110 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { parse as parseYaml } from "yaml";
+import { AGENT_CATALOG, buildAgentEnumDescription } from "./agent-catalog.js";
+import { RPIV_SPECIALISTS } from "./hide-builtin-subagents.js";
+
+const AGENTS_DIR = fileURLToPath(new URL("../../agents/", import.meta.url));
+
+function readFrontmatterDescription(name: string): string {
+	const content = readFileSync(join(AGENTS_DIR, `${name}.md`), "utf8");
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) throw new Error(`${name}.md has no frontmatter`);
+	const fm = parseYaml(match[1]) as Record<string, unknown>;
+	return fm.description as string;
+}
+
+describe("AGENT_CATALOG — frontmatter-sourced per-agent descriptions", () => {
+	it("contains exactly one entry per RPIV_SPECIALISTS name, in declaration order", () => {
+		expect(AGENT_CATALOG.map((e) => e.name)).toEqual([...RPIV_SPECIALISTS]);
+	});
+
+	it("every entry has a non-empty description string", () => {
+		for (const entry of AGENT_CATALOG) {
+			expect(typeof entry.description).toBe("string");
+			expect(entry.description.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("each entry's description is a byte-for-byte mirror of the agents/<name>.md frontmatter", () => {
+		// Hard invariant: no trimming, no truncation, no transformation — the
+		// value the LLM sees is exactly the value authored in the .md file.
+		for (const entry of AGENT_CATALOG) {
+			expect(entry.description).toBe(readFrontmatterDescription(entry.name));
+		}
+	});
+});
+
+describe("AGENTS_DIR resolution — cross-platform URL walk via fileURLToPath(new URL(...))", () => {
+	// WHATWG URL resolution is OS-agnostic: `new URL("../../agents/", base)` uses
+	// forward-slash URL semantics regardless of what OS the test runs on. We can
+	// therefore simulate POSIX, Windows, and Windows-UNC base URLs from any host
+	// platform and assert the resolved URL is correct — no actual file I/O, no
+	// need for a Windows CI runner to catch URL-walk bugs.
+	const MODULE_REL = "/packages/rpiv-pi/extensions/subagent-widget/agent-catalog.ts";
+
+	it("POSIX base: resolves to the rpiv-pi/agents/ directory URL", () => {
+		const base = `file:///Users/alice/repo${MODULE_REL}`;
+		const resolved = new URL("../../agents/", base);
+		expect(resolved.href).toBe("file:///Users/alice/repo/packages/rpiv-pi/agents/");
+	});
+
+	it("Windows drive-letter base: resolves preserving the C: drive and backslash-free URL form", () => {
+		const base = `file:///C:/Users/alice/repo${MODULE_REL}`;
+		const resolved = new URL("../../agents/", base);
+		expect(resolved.href).toBe("file:///C:/Users/alice/repo/packages/rpiv-pi/agents/");
+	});
+
+	it("Windows UNC share base: preserves the //server/share/ authority across the relative walk", () => {
+		const base = `file:////server/share/repo${MODULE_REL}`;
+		const resolved = new URL("../../agents/", base);
+		// WHATWG keeps the empty-host + path-with-leading-// form of UNC file URLs;
+		// Node's fileURLToPath on Windows later converts this to \\server\share\... .
+		expect(resolved.href).toBe("file:////server/share/repo/packages/rpiv-pi/agents/");
+	});
+
+	it("URL-encoded characters in the path (space, %20): round-trip through fileURLToPath correctly", () => {
+		// Typical hazard: installing under a path with a space (e.g. "Program Files").
+		// import.meta.url encodes the space as %20; fileURLToPath decodes it back.
+		const base = `file:///Users/alice/Program%20Files/repo${MODULE_REL}`;
+		const resolved = new URL("../../agents/", base);
+		expect(resolved.href).toBe("file:///Users/alice/Program%20Files/repo/packages/rpiv-pi/agents/");
+		// fileURLToPath decodes %20 back to a literal space in the filesystem path.
+		const fsPath = fileURLToPath(resolved);
+		expect(fsPath).toContain("Program Files");
+		expect(fsPath).not.toContain("%20");
+	});
+
+	it("current-platform sanity: AGENTS_DIR points at a real directory containing the specialists", () => {
+		// Closes the loop — the URL walk is correct on this runner AND the
+		// resulting path is a real dir that readFileSync can subsequently read.
+		const stat = statSync(AGENTS_DIR);
+		expect(stat.isDirectory()).toBe(true);
+		for (const name of RPIV_SPECIALISTS) {
+			const entryStat = statSync(join(AGENTS_DIR, `${name}.md`));
+			expect(entryStat.isFile()).toBe(true);
+		}
+	});
+});
+
+describe("buildAgentEnumDescription — flattens catalog into an LLM-facing bullet list", () => {
+	const text = buildAgentEnumDescription();
+
+	it("starts with a contextual header line before the bullet list", () => {
+		expect(text.split("\n")[0]).toBe("Agent name (SINGLE mode) or target for management get/update/delete. Options:");
+	});
+
+	it("emits one '- <name>: <description>' bullet per specialist", () => {
+		for (const entry of AGENT_CATALOG) {
+			expect(text).toContain(`- ${entry.name}: ${entry.description}`);
+		}
+	});
+
+	it("orders bullets by RPIV_SPECIALISTS declaration order", () => {
+		const bullets = text.split("\n").slice(1);
+		const names = bullets.map((line) => line.replace(/^- /, "").split(":")[0]);
+		expect(names).toEqual([...RPIV_SPECIALISTS]);
+	});
+});

package/extensions/subagent-widget/agent-catalog.ts

@@ -0,0 +1,58 @@
+// Loads per-agent descriptions from packages/rpiv-pi/agents/<name>.md YAML
+// frontmatter so the `agent` tool parameter can carry a rich enum-with-table
+// description instead of duplicating copy across the monorepo. Runs once at
+// module init; crashes loudly if an expected agent file is missing.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { RPIV_SPECIALISTS } from "./hide-builtin-subagents.js";
+
+// extensions/subagent-widget/agent-catalog.ts → packages/rpiv-pi/agents/
+// URL form matches the monorepo idiom (see root guidance: prompts loaded via
+// `fileURLToPath(new URL("./prompts/…", import.meta.url))`) and cross-platform
+// safely handles both POSIX and Windows file URLs.
+const AGENTS_DIR = fileURLToPath(new URL("../../agents/", import.meta.url));
+
+// Splits a markdown file on its leading `---` frontmatter fences and parses
+// the YAML block. Returns undefined when no frontmatter is present.
+function extractFrontmatter(content: string): Record<string, unknown> | undefined {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) return undefined;
+	const parsed = parseYaml(match[1]) as unknown;
+	if (typeof parsed !== "object" || parsed === null) return undefined;
+	return parsed as Record<string, unknown>;
+}
+
+export interface AgentCatalogEntry {
+	readonly name: string;
+	readonly description: string;
+}
+
+function loadAgentEntry(name: string): AgentCatalogEntry {
+	const path = join(AGENTS_DIR, `${name}.md`);
+	const content = readFileSync(path, "utf8");
+	const fm = extractFrontmatter(content);
+	if (!fm) throw new Error(`agent-catalog: ${name}.md has no YAML frontmatter`);
+	const description = fm.description;
+	if (typeof description !== "string" || description.length === 0) {
+		throw new Error(`agent-catalog: ${name}.md frontmatter is missing a string 'description'`);
+	}
+	return { name, description };
+}
+
+// Eager load at module init: one readFileSync per specialist. Failure modes
+// (missing file, missing description) fail Pi's boot rather than surfacing as
+// a runtime tool-registration error — consistent with rpiv-todo / rpiv-advisor
+// loading their prompts at module init.
+export const AGENT_CATALOG: ReadonlyArray<AgentCatalogEntry> = RPIV_SPECIALISTS.map(loadAgentEntry);
+
+// Flattens the catalog into the LLM-facing string used as the `agent` param's
+// `description`. Format: header line + "- <name>: <desc>" bullets. Keeps the
+// list parameter-adjacent so the LLM sees agent capabilities inline with the
+// enum choice instead of having to cross-reference a separate doc.
+export function buildAgentEnumDescription(): string {
+	const bullets = AGENT_CATALOG.map((entry) => `- ${entry.name}: ${entry.description}`).join("\n");
+	return `Agent name (SINGLE mode) or target for management get/update/delete. Options:\n${bullets}`;
+}

package/extensions/subagent-widget/catalog-drift.test.ts

@@ -0,0 +1,21 @@
+import { readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { RPIV_SPECIALISTS } from "./hide-builtin-subagents.js";
+
+const AGENTS_DIR = fileURLToPath(new URL("../../agents/", import.meta.url));
+
+function discoverAgentStems(): string[] {
+	return readdirSync(AGENTS_DIR)
+		.filter((name) => name.endsWith(".md"))
+		.map((name) => name.slice(0, -".md".length))
+		.sort();
+}
+
+describe("RPIV_SPECIALISTS catalog drift guard", () => {
+	it("matches the bundled packages/rpiv-pi/agents/*.md filenames", () => {
+		const onDisk = discoverAgentStems();
+		const declared = [...RPIV_SPECIALISTS].sort();
+		expect(declared).toEqual(onDisk);
+	});
+});

package/extensions/subagent-widget/constants.ts

@@ -16,11 +16,19 @@ export const ERROR_STATUSES: ReadonlySet<ErrorStatus> = new Set<ErrorStatus>([
 	"stopped",
 ]);
 
-/** How many turns a completed run lingers before it drops from the tree. */
-export const COMPLETED_LINGER_TURNS = 1;
+/** How many turns a completed run lingers before it drops from the tree.
+ * Advanced by both user-input boundaries (`pi.on("input")`) and orchestrator
+ * agent-loop iterations (`pi.on("turn_start")`), so completed runs stay visible
+ * for ~3 orchestrator turns after the last agent finishes, then auto-evict. */
+export const COMPLETED_LINGER_TURNS = 3;
 
 /** How many turns an error/aborted/steered/stopped run lingers. */
-export const ERROR_LINGER_TURNS = 2;
+export const ERROR_LINGER_TURNS = 5;
 
 /** Spinner animation tick in ms. TUI's 16 ms render coalescing absorbs this. */
 export const TICK_MS = 80;
+
+/** Max visible characters of the descriptor column (task text). Applied
+ * identically to running + finished rows so the stats tail is never
+ * truncation-clipped off the right edge regardless of terminal width. */
+export const MAX_DESCRIPTOR_CHARS = 40;

package/extensions/subagent-widget/hide-builtin-subagents.test.ts

@@ -0,0 +1,218 @@
+import { Type } from "@sinclair/typebox";
+import { describe, expect, it } from "vitest";
+import {
+	filterDisabledFromListResult,
+	getCuratedSubagentDescription,
+	LIST_FILTER_SNAPSHOT_FRAGMENT,
+	PI_SUBAGENTS_BUILTINS,
+	RPIV_SPECIALISTS,
+	rewriteSubagentParameters,
+} from "./hide-builtin-subagents.js";
+
+// Mirrors pi-subagents@0.17.5/index.ts:311-336 verbatim. This fixture is no
+// longer used to exercise a rewriter (we replace upstream wholesale), but the
+// upstream-snapshot drift guard below fails when these literals diverge — a
+// signal to re-review prompts/subagent-description.txt against upstream.
+const PI_SUBAGENTS_UPSTREAM_DESCRIPTION = `Delegate to subagents or manage agent definitions.
+
+EXECUTION (use exactly ONE mode):
+• SINGLE: { agent, task } - one task
+• CHAIN: { chain: [{agent:"scout"}, {parallel:[{agent:"worker",count:3}]}] } - sequential pipeline with optional parallel fan-out
+• PARALLEL: { tasks: [{agent,task,count?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
+• Optional context: { context: "fresh" | "fork" } (default: "fresh")
+
+CHAIN TEMPLATE VARIABLES (use in task strings):
+• {task} - The original task/request from the user
+• {previous} - Text response from the previous step (empty for first step)
+• {chain_dir} - Shared directory for chain files (e.g., <tmpdir>/pi-subagents-<scope>/chain-runs/abc123/)
+
+Example: { chain: [{agent:"scout", task:"Analyze {task}"}, {agent:"planner", task:"Plan based on {previous}"}] }
+
+MANAGEMENT (use action field, omit agent/task/chain/tasks):
+• { action: "list" } - discover agents/chains
+• { action: "get", agent: "name" } - full detail
+• { action: "create", config: { name, systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, ... } }
+• { action: "update", agent: "name", config: { ... } } - merge
+• { action: "delete", agent: "name" }
+• Use chainName for chain operations
+
+CONTROL:
+• { action: "status", id: "..." } - inspect an async/background run by id or prefix
+• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused`;
+
+describe("getCuratedSubagentDescription — file-loaded replacement for upstream's literal", () => {
+	const curated = getCuratedSubagentDescription();
+
+	it("contains no builtin agent names — leak invariant over prompts/subagent-description.txt", () => {
+		for (const name of PI_SUBAGENTS_BUILTINS) {
+			expect(curated).not.toContain(`"${name}"`);
+			expect(curated).not.toContain(`:"${name}"`);
+		}
+	});
+
+	it("preserves the mode and action section headers the LLM anchors on", () => {
+		expect(curated).toContain("EXECUTION");
+		expect(curated).toContain("CHAIN TEMPLATE VARIABLES");
+		expect(curated).toContain("MANAGEMENT");
+		expect(curated).toContain("CONTROL");
+		expect(curated).toContain("• SINGLE: { agent, task }");
+		expect(curated).toContain("• PARALLEL:");
+		expect(curated).toContain(`{ action: "list" }`);
+		expect(curated).toContain(`{ action: "status", id: "..." }`);
+	});
+
+	it("is non-empty and trimmed (no trailing whitespace from readFileSync)", () => {
+		expect(curated.length).toBeGreaterThan(0);
+		expect(curated).toBe(curated.trimEnd());
+	});
+
+	it("upstream drift guard: fails when pi-subagents' literal diverges from the pinned snapshot", () => {
+		// The snapshot is pinned to pi-subagents@0.17.5/index.ts:311-336. If
+		// upstream adds/edits sections, this fails FIRST — prompting a human
+		// review of prompts/subagent-description.txt. We deliberately do NOT
+		// compare curated to upstream (they're allowed to diverge); we only
+		// verify the snapshot remains a faithful record of what we forked from.
+		expect(PI_SUBAGENTS_UPSTREAM_DESCRIPTION).toContain("Delegate to subagents or manage agent definitions.");
+		expect(PI_SUBAGENTS_UPSTREAM_DESCRIPTION).toContain(
+			`{ chain: [{agent:"scout"}, {parallel:[{agent:"worker",count:3}]}] }`,
+		);
+		expect(PI_SUBAGENTS_UPSTREAM_DESCRIPTION).toContain(
+			`Example: { chain: [{agent:"scout", task:"Analyze {task}"}, {agent:"planner", task:"Plan based on {previous}"}] }`,
+		);
+	});
+});
+
+describe("rewriteSubagentParameters — pin top-level agent to RPIV_SPECIALISTS enum + injected description", () => {
+	const original = Type.Object({
+		agent: Type.Optional(Type.String({ description: "orig agent description" })),
+		task: Type.Optional(Type.String({ description: "task" })),
+		tasks: Type.Optional(Type.Array(Type.Object({ agent: Type.String(), task: Type.String() }))),
+	});
+
+	const stubAgentDescription = "stub agent description (injected)";
+
+	it("re-types the agent field to an optional string enum of RPIV_SPECIALISTS", () => {
+		const rewritten = rewriteSubagentParameters(original, stubAgentDescription) as unknown as {
+			properties: { agent: { type: string; enum: string[]; description: string } };
+		};
+		const agent = rewritten.properties.agent;
+		expect(agent.type).toBe("string");
+		expect(agent.enum).toEqual([...RPIV_SPECIALISTS]);
+	});
+
+	it("carries the injected description verbatim onto the agent field", () => {
+		const rewritten = rewriteSubagentParameters(original, stubAgentDescription) as unknown as {
+			properties: { agent: { description: string } };
+		};
+		expect(rewritten.properties.agent.description).toBe(stubAgentDescription);
+	});
+
+	it("preserves all other top-level properties unchanged by reference", () => {
+		const rewritten = rewriteSubagentParameters(original, stubAgentDescription) as unknown as {
+			properties: { task: unknown; tasks: unknown };
+		};
+		expect(rewritten.properties.task).toBe(original.properties.task);
+		expect(rewritten.properties.tasks).toBe(original.properties.tasks);
+	});
+
+	it("preserves Type.Optional modifier on sibling fields (TypeBox symbol carried via reference spread)", () => {
+		const schema = Type.Object({
+			agent: Type.Optional(Type.String()),
+			task: Type.Optional(Type.String()),
+		});
+		const rewritten = rewriteSubagentParameters(schema, stubAgentDescription);
+		const optionalKey = Object.getOwnPropertySymbols(schema.properties.task).find(
+			(s) => s.description === "TypeBox.Optional",
+		);
+		expect(optionalKey).toBeDefined();
+		const preservedFlag = (rewritten as typeof schema).properties.task[
+			optionalKey as keyof typeof schema.properties.task
+		];
+		expect(preservedFlag).toBe("Optional");
+	});
+
+	it("does not mutate the input schema", () => {
+		const snapshot = JSON.stringify(original);
+		rewriteSubagentParameters(original, stubAgentDescription);
+		expect(JSON.stringify(original)).toBe(snapshot);
+	});
+
+	it("returns input unchanged when it is not a TypeBox object schema (defensive fallback)", () => {
+		const notASchema = { foo: "bar" } as unknown;
+		expect(rewriteSubagentParameters(notASchema, stubAgentDescription)).toBe(notASchema);
+		expect(rewriteSubagentParameters(undefined, stubAgentDescription)).toBe(undefined);
+	});
+});
+
+// Mirrors the `- <name> (<source>, disabled): <desc>` row format emitted by
+// pi-subagents@0.17.5/agent-management.ts:375 (`handleList`). If upstream
+// shifts the literal, the drift guard below fails first — pointing at
+// LIST_FILTER_SNAPSHOT_FRAGMENT in hide-builtin-subagents.ts.
+const PI_SUBAGENTS_LIST_OUTPUT = `Agents:
+- claim-verifier (project): Adversarial finding verifier. …
+- codebase-analyzer (project): Analyzes codebase implementation details. …
+- context-builder (builtin, disabled): Analyzes requirements and codebase, generates context and meta-prompt
+- delegate (builtin, disabled): Lightweight subagent that inherits the parent model with no default reads
+- general-purpose (project): General-purpose agent for researching complex questions …
+- oracle (builtin, disabled): High-context decision-consistency oracle that protects inherited state and prevents drift
+- oracle-executor (builtin, disabled): High-context implementation agent that executes only after main-agent approval
+- planner (builtin, disabled): Creates implementation plans from context and requirements
+- researcher (builtin, disabled): Autonomous web researcher …
+- reviewer (builtin, disabled): Code review specialist that validates implementation and fixes issues
+- scout (builtin, disabled): Fast codebase recon that returns compressed context for handoff
+- thoughts-locator (project): Discovers relevant documents in thoughts/ directory …
+- worker (builtin, disabled): General-purpose subagent with full capabilities
+
+Chains:
+- (none)`;
+
+describe("filterDisabledFromListResult — strip disabled builtin rows from handleList output", () => {
+	it("drift guard: handleList still emits the '(builtin, disabled)' suffix somewhere in the snapshot", () => {
+		expect(PI_SUBAGENTS_LIST_OUTPUT).toContain(LIST_FILTER_SNAPSHOT_FRAGMENT);
+	});
+
+	it("removes every row tagged '(builtin, disabled)' — leak invariant over all 9 builtins", () => {
+		const filtered = filterDisabledFromListResult(PI_SUBAGENTS_LIST_OUTPUT) as string;
+		for (const name of PI_SUBAGENTS_BUILTINS) {
+			expect(filtered).not.toContain(`- ${name} (builtin, disabled)`);
+		}
+		expect(filtered).not.toMatch(/, disabled\)/);
+	});
+
+	it("preserves non-disabled project rows and the Chains section verbatim", () => {
+		const filtered = filterDisabledFromListResult(PI_SUBAGENTS_LIST_OUTPUT) as string;
+		expect(filtered).toContain("- claim-verifier (project):");
+		expect(filtered).toContain("- codebase-analyzer (project):");
+		expect(filtered).toContain("- general-purpose (project):");
+		expect(filtered).toContain("- thoughts-locator (project):");
+		expect(filtered).toContain("Chains:");
+		expect(filtered).toContain("- (none)");
+	});
+
+	it("keeps the Agents: header and blank-line-before-Chains even when every builtin is removed", () => {
+		const filtered = filterDisabledFromListResult(PI_SUBAGENTS_LIST_OUTPUT) as string;
+		expect(filtered.startsWith("Agents:\n")).toBe(true);
+		expect(filtered).toMatch(/\n\nChains:/);
+	});
+
+	it("consumes trailing newline on each removed row (no accumulated blank lines)", () => {
+		const minimal = "Agents:\n- scout (builtin, disabled): a\n- foo (project): b\n\nChains:\n- (none)";
+		const filtered = filterDisabledFromListResult(minimal) as string;
+		expect(filtered).toBe("Agents:\n- foo (project): b\n\nChains:\n- (none)");
+	});
+
+	it("handles a disabled row at EOF (no trailing newline) without leaving it behind", () => {
+		const endEdge = "Agents:\n- foo (project): b\n- scout (builtin, disabled): a";
+		const filtered = filterDisabledFromListResult(endEdge) as string;
+		expect(filtered).toBe("Agents:\n- foo (project): b\n");
+	});
+
+	it("is a no-op on inputs that contain no disabled-tagged rows", () => {
+		const userOnly = "Agents:\n- claim-verifier (project): x\n\nChains:\n- (none)";
+		expect(filterDisabledFromListResult(userOnly)).toBe(userOnly);
+	});
+
+	it("passes undefined through unchanged", () => {
+		expect(filterDisabledFromListResult(undefined)).toBe(undefined);
+	});
+});

package/extensions/subagent-widget/hide-builtin-subagents.ts

@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { type TSchema, Type } from "@sinclair/typebox";
+
+export const RPIV_SPECIALISTS = [
+	"claim-verifier",
+	"codebase-analyzer",
+	"codebase-locator",
+	"codebase-pattern-finder",
+	"diff-auditor",
+	"general-purpose",
+	"integration-scanner",
+	"peer-comparator",
+	"precedent-locator",
+	"test-case-locator",
+	"thoughts-analyzer",
+	"thoughts-locator",
+	"web-search-researcher",
+] as const;
+
+export const PI_SUBAGENTS_BUILTINS = [
+	"scout",
+	"planner",
+	"worker",
+	"reviewer",
+	"context-builder",
+	"researcher",
+	"delegate",
+	"oracle",
+	"oracle-executor",
+] as const;
+
+const AGENT_ENUM: string[] = [...RPIV_SPECIALISTS];
+
+// Curated tool description loaded once at module init — replaces upstream's
+// literal wholesale instead of regex-editing it. Avoids the drift-fragility of
+// matching template-literal fragments; we own every byte the LLM sees.
+const CURATED_TOOL_DESCRIPTION = readFileSync(
+	fileURLToPath(new URL("./prompts/subagent-description.txt", import.meta.url)),
+	"utf8",
+).trimEnd();
+
+export function getCuratedSubagentDescription(): string {
+	return CURATED_TOOL_DESCRIPTION;
+}
+
+interface TypeBoxObject {
+	properties: Record<string, TSchema>;
+}
+
+function isTypeBoxObject(schema: unknown): schema is TypeBoxObject {
+	return typeof schema === "object" && schema !== null && "properties" in schema;
+}
+
+// Rebuild via Type.Object (not shallow spread) so TypeBox regenerates the
+// Symbol-keyed kind markers + compiler hooks that a plain clone would drop.
+// agentEnumDescription is injected (not imported directly) to keep this module
+// free of the agent-catalog's fs side-effect at load time — test-only callers
+// can substitute a stub.
+export function rewriteSubagentParameters<T>(original: T, agentEnumDescription: string): T {
+	if (!isTypeBoxObject(original)) return original;
+	const rebuilt = Type.Object({
+		...original.properties,
+		agent: Type.Optional(Type.String({ enum: AGENT_ENUM, description: agentEnumDescription })),
+	});
+	return rebuilt as unknown as T;
+}
+
+// Matches a single "- <name> (<source>, disabled): <desc>" row as produced by
+// handleList in pi-subagents@0.17.5/agent-management.ts:375. The `(builtin,
+// disabled)` suffix is the load-bearing literal — source="user" / "project"
+// rows never carry the ", disabled" tag, so this regex is safe to apply to the
+// full text block without parsing sections. The `.*(?:\r?\n|$)` trailing group
+// consumes the row's newline so removed rows don't leave blank lines behind,
+// with an alternation for the EOF case (no trailing newline).
+const DISABLED_ROW_REGEX = /^- .+ \([^)]+, disabled\): .*(?:\r?\n|$)/gm;
+
+// Drift guard anchor — the exact literal suffix handleList interpolates when
+// an agent is disabled. If upstream renames the tag (e.g. "(builtin, off)"),
+// the test fixture fails BEFORE the filter's behavioural test, pinpointing
+// the stale literal instead of reporting an empty match.
+export const LIST_FILTER_SNAPSHOT_FRAGMENT = ", disabled): ";
+
+export function filterDisabledFromListResult(text: string | undefined): string | undefined {
+	if (text === undefined) return undefined;
+	return text.replace(DISABLED_ROW_REGEX, "");
+}

package/extensions/subagent-widget/index.test.ts

@@ -213,12 +213,13 @@ describe("subagent-widget extension factory", () => {
 		expect(listRuns()).toHaveLength(0);
 	});
 
-	it("input evicts lingering finished runs on the next user turn", async () => {
+	it("input + turn_start both advance linger ages; evicts after COMPLETED_LINGER_TURNS boundaries", async () => {
 		const pi = makePi();
 		await initExtension(pi);
 		const startHandler = pi.handlers.get("tool_execution_start")!;
 		const endHandler = pi.handlers.get("tool_execution_end")!;
 		const inputHandler = pi.handlers.get("input")!;
+		const turnStartHandler = pi.handlers.get("turn_start")!;
 		await startHandler(
 			{
 				type: "tool_execution_start",
@@ -239,7 +240,52 @@ describe("subagent-widget extension factory", () => {
 			makeCtx(true),
 		);
 		expect(listRuns()).toHaveLength(1);
-		await inputHandler({ type: "input", text: "next", source: "interactive" } as any, makeCtx(true));
+		// COMPLETED_LINGER_TURNS = 3 — takes 3 turn boundaries to evict.
+		await turnStartHandler({ type: "turn_start" } as any, makeCtx(true)); // age 1
+		await turnStartHandler({ type: "turn_start" } as any, makeCtx(true)); // age 2
+		expect(listRuns()).toHaveLength(1);
+		await inputHandler({ type: "input", text: "next", source: "interactive" } as any, makeCtx(true)); // age 3 → evicted
 		expect(listRuns()).toHaveLength(0);
 	});
+
+	it("purges finished runs when a new wave starts (tool_execution_start with no active runs)", async () => {
+		const pi = makePi();
+		await initExtension(pi);
+		const startHandler = pi.handlers.get("tool_execution_start")!;
+		const endHandler = pi.handlers.get("tool_execution_end")!;
+		// Wave 1: dispatch + complete.
+		await startHandler(
+			{
+				type: "tool_execution_start",
+				toolCallId: "t1",
+				toolName: "subagent",
+				args: { agent: "scout", task: "x" },
+			},
+			makeCtx(true),
+		);
+		await endHandler(
+			{
+				type: "tool_execution_end",
+				toolCallId: "t1",
+				toolName: "subagent",
+				result: { details: { mode: "single", agentScope: "user", projectAgentsDir: null, results: [] } },
+				isError: false,
+			},
+			makeCtx(true),
+		);
+		expect(listRuns()).toHaveLength(1);
+		// Wave 2: new dispatch while wave 1 is still lingering → wave 1 purged first.
+		await startHandler(
+			{
+				type: "tool_execution_start",
+				toolCallId: "t2",
+				toolName: "subagent",
+				args: { agent: "worker", task: "y" },
+			},
+			makeCtx(true),
+		);
+		const runs = listRuns();
+		expect(runs).toHaveLength(1);
+		expect(runs[0].toolCallId).toBe("t2");
+	});
 });

package/extensions/subagent-widget/index.ts

@@ -49,15 +49,20 @@ export default async function (pi: ExtensionAPI) {
 		tracker.__resetState();
 	});
 
-	// User-turn boundary: advance linger ages on user input, NOT on "turn_start".
-	// Pi fires turn_start per agent-loop iteration (after each tool result,
-	// before the next assistant call), which would evict completed runs
-	// before the user sees them. "input" fires only on user-originated
-	// messages — the correct semantics for "persists until next user turn".
-	pi.on("input", async () => {
+	// Turn-boundary eviction: advance linger ages on BOTH user input and
+	// orchestrator agent-loop iterations. `input` fires on user-originated
+	// messages; `turn_start` fires per agent-loop iteration (after each tool
+	// result, before the next assistant call). Together with the bumped
+	// `COMPLETED_LINGER_TURNS=3` budget in constants.ts, completed rows stay
+	// visible long enough for the user to see, then auto-evict across
+	// ~3 orchestrator turns — no more "overlay sticks around forever" when
+	// the user doesn't immediately type back.
+	const advanceTurn = () => {
 		const evicted = tracker.onTurnStart();
 		if (evicted) widget?.update();
-	});
+	};
+	pi.on("input", async () => advanceTurn());
+	pi.on("turn_start", async () => advanceTurn());
 
 	// Background dispatches (args.async === true per pi-subagents@0.17.5 schema)
 	// return a job handle in ~100ms. Tracking them produces a misleading
@@ -70,6 +75,13 @@ export default async function (pi: ExtensionAPI) {
 	pi.on("tool_execution_start", async (event, ctx) => {
 		if (event.toolName !== SUBAGENT_TOOL) return;
 		if (isAsyncDispatch(event.args)) return;
+		// Wave-boundary purge: if no runs are currently active and we still
+		// have finished rows lingering from a prior wave, drop them before
+		// the new run appears. Prevents "new wave appends under yesterday's
+		// ✓ lines" when waves dispatch back-to-back without a user turn.
+		if (tracker.runningCount() === 0 && tracker.hasAnyVisible()) {
+			tracker.purgeFinished();
+		}
 		tracker.onStart(event.toolCallId, event.args);
 		if (ctx.hasUI) {
 			widget ??= new SubagentWidget();