osdy-pi 1.3.0 → 1.4.1

package/README.md

@@ -33,6 +33,15 @@ 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.
+
 2. Start Pi:
 
    ```bash
@@ -99,6 +108,18 @@ git clone https://github.com/Gentleman-Programming/gentle-pi.git
 osdy-pi gentle setup "$(pwd)/gentle-pi"
 ```
 
+## Explicit Joker agents setup in normal Pi
+
+After `pi install npm:osdy-pi`, open **normal personal Pi** (not `osdy`'s isolated profile) and run:
+
+```text
+/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.
+
+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.
+
 ## Gentle coexistence setup
 
 To load a local `gentle-pi` checkout while keeping Osdy Pi's UI authoritative, run:
@@ -196,7 +217,7 @@ Before rename or removal, close this Pi process when it uses the target and **ma
 | Header and mascot | Independently selectable `osdy-theme`/`neon` headers and `current`/`bts` mascots |
 | Messages | Pi-native, theme-aware user and assistant message cards |
 | Input | Responsive auto editor by default, with selectable simple Pi-native or extended framed modes |
-| Status | Custom working spinner, responsive footer metrics, dynamic extension statuses, and Codex subscription quota with low-capacity emphasis |
+| 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 |
 | Audio | Optional event sounds on macOS and Windows |
 
@@ -314,7 +335,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.
 
-A custom spinner appears above the editor while work is active. 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 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.
 
 ## Working tree and diff
 

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

@@ -0,0 +1,163 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { registerHooks } from "node:module";
+import test from "node:test";
+
+registerHooks({ resolve(specifier, context, nextResolve) {
+	if (specifier === "./agent-coexistence-setup.js" && context.parentURL?.endsWith(".test.ts"))
+		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");
+
+async function fixture() {
+	const root = await mkdtemp(join(tmpdir(), "osdy-joker-"));
+	const agentDir = join(root, ".pi", "agent");
+	const gentle = join(root, "gentle");
+	await mkdir(agentDir, { recursive: true });
+	await mkdir(gentle);
+	await writeFile(join(gentle, "package.json"), '{"name":"gentle-pi"}');
+	const settingsPath = join(agentDir, "settings.json");
+	const packages = ["npm:other", { source: gentle, extensions: ["-extensions/gentle-todo.ts"], themes: [], skills: ["skills/*"] }, "npm:gentle-pi@1.2.0", { source: "npm:gentle-pi", extensions: ["-extensions/gentle-agents.ts"] }];
+	await writeFile(settingsPath, JSON.stringify({ theme: "dark", packages }));
+	return { root, agentDir, gentle, settingsPath, packages };
+}
+
+const base = (f: Awaited<ReturnType<typeof fixture>>) => ({
+	agentDir: f.agentDir, home: f.root, cwd: f.root, env: {},
+});
+
+void test("installs Joker then narrowly reconciles every Gentle entry using latest settings", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = async () => {
+		calls++;
+		const latest = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: unknown[] };
+		latest.packages.push("npm:pi-subagents-j0k3r", "npm:newly-added");
+		await writeFile(f.settingsPath, JSON.stringify(latest));
+	};
+	await setupJokerAgents({ ...base(f), install });
+	const settings = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: unknown[]; theme: string };
+	assert.equal(calls, 1);
+	assert.deepEqual(settings.packages, [
+		"npm:other",
+		{ source: f.gentle, extensions: ["-extensions/gentle-todo.ts", "-extensions/gentle-agents.ts"], themes: [], skills: ["skills/*"] },
+		{ source: "npm:gentle-pi@1.2.0", extensions: ["-extensions/gentle-agents.ts"] },
+		{ source: "npm:gentle-pi", extensions: ["-extensions/gentle-agents.ts"] },
+		"npm:pi-subagents-j0k3r", "npm:newly-added",
+	]);
+	assert.equal(settings.theme, "dark");
+	await setupJokerAgents({ ...base(f), install: () => Promise.reject(new Error("duplicate install")) });
+	assert.equal((await readFile(f.settingsPath, "utf8")).includes("duplicate"), false);
+});
+
+void test("relative Gentle sources resolve from settings and project overrides fail closed", async () => {
+	const f = await fixture();
+	const local = join(f.agentDir, "gentle-local");
+	await mkdir(local);
+	await writeFile(join(local, "package.json"), '{"name":"gentle-pi"}');
+	await writeFile(f.settingsPath, '{"packages":["./gentle-local","npm:pi-subagents-j0k3r"]}');
+	await setupJokerAgents({ ...base(f), install: () => Promise.reject(new Error("should skip")) });
+	const result = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: unknown[] };
+	assert.deepEqual(result.packages[0], { source: "./gentle-local", extensions: ["-extensions/gentle-agents.ts"] });
+	const project = join(f.root, "project");
+	await mkdir(join(project, ".pi", "gentle"), { recursive: true });
+	await writeFile(join(project, ".pi", "gentle", "package.json"), '{"name":"gentle-pi"}');
+	await writeFile(join(project, ".pi", "settings.json"), '{"packages":["./gentle"]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), cwd: project }), /project-local Gentle/i);
+});
+
+void test("bare, tilde, and file URL local Gentle entries get the narrow personal filter", async () => {
+	const f = await fixture();
+	const bare = join(f.agentDir, "gentle");
+	await mkdir(bare);
+	await writeFile(join(bare, "package.json"), '{"name":"gentle-pi"}');
+	await writeFile(f.settingsPath, JSON.stringify({ packages: ["gentle", "~/gentle", pathToFileURL(f.gentle).href, "npm:pi-subagents-j0k3r"] }));
+	const result = await setupJokerAgents({ ...base(f), install: () => Promise.reject(new Error("no install")) });
+	assert.equal(result.gentleCount, 3);
+	const settings = JSON.parse(await readFile(f.settingsPath, "utf8")) as { packages: Array<{ source: string; extensions: string[] }> };
+	assert.deepEqual(settings.packages.slice(0, 3).map((entry) => entry.extensions), Array(3).fill(["-extensions/gentle-agents.ts"]));
+});
+
+void test("bare project Gentle override and ambiguous Gentle local path fail before install", async () => {
+	const f = await fixture();
+	const project = join(f.root, "project");
+	await mkdir(join(project, ".pi", "gentle"), { recursive: true });
+	await writeFile(join(project, ".pi", "gentle", "package.json"), '{"name":"gentle-pi"}');
+	await writeFile(join(project, ".pi", "settings.json"), '{"packages":["gentle"]}');
+	let calls = 0;
+	const install = () => { calls++; return Promise.resolve(); };
+	await assert.rejects(setupJokerAgents({ ...base(f), cwd: project, install }), /project-local Gentle/i);
+	await writeFile(join(project, ".pi", "settings.json"), '{"packages":[]}');
+	await writeFile(f.settingsPath, '{"packages":["gentle","npm:pi-subagents-j0k3r"]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), install }), /Gentle.*resolve|Gentle.*source/i);
+	assert.equal(calls, 0);
+});
+
+void test("recognizable remote Gentle sources fail closed before install, but unrelated Git packages remain", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = () => { calls++; return Promise.resolve(); };
+	for (const remote of [
+		"git:github.com/Gentleman-Programming/gentle-pi",
+		"https://github.com/Gentleman-Programming/gentle-pi.git",
+	]) {
+		await writeFile(f.settingsPath, JSON.stringify({ packages: [remote, "git:github.com/owner/other-package"] }));
+		await assert.rejects(setupJokerAgents({ ...base(f), install }), /remote Gentle.*local.*npm/i);
+		const project = join(f.root, "project");
+		await mkdir(join(project, ".pi"), { recursive: true });
+		await writeFile(join(project, ".pi", "settings.json"), JSON.stringify({ packages: [remote] }));
+		await writeFile(f.settingsPath, '{"packages":["npm:pi-subagents-j0k3r"]}');
+		await assert.rejects(setupJokerAgents({ ...base(f), cwd: project, install }), /remote Gentle.*local.*npm/i);
+		await writeFile(join(project, ".pi", "settings.json"), '{"packages":[]}');
+	}
+	assert.equal(calls, 0);
+	await writeFile(f.settingsPath, '{"packages":["git:github.com/owner/other-package","npm:pi-subagents-j0k3r"]}');
+	const result = await setupJokerAgents({ ...base(f), install });
+	assert.equal(result.gentleCount, 0);
+});
+
+void test("invalid Gentle filters or duplicate Joker declarations block setup before further writes", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = () => { calls++; return Promise.resolve(); };
+	await writeFile(f.settingsPath, '{"packages":[{"source":"npm:gentle-pi","extensions":false}]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), install }), /Gentle extensions/i);
+	await writeFile(f.settingsPath, '{"packages":["npm:pi-subagents-j0k3r","npm:pi-subagents-j0k3r"]}');
+	await assert.rejects(setupJokerAgents({ ...base(f), install }), /duplicate Joker/i);
+	assert.equal(calls, 0);
+});
+
+void test("without Gentle, only Joker installation changes settings", async () => {
+	const f = await fixture();
+	await writeFile(f.settingsPath, '{"packages":["npm:other"]}');
+	await setupJokerAgents({ ...base(f), install: async () => {
+		await writeFile(f.settingsPath, '{"packages":["npm:other","npm:pi-subagents-j0k3r"]}');
+	} });
+	assert.deepEqual(JSON.parse(await readFile(f.settingsPath, "utf8")) as unknown, { packages: ["npm:other", "npm:pi-subagents-j0k3r"] });
+});
+
+void test("rejects alternate agent directories and project-local Gentle overrides before install", async () => {
+	const f = await fixture();
+	let calls = 0;
+	const install = () => { calls++; return Promise.resolve(); };
+	await assert.rejects(setupJokerAgents({ ...base(f), agentDir: join(f.root, "isolated"), install }), /personal|agent/i);
+	await assert.rejects(setupJokerAgents({ ...base(f), env: { PI_CODING_AGENT_DIR: f.agentDir }, install }), /override|normal/i);
+	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(setupJokerAgents({ ...base(f), cwd: project, install }), /project|Gentle/i);
+	assert.equal(calls, 0);
+});
+
+void test("failed installer or malformed latest settings cannot rewrite personal settings", async () => {
+	const f = await fixture();
+	const original = await readFile(f.settingsPath, "utf8");
+	await assert.rejects(setupJokerAgents({ ...base(f), install: () => Promise.reject(new Error("install failed")) }), /install failed/);
+	assert.equal(await readFile(f.settingsPath, "utf8"), original);
+	await assert.rejects(setupJokerAgents({ ...base(f), install: async () => { await writeFile(f.settingsPath, "{bad"); } }), /settings/i);
+	assert.equal(await readFile(f.settingsPath, "utf8"), "{bad");
+});

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

@@ -0,0 +1,196 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { lstat, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+
+const runFile = promisify(execFile);
+const JOKER = "npm:pi-subagents-j0k3r";
+const GENTLE_EXCLUSION = "-extensions/gentle-agents.ts";
+
+type Settings = Record<string, unknown> & { packages?: unknown[] };
+
+type SetupOptions = {
+	agentDir: string;
+	home?: string;
+	cwd: string;
+	env?: NodeJS.ProcessEnv;
+	install?: () => Promise<void>;
+};
+
+function object(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function source(entry: unknown): string | undefined {
+	if (typeof entry === "string") return entry;
+	return object(entry) && typeof entry.source === "string" ? entry.source : undefined;
+}
+
+function npmGentle(entry: unknown): boolean {
+	return /^npm:gentle-pi(?:@[^\s]+)?$/i.test(source(entry) ?? "");
+}
+
+function joker(entry: unknown): boolean {
+	return /^npm:pi-subagents-j0k3r(?:@[^\s]+)?$/i.test(source(entry) ?? "");
+}
+
+async function gentle(entry: unknown, settingsDir: string, home: string): Promise<boolean> {
+	if (npmGentle(entry)) return true;
+	const value = source(entry);
+	if (!value || /^npm:/i.test(value)) return false;
+	if (/^(?:git:|https?:\/\/)/i.test(value)) {
+		if (/(?:^|\/)gentle-pi(?:\.git)?(?:[@#?][^\s]*)?$/i.test(value))
+			throw new Error("Remote Gentle source unsupported: register a local gentle-pi checkout or npm:gentle-pi in personal Pi, then rerun agents setup.");
+		return false;
+	}
+	let path: string;
+	try {
+		if (value.startsWith("file:")) path = fileURLToPath(value);
+		else if (value === "~" || value.startsWith("~/")) path = resolve(home, value.slice(value === "~" ? 1 : 2));
+		else if (!value.includes(":")) path = resolve(settingsDir, value);
+		else return false;
+	} catch {
+		throw new Error(`Gentle source cannot be resolved: ${value}`);
+	}
+	try {
+		const manifest: unknown = JSON.parse(await readFile(join(path, "package.json"), "utf8"));
+		return object(manifest) && manifest.name === "gentle-pi";
+	} catch {
+		if (/(?:^|[\\/])gentle(?:-pi)?$/i.test(path))
+			throw new Error(`Gentle source cannot be resolved: ${value}`);
+		return false;
+	}
+}
+
+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;
+	try {
+		value = JSON.parse(await readFile(path, "utf8"));
+	} catch {
+		throw new Error("Personal settings.json must contain valid JSON.");
+	}
+	if (!object(value) || (value.packages !== undefined && !Array.isArray(value.packages)))
+		throw new Error("Personal settings.json must have an object root and array packages.");
+	return value;
+}
+
+async function assertNoProjectGentle(cwd: string, home: string): Promise<void> {
+	let directory = resolve(cwd);
+	while (true) {
+		const local = join(directory, ".pi", "settings.json");
+		let text: string;
+		try {
+			text = await readFile(local, "utf8");
+		} catch (error) {
+			if (object(error) && error.code === "ENOENT") {
+				const parent = dirname(directory);
+				if (parent === directory) return;
+				directory = parent;
+				continue;
+			}
+			throw error;
+		}
+		let settings: unknown;
+		try { settings = JSON.parse(text); }
+		catch { throw new Error(`Project settings invalid at ${local}; cannot guarantee Gentle filtering.`); }
+		if (!object(settings) || (settings.packages !== undefined && !Array.isArray(settings.packages)))
+			throw new Error(`Project settings invalid at ${local}; cannot guarantee Gentle filtering.`);
+		for (const entry of settings.packages ?? []) {
+			if (await gentle(entry, dirname(local), home)) throw new Error(`Project-local Gentle package at ${local} can override the personal filter.`);
+		}
+		const parent = dirname(directory);
+		if (parent === directory) return;
+		directory = parent;
+	}
+}
+
+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 }> {
+	const target = await validateTarget(options);
+	const settings = await regularSettings(join(target, "settings.json"));
+	const packages = settings.packages ?? [];
+	const flags = await Promise.all(packages.map((entry) => gentle(entry, target, options.home ?? homedir())));
+	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))),
+	};
+}
+
+async function validateTarget(options: Omit<SetupOptions, "install">): Promise<string> {
+	const home = resolve(options.home ?? homedir());
+	const target = resolve(options.agentDir);
+	if (options.env?.PI_CODING_AGENT_DIR !== undefined || !isAbsolute(options.agentDir))
+		throw new Error("Agents setup requires normal personal Pi; agent directory override or isolated profile is unsupported.");
+	let personal: boolean;
+	try {
+		personal = (await realpath(target)) === (await realpath(join(home, ".pi", "agent")));
+	} catch {
+		personal = false;
+	}
+	if (!personal)
+		throw new Error("Agents setup requires the normal personal Pi agent directory, not an isolated profile.");
+	await assertNoProjectGentle(options.cwd, home);
+	return target;
+}
+
+export async function setupJokerAgents(options: SetupOptions): 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.");
+	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)();
+	// 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.");
+	const gentleFlags = await Promise.all(packages.map((entry) => gentle(entry, target, options.home ?? homedir())));
+	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 extensions = item.extensions as string[] | undefined;
+		if (extensions?.includes(GENTLE_EXCLUSION)) 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(() => {});
+		}
+	}
+	return { installed: !alreadyJoker, changed, gentleCount: gentleFlags.filter(Boolean).length };
+}

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

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { registerHooks } from "node:module";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import ts from "typescript";
 
 registerHooks({
@@ -43,6 +43,7 @@ const { PLUGIN_EVENTS, subscribeQuestionPromptAudioNotification } =
 const {
 	createActiveSessionRefresh,
 	getOsdyCommandCompletions,
+	handleAgentsSetupCommand,
 	refreshCodexUsage,
 } = await import("./runtime.js");
 
@@ -80,6 +81,39 @@ class TestSessionContextProvider {
 	}
 }
 
+void test("agents setup requires interactive confirmation and reloads only after success", async () => {
+	const notices: string[] = [];
+	let installs = 0;
+	let reloads = 0;
+	let accepted = false;
+	const ui = {
+		confirm: (_title: string, message: string) => {
+			assert.match(message, /pi-subagents-j0k3r/);
+			assert.match(message, /gentle-agents\.ts/);
+			assert.match(message, /settings\.json/);
+			return Promise.resolve(accepted);
+		},
+		notify: (message: string) => { notices.push(message); },
+	};
+	const ctx = { mode: "tui", hasUI: true, cwd: "/tmp", ui, reload: () => { reloads++; return Promise.resolve(); } } as unknown as ExtensionCommandContext;
+	const setup = () => { installs++; return Promise.resolve({ installed: true, changed: true, gentleCount: 1 }); };
+	await handleAgentsSetupCommand("setup", ctx, setup);
+	assert.equal(installs, 0);
+	accepted = true;
+	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 }));
+	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" },
+	]);
+});
+
 void test("header command completes only catalog choices and is persisted through session wiring", () => {
 	assert.deepEqual(getOsdyCommandCompletions("header"), [
 		{ value: "header osdy-theme", label: "header osdy-theme" },

package/extensions/osdy-pi/runtime.ts

@@ -1,7 +1,11 @@
 import type {
 	ExtensionAPI,
+	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { inspectJokerAgents, setupJokerAgents } 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";
@@ -250,6 +254,7 @@ export function getOsdyCommandCompletions(prefix: string) {
 			"on",
 			"off",
 			"status",
+			"agents",
 			"sound",
 			"working-tree",
 			"editor",
@@ -258,6 +263,9 @@ export function getOsdyCommandCompletions(prefix: string) {
 			"diff",
 		].map((value) => ({ value, label: value }));
 	}
+	if (trimmed === "agents") {
+		return ["agents setup", "agents status"].map((value) => ({ value, label: value }));
+	}
 	if (trimmed === "sound") {
 		return [{ value: "sound setup", label: "sound setup" }];
 	}
@@ -302,6 +310,7 @@ export function getOsdyCommandCompletions(prefix: string) {
 			"on",
 			"off",
 			"status",
+			"agents",
 			"sound",
 			"working-tree",
 			"editor",
@@ -312,6 +321,12 @@ export function getOsdyCommandCompletions(prefix: string) {
 			.filter((value) => value.startsWith(valuePrefix))
 			.map((value) => ({ value, label: value }));
 	}
+	if (parts[0] === "agents" && parts.length === 2) {
+		const valuePrefix = parts[1] ?? "";
+		return ["setup", "status"]
+			.filter((value) => value.startsWith(valuePrefix))
+			.map((value) => ({ value: `agents ${value}`, label: `agents ${value}` }));
+	}
 	if (parts[0] === "sound" && parts.length === 2) {
 		const valuePrefix = parts[1] ?? "";
 		return ["setup"]
@@ -692,6 +707,49 @@ function registerUsageCommand(
 	});
 }
 
+export async function handleAgentsSetupCommand(
+	action: string | undefined,
+	ctx: ExtensionCommandContext,
+	setup: typeof setupJokerAgents = setupJokerAgents,
+	inspect: typeof inspectJokerAgents = inspectJokerAgents,
+): Promise<void> {
+	if (action !== "setup" && action !== "status") {
+		ctx.ui.notify("Usage: /osdy-pi agents setup|status", "warning");
+		return;
+	}
+	if (!ctx.hasUI) {
+		ctx.ui.notify("Agents setup requires an interactive confirmation.", "warning");
+		return;
+	}
+	const target = join(homedir(), ".pi", "agent");
+	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");
+		} 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.`,
+	);
+	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");
+	} 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;
+	}
+	try {
+		await ctx.reload();
+	} catch {
+		ctx.ui.notify("Agents setup saved, but reload failed; restart Pi to apply the changes.", "warning");
+	}
+}
+
 function registerCommand(
 	pi: ExtensionAPI,
 	state: OsdyState,
@@ -709,6 +767,10 @@ function registerCommand(
 		getArgumentCompletions: getOsdyCommandCompletions,
 		handler: async (args, ctx) => {
 			const [action = "status", ...rest] = parseCommandArgs(args);
+			if (action === "agents") {
+				await handleAgentsSetupCommand(rest.length === 1 ? rest[0] : undefined, ctx);
+				return;
+			}
 			if (["enable", "on"].includes(action)) {
 				await enableOsdyPi(
 					pi,
@@ -797,7 +859,7 @@ function registerCommand(
 				return;
 			}
 			ctx.ui.notify(
-				`Usage: /osdy-pi 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|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`,
 				"warning",
 			);
 		},

package/extensions/osdy-pi/ui.ts

@@ -39,9 +39,9 @@ import {
 	STACKED_HEADER_MIN_ROWS,
 	type MascotConfig,
 	type ScaledHeaderArt,
-	WORKING_SPINNER_FRAMES,
 } from "./constants.js";
 import { formatPath } from "./format.js";
+import { renderWorkingWidget } from "./working-animation.js";
 import { contextUsageData, modelLabel } from "./metrics.js";
 import {
 	formatModelMetadata,
@@ -363,13 +363,7 @@ class OsdyWorkingWidget implements Component {
 	}
 
 	render(width: number): string[] {
-		if (!this.state.active) return [];
-		const frame =
-			WORKING_SPINNER_FRAMES[this.state.frame % WORKING_SPINNER_FRAMES.length] ??
-			WORKING_SPINNER_FRAMES[0] ??
-			"⠋";
-		const line = `${this.theme.fg("accent", frame)} ${this.theme.fg("muted", this.state.label)}`;
-		return [fitCenterVisible(line, width)];
+		return renderWorkingWidget(this.state, this.theme, width);
 	}
 
 	invalidate(): void {}

package/extensions/osdy-pi/working-animation.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { registerHooks } from "node:module";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import type { SimpleTheme, WorkingWidgetState } from "./types.js";
+
+registerHooks({
+	resolve(specifier, context, nextResolve) {
+		if (
+			context.parentURL?.includes("/extensions/osdy-pi/") &&
+			specifier.startsWith("./") &&
+			specifier.endsWith(".js")
+		) {
+			return nextResolve(`${specifier.slice(0, -3)}.ts`, context);
+		}
+		return nextResolve(specifier, context);
+	},
+});
+
+// @ts-expect-error Node's native TypeScript runner resolves test-only TypeScript source imports.
+const { renderWorkingWidget } = await import("./working-animation.ts");
+// @ts-expect-error Node's native TypeScript runner resolves test-only TypeScript source imports.
+const { WORKING_SPINNER_FRAMES } = await import("./constants.ts");
+
+function state(label: string, frame = 0, active = true): WorkingWidgetState {
+	return { active, label, frame, timer: undefined, tui: undefined };
+}
+
+function theme(base: string, accent: string, muted: string): SimpleTheme {
+	return {
+		fg(name, text) {
+			const color = name === "accent" ? accent : name === "muted" ? muted : base;
+			return `\u001B[${color}m${text}\u001B[0m`;
+		},
+	};
+}
+
+const palette = theme("37", "33", "90");
+void test("original Braille frames advance every 80ms tick, wrap at ten, and use theme accent", () => {
+	assert.equal(WORKING_SPINNER_FRAMES.length, 10);
+	for (let frame = 0; frame <= WORKING_SPINNER_FRAMES.length; frame += 1) {
+		const glyph = WORKING_SPINNER_FRAMES[frame % WORKING_SPINNER_FRAMES.length] ?? "";
+		const spinner = palette.fg("accent", glyph);
+		const line = renderWorkingWidget(state("Working...", frame), palette, 40)[0] ?? "";
+		assert.ok(line.includes(`${spinner} `), `frame ${frame} uses accent Braille ${glyph}`);
+		assert.equal(visibleWidth(spinner), 1);
+	}
+	const at = (frame: number) => renderWorkingWidget(state("Working...", frame), palette, 40)[0] ?? "";
+	assert.ok(at(0).includes(`${palette.fg("accent", WORKING_SPINNER_FRAMES[0] ?? "")} ${palette.fg("accent", "W")}${palette.fg("text", "o")}`));
+	assert.ok(at(1).includes(`${palette.fg("accent", WORKING_SPINNER_FRAMES[1] ?? "")} ${palette.fg("text", "W")}${palette.fg("accent", "o")}`));
+	const runningAt = (frame: number) => renderWorkingWidget(state("Running build...", frame), palette, 40)[0] ?? "";
+	assert.notEqual(runningAt(0), runningAt(10), "letter wave advances when the spinner wraps");
+});
+
+void test("Running label skips spaces, wraps its one highlighted grapheme, and follows theme on next render", () => {
+	const label = "Running build...";
+	const changedTheme = theme("36", "35", "34");
+	const first = renderWorkingWidget(state(label, 7), palette, 40)[0] ?? "";
+	const changed = renderWorkingWidget(state(label, 7), changedTheme, 40)[0] ?? "";
+	assert.ok(first.includes(`${palette.fg("accent", WORKING_SPINNER_FRAMES[7] ?? "")} `));
+	assert.ok(changed.includes(`${changedTheme.fg("accent", WORKING_SPINNER_FRAMES[7] ?? "")} `));
+	assert.ok(first.includes(`${palette.fg("text", "g")} ${palette.fg("accent", "b")}`));
+	assert.ok(changed.includes(`${changedTheme.fg("text", "g")} ${changedTheme.fg("accent", "b")}`));
+	assert.ok(changed.includes(changedTheme.fg("text", "R")));
+	assert.ok(renderWorkingWidget(state("A B", 1), palette, 20)[0]?.includes(
+		`${palette.fg("text", "A")} ${palette.fg("accent", "B")}`,
+	));
+	assert.ok(renderWorkingWidget(state("AB", 2), palette, 20)[0]?.includes(
+		`${palette.fg("accent", "A")}${palette.fg("text", "B")}`,
+	));
+});
+
+void test("tab-separated label skips whitespace when advancing the highlight", () => {
+	const label = "A\tB";
+	const line = renderWorkingWidget(state(label, 1), palette, 20)[0] ?? "";
+	assert.ok(line.includes(`${palette.fg("accent", WORKING_SPINNER_FRAMES[1] ?? "")} ${palette.fg("text", "A")}\t${palette.fg("accent", "B")}`));
+	assert.equal(visibleWidth(line.trimStart()), 2 + visibleWidth(label));
+});
+
+void test("combining marks and ZWJ emoji remain whole graphemes in the traveling wave", () => {
+	const label = "A\u0301👩‍💻 B";
+	for (const [frame, expected] of [
+		[0, `${palette.fg("accent", "A\u0301")}${palette.fg("text", "👩‍💻")} ${palette.fg("text", "B")}`],
+		[1, `${palette.fg("text", "A\u0301")}${palette.fg("accent", "👩‍💻")} ${palette.fg("text", "B")}`],
+		[2, `${palette.fg("text", "A\u0301")}${palette.fg("text", "👩‍💻")} ${palette.fg("accent", "B")}`],
+	] as const) {
+		const line = renderWorkingWidget(state(label, frame), palette, 40)[0] ?? "";
+		assert.ok(line.includes(`${palette.fg("accent", WORKING_SPINNER_FRAMES[frame] ?? "")} ${expected}`), `frame ${frame} preserves graphemes`);
+		assert.equal(visibleWidth(line.trimStart()), 2 + visibleWidth(label));
+	}
+});
+
+void test("inactive widget renders nothing; narrow output fits and full output stays centered", () => {
+	assert.deepEqual(renderWorkingWidget(state("Working...", 18, false), palette, 20), []);
+	for (const frame of [0, 2, 4, 6]) {
+		const line = renderWorkingWidget(state("Working...", frame), palette, 5)[0] ?? "";
+		assert.equal(visibleWidth(line), 5);
+	}
+	const centered = renderWorkingWidget(state("Working..."), palette, 20)[0] ?? "";
+	assert.equal(centered.match(/^ */)?.[0].length, 4);
+});

package/extensions/osdy-pi/working-animation.ts

@@ -0,0 +1,27 @@
+import { WORKING_SPINNER_FRAMES } from "./constants.js";
+import type { SimpleTheme, WorkingWidgetState } from "./types.js";
+import { fitCenterVisible } from "./utils.js";
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const isWhitespace = (segment: string) => /\s/u.test(segment);
+
+/** Render the theme-accent Braille spinner beside a theme-aware traveling letter highlight. */
+export function renderWorkingWidget(
+	state: WorkingWidgetState,
+	theme: SimpleTheme,
+	width: number,
+): string[] {
+	if (!state.active) return [];
+	const spinner = WORKING_SPINNER_FRAMES[state.frame % WORKING_SPINNER_FRAMES.length] ?? "";
+	const segments = [...graphemes.segment(state.label)].map(({ segment }) => segment);
+	const letterCount = segments.filter((segment) => !isWhitespace(segment)).length;
+	const highlighted = letterCount > 0 ? state.frame % letterCount : -1;
+	let letterIndex = 0;
+	const label = segments
+		.map((segment) => {
+			if (isWhitespace(segment)) return segment;
+			const color = letterIndex++ === highlighted ? "accent" : "text";
+			return theme.fg(color, segment);
+		})
+		.join("");
+	return [fitCenterVisible(`${theme.fg("accent", spinner)} ${label}`, width)];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "osdy-pi",
-	"version": "1.3.0",
+	"version": "1.4.1",
 	"description": "Osdy Pi package: themes, header, and custom editor for Pi.",
 	"license": "MIT",
 	"type": "module",