@event4u/agent-switch 1.6.1 → 2.0.0

package/dist/index.js

@@ -13,20 +13,27 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as readline from "node:readline";
 import { spawn, spawnSync } from "node:child_process";
-import { HOME, browserDir, configDir, die, ensureRoot, identity, listAllProfiles, listProfiles, migrateLegacyLayout, profileDir, profileExists, readJson, requireProfile, activeFor, setActive, labelFor, setLabel, clearLabel, renameProfile, isProfileLabel, PROFILE_LABELS, readAutoSwitch, readAutoSwitchAll, setAutoSwitch, readSwitchStrategy, setSwitchStrategy, readOsNotifications, setOsNotifications, readProviders, setProviderSurface, readBinaryPath, readBinaryPaths, setBinaryPath, ROOT, } from "./profiles.js";
+import { HOME, browserDir, configDir, die, ensureRoot, identity, listAllProfiles, listProfiles, migrateLegacyLayout, profileDir, profileExists, readJson, requireProfile, activeFor, setActive, labelFor, setLabel, clearLabel, renameProfile, isProfileLabel, PROFILE_LABELS, readAutoSwitch, readAutoSwitchAll, setAutoSwitch, readOsNotifications, setOsNotifications, readProviders, setProviderSurface, readBinaryPath, readBinaryPaths, setBinaryPath, ROOT, resetRebindKillSwitch, } from "./profiles.js";
 import { PROVIDER_IDS, provider, isProviderInstalled, resolveBinary } from "./providers.js";
+import { rebind, restoreRebind } from "./rebind.js";
+import { buildRebindDialog, resolveRebindChoice, selectableRows } from "./rebind-dialog.js";
 import { parseArgs, parseRun, resolveProviderValue } from "./args.js";
 import { extractBrief, writeBrief, sweepBriefs, seedPrompt } from "./handoff.js";
 import { credentialStore } from "./credentials.js";
 import { withProperLock } from "./locks.js";
 import { applySharing, removeSharing, syncSharing, sharedLinkHealth } from "./share.js";
+import { assertNotFull, exportConfig, importConfig } from "./config-transfer.js";
 import { detectShell, shellenvScript } from "./shellenv.js";
 import { runDoctor } from "./doctor.js";
+import { TOOL_IDS, checkTooling, formatToolingLines, runToolAction } from "./tooling.js";
+import { readHistory, recordHistorySample } from "./history.js";
 import { launchGui } from "./gui-launch.js";
 import { checkForUpdate, selfUpdate } from "./updates.js";
 import { mappingRows, pruneMappings, removeMapping, resolveMapping, setMapping, } from "./mappings.js";
-import { accessTokenOf, checkAuth, fetchProfile, fetchUsage, liveSessionPids, readProfileCredential, } from "./api.js";
+import { checkAuth, fetchProfile, fetchUsage, liveSessionPids, } from "./api.js";
+import { defaultFreshenDeps, freshAccessToken } from "./token-freshen.js";
 import { formatSnapshot, parseUsage } from "./usage.js";
 import { readCodexUsage } from "./codex-usage.js";
 import { redeemResetCredit } from "./codex-reset.js";
@@ -270,8 +277,7 @@ async function claudeSnapshot(name) {
         if (cached)
             return cached;
     }
-    const creds = readProfileCredential(configDir("claude", name));
-    const token = creds ? accessTokenOf(creds) : null;
+    const token = freshAccessToken(configDir("claude", name), defaultFreshenDeps(readBinaryPath("claude")));
     if (!token)
         return null;
     const raw = await fetchUsage(token);
