@usagefleet/cli 1.2.59

package/dist/hook.js

@@ -0,0 +1,103 @@
+import { mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { writeFileAtomic } from './atomic-write.js';
+import { claudeSettingsPath } from './paths.js';
+/** Outer bound on the hook, in seconds. runGuard's own fetch gives up after 5s
+ *  and fails open; this only matters if the process itself wedges. */
+const HOOK_TIMEOUT_S = 10;
+/** Recognises a guard hook we installed (at any binary path, from any version)
+ *  so install is idempotent and uninstall is precise. */
+const GUARD_COMMAND = /usagefleet.*\bguard\b/;
+/** `/path/to/usagefleet guard`, quoted for the shell Claude Code runs it in. */
+export function guardCommand(program) {
+    return program.map(p => (p.includes(' ') ? `"${p}"` : p)).join(' ');
+}
+/** Drop every guard hook we ever installed, leaving the rest of the file alone. */
+export function withoutGuardHook(settings) {
+    const groups = settings.hooks?.UserPromptSubmit;
+    if (!groups) {
+        return settings;
+    }
+    const kept = groups
+        .map(g => ({
+        ...g,
+        hooks: (g.hooks ?? []).filter(h => !GUARD_COMMAND.test(h.command ?? '')),
+    }))
+        .filter(g => g.hooks.length > 0);
+    const hooks = { ...settings.hooks };
+    if (kept.length > 0) {
+        hooks.UserPromptSubmit = kept;
+    }
+    else {
+        delete hooks.UserPromptSubmit;
+    }
+    return {
+        ...settings,
+        hooks: Object.keys(hooks).length > 0 ? hooks : undefined,
+    };
+}
+/** Strip-then-append, so re-running install refreshes a stale binary path
+ *  instead of stacking a second hook. */
+export function withGuardHook(settings, command) {
+    const base = withoutGuardHook(settings);
+    const groups = base.hooks?.UserPromptSubmit ?? [];
+    return {
+        ...base,
+        hooks: {
+            ...base.hooks,
+            UserPromptSubmit: [...groups, { hooks: [{ command, timeout: HOOK_TIMEOUT_S, type: 'command' }] }],
+        },
+    };
+}
+/** Read → transform → write ~/.claude/settings.json, skipping the write when
+ *  nothing changed. Refuses to touch a file it cannot parse: a hand-edited
+ *  settings file is worth more than this hook. */
+function editSettings(transform, onWrite) {
+    const path = claudeSettingsPath();
+    let raw = '';
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch {
+        /* no settings file yet */
+    }
+    let settings = {};
+    if (raw.trim()) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                throw new Error('settings JSON is not an object');
+            }
+            settings = parsed;
+        }
+        catch {
+            console.warn(`Could not parse ${path} — left it untouched. Fix the JSON and re-run.`);
+            return;
+        }
+    }
+    const next = transform(settings);
+    if (JSON.stringify(next) === JSON.stringify(settings)) {
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    // Atomic: this file is the user's, not ours, and an interrupted write would
+    // truncate their whole Claude Code configuration for the sake of our hook.
+    writeFileAtomic(path, `${JSON.stringify(next, null, 2)}\n`);
+    onWrite(path);
+}
+/**
+ * Register `usagefleet guard` as a Claude Code UserPromptSubmit hook, so a
+ * group with blocking enabled actually refuses prompts. Called by
+ * `usagefleet install`; set USAGEFLEET_HOOK=0 to keep settings.json
+ * untouched.
+ */
+export function installPromptHook(program) {
+    if (process.env.USAGEFLEET_HOOK === '0') {
+        return;
+    }
+    const command = guardCommand(program);
+    editSettings(s => withGuardHook(s, command), path => console.log(`Registered the over-limit prompt guard in ${path}.`));
+}
+export function uninstallPromptHook() {
+    editSettings(withoutGuardHook, path => console.log(`Removed the prompt guard from ${path}.`));
+}

