vibe-usage-cli 0.0.0-stage → 0.1.1

package/build/core/diagnostics.d.ts

@@ -0,0 +1,25 @@
+import { type ProviderId } from '../shared/catalog.ts';
+import type { Diagnostics, ProviderStatus, Remedy, Snapshot, StatusCode } from '../shared/types.ts';
+export type { AccountDiagnostics, Diagnostics, ProviderDiagnostics, Remedy } from '../shared/types.ts';
+import type { Environment } from './environment.ts';
+export declare const REMEDY_TEXT: Readonly<Record<Remedy, string>>;
+export declare const remedyFor: (status: ProviderStatus, code: StatusCode | null) => Remedy | null;
+export interface ToolProbe {
+    installed(providerId: ProviderId): Promise<boolean | null>;
+}
+export declare function collectDiagnostics(snapshot: Snapshot, probe: ToolProbe, now: number): Promise<Diagnostics>;
+export interface ToolProbeOptions {
+    homeDir?: string;
+    platform?: NodeJS.Platform;
+    env?: Environment;
+}
+export declare function createToolProbe({ homeDir, platform, env }?: ToolProbeOptions): ToolProbe;
+export interface ReportContext {
+    appVersion: string;
+    platform: string;
+    arch: string;
+    generatedAt: number;
+    homeDir?: string;
+}
+export declare function redactReport(text: string, homeDir?: string): string;
+export declare function renderDiagnosticsReport(diagnostics: Diagnostics, context: ReportContext): string;

package/build/core/diagnostics.js

