osdy-pi 1.11.2 → 1.11.3

package/extensions/osdy-pi/control-center-account.ts

@@ -0,0 +1,141 @@
+import { createAccountManagementDependencies, isProfileName, readActiveProfileName, readStoredProfileCodexCredential, sharedAgentDir, switchAccountInPlace, type AccountContext, type AccountManagementDependencies } from "./account-profiles.js";
+import type { ControlCenterService, ControlCenterRow, ControlCenterAccountAction } from "./control-center.js";
+import { requestProfileCodexUsage, type ProfileCodexUsageResult } from "./profile-codex-usage.js";
+
+export interface ControlCenterAccountService extends ControlCenterService<ControlCenterAccountAction> {
+	cancelUsage?(): void;
+	isCurrent?(): boolean;
+}
+function localTime(value: number | undefined): string {
+	return value !== undefined && Number.isFinite(value) && !Number.isNaN(new Date(value).getTime())
+		? new Date(value).toLocaleString() : "unknown";
+}
+function localResetTime(unixSeconds: number | undefined): string {
+	return localTime(unixSeconds === undefined ? undefined : unixSeconds * 1000);
+}
+function usageDetails(profile: string, result: ProfileCodexUsageResult): string[] {
+	const lines = [`Profile: ${profile}`, `Checked: ${localTime(result.checkedAt)} (local time)`];
+	if (result.status !== "ready") return [...lines, result.status === "cancelled" ? "Query cancelled." :
+		result.reason === "remote-usage-unavailable" ? "Remote Codex usage unavailable (credentials may be rejected)." : "Stored credentials unavailable (missing, expired or unsupported)."];
+	for (const bucket of result.quotaSnapshot.buckets) {
+		if (!bucket.primary && !bucket.secondary) lines.push(`${bucket.label ?? bucket.id}: quota and next reset unknown.`);
+		for (const [label, window] of [["Session", bucket.primary], ["Weekly", bucket.secondary]] as const) {
+			if (window) lines.push(`${bucket.label ?? bucket.id} / ${label}: ${100 - window.usedPercent}% remaining · Next reset: ${localResetTime(window.resetsAt)}`);
+		}
+	}
+	if (lines.length === 2) lines.push("Quota and next reset: unknown (no quota windows returned).");
+	return lines;
+}
+
+export interface ControlCenterAccountBackend {
+	profiles(): Promise<unknown>;
+	active(): string | undefined;
+	defaultProfile(): Promise<unknown>;
+	switch(profile: string): Promise<boolean>;
+	setDefault(profile: string | undefined): Promise<boolean>;
+	usage?(profile: string, signal: AbortSignal): Promise<ProfileCodexUsageResult>;
+	isCurrent?(): boolean;
+}
+function names(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((name: unknown): name is string => typeof name === "string" && isProfileName(name)) : [];
+}
+function safeName(value: unknown): string | undefined {
+	return typeof value === "string" && isProfileName(value) ? value : undefined;
+}
+type DefaultMetadata = { kind: "profile"; name: string } | { kind: "unset" | "unavailable" };
+function defaultMetadata(value: unknown): DefaultMetadata {
+	if (typeof value !== "object" || value === null || !("code" in value) || value.code !== 0 || !("stdout" in value) || typeof value.stdout !== "string") return { kind: "unavailable" };
+	const output = value.stdout.trim();
+	if (output === "No default account.") return { kind: "unset" };
+	const name = safeName(output);
+	return name ? { kind: "profile", name } : { kind: "unavailable" };
+}
+
+/** Metadata-only projection. Never interpolate backend stdout/stderr/errors. */
+export function createControlCenterAccount(backend: ControlCenterAccountBackend): ControlCenterAccountService {
+	let busy = false;
+	let controller: AbortController | undefined;
+	let preview: { profile: string; details: string[] } | undefined;
+	const current = () => backend.isCurrent?.() ?? true;
+	const cancelUsage = () => { controller?.abort(); controller = undefined; preview = undefined; };
+	return {
+		cancelUsage,
+		isCurrent: current,
+		async read() {
+			let profiles: string[];
+			try { profiles = names(await backend.profiles()); }
+			catch { return { summary: "Account profiles unavailable", note: "Reopen to retry. Login remains Pi-owned (/login).", rows: [] }; }
+			const active = safeName(backend.active());
+			let metadata: DefaultMetadata = { kind: "unavailable" };
+			try { metadata = defaultMetadata(await backend.defaultProfile()); } catch { /* Fixed metadata state only. */ }
+			const defaultProfile = metadata.kind === "profile" ? metadata.name : undefined;
+			const rows: ControlCenterRow[] = [];
+			for (const profile of profiles) {
+				rows.push({ label: `View usage: ${profile}`, current: false, action: { kind: "account-usage", profile },
+					details: preview?.profile === profile && (backend.isCurrent?.() ?? true) ? preview.details : [`Profile: ${profile}`, "Explicit live Codex query using this profile's stored credentials snapshot; no automatic refresh.", "Missing or expired snapshots are unavailable. Local token history is not quota."] });
+				const current = profile.toLowerCase() === active?.toLowerCase();
+				if (!current) rows.push({ label: `Switch to ${profile}`, current: false, action: { kind: "account-switch", profile }, details: ["Switch in place after Pi is idle; next request uses this account."] });
+				rows.push({ label: `Default: ${profile}`, current: profile.toLowerCase() === defaultProfile?.toLowerCase(), action: { kind: "account-default", profile }, details: [`Profile: ${profile}${current ? " (active)" : ""}`, "Default selects the account for future launcher startup."] });
+			}
+			rows.push({ label: "Clear default", current: false, action: { kind: "account-default", profile: undefined } });
+			return { summary: `Current: ${active ?? "unmanaged"} | Default: ${defaultProfile ?? metadata.kind} | Profiles: ${profiles.length}`,
+				note: "View usage queries Codex only; other actions require confirmation. Login remains Pi-owned (/login).", rows };
+		},
+		async apply(action) {
+			if (action.kind === "account-usage") {
+				if (busy || !current() || !backend.usage || !isProfileName(action.profile)) return { failed: true, message: "Profile usage unavailable." };
+				cancelUsage();
+				const request = new AbortController();
+				controller = request;
+				try {
+					if (!names(await backend.profiles()).includes(action.profile) || request.signal.aborted || !current()) return { failed: true, message: "Profile usage unavailable." };
+					const result = await backend.usage(action.profile, request.signal);
+					if (controller !== request || request.signal.aborted || !current()) return { failed: true, message: "Query cancelled." };
+					preview = { profile: action.profile, details: usageDetails(action.profile, result) };
+					return { failed: result.status !== "ready", message: result.status === "ready" ? "Stored-profile Codex usage checked." : "Profile usage unavailable." };
+				} catch {
+					if (controller === request && !request.signal.aborted && current()) preview = { profile: action.profile, details: [`Profile: ${action.profile}`, "Checked: unknown", "Profile usage unavailable."] };
+					return { failed: true, message: "Profile usage unavailable." };
+				} finally { if (controller === request) controller = undefined; }
+			}
+			if (busy || controller || !current() || (action.kind !== "account-switch" && action.kind !== "account-default")) return { failed: true, message: "Account action unavailable." };
+			busy = true;
+			try {
+				const profile = action.profile;
+				if (profile !== undefined && (!isProfileName(profile) || !names(await backend.profiles()).includes(profile))) return { failed: true, message: "Profile no longer available. Reopen Account." };
+				if (!current()) return { failed: true, message: "Account action unavailable." };
+				if (action.kind === "account-switch" && action.profile.toLowerCase() === safeName(backend.active())?.toLowerCase()) return { failed: false, message: "Account already active." };
+				const success = action.kind === "account-switch" ? await backend.switch(action.profile) : await backend.setDefault(profile);
+				if (!success) return { failed: true, message: "Account operation failed; change not confirmed." };
+				const message = action.kind === "account-switch"
+					? "Account switched; next request uses it."
+					: "Default account saved.";
+				return { failed: false, message };
+			} catch { return { failed: true, message: "Account operation failed; change not confirmed." }; }
+			finally { busy = false; }
+		},
+	};
+}
+
+export function bindControlCenterAccount(ctx: AccountContext, refreshUsage: () => Promise<void>, requestRender: () => void,
+	backend: AccountManagementDependencies = createAccountManagementDependencies({ refreshUsage, requestRender }),
+	options: { isCurrent?: () => boolean; usage?: ControlCenterAccountBackend["usage"] } = {},
+): ControlCenterAccountService {
+	return createControlCenterAccount({
+		isCurrent: options.isCurrent ?? (() => true),
+		usage: options.usage ?? ((profile, signal) => requestProfileCodexUsage(profile, {
+			readCredentials: async name => readStoredProfileCodexCredential(await sharedAgentDir(process.env), name), signal,
+		})),
+		profiles: () => backend.profiles(), active: readActiveProfileName,
+		defaultProfile: () => backend.run(["account", "default"]),
+		switch: profile => backend.activate ? switchAccountInPlace(ctx, profile, async name => {
+			if (!(options.isCurrent?.() ?? true) || !ctx.isIdle()) throw new Error("Account action unavailable.");
+			await backend.activate!(name);
+		}, refreshUsage, requestRender) : Promise.resolve(false),
+		setDefault: async profile => {
+			if (!ctx.isIdle()) await ctx.waitForIdle();
+			if (!(options.isCurrent?.() ?? true) || !ctx.isIdle()) return false;
+			return (await backend.run(["account", "default", profile ?? "--clear"])).code === 0;
+		},
+	});
+}

