@event4u/agent-switch 2.0.0 → 2.1.0

package/README.md

@@ -29,6 +29,39 @@ Most naive switchers snapshot the macOS Keychain entry (`Claude Code-credentials
 
 The same restraint governs the whole tool: no proxy, no traffic interception, no fingerprinting, no prompt rewriting — see [NON-GOALS.md](NON-GOALS.md) for the explicit list and the alternatives this ecosystem offers instead.
 
+## One profile, one session
+
+Because `agent-switch use` sets a **global** pointer that every shell re-reads,
+nothing used to stop two terminals from starting `claude` on the same account —
+sharing one set of rate limits and both refreshing one rotating OAuth token,
+while each terminal looked like a separate account.
+
+The single-load guard refuses that second start and says which session already
+holds the profile and which accounts are free:
+
+```
+$ claude
+agent-switch: profile "work" is already loaded by a running claude session.
+
+  pid 41234  started 12m ago  ~/projects/foo
+
+Two sessions on one account share its rate limits, and both refresh the
+same rotating OAuth token.
+
+Ways forward:
+  agent-switch use privat                switch to a free account — also free: event4u
+  AGENT_SWITCH_ALLOW_DUPLICATE=1 claude  start it anyway, this once
+  agent-switch guard warn                warn instead of refusing, from now on
+  agent-switch guard off                 turn the guard off entirely
+```
+
+It never gets in the way where it has no business being: a `claude` started
+*inside* a running session is a child, not a duplicate; a crashed session leaves
+nothing behind that can lock you out; and if `agent-switch` itself is missing or
+broken, the wrapper falls straight through to the real binary. Set the policy
+with `agent-switch guard <block|warn|off>` — see the
+[CLI reference](https://event4u-app.github.io/agent-switch/reference/cli/#single-load-guard).
+
 ## Install
 
 **npm / npx** (any OS — needs Node ≥ 20). The package is published as

package/dist/config-transfer.js

@@ -36,9 +36,19 @@ const DENY_SET = new Set([".claude.json", ".credentials.json", "plugins", "sessi
 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.";
+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. " +
+    "To move an account to another machine: `agent-switch config export` (config-only) → `config import` on the target → `agent-switch <profile>` and re-run `claude` to log in there — a fresh login is machine-specific 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. */
+ *  surface it via `die`; kept here because it is a config-transfer policy.
+ *
+ *  Re-affirmed 2026-07-29: an AI-council threat-modelled review of whether to
+ *  build `--full` (with mandatory encryption) concluded KEEP IT REFUSED — even
+ *  AES-256-GCM + Argon2id cannot fix the threat-model shift (an exportable
+ *  credential bundle is a persistent cloud-sync / malware / phishing exfil
+ *  vector), the 30-second `config import → auth login` path covers the real
+ *  need, and industry practice (aws / gh / kubectl) never exports credentials.
+ *  Reversing this requires the repo owner's explicit sign-off, not agent
+ *  convergence. */
 export function assertNotFull(full) {
     if (full)
         throw new Error(FULL_REFUSAL);

package/dist/doctor.js

@@ -7,11 +7,11 @@
  */
 import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
-import { ROOT, activeFor, configDir, listProfiles, profileExists } from "./profiles.js";
+import { ROOT, activeFor, configDir, listProfiles, profileExists, readGuard } from "./profiles.js";
 import { allProviders } from "./providers.js";
 import { credentialStore } from "./credentials.js";
 import { sharedLinkHealth } from "./share.js";
-import { checkAuth } from "./api.js";
+import { checkAuth, liveSessionPids } from "./api.js";
 import { checkTooling, doctorToolingLine } from "./tooling.js";
 const OK = "✅";
 const WARN = "⚠️";
@@ -113,6 +113,27 @@ export async function runDoctor() {
             line(WARN, `claude/${n}: ${parts.join("; ")} — run \`agent-switch share sync\`.`);
         }
     }
+    // Single-load guard: the policy, and whether any profile is doubled RIGHT NOW.
+    // Reported even when the policy is `warn`/`off` — the point of doctor is to
+    // surface the state, and a silently tolerated duplicate is exactly the thing
+    // the user came here to find.
+    {
+        const policy = readGuard();
+        line(policy === "off" ? WARN : OK, `single-load guard: ${policy}${policy === "off" ? " — a profile can be loaded twice" : ""}.`);
+        const doubled = [];
+        for (const p of allProviders()) {
+            if (!p.hasLiveSessionSignal)
+                continue;
+            for (const n of listProfiles(p.id)) {
+                const count = liveSessionPids(configDir(p.id, n)).length;
+                if (count > 1)
+                    doubled.push(`${p.id}/${n} (${count} sessions)`);
+            }
+        }
+        if (doubled.length > 0) {
+            line(WARN, `  loaded more than once: ${doubled.join(", ")} — they share one account's rate limits.`);
+        }
+    }
     // Ecosystem tooling (agent-config + rtk) — same detection module as
     // `agent-switch tooling`, never a second implementation. Both tools are
     // optional, so an unhealthy row is a WARN, never a blocking error.