package/dist/index.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+import { detectClaudeCreds } from './claude-creds.js';
+import { reportLimitsOnce, runOnce } from './collector.js';
+import { loadConfig } from './config.js';
+import { runGuard } from './guard.js';
+import { loadNotifyConfig } from './notifier.js';
+import { sendNotification } from './notify.js';
+import { detectOs } from './os.js';
+import { RELEASE_VERSION } from './release.js';
+import { serviceStatus } from './service.js';
+import { readStore, storePath, updateStore } from './store.js';
+import { ago, bar, bold, dim, green, pct, row, state as stateLine, step, yellow } from './ui.js';
+import { checkForUpdate } from './update.js';
+function flag(name) {
+    const prefix = `--${name}`;
+    const args = process.argv;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === prefix) {
+            const next = args[i + 1];
+            // don't swallow a following option as this flag's value
+            return next !== undefined && !next.startsWith('--') ? next : undefined;
+        }
+        if (a.startsWith(`${prefix}=`)) {
+            return a.slice(prefix.length + 1);
+        }
+    }
+    return undefined;
+}
+function ts() {
+    return new Date().toISOString().replace('T', ' ').slice(0, 19);
+}
+/** "5h ██░░░░░░░░   2% · weekly ████░░░░░░  13%" — the shared limits line.
+ *  Bars are plain characters, so they survive a service log as well as a TTY. */
+function limitsSummary(limits) {
+    const models = limits.modelLimits.map(m => ` · ${m.model}(${m.window}) ${bar(m.pct, 6)} ${pct(m.pct)}`).join('');
+    return `5h ${bar(limits.fiveHourPct)} ${pct(limits.fiveHourPct)} · weekly ${bar(limits.sevenDayPct)} ${pct(limits.sevenDayPct)}${models}`;
+}
+async function cmdRun() {
+    const cfg = loadConfig();
+    const r = await runOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+    console.log(`[${ts()}] scanned ${r.files} files · sent ${r.sent} · accepted ${r.accepted} · duplicates ${r.duplicates}${r.dropped > 0 ? ` · DROPPED ${r.dropped}` : ''}${r.failed ? ' · FAILED' : ''}`);
+    const limits = await reportLimitsOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+    if (limits) {
+        console.log(`[${ts()}] limits (${limits.source}): ${limitsSummary(limits)}`);
+    }
+    if (r.failed) {
+        process.exitCode = 1;
+    }
+}
+async function cmdLimits() {
+    const cfg = loadConfig();
+    const limits = await reportLimitsOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+    if (!limits) {
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`[${ts()}] reported ${limits.source}: ${limitsSummary(limits)}`);
+}
+async function cmdWatch() {
+    const cfg = loadConfig();
+    const raw = Number(flag('interval') ?? process.env.USAGEFLEET_INTERVAL ?? 15);
+    const interval = Math.max(1, Number.isFinite(raw) && raw > 0 ? raw : 15) * 1000;
+    // The limits ping hits the real Messages API (1 billable token) — don't run it
+    // every usage-scan tick. Report at most once per USAGEFLEET_LIMITS_INTERVAL
+    // seconds (default 300), decoupled from the much faster usage poll.
+    const rawLimits = Number(process.env.USAGEFLEET_LIMITS_INTERVAL ?? 300);
+    const limitsInterval = Math.max(interval / 1000, Number.isFinite(rawLimits) && rawLimits > 0 ? rawLimits : 300) * 1000;
+    let lastLimitsAt = 0;
+    // Self-update: once at startup, then every USAGEFLEET_UPDATE_INTERVAL seconds
+    // (default 6h — a release lands on a device the same day, not the next).
+    // USAGEFLEET_UPDATE=0 opts out.
+    const rawUpdate = Number(process.env.USAGEFLEET_UPDATE_INTERVAL ?? 6 * 60 * 60);
+    const updateInterval = Math.max(60, Number.isFinite(rawUpdate) && rawUpdate > 0 ? rawUpdate : 6 * 60 * 60) * 1000;
+    let lastUpdateAt = 0;
+    console.log(header());
+    console.log(dim(`[${ts()}] watching every ${interval / 1000}s → ${cfg.endpoint}`));
+    for (const dir of [cfg.projectsDir, cfg.desktopDir, ...cfg.piDirs].filter((d) => !!d)) {
+        console.log(dim(`           ${dir}`));
+    }
+    let stopping = false;
+    let timer = null;
+    let running = false;
+    const tick = async () => {
+        if (stopping) {
+            return;
+        }
+        running = true;
+        try {
+            const r = await runOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+            // Dropped records are real data loss, so they must show up even in a
+            // cycle that uploaded nothing.
+            if (r.sent > 0 || r.dropped > 0) {
+                console.log(`[${ts()}] ${r.dropped > 0 ? yellow('!') : green('↑')} sent ${r.sent} · accepted ${r.accepted} · dup ${r.duplicates}${r.dropped > 0 ? ` · ${yellow(`DROPPED ${r.dropped}`)}` : ''}`);
+            }
+            const nowMs = Date.now();
+            if (nowMs - lastUpdateAt >= updateInterval) {
+                lastUpdateAt = nowMs;
+                await checkForUpdate(m => console.log(`[${ts()}] ${m}`));
+            }
+            if (nowMs - lastLimitsAt >= limitsInterval) {
+                lastLimitsAt = nowMs;
+                const limits = await reportLimitsOnce(cfg, m => console.log(`[${ts()}] ${m}`));
+                if (limits) {
+                    console.log(`[${ts()}] limits (${limits.source}): ${limitsSummary(limits)}`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`[${ts()}] cycle error:`, error.message);
+        }
+        finally {
+            running = false;
+        }
+        if (!stopping) {
+            timer = setTimeout(tick, interval);
+        }
+    };
+    function shutdown() {
+        stopping = true;
+        if (timer) {
+            clearTimeout(timer);
+        }
+        console.log(`\n[${ts()}] stopping…`);
+        // Let an in-flight cycle finish committing offsets; hard-exit fallback.
+        const bail = setTimeout(() => process.exit(0), 5000);
+        bail.unref();
+        const wait = setInterval(() => {
+            if (!running) {
+                clearInterval(wait);
+                process.exit(0);
+            }
+        }, 100);
+        wait.unref();
+    }
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await tick();
+}
+function cmdNotifyTest() {
+    const cfg = loadNotifyConfig();
+    if (!cfg.enabled) {
+        console.log('Notifications are disabled (USAGEFLEET_NOTIFY=0).');
+        return;
+    }
+    sendNotification('usagefleet', 'Test notification — desktop alerts are working.', {
+        urgency: 'normal',
+    });
+    console.log(`[${ts()}] sent a test notification via ${detectOs()} (thresholds: ${cfg.thresholds.join(', ')}%)`);
+}
+async function cmdStatus() {
+    const cfg = loadConfig();
+    const { limits, state } = readStore(cfg.storePath);
+    const tracked = Object.keys(state.files).length;
+    const mb = (Object.values(state.files).reduce((a, f) => a + f.offset, 0) / 1_048_576).toFixed(1);
+    const svc = serviceStatus();
+    const creds = await detectClaudeCreds();
+    console.log(header());
+    console.log('');
+    console.log(svc.state === 'running'
+        ? stateLine('ok', 'service', `running${svc.pid ? dim(` · pid ${svc.pid}`) : ''}`)
+        : stateLine('bad', 'service', `${svc.state} ${dim(svc.state === 'stopped' ? '· check the log' : '· run `usagefleet install`')}`));
+    console.log(creds
+        ? stateLine('ok', 'claude', `${creds.source}${dim(creds.subscriptionType ? ` · ${creds.subscriptionType}` : '')}`)
+        : stateLine('warn', 'claude', `no login ${dim('· sign in with `claude` or set ANTHROPIC_API_KEY')}`));
+    console.log(limits
+        ? stateLine(limitHealth(limits.fiveHourPct, limits.sevenDayPct), 'limits', `5h ${bar(limits.fiveHourPct)} ${pct(limits.fiveHourPct)} · weekly ${bar(limits.sevenDayPct)} ${pct(limits.sevenDayPct)} ${dim(ago(limits.at))}`)
+        : stateLine('warn', 'limits', `no reading yet ${dim('· run `usagefleet limits`')}`));
+    console.log('');
+    console.log(row('endpoint', cfg.endpoint));
+    console.log(row('device', `${state.deviceId} · token ${cfg.token.slice(0, 8)}…`));
+    const watching = [cfg.projectsDir, cfg.desktopDir, ...cfg.piDirs].filter((d) => !!d);
+    for (const [i, dir] of watching.entries()) {
+        console.log(row(i === 0 ? 'watching' : '', dir));
+    }
+    console.log(row('tracked', `${tracked} file${tracked === 1 ? '' : 's'} · ${mb} MB read · synced ${ago(state.updatedAt)}`));
+    console.log(row('config', cfg.storePath));
+}
+/** Worst of the two windows decides the dot colour. */
+function limitHealth(fiveHour, sevenDay) {
+    const worst = Math.max(fiveHour ?? 0, sevenDay ?? 0);
+    return worst >= 95 ? 'bad' : worst >= 80 ? 'warn' : 'ok';
+}
+/** "usagefleet 1.2.55  mac" — the one-line banner every command opens with. */
+function header() {
+    const build = RELEASE_VERSION === 'dev' ? dim(' (local build · self-update off)') : '';
+    return `${bold('usagefleet')} ${RELEASE_VERSION}${build}  ${dim(detectOs())}`;
+}
+function cmdInit() {
+    const endpoint = flag('endpoint') ?? process.env.USAGEFLEET_ENDPOINT;
+    const token = flag('token') ?? process.env.USAGEFLEET_TOKEN;
+    if (!endpoint || !token) {
+        console.error('Usage: usagefleet init --endpoint <url> --token <device-token>');
+        process.exit(1);
+    }
+    const path = storePath();
+    // Merges over whatever is already there, so tail offsets and projectsDir
+    // survive a re-init and the device does not re-upload its whole history.
+    updateStore(path, store => {
+        store.endpoint = endpoint;
+        store.token = token;
+    });
+    console.log(step('configured', `${endpoint} · ${path}`));
+}
+function help() {
+    console.log(`usagefleet ${RELEASE_VERSION} — Claude usage collector
+
+Usage:
+  usagefleet run                 Scan once, upload usage + report limits
+  usagefleet watch [--interval s] Poll continuously (default 15s)
+  usagefleet limits              Report only your real 5h/weekly limit usage
+  usagefleet guard               Exit 2 if this device's group is over a blocking limit
+                                   (use as a Claude Code UserPromptSubmit hook)
+  usagefleet update              Update to the latest release now (watch does this every 6h)
+  usagefleet notify-test         Fire a test desktop notification
+  usagefleet status              Show service health, limits, resolved config
+  usagefleet version             Print the release version
+  usagefleet init --endpoint <url> --token <t>   Write ~/.config/usagefleet/config.json
+  usagefleet install             Install as a background service (launchd/systemd/Task Scheduler)
+                                   and register the guard as a Claude Code hook
+  usagefleet uninstall           Remove the background service and the hook
+
+Config (env overrides ~/.config/usagefleet/config.json, which holds settings,
+tail offsets and notification marks; USAGEFLEET_CONFIG relocates it):
+  USAGEFLEET_ENDPOINT   server base URL (e.g. https://track.example.com)
+  USAGEFLEET_TOKEN      device token from the Devices page
+  USAGEFLEET_PROJECTS   override ~/.claude/projects (Claude Code)
+  USAGEFLEET_DESKTOP    override Claude Desktop sessions dir ("off" to disable)
+  USAGEFLEET_PI         override pi sessions dirs, comma-separated ("off" to disable)
+  USAGEFLEET_INTERVAL   watch interval seconds
+  USAGEFLEET_NOTIFY     desktop notifications on/off (default on; 0 to disable)
+  USAGEFLEET_HOOK       register the guard in ~/.claude/settings.json on install (0 to skip)
+  USAGEFLEET_UPDATE     self-update while watching (0 to disable)
+  USAGEFLEET_UPDATE_INTERVAL  seconds between update checks (default 21600 = 6h)
+  USAGEFLEET_NOTIFY_THRESHOLDS  comma list of % alerts (default 80,95)`);
+}
+async function main() {
+    // Log-and-continue for the long-running watch daemon: a stray rejection must
+    // not silently kill the background service. One-shot commands still set a
+    // non-zero exit via their own error paths.
+    process.on('unhandledRejection', reason => {
+        console.error(`[${ts()}] unhandledRejection:`, reason);
+    });
+    process.on('uncaughtException', err => {
+        console.error(`[${ts()}] uncaughtException:`, err.message);
+    });
+    const cmd = process.argv[2] ?? 'help';
+    switch (cmd) {
+        case 'run': {
+            return cmdRun();
+        }
+        case 'watch': {
+            return cmdWatch();
+        }
+        case 'limits': {
+            return cmdLimits();
+        }
+        case 'guard': {
+            process.exitCode = await runGuard();
+            return;
+        }
+        case 'update': {
+            await checkForUpdate(m => console.log(`[${ts()}] ${m}`), true);
+            return;
+        }
+        case 'notify-test': {
+            return cmdNotifyTest();
+        }
+        case 'status': {
+            return cmdStatus();
+        }
+        // Bare version, so the installer can compare builds without parsing help.
+        case 'version':
+        case '--version':
+        case '-v': {
+            console.log(RELEASE_VERSION);
+            return;
+        }
+        case 'init': {
+            return cmdInit();
+        }
+        case 'install': {
+            const { install } = await import('./service.js');
+            return install();
+        }
+        case 'uninstall': {
+            const { uninstall } = await import('./service.js');
+            return uninstall();
+        }
+        default: {
+            return help();
+        }
+    }
+}
+main().catch(error => {
+    console.error(error.message);
+    process.exit(1);
+});

package/dist/notifier.js

@@ -0,0 +1,112 @@
+import { sendNotification } from './notify.js';
+import { freshWindow, readStore, storePath, updateStore } from './store.js';
+const DEFAULT_THRESHOLDS = [80, 95];
+/** Resolve notify config from env. Enabled by default; disable with
+ *  USAGEFLEET_NOTIFY=0 (also: false/off/no). Thresholds from
+ *  USAGEFLEET_NOTIFY_THRESHOLDS as a comma list (e.g. "50,80,95"). */
+export function loadNotifyConfig(env = process.env) {
+    const flag = env.USAGEFLEET_NOTIFY;
+    const enabled = flag == null || !/^(0|false|off|no)$/i.test(flag.trim());
+    let thresholds = DEFAULT_THRESHOLDS;
+    const raw = env.USAGEFLEET_NOTIFY_THRESHOLDS;
+    if (raw && raw.trim()) {
+        const parsed = raw
+            .split(',')
+            .map(s => Math.round(Number(s.trim())))
+            .filter(n => Number.isFinite(n) && n > 0 && n <= 100);
+        if (parsed.length > 0) {
+            thresholds = [...new Set(parsed)].toSorted((a, b) => a - b);
+        }
+    }
+    return { enabled, thresholds };
+}
+/** Per-window high-water mark so each threshold notifies at most once per
+ *  window. `resetsAt` ties the mark to a specific window — when it changes the
+ *  window has rolled over and the mark clears. */
+export function emptyNotifyState() {
+    return { fiveHour: freshWindow(), sevenDay: freshWindow() };
+}
+/**
+ * Decide whether a window crosses a not-yet-notified threshold. Pure — no IO.
+ * Returns the threshold to fire (or null) and the next persisted state.
+ *
+ * A window rollover (resetsAt change) resets the high-water mark first, so the
+ * first crossing in a new window always re-notifies. If utilization later drops
+ * below the mark within the SAME window (e.g. a server correction), the mark is
+ * lowered so a subsequent re-cross notifies again.
+ */
+export function evaluateWindow(prev, pct, resetsAt, thresholds) {
+    const rolledOver = !prev || prev.resetsAt !== resetsAt;
+    const lastBucket = rolledOver ? 0 : prev.lastBucket;
+    if (pct == null) {
+        // No reading this cycle — keep the mark, just track the (possibly new) window.
+        return { fire: null, next: { lastBucket, resetsAt } };
+    }
+    // Highest threshold the current pct has reached (thresholds are ascending).
+    let top = 0;
+    for (const t of thresholds) {
+        if (pct >= t) {
+            top = t;
+        }
+    }
+    if (top > lastBucket) {
+        return { fire: top, next: { lastBucket: top, resetsAt } };
+    }
+    if (top < lastBucket) {
+        return { fire: null, next: { lastBucket: top, resetsAt } };
+    }
+    return { fire: null, next: { lastBucket, resetsAt } };
+}
+/** Relative "resets in 12m" / "resets in 2h" suffix, or "" if unknown/past. */
+function resetSuffix(resetsAt) {
+    if (!resetsAt) {
+        return '';
+    }
+    const ms = new Date(resetsAt).getTime() - Date.now();
+    if (!Number.isFinite(ms) || ms <= 0) {
+        return '';
+    }
+    const min = Math.round(ms / 60_000);
+    if (min < 60) {
+        return ` · resets in ${min}m`;
+    }
+    const h = Math.round(min / 60);
+    if (h < 48) {
+        return ` · resets in ${h}h`;
+    }
+    return ` · resets in ${Math.round(h / 24)}d`;
+}
+function urgencyFor(bucket) {
+    return bucket >= 95 ? 'critical' : 'normal';
+}
+/**
+ * Notify on freshly-crossed 5h/weekly thresholds, deduped across runs via the
+ * store's `notify` section. Best-effort and self-contained: it owns its state
+ * IO and never throws out to the caller.
+ */
+export function maybeNotify(report, cfg = loadNotifyConfig(), log = () => {
+    /* empty */
+}, path = storePath()) {
+    if (!cfg.enabled || cfg.thresholds.length === 0) {
+        return;
+    }
+    try {
+        const state = readStore(path).notify;
+        const five = evaluateWindow(state.fiveHour, report.fiveHourPct, report.fiveHourResetsAt, cfg.thresholds);
+        const seven = evaluateWindow(state.sevenDay, report.sevenDayPct, report.sevenDayResetsAt, cfg.thresholds);
+        if (five.fire != null) {
+            sendNotification('Claude usage · 5-hour limit', `${report.fiveHourPct}% of your 5-hour limit used${resetSuffix(report.fiveHourResetsAt)}.`, { urgency: urgencyFor(five.fire) });
+            log(`notified: 5h at ${report.fiveHourPct}% (crossed ${five.fire}%)`);
+        }
+        if (seven.fire != null) {
+            sendNotification('Claude usage · weekly limit', `${report.sevenDayPct}% of your weekly limit used${resetSuffix(report.sevenDayResetsAt)}.`, { urgency: urgencyFor(seven.fire) });
+            log(`notified: weekly at ${report.sevenDayPct}% (crossed ${seven.fire}%)`);
+        }
+        updateStore(path, store => {
+            store.notify = { fiveHour: five.next, sevenDay: seven.next };
+        });
+    }
+    catch (error) {
+        log(`notify skipped: ${error.message}`);
+    }
+}

package/dist/notify.js

@@ -0,0 +1,88 @@
+import { execFile } from 'node:child_process';
+/** Collapse every whitespace run (including the raw newlines AppleScript string
+ *  literals forbid) to a single space, leaving hyphens and other punctuation
+ *  intact. */
+function oneLine(s) {
+    return s.replaceAll(/\s+/g, ' ').trim();
+}
+/** Escape a string for embedding inside an AppleScript double-quoted literal. */
+function osaEscape(s) {
+    return oneLine(s).replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+}
+/** Fire-and-forget child process; swallow spawn/runtime errors so a missing
+ *  binary or denied display never disturbs the collector. */
+function spawnQuiet(cmd, args, onError) {
+    try {
+        const child = execFile(cmd, args, { timeout: 5000 }, err => {
+            if (err && onError) {
+                onError(err);
+            }
+        });
+        // Don't keep the event loop (or a one-shot `run`) alive waiting on the UI.
+        child.unref?.();
+    }
+    catch (error) {
+        onError?.(error);
+    }
+}
+function notifyMac(title, message) {
+    // execFile (no shell) — the only interpolation surface is the AppleScript
+    // string, which osaEscape neutralizes.
+    const script = `display notification "${osaEscape(message)}" with title "${osaEscape(title)}"`;
+    spawnQuiet('osascript', ['-e', script]);
+}
+function notifyLinux(title, message, urgency) {
+    // notify-send is the freedesktop standard; KDE Plasma's notification daemon
+    // implements it. If it's absent (ENOENT) or fails, fall back to kdialog's
+    // native passive popup (ships with KDE).
+    spawnQuiet('notify-send', 
+    // `--` ends option parsing so a title/message can never be read as a flag.
+    ['-a', 'usagefleet', '-u', urgency, '--', oneLine(title), oneLine(message)], () => {
+        spawnQuiet('kdialog', ['--title', oneLine(title), '--passivepopup', oneLine(message), '10']);
+    });
+}
+/** Escape a string for a PowerShell single-quoted literal (no interpolation
+ *  happens inside one, so doubling `'` is the whole job). */
+function psEscape(s) {
+    return oneLine(s).replaceAll("'", "''");
+}
+function notifyWindows(title, message) {
+    // WinRT toast through Windows PowerShell 5.1 (always present on Win10/11;
+    // pwsh 7 can't load WinRT types). Text goes in via the DOM, so there is no
+    // XML-injection surface. Borrowing PowerShell's AppUserModelID avoids having
+    // to register one of our own — the toast shows up under "Windows PowerShell".
+    const script = [
+        '[Windows.UI.Notifications.ToastNotificationManager,Windows.UI.Notifications,ContentType=WindowsRuntime]|Out-Null',
+        '$t=[Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)',
+        "$n=$t.GetElementsByTagName('text')",
+        `$n.Item(0).AppendChild($t.CreateTextNode('${psEscape(title)}'))|Out-Null`,
+        `$n.Item(1).AppendChild($t.CreateTextNode('${psEscape(message)}'))|Out-Null`,
+        "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Microsoft.WindowsPowerShell').Show([Windows.UI.Notifications.ToastNotification]::new($t))",
+    ].join(';');
+    spawnQuiet('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script]);
+}
+/**
+ * Show a desktop notification. Best-effort and non-blocking: it never throws and
+ * never blocks the caller. Supported platforms:
+ *   - macOS: `osascript` -> Notification Center.
+ *   - Linux: `notify-send` (KDE Plasma + other freedesktop daemons), falling
+ *     back to `kdialog --passivepopup` on KDE.
+ *   - Windows: WinRT toast via `powershell.exe` -> Action Center.
+ * Other platforms are a no-op.
+ */
+export function sendNotification(title, message, opts = {}) {
+    try {
+        if (process.platform === 'darwin') {
+            notifyMac(title, message);
+        }
+        else if (process.platform === 'linux') {
+            notifyLinux(title, message, opts.urgency ?? 'normal');
+        }
+        else if (process.platform === 'win32') {
+            notifyWindows(title, message);
+        }
+    }
+    catch {
+        /* notifications are non-essential — never let one break a cycle */
+    }
+}

package/dist/os.js

@@ -0,0 +1,16 @@
+export function detectOs() {
+    switch (process.platform) {
+        case 'darwin': {
+            return 'mac';
+        }
+        case 'win32': {
+            return 'windows';
+        }
+        case 'linux': {
+            return 'linux';
+        }
+        default: {
+            return process.platform;
+        }
+    }
+}