package/extensions/osdy-pi/control-center-agents.test.ts

@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+registerHooks({ resolve(specifier, context, next) {
+	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 next(specifier, context);
+} });
+const { createControlCenterAgents } = await import("./control-center-agents.js");
+
+function fixture() {
+	const home = mkdtempSync(join(tmpdir(), "osdy-cc08-"));
+	const agentDir = join(home, ".pi", "agent");
+	mkdirSync(agentDir, { recursive: true });
+	const path = join(agentDir, "settings.json");
+	writeFileSync(path, JSON.stringify({ packages: [{ source: "npm:gentle-pi", extensions: ["!unrelated.ts"], themes: [] }, "npm:unrelated"], unrelated: true }));
+	let installs = 0;
+	const options = { home, agentDir, cwd: home, env: {}, isIdle: () => true, install: () => {
+		installs++;
+		const settings = JSON.parse(readFileSync(path, "utf8")) as { packages: unknown[] };
+		settings.packages.push("npm:pi-subagents-j0k3r");
+		writeFileSync(path, JSON.stringify(settings));
+		return Promise.resolve();
+	} };
+	return { options, path, installs: () => installs };
+}
+
+void test("Agents read is inspection-only and describes the confirmed installation and real target", async () => {
+	const f = fixture(); const before = readFileSync(f.path, "utf8");
+	const service = createControlCenterAgents(f.options);
+	assert.equal(f.installs(), 0);
+	const view = await service.read(); await service.read();
+	assert.match(view.summary, /gentle.*Joker.*not installed/i);
+	assert.equal(view.rows.length, 2);
+	const details = view.rows[0]!.details!.join(" ");
+	assert.ok(details.includes(f.path));
+	assert.match(details, /Install npm:pi-subagents-j0k3r if absent/);
+	assert.match(details, /-extensions\/gentle-agents.ts/);
+	assert.match(details, /unrelated.*preserved/i);
+	assert.match(details, /reload.*restart/i);
+	assert.equal(f.installs(), 0); assert.equal(readFileSync(f.path, "utf8"), before);
+});
+
+void test("confirmed Agents selection delegates Joker installation and owned Gentle/Joker filters", async () => {
+	const f = fixture(); const service = createControlCenterAgents(f.options);
+	assert.equal((await service.apply({ kind: "agents-provider", mode: "joker" })).kind, "reload");
+	assert.equal(f.installs(), 1);
+	assert.match(readFileSync(f.path, "utf8"), /-extensions\/gentle-agents.ts/);
+	assert.match((await service.read()).summary, /joker/i);
+	assert.equal((await service.apply({ kind: "agents-provider", mode: "gentle" })).kind, "reload");
+	const saved = JSON.parse(readFileSync(f.path, "utf8")) as { packages: unknown[]; unrelated: boolean; osdyPiJokerExclusionOwned: boolean };
+	assert.deepEqual(saved.packages[0], { source: "npm:gentle-pi", extensions: ["!unrelated.ts"], themes: [] });
+	assert.equal(saved.packages[1], "npm:unrelated");
+	assert.deepEqual(saved.packages[2], { source: "npm:pi-subagents-j0k3r", extensions: ["-./index.ts"] });
+	assert.equal(saved.unrelated, true); assert.equal(saved.osdyPiJokerExclusionOwned, true);
+	assert.equal(f.installs(), 1);
+});
+
+void test("isolated Agents owner guard blocks rows, installs and writes even for a personal target", async () => {
+	for (const override of [true, false]) {
+		const f = fixture(); const before = readFileSync(f.path, "utf8");
+		const service = createControlCenterAgents({ ...f.options,
+			...(override ? { env: { PI_CODING_AGENT_DIR: f.options.agentDir } } : { agentDir: join(f.options.home, "isolated") }) });
+		const view = await service.read();
+		assert.deepEqual(view.rows, []); assert.match(view.note, /normal personal Pi.*isolated|override/i);
+		const result = await service.apply({ kind: "agents-provider", mode: "joker" });
+		assert.equal(result.kind, "rejected"); assert.equal(f.installs(), 0);
+		assert.equal(readFileSync(f.path, "utf8"), before);
+	}
+});
+
+void test("Agents service guards idle, reentrancy and stale owner responses without reload", async () => {
+	const f = fixture(); let idle = false; let current = true; let writes = 0; let finish = () => {};
+	const service = createControlCenterAgents({ ...f.options, isIdle: () => idle, isCurrent: () => current,
+		setup: () => { writes++; return new Promise(resolve => { finish = () => resolve({ installed: false, changed: true, gentleCount: 1 }); }); } });
+	const action = { kind: "agents-provider", mode: "joker" } as const;
+	assert.equal((await service.apply(action)).kind, "rejected"); assert.equal(writes, 0);
+	idle = true; const pending = service.apply(action);
+	assert.equal((await service.apply(action)).kind, "rejected"); assert.equal(writes, 1);
+	current = false; finish(); assert.equal((await pending).kind, "rejected");
+	assert.equal((await service.apply(action)).kind, "rejected"); assert.equal(writes, 1);
+});
+
+void test("Agents omits ineligible Gentle and ignores status from an old session", async () => {
+	const f = fixture(); writeFileSync(f.path, JSON.stringify({ packages: ["npm:pi-subagents-j0k3r"] }));
+	const service = createControlCenterAgents(f.options);
+	assert.deepEqual((await service.read()).rows.map(row => row.label), ["Joker agents"]);
+	const stale = createControlCenterAgents({ ...f.options, isCurrent: () => false });
+	assert.deepEqual((await stale.read()).rows, []);
+	const result = await service.apply({ kind: "agents-provider", mode: "gentle" });
+	assert.equal(result.kind, "rejected"); assert.match(result.message, /eligible personal Gentle/);
+	assert.equal(f.installs(), 0);
+});
+
+void test("Agents owner errors retain honest failure and never request reload", async () => {
+	const f = fixture();
+	const service = createControlCenterAgents({ ...f.options, setup: () => Promise.reject(new Error("synthetic failure")) });
+	const result = await service.apply({ kind: "agents-provider", mode: "joker" });
+	assert.equal(result.kind, "rejected"); assert.match(result.message, /synthetic failure.*Reload not requested/);
+	assert.equal(f.installs(), 0);
+});

