@event4u/agent-switch 1.0.0

package/dist/daemon.js

@@ -0,0 +1,393 @@
+/**
+ * Background usage daemon — poller, cache, and (opt-in) auto-switcher.
+ *
+ * It polls Claude profiles for their OWN usage, appends history, detects
+ * active-profile threshold crossings, and writes `daemon-state.json` so
+ * `status`/the GUI can read a fresh snapshot without hitting the API. When
+ * `autoSwitch.enabled` (default OFF) it also watches every profile and moves the
+ * active pointer to the account with the most headroom once the active one hits
+ * the configured threshold — pooling accounts to route around limits, which the
+ * operator opts into deliberately (see `AutoSwitchConfig`). With auto-switch off
+ * it stays a pure poller/cache that never mutates the active profile.
+ *
+ * The pure helpers (single-instance, poll-target selection, backoff, state
+ * freshness, switch decision in `usage.ts`) are exported for unit testing;
+ * `runDaemon` is the loop.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ROOT, activeFor, configDir, labelFor, listProfiles, readAutoSwitch, setActive, readSwitchStrategy } from "./profiles.js";
+import { profileDir } from "./profiles.js";
+import { accessTokenOf, fetchUsage, liveSessionPids, readProfileCredential } from "./api.js";
+import { parseUsage, detectCrossings, pickSwitchTarget, maxUtilization } from "./usage.js";
+import { readCodexUsage } from "./codex-usage.js";
+import { redeemResetCredit } from "./codex-reset.js";
+import { appendSample } from "./history.js";
+import { appendNotification, markOsNotified } from "./notifications.js";
+import { readOsNotifications } from "./profiles.js";
+import { osNotify } from "./os-notify.js";
+import { listSessions, listCodexSessions, markLive } from "./sessions.js";
+import { readContext } from "./telemetry.js";
+import { readTelemetryConfig, detectContextCrossings, coalesce, } from "./notify.js";
+import { readEvents, eventFile } from "./hooks.js";
+import { execFileSync } from "node:child_process";
+/** Append an event to the shared log and, when the operator opted into
+ *  daemon-side OS notifications, fire a desktop notification too — marking the
+ *  record so the GUI does not show it a second time. Deduped events (append
+ *  returns null) never OS-notify. */
+function notify(event) {
+    const created = appendNotification(event);
+    if (created && readOsNotifications() && osNotify(event.title, event.message)) {
+        markOsNotified(created.id);
+    }
+}
+// Providers whose active profile the daemon may auto-switch (they expose a
+// usage readout to base a headroom decision on). Antigravity has none.
+const AUTO_PROVIDERS = ["claude", "codex"];
+export const PIDFILE = path.join(ROOT, "daemon.pid");
+export const STATE_FILE = path.join(ROOT, "daemon-state.json");
+export const MIN_INTERVAL_MS = 60_000; // never poll faster than once a minute
+export const MAX_BACKOFF_MS = 30 * 60_000; // cap backoff at 30 min
+// ---------- state file (the cache) ----------
+export function readDaemonState(file = STATE_FILE) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeDaemonState(state, file = STATE_FILE) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+}
+/** True when the state's lastPoll is within maxAgeMs of `now` — the CLI/GUI use
+ *  this to decide whether to trust the cache instead of hitting the API. */
+export function isFresh(state, maxAgeMs, now = Date.now()) {
+    if (!state?.lastPoll)
+        return false;
+    const t = Date.parse(state.lastPoll);
+    return !isNaN(t) && now - t <= maxAgeMs;
+}
+// ---------- single instance (pidfile) ----------
+export function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err?.code === "EPERM";
+    }
+}
+export function readPid(file = PIDFILE) {
+    try {
+        const n = Number(fs.readFileSync(file, "utf8").trim());
+        return Number.isInteger(n) && n > 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Acquire the single-instance lock. Returns true and writes the pidfile when no
+ * live daemon holds it (taking over a stale pidfile); false when another live
+ * daemon is already running.
+ */
+export function acquireSingleInstance(myPid, file = PIDFILE) {
+    const existing = readPid(file);
+    if (existing && existing !== myPid && processAlive(existing))
+        return false;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, String(myPid) + "\n", { mode: 0o600 });
+    return true;
+}
+export function releaseSingleInstance(myPid, file = PIDFILE) {
+    if (readPid(file) === myPid) {
+        try {
+            fs.rmSync(file, { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+// ---------- poll discipline ----------
+/**
+ * Which Claude profiles to poll this cycle. Normally the active one plus any
+ * with a live session — never a busy-poll of idle accounts. With `watchAll`
+ * (auto-switch enabled) every profile is polled, since the switch decision
+ * needs each candidate's headroom. `liveCheck` is injected for testability.
+ */
+export function selectPollTargets(claudeNames, active, liveCheck, watchAll = false) {
+    if (watchAll)
+        return [...claudeNames];
+    const targets = new Set();
+    if (active && claudeNames.includes(active))
+        targets.add(active);
+    for (const n of claudeNames)
+        if (liveCheck(n))
+            targets.add(n);
+    return [...targets];
+}
+/** Exponential backoff on consecutive failures, floored at the base interval
+ *  and capped at MAX_BACKOFF_MS. */
+export function nextIntervalMs(baseMs, consecutiveFailures, capMs = MAX_BACKOFF_MS) {
+    const base = Math.max(baseMs, MIN_INTERVAL_MS);
+    if (consecutiveFailures <= 0)
+        return base;
+    return Math.min(base * 2 ** consecutiveFailures, capMs);
+}
+// ---------- context monitoring (own-session; Phase 3) ----------
+let _claudeVer;
+function claudeVer() {
+    if (_claudeVer !== undefined)
+        return _claudeVer;
+    try {
+        _claudeVer = execFileSync("claude", ["--version"], { encoding: "utf8" }).trim() || null;
+    }
+    catch {
+        _claudeVer = null;
+    }
+    return _claudeVer;
+}
+/** Session ids for `provider/name` that saw a real compaction (or a fresh
+ *  clear) since `sinceISO`, from the hook event ring — the ground-truth re-arm
+ *  signal (Phase 2.5). Empty when hooks are not installed. */
+function compactedSince(provider, name, sinceISO) {
+    const out = new Set();
+    const since = sinceISO ? Date.parse(sinceISO) : 0;
+    for (const e of readEvents(eventFile(ROOT, provider, name))) {
+        if (!e.sessionId)
+            continue;
+        const isCompact = e.event === "PreCompact" || e.event === "PostCompact" || (e.event === "SessionStart" && (e.source === "compact" || e.source === "clear"));
+        if (isCompact && (!since || Date.parse(e.at) >= since))
+            out.add(e.sessionId);
+    }
+    return out;
+}
+/**
+ * Tail the active profile's LIVE sessions, snapshot their own context into the
+ * daemon state, detect per-session threshold crossings (edge-triggered, re-armed
+ * on real compaction events), and record ONE coalesced event in the shared
+ * notification log per cycle when alerts are enabled. Local file reads only —
+ * no API calls. Own-session only: nothing here compares profiles. Best-effort;
+ * never throws.
+ */
+export function monitorContext(provider, name, state, log) {
+    try {
+        if (provider !== "claude" && provider !== "codex")
+            return;
+        const cfg = configDir(provider, name);
+        const rows = provider === "codex" ? listCodexSessions(cfg, 30) : listSessions(cfg, 30);
+        if (provider === "claude")
+            markLive(cfg, rows);
+        const live = rows.filter((r) => r.live && r.file);
+        const key = `${provider}/${name}`;
+        const now = new Date().toISOString();
+        const samples = [];
+        const snapshots = [];
+        for (const r of live) {
+            const c = readContext(provider, r.file, { claudeVersion: claudeVer() });
+            if (!c)
+                continue;
+            const where = (r.cwd ?? r.projectDir).split("/").filter(Boolean).slice(-1)[0] || r.projectDir;
+            samples.push({ sessionId: r.sessionId, pct: c.pct, where });
+            snapshots.push({ sessionId: r.sessionId, pct: c.pct, contextTokens: c.contextTokens, windowTokens: c.windowTokens, where, confidence: c.confidence, at: now });
+        }
+        state.sessionContext = state.sessionContext ?? {};
+        state.sessionContext[key] = snapshots;
+        const cfgT = readTelemetryConfig(ROOT);
+        const prev = (state.contextThresholds ?? {})[key] ?? {};
+        const compacted = compactedSince(provider, name, state.lastPoll);
+        const { crossings, state: next } = detectContextCrossings(samples, prev, cfgT.contextThresholds, compacted);
+        state.contextThresholds = state.contextThresholds ?? {};
+        state.contextThresholds[key] = next;
+        for (const c of crossings)
+            log(`context: ${provider}/${name} ${c.where} crossed ${c.threshold}% (now ${c.pct}%)`);
+        // Feed the ONE coalesced crossing into the shared notification log (the app's
+        // single notifier: the GUI bell/flyout reads it and fires a best-effort
+        // desktop notification). Off by default via the alerts config.
+        const note = coalesce(crossings);
+        if (note && cfgT.notify) {
+            appendNotification({ kind: "warning", title: note.title, message: note.body });
+        }
+    }
+    catch (err) {
+        log(`context monitor error: ${String(err?.message ?? err)}`);
+    }
+}
+/** One poll cycle: refresh the state cache for the selected profiles. Returns
+ *  the number of failures this cycle (for backoff). */
+/** One profile's own usage snapshot: Claude via its OAuth endpoint, Codex via
+ *  the live `wham/usage` read. null when unreadable (counts as a poll failure). */
+async function snapshotFor(provider, name) {
+    if (provider === "codex")
+        return readCodexUsage(configDir("codex", name));
+    const creds = readProfileCredential(configDir("claude", name));
+    const token = creds ? accessTokenOf(creds) : null;
+    if (!token)
+        return null;
+    const raw = await fetchUsage(token);
+    return raw ? parseUsage(raw) : null;
+}
+async function pollProvider(provider, strategy, state, thresholds, redeemed, log) {
+    const names = listProfiles(provider);
+    const active = activeFor(provider);
+    const autoSwitch = readAutoSwitch(provider);
+    const isLive = (n) => (provider === "claude" ? liveSessionPids(configDir("claude", n)).length > 0 : false);
+    const targets = selectPollTargets(names, active, isLive, autoSwitch.enabled);
+    let failures = 0;
+    const polled = [];
+    state.notifiedFetchFail = state.notifiedFetchFail ?? {};
+    for (const name of targets) {
+        const key = `${provider}/${name}`;
+        const snapshot = await snapshotFor(provider, name);
+        if (!snapshot) {
+            failures++;
+            // Fail-safe: the last-known snapshot in state.profiles[key] is left intact
+            // (never overwritten with null), and we warn ONCE per outage rather than
+            // every cycle — the loop keeps serving the last good numbers meanwhile.
+            if (!state.notifiedFetchFail[key]) {
+                state.notifiedFetchFail[key] = true;
+                notify({
+                    kind: "warning",
+                    title: "Usage fetch failed",
+                    message: `Could not fetch usage limits for ${provider}/${name}. Keeping the last known values.`,
+                });
+            }
+            continue;
+        }
+        if (state.notifiedFetchFail[key]) {
+            delete state.notifiedFetchFail[key];
+            log(`recovered: ${provider}/${name} usage fetch succeeded again`);
+        }
+        state.profiles[key] = snapshot;
+        polled.push({ name, snapshot });
+        appendSample(path.join(profileDir(provider, name), "usage-history.json"), snapshot);
+        if (name === active) {
+            const prev = thresholds.get(`${provider}/${name}`) ?? {};
+            const { crossings, state: next } = detectCrossings(snapshot, prev);
+            thresholds.set(`${provider}/${name}`, next);
+            for (const c of crossings) {
+                log(`threshold: ${provider}/${name} ${c.window} crossed ${c.threshold}% (now ${c.utilization}%)`);
+                notify({
+                    kind: "info",
+                    title: "Usage threshold crossed",
+                    message: `${provider}/${name} ${c.window} passed ${c.threshold}% (now ${c.utilization}%).`,
+                });
+            }
+        }
+    }
+    // Context monitoring is local file I/O only — it must run for the active
+    // profile even when the usage API poll failed (expired token, offline).
+    if (active)
+        monitorContext(provider, active, state, log);
+    if (!autoSwitch.enabled || !active)
+        return failures;
+    const activeSnap = polled.find((p) => p.name === active)?.snapshot;
+    const activeMax = activeSnap ? maxUtilization(activeSnap) : null;
+    if (activeMax === null || activeMax < autoSwitch.threshold)
+        return failures; // still has headroom
+    // reset-first (Codex only — banked resets are a Codex feature): redeem a reset
+    // instead of switching, but AT MOST ONCE per reset cycle. We record the
+    // window's resets_at BEFORE calling, so a buggy reset that doesn't actually
+    // clear usage can never loop and burn the whole balance — it falls through to
+    // a profile switch on the same poll's next-cycle.
+    if (strategy === "reset-first" && provider === "codex" && activeSnap) {
+        const stuck = activeSnap.windows.find((w) => typeof w.utilization === "number" && w.utilization >= autoSwitch.threshold);
+        const cycle = stuck?.resetsAt ?? "";
+        const guardKey = `codex/${active}`;
+        if ((activeSnap.resetCredits ?? 0) > 0 && redeemed.get(guardKey) !== cycle) {
+            redeemed.set(guardKey, cycle);
+            const r = await redeemResetCredit(configDir("codex", active));
+            if (r.ok) {
+                log(`auto-switch: codex/${active} over ≥${autoSwitch.threshold}% → redeemed a reset (windows_reset=${r.windowsReset ?? "?"}); staying on ${active}`);
+                notify({
+                    kind: "success",
+                    title: "Codex reset redeemed",
+                    message: `codex/${active} hit ≥${autoSwitch.threshold}% — redeemed a banked reset and stayed on ${active}.`,
+                });
+                return failures;
+            }
+            log(`auto-switch: codex/${active} reset redeem failed (${r.reason ?? "?"}) → falling back to a profile switch`);
+        }
+    }
+    // Tag filter: only accounts carrying the configured label are eligible switch
+    // targets ("all" = no filter). Lets the operator pool e.g. only Work accounts.
+    const eligible = (name) => autoSwitch.tag === "all" || labelFor(provider, name) === autoSwitch.tag;
+    const target = pickSwitchTarget(active, polled, autoSwitch.threshold, eligible);
+    if (target && target !== active) {
+        setActive(provider, target);
+        log(`auto-switch: ${provider}/${active} out of headroom (≥${autoSwitch.threshold}%) → switched active to ${provider}/${target}`);
+        notify({
+            kind: "success",
+            title: "Auto-switched account",
+            message: `${provider}/${active} hit ≥${autoSwitch.threshold}% — switched active to ${provider}/${target}.`,
+        });
+    }
+    return failures;
+}
+async function pollOnce(state, thresholds, redeemed, log) {
+    const strategy = readSwitchStrategy();
+    let failures = 0;
+    for (const provider of AUTO_PROVIDERS) {
+        failures += await pollProvider(provider, strategy, state, thresholds, redeemed, log);
+    }
+    state.lastPoll = new Date().toISOString();
+    state.lastError = failures > 0 ? `${failures} profile(s) failed to poll` : null;
+    return failures;
+}
+/** Run the daemon loop. Single-instance; SIGTERM-clean. */
+export async function runDaemon(opts = {}) {
+    const log = opts.log ?? ((l) => console.log(`[daemon] ${new Date().toISOString()} ${l}`));
+    const baseInterval = Math.max(opts.intervalMs ?? MIN_INTERVAL_MS, MIN_INTERVAL_MS);
+    if (!acquireSingleInstance(process.pid)) {
+        log("another daemon is already running — exiting.");
+        return;
+    }
+    let running = true;
+    const stop = () => {
+        running = false;
+        releaseSingleInstance(process.pid);
+        log("stopped.");
+        process.exit(0);
+    };
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+    const state = readDaemonState() ?? {
+        lastPoll: null,
+        pollIntervalMs: baseInterval,
+        profiles: {},
+        lastError: null,
+    };
+    // Load persisted usage-window fired state so crossings do NOT re-fire after a
+    // daemon restart within the same window cycle (the pre-existing in-memory gap).
+    const thresholds = new Map(Object.entries(state.usageThresholds ?? {}));
+    // Anti-loop guard for reset-first: `<provider>/<name>` → the window resets_at
+    // we last redeemed for, so we never redeem the same stuck cycle twice.
+    const redeemed = new Map();
+    let consecutiveFailures = 0;
+    let cycles = 0;
+    log(`started (pid ${process.pid}, base interval ${baseInterval}ms).`);
+    while (running) {
+        try {
+            const failures = await pollOnce(state, thresholds, redeemed, log);
+            consecutiveFailures = failures > 0 ? consecutiveFailures + 1 : 0;
+        }
+        catch (err) {
+            consecutiveFailures++;
+            state.lastError = String(err?.message ?? err);
+            log(`poll error: ${state.lastError}`);
+        }
+        const wait = nextIntervalMs(baseInterval, consecutiveFailures);
+        state.pollIntervalMs = wait;
+        state.usageThresholds = Object.fromEntries(thresholds); // persist for restart
+        writeDaemonState(state);
+        if (opts.maxCycles !== undefined && ++cycles >= opts.maxCycles)
+            break;
+        // Jitter ±10% so many machines don't poll in lockstep.
+        const jitter = wait * 0.1 * (Math.random() * 2 - 1);
+        await new Promise((r) => setTimeout(r, wait + jitter));
+    }
+    releaseSingleInstance(process.pid);
+}

package/dist/doctor.js

@@ -0,0 +1,119 @@
+/**
+ * `agent-switch doctor` — a per-OS, per-provider self-check.
+ *
+ * Reports health with actionable fixes and returns an exit code: 0 when there
+ * is no hard error, 1 when a provider that has profiles is missing its binary.
+ * Read-only — it never mutates a profile.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import { ROOT, activeFor, configDir, listProfiles, profileExists } from "./profiles.js";
+import { allProviders } from "./providers.js";
+import { credentialStore } from "./credentials.js";
+import { sharedLinkHealth } from "./share.js";
+import { checkAuth } from "./api.js";
+const OK = "✅";
+const WARN = "⚠️";
+const ERR = "❌";
+function binaryOnPath(binary) {
+    // Timeout so a hung binary can't hang the doctor.
+    const probe = spawnSync(binary, ["--version"], { stdio: "ignore", timeout: 5000 });
+    if (probe.error?.code === "ENOENT")
+        return "no";
+    if (probe.error)
+        return "error";
+    return "yes";
+}
+function credentialReadable(p, name) {
+    const cfg = p.configDirFor(configDir(p.id, name));
+    if (p.id === "claude")
+        return credentialStore().read(cfg) !== null;
+    try {
+        fs.accessSync(p.credentialPath(cfg));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runDoctor() {
+    let hardError = false;
+    const line = (mark, msg) => console.log(`${mark}  ${msg}`);
+    console.log(`agent-switch doctor — platform ${process.platform}, node ${process.version}`);
+    console.log(process.platform === "darwin"
+        ? "  claude credential store: macOS Keychain (hashed per config dir), file fallback"
+        : "  claude credential store: plaintext .credentials.json per profile");
+    console.log("");
+    for (const p of allProviders()) {
+        const names = listProfiles(p.id);
+        const onPath = binaryOnPath(p.binary);
+        if (onPath === "no") {
+            if (names.length > 0) {
+                line(ERR, `\`${p.binary}\` not on PATH but ${names.length} ${p.id} profile(s) exist — install ${p.id}.`);
+                hardError = true;
+            }
+            else {
+                line(WARN, `\`${p.binary}\` not on PATH (no ${p.id} profiles yet — fine unless you use ${p.id}).`);
+            }
+            continue;
+        }
+        if (onPath === "error")
+            line(WARN, `could not probe \`${p.binary} --version\`.`);
+        else
+            line(OK, `\`${p.binary}\` is on PATH.`);
+        if (names.length === 0) {
+            line(WARN, `  no ${p.id} profiles yet — \`agent-switch add <name>${p.id === "claude" ? "" : ` --provider ${p.id}`}\`.`);
+            continue;
+        }
+        line(OK, `  ${names.length} ${p.id} profile(s): ${names.join(", ")}.`);
+        const active = activeFor(p.id);
+        if (active && !profileExists(p.id, active)) {
+            line(WARN, `  active ${p.id} profile "${active}" no longer exists.`);
+        }
+        // Login validity (Claude only): probe readable credentials in parallel, so
+        // an expired login is caught here instead of failing silently at next use.
+        // Read-only; offline / transient degrades to a neutral note, never a WARN.
+        const authByName = new Map();
+        if (p.id === "claude") {
+            const readable = names.filter((n) => credentialReadable(p, n));
+            const states = await Promise.all(readable.map((n) => checkAuth(p.configDirFor(configDir(p.id, n)))));
+            readable.forEach((n, i) => authByName.set(n, states[i]));
+        }
+        for (const n of names) {
+            if (!credentialReadable(p, n)) {
+                line(WARN, `  ${p.id}/${n}: credential not readable — \`agent-switch run ${n}${p.id === "claude" ? "" : ` --provider ${p.id}`}\` and log in.`);
+                continue;
+            }
+            const auth = authByName.get(n);
+            if (auth === "expired") {
+                line(WARN, `  ${p.id}/${n}: login expired — \`agent-switch run ${n}\` and /login again.`);
+            }
+            else if (auth === "ok") {
+                line(OK, `  ${p.id}/${n}: credential readable, login valid.`);
+            }
+            else {
+                // Non-Claude (no probe) or Claude "unknown"/offline — don't over-claim.
+                line(OK, `  ${p.id}/${n}: credential readable${p.id === "claude" ? " (login not verified — offline?)" : ""}.`);
+            }
+        }
+    }
+    // Share-link health (Claude-config sharing).
+    for (const n of listProfiles("claude")) {
+        const health = sharedLinkHealth(configDir("claude", n));
+        if (health.length === 0)
+            continue;
+        const forked = health.filter((h) => h.state === "forked").map((h) => h.name);
+        const missing = health.filter((h) => h.state === "missing").map((h) => h.name);
+        if (forked.length === 0 && missing.length === 0) {
+            line(OK, `claude/${n}: ${health.length} shared link(s) intact.`);
+        }
+        else {
+            const parts = [forked.length ? `forked: ${forked.join(", ")}` : "", missing.length ? `missing: ${missing.join(", ")}` : ""].filter(Boolean);
+            line(WARN, `claude/${n}: ${parts.join("; ")} — run \`agent-switch share sync\`.`);
+        }
+    }
+    console.log(`\n  profile root: ${ROOT}`);
+    console.log("");
+    line(hardError ? ERR : OK, hardError ? "doctor found a blocking problem (see above)." : "no blocking problems.");
+    return hardError ? 1 : 0;
+}

package/dist/gui-launch.js

@@ -0,0 +1,91 @@
+/**
+ * `agent-switch gui` — launch the desktop tray GUI.
+ *
+ * The GUI is a native (Tauri) binary, so it can't run "as JS". Instead the
+ * prebuilt binary ships as a per-platform optional-dependency npm package
+ * (`@event4u/agent-switch-<platform>`, the esbuild pattern), installed
+ * automatically alongside the CLI. Because it arrives via npm — not a
+ * browser-downloaded DMG/exe — it carries no quarantine flag, so it launches
+ * without the Gatekeeper / SmartScreen "unverified developer" block.
+ *
+ * The platform→package / artifact / launch-argv resolution is pure and tested;
+ * only {@link launchGui} touches the filesystem and spawns a process.
+ */
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const require = createRequire(import.meta.url);
+/** The optional-dependency package carrying the GUI binary for a platform+arch,
+ *  or null when the platform is unsupported. macOS ships a universal binary, so
+ *  one darwin package serves both arches. Pure. */
+export function guiPackageFor(platform = process.platform, arch = process.arch) {
+    if (platform === "darwin")
+        return "@event4u/agent-switch-darwin";
+    if (platform === "win32" && arch === "x64")
+        return "@event4u/agent-switch-win32-x64";
+    if (platform === "linux" && arch === "x64")
+        return "@event4u/agent-switch-linux-x64";
+    return null;
+}
+/** The artifact file name inside a platform package. macOS ships the `.app`
+ *  bundle (launched via `open`), Windows the `.exe`, Linux the raw binary. Pure. */
+export function guiArtifactName(platform = process.platform) {
+    if (platform === "darwin")
+        return "agent-switch.app";
+    if (platform === "win32")
+        return "agent-switch.exe";
+    if (platform === "linux")
+        return "agent-switch";
+    return null;
+}
+/** Program + args to launch the artifact at `artifactPath`. macOS uses `open`
+ *  (the artifact is an .app bundle); elsewhere the binary is executed directly.
+ *  Pure — the launch convention split out for testing. */
+export function guiLaunchArgv(platform, artifactPath) {
+    if (platform === "darwin")
+        return { program: "open", args: ["-n", artifactPath] };
+    return { program: artifactPath, args: [] };
+}
+/** Absolute path to the GUI artifact for the host, or null when the platform
+ *  package isn't installed / the artifact is missing. */
+export function resolveGuiArtifact(platform = process.platform, arch = process.arch) {
+    const pkg = guiPackageFor(platform, arch);
+    const artifact = guiArtifactName(platform);
+    if (!pkg || !artifact)
+        return null;
+    let pkgDir;
+    try {
+        pkgDir = path.dirname(require.resolve(`${pkg}/package.json`));
+    }
+    catch {
+        return null; // optional dependency not installed for this platform
+    }
+    const p = path.join(pkgDir, "bin", artifact);
+    return fs.existsSync(p) ? p : null;
+}
+/** Launch the desktop GUI, detached so the CLI returns immediately. Throws a
+ *  helpful error when the platform is unsupported or the package is absent. */
+export function launchGui() {
+    const pkg = guiPackageFor();
+    if (!pkg) {
+        throw new Error(`the desktop GUI has no prebuilt binary for ${process.platform}/${process.arch} — build it from source with \`task gui:build\`.`);
+    }
+    const artifact = resolveGuiArtifact();
+    if (!artifact) {
+        throw new Error(`GUI binary not found — the platform package "${pkg}" is not installed.\n` +
+            `Reinstall the CLI so npm pulls it: \`npm install -g @event4u/agent-switch\`.`);
+    }
+    // On POSIX the raw binary needs the executable bit (npm can drop it).
+    if (process.platform !== "win32" && process.platform !== "darwin") {
+        try {
+            fs.chmodSync(artifact, 0o755);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    const { program, args } = guiLaunchArgv(process.platform, artifact);
+    const child = spawn(program, args, { detached: true, stdio: "ignore" });
+    child.unref();
+}