@juicesharp/rpiv-pi 0.12.3 → 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/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/overlay.test.ts

@@ -0,0 +1,149 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { Container, Text } from "@mariozechner/pi-tui";
+import { describe, expect, it, vi } from "vitest";
+
+// Stub the full renderer so the terminal-state branch returns a recognisable sentinel
+// instead of executing nicobailon's real renderer (which needs a full Theme).
+// vi.hoisted is required because vi.mock factories are top-hoisted and can't close
+// over file-level consts.
+const { renderSubagentResultMock } = vi.hoisted(() => ({
+	renderSubagentResultMock: vi.fn(() => ({ __sentinel: "full-render" }) as unknown),
+}));
+vi.mock("pi-subagents/render", () => ({ renderSubagentResult: renderSubagentResultMock }));
+
+import { buildQuietRenderCall, buildQuietRenderResult } from "./overlay.js";
+
+function makeTheme(): Theme {
+	return {
+		fg: (_c: string, t: string) => t,
+		bold: (t: string) => t,
+	} as unknown as Theme;
+}
+
+describe("buildQuietRenderCall — layout-stable status trailer from first frame", () => {
+	it("composes original call + status trailer when no original is provided", () => {
+		const render = buildQuietRenderCall(undefined);
+		// No original renderCall → just the trailer.
+		const out = render({}, makeTheme(), { executionStarted: false, state: {} });
+		expect(out).toBeInstanceOf(Text);
+	});
+
+	it("emits pending glyph when !executionStarted (before markExecutionStarted)", () => {
+		const render = buildQuietRenderCall(undefined);
+		const out = render({}, makeTheme(), { executionStarted: false, state: {} }) as Text;
+		// Our stubbed theme.fg is identity, so Text content includes the literal glyph + label.
+		const text = (out as unknown as { text?: string }).text ?? "";
+		expect(text).toContain("○");
+		expect(text).toContain("pending");
+	});
+
+	it("emits running glyph when executionStarted === true", () => {
+		const render = buildQuietRenderCall(undefined);
+		const out = render({}, makeTheme(), { executionStarted: true, state: {} }) as Text;
+		const text = (out as unknown as { text?: string }).text ?? "";
+		expect(text).toContain("◐");
+		expect(text).toContain("running");
+	});
+
+	it("wraps original call + trailer in a Container when both are present", () => {
+		const originalCall = vi.fn(() => new Text("subagent peer-comparator", 0, 0));
+		const render = buildQuietRenderCall(originalCall);
+		const out = render({}, makeTheme(), { executionStarted: true, state: {} });
+		expect(out).toBeInstanceOf(Container);
+		expect(originalCall).toHaveBeenCalledOnce();
+	});
+
+	it("suppresses trailer once state.subagentTerminal is set (final frame)", () => {
+		const originalCall = vi.fn(() => new Text("subagent peer-comparator", 0, 0));
+		const render = buildQuietRenderCall(originalCall);
+		const out = render({}, makeTheme(), { executionStarted: true, state: { subagentTerminal: true } });
+		// Should return the original call as-is, no Container wrapping with trailer.
+		expect(out).toBeInstanceOf(Text);
+		expect(originalCall).toHaveBeenCalledOnce();
+	});
+});
+
+describe("buildQuietRenderResult — non-terminal stub + terminal delegation", () => {
+	it("returns zero-height stub while progress.status === 'running' (renderCall owns trailer)", () => {
+		renderSubagentResultMock.mockClear();
+		const render = buildQuietRenderResult();
+		const out = render(
+			{ details: { results: [{ agent: "x", progress: { status: "running" } }] } },
+			{ expanded: false, isPartial: true },
+			makeTheme(),
+			{ state: {} },
+		);
+		expect(out).toBeInstanceOf(Text);
+		expect(renderSubagentResultMock).not.toHaveBeenCalled();
+	});
+
+	it("returns zero-height stub when progress is MISSING (pre-progress first frame)", () => {
+		renderSubagentResultMock.mockClear();
+		const render = buildQuietRenderResult();
+		const out = render({ details: { results: [{ agent: "x" }] } }, { expanded: false }, makeTheme(), { state: {} });
+		expect(out).toBeInstanceOf(Text);
+		expect(renderSubagentResultMock).not.toHaveBeenCalled();
+	});
+
+	it("returns zero-height stub when result.details is missing entirely", () => {
+		renderSubagentResultMock.mockClear();
+		const render = buildQuietRenderResult();
+		const out = render({}, { expanded: false }, makeTheme(), { state: {} });
+		expect(out).toBeInstanceOf(Text);
+	});
+
+	it("delegates to full renderer once terminal AND isPartial === false", () => {
+		renderSubagentResultMock.mockClear();
+		const state: { subagentTerminal?: boolean } = {};
+		const render = buildQuietRenderResult();
+		const out = render(
+			{ details: { results: [{ agent: "x", exitCode: 0, progress: { status: "complete" } }] } },
+			{ expanded: false, isPartial: false },
+			makeTheme(),
+			{ state },
+		);
+		expect(renderSubagentResultMock).toHaveBeenCalledOnce();
+		expect((out as { __sentinel?: string }).__sentinel).toBe("full-render");
+		// State flag is set so renderCall suppresses its trailer next frame.
+		expect(state.subagentTerminal).toBe(true);
+	});
+
+	it("keeps stub when terminal but isPartial === true (don't commit until final)", () => {
+		renderSubagentResultMock.mockClear();
+		const render = buildQuietRenderResult();
+		const out = render(
+			{ details: { results: [{ agent: "x", exitCode: 0 }] } },
+			{ expanded: false, isPartial: true },
+			makeTheme(),
+			{ state: {} },
+		);
+		expect(out).toBeInstanceOf(Text);
+		expect(renderSubagentResultMock).not.toHaveBeenCalled();
+	});
+
+	it("delegates to full renderer on error stopReason (terminal)", () => {
+		renderSubagentResultMock.mockClear();
+		const render = buildQuietRenderResult();
+		const out = render(
+			{ details: { results: [{ agent: "x", stopReason: "error" }] } },
+			{ expanded: false, isPartial: false },
+			makeTheme(),
+			{ state: {} },
+		);
+		expect(renderSubagentResultMock).toHaveBeenCalledOnce();
+		expect((out as { __sentinel?: string }).__sentinel).toBe("full-render");
+	});
+
+	it("treats exitCode present + status=running as NON-terminal (streaming finalisation window)", () => {
+		renderSubagentResultMock.mockClear();
+		const render = buildQuietRenderResult();
+		const out = render(
+			{ details: { results: [{ agent: "x", exitCode: 0, progress: { status: "running" } }] } },
+			{ expanded: false, isPartial: true },
+			makeTheme(),
+			{ state: {} },
+		);
+		expect(out).toBeInstanceOf(Text);
+		expect(renderSubagentResultMock).not.toHaveBeenCalled();
+	});
+});