package/extensions/osdy-pi/control-center-agents.ts

@@ -0,0 +1,60 @@
+import { join } from "node:path";
+import { inspectJokerAgents, setupJokerAgents, switchAgentMode } from "./agent-coexistence-setup.js";
+import type { ControlCenterDetail, ProviderApplyResult } from "./control-center.js";
+
+export type ControlCenterAgentsAction = { kind: "agents-provider"; mode: "joker" | "gentle" };
+export interface ControlCenterAgentsService {
+	read(): Promise<ControlCenterDetail>;
+	apply(action: ControlCenterAgentsAction): Promise<ProviderApplyResult>;
+}
+
+/** The coexistence owner validates normal personal Pi and owns every install/filter write. */
+export function createControlCenterAgents(options: Parameters<typeof setupJokerAgents>[0] & {
+	isIdle: () => boolean;
+	isCurrent?: () => boolean;
+	inspect?: typeof inspectJokerAgents;
+	setup?: typeof setupJokerAgents;
+	switchMode?: typeof switchAgentMode;
+}): ControlCenterAgentsService {
+	let busy = false;
+	const current = () => options.isCurrent?.() !== false;
+	const target = join(options.agentDir, "settings.json");
+	return {
+		async read() {
+			try {
+				const status = await (options.inspect ?? inspectJokerAgents)(options);
+				if (!current()) return { summary: "Agents status unavailable", note: "Session changed; reopen the panel.", rows: [] };
+				return {
+					summary: `Agent mode: ${status.mode} | Joker: ${status.jokerInstalled ? "installed" : "not installed"} | Gentle entries: ${status.gentleCount}`,
+					note: "Configured provider, not proof of loaded tools. Opening this category never installs or switches agents.",
+					rows: (["joker", "gentle"] as const).filter(mode => mode === "joker" || status.gentleCount > 0).map(mode => ({
+						label: mode === "joker" ? "Joker agents" : "Gentle agents", current: status.mode === mode,
+						action: { kind: "agents-provider", mode },
+						details: [`Target: ${target}`, mode === "joker"
+							? "Select Joker: Install npm:pi-subagents-j0k3r if absent; enable ./index.ts and exclude only -extensions/gentle-agents.ts from eligible Gentle entries."
+							: "Select Gentle: enable extensions/gentle-agents.ts; exclude Joker ./index.ts with the owner's -./index.ts filter. No installation.",
+							"Only owner-managed agent filters change; unrelated resources and installed packages are preserved.",
+							"Successful save closes this panel before resource reload; restart Pi if reload fails."],
+					})),
+				};
+			} catch (error) {
+				return { summary: "Agents status unavailable", note: error instanceof Error ? error.message : "Inspection failed; reopen to retry.", rows: [] };
+			}
+		},
+		async apply(action) {
+			if (busy || !current() || !options.isIdle())
+				return { kind: "rejected", message: "Agents selection requires the current idle session; nothing changed." };
+			busy = true;
+			try {
+				if (action.mode === "joker") await (options.setup ?? setupJokerAgents)(options);
+				else await (options.switchMode ?? switchAgentMode)({ ...options, mode: "off" });
+				if (!current()) return { kind: "rejected", message: "Session changed after the owner operation; reload not requested. Reopen status in the current session." };
+				return { kind: "reload", message: "Agents selection saved. Reloading resources; restart Pi if reload fails." };
+			} catch (error) {
+				return { kind: "rejected", message: `Agents selection failed: ${error instanceof Error ? error.message : "unknown error"}. Reload not requested.` };
+			} finally {
+				busy = false;
+			}
+		},
+	};
+}

