@event4u/agent-switch 1.7.0 → 2.0.0

package/README.md

@@ -313,7 +313,9 @@ The CLI is fully usable on its own. Two optional layers add convenience:
 - **Tray/menubar GUI** (`gui/`, Tauri) — a small panel to see per-profile usage
   and switch/open sessions. It is a **client of the CLI** (`agent-switch <cmd>
   --json`) and never re-implements profile logic; the CLI core stays
-  dependency-free. See [`gui/README.md`](gui/README.md).
+  dependency-free. See [`gui/README.md`](gui/README.md). Running `agent-switch`
+  **with no command** launches it (same as `agent-switch gui`); if the GUI is
+  already running, no second copy starts.
 
 Usage readout is per-provider: Claude exposes an OAuth `/usage` endpoint;
 **Codex and Gemini have no usage readout**, so they show identity only (never a

package/dist/api.js

@@ -7,10 +7,11 @@
  * both with `Authorization: Bearer <accessToken>` and the
  * `anthropic-beta: oauth-2025-04-20` header.
  *
- * Deliberately NOT adopted from claude-swap: the token-refresh grant. Our
- * profiles are live logins — Claude Code refreshes its own tokens per config
- * dir. Refreshing from outside would rotate the refresh token underneath a
- * running session for no benefit.
+ * This module never refreshes a token. An out-of-band refresh grant rotates the
+ * refresh token underneath a running session and would strand Claude Code with
+ * a dead one (ADR-004 § Evidence — the rotation is confirmed, not theoretical).
+ * A spent access token is instead handed to `token-freshen.ts`, which lets
+ * Claude Code refresh its own store; this stays the low-level fetch layer.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";

package/dist/codex-reset.js

@@ -13,8 +13,8 @@
  *
  * SAFETY: a reset credit is scarce and non-refundable, and redeeming is known to
  * be occasionally buggy upstream. This module only redeems when the caller asks;
- * the daemon's reset-first path guards it to at most once per reset cycle so a
- * loop can never burn a user's whole balance. The redeem call itself cannot be
+ * the daemon's reset-redemption path guards it to at most once per reset cycle so
+ * a loop can never burn a user's whole balance. The redeem call itself cannot be
  * exercised in CI (it would consume a real credit) — the request construction is
  * unit-tested and it is validated live the first time a limit is hit.
  */

package/dist/config-transfer.js

@@ -0,0 +1,184 @@
+/**
+ * Config-only cross-machine export/import (SAFE subset).
+ *
+ * Moves a profile's SHARED config — settings.json, keybindings.json, CLAUDE.md,
+ * and the skills/, commands/, agents/ trees — between machines as a single
+ * self-describing JSON bundle (base64-encoded file bodies). It handles NO
+ * credentials: the allowlist is the exact `SHARED_ITEMS` set from `share.ts`,
+ * and the account-scoped deny-set (`.claude.json`, `.credentials.json`,
+ * `plugins/`, `sessions/`, `ide/`, `statsig/`) is excluded by construction —
+ * we only ever walk allowlisted top-level names, and both export and import
+ * additionally assert the top-level segment against the allowlist/deny-set.
+ *
+ * A `--full` variant that would bundle live OAuth tokens is deliberately NOT
+ * implemented (see {@link assertNotFull}) — it is an account-takeover vector.
+ *
+ * Threat-model controls implemented here (untrusted bundle on import):
+ *   - path shape guard: no absolute paths, no `..` traversal, no empty/`.`
+ *     segments, top-level segment must be an allowlisted `SHARED_ITEMS` name.
+ *   - path-confinement (zip-slip): the resolved real path must stay inside the
+ *     target config dir.
+ *   - bounded input: at most {@link MAX_ENTRIES} entries and {@link MAX_FILE_BYTES}
+ *     per decoded file.
+ *   - deny-set is never written even if present in the bundle (rejected).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { SHARED_ITEMS } from "./share.js";
+/** The single source of the allowlist — the same names `share.ts` links. */
+const ALLOW = new Set(SHARED_ITEMS);
+/** Account-/instance-scoped top-level names that must never be in a bundle.
+ *  Kept in sync with the deny-set documented in `share.ts`'s header. Disjoint
+ *  from ALLOW, so `!ALLOW.has(top)` already excludes these — asserted anyway
+ *  for a clearer error and defense-in-depth. */
+const DENY_SET = new Set([".claude.json", ".credentials.json", "plugins", "sessions", "ide", "statsig"]);
+/** Bound untrusted input: refuse a bundle with more entries than this. */
+export const MAX_ENTRIES = 5000;
+/** Bound untrusted input: refuse a single decoded file larger than this. */
+export const MAX_FILE_BYTES = 25 * 1024 * 1024;
+export const FULL_REFUSAL = "--full (bundling live OAuth tokens) is intentionally not implemented — it is an account-takeover vector; export is config-only by design.";
+/** Refuse the `--full` (credential-bundling) variant. Throws so callers can
+ *  surface it via `die`; kept here because it is a config-transfer policy. */
+export function assertNotFull(full) {
+    if (full)
+        throw new Error(FULL_REFUSAL);
+}
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+function topSegment(relPosix) {
+    return relPosix.split("/")[0];
+}
+/** Add one file's body to the bundle, keyed by its POSIX-relative path. The
+ *  top-level allowlist/deny-set assertion is redundant (we only walk allowlisted
+ *  trees) but enforced regardless. */
+function addFile(root, rel, out) {
+    const posix = toPosix(rel);
+    const top = topSegment(posix);
+    if (DENY_SET.has(top) || !ALLOW.has(top))
+        return; // excluded by construction — assert anyway
+    out[posix] = fs.readFileSync(path.join(root, rel)).toString("base64");
+}
+/** Recursively collect files under an allowlisted directory tree. Follows
+ *  symlinks to their real target (a `share on` link) so the bundle carries
+ *  content, not a link we cannot reproduce on another machine; skips dangling
+ *  links. */
+function walkDir(root, relDir, out) {
+    const absDir = path.join(root, relDir);
+    let entries;
+    try {
+        entries = fs.readdirSync(absDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const rel = `${relDir}/${entry.name}`;
+        const abs = path.join(root, rel);
+        let st;
+        try {
+            st = fs.statSync(abs); // statSync (not lstat) follows a shared-mode link to its target
+        }
+        catch {
+            continue; // dangling / unreadable
+        }
+        if (st.isDirectory())
+            walkDir(root, rel, out);
+        else if (st.isFile())
+            addFile(root, rel, out);
+    }
+}
+/**
+ * Walk ONLY the SHARED_ITEMS allowlist (files + directory trees, recursively)
+ * under `configDir`, base64-encode each file, and return a JSON bundle string.
+ * The deny-set is never read (we only walk allowlisted names). Absent items are
+ * skipped.
+ */
+export function exportConfig(configDir) {
+    const files = {};
+    for (const name of SHARED_ITEMS) {
+        const abs = path.join(configDir, name);
+        let st;
+        try {
+            st = fs.statSync(abs); // follow a top-level shared-mode link to its target
+        }
+        catch {
+            continue; // absent / dangling
+        }
+        if (st.isFile())
+            addFile(configDir, name, files);
+        else if (st.isDirectory())
+            walkDir(configDir, name, files);
+    }
+    const bundle = { version: 1, files };
+    return JSON.stringify(bundle);
+}
+/**
+ * Parse a config bundle and write its config-only files under `configDir`.
+ * Returns the list of written relative paths. Rejects (throws) on any control
+ * violation — an absolute path, `..` traversal, a non-allowlisted or deny-set
+ * top-level segment, a path escaping the config dir, or an over-limit bundle.
+ * Never writes a credential/deny-set path even if present.
+ */
+export function importConfig(configDir, bundleJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bundleJson);
+    }
+    catch {
+        throw new Error("invalid config bundle: not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("invalid config bundle: expected an object");
+    }
+    const b = parsed;
+    if (b.version !== 1)
+        throw new Error(`unsupported config bundle version ${String(b.version)} (expected 1)`);
+    if (!b.files || typeof b.files !== "object" || Array.isArray(b.files)) {
+        throw new Error("invalid config bundle: missing 'files' map");
+    }
+    const entries = Object.entries(b.files);
+    if (entries.length > MAX_ENTRIES) {
+        throw new Error(`config bundle has ${entries.length} entries (> ${MAX_ENTRIES}) — refusing`);
+    }
+    fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+    const root = fs.realpathSync(configDir); // resolve symlinks once for the confinement check
+    const coarseB64Limit = 4 * Math.ceil(MAX_FILE_BYTES / 3) + 4;
+    const written = [];
+    for (const [rawPath, value] of entries) {
+        if (typeof value !== "string")
+            throw new Error(`invalid bundle entry "${rawPath}": value is not a base64 string`);
+        // (a) path shape guards — normalize any backslashes to POSIX for the checks.
+        const rel = rawPath.replace(/\\/g, "/");
+        if (path.isAbsolute(rawPath) || rel.startsWith("/")) {
+            throw new Error(`refusing absolute path in bundle: "${rawPath}"`);
+        }
+        const segments = rel.split("/");
+        if (segments.some((s) => s === ".."))
+            throw new Error(`refusing path traversal ('..') in bundle: "${rawPath}"`);
+        if (segments.some((s) => s === "" || s === "."))
+            throw new Error(`refusing malformed path in bundle: "${rawPath}"`);
+        const top = segments[0];
+        if (DENY_SET.has(top))
+            throw new Error(`refusing deny-set path in bundle: "${rawPath}" (account-scoped, never imported)`);
+        if (!ALLOW.has(top))
+            throw new Error(`refusing non-allowlisted path in bundle: "${rawPath}"`);
+        // bounded input: coarse check on the base64 length before allocating, then
+        // a precise check on the decoded size.
+        if (value.length > coarseB64Limit)
+            throw new Error(`refusing oversized file "${rawPath}" (> ${MAX_FILE_BYTES} bytes)`);
+        const buf = Buffer.from(value, "base64");
+        if (buf.length > MAX_FILE_BYTES)
+            throw new Error(`refusing oversized file "${rawPath}" (> ${MAX_FILE_BYTES} bytes)`);
+        // (b) path-confinement / zip-slip: the resolved real path must stay inside root.
+        const dest = path.resolve(root, rel);
+        if (dest !== root && !dest.startsWith(root + path.sep)) {
+            throw new Error(`refusing path escaping the config dir: "${rawPath}"`);
+        }
+        // (c) write the decoded body (mkdir -p parent).
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, buf, { mode: 0o600 });
+        written.push(rel);
+    }
+    return written;
+}

