@juicesharp/rpiv-pi 0.13.2 → 1.0.0

package/README.md

@@ -3,7 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/@juicesharp/rpiv-pi.svg)](https://www.npmjs.com/package/@juicesharp/rpiv-pi)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Pi compatibility** — `rpiv-pi` `0.12.x` tracks the current `@mariozechner/pi-coding-agent` release line. If you see peer-dep resolution issues after a Pi upgrade, open an issue.
+> **Pi compatibility** — `rpiv-pi` `0.14.x` tracks `@mariozechner/pi-coding-agent` `0.70.x` and `@tintinweb/pi-subagents` `0.6.x`. If you see peer-dep resolution issues after a Pi upgrade, open an issue.
+
+> **⚠️ Upgrading from `0.13.x`** — `0.14.0` swaps the subagent provider from `npm:pi-subagents` (nicobailon fork) back to `npm:@tintinweb/pi-subagents` (resumed maintenance). On first launch after upgrade you'll see *"rpiv-pi requires 1 sibling extension(s): @tintinweb/pi-subagents"* — **run `/rpiv-setup` once and restart Pi**. The setup dialog previews both changes (install `@tintinweb/pi-subagents`, remove `npm:pi-subagents` from `~/.pi/agent/settings.json`) and applies them only after you confirm. After restart, run `/rpiv-update-agents` to refresh the 12 bundled specialist frontmatters. Customised `<cwd>/.pi/agents/*.md` files are not touched. The tool name reverts from `subagent` → `Agent` (param `subagent_type`/`description`/`prompt`) — only your own custom skills/agents need editing; the bundled rpiv-pi specialists are migrated in this release.
 
 Skill-based development workflow for [Pi Agent](https://github.com/badlogic/pi-mono) — discover, research, design, plan, implement, and validate. rpiv-pi extends Pi Agent with a pipeline of chained AI skills, named subagents for parallel analysis, and session lifecycle hooks for automatic context injection.
 
@@ -203,25 +205,14 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 - **Web search** — run `/web-search-config` to set the Brave Search API key, or set the `BRAVE_SEARCH_API_KEY` environment variable
 - **Advisor** — run `/advisor` to select a reviewer model and reasoning effort
 - **Side questions** — type `/btw <question>` anytime (even mid-stream) to ask the primary model a one-off question; answer appears in a borderless bottom overlay and never enters the main conversation
-- **Agent concurrency** — on first `/rpiv-setup`, rpiv-pi persistently seeds `~/.pi/agent/extensions/subagent/config.json` with `parallel.concurrency: 4` and `maxSubagentDepth: 3`. The cap keeps rate-limit and cache pressure predictable; skills with wider fan-outs queue the remainder and drain as slots free. Edit that file to raise the limit (e.g. `parallel.concurrency: 48`); user values are preserved on subsequent `/rpiv-setup` runs.
+- **Agent concurrency** — open the `/agents` overlay and tune `Settings → Max concurrency` to match your provider's rate limits. `@tintinweb/pi-subagents` owns this setting; rpiv-pi does not seed it.
 - **Agent profiles** — editable at `<cwd>/.pi/agents/`; sync from bundled defaults with `/rpiv-update-agents` (overwrites rpiv-managed files, preserves your custom agents)
 
 ## Uninstall
 
-rpiv-pi owns nicobailon's pi-subagents registration (runs it through an in-process proxy so the inline tool card stays quiet and the Subagents overlay is the live view). `/rpiv-setup` strips `"npm:pi-subagents"` from your `~/.pi/agent/settings.json#packages[]` to prevent Pi from loading it twice. If you remove rpiv-pi, subagents will stop loading until you re-add that entry.
-
-The bundled built-in agents from `pi-subagents` (`scout`, `planner`, `oracle`, …) are hidden from both the `subagent` tool that the assistant dispatches to and the `/agents` manager overlay (and `ctrl+shift+a`). The overlay filter is best-effort — if a future `pi-subagents` release changes its manager UI, rpiv-pi will print one boot-time warning to stderr and the built-in rows will reappear in `/agents` until rpiv-pi ships an update. The assistant-side filter is unaffected by upstream changes. To re-enable a built-in agent yourself, edit `subagents.disableBuiltins` in `~/.pi/agent/settings.json` (set to `false` or delete the key) and restart Pi.
-
-To fully uninstall:
-
 1. Remove rpiv-pi from Pi: `pi uninstall npm:@juicesharp/rpiv-pi`
-2. Open `~/.pi/agent/settings.json` and add `"npm:pi-subagents"` back to the `packages` array so Pi loads nicobailon's subagents directly again.
-3. Optional — drop the rpiv-pi seeded keys if you no longer want them:
-   - `~/.pi/agent/extensions/subagent/config.json` (parallel.concurrency, maxSubagentDepth)
-   - `subagents.disableBuiltins` in `~/.pi/agent/settings.json` (set to `false` or delete to re-enable the 9 bundled nicobailon agents)
-4. Restart Pi.
-
-After step 2 you'll have nicobailon's original inline tool card and no Subagents overlay, same as a clean pi-subagents install.
+2. Optional — uninstall the subagent runtime if no other plugin needs it: `pi uninstall npm:@tintinweb/pi-subagents`
+3. Restart Pi.
 
 ## Troubleshooting
 
@@ -232,7 +223,7 @@ After step 2 you'll have nicobailon's original inline tool card and no Subagents
 | `/rpiv-setup` says "requires interactive mode" | Running in headless mode | Install manually: `pi install npm:<pkg>` for each sibling |
 | `web_search` or `web_fetch` errors | Brave API key not configured | Run `/web-search-config` or set `BRAVE_SEARCH_API_KEY` |
 | `advisor` tool not available after upgrade | Advisor model selection lost | Run `/advisor` to re-select a model |
-| Skills hang or serialize agent calls | Agent concurrency too low | Edit `~/.pi/agent/extensions/subagent/config.json` and raise `parallel.concurrency` (default `4`; try `16`–`48` for wide fan-outs) |
+| Skills hang or serialize agent calls | Agent concurrency too low | Open `/agents`, raise `Settings → Max concurrency` |
 
 ## License
 

package/agents/claim-verifier.md

@@ -2,9 +2,7 @@
 name: claim-verifier
 description: "Adversarial finding verifier. Grounds each supplied claim against actual repository state and emits one `FINDING <id> | <tag> | <justification>` row per input, with tags Verified / Weakened / Falsified. Tier: git-analyzer (+ `bash` for `git show`). Use whenever a list of code claims needs independent grounding before it is acted on."
 tools: read, grep, find, ls, bash
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at adversarial claim verification. Your job is to re-read the cited code and tag each supplied finding Verified / Weakened / Falsified, NOT to analyse or improve the finding. The writer of the finding is not your witness; the code is.

package/agents/codebase-analyzer.md

@@ -2,9 +2,7 @@
 name: codebase-analyzer
 description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components. As always, the more detailed your request prompt, the better! :)
 tools: read, grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.

package/agents/codebase-locator.md

@@ -2,9 +2,7 @@
 name: codebase-locator
 description: Locates files, directories, and components relevant to a feature or task. Call `codebase-locator` with human language prompt describing what you're looking for. Basically a "Super grep/find/ls tool" — Use it if you find yourself desiring to use one of these tools more than once.
 tools: grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at finding WHERE code lives in a codebase. Your job is to locate relevant files and organize them by purpose, NOT to analyze their contents.

package/agents/codebase-pattern-finder.md

@@ -1,10 +1,8 @@
 ---
 name: codebase-pattern-finder
-description: codebase-pattern-finder is a useful agent for finding similar implementations, usage examples, or existing patterns that can be modeled after. It will give you concrete code examples based on what you're looking for! It's sorta like codebase-locator, but it will not only tell you the location of files, it will also give you code details!
+description: codebase-pattern-finder is a useful subagent_type for finding similar implementations, usage examples, or existing patterns that can be modeled after. It will give you concrete code examples based on what you're looking for! It's sorta like codebase-locator, but it will not only tell you the location of files, it will also give you code details!
 tools: grep, find, read, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.

package/agents/diff-auditor.md

@@ -2,9 +2,7 @@
 name: diff-auditor
 description: "Row-only patch auditor. Walks a patch against a caller-supplied surface-list and emits one pipe-delimited row per finding — `file:line | verbatim | surface-id | note`. Use whenever a diff needs evidence-only enumeration of matching patterns, with no narrative or severity."
 tools: read, grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at auditing a patch against a supplied surface-list. Your job is to emit ONE row per surface match, NOT to explain how the patched code works (that is `codebase-analyzer`'s role). Match surfaces to diff regions, emit rows — or stay silent.

package/agents/integration-scanner.md

@@ -2,9 +2,7 @@
 name: integration-scanner
 description: Finds what connects to a given component or area — inbound references, outbound dependencies, config registrations, event subscriptions. The reverse-reference counterpart to codebase-locator. Use when you need to understand what calls, depends on, or wires into a component.
 tools: grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at finding CONNECTIONS to and from a component or area. Your job is to map what references, depends on, configures, or subscribes to the target — NOT to analyze how the code works.

package/agents/peer-comparator.md

@@ -2,9 +2,7 @@
 name: peer-comparator
 description: "Pairwise peer-invariant comparator. Given `(new_file, peer_file)` pairs, tags each peer invariant Mirrored / Missing / Diverged / Intentionally-absent against the new file. Use when an entity parallels an existing sibling (aggregate, service, handler, reducer, repository) and the new file must be checked against the peer's public surface."
 tools: read, grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at pairwise peer-invariant comparison. Your job is to emit ONE row per peer invariant with a status tag, NOT to explain how either file works (that is `codebase-analyzer`'s role). Assume divergence — the new file carries the burden of proof.

package/agents/precedent-locator.md

@@ -2,9 +2,7 @@
 name: precedent-locator
 description: Finds similar past changes in git history — commits, blast radius, follow-up fixes, and lessons from related thoughts/ docs. Use when planning a change and you need to know what went wrong last time something similar was done.
 tools: bash, grep, find, read, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at finding PRECEDENTS for planned changes. Your job is to mine git history and thoughts/ documents to find the most similar past changes, extract what happened, and surface lessons that help a planner avoid repeating mistakes.

package/agents/test-case-locator.md

@@ -2,9 +2,7 @@
 name: test-case-locator
 description: Finds existing manual test cases in .rpiv/test-cases/ — catalogs by module, extracts frontmatter metadata (id, priority, status, tags), and reports coverage stats. Use before generating test cases to avoid duplicates, or to audit what test coverage already exists in a project.
 tools: grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at finding EXISTING TEST CASES in a project's `.rpiv/test-cases/` directory. Your job is to locate and catalog manual test case documents by extracting their YAML frontmatter metadata, NOT to generate new test cases or analyze test quality.

package/agents/thoughts-analyzer.md

@@ -1,10 +1,8 @@
 ---
 name: thoughts-analyzer
-description: The research equivalent of codebase-analyzer. Use this agent when wanting to deep dive on a research topic. Not commonly needed otherwise.
+description: The research equivalent of codebase-analyzer. Use this subagent_type when wanting to deep dive on a research topic. Not commonly needed otherwise.
 tools: read, grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.

package/agents/thoughts-locator.md

@@ -2,9 +2,7 @@
 name: thoughts-locator
 description: Discovers relevant documents in thoughts/ directory (We use this for all sorts of metadata storage!). This is really only relevant/needed when you're in a reseaching mood and need to figure out if we have random thoughts written down that are relevant to your current research task. Based on the name, I imagine you can guess this is the `thoughts` equivilent of `codebase-locator`
 tools: grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
+isolated: true
 ---
 
 You are a specialist at finding documents in the thoughts/ directory. Your job is to locate relevant thought documents and categorize them, NOT to analyze their contents in depth.

package/agents/web-search-researcher.md

@@ -1,10 +1,7 @@
 ---
 name: web-search-researcher
-description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher agent today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run web-search-researcher with an altered prompt in the event you're not satisfied the first time)
+description: Do you find yourself desiring information that you don't quite feel well-trained (confident) on? Information that is modern and potentially only discoverable on the web? Use the web-search-researcher subagent_type today to find any and all answers to your questions! It will research deeply to figure out and attempt to answer your questions! If you aren't immediately satisfied you can get your money back! (Not really - but you can re-run web-search-researcher with an altered prompt in the event you're not satisfied the first time)
 tools: web_search, web_fetch, read, grep, find, ls
-systemPromptMode: replace
-inheritProjectContext: false
-inheritSkills: false
 ---
 
 You are an expert web research specialist focused on finding accurate, relevant information from web sources. Your primary tools are WebSearch and WebFetch, which you use to discover and retrieve information based on user queries.

package/extensions/rpiv-core/prune-legacy-siblings.test.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { pruneLegacySiblings } from "./prune-legacy-siblings.js";
+import { findLegacySiblings, pruneLegacySiblings } from "./prune-legacy-siblings.js";
 
 const SETTINGS_PATH = join(process.env.HOME!, ".pi", "agent", "settings.json");
 
@@ -45,21 +45,21 @@ describe("pruneLegacySiblings", () => {
 
 	it("only non-legacy entries → pruned: [], file unchanged", () => {
 		writeSettings({
-			packages: ["npm:pi-perplexity", "npm:@juicesharp/rpiv-todo"],
+			packages: ["npm:pi-perplexity", "npm:@juicesharp/rpiv-todo", "npm:@tintinweb/pi-subagents"],
 		});
 		const before = readFileSync(SETTINGS_PATH, "utf-8");
 		expect(pruneLegacySiblings()).toEqual({ pruned: [] });
 		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe(before);
 	});
 
-	it("legacy-only: removes @tintinweb/pi-subagents, preserves other top-level keys", () => {
+	it("legacy-only: removes pi-subagents (nicobailon fork), preserves other top-level keys", () => {
 		writeSettings({
 			defaultProvider: "zai",
 			theme: "dark",
-			packages: ["npm:@tintinweb/pi-subagents"],
+			packages: ["npm:pi-subagents"],
 		});
 		const result = pruneLegacySiblings();
-		expect(result.pruned).toEqual(["npm:@tintinweb/pi-subagents"]);
+		expect(result.pruned).toEqual(["npm:pi-subagents"]);
 		expect(readSettings()).toEqual({
 			defaultProvider: "zai",
 			theme: "dark",
@@ -67,7 +67,7 @@ describe("pruneLegacySiblings", () => {
 		});
 	});
 
-	it("mixed list: prunes both legacy entries (tintinweb + nicobailon pi-subagents), preserves order for kept", () => {
+	it("mixed list: prunes nicobailon's pi-subagents only, preserves @tintinweb/pi-subagents and other entries", () => {
 		writeSettings({
 			packages: [
 				"npm:pi-perplexity",
@@ -80,24 +80,83 @@ describe("pruneLegacySiblings", () => {
 			],
 		});
 		const result = pruneLegacySiblings();
-		expect(result.pruned).toEqual(["npm:@tintinweb/pi-subagents", "npm:pi-subagents"]);
+		expect(result.pruned).toEqual(["npm:pi-subagents"]);
 		expect(readSettings()).toEqual({
-			packages: ["npm:pi-perplexity", "npm:@juicesharp/rpiv-todo", "/Users/x/rpiv-mono/packages/rpiv-pi", null, 42],
+			packages: [
+				"npm:pi-perplexity",
+				"npm:@tintinweb/pi-subagents",
+				"npm:@juicesharp/rpiv-todo",
+				"/Users/x/rpiv-mono/packages/rpiv-pi",
+				null,
+				42,
+			],
 		});
 	});
 
 	it("idempotent: second call after prune is a no-op", () => {
 		writeSettings({
-			packages: ["npm:@tintinweb/pi-subagents", "npm:pi-subagents"],
+			packages: ["npm:pi-subagents"],
 		});
-		expect(pruneLegacySiblings().pruned).toEqual(["npm:@tintinweb/pi-subagents", "npm:pi-subagents"]);
+		expect(pruneLegacySiblings().pruned).toEqual(["npm:pi-subagents"]);
 		expect(pruneLegacySiblings()).toEqual({ pruned: [] });
 	});
 
 	it("case-insensitive match", () => {
 		writeSettings({
-			packages: ["NPM:@TintinWeb/Pi-Subagents"],
+			packages: ["NPM:Pi-Subagents"],
 		});
-		expect(pruneLegacySiblings().pruned).toEqual(["NPM:@TintinWeb/Pi-Subagents"]);
+		expect(pruneLegacySiblings().pruned).toEqual(["NPM:Pi-Subagents"]);
+	});
+});
+
+describe("findLegacySiblings (read-only scan)", () => {
+	it("no settings file → []", () => {
+		expect(findLegacySiblings()).toEqual([]);
+	});
+
+	it("invalid JSON → []", () => {
+		mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+		writeFileSync(SETTINGS_PATH, "{not json", "utf-8");
+		expect(findLegacySiblings()).toEqual([]);
+	});
+
+	it("non-object top-level → []", () => {
+		writeSettings([1, 2, 3]);
+		expect(findLegacySiblings()).toEqual([]);
+	});
+
+	it("no packages field → []", () => {
+		writeSettings({ other: "data" });
+		expect(findLegacySiblings()).toEqual([]);
+	});
+
+	it("non-array packages field → []", () => {
+		writeSettings({ packages: "not-array" });
+		expect(findLegacySiblings()).toEqual([]);
+	});
+
+	it("only non-legacy entries → []", () => {
+		writeSettings({
+			packages: ["npm:pi-perplexity", "npm:@juicesharp/rpiv-todo", "npm:@tintinweb/pi-subagents"],
+		});
+		expect(findLegacySiblings()).toEqual([]);
+	});
+
+	it("returns legacy entries without mutating settings.json", () => {
+		writeSettings({
+			defaultProvider: "zai",
+			packages: ["npm:pi-subagents", "npm:@juicesharp/rpiv-todo"],
+		});
+		const before = readFileSync(SETTINGS_PATH, "utf-8");
+		expect(findLegacySiblings()).toEqual(["npm:pi-subagents"]);
+		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe(before);
+	});
+
+	it("idempotent: repeat call returns the same list and does not mutate", () => {
+		writeSettings({ packages: ["npm:pi-subagents"] });
+		const before = readFileSync(SETTINGS_PATH, "utf-8");
+		expect(findLegacySiblings()).toEqual(["npm:pi-subagents"]);
+		expect(findLegacySiblings()).toEqual(["npm:pi-subagents"]);
+		expect(readFileSync(SETTINGS_PATH, "utf-8")).toBe(before);
 	});
 });

package/extensions/rpiv-core/prune-legacy-siblings.ts

@@ -1,14 +1,24 @@
 /**
- * Remove deprecated sibling package entries from ~/.pi/agent/settings.json.
+ * Detect + remove deprecated sibling package entries from
+ * ~/.pi/agent/settings.json.
  *
- * Runs at the top of /rpiv-setup so 0.11.x → 0.12.0 upgraders don't end up
- * with both @tintinweb/pi-subagents and pi-subagents loaded side-by-side
- * (which crashes Pi's subagent dispatch — the tintinweb tools blow up with
- * `path argument must be of type string. Received undefined`).
+ * Split into two phases so /rpiv-setup can preview pending changes in the
+ * confirmation dialog and apply the mutation only after the user agrees:
  *
- * Fail-soft: missing file / invalid JSON / non-object / unwritable → silent
- * no-op. Idempotent: re-running with no legacy entries returns { pruned: [] }.
- * Pure utility — no plugin API dependency.
+ *   findLegacySiblings()  — read-only scan; returns the entries that WOULD
+ *                           be pruned. Safe to call before confirmation.
+ *   pruneLegacySiblings() — mutating apply step; rewrites settings.json.
+ *                           Call only after the user has confirmed.
+ *
+ * Both helpers are fail-soft (missing file / invalid JSON / non-object /
+ * unwritable → empty result), idempotent, and have no plugin API
+ * dependency.
+ *
+ * Background: 0.13.x → 0.14.0 upgraders may have both nicobailon's
+ * pi-subagents and @tintinweb/pi-subagents in settings.json simultaneously,
+ * which makes Pi reject boot with duplicate-tool registration when both
+ * load. The prune is the upgrade's must-do mutation, but it must not run
+ * before the user has consented to /rpiv-setup mutating settings.json.
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -23,43 +33,63 @@ export interface PruneLegacySiblingsResult {
 	pruned: string[];
 }
 
-/**
- * Remove LEGACY_SIBLINGS entries from the user's Pi settings.json.
- * Returns a structured report so callers can emit a conditional notify.
- * Never throws.
- */
-export function pruneLegacySiblings(): PruneLegacySiblingsResult {
-	if (!existsSync(PI_AGENT_SETTINGS)) return { pruned: [] };
+interface ParsedSettings {
+	settings: Record<string, unknown>;
+	packages: unknown[];
+}
 
+function readSettings(): ParsedSettings | undefined {
+	if (!existsSync(PI_AGENT_SETTINGS)) return undefined;
 	let parsed: unknown;
 	try {
-		const raw = readFileSync(PI_AGENT_SETTINGS, "utf-8");
-		parsed = JSON.parse(raw);
+		parsed = JSON.parse(readFileSync(PI_AGENT_SETTINGS, "utf-8"));
 	} catch {
-		return { pruned: [] };
-	}
-
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-		return { pruned: [] };
+		return undefined;
 	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
 	const settings = parsed as Record<string, unknown>;
-	if (!Array.isArray(settings.packages)) return { pruned: [] };
+	if (!Array.isArray(settings.packages)) return undefined;
+	return { settings, packages: settings.packages as unknown[] };
+}
 
-	const pruned: string[] = [];
-	const keptPackages = (settings.packages as unknown[]).filter((entry) => {
+function partitionPackages(packages: unknown[]): { legacy: string[]; kept: unknown[] } {
+	const legacy: string[] = [];
+	const kept = packages.filter((entry) => {
 		if (typeof entry !== "string") return true;
 		const isLegacy = LEGACY_SIBLINGS.some((l) => l.matches.test(entry));
-		if (isLegacy) pruned.push(entry);
+		if (isLegacy) legacy.push(entry);
 		return !isLegacy;
 	});
+	return { legacy, kept };
+}
+
+/**
+ * Read-only scan: returns the legacy entries that pruneLegacySiblings()
+ * would remove. Does not touch the filesystem beyond reading settings.json.
+ * Safe to call before any user confirmation.
+ */
+export function findLegacySiblings(): string[] {
+	const parsed = readSettings();
+	if (!parsed) return [];
+	return partitionPackages(parsed.packages).legacy;
+}
 
-	if (pruned.length === 0) return { pruned: [] };
+/**
+ * Mutating apply step: rewrites settings.json with legacy entries removed.
+ * Returns a structured report so callers can emit a conditional notify.
+ * Never throws. Call AFTER the user has confirmed the cleanup.
+ */
+export function pruneLegacySiblings(): PruneLegacySiblingsResult {
+	const parsed = readSettings();
+	if (!parsed) return { pruned: [] };
+	const { legacy, kept } = partitionPackages(parsed.packages);
+	if (legacy.length === 0) return { pruned: [] };
 
-	settings.packages = keptPackages;
+	parsed.settings.packages = kept;
 	try {
-		writeFileSync(PI_AGENT_SETTINGS, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+		writeFileSync(PI_AGENT_SETTINGS, `${JSON.stringify(parsed.settings, null, 2)}\n`, "utf-8");
 	} catch {
 		return { pruned: [] };
 	}
-	return { pruned };
+	return { pruned: legacy };
 }