@event4u/agent-switch 2.0.0 → 2.2.0

package/dist/share.js

@@ -15,9 +15,15 @@
  *     re-links (last-sync-wins across profiles). On win32, file symlinks need
  *     Developer Mode/admin, so file links degrade with a message there.
  *
+ *   - Prompt history (`history.jsonl`, what ↑ and Ctrl+R search) — always
+ *     linked: it holds no account state, and Claude Code only ever APPENDS to
+ *     it (under a lock), so the link never forks. A profile's own file is
+ *     merged into the shared one (chronological, de-duplicated) and kept as a
+ *     `history.jsonl.pre-share*` backup instead of blocking the link.
+ *
  * Account-/instance-scoped items (`.claude.json`, `.credentials.json`,
  * `plugins/`, `sessions/`, `ide/`, `statsig/`) are deliberately never shared.
- * History (`projects/`, `history.jsonl`, `plans/`) is a POSIX-only opt-in.
+ * Conversations (`projects/`, `plans/`) are a POSIX-only opt-in (`--history`).
  * (`plans/` defaults to `<CLAUDE_CONFIG_DIR>/plans/` in Claude Code, so plan-mode
  * files are otherwise isolated per profile — verified against claude-code 2.1.215.)
  *
@@ -34,18 +40,21 @@ const BASE_ITEMS = [
     { name: "commands", kind: "dir" },
     { name: "agents", kind: "dir" },
 ];
-/** Conversation history + plan-mode files; opt-in — shares `claude --resume`
+/** Append-only logs shared by every `share on`, but never part of a config
+ *  export (`SHARED_ITEMS` is that export's allowlist). */
+const LOG_ITEMS = [{ name: "history.jsonl", kind: "log" }];
+/** Conversations + plan-mode files; opt-in — shares `claude --resume`
  *  and the plan store across accounts. `plans/` is a `dir`, so writes inside it
  *  reach the source (no atomic-rename fork), exactly like `projects/`. */
 const HISTORY_ITEMS = [
     { name: "projects", kind: "dir" },
-    { name: "history.jsonl", kind: "file" },
     { name: "plans", kind: "dir" },
 ];
 /** Names exported for messaging/tests. */
 export const SHARED_ITEMS = BASE_ITEMS.map((i) => i.name);