package/extensions/osdy-pi/control-center-git.test.ts

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { registerHooks } from "node:module";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+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);
+} });
+const { createControlCenterGit } = await import("./control-center-git.js");
+void test("Git reads branch/status only and delegates persisted enabled changes to its shared owner", async () => {
+	let enabled = true;
+	const calls: string[][] = [];
+	const applied: boolean[] = [];
+	const service = createControlCenterGit({
+		snapshot: () => ({ enabled, placement: "aboveEditor" }),
+		exec: (args) => {
+			calls.push(args);
+			if (args.includes("branch")) return Promise.resolve("feature\n");
+			if (args.includes("status")) return Promise.resolve(" M file.ts\n?? new.ts\n");
+			throw new Error("Unexpected Git inspection command");
+		},
+		applyEnabled: (value) => { enabled = value; applied.push(value); return Promise.resolve(true); },
+	});
+	const view = await service.read();
+	assert.match(view.summary, /Branch: feature.*2 changed/);
+	assert.match(view.note, /aboveEditor.*session.*read-only/i);
+	assert.deepEqual(calls, [
+		["--no-optional-locks", "branch", "--show-current"],
+		["--no-optional-locks", "status", "--short", "--untracked-files=normal"],
+	]);
+	assert.deepEqual(applied, []);
+	assert.equal((await service.apply({ kind: "git-enabled", value: false })).failed, false);
+	assert.deepEqual(applied, [false]);
+	assert.equal((await service.read()).rows[1]?.current, true);
+});
+void test("Git unavailable and failed persistence are honest, without new workflows", async () => {
+	const service = createControlCenterGit({ snapshot: () => ({ enabled: false, placement: "belowEditor" }),
+		exec: () => Promise.reject(new Error("not a repository")), applyEnabled: () => Promise.resolve(false) });
+	assert.match((await service.read()).summary, /unavailable/);
+	assert.match((await service.apply({ kind: "git-enabled", value: true })).message, /Applied live.*could not be saved/);
+	const detached = createControlCenterGit({ snapshot: () => ({ enabled: true, placement: "aboveEditor" }),
+		exec: () => Promise.resolve(""), applyEnabled: () => Promise.resolve(true) });
+	assert.match((await detached.read()).summary, /detached.*clean/);
+});