package/dist/index.js

@@ -15,7 +15,7 @@ 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, readOsNotifications, setOsNotifications, readProviders, setProviderSurface, readBinaryPath, readBinaryPaths, setBinaryPath, ROOT, resetRebindKillSwitch, } 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";
@@ -27,17 +27,19 @@ import { applySharing, removeSharing, syncSharing, sharedLinkHealth } from "./sh
 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 { 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 { 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";
@@ -52,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);
@@ -165,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);
@@ -179,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.)");
@@ -204,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}`);
 }
@@ -362,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]`);
@@ -1664,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)));
 }
@@ -1679,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
@@ -1736,7 +1931,8 @@ Run with no command to launch the tray/menubar GUI (single-instance).
   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
@@ -1769,6 +1965,7 @@ Run with no command to launch the tray/menubar GUI (single-instance).
   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`);
 }
 /**
@@ -1858,7 +2055,26 @@ async function rebindDialog(running) {
 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;
+    // 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.
@@ -1920,8 +2136,10 @@ async function main() {
         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(", ")}.`);
         }
     }
@@ -1956,7 +2174,8 @@ 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();
@@ -1985,8 +2204,10 @@ 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());

package/dist/profiles.js

@@ -4,6 +4,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { PROVIDER_IDS, provider, isProviderId } from "./providers.js";
 import { credentialStore } from "./credentials.js";
+import { DEFAULT_GUARD_POLICY, isGuardPolicy } from "./single-load.js";
 export const HOME = os.homedir();
 export const ROOT = process.env.AGENT_SWITCH_HOME ?? path.join(HOME, ".agent-switch");
 export const STATE_FILE = path.join(ROOT, "state.json");
@@ -160,6 +161,9 @@ function normalizeRebindState(raw) {
     const consecutiveFailures = typeof r.consecutiveFailures === "number" && r.consecutiveFailures >= 0 ? Math.floor(r.consecutiveFailures) : 0;
     return { disabled: r.disabled === true, consecutiveFailures };
 }
