@event4u/agent-switch 1.7.0 → 2.1.0

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/token-freshen.js

@@ -0,0 +1,154 @@
+/**
+ * Keep a Claude profile's OAuth access token usable for the read-only usage /
+ * profile endpoints — WITHOUT agent-switch ever touching the credential store.
+ *
+ * The problem: a stored access token lives ~8h, the refresh token ~3 weeks.
+ * agent-switch reads the credential and calls the OAuth endpoints with whatever
+ * access token is in the store. Once that token expires the endpoints 401 and
+ * usage silently freezes on the last cached numbers — for exactly the profiles
+ * the operator is NOT actively using, which is the whole point of the readout.
+ * Starting Claude Code on the profile "fixes" it, because Claude Code refreshes.
+ *
+ * The mechanism: let Claude Code do the refresh. `claude doctor` is a LOCAL
+ * health check — it runs no completion and consumes no quota — but it goes
+ * through Claude Code's auth path, so an expired token is refreshed first,
+ * under Claude Code's own lock, into Claude Code's own store. Verified against
+ * CC 2.1.x (2026-07-25): with `expiresAt` in the past, `claude doctor` rotates
+ * BOTH the access and the refresh token and moves `expiresAt` ~8h out.
+ *
+ * Why not the refresh grant ourselves: that rotation is precisely the hazard the
+ * Phase-4 lock recorded — an out-of-band grant invalidates the refresh token a
+ * live session still holds. Delegating honours that lock instead of reopening
+ * it: agent-switch stays read-only outside `rebind` (ADR-003), and the one
+ * process allowed to rotate the token family is the one that owns it. Full
+ * rationale, evidence, and the rejected alternatives: ADR-004.
+ */
+import { spawnSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { accessTokenOf, readProfileCredential } from "./api.js";
+import { ROOT } from "./profiles.js";
+import { resolveBinary } from "./providers.js";
+/** Treat a token as spent this close to `expiresAt` — mirrors Claude Code's own
+ *  5-minute refresh buffer, so we never race it into a just-expired window. */
+export const EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+/** Minimum gap between two freshen attempts for one profile. A truly dead login
+ *  (refresh token expired / revoked) cannot be healed by retrying, and the GUI
+ *  re-reads usage every few seconds — without this floor a dead profile would
+ *  spawn `claude doctor` on every cycle. */
+export const FRESHEN_COOLDOWN_MS = 10 * 60 * 1000;
+/** How long to let Claude Code's health check run before giving up on it. The
+ *  observed run is a few seconds; this is a stuck-process guard, and it bounds
+ *  how long a daemon poll cycle can stall on one profile. */
+const FRESHEN_TIMEOUT_MS = 30_000;
+/** `expiresAt` (epoch ms) out of a credential blob; null when absent/unparseable. */
+export function tokenExpiresAt(credentials) {
+    if (!credentials)
+        return null;
+    try {
+        const v = JSON.parse(credentials)?.claudeAiOauth?.expiresAt;
+        return typeof v === "number" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is this credential's access token spent (or about to be)? Pure — the testable
+ * core. A credential we cannot read or whose `expiresAt` we cannot parse is NOT
+ * reported as expired: we have no evidence it is, and spawning Claude Code on a
+ * guess is worse than one failed read.
+ */
+export function needsFreshen(credentials, now, bufferMs = EXPIRY_BUFFER_MS) {
+    const exp = tokenExpiresAt(credentials);
+    if (exp === null)
+        return false;
+    return exp - now <= bufferMs;
+}
+/** The attempt-stamp file for a config dir. Keyed by hash so the path stays
+ *  flat and filesystem-safe, and lives in agent-switch's own root — never
+ *  inside Claude Code's config dir. */
+function attemptStampFile(configDir) {
+    const digest = crypto.createHash("sha256").update(configDir.normalize("NFC"), "utf8").digest("hex").slice(0, 12);
+    return path.join(ROOT, "freshen", `${digest}`);
+}
+/** Cooldown state is a FILE, not a module variable: the GUI reads usage by
+ *  spawning a fresh `agent-switch status --json` per profile, so an in-process
+ *  map would reset on every read and defeat the floor entirely. */
+function readLastAttemptFile(configDir) {
+    try {
+        const n = Number(fs.readFileSync(attemptStampFile(configDir), "utf8").trim());
+        return Number.isFinite(n) ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function recordAttemptFile(configDir, at) {
+    const file = attemptStampFile(configDir);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(file, String(at));
+    }
+    catch {
+        /* best-effort: a missing stamp only costs an extra attempt */
+    }
+}
+/**
+ * `claude doctor` against one profile's config dir. stdout/stderr are dropped —
+ * this is a side-effect call, not a readout. Any completed run returns true;
+ * whether the token actually got refreshed is decided by re-reading the store.
+ */
+function runClaudeDoctor(configDir, linkedBinary) {
+    const res = spawnSync(resolveBinary("claude", linkedBinary), ["doctor"], {
+        env: { ...process.env, CLAUDE_CONFIG_DIR: configDir },
+        // Claude Code reads settings from the CWD; run it somewhere neutral so a
+        // project's config can never influence a background health check.
+        cwd: os.tmpdir(),
+        stdio: "ignore",
+        timeout: FRESHEN_TIMEOUT_MS,
+    });
+    if (res.error)
+        return false;
+    return true;
+}
+export function defaultFreshenDeps(linkedBinary = null) {
+    return {
+        now: () => Date.now(),
+        readCredential: readProfileCredential,
+        readLastAttempt: readLastAttemptFile,
+        recordAttempt: recordAttemptFile,
+        runHealthCheck: (configDir) => runClaudeDoctor(configDir, linkedBinary),
+        cooldownMs: FRESHEN_COOLDOWN_MS,
+        bufferMs: EXPIRY_BUFFER_MS,
+    };
+}
+/**
+ * Make sure the store behind `configDir` holds a usable access token, letting
+ * Claude Code refresh it when it does not. Idempotent, cooldown-guarded, and a
+ * no-op when the token is still good.
+ */
+export function freshenToken(configDir, deps = defaultFreshenDeps()) {
+    const creds = deps.readCredential(configDir);
+    if (!needsFreshen(creds, deps.now(), deps.bufferMs))
+        return "not-needed";
+    if (deps.now() - deps.readLastAttempt(configDir) < deps.cooldownMs)
+        return "cooling-down";
+    deps.recordAttempt(configDir, deps.now());
+    if (!deps.runHealthCheck(configDir))
+        return "unavailable";
+    return needsFreshen(deps.readCredential(configDir), deps.now(), deps.bufferMs) ? "still-expired" : "refreshed";
+}
+/**
+ * The access token to call the OAuth endpoints with — freshened first when it
+ * has expired. Returns whatever the store holds afterwards (null when there is
+ * no readable credential at all); a freshen that could not heal the login just
+ * means the caller's read fails as it did before.
+ */
+export function freshAccessToken(configDir, deps = defaultFreshenDeps()) {
+    freshenToken(configDir, deps);
+    const creds = deps.readCredential(configDir);
+    return creds ? accessTokenOf(creds) : null;
+}

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;
+}