package/extensions/osdy-pi/control-center-git.ts

@@ -0,0 +1,40 @@
+import type { ControlCenterService } from "./control-center.js";
+import type { WorkingTreePlacement } from "./types.js";
+
+interface GitDependencies {
+	snapshot(): { enabled: boolean; placement: WorkingTreePlacement };
+	exec(args: string[]): Promise<string>;
+	applyEnabled(value: boolean): Promise<boolean>;
+}
+
+/** Read-only Git inspection; the runtime retains ownership of widget persistence. */
+export function createControlCenterGit(dependencies: GitDependencies): ControlCenterService {
+	return {
+		async read() {
+			let summary: string;
+			try {
+				const [branch, status] = await Promise.all([
+					dependencies.exec(["--no-optional-locks", "branch", "--show-current"]),
+					dependencies.exec(["--no-optional-locks", "status", "--short", "--untracked-files=normal"]),
+				]);
+				const changed = status.split("\n").filter((line) => line.trim()).length;
+				summary = `Branch: ${branch.trim() || "detached HEAD"} | ${changed ? `${changed} changed entries` : "working tree clean"}`;
+			} catch {
+				summary = "Git branch/worktree unavailable (not a repository or inspection failed).";
+			}
+			const state = dependencies.snapshot();
+			return {
+				summary,
+				note: `Position: ${state.placement} (session detail, read-only). Inspection never writes Git.`,
+				rows: [true, false].map((value) => ({ label: `Working-tree widget: ${value ? "enabled" : "disabled"}`,
+					current: state.enabled === value, action: { kind: "git-enabled" as const, value } })),
+			};
+		},
+		async apply(action) {
+			if (action.kind !== "git-enabled") return { failed: true, message: "Not a Git preference action" };
+			const saved = await dependencies.applyEnabled(action.value);
+			return { failed: !saved, message: saved ? "Saved globally: working-tree widget"
+				: "Applied live: working-tree widget, but could not be saved. Retry to persist." };
+		},
+	};
+}

