osdy-pi 1.4.1 → 1.6.0

package/LICENSE

@@ -1,6 +1,11 @@
 MIT License
 
 Copyright (c) 2026 Osdy
+Copyright (c) 2026 juicesharp
+
+TODO portions are adapted from @juicesharp/rpiv-todo@2.11.0
+(https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo),
+licensed under the MIT terms below.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -8,10 +8,11 @@ Osdy Pi gives [Pi](https://github.com/earendil-works/pi) a themed, responsive te
 
 | Area | What ships |
 | --- | --- |
-| Message cards | Pi-native, theme-aware user and assistant cards; assistant accents follow the theme and user accents are white. |
+| Message cards | Pi-native colored user cards without emojis and plain assistant Markdown preceded by a separate `🦝` transcript row. |
 | Header and mascot | A theme-aware `neon` header and selectable `bts` mascot, both responsive and persisted independently. |
 | Accounts | `/osdy-account` switches Codex profiles in place with atomic activation, rollback, bounded auth files, and process-safe locks. |
 | Quota | `/usage` and compact bars emphasize remaining Codex quota at warning (40% or less) and error (15% or less) thresholds. |
+| TODO (starting in 1.5.0) | First-party `todo` snapshots track the Pi session branch; `/todos` reads them without editing. ODD Markdown remains separate. |
 
 ## Prerequisites
 
@@ -33,14 +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 installed a pinned `npm:osdy-pi@1.3.0` or `npm:osdy-pi@1.4.0` in **normal Pi**? Once 1.4.1 is published, replace the older pin (no uninstall or `--local` needed):
-
-   ```bash
-   pi install npm:osdy-pi@1.4.1
-   pi list
-   ```
-
-   Check that `pi list` shows `npm:osdy-pi@1.4.1`, then restart Pi or run `/reload`. `pi update` does not move a pinned npm version. Installing Osdy does not automatically install Joker; use the [explicit agents setup](#explicit-joker-agents-setup-in-normal-pi) after updating if you want Joker 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:
 
@@ -82,7 +76,6 @@ Add these maintained extensions after installing Osdy Pi. They are optional; eac
 | `pi-playwright` | Playwright browser-automation skills. |
 | `pi-mcp-adapter` | MCP server and tool adapter for Pi. |
 | `pi-subagents-j0k3r` | Markdown-defined subagents, delegation tools, history, and model profiles. |
-| `@juicesharp/rpiv-todo` | A persistent live todo overlay for the agent. |
 | `gentle-pi` | The Gentle senior-architect harness, with SDD/OpenSpec, subagents, TDD evidence, and skills. |
 
 Install the ordinary npm packages once:
@@ -98,7 +91,6 @@ pi install npm:@open-pets/pi
 pi install npm:pi-playwright
 pi install npm:pi-mcp-adapter
 pi install npm:pi-subagents-j0k3r
-pi install npm:@juicesharp/rpiv-todo
 ```
 
 `gentle-pi` is deliberately not included in that package-install block: clone and register it through the coexistence setup below, which applies Osdy-specific exclusions instead of adding a duplicate ordinary package entry.
@@ -108,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:
 
@@ -116,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
 
@@ -128,11 +122,48 @@ To load a local `gentle-pi` checkout while keeping Osdy Pi's UI authoritative, r
 osdy-pi gentle setup /absolute/path/to/gentle-pi
 ```
 
-The command validates that the absolute source is a readable `gentle-pi` package with Gentle's todo and agents extensions before atomically updating `$PI_CODING_AGENT_DIR/settings.json` (or `~/.pi/agent/settings.json`). It registers the local package immediately before the first configured Osdy Pi package entry, so Gentle Shell initializes first, with exclusions only for Gentle's `gentle-todo.ts` and `gentle-agents.ts`, plus `themes: []`. Restart Pi or run `/reload` after setup.
+The command validates that the absolute source is a readable `gentle-pi` package with Gentle's todo and agents extensions before atomically updating `$PI_CODING_AGENT_DIR/settings.json` (or `~/.pi/agent/settings.json`). It registers the local package immediately before the first configured Osdy Pi package entry, so Gentle Shell initializes first, with exclusions for Gentle's `gentle-todo.ts`, `ask-user-question.ts`, and `gentle-agents.ts`, plus `themes: []`. Restart Pi or run `/reload` after setup.
 
 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 and agents extensions from competing with the suite. `@juicesharp/rpiv-todo` remains the authoritative todo overlay, `pi-subagents-j0k3r` remains the authoritative subagent system, and `@juicesharp/rpiv-ask-user-question` remains the authoritative structured-question plugin; their package entries are left untouched.
+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
+
+The model-facing `todo` tool supports `create`, `update`, `list`, `get`, `delete`, and `clear`. Tool results carry full task snapshots; Pi's current session branch is the TODO authority. Session switches and compaction replay the latest valid branch snapshot, rather than sharing one project-wide list. `/todos` opens a read-only, grouped modal (pending, in progress, completed) in interactive Pi; scroll with arrow or Page Up/Down keys and close with Esc or q. The refreshed modal adds a completed-task progress meter, theme-aware status groups and a scroll-position footer while keeping every task reachable. It is not an interactive Markdown editor. In non-terminal modes with UI support, it retains notification output. ODD's `odd/tasks/*.md` ledger and Engram are separate orchestration records: there is no automatic sync with these Pi TODOs.
+
+In interactive Pi, the persistent widget appears above the editor while visible tasks exist. By default it shows up to five task rows (excluding heading, overflow hint, and spacer), summarizes overflow, and keeps completed rows visible with crossed-out subjects on subsequent turns; expand tool output to view all rows. `ctrl+shift+t` collapses or expands the widget.
+
+### Try session TODO
+
+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.
+
+### TODO configuration and language
+
+Create `$XDG_CONFIG_HOME/rpiv-todo/config.json` (with an absolute `XDG_CONFIG_HOME`); when absent, Osdy falls back to `~/.config/rpiv-todo/config.json`. Invalid JSON uses defaults. For example:
+
+```json
+{
+  "maxWidgetLines": 7,
+  "collapseKey": "ctrl+shift+t",
+  "guidance": {
+    "promptSnippet": "Track multi-step work",
+    "promptGuidelines": ["Update task status as work progresses"]
+  }
+}
+```
+
+`maxWidgetLines` must be a number >= 3 (otherwise 7); it is read on widget renders. `collapseKey` accepts a key combination or `"off"` to disable the shortcut; the shortcut binds at extension load, so restart Pi or run `/reload` after changing it. `guidance.promptSnippet` and `guidance.promptGuidelines` override the tool's model guidance at registration; reload after changing them. The optional `@juicesharp/rpiv-i18n` peer enables nine bundled locales (`de`, `en`, `es`, `fr`, `pt-BR`, `pt`, `ru`, `uk`, `zh`); without the SDK the UI uses English. To use `/languages`, also load its Pi extension (for example, `pi install npm:@juicesharp/rpiv-i18n` in your chosen profile); the peer dependency alone does not register that command. An isolated Pi TUI with both extensions loaded switched the TODO widget and `/todos` from English to Spanish.
+
+**Already installed `@juicesharp/rpiv-todo`?** Both packages can register `todo` and `/todos`. Check `pi list` in the Pi profile you intend to use; to use Osdy's first-party implementation, explicitly remove the standalone package in that same profile:
+
+```bash
+pi remove npm:@juicesharp/rpiv-todo
+```
+
+For a project-local installation, run `pi remove -l npm:@juicesharp/rpiv-todo` in that project instead. Restart Pi or run `/reload`, then check `/todos` shows session tasks, not a document panel. Osdy never uninstalls another package or silently changes package settings. If you need the standalone package, disable the conflicting extension via Pi package configuration instead.
 
 ## OpenAI account profiles
 
@@ -215,7 +246,7 @@ Before rename or removal, close this Pi process when it uses the target and **ma
 | --- | --- |
 | Themes | 14 built-in themes, including Osdy, Kanagawa, Dracula, Catppuccin, Matrix, and Lucent Orange palettes |
 | Header and mascot | Independently selectable `osdy-theme`/`neon` headers and `current`/`bts` mascots |
-| Messages | Pi-native, theme-aware user and assistant message cards |
+| Messages | Native colored user cards without emojis and plain assistant Markdown with a separate assistant `🦝` row |
 | Input | Responsive auto editor by default, with selectable simple Pi-native or extended framed modes |
 | Status | Theme-aware Braille spinner and animated working label, responsive footer metrics, dynamic extension statuses, and Codex subscription quota with low-capacity emphasis |
 | Git | Working-tree summary and a centered, filterable diff panel |
@@ -300,6 +331,7 @@ The enabled state, editor mode, working-tree visibility preference, header, and
 | Main | `/osdy-pi` |
 | Main | `/osdy-pi enable\|disable\|on\|off\|status` |
 | Accounts | `/osdy-account` |
+| Session TODO (starting in 1.5.0) | `/todos` (read-only) |
 | Header | `/osdy-pi header osdy-theme\|neon\|status` |
 | Mascot | `/osdy-pi mascot current\|bts\|status` |
 | Editor | `/osdy-pi editor auto\|extended\|simple\|on\|off\|toggle\|status` |
@@ -307,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
@@ -325,9 +360,7 @@ Usage loads once when the session starts and refreshes when the modal opens or `
 
 ## Native message cards
 
-Osdy Pi delegates conversation rendering to Pi's native message-card components. It does not install a Markdown transformer or inject card markup into assistant responses. This preserves Pi's own streaming, selection, and Markdown behavior while allowing every bundled Osdy theme to style the native cards.
-
-User and assistant cards have separate background, text, and accent tokens. Assistant accents follow each theme's primary accent; user accents are white for a consistent visual distinction. Disabling Osdy Pi continues to restore the underlying Gentle Shell or Pi presentation normally.
+Pi renders the colored user card and assistant Markdown natively. User messages have no emoji; Osdy Pi places a separate `🦝` transcript entry before each assistant response with visible text, not inside message content. Previously saved user `👤` entries remain in session history but render no row on replay. Selecting only the native message keeps its body clean; a wide selection that includes the emoji row copies the emoji too. Assistant markers persist with the session but do not enter model context. The installed Pi 0.87.1 does not use `assistantMessage*` theme palette keys, so these keys do not create a native assistant card. Osdy does not install a Markdown transformer or change streaming. The current user card colors remain unchanged. Try both roles in your selected theme with `npm run pi:dev`; terminal rendering and selection still need a live visual check. When disabled, Osdy does not add new markers.
 
 ## Editor and working indicator
 
@@ -335,7 +368,7 @@ The default `auto` editor mode preserves the responsive behavior: it uses the fr
 
 In auto or extended mode at a non-small width, the framed editor shows the model and thinking level in its title and session usage in its footer. For an account-profile launch, the left title shows the active profile name instead of `Osdy-Pi`. When the native editor is effective (simple mode or any small terminal), the Osdy footer instead shows model, active profile when present, thinking, and usage rows before its path/branch and status rows. It uses the currently active Pi/Osdy theme palette; no separate editor theme selector exists. Usage covers input, output, cache read, cache write when present, cost, and context. If Pi supports autocomplete, the editor uses Pi's native autocomplete rendering while the completion UI is visible.
 
-While work is active, Osdy Pi shows the original Braille spinner above the editor in the selected theme's accent color. A highlight travels across the `Working...` and `Running ...` letters using the active theme's accent and text colors; the spinner and label update when the theme changes. Osdy Pi hides Pi's built-in working row while enabled to avoid a duplicate indicator.
+While work is active, Osdy Pi shows the original Braille spinner above the editor in the selected theme's accent color. A two-color wave travels across the `Working...` and `Running ...` letters: the current letter uses the active theme's `accent`, the trailing letter uses `warning`, and the rest use `text`. Only the current `accent` letter tries the active theme's bold styling; this is a terminal-dependent visual trial, not a change to font size. The trailing `warning` letter stays plain, as does the accent spinner. The spinner and label update when the theme changes. Osdy Pi hides Pi's built-in working row while enabled to avoid a duplicate indicator.
 
 ## Working tree and diff
 

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 };
 }