+function normalizeGuard(raw) {
+    return isGuardPolicy(raw) ? raw : DEFAULT_GUARD_POLICY;
+}
 export function readState() {
     try {
         const raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
@@ -169,19 +173,20 @@ export function readState() {
         const binaryPaths = normalizeBinaryPaths(raw?.binaryPaths);
         const osNotifications = raw?.osNotifications === true;
         const rebind = normalizeRebindState(raw?.rebind);
+        const guard = normalizeGuard(raw?.guard);
         // v1: { active: "<name>" } — a single Claude profile.
         if (typeof raw?.active === "string") {
-            return { active: { ...emptyActive(), claude: raw.active }, labels, autoSwitch, providers, binaryPaths, osNotifications, rebind };
+            return { active: { ...emptyActive(), claude: raw.active }, labels, autoSwitch, providers, binaryPaths, osNotifications, rebind, guard };
         }
         if (raw?.active && typeof raw.active === "object") {
-            return { active: { ...emptyActive(), ...raw.active }, labels, autoSwitch, providers, binaryPaths, osNotifications, rebind };
+            return { active: { ...emptyActive(), ...raw.active }, labels, autoSwitch, providers, binaryPaths, osNotifications, rebind, guard };
         }
-        return { active: emptyActive(), labels, autoSwitch, providers, binaryPaths, osNotifications, rebind };
+        return { active: emptyActive(), labels, autoSwitch, providers, binaryPaths, osNotifications, rebind, guard };
     }
     catch {
         /* absent / unparsable → default */
     }
-    return { active: emptyActive(), labels: {}, autoSwitch: emptyAutoSwitch(), providers: emptyProviders(), binaryPaths: {}, osNotifications: false, rebind: { ...DEFAULT_REBIND_STATE } };
+    return { active: emptyActive(), labels: {}, autoSwitch: emptyAutoSwitch(), providers: emptyProviders(), binaryPaths: {}, osNotifications: false, rebind: { ...DEFAULT_REBIND_STATE }, guard: DEFAULT_GUARD_POLICY };
 }
 export function readOsNotifications() {
     return readState().osNotifications;
@@ -191,6 +196,17 @@ export function setOsNotifications(on) {
     state.osNotifications = on;
     writeState(state);
 }
+// ---------- single-load guard policy ----------
+/** How the single-load guard reacts to a second load of one profile. */
+export function readGuard() {
+    return readState().guard;
+}
+/** Persist the guard policy. */
+export function setGuard(policy) {
+    const state = readState();
+    state.guard = policy;
+    writeState(state);
+}
 // ---------- rebind kill-switch / circuit-breaker (ADR-003) ----------
 /** Current rollback/circuit-breaker state for the `rebind` write path. */
 export function readRebindKillSwitch() {

package/dist/providers.js

@@ -77,6 +77,7 @@ const claude = {
     oneShotArgs: (prompt) => ["-p", prompt],
     importFiles: [],
     hasUsageReadout: true,
+    hasLiveSessionSignal: true,
 };
 const codex = {
     id: "codex",
@@ -95,6 +96,7 @@ const codex = {
     oneShotArgs: (prompt) => ["exec", prompt],
     importFiles: ["auth.json"],
     hasUsageReadout: true, // live via wham/usage (ChatGPT backend)
+    hasLiveSessionSignal: false, // rollouts are date-partitioned; no live-pid marker
 };
 const antigravity = {
     id: "antigravity",
@@ -128,6 +130,7 @@ const antigravity = {
     oneShotArgs: (prompt) => ["--print", prompt],
     importFiles: [],
     hasUsageReadout: false,
+    hasLiveSessionSignal: false,
 };
 const PROVIDERS = { claude, codex, antigravity };
 export function provider(id) {

package/dist/release-notes.js

@@ -0,0 +1,154 @@
+/**
+ * Release-note normalisation — turn a GitHub release body into something a
+ * card or a terminal can show without it reading as broken.
+ *
+ * Mirrored in `gui/src/release-notes.ts` (same boundary reason as updates.ts:
+ * the GUI's tsconfig only includes `gui/src`, so pure helpers are duplicated
+ * rather than imported across it). `tests/release-notes.test.ts` byte-compares
+ * the two below their header comment, so a fix applied to one and not the other
+ * fails there — and it asserts against the real captured body
+ * (`tests/fixtures/agent-config-release-14.2.0.md`), which the GUI mirror's own
+ * suite cannot read: that project ships no `@types/node` on purpose.
+ *
+ * Why a normaliser and not `body.slice(0, 500)`: measured on agent-config
+ * 14.2.0, the first 500 characters are a heading, an HTML comment addressed to
+ * the release author, and five `_none_` placeholders. The shapes handled here
+ * are the ones that release template actually emits — headings, `*` items with
+ * a `**scope:**` prefix, `([sha](commit-url))` suffixes, `**bold**` / `_italic_`
+ * and horizontal rules. Everything is pure; no I/O, no markdown dependency.
+ */
+/** Drop HTML comments, including multi-line ones. This is what removes the
+ *  release template's author-facing instruction line ("fill before merge …") —
+ *  a comment is invisible on GitHub and must stay invisible here. */
+export function stripHtmlComments(md) {
+    return String(md).replace(/<!--[\s\S]*?-->/g, "");
+}
+/** Inline cleanup applied to every line's text: commit-link suffixes go, real
+ *  links collapse to their label, bold/italic markers are unwrapped, and runs
+ *  of whitespace collapse. Inline code keeps its backticks on purpose — they
+ *  mark a literal name, which is information, not noise. Pure. */
+export function normalizeInline(s) {
+    return String(s)
+        // ` ([abc1234](https://…/commit/abc…))` — the generated changelog's sha
+        // suffix. Removed before generic link handling, which would otherwise
+        // leave a bare `(abc1234)` behind.
+        .replace(/\s*\(\[[0-9a-f]{7,40}\]\([^)\s]*\)\)/gi, "")
+        // `[label](url)` → `label`
+        .replace(/\[([^\]]*)\]\([^)\s]*\)/g, "$1")
+        // `**bold**` / `__bold__` → bold
+        .replace(/\*\*([^*]+)\*\*/g, "$1")
+        .replace(/__([^_]+)__/g, "$1")
+        // `_italic_` → italic (this is what turns `_none_` into `none`).
+        // Underscore-delimited only at word boundaries so `snake_case_names` and
+        // `file_name.ts` survive untouched.
+        .replace(/(^|[\s(])_([^_]+)_(?=[\s).,;:!?]|$)/g, "$1$2")
+        .replace(/[ \t]{2,}/g, " ")
+        .trim();
+}
+/** True for a markdown horizontal rule (`---`, `***`, `___`). */
+function isHorizontalRule(line) {
+    return /^\s*([-*_])\s*(\1\s*){2,}$/.test(line);
+}
+/**
+ * Parse a release body into ordered blocks. Blank lines carry no block — the
+ * renderers space by `kind` instead, so a body with erratic blank runs comes
+ * out evenly spaced. An empty or comment-only body yields `[]`, which every
+ * caller must treat as "no notes" (render nothing — never a placeholder).
+ */
+export function releaseNoteBlocks(md) {
+    const blocks = [];
+    for (const raw of stripHtmlComments(md).split(/\r?\n/)) {
+        if (!raw.trim() || isHorizontalRule(raw))
+            continue;
+        const heading = /^\s*#{1,6}\s+(.*)$/.exec(raw);
+        if (heading) {
+            const text = normalizeInline(heading[1]);
+            if (text)
+                blocks.push({ kind: "heading", text });
+            continue;
+        }
+        const item = /^\s*[-*+]\s+(.*)$/.exec(raw);
+        if (item) {
+            const text = normalizeInline(item[1]);
+            if (text)
+                blocks.push({ kind: "item", text });
+            continue;
+        }
+        const text = normalizeInline(raw);
+        if (text)
+            blocks.push({ kind: "text", text });
+    }
+    return blocks;
+}
+/** A `_none_`-style empty value — the release template's way of saying "this
+ *  section genuinely has nothing", which must not be offered as a highlight. */
+function isEmptyValue(value) {
+    return /^(none|n\/a|-|—)$/i.test(value.trim());
+}
+/**
+ * The one line worth putting in a notification: the first non-empty bullet
+ * under a "highlights"-ish heading, else the first bullet in the body. Returns
+ * null when the body carries no bullet with content — callers then say nothing
+ * rather than inventing a summary. Pure.
+ */
+export function firstHighlight(blocks) {
+    const start = blocks.findIndex((b) => b.kind === "heading" && /highlight/i.test(b.text));
+    const scan = (from, stopAtHeading) => {
+        for (let i = from; i < blocks.length; i++) {
+            const b = blocks[i];
+            if (b.kind === "heading" && stopAtHeading && i > from)
+                return null;
+            if (b.kind !== "item")
+                continue;
+            // `Behaviour changes: none` → value `none`; a bullet with no colon is
+            // its own value.
+            const colon = b.text.indexOf(":");
+            const value = colon >= 0 ? b.text.slice(colon + 1) : b.text;
+            if (!isEmptyValue(value))
+                return b.text;
+        }
+        return null;
+    };
+    return start >= 0 ? (scan(start + 1, true) ?? scan(0, false)) : scan(0, false);
+}
+/**
+ * Render blocks as terminal lines: a blank line before each heading (never as
+ * the first line), items bulleted, text as-is. `omitted` is how many lines the
+ * cap dropped, so the caller can print an honest "… N more" plus the release
+ * URL instead of silently truncating. Pure.
+ */
+export function releaseNotesText(blocks, opts = {}) {
+    const bullet = opts.bullet ?? "•";
+    const indent = opts.indent ?? "";
+    const all = [];
+    for (const b of blocks) {
+        if (b.kind === "heading") {
+            if (all.length)
+                all.push("");
+            all.push(`${indent}${b.text}`);
+        }
+        else if (b.kind === "item") {
+            all.push(`${indent}  ${bullet} ${b.text}`);
+        }
+        else {
+            all.push(`${indent}  ${b.text}`);
+        }
+    }
+    const max = opts.maxLines;
+    if (max === undefined || all.length <= max)
+        return { lines: all, omitted: 0 };
+    return { lines: all.slice(0, max), omitted: all.length - max };
+}
+/** Clamp to `max` characters on a word boundary, appending an ellipsis when
+ *  anything was cut. Used for the one-line notification summary, where a raw
+ *  bullet can run to several hundred characters. Pure. */
+export function clampText(s, max) {
+    const t = String(s).trim();
+    if (t.length <= max)
+        return t;
+    const cut = t.slice(0, max);
+    const space = cut.lastIndexOf(" ");
+    // Prefer the word boundary, but only when it still keeps at least half the
+    // budget — otherwise a long first word would collapse the summary to nothing.
+    return `${(space > max * 0.5 ? cut.slice(0, space) : cut).replace(/[\s,;:.\-]+$/, "")}…`;
+}

package/dist/sessions.js

@@ -174,6 +174,25 @@ export function markLive(configDir, rows, cwdOf = pidCwd) {
             row.live = true;
     }
 }
+/**
+ * Auto-detect which Claude profile has a live session, for `rebind`'s
+ * no-`--profile` resolution. A profile is "running" when its config dir carries
+ * a live session pid (`<configDir>/sessions/<pid>.json` whose pid is alive).
+ *
+ * Returns `single` ONLY when exactly one profile is running — rebind writes a
+ * credential store, so the caller must never guess a target across ambiguity;
+ * `none` / `ambiguous` leave the caller on its explicit-`--profile` / active
+ * fallback. Pure (`livePidsOf` injected) so every branch is unit-tested without
+ * touching real processes.
+ */
+export function detectRunningClaudeProfile(profiles, configDirOf, livePidsOf = liveSessionPids) {
+    const running = profiles.filter((p) => livePidsOf(configDirOf(p)).length > 0);
+    if (running.length === 1)
+        return { kind: "single", profile: running[0] };
+    if (running.length > 1)
+        return { kind: "ambiguous", profiles: running };
+    return { kind: "none" };
+}
 /** Where a session id lives inside ONE profile config dir, or null. */
 export function locateSession(configDir, sessionId) {
     const projects = path.join(configDir, "projects");

package/dist/shellenv.js

@@ -13,8 +13,29 @@
  * `asw` convenience: bare `asw` lists all providers' profiles; `asw <name>`
  * switches the active Claude profile; `asw <provider> <name>` switches that
  * provider's.
+ *
+ * SINGLE-LOAD GUARD. The wrapper is the one place every interactive start
+ * funnels through, so it is where the guard has to sit. `dir --guard` keeps the
+ * config path on stdout (unchanged) and writes the human message to stderr, so
+ * one invocation both feeds the wrapper and talks to the user — no second
+ * process launch per command.
+ *
+ * The wrapper blocks on EXACTLY ONE exit code (86, GUARD_REFUSED_EXIT) and on
+ * nothing else. That asymmetry is deliberate and load-bearing: a missing,
+ * older, or broken `agent-switch` exits 127 / 1 / 2 and the wrapper carries on
+ * to the real binary. This tool must never become the reason a user cannot
+ * reach their assistant.
+ *
+ * Each wrapper first checks that `agent-switch` exists at all and otherwise
+ * calls the real binary straight away. That check replaces the old
+ * `2>/dev/null`: the guard has to be able to SPEAK on stderr, so the blanket
+ * redirect had to go, and without the existence check an uninstalled
+ * `agent-switch` would print "command not found" on every single invocation.
+ * A side effect worth having: a genuinely broken agent-switch now surfaces its
+ * error instead of silently degrading the shell onto the default config dir.
  */
 import { allProviders } from "./providers.js";
+import { GUARD_REFUSED_EXIT } from "./single-load.js";
 export const SHELLS = ["zsh", "bash", "fish", "powershell"];
 /** Resolve the target shell: explicit request wins, else detect from the
  *  environment / platform. Windows defaults to PowerShell; POSIX reads $SHELL. */
@@ -40,8 +61,11 @@ export function detectShell(requested, env = process.env, platform = process.pla
 }
 function posixWrapper(binary, envVar, id) {
     return `${binary}() {
-  local dir
-  dir="$(command agent-switch dir --provider ${id} 2>/dev/null)"
+  local dir rc
+  command -v agent-switch >/dev/null 2>&1 || { command ${binary} "$@"; return; }
+  dir="$(command agent-switch dir --provider ${id} --guard)"
+  rc=$?
+  if [ $rc -eq ${GUARD_REFUSED_EXIT} ]; then return $rc; fi
   if [ -n "$dir" ]; then
     ${envVar}="$dir" command ${binary} "$@"
   else
@@ -51,7 +75,15 @@ function posixWrapper(binary, envVar, id) {
 }
 function fishWrapper(binary, envVar, id) {
     return `function ${binary}
-    set -l dir (command agent-switch dir --provider ${id} 2>/dev/null)
+    if not type -q agent-switch
+        command ${binary} $argv
+        return
+    end
+    set -l dir (command agent-switch dir --provider ${id} --guard)
+    set -l rc $status
+    if test $rc -eq ${GUARD_REFUSED_EXIT}
+        return $rc
+    end
     if test -n "$dir"
         ${envVar}=$dir command ${binary} $argv
     else
@@ -63,7 +95,9 @@ function powershellWrapper(binary, envVar, id) {
     return `function ${binary} {
     $exe = Get-Command ${binary} -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
     if (-not $exe) { Write-Error '${binary} not found on PATH.'; return }
-    $dir = (& agent-switch dir --provider ${id} 2>$null)
+    if (-not (Get-Command agent-switch -ErrorAction SilentlyContinue)) { & $exe.Source @args; return }
+    $dir = (& agent-switch dir --provider ${id} --guard)
+    if ($LASTEXITCODE -eq ${GUARD_REFUSED_EXIT}) { return }
     if ($dir) {
         $prev = Get-Item -Path Env:\\${envVar} -ErrorAction SilentlyContinue
         $env:${envVar} = $dir

package/dist/single-load.js

@@ -0,0 +1,171 @@
+/**
+ * Single-load guard: one profile, one live session.
+ *
+ * The problem it solves: `agent-switch use` writes a GLOBAL active pointer and
+ * the shell wrapper re-resolves it on every invocation, so nothing stops two
+ * terminals from starting `claude` on the same profile. Two live sessions on
+ * one account share its rate-limit windows and both refresh one rotating OAuth
+ * store (the rotation `src/locks.ts` documents) — and, worst of the three, the
+ * user believes the second terminal is on a different account because they
+ * typed `asw <other>` there.
+ *
+ * Ground truth is Claude Code's own bookkeeping, never ours: a live session
+ * writes `<config>/sessions/<pid>.json`, and `liveSessionPids` filters dead
+ * pids on every read. That makes the signal self-healing — a crashed session
+ * leaves a stale file that is simply never counted, so this module needs no
+ * cleanup job and holds no lease of its own. (An agent-switch-owned lease would
+ * need a holder process; the shell wrapper execs `claude` and exits, so every
+ * crash would leak one.)
+ *
+ * Everything here is pure — processes, environment, and clock are injected — so
+ * every branch is unit-tested without spawning anything.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { liveSessionPids } from "./api.js";
+import { pidCwd } from "./sessions.js";
+export const GUARD_POLICIES = ["block", "warn", "off"];
+export const DEFAULT_GUARD_POLICY = "block";
+export function isGuardPolicy(v) {
+    return typeof v === "string" && GUARD_POLICIES.includes(v);
+}
+/** Env var that waives the guard for exactly one invocation. An env var, not a
+ *  flag: the shell wrapper passes every unknown flag THROUGH to the provider
+ *  binary, so a `--force` there would reach `claude`, not us. */
+export const OVERRIDE_ENV = "AGENT_SWITCH_ALLOW_DUPLICATE";
+/** Exit code the wrapper keys on. Distinct from every generic failure (1, 2,
+ *  127 …) so the wrapper blocks on a REFUSAL and never on a missing or older
+ *  `agent-switch` — fail-open is deliberate: this tool must never be the reason
+ *  a user cannot start their assistant. */
+export const GUARD_REFUSED_EXIT = 86;
+function pidFileMtime(configDir, pid) {
+    try {
+        return fs.statSync(path.join(configDir, "sessions", `${pid}.json`)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Who currently holds `configDir`, and whether we are a child of one of them.
+ *
+ * `envVar` is the provider's isolation variable (`CLAUDE_CONFIG_DIR`, …). The
+ * nested comparison is on the RAW string, deliberately unresolved: that same
+ * unresolved string is what Claude Code hashes into its keychain service name
+ * (`profiles.ts` § configDir), so resolving it here would compare a different
+ * identity than the one the rest of the tool uses.
+ */
+export function inspectLoad(configDir, envVar, deps = {}) {
+    const livePidsOf = deps.livePidsOf ?? liveSessionPids;
+    const cwdOf = deps.cwdOf ?? pidCwd;
+    const startedMsOf = deps.startedMsOf ?? pidFileMtime;
+    const env = deps.env ?? process.env;
+    const nested = env[envVar] === configDir;
+    const pids = livePidsOf(configDir);
+    // A nested start is allowed unconditionally, so its message is never
+    // rendered — and resolving a cwd costs an `lsof` per pid on darwin. Skip the
+    // lookup rather than pay it on a path that cannot use the answer.
+    const sessions = pids.map((pid) => ({
+        pid,
+        cwd: nested ? null : cwdOf(pid),
+        startedMs: startedMsOf(configDir, pid),
+    }));
+    return { sessions, loaded: sessions.length > 0, nested };
+}
+/**
+ * Pure policy resolution. Order matters and each precedence is load-bearing:
+ * an undetectable provider can never refuse (no evidence), a nested start is
+ * a deliberate child rather than a duplicate, and an explicit override outranks
+ * the policy because the user just stated an intent this turn.
+ */
+export function guardVerdict({ policy, inspection, overridden = false, detectable = true }) {
+    if (!detectable)
+        return "allow";
+    if (policy === "off")
+        return "allow";
+    if (!inspection.loaded)
+        return "allow";
+    if (inspection.nested)
+        return "allow";
+    if (overridden)
+        return "warn"; // proceed, but still say what is happening
+    return policy === "warn" ? "warn" : "refuse";
+}
+/** True when the one-shot override env var is set to a meaningful value. */
+export function overrideFromEnv(env = process.env) {
+    const v = env[OVERRIDE_ENV];
+    return typeof v === "string" && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+}
+/** Relative age like "3m" / "2h" — mirrors the sessions listing's `ageOf`. */
+function ageOf(startedMs, now) {
+    if (startedMs === null)
+        return null;
+    const s = Math.max(0, Math.round((now - startedMs) / 1000));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.round(s / 60)}m`;
+    if (s < 86400)
+        return `${Math.round(s / 3600)}h`;
+    return `${Math.round(s / 86400)}d`;
+}
+/** Render actions as a table whose column width comes from the widest action,
+ *  so a long override line can never collide with its own explanation. */
+function actionTable(rows) {
+    const width = Math.max(...rows.map(([action]) => action.length));
+    return rows.map(([action, explanation]) => `  ${action.padEnd(width + 2)}${explanation}`);
+}
+/**
+ * The one place the guard speaks. Every enforcement point renders through this
+ * so the CLI, the wrapper path, and `use` never drift into three dialects.
+ *
+ * A refusal that only says "no" hands the problem straight back, so the message
+ * names WHO holds the profile (pid, age, directory), WHY that matters, and the
+ * concrete ways forward — including the names of the profiles that are actually
+ * free, and how to switch the guard off.
+ */
+export function renderGuardMessage(input) {
+    const { profile, binary, verdict, inspection, offerForceFlag = false, alternatives = [], context = "start", now = Date.now(), } = input;
+    const n = inspection.sessions.length;
+    const held = `profile "${profile}" is already loaded by ${n === 1 ? "a running" : `${n} running`} ${binary} session${n === 1 ? "" : "s"}`;
+    const headline = context === "use"
+        ? verdict === "refuse"
+            ? `${held} — the next \`${binary}\` started here will be refused.`
+            : `${held} — a second session will be allowed (guard: warn).`
+        : verdict === "refuse"
+            ? `${held}.`
+            : `${held} — continuing anyway.`;
+    const lines = [headline, ""];
+    for (const sess of inspection.sessions) {
+        const age = ageOf(sess.startedMs, now);
+        const parts = [`  pid ${sess.pid}`];
+        if (age)
+            parts.push(`started ${age} ago`);
+        if (sess.cwd)
+            parts.push(sess.cwd);
+        lines.push(parts.join("  "));
+    }
+    lines.push("", "Two sessions on one account share its rate limits, and both refresh the", "same rotating OAuth token.");
+    if (verdict === "refuse") {
+        const rows = [];
+        rows.push([
+            `agent-switch use ${alternatives.length > 0 ? alternatives[0] : "<other-profile>"}`,
+            alternatives.length > 1
+                ? `switch to a free account — also free: ${alternatives.slice(1).join(", ")}`
+                : alternatives.length === 1
+                    ? "switch to the account that is free"
+                    : "point new sessions at another account",
+        ]);
+        // Both overrides do the same thing, so only one is offered: `--force` where
+        // the caller can accept a flag, the env var everywhere else. A shell wrapper
+        // passes unknown flags THROUGH to the provider binary, which is why the env
+        // var exists at all — offering both would just be two names for one action.
+        rows.push(offerForceFlag
+            ? ["--force", "start it anyway, this once"]
+            : [`${OVERRIDE_ENV}=1 ${binary}`, "start it anyway, this once"]);
+        rows.push(["agent-switch guard warn", "warn instead of refusing, from now on"]);
+        rows.push(["agent-switch guard off", "turn the guard off entirely"]);
+        lines.push("", "Ways forward:", ...actionTable(rows));
+    }
+    return lines.join("\n");
+}

package/dist/tooling.js

@@ -19,6 +19,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { readBinaryPath } from "./profiles.js";
 import { npmSearchPath } from "./updates.js";
+import { releaseNoteBlocks, releaseNotesText } from "./release-notes.js";
 export const TOOL_IDS = ["agent-config", "rtk", "claude", "codex", "agy"];
 /** Which provider a probed binary belongs to (for `providers link` hints and
  *  the user-linked path lookup). */
@@ -322,3 +323,75 @@ export function doctorToolingLine(t) {
     }
     return `\`${t.id}\`: ${t.hint}`;
 }
+// ---------- release notes (`tooling notes <tool>`) --------------------------------
+/**
+ * Repos whose GitHub Releases are a tool's release-note source. Only tools with
+ * a source this repo has actually verified appear here — inventing a plausible
+ * repo for the rest would be worse than the refusal `toolNotesRefusal` prints.
+ * Same two sources the GUI uses (agent-config's release check, rtk's update
+ * check), so the CLI and the GUI can never describe a release differently.
+ */
+export const TOOL_RELEASE_REPOS = {
+    "agent-config": "event4u-app/agent-config",
+    rtk: "rtk-ai/rtk",
+};
+/** The release-notes source for a tool, or null when it has none. */
+export function toolReleaseRepo(id) {
+    return TOOL_RELEASE_REPOS[id] ?? null;
+}
+/** Why a tool has no readable release notes here — named, never guessed. */
+export function toolNotesRefusal(id) {
+    if (id === "claude" || id === "codex") {
+        return (`\`${id}\` is distributed on npm and this repo has no verified GitHub release source for it, ` +
+            `so there are no notes to show rather than a guessed one.\n` +
+            `  Its installed version is in \`agent-switch tooling\`; upgrade with \`agent-switch tooling upgrade ${id}\`.`);
+    }
+    return (`\`${id}\` has no known release source — the Antigravity CLI ships with the Antigravity app and publishes no releases here.\n` +
+        `  Its installed version is in \`agent-switch tooling\`.`);
+}
+/** The header line: what is installed, what is published, and whether anything
+ *  is waiting. Pure — every branch is unit-tested. */
+export function toolNotesHeader(view) {
+    const { id, installed, latest } = view;
+    if (!installed) {
+        return `${id} — not installed · ${latest ? `latest ${latest}` : "latest unknown"}`;
+    }
+    if (!latest) {
+        return `${id} — installed ${installed} · latest unknown (offline or rate-limited)`;
+    }
+    const pending = view.releases.filter((r) => r.tag !== installed).length;
+    if (installed === latest || pending === 0)
+        return `${id} — installed ${installed} · up to date`;
+    return `${id} — installed ${installed} · latest ${latest} · ${pending} update${pending === 1 ? "" : "s"} to read`;
+}
+/**
+ * The full `tooling notes` rendering: header, then each release as a dated
+ * block of normalised notes plus its URL. A release whose body normalises to
+ * nothing is listed with its URL and an explicit "no notes in this release" —
+ * unlike the GUI panel, a terminal command the user typed must answer rather
+ * than print nothing. `maxLinesPerRelease` caps a long body and says how much
+ * was left out. Pure.
+ */
+export function formatToolNotes(view, maxLinesPerRelease = 40) {
+    const out = [toolNotesHeader(view)];
+    if (view.releases.length === 0) {
+        out.push("", "No release notes available.");
+        return out;
+    }
+    for (const r of view.releases) {
+        const date = /^\d{4}-\d{2}-\d{2}/.test(r.publishedAt) ? r.publishedAt.slice(0, 10) : null;
+        out.push("", `${r.name || r.tag}${date ? ` — ${date}` : ""}`);
+        const { lines, omitted } = releaseNotesText(releaseNoteBlocks(r.notes), {
+            maxLines: maxLinesPerRelease,
+            indent: "  ",
+        });
+        if (lines.length === 0)
+            out.push("  (no notes in this release)");
+        else
+            out.push(...lines);
+        if (omitted > 0)
+            out.push(`  … ${omitted} more line${omitted === 1 ? "" : "s"}`);
+        out.push(`  ${r.url}`);
+    }
+    return out;
+}

package/dist/updates.js

@@ -47,8 +47,10 @@ export function isNewer(latest, current) {
     return compareVersions(latest, current) > 0;
 }
 /** Reshape a raw GitHub `releases/latest` payload into {@link ReleaseInfo}, or
- *  null for a draft/prerelease or a payload without a tag. Pure — no network. */
-export function parseRelease(raw) {
+ *  null for a draft/prerelease or a payload without a tag. Pure — no network.
+ *  `repo` only supplies the fallback URL for a payload missing `html_url`; it
+ *  defaults to this app's own repo so existing callers are unaffected. */
+export function parseRelease(raw, repo = UPDATE_REPO) {
     if (!raw || typeof raw !== "object")
         return null;
     const r = raw;
@@ -60,11 +62,43 @@ export function parseRelease(raw) {
     return {
         tag,
         name: typeof r.name === "string" && r.name ? r.name : tag,
-        url: typeof r.html_url === "string" ? r.html_url : `https://github.com/${UPDATE_REPO}/releases`,
+        url: typeof r.html_url === "string" ? r.html_url : `https://github.com/${repo}/releases`,
         notes: typeof r.body === "string" ? r.body : "",
         publishedAt: typeof r.published_at === "string" ? r.published_at : "",
     };
 }
+/** Reshape a raw GitHub `/releases` array (drafts and prereleases dropped by
+ *  {@link parseRelease}'s existing rule) and order it newest version first, so
+ *  the ordering is the version math rather than GitHub's creation order. Pure. */
+export function parseReleases(raw, repo = UPDATE_REPO) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .map((r) => parseRelease(r, repo))
+        .filter((r) => r !== null)
+        .sort((a, b) => compareVersions(b.tag, a.tag));
+}
+/** The releases strictly newer than `current`, newest first — i.e. everything
+ *  the user has not seen yet, which is what "what changed" actually means for
+ *  someone several versions behind. Pure. */
+export function releasesNewerThan(releases, current) {
+    return releases.filter((r) => isNewer(r.tag, current)).sort((a, b) => compareVersions(b.tag, a.tag));
+}
+/** Recent releases for a repo, newest first. `[]` when the repo has none (404)
+ *  — a normal empty state. Throws on any other network/HTTP failure so the
+ *  caller can fall back to {@link fetchLatestRelease} rather than silently
+ *  reporting "nothing new". One request; the unauthenticated endpoint is
+ *  rate-limited (60/h per IP), ample for an hourly check. */
+export async function fetchReleases(repo = UPDATE_REPO, perPage = 20) {
+    const res = await fetch(`https://api.github.com/repos/${repo}/releases?per_page=${perPage}`, {
+        headers: { Accept: "application/vnd.github+json", "User-Agent": `${PACKAGE_NAME} cli-updater` },
+    });
+    if (res.status === 404)
+        return [];
+    if (!res.ok)
+        throw new Error(`GitHub API returned ${res.status}`);
+    return parseReleases(await res.json(), repo);
+}
 /** The running CLI's version, from the package's own package.json (one level up
  *  from the compiled dist/). "0.0.0" if unreadable so callers never crash. */
 export function currentVersion() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@event4u/agent-switch",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Switch between multiple Claude Code accounts on macOS, Linux, and Windows via isolated CLAUDE_CONFIG_DIR profiles",
   "repository": {
     "type": "git",