package/extensions/osdy-pi/control-center-preferences.test.ts

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { registerHooks } from "node:module";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import type { VisualPreferenceSnapshot } from "./control-center-preferences.js";
+
+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);
+	},
+});
+const { preferenceDetail } = await import("./control-center-preferences.js");
+const snapshot: VisualPreferenceSnapshot = { enabled: true, headerVariant: "osdy-theme", mascot: "current",
+	editorMode: "auto", editorEffective: true, smallMode: false };
+
+void test("preference rows expose every catalog value and exactly one current indicator", () => {
+	for (const [category, field, values] of [
+		["Header", "headerVariant", ["osdy-theme", "neon"]],
+		["Mascot", "mascot", ["current", "bts"]],
+		["Editor", "editorMode", ["auto", "extended", "simple"]],
+	] as const) {
+		for (const value of values) {
+			const detail = preferenceDetail(category, { ...snapshot, [field]: value });
+			assert.ok(detail);
+			assert.deepEqual(detail.rows.map((row) => "value" in row.action ? row.action.value : undefined), values);
+			assert.equal(detail.rows.filter((row) => row.current).length, 1);
+			assert.equal(detail.rows.find((row) => row.current)?.action.kind, category.toLowerCase());
+			assert.match(detail.summary, new RegExp(`Current: ${value === "bts" ? "Bts" : value}`));
+		}
+	}
+});
+
+void test("effective editor and disabled visuals describe live runtime, not a derived rendering policy", () => {
+	assert.match(preferenceDetail("Editor", snapshot)?.summary ?? "", /Effective: extended/);
+	const disabled = { ...snapshot, enabled: false, editorEffective: false };
+	assert.match(preferenceDetail("Editor", disabled)?.summary ?? "", /Osdy disabled.*Effective: simple\/native/);
+	assert.match(preferenceDetail("Header", disabled)?.note ?? "", /apply when Osdy is enabled/);
+	assert.match(preferenceDetail("Mascot", { ...snapshot, smallMode: true })?.summary ?? "", /Current: current/);
+	assert.equal(preferenceDetail("Git", snapshot), undefined);
+	assert.equal(preferenceDetail("Sounds", snapshot), undefined);
+	assert.equal(preferenceDetail("Account", snapshot), undefined);
+	assert.equal(preferenceDetail("Usage", snapshot), undefined);
+});

package/extensions/osdy-pi/control-center-preferences.ts

