@duckmind/dm-darwin-x64 0.35.6 → 0.35.9

package/extensions/dm-usage/index.ts

@@ -9,9 +9,10 @@
 
 import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@mariozechner/pi-coding-agent";
 import { DynamicBorder } from "@mariozechner/pi-coding-agent";
-import { CancellableLoader, Container, Spacer, matchesKey, visibleWidth, truncateToWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { CancellableLoader, Container, Spacer, matchesKey, visibleWidth, truncateToWidth, wrapTextWithAnsi, type AutocompleteItem } from "@mariozechner/pi-tui";
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 
 // =============================================================================
@@ -77,6 +78,7 @@ interface GlobalSessionSpan {
 interface TimeFilteredStats {
 	providers: Map<string, ProviderStats>;
 	totals: TotalStats;
+	dailySpend: Map<string, number>;
 	insights: PeriodInsights;
 }
 
@@ -89,6 +91,31 @@ interface UsageData {
 
 type TabName = "today" | "thisWeek" | "lastWeek" | "allTime";
 type ViewMode = "table" | "insights";
+type UsageSubcommand = "use" | "show" | "rotation" | "verify" | "path" | "reset" | "help";
+type UsageResetTarget = "manual" | "quota" | "all";
+
+interface UsageManagedAccount {
+	id: string;
+	label: string;
+	provider: string;
+	source: "session" | "manual";
+	updatedAt: string;
+	quotaExhaustedUntil?: number;
+}
+
+interface UsageManagedState {
+	version: 1;
+	manualAccountId?: string;
+	removedAccountIds: string[];
+	accounts: UsageManagedAccount[];
+	updatedAt: string;
+}
+
+interface UsageManagedSummary {
+	data: UsageData;
+	state: UsageManagedState;
+	accounts: UsageManagedAccount[];
+}
 
 // =============================================================================
 // Column Configuration
@@ -194,10 +221,25 @@ const TABLE_LAYOUTS: TableLayoutCandidate[] = [
 // Data Collection
 // =============================================================================
 
-function getSessionsDir(): string {
+function getAgentDir(): string {
 	// Respect DM_CODING_AGENT_DIR, keeping PI_CODING_AGENT_DIR only as a compatibility fallback
-	const agentDir = process.env.DM_CODING_AGENT_DIR || process.env.PI_CODING_AGENT_DIR || join(homedir(), ".dm", "agent");
-	return join(agentDir, "sessions");
+	return process.env.DM_CODING_AGENT_DIR || process.env.PI_CODING_AGENT_DIR || join(homedir(), ".dm", "agent");
+}
+
+function getSessionsDir(): string {
+	return join(getAgentDir(), "sessions");
+}
+
+function getUsageStateDir(): string {
+	return join(getAgentDir(), "usage");
+}
+
+function getUsageStatePath(): string {
+	return join(getUsageStateDir(), "state.json");
+}
+
+function getAgentSettingsPath(): string {
+	return join(getAgentDir(), "settings.json");
 }
 
 async function collectSessionFilesRecursively(dir: string, files: string[], signal?: AbortSignal): Promise<void> {
@@ -335,6 +377,7 @@ function emptyTimeFilteredStats(): TimeFilteredStats {
 	return {
 		providers: new Map(),
 		totals: { sessions: 0, messages: 0, cost: 0, tokens: emptyTokens() },
+		dailySpend: new Map(),
 		insights: { insights: [] },
 	};
 }
@@ -422,6 +465,10 @@ function addMessagesToUsageData(
 			accumulateStats(providerStats, msg.cost, tokens);
 
 			accumulateStats(stats.totals, msg.cost, tokens);
+			if (msg.cost > 0 && msg.timestamp > 0) {
+				const dayKey = new Date(msg.timestamp).toISOString().slice(0, 10);
+				stats.dailySpend.set(dayKey, (stats.dailySpend.get(dayKey) ?? 0) + msg.cost);
+			}
 			sessionContributed[period] = true;
 
 			const raw = rawByPeriod[period];
@@ -507,6 +554,449 @@ async function collectUsageData(signal?: AbortSignal): Promise<UsageData | null>
 	return data;
 }
 
+// =============================================================================
+// Managed Account Command Helpers
+// =============================================================================
+
+const USAGE_SUBCOMMANDS = ["use", "show", "rotation", "verify", "path", "reset", "help"] as const;
+const USAGE_RESET_TARGETS = ["manual", "quota", "all"] as const;
+const USAGE_HELP_TEXT = [
+	"Usage: /usage [use|show|rotation|verify|path|reset|help]",
+	"use: select, activate, or remove managed account",
+	"show: managed account and usage summary",
+	"rotation: current rotation behavior",
+	"verify: runtime health checks",
+	"path: storage and settings locations",
+	"reset: clear manual or quota state",
+].join("\n");
+
+function parseUsageCommandArgs(args: string): { subcommand?: string; rest: string } {
+	const trimmed = args.trim();
+	if (!trimmed) return { rest: "" };
+	const firstSpaceIndex = trimmed.indexOf(" ");
+	if (firstSpaceIndex < 0) return { subcommand: trimmed.toLowerCase(), rest: "" };
+	return {
+		subcommand: trimmed.slice(0, firstSpaceIndex).toLowerCase(),
+		rest: trimmed.slice(firstSpaceIndex + 1).trim(),
+	};
+}
+
+function isUsageSubcommand(value: string): value is UsageSubcommand {
+	return USAGE_SUBCOMMANDS.some((subcommand) => subcommand === value);
+}
+
+function parseUsageResetTarget(value: string): UsageResetTarget | undefined {
+	if (value === "manual" || value === "quota" || value === "all") return value;
+	return undefined;
+}
+
+function toAutocompleteItems(values: readonly string[]): AutocompleteItem[] {
+	return values.map((value) => ({ value, label: value }));
+}
+
+function getUsageCommandCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+	const trimmedStart = argumentPrefix.trimStart();
+	if (!trimmedStart) return toAutocompleteItems(USAGE_SUBCOMMANDS);
+
+	const firstSpaceIndex = trimmedStart.indexOf(" ");
+	if (firstSpaceIndex < 0) {
+		const matches = USAGE_SUBCOMMANDS.filter((value) => value.startsWith(trimmedStart.toLowerCase()));
+		return matches.length > 0 ? toAutocompleteItems(matches) : null;
+	}
+
+	const subcommand = trimmedStart.slice(0, firstSpaceIndex).toLowerCase();
+	const rest = trimmedStart.slice(firstSpaceIndex + 1).toLowerCase();
+	if (subcommand === "reset") {
+		const matches = USAGE_RESET_TARGETS.filter((value) => value.startsWith(rest));
+		return matches.length > 0 ? matches.map((value) => ({ value: `reset ${value}`, label: value })) : null;
+	}
+	if (subcommand === "use") {
+		const matches = ["clear", "remove"].filter((value) => value.startsWith(rest));
+		return matches.length > 0 ? matches.map((value) => ({ value: `use ${value}`, label: value })) : null;
+	}
+	return null;
+}
+
+function emptyUsageManagedState(): UsageManagedState {
+	return { version: 1, removedAccountIds: [], accounts: [], updatedAt: new Date(0).toISOString() };
+}
+
+function asString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function normalizeUsageManagedAccount(value: unknown): UsageManagedAccount | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	const id = asString(record.id);
+	const provider = asString(record.provider) ?? id;
+	if (!id || !provider) return undefined;
+	const label = asString(record.label) ?? formatProviderName(provider);
+	const source = record.source === "manual" ? "manual" : "session";
+	const updatedAt = asString(record.updatedAt) ?? new Date(0).toISOString();
+	const quota =
+		typeof record.quotaExhaustedUntil === "number" && Number.isFinite(record.quotaExhaustedUntil)
+			? record.quotaExhaustedUntil
+			: undefined;
+	return { id, label, provider, source, updatedAt, quotaExhaustedUntil: quota };
+}
+
+function normalizeUsageManagedState(value: unknown): UsageManagedState {
+	const empty = emptyUsageManagedState();
+	if (!value || typeof value !== "object") return empty;
+	const record = value as Record<string, unknown>;
+	const accounts = Array.isArray(record.accounts)
+		? record.accounts.map(normalizeUsageManagedAccount).filter((account): account is UsageManagedAccount => Boolean(account))
+		: [];
+	const removedAccountIds = Array.isArray(record.removedAccountIds)
+		? record.removedAccountIds.map(asString).filter((id): id is string => Boolean(id))
+		: [];
+	return {
+		version: 1,
+		manualAccountId: asString(record.manualAccountId),
+		removedAccountIds,
+		accounts,
+		updatedAt: asString(record.updatedAt) ?? empty.updatedAt,
+	};
+}
+
+function getErrorCode(error: unknown): string | undefined {
+	return error && typeof error === "object" && "code" in error ? String((error as { code?: unknown }).code) : undefined;
+}
+
+async function readUsageManagedState(): Promise<{ state: UsageManagedState; error?: string }> {
+	try {
+		const raw = await readFile(getUsageStatePath(), "utf8");
+		return { state: normalizeUsageManagedState(JSON.parse(raw)) };
+	} catch (error) {
+		if (getErrorCode(error) === "ENOENT") return { state: emptyUsageManagedState() };
+		return { state: emptyUsageManagedState(), error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+async function saveUsageManagedState(state: UsageManagedState): Promise<void> {
+	state.version = 1;
+	state.updatedAt = new Date().toISOString();
+	state.removedAccountIds = [...new Set(state.removedAccountIds)].sort();
+	state.accounts = state.accounts
+		.filter((account) => !state.removedAccountIds.includes(account.id))
+		.sort((a, b) => a.label.localeCompare(b.label));
+	await mkdir(dirname(getUsageStatePath()), { recursive: true });
+	await writeFile(getUsageStatePath(), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+function isQuotaActive(account: UsageManagedAccount): boolean {
+	return typeof account.quotaExhaustedUntil === "number" && account.quotaExhaustedUntil > Date.now();
+}
+
+function getAccountStats(data: UsageData, account: UsageManagedAccount): ProviderStats | undefined {
+	return data.allTime.providers.get(account.provider);
+}
+
+function getManagedAccounts(data: UsageData, state: UsageManagedState): UsageManagedAccount[] {
+	const now = new Date().toISOString();
+	const accounts = new Map<string, UsageManagedAccount>();
+	for (const account of state.accounts) {
+		if (!state.removedAccountIds.includes(account.id)) accounts.set(account.id, account);
+	}
+	for (const provider of data.allTime.providers.keys()) {
+		if (state.removedAccountIds.includes(provider) || accounts.has(provider)) continue;
+		accounts.set(provider, {
+			id: provider,
+			label: formatProviderName(provider),
+			provider,
+			source: "session",
+			updatedAt: now,
+		});
+	}
+
+	return Array.from(accounts.values()).sort((a, b) => {
+		const manualId = state.manualAccountId;
+		if (a.id === manualId && b.id !== manualId) return -1;
+		if (b.id === manualId && a.id !== manualId) return 1;
+		if (isQuotaActive(a) !== isQuotaActive(b)) return isQuotaActive(a) ? 1 : -1;
+		const costDelta = (getAccountStats(data, b)?.cost ?? 0) - (getAccountStats(data, a)?.cost ?? 0);
+		if (costDelta !== 0) return costDelta;
+		return a.label.localeCompare(b.label);
+	});
+}
+
+function getActiveManagedAccount(accounts: UsageManagedAccount[], state: UsageManagedState): UsageManagedAccount | undefined {
+	const manual = accounts.find((account) => account.id === state.manualAccountId && !isQuotaActive(account));
+	return manual ?? accounts.find((account) => !isQuotaActive(account));
+}
+
+function findManagedAccount(accounts: UsageManagedAccount[], query: string): UsageManagedAccount | undefined {
+	const normalized = query.trim().toLowerCase();
+	return accounts.find(
+		(account) =>
+			account.id.toLowerCase() === normalized ||
+			account.provider.toLowerCase() === normalized ||
+			account.label.toLowerCase() === normalized
+	);
+}
+
+function formatManagedAccountLine(account: UsageManagedAccount, data: UsageData, state: UsageManagedState): string {
+	const stats = getAccountStats(data, account);
+	const tags = [
+		state.manualAccountId === account.id ? "manual" : undefined,
+		isQuotaActive(account) ? "quota" : undefined,
+		account.source === "manual" ? "manual-entry" : undefined,
+	]
+		.filter(Boolean)
+		.join(", ");
+	const suffix = tags ? ` (${tags})` : "";
+	const cost = stats ? formatCost(stats.cost) : formatCost(0);
+	const messages = stats ? formatNumber(stats.messages) : "0";
+	const sessions = stats ? formatNumber(stats.sessions.size) : "0";
+	return `${account.label}${suffix} · id=${account.id} · spend=${cost} · messages=${messages} · sessions=${sessions}`;
+}
+
+async function loadUsageManagedSummary(ctx: ExtensionCommandContext): Promise<UsageManagedSummary | null> {
+	const data = await collectUsageData(ctx.signal);
+	if (!data) {
+		ctx.ui.notify("Usage data unavailable or cancelled.", "warning");
+		return null;
+	}
+	const { state, error } = await readUsageManagedState();
+	if (error) {
+		ctx.ui.notify(`dm-usage state unreadable; using empty state: ${error}`, "warning");
+	}
+	return { data, state, accounts: getManagedAccounts(data, state) };
+}
+
+function managedAccountNoDataMessage(): string {
+	return "No managed accounts found. Run /usage after at least one provider response, or use /usage use <provider-id> to create a local manual entry.";
+}
+
+async function activateUsageAccount(ctx: ExtensionCommandContext, summary: UsageManagedSummary, account: UsageManagedAccount): Promise<void> {
+	summary.state.manualAccountId = account.id;
+	summary.state.removedAccountIds = summary.state.removedAccountIds.filter((id) => id !== account.id);
+	summary.state.accounts = summary.accounts.map((item) => (item.id === account.id ? { ...item, updatedAt: new Date().toISOString() } : item));
+	await saveUsageManagedState(summary.state);
+	ctx.ui.notify(`dm-usage: now using ${account.label} (${account.id})`, "info");
+}
+
+async function clearUsageManualAccount(ctx: ExtensionCommandContext, state: UsageManagedState): Promise<void> {
+	const hadManual = Boolean(state.manualAccountId);
+	state.manualAccountId = undefined;
+	await saveUsageManagedState(state);
+	ctx.ui.notify(`dm-usage: manual account ${hadManual ? "cleared" : "was not set"}`, "info");
+}
+
+async function removeUsageAccountState(ctx: ExtensionCommandContext, summary: UsageManagedSummary, account: UsageManagedAccount): Promise<void> {
+	summary.state.removedAccountIds = [...summary.state.removedAccountIds, account.id];
+	if (summary.state.manualAccountId === account.id) summary.state.manualAccountId = undefined;
+	summary.state.accounts = summary.accounts.filter((item) => item.id !== account.id);
+	await saveUsageManagedState(summary.state);
+	ctx.ui.notify(`dm-usage: removed local managed-account state for ${account.label}; session data was not changed.`, "info");
+}
+
+async function runUsageUseSubcommand(ctx: ExtensionCommandContext, rest: string): Promise<void> {
+	const summary = await loadUsageManagedSummary(ctx);
+	if (!summary) return;
+
+	if (rest === "clear") {
+		await clearUsageManualAccount(ctx, summary.state);
+		return;
+	}
+
+	if (rest.startsWith("remove ")) {
+		const account = findManagedAccount(summary.accounts, rest.slice("remove ".length));
+		if (!account) {
+			ctx.ui.notify(`Unknown managed account: ${rest.slice("remove ".length)}`, "warning");
+			return;
+		}
+		await removeUsageAccountState(ctx, summary, account);
+		return;
+	}
+
+	if (rest) {
+		const account =
+			findManagedAccount(summary.accounts, rest) ??
+			({ id: rest, label: formatProviderName(rest), provider: rest, source: "manual", updatedAt: new Date().toISOString() } satisfies UsageManagedAccount);
+		if (!summary.accounts.some((item) => item.id === account.id)) summary.accounts.push(account);
+		await activateUsageAccount(ctx, summary, account);
+		return;
+	}
+
+	if (!ctx.hasUI) {
+		ctx.ui.notify(summary.accounts.length ? summary.accounts.map((account) => formatManagedAccountLine(account, summary.data, summary.state)).join("\n") : managedAccountNoDataMessage(), summary.accounts.length ? "info" : "warning");
+		return;
+	}
+
+	const options = [
+		...summary.accounts.map((account) => formatManagedAccountLine(account, summary.data, summary.state)),
+		"add manual account",
+		"clear manual account",
+	];
+	const selected = await ctx.ui.select("DuckMind Usage Accounts", options);
+	if (!selected) return;
+	if (selected === "add manual account") {
+		const id = (await ctx.ui.input("Managed account id (provider key, no secret)"))?.trim();
+		if (!id) return;
+		await runUsageUseSubcommand(ctx, id);
+		return;
+	}
+	if (selected === "clear manual account") {
+		await clearUsageManualAccount(ctx, summary.state);
+		return;
+	}
+
+	const account = summary.accounts[options.indexOf(selected)];
+	if (!account) return;
+	const action = await ctx.ui.select("Account Action", ["activate", "remove local state", "cancel"]);
+	if (action === "activate") await activateUsageAccount(ctx, summary, account);
+	if (action === "remove local state") await removeUsageAccountState(ctx, summary, account);
+}
+
+async function runUsageShowSubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	const summary = await loadUsageManagedSummary(ctx);
+	if (!summary) return;
+	const active = getActiveManagedAccount(summary.accounts, summary.state);
+	const hiddenCount = summary.state.removedAccountIds.length;
+	const lines = [
+		"DuckMind Usage managed account summary",
+		`active: ${active ? `${active.label} (${active.id})` : "none"}`,
+		`manual: ${summary.state.manualAccountId ?? "none"}`,
+		`accounts: ${summary.accounts.length}${hiddenCount ? ` · hidden=${hiddenCount}` : ""}`,
+		`all-time: spend=${formatCost(summary.data.allTime.totals.cost)} · messages=${formatNumber(summary.data.allTime.totals.messages)} · sessions=${formatNumber(summary.data.allTime.totals.sessions)} · tokens=${formatTokens(summary.data.allTime.totals.tokens.total)}`,
+		"",
+		...(summary.accounts.length
+			? summary.accounts.map((account) => formatManagedAccountLine(account, summary.data, summary.state))
+			: [managedAccountNoDataMessage()]),
+	];
+	if (ctx.hasUI) {
+		await ctx.ui.select("DuckMind Usage Summary", lines);
+	} else {
+		ctx.ui.notify(lines.join("\n"), "info");
+	}
+}
+
+async function runUsageRotationSubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	const lines = [
+		"Current policy: manual account first, then accounts without quota cooldown, then highest all-time local spend, then alphabetical fallback.",
+		"dm-usage is observational: this state changes /usage account summaries only and does not route provider requests or store API secrets.",
+		"Use /usage reset manual to clear manual selection, or /usage reset quota to clear quota cooldown markers.",
+	];
+	if (ctx.hasUI) {
+		await ctx.ui.select("DuckMind Usage Rotation", lines);
+	} else {
+		ctx.ui.notify(lines.join(" "), "info");
+	}
+}
+
+async function isDirectoryReadable(path: string): Promise<boolean> {
+	try {
+		await access(path, fsConstants.R_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function isWritableDirectoryFor(filePath: string): Promise<boolean> {
+	try {
+		const directory = dirname(filePath);
+		await mkdir(directory, { recursive: true });
+		await access(directory, fsConstants.R_OK | fsConstants.W_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function runUsageVerifySubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	const sessionsReadable = await isDirectoryReadable(getSessionsDir());
+	const stateWritable = await isWritableDirectoryFor(getUsageStatePath());
+	const settingsWritable = await isWritableDirectoryFor(getAgentSettingsPath());
+	const stateRead = await readUsageManagedState();
+	const summary = await loadUsageManagedSummary(ctx);
+	const accounts = summary?.accounts.length ?? 0;
+	const active = summary ? getActiveManagedAccount(summary.accounts, summary.state)?.id ?? "none" : "none";
+	const ok = sessionsReadable && stateWritable && settingsWritable && !stateRead.error;
+	const lines = [
+		`verify: ${ok ? "PASS" : "WARN"}`,
+		`sessions readable: ${sessionsReadable ? "yes" : "no"}`,
+		`state directory writable: ${stateWritable ? "yes" : "no"}`,
+		`settings directory writable: ${settingsWritable ? "yes" : "no"}`,
+		`state json: ${stateRead.error ? `invalid (${stateRead.error})` : "ok"}`,
+		`managed accounts: ${accounts}`,
+		`active account: ${active}`,
+	];
+	if (ctx.hasUI) {
+		await ctx.ui.select(`DuckMind Usage Verify (${ok ? "PASS" : "WARN"})`, lines);
+	} else {
+		ctx.ui.notify(lines.join("\n"), ok ? "info" : "warning");
+	}
+}
+
+async function runUsagePathSubcommand(ctx: ExtensionCommandContext): Promise<void> {
+	const lines = [
+		`Session storage: ${getSessionsDir()}`,
+		`Managed account state: ${getUsageStatePath()}`,
+		`Agent settings: ${getAgentSettingsPath()}`,
+	];
+	if (ctx.hasUI) {
+		await ctx.ui.select("DuckMind Usage Paths", lines);
+	} else {
+		ctx.ui.notify(lines.join("\n"), "info");
+	}
+}
+
+async function chooseUsageResetTarget(ctx: ExtensionCommandContext, argument: string): Promise<UsageResetTarget | undefined> {
+	const explicitTarget = parseUsageResetTarget(argument.toLowerCase());
+	if (explicitTarget) return explicitTarget;
+	if (argument) {
+		ctx.ui.notify("Unknown reset target. Use: /usage reset [manual|quota|all]", "warning");
+		return undefined;
+	}
+	if (!ctx.hasUI) return "all";
+	const selected = await ctx.ui.select("Reset DuckMind Usage State", [
+		"manual - clear manual account override",
+		"quota - clear quota cooldown markers",
+		"all - clear manual override, quota cooldown markers, and hidden account state",
+	]);
+	if (!selected) return undefined;
+	if (selected.startsWith("manual")) return "manual";
+	if (selected.startsWith("quota")) return "quota";
+	return "all";
+}
+
+async function runUsageResetSubcommand(ctx: ExtensionCommandContext, rest: string): Promise<void> {
+	const target = await chooseUsageResetTarget(ctx, rest);
+	if (!target) return;
+	const { state } = await readUsageManagedState();
+	const hadManual = Boolean(state.manualAccountId);
+	if (target === "manual" || target === "all") state.manualAccountId = undefined;
+	let quotaCleared = 0;
+	if (target === "quota" || target === "all") {
+		state.accounts = state.accounts.map((account) => {
+			if (account.quotaExhaustedUntil === undefined) return account;
+			quotaCleared++;
+			const { quotaExhaustedUntil: _quotaExhaustedUntil, ...restAccount } = account;
+			return restAccount;
+		});
+	}
+	const hiddenCleared = target === "all" ? state.removedAccountIds.length : 0;
+	if (target === "all") state.removedAccountIds = [];
+	await saveUsageManagedState(state);
+	ctx.ui.notify(
+		`reset: target=${target} manualCleared=${hadManual && !state.manualAccountId ? "yes" : "no"} quotaCleared=${quotaCleared} hiddenCleared=${hiddenCleared}`,
+		"info"
+	);
+}
+
+async function runUsageSubcommand(subcommand: UsageSubcommand, rest: string, ctx: ExtensionCommandContext): Promise<void> {
+	if (subcommand === "use") return runUsageUseSubcommand(ctx, rest);
+	if (subcommand === "show") return runUsageShowSubcommand(ctx);
+	if (subcommand === "rotation") return runUsageRotationSubcommand(ctx);
+	if (subcommand === "verify") return runUsageVerifySubcommand(ctx);
+	if (subcommand === "path") return runUsagePathSubcommand(ctx);
+	if (subcommand === "reset") return runUsageResetSubcommand(ctx, rest);
+	ctx.ui.notify(USAGE_HELP_TEXT, "info");
+}
+
 // =============================================================================
 // Insights
 // =============================================================================
@@ -753,6 +1243,61 @@ function getTableLayout(width: number): TableLayout {
 	};
 }
 
+// Visual shell inspired by robhowley/pi-userland packages/pi-openrouter
+// overlay/chart helpers, kept local-session-only for dm-usage.
+function renderPanel(title: string, rows: string[], width: number, theme: Theme): string[] {
+	const safeWidth = Math.max(Math.floor(width), 0);
+	if (safeWidth < 12) {
+		return clampLines([theme.fg("accent", theme.bold(title)), ...rows, ""], safeWidth);
+	}
+
+	const innerWidth = Math.max(safeWidth - 2, 1);
+	const titleText = ` ${title} `;
+	const visibleTitle = truncateToWidth(titleText, Math.max(innerWidth - 1, 1), "");
+	const titleWidth = visibleWidth(visibleTitle);
+	const topRight = Math.max(innerWidth - titleWidth, 0);
+	const top = `╭${visibleTitle}${"─".repeat(topRight)}╮`;
+	const bottom = `╰${"─".repeat(innerWidth)}╯`;
+	const body = rows.length > 0 ? rows : [theme.fg("dim", "No data")];
+
+	return [
+		theme.fg("border", top),
+		...body.map((line) => panelRow(line, innerWidth, theme)),
+		theme.fg("border", bottom),
+		"",
+	];
+}
+
+function panelRow(content: string, innerWidth: number, theme: Theme): string {
+	const fitted = truncateToWidth(content, innerWidth);
+	const padding = Math.max(innerWidth - visibleWidth(fitted), 0);
+	return `${theme.fg("border", "│")}${fitted}${" ".repeat(padding)}${theme.fg("border", "│")}`;
+}
+
+function renderSpendSparkline(dailySpend: Map<string, number>, maxWidth: number): string {
+	if (dailySpend.size === 0) return "No spend data";
+
+	const sortedDays = Array.from(dailySpend.keys()).sort();
+	const visibleDays = sortedDays.slice(-Math.max(1, Math.min(30, maxWidth)));
+	const values = visibleDays.map((day) => dailySpend.get(day) ?? 0);
+	const max = Math.max(...values);
+	if (max <= 0) return "No spend";
+
+	const blocks = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+	return values
+		.map((value) => {
+			const idx = Math.max(0, Math.min(blocks.length - 1, Math.ceil((value / max) * blocks.length) - 1));
+			return blocks[idx];
+		})
+		.join("");
+}
+
+function formatDailyAverage(stats: TimeFilteredStats): string {
+	const days = stats.dailySpend.size;
+	if (days === 0) return "avg/day -";
+	return `avg/day ${formatCost(stats.totals.cost / days)}`;
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -846,8 +1391,9 @@ class UsageComponent {
 		if (this.viewMode === "insights") {
 			return clampLines(
 				[
-					...this.renderTitle(),
+					...this.renderTitle(width),
 					...this.renderTabs(width, getTableLayout(width)),
+					...this.renderSpendChart(width),
 					...this.renderInsights(width),
 					...this.renderHelp(width),
 				],
@@ -858,7 +1404,7 @@ class UsageComponent {
 		const layout = getTableLayout(width);
 		return clampLines(
 			[
-				...this.renderTitle(),
+				...this.renderTitle(width),
 				...this.renderTabs(width, layout),
 				...this.renderHeader(layout),
 				...this.renderRows(layout),
@@ -870,10 +1416,34 @@ class UsageComponent {
 		);
 	}
 
-	private renderTitle(): string[] {
+	private renderTitle(width: number): string[] {
 		const th = this.theme;
+		const stats = this.data[this.activeTab];
 		const label = this.viewMode === "insights" ? "Usage Insights" : "Usage Statistics";
-		return [th.fg("accent", th.bold(label)), ""];
+		return renderPanel(
+			"DuckMind Usage",
+			[
+				`${th.fg("accent", th.bold(label))} · ${TAB_LABELS[this.activeTab]}`,
+				`Spend ${formatCost(stats.totals.cost)} · ${formatNumber(stats.totals.messages)} messages · ${formatTokens(stats.totals.tokens.total)} tokens`,
+				`Providers ${formatNumber(stats.providers.size)} · Sessions ${formatNumber(stats.totals.sessions)} · ${formatDailyAverage(stats)}`,
+			],
+			width,
+			th
+		);
+	}
+
+	private renderSpendChart(width: number): string[] {
+		const th = this.theme;
+		const stats = this.data[this.activeTab];
+		return renderPanel(
+			"Daily Spend",
+			[
+				th.fg("accent", renderSpendSparkline(stats.dailySpend, Math.max(width - 4, 10))),
+				th.fg("dim", "Local session spend, last 30 active UTC days"),
+			],
+			width,
+			th
+		);
 	}
 
 	private renderInsights(width: number): string[] {
@@ -1075,9 +1645,21 @@ class UsageComponent {
 
 export default function (pi: ExtensionAPI) {
 	pi.registerCommand("usage", {
-		description: "Show usage statistics dashboard",
-		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+		description: `Show usage statistics dashboard and account tools: ${USAGE_SUBCOMMANDS.join(", ")}`,
+		getArgumentCompletions: getUsageCommandCompletions,
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const parsed = parseUsageCommandArgs(args);
+			if (parsed.subcommand) {
+				if (!isUsageSubcommand(parsed.subcommand)) {
+					ctx.ui.notify(`Unknown /usage subcommand: ${parsed.subcommand}\n${USAGE_HELP_TEXT}`, "warning");
+					return;
+				}
+				await runUsageSubcommand(parsed.subcommand, parsed.rest, ctx);
+				return;
+			}
+
 			if (!ctx.hasUI) {
+				await runUsageShowSubcommand(ctx);
 				return;
 			}