@@ -0,0 +1,229 @@
+// What the diagnostics screen and its copyable report show: whether each tool is present,
+// the state of its accounts, how fresh their readings are, and a concrete next step.
+// Accounts appear only as ordinals; nothing here carries a label, address, path or token.
+import os from 'node:os';
+import path from 'node:path';
+import { findBinary, TOOL_INSTALLS, windowsAppPath } from "../providers/common.js";
+import { APP_NAME, DURATION_MS, PROVIDER_IDS, providerById } from "../shared/catalog.js";
+import { isDirectory, isFile } from "./files.js";
+// A reading older than this many refresh intervals is shown as stale.
+const STALE_INTERVALS = 3;
+// English wording for the report, which is meant to be pasted into a GitHub issue.
+export const REMEDY_TEXT = {
+    remedyInstallTool: 'Install the tool, then refresh.',
+    remedyInstallCli: "Install the tool's command-line interface, or check where it is installed.",
+    remedySignIn: 'Sign in again with the tool, then refresh.',
+    remedyOpenApp: 'Open the app, then refresh.',
+    remedyUnlockKeychain: 'Unlock the Keychain and allow access when asked, then refresh.',
+    remedyWaitRateLimit: 'Wait a few minutes; the provider is limiting requests.',
+    remedyCheckNetwork: 'Check the internet connection, proxy or VPN, then refresh.',
+    remedyCheckCertificates: "Check the system's certificate trust and any TLS-inspecting proxy, then refresh.",
+    remedyNotSupported: 'Reading this account is not supported on this system yet.',
+    remedyAddAccount: 'Sign in with the tool or add an account in Settings.',
+    remedyWaitForRefresh: 'Wait for the current reading to finish.',
+    remedyUpdateTool: 'Update the tool to its latest version, then refresh.',
+    remedyRetryLater: 'Refresh again later; if it keeps failing, report an issue with this report.',
+    remedyReportIssue: 'This looks like a Vibe Usage bug; report an issue with this report.'
+};
+// Every status and message code the app knows. Doubles as the allow-list of what may be
+// reported: anything else in a snapshot is treated as unknown.
+const REMEDIES = {
+    pending: 'remedyWaitForRefresh',
+    ok: null,
+    stale: 'remedyRetryLater',
+    no_limits_reported: null,
+    unavailable: 'remedyRetryLater',
+    no_accounts: 'remedyAddAccount',
+    auth_missing: 'remedySignIn',
+    auth_expired: 'remedySignIn',
+    auth_invalid: 'remedySignIn',
+    auth_rejected: 'remedySignIn',
+    rate_limited: 'remedyWaitRateLimit',
+    transport_error: 'remedyCheckNetwork',
+    request_timeout: 'remedyCheckNetwork',
+    tls_certificate_error: 'remedyCheckCertificates',
+    trust_store_unavailable: 'remedyCheckCertificates',
+    response_too_large: 'remedyUpdateTool',
+    invalid_response: 'remedyUpdateTool',
+    rpc_error: 'remedyUpdateTool',
+    http_rejected: 'remedyRetryLater',
+    endpoint_not_allowed: 'remedyReportIssue',
+    binary_missing: 'remedyInstallCli',
+    invalid_binary: 'remedyInstallCli',
+    process_failed: 'remedyRetryLater',
+    process_timeout: 'remedyRetryLater',
+    rpc_timeout: 'remedyRetryLater',
+    server_closed: 'remedyRetryLater',
+    app_closed: 'remedyOpenApp',
+    local_service_unavailable: 'remedyOpenApp',
+    unsupported_platform: 'remedyNotSupported',
+    unsupported_profile: 'remedyNotSupported',
+    keychain_unavailable: 'remedyUnlockKeychain',
+    provider_failed: 'remedyRetryLater'
+};
+const isCode = (value) => typeof value === 'string' && Object.hasOwn(REMEDIES, value);
+const accountStatus = (value) => isCode(value) && value !== 'unavailable' && value !== 'no_accounts' ? value : 'provider_failed';
+const providerStatus = (value) => (isCode(value) && value !== 'no_accounts' ? value : 'unavailable');
+const messageCode = (value) => isCode(value) && value !== 'pending' && value !== 'ok' && value !== 'stale' && value !== 'unavailable' ? value : null;
+// A stale reading keeps the failure that made it stale in its message code; that failure is
+// what the user can act on.
+export const remedyFor = (status, code) => REMEDIES[code ?? status];
+function freshness(fetchedAt, status, staleAfterMs, now) {
+    const time = typeof fetchedAt === 'string' ? Date.parse(fetchedAt) : NaN;
+    // A reading stamped in the future (a clock change) counts as just taken.
+    const ageMs = Number.isFinite(time) ? Math.max(0, now - time) : null;
+    return { ageMs, stale: status === 'stale' || (ageMs !== null && ageMs > staleAfterMs) };
+}
+// A failing tool usually takes its state from its accounts, whose remedy is more specific.
+function providerRemedy(installed, status, code, accounts) {
+    // A tool the probe misses but that still reads fine is present in a form the probe does not know.
+    if (installed === false && !accounts.some(a => a.status === 'ok'))
+        return 'remedyInstallTool';
+    if (status === 'ok' || code)
+        return remedyFor(status, code);
+    return accounts.find(a => a.remedy)?.remedy ?? remedyFor(status, null);
+}
+async function probeSafely(probe, id) {
+    try {
+        return await probe.installed(id);
+    }
+    catch {
+        return null;
+    }
+}
+export async function collectDiagnostics(snapshot, probe, now) {
+    const { settings } = snapshot;
+    const staleAfterMs = STALE_INTERVALS * settings.intervalSeconds * 1000;
+    const installed = await Promise.all(PROVIDER_IDS.map(id => probeSafely(probe, id)));
+    const providers = PROVIDER_IDS.map((id, index) => {
+        const state = snapshot.providers.find(provider => provider.id === id);
+        const measured = state?.accounts ?? [];
+        // Settings list every account, disabled ones too; the service measures only enabled ones.
+        const configured = settings.accounts.filter(a => a.providerId === id);
+        const accounts = [
+            ...configured.map(a => measured.find(m => m.id === a.id) ?? { ...a, status: 'pending' }),
+            ...measured.filter(m => !configured.some(a => a.id === m.id))
+        ];
+        const rows = accounts.map((a, i) => {
+            const status = accountStatus(a.status);
+            const code = messageCode(a.messageCode);
+            return {
+                ordinal: i + 1,
+                enabled: a.enabled,
+                primary: a.primary,
+                status,
+                messageCode: code,
+                ...freshness(a.fetchedAt, status, staleAfterMs, now),
+                // A disabled account is the user's choice, not a fault.
+                remedy: a.enabled ? remedyFor(status, code) : null
+            };
+        });
+        const status = providerStatus(state?.status);
+        const code = messageCode(state?.messageCode);
+        const isInstalled = installed[index] ?? null;
+        return {
+            id,
+            installed: isInstalled,
+            status,
+            messageCode: code,
+            accountCount: rows.length,
+            enabledCount: rows.filter(a => a.enabled).length,
+            ...freshness(state?.fetchedAt, status, staleAfterMs, now),
+            remedy: providerRemedy(isInstalled, status, code, rows),
+            accounts: rows
+        };
+    });
+    return { generatedAt: now, intervalSeconds: settings.intervalSeconds, refreshing: snapshot.refreshing, providers };
+}
+// Looks tools up the way launches do (TOOL_INSTALLS), but only looks for files: it never starts
+// a tool, which could ask to sign in or touch credentials.
+export function createToolProbe({ homeDir = os.homedir(), platform = process.platform, env = process.env } = {}) {
+    // null when this platform has no known app location.
+    async function hasApp(app) {
+        if (platform === 'win32')
+            return isFile(windowsAppPath(app, env, homeDir));
+        if (platform === 'darwin') {
+            const bundles = ['/Applications', path.join(homeDir, 'Applications')].map(dir => path.join(dir, `${app.mac}.app`));
+            return (await Promise.all(bundles.map(isDirectory))).some(Boolean);
+        }
+        return null;
+    }
+    async function hasBinary(name) {
+        return findBinary(name, { env, home: homeDir, platform }).then(() => true, () => false);
+    }
+    return {
+        async installed(providerId) {
+            const { binaries, app } = TOOL_INSTALLS[providerId];
+            const found = await Promise.all([...binaries.map(hasBinary), app ? hasApp(app) : false]);
+            if (found.includes(true))
+                return true;
+            return found.includes(null) ? null : false;
+        }
+    };
+}
+const yesNo = (value) => (value === null ? 'unknown' : value ? 'yes' : 'no');
+const safeToken = (value, pattern) => (pattern.test(value) ? value : 'unknown');
+const VERSION_PATTERN = /^[0-9A-Za-z.+-]{1,40}$/;
+const SYSTEM_PATTERN = /^[a-z0-9_]{1,20}$/i;
+function formatAge(ageMs) {
+    if (ageMs === null)
+        return 'never';
+    const minutes = Math.floor(ageMs / DURATION_MS.MINUTE);
+    if (minutes < 1)
+        return 'under 1 min ago';
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 48 ? `${hours} h ${minutes % 60} min ago` : `${Math.floor(hours / 24)} d ago`;
+}
+const formatStatus = (status, code) => (code && code !== status ? `${status} (${code})` : status);
+const formatRemedy = (remedy) => (remedy ? REMEDY_TEXT[remedy] : 'none');
+// Anything with an @, absolute Windows, UNC and POSIX paths, and home-relative paths.
+const REDACTIONS = [/[^\s|`]*@[^\s|`]*/g, /(?:\b[A-Za-z]:[\\/]|\\\\)[^\s|`]*/g, /(?<![\w.-])~?\/[^\s|`]*/g];
+const REDACTED = '[redacted]';
+// A last pass over the finished report, so a mistake upstream cannot leak identity.
+export function redactReport(text, homeDir) {
+    let result = text;
+    if (homeDir) {
+        // win32 parsing accepts both separators, whatever the host.
+        const user = path.win32.basename(homeDir);
+        const variants = new Set([homeDir, homeDir.replaceAll('\\', '/'), homeDir.replaceAll('/', '\\')]);
+        for (const variant of variants)
+            result = result.replace(new RegExp(RegExp.escape(variant), 'gi'), REDACTED);
+        // Short names would also match ordinary words in the report.
+        if (user.length >= 3)
+            result = result.replace(new RegExp(`\\b${RegExp.escape(user)}\\b`, 'gi'), REDACTED);
+    }
+    for (const pattern of REDACTIONS)
+        result = result.replace(pattern, REDACTED);
+    return result;
+}
+// Plain Markdown in English, to paste into a GitHub issue: codes, counts, ages and ordinals only.
+export function renderDiagnosticsReport(diagnostics, context) {
+    const lines = [
+        `## ${APP_NAME} diagnostics`,
+        '',
+        `- Version: ${safeToken(context.appVersion, VERSION_PATTERN)}`,
+        `- OS: ${safeToken(context.platform, SYSTEM_PATTERN)} ${safeToken(context.arch, SYSTEM_PATTERN)}`,
+        `- Generated: ${Number.isFinite(context.generatedAt) ? new Date(context.generatedAt).toISOString() : 'unknown'}`,
+        `- Refresh interval: ${diagnostics.intervalSeconds} s`,
+        `- Refreshing: ${yesNo(diagnostics.refreshing)}`
+    ];
+    for (const provider of diagnostics.providers) {
+        lines.push('', `### ${providerById(provider.id).name}`, '', `- Installed: ${yesNo(provider.installed)}`, `- Status: ${formatStatus(provider.status, provider.messageCode)}`, `- Accounts: ${provider.accountCount} configured, ${provider.enabledCount} enabled`, `- Last measured: ${formatAge(provider.ageMs)}${provider.stale ? ', stale' : ''}`, `- Next step: ${formatRemedy(provider.remedy)}`);
+        if (!provider.accounts.length)
+            continue;
+        lines.push('', '| Account | Enabled | Primary | Status | Last measured | Stale | Next step |', '| --- | --- | --- | --- | --- | --- | --- |', ...provider.accounts
+            .map(a => [
+            `Account ${a.ordinal}`,
+            yesNo(a.enabled),
+            yesNo(a.primary),
+            formatStatus(a.status, a.messageCode),
+            formatAge(a.ageMs),
+            yesNo(a.stale),
+            formatRemedy(a.remedy)
+        ].join(' | '))
+            .map(row => `| ${row} |`));
+    }
+    return `${redactReport(lines.join('\n'), context.homeDir)}\n`;
+}