@@ -0,0 +1,57 @@
+import { EDITOR_MODES, HEADER_VARIANT_CHOICES, MASCOT_CHOICES } from "./types.js";
+import type { EditorMode, HeaderVariant, MascotChoice, OsdyState } from "./types.js";
+import type { ControlCenterCategory, ControlCenterRow } from "./control-center.js";
+
+export type VisualPreferenceAction =
+	| { kind: "header"; value: HeaderVariant }
+	| { kind: "mascot"; value: MascotChoice }
+	| { kind: "editor"; value: EditorMode };
+
+export type VisualPreferenceSnapshot = Pick<OsdyState,
+	"enabled" | "headerVariant" | "mascot" | "editorMode" | "editorEffective" | "smallMode">;
+
+export interface ControlCenterPreferences {
+	snapshot(): VisualPreferenceSnapshot;
+	/** Applies live before awaiting the existing global store. False means save failed. */
+	apply(action: VisualPreferenceAction): Promise<boolean>;
+}
+
+export function visualPreferenceLabel(action: VisualPreferenceAction): string {
+	return action.kind === "mascot" && action.value === "bts" ? "Bts" : action.value;
+}
+
+/** Explicit view adaptation only; application and persistence belong to runtime. */
+export function preferenceDetail(category: ControlCenterCategory, state: VisualPreferenceSnapshot): {
+	rows: ControlCenterRow[];
+	summary: string;
+	note: string;
+} | undefined {
+	let actions: VisualPreferenceAction[];
+	let current: string;
+	let effective = state.enabled ? "" : " | Osdy disabled";
+	switch (category) {
+		case "Header":
+			actions = HEADER_VARIANT_CHOICES.map((value) => ({ kind: "header", value }));
+			current = state.headerVariant;
+			break;
+		case "Mascot":
+			actions = MASCOT_CHOICES.map((value) => ({ kind: "mascot", value }));
+			current = state.mascot;
+			break;
+		case "Editor":
+			actions = Object.values(EDITOR_MODES).map((value) => ({ kind: "editor", value }));
+			current = state.editorMode;
+			effective += ` | Effective: ${state.editorEffective ? "extended" : "simple/native"}`;
+			if (state.smallMode) effective += " (small terminal)";
+			break;
+		default: return undefined;
+	}
+	const currentAction = actions.find((action) => action.value === current);
+	return {
+		rows: actions.map((action) => ({ label: visualPreferenceLabel(action), current: action.value === current, action })),
+		summary: `Current: ${currentAction ? visualPreferenceLabel(currentAction) : current}${effective}`,
+		note: state.enabled
+			? "Applies live; saves globally in Osdy settings."
+			: "Saves globally; visuals apply when Osdy is enabled.",
+	};
+}

package/extensions/osdy-pi/control-center-sounds.test.ts