package/dist/credentials.js

@@ -2,10 +2,12 @@
  * Per-OS credential access — a read-only abstraction over where Claude Code
  * keeps a profile's OAuth credential.
  *
- * By design there is NO `write()`: agent-switch never writes Claude Code's
- * credential storage. The only supported way to place a credential is seeding
- * a plaintext `.credentials.json` file inside the config dir (see `import`),
- * which Claude Code then migrates into its own store on first use.
+ * By design this store has NO `write()`: agent-switch never writes Claude Code's
+ * credential storage **outside the `rebind` path** (ADR-003 — the single
+ * sanctioned exception, which writes the macOS Keychain entry directly under
+ * Claude Code's lock via `keychain.addPassword`). The only other way to place a
+ * credential is seeding a plaintext `.credentials.json` file inside the config
+ * dir (see `import`), which Claude Code migrates into its own store on first use.
  *
  * Backends:
  *   - darwin  → Keychain (hashed service per config dir), then the plaintext

package/dist/daemon.js

@@ -1,28 +1,29 @@
 /**
- * Background usage daemon — poller, cache, and (opt-in) auto-switcher.
+ * Background usage daemon — poller, cache, and (opt-in) threshold notifier.
  *
  * 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.
+ * `autoSwitch.enabled` (default OFF) it also watches every profile and, once the
+ * active one hits the configured threshold, NOTIFIES the operator and SUGGESTS
+ * the account with the most headroom — it never switches automatically. The
+ * suggestion is a convenience; the actual switch is always a user interaction
+ * (see `AutoSwitchConfig`). The daemon 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;
+ * freshness, suggestion 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 { ROOT, activeFor, configDir, labelFor, listProfiles, readAutoSwitch, readBinaryPath } from "./profiles.js";
 import { profileDir } from "./profiles.js";
-import { accessTokenOf, fetchUsage, liveSessionPids, readProfileCredential } from "./api.js";
+import { fetchUsage, liveSessionPids } from "./api.js";
+import { defaultFreshenDeps, freshAccessToken } from "./token-freshen.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 { recordHistorySample } from "./history.js";
 import { appendNotification, markOsNotified } from "./notifications.js";
 import { readOsNotifications } from "./profiles.js";
 import { osNotify } from "./os-notify.js";
@@ -41,8 +42,8 @@ function notify(event) {
         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.
+// Providers the daemon may suggest a switch for on threshold (they expose a
+// usage readout to base a headroom suggestion 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");
@@ -137,6 +138,26 @@ export function nextIntervalMs(baseMs, consecutiveFailures, capMs = MAX_BACKOFF_
         return base;
     return Math.min(base * 2 ** consecutiveFailures, capMs);
 }
+/**
+ * Compliance-locked threshold decision (Council follow-up). Given the active
+ * profile and the same-provider candidates polled this cycle, decide whether to
+ * NOTIFY and which account to SUGGEST. Pure — no I/O, and crucially NO `setActive`:
+ * the daemon never auto-switches. Returns `{ notify: false }` while the active
+ * profile still has headroom (or auto-switch is off / there is no active profile).
+ * `notify` fires only alongside a concrete suggestion, mirroring the behavior
+ * before this decision was extracted from `pollProvider`.
+ */
+export function decideThresholdAction(active, polled, autoSwitch, isEligible = () => true) {
+    if (!autoSwitch.enabled || !active)
+        return { notify: false, suggestedTarget: null };
+    const activeSnap = polled.find((p) => p.name === active)?.snapshot;
+    const activeMax = activeSnap ? maxUtilization(activeSnap) : null;
+    if (activeMax === null || activeMax < autoSwitch.threshold)
+        return { notify: false, suggestedTarget: null };
+    const target = pickSwitchTarget(active, polled, autoSwitch.threshold, isEligible);
+    const suggestedTarget = target && target !== active ? target : null;
+    return { notify: suggestedTarget !== null, suggestedTarget };
+}
 // ---------- context monitoring (own-session; Phase 3) ----------
 let _claudeVer;
 function claudeVer() {
@@ -223,14 +244,16 @@ export function monitorContext(provider, name, state, log) {
 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;
+    // 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")));
     if (!token)
         return null;
     const raw = await fetchUsage(token);
     return raw ? parseUsage(raw) : null;
 }
-async function pollProvider(provider, strategy, state, thresholds, redeemed, log) {
+async function pollProvider(provider, state, thresholds, redeemed, log) {
     const names = listProfiles(provider);
     const active = activeFor(provider);
     const autoSwitch = readAutoSwitch(provider);
@@ -263,7 +286,7 @@ async function pollProvider(provider, strategy, state, thresholds, redeemed, log
         }
         state.profiles[key] = snapshot;
         polled.push({ name, snapshot });
-        appendSample(path.join(profileDir(provider, name), "usage-history.json"), snapshot);
+        recordHistorySample(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);
@@ -288,12 +311,12 @@ async function pollProvider(provider, strategy, state, thresholds, redeemed, log
     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) {
+    // Codex only (banked resets are a Codex feature): redeem a reset and STAY, 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 switch SUGGESTION on the same poll's
+    // next-cycle. Redeeming still stays on the active profile.
+    if (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}`;
@@ -309,29 +332,39 @@ async function pollProvider(provider, strategy, state, thresholds, redeemed, log
                 });
                 return failures;
             }
-            log(`auto-switch: codex/${active} reset redeem failed (${r.reason ?? "?"}) → falling back to a profile switch`);
+            log(`auto-switch: codex/${active} reset redeem failed (${r.reason ?? "?"}) → falling back to a switch suggestion`);
         }
     }
     // 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}`);
+    // Compliance decision is a pure function (decideThresholdAction): it returns
+    // notify + a suggested target and NEVER a switch — see the daemon no-auto-switch
+    // regression test. pollProvider only turns that decision into log + notify I/O.
+    const action = decideThresholdAction(active, polled, autoSwitch, eligible);
+    const target = action.suggestedTarget;
+    if (action.notify && target) {
+        // Compliance: the daemon NEVER switches automatically. It only names the
+        // suggested account with the most headroom; switching stays a user
+        // interaction (CLI/GUI). No `setActive` call here.
+        log(`threshold: ${provider}/${active} out of headroom (≥${autoSwitch.threshold}%) → suggesting ${provider}/${target} (no automatic switch)`);
+        // Name the command that opens the limit dialog (claude only — rebind is
+        // claude-scoped). Wording only; the notify/suggest DECISION above is unchanged.
+        const how = provider === "claude"
+            ? "Run `agent-switch rebind` to switch (no automatic switch)."
+            : "Switch manually (no automatic switch).";
         notify({
-            kind: "success",
-            title: "Auto-switched account",
-            message: `${provider}/${active} hit ≥${autoSwitch.threshold}% — switched active to ${provider}/${target}.`,
+            kind: "warning",
+            title: "Usage limit near",
+            message: `${provider}/${active} hit ≥${autoSwitch.threshold}% — suggested profile: ${provider}/${target}. ${how}`,
         });
     }
     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);
+        failures += await pollProvider(provider, state, thresholds, redeemed, log);
     }
     state.lastPoll = new Date().toISOString();
     state.lastError = failures > 0 ? `${failures} profile(s) failed to poll` : null;
@@ -363,8 +396,9 @@ export async function runDaemon(opts = {}) {
     // 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.
+    // Anti-loop guard for the Codex reset redemption: `<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;

package/dist/gui-launch.js

@@ -44,12 +44,49 @@ export function guiAssetSpec(platform = process.platform, arch = process.arch) {
         return { match: /-setup\.exe$/i, kind: "win-setup" };
     return null;
 }
-/** Program + args to launch a prepared artifact. Pure. */
+/** Program + args to launch a prepared artifact. Pure.
+ *  macOS uses `open` WITHOUT `-n`: a bare `open` activates the already-running
+ *  app instead of forcing a second copy, so it is the OS-level half of the
+ *  single-instance guarantee (`isGuiRunning` is the other half). */
 export function guiLaunchArgv(kind, target) {
     if (kind === "app")
-        return { program: "open", args: ["-n", target] };
+        return { program: "open", args: [target] };
     return { program: target, args: [] }; // AppImage runs directly; win-setup runs the installer
 }
+/** Substring that identifies a RUNNING GUI process for this kind inside a
+ *  process-list snapshot. Specific enough not to match the Node CLI itself
+ *  (whose command line is `node …/dist/index.js`). Pure. */
+export function guiProcessSignature(kind) {
+    if (kind === "app")
+        return "agent-switch.app/Contents/MacOS/agent-switch"; // the running .app binary
+    if (kind === "appimage")
+        return "agent-switch.AppImage";
+    return "agent-switch.exe"; // win: the installed app process (not the -setup installer)
+}
+/** Whether `signature` appears in a process-list snapshot. Pure. */
+export function guiRunningIn(signature, processList) {
+    return processList.includes(signature);
+}
+/** Live process-list snapshot for the host (full command line per process). */
+function processListSnapshot(platform = process.platform) {
+    try {
+        if (platform === "win32") {
+            return spawnSync("tasklist", [], { encoding: "utf8" }).stdout ?? "";
+        }
+        return spawnSync("ps", ["ax", "-o", "command="], { encoding: "utf8" }).stdout ?? "";
+    }
+    catch {
+        return ""; // ps/tasklist unavailable → treat as "not detectably running"
+    }
+}
+/** Whether the desktop GUI is already running on this host. Used to enforce
+ *  the single-instance rule before spawning a second copy. */
+export function isGuiRunning() {
+    const spec = guiAssetSpec();
+    if (!spec)
+        return false;
+    return guiRunningIn(guiProcessSignature(spec.kind), processListSnapshot());
+}
 /** Find a matching GUI asset on the release for `version`, falling back to the
  *  latest release. Returns null when neither has one. */
 async function findAsset(version, match) {
@@ -115,14 +152,19 @@ async function ensureGuiArtifact(spec) {
         fs.chmodSync(launchPath, 0o755);
     return launchPath;
 }
-/** Launch the desktop GUI (downloading + caching it on first use). */
+/** Launch the desktop GUI (downloading + caching it on first use).
+ *  Single-instance: if a GUI is already running, no second copy is started —
+ *  returns "already-running" so the caller can say so. */
 export async function launchGui() {
     const spec = guiAssetSpec();
     if (!spec) {
         throw new Error(`the desktop GUI has no prebuilt artifact for ${process.platform}/${process.arch} — build it from source with \`task gui:build\`.`);
     }
+    if (isGuiRunning())
+        return "already-running";
     const target = await ensureGuiArtifact(spec);
     const { program, args } = guiLaunchArgv(spec.kind, target);
     const child = spawn(program, args, { detached: true, stdio: "ignore" });
     child.unref();
+    return "launched";
 }

package/dist/history.js

@@ -15,6 +15,29 @@ export function readHistory(file) {
         return [];
     }
 }
+/** Minimum spacing between two recorded samples. The ring holds MAX_SAMPLES
+ *  (720) and the chart spans ~30 days, so ~one sample/hour fills it. Frequent
+ *  callers — a GUI refresh every few minutes, the 60s daemon poll — would
+ *  otherwise pack 720 samples into a few hours and shrink the window to that.
+ *  55 min (not a full 60) so a refresh landing slightly early still counts. */
+export const HISTORY_MIN_GAP_MS = 55 * 60 * 1000;
+/**
+ * Throttled append: record `snapshot` only when the newest existing sample is
+ * at least {@link HISTORY_MIN_GAP_MS} older (or there is none). This is the entry
+ * point every recorder uses so no caller's cadence can bloat the ring. Time is
+ * the snapshot's own `capturedAt`; an unparseable one always records.
+ */
+export function recordHistorySample(file, snapshot) {
+    const samples = readHistory(file);
+    const capturedMs = Date.parse(snapshot.capturedAt);
+    const last = samples[samples.length - 1];
+    if (last && Number.isFinite(capturedMs)) {
+        const lastMs = Date.parse(last.at);
+        if (Number.isFinite(lastMs) && capturedMs - lastMs < HISTORY_MIN_GAP_MS)
+            return samples;
+    }
+    return appendSample(file, snapshot);
+}
 /** Append a snapshot as one sample, trimming to the newest MAX_SAMPLES. */
 export function appendSample(file, snapshot) {
     const samples = readHistory(file);

package/dist/hooks.js

@@ -20,8 +20,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 /** The hook events we install. `source`/matcher values confirmed in spikes/t6
- *  (the stdin field is `source`, not `matcher`). */
-export const HOOK_EVENTS = ["SessionStart", "SessionEnd", "PreCompact", "PostCompact"];
+ *  (the stdin field is `source`, not `matcher`). `Stop` fires when Claude ends a
+ *  turn (finished / now waiting on you); `Notification` fires when it needs your
+ *  attention (a permission prompt, or a long idle) — the two session-awareness
+ *  signals the pet surfaces. */
+export const HOOK_EVENTS = ["SessionStart", "SessionEnd", "PreCompact", "PostCompact", "Stop", "Notification"];
 /** Marker stamped on every entry we add, so uninstall touches only our own. */
 export const HOOK_MARKER = "asw_managed";
 export const EVENT_RING_CAP = 500;