package/build/core/environment.d.ts

@@ -0,0 +1,12 @@
+export type Environment = Readonly<Record<string, string | undefined>>;
+export interface EnvironmentRequest {
+    set?: Readonly<Record<string, string>>;
+    unset?: readonly string[];
+}
+export interface EnvironmentChanges {
+    set: Readonly<Record<string, string>>;
+    unset: readonly string[];
+}
+export declare function environmentChanges({ set, unset }?: EnvironmentRequest): EnvironmentChanges;
+export declare function applyEnvironment(changes: EnvironmentChanges, source?: Environment, platform?: NodeJS.Platform): Record<string, string>;
+export declare function cleanEnvironment(set?: Readonly<Record<string, string>>, platform?: NodeJS.Platform, source?: Environment): Record<string, string>;

package/build/core/environment.js

@@ -0,0 +1,25 @@
+// Environments for processes the app starts. Credential overrides are always removed so that
+// a tool uses the account the user picked, never one injected by the parent environment, and so
+// are Claude Code's session markers, so a tool started from it is never taken for a child session.
+import { CLAUDE_SESSION_ENV_KEYS, CREDENTIAL_ENV_KEYS } from "../shared/catalog.js";
+import { AppError } from "./errors.js";
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function environmentChanges({ set = {}, unset = [] } = {}) {
+    if ([...Object.keys(set), ...unset].some(name => !ENV_NAME.test(name)))
+        throw new AppError('invalid_argument');
+    return {
+        set,
+        unset: [...new Set([...CREDENTIAL_ENV_KEYS, ...CLAUDE_SESSION_ENV_KEYS, ...unset])].filter(name => !Object.hasOwn(set, name))
+    };
+}
+// A copy of `source` with the changes applied (names are case-insensitive on Windows).
+export function applyEnvironment(changes, source = process.env, platform = process.platform) {
+    const normalize = platform === 'win32' ? (name) => name.toLowerCase() : (name) => name;
+    const removed = new Set([...changes.unset, ...Object.keys(changes.set)].map(normalize));
+    const kept = Object.entries(source).filter((entry) => entry[1] !== undefined && !removed.has(normalize(entry[0])));
+    return { ...Object.fromEntries(kept), ...changes.set };
+}
+// `source` without credential overrides, plus `set`.
+export function cleanEnvironment(set = {}, platform = process.platform, source = process.env) {
+    return applyEnvironment(environmentChanges({ set }), source, platform);
+}