@@ -0,0 +1,120 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { registerHooks } from "node:module";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import type { GlobalAudioNotificationSettings } from "./audio-notification-types.js";
+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);
+} });
+const { createControlCenterSounds } = await import("./control-center-sounds.js");
+
+function fixture(platform: "darwin" | "unsupported" = "darwin") {
+	let settings: GlobalAudioNotificationSettings = { version: 1, sounds: { completion: "/saved.wav" } };
+	let saveFails = false;
+	let loadFails = false;
+	let playFails = false;
+	let failAfterSave = false;
+	const played: string[] = [];
+	const writes: GlobalAudioNotificationSettings[] = [];
+	const service = createControlCenterSounds({
+		cwd: process.cwd(),
+		store: { path: "/unused", load: () => {
+			if (loadFails) throw new Error("refresh failed");
+			return Promise.resolve(settings);
+		}, save: (value) => {
+			if (saveFails) throw new Error("disk full");
+			writes.push(value); settings = value;
+			if (failAfterSave) loadFails = true;
+			return Promise.resolve();
+		} },
+		effective: (_settings, event) => event === "completion"
+			? { source: "startup-flag", path: "/flag.wav" } : { source: "unconfigured" },
+		resolve: (event) => Promise.resolve({ ok: true, event, path: "/flag.wav", source: "startup-flag" }),
+		playback: { platform, play: (path) => {
+			if (playFails) throw new Error("player failed");
+			played.push(path);
+			return Promise.resolve();
+		} },
+		validate: (value) => Promise.resolve(value === "valid.wav"
+			? { ok: true, inputPath: value, resolvedPath: "/valid.wav", persistedPath: "/valid.wav" }
+			: { ok: false, reason: "missing" }),
+	});
+	return { service, played, writes, settings: () => settings,
+		failSave: () => { saveFails = true; }, failLoad: () => { loadFails = true; }, failPlay: () => { playFails = true; }, failRefresh: () => { failAfterSave = true; } };
+}
+
+void test("Sounds shows saved/effective paths and flag precedence without playing or saving", async () => {
+	const f = fixture();
+	const view = await f.service.read();
+	assert.match(view.summary, /Master.*unavailable/);
+	assert.match(view.rows[0]?.details?.join(" | ") ?? "", /saved: \/saved.wav.*Effective \(startup-flag\): \/flag.wav/);
+	assert.match(view.note, /clearing.*does not disable/i);
+	assert.equal(view.rows.length, 12);
+	assert.deepEqual(f.played, []); assert.deepEqual(f.writes, []);
+});
+
+void test("configure validates before saving and refreshes; clear keeps v1 and other paths", async () => {
+	const f = fixture();
+	assert.equal((await f.service.apply({ kind: "sound-set", event: "completion", path: "missing.wav" })).failed, true);
+	assert.equal(f.writes.length, 0);
+	assert.equal((await f.service.apply({ kind: "sound-set", event: "question", path: "valid.wav" })).failed, false);
+	assert.deepEqual(f.settings(), { version: 1, sounds: { completion: "/saved.wav", question: "/valid.wav" } });
+	const clear = await f.service.apply({ kind: "sound-clear", event: "completion" });
+	assert.equal(clear.failed, false);
+	assert.deepEqual(f.settings(), { version: 1, sounds: { question: "/valid.wav" } });
+	assert.match((await f.service.read()).rows[0]?.details?.join(" | ") ?? "", /saved: none.*Effective \(startup-flag\): \/flag.wav/);
+	assert.deepEqual(f.played, []);
+});
+
+void test("test playback is explicit, reports unavailable platforms and player failures", async () => {
+	const f = fixture();
+	assert.equal((await f.service.apply({ kind: "sound-test", event: "completion" })).failed, false);
+	assert.deepEqual(f.played, ["/flag.wav"]); assert.deepEqual(f.writes, []);
+	f.failPlay();
+	assert.match((await f.service.apply({ kind: "sound-test", event: "completion" })).message, /player failed/);
+	const unsupported = fixture("unsupported");
+	assert.match((await unsupported.service.apply({ kind: "sound-test", event: "completion" })).message, /unavailable/);
+	assert.deepEqual(unsupported.played, []);
+});
+
+void test("save errors and refresh errors never falsely report success", async () => {
+	const f = fixture(); f.failSave();
+	assert.match((await f.service.apply({ kind: "sound-clear", event: "completion" })).message, /Not saved.*disk full/);
+	const g = fixture();
+	g.failLoad();
+	assert.equal((await g.service.apply({ kind: "sound-clear", event: "completion" })).failed, true);
+	assert.deepEqual(g.writes, []);
+	const h = fixture(); h.failRefresh();
+	const result = await h.service.apply({ kind: "sound-clear", event: "completion" });
+	assert.equal(result.failed, true);
+	assert.match(result.message, /Saved globally, but runtime refresh failed/);
+	assert.deepEqual(h.writes, [{ version: 1, sounds: {} }]);
+});
+
+void test("default validator rejects missing, unsupported and directory paths without saving", async () => {
+	const root = mkdtempSync(join(tmpdir(), "osdy-sound-validation-"));
+	mkdirSync(join(root, "directory.wav"));
+	writeFileSync(join(root, "sound.wav"), "mock wave bytes");
+	const f = fixture();
+	const writes: GlobalAudioNotificationSettings[] = [];
+	const service = createControlCenterSounds({ cwd: root,
+		store: { path: "/unused", load: () => Promise.resolve(f.settings()), save: (value) => { writes.push(value); return Promise.resolve(); } },
+		effective: () => ({ source: "unconfigured" }),
+		resolve: (event) => Promise.resolve({ ok: false, event, source: "unconfigured", reason: "unconfigured" }),
+		playback: { platform: "unsupported", play: () => Promise.reject(new Error("must not play")) },
+	});
+	for (const path of ["README.md", "absent-file.wav", "directory.wav", ""]) {
+		const result = await service.apply({ kind: "sound-set", event: "error", path });
+		assert.equal(result.failed, true); assert.match(result.message, /Invalid/);
+	}
+	assert.equal(writes.length, 0);
+	assert.equal((await service.apply({ kind: "sound-set", event: "error", path: "sound.wav" })).failed, false);
+	assert.equal(writes[0]?.sounds.error, join(root, "sound.wav"));
+});