@@ -293,6 +299,12 @@ async function cmdStatus(providerId, name, json = false) {
             : pid === "codex"
                 ? await readCodexUsage(configDir("codex", active))
                 : null;
+        // Feed the 30-day usage history from the GUI's own fetches: the GUI polls
+        // every displayed profile on each refresh, so recording the fresh snapshot
+        // here (throttled to ~hourly) fills the chart for all profiles without
+        // depending on the background daemon or an "active" profile being set.
+        if (usage)
+            recordHistorySample(path.join(profileDir(pid, active), "usage-history.json"), usage);
         const wc = worstLiveContext(pid, active);
         const context = wc
             ? { sessionId: wc.sessionId, pct: wc.pct, contextTokens: wc.contextTokens, windowTokens: wc.windowTokens, model: wc.model, confidence: wc.confidence }
@@ -326,8 +338,7 @@ async function cmdStatus(providerId, name, json = false) {
             console.log("  (no usage readout for this provider — shows own usage only where available)");
             continue;
         }
-        const creds = readProfileCredential(configDir("claude", n));
-        const token = creds ? accessTokenOf(creds) : null;
+        const token = freshAccessToken(configDir("claude", n), defaultFreshenDeps(readBinaryPath("claude")));
         if (!token) {
             console.log("  (credential not readable — profile may not have run yet)");
             continue;
@@ -449,6 +460,55 @@ function cmdShare(mode, flags = []) {
         die("usage: agent-switch share on|sync|off|status [--history] [--source <profile|default>]");
     }
 }
+/**
+ * `agent-switch config export|import <profile> [--full]` — move a Claude
+ * profile's SHARED config (settings.json, keybindings.json, CLAUDE.md, skills/,
+ * commands/, agents/) between machines as a JSON bundle. Config-ONLY — it never
+ * touches credentials. Claude-scoped (config lives under the Claude layout).
+ *
+ *   export → the bundle goes to STDOUT (pipe it: `| gpg -c > backup.gpg`), all
+ *            status on STDERR so stdout stays a clean bundle.
+ *   import → reads a bundle from STDIN into the profile's config dir.
+ *   --full → REFUSED (would bundle live OAuth tokens; account-takeover vector).
+ */
+function cmdConfig(sub, name, flags = {}) {
+    try {
+        assertNotFull(!!flags.full);
+    }
+    catch (e) {
+        die(e.message);
+    }
+    if (sub === "export") {
+        const n = requireProfile("claude", name, "config export");
+        const bundle = exportConfig(configDir("claude", n));
+        // Status on stderr — stdout is the bundle (so `... | gpg -c > backup.gpg` works).
+        console.error(`Exported config-only bundle for claude/${n} (SHARED_ITEMS allowlist; no credentials).`);
+        process.stdout.write(bundle + "\n");
+        return;
+    }
+    if (sub === "import") {
+        const n = requireProfile("claude", name, "config import");
+        let input;
+        try {
+            input = fs.readFileSync(0, "utf8"); // stdin
+        }
+        catch {
+            die("config import reads a bundle from stdin — pipe one in (e.g. `gpg -d backup.gpg | agent-switch config import <profile>`).");
+        }
+        let written;
+        try {
+            written = importConfig(configDir("claude", n), input);
+        }
+        catch (e) {
+            die(e.message);
+        }
+        console.error(`Imported ${written.length} config file(s) into claude/${n} (config-only; no credentials):`);
+        for (const w of written)
+            console.error(`  ${w}`);
+        return;
+    }
+    die("usage: agent-switch config export|import <profile>   (config-only; pipe export | gpg -c > backup.gpg)");
+}
 // ---------- session inventory + takeover (Claude; Codex lands per G0.3) ------
 /** Relative age like "3m" / "2h" / "5d" for the sessions table. */
 function ageOf(mtimeMs) {
@@ -658,6 +718,16 @@ function cmdHookEvent() {
             at: new Date().toISOString(),
         };
         appendEvent(eventFile(ROOT, who.provider, who.profile), rec);
+        // Session awareness: surface "Claude needs you / finished" as a notification
+        // the GUI routes to the pet. dedupe=false — each turn is a distinct moment,
+        // so a solo session's repeated turns are never collapsed. Best-effort; a hook
+        // must never throw.
+        if (rec.event === "Notification") {
+            appendNotification({ kind: "warning", title: "Claude is waiting", message: `${who.provider}/${who.profile} needs your input.` }, undefined, undefined, false);
+        }
+        else if (rec.event === "Stop") {
+            appendNotification({ kind: "info", title: "Claude finished", message: `${who.provider}/${who.profile} finished its turn.` }, undefined, undefined, false);
+        }
     }
     catch {
         // never throw from a hook
@@ -1210,7 +1280,8 @@ function cmdLabel(providerId, name, label) {
     setLabel(providerId, name, label);
     console.log(`Labeled ${providerId}/${name} as ${label}.`);
 }
-/** Enable/disable opt-in auto-switch, or show the current setting. */
+/** Enable/disable opt-in near-limit notifications (notify + suggest, never an
+ *  automatic switch), or show the current setting. */
 /** Rename a profile (move its config dir + carry active/label/mappings). */
 function cmdRename(providerId, from, to) {
     const n = requireProfile(providerId, from, "rename");
@@ -1254,23 +1325,7 @@ async function cmdReset(providerId, name) {
         die(`reset failed: ${r.reason ?? "unknown"}`);
     }
 }
-function cmdAutoswitch(providerId, providerExplicit, mode, flags = {}, value) {
-    // `autoswitch strategy [reset-first|rotation-first]` — global switch behaviour.
-    if (mode === "strategy") {
-        if (value === "reset-first" || value === "rotation-first") {
-            setSwitchStrategy(value);
-        }
-        else if (value !== undefined) {
-            die("usage: agent-switch autoswitch strategy [reset-first|rotation-first]");
-        }
-        if (flags.json) {
-            console.log(JSON.stringify({ strategy: readSwitchStrategy() }));
-        }
-        else {
-            console.log(`Auto-switch strategy: ${readSwitchStrategy()}.`);
-        }
-        return;
-    }
+function cmdAutoswitch(providerId, providerExplicit, mode, flags = {}) {
     const thresholdFlag = flags.threshold;
     const threshold = typeof thresholdFlag === "string" ? Number(thresholdFlag) : undefined;
     if (threshold !== undefined && (!Number.isFinite(threshold) || threshold < 1 || threshold > 100)) {
@@ -1299,22 +1354,12 @@ function cmdAutoswitch(providerId, providerExplicit, mode, flags = {}, value) {
             ...(tag !== undefined ? { tag } : {}),
         });
         const tagNote = cfg.tag === "all" ? "" : `, tag ${cfg.tag}`;
-        console.log(`Auto-switch for ${providerId} ${cfg.enabled ? "ON" : "OFF"} (threshold ${cfg.threshold}%${tagNote}).`);
+        console.log(`Near-limit notifications for ${providerId} ${cfg.enabled ? "ON" : "OFF"} (threshold ${cfg.threshold}%${tagNote}).`);
         if (cfg.enabled) {
-            // Usage-policy disclosure — restored deliberately. Automated rotation on
-            // quota signals pools separate subscriptions to route around per-account
-            // rate limits; a prior review found this can violate the provider's usage
-            // policy. Enabling is the user's decision, but the risk must be stated.
-            console.warn("⚠️  Usage-policy warning: quota-triggered rotation across accounts can violate\n" +
-                "   the providers' usage policies — it pools separate subscriptions to route around\n" +
-                "   per-account rate limits. An internal review unanimously recommended removing it;\n" +
-                "   it ships off-by-default anyway. See the README before enabling. (Per-context\n" +
-                "   profile switching — private / work / client — is unaffected; this applies only\n" +
-                "   to automated quota-driven rotation.)");
-            const strat = readSwitchStrategy();
-            console.log(`Strategy: ${strat}${strat === "reset-first" ? " (redeem a banked reset before switching, Codex)" : ""}.\n` +
-                `The daemon moves the active ${providerId} profile to the account with the most headroom once the\n` +
-                "active one hits the threshold. Run `agent-switch service start` so the daemon is watching.");
+            console.log(`Once the active ${providerId} profile hits the threshold, the daemon NOTIFIES you and SUGGESTS the\n` +
+                "account with the most headroom — it never switches automatically; switching stays a manual action.\n" +
+                "On Codex it redeems a banked reset first (and stays on the account) before suggesting a switch.\n" +
+                "Run `agent-switch service start` so the daemon is watching.");
         }
         return;
     }
@@ -1324,15 +1369,14 @@ function cmdAutoswitch(providerId, providerExplicit, mode, flags = {}, value) {
             console.log(JSON.stringify(readAutoSwitchAll()));
             return;
         }
-        console.log(`strategy: ${readSwitchStrategy()}`);
         for (const p of providerExplicit ? [providerId] : PROVIDER_IDS) {
             const cfg = readAutoSwitch(p);
             const tagNote = cfg.tag === "all" ? "" : `, tag ${cfg.tag}`;
-            console.log(`${p}: auto-switch ${cfg.enabled ? "ON" : "OFF"} (threshold ${cfg.threshold}%${tagNote}).`);
+            console.log(`${p}: near-limit notifications ${cfg.enabled ? "ON" : "OFF"} (threshold ${cfg.threshold}%${tagNote}).`);
         }
         return;
     }
-    die("usage: agent-switch autoswitch on|off|status|strategy [reset-first|rotation-first] [--provider P] [--threshold <1-100>] [--tag all|work|personal|other] [--json]");
+    die("usage: agent-switch autoswitch on|off|status [--provider P] [--threshold <1-100>] [--tag all|work|personal|other] [--json]");
 }
 /**
  * Enable/disable a provider's surfaces (cli / ui), or show the current setting.
@@ -1549,8 +1593,8 @@ async function cmdGui() {
     // Launch the tray/menubar GUI — downloads its prebuilt artifact from the
     // matching GitHub Release on first use, then caches it (see gui-launch.ts).
     try {
-        await launchGui();
-        console.log("Launched the agent-switch GUI.");
+        const result = await launchGui();
+        console.log(result === "already-running" ? "The agent-switch GUI is already running." : "Launched the agent-switch GUI.");
     }
     catch (err) {
         die(String(err?.message ?? err));
@@ -1623,10 +1667,65 @@ function cmdOpen(appId, name) {
 function cmdShellenv(shellArg) {
     console.log(shellenvScript(detectShell(shellArg)));
 }
+/** `agent-switch tooling` — ecosystem tool readout (agent-config, rtk, provider
+ *  CLIs). `--json` is the GUI IPC contract: the GUI renders this readout and
+ *  never shells out to detect on its own. */
+function cmdTooling(json = false) {
+    const tools = checkTooling();
+    if (json) {
+        console.log(JSON.stringify(tools, null, 2));
+        return;
+    }
+    console.log(`agent-switch tooling — platform ${process.platform}\n`);
+    for (const l of formatToolingLines(tools))
+        console.log(l);
+}
+/** `agent-switch tooling install|upgrade <id>` — run the tool's per-platform
+ *  install/upgrade command as a visible child process (the GUI runs this inside
+ *  its embedded terminal). Exit code = the child's exit code. */
+function cmdToolingAction(action, id) {
+    if (!id || !TOOL_IDS.includes(id)) {
+        die(`usage: agent-switch tooling ${action} <${TOOL_IDS.join("|")}>`);
+    }
+    process.exit(runToolAction(id, action));
+}
+/**
+ * `agent-switch usage history [--provider claude] [--profile <name>] [--json]`
+ * — the daemon-recorded usage-history ring per profile (same file the daemon
+ * appends: `<profileDir>/usage-history.json`). `--json` is the GUI contract:
+ * `[{ profile, samples: [{ at, windows }] }]`. Own-profile data only.
+ */
+function cmdUsageHistory(providerId, sub, flags = {}) {
+    if (sub !== "history")
+        die("usage: agent-switch usage history [--provider P] [--profile <name>] [--json]");
+    const profiles = typeof flags.profile === "string"
+        ? [requireProfile(providerId, flags.profile, "usage history --profile")]
+        : listProfiles(providerId);
+    if (profiles.length === 0)
+        die(`no ${providerId} profiles`);
+    const rows = profiles.map((p) => ({
+        profile: p,
+        samples: readHistory(path.join(profileDir(providerId, p), "usage-history.json")),
+    }));
+    if (flags.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    for (const r of rows) {
+        if (r.samples.length === 0) {
+            console.log(`${providerId}/${r.profile}: no usage history yet (the daemon records samples — agent-switch service start)`);
+            continue;
+        }
+        const first = r.samples[0].at;
+        const last = r.samples[r.samples.length - 1].at;
+        console.log(`${providerId}/${r.profile}: ${r.samples.length} sample${r.samples.length === 1 ? "" : "s"} (${first} → ${last})`);
+    }
+}
 function usage() {
     console.log(`agent-switch — switch accounts for Claude Code, Codex, and Antigravity (macOS · Linux · Windows)
 
 Provider defaults to claude; pass --provider codex|antigravity for the others.
+Run with no command to launch the tray/menubar GUI (single-instance).
 
   agent-switch add [--provider P] <name>       create a profile and log it in
   agent-switch import [--provider P] <name>    migrate the default install (no re-login)
@@ -1642,31 +1741,165 @@ Provider defaults to claude; pass --provider codex|antigravity for the others.
   agent-switch unmap [--provider P] [dir]      remove a directory mapping
   agent-switch mappings                        list directory mappings
   agent-switch share on|sync|off|status [--history] [--source <profile|default>] [--json]   (Claude)
+  agent-switch config export|import <profile>   config-only cross-machine bundle to stdout / from stdin (settings, keybindings, CLAUDE.md, skills/, commands/, agents/ — NEVER credentials; pipe export | gpg -c)
   agent-switch sessions [profile] [--recent N] [--json]   recent + live Claude sessions per profile (with context %)
   agent-switch hooks install|uninstall|status [profile]   manage lifecycle push hooks in Claude settings.json
   agent-switch alerts on|off|status [--threshold 80,95]   record context/usage crossings to the notification log (off by default)
   agent-switch compact <profile> [--clear] [--dry-run] [--force]   type /compact (or /clear) into the profile's managed tmux pane
   agent-switch takeover <id> --to <profile> [--from <profile>] [--keep-source] [--in-place] [--print-only] [--force]   move a session to another profile and resume it
+  agent-switch rebind [<account>] [--profile <p>]   |   rebind --restore [--profile <p>]   |   rebind --reset   switch a RUNNING profile's account (macOS; no <account> = interactive picker; --restore reverses; --reset re-enables after a circuit-breaker trip)
   agent-switch web <name>                      claude.ai in a persistent browser (Claude)
   agent-switch remove [--provider P] <name> [--force]   delete a profile
   agent-switch label [--provider P] <name> [Work|Personal|Other|none]   tag a profile
-  agent-switch autoswitch on|off|status [--provider P] [--threshold <1-100>]   per-provider auto-switch (default OFF)
+  agent-switch autoswitch on|off|status [--provider P] [--threshold <1-100>]   notify + suggest near a usage limit; never switches automatically (default OFF)
   agent-switch reset <profile> --provider codex                                redeem one banked Codex rate-limit reset
   agent-switch rename <old> <new> [--provider P]                               rename a profile (name & keep its tag)
   agent-switch providers enable|disable|status [--provider P] [--surface cli|ui]   enable/disable a provider (default: Claude + Codex)
-  agent-switch gui                             launch the tray/menubar GUI (bundled via npm)
+  agent-switch [gui]                           launch the tray/menubar GUI (the default with no command; won't start a second if one is running)
   agent-switch check-update [--json]           check GitHub Releases for a newer version
   agent-switch update                          self-update to the latest version (via npm)
   agent-switch apps                            list launchable GUI apps (macOS)
   agent-switch open <app> [profile]            launch a GUI app on a profile, isolated (macOS)
   agent-switch shellenv [--shell zsh|bash|fish|powershell]   shell integration
   agent-switch service run|start|stop|status|install|uninstall   background usage daemon
-  agent-switch notifications [clear] [--json]  recent notifications (auto-switches, fetch failures)
+  agent-switch notifications [clear] [--json]  recent notifications (usage-limit suggestions, fetch failures)
   agent-switch notify --kind K --title T --message M [--json]   record a notification event
   agent-switch os-notify [on|off|status] [--json]   daemon-side OS desktop notifications (default off)
   agent-switch uninstall [--force]             remove all agent-switch data + daemon
+  agent-switch usage history [--provider P] [--profile <name>] [--json]   daemon-recorded usage samples per profile
+  agent-switch tooling [--json]                ecosystem tool readout (agent-config, rtk, provider CLIs)
+  agent-switch tooling install|upgrade <tool>  install/upgrade an ecosystem tool (agent-config, rtk, claude, codex)
   agent-switch doctor                          per-OS, per-provider self-check`);
 }
+/**
+ * The interactive limit dialog (Phase 4) — `agent-switch rebind` with no account
+ * and no `--restore`. Gathers the OTHER claude profiles + their usage, pre-selects
+ * the best-headroom profile as a convenience, and prompts the user to pick. Only
+ * an explicit selection switches (via `rebind`); cancel stays put. The user
+ * interaction IS the compliance line — there is NO automatic switch anywhere in
+ * here. macOS-only for the actual switch; a non-TTY stdin prints the suggested
+ * command instead of hanging on a prompt no one can answer.
+ */
+async function rebindDialog(running) {
+    const others = listProfiles("claude").filter((n) => n !== running);
+    const candidates = [];
+    for (const n of others) {
+        // Same usage read path `status` uses (daemon cache when fresh, else the
+        // OAuth /usage endpoint); null when unreadable — the row shows no %.
+        candidates.push({ name: n, snapshot: await claudeSnapshot(n), label: labelFor("claude", n) });
+    }
+    const dialog = buildRebindDialog(candidates, running);
+    const rows = selectableRows(dialog);
+    if (rows.length === 0) {
+        die(`no other claude profile to rebind "${running}" to — add one with \`agent-switch add <name>\`.`);
+    }
+    // Non-interactive stdin: never hang. Print the pre-selected profile + the exact
+    // command that performs the switch, then return (no switch — the user has to run it).
+    if (!process.stdin.isTTY) {
+        const sug = dialog.suggestedProfile;
+        if (sug) {
+            console.error(`Suggested profile (most headroom): ${sug}`);
+            console.error(`Switch "${running}" to it with:  agent-switch rebind ${sug} --profile ${running}`);
+        }
+        else {
+            console.error(`No usage data to pre-select a profile. Switch with:  agent-switch rebind <account> --profile ${running}`);
+        }
+        return;
+    }
+    // The actual switch is macOS-only (the Linux/Windows credential backend is
+    // unproven — spike R0.1). Refuse before prompting rather than after a pick.
+    if (process.platform !== "darwin") {
+        die("rebind is macOS-only for now (the Linux/Windows credential backend is unproven — spike R0.1).");
+    }
+    console.log(`Rebind "${running}" to which account? A running Claude session adopts it on its next message.`);
+    rows.forEach((r, i) => {
+        const marker = r.profile === dialog.suggestedProfile ? "  ← suggested (most headroom)" : "";
+        const label = r.label ? ` [${r.label}]` : "";
+        const util = r.maxUtil === null ? "usage n/a" : `${r.maxUtil}% used`;
+        console.log(`  ${i + 1}) ${(r.profile + label).padEnd(24)} ${util}${marker}`);
+    });
+    const enterHint = dialog.suggestedProfile ?? "(no suggestion)";
+    console.log(`  [enter] = ${enterHint}   ·   q = cancel (stay on "${running}")`);
+    const SIGINT = "\u0003"; // sentinel distinct from empty input (empty = accept the suggestion)
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+        rl.on("SIGINT", () => resolve(SIGINT)); // Ctrl-C -> cancel, no switch
+        rl.question("> ", (a) => resolve(a));
+    });
+    rl.close();
+    if (answer === SIGINT) {
+        console.log(`\nStayed on "${running}" — no switch.`);
+        return;
+    }
+    const choice = resolveRebindChoice(answer, dialog);
+    if (choice.kind === "cancel") {
+        console.log(`Stayed on "${running}" — no switch.`);
+        return;
+    }
+    if (choice.kind === "invalid") {
+        console.log(`No valid selection — stayed on "${running}".`);
+        return;
+    }
+    try {
+        const r = await rebind({ account: choice.profile, profile: running });
+        console.log(r.uxNote);
+    }
+    catch (e) {
+        die(e.message);
+    }
+}
+/**
+ * `agent-switch rebind <account> [--profile <p>]` — point a RUNNING profile's
+ * credential store at another account, so a live Claude session adopts it on its
+ * next message (macOS; the user-interaction switch, ADR-003). `--restore` reverses
+ * it. With NO account and NO `--restore`, opens the interactive limit dialog
+ * ({@link rebindDialog}). Claude only; the target + running profiles must be logged in.
+ */
+async function cmdRebind(providerId, providerExplicit, account, flags) {
+    if (providerExplicit && providerId !== "claude")
+        die(`rebind supports claude only (not ${providerId})`);
+    const profile = typeof flags.profile === "string" ? flags.profile : activeFor("claude") ?? undefined;
+    if (flags.reset) {
+        // Kill-switch reset (ADR-003): clear `disabled` + the failure counter so a
+        // circuit-breaker trip (or a manual disable) no longer refuses rebind.
+        resetRebindKillSwitch();
+        console.log("rebind re-enabled — circuit-breaker cleared (disabled=false, consecutiveFailures=0).");
+        return;
+    }
+    if (flags.restore) {
+        if (!profile)
+            die("usage: agent-switch rebind --restore [--profile <p>] — no active claude profile to restore");
+        requireProfile("claude", profile, "rebind --restore --profile");
+        try {
+            const r = await restoreRebind({ profile });
+            console.log(`Restored "${r.restoredProfile}" to its own account (was rebound to "${r.wasBoundTo}").`);
+        }
+        catch (e) {
+            die(e.message);
+        }
+        return;
+    }
+    if (!account) {
+        // No account + no --restore → the interactive limit dialog (Phase 4). The
+        // switch is user-interaction-gated: the picker pre-selects the best-headroom
+        // profile as a convenience, but only an explicit pick switches.
+        if (!profile)
+            die("no running claude profile — pass --profile <name> or set one active with `asw <name>`.");
+        requireProfile("claude", profile, "rebind --profile");
+        return rebindDialog(profile);
+    }
+    if (!profile)
+        die("no running claude profile — pass --profile <name> or set one active with `asw <name>`.");
+    requireProfile("claude", account, "rebind");
+    requireProfile("claude", profile, "rebind --profile");
+    try {
+        const r = await rebind({ account, profile });
+        console.log(r.uxNote);
+    }
+    catch (e) {
+        die(e.message);
+    }
+}
 // ---------- main -------------------------------------------------------------
 async function main() {
     const argv = process.argv.slice(2);
@@ -1681,7 +1914,9 @@ async function main() {
     // profiles) skip it.
     if (cmd === "__hook-event")
         return cmdHookEvent(); // internal, silent, no migration
-    if (cmd && !["help", "--help", "-h", "shellenv"].includes(cmd)) {
+    // A bare `agent-switch` (no command) launches the GUI, which reads profiles —
+    // so it runs the migration too. Only pure help / shellenv skip it.
+    if (cmd === undefined || !["help", "--help", "-h", "shellenv"].includes(cmd)) {
         const moved = migrateLegacyLayout();
         if (moved.length > 0) {
             // stderr, not stdout: `dir` is machine-consumed by the shell wrapper
@@ -1696,7 +1931,7 @@ async function main() {
         case "use": return cmdUse(providerId, positional[0]);
         case "deactivate": return cmdDeactivate(providerId);
         case "label": return cmdLabel(providerId, positional[0], positional[1]);
-        case "autoswitch": return cmdAutoswitch(providerId, providerExplicit, positional[0], flags, positional[1]);
+        case "autoswitch": return cmdAutoswitch(providerId, providerExplicit, positional[0], flags);
         case "reset": return cmdReset(providerId, positional[0]);
         case "rename": return cmdRename(providerId, positional[0], positional[1]);
         case "providers": return cmdProviders(providerId, providerExplicit, positional[0], flags);
@@ -1726,6 +1961,7 @@ async function main() {
         case "unmap": return cmdUnmap(providerExplicit ? providerId : undefined, positional[0]);
         case "mappings": return cmdMappings();
         case "share": return cmdShare(positional[0], rest.slice(1));
+        case "config": return cmdConfig(positional[0], positional[1], flags);
         case "sessions":
             if (positional[0] === "rm")
                 return cmdSessionsRm(providerId, providerExplicit, positional[1], flags);
@@ -1738,18 +1974,32 @@ async function main() {
         case "alerts": return cmdAlerts(positional[0], flags);
         case "compact": return cmdCompact(providerId, positional[0], flags);
         case "takeover": return cmdTakeover(providerId, providerExplicit, positional[0], flags);
+        case "rebind": return cmdRebind(providerId, providerExplicit, positional[0], flags);
         case "web": return cmdWeb(positional[0]);
         case "remove":
         case "rm": return cmdRemove(providerId, positional[0], !!flags.force);
         case "shellenv": return cmdShellenv(flags.shell ?? positional[0]);
         case "service": return cmdService(positional[0]);
+        case "usage": return cmdUsageHistory(providerId, positional[0], flags);
+        case "tooling":
+            if (positional[0] === "install" || positional[0] === "upgrade") {
+                return cmdToolingAction(positional[0], positional[1]);
+            }
+            if (positional[0] !== undefined) {
+                die(`usage: agent-switch tooling [install|upgrade <${TOOL_IDS.join("|")}>] [--json]`);
+            }
+            return cmdTooling(!!flags.json);
         case "doctor": return process.exit(await runDoctor());
         case "help":
         case "--help":
         case "-h": return usage();
+        // A bare `agent-switch` (no command) launches the GUI; an unknown command
+        // still prints usage and exits non-zero.
         default:
+            if (cmd === undefined)
+                return cmdGui();
             usage();
-            process.exit(cmd ? 1 : 0);
+            process.exit(1);
     }
 }
 main().catch((err) => die(String(err?.message ?? err)));

package/dist/keychain.js

@@ -48,6 +48,20 @@ export function deletePassword(service) {
         return false;
     return (security(["delete-generic-password", "-a", os.userInfo().username, "-s", service]) !== null);
 }
+/**
+ * Upsert a generic password entry (`-U` overwrites an existing value). Returns
+ * true on success. This is the ONE credential-store WRITE in agent-switch — used
+ * ONLY by `src/rebind.ts` under Claude Code's lock (ADR-003). Elsewhere the
+ * credential store stays read-only.
+ *
+ * Note: the value is passed on argv (as `security` requires with `-w`), so it is
+ * briefly visible to `ps` — the same trade-off Claude Code's own tooling makes.
+ */
+export function addPassword(service, value) {
+    if (!isMac())
+        return false;
+    return security(["add-generic-password", "-U", "-a", os.userInfo().username, "-s", service, "-w", value]) !== null;
+}
 /** The live credential of the default ~/.claude install (keychain, macOS). */
 export function readDefaultCredential() {
     return getPassword(DEFAULT_SERVICE);

package/dist/notifications.js

@@ -33,11 +33,16 @@ function writeNotifications(list, file) {
  * Append an event (kept newest-last). Deduplicates a byte-identical
  * kind+title+message against the most recent entry within DEDUP_WINDOW_MS.
  * Returns the created notification, or `null` when it was deduplicated.
+ *
+ * `dedupe: false` skips that collapse — for session-awareness events (Claude
+ * finished / is waiting) where each occurrence is a distinct moment the user
+ * wants surfaced, so a solo session's repeated turns are never swallowed.
  */
-export function appendNotification(event, now = Date.now(), file = NOTIFICATIONS_FILE) {
+export function appendNotification(event, now = Date.now(), file = NOTIFICATIONS_FILE, dedupe = true) {
     const list = readNotifications(file);
     const last = list[list.length - 1];
-    if (last &&
+    if (dedupe &&
+        last &&
         last.kind === event.kind &&
         last.title === event.title &&
         last.message === event.message &&

package/dist/profiles.js

@@ -13,7 +13,6 @@ export function isProfileLabel(v) {
     return typeof v === "string" && PROFILE_LABELS.includes(v);
 }
 export const DEFAULT_AUTOSWITCH = { enabled: false, threshold: 95, tag: "all" };
-export const DEFAULT_SWITCH_STRATEGY = "reset-first";
 /**
  * Providers enabled out of the box. Everything else is available but off by
  * default — the user opts it in from the Providers settings tab. A provider that
@@ -21,6 +20,7 @@ export const DEFAULT_SWITCH_STRATEGY = "reset-first";
  * upgrading never hides an account the user already set up.
  */
 export const PROVIDERS_ON_BY_DEFAULT = ["claude", "codex"];
+export const DEFAULT_REBIND_STATE = { disabled: false, consecutiveFailures: 0 };
 function emptyActive() {
     return { claude: null, codex: null, antigravity: null };
 }
@@ -155,6 +155,11 @@ function normalizeBinaryPaths(raw) {
             out[p] = r[p];
     return out;
 }
+function normalizeRebindState(raw) {
+    const r = (raw ?? {});
+    const consecutiveFailures = typeof r.consecutiveFailures === "number" && r.consecutiveFailures >= 0 ? Math.floor(r.consecutiveFailures) : 0;
+    return { disabled: r.disabled === true, consecutiveFailures };
+}
 export function readState() {
     try {
         const raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
@@ -162,29 +167,21 @@ export function readState() {
         const autoSwitch = normalizeAutoSwitchMap(raw?.autoSwitch);
         const providers = normalizeProvidersMap(raw?.providers);
         const binaryPaths = normalizeBinaryPaths(raw?.binaryPaths);
-        const switchStrategy = raw?.switchStrategy === "rotation-first" ? "rotation-first" : DEFAULT_SWITCH_STRATEGY;
         const osNotifications = raw?.osNotifications === true;
+        const rebind = normalizeRebindState(raw?.rebind);
         // v1: { active: "<name>" } — a single Claude profile.
         if (typeof raw?.active === "string") {
-            return { active: { ...emptyActive(), claude: raw.active }, labels, autoSwitch, providers, binaryPaths, switchStrategy, osNotifications };
+            return { active: { ...emptyActive(), claude: raw.active }, labels, autoSwitch, providers, binaryPaths, osNotifications, rebind };
         }
         if (raw?.active && typeof raw.active === "object") {
-            return { active: { ...emptyActive(), ...raw.active }, labels, autoSwitch, providers, binaryPaths, switchStrategy, osNotifications };
+            return { active: { ...emptyActive(), ...raw.active }, labels, autoSwitch, providers, binaryPaths, osNotifications, rebind };
         }
-        return { active: emptyActive(), labels, autoSwitch, providers, binaryPaths, switchStrategy, osNotifications };
+        return { active: emptyActive(), labels, autoSwitch, providers, binaryPaths, osNotifications, rebind };
     }
     catch {
         /* absent / unparsable → default */
     }
-    return { active: emptyActive(), labels: {}, autoSwitch: emptyAutoSwitch(), providers: emptyProviders(), binaryPaths: {}, switchStrategy: DEFAULT_SWITCH_STRATEGY, osNotifications: false };
-}
-export function readSwitchStrategy() {
-    return readState().switchStrategy;
-}
-export function setSwitchStrategy(strategy) {
-    const state = readState();
-    state.switchStrategy = strategy;
-    writeState(state);
+    return { active: emptyActive(), labels: {}, autoSwitch: emptyAutoSwitch(), providers: emptyProviders(), binaryPaths: {}, osNotifications: false, rebind: { ...DEFAULT_REBIND_STATE } };
 }
 export function readOsNotifications() {
     return readState().osNotifications;
@@ -194,6 +191,21 @@ export function setOsNotifications(on) {
     state.osNotifications = on;
     writeState(state);
 }
+// ---------- rebind kill-switch / circuit-breaker (ADR-003) ----------
+/** Current rollback/circuit-breaker state for the `rebind` write path. */
+export function readRebindKillSwitch() {
+    return readState().rebind;
+}
+/** Persist the rebind kill-switch state (breaker counter + disabled flag). */
+export function writeRebindKillSwitch(next) {
+    const state = readState();
+    state.rebind = normalizeRebindState(next);
+    writeState(state);
+}
+/** Re-enable `rebind`: clear `disabled` + reset the failure counter (`--reset`). */
+export function resetRebindKillSwitch() {
+    writeRebindKillSwitch({ ...DEFAULT_REBIND_STATE });
+}
 export function writeState(state) {
     ensureRoot();
     fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });