osdy-pi 1.5.0 → 1.6.1

package/README.md

@@ -34,7 +34,7 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
    pi install git:github.com/OsdyOrtiz/Osdy-Pi
    ```
 
-   Already using a pinned npm version? `pi update` does not move a pinned version. First-party TODO is included starting in 1.5.0; until that version is published, npm `latest` may still resolve to an earlier release. Check the resolved version or use a checkout to evaluate 1.5.0 before publication. Installing Osdy does not automatically install Joker; see [explicit agents setup](#explicit-joker-agents-setup-in-normal-pi).
+   Already using a pinned npm version? `pi update` does not move a pinned version. First-party TODO is included starting in 1.5.0. Starting in 1.6.0, `/osdy-pi uninstall` and explicit agent provider modes are available. Check the resolved version when installing from npm or use a 1.6.0-or-later checkout to try these changes. Installing Osdy does not automatically install Joker; see [explicit agent provider modes](#explicit-agent-provider-modes-in-normal-pi).
 
 2. Start Pi:
 
@@ -100,7 +100,7 @@ git clone https://github.com/Gentleman-Programming/gentle-pi.git
 osdy-pi gentle setup "$(pwd)/gentle-pi"
 ```
 
-## Explicit Joker agents setup in normal Pi
+## Explicit agent provider modes in normal Pi
 
 After `pi install npm:osdy-pi`, open **normal personal Pi** (not `osdy`'s isolated profile) and run:
 
@@ -108,9 +108,11 @@ After `pi install npm:osdy-pi`, open **normal personal Pi** (not `osdy`'s isolat
 /osdy-pi agents setup
 ```
 
-Review the confirmation: it names `~/.pi/agent/settings.json`, installs `npm:pi-subagents-j0k3r` using Pi's package command, and adds only `-extensions/gentle-agents.ts` to each eligible Gentle package entry. It preserves unrelated settings and Gentle resources; if no Gentle package is present, it only installs Joker. After success, Pi reloads resources (restart Pi if reload fails). `/osdy-pi agents status` checks the personal Joker/Gentle setup without writing. Cancel changes nothing; rerunning is safe. This command is available inside Pi after the Pi package install—no global npm CLI or package postinstall hook is required.
+`/osdy-pi agents setup` and `/osdy-pi agents on` ensure **Joker mode**: install Joker with Pi if absent, enable its package extension (`./index.ts`), and exclude only `-extensions/gentle-agents.ts` from eligible Gentle entries. `/osdy-pi agents off` selects **Gentle mode**: require an eligible Gentle package first, exclude only Joker's `./index.ts` using `-./index.ts` in its package entry (if installed), and remove Gentle's agents exclusion. Both packages and all unrelated resources stay installed. `/osdy-pi agents status` reports the settings-derived mode (`joker`, `gentle`, `mixed`, or `unavailable`) without writing. Confirm the named `~/.pi/agent/settings.json` change; after success Pi reloads resources, or prompts a restart if reload fails. Cancel changes nothing; repeating either mode is safe. No runtime task-failure fallback is provided.
 
-Gentle package detection supports `npm:gentle-pi` and validated local checkouts (absolute, settings-relative, `~/`, and `file:` paths). Remote Git/HTTPS Gentle sources are not reconciled: when recognized, setup stops before installing Joker rather than reporting a false success. Register a local Gentle checkout or npm Gentle source in personal Pi first; the existing `osdy-pi gentle setup /absolute/path/to/gentle-pi` command can configure local coexistence if you have that CLI. Setup refuses an isolated/custom `$PI_CODING_AGENT_DIR` or a project-local Gentle override because a personal filter cannot reliably control those contexts. Run it in normal Pi without a conflicting project package; an invalid settings file or failed install produces an error rather than silently applying only part of the filter. It does not edit credentials.
+A pre-existing Joker `-./index.ts` filter without Osdy's ownership marker is ambiguous and blocks switching rather than being removed. Osdy records ownership in the personal settings field `osdyPiJokerExclusionOwned` while it owns that filter and removes the field on return to Joker mode. Existing Gentle agents exclusions are removed by `off`, including exclusions configured before this feature; review that change before confirming. Other package fields and extension filters remain intact. An extension allowlist that omits the agent extension needed for the selected mode blocks switching rather than silently reporting success.
+
+Gentle package detection supports `npm:gentle-pi` and validated local checkouts (absolute, settings-relative, `~/`, and `file:` paths). Remote Git/HTTPS Gentle sources are not reconciled: when recognized, setup stops before installing Joker rather than reporting a false success. Register a local Gentle checkout or npm Gentle source in personal Pi first; the existing `osdy-pi gentle setup /absolute/path/to/gentle-pi` command can configure local coexistence if you have that CLI. Mode switching refuses an isolated/custom `$PI_CODING_AGENT_DIR` or a project-local Gentle override because a personal filter cannot reliably control those contexts. Run it in normal Pi without a conflicting project package; an invalid settings file or failed install produces an error rather than silently applying only part of the filter. It does not edit credentials.
 
 ## Gentle coexistence setup
 
@@ -124,7 +126,7 @@ The command validates that the absolute source is a readable `gentle-pi` package
 
 Gentle Shell intentionally remains fully active underneath Osdy, including its footer and widgets. While Osdy is enabled, Osdy claims the footer and editor; disabling Osdy restores the editor Gentle Shell provided at session startup. Gentle's changes widget may coexist with Osdy's visual widgets.
 
-The exclusions prevent Gentle's todo, questionnaire, and agents extensions from competing with the suite. Osdy's session-branch snapshots are authoritative for its `todo` tool and read-only `/todos` command; `pi-subagents-j0k3r` remains the subagent system and `@juicesharp/rpiv-ask-user-question` remains the structured-question plugin. This setup does **not** remove an independently installed `@juicesharp/rpiv-todo` package or edit its package entry. Remove that package yourself as described below to avoid duplicate `todo` and `/todos` registrations.
+The exclusions prevent Gentle's todo, questionnaire, and agents extensions from competing with the suite. Osdy's session-branch snapshots are authoritative for its `todo` tool and read-only `/todos` command; `pi-subagents-j0k3r` is the subagent system in Joker mode (Gentle agents in Gentle mode) and `@juicesharp/rpiv-ask-user-question` remains the structured-question plugin. This setup does **not** remove an independently installed `@juicesharp/rpiv-todo` package or edit its package entry. Remove that package yourself as described below to avoid duplicate `todo` and `/todos` registrations.
 
 ## First-party TODO included starting in 1.5.0
 
@@ -134,7 +136,7 @@ In interactive Pi, the persistent widget appears above the editor while visible
 
 ### Try session TODO
 
-Use a 1.5.0 checkout (or an installed 1.5.0 package once published), ask the agent to track a task with `todo`, then run `/todos`. The widget shows up to five tasks by default; the modal shows the entire grouped list with arrow/Page Up/Down scrolling. If your `maxWidgetLines` configuration overrides the default, set it to `7` to show five task rows.
+Use an installed 1.5.0-or-later package (or a checkout), ask the agent to track a task with `todo`, then run `/todos`. The widget shows up to five tasks by default; the modal shows the entire grouped list with arrow/Page Up/Down scrolling. If your `maxWidgetLines` configuration overrides the default, set it to `7` to show five task rows.
 
 **Verification to date (not complete):** Prior feature checks passed 187 extension tests, 60 script tests, typecheck, and lint. A disposable Pi TUI with seeded tasks showed the modal's progress meter, grouped rows, scroll footer, and close behavior. Authenticated RPC turns exercised all six `todo` actions, and an authenticated TUI smoke observed widget and `/todos` updates. An RPC lifecycle check observed an empty new session and the completed task on switching back. Compaction replay remains unverified because Pi returned “Nothing to compact (session too small).” Language switching in the authenticated TODO flow remains unverified (an isolated TUI with both extensions did switch English to Spanish). Visual strikethrough of completed rows in the authenticated TUI remains unverified. Launch under an installed Osdy account profile remains unverified. These checks do not establish full feature parity or validate a published npm artifact.
 
@@ -337,8 +339,11 @@ The enabled state, editor mode, working-tree visibility preference, header, and
 | Working tree | `/osdy-pi working-tree position top\|bottom\|status` |
 | Audio | `/osdy-pi sound setup` |
 | Diff | `/osdy-pi diff` |
+| Package | `/osdy-pi uninstall` |
 | Codex subscription | `/usage` |
 
+`/osdy-pi uninstall` finds a unique Osdy Pi package in Pi's configured package list and asks you to confirm its exact source and user/project scope before calling Pi's `remove` command. Run it from a trusted project with interactive UI. Git registrations are checked against Pi's host/path identity; a local registration must point to this running extension's package root and have a matching manifest. Ambiguous or changed registrations, unrecognized sources, and cancelled confirmation remove nothing. It removes only the Pi package registration, not Osdy profiles, accounts, the globally installed CLI, or other packages. Restart Pi afterward to unload the extension. If no unique source is found, inspect `pi list` and use `pi remove <source> [-l]` manually.
+
 `/osdy-pi` reports status. `enable` (or `on`) applies the Osdy Pi UI without changing the selected Pi theme; `disable` (or `off`) restores the Gentle Shell or Pi UI captured at session startup while preserving that theme. The enabled state, editor mode, working-tree visibility, and sound configuration persist globally.
 
 ### Codex subscription usage

package/extensions/osdy-pi/agent-coexistence-setup.test.ts

@@ -11,7 +11,7 @@ registerHooks({ resolve(specifier, context, nextResolve) {
 		return { shortCircuit: true, url: new URL("./agent-coexistence-setup.ts", context.parentURL).href };
 	return nextResolve(specifier, context);
 } });
-const { setupJokerAgents } = await import("./agent-coexistence-setup.js");
+const { setupJokerAgents, switchAgentMode, inspectJokerAgents } = await import("./agent-coexistence-setup.js");
 
 async function fixture() {
 	const root = await mkdtemp(join(tmpdir(), "osdy-joker-"));
@@ -30,6 +30,167 @@ const base = (f: Awaited<ReturnType<typeof fixture>>) => ({
 	agentDir: f.agentDir, home: f.root, cwd: f.root, env: {},
 });
 
+void test("off filters only Joker's extension and enables Gentle; on reverses, both idempotently", async () => {
+	const f = await fixture();
+	await writeFile(f.settingsPath, JSON.stringify({ packages: [...f.packages, { source: "npm:pi-subagents-j0k3r", skills: ["skills/*"], extensions: ["-other.ts"] }] }));
+	await switchAgentMode({ ...base(f), mode: "off" });
+	const off = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: Array<unknown>; osdyPiJokerExclusionOwned: boolean };
+	assert.equal(off.osdyPiJokerExclusionOwned, true);
+	assert.deepEqual(off.packages.at(-1), { source: "npm:pi-subagents-j0k3r", skills: ["skills/*"], extensions: ["-other.ts", "-./index.ts"] });
+	assert.deepEqual(off.packages.slice(1, 4), [
+		{ source: f.gentle, extensions: ["-extensions/gentle-todo.ts"], themes: [], skills: ["skills/*"] },
+		"npm:gentle-pi@1.2.0", "npm:gentle-pi",
+	]);
+	assert.equal((await inspectJokerAgents(base(f))).mode, "gentle");
+	assert.equal((await switchAgentMode({ ...base(f), mode: "off" })).changed, false);
+	await switchAgentMode({ ...base(f), mode: "on", install: () => Promise.reject(new Error("should not install")) });
+	assert.equal((await inspectJokerAgents(base(f))).mode, "joker");
+	assert.equal((await switchAgentMode({ ...base(f), mode: "on" })).changed, false);
+	const on = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: Array<unknown>; osdyPiJokerExclusionOwned?: boolean };
+	assert.equal(on.osdyPiJokerExclusionOwned, undefined);
+	assert.deepEqual(on.packages.at(-1), { source: "npm:pi-subagents-j0k3r", skills: ["skills/*"], extensions: ["-other.ts"] });
+});
+
+void test("off refuses without Gentle and unowned Joker filters without writes", async () => {
+	const f = await fixture();
+	await writeFile(f.settingsPath, '{"packages":["npm:pi-subagents-j0k3r"]}');
+	const original = await readFile(f.settingsPath, "utf8");
+	await assert.rejects(switchAgentMode({ ...base(f), mode: "off" }), /Gentle/i);
+	assert.equal(await readFile(f.settingsPath, "utf8"), original);
+	await writeFile(f.settingsPath, '{"packages":["npm:gentle-pi",{"source":"npm:pi-subagents-j0k3r","extensions":["-./index.ts"]}]}');
+	const existing = await readFile(f.settingsPath, "utf8");
+	await assert.rejects(switchAgentMode({ ...base(f), mode: "on" }), /unowned|ownership/i);
+	await assert.rejects(switchAgentMode({ ...base(f), mode: "off" }), /unowned|ownership/i);
+	assert.equal(await readFile(f.settingsPath, "utf8"), existing);
+});
+
+void test("off enables Gentle without installing an absent Joker", async () => {
+	const f = await fixture();
+	const result = await switchAgentMode({ ...base(f), mode: "off", install: () => Promise.reject(new Error("must not install")) });
+	assert.equal(result.installed, false);
+	assert.equal((await inspectJokerAgents(base(f))).mode, "gentle");
+	const settings = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: unknown[]; osdyPiJokerExclusionOwned?: boolean };
+	assert.equal(settings.osdyPiJokerExclusionOwned, undefined);
+	assert.equal(settings.packages.at(-1), "npm:gentle-pi");
+});
+
+void test("off restores string and object Gentle registrations without leaving empty filters", async () => {
+	const f = await fixture();
+	await writeFile(f.settingsPath, JSON.stringify({ theme: "dark", packages: [
+		{ source: "npm:gentle-pi@1.2.0", extensions: ["-extensions/gentle-agents.ts"] },
+		{ source: "npm:gentle-pi", skills: ["skills/*"], extensions: ["-extensions/gentle-agents.ts"] },
+		"npm:pi-subagents-j0k3r",
+	] }));
+	await switchAgentMode({ ...base(f), mode: "off" });
+	const settings = JSON.parse(await readFile(f.settingsPath, "utf8")) as { theme: string; packages: unknown[] };
+	assert.equal(settings.theme, "dark");
+	assert.deepEqual(settings.packages.slice(0, 2), [
+		"npm:gentle-pi@1.2.0",
+		{ source: "npm:gentle-pi", skills: ["skills/*"] },
+	]);
+	assert.equal((await inspectJokerAgents(base(f))).mode, "gentle");
+});
+
+void test("empty extension arrays disable selected agents, including Joker, without writes", async () => {
+	const f = await fixture();
+	for (const [mode, packages] of [
+		["off", [{ source: "npm:gentle-pi", extensions: [] }, "npm:pi-subagents-j0k3r"]],
+		["on", ["npm:gentle-pi", { source: "npm:pi-subagents-j0k3r", extensions: [] }]],
+	] as const) {
+		await writeFile(f.settingsPath, JSON.stringify({ packages }));
+		const before = await readFile(f.settingsPath, "utf8");
+		assert.notEqual((await inspectJokerAgents(base(f))).mode, mode === "off" ? "gentle" : "joker");
+		await assert.rejects(switchAgentMode({ ...base(f), mode }), /allowlist/i);
+		assert.equal(await readFile(f.settingsPath, "utf8"), before);
+	}
+});
+
+void test("mode switches do not turn disabled extension arrays into all-but-agent filters", async () => {
+	const f = await fixture();
+	for (const [mode, packages] of [
+		["on", [{ source: "npm:gentle-pi", extensions: [] }, "npm:pi-subagents-j0k3r", "npm:other"]],
+		["off", ["npm:gentle-pi", { source: "npm:pi-subagents-j0k3r", extensions: [] }, "npm:other"]],
+	] as const) {
+		await writeFile(f.settingsPath, JSON.stringify({ theme: "dark", packages }));
+		const before = await readFile(f.settingsPath, "utf8");
+		let installs = 0;
+		await assert.rejects(switchAgentMode({ ...base(f), mode, install: () => { installs++; return Promise.resolve(); } }), /disabled|empty|extensions/i);
+		assert.equal(installs, 0);
+		assert.equal(await readFile(f.settingsPath, "utf8"), before);
+	}
+});
+
+void test("autoload disabled and Pi exclusion patterns cannot select an agent", async () => {
+	const f = await fixture();
+	for (const [mode, packages] of [
+		["off", [{ source: "npm:gentle-pi", autoload: false }, "npm:pi-subagents-j0k3r"]],
+		["on", ["npm:gentle-pi", { source: "npm:pi-subagents-j0k3r", autoload: false }]],
+		["off", [{ source: "npm:gentle-pi", extensions: ["extensions/gentle-agents.ts", "!extensions/gentle-agents.ts"] }, "npm:pi-subagents-j0k3r"]],
+		["on", ["npm:gentle-pi", { source: "npm:pi-subagents-j0k3r", extensions: ["./index.ts", "!./index.ts"] }]],
+		["on", ["npm:gentle-pi", { source: "npm:pi-subagents-j0k3r", extensions: ["./index.ts", "!*.ts"] }]],
+	] as const) {
+		await writeFile(f.settingsPath, JSON.stringify({ packages }));
+		const before = await readFile(f.settingsPath, "utf8");
+		assert.notEqual((await inspectJokerAgents(base(f))).mode, mode === "off" ? "gentle" : "joker");
+		await assert.rejects(switchAgentMode({ ...base(f), mode }), /autoload|allowlist/i);
+		assert.equal(await readFile(f.settingsPath, "utf8"), before);
+	}
+});
+
+void test("prevalidates known failures before install and reports partial installation on later failure", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = async () => { calls++; await writeFile(f.settingsPath, '{"packages":["npm:pi-subagents-j0k3r"]}'); };
+	await writeFile(f.settingsPath, '{"packages":["npm:gentle-pi"],"osdyPiJokerExclusionOwned":false}');
+	await assert.rejects(switchAgentMode({ ...base(f), mode: "on", install }), /ownership|marker/i);
+	assert.equal(calls, 0);
+	await writeFile(f.settingsPath, '{"packages":["npm:gentle-pi"]}');
+	await assert.rejects(switchAgentMode({ ...base(f), mode: "on", install: async () => {
+		await install();
+		await writeFile(f.settingsPath, "{bad");
+	} }), /Joker may have been installed.*agents status/is);
+	assert.equal(calls, 1);
+});
+
+void test("off retains remaining positive and negative Gentle filters", async () => {
+	const f = await fixture();
+	await writeFile(f.settingsPath, JSON.stringify({ packages: [
+		{ source: "npm:gentle-pi", skills: ["skills/*"], extensions: ["extensions/gentle-agents.ts", "-extensions/gentle-todo.ts", "-extensions/gentle-agents.ts"] },
+		"npm:pi-subagents-j0k3r",
+	] }));
+	await switchAgentMode({ ...base(f), mode: "off" });
+	const settings = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: unknown[] };
+	assert.deepEqual(settings.packages[0], {
+		source: "npm:gentle-pi", skills: ["skills/*"], extensions: ["extensions/gentle-agents.ts", "-extensions/gentle-todo.ts"],
+	});
+	assert.equal((await inspectJokerAgents(base(f))).mode, "gentle");
+});
+
+void test("off validates project override and malformed filters before touching settings", async () => {
+	const f = await fixture();
+	const project = join(f.root, "project");
+	await mkdir(join(project, ".pi"), { recursive: true });
+	await writeFile(join(project, ".pi", "settings.json"), '{"packages":["npm:gentle-pi"]}');
+	await assert.rejects(switchAgentMode({ ...base(f), cwd: project, mode: "off" }), /project-local Gentle/i);
+	await writeFile(f.settingsPath, '{"packages":["npm:gentle-pi",{"source":"npm:pi-subagents-j0k3r","extensions":false}]}');
+	const previous = await readFile(f.settingsPath, "utf8");
+	await assert.rejects(switchAgentMode({ ...base(f), mode: "off" }), /extensions filter/i);
+	assert.equal(await readFile(f.settingsPath, "utf8"), previous);
+});
+
+void test("positive extension allowlists that omit selected agents fail closed", async () => {
+	const f = await fixture();
+	for (const [mode, packages] of [
+		["on", ["npm:gentle-pi", { source: "npm:pi-subagents-j0k3r", extensions: ["./other.ts"] }]],
+		["off", [{ source: "npm:gentle-pi", extensions: ["extensions/gentle-todo.ts"] }, "npm:pi-subagents-j0k3r"]],
+	] as const) {
+		await writeFile(f.settingsPath, JSON.stringify({ packages }));
+		const previous = await readFile(f.settingsPath, "utf8");
+		await assert.rejects(switchAgentMode({ ...base(f), mode }), /allowlist/i);
+		assert.equal(await readFile(f.settingsPath, "utf8"), previous);
+	}
+});
+
 void test("installs Joker then narrowly reconciles every Gentle entry using latest settings", async () => {
 	const f = await fixture();
 	let calls = 0;

package/extensions/osdy-pi/agent-coexistence-setup.ts

@@ -9,6 +9,8 @@ import { fileURLToPath } from "node:url";
 const runFile = promisify(execFile);
 const JOKER = "npm:pi-subagents-j0k3r";
 const GENTLE_EXCLUSION = "-extensions/gentle-agents.ts";
+const JOKER_EXCLUSION = "-./index.ts";
+const OWNED = "osdyPiJokerExclusionOwned";
 
 type Settings = Record<string, unknown> & { packages?: unknown[] };
 
@@ -65,12 +67,6 @@ async function gentle(entry: unknown, settingsDir: string, home: string): Promis
 	}
 }
 
-function validateGentleFilters(entry: unknown): void {
-	if (!object(entry) || entry.extensions === undefined) return;
-	if (!Array.isArray(entry.extensions) || !entry.extensions.every((value: unknown) => typeof value === "string"))
-		throw new Error("Gentle extensions filter must be an array of strings.");
-}
-
 async function regularSettings(path: string): Promise<Settings> {
 	if (!(await lstat(path)).isFile()) throw new Error("Personal settings.json must be a regular file, not a link.");
 	let value: unknown;
@@ -118,19 +114,87 @@ async function installJoker(): Promise<void> {
 	await runFile("pi", ["install", JOKER], { cwd: homedir(), maxBuffer: 4096 });
 }
 
-export async function inspectJokerAgents(options: Omit<SetupOptions, "install">): Promise<{ jokerInstalled: boolean; gentleCount: number; filtered: boolean }> {
+export async function inspectJokerAgents(options: Omit<SetupOptions, "install">): Promise<{ jokerInstalled: boolean; gentleCount: number; filtered: boolean; mode: "joker" | "gentle" | "mixed" | "unavailable" }> {
 	const target = await validateTarget(options);
 	const settings = await regularSettings(join(target, "settings.json"));
 	const packages = settings.packages ?? [];
+	validatePackages(packages);
 	const flags = await Promise.all(packages.map((entry) => gentle(entry, target, options.home ?? homedir())));
+	const filtered = flags.every((isGentle, index) => !isGentle || hasFilter(packages[index], GENTLE_EXCLUSION));
+	const jokerInstalled = packages.some(joker);
+	const jokerDisabled = packages.some((entry) => joker(entry) && hasFilter(entry, JOKER_EXCLUSION));
+	const jokerAllowed = packages.some((entry) => joker(entry) && allowsAgent(entry, "./index.ts"));
+	const gentleAllowed = flags.every((flag, i) => !flag || allowsAgent(packages[i], "extensions/gentle-agents.ts"));
 	return {
-		jokerInstalled: packages.some(joker),
-		gentleCount: flags.filter(Boolean).length,
-		filtered: flags.every((isGentle, index) => !isGentle ||
-			(object(packages[index]) && Array.isArray(packages[index].extensions) && packages[index].extensions.includes(GENTLE_EXCLUSION))),
+		jokerInstalled, gentleCount: flags.filter(Boolean).length, filtered,
+		mode: jokerInstalled && !jokerDisabled && jokerAllowed && filtered ? "joker" :
+			(!jokerInstalled || jokerDisabled) && flags.some(Boolean) && gentleAllowed && flags.every((flag, i) => !flag || !hasFilter(packages[i], GENTLE_EXCLUSION)) ? "gentle" :
+			jokerInstalled || flags.some(Boolean) ? "mixed" : "unavailable",
 	};
 }
 
+function hasFilter(entry: unknown, filter: string): boolean {
+	return object(entry) && Array.isArray(entry.extensions) && entry.extensions.includes(filter);
+}
+
+function validatePackages(packages: unknown[]): void {
+	if (packages.some((entry) => typeof entry !== "string" && (!object(entry) || typeof entry.source !== "string")))
+		throw new Error("Personal settings packages contain an invalid entry.");
+	if (packages.filter(joker).length > 1) throw new Error("Personal settings contain duplicate Joker entries.");
+	for (const entry of packages) {
+		if (object(entry) && entry.extensions !== undefined &&
+			(!Array.isArray(entry.extensions) || !entry.extensions.every((value: unknown) => typeof value === "string")))
+			throw new Error("Gentle extensions or Joker extensions filter must be an array of strings.");
+	}
+}
+
+function allowsAgent(entry: unknown, expected: string): boolean {
+	if (object(entry) && entry.autoload === false) return false;
+	if (!object(entry) || !Array.isArray(entry.extensions)) return true;
+	const filters = entry.extensions as string[];
+	if (!filters.length) return false;
+	// Pi applies plain includes, then ! globs, + exact paths, and finally - exact paths.
+	// Refuse uncertain glob matches rather than reporting a provider ready incorrectly.
+	const exact = (pattern: string) => pattern.replace(/^\.\//, "") === expected.replace(/^\.\//, "");
+	const exclusions = filters.filter((filter) => filter.startsWith("!") || filter.startsWith("-"));
+	if (exclusions.some((filter) => filter.slice(1).includes("*") || filter.slice(1).includes("?") || exact(filter.slice(1)))) return false;
+	const positives = filters.filter((filter) => !/^[!+-]/.test(filter));
+	return !positives.length || positives.some(exact) || filters.some((filter) => filter.startsWith("+") && exact(filter.slice(1)));
+}
+
+function assertAgentAllowlists(packages: unknown[], gentleFlags: boolean[], mode: "on" | "off"): void {
+	for (const [index, entry] of packages.entries()) {
+		// Adding a negative filter to [] makes Pi load every other extension.
+		if (((gentleFlags[index] && mode === "on") || (joker(entry) && mode === "off")) &&
+			object(entry) && Array.isArray(entry.extensions) && entry.extensions.length === 0)
+			throw new Error("Cannot exclude an agent from disabled extensions []; nothing changed.");
+		if (!(joker(entry) && mode === "on") && !(gentleFlags[index] && mode === "off")) continue;
+		const expected = joker(entry) ? "./index.ts" : "extensions/gentle-agents.ts";
+		// The mode switch removes only its own known exclusion before selecting this agent.
+		const ownedFilter = joker(entry) ? JOKER_EXCLUSION : GENTLE_EXCLUSION;
+		let selected = entry;
+		if (object(entry) && Array.isArray(entry.extensions) && entry.extensions.includes(ownedFilter)) {
+			const remaining = entry.extensions.filter((value: unknown) => value !== ownedFilter);
+			const updated = { ...entry };
+			if (remaining.length) updated.extensions = remaining;
+			else delete updated.extensions;
+			selected = updated;
+		}
+		if (!allowsAgent(selected, expected))
+			throw new Error(`Package autoload or extension allowlist excludes ${expected}; cannot guarantee selected agent mode.`);
+	}
+}
+
+async function saveSettings(path: string, settings: Settings): Promise<void> {
+	const temporary = join(dirname(path), `.settings.${randomUUID()}.tmp`);
+	try {
+		await writeFile(temporary, `${JSON.stringify(settings, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+		await rename(temporary, path);
+	} finally {
+		await unlink(temporary).catch(() => {});
+	}
+}
+
 async function validateTarget(options: Omit<SetupOptions, "install">): Promise<string> {
 	const home = resolve(options.home ?? homedir());
 	const target = resolve(options.agentDir);
@@ -149,48 +213,76 @@ async function validateTarget(options: Omit<SetupOptions, "install">): Promise<s
 }
 
 export async function setupJokerAgents(options: SetupOptions): Promise<{ installed: boolean; changed: boolean; gentleCount: number }> {
+	return switchAgentMode({ ...options, mode: "on" });
+}
+
+export async function switchAgentMode(options: SetupOptions & { mode: "on" | "off" }): Promise<{ installed: boolean; changed: boolean; gentleCount: number }> {
 	const target = await validateTarget(options);
 	const path = join(target, "settings.json");
 	const before = await regularSettings(path);
 	const original = before.packages ?? [];
-	if (original.some((entry) => entry !== null && typeof entry !== "string" && !object(entry)))
-		throw new Error("Personal settings packages contain an invalid entry.");
+	validatePackages(original);
 	const initialGentle = await Promise.all(original.map((entry) => gentle(entry, target, options.home ?? homedir())));
-	if (original.filter(joker).length > 1) throw new Error("Personal settings contain duplicate Joker entries.");
 	const alreadyJoker = original.some(joker);
-	for (const [index, isGentle] of initialGentle.entries()) {
-		if (isGentle) validateGentleFilters(original[index]);
-	}
-	const filtered = initialGentle.every((isGentle, index) => !isGentle ||
-		(object(original[index]) && Array.isArray(original[index].extensions) && original[index].extensions.includes(GENTLE_EXCLUSION)));
-	if (alreadyJoker && filtered) return { installed: false, changed: false, gentleCount: initialGentle.filter(Boolean).length };
-	if (!alreadyJoker) await (options.install ?? installJoker)();
+	if (options.mode === "off" && !initialGentle.some(Boolean))
+		throw new Error("Gentle agents require an eligible personal Gentle package; nothing changed.");
+	if (before[OWNED] !== undefined && before[OWNED] !== true)
+		throw new Error("Invalid Joker filter ownership marker; nothing changed.");
+	if (before[OWNED] === true && !original.some((entry) => joker(entry) && hasFilter(entry, JOKER_EXCLUSION)))
+		throw new Error("Joker filter ownership marker does not match settings; nothing changed.");
+	if (original.some((entry) => joker(entry) && hasFilter(entry, JOKER_EXCLUSION)) && before[OWNED] !== true)
+		throw new Error("Joker extension has an unowned exclusion; cannot change agent mode.");
+	assertAgentAllowlists(original, initialGentle, options.mode);
+	// All failures known from the original settings must be checked before Pi install can mutate them.
+	let installAttempted = false;
+	try {
+		if (options.mode === "on" && !alreadyJoker) {
+			installAttempted = true;
+			await (options.install ?? installJoker)();
+		}
 	// Install owns only Joker. Re-read the latest settings instead of replaying a stale snapshot.
 	await assertNoProjectGentle(options.cwd, options.home ?? homedir());
 	const latest = await regularSettings(path);
 	const packages = latest.packages ?? [];
-	if (!packages.some(joker)) throw new Error("Pi install did not register Joker in personal settings; no Gentle filters were changed.");
-	if (packages.filter(joker).length > 1) throw new Error("Personal settings contain duplicate Joker entries.");
+	validatePackages(packages);
+	if (options.mode === "on" && !packages.some(joker)) throw new Error("Joker is not registered in personal settings; no filters were changed.");
+	if (latest[OWNED] !== undefined && latest[OWNED] !== true)
+		throw new Error("Invalid Joker filter ownership marker; nothing changed.");
+	if (packages.some((entry) => joker(entry) && hasFilter(entry, JOKER_EXCLUSION)) && latest[OWNED] !== true)
+		throw new Error("Joker extension has an unowned exclusion; cannot change agent mode.");
+	if (latest[OWNED] === true && !packages.some((entry) => joker(entry) && hasFilter(entry, JOKER_EXCLUSION)))
+		throw new Error("Joker filter ownership marker does not match settings; nothing changed.");
 	const gentleFlags = await Promise.all(packages.map((entry) => gentle(entry, target, options.home ?? homedir())));
+	assertAgentAllowlists(packages, gentleFlags, options.mode);
+	if (options.mode === "off" && !gentleFlags.some(Boolean)) throw new Error("No eligible Gentle package; nothing changed.");
 	let changed = false;
 	const updated = packages.map((entry, index) => {
-		if (!gentleFlags[index]) return entry;
-		if (typeof entry !== "string" && !object(entry)) throw new Error("Gentle package entry is invalid.");
-		const item = typeof entry === "string" ? { source: entry } : entry;
-		validateGentleFilters(item);
+		const isGentle = gentleFlags[index];
+		if (!isGentle && !joker(entry)) return entry;
+		const filter = isGentle ? GENTLE_EXCLUSION : JOKER_EXCLUSION;
+		const shouldExclude = isGentle ? options.mode === "on" : options.mode === "off";
+		const item = typeof entry === "string" ? { source: entry } : entry as Record<string, unknown>;
 		const extensions = item.extensions as string[] | undefined;
-		if (extensions?.includes(GENTLE_EXCLUSION)) return entry;
+		if (shouldExclude === (extensions?.includes(filter) ?? false)) return entry;
 		changed = true;
-		return { ...item, extensions: [...(extensions ?? []), GENTLE_EXCLUSION] };
-	});
-	if (changed) {
-		const temporary = join(target, `.settings.${randomUUID()}.tmp`);
-		try {
-			await writeFile(temporary, `${JSON.stringify({ ...latest, packages: updated }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
-			await rename(temporary, path);
-		} finally {
-			await unlink(temporary).catch(() => {});
+		const next = shouldExclude ? [...(extensions ?? []), filter] : extensions!.filter((value) => value !== filter);
+		if (!next.length) {
+			const rest = { ...item };
+			delete rest.extensions;
+			return Object.keys(rest).length === 1 ? rest.source : rest;
 		}
+		return { ...item, extensions: next };
+	});
+	const ownershipChanged = (latest[OWNED] === true) !== (options.mode === "off" && packages.some(joker));
+	if (changed || ownershipChanged) {
+		const saved: Settings = { ...latest, packages: updated };
+		if (options.mode === "off" && packages.some(joker)) saved[OWNED] = true;
+		else delete saved[OWNED];
+		await saveSettings(path, saved);
+	}
+	return { installed: options.mode === "on" && !alreadyJoker, changed: changed || ownershipChanged, gentleCount: gentleFlags.filter(Boolean).length };
+	} catch (error) {
+		if (!installAttempted) throw error;
+		throw new Error(`Joker may have been installed even though agent setup failed: ${error instanceof Error ? error.message : String(error)} Run /osdy-pi agents status, inspect personal Pi settings.json, and retry /osdy-pi agents on after resolving the issue.`, { cause: error });
 	}
-	return { installed: !alreadyJoker, changed, gentleCount: gentleFlags.filter(Boolean).length };
 }

package/extensions/osdy-pi/runtime.test.ts

@@ -117,15 +117,30 @@ void test("agents setup requires interactive confirmation and reloads only after
 	await handleAgentsSetupCommand("setup", ctx, setup);
 	assert.equal(installs, 1);
 	assert.equal(reloads, 1);
-	await handleAgentsSetupCommand("status", ctx, setup, () => Promise.resolve({ jokerInstalled: true, gentleCount: 1, filtered: true }));
+	await handleAgentsSetupCommand("status", ctx, setup, () => Promise.resolve({ jokerInstalled: true, gentleCount: 1, filtered: true, mode: "joker" as const }));
 	assert.ok(notices.some((notice) => notice.includes("agent exclusion complete")));
 	await handleAgentsSetupCommand("invalid", ctx, setup);
 	assert.equal(installs, 1);
 	assert.ok(notices.some((notice) => notice.includes("Usage:")));
-	assert.deepEqual(getOsdyCommandCompletions("agents"), [
-		{ value: "agents setup", label: "agents setup" },
-		{ value: "agents status", label: "agents status" },
-	]);
+	assert.deepEqual(getOsdyCommandCompletions("agents"), ["setup", "on", "off", "status"].map((action) => ({ value: `agents ${action}`, label: `agents ${action}` })));
+});
+
+void test("agents off confirms and switches, reports actual mode, and guides restart on failed reload", async () => {
+	const notices: string[] = [];
+	const confirmations: string[] = [];
+	const modes: string[] = [];
+	const ctx = { hasUI: true, cwd: "/tmp", ui: {
+		confirm: (_title: string, message: string) => { confirmations.push(message); return Promise.resolve(true); },
+		notify: (message: string) => { notices.push(message); },
+	}, reload: () => Promise.reject(new Error("reload failed")) } as unknown as ExtensionCommandContext;
+	await handleAgentsSetupCommand("off", ctx, undefined, () => Promise.resolve({ jokerInstalled: true, gentleCount: 1, filtered: false, mode: "gentle" }),
+		(options) => { modes.push(options.mode); return Promise.resolve({ installed: false, changed: true, gentleCount: 1 }); });
+	assert.deepEqual(modes, ["off"]);
+	assert.match(confirmations[0] ?? "", /Joker.*Gentle|Gentle.*Joker/i);
+	assert.ok(notices.some((notice) => /restart Pi/i.test(notice)));
+	await handleAgentsSetupCommand("status", ctx, undefined, () => Promise.resolve({ jokerInstalled: true, gentleCount: 1, filtered: false, mode: "gentle" }));
+	assert.ok(notices.some((notice) => /Gentle/.test(notice)));
+	assert.deepEqual(getOsdyCommandCompletions("agents"), ["setup", "on", "off", "status"].map((action) => ({ value: `agents ${action}`, label: `agents ${action}` })));
 });
 
 void test("header command completes only catalog choices and is persisted through session wiring", () => {
@@ -151,6 +166,17 @@ void test("header command completes only catalog choices and is persisted throug
 	assert.doesNotMatch(source, /if \(isHeaderVariant\(action\)\)/);
 });
 
+void test("uninstall command is offered and wired through guarded Pi CLI removal", () => {
+ assert.deepEqual(getOsdyCommandCompletions("uninstall"), [
+  { value: "uninstall", label: "uninstall" },
+ ]);
+ const source = readFileSync(new URL("./runtime.ts", import.meta.url), "utf8");
+ assert.match(source, /action === "uninstall"/);
+ assert.match(source, /!ctx\.hasUI \|\| !ctx\.isProjectTrusted\(\)/);
+ assert.match(source, /runOsdyUninstall\(/);
+ assert.match(source, /pi\.exec\("pi", \["remove", source/);
+});
+
 void test("mascot command completes current, Bts, and status while persisting with immediate refresh", () => {
 	assert.deepEqual(getOsdyCommandCompletions("mascot"), [
 		{ value: "mascot current", label: "mascot current" },

package/extensions/osdy-pi/runtime.ts

@@ -4,8 +4,9 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { homedir } from "node:os";
+import { identifyLocalPackage, runOsdyUninstall } from "./uninstall.js";
 import { join } from "node:path";
-import { inspectJokerAgents, setupJokerAgents } from "./agent-coexistence-setup.js";
+import { inspectJokerAgents, setupJokerAgents, switchAgentMode } from "./agent-coexistence-setup.js";
 import { createAudioEventRouter } from "./audio-event-router.js";
 import { registerAudioNotificationFlags } from "./audio-notification-config.js";
 import { createAudioNotificationService } from "./audio-notification-service.js";
@@ -266,10 +267,11 @@ export function getOsdyCommandCompletions(prefix: string) {
 			"mascot",
 			"header",
 			"diff",
+			"uninstall",
 		].map((value) => ({ value, label: value }));
 	}
 	if (trimmed === "agents") {
-		return ["agents setup", "agents status"].map((value) => ({ value, label: value }));
+		return ["agents setup", "agents on", "agents off", "agents status"].map((value) => ({ value, label: value }));
 	}
 	if (trimmed === "sound") {
 		return [{ value: "sound setup", label: "sound setup" }];
@@ -322,6 +324,7 @@ export function getOsdyCommandCompletions(prefix: string) {
 			"mascot",
 			"header",
 			"diff",
+			"uninstall",
 		]
 			.filter((value) => value.startsWith(valuePrefix))
 			.map((value) => ({ value, label: value }));
@@ -717,9 +720,10 @@ export async function handleAgentsSetupCommand(
 	ctx: ExtensionCommandContext,
 	setup: typeof setupJokerAgents = setupJokerAgents,
 	inspect: typeof inspectJokerAgents = inspectJokerAgents,
+	switchMode: typeof switchAgentMode = switchAgentMode,
 ): Promise<void> {
-	if (action !== "setup" && action !== "status") {
-		ctx.ui.notify("Usage: /osdy-pi agents setup|status", "warning");
+	if (action !== "setup" && action !== "on" && action !== "off" && action !== "status") {
+		ctx.ui.notify("Usage: /osdy-pi agents setup|on|off|status", "warning");
 		return;
 	}
 	if (!ctx.hasUI) {
@@ -730,20 +734,21 @@ export async function handleAgentsSetupCommand(
 	if (action === "status") {
 		try {
 			const status = await inspect({ agentDir: target, cwd: ctx.cwd, env: process.env });
-			ctx.ui.notify(`Joker ${status.jokerInstalled ? "installed" : "not installed"}; ${status.gentleCount} Gentle entries; agent exclusion ${status.filtered ? "complete" : "incomplete"}.`, "info");
+			ctx.ui.notify(`Agent mode: ${status.mode}; Joker ${status.jokerInstalled ? "installed" : "not installed"}; ${status.gentleCount} Gentle entries; agent exclusion ${status.filtered ? "complete" : "incomplete"}.`, "info");
 		} catch (error) {
 			ctx.ui.notify(`Agents status unavailable: ${error instanceof Error ? error.message : "unknown error"}`, "warning");
 		}
 		return;
 	}
 	const confirmed = await ctx.ui.confirm(
-		"Set up Joker agents in normal Pi?",
-		`Target: ${join(target, "settings.json")}\nInstall npm:pi-subagents-j0k3r with Pi and exclude only -extensions/gentle-agents.ts from eligible Gentle packages. No isolated profile or credentials are changed.`,
+		`Switch agents to ${action === "off" ? "Gentle" : "Joker"} in normal Pi?`,
+		`Target: ${join(target, "settings.json")}\n${action === "off" ? "Disable Joker's ./index.ts extension and enable Gentle agents (requires eligible Gentle)." : "Install npm:pi-subagents-j0k3r if absent, enable Joker's ./index.ts extension and exclude only -extensions/gentle-agents.ts from eligible Gentle packages."} Packages and unrelated resources remain installed. No isolated profile or credentials are changed.`,
 	);
 	if (!confirmed) return;
 	try {
-		const result = await setup({ agentDir: target, cwd: ctx.cwd, env: process.env });
-		ctx.ui.notify(`Joker agents ready (${result.gentleCount} Gentle entries checked). Reloading resources.`, "info");
+		const result = action === "setup" ? await setup({ agentDir: target, cwd: ctx.cwd, env: process.env }) :
+			await switchMode({ agentDir: target, cwd: ctx.cwd, env: process.env, mode: action });
+		ctx.ui.notify(`${action === "off" ? "Gentle" : "Joker"} agents ready (${result.gentleCount} Gentle entries checked). ${result.changed || result.installed ? "Reloading resources." : "Settings already in this mode; reloading resources."}`, "info");
 	} catch (error) {
 		ctx.ui.notify(`Agents setup failed: ${error instanceof Error ? error.message : "unknown error"}. Check settings and retry after resolving the error.`, "error");
 		return;
@@ -751,7 +756,7 @@ export async function handleAgentsSetupCommand(
 	try {
 		await ctx.reload();
 	} catch {
-		ctx.ui.notify("Agents setup saved, but reload failed; restart Pi to apply the changes.", "warning");
+		ctx.ui.notify("Agent settings saved, but reload failed; restart Pi to apply the changes.", "warning");
 	}
 }
 
@@ -772,6 +777,27 @@ function registerCommand(
 		getArgumentCompletions: getOsdyCommandCompletions,
 		handler: async (args, ctx) => {
 			const [action = "status", ...rest] = parseCommandArgs(args);
+			if (action === "uninstall") {
+				if (rest.length || !ctx.hasUI || !ctx.isProjectTrusted()) {
+					ctx.ui.notify("Uninstall requires an interactive, trusted project and no extra arguments; nothing was removed.", "warning");
+					return;
+				}
+				await runOsdyUninstall({
+					list: async () => {
+						const result = await pi.exec("pi", ["list", "--approve"], { cwd: ctx.cwd });
+						if (result.code !== 0 || result.stderr.trim()) throw new Error("pi list failed");
+						return result.stdout;
+					},
+					remove: async (source, local) => {
+						const result = await pi.exec("pi", ["remove", source, ...(local ? ["--local", "--approve"] : [])], { cwd: ctx.cwd });
+						if (result.code !== 0) throw new Error("pi remove failed");
+					},
+					identifyLocal: (path) => identifyLocalPackage(path, import.meta.url),
+					confirm: (source, scope) => ctx.ui.confirm("Uninstall Osdy Pi?", `Remove only the Pi package registration:\nSource: ${source}\nScope: ${scope}\nProfiles, accounts and global CLI stay intact. Continue?`),
+					notify: (message, level = "info") => ctx.ui.notify(message, level),
+				});
+				return;
+			}
 			if (action === "agents") {
 				await handleAgentsSetupCommand(rest.length === 1 ? rest[0] : undefined, ctx);
 				return;
@@ -864,7 +890,7 @@ function registerCommand(
 				return;
 			}
 			ctx.ui.notify(
-				`Usage: /osdy-pi agents setup|status | enable|disable|on|off|status | mascot ${MASCOT_CHOICES.join("|")}|status | header ${HEADER_VARIANT_CHOICES.join("|")}|status | editor auto|extended|simple|on|off|toggle|status | sound setup | working-tree ... | diff`,
+				`Usage: /osdy-pi agents setup|on|off|status | enable|disable|on|off|status | mascot ${MASCOT_CHOICES.join("|")}|status | header ${HEADER_VARIANT_CHOICES.join("|")}|status | editor auto|extended|simple|on|off|toggle|status | sound setup | working-tree ... | diff | uninstall`,
 				"warning",
 			);
 		},

package/extensions/osdy-pi/uninstall.test.ts

@@ -0,0 +1,142 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { existsSync, readFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+registerHooks({
+ resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(".") && specifier.endsWith(".js") && context.parentURL?.endsWith(".ts")) {
+   const url = new URL(`${specifier.slice(0, -3)}.ts`, context.parentURL);
+   if (existsSync(fileURLToPath(url))) return { shortCircuit: true, url: url.href };
+  }
+  return nextResolve(specifier, context);
+ },
+ load(url, context, nextLoad) {
+  if (url.endsWith(".ts")) return { format: "module", shortCircuit: true, source: ts.transpileModule(readFileSync(fileURLToPath(url), "utf8"), { compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 } }).outputText };
+  return nextLoad(url, context);
+ },
+});
+const { runOsdyUninstall, identifyLocalPackage } = await import("./uninstall.js");
+
+const listing = "User packages:\n  npm:osdy-pi@1.5.0\n  npm:other\n";
+function harness(output = listing) {
+ const calls: Array<{ command: string; args: string[] }> = [];
+ const notices: string[] = [];
+ let confirmed = true;
+ const api = {
+  list: () => Promise.resolve(output),
+  remove: (source: string, local: boolean) => { calls.push({ command: source, args: local ? ["--local"] : [] }); return Promise.resolve(); },
+  confirm: () => Promise.resolve(confirmed),
+  notify: (message: string) => notices.push(message),
+ };
+ return { api, calls, notices, cancel: () => { confirmed = false; } };
+}
+
+void test("removes exactly one confirmed registration without touching unrelated packages", async () => {
+ const h = harness();
+ await runOsdyUninstall(h.api);
+ assert.deepEqual(h.calls, [{ command: "npm:osdy-pi@1.5.0", args: [] }]);
+ assert.match(h.notices.at(-1) ?? "", /restart Pi/i);
+});
+
+void test("cancellation and ambiguous scopes never remove", async () => {
+ const cancelled = harness(); cancelled.cancel();
+ await runOsdyUninstall(cancelled.api);
+ assert.equal(cancelled.calls.length, 0);
+ const ambiguous = harness("User packages:\n  npm:osdy-pi\nProject packages:\n  npm:osdy-pi\n");
+ await runOsdyUninstall(ambiguous.api);
+ assert.equal(ambiguous.calls.length, 0);
+});
+
+void test("unrecognized list output fails closed", async () => {
+ const h = harness("User packages:\n  npm:osdy-pi\nmalformed\n");
+ await runOsdyUninstall(h.api);
+ assert.equal(h.calls.length, 0);
+});
+
+void test("git project registration uses local scope and exact ref", async () => {
+ const h = harness("Project packages:\n  git:github.com/OsdyOrtiz/Osdy-Pi@v1\n  npm:unrelated\n");
+ await runOsdyUninstall(h.api);
+ assert.deepEqual(h.calls, [{ command: "git:github.com/OsdyOrtiz/Osdy-Pi@v1", args: ["--local"] }]);
+});
+
+void test("Pi-prefixed HTTPS Git source is removable when unique", async () => {
+ const h = harness("User packages:\n  git:https://github.com/OsdyOrtiz/Osdy-Pi@main\n");
+ await runOsdyUninstall(h.api);
+ assert.deepEqual(h.calls, [{ command: "git:https://github.com/OsdyOrtiz/Osdy-Pi@main", args: [] }]);
+});
+
+void test("equivalent Git URLs in one scope are ambiguous", async () => {
+ for (const duplicate of [
+  "https://github.com/OsdyOrtiz/Osdy-Pi.git",
+  "git:https://github.com/OsdyOrtiz/Osdy-Pi@main",
+  "git:ssh://git@github.com/OsdyOrtiz/Osdy-Pi",
+  "git:git@github.com:OsdyOrtiz/Osdy-Pi.git",
+  "git:git+https://github.com/OsdyOrtiz/Osdy-Pi",
+  "git:github.com/OsdyOrtiz/Osdy-Pi",
+ ]) {
+  const h = harness(`User packages:\n  git:github.com/OsdyOrtiz/Osdy-Pi\n  ${duplicate}\n`);
+  await runOsdyUninstall(h.api);
+  assert.equal(h.calls.length, 0, duplicate);
+ }
+});
+
+void test("unsupported Git spelling is never selected", async () => {
+ const h = harness("User packages:\n  git@github.com:OsdyOrtiz/Osdy-Pi\n");
+ await runOsdyUninstall(h.api);
+ assert.equal(h.calls.length, 0);
+});
+
+void test("confirmation rechecks source, scope, and duplicate identities", async () => {
+ for (const changed of [
+  "User packages:\n  npm:osdy-pi@2.0.0\n",
+  "Project packages:\n  npm:osdy-pi@1.5.0\n",
+  "User packages:\n  npm:osdy-pi@1.5.0\n  npm:osdy-pi@2.0.0\n",
+  "User packages:\n  git:github.com/OsdyOrtiz/Osdy-Pi\n",
+  "User packages:\n  npm:osdy-pi@1.5.0\n  npm:other\nProject packages:\n  npm:unrelated\n",
+ ]) {
+  const h = harness();
+  let current = listing;
+  await runOsdyUninstall({ ...h.api, list: () => Promise.resolve(current), confirm: () => { current = changed; return Promise.resolve(true); } });
+  assert.equal(h.calls.length, 0, changed);
+ }
+});
+
+void test("local provenance requires the executing package root, not only a matching manifest", async () => {
+ const manifest = JSON.stringify({ name: "osdy-pi", pi: { extensions: ["./extensions/osdy-pi.ts"] } });
+ const io = {
+  readFile: () => Promise.resolve(manifest),
+  realpath: (path: string) => Promise.resolve(path === "/installed/copy" ? "/installed/copy" : "/running/package"),
+ };
+ assert.equal(await identifyLocalPackage("/installed/copy", import.meta.url, io), false);
+ assert.equal(await identifyLocalPackage("/running/package", import.meta.url, io), true);
+ assert.equal(await identifyLocalPackage("/running/package", import.meta.url, { ...io, readFile: () => Promise.resolve("{}") }), false);
+});
+
+void test("local provenance is rechecked after confirmation", async () => {
+ const h = harness("User packages:\n  ./Osdy-Pi\n    /running/package\n");
+ let trusted = true;
+ await runOsdyUninstall({
+  ...h.api,
+  identifyLocal: () => Promise.resolve(trusted),
+  confirm: () => { trusted = false; return Promise.resolve(true); },
+ });
+ assert.equal(h.calls.length, 0);
+});
+
+void test("local registrations require identified package path and do not remove other local packages", async () => {
+ const h = harness("User packages:\n  ../Osdy-Pi\n    /home/user/Osdy-Pi\n  ./other\n    /home/user/other\n");
+ await runOsdyUninstall({ ...h.api, identifyLocal: (path) => Promise.resolve(path === "/home/user/Osdy-Pi") });
+ assert.deepEqual(h.calls, [{ command: "/home/user/Osdy-Pi", args: [] }]);
+ const unknown = harness("User packages:\n  ../Osdy-Pi\n    /home/user/Osdy-Pi\n");
+ await runOsdyUninstall(unknown.api);
+ assert.equal(unknown.calls.length, 0);
+});
+
+void test("remove errors do not report success", async () => {
+ const h = harness();
+ await runOsdyUninstall({ ...h.api, remove: () => Promise.reject(new Error("remove failed")) });
+ assert.equal(h.notices.some((message) => message.startsWith("Removed")), false);
+});

package/extensions/osdy-pi/uninstall.ts

@@ -0,0 +1,141 @@
+import { readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface UninstallPort {
+ list(): Promise<string>;
+ remove(source: string, local: boolean): Promise<void>;
+ confirm(source: string, scope: "user" | "project"): Promise<boolean>;
+ notify(message: string, level?: "info" | "warning"): void;
+ identifyLocal?(path: string): Promise<boolean>;
+}
+
+type Registration = { source: string; scope: "user" | "project"; path?: string };
+type GitSource = { type: "git"; host: string; path: string };
+type GitParser = { parseGitUrl(source: string): GitSource | null };
+
+// Use the parser shipped with the installed Pi CLI: its host/path pair is
+// also the key Pi uses when removing declarations from a scope's settings.
+async function gitParser(): Promise<GitParser> {
+ const packageEntry = import.meta.resolve("@earendil-works/pi-coding-agent");
+ const parserUrl = new URL("./utils/git.js", packageEntry);
+ const module: unknown = await import(parserUrl.href);
+ if (typeof module !== "object" || module === null || !("parseGitUrl" in module) || typeof module.parseGitUrl !== "function") {
+  throw new Error("Pi Git parser unavailable");
+ }
+ return module as GitParser;
+}
+
+// `pi list` has no machine-readable mode. Reject unknown output instead of guessing
+// which section owns a source or passing a display label to `pi remove`.
+function parseList(output: string): Registration[] {
+ const entries: Registration[] = [];
+ let scope: Registration["scope"] | undefined;
+ let last: Registration | undefined;
+ for (const line of output.trimEnd().split("\n")) {
+  if (line === "No packages installed.") return [];
+  if (line === "User packages:") { scope = "user"; last = undefined; continue; }
+  if (line === "Project packages:") { scope = "project"; last = undefined; continue; }
+  if (line === "") continue;
+  if (line.startsWith("    ") && last && isAbsolute(line.trim())) {
+   last.path = line.trim(); continue;
+  }
+  const match = /^ {2}(\S+?)(?: \(filtered\))?$/.exec(line);
+  if (!match?.[1] || !scope) throw new Error("Unrecognized pi list output");
+  last = { source: match[1], scope };
+  entries.push(last);
+ }
+ return entries;
+}
+
+// Limit the source we submit to remove to protocol forms Pi actually parses.
+// The installed parser, rather than this allowlist, decides identity.
+function supportedGitSource(source: string): boolean {
+ return /^(?:git:(?:github\.com\/|https?:\/\/|ssh:\/\/|git:\/\/|git@github\.com:)|https?:\/\/|ssh:\/\/|git:\/\/)/.test(source);
+}
+
+function isLocalSource(source: string): boolean {
+ return source.startsWith("/") || source.startsWith(".") || source.startsWith("~");
+}
+
+/** Only a registration pointing to the package executing this code is trusted. */
+export async function identifyLocalPackage(
+ path: string,
+ extensionUrl: string,
+ io: { realpath(path: string): Promise<string>; readFile(path: string, encoding: "utf8"): Promise<string> } = { realpath, readFile },
+): Promise<boolean> {
+ try {
+  if (!isAbsolute(path)) return false;
+  const root = fileURLToPath(new URL("../../", extensionUrl));
+  if (await io.realpath(path) !== await io.realpath(root)) return false;
+  const manifest: unknown = JSON.parse(await io.readFile(join(path, "package.json"), "utf8"));
+  return typeof manifest === "object" && manifest !== null && "name" in manifest && manifest.name === "osdy-pi" &&
+   "pi" in manifest && typeof manifest.pi === "object" && manifest.pi !== null && "extensions" in manifest.pi &&
+   Array.isArray(manifest.pi.extensions) && manifest.pi.extensions.includes("./extensions/osdy-pi.ts");
+ } catch { return false; }
+}
+
+async function select(entries: Registration[], port: UninstallPort, parseGit: GitParser["parseGitUrl"]): Promise<(Registration & { removeSource: string }) | undefined> {
+ const candidates: Array<Registration & { removeSource: string }> = [];
+ for (const entry of entries) {
+  if (/^npm:osdy-pi(?:@[^\s]+)?$/.test(entry.source)) {
+   candidates.push({ ...entry, removeSource: entry.source });
+  } else if (supportedGitSource(entry.source)) {
+   const git = parseGit(entry.source);
+   if (git?.type === "git" && git.host === "github.com" && git.path === "OsdyOrtiz/Osdy-Pi") {
+    candidates.push({ ...entry, removeSource: entry.source });
+   }
+  } else if (isLocalSource(entry.source) && entry.path && port.identifyLocal && await port.identifyLocal(entry.path)) {
+   candidates.push({ ...entry, removeSource: entry.path });
+  }
+ }
+ if (candidates.length !== 1) {
+  port.notify(candidates.length ? "Multiple Osdy Pi registrations found; remove one manually with pi remove <source> [-l]." : "No unique Osdy Pi package registration found; nothing was removed.", "warning");
+  return undefined;
+ }
+ const selected = candidates[0];
+ if (!selected) return undefined;
+ const selectedGit = parseGit(selected.source);
+ const selectedEntry = entries.find((entry) => entry.scope === selected.scope && entry.source === selected.source && entry.path === selected.path);
+ const duplicates = entries.filter((entry) => entry.scope === selected.scope && entry !== selectedEntry);
+ for (const entry of duplicates) {
+  if (selected.source.startsWith("npm:")) {
+   if (/^npm:osdy-pi(?:@|$)/.test(entry.source)) {
+    port.notify("Ambiguous package identity; nothing was removed.", "warning"); return undefined;
+   }
+  } else if (selectedGit?.type === "git") {
+   const git = parseGit(entry.source);
+   if (git?.type === "git" && git.host === selectedGit.host && git.path === selectedGit.path) {
+    port.notify("Ambiguous package identity; nothing was removed.", "warning"); return undefined;
+   }
+  } else if (entry.path === selected.path) {
+   port.notify("Ambiguous package identity; nothing was removed.", "warning"); return undefined;
+  }
+ }
+ return selected;
+}
+
+export async function runOsdyUninstall(port: UninstallPort): Promise<void> {
+ try {
+  const parser = await gitParser();
+  const parseGit = (source: string) => parser.parseGitUrl(source);
+  const entries = parseList(await port.list());
+  const selected = await select(entries, port, parseGit);
+  if (!selected) return;
+  if (!await port.confirm(selected.source, selected.scope)) {
+   port.notify("Uninstall cancelled; nothing was removed.", "info"); return;
+  }
+  // The confirmation applies only to the exact observed registration set.
+  // Re-list and re-identify local paths before invoking the separate Pi process.
+  const current = parseList(await port.list());
+  if (JSON.stringify(current) !== JSON.stringify(entries)) {
+   port.notify("Pi registrations changed after confirmation; nothing was removed.", "warning"); return;
+  }
+  const verified = await select(current, port, parseGit);
+  if (!verified || JSON.stringify(verified) !== JSON.stringify(selected)) return;
+  await port.remove(selected.removeSource, selected.scope === "project");
+  port.notify(`Removed ${selected.source} (${selected.scope}) from Pi. Restart Pi to unload the extension. Profiles, accounts, global CLI and other packages were left untouched.`, "info");
+ } catch {
+  port.notify("Could not safely identify or remove the Osdy Pi registration. Check pi list before retrying; no other packages were requested for removal.", "warning");
+ }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "osdy-pi",
-	"version": "1.5.0",
+	"version": "1.6.1",
 	"description": "Osdy Pi package: themes, header, and custom editor for Pi.",
 	"license": "MIT",
 	"type": "module",
@@ -56,7 +56,8 @@
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
 		"@earendil-works/pi-tui": "*",
-		"@juicesharp/rpiv-i18n": "*"
+		"@juicesharp/rpiv-i18n": "*",
+		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
 		"@juicesharp/rpiv-i18n": {
@@ -69,10 +70,8 @@
 		"@eslint/js": "^9.39.1",
 		"@types/node": "^25.8.0",
 		"eslint": "^9.39.1",
+		"typebox": "^1.3.7",
 		"typescript": "^5.9.3",
 		"typescript-eslint": "^8.46.3"
-	},
-	"dependencies": {
-		"typebox": "^1.3.7"
 	}
 }