@juicesharp/rpiv-pi 1.6.1 → 1.8.0

package/README.md

@@ -91,7 +91,7 @@ pi install npm:@juicesharp/rpiv-pi
 ### First Session
 
 On first Pi Agent session start, rpiv-pi automatically:
-- Copies agent profiles to `<cwd>/.pi/agents/`
+- Copies agent profiles to `~/.pi/agent/agents/` (user-global, shared across all projects)
 - Detects outdated or removed agents on subsequent starts
 - Scaffolds `thoughts/shared/` directories for pipeline artifacts
 - Shows a warning if any sibling plugins are missing
@@ -180,12 +180,12 @@ Invoke via `/skill:<name>` from inside a Pi Agent session.
 | Command | Description |
 |---|---|
 | `/rpiv-setup` | Install all sibling plugins in one go |
-| `/rpiv-update-agents` | Sync rpiv agent profiles: add new, update changed, remove stale |
+| `/rpiv-update-agents` | Refresh `~/.pi/agent/agents/` from bundled agent definitions and clean up legacy per-project agent directories |
 | `/advisor` | Configure advisor model and reasoning effort |
 | `/btw` | Ask a side question without polluting the main conversation _(requires `@juicesharp/rpiv-btw`, opt-in)_ |
 | `/languages` | Pick the UI language for rpiv-* TUI strings (Deutsch / English / Español / Français / Português / Português (Brasil) / Русский / Українська) |
 | `/todos` | Show current todo list |
-| `/web-search-config` | Set Brave Search API key |
+| `/web-search-config` | Pick the active search provider and set its API key |
 
 ### Agents
 
@@ -220,12 +220,12 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 
 ## Configuration
 
-- **Web search** - run `/web-search-config` to set the Brave Search API key, or set the `BRAVE_SEARCH_API_KEY` environment variable
+- **Web search** - run `/web-search-config` to pick a provider (Brave, Tavily, Serper, Exa, Jina, or Firecrawl) and set its API key; the per-provider env var (e.g. `BRAVE_SEARCH_API_KEY`, `EXA_API_KEY`) also works and takes precedence
 - **Advisor** - run `/advisor` to select a reviewer model and reasoning effort
 - **Side questions** _(opt-in: `pi install npm:@juicesharp/rpiv-btw`)_ - 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
 - **UI language** - run `/languages` to pick the locale for rpiv-* TUI strings, or pass `pi --locale <code>` at startup. Detection priority: flag → `~/.config/rpiv-i18n/locale.json` → `LANG` / `LC_ALL` → English. LLM-facing copy stays English by design
 - **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)
+- **Agent profiles** - synced to `~/.pi/agent/agents/` from bundled defaults; refresh with `/rpiv-update-agents` (overwrites rpiv-managed files, preserves your custom agents).
 
 ## Uninstall
 
@@ -240,7 +240,7 @@ Pi Agent discovers extensions via `"extensions": ["./extensions"]` and skills vi
 | Warning about missing siblings on session start | Sibling plugins not installed | Run `/rpiv-setup` |
 | `/rpiv-setup` fails on a package | Network or registry issue | Check connection, retry with `pi install npm:<pkg>`, re-run `/rpiv-setup` |
 | `/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` |
+| `web_search` or `web_fetch` errors | Active provider's API key not configured | Run `/web-search-config` or set the matching env var (e.g. `BRAVE_SEARCH_API_KEY`, `EXA_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 | Open `/agents`, raise `Settings → Max concurrency` |
 

package/agents/web-search-researcher.md

@@ -2,7 +2,6 @@
 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 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
-isolated: true
 ---
 
 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/agents.test.ts

@@ -10,10 +10,18 @@ import {
 	statSync,
 	writeFileSync,
 } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { BUNDLED_AGENTS_DIR, isSafeDestructiveOp, SYNC_OP, syncBundledAgents } from "./agents.js";
+import {
+	BUNDLED_AGENTS_DIR,
+	CLEANUP_SKIP_REASON,
+	cleanupPerCwdAgents,
+	isSafeDestructiveOp,
+	SYNC_OP,
+	summarizeCleanupSkips,
+	syncBundledAgents,
+} from "./agents.js";
 
 const sha256 = (s: string | Buffer) => createHash("sha256").update(s).digest("hex");
 
@@ -27,12 +35,15 @@ let markerPath: string;
 
 beforeEach(() => {
 	cwd = mkdtempSync(join(tmpdir(), "rpiv-agents-"));
-	targetDir = join(cwd, ".pi", "agents");
+	targetDir = join(homedir(), ".pi", "agent", "agents");
 	manifestPath = join(targetDir, ".rpiv-managed.json");
 	markerPath = join(targetDir, ".rpiv-managed.v2");
 });
 afterEach(() => {
 	rmSync(cwd, { recursive: true, force: true });
+	// Remove the `agent/` parent — not just `agent/agents/` — so Q18's writeFileSync
+	// (which needs the `agent` slot empty) and cross-test isolation both hold.
+	rmSync(join(homedir(), ".pi", "agent"), { recursive: true, force: true });
 	vi.restoreAllMocks();
 });
 