-export const HISTORY_ITEM_NAMES = HISTORY_ITEMS.map((i) => i.name);
-const ITEM_KIND = new Map([...BASE_ITEMS, ...HISTORY_ITEMS].map((i) => [i.name, i.kind]));
+export const PROMPT_HISTORY = LOG_ITEMS[0].name;
+export const HISTORY_ITEM_NAMES = [...HISTORY_ITEMS, ...LOG_ITEMS].map((i) => i.name);
+const ITEM_KIND = new Map([...BASE_ITEMS, ...LOG_ITEMS, ...HISTORY_ITEMS].map((i) => [i.name, i.kind]));
 const MANIFEST = ".agent-switch-shared.json";
 function readManifest(dir) {
     try {
@@ -72,6 +81,59 @@ function link(src, dst, kind) {
         fs.symlinkSync(src, dst, process.platform === "win32" ? "file" : undefined);
     }
 }
+const stampOf = (l) => {
+    try {
+        const t = JSON.parse(l)?.timestamp;
+        return typeof t === "number" && Number.isFinite(t) ? t : null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Merge the lines of `extra` into the prompt history at `src`: de-duplicated by
+ * exact line, ordered by timestamp (Claude Code reads the file newest-last, so
+ * ↑ walks back in time). Unparseable lines keep their place after their
+ * predecessor. Written via temp + rename; re-read when the source grew while we
+ * merged, so a concurrent append is not lost. Returns the lines added.
+ */
+export function mergePromptHistory(src, extra) {
+    const linesOf = (f) => fs.existsSync(f) ? fs.readFileSync(f, "utf8").split("\n").filter((l) => l.trim() !== "") : [];
+    const incoming = linesOf(extra);
+    for (let attempt = 0;; attempt++) {
+        const before = fs.existsSync(src) ? fs.statSync(src).size : -1;
+        const own = linesOf(src);
+        const seen = new Set(own);
+        const added = incoming.filter((l) => !seen.has(l) && (seen.add(l), true));
+        if (added.length === 0)
+            return 0;
+        let last = 0;
+        const keyed = [...own, ...added].map((l, i) => {
+            last = stampOf(l) ?? last;
+            return { l, i, t: last };
+        });
+        keyed.sort((a, b) => a.t - b.t || a.i - b.i);
+        const tmp = `${src}.agent-switch-merge`;
+        fs.writeFileSync(tmp, keyed.map((k) => k.l).join("\n") + "\n", { mode: 0o600 });
+        const after = fs.existsSync(src) ? fs.statSync(src).size : -1;
+        if (after !== before && attempt < 3) {
+            fs.unlinkSync(tmp);
+            continue;
+        }
+        fs.renameSync(tmp, src);
+        return added.length;
+    }
+}
+/** Merge a profile's own prompt history into the shared one, keep the original
+ *  as a backup next to it, and leave the slot free for the link. */
+function adoptLog(src, dst, name) {
+    const n = mergePromptHistory(src, dst);
+    let backup = `${dst}.pre-share`;
+    if (fs.existsSync(backup))
+        backup = `${backup}-${Date.now()}`;
+    fs.renameSync(dst, backup);
+    return `merged ${n} prompt(s) from ${name} (original kept as ${path.basename(backup)})`;
+}
 /** True when the existing symlink already points at src (junction paths on
  *  win32 may carry a trailing separator / `\\?\` prefix, so compare loosely). */
 function pointsAt(dst, src) {
@@ -108,14 +170,12 @@ export function settingsSharingRisk(settingsPath) {
 /** Link items from sourceDir into targetDir. Returns human-readable actions. */
 export function applySharing(sourceDir, targetDir, withHistory) {
     const actions = [];
-    const items = withHistory ? [...BASE_ITEMS, ...HISTORY_ITEMS] : [...BASE_ITEMS];
+    const items = withHistory ? [...BASE_ITEMS, ...LOG_ITEMS, ...HISTORY_ITEMS] : [...BASE_ITEMS, ...LOG_ITEMS];
     const managed = new Set(readManifest(targetDir));
     fs.mkdirSync(targetDir, { recursive: true, mode: 0o700 });
     for (const item of items) {
         const src = path.join(sourceDir, item.name);
         const dst = path.join(targetDir, item.name);
-        if (!fs.existsSync(src))
-            continue;
         let st = null;
         try {
             st = fs.lstatSync(dst);
@@ -123,6 +183,12 @@ export function applySharing(sourceDir, targetDir, withHistory) {
         catch {
             /* absent */
         }
+        // The shared prompt history starts empty when the source never had one.
+        if (item.kind === "log" && !fs.existsSync(src) && process.platform !== "win32") {
+            fs.writeFileSync(src, "", { mode: 0o600 });
+        }
+        if (!fs.existsSync(src))
+            continue;
         if (st?.isSymbolicLink()) {
             if (pointsAt(dst, src)) {
                 managed.add(item.name);
@@ -136,14 +202,19 @@ export function applySharing(sourceDir, targetDir, withHistory) {
         }
         else if (st) {
             // A regular file/dir sits where a link would go.
-            if (item.kind === "file" && managed.has(item.name)) {
+            if (item.kind === "log" && st.isFile() && process.platform !== "win32") {
+                actions.push(adoptLog(src, dst, item.name));
+            }
+            else if (item.kind === "file" && managed.has(item.name)) {
                 // We linked it before; it's now a regular file → an in-profile write
                 // forked it. Don't clobber — `share sync` reconciles it.
                 actions.push(`forked ${item.name}: run 'agent-switch share sync' to re-link`);
                 continue;
             }
-            actions.push(`skipped ${item.name}: profile has its own copy (remove it to share)`);
-            continue;
+            else {
+                actions.push(`skipped ${item.name}: profile has its own copy (remove it to share)`);
+                continue;
+            }
         }
         if (item.name === "settings.json") {
             const risk = settingsSharingRisk(src);
@@ -158,7 +229,7 @@ export function applySharing(sourceDir, targetDir, withHistory) {
             actions.push(`linked ${item.name}`);
         }
         catch (err) {
-            if (process.platform === "win32" && item.kind === "file") {
+            if (process.platform === "win32" && item.kind !== "dir") {
                 actions.push(`skipped ${item.name}: Windows file symlinks need Developer Mode or admin ` +
                     `(directories are shared via junction regardless)`);
             }
@@ -199,7 +270,11 @@ export function syncSharing(sourceDir, targetDir) {
         }
         if (st.isSymbolicLink())
             continue; // intact
-        if (st.isFile()) {
+        if (st.isFile() && kind === "log") {
+            actions.push(`${adoptLog(src, dst, name)}, re-linked`);
+            link(src, dst, kind);
+        }
+        else if (st.isFile()) {
             // Forked file: propagate the profile's edit to the source, then re-link.
             if (name === "settings.json") {
                 const risk = settingsSharingRisk(dst);
@@ -244,7 +319,11 @@ export function removeSharing(targetDir) {
             // A symlink (POSIX) or a junction (win32, reported as a symlink by
             // lstat) is ours to remove; a forked regular file is the user's, leave it.
             if (st.isSymbolicLink()) {
+                const shared = ITEM_KIND.get(name) === "log" && fs.existsSync(dst) ? fs.realpathSync(dst) : null;
                 fs.unlinkSync(dst);
+                // Unsharing must not empty a profile's prompt history: it keeps a copy.
+                if (shared)
+                    fs.copyFileSync(shared, dst);
                 actions.push(`unlinked ${name}`);
             }
         }

package/dist/shellenv.js

@@ -13,8 +13,31 @@
  * `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 * as fs from "node:fs";
+import * as path from "node:path";
 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. */
@@ -38,10 +61,58 @@ export function detectShell(requested, env = process.env, platform = process.pla
         return "zsh";
     return "zsh"; // sensible POSIX default when $SHELL is unset
 }
+// The CLI the running app activated (`agent-switch activate` writes its path to
+// <home>/active-cli), so a dev build and an installed app each bring their own;
+// a missing or vanished path falls back to agent-switch on PATH.
+const POSIX_BIN = `__agent_switch_bin() {
+  local p
+  p="$(cat "\${AGENT_SWITCH_HOME:-$HOME/.agent-switch}/active-cli" 2>/dev/null)"
+  if [ -n "$p" ] && [ -x "$p" ]; then printf '%s\\n' "$p"
+  elif command -v agent-switch >/dev/null 2>&1; then printf 'agent-switch\\n'
+  fi
+}
+__agent_switch() {
+  local as
+  as="$(__agent_switch_bin)"
+  command "\${as:-agent-switch}" "$@"
+}`;
+const FISH_BIN = `function __agent_switch_bin
+    set -l home $HOME/.agent-switch
+    set -q AGENT_SWITCH_HOME; and set home $AGENT_SWITCH_HOME
+    if test -r $home/active-cli
+        set -l p (cat $home/active-cli)
+        if test -x "$p"
+            echo $p
+            return
+        end
+    end
+    type -q agent-switch; and echo agent-switch
+end
+function __agent_switch
+    set -l as (__agent_switch_bin)
+    test -n "$as"; or set as agent-switch
+    command $as $argv
+end`;
+const POWERSHELL_BIN = `function __agent_switch_bin {
+    $home_ = if ($env:AGENT_SWITCH_HOME) { $env:AGENT_SWITCH_HOME } else { Join-Path $HOME '.agent-switch' }
+    $p = Get-Content -Path (Join-Path $home_ 'active-cli') -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($p -and (Test-Path $p)) { return $p }
+    if (Get-Command agent-switch -ErrorAction SilentlyContinue) { return 'agent-switch' }
+    return $null
+}
+function __agent_switch {
+    $as = __agent_switch_bin
+    if (-not $as) { $as = 'agent-switch' }
+    if ($as -like '*.js') { & node $as @args } else { & $as @args }
+}`;
 function posixWrapper(binary, envVar, id) {
     return `${binary}() {
-  local dir
-  dir="$(command agent-switch dir --provider ${id} 2>/dev/null)"
+  local dir rc as
+  as="$(__agent_switch_bin)"
+  [ -n "$as" ] || { command ${binary} "$@"; return; }
+  dir="$(command "$as" 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 +122,16 @@ 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)
+    set -l as (__agent_switch_bin)
+    if test -z "$as"
+        command ${binary} $argv
+        return
+    end
+    set -l dir (command $as 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 +143,10 @@ 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)
+    $as = __agent_switch_bin
+    if (-not $as) { & $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
@@ -73,8 +156,8 @@ function powershellWrapper(binary, envVar, id) {
     }
 }`;
 }
-function build(header, wrappers, asw) {
-    return [header, ...wrappers, asw].join("\n");
+function build(header, bin, wrappers, asw) {
+    return [header, bin, ...wrappers, asw].join("\n");
 }
 export function shellenvScript(shell) {
     const providers = allProviders();
@@ -83,34 +166,64 @@ export function shellenvScript(shell) {
         const asw = `# Convenience: "asw" lists all; "asw work" switches claude; "asw codex work" switches a provider
 function asw
     if test (count $argv) -eq 0
-        command agent-switch list
+        __agent_switch list
     else if contains -- $argv[1] claude codex antigravity
-        command agent-switch use $argv[2] --provider $argv[1]
+        __agent_switch use $argv[2] --provider $argv[1]
     else
-        command agent-switch use $argv
+        __agent_switch use $argv
     end
 end`;
-        return build(header, providers.map((p) => fishWrapper(p.binary, p.envVar, p.id)), asw);
+        return build(header, FISH_BIN, providers.map((p) => fishWrapper(p.binary, p.envVar, p.id)), asw);
     }
     if (shell === "powershell") {
         const header = `# agent-switch shell integration — add to $PROFILE:  agent-switch shellenv --shell powershell | Out-String | Invoke-Expression`;
         const asw = `# Convenience: "asw" lists all; "asw work" switches claude; "asw codex work" switches a provider
 function asw {
-    if ($args.Count -eq 0) { command agent-switch list; return }
-    if (@('claude','codex','antigravity') -contains $args[0]) { & agent-switch use $args[1] --provider $args[0] }
-    else { & agent-switch use @args }
+    if ($args.Count -eq 0) { __agent_switch list; return }
+    if (@('claude','codex','antigravity') -contains $args[0]) { __agent_switch use $args[1] --provider $args[0] }
+    else { __agent_switch use @args }
 }`;
-        return build(header, providers.map((p) => powershellWrapper(p.binary, p.envVar, p.id)), asw);
+        return build(header, POWERSHELL_BIN, providers.map((p) => powershellWrapper(p.binary, p.envVar, p.id)), asw);
     }
     // zsh + bash share the POSIX snippet.
     const header = `# agent-switch shell integration — add to your rc file:  eval "$(agent-switch shellenv)"`;
     const asw = `# Convenience: "asw" lists all; "asw work" switches claude; "asw codex work" switches a provider
 asw() {
-  if [ $# -eq 0 ]; then command agent-switch list; return; fi
+  if [ $# -eq 0 ]; then __agent_switch list; return; fi
   case "$1" in
-    claude|codex|antigravity) command agent-switch use "$2" --provider "$1" ;;
-    *) command agent-switch use "$@" ;;
+    claude|codex|antigravity) __agent_switch use "$2" --provider "$1" ;;
+    *) __agent_switch use "$@" ;;
   esac
 }`;
-    return build(header, providers.map((p) => posixWrapper(p.binary, p.envVar, p.id)), asw);
+    return build(header, POSIX_BIN, providers.map((p) => posixWrapper(p.binary, p.envVar, p.id)), asw);
+}
+/** The line that loads the integration, per shell (same as the docs table). */
+export const SHELLENV_LINE = {
+    zsh: 'eval "$(agent-switch shellenv)"',
+    bash: 'eval "$(agent-switch shellenv)"',
+    fish: "agent-switch shellenv --shell fish | source",
+    powershell: "agent-switch shellenv --shell powershell | Out-String | Invoke-Expression",
+};
+/** The startup file `shellenv install` writes to. macOS opens login shells,
+ *  which read ~/.bash_profile rather than ~/.bashrc. */
+export function rcFileFor(shell, home, platform = process.platform) {
+    if (shell === "zsh")
+        return path.join(home, ".zshrc");
+    if (shell === "bash")
+        return path.join(home, platform === "darwin" ? ".bash_profile" : ".bashrc");
+    if (shell === "fish")
+        return path.join(home, ".config", "fish", "config.fish");
+    return path.join(home, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1");
+}
+/** Append the loader line to the shell's startup file, once. `present` says
+ *  whether any known startup file already loads it (the doctor check). */
+export function installShellIntegration(shell, home, present) {
+    const file = rcFileFor(shell, home);
+    if (present)
+        return { shell, file, alreadyInstalled: true };
+    const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const sep = before === "" || before.endsWith("\n") ? "" : "\n";
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${before}${sep}\n# agent-switch shell integration\n${SHELLENV_LINE[shell]}\n`);
+    return { shell, file, alreadyInstalled: false };
 }

package/dist/single-load.js

@@ -0,0 +1,176 @@
+/**
+ * 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"];
+/** What a state file without a `guard` key meant before 2.2 — kept so an
+ *  upgrade never changes a user's effective guard. */
+export const DEFAULT_GUARD_POLICY = "block";
+/** A fresh install (no state file and no profile yet) starts on `warn`: a second load is
+ *  reported, never refused, so nothing changes how a tool starts. */
+export const FRESH_INSTALL_GUARD_POLICY = "warn";
+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;
+}