@event4u/agent-switch 2.2.0 → 2.3.0

package/README.md

@@ -74,7 +74,7 @@ $ asw             # list all profiles, the starred one marked *
 - **Disable instead of delete** — a disabled account keeps its login and history but is never picked and not polled; refresh it by hand when you want to look.
 - **One prompt history** — with the shared setup (`agent-switch share on`, the app's default) ↑ and Ctrl+R in Claude Code find your old prompts on every account.
 - **Explicit switching only** — a running session moves to another account only when you choose it (live switch, take over or hand off). Nothing switches on its own.
-- **Balanced starts, pools and project rules** — a plain `claude` with no folder rule is spread across your enabled accounts: it starts on the one that would lose the most at its next reset (its rest divided by the hours until its weekly window resets), so every account gets used up by its reset instead of one running dry while another resets unused. An account at its protection limit is never picked; when the best accounts are level, or nothing can be weighed, the account set for plain starts (the star) is used. A folder can also point at one account, or at a pool that is balanced the same way. `dir --json` tells you why. The weighing uses cached usage only — written by the background service (`agent-switch service install`, which refreshes every enabled account every 5 minutes) or by the desktop app's own refresh; usage older than 10 minutes is not trusted and `dir --json` says so. Under `guard block` an account that already has a live session is skipped.
+- **Balanced starts, pools and project rules** — a plain `claude` with no folder rule is spread across your enabled accounts: it starts on the one that would lose the most at its next reset (its rest divided by the hours until its weekly window resets), so every account gets used up by its reset instead of one running dry while another resets unused. An account at its protection limit is never picked; when the best accounts are level, or nothing can be weighed, the account set for plain starts (the star) is used. A folder can also point at one account, or at a pool that is balanced the same way — a pool start never leaves the pool: without fresh usage it still takes a member, and a pool that is gone or has no usable member refuses the start. `dir --json` tells you why. The weighing uses cached usage only — written by the background service (`agent-switch service install`, which refreshes every enabled account every 5 minutes) or by every refresh the desktop app makes (kept unthrottled in `usage-latest.json`); usage older than 10 minutes is not trusted and `dir --json` says so. Under `guard block` an account that already has a live session is skipped.
 - **Health, activity, sign-in state** — `doctor --json`, `activity`, `auth-status` — readouts without tokens.
 - **Switch, the desktop pet** — introduces itself once, on the very first start. Never again.
 
@@ -327,9 +327,33 @@ profile. Two strategies, picked per app:
 
 ```bash
 agent-switch apps                 # list launchable GUI apps + installed state
-agent-switch open <app> [profile] # launch an app on a profile (active if omitted)
+agent-switch open <app> [profile] # launch an app on a profile (active if omitted);
+                                  # if that profile already runs, its window comes to the front
+agent-switch launcher add <app> <profile>     # a Dock/Spotlight app for that account
+agent-switch launcher remove <app> <profile>  # remove it again (list / repair as well)
+agent-switch app-settings copy claude-desktop --from default --to <profile>
+                                  # MCP servers, preferences, extensions — never logins
 ```
 
+**Launchers.** `launcher add` puts a small app into `~/Applications/Agent Switch/`
+(e.g. `Claude Desktop – Work.app`) that runs `agent-switch open` for that
+account — drag it into the Dock or start it from Spotlight. It is built locally
+with `osacompile` and signed ad hoc, so Gatekeeper does not prompt; the
+original app is never copied, patched or re-signed. The launcher carries the
+app's icon; the open window still shows the app's own icon and name. Removing
+or renaming a profile removes or rebuilds its launchers, `uninstall` removes
+them all, and `launcher repair` rebuilds them after Node or agent-switch moved.
+macOS only: Claude Desktop on Windows is an MSIX package whose executable
+cannot be started with its own arguments.
+
+**Copying Claude Desktop settings.** Chats, Projects and memory belong to the
+account on Anthropic's servers and cannot be moved. What lives on the Mac can:
+`app-settings copy` takes the MCP servers, preferences and installed extensions
+from the default install (`default`) or another profile. It never copies
+`config.json` (it holds the login's token cache), cookies, web storage,
+session folders or preferences scoped to one account; replaced files are kept
+as `*.pre-copy`. Quit Claude Desktop on the target profile first.
+
 **Supported now:**
 
 - **Claude Desktop** (`agent-switch open claude-desktop <profile>`) —
@@ -343,8 +367,8 @@ agent-switch open <app> [profile] # launch an app on a profile (active if omitte
 More clients land via their roadmaps in `agents/roadmaps/`.
 
 Caveats (why this is experimental):
-- **macOS-only for now**; launched via the `open` command, not a Finder/Dock
-  double-click (a plain launch doesn't carry the flag/env → no isolation).
+- **macOS-only for now**; a plain Finder/Dock start of the app itself doesn't
+  carry the flag/env (→ no isolation) — use `agent-switch open` or a launcher.
 - **Unofficial / version-fragile** — no vendor ships a built-in account
   switcher; an app update can change launcher behaviour. Re-verify per app.
 - The profile's data dir is never swapped on a live app (that risks

package/dist/activity.js

@@ -27,6 +27,8 @@ export const ACTIVITY_KINDS = [
     "protection",
     "pool",
     "remove",
+    "launcher",
+    "settings",
 ];
 /** Strip anything shaped like a credential: OAuth/API key prefixes, JWTs, and
  *  long opaque runs. Over-redaction is fine here; a leaked token is not. */

package/dist/auth-status.js

@@ -11,6 +11,16 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 export const EXPIRING_MS = 3 * 24 * 60 * 60_000;
+/** Who keeps a Claude login fresh: the background service polls (and so
+ *  refreshes) every enabled profile — except one sharing the default install's
+ *  login, which agent-switch never refreshes. */
+export function keptFreshByFor(provider, o, base) {
+    if (o.shared)
+        return "only you, by using it — it shares its login with the default install";
+    if (provider === "claude" && o.serviceInstalled)
+        return "the agent-switch service (Claude Code's own refresh)";
+    return base;
+}
 function iso(ms) {
     return ms !== null && Number.isFinite(ms) ? new Date(ms).toISOString() : null;
 }

package/dist/balance.js

@@ -34,7 +34,10 @@ export function weigh(snapshot, now, thresholdPct) {
         return { usable: false, why: "usage unknown" };
     const rest = Math.max(0, 100 - w.utilization);
     const resetH = w.resetsAt && !isNaN(Date.parse(w.resetsAt)) ? Math.max(1, (Date.parse(w.resetsAt) - now) / HOUR_MS) : null;
-    return { usable: true, need: rest / (resetH ?? UNKNOWN_RESET_H), rest, resetH, window: windowName(w), key: w.key };
+    // The fullest window breaks a level tie: equal room this week, but one is about
+    // to hit its 5h limit.
+    const peak = Math.max(...snapshot.windows.map((x) => (typeof x.utilization === "number" ? x.utilization : 0)));
+    return { usable: true, need: rest / (resetH ?? UNKNOWN_RESET_H), rest, resetH, window: windowName(w), key: w.key, peak };
 }
 const WINDOW_NAME = { five_hour: "5h", seven_day: "7d", monthly: "30d" };
 /** Named by key: a window read back from the usage history carries its key as label. */

package/dist/daemon.js

@@ -26,13 +26,13 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { ROOT, activeFor, configDir, isDisabled, labelFor, listProfiles, readAutoSwitch, readBinaryPath } from "./profiles.js";
+import { ROOT, activeFor, configDir, isDisabled, labelFor, listProfiles, readAutoSwitch, readBinaryPath, sharesDefaultLogin } from "./profiles.js";
 import { profileDir } from "./profiles.js";
 import { fetchUsage, liveSessionPids } from "./api.js";
-import { defaultFreshenDeps, freshAccessToken } from "./token-freshen.js";
+import { defaultFreshenDeps, usageToken } from "./token-freshen.js";
 import { parseUsage, detectCrossings, pickSwitchTarget, maxUtilization } from "./usage.js";
 import { readCodexUsage } from "./codex-usage.js";
-import { recordHistorySample } from "./history.js";
+import { LATEST_FILE, recordHistorySample, writeLatestSnapshot } from "./history.js";
 import { appendNotification, markOsNotified } from "./notifications.js";
 import { readOsNotifications } from "./profiles.js";
 import { osNotify } from "./os-notify.js";
@@ -295,8 +295,9 @@ async function snapshotFor(provider, name) {
         return readCodexUsage(configDir("codex", name));
     // An expired access token is the daemon's most common "usage stopped moving"
     // cause — a profile nobody is running never refreshes itself. Let Claude Code
-    // refresh it first (cooldown-guarded, no-op while the token is still good).
-    const token = freshAccessToken(configDir("claude", name), defaultFreshenDeps(readBinaryPath("claude")));
+    // refresh it first (cooldown-guarded, no-op while the token is still good) —
+    // never for a profile sharing the default install's login.
+    const token = usageToken(configDir("claude", name), defaultFreshenDeps(readBinaryPath("claude")), sharesDefaultLogin("claude", name));
     if (!token)
         return null;
     const raw = await fetchUsage(token);
@@ -352,6 +353,7 @@ async function pollProvider(provider, state, thresholds, notifiedReset, log) {
             notify({ kind: "info", title: pNotice.title, message: pNotice.message });
         }
         recordHistorySample(path.join(profileDir(provider, name), "usage-history.json"), snapshot);
+        writeLatestSnapshot(path.join(profileDir(provider, name), LATEST_FILE), snapshot);
         if (name === active) {
             const prev = thresholds.get(`${provider}/${name}`) ?? {};
             const { crossings, state: next } = detectCrossings(snapshot, prev);

package/dist/desktop-settings.js

@@ -0,0 +1,90 @@
+/**
+ * Copy one desktop profile's local settings into another (Claude Desktop):
+ * MCP servers, preferences and installed extensions. Chats, Projects and
+ * memory live with the account on the server, so they are not here at all.
+ *
+ * What is never copied: `config.json` (it holds the OAuth token cache),
+ * cookies and web storage (the login), session folders (bound to an account
+ * id), and preference keys scoped to one account (`…ByAccount`) or to the
+ * target's own files (`coworkUserFilesPath`).
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+const LAYOUTS = {
+    "claude-desktop": {
+        merged: ["claude_desktop_config.json", "claude_desktop_config.mcp.json"],
+        replaced: ["Claude Extensions", "Claude Extensions Settings"],
+    },
+};
+/** The app's own data dir outside agent-switch (the plain, unprofiled install). */
+export const DEFAULT_DATA_DIR = {
+    "claude-desktop": path.posix.join(os.homedir(), "Library", "Application Support", "Claude"),
+};
+export function hasSettingsLayout(appId) {
+    return appId in LAYOUTS;
+}
+function isObject(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+export function mergeDesktopConfig(src, dst) {
+    const out = { ...dst };
+    if (src.mcpServers !== undefined)
+        out.mcpServers = src.mcpServers;
+    if (isObject(src.preferences)) {
+        const prefs = isObject(dst.preferences) ? { ...dst.preferences } : {};
+        for (const [k, v] of Object.entries(src.preferences))
+            if (!k.endsWith("ByAccount"))
+                prefs[k] = v;
+        out.preferences = prefs;
+    }
+    return out;
+}
+function readJson(file) {
+    try {
+        const v = JSON.parse(fs.readFileSync(file, "utf8"));
+        return isObject(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+function backup(file) {
+    let to = `${file}.pre-copy`;
+    if (fs.existsSync(to))
+        to = `${file}.pre-copy-${Date.now()}`;
+    fs.cpSync(file, to, { recursive: true });
+    return to;
+}
+export function copyDesktopSettings(appId, fromDir, toDir) {
+    const layout = LAYOUTS[appId];
+    if (!layout)
+        throw new Error(`${appId} has no settings layout agent-switch knows how to copy.`);
+    fs.mkdirSync(toDir, { recursive: true });
+    const copied = [];
+    const backups = [];
+    for (const name of layout.merged) {
+        const src = readJson(path.join(fromDir, name));
+        if (!src)
+            continue;
+        const dstFile = path.join(toDir, name);
+        const dst = fs.existsSync(dstFile) ? readJson(dstFile) : null;
+        if (fs.existsSync(dstFile))
+            backups.push(backup(dstFile));
+        fs.writeFileSync(dstFile, JSON.stringify(mergeDesktopConfig(src, dst ?? {}), null, 2) + "\n");
+        copied.push(name);
+    }
+    for (const name of layout.replaced) {
+        const src = path.join(fromDir, name);
+        if (!fs.existsSync(src))
+            continue;
+        const dst = path.join(toDir, name);
+        if (fs.existsSync(dst)) {
+            backups.push(backup(dst));
+            fs.rmSync(dst, { recursive: true, force: true });
+        }
+        fs.cpSync(src, dst, { recursive: true });
+        copied.push(name);
+    }
+    return { copied, backups };
+}

package/dist/dir-resolve.js

@@ -2,11 +2,15 @@
  * Which profile a new session in a folder gets, and why — the logic behind
  * `agent-switch dir` (the shell wrapper's hot path) and `dir --json`.
  *
- * Order: folder rule (to a profile, or to a pool) > active profile > none.
+ * Order: folder rule (to a profile, or to a pool) > balanced plain start > active
+ * profile > none. A rule never resolves outside itself: a disabled or missing
+ * profile, like a pool that cannot serve, refuses the start (`blocked`).
  * A pool resolves to the member with the most headroom on FRESH cached usage.
  * Unknown usage is never treated as free: a member whose usage is older than
- * {@link FRESH_USAGE_MS}, missing, or who is signed out is skipped, and when no
- * member qualifies the rule falls back to the active profile and says so. No
+ * {@link FRESH_USAGE_MS}, missing, or who is signed out is skipped. A pool rule
+ * never leaves its pool: with no fresh member it takes a usable member anyway,
+ * and when the pool is gone or has no usable member the start is refused
+ * (`blocked`) rather than run on an account outside it. No
  * network call happens here — only the cache the daemon / `status` already wrote.
  * The background service (`agent-switch service`) is what keeps that cache
  * fresh for pool members: it polls every member of a pool a folder rule targets.
@@ -37,6 +41,10 @@ function fallbackToActive(i, why) {
     why.push("No active profile — the tool starts with its own default login");
     return { name: null, why };
 }
+function refuse(why, reason) {
+    why.push(`Refused: ${reason}`);
+    return { name: null, why, blocked: reason };
+}
 export function resolveForDir(i) {
     const shown = (p) => (i.displayPath ? i.displayPath(p) : p);
     const why = [];
@@ -44,33 +52,40 @@ export function resolveForDir(i) {
         const id = poolIdOf(i.mapping.name);
         why.push(`Rule: folder ${shown(i.mapping.path)} → pool ${id}`);
         const pool = i.pool(id);
-        if (!pool) {
-            why.push(`Pool ${id} no longer exists`);
-            return fallbackToActive(i, why);
-        }
+        if (!pool)
+            return refuse(why, `pool ${id} no longer exists — bind the folder anew or remove the rule (agent-switch unmap)`);
         const considered = pool.members.map(parseMember).filter((m) => m && m.provider === i.providerId);
-        if (considered.length === 0) {
-            why.push(`Pool ${id} has no ${i.providerId} profile`);
-            return fallbackToActive(i, why);
+        if (considered.length === 0)
+            return refuse(why, `pool ${id} has no ${i.providerId} profile — add one with agent-switch pool add`);
+        const members = considered.map((m) => m.name);
+        const best = pickBalanced(i, members, why, null);
+        if (best)
+            return { name: best, why };
+        // No fresh numbers to weigh: still a member — the rule is a boundary first.
+        const usable = (n) => i.exists(n) && !i.disabled?.(n) && !i.sharesDefaultLogin?.(n) && i.signedIn(n) && !(i.guard === "block" && (i.live?.(n) ?? false));
+        const anyone = members.filter(usable);
+        if (!anyone.length)
+            return refuse(why, `pool ${id} has no usable ${i.providerId} member (signed out, disabled, busy or sharing the default login)`);
+        why.push(`No member of pool ${id} has fresh usage`);
+        why.push("Usage comes from the background service or the open desktop app — keep one running (agent-switch service install)");
+        if (i.active && anyone.includes(i.active)) {
+            why.push(`Using the plain-start account ${i.providerId}/${i.active}, a member of pool ${id}`);
+            return { name: i.active, why };
         }
-        const best = pickBalanced(i, considered.map((m) => m.name), why, null);
-        if (!best) {
-            why.push(`No member of pool ${id} has fresh usage`);
-            why.push("Pool picks use the background service's cached usage — keep it running: agent-switch service install");
-            return fallbackToActive(i, why);
-        }
-        return { name: best, why };
+        why.push(`Using ${i.providerId}/${anyone[0]}, the first usable member of pool ${id}`);
+        return { name: anyone[0], why };
     }
-    if (i.mapping && i.exists(i.mapping.name) && i.disabled?.(i.mapping.name)) {
-        why.push(`Rule: folder ${shown(i.mapping.path)} → ${i.providerId}/${i.mapping.name}, but that account is disabled`);
-        return balancePlain(i, why);
-    }
-    if (i.mapping && i.exists(i.mapping.name)) {
-        why.push(`Rule: folder ${shown(i.mapping.path)} → ${i.providerId}/${i.mapping.name}`);
+    // A rule to one account is a boundary too: never another account in its place.
+    if (i.mapping) {
+        const key = `${i.providerId}/${i.mapping.name}`;
+        const flag = i.providerId === "claude" ? "" : ` --provider ${i.providerId}`;
+        why.push(`Rule: folder ${shown(i.mapping.path)} → ${key}`);
+        if (!i.exists(i.mapping.name))
+            return refuse(why, `${key} no longer exists — bind the folder anew (agent-switch map) or remove the rule (agent-switch unmap)`);
+        if (i.disabled?.(i.mapping.name))
+            return refuse(why, `${key} is disabled — turn it back on (agent-switch enable ${i.mapping.name}${flag}) or change the rule`);
         return { name: i.mapping.name, why };
     }
-    if (i.mapping)
-        why.push(`Rule: folder ${shown(i.mapping.path)} → ${i.providerId}/${i.mapping.name}, but that profile is gone`);
     return balancePlain(i, why);
 }
 /** No rule decides: balance across all profiles, or the active one when the
@@ -79,7 +94,7 @@ function balancePlain(i, why) {
     if (!i.names)
         return fallbackToActive(i, why);
     const n = i.names.length;
-    why.push(`${i.mapping ? "Balancing" : "No folder rule — balancing"} across ${n} ${i.providerId} account${n === 1 ? "" : "s"} by what each would lose at its reset`);
+    why.push(`No folder rule — balancing across ${n} ${i.providerId} account${n === 1 ? "" : "s"} by what each would lose at its reset`);
     const best = pickBalanced(i, i.names, why, i.active);
     if (best)
         return { name: best, why };
@@ -105,6 +120,10 @@ function pickBalanced(i, names, why, prefer) {
             why.push(`Skipped ${key}: disabled`);
             continue;
         }
+        if (i.sharesDefaultLogin?.(name)) {
+            why.push(`Skipped ${key}: shares its login with the default install`);
+            continue;
+        }
         if (!i.signedIn(name)) {
             why.push(`Skipped ${key}: signed out`);
             continue;
@@ -137,9 +156,17 @@ function pickBalanced(i, names, why, prefer) {
     const tied = picks.filter((p) => level(p.w.need, top.w.need));
     let chosen = top;
     if (tied.length > 1) {
-        chosen = tied.find((p) => p.name === prefer) ?? tied.find((p) => !p.live) ?? top;
+        const free = tied.filter((p) => !p.live);
+        const roomiest = (ps) => ps.reduce((a, b) => (b.w.peak < a.w.peak ? b : a));
+        chosen = tied.find((p) => p.name === prefer) ?? (free.length ? roomiest(free) : roomiest(tied));
         const keys = tied.map((p) => `${i.providerId}/${p.name}`).join(", ");
-        const by = chosen.name === prefer ? "the plain-start account" : !chosen.live && tied.some((p) => p.live) ? "the one without a live session" : "the first of them";
+        const by = chosen.name === prefer
+            ? "the plain-start account"
+            : !chosen.live && tied.some((p) => p.live)
+                ? "the one without a live session"
+                : tied.some((p) => p.w.peak !== chosen.w.peak)
+                    ? "the one with the most room right now"
+                    : "the first of them";
         why.push(`${keys} are level (${top.w.need.toFixed(1)} %/h) — taking ${by}, ${i.providerId}/${chosen.name}`);
     }
     const runnerUp = picks.filter((p) => p !== chosen).reduce((a, b) => (!a || b.w.need > a.w.need ? b : a), null);

package/dist/doctor.js

@@ -10,7 +10,7 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { ROOT, activeFor, configDir, identity, listProfiles, profileExists, readGuard } from "./profiles.js";
+import { ROOT, activeFor, configDir, identity, listProfiles, profileExists, readGuard, sharesDefaultLogin } from "./profiles.js";
 import { allProviders } from "./providers.js";
 import { credentialStore } from "./credentials.js";
 import { sharedLinkHealth } from "./share.js";
@@ -210,6 +210,38 @@ async function providerChecks(checks) {
         }
     }
 }
+/** Profiles that share their login with the default install: agent-switch
+ *  never refreshes or balances onto them; a separate sign-in ends that. */
+/** The account the provider's own default install is signed into, where it can
+ *  be read without touching a credential (Antigravity's needs the keychain). */
+function defaultIdentity(p) {
+    if (p.id === "antigravity")
+        return null;
+    // Claude keeps .claude.json in the home dir, next to (not inside) ~/.claude.
+    return p.readIdentity(p.id === "claude" ? os.homedir() : p.defaultConfigDir());
+}
+export function sharedLoginCheck(rows, likely = []) {
+    if (!rows.length && !likely.length)
+        return { id: "shared-login", status: "ok", title: "No profile shares its login with the default install", detail: "" };
+    const key = (r) => `${r.provider}/${r.name}`;
+    const flag = (p) => (p === "claude" ? "" : ` --provider ${p}`);
+    const parts = [];
+    if (rows.length) {
+        parts.push(`${rows.map(key).join(", ")} — imported with the default install's credential. agent-switch never refreshes ${rows.length === 1 ? "it" : "them"} (that would sign the other side out) and never starts ${rows.length === 1 ? "it" : "them"} by balancing.`);
+    }
+    // Imports from before the marker existed: same account as the default install.
+    if (likely.length) {
+        parts.push(`${likely.map(key).join(", ")} may share ${likely.length === 1 ? "its" : "their"} login with the default install (same account, no mark) — if imported, mark ${likely.length === 1 ? "it" : "them"}; if signed in on ${likely.length === 1 ? "its" : "their"} own, ignore this.`);
+    }
+    const n = rows.length + likely.length;
+    return {
+        id: "shared-login",
+        status: "warn",
+        title: rows.length ? `${n === 1 ? "A profile shares" : `${n} profiles share`} the default install's login` : "A profile may share the default install's login",
+        detail: parts.join(" "),
+        fix: rows.length ? `agent-switch login ${rows[0].name}${flag(rows[0].provider)}` : `agent-switch mark-shared ${likely[0].name}${flag(likely[0].provider)}`,
+    };
+}
 export async function collectDoctorReport() {
     const checks = [];
     checks.push(cliOnPathCheck());
@@ -220,6 +252,8 @@ export async function collectDoctorReport() {
     await providerChecks(checks);
     const identities = allProviders().flatMap((p) => listProfiles(p.id).map((n) => ({ provider: p.id, name: n, identity: identity(p.id, n) })));
     checks.push(signInIsolationCheck(identities));
+    const defaults = new Map(allProviders().map((p) => [p.id, defaultIdentity(p)]));
+    checks.push(sharedLoginCheck(identities.filter((r) => sharesDefaultLogin(r.provider, r.name)), identities.filter((r) => !sharesDefaultLogin(r.provider, r.name) && r.identity !== null && r.identity === defaults.get(r.provider))));
     // Share-link health (Claude-config sharing).
     for (const n of listProfiles("claude")) {
         const health = sharedLinkHealth(configDir("claude", n));

package/dist/history.js

@@ -56,3 +56,23 @@ export function seriesFor(samples, windowKey) {
         .map((s) => s.windows.find((w) => w.key === windowKey)?.utilization)
         .filter((u) => typeof u === "number");
 }
+/** The last snapshot read for a profile, kept unthrottled next to the history:
+ *  `dir` trusts usage only while it is minutes old, and the history keeps at
+ *  most one sample an hour. Holds the snapshot only, never a token. */
+export const LATEST_FILE = "usage-latest.json";
+export function writeLatestSnapshot(file, snapshot) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(snapshot) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+export function readLatestSnapshot(file) {
+    try {
+        const snapshot = JSON.parse(fs.readFileSync(file, "utf8"));
+        const capturedMs = Date.parse(snapshot?.capturedAt);
+        return Array.isArray(snapshot?.windows) && !isNaN(capturedMs) ? { snapshot, capturedMs } : null;
+    }
+    catch {
+        return null;
+    }
+}