package/build/core/errors.d.ts

@@ -0,0 +1,23 @@
+import type { ErrorCode, ErrorPayload, ProviderErrorCode } from '../shared/types.ts';
+type Params = Readonly<Record<string, string>>;
+export declare class AppError extends Error {
+    readonly code: ErrorCode;
+    readonly params: Params;
+    constructor(code: ErrorCode, params?: Params, options?: ErrorOptions);
+}
+export declare const systemErrorCode: (error: unknown) => unknown;
+export declare class ProviderError extends AppError {
+    readonly code: ProviderErrorCode;
+    readonly retryAfterSeconds: number | undefined;
+    constructor(code: ProviderErrorCode, { retryAfterSeconds, cause }?: {
+        retryAfterSeconds?: number;
+        cause?: unknown;
+    });
+}
+export declare class InvalidSettingsError extends AppError {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare function providerErrorCode(error: unknown): ProviderErrorCode;
+export declare function toErrorPayload(error: unknown): ErrorPayload;
+export {};

package/build/core/errors.js

@@ -0,0 +1,48 @@
+// A failure the user can act on. `code` maps to an i18n message; the main process and the
+// CLI translate it, so no layer below them produces display text.
+export class AppError extends Error {
+    code;
+    params;
+    constructor(code, params = {}, options) {
+        super(code, options);
+        this.name = 'AppError';
+        this.code = code;
+        this.params = params;
+    }
+}
+// The `code` a system call or child process failed with (`ENOENT`, an exit status); undefined
+// for anything else thrown.
+export const systemErrorCode = (error) => (error instanceof Error && 'code' in error ? error.code : undefined);
+const RETRY_AFTER_BOUNDS_SECONDS = { min: 60, max: 900 };
+// A failed quota read. `retryAfterSeconds` is the server's back-off hint, kept within bounds.
+export class ProviderError extends AppError {
+    retryAfterSeconds;
+    constructor(code, { retryAfterSeconds, cause } = {}) {
+        super(code, {}, cause === undefined ? undefined : { cause });
+        this.name = 'ProviderError';
+        this.retryAfterSeconds =
+            retryAfterSeconds === undefined
+                ? undefined
+                : Math.max(RETRY_AFTER_BOUNDS_SECONDS.min, Math.min(RETRY_AFTER_BOUNDS_SECONDS.max, Number.isFinite(retryAfterSeconds) ? retryAfterSeconds : 0));
+    }
+}
+// Settings that do not match the schema. `reason` names the rule, for logs and tests.
+export class InvalidSettingsError extends AppError {
+    reason;
+    constructor(reason) {
+        super('invalid_settings');
+        this.name = 'InvalidSettingsError';
+        this.reason = reason;
+        this.message = `invalid_settings: ${reason}`;
+    }
+}
+// The code a failed read is reported with; anything but a ProviderError is internal.
+export function providerErrorCode(error) {
+    return error instanceof ProviderError ? error.code : 'provider_failed';
+}
+// Errors cross the IPC boundary as plain data: Electron would otherwise flatten them into
+// "Error invoking remote method …" strings and drop the code. Anything that is not an
+// AppError is an internal fault; its message is never exposed.
+export function toErrorPayload(error) {
+    return error instanceof AppError ? { code: error.code, params: error.params } : { code: 'unexpected', params: {} };
+}

package/build/core/files.d.ts

@@ -0,0 +1,20 @@
+export type JsonObject = Record<string, unknown>;
+export declare const isObject: (value: unknown) => value is JsonObject;
+export declare const asArray: (value: unknown) => readonly unknown[];
+export declare const parseJson: (text: string) => unknown;
+export declare const field: (value: unknown, key: string) => unknown;
+export declare const pathKey: (dir: string, platform?: NodeJS.Platform) => string;
+export declare const samePath: (a: string, b: string) => boolean;
+export declare const JSON_LINES_EXTENSION = ".jsonl";
+export declare function jsonLines(text: string): Generator<JsonObject>;
+export declare function readHeadSync(file: string, bytes: number): string;
+export declare function readTailSync(file: string, bytes: number): string;
+export declare function newestFiles(dir: string, extension: string): string[];
+export declare function readJsonSync(file: string): unknown;
+export declare function readJson(file: string): Promise<unknown>;
+export declare const isFile: (file: string) => Promise<boolean>;
+export declare const isDirectory: (file: string) => Promise<boolean>;
+export declare function writeFileAtomic(file: string, text: string): Promise<void>;
+export declare function writeFileAtomicSync(file: string, text: string): void;
+export declare function attempt<T>(task: () => Promise<T>): Promise<T | null>;
+export declare function attemptSync<T>(task: () => T): T | null;

package/build/core/files.js

@@ -0,0 +1,136 @@
+// Reading data that other tools write (session transcripts, model caches, settings). It is
+// read best effort: a missing, unreadable or malformed file counts as absent and never fails
+// the caller, so one damaged session cannot hide all the others.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+export const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export const asArray = (value) => (Array.isArray(value) ? value : []);
+// Text written on Windows (PowerShell 5's UTF-8, Notepad) may start with a byte order mark.
+export const parseJson = (text) => JSON.parse(text.replace(/^\uFEFF/, ''));
+// A field of a JSON object; undefined for anything else.
+export const field = (value, key) => (isObject(value) ? value[key] : undefined);
+// A folder as a key: resolved, and in one case where the file system ignores case (Windows,
+// macOS), so that two spellings of one folder compare equal.
+export const pathKey = (dir, platform = process.platform) => {
+    const resolved = path.resolve(dir);
+    return platform === 'win32' || platform === 'darwin' ? resolved.toLowerCase() : resolved;
+};
+export const samePath = (a, b) => pathKey(a) === pathKey(b);
+// The extension of JSON Lines files: the session transcripts both CLIs write.
+export const JSON_LINES_EXTENSION = '.jsonl';
+// Parsed records of a JSON Lines document; blank, malformed and non-object lines are skipped
+// (the last line of a file another process is writing may be incomplete).
+export function* jsonLines(text) {
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        const record = attemptSync(() => JSON.parse(line));
+        if (isObject(record))
+            yield record;
+    }
+}
+// The first `bytes` of a file as text ('' when unreadable); a trailing partial line is
+// dropped by jsonLines.
+export function readHeadSync(file, bytes) {
+    return (attemptSync(() => {
+        const fd = fs.openSync(file, 'r');
+        try {
+            const buffer = Buffer.alloc(bytes);
+            return buffer.toString('utf8', 0, fs.readSync(fd, buffer, 0, bytes, 0));
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }) ?? '');
+}
+// The last `bytes` of a file as text ('' when unreadable); a leading partial line is dropped
+// by jsonLines.
+export function readTailSync(file, bytes) {
+    return (attemptSync(() => {
+        const fd = fs.openSync(file, 'r');
+        try {
+            const { size } = fs.fstatSync(fd);
+            const length = Math.min(bytes, size);
+            const buffer = Buffer.alloc(length);
+            return buffer.toString('utf8', 0, fs.readSync(fd, buffer, 0, length, size - length));
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }) ?? '');
+}
+// Files in `dir` with the given extension, newest first ([] when unreadable).
+export function newestFiles(dir, extension) {
+    return (attemptSync(() => fs.readdirSync(dir)) ?? [])
+        .filter(name => name.endsWith(extension))
+        .map(name => path.join(dir, name))
+        .map(file => ({ file, mtimeMs: attemptSync(() => fs.statSync(file).mtimeMs) ?? 0 }))
+        .sort((a, b) => b.mtimeMs - a.mtimeMs)
+        .map(entry => entry.file);
+}
+export function readJsonSync(file) {
+    return attemptSync(() => JSON.parse(fs.readFileSync(file, 'utf8')));
+}
+export async function readJson(file) {
+    return attempt(async () => JSON.parse(await fsp.readFile(file, 'utf8')));
+}
+export const isFile = (file) => fsp.stat(file).then(stat => stat.isFile(), () => false);
+export const isDirectory = (file) => fsp.stat(file).then(stat => stat.isDirectory(), () => false);
+// Writes the app's own data atomically and private to the user: a crash mid-write never
+// leaves a truncated file.
+export async function writeFileAtomic(file, text) {
+    await fsp.mkdir(path.dirname(file), { recursive: true });
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+    try {
+        const handle = await fsp.open(temporary, 'wx', 0o600);
+        try {
+            await handle.writeFile(text, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fsp.rename(temporary, file);
+    }
+    finally {
+        await fsp.rm(temporary, { force: true });
+    }
+}
+// The same, for the moment the app quits, when nothing asynchronous is waited for.
+export function writeFileAtomicSync(file, text) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${crypto.randomBytes(8).toString('hex')}.tmp`);
+    try {
+        const handle = fs.openSync(temporary, 'wx', 0o600);
+        try {
+            fs.writeFileSync(handle, text, 'utf8');
+            fs.fsyncSync(handle);
+        }
+        finally {
+            fs.closeSync(handle);
+        }
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+// The task's result, or null if it throws.
+export async function attempt(task) {
+    try {
+        return await task();
+    }
+    catch {
+        return null;
+    }
+}
+export function attemptSync(task) {
+    try {
+        return task();
+    }
+    catch {
+        return null;
+    }
+}

package/build/core/glance.d.ts

@@ -0,0 +1,25 @@
+import { type ProviderId } from '../shared/catalog.ts';
+import { type FormatContext } from '../shared/format.ts';
+import type { Account, MeasuredAccount, Snapshot } from '../shared/types.ts';
+import type { Notice } from './continuity.ts';
+import { type KnownWindow } from './selection.ts';
+export declare function trayTool(snapshot: Snapshot): {
+    providerId: ProviderId;
+    percent: number | null;
+} | null;
+export declare function trayTooltip(snapshot: Snapshot, { locale, now }: FormatContext): string;
+export interface QuotaAlert {
+    kind: 'low' | 'available';
+    providerId: ProviderId;
+    account: MeasuredAccount;
+    window: KnownWindow;
+}
+export declare function createQuotaWatch(threshold?: number): (snapshot: Snapshot) => QuotaAlert[];
+export declare function describeNotice(notice: Notice, context: FormatContext, accounts: readonly Account[]): {
+    title: string;
+    body: string;
+};
+export declare function describeAlert({ kind, providerId, account, window }: QuotaAlert, context: FormatContext): {
+    title: string;
+    body: string;
+};

package/build/core/glance.js

@@ -0,0 +1,107 @@
+// What the tray tells without the window being opened: each tool's best limit in the tooltip,
+// and a notification when an account's tightest limit runs low or becomes available again.
+import path from 'node:path';
+import { APP_NAME, displayOrder, providerById } from "../shared/catalog.js";
+import { describeCode, describeWindow, formatAccountName, formatDuration, formatPercent, successorName } from "../shared/format.js";
+import { tightestWindow } from "./selection.js";
+const UNMEASURED = '—';
+const isMeasured = (account) => account.status === 'ok';
+// The most headroom any measured account of the tool has: its tightest limit.
+function bestWindow(snapshot, providerId) {
+    return (snapshot.providers.find(p => p.id === providerId)?.accounts ?? [])
+        .filter(isMeasured)
+        .flatMap(account => tightestWindow(account) ?? [])
+        .reduce((most, window) => (most && most.remainingPercent >= window.remainingPercent ? most : window), null);
+}
+// The tool the tray icon shows: the first one in the window's order that has accounts.
+export function trayTool(snapshot) {
+    const providerId = displayOrder(snapshot.settings).find(id => snapshot.providers.some(p => p.id === id && p.accounts.length));
+    return providerId ? { providerId, percent: bestWindow(snapshot, providerId)?.remainingPercent ?? null } : null;
+}
+// One line per tool with accounts: the most headroom any of its accounts has, and when that
+// account's tightest limit resets.
+export function trayTooltip(snapshot, { locale, now = Date.now() }) {
+    const lines = displayOrder(snapshot.settings).flatMap(providerId => {
+        const accounts = snapshot.providers.find(p => p.id === providerId)?.accounts ?? [];
+        if (!accounts.length)
+            return [];
+        const best = bestWindow(snapshot, providerId);
+        const name = providerById(providerId).name;
+        if (!best)
+            return [`${name} ${UNMEASURED}`];
+        const resetMs = best.resetsAt ? Date.parse(best.resetsAt) - now : NaN;
+        const reset = resetMs > 0 ? ` · ${formatDuration(resetMs, locale)}` : '';
+        return [`${name} ${formatPercent(best.remainingPercent, locale)}${reset}`];
+    });
+    return [APP_NAME, ...lines].join('\n');
+}
+// Remembers each account's last measured headroom and reports the readings that cross
+// `threshold` (by default the low line the user set). An account's first reading only sets the
+// baseline.
+export function createQuotaWatch(threshold) {
+    const lastHeadroom = new Map();
+    return snapshot => {
+        const line = threshold ?? snapshot.settings.lowQuotaPercent;
+        return snapshot.providers.flatMap(provider => provider.accounts.filter(isMeasured).flatMap((account) => {
+            const window = tightestWindow(account);
+            if (!window)
+                return [];
+            const before = lastHeadroom.get(account.id);
+            lastHeadroom.set(account.id, window.remainingPercent);
+            if (before === undefined)
+                return [];
+            const isLow = window.remainingPercent <= line;
+            if (isLow === before <= line)
+                return [];
+            return [{ kind: isLow ? 'low' : 'available', providerId: provider.id, account, window }];
+        }));
+    };
+}
+// What a failed notice says, by what failed: work moved off an account that ran out, work brought
+// back to the main account (which has quota again), or a session opened again after a restart.
+const FAILED_BODIES = {
+    move: 'noticeFailedBody',
+    return: 'noticeReturnFailedBody',
+    reopen: 'noticeReopenFailedBody'
+};
+export function describeNotice(notice, context, accounts) {
+    const { t, locale } = context;
+    const subject = notice.kind === 'suggested' ? accounts.find(a => a.id === notice.suggestion.accountId) : notice.from;
+    const providerId = notice.kind === 'suggested' ? notice.suggestion.providerId : notice.from.providerId;
+    const title = `${providerById(providerId).name}${subject ? ` · ${formatAccountName(subject, t)}` : ''}`;
+    switch (notice.kind) {
+        case 'suggested': {
+            const { suggestion } = notice;
+            if (suggestion.kind === 'return')
+                return { title, body: t('noticeReturnBody') };
+            if (suggestion.kind === 'reopen')
+                return { title, body: t('noticeReopenBody') };
+            const target = successorName(providerId, suggestion.target, accounts, t);
+            return { title, body: t('noticeLowBody', { quota: formatPercent(suggestion.remainingPercent, locale), target }) };
+        }
+        case 'continued': {
+            const target = successorName(providerId, { providerId: notice.to.providerId, accountId: notice.to.account?.id ?? null }, accounts, t);
+            return { title, body: t('noticeContinuedBody', { target, project: path.basename(notice.projectDir) }) };
+        }
+        case 'returned': {
+            const target = successorName(providerId, { providerId: notice.to.providerId, accountId: notice.to.account?.id ?? null }, accounts, t);
+            return { title, body: t('noticeReturnedBody', { target, project: path.basename(notice.projectDir) }) };
+        }
+        case 'reopened': {
+            const target = successorName(providerId, { providerId: notice.to.providerId, accountId: notice.to.account?.id ?? null }, accounts, t);
+            return { title, body: t('noticeReopenedBody', { target, project: path.basename(notice.projectDir) }) };
+        }
+        case 'stranded':
+            return { title, body: t('noticeStrandedBody') };
+        case 'failed':
+            return { title, body: t(FAILED_BODIES[notice.attempt ?? 'move'], { reason: describeCode(notice.code, t) }) };
+    }
+}
+export function describeAlert({ kind, providerId, account, window }, context) {
+    const view = describeWindow(window, context);
+    const quota = [`${view.label}: ${view.value}`, view.reset].filter(Boolean).join(' · ');
+    return {
+        title: `${providerById(providerId).name} · ${formatAccountName(account, context.t)}`,
+        body: kind === 'low' ? quota : `${context.t('quotaAvailableAgain')}\n${quota}`
+    };
+}