@@ -42,7 +53,7 @@ afterEach(() => {
 
 describe("syncBundledAgents — first-run (no manifest, empty target)", () => {
 	it("copies every source .md and writes a v2 manifest with sha256 hashes", () => {
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 		const bundled = bundledNames();
 		expect(r.added.sort()).toEqual(bundled.sort());
 		expect(r.updated).toEqual([]);
@@ -60,7 +71,7 @@ describe("syncBundledAgents — first-run (no manifest, empty target)", () => {
 	});
 
 	it("writes the .rpiv-managed.v2 sentinel marker after first successful sync", () => {
-		syncBundledAgents(cwd, false);
+		syncBundledAgents(false);
 		expect(existsSync(markerPath)).toBe(true);
 		expect(readFileSync(markerPath, "utf-8")).toBe("");
 	});
@@ -79,7 +90,7 @@ describe("syncBundledAgents — legacy v1 manifest one-shot migration", () => {
 		writeFileSync(join(targetDir, target), bundledContent(target), "utf-8");
 		writeFileSync(manifestPath, JSON.stringify([target]), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.unchanged).toContain(target);
 		expect(r.updated).not.toContain(target);
@@ -96,7 +107,7 @@ describe("syncBundledAgents — legacy v1 manifest one-shot migration", () => {
 		writeFileSync(join(targetDir, target), "user-edited content", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify([target]), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.updated).toContain(target);
 		expect(r.pendingUpdate).not.toContain(target);
@@ -115,7 +126,7 @@ describe("syncBundledAgents — legacy v1 manifest one-shot migration", () => {
 		for (const name of legacyEntries) writeFileSync(join(targetDir, name), bundledContent(name), "utf-8");
 		writeFileSync(manifestPath, JSON.stringify(legacyEntries), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.added).toContain(target);
 		expect(existsSync(join(targetDir, target))).toBe(true);
@@ -126,7 +137,7 @@ describe("syncBundledAgents — legacy v1 manifest one-shot migration", () => {
 		writeFileSync(join(targetDir, "stale.md"), "old shipped content", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify(["stale.md"]), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.removed).toContain("stale.md");
 		expect(r.pendingRemove).not.toContain("stale.md");
@@ -138,7 +149,7 @@ describe("syncBundledAgents — legacy v1 manifest one-shot migration", () => {
 		writeFileSync(join(targetDir, "stale.md"), "user-edited stale content", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify(["stale.md"]), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.removed).toContain("stale.md");
 		expect(existsSync(join(targetDir, "stale.md"))).toBe(false);
@@ -149,7 +160,7 @@ describe("syncBundledAgents — legacy v1 manifest one-shot migration", () => {
 		writeFileSync(join(targetDir, "unrelated.md"), "stale", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify([42, null, "unrelated.md"]), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.errors).toEqual([]);
 		expect(r.removed).toContain("unrelated.md");
@@ -162,7 +173,7 @@ describe("syncBundledAgents — legacy v1 manifest one-shot migration", () => {
 		for (const name of bundled) writeFileSync(join(targetDir, name), "stale legacy content", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify(bundled), "utf-8");
 
-		syncBundledAgents(cwd, false);
+		syncBundledAgents(false);
 
 		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
 		expect(Array.isArray(manifest)).toBe(false);
@@ -180,14 +191,14 @@ describe("syncBundledAgents — legacy v1 manifest one-shot migration", () => {
 		mkdirSync(targetDir, { recursive: true });
 		writeFileSync(join(targetDir, target), "pre-migration drift", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify([target]), "utf-8");
-		syncBundledAgents(cwd, false);
+		syncBundledAgents(false);
 		// First successful sync commits the v2 marker (one-shot per project).
 		expect(existsSync(markerPath)).toBe(true);
 
 		// User edits AFTER migration
 		writeFileSync(join(targetDir, target), "user customization", "utf-8");
 
-		const r2 = syncBundledAgents(cwd, false);
+		const r2 = syncBundledAgents(false);
 
 		expect(r2.pendingUpdate).toContain(target);
 		expect(r2.updated).not.toContain(target);
@@ -207,7 +218,7 @@ describe("syncBundledAgents — missing/corrupt manifest", () => {
 		const target = bundled[0];
 		writeFileSync(join(targetDir, target), bundledContent(target), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.unchanged).toContain(target);
 		expect(r.added).not.toContain(target);
@@ -222,7 +233,7 @@ describe("syncBundledAgents — missing/corrupt manifest", () => {
 		const target = bundled[0];
 		writeFileSync(join(targetDir, target), "drift content", "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.updated).toContain(target);
 		expect(readFileSync(join(targetDir, target), "utf-8")).toBe(bundledContent(target));
@@ -236,7 +247,7 @@ describe("syncBundledAgents — missing/corrupt manifest", () => {
 		writeFileSync(join(targetDir, bundled[0]), "drift", "utf-8");
 		expect(existsSync(markerPath)).toBe(false);
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.errors).toEqual([]);
 		expect(r.updated).toContain(bundled[0]);
@@ -254,7 +265,7 @@ describe("syncBundledAgents — missing/corrupt manifest", () => {
 		writeFileSync(manifestPath, JSON.stringify(42), "utf-8");
 		writeFileSync(join(targetDir, bundled[0]), "drift", "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.errors).toEqual([]);
 		expect(r.updated).toContain(bundled[0]);
@@ -277,7 +288,7 @@ describe("syncBundledAgents — v2 manifest smart gate (apply=false)", () => {
 		// v2 manifest: hash matches what we just wrote, so "user hasn't edited"
 		writeFileSync(manifestPath, JSON.stringify({ [target]: sha256(oldContent) }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.updated).toContain(target);
 		expect(r.pendingUpdate).not.toContain(target);
@@ -295,7 +306,7 @@ describe("syncBundledAgents — v2 manifest smart gate (apply=false)", () => {
 		writeFileSync(join(targetDir, target), "user edits", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify({ [target]: sha256("shipped version") }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.pendingUpdate).toContain(target);
 		expect(r.updated).not.toContain(target);
@@ -307,7 +318,7 @@ describe("syncBundledAgents — v2 manifest smart gate (apply=false)", () => {
 		writeFileSync(join(targetDir, "removed.md"), "old removed agent", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify({ "removed.md": sha256("old removed agent") }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.removed).toContain("removed.md");
 		expect(existsSync(join(targetDir, "removed.md"))).toBe(false);
@@ -318,7 +329,7 @@ describe("syncBundledAgents — v2 manifest smart gate (apply=false)", () => {
 		writeFileSync(join(targetDir, "removed.md"), "user added notes", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify({ "removed.md": sha256("shipped") }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.pendingRemove).toContain("removed.md");
 		expect(r.removed).not.toContain("removed.md");
@@ -326,19 +337,19 @@ describe("syncBundledAgents — v2 manifest smart gate (apply=false)", () => {
 	});
 
 	it("treats a manually-removed dest as a new add on next sync", () => {
-		syncBundledAgents(cwd, true);
+		syncBundledAgents(true);
 		const bundled = bundledNames();
 		if (bundled.length === 0) return;
 		rmSync(join(targetDir, bundled[0]));
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.added).toContain(bundled[0]);
 	});
 
 	it("reports unchanged on a quiescent second sync", () => {
-		syncBundledAgents(cwd, true);
-		const r = syncBundledAgents(cwd, false);
+		syncBundledAgents(true);
+		const r = syncBundledAgents(false);
 		expect(r.added).toEqual([]);
 		expect(r.updated).toEqual([]);
 		expect(r.pendingUpdate).toEqual([]);
@@ -352,11 +363,11 @@ describe("syncBundledAgents — v2 manifest smart gate (apply=false)", () => {
 
 describe("syncBundledAgents — custom user agents (v2 manifest active)", () => {
 	it("ignores a custom user .md whose name does NOT match any bundled agent", () => {
-		syncBundledAgents(cwd, true);
+		syncBundledAgents(true);
 		const customPath = join(targetDir, "my-custom-agent.md");
 		writeFileSync(customPath, "user content", "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.removed).not.toContain("my-custom-agent.md");
 		expect(r.pendingRemove).not.toContain("my-custom-agent.md");
@@ -382,7 +393,7 @@ describe("syncBundledAgents — custom user agents (v2 manifest active)", () =>
 		// User's hand-placed file happens to match canonical content
 		writeFileSync(join(targetDir, target), bundledContent(target), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.unchanged).toContain(target);
 		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -406,7 +417,7 @@ describe("syncBundledAgents — custom user agents (v2 manifest active)", () =>
 		// User's hand-placed file diverges from canonical
 		writeFileSync(join(targetDir, target), "user wrote this", "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		// hasV2Data=true (marker present) → unknown entry is gated
 		expect(r.pendingUpdate).toContain(target);
@@ -423,11 +434,11 @@ describe("syncBundledAgents — apply=true (forced sync)", () => {
 	it("overwrites a user-edited file even with v2 gate in place", () => {
 		const bundled = bundledNames();
 		if (bundled.length === 0) return;
-		syncBundledAgents(cwd, true);
+		syncBundledAgents(true);
 		const target = bundled[0];
 		writeFileSync(join(targetDir, target), "user-modified", "utf-8");
 
-		const r = syncBundledAgents(cwd, true);
+		const r = syncBundledAgents(true);
 
 		expect(r.updated).toContain(target);
 		expect(readFileSync(join(targetDir, target), "utf-8")).toBe(bundledContent(target));
@@ -438,20 +449,20 @@ describe("syncBundledAgents — apply=true (forced sync)", () => {
 		writeFileSync(join(targetDir, "stale.md"), "user-edited stale", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify({ "stale.md": sha256("originally shipped content") }), "utf-8");
 
-		const r = syncBundledAgents(cwd, true);
+		const r = syncBundledAgents(true);
 
 		expect(r.removed).toContain("stale.md");
 		expect(existsSync(join(targetDir, "stale.md"))).toBe(false);
 	});
 
 	it("baselines real hashes from a v1 manifest (after-upgrade sync)", () => {
-		syncBundledAgents(cwd, true);
+		syncBundledAgents(true);
 		const bundled = bundledNames();
 		if (bundled.length === 0) return;
 		// Roll back manifest to v1 form to simulate upgrade-then-/rpiv-update-agents
 		writeFileSync(manifestPath, JSON.stringify(bundled), "utf-8");
 
-		syncBundledAgents(cwd, true);
+		syncBundledAgents(true);
 
 		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
 		expect(Array.isArray(manifest)).toBe(false);
@@ -461,8 +472,8 @@ describe("syncBundledAgents — apply=true (forced sync)", () => {
 	});
 
 	it("leaves unchanged files alone", () => {
-		syncBundledAgents(cwd, true);
-		const r = syncBundledAgents(cwd, true);
+		syncBundledAgents(true);
+		const r = syncBundledAgents(true);
 		expect(r.updated).toEqual([]);
 		expect(r.unchanged.length).toBeGreaterThan(0);
 	});
@@ -486,7 +497,7 @@ describe("syncBundledAgents — manifest robustness", () => {
 		);
 		writeFileSync(join(targetDir, target), bundledContent(target), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.errors).toEqual([]);
 		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -506,7 +517,7 @@ describe("syncBundledAgents — manifest robustness", () => {
 		writeFileSync(join(targetDir, a), bundledContent(a), "utf-8");
 		writeFileSync(join(targetDir, b), "user-edited content", "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.pendingUpdate).toContain(b);
 		expect(r.updated).not.toContain(b);
@@ -522,14 +533,14 @@ describe("syncBundledAgents — I1: v2 sentinel marker", () => {
 	it("with marker present and corrupt JSON manifest, gates user edits as pendingUpdate", () => {
 		const bundled = bundledNames();
 		if (bundled.length === 0) return;
-		syncBundledAgents(cwd, false); // first sync — writes marker
+		syncBundledAgents(false); // first sync — writes marker
 		expect(existsSync(markerPath)).toBe(true);
 
 		const target = bundled[0];
 		writeFileSync(join(targetDir, target), "user customization", "utf-8");
 		writeFileSync(manifestPath, "{ corrupt :: not json", "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.updated).not.toContain(target);
 		expect(r.pendingUpdate).toContain(target);
@@ -539,7 +550,7 @@ describe("syncBundledAgents — I1: v2 sentinel marker", () => {
 	it("with marker present and all-empty-hash manifest, gates user edits as pendingUpdate", () => {
 		const bundled = bundledNames();
 		if (bundled.length === 0) return;
-		syncBundledAgents(cwd, false);
+		syncBundledAgents(false);
 
 		const target = bundled[0];
 		writeFileSync(join(targetDir, target), "user customization", "utf-8");
@@ -547,7 +558,7 @@ describe("syncBundledAgents — I1: v2 sentinel marker", () => {
 		for (const name of bundled) empty[name] = "";
 		writeFileSync(manifestPath, JSON.stringify(empty), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.updated).not.toContain(target);
 		expect(r.pendingUpdate).toContain(target);
@@ -562,12 +573,12 @@ describe("syncBundledAgents — I1: v2 sentinel marker", () => {
 		writeFileSync(join(targetDir, target), "drift", "utf-8");
 		expect(existsSync(markerPath)).toBe(false);
 
-		const r1 = syncBundledAgents(cwd, false);
+		const r1 = syncBundledAgents(false);
 		expect(r1.updated).toContain(target);
 		expect(existsSync(markerPath)).toBe(true);
 
 		writeFileSync(join(targetDir, target), "post-migration user edit", "utf-8");
-		const r2 = syncBundledAgents(cwd, false);
+		const r2 = syncBundledAgents(false);
 		expect(r2.updated).not.toContain(target);
 		expect(r2.pendingUpdate).toContain(target);
 	});
@@ -584,7 +595,7 @@ describe("syncBundledAgents — I2: path-traversal hardening", () => {
 		writeFileSync(sentinel, "DO NOT DELETE", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify({ "../../sentinel.md": "" }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(existsSync(sentinel)).toBe(true);
 		expect(r.removed).not.toContain("../../sentinel.md");
@@ -597,7 +608,7 @@ describe("syncBundledAgents — I2: path-traversal hardening", () => {
 		writeFileSync(sentinel, "absolute target", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify({ [sentinel]: "" }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(existsSync(sentinel)).toBe(true);
 		expect(r.removed.length).toBe(0);
@@ -608,7 +619,7 @@ describe("syncBundledAgents — I2: path-traversal hardening", () => {
 		writeFileSync(join(targetDir, "weird.txt"), "not an agent", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify({ "weird.txt": "" }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.removed).not.toContain("weird.txt");
 		expect(existsSync(join(targetDir, "weird.txt"))).toBe(true);
@@ -620,7 +631,7 @@ describe("syncBundledAgents — I2: path-traversal hardening", () => {
 		writeFileSync(sentinel, "v1 target", "utf-8");
 		writeFileSync(manifestPath, JSON.stringify(["../../v1-sentinel.md"]), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(existsSync(sentinel)).toBe(true);
 		expect(r.removed).not.toContain("../../v1-sentinel.md");
@@ -628,12 +639,13 @@ describe("syncBundledAgents — I2: path-traversal hardening", () => {
 
 	it("ignores manifest keys containing a NUL byte", () => {
 		mkdirSync(targetDir, { recursive: true });
-		writeFileSync(manifestPath, JSON.stringify({ "evil\u0000.md": "" }), "utf-8");
+		const nulKey = `evil${String.fromCharCode(0)}.md`;
+		writeFileSync(manifestPath, JSON.stringify({ [nulKey]: "" }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.errors).toEqual([]);
-		expect(r.removed).not.toContain("evil\u0000.md");
+		expect(r.removed).not.toContain(nulKey);
 	});
 });
 
@@ -644,7 +656,7 @@ describe("syncBundledAgents — error paths", () => {
 		mkdirSync(targetDir, { recursive: true });
 		chmodSync(targetDir, 0o500);
 		try {
-			const r = syncBundledAgents(cwd, false);
+			const r = syncBundledAgents(false);
 			const errorTripped = r.errors.some((e) => e.op === SYNC_OP.COPY) || r.added.length < bundled.length;
 			expect(errorTripped).toBe(true);
 		} finally {
@@ -658,7 +670,7 @@ describe("syncBundledAgents — error paths", () => {
 		mkdirSync(targetDir, { recursive: true });
 		writeFileSync(manifestPath, JSON.stringify({ "stale.md": sha256("x") }), "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.errors).toEqual([]);
 		expect(r.removed).toContain("stale.md");
@@ -668,35 +680,39 @@ describe("syncBundledAgents — error paths", () => {
 	});
 
 	it.skipIf(process.platform === "win32")("Q9: writeManifest failure surfaces op:'manifest-write' SyncError", () => {
-		// Plan called for chmod(targetDir, 0o500), but POSIX dir-without-write still
-		// permits writes to existing files inside, so writeManifest would not fail.
-		// Read-only the manifest file itself to deterministically trigger EACCES on
-		// the writeManifest open(O_WRONLY|O_TRUNC|O_CREAT).
-		syncBundledAgents(cwd, true);
+		// Q9: make the targetDir read-only so writeFileSync(tmpFile) fails (not just renameSync).
+		// Atomic write writes a NEW .tmp file then renames — chmod-ing the manifest file
+		// is insufficient because renameSync only needs directory write perms.
+		syncBundledAgents(true);
 		const bundled = bundledNames();
 		if (bundled.length === 0) return;
 		writeFileSync(join(targetDir, bundled[0]), "drift", "utf-8");
-		chmodSync(manifestPath, 0o400);
+		chmodSync(targetDir, 0o500);
 
 		try {
-			const r = syncBundledAgents(cwd, true);
+			const r = syncBundledAgents(true);
 			expect(r.errors.some((e) => e.op === SYNC_OP.MANIFEST_WRITE)).toBe(true);
 		} finally {
-			chmodSync(manifestPath, 0o600);
+			chmodSync(targetDir, 0o700);
 		}
 	});
 
 	it("Q18: mkdir failure tagged op:'mkdir' (not op:'manifest-write')", () => {
-		// Plan called for vi.spyOn(fs, "mkdirSync"), but ESM module namespaces are
-		// not configurable under this Vitest config. Inject the failure by placing
-		// a regular file at `<cwd>/.pi` so mkdirSync(<cwd>/.pi/agents, {recursive:true})
-		// fails with ENOTDIR — same observable: an op:"mkdir" SyncError.
-		writeFileSync(join(cwd, ".pi"), "not a dir", "utf-8");
+		// Reset pre-state: parent must exist as a dir; the agent slot must NOT exist
+		// (other tests may have left it as an empty dir via mkdirSync(recursive)).
+		mkdirSync(join(homedir(), ".pi"), { recursive: true });
+		rmSync(join(homedir(), ".pi", "agent"), { recursive: true, force: true });
+		// Block the global agents dir path by placing a file where the dir should go
+		writeFileSync(join(homedir(), ".pi", "agent"), "not a dir", "utf-8");
 
-		const r = syncBundledAgents(cwd, false);
+		try {
+			const r = syncBundledAgents(false);
 
-		expect(r.errors.some((e) => e.op === SYNC_OP.MKDIR)).toBe(true);
-		expect(r.errors.some((e) => e.op === SYNC_OP.MANIFEST_WRITE)).toBe(false);
+			expect(r.errors.some((e) => e.op === SYNC_OP.MKDIR)).toBe(true);
+			expect(r.errors.some((e) => e.op === SYNC_OP.MANIFEST_WRITE)).toBe(false);
+		} finally {
+			rmSync(join(homedir(), ".pi", "agent"), { force: true });
+		}
 	});
 
 	it("Q5: pushes to result.removed when a tracked file has already vanished from disk (v2 active)", () => {
@@ -705,7 +721,7 @@ describe("syncBundledAgents — error paths", () => {
 		writeFileSync(markerPath, "", "utf-8");
 		// Note: 'stale.md' is NOT created on disk — it has vanished while still tracked.
 
-		const r = syncBundledAgents(cwd, false);
+		const r = syncBundledAgents(false);
 
 		expect(r.removed).toContain("stale.md");
 		expect(r.errors).toEqual([]);
@@ -722,7 +738,7 @@ describe("syncBundledAgents — error paths", () => {
 			// readFileSync(src) throws EACCES; restore in finally.
 			const bundled = bundledNames();
 			if (bundled.length === 0) return;
-			syncBundledAgents(cwd, false);
+			syncBundledAgents(false);
 			const target = bundled[0];
 			const baselined = JSON.parse(readFileSync(manifestPath, "utf-8"));
 			const priorHash = baselined[target];
@@ -732,7 +748,7 @@ describe("syncBundledAgents — error paths", () => {
 			const originalMode = statSync(srcPath).mode & 0o777;
 			chmodSync(srcPath, 0o000);
 			try {
-				const r = syncBundledAgents(cwd, false);
+				const r = syncBundledAgents(false);
 				expect(r.errors.some((e) => e.op === SYNC_OP.READ_SRC && e.file === target)).toBe(true);
 				expect(r.pendingUpdate).not.toContain(target);
 				const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -752,7 +768,7 @@ describe("syncBundledAgents — error paths", () => {
 		chmodSync(stalePath, 0o000);
 
 		try {
-			const r = syncBundledAgents(cwd, false);
+			const r = syncBundledAgents(false);
 			expect(r.errors.some((e) => e.op === SYNC_OP.READ_DEST && e.file === "stale.md")).toBe(true);
 		} finally {
 			chmodSync(stalePath, 0o600);
@@ -760,6 +776,114 @@ describe("syncBundledAgents — error paths", () => {
 	});
 });
 
+// ─────────────────────────────────────────────────────────────────────────────
+// cleanupPerCwdAgents — conservative all-or-nothing migration helper
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("cleanupPerCwdAgents — conservative all-or-nothing cleanup", () => {
+	let perCwdAgentsDir: string;
+	let perCwdManifest: string;
+
+	beforeEach(() => {
+		perCwdAgentsDir = join(cwd, ".pi", "agents");
+		perCwdManifest = join(perCwdAgentsDir, ".rpiv-managed.json");
+	});
+
+	it("returns empty when no .pi/agents/ directory exists", () => {
+		const r = cleanupPerCwdAgents(cwd);
+		expect(r.cleanedUp).toEqual([]);
+		expect(r.skipped).toEqual([]);
+		expect(r.errors).toEqual([]);
+	});
+
+	it("skips with reason=unmanaged when manifest is missing (hand-managed directory)", () => {
+		mkdirSync(perCwdAgentsDir, { recursive: true });
+		writeFileSync(join(perCwdAgentsDir, "custom.md"), "user content", "utf-8");
+
+		const r = cleanupPerCwdAgents(cwd);
+
+		expect(r.skipped.length).toBe(1);
+		expect(r.skipped[0].reason).toBe(CLEANUP_SKIP_REASON.UNMANAGED);
+		expect(existsSync(perCwdAgentsDir)).toBe(true);
+	});
+
+	it("skips with reason=diverged when a managed file is user-edited", () => {
+		const bundled = bundledNames();
+		if (bundled.length === 0) return;
+		mkdirSync(perCwdAgentsDir, { recursive: true });
+		const manifest: Record<string, string> = {};
+		for (const name of bundled) {
+			writeFileSync(join(perCwdAgentsDir, name), "user edited", "utf-8");
+			manifest[name] = sha256("user edited");
+		}
+		writeFileSync(perCwdManifest, JSON.stringify(manifest), "utf-8");
+
+		const r = cleanupPerCwdAgents(cwd);
+
+		expect(r.skipped.length).toBe(1);
+		expect(r.skipped[0].reason).toBe(CLEANUP_SKIP_REASON.DIVERGED);
+		expect(existsSync(perCwdAgentsDir)).toBe(true);
+	});
+
+	it("skips with reason=custom-files when non-managed files exist alongside matching managed files", () => {
+		const bundled = bundledNames();
+		if (bundled.length === 0) return;
+		mkdirSync(perCwdAgentsDir, { recursive: true });
+		const manifest: Record<string, string> = {};
+		for (const name of bundled) {
+			writeFileSync(join(perCwdAgentsDir, name), bundledContent(name), "utf-8");
+			manifest[name] = sha256(bundledContent(name));
+		}
+		writeFileSync(join(perCwdAgentsDir, "my-custom.md"), "user content", "utf-8");
+		writeFileSync(perCwdManifest, JSON.stringify(manifest), "utf-8");
+
+		const r = cleanupPerCwdAgents(cwd);
+
+		expect(r.skipped.length).toBe(1);
+		expect(r.skipped[0].reason).toBe(CLEANUP_SKIP_REASON.CUSTOM_FILES);
+		expect(existsSync(perCwdAgentsDir)).toBe(true);
+		expect(existsSync(join(perCwdAgentsDir, "my-custom.md"))).toBe(true);
+	});
+
+	describe("summarizeCleanupSkips", () => {
+		it("returns empty string for no skips", () => {
+			expect(summarizeCleanupSkips([])).toBe("");
+		});
+
+		it("formats a single reason", () => {
+			expect(summarizeCleanupSkips([{ dir: "/a", reason: CLEANUP_SKIP_REASON.DIVERGED }])).toBe("1 with user edits");
+		});
+
+		it("aggregates and orders reasons (unmanaged, diverged, custom-files)", () => {
+			const skips = [
+				{ dir: "/a", reason: CLEANUP_SKIP_REASON.DIVERGED },
+				{ dir: "/b", reason: CLEANUP_SKIP_REASON.UNMANAGED },
+				{ dir: "/c", reason: CLEANUP_SKIP_REASON.CUSTOM_FILES },
+				{ dir: "/d", reason: CLEANUP_SKIP_REASON.DIVERGED },
+			];
+			expect(summarizeCleanupSkips(skips)).toBe("1 unmanaged, 2 with user edits, 1 with custom files");
+		});
+	});
+
+	it("removes directory when all managed files match source and no extras", () => {
+		const bundled = bundledNames();
+		if (bundled.length === 0) return;
+		mkdirSync(perCwdAgentsDir, { recursive: true });
+		const manifest: Record<string, string> = {};
+		for (const name of bundled) {
+			writeFileSync(join(perCwdAgentsDir, name), bundledContent(name), "utf-8");
+			manifest[name] = sha256(bundledContent(name));
+		}
+		writeFileSync(perCwdManifest, JSON.stringify(manifest), "utf-8");
+
+		const r = cleanupPerCwdAgents(cwd);
+
+		expect(r.cleanedUp.length).toBe(1);
+		expect(r.skipped).toEqual([]);
+		expect(existsSync(perCwdAgentsDir)).toBe(false);
+	});
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Unified safety predicate — exercised indirectly through syncBundledAgents,
 // pinned here directly so the three branches stay regression-checked.

package/extensions/rpiv-core/agents.ts

@@ -1,20 +1,34 @@
 /**
- * Agent auto-copy — copies bundled agents into <cwd>/.pi/agents/.
+ * Agent auto-copy — copies bundled agents into ~/.pi/agent/agents/.
  *
  * Pure utility. No ExtensionAPI interactions.
  *
- * Concurrency: NOT safe across multiple Pi sessions sharing one cwd. Two
- * sessions racing here may produce a partial manifest where the loser's
- * mutations are untracked. Per-cwd advisory locking is a deferred follow-up
- * (see CHANGELOG known-limitations and review findings Q12/Q13). The path
- * allowlist in readManifest neutralises the worst-case (arbitrary-path
- * unlink) regardless of concurrency.
+ * Concurrency: NOT safe across multiple Pi sessions sharing one target dir.
+ * The temp+rename atomic write in writeManifest guarantees the on-disk manifest
+ * file is always a complete valid JSON (no truncated/half-written content), but
+ * the read-modify-write lost-update problem remains: two sessions both reading
+ * the manifest before either writes will race, and the second writer overwrites
+ * the first's entries with its own stale snapshot. Advisory locking is a
+ * deferred follow-up (see CHANGELOG known-limitations). The path allowlist in
+ * readManifest neutralises the worst-case (arbitrary-path unlink) regardless of
+ * concurrency.
  */
 
 import { createHash } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { isPlainObject, toErrorMessage } from "./utils.js";
 
 // ---------------------------------------------------------------------------
@@ -86,6 +100,61 @@ function emptySyncResult(): SyncResult {
 	};
 }
 
+/** Discriminant for why a per-cwd directory was left intact. */
+export const CLEANUP_SKIP_REASON = {
+	/** No manifest present — directory was never installed by rpiv (hand-managed). */
+	UNMANAGED: "unmanaged",
+	/** Managed file content diverges from current bundle source (user edit, deletion, or source change). */
+	DIVERGED: "diverged",
+	/** Directory contains non-managed files (user added custom agents). */
+	CUSTOM_FILES: "custom-files",
+} as const;
+
+export type CleanupSkipReason = (typeof CLEANUP_SKIP_REASON)[keyof typeof CLEANUP_SKIP_REASON];
+
+export interface CleanupSkip {
+	dir: string;
+	reason: CleanupSkipReason;
+}
+
+export interface CleanupResult {
+	/** Per-cwd agent directories successfully removed (all managed files matched source). */
+	cleanedUp: string[];
+	/** Directories preserved with discriminated reason — see CLEANUP_SKIP_REASON. */
+	skipped: CleanupSkip[];
+	/** Per-file errors collected during cleanup. */
+	errors: SyncError[];
+}
+
+/** Create an empty CleanupResult with all arrays initialized. */
+function emptyCleanupResult(): CleanupResult {
+	return {
+		cleanedUp: [],
+		skipped: [],
+		errors: [],
+	};
+}
+
+/**
+ * Format skip counts as a comma-joined parts list ("N edited, M with custom files").
+ * Shared by session_start notifyCleanup and /rpiv-update-agents handler so the
+ * two consumer surfaces describe preserved directories identically.
+ */
+export function summarizeCleanupSkips(skipped: CleanupSkip[]): string {
+	if (skipped.length === 0) return "";
+	const counts: Record<CleanupSkipReason, number> = {
+		unmanaged: 0,
+		diverged: 0,
+		"custom-files": 0,
+	};
+	for (const s of skipped) counts[s.reason]++;
+	const parts: string[] = [];
+	if (counts.unmanaged > 0) parts.push(`${counts.unmanaged} unmanaged`);
+	if (counts.diverged > 0) parts.push(`${counts.diverged} with user edits`);
+	if (counts["custom-files"] > 0) parts.push(`${counts["custom-files"]} with custom files`);
+	return parts.join(", ");
+}
+
 // ---------------------------------------------------------------------------
 // Path-traversal allowlist (I2 — hardens the manifest reader boundary)
 // ---------------------------------------------------------------------------
@@ -215,7 +284,23 @@ function writeManifest(targetDir: string, manifest: Manifest, result: SyncResult
 	try {
 		const ordered: Manifest = {};
 		for (const k of Object.keys(manifest).sort()) ordered[k] = manifest[k];
-		writeFileSync(manifestPath, `${JSON.stringify(ordered, null, 2)}\n`, "utf-8");
+		const content = `${JSON.stringify(ordered, null, 2)}\n`;
+		// Atomic write: tmp file in same dir + renameSync (POSIX same-filesystem guarantee).
+		// Prevents write-write corruption under widened concurrency (global target).
+		// Pid-suffixed so concurrent sessions don't unlink each other's in-flight tmp files
+		// on the failure path (see catch's unlinkSync below).
+		const tmpFile = join(targetDir, `${MANIFEST_FILE}.${process.pid}.tmp`);
+		try {
+			writeFileSync(tmpFile, content, "utf-8");
+			renameSync(tmpFile, manifestPath);
+		} catch (inner) {
+			try {
+				unlinkSync(tmpFile);
+			} catch {
+				/* ignore */
+			}
+			throw inner;
+		}
 	} catch (e) {
 		result.errors.push({
 			op: SYNC_OP.MANIFEST_WRITE,
@@ -420,7 +505,7 @@ function commitStaleUnlinks(
 // ---------------------------------------------------------------------------
 
 /**
- * Synchronize bundled agents from <PACKAGE_ROOT>/agents/ into <cwd>/.pi/agents/.
+ * Synchronize bundled agents from <PACKAGE_ROOT>/agents/ into ~/.pi/agent/agents/.
  *
  * Resolution policy (apply=false, session_start):
  *   - New source files → always copied.
@@ -430,7 +515,7 @@ function commitStaleUnlinks(
  *     - V2 marker absent (legacy v1, missing, or never-installed) → auto-update;
  *       package wins. Triggers exactly while transitioning to v2; the marker
  *       file (.rpiv-managed.v2) is written once committed and never re-fires
- *       for this project, surviving JSON corruption / partial writes / empty-
+ *       for this installation, surviving JSON corruption / partial writes / empty-
  *       hash collapse.
  *     - otherwise (V2 marker present, dest differs from recorded hash) →
  *       pendingUpdate (gated; respects user edits).
@@ -445,14 +530,14 @@ function commitStaleUnlinks(
  *
  * Never throws — errors are collected in `result.errors`.
  */
-export function syncBundledAgents(cwd: string, apply: boolean): SyncResult {
+export function syncBundledAgents(apply: boolean): SyncResult {
 	const result = emptySyncResult();
 
 	if (!existsSync(BUNDLED_AGENTS_DIR)) {
 		return result;
 	}
 
-	const targetDir = join(cwd, ".pi", "agents");
+	const targetDir = join(getAgentDir(), "agents");
 	try {
 		mkdirSync(targetDir, { recursive: true });
 	} catch (e) {
@@ -488,3 +573,97 @@ export function syncBundledAgents(cwd: string, apply: boolean): SyncResult {
 
 	return result;
 }
+
+/**
+ * Clean up per-cwd agent directories from pre-global-sync installs.
+ *
+ * Conservative all-or-nothing gate: removes `<cwd>/.pi/agents/` only when:
+ *   1. A manifest exists (we installed these files)
+ *   2. Every managed file matches current source content
+ *   3. No non-managed files exist in the directory
+ *
+ * If any check fails, the directory is left intact. Never throws — errors
+ * are collected in the CleanupResult.
+ */
+export function cleanupPerCwdAgents(cwd: string): CleanupResult {
+	const result = emptyCleanupResult();
+	const perCwdDir = join(cwd, ".pi", "agents");
+
+	if (!existsSync(perCwdDir)) return result;
+	const manifest = readManifest(perCwdDir);
+	if (Object.keys(manifest).length === 0) {
+		// Edge state 1: no manifest (never synced by us, or hand-managed)
+		result.skipped.push({ dir: perCwdDir, reason: CLEANUP_SKIP_REASON.UNMANAGED });
+		return result;
+	}
+
+	// Edge state 2: verify all managed files match current source content
+	for (const [name] of Object.entries(manifest)) {
+		const srcPath = safeJoin(BUNDLED_AGENTS_DIR, name);
+		const destPath = safeJoin(perCwdDir, name);
+		if (srcPath === null || destPath === null) {
+			// Crafted manifest key would escape allowlist — treat as unmanaged.
+			result.skipped.push({ dir: perCwdDir, reason: CLEANUP_SKIP_REASON.UNMANAGED });
+			return result;
+		}
+
+		let srcContent: Buffer;
+		try {
+			srcContent = readFileSync(srcPath);
+		} catch {
+			// Source file no longer exists — can't verify against bundle, treat as diverged.
+			result.skipped.push({ dir: perCwdDir, reason: CLEANUP_SKIP_REASON.DIVERGED });
+			return result;
+		}
+
+		if (!existsSync(destPath)) {
+			// Managed file missing from disk — user deleted it, treat as diverged.
+			result.skipped.push({ dir: perCwdDir, reason: CLEANUP_SKIP_REASON.DIVERGED });
+			return result;
+		}
+
+		let destContent: Buffer;
+		try {
+			destContent = readFileSync(destPath);
+		} catch (e) {
+			// Hard failure — surface as error only (do not double-count in skipped).
+			result.errors.push({ op: SYNC_OP.READ_DEST, message: toErrorMessage(e) });
+			return result;
+		}
+
+		if (sha256(destContent) !== sha256(srcContent)) {
+			// User edited this file — conservative gate.
+			result.skipped.push({ dir: perCwdDir, reason: CLEANUP_SKIP_REASON.DIVERGED });
+			return result;
+		}
+	}
+
+	// Edge state 3: check for non-managed files
+	try {
+		const allFiles = readdirSync(perCwdDir);
+		const managedNames = new Set(Object.keys(manifest));
+		const managedMetadata = new Set([MANIFEST_FILE, V2_MARKER_FILE]);
+		for (const f of allFiles) {
+			if (!managedNames.has(f) && !managedMetadata.has(f)) {
+				// Non-managed file present (user custom agent or other content)
+				result.skipped.push({ dir: perCwdDir, reason: CLEANUP_SKIP_REASON.CUSTOM_FILES });
+				return result;
+			}
+		}
+	} catch (e) {
+		// Hard failure — surface as error only (do not double-count in skipped).
+		result.errors.push({ op: SYNC_OP.READ_DEST, message: toErrorMessage(e) });
+		return result;
+	}
+
+	// Happy path: all checks passed, safe to remove
+	try {
+		rmSync(perCwdDir, { recursive: true, force: true });
+		result.cleanedUp.push(perCwdDir);
+	} catch (e) {
+		// Hard failure — surface as error only (do not double-count in skipped).
+		result.errors.push({ op: SYNC_OP.REMOVE, message: toErrorMessage(e) });
+	}
+
+	return result;
+}

package/extensions/rpiv-core/session-hooks.test.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { createMockCtx, createMockPi, stubGitExec } from "@juicesharp/rpiv-test-utils";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -18,11 +18,16 @@ vi.mock("./agents.js", async (importOriginal) => {
 			pendingRemove: [],
 			errors: [],
 		})),
+		cleanupPerCwdAgents: vi.fn(() => ({
+			cleanedUp: [],
+			skipped: [],
+			errors: [],
+		})),
 	};
 });
 
 import type { SyncResult } from "./agents.js";
-import { SYNC_OP, syncBundledAgents } from "./agents.js";
+import { cleanupPerCwdAgents, SYNC_OP, syncBundledAgents } from "./agents.js";
 import { clearGitContextCache, getGitContext, resetInjectedMarker, takeGitContextIfChanged } from "./git-context.js";
 import { clearInjectionState } from "./guidance.js";
 import { findMissingSiblings } from "./package-checks.js";
@@ -161,6 +166,64 @@ describe("session_start hook — notifications", () => {
 		expect(healCall?.[1]).toBe("info");
 	});
 
+	it("notifyCleanup: emits 'Cleaned up' info when cleanedUp > 0", async () => {
+		vi.mocked(syncBundledAgents).mockReturnValueOnce(emptySync);
+		vi.mocked(cleanupPerCwdAgents).mockReturnValueOnce({
+			cleanedUp: ["/tmp/old-project/.pi/agents"],
+			skipped: [],
+			errors: [],
+		});
+		vi.mocked(findMissingSiblings).mockReturnValueOnce([]);
+		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+		registerSessionHooks(pi);
+		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+		await captured.events.get("session_start")?.[0]({ reason: "startup" } as never, ctx as never);
+		const cleanCall = (ctx.ui.notify as ReturnType<typeof vi.fn>).mock.calls.find(
+			(c) => typeof c[0] === "string" && /Cleaned up \d+ per-project agent/.test(c[0]),
+		);
+		expect(cleanCall).toBeDefined();
+		expect(cleanCall?.[1]).toBe("info");
+	});
+
+	it("notifyCleanup: emits 'Preserved ...' info with reason summary when skipped > 0", async () => {
+		vi.mocked(syncBundledAgents).mockReturnValueOnce(emptySync);
+		vi.mocked(cleanupPerCwdAgents).mockReturnValueOnce({
+			cleanedUp: [],
+			skipped: [{ dir: "/tmp/old-project/.pi/agents", reason: "diverged" }],
+			errors: [],
+		});
+		vi.mocked(findMissingSiblings).mockReturnValueOnce([]);
+		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+		registerSessionHooks(pi);
+		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+		await captured.events.get("session_start")?.[0]({ reason: "startup" } as never, ctx as never);
+		const skipCall = (ctx.ui.notify as ReturnType<typeof vi.fn>).mock.calls.find(
+			(c) => typeof c[0] === "string" && /Preserved \d+ per-project agent/.test(c[0]),
+		);
+		expect(skipCall).toBeDefined();
+		expect(skipCall?.[0]).toContain("1 with user edits");
+		expect(skipCall?.[1]).toBe("info");
+	});
+
+	it("notifyCleanup: emits warning when cleanup errors > 0", async () => {
+		vi.mocked(syncBundledAgents).mockReturnValueOnce(emptySync);
+		vi.mocked(cleanupPerCwdAgents).mockReturnValueOnce({
+			cleanedUp: [],
+			skipped: [],
+			errors: [{ op: SYNC_OP.REMOVE, message: "EACCES" }],
+		});
+		vi.mocked(findMissingSiblings).mockReturnValueOnce([]);
+		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
+		registerSessionHooks(pi);
+		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
+		await captured.events.get("session_start")?.[0]({ reason: "startup" } as never, ctx as never);
+		const warnCall = (ctx.ui.notify as ReturnType<typeof vi.fn>).mock.calls.find(
+			(c) => c[1] === "warning" && typeof c[0] === "string" && /Agent cleanup reported/.test(c[0]),
+		);
+		expect(warnCall).toBeDefined();
+		expect(warnCall?.[0]).toContain("1 error");
+	});
+
 	it("I3: emits a 'sync errors' warning when result.errors > 0", async () => {
 		vi.mocked(syncBundledAgents).mockReturnValueOnce({
 			...emptySync,
@@ -191,14 +254,14 @@ describe("G0: session_start → real syncBundledAgents → notifyAgentSyncDrift"
 
 	it("on a fresh tmp cwd, copies bundled agents and emits a single 'Copied N agents' info", async () => {
 		const real = await vi.importActual<typeof import("./agents.js")>("./agents.js");
-		vi.mocked(syncBundledAgents).mockImplementationOnce((cwd, apply) => real.syncBundledAgents(cwd, apply));
+		vi.mocked(syncBundledAgents).mockImplementationOnce((apply) => real.syncBundledAgents(apply));
 
 		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
 		registerSessionHooks(pi);
 		const ctx = createMockCtx({ cwd: projectDir, hasUI: true });
 		await captured.events.get("session_start")?.[0]({ reason: "startup" } as never, ctx as never);
 
-		const agentsDir = join(projectDir, ".pi", "agents");
+		const agentsDir = join(homedir(), ".pi", "agent", "agents");
 		expect(existsSync(agentsDir)).toBe(true);
 		expect(existsSync(join(agentsDir, ".rpiv-managed.json"))).toBe(true);
 		expect(existsSync(join(agentsDir, ".rpiv-managed.v2"))).toBe(true);
@@ -216,7 +279,7 @@ describe("G0: session_start → real syncBundledAgents → notifyAgentSyncDrift"
 
 	it("on a second cold-start, reports unchanged (no Copied / no Synced / no drift)", async () => {
 		const real = await vi.importActual<typeof import("./agents.js")>("./agents.js");
-		vi.mocked(syncBundledAgents).mockImplementation((cwd, apply) => real.syncBundledAgents(cwd, apply));
+		vi.mocked(syncBundledAgents).mockImplementation((apply) => real.syncBundledAgents(apply));
 
 		const { pi, captured } = createMockPi({ exec: stubGitExec({}) as never });
 		registerSessionHooks(pi);

package/extensions/rpiv-core/session-hooks.ts

@@ -13,7 +13,13 @@ import {
 	isToolCallEventType,
 	type ToolCallEvent,
 } from "@earendil-works/pi-coding-agent";
-import { type SyncResult, syncBundledAgents } from "./agents.js";
+import {
+	type CleanupResult,
+	cleanupPerCwdAgents,
+	type SyncResult,
+	summarizeCleanupSkips,
+	syncBundledAgents,
+} from "./agents.js";
 import { FLAG_DEBUG, MSG_TYPE_GIT_CONTEXT } from "./constants.js";
 import {
 	clearGitContextCache,
@@ -33,7 +39,7 @@ const THOUGHTS_DIRS = [
 	"thoughts/shared/reviews",
 ] as const;
 
-const msgAgentsAdded = (n: number) => `Copied ${n} rpiv-pi agent(s) to .pi/agents/`;
+const msgAgentsAdded = (n: number) => `Copied ${n} rpiv-pi agent(s) to ~/.pi/agent/agents/`;
 const msgAgentsHealed = (parts: string[]) => `Synced bundled agent(s): ${parts.join(", ")}.`;
 const msgAgentsDrift = (parts: string[]) => `${parts.join(", ")} agent(s). Run /rpiv-update-agents to sync.`;
 const msgAgentsErrors = (n: number) => `Agent sync reported ${n} error(s). Run /rpiv-update-agents for details.`;
@@ -79,8 +85,10 @@ async function onSessionStart(
 	injectRootGuidance(ctx.cwd, pi);
 	scaffoldThoughtsDirs(ctx.cwd);
 	await injectGitContext(pi, (msg) => sendGitContextMessage(pi, msg));
-	const agents = syncBundledAgents(ctx.cwd, false);
+	const cleanup = cleanupPerCwdAgents(ctx.cwd);
+	const agents = syncBundledAgents(false);
 	if (ctx.hasUI) {
+		notifyCleanup(ctx.ui, cleanup);
 		notifyAgentSyncDrift(ctx.ui, agents);
 		warnMissingSiblings(ctx.ui);
 	}
@@ -157,6 +165,21 @@ function notifyAgentSyncDrift(ui: UI, result: SyncResult): void {
 	}
 }
 
+function notifyCleanup(ui: UI, result: CleanupResult): void {
+	if (result.cleanedUp.length > 0) {
+		ui.notify(`Cleaned up ${result.cleanedUp.length} per-project agent directory (migrated to global)`, "info");
+	}
+	if (result.skipped.length > 0) {
+		ui.notify(
+			`Preserved ${result.skipped.length} per-project agent directory (${summarizeCleanupSkips(result.skipped)})`,
+			"info",
+		);
+	}
+	if (result.errors.length > 0) {
+		ui.notify(`Agent cleanup reported ${result.errors.length} error(s)`, "warning");
+	}
+}
+
 function warnMissingSiblings(ui: UI): void {
 	const missing = findMissingSiblings();
 	if (missing.length === 0) return;

package/extensions/rpiv-core/update-agents-command.test.ts

@@ -11,13 +11,18 @@ vi.mock("./agents.js", () => ({
 		MKDIR: "mkdir",
 	},
 	syncBundledAgents: vi.fn(),
+	cleanupPerCwdAgents: vi.fn(),
 }));
 
-import { SYNC_OP, syncBundledAgents } from "./agents.js";
+import { cleanupPerCwdAgents, SYNC_OP, syncBundledAgents } from "./agents.js";
 import { registerUpdateAgentsCommand } from "./update-agents-command.js";
 
+const emptyCleanup = () => ({ cleanedUp: [], skipped: [], errors: [] });
+
 beforeEach(() => {
 	vi.mocked(syncBundledAgents).mockReset();
+	vi.mocked(cleanupPerCwdAgents).mockReset();
+	vi.mocked(cleanupPerCwdAgents).mockReturnValue(emptyCleanup());
 });
 
 const empty = (overrides: Partial<ReturnType<typeof syncBundledAgents>> = {}) => ({

package/extensions/rpiv-core/update-agents-command.ts

@@ -1,10 +1,11 @@
 /**
- * /rpiv-update-agents — apply-mode sync of bundled agents into <cwd>/.pi/agents/.
+ * /rpiv-update-agents — apply-mode sync of bundled agents into ~/.pi/agent/agents/.
+ * Also cleans up legacy per-cwd agent directories.
  * Adds new, overwrites changed managed files, removes stale managed files.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { type SyncResult, syncBundledAgents } from "./agents.js";
+import { cleanupPerCwdAgents, type SyncResult, summarizeCleanupSkips, syncBundledAgents } from "./agents.js";
 
 const MSG_UP_TO_DATE = "All agents already up-to-date.";
 const MSG_NO_CHANGES = "No changes needed.";
@@ -15,11 +16,20 @@ const msgSyncedWithErrors = (summary: string, errors: string[]) =>
 
 export function registerUpdateAgentsCommand(pi: ExtensionAPI): void {
 	pi.registerCommand("rpiv-update-agents", {
-		description: "Sync rpiv-pi bundled agents into .pi/agents/: add new, update changed, remove stale",
+		description:
+			"Sync rpiv-pi bundled agents into ~/.pi/agent/agents/: add new, update changed, remove stale. Also cleans up legacy per-project agent directories.",
 		handler: async (_args, ctx) => {
-			const result = syncBundledAgents(ctx.cwd, true);
+			const cleanup = cleanupPerCwdAgents(ctx.cwd);
+			const result = syncBundledAgents(true);
 			if (!ctx.hasUI) return;
-			ctx.ui.notify(formatSyncReport(result), result.errors.length > 0 ? "warning" : "info");
+			const parts: string[] = [];
+			if (cleanup.cleanedUp.length > 0) parts.push(`${cleanup.cleanedUp.length} old dir(s) cleaned up`);
+			if (cleanup.skipped.length > 0)
+				parts.push(`${cleanup.skipped.length} old dir(s) preserved (${summarizeCleanupSkips(cleanup.skipped)})`);
+			if (cleanup.errors.length > 0) parts.push(`${cleanup.errors.length} cleanup error(s)`);
+			const syncReport = formatSyncReport(result);
+			const fullReport = parts.length > 0 ? `${parts.join(", ")}. ${syncReport}` : syncReport;
+			ctx.ui.notify(fullReport, result.errors.length + cleanup.errors.length > 0 ? "warning" : "info");
 		},
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "description": "A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",