@event4u/agent-switch 1.7.0 → 2.1.0

package/dist/index.js

@@ -13,26 +13,33 @@
  */
 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, readGuard, setGuard, 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 } from "./history.js";
+import { TOOL_IDS, checkTooling, formatToolNotes, formatToolingLines, runToolAction, toolNotesRefusal, toolReleaseRepo, } from "./tooling.js";
+import { releaseNoteBlocks } from "./release-notes.js";
+import { readHistory, recordHistorySample } from "./history.js";
 import { launchGui } from "./gui-launch.js";
-import { checkForUpdate, selfUpdate } from "./updates.js";
+import { GUARD_POLICIES, GUARD_REFUSED_EXIT, OVERRIDE_ENV, guardVerdict, inspectLoad, isGuardPolicy, overrideFromEnv, renderGuardMessage, } from "./single-load.js";
+import { checkForUpdate, fetchReleases, releasesNewerThan, 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";
-import { assertValidSessionId, cleanupForkVehicle, codexSessionCommand, deleteSession, listSessions, listCodexSessions, locateSession, locateCodexSession, markLive, restoreSession, sharedHistory, sweepTrash, transferSession, transferCodexSession, trashedSessionExists, } from "./sessions.js";
+import { assertValidSessionId, cleanupForkVehicle, codexSessionCommand, deleteSession, detectRunningClaudeProfile, listSessions, listCodexSessions, locateSession, locateCodexSession, markLive, restoreSession, sharedHistory, sweepTrash, transferSession, transferCodexSession, trashedSessionExists, } from "./sessions.js";
 import { isFresh, readDaemonState, readPid, PIDFILE, processAlive } from "./daemon.js";
 import { cmdService, serviceUninstall } from "./service.js";
 import { readContext, turnInFlight } from "./telemetry.js";
@@ -47,6 +54,46 @@ import { currentManagedSession, currentTmuxSessionName, newSessionArgs, readTmux
 const credentials = credentialStore();
 const CLAUDE_HOME = provider("claude").defaultConfigDir(); // ~/.claude
 const CLAUDE_JSON = path.join(HOME, ".claude.json");
+/** Same-provider profiles that carry no live session — the concrete
+ *  alternatives a refusal names, so the user can act on it without first
+ *  running `list` themselves. */
+function freeProfiles(providerId, exclude) {
+    return listProfiles(providerId).filter((n) => n !== exclude && liveSessionPids(configDir(providerId, n)).length === 0);
+}
+function checkSingleLoad(providerId, name, opts = {}) {
+    const p = provider(providerId);
+    // Early-out before touching the filesystem: `dir --guard` runs on every
+    // interactive start, so a disabled guard (or a provider with no live-session
+    // signal at all) must cost a state read and nothing more.
+    const policy = readGuard();
+    if (policy === "off" || !p.hasLiveSessionSignal) {
+        return { verdict: "allow", inspection: { sessions: [], loaded: false, nested: false }, message: null };
+    }
+    const cfg = configDir(providerId, name);
+    const inspection = inspectLoad(cfg, p.envVar);
+    const verdict = guardVerdict({
+        policy,
+        inspection,
+        overridden: opts.forced === true || overrideFromEnv(),
+        detectable: p.hasLiveSessionSignal,
+    });
+    return {
+        verdict,
+        inspection,
+        message: verdict === "allow"
+            ? null
+            : renderGuardMessage({
+                profile: name,
+                binary: p.binary,
+                verdict,
+                inspection,
+                offerForceFlag: opts.offerForceFlag === true,
+                context: opts.context ?? "start",
+                // Only worth computing on a message we are actually going to print.
+                alternatives: verdict === "refuse" ? freeProfiles(providerId, name) : [],
+            }),
+    };
+}
 // ---------- launcher ---------------------------------------------------------
 function launch(p, name, args) {
     const home = configDir(p.id, name);
@@ -160,6 +207,14 @@ function cmdUse(providerId, name) {
     const id = identity(providerId, n);
     console.log(`Active ${providerId} profile: ${n}${id ? ` (${id})` : ""}`);
     console.log(`New \`${provider(providerId).binary}\` sessions use this profile. Running sessions are unaffected.`);
+    // `use` loads nothing — it states an intent — so it NEVER blocks. But it is
+    // the cheapest possible moment to tell the user that the profile they just
+    // pointed at is already busy, before they type the command that gets refused.
+    const check = checkSingleLoad(providerId, n, { context: "use" });
+    if (check.message) {
+        console.log("");
+        console.warn(check.message);
+    }
 }
 function cmdDeactivate(providerId) {
     const active = activeFor(providerId);
@@ -174,9 +229,18 @@ function cmdDeactivate(providerId) {
 function cmdRun(providerId, name, args) {
     const n = requireProfile(providerId, name, "run");
     const p = provider(providerId);
-    // `--tmux` is an agent-switch flag, not a passthrough flag — strip it.
+    // `--tmux` and `--force` are agent-switch flags, not passthrough flags — strip
+    // them before the rest reaches the provider binary.
     const wantTmux = args.includes("--tmux");
-    const passthrough = args.filter((a) => a !== "--tmux");
+    const forced = args.includes("--force");
+    const passthrough = args.filter((a) => a !== "--tmux" && a !== "--force");
+    // agent-switch spawns the binary itself here, so this is the strongest
+    // enforcement point: refuse before anything is launched.
+    const guard = checkSingleLoad(providerId, n, { forced, offerForceFlag: true });
+    if (guard.message)
+        console.error(guard.verdict === "refuse" ? `error: ${guard.message}` : guard.message);
+    if (guard.verdict === "refuse")
+        process.exit(GUARD_REFUSED_EXIT);
     if (wantTmux) {
         if (!tmuxAvailable()) {
             console.log("(--tmux unavailable — tmux not found or Windows; running normally.)");
@@ -199,8 +263,12 @@ function printProfileLine(providerId, name, showLive) {
     let live = "";
     if (showLive && providerId === "claude") {
         const pids = liveSessionPids(configDir("claude", name));
-        if (pids.length > 0)
-            live = `  [${pids.length} live session${pids.length > 1 ? "s" : ""}]`;
+        // More than one session on one account is the state the single-load guard
+        // exists to prevent, so it is marked rather than blending into the count.
+        if (pids.length > 1)
+            live = `  ⚠️  [loaded ${pids.length}× — ${pids.length} live sessions]`;
+        else if (pids.length === 1)
+            live = "  [1 live session]";
     }
     console.log(`${mark} ${name.padEnd(16)} ${id}${live}`);
 }
@@ -272,8 +340,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);
@@ -295,6 +362,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 }
@@ -328,8 +401,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;
@@ -353,17 +425,37 @@ async function cmdStatus(providerId, name, json = false) {
         }
     }
 }
-function cmdDir(providerId) {
-    // Precedence: directory mapping (nearest ancestor of CWD) > active-for-provider.
+/**
+ * Resolve which profile a shell wrapper should load: directory mapping (nearest
+ * ancestor of CWD) > active-for-provider. Empty output → the wrapper falls back
+ * to the default config dir.
+ *
+ * With `--guard`, stdout is unchanged (the wrapper still reads the path from
+ * it) and the guard speaks on STDERR, exiting {@link GUARD_REFUSED_EXIT} on a
+ * refusal. Splitting the streams is what lets one command both feed the wrapper
+ * and talk to the human; a distinct exit code is what lets the wrapper block on
+ * a refusal without ever blocking on a missing or older `agent-switch`.
+ */
+function cmdDir(providerId, guarded = false) {
     const mapped = resolveMapping(process.cwd(), providerId);
-    if (mapped && profileExists(providerId, mapped.name)) {
-        console.log(configDir(providerId, mapped.name));
+    const name = mapped && profileExists(providerId, mapped.name)
+        ? mapped.name
+        : (() => {
+            const active = activeFor(providerId);
+            return active && profileExists(providerId, active) ? active : null;
+        })();
+    if (!name)
         return;
-    }
-    const active = activeFor(providerId);
-    if (active && profileExists(providerId, active))
-        console.log(configDir(providerId, active));
-    // Empty output -> shell wrapper falls back to the default config dir.
+    console.log(configDir(providerId, name));
+    if (!guarded)
+        return;
+    // A wrapper cannot pass `--force` (it would reach the provider binary), so
+    // only the env override is offered here.
+    const guard = checkSingleLoad(providerId, name, { offerForceFlag: false });
+    if (guard.message)
+        console.error(`agent-switch: ${guard.message}`);
+    if (guard.verdict === "refuse")
+        process.exit(GUARD_REFUSED_EXIT);
 }
 function cmdMap(providerId, name, dir) {
     const n = requireProfile(providerId, name, `map [--provider ${providerId}] <profile> [dir]`);
@@ -451,6 +543,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) {
@@ -660,6 +801,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
@@ -1212,7 +1363,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");
@@ -1256,23 +1408,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)) {
@@ -1301,22 +1437,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;
     }
@@ -1326,15 +1452,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.
@@ -1551,8 +1676,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));
@@ -1622,6 +1747,63 @@ function cmdOpen(appId, name) {
         console.log("is saved to this profile. Quit other windows of this app before signing in.");
     }
 }
+/**
+ * `agent-switch guard [block|warn|off]` — read or set the single-load policy.
+ * The bare form also reports what is loaded RIGHT NOW, because "what is my
+ * policy" and "is anything currently doubled" are the same question in practice.
+ */
+function cmdGuard(value, json = false) {
+    if (value !== undefined) {
+        if (!isGuardPolicy(value)) {
+            die(`unknown guard policy "${value}" (choose: ${GUARD_POLICIES.join(", ")})`);
+        }
+        setGuard(value);
+    }
+    const policy = readGuard();
+    // Every profile of every provider that can report a live session.
+    const rows = [];
+    for (const pid of PROVIDER_IDS) {
+        if (!provider(pid).hasLiveSessionSignal)
+            continue;
+        for (const n of listProfiles(pid)) {
+            const count = liveSessionPids(configDir(pid, n)).length;
+            if (count > 0)
+                rows.push({ provider: pid, name: n, sessions: count });
+        }
+    }
+    if (json) {
+        console.log(JSON.stringify({ policy, loaded: rows }, null, 2));
+        return;
+    }
+    const explain = {
+        block: "a second session on a profile that is already loaded is refused",
+        warn: "a second session is reported, then allowed",
+        off: "no check at all",
+    };
+    console.log(`Single-load guard: ${policy} — ${explain[policy]}.`);
+    if (rows.length === 0) {
+        console.log("No profile is currently loaded by a live session.");
+    }
+    else {
+        console.log("");
+        for (const r of rows) {
+            const doubled = r.sessions > 1;
+            const mark = doubled ? "⚠️ " : "  ";
+            const detail = doubled ? `loaded ${r.sessions}× — this is what the guard exists to prevent` : "1 live session";
+            console.log(`${mark} ${`${r.provider}/${r.name}`.padEnd(24)} ${detail}`);
+        }
+    }
+    const inert = PROVIDER_IDS.filter((pid) => !provider(pid).hasLiveSessionSignal && listProfiles(pid).length > 0);
+    if (inert.length > 0) {
+        console.log("");
+        console.log(`Not covered: ${inert.join(", ")} — these CLIs do not register a running session on disk,`);
+        console.log("so agent-switch has no way to tell a second load from a first.");
+    }
+    if (policy !== "off") {
+        console.log("");
+        console.log(`Override once: ${OVERRIDE_ENV}=1 <binary>    ·    Change: agent-switch guard <${GUARD_POLICIES.join("|")}>`);
+    }
+}
 function cmdShellenv(shellArg) {
     console.log(shellenvScript(detectShell(shellArg)));
 }
@@ -1637,6 +1819,61 @@ function cmdTooling(json = false) {
     console.log(`agent-switch tooling — platform ${process.platform}\n`);
     for (const l of formatToolingLines(tools))
         console.log(l);
+    // This readout stays offline by contract; the notes command is where the
+    // network lives, so point at it rather than fetching here.
+    console.log("\nWhat changed in a release: `agent-switch tooling notes [<tool>]`");
+}
+/**
+ * `agent-switch tooling notes [<tool>] [--latest] [--json]` — read what an
+ * ecosystem update actually contains, in the terminal.
+ *
+ * Deliberately a SEPARATE subcommand: `tooling` (no args) is a local, offline
+ * readout the GUI consumes over `--json`, and that contract stays. This one
+ * fetches, and says so in the help.
+ *
+ * Default tool is `agent-config` (the one agent-switch announces updates for).
+ * Shown: every release newer than the installed version, newest first — so
+ * someone several versions behind reads all of them, not just the last. Up to
+ * date or not installed → the newest release, so the command always answers.
+ * A tool with no verified release source gets a named refusal, never an
+ * invented source.
+ */
+async function cmdToolingNotes(id, flags) {
+    const toolId = (id ?? "agent-config");
+    if (!TOOL_IDS.includes(toolId)) {
+        die(`usage: agent-switch tooling notes [<${TOOL_IDS.join("|")}>] [--latest] [--json]`);
+    }
+    const repo = toolReleaseRepo(toolId);
+    if (!repo)
+        die(toolNotesRefusal(toolId));
+    const installed = checkTooling({ ids: [toolId] })[0]?.version ?? null;
+    let releases = [];
+    let failure = null;
+    try {
+        releases = await fetchReleases(repo);
+    }
+    catch (e) {
+        failure = e instanceof Error ? e.message : String(e);
+    }
+    const latest = releases[0]?.tag ?? null;
+    // Unread first; when there is nothing unread (up to date, not installed, or
+    // the list is empty) fall back to the newest release so the command answers.
+    const unread = installed ? releasesNewerThan(releases, installed) : [];
+    const selected = unread.length > 0 ? unread : releases.slice(0, 1);
+    const view = { id: toolId, installed, latest, releases: flags.latest ? selected.slice(0, 1) : selected };
+    if (flags.json) {
+        console.log(JSON.stringify({
+            ...view,
+            repo,
+            error: failure,
+            releases: view.releases.map((r) => ({ ...r, blocks: releaseNoteBlocks(r.notes) })),
+        }, null, 2));
+        return;
+    }
+    for (const line of formatToolNotes(view))
+        console.log(line);
+    if (failure)
+        console.log(`\nCould not reach the release source (${failure}) — showing what was available.`);
 }
 /** `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
@@ -1683,6 +1920,7 @@ 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)
@@ -1693,39 +1931,191 @@ Provider defaults to claude; pass --provider codex|antigravity for the others.
   agent-switch status [--provider P] [name] [--json]   identity (+ Claude usage); --json = active only
   agent-switch current [--provider P]          show the active profile(s)
   agent-switch whoami [--provider P] [name]    show a profile's account identity
-  agent-switch dir [--provider P]              resolve profile for CWD (mapping > active)
+  agent-switch dir [--provider P] [--guard]    resolve profile for CWD (mapping > active)
+  agent-switch guard [block|warn|off]          one profile, one live session (default block)
   agent-switch map [--provider P] <name> [dir] map a directory to a profile
   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 tooling notes [<tool>] [--latest] [--json]   read an ecosystem tool's release notes (default agent-config; fetches from GitHub)
   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})`);
+    // Resolve which running profile rebind targets: explicit --profile wins; else
+    // prefer the profile that actually has a LIVE session (rebind's whole point is
+    // the running session, which may not be the "active" default-for-new-processes
+    // profile). Only auto-target when exactly one profile is running — a credential
+    // write must never guess across ambiguity — otherwise keep the active fallback.
+    const explicitProfile = typeof flags.profile === "string" ? flags.profile : undefined;
+    let profile = explicitProfile ?? activeFor("claude") ?? undefined;
+    if (!explicitProfile) {
+        const running = detectRunningClaudeProfile(listProfiles("claude"), (p) => configDir("claude", p));
+        if (running.kind === "single") {
+            if (running.profile !== profile) {
+                console.log(`Auto-detected the running claude profile "${running.profile}" (its session is live) — targeting it. Pass --profile to override.`);
+            }
+            profile = running.profile;
+        }
+        else if (running.kind === "ambiguous") {
+            console.log(`Multiple running claude profiles (${running.profiles.join(", ")}) — ` +
+                `${profile ? `using the active profile "${profile}"` : "no active default"}; pass --profile <name> to target a specific one.`);
+        }
+    }
+    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);
@@ -1740,12 +2130,16 @@ 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
-            // (`dir="$(agent-switch dir 2>/dev/null)"`), so a status line on stdout
-            // would pollute the resolved config path.
+            // (`dir="$(agent-switch dir --provider … --guard)"`), so a status line on
+            // stdout would pollute the resolved config path. Since the single-load
+            // guard needs to speak, the wrapper no longer discards stderr — this
+            // one-time migration note is now visible to the user, which is right.
             console.error(`Migrated ${moved.length} Claude profile(s) to the new layout: ${moved.join(", ")}.`);
         }
     }
@@ -1755,7 +2149,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);
@@ -1780,11 +2174,13 @@ async function main() {
         case "status": return cmdStatus(providerExplicit ? providerId : undefined, positional[0], !!flags.json);
         case "current": return cmdCurrent(providerExplicit ? providerId : undefined);
         case "whoami": return cmdWhoami(providerId, positional[0]);
-        case "dir": return cmdDir(providerId);
+        case "dir": return cmdDir(providerId, !!flags.guard);
+        case "guard": return cmdGuard(positional[0], !!flags.json);
         case "map": return cmdMap(providerId, positional[0], positional[1]);
         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);
@@ -1797,6 +2193,7 @@ 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);
@@ -1807,17 +2204,23 @@ async function main() {
             if (positional[0] === "install" || positional[0] === "upgrade") {
                 return cmdToolingAction(positional[0], positional[1]);
             }
+            if (positional[0] === "notes")
+                return cmdToolingNotes(positional[1], flags);
             if (positional[0] !== undefined) {
-                die(`usage: agent-switch tooling [install|upgrade <${TOOL_IDS.join("|")}>] [--json]`);
+                die(`usage: agent-switch tooling [install|upgrade <${TOOL_IDS.join("|")}>] [notes [<tool>]] [--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)));